@dexterai/x402 6.0.0 → 6.0.2

package/dist/{types-BvK5UjA9.d.ts → types-zImyINj3.d.ts}

@@ -1,5 +1,6 @@
-import { W as WalletSet } from './types-C08JT9MG.js';
+import { W as WalletSet } from './types-Ds9IUnXG.js';
 import { T as Tab } from './types-D0IFR4Ro.js';
+import { P as PaymentReceipt } from './x402-client-Cil4Tmqy.js';
 
 /**
  * Shared contract for the x402 version seam. Both the v1 and v2 strategy
@@ -34,6 +35,8 @@ interface PaymentChallenge {
     x402Version: 1 | 2;
     options: ChallengeOption[];
     resourceUrl?: string;
+    /** Extension requirements advertised by the merchant. */
+    extensions?: Record<string, unknown>;
 }
 /**
  * Result of a paid fetch. Never throws for an expected failure.
@@ -67,6 +70,8 @@ type PayResult = {
     amountPaid: string;
     network: NetworkRef;
     txSignature?: string;
+    /** Merchant settlement evidence, when a receipt was returned. */
+    paymentReceipt?: PaymentReceipt;
 } | {
     ok: true;
     paid: false;
@@ -80,18 +85,27 @@ type PayResult = {
     /** The merchant ACCEPTED the payment shape but their own settlement
      *  failed (their facilitator errored). Not our payload — a
      *  merchant-side defect. `detail` carries their verbatim error. */
-     | 'settlement_failed' | 'no_payment_options'
+     | 'settlement_failed'
+    /** Settlement succeeded, but the merchant returned an unsuccessful HTTP
+     *  response. Recover the same result; another authorization can charge again. */
+     | 'delivery_failed' | 'no_payment_options'
     /** No payment was sent before the deadline — the unpaid probe (or
      *  build/sign) ran past the pre-payment timeout. No money moved;
      *  safe to retry. */
      | 'timeout'
-    /** The payment authorization WAS sent to the merchant, the merchant
-     *  did not respond before the deadline, and settlement could not be
-     *  confirmed. The payment MAY have settled on-chain. DO NOT
+    /** The payment authorization WAS sent, but settlement could not be
+     *  confirmed: the response may be absent, pending, malformed or
+     *  inconsistent with the dispatched payment. It MAY have settled. DO NOT
      *  blind-retry — a retry signs a fresh authorization and can pay
      *  again. `detail` explains the state. */
      | 'payment_unconfirmed' | 'budget_exceeded' | 'error';
     detail?: string;
+    /** Original response, retained even when HTTP succeeded but settlement did not. */
+    response?: Response;
+    /** Transaction identifier reported by the merchant; not proof of settlement. */
+    txSignature?: string;
+    /** Saved settlement evidence for recovery of this same payment. */
+    paymentReceipt?: PaymentReceipt;
 };
 
 /** Options for a paid fetch. */

package/dist/x402-client-Cil4Tmqy.d.cts

@@ -0,0 +1,93 @@
+/**
+ * x402 v2 Client
+ *
+ * `createX402Client`, `X402Client`, and `X402ClientConfig` are
+ * @deprecated — slated for removal in `@dexterai/x402` 5.0 (~6 months out;
+ * longer cycle than the 4.0 batch because there are real consumers). Use
+ * `payAndFetch` from `@dexterai/x402/client` instead — it's the version-
+ * agnostic 2026+ client with a discriminated-union return type. The
+ * `getPaymentReceipt` helper and `PaymentReceipt` type in this file are NOT
+ * deprecated; they continue to support receipt-reading on any paid response.
+ *
+ * Chain-agnostic client for x402 v2 payments.
+ * Automatically detects 402 responses, finds a matching payment option,
+ * builds the transaction with the appropriate chain adapter, and retries.
+ *
+ * @example
+ * ```typescript
+ * import { createX402Client } from '@dexterai/x402/client';
+ * import { createSolanaAdapter, createEvmAdapter } from '@dexterai/x402/adapters';
+ *
+ * const client = createX402Client({
+ *   adapters: [createSolanaAdapter(), createEvmAdapter()],
+ *   wallets: {
+ *     solana: solanaWallet,
+ *     evm: evmWallet,
+ *   },
+ * });
+ *
+ * const response = await client.fetch(url);
+ * ```
+ */
+
+/**
+ * Settlement evidence attached to a response after payment dispatch.
+ * Access via `getPaymentReceipt(response)`.
+ */
+interface PaymentReceipt {
+    /** Whether settlement succeeded */
+    success?: boolean;
+    /** Transaction signature/hash */
+    transaction?: string;
+    /** CAIP-2 network */
+    network?: string;
+    /** Payer address */
+    payer?: string;
+    /** Protocol extensions (e.g., sponsored-access recommendations) */
+    extensions?: Record<string, unknown>;
+    /** Merchant-reported settlement error. This alone does not prove no debit occurred. */
+    errorReason?: string;
+    errorCode?: string;
+    errorMessage?: string;
+    /** Interpretation of the receipt for the exact dispatched requirements. */
+    settlementStatus?: 'settled' | 'pending' | 'failed' | 'unconfirmed';
+    /** Amount authorized for this attempt, whether or not settlement is confirmed. */
+    attemptedAmountAtomic?: string;
+    /**
+     * Amount actually paid, in atomic units (e.g. '10000' for 0.01 USDC).
+     * Set from the dispatched requirement only when the matching receipt reports
+     * successful settlement. An unknown outcome exposes attemptedAmountAtomic.
+     */
+    amountAtomic?: string;
+    /**
+     * Decimals of the paid asset, so `amountAtomic` can be converted to a human
+     * amount: `Number(amountAtomic) / 10 ** assetDecimals`.
+     */
+    assetDecimals?: number;
+}
+/**
+ * Get the x402 payment receipt from a response, or undefined if none.
+ */
+declare function getPaymentReceipt(response: Response): PaymentReceipt | undefined;
+interface PaymentReceiptAttempt {
+    network: string;
+    amountAtomic: string;
+    assetDecimals?: number;
+}
+/** Capture a dispatched payment's response without consuming its body or issuing another request. */
+declare function capturePaymentReceipt(response: Response, attempt: PaymentReceiptAttempt): PaymentReceipt;
+/**
+ * x402 Client interface
+ *
+ * @deprecated Slated for removal in `@dexterai/x402` 5.0. Use `payAndFetch`
+ * directly instead of constructing a client object.
+ */
+interface X402Client {
+    /**
+     * Fetch with automatic x402 payment handling.
+     * If the server returns 402, handles payment automatically and retries.
+     */
+    fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
+}
+
+export { type PaymentReceipt as P, type X402Client as X, type PaymentReceiptAttempt as a, capturePaymentReceipt as c, getPaymentReceipt as g };

package/dist/x402-client-Cil4Tmqy.d.ts

@@ -0,0 +1,93 @@
+/**
+ * x402 v2 Client
+ *
+ * `createX402Client`, `X402Client`, and `X402ClientConfig` are
+ * @deprecated — slated for removal in `@dexterai/x402` 5.0 (~6 months out;
+ * longer cycle than the 4.0 batch because there are real consumers). Use
+ * `payAndFetch` from `@dexterai/x402/client` instead — it's the version-
+ * agnostic 2026+ client with a discriminated-union return type. The
+ * `getPaymentReceipt` helper and `PaymentReceipt` type in this file are NOT
+ * deprecated; they continue to support receipt-reading on any paid response.
+ *
+ * Chain-agnostic client for x402 v2 payments.
+ * Automatically detects 402 responses, finds a matching payment option,
+ * builds the transaction with the appropriate chain adapter, and retries.
+ *
+ * @example
+ * ```typescript
+ * import { createX402Client } from '@dexterai/x402/client';
+ * import { createSolanaAdapter, createEvmAdapter } from '@dexterai/x402/adapters';
+ *
+ * const client = createX402Client({
+ *   adapters: [createSolanaAdapter(), createEvmAdapter()],
+ *   wallets: {
+ *     solana: solanaWallet,
+ *     evm: evmWallet,
+ *   },
+ * });
+ *
+ * const response = await client.fetch(url);
+ * ```
+ */
+
+/**
+ * Settlement evidence attached to a response after payment dispatch.
+ * Access via `getPaymentReceipt(response)`.
+ */
+interface PaymentReceipt {
+    /** Whether settlement succeeded */
+    success?: boolean;
+    /** Transaction signature/hash */
+    transaction?: string;
+    /** CAIP-2 network */
+    network?: string;
+    /** Payer address */
+    payer?: string;
+    /** Protocol extensions (e.g., sponsored-access recommendations) */
+    extensions?: Record<string, unknown>;
+    /** Merchant-reported settlement error. This alone does not prove no debit occurred. */
+    errorReason?: string;
+    errorCode?: string;
+    errorMessage?: string;
+    /** Interpretation of the receipt for the exact dispatched requirements. */
+    settlementStatus?: 'settled' | 'pending' | 'failed' | 'unconfirmed';
+    /** Amount authorized for this attempt, whether or not settlement is confirmed. */
+    attemptedAmountAtomic?: string;
+    /**
+     * Amount actually paid, in atomic units (e.g. '10000' for 0.01 USDC).
+     * Set from the dispatched requirement only when the matching receipt reports
+     * successful settlement. An unknown outcome exposes attemptedAmountAtomic.
+     */
+    amountAtomic?: string;
+    /**
+     * Decimals of the paid asset, so `amountAtomic` can be converted to a human
+     * amount: `Number(amountAtomic) / 10 ** assetDecimals`.
+     */
+    assetDecimals?: number;
+}
+/**
+ * Get the x402 payment receipt from a response, or undefined if none.
+ */
+declare function getPaymentReceipt(response: Response): PaymentReceipt | undefined;
+interface PaymentReceiptAttempt {
+    network: string;
+    amountAtomic: string;
+    assetDecimals?: number;
+}
+/** Capture a dispatched payment's response without consuming its body or issuing another request. */
+declare function capturePaymentReceipt(response: Response, attempt: PaymentReceiptAttempt): PaymentReceipt;
+/**
+ * x402 Client interface
+ *
+ * @deprecated Slated for removal in `@dexterai/x402` 5.0. Use `payAndFetch`
+ * directly instead of constructing a client object.
+ */
+interface X402Client {
+    /**
+     * Fetch with automatic x402 payment handling.
+     * If the server returns 402, handles payment automatically and retries.
+     */
+    fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
+}
+
+export { type PaymentReceipt as P, type X402Client as X, type PaymentReceiptAttempt as a, capturePaymentReceipt as c, getPaymentReceipt as g };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dexterai/x402",
-  "version": "6.0.0",
+  "version": "6.0.2",
   "description": "Full-stack x402 SDK - add paid API monetization to any endpoint. Express middleware, React hooks, Access Pass, dynamic pricing. Solana, Base, Polygon, Arbitrum, Optimism, Avalanche, World Chain, Monad, Robinhood Chain, SKALE.",
   "author": "Dexter",
   "license": "MIT",
@@ -84,7 +84,7 @@
   },
   "dependencies": {
     "@dexterai/x402-ads-types": "^0.2.0",
-    "@dexterai/x402-core": "^1.4.0",
+    "@dexterai/x402-core": "^1.5.2",
     "@noble/curves": "^1.9.7",
     "@noble/hashes": "^1.8.0",
     "@solana/spl-token": "^0.4.9",

package/dist/x402-client-B8zdDeat.d.cts

@@ -1,146 +0,0 @@
-import { SponsoredAccessSettlementInfo, SponsoredRecommendation } from '@dexterai/x402-ads-types';
-
-/**
- * Sponsored Access (Ads for Agents) — Client Helpers
- *
- * Extract sponsored recommendations from x402 payment receipts and
- * fire impression beacons to confirm delivery to the ad network.
- *
- * Recommendations are injected by the facilitator after settlement
- * via the `extensions["sponsored-access"]` field. Publishers who enable
- * `sponsoredAccess: true` in their middleware also inject them into
- * the JSON response body as `_x402_sponsored`.
- *
- * @example
- * ```typescript
- * import { wrapFetch, getSponsoredRecommendations, fireImpressionBeacon } from '@dexterai/x402/client';
- *
- * const x402Fetch = wrapFetch(fetch, { walletPrivateKey: key });
- * const response = await x402Fetch('https://api.example.com/data');
- *
- * const recs = getSponsoredRecommendations(response);
- * if (recs) {
- *   console.log('Sponsored:', recs.map(r => `${r.sponsor}: ${r.description}`));
- *   await fireImpressionBeacon(response); // Confirm delivery to ad network
- * }
- * ```
- */
-
-/**
- * Extract the full sponsored-access extension data from a payment receipt.
- * Returns undefined if no sponsored-access extension is present.
- */
-declare function getSponsoredAccessInfo(response: Response): SponsoredAccessSettlementInfo | undefined;
-/**
- * Extract sponsored recommendations from an x402 payment response.
- * Returns the recommendations array, or undefined if none present.
- *
- * @example
- * ```typescript
- * const recs = getSponsoredRecommendations(response);
- * if (recs) {
- *   for (const rec of recs) {
- *     console.log(`${rec.sponsor}: ${rec.description} — ${rec.resourceUrl}`);
- *   }
- * }
- * ```
- */
-declare function getSponsoredRecommendations(response: Response): SponsoredRecommendation[] | undefined;
-/**
- * Fire the impression beacon to confirm recommendation delivery to the ad network.
- * This is a fire-and-forget GET request — failures are silently ignored.
- *
- * Call this after you've read the recommendations to help the ad network
- * track delivery rates and verify impressions.
- *
- * @returns true if the beacon was fired (regardless of response), false if no beacon URL
- *
- * @example
- * ```typescript
- * const recs = getSponsoredRecommendations(response);
- * if (recs) {
- *   // Process recommendations...
- *   await fireImpressionBeacon(response);
- * }
- * ```
- */
-declare function fireImpressionBeacon(response: Response): Promise<boolean>;
-
-/**
- * x402 v2 Client
- *
- * `createX402Client`, `X402Client`, and `X402ClientConfig` are
- * @deprecated — slated for removal in `@dexterai/x402` 5.0 (~6 months out;
- * longer cycle than the 4.0 batch because there are real consumers). Use
- * `payAndFetch` from `@dexterai/x402/client` instead — it's the version-
- * agnostic 2026+ client with a discriminated-union return type. The
- * `getPaymentReceipt` helper and `PaymentReceipt` type in this file are NOT
- * deprecated; they continue to support receipt-reading on any paid response.
- *
- * Chain-agnostic client for x402 v2 payments.
- * Automatically detects 402 responses, finds a matching payment option,
- * builds the transaction with the appropriate chain adapter, and retries.
- *
- * @example
- * ```typescript
- * import { createX402Client } from '@dexterai/x402/client';
- * import { createSolanaAdapter, createEvmAdapter } from '@dexterai/x402/adapters';
- *
- * const client = createX402Client({
- *   adapters: [createSolanaAdapter(), createEvmAdapter()],
- *   wallets: {
- *     solana: solanaWallet,
- *     evm: evmWallet,
- *   },
- * });
- *
- * const response = await client.fetch(url);
- * ```
- */
-
-/**
- * Payment receipt attached to a successful x402 response.
- * Access via `getPaymentReceipt(response)`.
- */
-interface PaymentReceipt {
-    /** Whether settlement succeeded */
-    success?: boolean;
-    /** Transaction signature/hash */
-    transaction?: string;
-    /** CAIP-2 network */
-    network?: string;
-    /** Payer address */
-    payer?: string;
-    /** Protocol extensions (e.g., sponsored-access recommendations) */
-    extensions?: Record<string, unknown>;
-    /**
-     * Amount actually paid, in atomic units (e.g. '10000' for 0.01 USDC).
-     * Sourced from the payment requirement the client settled — the facilitator's
-     * PAYMENT-RESPONSE receipt does not echo the amount, so the client records it.
-     */
-    amountAtomic?: string;
-    /**
-     * Decimals of the paid asset, so `amountAtomic` can be converted to a human
-     * amount: `Number(amountAtomic) / 10 ** assetDecimals`.
-     */
-    assetDecimals?: number;
-}
-/**
- * Get the x402 payment receipt from a response, or undefined if none.
- */
-declare function getPaymentReceipt(response: Response): PaymentReceipt | undefined;
-/**
- * x402 Client interface
- *
- * @deprecated Slated for removal in `@dexterai/x402` 5.0. Use `payAndFetch`
- * directly instead of constructing a client object.
- */
-interface X402Client {
-    /**
-     * Fetch with automatic x402 payment handling.
-     * If the server returns 402, handles payment automatically and retries.
-     */
-    fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
-}
-
-export { type PaymentReceipt as P, type X402Client as X, getSponsoredAccessInfo as a, getSponsoredRecommendations as b, fireImpressionBeacon as f, getPaymentReceipt as g };

package/dist/x402-client-B8zdDeat.d.ts

@@ -1,146 +0,0 @@
-import { SponsoredAccessSettlementInfo, SponsoredRecommendation } from '@dexterai/x402-ads-types';
-
-/**
- * Sponsored Access (Ads for Agents) — Client Helpers
- *
- * Extract sponsored recommendations from x402 payment receipts and
- * fire impression beacons to confirm delivery to the ad network.
- *
- * Recommendations are injected by the facilitator after settlement
- * via the `extensions["sponsored-access"]` field. Publishers who enable
- * `sponsoredAccess: true` in their middleware also inject them into
- * the JSON response body as `_x402_sponsored`.
- *
- * @example
- * ```typescript
- * import { wrapFetch, getSponsoredRecommendations, fireImpressionBeacon } from '@dexterai/x402/client';
- *
- * const x402Fetch = wrapFetch(fetch, { walletPrivateKey: key });
- * const response = await x402Fetch('https://api.example.com/data');
- *
- * const recs = getSponsoredRecommendations(response);
- * if (recs) {
- *   console.log('Sponsored:', recs.map(r => `${r.sponsor}: ${r.description}`));
- *   await fireImpressionBeacon(response); // Confirm delivery to ad network
- * }
- * ```
- */
-
-/**
- * Extract the full sponsored-access extension data from a payment receipt.
- * Returns undefined if no sponsored-access extension is present.
- */
-declare function getSponsoredAccessInfo(response: Response): SponsoredAccessSettlementInfo | undefined;
-/**
- * Extract sponsored recommendations from an x402 payment response.
- * Returns the recommendations array, or undefined if none present.
- *
- * @example
- * ```typescript
- * const recs = getSponsoredRecommendations(response);
- * if (recs) {
- *   for (const rec of recs) {
- *     console.log(`${rec.sponsor}: ${rec.description} — ${rec.resourceUrl}`);
- *   }
- * }
- * ```
- */
-declare function getSponsoredRecommendations(response: Response): SponsoredRecommendation[] | undefined;
-/**
- * Fire the impression beacon to confirm recommendation delivery to the ad network.
- * This is a fire-and-forget GET request — failures are silently ignored.
- *
- * Call this after you've read the recommendations to help the ad network
- * track delivery rates and verify impressions.
- *
- * @returns true if the beacon was fired (regardless of response), false if no beacon URL
- *
- * @example
- * ```typescript
- * const recs = getSponsoredRecommendations(response);
- * if (recs) {
- *   // Process recommendations...
- *   await fireImpressionBeacon(response);
- * }
- * ```
- */
-declare function fireImpressionBeacon(response: Response): Promise<boolean>;
-
-/**
- * x402 v2 Client
- *
- * `createX402Client`, `X402Client`, and `X402ClientConfig` are
- * @deprecated — slated for removal in `@dexterai/x402` 5.0 (~6 months out;
- * longer cycle than the 4.0 batch because there are real consumers). Use
- * `payAndFetch` from `@dexterai/x402/client` instead — it's the version-
- * agnostic 2026+ client with a discriminated-union return type. The
- * `getPaymentReceipt` helper and `PaymentReceipt` type in this file are NOT
- * deprecated; they continue to support receipt-reading on any paid response.
- *
- * Chain-agnostic client for x402 v2 payments.
- * Automatically detects 402 responses, finds a matching payment option,
- * builds the transaction with the appropriate chain adapter, and retries.
- *
- * @example
- * ```typescript
- * import { createX402Client } from '@dexterai/x402/client';
- * import { createSolanaAdapter, createEvmAdapter } from '@dexterai/x402/adapters';
- *
- * const client = createX402Client({
- *   adapters: [createSolanaAdapter(), createEvmAdapter()],
- *   wallets: {
- *     solana: solanaWallet,
- *     evm: evmWallet,
- *   },
- * });
- *
- * const response = await client.fetch(url);
- * ```
- */
-
-/**
- * Payment receipt attached to a successful x402 response.
- * Access via `getPaymentReceipt(response)`.
- */
-interface PaymentReceipt {
-    /** Whether settlement succeeded */
-    success?: boolean;
-    /** Transaction signature/hash */
-    transaction?: string;
-    /** CAIP-2 network */
-    network?: string;
-    /** Payer address */
-    payer?: string;
-    /** Protocol extensions (e.g., sponsored-access recommendations) */
-    extensions?: Record<string, unknown>;
-    /**
-     * Amount actually paid, in atomic units (e.g. '10000' for 0.01 USDC).
-     * Sourced from the payment requirement the client settled — the facilitator's
-     * PAYMENT-RESPONSE receipt does not echo the amount, so the client records it.
-     */
-    amountAtomic?: string;
-    /**
-     * Decimals of the paid asset, so `amountAtomic` can be converted to a human
-     * amount: `Number(amountAtomic) / 10 ** assetDecimals`.
-     */
-    assetDecimals?: number;
-}
-/**
- * Get the x402 payment receipt from a response, or undefined if none.
- */
-declare function getPaymentReceipt(response: Response): PaymentReceipt | undefined;
-/**
- * x402 Client interface
- *
- * @deprecated Slated for removal in `@dexterai/x402` 5.0. Use `payAndFetch`
- * directly instead of constructing a client object.
- */
-interface X402Client {
-    /**
-     * Fetch with automatic x402 payment handling.
-     * If the server returns 402, handles payment automatically and retries.
-     */
-    fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
-}
-
-export { type PaymentReceipt as P, type X402Client as X, getSponsoredAccessInfo as a, getSponsoredRecommendations as b, fireImpressionBeacon as f, getPaymentReceipt as g };