@mixrpay/agent-sdk 0.1.1 → 0.3.0

package/dist/index.js

@@ -1,7 +1,8 @@
 // src/session-key.ts
 import {
   privateKeyToAccount,
-  signTypedData
+  signTypedData,
+  signMessage as viemSignMessage
 } from "viem/accounts";
 
 // src/errors.ts
@@ -114,17 +115,71 @@ var X402ProtocolError = class extends MixrPayError {
     this.reason = reason;
   }
 };
-function isMixrPayError(error) {
-  return error instanceof MixrPayError;
-}
-function getErrorMessage(error) {
-  if (error instanceof MixrPayError) {
-    return error.message;
+var SessionExpiredError = class extends MixrPayError {
+  /** ID of the expired session */
+  sessionId;
+  /** When the session expired (ISO string or Date) */
+  expiredAt;
+  constructor(sessionId, expiredAt) {
+    super(
+      `Session ${sessionId} has expired${expiredAt ? ` at ${expiredAt}` : ""}. A new session will be created automatically on your next request.`,
+      "SESSION_EXPIRED"
+    );
+    this.name = "SessionExpiredError";
+    this.sessionId = sessionId;
+    this.expiredAt = expiredAt;
+  }
+};
+var SessionLimitExceededError = class extends MixrPayError {
+  /** ID of the session */
+  sessionId;
+  /** The session's spending limit in USD */
+  limit;
+  /** The amount requested in USD */
+  requested;
+  /** Remaining balance in the session (limit - used) */
+  remaining;
+  constructor(limit, requested, remaining, sessionId) {
+    super(
+      `Session spending limit exceeded: limit is $${limit.toFixed(2)}, requested $${requested.toFixed(2)}, remaining $${remaining.toFixed(2)}. Create a new session with a higher limit to continue.`,
+      "SESSION_LIMIT_EXCEEDED"
+    );
+    this.name = "SessionLimitExceededError";
+    this.sessionId = sessionId;
+    this.limit = limit;
+    this.requested = requested;
+    this.remaining = remaining;
+  }
+};
+var SessionNotFoundError = class extends MixrPayError {
+  /** The session ID that was not found */
+  sessionId;
+  constructor(sessionId) {
+    super(
+      `Session ${sessionId} not found. It may have been deleted or never existed. Create a new session with getOrCreateSession().`,
+      "SESSION_NOT_FOUND"
+    );
+    this.name = "SessionNotFoundError";
+    this.sessionId = sessionId;
   }
-  if (error instanceof Error) {
-    return error.message;
+};
+var SessionRevokedError = class extends MixrPayError {
+  /** The session ID that was revoked */
+  sessionId;
+  /** Optional reason for revocation */
+  reason;
+  constructor(sessionId, reason) {
+    super(
+      `Session ${sessionId} has been revoked${reason ? `: ${reason}` : ""}. Create a new session with getOrCreateSession().`,
+      "SESSION_REVOKED"
+    );
+    this.name = "SessionRevokedError";
+    this.sessionId = sessionId;
+    this.reason = reason;
   }
-  return String(error);
+};
+function isMixrPayError(error) {
+  return error instanceof MixrPayError;
 }
 
 // src/session-key.ts
@@ -159,6 +214,13 @@ var SessionKey = class _SessionKey {
     this.address = this.account.address;
     this.isTest = isTest;
   }
+  /**
+   * Get the private key as hex string (without 0x prefix).
+   * Used for API authentication headers.
+   */
+  get privateKeyHex() {
+    return this.privateKey.slice(2);
+  }
   /**
    * Parse a session key string into a SessionKey object.
    * 
@@ -199,6 +261,18 @@ var SessionKey = class _SessionKey {
       message
     });
   }
+  /**
+   * Sign a plain message (EIP-191 personal sign).
+   * 
+   * @param message - Message to sign
+   * @returns Hex-encoded signature
+   */
+  async signMessage(message) {
+    return viemSignMessage({
+      privateKey: this.privateKey,
+      message
+    });
+  }
   /**
    * Get the chain ID based on whether this is a test key.
    */
@@ -231,6 +305,19 @@ function generateNonce() {
   crypto.getRandomValues(bytes);
   return `0x${Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("")}`;
 }
+function buildSessionAuthMessage(timestamp, address) {
+  return `MixrPay:${timestamp}:${address.toLowerCase()}`;
+}
+async function createSessionAuthPayload(sessionKey) {
+  const timestamp = Date.now();
+  const message = buildSessionAuthMessage(timestamp, sessionKey.address);
+  const signature = await sessionKey.signMessage(message);
+  return {
+    address: sessionKey.address,
+    timestamp,
+    signature
+  };
+}
 
 // src/x402.ts
 async function parse402Response(response) {
@@ -319,21 +406,10 @@ function isPaymentExpired(requirements) {
 function getAmountUsd(requirements) {
   return Number(requirements.amount) / 1e6;
 }
-function validatePaymentAmount(amountUsd, maxPaymentUsd) {
-  if (amountUsd <= 0) {
-    throw new X402ProtocolError(`Invalid payment amount: $${amountUsd.toFixed(2)}`);
-  }
-  if (maxPaymentUsd !== void 0 && amountUsd > maxPaymentUsd) {
-    throw new X402ProtocolError(
-      `Payment amount $${amountUsd.toFixed(2)} exceeds client limit $${maxPaymentUsd.toFixed(2)}`
-    );
-  }
-}
 
 // src/agent-wallet.ts
-var SDK_VERSION = "0.1.0";
+var SDK_VERSION = "0.3.0";
 var DEFAULT_BASE_URL = process.env.MIXRPAY_BASE_URL || "https://mixrpay.com";
-var DEFAULT_FACILITATOR_URL = "https://x402.org/facilitator";
 var DEFAULT_TIMEOUT = 3e4;
 var NETWORKS = {
   BASE_MAINNET: { chainId: 8453, name: "Base", isTestnet: false },
@@ -908,29 +984,468 @@ var AgentWallet = class {
   setLogLevel(level) {
     this.logger.setLevel(level);
   }
+  // ===========================================================================
+  // Session Authorization Methods (for MixrPay Merchants)
+  // ===========================================================================
+  /**
+   * Create the X-Session-Auth header for secure API authentication.
+   * Uses signature-based authentication - private key is NEVER transmitted.
+   * 
+   * @returns Headers object with X-Session-Auth
+   */
+  async getSessionAuthHeaders() {
+    const payload = await createSessionAuthPayload(this.sessionKey);
+    return {
+      "X-Session-Auth": JSON.stringify(payload)
+    };
+  }
+  /**
+   * Get an existing session or create a new one with a MixrPay merchant.
+   * 
+   * This is the recommended way to interact with MixrPay-enabled APIs.
+   * If an active session exists, it will be returned. Otherwise, a new
+   * session authorization request will be created and confirmed.
+   * 
+   * @param options - Session creation options
+   * @returns Active session authorization
+   * 
+   * @throws {MixrPayError} If merchant is not found or session creation fails
+   * 
+   * @example
+   * ```typescript
+   * const session = await wallet.getOrCreateSession({
+   *   merchantPublicKey: 'pk_live_abc123...',
+   *   spendingLimitUsd: 25.00,
+   *   durationDays: 7,
+   * });
+   * 
+   * console.log(`Session active: $${session.remainingLimitUsd} remaining`);
+   * ```
+   */
+  async getOrCreateSession(options) {
+    this.logger.debug("getOrCreateSession called", options);
+    const { merchantPublicKey, spendingLimitUsd = 25, durationDays = 7 } = options;
+    try {
+      const existingSession = await this.getSessionByMerchant(merchantPublicKey);
+      if (existingSession && existingSession.status === "active") {
+        this.logger.debug("Found existing active session", existingSession.id);
+        return existingSession;
+      }
+    } catch {
+    }
+    this.logger.info(`Creating new session with merchant ${merchantPublicKey.slice(0, 20)}...`);
+    const authHeaders = await this.getSessionAuthHeaders();
+    const authorizeResponse = await fetch(`${this.baseUrl}/api/v2/session/authorize`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...authHeaders
+      },
+      body: JSON.stringify({
+        merchant_public_key: merchantPublicKey,
+        spending_limit_usd: spendingLimitUsd,
+        duration_days: durationDays
+      })
+    });
+    if (!authorizeResponse.ok) {
+      const error = await authorizeResponse.json().catch(() => ({}));
+      throw new MixrPayError(
+        error.message || error.error || `Failed to create session: ${authorizeResponse.status}`
+      );
+    }
+    const authorizeData = await authorizeResponse.json();
+    const sessionId = authorizeData.session_id;
+    const messageToSign = authorizeData.message_to_sign;
+    if (!sessionId || !messageToSign) {
+      throw new MixrPayError("Invalid authorize response: missing session_id or message_to_sign");
+    }
+    this.logger.debug("Signing session authorization message...");
+    const signature = await this.sessionKey.signMessage(messageToSign);
+    const confirmResponse = await fetch(`${this.baseUrl}/api/v2/session/confirm`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        session_id: sessionId,
+        signature,
+        wallet_address: this.walletAddress
+      })
+    });
+    if (!confirmResponse.ok) {
+      const error = await confirmResponse.json().catch(() => ({}));
+      throw new MixrPayError(
+        error.message || `Failed to confirm session: ${confirmResponse.status}`
+      );
+    }
+    const confirmData = await confirmResponse.json();
+    this.logger.info(`Session created: ${confirmData.session?.id || sessionId}`);
+    return this.parseSessionResponse(confirmData.session || confirmData);
+  }
+  /**
+   * Get session status for a specific merchant.
+   * 
+   * @param merchantPublicKey - The merchant's public key
+   * @returns Session authorization or null if not found
+   */
+  async getSessionByMerchant(merchantPublicKey) {
+    this.logger.debug("getSessionByMerchant", merchantPublicKey);
+    const authHeaders = await this.getSessionAuthHeaders();
+    const response = await fetch(`${this.baseUrl}/api/v2/session/status?merchant_public_key=${encodeURIComponent(merchantPublicKey)}`, {
+      headers: authHeaders
+    });
+    if (response.status === 404) {
+      return null;
+    }
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new MixrPayError(error.message || `Failed to get session: ${response.status}`);
+    }
+    const data = await response.json();
+    return data.session ? this.parseSessionResponse(data.session) : null;
+  }
+  /**
+   * List all session authorizations for this wallet.
+   * 
+   * @returns Array of session authorizations
+   * 
+   * @example
+   * ```typescript
+   * const sessions = await wallet.listSessions();
+   * for (const session of sessions) {
+   *   console.log(`${session.merchantName}: $${session.remainingLimitUsd} remaining`);
+   * }
+   * ```
+   */
+  async listSessions() {
+    this.logger.debug("listSessions");
+    const authHeaders = await this.getSessionAuthHeaders();
+    const response = await fetch(`${this.baseUrl}/api/v2/session/list`, {
+      headers: authHeaders
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new MixrPayError(error.message || `Failed to list sessions: ${response.status}`);
+    }
+    const data = await response.json();
+    return (data.sessions || []).map((s) => this.parseSessionResponse(s));
+  }
+  /**
+   * Revoke a session authorization.
+   * 
+   * After revocation, no further charges can be made against this session.
+   * 
+   * @param sessionId - The session ID to revoke
+   * @returns true if revoked successfully
+   * 
+   * @example
+   * ```typescript
+   * const revoked = await wallet.revokeSession('sess_abc123');
+   * if (revoked) {
+   *   console.log('Session revoked successfully');
+   * }
+   * ```
+   */
+  async revokeSession(sessionId) {
+    this.logger.debug("revokeSession", sessionId);
+    const authHeaders = await this.getSessionAuthHeaders();
+    const response = await fetch(`${this.baseUrl}/api/v2/session/revoke`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...authHeaders
+      },
+      body: JSON.stringify({ session_id: sessionId })
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      this.logger.error("Failed to revoke session:", error);
+      return false;
+    }
+    this.logger.info(`Session ${sessionId} revoked`);
+    return true;
+  }
+  /**
+   * Get statistics about all session authorizations.
+   * 
+   * This provides an overview of active, expired, and revoked sessions,
+   * along with aggregate spending information.
+   * 
+   * @returns Session statistics
+   * 
+   * @example
+   * ```typescript
+   * const stats = await wallet.getSessionStats();
+   * console.log(`Active sessions: ${stats.activeCount}`);
+   * console.log(`Total authorized: $${stats.totalAuthorizedUsd.toFixed(2)}`);
+   * console.log(`Total remaining: $${stats.totalRemainingUsd.toFixed(2)}`);
+   * 
+   * for (const session of stats.activeSessions) {
+   *   console.log(`${session.merchantName}: $${session.remainingUsd} remaining`);
+   * }
+   * ```
+   */
+  async getSessionStats() {
+    this.logger.debug("getSessionStats");
+    const sessions = await this.listSessions();
+    const now = /* @__PURE__ */ new Date();
+    const active = [];
+    const expired = [];
+    const revoked = [];
+    for (const session of sessions) {
+      if (session.status === "revoked") {
+        revoked.push(session);
+      } else if (session.status === "expired" || session.expiresAt && session.expiresAt < now) {
+        expired.push(session);
+      } else if (session.status === "active") {
+        active.push(session);
+      }
+    }
+    const totalAuthorizedUsd = active.reduce((sum, s) => sum + s.spendingLimitUsd, 0);
+    const totalSpentUsd = sessions.reduce((sum, s) => sum + s.amountUsedUsd, 0);
+    const totalRemainingUsd = active.reduce((sum, s) => sum + s.remainingLimitUsd, 0);
+    return {
+      activeCount: active.length,
+      expiredCount: expired.length,
+      revokedCount: revoked.length,
+      totalAuthorizedUsd,
+      totalSpentUsd,
+      totalRemainingUsd,
+      activeSessions: active.map((s) => ({
+        id: s.id,
+        merchantName: s.merchantName,
+        merchantPublicKey: s.merchantId,
+        // merchantId is the public key in this context
+        spendingLimitUsd: s.spendingLimitUsd,
+        remainingUsd: s.remainingLimitUsd,
+        expiresAt: s.expiresAt
+      }))
+    };
+  }
+  /**
+   * Charge against an active session authorization.
+   * 
+   * This is useful when you need to manually charge a session outside of
+   * the `callMerchantApi()` flow.
+   * 
+   * @param sessionId - The session ID to charge
+   * @param amountUsd - Amount to charge in USD
+   * @param options - Additional charge options
+   * @returns Charge result
+   * 
+   * @example
+   * ```typescript
+   * const result = await wallet.chargeSession('sess_abc123', 0.05, {
+   *   feature: 'ai-generation',
+   *   idempotencyKey: 'unique-key-123',
+   * });
+   * 
+   * console.log(`Charged $${result.amountUsd}, remaining: $${result.remainingSessionBalanceUsd}`);
+   * ```
+   */
+  async chargeSession(sessionId, amountUsd, options = {}) {
+    this.logger.debug("chargeSession", { sessionId, amountUsd, options });
+    const authHeaders = await this.getSessionAuthHeaders();
+    const response = await fetch(`${this.baseUrl}/api/v2/charge`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...authHeaders
+      },
+      body: JSON.stringify({
+        session_id: sessionId,
+        price_usd: amountUsd,
+        feature: options.feature,
+        idempotency_key: options.idempotencyKey,
+        metadata: options.metadata
+      })
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      const errorCode = error.error || error.error_code || "";
+      if (response.status === 402) {
+        if (errorCode === "session_limit_exceeded") {
+          const limit = error.sessionLimitUsd || error.session_limit_usd || 0;
+          const remaining = error.remainingUsd || error.remaining_usd || 0;
+          throw new SessionLimitExceededError(limit, amountUsd, remaining, sessionId);
+        }
+        if (errorCode === "insufficient_balance") {
+          throw new InsufficientBalanceError(
+            amountUsd,
+            error.availableUsd || error.available_usd || 0
+          );
+        }
+      }
+      if (response.status === 404 || errorCode === "session_not_found") {
+        throw new SessionNotFoundError(sessionId);
+      }
+      if (errorCode === "session_expired") {
+        throw new SessionExpiredError(sessionId, error.expiredAt || error.expires_at);
+      }
+      if (errorCode === "session_revoked") {
+        throw new SessionRevokedError(sessionId, error.reason);
+      }
+      throw new MixrPayError(error.message || `Charge failed: ${response.status}`);
+    }
+    const data = await response.json();
+    this.logger.payment(amountUsd, sessionId, options.feature);
+    return {
+      success: true,
+      chargeId: data.chargeId || data.charge_id,
+      amountUsd: data.amountUsd || data.amount_usd || amountUsd,
+      txHash: data.txHash || data.tx_hash,
+      remainingSessionBalanceUsd: data.remainingSessionBalanceUsd || data.remaining_session_balance_usd || 0
+    };
+  }
+  /**
+   * Call a MixrPay merchant's API with automatic session management.
+   * 
+   * This is the recommended way to interact with MixrPay-enabled APIs.
+   * It automatically:
+   * 1. Gets or creates a session authorization
+   * 2. Adds the `X-Mixr-Session` header to the request
+   * 3. Handles payment errors and session expiration
+   * 
+   * @param options - API call options
+   * @returns Response from the merchant API
+   * 
+   * @example
+   * ```typescript
+   * const response = await wallet.callMerchantApi({
+   *   url: 'https://api.merchant.com/generate',
+   *   merchantPublicKey: 'pk_live_abc123...',
+   *   method: 'POST',
+   *   body: { prompt: 'Hello world' },
+   *   priceUsd: 0.05,
+   * });
+   * 
+   * const data = await response.json();
+   * ```
+   */
+  async callMerchantApi(options) {
+    const {
+      url,
+      method = "POST",
+      body,
+      headers: customHeaders = {},
+      merchantPublicKey,
+      priceUsd,
+      feature
+    } = options;
+    this.logger.debug("callMerchantApi", { url, method, merchantPublicKey, priceUsd });
+    if (priceUsd !== void 0 && this.maxPaymentUsd !== void 0 && priceUsd > this.maxPaymentUsd) {
+      throw new SpendingLimitExceededError("client_max", this.maxPaymentUsd, priceUsd);
+    }
+    const session = await this.getOrCreateSession({
+      merchantPublicKey,
+      spendingLimitUsd: 25,
+      // Default limit
+      durationDays: 7
+    });
+    const headers = {
+      "Content-Type": "application/json",
+      "X-Mixr-Session": session.id,
+      ...customHeaders
+    };
+    if (feature) {
+      headers["X-Mixr-Feature"] = feature;
+    }
+    const requestBody = body !== void 0 ? typeof body === "string" ? body : JSON.stringify(body) : void 0;
+    const response = await fetch(url, {
+      method,
+      headers,
+      body: requestBody,
+      signal: AbortSignal.timeout(this.timeout)
+    });
+    const chargedAmount = response.headers.get("X-Mixr-Charged");
+    if (chargedAmount) {
+      const amountUsd = parseFloat(chargedAmount);
+      if (!isNaN(amountUsd)) {
+        const payment = {
+          amountUsd,
+          recipient: merchantPublicKey,
+          txHash: response.headers.get("X-Payment-TxHash"),
+          timestamp: /* @__PURE__ */ new Date(),
+          description: feature || "API call",
+          url
+        };
+        this.payments.push(payment);
+        this.totalSpentUsd += amountUsd;
+        this.logger.payment(amountUsd, merchantPublicKey, feature);
+        if (this.onPayment) {
+          this.onPayment(payment);
+        }
+      }
+    }
+    if (response.status === 402) {
+      const errorData = await response.json().catch(() => ({}));
+      const errorCode = errorData.error || errorData.error_code || "";
+      if (errorCode === "session_expired") {
+        this.logger.info("Session expired, creating new one...");
+        const newSession = await this.getOrCreateSession({
+          merchantPublicKey,
+          spendingLimitUsd: 25,
+          durationDays: 7
+        });
+        headers["X-Mixr-Session"] = newSession.id;
+        return fetch(url, {
+          method,
+          headers,
+          body: requestBody,
+          signal: AbortSignal.timeout(this.timeout)
+        });
+      }
+      if (errorCode === "session_limit_exceeded") {
+        const limit = errorData.sessionLimitUsd || errorData.session_limit_usd || 0;
+        const remaining = errorData.remainingUsd || errorData.remaining_usd || 0;
+        throw new SessionLimitExceededError(limit, priceUsd || 0, remaining, session.id);
+      }
+      if (errorCode === "session_revoked") {
+        throw new SessionRevokedError(session.id, errorData.reason);
+      }
+      if (errorCode === "session_not_found") {
+        throw new SessionNotFoundError(session.id);
+      }
+      if (errorCode === "insufficient_balance") {
+        throw new InsufficientBalanceError(
+          priceUsd || 0,
+          errorData.availableUsd || errorData.available_usd || 0
+        );
+      }
+    }
+    return response;
+  }
+  /**
+   * Parse session response data into SessionAuthorization object.
+   */
+  parseSessionResponse(data) {
+    return {
+      id: data.id || data.session_id || data.sessionId,
+      merchantId: data.merchantId || data.merchant_id,
+      merchantName: data.merchantName || data.merchant_name || "Unknown",
+      status: data.status || "active",
+      spendingLimitUsd: Number(data.spendingLimitUsd || data.spending_limit_usd || data.spendingLimit || 0),
+      amountUsedUsd: Number(data.amountUsedUsd || data.amount_used_usd || data.amountUsed || 0),
+      remainingLimitUsd: Number(
+        data.remainingLimitUsd || data.remaining_limit_usd || data.remainingLimit || Number(data.spendingLimitUsd || data.spending_limit_usd || 0) - Number(data.amountUsedUsd || data.amount_used_usd || 0)
+      ),
+      expiresAt: new Date(data.expiresAt || data.expires_at),
+      createdAt: new Date(data.createdAt || data.created_at)
+    };
+  }
 };
 export {
   AgentWallet,
-  DEFAULT_BASE_URL,
-  DEFAULT_FACILITATOR_URL,
-  DEFAULT_TIMEOUT,
   InsufficientBalanceError,
   InvalidSessionKeyError,
   MixrPayError,
-  NETWORKS,
   PaymentFailedError,
   SDK_VERSION,
-  SessionKey,
+  SessionExpiredError,
   SessionKeyExpiredError,
+  SessionLimitExceededError,
+  SessionNotFoundError,
+  SessionRevokedError,
   SpendingLimitExceededError,
-  X402ProtocolError,
-  buildTransferAuthorizationData,
-  buildXPaymentHeader,
-  generateNonce,
-  getAmountUsd,
-  getErrorMessage,
-  isMixrPayError,
-  isPaymentExpired,
-  parse402Response,
-  validatePaymentAmount
+  isMixrPayError
 };

package/package.json

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