@waterx/sdk 3.1.0 → 4.0.0

package/dist/src/oracle/rules/pyth-core-rule.js

@@ -0,0 +1,81 @@
+/**
+ * `PythCoreRule` — `PriceUpdateRule` wrapper around the existing Pyth Core
+ * (Hermes VAA) source in `../pyth.ts`. Delegates to `fetchPriceFeedsUpdateData`
+ * / `buildPythPriceUpdateCalls` verbatim; this file only adapts them to the
+ * `PriceUpdateRule` port shape (fetch → build) so a future router can select
+ * across rules by `kind`. Mechanical wrap only — no on-chain/off-chain logic
+ * changes vs `../pyth.ts` / `./pyth-rule.ts`.
+ */
+import { assertRuleUpdateData, } from "../price-update-rule.js";
+import { buildPythPriceUpdateCalls, fetchPriceFeedsUpdateData } from "../pyth.js";
+/**
+ * Shape check ONLY — the `kind` discriminant is checked separately by the
+ * caller before this runs, since a same-shaped payload from a different rule
+ * (e.g. a hypothetical Lazer payload also carrying `updates`/`feedIds`) must
+ * not silently pass as a Pyth Core VAA block.
+ */
+function isPythCoreUpdatePayloadShape(payload) {
+    return (typeof payload === "object" &&
+        payload !== null &&
+        Array.isArray(payload.updates) &&
+        Array.isArray(payload.feedIds));
+}
+export const PythCoreRule = {
+    kind: "pyth_rule",
+    // Charges a per-feed `base_update_fee` via `pyth::update_single_price_feed` —
+    // see `PriceUpdateRule.requiresFeeSource`.
+    requiresFeeSource: true,
+    /** Tickers with a `pyth_rule.feeds` entry (mirrors `refreshOraclePrices`'s filter). */
+    supportedTickers(host) {
+        return Object.keys(host.config.packages.pyth_rule?.feeds ?? {});
+    },
+    /** Resolves feed ids for `tickers`, then fetches their Hermes accumulator update. */
+    async fetchUpdateData(host, tickers) {
+        if (tickers.length === 0)
+            return null;
+        const feedIds = tickers.map((ticker) => host.getPythFeed(ticker).feed_id);
+        const updates = await fetchPriceFeedsUpdateData(host.pyth.hermes_endpoint, feedIds, {
+            apiKey: host.pyth.api_key,
+            fetch: host.pyth.fetch,
+        });
+        return { kind: "pyth_rule", payload: { updates, feedIds } };
+    },
+    /**
+     * Subsets a (typically whole-universe) payload from {@link fetchUpdateData}
+     * down to exactly `tickers`. Pyth Core charges a per-feed update fee (one
+     * `update_single_price_feed` moveCall per `feedIds` entry — see
+     * `buildPythPriceUpdateCalls`), so serving a full all-registry payload for a
+     * 2-ticker build would multiply both the fee and the PTB size ~N× — a
+     * per-feed subset is valid input by construction. Narrows `feedIds` only:
+     * the single combined Hermes accumulator blob in `updates` already covers
+     * every packed feed and needs no re-slicing. A ticker with no
+     * `pyth_rule.feeds` entry, or whose feed id is not packed in THIS payload's
+     * `feedIds`, is a coverage gap → `null` (miss), never a silent partial.
+     */
+    narrowUpdateData(host, data, tickers) {
+        const payload = assertRuleUpdateData(data, "pyth_rule", isPythCoreUpdatePayloadShape, "{ updates: Uint8Array[]; feedIds: string[] }");
+        if (!payload || tickers.length === 0)
+            return null;
+        const packedFeedIds = new Set(payload.feedIds);
+        const feedIds = [];
+        for (const ticker of tickers) {
+            // Same lookup as `host.getPythFeed(ticker)` minus its throw — an
+            // unlisted ticker is a miss here, not an error.
+            const feedId = host.config.packages.pyth_rule?.feeds?.[ticker]?.feed_id;
+            if (feedId === undefined || !packedFeedIds.has(feedId))
+                return null;
+            feedIds.push(feedId);
+        }
+        return { kind: "pyth_rule", payload: { updates: payload.updates, feedIds } };
+    },
+    /** Appends the wormhole/pyth update PTB block for the payload from {@link fetchUpdateData}. */
+    async buildUpdateCalls(tx, host, data, opts) {
+        const payload = assertRuleUpdateData(data, "pyth_rule", isPythCoreUpdatePayloadShape, "{ updates: Uint8Array[]; feedIds: string[] }");
+        if (!payload)
+            return;
+        await buildPythPriceUpdateCalls(tx, host, payload.updates, payload.feedIds, {
+            cache: opts?.cache,
+            feeSource: opts?.feeSource,
+        });
+    },
+};

package/dist/src/oracle/rules/pyth-lazer-rule.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `PythLazerRule` — `PriceUpdateRule` for Pyth Lazer (Pyth Pro) signed
+ * updates, plus `feedLazerRule`, the collector-feed leg `aggregateTicker`
+ * appends per lazer-routed ticker. Fetches one `leEcdsa` payload for all
+ * requested integer feed ids from the Lazer HTTP API (Bearer-authenticated
+ * via `config.pyth.api_key`), verifies it ONCE on-chain via
+ * `pyth_lazer::parse_and_verify_le_ecdsa_update`, and hands the resulting
+ * `Update` PTB value back through a `RuleUpdateHandle` for the feed calls.
+ */
+import type { Transaction, TransactionArgument } from "@mysten/sui/transactions";
+import type { OracleHost } from "../host.ts";
+import { type PriceUpdateRule } from "../price-update-rule.ts";
+/** `pyth_lazer_rule`'s narrowed `RuleUpdateData.payload` shape. */
+export interface PythLazerUpdatePayload {
+    /** One signed `leEcdsa` message carrying every requested feed. */
+    readonly update: Uint8Array;
+    /** Integer Lazer feed ids the update was requested for (debug/audit trail). */
+    readonly feedIds: number[];
+}
+/**
+ * Thrown by {@link PythLazerRule.fetchUpdateData} when `pyth_lazer_rule` is
+ * deployed in config but no `pyth.api_key` is set — the Lazer HTTP API
+ * requires a Bearer token and the SDK never reads `process.env` to find one.
+ * `instanceof`-able (mirrors `OracleFeeSourceUnavailableError` in `pyth.ts`)
+ * so a consumer can branch on the failure type directly instead of
+ * string-matching `error.message`.
+ */
+export declare class LazerApiKeyMissingError extends Error {
+    constructor();
+}
+/**
+ * `pyth_lazer_rule::feed(collector, config, clock, &update)` — contribute the
+ * verified Lazer price for `collector.symbol()` to the collector. `update` is
+ * the `RuleUpdateHandle` value from {@link PythLazerRule.buildUpdateCalls} in
+ * the SAME PTB; one verified update serves every ticker's feed call. On-chain
+ * the rule abstains (records `none`) instead of aborting when the symbol is
+ * unconfigured, the feed is absent from the update, the value is degenerate,
+ * or the Lazer timestamp is stale.
+ */
+export declare function feedLazerRule(tx: Transaction, host: OracleHost, collector: TransactionArgument, update: TransactionArgument): void;
+export declare const PythLazerRule: PriceUpdateRule;

package/dist/src/oracle/rules/pyth-lazer-rule.js

@@ -0,0 +1,189 @@
+/**
+ * `PythLazerRule` — `PriceUpdateRule` for Pyth Lazer (Pyth Pro) signed
+ * updates, plus `feedLazerRule`, the collector-feed leg `aggregateTicker`
+ * appends per lazer-routed ticker. Fetches one `leEcdsa` payload for all
+ * requested integer feed ids from the Lazer HTTP API (Bearer-authenticated
+ * via `config.pyth.api_key`), verifies it ONCE on-chain via
+ * `pyth_lazer::parse_and_verify_le_ecdsa_update`, and hands the resulting
+ * `Update` PTB value back through a `RuleUpdateHandle` for the feed calls.
+ */
+import { fromHex } from "@mysten/bcs";
+import { LAZER_DEFAULTS } from "../config.js";
+import { assertRuleUpdateData, } from "../price-update-rule.js";
+import { FetchPolicyError, fetchWithPolicy } from "../update-fetch.js";
+/**
+ * Signed-update request pins, mirroring what the on-chain rule consumes:
+ * - `properties` — `price` + `exponent` are REQUIRED by
+ *   `pyth_lazer_rule::price_or_abstain` (a missing exponent abstains);
+ *   `confidence` is optional on-chain but requested so the rule's
+ *   fail-closed confidence gate actually engages (a payload without
+ *   confidence passes the gate unchecked).
+ * - `channel` — `real_time`: the deployed rule binds the v1 Lazer API, whose
+ *   `channel::from_u8` aborts on the 1000ms fixed-rate channel; real_time /
+ *   50ms / 200ms are the safe subscriptions, and for an on-demand pull
+ *   real_time is the freshest.
+ * - `formats: leEcdsa` + `jsonBinaryEncoding: hex` — the Sui verifier takes
+ *   the `leEcdsa` framing; hex matches `fromHex` below.
+ */
+const LAZER_LATEST_PRICE_REQUEST = {
+    properties: ["price", "exponent", "confidence"],
+    formats: ["leEcdsa"],
+    jsonBinaryEncoding: "hex",
+    channel: "real_time",
+};
+/**
+ * Shape check ONLY — the `kind` discriminant is checked separately by the
+ * caller before this runs (mirrors `PythCoreRule`'s guard split), so a
+ * same-shaped payload from a different rule can never silently pass.
+ */
+function isPythLazerUpdatePayloadShape(payload) {
+    return (typeof payload === "object" &&
+        payload !== null &&
+        payload.update instanceof Uint8Array &&
+        Array.isArray(payload.feedIds));
+}
+/**
+ * Thrown by {@link PythLazerRule.fetchUpdateData} when `pyth_lazer_rule` is
+ * deployed in config but no `pyth.api_key` is set — the Lazer HTTP API
+ * requires a Bearer token and the SDK never reads `process.env` to find one.
+ * `instanceof`-able (mirrors `OracleFeeSourceUnavailableError` in `pyth.ts`)
+ * so a consumer can branch on the failure type directly instead of
+ * string-matching `error.message`.
+ */
+export class LazerApiKeyMissingError extends Error {
+    constructor() {
+        super("LazerApiKeyMissing: pyth_lazer_rule requires a Pyth Lazer access token — " +
+            "set `pyth.api_key` in the client config (the SDK never reads process.env)");
+        this.name = "LazerApiKeyMissingError";
+    }
+}
+/** The `pyth_lazer_rule` deployment entry; throws when the config carries none. */
+function requireLazerPackage(host) {
+    const entry = host.config.packages.pyth_lazer_rule;
+    if (!entry) {
+        throw new Error("pyth_lazer_rule package is not deployed in this config");
+    }
+    return entry;
+}
+/**
+ * Fetch one signed `leEcdsa` update for `feedIds` from the Lazer HTTP API.
+ * Goes through the shared `fetchWithPolicy` (`../update-fetch.ts`) — same
+ * retry/timeout/Bearer policy as `fetchPriceFeedsUpdateData`, unified so
+ * both oracle sources fail the same way under upstream degradation.
+ */
+async function fetchLazerSignedUpdate(endpoint, apiKey, feedIds, fetchOpts) {
+    const url = new URL("/v1/latest_price", endpoint);
+    let res;
+    try {
+        res = await fetchWithPolicy(url.toString(), {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ priceFeedIds: feedIds, ...LAZER_LATEST_PRICE_REQUEST }),
+        }, { apiKey, ...fetchOpts });
+    }
+    catch (err) {
+        // Mirrors fetchPriceFeedsUpdateData's reframing: a retryable status that
+        // never recovered carries `status` on the FetchPolicyError — reformat
+        // into this function's own message shape; a network-level exhaustion
+        // (no status) propagates as-is.
+        if (err instanceof FetchPolicyError && err.status !== undefined) {
+            const body = err.bodySnippet ? ` ${err.bodySnippet}` : "";
+            throw new Error(`Lazer price fetch failed: ${err.status}${body} (retries exhausted after ${err.attempts} attempts)`, { cause: err });
+        }
+        throw err;
+    }
+    if (!res.ok)
+        throw new Error(`Lazer price fetch failed: ${res.status} ${await res.text()}`);
+    const json = (await res.json());
+    const hex = json.leEcdsa?.data;
+    if (typeof hex !== "string" || hex.length === 0) {
+        throw new Error("Lazer returned no leEcdsa update data");
+    }
+    return fromHex(hex);
+}
+/**
+ * `pyth_lazer_rule::feed(collector, config, clock, &update)` — contribute the
+ * verified Lazer price for `collector.symbol()` to the collector. `update` is
+ * the `RuleUpdateHandle` value from {@link PythLazerRule.buildUpdateCalls} in
+ * the SAME PTB; one verified update serves every ticker's feed call. On-chain
+ * the rule abstains (records `none`) instead of aborting when the symbol is
+ * unconfigured, the feed is absent from the update, the value is degenerate,
+ * or the Lazer timestamp is stale.
+ */
+export function feedLazerRule(tx, host, collector, update) {
+    const lazer = requireLazerPackage(host);
+    tx.moveCall({
+        target: `${lazer.published_at}::pyth_lazer_rule::feed`,
+        arguments: [collector, tx.object(lazer.config), tx.object.clock(), update],
+    });
+}
+export const PythLazerRule = {
+    kind: "pyth_lazer_rule",
+    // Verification is a flat signature check with no Coin argument — no
+    // update fee — see `PriceUpdateRule.requiresFeeSource`.
+    requiresFeeSource: false,
+    /** Tickers with a `pyth_lazer_rule.feeds` entry (integer Lazer feed ids). */
+    supportedTickers(host) {
+        return Object.keys(host.config.packages.pyth_lazer_rule?.feeds ?? {});
+    },
+    /** Resolves integer feed ids for `tickers`, then fetches one signed `leEcdsa` update. */
+    async fetchUpdateData(host, tickers) {
+        if (tickers.length === 0)
+            return null;
+        // Package-level check first: a config without the deployment must say so,
+        // not fail per ticker as if only that feed were missing.
+        const { feeds } = requireLazerPackage(host);
+        const feedIds = tickers.map((ticker) => {
+            const feedId = feeds[ticker];
+            if (feedId === undefined) {
+                throw new Error(`No pyth_lazer_rule feed listed for ticker: ${ticker}`);
+            }
+            return feedId;
+        });
+        const apiKey = host.pyth.api_key;
+        if (!apiKey) {
+            throw new LazerApiKeyMissingError();
+        }
+        const update = await fetchLazerSignedUpdate(LAZER_DEFAULTS[host.network].endpoint, apiKey, feedIds, host.pyth.fetch);
+        return { kind: "pyth_lazer_rule", payload: { update, feedIds } };
+    },
+    /**
+     * A Lazer payload is ONE signed `leEcdsa` message covering every feed it was
+     * fetched for — verification is a single flat signature check over the whole
+     * message (`parse_and_verify_le_ecdsa_update`, no per-feed cost), so the
+     * payload is indivisible: it can only be served whole. Returns the whole
+     * payload iff every requested ticker's integer feed id is packed in THIS
+     * payload's `feedIds`; any coverage gap (unlisted ticker, or a feed this
+     * payload does not carry) → `null` (miss), never a silent partial.
+     */
+    narrowUpdateData(host, data, tickers) {
+        const payload = assertRuleUpdateData(data, "pyth_lazer_rule", isPythLazerUpdatePayloadShape, "{ update: Uint8Array; feedIds: number[] }");
+        if (!payload || tickers.length === 0)
+            return null;
+        const packedFeedIds = new Set(payload.feedIds);
+        for (const ticker of tickers) {
+            const feedId = host.config.packages.pyth_lazer_rule?.feeds?.[ticker];
+            if (feedId === undefined || !packedFeedIds.has(feedId))
+                return null;
+        }
+        return { kind: "pyth_lazer_rule", payload };
+    },
+    /**
+     * Appends the single `parse_and_verify_le_ecdsa_update(state, clock, bytes)`
+     * call — one secp256k1 signature check covering every feed in the payload —
+     * and returns its `Update` result as the handle the per-ticker feed leg
+     * consumes. `opts.cache` / `opts.feeSource` are Pyth-Core-specific and
+     * ignored (Lazer verification charges no update fee).
+     */
+    buildUpdateCalls(tx, host, data, _opts) {
+        const payload = assertRuleUpdateData(data, "pyth_lazer_rule", isPythLazerUpdatePayloadShape, "{ update: Uint8Array; feedIds: number[] }");
+        if (!payload)
+            return undefined;
+        const lazer = requireLazerPackage(host);
+        const [update] = tx.moveCall({
+            target: `${LAZER_DEFAULTS[host.network].verifier_package}::pyth_lazer::parse_and_verify_le_ecdsa_update`,
+            arguments: [tx.object(lazer.state), tx.object.clock(), tx.pure.vector("u8", payload.update)],
+        });
+        return { kind: "pyth_lazer_rule", update };
+    },
+};

package/dist/src/oracle/rules/sponsor.d.ts

@@ -3,17 +3,21 @@
  * attach the `PythSponsorRule` witness to a `TradingRequest`. Required when the
  * market's `request_checklist` contains `PythSponsorRule`.
  *
- * Flow: {@link openPythSponsorFund} opens a `Fund` hot potato; pass the returned
- * `{ fund, packageId }` to the Pyth update path as its `sponsorFund` (it draws
- * per-feed fees via `pyth_sponsor_rule::split`); then {@link reimbursePythSponsor}
- * consumes the `Fund`, returns leftover SUI, and attaches the witness.
+ * Flow: {@link openPythSponsorFund} opens a `Fund` hot potato; the caller wraps
+ * the returned `{ fund, packageId }` into an `OracleFeeSource` (`{ kind:
+ * 'sponsor', fund, packageId }`) and passes that to the Pyth update path (it
+ * draws per-feed fees via `pyth_sponsor_rule::split`); then
+ * {@link reimbursePythSponsor} consumes the `Fund`, returns leftover SUI, and
+ * attaches the witness.
  */
 import type { Transaction, TransactionArgument } from "@mysten/sui/transactions";
 import type { OracleHost } from "../host.ts";
 /**
- * Opens a `Fund` hot potato from the shared PythSponsor pool. Pass the returned
- * `{ fund, packageId }` straight to `refreshOraclePrices` as `sponsorFund`, then
- * {@link reimbursePythSponsor} once the TradingRequest is built.
+ * Opens a `Fund` hot potato from the shared PythSponsor pool. Wrap the
+ * returned `{ fund, packageId }` into an `OracleFeeSource`
+ * (`{ kind: 'sponsor', fund, packageId }`) and pass that to
+ * `refreshOraclePrices` as `feeSource`, then {@link reimbursePythSponsor} once
+ * the TradingRequest is built.
  */
 export declare function openPythSponsorFund(tx: Transaction, host: OracleHost): {
     fund: TransactionArgument;

package/dist/src/oracle/rules/sponsor.js

@@ -3,16 +3,20 @@
  * attach the `PythSponsorRule` witness to a `TradingRequest`. Required when the
  * market's `request_checklist` contains `PythSponsorRule`.
  *
- * Flow: {@link openPythSponsorFund} opens a `Fund` hot potato; pass the returned
- * `{ fund, packageId }` to the Pyth update path as its `sponsorFund` (it draws
- * per-feed fees via `pyth_sponsor_rule::split`); then {@link reimbursePythSponsor}
- * consumes the `Fund`, returns leftover SUI, and attaches the witness.
+ * Flow: {@link openPythSponsorFund} opens a `Fund` hot potato; the caller wraps
+ * the returned `{ fund, packageId }` into an `OracleFeeSource` (`{ kind:
+ * 'sponsor', fund, packageId }`) and passes that to the Pyth update path (it
+ * draws per-feed fees via `pyth_sponsor_rule::split`); then
+ * {@link reimbursePythSponsor} consumes the `Fund`, returns leftover SUI, and
+ * attaches the witness.
  */
 import { reimburse as sponsorReimburse, request as sponsorRequest, } from "../../generated/pyth_sponsor_rule/pyth_sponsor_rule.js";
 /**
- * Opens a `Fund` hot potato from the shared PythSponsor pool. Pass the returned
- * `{ fund, packageId }` straight to `refreshOraclePrices` as `sponsorFund`, then
- * {@link reimbursePythSponsor} once the TradingRequest is built.
+ * Opens a `Fund` hot potato from the shared PythSponsor pool. Wrap the
+ * returned `{ fund, packageId }` into an `OracleFeeSource`
+ * (`{ kind: 'sponsor', fund, packageId }`) and pass that to
+ * `refreshOraclePrices` as `feeSource`, then {@link reimbursePythSponsor} once
+ * the TradingRequest is built.
  */
 export function openPythSponsorFund(tx, host) {
     const entry = host.config.packages.pyth_sponsor_rule;

package/dist/src/oracle/update-fetch.d.ts

@@ -0,0 +1,85 @@
+/**
+ * `fetchWithPolicy` — resilience wrapper around `fetch` for the oracle money
+ * path's off-chain update-data fetches. Every order/position/collateral
+ * tx-build depends on one of these REST calls landing (Hermes VAA for
+ * `pyth_rule`, Lazer signed updates for `pyth_lazer_rule`); a bare `fetch`
+ * with a single attempt and no retry means one Hermes 429/5xx or timeout
+ * fails every trade. `fetchPriceFeedsUpdateData` (`./pyth.ts`),
+ * `PythLazerRule.fetchUpdateData`'s Lazer POST (`./rules/pyth-lazer-rule.ts`),
+ * and `loadConfig` (`../perp/config.ts`) all delegate here instead of calling
+ * `fetch` directly — this is the ONE place a retry/timeout/auth policy is
+ * implemented for these fetches.
+ *
+ * Policy semantics:
+ * - Bearer auth is attached iff `policy.apiKey` is a non-empty string —
+ *   absent/empty is byte-identical to today's keyless request (no
+ *   `Authorization` header at all). This is the Phase-0 invariant of the
+ *   Pyth Pro migration: existing keyless deployments see no behavior change.
+ * - Retries on network errors, HTTP 429, and HTTP 5xx, with exponential
+ *   backoff (`retryDelayMs * 2^attempt`, capped at `MAX_BACKOFF_MS`). Other
+ *   4xx statuses (401/400/403/404/…) are NOT retried — auth/bad-request
+ *   failures are deterministic, so that `Response` (`ok: false`) is handed
+ *   back on the first attempt for the caller to format its own
+ *   domain-specific error, exactly as it did before this wrapper existed.
+ * - `init.body`, if set, MUST be replayable across attempts — a retry
+ *   re-sends the SAME `init` object to `fetch` on every attempt. A string /
+ *   `URLSearchParams` / BCS-serialized `Uint8Array` body (every caller today)
+ *   is fine; a one-shot `ReadableStream` body would not survive a second
+ *   attempt and must not be passed through this function.
+ * - Each attempt gets its own `AbortSignal.timeout(policy.timeoutMs)`
+ *   combined with whichever of `init.signal` / the `externalSignal` param are
+ *   set — ALL of them can end the whole policy (not just the in-flight
+ *   attempt), including a queued backoff sleep, via `AbortSignal.any`
+ *   (runtime floor: Node ≥20.3 / any modern browser — matches this repo's
+ *   `target: ES2023` + `lib: ["dom", "esnext"]`).
+ * - Exhausting retries with no successful/non-retryable response (i.e. every
+ *   attempt was a network error, or the final attempt was still a retryable
+ *   HTTP failure) throws a {@link FetchPolicyError} naming the target's
+ *   `host + pathname` (never the query string — feed ids are off-chain
+ *   noise, not diagnostic value), the attempt count, and whichever of
+ *   `status` (a retryable HTTP failure — plus a truncated response-body
+ *   snippet, when the final attempt's response carried one) or `cause` (a
+ *   network error) the final attempt produced. An INTERMEDIATE (non-final)
+ *   retryable response's body is discarded via `response.body?.cancel()`
+ *   instead of read, so a doomed-to-retry response doesn't pin its
+ *   connection's socket open for no reason.
+ * - Retry worst case: with the defaults (15s timeout × 3 attempts + ~0.75s of
+ *   backoff between them) a FULL outage takes up to ~46s to surface as a
+ *   `FetchPolicyError`, vs ~15s pre-3.2.0's single bare-`fetch` attempt.
+ *   Tunable per client via `config.pyth.fetch.{timeoutMs,retries}`.
+ */
+export interface FetchPolicy {
+    /** Per-attempt timeout (ms). Default 15_000. */
+    readonly timeoutMs?: number;
+    /** Retry attempts AFTER the first try — `retries: 2` ⇒ 3 attempts total. Default 2. */
+    readonly retries?: number;
+    /** Base backoff (ms); doubled per attempt, capped at 2_000ms. Default 250. */
+    readonly retryDelayMs?: number;
+    /** Bearer token. Attached iff non-empty; empty/missing ⇒ no `Authorization` header. */
+    readonly apiKey?: string;
+    /** Override the fetch implementation (tests / non-global-`fetch` environments). Default: global `fetch`. */
+    readonly fetchImpl?: typeof fetch;
+}
+/** Thrown by {@link fetchWithPolicy} when every attempt failed. */
+export declare class FetchPolicyError extends Error {
+    /** HTTP status of the final attempt, when it got a (retryable-but-failing) response. */
+    readonly status?: number;
+    /** Truncated (~200 char) body of the final attempt's response, when one was readable. */
+    readonly bodySnippet?: string;
+    /** Total attempts made (first try + retries actually used). */
+    readonly attempts: number;
+    constructor(message: string, opts: {
+        status?: number;
+        bodySnippet?: string;
+        cause?: unknown;
+        attempts: number;
+    });
+}
+/**
+ * `fetch` with per-attempt timeout, bounded retry + backoff, and optional
+ * Bearer auth. See the module header for the full policy. Both `init.signal`
+ * (if the caller set one) AND the separate `externalSignal` param cancel the
+ * WHOLE policy — in-flight attempts AND queued backoff sleeps — not just a
+ * single attempt.
+ */
+export declare function fetchWithPolicy(url: string, init?: RequestInit, policy?: FetchPolicy, externalSignal?: AbortSignal): Promise<Response>;