gloomberb 0.18.2 → 0.18.4

package/src/plugins/builtin/shared/cloud-upgrade.ts

@@ -12,8 +12,9 @@ import { getSharedRegistry } from "../../registry";
 import { requestAccountManagementTab } from "../account-management/navigation";
 import { resolvePlanAccess, usePlanAccess, type PlanAccess } from "../../../api-client/plan-access";
 import { useViewport } from "../../../react/input";
-import { useOptionalDialog } from "../../../ui/dialog";
+import { type DialogApi, useOptionalDialog } from "../../../ui/dialog";
 import { promptCloudUpgrade } from "../../../account/upgrade-dialog";
+import { type CheckoutHandoffTarget, promptCheckoutHandoff } from "../../../account/checkout-handoff";
 
 const CLOUD_UPGRADE_URL = "https://gloom.sh/cloud?upgrade=pro";
 
@@ -120,8 +121,12 @@ export function resetCloudUpgradeGuardForTests(): void {
   cloudUpgradeBlockedUntil.clear();
 }
 
+function cloudUpgradeReturnTo(): string | undefined {
+  return getCurrentPluginTarget() === "web" ? window.location.href : undefined;
+}
+
 async function resolveCloudUpgradeUrl(page: CloudUpgradePage, options: CloudUpgradeOptions): Promise<string> {
-  const returnTo = getCurrentPluginTarget() === "web" ? window.location.href : undefined;
+  const returnTo = cloudUpgradeReturnTo();
   if (page === "cloud") return researchUpgradeUrl(returnTo);
   const { url } = page === "portal"
     ? await apiClient.createBillingPortal()
@@ -138,6 +143,28 @@ async function openCloudUpgrade(
   await rendererHost.openExternal(await resolveCloudUpgradeUrl(page, options));
 }
 
+/**
+ * Opens checkout with the hand-off over the app: it says checkout is in the
+ * browser, reopens that same checkout, shows the short link where no browser
+ * opened, and waits for Pro. Settles once the browser was asked to open it;
+ * the dialog stays until Pro arrives or it is closed. Only a checkout that
+ * cannot be created rejects: a browser that fails to open leaves the link.
+ */
+async function openCheckoutWithHandoff(
+  dialog: DialogApi,
+  rendererHost: Pick<RendererHost, "openExternal">,
+  options: CloudUpgradeOptions,
+): Promise<void> {
+  const target = apiClient.createCloudCheckout(cloudUpgradeReturnTo(), options.interval ?? "month")
+    .then(({ url, link }): CheckoutHandoffTarget => ({
+      url,
+      link: link ?? null,
+      opened: rendererHost.openExternal(url).then((result) => result !== false, () => false),
+    }));
+  void promptCheckoutHandoff(dialog, target);
+  await (await target).opened;
+}
+
 /**
  * Opens the checkout page when any cloud UI has published an opener, counted
  * under `placement` rather than the UI that published it.
@@ -166,9 +193,9 @@ function isCloudUpgradeOptions(value: unknown): value is CloudUpgradeOptions {
  * a held Enter would otherwise open a checkout per keypress.
  *
  * A signed-in account without Pro sees the upgrade sheet first (what Pro adds,
- * what today costs), and checkout opens only once they choose to go on.
- * Signed-out users get the public Cloud page and Pro accounts the billing
- * portal, as before.
+ * what today costs), and checkout opens only once they choose to go on, with
+ * the checkout hand-off over the app until Pro arrives. Signed-out users get
+ * the public Cloud page and Pro accounts the billing portal, as before.
  */
 export function useCloudUpgradeAction(placement: string): (options?: unknown) => Promise<void> {
   const rendererHost = useRendererHost();
@@ -184,7 +211,8 @@ export function useCloudUpgradeAction(placement: string): (options?: unknown) =>
       const page = currentCloudUpgradePage();
       await openCloudUpgradePage(page, async () => {
         resolved.onOpening?.();
-        await openCloudUpgrade(rendererHost, page, resolved);
+        if (page === "checkout" && dialog) await openCheckoutWithHandoff(dialog, rendererHost, resolved);
+        else await openCloudUpgrade(rendererHost, page, resolved);
       }).catch(() => (
         // Keep the Cloud page reachable when checkout cannot be created; a native
         // session still rides along on the server's one-time handoff URL. Under

package/src/plugins/builtin/shared/earnings-calendar.ts

@@ -0,0 +1,375 @@
+import type { DataProvider, EarningsEvent } from "../../../types/data-provider";
+import type { CorporateActionsData, EarningsAction, EarningsDateStatus, EarningsEpsBasis } from "../../../types/financials";
+import { logFailure } from "../../../utils/log-failure";
+import { zonedDateKey } from "../../../utils/zoned-date-time";
+import { dateStatusFromEstimateFlag, earningsDateStatus, earningsEpsBasis } from "./earnings-report";
+import { coherentEarningsValue, EARNINGS_ESTIMATE_FIELDS } from "./earnings-estimate-basis";
+
+/**
+ * The one reading of a company's report dates that `earnings`, `events`, EE,
+ * ERN, OSA and the LEAPS next-earnings column share: the per-ticker
+ * calendar's date resolved against the quarters the company has on record
+ * (corporate actions, ERN's history), so a symbol shows the same next date,
+ * timing and status everywhere.
+ *
+ * - A confirmed date beats an estimated one; otherwise the calendar's stands
+ *   (JPM: the record's 2027-01-13 gives way to the calendar's confirmed
+ *   2027-01-14).
+ * - A date that has passed is reported, with the actual EPS once it is known
+ *   (PEP's 2026-10-08). A report out today is reported as soon as its figure
+ *   is, as same-day actuals are (META after the close).
+ * - A next date only the calendar knows is added (GS's 2027-01-19).
+ */
+
+/** Two dates this close are one report under two sources: quarterly reports are some ninety days apart. */
+const SAME_QUARTER_DAYS = 45;
+/** An actual this close to an upcoming date is that report, out already. */
+const SAME_REPORT_DAYS = 3;
+const DAY_MS = 86_400_000;
+
+/** The trading calendar's day, which report dates are on. */
+export function newYorkDay(now = Date.now()): string {
+  return zonedDateKey(now, "America/New_York");
+}
+
+/** The day the calendar puts a report on, YYYY-MM-DD. */
+function calendarDay(event: Pick<EarningsEvent, "earningsDate">): string {
+  return event.earningsDate.toISOString().slice(0, 10);
+}
+
+/**
+ * A calendar event's status on `today`: reported once the report is out
+ * (Gloom Cloud says so, or has its figure) or its date has passed.
+ */
+export function calendarStatus(
+  event: Pick<EarningsEvent, "earningsDate" | "epsActual" | "isDateEstimate" | "dateStatus">,
+  today: string,
+): EarningsDateStatus | null {
+  if (event.epsActual != null || earningsDateStatus(event.dateStatus) === "reported" || calendarDay(event) < today) return "reported";
+  return dateStatusFromEstimateFlag(event.isDateEstimate);
+}
+
+/** Whether the calendar's date for a report replaces another source's: a confirmed date beats an estimated one, else the calendar's stands. */
+function calendarDateWins(calendar: EarningsDateStatus | null, other: EarningsDateStatus | null): boolean {
+  return calendar === "confirmed" || other !== "confirmed";
+}
+
+/** The calendar's report as a quarter on record takes it. */
+interface CalendarReport {
+  date: string;
+  timing: "bmo" | "amc" | null;
+  dateStatus: EarningsDateStatus | null;
+  /** Whether the calendar's consensus is for this report; see `consensusIsReports`. */
+  ownConsensus: boolean;
+  /** Null when the calendar's consensus cannot be tied to the report. */
+  epsEstimate: number | null;
+  epsAnalysts: number | null;
+  epsActual: number | null;
+  epsBasis: EarningsEpsBasis | null;
+  revenueEstimate: number | null;
+  /** The quarter the estimate is for, YYYY-MM, when the calendar names it. */
+  fiscalPeriod: string | null;
+  currency: string | null;
+}
+
+/**
+ * Whether the calendar's consensus is for its own report. A report out keeps
+ * its date while the consensus rolls to the next quarter (PEP's 2026-10-08
+ * beside December's 2.24), so once a report is out its consensus counts only
+ * when something ties it to that report: the calendar's actual beside it,
+ * Gloom Cloud's stored report (which says its status, and keeps the report's
+ * own consensus), or a forecast quarter ending before the report date.
+ */
+function consensusIsReports(event: EarningsEvent, dateStatus: EarningsDateStatus | null, date: string): boolean {
+  if (dateStatus !== "reported" || event.epsActual != null || event.dateStatus != null) return true;
+  const periodEnd = event.estimateBasis?.epsEstimate?.periodEndDate ?? null;
+  return periodEnd != null && periodEnd < date;
+}
+
+function calendarReport(event: EarningsEvent, today: string): CalendarReport {
+  const date = calendarDay(event);
+  const dateStatus = calendarStatus(event, today);
+  const ownConsensus = consensusIsReports(event, dateStatus, date);
+  const periodEnd = event.estimateBasis?.epsEstimate?.periodEndDate ?? null;
+  const epsEstimate = ownConsensus ? coherentEarningsValue(event, "epsEstimate") : null;
+  return {
+    date,
+    timing: event.timing === "BMO" ? "bmo" : event.timing === "AMC" ? "amc" : null,
+    dateStatus,
+    ownConsensus,
+    epsEstimate,
+    epsAnalysts: epsEstimate == null ? null : coherentEarningsValue(event, "epsAnalysts"),
+    epsActual: event.epsActual ?? null,
+    epsBasis: epsEstimate == null ? null : earningsEpsBasis(event.epsBasis),
+    revenueEstimate: ownConsensus ? coherentEarningsValue(event, "revenueEstimate") : null,
+    fiscalPeriod: ownConsensus && periodEnd ? periodEnd.slice(0, 7) : null,
+    currency: epsEstimate == null ? null : event.estimateBasis?.epsEstimate?.currency ?? null,
+  };
+}
+
+/** What the resolver reads of a quarter on record. */
+interface ReportSlot {
+  date: string;
+  dateStatus: EarningsDateStatus | null | undefined;
+  epsActual: number | null | undefined;
+}
+
+/** How one source's rows are read and rebuilt: corporate actions for events and EE, history for ERN. */
+export interface ReportRowAdapter<T> {
+  slot(row: T): ReportSlot;
+  /** The row labelled reported, with `epsActual` when it has no figure of its own. */
+  reported(row: T, epsActual: number | null): T;
+  /** The calendar's report as a row: over `row` when it is the same report, else a new one. */
+  fromCalendar(report: CalendarReport, row: T | null): T;
+}
+
+const isOut = (slot: ReportSlot, today: string) => slot.epsActual != null || slot.dateStatus === "reported" || slot.date < today;
+const dayGap = (left: string, right: string) => Math.abs(Date.parse(`${left}T00:00:00Z`) - Date.parse(`${right}T00:00:00Z`)) / DAY_MS;
+
+/**
+ * The row the calendar's report is: for a report out, the nearest quarter on
+ * record that is out, else an upcoming one days away; for an upcoming one,
+ * the nearest upcoming quarter, else one out days away (out early).
+ */
+function calendarRowIndex(slots: readonly ReportSlot[], report: CalendarReport, today: string): number {
+  const nearest = (keep: (slot: ReportSlot) => boolean, days: number) => {
+    let best = -1;
+    for (const [index, slot] of slots.entries()) {
+      const gap = dayGap(slot.date, report.date);
+      if (gap <= days && keep(slot) && (best < 0 || gap < dayGap(slots[best]!.date, report.date))) best = index;
+    }
+    return best;
+  };
+  const out = (slot: ReportSlot) => isOut(slot, today);
+  const upcoming = (slot: ReportSlot) => !isOut(slot, today);
+  const [first, second] = report.dateStatus === "reported" ? [out, upcoming] : [upcoming, out];
+  const index = nearest(first, SAME_QUARTER_DAYS);
+  return index >= 0 ? index : nearest(second, SAME_REPORT_DAYS);
+}
+
+/**
+ * Quarters on record resolved against the calendar's event, with the row
+ * that is the calendar's report. Past quarters read reported; the calendar's
+ * report updates its row, or is added when the record has none.
+ */
+function resolveReportRowsWithCalendar<T>(
+  rows: readonly T[],
+  event: EarningsEvent | null | undefined,
+  today: string,
+  adapter: ReportRowAdapter<T>,
+): { rows: T[]; calendarRow: T | null } {
+  const resolved = rows.map((row) => {
+    const slot = adapter.slot(row);
+    return isOut(slot, today) && slot.dateStatus !== "reported" ? adapter.reported(row, null) : row;
+  });
+  if (!event) return { rows: resolved, calendarRow: null };
+  const report = calendarReport(event, today);
+  const index = calendarRowIndex(resolved.map(adapter.slot), report, today);
+  if (index < 0) {
+    const added = adapter.fromCalendar(report, null);
+    return { rows: [...resolved, added], calendarRow: added };
+  }
+  const row = resolved[index]!;
+  const slot = adapter.slot(row);
+  if (isOut(slot, today)) {
+    if (slot.epsActual == null && report.epsActual != null) resolved[index] = adapter.reported(row, report.epsActual);
+  } else if (report.dateStatus === "reported" || calendarDateWins(report.dateStatus, earningsDateStatus(slot.dateStatus))) {
+    resolved[index] = adapter.fromCalendar(report, row);
+  }
+  return { rows: resolved, calendarRow: resolved[index]! };
+}
+
+export function resolveReportRows<T>(rows: readonly T[], event: EarningsEvent | null | undefined, today: string, adapter: ReportRowAdapter<T>): T[] {
+  return resolveReportRowsWithCalendar(rows, event, today, adapter).rows;
+}
+
+const TIME_TEXT = { bmo: "Pre Market", amc: "After Hours" } as const;
+
+/** A row's beat, measured as Gloom Cloud measures it, once the calendar gives it a figure or an estimate it lacked. */
+function withSurprise(row: EarningsAction, before: EarningsAction | null): EarningsAction {
+  const { epsActual: actual, epsEstimate: estimate } = row;
+  if (actual == null || estimate == null || (actual === before?.epsActual && estimate === before.epsEstimate)) return row;
+  const cents = (value: number) => Math.round(value * 100) / 100;
+  const { difference: _difference, surprisePercent: _surprise, ...rest } = row;
+  return { ...rest, difference: cents(actual - estimate), ...(estimate !== 0 ? { surprisePercent: cents((actual - estimate) / Math.abs(estimate) * 100) } : {}) };
+}
+
+function definedFields<T extends object>(row: T): T {
+  return Object.fromEntries(Object.entries(row).filter(([, value]) => value !== undefined)) as T;
+}
+
+/** Corporate-actions earnings rows, as events, EE and the `earnings` resolution read them. */
+const ACTION_ROWS: ReportRowAdapter<EarningsAction> = {
+  slot: (row) => ({ date: row.date, dateStatus: earningsDateStatus(row.dateStatus), epsActual: row.epsActual }),
+  reported: (row, epsActual) => withSurprise({ ...row, dateStatus: "reported", ...(row.epsActual == null && epsActual != null ? { epsActual } : {}) }, row),
+  fromCalendar(report, row) {
+    // The calendar's consensus goes with its date; without one, the record's stays.
+    const estimate = report.epsEstimate != null;
+    return withSurprise(definedFields<EarningsAction>({
+      ...row,
+      date: report.date,
+      dateType: "announcement",
+      time: report.timing ? TIME_TEXT[report.timing] : row?.time,
+      currency: estimate ? report.currency ?? row?.currency : row?.currency,
+      epsEstimate: estimate ? report.epsEstimate! : row?.epsEstimate,
+      epsAnalysts: estimate ? report.epsAnalysts ?? undefined : row?.epsAnalysts,
+      epsActual: report.epsActual ?? row?.epsActual,
+      fiscalPeriod: row?.fiscalPeriod ?? report.fiscalPeriod ?? undefined,
+      epsBasis: estimate ? report.epsBasis : row?.epsBasis,
+      dateStatus: report.dateStatus ?? undefined,
+    }), row);
+  },
+};
+
+/** A company's corporate-actions earnings rows, newest first, resolved against its calendar event. */
+export function resolveEarningsActions(earnings: readonly EarningsAction[], event: EarningsEvent | null | undefined, today: string): EarningsAction[] {
+  return resolveReportRows(earnings, event, today, ACTION_ROWS).sort((left, right) => right.date.localeCompare(left.date));
+}
+
+/** A company's corporate actions with their earnings rows resolved against its calendar event. */
+export function withResolvedEarnings(actions: CorporateActionsData, event: EarningsEvent | null | undefined, today: string): CorporateActionsData {
+  // Without a calendar event the rows still resolve: a date gone by reads reported, as ERN reads it.
+  return { ...actions, earnings: resolveEarningsActions(actions.earnings, event, today) };
+}
+
+/** The calendar's event for a symbol, as it was asked for (SAN:EPA comes back as SAN:EPA). */
+export function calendarEventOf(events: readonly EarningsEvent[] | null | undefined, symbol: string): EarningsEvent | null {
+  const key = symbol.trim().toUpperCase();
+  return events?.find((event) => event.symbol.trim().toUpperCase() === key) ?? null;
+}
+
+/**
+ * Whether the calendar event is read against its quarters on record: once
+ * its date has come or its report is out, for the actual and the next
+ * report, and while its date is not confirmed, which a confirmed date on
+ * record beats. A confirmed date to come stands alone.
+ */
+function needsRecordedQuarters(event: EarningsEvent, today: string): boolean {
+  return event.epsActual == null && (calendarDay(event) <= today || calendarStatus(event, today) !== "confirmed");
+}
+
+export interface ResolvedEarningsEvent extends EarningsEvent {
+  /** Out, announced or projected, after resolution; null when no source says. */
+  dateStatus: EarningsDateStatus | null;
+}
+
+const TIMING_OF_TEXT: Record<string, EarningsEvent["timing"]> = { "Pre Market": "BMO", "After Hours": "AMC" };
+
+/** The calendar's event without its consensus, which is another quarter's than the report's. */
+function withoutConsensus(event: EarningsEvent): EarningsEvent {
+  const stripped: EarningsEvent = { ...event, epsEstimate: null, revenueEstimate: null, epsBasis: null };
+  delete stripped.estimateBasis;
+  for (const field of EARNINGS_ESTIMATE_FIELDS) if (stripped[field] != null) stripped[field] = null;
+  return stripped;
+}
+
+const statusFlag = (status: EarningsDateStatus | null) => status === "projected" ? true : status === "confirmed" ? false : null;
+
+/**
+ * The resolved event for a row. The calendar's own report keeps every figure
+ * the calendar carries (revenue, ranges, bases), but its consensus only when
+ * it is the report's, and takes the row's status and, when the record has the
+ * actual the calendar lacks, the record's EPS figures, measured against the
+ * record's estimate. Another report on record is that row alone.
+ */
+function eventOfRow(event: EarningsEvent, row: EarningsAction, report: CalendarReport | null): ResolvedEarningsEvent {
+  const ownDate = row.date === calendarDay(event);
+  const dateStatus = earningsDateStatus(row.dateStatus);
+  const earningsDate = ownDate ? event.earningsDate : new Date(`${row.date}T00:00:00.000Z`);
+  const rowTiming = TIMING_OF_TEXT[row.time ?? ""];
+  if (report) {
+    const base = report.ownConsensus ? event : withoutConsensus(event);
+    const recordFigures = row.epsActual != null && event.epsActual == null;
+    return {
+      ...base,
+      earningsDate,
+      earningsCallDate: ownDate ? event.earningsCallDate ?? null : null,
+      isDateEstimate: statusFlag(dateStatus) ?? (dateStatus === "reported" ? base.isDateEstimate ?? null : null),
+      epsEstimate: recordFigures ? row.epsEstimate ?? null : base.epsEstimate ?? row.epsEstimate ?? null,
+      epsAnalysts: recordFigures ? row.epsAnalysts ?? null : base.epsAnalysts ?? row.epsAnalysts ?? null,
+      epsActual: event.epsActual ?? row.epsActual ?? null,
+      epsBasis: recordFigures ? row.epsBasis ?? null : base.epsBasis ?? row.epsBasis ?? null,
+      surprise: recordFigures ? row.surprisePercent ?? null : base.surprise ?? row.surprisePercent ?? null,
+      timing: (ownDate && event.timing) || rowTiming || event.timing,
+      dateStatus,
+    };
+  }
+  return {
+    symbol: event.symbol,
+    name: event.name,
+    earningsDate,
+    earningsCallDate: null,
+    isDateEstimate: statusFlag(dateStatus),
+    epsEstimate: row.epsEstimate ?? null,
+    epsAnalysts: row.epsAnalysts ?? null,
+    epsActual: row.epsActual ?? null,
+    epsBasis: row.epsBasis ?? null,
+    revenueEstimate: null,
+    revenueActual: null,
+    surprise: row.surprisePercent ?? null,
+    timing: rowTiming ?? "",
+    dateStatus,
+  };
+}
+
+/**
+ * A company's next report: the calendar's, resolved against its quarters on
+ * record when they were read. Once the calendar's date has passed, the next
+ * upcoming quarter on record stands in, else the report that is out, with its
+ * actual and the estimate it was measured against. Without the record, a past
+ * date still reads reported.
+ */
+export function resolveCalendarEvent(event: EarningsEvent, earnings: readonly EarningsAction[] | null | undefined, today: string): ResolvedEarningsEvent {
+  const status = calendarStatus(event, today);
+  if (!earnings && status !== "reported") return { ...event, dateStatus: status };
+  const { rows, calendarRow } = resolveReportRowsWithCalendar(earnings ?? [], event, today, ACTION_ROWS);
+  const next = rows
+    .filter((row) => !isOut(ACTION_ROWS.slot(row), today))
+    .sort((left, right) => left.date.localeCompare(right.date))[0];
+  const chosen = next ?? calendarRow!;
+  return eventOfRow(event, chosen, chosen === calendarRow ? calendarReport(event, today) : null);
+}
+
+/** The next report date, YYYY-MM-DD, of a resolved event; null once it is out. */
+export function upcomingReportDate(event: ResolvedEarningsEvent | null | undefined): string | null {
+  return event && event.dateStatus !== "reported" ? calendarDay(event) : null;
+}
+
+/** A listing: the calendar's key for it (SAN:EPA) and the symbol and venue corporate actions are read by. */
+export interface EarningsListing {
+  key: string;
+  symbol: string;
+  exchange: string;
+}
+
+/** Calendar events need their quarters on record read at most this many at a time. */
+const RECORD_CONCURRENCY = 4;
+
+/**
+ * Each listing's calendar event, resolved: the corporate actions of those
+ * whose date has come are read for their actual and the next quarter on
+ * record. A listing the calendar has nothing for is absent; one whose
+ * record cannot be read resolves on the calendar alone.
+ */
+export async function resolveListingEvents(
+  provider: Pick<DataProvider, "getCorporateActions">,
+  listings: readonly EarningsListing[],
+  events: readonly EarningsEvent[],
+  today: string,
+): Promise<Map<string, ResolvedEarningsEvent>> {
+  const resolved = new Map<string, ResolvedEarningsEvent>();
+  const pending = listings.flatMap((listing) => {
+    const event = calendarEventOf(events, listing.key);
+    return event ? [{ listing, event }] : [];
+  });
+  for (let index = 0; index < pending.length; index += RECORD_CONCURRENCY) {
+    await Promise.all(pending.slice(index, index + RECORD_CONCURRENCY).map(async ({ listing, event }) => {
+      const earnings = needsRecordedQuarters(event, today) && provider.getCorporateActions
+        ? await provider.getCorporateActions(listing.symbol, listing.exchange)
+          .then((actions) => actions.earnings, logFailure("earnings-calendar", "Read corporate actions for a past report date failed", null))
+        : null;
+      resolved.set(listing.key.toUpperCase(), resolveCalendarEvent(event, earnings, today));
+    }));
+  }
+  return resolved;
+}

package/src/plugins/builtin/{earnings/estimate-basis.ts → shared/earnings-estimate-basis.ts}

@@ -1,6 +1,6 @@
 import type { EarningsEstimateBasis, EarningsEstimateField, EarningsEvent } from "../../../types/data-provider";
 
-const EARNINGS_ESTIMATE_FIELDS: readonly EarningsEstimateField[] = [
+export const EARNINGS_ESTIMATE_FIELDS: readonly EarningsEstimateField[] = [
   "epsEstimate", "epsLow", "epsHigh", "epsYearAgo", "epsGrowth", "epsAnalysts",
   "epsTrend7dAgo", "epsTrend30dAgo", "epsRevisionUp7d", "epsRevisionUp30d", "epsRevisionDown7d", "epsRevisionDown30d",
   "revenueEstimate", "revenueLow", "revenueHigh", "revenueYearAgo", "revenueGrowth", "revenueAnalysts",

package/src/plugins/builtin/shared/earnings-report.ts

@@ -54,8 +54,8 @@ export function epsBasisShort(basis: EarningsEpsBasis | null): string {
   return basis === "gaap" ? "GAAP" : basis === "adjusted" ? "adj" : "?";
 }
 
-/** The basis as every earnings table names it: GAAP, adj, basis unknown. */
-const BASIS_TEXT: Record<EpsBasisName, string> = { GAAP: "GAAP", adjusted: "adj", unknown: "basis unknown" };
+/** Known bases are named in row details; unknown stays in the structured data and drilldown. */
+const BASIS_TEXT: Record<EpsBasisName, string> = { GAAP: "GAAP", adjusted: "adj", unknown: "" };
 
 type EarningsRecord = CorporateActionsData["earnings"][number];
 
@@ -80,7 +80,7 @@ export function earningsDetailParts(earning: EarningsRecord): string[] {
 export function earningsDetail(earning: EarningsRecord): string {
   const detail = earningsDetailParts(earning).join(", ");
   if (earning.epsActual == null) return detail || "Pending";
-  return earning.dateType === "fiscal-period-end" ? `Period end; ${detail}` : detail;
+  return earning.dateType === "fiscal-period-end" ? ["Period end", detail].filter(Boolean).join("; ") : detail;
 }
 
 const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];

package/src/plugins/builtin/shared/fx-rate-freshness.ts

@@ -1,4 +1,5 @@
-import type { Quote } from "../../../types/financials";
+import { intradayBarText } from "../../../market-data/quotes/intraday-bar";
+import type { Quote, QuoteIntradayBar } from "../../../types/financials";
 import { isFxMarketOpen } from "../../../utils/fx-market-hours";
 import { quoteFreshnessFields } from "./report-freshness";
 
@@ -32,6 +33,27 @@ export interface FxRateTiming {
   error?: unknown;
   /** How far the snapshot runs behind the market, as the data service states it; 0 is real-time. */
   delayMinutes?: number;
+  /** The pair's bar the rate is the close of, when the data service took one over a print that had stopped behind it. */
+  intradayBar?: QuoteIntradayBar;
+  /** Why a stale rate stands, as the data service states it. */
+  staleReason?: string;
+}
+
+/**
+ * What the loaded USD rates behind a pair say of themselves, one line per
+ * rate (`BRL/USD: ...`): the bar a rate is the close of, and, for a stale
+ * rate, why it stands (its bars had nothing newer, or did not load). A rate
+ * whose own refresh failed is stale for that reason, so it states none.
+ */
+export function fxRateNotes(legs: ReadonlyMap<string, FxRateTiming>, now = Date.now()): string[] {
+  return [...legs].flatMap(([currency, timing]) => {
+    if (currency === "USD") return [];
+    const stale = timing.staleAt != null && timing.staleAt <= now;
+    return [
+      ...timing.intradayBar ? [`${currency}/USD: ${intradayBarText(timing.intradayBar)}`] : [],
+      ...stale && timing.error == null && timing.staleReason ? [`${currency}/USD: ${timing.staleReason}`] : [],
+    ];
+  });
 }
 
 function isoTime(time: number | undefined | null): string | undefined {

package/src/plugins/builtin/shared/job-posting.ts

@@ -0,0 +1,129 @@
+import type { CloudJobsPostingDetail } from "../../../api-client/types";
+import { formatShortDate } from "../../../utils/datetime-format";
+import { formatCompact, formatNumber } from "../../../utils/format";
+import { humanLabel } from "./research-cells";
+
+/**
+ * One job posting read by a person: its place, when it was posted, its pay
+ * and its hours, in words. Shared by JOBS and HIRE's posting detail. A value
+ * the careers system did not give is left out, never shown as a dash or
+ * "Unknown".
+ */
+
+/** "$120k–150k", "$45–52/h", "£60k"; empty when the posting has no pay. */
+export function formatSalaryRange(
+  min: number | null,
+  max: number | null,
+  currency: string | null,
+  period: string | null,
+): string {
+  if (min == null && max == null) return "";
+  const symbol = currency === "USD" ? "$" : currency === "EUR" ? "€" : currency === "GBP" ? "£" : currency ? `${currency} ` : "";
+  const fmt = (value: number) => (period === "hour" ? formatNumber(value, 0) : formatCompact(value));
+  const range = min != null && max != null && min !== max
+    ? `${symbol}${fmt(min)}–${fmt(max)}`
+    : `${symbol}${fmt((min ?? max)!)}`;
+  return period === "hour" ? `${range}/h` : period === "month" ? `${range}/mo` : range;
+}
+
+const countryNames = new Intl.DisplayNames(["en"], { type: "region" });
+
+/** A country code as its name: "AU" as "Australia". */
+export function countryName(code: string | null | undefined): string | null {
+  if (!code || !/^[A-Z]{2}$/.test(code)) return null;
+  try {
+    return countryNames.of(code) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Where the role is, in words: the posting's location with its country named
+ * ("Paris, FR" as "Paris, France"), the country when the location does not end
+ * with it, and "Remote" when the role is remote and the location does not say
+ * so. A list of places ("Austin, TX; Denver, CO") stays as written.
+ */
+export function postingPlace(posting: { location: string | null; country: string | null; remote: boolean | null }): string | null {
+  const location = posting.location?.trim() || null;
+  const name = countryName(posting.country);
+  let place = location;
+  if (location && !location.includes(";")) {
+    const parts = location.split(/\s*,\s*/);
+    const last = parts.at(-1) ?? "";
+    const lastName = /^[A-Z]{2}$/.test(last) && parts.length > 1 ? countryName(last) : null;
+    // A trailing code names the country only when it is the posting's own ("…, CA" may be California).
+    if (lastName && last === posting.country) place = [...parts.slice(0, -1), lastName].join(", ");
+    else if (name && last.toLowerCase() !== name.toLowerCase() && last !== posting.country) place = `${location}, ${name}`;
+  } else if (!location) place = name;
+  const remote = posting.remote && !/remote/i.test(place ?? "") ? "Remote" : null;
+  return [place, remote].filter(Boolean).join(" · ") || null;
+}
+
+/** "Oct 3, 2026"; "about Oct 3, 2026" or "Oct 3, 2026 or earlier" when the careers system's date is not exact. */
+function postedText(postedAt: string | null | undefined, precision?: string | null): string | null {
+  if (!postedAt) return null;
+  const date = formatShortDate(postedAt.slice(0, 10), { utc: true, fallback: "" });
+  if (!date) return null;
+  return precision === "floor" ? `${date} or earlier` : precision === "approximate" ? `about ${date}` : date;
+}
+
+/** schema.org's employment types, in words. */
+const EMPLOYMENT: Record<string, string> = {
+  FULL_TIME: "Full time", PART_TIME: "Part time", CONTRACTOR: "Contract", TEMPORARY: "Temporary",
+  INTERN: "Internship", PER_DIEM: "Per diem", VOLUNTEER: "Volunteer",
+};
+
+/** "Full time" for FULL_TIME or full_time; a careers system's own word ("CDI", "Vollzeit") as written. Nothing for "other" or "unavailable". */
+export function employmentText(value: string | null | undefined): string | null {
+  const text = value?.trim();
+  if (!text || /^(?:other|unknown|unavailable|n\/?a|none)$/i.test(text)) return null;
+  const known = EMPLOYMENT[text.toUpperCase().replace(/[\s-]+/g, "_")];
+  if (known) return known;
+  return /^[A-Z_]+$/.test(text) && text.includes("_") ? humanLabel(text) : text;
+}
+
+/**
+ * A title the careers system never gave: `Job <id>`, an id alone, or the
+ * words of the posting's address. A reader is shown "Untitled role" instead.
+ */
+function isPlaceholderTitle(title: string | null | undefined, externalId?: string | null): boolean {
+  const text = title?.trim() ?? "";
+  if (!text) return true;
+  if (/^job\s+\S*\d\S*$/i.test(text) || /^[A-Z]{0,4}[-_]?\d{3,}$/i.test(text)) return true;
+  if (externalId && (text === externalId || text === `Job ${externalId}`)) return true;
+  // Bytes still percent-encoded: the address's words, not the role's title.
+  return /%[0-9A-F]{2}/i.test(text);
+}
+
+/** The posting's title as the careers system wrote it, or "Untitled role" for one it never gave. */
+export function postingTitle(title: string | null | undefined, externalId?: string | null): string {
+  return isPlaceholderTitle(title, externalId) ? "Untitled role" : title!;
+}
+
+/**
+ * A posting's description as words: the markdown marks some careers systems
+ * write (Starbucks' "#### Basic Qualifications", "**Pay**") taken off, so a
+ * heading reads as a heading line and bold as its words.
+ */
+export function descriptionText(text: string | null | undefined): string | null {
+  if (!text) return null;
+  return text.replace(/^[ \t]*#{1,6}[ \t]+(?=\S)/gm, "").replace(/\*\*([^*\n]+)\*\*/g, "$1").replace(/__([^_\n]+)__/g, "$1");
+}
+
+export interface PostingFact {
+  label: string;
+  value: string;
+}
+
+/** A posting's facts, in the order a reader wants them; only those the posting has. */
+export function postingFacts(posting: CloudJobsPostingDetail): PostingFact[] {
+  const facts: Array<[string, string | null]> = [
+    ["Place", postingPlace(posting)],
+    ["Posted", postedText(posting.postedAt, posting.postedPrecision)],
+    ["Pay", formatSalaryRange(posting.salaryMin, posting.salaryMax, posting.salaryCurrency, posting.salaryPeriod) || null],
+    ["Hours", employmentText(posting.employmentType)],
+    ["Closed", posting.closedAt ? postedText(posting.closedAt) : null],
+  ];
+  return facts.filter((fact): fact is [string, string] => !!fact[1]).map(([label, value]) => ({ label, value }));
+}

package/src/plugins/builtin/shared/pro-lock-note.ts

@@ -127,10 +127,10 @@ export async function proLockNote(
     ? "verify your email (Ctrl+P, Resend Verification Email)"
     : `log in or sign up${pro ? "" : " free"} from the command bar (Ctrl+P, Log In or Sign Up)`;
   const unlock = gate === "pro"
-    ? `To read ${pane.shows} in ${token}, upgrade in the app (gloomberb, then Ctrl+P, UPGRADE)`
-    : `To read ${pane.shows} in ${token}, open the app (gloomberb), ${account}${pro ? ", then upgrade (Ctrl+P, UPGRADE)" : ""}`;
+    ? `To read ${pane.shows} in ${token}, upgrade in the app (gloom, then Ctrl+P, UPGRADE)`
+    : `To read ${pane.shows} in ${token}, open the app (gloom), ${account}${pro ? ", then upgrade (Ctrl+P, UPGRADE)" : ""}`;
   const bare = pane.argument === "none" || (pane.argument === "optional" && !symbol);
-  const command = bare ? `gloomberb fn ${token}` : `gloomberb fn ${token} ${ticker}`;
+  const command = bare ? `gloom fn ${token}` : `gloom fn ${token} ${ticker}`;
   const free = pane.free ? await answeringFreeRoute(lock, pane.free) : null;
   return [
     `${token} ${what}: ${pane.does}. ${without} it shows none of ${pane.shows}.`,