powertools-x402 0.1.1 → 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
@@ -76,66 +78,49 @@ 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). You point `payTo` at a Stripe crypto deposit address, settle through the Coinbase Developer Platform facilitator, and record each settled payment as a Stripe PaymentIntent. Funds land in your Stripe balance next to your card payments.
+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 { createFacilitatorConfig } from '@coinbase/x402';
-import Stripe from 'stripe';
+import { createStripeX402 } from 'powertools-x402/stripe';
 
-const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
-  apiVersion: '2026-05-27.preview' as Stripe.LatestApiVersion,
-});
+// Reads STRIPE_SECRET_KEY, STRIPE_DEPOSIT_ADDRESS, CDP_API_KEY_ID, and CDP_API_KEY_SECRET
+const x402 = createStripeX402();
 
-const x402 = createX402({
-  facilitator: createFacilitatorConfig(process.env.CDP_API_KEY_ID!, process.env.CDP_API_KEY_SECRET!),
-  network: 'eip155:8453', // Base mainnet
-  payTo: process.env.STRIPE_DEPOSIT_ADDRESS!, // POST /v1/crypto/deposit_addresses, one time
-});
-
-x402.resourceServer.onAfterSettle(async ({ result, requirements }) => {
-  if (!result.success || !result.transaction) return;
-  await stripe.paymentIntents.create(
-    {
-      amount: Math.round(Number(requirements.amount) / 10_000), // atomic USDC to cents
-      currency: 'usd',
-      confirm: true,
-      payment_method_data: { type: 'crypto' },
-      payment_method_types: ['crypto'],
-      payment_method_options: {
-        crypto: {
-          mode: 'transaction_verification',
-          transaction_verification_options: { network: 'base', transaction_hash: result.transaction },
-        } as Stripe.PaymentIntentCreateParams.PaymentMethodOptions.Crypto,
-      },
-    },
-    { idempotencyKey: result.transaction }
-  );
-});
+app.post('/paid', [x402.paid({ price: '$0.01' })], async () => ({ foo: 'bar' }));
 ```
 
-Full working version in [example/stripe.ts](example/stripe.ts). Heads up: 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.
+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
 
@@ -192,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)
 

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,