gloomberb 0.14.1 → 0.15.1

package/src/plugins/builtin/equity-screener/criterion-editor.tsx

@@ -0,0 +1,174 @@
+import { useRef, useState } from "react";
+import { Box } from "../../../ui";
+import {
+  Button,
+  Notice,
+  SelectButton,
+  TextField,
+  type SelectControl,
+} from "../../../components";
+import { useShortcut } from "../../../public/react";
+import type {
+  ScreenCriterion,
+  ScreenFieldDefinition,
+  ScreenOperator,
+} from "../../../api-client/equity-screener";
+import { parseCriterion } from "./model";
+
+export function CriterionEditor({
+  fields,
+  value,
+  onSave,
+  onCancel,
+  focused,
+  width,
+}: {
+  fields: ScreenFieldDefinition[];
+  value: ScreenCriterion | null;
+  onSave: (criterion: ScreenCriterion) => void;
+  onCancel: () => void;
+  focused: boolean;
+  width: number;
+}) {
+  const [fieldId, setFieldId] = useState(
+    value?.field ??
+      (fields.find((row) => row.id === "trailingPE") ??
+        fields.find((row) => row.kind === "number") ??
+        fields[0]!).id,
+  );
+  const field = fields.find((row) => row.id === fieldId)!;
+  const [operator, setOperator] = useState<ScreenOperator>(
+    value?.op ?? field.operators[0]!,
+  );
+  const [text, setText] = useState(
+    value && "value" in value
+      ? Array.isArray(value.value)
+        ? value.value.join(", ")
+        : String(value.value)
+      : "",
+  );
+  const [error, setError] = useState<string | null>(null);
+  const [active, setActive] = useState("field");
+  const fieldControl = useRef<SelectControl>(null),
+    operatorControl = useRef<SelectControl>(null);
+  const ring = [
+    "field",
+    "operator",
+    ...(["present", "missing"].includes(operator) ? [] : ["value"]),
+    "save",
+    "cancel",
+  ];
+  const save = () => {
+    try {
+      onSave(parseCriterion(field, operator, text));
+    } catch (error) {
+      setError(error instanceof Error ? error.message : "Invalid criterion.");
+    }
+  };
+  useShortcut(
+    (event) => {
+      if (event.name === "tab") {
+        event.preventDefault();
+        event.stopPropagation();
+        setActive((current) => ring[(ring.indexOf(current) + (event.shift ? -1 : 1) + ring.length) % ring.length]!);
+      } else if (event.name === "escape") {
+        event.preventDefault();
+        event.stopPropagation();
+        onCancel();
+      } else if (
+        ["enter", "return"].includes(event.name ?? "") &&
+        !event.targetEditable
+      ) {
+        event.preventDefault();
+        event.stopPropagation();
+        if (active === "field") fieldControl.current?.open();
+        else if (active === "operator") operatorControl.current?.open();
+        else if (active === "cancel") onCancel();
+        else save();
+      }
+    },
+    {
+      enabled: focused,
+      allowEditable: true,
+      phase: "before",
+      scope: "equity-screen-criterion",
+    },
+  );
+  return (
+    <Box paddingX={1} paddingTop={1} flexDirection="column" gap={1}>
+      <SelectButton
+        label="Field"
+        emphasized={focused && active === "field"}
+        value={fieldId}
+        options={fields.map((row) => ({ value: row.id, label: row.label }))}
+        variant="field"
+        width={Math.min(40, width - 4)}
+        onFocus={() => setActive("field")}
+        controlRef={fieldControl}
+        onChange={(id) => {
+          setFieldId(id);
+          const next = fields.find((row) => row.id === id)!;
+          setOperator(next.operators[0]!);
+          setError(null);
+        }}
+      />
+      <SelectButton
+        label="Operator"
+        emphasized={focused && active === "operator"}
+        value={operator}
+        options={field.operators.map((op) => ({
+          value: op,
+          label: {
+            gte: "At least",
+            lte: "At most",
+            gt: "Above",
+            lt: "Below",
+            eq: "Equals",
+            between: "Between",
+            in: "One of",
+            present: "Available",
+            missing: "Unavailable",
+          }[op],
+        }))}
+        variant="field"
+        width={Math.min(30, width - 4)}
+        onChange={setOperator}
+        onFocus={() => setActive("operator")}
+        controlRef={operatorControl}
+      />
+      {!["present", "missing"].includes(operator) ? (
+        <TextField
+          label={`Value${field.unit ? ` (${field.unit})` : ""}`}
+          value={text}
+          onChange={setText}
+          placeholder={
+            operator === "between"
+              ? "minimum, maximum"
+              : operator === "in"
+                ? "comma-separated values"
+                : "threshold, e.g. 25 or 10B"
+          }
+          width={Math.min(45, width - 4)}
+          focused={focused && active === "value"}
+          onMouseDown={() => setActive("value")}
+          onSubmit={save}
+        />
+      ) : null}
+      {error ? <Notice tone="negative">{error}</Notice> : null}
+      <Box flexDirection="row" gap={1}>
+        <Button
+          label="Save criterion"
+          variant="primary"
+          active={focused && active === "save"}
+          onPress={save}
+        />
+        <Button
+          label="Cancel"
+          variant="secondary"
+          active={focused && active === "cancel"}
+          onPress={onCancel}
+        />
+      </Box>
+    </Box>
+  );
+}

package/src/plugins/builtin/equity-screener/headless.test.ts

@@ -0,0 +1,22 @@
+import { expect, test } from "bun:test";
+import { MAX_TOOL_RESULT_BYTES } from "../cloud/askg/protocol";
+import { equityScreenerHeadless } from "./headless";
+import { screenFixture } from "./test-fixture";
+
+test("a full page with more matches is neither an error nor too large for an Ask Gloom tool result", async () => {
+  const data = screenFixture();
+  const row = data.rows[0]!;
+  data.rows = Array.from({ length: 100 }, (_, index) => ({ ...row, symbol: `S${index}` }));
+  // Sparse fields make every real payload "partial"; that is not a failure.
+  Object.assign(data, { status: "partial", nextCursor: "next", universe: { ...data.universe, covered: 700, matched: 680 } });
+  const apiClient = { equityScreener: async () => structuredClone(data) };
+  const result = await equityScreenerHeadless.load({ argument: undefined, options: {} } as never, { apiClient } as never);
+  expect(result.errors).toEqual([]);
+  expect(result.complete).toBe(false);
+  expect(result.metadata).toMatchObject({ matched: 680, returned: 100, hasMore: true, notices: ["Top 100 of 680 matches; narrow the criteria to see the rest."] });
+  expect(new TextEncoder().encode(JSON.stringify(result)).byteLength).toBeLessThan(MAX_TOOL_RESULT_BYTES);
+
+  data.warnings = ["Bounded scan: some listings were not evaluated."];
+  const bounded = await equityScreenerHeadless.load({ argument: undefined, options: {} } as never, { apiClient } as never);
+  expect(bounded.errors).toEqual(data.warnings);
+});

package/src/plugins/builtin/equity-screener/headless.ts

@@ -0,0 +1,102 @@
+import type { HeadlessPaneDefinition } from "../../../types/plugin";
+import {
+  NUMERIC_FIELDS,
+  type NumericField,
+} from "../../../api-client/equity-screener";
+import { fetchScreen } from "./client";
+import {
+  DEFAULT_SCREEN,
+  formatScreenValue,
+  metricDate,
+  parseScreenDefinition,
+  SHORT_LABELS,
+} from "./model";
+
+export const equityScreenerHeadless: HeadlessPaneDefinition<"bundle"> = {
+  shape: "bundle",
+  argument: { kind: "none" },
+  options: [
+    {
+      key: "definition",
+      type: "string",
+      description: "Version 1 JSON screen criteria and sort definition.",
+    },
+    {
+      key: "metric",
+      type: "enum",
+      description:
+        "Metric to display with its source date and covered-universe rank.",
+      values: NUMERIC_FIELDS.map((value) => ({ value })),
+      defaultValue: "marketCap",
+    },
+  ],
+  describe: "Equity screener",
+  discovery: {
+    aliases: ["EQS"],
+    dataRequirements: ["Gloom Cloud stored screener snapshot"],
+    limitations: [
+      "Covered stored universe, not every listed equity",
+      "Ranks are cross-sectional and dates differ by field",
+      "Observed-subset insider activity cannot establish an absence",
+    ],
+  },
+  async load(args, ctx) {
+    const definition = args.options.definition
+      ? parseScreenDefinition(JSON.parse(String(args.options.definition)))
+      : DEFAULT_SCREEN;
+    const data = await fetchScreen(definition, null, ctx.signal, ctx.apiClient);
+    const metric = (args.options.metric ?? "marketCap") as NumericField;
+    // Payload status also counts ordinary per-field sparsity; only generation
+    // warnings are failures, and more pages are not an error.
+    return {
+      complete: !data.nextCursor && data.warnings.length === 0,
+      errors: data.warnings,
+      sections: [
+        {
+          title: "Matching equities",
+          columns: [
+            { key: "symbol", header: "Symbol" },
+            { key: "exchange", header: "Exchange" },
+            { key: "name", header: "Name" },
+            { key: "value", header: SHORT_LABELS[metric], align: "right" },
+            { key: "unit", header: "Unit" },
+            { key: "percentile", header: "Covered pctl", align: "right" },
+            { key: "asOf", header: "As of" },
+            { key: "state", header: "State" },
+          ],
+          rows: data.rows.map((row) => {
+            const observation = row.metrics[metric];
+            const stamp = metricDate(observation);
+            return {
+              symbol: row.symbol,
+              exchange: row.exchange,
+              name: row.name,
+              value: formatScreenValue(metric, observation.value),
+              unit: observation.unit,
+              percentile:
+                observation.percentile.value == null
+                  ? null
+                  : Math.round(observation.percentile.value),
+              asOf: stamp.collected ? `${stamp.text} (collected)` : stamp.text,
+              state: observation.state,
+            };
+          }),
+        },
+      ],
+      // Per-row metric provenance stays out: 100 annotated rows overflow tool results.
+      metadata: {
+        snapshot: data.snapshot,
+        definition: data.definition,
+        matched: data.universe.matched,
+        covered: data.universe.covered,
+        returned: data.rows.length,
+        hasMore: !!data.nextCursor,
+        notices: data.nextCursor
+          ? [
+              `Top ${data.rows.length} of ${data.universe.matched} matches; narrow the criteria to see the rest.`,
+            ]
+          : [],
+      },
+    };
+  },
+};

package/src/plugins/builtin/equity-screener/index.tsx

@@ -0,0 +1,38 @@
+import type { PluginModule } from "../plugin-module";
+import { equityScreenerHeadless } from "./headless";
+import { EquityScreenerPane } from "./pane";
+
+export const equityScreenerModule: PluginModule = {
+  panes: [
+    {
+      id: "equity-screener",
+      name: "Equity Screener",
+      icon: "S",
+      component: EquityScreenerPane,
+      defaultPosition: "right",
+      defaultMode: "floating",
+      defaultFloatingSize: { width: 108, height: 30 },
+      tableExport: true,
+      headless: equityScreenerHeadless,
+    },
+  ],
+  paneTemplates: [
+    {
+      id: "equity-screener-pane",
+      paneId: "equity-screener",
+      label: "Equity Screener",
+      description:
+        "Screen stored equities by valuation, growth, liquidity and reported activity; save criteria to your Cloud account.",
+      keywords: [
+        "eqs",
+        "criteria",
+        "screener",
+        "valuation",
+        "discovery",
+        "filter",
+      ],
+      shortcut: { prefix: "EQS" },
+      headless: equityScreenerHeadless,
+    },
+  ],
+};

package/src/plugins/builtin/equity-screener/live.ts

@@ -0,0 +1,74 @@
+import type { ScreenMetric, ScreenRow } from "../../../api-client/equity-screener";
+import type { QueryEntry } from "../../../market-data/result-types";
+import { buildQuoteKey, resolveEntryData } from "../../../market-data/selectors";
+import type { Quote } from "../../../types/financials";
+
+const finite = (value: number | null | undefined): value is number =>
+  typeof value === "number" && Number.isFinite(value);
+
+function metricTime(metric: ScreenMetric | undefined): number | null {
+  const stamp = metric?.observedAt ?? metric?.asOf ?? null;
+  if (!stamp) return null;
+  const time = Date.parse(stamp);
+  return Number.isFinite(time) ? time : null;
+}
+
+function screenRowQuoteKey(row: Pick<ScreenRow, "symbol" | "exchange">): string {
+  return buildQuoteKey({ symbol: row.symbol, exchange: row.exchange });
+}
+
+function liveMetric(metric: ScreenMetric, value: number, observedAt: string): ScreenMetric {
+  return { ...metric, value, asOf: observedAt, observedAt, state: "available" };
+}
+
+/**
+ * Price, day change, volume and market cap from a live quote, over a snapshot
+ * row. Market cap scales with price so it keeps the snapshot's share basis.
+ * Membership, sort order and percentiles stay the snapshot's, so rows neither
+ * reshuffle nor vanish between snapshots. A quote in another currency unit
+ * (GBp against GBP) or older than the snapshot leaves the row alone.
+ */
+function overlayLiveScreenRow(row: ScreenRow, quote: Quote | null): ScreenRow {
+  if (!quote || quote.stale === true || !finite(quote.price) || quote.price <= 0) return row;
+  const snapshotPrice = row.metrics.price;
+  if (!snapshotPrice) return row;
+  const quoteCurrency = quote.currency?.trim();
+  if (quoteCurrency && row.currency && quoteCurrency !== row.currency) return row;
+  const snapshotAt = metricTime(snapshotPrice);
+  if (snapshotAt != null && finite(quote.lastUpdated) && quote.lastUpdated < snapshotAt) return row;
+  if (!finite(quote.lastUpdated)) return row;
+  if (snapshotPrice.value === quote.price && row.metrics.changePercent?.value === quote.changePercent) return row;
+
+  const observedAt = new Date(quote.lastUpdated).toISOString();
+  const metrics = { ...row.metrics, price: liveMetric(snapshotPrice, quote.price, observedAt) };
+  if (finite(quote.changePercent) && metrics.changePercent) {
+    metrics.changePercent = liveMetric(metrics.changePercent, quote.changePercent, observedAt);
+  }
+  if (finite(quote.volume) && quote.volume >= 0 && metrics.volume) {
+    metrics.volume = liveMetric(metrics.volume, quote.volume, observedAt);
+  }
+  const cap = metrics.marketCap;
+  if (cap && finite(cap.value) && finite(snapshotPrice.value) && snapshotPrice.value > 0) {
+    metrics.marketCap = liveMetric(cap, cap.value * (quote.price / snapshotPrice.value), observedAt);
+  }
+  return { ...row, metrics };
+}
+
+/** The last overlay per snapshot row, so a row whose quote did not move keeps its object. */
+const liveRows = new WeakMap<ScreenRow, { quote: Quote | null; row: ScreenRow }>();
+
+export function overlayLiveScreenRows(
+  rows: readonly ScreenRow[],
+  entries: ReadonlyMap<string, QueryEntry<Quote>>,
+): ScreenRow[] {
+  return rows.map((row) => {
+    const entry = entries.get(screenRowQuoteKey(row));
+    if (!entry) return row;
+    const quote = resolveEntryData(entry);
+    const cached = liveRows.get(row);
+    if (cached && cached.quote === quote) return cached.row;
+    const next = overlayLiveScreenRow(row, quote);
+    liveRows.set(row, { quote, row: next });
+    return next;
+  });
+}

package/src/plugins/builtin/equity-screener/model.test.ts

@@ -0,0 +1,116 @@
+import { screenFixture as payload } from "./test-fixture";
+import { expect, test } from "bun:test";
+import type { ScreenSnapshot } from "../../../api-client/equity-screener";
+import { fetchScreen } from "./client";
+import {
+  appendScreenPage,
+  criterionText,
+  DEFAULT_SCREEN,
+  formatScreenValue,
+  metricDate,
+  parseCriterion,
+  parseThreshold,
+  resultFields,
+  parseScreenDefinition,
+  validateScreenPayload,
+} from "./model";
+const field = {
+  id: "trailingPE" as const,
+  label: "P/E",
+  kind: "number" as const,
+  unit: "x",
+  description: "",
+  operators: ["gte", "between", "present"] as const,
+};
+
+test("criteria preserve zero and finite bounds, reject blank, currency ambiguity and observed-subset absence claims", () => {
+  expect(
+    parseCriterion({ ...field, operators: [...field.operators] }, "gte", "0"),
+  ).toEqual({ field: "trailingPE", op: "gte", value: 0 });
+  expect(() =>
+    parseCriterion({ ...field, operators: [...field.operators] }, "gte", ""),
+  ).toThrow("finite");
+  expect(() =>
+    parseCriterion(
+      { ...field, operators: [...field.operators] },
+      "between",
+      "20,10",
+    ),
+  ).toThrow("ascending");
+  expect(() =>
+    parseScreenDefinition({ ...DEFAULT_SCREEN, currency: null }),
+  ).toThrow("currency");
+  expect(() =>
+    parseScreenDefinition({
+      ...DEFAULT_SCREEN,
+      criteria: [{ field: "insiderPurchases90d", op: "eq", value: 0 }],
+    }),
+  ).toThrow("supported operator");
+});
+test("boundaries reject fabricated dates and percentiles; pagination cannot cross snapshots", () => {
+  const data = payload();
+  expect(validateScreenPayload(data)).toBe(data);
+  data.rows[0]!.metrics.price.value = 1;
+  data.rows[0]!.metrics.price.state = "available";
+  expect(() => validateScreenPayload(data)).toThrow("price");
+  data.rows[0]!.metrics.price.asOf = "2026-09-22";
+  data.rows[0]!.metrics.price.percentile.value = 101;
+  expect(() => validateScreenPayload(data)).toThrow("price");
+  const dated = payload();
+  dated.snapshot!.assembledAt = null as unknown as ScreenSnapshot["assembledAt"];
+  expect(() => validateScreenPayload(dated)).toThrow("snapshot identity");
+  const undated = payload();
+  undated.rows[0]!.metrics.marketCap.value = 12;
+  undated.rows[0]!.metrics.marketCap.state = "partial";
+  undated.rows[0]!.metrics.marketCap.observedAt = "2026-09-22T12:00:00Z";
+  expect(validateScreenPayload(undated).rows[0]!.metrics.marketCap.asOf).toBeNull();
+  const next = payload();
+  next.snapshot!.id = "two";
+  expect(() => appendScreenPage(payload(), next)).toThrow("snapshot changed");
+  expect(appendScreenPage(payload(), payload()).rows).toHaveLength(1);
+});
+
+test("query boundary rejects valid rows from different criteria", async () => {
+  const response = payload();
+  response.definition.criteria = [];
+  await expect(fetchScreen(DEFAULT_SCREEN, null, undefined, {
+    equityScreener: async () => response,
+  })).rejects.toThrow("requested criteria");
+});
+
+test("thresholds accept scale suffixes and reject anything else", () => {
+  expect(parseThreshold("10B")).toBe(10_000_000_000);
+  expect(parseThreshold("1.5t")).toBe(1_500_000_000_000);
+  expect(parseThreshold("-0.5")).toBe(-0.5);
+  expect(parseThreshold("1e6")).toBe(1_000_000);
+  expect(parseThreshold("10 B")).toBeNull();
+  expect(parseThreshold("ten")).toBeNull();
+  expect(criterionText({ field: "marketCap", op: "gte", value: 10_000_000_000 })).toBe("Market cap >= 10B");
+  expect(criterionText({ field: "trailingPE", op: "between", value: [0, 25] })).toBe("Trailing P/E between 0, 25");
+});
+
+test("values keep sign, scale and missing distinct from zero", () => {
+  expect(formatScreenValue("marketCap", 5_547_531_698_176)).toBe("5.55T");
+  expect(formatScreenValue("revenueGrowthPercent", 65.47)).toBe("+65.5");
+  expect(formatScreenValue("revenueGrowthPercent", 0)).toBe("0.0");
+  expect(formatScreenValue("insiderSales90d", 20)).toBe("20");
+  expect(formatScreenValue("trailingPE", null)).toBe("--");
+});
+
+test("undated provider values show their collection date, never an invented source date", () => {
+  const base = payload().rows[0]!.metrics.trailingPE;
+  expect(metricDate({ ...base, asOf: "2026-08-31", observedAt: "2026-09-22T12:00:00Z" })).toEqual({ text: "2026-08-31", collected: false });
+  expect(metricDate({ ...base, value: 10, asOf: null, observedAt: "2026-09-22T12:00:00Z" })).toEqual({ text: "2026-09-22", collected: true });
+  expect(metricDate({ ...base, value: null, asOf: null, observedAt: null })).toEqual({ text: "--", collected: false });
+});
+
+test("result columns lead with the focus metric and the screen's criteria; money needs a currency", () => {
+  const definition = parseScreenDefinition({
+    version: 1,
+    currency: "USD",
+    criteria: [{ field: "operatingMarginPercent", op: "gte", value: 20 }, { field: "sector", op: "in", value: ["Technology"] }],
+    sort: { field: "trailingPE", direction: "asc" },
+  });
+  expect(resultFields(definition, "trailingPE").slice(0, 3)).toEqual(["trailingPE", "operatingMarginPercent", "marketCap"]);
+  expect(resultFields({ ...definition, currency: null }, "trailingPE")).not.toContain("price");
+});