@dexterai/x402 1.9.0 → 1.9.1

package/dist/{x402-client-BDaOwfgE.d.cts → sponsored-access-BCB2CxdG.d.cts}

@@ -1,5 +1,6 @@
 import { C as ChainAdapter, W as WalletSet } from './types-DmqH9yD8.cjs';
 import { A as AccessPassClientConfig } from './types-BQvaF8lB.cjs';
+import { SponsoredRecommendation, SponsoredAccessSettlementInfo } from '@dexterai/x402-ads-types';
 
 /**
  * x402 v2 Client
@@ -109,4 +110,70 @@ interface X402Client {
  */
 declare function createX402Client(config: X402ClientConfig): X402Client;
 
-export { type PaymentReceipt as P, type X402ClientConfig as X, type X402Client as a, createX402Client as c, getPaymentReceipt as g };
+/**
+ * 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>;
+
+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 };

package/dist/{x402-client-DIcp-PvX.d.ts → sponsored-access-H1EX6zpi.d.ts}

@@ -1,5 +1,6 @@
 import { C as ChainAdapter, W as WalletSet } from './types-ENcnkof8.js';
 import { A as AccessPassClientConfig } from './types-BQvaF8lB.js';
+import { SponsoredRecommendation, SponsoredAccessSettlementInfo } from '@dexterai/x402-ads-types';
 
 /**
  * x402 v2 Client
@@ -109,4 +110,70 @@ interface X402Client {
  */
 declare function createX402Client(config: X402ClientConfig): X402Client;
 
-export { type PaymentReceipt as P, type X402ClientConfig as X, type X402Client as a, createX402Client as c, getPaymentReceipt as g };
+/**
+ * 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>;
+
+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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dexterai/x402",
-  "version": "1.9.0",
+  "version": "1.9.1",
   "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",
@@ -52,11 +52,11 @@
   },
   "dependencies": {
     "@solana/spl-token": "^0.4.9",
+    "@dexterai/x402-ads-types": "^0.1.0",
     "@solana/web3.js": "^1.98.0",
     "tiktoken": "^1.0.22"
   },
   "devDependencies": {
-    "@dexterai/x402-ads-types": "^0.1.0",
     "@types/aws-lambda": "^8.10.161",
     "@types/express": "^5.0.6",
     "@types/node": "^22.10.0",
@@ -70,16 +70,12 @@
     "vitest": "^2.1.8"
   },
   "peerDependencies": {
-    "@dexterai/x402-ads-types": ">=0.1.0",
     "@solana/wallet-adapter-base": "^0.9.0",
     "react": "^18.0.0 || ^19.0.0",
     "stripe": "^20.0.0",
     "viem": "^2.0.0"
   },
   "peerDependenciesMeta": {
-    "@dexterai/x402-ads-types": {
-      "optional": true
-    },
     "@solana/wallet-adapter-base": {
       "optional": true
     },