@openfacilitator/sdk 0.2.0 → 0.5.0

package/dist/index.d.mts

@@ -73,9 +73,11 @@ interface PaymentRequirements {
 }
 interface VerifyResponse {
     /** Whether the payment is valid */
-    valid: boolean;
-    /** Error message if invalid */
-    error?: string;
+    isValid: boolean;
+    /** Reason if invalid (x402 standard) */
+    invalidReason?: string;
+    /** Payer address */
+    payer?: string;
     /** Additional verification details */
     details?: {
         /** Verified amount */
@@ -89,12 +91,14 @@ interface VerifyResponse {
 interface SettleResponse {
     /** Whether settlement was successful */
     success: boolean;
-    /** Transaction hash/signature */
-    transactionHash?: string;
+    /** Transaction hash/signature (empty string when failed, x402 standard) */
+    transaction: string;
+    /** Payer address (x402 standard) */
+    payer: string;
     /** Network the transaction was settled on */
-    network?: string;
-    /** Error message if failed */
-    error?: string;
+    network: string;
+    /** Error reason if failed (x402 standard) */
+    errorReason?: string;
 }
 interface SupportedResponse {
     /** Supported payment kinds */
@@ -253,4 +257,370 @@ declare function getTestnets(): NetworkInfo[];
  */
 declare function isPaymentPayload(value: unknown): value is PaymentPayload;
 
-export { ConfigurationError, type FacilitatorConfig, FacilitatorError, NETWORKS, NetworkError, type NetworkInfo, type NetworkType, OpenFacilitator, type PaymentAuthorization, type PaymentKind, type PaymentPayload, type PaymentRequirements, type SettleResponse, SettlementError, type SupportedResponse, VerificationError, type VerifyResponse, createDefaultFacilitator, getMainnets, getNetwork, getNetworkType, getTestnets, isPaymentPayload, isValidNetwork, toV1NetworkId, toV2NetworkId };
+/**
+ * Claims module for reporting failures and managing refunds
+ */
+interface ReportFailureParams {
+    /** The facilitator URL (e.g., https://api.openfacilitator.io) */
+    facilitatorUrl: string;
+    /** The API key from server registration */
+    apiKey: string;
+    /** The original transaction hash that failed */
+    originalTxHash: string;
+    /** The user's wallet address to receive the refund */
+    userWallet: string;
+    /** The amount to refund (in atomic units, e.g., "1000000" for $1 USDC) */
+    amount: string;
+    /** The asset address (token contract) */
+    asset: string;
+    /** The network (e.g., "base", "solana") */
+    network: string;
+    /** Optional reason for the failure */
+    reason?: string;
+}
+interface ReportFailureResponse {
+    success: boolean;
+    claimId?: string;
+    error?: string;
+}
+/**
+ * Report a failure to the facilitator to create a refund claim
+ *
+ * @example
+ * ```typescript
+ * import { reportFailure } from '@openfacilitator/sdk/claims';
+ *
+ * const result = await reportFailure({
+ *   facilitatorUrl: 'https://my-facilitator.openfacilitator.io',
+ *   apiKey: 'sk_...',
+ *   originalTxHash: '0x123...',
+ *   userWallet: '0xabc...',
+ *   amount: '1000000', // 1 USDC
+ *   asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+ *   network: 'base',
+ *   reason: 'Service unavailable',
+ * });
+ *
+ * if (result.success) {
+ *   console.log('Claim created:', result.claimId);
+ * } else {
+ *   console.error('Failed to create claim:', result.error);
+ * }
+ * ```
+ */
+declare function reportFailure(params: ReportFailureParams): Promise<ReportFailureResponse>;
+interface GetClaimableParams {
+    /** The facilitator URL */
+    facilitatorUrl: string;
+    /** The user's wallet address */
+    wallet: string;
+    /** Optional facilitator subdomain filter */
+    facilitator?: string;
+}
+interface ClaimableItem {
+    id: string;
+    originalTxHash: string;
+    amount: string;
+    asset: string;
+    network: string;
+    reason?: string;
+    status: 'pending' | 'approved';
+    reportedAt: string;
+    expiresAt?: string;
+}
+interface GetClaimableResponse {
+    claims: ClaimableItem[];
+}
+/**
+ * Get claimable refunds for a wallet
+ */
+declare function getClaimable(params: GetClaimableParams): Promise<GetClaimableResponse>;
+interface ClaimHistoryItem {
+    id: string;
+    originalTxHash: string;
+    amount: string;
+    asset: string;
+    network: string;
+    reason?: string;
+    status: 'pending' | 'approved' | 'paid' | 'rejected' | 'expired';
+    reportedAt: string;
+    expiresAt?: string;
+    payoutTxHash?: string;
+    paidAt?: string;
+}
+interface GetClaimHistoryResponse {
+    claims: ClaimHistoryItem[];
+}
+/**
+ * Get claim history for a wallet
+ */
+declare function getClaimHistory(params: GetClaimableParams): Promise<GetClaimHistoryResponse>;
+interface ExecuteClaimParams {
+    /** The facilitator URL */
+    facilitatorUrl: string;
+    /** The claim ID to execute */
+    claimId: string;
+    /** Optional signature for verification (recommended in production) */
+    signature?: string;
+}
+interface ExecuteClaimResponse {
+    success: boolean;
+    transactionHash?: string;
+    error?: string;
+}
+/**
+ * Execute a claim payout (claim must be approved)
+ */
+declare function executeClaim(params: ExecuteClaimParams): Promise<ExecuteClaimResponse>;
+
+/**
+ * Payment and refund protection middleware
+ */
+
+interface RefundProtectionConfig {
+    /** The API key from server registration */
+    apiKey: string;
+    /** The 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;
+    /** User's wallet address (payer) */
+    userWallet: string;
+    /** Payment amount in atomic units */
+    amount: string;
+    /** Asset/token address */
+    asset: string;
+    /** Network identifier (e.g., "base", "solana") */
+    network: string;
+}
+/**
+ * Wrap an async function with refund protection.
+ * If the function throws, a failure is automatically reported.
+ *
+ * @example
+ * ```typescript
+ * import { withRefundProtection } from '@openfacilitator/sdk';
+ *
+ * const protectedHandler = withRefundProtection(
+ *   {
+ *     apiKey: process.env.REFUND_API_KEY!,
+ *     facilitatorUrl: 'https://free.openfacilitator.xyz',
+ *   },
+ *   async (paymentContext) => {
+ *     // Your logic here - if this throws, failure is auto-reported
+ *     const result = await doExpensiveOperation();
+ *     return result;
+ *   }
+ * );
+ *
+ * // Call with payment context from settle response
+ * const result = await protectedHandler({
+ *   transactionHash: settleResponse.transaction,
+ *   userWallet: settleResponse.payer,
+ *   amount: paymentPayload.payload.authorization.amount,
+ *   asset: paymentPayload.payload.authorization.asset,
+ *   network: settleResponse.network,
+ * });
+ * ```
+ */
+declare function withRefundProtection<T>(config: RefundProtectionConfig, handler: (context: PaymentContext) => Promise<T>): (context: PaymentContext) => Promise<T>;
+/**
+ * Express request with payment context attached
+ */
+interface PaymentRequest {
+    paymentContext?: PaymentContext;
+}
+/**
+ * Create Express middleware that attaches payment context and reports failures.
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { createRefundMiddleware } from '@openfacilitator/sdk';
+ *
+ * const app = express();
+ *
+ * const refundMiddleware = createRefundMiddleware({
+ *   apiKey: process.env.REFUND_API_KEY!,
+ *   facilitatorUrl: 'https://free.openfacilitator.xyz',
+ * });
+ *
+ * // Apply after your x402 payment verification
+ * app.post('/api/resource', paymentMiddleware, refundMiddleware, async (req, res) => {
+ *   // If this throws, failure is auto-reported
+ *   const result = await doExpensiveOperation();
+ *   res.json(result);
+ * });
+ * ```
+ */
+declare function createRefundMiddleware(config: RefundProtectionConfig): (req: PaymentRequest & {
+    body?: unknown;
+}, res: {
+    locals?: {
+        paymentContext?: PaymentContext;
+    };
+}, next: (error?: unknown) => void) => Promise<void>;
+/**
+ * Create Hono middleware for refund protection.
+ *
+ * @example
+ * ```typescript
+ * import { Hono } from 'hono';
+ * import { honoRefundMiddleware } from '@openfacilitator/sdk';
+ *
+ * const app = new Hono();
+ *
+ * // Apply after your x402 payment verification
+ * app.post('/api/resource', paymentMiddleware, honoRefundMiddleware({
+ *   apiKey: process.env.REFUND_API_KEY!,
+ *   facilitatorUrl: 'https://free.openfacilitator.xyz',
+ *   getPaymentContext: (c) => c.get('paymentContext'),
+ * }), async (c) => {
+ *   const result = await doExpensiveOperation();
+ *   return c.json(result);
+ * });
+ * ```
+ */
+interface HonoRefundConfig extends RefundProtectionConfig {
+    /** Function to extract payment context from Hono context */
+    getPaymentContext: (c: HonoContext) => PaymentContext | undefined;
+}
+interface HonoContext {
+    get: (key: string) => unknown;
+    set: (key: string, value: unknown) => void;
+}
+declare function honoRefundMiddleware(config: HonoRefundConfig): (c: HonoContext, next: () => Promise<void>) => Promise<void>;
+/**
+ * Helper to create PaymentContext from settle response and payment payload.
+ *
+ * @example
+ * ```typescript
+ * import { OpenFacilitator, createPaymentContext } from '@openfacilitator/sdk';
+ *
+ * const facilitator = new OpenFacilitator({ url: '...' });
+ * const settleResult = await facilitator.settle(paymentPayload, requirements);
+ *
+ * const paymentContext = createPaymentContext(settleResult, paymentPayload);
+ * // Use with withRefundProtection or attach to request
+ * ```
+ */
+declare function createPaymentContext(settleResponse: {
+    transaction: string;
+    payer: string;
+    network: string;
+}, paymentPayload: {
+    payload: {
+        authorization: {
+            amount: string;
+            asset: string;
+        };
+    };
+}): PaymentContext;
+interface PaymentMiddlewareConfig {
+    /** Facilitator instance or URL */
+    facilitator: OpenFacilitator | string;
+    /** Function to get payment requirements for the request */
+    getRequirements: (req: unknown) => PaymentRequirements | Promise<PaymentRequirements>;
+    /** Optional: Refund protection config (enables auto failure reporting) */
+    refundProtection?: RefundProtectionConfig;
+    /** Optional: Custom 402 response handler */
+    on402?: (req: unknown, res: unknown, requirements: PaymentRequirements) => void | Promise<void>;
+}
+/**
+ * Create x402 payment middleware that handles verification, settlement, and optional refund protection.
+ *
+ * @example
+ * ```typescript
+ * import express from 'express';
+ * import { createPaymentMiddleware, OpenFacilitator } from '@openfacilitator/sdk';
+ *
+ * const app = express();
+ *
+ * const paymentMiddleware = createPaymentMiddleware({
+ *   facilitator: new OpenFacilitator({ url: 'https://free.openfacilitator.xyz' }),
+ *   getRequirements: (req) => ({
+ *     scheme: 'exact',
+ *     network: 'base',
+ *     maxAmountRequired: '1000000', // $1 USDC
+ *     asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+ *     payTo: '0xYourAddress',
+ *     resource: req.url,
+ *   }),
+ *   refundProtection: {
+ *     apiKey: process.env.REFUND_API_KEY!,
+ *     facilitatorUrl: 'https://free.openfacilitator.xyz',
+ *   },
+ * });
+ *
+ * app.post('/api/resource', paymentMiddleware, async (req, res) => {
+ *   // Payment verified & settled, refund protection active
+ *   const result = await doExpensiveOperation();
+ *   res.json(result);
+ * });
+ * ```
+ */
+declare function createPaymentMiddleware(config: PaymentMiddlewareConfig): (req: {
+    headers: Record<string, string | string[] | undefined>;
+    url?: string;
+    paymentContext?: PaymentContext;
+}, res: {
+    status: (code: number) => {
+        json: (body: unknown) => void;
+    };
+    locals?: Record<string, unknown>;
+}, next: (error?: unknown) => void) => Promise<void>;
+interface HonoPaymentConfig {
+    /** Facilitator instance or URL */
+    facilitator: OpenFacilitator | string;
+    /** Function to get payment requirements for the request */
+    getRequirements: (c: HonoContext) => PaymentRequirements | Promise<PaymentRequirements>;
+    /** Optional: Refund protection config */
+    refundProtection?: RefundProtectionConfig;
+}
+/**
+ * Create Hono x402 payment middleware.
+ *
+ * @example
+ * ```typescript
+ * import { Hono } from 'hono';
+ * import { honoPaymentMiddleware, OpenFacilitator } from '@openfacilitator/sdk';
+ *
+ * const app = new Hono();
+ *
+ * app.post('/api/resource', honoPaymentMiddleware({
+ *   facilitator: new OpenFacilitator({ url: 'https://free.openfacilitator.xyz' }),
+ *   getRequirements: (c) => ({
+ *     scheme: 'exact',
+ *     network: 'base',
+ *     maxAmountRequired: '1000000',
+ *     asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+ *     payTo: '0xYourAddress',
+ *   }),
+ *   refundProtection: {
+ *     apiKey: process.env.REFUND_API_KEY!,
+ *     facilitatorUrl: 'https://free.openfacilitator.xyz',
+ *   },
+ * }), async (c) => {
+ *   const paymentContext = c.get('paymentContext');
+ *   const result = await doExpensiveOperation();
+ *   return c.json(result);
+ * });
+ * ```
+ */
+declare function honoPaymentMiddleware(config: HonoPaymentConfig): (c: HonoContext & {
+    req: {
+        header: (name: string) => string | undefined;
+        url: string;
+    };
+    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 };