@zendfi/sdk 0.5.8 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { C as CreateAgentApiKeyRequest, A as AgentApiKey, b as CreateAgentSessionRequest, c as AgentSession, d as AgentPaymentRequest, e as AgentPaymentResponse, f as AgentAnalytics, g as CreatePaymentIntentRequest, P as PaymentIntent, h as ConfirmPaymentIntentRequest, i as PaymentIntentEvent, j as PPPFactor, k as PricingSuggestionRequest, l as PricingSuggestion, E as EnableAutonomyRequest, m as EnableAutonomyResponse, n as AutonomyStatus, S as SmartPaymentRequest, o as SmartPaymentResponse, p as CreateSessionKeyRequest, q as CreateSessionKeyResponse, r as CreateDeviceBoundSessionKeyRequest$1, s as CreateDeviceBoundSessionKeyResponse$1, t as SubmitSignedTransactionRequest, u as SubmitTransactionResponse, v as SessionKeyStatus, w as SessionKeyListResponse, T as TopUpSessionKeyRequest, x as TopUpSessionKeyResponse, Z as ZendFiConfig, y as CreatePaymentRequest, z as Payment, L as ListPaymentsRequest, B as PaginatedResponse, D as CreateSubscriptionPlanRequest, F as SubscriptionPlan, G as CreateSubscriptionRequest, H as Subscription, I as CreatePaymentLinkRequest, J as PaymentLink, K as CreateInstallmentPlanRequest, M as InstallmentPlan, N as CreateEscrowRequest, O as Escrow, Q as ApproveEscrowRequest, R as RefundEscrowRequest, U as DisputeEscrowRequest, V as CreateInvoiceRequest, X as Invoice, Y as VerifyWebhookRequest, _ as WebhookPayload } from './webhook-handler-D5CigE9G.js';
2
- export { a5 as AgentKeyId, ao as ApiKeyMode, aD as ApiKeyScope, aJ as AutonomousDelegate, a2 as Brand, aG as CaptureMethod, aA as CreateInstallmentPlanResponse, ap as Currency, an as Environment, a9 as EscrowId, au as EscrowStatus, aa as InstallmentPlanId, at as InstallmentPlanStatus, az as InstallmentScheduleItem, ac as IntentId, a7 as InvoiceId, aC as InvoiceLineItem, av as InvoiceStatus, aO as LinkedSessionInfo, a6 as MerchantId, aI as PPPConfig, a3 as PaymentId, aF as PaymentIntentStatus, ab as PaymentLinkCode, ar as PaymentStatus, aq as PaymentToken, aB as ReleaseCondition, aK as RevokeAutonomyRequest, aP as SecurityStatus, a4 as SessionId, aM as SessionKeyInstructions, aN as SessionKeySecurityInfo, aQ as SessionKeyStats, aE as SessionLimits, aL as SmartPaymentStatus, ay as SplitRecipient, aw as SplitStatus, a8 as SubscriptionId, as as SubscriptionStatus, aH as UserProfile, ax as WebhookEvent, a1 as WebhookEventHandler, W as WebhookHandlerConfig, a as WebhookHandlers, a0 as WebhookResult, af as asAgentKeyId, aj as asEscrowId, ak as asInstallmentPlanId, am as asIntentId, ah as asInvoiceId, ag as asMerchantId, ad as asPaymentId, al as asPaymentLinkCode, ae as asSessionId, ai as asSubscriptionId, $ as processWebhook } from './webhook-handler-D5CigE9G.js';
1
+ import { C as CreateAgentApiKeyRequest, A as AgentApiKey, b as CreateAgentSessionRequest, c as AgentSession, d as AgentPaymentRequest, e as AgentPaymentResponse, f as AgentAnalytics, g as CreatePaymentIntentRequest, P as PaymentIntent, h as ConfirmPaymentIntentRequest, i as PaymentIntentEvent, j as PPPFactor, k as PricingSuggestionRequest, l as PricingSuggestion, E as EnableAutonomyRequest, m as EnableAutonomyResponse, n as AutonomyStatus, S as SmartPaymentRequest, o as SmartPaymentResponse, p as CreateSessionKeyRequest, q as CreateSessionKeyResponse, r as CreateDeviceBoundSessionKeyRequest$1, s as CreateDeviceBoundSessionKeyResponse$1, t as SubmitSignedTransactionRequest, u as SubmitTransactionResponse, v as SessionKeyStatus, w as SessionKeyListResponse, T as TopUpSessionKeyRequest, x as TopUpSessionKeyResponse, Z as ZendFiConfig, y as CreatePaymentRequest, z as Payment, L as ListPaymentsRequest, B as PaginatedResponse, D as CreateSubscriptionPlanRequest, F as SubscriptionPlan, G as CreateSubscriptionRequest, H as Subscription, I as CreatePaymentLinkRequest, J as PaymentLink, K as CreateInstallmentPlanRequest, M as InstallmentPlan, N as CreateEscrowRequest, O as Escrow, Q as ApproveEscrowRequest, R as RefundEscrowRequest, U as DisputeEscrowRequest, V as CreateInvoiceRequest, X as Invoice, Y as VerifyWebhookRequest, _ as WebhookPayload, $ as ApiKeyMode } from './webhook-handler-D5INiR-l.js';
2
+ export { a6 as AgentKeyId, aD as ApiKeyScope, aJ as AutonomousDelegate, a3 as Brand, aG as CaptureMethod, aA as CreateInstallmentPlanResponse, ap as Currency, ao as Environment, aa as EscrowId, au as EscrowStatus, ab as InstallmentPlanId, at as InstallmentPlanStatus, az as InstallmentScheduleItem, ad as IntentId, a8 as InvoiceId, aC as InvoiceLineItem, av as InvoiceStatus, aO as LinkedSessionInfo, a7 as MerchantId, aI as PPPConfig, a4 as PaymentId, aF as PaymentIntentStatus, ac as PaymentLinkCode, ar as PaymentStatus, aq as PaymentToken, aB as ReleaseCondition, aK as RevokeAutonomyRequest, aP as SecurityStatus, a5 as SessionId, aM as SessionKeyInstructions, aN as SessionKeySecurityInfo, aQ as SessionKeyStats, aE as SessionLimits, aL as SmartPaymentStatus, ay as SplitRecipient, aw as SplitStatus, a9 as SubscriptionId, as as SubscriptionStatus, aH as UserProfile, ax as WebhookEvent, a2 as WebhookEventHandler, W as WebhookHandlerConfig, a as WebhookHandlers, a1 as WebhookResult, ag as asAgentKeyId, ak as asEscrowId, al as asInstallmentPlanId, an as asIntentId, ai as asInvoiceId, ah as asMerchantId, ae as asPaymentId, am as asPaymentLinkCode, af as asSessionId, aj as asSubscriptionId, a0 as processWebhook } from './webhook-handler-D5INiR-l.js';
3
3
  import { Transaction, Keypair } from '@solana/web3.js';
4
4
 
5
5
  /**
@@ -715,6 +715,68 @@ declare class AutonomyAPI {
715
715
  * ```
716
716
  */
717
717
  validateRequest(request: EnableAutonomyRequest): void;
718
+ /**
719
+ * Get spending attestations for a delegate (audit trail)
720
+ *
721
+ * Returns all cryptographically signed attestations ZendFi created for
722
+ * this delegate. Each attestation contains:
723
+ * - The spending state at the time of payment
724
+ * - ZendFi's Ed25519 signature
725
+ * - Timestamp and nonce (for replay protection)
726
+ *
727
+ * These attestations can be independently verified using ZendFi's public key
728
+ * to confirm spending limit enforcement was applied correctly.
729
+ *
730
+ * @param delegateId - UUID of the autonomous delegate
731
+ * @returns Attestation audit response with all signed attestations
732
+ *
733
+ * @example
734
+ * ```typescript
735
+ * const audit = await zendfi.autonomy.getAttestations('delegate_123...');
736
+ *
737
+ * console.log(`Found ${audit.attestation_count} attestations`);
738
+ * console.log(`ZendFi public key: ${audit.zendfi_attestation_public_key}`);
739
+ *
740
+ * // Verify each attestation independently
741
+ * for (const signed of audit.attestations) {
742
+ * console.log(`Payment ${signed.attestation.payment_id}:`);
743
+ * console.log(` Requested: $${signed.attestation.requested_usd}`);
744
+ * console.log(` Remaining after: $${signed.attestation.remaining_after_usd}`);
745
+ * // Verify signature with nacl.sign.detached.verify()
746
+ * }
747
+ * ```
748
+ */
749
+ getAttestations(delegateId: string): Promise<AttestationAuditResponse>;
750
+ }
751
+ /** Spending attestation - ZendFi's signed commitment to spending state */
752
+ interface SpendingAttestation {
753
+ delegate_id: string;
754
+ session_key_id: string;
755
+ merchant_id: string;
756
+ spent_usd: number;
757
+ limit_usd: number;
758
+ requested_usd: number;
759
+ remaining_after_usd: number;
760
+ timestamp_ms: number;
761
+ nonce: string;
762
+ payment_id: string;
763
+ version: number;
764
+ }
765
+ /** Signed attestation with ZendFi's cryptographic signature */
766
+ interface SignedSpendingAttestation {
767
+ attestation: SpendingAttestation;
768
+ /** Base64-encoded Ed25519 signature */
769
+ signature: string;
770
+ /** Base58-encoded ZendFi public key */
771
+ signer_public_key: string;
772
+ }
773
+ /** Response from the attestation audit endpoint */
774
+ interface AttestationAuditResponse {
775
+ delegate_id: string;
776
+ attestation_count: number;
777
+ attestations: SignedSpendingAttestation[];
778
+ /** ZendFi's attestation public key for independent verification */
779
+ zendfi_attestation_public_key: string | null;
718
780
  }
719
781
 
720
782
  /**
@@ -1691,6 +1753,211 @@ declare function verifyExpressWebhook(request: any, secret?: string): Promise<We
1691
1753
  */
1692
1754
  declare function verifyWebhookSignature(payload: string, signature: string, secret: string): boolean;
1693
1755
 
1756
+ /**
1757
+ * ZendFi Embedded Checkout
1758
+ *
1759
+ * Embed the ZendFi checkout directly into your website/app
1760
+ * without redirecting to checkout.zendfi.tech
1761
+ *
1762
+ * @example
1763
+ * ```typescript
1764
+ * import { ZendFiEmbeddedCheckout } from '@zendfi/sdk';
1765
+ *
1766
+ * const checkout = new ZendFiEmbeddedCheckout({
1767
+ * linkCode: 'abc123xyz',
1768
+ * containerId: 'zendfi-checkout',
1769
+ * mode: 'live',
1770
+ * onSuccess: (payment) => {
1771
+ * console.log('Payment successful!', payment);
1772
+ * },
1773
+ * onError: (error) => {
1774
+ * console.error('Payment failed:', error);
1775
+ * }
1776
+ * });
1777
+ *
1778
+ * checkout.mount();
1779
+ * ```
1780
+ */
1781
+
1782
+ interface EmbeddedCheckoutConfig {
1783
+ /** Payment link code or payment ID */
1784
+ linkCode?: string;
1785
+ paymentId?: string;
1786
+ /** Container element ID where checkout will be mounted */
1787
+ containerId: string;
1788
+ /** API mode - 'test' for devnet, 'live' for mainnet */
1789
+ mode?: ApiKeyMode;
1790
+ /** API base URL (defaults to production) */
1791
+ apiUrl?: string;
1792
+ /** Callback when payment is successful */
1793
+ onSuccess?: (payment: PaymentSuccessData) => void;
1794
+ /** Callback when payment fails */
1795
+ onError?: (error: CheckoutError) => void;
1796
+ /** Callback when checkout is loaded */
1797
+ onLoad?: () => void;
1798
+ /** Custom theme overrides */
1799
+ theme?: CheckoutTheme;
1800
+ /** Enable custom amount (Pay What You Want) */
1801
+ allowCustomAmount?: boolean;
1802
+ /** Show/hide specific payment methods */
1803
+ paymentMethods?: {
1804
+ walletConnect?: boolean;
1805
+ qrCode?: boolean;
1806
+ solanaWallet?: boolean;
1807
+ };
1808
+ }
1809
+ interface CheckoutTheme {
1810
+ primaryColor?: string;
1811
+ backgroundColor?: string;
1812
+ borderRadius?: string;
1813
+ fontFamily?: string;
1814
+ textColor?: string;
1815
+ buttonStyle?: 'solid' | 'outlined' | 'minimal';
1816
+ }
1817
+ interface PaymentSuccessData {
1818
+ paymentId: string;
1819
+ transactionSignature: string;
1820
+ amount: number;
1821
+ token: string;
1822
+ merchantName: string;
1823
+ }
1824
+ interface CheckoutError {
1825
+ code: string;
1826
+ message: string;
1827
+ details?: any;
1828
+ }
1829
+ /**
1830
+ * ZendFi Embedded Checkout Component
1831
+ *
1832
+ * Provides a fully-functional checkout experience that can be
1833
+ * embedded directly into any web application.
1834
+ */
1835
+ declare class ZendFiEmbeddedCheckout {
1836
+ private config;
1837
+ private container;
1838
+ private checkoutData;
1839
+ private pollInterval;
1840
+ private mounted;
1841
+ constructor(config: EmbeddedCheckoutConfig);
1842
+ private getDefaultApiUrl;
1843
+ /**
1844
+ * Mount the checkout to the DOM
1845
+ */
1846
+ mount(): Promise<void>;
1847
+ /**
1848
+ * Unmount and cleanup
1849
+ */
1850
+ unmount(): void;
1851
+ /**
1852
+ * Fetch checkout data from API
1853
+ */
1854
+ private fetchCheckoutData;
1855
+ /**
1856
+ * Poll for payment confirmation
1857
+ */
1858
+ private startPaymentPolling;
1859
+ /**
1860
+ * Handle successful payment
1861
+ */
1862
+ private handlePaymentSuccess;
1863
+ /**
1864
+ * Handle payment failure
1865
+ */
1866
+ private handlePaymentFailure;
1867
+ /**
1868
+ * Handle payment expiration
1869
+ */
1870
+ private handlePaymentExpired;
1871
+ /**
1872
+ * Render loading state
1873
+ */
1874
+ private renderLoading;
1875
+ /**
1876
+ * Render the main checkout UI
1877
+ */
1878
+ private render;
1879
+ /**
1880
+ * Render header section
1881
+ */
1882
+ private renderHeader;
1883
+ /**
1884
+ * Render payment information
1885
+ */
1886
+ private renderPaymentInfo;
1887
+ /**
1888
+ * Render custom amount input (Pay What You Want)
1889
+ */
1890
+ private renderCustomAmountInput;
1891
+ /**
1892
+ * Render payment methods
1893
+ */
1894
+ private renderPaymentMethods;
1895
+ /**
1896
+ * Render QR code payment method
1897
+ */
1898
+ private renderQRCodeMethod;
1899
+ /**
1900
+ * Render browser wallet method
1901
+ */
1902
+ private renderWalletMethod;
1903
+ /**
1904
+ * Render WalletConnect method
1905
+ */
1906
+ private renderWalletConnectMethod;
1907
+ /**
1908
+ * Render footer
1909
+ */
1910
+ private renderFooter;
1911
+ /**
1912
+ * Render success state
1913
+ */
1914
+ private renderSuccess;
1915
+ /**
1916
+ * Render error state
1917
+ */
1918
+ private renderError;
1919
+ /**
1920
+ * Attach event listeners to interactive elements
1921
+ */
1922
+ private attachEventListeners;
1923
+ /**
1924
+ * Handle wallet connection and payment
1925
+ */
1926
+ private handleWalletConnect;
1927
+ /**
1928
+ * Handle mobile wallet connection via Solana Pay deep link
1929
+ */
1930
+ private handleWalletConnectScan;
1931
+ /**
1932
+ * Generate QR code on canvas using QRious library
1933
+ */
1934
+ private generateQRCode;
1935
+ /**
1936
+ * Inject custom styles
1937
+ */
1938
+ private injectStyles;
1939
+ /**
1940
+ * Load external dependencies (QR code library, Solana web3.js)
1941
+ */
1942
+ private loadDependencies;
1943
+ /**
1944
+ * Load external script
1945
+ */
1946
+ private loadScript;
1947
+ /**
1948
+ * Get computed theme with defaults
1949
+ */
1950
+ private getComputedTheme;
1951
+ /**
1952
+ * Style helpers
1953
+ */
1954
+ private getCheckoutContainerStyles;
1955
+ private getLoadingStyles;
1956
+ private getSpinnerStyles;
1957
+ private getSuccessStyles;
1958
+ private getErrorStyles;
1959
+ }
1960
+
1694
1961
  /**
1695
1962
  * ZendFi SDK Error Classes
1696
1963
  *
@@ -2058,6 +2325,8 @@ declare class DeviceBoundSessionKey {
2058
2325
 
2059
2326
  interface CreateDeviceBoundSessionKeyRequest {
2060
2327
  userWallet: string;
2328
+ agentId: string;
2329
+ agentName?: string;
2061
2330
  limitUsdc: number;
2062
2331
  durationDays: number;
2063
2332
  encryptedSessionKey: string;
@@ -2071,10 +2340,13 @@ interface CreateDeviceBoundSessionKeyResponse {
2071
2340
  mode: 'device_bound';
2072
2341
  isCustodial: false;
2073
2342
  userWallet: string;
2343
+ agentId: string;
2344
+ agentName?: string;
2074
2345
  sessionWallet: string;
2075
2346
  limitUsdc: number;
2076
2347
  expiresAt: string;
2077
2348
  requiresClientSigning: true;
2349
+ crossAppCompatible: boolean;
2078
2350
  securityInfo: {
2079
2351
  encryptionType: string;
2080
2352
  deviceBound: boolean;
@@ -2105,6 +2377,8 @@ declare class ZendFiSessionKeyManager {
2105
2377
  *
2106
2378
  * const sessionKey = await manager.createSessionKey({
2107
2379
  * userWallet: '7xKNH....',
2380
+ * agentId: 'shopping-assistant-v1',
2381
+ * agentName: 'AI Shopping Assistant',
2108
2382
  * limitUSDC: 100,
2109
2383
  * durationDays: 7,
2110
2384
  * pin: '123456',
@@ -2112,21 +2386,27 @@ declare class ZendFiSessionKeyManager {
2112
2386
  * });
2113
2387
  *
2114
2388
  * console.log('Session key created:', sessionKey.sessionKeyId);
2389
+ * console.log('Works across all apps with agent:', sessionKey.agentId);
2115
2390
  * console.log('Recovery QR:', sessionKey.recoveryQR);
2116
2391
  * ```
2117
2392
  */
2118
2393
  createSessionKey(options: {
2119
2394
  userWallet: string;
2395
+ agentId: string;
2396
+ agentName?: string;
2120
2397
  limitUSDC: number;
2121
2398
  durationDays: number;
2122
2399
  pin: string;
2123
2400
  generateRecoveryQR?: boolean;
2124
2401
  }): Promise<{
2125
2402
  sessionKeyId: string;
2403
+ agentId: string;
2404
+ agentName?: string;
2126
2405
  sessionWallet: string;
2127
2406
  expiresAt: string;
2128
2407
  recoveryQR?: string;
2129
2408
  limitUsdc: number;
2409
+ crossAppCompatible: boolean;
2130
2410
  }>;
2131
2411
  /**
2132
2412
  * Load an existing session key from backend
@@ -2360,4 +2640,988 @@ declare function requiresLitSigning(session: {
2360
2640
  declare function encodeTransactionForLit(transaction: Uint8Array | Buffer): string;
2361
2641
  declare function decodeSignatureFromLit(result: SignPaymentResult): Uint8Array | null;
2362
2642
 
2363
- export { AgentAPI, AgentAnalytics, AgentApiKey, AgentPaymentRequest, AgentPaymentResponse, AgentSession, ApiError, ApproveEscrowRequest, AuthenticationError, AutonomyAPI, AutonomyStatus, ConfigLoader, ConfirmPaymentIntentRequest, CreateAgentApiKeyRequest, CreateAgentSessionRequest, type CreateDeviceBoundSessionKeyRequest, type CreateDeviceBoundSessionKeyResponse, CreateEscrowRequest, CreateInstallmentPlanRequest, CreateInvoiceRequest, CreatePaymentIntentRequest, CreatePaymentLinkRequest, CreatePaymentRequest, CreateSessionKeyRequest, CreateSessionKeyResponse, CreateSubscriptionPlanRequest, CreateSubscriptionRequest, DeviceBoundSessionKey, type DeviceBoundSessionKeyOptions, DeviceFingerprintGenerator, DisputeEscrowRequest, ERROR_CODES, EnableAutonomyRequest, EnableAutonomyResponse, type EncryptedSessionKey, type ErrorInterceptor, Escrow, InstallmentPlan, InterceptorManager, type Interceptors, Invoice, ListPaymentsRequest, LitCryptoSigner, type LitCryptoSignerConfig, type LitNetwork, NetworkError, PPPFactor, PaginatedResponse, Payment, PaymentError, PaymentIntent, PaymentIntentEvent, PaymentIntentsAPI, PaymentLink, PricingAPI, PricingSuggestion, PricingSuggestionRequest, RateLimitError, RateLimiter, type RecoveryQR, RecoveryQRGenerator, RefundEscrowRequest, type RequestConfig, type RequestInterceptor, type ResponseData, type ResponseInterceptor, SPENDING_LIMIT_ACTION_CID, SessionKeyCrypto, SessionKeyListResponse, type SessionKeyPaymentRequest, SessionKeyStatus, SessionKeysAPI, type SignPaymentParams, type SignPaymentResult, SmartPaymentRequest, SmartPaymentResponse, SmartPaymentsAPI, SubmitSignedTransactionRequest, SubmitTransactionResponse, Subscription, SubscriptionPlan, TopUpSessionKeyRequest, TopUpSessionKeyResponse, ValidationError, VerifyWebhookRequest, WebhookError, WebhookPayload, ZendFiClient, ZendFiConfig, ZendFiError, type ZendFiErrorData, type ZendFiErrorType, ZendFiSessionKeyManager, createZendFiError, decodeSignatureFromLit, encodeTransactionForLit, generateIdempotencyKey, isZendFiError, requiresLitSigning, sleep, verifyExpressWebhook, verifyNextWebhook, verifyWebhookSignature, zendfi };
2643
+ /**
2644
+ * Session Key Cache Manager
2645
+ * Optional caching utility for session key keypairs
2646
+ *
2647
+ * @example
2648
+ * ```typescript
2649
+ * import { SessionKeyCache } from '@zendfi/sdk/helpers';
2650
+ *
2651
+ * const cache = new SessionKeyCache({
2652
+ * storage: 'localStorage',
2653
+ * ttl: 3600000, // 1 hour
2654
+ * autoRefresh: true,
2655
+ * });
2656
+ *
2657
+ * // Get cached or decrypt
2658
+ * const keypair = await cache.getCached(sessionKeyId, async () => {
2659
+ * return await SessionKeyCrypto.decrypt(encrypted, pin, fingerprint);
2660
+ * });
2661
+ *
2662
+ * // Invalidate on logout
2663
+ * await cache.clear();
2664
+ * ```
2665
+ */
2666
+ interface CachedKeypair {
2667
+ keypair: any;
2668
+ expiry: number;
2669
+ sessionKeyId: string;
2670
+ deviceFingerprint?: string;
2671
+ }
2672
+ interface SessionKeyCacheConfig {
2673
+ /** Storage backend */
2674
+ storage?: 'memory' | 'localStorage' | 'indexedDB' | CustomStorageAdapter;
2675
+ /** Time-to-live in milliseconds (default: 30 minutes) */
2676
+ ttl?: number;
2677
+ /** Auto-refresh before expiry (default: false) */
2678
+ autoRefresh?: boolean;
2679
+ /** Namespace for storage keys (default: 'zendfi_cache') */
2680
+ namespace?: string;
2681
+ /** Enable debug logging (default: false) */
2682
+ debug?: boolean;
2683
+ }
2684
+ interface CustomStorageAdapter {
2685
+ get(key: string): Promise<string | null>;
2686
+ set(key: string, value: string): Promise<void>;
2687
+ remove(key: string): Promise<void>;
2688
+ clear(): Promise<void>;
2689
+ }
2690
+ /**
2691
+ * Session Key Cache Manager
2692
+ * Provides flexible caching with multiple storage backends
2693
+ */
2694
+ declare class SessionKeyCache {
2695
+ private memoryCache;
2696
+ private config;
2697
+ private refreshTimers;
2698
+ constructor(config?: SessionKeyCacheConfig);
2699
+ /**
2700
+ * Get cached keypair or decrypt and cache
2701
+ */
2702
+ getCached(sessionKeyId: string, decryptFn: () => Promise<any>, options?: {
2703
+ deviceFingerprint?: string;
2704
+ }): Promise<any>;
2705
+ /**
2706
+ * Decrypt keypair and cache it
2707
+ */
2708
+ private decryptAndCache;
2709
+ /**
2710
+ * Invalidate cached keypair
2711
+ */
2712
+ invalidate(sessionKeyId: string): Promise<void>;
2713
+ /**
2714
+ * Clear all cached keypairs
2715
+ */
2716
+ clear(): Promise<void>;
2717
+ /**
2718
+ * Get cache statistics
2719
+ */
2720
+ getStats(): {
2721
+ size: number;
2722
+ entries: Array<{
2723
+ sessionKeyId: string;
2724
+ expiresIn: number;
2725
+ }>;
2726
+ };
2727
+ /**
2728
+ * Check if a session key is cached and valid
2729
+ */
2730
+ isCached(sessionKeyId: string): boolean;
2731
+ /**
2732
+ * Update TTL for a cached session key
2733
+ */
2734
+ extendTTL(sessionKeyId: string, additionalMs: number): Promise<boolean>;
2735
+ private getFromStorage;
2736
+ private setInStorage;
2737
+ private removeFromStorage;
2738
+ private clearStorage;
2739
+ private getFromIndexedDB;
2740
+ private setInIndexedDB;
2741
+ private removeFromIndexedDB;
2742
+ private clearIndexedDB;
2743
+ private serializeKeypair;
2744
+ private deserializeKeypair;
2745
+ private setupAutoRefresh;
2746
+ private getStorageKey;
2747
+ private log;
2748
+ }
2749
+ /**
2750
+ * Pre-configured cache instances for common use cases
2751
+ */
2752
+ declare const QuickCaches: {
2753
+ /** Memory-only cache (30 minutes) */
2754
+ memory: () => SessionKeyCache;
2755
+ /** Persistent cache (1 hour, survives reload) */
2756
+ persistent: () => SessionKeyCache;
2757
+ /** Long-term cache (24 hours, IndexedDB) */
2758
+ longTerm: () => SessionKeyCache;
2759
+ /** Secure cache (5 minutes, memory-only) */
2760
+ secure: () => SessionKeyCache;
2761
+ };
2762
+
2763
+ /**
2764
+ * AI Intent Parser & Adapters
2765
+ * Parse natural language into payment intents
2766
+ *
2767
+ * @example
2768
+ * ```typescript
2769
+ * import { PaymentIntentParser, GeminiAdapter } from '@zendfi/sdk/helpers';
2770
+ *
2771
+ * // Parse AI response
2772
+ * const intent = PaymentIntentParser.parse(aiResponse);
2773
+ * if (intent?.action === 'payment') {
2774
+ * await zendfi.smartPayments.execute({
2775
+ * amount_usd: intent.amount,
2776
+ * description: intent.description,
2777
+ * });
2778
+ * }
2779
+ *
2780
+ * // Or use adapters
2781
+ * const gemini = new GeminiAdapter(apiKey);
2782
+ * const { text, intent } = await gemini.chat('Buy coffee for $5');
2783
+ * ```
2784
+ */
2785
+ interface ParsedIntent {
2786
+ action: 'payment' | 'create_session' | 'check_balance' | 'check_status' | 'topup' | 'revoke' | 'enable_autonomy' | 'chat_only';
2787
+ amount?: number;
2788
+ description?: string;
2789
+ confidence: number;
2790
+ rawText: string;
2791
+ metadata?: Record<string, any>;
2792
+ }
2793
+ interface AICapabilities {
2794
+ createPayment?: boolean;
2795
+ createSessionKey?: boolean;
2796
+ checkBalance?: boolean;
2797
+ checkStatus?: boolean;
2798
+ topUpSession?: boolean;
2799
+ revokeSession?: boolean;
2800
+ enableAutonomy?: boolean;
2801
+ }
2802
+ /**
2803
+ * Payment Intent Parser
2804
+ * Extract payment information from natural language
2805
+ */
2806
+ declare class PaymentIntentParser {
2807
+ /**
2808
+ * Parse natural language into structured intent
2809
+ */
2810
+ static parse(text: string): ParsedIntent | null;
2811
+ /**
2812
+ * Generate system prompt for AI models
2813
+ */
2814
+ static generateSystemPrompt(capabilities?: AICapabilities): string;
2815
+ private static containsPaymentKeywords;
2816
+ private static containsSessionKeywords;
2817
+ private static containsStatusKeywords;
2818
+ private static containsTopUpKeywords;
2819
+ private static containsRevokeKeywords;
2820
+ private static containsAutonomyKeywords;
2821
+ private static extractAmount;
2822
+ private static extractDescription;
2823
+ }
2824
+ interface AIResponse {
2825
+ text: string;
2826
+ intent: ParsedIntent | null;
2827
+ raw?: any;
2828
+ }
2829
+ /**
2830
+ * OpenAI GPT Adapter
2831
+ */
2832
+ declare class OpenAIAdapter {
2833
+ private apiKey;
2834
+ private model;
2835
+ private capabilities?;
2836
+ constructor(apiKey: string, model?: string, capabilities?: AICapabilities | undefined);
2837
+ chat(message: string, conversationHistory?: Array<{
2838
+ role: string;
2839
+ content: string;
2840
+ }>): Promise<AIResponse>;
2841
+ }
2842
+ /**
2843
+ * Anthropic Claude Adapter
2844
+ */
2845
+ declare class AnthropicAdapter {
2846
+ private apiKey;
2847
+ private model;
2848
+ private capabilities?;
2849
+ constructor(apiKey: string, model?: string, capabilities?: AICapabilities | undefined);
2850
+ chat(message: string, conversationHistory?: Array<{
2851
+ role: string;
2852
+ content: string;
2853
+ }>): Promise<AIResponse>;
2854
+ }
2855
+ /**
2856
+ * Google Gemini Adapter
2857
+ */
2858
+ declare class GeminiAdapter {
2859
+ private apiKey;
2860
+ private model;
2861
+ private capabilities?;
2862
+ constructor(apiKey: string, model?: string, capabilities?: AICapabilities | undefined);
2863
+ chat(message: string): Promise<AIResponse>;
2864
+ }
2865
+
2866
+ /**
2867
+ * Wallet Connector
2868
+ * Simplifies integration with Solana wallets (Phantom, Solflare, Backpack, etc.)
2869
+ *
2870
+ * @example
2871
+ * ```typescript
2872
+ * import { WalletConnector } from '@zendfi/sdk/helpers';
2873
+ *
2874
+ * // Auto-detect and connect
2875
+ * const wallet = await WalletConnector.detectAndConnect();
2876
+ * console.log(`Connected: ${wallet.address}`);
2877
+ * console.log(`Provider: ${wallet.provider}`);
2878
+ *
2879
+ * // Sign transaction
2880
+ * const result = await wallet.signTransaction(transaction);
2881
+ *
2882
+ * // Disconnect
2883
+ * await wallet.disconnect();
2884
+ * ```
2885
+ */
2886
+ interface ConnectedWallet {
2887
+ address: string;
2888
+ provider: 'phantom' | 'solflare' | 'backpack' | 'coinbase' | 'trust' | 'unknown';
2889
+ publicKey: any;
2890
+ signTransaction: (tx: any) => Promise<any>;
2891
+ signAllTransactions: (txs: any[]) => Promise<any[]>;
2892
+ signMessage: (message: Uint8Array) => Promise<{
2893
+ signature: Uint8Array;
2894
+ }>;
2895
+ disconnect: () => Promise<void>;
2896
+ isConnected: () => boolean;
2897
+ raw: any;
2898
+ }
2899
+ interface WalletConnectorConfig {
2900
+ /** Preferred wallet provider (if multiple detected) */
2901
+ preferredProvider?: 'phantom' | 'solflare' | 'backpack' | 'coinbase' | 'trust';
2902
+ /** Auto-connect on page load if previously connected */
2903
+ autoConnect?: boolean;
2904
+ /** Show connection UI if no wallet detected */
2905
+ showInstallPrompt?: boolean;
2906
+ /** Network (mainnet-beta, devnet, testnet) */
2907
+ network?: string;
2908
+ }
2909
+ /**
2910
+ * Wallet Connector
2911
+ * Detects and connects to Solana wallets
2912
+ */
2913
+ declare class WalletConnector {
2914
+ private static connectedWallet;
2915
+ /**
2916
+ * Detect and connect to a Solana wallet
2917
+ */
2918
+ static detectAndConnect(config?: WalletConnectorConfig): Promise<ConnectedWallet>;
2919
+ /**
2920
+ * Detect available Solana wallets
2921
+ */
2922
+ static detectWallets(): Array<'phantom' | 'solflare' | 'backpack' | 'coinbase' | 'trust'>;
2923
+ /**
2924
+ * Connect to a specific wallet provider
2925
+ */
2926
+ static connectToProvider(provider: 'phantom' | 'solflare' | 'backpack' | 'coinbase' | 'trust'): Promise<ConnectedWallet>;
2927
+ /**
2928
+ * Sign and submit a transaction
2929
+ */
2930
+ static signAndSubmit(transaction: any, wallet: ConnectedWallet, connection: any): Promise<{
2931
+ signature: string;
2932
+ }>;
2933
+ /**
2934
+ * Get current connected wallet
2935
+ */
2936
+ static getConnectedWallet(): ConnectedWallet | null;
2937
+ /**
2938
+ * Disconnect current wallet
2939
+ */
2940
+ static disconnect(): Promise<void>;
2941
+ /**
2942
+ * Listen for wallet connection changes
2943
+ */
2944
+ static onAccountChange(callback: (publicKey: any) => void): () => void;
2945
+ /**
2946
+ * Listen for wallet disconnection
2947
+ */
2948
+ static onDisconnect(callback: () => void): () => void;
2949
+ /**
2950
+ * Show install prompt UI
2951
+ */
2952
+ private static showInstallPrompt;
2953
+ /**
2954
+ * Check if wallet is installed
2955
+ */
2956
+ static isWalletInstalled(provider: 'phantom' | 'solflare' | 'backpack' | 'coinbase' | 'trust'): boolean;
2957
+ /**
2958
+ * Get wallet download URL
2959
+ */
2960
+ static getWalletUrl(provider: 'phantom' | 'solflare' | 'backpack' | 'coinbase' | 'trust'): string;
2961
+ }
2962
+ /**
2963
+ * React Hook for Wallet Connection (optional)
2964
+ * Export as separate module to avoid forcing React dependency
2965
+ */
2966
+ declare function createWalletHook(): () => {
2967
+ wallet: any;
2968
+ connecting: any;
2969
+ error: any;
2970
+ connect: (config?: WalletConnectorConfig) => Promise<void>;
2971
+ disconnect: () => Promise<void>;
2972
+ isConnected: boolean;
2973
+ };
2974
+
2975
+ /**
2976
+ * Security Utilities
2977
+ * PIN validation, rate limiting, and security best practices
2978
+ *
2979
+ * @example
2980
+ * ```typescript
2981
+ * import { PINValidator, PINRateLimiter } from '@zendfi/sdk/helpers';
2982
+ *
2983
+ * // Validate PIN
2984
+ * const validation = PINValidator.validate(pin);
2985
+ * if (!validation.valid) {
2986
+ * console.error(validation.errors);
2987
+ * }
2988
+ *
2989
+ * // Rate limit PIN attempts
2990
+ * const limiter = new PINRateLimiter();
2991
+ * const attempt = await limiter.checkAttempt(sessionKeyId);
2992
+ * if (!attempt.allowed) {
2993
+ * console.log(`Locked out for ${attempt.lockoutSeconds}s`);
2994
+ * }
2995
+ * ```
2996
+ */
2997
+ interface PINValidationResult {
2998
+ valid: boolean;
2999
+ strength: 'weak' | 'medium' | 'strong';
3000
+ errors: string[];
3001
+ suggestions: string[];
3002
+ }
3003
+ /**
3004
+ * PIN Validator
3005
+ * Validates PIN security and strength
3006
+ */
3007
+ declare class PINValidator {
3008
+ /**
3009
+ * Validate PIN strength and format
3010
+ */
3011
+ static validate(pin: string): PINValidationResult;
3012
+ /**
3013
+ * Check PIN strength (0-100 score)
3014
+ */
3015
+ static strengthScore(pin: string): number;
3016
+ /**
3017
+ * Generate a secure random PIN
3018
+ */
3019
+ static generateSecureRandom(length?: number): string;
3020
+ /**
3021
+ * Check for weak patterns
3022
+ */
3023
+ private static isWeakPattern;
3024
+ /**
3025
+ * Check if PIN is sequential
3026
+ */
3027
+ private static isSequential;
3028
+ /**
3029
+ * Check if PIN has repeated digits
3030
+ */
3031
+ private static hasRepeatedDigits;
3032
+ /**
3033
+ * Hash PIN for storage (if needed)
3034
+ * Note: For device-bound keys, the PIN is used for key derivation, not storage
3035
+ */
3036
+ static hashPIN(pin: string, salt?: string): Promise<string>;
3037
+ }
3038
+ /**
3039
+ * PIN Rate Limiter
3040
+ * Prevents brute-force attacks on PIN entry
3041
+ */
3042
+ declare class PINRateLimiter {
3043
+ private attempts;
3044
+ private locked;
3045
+ private maxAttempts;
3046
+ private windowMs;
3047
+ private lockoutMs;
3048
+ constructor(config?: {
3049
+ maxAttempts?: number;
3050
+ windowMs?: number;
3051
+ lockoutMs?: number;
3052
+ });
3053
+ /**
3054
+ * Check if attempt is allowed
3055
+ */
3056
+ checkAttempt(sessionKeyId: string): Promise<{
3057
+ allowed: boolean;
3058
+ remainingAttempts: number;
3059
+ lockoutSeconds?: number;
3060
+ }>;
3061
+ /**
3062
+ * Record a failed attempt
3063
+ */
3064
+ recordFailedAttempt(sessionKeyId: string): void;
3065
+ /**
3066
+ * Record a successful attempt (clears history)
3067
+ */
3068
+ recordSuccessfulAttempt(sessionKeyId: string): void;
3069
+ /**
3070
+ * Get recent attempts within window
3071
+ */
3072
+ private getRecentAttempts;
3073
+ /**
3074
+ * Clear all rate limit data
3075
+ */
3076
+ clear(): void;
3077
+ /**
3078
+ * Check lockout status
3079
+ */
3080
+ isLockedOut(sessionKeyId: string): boolean;
3081
+ /**
3082
+ * Get remaining lockout time
3083
+ */
3084
+ getRemainingLockoutTime(sessionKeyId: string): number;
3085
+ }
3086
+ /**
3087
+ * Secure Storage Helper
3088
+ * Utilities for secure data storage
3089
+ */
3090
+ declare class SecureStorage {
3091
+ /**
3092
+ * Store data with encryption (basic)
3093
+ * For production, consider using Web Crypto API with user-derived keys
3094
+ */
3095
+ static setEncrypted(key: string, value: string, secret: string): Promise<void>;
3096
+ /**
3097
+ * Retrieve encrypted data
3098
+ */
3099
+ static getEncrypted(key: string, secret: string): Promise<string | null>;
3100
+ /**
3101
+ * Encrypt string with AES-GCM
3102
+ */
3103
+ private static encrypt;
3104
+ /**
3105
+ * Decrypt AES-GCM ciphertext
3106
+ */
3107
+ private static decrypt;
3108
+ /**
3109
+ * Derive encryption key from secret
3110
+ */
3111
+ private static deriveKey;
3112
+ /**
3113
+ * Clear all secure storage
3114
+ */
3115
+ static clearAll(namespace?: string): void;
3116
+ }
3117
+
3118
+ /**
3119
+ * Transaction Polling Utilities
3120
+ * Poll Solana transactions with exponential backoff
3121
+ *
3122
+ * @example
3123
+ * ```typescript
3124
+ * import { TransactionPoller } from '@zendfi/sdk/helpers';
3125
+ *
3126
+ * // Wait for confirmation
3127
+ * const status = await TransactionPoller.waitForConfirmation(
3128
+ * signature,
3129
+ * { timeout: 60000, interval: 2000 }
3130
+ * );
3131
+ *
3132
+ * if (status.confirmed) {
3133
+ * console.log(`Confirmed in slot ${status.slot}`);
3134
+ * }
3135
+ * ```
3136
+ */
3137
+ interface TransactionStatus {
3138
+ confirmed: boolean;
3139
+ signature: string;
3140
+ slot?: number;
3141
+ blockTime?: number;
3142
+ confirmations?: number;
3143
+ error?: string;
3144
+ }
3145
+ interface PollingOptions {
3146
+ /** Maximum time to wait in ms (default: 60000 = 1 minute) */
3147
+ timeout?: number;
3148
+ /** Initial polling interval in ms (default: 2000 = 2 seconds) */
3149
+ interval?: number;
3150
+ /** Maximum polling interval in ms (default: 10000 = 10 seconds) */
3151
+ maxInterval?: number;
3152
+ /** Maximum number of attempts (default: 30) */
3153
+ maxAttempts?: number;
3154
+ /** Commitment level (default: 'confirmed') */
3155
+ commitment?: 'processed' | 'confirmed' | 'finalized';
3156
+ /** RPC endpoint (optional, uses default if not provided) */
3157
+ rpcUrl?: string;
3158
+ }
3159
+ /**
3160
+ * Transaction Poller
3161
+ * Poll transaction status with smart backoff
3162
+ */
3163
+ declare class TransactionPoller {
3164
+ /**
3165
+ * Wait for transaction confirmation
3166
+ */
3167
+ static waitForConfirmation(signature: string, options?: PollingOptions): Promise<TransactionStatus>;
3168
+ /**
3169
+ * Check transaction status via RPC
3170
+ */
3171
+ private static checkTransactionStatus;
3172
+ /**
3173
+ * Check if commitment level is reached
3174
+ */
3175
+ private static isCommitmentReached;
3176
+ /**
3177
+ * Get default RPC URL based on environment
3178
+ */
3179
+ private static getDefaultRpcUrl;
3180
+ /**
3181
+ * Poll multiple transactions in parallel
3182
+ */
3183
+ static waitForMultiple(signatures: string[], options?: PollingOptions): Promise<TransactionStatus[]>;
3184
+ /**
3185
+ * Get transaction details after confirmation
3186
+ */
3187
+ static getTransactionDetails(signature: string, rpcUrl?: string): Promise<any>;
3188
+ /**
3189
+ * Check if transaction exists on chain
3190
+ */
3191
+ static exists(signature: string, rpcUrl?: string): Promise<boolean>;
3192
+ /**
3193
+ * Get recent blockhash (useful for transaction building)
3194
+ */
3195
+ static getRecentBlockhash(rpcUrl?: string): Promise<{
3196
+ blockhash: string;
3197
+ lastValidBlockHeight: number;
3198
+ }>;
3199
+ /**
3200
+ * Sleep utility
3201
+ */
3202
+ private static sleep;
3203
+ }
3204
+ /**
3205
+ * Transaction Monitor
3206
+ * Monitor transaction status with callbacks
3207
+ */
3208
+ declare class TransactionMonitor {
3209
+ private monitors;
3210
+ /**
3211
+ * Start monitoring a transaction
3212
+ */
3213
+ monitor(signature: string, callbacks: {
3214
+ onConfirmed?: (status: TransactionStatus) => void;
3215
+ onFailed?: (status: TransactionStatus) => void;
3216
+ onTimeout?: () => void;
3217
+ }, options?: PollingOptions): void;
3218
+ /**
3219
+ * Stop monitoring a transaction
3220
+ */
3221
+ stopMonitoring(signature: string): void;
3222
+ /**
3223
+ * Stop all monitors
3224
+ */
3225
+ stopAll(): void;
3226
+ /**
3227
+ * Get active monitors
3228
+ */
3229
+ getActiveMonitors(): string[];
3230
+ }
3231
+
3232
+ /**
3233
+ * Retry Strategy & Error Recovery
3234
+ * Smart retry logic with exponential backoff
3235
+ *
3236
+ * @example
3237
+ * ```typescript
3238
+ * import { RetryStrategy, ErrorRecovery } from '@zendfi/sdk/helpers';
3239
+ *
3240
+ * // Retry with exponential backoff
3241
+ * const result = await RetryStrategy.withRetry(
3242
+ * () => zendfi.smartPayments.execute({ amount_usd: 50 }),
3243
+ * { maxAttempts: 3, backoffMs: 1000 }
3244
+ * );
3245
+ *
3246
+ * // Auto-recover from common errors
3247
+ * const payment = await ErrorRecovery.recoverFromNetworkError(
3248
+ * () => createPayment()
3249
+ * );
3250
+ * ```
3251
+ */
3252
+ interface RetryOptions {
3253
+ /** Maximum number of retry attempts (default: 3) */
3254
+ maxAttempts?: number;
3255
+ /** Initial backoff delay in ms (default: 1000) */
3256
+ backoffMs?: number;
3257
+ /** Backoff multiplier (default: 2 for exponential) */
3258
+ backoffMultiplier?: number;
3259
+ /** Maximum backoff delay in ms (default: 30000) */
3260
+ maxBackoffMs?: number;
3261
+ /** Function to determine if error is retryable (default: all errors) */
3262
+ shouldRetry?: (error: Error, attempt: number) => boolean;
3263
+ /** Callback on each retry */
3264
+ onRetry?: (error: Error, attempt: number, nextDelayMs: number) => void;
3265
+ }
3266
+ /**
3267
+ * Retry Strategy
3268
+ * Implements smart retry logic with exponential backoff
3269
+ */
3270
+ declare class RetryStrategy {
3271
+ /**
3272
+ * Execute function with retry logic
3273
+ */
3274
+ static withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
3275
+ /**
3276
+ * Retry with linear backoff
3277
+ */
3278
+ static withLinearRetry<T>(fn: () => Promise<T>, maxAttempts?: number, delayMs?: number): Promise<T>;
3279
+ /**
3280
+ * Retry with custom backoff function
3281
+ */
3282
+ static withCustomBackoff<T>(fn: () => Promise<T>, backoffFn: (attempt: number) => number, maxAttempts?: number): Promise<T>;
3283
+ /**
3284
+ * Check if error is retryable
3285
+ */
3286
+ static isRetryableError(error: any): boolean;
3287
+ private static sleep;
3288
+ }
3289
+ /**
3290
+ * Error Recovery
3291
+ * Auto-recovery strategies for common failure scenarios
3292
+ */
3293
+ declare class ErrorRecovery {
3294
+ /**
3295
+ * Recover from network errors with retry
3296
+ */
3297
+ static recoverFromNetworkError<T>(fn: () => Promise<T>, maxAttempts?: number): Promise<T>;
3298
+ /**
3299
+ * Recover from rate limit errors with exponential backoff
3300
+ */
3301
+ static recoverFromRateLimit<T>(fn: () => Promise<T>, maxAttempts?: number): Promise<T>;
3302
+ /**
3303
+ * Recover from Solana RPC errors (blockhash, etc.)
3304
+ */
3305
+ static recoverFromRPCError<T>(fn: () => Promise<T>, maxAttempts?: number): Promise<T>;
3306
+ /**
3307
+ * Recover from timeout errors
3308
+ */
3309
+ static recoverFromTimeout<T>(fn: () => Promise<T>, timeoutMs?: number, maxAttempts?: number): Promise<T>;
3310
+ /**
3311
+ * Add timeout to async function
3312
+ */
3313
+ private static withTimeout;
3314
+ /**
3315
+ * Circuit breaker pattern for repeated failures
3316
+ */
3317
+ static createCircuitBreaker<T>(fn: () => Promise<T>, options?: {
3318
+ failureThreshold?: number;
3319
+ resetTimeoutMs?: number;
3320
+ onStateChange?: (state: 'closed' | 'open' | 'half-open') => void;
3321
+ }): () => Promise<T>;
3322
+ /**
3323
+ * Fallback to alternative function on error
3324
+ */
3325
+ static withFallback<T>(primaryFn: () => Promise<T>, fallbackFn: () => Promise<T>, shouldFallback?: (error: Error) => boolean): Promise<T>;
3326
+ /**
3327
+ * Graceful degradation - return partial result on error
3328
+ */
3329
+ static withGracefulDegradation<T>(fn: () => Promise<T>, defaultValue: T, onError?: (error: Error) => void): Promise<T>;
3330
+ }
3331
+
3332
+ /**
3333
+ * Session Key Lifecycle Manager
3334
+ * High-level wrapper for device-bound session keys
3335
+ * Handles common patterns: create → cache → use → revoke
3336
+ *
3337
+ * @example
3338
+ * ```typescript
3339
+ * import { SessionKeyLifecycle } from '@zendfi/sdk/helpers';
3340
+ *
3341
+ * const lifecycle = new SessionKeyLifecycle(zendfi, {
3342
+ * cache: QuickCaches.persistent(),
3343
+ * pinProvider: () => promptUserForPIN(),
3344
+ * });
3345
+ *
3346
+ * // Create and fund in one call
3347
+ * await lifecycle.createAndFund({
3348
+ * userWallet: address,
3349
+ * agentId: 'my-agent',
3350
+ * limitUsdc: 100,
3351
+ * });
3352
+ *
3353
+ * // Make payments (auto-handles caching/PIN)
3354
+ * await lifecycle.pay(5, 'Coffee');
3355
+ *
3356
+ * // Cleanup on app close
3357
+ * await lifecycle.cleanup();
3358
+ * ```
3359
+ */
3360
+
3361
+ interface LifecycleConfig {
3362
+ /** Optional cache instance */
3363
+ cache?: SessionKeyCache;
3364
+ /** PIN provider function (called when cache expires) */
3365
+ pinProvider?: () => Promise<string>;
3366
+ /** Device fingerprint generator */
3367
+ deviceFingerprintProvider?: () => Promise<string>;
3368
+ /** Auto-cleanup on window/tab close */
3369
+ autoCleanup?: boolean;
3370
+ }
3371
+ interface CreateAndFundConfig {
3372
+ userWallet: string;
3373
+ agentId: string;
3374
+ agentName?: string;
3375
+ limitUsdc: number;
3376
+ durationDays?: number;
3377
+ onApprovalNeeded?: (transaction: string) => Promise<string>;
3378
+ }
3379
+ interface PaymentResult {
3380
+ paymentId: string;
3381
+ status: string;
3382
+ signature?: string;
3383
+ confirmedInMs?: number;
3384
+ }
3385
+ /**
3386
+ * Session Key Lifecycle Manager
3387
+ * Simplifies device-bound session key management
3388
+ */
3389
+ declare class SessionKeyLifecycle {
3390
+ private client;
3391
+ private config;
3392
+ private sessionKeyId;
3393
+ private sessionWallet;
3394
+ private encryptedKey;
3395
+ private deviceFingerprint;
3396
+ constructor(client: ZendFiClient, config?: LifecycleConfig);
3397
+ /**
3398
+ * Create and fund session key in one call
3399
+ * Handles: keypair generation → encryption → backend registration → funding
3400
+ */
3401
+ createAndFund(config: CreateAndFundConfig): Promise<{
3402
+ sessionKeyId: string;
3403
+ sessionWallet: string;
3404
+ }>;
3405
+ /**
3406
+ * Make a payment using the session key
3407
+ * Auto-handles caching, PIN prompts, and signing
3408
+ */
3409
+ pay(amount: number, description: string): Promise<PaymentResult>;
3410
+ /**
3411
+ * Check session key status
3412
+ */
3413
+ getStatus(): Promise<SessionKeyStatus>;
3414
+ /**
3415
+ * Top up session key
3416
+ */
3417
+ topUp(amount: number, userWallet: string, onApprovalNeeded?: (tx: string) => Promise<void>): Promise<void>;
3418
+ /**
3419
+ * Revoke session key
3420
+ */
3421
+ revoke(): Promise<void>;
3422
+ /**
3423
+ * Cleanup (clear cache, reset state)
3424
+ */
3425
+ cleanup(): Promise<void>;
3426
+ /**
3427
+ * Get current session key ID
3428
+ */
3429
+ getSessionKeyId(): string | null;
3430
+ /**
3431
+ * Check if session is active
3432
+ */
3433
+ isActive(): boolean;
3434
+ private decryptKeypair;
3435
+ private generateDeviceFingerprint;
3436
+ private promptForPIN;
3437
+ private getSolanaWeb3;
3438
+ }
3439
+ /**
3440
+ * Quick setup function for common use case
3441
+ */
3442
+ declare function setupQuickSessionKey(client: ZendFiClient, config: {
3443
+ userWallet: string;
3444
+ agentId: string;
3445
+ budgetUsdc: number;
3446
+ onApproval: (tx: string) => Promise<string>;
3447
+ }): Promise<SessionKeyLifecycle>;
3448
+
3449
+ /**
3450
+ * Development Tools & Utilities
3451
+ * Debugging helpers for development and testing
3452
+ *
3453
+ * @example
3454
+ * ```typescript
3455
+ * import { DevTools } from '@zendfi/sdk/helpers';
3456
+ *
3457
+ * // Enable debug mode
3458
+ * DevTools.enableDebugMode();
3459
+ *
3460
+ * // Create test session key
3461
+ * const testKey = await DevTools.createTestSessionKey();
3462
+ *
3463
+ * // Mock wallet for testing
3464
+ * const mockWallet = DevTools.mockWallet();
3465
+ *
3466
+ * // Log transaction flow
3467
+ * DevTools.logTransactionFlow(paymentId);
3468
+ * ```
3469
+ */
3470
+ interface MockWallet {
3471
+ address: string;
3472
+ publicKey: any;
3473
+ signTransaction: (tx: any) => Promise<any>;
3474
+ signMessage: (msg: Uint8Array) => Promise<{
3475
+ signature: Uint8Array;
3476
+ }>;
3477
+ isConnected: () => boolean;
3478
+ disconnect: () => Promise<void>;
3479
+ }
3480
+ interface TestSessionKey {
3481
+ sessionKeyId: string;
3482
+ sessionWallet: string;
3483
+ privateKey: Uint8Array;
3484
+ budget: number;
3485
+ }
3486
+ /**
3487
+ * Development Tools
3488
+ * Utilities for debugging and testing
3489
+ */
3490
+ declare class DevTools {
3491
+ private static debugEnabled;
3492
+ private static requestLog;
3493
+ /**
3494
+ * Enable debug mode (logs all API requests/responses)
3495
+ */
3496
+ static enableDebugMode(): void;
3497
+ /**
3498
+ * Disable debug mode
3499
+ */
3500
+ static disableDebugMode(): void;
3501
+ /**
3502
+ * Check if debug mode is enabled
3503
+ */
3504
+ static isDebugEnabled(): boolean;
3505
+ /**
3506
+ * Log API request
3507
+ */
3508
+ static logRequest(method: string, url: string, body?: any): void;
3509
+ /**
3510
+ * Log API response
3511
+ */
3512
+ static logResponse(method: string, url: string, status: number, data: any, duration?: number): void;
3513
+ /**
3514
+ * Get request log
3515
+ */
3516
+ static getRequestLog(): Array<{
3517
+ timestamp: Date;
3518
+ method: string;
3519
+ url: string;
3520
+ status?: number;
3521
+ duration?: number;
3522
+ }>;
3523
+ /**
3524
+ * Clear request log
3525
+ */
3526
+ static clearRequestLog(): void;
3527
+ /**
3528
+ * Create a test session key (devnet only)
3529
+ */
3530
+ static createTestSessionKey(): Promise<TestSessionKey>;
3531
+ /**
3532
+ * Create a mock wallet for testing
3533
+ */
3534
+ static mockWallet(address?: string): MockWallet;
3535
+ /**
3536
+ * Log transaction flow (visual diagram in console)
3537
+ */
3538
+ static logTransactionFlow(paymentId: string): void;
3539
+ /**
3540
+ * Log session key lifecycle
3541
+ */
3542
+ static logSessionKeyLifecycle(sessionKeyId: string): void;
3543
+ /**
3544
+ * Benchmark API request
3545
+ */
3546
+ static benchmarkRequest<T>(name: string, fn: () => Promise<T>): Promise<{
3547
+ result: T;
3548
+ durationMs: number;
3549
+ }>;
3550
+ /**
3551
+ * Stress test (send multiple concurrent requests)
3552
+ */
3553
+ static stressTest<T>(name: string, fn: () => Promise<T>, concurrency?: number, iterations?: number): Promise<{
3554
+ totalRequests: number;
3555
+ successful: number;
3556
+ failed: number;
3557
+ avgDurationMs: number;
3558
+ minDurationMs: number;
3559
+ maxDurationMs: number;
3560
+ }>;
3561
+ /**
3562
+ * Inspect ZendFi SDK configuration
3563
+ */
3564
+ static inspectConfig(client: any): void;
3565
+ /**
3566
+ * Generate test data
3567
+ */
3568
+ static generateTestData(): {
3569
+ userWallet: string;
3570
+ agentId: string;
3571
+ sessionKeyId: string;
3572
+ paymentId: string;
3573
+ };
3574
+ /**
3575
+ * Check if running in development environment
3576
+ */
3577
+ private static isDevelopment;
3578
+ /**
3579
+ * Generate test Solana address
3580
+ */
3581
+ private static generateTestAddress;
3582
+ /**
3583
+ * Generate test ID with prefix
3584
+ */
3585
+ private static generateTestId;
3586
+ /**
3587
+ * Get Solana Web3.js
3588
+ */
3589
+ private static getSolanaWeb3;
3590
+ }
3591
+ /**
3592
+ * Performance Monitor
3593
+ * Track SDK performance metrics
3594
+ */
3595
+ declare class PerformanceMonitor {
3596
+ private metrics;
3597
+ /**
3598
+ * Record a metric
3599
+ */
3600
+ record(name: string, value: number): void;
3601
+ /**
3602
+ * Get statistics for a metric
3603
+ */
3604
+ getStats(name: string): {
3605
+ count: number;
3606
+ avg: number;
3607
+ min: number;
3608
+ max: number;
3609
+ p50: number;
3610
+ p95: number;
3611
+ p99: number;
3612
+ } | null;
3613
+ /**
3614
+ * Get all metrics
3615
+ */
3616
+ getAllStats(): Record<string, ReturnType<typeof this.getStats>>;
3617
+ /**
3618
+ * Print report
3619
+ */
3620
+ printReport(): void;
3621
+ /**
3622
+ * Clear all metrics
3623
+ */
3624
+ clear(): void;
3625
+ }
3626
+
3627
+ export { AgentAPI, AgentAnalytics, AgentApiKey, AgentPaymentRequest, AgentPaymentResponse, AgentSession, AnthropicAdapter, ApiError, ApiKeyMode, ApproveEscrowRequest, AuthenticationError, AutonomyAPI, AutonomyStatus, type CachedKeypair, type CheckoutError, type CheckoutTheme, ConfigLoader, ConfirmPaymentIntentRequest, type ConnectedWallet, CreateAgentApiKeyRequest, CreateAgentSessionRequest, type CreateAndFundConfig, type CreateDeviceBoundSessionKeyRequest, type CreateDeviceBoundSessionKeyResponse, CreateEscrowRequest, CreateInstallmentPlanRequest, CreateInvoiceRequest, CreatePaymentIntentRequest, CreatePaymentLinkRequest, CreatePaymentRequest, CreateSessionKeyRequest, CreateSessionKeyResponse, CreateSubscriptionPlanRequest, CreateSubscriptionRequest, type CustomStorageAdapter, DevTools, DeviceBoundSessionKey, type DeviceBoundSessionKeyOptions, DeviceFingerprintGenerator, DisputeEscrowRequest, ERROR_CODES, type EmbeddedCheckoutConfig, EnableAutonomyRequest, EnableAutonomyResponse, type EncryptedSessionKey, type ErrorInterceptor, ErrorRecovery, Escrow, GeminiAdapter, InstallmentPlan, InterceptorManager, type Interceptors, Invoice, type LifecycleConfig, ListPaymentsRequest, LitCryptoSigner, type LitCryptoSignerConfig, type LitNetwork, type MockWallet, NetworkError, OpenAIAdapter, PINRateLimiter, type PINValidationResult, PINValidator, PPPFactor, PaginatedResponse, type ParsedIntent, Payment, PaymentError, PaymentIntent, PaymentIntentEvent, PaymentIntentParser, PaymentIntentsAPI, PaymentLink, type PaymentResult, type PaymentSuccessData, PerformanceMonitor, type PollingOptions, PricingAPI, PricingSuggestion, PricingSuggestionRequest, QuickCaches, RateLimitError, RateLimiter, type RecoveryQR, RecoveryQRGenerator, RefundEscrowRequest, type RequestConfig, type RequestInterceptor, type ResponseData, type ResponseInterceptor, type RetryOptions, RetryStrategy, SPENDING_LIMIT_ACTION_CID, SecureStorage, SessionKeyCache, type SessionKeyCacheConfig, SessionKeyCrypto, SessionKeyLifecycle, SessionKeyListResponse, type SessionKeyPaymentRequest, SessionKeyStatus, SessionKeysAPI, type SignPaymentParams, type SignPaymentResult, SmartPaymentRequest, SmartPaymentResponse, SmartPaymentsAPI, SubmitSignedTransactionRequest, SubmitTransactionResponse, Subscription, SubscriptionPlan, type TestSessionKey, TopUpSessionKeyRequest, TopUpSessionKeyResponse, TransactionMonitor, TransactionPoller, type TransactionStatus, ValidationError, VerifyWebhookRequest, WalletConnector, WebhookError, WebhookPayload, ZendFiClient, ZendFiConfig, ZendFiEmbeddedCheckout, ZendFiError, type ZendFiErrorData, type ZendFiErrorType, ZendFiSessionKeyManager, createWalletHook, createZendFiError, decodeSignatureFromLit, encodeTransactionForLit, generateIdempotencyKey, isZendFiError, requiresLitSigning, setupQuickSessionKey, sleep, verifyExpressWebhook, verifyNextWebhook, verifyWebhookSignature, zendfi };