gloomberb 0.18.2 → 0.18.4

package/src/utils/option-expiry.ts

@@ -4,7 +4,11 @@
  * convert both ways, and two stamps on the same UTC date are the same expiry.
  */
 
-import { readCalendarDate } from "./calendar-date";
+import type { OptionsChain } from "../types/financials";
+import { hasRegularCloseHour, latestRegularSessionClose, sessionCalendarTimeZone } from "../market-data/market/freshness";
+import { dateOptionHint, readCalendarDate } from "./calendar-date";
+import { canonicalExchange, isUsListingExchange } from "./exchanges";
+import { zonedWallClockToUtcMs } from "./zoned-date-time";
 
 // 9999-12-31 in Unix seconds; a longer number is milliseconds or a typo.
 const MAX_UNIX_SECONDS = 253_402_300_799;
@@ -40,13 +44,23 @@ export function parseOptionExpiration(raw: string): number | null {
   return seconds > 0 && seconds <= MAX_UNIX_SECONDS ? seconds : null;
 }
 
+/**
+ * The sentence that follows an unreadable expiry: the date to type for one
+ * written another way that plainly names it (`Type --expiration 2026-10-22 for
+ * 22/10/2026.`), led by a space, or nothing for anything else.
+ */
+export function expirationHint(value: string, flag = "expiration"): string {
+  const hint = dateOptionHint(value, `--${flag}`);
+  return hint ? ` ${hint[0]!.toUpperCase()}${hint.slice(1)}.` : "";
+}
+
 /**
  * A pane function's typed expiry flag as the Unix seconds `parseOptionExpiration`
  * reads; throws an Error naming both accepted forms.
  */
 export function expirationOptionSeconds(value: string, flag = "expiration"): number {
   const expiration = parseOptionExpiration(value);
-  if (expiration == null) throw new Error(`Invalid --${flag} "${value}". Use ${OPTION_EXPIRATION_FORMAT}.`);
+  if (expiration == null) throw new Error(`Invalid --${flag} "${value}". Use ${OPTION_EXPIRATION_FORMAT}.${expirationHint(value, flag)}`);
   return expiration;
 }
 
@@ -70,10 +84,128 @@ export function daysToExpiry(expiration: number, asOfMs: number): number {
   return Math.round((expiry - asOf) / DAY_MS);
 }
 
-/** `469d` to expiry from the as-of date; `expired` once it has passed. */
-export function formatDaysToExpiry(expiration: number, asOfMs: number): string {
-  const days = daysToExpiry(expiration, asOfMs);
-  return days < 0 ? "expired" : `${days}d`;
+/** `469d` to expiry from the as-of date; `expired` once its last session has closed (`isLiveOptionExpiry`). */
+export function formatDaysToExpiry(expiration: number, asOfMs: number, exchange?: string): string {
+  return isLiveOptionExpiry(expiration, asOfMs, exchange) ? `${Math.max(0, daysToExpiry(expiration, asOfMs))}d` : "expired";
+}
+
+/** Listed US options trade on the US equity calendar, NYSE's published one. */
+const US_OPTIONS_CALENDAR = "NYSE";
+const lastSessions = new Map<string, { date: string; close: number } | null>();
+
+/**
+ * The venue whose calendar an expiry's last session is read on: a listing's
+ * own venue abroad when its zone and close hour are known (XETRA, JPX), else
+ * the US one listed options trade on, which also stands for a chain read
+ * without a venue.
+ */
+function expiryCalendarVenue(exchange: string | undefined): string {
+  const venue = canonicalExchange(exchange);
+  return venue && !isUsListingExchange(venue) && hasRegularCloseHour(venue) && sessionCalendarTimeZone(venue)
+    ? venue : US_OPTIONS_CALENDAR;
+}
+
+/** The expiry's last trading session, on or before its date, on its venue's calendar: the date and when it closed. */
+function expiryLastSession(expiration: number, exchange: string | undefined): { date: string; close: number } | null {
+  const date = expiryIsoDate(expiration);
+  if (!date) return null;
+  const venue = expiryCalendarVenue(exchange);
+  const key = `${venue}:${date}`;
+  const known = lastSessions.get(key);
+  if (known !== undefined) return known;
+  const timeZone = sessionCalendarTimeZone(venue)!;
+  // Midnight ending the expiry's date on the venue's clock: its session that day, else the latest before it.
+  const dayEnd = zonedWallClockToUtcMs(timeZone, Number(date.slice(0, 4)), Number(date.slice(5, 7)), Number(date.slice(8, 10)) + 1, 0, 0, 0);
+  const session = latestRegularSessionClose(venue, dayEnd);
+  const last = session ? { date: session.date, close: session.close } : null;
+  // The calendar is static, and every list and picker asks about the same few dates.
+  if (lastSessions.size < 4096) lastSessions.set(key, last);
+  return last;
+}
+
+/**
+ * When an expiry stops trading: the regular close of its last session, the
+ * listing venue's last trading day on or before the expiry's date, on that
+ * venue's clock and calendar. A US expiry closes at 16:00 New York, at 13:00
+ * on a published early close, and one dated on a holiday or a weekend closed
+ * with the session before it. Null for a stamp that is not a date.
+ */
+export function optionExpiryCloseMs(expiration: number, exchange?: string): number | null {
+  return expiryLastSession(expiration, exchange)?.close ?? null;
+}
+
+/**
+ * The rule every expiry list, picker and default chain follows: an expiry is
+ * live until its last session has closed (`optionExpiryCloseMs`). After
+ * Friday's close Friday's expiry is gone, over the weekend and on Monday
+ * before the open too, while on its own day it stays until the close.
+ */
+export function isLiveOptionExpiry(expiration: number, now: number, exchange?: string): boolean {
+  if (!Number.isFinite(expiration) || expiration <= 0) return false;
+  const close = optionExpiryCloseMs(expiration, exchange);
+  return close != null && now < close;
+}
+
+/** The listed expiries still live (`isLiveOptionExpiry`), once each, in date order. */
+export function liveOptionExpiries(expirations: readonly number[], now: number, exchange?: string): number[] {
+  return [...new Set(expirations)].filter((expiration) => isLiveOptionExpiry(expiration, now, exchange)).sort((a, b) => a - b);
+}
+
+/** The chain with only its live expiries listed; the contracts are left as they are. */
+export function withLiveExpiryList<T extends Pick<OptionsChain, "expirationDates">>(chain: T, now: number, exchange?: string): T {
+  const live = liveOptionExpiries(chain.expirationDates, now, exchange);
+  return live.length === chain.expirationDates.length && live.every((expiration, index) => expiration === chain.expirationDates[index])
+    ? chain : { ...chain, expirationDates: live };
+}
+
+/**
+ * The expiry a chain asked for without a date shows instead of the one its
+ * source sent, by the same rule: undefined when the source's default is live
+ * or has no contracts, else the nearest live expiry it lists, to ask for by
+ * date, or null when none of them is live. A source can still answer with
+ * Friday's chain after Friday's close, all weekend.
+ */
+export function liveDefaultExpiry(
+  chain: Pick<OptionsChain, "calls" | "puts" | "expirationDates">, now: number, exchange?: string,
+): number | null | undefined {
+  const contracts = [...chain.calls, ...chain.puts];
+  if (contracts.length === 0 || contracts.some((contract) => isLiveOptionExpiry(contract.expiration, now, exchange))) return undefined;
+  return liveOptionExpiries(chain.expirationDates, now, exchange)[0] ?? null;
+}
+
+/** The first live listed expiry dated after `expiration`, for a chain that had nothing to offer. */
+export function nextLiveExpiry(expiration: number, expirations: readonly number[], now: number, exchange?: string): number | undefined {
+  const date = expiryIsoDate(expiration);
+  return liveOptionExpiries(expirations, now, exchange).find((listed) => expiryIsoDate(listed) > date);
+}
+
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+
+/** An expiry's date as a sentence names it: `23 Oct`, with the year when it is not the current one (`21 Jan 2028`). */
+export function expiryDayLabel(expiration: number | string, now: number): string {
+  const date = typeof expiration === "string" ? expiration : expiryIsoDate(expiration);
+  if (!date) return "";
+  const label = `${Number(date.slice(8, 10))} ${MONTHS[Number(date.slice(5, 7)) - 1]}`;
+  return date.slice(0, 4) === new Date(now).toISOString().slice(0, 4) ? label : `${label} ${date.slice(0, 4)}`;
+}
+
+/** An expiry to pick, and with a flag how to ask for it: `30 Oct (--expiration 2026-10-30)`. */
+export function expiryChoiceText(expiration: number, now: number, flag?: string): string {
+  return `${expiryDayLabel(expiration, now)}${flag ? ` (--${flag} ${expiryIsoDate(expiration)})` : ""}`;
+}
+
+/**
+ * Why an expired date shows no chain, naming the day its last session closed
+ * and the nearest live expiry, with the flag that asks for it when given:
+ * `expired on 23 Oct; nearest live: 30 Oct (--expiration 2026-10-30)`.
+ */
+export function expiredExpiryText(
+  requested: number, expirations: readonly number[], now: number, { exchange, flag }: { exchange?: string; flag?: string } = {},
+): string {
+  const last = expiryLastSession(requested, exchange);
+  const nearest = liveOptionExpiries(expirations, now, exchange)[0];
+  return `expired on ${expiryDayLabel(last?.date ?? requested, now)}; `
+    + (nearest == null ? "the chain lists no live expiry" : `nearest live: ${expiryChoiceText(nearest, now, flag)}`);
 }
 
 const NEAREST_EXPIRIES = 4;
@@ -137,6 +269,6 @@ export function missingExpiryMessage(
 ): { message: string; details: string } {
   return {
     message: missingExpiryText(requested, expirations, symbol),
-    details: `Run gloomberb options ${symbol} to list every expiry (--json carries them too).`,
+    details: `Run gloom options ${symbol} to list every expiry (--json carries them too).`,
   };
 }

package/src/utils/price-earnings.ts

@@ -1,5 +1,6 @@
 import type { Fundamentals } from "../types/financials";
 import { formatNumber } from "./format";
+import { enterpriseValueNotMeaningful } from "./fundamentals";
 
 export const PRICE_EARNINGS_NOTICE = "N/M = not meaningful. Non-positive P/E values are excluded from ranking.";
 
@@ -61,16 +62,19 @@ export function notMeaningfulMultiples(
 
 /**
  * The fundamentals block as JSON exports it: a multiple that is not meaningful
- * reads null, with the reason under `notMeaningful`, never as a number.
+ * reads null, with the reason under `notMeaningful`, never as a number. An
+ * enterprise value at or below zero does too, with EV/revenue over it.
  */
 export function exportedFundamentals<T extends Fundamentals>(
   fundamentals: T | undefined,
-): (Omit<T, PriceEarningsField> & Partial<Record<PriceEarningsField, number | null>> & {
-  notMeaningful?: Partial<Record<PriceEarningsField, string>>;
+): (Omit<T, PriceEarningsField | EnterpriseValueField> & Partial<Record<PriceEarningsField | EnterpriseValueField, number | null>> & {
+  notMeaningful?: Partial<Record<PriceEarningsField | EnterpriseValueField, string>>;
 }) | undefined {
   if (!fundamentals) return fundamentals;
-  const reasons = notMeaningfulMultiples(fundamentals);
-  const fields = Object.keys(reasons) as PriceEarningsField[];
+  const reasons: Partial<Record<PriceEarningsField | EnterpriseValueField, string>> = notMeaningfulMultiples(fundamentals);
+  const enterpriseValue = enterpriseValueNotMeaningful(fundamentals);
+  if (enterpriseValue) reasons.enterpriseValue = reasons.enterpriseToRevenue = enterpriseValue;
+  const fields = Object.keys(reasons) as Array<PriceEarningsField | EnterpriseValueField>;
   if (fields.length === 0) return fundamentals;
   return {
     ...fundamentals,
@@ -78,3 +82,5 @@ export function exportedFundamentals<T extends Fundamentals>(
     notMeaningful: reasons,
   };
 }
+
+type EnterpriseValueField = "enterpriseValue" | "enterpriseToRevenue";

package/src/utils/price-history.ts

@@ -313,6 +313,8 @@ function zonedWeekday(time: number, timeZone: string): number {
 }
 
 const CRYPTO_BAR_MAX_AGE_MS = 60 * 60 * 1000;
+// A coin's UTC day is served whole this long after midnight: the delay on bars that are not live.
+const CRYPTO_DAY_ROLL_MS = 15 * 60 * 1000;
 // A copy missing a settled session is asked again at most this often, and less
 // often as that close recedes, so a halted, delisted or late listing costs a
 // handful of requests per session rather than one per request.
@@ -404,12 +406,15 @@ function intradayHistoryFetchState(
 }
 
 /**
- * A daily or coarser series changes at every close. A copy fetched before the
- * latest settled close is outdated whatever its cache TTL. A copy fetched
- * after it but without its bar is behind only where the venue's closures are
- * published (hasPublishedSessionCalendar): elsewhere, and for a bare symbol whose venue is
- * unknown, a local holiday would read as a missing session. A copy of a 24/7
- * series goes out of date within the hour.
+ * A daily or coarser series changes at every close, and gains a bar for the
+ * day once a session opens. A copy fetched before the latest settled close is
+ * outdated whatever its cache TTL, and so is one fetched before a session that
+ * has opened since: it lacks today's bar, so a morning copy would answer for
+ * yesterday all day. A copy fetched after the latest settled close but without
+ * its bar is behind only where the venue's closures are published
+ * (hasPublishedSessionCalendar): elsewhere, and for a bare symbol whose venue
+ * is unknown, a local holiday would read as a missing session. A copy of a
+ * 24/7 series goes out of date within the hour.
  */
 export function calendarHistoryFetchState(
   points: PricePoint[],
@@ -424,13 +429,18 @@ export function calendarHistoryFetchState(
   if (intervalMs < DAY_MS) return intradayHistoryFetchState(normalized, fetchedAt, now, intervalMs, options);
   const exchange = canonicalExchange(options.exchange);
   if (isRoundTheClockCoin(options.symbol, options.exchange)) {
-    return now - fetchedAt > CRYPTO_BAR_MAX_AGE_MS
-      ? unsettledState(fetchedAt + CRYPTO_BAR_MAX_AGE_MS, options.checkedAt, now) : "current";
+    // A coin's day closes at UTC midnight, and the service has it by the delay after:
+    // a copy from before then holds that day as still forming.
+    const roll = Math.floor((now - CRYPTO_DAY_ROLL_MS) / DAY_MS) * DAY_MS + CRYPTO_DAY_ROLL_MS;
+    const settledAt = Math.min(fetchedAt + CRYPTO_BAR_MAX_AGE_MS, fetchedAt < roll ? roll : Number.POSITIVE_INFINITY);
+    return now >= settledAt ? unsettledState(settledAt, options.checkedAt, now) : "current";
   }
   // Bare symbols resolve to their US listing at the sources.
   const session = latestRegularSessionClose(exchange || "NYSE", now - SESSION_BAR_SETTLE_MS);
   if (!session) return "current";
   if (fetchedAt < session.close + SESSION_BAR_SETTLE_MS) return unsettledState(session.close + SESSION_BAR_SETTLE_MS, options.checkedAt, now);
+  const open = latestRegularSessionOpen(exchange || "NYSE", now);
+  if (open !== null && open > session.close && fetchedAt < open) return unsettledState(open, options.checkedAt, now);
   if (!exchange || !hasPublishedSessionCalendar(exchange, session.date)) return "current";
   const latest = normalized.findLast(hasFiniteClose);
   if (!latest || !isBarBeforeSession(getPricePointTimestamp(latest), session.date, intervalMs, session.timeZone)) return "current";

package/src/utils/price-window.ts

@@ -0,0 +1,131 @@
+import { dateOptionError, isoDateToday, readCalendarDate } from "./calendar-date";
+import { fetchHistoryResult } from "../sources/history-result";
+import type { DataProvider, MarketDataRequestContext } from "../types/data-provider";
+import type { PriceHistoryResult } from "../types/price-history";
+import { getPricePointTimestamp } from "./price-history";
+import { zonedDateKey } from "./zoned-date-time";
+
+/**
+ * A price-history window typed as `--from` and `--to`: a year (2007) or a date
+ * (2008-09-15, or any form `readCalendarDate` reads). A year runs from 1 Jan
+ * as a start and to 31 Dec as an end. Without `--to` the window runs to
+ * today; `--to` needs a `--from`. Dates are YYYY-MM-DD, both inclusive.
+ */
+export interface PriceWindow {
+  from: string;
+  to: string;
+}
+
+const YEAR = /^\d{4}$/;
+const DAY_MS = 86_400_000;
+
+/**
+ * Today as the window reads it: the reader's date (in `timeZone`, the host's
+ * when not given), or UTC's when that is later, so a date that has begun for
+ * the reader (east of UTC, or in UTC already) is never refused as still ahead.
+ */
+function priceWindowToday(now: Date, timeZone?: string): string {
+  const pad = (value: number) => String(value).padStart(2, "0");
+  const local = timeZone ? zonedDateKey(now.getTime(), timeZone) : `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+  const utc = isoDateToday(now);
+  return local > utc ? local : utc;
+}
+
+/** Whether the window closed before today in UTC: its bars are history, with no session still trading in them. */
+export function isPastPriceWindow(window: PriceWindow, now = new Date()): boolean {
+  return window.to < isoDateToday(now);
+}
+
+const FORMATS = "a year (2007) or a date (2008-09-15)";
+
+function readBound(value: string, edge: "start" | "end", flag: string, now: Date): string {
+  const text = value.trim();
+  if (YEAR.test(text)) return edge === "start" ? `${text}-01-01` : `${text}-12-31`;
+  const date = text ? readCalendarDate(text) : null;
+  if (date) return date;
+  throw new Error(`Invalid ${flag} "${value}". ${dateOptionError(text, flag, { now, subject: `the window's ${edge}`, formats: FORMATS, example: edge === "start" ? "2007" : "2009" })}`);
+}
+
+/**
+ * The window `--from` and `--to` name, or null when neither was given. Throws
+ * a message naming the option for a value that is no year or date, a `--to`
+ * alone, a start after the end, or a start still ahead. An end past today
+ * stops at today.
+ */
+export function readPriceWindow(
+  from: string | undefined,
+  to: string | undefined,
+  now = new Date(),
+  timeZone?: string,
+  /** The options as typed, for the messages: `--start` and `--end` where a command takes those too. */
+  flags: { from: string; to: string } = { from: "--from", to: "--to" },
+): PriceWindow | null {
+  if (from == null && to == null) return null;
+  const { from: fromFlag, to: toFlag } = flags;
+  if (from == null) throw new Error(`${toFlag} needs a ${fromFlag}: ${fromFlag} ${YEAR.test(to!.trim()) ? Number(to!.trim()) - 2 : 2007} ${toFlag} ${to!.trim()}.`);
+  const today = priceWindowToday(now, timeZone);
+  const start = readBound(from, "start", fromFlag, now);
+  const typedEnd = to == null ? today : readBound(to, "end", toFlag, now);
+  if (start > today) throw new Error(`${fromFlag} ${from.trim()} has not started yet. Use a start on or before ${today}.`);
+  if (start > typedEnd) {
+    throw new Error(`${fromFlag} ${from.trim()} is after ${toFlag} ${to!.trim()}. The window runs from the earlier to the later, such as ${fromFlag} ${to!.trim()} ${toFlag} ${from.trim()}.`);
+  }
+  return { from: start, to: typedEnd > today ? today : typedEnd };
+}
+
+/** The window in words: `2007 to 2009`, `2008-09-15 to 2009-03-31`, `2007 to today`. */
+export function priceWindowText(window: PriceWindow, now = new Date(), timeZone?: string): string {
+  const year = (date: string, edge: "start" | "end") => date.slice(5) === (edge === "start" ? "01-01" : "12-31") ? date.slice(0, 4) : date;
+  const end = window.to === priceWindowToday(now, timeZone) ? "today" : year(window.to, "end");
+  return `${year(window.from, "start")} to ${end}`;
+}
+
+/** Calendar days the window spans, both ends counted. */
+function priceWindowDays(window: PriceWindow): number {
+  return Math.round((Date.parse(`${window.to}T00:00:00Z`) - Date.parse(`${window.from}T00:00:00Z`)) / 86_400_000) + 1;
+}
+
+/** Daily bars up to five years, weekly up to twenty, monthly beyond: the sizes `history`'s 1Y, 5Y and ALL come in. */
+export function priceWindowInterval(window: PriceWindow): "1d" | "1wk" | "1mo" {
+  const days = priceWindowDays(window);
+  return days <= 5 * 366 ? "1d" : days <= 20 * 366 ? "1wk" : "1mo";
+}
+
+/**
+ * Where the bar of this size that holds `date` starts, at midnight UTC: the
+ * day itself, its week's Monday (weekly bars are dated by the Monday) or its
+ * month's 1st. A window keeps the week or month its first date falls in.
+ */
+export function priceWindowBarStart(date: string, interval: string): number {
+  const day = Date.parse(`${date}T00:00:00Z`);
+  if (interval === "1wk") return day - ((new Date(day).getUTCDay() + 6) % 7) * DAY_MS;
+  if (interval === "1mo") return Date.parse(`${date.slice(0, 7)}-01T00:00:00Z`);
+  return day;
+}
+
+/**
+ * The bars of a window, in the size `priceWindowInterval` picks: the source's
+ * bars for those dates, else, from a source that serves no dated request, its
+ * whole history in that size. Either way only bars inside the window are
+ * kept, with the week or month its first date falls in (`--from 2008-09-15`
+ * in monthly bars starts with September 2008's).
+ */
+export async function loadPriceWindowHistory(
+  provider: DataProvider, symbol: string, exchange: string, window: PriceWindow, context?: MarketDataRequestContext,
+): Promise<PriceHistoryResult> {
+  const interval = priceWindowInterval(window);
+  const start = new Date(priceWindowBarStart(window.from, interval));
+  const end = new Date(`${window.to}T23:59:59Z`);
+  const result = await fetchHistoryResult(provider, symbol, exchange, { kind: "detail", start, end, interval }, context)
+    ?? await fetchHistoryResult(provider, symbol, exchange, { kind: "resolution", range: "ALL", resolution: interval }, context)
+    ?? await fetchHistoryResult(provider, symbol, exchange, { kind: "range", range: "ALL" }, context);
+  const points = (result?.points ?? []).filter((point) => {
+    const time = getPricePointTimestamp(point);
+    return Number.isFinite(time) && time >= start.getTime() && time <= end.getTime();
+  });
+  return { ...(result ?? { resolution: null }), points };
+}
+
+/** Shared help text for `--from` and `--to`. */
+export const PRICE_WINDOW_FROM_HELP = `First year or date of the window, as ${FORMATS}; replaces --range`;
+export const PRICE_WINDOW_TO_HELP = "Last year or date of the window, with --from (default today)";

package/src/utils/release-date.ts

@@ -0,0 +1,47 @@
+import { parseReportTime } from "./utc-time";
+
+const WEEKDAYS = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"] as const;
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"] as const;
+
+/**
+ * When a statistic was released, said after the period it covers:
+ * `released Tue 20 Oct`, with the year when it is not the year of the period
+ * (`released Fri 15 Jan 2027` for December 2026's figure), and the time in
+ * UTC for a release known to the minute (`released Wed 14 Oct 12:30 UTC`).
+ * `periodStart` is the date the figure is dated by (`2026-09-01`). Null when
+ * `released` is not a date.
+ */
+export function releasedText(released: unknown, periodStart?: string | null): string | null {
+  const time = parseReportTime(released);
+  if (!time) return null;
+  const day = new Date(time.time);
+  const periodYear = periodStart ? Number(periodStart.slice(0, 4)) : Number.NaN;
+  const year = day.getUTCFullYear() === periodYear ? "" : ` ${day.getUTCFullYear()}`;
+  const date = `${WEEKDAYS[day.getUTCDay()]} ${day.getUTCDate()} ${MONTHS[day.getUTCMonth()]}${year}`;
+  return `released ${date}${time.dateOnly ? "" : ` ${day.toISOString().slice(11, 16)} UTC`}`;
+}
+
+/**
+ * The period a figure covers and when it was released, as every macro pane,
+ * report and footer says it: `Sep 2026, released Tue 20 Oct`. The period
+ * alone when the release is not known.
+ */
+export function periodReleasedText(period: string, released: unknown, periodStart?: string | null): string {
+  const text = releasedText(released, periodStart);
+  return text ? `${period}, ${text}` : period;
+}
+
+/**
+ * How often a figure dated by the first day of its period publishes, from the
+ * prints a year holds (12 for monthly): `monthly` for `2026-09-01`, `quarterly`
+ * for `2026-07-01`. Null for a weekly or daily print, or a date that starts no
+ * such period.
+ */
+export function periodStartPeriodicity(date: string, perYear: number): "monthly" | "quarterly" | "annual" | null {
+  const match = /^\d{4}-(\d{2})-01/.exec(date);
+  if (!match || perYear > 12) return null;
+  const month = Number(match[1]) - 1;
+  if (perYear <= 1) return month === 0 ? "annual" : null;
+  if (perYear <= 4) return month % 3 === 0 ? "quarterly" : null;
+  return "monthly";
+}

package/src/utils/sec.ts

@@ -141,6 +141,9 @@ export function listingAbroadVenue(key: string): string | null {
   return venue && zone && zone !== "UTC" && !US_TIME_ZONES.has(zone) ? venue : null;
 }
 
+/** What `ticker` and ETF say of a fund listed abroad: the facts Gloom collects are the US-listed funds'. */
+export const US_FUND_FACTS_ONLY = "Fund facts (fee, NAV, premium) cover US-listed funds only.";
+
 /**
  * The symbol data that covers US listings only reads a listing by: AAPL for
  * AAPL:NASDAQ, ^SPX as it is. A listing abroad throws, naming what covers US
@@ -163,6 +166,74 @@ export function noSecReportsNotice(listing: { symbol: string; exchange: string;
   return `${shortListingTitle(listing)} files no SEC reports.`;
 }
 
+/** The country of a venue abroad, ISO 3166 alpha-2, for the companies an SEC report may list there. */
+const VENUE_COUNTRY: Readonly<Record<string, string>> = {
+  TSX: "CA", TSXV: "CA", CSE: "CA", NEO: "CA",
+  LSE: "GB",
+  ASX: "AU", CXA: "AU", NZX: "NZ",
+  SWX: "CH",
+  XETRA: "DE", FWB2: "DE", EPA: "FR", AMS: "NL", BRU: "BE", LIS: "PT", BIT: "IT", MCE: "ES", ISE: "IE",
+  SFB: "SE", HEL: "FI", CPH: "DK", OSL: "NO", ICEX: "IS", WSE: "PL", PSE: "CZ", VIE: "AT", WBDM: "AT",
+  JPX: "JP", HKEX: "HK", KRX: "KR", KOSDAQ: "KR", TWSE: "TW", TPEX: "TW", SSE: "CN", SZSE: "CN",
+  NSE: "IN", BSE: "IN", SGX: "SG", SET: "TH",
+  BMV: "MX", B3: "BR", BYMA: "AR", JSE: "ZA", TASE: "IL", BIST: "TR", TADAWUL: "SA",
+};
+
+/** The European Economic Area, whose issuers report managers' dealings under the Market Abuse Regulation. */
+const EEA = new Set(["AT", "BE", "CZ", "DE", "DK", "ES", "FI", "FR", "IE", "IS", "IT", "NL", "NO", "PL", "PT", "SE"]);
+
+/** Insider reports outside the SEC by the name they go by, by the issuer's country. */
+const HOME_INSIDER_REPORTS: Readonly<Record<string, string>> = {
+  CA: "Canadian insider reports (SEDI)",
+  GB: "UK insider reports (PDMR notifications)",
+  AU: "Australian insider reports (Appendix 3Y)",
+};
+
+/** The country of a venue abroad that a company's insiders may report in (TSX is CA); null for a US venue or one not placed. */
+export function venueHomeCountry(exchange: string | null | undefined): string | null {
+  return VENUE_COUNTRY[canonicalExchange(exchange ?? "")] ?? null;
+}
+
+/** A country's English name ("Japan"), or null when the runtime has none. */
+function countryName(code: string): string | null {
+  try {
+    const name = new Intl.DisplayNames(["en"], { type: "region" }).of(code);
+    return name && name !== code ? name : null;
+  } catch {
+    // Intentional ignore: a runtime without region names leaves the home market unnamed.
+    return null;
+  }
+}
+
+/**
+ * What a company from abroad's insiders report at home, which Form 4 data
+ * does not cover: "Canadian insider reports (SEDI) not covered." Where home
+ * is comes from the company's country (Gloom Cloud's issuer listings: RY in
+ * New York is Royal Bank of Canada), else its listing's venue abroad (RY:TSX).
+ * A foreign private issuer placed by neither gets its home market unnamed.
+ * Null for a US company, and for a US listing of a company that files as a
+ * domestic one, whose insiders file Form 4.
+ */
+export function homeInsiderReportsNote({ country, exchange, foreignPrivateIssuer = false }: {
+  /** The company's country, ISO 3166 alpha-2, when known. */
+  country?: string | null;
+  /** The listing's venue. */
+  exchange?: string | null;
+  foreignPrivateIssuer?: boolean;
+}): string | null {
+  const venueHome = venueHomeCountry(exchange) ?? "";
+  if (!venueHome && !foreignPrivateIssuer) return null;
+  // ZZ is the service's own word for a country it does not know.
+  const given = normalize(country ?? "");
+  const home = (given !== "ZZ" ? given : "") || venueHome;
+  if (home === "US") return null;
+  if (!home) return foreignPrivateIssuer ? "Home-market insider reports not covered." : null;
+  const named = HOME_INSIDER_REPORTS[home] ?? (EEA.has(home) ? "European insider reports (MAR managers' transactions)" : null);
+  if (named) return `${named} not covered.`;
+  const place = countryName(home);
+  return place ? `Insider reports filed in ${place} not covered.` : "Home-market insider reports not covered.";
+}
+
 /**
  * The key an issuer read is cached and deduplicated under: the ticker as given
  * for a US listing or a symbol with no venue, SYMBOL:VENUE for a listing

package/src/utils/throttled-fetch.ts

@@ -14,6 +14,7 @@ const DEFAULT_REQUESTS_PER_MINUTE = 30;
 const DEFAULT_MAX_RETRIES = 2;
 const DEFAULT_TIMEOUT_MS = 10_000;
 const BACKOFF_BASE_MS = 1_000;
+const DEFAULT_MAX_RETRY_WAIT_MS = 10_000;
 
 export interface ThrottledFetchOptions {
   /** Max requests per minute per host. Default: 30 */
@@ -24,6 +25,12 @@ export interface ThrottledFetchOptions {
   timeoutMs?: number;
   /** Initial retry backoff in ms. Default: 1000 */
   backoffBaseMs?: number;
+  /**
+   * Longest a retry waits, `Retry-After` included. A host that asks for more
+   * (a minute, say) gets no retry: the 429 or 5xx comes back as it is, so one
+   * rate-limited feed cannot hold its callers for that long. Default: 10000
+   */
+  maxRetryWaitMs?: number;
   /** Default headers applied to every request */
   defaultHeaders?: Record<string, string>;
   /** Share concurrent GET requests to the same URL. Default: true */
@@ -50,6 +57,7 @@ export function createThrottledFetch(
   const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
   const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   const backoffBaseMs = options.backoffBaseMs ?? BACKOFF_BASE_MS;
+  const maxRetryWaitMs = options.maxRetryWaitMs ?? DEFAULT_MAX_RETRY_WAIT_MS;
   const defaultHeaders = options.defaultHeaders ?? {};
   const dedupeGetRequests = options.dedupeGetRequests ?? true;
   const fetchTransport =
@@ -190,10 +198,9 @@ export function createThrottledFetch(
     // Retry on 429 or 5xx
     if ((resp.status === 429 || resp.status >= 500) && retriesLeft > 0) {
       throwIfAborted(callerSignal);
-      await wait(
-        getBackoffMs(retriesLeft, resp.headers.get("retry-after")),
-        callerSignal,
-      );
+      const retryWaitMs = getBackoffMs(retriesLeft, resp.headers.get("retry-after"));
+      if (retryWaitMs > maxRetryWaitMs) return resp;
+      await wait(retryWaitMs, callerSignal);
       return executeRequest(url, init, retriesLeft - 1);
     }
 

package/src/utils/trailing-eps.ts

@@ -0,0 +1,67 @@
+import type { EarningsField, FinancialStatement } from "../types/financials";
+import { areNearbyFinancialPeriodEnds } from "./financial-statements";
+import { hasStatementGap } from "./statement-gaps";
+
+const DAY_MS = 86_400_000;
+
+/** A per-share amount the row reports: finite, not declared unavailable, and diluted EPS on a resolved share basis. */
+function reportedEarnings(row: FinancialStatement, field: EarningsField): number | null {
+  if (hasStatementGap(row, field) || (field === "eps" && row.epsBasis?.status === "unresolved")) return null;
+  const value = row[field];
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+const consecutiveQuarters = (earlier: string, later: string) => {
+  const days = (Date.parse(later) - Date.parse(earlier)) / DAY_MS;
+  return days >= 60 && days <= 120;
+};
+
+/**
+ * The EPS of four consecutive quarters (oldest first) when one of them is a
+ * fiscal fourth quarter with no EPS of its own, as since 2021 a 10-K states
+ * the year but not its last quarter: the fiscal year's EPS, plus this fiscal
+ * year's quarters to date, less the same quarters a year earlier. The quarter
+ * itself is not given an EPS, since a year's EPS is not the sum of its
+ * quarters'. Null unless exactly one quarter lacks the line without declaring
+ * it unavailable, a fiscal year in the same currency ends with that quarter,
+ * and the year and its three earlier quarters report the line. Any input on
+ * an unresolved split basis, or two inputs on different share bases, leave it
+ * unknown. `inputs` are the rows the value reads, for its availability.
+ */
+export function trailingEpsAcrossFiscalYearEnd(
+  window: readonly FinancialStatement[],
+  quarterlyStatements: readonly FinancialStatement[],
+  annualStatements: readonly FinancialStatement[],
+  field: EarningsField,
+): { value: number; inputs: FinancialStatement[] } | null {
+  if (window.length !== 4) return null;
+  const unreported = window.filter((row) => reportedEarnings(row, field) === null);
+  if (unreported.length !== 1) return null;
+  const fourth = unreported[0]!;
+  // A declared gap or an unverified share basis is a figure withheld, not one missing.
+  if (hasStatementGap(fourth, field) || (field === "eps" && fourth.epsBasis?.status === "unresolved")) return null;
+  const years = annualStatements.filter((row) => areNearbyFinancialPeriodEnds(row.date, fourth.date));
+  if (years.length !== 1 || years[0]!.currency !== fourth.currency) return null;
+  const year = years[0]!;
+  const yearValue = reportedEarnings(year, field);
+  if (yearValue === null) return null;
+
+  const sorted = [...quarterlyStatements].sort((a, b) => a.date.localeCompare(b.date));
+  const end = sorted.findIndex((row) => row.date === fourth.date);
+  const earlier = end < 3 ? [] : sorted.slice(end - 3, end);
+  if (earlier.length !== 3 || [...earlier, fourth].some((row, index, rows) => (
+    row.currency !== fourth.currency || (index > 0 && !consecutiveQuarters(rows[index - 1]!.date, row.date))
+  ))) return null;
+  // The window's quarters before the fourth are that year's last ones.
+  const position = window.indexOf(fourth);
+  if (window.slice(0, position).some((row, index) => row.date !== earlier[3 - position + index]!.date)) return null;
+
+  const after = window.slice(position + 1);
+  const before = earlier.slice(0, 3 - position);
+  const inputs = [year, ...before, ...after];
+  if ([...earlier, ...after].some((row) => reportedEarnings(row, field) === null)) return null;
+  const bases = new Set([...window, year, ...earlier].flatMap((row) => row.shareBasis ?? []));
+  if (bases.size > 1) return null;
+  const sum = (rows: readonly FinancialStatement[]) => rows.reduce((total, row) => total + reportedEarnings(row, field)!, 0);
+  return { value: yearValue + sum(after) - sum(before), inputs };
+}