@zendfi/sdk 0.5.8 → 0.6.0

package/README.md

@@ -38,20 +38,20 @@ console.log(payment.payment_url); // Send customer here
 
 ## Features
 
-### 🚀 **Core Payments** (Start Here)
+### **Core Payments** (Start Here)
 - **Simple Payments** — QR codes, payment links, instant settlements
 - **Payment Links** — Reusable checkout pages for social/email
 - **Webhooks** — Real-time notifications with auto-verification
 - **Test Mode** — Free devnet testing with no real money
 - **Type-Safe** — Full TypeScript support with auto-completion
 
-### 💼 **Scale Up** (When You Grow)
+### **Scale Up** (When You Grow)
 - **Subscriptions** — Recurring billing with trials
 - **Installments** — Buy now, pay later flows
 - **Invoices** — Professional invoicing with email
 - **Payment Splits** — Revenue sharing for marketplaces
 
-### 🤖 **AI-Ready** (Optional Advanced)
+### **AI-Ready** (Optional Advanced)
 - **Agent Keys** — Scoped API keys for AI with spending limits
 - **Session Keys** — Pre-funded wallets for autonomous payments
 - **Payment Intents** — Two-phase commit for reliable checkout
@@ -226,7 +226,7 @@ const payment = await zendfi.agent.pay({
 
 ---
 
-## 📚 Core API Reference
+## Core API Reference
 
 ### Namespaced APIs
 
@@ -399,6 +399,111 @@ const suggestion = await zendfi.pricing.getSuggestion({
 **Supported Countries (27+):**
 Argentina, Australia, Brazil, Canada, China, Colombia, Egypt, France, Germany, Ghana, Hong Kong, Hungary, India, Indonesia, Israel, Japan, Kenya, Mexico, Nigeria, Philippines, Poland, South Africa, Thailand, Turkey, Ukraine, United Kingdom, Vietnam, and more.
 
+---
+
+## Optional Helper Utilities
+
+Production-ready utilities to simplify common integration patterns. All helpers are **optional**, **tree-shakeable**, and **zero-config**.
+
+```typescript
+import { 
+  SessionKeyCache,
+  WalletConnector,
+  TransactionPoller,
+  DevTools 
+} from '@zendfi/sdk/helpers';
+```
+
+### Why Use Helpers?
+
+- **Optional**: Import only what you need
+- **Tree-shakeable**: Unused code eliminated by bundlers  
+- **Zero config**: Sensible defaults, works out of the box
+- **Pluggable**: Bring your own storage/AI/PIN providers
+- **Production-ready**: Full TypeScript types, error handling
+
+### Available Helpers
+
+| Helper | Purpose | Use Case |
+|--------|---------|----------|
+| `SessionKeyCache` | Cache encrypted session keys | Avoid re-prompting for PIN |
+| `WalletConnector` | Detect & connect Solana wallets | Phantom, Solflare, Backpack |
+| `PaymentIntentParser` | Parse natural language to payments | AI chat interfaces |
+| `PINValidator` | Validate PIN strength | Device-bound security |
+| `TransactionPoller` | Poll for confirmations | Wait for on-chain finality |
+| `RetryStrategy` | Exponential backoff retries | Handle network failures |
+| `SessionKeyLifecycle` | High-level session key manager | One-liner setup |
+| `DevTools` | Debug mode & test utilities | Development & testing |
+
+### Session Key Cache
+
+Cache encrypted session keys to avoid re-prompting users for their PIN:
+
+```typescript
+import { SessionKeyCache, QuickCaches } from '@zendfi/sdk/helpers';
+
+// Use presets
+const cache = QuickCaches.persistent(); // 1 hour localStorage
+
+// Use with device-bound session keys
+const keypair = await cache.getCached(
+  sessionKeyId,
+  async () => {
+    const pin = await promptUserForPIN();
+    return await decryptKeypair(pin);
+  }
+);
+```
+
+### Wallet Connector
+
+Auto-detect and connect to Solana wallets:
+
+```typescript
+import { WalletConnector } from '@zendfi/sdk/helpers';
+
+const wallet = await WalletConnector.detectAndConnect();
+console.log(wallet.address);
+
+const signedTx = await wallet.signTransaction(transaction);
+```
+
+### Transaction Polling
+
+Wait for confirmations with exponential backoff:
+
+```typescript
+import { TransactionPoller } from '@zendfi/sdk/helpers';
+
+const poller = new TransactionPoller({ connection: rpcConnection });
+const result = await poller.waitForConfirmation(signature);
+```
+
+### Session Key Lifecycle
+
+High-level wrapper for complete session key management:
+
+```typescript
+import { SessionKeyLifecycle } from '@zendfi/sdk/helpers';
+
+const lifecycle = new SessionKeyLifecycle(zendfi, {
+  cache: QuickCaches.persistent(),
+  autoCleanup: true,
+});
+
+await lifecycle.createAndFund({
+  userWallet: userAddress,
+  agentId: 'my-agent',
+  limitUsdc: 100,
+});
+
+await lifecycle.pay(5.00, 'Coffee');
+```
+
+**Full documentation:** See [Helper Utilities Guide](https://docs.zendfi.tech/helpers) for complete API reference and examples.
+
+---
+
 ### Autonomous Delegation
 
 Enable agents to make payments without per-transaction approval:

package/dist/cache-T5YPC7OK.mjs

@@ -0,0 +1,9 @@
+import {
+  QuickCaches,
+  SessionKeyCache
+} from "./chunk-5O5NAX65.mjs";
+import "./chunk-Y6FXYEAI.mjs";
+export {
+  QuickCaches,
+  SessionKeyCache
+};

package/dist/{chunk-YFOBPGQE.mjs → chunk-3ACJUM6V.mjs}

@@ -1,10 +1,3 @@
-var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
-  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
-}) : x)(function(x) {
-  if (typeof require !== "undefined") return require.apply(this, arguments);
-  throw Error('Dynamic require of "' + x + '" is not supported');
-});
-
 // src/webhook-handler.ts
 import { createHmac, timingSafeEqual } from "crypto";
 var processedWebhooks = /* @__PURE__ */ new Set();
@@ -147,6 +140,5 @@ async function processWebhook(a, b, c) {
 }
 
 export {
-  __require,
   processWebhook
 };

package/dist/chunk-5O5NAX65.mjs

@@ -0,0 +1,366 @@
+// src/helpers/cache.ts
+var SessionKeyCache = class {
+  memoryCache = /* @__PURE__ */ new Map();
+  config;
+  refreshTimers = /* @__PURE__ */ new Map();
+  constructor(config = {}) {
+    this.config = {
+      storage: config.storage || "memory",
+      ttl: config.ttl || 30 * 60 * 1e3,
+      // 30 minutes default
+      autoRefresh: config.autoRefresh || false,
+      namespace: config.namespace || "zendfi_cache",
+      debug: config.debug || false
+    };
+  }
+  /**
+   * Get cached keypair or decrypt and cache
+   */
+  async getCached(sessionKeyId, decryptFn, options) {
+    this.log(`getCached: ${sessionKeyId}`);
+    const memoryCached = this.memoryCache.get(sessionKeyId);
+    if (memoryCached && Date.now() < memoryCached.expiry) {
+      this.log(`Memory cache HIT: ${sessionKeyId}`);
+      return memoryCached.keypair;
+    }
+    if (this.config.storage !== "memory") {
+      const persistentCached = await this.getFromStorage(sessionKeyId);
+      if (persistentCached && Date.now() < persistentCached.expiry) {
+        if (options?.deviceFingerprint && persistentCached.deviceFingerprint) {
+          if (options.deviceFingerprint !== persistentCached.deviceFingerprint) {
+            this.log(`Device fingerprint mismatch for ${sessionKeyId}`);
+            await this.invalidate(sessionKeyId);
+            return await this.decryptAndCache(sessionKeyId, decryptFn, options);
+          }
+        }
+        this.log(`Persistent cache HIT: ${sessionKeyId}`);
+        this.memoryCache.set(sessionKeyId, persistentCached);
+        return persistentCached.keypair;
+      }
+    }
+    this.log(`Cache MISS: ${sessionKeyId}`);
+    return await this.decryptAndCache(sessionKeyId, decryptFn, options);
+  }
+  /**
+   * Decrypt keypair and cache it
+   */
+  async decryptAndCache(sessionKeyId, decryptFn, options) {
+    const keypair = await decryptFn();
+    const expiry = Date.now() + this.config.ttl;
+    const cached = {
+      keypair,
+      expiry,
+      sessionKeyId,
+      deviceFingerprint: options?.deviceFingerprint
+    };
+    this.memoryCache.set(sessionKeyId, cached);
+    if (this.config.storage !== "memory") {
+      await this.setInStorage(sessionKeyId, cached);
+    }
+    if (this.config.autoRefresh) {
+      this.setupAutoRefresh(sessionKeyId, decryptFn, options);
+    }
+    this.log(`Cached: ${sessionKeyId}, expires in ${this.config.ttl}ms`);
+    return keypair;
+  }
+  /**
+   * Invalidate cached keypair
+   */
+  async invalidate(sessionKeyId) {
+    this.log(`Invalidating: ${sessionKeyId}`);
+    this.memoryCache.delete(sessionKeyId);
+    const timer = this.refreshTimers.get(sessionKeyId);
+    if (timer) {
+      clearTimeout(timer);
+      this.refreshTimers.delete(sessionKeyId);
+    }
+    if (this.config.storage !== "memory") {
+      await this.removeFromStorage(sessionKeyId);
+    }
+  }
+  /**
+   * Clear all cached keypairs
+   */
+  async clear() {
+    this.log("Clearing all cache");
+    this.memoryCache.clear();
+    for (const timer of this.refreshTimers.values()) {
+      clearTimeout(timer);
+    }
+    this.refreshTimers.clear();
+    if (this.config.storage !== "memory") {
+      await this.clearStorage();
+    }
+  }
+  /**
+   * Get cache statistics
+   */
+  getStats() {
+    const entries = Array.from(this.memoryCache.entries()).map(([id, cached]) => ({
+      sessionKeyId: id,
+      expiresIn: Math.max(0, cached.expiry - Date.now())
+    }));
+    return { size: this.memoryCache.size, entries };
+  }
+  /**
+   * Check if a session key is cached and valid
+   */
+  isCached(sessionKeyId) {
+    const cached = this.memoryCache.get(sessionKeyId);
+    return cached ? Date.now() < cached.expiry : false;
+  }
+  /**
+   * Update TTL for a cached session key
+   */
+  async extendTTL(sessionKeyId, additionalMs) {
+    const cached = this.memoryCache.get(sessionKeyId);
+    if (!cached) return false;
+    cached.expiry += additionalMs;
+    this.memoryCache.set(sessionKeyId, cached);
+    if (this.config.storage !== "memory") {
+      await this.setInStorage(sessionKeyId, cached);
+    }
+    this.log(`Extended TTL for ${sessionKeyId} by ${additionalMs}ms`);
+    return true;
+  }
+  // ============================================
+  // Storage Backend Implementations
+  // ============================================
+  async getFromStorage(sessionKeyId) {
+    try {
+      const key = this.getStorageKey(sessionKeyId);
+      if (this.config.storage === "localStorage") {
+        const data = localStorage.getItem(key);
+        if (!data) return null;
+        const parsed = JSON.parse(data);
+        return {
+          ...parsed,
+          keypair: this.deserializeKeypair(parsed.keypair)
+        };
+      }
+      if (this.config.storage === "indexedDB") {
+        return await this.getFromIndexedDB(key);
+      }
+      if (typeof this.config.storage === "object") {
+        const data = await this.config.storage.get(key);
+        if (!data) return null;
+        const parsed = JSON.parse(data);
+        return {
+          ...parsed,
+          keypair: this.deserializeKeypair(parsed.keypair)
+        };
+      }
+    } catch (error) {
+      this.log(`Error reading from storage: ${error}`);
+    }
+    return null;
+  }
+  async setInStorage(sessionKeyId, cached) {
+    try {
+      const key = this.getStorageKey(sessionKeyId);
+      const serialized = {
+        ...cached,
+        keypair: this.serializeKeypair(cached.keypair)
+      };
+      if (this.config.storage === "localStorage") {
+        localStorage.setItem(key, JSON.stringify(serialized));
+        return;
+      }
+      if (this.config.storage === "indexedDB") {
+        await this.setInIndexedDB(key, serialized);
+        return;
+      }
+      if (typeof this.config.storage === "object") {
+        await this.config.storage.set(key, JSON.stringify(serialized));
+      }
+    } catch (error) {
+      this.log(`Error writing to storage: ${error}`);
+    }
+  }
+  async removeFromStorage(sessionKeyId) {
+    try {
+      const key = this.getStorageKey(sessionKeyId);
+      if (this.config.storage === "localStorage") {
+        localStorage.removeItem(key);
+        return;
+      }
+      if (this.config.storage === "indexedDB") {
+        await this.removeFromIndexedDB(key);
+        return;
+      }
+      if (typeof this.config.storage === "object") {
+        await this.config.storage.remove(key);
+      }
+    } catch (error) {
+      this.log(`Error removing from storage: ${error}`);
+    }
+  }
+  async clearStorage() {
+    try {
+      if (this.config.storage === "localStorage") {
+        const keysToRemove = [];
+        for (let i = 0; i < localStorage.length; i++) {
+          const key = localStorage.key(i);
+          if (key?.startsWith(this.config.namespace)) {
+            keysToRemove.push(key);
+          }
+        }
+        keysToRemove.forEach((key) => localStorage.removeItem(key));
+        return;
+      }
+      if (this.config.storage === "indexedDB") {
+        await this.clearIndexedDB();
+        return;
+      }
+      if (typeof this.config.storage === "object") {
+        await this.config.storage.clear();
+      }
+    } catch (error) {
+      this.log(`Error clearing storage: ${error}`);
+    }
+  }
+  // ============================================
+  // IndexedDB Helpers
+  // ============================================
+  async getFromIndexedDB(key) {
+    return new Promise((resolve) => {
+      const request = indexedDB.open(this.config.namespace, 1);
+      request.onerror = () => resolve(null);
+      request.onupgradeneeded = (event) => {
+        const db = event.target.result;
+        if (!db.objectStoreNames.contains("cache")) {
+          db.createObjectStore("cache");
+        }
+      };
+      request.onsuccess = (event) => {
+        const db = event.target.result;
+        const transaction = db.transaction(["cache"], "readonly");
+        const store = transaction.objectStore("cache");
+        const getRequest = store.get(key);
+        getRequest.onsuccess = () => {
+          resolve(getRequest.result || null);
+        };
+        getRequest.onerror = () => resolve(null);
+      };
+    });
+  }
+  async setInIndexedDB(key, value) {
+    return new Promise((resolve, reject) => {
+      const request = indexedDB.open(this.config.namespace, 1);
+      request.onerror = () => reject(new Error("IndexedDB error"));
+      request.onupgradeneeded = (event) => {
+        const db = event.target.result;
+        if (!db.objectStoreNames.contains("cache")) {
+          db.createObjectStore("cache");
+        }
+      };
+      request.onsuccess = (event) => {
+        const db = event.target.result;
+        const transaction = db.transaction(["cache"], "readwrite");
+        const store = transaction.objectStore("cache");
+        store.put(value, key);
+        transaction.oncomplete = () => resolve();
+        transaction.onerror = () => reject(new Error("IndexedDB transaction error"));
+      };
+    });
+  }
+  async removeFromIndexedDB(key) {
+    return new Promise((resolve) => {
+      const request = indexedDB.open(this.config.namespace, 1);
+      request.onsuccess = (event) => {
+        const db = event.target.result;
+        const transaction = db.transaction(["cache"], "readwrite");
+        const store = transaction.objectStore("cache");
+        store.delete(key);
+        transaction.oncomplete = () => resolve();
+      };
+      request.onerror = () => resolve();
+    });
+  }
+  async clearIndexedDB() {
+    return new Promise((resolve) => {
+      const request = indexedDB.open(this.config.namespace, 1);
+      request.onsuccess = (event) => {
+        const db = event.target.result;
+        const transaction = db.transaction(["cache"], "readwrite");
+        const store = transaction.objectStore("cache");
+        store.clear();
+        transaction.oncomplete = () => resolve();
+      };
+      request.onerror = () => resolve();
+    });
+  }
+  // ============================================
+  // Serialization
+  // ============================================
+  serializeKeypair(keypair) {
+    if (keypair && typeof keypair === "object" && "secretKey" in keypair) {
+      return {
+        type: "solana",
+        secretKey: Array.from(keypair.secretKey)
+      };
+    }
+    if (keypair instanceof Uint8Array) {
+      return {
+        type: "uint8array",
+        data: Array.from(keypair)
+      };
+    }
+    return keypair;
+  }
+  deserializeKeypair(data) {
+    if (!data || typeof data !== "object") return data;
+    if (data.type === "solana" && data.secretKey) {
+      return new Uint8Array(data.secretKey);
+    }
+    if (data.type === "uint8array" && data.data) {
+      return new Uint8Array(data.data);
+    }
+    return data;
+  }
+  // ============================================
+  // Auto-Refresh
+  // ============================================
+  setupAutoRefresh(sessionKeyId, decryptFn, options) {
+    const existingTimer = this.refreshTimers.get(sessionKeyId);
+    if (existingTimer) {
+      clearTimeout(existingTimer);
+    }
+    const refreshIn = Math.max(0, this.config.ttl - 5 * 60 * 1e3);
+    const timer = setTimeout(async () => {
+      this.log(`Auto-refreshing: ${sessionKeyId}`);
+      try {
+        await this.decryptAndCache(sessionKeyId, decryptFn, options);
+      } catch (error) {
+        this.log(`Auto-refresh failed: ${error}`);
+      }
+    }, refreshIn);
+    this.refreshTimers.set(sessionKeyId, timer);
+  }
+  // ============================================
+  // Utilities
+  // ============================================
+  getStorageKey(sessionKeyId) {
+    return `${this.config.namespace}:${sessionKeyId}`;
+  }
+  log(message) {
+    if (this.config.debug) {
+      console.log(`[SessionKeyCache] ${message}`);
+    }
+  }
+};
+var QuickCaches = {
+  /** Memory-only cache (30 minutes) */
+  memory: () => new SessionKeyCache({ storage: "memory", ttl: 30 * 60 * 1e3 }),
+  /** Persistent cache (1 hour, survives reload) */
+  persistent: () => new SessionKeyCache({ storage: "localStorage", ttl: 60 * 60 * 1e3 }),
+  /** Long-term cache (24 hours, IndexedDB) */
+  longTerm: () => new SessionKeyCache({ storage: "indexedDB", ttl: 24 * 60 * 60 * 1e3, autoRefresh: true }),
+  /** Secure cache (5 minutes, memory-only) */
+  secure: () => new SessionKeyCache({ storage: "memory", ttl: 5 * 60 * 1e3 })
+};
+
+export {
+  SessionKeyCache,
+  QuickCaches
+};