gloomberb 0.17.0 → 0.17.2

package/src/cli/commands/market.ts

@@ -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,19 +49,25 @@ 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,
-  missingExpiryMessage,
   OPTION_MODEL_RATE,
   OPTIONS_USAGE,
   optionRows,
+  optionsBasisFields,
+  optionsBasisFootnote,
   parseOptionExpiration,
+  valueChainAtModelSpot,
+  type OptionsChainBasis,
 } from "./options-chain";
-import { DEFAULT_LEAPS_CRITERIA, LEAPS_USAGE, parseLeapsCriteria, runLeapsScreen, takeLeapsOptions } from "./options-leaps";
+import { missingExpiryMessage } from "../../utils/option-expiry";
+import {
+  DEFAULT_LEAPS_CRITERIA, LEAPS_EXTRA_COLUMNS, LEAPS_USAGE, parseLeapsCriteria, runLeapsScreen, takeLeapsOptions,
+} from "./options-leaps";
 import type { CliResultColumn } from "../result";
 import type { PriceHistoryResult } from "../../types/price-history";
 import {
@@ -137,7 +144,7 @@ import { formatBasisPoints, toBasisPoints } from "../../utils/basis-points";
 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 { splitSymbolArgs, uniqueSecuritySymbols } from "../symbol-args";
 import { cliPerpetualContract, perpetualContractStats, type PerpetualContractPayload } from "../perpetual-contract";
 import { subMinuteDataMessage } from "../known-gaps";
 import { secRegistrantMismatchMessage, SecRegistrantMismatchError, areDifferentCompanies } from "../../sources/sec-registrant";
@@ -218,9 +225,13 @@ function parseNewsFeed(value: string | undefined): NewsQuery["feed"] | undefined
   return value && VALID_NEWS_FEEDS.has(value as NewsFeed) ? value as NewsQuery["feed"] : undefined;
 }
 
-/** The symbols of a command's arguments, one each however they were separated: spaces, commas or pasted lines. */
+/**
+ * The symbols of a command's arguments, one each however they were separated
+ * (spaces, commas or pasted lines), and each security once however its case or
+ * share class was written: `AAPL aapl BRK.B BRK-B` is AAPL and BRK.B.
+ */
 function normalizeSymbols(args: string[]): string[] {
-  return splitSymbolArgs(args).map((symbol) => symbol.toUpperCase());
+  return uniqueSecuritySymbols(splitSymbolArgs(args).map((symbol) => symbol.toUpperCase()));
 }
 
 /** What JSON metadata says about the listing a command resolved. */
@@ -950,11 +961,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({
@@ -966,6 +979,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 } : {}),
@@ -973,6 +987,7 @@ 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" },
@@ -1462,10 +1477,9 @@ async function runOptions(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
   const expiration = takeOption(args, "--expiration");
   const exchangeOption = takeOption(args, "--exchange");
   if (leapsOptions.leaps) {
-    if (expiration != null || rawArgs.includes("--expiration")) {
-      ctx.fail("--leaps reads every expiry more than a year out; drop --expiration.", `Usage: gloomberb ${LEAPS_USAGE}`);
-    }
-    const criteria = parseLeapsCriteria(leapsOptions.raw);
+    // With --leaps, --expiration is a window of one expiry.
+    const expirationGiven = expiration != null || rawArgs.some((arg) => arg === "--expiration" || arg.startsWith("--expiration="));
+    const criteria = parseLeapsCriteria({ ...leapsOptions.raw, ...expirationGiven ? { "--expiration": expiration ?? "" } : {} });
     if ("error" in criteria) ctx.fail(criteria.error, `Usage: gloomberb ${LEAPS_USAGE}`);
     const symbols = normalizeSymbols(args);
     if (symbols.length === 0) ctx.fail("--leaps needs at least one symbol.", `Usage: gloomberb ${LEAPS_USAGE}`);
@@ -1524,7 +1538,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) };
+    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()}`
@@ -1546,23 +1566,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.
@@ -1580,6 +1631,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]) {
@@ -1763,10 +1817,10 @@ export const marketDataCliCommands: BuiltinCliCommandDef[] = [
       options: [
         {
           flags: "--expiration <YYYY-MM-DD|unix>",
-          description: "Expiration as a date (2028-01-21) or Unix seconds; defaults to the nearest one, and lists the others",
+          description: "Expiration as a date (2028-01-21) or Unix seconds; defaults to the nearest one, and lists the others. With --leaps: rank that expiry alone",
         },
         EXCHANGE_OPTION,
-        { flags: "--leaps", description: "Rank contracts more than a year out across the symbols given, as a stock replacement" },
+        { flags: "--leaps", description: "Rank long-dated contracts across the symbols given, as a stock replacement; more than a year out unless a window says otherwise" },
         { flags: "--side <calls|puts>", description: `With --leaps: the side to rank (default ${DEFAULT_LEAPS_CRITERIA.side}s)` },
         {
           flags: "--delta <low-high>",
@@ -1777,6 +1831,17 @@ export const marketDataCliCommands: BuiltinCliCommandDef[] = [
           description: `With --leaps: widest bid/ask spread, in percent of the midpoint (default ${DEFAULT_LEAPS_CRITERIA.maxSpreadPercent})`,
         },
         { flags: "--min-oi <contracts>", description: `With --leaps: least open interest (default ${DEFAULT_LEAPS_CRITERIA.minOpenInterest})` },
+        {
+          flags: "--min-days <days>",
+          description: `With --leaps: fewest calendar days to expiry (default ${DEFAULT_LEAPS_CRITERIA.minDays}); 180 reaches six months out`,
+        },
+        { flags: "--max-days <days>", description: "With --leaps: most calendar days to expiry; --min-days 365 --max-days 730 is 12 to 24 months" },
+        { flags: "--expiry-from <YYYY-MM-DD>", description: "With --leaps: first expiry date kept; replaces the one-year floor" },
+        { flags: "--expiry-to <YYYY-MM-DD>", description: "With --leaps: last expiry date kept" },
+        {
+          flags: "--columns <list>",
+          description: `With --leaps: add figures, comma-separated: ${LEAPS_EXTRA_COLUMNS.join(", ")}`,
+        },
         {
           flags: "--sort <order>",
           description: "With --leaps: carry (extrinsic per year, lowest first; the default), spread, oi, delta, expiry or symbol",
@@ -1785,7 +1850,10 @@ export const marketDataCliCommands: BuiltinCliCommandDef[] = [
       sections: [{
         title: "LEAPS",
         lines: [
-          "--leaps reads every expiry more than a year out for each symbol and keeps the liquid contracts in the delta band, ranked by extrinsic per year: time value (midpoint less intrinsic) as a percent of spot, per year to expiry.",
+          "--leaps reads each symbol's expiries in the window and keeps the liquid contracts in the delta band, ranked by extrinsic per year: time value (midpoint less intrinsic) as a percent of spot, per year to expiry.",
+          "--min-days, --max-days, --expiry-from and --expiry-to set the window together; without a lower bound it starts a year out. Each symbol reads at most 8 expiries, the ones nearest the window's start, and a warning names any it left.",
+          "--columns adds iv (the contract's implied vol), ivr (the underlying's IV rank), cost (midpoint x 100 per contract), breakeven (at the midpoint, and its distance from spot), next-earnings, ex-dividend and carry-net "
+            + `(extrinsic per year net of the ${Number((OPTION_MODEL_RATE * 100).toFixed(2))}% rate on the strike and the dividend yield). A figure a symbol lacks is blank, with a warning.`,
           "A symbol without LEAPS, a quote or a chain is named in a warning and the others still rank. docs/research-data.md defines each figure.",
         ],
       }],
@@ -1795,6 +1863,8 @@ export const marketDataCliCommands: BuiltinCliCommandDef[] = [
         "options AAPL:NASDAQ --json",
         "options AAPL MSFT NVDA GOOGL AMZN META --leaps",
         "options SPY QQQ --leaps --side puts --delta 0.20-0.40 --csv",
+        "options MSFT --leaps --min-days 365 --max-days 730",
+        "options AAPL MSFT NVDA --leaps --min-days 180 --columns iv,ivr,cost,breakeven,carry-net",
       ],
     },
     execute: runOptions,

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

@@ -1,12 +1,18 @@
-import type { OptionContract, OptionsChain, Quote } from "../../types/financials";
+import type { OptionContract, OptionsChain, Quote, TickerFinancials } from "../../types/financials";
 import type { DataProvider } from "../../types/data-provider";
 import type { CliListing } from "../listing-arg";
 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, statedOpenInterestAsOf,
+} 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";
+import { expiryIsoDate, parseOptionExpiration } from "../../utils/option-expiry";
 
 export const OPTIONS_USAGE = "options <symbol> [--expiration <YYYY-MM-DD|unix>]";
 
@@ -23,22 +29,6 @@ function listedDates(expirations: readonly number[]): string[] {
   return [...new Set(expirations.map((expiration) => expiryIsoDate(expiration)).filter(Boolean))].sort();
 }
 
-/**
- * Why a chain request for one expiry came back without contracts, and which
- * expiries it could have been: the few nearest the requested date, so a typo or
- * an unlisted LEAPS date points at the neighbours to pick.
- */
-export function missingExpiryMessage(
-  symbol: string,
-  requested: number,
-  expirations: readonly number[],
-): { message: string; details?: string } {
-  return {
-    message: missingExpiryText(requested, expirations, symbol),
-    details: `Run gloomberb options ${symbol} to list every expiry (--json carries them too).`,
-  };
-}
-
 const EXPIRY_LIST_LIMIT = 40;
 const EXPIRY_LIST_WIDTH = 100;
 const EXPIRY_GAP = 2;
@@ -61,6 +51,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;
 }
@@ -105,21 +97,35 @@ function optionModelFigures(chain: OptionsChain, inputs: OptionModelInputs): Map
   return figures;
 }
 
-/** Spot and dividend yield for IV and delta, read from the underlying the way the options pane does; missing ones stay missing. */
+/** The underlying's financials, as DES reads them: its dividend yield, ex-dividend date and next report. Null when they cannot be read. */
+export function loadUnderlyingFinancials(
+  dataProvider: Pick<DataProvider, "getTickerFinancials">,
+  listing: CliListing,
+  refresh: boolean,
+): Promise<TickerFinancials | null> {
+  return Promise.resolve().then(() => dataProvider.getTickerFinancials(
+    listing.request.symbol, listing.request.exchange, { cacheMode: refresh ? "refresh" : "default" },
+  )).catch(() => null);
+}
+
+/**
+ * Spot and dividend yield for IV and delta, read from the underlying the way the
+ * options pane does; missing ones stay missing. `financials` shares one read of
+ * them with a caller that needs more of them.
+ */
 export async function loadOptionModelInputs(
   dataProvider: Pick<DataProvider, "getTickerFinancials">,
   listing: CliListing,
   quote: Promise<Quote | null>,
   refresh: boolean,
+  underlying: Promise<TickerFinancials | null> = loadUnderlyingFinancials(dataProvider, listing, refresh),
 ): Promise<OptionModelInputs> {
-  const financials = await Promise.resolve().then(() => dataProvider.getTickerFinancials(
-    listing.request.symbol, listing.request.exchange, { cacheMode: refresh ? "refresh" : "default" },
-  )).catch(() => null);
+  const financials = await underlying;
   const current = [await quote, financials?.quote]
     .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 +137,70 @@ 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: the chain's own, else (a chain
+ * that does not say) from OPX's listing of it; null when the listing cannot be read.
+ */
+export async function loadOptionsChainOpenInterest(symbol: string, chain: OptionsChain): Promise<OpenInterestAsOf | null> {
+  const stated = statedOpenInterestAsOf(chain);
+  if (stated) return stated;
+  const expiration = [...chain.calls, ...chain.puts][0]?.expiration;
+  if (expiration == null) return null;
+  const payload = await loadListedOpenInterest(symbol, expiryIsoDate(expiration));
+  return payload ? chainOpenInterestAsOf(chain, payload) : null;
+}
+
+/**
+ * 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 })),