@paxoslabs/amplify-sdk 0.1.1 → 0.2.0-alpha.1

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { Address, erc20Abi, Hex } from 'viem';
 import { A as AmplifyVault, S as SupportedAsset, a as AssetFilterOptions, V as VaultFilterOptions, W as WithdrawSupportedAsset } from './amplify-sdk-api-DGRgEybp.js';
 export { b as APIError } from './amplify-sdk-api-DGRgEybp.js';
-export { g as getDepositExchangeRate, a as getWithdrawExchangeRate, i as isDepositSpendApproved, b as isWithdrawalSpendApproved } from './exchange-rate-Cp1ddpw4.js';
+export { g as getDepositExchangeRate, a as getWithdrawExchangeRate, i as isDepositSpendApproved, b as isWithdrawalSpendApproved } from './exchange-rate-DOmoqut9.js';
 import { Y as YieldType } from './config-B-u3VqEX.js';
 import { C as ChainId } from './vault-config-BNzhv3QV.js';
 import './config-BQynVNDC.js';
@@ -375,11 +375,119 @@ declare function findVaultByConfig(params: {
  */
 declare function getWithdrawSupportedAssets(): Promise<WithdrawSupportedAsset[]>;
 
+/**
+ * Telemetry Type Definitions
+ *
+ * Types for SDK telemetry, logging, and PostHog integration.
+ */
+/**
+ * Log levels for controlling console output
+ *
+ * @example
+ * ```typescript
+ * import { LogLevel } from "@paxoslabs/amplify-sdk";
+ *
+ * // Only show errors (default)
+ * await initAmplifySDK(apiKey, { logLevel: LogLevel.ERROR });
+ *
+ * // Show all logs including debug
+ * await initAmplifySDK(apiKey, { logLevel: LogLevel.DEBUG });
+ * ```
+ */
+declare const LogLevel: {
+    readonly DEBUG: 0;
+    readonly INFO: 1;
+    readonly WARN: 2;
+    readonly ERROR: 3;
+    readonly NONE: 4;
+};
+type LogLevel = (typeof LogLevel)[keyof typeof LogLevel];
+/**
+ * Logger interface for consumer use
+ *
+ * Implement this interface to provide a custom logger.
+ * All methods receive a message and optional context object.
+ *
+ * @example
+ * ```typescript
+ * import { setLogger, Logger } from "@paxoslabs/amplify-sdk";
+ *
+ * const customLogger: Logger = {
+ *   debug: (msg, ctx) => console.debug(`[MyApp] ${msg}`, ctx),
+ *   info: (msg, ctx) => console.info(`[MyApp] ${msg}`, ctx),
+ *   warn: (msg, ctx) => console.warn(`[MyApp] ${msg}`, ctx),
+ *   error: (msg, ctx) => console.error(`[MyApp] ${msg}`, ctx),
+ * };
+ *
+ * setLogger(customLogger);
+ * ```
+ */
+interface Logger {
+    /**
+     * Log debug message (verbose, development only)
+     */
+    debug(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log informational message
+     */
+    info(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log warning message
+     */
+    warn(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log error message
+     */
+    error(message: string, context?: Record<string, unknown>): void;
+}
+
 /**
  * SDK Configuration Types
  *
  * Type definitions for SDK initialization and configuration management.
  */
+
+/**
+ * SDK Initialization Options
+ *
+ * Options for configuring SDK behavior during initialization.
+ *
+ * @example
+ * ```typescript
+ * // Enable debug logging, disable telemetry
+ * await initAmplifySDK(apiKey, {
+ *   telemetry: false,
+ *   logLevel: LogLevel.DEBUG,
+ * });
+ * ```
+ */
+interface SDKInitOptions {
+    /**
+     * Enable or disable telemetry (PostHog error tracking)
+     *
+     * When enabled (default), errors are tracked to PostHog for
+     * proactive monitoring. Disable for privacy or testing.
+     *
+     * @default true
+     */
+    telemetry?: boolean;
+    /**
+     * Console log level
+     *
+     * Controls which log messages are output to the console.
+     * Does not affect telemetry (errors are always tracked if enabled).
+     *
+     * @default LogLevel.ERROR
+     */
+    logLevel?: LogLevel;
+    /**
+     * Custom logger implementation
+     *
+     * Override the default console logger with a custom implementation.
+     * Useful for integrating with existing logging infrastructure.
+     */
+    logger?: Logger;
+}
 /**
  * SDK Configuration State
  *
@@ -413,6 +521,11 @@ interface SDKConfig {
      * Allows concurrent calls to wait for same initialization
      */
     initPromise: Promise<void> | null;
+    /**
+     * Whether telemetry is enabled
+     * Set during initialization based on options
+     */
+    telemetryEnabled: boolean;
 }
 /**
  * Request headers for Paxos Labs API
@@ -439,19 +552,100 @@ type InitErrorCode = "INVALID_API_KEY" | "EMPTY_API_KEY" | "AUTH_FAILED" | "NETW
  * Initialize Amplify SDK with API key
  *
  * Validates API key, configures authentication headers, and pre-populates
- * the cache with vault and asset data.
+ * the cache with vault and asset data. Optionally initializes telemetry
+ * for error tracking.
  *
  * @param apiKey - API key obtained from Paxos Labs
+ * @param options - Optional configuration options
+ * @param options.telemetry - Enable/disable telemetry (default: true)
+ * @param options.logLevel - Console log level (default: LogLevel.ERROR)
+ * @param options.logger - Custom logger implementation
  * @throws {APIError} If initialization fails
  *
  * @example
  * ```typescript
  * import { initAmplifySDK } from "@paxoslabs/amplify-sdk";
  *
+ * // Basic initialization (telemetry enabled by default)
  * await initAmplifySDK("pxl_internal_your_api_key_here");
+ *
+ * // Disable telemetry
+ * await initAmplifySDK("pxl_your_api_key", { telemetry: false });
+ *
+ * // Enable debug logging
+ * await initAmplifySDK("pxl_your_api_key", { logLevel: LogLevel.DEBUG });
  * ```
  */
-declare function initAmplifySDK(apiKey: string): Promise<void>;
+declare function initAmplifySDK(apiKey: string, options?: SDKInitOptions): Promise<void>;
+
+/**
+ * Logger Module
+ *
+ * Provides a consumer-facing logger interface with configurable log levels.
+ * Default implementation logs errors only to console.
+ */
+
+/**
+ * Set a custom logger implementation
+ *
+ * Replace the default console logger with a custom implementation.
+ * Useful for integrating with existing logging infrastructure.
+ *
+ * @param logger - Custom logger implementing the Logger interface
+ *
+ * @example
+ * ```typescript
+ * import { setLogger } from "@paxoslabs/amplify-sdk";
+ *
+ * // Use a custom logger
+ * setLogger({
+ *   debug: (msg, ctx) => winston.debug(msg, ctx),
+ *   info: (msg, ctx) => winston.info(msg, ctx),
+ *   warn: (msg, ctx) => winston.warn(msg, ctx),
+ *   error: (msg, ctx) => winston.error(msg, ctx),
+ * });
+ * ```
+ */
+declare function setLogger(logger: Logger): void;
+/**
+ * Get the current logger instance
+ *
+ * Returns the custom logger if set, otherwise the default console logger.
+ *
+ * @returns Current logger instance
+ *
+ * @example
+ * ```typescript
+ * import { getLogger } from "@paxoslabs/amplify-sdk";
+ *
+ * const logger = getLogger();
+ * logger.info("Processing deposit", { amount: "100" });
+ * ```
+ */
+declare function getLogger(): Logger;
+/**
+ * Set the log level for the default console logger
+ *
+ * Controls which log messages are output to the console.
+ * Has no effect if a custom logger is set.
+ *
+ * @param level - Minimum log level to output
+ *
+ * @example
+ * ```typescript
+ * import { setLogLevel, LogLevel } from "@paxoslabs/amplify-sdk";
+ *
+ * // Show all logs including debug
+ * setLogLevel(LogLevel.DEBUG);
+ *
+ * // Only show errors (default)
+ * setLogLevel(LogLevel.ERROR);
+ *
+ * // Disable all logging
+ * setLogLevel(LogLevel.NONE);
+ * ```
+ */
+declare function setLogLevel(level: LogLevel): void;
 
 /**
  * @file Approve Asset for deposit functionality for Paxos Labs vaults
@@ -850,11 +1044,12 @@ interface DepositTxData {
  * Accepts yieldType, recipientAddress, depositToken, and chainId for automatic vault resolution
  * @interface PrepareDepositTxDataParams
  * @property {YieldType} yieldType - Yield strategy type (e.g., "PRIME", "TBILL", "LENDING")
- * @property {Address} recipientAddress - Ethereum address of the user (recipient of vault shares)
- * @property {Address} depositToken - Token contract address to deposit (matches vault's baseTokenAddress)
+ * @property {Address} recipientAddress - Ethereum address of the user. Must be the same as the address used to sign the deposit transaction.
+ * @property {Address} depositToken - Token contract address to deposit. Must be supported by the vault.
  * @property {string} depositAmount - Amount of assets to deposit as a decimal string (e.g., "1.5")
  * @property {number | string} chainId - ID of the chain where the deposit will occur
- * @property {number} [slippage] - Maximum acceptable slippage in basis points (e.g., 100 for 1%)
+ * @property {number} [slippage] - Optional (default is 50 (0.5%)): Maximum acceptable slippage in basis points (e.g., 100 for 1%).
+ * @property {string} [partnerCode] - Optional (default is empty string): Partner code to credit deposit fees to the partner used for the deposit
  */
 interface PrepareDepositTxDataParams {
     yieldType: YieldType;
@@ -880,6 +1075,7 @@ interface PrepareDepositTxDataParams {
  *   depositAmount: "1.0",
  *   chainId: 1,
  *   slippage: 100, // 1% slippage (100 bps)
+ *   partnerCode: 'my-partner-code',
  * });
  * ```
  *
@@ -975,6 +1171,10 @@ interface ParsedPermitSignature {
  * @property recipientAddress - User address (permit owner)
  * @property chainId - Blockchain network ID
  * @property deadline - Optional permit expiration (defaults to 1 hour)
+ * @property nonce - Optional pre-fetched nonce (skips RPC call if provided)
+ * @property decimals - Optional pre-fetched token decimals (skips RPC call)
+ * @property tokenName - Optional pre-fetched token name (skips RPC call)
+ * @property tokenVersion - Optional pre-fetched token version (skips RPC call)
  */
 interface PrepareDepositPermitSignatureParams {
     yieldType: YieldType;
@@ -983,6 +1183,14 @@ interface PrepareDepositPermitSignatureParams {
     recipientAddress: Address;
     chainId: number;
     deadline?: bigint;
+    /** Pre-fetched nonce from getTokenPermitInfoWithAllowance */
+    nonce?: bigint;
+    /** Pre-fetched token decimals */
+    decimals?: number;
+    /** Pre-fetched token name for EIP-712 domain */
+    tokenName?: string;
+    /** Pre-fetched token version for EIP-712 domain (defaults to "1") */
+    tokenVersion?: string;
 }
 /**
  * T009: Encoded transaction data for permit deposit
@@ -1070,7 +1278,8 @@ declare function parsePermitSignature(signature: Hex): ParsedPermitSignature;
  * @property {number | ChainId} chainId - ID of the chain where the deposit will occur
  * @property {Hex} signature - Raw hex signature from wallet signing
  * @property {bigint} deadline - Deadline timestamp (must match permit signature deadline)
- * @property {number} [slippage] - Maximum acceptable slippage in basis points (default: 100 for 1%)
+ * @property {number} [slippage] - Optional (default is 50 (0.5%)): Maximum acceptable slippage in basis points (e.g., 100 for 1%).
+ * @property {string} [partnerCode] - Optional (default is empty string): Partner code to credit deposit fees to the partner used for the deposit
  *
  * @example
  * ```typescript
@@ -1086,6 +1295,7 @@ declare function parsePermitSignature(signature: Hex): ParsedPermitSignature;
  *   signature,
  *   deadline: permitData.message.deadline,
  *   slippage: 100, // 1%
+ *   partnerCode: "my-partner-code",
  * };
  * ```
  */
@@ -1120,6 +1330,244 @@ interface PrepareDepositWithPermitTxDataParams {
  */
 declare function prepareDepositWithPermitTxData(params: PrepareDepositWithPermitTxDataParams): Promise<UnencodedDepositWithPermitData>;
 
+/**
+ * @file Unified deposit module with wrapper functions
+ * @module vaults/deposit
+ *
+ * Provides high-level wrapper functions for deposit authorization and execution:
+ * - `prepareDepositAuthorization`: Determines optimal authorization method (permit/approval)
+ * - `prepareDeposit`: Unified deposit preparation with automatic routing
+ */
+
+/**
+ * Authorization methods for deposit operations
+ *
+ * Extensible const object for current and future authorization mechanisms:
+ * - PERMIT: EIP-2612 off-chain signature (gas efficient, single transaction)
+ * - APPROVAL: Traditional ERC20 approval (two transactions)
+ * - ALREADY_APPROVED: Existing allowance is sufficient (no action needed)
+ *
+ * @example
+ * ```typescript
+ * import { DepositAuthMethod } from "@paxoslabs/amplify-sdk";
+ *
+ * if (result.method === DepositAuthMethod.PERMIT) {
+ *   // Handle permit flow
+ * }
+ * ```
+ */
+declare const DepositAuthMethod: {
+    readonly PERMIT: "permit";
+    readonly APPROVAL: "approval";
+    readonly ALREADY_APPROVED: "already_approved";
+};
+type DepositAuthMethod = (typeof DepositAuthMethod)[keyof typeof DepositAuthMethod];
+/**
+ * Permit authorization result
+ * Returned when token supports EIP-2612 permit
+ */
+interface PermitAuthorizationResult {
+    method: typeof DepositAuthMethod.PERMIT;
+    /** EIP-712 typed data ready for wallet signing */
+    permitData: PermitSignatureData;
+}
+/**
+ * Approval authorization result
+ * Returned when an ERC20 approval transaction is needed
+ */
+interface ApprovalAuthorizationResult {
+    method: typeof DepositAuthMethod.APPROVAL;
+    /** Transaction data for ERC20 approve() call */
+    txData: ApproveDepositTokenTxData;
+    /** Current allowance (human-readable) */
+    currentAllowance: string;
+    /** Current allowance as BigInt string */
+    currentAllowanceAsBigInt: string;
+}
+/**
+ * Already approved authorization result
+ * Returned when existing allowance is sufficient for the deposit
+ */
+interface AlreadyApprovedAuthorizationResult {
+    method: typeof DepositAuthMethod.ALREADY_APPROVED;
+    /** Current allowance (human-readable) */
+    allowance: string;
+    /** Current allowance as BigInt string */
+    allowanceAsBigInt: string;
+}
+/**
+ * Discriminated union of all authorization result types
+ *
+ * Use type narrowing with `result.method` to access specific fields:
+ *
+ * @example
+ * ```typescript
+ * const result = await prepareDepositAuthorization({...});
+ *
+ * switch (result.method) {
+ *   case DepositAuthMethod.PERMIT:
+ *     // TypeScript knows result.permitData exists
+ *     const signature = await signTypedData(result.permitData);
+ *     break;
+ *   case DepositAuthMethod.APPROVAL:
+ *     // TypeScript knows result.txData exists
+ *     await writeContract(result.txData);
+ *     break;
+ *   case DepositAuthMethod.ALREADY_APPROVED:
+ *     // TypeScript knows result.allowance exists
+ *     console.log(`Already approved: ${result.allowance}`);
+ *     break;
+ * }
+ * ```
+ */
+type DepositAuthorizationResult = PermitAuthorizationResult | ApprovalAuthorizationResult | AlreadyApprovedAuthorizationResult;
+/**
+ * Parameters for prepareDepositAuthorization
+ */
+interface PrepareDepositAuthorizationParams {
+    /** Yield strategy type (e.g., "PRIME", "TBILL", "LENDING") */
+    yieldType: YieldType;
+    /** Token contract address to deposit */
+    depositToken: Address;
+    /** Amount of assets to deposit as decimal string (e.g., "100.25") */
+    depositAmount: string;
+    /** User's wallet address (permit owner / approval sender) */
+    recipientAddress: Address;
+    /** Blockchain network ID */
+    chainId: ChainId;
+    /** Optional deadline for permit signature (defaults to 1 hour from now) */
+    deadline?: bigint;
+    /** Force specific authorization method (bypasses automatic detection) */
+    forceMethod?: "permit" | "approval";
+}
+/**
+ * Parameters for prepareDeposit
+ * Unified deposit function accepting optional permit signature
+ */
+interface PrepareDepositParams {
+    /** Yield strategy type (e.g., "PRIME", "TBILL", "LENDING") */
+    yieldType: YieldType;
+    /** Token contract address to deposit */
+    depositToken: Address;
+    /** Amount of assets to deposit as decimal string (e.g., "100.25") */
+    depositAmount: string;
+    /** Recipient address for vault shares */
+    recipientAddress: Address;
+    /** Blockchain network ID */
+    chainId: ChainId;
+    /** Optional slippage in basis points (default: 50 = 0.5%) */
+    slippage?: number;
+    /** Optional partner code for fee attribution */
+    partnerCode?: string;
+    /** Optional permit signature (hex string from wallet signing) */
+    signature?: Hex;
+    /** Optional permit deadline (must match signature deadline) */
+    deadline?: bigint;
+    /** Force deposit method (bypasses automatic routing) */
+    forceMethod?: "permit" | "approval";
+}
+/**
+ * Standard deposit result (approval flow)
+ */
+interface StandardDepositResult {
+    method: typeof DepositAuthMethod.APPROVAL;
+    txData: DepositTxData;
+}
+/**
+ * Permit deposit result
+ */
+interface PermitDepositResult {
+    method: typeof DepositAuthMethod.PERMIT;
+    txData: UnencodedDepositWithPermitData;
+}
+/**
+ * Unified deposit result
+ * Returns either standard deposit or permit deposit transaction data
+ */
+type PrepareDepositResult = StandardDepositResult | PermitDepositResult;
+/**
+ * Prepares authorization for a deposit operation
+ *
+ * Intelligently determines the best authorization method:
+ * 1. Check if token supports EIP-2612 permit → return permit signature data
+ * 2. Check existing allowance → if sufficient, return "already approved"
+ * 3. Otherwise → return approval transaction data
+ *
+ * Supports force override via `forceMethod` parameter.
+ *
+ * @param params - Authorization parameters
+ * @returns Discriminated union of authorization results
+ * @throws {APIError} If vault not found, chain not supported, or token invalid
+ *
+ * @example
+ * ```typescript
+ * import { prepareDepositAuthorization, DepositAuthMethod } from "@paxoslabs/amplify-sdk";
+ *
+ * const authResult = await prepareDepositAuthorization({
+ *   yieldType: "PRIME",
+ *   depositToken: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
+ *   depositAmount: "1000.0",
+ *   recipientAddress: "0x1234...",
+ *   chainId: 1,
+ * });
+ *
+ * if (authResult.method === DepositAuthMethod.PERMIT) {
+ *   const signature = await signTypedData(authResult.permitData);
+ *   // Use signature in prepareDeposit
+ * } else if (authResult.method === DepositAuthMethod.APPROVAL) {
+ *   await writeContract(authResult.txData);
+ *   // Wait for confirmation, then call prepareDeposit
+ * } else {
+ *   // Already approved, proceed directly to deposit
+ *   console.log(`Approved amount: ${authResult.allowance}`);
+ * }
+ * ```
+ */
+declare function prepareDepositAuthorization(params: PrepareDepositAuthorizationParams): Promise<DepositAuthorizationResult>;
+/**
+ * Unified deposit preparation function
+ *
+ * Intelligently routes to permit deposit or standard deposit based on:
+ * 1. Presence of signature/deadline parameters → permit deposit
+ * 2. Force method override → specified method
+ * 3. Otherwise → standard deposit
+ *
+ * @param params - Deposit parameters with optional permit signature
+ * @returns Discriminated union of deposit transaction data
+ * @throws {APIError} If vault not found, invalid signature, or validation fails
+ *
+ * @example
+ * ```typescript
+ * import { prepareDeposit, DepositAuthMethod } from "@paxoslabs/amplify-sdk";
+ *
+ * // Scenario 1: Permit deposit (with signature from prepareDepositAuthorization)
+ * const permitDeposit = await prepareDeposit({
+ *   yieldType: "PRIME",
+ *   depositToken: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+ *   depositAmount: "1000.0",
+ *   recipientAddress: "0x1234...",
+ *   chainId: 1,
+ *   signature: "0xabc...",
+ *   deadline: 1234567890n,
+ * });
+ * // permitDeposit.method === DepositAuthMethod.PERMIT
+ *
+ * // Scenario 2: Standard deposit (after approval)
+ * const standardDeposit = await prepareDeposit({
+ *   yieldType: "PRIME",
+ *   depositToken: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+ *   depositAmount: "1000.0",
+ *   recipientAddress: "0x1234...",
+ *   chainId: 1,
+ * });
+ * // standardDeposit.method === DepositAuthMethod.APPROVAL
+ *
+ * // Submit transaction
+ * await writeContract(standardDeposit.txData);
+ * ```
+ */
+declare function prepareDeposit(params: PrepareDepositParams): Promise<PrepareDepositResult>;
+
 declare const BoringVaultAbi: readonly [{
     readonly type: "constructor";
     readonly inputs: readonly [{
@@ -3557,4 +4005,4 @@ interface WithdrawTxData {
  */
 declare const prepareWithdrawTxData: ({ yieldType, wantAssetAddress, chainId, offerAmount, deadline, slippage, }: PrepareWithdrawTxDataParams) => Promise<WithdrawTxData>;
 
-export { AmplifyVault, type ApproveDepositTokenTxData, type ApproveWithdrawTokenTxData, AssetFilterOptions, type BulkWithdrawTxData, type DepositTxData, type EIP712Domain, type InitErrorCode, PERMIT_TYPES, type ParsedPermitSignature, type PermitSignatureData, type PrepareDepositPermitSignatureParams, type PrepareDepositWithPermitTxDataParams, type RequestHeaders, type SDKConfig, SupportedAsset, type UnencodedDepositWithPermitData, VaultFilterOptions, WithdrawSupportedAsset, type WithdrawTxData, YieldType, fetchSupportedAssets, fetchVaults, findVaultByConfig, getAssetsFromCache, getCache, getWithdrawSupportedAssets, initAmplifySDK, initializeCache, parsePermitSignature, prepareApproveDepositTokenTxData, prepareApproveWithdrawTxData, prepareBulkWithdrawTxData, prepareDepositPermitSignature, prepareDepositTxData, prepareDepositWithPermitTxData, prepareWithdrawTxData, refreshVaultCache };
+export { type AlreadyApprovedAuthorizationResult, AmplifyVault, type ApprovalAuthorizationResult, type ApproveDepositTokenTxData, type ApproveWithdrawTokenTxData, AssetFilterOptions, type BulkWithdrawTxData, DepositAuthMethod, type DepositAuthorizationResult, type DepositTxData, type EIP712Domain, type InitErrorCode, LogLevel, type Logger, PERMIT_TYPES, type ParsedPermitSignature, type PermitAuthorizationResult, type PermitDepositResult, type PermitSignatureData, type PrepareDepositAuthorizationParams, type PrepareDepositParams, type PrepareDepositPermitSignatureParams, type PrepareDepositResult, type PrepareDepositWithPermitTxDataParams, type RequestHeaders, type SDKConfig, type SDKInitOptions, type StandardDepositResult, SupportedAsset, type UnencodedDepositWithPermitData, VaultFilterOptions, WithdrawSupportedAsset, type WithdrawTxData, YieldType, fetchSupportedAssets, fetchVaults, findVaultByConfig, getAssetsFromCache, getCache, getLogger, getWithdrawSupportedAssets, initAmplifySDK, initializeCache, parsePermitSignature, prepareApproveDepositTokenTxData, prepareApproveWithdrawTxData, prepareBulkWithdrawTxData, prepareDeposit, prepareDepositAuthorization, prepareDepositPermitSignature, prepareDepositTxData, prepareDepositWithPermitTxData, prepareWithdrawTxData, refreshVaultCache, setLogLevel, setLogger };