@faremeter/middleware 0.15.0 → 0.17.0

package/dist/src/common.js

@@ -1,26 +1,69 @@
 import { isValidationError } from "@faremeter/types";
-import { x402PaymentRequiredResponse, x402PaymentHeaderToPayload, x402VerifyRequest, x402VerifyResponse, x402SettleRequest, x402SettleResponse, } from "@faremeter/types/x402";
+import { x402PaymentRequiredResponseLenient, normalizePaymentRequiredResponse, x402PaymentHeaderToPayload as x402PaymentHeaderToPayloadV1, x402VerifyRequest as x402VerifyRequestV1, x402VerifyResponseLenient, normalizeVerifyResponse, x402SettleRequest as x402SettleRequestV1, x402SettleResponse as x402SettleResponseV1, x402SettleResponseLenient, normalizeSettleResponse, X_PAYMENT_HEADER, X_PAYMENT_RESPONSE_HEADER, } from "@faremeter/types/x402";
+import { x402PaymentRequiredResponse, x402PaymentHeaderToPayload, x402VerifyRequest, x402VerifyResponse, x402SettleRequest, x402SettleResponse, V2_PAYMENT_HEADER, V2_PAYMENT_REQUIRED_HEADER, V2_PAYMENT_RESPONSE_HEADER, } from "@faremeter/types/x402v2";
+import { adaptPaymentRequiredResponseV1ToV2, adaptPaymentRequiredResponseV2ToV1, } from "@faremeter/types/x402-adapters";
+import { normalizeNetworkId } from "@faremeter/info";
 import { AgedLRUCache } from "./cache.js";
 import { logger } from "./logger.js";
-export function findMatchingPaymentRequirements(accepts, payload) {
-    let possible;
-    if (payload.asset !== undefined) {
-        // Narrow based on the asset if available.
-        possible = accepts.filter((x) => x.network === payload.network &&
-            x.scheme === payload.scheme &&
-            x.asset === payload.asset);
+/**
+ * Build the X-PAYMENT-RESPONSE header value from a settle response.
+ *
+ * The header uses spec-compliant field names: `transaction`, `network`,
+ * and `errorReason`.
+ */
+function buildPaymentResponseHeader(settlementResponse) {
+    const headerPayload = {
+        success: settlementResponse.success,
+        transaction: settlementResponse.transaction ?? "",
+        network: settlementResponse.network ?? "",
+    };
+    if (settlementResponse.payer !== undefined) {
+        headerPayload.payer = settlementResponse.payer;
     }
-    else {
-        // Otherwise fall back to the behavior in coinbase/x402.
-        possible = accepts.filter((x) => x.network === payload.network && x.scheme === payload.scheme);
+    if (!settlementResponse.success &&
+        settlementResponse.errorReason !== undefined) {
+        headerPayload.errorReason = settlementResponse.errorReason;
     }
+    return btoa(JSON.stringify(headerPayload));
+}
+function findMatching(accepts, criteria, label, payload) {
+    const possible = criteria.asset !== undefined
+        ? accepts.filter((x) => x.network === criteria.network &&
+            x.scheme === criteria.scheme &&
+            x.asset === criteria.asset)
+        : accepts.filter((x) => x.network === criteria.network && x.scheme === criteria.scheme);
     if (possible.length > 1) {
-        logger.warning(`found ${possible.length} ambiguous matching requirements for client payment: {*}`, payload);
+        logger.warning(`found ${possible.length} ambiguous matching requirements for ${label} client payment`, payload);
     }
     // XXX - If there are more than one, this really should be an error.
     // For now, err on the side of potential compatibility.
     return possible[0];
 }
+/**
+ * Finds the payment requirement that matches the client's v1 payment payload.
+ *
+ * @param accepts - Array of accepted payment requirements from the facilitator
+ * @param payload - The client's payment payload
+ * @returns The matching requirement, or undefined if no match found
+ */
+export function findMatchingPaymentRequirements(accepts, payload) {
+    return findMatching(accepts, payload, "v1", payload);
+}
+/**
+ * Finds the payment requirement that matches the client's v2 payment payload.
+ *
+ * @param accepts - Array of accepted payment requirements from the facilitator
+ * @param payload - The client's v2 payment payload
+ * @returns The matching requirement, or undefined if no match found
+ */
+export function findMatchingPaymentRequirementsV2(accepts, payload) {
+    return findMatching(accepts, payload.accepted, "v2", payload);
+}
+/**
+ * Validates that a facilitator response is successful, throwing if not.
+ *
+ * @param res - The Response from the facilitator
+ */
 export function gateGetPaymentRequiredResponse(res) {
     if (res.status === 200) {
         return;
@@ -29,12 +72,61 @@ export function gateGetPaymentRequiredResponse(res) {
     logger.error(msg);
     throw new Error(msg);
 }
+function relaxedRequirementsToV2(req) {
+    const result = {};
+    if (req.scheme !== undefined)
+        result.scheme = req.scheme;
+    if (req.network !== undefined)
+        result.network = req.network;
+    if (req.maxAmountRequired !== undefined)
+        result.amount = req.maxAmountRequired;
+    if (req.asset !== undefined)
+        result.asset = req.asset;
+    if (req.payTo !== undefined)
+        result.payTo = req.payTo;
+    if (req.maxTimeoutSeconds !== undefined)
+        result.maxTimeoutSeconds = req.maxTimeoutSeconds;
+    if (req.extra !== undefined)
+        result.extra = req.extra;
+    return result;
+}
+/**
+ * Parse a payment header from either v1 (X-PAYMENT) or v2 (PAYMENT-SIGNATURE).
+ * Returns the parsed payload with version discriminant, or undefined if no valid header found.
+ */
+function parsePaymentHeader(getHeader) {
+    // Try v2 header first
+    const v2Header = getHeader(V2_PAYMENT_HEADER);
+    if (v2Header) {
+        const v2Payload = x402PaymentHeaderToPayload(v2Header);
+        if (!isValidationError(v2Payload)) {
+            return { version: 2, payload: v2Payload, rawHeader: v2Header };
+        }
+        logger.debug(`couldn't validate v2 client payload: ${v2Payload.summary}`);
+    }
+    const v1Header = getHeader(X_PAYMENT_HEADER);
+    if (v1Header) {
+        const v1Payload = x402PaymentHeaderToPayloadV1(v1Header);
+        if (!isValidationError(v1Payload)) {
+            return { version: 1, payload: v1Payload, rawHeader: v1Header };
+        }
+        logger.debug(`couldn't validate v1 client payload: ${v1Payload.summary}`);
+    }
+    return undefined;
+}
+/**
+ * Fetches v1 payment requirements from the facilitator's /accepts endpoint.
+ *
+ * @param args - Arguments including facilitator URL and accepted payment types
+ * @returns The validated payment required response from the facilitator
+ */
 export async function getPaymentRequiredResponse(args) {
+    const fetchFn = args.fetch ?? fetch;
     const accepts = args.accepts.map((x) => ({
         ...x,
         resource: x.resource ?? args.resource,
     }));
-    const t = await fetch(`${args.facilitatorURL}/accepts`, {
+    const t = await fetchFn(`${args.facilitatorURL}/accepts`, {
         method: "POST",
         headers: {
             Accept: "application/json",
@@ -43,45 +135,243 @@ export async function getPaymentRequiredResponse(args) {
         body: JSON.stringify({
             x402Version: 1,
             accepts,
+            error: "",
+        }),
+    });
+    gateGetPaymentRequiredResponse(t);
+    const rawResponse = x402PaymentRequiredResponseLenient(await t.json());
+    if (isValidationError(rawResponse)) {
+        throw new Error(`invalid payment requirements from facilitator: ${rawResponse.summary}`);
+    }
+    return normalizePaymentRequiredResponse(rawResponse);
+}
+/**
+ * Fetches v2 payment requirements from the facilitator's /accepts endpoint.
+ *
+ * @param args - Arguments including facilitator URL, resource info, and accepted payment types
+ * @returns The validated v2 payment required response from the facilitator
+ */
+export async function getPaymentRequiredResponseV2(args) {
+    const fetchFn = args.fetch ?? fetch;
+    const t = await fetchFn(`${args.facilitatorURL}/accepts`, {
+        method: "POST",
+        headers: {
+            Accept: "application/json",
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+            x402Version: 2,
+            resource: args.resource,
+            accepts: args.accepts,
         }),
     });
     gateGetPaymentRequiredResponse(t);
     const response = x402PaymentRequiredResponse(await t.json());
     if (isValidationError(response)) {
-        throw new Error(`invalid payment requirements from facilitator: ${response.summary}`);
+        throw new Error(`invalid v2 payment requirements from facilitator: ${response.summary}`);
     }
     return response;
 }
+/**
+ * Resolve and validate supported versions config.
+ * Returns resolved config with defaults applied.
+ * Throws if configuration is invalid.
+ */
+export function resolveSupportedVersions(config) {
+    const resolved = {
+        x402v1: config?.x402v1 ?? true,
+        x402v2: config?.x402v2 ?? false,
+    };
+    if (!resolved.x402v1 && !resolved.x402v2) {
+        throw new Error("Invalid supportedVersions configuration: at least one protocol version must be enabled");
+    }
+    return resolved;
+}
+/**
+ * Core middleware request handler that processes x402 payment flows.
+ *
+ * This function handles both v1 and v2 protocol versions, validates payment
+ * headers, communicates with the facilitator, and delegates to the body
+ * handler when payment is valid.
+ *
+ * @param args - Handler arguments including framework-specific adapters
+ * @returns The middleware response, or undefined if the body handler should continue
+ */
 export async function handleMiddlewareRequest(args) {
     const accepts = args.accepts.flat();
-    const paymentRequiredResponse = await args.getPaymentRequiredResponse({
-        accepts,
-        facilitatorURL: args.facilitatorURL,
-        resource: args.resource,
-    });
-    const sendPaymentRequired = () => args.sendJSONResponse(402, paymentRequiredResponse);
-    const paymentHeader = args.getHeader("X-PAYMENT");
-    if (!paymentHeader) {
-        return sendPaymentRequired();
+    const fetchFn = args.fetch ?? fetch;
+    const { supportedVersions } = args;
+    // Fetch requirements in the highest supported version, adapt downward as needed.
+    let v1Response;
+    let v2Response;
+    if (supportedVersions.x402v2 && args.getPaymentRequiredResponseV2) {
+        const firstAccept = accepts.find((a) => a.resource !== undefined);
+        const resourceInfo = {
+            url: firstAccept?.resource ?? args.resource,
+        };
+        if (firstAccept?.description) {
+            resourceInfo.description = firstAccept.description;
+        }
+        if (firstAccept?.mimeType) {
+            resourceInfo.mimeType = firstAccept.mimeType;
+        }
+        v2Response = await args.getPaymentRequiredResponseV2({
+            accepts: accepts.map(relaxedRequirementsToV2),
+            facilitatorURL: args.facilitatorURL,
+            resource: resourceInfo,
+            fetch: fetchFn,
+        });
+        if (supportedVersions.x402v1) {
+            v1Response = adaptPaymentRequiredResponseV2ToV1(v2Response);
+        }
     }
-    const paymentPayload = x402PaymentHeaderToPayload(paymentHeader);
-    if (isValidationError(paymentPayload)) {
-        logger.debug(`couldn't validate client payload: ${paymentPayload.summary}`);
+    else {
+        v1Response = await args.getPaymentRequiredResponse({
+            accepts,
+            facilitatorURL: args.facilitatorURL,
+            resource: args.resource,
+            fetch: fetchFn,
+        });
+        if (supportedVersions.x402v2) {
+            v2Response = adaptPaymentRequiredResponseV1ToV2(v1Response, args.resource, normalizeNetworkId);
+        }
+    }
+    const parsedHeader = parsePaymentHeader(args.getHeader);
+    const sendPaymentRequired = () => {
+        if (supportedVersions.x402v2 && v2Response) {
+            const v2Headers = {
+                [V2_PAYMENT_REQUIRED_HEADER]: btoa(JSON.stringify(v2Response)),
+            };
+            if (supportedVersions.x402v1 && v1Response) {
+                return args.sendJSONResponse(402, v1Response, v2Headers);
+            }
+            return args.sendJSONResponse(402, v2Response.error ? { error: v2Response.error } : undefined, v2Headers);
+        }
+        if (v1Response) {
+            return args.sendJSONResponse(402, v1Response);
+        }
+        throw new Error("no payment required response available");
+    };
+    if (!parsedHeader) {
         return sendPaymentRequired();
     }
+    if (parsedHeader.version === 2 && !supportedVersions.x402v2) {
+        return args.sendJSONResponse(400, {
+            error: "This server does not support x402 protocol version 2",
+        });
+    }
+    if (parsedHeader.version === 1 && !supportedVersions.x402v1) {
+        return args.sendJSONResponse(400, {
+            error: "This server does not support x402 protocol version 1",
+        });
+    }
+    if (parsedHeader.version === 2) {
+        if (!v2Response) {
+            throw new Error("v2 response unavailable for v2 request");
+        }
+        return handleV2Request(args, parsedHeader.payload, v2Response, sendPaymentRequired, fetchFn);
+    }
+    if (!v1Response) {
+        throw new Error("v1 response unavailable for v1 request");
+    }
+    return handleV1Request(args, parsedHeader.payload, parsedHeader.rawHeader, v1Response, sendPaymentRequired, fetchFn);
+}
+/**
+ * Handle v1 protocol request.
+ */
+async function handleV1Request(args, paymentPayload, paymentHeader, paymentRequiredResponse, sendPaymentRequired, fetchFn) {
     const paymentRequirements = findMatchingPaymentRequirements(paymentRequiredResponse.accepts, paymentPayload);
     if (!paymentRequirements) {
-        logger.warning(`couldn't find matching payment requirements for payload`, paymentPayload);
+        logger.warning(`couldn't find matching payment requirements for v1 payload`, paymentPayload);
         return sendPaymentRequired();
     }
     const settle = async () => {
         const settleRequest = {
-            x402Version: 1,
             paymentHeader,
             paymentPayload,
             paymentRequirements,
         };
-        const t = await fetch(`${args.facilitatorURL}/settle`, {
+        const t = await fetchFn(`${args.facilitatorURL}/settle`, {
+            method: "POST",
+            headers: {
+                Accept: "application/json",
+                "Content-Type": "application/json",
+            },
+            // x402Version is not part of the v1 spec but older Faremeter
+            // facilitators require it, so include it for backwards compatibility.
+            body: JSON.stringify({ x402Version: 1, ...settleRequest }),
+        });
+        // Parse with lenient type to accept both legacy and spec-compliant field names
+        const rawSettlementResponse = x402SettleResponseLenient(await t.json());
+        if (isValidationError(rawSettlementResponse)) {
+            const msg = `error getting response from facilitator for settlement: ${rawSettlementResponse.summary}`;
+            logger.error(msg);
+            throw new Error(msg);
+        }
+        // Normalize to spec-compliant field names
+        const settlementResponse = normalizeSettleResponse(rawSettlementResponse);
+        // Set the X-PAYMENT-RESPONSE header for both success and failure
+        if (args.setResponseHeader) {
+            args.setResponseHeader(X_PAYMENT_RESPONSE_HEADER, buildPaymentResponseHeader(settlementResponse));
+        }
+        if (!settlementResponse.success) {
+            logger.warning("failed to settle payment: {errorReason}", settlementResponse);
+            return { success: false, errorResponse: sendPaymentRequired() };
+        }
+        return { success: true, facilitatorResponse: settlementResponse };
+    };
+    const verify = async () => {
+        const verifyRequest = {
+            paymentHeader,
+            paymentPayload,
+            paymentRequirements,
+        };
+        const t = await fetchFn(`${args.facilitatorURL}/verify`, {
+            method: "POST",
+            headers: {
+                Accept: "application/json",
+                "Content-Type": "application/json",
+            },
+            // x402Version is not part of the v1 spec but older Faremeter
+            // facilitators require it, so include it for backwards compatibility.
+            body: JSON.stringify({ x402Version: 1, ...verifyRequest }),
+        });
+        const rawVerifyResponse = x402VerifyResponseLenient(await t.json());
+        if (isValidationError(rawVerifyResponse)) {
+            const msg = `error getting response from facilitator for verification: ${rawVerifyResponse.summary}`;
+            logger.error(msg);
+            throw new Error(msg);
+        }
+        const verifyResponse = normalizeVerifyResponse(rawVerifyResponse);
+        if (!verifyResponse.isValid) {
+            logger.warning("failed to verify payment: {invalidReason}", verifyResponse);
+            return { success: false, errorResponse: sendPaymentRequired() };
+        }
+        return { success: true, facilitatorResponse: verifyResponse };
+    };
+    return await args.body({
+        protocolVersion: 1,
+        paymentRequirements,
+        paymentPayload,
+        settle,
+        verify,
+    });
+}
+/**
+ * Handle v2 protocol request.
+ */
+async function handleV2Request(args, paymentPayload, paymentRequiredResponse, sendPaymentRequired, fetchFn) {
+    const paymentRequirements = findMatchingPaymentRequirementsV2(paymentRequiredResponse.accepts, paymentPayload);
+    if (!paymentRequirements) {
+        logger.warning(`couldn't find matching payment requirements for v2 payload`, paymentPayload);
+        return sendPaymentRequired();
+    }
+    const settle = async () => {
+        const settleRequest = {
+            paymentPayload,
+            paymentRequirements,
+        };
+        const t = await fetchFn(`${args.facilitatorURL}/settle`, {
             method: "POST",
             headers: {
                 Accept: "application/json",
@@ -91,23 +381,25 @@ export async function handleMiddlewareRequest(args) {
         });
         const settlementResponse = x402SettleResponse(await t.json());
         if (isValidationError(settlementResponse)) {
-            const msg = `error getting response from facilitator for settlement: ${settlementResponse.summary}`;
+            const msg = `error getting response from facilitator for v2 settlement: ${settlementResponse.summary}`;
             logger.error(msg);
             throw new Error(msg);
         }
+        if (args.setResponseHeader) {
+            args.setResponseHeader(V2_PAYMENT_RESPONSE_HEADER, btoa(JSON.stringify(settlementResponse)));
+        }
         if (!settlementResponse.success) {
-            logger.warning("failed to settle payment: {error}", settlementResponse);
-            return sendPaymentRequired();
+            logger.warning("failed to settle v2 payment: {errorReason}", settlementResponse);
+            return { success: false, errorResponse: sendPaymentRequired() };
         }
+        return { success: true, facilitatorResponse: settlementResponse };
     };
     const verify = async () => {
         const verifyRequest = {
-            x402Version: 1,
-            paymentHeader,
             paymentPayload,
             paymentRequirements,
         };
-        const t = await fetch(`${args.facilitatorURL}/verify`, {
+        const t = await fetchFn(`${args.facilitatorURL}/verify`, {
             method: "POST",
             headers: {
                 Accept: "application/json",
@@ -117,36 +409,57 @@ export async function handleMiddlewareRequest(args) {
         });
         const verifyResponse = x402VerifyResponse(await t.json());
         if (isValidationError(verifyResponse)) {
-            const msg = `error getting response from facilitator for verification: ${verifyResponse.summary}`;
+            const msg = `error getting response from facilitator for v2 verification: ${verifyResponse.summary}`;
             logger.error(msg);
             throw new Error(msg);
         }
         if (!verifyResponse.isValid) {
-            logger.warning("failed to settle payment: {invalidReason}", verifyResponse);
-            return sendPaymentRequired();
+            logger.warning("failed to verify v2 payment: {invalidReason}", verifyResponse);
+            return { success: false, errorResponse: sendPaymentRequired() };
         }
+        return { success: true, facilitatorResponse: verifyResponse };
     };
     return await args.body({
+        protocolVersion: 2,
         paymentRequirements,
         paymentPayload,
         settle,
         verify,
     });
 }
+/**
+ * Creates a cached wrapper around payment requirements fetching functions.
+ *
+ * The cache reduces load on the facilitator by reusing recent responses
+ * for identical requirements.
+ *
+ * @param opts - Cache configuration options
+ * @returns Object containing cached getPaymentRequiredResponse functions
+ */
 export function createPaymentRequiredResponseCache(opts = {}) {
     if (opts.disable) {
         logger.warning("payment required response cache disabled");
         return {
             getPaymentRequiredResponse,
+            getPaymentRequiredResponseV2,
         };
     }
-    const cache = new AgedLRUCache(opts);
+    const v1Cache = new AgedLRUCache(opts);
+    const v2Cache = new AgedLRUCache(opts);
     return {
         getPaymentRequiredResponse: async (args) => {
-            let response = cache.get(args.accepts);
+            let response = v1Cache.get(args.accepts);
             if (response === undefined) {
                 response = await getPaymentRequiredResponse(args);
-                cache.put(args.accepts, response);
+                v1Cache.put(args.accepts, response);
+            }
+            return response;
+        },
+        getPaymentRequiredResponseV2: async (args) => {
+            let response = v2Cache.get(args.accepts);
+            if (response === undefined) {
+                response = await getPaymentRequiredResponseV2(args);
+                v2Cache.put(args.accepts, response);
             }
             return response;
         },

package/dist/src/common.test.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env pnpm tsx
+export {};
+//# sourceMappingURL=common.test.d.ts.map

package/dist/src/common.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.test.d.ts","sourceRoot":"","sources":["../../src/common.test.ts"],"names":[],"mappings":""}

package/dist/src/common.test.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env pnpm tsx
+import t from "tap";
+import { getPaymentRequiredResponse } from "./common.js";
+const validAccepts = [
+    {
+        scheme: "exact",
+        network: "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
+        maxAmountRequired: "1000",
+        resource: "https://example.com/resource",
+        description: "Test resource",
+        payTo: "test-receiver",
+        maxTimeoutSeconds: 60,
+        asset: "test-token",
+    },
+];
+await t.test("getPaymentRequiredResponse accepts response without error field", async (t) => {
+    const mockFetch = async () => new Response(JSON.stringify({
+        x402Version: 1,
+        accepts: validAccepts,
+    }), { status: 200, headers: { "Content-Type": "application/json" } });
+    const response = await getPaymentRequiredResponse({
+        facilitatorURL: "https://facilitator.example.com",
+        accepts: [
+            { scheme: "exact", network: "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1" },
+        ],
+        resource: "https://example.com/resource",
+        fetch: mockFetch,
+    });
+    t.equal(response.x402Version, 1);
+    t.equal(response.accepts.length, 1);
+    t.equal(response.error, "");
+    t.end();
+});
+await t.test("getPaymentRequiredResponse preserves error field when present", async (t) => {
+    const mockFetch = async () => new Response(JSON.stringify({
+        x402Version: 1,
+        accepts: validAccepts,
+        error: "some error",
+    }), { status: 200, headers: { "Content-Type": "application/json" } });
+    const response = await getPaymentRequiredResponse({
+        facilitatorURL: "https://facilitator.example.com",
+        accepts: [
+            { scheme: "exact", network: "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1" },
+        ],
+        resource: "https://example.com/resource",
+        fetch: mockFetch,
+    });
+    t.equal(response.error, "some error");
+    t.end();
+});

package/dist/src/express.d.ts

@@ -1,6 +1,16 @@
 import { type CommonMiddlewareArgs } from "./common.js";
 import type { NextFunction, Request, Response } from "express";
 type createMiddlewareArgs = CommonMiddlewareArgs;
+/**
+ * Creates Express middleware that gates routes behind x402 payment.
+ *
+ * The middleware intercepts requests, checks for payment headers, communicates
+ * with the facilitator to validate and settle payments, and only allows the
+ * request to proceed if payment is successful.
+ *
+ * @param args - Configuration including facilitator URL and accepted payment types
+ * @returns An Express middleware function
+ */
 export declare function createMiddleware(args: createMiddlewareArgs): Promise<(req: Request, res: Response, next: NextFunction) => Promise<Response<any, Record<string, any>> | undefined>>;
 export {};
 //# sourceMappingURL=express.d.ts.map

package/dist/src/express.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"express.d.ts","sourceRoot":"","sources":["../../src/express.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,oBAAoB,EAE1B,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAE/D,KAAK,oBAAoB,GAAG,oBAAoB,CAAC;AAEjD,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,oBAAoB,iBAK5C,OAAO,OAAO,QAAQ,QAAQ,YAAY,8DAiB9D"}
+{"version":3,"file":"express.d.ts","sourceRoot":"","sources":["../../src/express.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,oBAAoB,EAG1B,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAE/D,KAAK,oBAAoB,GAAG,oBAAoB,CAAC;AAEjD;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,oBAAoB,iBAO5C,OAAO,OAAO,QAAQ,QAAQ,YAAY,8DA+B9D"}

package/dist/src/express.js

@@ -1,17 +1,43 @@
-import { handleMiddlewareRequest, createPaymentRequiredResponseCache, } from "./common.js";
+import { handleMiddlewareRequest, createPaymentRequiredResponseCache, resolveSupportedVersions, } from "./common.js";
+/**
+ * Creates Express middleware that gates routes behind x402 payment.
+ *
+ * The middleware intercepts requests, checks for payment headers, communicates
+ * with the facilitator to validate and settle payments, and only allows the
+ * request to proceed if payment is successful.
+ *
+ * @param args - Configuration including facilitator URL and accepted payment types
+ * @returns An Express middleware function
+ */
 export async function createMiddleware(args) {
-    const { getPaymentRequiredResponse } = createPaymentRequiredResponseCache(args.cacheConfig);
+    // Validate configuration at creation time
+    const supportedVersions = resolveSupportedVersions(args.supportedVersions);
+    const { getPaymentRequiredResponse, getPaymentRequiredResponseV2 } = createPaymentRequiredResponseCache(args.cacheConfig);
     return async (req, res, next) => {
         return await handleMiddlewareRequest({
             ...args,
+            supportedVersions,
             resource: `${req.protocol}://${req.headers.host}${req.path}`,
             getPaymentRequiredResponse,
+            getPaymentRequiredResponseV2,
             getHeader: (key) => req.header(key),
-            sendJSONResponse: (status, body) => res.status(status).json(body),
+            setResponseHeader: (key, value) => res.setHeader(key, value),
+            sendJSONResponse: (status, body, headers) => {
+                res.status(status);
+                if (headers) {
+                    for (const [key, value] of Object.entries(headers)) {
+                        res.setHeader(key, value);
+                    }
+                }
+                if (body) {
+                    return res.json(body);
+                }
+                return res.end();
+            },
             body: async ({ settle }) => {
-                const response = await settle();
-                if (response !== undefined) {
-                    return response;
+                const settleResult = await settle();
+                if (!settleResult.success) {
+                    return settleResult.errorResponse;
                 }
                 next();
             },

package/dist/src/hono.d.ts

@@ -1,8 +1,22 @@
 import { type CommonMiddlewareArgs } from "./common.js";
 import type { MiddlewareHandler } from "hono";
+/**
+ * Configuration arguments for creating Hono x402 middleware.
+ */
 type CreateMiddlewareArgs = {
+    /** If true, verifies payment before running the handler, then settles after. */
     verifyBeforeSettle?: boolean;
 } & CommonMiddlewareArgs;
+/**
+ * Creates Hono middleware that gates routes behind x402 payment.
+ *
+ * The middleware intercepts requests, checks for payment headers, communicates
+ * with the facilitator to validate and settle payments, and only allows the
+ * request to proceed if payment is successful.
+ *
+ * @param args - Configuration including facilitator URL and accepted payment types
+ * @returns A Hono middleware handler
+ */
 export declare function createMiddleware(args: CreateMiddlewareArgs): Promise<MiddlewareHandler>;
 export {};
 //# sourceMappingURL=hono.d.ts.map

package/dist/src/hono.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hono.d.ts","sourceRoot":"","sources":["../../src/hono.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,oBAAoB,EAE1B,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAE9C,KAAK,oBAAoB,GAAG;IAC1B,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B,GAAG,oBAAoB,CAAC;AAEzB,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,iBAAiB,CAAC,CAoD5B"}
+{"version":3,"file":"hono.d.ts","sourceRoot":"","sources":["../../src/hono.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,oBAAoB,EAG1B,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAE9C;;GAEG;AACH,KAAK,oBAAoB,GAAG;IAC1B,gFAAgF;IAChF,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B,GAAG,oBAAoB,CAAC;AAEzB;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,iBAAiB,CAAC,CAiE5B"}