@parallel-protocol/x402 0.5.3 → 0.6.0

package/dist/next.cjs

@@ -1,7 +1,6 @@
 'use strict';
 
-var chunkXUNNMCO5_cjs = require('./chunk-XUNNMCO5.cjs');
-var chunkKQPIZ6SZ_cjs = require('./chunk-KQPIZ6SZ.cjs');
+var chunkK6QETMQA_cjs = require('./chunk-K6QETMQA.cjs');
 var server = require('next/server');
 
 // src/next/adapter.ts
@@ -26,7 +25,7 @@ var NextAdapter = class {
 
 // src/next/index.ts
 function withPayment(config, handler) {
-  const gate = chunkKQPIZ6SZ_cjs.createPaymentGate(config);
+  const gate = chunkK6QETMQA_cjs.createPaymentGate(config);
   return async (req) => {
     const gateResult = await gate(new NextAdapter(req));
     if (gateResult.type === "pass") {
@@ -43,20 +42,50 @@ function withPayment(config, handler) {
     }
     let response;
     try {
-      const outcome = await chunkXUNNMCO5_cjs.raceTimeout(handler(req));
-      if (outcome === chunkXUNNMCO5_cjs.HANDLER_TIMEOUT) {
+      const outcome = await chunkK6QETMQA_cjs.raceTimeout(
+        handler(req),
+        gateResult.handlerTimeoutMs
+      );
+      if (outcome === chunkK6QETMQA_cjs.HANDLER_TIMEOUT) {
         return new server.NextResponse(null, { status: 504 });
       }
       response = outcome;
     } catch {
       return new server.NextResponse(null, { status: 504 });
     }
+    let raw;
+    if (gateResult.scheme === "upto") {
+      raw = response.headers.get(chunkK6QETMQA_cjs.SETTLE_AMOUNT_HEADER) ?? void 0;
+      if (raw !== void 0) {
+        const headers = new Headers(response.headers);
+        headers.delete(chunkK6QETMQA_cjs.SETTLE_AMOUNT_HEADER);
+        response = new server.NextResponse(response.body, {
+          status: response.status,
+          headers
+        });
+      }
+    }
     if (response.status >= 200 && response.status < 300) {
+      let settleOptions;
+      if (gateResult.scheme === "upto") {
+        const resolved = chunkK6QETMQA_cjs.resolveSettleAmount(
+          raw,
+          gateResult.maxAmount,
+          gateResult.decimals
+        );
+        if (resolved.kind === "invalid") {
+          return server.NextResponse.json(chunkK6QETMQA_cjs.INVALID_SETTLE_AMOUNT_RESPONSE, {
+            status: 402
+          });
+        }
+        if (resolved.kind === "skip") return response;
+        settleOptions = { amount: resolved.amount };
+      }
       try {
-        const settleResponse = await gateResult.settle();
+        const settleResponse = settleOptions ? await gateResult.settle(settleOptions) : await gateResult.settle();
         if (settleResponse.success) {
           const headers = new Headers(response.headers);
-          headers.set("payment-response", chunkKQPIZ6SZ_cjs.encodeBase64(settleResponse));
+          headers.set("payment-response", chunkK6QETMQA_cjs.encodeBase64(settleResponse));
           headers.set("access-control-expose-headers", "payment-response");
           return new server.NextResponse(response.body, {
             status: response.status,

package/dist/next.d.cts

@@ -1,5 +1,5 @@
 import { NextRequest, NextResponse } from 'next/server';
-import { H as HTTPAdapter, P as PaymentMiddlewareConfig } from './types-CUi55YSx.cjs';
+import { H as HTTPAdapter, P as PaymentMiddlewareConfig } from './types-CBzm5CtM.cjs';
 import 'viem';
 
 declare class NextAdapter implements HTTPAdapter {

package/dist/next.d.ts

@@ -1,5 +1,5 @@
 import { NextRequest, NextResponse } from 'next/server';
-import { H as HTTPAdapter, P as PaymentMiddlewareConfig } from './types-CUi55YSx.js';
+import { H as HTTPAdapter, P as PaymentMiddlewareConfig } from './types-CBzm5CtM.js';
 import 'viem';
 
 declare class NextAdapter implements HTTPAdapter {

package/dist/next.js

@@ -1,5 +1,4 @@
-import { raceTimeout, HANDLER_TIMEOUT } from './chunk-2UEAVMCH.js';
-import { createPaymentGate, encodeBase64 } from './chunk-75GLDK7L.js';
+import { createPaymentGate, raceTimeout, HANDLER_TIMEOUT, SETTLE_AMOUNT_HEADER, resolveSettleAmount, INVALID_SETTLE_AMOUNT_RESPONSE, encodeBase64 } from './chunk-TLCEPWQI.js';
 import { NextResponse } from 'next/server';
 
 // src/next/adapter.ts
@@ -41,7 +40,10 @@ function withPayment(config, handler) {
     }
     let response;
     try {
-      const outcome = await raceTimeout(handler(req));
+      const outcome = await raceTimeout(
+        handler(req),
+        gateResult.handlerTimeoutMs
+      );
       if (outcome === HANDLER_TIMEOUT) {
         return new NextResponse(null, { status: 504 });
       }
@@ -49,9 +51,36 @@ function withPayment(config, handler) {
     } catch {
       return new NextResponse(null, { status: 504 });
     }
+    let raw;
+    if (gateResult.scheme === "upto") {
+      raw = response.headers.get(SETTLE_AMOUNT_HEADER) ?? void 0;
+      if (raw !== void 0) {
+        const headers = new Headers(response.headers);
+        headers.delete(SETTLE_AMOUNT_HEADER);
+        response = new NextResponse(response.body, {
+          status: response.status,
+          headers
+        });
+      }
+    }
     if (response.status >= 200 && response.status < 300) {
+      let settleOptions;
+      if (gateResult.scheme === "upto") {
+        const resolved = resolveSettleAmount(
+          raw,
+          gateResult.maxAmount,
+          gateResult.decimals
+        );
+        if (resolved.kind === "invalid") {
+          return NextResponse.json(INVALID_SETTLE_AMOUNT_RESPONSE, {
+            status: 402
+          });
+        }
+        if (resolved.kind === "skip") return response;
+        settleOptions = { amount: resolved.amount };
+      }
       try {
-        const settleResponse = await gateResult.settle();
+        const settleResponse = settleOptions ? await gateResult.settle(settleOptions) : await gateResult.settle();
         if (settleResponse.success) {
           const headers = new Headers(response.headers);
           headers.set("payment-response", encodeBase64(settleResponse));

package/dist/types-CBzm5CtM.d.cts

@@ -0,0 +1,131 @@
+import { Address } from 'viem';
+
+interface FacilitatorConfig {
+    url: string;
+    apiKey?: string;
+}
+interface RouteConfig {
+    price: string | bigint;
+    decimals?: number;
+    network: string;
+    payTo: Address;
+    acceptedTokens?: Address[];
+    description?: string;
+    /**
+     * `exact` (default) charges `price` as invoiced. `upto` invoices `price` as a
+     * cap: the handler decides the actual amount through the
+     * `payment-settle-amount` response header and the remainder is refunded.
+     */
+    scheme?: "exact" | "upto";
+    /**
+     * Settlement window the payer signs for, in seconds (default 300). Metered
+     * routes announce how long their handler may take; the facilitator caps it
+     * at 3600. The handler must finish comfortably before it expires.
+     */
+    maxTimeoutSeconds?: number;
+}
+interface PaymentMiddlewareConfig {
+    facilitator: FacilitatorConfig;
+    routes: Record<string, RouteConfig>;
+}
+interface RunHandlerOptions {
+    /** Handler timeout for this request; defaults to the adapter's 30 s. */
+    timeoutMs?: number;
+}
+interface RunHandlerResult {
+    status: number;
+    setResponseHeader(name: string, value: string): void;
+    /** Reads a header the handler set on its response (metered routes). */
+    getResponseHeader?(name: string): string | undefined;
+    /** Strips a header before the response leaves (metered routes). */
+    removeResponseHeader?(name: string): void;
+    sendResponse(): void;
+    discardResponse(): void;
+}
+interface HTTPAdapter {
+    getHeader(name: string): string | undefined;
+    getMethod(): string;
+    getPath(): string;
+    getUrl(): string;
+    runHandler?(options?: RunHandlerOptions): Promise<RunHandlerResult>;
+}
+interface ResourceInfo {
+    url: string;
+    description?: string;
+    mimeType?: string;
+}
+interface PaymentRequirements {
+    scheme: string;
+    network: string;
+    asset: string;
+    amount: string;
+    payTo: string;
+    maxTimeoutSeconds: number;
+    extra: Record<string, unknown>;
+}
+interface PaymentRequired {
+    x402Version: number;
+    error?: string;
+    resource: ResourceInfo;
+    accepts: PaymentRequirements[];
+    extensions?: Record<string, unknown>;
+}
+interface FacilitatorPaymentRequirements {
+    maxAmountRequired: string;
+    asset: string;
+    payTo: string;
+    network: string;
+    scheme?: "exact" | "upto";
+    maxTimeoutSeconds?: number;
+}
+/** Settle-time options — only metered (`upto`) routes use them. */
+interface SettleOptions {
+    /** Amount actually charged, in the asset's smallest unit. */
+    amount?: string;
+}
+interface PaymentConfirmation {
+    success: true;
+    txHash: Address;
+    route: string;
+    chain: string;
+    gasSponsored: boolean;
+    networkId: string;
+    /** Amount actually charged (smallest unit) — metered routes only. */
+    amountSettled?: string;
+}
+interface PaymentFailure {
+    success: false;
+    error: {
+        code: string;
+        message: string;
+        hint?: string;
+    };
+}
+type FacilitatorResponse = PaymentConfirmation | PaymentFailure;
+interface MiddlewareResult {
+    status: number;
+    headers: Record<string, string>;
+    body: unknown;
+}
+interface PassResult {
+    pass: true;
+    handlerRan?: true;
+}
+type VerifiedPayment = {
+    type: "verified";
+    scheme: "exact" | "upto";
+    /** The verified amount (smallest unit): the price, or the cap for `upto`. */
+    maxAmount: bigint;
+    decimals: number;
+    /** How long the handler may run before the middleware gives up on it. */
+    handlerTimeoutMs: number;
+    settle(options?: SettleOptions): Promise<FacilitatorResponse>;
+};
+type PaymentGateResult = {
+    type: "pass";
+} | {
+    type: "error";
+    result: MiddlewareResult;
+} | VerifiedPayment;
+
+export type { FacilitatorConfig as F, HTTPAdapter as H, MiddlewareResult as M, PaymentMiddlewareConfig as P, RunHandlerOptions as R, SettleOptions as S, VerifiedPayment as V, RunHandlerResult as a, FacilitatorPaymentRequirements as b, FacilitatorResponse as c, PaymentGateResult as d, PassResult as e, PaymentConfirmation as f, PaymentFailure as g, PaymentRequired as h, PaymentRequirements as i, ResourceInfo as j, RouteConfig as k };

package/dist/types-CBzm5CtM.d.ts

@@ -0,0 +1,131 @@
+import { Address } from 'viem';
+
+interface FacilitatorConfig {
+    url: string;
+    apiKey?: string;
+}
+interface RouteConfig {
+    price: string | bigint;
+    decimals?: number;
+    network: string;
+    payTo: Address;
+    acceptedTokens?: Address[];
+    description?: string;
+    /**
+     * `exact` (default) charges `price` as invoiced. `upto` invoices `price` as a
+     * cap: the handler decides the actual amount through the
+     * `payment-settle-amount` response header and the remainder is refunded.
+     */
+    scheme?: "exact" | "upto";
+    /**
+     * Settlement window the payer signs for, in seconds (default 300). Metered
+     * routes announce how long their handler may take; the facilitator caps it
+     * at 3600. The handler must finish comfortably before it expires.
+     */
+    maxTimeoutSeconds?: number;
+}
+interface PaymentMiddlewareConfig {
+    facilitator: FacilitatorConfig;
+    routes: Record<string, RouteConfig>;
+}
+interface RunHandlerOptions {
+    /** Handler timeout for this request; defaults to the adapter's 30 s. */
+    timeoutMs?: number;
+}
+interface RunHandlerResult {
+    status: number;
+    setResponseHeader(name: string, value: string): void;
+    /** Reads a header the handler set on its response (metered routes). */
+    getResponseHeader?(name: string): string | undefined;
+    /** Strips a header before the response leaves (metered routes). */
+    removeResponseHeader?(name: string): void;
+    sendResponse(): void;
+    discardResponse(): void;
+}
+interface HTTPAdapter {
+    getHeader(name: string): string | undefined;
+    getMethod(): string;
+    getPath(): string;
+    getUrl(): string;
+    runHandler?(options?: RunHandlerOptions): Promise<RunHandlerResult>;
+}
+interface ResourceInfo {
+    url: string;
+    description?: string;
+    mimeType?: string;
+}
+interface PaymentRequirements {
+    scheme: string;
+    network: string;
+    asset: string;
+    amount: string;
+    payTo: string;
+    maxTimeoutSeconds: number;
+    extra: Record<string, unknown>;
+}
+interface PaymentRequired {
+    x402Version: number;
+    error?: string;
+    resource: ResourceInfo;
+    accepts: PaymentRequirements[];
+    extensions?: Record<string, unknown>;
+}
+interface FacilitatorPaymentRequirements {
+    maxAmountRequired: string;
+    asset: string;
+    payTo: string;
+    network: string;
+    scheme?: "exact" | "upto";
+    maxTimeoutSeconds?: number;
+}
+/** Settle-time options — only metered (`upto`) routes use them. */
+interface SettleOptions {
+    /** Amount actually charged, in the asset's smallest unit. */
+    amount?: string;
+}
+interface PaymentConfirmation {
+    success: true;
+    txHash: Address;
+    route: string;
+    chain: string;
+    gasSponsored: boolean;
+    networkId: string;
+    /** Amount actually charged (smallest unit) — metered routes only. */
+    amountSettled?: string;
+}
+interface PaymentFailure {
+    success: false;
+    error: {
+        code: string;
+        message: string;
+        hint?: string;
+    };
+}
+type FacilitatorResponse = PaymentConfirmation | PaymentFailure;
+interface MiddlewareResult {
+    status: number;
+    headers: Record<string, string>;
+    body: unknown;
+}
+interface PassResult {
+    pass: true;
+    handlerRan?: true;
+}
+type VerifiedPayment = {
+    type: "verified";
+    scheme: "exact" | "upto";
+    /** The verified amount (smallest unit): the price, or the cap for `upto`. */
+    maxAmount: bigint;
+    decimals: number;
+    /** How long the handler may run before the middleware gives up on it. */
+    handlerTimeoutMs: number;
+    settle(options?: SettleOptions): Promise<FacilitatorResponse>;
+};
+type PaymentGateResult = {
+    type: "pass";
+} | {
+    type: "error";
+    result: MiddlewareResult;
+} | VerifiedPayment;
+
+export type { FacilitatorConfig as F, HTTPAdapter as H, MiddlewareResult as M, PaymentMiddlewareConfig as P, RunHandlerOptions as R, SettleOptions as S, VerifiedPayment as V, RunHandlerResult as a, FacilitatorPaymentRequirements as b, FacilitatorResponse as c, PaymentGateResult as d, PassResult as e, PaymentConfirmation as f, PaymentFailure as g, PaymentRequired as h, PaymentRequirements as i, ResourceInfo as j, RouteConfig as k };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@parallel-protocol/x402",
-	"version": "0.5.3",
+	"version": "0.6.0",
 	"description": "Parallel Protocol x402 payment middleware — Express, Next.js, Fastify, Hono",
 	"author": "Parallel Protocol <contact@parallel.best>",
 	"repository": {
@@ -123,7 +123,7 @@
 		"vitest": "^4.0.14"
 	},
 	"dependencies": {
-		"@parallel-protocol/chains": "^0.3.0",
+		"@parallel-protocol/chains": "^0.4.0",
 		"fastify-plugin": "^6.0.0",
 		"zod": "^4.4.3"
 	},

package/dist/chunk-2UEAVMCH.js

@@ -1,17 +0,0 @@
-// src/timeout.ts
-var HANDLER_TIMEOUT_MS = 3e4;
-var HANDLER_TIMEOUT = /* @__PURE__ */ Symbol("x402:handler-timeout");
-async function raceTimeout(promise, ms = HANDLER_TIMEOUT_MS) {
-  let timer;
-  const timeout = new Promise((resolve) => {
-    timer = setTimeout(() => resolve(HANDLER_TIMEOUT), ms);
-    timer.unref?.();
-  });
-  try {
-    return await Promise.race([promise, timeout]);
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
-export { HANDLER_TIMEOUT, raceTimeout };

package/dist/chunk-XUNNMCO5.cjs

@@ -1,20 +0,0 @@
-'use strict';
-
-// src/timeout.ts
-var HANDLER_TIMEOUT_MS = 3e4;
-var HANDLER_TIMEOUT = /* @__PURE__ */ Symbol("x402:handler-timeout");
-async function raceTimeout(promise, ms = HANDLER_TIMEOUT_MS) {
-  let timer;
-  const timeout = new Promise((resolve) => {
-    timer = setTimeout(() => resolve(HANDLER_TIMEOUT), ms);
-    timer.unref?.();
-  });
-  try {
-    return await Promise.race([promise, timeout]);
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
-exports.HANDLER_TIMEOUT = HANDLER_TIMEOUT;
-exports.raceTimeout = raceTimeout;

package/dist/types-CUi55YSx.d.cts

@@ -1,95 +0,0 @@
-import { Address } from 'viem';
-
-interface FacilitatorConfig {
-    url: string;
-    apiKey?: string;
-}
-interface RouteConfig {
-    price: string | bigint;
-    decimals?: number;
-    network: string;
-    payTo: Address;
-    acceptedTokens?: Address[];
-    description?: string;
-}
-interface PaymentMiddlewareConfig {
-    facilitator: FacilitatorConfig;
-    routes: Record<string, RouteConfig>;
-}
-interface RunHandlerResult {
-    status: number;
-    setResponseHeader(name: string, value: string): void;
-    sendResponse(): void;
-    discardResponse(): void;
-}
-interface HTTPAdapter {
-    getHeader(name: string): string | undefined;
-    getMethod(): string;
-    getPath(): string;
-    getUrl(): string;
-    runHandler?(): Promise<RunHandlerResult>;
-}
-interface ResourceInfo {
-    url: string;
-    description?: string;
-    mimeType?: string;
-}
-interface PaymentRequirements {
-    scheme: string;
-    network: string;
-    asset: string;
-    amount: string;
-    payTo: string;
-    maxTimeoutSeconds: number;
-    extra: Record<string, unknown>;
-}
-interface PaymentRequired {
-    x402Version: number;
-    error?: string;
-    resource: ResourceInfo;
-    accepts: PaymentRequirements[];
-    extensions?: Record<string, unknown>;
-}
-interface FacilitatorPaymentRequirements {
-    maxAmountRequired: string;
-    asset: string;
-    payTo: string;
-    network: string;
-}
-interface PaymentConfirmation {
-    success: true;
-    txHash: Address;
-    route: string;
-    chain: string;
-    gasSponsored: boolean;
-    networkId: string;
-}
-interface PaymentFailure {
-    success: false;
-    error: {
-        code: string;
-        message: string;
-        hint?: string;
-    };
-}
-type FacilitatorResponse = PaymentConfirmation | PaymentFailure;
-interface MiddlewareResult {
-    status: number;
-    headers: Record<string, string>;
-    body: unknown;
-}
-interface PassResult {
-    pass: true;
-    handlerRan?: true;
-}
-type PaymentGateResult = {
-    type: "pass";
-} | {
-    type: "error";
-    result: MiddlewareResult;
-} | {
-    type: "verified";
-    settle(): Promise<FacilitatorResponse>;
-};
-
-export type { FacilitatorConfig as F, HTTPAdapter as H, MiddlewareResult as M, PaymentMiddlewareConfig as P, RunHandlerResult as R, FacilitatorPaymentRequirements as a, FacilitatorResponse as b, PaymentGateResult as c, PassResult as d, PaymentConfirmation as e, PaymentFailure as f, PaymentRequired as g, PaymentRequirements as h, ResourceInfo as i, RouteConfig as j };

package/dist/types-CUi55YSx.d.ts

@@ -1,95 +0,0 @@
-import { Address } from 'viem';
-
-interface FacilitatorConfig {
-    url: string;
-    apiKey?: string;
-}
-interface RouteConfig {
-    price: string | bigint;
-    decimals?: number;
-    network: string;
-    payTo: Address;
-    acceptedTokens?: Address[];
-    description?: string;
-}
-interface PaymentMiddlewareConfig {
-    facilitator: FacilitatorConfig;
-    routes: Record<string, RouteConfig>;
-}
-interface RunHandlerResult {
-    status: number;
-    setResponseHeader(name: string, value: string): void;
-    sendResponse(): void;
-    discardResponse(): void;
-}
-interface HTTPAdapter {
-    getHeader(name: string): string | undefined;
-    getMethod(): string;
-    getPath(): string;
-    getUrl(): string;
-    runHandler?(): Promise<RunHandlerResult>;
-}
-interface ResourceInfo {
-    url: string;
-    description?: string;
-    mimeType?: string;
-}
-interface PaymentRequirements {
-    scheme: string;
-    network: string;
-    asset: string;
-    amount: string;
-    payTo: string;
-    maxTimeoutSeconds: number;
-    extra: Record<string, unknown>;
-}
-interface PaymentRequired {
-    x402Version: number;
-    error?: string;
-    resource: ResourceInfo;
-    accepts: PaymentRequirements[];
-    extensions?: Record<string, unknown>;
-}
-interface FacilitatorPaymentRequirements {
-    maxAmountRequired: string;
-    asset: string;
-    payTo: string;
-    network: string;
-}
-interface PaymentConfirmation {
-    success: true;
-    txHash: Address;
-    route: string;
-    chain: string;
-    gasSponsored: boolean;
-    networkId: string;
-}
-interface PaymentFailure {
-    success: false;
-    error: {
-        code: string;
-        message: string;
-        hint?: string;
-    };
-}
-type FacilitatorResponse = PaymentConfirmation | PaymentFailure;
-interface MiddlewareResult {
-    status: number;
-    headers: Record<string, string>;
-    body: unknown;
-}
-interface PassResult {
-    pass: true;
-    handlerRan?: true;
-}
-type PaymentGateResult = {
-    type: "pass";
-} | {
-    type: "error";
-    result: MiddlewareResult;
-} | {
-    type: "verified";
-    settle(): Promise<FacilitatorResponse>;
-};
-
-export type { FacilitatorConfig as F, HTTPAdapter as H, MiddlewareResult as M, PaymentMiddlewareConfig as P, RunHandlerResult as R, FacilitatorPaymentRequirements as a, FacilitatorResponse as b, PaymentGateResult as c, PassResult as d, PaymentConfirmation as e, PaymentFailure as f, PaymentRequired as g, PaymentRequirements as h, ResourceInfo as i, RouteConfig as j };