gloomberb 0.18.3 → 0.18.4

package/src/cli/commands/news-hints.ts

@@ -44,11 +44,11 @@ export function newsEmptyMessage(
     if (searched) {
       return contract
         ? `No stories match ${typed}, the futures board's code for ${contract.name}. It is not a ticker: ${contractSuggestion(contract)}.`
-        : `No listing answers to ${typed} and no stories match it. Try \`gloomberb search ${typed}\`.`;
+        : `No listing answers to ${typed} and no stories match it. Try \`gloom search ${typed}\`.`;
     }
     return contract
       ? `${typed} is the futures board's code for ${contract.name}, not a ticker. news takes a company ticker: ${contractSuggestion(contract)}.`
-      : `No listing answers to ${typed}. news takes a company ticker, such as news AAPL. Try \`gloomberb search ${typed}\`.`;
+      : `No listing answers to ${typed}. news takes a company ticker, such as news AAPL. Try \`gloom search ${typed}\`.`;
   }
   if (isFuturesInstrument(symbol, quote?.instrumentType)) {
     if (searched) {

package/src/cli/commands/news-search.ts

@@ -4,7 +4,7 @@ import { mapCloudNewsArticle } from "../../sources/gloomberb-cloud/news";
 import { cliStyles } from "../../utils/cli-output";
 import { logFailure } from "../../utils/log-failure";
 import { commodityNamedIn, commoditySearchName, isCommodityName } from "../../market-data/commodity-names";
-import type { FuturesContract } from "../../market-data/futures-board";
+import { futuresBoardContract, type FuturesContract } from "../../market-data/futures-board";
 
 /** What the service accepts of a search: two characters to two hundred, with a letter or a number in them. */
 const MIN_TEXT_LENGTH = 2;
@@ -26,7 +26,7 @@ export function newsSearchText(args: readonly string[]): string | null {
 }
 
 /** How to type a word as text to search from a shell: `'"gold"'` keeps the quotes a shell would drop. */
-export const quotedSearchCommand = (word: string) => `gloomberb news '"${word}"'`;
+export const quotedSearchCommand = (word: string) => `gloom news '"${word}"'`;
 
 /**
  * Whether a word typed for `news` may mean more than the listing it found:
@@ -77,12 +77,65 @@ export function newsFallbackText(symbol: string): string | null {
  * newest first within each. The service holds stories back from an account
  * without real-time access, as every other news request.
  */
-export async function searchNewsStories(text: string, limit: number): Promise<NewsArticle[]> {
-  const response = await apiClient.searchCloudNews(text, limit);
+export async function searchNewsStories(text: string, limit: number, topics?: readonly string[]): Promise<NewsArticle[]> {
+  const response = await apiClient.searchCloudNews(text, limit, topics);
   return response.items.map((item) => mapCloudNewsArticle(item));
 }
 
-/** The futures news route a search offers when no story matches it: `gloomberb news KC=F` for "arabica". */
+/** The NI code of the metal markets: prices, futures, bullion and the trusts that hold it, not a miner's releases. */
+export const METALS_NEWS_TOPIC = "metals";
+
+/** A metal's market news, for what `news` was given: its name, its future, or its board code. */
+export interface MetalNewsRoute {
+  /** The metal the stories are searched for, in METALS: "gold". */
+  metal: string;
+  contract: FuturesContract;
+  /** Why what was typed reads as the metal, under the heading; null for the metal's own name. */
+  reason: string | null;
+  /** The name as typed, which in capitals may be a ticker too ("gold", GOLD for Gold.com Inc.). */
+  word: string | null;
+}
+
+/**
+ * A metal's market news for a metal's future (GC=F, SI=F, HG=F, PL=F, PA=F,
+ * ALI=F) or its name typed as a word (gold, Silver, copper): news filed under
+ * companies has none of the metal's own, and the stories that merely name it
+ * are mostly miners' releases. A word with no lower-case letter (GOLD) is a
+ * ticker and keeps its company news; a board code typed bare (GC) is read once
+ * no listing answers to it (`metalCodeNewsRoute`).
+ */
+export function metalNewsRoute(typed: string): MetalNewsRoute | null {
+  const text = typed.trim();
+  if (/=F$/i.test(text)) {
+    const contract = futuresBoardContract(text);
+    const metal = contract?.sector === "metals" ? commoditySearchName(contract) : null;
+    return contract && metal ? { metal, contract, reason: `the commodity ${contract.symbol} trades`, word: null } : null;
+  }
+  if (!/^\p{L}{3,}$/u.test(text) || !/\p{Ll}/u.test(text)) return null;
+  // One word of letters: the metal's names are one word each (gold, aluminium).
+  const contract = commodityNamedIn(text);
+  return contract?.sector === "metals" ? { metal: text.toLowerCase(), contract, reason: null, word: text } : null;
+}
+
+/** A metal's market news for its board code typed bare (GC, SI, HG) where no listing answers to it. */
+export function metalCodeNewsRoute(typed: string): MetalNewsRoute | null {
+  const code = typed.trim().toUpperCase();
+  const contract = /^[A-Z]{2,3}$/.test(code) ? futuresBoardContract(code) : null;
+  const metal = contract?.sector === "metals" ? commoditySearchName(contract) : null;
+  return contract && metal ? { metal, contract, reason: `${code} is the futures board's code for ${contract.name}`, word: null } : null;
+}
+
+/** The line above a metal's market news: "Metals news matching "gold"", with why what was typed reads as the metal. */
+export function metalNewsHeading(route: MetalNewsRoute): string {
+  return `${cliStyles.bold(`Metals news matching "${route.metal}"`)}${route.reason ? cliStyles.muted(`  ·  ${route.reason}`) : ""}`;
+}
+
+/** What a metal's market news says when no story is tagged METALS: every story that names it is one search away. */
+export function noMetalStoriesMessage(route: MetalNewsRoute): string {
+  return `No metals stories match "${route.metal}". For every story that mentions it, try: ${quotedSearchCommand(route.metal)}`;
+}
+
+/** The futures news route a search offers when no story matches it: `gloom news KC=F` for "arabica". */
 export interface CommodityNewsRoute {
   contract: FuturesContract;
   command: string;
@@ -98,7 +151,7 @@ export async function commodityNewsRoute(text: string): Promise<CommodityNewsRou
   const name = contract ? commoditySearchName(contract) : null;
   if (!contract || !name || isCommodityName(text, name)) return null;
   const stories = await searchNewsStories(name, 1).catch(logFailure("cli.news-search", "Search a commodity's stories failed", []));
-  return stories.length > 0 ? { contract, command: `gloomberb news ${contract.symbol}` } : null;
+  return stories.length > 0 ? { contract, command: `gloom news ${contract.symbol}` } : null;
 }
 
 /** What a search that matched no story says: never a near miss, and the commodity's futures news where it has some. */

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

@@ -8,26 +8,27 @@ import { formatCountCell } from "../helpers";
 import { cliStyles, renderTable, type CliTableColumn } from "../../utils/cli-output";
 import { errorMessage } from "../../utils/errors";
 import { numberErrorMessage, rangeErrorMessage } from "../../utils/decimal-comma";
-import { expiryIsoDate, OPTION_EXPIRATION_FORMAT, parseOptionExpiration } from "../../utils/option-expiry";
+import { expirationHint, expiryIsoDate, OPTION_EXPIRATION_FORMAT, parseOptionExpiration } from "../../utils/option-expiry";
 import { dateOptionError, readCalendarDate } from "../../utils/calendar-date";
 import { isFundType } from "../../utils/sec";
-import { zonedDateKey } from "../../utils/zoned-date-time";
 import { daysToExpiryFrom, optionMid, type OptionSide } from "../../plugins/builtin/shared/volatility";
 import { optionQuoteValuationTime } from "../../plugins/builtin/vol-surface/model";
 import { optionBreakeven, optionCarry, optionCarryNet, optionSpreadPercent } from "../../plugins/builtin/options/carry";
 import { parseDeltaBand } from "../../plugins/builtin/options/strike-window";
-import { ivSymbol, loadIvScreen, type IvScreenRow } from "../../plugins/builtin/iv-history/client";
+import { ivRankReason, ivSymbol, loadIvScreen, type IvScreenRow } from "../../plugins/builtin/iv-history/client";
+import { newYorkDay, resolveListingEvents, upcomingReportDate } from "../../plugins/builtin/shared/earnings-calendar";
 import {
   chainWithModelFigures, loadOptionModelInputs, loadUnderlyingFinancials, OPTION_MODEL_RATE, type OptionModelInputs,
 } from "./options-chain";
 import { takeFlag, takeOption } from "./command-utils";
 
 /**
- * `gloomberb options <symbol...> --leaps`: long-dated contracts ranked across
+ * `gloom options <symbol...> --leaps`: long-dated contracts ranked across
  * symbols for a stock replacement, by what the time value costs per year.
  * Delta, IV and carry come from the same solver and formulas as the options
- * pane (`carry.ts`, `analytics.ts`); IV rank, the next report and the
- * ex-dividend date from the same sources as OMON, OVDV and DES.
+ * pane (`carry.ts`, `analytics.ts`); IV rank and the ex-dividend date from
+ * the same sources as OVDV and DES, and the next report as `earnings`, EE and
+ * ERN resolve it.
  */
 export const LEAPS_USAGE = "options <symbol...> --leaps [--side calls|puts] [--delta <low-high>] [--max-spread <percent>] "
   + "[--min-oi <contracts>] [--min-days <days>] [--max-days <days>] [--expiry-from <date>] [--expiry-to <date>] "
@@ -163,7 +164,7 @@ function parseLeapsWindow(raw: Record<string, string | undefined>, now: number):
       return { error: "--expiration reads one expiry; give it alone, or a range with --expiry-from and --expiry-to." };
     }
     const seconds = parseOptionExpiration(expiration);
-    if (seconds == null) return { error: `Invalid --expiration "${expiration}". Use ${OPTION_EXPIRATION_FORMAT}.` };
+    if (seconds == null) return { error: `Invalid --expiration "${expiration}". Use ${OPTION_EXPIRATION_FORMAT}.${expirationHint(expiration)}` };
     window.expiryFrom = window.expiryTo = expiryIsoDate(seconds);
   }
   const fromFlag = expiration != null ? "--expiration" : "--expiry-from";
@@ -500,13 +501,6 @@ function ivKey(listing: CliListing): string | null {
   }
 }
 
-/** Why a symbol IV history covers has no rank yet, by where its history stands. */
-const IV_COVERAGE_REASONS: Partial<Record<string, string>> = {
-  queued: "IV history queued, try again in a few minutes",
-  backfilling: "IV history still loading",
-  unavailable: "no options history",
-};
-
 async function loadLeapsIvRanks(listings: readonly CliListing[]): Promise<LeapsIvRanks> {
   const symbols = listings.flatMap((listing) => ivKey(listing) ?? []);
   if (symbols.length === 0) return { rows: new Map(), error: null };
@@ -518,9 +512,26 @@ async function loadLeapsIvRanks(listings: readonly CliListing[]): Promise<LeapsI
   }
 }
 
+/** Each symbol's next report date for every symbol in one calendar read, as `earnings` resolves it; a failed read is one reason for all. */
+type LeapsNextReports = { dates: Map<string, string | null>; error: string | null };
+
+async function loadLeapsNextReports(market: MarketContext, listings: readonly CliListing[], now: number): Promise<LeapsNextReports> {
+  const keys = listings.map((listing) => listing.key);
+  try {
+    const events = await market.dataProvider.getEarningsCalendar?.(keys) ?? [];
+    const resolved = await resolveListingEvents(market.dataProvider, listings.map((listing) => ({
+      key: listing.key, symbol: listing.request.symbol, exchange: listing.request.exchange,
+    })), events, newYorkDay(now));
+    return { dates: new Map(keys.map((key) => [key.toUpperCase(), upcomingReportDate(resolved.get(key.toUpperCase()))])), error: null };
+  } catch (error) {
+    return { dates: new Map(), error: errorMessage(error) ?? "no response" };
+  }
+}
+
 /**
  * The underlying's `--columns` figures and, in one phrase, what of them it
- * lacks: IV rank from Cloud IV history; the next report and the latest
+ * lacks: IV rank from Cloud IV history; the next report from the earnings
+ * calendar, resolved as every earnings surface resolves it; the latest
  * ex-dividend date from the financials DES reads, which also give the dividend
  * yield delta is valued at. A fund reports no earnings, and a stock paying no
  * dividend has no ex-date, so neither is named as missing.
@@ -532,7 +543,7 @@ function underlyingFigures(
   instrumentType: string | undefined,
   dividendYield: number | undefined,
   ivRanks: LeapsIvRanks | null,
-  now: number,
+  nextReports: LeapsNextReports | null,
 ): { figures: LeapsUnderlying; missing: string[] } {
   const figures: LeapsUnderlying = {};
   const missing: string[] = [];
@@ -545,25 +556,24 @@ function underlyingFigures(
     // A failed request is said once for every symbol.
     if (figures.ivRank == null && !ivRanks?.error) {
       const reason = key == null ? "US listings only"
-        : row?.iv30?.rankNote ?? row?.warnings?.[0] ?? (row ? IV_COVERAGE_REASONS[row.coverageStatus ?? row.status] ?? null : "no IV history");
+        : ivRankReason(row);
       missing.push(`no IV rank${reason ? ` (${reason})` : ""}`);
     }
   }
-  const today = zonedDateKey(now, "America/New_York");
   if (columns.has("next-earnings")) {
-    const next = financials?.nextEarnings?.date;
-    figures.nextEarnings = next && ISO_DATE.test(next) && next >= today ? next : null;
+    figures.nextEarnings = nextReports?.dates.get(listing.key.toUpperCase()) ?? null;
+    // A failed calendar read is said once for every symbol.
+    if (figures.nextEarnings == null && !nextReports?.error && !isFundType(instrumentType)) missing.push("no upcoming earnings date");
   }
   if (columns.has("ex-dividend")) {
     const exDate = financials?.fundamentals?.exDividendDate;
     figures.exDividend = exDate && ISO_DATE.test(exDate) ? exDate : null;
   }
   if (columns.has("carry-net")) figures.dividendYield = dividendYield ?? null;
-  if (financials == null && (columns.has("next-earnings") || columns.has("ex-dividend") || columns.has("carry-net"))) {
-    missing.push(columns.has("carry-net") ? "no earnings or dividend data, so carry-net counts no dividends" : "no earnings or dividend data");
+  if (financials == null && (columns.has("ex-dividend") || columns.has("carry-net"))) {
+    missing.push(columns.has("carry-net") ? "no dividend data, so carry-net counts no dividends" : "no dividend data");
     return { figures, missing };
   }
-  if (columns.has("next-earnings") && figures.nextEarnings == null && !isFundType(instrumentType)) missing.push("no upcoming earnings date");
   if (columns.has("ex-dividend") && figures.exDividend == null && dividendYield !== 0) missing.push("no ex-dividend date");
   if (columns.has("carry-net") && dividendYield == null) missing.push("dividend yield unknown, so carry-net counts no dividends");
   return { figures, missing };
@@ -576,11 +586,12 @@ async function screenSymbol(
   refresh: boolean,
   limit: ReturnType<typeof concurrencyLimit>,
   ivRanks: Promise<LeapsIvRanks> | null,
+  nextReports: Promise<LeapsNextReports> | null,
   now: number,
 ): Promise<{ result: LeapsSymbolResult; rows: LeapsRow[]; warning: string | null }> {
   const symbol = listing.key;
   const quote = loadListingQuote(market.dataProvider, listing);
-  // One read of the financials gives delta its dividend yield and --columns the report and ex-dividend dates.
+  // One read of the financials gives delta its dividend yield and --columns the ex-dividend date.
   const financials = loadUnderlyingFinancials(market.dataProvider, listing, refresh);
   const inputsPromise = loadOptionModelInputs(market.dataProvider, listing, quote, refresh, financials);
   const fail = (error: string, spot: number | null = null) => ({
@@ -628,7 +639,7 @@ async function screenSymbol(
   const underlying: { figures: LeapsUnderlying; missing: string[] } = columns.size === 0
     ? { figures: {}, missing: [] }
     : underlyingFigures(listing, columns, await financials, inputs.quote?.instrumentType ?? (await quote)?.instrumentType,
-      inputs.dividendYield, ivRanks ? await ivRanks : null, now);
+      inputs.dividendYield, ivRanks ? await ivRanks : null, nextReports ? await nextReports : null);
   // Each row carries the underlying's figures; the dividend yield behind carry-net is in `symbols`.
   const rowFigures: LeapsUnderlying = { ...underlying.figures };
   delete rowFigures.dividendYield;
@@ -775,7 +786,9 @@ export async function runLeapsScreen(
   const limit = concurrencyLimit(LEAPS_CHAIN_CONCURRENCY);
   // IV rank is one request for every symbol, read beside the chains and only when asked for.
   const ivRanks = criteria.columns.includes("ivr") ? loadLeapsIvRanks(listings) : null;
-  const screened = await Promise.all(listings.map((listing) => screenSymbol(market, listing, criteria, refresh, limit, ivRanks, now)));
+  // The next reports are one calendar read for every symbol, likewise.
+  const nextReports = criteria.columns.includes("next-earnings") ? loadLeapsNextReports(market, listings, now) : null;
+  const screened = await Promise.all(listings.map((listing) => screenSymbol(market, listing, criteria, refresh, limit, ivRanks, nextReports, now)));
   const symbols = screened.map((entry) => entry.result);
   // Nothing to rank only when no symbol's chain loaded at all; a symbol without LEAPS is an answer.
   if (symbols.every((entry) => entry.error?.startsWith("options chain unavailable"))) {
@@ -783,10 +796,12 @@ export async function runLeapsScreen(
   }
   const rows = sortLeapsRows(screened.flatMap((entry) => entry.rows), criteria.sort);
   const ivRankError = ivRanks ? (await ivRanks).error : null;
+  const nextReportsError = nextReports ? (await nextReports).error : null;
   const warnings = [
     ...listings.flatMap(listingReadNotes),
     ...screened.map((entry) => entry.warning).filter((warning): warning is string => warning != null),
     ...ivRankError ? [`IV rank unavailable (${ivRankError})`] : [],
+    ...nextReportsError ? [`Next earnings unavailable (${nextReportsError})`] : [],
   ];
   const { format, limit: rowLimit, tail } = ctx.cliOptions;
   const capped = format === "text" && rowLimit == null && tail == null && rows.length > LEAPS_TEXT_ROWS;