@cedros/pay-react 0.1.0

package/dist/utils/circuitBreaker.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Circuit Breaker Pattern Implementation
+ *
+ * Prevents cascading failures by "opening the circuit" when a service is failing,
+ * giving it time to recover before attempting requests again.
+ *
+ * States:
+ * - CLOSED: Normal operation, requests pass through
+ * - OPEN: Service is failing, requests fail immediately
+ * - HALF_OPEN: Testing if service has recovered
+ *
+ * Flow:
+ * 1. CLOSED → OPEN: After N consecutive failures
+ * 2. OPEN → HALF_OPEN: After timeout expires
+ * 3. HALF_OPEN → CLOSED: If request succeeds
+ * 4. HALF_OPEN → OPEN: If request fails
+ *
+ * Usage:
+ * ```typescript
+ * const breaker = createCircuitBreaker({ failureThreshold: 5, timeout: 30000 });
+ *
+ * const result = await breaker.execute(async () => {
+ *   return await fetch('/api/payment');
+ * });
+ * ```
+ */
+export declare enum CircuitState {
+    CLOSED = "CLOSED",
+    OPEN = "OPEN",
+    HALF_OPEN = "HALF_OPEN"
+}
+export interface CircuitBreakerConfig {
+    /** Number of consecutive failures before opening circuit */
+    failureThreshold: number;
+    /** Time in ms to wait before attempting recovery (OPEN → HALF_OPEN) */
+    timeout: number;
+    /** Optional name for logging/debugging */
+    name?: string;
+}
+export interface CircuitBreakerStats {
+    state: CircuitState;
+    failures: number;
+    successes: number;
+    rejections: number;
+    lastFailureTime: number | null;
+    lastSuccessTime: number | null;
+}
+export interface CircuitBreaker {
+    /** Execute a function with circuit breaker protection */
+    execute: <T>(fn: () => Promise<T>) => Promise<T>;
+    /** Get current circuit state */
+    getState: () => CircuitState;
+    /** Get circuit breaker statistics */
+    getStats: () => CircuitBreakerStats;
+    /** Manually reset circuit to CLOSED state */
+    reset: () => void;
+    /** Manually trip circuit to OPEN state */
+    trip: () => void;
+}
+/**
+ * Error thrown when circuit breaker is OPEN
+ */
+export declare class CircuitBreakerOpenError extends Error {
+    constructor(message: string);
+}
+/**
+ * Create a circuit breaker instance
+ *
+ * @param config - Circuit breaker configuration
+ * @returns Circuit breaker instance
+ *
+ * @example
+ * ```typescript
+ * const paymentBreaker = createCircuitBreaker({
+ *   failureThreshold: 5,
+ *   timeout: 30000,
+ *   name: 'payment-service',
+ * });
+ *
+ * try {
+ *   const result = await paymentBreaker.execute(async () => {
+ *     return await createPaymentSession();
+ *   });
+ * } catch (error) {
+ *   if (error instanceof CircuitBreakerOpenError) {
+ *     console.error('Payment service is down, please try again later');
+ *   }
+ * }
+ * ```
+ */
+export declare function createCircuitBreaker(config: CircuitBreakerConfig): CircuitBreaker;
+/**
+ * Preset circuit breaker configurations
+ */
+export declare const CIRCUIT_BREAKER_PRESETS: {
+    /** Strict: Opens quickly (3 failures), long timeout (60s) */
+    readonly STRICT: {
+        readonly failureThreshold: 3;
+        readonly timeout: 60000;
+    };
+    /** Standard: Balanced settings (5 failures, 30s timeout) */
+    readonly STANDARD: {
+        readonly failureThreshold: 5;
+        readonly timeout: 30000;
+    };
+    /** Lenient: Tolerates more failures (10 failures, 15s timeout) */
+    readonly LENIENT: {
+        readonly failureThreshold: 10;
+        readonly timeout: 15000;
+    };
+};
+//# sourceMappingURL=circuitBreaker.d.ts.map

package/dist/utils/circuitBreaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuitBreaker.d.ts","sourceRoot":"","sources":["../../src/utils/circuitBreaker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,oBAAY,YAAY;IACtB,MAAM,WAAW;IACjB,IAAI,SAAS;IACb,SAAS,cAAc;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC,4DAA4D;IAC5D,gBAAgB,EAAE,MAAM,CAAC;IACzB,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,YAAY,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,cAAc;IAC7B,yDAAyD;IACzD,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IACjD,gCAAgC;IAChC,QAAQ,EAAE,MAAM,YAAY,CAAC;IAC7B,qCAAqC;IACrC,QAAQ,EAAE,MAAM,mBAAmB,CAAC;IACpC,6CAA6C;IAC7C,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,0CAA0C;IAC1C,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB;AAED;;GAEG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,oBAAoB,GAAG,cAAc,CA6IjF;AAED;;GAEG;AACH,eAAO,MAAM,uBAAuB;IAClC,6DAA6D;;;;;IAE7D,4DAA4D;;;;;IAE5D,kEAAkE;;;;;CAE1D,CAAC"}

package/dist/utils/couponHelpers.d.ts

@@ -0,0 +1,50 @@
+import { SettlementResponse } from '../types';
+/**
+ * Parse coupon codes from metadata
+ *
+ * Parses comma-separated coupon codes from the coupon_codes field
+ *
+ * @param metadata - Metadata object from settlement response or cart callback
+ * @returns Array of coupon codes that were applied
+ *
+ * @example
+ * // Multiple coupons
+ * parseCouponCodes({ coupon_codes: "SITE10,CRYPTO5AUTO,SAVE20" })
+ * // Returns: ["SITE10", "CRYPTO5AUTO", "SAVE20"]
+ *
+ * @example
+ * // Single coupon
+ * parseCouponCodes({ coupon_codes: "SAVE20" })
+ * // Returns: ["SAVE20"]
+ *
+ * @example
+ * // No coupons applied
+ * parseCouponCodes({})
+ * // Returns: []
+ */
+export declare function parseCouponCodes(metadata?: Record<string, string | undefined> | SettlementResponse["metadata"]): string[];
+/**
+ * Format coupon codes for display
+ *
+ * @param coupons - Array of coupon codes
+ * @param separator - Separator string (default: ", ")
+ * @returns Formatted string
+ *
+ * @example
+ * formatCouponCodes(["SITE10", "CRYPTO5AUTO", "SAVE20"])
+ * // Returns: "SITE10, CRYPTO5AUTO, SAVE20"
+ */
+export declare function formatCouponCodes(coupons: string[], separator?: string): string;
+/**
+ * Calculate total discount percentage
+ *
+ * @param originalAmount - Original price before discounts
+ * @param discountedAmount - Final price after discounts
+ * @returns Discount percentage (0-100)
+ *
+ * @example
+ * calculateDiscountPercentage(100, 75)
+ * // Returns: 25.0
+ */
+export declare function calculateDiscountPercentage(originalAmount: number, discountedAmount: number): number;
+//# sourceMappingURL=couponHelpers.d.ts.map

package/dist/utils/couponHelpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"couponHelpers.d.ts","sourceRoot":"","sources":["../../src/utils/couponHelpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,kBAAkB,CAAC,UAAU,CAAC,GAC7E,MAAM,EAAE,CASV;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EAAE,EACjB,SAAS,GAAE,MAAa,GACvB,MAAM,CAER;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CACzC,cAAc,EAAE,MAAM,EACtB,gBAAgB,EAAE,MAAM,GACvB,MAAM,CAIR"}

package/dist/utils/cspHelper.d.ts

@@ -0,0 +1,162 @@
+import { SolanaCluster } from '../types';
+/**
+ * CSP generation options
+ */
+export interface CSPConfig {
+    /**
+     * Solana network cluster
+     * Determines which Solana RPC endpoints to include
+     */
+    solanaCluster?: SolanaCluster;
+    /**
+     * Custom Solana RPC endpoint URL
+     * If provided, this domain will be added to connect-src
+     * @example "https://mainnet.helius-rpc.com"
+     */
+    solanaEndpoint?: string;
+    /**
+     * Additional custom RPC providers
+     * Common providers: Helius, QuickNode, Alchemy, Ankr
+     * @example ["https://*.helius-rpc.com", "https://*.quicknode.pro"]
+     */
+    customRpcProviders?: string[];
+    /**
+     * Whether to include 'unsafe-inline' and 'unsafe-eval' in script-src
+     * Required for some frameworks (Next.js, etc.)
+     * @default false
+     */
+    allowUnsafeScripts?: boolean;
+    /**
+     * Additional domains to include in script-src
+     * @example ["https://cdn.example.com"]
+     */
+    additionalScriptSrc?: string[];
+    /**
+     * Additional domains to include in connect-src
+     * @example ["https://api.example.com"]
+     */
+    additionalConnectSrc?: string[];
+    /**
+     * Additional domains to include in frame-src
+     * @example ["https://embed.example.com"]
+     */
+    additionalFrameSrc?: string[];
+    /**
+     * Whether to include Stripe directives
+     * Set to false if only using crypto payments
+     * @default true
+     */
+    includeStripe?: boolean;
+}
+/**
+ * Generated CSP directives
+ */
+export interface CSPDirectives {
+    scriptSrc: string[];
+    connectSrc: string[];
+    frameSrc: string[];
+}
+/**
+ * CSP output format for different frameworks
+ */
+export type CSPFormat = 'header' | 'meta' | 'nextjs' | 'helmet' | 'nginx' | 'directives';
+/**
+ * Generate CSP directives for Cedros Pay
+ *
+ * @param config - CSP configuration options
+ * @returns Object containing script-src, connect-src, and frame-src arrays
+ *
+ * @example
+ * ```typescript
+ * const directives = generateCSPDirectives({
+ *   solanaCluster: 'mainnet-beta',
+ *   solanaEndpoint: 'https://mainnet.helius-rpc.com',
+ *   allowUnsafeScripts: true, // Required for Next.js
+ * });
+ * ```
+ */
+export declare function generateCSPDirectives(config?: CSPConfig): CSPDirectives;
+/**
+ * Format CSP directives for different frameworks and environments
+ *
+ * @param directives - CSP directives from generateCSPDirectives()
+ * @param format - Output format
+ * @returns Formatted CSP string or object
+ *
+ * @example
+ * ```typescript
+ * const directives = generateCSPDirectives({ solanaCluster: 'mainnet-beta' });
+ *
+ * // HTTP Header format
+ * const header = formatCSP(directives, 'header');
+ * // "script-src 'self' https://js.stripe.com; connect-src 'self' ..."
+ *
+ * // Next.js config format
+ * const nextjs = formatCSP(directives, 'nextjs');
+ *
+ * // Express helmet format
+ * const helmet = formatCSP(directives, 'helmet');
+ * ```
+ */
+export declare function formatCSP(directives: CSPDirectives, format?: CSPFormat): string | Record<string, string[]>;
+/**
+ * Generate CSP string for Cedros Pay (convenience function)
+ *
+ * Combines generateCSPDirectives() and formatCSP() into a single call.
+ *
+ * @param config - CSP configuration options
+ * @param format - Output format (default: 'header')
+ * @returns Formatted CSP string or object
+ *
+ * @example
+ * ```typescript
+ * // Quick CSP generation for HTTP headers
+ * const csp = generateCSP({
+ *   solanaCluster: 'mainnet-beta',
+ *   solanaEndpoint: 'https://mainnet.helius-rpc.com',
+ *   allowUnsafeScripts: true,
+ * });
+ * // "script-src 'self' 'unsafe-inline' 'unsafe-eval' https://js.stripe.com; ..."
+ *
+ * // For Express helmet
+ * const helmetCSP = generateCSP({ solanaCluster: 'mainnet-beta' }, 'helmet');
+ * app.use(helmet.contentSecurityPolicy({ directives: helmetCSP }));
+ * ```
+ */
+export declare function generateCSP(config?: CSPConfig, format?: CSPFormat): string | Record<string, string[]>;
+/**
+ * Common RPC provider patterns for convenience
+ */
+export declare const RPC_PROVIDERS: {
+    readonly HELIUS: "https://*.helius-rpc.com";
+    readonly QUICKNODE: "https://*.quicknode.pro";
+    readonly ALCHEMY: "https://*.alchemy.com";
+    readonly ANKR: "https://rpc.ankr.com";
+    readonly TRITON: "https://*.rpcpool.com";
+};
+/**
+ * Preset CSP configurations for common scenarios
+ */
+export declare const CSP_PRESETS: {
+    /**
+     * Mainnet production with custom RPC (recommended)
+     */
+    readonly MAINNET_CUSTOM_RPC: (rpcEndpoint: string) => CSPConfig;
+    /**
+     * Mainnet with Next.js (requires unsafe-inline/eval)
+     */
+    readonly MAINNET_NEXTJS: (rpcEndpoint?: string) => CSPConfig;
+    /**
+     * Devnet for testing
+     */
+    readonly DEVNET: () => CSPConfig;
+    /**
+     * Crypto-only payments (no Stripe)
+     */
+    readonly CRYPTO_ONLY: (rpcEndpoint?: string) => CSPConfig;
+    /**
+     * Stripe-only payments (no Solana)
+     */
+    readonly STRIPE_ONLY: () => CSPConfig;
+};
+//# sourceMappingURL=cspHelper.d.ts.map

package/dist/utils/cspHelper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cspHelper.d.ts","sourceRoot":"","sources":["../../src/utils/cspHelper.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE9C;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB;;;OAGG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAE9B;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE9B;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAE7B;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE/B;;;OAGG;IACH,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;IAEhC;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE9B;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,MAAM,SAAS,GACjB,QAAQ,GACR,MAAM,GACN,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,YAAY,CAAC;AA+BjB;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,GAAE,SAAc,GAAG,aAAa,CAmE3E;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,SAAS,CACvB,UAAU,EAAE,aAAa,EACzB,MAAM,GAAE,SAAoB,GAC3B,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CA4CnC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,WAAW,CACzB,MAAM,GAAE,SAAc,EACtB,MAAM,GAAE,SAAoB,GAC3B,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAGnC;AAED;;GAEG;AACH,eAAO,MAAM,aAAa;;;;;;CAMhB,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,WAAW;IACtB;;OAEG;+CAC+B,MAAM,KAAG,SAAS;IAMpD;;OAEG;4CAC4B,MAAM,KAAG,SAAS;IAMjD;;OAEG;2BACS,SAAS;IAKrB;;OAEG;yCACyB,MAAM,KAAG,SAAS;IAM9C;;OAEG;gCACc,SAAS;CAMlB,CAAC"}

package/dist/utils/deprecation.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Deprecation utilities for managing API lifecycle
+ *
+ * Provides helpers for marking APIs as deprecated with clear migration paths.
+ */
+/**
+ * Deprecation severity levels
+ */
+export declare enum DeprecationLevel {
+    /** Soft warning - API works but has a better alternative */
+    WARNING = "warning",
+    /** Notice - API will be removed in next major version */
+    NOTICE = "notice",
+    /** Critical - API will be removed soon, migration urgent */
+    CRITICAL = "critical"
+}
+/**
+ * Deprecation metadata
+ */
+export interface DeprecationInfo {
+    /** What is being deprecated */
+    feature: string;
+    /** Why it's deprecated */
+    reason: string;
+    /** What to use instead */
+    replacement?: string;
+    /** Version when it will be removed */
+    removalVersion?: string;
+    /** Additional migration notes */
+    migrationGuide?: string;
+    /** Severity level */
+    level: DeprecationLevel;
+}
+/**
+ * Log a deprecation warning (once per session)
+ *
+ * @param info - Deprecation details
+ *
+ * @example
+ * ```typescript
+ * logDeprecation({
+ *   feature: 'StripeManager class export',
+ *   reason: 'Direct class imports create breaking changes',
+ *   replacement: 'Use IStripeManager interface from context',
+ *   removalVersion: '3.0.0',
+ *   level: DeprecationLevel.NOTICE
+ * });
+ * ```
+ */
+export declare function logDeprecation(info: DeprecationInfo): void;
+/**
+ * Mark a function as deprecated with automatic warnings
+ *
+ * @param fn - Function to deprecate
+ * @param info - Deprecation details
+ * @returns Wrapped function that logs deprecation warnings
+ *
+ * @example
+ * ```typescript
+ * export const oldFunction = deprecate(
+ *   (x: number) => x * 2,
+ *   {
+ *     feature: 'oldFunction',
+ *     reason: 'Use the new API instead',
+ *     replacement: 'newFunction',
+ *     removalVersion: '3.0.0',
+ *     level: DeprecationLevel.NOTICE
+ *   }
+ * );
+ * ```
+ */
+export declare function deprecate<T extends (...args: any[]) => any>(fn: T, info: DeprecationInfo): T;
+/**
+ * Mark a class as deprecated
+ *
+ * Returns a Proxy that logs deprecation warnings on construction
+ *
+ * @param Class - Class to deprecate
+ * @param info - Deprecation details
+ * @returns Proxied class that warns on instantiation
+ *
+ * @example
+ * ```typescript
+ * export const OldManager = deprecateClass(
+ *   OldManagerImpl,
+ *   {
+ *     feature: 'OldManager class',
+ *     reason: 'Use interface from context instead',
+ *     replacement: 'useCedrosContext().manager',
+ *     removalVersion: '3.0.0',
+ *     level: DeprecationLevel.CRITICAL
+ *   }
+ * );
+ * ```
+ */
+export declare function deprecateClass<T extends new (...args: any[]) => any>(Class: T, info: DeprecationInfo): T;
+/**
+ * Create a deprecation notice for an export
+ *
+ * Use this to create a deprecated re-export that warns users
+ *
+ * @param value - Value to re-export
+ * @param info - Deprecation details
+ * @returns Proxied value that warns on access
+ *
+ * @example
+ * ```typescript
+ * // In index.ts
+ * export const DeprecatedExport = deprecateExport(
+ *   ActualImplementation,
+ *   {
+ *     feature: 'DeprecatedExport',
+ *     reason: 'Moved to new package',
+ *     replacement: '@new-package/export',
+ *     removalVersion: '3.0.0',
+ *     level: DeprecationLevel.NOTICE
+ *   }
+ * );
+ * ```
+ */
+export declare function deprecateExport<T>(value: T, info: DeprecationInfo): T;
+/**
+ * Reset deprecation warnings (useful for testing)
+ *
+ * @internal
+ */
+export declare function resetDeprecationWarnings(): void;
+//# sourceMappingURL=deprecation.d.ts.map

package/dist/utils/deprecation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deprecation.d.ts","sourceRoot":"","sources":["../../src/utils/deprecation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;GAEG;AACH,oBAAY,gBAAgB;IAC1B,4DAA4D;IAC5D,OAAO,YAAY;IACnB,yDAAyD;IACzD,MAAM,WAAW;IACjB,4DAA4D;IAC5D,QAAQ,aAAa;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,0BAA0B;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sCAAsC;IACtC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iCAAiC;IACjC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qBAAqB;IACrB,KAAK,EAAE,gBAAgB,CAAC;CACzB;AAKD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI,CAmC1D;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,wBAAgB,SAAS,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EACzD,EAAE,EAAE,CAAC,EACL,IAAI,EAAE,eAAe,GACpB,CAAC,CAMH;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,wBAAgB,cAAc,CAAC,CAAC,SAAS,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EAClE,KAAK,EAAE,CAAC,EACR,IAAI,EAAE,eAAe,GACpB,CAAC,CAQH;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,eAAe,GAAG,CAAC,CA2BrE;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C"}

package/dist/utils/errorHandling.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Format error into user-friendly message string
+ *
+ * Consolidates the repetitive `error instanceof Error ? error.message : fallback`
+ * pattern used throughout the codebase into a single utility.
+ *
+ * @param error - The error to format (can be Error, string, or unknown type)
+ * @param fallback - Fallback message if error cannot be converted to string
+ * @returns User-friendly error message string
+ *
+ * @example
+ * formatError(new Error('Failed'), 'Unknown error') // Returns: 'Failed'
+ * formatError('Custom error', 'Unknown error')      // Returns: 'Custom error'
+ * formatError(null, 'Unknown error')                // Returns: 'Unknown error'
+ */
+export declare function formatError(error: unknown, fallback: string): string;
+/**
+ * Parse error response from failed HTTP requests
+ *
+ * Shared utility for consistent error handling across managers.
+ * Tries JSON parsing first, falls back to plain text if that fails.
+ * Supports both standard error responses and X402Response verification errors.
+ *
+ * @param response - The failed HTTP response
+ * @param defaultMessage - Fallback message if parsing fails
+ * @param parseVerificationError - If true, handle X402Response verification errors with detailed mapping
+ * @returns User-friendly error message
+ */
+export declare function parseErrorResponse(response: Response, defaultMessage: string, parseVerificationError?: boolean): Promise<string>;
+//# sourceMappingURL=errorHandling.d.ts.map

package/dist/utils/errorHandling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorHandling.d.ts","sourceRoot":"","sources":["../../src/utils/errorHandling.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAQpE;AAgBD;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,QAAQ,EAClB,cAAc,EAAE,MAAM,EACtB,sBAAsB,GAAE,OAAe,GACtC,OAAO,CAAC,MAAM,CAAC,CAwBjB"}

package/dist/utils/errorMessages.d.ts

@@ -0,0 +1,47 @@
+/**
+ * User-Friendly Error Messages
+ *
+ * Provides contextual, actionable error messages for all payment error codes.
+ * Messages are designed to:
+ * - Be clear and non-technical
+ * - Provide actionable next steps
+ * - Avoid embarrassing the business
+ * - Enable user self-service
+ * - Support internationalization
+ */
+/**
+ * User-friendly error message with actionable guidance
+ */
+export interface ErrorMessage {
+    /** Short user-friendly message */
+    message: string;
+    /** Actionable next steps for the user */
+    action?: string;
+    /** Support-friendly technical detail (optional, for error reporting) */
+    technicalHint?: string;
+}
+/**
+ * Error message map: error code string -> User-friendly message with actions
+ *
+ * Translation key format: `errors.{error_code}.{message|action}`
+ * Example: errors.insufficient_funds_token.message
+ *
+ * Note: Uses string keys instead of enum to avoid circular dependency with types/errors.ts
+ */
+export declare const ERROR_MESSAGES: Record<string, ErrorMessage>;
+/**
+ * Get user-friendly error message for an error code string
+ *
+ * @param code - Payment error code (as string)
+ * @returns User-friendly error message with action
+ */
+export declare function getUserFriendlyError(code: string): ErrorMessage;
+/**
+ * Format error for display to user
+ *
+ * @param code - Payment error code (as string)
+ * @param includeAction - Whether to include the action guidance (default: true)
+ * @returns Formatted error string
+ */
+export declare function formatUserError(code: string, includeAction?: boolean): string;
+//# sourceMappingURL=errorMessages.d.ts.map

package/dist/utils/errorMessages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorMessages.d.ts","sourceRoot":"","sources":["../../src/utils/errorMessages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAkTvD,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAM/D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,aAAa,GAAE,OAAc,GAAG,MAAM,CAMnF"}

package/dist/utils/errorParser.d.ts

@@ -0,0 +1,37 @@
+import { PaymentError } from '../types/errors';
+/**
+ * Parse JSON error response from backend API
+ *
+ * Expects structured error format from backend:
+ * {
+ *   error: {
+ *     code: "insufficient_funds_token",
+ *     message: "Insufficient token balance",
+ *     retryable: false,
+ *     details?: { ... }
+ *   }
+ * }
+ *
+ * @param response - Fetch Response object
+ * @returns PaymentError with structured error information
+ */
+export declare function parseErrorResponse(response: Response): Promise<PaymentError>;
+/**
+ * Check if an error is retryable
+ *
+ * Convenience function to check if an error (of any type) is retryable.
+ *
+ * @param error - Error to check
+ * @returns true if error is a PaymentError and is retryable
+ */
+export declare function isRetryableError(error: unknown): boolean;
+/**
+ * Get user-friendly error message
+ *
+ * Extracts a user-friendly message from any error type.
+ *
+ * @param error - Error to extract message from
+ * @returns User-friendly error message
+ */
+export declare function getUserErrorMessage(error: unknown): string;
+//# sourceMappingURL=errorParser.d.ts.map

package/dist/utils/errorParser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorParser.d.ts","sourceRoot":"","sources":["../../src/utils/errorParser.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAwC,MAAM,iBAAiB,CAAC;AAErF;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,YAAY,CAAC,CA8BlF;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAExD;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAU1D"}