@envarai/envarpay 0.1.0-alpha.3 → 0.2.0-alpha.1

package/README.md

@@ -1,159 +1,69 @@
-# @envarai/envarpay
+# EnvarPay TypeScript
 
-A TypeScript client for an existing **authenticated EnvarPay wallet MCP service**.
-The client does not install Python, run a signer, hold wallet keys, or change wallet
-policy. Use the Python CLI or a separately operated service for those responsibilities.
+Independent service commerce for user-operated Agents. Public communication uses
+A2A 1.0; payments use native x402 v2 exact USDC or MPP Stripe charge. Prices and
+scope are versioned configuration, enforced before dispatch, not instructions in
+a prompt. Envar is an optional directory and management UI.
 
-This client uses the alpha release channel. See
-[installation channels](https://github.com/EnvarAI/EnvarPay/blob/main/docs/packages.md)
-for the current registry status and available distributions.
+The 0.2 source line replaces the previous npm wallet-only MCP client. Build from
+this checkout while the release is undergoing acceptance; a source version is
+not evidence that its npm/OCI artifact is published.
 
-## Install and start a wallet
+## Runtime and entry points
 
-Install the npm alpha client:
+Node.js 22.14+ (Node 24 recommended). SQLite is single-instance. Contracts can be
+read without loading the seller or buyer runtime; Bun validation covers the
+contracts entry, not the SQLite server.
 
-```sh
-npm install @envarai/envarpay@next
-```
-
-If your project uses a custom package registry, route this scope to the public
-registry in its `.npmrc`: `@envarai:registry=https://registry.npmjs.org/`.
-
-Node.js >=22.14 and Bun are supported. Import this package from an ESM application.
-The npm library is a client; the wallet runs as a separate service:
-
-```sh
-uv tool install --python 3.13 envarpay==0.1.0a10
-envarpay init --agent mcp --role buyer --directory ./buyer \
-  --peer-url https://seller.example/mcp --pay-to SELLER_FULL_RECEIVING_ADDRESS \
-  --tool ask_agent --max-per-call 0.01 --budget 0.05
-envarpay keygen --output ./buyer/buyer.key
-```
-
-The generated policy uses Base Sepolia test USDC and payments off. Fund the
-dedicated test wallet, review the recipient/tool/limits and enable payments only
-for your intended purchases. The agent never receives the wallet key.
-
-Create the wallet-access credential in your private operator environment. This
-command never prints it and refuses to overwrite an existing file:
+| Entry | Purpose |
+|---|---|
+| `@envarai/envarpay` | Config types/validation, integer pricing, quotes and A2A Cards |
+| `/server` | Durable seller A2A handler, exact x402 gate and native upstream executor |
+| `/client` | Buyer policy, atomic budgets, original-operation recovery and private management |
+| `/mpp` | Opt-in native MPP seller and read-only Stripe reconciliation |
+| `/envar` | Optional bounded config pull/ack and durable observation reports |
 
 ```sh
-python3 - <<'PY'
-import os, secrets
-with os.fdopen(os.open('buyer/wallet-service.token', os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600), 'w') as f:
-    f.write(secrets.token_urlsafe(32))
-PY
+npm ci --ignore-scripts
+npm run build
+node dist/commerce/cli.js init --directory ./private
+node dist/commerce/cli.js validate --config ./private/seller.json
 ```
 
-Add this table to the existing `buyer.toml`:
-
-```toml
-[wallet_server]
-host = "127.0.0.1"
-port = 4021
-allowed_hosts = ["127.0.0.1:*", "localhost:*"]
-bearer_token_file = "./wallet-service.token"
-```
+Initialization writes examples and a vault key; it never creates a purchase or
+funds a wallet. Replace example addresses/hosts and review service limits before
+starting. Keep Agent model credentials in the Agent, and signer keys in a separate
+private wallet boundary.
 
 ```sh
-envarpay doctor --config ./buyer/buyer.toml
-envarpay wallet-serve --config ./buyer/buyer.toml
-```
-
-For local development, connect to `http://127.0.0.1:4021/mcp`. For a separate wallet
-permission boundary, run it under another OS identity/container or on a private
-service with HTTPS; only the wallet receives its key, policy and ledger. Keep the
-wallet service private. Give the client its wallet-access token, not a seller's
-token or an Envar machine credential.
-
-## Discover tools and make a purchase
-
-```ts
-import { WalletClient, OperationUnknownError } from '@envarai/envarpay';
-
-const wallet = await WalletClient.connect({
-  url: 'https://wallet.example/mcp',
-  token: process.env.ENVARPAY_WALLET_TOKEN!,
-});
-try {
-  const tools = await wallet.listPaidTools('seller');
-  console.log(tools.tools.map(tool => tool.name));
-  // This may pay within the wallet operator's existing allowlist and budget.
-  const result = await wallet.callPaidTool({
-    peer: 'seller', tool: 'ask_agent',
-    arguments: { question: 'Review my API design' }, requestId: 'review-001',
-  });
-  console.log(result.result.content);
-} catch (error) {
-  if (error instanceof OperationUnknownError) {
-    console.log(await wallet.paymentStatus(error.requestId));
-    // When the operator-approved seller supports recovery:
-    // await wallet.recoverPayment(error.requestId);
-  } else throw error;
-} finally {
-  await wallet.close();
-}
+node dist/commerce/cli.js serve --config seller.json \
+  --credentials private/seller-auth.json --state private/seller.sqlite3 \
+  --origin https://seller.example --port 4020
+node dist/commerce/cli.js buyer-serve --config buyer-policy.json \
+  --credentials private/buyer-auth.json --state private/buyer.sqlite3 \
+  --origin https://buyer-management.example --port 4021
 ```
 
-The example uses the `seller` alias generated by the quickstart. If you changed it,
-use the alias actually configured in `buyer.toml`.
-`listPaidTools` does not pay. `callPaidTool` may spend within the existing wallet
-policy; `paymentStatus` and `recoverPayment` retain the original purchase.
-
-## Envar discovery and transaction pages
-
-With the optional `[connection]` in the wallet, these additional methods read
-Envar's public catalog:
-
-```ts
-const candidates = await wallet.discoverAgents('research');
-console.log(candidates.payment_authorized); // always false
-const profile = await wallet.getAgent('THE_PUBLISHED_AGENT_HANDLE');
-```
-
-The operator still approves and configures a peer before purchasing from it.
-The Python wallet handles optional durable Envar reports; the npm client does not
-duplicate signing, settlement or the platform's payment verification.
-[Complete Envar setup](https://github.com/EnvarAI/EnvarPay/blob/main/docs/envar.md).
-
-## Receiving and asynchronous tasks
-
-For **receiving**, put the Python `envarpay` payment gate in front of your existing
-private JS/TS MCP tool and expose only the gate through HTTPS. No buyer-wallet
-client is needed to receive payments; the seller does not need a signing key.
-[Seller quickstart](https://github.com/EnvarAI/EnvarPay/blob/main/docs/selling.md).
-
-For **asynchronous escrow/acceptance/refunds**, use Python `envarpay[task]` and
-`envarpay task wallet` with your host's standard MCP client. The task mode is an
-experimental Base Sepolia-only flow, separate from this upfront wallet API.
-[Task guide](https://github.com/EnvarAI/EnvarPay/blob/main/docs/tasks/README.md).
-
-## Errors and recovery
-
-Persist the request ID in your application before calling. Never replace it after
-an uncertain result. The client does not retry paid calls; the wallet retains the
-original authorization and ledger. A `WalletToolError` preserves an explicit
-wallet refusal/execution error. An `OperationUnknownError` means the result is
-uncertain, including transport failures and timeouts; it does not mean no payment occurred.
-
-HTTPS is required except for loopback HTTP. Redirects are rejected, including
-redirects to another wallet URL. The bearer token belongs to the wallet service,
-not to a seller or public directory; keep it in the application's private config.
-
-Targets Node.js >=22.14 and Bun. Local tests use the actual Python wallet MCP
-adapter with a fake service and transfer no funds; they are not real payment evidence.
-This client has no task-escrow API or framework-native plugin manifest.
-
-## Reviewed purchases from Envar
-
-Use the published Python EnvarPay 0.1.0a10 service with this client. `walletPolicy()` reads limits
-and already-approved peers. `callAgent()` selects only a peer bound to the reviewed
-Agent and endpoint IDs; it never adds a directory candidate to wallet policy. Supply
-`expectedNetwork`, `expectedPayTo` and `expectedAmountAtomic` from the terms you
-reviewed. A different live price is refused before signing. Keep `requestId` across
-uncertain outcomes and use the original status/recovery methods.
-
-The website can use the same authenticated wallet through its owner-only entry.
-For task creation, result verification and acceptance/refunds, connect the private
-`envarpay task wallet-serve` using a standard MCP client. The task signer and
-contract verification stay in Python; the task mode remains experimental/testnet.
+The management service is private and owner-authenticated. A website may request a
+quote and confirm an already-reviewed purchase; it cannot change peers, recipient
+allowlists, budgets or signing keys. Unknown outcomes retain the original request,
+signature/SPT and reserved budget. Never create a replacement purchase after a
+timeout.
+
+[Seller and wire behavior](../../docs/a2a-commerce.md) ·
+[Buyer management](../../docs/a2a-buyer.md) ·
+[Continuation and recovery](../../docs/a2a-runtime-recovery.md) ·
+[Envar configuration integration](../../docs/a2a-envar.md)
+
+## Payment guarantees
+
+Payment confirmation, task completion and acceptance are separate facts. The MVP
+charges upfront for a new task; reads and permitted clarification use that same
+purchase. It does not provide escrow, automatic refunds, subscriptions or billing
+for arbitrary internal tools. A2A compatibility alone does not give an Agent a
+wallet or authorize payment.
+
+MPP requires an eligible Stripe merchant, a permitted buyer token-creation flow,
+explicit test/live mode and any required customer authentication. Simulator tests
+are not card charges. Provider and chain acceptance must be recorded separately
+from SDK tests and build results.

package/dist/commerce/buyer-store.d.ts

@@ -0,0 +1,93 @@
+import type { PaymentRequired, PaymentRequirements, SettleResponse } from '@x402/core/types';
+import type { Challenge } from 'mppx';
+import type { MppReceipt } from './mpp-client.js';
+import { type BuyerPolicy, type Input } from './types.js';
+export interface BuyerQuote {
+    messageId: string;
+    payer: string;
+    amount: string;
+    currency: string | null;
+    recipient: string | null;
+    expiresAt: string;
+    serviceId: string;
+    serviceRevision: number;
+    offerId: string;
+    inputDigest: string;
+    termsDigest: string;
+    quoteId: string;
+}
+export interface BuyerRecord {
+    id: string;
+    caller: string;
+    peerId: string;
+    cardUrl: string;
+    endpoint: string;
+    messageId: string;
+    fingerprint: string;
+    body: string;
+    quoteToken: string;
+    quote: BuyerQuote;
+    input: Input;
+    inputSchema: Record<string, unknown>;
+    continuations?: {
+        messageId: string;
+        input: Input;
+        body?: string;
+        state: 'pending' | 'unknown' | 'resolved';
+        beforeDigest: string;
+    }[];
+    protocol?: 'x402' | 'mpp' | 'free';
+    mppChallenge?: Challenge.Challenge;
+    tokenOperationId?: string;
+    tokenRef?: string;
+    mppMode?: 'test' | 'live';
+    mppPaymentMethod?: string;
+    required?: PaymentRequired;
+    requirements?: PaymentRequirements;
+    createdAt: string;
+    updatedAt: string;
+    state: 'previewed' | 'signing' | 'submitted' | 'unknown' | 'completed' | 'failed';
+    paymentState: 'quoted' | 'reserved' | 'unknown' | 'confirmed' | 'rejected' | 'not_required';
+    executionState: string;
+    credentialRef?: string;
+    nonce?: string;
+    fromBlock?: string;
+    receipt?: SettleResponse | MppReceipt;
+    task?: Record<string, unknown>;
+    result?: unknown;
+    errorCode?: string;
+    rejectionEvidence?: {
+        kind: 'finalized_expired_unused';
+        checkedAt: string;
+        nonce: string;
+    };
+}
+/** One wallet ledger, one process. Unknown authorizations retain cumulative budget. */
+export declare class BuyerStore {
+    private readonly db;
+    private readonly owner?;
+    constructor(path: string);
+    close(): void;
+    private transaction;
+    get(id: string, caller: string): BuyerRecord | undefined;
+    assertMessageOwner(caller: string, messageId: string): void;
+    find(caller: string, messageId: string): BuyerRecord | undefined;
+    insert(value: Omit<BuyerRecord, 'id' | 'createdAt' | 'updatedAt' | 'state' | 'paymentState' | 'executionState'>): BuyerRecord;
+    update(id: string, patch: Partial<Pick<BuyerRecord, 'state' | 'paymentState' | 'executionState' | 'credentialRef' | 'nonce' | 'fromBlock' | 'receipt' | 'task' | 'result' | 'errorCode' | 'continuations' | 'tokenOperationId' | 'tokenRef' | 'rejectionEvidence'>>): BuyerRecord;
+    pendingTasks(): BuyerRecord[];
+    usage(currency: string): {
+        reserved: string;
+        spent: string;
+    };
+    reserve(id: string, caller: string, policy: BuyerPolicy): {
+        record: BuyerRecord;
+        fresh: boolean;
+    };
+    beginFree(id: string, caller: string): {
+        record: BuyerRecord;
+        fresh: boolean;
+    };
+    rejectBeforeSigning(id: string, caller: string, errorCode: string): BuyerRecord;
+    rejectExpiredAuthorization(id: string, caller: string): BuyerRecord;
+    confirmed(id: string, receipt: SettleResponse | MppReceipt): BuyerRecord;
+}

package/dist/commerce/buyer-store.js

@@ -0,0 +1,168 @@
+import { DatabaseSync } from 'node:sqlite';
+import { chmodSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { atomic } from './config.js';
+import { CommerceError } from './types.js';
+/** One wallet ledger, one process. Unknown authorizations retain cumulative budget. */
+export class BuyerStore {
+    db;
+    owner;
+    constructor(path) {
+        if (path !== ':memory:') {
+            mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+            this.owner = new DatabaseSync(path + '.owner.sqlite3');
+            chmodSync(path + '.owner.sqlite3', 0o600);
+            try {
+                this.owner.exec('PRAGMA busy_timeout=0; BEGIN EXCLUSIVE');
+            }
+            catch {
+                this.owner.close();
+                throw new CommerceError('store_locked', 'Buyer ledger already has an active process');
+            }
+        }
+        try {
+            this.db = new DatabaseSync(path);
+            if (path !== ':memory:')
+                chmodSync(path, 0o600);
+            this.db.exec(`PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL; PRAGMA busy_timeout=5000;
+        CREATE TABLE IF NOT EXISTS buyer_meta(version INTEGER NOT NULL);
+        INSERT INTO buyer_meta SELECT 1 WHERE NOT EXISTS(SELECT 1 FROM buyer_meta);
+        CREATE TABLE IF NOT EXISTS buyer_purchases(
+          id TEXT PRIMARY KEY, caller TEXT NOT NULL, message_id TEXT NOT NULL,
+          currency TEXT NOT NULL, amount TEXT NOT NULL, budget_state TEXT NOT NULL,
+          record_json TEXT NOT NULL, UNIQUE(caller,message_id), UNIQUE(message_id)
+        );`);
+            if (this.db.prepare('SELECT version FROM buyer_meta').get()?.version !== 1)
+                throw new CommerceError('store_version', 'Unsupported buyer ledger version');
+            // Never resume signing after a crash: no second nonce may be created.
+            for (const row of this.db.prepare('SELECT record_json FROM buyer_purchases').all()) {
+                const record = JSON.parse(String(row.record_json));
+                if (record.state === 'signing' || record.state === 'submitted')
+                    this.update(record.id, { state: 'unknown', paymentState: ['confirmed', 'not_required'].includes(record.paymentState) ? record.paymentState : 'unknown', errorCode: 'interrupted_purchase' });
+            }
+        }
+        catch (error) {
+            this.owner?.close();
+            throw error;
+        }
+    }
+    close() { this.db.close(); if (this.owner) {
+        this.owner.exec('ROLLBACK');
+        this.owner.close();
+    } }
+    transaction(fn) {
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            const result = fn();
+            this.db.exec('COMMIT');
+            return result;
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK');
+            throw error;
+        }
+    }
+    get(id, caller) {
+        const row = this.db.prepare('SELECT record_json FROM buyer_purchases WHERE id=? AND caller=?').get(id, caller);
+        return row ? JSON.parse(String(row.record_json)) : undefined;
+    }
+    assertMessageOwner(caller, messageId) {
+        const row = this.db.prepare('SELECT caller FROM buyer_purchases WHERE message_id=?').get(messageId);
+        if (row && row.caller !== caller)
+            throw new CommerceError('purchase_conflict', 'Message ID is already reserved to another caller');
+    }
+    find(caller, messageId) {
+        const row = this.db.prepare('SELECT record_json FROM buyer_purchases WHERE caller=? AND message_id=?').get(caller, messageId);
+        return row ? JSON.parse(String(row.record_json)) : undefined;
+    }
+    insert(value) {
+        return this.transaction(() => {
+            this.assertMessageOwner(value.caller, value.messageId);
+            const prior = this.find(value.caller, value.messageId);
+            if (prior) {
+                if (prior.fingerprint !== value.fingerprint)
+                    throw new CommerceError('purchase_conflict', 'Message ID already identifies another purchase');
+                return prior;
+            }
+            const now = new Date().toISOString();
+            const record = { ...value, id: randomUUID(), createdAt: now, updatedAt: now, state: 'previewed', paymentState: 'quoted', executionState: 'not_started' };
+            this.db.prepare('INSERT INTO buyer_purchases VALUES(?,?,?,?,?,?,?)').run(record.id, record.caller, record.messageId, record.quote.currency ?? '', record.quote.amount, 'none', JSON.stringify(record));
+            return record;
+        });
+    }
+    update(id, patch) {
+        const row = this.db.prepare('SELECT record_json FROM buyer_purchases WHERE id=?').get(id);
+        if (!row)
+            throw new CommerceError('purchase_not_found', 'Purchase not found');
+        const record = { ...JSON.parse(String(row.record_json)), ...patch, updatedAt: new Date().toISOString() };
+        this.db.prepare('UPDATE buyer_purchases SET record_json=? WHERE id=?').run(JSON.stringify(record), id);
+        return record;
+    }
+    pendingTasks() {
+        return this.db.prepare('SELECT record_json FROM buyer_purchases').all()
+            .map(row => JSON.parse(String(row.record_json)))
+            .filter(record => record.task?.id && ['working', 'unknown'].includes(record.executionState));
+    }
+    usage(currency) {
+        let reserved = 0n, spent = 0n;
+        for (const row of this.db.prepare("SELECT amount,budget_state FROM buyer_purchases WHERE currency=? AND budget_state!='none'").all(currency)) {
+            if (row.budget_state === 'spent')
+                spent += BigInt(String(row.amount));
+            else
+                reserved += BigInt(String(row.amount));
+        }
+        return { reserved: reserved.toString(), spent: spent.toString() };
+    }
+    reserve(id, caller, policy) {
+        return this.transaction(() => {
+            const record = this.get(id, caller);
+            if (!record)
+                throw new CommerceError('purchase_not_found', 'Purchase not found');
+            if (record.state !== 'previewed')
+                return { record, fresh: false };
+            const limit = policy.budgets.find(b => b.currency === record.quote.currency);
+            const usage = this.usage(record.quote.currency ?? '');
+            if (!limit || BigInt(usage.reserved) + BigInt(usage.spent) + atomic(record.quote.amount) > atomic(limit.maxTotal))
+                throw new CommerceError('budget_exceeded', 'Cumulative wallet budget is exhausted or reserved');
+            this.db.prepare("UPDATE buyer_purchases SET budget_state='reserved' WHERE id=?").run(id);
+            return { record: this.update(id, { state: 'signing', paymentState: 'reserved' }), fresh: true };
+        });
+    }
+    beginFree(id, caller) {
+        return this.transaction(() => {
+            const record = this.get(id, caller);
+            if (!record || record.protocol !== 'free' || record.quote.amount !== '0' || record.quote.currency !== null || record.quote.recipient !== null)
+                throw new CommerceError('free_purchase_binding', 'Invalid original free purchase');
+            if (record.state !== 'previewed')
+                return { record, fresh: false };
+            return { record: this.update(id, { state: 'submitted', paymentState: 'not_required' }), fresh: true };
+        });
+    }
+    rejectBeforeSigning(id, caller, errorCode) {
+        return this.transaction(() => {
+            const record = this.get(id, caller);
+            if (!record || record.state !== 'signing' || record.credentialRef || record.nonce)
+                throw new CommerceError('authorization_may_exist', 'Cannot release an existing or ambiguous authorization');
+            this.db.prepare("UPDATE buyer_purchases SET budget_state='none' WHERE id=? AND budget_state='reserved'").run(id);
+            return this.update(id, { state: 'failed', paymentState: 'rejected', executionState: 'not_started', errorCode });
+        });
+    }
+    rejectExpiredAuthorization(id, caller) {
+        return this.transaction(() => {
+            const record = this.get(id, caller);
+            if (!record || record.protocol === 'mpp' || record.protocol === 'free' || !record.credentialRef || !record.nonce)
+                throw new CommerceError('authorization_recovery_required', 'Original x402 authorization is required');
+            if (record.paymentState === 'confirmed')
+                return record;
+            this.db.prepare("UPDATE buyer_purchases SET budget_state='none' WHERE id=? AND budget_state='reserved'").run(id);
+            return this.update(id, { state: 'failed', paymentState: 'rejected', errorCode: 'authorization_expired_unused', rejectionEvidence: { kind: 'finalized_expired_unused', checkedAt: new Date().toISOString(), nonce: record.nonce } });
+        });
+    }
+    confirmed(id, receipt) {
+        return this.transaction(() => {
+            this.db.prepare("UPDATE buyer_purchases SET budget_state='spent' WHERE id=? AND budget_state IN ('reserved','spent')").run(id);
+            return this.update(id, { paymentState: 'confirmed', receipt });
+        });
+    }
+}

package/dist/commerce/buyer.d.ts

@@ -0,0 +1,129 @@
+import type { ClientEvmSigner } from '@x402/evm';
+import type { PaymentPayload, PaymentRequirements, SettleResponse } from '@x402/core/types';
+import { type BuyerPolicy, type Input } from './types.js';
+import { CredentialVault } from './vault.js';
+import { BuyerStore, type BuyerQuote } from './buyer-store.js';
+import { type MppBuyerOptions, type MppReceipt } from './mpp-client.js';
+export interface BuyerPreviewInput {
+    cardUrl: string;
+    messageId: string;
+    input: Input;
+    offerId: string;
+}
+export interface BuyerConfirmInput {
+    previewId: string;
+    quoteToken: string;
+    messageId: string;
+}
+export interface CommerceBuyerOptions {
+    policy: BuyerPolicy;
+    store: BuyerStore;
+    vault?: CredentialVault;
+    signer?: ClientEvmSigner;
+    mpp?: MppBuyerOptions;
+    peerTokens: Readonly<Record<string, string>>;
+    /** Override sibling /a2a only when the local wallet owner explicitly allows it. */
+    peerEndpoints?: Readonly<Record<string, string>>;
+    verifyReceipt?: (receipt: SettleResponse, payload: PaymentPayload, requirements: PaymentRequirements) => Promise<boolean>;
+    checkpoint?: (requirements: PaymentRequirements) => Promise<string>;
+    proveExpiredUnused?: (payload: PaymentPayload, requirements: PaymentRequirements) => Promise<boolean>;
+    findOriginalReceipt?: (payload: PaymentPayload, requirements: PaymentRequirements, fromBlock: string) => Promise<SettleResponse | undefined>;
+    fetchImpl?: typeof fetch;
+}
+export interface BuyerSnapshot {
+    id: string;
+    quoteToken: string;
+    messageId: string;
+    payer: string;
+    state: string;
+    quote: BuyerQuote;
+    paymentState: string;
+    executionState: string;
+    task?: Record<string, unknown>;
+    result?: unknown;
+    errorCode?: string;
+    continuation?: {
+        messageId: string;
+        state: 'pending' | 'unknown' | 'resolved';
+        input: Input;
+    };
+    receipt?: SettleResponse | MppReceipt;
+    nonce?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Independent x402 wallet; payment and execution state are deliberately separate. */
+export declare class CommerceBuyer {
+    private readonly options;
+    readonly policy: BuyerPolicy;
+    private readonly fetchImpl;
+    private readonly active;
+    private timer?;
+    private readonly previews;
+    constructor(options: CommerceBuyerOptions);
+    /** Background observation only; never signs, replays credentials or changes reservations. */
+    start(intervalMs?: number): void;
+    stop(): Promise<void>;
+    policySnapshot(): {
+        capabilities: ("free" | "x402" | "mpp")[];
+        state: string;
+        payer: string | undefined;
+        budgets: {
+            reserved: string;
+            spent: string;
+            currency: string;
+            maxTotal: string;
+            period: "cumulative";
+        }[];
+        policyVersion: 1;
+        paymentsEnabled: boolean;
+        approval: "per_purchase" | "within_preapproved_limits";
+        peers: ({
+            id: string;
+            cardUrl: string;
+            protocol: "x402" | "mpp";
+            currency: string;
+            recipient: string;
+            maxPerPurchase: string;
+        } | {
+            id: string;
+            cardUrl: string;
+            protocol: "free";
+            currency: null;
+            recipient: null;
+            maxPerPurchase: "0";
+        })[];
+    };
+    private peer;
+    private endpoint;
+    private scopedFetch;
+    private record;
+    private snapshot;
+    get(caller: string, id: string): BuyerSnapshot;
+    preview(caller: string, input: BuyerPreviewInput): Promise<BuyerSnapshot>;
+    private prepare;
+    private prepareFree;
+    private replayFree;
+    private prepareMpp;
+    private mppCredential;
+    private purchaseMpp;
+    private savedMpp;
+    private verifyMpp;
+    private replayMpp;
+    private recoverMpp;
+    private assertCurrentPolicy;
+    confirm(caller: string, input: BuyerConfirmInput): Promise<BuyerSnapshot>;
+    private exclusive;
+    private purchase;
+    private saved;
+    private verify;
+    private task;
+    private replay;
+    private client;
+    private observe;
+    continue(caller: string, id: string, input: {
+        messageId: string;
+        input: Input;
+    }): Promise<BuyerSnapshot>;
+    recover(caller: string, id: string): Promise<BuyerSnapshot>;
+}