@zendfi/sdk 0.8.4 → 1.0.1

package/dist/helpers/index.d.ts

@@ -0,0 +1,402 @@
+/**
+ * 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;
+};
+
+/**
+ * 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[];
+}
+
+/**
+ * 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 { type ConnectedWallet, DevTools, type MockWallet, PerformanceMonitor, type PollingOptions, type TestSessionKey, TransactionMonitor, TransactionPoller, type TransactionStatus, WalletConnector, createWalletHook };