Read-only public readback helpers for Agentique resources.
This package helps integrators consume public Agentique resource status from agentique.io when the platform exposes versioned public endpoints. It exposes status, list, detail, download metadata, readback projection, context bundle, selection readback, catalog normalization, and safe byte-download helpers only.
agentique.io remains the source of truth for upload, scan, review, moderation, publication, distribution state, and readback. This package does not publish, edit, delete, moderate, approve, certify, install, extract, open, or execute resources.
Catalog and direct-download helpers are included in the published 0.2.2 package for canonical public catalog envelopes, ticket-backed byte transfer, and agent-native readback projection helpers. The helpers remain read-only or explicit-output only. Download readiness is derived from canonical source-package metadata, not legacy top-level availability alone. Owner-approved disposable byte-transfer evidence is recorded for a public catalog resource, but this evidence does not certify content safety, approve arbitrary resources, or guarantee every public resource is downloadable.
npm install @agentique.io/readbackimport {
createBadgeState,
createReadbackClient,
downloadResourceArtifact,
normalizeAgentNativeReadback,
normalizeDownloadMetadata,
normalizeParserVariantReadback,
normalizeResourceList,
normalizeTrustReadback
} from "@agentique.io/readback";
const client = createReadbackClient();
const catalog = normalizeResourceList(await client.listResources({ limit: 10 }));
const metadata = normalizeDownloadMetadata(await client.getDownloadMetadata("resource-id"));
const readback = await client.getReadback("resource-id");
const trust = normalizeTrustReadback(readback);
const parserVariant = normalizeParserVariantReadback(readback);
const agentNative = normalizeAgentNativeReadback(readback);
const badge = createBadgeState(readback);
console.log(badge.label);
console.log(trust.trustPanel?.state ?? trust.platformState);
console.log(parserVariant.parserEvidence?.parseStatus ?? "unavailable");
console.log(agentNative.resolverResult?.state ?? "unavailable");
console.log(`${catalog.items.length} catalog entries`);
console.log(metadata.availability);The client exposes:
getStatus(resourceId)listResources(params)getResource(resourceId)getDownloadMetadata(resourceId)getReadback(resourceId)getContextBundle(resourceId, params)getSelectionReadback(resourceId, params)
No mutation methods are included. Platform pages remain canonical for user decisions.
The client targets versioned public resource paths under /api/public/v1/resources. Callers must handle unavailable, stale, rate-limited, and blocked states because endpoint availability and publication state are controlled by agentique.io.
Context bundle and selection readback helpers use narrow query allowlists for public selection hints such as intent, audience, limit, and cursor. They do not expose production platform scoring, risk thresholds, quarantine criteria, human-review procedures, moderation disposition logic, or operator response workflows.
Returned payloads are normalized with a defense-in-depth projection pass that removes explicitly private fields while preserving public schema fields such as internalId, storageUsage, deploymentDate, tokenCount, objectType, and storageMode. The platform API remains responsible for the authoritative public projection; client-side normalization is not a privacy boundary.
normalizeTrustReadback() projects public desired-state, scanner-policy, trust-panel, review-eligibility, report-action, and version-history fields into a stable readback summary when those fields are present.
normalizeResourceList() projects public catalog list payloads into stable item and page-info fields. normalizeDownloadMetadata() projects public download metadata into availability, filename, media type, size, digest, and expiry fields while filtering private projection fields. When sourcePackage metadata is present, it is authoritative: DOWNLOADABLE status, POST ticket endpoint, safe filename and content type, positive byte size, and SHA-256 digest are required before availability becomes available. Legacy top-level availability cannot make metadata-only or malformed canonical source-package rows downloadable. Placeholder, source-index, schema-only, review-only, review-guide, demo-only, or example-only public package labels normalize to unavailable.
normalizeParserVariantReadback() projects public parser evidence and platform variant fields into a bounded summary when those fields are present. It reports digest presence instead of raw digests and keeps parser/variant state descriptive. Source-only variant metadata remains preparation evidence and is not treated as platform download readiness.
normalizeAgentNativeReadback() projects public namespace, provenance, install guidance, public-boundary, resolver result, and checkpoint fields into a bounded summary when those fields are present. It reports digest presence instead of raw digests and keeps resolver output non-certifying.
downloadResourceArtifact() can write available artifact bytes to an explicit output path only after normalized download metadata passes the same source-package gate. It enforces HTTPS outside loopback development, POST ticket handoff or safe direct URL handling, manual redirect handling, no-overwrite by default, safe filename/path checks, temp-file cleanup, size limits, and digest verification. It omits raw signed URLs and absolute local output paths from public result/error data. It does not install, extract, open, execute, approve, certify, publish, host, or moderate downloaded content. Treat downloaded bytes as untrusted until separately reviewed.
Badge helpers return explicit states:
publishedparsedpartialunsupportedvariant-availableagent-native-readyagent-native-review-requiredagent-native-private-deniedagent-native-ambiguousreview-requiredrescan-requiredblockedstaleunavailablerate-limited
Parser, variant, and agent-native badge states are public readback summaries. They do not prove runtime compatibility, create platform downloads, provide resolver availability, or replace platform review.
Badge output is a public readback summary, not a safety guarantee.
Published on npm as @agentique.io/readback; registry readback currently records the published package set at 0.2.2. Agent-native readback helpers remain public projection helpers, not resolver availability, platform approval, or safety certification. Badge output is a public readback summary, not a platform approval or safety guarantee.