powertools-x402 0.1.1 → 0.2.0

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. A `billable` predicate can also decline to charge for a response that succeeded
 - 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
@@ -74,68 +76,51 @@ 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.
+This emits `PaymentRequired`, `PaymentRejected`, `PaymentVerified`, `PaymentSettled`, `PaymentCancelled`, `PaymentNotBillable`, 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.
+
+### 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:
 
-### Use an authenticated 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
 
@@ -177,6 +162,41 @@ x402.paid({
 });
 ```
 
+### Decline to charge for a successful response
+
+Sometimes the work succeeds, the caller should get the payload, and you still don't want the money. A `billable` predicate runs after your handler on the path that would otherwise settle, and returning `false` skips settlement:
+
+```ts
+app.post(
+  '/extract',
+  [
+    x402.paid({
+      price: '$0.05',
+      billable: (response) =>
+        response
+          .json()
+          .then(({ fields }: { fields: Record<string, string> }) => Object.keys(fields).length > 0),
+    }),
+  ],
+  async (reqCtx) => {
+    const { document } = (await reqCtx.req.json()) as { document: string };
+    return { fields: await extractFields(document) };
+  }
+);
+```
+
+The caller gets their 200 and the empty result either way; they just aren't charged for it. The same shape covers an LLM route that returned a refusal, or a search that legitimately found nothing.
+
+It's all or nothing: `billable` decides whether to charge the full price, not how much to charge. If what you want is to bill less for cheaper work, that's partial settlement, which the `exact` scheme doesn't do.
+
+The predicate receives a clone of the handler's response, so reading its body is safe, plus the request context, so `reqCtx.get('payment')` is available. It may be async. Skipping settlement leaves the response exactly as your handler produced it, with no `PAYMENT-RESPONSE` receipt header.
+
+A skip counts a `PaymentNotBillable` metric, deliberately separate from `PaymentCancelled`, which stays reserved for handlers that threw or failed. An alarm on cancellations won't fire on a route declining to bill. A predicate that throws is treated as not billable and logged at error, so a broken predicate never turns a successful response into a 500.
+
+Note the direction: `billable` can only subtract a settlement, never add one. It isn't consulted at all when the handler throws or returns an error status, since those already skip settlement.
+
+It also only prevents a charge when the selected payment flow settles *after* the handler. The default `exact` authorization flow does, and that's what you get unless you ask for something else. But `exact` also supports the `upfront` flow, chosen with `extra: { paymentFlow: 'upfront' }` on an `accepts` entry, and `upfront` and `escrow` both settle before your handler runs. By the time `billable` returns `false` there, the money has already moved and nothing can unmake the charge. Rather than report a refund that never happened, the middleware ignores the `false`, settles as normal so the caller still gets the receipt they paid for, and logs at error.
+
 ### Customize the 402 response
 
 ```ts
@@ -192,23 +212,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-4ZP7AJJC.js

@@ -0,0 +1,231 @@
+// 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 isBillable = async (predicate, reqCtx, path) => {
+    try {
+      return await predicate(reqCtx.res.clone(), reqCtx);
+    } catch (error) {
+      logger?.error("x402 billable predicate threw", { path, error });
+      return false;
+    }
+  };
+  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, billable, ...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;
+      }
+      if (billable && !await isBillable(billable, reqCtx, context.path)) {
+        if (beforeHandlerSettlement) {
+          logger?.error("x402 billable ignored: flow settles before the handler", {
+            path: context.path
+          });
+        } else {
+          await cancellationDispatcher.cancel({ reason: "after_verify_aborted" });
+          count("PaymentNotBillable");
+          logger?.warn("x402 payment not billed: route declined", { path: context.path });
+          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.cjs

@@ -114,12 +114,20 @@ function createX402(options) {
   const { logger } = options;
   const metrics = options.enableMetrics ? options.metrics ?? new import_metrics.Metrics({ namespace: "x402" }) : void 0;
   const count = (name) => metrics && (metrics.singleMetric?.() ?? metrics).addMetric(name, "Count", 1);
+  const isBillable = async (predicate, reqCtx, path) => {
+    try {
+      return await predicate(reqCtx.res.clone(), reqCtx);
+    } catch (error) {
+      logger?.error("x402 billable predicate threw", { path, error });
+      return false;
+    }
+  };
   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;
+    const { price, accepts, onProtectedRequest, billable, ...routeConfig } = route;
     if (accepts === void 0 && price === void 0) {
       throw new Error("paid() requires a price or an accepts configuration");
     }
@@ -193,6 +201,18 @@ function createX402(options) {
         });
         return;
       }
+      if (billable && !await isBillable(billable, reqCtx, context.path)) {
+        if (beforeHandlerSettlement) {
+          logger?.error("x402 billable ignored: flow settles before the handler", {
+            path: context.path
+          });
+        } else {
+          await cancellationDispatcher.cancel({ reason: "after_verify_aborted" });
+          count("PaymentNotBillable");
+          logger?.warn("x402 payment not billed: route declined", { path: context.path });
+          return;
+        }
+      }
       const settlement = await httpServer.processSettlement(
         paymentPayload,
         paymentRequirements,

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { Middleware } from '@aws-lambda-powertools/event-handler/types';
+import { RequestContext, Middleware } from '@aws-lambda-powertools/event-handler/types';
 import { HTTPAdapter, FacilitatorClient, FacilitatorConfig, x402ResourceServer, PaywallConfig, RouteConfig, ProtectedRequestHook } from '@x402/core/server';
 import { PaymentOption } from '@x402/core/http';
 import { PaymentPayload, PaymentRequirements, VerifyResponse, SettleResponse, SupportedResponse, Network, Price } from '@x402/core/types';
@@ -54,10 +54,19 @@ interface CreateX402Options {
     enableMetrics?: boolean;
     metrics?: X402Metrics;
 }
+/**
+ * Decides whether a successful response should be charged for. Receives a
+ * clone of the handler's response, so reading its body is safe. Returning
+ * false skips settlement. Only prevents a charge when the selected payment
+ * flow settles after the handler, as the default exact authorization flow
+ * does; see the README for flows that settle before it.
+ */
+type BillablePredicate = (response: Response, reqCtx: RequestContext<X402Environment>) => boolean | Promise<boolean>;
 interface PaidRouteOptions extends Omit<RouteConfig, 'accepts'> {
     price?: Price;
     accepts?: PaymentOption | PaymentOption[];
     onProtectedRequest?: ProtectedRequestHook;
+    billable?: BillablePredicate;
 }
 type PaymentInfo = {
     network: Network;
@@ -78,4 +87,4 @@ declare function createX402(options: CreateX402Options): {
     resourceServer: x402ResourceServer;
 };
 
-export { CachingFacilitatorClient, type CreateX402Options, type PaidRouteOptions, type PaymentInfo, PowertoolsAdapter, type SchemeRegistrar, type X402Environment, type X402Logger, type X402Metrics, createX402 };
+export { type BillablePredicate, CachingFacilitatorClient, type CreateX402Options, type PaidRouteOptions, type PaymentInfo, PowertoolsAdapter, type SchemeRegistrar, type X402Environment, type X402Logger, type X402Metrics, createX402 };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Middleware } from '@aws-lambda-powertools/event-handler/types';
+import { RequestContext, Middleware } from '@aws-lambda-powertools/event-handler/types';
 import { HTTPAdapter, FacilitatorClient, FacilitatorConfig, x402ResourceServer, PaywallConfig, RouteConfig, ProtectedRequestHook } from '@x402/core/server';
 import { PaymentOption } from '@x402/core/http';
 import { PaymentPayload, PaymentRequirements, VerifyResponse, SettleResponse, SupportedResponse, Network, Price } from '@x402/core/types';
@@ -54,10 +54,19 @@ interface CreateX402Options {
     enableMetrics?: boolean;
     metrics?: X402Metrics;
 }
+/**
+ * Decides whether a successful response should be charged for. Receives a
+ * clone of the handler's response, so reading its body is safe. Returning
+ * false skips settlement. Only prevents a charge when the selected payment
+ * flow settles after the handler, as the default exact authorization flow
+ * does; see the README for flows that settle before it.
+ */
+type BillablePredicate = (response: Response, reqCtx: RequestContext<X402Environment>) => boolean | Promise<boolean>;
 interface PaidRouteOptions extends Omit<RouteConfig, 'accepts'> {
     price?: Price;
     accepts?: PaymentOption | PaymentOption[];
     onProtectedRequest?: ProtectedRequestHook;
+    billable?: BillablePredicate;
 }
 type PaymentInfo = {
     network: Network;
@@ -78,4 +87,4 @@ declare function createX402(options: CreateX402Options): {
     resourceServer: x402ResourceServer;
 };
 
-export { CachingFacilitatorClient, type CreateX402Options, type PaidRouteOptions, type PaymentInfo, PowertoolsAdapter, type SchemeRegistrar, type X402Environment, type X402Logger, type X402Metrics, createX402 };
+export { type BillablePredicate, CachingFacilitatorClient, type CreateX402Options, type PaidRouteOptions, type PaymentInfo, PowertoolsAdapter, type SchemeRegistrar, type X402Environment, type X402Logger, type X402Metrics, createX402 };