@mixrpay/agent-sdk 0.8.8 → 0.9.1

package/dist/index.d.ts

@@ -557,7 +557,7 @@ interface AgentClaimInviteResult {
  * Options for spawning a child invite
  */
 interface SpawnChildOptions {
-    /** Budget in USD for the child (max 20% of available) */
+    /** Budget in USD for the child (subject to platform limits) */
     budgetUsd: number;
     /** Name for the child invite */
     name: string;
@@ -574,13 +574,13 @@ interface SpawnChildResult {
     inviteCode: string;
     /** Database ID of the invite */
     inviteId: string;
-    /** Actual budget (may be less than requested due to 20% cap) */
+    /** Actual budget (may be less than requested due to platform limits) */
     budgetUsd: number;
     /** When the invite expires */
     expiresAt: Date;
     /** Depth in hierarchy (1 = child, 2 = grandchild, etc.) */
     depth: number;
-    /** How much this child can spawn (20% of their budget) */
+    /** How much this child can spawn */
     maxSpawnBudget: number;
     /** Allowed merchants for this child */
     allowedMerchants: string[];
@@ -597,9 +597,9 @@ interface AvailableBudget {
     allocatedToChildren: number;
     /** Available for spending or spawning */
     available: number;
-    /** Maximum budget for next spawn (20% of available) */
+    /** Maximum budget for next spawn */
     maxSpawnBudget: number;
-    /** Whether spawning is allowed (depth < 10, can_spawn, available > 0) */
+    /** Whether spawning is allowed */
     canSpawn: boolean;
 }
 /**
@@ -748,7 +748,7 @@ declare class AgentWallet {
     /**
      * Register a new agent with MixrPay.
      *
-     * This creates a Privy-managed embedded wallet for the agent's payments.
+     * This creates a platform-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
@@ -786,7 +786,7 @@ declare class AgentWallet {
         healthy: boolean;
         database: string;
         agentRegistrationAvailable: boolean;
-        privyConfigured: boolean;
+        walletServiceConfigured: boolean;
         error?: string;
     }>;
     /**
@@ -916,7 +916,7 @@ declare class AgentWallet {
      * Spawn a child invite for sub-agents.
      *
      * Allows an agent to create an invite code for a sub-agent with a portion
-     * of their remaining budget (max 20%). The child inherits merchant restrictions
+     * of their remaining budget. The child inherits merchant restrictions
      * and cannot outlive the parent session.
      *
      * @param options - Spawn options
@@ -930,7 +930,7 @@ declare class AgentWallet {
      *
      * // Spawn a child invite for a sub-agent
      * const childInvite = await wallet.spawnChildInvite({
-     *   budgetUsd: 10.00,  // Max 20% of available budget
+     *   budgetUsd: 10.00,
      *   name: 'Research Sub-Agent',
      *   allowedMerchants: ['firecrawl.dev'],  // Must be subset of parent
      *   expiresInDays: 7,  // Will be capped to parent's expiry
@@ -944,8 +944,7 @@ declare class AgentWallet {
     /**
      * Get available budget information for spawning.
      *
-     * Returns the current budget status including how much can be spawned
-     * to child agents (20% of available).
+     * Returns the current budget status including spawn availability.
      *
      * @returns Budget information
      *
@@ -1459,6 +1458,183 @@ declare class AgentWallet {
      * ```
      */
     getJitInstance(instanceId: string): Promise<JitInstance>;
+    /**
+     * Execute an on-chain transaction from the human's wallet.
+     *
+     * Submits arbitrary calldata to any contract, bounded by the session key's
+     * budget limits (max_total, max_per_tx, max_daily). The platform validates
+     * the budget, executes the transaction, and records a charge.
+     *
+     * @param params - Transaction parameters
+     * @returns Transaction result with hash and remaining budget
+     * @throws {MixrPayError} If budget exceeded, tx reverted, or auth fails
+     *
+     * @example
+     * ```typescript
+     * // Bridge USDC via deBridge
+     * const quote = await deBridgeMcp.create_tx({ ... });
+     * const result = await wallet.executeTransaction({
+     *   to: quote.contractAddress,
+     *   data: quote.calldata,
+     *   estimatedCostUsd: 25.0,
+     *   description: 'Bridge 25 USDC Base -> Avalanche via deBridge',
+     * });
+     * console.log('TX:', result.txHash);
+     * console.log('Budget remaining:', result.remainingBudgetUsd);
+     * ```
+     */
+    executeTransaction(params: {
+        to: `0x${string}`;
+        data: `0x${string}`;
+        value?: bigint;
+        chainId?: number;
+        estimatedCostUsd: number;
+        description?: string;
+        idempotencyKey?: string;
+    }): Promise<{
+        success: boolean;
+        txHash: string;
+        chargeId: string;
+        estimatedCostUsd: number;
+        remainingBudgetUsd: number | null;
+    }>;
+    /**
+     * Use a configured skill by deploying a JIT MCP server with your saved API keys.
+     *
+     * Skills are configured on the MixrPay dashboard with your API keys stored securely.
+     * When you call useSkill(), MixrPay deploys an ephemeral MCP server with your keys
+     * injected server-side - your keys are never exposed to the agent.
+     *
+     * @param skillId - The skill ID (e.g., 'github', 'notion', 'spotify')
+     * @param options - Optional configuration
+     * @returns Skill endpoint and available tools
+     *
+     * @example
+     * ```typescript
+     * // Use the GitHub skill
+     * const github = await wallet.useSkill('github');
+     *
+     * console.log('Endpoint:', github.endpoint);
+     * console.log('Tools:', github.tools);
+     * console.log('Expires:', github.expiresAt);
+     *
+     * // Connect to the MCP endpoint and call tools
+     * // The exact method depends on your MCP client
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Use Notion with custom TTL
+     * const notion = await wallet.useSkill('notion', { ttlHours: 48 });
+     * ```
+     *
+     * @throws {MixrPayError} If skill is not configured or deployment fails
+     */
+    useSkill(skillId: string, options?: UseSkillOptions): Promise<UseSkillResult>;
+    /**
+     * List all available skills and their configuration status.
+     *
+     * @returns Array of skills with status
+     *
+     * @example
+     * ```typescript
+     * const skills = await wallet.listSkills();
+     *
+     * // Find configured skills
+     * const configured = skills.filter(s => s.status === 'configured');
+     * console.log(`${configured.length} skills ready to use`);
+     *
+     * // Find skills that need configuration
+     * const needsConfig = skills.filter(s => s.status === 'not_configured' && s.envVars.length > 0);
+     * for (const skill of needsConfig) {
+     *   console.log(`${skill.name} needs: ${skill.envVars.map(v => v.label).join(', ')}`);
+     * }
+     * ```
+     */
+    listSkills(): Promise<SkillInfo[]>;
+    /**
+     * Get apps connected via Composio (Gmail, Slack, GitHub, etc.).
+     *
+     * Use this to discover which apps the owner has connected before
+     * attempting to use them via `wallet.useSkill('composio')`.
+     *
+     * @returns Object with connected app names and connection details
+     *
+     * @example
+     * ```typescript
+     * const apps = await wallet.getConnectedApps();
+     *
+     * if (apps.connected.length === 0) {
+     *   console.log('No apps connected. Ask your owner to connect apps at the dashboard.');
+     * } else {
+     *   console.log('Connected apps:', apps.connected.join(', '));
+     *
+     *   if (apps.connected.includes('gmail')) {
+     *     // Safe to use Composio for Gmail
+     *     const { endpoint, tools } = await wallet.useSkill('composio');
+     *     // tools will include 'gmail_read_emails', 'gmail_send_email', etc.
+     *   }
+     * }
+     * ```
+     */
+    getConnectedApps(): Promise<ConnectedAppsResult>;
+    /**
+     * Get configuration status for a specific skill.
+     *
+     * @param skillId - The skill ID
+     * @returns Skill configuration status
+     *
+     * @example
+     * ```typescript
+     * const status = await wallet.getSkillStatus('github');
+     *
+     * if (status.status === 'configured') {
+     *   console.log('GitHub is ready!');
+     *   console.log('Configured vars:', status.configuredVars);
+     * } else {
+     *   console.log('Please configure GitHub at the MixrPay dashboard');
+     * }
+     * ```
+     */
+    getSkillStatus(skillId: string): Promise<SkillStatus>;
+    /**
+     * Configure a skill with API keys.
+     *
+     * This allows agents to save API keys received via chat to the MixrPay platform.
+     * Keys are encrypted at rest and will be available for use on subsequent deploy/redeploy.
+     *
+     * @param skillId - The skill ID (e.g., 'web-search', 'github', 'notion') or custom skill with 'custom-' prefix
+     * @param envVars - Environment variables with API keys (e.g., { BRAVE_API_KEY: 'xxx' })
+     * @returns Configuration result with list of configured variables
+     *
+     * @example Predefined skill
+     * ```typescript
+     * // User provides API key in chat, agent saves it
+     * const result = await wallet.configureSkill('web-search', {
+     *   BRAVE_API_KEY: 'BSA_abc123xyz',
+     * });
+     *
+     * console.log('Configured:', result.configuredVars);
+     * // After next redeploy, the skill will be enabled with this key
+     * ```
+     *
+     * @example Custom API key
+     * ```typescript
+     * // For APIs not in predefined skills, use custom- prefix
+     * // User: "Here's my Polymarket API key: pk_abc123"
+     * const result = await wallet.configureSkill('custom-polymarket', {
+     *   POLYMARKET_API_KEY: 'pk_abc123',
+     * });
+     *
+     * // The key is now available in the agent's environment
+     * // Access via: process.env.POLYMARKET_API_KEY
+     * ```
+     */
+    configureSkill(skillId: string, envVars: Record<string, string>): Promise<{
+        success: boolean;
+        skillId: string;
+        configuredVars: string[];
+    }>;
     /**
      * Search the Glama MCP server directory.
      *
@@ -2468,6 +2644,115 @@ interface JitInstance {
     /** Creation time */
     createdAt: Date;
 }
+/**
+ * Options for using a skill
+ */
+interface UseSkillOptions {
+    /** Time-to-live in hours for the MCP server (default: 24, max: 48) */
+    ttlHours?: number;
+}
+/**
+ * Result from using a skill
+ */
+interface UseSkillResult {
+    /** Skill ID */
+    skillId: string;
+    /** MCP server endpoint URL */
+    endpoint: string;
+    /** Available tool names */
+    tools: string[];
+    /** When the MCP server expires */
+    expiresAt: Date;
+    /** JIT instance ID for reference */
+    instanceId: string;
+}
+/**
+ * Skill information from the skills list
+ */
+interface SkillInfo {
+    /** Skill ID */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Short description */
+    description: string;
+    /** Category */
+    category: string;
+    /** Category display name */
+    categoryName: string;
+    /** Icon name */
+    icon: string;
+    /** Whether this is a built-in skill */
+    builtIn: boolean;
+    /** Whether this skill requires MCP deployment */
+    requiresMcp: boolean;
+    /** Whether this skill is available */
+    available: boolean;
+    /** Configuration status */
+    status: 'not_configured' | 'configured' | 'error';
+    /** Last used timestamp */
+    lastUsedAt?: string;
+    /** Error message if status is 'error' */
+    errorMessage?: string;
+    /** Environment variables required */
+    envVars: Array<{
+        name: string;
+        label: string;
+        description: string;
+        required: boolean;
+        isSecret: boolean;
+        configured: boolean;
+    }>;
+}
+/**
+ * Skill configuration status
+ */
+interface SkillStatus {
+    /** Skill ID */
+    skillId: string;
+    /** Configuration status */
+    status: 'not_configured' | 'configured' | 'error';
+    /** Names of configured environment variables */
+    configuredVars: string[];
+    /** Last used timestamp */
+    lastUsedAt?: Date;
+    /** Error message if status is 'error' */
+    errorMessage?: string;
+}
+/**
+ * Connected apps information from Composio
+ */
+interface ConnectedAppsResult {
+    /** Array of connected app IDs (e.g., ['gmail', 'slack', 'github']) */
+    connected: string[];
+    /** Full connection details */
+    connections: Array<{
+        id: string;
+        app: string;
+        app_name: string;
+        type: 'oauth' | 'api_key';
+        status: string;
+        account_name: string | null;
+        connected_at: string;
+    }>;
+    /** OAuth connections only */
+    oauthConnections: Array<{
+        id: string;
+        app: string;
+        app_name: string;
+        status: string;
+        account_name: string | null;
+        connected_at: string;
+    }>;
+    /** API key connections only */
+    apiKeyConnections: Array<{
+        id: string;
+        app: string;
+        app_name: string;
+        status: string;
+        connected_at: string;
+    }>;
+}
 /**
  * MCP server from the Glama directory
  */
@@ -3403,4 +3688,4 @@ declare function isMixrPayError(error: unknown): error is MixrPayError;
  */
 declare function getErrorMessage(error: unknown): string;
 
-export { type AgentClaimInviteOptions, type AgentClaimInviteResult, type AgentMessage, type AgentRunConfig, type AgentRunEvent, type AgentRunOptions, type AgentRunResult, type AgentRunStatusResult, AgentWallet, type AgentWalletConfig, type AvailableBudget, type CallMerchantApiOptions, type ChargeResult, type ChildSession, type CompleteOptions, type CompleteResult, type DeployJitMcpOptions, type DeployJitMcpResult, type DiagnosticsResult, type GlamaImportData, type GlamaSearchResult, type GlamaServer, InsufficientBalanceError, InvalidSessionKeyError, type JitInstance, MerchantNotAllowedError, MixrPayError, type PaymentEvent, PaymentFailedError, SDK_VERSION, type SessionAuthorization, SessionExpiredError, SessionKeyExpiredError, type SessionKeyInfo, SessionLimitExceededError, SessionNotFoundError, SessionRevokedError, type SessionStats, type SpawnChildOptions, type SpawnChildResult, SpendingLimitExceededError, type SpendingStats, X402ProtocolError, getErrorMessage, isMixrPayError };
+export { type AgentClaimInviteOptions, type AgentClaimInviteResult, type AgentMessage, type AgentRunConfig, type AgentRunEvent, type AgentRunOptions, type AgentRunResult, type AgentRunStatusResult, AgentWallet, type AgentWalletConfig, type AvailableBudget, type CallMerchantApiOptions, type ChargeResult, type ChildSession, type CompleteOptions, type CompleteResult, type DeployJitMcpOptions, type DeployJitMcpResult, type DiagnosticsResult, type GlamaImportData, type GlamaSearchResult, type GlamaServer, InsufficientBalanceError, InvalidSessionKeyError, type JitInstance, MerchantNotAllowedError, MixrPayError, type PaymentEvent, PaymentFailedError, SDK_VERSION, type SessionAuthorization, SessionExpiredError, SessionKeyExpiredError, type SessionKeyInfo, SessionLimitExceededError, SessionNotFoundError, SessionRevokedError, type SessionStats, type SkillInfo, type SkillStatus, type SpawnChildOptions, type SpawnChildResult, SpendingLimitExceededError, type SpendingStats, type UseSkillOptions, type UseSkillResult, X402ProtocolError, getErrorMessage, isMixrPayError };