@gibs/quotes 1.13.0

package/dist/quote-guards.js

@@ -0,0 +1,240 @@
+import { ecosystemRegistry } from '@gibs/bridge-sdk/ecosystems';
+import { decodeBaseUnitsAmount } from './quote-service-contract.js';
+import { twoSignificantFigureAmountBucket } from './search/waves.js';
+/**
+ * The shared upstream guards `docs/quote-service.md`'s "Guards" and "Cache"
+ * sections name: a keyed concurrency limiter with a deadline, a Retry-After
+ * cooldown, the display-quote cache key, and the bigint scaling formula. A
+ * host wraps every network call to a provider through these before it ever
+ * reaches `fetch` — see `types.ts`'s `UpstreamFunnel`.
+ */
+// ---------------------------------------------------------------------------
+// Keyed concurrency limiter — per-key cap, FIFO queue, deadline -> busy
+// ---------------------------------------------------------------------------
+/**
+ * Thrown by {@link KeyedConcurrencyLimiter.run} when a slot under `key` does
+ * not open before the caller's deadline. The task is never started — a host
+ * catches this and answers `could-not-ask: busy` (`docs/quote-service.md`'s
+ * "Guards" section) rather than queuing indefinitely behind a saturated
+ * provider.
+ */
+export class ConcurrencyDeadlineExceededError extends Error {
+    key;
+    constructor(key) {
+        super(`no slot for "${key}" opened before the deadline`);
+        this.key = key;
+        this.name = 'ConcurrencyDeadlineExceededError';
+    }
+}
+const scheduleTimer = (callback, delayMs) => {
+    const handle = setTimeout(callback, Math.max(0, delayMs));
+    // `unref` exists on Node's Timeout but not on the browser's numeric handle
+    // — isomorphic code checks for it rather than assuming either shape, so a
+    // pending deadline never keeps a Node process alive on its own.
+    if (typeof handle === 'object' && handle !== null && 'unref' in handle) {
+        handle.unref();
+    }
+    return () => clearTimeout(handle);
+};
+/**
+ * Builds a fresh, empty {@link KeyedConcurrencyLimiter}.
+ *
+ * @returns the limiter
+ */
+export const createKeyedConcurrencyLimiter = () => {
+    const activeCountByKey = new Map();
+    const queueByKey = new Map();
+    const release = (key) => {
+        const active = activeCountByKey.get(key) ?? 0;
+        activeCountByKey.set(key, Math.max(0, active - 1));
+        const next = queueByKey.get(key)?.shift();
+        if (next !== undefined)
+            next();
+    };
+    const acquire = (key, limit, deadlineMs, now) => {
+        const active = activeCountByKey.get(key) ?? 0;
+        if (active < limit) {
+            activeCountByKey.set(key, active + 1);
+            return Promise.resolve();
+        }
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const grant = () => {
+                if (settled)
+                    return;
+                settled = true;
+                cancelTimer?.();
+                activeCountByKey.set(key, (activeCountByKey.get(key) ?? 0) + 1);
+                resolve();
+            };
+            const queue = queueByKey.get(key) ?? [];
+            queue.push(grant);
+            queueByKey.set(key, queue);
+            const cancelTimer = deadlineMs === undefined
+                ? undefined
+                : scheduleTimer(() => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    const currentQueue = queueByKey.get(key);
+                    const index = currentQueue?.indexOf(grant) ?? -1;
+                    if (currentQueue !== undefined && index !== -1)
+                        currentQueue.splice(index, 1);
+                    reject(new ConcurrencyDeadlineExceededError(key));
+                }, deadlineMs - now());
+        });
+    };
+    return {
+        run: async (key, limit, task, options) => {
+            await acquire(key, limit, options?.deadlineMs, options?.now ?? Date.now);
+            try {
+                return await task();
+            }
+            finally {
+                release(key);
+            }
+        },
+        queueDepth: (key) => {
+            if (key !== undefined)
+                return queueByKey.get(key)?.length ?? 0;
+            let total = 0;
+            for (const queue of queueByKey.values())
+                total += queue.length;
+            return total;
+        },
+    };
+};
+// ---------------------------------------------------------------------------
+// Retry-After cooldown — 30 s default, never zero, seconds or HTTP date
+// ---------------------------------------------------------------------------
+/** How long a key is treated as rate-limited when its answer carries no readable `Retry-After`. */
+export const DEFAULT_RETRY_AFTER_COOLDOWN_MS = 30_000;
+/**
+ * Reads a `Retry-After` header value as a millisecond delay from now.
+ *
+ * The header is either a whole number of seconds or an HTTP-date (RFC 9110
+ * §10.2.3); both are read. An absent, unreadable, non-positive, or zero
+ * value falls back to `defaultMs` — `docs/quote-service.md`'s cache rule is
+ * explicit: "30 s default, never 0." A key that rate-limited us once without
+ * saying for how long — or that names a cooldown already in the past — is
+ * not asked again on the very next call.
+ *
+ * @param retryAfterHeader - the header's raw value, or null when absent
+ * @param nowMs - the current time in epoch milliseconds
+ * @param defaultMs - the fallback cooldown
+ * @returns the delay, in milliseconds, before the key should be asked again
+ */
+const backoffMsFromRetryAfter = (retryAfterHeader, nowMs, defaultMs) => {
+    if (retryAfterHeader === null) {
+        return defaultMs;
+    }
+    const seconds = Number(retryAfterHeader);
+    // A FINITE NUMBER IS DECIDED HERE, NEVER HANDED TO `Date.parse`. A plain
+    // digit string such as `'0'` is unambiguously a seconds value, not a date
+    // — but `Date.parse('0')` does not throw or return `NaN`; it happily reads
+    // it as a bare year and returns a timestamp decades away. Falling through
+    // to the date branch for a non-positive number turned "never zero" into
+    // "cooldown for decades" instead of the intended 30 s default.
+    if (Number.isFinite(seconds)) {
+        return seconds > 0 ? seconds * 1000 : defaultMs;
+    }
+    const untilMs = Date.parse(retryAfterHeader);
+    if (Number.isFinite(untilMs)) {
+        const deltaMs = untilMs - nowMs;
+        return deltaMs > 0 ? deltaMs : defaultMs;
+    }
+    return defaultMs;
+};
+/**
+ * Builds a fresh, empty {@link RetryAfterCooldown}.
+ *
+ * @param options.defaultMs - the fallback cooldown; defaults to
+ *   {@link DEFAULT_RETRY_AFTER_COOLDOWN_MS}
+ * @returns the cooldown tracker
+ */
+export const createRetryAfterCooldown = (options) => {
+    const defaultMs = options?.defaultMs ?? DEFAULT_RETRY_AFTER_COOLDOWN_MS;
+    const cooldownUntilMsByKey = new Map();
+    return {
+        record: (key, retryAfterHeader, nowMs = Date.now()) => {
+            cooldownUntilMsByKey.set(key, nowMs + backoffMsFromRetryAfter(retryAfterHeader, nowMs, defaultMs));
+        },
+        isActive: (key, nowMs = Date.now()) => {
+            const untilMs = cooldownUntilMsByKey.get(key);
+            return untilMs !== undefined && nowMs < untilMs;
+        },
+        clearsAtMs: (key) => cooldownUntilMsByKey.get(key) ?? null,
+        reset: () => {
+            cooldownUntilMsByKey.clear();
+        },
+    };
+};
+// ---------------------------------------------------------------------------
+// The display-quote cache key
+// ---------------------------------------------------------------------------
+/** Canonical spelling every known native-asset placeholder normalizes to. */
+const NATIVE_TOKEN_PLACEHOLDER = 'native';
+/** Every ecosystem's own native-asset sentinel string, lower-cased, as a lookup set. */
+const nativeAssetSentinels = new Set(ecosystemRegistry.map((descriptor) => descriptor.nativeAssetSentinel.toLowerCase()));
+/** A plain 20-byte Ethereum-style hex address. */
+const evmHexAddressPattern = /^0x[0-9a-fA-F]{40}$/;
+/**
+ * Normalizes one token reference for the cache key, per
+ * `docs/quote-service.md`'s "Cache" section: "Ethereum-style addresses
+ * lowercased; native placeholders mapped to one form; base58/bech32 keep
+ * case."
+ *
+ * @param token - the raw token address or identifier from a {@link DisplayAsk}
+ * @returns the normalized form
+ */
+const normalizeCacheKeyToken = (token) => {
+    if (nativeAssetSentinels.has(token.toLowerCase()))
+        return NATIVE_TOKEN_PLACEHOLDER;
+    return evmHexAddressPattern.test(token) ? token.toLowerCase() : token;
+};
+/**
+ * Builds the display-quote cache key for one provider's answer to one ask,
+ * exactly per `docs/quote-service.md`'s "Cache" section:
+ * `v1|provider|from.chainId|from.token|to.chainId|to.token|recipientEcosystem|probeSetVersion|bucket`.
+ *
+ * @param provider - which provider this key caches an answer for
+ * @param ask - the ask being cached; only the fields the key is built from
+ * @param probeSetVersion - the server's own probe-address generation, so a
+ *   rotated probe address never serves a cached answer keyed to the old one
+ * @returns the cache key
+ */
+export const displayQuoteCacheKey = (provider, ask, probeSetVersion) => {
+    const bucket = twoSignificantFigureAmountBucket(decodeBaseUnitsAmount(ask.amount));
+    return [
+        'v1',
+        provider,
+        ask.from.chainId.toString(),
+        normalizeCacheKeyToken(ask.from.token),
+        ask.to.chainId.toString(),
+        normalizeCacheKeyToken(ask.to.token),
+        ask.recipientEcosystem ?? '',
+        probeSetVersion,
+        bucket.toString(),
+    ].join('|');
+};
+// ---------------------------------------------------------------------------
+// Scaling a cached figure to the amount actually asked
+// ---------------------------------------------------------------------------
+/**
+ * Scales a cached figure — answered for a NEARBY amount — into an estimate
+ * for the amount actually asked, per `docs/quote-service.md`'s "Cache"
+ * section: `scaled = figure × userAmount / askedAmount`, entirely in bigint.
+ *
+ * @param figure - the nearby amount's own raw answer
+ * @param userAmount - the amount actually asked for (this asker's own amount)
+ * @param askedAmount - the amount that was actually asked upstream (the
+ *   nearby, cached amount `figure` answers)
+ * @returns the scaled estimate, in the same units as `figure`
+ * @throws when `askedAmount` is not positive — there is nothing to scale from
+ */
+export const scaleToAskedAmount = (figure, userAmount, askedAmount) => {
+    if (askedAmount <= 0n) {
+        throw new Error('scaleToAskedAmount: askedAmount must be positive');
+    }
+    return (figure * userAmount) / askedAmount;
+};

package/dist/quote-refusals.d.ts

@@ -0,0 +1,180 @@
+import type { ProviderId } from '@gibs/bridge-sdk/providers';
+/**
+ * Why a quote provider gave the reader no route.
+ *
+ * WHY THIS EXISTS. A provider that answered "I cannot carry this" used to be
+ * dropped with no trace, and its route simply was not on the strip. That
+ * silence hid real defects: NEAR Intents refused wrapped ether on Ethereum
+ * for weeks and nothing on screen said so. Every reader here names the
+ * provider it asked and did not get a route from.
+ *
+ * THREE KINDS, AND THEY MUST READ DIFFERENTLY. Measured against LI.FI on
+ * 2026-09-21: a well-formed request with no route answers 404 with
+ * `code 1002`; a path that does not exist also answers 404, with
+ * `code 1003`; a malformed body answers 400 with `code 1011`. Only the
+ * first is the provider saying "no". The others mean the question was never
+ * answered, and a reader told "no route" when the truth is "we could not
+ * ask" draws the wrong conclusion.
+ *
+ * - `no-quote` — the provider answered and declined.
+ * - `could-not-ask` — the request failed, or the answer was unreadable.
+ * - `cannot-carry` — the provider was never asked, because it cannot express
+ *   this pair at all (its request builder returned nothing).
+ * - `invalid-api-key` — the provider rejected the api key attached to this
+ *   request. Kept apart from `could-not-ask` because it is not a transient
+ *   failure: a rejected key does not clear on its own, and treating it as a
+ *   generic "we could not ask" invites a retry that repeats the exact same
+ *   rejection. See {@link readLifiRefusal}. THIS MODULE NEVER LOGS OR
+ *   RECORDS THE REJECTION ITSELF — it only classifies the response. A host
+ *   that wants the rejection remembered (so it stops retrying, or logs it
+ *   once) does that itself by checking `kind === 'invalid-api-key'` on the
+ *   returned refusal; see `packages/ui/src/lib/stores/quote-refusals.ts`'s
+ *   `readLifiRefusal` wrapper for the browser-side example.
+ */
+export type QuoteRefusalKind = 'no-quote' | 'could-not-ask' | 'cannot-carry' | 'invalid-api-key';
+/** One provider that was asked for a route and did not return one. */
+export type ProviderQuoteRefusal = {
+    /** Which provider. */
+    readonly provider: ProviderId;
+    /** Whether it declined, could not be asked, or cannot carry the pair. */
+    readonly kind: QuoteRefusalKind;
+    /**
+     * The provider's own words for why, shortened for a tooltip, or null when
+     * the answer carried none. Never invented: when this is null the surface
+     * says only that no reason was given.
+     */
+    readonly reason: string | null;
+    /**
+     * A minimum amount the refusal named, in the ORIGIN token's base units, or
+     * undefined when it named none.
+     *
+     * Only `readNearIntentsRefusal`'s `belowBridgeMinimum` case sets it: that
+     * is the one refusal among the three providers whose minimum already
+     * arrives in the ORIGIN token's own base units rather than United States
+     * dollars. A `belowChainMinimum` refusal names its floor in dollars and is
+     * left unset here for the same reason: converting it to base units needs a
+     * price this module does not have, and a floor that silently mixed units
+     * would prune the wrong edges.
+     */
+    readonly minimumAmount?: bigint;
+};
+/**
+ * Thrown by a provider transport when the provider answered without a quote.
+ *
+ * Carries the classified refusal so the caller can record WHICH provider said
+ * no and why, instead of a bare `Error` whose message is the only trace.
+ */
+export declare class ProviderQuoteError extends Error {
+    readonly refusal: ProviderQuoteRefusal;
+    constructor(refusal: ProviderQuoteRefusal);
+}
+/**
+ * Thrown when no provider returned a quote, carrying every refusal.
+ *
+ * The message is unchanged from the plain error this replaces, because callers
+ * and tests match on it; the refusals are what is new.
+ */
+export declare class NoProviderQuotedError extends Error {
+    readonly refusals: readonly ProviderQuoteRefusal[];
+    constructor(refusals: readonly ProviderQuoteRefusal[]);
+}
+/**
+ * Whether a LI.FI response is specifically "the api key attached to this
+ * request was rejected" — a 401 carrying `code: 1010`, "Invalid API key".
+ * Measured live: this is the ONE 401 shape LI.FI answers with when the
+ * configured key is bad, distinct from a plain unauthenticated request
+ * (which LI.FI answers normally at a lower rate limit, never 401).
+ *
+ * Exported so every LI.FI response reader — not only the quote endpoints —
+ * can classify a failure the same way.
+ *
+ * @param status - the HTTP status
+ * @param body - the parsed JSON body, or null when it was unreadable
+ * @returns whether this response is LI.FI rejecting the configured key
+ */
+export declare const isLifiInvalidApiKeyResponse: (status: number, body: unknown) => boolean;
+/**
+ * Classifies a non-success LI.FI answer.
+ *
+ * `code 1002` is the one "no" — see {@link QuoteRefusalKind}. A rejected api
+ * key ({@link isLifiInvalidApiKeyResponse}) is its own kind,
+ * `invalid-api-key`. Everything else, including a 404 carrying a different
+ * code, is a request that could not be made.
+ *
+ * PURE: this reader never logs and never records anything. A host that wants
+ * a rejected key remembered — so it stops retrying, or logs it once — reads
+ * `kind === 'invalid-api-key'` off the return value and records it itself.
+ *
+ * @param status - the HTTP status
+ * @param body - the parsed JSON body, or null when it was unreadable
+ * @returns the refusal
+ */
+export declare const readLifiRefusal: (status: number, body: unknown) => ProviderQuoteRefusal;
+/**
+ * Classifies a non-success Relay answer.
+ *
+ * Relay declines with a 4xx carrying an `errorCode` — measured:
+ * `{"message":"no routes found","errorCode":"NO_SWAP_ROUTES_FOUND"}`. A 4xx
+ * with a code is the provider saying no; a server error, an unauthenticated
+ * or rate-limited request (see {@link REQUEST_NEVER_REACHED_STATUSES}), or a
+ * body with no code, is a request that could not be made.
+ *
+ * @param status - the HTTP status
+ * @param body - the parsed JSON body, or null when it was unreadable
+ * @returns the refusal
+ */
+export declare const readRelayRefusal: (status: number, body: unknown) => ProviderQuoteRefusal;
+/**
+ * Classifies a declined NEAR Intents `POST /v0/quote` answer.
+ *
+ * WORTH ITS OWN READER, SEPARATE FROM {@link readLifiRefusal} AND
+ * {@link readRelayRefusal}. NEAR Intents' decline carries no HTTP status code
+ * of its own worth branching on — every decline this service gives arrives
+ * as a 400 with a `message` — so the classification work is entirely in
+ * READING that message, which `@gibs/bridge-sdk/near-intents`'s
+ * `parseNearIntentsQuoteRefusal` already does. EVERY readable reason is a
+ * `'no-quote'` — the service considered the pair and named a real,
+ * size-shaped reason it cannot carry it — and only an UNREADABLE body falls
+ * back to `'could-not-ask'`, matching this module's own rule that a request
+ * that never got an answer must never read as a "no."
+ *
+ * @param status - the HTTP status (informational only; NEAR Intents declines
+ *   are read from the body, not the status)
+ * @param body - the parsed JSON body, or null when it was unreadable
+ * @returns the refusal
+ */
+export declare const readNearIntentsRefusal: (status: number, body: unknown) => ProviderQuoteRefusal;
+/**
+ * Turns one rejected provider call into a refusal, or null for an abort.
+ *
+ * An abort is not a refusal — the reader moved on and the question was
+ * withdrawn — so it is never reported. A {@link ProviderQuoteError} already
+ * carries its classification. Anything else thrown is a failure to ask.
+ *
+ * @param provider - the provider whose call rejected
+ * @param reason - the rejection value
+ * @param signal - the shared abort signal, to recognise a withdrawn question
+ * @returns the refusal, or null when the call was aborted
+ */
+export declare const refusalFromRejection: (provider: ProviderId, reason: unknown, signal: AbortSignal) => ProviderQuoteRefusal | null;
+/**
+ * The refusals one route entry reports: the shared quote's, plus the
+ * separate two-step NEAR Intents question when that was asked.
+ *
+ * NEAR Intents is asked TWICE per entry, in two shapes. The shared quote asks
+ * it for a one-signature crossing, which it can never form — so it always
+ * answers `cannot-carry` there — while the two-step query asks it the
+ * question it can answer. When the two-step question was asked, its answer
+ * is NEAR Intents' real one, and the shared `cannot-carry` would contradict
+ * it.
+ *
+ * @param options.quoteRefusals - the shared quote's refusals
+ * @param options.twoStepAsked - whether the two-step question was asked
+ * @param options.twoStepError - the two-step query's error, or null
+ * @returns the entry's refusals, one per provider at most
+ */
+export declare const mergeEntryRefusals: ({ quoteRefusals, twoStepAsked, twoStepError, }: {
+    quoteRefusals: readonly ProviderQuoteRefusal[];
+    twoStepAsked: boolean;
+    twoStepError: unknown;
+}) => readonly ProviderQuoteRefusal[];