@gibs/quotes 1.13.0

package/dist/types.d.ts

@@ -0,0 +1,502 @@
+import type { Ecosystem } from '@gibs/bridge-sdk/ecosystems';
+import type { ProviderId } from '@gibs/bridge-sdk/providers';
+import type { AssetNode, HopEdge, HopEdgeOrigin, HopFloor } from '@gibs/bridge-sdk/routing';
+import type { AskEdge, AskEdgeAnswer, AskEdgeRequest, EdgeRefusal, EdgeRefusalKind } from './search/waves.js';
+import type { DisplayProviderSlot } from './quote-service-contract.js';
+/**
+ * The internal interfaces later steps in this package build against: the
+ * route-search {@link Carrier} plug-in vocabulary, the funnel every carrier's
+ * network calls pass through, the display-quote answer cache, and the
+ * configuration object that makes the whole library agnostic to any one
+ * host. See `docs/quote-service.md`'s "Library" and "Carriers" sections for
+ * the narrative this file's shapes implement.
+ *
+ * NOTHING HERE NAMES A HOST. No `gibs.finance`, no chain 369, no PulseChain,
+ * no omnibridge, no PulseX, no API key. Every fact a host supplies travels
+ * through {@link QuoteClientConfig} or a registered {@link Carrier} — never a
+ * constant in this file.
+ */
+/** Identifies one registered {@link Carrier}. A plain string, not a closed union — see this section's head note for why. */
+export type CarrierId = string;
+/** One asset a route search can hold: a token, or a chain's native currency, on one chain. Alias of `@gibs/bridge-sdk/routing`'s `AssetNode`. */
+export type CarrierAssetNode = AssetNode;
+/** How a hop's crossing is initiated. Alias of `@gibs/bridge-sdk/routing`'s `HopEdgeOrigin`. */
+export type CarrierHopOrigin = HopEdgeOrigin;
+/** A known minimum this edge has already been refused below. Alias of `@gibs/bridge-sdk/routing`'s `HopFloor`. */
+export type CarrierHopFloor = HopFloor;
+/**
+ * One directed edge a {@link Carrier} can move funds across. Alias of
+ * `@gibs/bridge-sdk/routing`'s `HopEdge` — that type's own `carrier` field is
+ * already {@link CarrierId} (a plain string), not a closed union, so no
+ * narrowing is needed here.
+ */
+export type CarrierHopEdge = HopEdge;
+/** One request a {@link Carrier} is asked: "what does this edge deliver for this input?" Alias of `@gibs/bridge-sdk/routing`'s `AskEdgeRequest`. */
+export type CarrierAskRequest = AskEdgeRequest;
+/**
+ * Why an edge answered with a refusal rather than a deliverable amount.
+ * Alias of `@gibs/bridge-sdk/routing`'s `EdgeRefusalKind` — a broader
+ * vocabulary than {@link QuoteRefusalKind} in `quote-refusals.ts`, because a
+ * carrier can also refuse for a bound its own local read enforces
+ * (`'below-minimum'`, `'above-available'`), not only an aggregator's "no" or
+ * "could not ask."
+ */
+export type CarrierRefusalKind = EdgeRefusalKind;
+/** Why a carrier refused, with its reason and any minimum learned from it. Alias of `@gibs/bridge-sdk/routing`'s `EdgeRefusal`. */
+export type CarrierRefusal = EdgeRefusal;
+/** What answering one {@link CarrierAskRequest} produces. Alias of `@gibs/bridge-sdk/routing`'s `AskEdgeAnswer`. */
+export type CarrierAskAnswer = AskEdgeAnswer;
+/** Asks one carrier's edge, at one amount, for what it delivers. Alias of `@gibs/bridge-sdk/routing`'s `AskEdge`. */
+export type CarrierAsk = AskEdge;
+/** What {@link Carrier.fusesWithNext} is asked about the hop immediately following the one it performs. */
+export type CarrierFusesWithNextOptions = {
+    /**
+     * What the acting hop itself spends — its `from` node. A carrier whose
+     * destination call is available only from some origins (LI.FI's
+     * contract-calls endpoint answers for Ethereum alone) reads its chain here.
+     */
+    readonly hopFrom: CarrierAssetNode;
+    /** The carrier of the hop immediately after this one in the same plan. */
+    readonly nextHopCarrier: CarrierId;
+    /**
+     * What the next hop spends — its `from` node, which is where the acting hop
+     * lands. A native coin here means the next hop's call is payable (the
+     * omnibridge's native entry), and a carrier that cannot attach value to its
+     * destination call must not fuse into it.
+     */
+    readonly nextHopFrom: CarrierAssetNode;
+    /** The chain id the next hop DELIVERS to — its `to.chainId`. */
+    readonly nextHopDestinationChainId: number;
+};
+/**
+ * How a reader may fund the first hop of a route section that starts with
+ * this carrier.
+ *
+ * REPLACES A BOOLEAN `acceptsByHandDeposit` FIELD ON PURPOSE — see this
+ * file's Code Style rule against boolean fields. `'wallet-signed'` and
+ * `'by-hand-deposit'` are not two poles of one axis a reader flips; a third,
+ * genuinely different carrier exists that offers BOTH (NEAR Intents, which
+ * carries a pay-by-hand origin's first hop today and also runs as an
+ * ordinary wallet-signed aggregator mid-route), and a boolean has no way to
+ * say "either" without a second field beside it — which is exactly the
+ * "two names for one fact" trap the boolean would have created.
+ *
+ * - `'wallet-signed'` — the reader's connected wallet signs a transaction.
+ *   Every aggregator and on-chain carrier that has no deposit-address flow
+ *   (LI.FI, Relay, the omnibridge crossing, a PulseX swap) is this.
+ * - `'by-hand-deposit'` — the reader sends funds to a carrier-supplied
+ *   deposit address; no wallet signature. `@gibs/bridge-sdk/chain-names`'s
+ *   `isDepositAddressChain` is the origin-side test this pairs with:
+ *   `enumerate.ts` prunes every carrier whose `depositMode` is
+ *   `'wallet-signed'` from a pay-by-hand origin's first hop.
+ * - `'either'` — the carrier can be funded either way, chosen elsewhere by
+ *   which hop it fills (NEAR Intents today).
+ */
+export type CarrierDepositMode = 'wallet-signed' | 'by-hand-deposit' | 'either';
+/**
+ * Which signer a route section STARTING with this carrier uses — what a
+ * display layer names next to its "sign" prompt.
+ *
+ * AN OPEN STRING-LITERAL UNION, LIKE {@link CarrierId}'s OWN NOTE EXPLAINS:
+ * this package's own built-in carriers (LI.FI, Relay, NEAR Intents) are all
+ * `'aggregator'`; a host's own carriers name the other two known values here
+ * (gibs registers the omnibridge crossing as `'omnibridge'` and its PulseX
+ * conversion leg as `'swap'`) or coins its own term entirely — the
+ * `(string & {})` member keeps editor autocomplete for the known set without
+ * closing the union to a host's own vocabulary, exactly as `CarrierId`
+ * itself stays a plain string rather than a closed union.
+ */
+export type CarrierSender = 'omnibridge' | 'aggregator' | 'swap' | 'deposit-address' | (string & {});
+/**
+ * What {@link Carrier.exact} answers for one edge at one input amount, once
+ * {@link Carrier.prepare} has read whatever local data (a fee rate, a pool's
+ * reserves, a known limit) the answer needs.
+ *
+ * TWO CASES, BOTH DISTINCT FROM THE BARE `null` {@link Carrier.exact} MAY ALSO
+ * RETURN. `'delivered'` is the exact answer. `'refused'` is ALSO a real
+ * answer — the carrier read its own data and that data says this amount
+ * cannot cross (below a minimum, above an available reserve) — so it carries
+ * a {@link CarrierRefusal}, reusing the SAME reason vocabulary a live
+ * provider's own `ask()` refusal already uses, rather than inventing a
+ * second one for a local read. Bare `null` is reserved for a carrier that
+ * has NOTHING to say about this edge at all (its `prepare` was never called,
+ * or this edge fell outside what it read) — a structural non-answer, not a
+ * reasoned refusal; `enumerate.ts` treats both the same way for pruning
+ * (this candidate hop is dropped), but only `'refused'` carries a reason
+ * worth keeping.
+ */
+export type ExactHopResult = {
+    readonly outcome: 'delivered';
+    /** What this edge delivers for exactly the requested input amount, in `to`'s base units. */
+    readonly deliveredAmount: bigint;
+} | {
+    readonly outcome: 'refused';
+    /** Why this carrier's own data says the amount cannot cross. */
+    readonly refusal: CarrierRefusal;
+};
+/**
+ * What {@link Carrier.estimate} answers for one edge at one input amount — a
+ * PROVIDER MODEL, not a live quote and not a local exact read: a price ratio
+ * times (one minus the carrier's typical fee) minus a fixed cost, calibrated
+ * against observed history. `enumerate.ts` always grounds a figure this
+ * method produces on the `'provider-model'` {@link @gibs/bridge-sdk/routing!EstimateBasis} — RANKABLE
+ * (a search may compare and prune on it) but NEVER CONFIRMED (a search may
+ * never report it as the final winner without a live quote first) — see
+ * `@gibs/bridge-sdk/routing`'s `RANKABLE_ESTIMATE_BASES` and
+ * `isConfirmedBasis` for where that split is enforced.
+ */
+export type EstimatedHopResult = {
+    /** What this carrier's provider model expects this edge to deliver for the requested input amount, in `to`'s base units. */
+    readonly deliveredAmount: bigint;
+};
+/**
+ * One plug-in the route-search maximization engine can ask: a built-in
+ * aggregator this package ships (LI.FI, Relay, NEAR Intents) or a host's own
+ * local read (an omnibridge crossing, a PulseX swap, or anything else a
+ * host's own code registers).
+ *
+ * `ProviderAsker` (the built-in aggregator's own vocabulary) IS a `Carrier` —
+ * see {@link ProviderAsker}'s doc for why the two are one vocabulary, not two.
+ */
+export type Carrier = {
+    /** This carrier's own id — what {@link CarrierHopEdge.carrier} names when this carrier performs a hop. */
+    readonly id: CarrierId;
+    /**
+     * Every edge this carrier can move funds across right now, given its own
+     * capability data (a chain list, a token list, bridgeable pairs — whatever
+     * it was built from). Mirrors `routing/search/capabilities.ts`'s
+     * `CapabilityIndex.carriersFrom`, scoped to one carrier rather than every
+     * registered one.
+     */
+    readonly edgesFrom: (from: CarrierAssetNode, to: CarrierAssetNode) => readonly CarrierHopEdge[];
+    /** Asks one of this carrier's own edges. */
+    readonly ask: CarrierAsk;
+    /**
+     * Runs ONE BATCHED set of reads this carrier needs before {@link exact} can
+     * answer synchronously — a local carrier's own fee rate, pool reserves, or
+     * a known limit, read once per search rather than once per candidate hop.
+     * Called at most once per {@link enumerateRoutes} call, before any `exact`
+     * call, over every node the search might branch through; omitted entirely
+     * by a carrier with no local read to batch (every built-in aggregator this
+     * package ships — LI.FI, Relay, NEAR Intents — has none; they answer
+     * through {@link estimate} or a live `ask` instead).
+     *
+     * @param nodes - every node the search might branch through
+     */
+    readonly prepare?: (nodes: readonly CarrierAssetNode[]) => Promise<void>;
+    /**
+     * A SYNCHRONOUS, EXACT answer for one edge at one input amount, read from
+     * whatever {@link prepare} already loaded — never a network call. The
+     * owner's own routing model ("each individual step and its associated fees
+     * can be known ahead of time") is what this method exists to express: a
+     * local carrier whose crossing or swap formula is closed-form given its own
+     * read (the omnibridge crossing, a PulseX swap, a native wrap/unwrap)
+     * answers here instead of estimating. Omitted by every carrier that has no
+     * closed-form answer — an aggregator supplies {@link estimate} instead, or
+     * neither, falling back to a caller-supplied price-feed estimate.
+     *
+     * WHEN THIS IS DEFINED, `enumerate.ts` NEVER FALLS THROUGH TO `estimate` OR
+     * THE PRICE-FEED DEFAULT FOR THIS CARRIER'S EDGES — a hop this method
+     * answers always carries a `'quote'` {@link @gibs/bridge-sdk/routing!HopOutcome},
+     * never an `'estimate'` one, because a carrier that KNOWS its own exact
+     * math has nothing left to estimate.
+     *
+     * @param edge - the candidate hop
+     * @param amountIn - the amount flowing into `edge`, in `edge.from`'s base units
+     * @returns the exact result, or null — see {@link ExactHopResult}'s own doc
+     *   for the difference between its `'refused'` case and a bare `null`
+     */
+    readonly exact?: (edge: CarrierHopEdge, amountIn: bigint) => ExactHopResult | null;
+    /**
+     * A PROVIDER-MODEL estimate for one edge at one input amount — a price
+     * ratio times (one minus this carrier's typical fee) minus a fixed cost,
+     * calibrated against observed history, never a live quote. The aggregator
+     * counterpart to {@link exact}: a carrier with no closed-form crossing
+     * formula (LI.FI, Relay, NEAR Intents) supplies this instead, so
+     * `enumerate.ts` can rank its edges on more than a bare price-feed
+     * conversion without asking the network during enumeration. See
+     * {@link EstimatedHopResult}'s own doc for the `'provider-model'`
+     * {@link @gibs/bridge-sdk/routing!EstimateBasis} every answer here is grounded on.
+     *
+     * RETURNS NULL WHEN THIS CARRIER HAS NOTHING TO SAY, MOST COMMONLY A
+     * MISSING PRICE — a provider-model figure needs both ends of an edge
+     * priced (`@gibs/quotes/carriers/price-catalogue!PriceCatalogue`); a token
+     * neither this carrier's own catalogue nor the search has learned a price
+     * for cannot be estimated, and guessing would rank it on a fabricated
+     * number. `enumerate.ts` reads `null` here exactly as it reads this method
+     * being absent altogether: it falls through to the caller-supplied
+     * price-feed `estimateHopOutput` instead of stopping the search.
+     *
+     * @param edge - the candidate hop
+     * @param amountIn - the amount flowing into `edge`, in `edge.from`'s base units
+     * @returns the modeled result, or null when this carrier cannot estimate this edge right now
+     */
+    readonly estimate?: (edge: CarrierHopEdge, amountIn: bigint) => EstimatedHopResult | null;
+    /**
+     * Whether this carrier competes for a shared, rate-limited network budget,
+     * as opposed to a free local read (an on-chain fee-rate read, a
+     * `getAmountsOut` call). Mirrors `routing/search/graph.ts`'s
+     * `isRateLimitedCarrier`, expressed per-carrier rather than as a lookup
+     * over a fixed set.
+     */
+    readonly isRateLimited: boolean;
+    /**
+     * How many of this carrier's requests may run at once, across every asker
+     * sharing it. Required when {@link isRateLimited} is true; meaningless (and
+     * ignored) for a free local read, which is never funnelled through a
+     * concurrency cap at all.
+     */
+    readonly concurrencyLimit?: number;
+    /** How a reader may fund a section starting with this carrier — see {@link CarrierDepositMode}'s own doc. */
+    readonly depositMode: CarrierDepositMode;
+    /** Which signer a section starting with this carrier uses — see {@link CarrierSender}'s own doc. */
+    readonly sender: CarrierSender;
+    /**
+     * A typical wait, in seconds, for this carrier's own crossing to settle —
+     * used to score a plan before any live quote names a real figure (a live
+     * `ask()` answer's own `claimedDurationSeconds`, when one comes back,
+     * always takes precedence; see `routing/carriers/ask-answer.ts`'s
+     * `CarrierAskAnswer`). Static per carrier, not per edge, because this
+     * package's own route-search maximization runs this figure through scoring
+     * BEFORE any edge is asked — see the owner's own model, "each individual
+     * step and its associated fees can be known ahead of time."
+     */
+    readonly settlementSeconds: number;
+    /**
+     * Whether THIS carrier's own execution, on arrival, also performs the
+     * NEXT hop in the plan — so the two hops together cost the reader only ONE
+     * signature. Mirrors `routing/search/graph.ts`'s `HopEdge.fusesNext`
+     * (which records the OUTCOME of this check for one specific pair of hops)
+     * and the OLD `hopFusesWithBridgeEntry`'s role (which HARD-CODED "the next
+     * hop is the omnibridge entry call" — a fact only gibs's own carriers may
+     * know).
+     *
+     * OMITTED MEANS "NEVER FUSES" — the correct default for every carrier that
+     * does not execute a destination call on arrival (every built-in
+     * aggregator here that merely delivers to the reader's own wallet, and any
+     * free local read with no executor of its own). A carrier that DOES
+     * execute destination calls, and that recognizes a following hop as its
+     * own kind of "entry call," supplies this to decide the two cases: gibs's
+     * own LI.FI/Relay-wrapping registration (`packages/ui/src/lib/state/useRouteSearch.ts`)
+     * is where `'pulsechain'`/`'tokensex'` ever appear in this check — never in
+     * this package.
+     *
+     * @param nextHop - the carrier and destination chain of the hop immediately following this one
+     * @returns whether this hop's signature also covers the next one
+     */
+    readonly fusesWithNext?: (nextHop: CarrierFusesWithNextOptions) => boolean;
+};
+/**
+ * A built-in carrier this library ships: LI.FI, Relay, or NEAR Intents.
+ *
+ * THE SAME THING AS A {@link Carrier}, NOT A SECOND VOCABULARY. Before this
+ * type existed, `bridge-sdk`'s `providers.ts` used `ProviderQuoteContext` to
+ * describe what a provider needs beyond the route request, and the
+ * route-search engine used `AskEdge`/`HopCarrier` to describe the same
+ * question in different words — two names for "something that answers what
+ * an edge delivers." `ProviderAsker` is a plain alias for `Carrier` whose
+ * `id` happens to be a {@link ProviderId}, so a `Carrier & { id: ProviderId }`
+ * and a `ProviderAsker` are interchangeable: a later step's `UpstreamFunnel`
+ * wraps either one identically, and a caller never has to know which kind it
+ * holds.
+ */
+export type ProviderAsker = Carrier & {
+    readonly id: ProviderId;
+};
+/**
+ * Wraps a {@link Carrier}'s own `ask` so every network call it makes passes
+ * through this library's shared guards before it ever reaches `fetch`: the
+ * keyed concurrency limiter and Retry-After cooldown (`quote-guards.ts`), and
+ * the host's `neverSendChainIds` tripwire (`QuoteClientConfig`). One funnel
+ * wraps every carrier a client holds, so the guards govern the WHOLE client
+ * rather than being left to whichever carrier happens to remember to call
+ * them — the same reasoning `routing/search/waves.ts`'s own doc gives for
+ * keeping its concurrency limiter internal rather than trusting each caller
+ * to apply one.
+ *
+ * A FREE CARRIER (`isRateLimited: false`) IS RETURNED UNCHANGED, except for
+ * the chain-guard check, which applies to every carrier — a local read that
+ * happened to be pointed at a guarded chain is exactly as dangerous as a
+ * network call to one.
+ */
+export type UpstreamFunnel = {
+    /**
+     * Wraps one carrier, returning a carrier whose `ask` goes through every
+     * shared guard. The returned carrier's `id`, `edgesFrom` and
+     * `isRateLimited` are unchanged; only `ask` is wrapped.
+     *
+     * @param carrier - the carrier to wrap
+     * @returns a carrier with the same identity, guarded `ask`
+     */
+    readonly wrap: (carrier: Carrier) => Carrier;
+};
+/** One cached display-quote answer, with the bookkeeping needed to compute `ageMs` and `cache` on a later read. */
+export type AnswerCacheEntry = {
+    readonly answer: DisplayProviderSlot;
+    /** Epoch milliseconds this entry was recorded — the basis for `ageMs` and time-to-live expiry. */
+    readonly recordedAtMs: number;
+};
+/**
+ * The display-quote endpoint's shared cache: keyed by
+ * `quote-guards.ts`'s `displayQuoteCacheKey`, single-flight over identical
+ * concurrent requests, least-recently-used eviction around 10,000 entries —
+ * see `docs/quote-service.md`'s "Cache" section for the exact policy a
+ * concrete implementation must follow.
+ */
+export type AnswerCache = {
+    /**
+     * Reads a cached entry, or null when there is none or it has aged out
+     * past the caller-supplied time-to-live for its {@link DisplayProviderSlot}
+     * status (30 s for `quoted`/`no-quote`, 5 s for `could-not-ask`, until the
+     * next chain-list refresh for `cannot-carry`).
+     *
+     * @param key - a {@link displayQuoteCacheKey} result
+     * @returns the entry, or null
+     */
+    readonly get: (key: string) => AnswerCacheEntry | null;
+    /**
+     * Records an answer under `key`, evicting the least-recently-used entry
+     * first when the cache is already at capacity.
+     *
+     * @param key - a {@link displayQuoteCacheKey} result
+     * @param answer - the answer to cache
+     * @param recordedAtMs - when it was recorded
+     */
+    readonly set: (key: string, answer: DisplayProviderSlot, recordedAtMs: number) => void;
+    /**
+     * Runs `task` at most once per `key` among concurrent callers: the first
+     * caller under a key runs `task`; every concurrent caller under the SAME
+     * key joins that one call rather than starting a second. Implements
+     * `docs/quote-service.md`'s "Cache" section: "identical concurrent
+     * requests wait on one upstream call," and "a client disconnect never
+     * cancels the shared call."
+     *
+     * @param key - a {@link displayQuoteCacheKey} result
+     * @param task - the upstream call to make, if nobody else is already making it
+     * @returns the answer, and whether this caller joined another's in-flight
+     *   call rather than starting its own
+     */
+    readonly joinOrRun: (key: string, task: () => Promise<DisplayProviderSlot>) => Promise<{
+        readonly answer: DisplayProviderSlot;
+        readonly joined: boolean;
+    }>;
+};
+/** What a LI.FI carrier needs beyond the route request — every field a host's own, never a default this library supplies. */
+export type LifiProviderConfig = {
+    /** Forwarded as the `x-lifi-api-key` header, when set. */
+    readonly apiKey?: string;
+    /** Forwarded as the `integrator` query parameter LI.FI attributes traffic and referral fees to. */
+    readonly integrator?: string;
+    /** Overrides LI.FI's own API root, for a host proxying it under its own domain. */
+    readonly baseUrl?: string;
+    /** Referral fee as a decimal fraction (e.g. `0.001` = 0.1%), forwarded as `fee` when positive. */
+    readonly fee?: number;
+};
+/** What a Relay carrier needs beyond the route request. */
+export type RelayProviderConfig = {
+    /** Forwarded as the `x-api-key` header, when set. */
+    readonly apiKey?: string;
+    /** Forwarded as `referrer` on every request. */
+    readonly referrer?: string;
+    /** Overrides Relay's own API root. */
+    readonly baseUrl?: string;
+};
+/** What a NEAR Intents carrier needs beyond the route request. */
+export type NearIntentsProviderConfig = {
+    /** Forwarded as `X-API-Key`, when set — NEAR Intents' own partner key. */
+    readonly apiKey?: string;
+    /** Forwarded as `referral` on every quote request. */
+    readonly referral?: string;
+    /** Overrides NEAR Intents' own API root. */
+    readonly baseUrl?: string;
+};
+/** Every built-in carrier's own configuration, all optional — a host wires only the providers it uses. */
+export type QuoteClientProvidersConfig = {
+    readonly lifi?: LifiProviderConfig;
+    readonly relay?: RelayProviderConfig;
+    readonly nearIntents?: NearIntentsProviderConfig;
+};
+/**
+ * How a {@link QuoteClientConfig} behaves when its own `serviceUrl` cannot be
+ * reached: `'direct'` runs the same built-in carriers against the providers
+ * directly (the browser fallback `docs/quote-service.md`'s "Decisions"
+ * section describes); `'none'` surfaces the failure instead of ever calling
+ * a provider straight from this runtime — the right choice for a server that
+ * IS the service, which has no "direct" to fall back to beyond itself.
+ */
+export type QuoteClientFallbackMode = 'direct' | 'none';
+/** A host's own limits, layered over this library's neutral defaults. */
+export type QuoteClientLimitsConfig = {
+    /** Per-carrier in-flight request cap, keyed by {@link CarrierId}. Falls back to the carrier's own `concurrencyLimit` when a carrier is not named here. */
+    readonly concurrencyByCarrier?: Readonly<Record<CarrierId, number>>;
+    /** Overrides `quote-guards.ts`'s `DEFAULT_RETRY_AFTER_COOLDOWN_MS` (30 s). */
+    readonly defaultRetryAfterMs?: number;
+};
+/** A host's own cache sizing, layered over this library's neutral defaults. */
+export type QuoteClientCacheConfig = {
+    /** Overrides the answer time-to-live, in milliseconds, for a `quoted`/`no-quote` entry. */
+    readonly ttlMs?: number;
+    /** Overrides the least-recently-used eviction size (about 10,000 entries by default). */
+    readonly maxEntries?: number;
+};
+/**
+ * The one configuration object a host builds this library's client from.
+ * Nothing about a host — its name, its allowed origins, its chain policy,
+ * its keys — lives anywhere else in this package; it all arrives here.
+ *
+ * THREE MODES, ONE SHAPE. See `docs/quote-service.md`'s "Library" section
+ * for the full description of each:
+ *
+ * - **Backend** — `providers` carries real secrets (`apiKey`s); this config
+ *   builds the same client the display-quote service's server process runs.
+ * - **Frontend, direct** — `providers` carries no secret (or only a public,
+ *   rate-limit-budget identifier, exactly as today's browser bundle already
+ *   does for Relay); `fallback: 'none'` or `serviceUrl` absent, so the
+ *   client calls providers straight from the browser.
+ * - **Frontend, via a service with a fallback** — `serviceUrl` names a host's
+ *   own display-quote service; `fallback: 'direct'` runs the same built-in
+ *   carriers straight from the browser when that service cannot be reached,
+ *   under `providers`' own (public) values.
+ *
+ * @see LifiProviderConfig
+ * @see RelayProviderConfig
+ * @see NearIntentsProviderConfig
+ */
+export type QuoteClientConfig = {
+    /** Every built-in carrier's own configuration. */
+    readonly providers?: QuoteClientProvidersConfig;
+    /** A host's own display-quote service, when this client should prefer it over asking providers directly. */
+    readonly serviceUrl?: string;
+    /** What to do when `serviceUrl` is set but unreachable. Required, so a caller always states its intent rather than inheriting a silent default. */
+    readonly fallback: QuoteClientFallbackMode;
+    /**
+     * A server-held address this host controls, per ecosystem, that a
+     * pre-quote can name as its own recipient without exposing a real user
+     * address — see `docs/quote-service.md`'s "Endpoint" section, "a
+     * server-held probe address." A host supplies one per ecosystem it wants
+     * to quote non-Ethereum origins for; an ecosystem with none configured is
+     * simply not quoted for that origin.
+     */
+    readonly probeAddresses?: Readonly<Partial<Record<Ecosystem, string>>>;
+    /**
+     * Chain ids no request this client builds may ever name, in an address or
+     * a request body, including a forwarding path — the tripwire
+     * `docs/quote-service.md`'s "Rules that never bend" section requires. A
+     * host with no such restriction passes an empty array or omits the field;
+     * this library enforces nothing on its own, because it does not know any
+     * host's chain ids to forbid.
+     */
+    readonly neverSendChainIds?: readonly number[];
+    readonly cache?: QuoteClientCacheConfig;
+    readonly limits?: QuoteClientLimitsConfig;
+    /**
+     * The `fetch` implementation every carrier calls through. Defaults to the
+     * runtime global when omitted; a host — or a test — that needs a
+     * different one (logging, a fixture replay, a Node runtime with no global
+     * fetch) supplies its own. Never imported from `node:*`, so this stays
+     * isomorphic.
+     */
+    readonly fetch?: typeof fetch;
+    /** The clock every time-sensitive guard reads. Defaults to `Date.now` when omitted; a test supplies its own. */
+    readonly now?: () => number;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/upstream.d.ts

@@ -0,0 +1,126 @@
+import type { CarrierId, UpstreamFunnel } from './types.js';
+/**
+ * The single choke point every outbound network call a {@link Carrier} makes
+ * passes through — see `docs/quote-service.md`'s "Carriers" section for the
+ * narrative and `types.ts`'s {@link UpstreamFunnel} for the contract this
+ * module implements.
+ *
+ * TWO LAYERS, BECAUSE `Carrier.ask` HIDES THE WIRE. `UpstreamFunnel.wrap`
+ * only sees a {@link CarrierAskRequest} (an edge and an amount) and a
+ * {@link CarrierAskAnswer} (delivered/refusal) — never a URL, a request body,
+ * or a response header, because that is exactly what makes `Carrier` usable
+ * for a free local read as well as a network call. The guards this module
+ * must enforce — the Retry-After cooldown, the 401-code-1010 breaker, and
+ * the chain tripwire's URL/body scan — all need that wire-level view. So
+ * this module builds it in two pieces:
+ *
+ * - {@link createUpstreamFunnel}'s `wrap` applies the STRUCTURAL guards every
+ *   `Carrier.ask` call can be judged on without touching the network: the
+ *   chain-id tripwire read off the edge itself, the per-carrier concurrency
+ *   cap, and refusing locally while a carrier's cooldown is active.
+ * - Its `guardedFetch` is the WIRE-level guard: every built-in carrier
+ *   (`carriers/lifi.ts`, `carriers/relay.ts`, `carriers/near-intents.ts`)
+ *   must call it — bound to its own {@link CarrierId} — instead of calling
+ *   `fetch` directly. It re-runs the chain tripwire against the actual
+ *   outgoing URL and body (the backstop `docs/quote-service.md` calls for:
+ *   "rejects any 369/943 in the address or body"), records a `429`'s
+ *   `Retry-After` into the SAME cooldown `wrap` reads, and — for `'lifi'`
+ *   only — arms the five-minute breaker on a `401` carrying LI.FI's
+ *   `code: 1010`.
+ *
+ * A caller wires the two together: build the funnel first, construct each
+ * carrier with `(input, init) => funnel.guardedFetch(carrierId, input, init)`
+ * as its `fetchImpl`, THEN call `funnel.wrap(carrier)` on the result. Skipping
+ * either half leaves a real gap — `wrap` alone never sees a 429 to cool down
+ * from, and `guardedFetch` alone never caps concurrency.
+ */
+/** Every built-in carrier's own concurrency cap, unless `concurrencyByCarrier` overrides it. */
+export declare const DEFAULT_CARRIER_CONCURRENCY = 4;
+/** NEAR Intents' own default concurrency cap — see `docs/quote-service.md`'s "Guards" section: "4, NEAR 3." */
+export declare const NEAR_INTENTS_CONCURRENCY = 3;
+/** Per-provider defaults, read when `concurrencyByCarrier` names no override for a carrier. */
+export declare const DEFAULT_CONCURRENCY_BY_CARRIER: Readonly<Record<string, number>>;
+/** How long the LI.FI carrier is refused after a `401` carrying `code: 1010` — five minutes, per `docs/quote-service.md`'s "Cache" section. */
+export declare const LIFI_INVALID_API_KEY_BREAKER_MS: number;
+/**
+ * Thrown by {@link GuardedFetch} BEFORE any network call, when the outgoing
+ * request names a chain id the host listed in `neverSendChainIds` — either in
+ * a query parameter or inside the JSON body, under one of the structured
+ * chain-id field names this module reads (never a raw string search over the
+ * whole request, which would also match an amount or an address that merely
+ * CONTAINS the digits).
+ */
+export declare class NeverSendChainIdError extends Error {
+    readonly chainId: number;
+    readonly carrierId: CarrierId;
+    constructor(chainId: number, carrierId: CarrierId);
+}
+/**
+ * Thrown by {@link GuardedFetch} when a configured provider key would
+ * otherwise appear in the outgoing URL or body — `docs/quote-service.md`'s
+ * rule, "keys go only into headers, never URLs or bodies, never logs,"
+ * enforced rather than merely documented.
+ */
+export declare class KeyLeakError extends Error {
+    readonly carrierId: CarrierId;
+    constructor(carrierId: CarrierId);
+}
+/**
+ * Thrown by {@link GuardedFetch} for `'lifi'` while its five-minute breaker
+ * is active — see {@link LIFI_INVALID_API_KEY_BREAKER_MS}. Never thrown for
+ * any other carrier; only LI.FI answers a rejected key with a 401 this
+ * module can classify (`isLifiInvalidApiKeyResponse`).
+ */
+export declare class LifiApiKeyBreakerActiveError extends Error {
+    constructor();
+}
+/**
+ * A `fetch` every built-in carrier's own network call must go through,
+ * keyed by which carrier is calling — see this module's head note for why a
+ * carrier id, rather than a plain `typeof fetch`, is required here.
+ */
+export type GuardedFetch = (carrierId: CarrierId, input: string | URL, init?: RequestInit) => Promise<Response>;
+export type CreateUpstreamFunnelOptions = {
+    /** Chain ids no request this funnel guards may ever name — see `QuoteClientConfig.neverSendChainIds`. */
+    readonly neverSendChainIds?: readonly number[];
+    /** Every configured provider key, checked against the outgoing URL and body so a key never travels anywhere but a header. */
+    readonly keys?: readonly string[];
+    /** Per-carrier in-flight cap, overriding {@link DEFAULT_CONCURRENCY_BY_CARRIER}. */
+    readonly concurrencyByCarrier?: Readonly<Record<CarrierId, number>>;
+    /** Overrides `quote-guards.ts`'s `DEFAULT_RETRY_AFTER_COOLDOWN_MS` for a carrier's own Retry-After cooldown. */
+    readonly defaultRetryAfterMs?: number;
+    /**
+     * How long, from the moment an `ask` call is queued, it may wait for a
+     * concurrency slot before {@link createUpstreamFunnel}'s `wrap` answers
+     * `could-not-ask: busy` instead. Omitted waits indefinitely, matching
+     * `KeyedConcurrencyLimiter.run`'s own default.
+     */
+    readonly askDeadlineMs?: number;
+    readonly fetch?: typeof fetch;
+    readonly now?: () => number;
+};
+/** {@link UpstreamFunnel}, widened with the wire-level {@link GuardedFetch} every built-in carrier is constructed with. */
+export type QuoteUpstreamFunnel = UpstreamFunnel & {
+    readonly guardedFetch: GuardedFetch;
+    /**
+     * Total `429` responses `guardedFetch` has seen across every carrier since
+     * this funnel was built — the figure `/stats`'s `rateLimited429s` reports,
+     * per `docs/quote-service.md`'s "Endpoint" section. Counts the response,
+     * not the cooldown it starts, so a burst of calls that all land during one
+     * already-active cooldown (refused locally by `wrap`, never reaching
+     * `guardedFetch`) does not inflate it.
+     */
+    readonly rateLimited429Count: () => number;
+    /** Every carrier's own queued-task count, summed — see `quote-guards.ts`'s `KeyedConcurrencyLimiter.queueDepth`. */
+    readonly queueDepth: () => number;
+};
+/**
+ * Builds the funnel every carrier's `ask` — built-in or host-registered —
+ * should be wrapped through, and the wire-level {@link GuardedFetch} every
+ * built-in carrier's own HTTP call should go through. See this module's
+ * head note for how the two fit together.
+ *
+ * @param options - see {@link CreateUpstreamFunnelOptions}
+ * @returns the funnel
+ */
+export declare const createUpstreamFunnel: (options?: CreateUpstreamFunnelOptions) => QuoteUpstreamFunnel;