@zendfi/sdk 0.5.2 → 0.5.4

package/dist/index.js

@@ -49,6 +49,7 @@ __export(index_exports, {
   RecoveryQRGenerator: () => RecoveryQRGenerator,
   SPENDING_LIMIT_ACTION_CID: () => SPENDING_LIMIT_ACTION_CID,
   SessionKeyCrypto: () => SessionKeyCrypto,
+  SessionKeysAPI: () => SessionKeysAPI,
   SmartPaymentsAPI: () => SmartPaymentsAPI,
   ValidationError: () => ValidationError2,
   WebhookError: () => WebhookError,
@@ -719,6 +720,70 @@ var AgentAPI = class {
     await this.request("POST", `/api/v1/ai/sessions/${sessionId}/revoke`);
   }
   // ============================================
+  // Agent Payments
+  // ============================================
+  /**
+   * Execute a payment using an agent session
+   * 
+   * This is the primary method for AI agents to make payments. It uses the
+   * session token to enforce spending limits and automatically routes the
+   * payment through the optimal path.
+   * 
+   * The session token comes from `createSession()` and enforces:
+   * - Per-transaction limits
+   * - Daily limits
+   * - Weekly limits
+   * - Monthly limits
+   * 
+   * @param request - Payment request with session token
+   * @returns Payment result with status and receipt
+   * 
+   * @example
+   * ```typescript
+   * // Create a session first
+   * const session = await zendfi.agent.createSession({
+   *   agent_id: 'shopping-bot',
+   *   user_wallet: 'Hx7B...abc',
+   *   limits: {
+   *     max_per_transaction: 50,
+   *     max_per_day: 200,
+   *   },
+   *   duration_hours: 24,
+   * });
+   * 
+   * // Make payments within the session limits
+   * const payment = await zendfi.agent.pay({
+   *   session_token: session.session_token,
+   *   amount: 29.99,
+   *   description: 'Premium widget',
+   *   auto_gasless: true,
+   * });
+   * 
+   * if (payment.requires_signature) {
+   *   // Device-bound: user must sign
+   *   console.log('Sign and submit to:', payment.submit_url);
+   * } else {
+   *   // Auto-signed: payment complete
+   *   console.log('Payment confirmed:', payment.transaction_signature);
+   * }
+   * ```
+   */
+  async pay(request) {
+    return this.request("POST", "/api/v1/ai/smart-payment", {
+      session_token: request.session_token,
+      agent_id: "session",
+      // Session already has agent_id bound
+      user_wallet: "",
+      // Will be extracted from session
+      amount_usd: request.amount,
+      merchant_id: request.recipient_merchant_id,
+      token: request.token || "USDC",
+      auto_detect_gasless: request.auto_gasless,
+      description: request.description,
+      metadata: request.metadata
+    });
+  }
+  // ============================================
   // Agent Analytics
   // ============================================
   /**
@@ -854,7 +919,8 @@ var PaymentIntentsAPI = class {
       customer_wallet: request.customer_wallet,
       payment_type: request.payment_type,
       auto_gasless: request.auto_gasless,
-      metadata: request.metadata
+      metadata: request.metadata,
+      session_token: request.session_token
     });
   }
   /**
@@ -1318,6 +1384,269 @@ var SmartPaymentsAPI = class {
   }
 };
 
+// src/api/session-keys.ts
+var SessionKeysAPI = class {
+  constructor(request) {
+    this.request = request;
+  }
+  // ============================================
+  // Custodial Session Keys
+  // ============================================
+  /**
+   * Create a custodial session key
+   * 
+   * The backend generates and securely stores the keypair.
+   * Returns an approval transaction that the user must sign to fund the session wallet.
+   * 
+   * @param request - Session key configuration
+   * @returns Creation response with approval transaction
+   * 
+   * @example
+   * ```typescript
+   * const result = await zendfi.sessionKeys.create({
+   *   user_wallet: 'Hx7B...abc',
+   *   limit_usdc: 100,
+   *   duration_days: 7,
+   *   device_fingerprint: deviceFingerprint,
+   * });
+   * 
+   * console.log(`Session key: ${result.session_key_id}`);
+   * console.log('Please sign the approval transaction');
+   * ```
+   */
+  async create(request) {
+    return this.request("POST", "/api/v1/ai/session-keys/create", {
+      user_wallet: request.user_wallet,
+      limit_usdc: request.limit_usdc,
+      duration_days: request.duration_days ?? 7,
+      device_fingerprint: request.device_fingerprint
+    });
+  }
+  // ============================================
+  // Device-Bound Session Keys (Non-Custodial)
+  // ============================================
+  /**
+   * Create a device-bound session key (non-custodial)
+   * 
+   * The client generates the keypair and encrypts it with a PIN before sending.
+   * The backend cannot decrypt the keypair - only the user's device can.
+   * 
+   * @param request - Device-bound session key configuration
+   * @returns Creation response with session wallet address
+   * 
+   * @example
+   * ```typescript
+   * // Generate keypair client-side
+   * const keypair = Keypair.generate();
+   * 
+   * // Encrypt with PIN
+   * const encrypted = await encryptWithPin(keypair.secretKey, pin);
+   * 
+   * const result = await zendfi.sessionKeys.createDeviceBound({
+   *   user_wallet: 'Hx7B...abc',
+   *   limit_usdc: 100,
+   *   duration_days: 7,
+   *   encrypted_session_key: encrypted.ciphertext,
+   *   nonce: encrypted.nonce,
+   *   session_public_key: keypair.publicKey.toBase58(),
+   *   device_fingerprint: deviceFingerprint,
+   * });
+   * 
+   * console.log(`Session wallet: ${result.session_wallet}`);
+   * ```
+   */
+  async createDeviceBound(request) {
+    return this.request(
+      "POST",
+      "/api/v1/ai/session-keys/device-bound/create",
+      {
+        user_wallet: request.user_wallet,
+        limit_usdc: request.limit_usdc,
+        duration_days: request.duration_days,
+        encrypted_session_key: request.encrypted_session_key,
+        nonce: request.nonce,
+        session_public_key: request.session_public_key,
+        device_fingerprint: request.device_fingerprint,
+        recovery_qr_data: request.recovery_qr_data
+      }
+    );
+  }
+  /**
+   * Get encrypted session key for device-bound mode
+   * 
+   * Retrieves the encrypted keypair so the client can decrypt it with their PIN.
+   * The device fingerprint must match the one used during creation.
+   * 
+   * @param sessionKeyId - UUID of the session key
+   * @param deviceFingerprint - Current device fingerprint
+   * @returns Encrypted key data
+   */
+  async getEncrypted(sessionKeyId, deviceFingerprint) {
+    return this.request("POST", "/api/v1/ai/session-keys/device-bound/get-encrypted", {
+      session_key_id: sessionKeyId,
+      device_fingerprint: deviceFingerprint
+    });
+  }
+  // ============================================
+  // Transaction Submission
+  // ============================================
+  /**
+   * Submit a signed approval transaction
+   * 
+   * After the user signs the approval transaction from `create()`,
+   * submit it here to activate the session key.
+   * 
+   * @param request - Signed transaction data
+   * @returns Submission result with signature
+   * 
+   * @example
+   * ```typescript
+   * const result = await zendfi.sessionKeys.submitApproval({
+   *   session_key_id: sessionKeyId,
+   *   signed_transaction: signedTxBase64,
+   * });
+   * 
+   * console.log(`Approved! Signature: ${result.signature}`);
+   * ```
+   */
+  async submitApproval(request) {
+    return this.request(
+      "POST",
+      "/api/v1/ai/session-keys/submit-approval",
+      {
+        session_key_id: request.session_key_id,
+        signed_transaction: request.signed_transaction
+      }
+    );
+  }
+  /**
+   * Submit a signed top-up transaction
+   * 
+   * After the user signs the top-up transaction from `topUp()`,
+   * submit it here to add funds.
+   * 
+   * @param sessionKeyId - UUID of the session key
+   * @param signedTransaction - Base64 encoded signed transaction
+   * @returns Submission result with new limit
+   */
+  async submitTopUp(sessionKeyId, signedTransaction) {
+    return this.request(
+      "POST",
+      `/api/v1/ai/session-keys/${sessionKeyId}/submit-top-up`,
+      {
+        signed_transaction: signedTransaction
+      }
+    );
+  }
+  // ============================================
+  // Status & Management
+  // ============================================
+  /**
+   * Get session key status
+   * 
+   * @param sessionKeyId - UUID of the session key
+   * @returns Current status with remaining balance
+   * 
+   * @example
+   * ```typescript
+   * const status = await zendfi.sessionKeys.getStatus(sessionKeyId);
+   * 
+   * console.log(`Active: ${status.is_active}`);
+   * console.log(`Limit: $${status.limit_usdc}`);
+   * console.log(`Used: $${status.used_amount_usdc}`);
+   * console.log(`Remaining: $${status.remaining_usdc}`);
+   * console.log(`Expires in ${status.days_until_expiry} days`);
+   * ```
+   */
+  async getStatus(sessionKeyId) {
+    return this.request("POST", "/api/v1/ai/session-keys/status", {
+      session_key_id: sessionKeyId
+    });
+  }
+  /**
+   * List all session keys for the merchant
+   * 
+   * @returns List of session keys with stats
+   * 
+   * @example
+   * ```typescript
+   * const { session_keys, stats } = await zendfi.sessionKeys.list();
+   * 
+   * console.log(`Total keys: ${stats.total_keys}`);
+   * console.log(`Active: ${stats.active_keys}`);
+   * 
+   * session_keys.forEach(key => {
+   *   console.log(`${key.session_key_id}: $${key.remaining_usdc} remaining`);
+   * });
+   * ```
+   */
+  async list() {
+    return this.request("GET", "/api/v1/ai/session-keys/list");
+  }
+  /**
+   * Top up a session key with additional funds
+   * 
+   * Returns a transaction that the user must sign to add funds.
+   * 
+   * @param sessionKeyId - UUID of the session key
+   * @param request - Top-up configuration
+   * @returns Top-up transaction to sign
+   * 
+   * @example
+   * ```typescript
+   * const topUp = await zendfi.sessionKeys.topUp(sessionKeyId, {
+   *   user_wallet: 'Hx7B...abc',
+   *   amount_usdc: 50,
+   *   device_fingerprint: deviceFingerprint,
+   * });
+   * 
+   * console.log(`Adding $${topUp.added_amount}`);
+   * console.log(`New limit will be: $${topUp.new_limit}`);
+   * 
+   * // User signs the transaction
+   * const signedTx = await wallet.signTransaction(topUp.top_up_transaction);
+   * 
+   * // Submit it
+   * await zendfi.sessionKeys.submitTopUp(sessionKeyId, signedTx);
+   * ```
+   */
+  async topUp(sessionKeyId, request) {
+    return this.request(
+      "POST",
+      `/api/v1/ai/session-keys/${sessionKeyId}/top-up`,
+      {
+        user_wallet: request.user_wallet,
+        amount_usdc: request.amount_usdc,
+        device_fingerprint: request.device_fingerprint
+      }
+    );
+  }
+  /**
+   * Revoke a session key
+   * 
+   * Immediately deactivates the session key. Any remaining funds
+   * are refunded to the user's wallet.
+   * 
+   * @param sessionKeyId - UUID of the session key
+   * @returns Revocation result with optional refund details
+   * 
+   * @example
+   * ```typescript
+   * const result = await zendfi.sessionKeys.revoke(sessionKeyId);
+   * 
+   * console.log('Session key revoked');
+   * if (result.refund?.refunded) {
+   *   console.log(`Refunded: ${result.refund.transaction_signature}`);
+   * }
+   * ```
+   */
+  async revoke(sessionKeyId) {
+    return this.request("POST", "/api/v1/ai/session-keys/revoke", {
+      session_key_id: sessionKeyId
+    });
+  }
+};
+
 // src/client.ts
 var ZendFiClient = class {
   config;
@@ -1422,6 +1751,38 @@ var ZendFiClient = class {
    * ```
    */
   smart;
+  /**
+   * Session Keys API - On-chain funded session keys with PKP identity
+   * 
+   * Session keys are pre-funded wallets with spending limits that enable
+   * AI agents to make autonomous payments without user signatures.
+   * 
+   * The flow:
+   * 1. Create a session key (user approves spending limit)
+   * 2. User signs the approval transaction (one-time)
+   * 3. Agent can now make payments up to the limit
+   * 
+   * @example
+   * ```typescript
+   * // Create session key
+   * const key = await zendfi.sessionKeys.create({
+   *   agent_id: 'shopping-bot',
+   *   user_wallet: 'Hx7B...abc',
+   *   max_amount: 100,
+   *   expiry_hours: 24,
+   * });
+   * 
+   * // User signs the approval
+   * await zendfi.sessionKeys.submitApproval(key.session_key_id, {
+   *   signed_transaction: signedTx,
+   * });
+   * 
+   * // Check status
+   * const status = await zendfi.sessionKeys.getStatus(key.session_key_id);
+   * console.log(`Remaining: $${status.remaining_amount}`);
+   * ```
+   */
+  sessionKeys;
   constructor(options) {
     this.config = ConfigLoader.load(options);
     ConfigLoader.validateApiKey(this.config.apiKey);
@@ -1432,6 +1793,7 @@ var ZendFiClient = class {
     this.pricing = new PricingAPI(boundRequest);
     this.autonomy = new AutonomyAPI(boundRequest);
     this.smart = new SmartPaymentsAPI(boundRequest);
+    this.sessionKeys = new SessionKeysAPI(boundRequest);
     if (this.config.environment === "development" || this.config.debug) {
       console.log(
         `\u2713 ZendFi SDK initialized in ${this.config.mode} mode (${this.config.mode === "test" ? "devnet" : "mainnet"})`
@@ -3224,6 +3586,7 @@ function decodeSignatureFromLit(result) {
   RecoveryQRGenerator,
   SPENDING_LIMIT_ACTION_CID,
   SessionKeyCrypto,
+  SessionKeysAPI,
   SmartPaymentsAPI,
   ValidationError,
   WebhookError,