@mixrpay/agent-sdk 0.5.0 → 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 = {
@@ -445,7 +507,7 @@ function getAmountUsd(requirements) {
 }
 
 // src/agent-wallet.ts
-var SDK_VERSION = "0.5.0";
+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 = {
@@ -857,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 {
@@ -867,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) {
@@ -879,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);
@@ -938,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;
@@ -1037,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.
    * 
@@ -1177,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.");
+        }
       }
-      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 +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;
@@ -1834,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;
@@ -1951,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;
@@ -2043,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;
@@ -2219,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;
@@ -2250,5 +2413,7 @@ Timestamp: ${timestamp}`;
   SessionNotFoundError,
   SessionRevokedError,
   SpendingLimitExceededError,
+  X402ProtocolError,
+  getErrorMessage,
   isMixrPayError
 });

package/dist/index.d.cts

@@ -121,6 +121,10 @@ interface PaymentEvent {
     description?: string;
     /** URL that triggered the payment */
     url?: string;
+    /** Auto-generated unique ID for this request */
+    requestId: string;
+    /** User-provided correlation ID (from X-Correlation-Id header if provided) */
+    correlationId?: string;
 }
 /**
  * Information about a session key.
@@ -195,6 +199,21 @@ interface DiagnosticsResult {
     network: string;
     /** Wallet address */
     walletAddress: string;
+    /** Session key limit info (if available) */
+    sessionLimits?: {
+        /** Remaining daily limit in USD (null if no limit) */
+        remainingDailyUsd: number | null;
+        /** Remaining total limit in USD (null if no limit) */
+        remainingTotalUsd: number | null;
+        /** When the session key expires (null if never) */
+        expiresAt: Date | null;
+        /** Hours until expiration (null if never) */
+        expiresInHours: number | null;
+    };
+    /** Network latency to API in milliseconds */
+    latencyMs?: number;
+    /** Actionable recommendations based on issues found */
+    recommendations: string[];
 }
 /**
  * Options for creating a session authorization with a MixrPay merchant.
@@ -359,7 +378,7 @@ interface SessionStats {
  */
 
 /** Current SDK version */
-declare const SDK_VERSION = "0.5.0";
+declare const SDK_VERSION = "0.6.0";
 /** Supported networks */
 declare const NETWORKS: {
     readonly BASE_MAINNET: {
@@ -672,6 +691,10 @@ declare class AgentWallet {
      * ```
      */
     fetch(url: string, init?: RequestInit): Promise<Response>;
+    /**
+     * Extract correlation ID from request headers.
+     */
+    private extractCorrelationId;
     /**
      * Handle a 402 Payment Required response.
      */
@@ -710,6 +733,36 @@ declare class AgentWallet {
      * ```
      */
     getBalance(): Promise<number>;
+    /**
+     * 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`);
+     * }
+     * ```
+     */
+    canAfford(amountUsd: number): Promise<{
+        /** Whether the wallet can afford this amount */
+        canAfford: boolean;
+        /** Current wallet balance in USD */
+        balance: number;
+        /** Amount short (0 if can afford) */
+        shortfall: number;
+        /** Remaining after payment (0 if can't afford) */
+        remainingAfter: number;
+    }>;
     /**
      * Get information about the session key.
      *
@@ -1326,7 +1379,33 @@ interface AgentRunStatusResult {
 declare class MixrPayError extends Error {
     /** Error code for programmatic handling */
     readonly code: string;
-    constructor(message: string, code?: string);
+    /** Optional hint for how long to wait before retrying (in milliseconds) */
+    readonly retryAfterMs?: number;
+    constructor(message: string, code?: string, retryAfterMs?: number);
+    /**
+     * 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(): boolean;
 }
 /**
  * Thrown when the wallet doesn't have enough USDC for the payment.
@@ -1418,6 +1497,12 @@ declare class SpendingLimitExceededError extends MixrPayError {
     /** The amount that was attempted in USD */
     readonly attempted: number;
     constructor(limitType: string, limit: number, attempted: number);
+    /**
+     * 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(): boolean;
 }
 /**
  * Thrown when a payment transaction fails.
@@ -1449,6 +1534,11 @@ declare class PaymentFailedError extends MixrPayError {
     /** Transaction hash if the tx was submitted (for debugging) */
     readonly txHash?: string;
     constructor(reason: string, txHash?: string);
+    /**
+     * Payment failures are often transient (network issues, temporary server errors).
+     * @returns true - payment failures should generally be retried
+     */
+    isRetryable(): boolean;
 }
 /**
  * Thrown when the session key format is invalid.
@@ -1479,6 +1569,38 @@ declare class InvalidSessionKeyError extends MixrPayError {
     readonly reason: string;
     constructor(reason?: string);
 }
+/**
+ * Thrown when there's an error in x402 protocol handling.
+ *
+ * This indicates a problem with the payment protocol, usually due to:
+ * - Malformed 402 response from server
+ * - Missing required payment fields
+ * - Invalid payment parameters
+ * - Protocol version mismatch
+ *
+ * ## Resolution
+ * This is usually a server-side issue. Contact the API provider if the error persists.
+ *
+ * @example
+ * ```typescript
+ * catch (error) {
+ *   if (error instanceof X402ProtocolError) {
+ *     console.log(`Protocol error: ${error.reason}`);
+ *     // Contact API provider or check server configuration
+ *   }
+ * }
+ * ```
+ */
+declare class X402ProtocolError extends MixrPayError {
+    /** Detailed reason for the protocol error */
+    readonly reason: string;
+    constructor(reason: string);
+    /**
+     * Protocol errors may be caused by temporary server issues.
+     * @returns true - worth retrying in case server recovers
+     */
+    isRetryable(): boolean;
+}
 /**
  * Thrown when a session authorization has expired.
  *
@@ -1611,5 +1733,20 @@ declare class SessionRevokedError extends MixrPayError {
  * ```
  */
 declare function isMixrPayError(error: unknown): error is MixrPayError;
+/**
+ * Get a user-friendly error message from any error.
+ *
+ * @param error - The error to get a message from
+ * @returns A user-friendly error message
+ *
+ * @example
+ * ```typescript
+ * catch (error) {
+ *   const message = getErrorMessage(error);
+ *   showToast(message);
+ * }
+ * ```
+ */
+declare function getErrorMessage(error: unknown): string;
 
-export { type AgentMessage, type AgentRunConfig, type AgentRunEvent, type AgentRunOptions, type AgentRunResult, type AgentRunStatusResult, AgentWallet, type AgentWalletConfig, type CallMerchantApiOptions, type ChargeResult, InsufficientBalanceError, InvalidSessionKeyError, MixrPayError, type PaymentEvent, PaymentFailedError, SDK_VERSION, type SessionAuthorization, SessionExpiredError, SessionKeyExpiredError, SessionLimitExceededError, SessionNotFoundError, SessionRevokedError, type SessionStats, SpendingLimitExceededError, type SpendingStats, isMixrPayError };
+export { type AgentMessage, type AgentRunConfig, type AgentRunEvent, type AgentRunOptions, type AgentRunResult, type AgentRunStatusResult, AgentWallet, type AgentWalletConfig, type CallMerchantApiOptions, type ChargeResult, type DiagnosticsResult, InsufficientBalanceError, InvalidSessionKeyError, MixrPayError, type PaymentEvent, PaymentFailedError, SDK_VERSION, type SessionAuthorization, SessionExpiredError, SessionKeyExpiredError, type SessionKeyInfo, SessionLimitExceededError, SessionNotFoundError, SessionRevokedError, type SessionStats, SpendingLimitExceededError, type SpendingStats, X402ProtocolError, getErrorMessage, isMixrPayError };

package/dist/index.d.ts

@@ -121,6 +121,10 @@ interface PaymentEvent {
     description?: string;
     /** URL that triggered the payment */
     url?: string;
+    /** Auto-generated unique ID for this request */
+    requestId: string;
+    /** User-provided correlation ID (from X-Correlation-Id header if provided) */
+    correlationId?: string;
 }
 /**
  * Information about a session key.
@@ -195,6 +199,21 @@ interface DiagnosticsResult {
     network: string;
     /** Wallet address */
     walletAddress: string;
+    /** Session key limit info (if available) */
+    sessionLimits?: {
+        /** Remaining daily limit in USD (null if no limit) */
+        remainingDailyUsd: number | null;
+        /** Remaining total limit in USD (null if no limit) */
+        remainingTotalUsd: number | null;
+        /** When the session key expires (null if never) */
+        expiresAt: Date | null;
+        /** Hours until expiration (null if never) */
+        expiresInHours: number | null;
+    };
+    /** Network latency to API in milliseconds */
+    latencyMs?: number;
+    /** Actionable recommendations based on issues found */
+    recommendations: string[];
 }
 /**
  * Options for creating a session authorization with a MixrPay merchant.
@@ -359,7 +378,7 @@ interface SessionStats {
  */
 
 /** Current SDK version */
-declare const SDK_VERSION = "0.5.0";
+declare const SDK_VERSION = "0.6.0";
 /** Supported networks */
 declare const NETWORKS: {
     readonly BASE_MAINNET: {
@@ -672,6 +691,10 @@ declare class AgentWallet {
      * ```
      */
     fetch(url: string, init?: RequestInit): Promise<Response>;
+    /**
+     * Extract correlation ID from request headers.
+     */
+    private extractCorrelationId;
     /**
      * Handle a 402 Payment Required response.
      */
@@ -710,6 +733,36 @@ declare class AgentWallet {
      * ```
      */
     getBalance(): Promise<number>;
+    /**
+     * 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`);
+     * }
+     * ```
+     */
+    canAfford(amountUsd: number): Promise<{
+        /** Whether the wallet can afford this amount */
+        canAfford: boolean;
+        /** Current wallet balance in USD */
+        balance: number;
+        /** Amount short (0 if can afford) */
+        shortfall: number;
+        /** Remaining after payment (0 if can't afford) */
+        remainingAfter: number;
+    }>;
     /**
      * Get information about the session key.
      *
@@ -1326,7 +1379,33 @@ interface AgentRunStatusResult {
 declare class MixrPayError extends Error {
     /** Error code for programmatic handling */
     readonly code: string;
-    constructor(message: string, code?: string);
+    /** Optional hint for how long to wait before retrying (in milliseconds) */
+    readonly retryAfterMs?: number;
+    constructor(message: string, code?: string, retryAfterMs?: number);
+    /**
+     * 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(): boolean;
 }
 /**
  * Thrown when the wallet doesn't have enough USDC for the payment.
@@ -1418,6 +1497,12 @@ declare class SpendingLimitExceededError extends MixrPayError {
     /** The amount that was attempted in USD */
     readonly attempted: number;
     constructor(limitType: string, limit: number, attempted: number);
+    /**
+     * 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(): boolean;
 }
 /**
  * Thrown when a payment transaction fails.
@@ -1449,6 +1534,11 @@ declare class PaymentFailedError extends MixrPayError {
     /** Transaction hash if the tx was submitted (for debugging) */
     readonly txHash?: string;
     constructor(reason: string, txHash?: string);
+    /**
+     * Payment failures are often transient (network issues, temporary server errors).
+     * @returns true - payment failures should generally be retried
+     */
+    isRetryable(): boolean;
 }
 /**
  * Thrown when the session key format is invalid.
@@ -1479,6 +1569,38 @@ declare class InvalidSessionKeyError extends MixrPayError {
     readonly reason: string;
     constructor(reason?: string);
 }
+/**
+ * Thrown when there's an error in x402 protocol handling.
+ *
+ * This indicates a problem with the payment protocol, usually due to:
+ * - Malformed 402 response from server
+ * - Missing required payment fields
+ * - Invalid payment parameters
+ * - Protocol version mismatch
+ *
+ * ## Resolution
+ * This is usually a server-side issue. Contact the API provider if the error persists.
+ *
+ * @example
+ * ```typescript
+ * catch (error) {
+ *   if (error instanceof X402ProtocolError) {
+ *     console.log(`Protocol error: ${error.reason}`);
+ *     // Contact API provider or check server configuration
+ *   }
+ * }
+ * ```
+ */
+declare class X402ProtocolError extends MixrPayError {
+    /** Detailed reason for the protocol error */
+    readonly reason: string;
+    constructor(reason: string);
+    /**
+     * Protocol errors may be caused by temporary server issues.
+     * @returns true - worth retrying in case server recovers
+     */
+    isRetryable(): boolean;
+}
 /**
  * Thrown when a session authorization has expired.
  *
@@ -1611,5 +1733,20 @@ declare class SessionRevokedError extends MixrPayError {
  * ```
  */
 declare function isMixrPayError(error: unknown): error is MixrPayError;
+/**
+ * Get a user-friendly error message from any error.
+ *
+ * @param error - The error to get a message from
+ * @returns A user-friendly error message
+ *
+ * @example
+ * ```typescript
+ * catch (error) {
+ *   const message = getErrorMessage(error);
+ *   showToast(message);
+ * }
+ * ```
+ */
+declare function getErrorMessage(error: unknown): string;
 
-export { type AgentMessage, type AgentRunConfig, type AgentRunEvent, type AgentRunOptions, type AgentRunResult, type AgentRunStatusResult, AgentWallet, type AgentWalletConfig, type CallMerchantApiOptions, type ChargeResult, InsufficientBalanceError, InvalidSessionKeyError, MixrPayError, type PaymentEvent, PaymentFailedError, SDK_VERSION, type SessionAuthorization, SessionExpiredError, SessionKeyExpiredError, SessionLimitExceededError, SessionNotFoundError, SessionRevokedError, type SessionStats, SpendingLimitExceededError, type SpendingStats, isMixrPayError };
+export { type AgentMessage, type AgentRunConfig, type AgentRunEvent, type AgentRunOptions, type AgentRunResult, type AgentRunStatusResult, AgentWallet, type AgentWalletConfig, type CallMerchantApiOptions, type ChargeResult, type DiagnosticsResult, InsufficientBalanceError, InvalidSessionKeyError, MixrPayError, type PaymentEvent, PaymentFailedError, SDK_VERSION, type SessionAuthorization, SessionExpiredError, SessionKeyExpiredError, type SessionKeyInfo, SessionLimitExceededError, SessionNotFoundError, SessionRevokedError, type SessionStats, SpendingLimitExceededError, type SpendingStats, X402ProtocolError, getErrorMessage, isMixrPayError };

package/dist/index.js

@@ -9,14 +9,43 @@ import {
 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 */
@@ -74,6 +103,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 */
@@ -90,6 +127,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 */
@@ -114,6 +158,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 */
@@ -181,6 +232,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 = {
@@ -411,7 +471,7 @@ function getAmountUsd(requirements) {
 }
 
 // src/agent-wallet.ts
-var SDK_VERSION = "0.5.0";
+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 = {
@@ -823,6 +883,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 {
@@ -833,7 +895,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) {
@@ -845,10 +907,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);
@@ -904,7 +983,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;
@@ -1003,6 +1084,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.
    * 
@@ -1143,56 +1254,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
     };
   }
   /**
@@ -1601,7 +1756,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;
@@ -1800,7 +1957,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;
@@ -1917,7 +2075,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;
@@ -2009,7 +2168,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;
@@ -2185,7 +2345,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;
@@ -2215,5 +2376,7 @@ export {
   SessionNotFoundError,
   SessionRevokedError,
   SpendingLimitExceededError,
+  X402ProtocolError,
+  getErrorMessage,
   isMixrPayError
 };

package/package.json

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