@dexterai/x402 3.8.0 → 3.9.0

package/dist/{sponsored-access-D7H-womP.d.cts → x402-client-CzseAnIt.d.ts}

@@ -1,9 +1,83 @@
-import { C as ChainAdapter, W as WalletSet, A as AccessPassClientConfig, P as PaymentAccept } from './types-htvWHuW3.cjs';
 import { SponsoredRecommendation, SponsoredAccessSettlementInfo } from '@dexterai/x402-ads-types';
+import { C as ChainAdapter, W as WalletSet, A as AccessPassClientConfig, P as PaymentAccept, S as SettlementProbe } from './types-RxdlGPaG.js';
+
+/**
+ * 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.
@@ -58,6 +132,9 @@ interface PaymentReceipt {
 declare function getPaymentReceipt(response: Response): PaymentReceipt | undefined;
 /**
  * Client configuration
+ *
+ * @deprecated Slated for removal in `@dexterai/x402` 5.0 alongside
+ * `createX402Client` and `X402Client`. Use `PayAndFetchOptions` instead.
  */
 interface X402ClientConfig {
     /**
@@ -121,6 +198,24 @@ interface X402ClientConfig {
      * ```
      */
     onPaymentRequired?: (requirements: PaymentAccept) => boolean | Promise<boolean>;
+    /**
+     * Called the instant the signed payment authorization is sent to the
+     * merchant — after `buildTransaction`, immediately before the paid retry
+     * fetch. This is the point past which a timeout can no longer be treated
+     * as "no money moved": the facilitator may settle at any time once the
+     * authorization is in its hands.
+     *
+     * The callback receives the `accept` it is paying against (network, asset,
+     * amount, payTo) and the `settlementProbe` the adapter produced (or
+     * `undefined` for schemes with no on-chain confirmation). `payAndFetch`
+     * uses this to mark a payment as dispatched — so a post-payment abort is
+     * not misreported as a plain timeout — and keeps the probe so it can
+     * confirm settlement on-chain if the merchant never responds.
+     *
+     * Fire-and-forget — the return value is ignored, and a throw is swallowed
+     * (the payment proceeds regardless). Do not do slow work here.
+     */
+    onPaymentDispatched?: (accept: PaymentAccept, settlementProbe?: SettlementProbe) => void;
     /**
      * Maximum retry attempts for transient failures (network errors, 502/503).
      * Does not cause double payments — EIP-3009 nonces prevent replay.
@@ -135,6 +230,9 @@ interface X402ClientConfig {
 }
 /**
  * x402 Client interface
+ *
+ * @deprecated Slated for removal in `@dexterai/x402` 5.0. Use `payAndFetch`
+ * directly instead of constructing a client object.
  */
 interface X402Client {
     /**
@@ -145,73 +243,26 @@ interface X402Client {
 }
 /**
  * Create an x402 v2 client
- */
-declare function createX402Client(config: X402ClientConfig): X402Client;
-
-/**
- * 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`.
+ * @deprecated Slated for removal in `@dexterai/x402` 5.0 (~6 months out — long
+ * cycle because of real production consumers). Use `payAndFetch` from
+ * `@dexterai/x402/client` instead — it's version-agnostic across x402 v1 and
+ * v2 and returns a discriminated union for cleaner error handling.
  *
- * @example
+ * Migration:
  * ```typescript
- * import { wrapFetch, getSponsoredRecommendations, fireImpressionBeacon } from '@dexterai/x402/client';
- *
- * const x402Fetch = wrapFetch(fetch, { walletPrivateKey: key });
- * const response = await x402Fetch('https://api.example.com/data');
+ * // Before
+ * const client = createX402Client({ wallets });
+ * const res = await client.fetch(url);
  *
- * const recs = getSponsoredRecommendations(response);
- * if (recs) {
- *   console.log('Sponsored:', recs.map(r => `${r.sponsor}: ${r.description}`));
- *   await fireImpressionBeacon(response); // Confirm delivery to ad network
+ * // After
+ * import { payAndFetch } from '@dexterai/x402/client';
+ * const result = await payAndFetch(url, undefined, wallets);
+ * if (result.ok) {
+ *   const res = result.response;
  * }
  * ```
  */
+declare function createX402Client(config: X402ClientConfig): X402Client;
 
-/**
- * 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>;
-
-export { type PaymentReceipt as P, type X402ClientConfig as X, type X402Client as a, getSponsoredRecommendations as b, createX402Client as c, getSponsoredAccessInfo as d, fireImpressionBeacon as f, getPaymentReceipt as g };
+export { type PaymentReceipt as P, type X402ClientConfig as X, getSponsoredAccessInfo as a, getPaymentReceipt as b, createX402Client as c, type X402Client as d, fireImpressionBeacon as f, getSponsoredRecommendations as g };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dexterai/x402",
-  "version": "3.8.0",
+  "version": "3.9.0",
   "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, SKALE.",
   "author": "Dexter",
   "license": "MIT",