upshift-config 0.5.14

package/lib/core/errors/index.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Error class hierarchy for the SDK. All subclasses extend `AugustSDKError`,
+ * which extends the native `Error`.
+ *
+ * ```ts
+ * import { AugustAuthError, AugustTimeoutError } from '@augustdigital/sdk';
+ *
+ * try {
+ *   await sdk.getVault(...);
+ * } catch (err) {
+ *   if (err instanceof AugustAuthError) refreshKey();
+ *   else if (err instanceof AugustTimeoutError) retry();
+ *   else throw err;
+ * }
+ * ```
+ */
+/** Stable error codes attached to SDK errors. */
+export type AugustErrorCode = 'AUTH_MISSING_KEY' | 'AUTH_INVALID_KEY' | 'AUTH_FORBIDDEN' | 'AUTH_UNAUTHORIZED' | 'INVALID_URL' | 'INVALID_INPUT' | 'INVALID_CHAIN' | 'INVALID_ADDRESS' | 'ACCOUNT_NOT_FUNDED' | 'NETWORK_ERROR' | 'TIMEOUT' | 'RATE_LIMITED' | 'SERVER_ERROR' | 'HISTORY_UNAVAILABLE' | 'UNKNOWN';
+/** Options accepted by every SDK error constructor. */
+export interface AugustErrorOptions {
+    /** Original error preserved for stack-trace chaining. */
+    cause?: unknown;
+    /** Set from the response `x-correlation-id` header when available. */
+    correlationId?: string;
+    /** Structured context attached to the error for logging. */
+    context?: Record<string, unknown>;
+}
+/** Base class for all SDK errors. */
+export declare class AugustSDKError extends Error {
+    readonly code: AugustErrorCode;
+    readonly correlationId?: string;
+    readonly context?: Record<string, unknown>;
+    constructor(code: AugustErrorCode, message: string, options?: AugustErrorOptions);
+    /**
+     * Serialize own properties to a plain object. Native `Error` enumerates
+     * nothing, so `JSON.stringify(err)` returns `"{}"` without this.
+     */
+    toJSON(): Record<string, unknown>;
+}
+/** Authentication/authorization failure: missing key, invalid key, forbidden. */
+export declare class AugustAuthError extends AugustSDKError {
+    constructor(code: Extract<AugustErrorCode, 'AUTH_MISSING_KEY' | 'AUTH_INVALID_KEY' | 'AUTH_FORBIDDEN' | 'AUTH_UNAUTHORIZED'>, message: string, options?: AugustErrorOptions);
+}
+/** Network-level failure: connection refused, DNS, fetch failed. */
+export declare class AugustNetworkError extends AugustSDKError {
+    constructor(message: string, options?: AugustErrorOptions);
+}
+/** Request exceeded its deadline. */
+export declare class AugustTimeoutError extends AugustSDKError {
+    /** Time elapsed (ms) before the request was aborted. */
+    readonly timeoutMs: number;
+    constructor(message: string, timeoutMs: number, options?: AugustErrorOptions);
+    toJSON(): Record<string, unknown>;
+}
+/** Caller-side input failed validation. */
+export declare class AugustValidationError extends AugustSDKError {
+    constructor(code: Extract<AugustErrorCode, 'INVALID_URL' | 'INVALID_INPUT' | 'INVALID_CHAIN' | 'INVALID_ADDRESS' | 'ACCOUNT_NOT_FUNDED'>, message: string, options?: AugustErrorOptions);
+}
+/** Backend rate-limited the request (HTTP 429 or equivalent). */
+export declare class AugustRateLimitError extends AugustSDKError {
+    /** Suggested wait before retrying, in milliseconds. */
+    readonly retryAfterMs?: number;
+    constructor(message: string, options?: AugustErrorOptions & {
+        retryAfterMs?: number;
+    });
+    toJSON(): Record<string, unknown>;
+}
+/** Backend returned a non-OK status that isn't auth, rate-limit, or timeout. */
+export declare class AugustServerError extends AugustSDKError {
+    /** HTTP status code returned by the backend. */
+    readonly status: number;
+    constructor(status: number, message: string, options?: AugustErrorOptions);
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Transaction/position history required to compute a value could not be
+ * retrieved or was empty, so the computed result would be wrong rather than
+ * merely missing.
+ *
+ * Motivation — the 2026-07-09 lifetime-PnL over-inflation incident. Lifetime
+ * PnL is `currentPosition + totalWithdrawn - totalDeposited`. Every
+ * history-fetch failure (deleted subgraph, subgraph deployed against the wrong
+ * ABI, missing archive backfill, deposits indexed on a different
+ * chain/contract) collapses the deposit/withdrawal history to empty. With
+ * `deposited = 0` and `withdrawn = 0` but a live on-chain `position > 0`, the
+ * formula degenerates to reporting the entire position as profit. Throwing this
+ * typed error makes that unrecoverable state fail loudly instead of returning
+ * an inflated number that looks plausible.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await sdk.vaults.getVaultUserLifetimePnl({ vault, wallet, options });
+ * } catch (err) {
+ *   if (err instanceof AugustHistoryUnavailableError) {
+ *     // History backfill is broken — surface "temporarily unavailable",
+ *     // never a fabricated PnL number.
+ *     showUnavailable(err.context);
+ *   } else throw err;
+ * }
+ * ```
+ */
+export declare class AugustHistoryUnavailableError extends AugustSDKError {
+    /**
+     * @param message - Human-readable description of the missing history. Callers
+     *   pass the same `#<method>::<vault>::<wallet>` prefix the surrounding getter
+     *   uses so log grouping stays consistent.
+     * @param options - Standard SDK error options. `context` should carry the
+     *   `{ vault, wallet }` (or equivalent) identifiers that scope the failure.
+     */
+    constructor(message: string, options?: AugustErrorOptions);
+}
+/** Type guard. Works across realms (e.g. Web Worker / VM contexts). */
+export declare function isAugustSDKError(err: unknown): err is AugustSDKError;

package/lib/core/errors/index.js

@@ -0,0 +1,183 @@
+"use strict";
+/**
+ * Error class hierarchy for the SDK. All subclasses extend `AugustSDKError`,
+ * which extends the native `Error`.
+ *
+ * ```ts
+ * import { AugustAuthError, AugustTimeoutError } from '@augustdigital/sdk';
+ *
+ * try {
+ *   await sdk.getVault(...);
+ * } catch (err) {
+ *   if (err instanceof AugustAuthError) refreshKey();
+ *   else if (err instanceof AugustTimeoutError) retry();
+ *   else throw err;
+ * }
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AugustHistoryUnavailableError = exports.AugustServerError = exports.AugustRateLimitError = exports.AugustValidationError = exports.AugustTimeoutError = exports.AugustNetworkError = exports.AugustAuthError = exports.AugustSDKError = void 0;
+exports.isAugustSDKError = isAugustSDKError;
+/** Base class for all SDK errors. */
+class AugustSDKError extends Error {
+    code;
+    correlationId;
+    context;
+    constructor(code, message, options = {}) {
+        super(message);
+        this.name = 'AugustSDKError';
+        this.code = code;
+        this.correlationId = options.correlationId;
+        this.context = options.context;
+        if (options.cause !== undefined) {
+            this.cause = options.cause;
+        }
+        // Restore prototype chain for transpilation targets that downlevel `extends Error`.
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+    /**
+     * Serialize own properties to a plain object. Native `Error` enumerates
+     * nothing, so `JSON.stringify(err)` returns `"{}"` without this.
+     */
+    toJSON() {
+        const out = {
+            name: this.name,
+            message: this.message,
+            code: this.code,
+        };
+        if (this.correlationId !== undefined)
+            out.correlationId = this.correlationId;
+        if (this.context !== undefined)
+            out.context = this.context;
+        if (this.stack !== undefined)
+            out.stack = this.stack;
+        const cause = this.cause;
+        if (cause !== undefined) {
+            out.cause =
+                cause instanceof Error
+                    ? { name: cause.name, message: cause.message }
+                    : cause;
+        }
+        return out;
+    }
+}
+exports.AugustSDKError = AugustSDKError;
+/** Authentication/authorization failure: missing key, invalid key, forbidden. */
+class AugustAuthError extends AugustSDKError {
+    constructor(code, message, options) {
+        super(code, message, options);
+        this.name = 'AugustAuthError';
+    }
+}
+exports.AugustAuthError = AugustAuthError;
+/** Network-level failure: connection refused, DNS, fetch failed. */
+class AugustNetworkError extends AugustSDKError {
+    constructor(message, options) {
+        super('NETWORK_ERROR', message, options);
+        this.name = 'AugustNetworkError';
+    }
+}
+exports.AugustNetworkError = AugustNetworkError;
+/** Request exceeded its deadline. */
+class AugustTimeoutError extends AugustSDKError {
+    /** Time elapsed (ms) before the request was aborted. */
+    timeoutMs;
+    constructor(message, timeoutMs, options) {
+        super('TIMEOUT', message, options);
+        this.name = 'AugustTimeoutError';
+        this.timeoutMs = timeoutMs;
+    }
+    toJSON() {
+        return { ...super.toJSON(), timeoutMs: this.timeoutMs };
+    }
+}
+exports.AugustTimeoutError = AugustTimeoutError;
+/** Caller-side input failed validation. */
+class AugustValidationError extends AugustSDKError {
+    constructor(code, message, options) {
+        super(code, message, options);
+        this.name = 'AugustValidationError';
+    }
+}
+exports.AugustValidationError = AugustValidationError;
+/** Backend rate-limited the request (HTTP 429 or equivalent). */
+class AugustRateLimitError extends AugustSDKError {
+    /** Suggested wait before retrying, in milliseconds. */
+    retryAfterMs;
+    constructor(message, options) {
+        super('RATE_LIMITED', message, options);
+        this.name = 'AugustRateLimitError';
+        this.retryAfterMs = options?.retryAfterMs;
+    }
+    toJSON() {
+        const base = super.toJSON();
+        if (this.retryAfterMs !== undefined)
+            base.retryAfterMs = this.retryAfterMs;
+        return base;
+    }
+}
+exports.AugustRateLimitError = AugustRateLimitError;
+/** Backend returned a non-OK status that isn't auth, rate-limit, or timeout. */
+class AugustServerError extends AugustSDKError {
+    /** HTTP status code returned by the backend. */
+    status;
+    constructor(status, message, options) {
+        super('SERVER_ERROR', message, options);
+        this.name = 'AugustServerError';
+        this.status = status;
+    }
+    toJSON() {
+        return { ...super.toJSON(), status: this.status };
+    }
+}
+exports.AugustServerError = AugustServerError;
+/**
+ * Transaction/position history required to compute a value could not be
+ * retrieved or was empty, so the computed result would be wrong rather than
+ * merely missing.
+ *
+ * Motivation — the 2026-07-09 lifetime-PnL over-inflation incident. Lifetime
+ * PnL is `currentPosition + totalWithdrawn - totalDeposited`. Every
+ * history-fetch failure (deleted subgraph, subgraph deployed against the wrong
+ * ABI, missing archive backfill, deposits indexed on a different
+ * chain/contract) collapses the deposit/withdrawal history to empty. With
+ * `deposited = 0` and `withdrawn = 0` but a live on-chain `position > 0`, the
+ * formula degenerates to reporting the entire position as profit. Throwing this
+ * typed error makes that unrecoverable state fail loudly instead of returning
+ * an inflated number that looks plausible.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await sdk.vaults.getVaultUserLifetimePnl({ vault, wallet, options });
+ * } catch (err) {
+ *   if (err instanceof AugustHistoryUnavailableError) {
+ *     // History backfill is broken — surface "temporarily unavailable",
+ *     // never a fabricated PnL number.
+ *     showUnavailable(err.context);
+ *   } else throw err;
+ * }
+ * ```
+ */
+class AugustHistoryUnavailableError extends AugustSDKError {
+    /**
+     * @param message - Human-readable description of the missing history. Callers
+     *   pass the same `#<method>::<vault>::<wallet>` prefix the surrounding getter
+     *   uses so log grouping stays consistent.
+     * @param options - Standard SDK error options. `context` should carry the
+     *   `{ vault, wallet }` (or equivalent) identifiers that scope the failure.
+     */
+    constructor(message, options) {
+        super('HISTORY_UNAVAILABLE', message, options);
+        this.name = 'AugustHistoryUnavailableError';
+    }
+}
+exports.AugustHistoryUnavailableError = AugustHistoryUnavailableError;
+/** Type guard. Works across realms (e.g. Web Worker / VM contexts). */
+function isAugustSDKError(err) {
+    return (err instanceof AugustSDKError ||
+        (err instanceof Error &&
+            typeof err.code === 'string' &&
+            err.name.startsWith('August')));
+}
+//# sourceMappingURL=index.js.map

package/lib/core/fetcher.d.ts

@@ -0,0 +1,198 @@
+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?: 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;
+/**
+ * Override the base URL used for `WEBSERVER_URL.public` requests — the
+ * unauthenticated vault-catalog API that `getVault` / `fetchTokenizedVault`
+ * (and the other `fetchAugustPublic` 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
+ * `IAugustBase.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 `AugustSDK` 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 authenticated requests to August backend services using API key.
+ * Automatically logs errors with correlation IDs for debugging.
+ * @param apiKey - August API key for authentication
+ * @param relativeUrl - Endpoint path relative to base URL
+ * @param options - Request configuration including method and headers
+ * @returns Response object if successful
+ * @throws Error with correlation ID if request fails
+ */
+export declare function fetchAugustWithKey(apiKey: string, relativeUrl: string, options?: IFetchAugustOptions): Promise<Response>;
+/**
+ * Make unauthenticated requests to August public API endpoints.
+ * Used for fetching vault metadata and public market data.
+ * @param relativeUrl - Endpoint path relative to public API base URL
+ * @param options - Request configuration including method and headers
+ * @returns Response object if successful
+ * @throws Error with correlation ID if request fails
+ */
+export declare function fetchAugustPublic(relativeUrl: string, options?: IFetchAugustOptions): Promise<Response>;
+/**
+ * Make authenticated requests using Bearer token authentication.
+ * Typically used for user-specific operations requiring OAuth tokens.
+ * @param bearerToken - OAuth bearer token
+ * @param relativeUrl - Endpoint path relative to base URL
+ * @param options - Request configuration including method and headers
+ * @returns Response object if successful
+ * @throws Error with correlation ID if request fails
+ */
+export declare function fetchAugustWithBearer(bearerToken: string, relativeUrl: string, options?: IFetchAugustOptions): Promise<Response>;
+/**
+ * Check if an error is network-related and suitable for retry.
+ * Identifies timeouts, connection resets, and fetch failures.
+ */
+export declare function isRetryableError(error: Error): boolean;
+/**
+ * Wrap async operations with exponential backoff retry logic.
+ * Retries on network errors with increasing delays between attempts.
+ * @param fn - Async function to execute with retry logic
+ * @param maxRetries - Maximum number of retry attempts
+ * @param baseDelay - Initial delay in milliseconds (doubles each retry)
+ * @param shouldRetry - Custom function to determine if error is retryable
+ * @returns Result of successful function execution
+ * @throws Last error if all retries exhausted
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, maxRetries?: number, baseDelay?: number, shouldRetry?: (error: Error) => boolean): Promise<T>;
+/**
+ * Fetch tokenized vault configurations from backend API.
+ * Results are cached to reduce API calls. Optionally filter by specific vault address.
+ * @param pool - Optional vault address to filter results
+ * @param headers - Monitoring headers for request tracking
+ * @returns Array of tokenized vault configurations
+ */
+export declare function fetchTokenizedVault(pool: VaultAddress, headers?: IWSMonitorHeaders, loadSubaccounts?: boolean, loadSnapshots?: boolean): Promise<ITokenizedVault[]>;
+/**
+ * Fetch tokenized vault configurations from backend API.
+ * Results are cached to reduce API calls. Optionally filter by specific vault address.
+ * @param pool - Optional vault address to filter results
+ * @param headers - Monitoring headers for request tracking
+ * @param loadSubaccounts - Optional flag to load subaccounts and EOA operators (defaults to true on API)
+ * @returns Array of tokenized vault configurations
+ */
+export declare function fetchTokenizedVaults(pool?: IAddress, headers?: IWSMonitorHeaders, loadSubaccounts?: boolean, loadSnapshots?: boolean): Promise<ITokenizedVault[]>;
+/**
+ * Fetch current USD price for a token symbol or vault LP token.
+ * For vault LP tokens, calculates share price using totalAssets/totalSupply ratio.
+ * Falls back to CoinGecko if primary source fails.
+ * @param symbol - Token symbol or contract address
+ * @param provider - Optional web3 provider for on-chain price calculations
+ * @param coinGeckoKey - Optional CoinGecko API key for fallback pricing
+ * @param headers - Monitoring headers for request tracking
+ * @returns Token price in USD
+ */
+export declare function fetchTokenPrice(symbol: string, provider?: IContractRunner, coinGeckoKey?: string, headers?: IWSMonitorHeaders): Promise<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[]>;