@openfacilitator/sdk 0.6.3 → 0.7.1

package/dist/index.d.mts

@@ -7,15 +7,14 @@ interface FacilitatorConfig {
     headers?: Record<string, string>;
 }
 /**
- * Payment payload for verification/settlement
- * Supports both x402 v1 and v2 formats
+ * Payment payload for x402 version 1. Uses flat structure with scheme/network at top level.
  */
-interface PaymentPayload {
-    /** x402 version (1 or 2) */
-    x402Version: 1 | 2;
+interface PaymentPayloadV1 {
+    /** x402 version 1 */
+    x402Version: 1;
     /** Payment scheme (e.g., "exact") */
     scheme: string;
-    /** Network identifier - v1: "base", v2: "eip155:8453" */
+    /** Network identifier - v1 format (e.g., "base", "solana") */
     network: string;
     /** Payment details */
     payload: {
@@ -25,6 +24,48 @@ interface PaymentPayload {
         authorization: PaymentAuthorization;
     };
 }
+/**
+ * Payment payload for x402 version 2. Uses nested `accepted` structure per @x402/core spec.
+ */
+interface PaymentPayloadV2 {
+    /** x402 version 2 */
+    x402Version: 2;
+    /** Optional resource being paid for */
+    resource?: {
+        /** Resource URL */
+        url: string;
+        /** Human-readable description */
+        description?: string;
+        /** MIME type of resource */
+        mimeType?: string;
+    };
+    /** Accepted payment requirements (contains scheme, network, amount, etc.) */
+    accepted: {
+        /** Payment scheme (e.g., "exact") */
+        scheme: string;
+        /** Network identifier - CAIP-2 format (e.g., "eip155:8453") */
+        network: string;
+        /** Token/asset address */
+        asset: string;
+        /** Amount in base units */
+        amount: string;
+        /** Recipient address */
+        payTo: string;
+        /** Maximum timeout in seconds */
+        maxTimeoutSeconds: number;
+        /** Extra data */
+        extra?: Record<string, unknown>;
+    };
+    /** Payment details (signature, authorization, etc.) */
+    payload: Record<string, unknown>;
+    /** Optional extensions */
+    extensions?: Record<string, unknown>;
+}
+/**
+ * Payment payload union - supports both x402 v1 and v2 formats.
+ * Use x402Version to discriminate between versions.
+ */
+type PaymentPayload = PaymentPayloadV1 | PaymentPayloadV2;
 interface PaymentAuthorization {
     /** Sender address */
     from: string;
@@ -44,10 +85,9 @@ interface PaymentAuthorization {
     [key: string]: unknown;
 }
 /**
- * Payment requirements from the server/resource
- * Used for validation during verify/settle
+ * Payment requirements for x402 version 1. Uses maxAmountRequired field.
  */
-interface PaymentRequirements {
+interface PaymentRequirementsV1 {
     /** Payment scheme (e.g., "exact") */
     scheme: string;
     /** Network identifier */
@@ -71,6 +111,31 @@ interface PaymentRequirements {
     /** Extra data */
     extra?: Record<string, unknown>;
 }
+/**
+ * Payment requirements for x402 version 2.
+ * Uses 'amount' instead of 'maxAmountRequired' and has stricter required fields.
+ */
+interface PaymentRequirementsV2 {
+    /** Payment scheme (e.g., "exact") */
+    scheme: string;
+    /** Network identifier - v2 CAIP-2 format */
+    network: string;
+    /** Amount required in base units */
+    amount: string;
+    /** Token/asset address */
+    asset: string;
+    /** Recipient address */
+    payTo: string;
+    /** Maximum timeout in seconds */
+    maxTimeoutSeconds: number;
+    /** Extra data */
+    extra: Record<string, unknown>;
+}
+/**
+ * Payment requirements union - supports both v1 and v2 formats.
+ * V1 uses maxAmountRequired, V2 uses amount.
+ */
+type PaymentRequirements = PaymentRequirementsV1 | PaymentRequirementsV2;
 interface VerifyResponse {
     /** Whether the payment is valid */
     isValid: boolean;
@@ -256,6 +321,65 @@ declare function getTestnets(): NetworkInfo[];
  * Type guard for checking if value is a valid payment payload
  */
 declare function isPaymentPayload(value: unknown): value is PaymentPayload;
+/**
+ * Type guard for PaymentPayloadV1 (x402 version 1).
+ * Narrows PaymentPayload to v1 format with flat structure.
+ */
+declare function isPaymentPayloadV1(value: unknown): value is PaymentPayloadV1;
+/**
+ * Type guard for PaymentPayloadV2 (x402 version 2).
+ * Narrows PaymentPayload to v2 format with nested `accepted` structure.
+ */
+declare function isPaymentPayloadV2(value: unknown): value is PaymentPayloadV2;
+/**
+ * Type guard for PaymentRequirementsV1.
+ * V1 requirements have maxAmountRequired field.
+ */
+declare function isPaymentRequirementsV1(value: unknown): value is PaymentRequirementsV1;
+/**
+ * Type guard for PaymentRequirementsV2.
+ * V2 requirements have amount but NOT maxAmountRequired.
+ */
+declare function isPaymentRequirementsV2(value: unknown): value is PaymentRequirementsV2;
+/**
+ * Extract scheme and network from PaymentPayload (version-agnostic).
+ * v1 has these at top level, v2 has them nested in `accepted`.
+ */
+declare function getSchemeNetwork(payload: PaymentPayload): {
+    scheme: string;
+    network: string;
+};
+/**
+ * Get x402 version from PaymentPayload.
+ * Returns literal type 1 | 2 for exhaustiveness checking in switch statements.
+ */
+declare function getVersion(payload: PaymentPayload): 1 | 2;
+/**
+ * Safely extract x402 version from an unknown payment object.
+ * Provides backward compatibility for pre-versioning payloads.
+ *
+ * - Returns 1 if x402Version is undefined/missing (backward compatibility)
+ * - Returns 1 or 2 for valid versions
+ * - Throws descriptive error for unsupported versions
+ *
+ * Use this at method entry points to validate version before processing.
+ * For type-safe access after validation, use getVersion() instead.
+ */
+declare function getVersionSafe(payment: unknown): 1 | 2;
+/**
+ * Exhaustiveness check for discriminated unions.
+ * TypeScript will error at compile time if not all union members are handled.
+ *
+ * @example
+ * function handlePayload(payload: PaymentPayload) {
+ *   switch (payload.x402Version) {
+ *     case 1: return handleV1(payload);
+ *     case 2: return handleV2(payload);
+ *     default: return assertNever(payload);
+ *   }
+ * }
+ */
+declare function assertNever(value: never, message?: string): never;
 
 /**
  * Claims module for reporting failures and managing refunds
@@ -380,7 +504,7 @@ declare function executeClaim(params: ExecuteClaimParams): Promise<ExecuteClaimR
 interface RefundProtectionConfig {
     /** The API key from server registration */
     apiKey: string;
-    /** The facilitator URL */
+    /** The facilitator URL (required for standalone usage) */
     facilitatorUrl: string;
     /** Optional: Custom error filter - return false to skip reporting */
     shouldReport?: (error: Error) => boolean;
@@ -389,6 +513,22 @@ interface RefundProtectionConfig {
     /** Optional: Called when reporting fails */
     onReportError?: (reportError: Error, originalError: Error) => void;
 }
+/**
+ * Refund protection config for use with payment middleware.
+ * The facilitatorUrl is optional and defaults to the middleware's facilitator URL.
+ */
+interface MiddlewareRefundConfig {
+    /** The API key from server registration */
+    apiKey: string;
+    /** The facilitator URL (optional - defaults to the middleware's facilitator URL) */
+    facilitatorUrl?: string;
+    /** Optional: Custom error filter - return false to skip reporting */
+    shouldReport?: (error: Error) => boolean;
+    /** Optional: Called when a failure is reported */
+    onReport?: (claimId: string | undefined, error: Error) => void;
+    /** Optional: Called when reporting fails */
+    onReportError?: (reportError: Error, originalError: Error) => void;
+}
 interface PaymentContext {
     /** Transaction hash from settlement */
     transactionHash: string;
@@ -518,6 +658,7 @@ declare function createPaymentContext(settleResponse: {
     network: string;
 }, paymentPayload: Record<string, unknown>, requirements?: {
     maxAmountRequired?: string;
+    amount?: string;
     asset?: string;
 }): PaymentContext;
 interface PaymentMiddlewareConfig {
@@ -526,7 +667,7 @@ interface PaymentMiddlewareConfig {
     /** Function to get payment requirements for the request (single or multiple for multi-network) */
     getRequirements: (req: unknown) => PaymentRequirements | PaymentRequirements[] | Promise<PaymentRequirements | PaymentRequirements[]>;
     /** Optional: Refund protection config (enables auto failure reporting) */
-    refundProtection?: RefundProtectionConfig;
+    refundProtection?: MiddlewareRefundConfig;
     /** Optional: Custom 402 response handler */
     on402?: (req: unknown, res: unknown, requirements: PaymentRequirements[]) => void | Promise<void>;
 }
@@ -579,7 +720,7 @@ interface HonoPaymentConfig {
     /** Function to get payment requirements for the request (single or multiple for multi-network) */
     getRequirements: (c: HonoContext) => PaymentRequirements | PaymentRequirements[] | Promise<PaymentRequirements | PaymentRequirements[]>;
     /** Optional: Refund protection config */
-    refundProtection?: RefundProtectionConfig;
+    refundProtection?: MiddlewareRefundConfig;
 }
 /**
  * Create Hono x402 payment middleware.
@@ -619,4 +760,4 @@ declare function honoPaymentMiddleware(config: HonoPaymentConfig): (c: HonoConte
     json: (body: unknown, status?: number) => Response;
 }, next: () => Promise<void>) => Promise<Response | undefined>;
 
-export { type ClaimHistoryItem, type ClaimableItem, ConfigurationError, type ExecuteClaimParams, type ExecuteClaimResponse, type FacilitatorConfig, FacilitatorError, type GetClaimHistoryResponse, type GetClaimableParams, type GetClaimableResponse, type HonoPaymentConfig, type HonoRefundConfig, NETWORKS, NetworkError, type NetworkInfo, type NetworkType, OpenFacilitator, type PaymentAuthorization, type PaymentContext, type PaymentKind, type PaymentMiddlewareConfig, type PaymentPayload, type PaymentRequest, type PaymentRequirements, type RefundProtectionConfig, type ReportFailureParams, type ReportFailureResponse, type SettleResponse, SettlementError, type SupportedResponse, VerificationError, type VerifyResponse, createDefaultFacilitator, createPaymentContext, createPaymentMiddleware, createRefundMiddleware, executeClaim, getClaimHistory, getClaimable, getMainnets, getNetwork, getNetworkType, getTestnets, honoPaymentMiddleware, honoRefundMiddleware, isPaymentPayload, isValidNetwork, reportFailure, toV1NetworkId, toV2NetworkId, withRefundProtection };
+export { type ClaimHistoryItem, type ClaimableItem, ConfigurationError, type ExecuteClaimParams, type ExecuteClaimResponse, type FacilitatorConfig, FacilitatorError, type GetClaimHistoryResponse, type GetClaimableParams, type GetClaimableResponse, type HonoPaymentConfig, type HonoRefundConfig, type MiddlewareRefundConfig, NETWORKS, NetworkError, type NetworkInfo, type NetworkType, OpenFacilitator, type PaymentAuthorization, type PaymentContext, type PaymentKind, type PaymentMiddlewareConfig, type PaymentPayload, type PaymentPayloadV1, type PaymentPayloadV2, type PaymentRequest, type PaymentRequirements, type PaymentRequirementsV1, type PaymentRequirementsV2, type RefundProtectionConfig, type ReportFailureParams, type ReportFailureResponse, type SettleResponse, SettlementError, type SupportedResponse, VerificationError, type VerifyResponse, assertNever, createDefaultFacilitator, createPaymentContext, createPaymentMiddleware, createRefundMiddleware, executeClaim, getClaimHistory, getClaimable, getMainnets, getNetwork, getNetworkType, getSchemeNetwork, getTestnets, getVersion, getVersionSafe, honoPaymentMiddleware, honoRefundMiddleware, isPaymentPayload, isPaymentPayloadV1, isPaymentPayloadV2, isPaymentRequirementsV1, isPaymentRequirementsV2, isValidNetwork, reportFailure, toV1NetworkId, toV2NetworkId, withRefundProtection };

package/dist/index.d.ts

@@ -7,15 +7,14 @@ interface FacilitatorConfig {
     headers?: Record<string, string>;
 }
 /**
- * Payment payload for verification/settlement
- * Supports both x402 v1 and v2 formats
+ * Payment payload for x402 version 1. Uses flat structure with scheme/network at top level.
  */
-interface PaymentPayload {
-    /** x402 version (1 or 2) */
-    x402Version: 1 | 2;
+interface PaymentPayloadV1 {
+    /** x402 version 1 */
+    x402Version: 1;
     /** Payment scheme (e.g., "exact") */
     scheme: string;
-    /** Network identifier - v1: "base", v2: "eip155:8453" */
+    /** Network identifier - v1 format (e.g., "base", "solana") */
     network: string;
     /** Payment details */
     payload: {
@@ -25,6 +24,48 @@ interface PaymentPayload {
         authorization: PaymentAuthorization;
     };
 }
+/**
+ * Payment payload for x402 version 2. Uses nested `accepted` structure per @x402/core spec.
+ */
+interface PaymentPayloadV2 {
+    /** x402 version 2 */
+    x402Version: 2;
+    /** Optional resource being paid for */
+    resource?: {
+        /** Resource URL */
+        url: string;
+        /** Human-readable description */
+        description?: string;
+        /** MIME type of resource */
+        mimeType?: string;
+    };
+    /** Accepted payment requirements (contains scheme, network, amount, etc.) */
+    accepted: {
+        /** Payment scheme (e.g., "exact") */
+        scheme: string;
+        /** Network identifier - CAIP-2 format (e.g., "eip155:8453") */
+        network: string;
+        /** Token/asset address */
+        asset: string;
+        /** Amount in base units */
+        amount: string;
+        /** Recipient address */
+        payTo: string;
+        /** Maximum timeout in seconds */
+        maxTimeoutSeconds: number;
+        /** Extra data */
+        extra?: Record<string, unknown>;
+    };
+    /** Payment details (signature, authorization, etc.) */
+    payload: Record<string, unknown>;
+    /** Optional extensions */
+    extensions?: Record<string, unknown>;
+}
+/**
+ * Payment payload union - supports both x402 v1 and v2 formats.
+ * Use x402Version to discriminate between versions.
+ */
+type PaymentPayload = PaymentPayloadV1 | PaymentPayloadV2;
 interface PaymentAuthorization {
     /** Sender address */
     from: string;
@@ -44,10 +85,9 @@ interface PaymentAuthorization {
     [key: string]: unknown;
 }
 /**
- * Payment requirements from the server/resource
- * Used for validation during verify/settle
+ * Payment requirements for x402 version 1. Uses maxAmountRequired field.
  */
-interface PaymentRequirements {
+interface PaymentRequirementsV1 {
     /** Payment scheme (e.g., "exact") */
     scheme: string;
     /** Network identifier */
@@ -71,6 +111,31 @@ interface PaymentRequirements {
     /** Extra data */
     extra?: Record<string, unknown>;
 }
+/**
+ * Payment requirements for x402 version 2.
+ * Uses 'amount' instead of 'maxAmountRequired' and has stricter required fields.
+ */
+interface PaymentRequirementsV2 {
+    /** Payment scheme (e.g., "exact") */
+    scheme: string;
+    /** Network identifier - v2 CAIP-2 format */
+    network: string;
+    /** Amount required in base units */
+    amount: string;
+    /** Token/asset address */
+    asset: string;
+    /** Recipient address */
+    payTo: string;
+    /** Maximum timeout in seconds */
+    maxTimeoutSeconds: number;
+    /** Extra data */
+    extra: Record<string, unknown>;
+}
+/**
+ * Payment requirements union - supports both v1 and v2 formats.
+ * V1 uses maxAmountRequired, V2 uses amount.
+ */
+type PaymentRequirements = PaymentRequirementsV1 | PaymentRequirementsV2;
 interface VerifyResponse {
     /** Whether the payment is valid */
     isValid: boolean;
@@ -256,6 +321,65 @@ declare function getTestnets(): NetworkInfo[];
  * Type guard for checking if value is a valid payment payload
  */
 declare function isPaymentPayload(value: unknown): value is PaymentPayload;
+/**
+ * Type guard for PaymentPayloadV1 (x402 version 1).
+ * Narrows PaymentPayload to v1 format with flat structure.
+ */
+declare function isPaymentPayloadV1(value: unknown): value is PaymentPayloadV1;
+/**
+ * Type guard for PaymentPayloadV2 (x402 version 2).
+ * Narrows PaymentPayload to v2 format with nested `accepted` structure.
+ */
+declare function isPaymentPayloadV2(value: unknown): value is PaymentPayloadV2;
+/**
+ * Type guard for PaymentRequirementsV1.
+ * V1 requirements have maxAmountRequired field.
+ */
+declare function isPaymentRequirementsV1(value: unknown): value is PaymentRequirementsV1;
+/**
+ * Type guard for PaymentRequirementsV2.
+ * V2 requirements have amount but NOT maxAmountRequired.
+ */
+declare function isPaymentRequirementsV2(value: unknown): value is PaymentRequirementsV2;
+/**
+ * Extract scheme and network from PaymentPayload (version-agnostic).
+ * v1 has these at top level, v2 has them nested in `accepted`.
+ */
+declare function getSchemeNetwork(payload: PaymentPayload): {
+    scheme: string;
+    network: string;
+};
+/**
+ * Get x402 version from PaymentPayload.
+ * Returns literal type 1 | 2 for exhaustiveness checking in switch statements.
+ */
+declare function getVersion(payload: PaymentPayload): 1 | 2;
+/**
+ * Safely extract x402 version from an unknown payment object.
+ * Provides backward compatibility for pre-versioning payloads.
+ *
+ * - Returns 1 if x402Version is undefined/missing (backward compatibility)
+ * - Returns 1 or 2 for valid versions
+ * - Throws descriptive error for unsupported versions
+ *
+ * Use this at method entry points to validate version before processing.
+ * For type-safe access after validation, use getVersion() instead.
+ */
+declare function getVersionSafe(payment: unknown): 1 | 2;
+/**
+ * Exhaustiveness check for discriminated unions.
+ * TypeScript will error at compile time if not all union members are handled.
+ *
+ * @example
+ * function handlePayload(payload: PaymentPayload) {
+ *   switch (payload.x402Version) {
+ *     case 1: return handleV1(payload);
+ *     case 2: return handleV2(payload);
+ *     default: return assertNever(payload);
+ *   }
+ * }
+ */
+declare function assertNever(value: never, message?: string): never;
 
 /**
  * Claims module for reporting failures and managing refunds
@@ -380,7 +504,7 @@ declare function executeClaim(params: ExecuteClaimParams): Promise<ExecuteClaimR
 interface RefundProtectionConfig {
     /** The API key from server registration */
     apiKey: string;
-    /** The facilitator URL */
+    /** The facilitator URL (required for standalone usage) */
     facilitatorUrl: string;
     /** Optional: Custom error filter - return false to skip reporting */
     shouldReport?: (error: Error) => boolean;
@@ -389,6 +513,22 @@ interface RefundProtectionConfig {
     /** Optional: Called when reporting fails */
     onReportError?: (reportError: Error, originalError: Error) => void;
 }
+/**
+ * Refund protection config for use with payment middleware.
+ * The facilitatorUrl is optional and defaults to the middleware's facilitator URL.
+ */
+interface MiddlewareRefundConfig {
+    /** The API key from server registration */
+    apiKey: string;
+    /** The facilitator URL (optional - defaults to the middleware's facilitator URL) */
+    facilitatorUrl?: string;
+    /** Optional: Custom error filter - return false to skip reporting */
+    shouldReport?: (error: Error) => boolean;
+    /** Optional: Called when a failure is reported */
+    onReport?: (claimId: string | undefined, error: Error) => void;
+    /** Optional: Called when reporting fails */
+    onReportError?: (reportError: Error, originalError: Error) => void;
+}
 interface PaymentContext {
     /** Transaction hash from settlement */
     transactionHash: string;
@@ -518,6 +658,7 @@ declare function createPaymentContext(settleResponse: {
     network: string;
 }, paymentPayload: Record<string, unknown>, requirements?: {
     maxAmountRequired?: string;
+    amount?: string;
     asset?: string;
 }): PaymentContext;
 interface PaymentMiddlewareConfig {
@@ -526,7 +667,7 @@ interface PaymentMiddlewareConfig {
     /** Function to get payment requirements for the request (single or multiple for multi-network) */
     getRequirements: (req: unknown) => PaymentRequirements | PaymentRequirements[] | Promise<PaymentRequirements | PaymentRequirements[]>;
     /** Optional: Refund protection config (enables auto failure reporting) */
-    refundProtection?: RefundProtectionConfig;
+    refundProtection?: MiddlewareRefundConfig;
     /** Optional: Custom 402 response handler */
     on402?: (req: unknown, res: unknown, requirements: PaymentRequirements[]) => void | Promise<void>;
 }
@@ -579,7 +720,7 @@ interface HonoPaymentConfig {
     /** Function to get payment requirements for the request (single or multiple for multi-network) */
     getRequirements: (c: HonoContext) => PaymentRequirements | PaymentRequirements[] | Promise<PaymentRequirements | PaymentRequirements[]>;
     /** Optional: Refund protection config */
-    refundProtection?: RefundProtectionConfig;
+    refundProtection?: MiddlewareRefundConfig;
 }
 /**
  * Create Hono x402 payment middleware.
@@ -619,4 +760,4 @@ declare function honoPaymentMiddleware(config: HonoPaymentConfig): (c: HonoConte
     json: (body: unknown, status?: number) => Response;
 }, next: () => Promise<void>) => Promise<Response | undefined>;
 
-export { type ClaimHistoryItem, type ClaimableItem, ConfigurationError, type ExecuteClaimParams, type ExecuteClaimResponse, type FacilitatorConfig, FacilitatorError, type GetClaimHistoryResponse, type GetClaimableParams, type GetClaimableResponse, type HonoPaymentConfig, type HonoRefundConfig, NETWORKS, NetworkError, type NetworkInfo, type NetworkType, OpenFacilitator, type PaymentAuthorization, type PaymentContext, type PaymentKind, type PaymentMiddlewareConfig, type PaymentPayload, type PaymentRequest, type PaymentRequirements, type RefundProtectionConfig, type ReportFailureParams, type ReportFailureResponse, type SettleResponse, SettlementError, type SupportedResponse, VerificationError, type VerifyResponse, createDefaultFacilitator, createPaymentContext, createPaymentMiddleware, createRefundMiddleware, executeClaim, getClaimHistory, getClaimable, getMainnets, getNetwork, getNetworkType, getTestnets, honoPaymentMiddleware, honoRefundMiddleware, isPaymentPayload, isValidNetwork, reportFailure, toV1NetworkId, toV2NetworkId, withRefundProtection };
+export { type ClaimHistoryItem, type ClaimableItem, ConfigurationError, type ExecuteClaimParams, type ExecuteClaimResponse, type FacilitatorConfig, FacilitatorError, type GetClaimHistoryResponse, type GetClaimableParams, type GetClaimableResponse, type HonoPaymentConfig, type HonoRefundConfig, type MiddlewareRefundConfig, NETWORKS, NetworkError, type NetworkInfo, type NetworkType, OpenFacilitator, type PaymentAuthorization, type PaymentContext, type PaymentKind, type PaymentMiddlewareConfig, type PaymentPayload, type PaymentPayloadV1, type PaymentPayloadV2, type PaymentRequest, type PaymentRequirements, type PaymentRequirementsV1, type PaymentRequirementsV2, type RefundProtectionConfig, type ReportFailureParams, type ReportFailureResponse, type SettleResponse, SettlementError, type SupportedResponse, VerificationError, type VerifyResponse, assertNever, createDefaultFacilitator, createPaymentContext, createPaymentMiddleware, createRefundMiddleware, executeClaim, getClaimHistory, getClaimable, getMainnets, getNetwork, getNetworkType, getSchemeNetwork, getTestnets, getVersion, getVersionSafe, honoPaymentMiddleware, honoRefundMiddleware, isPaymentPayload, isPaymentPayloadV1, isPaymentPayloadV2, isPaymentRequirementsV1, isPaymentRequirementsV2, isValidNetwork, reportFailure, toV1NetworkId, toV2NetworkId, withRefundProtection };

package/dist/index.js

@@ -27,6 +27,7 @@ __export(index_exports, {
   OpenFacilitator: () => OpenFacilitator,
   SettlementError: () => SettlementError,
   VerificationError: () => VerificationError,
+  assertNever: () => assertNever,
   createDefaultFacilitator: () => createDefaultFacilitator,
   createPaymentContext: () => createPaymentContext,
   createPaymentMiddleware: () => createPaymentMiddleware,
@@ -37,10 +38,17 @@ __export(index_exports, {
   getMainnets: () => getMainnets,
   getNetwork: () => getNetwork,
   getNetworkType: () => getNetworkType,
+  getSchemeNetwork: () => getSchemeNetwork,
   getTestnets: () => getTestnets,
+  getVersion: () => getVersion,
+  getVersionSafe: () => getVersionSafe,
   honoPaymentMiddleware: () => honoPaymentMiddleware,
   honoRefundMiddleware: () => honoRefundMiddleware,
   isPaymentPayload: () => isPaymentPayload,
+  isPaymentPayloadV1: () => isPaymentPayloadV1,
+  isPaymentPayloadV2: () => isPaymentPayloadV2,
+  isPaymentRequirementsV1: () => isPaymentRequirementsV1,
+  isPaymentRequirementsV2: () => isPaymentRequirementsV2,
   isValidNetwork: () => isValidNetwork,
   reportFailure: () => reportFailure,
   toV1NetworkId: () => toV1NetworkId,
@@ -94,7 +102,66 @@ function buildUrl(baseUrl, path) {
 function isPaymentPayload(value) {
   if (!value || typeof value !== "object") return false;
   const obj = value;
-  return (obj.x402Version === 1 || obj.x402Version === 2) && typeof obj.scheme === "string" && typeof obj.network === "string" && obj.payload !== void 0;
+  if (obj.x402Version === 1) {
+    return typeof obj.scheme === "string" && typeof obj.network === "string" && obj.payload !== void 0;
+  } else if (obj.x402Version === 2) {
+    const accepted = obj.accepted;
+    return accepted !== void 0 && typeof accepted === "object" && typeof accepted.scheme === "string" && typeof accepted.network === "string" && obj.payload !== void 0;
+  }
+  return false;
+}
+function isPaymentPayloadV1(value) {
+  if (!value || typeof value !== "object") return false;
+  const obj = value;
+  return obj.x402Version === 1 && typeof obj.scheme === "string" && typeof obj.network === "string" && obj.payload !== void 0 && typeof obj.payload === "object";
+}
+function isPaymentPayloadV2(value) {
+  if (!value || typeof value !== "object") return false;
+  const obj = value;
+  if (obj.x402Version !== 2) return false;
+  const accepted = obj.accepted;
+  return accepted !== void 0 && typeof accepted === "object" && typeof accepted.scheme === "string" && typeof accepted.network === "string" && typeof accepted.asset === "string" && typeof accepted.amount === "string" && typeof accepted.payTo === "string" && typeof accepted.maxTimeoutSeconds === "number" && obj.payload !== void 0;
+}
+function isPaymentRequirementsV1(value) {
+  if (!value || typeof value !== "object") return false;
+  return "maxAmountRequired" in value;
+}
+function isPaymentRequirementsV2(value) {
+  if (!value || typeof value !== "object") return false;
+  return "amount" in value && !("maxAmountRequired" in value);
+}
+function getSchemeNetwork(payload) {
+  if (payload.x402Version === 1) {
+    return {
+      scheme: payload.scheme,
+      network: payload.network
+    };
+  } else {
+    return {
+      scheme: payload.accepted.scheme,
+      network: payload.accepted.network
+    };
+  }
+}
+function getVersion(payload) {
+  return payload.x402Version;
+}
+function getVersionSafe(payment) {
+  if (!payment || typeof payment !== "object") {
+    return 1;
+  }
+  const obj = payment;
+  const version = obj.x402Version;
+  if (version === void 0) return 1;
+  if (version === 1 || version === 2) return version;
+  throw new Error(
+    `Unsupported x402 version: ${version}. SDK supports versions 1 and 2.`
+  );
+}
+function assertNever(value, message) {
+  throw new Error(
+    message ?? `Unhandled discriminated union member: ${JSON.stringify(value)}`
+  );
 }
 
 // src/client.ts
@@ -124,8 +191,9 @@ var OpenFacilitator = class {
    */
   async verify(payment, requirements) {
     try {
+      const version = getVersionSafe(payment);
       const body = {
-        x402Version: payment.x402Version,
+        x402Version: version,
         paymentPayload: payment,
         paymentRequirements: requirements
       };
@@ -149,8 +217,9 @@ var OpenFacilitator = class {
    */
   async settle(payment, requirements) {
     try {
+      const version = getVersionSafe(payment);
       const body = {
-        x402Version: payment.x402Version,
+        x402Version: version,
         paymentPayload: payment,
         paymentRequirements: requirements
       };
@@ -562,7 +631,7 @@ function honoRefundMiddleware(config) {
 function createPaymentContext(settleResponse, paymentPayload, requirements) {
   const payload = paymentPayload.payload;
   const authorization = payload?.authorization;
-  const amount = authorization?.amount || payload?.amount || requirements?.maxAmountRequired || "0";
+  const amount = authorization?.amount || payload?.amount || requirements?.amount || requirements?.maxAmountRequired || "0";
   const asset = authorization?.asset || payload?.asset || requirements?.asset || "";
   return {
     transactionHash: settleResponse.transaction,
@@ -591,16 +660,28 @@ function createPaymentMiddleware(config) {
             if (config.refundProtection) {
               extra.supportsRefunds = true;
             }
-            return {
-              scheme: requirements2.scheme,
-              network: requirements2.network,
-              maxAmountRequired: requirements2.maxAmountRequired,
-              asset: requirements2.asset,
-              payTo: requirements2.payTo,
-              resource: requirements2.resource || req.url,
-              description: requirements2.description,
-              ...Object.keys(extra).length > 0 ? { extra } : {}
-            };
+            if ("maxAmountRequired" in requirements2) {
+              return {
+                scheme: requirements2.scheme,
+                network: requirements2.network,
+                maxAmountRequired: requirements2.maxAmountRequired,
+                asset: requirements2.asset,
+                payTo: requirements2.payTo,
+                resource: requirements2.resource || req.url,
+                description: requirements2.description,
+                ...Object.keys(extra).length > 0 ? { extra } : {}
+              };
+            } else {
+              return {
+                scheme: requirements2.scheme,
+                network: requirements2.network,
+                amount: requirements2.amount,
+                asset: requirements2.asset,
+                payTo: requirements2.payTo,
+                maxTimeoutSeconds: requirements2.maxTimeoutSeconds,
+                extra: { ...extra, ...requirements2.extra }
+              };
+            }
           });
           res.status(402).json({
             x402Version: 2,
@@ -647,13 +728,14 @@ function createPaymentMiddleware(config) {
       if (config.refundProtection) {
         const originalNext = next;
         const refundConfig = config.refundProtection;
+        const refundFacilitatorUrl = refundConfig.facilitatorUrl || facilitator.url;
         next = async (error) => {
           if (error) {
             const err = error instanceof Error ? error : new Error(String(error));
             if (!refundConfig.shouldReport || refundConfig.shouldReport(err)) {
               try {
                 const result = await reportFailure({
-                  facilitatorUrl: refundConfig.facilitatorUrl,
+                  facilitatorUrl: refundFacilitatorUrl,
                   apiKey: refundConfig.apiKey,
                   originalTxHash: paymentContext.transactionHash,
                   userWallet: paymentContext.userWallet,
@@ -698,16 +780,28 @@ function honoPaymentMiddleware(config) {
         if (config.refundProtection) {
           extra.supportsRefunds = true;
         }
-        return {
-          scheme: requirements2.scheme,
-          network: requirements2.network,
-          maxAmountRequired: requirements2.maxAmountRequired,
-          asset: requirements2.asset,
-          payTo: requirements2.payTo,
-          resource: requirements2.resource || c.req.url,
-          description: requirements2.description,
-          ...Object.keys(extra).length > 0 ? { extra } : {}
-        };
+        if ("maxAmountRequired" in requirements2) {
+          return {
+            scheme: requirements2.scheme,
+            network: requirements2.network,
+            maxAmountRequired: requirements2.maxAmountRequired,
+            asset: requirements2.asset,
+            payTo: requirements2.payTo,
+            resource: requirements2.resource || c.req.url,
+            description: requirements2.description,
+            ...Object.keys(extra).length > 0 ? { extra } : {}
+          };
+        } else {
+          return {
+            scheme: requirements2.scheme,
+            network: requirements2.network,
+            amount: requirements2.amount,
+            asset: requirements2.asset,
+            payTo: requirements2.payTo,
+            maxTimeoutSeconds: requirements2.maxTimeoutSeconds,
+            extra: { ...extra, ...requirements2.extra }
+          };
+        }
       });
       return c.json({
         x402Version: 2,
@@ -745,6 +839,7 @@ function honoPaymentMiddleware(config) {
     c.set("paymentContext", paymentContext);
     if (config.refundProtection) {
       const refundConfig = config.refundProtection;
+      const refundFacilitatorUrl = refundConfig.facilitatorUrl || facilitator.url;
       try {
         await next();
       } catch (error) {
@@ -752,7 +847,7 @@ function honoPaymentMiddleware(config) {
         if (!refundConfig.shouldReport || refundConfig.shouldReport(err)) {
           try {
             const result = await reportFailure({
-              facilitatorUrl: refundConfig.facilitatorUrl,
+              facilitatorUrl: refundFacilitatorUrl,
               apiKey: refundConfig.apiKey,
               originalTxHash: paymentContext.transactionHash,
               userWallet: paymentContext.userWallet,
@@ -789,6 +884,7 @@ function honoPaymentMiddleware(config) {
   OpenFacilitator,
   SettlementError,
   VerificationError,
+  assertNever,
   createDefaultFacilitator,
   createPaymentContext,
   createPaymentMiddleware,
@@ -799,10 +895,17 @@ function honoPaymentMiddleware(config) {
   getMainnets,
   getNetwork,
   getNetworkType,
+  getSchemeNetwork,
   getTestnets,
+  getVersion,
+  getVersionSafe,
   honoPaymentMiddleware,
   honoRefundMiddleware,
   isPaymentPayload,
+  isPaymentPayloadV1,
+  isPaymentPayloadV2,
+  isPaymentRequirementsV1,
+  isPaymentRequirementsV2,
   isValidNetwork,
   reportFailure,
   toV1NetworkId,

package/dist/index.mjs

@@ -43,7 +43,66 @@ function buildUrl(baseUrl, path) {
 function isPaymentPayload(value) {
   if (!value || typeof value !== "object") return false;
   const obj = value;
-  return (obj.x402Version === 1 || obj.x402Version === 2) && typeof obj.scheme === "string" && typeof obj.network === "string" && obj.payload !== void 0;
+  if (obj.x402Version === 1) {
+    return typeof obj.scheme === "string" && typeof obj.network === "string" && obj.payload !== void 0;
+  } else if (obj.x402Version === 2) {
+    const accepted = obj.accepted;
+    return accepted !== void 0 && typeof accepted === "object" && typeof accepted.scheme === "string" && typeof accepted.network === "string" && obj.payload !== void 0;
+  }
+  return false;
+}
+function isPaymentPayloadV1(value) {
+  if (!value || typeof value !== "object") return false;
+  const obj = value;
+  return obj.x402Version === 1 && typeof obj.scheme === "string" && typeof obj.network === "string" && obj.payload !== void 0 && typeof obj.payload === "object";
+}
+function isPaymentPayloadV2(value) {
+  if (!value || typeof value !== "object") return false;
+  const obj = value;
+  if (obj.x402Version !== 2) return false;
+  const accepted = obj.accepted;
+  return accepted !== void 0 && typeof accepted === "object" && typeof accepted.scheme === "string" && typeof accepted.network === "string" && typeof accepted.asset === "string" && typeof accepted.amount === "string" && typeof accepted.payTo === "string" && typeof accepted.maxTimeoutSeconds === "number" && obj.payload !== void 0;
+}
+function isPaymentRequirementsV1(value) {
+  if (!value || typeof value !== "object") return false;
+  return "maxAmountRequired" in value;
+}
+function isPaymentRequirementsV2(value) {
+  if (!value || typeof value !== "object") return false;
+  return "amount" in value && !("maxAmountRequired" in value);
+}
+function getSchemeNetwork(payload) {
+  if (payload.x402Version === 1) {
+    return {
+      scheme: payload.scheme,
+      network: payload.network
+    };
+  } else {
+    return {
+      scheme: payload.accepted.scheme,
+      network: payload.accepted.network
+    };
+  }
+}
+function getVersion(payload) {
+  return payload.x402Version;
+}
+function getVersionSafe(payment) {
+  if (!payment || typeof payment !== "object") {
+    return 1;
+  }
+  const obj = payment;
+  const version = obj.x402Version;
+  if (version === void 0) return 1;
+  if (version === 1 || version === 2) return version;
+  throw new Error(
+    `Unsupported x402 version: ${version}. SDK supports versions 1 and 2.`
+  );
+}
+function assertNever(value, message) {
+  throw new Error(
+    message ?? `Unhandled discriminated union member: ${JSON.stringify(value)}`
+  );
 }
 
 // src/client.ts
@@ -73,8 +132,9 @@ var OpenFacilitator = class {
    */
   async verify(payment, requirements) {
     try {
+      const version = getVersionSafe(payment);
       const body = {
-        x402Version: payment.x402Version,
+        x402Version: version,
         paymentPayload: payment,
         paymentRequirements: requirements
       };
@@ -98,8 +158,9 @@ var OpenFacilitator = class {
    */
   async settle(payment, requirements) {
     try {
+      const version = getVersionSafe(payment);
       const body = {
-        x402Version: payment.x402Version,
+        x402Version: version,
         paymentPayload: payment,
         paymentRequirements: requirements
       };
@@ -511,7 +572,7 @@ function honoRefundMiddleware(config) {
 function createPaymentContext(settleResponse, paymentPayload, requirements) {
   const payload = paymentPayload.payload;
   const authorization = payload?.authorization;
-  const amount = authorization?.amount || payload?.amount || requirements?.maxAmountRequired || "0";
+  const amount = authorization?.amount || payload?.amount || requirements?.amount || requirements?.maxAmountRequired || "0";
   const asset = authorization?.asset || payload?.asset || requirements?.asset || "";
   return {
     transactionHash: settleResponse.transaction,
@@ -540,16 +601,28 @@ function createPaymentMiddleware(config) {
             if (config.refundProtection) {
               extra.supportsRefunds = true;
             }
-            return {
-              scheme: requirements2.scheme,
-              network: requirements2.network,
-              maxAmountRequired: requirements2.maxAmountRequired,
-              asset: requirements2.asset,
-              payTo: requirements2.payTo,
-              resource: requirements2.resource || req.url,
-              description: requirements2.description,
-              ...Object.keys(extra).length > 0 ? { extra } : {}
-            };
+            if ("maxAmountRequired" in requirements2) {
+              return {
+                scheme: requirements2.scheme,
+                network: requirements2.network,
+                maxAmountRequired: requirements2.maxAmountRequired,
+                asset: requirements2.asset,
+                payTo: requirements2.payTo,
+                resource: requirements2.resource || req.url,
+                description: requirements2.description,
+                ...Object.keys(extra).length > 0 ? { extra } : {}
+              };
+            } else {
+              return {
+                scheme: requirements2.scheme,
+                network: requirements2.network,
+                amount: requirements2.amount,
+                asset: requirements2.asset,
+                payTo: requirements2.payTo,
+                maxTimeoutSeconds: requirements2.maxTimeoutSeconds,
+                extra: { ...extra, ...requirements2.extra }
+              };
+            }
           });
           res.status(402).json({
             x402Version: 2,
@@ -596,13 +669,14 @@ function createPaymentMiddleware(config) {
       if (config.refundProtection) {
         const originalNext = next;
         const refundConfig = config.refundProtection;
+        const refundFacilitatorUrl = refundConfig.facilitatorUrl || facilitator.url;
         next = async (error) => {
           if (error) {
             const err = error instanceof Error ? error : new Error(String(error));
             if (!refundConfig.shouldReport || refundConfig.shouldReport(err)) {
               try {
                 const result = await reportFailure({
-                  facilitatorUrl: refundConfig.facilitatorUrl,
+                  facilitatorUrl: refundFacilitatorUrl,
                   apiKey: refundConfig.apiKey,
                   originalTxHash: paymentContext.transactionHash,
                   userWallet: paymentContext.userWallet,
@@ -647,16 +721,28 @@ function honoPaymentMiddleware(config) {
         if (config.refundProtection) {
           extra.supportsRefunds = true;
         }
-        return {
-          scheme: requirements2.scheme,
-          network: requirements2.network,
-          maxAmountRequired: requirements2.maxAmountRequired,
-          asset: requirements2.asset,
-          payTo: requirements2.payTo,
-          resource: requirements2.resource || c.req.url,
-          description: requirements2.description,
-          ...Object.keys(extra).length > 0 ? { extra } : {}
-        };
+        if ("maxAmountRequired" in requirements2) {
+          return {
+            scheme: requirements2.scheme,
+            network: requirements2.network,
+            maxAmountRequired: requirements2.maxAmountRequired,
+            asset: requirements2.asset,
+            payTo: requirements2.payTo,
+            resource: requirements2.resource || c.req.url,
+            description: requirements2.description,
+            ...Object.keys(extra).length > 0 ? { extra } : {}
+          };
+        } else {
+          return {
+            scheme: requirements2.scheme,
+            network: requirements2.network,
+            amount: requirements2.amount,
+            asset: requirements2.asset,
+            payTo: requirements2.payTo,
+            maxTimeoutSeconds: requirements2.maxTimeoutSeconds,
+            extra: { ...extra, ...requirements2.extra }
+          };
+        }
       });
       return c.json({
         x402Version: 2,
@@ -694,6 +780,7 @@ function honoPaymentMiddleware(config) {
     c.set("paymentContext", paymentContext);
     if (config.refundProtection) {
       const refundConfig = config.refundProtection;
+      const refundFacilitatorUrl = refundConfig.facilitatorUrl || facilitator.url;
       try {
         await next();
       } catch (error) {
@@ -701,7 +788,7 @@ function honoPaymentMiddleware(config) {
         if (!refundConfig.shouldReport || refundConfig.shouldReport(err)) {
           try {
             const result = await reportFailure({
-              facilitatorUrl: refundConfig.facilitatorUrl,
+              facilitatorUrl: refundFacilitatorUrl,
               apiKey: refundConfig.apiKey,
               originalTxHash: paymentContext.transactionHash,
               userWallet: paymentContext.userWallet,
@@ -737,6 +824,7 @@ export {
   OpenFacilitator,
   SettlementError,
   VerificationError,
+  assertNever,
   createDefaultFacilitator,
   createPaymentContext,
   createPaymentMiddleware,
@@ -747,10 +835,17 @@ export {
   getMainnets,
   getNetwork,
   getNetworkType,
+  getSchemeNetwork,
   getTestnets,
+  getVersion,
+  getVersionSafe,
   honoPaymentMiddleware,
   honoRefundMiddleware,
   isPaymentPayload,
+  isPaymentPayloadV1,
+  isPaymentPayloadV2,
+  isPaymentRequirementsV1,
+  isPaymentRequirementsV2,
   isValidNetwork,
   reportFailure,
   toV1NetworkId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfacilitator/sdk",
-  "version": "0.6.3",
+  "version": "0.7.1",
   "description": "TypeScript SDK for x402 payment facilitation",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -12,7 +12,7 @@
     "build": "tsup src/index.ts --format cjs,esm --dts",
     "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
     "test": "vitest",
-    "lint": "eslint src/",
+    "lint": "tsc --noEmit",
     "clean": "rm -rf dist"
   },
   "keywords": [