gloomberb 0.17.5 → 0.18.0

package/src/api-client/credit-boards.ts

@@ -9,6 +9,12 @@ export interface CreditBoardPoint {
   prints: number;
   /** The contract that was on the run that day, e.g. "2031-12-20". */
   maturity: string;
+  /**
+   * HY and EM: the day's price as a conventional spread in bp (ISDA standard
+   * model at the index's coupon and standard recovery). Absent from a server
+   * that predates it and on spread-quoted indexes; null where no spread fits.
+   */
+  spreadBp?: number | null;
 }
 
 /** IG and iTraxx trade on spread (bp); HY and EM on price. */
@@ -20,11 +26,25 @@ export interface CdxBoardIndex {
   quote: CreditIndexQuote;
   currency: string;
   couponBp: number;
+  /** The recovery the spread equivalent assumes (HY 30%, EM 25%). Absent from a server that predates it. */
+  recovery?: number;
   date: string | null;
   maturity: string | null;
   level: number | null;
   prints: number | null;
-  /** In the quote's unit, on one contract across a roll. */
+  /** HY and EM: the latest level as a conventional spread in bp, as on each point. */
+  spreadBp?: number | null;
+  /**
+   * The latest day is today's New York trade date, still trading: its level
+   * and prints are so far and the moves run to `changeDate`. Absent from a
+   * server that predates it, which the board then works out from the date.
+   */
+  partial?: boolean;
+  /** When the latest day's last print on its contract was executed, ISO UTC. */
+  lastPrintAt?: string | null;
+  /** The last complete day, which the moves run to. */
+  changeDate?: string | null;
+  /** In the quote's unit, on one contract across a roll, between complete days. */
   change1D: number | null;
   change1W: number | null;
   /** Absent from a server that predates it. */

package/src/api-client/crypto-markets.ts

@@ -6,8 +6,30 @@ interface CryptoDailyCloses {
 
 export type CryptoAssetKind = "coin" | "stablecoin";
 
+/** What a stablecoin holds to: a currency, or a dollar value that accrues yield. */
+export interface CryptoPeg {
+  /** The currency it is pegged to: USD, EUR. */
+  currency: string;
+  /** Yield accrues into the price (USDY): it has no par to be off. */
+  accrues: boolean;
+  /** The target in dollars: 1 for USD, the EUR/USD rate for EUR; null when it accrues or the rate is unavailable. */
+  price: number | null;
+  /** When a target that moves (an exchange rate) was quoted; null for USD. */
+  asOf: string | null;
+}
+
+/** The lowest and highest trade in the 24 hours to `end`, and when each was. */
+interface CryptoDayRange {
+  low: number;
+  lowAt: string;
+  high: number;
+  highAt: string;
+  start: string;
+  end: string;
+}
+
 export interface CryptoMarketAsset {
-  /** Quote symbol for streaming and the ticker pane, for example BTC-USD. */
+  /** The coin's one symbol for quotes, history, streaming and the ticker pane, for example BTC-USD or USDE-USD. */
   symbol: string;
   /** Display code, for example BTC. */
   code: string;
@@ -31,6 +53,10 @@ export interface CryptoMarketAsset {
   yearAgoPrice: number | null;
   quoteTime: string | null;
   history: CryptoDailyCloses | null;
+  /** A stablecoin's peg; absent from servers before it was served. */
+  peg?: CryptoPeg | null;
+  /** A stablecoin's 24-hour low and high; absent from servers before it was served. */
+  range24h?: CryptoDayRange | null;
 }
 
 export interface CryptoMarketsPayload {
@@ -47,3 +73,64 @@ export interface CryptoMarketsPayload {
   assets: CryptoMarketAsset[];
   warnings: string[];
 }
+
+/** One stablecoin's supply across chains in USD, on the board's as-of day. */
+export interface StablecoinSupplyCoin {
+  symbol: string;
+  name: string;
+  /** The currency the coin is pegged to, as the source names it: peggedUSD, peggedEUR, peggedVAR (a floating target). */
+  pegType: string;
+  pegMechanism: string | null;
+  /** USD per unit the day's supply is valued at; null when the source states no units that day. */
+  price: number | null;
+  /** USD on the as-of day: the same figure the coin's daily supply ends on. */
+  supply: number;
+  /** Change in USD over 7 and 30 days on the coin's daily supply, and in percent of the value then. */
+  change7d: number | null;
+  change7dPercent: number | null;
+  change30d: number | null;
+  change30dPercent: number | null;
+  /** Percent of the total stablecoin supply. */
+  share: number | null;
+}
+
+export interface StablecoinSupplyPayload {
+  version: 1;
+  generatedAt: string;
+  fetchedAt: string | null;
+  /** UTC date of the newest daily total. */
+  asOf: string | null;
+  status: "available" | "stale" | "unavailable";
+  source: { name: string; url: string };
+  total: {
+    supply: number;
+    change7d: number | null;
+    change7dPercent: number | null;
+    change30d: number | null;
+    change30dPercent: number | null;
+  } | null;
+  /** The largest stablecoins by supply, largest first. */
+  coins: StablecoinSupplyCoin[];
+  /** Daily supply in USD since `start`: the total and the largest coins, on the same days. */
+  history: {
+    start: string;
+    total: Array<number | null>;
+    coins: Array<{ symbol: string; name: string; values: Array<number | null> }>;
+  } | null;
+  warnings: string[];
+}
+
+/** One stablecoin's daily supply in USD. */
+export interface StablecoinSupplyHistoryPayload {
+  version: 1;
+  generatedAt: string;
+  fetchedAt: string | null;
+  asOf: string | null;
+  status: "available" | "stale" | "unavailable";
+  source: { name: string; url: string };
+  symbol: string;
+  name: string;
+  pegType: string;
+  history: { start: string; values: Array<number | null> } | null;
+  warnings: string[];
+}

package/src/api-client/data.ts

@@ -13,6 +13,7 @@ import { supplyGraphQuery, type GraphOptions, type GraphPayload } from "./supply
 import type { AwardDetailPayload, AwardFilter, AwardsPayload } from "./awards";
 import type { EarningsEvent } from "../types/data-provider";
 import type { MarketDividendsPayload, MarketHeatmapResult, MarketHeatmapUniverseId, MarketMoversPayload } from "./market-discovery";
+import type { BankFiguresPayload } from "./bank-figures";
 import type { DebtMaturitiesPayload } from "./debt-maturities";
 import type { RevenueBreakdownPayload, RevenueBreakdownView } from "./revenue-breakdown";
 import type { MnaDealPayload, MnaDealsParams, MnaDealsPayload } from "./mna";
@@ -27,7 +28,7 @@ import type { LettersParams } from "./letters";
 import type { IpoCalendarParams, IpoCalendarPayload } from "./ipo";
 import type { TickerChanges } from "../types/ticker-changes";
 import type { OrganizationTickersResponse } from "./organization-tickers";
-import type { CryptoMarketsPayload } from "./crypto-markets";
+import type { CryptoMarketsPayload, StablecoinSupplyHistoryPayload, StablecoinSupplyPayload } from "./crypto-markets";
 import type { CentralBankRatesPayload } from "./central-bank-rates";
 import type { EstimateRevisionsPayload } from "./estimate-revisions";
 import type { MoneyMarketsPayload } from "./money-markets";
@@ -35,15 +36,18 @@ import type { CloudCurveHistory, CloudCurveId, CloudCurveView, CloudWorldCurves
 import type { CdxBoardPayload, CloudCreditBoardParams, SovrBoardPayload } from "./credit-boards";
 import type { ShortVolumePayload, ShortVolumeScope } from "./short-volume";
 import type { BeneficialOwnersPayload, CloudBeneficialOwnersParams } from "./beneficial-owners";
+import type { CloudInsiderSignalsParams, InsiderSignalsPayload } from "./insider-signals";
 import type { SocialMentionDayPosts, SocialMentionsPayload, SocialMentionsRange } from "./social-mentions";
 import type { FuturesContractTermsPayload, FuturesCurveAsOfPayload, FuturesCurvePayload } from "./futures-curve";
 import type { CotBoardPayload, CotContractPayload, CotFamily, CotClass } from "./cot";
 import type { DoeBoardPayload, DoePricesPayload } from "./doe";
+import type { JodiBoardPayload, PsdBoardPayload } from "./commodity-balances";
 import type { CarbonBoard, CarbonHistory, EuropePowerBoard, EuropePowerHistory, GasStorageBoard, GasStorageHistory, GasStorageSeasonal } from "./europe-energy";
 import type { GpuBoardPayload, GpuEventsPayload, GpuHistoryPayload, GpuHistoryQuery } from "./gpu";
 import type { CpiBoardPayload } from "./cpi";
-import type { TapeSnapshot } from "./tape";
+import type { TapeRange, TapeSnapshot } from "./tape";
 import { signalWithTimeout } from "../utils/async-deadline";
+import { ApiRequestError } from "./errors";
 import type { ExchangeRateSnapshot } from "../types/exchange-rate";
 import type { RatePathPayload } from "./rates";
 import type { EarningsCalendarPayload, EarningsCalendarQuery, EarningsHistoryPayload } from "./earnings";
@@ -65,6 +69,7 @@ import {
   cloudCdsPath,
   cloudCongressHousePath,
   cloudEarningsCallsPath,
+  cloudEarningsCallAudioPath,
   cloudEarningsTranscriptPath,
   cloudJobsMoversPath,
   cloudJobsPath,
@@ -72,6 +77,7 @@ import {
   type CloudJobsPostingsParams,
   type IssuerListingParams,
   cloudProxyStatementPath,
+  cloudBankFiguresPath,
   cloudDebtMaturitiesPath,
   cloudFilingEventsPath,
   cloudRiskReportPath,
@@ -81,6 +87,7 @@ import {
   cloudExchangeRatePath,
   cloudSec13FPath,
   cloudSecBeneficialOwnersPath,
+  cloudSecInsiderSignalsPath,
   cloudSecFilingContentPath,
   cloudSecFilingDocumentsPath,
   cloudSecFilingsPath,
@@ -119,6 +126,7 @@ import type {
   CloudCdsResponse,
   CloudCongressHousePayload,
   CloudEarningsCallListPayload,
+  CloudEarningsCallAudioPayload,
   CloudEarningsTranscriptPayload,
   CloudJobsMoversPayload,
   CloudJobsPostingsPayload,
@@ -143,6 +151,7 @@ import type {
   CloudMarketResponse,
   CloudMarketScreenerCategory,
   CloudMarketScreenerPayload,
+  CloudMoverSession,
   CloudNewsListResponse,
   CloudNewsPayload,
   CloudSavedSearch,
@@ -165,6 +174,26 @@ import type {
 } from "./types";
 import type { CloudApiRequest } from "./request";
 
+/** A batched lookup's answer: one item per key asked, with that key's own status. */
+type CloudBatchAnswer<K extends string, T> = {
+  items?: Array<{ status?: string; data?: T | null } & Record<K, string>>;
+};
+
+/**
+ * A batched lookup's items by the key each was asked as: the data of an item
+ * that has some, null for one with nothing on record, and none for one the
+ * service could not answer (rate limited, an upstream failure).
+ */
+function batchAnswers<K extends string, T>(response: CloudMarketResponse<CloudBatchAnswer<K, T>>, key: K): Map<string, T | null> {
+  const answers = new Map<string, T | null>();
+  for (const item of response.data?.items ?? []) {
+    if (typeof item?.[key] !== "string") continue;
+    if (item.status === "success" || item.status === "partial") answers.set(item[key], item.data ?? null);
+    else if (item.status === "empty") answers.set(item[key], null);
+  }
+  return answers;
+}
+
 export class CloudDataApi {
   constructor(private readonly request: CloudApiRequest) {}
 
@@ -204,6 +233,11 @@ export class CloudDataApi {
     return this.request<import("./members").FundMembersPayload>(`/cloud/members/${encodeURIComponent(fund)}`);
   }
 
+  /** A US-listed fund's fee, NAV, premium and net assets as its sponsor publishes them. */
+  getFundFacts(ticker: string) {
+    return this.request<import("./fund-facts").FundFactsPayload>(`/cloud/fund-facts/${encodeURIComponent(ticker)}`);
+  }
+
   getFundChanges(fund: string) {
     return this.request<import("./members").FundChangesPayload>(`/cloud/members/${encodeURIComponent(fund)}/changes`);
   }
@@ -233,6 +267,10 @@ export class CloudDataApi {
     const response = await this.request<
       CloudMarketResponse<InstrumentSearchResult[]>
     >(cloudMarketSearchPath(query, limit));
+    // A search the service could not run (its catalogue rate limited, say) is no answer, not an empty one.
+    if (response.status === "retryable_error" || response.status === "fatal_error") {
+      throw new ApiRequestError(response.reasonCode ?? "Cloud search failed", undefined, undefined, response.status);
+    }
     return response.data ?? [];
   }
 
@@ -283,8 +321,10 @@ export class CloudDataApi {
     return this.request(`/news/article-summary?${new URLSearchParams({ url })}`);
   }
 
-  getMarketMovers(category: "day_gainers" | "day_losers" | "most_actives", count = 25, refresh = false): Promise<CloudMarketResponse<MarketMoversPayload>> {
+  /** `session` is what Gainers and Losers are ranked by (see CloudMoverSession). */
+  getMarketMovers(category: "day_gainers" | "day_losers" | "most_actives", count = 25, refresh = false, session?: CloudMoverSession): Promise<CloudMarketResponse<MarketMoversPayload>> {
     const params = new URLSearchParams({ category, count: String(count), mode: refresh ? "refresh" : "cache-first" });
+    if (session && category !== "most_actives") params.set("session", session);
     return this.request(`/market/movers?${params}`);
   }
 
@@ -300,12 +340,17 @@ export class CloudDataApi {
     return this.requestMarketSymbol("/market/dividends", symbol, exchange);
   }
 
-  /** Gainers, losers and most active, or the pre-market, after-hours and gap lists with a `side`. */
+  /**
+   * Gainers, losers and most active, or the pre-market, after-hours and gap
+   * lists with a `side`. `session` is what Gainers and Losers are ranked by
+   * (see CloudMoverSession).
+   */
   async getCloudMarketScreener<Category extends CloudMarketScreenerCategory | CloudSessionMoversCategory>(
     category: Category,
     count = 25,
     mode: "cache-first" | "refresh" = "cache-first",
     side?: CloudSessionMoversSide,
+    session?: CloudMoverSession,
   ): Promise<CloudMarketResponse<Category extends CloudSessionMoversCategory ? CloudSessionMoversPayload : CloudMarketScreenerPayload>> {
     const requestedCount = Number.isFinite(count) ? Math.round(count) : 25;
     const params = new URLSearchParams({
@@ -314,6 +359,7 @@ export class CloudDataApi {
       mode,
     });
     if (side && isSessionMoversCategory(category)) params.set("side", side);
+    if (session && (category === "gainers" || category === "losers")) params.set("session", session);
     return this.request(`/market/screener?${params.toString()}`);
   }
 
@@ -390,6 +436,40 @@ export class CloudDataApi {
     );
   }
 
+  /**
+   * `getCloudTickerChanges` for several symbols in one request: by symbol as
+   * asked, null for one with no change on record. A symbol the service could
+   * not answer for is left out.
+   */
+  async getCloudTickerChangesBatch(
+    symbols: readonly string[],
+    options: { signal?: AbortSignal } = {},
+  ): Promise<Map<string, TickerChanges | null>> {
+    const response = await this.request<CloudMarketResponse<CloudBatchAnswer<"symbol", TickerChanges>>>(
+      "/market/ticker-changes/batch",
+      { method: "POST", body: JSON.stringify({ symbols }), ...options.signal ? { signal: options.signal } : {} },
+    );
+    return batchAnswers(response, "symbol");
+  }
+
+  /**
+   * Several searches in one request, each answered as `searchInstruments`
+   * answers it: by query as asked, a query the service could not search left out.
+   */
+  async searchInstrumentsBatch(
+    queries: readonly string[],
+    limit = 10,
+    options: { signal?: AbortSignal } = {},
+  ): Promise<Map<string, InstrumentSearchResult[]>> {
+    const response = await this.request<CloudMarketResponse<CloudBatchAnswer<"query", InstrumentSearchResult[]>>>(
+      "/market/search/batch",
+      { method: "POST", body: JSON.stringify({ queries, limit }), ...options.signal ? { signal: options.signal } : {} },
+    );
+    const answers = new Map<string, InstrumentSearchResult[]>();
+    for (const [query, rows] of batchAnswers(response, "query")) answers.set(query, rows ?? []);
+    return answers;
+  }
+
   /** The listed company each organization name resolves to, if any: a trial's lead sponsors, a page at a time. */
   async getCloudOrganizationTickers(names: readonly string[], signal?: AbortSignal): Promise<OrganizationTickersResponse> {
     return this.request<OrganizationTickersResponse>("/market/organization-tickers", {
@@ -446,6 +526,11 @@ export class CloudDataApi {
     return this.request<CloudEconEventPayload[]>("/cloud/econ/calendar");
   }
 
+  /** The calendar from a UTC day, past events included, and the first day the stored calendar holds. */
+  async getCloudEconomicCalendarFrom(from: string): Promise<{ events: CloudEconEventPayload[]; storedFrom: string | null }> {
+    return this.request<{ events: CloudEconEventPayload[]; storedFrom: string | null }>(`/cloud/econ/calendar/history?from=${encodeURIComponent(from)}`);
+  }
+
   async getCloudMacroReleaseDays(): Promise<CloudMacroReleaseDaysPayload> {
     return this.request<CloudMacroReleaseDaysPayload>("/cloud/econ/release-days");
   }
@@ -590,6 +675,14 @@ export class CloudDataApi {
     return this.request<DoePricesPayload>("/cloud/doe/prices");
   }
 
+  getCloudJodiBoard(signal?: AbortSignal): Promise<JodiBoardPayload> {
+    return this.request<JodiBoardPayload>("/cloud/jodi/board", { signal });
+  }
+
+  getCloudPsdBoard(signal?: AbortSignal): Promise<PsdBoardPayload> {
+    return this.request<PsdBoardPayload>("/cloud/psd/board", { signal });
+  }
+
   async getCloudAttention(window: AttentionWindow = "now", symbol?: string): Promise<AttentionPayload> {
     const path = symbol ? `/cloud/attention/${encodeURIComponent(symbol)}` : "/cloud/attention";
     return this.request<AttentionPayload>(`${path}?window=${window}`);
@@ -672,8 +765,10 @@ export class CloudDataApi {
     return this.request<CpiBoardPayload>("/cloud/cpi/board");
   }
 
-  async getCloudTape(symbol: string, exchange: string, signal?: AbortSignal): Promise<TapeSnapshot> {
-    return this.request<TapeSnapshot>(`/cloud/tape/${encodeURIComponent(symbol)}?exchange=${encodeURIComponent(exchange)}`, { signal: signalWithTimeout(signal, 30_000) });
+  /** The latest tape, or with a `range` that window of the session, read forward from its start. */
+  async getCloudTape(symbol: string, exchange: string, signal?: AbortSignal, range?: TapeRange): Promise<TapeSnapshot> {
+    const window = range ? `&from=${encodeURIComponent(range.from)}&to=${encodeURIComponent(range.to)}` : "";
+    return this.request<TapeSnapshot>(`/cloud/tape/${encodeURIComponent(symbol)}?exchange=${encodeURIComponent(exchange)}${window}`, { signal: signalWithTimeout(signal, 30_000) });
   }
 
   async getCloudYieldCurve(): Promise<CloudYieldPointPayload[]> {
@@ -704,6 +799,19 @@ export class CloudDataApi {
     return this.request<CryptoMarketsPayload>("/cloud/crypto/markets", { signal: AbortSignal.timeout(45_000) });
   }
 
+  /** Total stablecoin supply and the largest coins', daily, with 7D and 30D changes and shares. */
+  async getCloudStablecoinSupply(): Promise<StablecoinSupplyPayload> {
+    return this.request<StablecoinSupplyPayload>("/cloud/crypto/stablecoins/supply", { signal: AbortSignal.timeout(30_000) });
+  }
+
+  /** One listed stablecoin's daily supply, by symbol. */
+  async getCloudStablecoinSupplyHistory(symbol: string): Promise<StablecoinSupplyHistoryPayload> {
+    return this.request<StablecoinSupplyHistoryPayload>(
+      `/cloud/crypto/stablecoins/supply/${encodeURIComponent(symbol)}`,
+      { signal: AbortSignal.timeout(30_000) },
+    );
+  }
+
   async getCloudCentralBankRates(): Promise<CentralBankRatesPayload> {
     return this.request<CentralBankRatesPayload>("/cloud/econ/central-bank-rates", { signal: AbortSignal.timeout(45_000) });
   }
@@ -725,6 +833,10 @@ export class CloudDataApi {
     return this.request<DebtMaturitiesPayload>(cloudDebtMaturitiesPath(symbol, listing), { signal: AbortSignal.timeout(45_000) });
   }
 
+  async getCloudBankFigures(symbol: string): Promise<BankFiguresPayload> {
+    return this.request<BankFiguresPayload>(cloudBankFiguresPath(symbol), { signal: AbortSignal.timeout(30_000) });
+  }
+
   async getCloudRevenueBreakdown(symbol: string, view?: RevenueBreakdownView, listing?: IssuerListingParams): Promise<RevenueBreakdownPayload> {
     return this.request<RevenueBreakdownPayload>(cloudRevenueBreakdownPath(symbol, view, listing), { signal: AbortSignal.timeout(30_000) });
   }
@@ -872,6 +984,14 @@ export class CloudDataApi {
     );
   }
 
+  async getCloudEarningsCallAudio(
+    id: string,
+  ): Promise<CloudEarningsCallAudioPayload> {
+    return this.request<CloudEarningsCallAudioPayload>(
+      cloudEarningsCallAudioPath(id),
+    );
+  }
+
   // A listing outside the US also sends its venue and company (listingAbroad).
   async getProxyStatements(
     ticker: string,
@@ -934,6 +1054,15 @@ export class CloudDataApi {
     });
   }
 
+  async getCloudSecInsiderSignals(
+    params: CloudInsiderSignalsParams = {},
+    options?: { signal?: AbortSignal },
+  ): Promise<InsiderSignalsPayload> {
+    return this.request<InsiderSignalsPayload>(cloudSecInsiderSignalsPath(params), {
+      signal: options?.signal,
+    });
+  }
+
   async getCloudSecFilingDocuments(
     params: CloudSecFilingParams,
   ): Promise<CloudSecDocumentsResponse> {

package/src/api-client/debt-maturities.ts

@@ -51,6 +51,22 @@ export interface DebtHistoryPoint {
   borrowingCostPercent: number | null;
   interestExpenseTag: string | null;
   borrowingCostDebtTags: string | null;
+  /** SEC's fiscal year for the period, when the server sends it. */
+  fy?: number | null;
+}
+/**
+ * The debt a 10-Q filed after the annual schedule reports on its balance
+ * sheet date: what is due within a year and what is due later.
+ */
+export interface DebtQuarter {
+  asOf: string;
+  filed: string;
+  accession: string;
+  form: string;
+  currency: string;
+  filingUrl: string;
+  current: DebtFact | null;
+  noncurrent: DebtFact | null;
 }
 export interface DebtMaturitiesPayload {
   version: 1;
@@ -88,5 +104,7 @@ export interface DebtMaturitiesPayload {
     borrowingCostEvidence: DebtBorrowingCost | null;
   };
   history: DebtHistoryPoint[];
+  /** The latest 10-Q when it is newer than `latest`. Older servers and cached payloads leave it out. */
+  latestQuarter?: DebtQuarter | null;
   warnings: string[];
 }

package/src/api-client/earnings.ts

@@ -27,6 +27,8 @@ interface EarningsRealizedMove {
   afterClose: number;
 }
 
+type EarningsActualSource = "calendar" | "press-release";
+
 export interface EarningsReport {
   symbol: string;
   name: string | null;
@@ -43,6 +45,12 @@ export interface EarningsReport {
   /** For an upcoming report, the consensus every earnings view shows, with `epsAnalysts` behind it. */
   epsEstimate: number | null;
   epsActual: number | null;
+  /**
+   * Where `epsActual` comes from: `press-release` is the company's own
+   * release, read the day it reports and provisional until the calendar's
+   * figure replaces it. Absent from older servers.
+   */
+  epsActualSource?: EarningsActualSource | null;
   epsAnalysts: number | null;
   revenueEstimate: number | null;
   revenueAnalysts: number | null;
@@ -69,6 +77,8 @@ export interface EarningsCalendarPayload {
 
 interface EarningsHistoryReport extends EarningsReport {
   revenueActual: number | null;
+  /** `press-release` until the statements have the quarter; absent from older servers. */
+  revenueActualSource?: "statements" | "press-release" | null;
 }
 
 export interface EarningsHistoryPayload {

package/src/api-client/equity-screener.ts

@@ -1,5 +1,7 @@
 /** Cited company disclosures; Pro, omitted by older servers. */
 export const KPI_FIELDS = ["kpiArr", "kpiNrrPercent", "kpiRpo", "kpiCrpo", "kpiSubscribers", "kpiDau", "kpiMau", "kpiGmv", "kpiTakeRatePercent", "kpiSameStoreSalesPercent", "kpiStores", "kpiBacklog", "kpiBookToBill", "kpiNimPercent", "kpiCet1Percent", "kpiCombinedRatioPercent", "kpiOccupancyPercent", "kpiLoadFactorPercent", "guideRevenueChangePercent", "guideEpsChangePercent"] as const;
+/** Payout ratio and dividend growth; listed only when asked (`include=dividends`), and omitted by a server from before them. */
+export const DIVIDEND_FIELDS = ["payoutRatioPercent", "dividendGrowth1YPercent", "dividendGrowth3YPercent"] as const;
 export const NUMERIC_FIELDS = [
   ...KPI_FIELDS,
   "price",
@@ -12,6 +14,7 @@ export const NUMERIC_FIELDS = [
   "forwardPE",
   "enterpriseToRevenue",
   "dividendYieldPercent",
+  ...DIVIDEND_FIELDS,
   "revenueGrowthPercent",
   "earningsGrowthPercent",
   "grossMarginPercent",

package/src/api-client/errors.ts

@@ -50,6 +50,17 @@ export function isPermanentClientError(error: unknown): boolean {
   return status !== undefined && status >= 400 && status < 500 && status !== 408 && status !== 429;
 }
 
+/**
+ * A failure asking again shortly may get past: a timeout, a rate limit or an
+ * overloaded server (408, 429, 5xx), or a market answer the service marked
+ * `retryable_error` because its own upstream was rate limited or timed out.
+ */
+export function isRetryableApiError(error: unknown): boolean {
+  if (!(error instanceof ApiRequestError)) return false;
+  const status = error.status;
+  return error.code === "retryable_error" || status === 408 || status === 429 || (status !== undefined && status >= 500);
+}
+
 /** Reads `Retry-After` as milliseconds, accepting seconds or an HTTP date. */
 export function parseRetryAfterMs(
   header: string | null,
@@ -97,6 +108,7 @@ export function parseApiErrorDetails(body: string): Readonly<Record<string, unkn
     const parsed = JSON.parse(body) as unknown;
     return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed as Record<string, unknown> : undefined;
   } catch {
+    // Intentional ignore: Non-JSON error responses retain their HTTP status and original body.
     return undefined;
   }
 }
@@ -107,6 +119,7 @@ export function parseApiErrorCode(body: string): string | undefined {
     const parsed = JSON.parse(body) as Record<string, unknown> | null;
     return typeof parsed?.error === "string" && parsed.error ? parsed.error : undefined;
   } catch {
+    // Intentional ignore: Non-JSON error responses retain their HTTP status and original body.
     return undefined;
   }
 }

package/src/api-client/fund-facts.ts

@@ -0,0 +1,72 @@
+/** One published figure: when it is as of and who published it (the fund's sponsor, or Gloom Cloud for a computed one). */
+interface FundFact<T> {
+  value: T;
+  asOf: string | null;
+  source: string;
+  url?: string;
+}
+
+type FundStructure = "registered" | "trust";
+type ExpenseRatioKind = "net" | "gross" | "sponsor-fee";
+/**
+ * A bond fund as its sponsor classes it: `municipal` when its interest is
+ * exempt from federal income tax, `taxable` otherwise.
+ */
+type BondFundClass = "municipal" | "taxable";
+
+/**
+ * What a bond fund's sponsor publishes about its yield and rate risk, each
+ * figure dated. The 30-day SEC yield is the standardized yield (net
+ * investment income of the last 30 days, annualized, over the offering
+ * price); a distribution yield annualizes cash paid and is not it.
+ */
+export interface FundBondFacts {
+  kind: BondFundClass;
+  /** A single-state municipal fund's state (`CA`, `NY`); null for a national fund. */
+  state: string | null;
+  /** Percent. */
+  secYield: FundFact<number> | null;
+  /** Percent. */
+  yieldToWorst: FundFact<number> | null;
+  /** Years: `effective` (option-adjusted) duration, or Vanguard's month-end `average` duration. */
+  duration: (FundFact<number> & { measure: "effective" | "average" }) | null;
+}
+
+/**
+ * `not-collected-yet`: a source Gloom reads covers the fund, but it has no
+ * figures yet. `not-published`: no source Gloom reads covers it. Servers
+ * before statuses leave it out.
+ */
+type FundFactsStatus = "covered" | "not-collected-yet" | "not-published" | "not-a-fund";
+
+/** GET /cloud/fund-facts/:ticker. Percent fields are in percent (0.03 is 0.03%). */
+export interface FundFactsPayload {
+  ticker: string;
+  covered: boolean;
+  status?: FundFactsStatus;
+  /** Why there are no facts, when `covered` is false. */
+  reason?: string;
+  name: string | null;
+  /** `trust`: an exchange-traded trust or pool outside the 1940 Act, charging a sponsor fee. */
+  structure: FundStructure | null;
+  /** `document`: read from the fund's prospectus filed with the SEC on `asOf`, not from its sponsor. */
+  expenseRatio: (FundFact<number> & { kind: ExpenseRatioKind; document?: "prospectus" }) | null;
+  nav: FundFact<number> | null;
+  closingPrice: FundFact<number> | null;
+  /** `published` by the sponsor, or `computed` from the closing price against the NAV. */
+  premiumDiscount: (FundFact<number> & { basis: "published" | "computed" }) | null;
+  /**
+   * `period`: a `day`'s figure, or the last `month-end`'s (Vanguard and ARK
+   * ETFs, N-PORT), which is not today's. `document`: the fund's N-PORT report
+   * to the SEC for that month end.
+   */
+  netAssets: (FundFact<number> & { scope: "share-class" | "fund" | null; period?: "day" | "month-end"; document?: "N-PORT" }) | null;
+  sponsor: FundFact<string> | null;
+  inception: FundFact<string> | null;
+  index: FundFact<string> | null;
+  /** A bond fund's SEC yield, yield to worst and duration; null for any other fund. Servers before it leave it out. */
+  bond?: FundBondFacts | null;
+  /** The newest NAV is older than a few US trading days: every figure is older than it looks. */
+  stale: boolean;
+  fetchedAt: string | null;
+}