@tabai/sdk 0.2.0

package/dist/http/client-402.d.ts

@@ -0,0 +1,243 @@
+/**
+ * The HTTP 402 client wrapper (R23.2).
+ *
+ * ## Tab is post-paid, so a 402 is not a demand for prepayment
+ *
+ * This is the one thing to understand about this file. A `402` from a Tab Service
+ * does not mean "pay now and I will then serve you". Work is delivered first and
+ * metered after (R23.3); the charge lands on the Open Tab as an accrual, and the
+ * Agent settles later, asynchronously, on Ethereum, with its own keys, through
+ * the payment-strategy seam. So:
+ *
+ * - the **normal** metered response is a `200` carrying the charge block, and
+ *   this client records the accrual and hands the response straight back;
+ * - a `402` is issued on `LimitExceeded` alone, the Agent has no headroom left
+ *   for that Asset. It is a credit decision, not an invoice;
+ * - on a `402` the client records what the Service says the call requires, sends
+ *   the original request **once** more carrying `Tab-Agent` and
+ *   `Tab-Authorisation`, and stops. Not a retry loop, and not a backoff.
+ *
+ * **Nothing in this file settles.** There is no signer here, no strategy call, no
+ * transaction, and no allowance. A settlement step inside the 402 handler would
+ * be the prepay model Tab exists to replace. Settling is the Agent's decision,
+ * taken through `tab_settle`, not something a transport does on its own.
+ *
+ * ## Why a repeat at all, if the charge already landed
+ *
+ * Two cases, and the repeat serves both. On the ordinary path the first attempt
+ * may have reached a Service that could not identify the Agent, a caller that
+ * built its own headers or a proxy that dropped them, and the repeat carries the
+ * identity headers explicitly. On the `LimitExceeded` path a Settlement may have
+ * landed between the two attempts: `TabSettlement` restores headroom in the
+ * same block it moves the Asset (R15.1), so the second attempt is genuinely a
+ * different question rather than the same one asked louder. Exactly one repeat,
+ * because a second `402` means the
+ * headroom is not coming back within the life of this request, and looping would
+ * only meter the Service's rejection path.
+ *
+ * ## x402, the one exception, and why it is not settlement
+ *
+ * A `402` from a Tab Service that also carries `PAYMENT-REQUIRED` is a credit
+ * refusal with an offer attached: pay for this one call, prepaid, through x402.
+ * When the caller configured an x402 signer, and only then, a `402` that still
+ * stands after the repeat is answered by signing that offer and sending the
+ * request once more with `PAYMENT-SIGNATURE`. That is a prepayment for one
+ * call and touches no tab. It is not a Settlement, it restores no headroom,
+ * and it is off unless a signer was given, because an Agent that would rather
+ * settle than prepay should get the `LIMIT_EXCEEDED` it can act on.
+ *
+ * ## Zero-throw, everywhere
+ *
+ * Every fallible call returns a `Result` (R21.5, design section 13.1). A transport
+ * failure, a response object that is not one, a malformed header, a partial charge
+ * block, an unreplayable request body, a `402` that stands after the repeat: all
+ * of them are `err` values carrying an error category. Nothing here throws,
+ * including the consumer's own `onCharge` callback, which is called inside a guard
+ * so a consumer's bug cannot fail a request that succeeded.
+ *
+ * Requirements: 23.2, 21.5
+ */
+import { type Address, type Bytes32, type Result } from "../_shared/index.js";
+import { type Logger } from "../logger.js";
+import { type ChargedAsset, type HeaderReader, type HeaderRecord } from "./headers.js";
+import { type X402PaymentReceipt, type X402SignerSource } from "../x402/client.js";
+/**
+ * What the caller may put on a request.
+ *
+ * A near-mirror of the standard `RequestInit` rather than an import of it, because
+ * `@tabai/sdk` compiles against the ES2023 library alone and must not acquire a DOM
+ * or `undici` type dependency to describe a request. The index signature carries
+ * every option this client does not read, `signal`, `redirect`, `cache`,
+ * `keepalive`, a dispatcher, through to the host `fetch` untouched.
+ */
+export interface Tab402RequestInit {
+    readonly method?: string;
+    /** A plain object, a `Headers`, or an array of pairs. Merged with the Tab headers. */
+    readonly headers?: HeaderReader | HeaderRecord | readonly (readonly [string, string])[];
+    readonly body?: unknown;
+    readonly [option: string]: unknown;
+}
+/** The request this client hands to its `fetch`: the caller's options, with headers resolved. */
+export interface Tab402FetchInit {
+    readonly headers: Readonly<Record<string, string>>;
+    readonly [option: string]: unknown;
+}
+/**
+ * The little of a response this client reads.
+ *
+ * Structural for the same reason as {@link Tab402RequestInit}, and loose on
+ * purpose: `body` and `bodyUsed` are `unknown` and duck-checked at runtime, so a
+ * real `Response` from any host satisfies this without the two type worlds having
+ * to agree. Widen it through the type parameter of {@link createTab402Client} when
+ * the caller supplies a typed `fetch`, and `client.fetch` then returns
+ * `Result<Response>` with every method of the real thing intact.
+ */
+export interface Tab402Response {
+    readonly status: number;
+    readonly headers: HeaderReader | HeaderRecord;
+    readonly body?: unknown;
+    readonly bodyUsed?: unknown;
+}
+/** The `fetch` this client calls. The host's global `fetch` is the default. */
+export type Tab402Fetch<Res extends Tab402Response> = (url: string, init: Tab402FetchInit) => Promise<Res>;
+/** Whether the charge the Service reported landed on the Open Tab. */
+export type ChargeOutcome = 
+/** The call was served and metered. The Open Tab now carries this amount. */
+"accrued"
+/**
+ * `LimitExceeded`: the amount is what the call *requires* and it did not land,
+ * because the Agent's headroom for the Asset does not cover it.
+ */
+ | "declined";
+/** One charge block, read off one response, in the client's own terms. */
+export interface ChargeAccrued {
+    /** The Agent this call was metered against. */
+    readonly agent: Address;
+    /** The absolute URL that was called. */
+    readonly url: string;
+    /** The HTTP status the charge block arrived on. */
+    readonly status: number;
+    readonly outcome: ChargeOutcome;
+    /** Integer Asset base units: charged on `accrued`, required on `declined`. */
+    readonly amount: bigint;
+    readonly asset: ChargedAsset;
+    readonly serviceId: Bytes32;
+    readonly tool: Bytes32;
+    /** The Open Tab the Service reported after this call. */
+    readonly openTab: bigint;
+    /** The headroom the Service reported for this Agent and Asset. */
+    readonly headroom: bigint;
+    readonly authorisation?: Bytes32;
+    /**
+     * The strategy the Agent intends to settle this Asset through, if the client was
+     * given one. Carried for the later, separate settlement path and used by nothing
+     * here.
+     */
+    readonly strategyId?: string;
+    /** `1` for the original request, `2` for the repeat. */
+    readonly attempt: 1 | 2;
+    /** Milliseconds since the epoch, when the header was read. */
+    readonly observedAt: number;
+}
+/** What this client believes about one Asset's tab, from headers alone. */
+export interface TabSnapshot {
+    readonly asset: ChargedAsset;
+    /** The Open Tab most recently reported for this Asset. */
+    readonly openTab: bigint;
+    /** The headroom most recently reported for this Asset. */
+    readonly headroom: bigint;
+    /** Sum of every charge that landed, across the client's lifetime. */
+    readonly accrued: bigint;
+    /** Sum of every charge refused for want of headroom. Never part of {@link accrued}. */
+    readonly declined: bigint;
+    readonly accruedCount: number;
+    readonly declinedCount: number;
+    readonly observedAt: number;
+}
+export interface Tab402ClientOptions<Res extends Tab402Response = Tab402Response> {
+    /** Absolute base URL. A relative path handed to `fetch` resolves against it. */
+    readonly baseUrl: string;
+    /** The Agent's Monad address, sent as `Tab-Agent`. */
+    readonly agent: Address;
+    /** The authKey to meter against, sent as `Tab-Authorisation` when supplied. */
+    readonly authorisation?: Bytes32;
+    /** Called for every charge block read, on the 200 path and the 402 path alike. */
+    readonly onCharge?: (charge: ChargeAccrued) => void;
+    /**
+     * `1` repeats the original request once after a `402`; `0` repeats nothing.
+     *
+     * Typed as the two values it can hold rather than as a `number`, because "repeat
+     * once" is the semantics rather than a default: a caller who wrote `5` would be
+     * asking for a retry loop against a credit decision, and a number that silently
+     * clamped to `1` would leave them believing they had one.
+     */
+    readonly maxRetries?: 0 | 1;
+    /** Recorded on each accrual for the later settlement path. Never used to settle here. */
+    readonly strategyId?: string;
+    /**
+     * The prepaid fallback. With a signer here, a `402` that still stands after
+     * the repeat and carries `PAYMENT-REQUIRED` is paid through x402 and the
+     * request sent once more. Without one, that `402` is the `LIMIT_EXCEEDED`
+     * it always was. See the module note.
+     */
+    readonly x402?: Tab402X402Options;
+    /** Defaults to the host's global `fetch`. */
+    readonly fetchImpl?: Tab402Fetch<Res>;
+    readonly logger?: Logger;
+    /** Injectable clock, so `observedAt` is testable. Defaults to `Date.now`. */
+    readonly now?: () => number;
+    /**
+     * How many accruals {@link Tab402Client.charges} keeps. Defaults to 128.
+     *
+     * Trimming the list never touches the totals in {@link TabSnapshot}, which are
+     * running sums, so a long-lived client keeps exact accounting on bounded memory.
+     */
+    readonly maxChargeHistory?: number;
+}
+/** How the client pays when it pays. */
+export interface Tab402X402Options {
+    /**
+     * The signer, or a factory called only when an offer is about to be taken. A
+     * factory returning `undefined` declines, and the `402` stands as the credit
+     * decision it was.
+     */
+    readonly signer: X402SignerSource;
+    /** Sign only on this chain. Defaults to any `eip155:*` the Service offers. */
+    readonly chainId?: bigint;
+    /** Sign only for this token. Defaults to any the Service offers. */
+    readonly asset?: Address;
+    /** Refuse an offer above this many atomic units. Omitted sets no ceiling. */
+    readonly maxAmount?: bigint;
+    readonly onPayment?: (receipt: X402PaymentReceipt) => void;
+}
+export interface Tab402Client<Res extends Tab402Response = Tab402Response> {
+    /**
+     * Sends a request, records whatever charge the response reports, and repeats
+     * once on a `402`.
+     *
+     * `input` may be absolute or relative to `baseUrl`. Returns the response the
+     * Service produced, this client never rewrites a status, so a `500` from the
+     * Service comes back as `ok(response)` for the caller to read. The `err` cases
+     * are this client's own: a bad URL, a malformed charge block, a transport
+     * failure, or a `402` that still stands after the repeat.
+     */
+    fetch(input: string, init?: Tab402RequestInit): Promise<Result<Res>>;
+    /** Every charge block read, oldest first, up to `maxChargeHistory`. */
+    charges(): readonly ChargeAccrued[];
+    /** One snapshot per Asset seen, in first-seen order. */
+    tabs(): readonly TabSnapshot[];
+    tabOf(asset: ChargedAsset): TabSnapshot | undefined;
+    /** Every x402 payment made, oldest first. Empty unless `x402` was configured. */
+    payments(): readonly X402PaymentReceipt[];
+}
+/**
+ * Builds the client.
+ *
+ * Construction is total: it cannot fail and returns a client, not a `Result`.
+ * Every fallible thing, an unusable `baseUrl`, an `agent` that is not an
+ * address, a host with no `fetch`, is reported by the call that needs it, which
+ * is the only place a caller can act on it. This matches
+ * `createEthereumUsdcStrategy` and keeps the SDK's two factories the same shape.
+ */
+export declare function createTab402Client<Res extends Tab402Response = Tab402Response>(options: Tab402ClientOptions<Res>): Tab402Client<Res>;
+//# sourceMappingURL=client-402.d.ts.map

package/dist/http/client-402.d.ts.map

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