gloomberb 0.4.0 → 0.5.0

package/src/utils/market-format.ts

@@ -0,0 +1,299 @@
+import { formatCurrency } from "./format";
+
+export type AssetDisplayKind = "cash" | "crypto" | "equity" | "contract" | "other";
+
+export interface AssetDisplayContext {
+  isCashBalance?: boolean;
+  assetCategory?: string;
+  contractSecType?: string;
+  multiplier?: number;
+}
+
+export interface MarketFormatOptions extends AssetDisplayContext {
+  maxWidth?: number;
+  minimumFractionDigits?: number;
+  precisionOffset?: number;
+  priceRange?: number;
+  fixedFractionDigits?: number;
+}
+
+const CASH_TYPES = new Set(["CASH", "FX", "FOREX", "CCY", "CURRENCY", "CURRENCYPAIR"]);
+const CRYPTO_TYPES = new Set(["CRYPTO", "CRYPTOCURRENCY", "COIN", "TOKEN"]);
+const EQUITY_TYPES = new Set(["STK", "STOCK", "EQUITY", "ETF", "ETN", "ETP", "FUND", "MUTUALFUND", "CEF", "ADR"]);
+const CONTRACT_TYPES = new Set(["OPT", "OPTION", "OPTIONS", "FUT", "FUTURE", "FUTURES", "FOP"]);
+
+const currencySymbols = new Map<string, string>();
+const numberFormatters = new Map<string, Intl.NumberFormat>();
+
+function normalizeType(value?: string): string {
+  return (value ?? "").trim().toUpperCase().replace(/[\s_-]+/g, "");
+}
+
+function getNumberFormatter(
+  minimumFractionDigits: number,
+  maximumFractionDigits: number,
+  useGrouping: boolean,
+): Intl.NumberFormat {
+  const key = `${minimumFractionDigits}:${maximumFractionDigits}:${useGrouping ? 1 : 0}`;
+  let formatter = numberFormatters.get(key);
+  if (!formatter) {
+    formatter = new Intl.NumberFormat("en-US", {
+      minimumFractionDigits,
+      maximumFractionDigits,
+      useGrouping,
+    });
+    numberFormatters.set(key, formatter);
+  }
+  return formatter;
+}
+
+function getCurrencySymbol(currency: string): string {
+  const normalizedCurrency = currency.trim().toUpperCase() || "USD";
+  const cached = currencySymbols.get(normalizedCurrency);
+  if (cached) return cached;
+
+  const formatter = new Intl.NumberFormat("en-US", {
+    style: "currency",
+    currency: normalizedCurrency,
+    currencyDisplay: "symbol",
+    minimumFractionDigits: 0,
+    maximumFractionDigits: 0,
+  });
+  const symbol = formatter.formatToParts(0).find((part) => part.type === "currency")?.value ?? normalizedCurrency;
+  currencySymbols.set(normalizedCurrency, symbol);
+  return symbol;
+}
+
+function fitsWidth(text: string, maxWidth: number | undefined): boolean {
+  return maxWidth == null || text.length <= maxWidth;
+}
+
+function isEffectivelyInteger(value: number): boolean {
+  return Math.abs(value - Math.round(value)) < 1e-9;
+}
+
+function formatVariableNumber(
+  value: number,
+  maxFractionDigits: number,
+  maxWidth: number | undefined,
+  minimumFractionDigits = 0,
+): string {
+  const groupedModes = [true, false];
+
+  for (const useGrouping of groupedModes) {
+    for (let decimals = maxFractionDigits; decimals >= minimumFractionDigits; decimals -= 1) {
+      const formatter = getNumberFormatter(Math.min(minimumFractionDigits, decimals), decimals, useGrouping);
+      const formatted = formatter.format(value);
+      if (fitsWidth(formatted, maxWidth)) return formatted;
+    }
+  }
+
+  return getNumberFormatter(0, 0, false).format(value);
+}
+
+function getQuantityMaxFractionDigits(kind: AssetDisplayKind, value: number): number {
+  if (isEffectivelyInteger(value)) return 0;
+
+  switch (kind) {
+    case "cash":
+      return 6;
+    case "crypto":
+      return 8;
+    case "equity":
+      return 4;
+    case "contract":
+      return 4;
+    case "other":
+    default:
+      return 4;
+  }
+}
+
+function getBasePriceMaxFractionDigits(kind: AssetDisplayKind, value: number): number {
+  switch (kind) {
+    case "cash":
+      return 6;
+    case "crypto":
+      return 8;
+    case "equity":
+      return Math.abs(value) >= 1 ? 2 : 4;
+    case "contract":
+      return 4;
+    case "other":
+    default:
+      return Math.abs(value) >= 1 ? 2 : 4;
+  }
+}
+
+function getAdaptivePriceFractionDigits(priceRange: number | undefined, precisionOffset = 0): number | null {
+  if (priceRange === undefined || !Number.isFinite(priceRange) || priceRange <= 0) return null;
+
+  // The chart price axis renders four labels by default, so the visible range
+  // divided across three intervals is a good proxy for the current zoom step.
+  const visibleStep = priceRange / 3;
+  if (!Number.isFinite(visibleStep) || visibleStep <= 0) return null;
+
+  return Math.max(0, Math.ceil(-Math.log10(visibleStep)) + precisionOffset);
+}
+
+function getPriceMaxFractionDigits(
+  kind: AssetDisplayKind,
+  value: number,
+  priceRange: number | undefined,
+  precisionOffset: number,
+): number {
+  const baseMaxFractionDigits = kind === "other" && priceRange !== undefined
+    ? 6
+    : getBasePriceMaxFractionDigits(kind, value);
+  const adaptiveFractionDigits = getAdaptivePriceFractionDigits(priceRange, precisionOffset);
+  return adaptiveFractionDigits === null
+    ? baseMaxFractionDigits
+    : Math.min(baseMaxFractionDigits, adaptiveFractionDigits);
+}
+
+function getCostMaxFractionDigits(kind: AssetDisplayKind): number {
+  switch (kind) {
+    case "cash":
+      return 6;
+    case "crypto":
+      return 8;
+    case "contract":
+      return 4;
+    case "equity":
+      return 2;
+    case "other":
+    default:
+      return 2;
+  }
+}
+
+function compactScaledPrice(
+  value: number,
+  divisor: number,
+  suffix: string,
+  currency: string,
+  maxWidth: number | undefined,
+): string {
+  const sign = value < 0 ? "-" : "";
+  const symbol = getCurrencySymbol(currency);
+  const numericWidth = maxWidth == null
+    ? undefined
+    : Math.max(1, maxWidth - sign.length - symbol.length - suffix.length);
+  const formatted = formatVariableNumber(Math.abs(value) / divisor, 1, numericWidth, 1);
+  return `${sign}${symbol}${formatted}${suffix}`;
+}
+
+export function resolveAssetDisplayKind({
+  isCashBalance,
+  assetCategory,
+  contractSecType,
+  multiplier,
+}: AssetDisplayContext): AssetDisplayKind {
+  if (isCashBalance) return "cash";
+
+  const normalizedType = normalizeType(contractSecType || assetCategory);
+  if (CASH_TYPES.has(normalizedType) || normalizedType.includes("FOREX") || normalizedType.includes("CURRENCY")) return "cash";
+  if (CRYPTO_TYPES.has(normalizedType) || normalizedType.includes("CRYPTO")) return "crypto";
+  if (EQUITY_TYPES.has(normalizedType)) return "equity";
+  if (CONTRACT_TYPES.has(normalizedType)) return "contract";
+  if ((multiplier ?? 1) > 1) return "contract";
+  return "other";
+}
+
+export function formatMarketQuantity(value: number | undefined, options: MarketFormatOptions = {}): string {
+  if (value === undefined || value === null || Number.isNaN(value)) return "—";
+  const kind = resolveAssetDisplayKind(options);
+  const maxFractionDigits = getQuantityMaxFractionDigits(kind, value);
+  return formatVariableNumber(value, maxFractionDigits, options.maxWidth);
+}
+
+export function formatMarketPrice(value: number | undefined, options: MarketFormatOptions = {}): string {
+  if (value === undefined || value === null || Number.isNaN(value)) return "—";
+  const kind = resolveAssetDisplayKind(options);
+  const fixedFractionDigits = options.fixedFractionDigits;
+  if (fixedFractionDigits !== undefined) {
+    const maxFractionDigits = kind === "other" && options.priceRange !== undefined
+      ? 6
+      : getBasePriceMaxFractionDigits(kind, value);
+    const clampedFixedFractionDigits = Math.max(0, Math.min(fixedFractionDigits, maxFractionDigits));
+    return formatVariableNumber(value, clampedFixedFractionDigits, options.maxWidth, clampedFixedFractionDigits);
+  }
+  const minimumFractionDigits = Math.max(
+    0,
+    Math.min(options.minimumFractionDigits ?? 0, getBasePriceMaxFractionDigits(kind, value)),
+  );
+  const maxFractionDigits = Math.max(
+    getPriceMaxFractionDigits(kind, value, options.priceRange, options.precisionOffset ?? 0),
+    minimumFractionDigits,
+  );
+  return formatVariableNumber(value, maxFractionDigits, options.maxWidth, minimumFractionDigits);
+}
+
+export function formatMarketCost(value: number | undefined, options: MarketFormatOptions = {}): string {
+  if (value === undefined || value === null || Number.isNaN(value)) return "—";
+  const kind = resolveAssetDisplayKind(options);
+  return formatVariableNumber(value, getCostMaxFractionDigits(kind), options.maxWidth);
+}
+
+export function formatSignedMarketPrice(value: number | undefined, options: MarketFormatOptions = {}): string {
+  if (value === undefined || value === null || Number.isNaN(value)) return "—";
+  if (value > 0) {
+    const maxWidth = options.maxWidth == null ? undefined : Math.max(1, options.maxWidth - 1);
+    return `+${formatMarketPrice(value, { ...options, maxWidth })}`;
+  }
+  return formatMarketPrice(value, options);
+}
+
+export function formatMarketPriceWithCurrency(
+  value: number | undefined,
+  currency = "USD",
+  options: MarketFormatOptions = {},
+): string {
+  if (value === undefined || value === null || Number.isNaN(value)) return "—";
+  const normalizedCurrency = currency.trim().toUpperCase() || "USD";
+  const sign = value < 0 ? "-" : "";
+  const symbol = getCurrencySymbol(normalizedCurrency);
+  const numericWidth = options.maxWidth == null
+    ? undefined
+    : Math.max(1, options.maxWidth - sign.length - symbol.length);
+  const body = formatMarketPrice(Math.abs(value), { ...options, maxWidth: numericWidth });
+  return `${sign}${symbol}${body}`;
+}
+
+export function formatMarketCostWithCurrency(
+  value: number | undefined,
+  currency = "USD",
+  options: MarketFormatOptions = {},
+): string {
+  if (value === undefined || value === null || Number.isNaN(value)) return "—";
+  const normalizedCurrency = currency.trim().toUpperCase() || "USD";
+  const sign = value < 0 ? "-" : "";
+  const symbol = getCurrencySymbol(normalizedCurrency);
+  const numericWidth = options.maxWidth == null
+    ? undefined
+    : Math.max(1, options.maxWidth - sign.length - symbol.length);
+  const body = formatMarketCost(Math.abs(value), { ...options, maxWidth: numericWidth });
+  return `${sign}${symbol}${body}`;
+}
+
+export function formatCompactMarketPriceWithCurrency(
+  value: number | undefined,
+  currency = "USD",
+  options: MarketFormatOptions = {},
+): string {
+  if (value === undefined || value === null || Number.isNaN(value)) return "—";
+  const abs = Math.abs(value);
+
+  if (abs >= 1e6) {
+    return compactScaledPrice(value, 1e6, "M", currency, options.maxWidth);
+  }
+  if (abs >= 1e3 && abs < 1e5) {
+    return compactScaledPrice(value, 1e3, "K", currency, options.maxWidth);
+  }
+
+  return formatMarketPriceWithCurrency(value, currency, options);
+}
+
+export function formatMarketMoney(value: number | undefined, currency = "USD"): string {
+  return formatCurrency(value, currency);
+}

package/src/utils/market-status.ts

@@ -1,6 +1,7 @@
 import type { MarketState, Quote, QuoteFieldProvenance } from "../types/financials";
 import { colors, priceColor } from "../theme/colors";
 import { formatPercentRaw } from "./format";
+import { formatMarketPrice } from "./market-format";
 
 export interface ActiveQuoteDisplay {
   price: number;
@@ -107,11 +108,11 @@ export function getExtendedHoursInfo(quote: Quote | null | undefined): { text: s
   if (!quote) return null;
   if ((quote.marketState === "PRE" || quote.marketState === "PREPRE") && quote.preMarketPrice != null) {
     const chg = quote.preMarketChangePercent ?? 0;
-    return { text: `Pre ${quote.preMarketPrice.toFixed(2)} ${formatPercentRaw(chg)}`, color: priceColor(chg) };
+    return { text: `Pre ${formatMarketPrice(quote.preMarketPrice)} ${formatPercentRaw(chg)}`, color: priceColor(chg) };
   }
   if ((quote.marketState === "POST" || quote.marketState === "POSTPOST") && quote.postMarketPrice != null) {
     const chg = quote.postMarketChangePercent ?? 0;
-    return { text: `AH ${quote.postMarketPrice.toFixed(2)} ${formatPercentRaw(chg)}`, color: priceColor(chg) };
+    return { text: `AH ${formatMarketPrice(quote.postMarketPrice)} ${formatPercentRaw(chg)}`, color: priceColor(chg) };
   }
   return null;
 }

package/src/utils/selection-clipboard.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, test } from "bun:test";
+import { copyActiveSelection, isCopyShortcut, isPasteShortcut } from "./selection-clipboard";
+
+describe("selection clipboard sync", () => {
+  test("copies the active selection when present", () => {
+    const renderer = {
+      copyToClipboardOSC52: (text: string) => text === "AAPL",
+      getSelection: () => ({
+        getSelectedText: () => "AAPL",
+      }),
+    };
+
+    expect(copyActiveSelection(renderer as any)).toBe(true);
+  });
+
+  test("ignores empty or missing selections", () => {
+    expect(copyActiveSelection({
+      copyToClipboardOSC52: () => true,
+      getSelection: () => null,
+    } as any)).toBe(false);
+
+    expect(copyActiveSelection({
+      copyToClipboardOSC52: () => true,
+      getSelection: () => ({
+        getSelectedText: () => "",
+      }),
+    } as any)).toBe(false);
+  });
+
+  test("matches explicit copy shortcuts only", () => {
+    expect(isCopyShortcut({ name: "c", super: true, meta: false, ctrl: false, shift: false } as any)).toBe(true);
+    expect(isCopyShortcut({ name: "c", super: false, meta: true, ctrl: false, shift: false } as any)).toBe(true);
+    expect(isCopyShortcut({ name: "c", super: false, meta: false, ctrl: true, shift: true } as any)).toBe(true);
+    expect(isCopyShortcut({ name: "c", super: false, ctrl: true, shift: false } as any)).toBe(false);
+  });
+
+  test("matches explicit paste shortcuts only", () => {
+    expect(isPasteShortcut({ name: "v", super: true, meta: false, ctrl: false, shift: false } as any)).toBe(true);
+    expect(isPasteShortcut({ name: "v", super: false, meta: true, ctrl: false, shift: false } as any)).toBe(true);
+    expect(isPasteShortcut({ name: "v", super: false, meta: false, ctrl: true, shift: true } as any)).toBe(true);
+    expect(isPasteShortcut({ name: "v", super: false, meta: false, ctrl: true, shift: false } as any)).toBe(false);
+  });
+});

package/src/utils/selection-clipboard.ts

@@ -0,0 +1,88 @@
+import type { CliRenderer, KeyEvent } from "@opentui/core";
+
+function readTextFromSystemClipboard(): string | null {
+  if (process.platform !== "darwin") {
+    return null;
+  }
+
+  try {
+    const result = Bun.spawnSync(["pbpaste"], {
+      stdout: "pipe",
+      stderr: "ignore",
+    });
+    if (!result.success) {
+      return null;
+    }
+    return result.stdout.toString().replace(/\r\n/g, "\n");
+  } catch {
+    return null;
+  }
+}
+
+function copyTextToSystemClipboard(text: string): boolean {
+  if (text.length === 0 || process.platform !== "darwin") {
+    return false;
+  }
+
+  try {
+    const result = Bun.spawnSync(["pbcopy"], {
+      stdin: new Blob([text]),
+      stdout: "ignore",
+      stderr: "ignore",
+    });
+    return result.success;
+  } catch {
+    return false;
+  }
+}
+
+export function copySelectionText(
+  renderer: Pick<CliRenderer, "copyToClipboardOSC52">,
+  text: string,
+): boolean {
+  if (text.length === 0) {
+    return false;
+  }
+
+  return renderer.copyToClipboardOSC52(text) || copyTextToSystemClipboard(text);
+}
+
+export function copyActiveSelection(
+  renderer: Pick<CliRenderer, "getSelection" | "copyToClipboardOSC52">,
+): boolean {
+  const text = renderer.getSelection()?.getSelectedText() ?? "";
+  return copySelectionText(renderer, text);
+}
+
+export function isCopyShortcut(
+  event: Pick<KeyEvent, "name" | "super" | "meta" | "ctrl" | "shift">,
+): boolean {
+  const keyName = event.name.toLowerCase();
+  return keyName === "c" && (
+    event.super === true
+    || event.meta === true
+    || (event.ctrl === true && event.shift === true)
+  );
+}
+
+export function isPasteShortcut(
+  event: Pick<KeyEvent, "name" | "super" | "meta" | "ctrl" | "shift">,
+): boolean {
+  const keyName = event.name.toLowerCase();
+  return keyName === "v" && (
+    event.super === true
+    || event.meta === true
+    || (event.ctrl === true && event.shift === true)
+  );
+}
+
+export function pasteSystemClipboard(
+  renderer: Pick<CliRenderer, "keyInput">,
+): boolean {
+  const text = readTextFromSystemClipboard();
+  if (!text) {
+    return false;
+  }
+  renderer.keyInput.processPaste(new TextEncoder().encode(text));
+  return true;
+}

package/src/utils/terminal-input-reset.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, test } from "bun:test";
+import { resetTerminalInputState, TERMINAL_MOUSE_RESET_SEQUENCE } from "./terminal-input-reset";
+
+describe("resetTerminalInputState", () => {
+  test("disables mouse tracking and exits raw mode before renderer startup", () => {
+    const writes: string[] = [];
+    const rawModeCalls: boolean[] = [];
+
+    resetTerminalInputState(
+      {
+        isTTY: true,
+        setRawMode(mode: boolean) {
+          rawModeCalls.push(mode);
+        },
+      },
+      {
+        isTTY: true,
+        write(chunk: string) {
+          writes.push(chunk);
+        },
+      },
+    );
+
+    expect(writes).toEqual([TERMINAL_MOUSE_RESET_SEQUENCE]);
+    expect(rawModeCalls).toEqual([false]);
+  });
+
+  test("does not write terminal escapes when stdout is not a tty", () => {
+    const writes: string[] = [];
+    const rawModeCalls: boolean[] = [];
+
+    resetTerminalInputState(
+      {
+        isTTY: true,
+        setRawMode(mode: boolean) {
+          rawModeCalls.push(mode);
+        },
+      },
+      {
+        isTTY: false,
+        write(chunk: string) {
+          writes.push(chunk);
+        },
+      },
+    );
+
+    expect(writes).toEqual([]);
+    expect(rawModeCalls).toEqual([false]);
+  });
+});

package/src/utils/terminal-input-reset.ts

@@ -0,0 +1,24 @@
+export const TERMINAL_MOUSE_RESET_SEQUENCE = "\x1B[?1016l\x1B[?1006l\x1B[?1005l\x1B[?1015l\x1B[?1003l\x1B[?1002l\x1B[?1000l";
+
+interface TerminalResetStdin {
+  isTTY?: boolean;
+  setRawMode?: (mode: boolean) => void;
+}
+
+interface TerminalResetStdout {
+  isTTY?: boolean;
+  write: (chunk: string) => unknown;
+}
+
+export function resetTerminalInputState(
+  stdin: TerminalResetStdin = process.stdin,
+  stdout: TerminalResetStdout = process.stdout,
+): void {
+  if (stdout.isTTY) {
+    stdout.write(TERMINAL_MOUSE_RESET_SEQUENCE);
+  }
+
+  if (stdin.isTTY !== false && typeof stdin.setRawMode === "function") {
+    stdin.setRawMode(false);
+  }
+}

package/src/utils/throttled-fetch.test.ts

@@ -0,0 +1,145 @@
+import { describe, expect, test, mock, beforeEach, afterAll } from "bun:test";
+import { createThrottledFetch } from "./throttled-fetch";
+
+// Mock global fetch
+const originalFetch = globalThis.fetch;
+let fetchMock: ReturnType<typeof mock>;
+
+beforeEach(() => {
+  fetchMock = mock(() => Promise.resolve(new Response(JSON.stringify({ ok: true }), { status: 200 })));
+  globalThis.fetch = fetchMock as any;
+});
+
+describe("createThrottledFetch", () => {
+  test("passes through a simple request", async () => {
+    const client = createThrottledFetch();
+    const resp = await client.fetch("https://api.example.com/test");
+    expect(resp.status).toBe(200);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  test("merges default headers", async () => {
+    const client = createThrottledFetch({
+      defaultHeaders: { "X-Custom": "value" },
+    });
+    await client.fetch("https://api.example.com/test");
+    const callInit = fetchMock.mock.calls[0]![1] as RequestInit;
+    expect((callInit.headers as Record<string, string>)["X-Custom"]).toBe("value");
+  });
+
+  test("deduplicates concurrent GET requests to same URL", async () => {
+    let resolveFirst: (r: Response) => void;
+    const slowResponse = new Promise<Response>((resolve) => { resolveFirst = resolve; });
+    fetchMock = mock(() => slowResponse);
+    globalThis.fetch = fetchMock as any;
+
+    const client = createThrottledFetch();
+    const p1 = client.fetch("https://api.example.com/same");
+    const p2 = client.fetch("https://api.example.com/same");
+
+    resolveFirst!(new Response("ok", { status: 200 }));
+    const [r1, r2] = await Promise.all([p1, p2]);
+    expect(r1).not.toBe(r2);
+    expect(await r1.text()).toBe("ok");
+    expect(await r2.text()).toBe("ok");
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  test("does not deduplicate different URLs", async () => {
+    const client = createThrottledFetch();
+    await Promise.all([
+      client.fetch("https://api.example.com/a"),
+      client.fetch("https://api.example.com/b"),
+    ]);
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+
+  test("retries on 429 with backoff", async () => {
+    let callCount = 0;
+    fetchMock = mock(() => {
+      callCount++;
+      if (callCount === 1) {
+        return Promise.resolve(new Response("rate limited", { status: 429 }));
+      }
+      return Promise.resolve(new Response(JSON.stringify({ ok: true }), { status: 200 }));
+    });
+    globalThis.fetch = fetchMock as any;
+
+    const client = createThrottledFetch({ maxRetries: 1, backoffBaseMs: 0 });
+    const resp = await client.fetch("https://api.example.com/test");
+    expect(resp.status).toBe(200);
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+
+  test("retries on 500 with backoff", async () => {
+    let callCount = 0;
+    fetchMock = mock(() => {
+      callCount++;
+      if (callCount === 1) {
+        return Promise.resolve(new Response("error", { status: 500 }));
+      }
+      return Promise.resolve(new Response(JSON.stringify({ ok: true }), { status: 200 }));
+    });
+    globalThis.fetch = fetchMock as any;
+
+    const client = createThrottledFetch({ maxRetries: 1, backoffBaseMs: 0 });
+    const resp = await client.fetch("https://api.example.com/test");
+    expect(resp.status).toBe(200);
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+
+  test("retries transient fetch failures", async () => {
+    let callCount = 0;
+    fetchMock = mock(() => {
+      callCount++;
+      if (callCount === 1) {
+        return Promise.reject(
+          Object.assign(new Error("The socket connection was closed unexpectedly."), {
+            code: "ECONNRESET",
+          }),
+        );
+      }
+      return Promise.resolve(new Response(JSON.stringify({ ok: true }), { status: 200 }));
+    });
+    globalThis.fetch = fetchMock as any;
+
+    const client = createThrottledFetch({ maxRetries: 1, backoffBaseMs: 0 });
+    const resp = await client.fetch("https://api.example.com/test");
+    expect(resp.status).toBe(200);
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+
+  test("stops retrying after max retries", async () => {
+    fetchMock = mock(() => Promise.resolve(new Response("error", { status: 429 })));
+    globalThis.fetch = fetchMock as any;
+
+    const client = createThrottledFetch({ maxRetries: 1, backoffBaseMs: 0 });
+    const resp = await client.fetch("https://api.example.com/test");
+    expect(resp.status).toBe(429);
+    expect(fetchMock).toHaveBeenCalledTimes(2); // initial + 1 retry
+  });
+
+  test("fetchJson parses response and throws on error", async () => {
+    const client = createThrottledFetch();
+    const data = await client.fetchJson<{ ok: boolean }>("https://api.example.com/test");
+    expect(data).toEqual({ ok: true });
+
+    fetchMock = mock(() => Promise.resolve(new Response("not found", { status: 404 })));
+    globalThis.fetch = fetchMock as any;
+    const client2 = createThrottledFetch({ maxRetries: 0 });
+    await expect(client2.fetchJson("https://api.example.com/test")).rejects.toThrow("HTTP 404");
+  });
+
+  test("fetchJson throws friendly message on 429", async () => {
+    fetchMock = mock(() => Promise.resolve(new Response("", { status: 429 })));
+    globalThis.fetch = fetchMock as any;
+
+    const client = createThrottledFetch({ maxRetries: 0 });
+    await expect(client.fetchJson("https://api.example.com/test")).rejects.toThrow("Rate limited");
+  });
+});
+
+// Restore
+afterAll(() => {
+  globalThis.fetch = originalFetch;
+});