gloomberb 0.16.4 → 0.16.6

package/src/plugins/builtin/central-bank-rates/headless.ts

@@ -1,25 +1,55 @@
-import type { HeadlessPaneDefinition } from "../../../types/plugin";
+import type { HeadlessPaneColumn, HeadlessPaneDefinition } from "../../../types/plugin";
 import { fetchCentralBankRates } from "./client";
-import { hasNoPolicyRate, policyBoardRow, policyNotices } from "./model";
+import { hasNoPolicyRate, policyExportRow, policyNextMeetingText, policyNotices } from "./model";
+
+/** The citation block every export row carries, headed as a journalist's spreadsheet names it. */
+const CITATION_FIELDS = [
+  "central_bank", "source", "series_id", "source_url", "as_of",
+  "next_meeting", "next_meeting_kind", "next_meeting_source_url", "next_meeting_verified_at", "citation",
+];
+
+const BOARD_COLUMNS: HeadlessPaneColumn[] = [
+  { key: "label", header: "Jurisdiction", shrink: false }, { key: "valueText", header: "Rate", align: "right" },
+  { key: "changeText", header: "Last move", align: "right" }, { key: "lastChangeDate", header: "Change observed", shrink: false },
+  { key: "percentileValue", header: "Pctl 1Y", align: "right", stackPriority: 1, format: (value) => value == null ? "--" : Number(value).toFixed(0) },
+  // A narrow terminal moves the instrument, status and percentile under each row first.
+  { key: "asOf", header: "As of", shrink: false }, { key: "status", header: "Status", stackPriority: 2 }, { key: "instrument", header: "Instrument", stackPriority: 3 },
+];
 
 export const centralBankRatesHeadless: HeadlessPaneDefinition<"bundle"> = {
   discovery: { aliases: ["CBR", "CBRT"], dataRequirements: ["Gloom Cloud central-bank-rates endpoint"],
-    limitations: ["Published policy observations with individual dates", "Policy instruments differ", "Only US meeting dates are maintained"] },
-  shape: "bundle", options: [], argument: { kind: "none" }, describe: "G20 central bank policy rates",
-  freshness: { source: "Central banks and BIS", status: "not-a-feed", basis: "published policy rates" },
-  async load(_args, ctx) {
+    limitations: ["Published policy observations with individual dates.", "Policy instruments differ.",
+      "Next meetings come from each bank's published calendar; SAMA publishes none, and China's date is the monthly LPR fixing."] },
+  shape: "bundle",
+  options: [{ key: "history", type: "boolean", defaultValue: false, description: "Add each row's one-year daily history to the JSON metadata." }],
+  argument: { kind: "none" }, describe: "Policy rates of the G20, SNB, Norges Bank, Riksbank and RBNZ",
+  // Each row is dated apart (BIS reports weekly, some banks weeks late), so exports cite the oldest as well.
+  freshness: { source: "BIS and FRED", publisher: "each row's central_bank, via BIS and FRED", status: "not-a-feed",
+    basis: "published policy rates", citeOldest: true },
+  async load(args, ctx) {
     const data = await fetchCentralBankRates(ctx.apiClient);
     const errors = policyNotices(data);
     const complete = data.status === "available" && errors.length === 0;
-    return { complete, sections: [{ title: "Policy rates", columns: [
-      { key: "label", header: "Jurisdiction" }, { key: "valueText", header: "Rate", align: "right" },
-      { key: "changeText", header: "Last move", align: "right" }, { key: "lastChangeDate", header: "Change observed" },
-      { key: "percentileValue", header: "Pctl 1Y", align: "right", format: (value) => value == null ? "--" : Number(value).toFixed(0) },
-      { key: "asOf", header: "As of" }, { key: "status", header: "Status" }, { key: "instrument", header: "Instrument" },
-    ], rows: data.rows.map(({ history: _history, ...row }) => {
-      const board = policyBoardRow({ ...row, history: [] });
-      return { ...row, valueText: board.valueText, changeText: board.changeText, percentileValue: row.percentile.value };
-    }) }], errors, unavailableSymbols: data.rows.filter((row) => row.status === "unavailable" && !hasNoPolicyRate(row)).map((row) => row.id),
-      metadata: { ...data, complete } };
+    // A row says "stale" in its status, not in a `stale` flag: hand the report its rows' staleness so its status line and a capture count them.
+    const observations = data.rows.filter((row) => row.status !== "unavailable")
+      .map((row) => ({ asOf: row.asOf, stale: row.status === "stale" }));
+    const exported = data.rows.map(policyExportRow);
+    // A caveat on most rows ("Change date is the first observed new level...") is said once for the report.
+    const shared = [...new Set(exported.flatMap((row) => row.notes))]
+      .filter((note) => exported.filter((row) => row.notes.includes(note)).length > 1);
+    const rows = exported.map((row) => ({ ...row, notes: row.notes.filter((note) => !shared.includes(note)) }));
+    return { complete, freshness: { observations }, ...(shared.length ? { notes: shared } : {}), sections: [{ title: "Policy rates",
+      columns: [...BOARD_COLUMNS, ...CITATION_FIELDS.map((key): HeadlessPaneColumn => ({ key, header: key, literalHeader: true }))],
+      rows,
+      // The text keeps the board's table; each row's bank, next meeting and citation go under it.
+      textColumns: [...BOARD_COLUMNS, { key: "detail", header: "Detail", underRow: true }],
+      textRows: rows.map((row, index) => {
+        const source = data.rows[index]!;
+        return { ...row, detail: `${row.central_bank ?? "No central bank"} · ${policyNextMeetingText(source)}\n${row.citation}` };
+      }),
+    }], errors, unavailableSymbols: data.rows.filter((row) => row.status === "unavailable" && !hasNoPolicyRate(row)).map((row) => row.id),
+    // A year of daily history per row is most of the payload, so JSON carries it only on request.
+    metadata: args.options.history === true ? { ...data, complete }
+      : { generatedAt: data.generatedAt, status: data.status, gaps: data.gaps, complete } };
   },
 };

package/src/plugins/builtin/central-bank-rates/index.tsx

@@ -2,14 +2,16 @@ import type { PluginModule } from "../plugin-module";
 import { centralBankRatesCache } from "./client";
 import { centralBankRatesHeadless } from "./headless";
 import { CentralBankRatesPane } from "./pane";
+import { CENTRAL_BANK_SERIES } from "./series";
 
 export const centralBankRatesModule: PluginModule = {
+  series: CENTRAL_BANK_SERIES,
   panes: [{ id: "central-bank-rates", name: "Central Bank Rates", icon: "%", component: CentralBankRatesPane,
     defaultPosition: "right", defaultMode: "floating", defaultFloatingSize: { width: 108, height: 25 },
     tableExport: true, headless: centralBankRatesHeadless }],
   paneTemplates: [{
     id: "central-bank-rates-cbr", paneId: "central-bank-rates", label: "Central Bank Rates",
-    description: "G20 policy rates, last observed changes and dated historical context.",
+    description: "Policy rates of the G20, SNB, Norges Bank, Riksbank and RBNZ, last observed changes and dated historical context.",
     keywords: ["central", "bank", "policy", "rates", "g20", "cbr", "cbrt"], shortcut: { prefix: "CBR", aliases: ["CBRT"] },
     headless: centralBankRatesHeadless,
   }],

package/src/plugins/builtin/central-bank-rates/model.ts

@@ -25,3 +25,102 @@ export function policyBoardRow(row: CentralBankRow): PolicyBoardRow {
     percentile: row.percentile.value, asOf: row.asOf, status: row.status, observation: row,
     history: policyHistory(row).flatMap((point) => point.value == null ? [] : [{ date: new Date(point.date), close: point.value }]) };
 }
+
+const SOURCE_LABELS = { bis: "BIS", fred: "FRED" } as const;
+
+/** Where the row's series is read from: `BIS` or `FRED`. */
+const policySource = (row: CentralBankRow) => row.source ? SOURCE_LABELS[row.source] : null;
+
+/** Each series' own page: one per FRED series (both bounds of the US range), the country's for BIS. */
+function policySeriesUrls(row: CentralBankRow): string[] {
+  if (row.source === "fred") return row.sourceSeriesIds.map((id) => `https://fred.stlouisfed.org/series/${id}`);
+  return row.sourceUrl ? [row.sourceUrl] : [];
+}
+
+/** `BIS series D.GB (url)`; a two-series range cites each bound: `FRED series DFEDTARL (lower bound, url) and DFEDTARU (upper bound, url)`. */
+function seriesCitation(row: CentralBankRow): string | null {
+  const source = policySource(row);
+  const ids = row.sourceSeriesIds;
+  const urls = policySeriesUrls(row);
+  if (!source || ids.length === 0) return null;
+  if (ids.length === 2 && urls.length === 2) return `${source} series ${ids[0]} (lower bound, ${urls[0]}) and ${ids[1]} (upper bound, ${urls[1]})`;
+  return `${source} series ${ids.join(" and ")}${urls.length ? ` (${urls.join(", ")})` : ""}`;
+}
+
+/**
+ * One line to cite the row by: its instrument and rate, the series it is read
+ * from with its page, and its own observation date, then the bank's site when
+ * that confirmed the level. `Bank Rate 3.75%, BIS series D.GB (https://...), as of 2026-10-05`.
+ */
+export function policyCitation(row: CentralBankRow): string {
+  const series = seriesCitation(row);
+  if (row.value == null) {
+    const missing = hasNoPolicyRate(row) ? `${row.label}: ${row.instrument.toLowerCase()}`
+      : `${row.instrument}: no current observation (${(row.unavailableReason ?? "unavailable").replaceAll("-", " ")})`;
+    return series ? `${missing}, ${series}` : missing;
+  }
+  const confirmed = row.confirmedAt && row.confirmationSourceUrl ? `; confirmed at ${row.confirmationSourceUrl} on ${row.confirmedAt.slice(0, 10)}` : "";
+  return `${row.instrument} ${policyLevel(row)}${series ? `, ${series}` : ""}, as of ${row.asOf}${confirmed}`;
+}
+
+interface PolicyNextMeeting {
+  /** The date, or why there is none: `not published`, `not verified`, `no policy rate`. */
+  text: string;
+  kind: "decision" | "fixing" | null;
+  sourceUrl: string | null;
+  verifiedAt: string | null;
+}
+
+/**
+ * The next decision from the bank's own calendar, or China's LPR fixing. A
+ * server that does not say why a meeting is missing predates the calendars,
+ * so its null reads as not published.
+ */
+function policyNextMeeting(row: CentralBankRow): PolicyNextMeeting {
+  const meeting = row.nextMeeting;
+  if (meeting) return { text: meeting.date, kind: meeting.kind ?? "decision", sourceUrl: meeting.sourceUrl, verifiedAt: meeting.verifiedAt };
+  const text = hasNoPolicyRate(row) || row.nextMeetingStatus === "no-policy-rate" ? "no policy rate"
+    : row.nextMeetingStatus === "not-verified" ? "not verified" : "not published";
+  return { text, kind: null, sourceUrl: null, verifiedAt: null };
+}
+
+/**
+ * `next decision 2026-11-05, calendar verified 2026-10-12 at https://...`,
+ * `next LPR fixing ...`, or `next decision not published`. The link comes
+ * last and bare, so a narrow terminal wraps it onto a line of its own, whole.
+ */
+export function policyNextMeetingText(row: CentralBankRow): string {
+  const meeting = policyNextMeeting(row);
+  if (meeting.text === "no policy rate") return meeting.text;
+  const event = meeting.kind === "fixing" ? "LPR fixing" : "decision";
+  return meeting.sourceUrl ? `next ${event} ${meeting.text}, calendar verified ${meeting.verifiedAt} at ${meeting.sourceUrl}` : `next ${event} ${meeting.text}`;
+}
+
+/**
+ * What an export says about one row, history aside: the board's figures and
+ * a citation block, `central_bank` to `citation`, named as CSV heads them.
+ * Notes keep the caveats on the latest rate; the BIS series definition goes
+ * with the history (`--history`).
+ */
+export function policyExportRow(row: CentralBankRow) {
+  const board = policyBoardRow({ ...row, history: [] });
+  const meeting = policyNextMeeting(row);
+  return {
+    id: row.id, label: row.label, instrument: row.instrument, central_bank: row.centralBank,
+    value: row.value, unit: row.unit, range: row.range, valueText: board.valueText,
+    changeBps: row.changeBps, changeText: board.changeText, lastChangeDate: row.lastChangeDate,
+    previousValue: row.previousValue, percentileValue: row.percentile.value,
+    asOf: row.asOf, lagDays: row.lagDays, status: row.status, unavailableReason: row.unavailableReason,
+    source: policySource(row), series_id: row.sourceSeriesIds.join(", ") || null, source_url: policySeriesUrls(row).join(" ") || null,
+    as_of: row.asOf, next_meeting: meeting.text, next_meeting_kind: meeting.kind,
+    next_meeting_source_url: meeting.sourceUrl, next_meeting_verified_at: meeting.verifiedAt,
+    citation: policyCitation(row), notes: row.notes.filter((note) => !row.seriesNotes?.includes(note)),
+  };
+}
+
+/** Who a chart of the row's series cites: `FRED series ECBDFR`, published by the European Central Bank. */
+export function policySeriesAttribution(row: CentralBankRow): { source: string; publisher?: string } | null {
+  const source = policySource(row);
+  if (!source || row.sourceSeriesIds.length === 0) return null;
+  return { source: `${source} series ${row.sourceSeriesIds.join(" and ")}`, ...(row.centralBank ? { publisher: row.centralBank } : {}) };
+}

package/src/plugins/builtin/central-bank-rates/pane.tsx

@@ -33,7 +33,7 @@ function PolicyDetail({ row, width, height, focused }: { row: CentralBankRow; wi
       detail: [row.publicationFrequency, row.lagDays == null ? null : `${row.lagDays}d lag`,
         row.confirmedAt ? `confirmed ${row.confirmedAt.slice(0, 10)}` : null, row.status === "stale" ? "stale" : null]
         .filter(Boolean).join(" · ") || undefined },
-    { id: "meeting", label: "Next meeting", value: row.nextMeeting?.date ?? "--" },
+    { id: "meeting", label: row.nextMeeting?.kind === "fixing" ? "Next fixing" : "Next meeting", value: row.nextMeeting?.date ?? "--" },
     { id: "source", label: "Source", value: row.source?.toUpperCase() ?? "--", detail: row.sourceSeriesIds.join(", ") || undefined },
     { id: "instrument", label: "Instrument", value: row.instrument, detail: row.centralBank ?? undefined, wide: true },
   ];

package/src/plugins/builtin/central-bank-rates/series.ts

@@ -0,0 +1,36 @@
+import type { SeriesDefinition } from "../../../series/types";
+import { CENTRAL_BANKS, centralBankNames } from "../../../utils/central-banks";
+import { cachedSeriesWarning } from "../shared/series-warning";
+import { loadCentralBankRates } from "./client";
+import { policySeriesAttribution } from "./model";
+
+/**
+ * The board rows the endpoint reads from FRED (the Fed's and the ECB's rates,
+ * `source: "fred"` on the row); every other row is the BIS central bank policy
+ * rates (`source: "bis"`). Check a new bank against `fn CBR --json`.
+ */
+const FRED_ROWS: ReadonlySet<string> = new Set(["US", "EA"]);
+
+/** One policy rate per bank on the board; a search finds it by any of the bank's names ("SNB", "Norges Bank"). */
+export const CENTRAL_BANK_SERIES: readonly SeriesDefinition[] = CENTRAL_BANKS.map((bank) => ({
+  id: `policy-rate:${bank.id.toLowerCase()}`,
+  name: `${bank.place} policy rate (${bank.instrument})`,
+  unit: "%",
+  frequency: "daily",
+  group: "Rates",
+  publisher: FRED_ROWS.has(bank.id) ? "FRED" : "BIS",
+  tags: ["central bank", "policy rate", bank.id, ...centralBankNames(bank)],
+  load: async () => {
+    const resource = await loadCentralBankRates();
+    const row = resource.payload.rows.find((entry) => entry.id === bank.id);
+    if (!row) throw new Error(`${bank.place} is not on the board right now.`);
+    const warning = cachedSeriesWarning(resource);
+    // Cited as CBR cites the row: the BIS or FRED series and the bank that sets the rate.
+    const attribution = policySeriesAttribution(row);
+    return {
+      points: row.history.map((point) => ({ date: point.date, value: point.value })),
+      ...(warning ? { warning } : {}),
+      ...(attribution ? { attribution } : {}),
+    };
+  },
+}));