@omnitron-dev/prism 0.2.0 → 0.3.1

package/dist/utils/fetch-interceptor.d.ts

@@ -0,0 +1,230 @@
+/**
+ * Fetch Interceptor Factory
+ *
+ * A flexible fetch wrapper with support for request/response interceptors,
+ * automatic token refresh, and retry logic.
+ *
+ * Designed for production applications that need centralized HTTP handling.
+ *
+ * @module utils
+ */
+import { type AsyncLock } from './async-lock.js';
+import { type RetryConfig } from './errors.js';
+/**
+ * Extended request init with additional options.
+ */
+export interface FetchRequestInit extends RequestInit {
+    /** Skip all interceptors for this request */
+    skipInterceptors?: boolean;
+    /** Skip request interceptors only */
+    skipRequestInterceptors?: boolean;
+    /** Skip response interceptors only */
+    skipResponseInterceptors?: boolean;
+    /** Custom timeout in milliseconds */
+    timeout?: number;
+    /** Enable automatic retry on failure */
+    retry?: boolean | RetryConfig;
+    /** Request metadata for logging/debugging */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Request interceptor context.
+ */
+export interface RequestContext {
+    url: string;
+    init: FetchRequestInit;
+    /** Original request info (can be string or Request) */
+    input: RequestInfo | URL;
+    /** Request metadata */
+    metadata: Record<string, unknown>;
+}
+/**
+ * Response interceptor context.
+ */
+export interface ResponseContext {
+    response: Response;
+    request: RequestContext;
+    /** Time taken for the request in ms */
+    duration: number;
+}
+/**
+ * Error interceptor context.
+ */
+export interface ErrorContext {
+    error: unknown;
+    request: RequestContext;
+    /** Time taken before error in ms */
+    duration: number;
+    /** Number of retry attempts made */
+    retryCount: number;
+}
+/**
+ * Request interceptor function.
+ * Can modify the request or return a new one.
+ */
+export type RequestInterceptor = (ctx: RequestContext) => RequestContext | Promise<RequestContext>;
+/**
+ * Response interceptor function.
+ * Can modify the response or return a new one.
+ */
+export type ResponseInterceptor = (ctx: ResponseContext) => Response | Promise<Response>;
+/**
+ * Error interceptor function.
+ * Can handle the error, retry, or rethrow.
+ */
+export type ErrorInterceptor = (ctx: ErrorContext) => Response | Promise<Response> | never;
+/**
+ * Interceptor configuration.
+ */
+export interface FetchInterceptorConfig {
+    /** Base URL to prepend to relative paths */
+    baseUrl?: string;
+    /** Default headers for all requests */
+    defaultHeaders?: HeadersInit;
+    /** Default timeout in milliseconds (0 = no timeout) */
+    defaultTimeout?: number;
+    /** Request interceptors (run in order) */
+    requestInterceptors?: RequestInterceptor[];
+    /** Response interceptors (run in order) */
+    responseInterceptors?: ResponseInterceptor[];
+    /** Error interceptors (run in order, first to handle wins) */
+    errorInterceptors?: ErrorInterceptor[];
+    /** Default retry configuration */
+    defaultRetry?: RetryConfig | false;
+    /** Credentials mode for all requests */
+    credentials?: RequestCredentials;
+}
+/**
+ * Token refresh handler configuration.
+ */
+export interface TokenRefreshConfig {
+    /** Check if a response indicates token expiration */
+    isTokenExpired: (response: Response) => boolean;
+    /** Refresh the token (called when token is expired) */
+    refreshToken: () => Promise<string | null>;
+    /** Get the current access token */
+    getAccessToken: () => string | null;
+    /** Called when refresh fails (e.g., redirect to login) */
+    onRefreshFailure?: () => void;
+    /** Maximum number of refresh attempts */
+    maxRefreshAttempts?: number;
+}
+/**
+ * Fetch client interface.
+ */
+export interface FetchClient {
+    /** Make a fetch request */
+    fetch: (input: RequestInfo | URL, init?: FetchRequestInit) => Promise<Response>;
+    /** Add a request interceptor */
+    addRequestInterceptor: (interceptor: RequestInterceptor) => () => void;
+    /** Add a response interceptor */
+    addResponseInterceptor: (interceptor: ResponseInterceptor) => () => void;
+    /** Add an error interceptor */
+    addErrorInterceptor: (interceptor: ErrorInterceptor) => () => void;
+    /** Remove all interceptors */
+    clearInterceptors: () => void;
+    /** Get current configuration */
+    getConfig: () => FetchInterceptorConfig;
+}
+/**
+ * Create a fetch client with interceptor support.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * const api = createFetchClient({
+ *   baseUrl: 'https://api.example.com',
+ *   defaultHeaders: { 'Content-Type': 'application/json' },
+ *   defaultTimeout: 30000,
+ * });
+ *
+ * // Add auth header interceptor
+ * api.addRequestInterceptor(async (ctx) => {
+ *   const token = getAccessToken();
+ *   if (token) {
+ *     ctx.init.headers = {
+ *       ...ctx.init.headers,
+ *       Authorization: `Bearer ${token}`,
+ *     };
+ *   }
+ *   return ctx;
+ * });
+ *
+ * // Add response logging
+ * api.addResponseInterceptor(async (ctx) => {
+ *   console.log(`${ctx.request.init.method} ${ctx.request.url} - ${ctx.response.status} (${ctx.duration}ms)`);
+ *   return ctx.response;
+ * });
+ *
+ * // Make requests
+ * const response = await api.fetch('/users');
+ * const data = await response.json();
+ * ```
+ */
+export declare function createFetchClient(config?: FetchInterceptorConfig): FetchClient;
+/**
+ * Create a token refresh interceptor that automatically refreshes
+ * expired tokens and retries failed requests.
+ *
+ * Uses AsyncLock to prevent multiple simultaneous refresh attempts.
+ *
+ * @example
+ * ```tsx
+ * const api = createFetchClient({ baseUrl: '/api' });
+ *
+ * const { addToClient } = createTokenRefreshInterceptor({
+ *   isTokenExpired: (response) => response.status === 401,
+ *   refreshToken: async () => {
+ *     const response = await fetch('/auth/refresh', { method: 'POST' });
+ *     const data = await response.json();
+ *     localStorage.setItem('token', data.accessToken);
+ *     return data.accessToken;
+ *   },
+ *   getAccessToken: () => localStorage.getItem('token'),
+ *   onRefreshFailure: () => {
+ *     localStorage.removeItem('token');
+ *     window.location.href = '/login';
+ *   },
+ * });
+ *
+ * addToClient(api);
+ * ```
+ */
+export declare function createTokenRefreshInterceptor(config: TokenRefreshConfig): {
+    addToClient: (client: FetchClient) => void;
+    refreshLock: AsyncLock;
+};
+/**
+ * Create a simple JSON API client.
+ *
+ * @example
+ * ```tsx
+ * const api = createJsonApiClient({
+ *   baseUrl: 'https://api.example.com',
+ *   getAuthToken: () => localStorage.getItem('token'),
+ * });
+ *
+ * // GET request
+ * const users = await api.get<User[]>('/users');
+ *
+ * // POST request
+ * const newUser = await api.post<User>('/users', { name: 'John' });
+ *
+ * // DELETE request
+ * await api.delete('/users/1');
+ * ```
+ */
+export declare function createJsonApiClient(options: {
+    baseUrl?: string;
+    getAuthToken?: () => string | null;
+    defaultHeaders?: Record<string, string>;
+    timeout?: number;
+}): {
+    client: FetchClient;
+    get: <T>(path: string) => Promise<T | null>;
+    post: <T>(path: string, body?: unknown) => Promise<T | null>;
+    put: <T>(path: string, body?: unknown) => Promise<T | null>;
+    patch: <T>(path: string, body?: unknown) => Promise<T | null>;
+    delete: <T>(path: string) => Promise<T | null>;
+};
+//# sourceMappingURL=fetch-interceptor.d.ts.map

package/dist/utils/fetch-interceptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-interceptor.d.ts","sourceRoot":"","sources":["../../src/utils/fetch-interceptor.ts"],"names":[],"mappings":"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"}

package/dist/utils/font.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Font Utilities
+ *
+ * Font family and unit conversion helpers.
+ *
+ * @module utils
+ */
+/**
+ * Create a font family string with fallback stack.
+ *
+ * @param {string} [fontName] - Primary font name
+ * @returns {string} Font family with fallbacks
+ *
+ * @example
+ * ```ts
+ * setFont('Inter'); // '"Inter", -apple-system, ...'
+ * setFont();        // Default system font stack
+ * ```
+ */
+export declare function setFont(fontName?: string): string;
+/**
+ * Convert rem to pixels.
+ *
+ * @param {string | number} value - Rem value (number or string like '1rem')
+ * @returns {number} Value in pixels
+ *
+ * @example
+ * ```ts
+ * remToPx(1);      // 16
+ * remToPx('1rem'); // 16
+ * remToPx(1.5);    // 24
+ * ```
+ */
+export declare function remToPx(value: string | number): number;
+/**
+ * Convert pixels to rem.
+ *
+ * @param {string | number} value - Pixel value (number or string like '16px')
+ * @returns {string} Value in rem with unit
+ *
+ * @example
+ * ```ts
+ * pxToRem(16);      // '1rem'
+ * pxToRem('16px');  // '1rem'
+ * pxToRem(24);      // '1.5rem'
+ * ```
+ */
+export declare function pxToRem(value: string | number): string;
+/**
+ * Create responsive font size based on viewport.
+ *
+ * @param {number} minSize - Minimum font size in px
+ * @param {number} maxSize - Maximum font size in px
+ * @param {number} [minWidth=320] - Minimum viewport width in px
+ * @param {number} [maxWidth=1200] - Maximum viewport width in px
+ * @returns {string} CSS clamp() value
+ *
+ * @example
+ * ```ts
+ * responsiveFontSize(14, 18);
+ * // 'clamp(0.875rem, 0.7955rem + 0.3977vw, 1.125rem)'
+ * ```
+ */
+export declare function responsiveFontSize(minSize: number, maxSize: number, minWidth?: number, maxWidth?: number): string;
+//# sourceMappingURL=font.d.ts.map

package/dist/utils/font.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"font.d.ts","sourceRoot":"","sources":["../../src/utils/font.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH;;;;;;;;;;;GAWG;AACH,wBAAgB,OAAO,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAMjD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAGtD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAGtD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,SAAM,EAAE,QAAQ,SAAO,GAAG,MAAM,CAW5G"}

package/dist/utils/format-crypto.d.ts

@@ -0,0 +1,312 @@
+/**
+ * Canonical BTC / XMR amount formatter.
+ *
+ * Why this exists
+ * ---------------
+ * Pre-consolidation the platform had ~8 independent formatters,
+ * each shipping its own opinion of precision:
+ *
+ *   - `org-finances/formatBtc`     → BTC 8, XMR 4
+ *   - `org-revenue-card`           → BTC 4, XMR 4
+ *   - `orgs-overview/formatBtc`    → tiered 8 → 4 → 2 by magnitude
+ *   - `shop-dashboard`             → BTC 4
+ *   - `shop-categories`            → BTC 8 with trailing-zero trim
+ *   - `finances/hooks`             → BTC 8, XMR 8 (already canonical
+ *                                    but isolated from everyone else)
+ *   - `pages/finances DEFAULT_ASSETS` → XMR 12 (wire-precision leak)
+ *
+ * Result: a single dashboard showed BTC 4 in the KPI tile, BTC 8
+ * in the Financial Overview tile, and BTC 6 in another corner —
+ * three "truths" for the same value. This module is the single
+ * source of truth from now on; all call sites import from here.
+ *
+ * Display vs wire precision
+ * -------------------------
+ * Wire precision (what the backend stores) is 8 for BTC, 12 for
+ * XMR — those are the on-chain atomic units (satoshi, piconero).
+ * Display precision is 8 for BOTH coins by platform convention:
+ *
+ *   - 8 fractional digits is a satoshi-level read for BTC,
+ *   - 8 fractional digits for XMR is "good enough" for human eyes
+ *     and keeps the column widths symmetric. The last 4 digits of
+ *     XMR's wire value are dropped from display only — never from
+ *     storage, math, or wire transfers.
+ *
+ * The platform-wide symmetric formatting was a direct user-facing
+ * request: the same coin column should align cleanly whether the
+ * row holds BTC or XMR.
+ *
+ * Which way a dropped digit goes
+ * ------------------------------
+ * Those four dropped XMR digits are the reason this module has a
+ * rounding DIRECTION and not just a scale. Display rounding used
+ * to be half-up, so a balance of
+ *
+ *     1.586170199999 XMR   (what the account holds)
+ *
+ * rendered as `1.58617020 XMR` — a tenth of a piconero MORE than
+ * exists. A person who reads that number and types it back into a
+ * withdrawal is refused for insufficient funds, by a figure the
+ * platform itself put on their screen. The same arithmetic seeds
+ * the "max balance" shortcut, so the refusal arrives from a button
+ * whose entire purpose is to be correct.
+ *
+ * So the rule for anything rendered as money is: **the displayed
+ * magnitude is never larger than the real one.** Quantization for
+ * display truncates toward zero (`'down'`), at any precision, in
+ * either sign. That is not a matter of taste at eight decimals
+ * versus twelve — it holds whatever the scale, which is why it is
+ * a separate decision from the 8-vs-12 convention above.
+ *
+ * Half-up remains available and remains the default for the
+ * ARITHMETIC primitives (`toScaledInteger`, `sumDecimalStrings`,
+ * `subtractDecimalStrings`), where the scale is the value's own
+ * and the last digit is a genuine rounding rather than a
+ * truncation of digits that are really there. Arithmetic on money
+ * belongs at `getCoinWireDecimals(coin)`, not at display scale;
+ * quantize once, at the end, downward.
+ *
+ * The other direction is a lie too
+ * --------------------------------
+ * Truncating `0.000000004916 XMR` to eight decimals gives
+ * `0.00000000` — a balance that exists, shown as nothing at all.
+ * `formatCoinAmount` renders that as `< 0.00000001 XMR` instead
+ * (`> -0.00000001` below zero). A threshold marker is honest about
+ * both the amount and the limit of the column; a flat zero is not.
+ * Pass `markDust: false` where a bare numeral is required.
+ *
+ * If you need a *narrower* surface (a dense table, a stat-card
+ * subtitle), use `{ trim: true }` to drop trailing zeros while
+ * keeping the canonical precision as the cap. Don't bypass this
+ * module with an ad-hoc `toFixed(N)` — that's exactly the entropy
+ * we just cleaned up, and `toFixed` rounds the wrong way for money
+ * on top of rounding a double.
+ */
+/**
+ * Canonical display-precision per supported coin. Use this when
+ * you need the raw precision number (e.g. populating an input
+ * field's `.toFixed(...)` to seed a "max balance" button). For
+ * actual rendering of a value, prefer `formatCoinAmount`.
+ */
+export declare const COIN_DISPLAY_DECIMALS: Readonly<Record<string, number>>;
+/**
+ * Atomic-unit precision per coin — what the backend actually stores.
+ *
+ * This is NOT a display precision and must never be used as one; the
+ * platform shows both coins at eight digits on purpose (see the module
+ * docblock). It is the scale to do ARITHMETIC at: totalling balances,
+ * subtracting a lock from a total, comparing an entered amount against
+ * what is available. Doing that at display scale quantizes four XMR
+ * digits away before the sum, and each quantization is a chance to
+ * report a figure the ledger does not agree with.
+ *
+ * The authority is payments's `coins.precision` column (`BTC` 8, `XMR` 12);
+ * main keeps its own copy in `billing.service.ts` as `CRYPTO_PRECISION`.
+ * This is the browser's copy, because a synchronous formatter cannot
+ * query a table. Three copies of one fact: when a coin is added, all
+ * three change, and a mismatch here shows up as arithmetic that silently
+ * drops the coin's last digits.
+ */
+export declare const COIN_WIRE_DECIMALS: Readonly<Record<string, number>>;
+/**
+ * Which way a value that does not fit the requested scale is quantized.
+ *
+ *   `'down'`     toward zero. The displayed magnitude is never larger
+ *                than the real one — the rule for money on a screen.
+ *   `'half-up'`  to the nearest, ties away from zero. The rule for
+ *                arithmetic, where the scale is the value's own.
+ */
+export type DecimalRounding = 'down' | 'half-up';
+export interface FormatCoinAmountOptions {
+    /**
+     * Append the uppercase coin symbol (`"0.00012345 BTC"`).
+     * Default `true`. Disable for places where the symbol is
+     * rendered separately (e.g. a chip beside the number).
+     */
+    withSymbol?: boolean;
+    /**
+     * Trim trailing zeros after the decimal point. Useful in dense
+     * tables where `0 BTC` reads cleaner than `0.00000000 BTC`. The
+     * precision cap (8) is still honoured — we just drop tail
+     * zeros up to and including the decimal point. Default `false`.
+     */
+    trim?: boolean;
+    /**
+     * Override precision. ONLY use this for legacy back-compat
+     * (e.g. a screen that genuinely needs to truncate at a non-
+     * standard width). Prefer the default. Negative values clamp
+     * to 0.
+     */
+    precision?: number;
+    /**
+     * Custom symbol override. Defaults to `coin.toUpperCase()`. Set
+     * this if you need a non-standard label (e.g. "₿" for BTC) —
+     * but be aware that mixing symbols across the platform is what
+     * this module was built to prevent.
+     */
+    symbol?: string;
+    /**
+     * Which way to quantize digits that do not fit `precision`.
+     * Default `'down'` — a rendered amount is never larger than the
+     * amount that exists. Pass `'half-up'` only where the figure is
+     * not a quantity anyone holds (a rate, an average, a chart axis).
+     */
+    rounding?: DecimalRounding;
+    /**
+     * Render a non-zero amount that vanishes at this precision as
+     * `< 0.00000001` rather than `0.00000000`. Default `true`.
+     * Disable where the output has to be a bare numeral.
+     */
+    markDust?: boolean;
+}
+/**
+ * Resolve the canonical display precision for a coin code.
+ * Case-insensitive. Unknown codes fall back to 8.
+ */
+export declare function getCoinDecimals(coin: string): number;
+/**
+ * Resolve the ATOMIC-UNIT precision for a coin code — the scale the value
+ * arrived at and the scale to compute at. Case-insensitive.
+ *
+ * `getCoinDecimals` is for rendering; this is for `sumDecimalStrings`,
+ * `subtractDecimalStrings`, and any comparison between an amount a person
+ * entered and an amount the ledger holds.
+ */
+export declare function getCoinWireDecimals(coin: string): number;
+/**
+ * Format a decimal STRING at a fixed scale without going through a float.
+ *
+ * Exported because more than one surface needs it: `formatCoinAmount` for
+ * coin balances, `AmountCell` for financial tables. Anything that receives a
+ * decimal string from the wire and renders it should use this rather than
+ * `Number(x).toFixed(n)`.
+ *
+ * The docblock above promises that string input "preserves full precision
+ * end-to-end from the RPC wire", but the implementation used to hand the
+ * string straight to `Number()` — inheriting binary floating point along with
+ * its rounding surprises. `'1.005'` is fractionally BELOW 1.005 as a double,
+ * so `toFixed(2)` rendered `'1.00'`: a balance displayed one cent short of
+ * the one actually stored.
+ *
+ * This is the RENDERING half of the pair, so it quantizes DOWN by default:
+ * the string it returns never stands for more than the string it was given.
+ * Its arithmetic counterpart `toScaledInteger` defaults to `'half-up'`;
+ * the two differ on purpose and the module docblock says why.
+ *
+ * Unlike `formatCoinAmount` it always returns a plain parseable decimal —
+ * no threshold marker, no symbol — because its callers feed the result back
+ * into `Number()`.
+ *
+ * @returns the formatted string, or `null` when `raw` is not a plain decimal
+ *          (exponent notation, junk) — the caller then falls back to `Number`.
+ */
+export declare function formatDecimalString(raw: string, decimals: number, rounding?: DecimalRounding): string | null;
+/**
+ * A decimal string as an exact integer at `decimals` scale.
+ *
+ * `'1.005'` at scale 2 is `101n` under the default half-up — which is the
+ * whole point: as a double the same literal sits fractionally BELOW 1.005,
+ * so any arithmetic that starts with `Number('1.005')` has already lost
+ * before it begins.
+ *
+ * The default is `'half-up'` because this is the arithmetic primitive:
+ * callers pass the value's own scale, where the last digit is a rounding
+ * and not a truncation. Rendering goes through `formatDecimalString`, which
+ * defaults to `'down'` — see the module docblock.
+ *
+ * @returns null when `raw` is not a plain decimal (exponent notation, junk).
+ */
+export declare function toScaledInteger(raw: string, decimals: number, rounding?: DecimalRounding): bigint | null;
+/** Render a scaled integer back as a decimal string. Inverse of `toScaledInteger`. */
+export declare function fromScaledInteger(scaled: bigint, decimals: number): string;
+/**
+ * Add decimal strings exactly, returning a decimal string.
+ *
+ * For totalling amounts that arrived from the wire as strings. Accumulating
+ * them with `parseFloat` is the same mistake as formatting with it, one step
+ * earlier and harder to see: `0.1 + 0.2 + 0.3` is `0.6000000000000001`, and
+ * while a formatter capped at eight decimals rounds that back to `0.60000000`,
+ * anything that shows the raw total — a tooltip, a CSV export, a value posted
+ * back to the server — shows the artefact.
+ *
+ * Values that are not plain decimals are skipped rather than poisoning the
+ * total with `NaN`; `null` and `undefined` count as absent, not as zero-ish
+ * junk. Numbers are accepted for callers mid-migration, and go through their
+ * decimal representation rather than their binary one.
+ *
+ * @param decimals scale to accumulate at — use the coin's WIRE precision
+ *        (`getCoinWireDecimals`). Accumulating at display scale quantizes
+ *        each value before it is added, so the total is a sum of roundings;
+ *        `getCoinDecimals` is for the one quantization at the end.
+ * @param options.rounding how each value is quantized to `decimals`. Default
+ *        `'half-up'`; at wire scale nothing is dropped and it does not
+ *        arise. Pass `'down'` if you must accumulate at display scale and
+ *        the total is money — a sum of half-ups can exceed what exists.
+ */
+export declare function sumDecimalStrings(values: Iterable<string | number | null | undefined>, decimals: number, options?: {
+    rounding?: DecimalRounding;
+}): string;
+/**
+ * Subtract decimal strings exactly, returning a decimal string.
+ *
+ * The companion to `sumDecimalStrings`, and the one a wallet needs more
+ * often: available balance is total minus locked, and computing it with
+ * `parseFloat` produces `0.19999999999999998` from `0.30000000 - 0.10000000`.
+ * A formatter capped at the coin's precision rounds that back, but the raw
+ * value does not always reach a formatter — a tooltip, a CSV column, a
+ * "max" button that fills an amount field, or a value posted back to the
+ * server all show it as it is. Small amounts are worse than wrong: they
+ * become exponential notation, and `1.0999999999999999e-7` is not a number
+ * any balance field will accept.
+ *
+ * Unparseable inputs are treated as absent — `null` when the minuend cannot
+ * be read, since a difference from an unknown quantity is unknown, and
+ * subtracting nothing when a subtrahend cannot be read.
+ *
+ * @param decimals scale to compute at — `getCoinWireDecimals(coin)`. At
+ *        display scale the minuend and the subtrahends are each quantized
+ *        first, and an available balance assembled from two roundings can
+ *        come out above the amount the ledger will actually release.
+ * @param clampAtZero return '0' rather than a negative result. On for the
+ *        available-balance case, where a negative would be a display artefact
+ *        of two readings taken a moment apart, not a debt.
+ * @param rounding how each operand is quantized to `decimals`. Default
+ *        `'half-up'`, matching `toScaledInteger`.
+ */
+export declare function subtractDecimalStrings(minuend: string | number | null | undefined, subtrahends: Iterable<string | number | null | undefined>, decimals: number, options?: {
+    clampAtZero?: boolean;
+    rounding?: DecimalRounding;
+}): string | null;
+/**
+ * Format a crypto amount for display.
+ *
+ * Input can be a string (preferred — preserves full precision
+ * end-to-end from the RPC wire) or a number. Non-finite / NaN
+ * inputs render as the zero-shaped placeholder so the UI never
+ * shows `NaN BTC`.
+ *
+ * Digits below the coin's display precision are dropped, not rounded up:
+ * the string returned never stands for more coin than the argument did.
+ * An amount that is real but smaller than the last displayed digit renders
+ * as `< 0.00000001` rather than as a flat zero.
+ *
+ * @example
+ *   formatCoinAmount('0.001', 'BTC')                 // '0.00100000 BTC'
+ *   formatCoinAmount('0.001', 'BTC', { trim: true }) // '0.001 BTC'
+ *   formatCoinAmount(null, 'XMR')                    // '0.00000000 XMR'
+ *   formatCoinAmount('1.23456789', 'BTC', { withSymbol: false }) // '1.23456789'
+ *   formatCoinAmount('1.586170199999', 'XMR')        // '1.58617019 XMR'
+ *   formatCoinAmount('0.000000004916', 'XMR')        // '< 0.00000001 XMR'
+ */
+export declare function formatCoinAmount(value: string | number | null | undefined, coin: string, options?: FormatCoinAmountOptions): string;
+/**
+ * Render a multi-coin total map (e.g. revenue across coins)
+ * as a single inline string: `"0.00010000 BTC · 0.00000000 XMR"`.
+ *
+ * Stable ordering by lower-cased coin code so BTC always appears
+ * before XMR regardless of object-property iteration quirks.
+ */
+export declare function formatCoinAmountList(totals: Partial<Record<string, string | number | null | undefined>>, options?: FormatCoinAmountOptions & {
+    separator?: string;
+}): string;
+//# sourceMappingURL=format-crypto.d.ts.map

package/dist/utils/format-crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-crypto.d.ts","sourceRoot":"","sources":["../../src/utils/format-crypto.ts"],"names":[],"mappings":"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"}