@parallel-protocol/x402 0.5.3 → 0.7.0

package/dist/hono.js

@@ -1,5 +1,5 @@
-import { raceTimeout, HANDLER_TIMEOUT } from './chunk-2UEAVMCH.js';
-import { createPaymentMiddleware } from './chunk-75GLDK7L.js';
+import { isJsonContentType, raceTimeout, HANDLER_TIMEOUT, jsonFromResponse, createPaymentMiddleware } from './chunk-AENXD4OC.js';
+import './chunk-AFRDHGDT.js';
 
 // src/hono/adapter.ts
 var TIMEOUT_BODY = JSON.stringify({
@@ -25,13 +25,26 @@ var HonoAdapter = class {
   getUrl() {
     return this.c.req.url;
   }
-  async runHandler() {
-    const outcome = await raceTimeout(this.next());
+  // Hono caches the parsed body on the request, so the handler can still read
+  // it after the price function did.
+  async getBody() {
+    if (!isJsonContentType(this.c.req.header("content-type"))) return void 0;
+    try {
+      return await this.c.req.json();
+    } catch {
+      return void 0;
+    }
+  }
+  async runHandler(options) {
+    const outcome = await raceTimeout(this.next(), options?.timeoutMs);
     if (outcome === HANDLER_TIMEOUT) {
       return {
         status: 504,
         setResponseHeader: () => {
         },
+        getResponseHeader: () => void 0,
+        removeResponseHeader: () => {
+        },
         sendResponse: () => {
           this.c.res = new Response(TIMEOUT_BODY, {
             status: 504,
@@ -46,9 +59,17 @@ var HonoAdapter = class {
     return {
       status: res.status,
       setResponseHeader: (name, value) => res.headers.set(name, value),
+      getResponseHeader: (name) => res.headers.get(name) ?? void 0,
+      removeResponseHeader: (name) => res.headers.delete(name),
+      // Read from a clone: the response body streams once, to the client.
+      getResponseBody: () => jsonFromResponse(res),
       sendResponse: () => {
       },
+      // The response is replaced: release its body (and whatever upstream
+      // stream feeds it) instead of leaving it open until collected.
       discardResponse: () => {
+        res.body?.cancel().catch(() => {
+        });
       }
     };
   }

package/dist/index.cjs

@@ -1,54 +1,75 @@
 'use strict';
 
-var chunkKQPIZ6SZ_cjs = require('./chunk-KQPIZ6SZ.cjs');
+var chunkPOU7EH3E_cjs = require('./chunk-POU7EH3E.cjs');
+var chunkJPMK5YBU_cjs = require('./chunk-JPMK5YBU.cjs');
 
 
 
 Object.defineProperty(exports, "FacilitatorClient", {
   enumerable: true,
-  get: function () { return chunkKQPIZ6SZ_cjs.FacilitatorClient; }
+  get: function () { return chunkPOU7EH3E_cjs.FacilitatorClient; }
 });
 Object.defineProperty(exports, "PARALLEL_TOKENS", {
   enumerable: true,
-  get: function () { return chunkKQPIZ6SZ_cjs.PARALLEL_TOKENS; }
+  get: function () { return chunkPOU7EH3E_cjs.PARALLEL_TOKENS; }
 });
-Object.defineProperty(exports, "X402ConfigError", {
-  enumerable: true,
-  get: function () { return chunkKQPIZ6SZ_cjs.X402ConfigError; }
-});
-Object.defineProperty(exports, "X402RuntimeError", {
-  enumerable: true,
-  get: function () { return chunkKQPIZ6SZ_cjs.X402RuntimeError; }
-});
-Object.defineProperty(exports, "X402_ERROR_CODES", {
+Object.defineProperty(exports, "SETTLE_AMOUNT_HEADER", {
   enumerable: true,
-  get: function () { return chunkKQPIZ6SZ_cjs.X402_ERROR_CODES; }
+  get: function () { return chunkPOU7EH3E_cjs.SETTLE_AMOUNT_HEADER; }
 });
 Object.defineProperty(exports, "createPaymentGate", {
   enumerable: true,
-  get: function () { return chunkKQPIZ6SZ_cjs.createPaymentGate; }
+  get: function () { return chunkPOU7EH3E_cjs.createPaymentGate; }
 });
 Object.defineProperty(exports, "createPaymentMiddleware", {
   enumerable: true,
-  get: function () { return chunkKQPIZ6SZ_cjs.createPaymentMiddleware; }
+  get: function () { return chunkPOU7EH3E_cjs.createPaymentMiddleware; }
 });
 Object.defineProperty(exports, "encodeBase64", {
   enumerable: true,
-  get: function () { return chunkKQPIZ6SZ_cjs.encodeBase64; }
+  get: function () { return chunkPOU7EH3E_cjs.encodeBase64; }
 });
 Object.defineProperty(exports, "getDefaultAcceptedTokens", {
   enumerable: true,
-  get: function () { return chunkKQPIZ6SZ_cjs.getDefaultAcceptedTokens; }
+  get: function () { return chunkPOU7EH3E_cjs.getDefaultAcceptedTokens; }
 });
 Object.defineProperty(exports, "parsePrice", {
   enumerable: true,
-  get: function () { return chunkKQPIZ6SZ_cjs.parsePrice; }
+  get: function () { return chunkPOU7EH3E_cjs.parsePrice; }
+});
+Object.defineProperty(exports, "resolveCharge", {
+  enumerable: true,
+  get: function () { return chunkPOU7EH3E_cjs.resolveCharge; }
+});
+Object.defineProperty(exports, "resolveSettleAmount", {
+  enumerable: true,
+  get: function () { return chunkPOU7EH3E_cjs.resolveSettleAmount; }
 });
 Object.defineProperty(exports, "toEip155Network", {
   enumerable: true,
-  get: function () { return chunkKQPIZ6SZ_cjs.toEip155Network; }
+  get: function () { return chunkPOU7EH3E_cjs.toEip155Network; }
 });
 Object.defineProperty(exports, "validateAddress", {
   enumerable: true,
-  get: function () { return chunkKQPIZ6SZ_cjs.validateAddress; }
+  get: function () { return chunkPOU7EH3E_cjs.validateAddress; }
+});
+Object.defineProperty(exports, "X402ConfigError", {
+  enumerable: true,
+  get: function () { return chunkJPMK5YBU_cjs.X402ConfigError; }
+});
+Object.defineProperty(exports, "X402PriceRejectedError", {
+  enumerable: true,
+  get: function () { return chunkJPMK5YBU_cjs.X402PriceRejectedError; }
+});
+Object.defineProperty(exports, "X402RuntimeError", {
+  enumerable: true,
+  get: function () { return chunkJPMK5YBU_cjs.X402RuntimeError; }
+});
+Object.defineProperty(exports, "X402_ERROR_CODES", {
+  enumerable: true,
+  get: function () { return chunkJPMK5YBU_cjs.X402_ERROR_CODES; }
+});
+Object.defineProperty(exports, "isPriceRejection", {
+  enumerable: true,
+  get: function () { return chunkJPMK5YBU_cjs.isPriceRejection; }
 });

package/dist/index.d.cts

@@ -1,12 +1,12 @@
-import { F as FacilitatorConfig, a as FacilitatorPaymentRequirements, b as FacilitatorResponse, P as PaymentMiddlewareConfig, H as HTTPAdapter, c as PaymentGateResult, M as MiddlewareResult, d as PassResult } from './types-CUi55YSx.cjs';
-export { e as PaymentConfirmation, f as PaymentFailure, g as PaymentRequired, h as PaymentRequirements, i as ResourceInfo, j as RouteConfig, R as RunHandlerResult } from './types-CUi55YSx.cjs';
+import { F as FacilitatorConfig, b as FacilitatorPaymentRequirements, S as SettleOptions, c as FacilitatorResponse, P as PaymentMiddlewareConfig, H as HTTPAdapter, d as PaymentGateResult, M as MiddlewareResult, e as PassResult, V as VerifiedPayment } from './types-q_gu5wjz.cjs';
+export { f as MeterContext, g as MeterFunction, h as PaymentConfirmation, i as PaymentFailure, j as PaymentRequired, k as PaymentRequirements, l as PriceContext, m as PriceFunction, n as ResourceInfo, o as RouteConfig, R as RunHandlerOptions, a as RunHandlerResult } from './types-q_gu5wjz.cjs';
 import { Address } from 'viem';
 
 declare class FacilitatorClient {
     private readonly config;
     constructor(config: FacilitatorConfig);
     verify(paymentHeader: string, paymentRequirements: FacilitatorPaymentRequirements): Promise<void>;
-    settle(paymentHeader: string, paymentRequirements: FacilitatorPaymentRequirements): Promise<FacilitatorResponse>;
+    settle(paymentHeader: string, paymentRequirements: FacilitatorPaymentRequirements, options?: SettleOptions): Promise<FacilitatorResponse>;
     pay(paymentHeader: string): Promise<FacilitatorResponse>;
     private buildHeaders;
 }
@@ -24,8 +24,67 @@ declare class X402RuntimeError extends Error {
     readonly code: string;
     constructor(code: string);
 }
+/**
+ * Thrown by a per-request price function to refuse a request before anything
+ * is invoiced or signed: the middleware answers with `status` and a JSON body
+ * `{ error: code, message }`. For requests the route will not serve (an
+ * unknown model, an unsupported option) rather than merchant bugs.
+ */
+declare class X402PriceRejectedError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(code: string, message: string, status?: number);
+}
+/**
+ * Recognises a price refusal by shape rather than by class identity, so a
+ * refusal thrown from another copy of this package (a nested install, the
+ * CommonJS build next to the ESM one) is still answered as a refusal.
+ */
+declare function isPriceRejection(error: unknown): error is X402PriceRejectedError;
 
-declare function createPaymentGate(config: PaymentMiddlewareConfig): (adapter: Pick<HTTPAdapter, "getHeader" | "getPath" | "getUrl" | "getMethod">) => Promise<PaymentGateResult>;
+type GateAdapter = Pick<HTTPAdapter, "getHeader" | "getPath" | "getUrl" | "getMethod" | "getBody">;
+/**
+ * Response header a handler on a metered (`upto`) route sets to the amount it
+ * actually charges, in whole token units like `price` ("0.75"). Read and
+ * stripped by the middleware before the response leaves. Absent → the cap is
+ * charged; "0" → the request is served for free (no settlement).
+ */
+declare const SETTLE_AMOUNT_HEADER = "payment-settle-amount";
+type SettleAmountResolution = {
+    kind: "settle";
+    amount: string;
+} | {
+    kind: "skip";
+} | {
+    kind: "invalid";
+    reason: "malformed" | "precision" | "above-cap" | "meter";
+};
+/**
+ * Turns the handler's `payment-settle-amount` header into a settle decision.
+ * A malformed value, one carrying more decimals than the token has, or one
+ * above the signed cap is a merchant bug: the payment fails closed rather than
+ * charging something the handler did not mean. Only an explicit zero skips
+ * the settlement — a positive amount the token cannot represent is never
+ * silently served for free.
+ */
+declare function resolveSettleAmount(raw: string | undefined, maxAmount: bigint, decimals: number): SettleAmountResolution;
+/** What the middleware can read from the handler's response. */
+interface ChargeResponse {
+    status: number;
+    header(name: string): string | undefined;
+    body(): Promise<unknown>;
+}
+/**
+ * The amount a metered route settles, once the handler answered with a 2xx.
+ * A `meter` function on the route decides first, from the response: its
+ * amount is bounded by the cap (an overrun is the merchant's loss, not a
+ * refused response), zero serves for free, and no amount hands over to the
+ * `payment-settle-amount` header, which keeps its rules (absent charges the
+ * cap, above the cap is refused). A meter that throws or returns something
+ * that is not an amount fails closed like an invalid header.
+ */
+declare function resolveCharge(verified: VerifiedPayment, settleHeader: string | undefined, response: ChargeResponse): Promise<SettleAmountResolution>;
+declare function createPaymentGate(config: PaymentMiddlewareConfig): (adapter: GateAdapter) => Promise<PaymentGateResult>;
 declare function createPaymentMiddleware(config: PaymentMiddlewareConfig): (adapter: HTTPAdapter) => Promise<MiddlewareResult | PassResult>;
 
 type ParallelNetwork = "ethereum" | "base" | "avalanche" | "hyperevm";
@@ -49,4 +108,4 @@ declare function validateAddress(address: string): address is Address;
 declare function toEip155Network(network: string): string;
 declare function encodeBase64(obj: unknown): string;
 
-export { FacilitatorClient, FacilitatorConfig, FacilitatorPaymentRequirements, FacilitatorResponse, HTTPAdapter, MiddlewareResult, PARALLEL_TOKENS, type ParallelNetwork, PassResult, PaymentGateResult, PaymentMiddlewareConfig, X402ConfigError, type X402ErrorCode, X402RuntimeError, X402_ERROR_CODES, createPaymentGate, createPaymentMiddleware, encodeBase64, getDefaultAcceptedTokens, parsePrice, toEip155Network, validateAddress };
+export { type ChargeResponse, FacilitatorClient, FacilitatorConfig, FacilitatorPaymentRequirements, FacilitatorResponse, HTTPAdapter, MiddlewareResult, PARALLEL_TOKENS, type ParallelNetwork, PassResult, PaymentGateResult, PaymentMiddlewareConfig, SETTLE_AMOUNT_HEADER, type SettleAmountResolution, SettleOptions, VerifiedPayment, X402ConfigError, type X402ErrorCode, X402PriceRejectedError, X402RuntimeError, X402_ERROR_CODES, createPaymentGate, createPaymentMiddleware, encodeBase64, getDefaultAcceptedTokens, isPriceRejection, parsePrice, resolveCharge, resolveSettleAmount, toEip155Network, validateAddress };

package/dist/index.d.ts

@@ -1,12 +1,12 @@
-import { F as FacilitatorConfig, a as FacilitatorPaymentRequirements, b as FacilitatorResponse, P as PaymentMiddlewareConfig, H as HTTPAdapter, c as PaymentGateResult, M as MiddlewareResult, d as PassResult } from './types-CUi55YSx.js';
-export { e as PaymentConfirmation, f as PaymentFailure, g as PaymentRequired, h as PaymentRequirements, i as ResourceInfo, j as RouteConfig, R as RunHandlerResult } from './types-CUi55YSx.js';
+import { F as FacilitatorConfig, b as FacilitatorPaymentRequirements, S as SettleOptions, c as FacilitatorResponse, P as PaymentMiddlewareConfig, H as HTTPAdapter, d as PaymentGateResult, M as MiddlewareResult, e as PassResult, V as VerifiedPayment } from './types-q_gu5wjz.js';
+export { f as MeterContext, g as MeterFunction, h as PaymentConfirmation, i as PaymentFailure, j as PaymentRequired, k as PaymentRequirements, l as PriceContext, m as PriceFunction, n as ResourceInfo, o as RouteConfig, R as RunHandlerOptions, a as RunHandlerResult } from './types-q_gu5wjz.js';
 import { Address } from 'viem';
 
 declare class FacilitatorClient {
     private readonly config;
     constructor(config: FacilitatorConfig);
     verify(paymentHeader: string, paymentRequirements: FacilitatorPaymentRequirements): Promise<void>;
-    settle(paymentHeader: string, paymentRequirements: FacilitatorPaymentRequirements): Promise<FacilitatorResponse>;
+    settle(paymentHeader: string, paymentRequirements: FacilitatorPaymentRequirements, options?: SettleOptions): Promise<FacilitatorResponse>;
     pay(paymentHeader: string): Promise<FacilitatorResponse>;
     private buildHeaders;
 }
@@ -24,8 +24,67 @@ declare class X402RuntimeError extends Error {
     readonly code: string;
     constructor(code: string);
 }
+/**
+ * Thrown by a per-request price function to refuse a request before anything
+ * is invoiced or signed: the middleware answers with `status` and a JSON body
+ * `{ error: code, message }`. For requests the route will not serve (an
+ * unknown model, an unsupported option) rather than merchant bugs.
+ */
+declare class X402PriceRejectedError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(code: string, message: string, status?: number);
+}
+/**
+ * Recognises a price refusal by shape rather than by class identity, so a
+ * refusal thrown from another copy of this package (a nested install, the
+ * CommonJS build next to the ESM one) is still answered as a refusal.
+ */
+declare function isPriceRejection(error: unknown): error is X402PriceRejectedError;
 
-declare function createPaymentGate(config: PaymentMiddlewareConfig): (adapter: Pick<HTTPAdapter, "getHeader" | "getPath" | "getUrl" | "getMethod">) => Promise<PaymentGateResult>;
+type GateAdapter = Pick<HTTPAdapter, "getHeader" | "getPath" | "getUrl" | "getMethod" | "getBody">;
+/**
+ * Response header a handler on a metered (`upto`) route sets to the amount it
+ * actually charges, in whole token units like `price` ("0.75"). Read and
+ * stripped by the middleware before the response leaves. Absent → the cap is
+ * charged; "0" → the request is served for free (no settlement).
+ */
+declare const SETTLE_AMOUNT_HEADER = "payment-settle-amount";
+type SettleAmountResolution = {
+    kind: "settle";
+    amount: string;
+} | {
+    kind: "skip";
+} | {
+    kind: "invalid";
+    reason: "malformed" | "precision" | "above-cap" | "meter";
+};
+/**
+ * Turns the handler's `payment-settle-amount` header into a settle decision.
+ * A malformed value, one carrying more decimals than the token has, or one
+ * above the signed cap is a merchant bug: the payment fails closed rather than
+ * charging something the handler did not mean. Only an explicit zero skips
+ * the settlement — a positive amount the token cannot represent is never
+ * silently served for free.
+ */
+declare function resolveSettleAmount(raw: string | undefined, maxAmount: bigint, decimals: number): SettleAmountResolution;
+/** What the middleware can read from the handler's response. */
+interface ChargeResponse {
+    status: number;
+    header(name: string): string | undefined;
+    body(): Promise<unknown>;
+}
+/**
+ * The amount a metered route settles, once the handler answered with a 2xx.
+ * A `meter` function on the route decides first, from the response: its
+ * amount is bounded by the cap (an overrun is the merchant's loss, not a
+ * refused response), zero serves for free, and no amount hands over to the
+ * `payment-settle-amount` header, which keeps its rules (absent charges the
+ * cap, above the cap is refused). A meter that throws or returns something
+ * that is not an amount fails closed like an invalid header.
+ */
+declare function resolveCharge(verified: VerifiedPayment, settleHeader: string | undefined, response: ChargeResponse): Promise<SettleAmountResolution>;
+declare function createPaymentGate(config: PaymentMiddlewareConfig): (adapter: GateAdapter) => Promise<PaymentGateResult>;
 declare function createPaymentMiddleware(config: PaymentMiddlewareConfig): (adapter: HTTPAdapter) => Promise<MiddlewareResult | PassResult>;
 
 type ParallelNetwork = "ethereum" | "base" | "avalanche" | "hyperevm";
@@ -49,4 +108,4 @@ declare function validateAddress(address: string): address is Address;
 declare function toEip155Network(network: string): string;
 declare function encodeBase64(obj: unknown): string;
 
-export { FacilitatorClient, FacilitatorConfig, FacilitatorPaymentRequirements, FacilitatorResponse, HTTPAdapter, MiddlewareResult, PARALLEL_TOKENS, type ParallelNetwork, PassResult, PaymentGateResult, PaymentMiddlewareConfig, X402ConfigError, type X402ErrorCode, X402RuntimeError, X402_ERROR_CODES, createPaymentGate, createPaymentMiddleware, encodeBase64, getDefaultAcceptedTokens, parsePrice, toEip155Network, validateAddress };
+export { type ChargeResponse, FacilitatorClient, FacilitatorConfig, FacilitatorPaymentRequirements, FacilitatorResponse, HTTPAdapter, MiddlewareResult, PARALLEL_TOKENS, type ParallelNetwork, PassResult, PaymentGateResult, PaymentMiddlewareConfig, SETTLE_AMOUNT_HEADER, type SettleAmountResolution, SettleOptions, VerifiedPayment, X402ConfigError, type X402ErrorCode, X402PriceRejectedError, X402RuntimeError, X402_ERROR_CODES, createPaymentGate, createPaymentMiddleware, encodeBase64, getDefaultAcceptedTokens, isPriceRejection, parsePrice, resolveCharge, resolveSettleAmount, toEip155Network, validateAddress };

package/dist/index.js

@@ -1 +1,2 @@
-export { FacilitatorClient, PARALLEL_TOKENS, X402ConfigError, X402RuntimeError, X402_ERROR_CODES, createPaymentGate, createPaymentMiddleware, encodeBase64, getDefaultAcceptedTokens, parsePrice, toEip155Network, validateAddress } from './chunk-75GLDK7L.js';
+export { FacilitatorClient, PARALLEL_TOKENS, SETTLE_AMOUNT_HEADER, createPaymentGate, createPaymentMiddleware, encodeBase64, getDefaultAcceptedTokens, parsePrice, resolveCharge, resolveSettleAmount, toEip155Network, validateAddress } from './chunk-AENXD4OC.js';
+export { X402ConfigError, X402PriceRejectedError, X402RuntimeError, X402_ERROR_CODES, isPriceRejection } from './chunk-AFRDHGDT.js';