@augustdigital/sdk 8.3.2 → 8.6.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;
+    data?: unknown;
     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[]>;
-export declare function fetchTokenPrice(symbol: string, provider?: IContractRunner, coinGeckoKey?: string, headers?: IWSMonitorHeaders): Promise<any>;
+/**
+ * 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<number>;
+/**
+ * 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[]>;