@mixrpay/agent-sdk 0.10.0 → 0.11.0

package/dist/index.d.cts

@@ -200,6 +200,7 @@ interface FetchPaymentInfo {
     amount_usd: string;
     tx_hash?: string;
     remaining_budget_usd: string | null;
+    charge_id?: string;
 }
 interface FetchPaidResponse {
     status: number;
@@ -212,6 +213,33 @@ interface FetchPaidOptions {
     headers?: Record<string, string>;
     body?: unknown;
     maxPaymentUsd?: number;
+    /** Idempotency key for exactly-once semantics. If provided with a duplicate key, returns cached result. */
+    idempotencyKey?: string;
+}
+/**
+ * Options for transfer operations with idempotency support.
+ */
+interface TransferOptions {
+    /** Idempotency key for exactly-once semantics. If provided with a duplicate key, returns cached result. */
+    idempotencyKey?: string;
+}
+/**
+ * Options for swap operations with idempotency support.
+ */
+interface SwapOptions {
+    /** Slippage tolerance in basis points (default: 100 = 1%) */
+    slippageBps?: number;
+    /** Idempotency key for exactly-once semantics. If provided with a duplicate key, returns cached result. */
+    idempotencyKey?: string;
+}
+/**
+ * Options for bridge operations with idempotency support.
+ */
+interface BridgeOptions {
+    /** Destination address (defaults to same address) */
+    destAddress?: string;
+    /** Idempotency key for exactly-once semantics. If provided with a duplicate key, returns cached result. */
+    idempotencyKey?: string;
 }
 /**
  * Known charge types in the MixrPay system.
@@ -310,9 +338,166 @@ interface AnthropicToolkit {
      */
     execute: (name: string, input: Record<string, unknown>) => Promise<string>;
 }
+/**
+ * Supported plan step actions.
+ */
+type PlanStepAction = 'transfer' | 'swap' | 'bridge' | 'tool_call' | 'fetch' | 'custom';
+/**
+ * A single step in a plan.
+ */
+interface PlanStep {
+    /** Action type for this step */
+    action: PlanStepAction;
+    /** Parameters for the action */
+    params: Record<string, unknown>;
+    /** Estimated cost in USD */
+    estimatedCostUsd?: number;
+    /** Human-readable description */
+    description: string;
+}
+/**
+ * Plan submission request.
+ */
+interface PlanSubmission {
+    /** Plan title */
+    title: string;
+    /** Optional description */
+    description?: string;
+    /** Steps to execute */
+    steps: PlanStep[];
+    /** Total estimated cost in USD */
+    totalEstimatedCostUsd: number;
+    /** Whether to require human approval (default: false) */
+    requiresApproval?: boolean;
+    /** Idempotency key for exactly-once submission */
+    idempotencyKey?: string;
+}
+/**
+ * Result from submitting a plan.
+ */
+interface PlanSubmitResult {
+    /** Unique plan ID */
+    planId: string;
+    /** Plan status after submission */
+    status: 'pending_approval' | 'auto_approved';
+    /** URL for human approval (if pending) */
+    approvalUrl?: string;
+}
+/**
+ * Status values for plan steps.
+ */
+type PlanStepStatusValue = 'pending' | 'executing' | 'completed' | 'failed' | 'skipped' | 'awaiting_confirmation';
+/**
+ * Status of a single plan step.
+ */
+interface PlanStepStatus {
+    /** Step index */
+    index: number;
+    /** Action type */
+    action: PlanStepAction;
+    /** Step description */
+    description: string;
+    /** Current status */
+    status: PlanStepStatusValue;
+    /** Estimated cost in USD */
+    estimatedCostUsd?: number;
+    /** Transaction hash (if completed) */
+    txHash?: string;
+    /** Charge ID (if completed) */
+    chargeId?: string;
+    /** Bridge order ID (if bridge action) */
+    bridgeOrderId?: string;
+    /** Error message (if failed) */
+    error?: string;
+    /** When execution started */
+    submittedAt?: string;
+    /** When execution completed */
+    completedAt?: string;
+}
+/**
+ * Overall plan status values.
+ */
+type PlanStatusValue = 'pending_approval' | 'approved' | 'auto_approved' | 'rejected' | 'expired' | 'executing' | 'completed' | 'partial_failure' | 'failed';
+/**
+ * Full plan status including step details.
+ */
+interface PlanStatus {
+    /** Unique plan ID */
+    planId: string;
+    /** Plan title */
+    title: string;
+    /** Plan description */
+    description?: string;
+    /** Overall plan status */
+    status: PlanStatusValue;
+    /** Per-step status */
+    steps: PlanStepStatus[];
+    /** Total estimated cost in USD */
+    totalEstimatedCostUsd: number;
+    /** Approval info (if responded) */
+    approval?: {
+        status: string;
+        respondedAt?: string;
+        responseNote?: string;
+    };
+    /** When the plan was created */
+    createdAt: string;
+    /** When the plan expires */
+    expiresAt?: string;
+}
+/**
+ * Summary item for plan listing.
+ */
+interface PlanListItem {
+    /** Unique plan ID */
+    planId: string;
+    /** Plan title */
+    title: string;
+    /** Overall status */
+    status: string;
+    /** Total estimated cost in USD */
+    totalEstimatedCostUsd: number;
+    /** Number of completed steps */
+    stepsCompleted: number;
+    /** Total number of steps */
+    stepsTotal: number;
+    /** When the plan was created */
+    createdAt: string;
+}
+/**
+ * Response from listing plans.
+ */
+interface PlansListResponse {
+    /** List of plans */
+    plans: PlanListItem[];
+    /** Total number of matching plans */
+    total: number;
+    /** Whether more plans exist */
+    hasMore: boolean;
+}
+/**
+ * Options for listing plans.
+ */
+interface ListPlansOptions {
+    /** Maximum number of plans to return */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+    /** Filter by status */
+    status?: string;
+}
+/**
+ * Options for waiting on plan completion.
+ */
+interface WaitForPlanOptions {
+    /** Poll interval in milliseconds (default: 15000) */
+    pollIntervalMs?: number;
+    /** Timeout in milliseconds (default: 1800000 = 30 min) */
+    timeoutMs?: number;
+}
 
 /** Current SDK version */
-declare const SDK_VERSION = "0.10.0";
+declare const SDK_VERSION = "0.11.0";
 /** Supported networks */
 declare const NETWORKS: {
     readonly BASE_MAINNET: {
@@ -2865,6 +3050,7 @@ declare class AgentWallet {
      * @param to - Recipient address
      * @param amount - Amount in USD (e.g., "10.50")
      * @param currency - Currency to transfer (default: "USDC")
+     * @param options - Optional transfer options (idempotencyKey)
      * @returns Transfer result with transaction hash
      * @throws {MixrPayError} If the transfer fails
      *
@@ -2875,8 +3061,16 @@ declare class AgentWallet {
      * console.log(`TX: ${result.tx_hash}`);
      * console.log(`Remaining budget: $${result.remaining_budget_usd}`);
      * ```
+     *
+     * @example With idempotency key
+     * ```typescript
+     * const result = await wallet.transfer('0x1234...', '10.00', 'USDC', {
+     *   idempotencyKey: 'payment-123',
+     * });
+     * // If called again with same key, returns cached result
+     * ```
      */
-    transfer(to: string, amount: string, currency?: string): Promise<TransferResponse>;
+    transfer(to: string, amount: string, currency?: string, options?: TransferOptions): Promise<TransferResponse>;
     /**
      * Swap tokens using 0x Protocol on Base.
      *
@@ -2886,7 +3080,7 @@ declare class AgentWallet {
      * @param sellToken - Token to sell (symbol or address, e.g., "USDC", "ETH")
      * @param buyToken - Token to buy (symbol or address, e.g., "WETH", "USDC")
      * @param sellAmount - Amount to sell in human-readable format (e.g., "100" for 100 USDC)
-     * @param slippageBps - Slippage tolerance in basis points (default: 100 = 1%)
+     * @param options - Optional swap options (slippageBps, idempotencyKey)
      * @returns Swap result with transaction hash and amounts
      * @throws {MixrPayError} If the swap fails
      *
@@ -2898,8 +3092,16 @@ declare class AgentWallet {
      * console.log(`Received ${result.buy_amount} ${result.buy_token}`);
      * console.log(`Price: ${result.price}`);
      * ```
+     *
+     * @example With options
+     * ```typescript
+     * const result = await wallet.swap('USDC', 'ETH', '100', {
+     *   slippageBps: 50,
+     *   idempotencyKey: 'swap-abc123',
+     * });
+     * ```
      */
-    swap(sellToken: string, buyToken: string, sellAmount: string, slippageBps?: number): Promise<SwapResponse>;
+    swap(sellToken: string, buyToken: string, sellAmount: string, options?: SwapOptions | number): Promise<SwapResponse>;
     /**
      * Bridge tokens to another chain using deBridge.
      *
@@ -2910,7 +3112,7 @@ declare class AgentWallet {
      * @param token - Token to bridge (symbol, e.g., "USDC")
      * @param amount - Amount in human-readable format (e.g., "100")
      * @param destChain - Destination chain ID or name (e.g., "1" for Ethereum, "arbitrum")
-     * @param destAddress - Destination address (defaults to same address)
+     * @param options - Optional bridge options (destAddress, idempotencyKey)
      * @returns Bridge result with order ID for tracking
      * @throws {MixrPayError} If the bridge fails
      *
@@ -2927,8 +3129,16 @@ declare class AgentWallet {
      *   console.log(`Completed! Dest TX: ${status.dest_tx_hash}`);
      * }
      * ```
+     *
+     * @example With options
+     * ```typescript
+     * const result = await wallet.bridge('USDC', '100', 'arbitrum', {
+     *   destAddress: '0xabc...',
+     *   idempotencyKey: 'bridge-xyz789',
+     * });
+     * ```
      */
-    bridge(token: string, amount: string, destChain: string, destAddress?: string): Promise<BridgeResponse>;
+    bridge(token: string, amount: string, destChain: string, options?: BridgeOptions | string): Promise<BridgeResponse>;
     /**
      * Check the status of a bridge order.
      *
@@ -2964,7 +3174,7 @@ declare class AgentWallet {
      * fetch() that uses session key auth for x402, see the standard fetch() method.
      *
      * @param url - URL to fetch
-     * @param options - Fetch options (method, headers, body, maxPaymentUsd)
+     * @param options - Fetch options (method, headers, body, maxPaymentUsd, idempotencyKey)
      * @returns Response with status, headers, body, and optional payment info
      * @throws {MixrPayError} If the fetch fails
      *
@@ -2984,8 +3194,126 @@ declare class AgentWallet {
      *   console.log(`Paid $${result.payment.amount_usd}`);
      * }
      * ```
+     *
+     * @example With idempotency key
+     * ```typescript
+     * const result = await wallet.fetchPaid('https://api.example.com/data', {
+     *   idempotencyKey: 'request-123',
+     * });
+     * // If called again with same key, returns cached result
+     * ```
      */
     fetchPaid(url: string, options?: FetchPaidOptions): Promise<FetchPaidResponse>;
+    /**
+     * Submit a multi-step plan for approval or auto-approval.
+     *
+     * Plans allow agents to propose complex workflows (swap, bridge, transfer, etc.)
+     * that can be reviewed by humans before execution.
+     *
+     * @param plan - Plan submission details
+     * @returns Plan submission result with ID and status
+     * @throws {MixrPayError} If submission fails
+     *
+     * @example
+     * ```typescript
+     * const result = await wallet.submitPlan({
+     *   title: 'Swap and Bridge to Arbitrum',
+     *   steps: [
+     *     { action: 'swap', params: { sellToken: 'USDC', buyToken: 'ETH', sellAmount: '100' }, description: 'Swap USDC for ETH' },
+     *     { action: 'bridge', params: { token: 'ETH', amount: '0.03', destChain: 'arbitrum' }, description: 'Bridge ETH to Arbitrum' },
+     *   ],
+     *   totalEstimatedCostUsd: 105,
+     * });
+     *
+     * if (result.status === 'pending_approval') {
+     *   console.log(`Waiting for approval: ${result.approvalUrl}`);
+     * } else {
+     *   await wallet.executePlan(result.planId);
+     * }
+     * ```
+     */
+    submitPlan(plan: PlanSubmission): Promise<PlanSubmitResult>;
+    /**
+     * Get the current status of a plan.
+     *
+     * @param planId - Plan ID
+     * @returns Full plan status including step details
+     * @throws {MixrPayError} If status check fails
+     */
+    getPlanStatus(planId: string): Promise<PlanStatus>;
+    /**
+     * List plans for this agent.
+     *
+     * @param options - Query options
+     * @returns List of plans with summary info
+     * @throws {MixrPayError} If listing fails
+     */
+    listPlans(options?: ListPlansOptions): Promise<PlansListResponse>;
+    /**
+     * Report progress on a plan step (internal use by executePlan).
+     *
+     * @param planId - Plan ID
+     * @param stepIndex - Step index
+     * @param status - New status
+     * @param details - Optional details (txHash, chargeId, error)
+     */
+    private reportPlanProgress;
+    /**
+     * Wait for a bridge order to complete.
+     *
+     * Polls the bridge status endpoint until the bridge is fulfilled or fails.
+     *
+     * @param orderId - Bridge order ID
+     * @param options - Polling options
+     * @throws {MixrPayError} If bridge fails or times out
+     */
+    waitForBridgeCompletion(orderId: string, options?: WaitForPlanOptions): Promise<void>;
+    /**
+     * Wait for a plan to complete execution.
+     *
+     * Polls the plan status until it reaches a terminal state.
+     *
+     * @param planId - Plan ID
+     * @param options - Polling options
+     * @returns Final plan status
+     */
+    waitForPlanCompletion(planId: string, options?: WaitForPlanOptions): Promise<PlanStatus>;
+    /**
+     * Execute an approved plan.
+     *
+     * Orchestrates step-by-step execution of an approved plan, handling:
+     * - Sequential execution of steps
+     * - Idempotency (safe to retry on restart)
+     * - Bridge wait times
+     * - Partial failure tracking
+     *
+     * This method runs in the agent's container (not serverless), so it can
+     * wait for long-running operations like bridge confirmations.
+     *
+     * @param planId - Plan ID to execute
+     * @returns Final plan status
+     * @throws {MixrPayError} If plan is not executable
+     *
+     * @example
+     * ```typescript
+     * // Submit and execute a plan
+     * const { planId, status } = await wallet.submitPlan({
+     *   title: 'DeFi workflow',
+     *   steps: [...],
+     *   totalEstimatedCostUsd: 50,
+     * });
+     *
+     * if (status === 'pending_approval') {
+     *   // Wait for human approval
+     *   await wallet.waitForPlanCompletion(planId);
+     * }
+     *
+     * // Execute once approved
+     * const result = await wallet.executePlan(planId);
+     * console.log(`Plan ${result.status}: ${result.steps.filter(s => s.status === 'completed').length} steps completed`);
+     * ```
+     */
+    executePlan(planId: string): Promise<PlanStatus>;
     /**
      * Call the API with agent token auth (agt_live_xxx bearer token).
      * Used by DeFi methods that require delegation auth.
@@ -4673,4 +5001,4 @@ declare function getWalletStoragePath(): string;
  */
 declare function deleteWalletKey(): Promise<boolean>;
 
-export { type AgentClaimInviteOptions, type AgentClaimInviteResult, type AgentMessage, type AgentRunConfig, type AgentRunEvent, type AgentRunOptions, type AgentRunResult, type AgentRunStatusResult, AgentWallet, type AgentWalletConfig, type AnthropicToolDefinition, type AnthropicToolkit, AuthenticationError, type AvailableBudget, type BalancesResponse, type BridgeResponse, type BridgeStatusResponse, type CallMerchantApiOptions, type ChargeResult, type ChargeType, type ChildSession, type CompleteOptions, type CompleteResult, type ConnectOptions, type CredentialLoadResult, type DelegationBudget, type DeployJitMcpOptions, type DeployJitMcpResult, type DiagnosticsResult, type FetchPaidOptions, type FetchPaidResponse, type FetchPaymentInfo, type GetTransactionsOptions, type GlamaImportData, type GlamaSearchResult, type GlamaServer, InsufficientBalanceError, InvalidSessionKeyError, type JitInstance, type KnownChargeType, type MCPTool, type MCPToolResult, type McpServerConfig, MerchantNotAllowedError, MixrPayError, NetworkError, type PaymentEvent, PaymentFailedError, RateLimitError, SDK_VERSION, type SessionAuthorization, SessionExpiredError, SessionKeyExpiredError, type SessionKeyInfo, SessionLimitExceededError, SessionNotFoundError, SessionRevokedError, type SessionStats, type SiweOptions, type SiweResult, type SkillInfo, type SkillStatus, type SpawnChildOptions, type SpawnChildResult, SpendingLimitExceededError, type SpendingStats, type StoredCredentials, type StoredWallet, type SwapResponse, type TokenBalance, type Tool, type ToolResult, type TransactionRecord, type TransactionsResponse, type TransferResponse, type UseSkillOptions, type UseSkillResult, X402ProtocolError, deleteCredentials, deleteWalletKey, getCredentialsFilePath, getErrorMessage, getWalletStoragePath, hasCredentials, hasWalletKey, isMixrPayError, loadCredentials, loadWalletData, loadWalletKey, saveCredentials, saveWalletKey };
+export { type AgentClaimInviteOptions, type AgentClaimInviteResult, type AgentMessage, type AgentRunConfig, type AgentRunEvent, type AgentRunOptions, type AgentRunResult, type AgentRunStatusResult, AgentWallet, type AgentWalletConfig, type AnthropicToolDefinition, type AnthropicToolkit, AuthenticationError, type AvailableBudget, type BalancesResponse, type BridgeOptions, type BridgeResponse, type BridgeStatusResponse, type CallMerchantApiOptions, type ChargeResult, type ChargeType, type ChildSession, type CompleteOptions, type CompleteResult, type ConnectOptions, type CredentialLoadResult, type DelegationBudget, type DeployJitMcpOptions, type DeployJitMcpResult, type DiagnosticsResult, type FetchPaidOptions, type FetchPaidResponse, type FetchPaymentInfo, type GetTransactionsOptions, type GlamaImportData, type GlamaSearchResult, type GlamaServer, InsufficientBalanceError, InvalidSessionKeyError, type JitInstance, type KnownChargeType, type ListPlansOptions, type MCPTool, type MCPToolResult, type McpServerConfig, MerchantNotAllowedError, MixrPayError, NetworkError, type PaymentEvent, PaymentFailedError, type PlanListItem, type PlanStatus, type PlanStatusValue, type PlanStep, type PlanStepAction, type PlanStepStatus, type PlanStepStatusValue, type PlanSubmission, type PlanSubmitResult, type PlansListResponse, RateLimitError, SDK_VERSION, type SessionAuthorization, SessionExpiredError, SessionKeyExpiredError, type SessionKeyInfo, SessionLimitExceededError, SessionNotFoundError, SessionRevokedError, type SessionStats, type SiweOptions, type SiweResult, type SkillInfo, type SkillStatus, type SpawnChildOptions, type SpawnChildResult, SpendingLimitExceededError, type SpendingStats, type StoredCredentials, type StoredWallet, type SwapOptions, type SwapResponse, type TokenBalance, type Tool, type ToolResult, type TransactionRecord, type TransactionsResponse, type TransferOptions, type TransferResponse, type UseSkillOptions, type UseSkillResult, type WaitForPlanOptions, X402ProtocolError, deleteCredentials, deleteWalletKey, getCredentialsFilePath, getErrorMessage, getWalletStoragePath, hasCredentials, hasWalletKey, isMixrPayError, loadCredentials, loadWalletData, loadWalletKey, saveCredentials, saveWalletKey };