gloomberb 0.12.0 → 0.13.2

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

@@ -4,7 +4,12 @@ import {
   type CloudEarningsTranscriptPayload,
 } from "../../../api-client";
 import { ApiRequestError } from "../../../api-client/errors";
-import type { PluginPersistence } from "../../../types/plugin";
+import type { HeadlessPaneApiClient, PluginPersistence } from "../../../types/plugin";
+
+type EarningsCallsApiClient = Pick<
+  HeadlessPaneApiClient,
+  "getCloudEarningsCalls" | "getCloudEarningsTranscript"
+>;
 
 const LIST_KIND = "calls";
 const TRANSCRIPT_KIND = "transcript";
@@ -83,7 +88,8 @@ function listKey(ticker: string | null): string {
   return ticker ? ticker.toUpperCase() : "__all__";
 }
 
-export async function loadEarningsCalls(
+export async function loadEarningsCallsWithClient(
+  client: EarningsCallsApiClient,
   ticker: string | null,
   options?: { force?: boolean; limit?: number },
 ): Promise<EarningsCallsResult> {
@@ -101,7 +107,7 @@ export async function loadEarningsCalls(
   const active = activeListFetches.get(key);
   if (active && !force) return active;
 
-  const request = apiClient
+  const request = client
     .getCloudEarningsCalls({
       ticker: ticker ?? undefined,
       limit: options?.limit ?? 50,
@@ -155,6 +161,13 @@ export async function loadEarningsCalls(
   return request;
 }
 
+export function loadEarningsCalls(
+  ticker: string | null,
+  options?: { force?: boolean; limit?: number },
+): Promise<EarningsCallsResult> {
+  return loadEarningsCallsWithClient(apiClient, ticker, options);
+}
+
 /**
  * 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
@@ -163,12 +176,13 @@ export async function loadEarningsCalls(
 export function isPendingTranscript(
   value: CloudEarningsTranscriptPayload | { status?: string } | null,
 ): boolean {
-  if (!value) return false
-  const record = value as { status?: string; turns?: unknown }
-  return record.status === "pending" || !Array.isArray(record.turns)
+  if (!value) return false;
+  const record = value as { status?: string; turns?: unknown };
+  return record.status === "pending" || !Array.isArray(record.turns);
 }
 
-export async function loadTranscript(
+export async function loadTranscriptWithClient(
+  client: EarningsCallsApiClient,
   callId: string,
   options?: { force?: boolean },
 ): Promise<CloudEarningsTranscriptPayload> {
@@ -184,7 +198,7 @@ export async function loadTranscript(
   const active = activeTranscriptFetches.get(callId);
   if (active && !force) return active;
 
-  const request = apiClient
+  const request = client
     .getCloudEarningsTranscript(callId)
     .then((transcript) => {
       if (isPendingTranscript(transcript)) return transcript;
@@ -221,3 +235,10 @@ export async function loadTranscript(
   activeTranscriptFetches.set(callId, request);
   return request;
 }
+
+export function loadTranscript(
+  callId: string,
+  options?: { force?: boolean },
+): Promise<CloudEarningsTranscriptPayload> {
+  return loadTranscriptWithClient(apiClient, callId, options);
+}

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

@@ -0,0 +1,192 @@
+import { describe, expect, test } from "bun:test";
+import type {
+  CloudEarningsCallPayload,
+  CloudEarningsTranscriptPayload,
+} from "../../../api-client";
+import type { HeadlessPaneContext, HeadlessPaneLoadArgs } from "../../../types/plugin";
+import {
+  createEarningsCallsHeadless,
+  createEarningsTranscriptHeadless,
+  type EarningsCallsHeadlessDependencies,
+} from "./headless";
+
+const calls: CloudEarningsCallPayload[] = [
+  {
+    id: "amd-fq2-2026",
+    ticker: "AMD",
+    companyName: "Advanced Micro Devices",
+    fiscalYear: 2026,
+    fiscalQuarter: 2,
+    callAt: "2026-07-29T21:00:00.000Z",
+    status: "published",
+    durationSeconds: 3_600,
+    wordCount: 12_000,
+    hasTranscript: true,
+    sentiment: 0.2,
+  },
+  {
+    id: "amd-fq1-2026",
+    ticker: "AMD",
+    companyName: "Advanced Micro Devices",
+    fiscalYear: 2026,
+    fiscalQuarter: 1,
+    callAt: "2026-04-29T21:00:00.000Z",
+    status: "discovered",
+    durationSeconds: null,
+    wordCount: null,
+    hasTranscript: false,
+    sentiment: null,
+  },
+];
+
+const transcript: CloudEarningsTranscriptPayload = {
+  id: "amd-fq2-2026",
+  ticker: "AMD",
+  companyName: "Advanced Micro Devices",
+  fiscalYear: 2026,
+  fiscalQuarter: 2,
+  callAt: "2026-07-29T21:00:00.000Z",
+  timing: "AMC",
+  webcastUrl: "https://example.com/call",
+  durationSeconds: 3_600,
+  status: "published",
+  fullText: "",
+  turns: [
+    {
+      speaker: "Jean Hu",
+      role: "Chief Financial Officer",
+      company: "AMD",
+      text: `Gross margin expanded. ${"Margin discipline remained strong. ".repeat(80)}`,
+      isQa: false,
+      startSeconds: 120,
+    },
+    {
+      speaker: "Analyst One",
+      role: "Analyst",
+      company: "Research Firm",
+      text: "What should investors expect from the CFO on data center margins?",
+      isQa: true,
+      startSeconds: 2_400,
+    },
+  ],
+  participants: [
+    { name: "Jean Hu", role: "Chief Financial Officer", company: "AMD" },
+  ],
+  summary: "Revenue grew while gross margin expanded.",
+  guidance: "Management expects sequential growth.",
+  riskFactors: "Supply remains constrained.",
+  analystFocus: "Analysts focused on data center margins.",
+  notable: "Management raised its annual outlook.",
+  sentiment: 0.2,
+  sentimentRationale: "Constructive outlook.",
+  qaStartTurn: 1,
+  wordCount: 12_000,
+  asrModel: "test",
+  updatedAt: "2026-07-30T00:00:00.000Z",
+};
+
+function callArgs(options: Record<string, string | number | boolean>): HeadlessPaneLoadArgs {
+  return {
+    rawArgument: "",
+    argument: null,
+    symbols: [],
+    options,
+  };
+}
+
+function transcriptArgs(options: Record<string, string | number | boolean>): HeadlessPaneLoadArgs {
+  return {
+    rawArgument: "AMD",
+    argument: "AMD",
+    symbols: ["AMD"],
+    options,
+  };
+}
+
+function dependencies(): EarningsCallsHeadlessDependencies {
+  return {
+    loadCalls: async () => ({
+      calls,
+      fetchedAt: 123,
+      stale: false,
+    }),
+    loadTranscript: async () => transcript,
+  };
+}
+
+const context = {} as HeadlessPaneContext;
+
+describe("earnings calls headless", () => {
+  test("maps call shelf rows and applies availability", async () => {
+    const definition = createEarningsCallsHeadless(dependencies());
+
+    const result = await definition.load(
+      callArgs({ availability: "pending", limit: 1 }),
+      context,
+    );
+
+    expect(result.rows).toEqual([
+      expect.objectContaining({
+        id: "amd-fq1-2026",
+        ticker: "AMD",
+        status: "queued",
+        hasTranscript: false,
+      }),
+    ]);
+    expect(result.metadata).toMatchObject({ availability: "pending", returned: 1 });
+  });
+});
+
+describe("earnings transcript headless", () => {
+  test("selects a quarter and filters speakers by role acronym", async () => {
+    const definition = createEarningsTranscriptHeadless(dependencies());
+
+    const result = await definition.load(transcriptArgs({
+      section: "transcript",
+      quarter: "FQ2-2026",
+      speaker: "CFO",
+      search: "margin",
+      offset: 0,
+      limit: 20,
+    }), context);
+
+    expect(result.rows.length).toBeGreaterThan(0);
+    expect(result.rows.every((row) => row.speaker === "Jean Hu")).toBe(true);
+    expect(result.metadata).toMatchObject({
+      fiscalYear: 2026,
+      fiscalQuarter: 2,
+      section: "transcript",
+      speaker: "CFO",
+    });
+  });
+
+  test("pages bounded transcript segments and reports truncation", async () => {
+    const definition = createEarningsTranscriptHeadless(dependencies());
+    const first = await definition.load(transcriptArgs({
+      section: "transcript",
+      quarter: "latest",
+      speaker: "CFO",
+      search: "",
+      offset: 0,
+      limit: 1,
+    }), context);
+    const second = await definition.load(transcriptArgs({
+      section: "transcript",
+      quarter: "latest",
+      speaker: "CFO",
+      search: "",
+      offset: 1,
+      limit: 1,
+    }), context);
+
+    expect(first.rows).toHaveLength(1);
+    expect(first.metadata).toMatchObject({
+      returnedSegments: 1,
+      truncated: true,
+      hasMore: true,
+      nextOffset: 1,
+    });
+    expect(second.rows).toHaveLength(1);
+    expect(second.rows[0]?.index).toBe(1);
+  });
+});

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

@@ -0,0 +1,300 @@
+import type {
+  CloudEarningsCallPayload,
+  CloudEarningsTranscriptPayload,
+} from "../../../api-client";
+import type {
+  HeadlessPaneContext,
+  HeadlessPaneDefinition,
+  HeadlessPaneLoadArgs,
+  HeadlessRowsResult,
+} from "../../../types/plugin";
+import {
+  callStatusLabel,
+  isPendingTranscript,
+  loadEarningsCallsWithClient,
+  loadTranscriptWithClient,
+  type EarningsCallsResult,
+} from "./data";
+import {
+  buildTranscriptSegments,
+  findCallForQuarter,
+  sortCallsNewest,
+  type TranscriptSection,
+} from "./model";
+
+const CALL_COLUMNS = [
+  { key: "ticker", header: "Ticker" },
+  { key: "company", header: "Company" },
+  { key: "callAt", header: "Call date" },
+  { key: "fiscalYear", header: "FY", align: "right" as const },
+  { key: "fiscalQuarter", header: "FQ", align: "right" as const },
+  { key: "status", header: "Status" },
+  { key: "durationSeconds", header: "Seconds", align: "right" as const },
+  { key: "wordCount", header: "Words", align: "right" as const },
+  { key: "sentiment", header: "Tone", align: "right" as const },
+];
+
+const TRANSCRIPT_COLUMNS = [
+  { key: "index", header: "#", align: "right" as const },
+  { key: "section", header: "Section" },
+  { key: "startSeconds", header: "Start", align: "right" as const },
+  { key: "speaker", header: "Speaker" },
+  { key: "role", header: "Role" },
+  { key: "isQa", header: "Q&A" },
+  { key: "text", header: "Text" },
+];
+
+export interface EarningsCallsHeadlessDependencies {
+  loadCalls(
+    ticker: string | null,
+    limit: number,
+    context: HeadlessPaneContext,
+  ): Promise<EarningsCallsResult>;
+  loadTranscript(
+    callId: string,
+    context: HeadlessPaneContext,
+  ): Promise<CloudEarningsTranscriptPayload>;
+}
+
+const defaultDependencies: EarningsCallsHeadlessDependencies = {
+  loadCalls: (ticker, limit, context) => loadEarningsCallsWithClient(
+    context.apiClient,
+    ticker,
+    { limit },
+  ),
+  loadTranscript: (callId, context) => loadTranscriptWithClient(context.apiClient, callId),
+};
+
+function callRow(call: CloudEarningsCallPayload) {
+  return {
+    id: call.id,
+    ticker: call.ticker,
+    company: call.companyName,
+    callAt: call.callAt,
+    fiscalYear: call.fiscalYear,
+    fiscalQuarter: call.fiscalQuarter,
+    status: call.hasTranscript ? "transcribed" : callStatusLabel(call) || call.status,
+    durationSeconds: call.durationSeconds,
+    wordCount: call.wordCount,
+    hasTranscript: call.hasTranscript,
+    sentiment: call.sentiment,
+    webcastUrl: call.webcastUrl ?? null,
+  };
+}
+
+function availabilityMatches(call: CloudEarningsCallPayload, availability: string): boolean {
+  if (availability === "all") return true;
+  return availability === "transcribed" ? call.hasTranscript : !call.hasTranscript;
+}
+
+export function projectEarningsCallsHeadless(
+  result: EarningsCallsResult,
+  args: HeadlessPaneLoadArgs,
+): 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);
+
+  return {
+    columns: CALL_COLUMNS,
+    rows,
+    errors: result.refreshError ? [result.refreshError] : undefined,
+    metadata: {
+      fetchedAt: result.fetchedAt,
+      stale: result.stale,
+      pending: result.pending ?? false,
+      unknownTicker: result.unknownTicker ?? false,
+      availability,
+      total: matching.length,
+      returned: rows.length,
+      truncated: rows.length < matching.length,
+    },
+  };
+}
+
+function selectedSection(args: HeadlessPaneLoadArgs): TranscriptSection {
+  return String(args.options.section ?? "overview") as TranscriptSection;
+}
+
+function transcriptResult(
+  transcript: CloudEarningsTranscriptPayload,
+  call: CloudEarningsCallPayload,
+  args: HeadlessPaneLoadArgs,
+): HeadlessRowsResult {
+  const section = selectedSection(args);
+  const speaker = String(args.options.speaker ?? "").trim();
+  const search = String(args.options.search ?? "").trim();
+  const offset = Number(args.options.offset ?? 0);
+  const limit = Number(args.options.limit ?? 20);
+  const segments = buildTranscriptSegments(transcript, section, { speaker, search });
+  const rows = segments.slice(offset, offset + limit).map((segment) => ({ ...segment }));
+  const hasMore = offset + rows.length < segments.length;
+
+  return {
+    columns: TRANSCRIPT_COLUMNS,
+    rows,
+    metadata: {
+      callId: call.id,
+      ticker: transcript.ticker,
+      company: transcript.companyName,
+      fiscalYear: transcript.fiscalYear,
+      fiscalQuarter: transcript.fiscalQuarter,
+      callAt: transcript.callAt,
+      durationSeconds: transcript.durationSeconds,
+      wordCount: transcript.wordCount,
+      sentiment: transcript.sentiment,
+      updatedAt: transcript.updatedAt,
+      section,
+      speaker: speaker || null,
+      search: search || null,
+      offset,
+      limit,
+      totalSegments: segments.length,
+      returnedSegments: rows.length,
+      truncated: offset > 0 || hasMore,
+      hasMore,
+      nextOffset: hasMore ? offset + rows.length : null,
+    },
+  };
+}
+
+function transcriptOptions() {
+  return [
+    {
+      key: "section",
+      description: "Transcript section to return.",
+      type: "enum" as const,
+      values: [
+        { value: "overview" },
+        { value: "summary" },
+        { value: "transcript" },
+        { value: "qa", aliases: ["q&a"] },
+        { value: "guidance" },
+        { value: "risks" },
+        { value: "notable" },
+        { value: "analyst-focus", aliases: ["analyst"] },
+        { value: "participants", aliases: ["speakers"] },
+      ],
+      defaultValue: "overview",
+    },
+    {
+      key: "quarter",
+      description: "Fiscal quarter such as latest, FQ2-2026, or FY2026.",
+      type: "string" as const,
+      defaultValue: "latest",
+    },
+    {
+      key: "speaker",
+      description: "Speaker name, role, or role acronym such as CFO.",
+      type: "string" as const,
+      defaultValue: "",
+    },
+    {
+      key: "search",
+      description: "Text to find in transcript turns.",
+      type: "string" as const,
+      defaultValue: "",
+    },
+    {
+      key: "offset",
+      description: "Transcript segment offset for paging.",
+      type: "integer" as const,
+      defaultValue: 0,
+      minimum: 0,
+      maximum: 100_000,
+    },
+    {
+      key: "limit",
+      description: "Maximum transcript segments to return.",
+      type: "integer" as const,
+      defaultValue: 20,
+      minimum: 1,
+      maximum: 200,
+    },
+  ];
+}
+
+export function createEarningsCallsHeadless(
+  dependencies: EarningsCallsHeadlessDependencies = defaultDependencies,
+): HeadlessPaneDefinition<"rows"> {
+  return {
+    shape: "rows",
+    argument: {
+      kind: "ticker",
+      placeholder: "ticker",
+      description: "Optional company symbol. Omit it to browse all calls.",
+      optional: true,
+    },
+    options: [
+      {
+        key: "availability",
+        description: "Transcript availability to include.",
+        type: "enum",
+        values: [
+          { value: "all" },
+          { value: "transcribed" },
+          { value: "pending" },
+        ],
+        defaultValue: "all",
+      },
+      {
+        key: "limit",
+        description: "Maximum calls to return.",
+        type: "integer",
+        defaultValue: 50,
+        minimum: 1,
+        maximum: 200,
+      },
+    ],
+    columns: CALL_COLUMNS,
+    describe: (args) => args.argument
+      ? `Earnings Calls | ${String(args.argument)}`
+      : "Earnings Calls",
+    async load(args, context) {
+      const ticker = typeof args.argument === "string" ? args.argument : null;
+      return projectEarningsCallsHeadless(
+        await dependencies.loadCalls(ticker, 200, context),
+        args,
+      );
+    },
+  };
+}
+
+export function createEarningsTranscriptHeadless(
+  dependencies: EarningsCallsHeadlessDependencies = defaultDependencies,
+): HeadlessPaneDefinition<"rows"> {
+  return {
+    shape: "rows",
+    argument: {
+      kind: "ticker",
+      placeholder: "ticker",
+      description: "Company symbol.",
+    },
+    options: transcriptOptions(),
+    columns: TRANSCRIPT_COLUMNS,
+    describe: (args) => (
+      `Earnings Call Transcript | ${String(args.argument)} | ${String(args.options.quarter)}`
+    ),
+    async load(args, context) {
+      const ticker = String(args.argument);
+      const calls = await dependencies.loadCalls(ticker, 200, context);
+      const quarter = String(args.options.quarter ?? "latest");
+      const selected = findCallForQuarter(calls.calls, quarter);
+      if (!selected) {
+        if (calls.unknownTicker) throw new Error(`${ticker} is not a known listed company.`);
+        if (calls.pending) throw new Error(`Earnings call discovery for ${ticker} is still pending.`);
+        throw new Error(`No ${quarter} earnings call found for ${ticker}.`);
+      }
+      const transcript = await dependencies.loadTranscript(selected.id, context);
+      if (isPendingTranscript(transcript)) {
+        throw new Error(`Transcript for ${ticker} ${quarter} is still being produced.`);
+      }
+      return transcriptResult(transcript, selected, args);
+    },
+  };
+}
+
+export const earningsCallsHeadless = createEarningsCallsHeadless();
+export const earningsTranscriptHeadless = createEarningsTranscriptHeadless();

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

@@ -2,6 +2,12 @@ import type { PluginModule } from "../plugin-module";
 import { createTickerSurfacePaneTemplate } from "../shared/ticker-surface";
 import { attachEarningsCallsPersistence, resetEarningsCallsPersistence } from "./data";
 import { EarningsCallsPane, EARNINGS_CALLS_PANE_ID } from "./pane";
+import {
+  earningsCallsHeadless,
+  earningsTranscriptHeadless,
+} from "./headless";
+
+export { earningsCallsHeadless, earningsTranscriptHeadless } from "./headless";
 
 const description =
   "Earnings call transcripts with speaker attribution, analyst Q&A, and extracted guidance.";
@@ -54,16 +60,20 @@ export const earningsCallsModule: PluginModule = {
         "qa",
       ],
       shortcut: { prefix: "CALLS" },
+      headless: earningsCallsHeadless,
       createInstance: () => ({ placement: "floating" }),
     },
-    createTickerSurfacePaneTemplate({
-      id: "earnings-call-transcripts-pane",
-      paneId: EARNINGS_CALLS_PANE_ID,
-      label: "Earnings Call Transcripts",
-      description,
-      keywords: ["earnings", "call", "transcript", "ect", "qa", "guidance"],
-      shortcut: "ECT",
-      publicShare: false,
-    }),
+    {
+      ...createTickerSurfacePaneTemplate({
+        id: "earnings-call-transcripts-pane",
+        paneId: EARNINGS_CALLS_PANE_ID,
+        label: "Earnings Call Transcripts",
+        description,
+        keywords: ["earnings", "call", "transcript", "ect", "qa", "guidance"],
+        shortcut: "ECT",
+        publicShare: false,
+      }),
+      headless: earningsTranscriptHeadless,
+    },
   ],
 };