@upshiftfinance/sdk 0.0.0-stage → 0.1.0

package/lib/core/helpers/chain-support.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Chain-ID validation for public SDK entry points.
+ *
+ * Two distinct failure modes are covered here, and they are deliberately kept
+ * separate because they have different remediations:
+ *
+ * 1. **Unknown chain ID** — the caller passed an ID the SDK has no concept of
+ *    (a typo, a stale constant, an off-by-one on a non-EVM synthetic ID). No
+ *    configuration can make this work; the call site is wrong.
+ * 2. **Known EVM chain, no RPC configured** — the ID is valid but the SDK was
+ *    constructed without a provider for it. Remediated by passing an RPC URL.
+ *
+ * Both used to be logged-and-ignored, letting execution continue with an
+ * `undefined` RPC URL. That produced a cascade of misleading downstream
+ * failures (`connect ECONNREFUSED 127.0.0.1:8545` from ethers' localhost
+ * default, `missing revert data` from `decimals()` reads issued against the
+ * wrong chain, and `TypeError: Cannot read properties of undefined`). Failing
+ * fast at the boundary replaces that cascade with one actionable error.
+ *
+ * @module core/helpers/chain-support
+ */
+/**
+ * Whether `chainId` is an EVM chain the SDK knows about (i.e. has an entry in
+ * {@link NETWORKS}).
+ *
+ * @param chainId - Numeric chain ID to test.
+ * @returns `true` for supported EVM chains, `false` for non-EVM synthetic IDs
+ *   (Solana, Stellar, Sui) and for anything unrecognised.
+ */
+export declare function isEvmChainId(chainId: number): boolean;
+/**
+ * Whether `chainId` is recognised by the SDK at all — either a supported EVM
+ * chain or one of the non-EVM chain IDs in {@link NON_EVM_CHAIN_IDS}.
+ *
+ * @param chainId - Numeric chain ID to test.
+ * @returns `true` when the ID maps to a chain the SDK can route to.
+ */
+export declare function isKnownChainId(chainId: number): boolean;
+/**
+ * Throw when `chainId` is not a chain the SDK recognises.
+ *
+ * Called at public vault entry points so an unroutable ID surfaces as one
+ * typed error instead of an opaque downstream RPC failure.
+ *
+ * @param chainId - Chain ID supplied by the caller. `undefined` is a no-op —
+ *   omitting the chain is valid and falls back to the SDK's active network.
+ * @param providers - The SDK's configured `chainId → RPC URL` map. A chain
+ *   with a caller-configured provider is routable even if it is missing from
+ *   {@link NETWORKS} (the SDK ships fallback RPCs/oracles for some EVM chains
+ *   ahead of adding them to `NETWORKS`), so it is accepted here too.
+ * @param method - Public method name, used to make the message actionable.
+ * @throws {@link UpshiftValidationError} with code `INVALID_CHAIN` when the ID
+ *   is not in {@link NETWORKS} or {@link NON_EVM_CHAIN_IDS}, and has no
+ *   caller-configured provider.
+ * @example
+ * ```ts
+ * assertKnownChainId(-4, undefined, 'getVault');
+ * // UpshiftValidationError: getVault: unknown chainId -4.
+ * ```
+ */
+export declare function assertKnownChainId(chainId: number | undefined, providers: Partial<Record<number, string>> | undefined, method: string): void;
+/**
+ * Throw when a known EVM `chainId` has no RPC URL configured on the SDK.
+ *
+ * Non-EVM chain IDs are exempt: Solana, Stellar and Sui vaults route through
+ * their adapters and never read from the `providers` map, so a missing entry
+ * is expected rather than a misconfiguration.
+ *
+ * @param chainId - Chain ID supplied by the caller. `undefined` is a no-op.
+ * @param providers - The SDK's configured `chainId → RPC URL` map.
+ * @param method - Public method name, used to make the message actionable.
+ * @throws {@link UpshiftValidationError} with code `INVALID_CHAIN` when
+ *   `chainId` is an EVM chain with no configured provider.
+ * @example
+ * ```ts
+ * assertEvmProviderConfigured(143, {}, 'getVault');
+ * // UpshiftValidationError: getVault: no RPC URL configured for chainId 143 (Monad).
+ * ```
+ */
+export declare function assertEvmProviderConfigured(chainId: number | undefined, providers: Partial<Record<number, string>> | undefined, method: string): void;
+/**
+ * Throw when a vault read targets Sui, whose vault reads this SDK does not
+ * implement yet: either `chainId` is Sui's (`-2`) or `vault` is a Sui object ID
+ * (`0x` + 64 hex chars), with or without a `chainId`.
+ *
+ * Call it before any EVM address check. Sui (`-2`) is a known chain, so it
+ * passes {@link assertKnownChainId}, and a Sui object ID is not an EVM address;
+ * without this guard a Sui read fails later with a misleading "no RPC URL" or
+ * "not an address" error.
+ *
+ * @internal
+ * @param chainId - Chain ID supplied by the caller; may be `undefined`.
+ * @param vault - Vault address supplied by the caller.
+ * @param method - Public method name, used to make the message actionable.
+ * @throws {@link UpshiftValidationError} with code `INVALID_CHAIN` for a Sui
+ *   chain ID or a Sui vault address.
+ */
+export declare function assertSuiReadsSupported(chainId: number | undefined, vault: string | undefined, method: string): void;

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

@@ -0,0 +1,139 @@
+"use strict";
+/**
+ * Chain-ID validation for public SDK entry points.
+ *
+ * Two distinct failure modes are covered here, and they are deliberately kept
+ * separate because they have different remediations:
+ *
+ * 1. **Unknown chain ID** — the caller passed an ID the SDK has no concept of
+ *    (a typo, a stale constant, an off-by-one on a non-EVM synthetic ID). No
+ *    configuration can make this work; the call site is wrong.
+ * 2. **Known EVM chain, no RPC configured** — the ID is valid but the SDK was
+ *    constructed without a provider for it. Remediated by passing an RPC URL.
+ *
+ * Both used to be logged-and-ignored, letting execution continue with an
+ * `undefined` RPC URL. That produced a cascade of misleading downstream
+ * failures (`connect ECONNREFUSED 127.0.0.1:8545` from ethers' localhost
+ * default, `missing revert data` from `decimals()` reads issued against the
+ * wrong chain, and `TypeError: Cannot read properties of undefined`). Failing
+ * fast at the boundary replaces that cascade with one actionable error.
+ *
+ * @module core/helpers/chain-support
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isEvmChainId = isEvmChainId;
+exports.isKnownChainId = isKnownChainId;
+exports.assertKnownChainId = assertKnownChainId;
+exports.assertEvmProviderConfigured = assertEvmProviderConfigured;
+exports.assertSuiReadsSupported = assertSuiReadsSupported;
+const web3_1 = require("../constants/web3");
+const chain_address_1 = require("./chain-address");
+const errors_1 = require("../errors");
+/**
+ * Whether `chainId` is an EVM chain the SDK knows about (i.e. has an entry in
+ * {@link NETWORKS}).
+ *
+ * @param chainId - Numeric chain ID to test.
+ * @returns `true` for supported EVM chains, `false` for non-EVM synthetic IDs
+ *   (Solana, Stellar, Sui) and for anything unrecognised.
+ */
+function isEvmChainId(chainId) {
+    return Object.hasOwn(web3_1.NETWORKS, chainId);
+}
+/**
+ * Whether `chainId` is recognised by the SDK at all — either a supported EVM
+ * chain or one of the non-EVM chain IDs in {@link NON_EVM_CHAIN_IDS}.
+ *
+ * @param chainId - Numeric chain ID to test.
+ * @returns `true` when the ID maps to a chain the SDK can route to.
+ */
+function isKnownChainId(chainId) {
+    return isEvmChainId(chainId) || web3_1.NON_EVM_CHAIN_IDS.has(chainId);
+}
+/**
+ * Throw when `chainId` is not a chain the SDK recognises.
+ *
+ * Called at public vault entry points so an unroutable ID surfaces as one
+ * typed error instead of an opaque downstream RPC failure.
+ *
+ * @param chainId - Chain ID supplied by the caller. `undefined` is a no-op —
+ *   omitting the chain is valid and falls back to the SDK's active network.
+ * @param providers - The SDK's configured `chainId → RPC URL` map. A chain
+ *   with a caller-configured provider is routable even if it is missing from
+ *   {@link NETWORKS} (the SDK ships fallback RPCs/oracles for some EVM chains
+ *   ahead of adding them to `NETWORKS`), so it is accepted here too.
+ * @param method - Public method name, used to make the message actionable.
+ * @throws {@link UpshiftValidationError} with code `INVALID_CHAIN` when the ID
+ *   is not in {@link NETWORKS} or {@link NON_EVM_CHAIN_IDS}, and has no
+ *   caller-configured provider.
+ * @example
+ * ```ts
+ * assertKnownChainId(-4, undefined, 'getVault');
+ * // UpshiftValidationError: getVault: unknown chainId -4.
+ * ```
+ */
+function assertKnownChainId(chainId, providers, method) {
+    if (typeof chainId === 'undefined')
+        return;
+    if (isKnownChainId(chainId))
+        return;
+    if (providers?.[chainId])
+        return;
+    throw new errors_1.UpshiftValidationError('INVALID_CHAIN', `${method}: unknown chainId ${chainId}. ` +
+        'Pass a supported EVM chain ID (see NETWORKS) or a non-EVM chain ID ' +
+        '(-1 Solana, -2 Sui, -3 Stellar).', { context: { method, chainId } });
+}
+/**
+ * Throw when a known EVM `chainId` has no RPC URL configured on the SDK.
+ *
+ * Non-EVM chain IDs are exempt: Solana, Stellar and Sui vaults route through
+ * their adapters and never read from the `providers` map, so a missing entry
+ * is expected rather than a misconfiguration.
+ *
+ * @param chainId - Chain ID supplied by the caller. `undefined` is a no-op.
+ * @param providers - The SDK's configured `chainId → RPC URL` map.
+ * @param method - Public method name, used to make the message actionable.
+ * @throws {@link UpshiftValidationError} with code `INVALID_CHAIN` when
+ *   `chainId` is an EVM chain with no configured provider.
+ * @example
+ * ```ts
+ * assertEvmProviderConfigured(143, {}, 'getVault');
+ * // UpshiftValidationError: getVault: no RPC URL configured for chainId 143 (Monad).
+ * ```
+ */
+function assertEvmProviderConfigured(chainId, providers, method) {
+    if (typeof chainId === 'undefined')
+        return;
+    if (!isEvmChainId(chainId))
+        return;
+    if (providers?.[chainId])
+        return;
+    const name = web3_1.NETWORKS[chainId]?.name;
+    throw new errors_1.UpshiftValidationError('INVALID_CHAIN', `${method}: no RPC URL configured for chainId ${chainId}` +
+        `${name ? ` (${name})` : ''}. ` +
+        'Pass one when constructing UpshiftSDK: ' +
+        `new UpshiftSDK({ providers: { ${chainId}: '<rpc-url>' } }).`, { context: { method, chainId } });
+}
+/**
+ * Throw when a vault read targets Sui, whose vault reads this SDK does not
+ * implement yet: either `chainId` is Sui's (`-2`) or `vault` is a Sui object ID
+ * (`0x` + 64 hex chars), with or without a `chainId`.
+ *
+ * Call it before any EVM address check. Sui (`-2`) is a known chain, so it
+ * passes {@link assertKnownChainId}, and a Sui object ID is not an EVM address;
+ * without this guard a Sui read fails later with a misleading "no RPC URL" or
+ * "not an address" error.
+ *
+ * @internal
+ * @param chainId - Chain ID supplied by the caller; may be `undefined`.
+ * @param vault - Vault address supplied by the caller.
+ * @param method - Public method name, used to make the message actionable.
+ * @throws {@link UpshiftValidationError} with code `INVALID_CHAIN` for a Sui
+ *   chain ID or a Sui vault address.
+ */
+function assertSuiReadsSupported(chainId, vault, method) {
+    if (chainId !== web3_1.SUI_CHAIN_ID && !(vault && (0, chain_address_1.isSuiAddress)(vault)))
+        return;
+    throw new errors_1.UpshiftValidationError('INVALID_CHAIN', `${method}: Sui vault reads are not supported yet (chainId ${web3_1.SUI_CHAIN_ID}).`, { context: { method, chainId } });
+}
+//# sourceMappingURL=chain-support.js.map

package/lib/core/helpers/concurrency.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Concurrency helpers.
+ *
+ * Internal only — deliberately not re-exported from `core/index.ts`, so it is
+ * not part of the published API surface.
+ *
+ * Leaf module: depends on nothing inside the SDK, so it is safe to import from
+ * any layer without forming a cycle (see CLAUDE.md §9).
+ */
+/**
+ * Map over `items` running at most `limit` tasks at a time.
+ *
+ * Exists because `Promise.all` over a caller-sized array is unbounded: a vault
+ * with 40 borrowers opens 40 simultaneous connections to the same backend,
+ * which is how a slow endpoint turns into a timeout storm rather than a slow
+ * response. A small fixed window keeps latency close to the parallel case while
+ * bounding the load the SDK can put on one origin.
+ *
+ * Results preserve input order regardless of completion order. A rejected task
+ * rejects the returned promise (like `Promise.all`); callers that need
+ * per-item error isolation should catch inside `task`.
+ *
+ * @param items - Inputs to process. An empty array resolves to `[]` immediately.
+ * @param limit - Maximum tasks in flight. Values below 1 are treated as 1.
+ * @param task - Receives an item and its index; returns the value for that slot.
+ * @returns Results in the same order as `items`.
+ * @throws Whatever `task` rejects with, on the first rejection.
+ * @example
+ * ```ts
+ * // At most 5 concurrent requests, regardless of borrower count.
+ * const positions = await mapWithConcurrency(borrowers, 5, (b) =>
+ *   fetchPosition(b).catch(() => null),
+ * );
+ * ```
+ * @internal
+ */
+export declare function mapWithConcurrency<TIn, TOut>(items: readonly TIn[], limit: number, task: (item: TIn, index: number) => Promise<TOut>): Promise<TOut[]>;
+/**
+ * Race a promise against a timeout so a hung call can't block indefinitely. The
+ * timer is always cleared, so a fast-resolving promise leaves nothing pending.
+ *
+ * @param promise - The call to bound. It keeps running after a timeout; only
+ *   the wait is abandoned.
+ * @param ms - Timeout in milliseconds. Values below 0 are treated as 0.
+ * @param label - Names the call in the rejection message.
+ * @returns What `promise` resolves to.
+ * @throws `Error("<label> timed out after <ms>ms")` on timeout, or whatever
+ *   `promise` rejects with.
+ * @internal
+ */
+export declare function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T>;

package/lib/core/helpers/concurrency.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * Concurrency helpers.
+ *
+ * Internal only — deliberately not re-exported from `core/index.ts`, so it is
+ * not part of the published API surface.
+ *
+ * Leaf module: depends on nothing inside the SDK, so it is safe to import from
+ * any layer without forming a cycle (see CLAUDE.md §9).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapWithConcurrency = mapWithConcurrency;
+exports.withTimeout = withTimeout;
+/**
+ * Map over `items` running at most `limit` tasks at a time.
+ *
+ * Exists because `Promise.all` over a caller-sized array is unbounded: a vault
+ * with 40 borrowers opens 40 simultaneous connections to the same backend,
+ * which is how a slow endpoint turns into a timeout storm rather than a slow
+ * response. A small fixed window keeps latency close to the parallel case while
+ * bounding the load the SDK can put on one origin.
+ *
+ * Results preserve input order regardless of completion order. A rejected task
+ * rejects the returned promise (like `Promise.all`); callers that need
+ * per-item error isolation should catch inside `task`.
+ *
+ * @param items - Inputs to process. An empty array resolves to `[]` immediately.
+ * @param limit - Maximum tasks in flight. Values below 1 are treated as 1.
+ * @param task - Receives an item and its index; returns the value for that slot.
+ * @returns Results in the same order as `items`.
+ * @throws Whatever `task` rejects with, on the first rejection.
+ * @example
+ * ```ts
+ * // At most 5 concurrent requests, regardless of borrower count.
+ * const positions = await mapWithConcurrency(borrowers, 5, (b) =>
+ *   fetchPosition(b).catch(() => null),
+ * );
+ * ```
+ * @internal
+ */
+async function mapWithConcurrency(items, limit, task) {
+    if (items.length === 0)
+        return [];
+    const width = Math.max(1, Math.min(Math.floor(limit), items.length));
+    const results = new Array(items.length);
+    // Shared cursor: each worker repeatedly claims the next unclaimed index, so
+    // a slow item never blocks the workers behind it (as a fixed chunked split
+    // would).
+    let cursor = 0;
+    const worker = async () => {
+        while (cursor < items.length) {
+            const index = cursor++;
+            results[index] = await task(items[index], index);
+        }
+    };
+    await Promise.all(Array.from({ length: width }, worker));
+    return results;
+}
+/**
+ * Race a promise against a timeout so a hung call can't block indefinitely. The
+ * timer is always cleared, so a fast-resolving promise leaves nothing pending.
+ *
+ * @param promise - The call to bound. It keeps running after a timeout; only
+ *   the wait is abandoned.
+ * @param ms - Timeout in milliseconds. Values below 0 are treated as 0.
+ * @param label - Names the call in the rejection message.
+ * @returns What `promise` resolves to.
+ * @throws `Error("<label> timed out after <ms>ms")` on timeout, or whatever
+ *   `promise` rejects with.
+ * @internal
+ */
+function withTimeout(promise, ms, label) {
+    let timer;
+    const timeout = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), Math.max(0, ms));
+    });
+    return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+//# sourceMappingURL=concurrency.js.map

package/lib/core/helpers/core.d.ts

@@ -0,0 +1,92 @@
+import type { INormalizedNumber } from '../../types';
+/**
+ * Table of Contents
+ * - Formatters
+ * - Datetime
+ * - Arrays
+ * - Caching
+ */
+/**
+ * Normalize an amount into both its human-readable and raw (integer) forms.
+ *
+ * @param value - Amount as a decimal string (`"1.5"`), a JS number, or a raw
+ *   `bigint` already scaled by `decimals`. Strings/numbers are treated as
+ *   human-readable values and scaled UP; bigints are treated as raw values
+ *   and scaled DOWN. Exponential notation (`1e-7`, `1e21`) is accepted for
+ *   strings and numbers.
+ * @param decimals - Token decimals used for scaling. Default `18`.
+ * @returns `{ normalized, raw }` where `normalized` is the decimal string
+ *   (fraction trimmed to `decimals` places) and `raw` is the integer string.
+ *   Falsy input yields `{ normalized: '0', raw: '0' }`.
+ * @throws Whatever ethers' `parseUnits` throws for a string that is not a
+ *   decimal number (e.g. `"abc"`).
+ */
+export declare function toNormalizedBn(value: string | bigint | number, decimals?: number | bigint): INormalizedNumber;
+/**
+ * Get fallback RPC URLs for a specific chain
+ */
+export declare function getFallbackRpcUrls(chainId: number): string[];
+export declare const filterOutBySize: (usdAmount: number) => boolean;
+/**
+ * Formatters
+ */
+export declare function toTitleCase(str: string, type?: 'camel'): string;
+export declare function truncate(s: string, amount?: number): string;
+/**
+ * Formats any numeric value (number, string, or bigint) to a standardized string.
+ *
+ * @param value - amount to be formatted
+ * @param options - formatting options:
+ *   `showing` is the number of decimals to cut off at (or `'all'`);
+ *   `usd` toggles USD-value display;
+ *   `decimals` is how many decimals to parse to when `value` is a bigint.
+ *
+ * @returns standardized string type value
+ */
+export declare function round(value: number | string | bigint, options?: {
+    showing?: number | 'all';
+    usd?: boolean;
+    decimals?: number;
+}): string;
+export declare function loanStateToReadable(loanState: number | bigint): "PREAPPROVED" | "FUNDING_REQUIRED" | "FUNDED" | "ACTIVE" | "CANCELLED" | "MATURED" | "CLOSED";
+/**
+ * Datetime
+ */
+export declare function dateToUnix(date: Date): number;
+export declare function unixToDate(epoch: number): Date;
+export declare function isEarlierThanNow(startTime: Date): boolean;
+export declare function daysAgo(days: number): Date;
+export declare function prepareDateForDb(date: string | Date): string;
+/**
+ * Arrays
+ */
+export declare function orderObjArrByDate<T extends Record<string, unknown>>(objectArray: T[], options?: {
+    key?: string;
+    order?: 'asc' | 'desc';
+}): T[];
+/**
+ * Calculate weights based on a specific property in array of objects.
+ * @param data - Array of objects to calculate weights for
+ * @param weightProperty - Property name to base weights on
+ * @returns Original data with each item's `weight` added
+ */
+export declare function calculateWeights<T extends Record<string, unknown>>(data?: T[], weightProperty?: string): Array<T & {
+    weight: number;
+}>;
+/**
+ * Calculate weighted average for array of objects.
+ * @param data - Array of objects with values
+ * @param valueProperty - Property name containing the value to average
+ * @param weightProperty - Optional property to base weights on
+ * @returns Weighted average
+ */
+export declare function calculateWeightedAverage<T extends Record<string, unknown>>(data?: T[], valueProperty?: string, weightProperty?: string): number;
+/**
+ * Coerce a caller-supplied integer (`string | bigint | number`) to a `bigint`,
+ * rejecting anything that is not a non-negative safe integer. `label` names the
+ * calling method and `noun` the field being validated, so bad input surfaces as
+ * `UpshiftValidationError('INVALID_INPUT')` at the SDK boundary instead of a
+ * `BigInt()` SyntaxError wrapped as `UNKNOWN`.
+ * @internal
+ */
+export declare function toRawBigInt(value: string | bigint | number, label: string, noun?: string): bigint;