@faremeter/test-harness 0.16.0 → 0.17.1

package/dist/src/interceptors/responses.d.ts

@@ -1,11 +1,83 @@
 import type { x402PaymentRequirements } from "@faremeter/types/x402";
+/**
+ * Creates a JSON Response with the given status and body.
+ *
+ * @param status - HTTP status code.
+ * @param body - Object to serialize as JSON.
+ * @returns A Response with JSON content type.
+ */
 export declare function jsonResponse(status: number, body: object): Response;
+/**
+ * Creates a failed verify response.
+ *
+ * @param reason - Reason for verification failure.
+ * @returns A 200 Response with isValid: false.
+ */
 export declare function verifyFailedResponse(reason: string): Response;
+/**
+ * Creates a successful verify response.
+ *
+ * @returns A 200 Response with isValid: true.
+ */
 export declare function verifySuccessResponse(): Response;
-export declare function settleFailedResponse(error: string): Response;
-export declare function settleSuccessResponse(txHash: string, networkId: string): Response;
-export declare function paymentRequiredResponse(accepts: x402PaymentRequirements[]): Response;
+/**
+ * Creates a failed settle response (v1 format).
+ *
+ * @param errorReason - Reason for settlement failure.
+ * @returns A 200 Response with success: false.
+ */
+export declare function settleFailedResponse(errorReason: string): Response;
+/**
+ * Creates a failed settle response (v2 format).
+ *
+ * @param errorReason - Reason for settlement failure.
+ * @param network - Network identifier for the response.
+ * @returns A 200 Response with success: false.
+ */
+export declare function settleFailedResponseV2(errorReason: string, network: string): Response;
+/**
+ * Creates a successful settle response (v1 format).
+ *
+ * @param transaction - Transaction identifier.
+ * @param network - Network identifier.
+ * @returns A 200 Response with success: true.
+ */
+export declare function settleSuccessResponse(transaction: string, network: string): Response;
+/**
+ * Creates a successful settle response (v2 format).
+ *
+ * @param transaction - Transaction identifier.
+ * @param network - Network identifier.
+ * @returns A 200 Response with success: true.
+ */
+export declare function settleSuccessResponseV2(transaction: string, network: string): Response;
+/**
+ * Creates a 402 Payment Required response.
+ *
+ * @param accepts - Payment requirements the server accepts.
+ * @param error - Optional error message.
+ * @returns A 402 Response with x402Version: 1.
+ */
+export declare function paymentRequiredResponse(accepts: x402PaymentRequirements[], error?: string): Response;
+/**
+ * Creates a network error for testing error handling.
+ *
+ * @param message - Error message.
+ * @returns An Error to be thrown by interceptors.
+ */
 export declare function networkError(message?: string): Error;
+/**
+ * Creates a timeout error for testing timeout handling.
+ *
+ * @returns An Error with "Request timed out" message.
+ */
 export declare function timeoutError(): Error;
+/**
+ * Creates an HTTP error response.
+ *
+ * @param status - HTTP status code.
+ * @param message - Error message.
+ * @returns A Response with the error JSON body.
+ */
 export declare function httpError(status: number, message: string): Response;
 //# sourceMappingURL=responses.d.ts.map

package/dist/src/interceptors/responses.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"responses.d.ts","sourceRoot":"","sources":["../../../src/interceptors/responses.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAErE,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,QAAQ,CAKnE;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAK7D;AAED,wBAAgB,qBAAqB,IAAI,QAAQ,CAIhD;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,CAO5D;AAED,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GAChB,QAAQ,CAMV;AAED,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,uBAAuB,EAAE,GACjC,QAAQ,CAKV;AAED,wBAAgB,YAAY,CAAC,OAAO,SAAkB,GAAG,KAAK,CAE7D;AAED,wBAAgB,YAAY,IAAI,KAAK,CAEpC;AAED,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,QAAQ,CAEnE"}
+{"version":3,"file":"responses.d.ts","sourceRoot":"","sources":["../../../src/interceptors/responses.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAErE;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,QAAQ,CAKnE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAM7D;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,QAAQ,CAKhD;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,QAAQ,CAQlE;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd,QAAQ,CAOV;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd,QAAQ,CAOV;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,GACd,QAAQ,CAMV;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,uBAAuB,EAAE,EAClC,KAAK,SAAK,GACT,QAAQ,CAMV;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,SAAkB,GAAG,KAAK,CAE7D;AAED;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,KAAK,CAEpC;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,QAAQ,CAEnE"}

package/dist/src/interceptors/responses.js

@@ -1,47 +1,137 @@
+/**
+ * Creates a JSON Response with the given status and body.
+ *
+ * @param status - HTTP status code.
+ * @param body - Object to serialize as JSON.
+ * @returns A Response with JSON content type.
+ */
 export function jsonResponse(status, body) {
     return new Response(JSON.stringify(body), {
         status,
         headers: { "Content-Type": "application/json" },
     });
 }
+/**
+ * Creates a failed verify response.
+ *
+ * @param reason - Reason for verification failure.
+ * @returns A 200 Response with isValid: false.
+ */
 export function verifyFailedResponse(reason) {
     return jsonResponse(200, {
         isValid: false,
         invalidReason: reason,
+        payer: "",
     });
 }
+/**
+ * Creates a successful verify response.
+ *
+ * @returns A 200 Response with isValid: true.
+ */
 export function verifySuccessResponse() {
     return jsonResponse(200, {
         isValid: true,
+        payer: "test-payer",
     });
 }
-export function settleFailedResponse(error) {
+/**
+ * Creates a failed settle response (v1 format).
+ *
+ * @param errorReason - Reason for settlement failure.
+ * @returns A 200 Response with success: false.
+ */
+export function settleFailedResponse(errorReason) {
     return jsonResponse(200, {
         success: false,
-        error,
-        txHash: null,
-        networkId: null,
+        errorReason,
+        transaction: "",
+        network: "",
+        payer: "",
+    });
+}
+/**
+ * Creates a failed settle response (v2 format).
+ *
+ * @param errorReason - Reason for settlement failure.
+ * @param network - Network identifier for the response.
+ * @returns A 200 Response with success: false.
+ */
+export function settleFailedResponseV2(errorReason, network) {
+    return jsonResponse(200, {
+        success: false,
+        errorReason,
+        transaction: "",
+        network,
     });
 }
-export function settleSuccessResponse(txHash, networkId) {
+/**
+ * Creates a successful settle response (v1 format).
+ *
+ * @param transaction - Transaction identifier.
+ * @param network - Network identifier.
+ * @returns A 200 Response with success: true.
+ */
+export function settleSuccessResponse(transaction, network) {
     return jsonResponse(200, {
         success: true,
-        txHash,
-        networkId,
+        transaction,
+        network,
+        payer: "test-payer",
     });
 }
-export function paymentRequiredResponse(accepts) {
+/**
+ * Creates a successful settle response (v2 format).
+ *
+ * @param transaction - Transaction identifier.
+ * @param network - Network identifier.
+ * @returns A 200 Response with success: true.
+ */
+export function settleSuccessResponseV2(transaction, network) {
+    return jsonResponse(200, {
+        success: true,
+        transaction,
+        network,
+    });
+}
+/**
+ * Creates a 402 Payment Required response.
+ *
+ * @param accepts - Payment requirements the server accepts.
+ * @param error - Optional error message.
+ * @returns A 402 Response with x402Version: 1.
+ */
+export function paymentRequiredResponse(accepts, error = "") {
     return jsonResponse(402, {
         x402Version: 1,
         accepts,
+        error,
     });
 }
+/**
+ * Creates a network error for testing error handling.
+ *
+ * @param message - Error message.
+ * @returns An Error to be thrown by interceptors.
+ */
 export function networkError(message = "Network error") {
     return new Error(message);
 }
+/**
+ * Creates a timeout error for testing timeout handling.
+ *
+ * @returns An Error with "Request timed out" message.
+ */
 export function timeoutError() {
     return new Error("Request timed out");
 }
+/**
+ * Creates an HTTP error response.
+ *
+ * @param status - HTTP status code.
+ * @param message - Error message.
+ * @returns A Response with the error JSON body.
+ */
 export function httpError(status, message) {
     return jsonResponse(status, { error: message });
 }

package/dist/src/interceptors/types.d.ts

@@ -1,3 +1,9 @@
+/**
+ * A function that wraps fetch to intercept requests and responses.
+ *
+ * Interceptors can modify requests before they're sent, inspect or modify
+ * responses, inject failures, add delays, or log activity.
+ */
 export type Interceptor = (fetch: typeof globalThis.fetch) => typeof globalThis.fetch;
 /**
  * Compose multiple interceptors into a single interceptor.
@@ -16,5 +22,10 @@ export type Interceptor = (fetch: typeof globalThis.fetch) => typeof globalThis.
  * ```
  */
 export declare function composeInterceptors(...interceptors: Interceptor[]): Interceptor;
+/**
+ * Predicate function that determines whether a request should be matched.
+ *
+ * Used by interceptors to selectively apply behavior to specific requests.
+ */
 export type RequestMatcher = (url: string, init?: RequestInit) => boolean;
 //# sourceMappingURL=types.d.ts.map

package/dist/src/interceptors/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/interceptors/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG,CACxB,KAAK,EAAE,OAAO,UAAU,CAAC,KAAK,KAC3B,OAAO,UAAU,CAAC,KAAK,CAAC;AAE7B;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,YAAY,EAAE,WAAW,EAAE,GAC7B,WAAW,CAMb;AAED,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/interceptors/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,CACxB,KAAK,EAAE,OAAO,UAAU,CAAC,KAAK,KAC3B,OAAO,UAAU,CAAC,KAAK,CAAC;AAE7B;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,YAAY,EAAE,WAAW,EAAE,GAC7B,WAAW,CAMb;AAED;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC"}

package/dist/src/interceptors/utils.d.ts

@@ -1,2 +1,8 @@
+/**
+ * Extracts the URL string from various request input types.
+ *
+ * @param input - A URL string, URL object, or Request object.
+ * @returns The URL as a string.
+ */
 export declare function getURLFromRequestInfo(input: RequestInfo | URL | string): string;
 //# sourceMappingURL=utils.d.ts.map

package/dist/src/interceptors/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/interceptors/utils.ts"],"names":[],"mappings":"AAAA,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,WAAW,GAAG,GAAG,GAAG,MAAM,GAChC,MAAM,CAUR"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/interceptors/utils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,WAAW,GAAG,GAAG,GAAG,MAAM,GAChC,MAAM,CAUR"}

package/dist/src/interceptors/utils.js

@@ -1,3 +1,9 @@
+/**
+ * Extracts the URL string from various request input types.
+ *
+ * @param input - A URL string, URL object, or Request object.
+ * @returns The URL as a string.
+ */
 export function getURLFromRequestInfo(input) {
     if (typeof input === "string") {
         return input;

package/dist/src/interceptors/v2.d.ts

@@ -0,0 +1,15 @@
+import type { Interceptor } from "./types.js";
+/**
+ * Creates an interceptor that transforms v1 402 responses to v2 format.
+ *
+ * This allows testing v2 client behavior by making the middleware appear
+ * to respond with v2 format even though it defaults to v1.
+ *
+ * The transformation:
+ * - Parses the JSON body as v1 PaymentRequiredResponse
+ * - Converts to v2 PaymentRequiredResponse format
+ * - Encodes as base64 in PAYMENT-REQUIRED header
+ * - Returns 402 with the new header
+ */
+export declare function createV2ResponseInterceptor(): Interceptor;
+//# sourceMappingURL=v2.d.ts.map

package/dist/src/interceptors/v2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v2.d.ts","sourceRoot":"","sources":["../../../src/interceptors/v2.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAO3C;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,IAAI,WAAW,CA8CzD"}

package/dist/src/interceptors/v2.js

@@ -0,0 +1,52 @@
+import { x402PaymentRequiredResponse } from "@faremeter/types/x402";
+import { isValidationError } from "@faremeter/types";
+import { adaptPaymentRequiredResponseV1ToV2 } from "@faremeter/types/x402-adapters";
+import { V2_PAYMENT_REQUIRED_HEADER } from "@faremeter/types/x402v2";
+import { normalizeNetworkId } from "@faremeter/info";
+/**
+ * Creates an interceptor that transforms v1 402 responses to v2 format.
+ *
+ * This allows testing v2 client behavior by making the middleware appear
+ * to respond with v2 format even though it defaults to v1.
+ *
+ * The transformation:
+ * - Parses the JSON body as v1 PaymentRequiredResponse
+ * - Converts to v2 PaymentRequiredResponse format
+ * - Encodes as base64 in PAYMENT-REQUIRED header
+ * - Returns 402 with the new header
+ */
+export function createV2ResponseInterceptor() {
+    return (baseFetch) => async (input, init) => {
+        const response = await baseFetch(input, init);
+        // Only transform 402 responses that don't already have v2 header
+        if (response.status !== 402 ||
+            response.headers.has(V2_PAYMENT_REQUIRED_HEADER)) {
+            return response;
+        }
+        const cloned = response.clone();
+        let body;
+        try {
+            body = await cloned.json();
+        }
+        catch {
+            return response;
+        }
+        const v1Response = x402PaymentRequiredResponse(body);
+        if (isValidationError(v1Response)) {
+            return response;
+        }
+        // Convert to v2 format using shared adapter
+        const resourceURL = v1Response.accepts[0]?.resource ?? "";
+        const v2Response = adaptPaymentRequiredResponseV1ToV2(v1Response, resourceURL, normalizeNetworkId);
+        // Encode as base64
+        const encoded = btoa(JSON.stringify(v2Response));
+        // Create new response with v2 header
+        const newHeaders = new Headers(response.headers);
+        newHeaders.set(V2_PAYMENT_REQUIRED_HEADER, encoded);
+        return new Response(null, {
+            status: 402,
+            statusText: "Payment Required",
+            headers: newHeaders,
+        });
+    };
+}

package/dist/src/scheme/client.d.ts

@@ -1,9 +1,15 @@
-import type { PaymentHandler } from "@faremeter/types/client";
+import type { PaymentHandlerV1 } from "@faremeter/types/client";
 import type { x402PaymentRequirements } from "@faremeter/types/x402";
 import { type TestPaymentPayload } from "./types.js";
+/**
+ * Options for creating a test payment handler.
+ */
 export type CreateTestPaymentHandlerOpts = {
+    /** Optional callback when requirements are matched. */
     onMatch?: (requirements: x402PaymentRequirements) => void;
+    /** Optional callback when payment is executed. */
     onExec?: (requirements: x402PaymentRequirements, payload: TestPaymentPayload) => void;
+    /** Custom metadata to include in test payloads. */
     metadata?: Record<string, unknown>;
 };
 /**
@@ -12,5 +18,5 @@ export type CreateTestPaymentHandlerOpts = {
  * This handler creates simple test payment payloads without any cryptographic
  * operations, making it suitable for testing the x402 protocol flow.
  */
-export declare function createTestPaymentHandler(opts?: CreateTestPaymentHandlerOpts): PaymentHandler;
+export declare function createTestPaymentHandler(opts?: CreateTestPaymentHandlerOpts): PaymentHandlerV1;
 //# sourceMappingURL=client.d.ts.map

package/dist/src/scheme/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/scheme/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EAGf,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAGrE,OAAO,EAAkB,KAAK,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAElE,MAAM,MAAM,4BAA4B,GAAG;IACzC,OAAO,CAAC,EAAE,CAAC,YAAY,EAAE,uBAAuB,KAAK,IAAI,CAAC;IAC1D,MAAM,CAAC,EAAE,CACP,YAAY,EAAE,uBAAuB,EACrC,OAAO,EAAE,kBAAkB,KACxB,IAAI,CAAC;IACV,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CAAC;AASF;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,GAAE,4BAAiC,GACtC,cAAc,CAiChB"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/scheme/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,gBAAgB,EAGjB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAGrE,OAAO,EAAkB,KAAK,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAElE;;GAEG;AACH,MAAM,MAAM,4BAA4B,GAAG;IACzC,uDAAuD;IACvD,OAAO,CAAC,EAAE,CAAC,YAAY,EAAE,uBAAuB,KAAK,IAAI,CAAC;IAC1D,kDAAkD;IAClD,MAAM,CAAC,EAAE,CACP,YAAY,EAAE,uBAAuB,EACrC,OAAO,EAAE,kBAAkB,KACxB,IAAI,CAAC;IACV,mDAAmD;IACnD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,GAAE,4BAAiC,GACtC,gBAAgB,CAiClB"}

package/dist/src/scheme/client.js

@@ -1,9 +1,5 @@
-import { TEST_SCHEME, TEST_NETWORK } from "./constants.js";
+import { isMatchingRequirement } from "./constants.js";
 import { generateTestId } from "./types.js";
-function isMatchingRequirement(req) {
-    return (req.scheme.toLowerCase() === TEST_SCHEME.toLowerCase() &&
-        req.network.toLowerCase() === TEST_NETWORK.toLowerCase());
-}
 /**
  * Create a test payment handler.
  *

package/dist/src/scheme/constants.d.ts

@@ -1,4 +1,11 @@
 export declare const TEST_SCHEME = "test";
 export declare const TEST_NETWORK = "test-local";
 export declare const TEST_ASSET = "TEST";
+/**
+ * Checks if a payment requirement matches the test scheme and network.
+ */
+export declare function isMatchingRequirement(req: {
+    scheme: string;
+    network: string;
+}): boolean;
 //# sourceMappingURL=constants.d.ts.map

package/dist/src/scheme/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/scheme/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,WAAW,SAAS,CAAC;AAElC,eAAO,MAAM,YAAY,eAAe,CAAC;AAEzC,eAAO,MAAM,UAAU,SAAS,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/scheme/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,WAAW,SAAS,CAAC;AAClC,eAAO,MAAM,YAAY,eAAe,CAAC;AACzC,eAAO,MAAM,UAAU,SAAS,CAAC;AAEjC;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAKV"}

package/dist/src/scheme/constants.js

@@ -1,3 +1,10 @@
 export const TEST_SCHEME = "test";
 export const TEST_NETWORK = "test-local";
 export const TEST_ASSET = "TEST";
+/**
+ * Checks if a payment requirement matches the test scheme and network.
+ */
+export function isMatchingRequirement(req) {
+    return (req.scheme.toLowerCase() === TEST_SCHEME.toLowerCase() &&
+        req.network.toLowerCase() === TEST_NETWORK.toLowerCase());
+}

package/dist/src/scheme/facilitator.d.ts

@@ -1,9 +1,15 @@
-import type { x402PaymentRequirements, x402PaymentPayload } from "@faremeter/types/x402";
+import type { x402PaymentRequirements, x402PaymentPayload } from "@faremeter/types/x402v2";
 import type { FacilitatorHandler } from "@faremeter/types/facilitator";
 import type { TestPaymentPayload } from "./types.js";
+/**
+ * Options for creating a test facilitator handler.
+ */
 export type CreateTestFacilitatorHandlerOpts = {
+    /** Address that should receive payments. */
     payTo: string;
+    /** Optional callback invoked during verify. */
     onVerify?: (requirements: x402PaymentRequirements, payload: x402PaymentPayload, testPayload: TestPaymentPayload) => void;
+    /** Optional callback invoked during settle. */
     onSettle?: (requirements: x402PaymentRequirements, payload: x402PaymentPayload, testPayload: TestPaymentPayload) => void;
 };
 /**

package/dist/src/scheme/facilitator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"facilitator.d.ts","sourceRoot":"","sources":["../../../src/scheme/facilitator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,uBAAuB,EACvB,kBAAkB,EAInB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAGvE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAElD,MAAM,MAAM,gCAAgC,GAAG;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,CACT,YAAY,EAAE,uBAAuB,EACrC,OAAO,EAAE,kBAAkB,EAC3B,WAAW,EAAE,kBAAkB,KAC5B,IAAI,CAAC;IACV,QAAQ,CAAC,EAAE,CACT,YAAY,EAAE,uBAAuB,EACrC,OAAO,EAAE,kBAAkB,EAC3B,WAAW,EAAE,kBAAkB,KAC5B,IAAI,CAAC;CACX,CAAC;AAuCF;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,gCAAgC,GACrC,kBAAkB,CAiHpB"}
+{"version":3,"file":"facilitator.d.ts","sourceRoot":"","sources":["../../../src/scheme/facilitator.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,uBAAuB,EACvB,kBAAkB,EAInB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAQvE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AASlD;;GAEG;AACH,MAAM,MAAM,gCAAgC,GAAG;IAC7C,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,CACT,YAAY,EAAE,uBAAuB,EACrC,OAAO,EAAE,kBAAkB,EAC3B,WAAW,EAAE,kBAAkB,KAC5B,IAAI,CAAC;IACV,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,CACT,YAAY,EAAE,uBAAuB,EACrC,OAAO,EAAE,kBAAkB,EAC3B,WAAW,EAAE,kBAAkB,KAC5B,IAAI,CAAC;CACX,CAAC;AAcF;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,gCAAgC,GACrC,kBAAkB,CAwHpB"}

package/dist/src/scheme/facilitator.js

@@ -1,28 +1,18 @@
-import { TEST_SCHEME, TEST_NETWORK, TEST_ASSET } from "./constants.js";
-function isMatchingRequirement(req) {
-    return (req.scheme.toLowerCase() === TEST_SCHEME.toLowerCase() &&
-        req.network.toLowerCase() === TEST_NETWORK.toLowerCase());
-}
+import { type } from "arktype";
+import { isValidationError } from "@faremeter/types";
+import { TEST_SCHEME, TEST_NETWORK, TEST_ASSET, isMatchingRequirement, } from "./constants.js";
+const testPaymentPayload = type({
+    testId: "string > 0",
+    amount: "string > 0",
+    timestamp: "number > 0",
+    "metadata?": "Record<string, unknown>",
+});
 function validateTestPayload(payload) {
-    const p = payload;
-    if (typeof p.testId !== "string" || p.testId.length === 0) {
-        return { valid: false, error: "Missing or invalid testId" };
-    }
-    if (typeof p.amount !== "string" || p.amount.length === 0) {
-        return { valid: false, error: "Missing or invalid amount" };
-    }
-    if (typeof p.timestamp !== "number" || p.timestamp <= 0) {
-        return { valid: false, error: "Missing or invalid timestamp" };
+    const result = testPaymentPayload(payload);
+    if (isValidationError(result)) {
+        return { valid: false, error: result.summary };
     }
-    return {
-        valid: true,
-        payload: {
-            testId: p.testId,
-            amount: p.amount,
-            timestamp: p.timestamp,
-            metadata: p.metadata,
-        },
-    };
+    return { valid: true, payload: result };
 }
 /**
  * Create a test facilitator handler.
@@ -35,18 +25,19 @@ export function createTestFacilitatorHandler(opts) {
     const getSupported = () => {
         return [
             Promise.resolve({
-                x402Version: 1,
+                x402Version: 2,
                 scheme: TEST_SCHEME,
                 network: TEST_NETWORK,
             }),
         ];
     };
-    const getRequirements = async (req) => {
+    const getRequirements = async ({ accepts: req, }) => {
+        // || is intentional: tests pass empty strings to signal "not provided".
         return req.filter(isMatchingRequirement).map((r) => ({
             ...r,
             asset: r.asset || TEST_ASSET,
             payTo: r.payTo || payTo,
-            maxTimeoutSeconds: r.maxTimeoutSeconds || 300,
+            maxTimeoutSeconds: r.maxTimeoutSeconds ?? 300,
         }));
     };
     const handleVerify = async (requirements, payment) => {
@@ -59,7 +50,7 @@ export function createTestFacilitatorHandler(opts) {
         }
         const testPayload = result.payload;
         // Verify amount matches
-        if (testPayload.amount !== requirements.maxAmountRequired) {
+        if (testPayload.amount !== requirements.amount) {
             return { isValid: false, invalidReason: "Amount mismatch" };
         }
         // Verify payment is to the correct address
@@ -69,7 +60,7 @@ export function createTestFacilitatorHandler(opts) {
         if (onVerify) {
             onVerify(requirements, payment, testPayload);
         }
-        return { isValid: true };
+        return { isValid: true, payer: "test-payer" };
     };
     const handleSettle = async (requirements, payment) => {
         if (!isMatchingRequirement(requirements)) {
@@ -79,28 +70,31 @@ export function createTestFacilitatorHandler(opts) {
         if (!result.valid) {
             return {
                 success: false,
-                error: result.error,
-                txHash: null,
-                networkId: null,
+                errorReason: result.error,
+                transaction: "",
+                network: requirements.network,
+                payer: "",
             };
         }
         const testPayload = result.payload;
         // Verify amount matches
-        if (testPayload.amount !== requirements.maxAmountRequired) {
+        if (testPayload.amount !== requirements.amount) {
             return {
                 success: false,
-                error: "Amount mismatch",
-                txHash: null,
-                networkId: null,
+                errorReason: "Amount mismatch",
+                transaction: "",
+                network: requirements.network,
+                payer: "",
             };
         }
         // Verify payment is to the correct address
         if (requirements.payTo.toLowerCase() !== payTo.toLowerCase()) {
             return {
                 success: false,
-                error: "Payment to wrong address",
-                txHash: null,
-                networkId: null,
+                errorReason: "Payment to wrong address",
+                transaction: "",
+                network: requirements.network,
+                payer: "",
             };
         }
         if (onSettle) {
@@ -108,8 +102,9 @@ export function createTestFacilitatorHandler(opts) {
         }
         return {
             success: true,
-            txHash: `test-tx-${testPayload.testId}`,
-            networkId: TEST_NETWORK,
+            transaction: `test-tx-${testPayload.testId}`,
+            network: TEST_NETWORK,
+            payer: "test-payer",
         };
     };
     return {

package/dist/src/scheme/types.d.ts

@@ -1,8 +1,16 @@
+/**
+ * Payload structure for test payment scheme transactions.
+ */
 export type TestPaymentPayload = {
     testId: string;
     amount: string;
     timestamp: number;
     metadata?: Record<string, unknown> | undefined;
 };
+/**
+ * Generates a unique test payment identifier.
+ *
+ * @returns A string like "test-1234567890-abc123".
+ */
 export declare function generateTestId(): string;
 //# sourceMappingURL=types.d.ts.map

package/dist/src/scheme/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/scheme/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;CAChD,CAAC;AAEF,wBAAgB,cAAc,IAAI,MAAM,CAEvC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/scheme/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;CAChD,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAEvC"}

package/dist/src/scheme/types.js

@@ -1,3 +1,8 @@
+/**
+ * Generates a unique test payment identifier.
+ *
+ * @returns A string like "test-1234567890-abc123".
+ */
 export function generateTestId() {
     return `test-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
 }