@axorum/client 0.0.0-stage → 1.1.0

package/dist/client.d.ts

@@ -0,0 +1,645 @@
+/**
+ * The client, and the one request funnel every call goes through.
+ *
+ * @packageDocumentation
+ */
+import { type IdempotencyKey } from "./idempotency.js";
+export { mintedAtWire } from "./idempotency.js";
+import { type Agent, type Authorization } from "./authorize.js";
+import { type RotationReason } from "./failover.js";
+import { type IntentDraft } from "./intent.js";
+import type { Payment } from "./payment.js";
+import { type RetryPolicy } from "./retry.js";
+import type { AgentOutcome, BalanceResponse, DeclaredCurrencies, Envelope, IdempotencyWindow, IntentEnvelope, ObligationsResponse, TransactionRecord, UsageBalanceReport } from "./types.js";
+/**
+ * How many policies {@link AxorumClient.submitPinned} will pin against before giving up.
+ *
+ * A bound, not a retry budget: each attempt pins against the policy the service *just
+ * told us* is in force, so a second failure means the policy moved again in the
+ * microseconds since. Three is generous; a service changing policy faster than that is
+ * not one a client can chase, and looping forever would turn a hot policy rotation into
+ * a self-inflicted denial of service.
+ */
+export declare const MAX_PINS = 3;
+/** How the client is built. */
+export interface AxorumClientOptions {
+    /** The service's root, e.g. `http://127.0.0.1:8080`. The `/api/v1` prefix is added. */
+    baseUrl: string;
+    /**
+     * The API URLs of the deployment's other replicas, tried in order after `baseUrl`.
+     * Each is a bare origin (`https://host:port`); `baseUrl`'s path is used on every one.
+     *
+     * A clustered deployment accepts a write only on its primary, and a follower answers
+     * `421 not_primary`. With every replica named here,
+     * {@link AxorumClient.authorize} moves an attempt that meets a `421`, a connection that
+     * never opens, or an attempt timeout on to the next URL at once, under the same deadline
+     * and the same transaction id. A `503` is sent again to the same URL. The next call
+     * starts at the URL that last answered. A `421`'s `primaryApiAddr` is never dialled: it is a hint that may
+     * be stale. No redirect is followed.
+     *
+     * Reads fail over too under a {@link retry} policy. A {@link AxorumClient.submitIntent}
+     * of the caller's own envelope is sent once, to one URL.
+     *
+     * Left out, `baseUrl` is assumed to reach the primary (a load balancer that routes to
+     * it), and the first client built so in the process warns saying so.
+     *
+     * ```ts
+     * const axorum = new AxorumClient({
+     *   baseUrl: "https://axorum-0.axorum.svc:8443",
+     *   failoverUrls: ["https://axorum-1.axorum.svc:8443", "https://axorum-2.axorum.svc:8443"],
+     * });
+     * ```
+     */
+    failoverUrls?: readonly string[];
+    /**
+     * Called each time a request moves to the next endpoint, with the endpoint it left
+     * (`scheme://host:port`) and why, as the next attempt is sent. Count it on
+     * {@link ROTATIONS_COUNTER}, labelled `reason` with {@link rotationLabel}, to match the
+     * Rust SDK's counter. It must not throw; what it throws is ignored.
+     */
+    onRotation?: (left: string, reason: RotationReason) => void;
+    /**
+     * Called each time a request is re-sent to the same endpoint, with that endpoint, why,
+     * and the number of the attempt about to be sent (`2` for the first re-send), counted
+     * over the call. A client with one URL only ever re-sends in place, so a deployment
+     * answering `421` to it shows up here. Count it on {@link RETRIES_COUNTER}, labelled
+     * `reason` with {@link rotationLabel}, to match the Rust SDK. It never overlaps
+     * {@link onRotation}; what it throws is ignored.
+     */
+    onRetry?: (endpoint: string, reason: RotationReason, attempt: number) => void;
+    /**
+     * The agent's PASETO v4.public capability attestation — the credential its **reads**
+     * are answered against.
+     *
+     * It is the same token the intent envelope carries, so there is nothing new to obtain:
+     * an agent that can submit already holds this. The party-scoped reads present it as
+     * `Authorization: Bearer …`; the service takes the reader's identity from the token's
+     * verified `agent_uri` claim and answers only within the party that URI is bound to.
+     *
+     * Optional, because a client that only submits (or only reads {@link
+     * AxorumClient.activePolicy}, which discloses no party's data) needs none. Omit it and
+     * the party-scoped reads raise {@link MissingAttestationError} locally rather than
+     * earning a `401`.
+     *
+     * This replaced a `bearerToken` option that promised to be "for a deployment that
+     * fronts the plane with a gateway". That is no longer a promise the client can keep:
+     * the `Authorization` slot now belongs to the attestation, and there is only one of it.
+     *
+     * Tokens expire — see {@link AxorumClient.withAttestation} to rotate one without
+     * rebuilding the client.
+     */
+    attestation?: string;
+    /**
+     * The per-request timeout, in milliseconds, each send its own. Defaults to 30 000. Left
+     * out, a plain submission to a clustered service that advertises a longer commit wait
+     * waits that wait plus 1 s instead, so it hears the service's `503 commit_unavailable`
+     * rather than timing out first. Set, it is kept as it is.
+     */
+    timeoutMs?: number;
+    /**
+     * Re-send a read that failed in transit. Off when left out, as in the Rust SDK.
+     *
+     * Covers connection failures, timeouts, and a `429`, `502` or `504` from something in
+     * front of the service (or a `423` with `Retry-After`), honouring `Retry-After`, within
+     * the policy's `deadlineMs` if it sets one; see {@link RetryPolicy}. Only reads are
+     * re-sent: a {@link AxorumClient.submitIntent} of the caller's own envelope is sent
+     * once, since the client cannot know a re-send was meant. {@link DEFAULT_RETRY_POLICY}
+     * is three sends, 100 ms doubling, capped at 5 s. {@link AxorumClient.authorize} does
+     * not use it: it always retries, under its own policy and deadline.
+     */
+    retry?: RetryPolicy;
+    /**
+     * Shortens the time budget of one {@link AxorumClient.authorize} call below
+     * {@link AUTHORIZE_DEADLINE_MS} (15 000), for a caller that must answer sooner. A
+     * payment the shorter budget leaves unanswered is `indeterminate`, as any is. It cannot
+     * be lengthened: `ATTESTATION_MIN_REMAINING_MS` guarantees a token outlasts the
+     * budget, and is sized for 15 s.
+     */
+    authorizeDeadlineMs?: number;
+    /**
+     * Whether {@link AxorumClient.authorize} re-sends a request that went unanswered.
+     * **On by default**, under {@link AUTHORIZE_RETRY_POLICY} until the call's deadline.
+     * Set `false` and each request of the call is sent once, still bounded by
+     * {@link submitAttemptTimeout} and the deadline, and the first unanswered one
+     * ends the call as `indeterminate`: for a caller that runs its own re-drive loop over
+     * the same payment. A stale pin is still re-pinned: that is a new request, not a
+     * re-send.
+     */
+    authorizeRetries?: boolean;
+    /**
+     * The client's diagnostic sink: everything it would say at debug level, one line per
+     * call, as the Rust client says it through `tracing::debug!`. A client and the clients
+     * {@link AxorumClient.withAttestation} derives share it. Unset, nothing is said.
+     *
+     * Its first message says why a submission attempt on {@link AxorumClient.authorize}'s
+     * lane waits {@link SUBMIT_ATTEMPT_FALLBACK_MS} (the service advertises no commit wait,
+     * or reading it failed), once per client and its derived clients.
+     */
+    debug?: (message: string) => void;
+    /**
+     * The `fetch` to use. Defaults to the global one.
+     *
+     * Swap it to add tracing, to route through a proxy agent, or — as this client's own
+     * unit tests do — to answer without a socket.
+     */
+    fetch?: typeof globalThis.fetch;
+}
+/** Per-call options. Every method takes them. */
+export interface RequestOptions {
+    /**
+     * Cancels the request.
+     *
+     * Composed with the client's timeout, so whichever fires first wins. When *yours*
+     * fires, the abort reason is thrown as-is — a cancellation you asked for is not a
+     * failure of the ledger, and is not dressed up as one.
+     */
+    signal?: AbortSignal;
+    /**
+     * The `x-request-id` for this call. A fresh UUID v4 is generated when you leave it
+     * out, so every request is traceable whether or not you thought about it.
+     */
+    requestId?: string;
+}
+/**
+ * A typed client for the Axorum agent plane.
+ *
+ * # Writes carry their credential; so do reads
+ *
+ * An intent authenticates **in the envelope**: the draft names the `agent://` URI and the
+ * PASETO attestation, and the service verifies them before it proposes anything. The
+ * reads used to carry nothing at all, and were answered anyway — so any party's
+ * obligations were enumerable, and any observed transaction id disclosed another tenant's
+ * record.
+ *
+ * They are credentialed now, with the **same token**: the party-scoped reads present the
+ * agent's attestation as `Authorization: Bearer …`, the service takes the reader's
+ * identity from that token's verified `agent_uri` claim, and answers only within the
+ * party it is bound to. There is no second credential to obtain — an agent that can
+ * submit can already read.
+ *
+ * So a client that reads must hold an attestation:
+ *
+ * ```ts
+ * const axorum = new AxorumClient({ baseUrl: "http://127.0.0.1:8080", attestation: paseto });
+ *
+ * const outcome = await axorum.submitPinned(draft);
+ *
+ * // A refusal RESOLVES. Branch on the verdict, never on a status code.
+ * if (outcome.posted) {
+ *   console.log("permitted, and the entries posted");
+ * } else {
+ *   console.log("refused, and the refusal is on the ledger:", outcome.verdict);
+ * }
+ *
+ * // Reads are scoped to the party the attestation is bound to.
+ * const owed = await axorum.obligations();
+ * ```
+ *
+ * A client built **without** one still submits and still reads {@link activePolicy} —
+ * both carry their own credential or need none — but any party-scoped read is a
+ * {@link MissingAttestationError}, raised locally, without a wasted round trip.
+ *
+ * An {@link AxorumError} means the ledger never got to answer at all.
+ */
+export declare class AxorumClient {
+    #private;
+    /**
+     * Builds a client for the service rooted at `baseUrl`.
+     *
+     * @throws {ConfigError} If `baseUrl` is not an absolute `http`/`https` URL, a failover
+     *   URL is not a bare origin of the same scheme or repeats one, the timeout is not a
+     *   positive number, the retry policy is not whole numbers, or the authorize deadline
+     *   is not a whole number of milliseconds from 1 to 15 000.
+     */
+    constructor(options: AxorumClientOptions);
+    /**
+     * The same client, reading as the bearer of a **different** attestation.
+     *
+     * Attestations expire, so an agent that outlives one of its tokens must be able to
+     * re-credential without rebuilding — and this hands the new client the *same* `fetch`,
+     * so whatever connections that `fetch` is keeping alive stay alive. Rotating a token
+     * costs a string, not a reconnect.
+     *
+     * It is also the honest way for one process to act for several agents: each gets its
+     * own view, and no view can see another's data, because the service scopes every read
+     * to the party the presented token names.
+     */
+    withAttestation(attestation: string): AxorumClient;
+    /**
+     * Asks the ledger whether `agent` may make `payment`, in one call.
+     *
+     * Proposes `purchase(amount, payee)` with the payee bound as **text**, debiting the
+     * default chart's spend account and crediting its payable account in the amount's
+     * currency. The policy in force must declare
+     * `action purchase(amount: amount, payee: text)`, and an operator must have opened the
+     * default chart in that currency. A rail governed by the same policy must be set to
+     * `payee_binding = "text"`; one left on `"party"` binds a different type.
+     *
+     * ```ts
+     * import { Agent, AxorumClient, AuthorizeError, payment } from "@axorum/client";
+     *
+     * const axorum = new AxorumClient({ baseUrl: "https://ledger.acme.com" });
+     * const buyer = new Agent("agent://acme.com/agent/buyer_01h455vb4pex5vsknk084sn02q", paseto);
+     * const lunch = payment({ amount: { minor: 1_250n, currency: "USD" }, payee: "api.openai.com" });
+     *
+     * const answer = await axorum.authorize(buyer, lunch);
+     * if (answer.allowed) {
+     *   await pay();
+     * } else {
+     *   console.log(answer.refusal.explanation);
+     * }
+     * ```
+     *
+     * # A refusal resolves
+     *
+     * A payment the policy forbids resolves as `{ allowed: false, refusal }`: it was judged
+     * and recorded, and nothing posted. A rejected promise ({@link AuthorizeError}) means the
+     * ledger never answered.
+     *
+     * # Retries and time
+     *
+     * One call has one budget, {@link AUTHORIZE_DEADLINE_MS} (15 s, or less with
+     * {@link AxorumClientOptions.authorizeDeadlineMs}), counted from the call and shared by
+     * the idempotency window and policy reads, every submission (the first, and each
+     * re-pin), every attempt and every pause. Each submission attempt waits the commit
+     * wait the service advertises plus 1 s ({@link submitAttemptTimeout}), so a clustered
+     * service's own `503 commit_unavailable` is heard rather than cut off, or 6 s
+     * ({@link SUBMIT_ATTEMPT_FALLBACK_MS}) when it advertises none; each read waits 6 s.
+     * Every attempt is also clamped to what is left of the budget. When that clamp cuts a
+     * submission attempt below the commit wait plus 1 s, the service may still be deciding
+     * when the client stops waiting, so a call that ends there is honestly
+     * `indeterminate`. The advertisement is read once per client, from
+     * `GET /api/openapi.json`.
+     * Re-sends follow {@link AUTHORIZE_RETRY_POLICY}: as many as the budget allows, full
+     * jitter floored at 100 ms and capped at 1.6 s, honouring `Retry-After` within the
+     * budget. The client's own `retry` and `timeoutMs` govern its other calls, not this one;
+     * {@link AxorumClientOptions.authorizeRetries} turns re-sending off.
+     *
+     * | Re-sent until the deadline | Not re-sent |
+     * |---|---|
+     * | connection failures and timeouts | refusals (they are answers) |
+     * | `429`, `502`, `503`, `504` (and `423` with `Retry-After`) | `422`, including a missing chart or an unknown payee |
+     * | `421 not_primary`, on the next {@link AxorumClientOptions.failoverUrls} URL | `409 transaction_reused` |
+     * | `409` stale pin: re-pinned to `active`, at most 3 times | `400` / `401` / `403` / `404` / `507` |
+     *
+     * Every send carries the payment's transaction id, so one that did commit replays its
+     * answer instead of paying twice. A connection failure, a timeout or a `421` moves the
+     * next attempt to the next failover URL at once; a `503` is sent again to the same URL,
+     * its body read. Whatever is still unanswered
+     * when the budget runs out (a `421` and a `503` included) is `indeterminate`: re-drive
+     * the same {@link Payment} to learn what happened. A call that proves it wrote nothing
+     * is `not_submitted`. `primaryApiAddr` is a hint, never followed.
+     *
+     * Once an attempt ends without a definite answer (a timeout, or a re-sent status other
+     * than `429`), it may have committed, so a later failure that is not the ledger's own
+     * answer about the transaction id (a `403`, a `401`, a `429` or `502` once retries are
+     * spent) is `indeterminate` too, with cause `earlier_attempt_in_doubt`. A
+     * `409 transaction_reused` and a `422 substrate_rejected` stay what they are.
+     *
+     * # Time
+     *
+     * The attestation is read once per submission (the first, and each re-pin), and its
+     * `exp` bounds that submission too: every send, and every wait between sends
+     * (`Retry-After` included), ends 30 seconds (`ATTESTATION_CLOCK_ALLOWANCE_MS`) before
+     * `exp` when that comes before the call's deadline. No send starts past that point, each
+     * send's timeout is cut to the time left, and a wait that would reach it ends the
+     * re-sends.
+     *
+     * @throws {AuthorizeError} Carrying the transaction id and a `failure` that says what to
+     *   do next.
+     * @throws The caller's own abort reason, as-is, when `options.signal` fires.
+     */
+    authorize(agent: Agent, payment: Payment, options?: {
+        signal?: AbortSignal;
+    }): Promise<Authorization>;
+    activePolicy(options?: RequestOptions): Promise<string | null>;
+    /**
+     * The ledger's currency registry: every declared currency and its minor-unit exponent,
+     * in canonical (sorted) code order.
+     *
+     * Requires an attestation, like every agent-plane read of ledger state, but is not
+     * owner-scoped: any bound agent reads the whole registry. From contract 5.0.0 an intent
+     * in any currency not listed here is refused with `422` and
+     * `cause: "undeclared_currency"`, so this is what to read to learn what the ledger will
+     * take. An empty list means nothing is declared.
+     *
+     * @throws {MissingAttestationError} If this client holds no attestation. Nothing is sent.
+     * @throws {AttestationError} If the service refuses the attestation.
+     * @throws {TransportError} If the service cannot be reached.
+     */
+    currencies(options?: RequestOptions): Promise<DeclaredCurrencies>;
+    /**
+     * How long this service answers a retry of a committed transaction id with the
+     * original outcome: its idempotency window (contract 5.0.0).
+     *
+     * Read from the three response headers on `GET /api/openapi.json`
+     * ({@link IDEMPOTENCY_WINDOW_HEADERS}); the document itself is the frozen contract and
+     * is not parsed. Needs no attestation. `window_seconds` is the window's wall-clock
+     * length (24 hours at least, rounded down), or `null` when the service runs no
+     * heartbeat and its window has no length in seconds. Read it once and hand it to
+     * {@link submitKeyed} or {@link ensureFresh}; it only ever grows.
+     *
+     * ```ts
+     * const window = await client.idempotencyWindow();
+     * window.window_seconds; // 86400n
+     * ```
+     *
+     * @throws {IdempotencyWindowError} If the headers state no window: a service older
+     *   than contract 5.0.0, a writer that could not answer, or a rewritten header.
+     * @throws {UnexpectedResponseError} If the spec fetch does not answer `2xx`.
+     * @throws {TransportError} If the service cannot be reached.
+     */
+    idempotencyWindow(options?: RequestOptions): Promise<IdempotencyWindow>;
+    /**
+     * Submits an envelope under a retry key, refusing the key first if the service's
+     * window no longer covers it.
+     *
+     * Use this for every resubmission you make on your own schedule: a queue that
+     * redelivers, a job that restarts. Within the window a resubmission of the identical
+     * intent answers the original outcome (`replayed: true`); past it, the answer is
+     * undefined and the intent might commit twice, so a stale key is never sent.
+     *
+     * The envelope goes out with the key's `minted_at_ms`, so a contract 5.0.0 service
+     * that runs a heartbeat refuses it too (`409 stale_idempotency_key`, an
+     * {@link ApiError}) once it is older than the window less a 5-minute clock-skew
+     * margin. A caller-chosen id restated with its true mint time passes that check
+     * exactly as a freshly minted one does.
+     *
+     * # Why re-sending is sound
+     *
+     * The service looks a transaction id up before it applies anything. A re-send inside
+     * the idempotency window returns what the first send committed, and one whose content
+     * differs is refused as `409 transaction_reused`, never applied.
+     *
+     * # Retries and time
+     *
+     * It runs on {@link authorize}'s transport: one budget of `authorizeDeadlineMs`
+     * ({@link AUTHORIZE_DEADLINE_MS} by default), shared by the read of the service's
+     * commit wait and every attempt, each bounded by {@link submitAttemptTimeout} of that
+     * wait, moving across the `failoverUrls` on a connection failure, a timeout and `421`,
+     * and sending a `503` again itself, its body read. `authorizeRetries: false` turns
+     * re-sending off here too.
+     *
+     * | Call | Re-sent? | Moves to the next URL? |
+     * |---|---|---|
+     * | {@link submitIntent} | no | no |
+     * | {@link submitPinned} | only to re-pin after a `409` | no |
+     * | `submitKeyed` | yes, until the deadline | yes |
+     *
+     * ```ts
+     * const window = await client.idempotencyWindow();
+     * const key = IdempotencyKey.mint();
+     * const envelope = pinIntent({ ...draft, transaction: key.transaction }, policy);
+     * const outcome = await client.submitKeyed(key, window, envelope);
+     * ```
+     *
+     * @throws {StaleIdempotencyKeyError} If the key is past the window, or the service
+     *   advertises no wall-clock window. Nothing was sent.
+     * @throws {ConfigError} If the envelope's `transaction` is not the key's. Nothing was
+     *   sent.
+     * @throws {TransactionReusedError} If the id committed with different content.
+     * @throws {EndpointsExhaustedError | DeadlineExceededError} When no endpoint answered
+     *   in time. Otherwise as {@link submitIntent}.
+     */
+    submitKeyed(key: IdempotencyKey, window: IdempotencyWindow, envelope: IntentEnvelope, options?: RequestOptions): Promise<AgentOutcome>;
+    /**
+     * Submits an intent envelope and returns the ledger's outcome.
+     *
+     * # A refusal resolves
+     *
+     * If the policy in force forbids the action, this **resolves** with
+     * `{ posted: false, verdict: "ForbiddenRejected", … }` — a `200`. The intent reached
+     * the commit point, was judged, and the refusal was *recorded*. That record is the
+     * product. Branch on `posted`/`verdict`; a rejected promise means the ledger never got
+     * to answer at all.
+     *
+     * Re-submitting the identical intent under a `transaction` id that already committed
+     * replays its stored outcome, marked `replayed: true`, rather than double-posting: the
+     * id is the substrate's idempotency key, which is what makes retrying a submission
+     * safe within the service's window ({@link idempotencyWindow}). Different content
+     * under a committed id is a {@link TransactionReusedError}. A replay also carries
+     * `content_verified`: `true` when the resubmitted content matched the stored intent,
+     * `false` when the service had no stored content to compare with (an id committed
+     * before 1.0.0 whose content hash the old log never recorded, retried inside the
+     * window after the upgrade). A `false` replay posted nothing, but it did not check
+     * your content either. To have the key's age checked before sending, use
+     * {@link submitKeyed}.
+     *
+     * @throws {ConfigError} If the envelope carries no `minted_at_ms` (a non-negative
+     *   `bigint` of milliseconds since the Unix epoch). Nothing was sent.
+     * @throws {StalePolicyError} If the pin did not hold. Use {@link submitPinned} to
+     *   handle that automatically.
+     * @throws {UnknownAgentError | AttestationError} On an identity or authority failure.
+     * @throws {NotPrimaryError} If a follower turned the mutation away. Not followed
+     *   automatically — see the class docs.
+     * @throws {CommitUnavailableError} If a cluster commit could not be confirmed.
+     * @throws {TransportError} If the service cannot be reached.
+     */
+    submitIntent(envelope: IntentEnvelope, options?: RequestOptions): Promise<AgentOutcome>;
+    /**
+     * Fetches the active policy, pins the draft to it, submits — and if the pin did not
+     * hold, re-pins and submits again.
+     *
+     * This is the loop every correct agent writes, so it ships in the client rather than
+     * in each caller. It is the *only* method that recovers automatically, and it is safe
+     * to do so for one specific reason: the `transaction` id is minted **once**, before
+     * the first attempt, and is the substrate's idempotency key. Every retry carries the
+     * same id, so if an earlier attempt in fact landed, the retry replays its stored
+     * outcome. The loop cannot double-post.
+     *
+     * A refusal still resolves (see {@link submitIntent}), and a `421` still rejects:
+     * following a redirect to another replica is the caller's decision, not the client's.
+     *
+     * @throws {NoActivePolicyError} If no policy is in force — there is nothing to pin to.
+     * @throws {StalePolicyError} If the policy kept moving out from under {@link MAX_PINS}
+     *   attempts.
+     */
+    submitPinned(draft: IntentDraft, options?: RequestOptions): Promise<AgentOutcome>;
+    /**
+     * {@link submitPinned}, but starting from a policy you already believe is in force —
+     * and recovering if you are wrong.
+     *
+     * This is the shape a long-running agent actually wants. Reading the active policy
+     * before *every* submission is a round trip spent re-learning something that changes
+     * rarely; an agent can hold the last policy it saw, submit straight against it, and
+     * let the `409` tell it when its belief went stale. The recovery is the same loop
+     * either way, so caching costs nothing in correctness — the service remains the
+     * authority, it is simply consulted only when it disagrees.
+     *
+     * On a `409` it re-pins against the policy **the rejection itself named**, rather than
+     * re-reading the active policy. That is not a shortcut: the rejection is the service's
+     * own statement of what is in force as of the moment it refused — strictly fresher
+     * than anything a follow-up read could return, and one round trip cheaper. Bounded at
+     * {@link MAX_PINS} attempts.
+     *
+     * @param draft - The intent, minus the pin. Its transaction id and mint time are
+     *   settled once, here, before the first attempt, and every re-pin carries both.
+     * @param policyId - The policy you believe is in force.
+     * @throws {StalePolicyError} If the policy kept moving out from under {@link MAX_PINS}
+     *   attempts — the policy is churning faster than a client can chase it, and looping
+     *   on would turn a hot rotation into a denial of service.
+     */
+    submitPinnedFrom(draft: IntentDraft, policyId: string, options?: RequestOptions): Promise<AgentOutcome>;
+    /**
+     * The stored record for a committed transaction — **if your party proposed it**.
+     *
+     * Reading it is the idempotent replay lookup: it tells you what a previously-submitted
+     * `transaction` id did, without resubmitting it. A recorded refusal is here like any
+     * other record, with `posted: false`.
+     *
+     * The record is {@link TransactionRecord | contractually opaque} in this version of
+     * the wire contract.
+     *
+     * # A transaction id is not a capability
+     *
+     * Ids are client-minted, and a counterparty may well know one. Holding an id therefore
+     * grants nothing: a transaction another party proposed answers `404`, *identically* to
+     * an id that never existed. The two are deliberately indistinguishable — a
+     * distinguishable "forbidden" would turn any id into an existence oracle against
+     * another tenant's ledger.
+     *
+     * @throws {MissingAttestationError} If this client holds no attestation.
+     * @throws {ApiError} With code `unknown_transaction` (404) if there is no such
+     *   transaction **or it belongs to another party**.
+     */
+    transaction(txnId: string, options?: RequestOptions): Promise<TransactionRecord>;
+    /**
+     * The **signed receipt** for a transaction your party proposed — an
+     * `axorum.evidence.v0` envelope whose base64 `payload` is the
+     * `axorum.receipt.v0` facts of the applied record (contract 4.1.0).
+     *
+     * Re-minted deterministically from the stored record on every call:
+     * byte-identical across fetches and to the inline `receipt` the original
+     * submission's outcome carried. Verify it **offline** against the key list
+     * published at `GET /api/verification-keys.json` — no credential, no server,
+     * no SDK required (see `spec/schemas/` and `spec/evidence-signing.md`).
+     *
+     * @throws {MissingAttestationError} If this client holds no attestation.
+     * @throws {ApiError} With `unknown_transaction` (404) if there is no such
+     *   transaction, it belongs to another party, **or** its record has been
+     *   archived out of the live tail — deliberately indistinguishable. With
+     *   `signing_not_configured` / `signing_unavailable` (503) when the
+     *   deployment does not sign or its signing service is down (the
+     *   transaction itself is committed and unaffected — retry later).
+     */
+    receipt(txnId: string, options?: RequestOptions): Promise<Envelope>;
+    /**
+     * The open obligations **your party** owes.
+     *
+     * Whose duties these are is decided by the attestation, never by an argument. That is
+     * the whole of the fix: `?actor=` used to *select* the party — through a deterministic,
+     * public hash of a name — so every party's duties were enumerable by anyone who could
+     * guess a name, with no credential at all.
+     *
+     * `actor` is now an assertion the service **checks** rather than obeys. Leave it out and
+     * you are answered for the party your token names. Supply it — a party id (`party_…`) or
+     * a DSL party name — and the service confirms it resolves to that same party, answering
+     * `403` if it does not. It is there so a caller can be explicit about who it believes it
+     * is, and be told when it is wrong; it can no longer be used to ask about somebody else.
+     *
+     * A duty-free party is not an error — it answers with an empty list.
+     *
+     * @throws {MissingAttestationError} If this client holds no attestation.
+     * @throws {ApiError} With `403` if `actor` names a party other than the one your
+     *   attestation is bound to.
+     */
+    obligations(actor?: string, options?: RequestOptions): Promise<ObligationsResponse>;
+    /**
+     * An account's net balance, in minor units.
+     *
+     * The balance is a **`bigint`**: the ledger's minor units are 128-bit integers, and
+     * decoding one as a JavaScript `number` would truncate it silently. See `src/json.ts`.
+     *
+     * # Scope
+     *
+     * Requires an attestation **and is scoped to the account's owning party**: the service
+     * answers only when the attested party is the recorded owner of the account. An account
+     * owned by another party — or one opened with no owner at all — answers exactly like an
+     * account that does not exist (`404 unknown_account`), fail-closed and deliberately
+     * indistinguishable: an account id is never an existence oracle across a tenant boundary.
+     *
+     * @throws {MissingAttestationError} If this client holds no attestation.
+     * @throws {ApiError} With code `unknown_account` (404) if there is no such account *or*
+     *   the attested party does not own it (the caller cannot tell which).
+     */
+    balance(accountId: string, options?: RequestOptions): Promise<BalanceResponse>;
+    /**
+     * A usage balance's three running totals — **if your party owns it**.
+     *
+     * The report carries `consumed`, `metered` and `billed`, the two headrooms derived from
+     * them (`unmetered`, `unbilled`), whether the chain has `reconciled`, and `text` — the
+     * balance narrated in compliance English with exact figures. Prefer `text` when you have
+     * a human to show: it is the service's own sentence, not a rendering you assemble.
+     *
+     * # Every counter is a `bigint`
+     *
+     * More so here than anywhere else on the plane. `consumed` is the top of the chain and
+     * takes **no ceiling** — a busy meter can lawfully outgrow `u64` — so decoding a counter
+     * as a JavaScript `number` would eventually truncate a real figure silently. This client
+     * parses them as `bigint`s; see `src/json.ts`.
+     *
+     * # Scope
+     *
+     * Owner-scoped, and fail-closed. A balance owned by another party, one opened with no
+     * owner at all, and one that was never opened all answer the **same** `404 unknown_usage`
+     * — deliberately indistinguishable, so that a usage id is never an existence oracle
+     * across a tenant boundary. The refusal names no owner and does not disclose whether the
+     * balance exists; surface it as it stands rather than inferring more from it than it says.
+     *
+     * @throws {MissingAttestationError} If this client holds no attestation.
+     * @throws {ApiError} With code `unknown_usage` (404) if there is no such usage balance
+     *   *or* the attested party does not own it (the caller cannot tell which), or
+     *   `invalid_usage_id` (400) if that is not a usage-balance id.
+     */
+    usage(usageId: string, options?: RequestOptions): Promise<UsageBalanceReport>;
+}
+/**
+ * The local checks {@link AxorumClient.submitKeyed} makes before anything is sent: the
+ * envelope carries the key's id, and the window still covers the key.
+ *
+ * @internal Exported for tests.
+ * @throws {ConfigError | StaleIdempotencyKeyError}
+ */
+export declare function checkKeyed(key: IdempotencyKey, window: IdempotencyWindow, envelope: IntentEnvelope, nowMs: number): void;
+/**
+ * Refuses an envelope that carries no mint time, before it is sent: `minted_at_ms` must
+ * be a non-negative `bigint` of milliseconds since the Unix epoch, as the wire type says. The type
+ * requires it; this holds a caller the type cannot reach (plain JavaScript, a cast).
+ * Pure.
+ *
+ * @internal Exported for tests.
+ * @throws {ConfigError}
+ */
+export declare function checkMinted(envelope: IntentEnvelope): void;
+/**
+ * Why a submission attempt waits {@link SUBMIT_ATTEMPT_FALLBACK_MS}: the service
+ * advertises no commit wait (`failure` absent), or reading it failed with `failure`.
+ * Pure. Internal: exported for this package's tests, never from its index.
+ */
+export declare function fallbackNote(failure: unknown): string;
+/** The earlier of two deadlines, either of which may be absent. Pure. */
+export declare function earliest(a: number | undefined, b: number | undefined): number | undefined;
+/**
+ * The retry policy a request is sent under, or `undefined` to send it once. Pure.
+ *
+ * `authorize`'s lane re-sends every request of the call, its `POST /intents` included:
+ * the service answers a resubmitted transaction id with the stored outcome, never
+ * applying it twice (`POST /intents`, crates/axorum-serve/src/routes/agent.rs), so a
+ * re-send to the same endpoint or the next is safe. Off the lane only reads are
+ * re-sent: a caller's own envelope is sent once, to one endpoint.
+ */
+export declare function sendPolicy(method: "GET" | "POST", lane: {
+    readonly retries: boolean;
+} | undefined, retry: RetryPolicy | undefined): RetryPolicy | undefined;
+/** What a client built with one endpoint logs, once per process. */
+export declare const ONE_ENDPOINT_WARNING = "one endpoint configured: an LB routing to the primary is assumed";
+/**
+ * Emits {@link ONE_ENDPOINT_WARNING}, naming `baseUrl`, unless `state` says it already
+ * was. The testable seam of {@link warnOneEndpoint}.
+ */
+export declare function warnOnce(state: {
+    warned: boolean;
+}, emit: (message: string) => void, baseUrl: string): void;
+/** Whether `ms` is a budget `authorizeDeadlineMs` accepts: whole, positive, at most 15 000. Pure. */
+export declare function validAuthorizeDeadline(ms: number): boolean;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}