@augustdigital/sdk 8.3.2 → 8.6.0

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();
@@ -68,18 +90,23 @@ function buildRequestAbortSignal(options) {
         timeoutController.abort();
     }, timeoutMs);
     let signal = timeoutController.signal;
-    let relayCleanup = () => { };
+    // No-op by default; replaced with a real listener-removal closure only when
+    // the manual relay fallback path below registers an 'abort' listener.
+    let relayCleanup = () => undefined;
     if (options?.signal) {
+        // Capture in a local so the cleanup closure below keeps the non-nullable
+        // narrowing (a closure over `options.signal` would otherwise be re-widened).
+        const callerSignal = options.signal;
         if (typeof AbortSignal.any === 'function') {
-            signal = AbortSignal.any([timeoutController.signal, options.signal]);
+            signal = AbortSignal.any([timeoutController.signal, callerSignal]);
         }
-        else if (options.signal.aborted) {
+        else if (callerSignal.aborted) {
             timeoutController.abort();
         }
         else {
             const relay = () => timeoutController.abort();
-            options.signal.addEventListener('abort', relay, { once: true });
-            relayCleanup = () => options.signal.removeEventListener('abort', relay);
+            callerSignal.addEventListener('abort', relay, { once: true });
+            relayCleanup = () => callerSignal.removeEventListener('abort', relay);
         }
     }
     return {
@@ -98,8 +125,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 +153,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 +189,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 +209,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 +245,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 +274,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 +329,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 +387,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 +400,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++) {
@@ -328,12 +427,22 @@ async function withRetry(fn, maxRetries = 3, baseDelay = 1000, shouldRetry = isR
             throw error;
         }
     }
-    throw lastError;
+    // Unreachable in practice: the final attempt re-throws inside the loop. This
+    // satisfies the compiler's control-flow analysis without a non-null assertion.
+    throw lastError ?? new Error('withRetry exhausted retries without an error');
 }
+/**
+ * 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 +455,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) {
@@ -356,21 +466,31 @@ async function fetchTokenizedVault(pool, headers, loadSubaccounts, loadSnapshots
         }
         const queryString = params.toString();
         if (queryString) {
-            endpoint += '?' + queryString;
+            endpoint += `?${queryString}`;
         }
         const tokenizedVaultsResponse = await fetchAugustPublic(endpoint, {
             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 +505,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) {
@@ -395,16 +516,17 @@ async function fetchTokenizedVaults(pool, headers, loadSubaccounts, loadSnapshot
         }
         const queryString = params.toString();
         if (queryString) {
-            endpoint += '?' + queryString;
+            endpoint += `?${queryString}`;
         }
         const tokenizedVaultsResponse = await fetchAugustPublic(endpoint, {
             headers: headers,
         });
         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 +534,93 @@ 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;
 }
+// Normalize both raw integers to the same decimal scale BEFORE dividing —
+// dividing the raw bigints first floors the ratio to ~1 and loses all
+// fractional precision. Returns 1 for an empty vault (priced 1:1).
+function normalizedSharePrice(totalAssets, totalSupply, decimals) {
+    const supply = Number((0, core_1.toNormalizedBn)(totalSupply, decimals).normalized);
+    if (!supply)
+        return 1;
+    return Number((0, core_1.toNormalizedBn)(totalAssets, decimals).normalized) / supply;
+}
+/**
+ * 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') {
@@ -474,19 +632,22 @@ async function _fetchTokenPriceInternal(symbol, provider, coinGeckoKey, headers)
             const sharePrice = await vaultContract.getSharePrice();
             return Number((0, core_1.toNormalizedBn)(sharePrice, decimals).normalized);
         }
-        catch (e) {
+        catch {
             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([
@@ -495,12 +656,13 @@ async function _fetchTokenPriceInternal(symbol, provider, coinGeckoKey, headers)
                 vaultContract.decimals(),
             ]);
             const decimals = Number(rawDecimals);
-            const ratio = (totalAssets || BigInt(0)) / (totalSupply || BigInt(0)) || 1;
-            return json.price * Number((0, core_1.toNormalizedBn)(ratio, decimals).normalized);
+            const sharePrice = normalizedSharePrice(totalAssets, totalSupply, decimals);
+            return json.price * sharePrice;
         }
         return json.price;
     }
-    catch (e) {
+    catch {
+        // 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);
@@ -510,8 +672,8 @@ async function _fetchTokenPriceInternal(symbol, provider, coinGeckoKey, headers)
                 vaultContract.decimals(),
             ]);
             const decimals = Number(rawDecimals);
-            const ratio = (totalAssets || BigInt(0)) / (totalSupply || BigInt(0)) || 1;
-            return fallbackPrice * Number((0, core_1.toNormalizedBn)(ratio, decimals).normalized);
+            const sharePrice = normalizedSharePrice(totalAssets, totalSupply, decimals);
+            return fallbackPrice * sharePrice;
         }
         if (fallbackPrice) {
             return fallbackPrice;
@@ -521,6 +683,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,32 +716,58 @@ 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;
-    if (cache_1.CACHE.get(key)) {
-        loans = cache_1.CACHE.get(key);
+    const cached = await (0, cache_1.getSafeCache)(key);
+    if (cached) {
+        loans = cached;
     }
     else {
         const tokenizedVaultsResponse = await fetchAugustPublic(core_2.WEBSERVER_ENDPOINTS.public.tokenizedVault.loans(pool, chainId, true), { headers: headers });
         loans = (await tokenizedVaultsResponse.json()).loans;
-        cache_1.CACHE.set(key, loans);
+        await (0, cache_1.setSafeCache)(key, loans);
     }
     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;
-    if (cache_1.CACHE.get(key)) {
-        loans = cache_1.CACHE.get(key);
+    const cached = await (0, cache_1.getSafeCache)(key);
+    if (cached) {
+        loans = cached;
     }
     else {
         const tokenizedVaultsResponse = await fetchAugustPublic(core_2.WEBSERVER_ENDPOINTS.public.tokenizedVault.subaccountLoans(pool, chainId, true), { headers: headers });
         loans = (await tokenizedVaultsResponse.json()).loans;
-        cache_1.CACHE.set(key, loans);
+        await (0, cache_1.setSafeCache)(key, loans);
     }
     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 +779,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';
+import type { 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;

package/lib/core/helpers/chain-address.js

@@ -5,7 +5,12 @@ exports.isStellarAddress = isStellarAddress;
 exports.isSuiAddress = isSuiAddress;
 const ethers_1 = require("ethers");
 const web3_js_1 = require("@solana/web3.js");
+/** Stellar uses RFC 4648 base32; 56 chars, prefixed by G (public key) or C (contract/Soroban). */
 const STELLAR_ADDRESS_RE = /^[A-Z2-7]{56}$/;
+/**
+ * Check if a string is a valid Solana base58 address (including PDAs).
+ * Returns `false` for EVM hex addresses.
+ */
 function isSolanaAddress(address) {
     if (!address)
         return false;
@@ -19,6 +24,11 @@ function isSolanaAddress(address) {
         return false;
     }
 }
+/**
+ * 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.
+ */
 function isStellarAddress(address) {
     if (!address || typeof address !== 'string')
         return false;
@@ -28,6 +38,7 @@ function isStellarAddress(address) {
         return false;
     return STELLAR_ADDRESS_RE.test(address);
 }
+/** Check if a string is a valid Sui address (0x + 64 hex chars). */
 function isSuiAddress(address) {
     if (!address || typeof address !== 'string')
         return false;