gloomberb 0.18.3 → 0.18.4

package/src/plugins/builtin/crypto-board/pane.tsx

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useMemo, useState } from "react";
-import { Box, TextAttributes } from "../../../ui";
+import { Box, TextAttributes, useUiCapabilities } from "../../../ui";
+import { withCompanyLogo } from "../../../components/company-logo";
 import {
   ChartTableHeader,
   DataTableView,
@@ -38,7 +39,9 @@ import { usePluginPaneState, usePluginTickerActions } from "../../runtime";
 import { useLiveStreamingSetting } from "../../../state/hooks/live-streaming";
 import { useResearchCloudSession } from "../shared/research-cloud-session";
 import { INITIAL_STREAM_RANGE, streamWindowRows } from "../shared/use-quote-board";
-import { cachedCryptoMarkets, cachedStablecoinSupply, loadCryptoMarkets, loadStablecoinSupply } from "./client";
+import { cachedCryptoMarkets, cachedDefiTvl, cachedStablecoinSupply, loadCryptoMarkets, loadDefiTvl, loadStablecoinSupply } from "./client";
+import { defiFailure } from "./defi";
+import { DefiTvlView } from "./defi-view";
 import {
   buildCryptoColumns,
   buildCryptoRows,
@@ -56,6 +59,7 @@ import {
   type CryptoColumn,
   type CryptoRow,
   type CryptoSortPreference,
+  type CryptoTab,
 } from "./model";
 import { stackedSupply, SUPPLY_RANGES, supplyByCode, supplyFailure, type SupplyRangeId } from "./supply";
 
@@ -91,7 +95,8 @@ function quoteTargets(
   }));
 }
 
-function renderCryptoCell(row: CryptoRow, column: CryptoColumn): DataTableCell {
+/** `logos`: the desktop and the web lead each name with the coin's logo; the terminal draws none. */
+function renderCryptoCell(row: CryptoRow, column: CryptoColumn, logos: boolean): DataTableCell {
   const signed = (value: number | null) => ({
     text: formatCryptoPercent(value),
     color: value == null ? colors.textDim : priceColor(value),
@@ -102,7 +107,7 @@ function renderCryptoCell(row: CryptoRow, column: CryptoColumn): DataTableCell {
     case "code":
       return { text: row.code, color: colors.textBright, attributes: TextAttributes.BOLD };
     case "name":
-      return { text: row.name };
+      return withCompanyLogo({ text: row.name }, { symbol: row.code, assetCategory: "CRYPTO", name: row.name }, logos);
     case "price":
       return { text: row.priceText };
     case "changePercent":
@@ -183,7 +188,7 @@ export function CryptoBoardPane({ width, height, focused }: PaneProps) {
   const data = resource.data?.payload;
   const { pinTicker } = usePluginTickerActions();
   const liveStreaming = useLiveStreamingSetting();
-  const [activeTab, setActiveTab] = usePluginPaneState<CryptoAssetKind>("activeTab", "coin");
+  const [activeTab, setActiveTab] = usePluginPaneState<CryptoTab>("activeTab", "coin");
   const [selectedId, setSelectedId] = usePluginPaneState<string | null>("selected", null);
   const [sort, setSort] = useState<CryptoSortPreference>(DEFAULT_CRYPTO_SORT);
   const [visibleRange, setVisibleRange] = useState(INITIAL_STREAM_RANGE);
@@ -202,16 +207,29 @@ export function CryptoBoardPane({ width, height, focused }: PaneProps) {
   const [supplyRange, setSupplyRange] = usePluginPaneState<SupplyRangeId>("supplyRange", "1Y");
   const stablecoins = activeTab === "stablecoin";
 
+  // DeFi TVL likewise loads once its tab is first shown; the server reads it once a UTC day.
+  const defi = activeTab === "defi";
+  const [defiShown, setDefiShown] = useState(defi);
+  useEffect(() => {
+    if (defi) setDefiShown(true);
+  }, [defi]);
+  const defiLoader = useCallback((force: boolean) => loadDefiTvl(force), [session.requestKey]);
+  const defiResource = useAsyncResource(defiShown ? defiLoader : null, { initialData: cachedDefiTvl });
+  const defiPayload = defiResource.data?.payload ?? null;
+  useAutoRefresh(defiResource.updatedAt, defiResource.load, { intervalMs: SUPPLY_REFRESH_MS });
+
+  // The DeFi tab lists no assets; the coin and stablecoin streams stop while it shows.
+  const assetKind: CryptoAssetKind = activeTab === "stablecoin" ? "stablecoin" : "coin";
   const tabAssets = useMemo(
-    () => data?.assets.filter((asset) => asset.kind === activeTab) ?? [],
-    [activeTab, data],
+    () => (defi ? [] : data?.assets.filter((asset) => asset.kind === activeTab) ?? []),
+    [activeTab, data, defi],
   );
   // The stream follows the rows on screen. Ordering by the board snapshot keeps
   // live ticks from reshuffling the subscription; the overscan covers the drift.
   const streamedAssets = useMemo(() => {
-    const ordered = sortCryptoRows(buildCryptoRows(tabAssets, activeTab, NO_QUOTES), sort).map((row) => row.asset);
+    const ordered = sortCryptoRows(buildCryptoRows(tabAssets, assetKind, NO_QUOTES), sort).map((row) => row.asset);
     return streamWindowRows(ordered, visibleRange, ordered.find((asset) => asset.symbol === selectedId));
-  }, [activeTab, selectedId, sort, tabAssets, visibleRange]);
+  }, [assetKind, selectedId, sort, tabAssets, visibleRange]);
   const targets = useMemo(() => quoteTargets(streamedAssets, selectedId), [selectedId, streamedAssets]);
   const { entries, freshnessNow } = useLiveQuoteEntries(targets, {
     freshnessScopeKey: `crypto-board:${activeTab}`,
@@ -221,20 +239,20 @@ export function CryptoBoardPane({ width, height, focused }: PaneProps) {
   const supplyRows = useMemo(() => (stablecoins ? supplyByCode(supply) : null), [stablecoins, supply]);
   const rows = useMemo(
     () => {
-      const built = buildCryptoRows(tabAssets, activeTab, entries, freshnessNow);
+      const built = buildCryptoRows(tabAssets, assetKind, entries, freshnessNow);
       return sortCryptoRows(supplyRows ? withCryptoSupply(built, supplyRows) : built, sort);
     },
-    [activeTab, entries, freshnessNow, sort, supplyRows, tabAssets],
+    [assetKind, entries, freshnessNow, sort, supplyRows, tabAssets],
   );
   const streamedIds = useMemo(() => new Set(streamedAssets.map((asset) => asset.symbol)), [streamedAssets]);
   const allStreamedLive = liveStreaming && streamedIds.size > 0
     && rows.every((row) => !streamedIds.has(row.id) || row.live);
   const boardRefreshMs = allStreamedLive ? CRYPTO_BOARD_STREAMING_REFRESH_MS : CRYPTO_BOARD_REFRESH_MS;
   useEffect(() => {
-    if (!paneVisible) return;
+    if (!paneVisible || defi) return;
     const timer = setInterval(() => void reloadBoard(false), boardRefreshMs);
     return () => clearInterval(timer);
-  }, [boardRefreshMs, paneVisible, reloadBoard]);
+  }, [boardRefreshMs, defi, paneVisible, reloadBoard]);
   useEffect(() => {
     if (!rows.length) return;
     if (!selectedId || !rows.some((row) => row.id === selectedId)) setSelectedId(rows[0]!.id);
@@ -254,7 +272,7 @@ export function CryptoBoardPane({ width, height, focused }: PaneProps) {
     : null, [now, observations]);
   // Supply columns join only once there is supply to show; an outage leaves the price columns as they are.
   const hasSupply = !!supplyRows && supplyRows.size > 0;
-  const columns = useMemo(() => buildCryptoColumns(width, activeTab, hasSupply), [activeTab, hasSupply, width]);
+  const columns = useMemo(() => buildCryptoColumns(width, assetKind, hasSupply), [assetKind, hasSupply, width]);
 
   // Other is muted against the theme it is drawn on; the coins take the shared series palette, which the chart themes.
   const otherColor = useThemeColors().textMuted;
@@ -282,7 +300,7 @@ export function CryptoBoardPane({ width, height, focused }: PaneProps) {
     value: tab.value,
   }));
   const selectTab = (value: string) => {
-    setActiveTab(value as CryptoAssetKind);
+    setActiveTab(value as CryptoTab);
     setSelectedId(null);
     setVisibleRange(INITIAL_STREAM_RANGE);
   };
@@ -291,7 +309,10 @@ export function CryptoBoardPane({ width, height, focused }: PaneProps) {
   usePaneNoticeFooter({
     registrationId: "crypto-board:notices",
     focused,
-    notices: [
+    notices: defi ? [
+      ...(defiPayload?.warnings ?? []),
+      ...(defiResource.data?.refreshError ? [defiFailure(defiResource.data.refreshError)] : []),
+    ] : [
       ...(data?.warnings ?? []),
       ...(resource.data?.refreshError ? [resource.data.refreshError] : []),
       ...(stablecoins ? [
@@ -302,16 +323,22 @@ export function CryptoBoardPane({ width, height, focused }: PaneProps) {
     ],
   });
   usePaneFooter("crypto-board", () => ({
-    info: [
+    info: defi ? [
+      ...(defiResource.loading && !defiPayload ? [{ id: "loading", parts: [{ text: "loading", tone: "muted" as const }] }] : []),
+      ...(defiPayload && defiResource.error ? [{ id: "refresh", parts: [{ text: "refresh failed", tone: "warning" as const }] }] : []),
+      ...(defiResource.data?.stale ? [{ id: "cached", parts: [{ text: "cached", tone: "warning" as const }] }] : []),
+    ] : [
       // Background refreshes run every 15s; only the first load is worth a label.
       ...(resource.loading && !data ? [{ id: "loading", parts: [{ text: "loading", tone: "muted" as const }] }] : []),
       ...(data && resource.error ? [{ id: "refresh", parts: [{ text: "refresh failed", tone: "warning" as const }] }] : []),
       ...(statusLine ? [{ id: "updated", asOf: true, parts: [{ text: statusLine, tone: "muted" as const }] }] : []),
       ...(resource.data?.stale ? [{ id: "cached", parts: [{ text: "cached", tone: "warning" as const }] }] : []),
     ],
-  }), [data, statusLine, resource.data?.stale, resource.error, resource.loading]);
+  }), [data, defi, defiPayload, defiResource.data?.stale, defiResource.error, defiResource.loading, statusLine, resource.data?.stale, resource.error, resource.loading]);
 
   const reloadSupply = supplyResource.reload;
+  const logos = useUiCapabilities().nativePaneChrome === true;
+  const renderCell = useCallback((row: CryptoRow, column: CryptoColumn) => renderCryptoCell(row, column, logos), [logos]);
   const handleKeyDown = useCallback((event: DataTableKeyEvent) => (
     handleRefreshKey(event, () => {
       void resource.reload();
@@ -321,10 +348,17 @@ export function CryptoBoardPane({ width, height, focused }: PaneProps) {
 
   const bodyHeight = Math.max(1, height - (tabStrip ? 1 : 0));
 
+  const defiState = useMemo(() => ({
+    payload: defiPayload,
+    loading: defiResource.loading,
+    error: defiResource.error,
+    reload: defiResource.reload,
+  }), [defiPayload, defiResource.error, defiResource.loading, defiResource.reload]);
+
   return (
     <Box width={width} height={height} flexDirection="column">
       {tabStrip && <Box height={1} paddingX={1}>{tabStrip}</Box>}
-      <PaneStatusBody
+      {defi ? <DefiTvlView width={width} height={bodyHeight} focused={focused} resource={defiState} /> : <PaneStatusBody
         loading={resource.loading && !data}
         error={!data ? resource.error : null}
         subject="crypto prices"
@@ -357,7 +391,7 @@ export function CryptoBoardPane({ width, height, focused }: PaneProps) {
           })}
           visibleRangeKey={`${activeTab}:${sort.columnId}:${sort.direction}`}
           onVisibleRangeChange={setVisibleRange}
-          renderCell={renderCryptoCell}
+          renderCell={renderCell}
           selectedTextOverridesCellColor
           emptyStateTitle="No crypto assets returned."
           rootBefore={stablecoins ? (
@@ -379,7 +413,7 @@ export function CryptoBoardPane({ width, height, focused }: PaneProps) {
             />
           ) : undefined}
         />
-      </PaneStatusBody>
+      </PaneStatusBody>}
     </Box>
   );
 }

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

@@ -1,6 +1,6 @@
 import type { SeriesDefinition, SeriesPoint } from "../../../series/types";
 import { cachedSeriesWarning } from "../shared/series-warning";
-import { loadStablecoinSupply, loadStablecoinSupplyHistory } from "./client";
+import { loadDefiTvl, loadStablecoinSupply, loadStablecoinSupplyHistory } from "./client";
 
 const DAY_MS = 86_400_000;
 
@@ -50,6 +50,23 @@ const STABLECOIN_SUPPLY_SERIES: readonly SeriesDefinition[] = [
   },
 ];
 
+/** Total value locked in DeFi, as CRYP's DeFi tab charts it. */
+const DEFI_TVL_SERIES: SeriesDefinition = {
+  id: "crypto:defi-tvl",
+  name: "Total DeFi TVL",
+  unit: "USD",
+  frequency: "daily",
+  group: "Crypto",
+  tags: ["defi", "tvl", "total value locked", "on-chain", "protocols", "chains"],
+  description: "Total value locked in DeFi protocols across every chain, valued in USD, daily since 2018, as DefiLlama measures it and CRYP's DeFi tab charts it.",
+  load: async () => {
+    const resource = await loadDefiTvl();
+    const history = resource.payload.history;
+    if (!history) throw new Error("DeFi TVL is not available yet.");
+    return { points: dailyPoints(history.start, history.total), warning: cachedSeriesWarning(resource) };
+  },
+};
+
 const PAIRS: ReadonlyArray<{ symbol: string; name: string }> = [
   { symbol: "BTC-USD", name: "Bitcoin" },
   { symbol: "ETH-USD", name: "Ethereum" },
@@ -96,4 +113,5 @@ export const CRYPTO_SERIES: readonly SeriesDefinition[] = [
     expression: "{ticker}:price",
   },
   ...STABLECOIN_SUPPLY_SERIES,
+  DEFI_TVL_SERIES,
 ];

package/src/plugins/builtin/crypto-etf-flows/client.ts

@@ -0,0 +1,60 @@
+import { apiClient } from "../../../api-client";
+import type { CryptoEtfFlowAsset, CryptoEtfFlowsPayload } from "../../../api-client/crypto-etf-flows";
+import { createPluginCache } from "../../../data/plugin-cache";
+import { cachedCloudResource, loadCloudResource, unavailableOnServer } from "../shared/cloud-resource";
+
+export const cryptoEtfFlowsCache = createPluginCache<CryptoEtfFlowsPayload>({
+  kind: "crypto-etf-flows", source: "gloom-cloud", schemaVersion: 1,
+  // Flows post once a trading day, in the US evening and the next morning in Europe.
+  policy: { staleMs: 15 * 60_000, expireMs: 7 * 24 * 60 * 60_000 },
+});
+
+const date = (value: unknown): value is string => typeof value === "string" && /^\d{4}-\d{2}-\d{2}$/.test(value)
+  && new Date(`${value}T00:00:00Z`).toISOString().slice(0, 10) === value;
+const flow = (value: unknown) => value === null || (typeof value === "number" && Number.isFinite(value));
+const text = (value: unknown): value is string => typeof value === "string" && value.trim().length > 0;
+const textOrNull = (value: unknown) => value === null || text(value);
+
+/**
+ * The flows as served, or an error: the asset asked for, its funds once each,
+ * every day newest first with a figure or none for each fund, and where they
+ * are from. A payload that breaks any of it is not drawn.
+ */
+export function validateCryptoEtfFlows(payload: CryptoEtfFlowsPayload, asset: CryptoEtfFlowAsset): CryptoEtfFlowsPayload {
+  const invalid = (): never => { throw new Error("The server returned invalid crypto ETF flows"); };
+  if (!payload || payload.asset !== asset || payload.unit !== "USD millions" || !Array.isArray(payload.funds)
+    || !Array.isArray(payload.days) || !date(payload.asOf) || !text(payload.fetchedAt) || !Number.isFinite(Date.parse(payload.fetchedAt))
+    || typeof payload.stale !== "boolean" || !payload.source || !text(payload.source.publisher) || !text(payload.source.url)) return invalid();
+  const tickers = payload.funds.map((fund) => fund?.ticker);
+  if (!tickers.length || tickers.some((ticker) => !text(ticker)) || new Set(tickers).size !== tickers.length
+    || payload.funds.some((fund) => !textOrNull(fund.name) || !textOrNull(fund.issuer))) return invalid();
+  const known = new Set(tickers);
+  for (const [index, day] of payload.days.entries()) {
+    if (!day || !date(day.date) || (index > 0 && day.date >= payload.days[index - 1]!.date) || !flow(day.total)
+      || !day.flows || typeof day.flows !== "object" || Object.entries(day.flows).some(([ticker, value]) => !known.has(ticker) || !flow(value))
+      || !Array.isArray(day.pending) || day.pending.some((ticker) => !known.has(ticker))) return invalid();
+  }
+  if (payload.days[0] && payload.days[0].date !== payload.asOf) return invalid();
+  return payload;
+}
+
+export async function fetchCryptoEtfFlows(
+  asset: CryptoEtfFlowAsset,
+  client: Pick<typeof apiClient, "getCloudCryptoEtfFlows"> = apiClient,
+): Promise<CryptoEtfFlowsPayload> {
+  try {
+    return validateCryptoEtfFlows(await client.getCloudCryptoEtfFlows(asset), asset);
+  } catch (error) {
+    // 404 from a server without the route; 503 until the first read is stored.
+    throw unavailableOnServer(error, "Crypto ETF flows are not available yet.", [404, 503]);
+  }
+}
+
+export function cachedCryptoEtfFlows(asset: CryptoEtfFlowAsset) {
+  return cachedCloudResource(cryptoEtfFlowsCache, asset, (payload) => validateCryptoEtfFlows(payload, asset));
+}
+
+export function loadCryptoEtfFlows(asset: CryptoEtfFlowAsset, force = false) {
+  return loadCloudResource(cryptoEtfFlowsCache, asset, () => fetchCryptoEtfFlows(asset),
+    { force, validate: (payload) => validateCryptoEtfFlows(payload, asset) });
+}

package/src/plugins/builtin/crypto-etf-flows/headless.ts

@@ -0,0 +1,132 @@
+import type { CryptoEtfFlowsPayload } from "../../../api-client/crypto-etf-flows";
+import type { HeadlessPaneColumn } from "../../../types/headless";
+import type { HeadlessPaneDefinition } from "../../../types/plugin";
+import { REPORT_ROWS } from "../shared/headless-options";
+import { fetchCryptoEtfFlows } from "./client";
+import {
+  cryptoEtfFlowAsset,
+  cryptoEtfFlowAssetLabel,
+  cryptoEtfFlowSummary,
+  formatFlow,
+  formatFlowAmount,
+  pendingText,
+} from "./model";
+
+const flowCell = (value: unknown) => formatFlow(typeof value === "number" ? value : null);
+
+/** Date, the day's total and each fund, in US$ millions as published. */
+function flowColumns(payload: CryptoEtfFlowsPayload): HeadlessPaneColumn[] {
+  return [
+    { key: "date", header: "Date", shrink: false },
+    { key: "total", header: "Total", align: "right", format: flowCell },
+    // A fund the day still waits on reads "pending", as in the pane; none at all is a dash.
+    ...payload.funds.map((fund): HeadlessPaneColumn => ({
+      key: fund.ticker, header: fund.ticker, literalHeader: true, align: "right",
+      format: (value, row) => value == null && Array.isArray(row.pending) && row.pending.includes(fund.ticker) ? "pending" : flowCell(value),
+    })),
+    { key: "pending", header: "Pending", format: (value) => Array.isArray(value) && value.length ? value.join(", ") : "" },
+  ];
+}
+
+/** "Net flows of the US spot bitcoin ETFs in US$ millions. 2026-10-20: -$6.70M (IBIT pending); 5 days ..., since 2024-01-11 +$57.47B." */
+function summaryLine(payload: CryptoEtfFlowsPayload): string {
+  const summary = cryptoEtfFlowSummary(payload);
+  const pending = pendingText(summary.latest);
+  return [
+    `Net flows of the US spot ${cryptoEtfFlowAssetLabel(payload.asset).toLowerCase()} ETFs in US$ millions.`,
+    `${summary.latest?.date ?? payload.asOf}: ${formatFlowAmount(summary.latest?.total)}${pending ? ` (${pending})` : ""};`,
+    [
+      summary.week != null ? `5 days ${formatFlowAmount(summary.week)}` : null,
+      summary.month != null ? `20 days ${formatFlowAmount(summary.month)}` : null,
+      summary.firstDate ? `since ${summary.firstDate} ${formatFlowAmount(summary.sinceLaunch)}` : null,
+    ].filter(Boolean).join(", ") + ".",
+  ].join(" ");
+}
+
+export const cryptoEtfFlowsHeadless: HeadlessPaneDefinition<"rows"> = {
+  shape: "rows",
+  argument: { kind: "none" },
+  options: [
+    {
+      key: "asset",
+      description: "The spot bitcoin or ether ETFs.",
+      type: "enum",
+      values: [
+        { value: "btc", aliases: ["bitcoin", "xbt"] },
+        { value: "eth", aliases: ["ether", "ethereum"] },
+      ],
+      defaultValue: "btc",
+      example: "--asset eth",
+      settingKey: "asset",
+    },
+    {
+      key: "limit",
+      shot: REPORT_ROWS,
+      aliases: ["count", "rows", "days"],
+      description: "Most recent trading days listed.",
+      type: "integer",
+      defaultValue: 20,
+      minimum: 1,
+      maximum: 2000,
+    },
+  ],
+  columns: [
+    { key: "date", header: "Date" },
+    { key: "total", header: "Total", align: "right", format: flowCell },
+  ],
+  describe: (args) => `Crypto ETF Flows | ${cryptoEtfFlowAssetLabel(cryptoEtfFlowAsset(args.options.asset))}`,
+  discovery: {
+    aliases: ["ETFF"],
+    dataRequirements: ["Gloom Cloud spot crypto ETF flows"],
+    limitations: [
+      "US spot bitcoin and ether ETFs only, net creations and redemptions in US$ millions as Farside Investors publishes them.",
+      "The newest day fills in fund by fund; a fund that has not reported shows as pending.",
+    ],
+  },
+  freshness: { source: "Farside Investors", publisher: "Farside Investors", status: "not-a-feed", basis: "daily fund flows", cadence: "daily", tradingDayMarket: "US" },
+  async load(args, ctx) {
+    const asset = cryptoEtfFlowAsset(args.options.asset);
+    const payload = await fetchCryptoEtfFlows(asset, ctx.apiClient);
+    const limit = Math.max(1, Number(args.options.limit) || 20);
+    const rows = payload.days.slice(0, limit).map((day) => ({
+      date: day.date,
+      total: day.total,
+      ...Object.fromEntries(payload.funds.map((fund) => [fund.ticker, day.flows[fund.ticker] ?? null])),
+      pending: day.pending,
+    }));
+    const summary = cryptoEtfFlowSummary(payload);
+    return {
+      rows,
+      columns: flowColumns(payload),
+      notes: [summaryLine(payload), `Source: ${payload.source.publisher}, ${payload.source.url}`],
+      complete: !payload.stale,
+      ...(payload.stale ? { warnings: [`The flows were last read ${payload.fetchedAt.slice(0, 10)}; newer days may be missing.`] } : {}),
+      freshness: {
+        source: payload.source.publisher,
+        publisher: payload.source.publisher,
+        status: "not-a-feed",
+        basis: "daily fund flows",
+        cadence: "daily",
+        tradingDayMarket: "US",
+        asOf: payload.asOf,
+        oldest: null,
+      },
+      metadata: {
+        asset,
+        unit: payload.unit,
+        asOf: payload.asOf,
+        fetchedAt: payload.fetchedAt,
+        stale: payload.stale,
+        source: payload.source,
+        funds: payload.funds,
+        summary: {
+          latest: summary.latest ? { date: summary.latest.date, total: summary.latest.total, pending: summary.latest.pending } : null,
+          fiveDays: summary.week,
+          twentyDays: summary.month,
+          sinceLaunch: summary.sinceLaunch,
+          firstDate: summary.firstDate,
+        },
+      },
+    };
+  },
+};

package/src/plugins/builtin/crypto-etf-flows/index.tsx

@@ -0,0 +1,44 @@
+import type { PluginModule } from "../plugin-module";
+import { cryptoEtfFlowsCache } from "./client";
+import { cryptoEtfFlowsHeadless } from "./headless";
+import { CRYPTO_ETF_FLOWS_PANE_ID } from "./model";
+import { CryptoEtfFlowsPane } from "./pane";
+
+/** ETFF: the daily net flows of the US spot bitcoin and ether ETFs, per fund. */
+export const cryptoEtfFlowsModule: PluginModule = {
+  panes: [
+    {
+      id: CRYPTO_ETF_FLOWS_PANE_ID,
+      name: "Crypto ETF Flows",
+      icon: "F",
+      component: CryptoEtfFlowsPane,
+      defaultPosition: "right",
+      defaultMode: "floating",
+      defaultFloatingSize: { width: 120, height: 32 },
+      tableExport: true,
+      headless: cryptoEtfFlowsHeadless,
+    },
+  ],
+  paneTemplates: [
+    {
+      id: "crypto-etf-flows-pane",
+      paneId: CRYPTO_ETF_FLOWS_PANE_ID,
+      label: "Crypto ETF Flows",
+      description: "Daily net flows of the US spot bitcoin and ether ETFs, per fund in US$ millions, with the running total since launch, as Farside Investors publishes them.",
+      keywords: [
+        "etf flows", "bitcoin flows", "btc flows", "ether flows", "eth flows", "ethereum flows", "crypto flows",
+        "bitcoin etf flows", "ether etf flows", "spot bitcoin etf", "spot ether etf", "spot etf flows",
+        "flows", "inflows", "outflows", "net flows", "creations", "redemptions",
+        "ibit", "fbtc", "gbtc", "etha", "farside",
+      ],
+      shortcut: { prefix: "ETFF" },
+      headless: cryptoEtfFlowsHeadless,
+    },
+  ],
+  setup(ctx) {
+    cryptoEtfFlowsCache.attach(ctx.persistence);
+  },
+  dispose() {
+    cryptoEtfFlowsCache.reset();
+  },
+};

package/src/plugins/builtin/crypto-etf-flows/model.ts

@@ -0,0 +1,121 @@
+import type { CryptoEtfFlowAsset, CryptoEtfFlowDay, CryptoEtfFlowsPayload } from "../../../api-client/crypto-etf-flows";
+import type { DataTableColumn } from "../../../components";
+import { calendarMonthsBefore } from "../../../utils/calendar-date";
+import { formatCompactAmount, formatNumber } from "../../../utils/format";
+
+export const CRYPTO_ETF_FLOWS_PANE_ID = "crypto-etf-flows";
+
+export const CRYPTO_ETF_FLOW_ASSETS: ReadonlyArray<{ value: CryptoEtfFlowAsset; label: string }> = [
+  { value: "BTC", label: "Bitcoin" },
+  { value: "ETH", label: "Ether" },
+];
+
+export type CryptoEtfFlowRange = "1M" | "3M" | "1Y" | "ALL";
+
+/** The range the chart and the table show; the figures always read the whole history. */
+export const CRYPTO_ETF_FLOW_RANGES: ReadonlyArray<{ value: CryptoEtfFlowRange; label: string; hint: string }> = [
+  { value: "1M", label: "1M", hint: "1" },
+  { value: "3M", label: "3M", hint: "2" },
+  { value: "1Y", label: "1Y", hint: "3" },
+  { value: "ALL", label: "All", hint: "4" },
+];
+
+export function cryptoEtfFlowRange(value: unknown): CryptoEtfFlowRange {
+  return CRYPTO_ETF_FLOW_RANGES.find((range) => range.value === value)?.value ?? "1Y";
+}
+
+const RANGE_MONTHS: Record<Exclude<CryptoEtfFlowRange, "ALL">, number> = { "1M": 1, "3M": 3, "1Y": 12 };
+
+/** The days within a range of the newest one listed, newest first. */
+export function daysInRange(days: readonly CryptoEtfFlowDay[], range: CryptoEtfFlowRange): CryptoEtfFlowDay[] {
+  const newest = days[0]?.date;
+  if (!newest || range === "ALL") return [...days];
+  const start = calendarMonthsBefore(new Date(`${newest}T00:00:00Z`), RANGE_MONTHS[range]);
+  const from = start.toISOString().slice(0, 10);
+  return days.filter((day) => day.date > from);
+}
+
+/** `btc`, `bitcoin`, `ETH`, `ether`, `ethereum`: the asset a setting or option names; bitcoin otherwise. */
+export function cryptoEtfFlowAsset(value: unknown): CryptoEtfFlowAsset {
+  const text = typeof value === "string" ? value.trim().toUpperCase() : "";
+  return text === "ETH" || text === "ETHER" || text === "ETHEREUM" ? "ETH" : "BTC";
+}
+
+export const cryptoEtfFlowAssetLabel = (asset: CryptoEtfFlowAsset) => asset === "ETH" ? "Ether" : "Bitcoin";
+
+/** A day's flow in US$ millions as the table shows it: `+665.2`, `-83.6`, `0.0`, `—` for none. */
+export function formatFlow(value: number | null | undefined): string {
+  if (value == null || !Number.isFinite(value)) return "—";
+  const text = formatNumber(Math.abs(value), 1);
+  return value > 0 && text !== "0.0" ? `+${text}` : value < 0 && text !== "0.0" ? `-${text}` : text;
+}
+
+/** A sum of flows in US$ millions as a figure reads it: `+$526.7M`, `-$1.13B`, `$0`. */
+export function formatFlowAmount(millions: number | null | undefined): string {
+  if (millions == null || !Number.isFinite(millions)) return "—";
+  const text = formatCompactAmount(millions * 1_000_000, { signed: true });
+  return text.replace(/^([+-]?)/, "$1$");
+}
+
+/** Inflows green, outflows red; a day with no flow recedes, so the funds that moved stand out in a wide table. */
+export const flowColor = (value: number | null | undefined, colors: { positive: string; negative: string; textMuted: string }) =>
+  value == null || value === 0 ? colors.textMuted : value > 0 ? colors.positive : colors.negative;
+
+export interface CryptoEtfFlowSummary {
+  latest: CryptoEtfFlowDay | null;
+  /** Sums of the published daily totals over the newest days listed. */
+  week: number | null;
+  month: number | null;
+  /** Every listed day's total: the net flow since the first fund launched. */
+  sinceLaunch: number | null;
+  firstDate: string | null;
+}
+
+const sumTotals = (days: readonly CryptoEtfFlowDay[]) => days.some((day) => day.total != null)
+  ? days.reduce((sum, day) => sum + (day.total ?? 0), 0)
+  : null;
+
+/** The figures over the table: the newest day, the last 5 and 20 trading days, and since launch. */
+export function cryptoEtfFlowSummary(payload: CryptoEtfFlowsPayload): CryptoEtfFlowSummary {
+  const days = payload.days;
+  return {
+    latest: days[0] ?? null,
+    week: days.length >= 5 ? sumTotals(days.slice(0, 5)) : null,
+    month: days.length >= 20 ? sumTotals(days.slice(0, 20)) : null,
+    sinceLaunch: sumTotals(days),
+    firstDate: days.at(-1)?.date ?? null,
+  };
+}
+
+/** The running sum of the daily totals, oldest first: what the chart draws. */
+export function cumulativeFlows(payload: CryptoEtfFlowsPayload): Array<{ date: string; value: number }> {
+  let running = 0;
+  return payload.days.toReversed().map((day) => {
+    running += day.total ?? 0;
+    return { date: day.date, value: running };
+  });
+}
+
+/** "IBIT pending" or "IBIT, ETHB pending": the funds a day still waits on. */
+export function pendingText(day: CryptoEtfFlowDay | null | undefined): string | null {
+  return day?.pending.length ? `${day.pending.join(", ")} pending` : null;
+}
+
+export type CryptoEtfFlowColumn = Omit<DataTableColumn, "id"> & { id: string };
+
+/** Date and the day's total, then each fund in the publisher's order. */
+export function cryptoEtfFlowColumns(payload: CryptoEtfFlowsPayload | null | undefined): CryptoEtfFlowColumn[] {
+  return [
+    { id: "date", label: "Date", width: 12, align: "left" },
+    { id: "total", label: "Total", width: 9, align: "right", title: "The day's net flow across the funds, US$ millions" },
+    ...(payload?.funds ?? []).map((fund): CryptoEtfFlowColumn => ({
+      id: `fund:${fund.ticker}`,
+      label: fund.ticker,
+      width: Math.max(8, fund.ticker.length + 2),
+      align: "right",
+      ...(fund.name ? { title: fund.issuer ? `${fund.name} (${fund.issuer})` : fund.name } : {}),
+    })),
+  ];
+}
+
+export const fundTickerOfColumn = (columnId: string) => columnId.startsWith("fund:") ? columnId.slice(5) : null;