@mixrpay/agent-sdk 0.4.1 → 0.6.0

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 = {
@@ -353,6 +415,9 @@ async function createSessionAuthPayload(sessionKey) {
   };
 }
 
+// src/agent-wallet.ts
+var import_accounts2 = require("viem/accounts");
+
 // src/x402.ts
 async function parse402Response(response) {
   let paymentData = null;
@@ -442,7 +507,7 @@ function getAmountUsd(requirements) {
 }
 
 // src/agent-wallet.ts
-var SDK_VERSION = "0.4.1";
+var SDK_VERSION = "0.6.0";
 var DEFAULT_BASE_URL = process.env.MIXRPAY_BASE_URL || "https://www.mixrpay.com";
 var DEFAULT_TIMEOUT = 3e4;
 var NETWORKS = {
@@ -586,6 +651,237 @@ var AgentWallet = class {
     }
   }
   // ===========================================================================
+  // Static Agent Registration Methods
+  // ===========================================================================
+  /**
+   * Register a new agent with MixrPay.
+   * 
+   * This creates a Privy-managed embedded wallet for the agent's payments.
+   * The agent proves ownership of their external wallet by signing a challenge.
+   * 
+   * @param options - Registration options including the private key
+   * @returns Registration result with deposit address
+   * @throws {MixrPayError} If registration fails
+   * 
+   * @example
+   * ```typescript
+   * const { depositAddress, userId } = await AgentWallet.register({
+   *   privateKey: process.env.AGENT_WALLET_KEY as `0x${string}`,
+   *   name: 'My Trading Agent',
+   * });
+   * 
+   * console.log(`Fund your agent at: ${depositAddress}`);
+   * ```
+   */
+  static async register(options) {
+    const { privateKey, name } = 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=register`
+    );
+    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 registerResponse = await fetch(`${baseUrl}/api/v1/agent/register`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        challenge,
+        external_wallet: walletAddress,
+        signature,
+        name
+      })
+    });
+    if (!registerResponse.ok) {
+      const error = await registerResponse.json().catch(() => ({}));
+      throw new MixrPayError(error.error || `Registration failed: ${registerResponse.status}`);
+    }
+    const data = await registerResponse.json();
+    return {
+      userId: data.user_id,
+      depositAddress: data.deposit_address
+    };
+  }
+  /**
+   * Get a session key for an already-registered agent.
+   * 
+   * Session keys allow the agent to make payments within the specified limits.
+   * The private key is returned ONCE - store it securely!
+   * 
+   * @param options - Session key options
+   * @returns Session key result with the sk_live_ format key
+   * @throws {MixrPayError} If session key creation fails
+   * 
+   * @example
+   * ```typescript
+   * const result = await AgentWallet.getSessionKey({
+   *   privateKey: process.env.AGENT_WALLET_KEY as `0x${string}`,
+   *   spendingLimitUsd: 100,
+   *   durationDays: 30,
+   * });
+   * 
+   * // Store this securely - it's your payment key!
+   * console.log(`Session key: ${result.sessionKey}`);
+   * 
+   * // Use it to create an AgentWallet
+   * const wallet = new AgentWallet({ sessionKey: result.sessionKey });
+   * ```
+   */
+  static async getSessionKey(options) {
+    const { privateKey, spendingLimitUsd, maxPerTxUsd, maxDailyUsd, durationDays } = 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=session-key`
+    );
+    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 sessionKeyResponse = await fetch(`${baseUrl}/api/v1/agent/session-key`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        challenge,
+        external_wallet: walletAddress,
+        signature,
+        spending_limit_usd: spendingLimitUsd,
+        max_per_tx_usd: maxPerTxUsd,
+        max_daily_usd: maxDailyUsd,
+        duration_days: durationDays
+      })
+    });
+    if (!sessionKeyResponse.ok) {
+      const error = await sessionKeyResponse.json().catch(() => ({}));
+      throw new MixrPayError(error.error || `Session key creation failed: ${sessionKeyResponse.status}`);
+    }
+    const data = await sessionKeyResponse.json();
+    return {
+      sessionKey: data.session_key,
+      address: data.address,
+      sessionKeyId: data.session_key_id,
+      expiresAt: new Date(data.expires_at),
+      limits: {
+        maxTotalUsd: data.limits.max_total_usd,
+        maxPerTxUsd: data.limits.max_per_tx_usd,
+        maxDailyUsd: data.limits.max_daily_usd
+      }
+    };
+  }
+  /**
+   * Get the status of a registered agent.
+   * 
+   * Returns balance, active sessions, and spending information.
+   * 
+   * @param options - Status options
+   * @returns Agent status
+   * @throws {MixrPayError} If status fetch fails
+   * 
+   * @example
+   * ```typescript
+   * const status = await AgentWallet.getStatus({
+   *   privateKey: process.env.AGENT_WALLET_KEY as `0x${string}`,
+   * });
+   * 
+   * console.log(`Balance: $${status.balanceUsd}`);
+   * console.log(`Active sessions: ${status.activeSessions.length}`);
+   * ```
+   */
+  static async getStatus(options) {
+    const { privateKey } = 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=status`
+    );
+    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 statusResponse = await fetch(
+      `${baseUrl}/api/v1/agent/status?challenge=${challenge}&external_wallet=${walletAddress}&signature=${encodeURIComponent(signature)}`
+    );
+    if (!statusResponse.ok) {
+      const error = await statusResponse.json().catch(() => ({}));
+      throw new MixrPayError(error.error || `Failed to get status: ${statusResponse.status}`);
+    }
+    const data = await statusResponse.json();
+    return {
+      depositAddress: data.deposit_address,
+      balanceUsd: data.balance_usd,
+      activeSessions: data.active_sessions.map((s) => ({
+        id: s.id,
+        expiresAt: new Date(s.expires_at),
+        totalSpentUsd: s.total_spent_usd,
+        remainingUsd: s.remaining_usd,
+        maxTotalUsd: s.max_total_usd
+      })),
+      totalSpentUsd: data.total_spent_usd
+    };
+  }
+  /**
+   * Revoke a session key.
+   * 
+   * After revocation, the session key can no longer be used for payments.
+   * 
+   * @param options - Revoke options
+   * @returns true if revoked successfully
+   * @throws {MixrPayError} If revocation fails
+   * 
+   * @example
+   * ```typescript
+   * const success = await AgentWallet.revokeSessionKey({
+   *   privateKey: process.env.AGENT_WALLET_KEY as `0x${string}`,
+   *   sessionKeyId: 'session-key-uuid',
+   * });
+   * 
+   * if (success) {
+   *   console.log('Session key revoked');
+   * }
+   * ```
+   */
+  static async revokeSessionKey(options) {
+    const { privateKey, sessionKeyId } = 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=revoke`
+    );
+    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 revokeResponse = await fetch(`${baseUrl}/api/v1/agent/session-key/revoke`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        challenge,
+        external_wallet: walletAddress,
+        signature,
+        session_key_id: sessionKeyId
+      })
+    });
+    if (!revokeResponse.ok) {
+      const error = await revokeResponse.json().catch(() => ({}));
+      throw new MixrPayError(error.error || `Revocation failed: ${revokeResponse.status}`);
+    }
+    return true;
+  }
+  // ===========================================================================
   // Core Methods
   // ===========================================================================
   /**
@@ -623,6 +919,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 {
@@ -633,7 +931,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) {
@@ -645,10 +943,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);
@@ -704,7 +1019,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;
@@ -803,6 +1120,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.
    * 
@@ -943,56 +1290,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.");
+        }
+      }
+      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 (info.expiresAt && info.expiresAt < /* @__PURE__ */ new Date()) {
-        checks.sessionKeyValid = false;
-        issues.push(`Session key expired on ${info.expiresAt.toISOString()}`);
+      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
     };
   }
   /**
@@ -1401,7 +1792,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;
@@ -1600,7 +1993,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;
@@ -1717,7 +2111,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;
@@ -1809,7 +2204,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;
@@ -1985,7 +2381,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;
@@ -2016,5 +2413,7 @@ Timestamp: ${timestamp}`;
   SessionNotFoundError,
   SessionRevokedError,
   SpendingLimitExceededError,
+  X402ProtocolError,
+  getErrorMessage,
   isMixrPayError
 });