gloomberb 0.14.1 → 0.15.0

package/src/plugins/builtin/estimate-revisions/index.tsx

@@ -0,0 +1,87 @@
+import type { PluginModule } from "../plugin-module";
+import { createTickerSurfacePaneTemplate } from "../shared/ticker-surface";
+import { estimateRevisionsCache } from "./client";
+import { estimateRevisionsHeadless } from "./headless";
+import { EstimateRevisionsPane } from "./pane";
+export const estimateRevisionsModule: PluginModule = {
+  panes: [
+    {
+      id: "estimate-revisions",
+      name: "Estimate Revisions",
+      icon: "E",
+      component: EstimateRevisionsPane,
+      defaultPosition: "right",
+      defaultMode: "floating",
+      defaultFloatingSize: { width: 104, height: 30 },
+      tableExport: true,
+      headless: estimateRevisionsHeadless,
+      settings: {
+        title: "Estimate Revisions",
+        fields: [
+          {
+            key: "period",
+            label: "Fiscal end",
+            type: "text",
+            placeholder: "YYYY-MM-DD",
+          },
+          {
+            key: "frequency",
+            label: "Frequency",
+            type: "select",
+            options: [
+              { value: "quarterly", label: "Quarterly" },
+              { value: "annual", label: "Annual" },
+            ],
+          },
+          {
+            key: "tab",
+            label: "View",
+            type: "select",
+            options: [
+              { value: "revisions", label: "Revisions" },
+              { value: "surprises", label: "Surprises" },
+              { value: "guidance", label: "Guidance" },
+            ],
+          },
+        ],
+      },
+    },
+  ],
+  paneTemplates: [
+    {
+      ...createTickerSurfacePaneTemplate({
+        id: "estimate-revisions-em",
+        paneId: "estimate-revisions",
+        label: "Estimate Revisions",
+        description:
+          "Consensus EPS changes, analyst revision counts, surprises and cited guidance.",
+        keywords: ["estimates", "revisions", "consensus", "em", "eeo"],
+        shortcut: "EM",
+        shortcutAliases: ["EEO"],
+        viewKey: "EM",
+        settings: () => ({ tab: "revisions" }),
+      }),
+      headless: estimateRevisionsHeadless,
+    },
+    {
+      ...createTickerSurfacePaneTemplate({
+        id: "estimate-revisions-guid",
+        paneId: "estimate-revisions",
+        label: "Company Guidance",
+        description:
+          "Company EPS guidance cited from filings and transcripts, against consensus.",
+        keywords: ["guidance", "outlook", "estimates", "guid"],
+        shortcut: "GUID",
+        viewKey: "GUID",
+        settings: () => ({ tab: "guidance" }),
+      }),
+      headless: estimateRevisionsHeadless,
+    },
+  ],
+  setup(ctx) {
+    estimateRevisionsCache.attach(ctx.persistence);
+  },
+  dispose() {
+    estimateRevisionsCache.reset();
+  },
+};

package/src/plugins/builtin/estimate-revisions/model.test.ts

@@ -0,0 +1,246 @@
+import { expect, test } from "bun:test";
+import type {
+  EstimatePeriod,
+  EstimateRevisionsPayload,
+} from "../../../api-client/estimate-revisions";
+import { ApiRequestError } from "../../../api-client/errors";
+import { CLOUD_SESSION_REQUIRED } from "../shared/research-cloud-session";
+import { fetchEstimates, validateEstimates } from "./client";
+import {
+  estimateCurrent,
+  estimateHistory,
+  sortPeriods,
+  pinnedEstimatePeriods,
+} from "./model";
+const stats = {
+  percentile: null,
+  rank: null,
+  samples: 1,
+  min: 1,
+  max: 1,
+  mean: 1,
+};
+function fixture(): EstimateRevisionsPayload {
+  const point = {
+    date: "2026-09-21",
+    recordedAt: null,
+    average: 1,
+    low: 0.8,
+    high: 1.2,
+    analysts: 2,
+    range: 0.4,
+    relativeRange: 0.4,
+    source: "yahoo" as const,
+  };
+  const period: EstimatePeriod = {
+    id: "quarterly:2026-09-30:USD",
+    frequency: "quarterly",
+    periodEnd: "2026-09-30",
+    currency: "USD",
+    label: "current quarter",
+    current: { ...point, growth: null },
+    revenue: null,
+    recorded: [point],
+    lookbacks: [{ ...point, date: "2026-08-21", source: "yahoo-eps-trend" }],
+    percentile: {
+      ...stats,
+      window: "1Y",
+      firstDate: point.date,
+      lastDate: point.date,
+    },
+    dispersionPercentile: stats,
+    change: { value: null, percent: null, fromDate: null, toDate: point.date },
+    breadth: [
+      {
+        days: 30,
+        up: 0,
+        down: 0,
+        net: 0,
+        ratio: null,
+        asOf: point.date,
+        percentile: null,
+      },
+    ],
+  };
+  const source = {
+    status: "available" as const,
+    fetchedAt: "2026-09-22T12:00:00Z",
+    stale: false,
+    reason: null,
+  };
+  return {
+    symbol: "AAPL",
+    exchange: "NASDAQ",
+    generatedAt: source.fetchedAt,
+    status: "partial",
+    sources: {
+      consensus: source,
+      history: source,
+      reported: { ...source, status: "unavailable" },
+      guidance: { ...source, status: "unavailable" },
+    },
+    periods: [period],
+    surprises: [],
+    guidance: null,
+    historyCoverage: {
+      since: "2025-09-22",
+      until: "2026-09-22",
+      truncated: false,
+      excludedRows: 0,
+      recordedDays: 1,
+      lookbackRows: 1,
+    },
+    gaps: [],
+  };
+}
+test("period identity and actual-versus-lookback boundaries reject unsafe ranks and revisions", () => {
+  const data = validateEstimates(fixture(), "AAPL", "NASDAQ");
+  expect(estimateHistory(data.periods[0]!).map((row) => row.source)).toEqual([
+    "yahoo",
+    "yahoo-eps-trend",
+  ]);
+  expect(estimateCurrent({ ...data.periods[0]!, current: null })?.date).toBe(
+    "2026-09-21",
+  );
+  const currency = fixture();
+  currency.periods[0]!.currency = "DKK";
+  expect(() => validateEstimates(currency, "AAPL", "NASDAQ")).toThrow();
+  const source = fixture();
+  source.periods[0]!.recorded[0]!.source = "yahoo-eps-trend";
+  expect(() => validateEstimates(source, "AAPL", "NASDAQ")).toThrow();
+  const rank = fixture();
+  rank.periods[0]!.percentile.percentile = 50;
+  expect(() => validateEstimates(rank, "AAPL", "NASDAQ")).toThrow();
+  const count = fixture();
+  count.periods[0]!.breadth[0]!.down = -1;
+  expect(() => validateEstimates(count, "AAPL", "NASDAQ")).toThrow();
+  expect(() => validateEstimates(fixture(), "AAPL", "NYSE")).toThrow();
+});
+test("sorting keeps missing consensus last without treating it as zero", () => {
+  const first = fixture().periods[0]!;
+  const missing = {
+    ...first,
+    id: "quarterly:2026-12-31:USD",
+    periodEnd: "2026-12-31",
+    current: null,
+    recorded: [],
+  };
+  expect(
+    sortPeriods([missing, first], "eps", "desc").map((row) => row.id),
+  ).toEqual([first.id, missing.id]);
+  expect(
+    sortPeriods([missing, first], "eps", "asc").map((row) => row.id),
+  ).toEqual([first.id, missing.id]);
+});
+test("absent endpoint and denied access remain distinct", async () => {
+  await expect(
+    fetchEstimates("AAPL", "NASDAQ", {
+      getCloudEstimateRevisions: async () => {
+        throw new ApiRequestError("Missing", 404);
+      },
+    }),
+  ).rejects.toThrow("not available on this Gloom Cloud server yet");
+  // A signed-out (401) or unverified (403) session becomes the shared Cloud gate the pane walls on.
+  for (const status of [401, 403]) {
+    await expect(
+      fetchEstimates("AAPL", "NASDAQ", {
+        getCloudEstimateRevisions: async () => {
+          throw new ApiRequestError(status === 401 ? "Unauthorized" : "Email verification required", status);
+        },
+      }),
+    ).rejects.toThrow(CLOUD_SESSION_REQUIRED);
+  }
+});
+
+test("fiscal pin preserves frequency and currency identity and rejects invalid or unavailable dates", () => {
+  const quarter = fixture().periods[0]!;
+  const annual = {
+    ...quarter,
+    id: "annual:2026-09-30:USD",
+    frequency: "annual" as const,
+  };
+  const alternateCurrency = {
+    ...quarter,
+    id: "quarterly:2026-09-30:DKK",
+    currency: "DKK",
+  };
+  const periods = [quarter, annual, alternateCurrency];
+  expect(
+    pinnedEstimatePeriods(periods, "2026-09-30", "quarterly").map(
+      (row) => row.id,
+    ),
+  ).toEqual([quarter.id, alternateCurrency.id]);
+  expect(pinnedEstimatePeriods(periods, "2026-09-30", "annual")).toEqual([
+    annual,
+  ]);
+  expect(pinnedEstimatePeriods(periods, undefined)).toBe(periods);
+  expect(() => pinnedEstimatePeriods(periods, "2026-02-30")).toThrow(
+    "valid YYYY-MM-DD",
+  );
+  expect(() => pinnedEstimatePeriods(periods, "2027-09-30")).toThrow(
+    "No quarterly estimates",
+  );
+});
+
+test("untracked listings resolve only an exact unambiguous Cloud search identity", async () => {
+  const listing = {
+    providerId: "yahoo",
+    symbol: "AAPL",
+    name: "Apple",
+    exchange: "NASDAQ",
+    type: "equity",
+  };
+  const seen: string[] = [];
+  const client = {
+    searchInstruments: async () => [listing, { ...listing, exchange: "XNAS" }],
+    getCloudEstimateRevisions: async (symbol: string, exchange: string) => {
+      seen.push(`${exchange}:${symbol}`);
+      return fixture();
+    },
+  };
+  await fetchEstimates("AAPL", "", client);
+  expect(seen).toEqual(["NASDAQ:AAPL"]);
+  await expect(
+    fetchEstimates("AAPL", "", {
+      ...client,
+      searchInstruments: async () => [
+        listing,
+        { ...listing, exchange: "NYSE" },
+      ],
+    }),
+  ).rejects.toThrow("Choose a listing exchange");
+  await expect(
+    fetchEstimates("AAPL", "", {
+      ...client,
+      searchInstruments: async () => [{ ...listing, symbol: "AAP" }],
+    }),
+  ).rejects.toThrow("Choose a listing exchange");
+  expect(seen).toHaveLength(1);
+});
+
+test("guidance and surprise provenance are validated before rendering date and source fields", () => {
+  const data = fixture();
+  data.guidance = {
+    callDate: "2026-08-26T00:00:00Z",
+    fiscalYear: 2027,
+    fiscalQuarter: 2,
+    publishedAt: "2026-09-08T17:15:00Z",
+    text: "Cited forecast text",
+    transcriptURL: "https://gloom.sh/stocks/nvda/transcripts/2027-q2",
+    webcastURL: null,
+    source: "public-transcript-summary",
+    numericComparison: null,
+  };
+  expect(validateEstimates(data, "AAPL", "NASDAQ").guidance).toBe(
+    data.guidance,
+  );
+  data.guidance.publishedAt = "not-a-date";
+  expect(() => validateEstimates(data, "AAPL", "NASDAQ")).toThrow(
+    "invalid estimate revisions",
+  );
+  data.guidance.publishedAt = "2026-09-08T17:15:00Z";
+  data.guidance.transcriptURL = "javascript:alert(1)";
+  expect(() => validateEstimates(data, "AAPL", "NASDAQ")).toThrow(
+    "invalid estimate revisions",
+  );
+});

package/src/plugins/builtin/estimate-revisions/model.ts

@@ -0,0 +1,115 @@
+import type {
+  EstimateObservation,
+  EstimatePeriod,
+  EstimateRevisionsPayload,
+} from "../../../api-client/estimate-revisions";
+import type { DataTableColumn } from "../../../components";
+export const estimateNumber = (value: number | null | undefined) =>
+  value == null
+    ? "--"
+    : value.toLocaleString("en-US", { maximumFractionDigits: 4 });
+export const estimatePercent = (value: number | null | undefined) =>
+  value == null ? "--" : `${value > 0 ? "+" : ""}${value.toFixed(2)}%`;
+export const estimateCurrent = (period: EstimatePeriod) =>
+  period.current ?? period.recorded.at(-1) ?? null;
+export const periodLabel = (period: EstimatePeriod) =>
+  `${period.frequency === "annual" ? "FY" : "Q"} ${period.periodEnd}`;
+export function revisionNotices(data: EstimateRevisionsPayload) {
+  return [
+    ...Object.entries(data.sources).flatMap(([source, state]) =>
+      state.status !== "available"
+        ? [`${source}: ${state.reason ?? "source unavailable"}`]
+        : [],
+    ),
+    ...(data.historyCoverage.recordedDays < 20
+      ? [
+          "Fewer than 20 actual observation days; EPS percentiles remain unavailable.",
+        ]
+      : []),
+    ...(data.historyCoverage.truncated
+      ? ["Stored history is truncated to the latest 4,000 rows."]
+      : []),
+    ...(data.historyCoverage.excludedRows
+      ? ["Some stored rows lack a valid fiscal identity or observation date."]
+      : []),
+  ];
+}
+export function estimateHistory(period: EstimatePeriod) {
+  return [...period.recorded, ...period.lookbacks].toSorted(
+    (a, b) => b.date.localeCompare(a.date) || a.source.localeCompare(b.source),
+  );
+}
+export function estimatePoints(rows: EstimateObservation[]) {
+  return rows.map((row) => ({
+    date: new Date(row.date),
+    observedAt: new Date(row.recordedAt ?? row.date),
+    value: row.average,
+  }));
+}
+export const PERIOD_COLUMNS: DataTableColumn[] = [
+  { id: "period", label: "FISCAL END", width: 16, align: "left" },
+  { id: "currency", label: "CCY", width: 5, align: "left" },
+  { id: "eps", label: "EPS", width: 11, align: "right" },
+  { id: "percentile", label: "PCTL 1Y", width: 9, align: "right" },
+  { id: "change", label: "CHANGE %", width: 11, align: "right" },
+  { id: "breadth", label: "UP/DN 30D", width: 12, align: "right" },
+  { id: "range", label: "HI-LO", width: 11, align: "right" },
+  { id: "asOf", label: "AS OF", width: 12, align: "left", flexGrow: 1 },
+];
+export function sortPeriods(
+  periods: EstimatePeriod[],
+  column: string,
+  direction: "asc" | "desc",
+) {
+  const value = (period: EstimatePeriod): string | number | null =>
+    column === "period"
+      ? period.periodEnd
+      : column === "currency"
+        ? period.currency
+        : column === "eps"
+          ? (estimateCurrent(period)?.average ?? null)
+          : column === "change"
+            ? period.change.percent
+            : column === "percentile"
+              ? period.percentile.percentile
+              : column === "range"
+                ? (estimateCurrent(period)?.range ?? null)
+                : column === "breadth"
+                  ? (period.breadth.find((row) => row.days === 30)?.net ?? null)
+                  : (estimateCurrent(period)?.date ?? null);
+  return [...periods].sort((a, b) => {
+    const left = value(a),
+      right = value(b);
+    if (left == null || right == null)
+      return left == null ? (right == null ? 0 : 1) : -1;
+    return (
+      (left < right ? -1 : left > right ? 1 : 0) *
+        (direction === "asc" ? 1 : -1) || a.id.localeCompare(b.id)
+    );
+  });
+}
+
+export function pinnedEstimatePeriods(
+  periods: EstimatePeriod[],
+  periodEnd: unknown,
+  frequency: unknown = "quarterly",
+): EstimatePeriod[] {
+  if (periodEnd == null || periodEnd === "") return periods;
+  if (
+    typeof periodEnd !== "string" ||
+    !/^\d{4}-\d{2}-\d{2}$/.test(periodEnd) ||
+    !Number.isFinite(Date.parse(periodEnd)) ||
+    new Date(periodEnd).toISOString().slice(0, 10) !== periodEnd
+  ) {
+    throw new Error("Fiscal end must be a valid YYYY-MM-DD date.");
+  }
+  if (frequency !== "quarterly" && frequency !== "annual")
+    throw new Error("Frequency must be quarterly or annual.");
+  const matches = periods.filter(
+    (period) =>
+      period.periodEnd === periodEnd && period.frequency === frequency,
+  );
+  if (!matches.length)
+    throw new Error(`No ${frequency} estimates for fiscal end ${periodEnd}.`);
+  return matches;
+}