gloomberb 0.18.3 → 0.18.4

package/src/plugins/builtin/earnings-calls/data.ts

@@ -9,6 +9,8 @@ import { ApiRequestError } from "../../../api-client/errors";
 import { listingAbroad, type IssuerListingParams, type ListingAbroad } from "../../../api-client/paths";
 import { areDifferentCompanies } from "../../../sources/sec-registrant";
 import type { HeadlessPaneApiClient, PluginPersistence } from "../../../types/plugin";
+import { shortDate } from "../earnings/format";
+import { callCountdown, callDay, callTimeKnown, isUpcomingCall } from "./upcoming";
 
 type EarningsCallsApiClient = Pick<
   HeadlessPaneApiClient,
@@ -54,8 +56,9 @@ export interface EarningsCallsResult {
   sourceLimitReached?: boolean;
 }
 
-/** Short label for the state of a call without a transcript. */
-export function callStatusLabel(call: CloudEarningsCallPayload): string {
+/** Short label for the state of a call without a transcript; "upcoming" for one still to come. */
+export function callStatusLabel(call: CloudEarningsCallPayload, now = Date.now()): string {
+  if (isUpcomingCall(call, now)) return "upcoming";
   switch (call.status) {
     case "available":
       return "on request";
@@ -71,7 +74,61 @@ export function callStatusLabel(call: CloudEarningsCallPayload): string {
   }
 }
 
+/** How long after its start a call not yet transcribed reads as started rather than queued. */
+const STARTED_FOR_MS = 3 * 60 * 60 * 1000;
+
+/**
+ * What the IN column says: how far away a call still to come is, and for one
+ * over, where its transcript is.
+ */
+export function calendarAway(call: CloudEarningsCallPayload, now: number): string {
+  if (isUpcomingCall(call, now)) return callCountdown(call, now);
+  if (call.hasTranscript) return "transcribed";
+  const label = callStatusLabel(call, now);
+  if (label === "in progress") return label;
+  const started = callTimeKnown(call) ? now - Date.parse(call.callAt!) : Number.POSITIVE_INFINITY;
+  return started < STARTED_FOR_MS ? "started" : label;
+}
+
+/** What the pane's notice and `fn CALLS` say when the calendar may be cut. */
+export function upcomingCutNotice(calls: readonly CloudEarningsCallPayload[]): string {
+  // The server answers earliest first, so the cut is late on the last day it reached.
+  const last = calls.length > 0 ? callDay(calls[calls.length - 1]!) : null;
+  return `The calendar stops at ${UPCOMING_LIMIT.toLocaleString("en-US")} calls${last ? `: later calls from ${shortDate(last)} on may be missing` : ""}.`;
+}
+
+const UPCOMING_KIND = "upcoming";
+const UPCOMING_CACHE_SCHEMA_VERSION = 1;
+/** The calendar moves as calls are found ahead and transcribed after; a day-old one is no calendar. */
+const UPCOMING_CACHE_POLICY = {
+  staleMs: 5 * 60 * 1000,
+  expireMs: 24 * 60 * 60 * 1000,
+} as const;
+/**
+ * The most calls one calendar asks for, the server's own cap. A peak week of
+ * the reporting season holds about 600, so a week is never cut; a calendar
+ * that gets this many says it may be (`truncated`).
+ */
+export const UPCOMING_LIMIT = 1500;
+
+/** Every company's calls on New York days `from` to `to`, earliest first. */
+export interface UpcomingCallsResult {
+  calls: CloudEarningsCallPayload[];
+  fetchedAt: number;
+  stale: boolean;
+  /** The server answered its limit's worth: calls later on these days may be missing. */
+  truncated?: boolean;
+  refreshError?: string;
+  errorStatus?: number;
+}
+
+export interface UpcomingDays {
+  from: string;
+  to: string;
+}
+
 let persistence: PluginPersistence | null = null;
+const activeUpcomingFetches = new Map<string, Promise<UpcomingCallsResult>>();
 const activeListFetches = new Map<string, Promise<EarningsCallsResult>>();
 const activeTranscriptFetches = new Map<string, Promise<CloudEarningsTranscriptPayload>>();
 
@@ -81,6 +138,7 @@ export function attachEarningsCallsPersistence(value: PluginPersistence): void {
 
 export function resetEarningsCallsPersistence(): void {
   persistence = null;
+  activeUpcomingFetches.clear();
   activeListFetches.clear();
   activeTranscriptFetches.clear();
   heldAudio.clear();
@@ -240,6 +298,92 @@ export function cachedEarningsCalls(
   };
 }
 
+/**
+ * A server from before the calendar answers the shelf of transcripts, whatever
+ * the days: only calls on those days are the calendar's.
+ */
+function onDays(calls: CloudEarningsCallPayload[], days: UpcomingDays): CloudEarningsCallPayload[] {
+  return calls.filter((call) => {
+    const day = callDay(call);
+    return day !== null && day >= days.from && day <= days.to;
+  });
+}
+
+type UpcomingCallsClient = Pick<HeadlessPaneApiClient, "getCloudEarningsCalls">;
+type UpcomingCacheValue = { calls: CloudEarningsCallPayload[]; truncated?: boolean };
+
+function upcomingFromCache(value: UpcomingCacheValue, fetchedAt: number, stale: boolean): UpcomingCallsResult {
+  return { calls: value.calls, fetchedAt, stale, ...(value.truncated ? { truncated: true } : {}) };
+}
+
+export async function loadUpcomingCallsWithClient(
+  client: UpcomingCallsClient,
+  days: UpcomingDays,
+  options: { force?: boolean } = {},
+): Promise<UpcomingCallsResult> {
+  const key = JSON.stringify([days.from, days.to]);
+  const store = persistence;
+  const read = (allowExpired: boolean) => store?.getResource<UpcomingCacheValue>(UPCOMING_KIND, key, {
+    sourceKey: CACHE_SOURCE,
+    schemaVersion: UPCOMING_CACHE_SCHEMA_VERSION,
+    ...(allowExpired ? { allowExpired: true } : {}),
+  });
+  const cached = read(false);
+  if (!options.force && cached && !cached.stale) return upcomingFromCache(cached.value, cached.fetchedAt, false);
+  const active = activeUpcomingFetches.get(key);
+  if (active && !options.force) return active;
+
+  const request = client
+    .getCloudEarningsCalls({ upcoming: days, limit: UPCOMING_LIMIT })
+    .then((payload) => {
+      const answered = payload.calls ?? [];
+      const value: UpcomingCacheValue = {
+        calls: onDays(answered, days),
+        // A full answer may stop partway through the last day it reaches.
+        ...(answered.length >= UPCOMING_LIMIT ? { truncated: true } : {}),
+      };
+      if (activeUpcomingFetches.get(key) === request && persistence === store) {
+        store?.setResource(UPCOMING_KIND, key, value, {
+          sourceKey: CACHE_SOURCE,
+          schemaVersion: UPCOMING_CACHE_SCHEMA_VERSION,
+          cachePolicy: UPCOMING_CACHE_POLICY,
+        });
+      }
+      return upcomingFromCache(value, Date.now(), false);
+    })
+    .catch((error: unknown) => {
+      const errorStatus = statusOf(error);
+      // Losing Pro access re-gates the calendar, as it does the list.
+      const expired = read(true);
+      if (expired && errorStatus !== 401 && errorStatus !== 402 && errorStatus !== 403) {
+        return {
+          ...upcomingFromCache(expired.value, expired.fetchedAt, true),
+          refreshError: error instanceof Error ? error.message : String(error),
+          errorStatus,
+        };
+      }
+      throw error;
+    })
+    .finally(() => {
+      if (activeUpcomingFetches.get(key) === request) activeUpcomingFetches.delete(key);
+    });
+  activeUpcomingFetches.set(key, request);
+  return request;
+}
+
+export function loadUpcomingCalls(days: UpcomingDays, options?: { force?: boolean }): Promise<UpcomingCallsResult> {
+  return loadUpcomingCallsWithClient(apiClient, days, options);
+}
+
+export function cachedUpcomingCalls(days: UpcomingDays): UpcomingCallsResult | null {
+  const cached = persistence?.getResource<UpcomingCacheValue>(UPCOMING_KIND, JSON.stringify([days.from, days.to]), {
+    sourceKey: CACHE_SOURCE,
+    schemaVersion: UPCOMING_CACHE_SCHEMA_VERSION,
+    allowExpired: true,
+  });
+  return cached ? upcomingFromCache(cached.value, cached.fetchedAt, cached.stale === true) : null;
+}
+
 /**
  * The server answers 202 with a pending marker when a call is known but not
  * transcribed yet, having just queued it. That is not a transcript and must

package/src/plugins/builtin/earnings-calls/headless.ts

@@ -11,12 +11,33 @@ import type {
 import { explainRefusal } from "../shared/cloud-denied";
 import { resolveHeadlessIssuerListing } from "../shared/headless-market-data";
 import {
+  calendarAway,
   callStatusLabel,
   isPendingTranscript,
   loadEarningsCallsWithClient,
   loadTranscriptWithClient,
+  loadUpcomingCallsWithClient,
+  UPCOMING_LIMIT,
+  upcomingCutNotice,
   type EarningsCallsResult,
+  type UpcomingCallsResult,
+  type UpcomingDays,
 } from "./data";
+import { formatPeriod } from "./format";
+import type { MarketDay } from "../earnings/board-model";
+import {
+  calendarDays,
+  calendarSections,
+  callAway,
+  callCountdown,
+  callLocalClock,
+  callNewYorkClock,
+  callStartText,
+  callTimeKnown,
+  clockIsNewYork,
+  isUpcomingCall,
+  nextCall,
+} from "./upcoming";
 import { callsLockNote } from "./lock-note";
 import {
   buildTranscriptSegments,
@@ -38,6 +59,22 @@ const CALL_COLUMNS = [
   { key: "sentiment", header: "Tone", align: "right" as const },
 ];
 
+/** CALLS alone: the calendar's calls, by day, with their starts here and in New York. */
+const CALENDAR_COLUMNS = [
+  { key: "day", header: "Day" },
+  { key: "ticker", header: "Ticker" },
+  { key: "company", header: "Company" },
+  { key: "callAt", header: "Call at" },
+  { key: "timeKnown", header: "Time known" },
+  { key: "local", header: "Local" },
+  { key: "newYork", header: "ET" },
+  { key: "period", header: "Period" },
+  { key: "in", header: "In" },
+  { key: "status", header: "Status" },
+];
+/** The text report leaves out the instant and its flag, which the two clocks say, and the status the In column says. */
+const CALENDAR_TEXT_COLUMNS = CALENDAR_COLUMNS.filter((column) => !["callAt", "timeKnown", "status"].includes(column.key));
+
 const TRANSCRIPT_COLUMNS = [
   { key: "index", header: "#", align: "right" as const },
   { key: "section", header: "Section" },
@@ -54,6 +91,9 @@ export interface EarningsCallsHeadlessDependencies {
     limit: number,
     context: HeadlessPaneContext,
   ): Promise<EarningsCallsResult>;
+  loadUpcoming(days: UpcomingDays, context: HeadlessPaneContext): Promise<UpcomingCallsResult>;
+  /** When the report is read; the countdowns and the calendar's days are against it. */
+  now?(): number;
   loadTranscript(
     callId: string,
     context: HeadlessPaneContext,
@@ -66,6 +106,7 @@ const defaultDependencies: EarningsCallsHeadlessDependencies = {
     ticker,
     { limit, ...(ticker ? await resolveHeadlessIssuerListing(context, ticker) : {}) },
   ),
+  loadUpcoming: (days, context) => loadUpcomingCallsWithClient(context.apiClient, days),
   loadTranscript: (callId, context) => loadTranscriptWithClient(context.apiClient, callId),
 };
 
@@ -74,7 +115,8 @@ function explainDenied(ticker: string | null, context: HeadlessPaneContext) {
   return async (error: unknown): Promise<never> => { throw await explainRefusal(error, callsLockNote, { symbol: ticker, context }); };
 }
 
-function callRow(call: CloudEarningsCallPayload) {
+function callRow(call: CloudEarningsCallPayload, now: number) {
+  const upcoming = isUpcomingCall(call, now);
   return {
     id: call.id,
     ticker: call.ticker,
@@ -82,7 +124,9 @@ function callRow(call: CloudEarningsCallPayload) {
     callAt: call.callAt,
     fiscalYear: call.fiscalYear,
     fiscalQuarter: call.fiscalQuarter,
-    status: call.hasTranscript ? "transcribed" : callStatusLabel(call) || call.status,
+    status: call.hasTranscript ? "transcribed" : callStatusLabel(call, now) || call.status,
+    upcoming,
+    in: upcoming ? callCountdown(call, now) : null,
     durationSeconds: call.durationSeconds,
     wordCount: call.wordCount,
     hasTranscript: call.hasTranscript,
@@ -96,24 +140,37 @@ function availabilityMatches(call: CloudEarningsCallPayload, availability: strin
   return availability === "transcribed" ? call.hasTranscript : !call.hasTranscript;
 }
 
+/** The next call as its own line above a company's calls: "Next call Thu Oct 22 22:30 (16:30 ET), in 3h." */
+export function nextCallNotice(call: CloudEarningsCallPayload, now: number): string {
+  const { start, newYork } = callStartText(call, now);
+  const away = callAway(call, now);
+  return `Next call ${start}${newYork ? ` (${newYork})` : ""}${away ? `, ${away}` : ""}.`;
+}
+
 function projectEarningsCallsHeadless(
   result: EarningsCallsResult,
   args: HeadlessPaneLoadArgs,
+  now: number,
 ): HeadlessRowsResult {
   const availability = String(args.options.availability ?? "all");
   const limit = Number(args.options.limit ?? 50);
   const matching = sortCallsNewest(result.calls)
     .filter((call) => availabilityMatches(call, availability));
-  const rows = matching.slice(0, limit).map(callRow);
+  // A company's next call leads, on its own line above the table as in the pane.
+  const next = typeof args.argument === "string" ? nextCall(matching, now) : null;
+  const ordered = next ? [next, ...matching.filter((call) => call !== next)] : matching;
+  const rows = ordered.slice(0, limit).map((call) => callRow(call, now));
   const sourceLimit = result.sourceLimit ?? 200;
   const sourceLimitReached = result.sourceLimitReached ?? result.calls.length >= sourceLimit;
 
   return {
     columns: CALL_COLUMNS,
     rows,
+    ...(next ? { textRows: rows.filter((row) => row.id !== next.id) } : {}),
     errors: result.refreshError ? [result.refreshError] : undefined,
     ...(sourceLimitReached || result.pending ? { complete: false } : {}),
     metadata: {
+      ...(next ? { notices: [nextCallNotice(next, now)], nextCall: { id: next.id, callAt: next.callAt, timeKnown: callTimeKnown(next), in: callCountdown(next, now) } } : {}),
       fetchedAt: result.fetchedAt,
       stale: result.stale,
       pending: result.pending ?? false,
@@ -181,9 +238,73 @@ function transcriptResult(
   };
 }
 
+/** The calendar's rows: each day's calls in start order, with how far away each is. */
+function projectCalendar(
+  result: UpcomingCallsResult,
+  days: readonly MarketDay[],
+  args: HeadlessPaneLoadArgs,
+  now: number,
+): HeadlessRowsResult {
+  const availability = String(args.options.availability ?? "all");
+  // The calendar lists every call of its days unless --limit says fewer.
+  const limit = args.options.limit == null ? Number.POSITIVE_INFINITY : Number(args.options.limit);
+  const sections = calendarSections(result.calls.filter((call) => availabilityMatches(call, availability)), days);
+  const all = sections.flatMap((section) => section.items.map((call) => ({ day: section.label, call })));
+  const rows = all.slice(0, limit).map(({ day, call }) => ({
+    id: call.id,
+    day,
+    ticker: call.ticker,
+    company: call.companyName,
+    callAt: call.callAt,
+    timeKnown: callTimeKnown(call),
+    local: callLocalClock(call),
+    newYork: callNewYorkClock(call),
+    period: formatPeriod(call.fiscalYear, call.fiscalQuarter),
+    fiscalYear: call.fiscalYear,
+    fiscalQuarter: call.fiscalQuarter,
+    in: calendarAway(call, now),
+    status: call.hasTranscript ? "transcribed" : callStatusLabel(call, now) || call.status,
+    hasTranscript: call.hasTranscript,
+    webcastUrl: call.webcastUrl ?? null,
+  }));
+  // On New York's clock one time says both, as in the pane.
+  const sameClock = clockIsNewYork(all.map(({ call }) => call), now);
+  // A cut list says so above the table: the server's limit, or the reader's own --limit.
+  const notices = [
+    ...(result.truncated ? [upcomingCutNotice(result.calls)] : []),
+    ...(rows.length < all.length ? [`Showing the first ${rows.length} of ${all.length} calls (--limit ${rows.length}).`] : []),
+  ];
+  return {
+    columns: CALENDAR_COLUMNS,
+    textColumns: sameClock ? CALENDAR_TEXT_COLUMNS.filter((column) => column.key !== "local") : CALENDAR_TEXT_COLUMNS,
+    rows,
+    errors: result.refreshError ? [result.refreshError] : undefined,
+    ...(result.stale || result.truncated ? { complete: false } : {}),
+    empty: "No calls on the calendar these days.",
+    metadata: {
+      view: "upcoming",
+      fetchedAt: result.fetchedAt,
+      stale: result.stale,
+      from: days[0]?.from ?? null,
+      to: days.at(-1)?.to ?? null,
+      days: days.map((day) => ({ label: day.label, from: day.from, to: day.to })),
+      timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+      availability,
+      total: all.length,
+      returned: rows.length,
+      truncated: rows.length < all.length || !!result.truncated,
+      sourceLimit: UPCOMING_LIMIT,
+      sourceLimitReached: !!result.truncated,
+      ...(notices.length ? { notices } : {}),
+    },
+  };
+}
+
 /**
- * `fn CALLS` lists calls; `fn CALLS NVDA` lists the company's calls. Naming a
- * quarter or a section reads one transcript instead, with paging.
+ * `fn CALLS` is the calendar of every company's calls this week (`--view
+ * transcripts` lists the latest transcripts instead); `fn CALLS NVDA` lists
+ * the company's calls, its next one first. Naming a quarter or a section
+ * reads one transcript instead, with paging.
  */
 function readsTranscript(args: HeadlessPaneLoadArgs): boolean {
   return typeof args.argument === "string"
@@ -199,10 +320,22 @@ export function createEarningsCallsHeadless(
     argument: {
       kind: "ticker",
       placeholder: "ticker",
-      description: "Optional company symbol. Omit it to browse all calls.",
+      description: "Optional company symbol. Omit it for the calendar of every company's calls.",
       optional: true,
     },
     options: [
+      {
+        key: "view",
+        description: "Without a ticker: the calendar of every company's calls today and this week, or the latest transcripts.",
+        type: "enum",
+        values: [
+          { value: "upcoming", aliases: ["calendar"] },
+          { value: "transcripts", aliases: ["transcribed", "shelf"] },
+        ],
+        defaultValue: "upcoming",
+        example: "--view transcripts",
+        exampleWithoutArgument: true,
+      },
       {
         key: "availability",
         shot: REPORT_FILTER,
@@ -265,7 +398,7 @@ export function createEarningsCallsHeadless(
       {
         key: "limit",
         shot: REPORT_ROWS,
-        description: "Maximum calls, or transcript segments, to return (50 calls, 20 segments by default).",
+        description: "Maximum calls, or transcript segments, to return (every call on the calendar, 50 of a company's calls, 20 segments by default).",
         type: "integer",
         minimum: 1,
         maximum: 200,
@@ -281,13 +414,22 @@ export function createEarningsCallsHeadless(
       if (readsTranscript(args)) {
         return `Earnings Call Transcript | ${String(args.argument)} | ${String(args.options.quarter || "latest")}`;
       }
-      return args.argument ? `Earnings Calls | ${String(args.argument)}` : "Earnings Calls";
+      if (args.argument) return `Earnings Calls | ${String(args.argument)}`;
+      return String(args.options.view ?? "upcoming") === "transcripts" ? "Earnings Calls | Transcripts" : "Earnings Calls | Calendar";
     },
     async load(args, context) {
       const ticker = typeof args.argument === "string" ? args.argument : null;
+      const now = dependencies.now?.() ?? Date.now();
+      if (!ticker && String(args.options.view ?? "upcoming") !== "transcripts") {
+        const days = calendarDays(now);
+        const upcoming = await dependencies
+          .loadUpcoming({ from: days[0]!.from, to: days.at(-1)!.to }, context)
+          .catch(explainDenied(null, context));
+        return projectCalendar(upcoming, days, args, now);
+      }
       const calls = await dependencies.loadCalls(ticker, 200, context).catch(explainDenied(ticker, context));
       if (!ticker || !readsTranscript(args)) {
-        return projectEarningsCallsHeadless(calls, { ...args, options: { ...args.options, limit: args.options.limit ?? 50 } });
+        return projectEarningsCallsHeadless(calls, { ...args, options: { ...args.options, limit: args.options.limit ?? 50 } }, now);
       }
       const quarter = String(args.options.quarter || "latest");
       const selected = findCallForQuarter(calls.calls, quarter);

package/src/plugins/builtin/earnings-calls/index.tsx

@@ -6,7 +6,7 @@ import { callsLockNote } from "./lock-note";
 
 
 const description =
-  "Pro earnings call transcripts with speaker attribution, analyst Q&A, and extracted guidance. Alone, every transcribed call; with a ticker, that company's calls.";
+  "Pro earnings call transcripts with speaker attribution, analyst Q&A, and extracted guidance. Alone, the calendar of upcoming calls this week; with a ticker, that company's calls, its next one first.";
 
 function explicitSymbol(options?: { arg?: string; symbol?: string | null }): string | null {
   const symbol = (options?.symbol ?? options?.arg ?? "").trim().toUpperCase();
@@ -63,8 +63,8 @@ export const earningsCallsModule: PluginModule = {
         "qa",
         "ect",
       ],
-      // The ticker is optional on purpose: CALLS alone browses every call,
-      // and it must not silently bind to whatever ticker happens to be active.
+      // The ticker is optional on purpose: CALLS alone is the calendar of every
+      // company's calls, and it must not silently bind to whatever ticker happens to be active.
       shortcut: { prefix: "CALLS", argPlaceholder: "ticker", argKind: "ticker", argOptional: true },
       headless: earningsCallsHeadless,
       createInstance: (_context, options) => {

package/src/plugins/builtin/earnings-calls/lock-note.ts

@@ -3,7 +3,7 @@ import { resolveHeadlessInstrument } from "../shared/headless-market-data";
 import { proLockNote, type FreeRoute } from "../shared/pro-lock-note";
 
 const EVENTS_ROUTE: FreeRoute = {
-  text: (ticker, company) => `gloomberb events ${ticker} lists ${company}'s earnings dates, with the EPS reported at each and the next estimate.`,
+  text: (ticker, company) => `gloom events ${ticker} lists ${company}'s earnings dates, with the EPS reported at each and the next estimate.`,
   answers: async (symbol, context) => {
     const { symbol: ticker, exchange } = await resolveHeadlessInstrument(context, symbol);
     return ((await context.marketData.getCorporateActions?.(ticker, exchange))?.earnings.length ?? 0) > 0;