@parallel-protocol/x402 0.7.1 → 0.8.1

package/dist/fastify.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunkPOU7EH3E_cjs = require('./chunk-POU7EH3E.cjs');
-require('./chunk-JPMK5YBU.cjs');
+var chunkSNW5Z5HB_cjs = require('./chunk-SNW5Z5HB.cjs');
+require('./chunk-KZZY5LS6.cjs');
 var fp = require('fastify-plugin');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
@@ -37,12 +37,14 @@ var FastifyAdapter = class {
 // src/fastify/index.ts
 function payloadJson(contentType, payload) {
   const text = typeof payload === "string" ? payload : payload instanceof Uint8Array ? Buffer.from(payload).toString("utf8") : void 0;
-  return chunkPOU7EH3E_cjs.parseJsonBody(contentType, text);
+  return chunkSNW5Z5HB_cjs.parseJsonBody(contentType, text);
 }
-function refuse(reply, body) {
-  const json = JSON.stringify(body);
-  reply.status(402);
-  reply.header("Content-Type", "application/json");
+function refuse(reply, result) {
+  const json = JSON.stringify(result.body);
+  reply.status(result.status);
+  for (const [name, value] of Object.entries(result.headers)) {
+    reply.header(name, value);
+  }
   reply.header("Content-Length", Buffer.byteLength(json));
   return json;
 }
@@ -52,11 +54,11 @@ function headerValue(value) {
 }
 function paymentMiddleware(config) {
   return fp__default.default(async (fastify) => {
-    const gate = chunkPOU7EH3E_cjs.createPaymentGate(config);
+    const gate = chunkSNW5Z5HB_cjs.createPaymentGate(config);
     const verifiedMap = /* @__PURE__ */ new WeakMap();
     const rawWriters = /* @__PURE__ */ new WeakMap();
     const needsBody = (req) => {
-      const route = chunkPOU7EH3E_cjs.matchRoute(
+      const route = chunkSNW5Z5HB_cjs.matchRoute(
         new FastifyAdapter(req).getPath(),
         config.routes
       );
@@ -109,41 +111,30 @@ function paymentMiddleware(config) {
       if (!verified) return payload;
       let raw;
       if (verified.scheme === "upto") {
-        raw = headerValue(reply.getHeader(chunkPOU7EH3E_cjs.SETTLE_AMOUNT_HEADER));
-        reply.removeHeader(chunkPOU7EH3E_cjs.SETTLE_AMOUNT_HEADER);
+        raw = headerValue(reply.getHeader(chunkSNW5Z5HB_cjs.SETTLE_AMOUNT_HEADER));
+        reply.removeHeader(chunkSNW5Z5HB_cjs.SETTLE_AMOUNT_HEADER);
       }
       if (reply.statusCode < 200 || reply.statusCode >= 300) {
         return payload;
       }
       let settleOptions;
       if (verified.scheme === "upto") {
-        const resolved = await chunkPOU7EH3E_cjs.resolveCharge(verified, raw, {
+        const resolved = await chunkSNW5Z5HB_cjs.resolveCharge(verified, raw, {
           status: reply.statusCode,
           header: (name) => headerValue(reply.getHeader(name)),
           body: async () => payloadJson(headerValue(reply.getHeader("content-type")), payload)
         });
         if (resolved.kind === "invalid") {
-          return refuse(reply, chunkPOU7EH3E_cjs.invalidSettleAmountResponse(resolved.reason));
+          return refuse(reply, chunkSNW5Z5HB_cjs.invalidSettleAmountResponse(resolved.reason));
         }
         if (resolved.kind === "skip") return payload;
         settleOptions = { amount: resolved.amount };
       }
-      let settled = false;
-      try {
-        const settleResponse = settleOptions ? await verified.settle(settleOptions) : await verified.settle();
-        if (settleResponse.success) {
-          reply.header("payment-response", chunkPOU7EH3E_cjs.encodeBase64(settleResponse));
-          reply.header("access-control-expose-headers", "payment-response");
-          settled = true;
-        }
-      } catch {
-      }
-      if (!settled) {
-        return refuse(reply, {
-          error: "PAYMENT_SETTLEMENT_FAILED",
-          message: "Payment could not be confirmed after multiple attempts. Please retry."
-        });
-      }
+      const outcome = await chunkSNW5Z5HB_cjs.settleVerified(verified, settleOptions);
+      if (!outcome.settled)
+        return refuse(reply, chunkSNW5Z5HB_cjs.settlementFailureResponse(outcome));
+      reply.header("payment-response", chunkSNW5Z5HB_cjs.encodeBase64(outcome.confirmation));
+      reply.header("access-control-expose-headers", "payment-response");
       return payload;
     });
   });

package/dist/fastify.d.cts

@@ -1,5 +1,5 @@
 import { FastifyRequest, FastifyPluginAsync } from 'fastify';
-import { H as HTTPAdapter, P as PaymentMiddlewareConfig } from './types-q_gu5wjz.cjs';
+import { H as HTTPAdapter, P as PaymentMiddlewareConfig } from './types-BkGQ2lPA.cjs';
 import 'viem';
 
 declare class FastifyAdapter implements HTTPAdapter {

package/dist/fastify.d.ts

@@ -1,5 +1,5 @@
 import { FastifyRequest, FastifyPluginAsync } from 'fastify';
-import { H as HTTPAdapter, P as PaymentMiddlewareConfig } from './types-q_gu5wjz.js';
+import { H as HTTPAdapter, P as PaymentMiddlewareConfig } from './types-BkGQ2lPA.js';
 import 'viem';
 
 declare class FastifyAdapter implements HTTPAdapter {

package/dist/fastify.js

@@ -1,5 +1,5 @@
-import { createPaymentGate, SETTLE_AMOUNT_HEADER, resolveCharge, invalidSettleAmountResponse, encodeBase64, matchRoute, parseJsonBody } from './chunk-AENXD4OC.js';
-import './chunk-AFRDHGDT.js';
+import { createPaymentGate, SETTLE_AMOUNT_HEADER, resolveCharge, invalidSettleAmountResponse, settleVerified, settlementFailureResponse, encodeBase64, matchRoute, parseJsonBody } from './chunk-GXPUE3ES.js';
+import './chunk-QAECRSWF.js';
 import fp from 'fastify-plugin';
 
 // src/fastify/adapter.ts
@@ -33,10 +33,12 @@ function payloadJson(contentType, payload) {
   const text = typeof payload === "string" ? payload : payload instanceof Uint8Array ? Buffer.from(payload).toString("utf8") : void 0;
   return parseJsonBody(contentType, text);
 }
-function refuse(reply, body) {
-  const json = JSON.stringify(body);
-  reply.status(402);
-  reply.header("Content-Type", "application/json");
+function refuse(reply, result) {
+  const json = JSON.stringify(result.body);
+  reply.status(result.status);
+  for (const [name, value] of Object.entries(result.headers)) {
+    reply.header(name, value);
+  }
   reply.header("Content-Length", Buffer.byteLength(json));
   return json;
 }
@@ -122,22 +124,11 @@ function paymentMiddleware(config) {
         if (resolved.kind === "skip") return payload;
         settleOptions = { amount: resolved.amount };
       }
-      let settled = false;
-      try {
-        const settleResponse = settleOptions ? await verified.settle(settleOptions) : await verified.settle();
-        if (settleResponse.success) {
-          reply.header("payment-response", encodeBase64(settleResponse));
-          reply.header("access-control-expose-headers", "payment-response");
-          settled = true;
-        }
-      } catch {
-      }
-      if (!settled) {
-        return refuse(reply, {
-          error: "PAYMENT_SETTLEMENT_FAILED",
-          message: "Payment could not be confirmed after multiple attempts. Please retry."
-        });
-      }
+      const outcome = await settleVerified(verified, settleOptions);
+      if (!outcome.settled)
+        return refuse(reply, settlementFailureResponse(outcome));
+      reply.header("payment-response", encodeBase64(outcome.confirmation));
+      reply.header("access-control-expose-headers", "payment-response");
       return payload;
     });
   });

package/dist/hono.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunkPOU7EH3E_cjs = require('./chunk-POU7EH3E.cjs');
-require('./chunk-JPMK5YBU.cjs');
+var chunkSNW5Z5HB_cjs = require('./chunk-SNW5Z5HB.cjs');
+require('./chunk-KZZY5LS6.cjs');
 
 // src/hono/adapter.ts
 var TIMEOUT_BODY = JSON.stringify({
@@ -30,7 +30,7 @@ var HonoAdapter = class {
   // Hono caches the parsed body on the request, so the handler can still read
   // it after the price function did.
   async getBody() {
-    if (!chunkPOU7EH3E_cjs.isJsonContentType(this.c.req.header("content-type"))) return void 0;
+    if (!chunkSNW5Z5HB_cjs.isJsonContentType(this.c.req.header("content-type"))) return void 0;
     try {
       return await this.c.req.json();
     } catch {
@@ -38,8 +38,8 @@ var HonoAdapter = class {
     }
   }
   async runHandler(options) {
-    const outcome = await chunkPOU7EH3E_cjs.raceTimeout(this.next(), options?.timeoutMs);
-    if (outcome === chunkPOU7EH3E_cjs.HANDLER_TIMEOUT) {
+    const outcome = await chunkSNW5Z5HB_cjs.raceTimeout(this.next(), options?.timeoutMs);
+    if (outcome === chunkSNW5Z5HB_cjs.HANDLER_TIMEOUT) {
       return {
         status: 504,
         setResponseHeader: () => {
@@ -64,7 +64,7 @@ var HonoAdapter = class {
       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: () => chunkPOU7EH3E_cjs.jsonFromResponse(res),
+      getResponseBody: () => chunkSNW5Z5HB_cjs.jsonFromResponse(res),
       sendResponse: () => {
       },
       // The response is replaced: release its body (and whatever upstream
@@ -79,7 +79,7 @@ var HonoAdapter = class {
 
 // src/hono/index.ts
 function paymentMiddleware(config) {
-  const middleware = chunkPOU7EH3E_cjs.createPaymentMiddleware(config);
+  const middleware = chunkSNW5Z5HB_cjs.createPaymentMiddleware(config);
   return async (c, next) => {
     const result = await middleware(new HonoAdapter(c, next));
     if ("pass" in result) {

package/dist/hono.d.cts

@@ -1,5 +1,5 @@
 import { Context, Next, MiddlewareHandler } from 'hono';
-import { H as HTTPAdapter, R as RunHandlerOptions, a as RunHandlerResult, P as PaymentMiddlewareConfig } from './types-q_gu5wjz.cjs';
+import { H as HTTPAdapter, R as RunHandlerOptions, a as RunHandlerResult, P as PaymentMiddlewareConfig } from './types-BkGQ2lPA.cjs';
 import 'viem';
 
 declare class HonoAdapter implements HTTPAdapter {

package/dist/hono.d.ts

@@ -1,5 +1,5 @@
 import { Context, Next, MiddlewareHandler } from 'hono';
-import { H as HTTPAdapter, R as RunHandlerOptions, a as RunHandlerResult, P as PaymentMiddlewareConfig } from './types-q_gu5wjz.js';
+import { H as HTTPAdapter, R as RunHandlerOptions, a as RunHandlerResult, P as PaymentMiddlewareConfig } from './types-BkGQ2lPA.js';
 import 'viem';
 
 declare class HonoAdapter implements HTTPAdapter {

package/dist/hono.js

@@ -1,5 +1,5 @@
-import { isJsonContentType, raceTimeout, HANDLER_TIMEOUT, jsonFromResponse, createPaymentMiddleware } from './chunk-AENXD4OC.js';
-import './chunk-AFRDHGDT.js';
+import { isJsonContentType, raceTimeout, HANDLER_TIMEOUT, jsonFromResponse, createPaymentMiddleware } from './chunk-GXPUE3ES.js';
+import './chunk-QAECRSWF.js';
 
 // src/hono/adapter.ts
 var TIMEOUT_BODY = JSON.stringify({

package/dist/index.cjs

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

package/dist/index.d.cts

@@ -1,12 +1,17 @@
-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 { F as FacilitatorConfig, b as FacilitatorPaymentRequirements, V as VerifyResult, c as FacilitatorSettleOptions, d as FacilitatorResponse, e as PaymentConfirmation, P as PaymentMiddlewareConfig, H as HTTPAdapter, f as PaymentGateResult, M as MiddlewareResult, g as PassResult, h as VerifiedPayment, S as SettleOptions } from './types-BkGQ2lPA.cjs';
+export { i as MeterContext, j as MeterFunction, k as PaymentFailure, l as PaymentRequired, m as PaymentRequirements, n as PriceContext, o as PriceFunction, p as ResourceInfo, q as RouteConfig, R as RunHandlerOptions, a as RunHandlerResult } from './types-BkGQ2lPA.cjs';
 import { Address } from 'viem';
 
 declare class FacilitatorClient {
-    private readonly config;
+    private readonly url;
+    private readonly apiKey;
     constructor(config: FacilitatorConfig);
-    verify(paymentHeader: string, paymentRequirements: FacilitatorPaymentRequirements): Promise<void>;
-    settle(paymentHeader: string, paymentRequirements: FacilitatorPaymentRequirements, options?: SettleOptions): Promise<FacilitatorResponse>;
+    verify(paymentHeader: string, paymentRequirements: FacilitatorPaymentRequirements): Promise<VerifyResult>;
+    settle(paymentHeader: string, paymentRequirements: FacilitatorPaymentRequirements, options?: FacilitatorSettleOptions): Promise<FacilitatorResponse>;
+    /**
+     * @deprecated The Parallel facilitator no longer serves `/x402/pay`, so this
+     * call fails with `FACILITATOR_UNAVAILABLE`. Use `verify`, then `settle`.
+     */
     pay(paymentHeader: string): Promise<FacilitatorResponse>;
     private buildHeaders;
 }
@@ -15,6 +20,8 @@ declare const X402_ERROR_CODES: {
     readonly FACILITATOR_UNAVAILABLE: "FACILITATOR_UNAVAILABLE";
     readonly FACILITATOR_INVALID_RESPONSE: "FACILITATOR_INVALID_RESPONSE";
     readonly INVALID_PAYMENT: "INVALID_PAYMENT";
+    /** The facilitator did not answer a settle within the client's timeout: the payment may still settle. */
+    readonly SETTLE_TIMEOUT: "SETTLE_TIMEOUT";
 };
 type X402ErrorCode = (typeof X402_ERROR_CODES)[keyof typeof X402_ERROR_CODES];
 declare class X402ConfigError extends Error {
@@ -22,7 +29,17 @@ declare class X402ConfigError extends Error {
 }
 declare class X402RuntimeError extends Error {
     readonly code: string;
-    constructor(code: string);
+    /** The facilitator's message for this code, when it answered with one. */
+    readonly detail?: string;
+    /** The facilitator's HTTP status, when the error comes from its answer. */
+    readonly status?: number;
+    /** The facilitator's `Retry-After` header, when it sent one. */
+    readonly retryAfter?: string;
+    constructor(code: string, extra?: {
+        detail?: string;
+        status?: number;
+        retryAfter?: string;
+    });
 }
 /**
  * Thrown by a per-request price function to refuse a request before anything
@@ -85,6 +102,38 @@ interface ChargeResponse {
  */
 declare function resolveCharge(verified: VerifiedPayment, settleHeader: string | undefined, response: ChargeResponse): Promise<SettleAmountResolution>;
 declare function createPaymentGate(config: PaymentMiddlewareConfig): (adapter: GateAdapter) => Promise<PaymentGateResult>;
+/** The 402 body a merchant answers when a verified payment could not be settled. */
+interface SettlementFailureBody {
+    /** Kept for the clients that read it: the historical code. */
+    error: "PAYMENT_SETTLEMENT_FAILED";
+    /**
+     * The facilitator's code, or this SDK's: `SETTLE_TIMEOUT`,
+     * `FACILITATOR_UNAVAILABLE`, `FACILITATOR_INVALID_RESPONSE`,
+     * `AMOUNT_MISMATCH`, `UNKNOWN`.
+     */
+    reason: string;
+    message: string;
+}
+/** A settlement that did not confirm the payment, and what the agent is told. */
+interface SettlementFailure {
+    settled: false;
+    reason: string;
+    message: string;
+    /** The facilitator's `Retry-After`, when it sent one. */
+    retryAfter?: string;
+}
+type SettlementOutcome = {
+    settled: true;
+    confirmation: PaymentConfirmation;
+} | SettlementFailure;
+/**
+ * Settles a verified payment once the handler answered, and says what the
+ * agent must be told when it could not be. A metered settle must settle the
+ * amount this request asked for, whatever else the facilitator recorded.
+ */
+declare function settleVerified(verified: VerifiedPayment, options?: SettleOptions): Promise<SettlementOutcome>;
+/** The 402 for a settlement that failed, with the facilitator's Retry-After when it gave one. */
+declare function settlementFailureResponse(failure: SettlementFailure): MiddlewareResult;
 declare function createPaymentMiddleware(config: PaymentMiddlewareConfig): (adapter: HTTPAdapter) => Promise<MiddlewareResult | PassResult>;
 
 type ParallelNetwork = "ethereum" | "base" | "avalanche" | "hyperevm";
@@ -108,4 +157,4 @@ declare function validateAddress(address: string): address is Address;
 declare function toEip155Network(network: string): string;
 declare function encodeBase64(obj: unknown): string;
 
-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 };
+export { type ChargeResponse, FacilitatorClient, FacilitatorConfig, FacilitatorPaymentRequirements, FacilitatorResponse, FacilitatorSettleOptions, HTTPAdapter, MiddlewareResult, PARALLEL_TOKENS, type ParallelNetwork, PassResult, PaymentConfirmation, PaymentGateResult, PaymentMiddlewareConfig, SETTLE_AMOUNT_HEADER, type SettleAmountResolution, SettleOptions, type SettlementFailure, type SettlementFailureBody, type SettlementOutcome, VerifiedPayment, VerifyResult, X402ConfigError, type X402ErrorCode, X402PriceRejectedError, X402RuntimeError, X402_ERROR_CODES, createPaymentGate, createPaymentMiddleware, encodeBase64, getDefaultAcceptedTokens, isPriceRejection, parsePrice, resolveCharge, resolveSettleAmount, settleVerified, settlementFailureResponse, toEip155Network, validateAddress };

package/dist/index.d.ts

@@ -1,12 +1,17 @@
-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 { F as FacilitatorConfig, b as FacilitatorPaymentRequirements, V as VerifyResult, c as FacilitatorSettleOptions, d as FacilitatorResponse, e as PaymentConfirmation, P as PaymentMiddlewareConfig, H as HTTPAdapter, f as PaymentGateResult, M as MiddlewareResult, g as PassResult, h as VerifiedPayment, S as SettleOptions } from './types-BkGQ2lPA.js';
+export { i as MeterContext, j as MeterFunction, k as PaymentFailure, l as PaymentRequired, m as PaymentRequirements, n as PriceContext, o as PriceFunction, p as ResourceInfo, q as RouteConfig, R as RunHandlerOptions, a as RunHandlerResult } from './types-BkGQ2lPA.js';
 import { Address } from 'viem';
 
 declare class FacilitatorClient {
-    private readonly config;
+    private readonly url;
+    private readonly apiKey;
     constructor(config: FacilitatorConfig);
-    verify(paymentHeader: string, paymentRequirements: FacilitatorPaymentRequirements): Promise<void>;
-    settle(paymentHeader: string, paymentRequirements: FacilitatorPaymentRequirements, options?: SettleOptions): Promise<FacilitatorResponse>;
+    verify(paymentHeader: string, paymentRequirements: FacilitatorPaymentRequirements): Promise<VerifyResult>;
+    settle(paymentHeader: string, paymentRequirements: FacilitatorPaymentRequirements, options?: FacilitatorSettleOptions): Promise<FacilitatorResponse>;
+    /**
+     * @deprecated The Parallel facilitator no longer serves `/x402/pay`, so this
+     * call fails with `FACILITATOR_UNAVAILABLE`. Use `verify`, then `settle`.
+     */
     pay(paymentHeader: string): Promise<FacilitatorResponse>;
     private buildHeaders;
 }
@@ -15,6 +20,8 @@ declare const X402_ERROR_CODES: {
     readonly FACILITATOR_UNAVAILABLE: "FACILITATOR_UNAVAILABLE";
     readonly FACILITATOR_INVALID_RESPONSE: "FACILITATOR_INVALID_RESPONSE";
     readonly INVALID_PAYMENT: "INVALID_PAYMENT";
+    /** The facilitator did not answer a settle within the client's timeout: the payment may still settle. */
+    readonly SETTLE_TIMEOUT: "SETTLE_TIMEOUT";
 };
 type X402ErrorCode = (typeof X402_ERROR_CODES)[keyof typeof X402_ERROR_CODES];
 declare class X402ConfigError extends Error {
@@ -22,7 +29,17 @@ declare class X402ConfigError extends Error {
 }
 declare class X402RuntimeError extends Error {
     readonly code: string;
-    constructor(code: string);
+    /** The facilitator's message for this code, when it answered with one. */
+    readonly detail?: string;
+    /** The facilitator's HTTP status, when the error comes from its answer. */
+    readonly status?: number;
+    /** The facilitator's `Retry-After` header, when it sent one. */
+    readonly retryAfter?: string;
+    constructor(code: string, extra?: {
+        detail?: string;
+        status?: number;
+        retryAfter?: string;
+    });
 }
 /**
  * Thrown by a per-request price function to refuse a request before anything
@@ -85,6 +102,38 @@ interface ChargeResponse {
  */
 declare function resolveCharge(verified: VerifiedPayment, settleHeader: string | undefined, response: ChargeResponse): Promise<SettleAmountResolution>;
 declare function createPaymentGate(config: PaymentMiddlewareConfig): (adapter: GateAdapter) => Promise<PaymentGateResult>;
+/** The 402 body a merchant answers when a verified payment could not be settled. */
+interface SettlementFailureBody {
+    /** Kept for the clients that read it: the historical code. */
+    error: "PAYMENT_SETTLEMENT_FAILED";
+    /**
+     * The facilitator's code, or this SDK's: `SETTLE_TIMEOUT`,
+     * `FACILITATOR_UNAVAILABLE`, `FACILITATOR_INVALID_RESPONSE`,
+     * `AMOUNT_MISMATCH`, `UNKNOWN`.
+     */
+    reason: string;
+    message: string;
+}
+/** A settlement that did not confirm the payment, and what the agent is told. */
+interface SettlementFailure {
+    settled: false;
+    reason: string;
+    message: string;
+    /** The facilitator's `Retry-After`, when it sent one. */
+    retryAfter?: string;
+}
+type SettlementOutcome = {
+    settled: true;
+    confirmation: PaymentConfirmation;
+} | SettlementFailure;
+/**
+ * Settles a verified payment once the handler answered, and says what the
+ * agent must be told when it could not be. A metered settle must settle the
+ * amount this request asked for, whatever else the facilitator recorded.
+ */
+declare function settleVerified(verified: VerifiedPayment, options?: SettleOptions): Promise<SettlementOutcome>;
+/** The 402 for a settlement that failed, with the facilitator's Retry-After when it gave one. */
+declare function settlementFailureResponse(failure: SettlementFailure): MiddlewareResult;
 declare function createPaymentMiddleware(config: PaymentMiddlewareConfig): (adapter: HTTPAdapter) => Promise<MiddlewareResult | PassResult>;
 
 type ParallelNetwork = "ethereum" | "base" | "avalanche" | "hyperevm";
@@ -108,4 +157,4 @@ declare function validateAddress(address: string): address is Address;
 declare function toEip155Network(network: string): string;
 declare function encodeBase64(obj: unknown): string;
 
-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 };
+export { type ChargeResponse, FacilitatorClient, FacilitatorConfig, FacilitatorPaymentRequirements, FacilitatorResponse, FacilitatorSettleOptions, HTTPAdapter, MiddlewareResult, PARALLEL_TOKENS, type ParallelNetwork, PassResult, PaymentConfirmation, PaymentGateResult, PaymentMiddlewareConfig, SETTLE_AMOUNT_HEADER, type SettleAmountResolution, SettleOptions, type SettlementFailure, type SettlementFailureBody, type SettlementOutcome, VerifiedPayment, VerifyResult, X402ConfigError, type X402ErrorCode, X402PriceRejectedError, X402RuntimeError, X402_ERROR_CODES, createPaymentGate, createPaymentMiddleware, encodeBase64, getDefaultAcceptedTokens, isPriceRejection, parsePrice, resolveCharge, resolveSettleAmount, settleVerified, settlementFailureResponse, toEip155Network, validateAddress };

package/dist/index.js

@@ -1,2 +1,2 @@
-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';
+export { FacilitatorClient, PARALLEL_TOKENS, SETTLE_AMOUNT_HEADER, createPaymentGate, createPaymentMiddleware, encodeBase64, getDefaultAcceptedTokens, parsePrice, resolveCharge, resolveSettleAmount, settleVerified, settlementFailureResponse, toEip155Network, validateAddress } from './chunk-GXPUE3ES.js';
+export { X402ConfigError, X402PriceRejectedError, X402RuntimeError, X402_ERROR_CODES, isPriceRejection } from './chunk-QAECRSWF.js';

package/dist/llm.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkJPMK5YBU_cjs = require('./chunk-JPMK5YBU.cjs');
+var chunkKZZY5LS6_cjs = require('./chunk-KZZY5LS6.cjs');
 
 // src/llm/estimate.ts
 function estimateTokens(text) {
@@ -71,7 +71,7 @@ function lookup(table, model) {
 function staticPrices(table) {
   for (const [model, price] of Object.entries(table)) {
     if (!isValidPrice(price)) {
-      throw new chunkJPMK5YBU_cjs.X402ConfigError(
+      throw new chunkKZZY5LS6_cjs.X402ConfigError(
         `Invalid price for model "${model}": expected { input, output } in USD per million tokens`
       );
     }
@@ -106,13 +106,13 @@ function shortName(value) {
 function parseDuration(value) {
   if (typeof value === "number") {
     if (!Number.isFinite(value) || value < 0) {
-      throw new chunkJPMK5YBU_cjs.X402ConfigError(`Invalid duration: ${value}`);
+      throw new chunkKZZY5LS6_cjs.X402ConfigError(`Invalid duration: ${value}`);
     }
     return value;
   }
   const match = value.trim().match(/^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)$/i);
   if (!match) {
-    throw new chunkJPMK5YBU_cjs.X402ConfigError(
+    throw new chunkKZZY5LS6_cjs.X402ConfigError(
       `Invalid duration "${value}": expected a number of milliseconds or a value like "24h", "30m", "10s"`
     );
   }
@@ -180,7 +180,7 @@ function openRouterPrices(options = {}) {
         if (canRetry()) await load().catch(() => {
         });
         if (!table) {
-          throw new chunkJPMK5YBU_cjs.X402PriceRejectedError(
+          throw new chunkKZZY5LS6_cjs.X402PriceRejectedError(
             "PRICING_UNAVAILABLE",
             "Model prices are not available right now, retry shortly",
             503
@@ -197,7 +197,7 @@ function openRouterPrices(options = {}) {
         });
       }
       if (inflight) {
-        throw new chunkJPMK5YBU_cjs.X402PriceRejectedError(
+        throw new chunkKZZY5LS6_cjs.X402PriceRejectedError(
           "UNKNOWN_MODEL",
           `No price known for model "${shortName(model)}" yet. The price list is being refreshed, retry in a few seconds.`
         );
@@ -210,7 +210,7 @@ function openRouterPrices(options = {}) {
 // src/llm/cap.ts
 var DEFAULT_MARGIN = 0;
 function reject(code, message) {
-  throw new chunkJPMK5YBU_cjs.X402PriceRejectedError(code, message);
+  throw new chunkKZZY5LS6_cjs.X402PriceRejectedError(code, message);
 }
 function isTextOnly(modalities) {
   return Array.isArray(modalities) && modalities.every((modality) => modality === "text");
@@ -222,17 +222,17 @@ function chatCompletionCap(options) {
   const allowed = options.models ? new Set(options.models) : void 0;
   const estimate = options.estimateInputTokens ?? estimateInputTokens;
   if (positiveInteger(maxOutputTokens) === void 0) {
-    throw new chunkJPMK5YBU_cjs.X402ConfigError(
+    throw new chunkKZZY5LS6_cjs.X402ConfigError(
       `chatCompletionCap: maxOutputTokens must be a positive integer, got ${maxOutputTokens}`
     );
   }
   if (!Number.isFinite(margin) || margin < 0) {
-    throw new chunkJPMK5YBU_cjs.X402ConfigError(
+    throw new chunkKZZY5LS6_cjs.X402ConfigError(
       `chatCompletionCap: margin must be a non-negative number, got ${margin}`
     );
   }
   if (allowed?.size === 0) {
-    throw new chunkJPMK5YBU_cjs.X402ConfigError("chatCompletionCap: models must not be empty");
+    throw new chunkKZZY5LS6_cjs.X402ConfigError("chatCompletionCap: models must not be empty");
   }
   return async (ctx) => {
     const raw = ctx.body;
@@ -295,7 +295,7 @@ function chatCompletionCap(options) {
       reject("UNKNOWN_MODEL", `No price known for model "${shortName(model)}"`);
     }
     if (!isValidPrice(price)) {
-      throw new chunkJPMK5YBU_cjs.X402ConfigError(
+      throw new chunkKZZY5LS6_cjs.X402ConfigError(
         `chatCompletionCap: the price source returned an invalid price for model "${shortName(model)}"`
       );
     }
@@ -343,13 +343,13 @@ var failure = (status, error, message) => ({
 });
 async function forwardChatCompletion(body, options) {
   if (typeof options.baseUrl !== "string" || !URL.canParse(options.baseUrl)) {
-    throw new chunkJPMK5YBU_cjs.X402ConfigError(
+    throw new chunkKZZY5LS6_cjs.X402ConfigError(
       `forwardChatCompletion: baseUrl must be a URL, got ${JSON.stringify(options.baseUrl)}`
     );
   }
   const maxOutputTokens = options.maxOutputTokens ?? DEFAULT_MAX_OUTPUT_TOKENS;
   if (positiveInteger(maxOutputTokens) === void 0) {
-    throw new chunkJPMK5YBU_cjs.X402ConfigError(
+    throw new chunkKZZY5LS6_cjs.X402ConfigError(
       `forwardChatCompletion: maxOutputTokens must be a positive integer, got ${maxOutputTokens}`
     );
   }