gloomberb 0.16.6 → 0.17.1

package/src/cli/commands/market.ts

@@ -16,7 +16,7 @@ import {
   getExtendedSessionDisplay,
   getQuoteSessionFields,
   getRegularSessionDisplay,
-  marketStateLabel,
+  quoteSessionLabel,
   type ExtendedSession,
 } from "../../market-data/market/status";
 import { formatCompact, formatDistributionAmount, formatPercent, formatPercentRaw } from "../../utils/format";
@@ -31,6 +31,7 @@ import {
   formatPriceRange,
 } from "../helpers";
 import { cliStyles, colorBySign, renderSection, renderStats } from "../../utils/cli-output";
+import { statementHistoryNotes } from "../../utils/financial-statements";
 import { formatPerShareNumber } from "../../utils/reported-money";
 import {
   analystTargetCurrency,
@@ -48,9 +49,9 @@ import type { FuturesContractTermsPayload } from "../../api-client/futures-curve
 import { futuresSettleText, isFuturesInstrument } from "../../market-data/futures-contract";
 import {
   chainHasExpiry,
-  chainWithModelFigures,
   formatExpiryList,
   loadOptionModelInputs,
+  loadOptionsChainOpenInterest,
   formatOptionDeltaCell,
   formatOptionIvCell,
   formatOptionQuoteCell,
@@ -58,10 +59,16 @@ import {
   OPTION_MODEL_RATE,
   OPTIONS_USAGE,
   optionRows,
+  optionsBasisFields,
+  optionsBasisFootnote,
   parseOptionExpiration,
+  requestListedOpenInterest,
+  valueChainAtModelSpot,
+  type OptionsChainBasis,
 } from "./options-chain";
 import { DEFAULT_LEAPS_CRITERIA, LEAPS_USAGE, parseLeapsCriteria, runLeapsScreen, takeLeapsOptions } from "./options-leaps";
 import type { CliResultColumn } from "../result";
+import type { PriceHistoryResult } from "../../types/price-history";
 import {
   exportRowsTable,
   reportFooterLines,
@@ -70,9 +77,12 @@ import {
 } from "../report-tables";
 import {
   historyBarStatusNote,
+  historyCoverageWarning,
   historyFacts,
   historyFlagNote,
   historyGapNote,
+  historyJumpNote,
+  historyUnbrokenFrom,
   historyAllRangeYears,
   historyIntervalsByRange,
   historyNotes,
@@ -89,7 +99,9 @@ import { newsFallbackText, newsSearchHeading, newsSearchText, newsSearchTextProb
 import { formatUtcTime } from "../../utils/utc-time";
 import { isFiniteNumber } from "../../utils/guards";
 import { exportedFundamentals } from "../../utils/price-earnings";
-import { fundamentalsFreshness, fxPairFreshness, quotesFreshness, rowsFreshness } from "../freshness";
+import { fundamentalsFreshness, fxPairFreshness, quotesFreshness, rowsFreshness, valuationFreshness } from "../freshness";
+import { atRegularSessionPrice } from "../../market-data/quotes/regular-session-valuation";
+import { selectMarketCapitalization } from "../../utils/market-capitalization";
 import {
   barHistoryFreshness,
   barResolutionFromDates,
@@ -128,13 +140,15 @@ import {
 import { indexRootAlsoLine, indexRootFor, indexRootTryLine, isYieldIndexSymbol } from "../index-roots";
 import { earningsCalendarFailure, earningsChoiceNote, earningsDateLabel, isListingAbroad, noListingCalendarNote } from "../earnings-calendar";
 import { formatBasisPoints, toBasisPoints } from "../../utils/basis-points";
-import { providerMissReason } from "../../sources/provider-errors";
-import { isNotATickerMessage } from "../not-a-ticker";
+import { notATickerSymbol, providerMissReason } from "../../sources/provider-errors";
+import { isNotATickerMessage, withListingSuggestion } from "../not-a-ticker";
+import { describeSuggestion, suggestListing } from "../listing-suggestion";
 import { splitSymbolArgs } from "../symbol-args";
 import { cliPerpetualContract, perpetualContractStats, type PerpetualContractPayload } from "../perpetual-contract";
 import { subMinuteDataMessage } from "../known-gaps";
 import { secRegistrantMismatchMessage, SecRegistrantMismatchError, areDifferentCompanies } from "../../sources/sec-registrant";
 import { isCryptoPairSymbol } from "../../utils/crypto-pair";
+import { looksLikeCurrencyPair } from "../../utils/currency-pair";
 import { isUsListingExchange } from "../../utils/exchanges";
 import { describeTickerChange, startTickerChangeLookup, tickerChangeLine, type TickerChange } from "../../tickers/ticker-changes";
 import { noSecReportsNotice, nonUsSecListingVenue } from "../../utils/sec";
@@ -245,6 +259,7 @@ const QUOTE_LEAD_COLUMNS = [
   // Text drops a column no row fills, so a table without an extended print stays as narrow as before.
   extendedColumn("PRE"),
   extendedColumn("POST"),
+  extendedColumn("OVERNIGHT"),
   { key: "session", header: "Session", shrink: false },
 ];
 
@@ -261,17 +276,21 @@ function yieldChangeCell(row: QuoteRow): string {
   return row.changeBasisPoints == null ? "" : colorBySign(formatBasisPoints(row.changeBasisPoints / 100, 1), row.changeBasisPoints);
 }
 
-/** The pre-market or after-hours print and its move from the regular close, in its own column. */
+/**
+ * The pre-market, after-hours or overnight print and its move from the
+ * regular close, in its own column; "mid" when it is a bid and ask midpoint.
+ */
 function extendedColumn(session: ExtendedSession) {
+  const price = (row: QuoteRow) => row.extendedMark ? `${row.extendedPrice} mid` : row.extendedPrice;
   return {
-    key: session === "PRE" ? "preMarket" : "afterHours",
+    key: session === "PRE" ? "preMarket" : session === "POST" ? "afterHours" : "overnight",
     header: EXTENDED_SESSION_LABELS[session],
     align: "right" as const,
     value: (row: QuoteRow) => row.extendedSession === session && row.extendedPrice
-      ? [row.extendedPrice, row.extendedChangePercent == null ? "" : formatPercentRaw(row.extendedChangePercent)].join(" ").trim()
+      ? [price(row), row.extendedChangePercent == null ? "" : formatPercentRaw(row.extendedChangePercent)].join(" ").trim()
       : "",
     format: (value: unknown, row: QuoteRow) => (
-      value ? [row.extendedPrice, formatChangePercentCell(row.extendedChangePercent)].join(" ").trim() : ""
+      value ? [price(row), formatChangePercentCell(row.extendedChangePercent)].join(" ").trim() : ""
     ),
   };
 }
@@ -361,7 +380,9 @@ function quoteRows(results: QuoteCliRecord[], now = Date.now()) {
       rawExtendedPrice: extended?.price ?? null,
       extendedChange: extended?.change ?? null,
       extendedChangePercent: roundedPercent(extended?.changePercent),
-      session: quote?.marketState ? marketStateLabel(quote.marketState) : "",
+      // The extended price is the session's bid and ask midpoint, nothing having traded in it.
+      extendedMark: extended?.mark === true,
+      session: quoteSessionLabel(quote) ?? "",
       // The close the shown move is measured from: the one before the session Last is.
       previousClose: price(display?.change != null ? display.price - display.change : quote?.previousClose),
       dayRange: quote?.low != null && quote.high != null
@@ -696,7 +717,7 @@ async function answerQuote(
     root ? indexRootTryLine(root, request.command) : null,
     other || listing.exchange ? null : futuresTryLine(listing.symbol, request),
   ].filter((line): line is string => !!line);
-  if (!other && tryLines.length === 0) return { result, listing, notes: [] };
+  if (!other && tryLines.length === 0) return { result: await withCurrencyPairHint(result, market), listing, notes: [] };
   const message = other?.message ?? `${listing.symbol} has no ${request.noun}.`;
   const details = [other?.details, ...tryLines].filter(Boolean).join("\n");
   const oneLine = [
@@ -707,6 +728,21 @@ async function answerQuote(
   return { result, listing, failure: { message, details, oneLine }, notes: [] };
 }
 
+/**
+ * A symbol written like a currency pair that is not a ticker (USD_NGN, as some
+ * FX feeds write a pair) names the listing `gloomberb search` finds nearest to
+ * it, as `watchlist add` does: "Did you mean USDNGN=X (US Dollar/Nigerian
+ * Naira)?". When search finds nothing near, the row keeps its own error and its
+ * search hint.
+ */
+async function withCurrencyPairHint(result: QuoteBatchResult, market: MarketContext): Promise<QuoteBatchResult> {
+  const message = errorMessage(result.error);
+  const symbol = message ? notATickerSymbol(message) : null;
+  if (!message || !symbol || !looksLikeCurrencyPair(symbol)) return result;
+  const suggestion = await suggestListing(symbol, market);
+  return suggestion ? { ...result, error: withListingSuggestion(message, describeSuggestion(suggestion)) } : result;
+}
+
 /** A crypto pair that will not load points at the crypto board. Structured formats keep the error as thrown. */
 function failHistory(error: unknown, symbol: string, ctx: Parameters<CliCommandDef["execute"]>[1]): never {
   if (ctx.cliOptions.format !== "text" || !isCryptoPairSymbol(symbol)) throw error;
@@ -744,16 +780,17 @@ async function runHistory(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
     const context = { cacheMode: ctx.cliOptions.refresh ? "refresh" as const : "default" as const };
     const load = () => market.dataProvider.getPriceHistoryWithMetadata
       ? market.dataProvider.getPriceHistoryWithMetadata(symbol, exchange, range, context)
-      : market.dataProvider.getPriceHistory(symbol, exchange, range, context).then((points) => ({ points, resolution: null }));
+      : market.dataProvider.getPriceHistory(symbol, exchange, range, context).then((points): PriceHistoryResult => ({ points, resolution: null }));
     const quoted = loadListingQuote(market.dataProvider, listing);
     const fate = listingFateLoader(listing, market, quoted);
-    const [{ points, resolution }, quote] = await Promise.all([
+    const [loaded, quote] = await Promise.all([
       loadForListing(listing, market, ctx, load, (loaded) => loaded.points.length === 0, {
         command: range === "1Y" ? "history" : `history --range ${range}`, noun: "history", fate,
       })
         .catch((error) => failHistory(error, listing.key, ctx)),
       quoted,
     ]);
+    const { points, resolution } = loaded;
     const identity = listingIdentity(listing, quote);
     // Without a quote currency, the listing metadata research reads (as `ticker` does) may still state it.
     const listed = quote?.currency ? quote : await market.dataProvider.getQuoteMetadata?.(symbol, exchange).catch(() => null);
@@ -783,7 +820,8 @@ async function runHistory(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
       // FB's bars are the fund listed there now; META's from 2021 are from when it was FB.
       ...listingFateNotes(await fate(), { served: data.length > 0, firstDate: data[0]?.date }),
       ...await listingChoiceNotes(listing, market, quote, venues),
-      ...historyNotes(range, interval, data[0]?.date), gaps ?? [], historyFlagNote(data) ?? [], historyBarStatusNote(data) ?? [],
+      ...historyNotes(range, interval, data[0]?.date), historyCoverageWarning(range, loaded) ?? [],
+      gaps ?? [], historyJumpNote(data) ?? [], historyFlagNote(data) ?? [], historyBarStatusNote(data) ?? [],
     ].flat();
     const priceColumns: CliResultColumn[] = [
       intraday
@@ -821,6 +859,8 @@ async function runHistory(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
         interval,
         firstDate: data[0]?.date ?? null,
         lastDate: data.at(-1)?.date ?? null,
+        // The first bar after the last gap or jump; the first bar when there is none.
+        unbrokenFrom: historyUnbrokenFrom(data) ?? data[0]?.date ?? null,
         bars: data.length,
         asOf: freshness?.asOf ?? null,
         ...(volume ? { volumeUnit: volume.unit, volumePeriod: interval === "1d" ? "UTC day" : interval } : {}),
@@ -831,16 +871,14 @@ async function runHistory(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
       heading: `${listingHeading(identity)}\n${cliStyles.muted(historyFacts(unit, data).join("  ·  "))}`,
       dateKey: "date",
       textColumns: [...priceColumns, flagTextColumn],
-      // Every exported row says its currency, what a price is in and its bar size, so it survives head and concatenation.
       columns: [
         ...priceColumns,
-        { key: "currency", header: "Currency" },
-        { key: "unit", header: "Unit" },
-        { key: "interval", header: "Interval" },
         flagColumn,
         ...marked ? [{ key: "partial", header: "Partial" }, { key: "filled", header: "Filled" }] : [],
         ...volume ? [{ key: "volumeUnit", header: "Volume unit" }, { key: "volumeNote", header: "Volume note" }] : [],
       ],
+      // Every exported row says what it is a bar of, the currency a price is in and its bar size, so it survives head and concatenation.
+      exportIdentity: { symbolOrSeries: listing.key, currencyOrUnit: unit.currency ?? unit.unit, interval },
     });
   });
 }
@@ -889,15 +927,28 @@ async function runFinancials(rawArgs: string[], ctx: Parameters<CliCommandDef["e
       ...financials,
     };
     if (view !== "statements") {
-      const freshness = fundamentalsFreshness(financials);
+      // A valuation is measured at the quote's regular session price, so the quote dates it.
+      const freshness = view === "valuation" ? valuationFreshness(financials) : fundamentalsFreshness(financials);
+      // Market cap, the multiples and the yield at the regular session price, as the text gives them; the quote stays as sent.
+      const priced = atRegularSessionPrice(financials);
+      const capitalization = selectMarketCapitalization(priced.quote, priced.fundamentals);
       ctx.printResult({
         // JSON reads a multiple over a loss as null with its reason, never as a number.
-        data: { ...data, fundamentals: exportedFundamentals(data.fundamentals) },
+        data: {
+          ...data,
+          ...view === "valuation" ? {
+            ...getQuoteSessionFields(financials.quote),
+            marketCap: capitalization?.value ?? null,
+            marketCapCurrency: capitalization?.currency ?? null,
+          } : {},
+          fundamentals: exportedFundamentals(priced.fundamentals),
+        },
         freshness,
         ...(choice.length > 0 ? { warnings: choice } : {}),
       }, {
         text: () => renderFundamentalsReport(data, view),
         ...(tabular ? { tables: selectTables(fundamentalsReportTables(data, view, freshness)) } : {}),
+        exportIdentity: { symbolOrSeries: listing.key },
       });
       return;
     }
@@ -905,11 +956,13 @@ async function runFinancials(rawArgs: string[], ctx: Parameters<CliCommandDef["e
     const freshness = rowsFreshness(rows, {
       ...REPORTED_DATA, basis: "financial statements", observedKey: "date", oldest: null,
     });
+    // The rows are the annual years served; older ones are not, and the closing lines say so.
+    const historyNotes = statementHistoryNotes("annual", rows.map((row) => row.date), listing.key);
     // NDJSON keeps the raw statement rows it always wrote; CSV gets the table and its closing lines.
     const tables = tabular
       ? selectTables({
         tables: [exportRowsTable("Annual statements", STATEMENT_COLUMNS, rows)],
-        footer: reportFooterLines({ freshness }),
+        footer: reportFooterLines({ freshness, notes: historyNotes }),
       })
       : undefined;
     ctx.printResult({
@@ -921,6 +974,7 @@ async function runFinancials(rawArgs: string[], ctx: Parameters<CliCommandDef["e
         quarterlyStatements: financials.quarterlyStatements.length,
         fundamentals: exportedFundamentals(financials.fundamentals),
         profile: financials.profile,
+        ...(historyNotes.length > 0 ? { notes: historyNotes } : {}),
       },
       freshness,
       ...(choice.length > 0 ? { warnings: choice } : {}),
@@ -928,7 +982,10 @@ async function runFinancials(rawArgs: string[], ctx: Parameters<CliCommandDef["e
       heading: listingHeading(identity),
       rows: () => rows,
       columns: STATEMENT_COLUMNS,
+      ...(historyNotes.length > 0 ? { footnote: historyNotes.join("\n"), exportNotes: historyNotes } : {}),
       ...(tables && ctx.cliOptions.format === "csv" ? { tables } : {}),
+      // Annual statements in the company's reporting currency.
+      exportIdentity: { symbolOrSeries: listing.key, currencyOrUnit: rows.find((row) => row.currency)?.currency ?? null, interval: "annual" },
     });
   });
 }
@@ -1318,6 +1375,7 @@ async function runHolders(
         tables: [exportRowsTable("Holders", columns, shownRows)],
         footer: reportFooterLines({ freshness, notes: notices }),
       },
+      exportIdentity: { symbolOrSeries: listing.key },
       summary: () => [
         [valueBasis ? `Value = ${valueBasis}.` : "", positionsBasis ?? "", shareBasisNote ?? "", unvaluedNote ?? ""].filter(Boolean).join(" "),
         insiderCommand ? insiderSummary(data, ownerTypes, listing, identity, form4) : "",
@@ -1447,6 +1505,8 @@ async function runOptions(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
     const quotePromise = loadListingQuote(market.dataProvider, listing);
     const fate = listingFateLoader(listing, market, quotePromise);
     const inputsPromise = loadOptionModelInputs(market.dataProvider, listing, quotePromise, refresh);
+    // OPX's listing dates the chain's open interest; asked for alongside the chain when the expiry is known.
+    const listedOpenInterest = expirationDate != null ? requestListedOpenInterest(symbol, expirationDate) : null;
     const { result, chain: loaded } = await loadForListing(listing, market, ctx, async () => {
       const cached = await market.dataProvider.getCachedQuery?.("getOptionsChain", [symbol, exchange, expirationDate, undefined])
         .load({ force: refresh });
@@ -1476,7 +1536,13 @@ async function runOptions(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
     }
     const quote = await quotePromise;
     const identity = listingIdentity(listing, quote);
-    const chain = chainWithModelFigures(loaded, inputs);
+    // IV and delta are valued at one spot and instant, named under the table and on every exported row.
+    const { chain, spot: modelSpot } = valueChainAtModelSpot(loaded, inputs, Date.now(), identity.exchange);
+    const basis: OptionsChainBasis = { spot: modelSpot, dividendYield: inputs.dividendYield ?? null,
+      openInterest: await loadOptionsChainOpenInterest(symbol, chain, listedOpenInterest) };
+    const basisFields = optionsBasisFields(basis);
+    const currency = [...chain.calls, ...chain.puts].find((contract) => contract.currency?.trim())?.currency.trim().toUpperCase()
+      ?? quote?.currency ?? null;
     // A failed refresh falls back to the stored chain, which can be days old.
     const refreshWarning = result?.refreshError == null ? null
       : `Options refresh failed; showing the chain stored ${new Date(result.fetchedAt).toISOString()}`
@@ -1498,23 +1564,54 @@ async function runOptions(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
       ...(chain.delayMinutes != null ? { delayMinutes: chain.delayMinutes } : {}),
       stale: refreshWarning != null,
     });
+    const contractCount = chain.calls.length + chain.puts.length;
     ctx.printResult({
       data: chain,
       metadata: {
         ...listingMetadata(identity),
         expirations: chain.expirationDates,
+        currency,
+        interval: OPTIONS_EXPORT_INTERVAL,
+        // `iv` is annualised volatility and `delta` the option's change per 1.00 move in the underlying, both decimals.
+        units: { iv: "annualized decimal", delta: "decimal per 1.00 move in the underlying" },
         // What `iv` and `delta` on each contract are valued from; the provider's own impliedVolatility is left as sent.
-        model: { spot: inputs.spot ?? null, dividendYield: inputs.dividendYield ?? null, rate: OPTION_MODEL_RATE },
+        model: {
+          spot: basisFields.spot, spotBasis: basisFields.spotBasis, spotAsOf: basisFields.spotAsOf,
+          valuationTime: modelSpot ? new Date(modelSpot.valuationTime).toISOString() : null,
+          dividendYield: inputs.dividendYield ?? null, rate: OPTION_MODEL_RATE,
+        },
+        openInterest: { asOf: basisFields.openInterestAsOf, listedAsOf: basis.openInterest?.listedDate ?? null,
+          compared: basis.openInterest?.compared ?? 0, matched: basis.openInterest?.matched ?? 0 },
       },
       ...(warnings.length > 0 ? { warnings } : {}),
       freshness,
     }, {
       heading: listingHeading(identity),
-      rows: optionRows,
+      rows: (data: OptionsChain) => optionRows(data).map((row) => ({ ...row, ...basisFields })),
       // Choosing an expiry needs the list; once one is chosen the table is that expiry.
       summary: (data: OptionsChain) => expirationDate == null ? formatExpiryList(data.expirationDates) : "",
       empty: `No option contracts for ${listingTitle(identity)}.`,
+      ...(contractCount > 0 ? { footnote: optionsBasisFootnote(basis) } : {}),
+      exportIdentity: { symbolOrSeries: listing.key, currencyOrUnit: currency, interval: OPTIONS_EXPORT_INTERVAL },
+      // Exports state each decimal's unit in its header and end every row with the spot and dates it is as of.
       columns: [
+        { key: "side", header: "Side" },
+        { key: "contract", header: "Contract" },
+        { key: "expiration", header: "Expiry" },
+        { key: "strike", header: "Strike" },
+        { key: "last", header: "Last" },
+        { key: "bid", header: "Bid" },
+        { key: "ask", header: "Ask" },
+        { key: "iv", header: "IV (annualized decimal)" },
+        { key: "delta", header: "Delta (decimal)" },
+        { key: "volume", header: "Vol" },
+        { key: "openInterest", header: "OI" },
+        { key: "spot", header: "Spot" },
+        { key: "spotBasis", header: "Spot basis" },
+        { key: "spotAsOf", header: "Spot as of" },
+        { key: "openInterestAsOf", header: "OI as of" },
+      ],
+      textColumns: [
         { key: "side", header: "Side" },
         { key: "contract", header: "Contract", shrink: false },
         // The contract symbol already carries the date, so this goes first when the table is narrow.
@@ -1532,6 +1629,9 @@ async function runOptions(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
   });
 }
 
+/** What an options chain export's `interval` says: one quote snapshot, not bars. */
+const OPTIONS_EXPORT_INTERVAL = "snapshot";
+
 const FX_USAGE = "fx <currency> | fx <base>/<quote>";
 
 async function runFx(rawArgs: string[], ctx: Parameters<CliCommandDef["execute"]>[1]) {
@@ -1577,6 +1677,8 @@ async function runFx(rawArgs: string[], ctx: Parameters<CliCommandDef["execute"]
     })));
     ctx.printResult({ data: [row], freshness }, {
       text: () => describeFxRate(request, rate),
+      // The rate is the base currency's price of one unit of the other, at the latest quote of each leg.
+      exportIdentity: { symbolOrSeries: pair, currencyOrUnit: baseCurrency, interval: "spot" },
       columns: [
         { key: "currency", header: "Currency" },
         { key: "baseCurrency", header: "Base" },
@@ -1689,7 +1791,14 @@ export const marketDataCliCommands: BuiltinCliCommandDef[] = [
         title: "Bars",
         lines: [
           `Each range comes in one bar size: ${historyIntervalsByRange()}. The line under the heading, and the --json metadata, give the currency, the bar size actually served, the first and last bar and the bar count. A warning says when the bars are coarser, or start later, than the range asked for, and for a coin, which trades every day, names each day it has no bar for.`,
-          "A bar whose prices contradict each other (high below the open or close, or low above them) is left blank and flagged, such as high<open, with the count in a warning. Every exported row (--csv, --ndjson, --json) carries currency, interval and flag.",
+          "A bar whose prices contradict each other (high below the open or close, or low above them) is left blank and flagged, such as high<open, with the count in a warning. Every --csv and --ndjson row carries its flag and ends with symbol_or_series, currency_or_unit, interval, source and as_of; --json rows carry currency, unit, interval and flag.",
+          "A break in the series flags the bar after it, which keeps its prices: gap after more than three months with no bar (weeks for weekly, daily and intraday bars), jump when the close is over 100 times the one before or under a hundredth of it. A warning names each break, and the heading says the date the series runs unbroken from.",
+        ],
+      }, {
+        title: "Long history",
+        lines: [
+          "ZAR has daily FRED data from 1980: gloomberb fred DEXSFUS --start 1980 --sort asc --csv",
+          "NGN, SAR and ILS have no FRED series. Their daily bars cover the last five years (gloomberb fn G USDNGN=X --rangePreset 5Y --chartResolution 1d --csv); before that there are monthly bars only (gloomberb history USDNGN=X --range ALL).",
         ],
       }],
       examples: ["history AAPL", "history BHP:ASX --range 5Y", "history ZAR=X --range ALL", "history ZAR=X --tail 5", "history AAPL --range 5Y --csv > aapl.csv"],

package/src/cli/commands/options-chain.ts

@@ -5,6 +5,12 @@ import { cliStyles, cliTerminalWidth, wrapText } from "../../utils/cli-output";
 import { isFiniteNumber } from "../../utils/guards";
 import { calculateOptionGreeks, solveChainVolatilities } from "../../plugins/builtin/options/analytics";
 import { optionQuoteSide } from "../../plugins/builtin/options/market-reference";
+import {
+  formatModelSpotPrice, modelSpotLabel, optionModelSpot, type OptionModelSpot,
+} from "../../plugins/builtin/options/model-spot";
+import {
+  chainOpenInterestAsOf, loadListedOpenInterest, openInterestAsOfLabel, type OpenInterestAsOf,
+} from "../../plugins/builtin/options/open-interest-as-of";
 import { DEFAULT_OPTION_CALC_DRAFT } from "../../plugins/builtin/options-calculator/model";
 import { expiryIsoDate, missingExpiryText, parseOptionExpiration } from "../../utils/option-expiry";
 
@@ -61,6 +67,8 @@ export function formatExpiryList(expirations: readonly number[], width = cliTerm
 export interface OptionModelInputs {
   /** The underlying's current price; absent when the quote is missing or stale. */
   spot?: number;
+  /** The quote `spot` is read from, for the spot the chain is valued at (`optionModelSpot`). */
+  quote?: Quote;
   dividendYield?: number;
   now?: number;
 }
@@ -119,7 +127,7 @@ export async function loadOptionModelInputs(
     .find((candidate) => candidate && candidate.stale !== true && isFiniteNumber(candidate.price) && candidate.price > 0);
   const dividendYield = financials?.fundamentals?.dividendYield;
   return {
-    ...(current ? { spot: current.price } : {}),
+    ...(current ? { spot: current.price, quote: current } : {}),
     ...(isFiniteNumber(dividendYield) && dividendYield >= 0 ? { dividendYield } : {}),
   };
 }
@@ -131,6 +139,72 @@ export function chainWithModelFigures(chain: OptionsChain, inputs: OptionModelIn
   return { ...chain, calls: chain.calls.map(add), puts: chain.puts.map(add) };
 }
 
+/**
+ * What a chain's IV, delta and open interest are as of: the spot and instant
+ * they are valued at, and the session the open interest counts. The rows and
+ * the closing lines of every format say it.
+ */
+export interface OptionsChainBasis {
+  spot: OptionModelSpot | null;
+  dividendYield: number | null;
+  openInterest: OpenInterestAsOf | null;
+}
+
+/** The chain with `iv` and `delta` valued at the spot `optionModelSpot` picks for it, and that spot. */
+export function valueChainAtModelSpot(
+  chain: OptionsChain, inputs: OptionModelInputs, now: number, exchange?: string,
+): { chain: OptionsChain; spot: OptionModelSpot | null } {
+  const spot = optionModelSpot(inputs.quote, chain, now, exchange);
+  return {
+    chain: chainWithModelFigures(chain, spot ? { spot: spot.price, dividendYield: inputs.dividendYield, now: spot.valuationTime } : inputs),
+    spot,
+  };
+}
+
+/** The open-interest date of the chain's expiry, from OPX's listing of it; null when the listing cannot be read. */
+export async function loadOptionsChainOpenInterest(
+  symbol: string, chain: OptionsChain, listed?: ReturnType<typeof loadListedOpenInterest> | null,
+): Promise<OpenInterestAsOf | null> {
+  const expiration = [...chain.calls, ...chain.puts][0]?.expiration;
+  if (expiration == null) return null;
+  const payload = await (listed ?? loadListedOpenInterest(symbol, expiryIsoDate(expiration)));
+  return payload ? chainOpenInterestAsOf(chain, payload) : null;
+}
+
+/** OPX's listing of an expiry, requested while the chain loads. */
+export function requestListedOpenInterest(symbol: string, expiration: number) {
+  return loadListedOpenInterest(symbol, expiryIsoDate(expiration));
+}
+
+/**
+ * The line under the chain: `Greeks at spot 89.79 (close Mon 12 Oct 20:00 UTC), dividend yield 2.34%, rate 4% · OI as of Fri 9 Oct`.
+ * An open interest whose date cannot be established says why.
+ */
+export function optionsBasisFootnote(basis: OptionsChainBasis): string {
+  const parts: string[] = [];
+  if (basis.spot) {
+    parts.push(`Greeks at spot ${formatModelSpotPrice(basis.spot.price)} (${modelSpotLabel(basis.spot)}), `
+      + `dividend yield ${basis.dividendYield == null ? "0%" : `${Number((basis.dividendYield * 100).toFixed(2))}%`}, `
+      + `rate ${Number((OPTION_MODEL_RATE * 100).toFixed(2))}%`);
+  }
+  const oi = basis.openInterest;
+  parts.push(oi?.date ? openInterestAsOfLabel(oi)
+    : oi?.listedDate && oi.compared > 0
+      ? `OI date not published: the counts differ from OPX's ${oi.listedDate} counts on ${oi.compared - oi.matched} of ${oi.compared} contracts`
+      : openInterestAsOfLabel(null));
+  return parts.join(" · ");
+}
+
+/** The spot and open-interest fields every exported row carries. */
+export function optionsBasisFields(basis: OptionsChainBasis) {
+  return {
+    spot: basis.spot?.price ?? null,
+    spotBasis: basis.spot ? basis.spot.basis === "close" ? "close" : basis.spot.session ?? "last" : null,
+    spotAsOf: basis.spot ? new Date(basis.spot.observedAt).toISOString() : null,
+    openInterestAsOf: basis.openInterest?.date ?? null,
+  };
+}
+
 export function optionRows(chain: OptionsChain) {
   const contracts = [
     ...chain.calls.map((contract) => ({ side: "call", contract })),

package/src/cli/commands/overview.ts

@@ -40,13 +40,17 @@ import { formatBasisPoints, toBasisPoints } from "../../utils/basis-points";
 import {
   basisPointsCell,
   DEFAULT_FRED_START,
+  filterFredSeries,
+  fredEmptyAdvice,
   fredEmptyMessage,
   fredExportValue,
   fredHistoryNotes,
+  fredInterval,
+  fredObservationsFromStart,
   fredProvenance,
   fredPublicationTime,
+  fredUnit,
   fredValueHeader,
-  fredValueKey,
   isSpreadSeries,
   laggingSeriesNote,
 } from "./fred-series";
@@ -346,13 +350,10 @@ async function runFredList(filter: string, ctx: Parameters<CliCommandDef["execut
     if (error instanceof ApiRequestError && error.status === 404) ctx.fail("The list of supported FRED series is not available yet.");
     throw error;
   }
-  const terms = filter.toLowerCase().split(/\s+/).filter(Boolean);
-  const rows = catalog.series
-    .map((series) => ({ id: series.id, title: series.title?.trim() ?? "", group: series.group?.trim() ?? "" }))
-    .filter((series) => {
-      const text = `${series.id} ${series.title} ${series.group}`.toLowerCase();
-      return terms.every((term) => text.includes(term));
-    });
+  const rows = filterFredSeries(
+    catalog.series.map((series) => ({ id: series.id, title: series.title?.trim() ?? "", group: series.group?.trim() ?? "" })),
+    filter,
+  );
   ctx.printResult({ data: rows, metadata: { filter: filter || null, total: catalog.series.length } }, {
     columns: [
       { key: "id", header: "ID", shrink: false },
@@ -381,15 +382,17 @@ async function runFred(rawArgs: string[], ctx: Parameters<CliCommandDef["execute
     if (isUnsupportedSeries(error)) ctx.fail(`Unsupported FRED series ${seriesId}. List supported series with: gloomberb fred --list`);
     throw error;
   });
-  // Each observation exports under its unit (`value_bp`, `value_pct`), a spread in basis points.
-  const valueKey = fredValueKey(seriesId, data.info?.units);
+  // Every observation exports as `value`, a spread in basis points; its unit goes in the `currency_or_unit` column.
+  const unit = fredUnit(seriesId, data.info);
+  const interval = fredInterval(data.info?.frequency);
   // A value FRED does not list yet carries its publisher and when it published, in every export.
   const exportRow = (observation: { date: string; value: number | null; publisher?: string; publishedAt?: string }) => ({
     date: observation.date,
-    [valueKey]: fredExportValue(seriesId, observation.value),
+    value: fredExportValue(seriesId, observation.value),
     ...(observation.publisher?.trim() ? { publisher: observation.publisher.trim(), ...(observation.publishedAt ? { publishedAt: observation.publishedAt } : {}) } : {}),
   });
-  const rows = data.observations.map(exportRow);
+  // A --start before the series begins comes back padded with blank days: the rows start at its first observation.
+  const rows = fredObservationsFromStart(data.observations, data.info?.observationStart).map(exportRow);
   // The default start hides older history and a start before the series begins is moved up silently: say where it really starts.
   const notes = [
     ...fredHistoryNotes({ startDate, startGiven: start != null, seriesStart: data.info?.observationStart }),
@@ -398,6 +401,10 @@ async function runFred(rawArgs: string[], ctx: Parameters<CliCommandDef["execute
   // Nothing on or after the start: name where the series ends, so an empty answer is not a dead end.
   const latest = rows.length > 0 ? null : await apiClient.getCloudFredSeries(seriesId, { limit: 1, sortOrder: "desc" })
     .then((payload) => payload.observations[0] ?? null).catch(() => null);
+  // CSV and NDJSON are rows alone: an empty one would read as a series with no data, so it fails and says where the series ends.
+  if (rows.length === 0 && (ctx.cliOptions.format === "csv" || ctx.cliOptions.format === "ndjson")) {
+    ctx.fail(`No ${seriesId} observations on or after ${startDate}.`, fredEmptyAdvice(seriesId, latest));
+  }
   const periodicity = periodicityOf(data.info?.frequency);
   const newestDate = rows.reduce<string | null>((newest, row) => (!newest || row.date > newest ? row.date : newest), null);
   // A newest value FRED does not list yet names its publisher, Treasury for a yield; FRED's own stay "FRED".
@@ -408,7 +415,7 @@ async function runFred(rawArgs: string[], ctx: Parameters<CliCommandDef["execute
   ctx.printResult({
     data: rows,
     metadata: {
-      info: data.info, seriesId, startDate, sortOrder,
+      info: data.info, seriesId, startDate, sortOrder, unit, interval,
       ...(notes.length ? { notes } : {}),
       ...(latest ? { latestObservation: exportRow(latest) } : {}),
     },
@@ -422,12 +429,13 @@ async function runFred(rawArgs: string[], ctx: Parameters<CliCommandDef["execute
   }, {
     dateKey: "date",
     empty: fredEmptyMessage(startDate, latest),
-    ...(notes.length ? { footnote: notes.join("\n") } : {}),
+    ...(notes.length ? { footnote: notes.join("\n"), exportNotes: notes } : {}),
+    exportIdentity: { symbolOrSeries: seriesId, currencyOrUnit: unit, interval },
     textColumns: [
       { key: "date", header: "Date" },
       isSpreadSeries(seriesId)
-        ? { key: valueKey, header: "Value (bp)", align: "right", format: basisPointsCell }
-        : { key: valueKey, header: fredValueHeader(data.info), align: "right" },
+        ? { key: "value", header: "Value (bp)", align: "right", format: basisPointsCell }
+        : { key: "value", header: fredValueHeader(data.info), align: "right" },
     ],
   });
 }
@@ -445,12 +453,12 @@ async function runYieldCurve(rawArgs: string[], ctx: Parameters<CliCommandDef["e
     return {
       seriesId,
       date: latest?.date ?? "",
-      // Yields in percent, named so in every export, as `fred` names a percent series.
-      value_pct: latest?.value ?? null,
+      // Yields in percent, which the exports' `currency_or_unit` column says (`pct`), as `fred` does.
+      value: latest?.value ?? null,
       title: data.info?.title ?? "",
       // The move since the previous observation FRED has, not calendar yesterday: a Monday reads against Friday.
       previousDate: previous?.date ?? null,
-      previousValue_pct: previous?.value ?? null,
+      previousValue: previous?.value ?? null,
       changeBasisPoints: latest?.value != null && previous?.value != null ? toBasisPoints(latest.value - previous.value, 1) : null,
       latest,
       publishedAt: latest?.publisher ? null : fredPublicationTime(data.info, latest?.date),
@@ -470,9 +478,10 @@ async function runYieldCurve(rawArgs: string[], ctx: Parameters<CliCommandDef["e
       ...(publishedAt ? { publishedAt } : {}),
     }),
   }, {
+    exportIdentity: (row) => ({ symbolOrSeries: String(row.seriesId), currencyOrUnit: "pct", interval: "daily" }),
     textColumns: [
       { key: "tenor", header: "Tenor", value: (row) => YIELD_TENORS[String(row.seriesId)] ?? row.seriesId },
-      { key: "value_pct", header: "Yield %", align: "right", format: (value) => typeof value === "number" ? value.toFixed(2) : "-" },
+      { key: "value", header: "Yield %", align: "right", format: (value) => typeof value === "number" ? value.toFixed(2) : "-" },
       {
         key: "changeBasisPoints",
         header: "1D bp",