@mooring-live/x402-client 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,152 @@
-# Temporary Holding Version
+# @mooring-live/x402-client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Pay [x402](https://x402.org)-protected APIs from a **Mooring spending card** on Stellar.
+
+A card is a Soroban custom account (`__check_auth`) that holds USDC and enforces a spending
+policy — periodic budget, per-payment cap, merchant allowlist, expiry, freeze/cancel — inside the
+authorization path. This package is the agent-side client: it detects a `402`, checks the card's
+policy locally, signs the payment with the agent key so the **card** is the payer, and turns every
+refusal into a typed error instead of a bare `402` — `CardPolicyDenied` when the card's policy
+said no, `PaymentError` for everything else.
+
+The server side stays stock x402 (`@x402/express` + `@x402/stellar` + any facilitator built on
+them — OpenZeppelin Channels and Rail402 are both verified); only the client scheme is Mooring's,
+because the stock one cannot sign for a contract account.
+
+Apache-2.0. **Stellar testnet only** — not audited, not on mainnet.
+
+## Install
+
+```sh
+npm i @mooring-live/x402-client @stellar/stellar-sdk
+```
+
+`@stellar/stellar-sdk` is a dependency of the client, but you import `Keypair` from it yourself,
+so install it alongside. The CLI (`npm i -g @mooring-live/cli`) wraps the same client for shell use.
+
+Requires Node.js 20+.
+
+## Usage
+
+```ts
+import { Keypair } from "@stellar/stellar-sdk";
+import { CardPolicyDenied, PaymentError, createMooringFetch, getSettlement } from "@mooring-live/x402-client";
+
+const fetchWithPayment = createMooringFetch({
+  card: "CAJPWJBF…AHCJ",                                 // card contract address (the payer)
+  agent: Keypair.fromSecret(process.env.AGENT_SECRET!),  // the card's registered signer
+  network: "stellar:testnet",
+});
+
+const res = await fetchWithPayment("https://api.example.com/weather");
+console.log(await res.json());
+console.log("settled:", getSettlement(res)?.transaction);
+```
+
+That is the whole integration: `fetchWithPayment` is a drop-in `fetch`. A `402` is answered by
+paying from the card and retrying; a `200` carries a `PAYMENT-RESPONSE` header that
+`getSettlement` decodes into `{ success, transaction, network, payer }`, where `payer` is the
+card.
+
+## Handling a refusal
+
+```ts
+try {
+  await fetchWithPayment(url);
+} catch (err) {
+  if (err instanceof CardPolicyDenied) {
+    // err.reason: "over_budget" | "not_allowlisted" | "expired" | …
+    // err.stage:  "precheck" | "simulate" | "verify" | "settle"
+    // err.contractError: the card's error code, when the contract spoke (1–8)
+    console.error(`payment refused: ${err.reason} at ${err.stage}`);
+  } else if (err instanceof PaymentError) {
+    // Not the card's verdict. err.kind: "rejected" | "unconfirmed"
+    console.error(`payment ${err.kind}: ${err.detail}`, err.transaction);
+  } else {
+    throw err; // a network/server problem the client did not classify
+  }
+}
+```
+
+**Failed payments are never retried automatically**, at any stage.
+
+`CardPolicyDenied` means exactly one thing: **the card's policy refused**. Everything else is a
+`PaymentError`, so a caller can treat the first as a policy decision without further checks.
+
+| `PaymentError.kind` | When | Was the card debited? |
+|---|---|---|
+| `rejected` | the facilitator refused before submitting — a malformed payload, a fee above its ceiling, an expiration too far out, a 5xx — or the client's own CAP-71 credential guard fired before signing | no |
+| `unconfirmed` | the settlement state is unknown or contradictory: the server reported a failure for a transaction the ledger accepted, the transaction was never observed within the reconciliation window, or the server answered a bare `402` with no `PAYMENT-REQUIRED` and no `PAYMENT-RESPONSE` | possibly — reconcile `err.transaction` and the card's `spent` before retrying |
+
+The facilitator answers `settle_exact_stellar_transaction_failed` both for a transaction the
+ledger rejected and for one it stopped waiting for, so a settle failure carrying a hash is
+reconciled against the RPC (~10 s) before it is named: a transaction the ledger accepted is never
+reported as a policy denial.
+
+### Stages
+
+| Stage | When | Reached the network? |
+|---|---|---|
+| `precheck` | the local policy mirror refused, before anything was signed | two read-only simulations of the card's views |
+| `simulate` | the card's own `__check_auth` refused, in the enforcing simulation the client runs after signing | no — nothing left the process, no fee paid |
+| `verify` | the facilitator refused the payload | yes; nothing submitted on-chain |
+| `settle` | the settlement transaction failed on-chain — confirmed with the RPC, and attributed to the card only when the failure's diagnostics name it | yes; a transaction was submitted and failed |
+
+### Reasons
+
+`frozen`, `cancelled`, `expired`, `not_allowlisted`, `over_per_tx_cap`, `over_budget`,
+`wrong_token`, `insufficient_balance`, `bad_signature`, `wrong_context`, `unknown`.
+
+Card contract codes map as #1 `bad_signature`, #2 `wrong_context`, #3 `frozen`, #4 `cancelled`,
+#5 `expired`, #6 `not_allowlisted`, #7 `over_per_tx_cap`, #8 `over_budget`. `wrong_token` and
+`insufficient_balance` are pre-check-only verdicts. `unknown` is **not a policy verdict** — only
+an unclassified one: the card refused but the client could not read which rule. It covers a card
+that could not be read (the pre-check fails **closed**), a facilitator `simulation_failed` the
+re-run pre-check no longer explains, and an on-chain failure whose diagnostics do not name the
+card.
+
+## Options
+
+| Option | Type | Default | Meaning |
+|---|---|---|---|
+| `card` | `string` | — | card contract address (`C…`); it is the payer |
+| `agent` | `Keypair` | — | the card's registered signer |
+| `network` | `"stellar:testnet" \| "stellar:pubnet"` | — | CAIP-2 network |
+| `rpcUrl` | `string` | testnet default; **required** on pubnet | Soroban RPC endpoint |
+| `precheck` | `boolean` | `true` | run the local policy mirror before signing |
+| `onDenial` | `(d: CardPolicyDenied) => void` | — | called at every denial stage |
+| `onPaymentError` | `(e: PaymentError) => void` | — | called for every non-policy failure |
+| `fetch` | `typeof fetch` | `globalThis.fetch` | transport (`createMooringFetch` only) |
+
+## API
+
+| Export | What it does |
+|---|---|
+| `createMooringFetch(opts)` | a `fetch` that pays from the card and rejects with `CardPolicyDenied` or `PaymentError`, never a bare `402`; builds a fresh client per call, so it is safe to share |
+| `createMooringClient(opts)` | the underlying `x402Client`. **Single-flight per instance** — x402's hooks carry no request identity, so build one per payment. Used directly it is stock x402: it throws generic errors and returns bare `402`s, and only `onDenial` / `onPaymentError` carry the typed reason |
+| `getSettlement(res)` | decodes `PAYMENT-RESPONSE`; `null` when absent or undecodable (a settlement you cannot read is not a failed payment) |
+| `CardPolicyDenied`, `DenialReason`, `DenialStage`, `CARD_ERROR_CODES`, `classifyContractError`, `cardDenialFromEvents` | typed denials (payment-path codes 1-8) |
+| `CARD_ERRORS` | the full contract error table (codes 1-13, including owner-operation errors like `InvalidLabel`) mapped to short user-facing sentences |
+| `PaymentError` | every failure that is *not* the card's policy (`rejected` / `unconfirmed`) |
+| `reconcileSettlement(rpcUrl, network, hash)` | asks the ledger what became of a settlement transaction |
+| `precheck(info, merchants, terms, now)` | the local policy mirror, on its own |
+| `readCardInfo(rpcUrl, passphrase, card)`, `readMerchants(…)` | read-only card views (`info()`, `merchants()`); `CardInfo.label` is the owner-chosen display name |
+| `CardExactStellarScheme` | the x402 `exact` scheme client whose payer is the card |
+| `signCardAuthEntries(tx, card, agent, expirationLedger)` | signs a card auth entry with the agent key |
+
+## Notes
+
+- The pre-check is **advisory**. The card contract is the authority and runs again at settlement;
+  the pre-check only avoids spending a signature and a round-trip on an obvious refusal.
+- Muxed (`M…`) destinations are not payable — a Soroban `Address` does not exist for them.
+- The client records legacy (v1) auth credentials (`useUpgradedAuth: false`) because the deployed
+  OZ Channels stack rejects CAP-71 `ADDRESS_V2` as malformed. It also **asserts** what the RPC
+  actually recorded and refuses to sign a v2 card entry, and `@stellar/stellar-sdk` is pinned
+  exactly to `17.0.1` while the workaround stands. All three go away together; see
+  `docs/x402-integration.md`.
+- The auth entry expires at `latestLedger + max(2, ceil(maxTimeoutSeconds / 6) - 2)` — a
+  deliberately conservative ledger estimate, so the expiry stays inside the window the facilitator
+  computes from its own.
+
+Full guide: [`docs/x402-integration.md`](../../docs/x402-integration.md). Testnet evidence:
+[`docs/testnet.md`](../../docs/testnet.md).

package/dist/card.d.ts

@@ -0,0 +1,60 @@
+export type CardState = 0 | 1 | 2;
+export interface CardPolicy {
+    period_amount: bigint;
+    period_duration: bigint;
+    max_per_tx: bigint;
+    expiry: bigint;
+}
+export interface CardInfo {
+    owner: string;
+    signer: Uint8Array;
+    token: string;
+    label: string;
+    policy: CardPolicy;
+    state: CardState;
+    period: {
+        start: bigint;
+        spent: bigint;
+    };
+    remaining: bigint;
+    balance: bigint;
+    allow_count: number;
+}
+/** `CardInfo` as `scValToNative` hands it back, before normalization. */
+export type RawCardInfo = {
+    owner: string;
+    signer: Uint8Array;
+    token: string;
+    label?: string;
+    policy: CardPolicy;
+    state: number;
+    period: {
+        start: bigint;
+        spent: bigint;
+    };
+    remaining: bigint;
+    balance: bigint;
+    allow_count: number;
+};
+/**
+ * Normalizes a raw `info()` result into `CardInfo`: `signer` becomes a
+ * plain `Uint8Array` (`scValToNative` hands back a node `Buffer`, which is one
+ * — copying it keeps node's type out of the published API), `allow_count` a
+ * `number`, and
+ * `state` is range-checked before it is narrowed. Every other field is already
+ * the `bigint` the contract declared, and is passed through untouched.
+ *
+ * @throws if `state` is not one of the contract's three variants.
+ * @throws if `label` is missing (a card deployed from a pre-label factory).
+ */
+export declare function normalizeInfo(raw: RawCardInfo): CardInfo;
+/**
+ * Normalizes a raw `merchants()` result into strkeys. `scValToNative` already
+ * renders an `ScAddress` as a strkey, so the guard is a no-op today; it keeps
+ * the reader honest if a future SDK hands back the raw XDR instead.
+ */
+export declare function normalizeMerchants(list: readonly unknown[]): string[];
+/** Reads the card's `info()` view via simulation (no signing, no fees). */
+export declare function readCardInfo(rpcUrl: string, networkPassphrase: string, card: string): Promise<CardInfo>;
+/** Reads the card's `merchants()` view via simulation. */
+export declare function readMerchants(rpcUrl: string, networkPassphrase: string, card: string): Promise<string[]>;

package/dist/card.js

@@ -0,0 +1,67 @@
+import { Address, contract, scValToNative } from "@stellar/stellar-sdk";
+/**
+ * Simulates a read-only contract method and returns its parsed result.
+ *
+ * `AssembledTransaction.build` without a `publicKey` simulates from a null
+ * account, so nothing is signed, submitted or charged.
+ */
+async function simulateView(rpcUrl, networkPassphrase, card, method) {
+    const tx = await contract.AssembledTransaction.build({
+        contractId: card,
+        method,
+        args: [],
+        networkPassphrase,
+        rpcUrl,
+        parseResultXdr: (v) => scValToNative(v),
+    });
+    return tx.result;
+}
+/**
+ * Normalizes a raw `info()` result into `CardInfo`: `signer` becomes a
+ * plain `Uint8Array` (`scValToNative` hands back a node `Buffer`, which is one
+ * — copying it keeps node's type out of the published API), `allow_count` a
+ * `number`, and
+ * `state` is range-checked before it is narrowed. Every other field is already
+ * the `bigint` the contract declared, and is passed through untouched.
+ *
+ * @throws if `state` is not one of the contract's three variants.
+ * @throws if `label` is missing (a card deployed from a pre-label factory).
+ */
+export function normalizeInfo(raw) {
+    const state = Number(raw.state);
+    if (state !== 0 && state !== 1 && state !== 2) {
+        throw new Error(`Unknown card state: ${raw.state}`);
+    }
+    if (typeof raw.label !== "string") {
+        throw new Error("card info has no label (card deployed from a pre-label factory?)");
+    }
+    return {
+        owner: raw.owner,
+        signer: new Uint8Array(raw.signer),
+        token: raw.token,
+        label: raw.label,
+        policy: raw.policy,
+        state: state,
+        period: raw.period,
+        remaining: raw.remaining,
+        balance: raw.balance,
+        allow_count: Number(raw.allow_count),
+    };
+}
+/**
+ * Normalizes a raw `merchants()` result into strkeys. `scValToNative` already
+ * renders an `ScAddress` as a strkey, so the guard is a no-op today; it keeps
+ * the reader honest if a future SDK hands back the raw XDR instead.
+ */
+export function normalizeMerchants(list) {
+    return list.map((a) => typeof a === "string" ? a : Address.fromScAddress(a).toString());
+}
+/** Reads the card's `info()` view via simulation (no signing, no fees). */
+export async function readCardInfo(rpcUrl, networkPassphrase, card) {
+    return normalizeInfo(await simulateView(rpcUrl, networkPassphrase, card, "info"));
+}
+/** Reads the card's `merchants()` view via simulation. */
+export async function readMerchants(rpcUrl, networkPassphrase, card) {
+    return normalizeMerchants(await simulateView(rpcUrl, networkPassphrase, card, "merchants"));
+}
+//# sourceMappingURL=card.js.map

package/dist/card.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"card.js","sourceRoot":"","sources":["../src/card.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAO,MAAM,sBAAsB,CAAC;AAsC7E;;;;;GAKG;AACH,KAAK,UAAU,YAAY,CACzB,MAAc,EACd,iBAAyB,EACzB,IAAY,EACZ,MAAc;IAEd,MAAM,EAAE,GAAG,MAAM,QAAQ,CAAC,oBAAoB,CAAC,KAAK,CAAI;QACtD,UAAU,EAAE,IAAI;QAChB,MAAM;QACN,IAAI,EAAE,EAAE;QACR,iBAAiB;QACjB,MAAM;QACN,cAAc,EAAE,CAAC,CAAY,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC,CAAM;KACxD,CAAC,CAAC;IACH,OAAO,EAAE,CAAC,MAAM,CAAC;AACnB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAAC,GAAgB;IAC5C,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAChC,IAAI,KAAK,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,KAAK,CAAC,uBAAuB,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC;IACtD,CAAC;IACD,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,kEAAkE,CAAC,CAAC;IACtF,CAAC;IACD,OAAO;QACL,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,MAAM,EAAE,IAAI,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC;QAClC,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,KAAK,EAAE,KAAkB;QACzB,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,WAAW,EAAE,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC;KACrC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAwB;IACzD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CACpB,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,CAAkB,CAAC,CAAC,QAAQ,EAAE,CACjF,CAAC;AACJ,CAAC;AAED,2EAA2E;AAC3E,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,MAAc,EACd,iBAAyB,EACzB,IAAY;IAEZ,OAAO,aAAa,CAAC,MAAM,YAAY,CAAc,MAAM,EAAE,iBAAiB,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;AACjG,CAAC;AAED,0DAA0D;AAC1D,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,MAAc,EACd,iBAAyB,EACzB,IAAY;IAEZ,OAAO,kBAAkB,CAAC,MAAM,YAAY,CAAY,MAAM,EAAE,iBAAiB,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC;AACzG,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,75 @@
+import type { Keypair } from "@stellar/stellar-sdk";
+import { x402Client } from "@x402/fetch";
+import { CardPolicyDenied, PaymentError } from "./denial.js";
+import { type StellarNetwork } from "./scheme.js";
+export interface MooringClientOptions {
+    card: string;
+    agent: Keypair;
+    network: StellarNetwork;
+    rpcUrl?: string;
+    /** Run the local policy pre-check before signing (default true). */
+    precheck?: boolean;
+    /** Called whenever the card's policy denies a payment, at any stage. */
+    onDenial?: (denial: CardPolicyDenied) => void;
+    /** Called whenever a payment fails for a reason that is *not* the card's policy. */
+    onPaymentError?: (error: PaymentError) => void;
+}
+export interface Settlement {
+    success: boolean;
+    transaction: string;
+    network: string;
+    payer?: string;
+    errorReason?: string;
+}
+/** Everything `createMooringFetch` can reject with. */
+type PaymentFailure = CardPolicyDenied | PaymentError;
+/**
+ * Internal: the last failure recorded by the hooks, so the fetch wrapper can
+ * rethrow it typed. `@x402/fetch` turns an aborted payment into a generic
+ * `Error` and returns verify/settle failures as a plain 402 response, so the
+ * hooks are the only place where the reason survives.
+ */
+declare class FailureBox {
+    last?: PaymentFailure;
+    set(failure: PaymentFailure, opts: MooringClientOptions): void;
+}
+/**
+ * Builds an x402 client that pays from a Mooring card.
+ *
+ * The card enforces the budget, allowlist and expiry on-chain; this client
+ * mirrors that policy locally so an over-limit payment is refused before the
+ * agent key signs anything, and classifies every other outcome into
+ * `CardPolicyDenied` (the card's policy refused) or `PaymentError` (anything
+ * else).
+ *
+ * **One instance is single-flight.** x402's hook contexts carry no request
+ * identity, so the failure recorded by one payment cannot be told apart from
+ * another's: do not run concurrent payments through the same client. Build one
+ * per payment, or use `createMooringFetch`, which does that for you.
+ *
+ * Used directly, the returned `x402Client` still throws x402's own generic
+ * errors and hands back bare 402 responses: only `onDenial` / `onPaymentError`
+ * surface the typed reason. `createMooringFetch` is what turns them into
+ * thrown `CardPolicyDenied` / `PaymentError`.
+ */
+export declare function createMooringClient(opts: MooringClientOptions, box?: FailureBox): x402Client;
+/**
+ * A `fetch` that pays x402-protected requests from the card, and rejects with
+ * `CardPolicyDenied` (the card's policy refused) or `PaymentError` (anything
+ * else) — never a bare 402 — whenever the payment does not deliver the
+ * resource. Failed payments are never retried.
+ *
+ * Each call builds its own client and failure scope — `x402Client.fromConfig`
+ * does no I/O — so concurrent requests through the same returned `fetch` cannot
+ * observe each other's failures.
+ */
+export declare function createMooringFetch(opts: MooringClientOptions & {
+    fetch?: typeof globalThis.fetch;
+}): typeof globalThis.fetch;
+/**
+ * Decodes the PAYMENT-RESPONSE header of a paid response. Returns `null` when
+ * the header is absent or undecodable — a settlement we cannot read is not a
+ * failed payment, and must never turn a 200 into an error.
+ */
+export declare function getSettlement(res: Response): Settlement | null;
+export {};

package/dist/client.js

@@ -0,0 +1,252 @@
+import { decodePaymentResponseHeader, wrapFetchWithPayment, x402Client } from "@x402/fetch";
+import { getNetworkPassphrase, getRpcUrl } from "@x402/stellar";
+import { readCardInfo, readMerchants } from "./card.js";
+import { CARD_ERROR_CODES, CardPolicyDenied, PaymentError, cardDenialFromEvents, classifyContractError, } from "./denial.js";
+import { precheck } from "./precheck.js";
+import { reconcileSettlement } from "./reconcile.js";
+import { CardExactStellarScheme } from "./scheme.js";
+/**
+ * Internal: the last failure recorded by the hooks, so the fetch wrapper can
+ * rethrow it typed. `@x402/fetch` turns an aborted payment into a generic
+ * `Error` and returns verify/settle failures as a plain 402 response, so the
+ * hooks are the only place where the reason survives.
+ */
+class FailureBox {
+    last;
+    set(failure, opts) {
+        this.last = failure;
+        if (failure instanceof CardPolicyDenied)
+            opts.onDenial?.(failure);
+        else
+            opts.onPaymentError?.(failure);
+    }
+}
+/**
+ * Builds an x402 client that pays from a Mooring card.
+ *
+ * The card enforces the budget, allowlist and expiry on-chain; this client
+ * mirrors that policy locally so an over-limit payment is refused before the
+ * agent key signs anything, and classifies every other outcome into
+ * `CardPolicyDenied` (the card's policy refused) or `PaymentError` (anything
+ * else).
+ *
+ * **One instance is single-flight.** x402's hook contexts carry no request
+ * identity, so the failure recorded by one payment cannot be told apart from
+ * another's: do not run concurrent payments through the same client. Build one
+ * per payment, or use `createMooringFetch`, which does that for you.
+ *
+ * Used directly, the returned `x402Client` still throws x402's own generic
+ * errors and hands back bare 402 responses: only `onDenial` / `onPaymentError`
+ * surface the typed reason. `createMooringFetch` is what turns them into
+ * thrown `CardPolicyDenied` / `PaymentError`.
+ */
+export function createMooringClient(opts, box = new FailureBox()) {
+    const rpcUrl = getRpcUrl(opts.network, opts.rpcUrl ? { url: opts.rpcUrl } : undefined);
+    const passphrase = getNetworkPassphrase(opts.network);
+    const scheme = new CardExactStellarScheme({
+        card: opts.card,
+        agent: opts.agent,
+        network: opts.network,
+        rpcUrl: opts.rpcUrl,
+        // A failure raised inside the scheme (the card refusing the enforcing
+        // simulation, or the CAP-71 credential guard) travels out as a thrown
+        // error, but it must reach the hooks and the box like every other stage.
+        onDenial: (denial) => box.set(denial, opts),
+        onPaymentError: (error) => box.set(error, opts),
+    });
+    const evaluate = async (req) => {
+        const [info, merchants] = await Promise.all([
+            readCardInfo(rpcUrl, passphrase, opts.card),
+            readMerchants(rpcUrl, passphrase, opts.card),
+        ]);
+        return precheck(info, merchants, { payTo: req.payTo, amount: req.amount, asset: req.asset }, Math.floor(Date.now() / 1000));
+    };
+    /**
+     * Classifies a refusal that happened *before* anything was submitted.
+     *
+     * The facilitator does not say whose rule it applied, so the card is asked
+     * instead: if the card's own state explains the refusal it is a policy
+     * denial, and `simulation_failed` is policy-shaped too (a card denial is a
+     * simulation failure — that is the whole of finding the reason on-chain, and
+     * a race can produce one the re-run pre-check no longer sees). Every other
+     * reason the facilitator can give — a malformed payload, a fee above its
+     * ceiling, an expiration too far out — is not the card's verdict and must
+     * not be reported as one.
+     */
+    const classifyRefusal = async (stage, text, req) => {
+        const parsed = classifyContractError(text);
+        if (parsed && parsed.code in CARD_ERROR_CODES) {
+            return new CardPolicyDenied(parsed.reason, stage, {
+                contractError: parsed.code,
+                detail: text || undefined,
+            });
+        }
+        let reason = null;
+        try {
+            reason = await evaluate(req);
+        }
+        catch {
+            /* the card could not be read; fall through to the reason string */
+        }
+        if (reason)
+            return new CardPolicyDenied(reason, stage, { detail: text || undefined });
+        if (text.includes("simulation_failed")) {
+            return new CardPolicyDenied("unknown", stage, { detail: text || undefined });
+        }
+        return new PaymentError({ kind: "rejected", detail: text || undefined });
+    };
+    /**
+     * Decides what a failed settlement means, by asking the ledger.
+     *
+     * A settle failure that carries a transaction hash is *not* evidence the
+     * payment did not happen: the facilitator returns the same
+     * `settle_exact_stellar_transaction_failed` when its poll times out, and
+     * inclusion can follow that answer. So the hash is reconciled before the
+     * failure is named — a transaction the ledger accepted is never reported as
+     * a policy denial, however the server described it.
+     */
+    const classifySettleFailure = async (settle, req) => {
+        const reason = settle.errorReason ?? "settle failed";
+        const hash = settle.transaction;
+        if (!hash)
+            return classifyRefusal("settle", reason, req);
+        let outcome;
+        try {
+            outcome = await reconcileSettlement(rpcUrl, opts.network, hash);
+        }
+        catch (err) {
+            return new PaymentError({
+                kind: "unconfirmed",
+                transaction: hash,
+                detail: `${reason}; reconciliation failed: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+        if (outcome.status === "SUCCESS") {
+            return new PaymentError({
+                kind: "unconfirmed",
+                transaction: hash,
+                detail: "settled on-chain but the server reported failure; reconcile",
+            });
+        }
+        if (outcome.status === "NOT_FOUND") {
+            return new PaymentError({
+                kind: "unconfirmed",
+                transaction: hash,
+                detail: `${reason}; not observed on-chain within the reconciliation window`,
+            });
+        }
+        const parsed = cardDenialFromEvents(outcome.events, opts.card);
+        return new CardPolicyDenied(parsed?.reason ?? "unknown", "settle", {
+            contractError: parsed?.code,
+            detail: `${reason} tx=${hash}`,
+        });
+    };
+    const client = x402Client.fromConfig({
+        schemes: [{ network: opts.network, client: scheme }],
+        // The card enforces limits on-chain; x402's USD-based client caps would only get in the way.
+        spendControls: false,
+    });
+    client.onBeforePaymentCreation(async ({ selectedRequirements }) => {
+        if (opts.precheck === false)
+            return;
+        let reason;
+        try {
+            reason = await evaluate(selectedRequirements);
+        }
+        catch (err) {
+            // Fail closed: a card we cannot read is a card we cannot spend from.
+            const detail = `pre-check unavailable: ${err instanceof Error ? err.message : String(err)}`;
+            box.set(new CardPolicyDenied("unknown", "precheck", { detail }), opts);
+            return { abort: true, reason: detail };
+        }
+        if (reason) {
+            box.set(new CardPolicyDenied(reason, "precheck"), opts);
+            return { abort: true, reason };
+        }
+    });
+    client.onPaymentResponse(async ({ requirements, settleResponse, paymentRequired, error }) => {
+        if (settleResponse && !settleResponse.success) {
+            box.set(await classifySettleFailure(settleResponse, requirements), opts);
+            return;
+        }
+        if (paymentRequired && !settleResponse) {
+            // Verify failed. The facilitator does not say why; ask the card.
+            const text = paymentRequired.error ?? error?.message ?? "";
+            box.set(await classifyRefusal("verify", text, requirements), opts);
+        }
+    });
+    return client;
+}
+/**
+ * A `fetch` that pays x402-protected requests from the card, and rejects with
+ * `CardPolicyDenied` (the card's policy refused) or `PaymentError` (anything
+ * else) — never a bare 402 — whenever the payment does not deliver the
+ * resource. Failed payments are never retried.
+ *
+ * Each call builds its own client and failure scope — `x402Client.fromConfig`
+ * does no I/O — so concurrent requests through the same returned `fetch` cannot
+ * observe each other's failures.
+ */
+export function createMooringFetch(opts) {
+    const transport = opts.fetch ?? globalThis.fetch;
+    return (async (input, init) => {
+        const box = new FailureBox();
+        const wrapped = wrapFetchWithPayment(transport, createMooringClient(opts, box));
+        try {
+            const res = await wrapped(input, init);
+            // Verify and settle failures come back as a non-2xx response, not a
+            // throw; the hooks have recorded why, so surface it typed.
+            if (box.last)
+                throw box.last;
+            const settlement = getSettlement(res);
+            if (settlement && !settlement.success) {
+                // The hooks classify every settlement they see; reaching here means
+                // the header said "failed" without the hook firing, so the settlement
+                // state is exactly as unknown as the header is unexplained.
+                box.set(new PaymentError({
+                    kind: "unconfirmed",
+                    transaction: settlement.transaction || undefined,
+                    detail: settlement.errorReason ?? "settle failed",
+                }), opts);
+                throw box.last;
+            }
+            if (res.status === 402) {
+                // The payment was made and the resource still withheld, with nothing
+                // in the response to say what happened to it. `@x402/express` answers
+                // exactly this from its settlement path, *after* the facilitator may
+                // have submitted — so this is an unknown settlement, not a denial.
+                box.set(new PaymentError({
+                    kind: "unconfirmed",
+                    detail: "402 without PAYMENT-REQUIRED or PAYMENT-RESPONSE; settlement state unknown",
+                }), opts);
+                throw box.last;
+            }
+            return res;
+        }
+        catch (err) {
+            // A pre-check abort reaches us as a generic Error from @x402/fetch.
+            if (err instanceof CardPolicyDenied || err instanceof PaymentError)
+                throw err;
+            if (box.last)
+                throw box.last;
+            throw err;
+        }
+    });
+}
+/**
+ * Decodes the PAYMENT-RESPONSE header of a paid response. Returns `null` when
+ * the header is absent or undecodable — a settlement we cannot read is not a
+ * failed payment, and must never turn a 200 into an error.
+ */
+export function getSettlement(res) {
+    const header = res.headers.get("PAYMENT-RESPONSE") ?? res.headers.get("X-PAYMENT-RESPONSE");
+    if (!header)
+        return null;
+    try {
+        return decodePaymentResponseHeader(header);
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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