gloomberb 0.17.2 → 0.17.4

package/src/utils/forward-dividend.ts

@@ -1,11 +1,16 @@
+import type { DeclaredDividendAction } from "../types/financials";
+import { formatDistributionAmount } from "./format";
+
 /**
  * What a forward dividend yield is everywhere it shows (fundamentals, DVD):
  * the indicated annual rate Gloom Cloud serves over the price, dated by the
  * ex-date of the distribution it annualizes. While no other is announced that
  * is the latest distribution, whose ex-date has passed. Once the next one is
  * declared the rate annualizes it, and its ex-date is still ahead: the basis
- * then names the declared distribution by its ex-date and pay date, never a
- * rate "as of" a day that has not come.
+ * then names the declared distribution by its ex-date and pay date, and by its
+ * amount when Gloom Cloud states one for that ex-date, never a rate "as of" a
+ * day that has not come. The amount is only ever the stated one, never the
+ * rate divided back.
  */
 const LATEST_DISTRIBUTION = "latest distribution annualized";
 
@@ -20,25 +25,43 @@ function isDeclared(exDate: string | null, now: Date): exDate is string {
   return exDate != null && exDate > now.toISOString().slice(0, 10);
 }
 
+interface DeclaredBasisOptions {
+  /** The declared distributions Gloom Cloud states (`declaredDividends`); only the one on the rate's ex-date counts. */
+  declared?: readonly DeclaredDividendAction[];
+  /** The currency their amounts are in; without it no amount is named. */
+  currency?: string | null;
+  now?: Date;
+}
+
+/** The declared row on the rate's ex-date, as `$0.98`, with its pay date; null when none is stated. */
+function statedDeclaration(exDate: string, options: DeclaredBasisOptions): { amount: string; payDate: string | null } | null {
+  const row = options.currency ? options.declared?.find((declared) => declared.exDate === exDate) : undefined;
+  return row ? { amount: formatDistributionAmount(row.amount, options.currency!), payDate: isoDay(row.payDate) } : null;
+}
+
 /**
  * `latest distribution annualized, as of 2026-08-20`, or for a rate dated
- * ahead, `annualized from the declared distribution payable 2026-12-10, ex
- * 2026-11-19`; the basis alone when the date is unknown. `payDate` is the pay
- * date stated beside that ex-date, for a source that pairs them.
+ * ahead, `annualized from the declared $0.98 payable 2026-12-10, ex
+ * 2026-11-19`, the amount and pay date when they are stated; the basis alone
+ * when the date is unknown. `payDate` is the pay date a source states beside
+ * that ex-date without a declared row (DVD's summary).
  */
 export function forwardDividendBasis(
   asOf: string | Date | null | undefined,
-  options: { payDate?: string | Date | null; now?: Date } = {},
+  options: DeclaredBasisOptions & { payDate?: string | Date | null } = {},
 ): string {
   const exDate = isoDay(asOf);
   if (!isDeclared(exDate, options.now ?? new Date())) return exDate ? `${LATEST_DISTRIBUTION}, as of ${exDate}` : LATEST_DISTRIBUTION;
-  const payDate = isoDay(options.payDate);
-  return `annualized from the declared distribution${payDate ? ` payable ${payDate}` : ""}, ex ${exDate}`;
+  const stated = statedDeclaration(exDate, options);
+  const payDate = stated?.payDate ?? isoDay(options.payDate);
+  return `annualized from the declared ${stated?.amount ?? "distribution"}${payDate ? ` payable ${payDate}` : ""}, ex ${exDate}`;
 }
 
-/** The same basis as a pane's short note under the figure: `as of 2026-08-20`, or `declared` beside the next ex-date it shows. */
-export function forwardDividendNote(asOf: string | Date | null | undefined, now = new Date()): string | null {
+/** The same basis as a pane's short note under the figure: `as of 2026-08-20`, or `declared $0.98` beside the next ex-date it shows. */
+export function forwardDividendNote(asOf: string | Date | null | undefined, options: DeclaredBasisOptions = {}): string | null {
   const exDate = isoDay(asOf);
   if (!exDate) return null;
-  return isDeclared(exDate, now) ? "declared" : `as of ${exDate}`;
+  if (!isDeclared(exDate, options.now ?? new Date())) return `as of ${exDate}`;
+  const stated = statedDeclaration(exDate, options);
+  return stated ? `declared ${stated.amount}` : "declared";
 }

package/src/utils/fundamentals.ts

@@ -40,18 +40,29 @@ export function enterpriseValueCheck(
   return fundamentals?.enterpriseValue === check.source ? check : undefined;
 }
 
+/**
+ * Whether the provider's EV was withdrawn: retracted (`unavailableFields`) and none served in its place, by the
+ * served check or by Gloom Cloud's own validation of the source observation, which leaves no check.
+ */
+export function enterpriseValueWithdrawn(fundamentals: Parameters<typeof enterpriseValueCheck>[0]): boolean {
+  return fundamentals?.enterpriseValue === undefined && !!fundamentals?.unavailableFields?.includes("enterpriseValue");
+}
+
 /** "(provider)" beside an EV more than 5% from market cap + debt - cash, or "unavailable" for a withdrawn one. */
 export function enterpriseValueLabel(fundamentals: Parameters<typeof enterpriseValueCheck>[0]): "provider" | "unavailable" | undefined {
   const status = enterpriseValueCheck(fundamentals)?.status;
-  return status === "differs" ? "provider" : status === "withdrawn" ? "unavailable" : undefined;
+  return status === "differs" ? "provider" : status === "withdrawn" || enterpriseValueWithdrawn(fundamentals) ? "unavailable" : undefined;
 }
 
 /**
  * The reconciliation line under a labelled or withdrawn EV: "EV 61.75B USD (provider) vs 63.75B computed from market
- * cap + total debt - cash (balance sheet 2026-06-30)." Undefined when the EV matches, is unchecked, or has no check.
+ * cap + total debt - cash (balance sheet 2026-06-30)." For an EV withdrawn without a check, that the source failed
+ * validation. Undefined when the EV matches, is unchecked, or has no check. Read it from the fundamentals the rows
+ * show (atRegularSessionPrice moves the check with the EV and the market cap), so its figures are theirs.
  */
 export function enterpriseValueReconciliationNote(fundamentals: Parameters<typeof enterpriseValueCheck>[0]): string | undefined {
   const check = enterpriseValueCheck(fundamentals);
+  if (!check && enterpriseValueWithdrawn(fundamentals)) return "EV unavailable: the provider's figure failed validation.";
   if (!check || !finiteNumber(check.computed) || (check.status !== "differs" && check.status !== "withdrawn")) return undefined;
   const source = `${formatCompact(check.source)} ${check.currency}`;
   const computed = formatCompact(check.computed);

package/src/utils/futures-generic.ts

@@ -28,9 +28,11 @@ export interface FuturesGeneric {
 
 /** Roots Gloom Cloud archives daily, by the venue that lists them. */
 const ROOT_VENUES: Readonly<Record<string, string>> = Object.fromEntries(([
-  ["CME", ["ES", "NQ", "RTY", "6E", "6J", "6B", "6A", "6C", "6S", "SR3", "LE", "GF", "HE", "LBR", "DC", "CSC", "GD", "BTC", "ETH", "SOL", "XRP"]],
-  ["CBT", ["YM", "ZT", "ZF", "ZN", "ZB", "UB", "ZQ", "ZC", "ZS", "ZW", "ZM", "ZL", "KE", "ZO", "ZR"]],
-  ["NYM", ["CL", "BZ", "NG", "RB", "HO", "PL", "PA", "B0", "TTF"]],
+  ["CME", ["ES", "NQ", "RTY", "EMD", "RS1", "NKD", "NIY", "MES", "MNQ", "M2K",
+    "XAE", "XAB", "XAI", "XAY", "XAP", "XAV", "XAF", "XAK", "XAZ", "XAU", "XAR", "SXO", "SXR", "SXT", "SXB", "SXI", "SOX",
+    "6E", "6J", "6B", "6A", "6C", "6S", "SR3", "LE", "GF", "HE", "LBR", "DC", "CSC", "GD", "BTC", "ETH", "SOL", "XRP"]],
+  ["CBT", ["YM", "MYM", "RX", "ZT", "ZF", "ZN", "ZB", "UB", "ZQ", "ZC", "ZS", "ZW", "ZM", "ZL", "KE", "ZO", "ZR"]],
+  ["NYM", ["CL", "QM", "MCL", "BZ", "NG", "QG", "MNG", "HH", "RB", "HO", "PL", "PA", "B0", "TTF"]],
   ["CMX", ["GC", "SI", "HG", "ALI", "HRC", "UX"]],
   ["NYB", ["KC", "SB", "CC", "CT", "OJ"]],
   ["CFE", ["VX"]],
@@ -128,16 +130,35 @@ function futuresGenericOrdinal(position: number): string {
   return `${position}${tens >= 11 && tens <= 13 ? "th" : ["th", "st", "nd", "rd"][position % 10] ?? "th"}`;
 }
 
+/** Equity index, sector and industry futures, the S&P GSCI and VIX: their prices are index points. */
+const POINT_ROOTS: ReadonlySet<string> = new Set(["ES", "NQ", "RTY", "YM", "GD", "VX", "EMD", "RS1", "NKD", "NIY", "MES", "MNQ", "M2K", "MYM", "RX",
+  "XAE", "XAB", "XAI", "XAY", "XAP", "XAV", "XAF", "XAK", "XAZ", "XAU", "XAR", "SXO", "SXR", "SXT", "SXB", "SXI", "SOX"]);
+
 /**
  * How a generic's price reads: index and VIX futures in points (not dollars),
  * Treasury futures in 32nds of par; everything else in its quote currency.
  */
 export function futuresGenericPriceBasis(generic: Pick<FuturesGeneric, "root">): "points" | "thirty-seconds" | null {
-  if (["ES", "NQ", "RTY", "YM", "GD", "VX"].includes(generic.root)) return "points";
+  if (POINT_ROOTS.has(generic.root)) return "points";
   if (["ZT", "ZF", "ZN", "ZB", "UB"].includes(generic.root)) return "thirty-seconds";
   return null;
 }
 
+/**
+ * How a futures listing's price reads, whichever form it takes: a generic by
+ * its root (VX1 points, TY1 32nds), and a continuous (`ES=F`, `SXO=F`) or
+ * listed contract (`SXOZ26.CME`) of an index, sector or industry root in index
+ * points, on the root's own venue or with none. The quote keeps its currency
+ * for what a tick is worth. Null for every other listing, a security that
+ * shares a root's code on another venue (XAU on Toronto, the XAR ETF) included.
+ */
+export function futuresListingPriceBasis(symbol: string, exchange?: string | null): "points" | "thirty-seconds" | null {
+  const generic = futuresGenericListing(symbol, exchange);
+  if (generic) return futuresGenericPriceBasis(generic);
+  const listing = futuresListingVenue(symbol, exchange);
+  return listing?.root && ROOT_VENUES[listing.root] === listing.venue && POINT_ROOTS.has(listing.root) ? "points" : null;
+}
+
 /** Whether a root's date rules count back from first notice or from last trade. */
 export function futuresGenericNotice(root: string): "first notice" | "last trade" {
   return FIRST_NOTICE_ROOTS.has(root) ? "first notice" : "last trade";

package/src/utils/markdown.ts

@@ -0,0 +1,180 @@
+/**
+ * The markdown every renderer of it reads: inline marks (the reader, buildout
+ * and Ask Gloom panes through components/markdown-text.tsx, and chat), and the
+ * line structure chat draws (headings, lists, quotes and fenced code).
+ */
+
+export interface MarkdownSegment {
+  text: string;
+  bold?: boolean;
+  italic?: boolean;
+  strike?: boolean;
+  code?: boolean;
+  /** Where the segment links to, when links are read. */
+  link?: string;
+}
+
+export interface InlineMarkdownOptions {
+  /**
+   * Reads `[label](href)` as a link: every one, or those whose href this
+   * accepts. A link not read stays the text it was written as.
+   */
+  links?: boolean | ((href: string) => boolean);
+}
+
+// A backslash escapes the punctuation markdown would read ("\\*" is a star).
+// A bracket after a bang is a picture, which stays as written. A bare address
+// is read whole, so the underscores and stars in it are not marks. A mark
+// opens before a character and closes after one, so "2 * 3 * 4" is
+// arithmetic, and an underscore inside a word (snake_case, a_b_c) is not one.
+// An italic span may hold a bold one ("*covers **96%** of value*").
+const INLINE_RE = new RegExp([
+  String.raw`\\(?<escaped>[\\` + "`" + String.raw`*_~#>[\]()-])`,
+  String.raw`(?<!!)\[(?<linkLabel>[^\]]+)\]\((?<linkHref>(?:[^()\s]|\([^()\s]*\))+)\)`,
+  String.raw`(?<url>\b(?:https?:\/\/|www\.)[^\s<>"']+)`,
+  "(?<!`)(?<ticks>`{1,3})(?!`)(?<code>[^`]|[^`].*?[^`])\\k<ticks>(?!`)",
+  String.raw`\*\*(?![\s*])(?<bold>[^*]+?)(?<!\s)\*\*`,
+  String.raw`(?<!\*)\*(?![\s*])(?<italic>(?:[^*]|\*\*[^*]+\*\*)+?)(?<!\s)\*(?!\*)`,
+  String.raw`(?<![A-Za-z0-9_])_(?![\s_])(?<underscored>[^_]+?)(?<!\s)_(?![A-Za-z0-9_])`,
+  String.raw`~~(?![\s~])(?<strike>[^~]+?)(?<!\s)~~`,
+].join("|"), "gi");
+
+function readsLink(options: InlineMarkdownOptions, href: string): boolean {
+  return typeof options.links === "function" ? options.links(href) : options.links === true;
+}
+
+/** Code keeps its text; one space inside each tick, as in "`` `a` ``", is padding. */
+function codeText(code: string): string {
+  return code.length > 2 && code.startsWith(" ") && code.endsWith(" ") && code.trim() ? code.slice(1, -1) : code;
+}
+
+export function parseInlineMarkdown(text: string, options: InlineMarkdownOptions = {}): MarkdownSegment[] {
+  const segments: MarkdownSegment[] = [];
+  let cursor = 0;
+  const marked = (inner: string, mark: Partial<MarkdownSegment>) => {
+    for (const segment of parseInlineMarkdown(inner, options)) segments.push({ ...segment, ...mark });
+  };
+
+  const pattern = new RegExp(INLINE_RE.source, INLINE_RE.flags);
+  let match: RegExpExecArray | null;
+  while ((match = pattern.exec(text)) !== null) {
+    const groups = match.groups ?? {};
+    if (groups.linkHref != null && !readsLink(options, groups.linkHref)) {
+      // Not read as a link: the bracket is text, and what is inside it still styles.
+      pattern.lastIndex = match.index + 1;
+      continue;
+    }
+    if (match.index > cursor) {
+      segments.push({ text: text.slice(cursor, match.index) });
+    }
+    if (groups.escaped != null) {
+      segments.push({ text: groups.escaped });
+    } else if (groups.linkHref != null) {
+      for (const inner of parseInlineMarkdown(groups.linkLabel ?? "")) segments.push({ ...inner, link: groups.linkHref });
+    } else if (groups.url != null) {
+      segments.push({ text: groups.url });
+    } else if (groups.code != null) {
+      segments.push({ text: codeText(groups.code), code: true });
+    } else if (groups.bold != null) {
+      marked(groups.bold, { bold: true });
+    } else if (groups.italic != null) {
+      marked(groups.italic, { italic: true });
+    } else if (groups.underscored != null) {
+      marked(groups.underscored, { italic: true });
+    } else if (groups.strike != null) {
+      marked(groups.strike, { strike: true });
+    }
+    cursor = match.index + match[0].length;
+  }
+  if (cursor < text.length) {
+    segments.push({ text: text.slice(cursor) });
+  }
+  // Plain runs split by an address or an escape read as one.
+  return segments.reduce<MarkdownSegment[]>((joined, segment) => {
+    const previous = joined[joined.length - 1];
+    if (previous && isPlain(previous) && isPlain(segment)) previous.text += segment.text;
+    else joined.push({ ...segment });
+    return joined;
+  }, []);
+}
+
+function isPlain(segment: MarkdownSegment): boolean {
+  return !segment.bold && !segment.italic && !segment.strike && !segment.code && segment.link === undefined;
+}
+
+export const MARKDOWN_HEADING_RE = /^(#{1,3})\s+(.+)$/;
+
+const LIST_ITEM_RE = /^(\s*)([-*]|\d+\.)\s(.*)$/;
+
+/** A list item's indent, marker ("-", "*" or "1.") and text, or null for any other line. */
+export function markdownListItem(line: string): { indent: number; marker: string; text: string } | null {
+  const match = line.match(LIST_ITEM_RE);
+  return match ? { indent: match[1]!.length, marker: match[2]!, text: match[3]! } : null;
+}
+
+export type MarkdownLine =
+  | { kind: "text"; text: string }
+  | { kind: "blank" }
+  | { kind: "heading"; text: string }
+  | { kind: "list"; indent: number; marker: string; text: string }
+  | { kind: "quote"; text: string }
+  /** A line inside a fenced code block, as written. */
+  | { kind: "code"; text: string };
+
+const FENCE_OPEN_RE = /^\s{0,3}```[^`]*$/;
+const FENCE_CLOSE_RE = /^\s{0,3}```\s*$/;
+const QUOTE_RE = /^>(?: (.*))?$/;
+
+/**
+ * A message's lines and what each is. The fence lines of a code block are
+ * dropped; a fence that never closes stays a line of text, so it cannot turn
+ * the rest of the message into code.
+ */
+export function parseMarkdownLines(text: string): MarkdownLine[] {
+  const lines = text.split("\n");
+  const parsed: MarkdownLine[] = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index]!;
+    if (FENCE_OPEN_RE.test(line)) {
+      const close = lines.findIndex((candidate, next) => next > index && FENCE_CLOSE_RE.test(candidate));
+      if (close > index) {
+        for (const code of lines.slice(index + 1, close)) parsed.push({ kind: "code", text: code });
+        index = close;
+        continue;
+      }
+    }
+    if (line.trim() === "") {
+      parsed.push({ kind: "blank" });
+      continue;
+    }
+    const heading = line.match(MARKDOWN_HEADING_RE);
+    if (heading) {
+      parsed.push({ kind: "heading", text: heading[2]! });
+      continue;
+    }
+    const quote = line.match(QUOTE_RE);
+    if (quote) {
+      parsed.push({ kind: "quote", text: quote[1] ?? "" });
+      continue;
+    }
+    const item = markdownListItem(line);
+    parsed.push(item ? { kind: "list", ...item } : { kind: "text", text: line });
+  }
+  return parsed;
+}
+
+/**
+ * The text without its marks, for wherever it shows as one plain line (a
+ * reply's quote, a notification). A link reads as its label.
+ */
+export function markdownPlainText(text: string, options: InlineMarkdownOptions = {}): string {
+  const plain = (line: string) => parseInlineMarkdown(line, options).map((segment) => segment.text).join("");
+  return parseMarkdownLines(text).map((line) => {
+    switch (line.kind) {
+      case "blank": return "";
+      case "code": return line.text;
+      case "list": return `${" ".repeat(line.indent)}${line.marker} ${plain(line.text)}`;
+      default: return plain(line.text);
+    }
+  }).join("\n");
+}

package/src/utils/market-capitalization.ts

@@ -1,4 +1,5 @@
 import type { Fundamentals, Quote } from "../types/financials";
+import { formatCompact, formatNumber } from "./format";
 
 export interface MarketCapitalization {
   value: number;
@@ -64,3 +65,24 @@ export function convertMarketCapitalization(
 export function listedMarketCapitalization(value: number | null): number | null {
   return value != null && Number.isFinite(value) && value > 0 ? value : null;
 }
+
+/** How far a market cap may sit from the share count times the price and still rest on that count. */
+const SHARE_COUNT_TOLERANCE = 0.02;
+
+/**
+ * Where a market cap does not rest on the share count shown beside it (one class's count beside an all-class cap):
+ * "Market cap 137.20B USD is the provider's and does not rest on the 799.93M shares shown (x 110.11 USD = 88.08B)."
+ * Undefined when they tie, or without a count and a price in the cap's currency to test.
+ */
+export function marketCapShareBasisNote(
+  capitalization: Pick<MarketCapitalization, "value" | "currency"> | null,
+  shares: number | undefined,
+  price: number | null | undefined,
+  priceCurrency: string | undefined,
+): string | undefined {
+  if (!capitalization || !(capitalization.value > 0) || capitalization.currency !== priceCurrency) return undefined;
+  if (shares == null || !Number.isFinite(shares) || !(shares > 0) || price == null || !Number.isFinite(price) || !(price > 0)) return undefined;
+  const product = shares * price;
+  if (Math.abs(capitalization.value / product - 1) <= SHARE_COUNT_TOLERANCE) return undefined;
+  return `Market cap ${formatCompact(capitalization.value)} ${capitalization.currency} is the provider's and does not rest on the ${formatCompact(shares)} shares shown (x ${formatNumber(price, price < 1 ? 4 : 2)} ${priceCurrency} = ${formatCompact(product)}).`;
+}

package/src/utils/plugin-proxy-hosts.json

@@ -1,16 +1,21 @@
 {
   "hosts": [
+    "api.crypto.com",
     "api.elections.kalshi.com",
     "api.fda.gov",
     "api.fiscaldata.treasury.gov",
+    "api.gemini.com",
+    "api.limitless.exchange",
     "api.publisher.jodidata.org",
     "api.votehub.com",
     "apps.fas.usda.gov",
     "clinicaltrials.gov",
     "clob.polymarket.com",
     "data-api.polymarket.com",
+    "data.pascal.trade",
     "efts.sec.gov",
     "gamma-api.polymarket.com",
+    "gateway.polymarket.us",
     "markets.newyorkfed.org",
     "nasdaqtrader.com",
     "production.dataviz.cnn.io",

package/src/utils/utc-time.ts

@@ -83,13 +83,13 @@ export function setDisplayTimeZone(zone: string | null | undefined): void {
 /**
  * ` (Sun 11 Oct 01:56 Asia/Tokyo)`: an instant on the reader's clock, to follow
  * its UTC time, with the weekday and date because the two can fall on
- * different days. Empty when no zone is set.
+ * different days; to the second with `seconds`. Empty when no zone is set.
  */
-export function localTimeSuffix(time: number): string {
+export function localTimeSuffix(time: number, seconds = false): string {
   if (!displayZone || !Number.isFinite(time)) return "";
   const local = zonedDateTimeParts(time, displayZone);
   const weekday = WEEKDAYS[new Date(Date.UTC(local.year, local.month - 1, local.day)).getUTCDay()];
-  const clock = `${String(local.hour).padStart(2, "0")}:${String(local.minute).padStart(2, "0")}`;
+  const clock = [local.hour, local.minute, ...(seconds ? [local.second] : [])].map((part) => String(part).padStart(2, "0")).join(":");
   return ` (${weekday} ${local.day} ${MONTHS[local.month - 1]} ${clock} ${displayZone})`;
 }
 
@@ -106,6 +106,17 @@ export function formatUtcTime(value: ReportTime | Date | number | string): strin
   return `${iso.slice(0, 16).replace("T", " ")} UTC${localTimeSuffix(parsed.time)}`;
 }
 
+/**
+ * `2026-10-09 00:08:00 UTC`: `formatUtcTime` to the second, for a column whose
+ * times are to the second, so a time that fell on a whole minute reads like
+ * the rest. Text that is not a time comes back as it is.
+ */
+export function formatUtcSeconds(value: unknown): string {
+  const parsed = parseReportTime(value);
+  if (!parsed || parsed.dateOnly) return typeof value === "string" ? value : "";
+  return `${new Date(parsed.time).toISOString().slice(0, 19).replace("T", " ")} UTC${localTimeSuffix(parsed.time, true)}`;
+}
+
 /**
  * `Fri 9 Oct 23:59` in UTC, or `Fri 9 Oct` for a date, for a table cell whose
  * header names the zone: a time without its zone, so each row stays short. The