@metalntwx/metal-pay 0.2.0 → 0.3.1

package/dist/clearing-client.d.ts

@@ -1,168 +1,105 @@
-import type { PaymentPayloadResult, PaymentRequirements, SchemeClientHooks, SchemeNetworkClient } from "@x402/core/types";
-import { type Address, type Hex, type LocalAccount } from "viem";
-/** What signs: a viem local account, or anything with an address and
- * EIP-712 `signTypedData`. */
+import { type Hex } from "viem";
+import { type ClearingInvoice, type ClearingReceipt } from "./clearing-codec.js";
 export interface ClearingSigner {
-    readonly address: Address;
-    signTypedData(args: {
-        domain: Record<string, unknown>;
-        types: Record<string, unknown>;
-        primaryType: string;
-        message: Record<string, unknown>;
-    }): Promise<Hex>;
+    publicKey: Hex;
+    sign(namespace: string, message: Hex): Hex | Promise<Hex>;
 }
-export interface ClearingDebitSchemeOptions {
-    /** The facilitator this payer trusts to report its position: Metal's,
-     * `https://<facilitator host>/x402/facilitator`. */
-    facilitator: string;
-    /** Where the highest total signed each epoch is remembered. Default: in
-     * memory, which does not survive a restart. */
-    storage?: ClearingPositionStorage;
-    fetch?: typeof globalThis.fetch;
-    /** Clock, in milliseconds. Default: wall time. */
-    now?: () => number;
+export interface ClearingEntry {
+    recipient: Hex;
+    cumulative: string;
+    count: string;
 }
-/** The payer's position as stored: the epoch, the next debit index and the
- * running total it last signed. Decimal strings, so any store can hold it. */
-export interface StoredClearingPosition {
-    epoch: string;
-    /** The next debit index, after the debit signed last. */
-    index: string;
-    /** The running total of the debit signed last. */
-    cumulativeDebit: string;
-    /** The highest running total ever signed in this epoch. It never goes
-     * down, so a stale or low report cannot weaken the check made against it. */
-    highestSigned: string;
+export interface ClearingPayment {
+    invoice: ClearingInvoice;
+    body: Hex;
+    payerSignature: Hex;
+    invoiceSignature: Hex;
+    entries: ClearingEntry[];
 }
-/** Where positions are kept: one record per network, Clearing contract,
- * payer and epoch. */
-export interface ClearingPositionStorage {
-    get(key: string): Promise<StoredClearingPosition | undefined>;
-    /** Store the position. An implementation MUST keep the larger of the
-     * stored and the new `highestSigned`, atomically with the write: two
-     * clients sharing a store sign in between each other's reads and writes,
-     * and the mark must never move down. `keepHighest` does the merge. */
-    set(key: string, position: StoredClearingPosition): Promise<void>;
+export interface ClearingPaid {
+    invoice: ClearingInvoice;
+    receipt: ClearingReceipt;
+    invoiceSignature: Hex;
+    entries: ClearingEntry[];
+    previous?: {
+        receipt: ClearingReceipt;
+        entries: ClearingEntry[];
+    };
 }
-/** `next`, with `highestSigned` no lower than the one already stored. */
-export declare function keepHighest(existing: StoredClearingPosition | undefined, next: StoredClearingPosition): StoredClearingPosition;
-/** The default store: positions do not survive a process restart. */
-export declare class InMemoryClearingPositionStorage implements ClearingPositionStorage {
-    private readonly positions;
-    get(key: string): Promise<StoredClearingPosition | undefined>;
-    set(key: string, position: StoredClearingPosition): Promise<void>;
+export interface ClearingClientState {
+    epoch?: string | undefined;
+    entries: ClearingEntry[];
+    sequence: string;
+    /** The payment sent whose outcome is unknown, with the URL it pays for
+     * when `pay` was given one. */
+    pending?: (ClearingPayment & {
+        url?: string | undefined;
+    }) | undefined;
+    payments: Record<string, ClearingPaid>;
 }
-export declare class ClearingDebitScheme implements SchemeNetworkClient {
-    private readonly signer;
-    readonly scheme = "clearing-debit";
-    readonly schemeHooks: SchemeClientHooks;
-    private readonly facilitator;
-    private readonly storage;
-    private readonly doFetch;
-    private readonly now;
-    /** Per payer and contract: the facilitator's last answer, adjusted for
-     * what this client has signed since. */
-    private readonly positions;
-    /** Per payer and contract: until when to pay the standard way. */
-    private readonly shortUntil;
-    /** Sellers the facilitator settles no clearing for, by network, contract
-     * and payee: a seller without Metal's seller token. That holds for as long
-     * as the client runs, so they are paid the standard way from then on. */
-    private readonly standardOnly;
-    /** Per payer and contract: the Debits whose outcome is in doubt, each to
-     * be presented again for its own offer. Only an answer about that Debit
-     * clears it. */
-    private readonly unresolved;
-    constructor(signer: ClearingSigner, options: ClearingDebitSchemeOptions);
-    /** The selector to give `new x402Client(...)`: the clearing offer, unless
-     * custody was lately found short or the seller cannot take clearing, in
-     * which case the standard one. A Debit whose outcome is in doubt is always
-     * presented again by clearing. */
-    readonly prefer: (_x402Version: number, accepts: PaymentRequirements[]) => PaymentRequirements;
-    /** One payment at a time per payer and contract: reading the position,
-     * signing and recording it must not interleave, or two payments would sign
-     * the same index. */
-    private readonly queues;
-    private exclusive;
-    private key;
-    private sellerOf;
-    /** The fetch to give `wrapFetchWithPayment`. A request carrying a Debit
-     * that fails without an answer, or ends in a server error that says
-     * nothing about the Debit (a proxy's 502 or 504), may still have been
-     * admitted, so its Debit is held in doubt: the next payment for that offer
-     * presents it again. It is held in memory, for as long as the client
-     * runs. */
-    wrapFetch(fetch: typeof globalThis.fetch): typeof globalThis.fetch;
-    /** Holds the Debit a request carried, if it carried one of this client's. */
-    private holdSent;
-    private hold;
-    /** Clears a Debit once a seller has answered about it. */
-    private release;
-    /** What makes two offers the same payment: a Debit signed for one can be
-     * presented again for the other. */
-    private offerId;
-    /** Where the next Debit starts: the facilitator's answer while it is
-     * fresh, else a new one. */
-    private position;
-    createPaymentPayload(x402Version: number, requirements: PaymentRequirements): Promise<PaymentPayloadResult>;
-    private sign;
+/** save must complete an atomic durability barrier; one process owns each payer. */
+export interface ClearingClientStore {
+    load(): Promise<ClearingClientState | null>;
+    save(state: ClearingClientState): Promise<void>;
 }
-/** Put funds into clearing custody. `from` pays and sends the transactions:
- * the agent's own wallet, or anyone funding it, in which case `account` is
- * the agent's address. The tokens go from `from` straight into custody under
- * `account`; only `account`'s signature can spend or withdraw them.
- *
- * Two transactions (an approval for exactly this amount, unless that much
- * is already approved, then the deposit), paid for in the network's fee token by `from`. Gas and
- * fees are set here because a Metal node cannot be asked to estimate them.
- *
- * The operator counts a deposit some seconds after its receipt, and refuses
- * clearing payments against it until then. Given `facilitator`, this waits
- * until the facilitator reports the deposit in the payer's position, so the
- * next payment can draw on it. */
-export declare function depositToClearing(opts: {
+export interface ClearingClientConfig {
+    serviceUrl: string;
     rpcUrl: string;
-    chainId: number;
-    from: LocalAccount;
-    /** The Clearing contract and the token it holds, as the 402 names them:
-     * `extra.clearing.contract` and `asset`. */
-    contract: Address;
-    asset: Address;
-    /** Whose custody is credited. Default: `from` itself. */
-    account?: Address;
-    amount: bigint;
-    /** The facilitator to wait on until it counts the deposit, as for
-     * `ClearingDebitScheme`. Only `from`'s own custody can be waited on: the
-     * position request is signed by the account it is about. */
-    facilitator?: string;
-    /** How long to wait for the facilitator to count it. Default: 60 s. */
-    timeoutMs?: number;
-    /** How often to ask. Default: every second. */
-    pollMs?: number;
-    fetch?: typeof globalThis.fetch;
-}): Promise<{
-    approveTx: Hex | null;
-    depositTx: Hex;
-    available?: bigint;
-}>;
-/** Take funds out of clearing custody: a payer's unused deposit, or what a
- * seller has been paid. It asks the facilitator what can be withdrawn, signs
- * an Exit for that amount, and submits it; Metal's operator sends the two
- * transactions (request, then release) and pays their gas.
- *
- * Only this wallet's signature moves its funds, and only to the destination
- * it names, which defaults to the wallet itself. */
-export declare function withdrawFromClearing(signer: ClearingSigner, facilitator: string, options: {
-    network: string;
-    /** Where the funds go. Default: the wallet itself. */
-    destination?: Address;
-    /** How much to withdraw, in base units. Default: everything available. */
-    amount?: bigint;
+    network: `eip155:${number}`;
+    settlement: Hex;
+    asset: Hex;
+    signer: ClearingSigner;
+    store: ClearingClientStore;
+    maxAmount: bigint;
     fetch?: typeof globalThis.fetch;
-    /** Clock, in milliseconds. Default: wall time. */
-    now?: () => number;
-}): Promise<{
-    amount: bigint;
-    requestTx: string;
-    releaseTx: string | null;
-}>;
+}
+/** Why a clearing payment was not made. */
+export type ClearingRefusalReason = "between_epochs" | "insufficient_deposit" | "payment_held" | "answer_lost";
+/** What to do after a `ClearingRefusal`. */
+export type ClearingRetry = 
+/** Nothing was paid: send the request again after `ms`, and wait `ms`
+ * again after each further `between_epochs` refusal. */
+{
+    action: "retry_after_ms";
+    ms: number;
+}
+/** Nothing was paid: deposit more, then send the request again. */
+ | {
+    action: "deposit";
+}
+/** The wallet holds a payment whose outcome is unknown, `amount` base
+ * units for `url` (`null` when `pay` was given none; through
+ * `fetchWithPayment`, the URL the request was sent to), and pays nothing
+ * else until it goes through: send that request again at that price
+ * after `ms`, which sends the same payment, so it is never paid twice. If
+ * that URL no longer offers clearing at that price, pass the wallet's
+ * `pendingInvoice()` to its `pay`, which sends the held payment itself
+ * once more; the wallet pays others once it goes through or is refused. */
+ | {
+    action: "repeat_same_request";
+    url: string | null;
+    amount: string;
+    ms: number;
+};
+/** A clearing payment the service did not take: `reason` says why, `retry`
+ * what to do, and the message both in words. */
+export declare class ClearingRefusal extends Error {
+    readonly reason: ClearingRefusalReason;
+    readonly retry: ClearingRetry;
+    readonly name = "ClearingRefusal";
+    constructor(reason: ClearingRefusalReason, retry: ClearingRetry, message: string, options?: ErrorOptions);
+}
+export declare function createClearingClient(config: ClearingClientConfig): {
+    account: `0x${string}`;
+    pendingInvoice(): Promise<ClearingInvoice | null>;
+    /** Why this wallet does not pay `invoice`, or undefined when it does. */
+    unpayable: (invoice: ClearingInvoice) => {
+        reason: string;
+        aboveMaxAmount: boolean;
+    } | undefined;
+    /** Pay `invoice`; `url`, the request it pays for, is kept with a
+     * payment whose outcome is unknown, so a refusal can name it. A payment
+     * the service does not take throws a `ClearingRefusal`. */
+    pay(invoice: ClearingInvoice, url?: string): Promise<ClearingPaid>;
+    request: <T>(path: string, body?: unknown) => Promise<T>;
+};