@upshiftfinance/sdk 0.0.0-stage → 0.1.0

package/lib/core/fetcher.d.ts

@@ -0,0 +1,237 @@
+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 Upshift backend services:
+ * - Authentication: fetchUpshiftWithKey, fetchUpshiftWithBearer, fetchUpshiftPublic
+ * - Retry Logic: withRetry, isRetryableError, promiseSettle
+ * - Vault Data: fetchTokenizedVaults, fetchTokenizedVaultLoans
+ * - Pricing: fetchTokenPrice (with CoinGecko fallback)
+ * - Caching: LRU cache for API responses
+ */
+export type IFetchUpshiftMethods = 'get' | 'post' | 'put';
+export type IFetchUpshiftOptions = {
+    method?: IFetchUpshiftMethods;
+    headers?: Record<string, string>;
+    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 No longer has any effect: an absent `apiKey` already sends an
+     * anonymous request. Will be removed in a future major version; drop it.
+     */
+    override?: boolean;
+};
+/**
+ * Override the default request timeout used by every Upshift 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;
+/**
+ * Record the consuming application's `appName` so every request to the
+ * Upshift backend carries it as `x-august-app`, next to
+ * `x-august-sdk-version`. This gives the backend per-integrator request
+ * counts that do not depend on Sentry sampling.
+ *
+ * Process-global, last writer wins — the same contract as
+ * `setSdkRequestTimeout` and `setPublicApiBaseUrl`. The `UpshiftSDK`
+ * constructor calls this with its validated `appName`.
+ *
+ * @param appName - Validated app-name slug, or `null` to stop sending it.
+ */
+export declare function setSdkAppName(appName?: string | null): void;
+/**
+ * Override the base URL used for `WEBSERVER_URL.public` requests — the
+ * unauthenticated vault-catalog API that `getVault` / `fetchTokenizedVault`
+ * (and the other `fetchUpshiftPublic` callers) read from. Defaults to the
+ * compiled-in prod base (`https://api.augustdigital.io/api/v1`); pass `null`
+ * (or call with no arguments) to clear.
+ *
+ * Intended for non-prod deployments that run against an ISOLATED backend
+ * (e.g. a staging API): set it once at construction via
+ * `IUpshiftBase.publicApiBaseUrl` so a staging-only vault resolves. Production
+ * leaves it unset, so behaviour is unchanged.
+ *
+ * This is a process-global override on the fetcher helpers. The SDK constructor
+ * calls it on EVERY instantiation (with `null` when `publicApiBaseUrl` is
+ * omitted), so the last `UpshiftSDK` instantiated is authoritative — a prod
+ * instance resets it to the default even after a prior staging instance set it.
+ * An invalid or non-http(s) URL is treated as "no override": it RESETS to the
+ * compiled-in default (warned) rather than retaining a prior value, so a bad env
+ * value can neither break fetches nor silently leave a previous instance's base
+ * in place.
+ *
+ * Whenever the effective base CHANGES, the shared public-response cache is
+ * cleared, so catalog data fetched from the previous backend is never served for
+ * the new one (e.g. a prod-cached vault leaking into a staging instance). Base
+ * changes happen at construction, when the cache is cold, so this is ~free.
+ *
+ * @param url - Absolute http(s) base URL (trailing slash is trimmed). `null`, or
+ *   an invalid / non-http(s) value, resets to the compiled-in public base.
+ */
+export declare function setPublicApiBaseUrl(url?: string | null): void;
+/**
+ * Read the active base for the `public` server — the SDK-level override if set,
+ * otherwise the compiled-in `WEBSERVER_URL.public`.
+ */
+export declare function getPublicApiBaseUrl(): string;
+import { CACHE, getSafeCache, setSafeCache } from './cache';
+export { CACHE, getSafeCache, setSafeCache };
+/**
+ * Make requests to Upshift backend services, sending an API key when one is
+ * configured. Many backend routes — vault-linked sub-account reads, the two
+ * collateral risk routes, timelock requests — answer anonymous callers, so a
+ * missing key is not an error here: the request goes out without the
+ * `x-api-key` header and the backend decides. Routes that do require a key
+ * answer `401`, which surfaces as an `UpshiftAuthError` with code
+ * `AUTH_UNAUTHORIZED`.
+ * Automatically logs errors with correlation IDs for debugging.
+ * @param apiKey - Upshift API key, or `undefined` for an anonymous request
+ * @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 fetchUpshiftWithKey(apiKey: string | undefined, relativeUrl: string, options?: IFetchUpshiftOptions): Promise<Response>;
+/**
+ * Make unauthenticated requests to Upshift 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 fetchUpshiftPublic(relativeUrl: string, options?: IFetchUpshiftOptions): 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 fetchUpshiftWithBearer(bearerToken: string, relativeUrl: string, options?: IFetchUpshiftOptions): 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<number>;
+/**
+ * Fetch token price by contract address and chain ID from Upshift 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>;
+/**
+ * Settle a batch of async tasks, allowing partial failure.
+ *
+ * Unlike `Promise.all`, a failing task does not reject the batch: its slot in
+ * the result array is `null`, so results stay index-aligned with the input.
+ *
+ * Retries only apply to **thunks** (`() => Promise<T>`): a thunk is invoked
+ * again on each attempt via {@link withRetry} (exponential backoff from
+ * `baseDelay`, retryable network errors only). A **bare promise** is already
+ * in flight and cannot be re-executed — re-awaiting it just yields the same
+ * rejection — so bare promises are settled exactly once, with no retry and
+ * no backoff sleep. Pass thunks when a retry is actually wanted.
+ *
+ * @param tasks - Promises and/or thunks to settle. Mixed arrays are allowed.
+ *   An empty array resolves to `[]`.
+ * @param maxRetries - Maximum retry attempts per **thunk** (ignored for bare
+ *   promises). Default `3`.
+ * @param baseDelay - Initial backoff delay in milliseconds for thunk retries
+ *   (ignored for bare promises). Default `1000`.
+ * @returns Results in input order; `null` in the slot of any task that
+ *   ultimately failed. Never rejects.
+ * @example
+ * ```ts
+ * // Bare promises: settle once, failures become null.
+ * const [a, b] = await promiseSettle([getA(), getB()]);
+ * // Thunks: each failing call is retried up to 3 times with backoff.
+ * const [c, d] = await promiseSettle([() => getC(), () => getD()]);
+ * ```
+ */
+export declare function promiseSettle<T>(tasks: Array<Promise<T> | (() => Promise<T>)>, maxRetries?: number, baseDelay?: number): Promise<T[]>;