@upshiftfinance/sdk 0.0.0-stage → 0.1.0

package/lib/core/fetcher.js

@@ -0,0 +1,1103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setSafeCache = exports.getSafeCache = exports.CACHE = void 0;
+exports.setSdkRequestTimeout = setSdkRequestTimeout;
+exports.getSdkRequestTimeout = getSdkRequestTimeout;
+exports.setSdkAppName = setSdkAppName;
+exports.setPublicApiBaseUrl = setPublicApiBaseUrl;
+exports.getPublicApiBaseUrl = getPublicApiBaseUrl;
+exports.fetchUpshiftWithKey = fetchUpshiftWithKey;
+exports.fetchUpshiftPublic = fetchUpshiftPublic;
+exports.fetchUpshiftWithBearer = fetchUpshiftWithBearer;
+exports.isRetryableError = isRetryableError;
+exports.withRetry = withRetry;
+exports.fetchTokenizedVault = fetchTokenizedVault;
+exports.fetchTokenizedVaults = fetchTokenizedVaults;
+exports.fetchTokenPrice = fetchTokenPrice;
+exports.fetchTokenPriceByAddress = fetchTokenPriceByAddress;
+exports.fetchTokenizedVaultLoans = fetchTokenizedVaultLoans;
+exports.fetchTokenizedVaultSubaccountLoans = fetchTokenizedVaultSubaccountLoans;
+exports.fetchVaultHistoricalTimeseries = fetchVaultHistoricalTimeseries;
+exports.promiseSettle = promiseSettle;
+const core_1 = require("./helpers/core");
+const ethers_1 = require("ethers");
+const abis_1 = require("../abis");
+const lru_cache_1 = require("lru-cache");
+const chain_address_1 = require("./helpers/chain-address");
+const chain_error_1 = require("./helpers/chain-error");
+const fetcher_1 = require("../services/coingecko/fetcher");
+const logger_1 = require("./logger");
+const ethers_2 = require("ethers");
+const web3_1 = require("./constants/web3");
+const core_2 = require("./constants/core");
+const vault_version_1 = require("./helpers/vault-version");
+const analytics_1 = require("./analytics");
+const sanitize_1 = require("./analytics/sanitize");
+const sentry_1 = require("./analytics/sentry");
+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.UpshiftAuthError('AUTH_UNAUTHORIZED', message, options);
+    }
+    if (status === 403) {
+        return new errors_1.UpshiftAuthError('AUTH_FORBIDDEN', message, options);
+    }
+    if (status === 429) {
+        return new errors_1.UpshiftRateLimitError(message, options);
+    }
+    return new errors_1.UpshiftServerError(status, message, options);
+}
+let SDK_REQUEST_TIMEOUT_OVERRIDE = null;
+/**
+ * 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.
+ */
+function setSdkRequestTimeout(ms = null) {
+    if (ms === null) {
+        SDK_REQUEST_TIMEOUT_OVERRIDE = null;
+        return;
+    }
+    if (!Number.isFinite(ms) || ms <= 0) {
+        logger_1.Logger.log.warn('setSdkRequestTimeout', 'Ignoring non-positive timeout', {
+            ms,
+        });
+        return;
+    }
+    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;
+}
+let SDK_APP_NAME = null;
+/**
+ * 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.
+ */
+function setSdkAppName(appName = null) {
+    SDK_APP_NAME = appName;
+}
+/**
+ * Client-identification headers merged into every backend fetcher's
+ * defaults. Both values are low-cardinality slugs, never credentials.
+ */
+function sdkClientHeaders() {
+    const headers = {
+        'x-august-sdk-version': (0, sentry_1.getSDKVersion)(),
+    };
+    if (SDK_APP_NAME)
+        headers['x-august-app'] = SDK_APP_NAME;
+    return headers;
+}
+let PUBLIC_API_BASE_OVERRIDE = null;
+/**
+ * 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.
+ */
+function setPublicApiBaseUrl(url = null) {
+    const previous = PUBLIC_API_BASE_OVERRIDE;
+    if (url === null) {
+        PUBLIC_API_BASE_OVERRIDE = null;
+    }
+    else {
+        let parsed = null;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            parsed = null;
+        }
+        if (!parsed ||
+            (parsed.protocol !== 'https:' && parsed.protocol !== 'http:')) {
+            // Reset to the default rather than retaining a stale prior override, so
+            // each construction stays authoritative and a bad env value fails safe to
+            // prod instead of inheriting another instance's base.
+            logger_1.Logger.log.warn('setPublicApiBaseUrl', 'Ignoring invalid/non-http(s) URL; resetting to the default public base', { url });
+            PUBLIC_API_BASE_OVERRIDE = null;
+        }
+        else {
+            // Store WITHOUT a trailing slash: buildUpshiftUrl concatenates
+            // `${base}${relativeUrl}` (relativeUrl starts with '/'), so a trailing
+            // slash on the base would produce a double slash.
+            PUBLIC_API_BASE_OVERRIDE = url.replace(/\/+$/, '');
+        }
+    }
+    if (PUBLIC_API_BASE_OVERRIDE !== previous) {
+        // The public base moved (or reset). Drop cached public-catalog responses
+        // keyed against the previous base (see fetchTokenizedVault(s) etc.) so they
+        // aren't served for the new backend.
+        cache_1.CACHE.clear();
+    }
+}
+/**
+ * Read the active base for the `public` server — the SDK-level override if set,
+ * otherwise the compiled-in `WEBSERVER_URL.public`.
+ */
+function getPublicApiBaseUrl() {
+    return PUBLIC_API_BASE_OVERRIDE ?? core_2.WEBSERVER_URL.public;
+}
+/**
+ * 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();
+    let didTimeout = false;
+    const timeoutId = setTimeout(() => {
+        didTimeout = true;
+        timeoutController.abort();
+    }, timeoutMs);
+    let signal = timeoutController.signal;
+    // 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, callerSignal]);
+        }
+        else if (callerSignal.aborted) {
+            timeoutController.abort();
+        }
+        else {
+            const relay = () => timeoutController.abort();
+            callerSignal.addEventListener('abort', relay, { once: true });
+            relayCleanup = () => callerSignal.removeEventListener('abort', relay);
+        }
+    }
+    return {
+        signal,
+        timeoutId,
+        timeoutMs,
+        timedOut: () => didTimeout,
+        cleanup: () => {
+            clearTimeout(timeoutId);
+            relayCleanup();
+        },
+    };
+}
+/**
+ * Build the `UpshiftTimeoutError` a fetcher throws when its own timeout fired,
+ * and record it as a breadcrumb rather than a Sentry issue.
+ *
+ * Severity rationale: the error is *thrown* to the caller, so whoever owns the
+ * request decides whether it is fatal. Logging it at `error` here as well made
+ * every timeout a standalone Sentry issue even when the caller swallowed it
+ * (`Promise.allSettled` fan-outs in `getVaultAllocations` do exactly that) — a
+ * single stalled render produced 20–30 identical issues in the same second and
+ * ~40k events a week, none of them separately actionable. As a breadcrumb the
+ * timeout still rides along with whatever the caller ultimately reports, with
+ * the endpoint and elapsed budget attached.
+ *
+ * @param tag - Call-site tag (`fetchUpshiftPublic`, …) used as the breadcrumb label.
+ * @param relativeUrl - Endpoint path that timed out; sanitized before use.
+ * @param timeoutMs - Timeout budget that elapsed, in milliseconds.
+ * @returns The error to throw. Never throws.
+ * @internal
+ */
+function timeoutErrorFor(tag, relativeUrl, timeoutMs) {
+    const timeoutError = new errors_1.UpshiftTimeoutError((0, sanitize_1.sanitizeString)(`Request timeout after ${timeoutMs / 1000}s: ${relativeUrl}`), timeoutMs);
+    logger_1.Logger.log.warn(tag, { relativeUrl, timeoutMs, reason: 'request timeout' });
+    return timeoutError;
+}
+let _overrideDeprecationWarned = false;
+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(`[@upshiftfinance/sdk] ${callerTag}: option "override" is deprecated and has no effect — an absent apiKey already sends an anonymous request. It will be removed in a future major version; drop it.`);
+}
+/**
+ * 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;
+    const h = headers;
+    if (typeof h.get === 'function') {
+        return h.get(name) ?? undefined;
+    }
+    const v = headers[name];
+    return typeof v === 'string' ? v : undefined;
+}
+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; } });
+/**
+ * TTL for the per-vault "active loans" lists returned by
+ * {@link fetchTokenizedVaultLoans} / {@link fetchTokenizedVaultSubaccountLoans}.
+ *
+ * Loan state changes as borrowers draw and repay, so these lists must not sit
+ * on the 24 h `CACHE` default — a loan that was repaid an hour ago would still
+ * be reported as active. 10 minutes matches the vault-catalog TTL used by
+ * `fetchTokenizedVault`.
+ */
+const ACTIVE_LOANS_TTL_MS = 10 * 60 * 1000;
+/**
+ * Drop `null` / `undefined` entries from a header map before it reaches
+ * `fetch`.
+ *
+ * Why: `UpshiftBase.monitoring` starts life as
+ * `{ 'x-user-id': undefined, 'x-environment': 'PROD' }` and is spread straight
+ * into request headers. `fetch` stringifies header values, so an `undefined`
+ * slot is sent on the wire as the literal string `"undefined"` — the backend
+ * then sees a bogus user id until `updateWallet` runs. Stripping nullish
+ * values here means "not set" is actually absent from the request.
+ *
+ * @param headers - Header map that may contain nullish values (an
+ *   `IWSMonitorHeaders` object or a spread of one). `undefined` as a whole
+ *   yields `{}`.
+ * @returns A new map containing only the entries whose value is a string.
+ *   Never mutates the input.
+ * @internal
+ */
+function compactHeaders(headers) {
+    const out = {};
+    if (!headers)
+        return out;
+    for (const [name, value] of Object.entries(headers)) {
+        if (typeof value === 'string')
+            out[name] = value;
+    }
+    return out;
+}
+/**
+ * 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, // 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, // 5 seconds
+    allowStale: false,
+});
+/**
+ * In-flight price requests to prevent duplicate simultaneous API calls.
+ */
+const PRICE_REQUESTS = new Map();
+/**
+ * In-flight `/tokenized_vault` requests, keyed by the same cache key the
+ * response is stored under.
+ *
+ * The response cache alone only de-duplicates *sequential* calls: a cold
+ * process (a fresh serverless container, a hard page load) fans out N
+ * concurrent `getVault` calls for the same vault before any of them has
+ * populated the cache, so all N hit the backend. Under load that self-inflicted
+ * stampede is what pushed `/tokenized_vault/{address}` past its timeout — the
+ * single largest source of `UpshiftTimeoutError` in production.
+ *
+ * Joining concurrent callers onto one promise collapses that fan-out to a
+ * single request. Entries are removed as soon as the request settles, so a
+ * failure is never cached — the next caller retries.
+ */
+const TOKENIZED_VAULT_REQUESTS = new Map();
+/**
+ * Run `factory` at most once per `key` while it is in flight, joining any
+ * concurrent caller onto the same promise.
+ *
+ * This is a de-duplication primitive, not a cache: the entry lives only for the
+ * duration of the request and is cleared on both success and failure, so errors
+ * are never shared beyond the callers that were already waiting.
+ *
+ * @param registry - Map holding the in-flight promises for this resource type.
+ * @param key - Identity of the request; callers sharing a key share a result.
+ * @param factory - Produces the promise to run when no request is in flight.
+ * @returns The shared promise for `key`.
+ * @internal
+ */
+function dedupeInFlight(registry, key, factory) {
+    const existing = registry.get(key);
+    if (existing)
+        return existing;
+    const request = factory().finally(() => {
+        registry.delete(key);
+    });
+    registry.set(key, request);
+    return request;
+}
+/**
+ * Build an Upshift backend URL, rejecting unknown server keys and any
+ * `relativeUrl` that would escape the configured origin.
+ * Throws `UpshiftValidationError` with `code: 'INVALID_URL'`.
+ */
+function buildUpshiftUrl(server, relativeUrl) {
+    const serverKey = server;
+    // The `public` base is overridable (setPublicApiBaseUrl / IUpshiftBase
+    // .publicApiBaseUrl) so non-prod deployments can point vault-catalog reads at
+    // an isolated backend. Resolved once here via getPublicApiBaseUrl() (single
+    // source of truth), so the origin check below validates against the OVERRIDDEN
+    // origin.
+    const base = serverKey === 'public' ? getPublicApiBaseUrl() : core_2.WEBSERVER_URL[serverKey];
+    if (!base) {
+        throw new errors_1.UpshiftValidationError('INVALID_URL', `Unknown Upshift server "${String(server)}". Expected one of: ${Object.keys(core_2.WEBSERVER_URL).join(', ')}`);
+    }
+    if (typeof relativeUrl !== 'string' || relativeUrl.length === 0) {
+        throw new errors_1.UpshiftValidationError('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.UpshiftValidationError('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 {
+        url = new URL(candidate);
+    }
+    catch {
+        throw new errors_1.UpshiftValidationError('INVALID_URL', `Invalid URL path: ${(0, sanitize_1.sanitizeString)(relativeUrl)}`);
+    }
+    const baseOrigin = new URL(base).origin;
+    if (url.origin !== baseOrigin) {
+        throw new errors_1.UpshiftValidationError('INVALID_URL', `URL origin mismatch: refusing to fetch ${url.origin} from a "${serverKey}" request scoped to ${baseOrigin}`);
+    }
+    return url.toString();
+}
+/**
+ * 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
+ */
+async function fetchUpshiftWithKey(apiKey, relativeUrl, options) {
+    if (options?.override) {
+        warnOverrideDeprecation('fetchUpshiftWithKey');
+    }
+    const defaultHeaders = {
+        ...sdkClientHeaders(),
+        ...(apiKey ? { 'x-api-key': apiKey } : {}),
+        'content-type': 'application/json',
+        accept: 'application/json',
+    };
+    const { signal: requestSignal, timeoutMs: effectiveTimeoutMs, timedOut, cleanup, } = buildRequestAbortSignal(options);
+    const startTime = performance.now();
+    const server = options?.server || 'production';
+    // Set once the response has been recorded with its real status, so the
+    // `catch` below does not record the same non-OK request a second time as
+    // status 0 (which double-counted every 4xx/5xx in the API-call metrics).
+    let tracked = false;
+    try {
+        const safeUrl = buildUpshiftUrl(server, relativeUrl);
+        const res = await fetch(safeUrl, {
+            headers: compactHeaders({
+                ...defaultHeaders,
+                ...options?.headers,
+            }),
+            method: options?.method ?? 'GET',
+            body: JSON.stringify(options?.data),
+            signal: requestSignal,
+        });
+        cleanup();
+        // Track API call
+        (0, analytics_1.trackApiCall)(relativeUrl, options?.method ?? 'GET', startTime, res.status, server);
+        tracked = true;
+        const correlationId = readResponseHeader(res.headers, 'x-correlation-id');
+        const logger = logger_1.Logger.getLogger();
+        if (!res.ok) {
+            if (correlationId && logger) {
+                logger.setTag('correlation_id', correlationId);
+            }
+            const error = errorFromResponseStatus(res.status, `Request failed: ${res.status}`, { correlationId });
+            logger?.captureException(error, { correlationId, status: res.status });
+            throw error;
+        }
+        return res;
+    }
+    catch (error) {
+        cleanup();
+        if (!tracked) {
+            (0, analytics_1.trackApiCall)(relativeUrl, options?.method ?? 'GET', startTime, 0, server);
+        }
+        const err = error instanceof Error ? error : new Error(String(error));
+        if (err.name === 'AbortError') {
+            if (!timedOut()) {
+                throw err;
+            }
+            throw timeoutErrorFor('fetchUpshiftWithKey', relativeUrl, effectiveTimeoutMs);
+        }
+        throw err;
+    }
+}
+/**
+ * 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
+ */
+async function fetchUpshiftPublic(relativeUrl, options) {
+    const defaultHeaders = {
+        ...sdkClientHeaders(),
+        'content-type': 'application/json',
+        accept: 'application/json',
+    };
+    const { signal: requestSignal, timeoutMs: effectiveTimeoutMs, timedOut, cleanup, } = buildRequestAbortSignal(options);
+    const startTime = performance.now();
+    // See fetchUpshiftWithKey: prevents a second status-0 record for non-OK responses.
+    let tracked = false;
+    try {
+        const safeUrl = buildUpshiftUrl('public', relativeUrl);
+        const res = await fetch(safeUrl, {
+            headers: compactHeaders({
+                ...defaultHeaders,
+                ...options?.headers,
+            }),
+            method: options?.method ?? 'GET',
+            body: JSON.stringify(options?.data),
+            signal: requestSignal,
+        });
+        cleanup();
+        (0, analytics_1.trackApiCall)(relativeUrl, options?.method ?? 'GET', startTime, res.status, 'public');
+        tracked = true;
+        const correlationId = readResponseHeader(res.headers, 'x-correlation-id');
+        const logger = logger_1.Logger.getLogger();
+        if (!res.ok) {
+            if (correlationId && logger) {
+                logger.setTag('correlation_id', correlationId);
+            }
+            const error = errorFromResponseStatus(res.status, `Request failed: ${res.status}`, { correlationId });
+            logger?.captureException(error, { correlationId, status: res.status });
+            throw error;
+        }
+        return res;
+    }
+    catch (error) {
+        cleanup();
+        if (!tracked) {
+            (0, analytics_1.trackApiCall)(relativeUrl, options?.method ?? 'GET', startTime, 0, 'public');
+        }
+        const err = error instanceof Error ? error : new Error(String(error));
+        if (err.name === 'AbortError') {
+            if (!timedOut()) {
+                throw err;
+            }
+            throw timeoutErrorFor('fetchUpshiftPublic', relativeUrl, effectiveTimeoutMs);
+        }
+        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 fetchUpshiftWithBearer(bearerToken, relativeUrl, options) {
+    const defaultHeaders = {
+        ...sdkClientHeaders(),
+        authorization: `Bearer ${bearerToken}`,
+        'content-type': 'application/json',
+        accept: 'application/json',
+    };
+    const { signal: requestSignal, timeoutMs: effectiveTimeoutMs, timedOut, cleanup, } = buildRequestAbortSignal(options);
+    const startTime = performance.now();
+    const server = options?.server ?? 'production';
+    // See fetchUpshiftWithKey: prevents a second status-0 record for non-OK responses.
+    let tracked = false;
+    try {
+        const safeUrl = buildUpshiftUrl(server, relativeUrl);
+        const res = await fetch(safeUrl, {
+            headers: compactHeaders({
+                ...defaultHeaders,
+                ...options?.headers,
+            }),
+            method: options?.method ?? 'GET',
+            body: JSON.stringify(options?.data),
+            signal: requestSignal,
+        });
+        cleanup();
+        (0, analytics_1.trackApiCall)(relativeUrl, options?.method ?? 'GET', startTime, res.status, server);
+        tracked = true;
+        const correlationId = readResponseHeader(res.headers, 'x-correlation-id');
+        const logger = logger_1.Logger.getLogger();
+        if (!res.ok) {
+            if (correlationId && logger) {
+                logger.setTag('correlation_id', correlationId);
+            }
+            const error = errorFromResponseStatus(res.status, `Request failed: ${res.status}`, { correlationId });
+            logger?.captureException(error, { correlationId, status: res.status });
+            throw error;
+        }
+        return res;
+    }
+    catch (error) {
+        cleanup();
+        if (!tracked) {
+            (0, analytics_1.trackApiCall)(relativeUrl, options?.method ?? 'GET', startTime, 0, server);
+        }
+        const err = error instanceof Error ? error : new Error(String(error));
+        if (err.name === 'AbortError') {
+            if (!timedOut()) {
+                throw err;
+            }
+            throw timeoutErrorFor('fetchUpshiftWithBearer', relativeUrl, effectiveTimeoutMs);
+        }
+        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' ||
+        error.message.includes('ETIMEDOUT') ||
+        error.message.includes('timeout') ||
+        error.message.includes('ECONNRESET') ||
+        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++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt < maxRetries && shouldRetry(error)) {
+                const delay = baseDelay * 2 ** attempt;
+                logger_1.Logger.log.warn('withRetry', `Attempt ${attempt + 1} failed, retrying in ${delay}ms: ${error.message}`);
+                await new Promise((resolve) => setTimeout(resolve, delay));
+                continue;
+            }
+            throw error;
+        }
+    }
+    // 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');
+    if (loadSnapshots === false)
+        keyParts.push('no-snapshots');
+    const key = keyParts.join('-');
+    let tokenizedVault;
+    const cachedResponse = await (0, cache_1.getSafeCache)(key);
+    if (cachedResponse) {
+        tokenizedVault = cachedResponse;
+    }
+    if (!tokenizedVault) {
+        // Concurrent callers for the same vault share one request; see
+        // TOKENIZED_VAULT_REQUESTS.
+        tokenizedVault = await dedupeInFlight(TOKENIZED_VAULT_REQUESTS, key, async () => {
+            // Build endpoint URL with optional query parameters
+            let endpoint = core_2.WEBSERVER_ENDPOINTS.public.tokenizedVault.byVaultAddress(pool);
+            const params = new URLSearchParams();
+            if (loadSubaccounts === false) {
+                params.set('load_subaccounts', 'false');
+            }
+            if (loadSnapshots === false) {
+                params.set('load_snapshots', 'false');
+            }
+            const queryString = params.toString();
+            if (queryString) {
+                endpoint += `?${queryString}`;
+            }
+            const tokenizedVaultsResponse = await fetchUpshiftPublic(endpoint, {
+                headers: headers,
+            });
+            const parsed = (await tokenizedVaultsResponse.json());
+            cache_1.CACHE.set(key, parsed, { ttl: 1000 * 60 * 10 }); // Cache for 10 minutes
+            return parsed;
+        });
+    }
+    // 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) ||
+            (0, chain_address_1.isSuiAddress)(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 from the request shape only. `pool` is NOT part of the
+    // request (the endpoint always returns the full catalog), so keying on it
+    // would store one full catalog copy per pool address and refetch it for
+    // every new pool. The pool filter is applied after the cached read below.
+    const keyParts = ['tokenized-vaults'];
+    if (loadSubaccounts === false)
+        keyParts.push('no-subaccounts');
+    if (loadSnapshots === false)
+        keyParts.push('no-snapshots');
+    const key = keyParts.join('-');
+    let tokenizedVaults;
+    const cachedResponse = await (0, cache_1.getSafeCache)(key);
+    if (cachedResponse) {
+        tokenizedVaults = cachedResponse;
+    }
+    if (!tokenizedVaults) {
+        // The vault list is requested by every vault page at once on a cold
+        // process; join concurrent callers onto one request.
+        tokenizedVaults = await dedupeInFlight(TOKENIZED_VAULT_REQUESTS, key, async () => {
+            // Build endpoint URL with optional query parameters
+            let endpoint = core_2.WEBSERVER_ENDPOINTS.public.tokenizedVault.list;
+            const params = new URLSearchParams();
+            if (loadSubaccounts === false) {
+                params.set('load_subaccounts', 'false');
+            }
+            if (loadSnapshots === false) {
+                params.set('load_snapshots', 'false');
+            }
+            const queryString = params.toString();
+            if (queryString) {
+                endpoint += `?${queryString}`;
+            }
+            const tokenizedVaultsResponse = await fetchUpshiftPublic(endpoint, {
+                headers: headers,
+            });
+            const parsed = (await tokenizedVaultsResponse.json());
+            const ttl = 1000 * 60 * 15; // 15 minute cache
+            cache_1.CACHE.set(key, parsed, { ttl });
+            return parsed;
+        });
+    }
+    // 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) ||
+            (0, chain_address_1.isSuiAddress)(pool))) {
+        const foundObj = tokenizedVaults.find((t) => t.address.toLowerCase() === pool.toLowerCase());
+        return foundObj ? [foundObj] : [];
+    }
+    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') {
+        try {
+            const vaultContract = new ethers_2.Contract((0, ethers_1.getAddress)(foundVaultLpAsset?.vault), abis_1.ABI_TOKENIZED_VAULT_V2, provider);
+            // Same bounded, no-fallback retry the write paths use for this selector
+            // (`getReceiptTokenAddressOrThrow` in `core/helpers/web3`). It cannot be
+            // reused here: `helpers/web3` imports `fetchTokenizedVault` from this
+            // module, so importing it back would be a circular dependency (CLAUDE.md
+            // §9). A transient empty `eth_call` response is absorbed; a vault that
+            // genuinely lacks `lpTokenAddress()` still falls into the catch below
+            // after the attempts are spent.
+            const receiptAddress = await (0, chain_error_1.retryOnTransientRpc)('fetchTokenPrice:receiptToken', () => vaultContract.lpTokenAddress(), { vault: foundVaultLpAsset.vault }, (error) => (0, chain_error_1.isRetryableRpcError)(error) ||
+                (0, chain_error_1.isEmptyViewResponse)(error, chain_error_1.LP_TOKEN_ADDRESS_SELECTOR));
+            const receiptContract = new ethers_2.Contract(receiptAddress, [web3_1.MIN_ABIS.decimals], provider);
+            const decimals = Number(await receiptContract.decimals());
+            const sharePrice = await vaultContract.getSharePrice();
+            return Number((0, core_1.toNormalizedBn)(sharePrice, decimals).normalized);
+        }
+        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 Upshift backend
+        const res = await fetch(`https://prices.augustdigital.io/price/${_symbol}`, { headers: compactHeaders(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([
+                vaultContract.totalAssets(),
+                vaultContract.totalSupply(),
+                vaultContract.decimals(),
+            ]);
+            const decimals = Number(rawDecimals);
+            const sharePrice = normalizedSharePrice(totalAssets, totalSupply, decimals);
+            return json.price * sharePrice;
+        }
+        return json.price;
+    }
+    catch {
+        // Fallback to CoinGecko if primary source fails
+        const fallbackPrice = await (0, fetcher_1.fetchTokenPricesFromCoinGecko)(symbol, coinGeckoKey);
+        // CoinGecko resolves to `null` when it has no price series for the coin.
+        // Guard BEFORE the LP branch: `null * sharePrice` is `0`, which the caller
+        // would cache in PRICE_CACHE as a genuine $0 price for the next 30 s.
+        // Throwing instead lands in PRICE_ERROR_CACHE (5 s) and surfaces as a
+        // typed error the consumer can branch on.
+        if (!fallbackPrice) {
+            throw new errors_1.UpshiftPriceUnavailableError(`failed to fetch token price: no price available for "${symbol}" from the Upshift price server or CoinGecko`, { context: { symbol } });
+        }
+        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([
+                vaultContract.totalAssets(),
+                vaultContract.totalSupply(),
+                vaultContract.decimals(),
+            ]);
+            const decimals = Number(rawDecimals);
+            const sharePrice = normalizedSharePrice(totalAssets, totalSupply, decimals);
+            return fallbackPrice * sharePrice;
+        }
+        return fallbackPrice;
+    }
+}
+/**
+ * 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
+ */
+async function fetchTokenPriceByAddress(address, chainId, headers) {
+    if (!address || !chainId) {
+        return 0;
+    }
+    try {
+        const url = new URL(`${core_2.PRICE_SERVER_URL}/price_by_address_chain`);
+        url.searchParams.set('address', address);
+        url.searchParams.set('chain', chainId.toString());
+        url.searchParams.set('method', 'contract');
+        const res = await fetch(url.toString(), {
+            headers: compactHeaders({
+                accept: 'application/json',
+                ...headers,
+            }),
+        });
+        if (res.status !== 200) {
+            throw new Error(`Failed to fetch price for ${address} on chain ${chainId}: ${res.statusText}`);
+        }
+        const json = (await res.json());
+        return json.price || 0;
+    }
+    catch (e) {
+        logger_1.Logger.log.warn('fetchTokenPriceByAddress', `Failed to fetch price for ${address} on chain ${chainId}: ${e}`);
+        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;
+    const cached = await (0, cache_1.getSafeCache)(key);
+    if (cached) {
+        loans = cached;
+    }
+    else {
+        const tokenizedVaultsResponse = await fetchUpshiftPublic(core_2.WEBSERVER_ENDPOINTS.public.tokenizedVault.loans(pool, chainId, true), { headers: headers });
+        loans = (await tokenizedVaultsResponse.json()).loans;
+        // Short TTL: loan state is live data (see ACTIVE_LOANS_TTL_MS). The
+        // falsy guard mirrors `setSafeCache` so a missing `loans` field is not
+        // cached as a sticky empty result.
+        if (loans)
+            cache_1.CACHE.set(key, loans, { ttl: ACTIVE_LOANS_TTL_MS });
+    }
+    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;
+    const cached = await (0, cache_1.getSafeCache)(key);
+    if (cached) {
+        loans = cached;
+    }
+    else {
+        const tokenizedVaultsResponse = await fetchUpshiftPublic(core_2.WEBSERVER_ENDPOINTS.public.tokenizedVault.subaccountLoans(pool, chainId, true), { headers: headers });
+        loans = (await tokenizedVaultsResponse.json()).loans;
+        // Short TTL: see fetchTokenizedVaultLoans / ACTIVE_LOANS_TTL_MS.
+        if (loans)
+            cache_1.CACHE.set(key, loans, { ttl: ACTIVE_LOANS_TTL_MS });
+    }
+    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);
+    if (cachedResponse) {
+        return cachedResponse;
+    }
+    const response = await fetchUpshiftPublic(core_2.WEBSERVER_ENDPOINTS.public.tokenizedVault.historicalTimeseries(vaultAddress, nDays), { headers: headers });
+    if (!response.ok) {
+        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 for 10 minutes
+    return json;
+}
+/**
+ * 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()]);
+ * ```
+ */
+async function promiseSettle(tasks, maxRetries = 3, baseDelay = 1000) {
+    const settling = tasks.map((task, index) => {
+        if (typeof task !== 'function') {
+            // Already-created promise: nothing to re-run, so settle it as-is.
+            return task;
+        }
+        return withRetry(async () => {
+            try {
+                return await task();
+            }
+            catch (error) {
+                logger_1.Logger.log.warn('promiseSettle', `Task at index ${index} failed`, error);
+                throw error;
+            }
+        }, maxRetries, baseDelay);
+    });
+    const results = await Promise.allSettled(settling);
+    return results.map((result, index) => {
+        if (result.status === 'fulfilled') {
+            return result.value;
+        }
+        else {
+            logger_1.Logger.log.warn('promiseSettle', `Promise at index ${index} failed after retries`, result.reason);
+            return null;
+        }
+    });
+}
+//# sourceMappingURL=fetcher.js.map