@mixrpay/agent-sdk 0.1.1 → 0.2.0

package/dist/index.cjs

@@ -204,6 +204,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.
    * 
@@ -244,6 +251,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 (0, import_accounts.signMessage)({
+      privateKey: this.privateKey,
+      message
+    });
+  }
   /**
    * Get the chain ID based on whether this is a test key.
    */
@@ -276,6 +295,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) {
@@ -953,6 +985,385 @@ 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;
+  }
+  /**
+   * 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(() => ({}));
+      if (response.status === 402) {
+        if (error.error === "session_limit_exceeded") {
+          throw new SpendingLimitExceededError(
+            "session",
+            error.sessionLimitUsd || error.session_limit_usd || 0,
+            amountUsd
+          );
+        }
+        if (error.error === "insufficient_balance") {
+          throw new InsufficientBalanceError(
+            amountUsd,
+            error.availableUsd || error.available_usd || 0
+          );
+        }
+      }
+      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(() => ({}));
+      if (errorData.error === "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 (errorData.error === "session_limit_exceeded") {
+        throw new SpendingLimitExceededError(
+          "session",
+          errorData.sessionLimitUsd || 0,
+          priceUsd || 0
+        );
+      }
+      if (errorData.error === "insufficient_balance") {
+        throw new InsufficientBalanceError(
+          priceUsd || 0,
+          errorData.availableUsd || 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)
+    };
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {