@zendfi/sdk 0.5.8 → 0.6.0

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-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.mjs';
-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.mjs';
+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-DGBeCWT-.mjs';
+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-DGBeCWT-.mjs';
 import { Transaction, Keypair } from '@solana/web3.js';
 
 /**
@@ -715,6 +715,68 @@ declare class AutonomyAPI {
      * ```
      */
     validateRequest(request: EnableAutonomyRequest): void;
+    /**
+     * Get spending attestations for a delegate (audit trail)
+     *
+     * Returns all cryptographically signed attestations ZendFi created for
+     * this delegate. Each attestation contains:
+     * - The spending state at the time of payment
+     * - ZendFi's Ed25519 signature
+     * - Timestamp and nonce (for replay protection)
+     *
+     * These attestations can be independently verified using ZendFi's public key
+     * to confirm spending limit enforcement was applied correctly.
+     *
+     * @param delegateId - UUID of the autonomous delegate
+     * @returns Attestation audit response with all signed attestations
+     *
+     * @example
+     * ```typescript
+     * const audit = await zendfi.autonomy.getAttestations('delegate_123...');
+     *
+     * console.log(`Found ${audit.attestation_count} attestations`);
+     * console.log(`ZendFi public key: ${audit.zendfi_attestation_public_key}`);
+     *
+     * // Verify each attestation independently
+     * for (const signed of audit.attestations) {
+     *   console.log(`Payment ${signed.attestation.payment_id}:`);
+     *   console.log(`  Requested: $${signed.attestation.requested_usd}`);
+     *   console.log(`  Remaining after: $${signed.attestation.remaining_after_usd}`);
+     *   // Verify signature with nacl.sign.detached.verify()
+     * }
+     * ```
+     */
+    getAttestations(delegateId: string): Promise<AttestationAuditResponse>;
+}
+/** Spending attestation - ZendFi's signed commitment to spending state */
+interface SpendingAttestation {
+    delegate_id: string;
+    session_key_id: string;
+    merchant_id: string;
+    spent_usd: number;
+    limit_usd: number;
+    requested_usd: number;
+    remaining_after_usd: number;
+    timestamp_ms: number;
+    nonce: string;
+    payment_id: string;
+    version: number;
+}
+/** Signed attestation with ZendFi's cryptographic signature */
+interface SignedSpendingAttestation {
+    attestation: SpendingAttestation;
+    /** Base64-encoded Ed25519 signature */
+    signature: string;
+    /** Base58-encoded ZendFi public key */
+    signer_public_key: string;
+}
+/** Response from the attestation audit endpoint */
+interface AttestationAuditResponse {
+    delegate_id: string;
+    attestation_count: number;
+    attestations: SignedSpendingAttestation[];
+    /** ZendFi's attestation public key for independent verification */
+    zendfi_attestation_public_key: string | null;
 }
 
 /**
@@ -2058,6 +2120,8 @@ declare class DeviceBoundSessionKey {
 
 interface CreateDeviceBoundSessionKeyRequest {
     userWallet: string;
+    agentId: string;
+    agentName?: string;
     limitUsdc: number;
     durationDays: number;
     encryptedSessionKey: string;
@@ -2071,10 +2135,13 @@ interface CreateDeviceBoundSessionKeyResponse {
     mode: 'device_bound';
     isCustodial: false;
     userWallet: string;
+    agentId: string;
+    agentName?: string;
     sessionWallet: string;
     limitUsdc: number;
     expiresAt: string;
     requiresClientSigning: true;
+    crossAppCompatible: boolean;
     securityInfo: {
         encryptionType: string;
         deviceBound: boolean;
@@ -2105,6 +2172,8 @@ declare class ZendFiSessionKeyManager {
      *
      * const sessionKey = await manager.createSessionKey({
      *   userWallet: '7xKNH....',
+     *   agentId: 'shopping-assistant-v1',
+     *   agentName: 'AI Shopping Assistant',
      *   limitUSDC: 100,
      *   durationDays: 7,
      *   pin: '123456',
@@ -2112,21 +2181,27 @@ declare class ZendFiSessionKeyManager {
      * });
      *
      * console.log('Session key created:', sessionKey.sessionKeyId);
+     * console.log('Works across all apps with agent:', sessionKey.agentId);
      * console.log('Recovery QR:', sessionKey.recoveryQR);
      * ```
      */
     createSessionKey(options: {
         userWallet: string;
+        agentId: string;
+        agentName?: string;
         limitUSDC: number;
         durationDays: number;
         pin: string;
         generateRecoveryQR?: boolean;
     }): Promise<{
         sessionKeyId: string;
+        agentId: string;
+        agentName?: string;
         sessionWallet: string;
         expiresAt: string;
         recoveryQR?: string;
         limitUsdc: number;
+        crossAppCompatible: boolean;
     }>;
     /**
      * Load an existing session key from backend
@@ -2360,4 +2435,988 @@ declare function requiresLitSigning(session: {
 declare function encodeTransactionForLit(transaction: Uint8Array | Buffer): string;
 declare function decodeSignatureFromLit(result: SignPaymentResult): Uint8Array | null;
 
-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 };
+/**
+ * Session Key Cache Manager
+ * Optional caching utility for session key keypairs
+ *
+ * @example
+ * ```typescript
+ * import { SessionKeyCache } from '@zendfi/sdk/helpers';
+ *
+ * const cache = new SessionKeyCache({
+ *   storage: 'localStorage',
+ *   ttl: 3600000, // 1 hour
+ *   autoRefresh: true,
+ * });
+ *
+ * // Get cached or decrypt
+ * const keypair = await cache.getCached(sessionKeyId, async () => {
+ *   return await SessionKeyCrypto.decrypt(encrypted, pin, fingerprint);
+ * });
+ *
+ * // Invalidate on logout
+ * await cache.clear();
+ * ```
+ */
+interface CachedKeypair {
+    keypair: any;
+    expiry: number;
+    sessionKeyId: string;
+    deviceFingerprint?: string;
+}
+interface SessionKeyCacheConfig {
+    /** Storage backend */
+    storage?: 'memory' | 'localStorage' | 'indexedDB' | CustomStorageAdapter;
+    /** Time-to-live in milliseconds (default: 30 minutes) */
+    ttl?: number;
+    /** Auto-refresh before expiry (default: false) */
+    autoRefresh?: boolean;
+    /** Namespace for storage keys (default: 'zendfi_cache') */
+    namespace?: string;
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+}
+interface CustomStorageAdapter {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    remove(key: string): Promise<void>;
+    clear(): Promise<void>;
+}
+/**
+ * Session Key Cache Manager
+ * Provides flexible caching with multiple storage backends
+ */
+declare class SessionKeyCache {
+    private memoryCache;
+    private config;
+    private refreshTimers;
+    constructor(config?: SessionKeyCacheConfig);
+    /**
+     * Get cached keypair or decrypt and cache
+     */
+    getCached(sessionKeyId: string, decryptFn: () => Promise<any>, options?: {
+        deviceFingerprint?: string;
+    }): Promise<any>;
+    /**
+     * Decrypt keypair and cache it
+     */
+    private decryptAndCache;
+    /**
+     * Invalidate cached keypair
+     */
+    invalidate(sessionKeyId: string): Promise<void>;
+    /**
+     * Clear all cached keypairs
+     */
+    clear(): Promise<void>;
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        size: number;
+        entries: Array<{
+            sessionKeyId: string;
+            expiresIn: number;
+        }>;
+    };
+    /**
+     * Check if a session key is cached and valid
+     */
+    isCached(sessionKeyId: string): boolean;
+    /**
+     * Update TTL for a cached session key
+     */
+    extendTTL(sessionKeyId: string, additionalMs: number): Promise<boolean>;
+    private getFromStorage;
+    private setInStorage;
+    private removeFromStorage;
+    private clearStorage;
+    private getFromIndexedDB;
+    private setInIndexedDB;
+    private removeFromIndexedDB;
+    private clearIndexedDB;
+    private serializeKeypair;
+    private deserializeKeypair;
+    private setupAutoRefresh;
+    private getStorageKey;
+    private log;
+}
+/**
+ * Pre-configured cache instances for common use cases
+ */
+declare const QuickCaches: {
+    /** Memory-only cache (30 minutes) */
+    memory: () => SessionKeyCache;
+    /** Persistent cache (1 hour, survives reload) */
+    persistent: () => SessionKeyCache;
+    /** Long-term cache (24 hours, IndexedDB) */
+    longTerm: () => SessionKeyCache;
+    /** Secure cache (5 minutes, memory-only) */
+    secure: () => SessionKeyCache;
+};
+
+/**
+ * AI Intent Parser & Adapters
+ * Parse natural language into payment intents
+ *
+ * @example
+ * ```typescript
+ * import { PaymentIntentParser, GeminiAdapter } from '@zendfi/sdk/helpers';
+ *
+ * // Parse AI response
+ * const intent = PaymentIntentParser.parse(aiResponse);
+ * if (intent?.action === 'payment') {
+ *   await zendfi.smartPayments.execute({
+ *     amount_usd: intent.amount,
+ *     description: intent.description,
+ *   });
+ * }
+ *
+ * // Or use adapters
+ * const gemini = new GeminiAdapter(apiKey);
+ * const { text, intent } = await gemini.chat('Buy coffee for $5');
+ * ```
+ */
+interface ParsedIntent {
+    action: 'payment' | 'create_session' | 'check_balance' | 'check_status' | 'topup' | 'revoke' | 'enable_autonomy' | 'chat_only';
+    amount?: number;
+    description?: string;
+    confidence: number;
+    rawText: string;
+    metadata?: Record<string, any>;
+}
+interface AICapabilities {
+    createPayment?: boolean;
+    createSessionKey?: boolean;
+    checkBalance?: boolean;
+    checkStatus?: boolean;
+    topUpSession?: boolean;
+    revokeSession?: boolean;
+    enableAutonomy?: boolean;
+}
+/**
+ * Payment Intent Parser
+ * Extract payment information from natural language
+ */
+declare class PaymentIntentParser {
+    /**
+     * Parse natural language into structured intent
+     */
+    static parse(text: string): ParsedIntent | null;
+    /**
+     * Generate system prompt for AI models
+     */
+    static generateSystemPrompt(capabilities?: AICapabilities): string;
+    private static containsPaymentKeywords;
+    private static containsSessionKeywords;
+    private static containsStatusKeywords;
+    private static containsTopUpKeywords;
+    private static containsRevokeKeywords;
+    private static containsAutonomyKeywords;
+    private static extractAmount;
+    private static extractDescription;
+}
+interface AIResponse {
+    text: string;
+    intent: ParsedIntent | null;
+    raw?: any;
+}
+/**
+ * OpenAI GPT Adapter
+ */
+declare class OpenAIAdapter {
+    private apiKey;
+    private model;
+    private capabilities?;
+    constructor(apiKey: string, model?: string, capabilities?: AICapabilities | undefined);
+    chat(message: string, conversationHistory?: Array<{
+        role: string;
+        content: string;
+    }>): Promise<AIResponse>;
+}
+/**
+ * Anthropic Claude Adapter
+ */
+declare class AnthropicAdapter {
+    private apiKey;
+    private model;
+    private capabilities?;
+    constructor(apiKey: string, model?: string, capabilities?: AICapabilities | undefined);
+    chat(message: string, conversationHistory?: Array<{
+        role: string;
+        content: string;
+    }>): Promise<AIResponse>;
+}
+/**
+ * Google Gemini Adapter
+ */
+declare class GeminiAdapter {
+    private apiKey;
+    private model;
+    private capabilities?;
+    constructor(apiKey: string, model?: string, capabilities?: AICapabilities | undefined);
+    chat(message: string): Promise<AIResponse>;
+}
+
+/**
+ * Wallet Connector
+ * Simplifies integration with Solana wallets (Phantom, Solflare, Backpack, etc.)
+ *
+ * @example
+ * ```typescript
+ * import { WalletConnector } from '@zendfi/sdk/helpers';
+ *
+ * // Auto-detect and connect
+ * const wallet = await WalletConnector.detectAndConnect();
+ * console.log(`Connected: ${wallet.address}`);
+ * console.log(`Provider: ${wallet.provider}`);
+ *
+ * // Sign transaction
+ * const result = await wallet.signTransaction(transaction);
+ *
+ * // Disconnect
+ * await wallet.disconnect();
+ * ```
+ */
+interface ConnectedWallet {
+    address: string;
+    provider: 'phantom' | 'solflare' | 'backpack' | 'coinbase' | 'trust' | 'unknown';
+    publicKey: any;
+    signTransaction: (tx: any) => Promise<any>;
+    signAllTransactions: (txs: any[]) => Promise<any[]>;
+    signMessage: (message: Uint8Array) => Promise<{
+        signature: Uint8Array;
+    }>;
+    disconnect: () => Promise<void>;
+    isConnected: () => boolean;
+    raw: any;
+}
+interface WalletConnectorConfig {
+    /** Preferred wallet provider (if multiple detected) */
+    preferredProvider?: 'phantom' | 'solflare' | 'backpack' | 'coinbase' | 'trust';
+    /** Auto-connect on page load if previously connected */
+    autoConnect?: boolean;
+    /** Show connection UI if no wallet detected */
+    showInstallPrompt?: boolean;
+    /** Network (mainnet-beta, devnet, testnet) */
+    network?: string;
+}
+/**
+ * Wallet Connector
+ * Detects and connects to Solana wallets
+ */
+declare class WalletConnector {
+    private static connectedWallet;
+    /**
+     * Detect and connect to a Solana wallet
+     */
+    static detectAndConnect(config?: WalletConnectorConfig): Promise<ConnectedWallet>;
+    /**
+     * Detect available Solana wallets
+     */
+    static detectWallets(): Array<'phantom' | 'solflare' | 'backpack' | 'coinbase' | 'trust'>;
+    /**
+     * Connect to a specific wallet provider
+     */
+    static connectToProvider(provider: 'phantom' | 'solflare' | 'backpack' | 'coinbase' | 'trust'): Promise<ConnectedWallet>;
+    /**
+     * Sign and submit a transaction
+     */
+    static signAndSubmit(transaction: any, wallet: ConnectedWallet, connection: any): Promise<{
+        signature: string;
+    }>;
+    /**
+     * Get current connected wallet
+     */
+    static getConnectedWallet(): ConnectedWallet | null;
+    /**
+     * Disconnect current wallet
+     */
+    static disconnect(): Promise<void>;
+    /**
+     * Listen for wallet connection changes
+     */
+    static onAccountChange(callback: (publicKey: any) => void): () => void;
+    /**
+     * Listen for wallet disconnection
+     */
+    static onDisconnect(callback: () => void): () => void;
+    /**
+     * Show install prompt UI
+     */
+    private static showInstallPrompt;
+    /**
+     * Check if wallet is installed
+     */
+    static isWalletInstalled(provider: 'phantom' | 'solflare' | 'backpack' | 'coinbase' | 'trust'): boolean;
+    /**
+     * Get wallet download URL
+     */
+    static getWalletUrl(provider: 'phantom' | 'solflare' | 'backpack' | 'coinbase' | 'trust'): string;
+}
+/**
+ * React Hook for Wallet Connection (optional)
+ * Export as separate module to avoid forcing React dependency
+ */
+declare function createWalletHook(): () => {
+    wallet: any;
+    connecting: any;
+    error: any;
+    connect: (config?: WalletConnectorConfig) => Promise<void>;
+    disconnect: () => Promise<void>;
+    isConnected: boolean;
+};
+
+/**
+ * Security Utilities
+ * PIN validation, rate limiting, and security best practices
+ *
+ * @example
+ * ```typescript
+ * import { PINValidator, PINRateLimiter } from '@zendfi/sdk/helpers';
+ *
+ * // Validate PIN
+ * const validation = PINValidator.validate(pin);
+ * if (!validation.valid) {
+ *   console.error(validation.errors);
+ * }
+ *
+ * // Rate limit PIN attempts
+ * const limiter = new PINRateLimiter();
+ * const attempt = await limiter.checkAttempt(sessionKeyId);
+ * if (!attempt.allowed) {
+ *   console.log(`Locked out for ${attempt.lockoutSeconds}s`);
+ * }
+ * ```
+ */
+interface PINValidationResult {
+    valid: boolean;
+    strength: 'weak' | 'medium' | 'strong';
+    errors: string[];
+    suggestions: string[];
+}
+/**
+ * PIN Validator
+ * Validates PIN security and strength
+ */
+declare class PINValidator {
+    /**
+     * Validate PIN strength and format
+     */
+    static validate(pin: string): PINValidationResult;
+    /**
+     * Check PIN strength (0-100 score)
+     */
+    static strengthScore(pin: string): number;
+    /**
+     * Generate a secure random PIN
+     */
+    static generateSecureRandom(length?: number): string;
+    /**
+     * Check for weak patterns
+     */
+    private static isWeakPattern;
+    /**
+     * Check if PIN is sequential
+     */
+    private static isSequential;
+    /**
+     * Check if PIN has repeated digits
+     */
+    private static hasRepeatedDigits;
+    /**
+     * Hash PIN for storage (if needed)
+     * Note: For device-bound keys, the PIN is used for key derivation, not storage
+     */
+    static hashPIN(pin: string, salt?: string): Promise<string>;
+}
+/**
+ * PIN Rate Limiter
+ * Prevents brute-force attacks on PIN entry
+ */
+declare class PINRateLimiter {
+    private attempts;
+    private locked;
+    private maxAttempts;
+    private windowMs;
+    private lockoutMs;
+    constructor(config?: {
+        maxAttempts?: number;
+        windowMs?: number;
+        lockoutMs?: number;
+    });
+    /**
+     * Check if attempt is allowed
+     */
+    checkAttempt(sessionKeyId: string): Promise<{
+        allowed: boolean;
+        remainingAttempts: number;
+        lockoutSeconds?: number;
+    }>;
+    /**
+     * Record a failed attempt
+     */
+    recordFailedAttempt(sessionKeyId: string): void;
+    /**
+     * Record a successful attempt (clears history)
+     */
+    recordSuccessfulAttempt(sessionKeyId: string): void;
+    /**
+     * Get recent attempts within window
+     */
+    private getRecentAttempts;
+    /**
+     * Clear all rate limit data
+     */
+    clear(): void;
+    /**
+     * Check lockout status
+     */
+    isLockedOut(sessionKeyId: string): boolean;
+    /**
+     * Get remaining lockout time
+     */
+    getRemainingLockoutTime(sessionKeyId: string): number;
+}
+/**
+ * Secure Storage Helper
+ * Utilities for secure data storage
+ */
+declare class SecureStorage {
+    /**
+     * Store data with encryption (basic)
+     * For production, consider using Web Crypto API with user-derived keys
+     */
+    static setEncrypted(key: string, value: string, secret: string): Promise<void>;
+    /**
+     * Retrieve encrypted data
+     */
+    static getEncrypted(key: string, secret: string): Promise<string | null>;
+    /**
+     * Encrypt string with AES-GCM
+     */
+    private static encrypt;
+    /**
+     * Decrypt AES-GCM ciphertext
+     */
+    private static decrypt;
+    /**
+     * Derive encryption key from secret
+     */
+    private static deriveKey;
+    /**
+     * Clear all secure storage
+     */
+    static clearAll(namespace?: string): void;
+}
+
+/**
+ * Transaction Polling Utilities
+ * Poll Solana transactions with exponential backoff
+ *
+ * @example
+ * ```typescript
+ * import { TransactionPoller } from '@zendfi/sdk/helpers';
+ *
+ * // Wait for confirmation
+ * const status = await TransactionPoller.waitForConfirmation(
+ *   signature,
+ *   { timeout: 60000, interval: 2000 }
+ * );
+ *
+ * if (status.confirmed) {
+ *   console.log(`Confirmed in slot ${status.slot}`);
+ * }
+ * ```
+ */
+interface TransactionStatus {
+    confirmed: boolean;
+    signature: string;
+    slot?: number;
+    blockTime?: number;
+    confirmations?: number;
+    error?: string;
+}
+interface PollingOptions {
+    /** Maximum time to wait in ms (default: 60000 = 1 minute) */
+    timeout?: number;
+    /** Initial polling interval in ms (default: 2000 = 2 seconds) */
+    interval?: number;
+    /** Maximum polling interval in ms (default: 10000 = 10 seconds) */
+    maxInterval?: number;
+    /** Maximum number of attempts (default: 30) */
+    maxAttempts?: number;
+    /** Commitment level (default: 'confirmed') */
+    commitment?: 'processed' | 'confirmed' | 'finalized';
+    /** RPC endpoint (optional, uses default if not provided) */
+    rpcUrl?: string;
+}
+/**
+ * Transaction Poller
+ * Poll transaction status with smart backoff
+ */
+declare class TransactionPoller {
+    /**
+     * Wait for transaction confirmation
+     */
+    static waitForConfirmation(signature: string, options?: PollingOptions): Promise<TransactionStatus>;
+    /**
+     * Check transaction status via RPC
+     */
+    private static checkTransactionStatus;
+    /**
+     * Check if commitment level is reached
+     */
+    private static isCommitmentReached;
+    /**
+     * Get default RPC URL based on environment
+     */
+    private static getDefaultRpcUrl;
+    /**
+     * Poll multiple transactions in parallel
+     */
+    static waitForMultiple(signatures: string[], options?: PollingOptions): Promise<TransactionStatus[]>;
+    /**
+     * Get transaction details after confirmation
+     */
+    static getTransactionDetails(signature: string, rpcUrl?: string): Promise<any>;
+    /**
+     * Check if transaction exists on chain
+     */
+    static exists(signature: string, rpcUrl?: string): Promise<boolean>;
+    /**
+     * Get recent blockhash (useful for transaction building)
+     */
+    static getRecentBlockhash(rpcUrl?: string): Promise<{
+        blockhash: string;
+        lastValidBlockHeight: number;
+    }>;
+    /**
+     * Sleep utility
+     */
+    private static sleep;
+}
+/**
+ * Transaction Monitor
+ * Monitor transaction status with callbacks
+ */
+declare class TransactionMonitor {
+    private monitors;
+    /**
+     * Start monitoring a transaction
+     */
+    monitor(signature: string, callbacks: {
+        onConfirmed?: (status: TransactionStatus) => void;
+        onFailed?: (status: TransactionStatus) => void;
+        onTimeout?: () => void;
+    }, options?: PollingOptions): void;
+    /**
+     * Stop monitoring a transaction
+     */
+    stopMonitoring(signature: string): void;
+    /**
+     * Stop all monitors
+     */
+    stopAll(): void;
+    /**
+     * Get active monitors
+     */
+    getActiveMonitors(): string[];
+}
+
+/**
+ * Retry Strategy & Error Recovery
+ * Smart retry logic with exponential backoff
+ *
+ * @example
+ * ```typescript
+ * import { RetryStrategy, ErrorRecovery } from '@zendfi/sdk/helpers';
+ *
+ * // Retry with exponential backoff
+ * const result = await RetryStrategy.withRetry(
+ *   () => zendfi.smartPayments.execute({ amount_usd: 50 }),
+ *   { maxAttempts: 3, backoffMs: 1000 }
+ * );
+ *
+ * // Auto-recover from common errors
+ * const payment = await ErrorRecovery.recoverFromNetworkError(
+ *   () => createPayment()
+ * );
+ * ```
+ */
+interface RetryOptions {
+    /** Maximum number of retry attempts (default: 3) */
+    maxAttempts?: number;
+    /** Initial backoff delay in ms (default: 1000) */
+    backoffMs?: number;
+    /** Backoff multiplier (default: 2 for exponential) */
+    backoffMultiplier?: number;
+    /** Maximum backoff delay in ms (default: 30000) */
+    maxBackoffMs?: number;
+    /** Function to determine if error is retryable (default: all errors) */
+    shouldRetry?: (error: Error, attempt: number) => boolean;
+    /** Callback on each retry */
+    onRetry?: (error: Error, attempt: number, nextDelayMs: number) => void;
+}
+/**
+ * Retry Strategy
+ * Implements smart retry logic with exponential backoff
+ */
+declare class RetryStrategy {
+    /**
+     * Execute function with retry logic
+     */
+    static withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+    /**
+     * Retry with linear backoff
+     */
+    static withLinearRetry<T>(fn: () => Promise<T>, maxAttempts?: number, delayMs?: number): Promise<T>;
+    /**
+     * Retry with custom backoff function
+     */
+    static withCustomBackoff<T>(fn: () => Promise<T>, backoffFn: (attempt: number) => number, maxAttempts?: number): Promise<T>;
+    /**
+     * Check if error is retryable
+     */
+    static isRetryableError(error: any): boolean;
+    private static sleep;
+}
+/**
+ * Error Recovery
+ * Auto-recovery strategies for common failure scenarios
+ */
+declare class ErrorRecovery {
+    /**
+     * Recover from network errors with retry
+     */
+    static recoverFromNetworkError<T>(fn: () => Promise<T>, maxAttempts?: number): Promise<T>;
+    /**
+     * Recover from rate limit errors with exponential backoff
+     */
+    static recoverFromRateLimit<T>(fn: () => Promise<T>, maxAttempts?: number): Promise<T>;
+    /**
+     * Recover from Solana RPC errors (blockhash, etc.)
+     */
+    static recoverFromRPCError<T>(fn: () => Promise<T>, maxAttempts?: number): Promise<T>;
+    /**
+     * Recover from timeout errors
+     */
+    static recoverFromTimeout<T>(fn: () => Promise<T>, timeoutMs?: number, maxAttempts?: number): Promise<T>;
+    /**
+     * Add timeout to async function
+     */
+    private static withTimeout;
+    /**
+     * Circuit breaker pattern for repeated failures
+     */
+    static createCircuitBreaker<T>(fn: () => Promise<T>, options?: {
+        failureThreshold?: number;
+        resetTimeoutMs?: number;
+        onStateChange?: (state: 'closed' | 'open' | 'half-open') => void;
+    }): () => Promise<T>;
+    /**
+     * Fallback to alternative function on error
+     */
+    static withFallback<T>(primaryFn: () => Promise<T>, fallbackFn: () => Promise<T>, shouldFallback?: (error: Error) => boolean): Promise<T>;
+    /**
+     * Graceful degradation - return partial result on error
+     */
+    static withGracefulDegradation<T>(fn: () => Promise<T>, defaultValue: T, onError?: (error: Error) => void): Promise<T>;
+}
+
+/**
+ * Session Key Lifecycle Manager
+ * High-level wrapper for device-bound session keys
+ * Handles common patterns: create → cache → use → revoke
+ *
+ * @example
+ * ```typescript
+ * import { SessionKeyLifecycle } from '@zendfi/sdk/helpers';
+ *
+ * const lifecycle = new SessionKeyLifecycle(zendfi, {
+ *   cache: QuickCaches.persistent(),
+ *   pinProvider: () => promptUserForPIN(),
+ * });
+ *
+ * // Create and fund in one call
+ * await lifecycle.createAndFund({
+ *   userWallet: address,
+ *   agentId: 'my-agent',
+ *   limitUsdc: 100,
+ * });
+ *
+ * // Make payments (auto-handles caching/PIN)
+ * await lifecycle.pay(5, 'Coffee');
+ *
+ * // Cleanup on app close
+ * await lifecycle.cleanup();
+ * ```
+ */
+
+interface LifecycleConfig {
+    /** Optional cache instance */
+    cache?: SessionKeyCache;
+    /** PIN provider function (called when cache expires) */
+    pinProvider?: () => Promise<string>;
+    /** Device fingerprint generator */
+    deviceFingerprintProvider?: () => Promise<string>;
+    /** Auto-cleanup on window/tab close */
+    autoCleanup?: boolean;
+}
+interface CreateAndFundConfig {
+    userWallet: string;
+    agentId: string;
+    agentName?: string;
+    limitUsdc: number;
+    durationDays?: number;
+    onApprovalNeeded?: (transaction: string) => Promise<string>;
+}
+interface PaymentResult {
+    paymentId: string;
+    status: string;
+    signature?: string;
+    confirmedInMs?: number;
+}
+/**
+ * Session Key Lifecycle Manager
+ * Simplifies device-bound session key management
+ */
+declare class SessionKeyLifecycle {
+    private client;
+    private config;
+    private sessionKeyId;
+    private sessionWallet;
+    private encryptedKey;
+    private deviceFingerprint;
+    constructor(client: ZendFiClient, config?: LifecycleConfig);
+    /**
+     * Create and fund session key in one call
+     * Handles: keypair generation → encryption → backend registration → funding
+     */
+    createAndFund(config: CreateAndFundConfig): Promise<{
+        sessionKeyId: string;
+        sessionWallet: string;
+    }>;
+    /**
+     * Make a payment using the session key
+     * Auto-handles caching, PIN prompts, and signing
+     */
+    pay(amount: number, description: string): Promise<PaymentResult>;
+    /**
+     * Check session key status
+     */
+    getStatus(): Promise<SessionKeyStatus>;
+    /**
+     * Top up session key
+     */
+    topUp(amount: number, userWallet: string, onApprovalNeeded?: (tx: string) => Promise<void>): Promise<void>;
+    /**
+     * Revoke session key
+     */
+    revoke(): Promise<void>;
+    /**
+     * Cleanup (clear cache, reset state)
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Get current session key ID
+     */
+    getSessionKeyId(): string | null;
+    /**
+     * Check if session is active
+     */
+    isActive(): boolean;
+    private decryptKeypair;
+    private generateDeviceFingerprint;
+    private promptForPIN;
+    private getSolanaWeb3;
+}
+/**
+ * Quick setup function for common use case
+ */
+declare function setupQuickSessionKey(client: ZendFiClient, config: {
+    userWallet: string;
+    agentId: string;
+    budgetUsdc: number;
+    onApproval: (tx: string) => Promise<string>;
+}): Promise<SessionKeyLifecycle>;
+
+/**
+ * Development Tools & Utilities
+ * Debugging helpers for development and testing
+ *
+ * @example
+ * ```typescript
+ * import { DevTools } from '@zendfi/sdk/helpers';
+ *
+ * // Enable debug mode
+ * DevTools.enableDebugMode();
+ *
+ * // Create test session key
+ * const testKey = await DevTools.createTestSessionKey();
+ *
+ * // Mock wallet for testing
+ * const mockWallet = DevTools.mockWallet();
+ *
+ * // Log transaction flow
+ * DevTools.logTransactionFlow(paymentId);
+ * ```
+ */
+interface MockWallet {
+    address: string;
+    publicKey: any;
+    signTransaction: (tx: any) => Promise<any>;
+    signMessage: (msg: Uint8Array) => Promise<{
+        signature: Uint8Array;
+    }>;
+    isConnected: () => boolean;
+    disconnect: () => Promise<void>;
+}
+interface TestSessionKey {
+    sessionKeyId: string;
+    sessionWallet: string;
+    privateKey: Uint8Array;
+    budget: number;
+}
+/**
+ * Development Tools
+ * Utilities for debugging and testing
+ */
+declare class DevTools {
+    private static debugEnabled;
+    private static requestLog;
+    /**
+     * Enable debug mode (logs all API requests/responses)
+     */
+    static enableDebugMode(): void;
+    /**
+     * Disable debug mode
+     */
+    static disableDebugMode(): void;
+    /**
+     * Check if debug mode is enabled
+     */
+    static isDebugEnabled(): boolean;
+    /**
+     * Log API request
+     */
+    static logRequest(method: string, url: string, body?: any): void;
+    /**
+     * Log API response
+     */
+    static logResponse(method: string, url: string, status: number, data: any, duration?: number): void;
+    /**
+     * Get request log
+     */
+    static getRequestLog(): Array<{
+        timestamp: Date;
+        method: string;
+        url: string;
+        status?: number;
+        duration?: number;
+    }>;
+    /**
+     * Clear request log
+     */
+    static clearRequestLog(): void;
+    /**
+     * Create a test session key (devnet only)
+     */
+    static createTestSessionKey(): Promise<TestSessionKey>;
+    /**
+     * Create a mock wallet for testing
+     */
+    static mockWallet(address?: string): MockWallet;
+    /**
+     * Log transaction flow (visual diagram in console)
+     */
+    static logTransactionFlow(paymentId: string): void;
+    /**
+     * Log session key lifecycle
+     */
+    static logSessionKeyLifecycle(sessionKeyId: string): void;
+    /**
+     * Benchmark API request
+     */
+    static benchmarkRequest<T>(name: string, fn: () => Promise<T>): Promise<{
+        result: T;
+        durationMs: number;
+    }>;
+    /**
+     * Stress test (send multiple concurrent requests)
+     */
+    static stressTest<T>(name: string, fn: () => Promise<T>, concurrency?: number, iterations?: number): Promise<{
+        totalRequests: number;
+        successful: number;
+        failed: number;
+        avgDurationMs: number;
+        minDurationMs: number;
+        maxDurationMs: number;
+    }>;
+    /**
+     * Inspect ZendFi SDK configuration
+     */
+    static inspectConfig(client: any): void;
+    /**
+     * Generate test data
+     */
+    static generateTestData(): {
+        userWallet: string;
+        agentId: string;
+        sessionKeyId: string;
+        paymentId: string;
+    };
+    /**
+     * Check if running in development environment
+     */
+    private static isDevelopment;
+    /**
+     * Generate test Solana address
+     */
+    private static generateTestAddress;
+    /**
+     * Generate test ID with prefix
+     */
+    private static generateTestId;
+    /**
+     * Get Solana Web3.js
+     */
+    private static getSolanaWeb3;
+}
+/**
+ * Performance Monitor
+ * Track SDK performance metrics
+ */
+declare class PerformanceMonitor {
+    private metrics;
+    /**
+     * Record a metric
+     */
+    record(name: string, value: number): void;
+    /**
+     * Get statistics for a metric
+     */
+    getStats(name: string): {
+        count: number;
+        avg: number;
+        min: number;
+        max: number;
+        p50: number;
+        p95: number;
+        p99: number;
+    } | null;
+    /**
+     * Get all metrics
+     */
+    getAllStats(): Record<string, ReturnType<typeof this.getStats>>;
+    /**
+     * Print report
+     */
+    printReport(): void;
+    /**
+     * Clear all metrics
+     */
+    clear(): void;
+}
+
+export { AgentAPI, AgentAnalytics, AgentApiKey, AgentPaymentRequest, AgentPaymentResponse, AgentSession, AnthropicAdapter, ApiError, ApproveEscrowRequest, AuthenticationError, AutonomyAPI, AutonomyStatus, type CachedKeypair, 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, 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, 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, ZendFiError, type ZendFiErrorData, type ZendFiErrorType, ZendFiSessionKeyManager, createWalletHook, createZendFiError, decodeSignatureFromLit, encodeTransactionForLit, generateIdempotencyKey, isZendFiError, requiresLitSigning, setupQuickSessionKey, sleep, verifyExpressWebhook, verifyNextWebhook, verifyWebhookSignature, zendfi };