@mixrpay/agent-sdk 0.1.1 → 0.3.0

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.
  */
@@ -222,95 +197,142 @@ interface DiagnosticsResult {
     walletAddress: string;
 }
 /**
- * The X-PAYMENT header payload structure.
+ * Options for creating a session authorization with a MixrPay merchant.
+ */
+interface CreateSessionOptions {
+    /**
+     * The merchant's MixrPay public key.
+     * Format: `pk_live_...` or `pk_test_...`
+     */
+    merchantPublicKey: string;
+    /**
+     * Maximum spending limit for this session in USD.
+     * @default 25.00
+     */
+    spendingLimitUsd?: number;
+    /**
+     * Number of days this session should be valid.
+     * @default 7
+     */
+    durationDays?: number;
+}
+/**
+ * Status of a session authorization.
+ */
+type SessionAuthStatus = 'pending' | 'active' | 'expired' | 'revoked';
+/**
+ * A session authorization with a MixrPay merchant.
  *
- * This is what gets base64-encoded and sent in the X-PAYMENT header.
+ * This represents a user-approved spending permission for a specific merchant.
  */
-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;
-        };
-    };
+interface SessionAuthorization {
+    /** Unique session ID */
+    id: string;
+    /** Merchant ID */
+    merchantId: string;
+    /** Merchant name */
+    merchantName: string;
+    /** Current session status */
+    status: SessionAuthStatus;
+    /** Maximum spending limit in USD */
+    spendingLimitUsd: number;
+    /** Amount already spent in USD */
+    amountUsedUsd: number;
+    /** Remaining spending limit in USD */
+    remainingLimitUsd: number;
+    /** When the session expires */
+    expiresAt: Date;
+    /** When the session was created */
+    createdAt: Date;
 }
 /**
- * EIP-712 domain for USDC transferWithAuthorization.
+ * Options for calling a MixrPay merchant's API.
  */
-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}`;
+interface CallMerchantApiOptions {
+    /**
+     * The merchant API URL to call.
+     */
+    url: string;
+    /**
+     * HTTP method (default: 'POST').
+     */
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    /**
+     * Request body (will be JSON-serialized if object).
+     */
+    body?: unknown;
+    /**
+     * Additional headers to include.
+     */
+    headers?: Record<string, string>;
+    /**
+     * The merchant's MixrPay public key.
+     * Required to identify which session to use.
+     */
+    merchantPublicKey: string;
+    /**
+     * Expected price in USD for this request.
+     * Used for client-side validation.
+     */
+    priceUsd?: number;
+    /**
+     * Feature slug for tracking/analytics.
+     */
+    feature?: string;
 }
 /**
- * EIP-3009 TransferWithAuthorization message structure.
+ * Options for charging against a session.
  */
-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}`;
+interface ChargeSessionOptions {
+    /** Feature slug for tracking */
+    feature?: string;
+    /** Idempotency key to prevent double-charges */
+    idempotencyKey?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
 }
 /**
- * Response from the wallet balance endpoint.
+ * Result of a session charge.
  */
-interface WalletBalanceResponse {
-    /** Balance in USD */
-    balanceUsd: number;
-    /** Balance in USDC minor units as string */
-    balanceMinor: string;
-    /** Currency code */
-    currency: string;
-    /** Wallet address */
-    walletAddress: string;
+interface ChargeResult {
+    /** Whether the charge succeeded */
+    success: boolean;
+    /** Charge ID */
+    chargeId: string;
+    /** Amount charged in USD */
+    amountUsd: number;
+    /** Transaction hash (if on-chain) */
+    txHash?: string;
+    /** Remaining session balance in USD */
+    remainingSessionBalanceUsd: number;
 }
 /**
- * Response from the session key stats endpoint.
+ * Statistics about session authorizations.
+ *
+ * This provides an overview of all sessions managed by the wallet.
  */
-interface SessionKeyStatsResponse {
-    /** Total spent in USD */
+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;
-    /** 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;
+    /** 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;
+    }>;
 }
 
 /**
@@ -337,13 +359,7 @@ interface SessionKeyStatsResponse {
  */
 
 /** 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.0";
 /** Supported networks */
 declare const NETWORKS: {
     readonly BASE_MAINNET: {
@@ -587,6 +603,148 @@ declare class AgentWallet {
      * @param level - 'debug' | 'info' | 'warn' | 'error' | 'none'
      */
     setLogLevel(level: LogLevel): void;
+    /**
+     * 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
+     */
+    private getSessionAuthHeaders;
+    /**
+     * 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`);
+     * ```
+     */
+    getOrCreateSession(options: CreateSessionOptions): Promise<SessionAuthorization>;
+    /**
+     * Get session status for a specific merchant.
+     *
+     * @param merchantPublicKey - The merchant's public key
+     * @returns Session authorization or null if not found
+     */
+    getSessionByMerchant(merchantPublicKey: string): Promise<SessionAuthorization | 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`);
+     * }
+     * ```
+     */
+    listSessions(): Promise<SessionAuthorization[]>;
+    /**
+     * 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');
+     * }
+     * ```
+     */
+    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.
+     *
+     * 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}`);
+     * ```
+     */
+    chargeSession(sessionId: string, amountUsd: number, options?: ChargeSessionOptions): Promise<ChargeResult>;
+    /**
+     * 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();
+     * ```
+     */
+    callMerchantApi(options: CallMerchantApiOptions): Promise<Response>;
+    /**
+     * Parse session response data into SessionAuthorization object.
+     */
+    private parseSessionResponse;
 }
 
 /**
@@ -785,177 +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.
  *
- * @param error - The error to get a message from
- * @returns A user-friendly error message
+ * This can happen if:
+ * - The session ID was incorrectly formatted
+ * - The session was deleted
+ * - The session belongs to a different user/merchant
+ *
+ * ## 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();
-    /**
-     * 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>;
-    /**
-     * 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).
+ * Thrown when attempting to use a session that has been revoked.
  *
- * @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
+ * Sessions can be revoked by:
+ * - The user (wallet owner)
+ * - The merchant
+ * - Automatically by the system (e.g., suspicious activity)
  *
- * 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.
- *
- * 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, DEFAULT_BASE_URL, DEFAULT_FACILITATOR_URL, DEFAULT_TIMEOUT, type DiagnosticsResult, InsufficientBalanceError, InvalidSessionKeyError, MixrPayError, NETWORKS, type PaymentEvent, PaymentFailedError, type PaymentRequirements, SDK_VERSION, 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 };