@mixrpay/agent-sdk 0.5.0 → 0.6.1

package/README.md

@@ -41,9 +41,13 @@ await wallet.fetch(url, options);
 // Get wallet balance
 const balance = await wallet.getBalance();
 
-// Track payments
-const payments = wallet.getPaymentHistory();
-const total = wallet.getTotalSpent();
+// Pre-flight balance check
+const check = await wallet.canAfford(0.50);
+if (check.canAfford) { /* proceed */ }
+
+// Run diagnostics
+const diag = await wallet.runDiagnostics();
+console.log(diag.recommendations);
 ```
 
 ## Configuration
@@ -63,6 +67,7 @@ import {
   AgentWallet,
   InsufficientBalanceError,
   SessionLimitExceededError,
+  MixrPayError,
 } from '@mixrpay/agent-sdk';
 
 try {
@@ -71,12 +76,27 @@ try {
   if (error instanceof InsufficientBalanceError) {
     console.log(`Need $${error.required}, have $${error.available}`);
   }
+  
+  // Check if error is retryable
+  if (error instanceof MixrPayError && error.isRetryable()) {
+    const delay = error.retryAfterMs || 1000;
+    await sleep(delay);
+    return retry();
+  }
 }
 ```
 
+## What's New in v0.6.0
+
+- `canAfford(amountUsd)` - Pre-flight balance check
+- `isRetryable()` on all errors - Determine if operation should be retried
+- `retryAfterMs` on errors - Suggested retry delay
+- Enhanced `runDiagnostics()` - Session limits, latency, recommendations
+- `requestId` and `correlationId` in payment events
+
 ## Documentation
 
-[mixrpay.com/build](https://www.mixrpay.com/build)
+[mixrpay.com/docs](https://www.mixrpay.com/docs)
 
 ## License
 

package/dist/index.cjs

@@ -32,6 +32,8 @@ __export(index_exports, {
   SessionNotFoundError: () => SessionNotFoundError,
   SessionRevokedError: () => SessionRevokedError,
   SpendingLimitExceededError: () => SpendingLimitExceededError,
+  X402ProtocolError: () => X402ProtocolError,
+  getErrorMessage: () => getErrorMessage,
   isMixrPayError: () => isMixrPayError
 });
 module.exports = __toCommonJS(index_exports);
@@ -43,14 +45,43 @@ var import_accounts = require("viem/accounts");
 var MixrPayError = class extends Error {
   /** Error code for programmatic handling */
   code;
-  constructor(message, code = "MIXRPAY_ERROR") {
+  /** Optional hint for how long to wait before retrying (in milliseconds) */
+  retryAfterMs;
+  constructor(message, code = "MIXRPAY_ERROR", retryAfterMs) {
     super(message);
     this.name = "MixrPayError";
     this.code = code;
+    this.retryAfterMs = retryAfterMs;
     if (Error.captureStackTrace) {
       Error.captureStackTrace(this, this.constructor);
     }
   }
+  /**
+   * Check if this error is retryable.
+   * 
+   * Returns true if the operation might succeed on retry (e.g., transient network issues).
+   * Returns false if the error requires user action to resolve (e.g., insufficient balance).
+   * 
+   * @returns true if the operation should be retried, false otherwise
+   * 
+   * @example
+   * ```typescript
+   * try {
+   *   await wallet.fetch(...);
+   * } catch (error) {
+   *   if (error instanceof MixrPayError && error.isRetryable()) {
+   *     // Retry the operation
+   *     await retry();
+   *   } else {
+   *     // Handle permanent failure
+   *     throw error;
+   *   }
+   * }
+   * ```
+   */
+  isRetryable() {
+    return false;
+  }
 };
 var InsufficientBalanceError = class extends MixrPayError {
   /** Amount required for the payment in USD */
@@ -108,6 +139,14 @@ var SpendingLimitExceededError = class extends MixrPayError {
     this.limit = limit;
     this.attempted = attempted;
   }
+  /**
+   * Daily limits reset at midnight, so those are retryable (after waiting).
+   * Other limit types require user action (new session key, config change).
+   * @returns true only for daily limits
+   */
+  isRetryable() {
+    return this.limitType === "daily";
+  }
 };
 var PaymentFailedError = class extends MixrPayError {
   /** Detailed reason for the failure */
@@ -124,6 +163,13 @@ var PaymentFailedError = class extends MixrPayError {
     this.reason = reason;
     this.txHash = txHash;
   }
+  /**
+   * Payment failures are often transient (network issues, temporary server errors).
+   * @returns true - payment failures should generally be retried
+   */
+  isRetryable() {
+    return true;
+  }
 };
 var InvalidSessionKeyError = class extends MixrPayError {
   /** Detailed reason why the key is invalid */
@@ -148,6 +194,13 @@ var X402ProtocolError = class extends MixrPayError {
     this.name = "X402ProtocolError";
     this.reason = reason;
   }
+  /**
+   * Protocol errors may be caused by temporary server issues.
+   * @returns true - worth retrying in case server recovers
+   */
+  isRetryable() {
+    return true;
+  }
 };
 var SessionExpiredError = class extends MixrPayError {
   /** ID of the expired session */
@@ -215,6 +268,15 @@ var SessionRevokedError = class extends MixrPayError {
 function isMixrPayError(error) {
   return error instanceof MixrPayError;
 }
+function getErrorMessage(error) {
+  if (error instanceof MixrPayError) {
+    return error.message;
+  }
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
 
 // src/session-key.ts
 var USDC_ADDRESSES = {
@@ -445,7 +507,7 @@ function getAmountUsd(requirements) {
 }
 
 // src/agent-wallet.ts
-var SDK_VERSION = "0.5.0";
+var SDK_VERSION = "0.6.1";
 var DEFAULT_BASE_URL = process.env.MIXRPAY_BASE_URL || "https://www.mixrpay.com";
 var DEFAULT_TIMEOUT = 3e4;
 var NETWORKS = {
@@ -637,7 +699,19 @@ var AgentWallet = class {
     });
     if (!registerResponse.ok) {
       const error = await registerResponse.json().catch(() => ({}));
-      throw new MixrPayError(error.error || `Registration failed: ${registerResponse.status}`);
+      const errorMessage = error.error || `Registration failed with status ${registerResponse.status}`;
+      const requestId = error.request_id;
+      const errorCode = error.code;
+      let helpText = "";
+      if (registerResponse.status === 503) {
+        helpText = " The service may be temporarily unavailable. Please try again later.";
+      } else if (registerResponse.status === 500) {
+        helpText = " This is a server error. Please contact support with the request ID.";
+      } else if (errorCode === "MISSING_CHALLENGE" || errorCode === "MISSING_SIGNATURE") {
+        helpText = " This may indicate an SDK bug. Please update to the latest version.";
+      }
+      const fullMessage = requestId ? `${errorMessage} (request_id: ${requestId})${helpText}` : `${errorMessage}${helpText}`;
+      throw new MixrPayError(fullMessage);
     }
     const data = await registerResponse.json();
     return {
@@ -645,6 +719,52 @@ var AgentWallet = class {
       depositAddress: data.deposit_address
     };
   }
+  /**
+   * Check if the MixrPay server is properly configured for agent registration.
+   * 
+   * Use this to diagnose registration issues before attempting to register.
+   * 
+   * @param baseUrl - MixrPay API base URL (default: https://www.mixrpay.com)
+   * @returns Server health status including agent registration availability
+   * 
+   * @example
+   * ```typescript
+   * const status = await AgentWallet.checkServerHealth();
+   * if (!status.agentRegistrationAvailable) {
+   *   console.error('Agent registration is not available:', status);
+   * }
+   * ```
+   */
+  static async checkServerHealth(baseUrl) {
+    const url = (baseUrl || DEFAULT_BASE_URL).replace(/\/$/, "");
+    try {
+      const response = await fetch(`${url}/api/health/ready?details=true`);
+      if (!response.ok) {
+        return {
+          healthy: false,
+          database: "unknown",
+          agentRegistrationAvailable: false,
+          privyConfigured: false,
+          error: `Health check failed with status ${response.status}`
+        };
+      }
+      const data = await response.json();
+      return {
+        healthy: data.status === "ready",
+        database: data.database || "unknown",
+        agentRegistrationAvailable: data.services?.agentRegistration?.available ?? false,
+        privyConfigured: data.services?.privy?.configured ?? false
+      };
+    } catch (error) {
+      return {
+        healthy: false,
+        database: "unreachable",
+        agentRegistrationAvailable: false,
+        privyConfigured: false,
+        error: error instanceof Error ? error.message : "Failed to reach server"
+      };
+    }
+  }
   /**
    * Get a session key for an already-registered agent.
    * 
@@ -819,6 +939,67 @@ var AgentWallet = class {
     }
     return true;
   }
+  /**
+   * Withdraw USDC from agent's MixrPay wallet to their external wallet.
+   * 
+   * SECURITY: Withdrawals can ONLY go to the agent's own registration wallet
+   * (the wallet used during `register()`). This prevents prompt injection
+   * attacks where a compromised agent might be tricked into withdrawing
+   * to an attacker's address.
+   * 
+   * @param options - Withdrawal options
+   * @returns Withdrawal result with transaction hash
+   * @throws {MixrPayError} If withdrawal fails
+   * 
+   * @example
+   * ```typescript
+   * const result = await AgentWallet.withdraw({
+   *   privateKey: process.env.AGENT_WALLET_KEY as `0x${string}`,
+   *   amountUsd: 50.00,
+   * });
+   * 
+   * console.log(`Withdrew $${result.amountUsd}`);
+   * console.log(`Transaction: ${result.txHash}`);
+   * console.log(`Remaining balance: $${result.remainingBalanceUsd}`);
+   * ```
+   */
+  static async withdraw(options) {
+    const { privateKey, amountUsd } = options;
+    const baseUrl = (options.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, "");
+    const account = (0, import_accounts2.privateKeyToAccount)(privateKey);
+    const walletAddress = account.address;
+    const challengeResponse = await fetch(
+      `${baseUrl}/api/v1/agent/challenge?wallet=${walletAddress}&action=withdraw`
+    );
+    if (!challengeResponse.ok) {
+      const error = await challengeResponse.json().catch(() => ({}));
+      throw new MixrPayError(error.error || `Failed to get challenge: ${challengeResponse.status}`);
+    }
+    const { challenge, message } = await challengeResponse.json();
+    const signature = await (0, import_accounts2.signMessage)({ message, privateKey });
+    const withdrawResponse = await fetch(`${baseUrl}/api/v1/agent/withdraw`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        challenge,
+        external_wallet: walletAddress,
+        signature,
+        to_address: walletAddress,
+        // Always withdraw to self
+        amount_usd: amountUsd
+      })
+    });
+    if (!withdrawResponse.ok) {
+      const error = await withdrawResponse.json().catch(() => ({}));
+      throw new MixrPayError(error.error || `Withdrawal failed: ${withdrawResponse.status}`);
+    }
+    const data = await withdrawResponse.json();
+    return {
+      txHash: data.tx_hash,
+      amountUsd: data.amount_usd,
+      remainingBalanceUsd: data.remaining_balance_usd
+    };
+  }
   // ===========================================================================
   // Core Methods
   // ===========================================================================
@@ -857,6 +1038,8 @@ var AgentWallet = class {
    */
   async fetch(url, init) {
     this.logger.debug(`Fetching ${init?.method || "GET"} ${url}`);
+    const requestId = crypto.randomUUID();
+    const correlationId = this.extractCorrelationId(init?.headers);
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
     try {
@@ -867,7 +1050,7 @@ var AgentWallet = class {
       this.logger.debug(`Initial response: ${response.status}`);
       if (response.status === 402) {
         this.logger.info(`Payment required for ${url}`);
-        response = await this.handlePaymentRequired(url, init, response);
+        response = await this.handlePaymentRequired(url, init, response, requestId, correlationId);
       }
       return response;
     } catch (error) {
@@ -879,10 +1062,27 @@ var AgentWallet = class {
       clearTimeout(timeoutId);
     }
   }
+  /**
+   * Extract correlation ID from request headers.
+   */
+  extractCorrelationId(headers) {
+    if (!headers) return void 0;
+    if (headers instanceof Headers) {
+      return headers.get("X-Correlation-Id") || headers.get("x-correlation-id") || void 0;
+    }
+    if (Array.isArray(headers)) {
+      const entry = headers.find(
+        ([key]) => key.toLowerCase() === "x-correlation-id"
+      );
+      return entry ? entry[1] : void 0;
+    }
+    const record = headers;
+    return record["X-Correlation-Id"] || record["x-correlation-id"] || void 0;
+  }
   /**
    * Handle a 402 Payment Required response.
    */
-  async handlePaymentRequired(url, init, response) {
+  async handlePaymentRequired(url, init, response, requestId, correlationId) {
     let requirements;
     try {
       requirements = await parse402Response(response);
@@ -938,7 +1138,9 @@ var AgentWallet = class {
         txHash: retryResponse.headers.get("X-Payment-TxHash"),
         timestamp: /* @__PURE__ */ new Date(),
         description: requirements.description,
-        url
+        url,
+        requestId,
+        correlationId
       };
       this.payments.push(payment);
       this.totalSpentUsd += amountUsd;
@@ -1037,6 +1239,36 @@ var AgentWallet = class {
     this.logger.debug("Using estimated balance based on tracking");
     return Math.max(0, 100 - this.totalSpentUsd);
   }
+  /**
+   * Check if the wallet can afford a specific amount.
+   * 
+   * This is a convenience method to check balance before making a request
+   * when you know the expected cost.
+   * 
+   * @param amountUsd - Amount to check in USD
+   * @returns Object with affordability information
+   * 
+   * @example
+   * ```typescript
+   * const check = await wallet.canAfford(5.00);
+   * if (check.canAfford) {
+   *   console.log(`Can afford! Will have $${check.remainingAfter.toFixed(2)} left`);
+   *   await wallet.fetch(url);
+   * } else {
+   *   console.log(`Need $${check.shortfall.toFixed(2)} more`);
+   * }
+   * ```
+   */
+  async canAfford(amountUsd) {
+    const balance = await this.getBalance();
+    const canAfford = balance >= amountUsd;
+    return {
+      canAfford,
+      balance,
+      shortfall: canAfford ? 0 : amountUsd - balance,
+      remainingAfter: canAfford ? balance - amountUsd : 0
+    };
+  }
   /**
    * Get information about the session key.
    * 
@@ -1177,56 +1409,100 @@ var AgentWallet = class {
   async runDiagnostics() {
     this.logger.info("Running diagnostics...");
     const issues = [];
+    const recommendations = [];
     const checks = {};
+    let latencyMs;
+    let sessionLimits;
     checks.sessionKeyFormat = true;
     try {
+      const startTime = Date.now();
       const response = await fetch(`${this.baseUrl}/health`, {
         method: "GET",
         signal: AbortSignal.timeout(5e3)
       });
+      latencyMs = Date.now() - startTime;
       checks.apiConnectivity = response.ok;
       if (!response.ok) {
         issues.push(`API server returned ${response.status}. Check baseUrl configuration.`);
+        recommendations.push("Verify the baseUrl configuration points to a valid MixrPay server.");
+      }
+      if (latencyMs > 2e3) {
+        issues.push(`High API latency: ${latencyMs}ms. This may cause timeouts.`);
+        recommendations.push("Consider using a server closer to your region or check network connectivity.");
       }
     } catch {
       checks.apiConnectivity = false;
       issues.push("Cannot connect to MixrPay API. Check your network connection and baseUrl.");
+      recommendations.push("Verify network connectivity and that the MixrPay server is running.");
     }
     try {
       const info = await this.getSessionKeyInfo(true);
       checks.sessionKeyValid = info.isValid;
       if (!info.isValid) {
         issues.push("Session key is invalid or has been revoked.");
+        recommendations.push("Request a new session key from the wallet owner or create one at /wallet/sessions.");
+      }
+      const now = /* @__PURE__ */ new Date();
+      let expiresInHours = null;
+      if (info.expiresAt) {
+        expiresInHours = (info.expiresAt.getTime() - now.getTime()) / (1e3 * 60 * 60);
+        if (info.expiresAt < now) {
+          checks.sessionKeyValid = false;
+          issues.push(`Session key expired on ${info.expiresAt.toISOString()}`);
+          recommendations.push("Create a new session key to continue making payments.");
+        } else if (expiresInHours < 24) {
+          issues.push(`Session key expires in ${expiresInHours.toFixed(1)} hours.`);
+          recommendations.push("Consider creating a new session key before the current one expires.");
+        }
       }
-      if (info.expiresAt && info.expiresAt < /* @__PURE__ */ new Date()) {
-        checks.sessionKeyValid = false;
-        issues.push(`Session key expired on ${info.expiresAt.toISOString()}`);
+      const stats = await this.getSpendingStats();
+      sessionLimits = {
+        remainingDailyUsd: stats.remainingDailyUsd,
+        remainingTotalUsd: stats.remainingTotalUsd,
+        expiresAt: info.expiresAt,
+        expiresInHours
+      };
+      if (stats.remainingDailyUsd !== null && stats.remainingDailyUsd < 1) {
+        issues.push(`Daily limit nearly exhausted: $${stats.remainingDailyUsd.toFixed(2)} remaining.`);
+        recommendations.push("Wait until tomorrow for daily limit to reset, or request a higher daily limit.");
+      }
+      if (stats.remainingTotalUsd !== null && stats.remainingTotalUsd < 1) {
+        issues.push(`Total limit nearly exhausted: $${stats.remainingTotalUsd.toFixed(2)} remaining.`);
+        recommendations.push("Request a new session key with a higher total limit.");
       }
     } catch {
       checks.sessionKeyValid = false;
       issues.push("Could not verify session key validity.");
+      recommendations.push("Check network connectivity and try again.");
     }
+    let balance = 0;
     try {
-      const balance = await this.getBalance();
+      balance = await this.getBalance();
       checks.hasBalance = balance > 0;
       if (balance <= 0) {
         issues.push("Wallet has no USDC balance. Top up at your MixrPay server /wallet");
+        recommendations.push("Deposit USDC to your wallet address to enable payments.");
       } else if (balance < 1) {
         issues.push(`Low balance: $${balance.toFixed(2)}. Consider topping up.`);
+        recommendations.push("Top up your wallet balance to avoid payment failures.");
       }
     } catch {
       checks.hasBalance = false;
       issues.push("Could not fetch wallet balance.");
+      recommendations.push("Check network connectivity and try again.");
     }
     const healthy = issues.length === 0;
-    this.logger.info("Diagnostics complete:", { healthy, issues });
+    this.logger.info("Diagnostics complete:", { healthy, issues, latencyMs });
     return {
       healthy,
       issues,
       checks,
       sdkVersion: SDK_VERSION,
       network: this.getNetwork().name,
-      walletAddress: this.walletAddress
+      walletAddress: this.walletAddress,
+      sessionLimits,
+      latencyMs,
+      recommendations
     };
   }
   /**
@@ -1635,7 +1911,9 @@ var AgentWallet = class {
           txHash: response.headers.get("X-Payment-TxHash"),
           timestamp: /* @__PURE__ */ new Date(),
           description: feature || "API call",
-          url
+          url,
+          requestId: crypto.randomUUID(),
+          correlationId: this.extractCorrelationId(customHeaders)
         };
         this.payments.push(payment);
         this.totalSpentUsd += amountUsd;
@@ -1834,7 +2112,8 @@ Timestamp: ${timestamp}`;
         txHash: mixrpay.txHash,
         timestamp: /* @__PURE__ */ new Date(),
         description: `MCP: ${toolName}`,
-        url: `${this.baseUrl}/api/mcp`
+        url: `${this.baseUrl}/api/mcp`,
+        requestId: crypto.randomUUID()
       };
       this.payments.push(payment);
       this.totalSpentUsd += mixrpay.chargedUsd;
@@ -1951,7 +2230,8 @@ Timestamp: ${timestamp}`;
           txHash: data.tx_hash,
           timestamp: /* @__PURE__ */ new Date(),
           description: `Agent run: ${data.run_id}`,
-          url: `${this.baseUrl}/api/v2/agent/run`
+          url: `${this.baseUrl}/api/v2/agent/run`,
+          requestId: idempotencyKey || crypto.randomUUID()
         };
         this.payments.push(payment);
         this.totalSpentUsd += data.cost.total_usd;
@@ -2043,7 +2323,8 @@ Timestamp: ${timestamp}`;
                     txHash: data.tx_hash,
                     timestamp: /* @__PURE__ */ new Date(),
                     description: `Agent run: ${data.run_id}`,
-                    url: `${this.baseUrl}/api/v2/agent/run`
+                    url: `${this.baseUrl}/api/v2/agent/run`,
+                    requestId: body.idempotency_key || crypto.randomUUID()
                   };
                   this.payments.push(payment);
                   this.totalSpentUsd += data.total_cost_usd;
@@ -2219,7 +2500,8 @@ Timestamp: ${timestamp}`;
         txHash: mixrpay.txHash,
         timestamp: /* @__PURE__ */ new Date(),
         description: `MCP: ${toolName}`,
-        url: `${this.baseUrl}/api/mcp`
+        url: `${this.baseUrl}/api/mcp`,
+        requestId: crypto.randomUUID()
       };
       this.payments.push(payment);
       this.totalSpentUsd += mixrpay.chargedUsd;
@@ -2250,5 +2532,7 @@ Timestamp: ${timestamp}`;
   SessionNotFoundError,
   SessionRevokedError,
   SpendingLimitExceededError,
+  X402ProtocolError,
+  getErrorMessage,
   isMixrPayError
 });