gloomberb 0.18.3 → 0.18.4

package/src/plugins/builtin/cot/model.ts

@@ -205,6 +205,18 @@ export function cotMarketName(name: string): string {
   const cut = name.lastIndexOf(" - ");
   return cut > 0 ? name.slice(0, cut).trim() : name.trim();
 }
+/** Units the CFTC spells in capitals that read as plain words: "100 TROY OUNCES" is "100 troy ounces". */
+const PLAIN_UNITS = /^[\d,.]+ (?:TROY OUNCES|BUSHELS|BARRELS|POUNDS|GALLONS|METRIC TONS|SHORT TONS|TONS|BOARD FEET)$/;
+/**
+ * What one contract is, from the CFTC's contract units: "1 contract = 100
+ * troy ounces" for "(CONTRACTS OF 100 TROY OUNCES)". Anything else keeps the
+ * CFTC's spelling ("$50 X S&P 500 INDEX", "JPY 12,500,000", "2,500 MMBtu").
+ * Null where the report states none.
+ */
+export function cotContractUnitText(units: string | null | undefined): string | null {
+  const text = (units ?? "").replace(/^\((.*)\)$/s, "$1").replace(/^contracts of\s+/i, "").replace(/\s+/g, " ").trim();
+  return text ? `1 contract = ${PLAIN_UNITS.test(text) ? text.toLowerCase() : text}` : null;
+}
 export function cotInteger(value: number | null, signed = false): string {
   return value == null ? "--" : `${signed && value > 0 ? "+" : ""}${value.toLocaleString("en-US", { maximumFractionDigits: 0 })}`;
 }

package/src/plugins/builtin/cot/pane.tsx

@@ -13,7 +13,7 @@ import { useAutoRefresh } from "../../../react/auto-refresh";
 import { compareSortValues, nextHeaderSort, type SortPreference } from "../../../utils/sort-values";
 import { useResearchCloudSession } from "../shared/research-cloud-session";
 import { cachedCotBoard, loadCotBoard, loadCotDetail } from "./client";
-import { COT_CLASSES, COT_MAJOR_CODES, COT_SCOPES, cotChartSeries, cotClass, cotInteger, cotLegendValue, cotMarketName, cotScope, type CotScope } from "./model";
+import { COT_CLASSES, COT_MAJOR_CODES, COT_SCOPES, cotChartSeries, cotClass, cotContractUnitText, cotInteger, cotLegendValue, cotMarketName, cotScope, type CotScope } from "./model";
 
 const FAMILIES = [{ value: "legacy", label: "Legacy" }, { value: "disaggregated", label: "Disaggregated" }];
 const BOARD_COLUMNS: DataTableColumn[] = [
@@ -177,7 +177,8 @@ function CotDetail({ width, height, focused, code, family, traderClass, onClassC
   });
   usePaneNoticeFooter({ registrationId: "cot:detail-notices", focused, notices: [...(payload?.gaps ?? []), ...(data?.priceWarning ? [data.priceWarning] : []), ...partialRanks] });
   usePaneStatusFooter({ registrationId: "cot:detail", loading: resource.loading, error: resource.error,
-    info: payload ? [{ id: "as-of", parts: [{ text: `CFTC ${payload.asOf ?? "--"} · contracts${data?.priceAsOf ? ` · ${data.priceSymbol} ${data.priceAsOf}` : ""}`, tone: "muted" }] }] : [] });
+    // The unit the net is counted in, as `fn COT` titles it: what one contract is, where the report says.
+    info: payload ? [{ id: "as-of", parts: [{ text: `CFTC ${payload.asOf ?? "--"} · ${cotContractUnitText(payload.contract?.contractUnits) ?? "contracts"}${data?.priceAsOf ? ` · ${data.priceSymbol} ${data.priceAsOf}` : ""}`, tone: "muted" }] }] : [] });
   return <PaneStatusBody loading={resource.loading && !data} error={!data ? resource.error : null} empty={!!payload && !payload.contract} subject="COT contract">
     {payload && data ? <DataTableView columns={POSITION_COLUMNS} items={payload.positions} focused={focused} rootWidth={width} rootHeight={height}
       rootBefore={<ChartTableHeader width={width} height={height} tableRows={payload.positions.length} chart={chart}

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

@@ -52,8 +52,12 @@ export const cpiHeadless: HeadlessPaneDefinition<"bundle"> = {
     const headline = data.rows.find((row) => row.code === "SA0") ?? null;
     const argument = Array.isArray(args.argument) ? args.argument.join(" ") : args.argument;
     const metadata = { ...data, complete: data.status === "available" };
+    // The month the figures cover and when BLS released them: `Sep 2026, released Wed 14 Oct 12:30 UTC`.
+    const period = data.release.period && data.release.releasedAt
+      ? { asOf: `${data.release.period}-01`, periodicity: "monthly" as const, releasedOn: data.release.releasedAt }
+      : { asOf: data.release.releasedAt };
     const freshness = { source: "BLS", status: "not-a-feed" as const, basis: "monthly release",
-      asOf: data.release.releasedAt, nextExpectedAt: data.release.nextReleaseAt };
+      ...period, nextExpectedAt: data.release.nextReleaseAt };
     if (argument) {
       const option = cpiRowOption(argument);
       const row = option ? data.rows.find((entry) => entry.id === option.value) : null;

package/src/plugins/builtin/cpi/pane.tsx

@@ -1,12 +1,14 @@
 import { useCallback, useMemo } from "react";
 import type { CpiBoardPayload, CpiRow } from "../../../api-client/cpi";
 import {
+  ChartRead,
   ChartTableHeader,
   CompositeChart,
   DataTableView,
   formatPercentAxis,
   PaneStatusBody,
   QueryBar,
+  useChartReadRows,
   usePaneNoticeFooter,
   usePaneStatusFooter,
   type ChartTableChart,
@@ -20,7 +22,6 @@ import { useThemeColors } from "../../../theme/theme-context";
 import type { ResolvedSeries } from "../../../time-series/types";
 import type { PaneProps } from "../../../types/plugin";
 import { Box, TextAttributes } from "../../../ui";
-import { ClippedText } from "../../../components/ui/display";
 import { nextHeaderSort } from "../../../utils/sort-values";
 import { CPI_NOT_AVAILABLE, getCachedCpiBoard, loadCpiBoard } from "./client";
 import {
@@ -52,8 +53,8 @@ const COLUMNS: DataTableColumn[] = [
   { id: "contributionYoy", label: "Y/Y Pts", width: 8, align: "right", flexGrow: 1 },
 ];
 const PANELS = [{ id: "main" }];
-/** Legend, four plot rows, the time axis and the read under it. */
-const CHART_MIN_ROWS = 7;
+/** Legend, four plot rows and the time axis; the read under them takes its own rows. */
+const CHART_ROWS_ABOVE_READ = 6;
 
 /** Legend values in the table's units: changes in percent. */
 const legendValue = (value: number) => `${value.toFixed(2)}%`;
@@ -64,18 +65,17 @@ const legendValue = (value: number) => `${value.toFixed(2)}%`;
  * the latest month so the legend reads it; the plain read sits under the axis.
  */
 function CpiChart({ row, series, width, height }: { row: CpiRow; series: ResolvedSeries[]; width: number; height: number }) {
-  const colors = useThemeColors();
   const latest = row.history.at(-1)?.[0] ?? null;
   const axis = useMemo(() => cpiTimeAxis(row.history), [row.history]);
-  // The plain read under the axis; the desktop cuts it where its line ends.
-  const read = row.read && width > 2 ? row.read : "";
+  // The plain read under the axis: wrapped in the terminal, cut by CSS where its line ends on the desktop.
+  const readRows = useChartReadRows([row.read], width);
   return (
     <Box width={width} height={height} flexDirection="column">
-      <CompositeChart series={series} panels={PANELS} width={width} height={Math.max(3, height - (read ? 1 : 0))}
+      <CompositeChart series={series} panels={PANELS} width={width} height={Math.max(3, height - readRows)}
         focused={false} navigable={false} showLegend showTimeAxis cursorDate={latest ? cpiMonthDate(latest) : null}
         viewport={axis?.viewport} xAxis={axis?.xAxis} clipToViewport={!!axis}
         formatValue={legendValue} formatAxisValue={formatPercentAxis} remoteKind="cpi-component-history" />
-      {read ? <Box height={1} paddingX={1}><ClippedText fg={colors.textMuted} text={read} width={width - 2} /></Box> : null}
+      <ChartRead text={row.read} width={width} />
     </Box>
   );
 }
@@ -92,9 +92,11 @@ function CpiBoard({ payload, initialRow, width, height, focused }: {
   const headline = payload.rows.find((row) => row.code === "SA0") ?? null;
   const series = useMemo(() => selected ? cpiChartSeries(selected, headline, colors) : [], [selected, headline, colors]);
   const meta = cpiHeaderLine(payload.release);
+  // Room for the longest read at this width, so the chart does not give way to the strip as the selection moves.
+  const readRows = useChartReadRows(rows.map((row) => row.read), width);
   const chart: ChartTableChart | null = selected ? {
     render: (size) => <CpiChart row={selected} series={series} width={size.width} height={size.height} />,
-    minRows: CHART_MIN_ROWS,
+    minRows: CHART_ROWS_ABOVE_READ + Math.max(1, readRows),
     strip: cpiChartStrip(selected, colors.warning),
     empty: series.length ? undefined : `No history for ${selected.label}`,
   } : null;

package/src/plugins/builtin/credit-boards/model.ts

@@ -239,6 +239,8 @@ export function sovrRows(
     return {
       id: sovereign.id,
       label: sovereign.name,
+      // The sovereign's flag, by its name, leads the row on the desktop.
+      country: sovereign.name,
       value: sovereign.level,
       valueText: formatLevel("spread", sovereign.level),
       change: shown("spread", sovereign.change1M),

package/src/plugins/builtin/credit-documents/headless.ts

@@ -61,7 +61,7 @@ export function creditEmptyReason(
   const why = data.issuer
     ? `No credit documents on file for ${data.issuer.name} (${symbol}): no debt instrument has been read from its filings yet.`
     : `No credit documents on file for ${symbol}: it is not an issuer the credit-document set covers.`;
-  const example = creditIssuerSymbol(symbol) === CREDIT_EXAMPLE_SYMBOL ? "" : ` Try \`gloomberb fn CRDOC ${CREDIT_EXAMPLE_SYMBOL}\` for an issuer with documents.`;
+  const example = creditIssuerSymbol(symbol) === CREDIT_EXAMPLE_SYMBOL ? "" : ` Try \`gloom fn CRDOC ${CREDIT_EXAMPLE_SYMBOL}\` for an issuer with documents.`;
   return `${why}${example}`;
 }
 

package/src/plugins/builtin/crypto-board/client.ts

@@ -3,6 +3,7 @@ import { ApiRequestError } from "../../../api-client/errors";
 import type {
   CryptoMarketAsset,
   CryptoMarketsPayload,
+  DefiTvlPayload,
   StablecoinSupplyHistoryPayload,
   StablecoinSupplyPayload,
 } from "../../../api-client/crypto-markets";
@@ -281,3 +282,88 @@ export function loadStablecoinSupplyHistory(symbol: string) {
     }
   }, { validate: validateStablecoinSupplyHistory });
 }
+
+// DeFi TVL ---------------------------------------------------------------------
+
+const defiTvlCache = createPluginCache<DefiTvlPayload>({
+  kind: "defi-tvl",
+  source: "gloom-cloud",
+  schemaVersion: 1,
+  // The server reads the source once a UTC day; a month-old copy still dates itself.
+  policy: { staleMs: 30 * 60_000, expireMs: 30 * 86_400_000 },
+});
+
+export const DEFI_TVL_CACHES = [defiTvlCache] as const;
+
+const MAX_TVL_DAYS = 20_000;
+const tvlValue = (value: unknown) => value === null || (isFiniteNumber(value) && value >= 0);
+const changes = (entry: { change7d: unknown; change7dPercent: unknown; change30d: unknown; change30dPercent: unknown }) =>
+  [entry.change7d, entry.change7dPercent, entry.change30d, entry.change30dPercent].every(nullableNumber);
+
+export function validateDefiTvl(data: DefiTvlPayload): DefiTvlPayload {
+  const history = data?.history;
+  if (
+    !data
+    || data.version !== 1
+    || !instant(data.generatedAt)
+    || !nullableInstant(data.fetchedAt)
+    || !(data.asOf === null || date(data.asOf))
+    || !supplyStatus(data.status)
+    || !data.source
+    || typeof data.source.name !== "string"
+    || typeof data.source.url !== "string"
+    || (data.total !== null && (!data.total || !isFiniteNumber(data.total.tvl) || !changes(data.total)))
+    || !Array.isArray(data.protocols)
+    || data.protocols.length > 500
+    || !data.protocols.every((protocol) => !!protocol
+      && typeof protocol.name === "string"
+      && protocol.name.length > 0
+      && nullableString(protocol.category)
+      && Number.isInteger(protocol.chains)
+      && isFiniteNumber(protocol.tvl)
+      && protocol.tvl >= 0
+      && nullableNumber(protocol.change1dPercent)
+      && changes(protocol))
+    || !nullableInstant(data.protocolsAsOf)
+    || !Array.isArray(data.chains)
+    || data.chains.length > 500
+    || !data.chains.every((chain) => !!chain
+      && typeof chain.name === "string"
+      && chain.name.length > 0
+      && nullableString(chain.tokenSymbol)
+      && isFiniteNumber(chain.tvl)
+      && chain.tvl >= 0
+      && nullableNumber(chain.share)
+      && changes(chain))
+    || (history !== null && (
+      !history
+      || !date(history.start)
+      || !Array.isArray(history.total)
+      || history.total.length > MAX_TVL_DAYS
+      || !history.total.every(tvlValue)
+    ))
+    || !Array.isArray(data.warnings)
+    || data.warnings.some((warning) => typeof warning !== "string")
+  ) {
+    throw new Error("The server returned invalid DeFi TVL");
+  }
+  return data;
+}
+
+export async function fetchDefiTvl(
+  client: Pick<typeof apiClient, "getCloudDefiTvl"> = apiClient,
+): Promise<DefiTvlPayload> {
+  try {
+    return validateDefiTvl(await client.getCloudDefiTvl());
+  } catch (error) {
+    throw supplyError(error, "DeFi TVL");
+  }
+}
+
+export function cachedDefiTvl() {
+  return cachedCloudResource(defiTvlCache, "all", validateDefiTvl);
+}
+
+export function loadDefiTvl(force = false) {
+  return loadCloudResource(defiTvlCache, "all", () => fetchDefiTvl(), { force, validate: validateDefiTvl });
+}

package/src/plugins/builtin/crypto-board/defi-view.tsx

@@ -0,0 +1,218 @@
+import { useCallback, useMemo, useState } from "react";
+import {
+  ChartTableHeader,
+  DataTableView,
+  PaneStatusBody,
+  QueryBar,
+  stackedSeries,
+  type DataTableCell,
+  type DataTableKeyEvent,
+  type StatItem,
+} from "../../../components";
+import { formatCompactAxis } from "../../../components/chart-table";
+import { handleRefreshKey } from "../../../components/data-table/table-pane";
+import type { DefiTvlPayload } from "../../../api-client/crypto-markets";
+import { colors, priceColor } from "../../../theme/colors";
+import { SERIES_COLORS } from "../../../theme/series-colors";
+import { formatCompact, formatCompactAmount } from "../../../utils/format";
+import { usePluginPaneState } from "../../runtime";
+import {
+  buildDefiColumns,
+  buildDefiRows,
+  DEFAULT_DEFI_SORT,
+  DEFI_LISTS,
+  defiFailure,
+  defiHistory,
+  defiHistoryStart,
+  defiListAsOf,
+  nextDefiSort,
+  sortDefiRows,
+  type DefiColumn,
+  type DefiList,
+  type DefiRow,
+  type DefiSortPreference,
+} from "./defi";
+import { formatCryptoPercent } from "./model";
+import { SUPPLY_RANGES, type SupplyRangeId } from "./supply";
+
+const RANGE_OPTIONS = SUPPLY_RANGES.map(({ value, label }) => ({ value, label }));
+const LIST_OPTIONS = DEFI_LISTS.map(({ value, label }) => ({ value, label }));
+
+const formatTvl = (value: number) => formatCompact(value, { fixedDecimals: true });
+
+function signedPercent(value: number | null): DataTableCell {
+  return { text: formatCryptoPercent(value), color: value == null ? colors.textDim : priceColor(value) };
+}
+
+function signedAmount(value: number | null): DataTableCell {
+  return {
+    text: value == null ? "—" : formatCompactAmount(value, { signed: true }),
+    color: value == null ? colors.textDim : priceColor(value),
+  };
+}
+
+function renderDefiCell(row: DefiRow, column: DefiColumn): DataTableCell {
+  switch (column.id) {
+    case "rank":
+      return { text: String(row.rank), color: colors.textDim };
+    case "name":
+      return { text: row.name, color: colors.textBright };
+    case "detail":
+      return { text: row.detail ?? "—", color: colors.textDim };
+    case "tvl":
+      return { text: formatTvl(row.tvl) };
+    case "change1dPercent":
+      return signedPercent(row.change1dPercent);
+    case "change7d":
+      return signedAmount(row.change7d);
+    case "change7dPercent":
+      return signedPercent(row.change7dPercent);
+    case "change30d":
+      return signedAmount(row.change30d);
+    case "change30dPercent":
+      return signedPercent(row.change30dPercent);
+    case "share":
+      return { text: row.share == null ? "—" : `${row.share.toFixed(2)}%`, color: colors.textDim };
+    case "chains":
+      return { text: row.chains == null ? "—" : String(row.chains), color: colors.textDim };
+  }
+}
+
+/** A TVL change as a figure: the amount, its percent beside it, coloured by direction. */
+function changeFigure(id: string, label: string, amount: number | null, percent: number | null): StatItem {
+  return {
+    id,
+    label,
+    value: amount == null ? "—" : formatCompactAmount(amount, { signed: true }),
+    detail: formatCryptoPercent(percent),
+    ...(amount == null ? {} : { color: priceColor(amount) }),
+  };
+}
+
+export interface DefiResourceState {
+  payload: DefiTvlPayload | null;
+  loading: boolean;
+  error: string | null;
+  reload: () => unknown;
+}
+
+/**
+ * CRYP's DeFi tab: the total DeFi TVL with its 7D and 30D change, its daily
+ * history, and the largest protocols or chains below. Every figure carries its
+ * date and who measures it, and the history says the day it starts.
+ */
+export function DefiTvlView({
+  width,
+  height,
+  focused,
+  resource,
+}: {
+  width: number;
+  height: number;
+  focused: boolean;
+  resource: DefiResourceState;
+}) {
+  const { payload } = resource;
+  const [list, setList] = usePluginPaneState<DefiList>("defiList", "protocol");
+  const [range, setRange] = usePluginPaneState<SupplyRangeId>("defiRange", "1Y");
+  const [selectedId, setSelectedId] = usePluginPaneState<string | null>("defiSelected", null);
+  const [sort, setSort] = useState<DefiSortPreference>(DEFAULT_DEFI_SORT);
+  const rows = useMemo(() => sortDefiRows(buildDefiRows(payload, list), sort), [list, payload, sort]);
+  const columns = useMemo(() => buildDefiColumns(width, list), [list, width]);
+  // A chain's figures are the total's day, which its figure dates; protocols are read live, so they say when.
+  const listAsOf = list === "protocol" ? defiListAsOf(payload, list) : null;
+
+  const series = useMemo(() => {
+    const history = defiHistory(payload, range);
+    if (!history) return [];
+    return stackedSeries(history.dates, [{ id: "tvl", label: "DeFi TVL", color: SERIES_COLORS[0]!, values: history.values }], { calendarSpaced: true });
+  }, [payload, range]);
+  const figures = useMemo<StatItem[]>(() => {
+    const total = payload?.total;
+    if (!payload || !total) return [];
+    const since = defiHistoryStart(payload);
+    return [
+      { id: "total", label: "Total DeFi TVL", value: formatTvl(total.tvl), ...(payload.asOf ? { detail: `as of ${payload.asOf}` } : {}) },
+      changeFigure("change-7d", "7D change", total.change7d, total.change7dPercent),
+      changeFigure("change-30d", "30D change", total.change30d, total.change30dPercent),
+      { id: "source", label: "Source", value: payload.source.name, ...(since ? { detail: `daily since ${since}` } : {}) },
+    ];
+  }, [payload]);
+
+  const reload = resource.reload;
+  const handleKeyDown = useCallback((event: DataTableKeyEvent) => (
+    handleRefreshKey(event, () => { void reload(); }, { stopPropagation: true })
+  ), [reload]);
+
+  const failure = !payload && resource.error ? defiFailure(resource.error) : null;
+
+  return (
+    <PaneStatusBody
+      loading={resource.loading && !payload}
+      // The failure names DeFi TVL itself, so it is the title and is said once.
+      error={failure}
+      errorTitle={failure ?? undefined}
+      subject="DeFi TVL"
+      empty={!!payload && !payload.total && !rows.length}
+      emptyTitle="No DeFi TVL yet."
+    >
+      <DataTableView<DefiRow, DefiColumn>
+        focused={focused}
+        selection={{
+          kind: "id",
+          selectedId: selectedId && rows.some((row) => row.id === selectedId) ? selectedId : rows[0]?.id ?? null,
+          getId: (row) => row.id,
+          onChange: (id) => setSelectedId(id),
+        }}
+        onRootKeyDown={handleKeyDown}
+        resetScrollKey={list}
+        columns={columns}
+        items={rows}
+        sortable
+        sortColumnId={sort.columnId}
+        sortDirection={sort.direction}
+        onHeaderClick={(columnId) => setSort((current) => nextDefiSort(current, columnId))}
+        onSortChange={(columnId, direction) => setSort({ columnId: columnId as DefiSortPreference["columnId"], direction })}
+        getItemKey={(row) => row.id}
+        renderCell={renderDefiCell}
+        selectedTextOverridesCellColor
+        emptyStateTitle={list === "chain" ? "No chains returned." : "No protocols returned."}
+        rootBefore={(
+          <ChartTableHeader
+            width={width}
+            height={height}
+            tableRows={rows.length}
+            tableColumns={columns}
+            query={(
+              <QueryBar
+                width={width}
+                filters={[{
+                  id: "list",
+                  label: "List",
+                  inline: true,
+                  value: list,
+                  options: LIST_OPTIONS,
+                  onChange: (value: string) => {
+                    setList(value === "chain" ? "chain" : "protocol");
+                    setSelectedId(null);
+                  },
+                }]}
+                view={{ value: range, options: RANGE_OPTIONS, onChange: setRange, chartRange: true }}
+                {...(listAsOf ? { asOf: `as of ${listAsOf}` } : {})}
+              />
+            )}
+            figures={figures}
+            chart={{
+              series,
+              formatValue: formatTvl,
+              formatAxisValue: formatCompactAxis,
+              remoteKind: "defi-tvl-history",
+              loading: resource.loading && !payload,
+              empty: "No DeFi TVL history yet.",
+            }}
+          />
+        )}
+      />
+    </PaneStatusBody>
+  );
+}