@gloom-sh/terminal 0.19.1 → 0.19.3

package/src/plugins/builtin/dividend-yield/ranking-view.tsx

@@ -0,0 +1,163 @@
+import { useCallback, useMemo, useRef } from "react";
+import { apiClient } from "../../../api-client";
+import {
+  DataTableView,
+  PaneStatusBody,
+  usePaneFooter,
+  type DataTableCell,
+  type DataTableColumn,
+} from "../../../components";
+import { loadingErrorFooterInfo, usePaneRefreshKey } from "../../../components/data-table/table-pane";
+import { useAsyncResource } from "../../../react/async-resource";
+import { useAssetData, usePluginAppActions, usePluginPaneState } from "../../../public/react";
+import { useAppSelector } from "../../../state/app/context";
+import { resolveSavedInstrument } from "../../../tickers/saved-instrument";
+import { colors } from "../../../theme/colors";
+import type { HeadlessPaneColumn } from "../../../types/headless";
+import { TextAttributes } from "../../../ui";
+import { compareSortValues, nextHeaderSort, type SortComparableValue, type SortPreference } from "../../../utils/sort-values";
+import { SignInWall } from "../cloud/auth-actions";
+import { isCloudSessionRequired, useResearchCloudSession } from "../shared/research-cloud-session";
+import { fetchDividendData } from "./client";
+import { dividendRankingReads, type DividendReadContext } from "./headless";
+import { projectDividendRanking, type DividendRankingEntry } from "./ranking";
+import { readDividendRanking, type DividendRankingReads } from "./ranking-reads";
+
+/** The pane setting a ranking of several tickers is opened with (`shot DVD KO JNJ`). */
+export const RANK_SYMBOLS_SETTING = "rankSymbols";
+
+/** The tickers a pane ranks, from its settings: two or more, or none for a pane of one ticker. */
+export function rankSymbolsOf(settings: Readonly<Record<string, unknown>> | undefined): string[] {
+  const value = settings?.[RANK_SYMBOLS_SETTING];
+  const symbols = Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === "string" && entry.trim() !== "") : [];
+  return symbols.length > 1 ? symbols : [];
+}
+
+/** How wide each of the ranking's columns starts, in characters; a column not named fits its header. */
+const COLUMN_WIDTHS: Record<string, number> = { symbol: 10, lastExDate: 10, payDate: 10, note: 24, yieldBasis: 24 };
+/** Growth figures read by their sign, as the single-ticker pane colors them. */
+const SIGNED_COLUMNS = new Set(["growth1Y", "growth3Y"]);
+const DATE_COLUMNS = new Set(["lastExDate", "payDate", "secYieldAsOf"]);
+
+type RankingRow = Record<string, unknown> & { symbol: string };
+type RankingColumn = DataTableColumn & { source: HeadlessPaneColumn };
+/**
+ * The order `fn DVD` ranks in: trailing yield, highest first. A stable sort
+ * of the ranked rows keeps a ticker not read last among those with no yield.
+ */
+const RANKED_ORDER: SortPreference<string> = { columnId: "trailingYield", direction: "desc" };
+
+function sortRankingRows(rows: RankingRow[], sort: SortPreference<string>): RankingRow[] {
+  const { columnId, direction } = sort;
+  if (!columnId) return rows;
+  return [...rows].sort((left, right) => compareSortValues(left[columnId] as SortComparableValue, right[columnId] as SortComparableValue, direction));
+}
+
+/** Signed out, every read is refused for the account: the pane shows the wall the single-ticker DVD shows. */
+function needsSignIn(entries: readonly DividendRankingEntry[] | null): boolean {
+  return !!entries?.length && entries.every((entry) => !("data" in entry))
+    && entries.some((entry) => "error" in entry && isCloudSessionRequired(entry.error));
+}
+
+function cellText(column: HeadlessPaneColumn, row: RankingRow): string {
+  const value = row[column.key];
+  const format = column.textFormat ?? column.format;
+  return format ? format(value, row) : value == null ? "" : String(value);
+}
+
+/**
+ * Several tickers ranked by trailing yield in one table, with the columns and
+ * figures `fn DVD A B C` prints; Enter opens a ticker's own dividend pane.
+ */
+export function DividendRankingView({ symbols, focused, width, height, loadData }: {
+  symbols: readonly string[];
+  focused: boolean;
+  width: number;
+  height: number;
+  /** One listing's history alone, without the quote `fn DVD` prices it at; for tests. */
+  loadData?: typeof fetchDividendData;
+}) {
+  const key = symbols.join(",");
+  const marketData = useAssetData();
+  const cloudSession = useResearchCloudSession();
+  // A key reads the listing `fn DVD` reads for it: its own venue, else the one its saved ticker is on.
+  // Through a ref, so a quote that updates a saved ticker does not read the ranking again.
+  const tickers = useAppSelector((state) => state.tickers);
+  const tickersRef = useRef(tickers);
+  tickersRef.current = tickers;
+  const reads = useMemo<DividendRankingReads>(() => {
+    const resolveInstrument = (typed: string) => resolveSavedInstrument(typed, (saved) => tickersRef.current.get(saved));
+    // `fn DVD`'s own reads: the listing's quote for the price, the stated forward rate, a fund's bond facts.
+    if (marketData && !loadData) return dividendRankingReads({ marketData, apiClient, resolveInstrument } satisfies DividendReadContext);
+    const history = loadData ?? fetchDividendData;
+    return { loadData: async (typed) => {
+      const listing = await resolveInstrument(typed);
+      return history(listing.symbol, null, listing.exchange ?? "");
+    } };
+  }, [loadData, marketData]);
+  // A sign-in or a verified email reads the ranking again.
+  const request = useCallback(() => readDividendRanking(key.split(","), reads), [key, reads, cloudSession.requestKey]);
+  const resource = useAsyncResource(request, { keepPreviousData: true });
+  const authWall = needsSignIn(resource.data);
+  const { createPaneFromTemplate } = usePluginAppActions();
+  const section = useMemo(() => resource.data ? projectDividendRanking(resource.data).sections[0] ?? null : null, [resource.data]);
+  const [sort, setSort] = usePluginPaneState<SortPreference<string>>("dividend-ranking:sort", RANKED_ORDER);
+  const rows = useMemo(() => sortRankingRows((section?.rows ?? []) as RankingRow[], sort), [section, sort]);
+  const columns = useMemo<RankingColumn[]>(() => (section?.columns ?? []).map((column) => ({
+    id: column.key,
+    label: column.header,
+    width: Math.max(column.header.length, COLUMN_WIDTHS[column.key] ?? 0),
+    align: column.align === "right" ? "right" : "left",
+    source: column,
+  })), [section]);
+  const [selected, setSelected] = usePluginPaneState<string | null>("dividend-ranking:selected", null);
+
+  usePaneFooter("dividend-ranking", () => ({
+    info: loadingErrorFooterInfo(resource.loading && !!resource.data, resource.data ? null : resource.error),
+  }), [resource.loading, resource.data, resource.error]);
+  usePaneRefreshKey(resource.reload, { focused, enabled: !authWall });
+
+  const renderCell = useCallback((row: RankingRow, column: RankingColumn): DataTableCell => {
+    const text = cellText(column.source, row);
+    const value = row[column.id];
+    if (column.id === "symbol") return { text, color: colors.textBright, attributes: TextAttributes.BOLD };
+    if (column.id === "note") return { text, color: colors.warning };
+    if (DATE_COLUMNS.has(column.id) || column.id === "yieldBasis") return { text, color: colors.textDim };
+    if (SIGNED_COLUMNS.has(column.id) && typeof value === "number") {
+      return { text, color: value > 0 ? colors.positive : value < 0 ? colors.negative : colors.text };
+    }
+    return { text };
+  }, []);
+
+  if (authWall) return <SignInWall placement="dividend-yield-signin" action="view dividend history" needsVerification={cloudSession.needsVerification} />;
+
+  return (
+    <PaneStatusBody
+      subject="dividends"
+      loading={!resource.data && resource.loading}
+      error={!resource.data ? resource.error : null}
+      empty={false}
+    >
+      <DataTableView<RankingRow, RankingColumn>
+        focused={focused}
+        columns={columns}
+        items={rows}
+        rootWidth={width}
+        rootHeight={height}
+        freezeFirstColumn
+        sortColumnId={sort.columnId}
+        sortDirection={sort.direction}
+        // A third click on a column returns to the ranking.
+        onHeaderClick={(id) => setSort((current) => nextHeaderSort(current, id, {
+          firstDirection: id === "symbol" || id === "note" || id === "yieldBasis" ? "asc" : "desc", resetTo: RANKED_ORDER }))}
+        getItemKey={(row) => row.symbol}
+        selection={{ kind: "id", selectedId: rows.some((row) => row.symbol === selected) ? selected! : rows[0]?.symbol ?? "",
+          getId: (row) => row.symbol, onChange: (id) => setSelected(id) }}
+        onActivate={(row) => createPaneFromTemplate("dividend-yield-pane", { symbol: row.symbol })}
+        renderCell={renderCell}
+        selectedTextOverridesCellColor
+        emptyStateTitle="No tickers"
+      />
+    </PaneStatusBody>
+  );
+}

package/src/plugins/builtin/dividend-yield/ranking.ts

@@ -146,7 +146,7 @@ const RANKING_COLUMNS: HeadlessPaneColumn[] = [
   { key: "growth3Y", header: "3Y CAGR", align: "right", format: growth("growth3Y"),
     description: "Compound annual growth of trailing twelve-month cash per share over three years; n/a when either year holds fewer payments than the cadence pays." },
   { key: "lastExDate", header: "Last ex", format: day, shrink: false },
-  { key: "payDate", header: "Pay date", format: day, shrink: false, stackPriority: 2,
+  { key: "payDate", header: "Next pay", format: day, shrink: false, stackPriority: 2,
     description: "Pay date of the next declared distribution; past distributions carry ex-dates only." },
 ];
 

package/src/plugins/builtin/dividend-yield/view.ts

@@ -1,4 +1,7 @@
 import type { DividendPayment, GrowthPayments } from "./types";
+import { formatCurrency } from "../../../utils/format";
+import { currencyMinorDigits } from "../../../market-data/market/format";
+import { resolveCurrencyUnit } from "../../../utils/currency-units";
 import type { ProjectedChartPoint } from "../../../components/chart/core/data";
 import { calendarMonthsBefore } from "../../../utils/calendar-date";
 import { NOT_MEANINGFUL, formatPriceEarnings } from "../../../utils/price-earnings";
@@ -6,6 +9,24 @@ import { LATE_GRACE_DAYS, trailingCashAt, type TrailingPayments } from "../../..
 
 const DAY = 24 * 60 * 60 * 1000;
 
+/**
+ * A cash amount the listing pays as a conversion of the currency its company
+ * declares in (`DividendData.convertedFrom`), to two decimals of the unit its
+ * source states it in: pence stay pence (BP's 6.4059p is `6.41p`, never
+ * `£0.06`), and a major unit keeps its currency's decimals (`ZAR 0.87`, not
+ * `ZAR 0.866087`), as the conversion gives it no more.
+ */
+export function formatConvertedAmount(value: number | null | undefined, currency: string, subUnit?: string): string {
+  if (value == null || !Number.isFinite(value)) return "—";
+  const unit = subUnit ? resolveCurrencyUnit(subUnit) : null;
+  return unit && unit.divisor !== 1 && unit.currency === currency
+    ? formatCurrency(value * unit.divisor, subUnit!, 2)
+    : formatCurrency(value, currency, currencyMinorDigits(currency));
+}
+
+/** What a converted amount says beside it: `converted from USD`. */
+export const convertedFromText = (currency: string) => `converted from ${currency}`;
+
 export function formatDividendYield(value: number | null): string {
   return value != null && Number.isFinite(value) ? `${(value * 100).toFixed(2)}%` : "—";
 }

package/src/plugins/builtin/docs/index.tsx

@@ -6,7 +6,6 @@ import type { PaneTemplateContext, PaneTemplateCreateOptions } from "../../../ty
 import { getSharedRegistry } from "../../registry";
 import { buildRegistryHelpIndex } from "../help/function-index";
 import type { PluginModule } from "../plugin-module";
-import { DocsPane } from "./pane";
 import { docsTopicForArgument, docsTopicForPane } from "./targets";
 
 /** One reader: every request lands in the same pane, on top of its history. */
@@ -38,8 +37,8 @@ export const docsModule: PluginModule = {
       id: "docs",
       name: "Docs",
       icon: "?",
-      component: DocsPane,
-      reportFreshness: { status: "not-a-feed", basis: "documentation" },
+      get component(): typeof import("./pane").DocsPane { const { DocsPane } = require("./pane"); return DocsPane; },
+      reportFreshness: { status: "not-a-feed", basis: "documentation", local: true },
       // A page reads whole in a report, not cut at the first screen.
       shotFitsReader: true,
       defaultPosition: "right",

package/src/plugins/builtin/doe/client.ts

@@ -1,8 +1,8 @@
 import { apiClient } from "../../../api-client";
+import { sourceDidNotAnswer } from "../../../api-client/errors";
 import type { DoeBoardPayload, DoeSeriesRow } from "../../../api-client/doe";
-import { ApiRequestError } from "../../../api-client/errors";
 import { createPluginCache } from "../../../data/plugin-cache";
-import { cachedCloudResource, loadCloudResource } from "../shared/cloud-resource";
+import { cachedCloudResource, loadCloudResource, unavailableOnServer } from "../shared/cloud-resource";
 
 /** What the pane says while the server has no EIA weeks to serve: before the backend ships, or before its first read. */
 export const DOE_NOT_AVAILABLE = "Oil and gas inventories are not available yet.";
@@ -65,11 +65,12 @@ export async function fetchDoeBoard(client: Pick<typeof apiClient, "getCloudDoeB
   try {
     payload = await client.getCloudDoeBoard();
   } catch (error) {
-    if (error instanceof ApiRequestError && (error.status === 404 || error.status === 503)) throw new Error(DOE_NOT_AVAILABLE);
-    throw error;
+    throw unavailableOnServer(error, DOE_NOT_AVAILABLE, [404, 503]);
   }
   const board = validateDoeBoard(payload);
-  if (board.status === "unavailable" || !board.series.some((row) => row.value != null)) throw new Error(DOE_NOT_AVAILABLE);
+  // The server's source did not answer this time: a saved copy answers, as it does a 5xx.
+  if (board.status === "unavailable") throw sourceDidNotAnswer(DOE_NOT_AVAILABLE);
+  if (!board.series.some((row) => row.value != null)) throw new Error(DOE_NOT_AVAILABLE);
   return board;
 }
 

package/src/plugins/builtin/doe/headless.ts

@@ -49,6 +49,14 @@ function seasonalRows(row: DoeSeriesRow) {
     fiveYearLow: level(min), fiveYearAverage: level(average), fiveYearHigh: level(max) }));
 }
 
+/** Words for natural gas storage, which `NGS` reads, rather than a series of the petroleum tables. */
+const GAS_WORDS = new Set(["ngs", "ng", "gas", "natgas", "naturalgas", "natgasstorage", "naturalgasstorage", "gasstorage", "storage", "workinggas"]);
+
+/** Whether `DOE` was given a word for gas storage (`NGS`, `natural gas`) rather than a series. */
+export function doeGasWord(argument: string): boolean {
+  return GAS_WORDS.has(argument.toLowerCase().replace(/[^a-z]/g, ""));
+}
+
 /** `DOE` reads every tab unless one is named; `NGS` starts on gas storage; a series argument adds its year. */
 export function doeHeadless(defaultTab: DoeTab | "all"): HeadlessPaneDefinition<"bundle"> {
   return {
@@ -77,10 +85,13 @@ export function doeHeadless(defaultTab: DoeTab | "all"): HeadlessPaneDefinition<
           nextExpectedAt: oldestReportTime(reports.map((report) => report.nextReleaseAt)) };
       };
       const argument = Array.isArray(args.argument) ? args.argument.join(" ") : args.argument;
-      if (argument) {
+      // `DOE NGS` or `DOE natural gas` is the gas storage tables `NGS` opens on, and says so; `NGS gas` is them already.
+      const gasWord = argument ? doeGasWord(argument) : false;
+      const ngs = defaultTab === "gas";
+      if (argument && !gasWord) {
         const option = doeSeriesOption(argument);
         const row = option ? data.series.find((entry) => entry.id === option.value) : null;
-        if (!row) throw new Error("Use a series such as cushing, gasoline, distillate or east");
+        if (!row) throw new Error(`Use a series such as cushing, gasoline, distillate or east${ngs ? "" : "; for gas storage, gloom fn NGS"}`);
         return {
           sections: [
             { title: doeHeaderLine(doeReport(data, row.tab)) ?? row.label, columns: SUMMARY_COLUMNS, rows: [reportRow(row)] },
@@ -95,8 +106,10 @@ export function doeHeadless(defaultTab: DoeTab | "all"): HeadlessPaneDefinition<
           metadata: { ...data, series: [row], complete: data.status === "available" },
         };
       }
-      const tabs = args.options.tab === "all" || args.options.tab == null ? DOE_TABS.map(({ value }) => value) : [doeTab(args.options.tab)];
+      const tabs = gasWord ? ["gas" as const]
+        : args.options.tab === "all" || args.options.tab == null ? DOE_TABS.map(({ value }) => value) : [doeTab(args.options.tab)];
       return {
+        ...(gasWord && !ngs ? { warnings: [`Gas storage is its own function: gloom fn NGS (one region: gloom fn NGS east)`] } : {}),
         sections: tabs.map((tab) => ({
           title: `${DOE_TABS.find((entry) => entry.value === tab)!.label}${doeHeaderLine(doeReport(data, tab)) ? `: ${doeHeaderLine(doeReport(data, tab))}` : ""}`,
           columns: SUMMARY_COLUMNS,

package/src/plugins/builtin/doe/index.tsx

@@ -4,15 +4,16 @@ import type { PluginModule } from "../plugin-module";
 import { DOE_CATALOG_SERIES } from "./series";
 import { doeBoardCache } from "./client";
 import { doePriceCache } from "./prices";
-import { doeHeadless } from "./headless";
+import { doeGasWord, doeHeadless } from "./headless";
 import { DOE_SERIES_OPTIONS, doeSeriesOption } from "./model";
-import { DoePane } from "./pane";
 
 /** Opens on a tab, or on the series typed after the mnemonic and its tab. */
 function doeInstance(tab: DoeTab, options?: PaneTemplateCreateOptions): PaneTemplateInstanceConfig {
   const input = options?.arg?.trim();
+  // `DOE NGS` or `DOE natural gas` opens on gas storage, as `NGS` does.
+  if (input && doeGasWord(input)) return { placement: "floating", settings: { tab: "gas" } };
   const series = doeSeriesOption(input);
-  if (input && !series) throw new Error("Use a series such as cushing, gasoline, distillate or east");
+  if (input && !series) throw new Error(`Use a series such as cushing, gasoline, distillate or east${tab === "gas" ? "" : "; for gas storage, gloom fn NGS"}`);
   return { placement: "floating", settings: { tab: series?.tab ?? tab }, ...(series ? { params: { series: series.value } } : {}) };
 }
 
@@ -23,7 +24,7 @@ const shortcut = (prefix: string, tab: DoeTab | null) => ({
 
 export const doeModule: PluginModule = {
   series: DOE_CATALOG_SERIES,
-  panes: [{ id: "doe", name: "Oil and Gas Inventories", icon: "D", component: DoePane,
+  panes: [{ id: "doe", name: "Oil and Gas Inventories", icon: "D", get component(): typeof import("./pane").DoePane { const { DoePane } = require("./pane"); return DoePane; },
     defaultPosition: "right", defaultMode: "floating", defaultFloatingSize: { width: 96, height: 34 },
     tableExport: true, headless: doeHeadless("all") }],
   paneTemplates: [{

package/src/plugins/builtin/doe/prices.ts

@@ -2,7 +2,7 @@ import { apiClient } from "../../../api-client";
 import type { DoePricesPayload } from "../../../api-client/doe";
 import { createPluginCache } from "../../../data/plugin-cache";
 import type { SeriesDefinition } from "../../../series/types";
-import { cachedSeriesWarning } from "../shared/series-warning";
+import { cachedSeriesNote } from "../shared/series-warning";
 import { loadCloudResource, unavailableOnServer } from "../shared/cloud-resource";
 
 /**
@@ -73,10 +73,9 @@ export const DOE_PRICE_SERIES: readonly SeriesDefinition[] = PRICE_SERIES.map((s
     const resource = await loadCloudResource(doePriceCache, "prices", () => fetchDoePrices(), { validate: validatePrices });
     const row = resource.payload.series.find((entry) => entry.id === series.id);
     if (!row?.points.length) throw new Error(`${series.name} is not available yet.`);
-    const warning = cachedSeriesWarning(resource);
     return {
       points: row.points.map(([date, value]) => ({ date, value })),
-      ...(warning ? { warning } : {}),
+      ...cachedSeriesNote(resource),
       // Cited as the EIA series it is, not as the route that served it.
       attribution: { source: `EIA series ${series.key}`, publisher: "EIA" },
     };

package/src/plugins/builtin/doe/series.ts

@@ -1,6 +1,6 @@
 import type { DoeSeriesRow, DoeUnit } from "../../../api-client/doe";
 import type { SeriesDefinition, SeriesPoint } from "../../../series/types";
-import { cachedSeriesWarning } from "../shared/series-warning";
+import { cachedSeriesNote } from "../shared/series-warning";
 import { loadDoeBoard } from "./client";
 import { DOE_SERIES_OPTIONS } from "./model";
 import { DOE_PRICE_SERIES } from "./prices";
@@ -50,14 +50,14 @@ const DOE_SERIES: readonly SeriesDefinition[] = DOE_SERIES_OPTIONS.map((option):
     unit: UNITS[unit].unit,
     frequency: "weekly",
     group: "Energy",
-    tags: gas ? ["natural gas", "storage", "inventories"] : ["oil", "petroleum", "inventories", "US"],
+    // Jet fuel is kerosene, the word a reader may search it by.
+    tags: gas ? ["natural gas", "storage", "inventories"] : ["oil", "petroleum", "inventories", "US", ...option.value === "jet" ? ["kerosene"] : []],
     publisher: "EIA",
     load: async () => {
       const resource = await loadDoeBoard();
       const row = resource.payload.series.find((entry) => entry.id === option.value);
       if (!row) throw new Error(`${option.label} is not in this week's report.`);
-      const warning = cachedSeriesWarning(resource);
-      return { points: doeRowPoints(row), ...(warning ? { warning } : {}) };
+      return { points: doeRowPoints(row), ...cachedSeriesNote(resource) };
     },
   };
 });

package/src/plugins/builtin/earnings/board.tsx

@@ -10,6 +10,7 @@ import {
   type QueryBarFilter,
   type QueryBarView,
 } from "../../../components";
+import { ageFooterSegment } from "../../../components/layout/pane/footer";
 import { handleRefreshKey, usePaneRefreshKey } from "../../../components/data-table/table-pane";
 import { openFormModal } from "../../../components/form-modal";
 import { FILL_REST } from "../../../components/ui/fill";
@@ -305,7 +306,7 @@ export function EarningsBoard({ focused, width, height, scopedSymbols, highlight
     loading: resource.loading,
     error: resource.error ?? data?.refreshError ?? null,
     stale: !!data?.stale,
-    info: data && updatedAgo ? [{ id: "updated", parts: [{ text: updatedAgo, tone: "muted" as const }] }] : [],
+    info: data && updatedAgo ? [ageFooterSegment(updatedAgo)] : [],
   });
   const symbol = open?.symbol ?? selectedReport?.symbol ?? null;
   // The desktop and the web only: the terminal's footer stays as it was.

package/src/plugins/builtin/earnings/history.tsx

@@ -8,6 +8,7 @@ import {
   usePaneStatusFooter,
   type ChartTableChart,
 } from "../../../components";
+import { ageFooterSegment } from "../../../components/layout/pane/footer";
 import { staticSeries } from "../../../components/chart/static/series";
 import { usePaneRefreshKey } from "../../../components/data-table/table-pane";
 import { useAsyncResource, useAutoRefresh, usePluginPaneState, useUpdatedAgo } from "../../../public/react";
@@ -107,7 +108,7 @@ export function EarningsHistoryView({ symbol, width, height, focused, registrati
     error: historyError,
     stale: !!resource.data?.stale,
     info: abroad ? [{ id: "us-listings", parts: [{ text: "past reports: US listings only", tone: "muted" as const }] }]
-      : payload && updatedAgo ? [{ id: "updated", parts: [{ text: updatedAgo, tone: "muted" as const }] }] : [],
+      : payload && updatedAgo ? [ageFooterSegment(updatedAgo)] : [],
   });
 
   return (

package/src/plugins/builtin/earnings-calls/calendar.tsx

@@ -19,6 +19,8 @@ import {
   type SectionedRow,
 } from "../../../components";
 import { handleRefreshKey } from "../../../components/data-table/table-pane";
+import { savedCopyFooterInfo } from "../../../components/layout/pane/footer";
+import { isPermanentClientError } from "../../../api-client/errors";
 import { TABLE_COLUMN_GAP, tableColumnWidth } from "../../../components/ui/table-layout";
 import { useAsyncResource } from "../../../react/async-resource";
 import { useAgeClock, useAutoRefresh } from "../../../react/auto-refresh";
@@ -162,6 +164,8 @@ export function UpcomingCallsView({ focused, width, height, view, renderCompany
   }, [range]);
   const resource = useAsyncResource(entitled ? loader : null, {
     keepPreviousData: true,
+    // A refusal asking again will not change takes the calendar off screen, for its wall or its error.
+    clearOnError: isPermanentClientError,
     initialData: () => cachedUpcomingCalls(range),
   });
   const data = resource.data;
@@ -204,12 +208,16 @@ export function UpcomingCallsView({ focused, width, height, view, renderCompany
   const proRequired = !signInRequired && !verificationRequired && (!access.hasProAccess || (!data && refused === 402));
 
   const hints = useMemo<PaneHint[]>(() => [{ id: "search", key: "/", label: "search", onPress: focusSearch }], [focusSearch]);
+  // A refresh that failed shows the calendar an earlier read saved, and says when that copy is from.
+  const savedAt = data?.savedAt ?? null;
+  const savedInfo = useMemo(() => savedCopyFooterInfo([savedAt]), [savedAt]);
   usePaneStatusFooter({
     registrationId: "earnings-calls:calendar",
     enabled: !detailOpen && entitled,
     loading: resource.loading && !!data,
-    error: data ? data.refreshError ?? resource.error : null,
-    stale: !!data && (data.stale || !!resource.error),
+    error: data ? (savedAt == null ? data.refreshError : null) ?? resource.error : null,
+    stale: !!data && savedAt == null && (data.stale || !!resource.error),
+    info: savedInfo,
     hints,
   });
   // A calendar cut at the server's limit says so, rather than end the week early.

package/src/plugins/builtin/earnings-calls/data.ts

@@ -5,7 +5,7 @@ import {
   type CloudEarningsCallPayload,
   type CloudEarningsTranscriptPayload,
 } from "../../../api-client";
-import { ApiRequestError } from "../../../api-client/errors";
+import { ApiRequestError, isTransientFailure } from "../../../api-client/errors";
 import { listingAbroad, type IssuerListingParams, type ListingAbroad } from "../../../api-client/paths";
 import { servedFromSavedCopy } from "../../../data/saved-copies";
 import { areDifferentCompanies } from "../../../sources/sec-registrant";
@@ -45,6 +45,8 @@ export interface EarningsCallsResult {
   calls: CloudEarningsCallPayload[];
   fetchedAt: number;
   stale: boolean;
+  /** Its refresh failed and the copy saved at this time (ms) answered instead. */
+  savedAt?: number;
   refreshError?: string;
   /** HTTP status when the request failed, used to pick the right gate. */
   errorStatus?: number;
@@ -122,6 +124,8 @@ export interface UpcomingCallsResult {
   stale: boolean;
   /** The server answered its limit's worth: calls later on these days may be missing. */
   truncated?: boolean;
+  /** Its refresh failed and the copy saved at this time (ms) answered instead. */
+  savedAt?: number;
   refreshError?: string;
   errorStatus?: number;
 }
@@ -134,7 +138,7 @@ export interface UpcomingDays {
 let persistence: PluginPersistence | null = null;
 const activeUpcomingFetches = new Map<string, Promise<UpcomingCallsResult>>();
 const activeListFetches = new Map<string, Promise<EarningsCallsResult>>();
-const activeTranscriptFetches = new Map<string, Promise<CloudEarningsTranscriptPayload>>();
+const activeTranscriptFetches = new Map<string, Promise<EarningsTranscriptResult>>();
 
 export function attachEarningsCallsPersistence(value: PluginPersistence): void {
   persistence = value;
@@ -253,20 +257,21 @@ export async function loadEarningsCallsWithClient(
     .catch((error: unknown) => {
       const refreshError = error instanceof Error ? error.message : String(error);
       const errorStatus = statusOf(error);
-      // An auth failure must surface its gate rather than silently showing
-      // a cached list the user is no longer entitled to refresh.
+      // A refusal (signed out, no Pro, a route the server stopped serving) or a reply that fails
+      // validation is said rather than covered by a cached list.
       const expired = store?.getResource<CloudEarningsCallListPayload>(LIST_KIND, key, {
         sourceKey: CACHE_SOURCE,
         schemaVersion: LIST_CACHE_SCHEMA_VERSION,
         allowExpired: true,
       });
-      if (expired && errorStatus !== 401 && errorStatus !== 402 && errorStatus !== 403) {
+      if (expired && isTransientFailure(error)) {
         // A command that shows it ends with when the copy was saved, not with the failure.
         return servedFromSavedCopy({
           ...expired.value,
           ...sourceScope(expired.value.calls),
           fetchedAt: expired.fetchedAt,
           stale: true,
+          savedAt: expired.fetchedAt,
           refreshError,
           errorStatus,
         }, expired.fetchedAt);
@@ -367,9 +372,10 @@ export async function loadUpcomingCallsWithClient(
       const errorStatus = statusOf(error);
       // Losing Pro access re-gates the calendar, as it does the list.
       const expired = read(true);
-      if (expired && errorStatus !== 401 && errorStatus !== 402 && errorStatus !== 403) {
+      if (expired && isTransientFailure(error)) {
         return servedFromSavedCopy({
           ...upcomingFromCache(expired.value, expired.fetchedAt, true),
+          savedAt: expired.fetchedAt,
           refreshError: error instanceof Error ? error.message : String(error),
           errorStatus,
         }, expired.fetchedAt);
@@ -409,11 +415,14 @@ export function isPendingTranscript(
   return record.status === "pending" || !Array.isArray(record.turns);
 }
 
+/** A transcript, and when it was saved when its refresh failed and the saved copy answered. */
+export type EarningsTranscriptResult = CloudEarningsTranscriptPayload & { savedAt?: number };
+
 export async function loadTranscriptWithClient(
   client: EarningsCallsApiClient,
   callId: string,
   options?: { force?: boolean },
-): Promise<CloudEarningsTranscriptPayload> {
+): Promise<EarningsTranscriptResult> {
   const force = options?.force ?? false;
   const store = persistence;
 
@@ -444,7 +453,6 @@ export async function loadTranscriptWithClient(
       return transcript;
     })
     .catch((error: unknown) => {
-      const status = statusOf(error);
       const expired = store?.getResource<CloudEarningsTranscriptPayload>(
         TRANSCRIPT_KIND,
         callId,
@@ -455,8 +463,8 @@ export async function loadTranscriptWithClient(
         },
       );
       // Losing Pro access must re-gate the transcript, not serve it from cache.
-      if (expired && status !== 401 && status !== 402 && status !== 403) {
-        return expired.value;
+      if (expired && isTransientFailure(error)) {
+        return servedFromSavedCopy({ ...expired.value, savedAt: expired.fetchedAt }, expired.fetchedAt);
       }
       throw error;
     })
@@ -473,7 +481,7 @@ export async function loadTranscriptWithClient(
 export function loadTranscript(
   callId: string,
   options?: { force?: boolean },
-): Promise<CloudEarningsTranscriptPayload> {
+): Promise<EarningsTranscriptResult> {
   return loadTranscriptWithClient(apiClient, callId, options);
 }