gloomberb 0.12.0 → 0.13.2

package/src/plugins/builtin/holders/headless.ts

@@ -0,0 +1,162 @@
+import type {
+  HeadlessPaneColumn,
+  HeadlessPaneContext,
+  HeadlessPaneDefinition,
+  HeadlessPaneLoadArgs,
+} from "../../../types/plugin";
+import { formatCompact } from "../../../utils/format";
+import { loadHolderSnapshot } from "./client";
+import {
+  displayDate,
+  formatHolderOwnershipPercent,
+  formatMaybePercent,
+  formatMoneyCompact,
+  formatSignedCompact,
+  resolveHolderOwnershipPercent,
+} from "./format";
+import { buildRows, sortRows } from "./table-model";
+import type { HolderData } from "../../../types/financials";
+import type { HolderColumnId } from "./types";
+
+const HOLDER_COLUMNS: HeadlessPaneColumn[] = [
+  { key: "name", header: "Holder" },
+  { key: "ownerType", header: "Type" },
+  {
+    key: "value",
+    header: "Value",
+    align: "right",
+    format: (value, row) => formatMoneyCompact(
+      value == null ? undefined : Number(value),
+      String(row.currency ?? "USD"),
+    ),
+  },
+  {
+    key: "shares",
+    header: "Amount",
+    align: "right",
+    format: (value) => value == null ? "-" : formatCompact(Number(value)),
+  },
+  {
+    key: "changeShares",
+    header: "Chg",
+    align: "right",
+    format: (value) => formatSignedCompact(value == null ? undefined : Number(value)),
+  },
+  {
+    key: "changePercent",
+    header: "Chg%",
+    align: "right",
+    format: (value) => formatMaybePercent(value == null ? undefined : Number(value)),
+  },
+  {
+    key: "percentHeld",
+    header: "Held",
+    align: "right",
+    format: (value) => formatHolderOwnershipPercent(value == null ? undefined : Number(value)),
+  },
+  {
+    key: "reportDate",
+    header: "Date",
+    format: (value) => displayDate(typeof value === "string" ? value : undefined),
+  },
+];
+
+const SORT_COLUMNS: Record<string, HolderColumnId> = {
+  holder: "holder",
+  value: "value",
+  shares: "shares",
+  change: "changeShares",
+  "change-percent": "changePercent",
+  held: "percentHeld",
+  date: "reportDate",
+};
+
+interface HolderSnapshot {
+  data: HolderData;
+  marketCap?: number;
+}
+
+export interface HoldersHeadlessDependencies {
+  loadSnapshot(
+    symbol: string,
+    args: HeadlessPaneLoadArgs,
+    ctx: HeadlessPaneContext,
+  ): Promise<HolderSnapshot>;
+}
+
+const defaultDependencies: HoldersHeadlessDependencies = {
+  loadSnapshot: (symbol, _args, ctx) => loadHolderSnapshot(ctx.marketData, symbol),
+};
+
+export function createHoldersHeadless(
+  dependencies: HoldersHeadlessDependencies = defaultDependencies,
+): HeadlessPaneDefinition<"rows"> {
+  return {
+    shape: "rows",
+    argument: {
+      kind: "ticker",
+      placeholder: "ticker",
+      description: "Ticker whose institutional holders should be loaded.",
+    },
+    options: [
+      {
+        key: "sort",
+        description: "Column used to sort holder rows.",
+        type: "enum",
+        values: Object.keys(SORT_COLUMNS).map((value) => ({ value })),
+        defaultValue: "value",
+      },
+      {
+        key: "order",
+        description: "Sort direction.",
+        type: "enum",
+        values: [{ value: "desc" }, { value: "asc" }],
+        defaultValue: "desc",
+      },
+      {
+        key: "limit",
+        aliases: ["count", "rows"],
+        description: "Maximum holder rows.",
+        type: "integer",
+        defaultValue: 25,
+        minimum: 1,
+        maximum: 200,
+      },
+    ],
+    columns: HOLDER_COLUMNS,
+    describe: (args) => `Holders | ${args.symbols[0]}`,
+    async load(args, ctx) {
+      const symbol = args.symbols[0]!;
+      const { data, marketCap } = await dependencies.loadSnapshot(symbol, args, ctx);
+      const currency = data.currency ?? "USD";
+      const rows = sortRows(buildRows(data), {
+        columnId: SORT_COLUMNS[String(args.options.sort)] ?? "value",
+        direction: args.options.order === "asc" ? "asc" : "desc",
+      }, marketCap)
+        .slice(0, Number(args.options.limit))
+        .map((row) => ({
+          name: row.name,
+          ownerType: row.ownerType,
+          value: row.value ?? null,
+          shares: row.shares ?? null,
+          changeShares: row.changeShares ?? null,
+          changePercent: row.changePercent ?? null,
+          percentHeld: resolveHolderOwnershipPercent(row, marketCap) ?? null,
+          reportDate: row.reportDate ?? null,
+          currency,
+        }));
+      return {
+        rows,
+        metadata: {
+          symbol: data.symbol || symbol,
+          name: data.name ?? null,
+          currency,
+          asOf: data.asOf ?? null,
+          summary: data.summary ?? null,
+        },
+      };
+    },
+  };
+}
+
+export const holdersHeadless = createHoldersHeadless();

package/src/plugins/builtin/holders/index.tsx

@@ -1,7 +1,10 @@
 import type { PluginModule } from "../plugin-module";
 import { createTickerSurfacePaneTemplate } from "../shared/ticker-surface";
+import { holdersHeadless } from "./headless";
 import { HoldersView } from "./pane";
 
+export { holdersHeadless } from "./headless";
+
 export const holdersModule: PluginModule = {
   setup(ctx) {
     ctx.registerTickerResearchTab({
@@ -27,13 +30,16 @@ export const holdersModule: PluginModule = {
   ],
 
   paneTemplates: [
-    createTickerSurfacePaneTemplate({
-      id: "holders-pane",
-      paneId: "holders",
-      label: "Holders",
-      description: "Institutional holders for the selected ticker.",
-      keywords: ["holders", "ownership", "institutional", "owners", "hds"],
-      shortcut: "HDS",
-    }),
+    {
+      ...createTickerSurfacePaneTemplate({
+        id: "holders-pane",
+        paneId: "holders",
+        label: "Holders",
+        description: "Institutional holders for the selected ticker.",
+        keywords: ["holders", "ownership", "institutional", "owners", "hds"],
+        shortcut: "HDS",
+      }),
+      headless: holdersHeadless,
+    },
   ],
 };

package/src/plugins/builtin/holders/pane.tsx

@@ -31,6 +31,7 @@ import {
   sortRows,
   VIEW_TABS,
 } from "./table-model";
+import { loadHolderData } from "./client";
 import { HoldersTreemap } from "./treemap";
 import type { HolderColumn, HolderRow, SortPreference, ViewMode } from "./types";
 import { loadHolder13FMatches, type Holder13FMatch } from "./thirteenf-match";
@@ -77,7 +78,12 @@ export function HoldersView({ focused, width, height }: { focused: boolean; widt
     setError(null);
 
     try {
-      const nextData = await dataProvider.getHolders(symbol, exchange, forceRefresh ? { cacheMode: "refresh" } : undefined);
+      const nextData = await loadHolderData(
+        dataProvider,
+        symbol,
+        exchange,
+        forceRefresh ? { cacheMode: "refresh" } : undefined,
+      );
       if (fetchGenRef.current !== gen) return;
       setData(nextData);
       setSelectedId(null);

package/src/plugins/builtin/insider/client.ts

@@ -0,0 +1,50 @@
+import type { DataProvider, SecFilingItem } from "../../../types/data-provider";
+import { parseForm4Xml } from "./insider-data";
+import type { ParsedInsiderFiling } from "./model";
+
+export async function loadInsiderFilings(
+  provider: DataProvider,
+  symbol: string,
+  count: number,
+  exchange = "",
+): Promise<SecFilingItem[]> {
+  if (!provider.getSecFilings) throw new Error("Insider filing data unavailable");
+  const filings = await provider.getSecFilings(symbol, count, exchange);
+  return filings.filter((filing) => filing.form.trim() === "4");
+}
+
+function throwIfAborted(signal: AbortSignal | undefined): void {
+  if (!signal?.aborted) return;
+  throw signal.reason instanceof Error ? signal.reason : new Error("Insider filing load was aborted.");
+}
+
+export async function loadParsedInsiderFilings(
+  provider: DataProvider,
+  symbol: string,
+  options: { limit: number; exchange?: string; signal?: AbortSignal },
+): Promise<ParsedInsiderFiling[]> {
+  if (!provider.getSecFilingContent) throw new Error("Insider filing content unavailable");
+  const filings = (await loadInsiderFilings(
+    provider,
+    symbol,
+    20_000,
+    options.exchange,
+  )).slice(0, options.limit);
+
+  const parsed: ParsedInsiderFiling[] = [];
+  for (const filing of filings) {
+    throwIfAborted(options.signal);
+    try {
+      const content = await provider.getSecFilingContent(filing);
+      parsed.push({
+        filing,
+        transaction: content ? parseForm4Xml(content) : null,
+        isLoading: false,
+      });
+    } catch {
+      throwIfAborted(options.signal);
+      parsed.push({ filing, transaction: null, isLoading: false });
+    }
+  }
+  return parsed;
+}

package/src/plugins/builtin/insider/headless.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, test } from "bun:test";
+import { createTestDataProvider } from "../../../test-support/data-provider";
+import { createDefaultConfig } from "../../../types/config";
+import type { HeadlessPaneContext, HeadlessPaneLoadArgs } from "../../../types/plugin";
+import { loadParsedInsiderFilings } from "./client";
+import { createInsiderHeadless } from "./headless";
+import type { ParsedInsiderFiling } from "./model";
+
+const parsed: ParsedInsiderFiling[] = [
+  {
+    filing: {
+      accessionNumber: "one",
+      form: "4",
+      filingDate: new Date("2026-08-26T00:00:00.000Z"),
+      cik: "0000002488",
+      filingUrl: "https://www.sec.gov/one",
+    },
+    transaction: {
+      filingDate: new Date("2026-08-25T00:00:00.000Z"),
+      reportedName: "SU LISA T",
+      title: "Chief Executive Officer",
+      transactionType: "P",
+      shares: 25_000,
+      pricePerShare: 150,
+      totalValue: 3_750_000,
+      sharesOwned: 4_000_000,
+      form: "4",
+    },
+    isLoading: false,
+  },
+  {
+    filing: {
+      accessionNumber: "two",
+      form: "4",
+      filingDate: new Date("2026-08-24T00:00:00.000Z"),
+      cik: "0000002488",
+      filingUrl: "https://www.sec.gov/two",
+    },
+    transaction: {
+      filingDate: new Date("2026-08-23T00:00:00.000Z"),
+      reportedName: "OTHER OFFICER",
+      title: "Officer",
+      transactionType: "S",
+      shares: 1_000,
+      pricePerShare: 155,
+      totalValue: 155_000,
+      sharesOwned: 20_000,
+      form: "4",
+    },
+    isLoading: false,
+  },
+];
+
+function context(): HeadlessPaneContext {
+  return {
+    marketData: createTestDataProvider(),
+    apiClient: {} as HeadlessPaneContext["apiClient"],
+    config: createDefaultConfig("/tmp/gloomberb-headless-insider"),
+    signal: new AbortController().signal,
+  };
+}
+
+function args(name = "", limit = 20): HeadlessPaneLoadArgs {
+  return {
+    rawArgument: "AMD",
+    argument: "AMD",
+    symbols: ["AMD"],
+    options: { name, limit },
+  };
+}
+
+describe("insider client", () => {
+  test("scans Form 4 filings and loads their content sequentially", async () => {
+    let activeContentLoads = 0;
+    let maxActiveContentLoads = 0;
+    const filingRequests: Array<{ symbol: string; count: number; exchange: string | undefined }> = [];
+    const provider = createTestDataProvider({
+      getSecFilings: async (symbol, count, exchange) => {
+        filingRequests.push({ symbol, count, exchange });
+        return parsed.map(({ filing }) => filing);
+      },
+      getSecFilingContent: async () => {
+        activeContentLoads += 1;
+        maxActiveContentLoads = Math.max(maxActiveContentLoads, activeContentLoads);
+        await Bun.sleep(1);
+        activeContentLoads -= 1;
+        return null;
+      },
+    });
+
+    const result = await loadParsedInsiderFilings(provider, "NVDA", { limit: 2 });
+
+    expect(filingRequests).toEqual([{ symbol: "NVDA", count: 20_000, exchange: "" }]);
+    expect(result).toHaveLength(2);
+    expect(maxActiveContentLoads).toBe(1);
+  });
+});
+
+describe("insider headless model", () => {
+  test("projects parsed Form 4 values and applies the owner filter", async () => {
+    const requestedLimits: number[] = [];
+    const headless = createInsiderHeadless({
+      loadParsed: async (_symbol, limit) => {
+        requestedLimits.push(limit);
+        return parsed.slice(0, limit);
+      },
+    });
+
+    const all = await headless.load(args("", 2), context());
+    expect(all.rows[0]).toMatchObject({
+      insider: "SU LISA T",
+      side: "BUY",
+      shares: 25_000,
+      totalValue: 3_750_000,
+    });
+
+    const filtered = await headless.load(args("other officer", 2), context());
+    expect(filtered.rows).toHaveLength(1);
+    expect(filtered.rows[0]).toMatchObject({ insider: "OTHER OFFICER", side: "SELL" });
+    expect(requestedLimits).toEqual([2, 2]);
+  });
+});

package/src/plugins/builtin/insider/headless.ts

@@ -0,0 +1,117 @@
+import type {
+  HeadlessPaneColumn,
+  HeadlessPaneContext,
+  HeadlessPaneDefinition,
+  HeadlessPaneLoadArgs,
+} from "../../../types/plugin";
+import { formatCompact, formatCurrency } from "../../../utils/format";
+import { loadParsedInsiderFilings } from "./client";
+import {
+  buildInsiderRows,
+  buildInsiderSummary,
+  type ParsedInsiderFiling,
+} from "./model";
+
+const INSIDER_COLUMNS: HeadlessPaneColumn[] = [
+  {
+    key: "filingDate",
+    header: "Filed",
+    format: (value) => typeof value === "string" ? value.slice(0, 10) : "-",
+  },
+  {
+    key: "transactionDate",
+    header: "Tx",
+    format: (value) => typeof value === "string" ? value.slice(0, 10) : "-",
+  },
+  { key: "insider", header: "Insider" },
+  { key: "title", header: "Title" },
+  { key: "side", header: "Side" },
+  {
+    key: "shares",
+    header: "Shares",
+    align: "right",
+    format: (value) => value == null ? "-" : formatCompact(Number(value)),
+  },
+  {
+    key: "pricePerShare",
+    header: "Price",
+    align: "right",
+    format: (value) => value == null ? "-" : formatCurrency(Number(value)),
+  },
+  {
+    key: "totalValue",
+    header: "Value",
+    align: "right",
+    format: (value) => value == null ? "-" : formatCurrency(Number(value)),
+  },
+];
+
+export interface InsiderHeadlessDependencies {
+  loadParsed(
+    symbol: string,
+    limit: number,
+    args: HeadlessPaneLoadArgs,
+    ctx: HeadlessPaneContext,
+  ): Promise<ParsedInsiderFiling[]>;
+}
+
+const defaultDependencies: InsiderHeadlessDependencies = {
+  loadParsed: (symbol, limit, _args, ctx) => loadParsedInsiderFilings(ctx.marketData, symbol, {
+    limit,
+    signal: ctx.signal,
+  }),
+};
+
+export function createInsiderHeadless(
+  dependencies: InsiderHeadlessDependencies = defaultDependencies,
+): HeadlessPaneDefinition<"rows"> {
+  return {
+    shape: "rows",
+    argument: {
+      kind: "ticker",
+      placeholder: "ticker",
+      description: "US equity ticker.",
+    },
+    options: [
+      {
+        key: "name",
+        description: "Exact reporting owner name.",
+        type: "string",
+        defaultValue: "",
+        pluginState: { pluginId: "ticker-research", key: "nameFilter" },
+      },
+      {
+        key: "limit",
+        aliases: ["count", "rows"],
+        description: "Maximum Form 4 filings to parse.",
+        type: "integer",
+        defaultValue: 20,
+        minimum: 1,
+        maximum: 100,
+      },
+    ],
+    columns: INSIDER_COLUMNS,
+    describe: (args) => `Insider Transactions | ${args.symbols[0]}`,
+    async load(args, ctx) {
+      const symbol = args.symbols[0]!;
+      const limit = Number(args.options.limit);
+      const parsed = await dependencies.loadParsed(symbol, limit, args, ctx);
+      const name = String(args.options.name ?? "").trim().toLocaleLowerCase();
+      const filtered = name
+        ? parsed.filter(({ transaction }) => transaction?.reportedName.toLocaleLowerCase() === name)
+        : parsed;
+      return {
+        rows: buildInsiderRows(filtered),
+        metadata: {
+          symbol,
+          summary: buildInsiderSummary(parsed),
+          parsed: parsed.filter(({ transaction }) => transaction != null).length,
+          requested: limit,
+          name: name || null,
+        },
+      };
+    },
+  };
+}
+
+export const insiderHeadless = createInsiderHeadless();

package/src/plugins/builtin/insider/index.tsx

@@ -1,6 +1,5 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import type { PluginModule } from "../plugin-module";
-import type { SecFilingItem } from "../../../types/data-provider";
 import {
   useResolvedEntryValue,
   useSecFilingsQuery,
@@ -11,9 +10,8 @@ import type { ScrollBoxRenderable } from "../../../ui";
 import { EmptyState, FeedDataTableStackView, Spinner, useExternalLinkFooter, useTableLoadMore, type FeedDataTableItem } from "../../../components";
 import { usePluginPaneState } from "../../runtime";
 import { isUsEquityTicker } from "../../../utils/sec";
-import { formatCompact, formatCurrency } from "../../../utils/format";
 import { truncateWithEllipsis as truncateText } from "../../../utils/text-wrap";
-import { parseForm4Xml, type InsiderTransaction } from "./insider-data";
+import { parseForm4Xml } from "./insider-data";
 import { createTickerSurfacePaneTemplate } from "../shared/ticker-surface";
 import {
   buildInsiderTransactionDetailBody,
@@ -23,48 +21,18 @@ import {
   renderFilingNotice,
 } from "../sec/filing-display";
 import { useSecFilingContentCache } from "../sec/filing-content";
+import {
+  buildInsiderSummary,
+  type ParsedInsiderFiling as ParsedFiling,
+} from "./model";
+import { insiderHeadless } from "./headless";
+
+export { insiderHeadless } from "./headless";
 
 const FORM4_PAGE_SIZE = 20;
 // Recent EDGAR dumps cap at 1,000 mixed forms. Older archives are fetched
 // until this many filings or company history ends.
 const SEC_FILING_SCAN_LIMIT = 20_000;
-const NINETY_DAYS_MS = 90 * 24 * 60 * 60 * 1000;
-
-interface ParsedFiling {
-  filing: SecFilingItem;
-  transaction: InsiderTransaction | null;
-  isLoading: boolean;
-}
-
-/** Null while filings are still parsing, so the pane never claims "no activity" early. */
-function buildSummary(parsed: ParsedFiling[]): string | null {
-  if (parsed.some(({ isLoading }) => isLoading)) return null;
-  const cutoff = new Date(Date.now() - NINETY_DAYS_MS);
-  let buyShares = 0;
-  let sellShares = 0;
-  let buyValue = 0;
-  let sellValue = 0;
-
-  for (const { transaction } of parsed) {
-    if (!transaction) continue;
-    const txDate = transaction.filingDate instanceof Date ? transaction.filingDate : new Date(transaction.filingDate);
-    if (isNaN(txDate.getTime()) || txDate < cutoff) continue;
-    if (transaction.transactionType === "P") {
-      buyShares += transaction.shares;
-      buyValue += transaction.totalValue ?? 0;
-    } else if (transaction.transactionType === "S") {
-      sellShares += transaction.shares;
-      sellValue += transaction.totalValue ?? 0;
-    }
-  }
-
-  if (buyShares === 0 && sellShares === 0) return "No buy/sell activity in last 90 days.";
-
-  const parts: string[] = [];
-  if (buyShares > 0) parts.push(`Bought ${formatCompact(buyShares)} shares (${formatCurrency(buyValue)})`);
-  if (sellShares > 0) parts.push(`Sold ${formatCompact(sellShares)} shares (${formatCurrency(sellValue)})`);
-  return parts.join("  |  ");
-}
 
 function toFeedItems(parsed: ParsedFiling[]): FeedDataTableItem[] {
   return parsed.map(({ filing, transaction, isLoading }) => {
@@ -165,7 +133,7 @@ function InsiderView({ width, height, focused }: { width: number; height: number
       : allParsed
   ), [allParsed, nameFilter]);
   const feedItems = useMemo(() => toFeedItems(parsed), [parsed]);
-  const summary = useMemo(() => buildSummary(allParsed), [allParsed]);
+  const summary = useMemo(() => buildInsiderSummary(allParsed), [allParsed]);
   const selectedTransaction = parsed[selectedIdx]?.transaction ?? null;
   const openFiling = openItemId
     ? parsed.find(({ filing }) => filing.accessionNumber === openItemId)?.filing ?? null
@@ -271,15 +239,18 @@ export const insiderModule: PluginModule = {
   ],
 
   paneTemplates: [
-    createTickerSurfacePaneTemplate({
-      id: "insider-pane",
-      paneId: "insider",
-      label: "Insider",
-      description: "Insider transaction activity for the selected ticker.",
-      keywords: ["insider", "form 4", "ownership", "transactions", "ins"],
-      shortcut: "INS",
-      canCreate: (_context, options) => !options?.ticker || isUsEquityTicker(options.ticker),
-    }),
+    {
+      ...createTickerSurfacePaneTemplate({
+        id: "insider-pane",
+        paneId: "insider",
+        label: "Insider",
+        description: "Insider transaction activity for the selected ticker.",
+        keywords: ["insider", "form 4", "ownership", "transactions", "ins"],
+        shortcut: "INS",
+        canCreate: (_context, options) => !options?.ticker || isUsEquityTicker(options.ticker),
+      }),
+      headless: insiderHeadless,
+    },
   ],
 
   setup(ctx) {

package/src/plugins/builtin/insider/insider-data.ts

@@ -45,6 +45,6 @@ export function transactionTypeLabel(type: InsiderTransaction["transactionType"]
     case "S": return "SELL";
     case "A": return "AWARD";
     case "D": return "DISPOSE";
-    default: return "—";
+    default: return "-";
   }
 }