@fora-protocol/sdk 1.0.3

package/sdk/ts/client/errors.js

@@ -0,0 +1,148 @@
+// The client's typed failure — TS port of sdk/go/connect/callerror.go.
+//
+// A refusal and a failure are different things, and a caller handles the situations
+// differently. It cannot tell them apart from a message, so the class is carried as a
+// value.
+//
+// The one worth naming is: WE refused to send. The routing checks that precede a call to
+// an offer-derived address can decline before anything leaves the process, and folding
+// that into "unreachable" — as a network timeout — hides the difference between "the
+// network is bad" and "the address failed a security check". They call for opposite
+// responses.
+/**
+ * ForaCallError is the client's typed failure. Every verb throws this and nothing else,
+ * so `instanceof ForaCallError` is not a coin flip on the very type callers are told to
+ * branch on — which is what happens when a method yields a typed error where it declines
+ * to send and a bare transport error where the peer refuses.
+ */
+export class ForaCallError extends Error {
+    kind;
+    op;
+    status;
+    reason;
+    detail;
+    /** The peer's own developer message, taken from its typed reason. Empty when the
+     * answer carried none.
+     *
+     * A field rather than something to recover from `message`'s rendering, because a
+     * reason rendered into prose cannot be read back out without parsing it. It sits
+     * BESIDE `reason` rather than in it: `reason` is the peer's machine token.
+     *
+     * NON-AUTHORITATIVE and UNBOUNDED — the contract says both of the field it comes
+     * from. Branch on `kind` or on the typed reason, never on this text, and bound it
+     * before rendering it to a log line or an agent. */
+    peerMessage;
+    constructor(init) {
+        super(renderCallError(init), init.cause !== undefined ? { cause: init.cause } : undefined);
+        this.name = "ForaCallError";
+        this.kind = init.kind;
+        this.op = init.op;
+        this.status = init.status;
+        this.reason = init.reason;
+        this.detail = init.detail;
+        // Taken ONLY from what the decode site passed, never derived from `detail`
+        // here. A detail is not always the peer's: the content leg SYNTHESIZES one
+        // from the edge's refusal token, and its message is this SDK's own sentence
+        // with the token quoted into it. Deriving from the field would put the SDK's
+        // words in the field that claims to hold a remote party's, which is the one
+        // thing this field exists not to do.
+        this.peerMessage = init.peerMessage ?? "";
+    }
+    /**
+     * The most specific machine-readable reason available: the peer's own token when it
+     * sent one, otherwise the failure class.
+     */
+    reasonOf() {
+        return this.reason !== undefined && this.reason !== ""
+            ? this.reason
+            : this.kind;
+    }
+}
+// renderCallError mirrors the Go failure renderer's shape (package, op, class, status,
+// reason, cause) so a log line reads the same whichever SDK produced it.
+function renderCallError(init) {
+    const parts = [`fora/client: ${init.op}: ${init.kind}`];
+    if (init.status !== undefined && init.status !== 0) {
+        parts.push(`status ${init.status}`);
+    }
+    if (init.reason !== undefined && init.reason !== "") {
+        parts.push(`reason ${init.reason}`);
+    }
+    if (init.cause !== undefined) {
+        parts.push(String(init.cause instanceof Error ? init.cause.message : init.cause));
+    }
+    return parts.join(": ");
+}
+/** The refusal for an address that failed a routing check. Its own constructor because
+ * every such refusal must state which check declined and must never carry a status:
+ * nothing was sent, so there is nothing to report a status for. */
+export function notSent(op, cause) {
+    return new ForaCallError({ kind: "not_sent", op, cause });
+}
+/** The refusal for a request that could not be assembled, or an answer that could not be
+ * read as the protocol defines it. */
+export function malformed(op, cause) {
+    return new ForaCallError({ kind: "malformed", op, cause });
+}
+/**
+ * The Connect code a peer answered with, mapped onto the failure class.
+ *
+ * A peer that answered is a refusal, whatever it said: the distinction a caller needs is
+ * "it said no" versus "it never answered", and only the first is worth surfacing a reason
+ * for. Three codes land on the second side. `unavailable` is the transport failure
+ * proper; `deadline_exceeded` and `canceled` are LOCAL outcomes wearing a Connect code,
+ * so neither means the peer reached a verdict — classifying a caller's own cancellation
+ * as a refusal would tell it the Exchange declined a call the Exchange may never have
+ * seen. `resource_exhausted` is the read cap seen from this side: the peer's answer was
+ * larger than the client agreed to read.
+ */
+/**
+ * The Connect code a status implies when the body is not an envelope that names one.
+ *
+ * connect-go derives the code from the HTTP STATUS in exactly two cases: a body it cannot
+ * read as an envelope, and an envelope carrying no code. Both are what a deployment's own
+ * infrastructure produces — a gateway draining, a proxy answering with its own HTML page —
+ * and the difference between "the Exchange declined this" and "nothing answered" is the
+ * whole reason the failure classes exist. Anything not listed is `unknown`, which reads as
+ * a refusal.
+ *
+ * Not a rule invented here: it is connect-go's own table (protocol.go, httpToCode), and
+ * the transport-failure corpus is captured from a real client so a future change to it is
+ * reported rather than mirrored by hand.
+ */
+const STATUS_CODES = {
+    // A 3xx reached this client only because the send refused to follow it, and every leg
+    // refuses. That is a server that did not answer the call, not one that declined it —
+    // which is what all three failure taxonomies say a redirect is. connect-go maps these
+    // to CodeUnknown, but it never sees one: its transport follows redirects, so the row is
+    // unreachable there rather than decided.
+    301: "unavailable",
+    302: "unavailable",
+    303: "unavailable",
+    307: "unavailable",
+    308: "unavailable",
+    400: "internal",
+    401: "unauthenticated",
+    403: "permission_denied",
+    404: "unimplemented",
+    429: "unavailable",
+    502: "unavailable",
+    503: "unavailable",
+    504: "unavailable",
+};
+/** The Connect code a non-envelope answer carries, derived from its status. */
+export function connectCodeFromStatus(status) {
+    return STATUS_CODES[status] ?? "unknown";
+}
+export function kindOfConnectCode(code) {
+    switch (code) {
+        case "unavailable":
+        case "deadline_exceeded":
+        case "canceled":
+            return "unreachable";
+        case "resource_exhausted":
+            return "too_large";
+        default:
+            return "refused";
+    }
+}

package/sdk/ts/client/index.d.ts

@@ -0,0 +1,241 @@
+import { type DiscoveryResult, type Mode, type VerifiedOffer } from "../core/verifier.ts";
+import type { z } from "zod";
+import { type Window } from "../core/window.ts";
+import { DisputeResponseSchema, GetAccountStatusResponseSchema, PushResourcesResponseSchema, RefreshCatalogResponseSchema, RegisterResponseSchema, RemoveResourcesResponseSchema, TransactionResponseSchema, UsageReportResponseSchema } from "../../../gen/ts/wire/schemas.ts";
+import { type Content } from "./content.ts";
+import { type RegistrationRequirements } from "../resolvers/index.ts";
+import type { EndpointResolver } from "./route.ts";
+import { type UnarySend, type Validation } from "./transport.ts";
+/** How long a delivery-fetch proof stays valid, in seconds.
+ *
+ * Short on purpose, and deliberately NOT the signed URL's own expiry, which can be hours:
+ * the proof covers only the method and the URL, so for as long as the window is open
+ * anyone who observes the request can repeat it. */
+export declare const DEFAULT_PROOF_WINDOW_SEC = 30;
+/** Reports what one Exchange asks of a registration.
+ *
+ * An interface for the same two reasons the endpoint seam is one: a test can drive a
+ * registration without standing up a manifest server, and this module has no way to
+ * accept a terms digest or a schema from configuration — the only way to skip the read
+ * is to set `terms_digest` on the request, where the signature covers it.
+ *
+ * An implementation MUST NOT serve the answer from a cache. The contract requires a
+ * registering client to read the digest from a freshly fetched manifest, so a cached one
+ * breaks the rule the field exists to record.
+ *
+ * An implementation's FAILURE decides how a caller is told to react, so it is part of the
+ * contract rather than an implementation detail. A failure that is a VERDICT — the domain
+ * is unusable, the deployment excludes it, the document served is not an Exchange's, or it
+ * is one this reader cannot use — MUST throw the resolver tier's ExchangeNotPermitted,
+ * ManifestNotExchange or ManifestUnusable, or the invalid-host error raised for a
+ * value that is not a bare domain;
+ * those surface as `not_sent`, which tells the caller not to retry. Anything else is read
+ * as a transport failure and reported as `unreachable`, i.e. worth retrying. An
+ * implementation that throws a bare error for a refusal therefore has its final answer
+ * retried indefinitely.
+ *
+ * ManifestUnusable is the seam's word for "the document arrived and cannot be read for
+ * what a registration owes". The SDK's own reader reaches it for a document version it
+ * cannot classify, and treats its other two disappointments as absence or as a transport
+ * failure. An implementation STRICTER than that one — validating the whole document, or
+ * applying a narrower version rule — reaches for the same word, and would otherwise hold
+ * a final answer this seam reported as transient.
+ *
+ * Note which class that is NOT. ManifestVersionRefused belongs to the endpoint seam and
+ * is absent from the list above on purpose: the two vocabularies are disjoint, one
+ * answering whether an endpoint may be dialled and this one whether a document can be
+ * read. An implementation that throws the endpoint class for a version refusal here has
+ * its verdict read as a transport failure. */
+export interface RegistrationRequirementsReader {
+    resolveRegistrationRequirements(exchange: string): Promise<RegistrationRequirements>;
+}
+/** Everything a client is built from. Every field is injected; the client owns none of it. */
+export interface ClientOptions {
+    /** The RFC 9421 request signer. Custody stays with the application — the SDK receives
+     * a non-extractable CryptoKey and the keyid it signs under, never key bytes. */
+    signer?: {
+        privKey: CryptoKey;
+        keyid: string;
+    };
+    /** The PUBLIC half of the key `signer` signs with. A bound delivery fetch presents it
+     * in a header and derives the agent identity from it, and a non-extractable CryptoKey
+     * cannot yield it — custody keeps the private half, so the public half is supplied
+     * alongside. Without it the client can buy but cannot fetch what it bought.
+     *
+     * There is deliberately no option for a separate agent PRIVATE key. The protocol
+     * carries one agent identity: agent_identity_hash is the thumbprint of the agent's
+     * request-signing key, an Exchange verifies the detached acceptance against the key
+     * registered for the caller its request signature identified, and the delivery URL is
+     * bound to that same thumbprint. A second key would be refused at execute, and any URL
+     * it did produce could never be fetched. */
+    agentPublicKey?: CryptoKey;
+    /** The agent's own identity, forwarded on discovery and required on a purchase: both
+     * reference services resolve the calling agent from it and refuse a request naming
+     * none. */
+    requester?: Record<string, unknown>;
+    /** Offer-verification strictness. Defaults to "strict" — fail-closed. */
+    verification?: Mode;
+    /** Whether an outbound request is checked against its generated schema first.
+     * Defaults to "strict", which is deliberately stricter than Go — see the Validation
+     * type for why. Orthogonal to `verification`: this one is about the message going
+     * out, that one about the offers coming back. */
+    validation?: Validation;
+    /** Resolves an exchange identity to its raw 32-byte Ed25519 offer-signing key.
+     * Injected: the client owns no key state. */
+    resolveOfferKey?: (exchange: string) => Promise<Uint8Array<ArrayBuffer> | undefined>;
+    /** Turns an offer's exchange domain into that Exchange's own advertised origin. Never
+     * configuration — a usage report and a dispute go where the signed offer says. */
+    endpointResolver?: EndpointResolver;
+    /** Reports what one Exchange asks of a registration — the terms revision submitting
+     * one accepts, and the schema its registration_data must match. Defaults to the
+     * well-known reader over the SSRF-guarded transport, built once with this client:
+     * the domain comes off the request rather than from configuration, so it is the
+     * request-derived provenance that takes the guarded default.
+     *
+     * The reader it takes holds no document cache, and that is the point rather than an
+     * implementation detail: the contract requires a registering client to read the terms
+     * digest from a FRESHLY fetched manifest, so an implementation serving it from a
+     * cache breaks the rule the field exists to record. There is deliberately no option
+     * to supply a digest or a schema directly — a caller managing its own requirements
+     * sets `terms_digest` on the request, which suppresses the read and says so on the
+     * message the signature covers. */
+    registrationRequirements?: RegistrationRequirementsReader;
+    /** The WBA directory origin this client signs as. */
+    signatureAgent?: string;
+    /** The RFC 9421 freshness window stamped on every outbound call. */
+    signWindow?: Window;
+    /** The freshness window stamped on a delivery-fetch proof. */
+    proofWindow?: Window;
+    /** Mints the X-Request-ID correlation value. Absent sends no header. */
+    requestId?: () => string;
+    /** The dialing seam for the configured (home Exchange / Broker) leg. */
+    send?: UnarySend;
+    /** The dialing seam for the OFFER-DERIVED leg. Defaults to the SSRF-guarded send,
+     * because the caller names a domain, the manifest it serves names an endpoint, and a
+     * signed call then goes there. */
+    guardedSend?: UnarySend;
+    maxRPCReadBytes?: number;
+    callTimeoutMs?: number;
+    contentTimeoutMs?: number;
+    maxContentBytes?: number;
+    /** The clock the offer Verifier reads, in epoch milliseconds. */
+    now?: () => number;
+}
+/** Tunes a single state-mutating call. */
+export interface CallOptions {
+    /**
+     * Pins the idempotency key for this call. Reusing a key makes the call a deliberate
+     * replay: the server dedupes on it (a fresh key is minted per call by default). The
+     * SDK never tracks keys — the server owns dedup.
+     *
+     * Hold the key and pass the same one back when retrying, on every verb that takes
+     * this option. The key identifies the ACTION, not the attempt: a fresh key on a retry
+     * reads to the server as a second purchase, a second report, a second dispute.
+     */
+    idempotencyKey?: string;
+}
+/**
+ * The response types, inferred from the generated schemas rather than restated.
+ *
+ * A verb returning `Record<string, unknown>` hands a caller no help exactly where it is
+ * needed: `transaction_id`, `report_id` and the retrieval endpoint are the links of the
+ * dispute chain, and every read of one was an unchecked index. Python's verbs return the
+ * generated models, so the two faces were the same verb names over materially different
+ * ergonomics.
+ */
+export type TransactionResponse = z.infer<typeof TransactionResponseSchema>;
+/** The answer to a usage report; carries the `report_id` a dispute is filed against. */
+export type UsageReportResponse = z.infer<typeof UsageReportResponseSchema>;
+/** The answer to a dispute. */
+export type DisputeResponse = z.infer<typeof DisputeResponseSchema>;
+/** The agent-facing Exchange client. */
+export interface Client {
+    discover(query: Record<string, unknown>): Promise<DiscoveryResult>;
+    execute(offer: VerifiedOffer, opts?: CallOptions): Promise<TransactionResponse>;
+    reportUsage(report: Record<string, unknown>, opts?: CallOptions): Promise<UsageReportResponse>;
+    dispute(request: Record<string, unknown>, opts?: CallOptions): Promise<DisputeResponse>;
+    /** Create this agent's account at the Exchange the request names. Takes no
+     * CallOptions: the message carries no idempotency key, because registering again
+     * returns the same account handle. */
+    register(request: Record<string, unknown>): Promise<RegisterResponse>;
+    /** Read whether this agent's account at the named Exchange is active. An empty
+     * `billing_ref` is a NORMAL answer — no account there yet. */
+    getAccountStatus(request: Record<string, unknown>): Promise<GetAccountStatusResponse>;
+    fetch(signedURL: string): Promise<Content>;
+}
+/** The Broker client. */
+export interface BrokerClient {
+    resolve(request: Record<string, unknown>): Promise<DiscoveryResult>;
+}
+/**
+ * createClient builds a client against baseURL — the agent's HOME Exchange, the one its
+ * account lives on.
+ *
+ * Discovery and purchase go to baseURL. A usage report or a dispute does NOT: those reach
+ * the Exchange that ISSUED the offer, resolved per call from that Exchange's own
+ * manifest, over a separately guarded transport.
+ */
+export declare function createClient(baseURL: string, options?: ClientOptions): Client;
+/**
+ * createBrokerClient builds a client against a Broker's base URL.
+ *
+ * A SEPARATE constructor rather than a second surface on the exchange client because the
+ * two speak to different parties. A Broker is not an Exchange: it fans a query out across
+ * Exchanges it knows and relays back what they offered, so its address is the Broker's,
+ * not any Exchange's. Hanging both off one base URL would mean one of the two was always
+ * pointed at the wrong party.
+ *
+ * It takes the same options, but only the ones a discovery call has any use for do
+ * anything, and two need care. A single pinned offer key is the wrong shape here: Broker
+ * fan-out returns offers minted by different Exchanges, so inject a resolver that
+ * resolves each issuing Exchange's own key. And `requester` is REQUIRED, not optional: a
+ * Broker resolves the calling agent from it and declines a request naming none, so
+ * resolve refuses locally rather than spending a round trip to be told.
+ */
+export declare function createBrokerClient(baseURL: string, options?: ClientOptions): BrokerClient;
+/** The answer to a registration: the account handle this Exchange minted, and the terms
+ * revision it recorded against it. */
+export type RegisterResponse = z.infer<typeof RegisterResponseSchema>;
+/** The answer to an account-status read. An empty account handle is a NORMAL answer: it
+ * means this agent holds no account at that Exchange yet. */
+export type GetAccountStatusResponse = z.infer<typeof GetAccountStatusResponseSchema>;
+/** The answer to a catalog push: accepted/rejected counts and the warnings the accepted terms carry. */
+export type PushResourcesResponse = z.infer<typeof PushResourcesResponseSchema>;
+/** The answer to a catalog removal. */
+export type RemoveResourcesResponse = z.infer<typeof RemoveResourcesResponseSchema>;
+/** The answer to a catalog refresh request. */
+export type RefreshCatalogResponse = z.infer<typeof RefreshCatalogResponseSchema>;
+/** The publisher-facing Catalog client. */
+export interface CatalogClient {
+    pushResources(request: Record<string, unknown>): Promise<PushResourcesResponse>;
+    removeResources(request: Record<string, unknown>): Promise<RemoveResourcesResponse>;
+    refreshCatalog(request: Record<string, unknown>): Promise<RefreshCatalogResponse>;
+}
+/**
+ * createCatalogClient builds a client against an Exchange's CATALOG endpoint — the
+ * publisher role's face: push, remove and refresh the catalog entries a publisher, or a
+ * contributor it authorised, supplies.
+ *
+ * A SEPARATE constructor, as the Broker's is, and for a related reason: the address is a
+ * different one. An Exchange advertises CatalogService at its manifest's
+ * `catalog_endpoint`, distinct from the ExchangeService endpoint the agent client dials,
+ * and the caller is a different party holding a different key — a contributor's, named
+ * by `caller_id`, never an agent's. Hanging the catalog verbs on the agent client would
+ * carry every agent-only holder into a client that uses none of them, and point one of
+ * the two roles at the wrong address.
+ *
+ * The publisher chose the Exchange, so the origin is configuration and the leg runs on
+ * the plain send — the posture of the agent client's home Exchange, not of its
+ * offer-derived leg. It takes the same options; `signer` is what a real push needs (an
+ * Exchange refuses an unsigned catalog call), and the agent-only ones — the requester,
+ * the agent key, the offer-key resolver, the endpoint resolver, the guarded send — are
+ * inert here rather than errors, so one option set can build every face.
+ */
+export declare function createCatalogClient(baseURL: string, options?: ClientOptions): CatalogClient;
+export { ForaCallError } from "./errors.ts";
+export type { CallErrorKind } from "./errors.ts";
+export type { Content } from "./content.ts";
+export type { EndpointResolver } from "./route.ts";
+export type { UnaryRequest, UnaryResponse, UnarySend, Validation } from "./transport.ts";
+export { DEFAULT_CALL_TIMEOUT_MS, DEFAULT_MAX_RPC_READ_BYTES, NOT_CANONICAL_WIRE_NAMING, } from "./transport.ts";
+export { DEFAULT_CONTENT_TIMEOUT_MS, DEFAULT_MAX_CONTENT_BYTES, } from "./content.ts";