@zendfi/sdk 0.5.8 → 0.7.0

package/README.md

@@ -26,11 +26,11 @@ console.log(payment.payment_url); // Send customer here
 
 | Feature | Stripe | PayPal | **ZendFi** |
 |---------|--------|--------|------------|
-| **Fees** | 2.9% + $0.30 | 3.5% + $0.49 | **0.6% flat** ✨ |
-| **Settlement** | 7 days | 3-5 days | **Instant** ✨ |
-| **Crypto Native** | Via 3rd party | Via 3rd party | **Built-in** ✨ |
-| **AI Agent Ready** | ❌ | ❌ | **✅ Native** ✨ |
-| **Setup Time** | 30 min | 30 min | **5 min** ✨ |
+| **Fees** | 2.9% + $0.30 | 3.5% + $0.49 | **0.6% flat** |
+| **Settlement** | 7 days | 3-5 days | **Instant** |
+| **Crypto Native** | Via 3rd party | Via 3rd party | **Built-in** |
+| **AI Agent Ready** | ACP  | NO | **Native** |
+| **Setup Time** | 30 min | 30 min | **5 min** |
 
 **Save 81% on fees.** Get paid instantly. Scale to AI when ready.
 
@@ -38,20 +38,21 @@ console.log(payment.payment_url); // Send customer here
 
 ## Features
 
-### 🚀 **Core Payments** (Start Here)
+### **Core Payments** (Start Here)
+- **Embedded Checkout** — Drop-in checkout component for your website/app
 - **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
@@ -125,6 +126,66 @@ console.log(payment.payment_url);
 
 ---
 
+## Embedded Checkout
+
+Skip redirects entirely—embed the checkout directly into your website or app. Perfect for seamless user experiences.
+
+### Quick Example
+
+```typescript
+import { ZendFiEmbeddedCheckout } from '@zendfi/sdk';
+
+const checkout = new ZendFiEmbeddedCheckout({
+  linkCode: 'your-payment-link-code',
+  containerId: 'checkout-container',
+  mode: 'test',
+  
+  onSuccess: (payment) => {
+    console.log('Payment successful!', payment.transactionSignature);
+    // Redirect to success page or show confirmation
+  },
+  
+  onError: (error) => {
+    console.error('Payment failed:', error.message);
+  },
+});
+
+// Mount the checkout
+await checkout.mount();
+```
+
+### HTML Setup
+
+```html
+<div id="checkout-container"></div>
+<script type="module">
+  import { ZendFiEmbeddedCheckout } from '@zendfi/sdk';
+  // ... (setup code above)
+</script>
+```
+
+### Features
+
+- **Drop-in Integration** — Works with React, Vue, Next.js, or vanilla JS
+- **QR Code Generation** — Automatic mobile wallet support
+- **Wallet Connect** — Phantom, Solflare, Backpack support
+- **Real-time Updates** — Live payment confirmation polling
+- **Gasless Transactions** — Optional backend-signed payments
+- **Customizable Theme** — Match your brand colors & styles
+- **TypeScript First** — Full type safety and autocomplete
+
+### Complete Documentation
+
+For comprehensive guides, React examples, theming, and advanced usage:
+
+- **Quick Start:** [`EMBEDDED_CHECKOUT_QUICKSTART.md`](./EMBEDDED_CHECKOUT_QUICKSTART.md)
+- **Full Guide:** [`EMBEDDED_CHECKOUT.md`](./EMBEDDED_CHECKOUT.md)
+- **Implementation Details:** [`EMBEDDED_CHECKOUT_IMPLEMENTATION.md`](./EMBEDDED_CHECKOUT_IMPLEMENTATION.md)
+- **React Example:** [`examples/embedded-checkout-react.tsx`](./examples/embedded-checkout-react.tsx)
+- **Vanilla JS Example:** [`examples/embedded-checkout-vanilla.html`](./examples/embedded-checkout-vanilla.html)
+
+---
+
 ## API Key Modes
 
 ZendFi uses **smart API keys** that automatically route to the correct network:
@@ -172,7 +233,7 @@ This covers:
 
 ---
 
-## 🤖 AI-Ready Features (Optional Advanced)
+## AI-Ready Features (Optional Advanced)
 
 Building AI agents? ZendFi has native support for autonomous payments with cryptographic security and spending limits.
 
@@ -226,12 +287,15 @@ const payment = await zendfi.agent.pay({
 
 ---
 
-## 📚 Core API Reference
+## Core API Reference
 
 ### Namespaced APIs
 
 ```typescript
-import { zendfi } from '@zendfi/sdk';
+import { zendfi, ZendFiEmbeddedCheckout } from '@zendfi/sdk';
+
+// Embedded Checkout (New!)
+const checkout = new ZendFiEmbeddedCheckout({...});
 
 // Traditional Payments (Most Common)
 zendfi.createPayment(...)
@@ -399,6 +463,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:
@@ -709,7 +878,7 @@ await zendfi.cancelInstallmentPlan(plan.id);
 
 ---
 
-### 🧾 Invoices
+### Invoices
 
 Professional invoices with crypto payment options.
 
@@ -1097,6 +1266,45 @@ console.log('Status:', updated.status); // "Confirmed"
 
 ## Examples
 
+### Embedded Checkout Integration
+
+```typescript
+import { ZendFiEmbeddedCheckout } from '@zendfi/sdk';
+
+// React Component
+function CheckoutPage({ linkCode }) {
+  const containerRef = useRef(null);
+  
+  useEffect(() => {
+    const checkout = new ZendFiEmbeddedCheckout({
+      linkCode,
+      containerId: 'checkout-container',
+      mode: 'test',
+      
+      onSuccess: (payment) => {
+        // Payment successful - redirect or show confirmation
+        router.push(`/success?payment=${payment.paymentId}`);
+      },
+      
+      onError: (error) => {
+        // Handle errors
+        setError(error.message);
+      },
+      
+      theme: {
+        primaryColor: '#8b5cf6',
+        borderRadius: '16px',
+      },
+    });
+    
+    checkout.mount();
+    return () => checkout.unmount();
+  }, [linkCode]);
+  
+  return <div id="checkout-container" ref={containerRef} />;
+}
+```
+
 ### E-commerce Checkout
 
 ```typescript

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
+};