@mixrpay/agent-sdk 0.6.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

@@ -507,7 +507,7 @@ function getAmountUsd(requirements) {
 }
 
 // src/agent-wallet.ts
-var SDK_VERSION = "0.6.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 = {
@@ -699,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 {
@@ -707,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.
    * 
@@ -881,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
   // ===========================================================================

package/dist/index.d.cts

@@ -378,7 +378,7 @@ interface SessionStats {
  */
 
 /** Current SDK version */
-declare const SDK_VERSION = "0.6.0";
+declare const SDK_VERSION = "0.6.1";
 /** Supported networks */
 declare const NETWORKS: {
     readonly BASE_MAINNET: {
@@ -487,6 +487,28 @@ interface AgentRevokeSessionKeyOptions {
     /** MixrPay API base URL (default: https://www.mixrpay.com) */
     baseUrl?: string;
 }
+/**
+ * Options for withdrawing funds
+ */
+interface AgentWithdrawOptions {
+    /** The agent's external wallet private key (used for signing, NOT transmitted) */
+    privateKey: `0x${string}`;
+    /** Amount to withdraw in USD */
+    amountUsd: number;
+    /** MixrPay API base URL (default: https://www.mixrpay.com) */
+    baseUrl?: string;
+}
+/**
+ * Result from withdrawal
+ */
+interface AgentWithdrawResult {
+    /** On-chain transaction hash */
+    txHash: string;
+    /** Amount withdrawn in USD */
+    amountUsd: number;
+    /** Remaining balance after withdrawal */
+    remainingBalanceUsd: number;
+}
 type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'none';
 /**
  * A wallet wrapper for AI agents that handles x402 payments automatically.
@@ -589,6 +611,29 @@ declare class AgentWallet {
      * ```
      */
     static register(options: AgentRegisterOptions): Promise<AgentRegisterResult>;
+    /**
+     * 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 checkServerHealth(baseUrl?: string): Promise<{
+        healthy: boolean;
+        database: string;
+        agentRegistrationAvailable: boolean;
+        privyConfigured: boolean;
+        error?: string;
+    }>;
     /**
      * Get a session key for an already-registered agent.
      *
@@ -657,6 +702,31 @@ declare class AgentWallet {
      * ```
      */
     static revokeSessionKey(options: AgentRevokeSessionKeyOptions): Promise<boolean>;
+    /**
+     * 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 withdraw(options: AgentWithdrawOptions): Promise<AgentWithdrawResult>;
     /**
      * Make an HTTP request, automatically handling x402 payment if required.
      *

package/dist/index.d.ts

@@ -378,7 +378,7 @@ interface SessionStats {
  */
 
 /** Current SDK version */
-declare const SDK_VERSION = "0.6.0";
+declare const SDK_VERSION = "0.6.1";
 /** Supported networks */
 declare const NETWORKS: {
     readonly BASE_MAINNET: {
@@ -487,6 +487,28 @@ interface AgentRevokeSessionKeyOptions {
     /** MixrPay API base URL (default: https://www.mixrpay.com) */
     baseUrl?: string;
 }
+/**
+ * Options for withdrawing funds
+ */
+interface AgentWithdrawOptions {
+    /** The agent's external wallet private key (used for signing, NOT transmitted) */
+    privateKey: `0x${string}`;
+    /** Amount to withdraw in USD */
+    amountUsd: number;
+    /** MixrPay API base URL (default: https://www.mixrpay.com) */
+    baseUrl?: string;
+}
+/**
+ * Result from withdrawal
+ */
+interface AgentWithdrawResult {
+    /** On-chain transaction hash */
+    txHash: string;
+    /** Amount withdrawn in USD */
+    amountUsd: number;
+    /** Remaining balance after withdrawal */
+    remainingBalanceUsd: number;
+}
 type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'none';
 /**
  * A wallet wrapper for AI agents that handles x402 payments automatically.
@@ -589,6 +611,29 @@ declare class AgentWallet {
      * ```
      */
     static register(options: AgentRegisterOptions): Promise<AgentRegisterResult>;
+    /**
+     * 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 checkServerHealth(baseUrl?: string): Promise<{
+        healthy: boolean;
+        database: string;
+        agentRegistrationAvailable: boolean;
+        privyConfigured: boolean;
+        error?: string;
+    }>;
     /**
      * Get a session key for an already-registered agent.
      *
@@ -657,6 +702,31 @@ declare class AgentWallet {
      * ```
      */
     static revokeSessionKey(options: AgentRevokeSessionKeyOptions): Promise<boolean>;
+    /**
+     * 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 withdraw(options: AgentWithdrawOptions): Promise<AgentWithdrawResult>;
     /**
      * Make an HTTP request, automatically handling x402 payment if required.
      *

package/dist/index.js

@@ -471,7 +471,7 @@ function getAmountUsd(requirements) {
 }
 
 // src/agent-wallet.ts
-var SDK_VERSION = "0.6.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 = {
@@ -663,7 +663,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 {
@@ -671,6 +683,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.
    * 
@@ -845,6 +903,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 = privateKeyToAccount2(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 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
   // ===========================================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mixrpay/agent-sdk",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "MixrPay Agent SDK - Enable AI agents to make x402 payments with session keys",
   "type": "module",
   "main": "./dist/index.js",