@mixrpay/agent-sdk 0.2.0 → 0.3.1

package/README.md

@@ -127,7 +127,7 @@ const session = await wallet.getOrCreateSession({
 });
 
 console.log('Session ID:', session.id);
-console.log('Remaining:', session.remainingUsd);
+console.log('Remaining:', session.remainingLimitUsd);
 console.log('Expires:', session.expiresAt);
 
 // Charge manually
@@ -154,7 +154,7 @@ const response = await fetch('https://api.merchant.com/generate', {
 // List all active sessions
 const sessions = await wallet.listSessions();
 for (const session of sessions) {
-  console.log(`${session.merchantName}: $${session.remainingUsd} remaining`);
+  console.log(`${session.merchantName}: $${session.remainingLimitUsd} remaining`);
 }
 
 // Revoke a session (e.g., when done with a merchant)
@@ -197,8 +197,11 @@ import {
   InsufficientBalanceError,
   SpendingLimitExceededError,
   SessionKeyExpiredError,
+  // Session Authorization Errors
   SessionExpiredError,
   SessionLimitExceededError,
+  SessionNotFoundError,
+  SessionRevokedError,
 } from '@mixrpay/agent-sdk';
 
 const wallet = new AgentWallet({ sessionKey: 'sk_live_...' });
@@ -210,11 +213,15 @@ try {
     console.log(`❌ Not enough funds: need $${error.required}, have $${error.available}`);
     console.log(`   Top up at: ${error.topUpUrl}`);
   } else if (error instanceof SessionExpiredError) {
-    console.log('❌ Session expired, creating new one...');
+    console.log(`❌ Session ${error.sessionId} expired`);
     // SDK will auto-create on next callMerchantApi()
   } else if (error instanceof SessionLimitExceededError) {
-    console.log(`❌ Session limit exceeded: ${error.limitType}`);
-    console.log(`   Limit: $${error.limit}, Requested: $${error.requested}`);
+    console.log(`❌ Session limit exceeded`);
+    console.log(`   Limit: $${error.limit}, Requested: $${error.requested}, Remaining: $${error.remaining}`);
+  } else if (error instanceof SessionNotFoundError) {
+    console.log(`❌ Session ${error.sessionId} not found`);
+  } else if (error instanceof SessionRevokedError) {
+    console.log(`❌ Session ${error.sessionId} was revoked: ${error.reason || 'no reason given'}`);
   } else if (error instanceof SpendingLimitExceededError) {
     console.log(`❌ Session key limit exceeded: ${error.limitType}`);
   } else if (error instanceof SessionKeyExpiredError) {
@@ -372,24 +379,41 @@ new AgentWallet({
 ### Types
 
 ```typescript
-interface Session {
+interface SessionAuthorization {
   id: string;
-  merchantPublicKey: string;
-  merchantName?: string;
+  merchantId: string;
+  merchantName: string;
+  status: 'pending' | 'active' | 'expired' | 'revoked';
   spendingLimitUsd: number;
-  spentUsd: number;
-  remainingUsd: number;
-  status: 'active' | 'expired' | 'revoked';
+  amountUsedUsd: number;
+  remainingLimitUsd: number;
   expiresAt: Date;
   createdAt: Date;
 }
 
+interface SessionStats {
+  activeCount: number;
+  expiredCount: number;
+  revokedCount: number;
+  totalAuthorizedUsd: number;
+  totalSpentUsd: number;
+  totalRemainingUsd: number;
+  activeSessions: Array<{
+    id: string;
+    merchantName: string;
+    merchantPublicKey: string;
+    spendingLimitUsd: number;
+    remainingUsd: number;
+    expiresAt: Date;
+  }>;
+}
+
 interface ChargeResult {
   success: boolean;
   chargeId: string;
   amountUsd: number;
   txHash?: string;
-  remainingUsd: number;
+  remainingSessionBalanceUsd: number;
 }
 
 interface PaymentEvent {

package/dist/index.cjs

@@ -21,28 +21,18 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   AgentWallet: () => AgentWallet,
-  DEFAULT_BASE_URL: () => DEFAULT_BASE_URL,
-  DEFAULT_FACILITATOR_URL: () => DEFAULT_FACILITATOR_URL,
-  DEFAULT_TIMEOUT: () => DEFAULT_TIMEOUT,
   InsufficientBalanceError: () => InsufficientBalanceError,
   InvalidSessionKeyError: () => InvalidSessionKeyError,
   MixrPayError: () => MixrPayError,
-  NETWORKS: () => NETWORKS,
   PaymentFailedError: () => PaymentFailedError,
   SDK_VERSION: () => SDK_VERSION,
-  SessionKey: () => SessionKey,
+  SessionExpiredError: () => SessionExpiredError,
   SessionKeyExpiredError: () => SessionKeyExpiredError,
+  SessionLimitExceededError: () => SessionLimitExceededError,
+  SessionNotFoundError: () => SessionNotFoundError,
+  SessionRevokedError: () => SessionRevokedError,
   SpendingLimitExceededError: () => SpendingLimitExceededError,
-  X402ProtocolError: () => X402ProtocolError,
-  buildTransferAuthorizationData: () => buildTransferAuthorizationData,
-  buildXPaymentHeader: () => buildXPaymentHeader,
-  generateNonce: () => generateNonce,
-  getAmountUsd: () => getAmountUsd,
-  getErrorMessage: () => getErrorMessage,
-  isMixrPayError: () => isMixrPayError,
-  isPaymentExpired: () => isPaymentExpired,
-  parse402Response: () => parse402Response,
-  validatePaymentAmount: () => validatePaymentAmount
+  isMixrPayError: () => isMixrPayError
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -159,17 +149,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;
   }
-  if (error instanceof Error) {
-    return error.message;
+};
+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;
   }
-  return String(error);
+};
+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;
+  }
+};
+function isMixrPayError(error) {
+  return error instanceof MixrPayError;
 }
 
 // src/session-key.ts
@@ -396,21 +440,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.1";
 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 },
@@ -1166,6 +1199,63 @@ var AgentWallet = class {
     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.
    * 
@@ -1206,21 +1296,29 @@ var AgentWallet = class {
     });
     if (!response.ok) {
       const error = await response.json().catch(() => ({}));
+      const errorCode = error.error || error.error_code || "";
       if (response.status === 402) {
-        if (error.error === "session_limit_exceeded") {
-          throw new SpendingLimitExceededError(
-            "session",
-            error.sessionLimitUsd || error.session_limit_usd || 0,
-            amountUsd
-          );
+        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 (error.error === "insufficient_balance") {
+        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();
@@ -1315,7 +1413,8 @@ var AgentWallet = class {
     }
     if (response.status === 402) {
       const errorData = await response.json().catch(() => ({}));
-      if (errorData.error === "session_expired") {
+      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,
@@ -1330,17 +1429,21 @@ var AgentWallet = class {
           signal: AbortSignal.timeout(this.timeout)
         });
       }
-      if (errorData.error === "session_limit_exceeded") {
-        throw new SpendingLimitExceededError(
-          "session",
-          errorData.sessionLimitUsd || 0,
-          priceUsd || 0
-        );
+      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 (errorData.error === "insufficient_balance") {
+      if (errorCode === "insufficient_balance") {
         throw new InsufficientBalanceError(
           priceUsd || 0,
-          errorData.availableUsd || 0
+          errorData.availableUsd || errorData.available_usd || 0
         );
       }
     }
@@ -1368,26 +1471,16 @@ var AgentWallet = class {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   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
 });