@mixrpay/agent-sdk 0.7.0 → 0.8.0

package/dist/index.cjs

@@ -525,7 +525,7 @@ function getAmountUsd(requirements) {
 }
 
 // src/agent-wallet.ts
-var SDK_VERSION = "0.6.1";
+var SDK_VERSION = "0.8.0";
 var DEFAULT_BASE_URL = process.env.MIXRPAY_BASE_URL || "https://www.mixrpay.com";
 var DEFAULT_TIMEOUT = 3e4;
 var NETWORKS = {
@@ -1141,6 +1141,91 @@ var AgentWallet = class {
       remainingBalanceUsd: data.remaining_balance_usd
     };
   }
+  /**
+   * Claim an agent invite code to receive a session key for the inviter's wallet.
+   * 
+   * This allows an agent to get a pre-configured session key from a human wallet owner
+   * without needing to register their own wallet or fund it. The human sets the budget
+   * limits and merchant whitelist when creating the invite.
+   * 
+   * @param options - Claim invite options including the invite code and agent's private key
+   * @returns Claim result with the new session key
+   * @throws {MixrPayError} If claiming fails (e.g., invalid code, already claimed, expired)
+   * 
+   * @example
+   * ```typescript
+   * // Human creates invite at their dashboard, shares code "mixr-abc123"
+   * 
+   * const result = await AgentWallet.claimInvite({
+   *   inviteCode: 'mixr-abc123',
+   *   privateKey: process.env.AGENT_WALLET_KEY as `0x${string}`,
+   * });
+   * 
+   * console.log(`Got session key: ${result.sessionKey}`);
+   * console.log(`Budget: $${result.limits.budgetUsd}/${result.limits.budgetPeriod}`);
+   * console.log(`Invited by: ${result.inviterName}`);
+   * 
+   * // Use the session key to make payments
+   * const wallet = new AgentWallet({ sessionKey: result.sessionKey });
+   * const response = await wallet.fetch('https://api.example.com/endpoint');
+   * ```
+   */
+  static async claimInvite(options) {
+    const { inviteCode, 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=claim-invite`
+    );
+    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 claimResponse = await fetch(`${baseUrl}/api/v1/agent/claim-invite`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        invite_code: inviteCode,
+        challenge,
+        agent_wallet_address: walletAddress,
+        signature
+      })
+    });
+    if (!claimResponse.ok) {
+      const error = await claimResponse.json().catch(() => ({}));
+      const errorMessage = error.error || `Failed to claim invite: ${claimResponse.status}`;
+      let helpText = "";
+      if (claimResponse.status === 404) {
+        helpText = " The invite code may be invalid or misspelled.";
+      } else if (claimResponse.status === 400) {
+        if (errorMessage.includes("already claimed")) {
+          helpText = " This invite has already been used by another agent.";
+        } else if (errorMessage.includes("expired")) {
+          helpText = " Ask the wallet owner to create a new invite.";
+        } else if (errorMessage.includes("revoked")) {
+          helpText = " The wallet owner has revoked this invite.";
+        }
+      }
+      throw new MixrPayError(`${errorMessage}${helpText}`);
+    }
+    const data = await claimResponse.json();
+    return {
+      sessionKey: data.session_key,
+      address: data.address,
+      sessionKeyId: data.session_key_id,
+      expiresAt: new Date(data.expires_at),
+      limits: {
+        budgetUsd: data.limits.budget_usd,
+        budgetPeriod: data.limits.budget_period,
+        maxPerTxUsd: data.limits.max_per_tx_usd
+      },
+      allowedMerchants: data.allowed_merchants || [],
+      inviterName: data.inviter_name || "Anonymous"
+    };
+  }
   // ===========================================================================
   // Core Methods
   // ===========================================================================

package/dist/index.d.cts

@@ -380,7 +380,7 @@ interface SessionStats {
  */
 
 /** Current SDK version */
-declare const SDK_VERSION = "0.6.1";
+declare const SDK_VERSION = "0.8.0";
 /** Supported networks */
 declare const NETWORKS: {
     readonly BASE_MAINNET: {
@@ -511,6 +511,43 @@ interface AgentWithdrawResult {
     /** Remaining balance after withdrawal */
     remainingBalanceUsd: number;
 }
+/**
+ * Options for claiming an agent invite
+ */
+interface AgentClaimInviteOptions {
+    /** The invite code provided by the human wallet owner (e.g., "mixr-abc123") */
+    inviteCode: string;
+    /** The agent's external wallet private key (used for signing, NOT transmitted) */
+    privateKey: `0x${string}`;
+    /** MixrPay API base URL (default: https://www.mixrpay.com) */
+    baseUrl?: string;
+}
+/**
+ * Result from claiming an agent invite
+ */
+interface AgentClaimInviteResult {
+    /** The session key in sk_live_{hex} format - STORE SECURELY! */
+    sessionKey: string;
+    /** The derived public address of the session key */
+    address: string;
+    /** Session key database ID */
+    sessionKeyId: string;
+    /** When the session key expires */
+    expiresAt: Date;
+    /** Budget limits set by the inviter */
+    limits: {
+        /** Total budget in USD */
+        budgetUsd: number;
+        /** Budget period: 'daily', 'monthly', or 'total' */
+        budgetPeriod: string;
+        /** Maximum per transaction in USD (null = no limit) */
+        maxPerTxUsd: number | null;
+    };
+    /** Whitelisted merchants/tools (empty = allow all) */
+    allowedMerchants: string[];
+    /** Name of the person who created the invite */
+    inviterName: string;
+}
 type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'none';
 /**
  * A wallet wrapper for AI agents that handles x402 payments automatically.
@@ -760,6 +797,36 @@ declare class AgentWallet {
      * ```
      */
     static withdraw(options: AgentWithdrawOptions): Promise<AgentWithdrawResult>;
+    /**
+     * Claim an agent invite code to receive a session key for the inviter's wallet.
+     *
+     * This allows an agent to get a pre-configured session key from a human wallet owner
+     * without needing to register their own wallet or fund it. The human sets the budget
+     * limits and merchant whitelist when creating the invite.
+     *
+     * @param options - Claim invite options including the invite code and agent's private key
+     * @returns Claim result with the new session key
+     * @throws {MixrPayError} If claiming fails (e.g., invalid code, already claimed, expired)
+     *
+     * @example
+     * ```typescript
+     * // Human creates invite at their dashboard, shares code "mixr-abc123"
+     *
+     * const result = await AgentWallet.claimInvite({
+     *   inviteCode: 'mixr-abc123',
+     *   privateKey: process.env.AGENT_WALLET_KEY as `0x${string}`,
+     * });
+     *
+     * console.log(`Got session key: ${result.sessionKey}`);
+     * console.log(`Budget: $${result.limits.budgetUsd}/${result.limits.budgetPeriod}`);
+     * console.log(`Invited by: ${result.inviterName}`);
+     *
+     * // Use the session key to make payments
+     * const wallet = new AgentWallet({ sessionKey: result.sessionKey });
+     * const response = await wallet.fetch('https://api.example.com/endpoint');
+     * ```
+     */
+    static claimInvite(options: AgentClaimInviteOptions): Promise<AgentClaimInviteResult>;
     /**
      * Make an HTTP request, automatically handling x402 payment if required.
      *

package/dist/index.d.ts

@@ -380,7 +380,7 @@ interface SessionStats {
  */
 
 /** Current SDK version */
-declare const SDK_VERSION = "0.6.1";
+declare const SDK_VERSION = "0.8.0";
 /** Supported networks */
 declare const NETWORKS: {
     readonly BASE_MAINNET: {
@@ -511,6 +511,43 @@ interface AgentWithdrawResult {
     /** Remaining balance after withdrawal */
     remainingBalanceUsd: number;
 }
+/**
+ * Options for claiming an agent invite
+ */
+interface AgentClaimInviteOptions {
+    /** The invite code provided by the human wallet owner (e.g., "mixr-abc123") */
+    inviteCode: string;
+    /** The agent's external wallet private key (used for signing, NOT transmitted) */
+    privateKey: `0x${string}`;
+    /** MixrPay API base URL (default: https://www.mixrpay.com) */
+    baseUrl?: string;
+}
+/**
+ * Result from claiming an agent invite
+ */
+interface AgentClaimInviteResult {
+    /** The session key in sk_live_{hex} format - STORE SECURELY! */
+    sessionKey: string;
+    /** The derived public address of the session key */
+    address: string;
+    /** Session key database ID */
+    sessionKeyId: string;
+    /** When the session key expires */
+    expiresAt: Date;
+    /** Budget limits set by the inviter */
+    limits: {
+        /** Total budget in USD */
+        budgetUsd: number;
+        /** Budget period: 'daily', 'monthly', or 'total' */
+        budgetPeriod: string;
+        /** Maximum per transaction in USD (null = no limit) */
+        maxPerTxUsd: number | null;
+    };
+    /** Whitelisted merchants/tools (empty = allow all) */
+    allowedMerchants: string[];
+    /** Name of the person who created the invite */
+    inviterName: string;
+}
 type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'none';
 /**
  * A wallet wrapper for AI agents that handles x402 payments automatically.
@@ -760,6 +797,36 @@ declare class AgentWallet {
      * ```
      */
     static withdraw(options: AgentWithdrawOptions): Promise<AgentWithdrawResult>;
+    /**
+     * Claim an agent invite code to receive a session key for the inviter's wallet.
+     *
+     * This allows an agent to get a pre-configured session key from a human wallet owner
+     * without needing to register their own wallet or fund it. The human sets the budget
+     * limits and merchant whitelist when creating the invite.
+     *
+     * @param options - Claim invite options including the invite code and agent's private key
+     * @returns Claim result with the new session key
+     * @throws {MixrPayError} If claiming fails (e.g., invalid code, already claimed, expired)
+     *
+     * @example
+     * ```typescript
+     * // Human creates invite at their dashboard, shares code "mixr-abc123"
+     *
+     * const result = await AgentWallet.claimInvite({
+     *   inviteCode: 'mixr-abc123',
+     *   privateKey: process.env.AGENT_WALLET_KEY as `0x${string}`,
+     * });
+     *
+     * console.log(`Got session key: ${result.sessionKey}`);
+     * console.log(`Budget: $${result.limits.budgetUsd}/${result.limits.budgetPeriod}`);
+     * console.log(`Invited by: ${result.inviterName}`);
+     *
+     * // Use the session key to make payments
+     * const wallet = new AgentWallet({ sessionKey: result.sessionKey });
+     * const response = await wallet.fetch('https://api.example.com/endpoint');
+     * ```
+     */
+    static claimInvite(options: AgentClaimInviteOptions): Promise<AgentClaimInviteResult>;
     /**
      * Make an HTTP request, automatically handling x402 payment if required.
      *

package/dist/index.js

@@ -488,7 +488,7 @@ function getAmountUsd(requirements) {
 }
 
 // src/agent-wallet.ts
-var SDK_VERSION = "0.6.1";
+var SDK_VERSION = "0.8.0";
 var DEFAULT_BASE_URL = process.env.MIXRPAY_BASE_URL || "https://www.mixrpay.com";
 var DEFAULT_TIMEOUT = 3e4;
 var NETWORKS = {
@@ -1104,6 +1104,91 @@ var AgentWallet = class {
       remainingBalanceUsd: data.remaining_balance_usd
     };
   }
+  /**
+   * Claim an agent invite code to receive a session key for the inviter's wallet.
+   * 
+   * This allows an agent to get a pre-configured session key from a human wallet owner
+   * without needing to register their own wallet or fund it. The human sets the budget
+   * limits and merchant whitelist when creating the invite.
+   * 
+   * @param options - Claim invite options including the invite code and agent's private key
+   * @returns Claim result with the new session key
+   * @throws {MixrPayError} If claiming fails (e.g., invalid code, already claimed, expired)
+   * 
+   * @example
+   * ```typescript
+   * // Human creates invite at their dashboard, shares code "mixr-abc123"
+   * 
+   * const result = await AgentWallet.claimInvite({
+   *   inviteCode: 'mixr-abc123',
+   *   privateKey: process.env.AGENT_WALLET_KEY as `0x${string}`,
+   * });
+   * 
+   * console.log(`Got session key: ${result.sessionKey}`);
+   * console.log(`Budget: $${result.limits.budgetUsd}/${result.limits.budgetPeriod}`);
+   * console.log(`Invited by: ${result.inviterName}`);
+   * 
+   * // Use the session key to make payments
+   * const wallet = new AgentWallet({ sessionKey: result.sessionKey });
+   * const response = await wallet.fetch('https://api.example.com/endpoint');
+   * ```
+   */
+  static async claimInvite(options) {
+    const { inviteCode, privateKey } = options;
+    const baseUrl = (options.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, "");
+    const account = privateKeyToAccount2(privateKey);
+    const walletAddress = account.address;
+    const challengeResponse = await fetch(
+      `${baseUrl}/api/v1/agent/challenge?wallet=${walletAddress}&action=claim-invite`
+    );
+    if (!challengeResponse.ok) {
+      const error = await challengeResponse.json().catch(() => ({}));
+      throw new MixrPayError(error.error || `Failed to get challenge: ${challengeResponse.status}`);
+    }
+    const { challenge, message } = await challengeResponse.json();
+    const signature = await signMessage({ message, privateKey });
+    const claimResponse = await fetch(`${baseUrl}/api/v1/agent/claim-invite`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        invite_code: inviteCode,
+        challenge,
+        agent_wallet_address: walletAddress,
+        signature
+      })
+    });
+    if (!claimResponse.ok) {
+      const error = await claimResponse.json().catch(() => ({}));
+      const errorMessage = error.error || `Failed to claim invite: ${claimResponse.status}`;
+      let helpText = "";
+      if (claimResponse.status === 404) {
+        helpText = " The invite code may be invalid or misspelled.";
+      } else if (claimResponse.status === 400) {
+        if (errorMessage.includes("already claimed")) {
+          helpText = " This invite has already been used by another agent.";
+        } else if (errorMessage.includes("expired")) {
+          helpText = " Ask the wallet owner to create a new invite.";
+        } else if (errorMessage.includes("revoked")) {
+          helpText = " The wallet owner has revoked this invite.";
+        }
+      }
+      throw new MixrPayError(`${errorMessage}${helpText}`);
+    }
+    const data = await claimResponse.json();
+    return {
+      sessionKey: data.session_key,
+      address: data.address,
+      sessionKeyId: data.session_key_id,
+      expiresAt: new Date(data.expires_at),
+      limits: {
+        budgetUsd: data.limits.budget_usd,
+        budgetPeriod: data.limits.budget_period,
+        maxPerTxUsd: data.limits.max_per_tx_usd
+      },
+      allowedMerchants: data.allowed_merchants || [],
+      inviterName: data.inviter_name || "Anonymous"
+    };
+  }
   // ===========================================================================
   // Core Methods
   // ===========================================================================

package/package.json

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