powertools-x402 0.1.0 → 0.1.2

package/README.md

@@ -16,9 +16,11 @@ Requires Node 18+. `@aws-lambda-powertools/event-handler` is a peer dependency,
 
 - No payment attached? The caller gets a 402 with signed payment requirements
 - Payment attached? It gets verified with a facilitator before your handler runs
-- Settlement happens after your handler succeeds. If it throws or returns an error status, the caller is never charged
+- With the default exact payment flow, settlement happens after your handler succeeds. If the handler throws or returns an error status, settlement does not occur
 - Verified payment details (payer, amount, network) are available in the request store
 
+One contract to understand before you ship: in the default exact flow, verify happens before your handler and settlement happens after. That's the right fit for work that can safely run before the money moves, like inference, generation, and data retrieval. It is not a transaction around your business logic. If your handler performs an irreversible side effect and settlement fails afterward, the work already happened. Keep that kind of work reversible or reconcilable, or handle it with your own orchestration.
+
 ## Usage
 
 ### Charge for a route
@@ -50,6 +52,8 @@ app.post(
 export const handler = (event: unknown, context: Context) => app.resolve(event, context);
 ```
 
+Dollar prices settle in USDC on the route's network. `'$0.01'` on Base Sepolia charges 0.01 USDC.
+
 ### Read payment details in the handler
 
 ```ts
@@ -74,22 +78,50 @@ const x402 = createX402({
 
 This emits `PaymentRequired`, `PaymentRejected`, `PaymentVerified`, `PaymentSettled`, `PaymentCancelled`, and `SettlementFailed` counts under the `x402` namespace. Metrics publish immediately, so there's no `publishStoredMetrics()` call to remember. Pass your own `metrics` instance if you want a different namespace.
 
-### Use an authenticated facilitator
+### Settle on mainnet with the Coinbase facilitator
+
+The free `x402.org` facilitator is testnet only. Mainnet payments settle through the [Coinbase Developer Platform](https://portal.cdp.coinbase.com/) facilitator:
+
+```bash
+npm install @coinbase/x402
+```
 
 ```ts
+import { coinbaseFacilitator } from 'powertools-x402/coinbase';
+
 const x402 = createX402({
-  facilitator: {
-    url: 'https://facilitator.example.com',
-    createAuthHeaders: async () => {
-      const headers = { Authorization: `Bearer ${token}` };
-      return { verify: headers, settle: headers, supported: headers };
-    },
-  },
+  facilitator: coinbaseFacilitator(), // reads CDP_API_KEY_ID and CDP_API_KEY_SECRET
   network: 'eip155:8453', // Base mainnet
   payTo: process.env.PAY_TO!,
 });
 ```
 
+Using a different facilitator? Pass `{ url, createAuthHeaders }` straight through the `facilitator` option.
+
+### Settle into your Stripe balance
+
+Stripe supports x402 through [machine payments](https://docs.stripe.com/payments/machine/x402). Payments settle through the Coinbase facilitator into a Stripe crypto deposit address, and each settled payment is recorded as a Stripe PaymentIntent. Funds land in your Stripe balance next to your card payments.
+
+```bash
+npm install stripe @coinbase/x402
+```
+
+```ts
+import { createStripeX402 } from 'powertools-x402/stripe';
+
+// Reads STRIPE_SECRET_KEY, STRIPE_DEPOSIT_ADDRESS, CDP_API_KEY_ID, and CDP_API_KEY_SECRET
+const x402 = createStripeX402();
+
+app.post('/paid', [x402.paid({ price: '$0.01' })], async () => ({ foo: 'bar' }));
+```
+
+Prefer explicit config? Pass `depositAddress`, `stripeSecretKey` (or your own `stripe` client), and `cdpApiKeyId`/`cdpApiKeySecret` directly. Every other `createX402` option works here too.
+
+A couple things to know:
+
+- Create your deposit address once with `POST /v1/crypto/deposit_addresses` and store it. Keep that call off your request path.
+- This uses Stripe's `2026-05-27.preview` API version, and you'll need the Stablecoins and Crypto payment method approved on your Stripe account.
+
 ### Accept multiple payment options on one route
 
 ```ts
@@ -103,6 +135,22 @@ x402.paid({
 
 Want to take payments on non-EVM networks? Register additional schemes with the `schemes` option on `createX402`.
 
+### Price in a specific token
+
+Dollar strings are shorthand for USDC. To pin the exact asset yourself, pass atomic units and the token address:
+
+```ts
+x402.paid({
+  price: {
+    amount: '10000', // atomic units, USDC has 6 decimals
+    asset: '0x036CbD53842c5426634e7929541eC2318f3dCF7e', // USDC on Base Sepolia
+    extra: { name: 'USDC', version: '2' }, // EIP-712 domain the payer signs against
+  },
+});
+```
+
+The same shape works for any EIP-3009 token. Set `extra` to the token's EIP-712 domain.
+
 ### Let some callers through free
 
 ```ts
@@ -129,23 +177,25 @@ x402.paid({
 
 ### Test your routes without a network
 
-The `facilitator` option takes any object with `verify`, `settle`, and `getSupported`, so your tests never touch the network:
+Import from `powertools-x402/testing` and your tests never touch the network. `stubFacilitator()` approves every payment, and `testPayer()` signs real payments with a throwaway account so you can test the paid path end to end:
 
 ```ts
-const facilitator = {
-  getSupported: async () => ({
-    kinds: [{ x402Version: 2, scheme: 'exact', network: 'eip155:84532' }],
-    extensions: [],
-    signers: {},
-  }),
-  verify: async () => ({ isValid: true, payer: '0xPayer' }),
-  settle: async () => ({ success: true, transaction: '0xTx', network: 'eip155:84532' }),
-};
+import { stubFacilitator, testPayer } from 'powertools-x402/testing';
+
+const facilitator = stubFacilitator(); // defaults to Base Sepolia
+const x402 = createX402({
+  facilitator,
+  network: 'eip155:84532',
+  payTo: '0x209693Bc6afc0C5328bA36FaF03C514EF312287C',
+});
 
-const x402 = createX402({ facilitator, network: 'eip155:84532', payTo: '0xYou' });
+// 402 challenge, then pay it and assert on your handler's behavior
+const payer = testPayer();
+const challenge = await app.resolve(event('POST', '/paid'), context);
+const paid = await app.resolve(event('POST', '/paid', await payer.payFor(challenge)), context);
 ```
 
-Drive your router with API Gateway events through `app.resolve(event, context)`. Check out [test/middleware.test.ts](test/middleware.test.ts) for full round trips, including client-side payment signing.
+Spy on `facilitator.verify` or `facilitator.settle` to assert calls or force failures. `payFor` also accepts fetch `Response` objects. And if you'd rather roll your own facilitator stub, it's any object with `verify`, `settle`, and `getSupported`.
 
 ### Pay for a request (client side)
 
@@ -178,6 +228,7 @@ Need testnet USDC? Grab some from the [Circle faucet](https://faucet.circle.com/
 
 - [example/handler.ts](example/handler.ts) - lambdalith with free and paid routes
 - [example/client.ts](example/client.ts) - paying client, step by step
+- [example/stripe.ts](example/stripe.ts) - settle x402 payments into your Stripe balance
 - [example/template.yaml](example/template.yaml) - SAM deploy (esbuild, ESM, HTTP API)
 
 ## License

package/dist/chunk-D46V2DLG.js

@@ -0,0 +1,211 @@
+// src/index.ts
+import { Metrics } from "@aws-lambda-powertools/metrics";
+import {
+  HTTPFacilitatorClient,
+  x402HTTPResourceServer,
+  x402ResourceServer
+} from "@x402/core/server";
+import { registerExactEvmScheme } from "@x402/evm/exact/server";
+
+// src/adapter.ts
+var PowertoolsAdapter = class {
+  constructor(request) {
+    this.request = request;
+  }
+  request;
+  getHeader(name) {
+    return this.request.headers.get(name) ?? void 0;
+  }
+  getMethod() {
+    return this.request.method;
+  }
+  getPath() {
+    return new URL(this.request.url).pathname;
+  }
+  getUrl() {
+    return this.request.url;
+  }
+  getAcceptHeader() {
+    return this.request.headers.get("accept") ?? "";
+  }
+  getUserAgent() {
+    return this.request.headers.get("user-agent") ?? "";
+  }
+  getQueryParams() {
+    const params = new URL(this.request.url).searchParams;
+    const result = {};
+    for (const key of new Set(params.keys())) {
+      const values = params.getAll(key);
+      result[key] = values.length === 1 ? values[0] : values;
+    }
+    return result;
+  }
+  getQueryParam(name) {
+    const values = new URL(this.request.url).searchParams.getAll(name);
+    if (values.length === 0) return void 0;
+    return values.length === 1 ? values[0] : values;
+  }
+  async getBody() {
+    try {
+      return await this.request.clone().json();
+    } catch {
+      return void 0;
+    }
+  }
+};
+
+// src/facilitator.ts
+var CachingFacilitatorClient = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  #supported;
+  verify(payload, requirements) {
+    return this.client.verify(payload, requirements);
+  }
+  settle(payload, requirements) {
+    return this.client.settle(payload, requirements);
+  }
+  getSupported() {
+    this.#supported ??= this.client.getSupported().catch((error) => {
+      this.#supported = void 0;
+      throw error;
+    });
+    return this.#supported;
+  }
+};
+
+// src/index.ts
+var toFacilitatorClient = (facilitator) => {
+  if (typeof facilitator === "string") return new HTTPFacilitatorClient({ url: facilitator });
+  if ("getSupported" in facilitator) return facilitator;
+  return new HTTPFacilitatorClient(facilitator);
+};
+var toResponse = ({ status, headers, body, isHtml }) => new Response(isHtml ? String(body ?? "") : JSON.stringify(body ?? {}), { status, headers });
+function createX402(options) {
+  const facilitator = new CachingFacilitatorClient(toFacilitatorClient(options.facilitator));
+  const resourceServer = new x402ResourceServer(facilitator);
+  for (const register of options.schemes ?? [registerExactEvmScheme]) {
+    register(resourceServer);
+  }
+  const { logger } = options;
+  const metrics = options.enableMetrics ? options.metrics ?? new Metrics({ namespace: "x402" }) : void 0;
+  const count = (name) => metrics && (metrics.singleMetric?.() ?? metrics).addMetric(name, "Count", 1);
+  const payers = /* @__PURE__ */ new WeakMap();
+  resourceServer.onAfterVerify(async ({ paymentPayload, result }) => {
+    if (result.payer) payers.set(paymentPayload, result.payer);
+  });
+  function paid(route) {
+    const { price, accepts, onProtectedRequest, ...routeConfig } = route;
+    if (accepts === void 0 && price === void 0) {
+      throw new Error("paid() requires a price or an accepts configuration");
+    }
+    const httpServer = new x402HTTPResourceServer(resourceServer, {
+      ...routeConfig,
+      mimeType: routeConfig.mimeType ?? "application/json",
+      accepts: accepts ?? {
+        scheme: "exact",
+        network: options.network,
+        payTo: options.payTo,
+        price
+      }
+    });
+    if (onProtectedRequest) httpServer.onProtectedRequest(onProtectedRequest);
+    let ready;
+    const initialize = () => ready ??= httpServer.initialize().catch((error) => {
+      ready = void 0;
+      throw error;
+    });
+    return async ({ reqCtx, next }) => {
+      await initialize();
+      const adapter = new PowertoolsAdapter(reqCtx.req);
+      const context = {
+        adapter,
+        path: adapter.getPath(),
+        method: adapter.getMethod()
+      };
+      const result = await httpServer.processHTTPRequest(context, options.paywall);
+      if (result.type === "no-payment-required") {
+        await next();
+        return;
+      }
+      if (result.type === "payment-error") {
+        count(adapter.getHeader("payment-signature") ? "PaymentRejected" : "PaymentRequired");
+        logger?.debug("x402 payment not accepted", { status: result.response.status });
+        reqCtx.res = toResponse(result.response);
+        return;
+      }
+      const {
+        cancellationDispatcher,
+        beforeHandlerSettlement,
+        paymentPayload,
+        paymentRequirements,
+        declaredExtensions
+      } = result;
+      reqCtx.set("payment", {
+        network: paymentRequirements.network,
+        scheme: paymentRequirements.scheme,
+        asset: paymentRequirements.asset,
+        amount: paymentRequirements.amount,
+        payer: payers.get(paymentPayload)
+      });
+      count("PaymentVerified");
+      try {
+        await next();
+      } catch (error) {
+        await cancellationDispatcher.cancel({ reason: "handler_threw", error });
+        count("PaymentCancelled");
+        logger?.warn("x402 payment cancelled: handler threw", { path: context.path });
+        throw error;
+      }
+      if (reqCtx.res.status >= 400) {
+        await cancellationDispatcher.cancel({
+          reason: "handler_failed",
+          responseStatus: reqCtx.res.status
+        });
+        count("PaymentCancelled");
+        logger?.warn("x402 payment cancelled: handler failed", {
+          path: context.path,
+          status: reqCtx.res.status
+        });
+        return;
+      }
+      const settlement = await httpServer.processSettlement(
+        paymentPayload,
+        paymentRequirements,
+        declaredExtensions,
+        {
+          request: context,
+          responseBody: Buffer.from(await reqCtx.res.clone().arrayBuffer()),
+          responseHeaders: Object.fromEntries(reqCtx.res.headers.entries())
+        },
+        void 0,
+        beforeHandlerSettlement
+      );
+      if (!settlement.success) {
+        count("SettlementFailed");
+        logger?.error("x402 settlement failed", {
+          path: context.path,
+          errorReason: settlement.errorReason
+        });
+        reqCtx.res = toResponse(settlement.response);
+        return;
+      }
+      count("PaymentSettled");
+      logger?.debug("x402 payment settled", { path: context.path, transaction: settlement.transaction });
+      for (const [name, value] of Object.entries(settlement.headers)) {
+        reqCtx.res.headers.set(name, value);
+      }
+      const cacheControl = reqCtx.res.headers.get("cache-control");
+      reqCtx.res.headers.set("cache-control", cacheControl ? `${cacheControl}, private` : "private");
+    };
+  }
+  return { paid, resourceServer };
+}
+
+export {
+  PowertoolsAdapter,
+  CachingFacilitatorClient,
+  createX402
+};

package/dist/chunk-FLK2T35N.js

@@ -0,0 +1,7 @@
+// src/coinbase.ts
+import { createFacilitatorConfig } from "@coinbase/x402";
+var coinbaseFacilitator = (apiKeyId, apiKeySecret) => createFacilitatorConfig(apiKeyId, apiKeySecret);
+
+export {
+  coinbaseFacilitator
+};

package/dist/coinbase.cjs

@@ -0,0 +1,31 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/coinbase.ts
+var coinbase_exports = {};
+__export(coinbase_exports, {
+  coinbaseFacilitator: () => coinbaseFacilitator
+});
+module.exports = __toCommonJS(coinbase_exports);
+var import_x402 = require("@coinbase/x402");
+var coinbaseFacilitator = (apiKeyId, apiKeySecret) => (0, import_x402.createFacilitatorConfig)(apiKeyId, apiKeySecret);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  coinbaseFacilitator
+});

package/dist/coinbase.d.cts

@@ -0,0 +1,9 @@
+import { FacilitatorConfig } from '@x402/core/server';
+
+/**
+ * Coinbase Developer Platform facilitator for mainnet settlement.
+ * Falls back to CDP_API_KEY_ID and CDP_API_KEY_SECRET when keys are omitted.
+ */
+declare const coinbaseFacilitator: (apiKeyId?: string, apiKeySecret?: string) => FacilitatorConfig;
+
+export { coinbaseFacilitator };

package/dist/coinbase.d.ts

@@ -0,0 +1,9 @@
+import { FacilitatorConfig } from '@x402/core/server';
+
+/**
+ * Coinbase Developer Platform facilitator for mainnet settlement.
+ * Falls back to CDP_API_KEY_ID and CDP_API_KEY_SECRET when keys are omitted.
+ */
+declare const coinbaseFacilitator: (apiKeyId?: string, apiKeySecret?: string) => FacilitatorConfig;
+
+export { coinbaseFacilitator };

package/dist/coinbase.js

@@ -0,0 +1,6 @@
+import {
+  coinbaseFacilitator
+} from "./chunk-FLK2T35N.js";
+export {
+  coinbaseFacilitator
+};

package/dist/index.js

@@ -1,208 +1,8 @@
-// src/index.ts
-import { Metrics } from "@aws-lambda-powertools/metrics";
 import {
-  HTTPFacilitatorClient,
-  x402HTTPResourceServer,
-  x402ResourceServer
-} from "@x402/core/server";
-import { registerExactEvmScheme } from "@x402/evm/exact/server";
-
-// src/adapter.ts
-var PowertoolsAdapter = class {
-  constructor(request) {
-    this.request = request;
-  }
-  request;
-  getHeader(name) {
-    return this.request.headers.get(name) ?? void 0;
-  }
-  getMethod() {
-    return this.request.method;
-  }
-  getPath() {
-    return new URL(this.request.url).pathname;
-  }
-  getUrl() {
-    return this.request.url;
-  }
-  getAcceptHeader() {
-    return this.request.headers.get("accept") ?? "";
-  }
-  getUserAgent() {
-    return this.request.headers.get("user-agent") ?? "";
-  }
-  getQueryParams() {
-    const params = new URL(this.request.url).searchParams;
-    const result = {};
-    for (const key of new Set(params.keys())) {
-      const values = params.getAll(key);
-      result[key] = values.length === 1 ? values[0] : values;
-    }
-    return result;
-  }
-  getQueryParam(name) {
-    const values = new URL(this.request.url).searchParams.getAll(name);
-    if (values.length === 0) return void 0;
-    return values.length === 1 ? values[0] : values;
-  }
-  async getBody() {
-    try {
-      return await this.request.clone().json();
-    } catch {
-      return void 0;
-    }
-  }
-};
-
-// src/facilitator.ts
-var CachingFacilitatorClient = class {
-  constructor(client) {
-    this.client = client;
-  }
-  client;
-  #supported;
-  verify(payload, requirements) {
-    return this.client.verify(payload, requirements);
-  }
-  settle(payload, requirements) {
-    return this.client.settle(payload, requirements);
-  }
-  getSupported() {
-    this.#supported ??= this.client.getSupported().catch((error) => {
-      this.#supported = void 0;
-      throw error;
-    });
-    return this.#supported;
-  }
-};
-
-// src/index.ts
-var toFacilitatorClient = (facilitator) => {
-  if (typeof facilitator === "string") return new HTTPFacilitatorClient({ url: facilitator });
-  if ("getSupported" in facilitator) return facilitator;
-  return new HTTPFacilitatorClient(facilitator);
-};
-var toResponse = ({ status, headers, body, isHtml }) => new Response(isHtml ? String(body ?? "") : JSON.stringify(body ?? {}), { status, headers });
-function createX402(options) {
-  const facilitator = new CachingFacilitatorClient(toFacilitatorClient(options.facilitator));
-  const resourceServer = new x402ResourceServer(facilitator);
-  for (const register of options.schemes ?? [registerExactEvmScheme]) {
-    register(resourceServer);
-  }
-  const { logger } = options;
-  const metrics = options.enableMetrics ? options.metrics ?? new Metrics({ namespace: "x402" }) : void 0;
-  const count = (name) => metrics && (metrics.singleMetric?.() ?? metrics).addMetric(name, "Count", 1);
-  const payers = /* @__PURE__ */ new WeakMap();
-  resourceServer.onAfterVerify(async ({ paymentPayload, result }) => {
-    if (result.payer) payers.set(paymentPayload, result.payer);
-  });
-  function paid(route) {
-    const { price, accepts, onProtectedRequest, ...routeConfig } = route;
-    if (accepts === void 0 && price === void 0) {
-      throw new Error("paid() requires a price or an accepts configuration");
-    }
-    const httpServer = new x402HTTPResourceServer(resourceServer, {
-      ...routeConfig,
-      mimeType: routeConfig.mimeType ?? "application/json",
-      accepts: accepts ?? {
-        scheme: "exact",
-        network: options.network,
-        payTo: options.payTo,
-        price
-      }
-    });
-    if (onProtectedRequest) httpServer.onProtectedRequest(onProtectedRequest);
-    let ready;
-    const initialize = () => ready ??= httpServer.initialize().catch((error) => {
-      ready = void 0;
-      throw error;
-    });
-    return async ({ reqCtx, next }) => {
-      await initialize();
-      const adapter = new PowertoolsAdapter(reqCtx.req);
-      const context = {
-        adapter,
-        path: adapter.getPath(),
-        method: adapter.getMethod()
-      };
-      const result = await httpServer.processHTTPRequest(context, options.paywall);
-      if (result.type === "no-payment-required") {
-        await next();
-        return;
-      }
-      if (result.type === "payment-error") {
-        count(adapter.getHeader("payment-signature") ? "PaymentRejected" : "PaymentRequired");
-        logger?.debug("x402 payment not accepted", { status: result.response.status });
-        reqCtx.res = toResponse(result.response);
-        return;
-      }
-      const {
-        cancellationDispatcher,
-        beforeHandlerSettlement,
-        paymentPayload,
-        paymentRequirements,
-        declaredExtensions
-      } = result;
-      reqCtx.set("payment", {
-        network: paymentRequirements.network,
-        scheme: paymentRequirements.scheme,
-        asset: paymentRequirements.asset,
-        amount: paymentRequirements.amount,
-        payer: payers.get(paymentPayload)
-      });
-      count("PaymentVerified");
-      try {
-        await next();
-      } catch (error) {
-        await cancellationDispatcher.cancel({ reason: "handler_threw", error });
-        count("PaymentCancelled");
-        logger?.warn("x402 payment cancelled: handler threw", { path: context.path });
-        throw error;
-      }
-      if (reqCtx.res.status >= 400) {
-        await cancellationDispatcher.cancel({
-          reason: "handler_failed",
-          responseStatus: reqCtx.res.status
-        });
-        count("PaymentCancelled");
-        logger?.warn("x402 payment cancelled: handler failed", {
-          path: context.path,
-          status: reqCtx.res.status
-        });
-        return;
-      }
-      const settlement = await httpServer.processSettlement(
-        paymentPayload,
-        paymentRequirements,
-        declaredExtensions,
-        {
-          request: context,
-          responseBody: Buffer.from(await reqCtx.res.clone().arrayBuffer()),
-          responseHeaders: Object.fromEntries(reqCtx.res.headers.entries())
-        },
-        void 0,
-        beforeHandlerSettlement
-      );
-      if (!settlement.success) {
-        count("SettlementFailed");
-        logger?.error("x402 settlement failed", {
-          path: context.path,
-          errorReason: settlement.errorReason
-        });
-        reqCtx.res = toResponse(settlement.response);
-        return;
-      }
-      count("PaymentSettled");
-      logger?.debug("x402 payment settled", { path: context.path, transaction: settlement.transaction });
-      for (const [name, value] of Object.entries(settlement.headers)) {
-        reqCtx.res.headers.set(name, value);
-      }
-      const cacheControl = reqCtx.res.headers.get("cache-control");
-      reqCtx.res.headers.set("cache-control", cacheControl ? `${cacheControl}, private` : "private");
-    };
-  }
-  return { paid, resourceServer };
-}
+  CachingFacilitatorClient,
+  PowertoolsAdapter,
+  createX402
+} from "./chunk-D46V2DLG.js";
 export {
   CachingFacilitatorClient,
   PowertoolsAdapter,