@augustdigital/sdk 8.3.2 → 8.5.0

package/lib/core/fetcher.d.ts

@@ -1,29 +1,163 @@
 import type { IAddress, IContractRunner, IHistoricalTimeseriesResponse, ITokenizedVault, IWSMonitorHeaders, IWSVaultLoan, VaultAddress } from '../types';
 import { WEBSERVER_URL } from './constants/core';
+/**
+ * API Fetching and Data Utilities
+ *
+ * Core fetching functions for August backend services:
+ * - Authentication: fetchAugustWithKey, fetchAugustWithBearer, fetchAugustPublic
+ * - Retry Logic: withRetry, isRetryableError, promiseSettle
+ * - Vault Data: fetchTokenizedVaults, fetchTokenizedVaultLoans
+ * - Pricing: fetchTokenPrice (with CoinGecko fallback)
+ * - Caching: LRU cache for API responses
+ */
 export type IFetchAugustMethods = 'get' | 'post' | 'put';
 export type IFetchAugustOptions = {
     method?: IFetchAugustMethods;
     headers?: Record<string, string>;
     data?: any;
     server?: keyof typeof WEBSERVER_URL;
+    /** Caller-supplied AbortSignal; combined with the default timeout. */
     signal?: AbortSignal;
+    /** Per-request timeout in ms. Defaults to `REQUEST_TIMEOUT_MS`. */
     timeoutMs?: number;
+    /**
+     * @deprecated Bypasses the API-key check for legacy unauthenticated endpoints.
+     * Will be removed in a future major version; pass a valid `apiKey` instead.
+     */
     override?: boolean;
 };
+/**
+ * Override the default request timeout used by every August fetcher helper
+ * when the caller doesn't supply a per-call `timeoutMs`. Pass `null` (or
+ * call with no arguments) to clear the override and fall back to the
+ * compiled-in `REQUEST_TIMEOUT_MS`.
+ *
+ * @param ms Positive number of milliseconds to wait before aborting, or
+ *   `null` to clear.
+ */
 export declare function setSdkRequestTimeout(ms?: number | null): void;
+/**
+ * Read the active default request timeout — the SDK-level override if set,
+ * otherwise the compiled-in `REQUEST_TIMEOUT_MS`.
+ */
 export declare function getSdkRequestTimeout(): number;
 import { CACHE, getSafeCache, setSafeCache } from './cache';
 export { CACHE, getSafeCache, setSafeCache };
+/**
+ * Make authenticated requests to August backend services using API key.
+ * Automatically logs errors with correlation IDs for debugging.
+ * @param apiKey August API key for authentication
+ * @param relativeUrl Endpoint path relative to base URL
+ * @param options Request configuration including method and headers
+ * @returns Response object if successful
+ * @throws Error with correlation ID if request fails
+ */
 export declare function fetchAugustWithKey(apiKey: string, relativeUrl: string, options?: IFetchAugustOptions): Promise<Response>;
+/**
+ * Make unauthenticated requests to August public API endpoints.
+ * Used for fetching vault metadata and public market data.
+ * @param relativeUrl Endpoint path relative to public API base URL
+ * @param options Request configuration including method and headers
+ * @returns Response object if successful
+ * @throws Error with correlation ID if request fails
+ */
 export declare function fetchAugustPublic(relativeUrl: string, options?: IFetchAugustOptions): Promise<Response>;
+/**
+ * Make authenticated requests using Bearer token authentication.
+ * Typically used for user-specific operations requiring OAuth tokens.
+ * @param bearerToken OAuth bearer token
+ * @param relativeUrl Endpoint path relative to base URL
+ * @param options Request configuration including method and headers
+ * @returns Response object if successful
+ * @throws Error with correlation ID if request fails
+ */
 export declare function fetchAugustWithBearer(bearerToken: string, relativeUrl: string, options?: IFetchAugustOptions): Promise<Response>;
+/**
+ * Check if an error is network-related and suitable for retry.
+ * Identifies timeouts, connection resets, and fetch failures.
+ */
 export declare function isRetryableError(error: Error): boolean;
+/**
+ * Wrap async operations with exponential backoff retry logic.
+ * Retries on network errors with increasing delays between attempts.
+ * @param fn Async function to execute with retry logic
+ * @param maxRetries Maximum number of retry attempts
+ * @param baseDelay Initial delay in milliseconds (doubles each retry)
+ * @param shouldRetry Custom function to determine if error is retryable
+ * @returns Result of successful function execution
+ * @throws Last error if all retries exhausted
+ */
 export declare function withRetry<T>(fn: () => Promise<T>, maxRetries?: number, baseDelay?: number, shouldRetry?: (error: Error) => boolean): Promise<T>;
+/**
+ * Fetch tokenized vault configurations from backend API.
+ * Results are cached to reduce API calls. Optionally filter by specific vault address.
+ * @param pool Optional vault address to filter results
+ * @param headers Monitoring headers for request tracking
+ * @returns Array of tokenized vault configurations
+ */
 export declare function fetchTokenizedVault(pool: VaultAddress, headers?: IWSMonitorHeaders, loadSubaccounts?: boolean, loadSnapshots?: boolean): Promise<ITokenizedVault[]>;
+/**
+ * Fetch tokenized vault configurations from backend API.
+ * Results are cached to reduce API calls. Optionally filter by specific vault address.
+ * @param pool Optional vault address to filter results
+ * @param headers Monitoring headers for request tracking
+ * @param loadSubaccounts Optional flag to load subaccounts and EOA operators (defaults to true on API)
+ * @returns Array of tokenized vault configurations
+ */
 export declare function fetchTokenizedVaults(pool?: IAddress, headers?: IWSMonitorHeaders, loadSubaccounts?: boolean, loadSnapshots?: boolean): Promise<ITokenizedVault[]>;
+/**
+ * Fetch current USD price for a token symbol or vault LP token.
+ * For vault LP tokens, calculates share price using totalAssets/totalSupply ratio.
+ * Falls back to CoinGecko if primary source fails.
+ * @param symbol Token symbol or contract address
+ * @param provider Optional web3 provider for on-chain price calculations
+ * @param coinGeckoKey Optional CoinGecko API key for fallback pricing
+ * @param headers Monitoring headers for request tracking
+ * @returns Token price in USD
+ */
 export declare function fetchTokenPrice(symbol: string, provider?: IContractRunner, coinGeckoKey?: string, headers?: IWSMonitorHeaders): Promise<any>;
+/**
+ * Fetch token price by contract address and chain ID from August price server.
+ * @param address Token contract address
+ * @param chainId Network chain ID
+ * @param headers Optional monitoring headers for request tracking
+ * @returns Token price in USD, or 0 if not found
+ */
 export declare function fetchTokenPriceByAddress(address: VaultAddress, chainId: number, headers?: IWSMonitorHeaders): Promise<number>;
+/**
+ * Fetch active loans for a specific vault from backend API.
+ * Results are cached per vault and chain to reduce API calls.
+ * @param pool Vault address
+ * @param chainId Network chain ID
+ * @param headers Monitoring headers for request tracking
+ * @returns Array of active loan objects
+ */
 export declare function fetchTokenizedVaultLoans(pool: VaultAddress, chainId: number, headers?: IWSMonitorHeaders): Promise<IWSVaultLoan[]>;
+/**
+ * Fetch subaccount loans for a specific tokenized vault (lending pool).
+ * Retrieves all active subaccount loan data from the backend.
+ * @param pool Vault address
+ * @param chainId Network chain ID
+ * @param headers Monitoring headers for request tracking
+ * @returns Array of active subaccount loan objects
+ */
 export declare function fetchTokenizedVaultSubaccountLoans(pool: VaultAddress, chainId: number, headers?: IWSMonitorHeaders): Promise<IWSVaultLoan[]>;
+/**
+ * Fetch historical timeseries data for a specific vault.
+ * Returns TVL, APY, PnL, and share price data over time.
+ * @param vaultAddress Vault contract address
+ * @param nDays Number of days of historical data to fetch (default 30, min 1)
+ * @param headers Monitoring headers for request tracking
+ * @returns Historical timeseries data with date keys
+ */
 export declare function fetchVaultHistoricalTimeseries(vaultAddress: IAddress, nDays?: number, headers?: IWSMonitorHeaders): Promise<IHistoricalTimeseriesResponse>;
+/**
+ * Execute multiple promises with retry logic and allow partial failures.
+ * Unlike Promise.all, continues execution if some promises fail.
+ * Failed promises return null to maintain array index alignment.
+ * @param promises Array of promises to execute
+ * @param maxRetries Maximum retry attempts per promise
+ * @param baseDelay Initial delay for exponential backoff
+ * @returns Array of results with null for failed promises
+ */
 export declare function promiseSettle<T>(promises: Promise<T>[], maxRetries?: number, baseDelay?: number): Promise<T[]>;

package/lib/core/fetcher.js

@@ -30,6 +30,7 @@ const vault_version_1 = require("./helpers/vault-version");
 const analytics_1 = require("./analytics");
 const sanitize_1 = require("./analytics/sanitize");
 const errors_1 = require("./errors");
+/** Map an HTTP status to the appropriate typed SDK error subclass. */
 function errorFromResponseStatus(status, message, options) {
     if (status === 401) {
         return new errors_1.AugustAuthError('AUTH_UNAUTHORIZED', message, options);
@@ -43,6 +44,15 @@ function errorFromResponseStatus(status, message, options) {
     return new errors_1.AugustServerError(status, message, options);
 }
 let SDK_REQUEST_TIMEOUT_OVERRIDE = null;
+/**
+ * Override the default request timeout used by every August fetcher helper
+ * when the caller doesn't supply a per-call `timeoutMs`. Pass `null` (or
+ * call with no arguments) to clear the override and fall back to the
+ * compiled-in `REQUEST_TIMEOUT_MS`.
+ *
+ * @param ms Positive number of milliseconds to wait before aborting, or
+ *   `null` to clear.
+ */
 function setSdkRequestTimeout(ms = null) {
     if (ms === null) {
         SDK_REQUEST_TIMEOUT_OVERRIDE = null;
@@ -56,9 +66,21 @@ function setSdkRequestTimeout(ms = null) {
     }
     SDK_REQUEST_TIMEOUT_OVERRIDE = ms;
 }
+/**
+ * Read the active default request timeout — the SDK-level override if set,
+ * otherwise the compiled-in `REQUEST_TIMEOUT_MS`.
+ */
 function getSdkRequestTimeout() {
     return SDK_REQUEST_TIMEOUT_OVERRIDE ?? core_2.REQUEST_TIMEOUT_MS;
 }
+/**
+ * Combine the per-request timeout signal with any caller-supplied signal.
+ * Uses `AbortSignal.any` (Node 22+) with a manual relay fallback.
+ *
+ * Returns `timedOut()` (a closure over an internal flag set when the timeout
+ * fires) so the caller can distinguish "we timed out" from "caller cancelled",
+ * and `cleanup()` to release the fallback-relay listener.
+ */
 function buildRequestAbortSignal(options) {
     const timeoutMs = options?.timeoutMs ?? SDK_REQUEST_TIMEOUT_OVERRIDE ?? core_2.REQUEST_TIMEOUT_MS;
     const timeoutController = new AbortController();
@@ -98,8 +120,20 @@ function warnOverrideDeprecation(callerTag) {
     if (_overrideDeprecationWarned)
         return;
     _overrideDeprecationWarned = true;
+    // Deliberately a direct console.warn, not Logger.log.warn: a deprecation
+    // notice must surface in the integrator's console in every environment.
+    // Logger.log.warn would downgrade it to a prod-silent Sentry breadcrumb.
+    // biome-ignore lint/suspicious/noConsole: integrator-facing deprecation notice must surface in every environment; Logger.log.warn would downgrade it to a prod-silent Sentry breadcrumb.
     console.warn(`[@augustdigital/sdk] ${callerTag}: option "override" is deprecated and will be removed in a future major version. Pass a valid apiKey instead.`);
 }
+/**
+ * LRU cache for API responses and frequently accessed data.
+ * 24-hour TTL with 1000 item capacity.
+ */
+/**
+ * Read a response header tolerantly. Real `fetch` returns a `Headers` instance,
+ * but some test mocks supply a plain object; both shapes are supported here.
+ */
 function readResponseHeader(headers, name) {
     if (!headers)
         return undefined;
@@ -114,17 +148,33 @@ const cache_1 = require("./cache");
 Object.defineProperty(exports, "CACHE", { enumerable: true, get: function () { return cache_1.CACHE; } });
 Object.defineProperty(exports, "getSafeCache", { enumerable: true, get: function () { return cache_1.getSafeCache; } });
 Object.defineProperty(exports, "setSafeCache", { enumerable: true, get: function () { return cache_1.setSafeCache; } });
+/**
+ * Dedicated cache for token prices with short TTL to prevent rate limiting.
+ * 30-second TTL with 500 item capacity.
+ */
 const PRICE_CACHE = new lru_cache_1.LRUCache({
     max: 500,
-    ttl: 1000 * 30,
+    ttl: 1000 * 30, // 30 seconds
     allowStale: false,
 });
+/**
+ * Cache for failed price requests to prevent retry storms.
+ * 5-second TTL to allow quick retry after temporary failures.
+ */
 const PRICE_ERROR_CACHE = new lru_cache_1.LRUCache({
     max: 100,
-    ttl: 1000 * 5,
+    ttl: 1000 * 5, // 5 seconds
     allowStale: false,
 });
+/**
+ * In-flight price requests to prevent duplicate simultaneous API calls.
+ */
 const PRICE_REQUESTS = new Map();
+/**
+ * Build an August backend URL, rejecting unknown server keys and any
+ * `relativeUrl` that would escape the configured origin.
+ * Throws `AugustValidationError` with `code: 'INVALID_URL'`.
+ */
 function buildAugustUrl(server, relativeUrl) {
     const serverKey = server;
     const base = core_2.WEBSERVER_URL[serverKey];
@@ -134,9 +184,12 @@ function buildAugustUrl(server, relativeUrl) {
     if (typeof relativeUrl !== 'string' || relativeUrl.length === 0) {
         throw new errors_1.AugustValidationError('INVALID_URL', 'relativeUrl must be a non-empty string');
     }
+    // Reject anything that looks like a scheme or protocol-relative authority.
     if (/^\s*[a-z][a-z0-9+.-]*:|^\s*\/\//i.test(relativeUrl)) {
         throw new errors_1.AugustValidationError('INVALID_URL', `relativeUrl must be a path, not an absolute or protocol-relative URL`);
     }
+    // Concat (rather than `new URL(rel, base)`) preserves base paths like /api/v1
+    // when relativeUrl starts with `/`. Origin check below is a second line.
     const candidate = `${base}${relativeUrl}`;
     let url;
     try {
@@ -151,6 +204,15 @@ function buildAugustUrl(server, relativeUrl) {
     }
     return url.toString();
 }
+/**
+ * Make authenticated requests to August backend services using API key.
+ * Automatically logs errors with correlation IDs for debugging.
+ * @param apiKey August API key for authentication
+ * @param relativeUrl Endpoint path relative to base URL
+ * @param options Request configuration including method and headers
+ * @returns Response object if successful
+ * @throws Error with correlation ID if request fails
+ */
 async function fetchAugustWithKey(apiKey, relativeUrl, options) {
     if (options?.override) {
         warnOverrideDeprecation('fetchAugustWithKey');
@@ -178,6 +240,7 @@ async function fetchAugustWithKey(apiKey, relativeUrl, options) {
             signal: requestSignal,
         });
         cleanup();
+        // Track API call
         (0, analytics_1.trackApiCall)(relativeUrl, options?.method ?? 'GET', startTime, res.status, server);
         const correlationId = readResponseHeader(res.headers, 'x-correlation-id');
         const logger = logger_1.Logger.getLogger();
@@ -206,6 +269,14 @@ async function fetchAugustWithKey(apiKey, relativeUrl, options) {
         throw err;
     }
 }
+/**
+ * Make unauthenticated requests to August public API endpoints.
+ * Used for fetching vault metadata and public market data.
+ * @param relativeUrl Endpoint path relative to public API base URL
+ * @param options Request configuration including method and headers
+ * @returns Response object if successful
+ * @throws Error with correlation ID if request fails
+ */
 async function fetchAugustPublic(relativeUrl, options) {
     const defaultHeaders = {
         'content-type': 'application/json',
@@ -253,6 +324,15 @@ async function fetchAugustPublic(relativeUrl, options) {
         throw err;
     }
 }
+/**
+ * Make authenticated requests using Bearer token authentication.
+ * Typically used for user-specific operations requiring OAuth tokens.
+ * @param bearerToken OAuth bearer token
+ * @param relativeUrl Endpoint path relative to base URL
+ * @param options Request configuration including method and headers
+ * @returns Response object if successful
+ * @throws Error with correlation ID if request fails
+ */
 async function fetchAugustWithBearer(bearerToken, relativeUrl, options) {
     const defaultHeaders = {
         authorization: `Bearer ${bearerToken}`,
@@ -302,6 +382,10 @@ async function fetchAugustWithBearer(bearerToken, relativeUrl, options) {
         throw err;
     }
 }
+/**
+ * Check if an error is network-related and suitable for retry.
+ * Identifies timeouts, connection resets, and fetch failures.
+ */
 function isRetryableError(error) {
     return ((error instanceof TypeError && error.message.includes('fetch failed')) ||
         error.name === 'AbortError' ||
@@ -311,6 +395,16 @@ function isRetryableError(error) {
         error.message.includes('ENOTFOUND') ||
         error.message.includes('ECONNREFUSED'));
 }
+/**
+ * Wrap async operations with exponential backoff retry logic.
+ * Retries on network errors with increasing delays between attempts.
+ * @param fn Async function to execute with retry logic
+ * @param maxRetries Maximum number of retry attempts
+ * @param baseDelay Initial delay in milliseconds (doubles each retry)
+ * @param shouldRetry Custom function to determine if error is retryable
+ * @returns Result of successful function execution
+ * @throws Last error if all retries exhausted
+ */
 async function withRetry(fn, maxRetries = 3, baseDelay = 1000, shouldRetry = isRetryableError) {
     let lastError;
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
@@ -330,10 +424,18 @@ async function withRetry(fn, maxRetries = 3, baseDelay = 1000, shouldRetry = isR
     }
     throw lastError;
 }
+/**
+ * Fetch tokenized vault configurations from backend API.
+ * Results are cached to reduce API calls. Optionally filter by specific vault address.
+ * @param pool Optional vault address to filter results
+ * @param headers Monitoring headers for request tracking
+ * @returns Array of tokenized vault configurations
+ */
 async function fetchTokenizedVault(pool, headers, loadSubaccounts, loadSnapshots) {
     if (!pool) {
         return [];
     }
+    // Build cache key based on loading options
     const keyParts = [`tokenized-vault-${pool}`];
     if (loadSubaccounts === false)
         keyParts.push('no-subaccounts');
@@ -346,6 +448,7 @@ async function fetchTokenizedVault(pool, headers, loadSubaccounts, loadSnapshots
         tokenizedVault = cachedResponse;
     }
     if (!tokenizedVault) {
+        // Build endpoint URL with optional query parameters
         let endpoint = core_2.WEBSERVER_ENDPOINTS.public.tokenizedVault.byVaultAddress(pool);
         const params = new URLSearchParams();
         if (loadSubaccounts === false) {
@@ -362,15 +465,25 @@ async function fetchTokenizedVault(pool, headers, loadSubaccounts, loadSnapshots
             headers: headers,
         });
         tokenizedVault = (await tokenizedVaultsResponse.json());
-        cache_1.CACHE.set(key, tokenizedVault, { ttl: 1000 * 60 * 10 });
+        cache_1.CACHE.set(key, tokenizedVault, { ttl: 1000 * 60 * 10 }); // Cache for 10 minutes
     }
+    // Filter by specific vault if address provided
     if (pool &&
         ((0, ethers_1.isAddress)(pool) || (0, chain_address_1.isSolanaAddress)(pool) || (0, chain_address_1.isStellarAddress)(pool))) {
         return tokenizedVault ? [tokenizedVault] : [];
     }
     return [tokenizedVault];
 }
+/**
+ * Fetch tokenized vault configurations from backend API.
+ * Results are cached to reduce API calls. Optionally filter by specific vault address.
+ * @param pool Optional vault address to filter results
+ * @param headers Monitoring headers for request tracking
+ * @param loadSubaccounts Optional flag to load subaccounts and EOA operators (defaults to true on API)
+ * @returns Array of tokenized vault configurations
+ */
 async function fetchTokenizedVaults(pool, headers, loadSubaccounts, loadSnapshots) {
+    // Build cache key based on loading options
     const keyParts = ['tokenized-vaults'];
     if (pool)
         keyParts.push(pool);
@@ -385,6 +498,7 @@ async function fetchTokenizedVaults(pool, headers, loadSubaccounts, loadSnapshot
         tokenizedVaults = cachedResponse;
     }
     if (!tokenizedVaults) {
+        // Build endpoint URL with optional query parameters
         let endpoint = core_2.WEBSERVER_ENDPOINTS.public.tokenizedVault.list;
         const params = new URLSearchParams();
         if (loadSubaccounts === false) {
@@ -402,9 +516,10 @@ async function fetchTokenizedVaults(pool, headers, loadSubaccounts, loadSnapshot
         });
         tokenizedVaults =
             (await tokenizedVaultsResponse.json());
-        const ttl = 1000 * 60 * 15;
+        const ttl = 1000 * 60 * 15; // 15 minute cache
         cache_1.CACHE.set(key, tokenizedVaults, { ttl });
     }
+    // Filter by specific vault if address provided
     if (pool &&
         ((0, ethers_1.isAddress)(pool) || (0, chain_address_1.isSolanaAddress)(pool) || (0, chain_address_1.isStellarAddress)(pool))) {
         const foundObj = tokenizedVaults.find((t) => t.address.toLowerCase() === pool.toLowerCase());
@@ -412,57 +527,84 @@ async function fetchTokenizedVaults(pool, headers, loadSubaccounts, loadSnapshot
     }
     return tokenizedVaults;
 }
+/**
+ * Fetch current USD price for a token symbol or vault LP token.
+ * For vault LP tokens, calculates share price using totalAssets/totalSupply ratio.
+ * Falls back to CoinGecko if primary source fails.
+ * @param symbol Token symbol or contract address
+ * @param provider Optional web3 provider for on-chain price calculations
+ * @param coinGeckoKey Optional CoinGecko API key for fallback pricing
+ * @param headers Monitoring headers for request tracking
+ * @returns Token price in USD
+ */
 async function fetchTokenPrice(symbol, provider, coinGeckoKey, headers) {
     if (!symbol) {
         logger_1.Logger.log.error('fetchTokenPrice', 'symbol parameter is undefined');
         return 0;
     }
+    // Normalize symbol and apply aliases BEFORE generating cache key
     let normalizedSymbol = symbol.toLowerCase();
     normalizedSymbol = normalizedSymbol === 'xbtc' ? 'btc' : normalizedSymbol;
     normalizedSymbol = normalizedSymbol === 'strbtc' ? 'btc' : normalizedSymbol;
+    // Generate cache key based on normalized symbol and provider presence
     const cacheKey = `price:${normalizedSymbol}:${provider ? 'with-provider' : 'no-provider'}`;
+    // Check error cache to prevent retry storms after failures
     const cachedError = PRICE_ERROR_CACHE.get(cacheKey);
     if (cachedError) {
         logger_1.Logger.log.info('fetchTokenPrice', `Error cache HIT for ${normalizedSymbol} - throwing cached error`);
         throw cachedError;
     }
+    // Check price cache first to avoid rate limiting
     const cachedPrice = PRICE_CACHE.get(cacheKey);
     if (cachedPrice !== undefined) {
         logger_1.Logger.log.info('fetchTokenPrice', `Cache HIT for ${normalizedSymbol}: $${cachedPrice}`);
         return cachedPrice;
     }
+    // Check for in-flight request to deduplicate simultaneous calls
     const inflightRequest = PRICE_REQUESTS.get(cacheKey);
     if (inflightRequest) {
         logger_1.Logger.log.info('fetchTokenPrice', `In-flight request deduplication for ${normalizedSymbol}`);
         return inflightRequest;
     }
+    // Create the price fetching promise
     const pricePromise = (async () => {
         try {
             const price = await _fetchTokenPriceInternal(symbol, provider, coinGeckoKey, headers);
+            // Cache the successful result
             PRICE_CACHE.set(cacheKey, price);
+            // Clear any previous error cache on success
             PRICE_ERROR_CACHE.delete(cacheKey);
             return price;
         }
         catch (error) {
+            // Cache the error temporarily to prevent retry storms
             const err = error instanceof Error ? error : new Error(String(error));
             PRICE_ERROR_CACHE.set(cacheKey, err);
             logger_1.Logger.log.info('fetchTokenPrice', `Cached error for ${normalizedSymbol}: ${err.message}`);
             throw err;
         }
         finally {
+            // Clean up in-flight request tracking
             PRICE_REQUESTS.delete(cacheKey);
         }
     })();
+    // Track this request to prevent duplicates
     PRICE_REQUESTS.set(cacheKey, pricePromise);
     return pricePromise;
 }
+/**
+ * Internal price fetching implementation.
+ * This is separated to allow caching and request deduplication in the public function.
+ */
 async function _fetchTokenPriceInternal(symbol, provider, coinGeckoKey, headers) {
+    // Fetch vault metadata to check if symbol is a vault LP token
     const tokenizedVaults = await fetchTokenizedVaults(undefined, headers, false, false);
     const vaultArray = tokenizedVaults.map((vault) => ({
         vault: vault.address,
         symbol: vault.receipt_token_symbol,
     }));
     const foundVaultLpAsset = vaultArray.find((v) => v.symbol?.toLowerCase() === symbol?.toLowerCase());
+    // @todo: handle multi-asset vaults
     const tokenizedVault = tokenizedVaults.find((vault) => vault.address === foundVaultLpAsset?.vault);
     const version = (0, vault_version_1.getVaultVersionV2)(tokenizedVault);
     if (foundVaultLpAsset?.vault && provider && version === 'evm-2') {
@@ -478,15 +620,18 @@ async function _fetchTokenPriceInternal(symbol, provider, coinGeckoKey, headers)
             throw new Error('failed to fetch token price for evm-2 vault');
         }
     }
+    // Apply symbol normalization and aliases for API calls
     let _symbol = symbol?.toLowerCase();
     _symbol = _symbol === 'xbtc' ? 'btc' : _symbol;
     _symbol = _symbol === 'strbtc' ? 'btc' : _symbol;
     try {
+        // Fetch base token price from August backend
         const res = await fetch(`https://prices.augustdigital.io/price/${_symbol}`, { headers: headers });
         if (res.status !== 200) {
             throw new Error(`fetching ${_symbol} price: ${res?.statusText}`);
         }
         const json = (await res.json());
+        // For vault LP tokens, calculate share price using on-chain ratio
         if (foundVaultLpAsset && provider) {
             const vaultContract = new ethers_2.Contract((0, ethers_1.getAddress)(foundVaultLpAsset.vault), abis_1.ABI_LENDING_POOL_V2, provider);
             const [totalAssets, totalSupply, rawDecimals] = await Promise.all([
@@ -501,6 +646,7 @@ async function _fetchTokenPriceInternal(symbol, provider, coinGeckoKey, headers)
         return json.price;
     }
     catch (e) {
+        // Fallback to CoinGecko if primary source fails
         const fallbackPrice = await (0, fetcher_1.fetchTokenPricesFromCoinGecko)(symbol, coinGeckoKey);
         if (foundVaultLpAsset && provider) {
             const vaultContract = new ethers_2.Contract((0, ethers_1.getAddress)(foundVaultLpAsset.vault), abis_1.ABI_LENDING_POOL_V2, provider);
@@ -521,6 +667,13 @@ async function _fetchTokenPriceInternal(symbol, provider, coinGeckoKey, headers)
         }
     }
 }
+/**
+ * Fetch token price by contract address and chain ID from August price server.
+ * @param address Token contract address
+ * @param chainId Network chain ID
+ * @param headers Optional monitoring headers for request tracking
+ * @returns Token price in USD, or 0 if not found
+ */
 async function fetchTokenPriceByAddress(address, chainId, headers) {
     if (!address || !chainId) {
         return 0;
@@ -547,6 +700,14 @@ async function fetchTokenPriceByAddress(address, chainId, headers) {
         return 0;
     }
 }
+/**
+ * Fetch active loans for a specific vault from backend API.
+ * Results are cached per vault and chain to reduce API calls.
+ * @param pool Vault address
+ * @param chainId Network chain ID
+ * @param headers Monitoring headers for request tracking
+ * @returns Array of active loan objects
+ */
 async function fetchTokenizedVaultLoans(pool, chainId, headers) {
     const key = `loans-${chainId}-${pool}`;
     let loans;
@@ -560,6 +721,14 @@ async function fetchTokenizedVaultLoans(pool, chainId, headers) {
     }
     return loans?.filter((l) => l.state.toLowerCase() === 'active');
 }
+/**
+ * Fetch subaccount loans for a specific tokenized vault (lending pool).
+ * Retrieves all active subaccount loan data from the backend.
+ * @param pool Vault address
+ * @param chainId Network chain ID
+ * @param headers Monitoring headers for request tracking
+ * @returns Array of active subaccount loan objects
+ */
 async function fetchTokenizedVaultSubaccountLoans(pool, chainId, headers) {
     const key = `subaccount-loans-${chainId}-${pool}`;
     let loans;
@@ -573,6 +742,14 @@ async function fetchTokenizedVaultSubaccountLoans(pool, chainId, headers) {
     }
     return loans?.filter((l) => l.state.toLowerCase() === 'active');
 }
+/**
+ * Fetch historical timeseries data for a specific vault.
+ * Returns TVL, APY, PnL, and share price data over time.
+ * @param vaultAddress Vault contract address
+ * @param nDays Number of days of historical data to fetch (default 30, min 1)
+ * @param headers Monitoring headers for request tracking
+ * @returns Historical timeseries data with date keys
+ */
 async function fetchVaultHistoricalTimeseries(vaultAddress, nDays, headers) {
     const key = `vault-historical-timeseries-${vaultAddress}-${nDays}`;
     const cachedResponse = await (0, cache_1.getSafeCache)(key);
@@ -584,9 +761,18 @@ async function fetchVaultHistoricalTimeseries(vaultAddress, nDays, headers) {
         throw new Error(`Failed to fetch historical timeseries data: ${response.statusText}`);
     }
     const json = (await response.json());
-    cache_1.CACHE.set(key, json, { ttl: 1000 * 60 * 10 });
+    cache_1.CACHE.set(key, json, { ttl: 1000 * 60 * 10 }); // Cache for 10 minutes
     return json;
 }
+/**
+ * Execute multiple promises with retry logic and allow partial failures.
+ * Unlike Promise.all, continues execution if some promises fail.
+ * Failed promises return null to maintain array index alignment.
+ * @param promises Array of promises to execute
+ * @param maxRetries Maximum retry attempts per promise
+ * @param baseDelay Initial delay for exponential backoff
+ * @returns Array of results with null for failed promises
+ */
 async function promiseSettle(promises, maxRetries = 3, baseDelay = 1000) {
     const promisesWithRetry = promises.map((promise, index) => withRetry(async () => {
         try {

package/lib/core/helpers/adapters.d.ts

@@ -1,4 +1,13 @@
 import { IAddress, IVaultAdapterConfig } from '../../types';
+/**
+ * Get adapter configuration for a vault
+ */
 export declare function getVaultAdapterConfig(vaultAddress: IAddress): IVaultAdapterConfig | undefined;
+/**
+ * Check if vault has adapter support
+ */
 export declare function vaultHasAdapter(vaultAddress: IAddress): boolean;
+/**
+ * Get deposit tokens for a vault (includes underlying + adapter tokens)
+ */
 export declare function getVaultDepositTokens(vaultAddress: IAddress, underlyingToken: IAddress): IAddress[];

package/lib/core/helpers/adapters.js

@@ -4,19 +4,30 @@ exports.getVaultAdapterConfig = getVaultAdapterConfig;
 exports.vaultHasAdapter = vaultHasAdapter;
 exports.getVaultDepositTokens = getVaultDepositTokens;
 const adapters_1 = require("../constants/adapters");
+/**
+ * Get adapter configuration for a vault
+ */
 function getVaultAdapterConfig(vaultAddress) {
     return adapters_1.VAULT_ADAPTER_CONFIGS[vaultAddress];
 }
+/**
+ * Check if vault has adapter support
+ */
 function vaultHasAdapter(vaultAddress) {
     return !!adapters_1.VAULT_ADAPTER_CONFIGS[vaultAddress];
 }
+/**
+ * Get deposit tokens for a vault (includes underlying + adapter tokens)
+ */
 function getVaultDepositTokens(vaultAddress, underlyingToken) {
     const adapterConfig = getVaultAdapterConfig(vaultAddress);
     if (!adapterConfig) {
         return [underlyingToken];
     }
+    // Return all tokens including the underlying
     const allTokens = [underlyingToken];
     if (adapterConfig.tokens && adapterConfig.tokens.length > 0) {
+        // Use configured tokens list
         adapterConfig.tokens.forEach((token) => {
             if (!allTokens.includes(token)) {
                 allTokens.push(token);

package/lib/core/helpers/chain-address.d.ts

@@ -1,3 +1,13 @@
+/**
+ * Check if a string is a valid Solana base58 address (including PDAs).
+ * Returns `false` for EVM hex addresses.
+ */
 export declare function isSolanaAddress(address: string): boolean;
+/**
+ * Check if a string is a valid Stellar address.
+ * Muxed accounts (M prefix, per SEP-0023) are intentionally excluded — they are
+ * not valid vault or contract addresses.
+ */
 export declare function isStellarAddress(address: string): boolean;
+/** Check if a string is a valid Sui address (0x + 64 hex chars). */
 export declare function isSuiAddress(address: string): boolean;