@gibs/quotes 1.13.0

package/dist/quote-refusals.js

@@ -0,0 +1,284 @@
+import { parseNearIntentsQuoteRefusal, } from '@gibs/bridge-sdk/near-intents';
+/**
+ * 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 class ProviderQuoteError extends Error {
+    refusal;
+    constructor(refusal) {
+        super(`${refusal.provider} gave no quote: ${refusal.reason ?? refusal.kind}`);
+        this.refusal = refusal;
+        this.name = 'ProviderQuoteError';
+    }
+}
+/**
+ * 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 class NoProviderQuotedError extends Error {
+    refusals;
+    constructor(refusals) {
+        super('invalid consolidated quote request');
+        this.refusals = refusals;
+        this.name = 'NoProviderQuotedError';
+    }
+}
+/** Longest reason kept, so one verbose provider cannot flood a tooltip. */
+const MAX_REASON_LENGTH = 160;
+const asRecord = (value) => typeof value === 'object' && value !== null ? value : null;
+const shorten = (text) => text.length <= MAX_REASON_LENGTH ? text : `${text.slice(0, MAX_REASON_LENGTH - 1)}…`;
+/** The sentence one excluded LI.FI path carries: `reason` when filtered, `message` when failed. */
+const pathReasonText = (record) => {
+    if (typeof record?.reason === 'string')
+        return record.reason;
+    if (typeof record?.message === 'string')
+        return record.message;
+    return null;
+};
+/**
+ * The most common reason among LI.FI's excluded paths, with its count.
+ *
+ * A LI.FI refusal lists every path it considered — measured at over a hundred
+ * for a small Base to Ethereum request — each with its own sentence, most of
+ * them identical but for the figures inside them. Grouping on the sentence
+ * with its numbers and parenthesised detail removed gives the one line that
+ * explains the refusal, rather than a hundred lines nobody reads.
+ *
+ * THE NORMALIZED KEY IS FOR COUNTING ONLY, NEVER FOR DISPLAY. It exists to
+ * tell two paths apart that differ only by amount; showing it to the reader
+ * showed a sentence with its numbers deleted — "amount ETH is below the
+ * minimum of ETH" — rather than an explanation. The text returned is always
+ * one of the ORIGINAL, unmutated sentences from the most common group.
+ */
+const dominantLifiPathReason = (errors) => {
+    if (errors === null)
+        return null;
+    const entries = [
+        ...(Array.isArray(errors.filteredOut) ? errors.filteredOut : []),
+        ...(Array.isArray(errors.failed) ? errors.failed : []),
+    ];
+    const groups = new Map();
+    for (const entry of entries) {
+        const text = pathReasonText(asRecord(entry));
+        if (text === null)
+            continue;
+        const normalized = text.replace(/\([^)]*\)/g, '').replace(/\d+/g, '').replace(/\s+/g, ' ').trim();
+        if (normalized === '')
+            continue;
+        const group = groups.get(normalized);
+        if (group === undefined) {
+            groups.set(normalized, { count: 1, example: text });
+            continue;
+        }
+        group.count += 1;
+    }
+    let best = null;
+    for (const group of groups.values()) {
+        if (best === null || group.count > best.count)
+            best = group;
+    }
+    if (best === null)
+        return null;
+    return `${best.example} (${best.count} of ${entries.length} paths)`;
+};
+/**
+ * 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 const isLifiInvalidApiKeyResponse = (status, body) => {
+    const record = asRecord(body);
+    return status === 401 && record?.code === 1010;
+};
+/**
+ * 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 const readLifiRefusal = (status, body) => {
+    const record = asRecord(body);
+    const message = typeof record?.message === 'string' ? record.message : null;
+    if (isLifiInvalidApiKeyResponse(status, body)) {
+        return {
+            provider: 'lifi',
+            kind: 'invalid-api-key',
+            reason: shorten(message ?? 'the configured LI.FI api key was rejected'),
+        };
+    }
+    if (record?.code === 1002) {
+        const dominant = dominantLifiPathReason(asRecord(record.errors));
+        const reason = [message, dominant].filter((part) => part !== null).join('. ');
+        return { provider: 'lifi', kind: 'no-quote', reason: reason === '' ? null : shorten(reason) };
+    }
+    return {
+        provider: 'lifi',
+        kind: 'could-not-ask',
+        reason: shorten(message ?? `the service answered ${status}`),
+    };
+};
+/**
+ * The two 4xx statuses that never mean "the provider considered this pair
+ * and said no" — they mean the QUESTION itself did not get through.
+ *
+ * 401 is a credentials failure and 429 is a rate limit; either can carry a
+ * body shaped exactly like a genuine decline (a `message` and an
+ * `errorCode`), because it is the same generic error envelope the API uses
+ * for every 4xx. Reading that envelope as a decline told the reader the
+ * provider had considered their transfer and refused it, when the truth is
+ * we never managed to ask.
+ */
+const REQUEST_NEVER_REACHED_STATUSES = new Set([401, 429]);
+/**
+ * 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 const readRelayRefusal = (status, body) => {
+    const record = asRecord(body);
+    const message = typeof record?.message === 'string' ? record.message : null;
+    const declined = status >= 400 &&
+        status < 500 &&
+        !REQUEST_NEVER_REACHED_STATUSES.has(status) &&
+        typeof record?.errorCode === 'string';
+    return {
+        provider: 'relay',
+        kind: declined ? 'no-quote' : 'could-not-ask',
+        reason: shorten(message ?? `the service answered ${status}`),
+    };
+};
+/**
+ * Turns a parsed {@link NearIntentsQuoteRefusal} into the plain sentence this
+ * surface shows for it.
+ *
+ * @param refusal - the parsed reason, or null when the body carried none
+ * @returns a plain-language description of the decline
+ */
+const nearIntentsRefusalSentence = (refusal) => {
+    if (refusal === null) {
+        return 'the service declined the request without a readable reason';
+    }
+    switch (refusal.reason) {
+        case 'belowChainMinimum':
+            return `the amount is under this chain's temporary minimum of ${refusal.minimumUsd} United States dollars`;
+        case 'belowBridgeMinimum':
+            return `the amount is under the bridge's live minimum of ${refusal.minimumAmount} base units of the origin token`;
+        case 'noLiquidity':
+            return 'No liquidity available for this pair right now';
+        case 'other':
+            return 'the service declined the request for an unstated reason';
+    }
+};
+/**
+ * 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 const readNearIntentsRefusal = (status, body) => {
+    const refusal = parseNearIntentsQuoteRefusal(body);
+    if (refusal === null) {
+        return {
+            provider: 'near-intents',
+            kind: 'could-not-ask',
+            reason: shorten(`the service answered ${status} with no readable reason`),
+        };
+    }
+    return {
+        provider: 'near-intents',
+        kind: 'no-quote',
+        reason: shorten(nearIntentsRefusalSentence(refusal)),
+        ...(refusal.reason === 'belowBridgeMinimum' ? { minimumAmount: refusal.minimumAmount } : {}),
+    };
+};
+/**
+ * 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 const refusalFromRejection = (provider, reason, signal) => {
+    if (signal.aborted)
+        return null;
+    if (reason instanceof ProviderQuoteError)
+        return reason.refusal;
+    const message = reason instanceof Error ? reason.message : null;
+    return { provider, kind: 'could-not-ask', reason: message === null ? null : shorten(message) };
+};
+/**
+ * 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 const mergeEntryRefusals = ({ quoteRefusals, twoStepAsked, twoStepError, }) => {
+    if (!twoStepAsked)
+        return quoteRefusals;
+    const withoutNear = quoteRefusals.filter((refusal) => refusal.provider !== 'near-intents');
+    if (twoStepError === null || twoStepError === undefined)
+        return withoutNear;
+    if (twoStepError instanceof ProviderQuoteError)
+        return [...withoutNear, twoStepError.refusal];
+    const message = twoStepError instanceof Error ? shorten(twoStepError.message) : null;
+    return [...withoutNear, { provider: 'near-intents', kind: 'could-not-ask', reason: message }];
+};