gloomberb 0.17.2 → 0.17.3

package/src/utils/declared-dividends.ts

@@ -0,0 +1,39 @@
+import type { CorporateActionsData, DeclaredDividendAction } from "../types/financials";
+
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+/** A paid row this close to a declared one is that distribution, dated a day apart. */
+const SAME_DISTRIBUTION_DAYS = 3;
+const DAY_MS = 86_400_000;
+
+function isoDate(value: unknown): string | undefined {
+  return typeof value === "string" && ISO_DATE.test(value) && Number.isFinite(Date.parse(`${value}T00:00:00Z`)) ? value : undefined;
+}
+
+/**
+ * The declared, unpaid distributions a corporate actions payload carries,
+ * oldest first: rows the source states with a real ex-date and amount, still
+ * owed today (not yet paid, or with no pay date, not yet ex), and not in the
+ * paid history yet. Kept apart from `dividends`, which history, yields and
+ * growth read. A server that does not send them, or a listing it has none
+ * for, gives none.
+ */
+export function declaredDividends(
+  actions: Pick<CorporateActionsData, "dividends" | "declaredDividends"> | null | undefined,
+  now = new Date(),
+): DeclaredDividendAction[] {
+  if (!Array.isArray(actions?.declaredDividends)) return [];
+  const today = now.toISOString().slice(0, 10);
+  const paid = (actions.dividends ?? []).map((payment) => Date.parse(`${payment.exDate}T00:00:00Z`));
+  return actions.declaredDividends.flatMap((row): DeclaredDividendAction[] => {
+    const exDate = isoDate(row?.exDate);
+    if (!exDate || typeof row.amount !== "number" || !Number.isFinite(row.amount) || row.amount <= 0) return [];
+    const payDate = isoDate(row.payDate);
+    const declarationDate = isoDate(row.declarationDate);
+    const recordDate = isoDate(row.recordDate);
+    if ((payDate ?? exDate) < today) return [];
+    const at = Date.parse(`${exDate}T00:00:00Z`);
+    if (paid.some((time) => Math.abs(time - at) <= SAME_DISTRIBUTION_DAYS * DAY_MS)) return [];
+    return [{ exDate, amount: row.amount, ...declarationDate ? { declarationDate } : {},
+      ...recordDate ? { recordDate } : {}, ...payDate ? { payDate } : {} }];
+  }).sort((left, right) => left.exDate.localeCompare(right.exDate));
+}

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/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)}).`;
+}