powertools-x402 0.1.2 → 0.2.0

package/README.md

@@ -16,7 +16,7 @@ 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
-- 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
+- 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.
@@ -76,7 +76,7 @@ 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
 
@@ -162,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

package/dist/{chunk-D46V2DLG.js → chunk-4ZP7AJJC.js}

@@ -92,12 +92,20 @@ function createX402(options) {
   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, ...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");
     }
@@ -171,6 +179,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.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 };

package/dist/index.js

@@ -2,7 +2,7 @@ import {
   CachingFacilitatorClient,
   PowertoolsAdapter,
   createX402
-} from "./chunk-D46V2DLG.js";
+} from "./chunk-4ZP7AJJC.js";
 export {
   CachingFacilitatorClient,
   PowertoolsAdapter,

package/dist/stripe.cjs

@@ -129,12 +129,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");
     }
@@ -208,6 +216,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/stripe.js

@@ -3,7 +3,7 @@ import {
 } from "./chunk-FLK2T35N.js";
 import {
   createX402
-} from "./chunk-D46V2DLG.js";
+} from "./chunk-4ZP7AJJC.js";
 
 // src/stripe.ts
 import Stripe from "stripe";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "powertools-x402",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "x402 payment middleware for AWS Lambda Powertools Event Handler",
   "license": "MIT",
   "author": "Allen Helton <allenheltondev@gmail.com>",