@clawback/sdk 1.0.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawback/sdk",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "SDK for Clawback - on-chain escrow payments for AI agents on Solana",
   "main": "src/index.js",
   "type": "module",

package/src/index.js

@@ -502,6 +502,169 @@ export class ClawbackClient {
     });
     return response.data;
   }
+
+  /**
+   * Set up webhooks with human-readable threshold
+   * @param {string} url - Webhook URL
+   * @param {Array<string>} events - Events to subscribe to (defaults to all payment events)
+   * @param {Object} options - Options
+   * @param {number} options.lowBalanceThreshold - Low balance threshold in human-readable form (e.g., 5 for 5 USDC)
+   * @param {string} options.lowBalanceToken - Token for threshold (default: USDC)
+   * @returns {Promise<Object>}
+   *
+   * @example
+   * // Subscribe to all events, alert when USDC balance < 5
+   * await clawback.setupWebhooks('https://myagent.com/webhook', null, {
+   *   lowBalanceThreshold: 5,
+   *   lowBalanceToken: 'USDC'
+   * });
+   */
+  async setupWebhooks(url, events = null, options = {}) {
+    const defaultEvents = [
+      'payment.created',
+      'payment.accepted',
+      'payment.released',
+      'payment.disputed',
+      'balance.low'
+    ];
+
+    const threshold = options.lowBalanceThreshold
+      ? this.toBaseUnits(options.lowBalanceThreshold, options.lowBalanceToken || 'USDC')
+      : 0;
+
+    return this.setWebhook(url, events || defaultEvents, threshold);
+  }
+
+  // =========================================================================
+  // Funding Helpers
+  // =========================================================================
+
+  /**
+   * Get funding instructions for your wallet
+   * @returns {Promise<{walletAddress: string, network: string, usdcMint: string, instructions: string}>}
+   */
+  async getFundingInstructions() {
+    const walletAddress = await this.getWalletAddress();
+
+    return {
+      walletAddress,
+      network: 'Solana Mainnet',
+      usdcMint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+      instructions: `
+ACTION REQUIRED: Fund your Clawback wallet
+
+Your Clawback wallet needs funding to make payments.
+
+Wallet Address: ${walletAddress}
+Network: Solana Mainnet
+
+Send USDC or SOL to this address.
+USDC Contract: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
+
+You can send funds from any Solana wallet (Phantom, Solflare, etc.)
+or from a centralized exchange that supports Solana withdrawals.
+`.trim()
+    };
+  }
+
+  /**
+   * Check balance and return funding instructions if needed
+   * @param {Object} thresholds - Minimum balance thresholds
+   * @param {number} thresholds.usdc - Minimum USDC balance (default: 1)
+   * @param {number} thresholds.sol - Minimum SOL balance (default: 0.01)
+   * @returns {Promise<{needsFunding: boolean, balance: Object, fundingInstructions: string|null}>}
+   *
+   * @example
+   * const status = await clawback.checkFundingStatus({ usdc: 5, sol: 0.1 });
+   * if (status.needsFunding) {
+   *   // Notify human with status.fundingInstructions
+   *   console.log(status.fundingInstructions);
+   * }
+   */
+  async checkFundingStatus(thresholds = {}) {
+    const minUsdc = thresholds.usdc ?? 1;
+    const minSol = thresholds.sol ?? 0.01;
+
+    const balance = await this.getBalance();
+    const needsFunding = balance.usdc < minUsdc && balance.sol < minSol;
+
+    let fundingInstructions = null;
+    if (needsFunding) {
+      const info = await this.getFundingInstructions();
+      fundingInstructions = info.instructions;
+    }
+
+    return {
+      needsFunding,
+      balance,
+      fundingInstructions,
+    };
+  }
+
+  /**
+   * Initialize agent with recommended setup (webhooks + funding check)
+   * Returns a status object and any actions needed from the human operator
+   *
+   * @param {Object} options - Setup options
+   * @param {string} options.webhookUrl - URL to receive webhook notifications
+   * @param {number} options.lowBalanceThreshold - USDC amount to trigger low balance alert (default: 5)
+   * @param {number} options.minUsdc - Minimum USDC to consider "funded" (default: 1)
+   * @param {number} options.minSol - Minimum SOL to consider "funded" (default: 0.01)
+   * @returns {Promise<{ready: boolean, balance: Object, webhooksConfigured: boolean, humanActionRequired: string|null}>}
+   *
+   * @example
+   * const status = await clawback.initialize({
+   *   webhookUrl: 'https://myagent.com/clawback-webhook',
+   *   lowBalanceThreshold: 10
+   * });
+   *
+   * if (!status.ready) {
+   *   // Send status.humanActionRequired to your human operator
+   *   notifyHuman(status.humanActionRequired);
+   * }
+   */
+  async initialize(options = {}) {
+    const {
+      webhookUrl,
+      lowBalanceThreshold = 5,
+      minUsdc = 1,
+      minSol = 0.01,
+    } = options;
+
+    // Ensure registered
+    await this._ensureRegistered();
+
+    // Set up webhooks if URL provided
+    let webhooksConfigured = false;
+    if (webhookUrl) {
+      try {
+        await this.setupWebhooks(webhookUrl, null, {
+          lowBalanceThreshold,
+          lowBalanceToken: 'USDC'
+        });
+        webhooksConfigured = true;
+      } catch (e) {
+        console.error('Failed to configure webhooks:', e.message);
+      }
+    }
+
+    // Check funding status
+    const fundingStatus = await this.checkFundingStatus({ usdc: minUsdc, sol: minSol });
+
+    const ready = !fundingStatus.needsFunding;
+    let humanActionRequired = null;
+
+    if (fundingStatus.needsFunding) {
+      humanActionRequired = fundingStatus.fundingInstructions;
+    }
+
+    return {
+      ready,
+      balance: fundingStatus.balance,
+      webhooksConfigured,
+      humanActionRequired,
+    };
+  }
 }
 
 // Export errors for type checking