@mixrpay/agent-sdk 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -312,6 +312,116 @@ interface SessionKeyStatsResponse {
     /** Expiration timestamp ISO string (null if never) */
     expiresAt: string | null;
 }
+/**
+ * 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 represents a user-approved spending permission for a specific merchant.
+ */
+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;
+}
+/**
+ * Options for calling a MixrPay merchant's API.
+ */
+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;
+}
+/**
+ * Options for charging against a session.
+ */
+interface ChargeSessionOptions {
+    /** Feature slug for tracking */
+    feature?: string;
+    /** Idempotency key to prevent double-charges */
+    idempotencyKey?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result of a session charge.
+ */
+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;
+}
 
 /**
  * MixrPay Agent SDK - AgentWallet
@@ -587,6 +697,127 @@ 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>;
+    /**
+     * 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;
 }
 
 /**
@@ -865,6 +1096,11 @@ declare class SessionKey {
     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.
      *
@@ -881,6 +1117,13 @@ declare class SessionKey {
      * @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.
      */
@@ -958,4 +1201,4 @@ declare function getAmountUsd(requirements: PaymentRequirements): number;
  */
 declare function validatePaymentAmount(amountUsd: number, maxPaymentUsd?: number): void;
 
-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, 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 };

package/dist/index.d.ts

@@ -312,6 +312,116 @@ interface SessionKeyStatsResponse {
     /** Expiration timestamp ISO string (null if never) */
     expiresAt: string | null;
 }
+/**
+ * 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 represents a user-approved spending permission for a specific merchant.
+ */
+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;
+}
+/**
+ * Options for calling a MixrPay merchant's API.
+ */
+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;
+}
+/**
+ * Options for charging against a session.
+ */
+interface ChargeSessionOptions {
+    /** Feature slug for tracking */
+    feature?: string;
+    /** Idempotency key to prevent double-charges */
+    idempotencyKey?: string;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result of a session charge.
+ */
+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;
+}
 
 /**
  * MixrPay Agent SDK - AgentWallet
@@ -587,6 +697,127 @@ 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>;
+    /**
+     * 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;
 }
 
 /**
@@ -865,6 +1096,11 @@ declare class SessionKey {
     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.
      *
@@ -881,6 +1117,13 @@ declare class SessionKey {
      * @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.
      */
@@ -958,4 +1201,4 @@ declare function getAmountUsd(requirements: PaymentRequirements): number;
  */
 declare function validatePaymentAmount(amountUsd: number, maxPaymentUsd?: number): void;
 
-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, 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 };