@mixrpay/agent-sdk 0.2.0 → 0.3.1

package/dist/index.d.ts

@@ -1,5 +1,3 @@
-import { Hex } from 'viem';
-
 /**
  * MixrPay Agent SDK - Type definitions
  *
@@ -124,29 +122,6 @@ interface PaymentEvent {
     /** URL that triggered the payment */
     url?: string;
 }
-/**
- * Payment requirements parsed from a 402 response.
- *
- * This represents what the server is asking for in exchange for the resource.
- */
-interface PaymentRequirements {
-    /** Address to send payment to */
-    recipient: string;
-    /** Amount in USDC minor units (6 decimals). 1000000 = $1.00 */
-    amount: bigint;
-    /** Currency code (currently only "USDC" is supported) */
-    currency: string;
-    /** Chain ID (8453 for Base mainnet, 84532 for Base Sepolia) */
-    chainId: number;
-    /** URL where the payment should be submitted */
-    facilitatorUrl: string;
-    /** Unique nonce for this payment request */
-    nonce: string;
-    /** Unix timestamp when this payment request expires */
-    expiresAt: number;
-    /** Human-readable description of the payment */
-    description?: string;
-}
 /**
  * Information about a session key.
  */
@@ -221,97 +196,6 @@ interface DiagnosticsResult {
     /** Wallet address */
     walletAddress: string;
 }
-/**
- * The X-PAYMENT header payload structure.
- *
- * This is what gets base64-encoded and sent in the X-PAYMENT header.
- */
-interface X402PaymentPayload {
-    /** Protocol version (currently 1) */
-    x402Version: number;
-    /** Payment scheme ('exact' for USDC transfers) */
-    scheme: 'exact';
-    /** Network identifier */
-    network: 'base' | 'base-sepolia';
-    /** Payment payload containing signature and authorization */
-    payload: {
-        /** EIP-712 signature of the transferWithAuthorization */
-        signature: string;
-        /** TransferWithAuthorization parameters */
-        authorization: {
-            /** Sender address (smart wallet) */
-            from: string;
-            /** Recipient address */
-            to: string;
-            /** Amount in USDC minor units as string */
-            value: string;
-            /** Unix timestamp after which the authorization is valid */
-            validAfter: string;
-            /** Unix timestamp before which the authorization is valid */
-            validBefore: string;
-            /** Unique nonce (32 bytes hex) */
-            nonce: string;
-        };
-    };
-}
-/**
- * EIP-712 domain for USDC transferWithAuthorization.
- */
-interface EIP712Domain {
-    /** Contract name ('USD Coin' for USDC) */
-    name: string;
-    /** Contract version ('2' for USDC) */
-    version: string;
-    /** Chain ID */
-    chainId: number;
-    /** USDC contract address */
-    verifyingContract: `0x${string}`;
-}
-/**
- * EIP-3009 TransferWithAuthorization message structure.
- */
-interface TransferWithAuthorizationMessage {
-    /** Sender address */
-    from: `0x${string}`;
-    /** Recipient address */
-    to: `0x${string}`;
-    /** Amount in minor units */
-    value: bigint;
-    /** Unix timestamp after which the authorization is valid */
-    validAfter: bigint;
-    /** Unix timestamp before which the authorization is valid */
-    validBefore: bigint;
-    /** Unique nonce (32 bytes) */
-    nonce: `0x${string}`;
-}
-/**
- * Response from the wallet balance endpoint.
- */
-interface WalletBalanceResponse {
-    /** Balance in USD */
-    balanceUsd: number;
-    /** Balance in USDC minor units as string */
-    balanceMinor: string;
-    /** Currency code */
-    currency: string;
-    /** Wallet address */
-    walletAddress: string;
-}
-/**
- * Response from the session key stats endpoint.
- */
-interface SessionKeyStatsResponse {
-    /** Total spent in USD */
-    totalSpentUsd: number;
-    /** Number of transactions */
-    txCount: number;
-    /** Remaining daily limit in USD (null if no limit) */
-    remainingDailyUsd: number | null;
-    /** Remaining total limit in USD (null if no limit) */
-    remainingTotalUsd: number | null;
-    /** Expiration timestamp ISO string (null if never) */
-    expiresAt: string | null;
-}
 /**
  * Options for creating a session authorization with a MixrPay merchant.
  */
@@ -422,6 +306,34 @@ interface ChargeResult {
     /** Remaining session balance in USD */
     remainingSessionBalanceUsd: number;
 }
+/**
+ * Statistics about session authorizations.
+ *
+ * This provides an overview of all sessions managed by the wallet.
+ */
+interface SessionStats {
+    /** Number of active sessions */
+    activeCount: number;
+    /** Number of expired sessions */
+    expiredCount: number;
+    /** Number of revoked sessions */
+    revokedCount: number;
+    /** Total amount authorized across all active sessions in USD */
+    totalAuthorizedUsd: number;
+    /** Total amount spent across all sessions in USD */
+    totalSpentUsd: number;
+    /** Total remaining across all active sessions in USD */
+    totalRemainingUsd: number;
+    /** List of active sessions (summary) */
+    activeSessions: Array<{
+        id: string;
+        merchantName: string;
+        merchantPublicKey: string;
+        spendingLimitUsd: number;
+        remainingUsd: number;
+        expiresAt: Date;
+    }>;
+}
 
 /**
  * MixrPay Agent SDK - AgentWallet
@@ -447,13 +359,7 @@ interface ChargeResult {
  */
 
 /** Current SDK version */
-declare const SDK_VERSION = "0.1.0";
-/** Default API base URL - override with baseUrl option or MIXRPAY_BASE_URL env var */
-declare const DEFAULT_BASE_URL: string;
-/** Default x402 facilitator URL */
-declare const DEFAULT_FACILITATOR_URL = "https://x402.org/facilitator";
-/** Default request timeout in milliseconds */
-declare const DEFAULT_TIMEOUT = 30000;
+declare const SDK_VERSION = "0.3.1";
 /** Supported networks */
 declare const NETWORKS: {
     readonly BASE_MAINNET: {
@@ -766,6 +672,27 @@ declare class AgentWallet {
      * ```
      */
     revokeSession(sessionId: string): Promise<boolean>;
+    /**
+     * 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`);
+     * }
+     * ```
+     */
+    getSessionStats(): Promise<SessionStats>;
     /**
      * Charge against an active session authorization.
      *
@@ -1016,189 +943,136 @@ declare class InvalidSessionKeyError extends MixrPayError {
     constructor(reason?: string);
 }
 /**
- * Thrown when there's an error in x402 protocol handling.
+ * Thrown when a session authorization has expired.
  *
- * This indicates a problem with the payment protocol, usually due to:
- * - Malformed 402 response from server
- * - Missing required payment fields
- * - Invalid payment parameters
- * - Protocol version mismatch
+ * Session authorizations have an expiration date set when created. Once expired,
+ * the session can no longer be used for payments.
  *
  * ## Resolution
- * This is usually a server-side issue. Contact the API provider if the error persists.
+ * Create a new session with the merchant using `wallet.getOrCreateSession()`.
+ * The SDK will automatically create a new session on the next `callMerchantApi()` call.
  *
  * @example
  * ```typescript
  * catch (error) {
- *   if (error instanceof X402ProtocolError) {
- *     console.log(`Protocol error: ${error.reason}`);
- *     // Contact API provider or check server configuration
+ *   if (error instanceof SessionExpiredError) {
+ *     console.log(`Session ${error.sessionId} expired at ${error.expiredAt}`);
+ *     // SDK will auto-create new session on next callMerchantApi()
  *   }
  * }
  * ```
  */
-declare class X402ProtocolError extends MixrPayError {
-    /** Detailed reason for the protocol error */
-    readonly reason: string;
-    constructor(reason: string);
+declare class SessionExpiredError extends MixrPayError {
+    /** ID of the expired session */
+    readonly sessionId: string;
+    /** When the session expired (ISO string or Date) */
+    readonly expiredAt?: string;
+    constructor(sessionId: string, expiredAt?: string);
 }
 /**
- * Check if an error is a MixrPay SDK error.
+ * Thrown when a payment would exceed the session's spending limit.
  *
- * @param error - The error to check
- * @returns true if the error is a MixrPayError or subclass
+ * Each session authorization has a spending limit set by the user. Once the limit
+ * is reached, no more payments can be made until a new session is created.
+ *
+ * ## Resolution
+ * - Create a new session with a higher limit
+ * - Wait for the current session to be renewed (if auto-renewal is enabled)
  *
  * @example
  * ```typescript
- * try {
- *   await wallet.fetch(...);
- * } catch (error) {
- *   if (isMixrPayError(error)) {
- *     console.log('MixrPay error:', error.code, error.message);
- *   } else {
- *     console.log('Other error:', error);
+ * catch (error) {
+ *   if (error instanceof SessionLimitExceededError) {
+ *     console.log(`Session limit: $${error.limit}, requested: $${error.requested}`);
+ *     console.log(`Remaining: $${error.remaining}`);
  *   }
  * }
  * ```
  */
-declare function isMixrPayError(error: unknown): error is MixrPayError;
+declare class SessionLimitExceededError extends MixrPayError {
+    /** ID of the session */
+    readonly sessionId?: string;
+    /** The session's spending limit in USD */
+    readonly limit: number;
+    /** The amount requested in USD */
+    readonly requested: number;
+    /** Remaining balance in the session (limit - used) */
+    readonly remaining: number;
+    constructor(limit: number, requested: number, remaining: number, sessionId?: string);
+}
 /**
- * Get a user-friendly error message from any error.
+ * Thrown when a session ID is invalid or not found.
+ *
+ * This can happen if:
+ * - The session ID was incorrectly formatted
+ * - The session was deleted
+ * - The session belongs to a different user/merchant
  *
- * @param error - The error to get a message from
- * @returns A user-friendly error message
+ * ## Resolution
+ * Create a new session using `wallet.getOrCreateSession()`.
  *
  * @example
  * ```typescript
  * catch (error) {
- *   const message = getErrorMessage(error);
- *   showToast(message);
+ *   if (error instanceof SessionNotFoundError) {
+ *     console.log(`Session ${error.sessionId} not found`);
+ *     const newSession = await wallet.getOrCreateSession({ ... });
+ *   }
  * }
  * ```
  */
-declare function getErrorMessage(error: unknown): string;
-
-/**
- * MixrPay Agent SDK - Session Key Handling
- *
- * Session keys are derived private keys with on-chain spending limits that enable
- * AI agents to sign USDC transferWithAuthorization transactions autonomously.
- */
-
-/**
- * Represents a session key for signing x402 payments.
- *
- * The session key format is: sk_live_{64_hex_chars} or sk_test_{64_hex_chars}
- */
-declare class SessionKey {
-    private readonly privateKey;
-    private readonly account;
-    readonly address: `0x${string}`;
-    readonly isTest: boolean;
-    private constructor();
-    /**
-     * Get the private key as hex string (without 0x prefix).
-     * Used for API authentication headers.
-     */
-    get privateKeyHex(): string;
-    /**
-     * Parse a session key string into a SessionKey object.
-     *
-     * @param sessionKey - Session key in format sk_live_... or sk_test_...
-     * @returns SessionKey object
-     * @throws InvalidSessionKeyError if the format is invalid
-     */
-    static fromString(sessionKey: string): SessionKey;
-    /**
-     * Sign EIP-712 typed data for TransferWithAuthorization.
-     *
-     * @param domain - EIP-712 domain
-     * @param message - Transfer authorization message
-     * @returns Hex-encoded signature
-     */
-    signTransferAuthorization(domain: EIP712Domain, message: TransferWithAuthorizationMessage): Promise<Hex>;
-    /**
-     * Sign a plain message (EIP-191 personal sign).
-     *
-     * @param message - Message to sign
-     * @returns Hex-encoded signature
-     */
-    signMessage(message: string): Promise<Hex>;
-    /**
-     * Get the chain ID based on whether this is a test key.
-     */
-    getDefaultChainId(): number;
+declare class SessionNotFoundError extends MixrPayError {
+    /** The session ID that was not found */
+    readonly sessionId: string;
+    constructor(sessionId: string);
 }
 /**
- * Build EIP-712 typed data for USDC transferWithAuthorization (EIP-3009).
- *
- * @param params - Parameters for the transfer authorization
- * @returns Domain and message for EIP-712 signing
- */
-declare function buildTransferAuthorizationData(params: {
-    fromAddress: `0x${string}`;
-    toAddress: `0x${string}`;
-    value: bigint;
-    validAfter: bigint;
-    validBefore: bigint;
-    nonce: Hex;
-    chainId: number;
-}): {
-    domain: EIP712Domain;
-    message: TransferWithAuthorizationMessage;
-};
-/**
- * Generate a random 32-byte nonce as hex.
- */
-declare function generateNonce(): Hex;
-
-/**
- * MixrPay Agent SDK - x402 Protocol Handling
+ * Thrown when attempting to use a session that has been revoked.
  *
- * The x402 protocol enables HTTP-native payments. When a server returns a 402 Payment
- * Required response, the client can automatically fulfill the payment and retry.
- */
-
-/**
- * Parse payment requirements from a 402 response.
+ * Sessions can be revoked by:
+ * - The user (wallet owner)
+ * - The merchant
+ * - Automatically by the system (e.g., suspicious activity)
  *
- * The 402 response can include payment requirements in:
- * 1. X-Payment-Required header (JSON)
- * 2. WWW-Authenticate header (per x402 spec)
- * 3. Response body (JSON)
+ * ## Resolution
+ * Create a new session using `wallet.getOrCreateSession()`.
  *
- * @param response - The HTTP response with status 402
- * @returns Parsed payment requirements
- * @throws X402ProtocolError if requirements cannot be parsed
+ * @example
+ * ```typescript
+ * catch (error) {
+ *   if (error instanceof SessionRevokedError) {
+ *     console.log(`Session ${error.sessionId} was revoked`);
+ *     if (error.reason) console.log(`Reason: ${error.reason}`);
+ *   }
+ * }
+ * ```
  */
-declare function parse402Response(response: Response): Promise<PaymentRequirements>;
+declare class SessionRevokedError extends MixrPayError {
+    /** The session ID that was revoked */
+    readonly sessionId: string;
+    /** Optional reason for revocation */
+    readonly reason?: string;
+    constructor(sessionId: string, reason?: string);
+}
 /**
- * Build the X-PAYMENT header value for a payment request.
- *
- * This creates an EIP-3009 transferWithAuthorization, signs it with the session key,
- * and encodes it for the X-PAYMENT header.
+ * Check if an error is a MixrPay SDK error.
  *
- * @param requirements - Payment requirements from the 402 response
- * @param sessionKey - Session key to sign the payment
- * @param walletAddress - The smart wallet address that holds USDC
- * @returns Base64-encoded JSON string for the X-PAYMENT header
- */
-declare function buildXPaymentHeader(requirements: PaymentRequirements, sessionKey: SessionKey, walletAddress: `0x${string}`): Promise<string>;
-/**
- * Check if payment requirements have expired.
- */
-declare function isPaymentExpired(requirements: PaymentRequirements): boolean;
-/**
- * Get payment amount in USD (USDC has 6 decimals).
- */
-declare function getAmountUsd(requirements: PaymentRequirements): number;
-/**
- * Validate that a payment amount is within acceptable limits.
+ * @param error - The error to check
+ * @returns true if the error is a MixrPayError or subclass
  *
- * @param amountUsd - Payment amount in USD
- * @param maxPaymentUsd - Optional client-side maximum per payment
- * @throws X402ProtocolError if the amount exceeds limits
+ * @example
+ * ```typescript
+ * try {
+ *   await wallet.fetch(...);
+ * } catch (error) {
+ *   if (isMixrPayError(error)) {
+ *     console.log('MixrPay error:', error.code, error.message);
+ *   } else {
+ *     console.log('Other error:', error);
+ *   }
+ * }
+ * ```
  */
-declare function validatePaymentAmount(amountUsd: number, maxPaymentUsd?: number): void;
+declare function isMixrPayError(error: unknown): error is MixrPayError;
 
-export { AgentWallet, type AgentWalletConfig, type CallMerchantApiOptions, type ChargeResult, type ChargeSessionOptions, type CreateSessionOptions, DEFAULT_BASE_URL, DEFAULT_FACILITATOR_URL, DEFAULT_TIMEOUT, type DiagnosticsResult, InsufficientBalanceError, InvalidSessionKeyError, MixrPayError, NETWORKS, type PaymentEvent, PaymentFailedError, type PaymentRequirements, SDK_VERSION, type SessionAuthStatus, type SessionAuthorization, SessionKey, SessionKeyExpiredError, type SessionKeyInfo, type SessionKeyStatsResponse, SpendingLimitExceededError, type SpendingStats, type WalletBalanceResponse, type X402PaymentPayload, X402ProtocolError, buildTransferAuthorizationData, buildXPaymentHeader, generateNonce, getAmountUsd, getErrorMessage, isMixrPayError, isPaymentExpired, parse402Response, validatePaymentAmount };
+export { AgentWallet, type AgentWalletConfig, type CallMerchantApiOptions, type ChargeResult, InsufficientBalanceError, InvalidSessionKeyError, MixrPayError, type PaymentEvent, PaymentFailedError, SDK_VERSION, type SessionAuthorization, SessionExpiredError, SessionKeyExpiredError, SessionLimitExceededError, SessionNotFoundError, SessionRevokedError, type SessionStats, SpendingLimitExceededError, type SpendingStats, isMixrPayError };