@faremeter/facilitator 0.16.0 → 0.17.0

package/dist/src/adapters.d.ts

@@ -0,0 +1,22 @@
+import { x402, facilitator } from "@faremeter/types";
+export { adaptRequirementsV1ToV2, adaptRequirementsV2ToV1, extractResourceInfoV1, adaptPayloadV1ToV2, adaptVerifyResponseV2ToV1, adaptSettleResponseV2ToV1, adaptSettleResponseV2ToV1Legacy, adaptSettleResponseLegacyToV2, adaptSettleResponseLenientToV2, adaptSupportedKindV2ToV1, adaptSupportedKindV1ToV2, adaptPaymentRequiredResponseV1ToV2, adaptPaymentRequiredResponseV2ToV1, adaptVerifyResponseV1ToV2, adaptSettleResponseV1ToV2, } from "@faremeter/types/x402-adapters";
+/** V1 payment requirements with mimeType guaranteed to be present */
+type x402PaymentRequirementsV1Strict = x402.x402PaymentRequirements & {
+    mimeType: string;
+};
+/**
+ * Legacy facilitator handler interface using pre-spec field names.
+ * Use this to wrap old handlers that return txHash/networkId/error.
+ */
+export type LegacyFacilitatorHandler = {
+    getSupported?: () => Promise<x402.x402SupportedKind>[];
+    getRequirements: (req: x402PaymentRequirementsV1Strict[]) => Promise<x402.x402PaymentRequirements[]>;
+    handleVerify?: (requirements: x402PaymentRequirementsV1Strict, payment: x402.x402PaymentPayload) => Promise<x402.x402VerifyResponse | null>;
+    handleSettle: (requirements: x402PaymentRequirementsV1Strict, payment: x402.x402PaymentPayload) => Promise<x402.x402SettleResponseLegacy | null>;
+};
+/**
+ * Adapts a v1 FacilitatorHandler to the v2 interface.
+ * Use this to wrap handlers from external packages that haven't been updated to v2 types.
+ */
+export declare function adaptHandlerV1ToV2(handler: LegacyFacilitatorHandler): facilitator.FacilitatorHandler;
+//# sourceMappingURL=adapters.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"adapters.d.ts","sourceRoot":"","sources":["../../src/adapters.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAU,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAU7D,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACvB,qBAAqB,EACrB,kBAAkB,EAClB,yBAAyB,EACzB,yBAAyB,EACzB,+BAA+B,EAC/B,6BAA6B,EAC7B,8BAA8B,EAC9B,wBAAwB,EACxB,wBAAwB,EACxB,kCAAkC,EAClC,kCAAkC,EAClC,yBAAyB,EACzB,yBAAyB,GAC1B,MAAM,gCAAgC,CAAC;AAExC,qEAAqE;AACrE,KAAK,+BAA+B,GAAG,IAAI,CAAC,uBAAuB,GAAG;IACpE,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,iBAAiB,CAAC,EAAE,CAAC;IACvD,eAAe,EAAE,CACf,GAAG,EAAE,+BAA+B,EAAE,KACnC,OAAO,CAAC,IAAI,CAAC,uBAAuB,EAAE,CAAC,CAAC;IAC7C,YAAY,CAAC,EAAE,CACb,YAAY,EAAE,+BAA+B,EAC7C,OAAO,EAAE,IAAI,CAAC,kBAAkB,KAC7B,OAAO,CAAC,IAAI,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAC;IAC7C,YAAY,EAAE,CACZ,YAAY,EAAE,+BAA+B,EAC7C,OAAO,EAAE,IAAI,CAAC,kBAAkB,KAC7B,OAAO,CAAC,IAAI,CAAC,wBAAwB,GAAG,IAAI,CAAC,CAAC;CACpD,CAAC;AAEF;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,wBAAwB,GAChC,WAAW,CAAC,kBAAkB,CA0EhC"}

package/dist/src/adapters.js

@@ -0,0 +1,68 @@
+import { x402, x402v2, facilitator } from "@faremeter/types";
+import { adaptRequirementsV1ToV2, adaptRequirementsV2ToV1, adaptSupportedKindV1ToV2, adaptVerifyResponseV1ToV2, adaptSettleResponseLegacyToV2, } from "@faremeter/types/x402-adapters";
+import { normalizeNetworkId } from "@faremeter/info";
+export { adaptRequirementsV1ToV2, adaptRequirementsV2ToV1, extractResourceInfoV1, adaptPayloadV1ToV2, adaptVerifyResponseV2ToV1, adaptSettleResponseV2ToV1, adaptSettleResponseV2ToV1Legacy, adaptSettleResponseLegacyToV2, adaptSettleResponseLenientToV2, adaptSupportedKindV2ToV1, adaptSupportedKindV1ToV2, adaptPaymentRequiredResponseV1ToV2, adaptPaymentRequiredResponseV2ToV1, adaptVerifyResponseV1ToV2, adaptSettleResponseV1ToV2, } from "@faremeter/types/x402-adapters";
+/**
+ * Adapts a v1 FacilitatorHandler to the v2 interface.
+ * Use this to wrap handlers from external packages that haven't been updated to v2 types.
+ */
+export function adaptHandlerV1ToV2(handler) {
+    const adapted = {
+        getRequirements: async ({ accepts, resource }) => {
+            // Convert v2 requirements to v1, call legacy handler, convert back to v2.
+            // Resource may be undefined when the caller has no resource context
+            // (e.g. during capability negotiation). Legacy handlers that inspect
+            // requirements.resource will see an empty string in that case.
+            const fallbackResource = resource ?? {
+                url: "",
+            };
+            const v1Reqs = accepts.map((r) => adaptRequirementsV2ToV1(r, fallbackResource));
+            const v1Results = await handler.getRequirements(v1Reqs);
+            return v1Results.map((req) => adaptRequirementsV1ToV2(req, normalizeNetworkId));
+        },
+        handleSettle: async (requirements, payment) => {
+            if (!payment.resource) {
+                throw new Error("v2 payment payload is missing resource context required for v1 adapter");
+            }
+            const v1Req = adaptRequirementsV2ToV1(requirements, payment.resource);
+            const v1Payload = {
+                x402Version: 1,
+                scheme: payment.accepted.scheme,
+                network: payment.accepted.network,
+                asset: payment.accepted.asset,
+                payload: payment.payload,
+            };
+            const v1Result = await handler.handleSettle(v1Req, v1Payload);
+            if (v1Result === null) {
+                return null;
+            }
+            return adaptSettleResponseLegacyToV2(v1Result);
+        },
+    };
+    if (handler.getSupported) {
+        const legacyGetSupported = handler.getSupported;
+        adapted.getSupported = () => legacyGetSupported().map((p) => p.then((kind) => adaptSupportedKindV1ToV2(kind, normalizeNetworkId)));
+    }
+    if (handler.handleVerify) {
+        const legacyHandleVerify = handler.handleVerify;
+        adapted.handleVerify = async (requirements, payment) => {
+            if (!payment.resource) {
+                throw new Error("v2 payment payload is missing resource context required for v1 adapter");
+            }
+            const v1Req = adaptRequirementsV2ToV1(requirements, payment.resource);
+            const v1Payload = {
+                x402Version: 1,
+                scheme: payment.accepted.scheme,
+                network: payment.accepted.network,
+                asset: payment.accepted.asset,
+                payload: payment.payload,
+            };
+            const v1Result = await legacyHandleVerify(v1Req, v1Payload);
+            if (v1Result === null) {
+                return null;
+            }
+            return adaptVerifyResponseV1ToV2(v1Result);
+        };
+    }
+    return adapted;
+}

package/dist/src/index.d.ts

@@ -1,2 +1,9 @@
+/**
+ * @title Facilitator Package
+ * @sidebarTitle Facilitator
+ * @description Server-side facilitator for verifying and settling x402 payments on-chain
+ * @packageDocumentation
+ */
 export * from "./routes.js";
+export * from "./adapters.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC"}

package/dist/src/index.js

@@ -1 +1,8 @@
+/**
+ * @title Facilitator Package
+ * @sidebarTitle Facilitator
+ * @description Server-side facilitator for verifying and settling x402 payments on-chain
+ * @packageDocumentation
+ */
 export * from "./routes.js";
+export * from "./adapters.js";

package/dist/src/routes.d.ts

@@ -1,12 +1,34 @@
-import { Hono } from "hono";
+import { Hono, type Context } from "hono";
 import type { FacilitatorHandler } from "@faremeter/types/facilitator";
+/**
+ * Configuration arguments for creating facilitator routes.
+ */
 type CreateFacilitatorRoutesArgs = {
+    /** Array of handlers that process payment operations. */
     handlers: FacilitatorHandler[];
+    /** Optional timeout settings in milliseconds for handler operations. */
     timeout?: {
+        /** Timeout for getRequirements calls. Defaults to 500ms. */
         getRequirements?: number;
+        /** Timeout for getSupported calls. Defaults to 500ms. */
         getSupported?: number;
     };
 };
+export declare function getClientIP(c: Context): string | undefined;
+/**
+ * Creates a Hono router with x402 facilitator endpoints.
+ *
+ * The router provides the following endpoints:
+ * - POST /verify - Verify a payment without settling
+ * - POST /settle - Verify and settle a payment
+ * - POST /accepts - Get payment requirements for a resource
+ * - GET /supported - List supported payment schemes and networks
+ *
+ * Both v1 and v2 protocol formats are supported on all endpoints.
+ *
+ * @param args - Configuration including payment handlers and timeouts
+ * @returns A Hono router instance with facilitator endpoints
+ */
 export declare function createFacilitatorRoutes(args: CreateFacilitatorRoutesArgs): Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
 export {};
 //# sourceMappingURL=routes.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/routes.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAgB,MAAM,MAAM,CAAC;AAI1C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAKvE,KAAK,2BAA2B,GAAG;IACjC,QAAQ,EAAE,kBAAkB,EAAE,CAAC;IAC/B,OAAO,CAAC,EAAE;QACR,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;CACH,CAAC;AAoCF,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,2BAA2B,8EAuQxE"}
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/routes.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,KAAK,OAAO,EAAE,MAAM,MAAM,CAAC;AAI1C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAiDvE;;GAEG;AACH,KAAK,2BAA2B,GAAG;IACjC,yDAAyD;IACzD,QAAQ,EAAE,kBAAkB,EAAE,CAAC;IAC/B,wEAAwE;IACxE,OAAO,CAAC,EAAE;QACR,4DAA4D;QAC5D,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,yDAAyD;QACzD,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;CACH,CAAC;AAkBF,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAO1D;AAcD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,2BAA2B,8EA0gBxE"}