gloomberb 0.18.4 → 0.19.0

package/src/plugins/builtin/scanner/live-condition-editor.tsx

@@ -0,0 +1,222 @@
+import { useRef, useState } from "react";
+import { Button, Notice, NumberField, SelectButton, useFieldRing, type SelectControl } from "../../../components";
+import { useInputCapture, useShortcut } from "../../../public/react";
+import { Box, ScrollBox, type ScrollBoxRenderable } from "../../../ui";
+import { useDialogState } from "../../../ui/dialog";
+import { LIVE_SCAN_WINDOWS, type LiveScanCondition } from "../../../api-client/live-scan";
+import { readCondition } from "./live-model";
+
+type Kind = LiveScanCondition["kind"];
+
+const KIND_OPTIONS: Array<{ value: Kind; label: string }> = [
+  { value: "move", label: "Price move" },
+  { value: "volume_spike", label: "Volume spike" },
+  { value: "new_high", label: "New session high" },
+  { value: "new_low", label: "New session low" },
+  { value: "vwap_cross", label: "VWAP cross" },
+  { value: "gap", label: "Gap from previous close" },
+];
+const WINDOW_OPTIONS = LIVE_SCAN_WINDOWS.map((window) => ({ value: String(window), label: `${window} min` }));
+const VOLUME_WINDOW_OPTIONS = [...WINDOW_OPTIONS, { value: "day", label: "Session so far" }];
+const MOVE_DIRECTIONS = [
+  { value: "either", label: "Either way" },
+  { value: "up", label: "Up" },
+  { value: "down", label: "Down" },
+];
+const VWAP_DIRECTIONS = [
+  { value: "either", label: "Either way" },
+  { value: "above", label: "Above" },
+  { value: "below", label: "Below" },
+];
+
+interface Draft {
+  kind: Kind;
+  window: string;
+  direction: string;
+  amount: string;
+}
+
+function draftOf(condition: LiveScanCondition | null): Draft {
+  if (!condition) return { kind: "move", window: "5", direction: "either", amount: "2" };
+  switch (condition.kind) {
+    case "move":
+      return { kind: "move", window: String(condition.window), direction: condition.direction, amount: String(condition.percent) };
+    case "volume_spike":
+      return { kind: "volume_spike", window: String(condition.window), direction: "either", amount: String(condition.ratio) };
+    case "new_high":
+    case "new_low":
+      return { kind: condition.kind, window: String(condition.within), direction: "either", amount: "" };
+    case "vwap_cross":
+      return { kind: "vwap_cross", window: String(condition.within), direction: condition.direction, amount: "" };
+    case "gap":
+      return { kind: "gap", window: "5", direction: condition.direction, amount: String(condition.percent) };
+  }
+}
+
+/** The condition a draft describes, or why it does not describe one. */
+function conditionFromDraft(draft: Draft): LiveScanCondition | string {
+  const amount = Number(draft.amount);
+  const window = draft.window === "day" ? "day" : Number(draft.window);
+  const needsAmount = draft.kind === "move" || draft.kind === "gap" || draft.kind === "volume_spike";
+  if (needsAmount && (!draft.amount.trim() || !Number.isFinite(amount))) {
+    return draft.kind === "volume_spike" ? "Enter a multiple of average volume, such as 3." : "Enter a percent, such as 2.";
+  }
+  if (draft.kind === "volume_spike" && amount < 0.1) return "A volume multiple starts at 0.1.";
+  if (needsAmount && amount > 1_000) return "That is more than the scanner takes.";
+  const raw = draft.kind === "move"
+    ? { kind: "move", window, direction: draft.direction, percent: amount }
+    : draft.kind === "volume_spike"
+      ? { kind: "volume_spike", window, ratio: amount }
+      : draft.kind === "gap"
+        ? { kind: "gap", direction: draft.direction, percent: amount }
+        : draft.kind === "vwap_cross"
+          ? { kind: "vwap_cross", direction: draft.direction, within: window }
+          : { kind: draft.kind, within: window };
+  return readCondition(raw) ?? "Check the window and direction.";
+}
+
+const FIELD_IDS = ["kind", "window", "direction", "amount", "save", "cancel"] as const;
+type FieldId = (typeof FIELD_IDS)[number];
+
+export function LiveConditionEditor({
+  value,
+  focused,
+  width,
+  onSave,
+  onCancel,
+}: {
+  value: LiveScanCondition | null;
+  focused: boolean;
+  width: number;
+  onSave: (condition: LiveScanCondition) => void;
+  onCancel: () => void;
+}) {
+  const [draft, setDraft] = useState<Draft>(() => draftOf(value));
+  const [error, setError] = useState<string | null>(null);
+  const [active, setActive] = useState<FieldId>("kind");
+  const kindControl = useRef<SelectControl>(null);
+  const windowControl = useRef<SelectControl>(null);
+  const directionControl = useRef<SelectControl>(null);
+  const scrollRef = useRef<ScrollBoxRenderable>(null);
+  const dialogOpen = useDialogState((state) => state.isOpen);
+  const hasWindow = draft.kind !== "gap";
+  const hasDirection = draft.kind === "move" || draft.kind === "gap" || draft.kind === "vwap_cross";
+  const hasAmount = draft.kind === "move" || draft.kind === "gap" || draft.kind === "volume_spike";
+  const ids = FIELD_IDS.filter((id) => (
+    (id !== "window" || hasWindow) && (id !== "direction" || hasDirection) && (id !== "amount" || hasAmount)
+  ));
+  const save = () => {
+    const condition = conditionFromDraft(draft);
+    if (typeof condition === "string") setError(condition);
+    else onSave(condition);
+  };
+  const ring = useFieldRing<FieldId>({
+    ids,
+    activeId: active,
+    onActivate: setActive,
+    enabled: focused && !dialogOpen,
+    scope: "live-scan-condition",
+    scrollRef,
+    actions: {
+      kind: () => kindControl.current?.open(),
+      window: () => windowControl.current?.open(),
+      direction: () => directionControl.current?.open(),
+      save,
+      cancel: onCancel,
+    },
+  });
+  useInputCapture(focused);
+  useShortcut((event) => {
+    if (event.name !== "escape") return;
+    event.preventDefault();
+    event.stopPropagation();
+    onCancel();
+  }, { enabled: focused && !dialogOpen, phase: "before", allowEditable: true, scope: "live-scan-condition" });
+  const update = (patch: Partial<Draft>) => {
+    setDraft((current) => ({ ...current, ...patch }));
+    setError(null);
+  };
+  const fieldWidth = Math.max(20, Math.min(44, width - 4));
+  const windowLabel = draft.kind === "move" || draft.kind === "volume_spike" ? "Over the last" : "Within the last";
+  const amountLabel = draft.kind === "volume_spike" ? "Times average volume" : "Percent, at least";
+  return (
+    <ScrollBox ref={scrollRef} flexGrow={1} flexBasis={0} minHeight={0} scrollY>
+      <Box paddingX={1} flexDirection="column" gap={1}>
+        <Box ref={ring.nodeRef("kind")}>
+          <SelectButton
+            variant="form"
+            width={fieldWidth}
+            label="Condition"
+            value={draft.kind}
+            options={KIND_OPTIONS}
+            onChange={(kind) => {
+              const next = draftOf(null);
+              update({
+                kind,
+                direction: kind === draft.kind ? draft.direction : "either",
+                window: kind === "volume_spike" || draft.window !== "day" ? draft.window : "5",
+                amount: kind === "volume_spike" ? "3" : kind === "move" || kind === "gap" ? next.amount : "",
+              });
+            }}
+            controlRef={kindControl}
+            onFocus={() => setActive("kind")}
+            emphasized={active === "kind"}
+          />
+        </Box>
+        {hasWindow ? (
+          <Box ref={ring.nodeRef("window")}>
+            <SelectButton
+              variant="form"
+              width={fieldWidth}
+              label={windowLabel}
+              value={draft.window}
+              options={draft.kind === "volume_spike" ? VOLUME_WINDOW_OPTIONS : WINDOW_OPTIONS}
+              onChange={(window) => update({ window })}
+              controlRef={windowControl}
+              onFocus={() => setActive("window")}
+              emphasized={active === "window"}
+            />
+          </Box>
+        ) : null}
+        {hasDirection ? (
+          <Box ref={ring.nodeRef("direction")}>
+            <SelectButton
+              variant="form"
+              width={fieldWidth}
+              label="Direction"
+              value={draft.direction}
+              options={draft.kind === "vwap_cross" ? VWAP_DIRECTIONS : MOVE_DIRECTIONS}
+              onChange={(direction) => update({ direction })}
+              controlRef={directionControl}
+              onFocus={() => setActive("direction")}
+              emphasized={active === "direction"}
+            />
+          </Box>
+        ) : null}
+        {hasAmount ? (
+          <Box ref={ring.nodeRef("amount")}>
+            <NumberField
+              label={amountLabel}
+              value={draft.amount}
+              onChange={(amount) => update({ amount })}
+              onSubmit={save}
+              width={fieldWidth}
+              focused={focused && active === "amount"}
+              active={active === "amount"}
+              onMouseDown={() => setActive("amount")}
+            />
+          </Box>
+        ) : null}
+        {error ? <Notice tone="negative">{error}</Notice> : null}
+        <Box flexDirection="row" gap={1}>
+          <Box ref={ring.nodeRef("save")}>
+            <Button label="Save condition" variant="primary" active={focused && active === "save"} onPress={save} />
+          </Box>
+          <Box ref={ring.nodeRef("cancel")}>
+            <Button label="Cancel" variant="secondary" active={focused && active === "cancel"} onPress={onCancel} />
+          </Box>
+        </Box>
+      </Box>
+    </ScrollBox>
+  );
+}

package/src/plugins/builtin/scanner/live-feed.ts

@@ -0,0 +1,168 @@
+import { createContext, useContext, useEffect, useMemo, useRef, useState } from "react";
+import { apiClient } from "../../../api-client";
+import type { LiveScanPayload, LiveScanWireDefinition } from "../../../api-client/live-scan";
+import { errorMessage } from "../../../utils/errors";
+
+/** Where a live scan pane reads its scans; absent, Gloom Cloud. */
+export type LiveScanClient = Pick<typeof apiClient, "getLiveScan">;
+export const LiveScanClientContext = createContext<LiveScanClient | null>(null);
+
+/** Never ask more often than this, whatever the snapshot's refresh says. */
+const MIN_POLL_MS = 5_000;
+/** A scanner that is still warming up answers again soon. */
+const STARTING_POLL_MS = 3_000;
+/** Outside the session the matches do not move. */
+const CLOSED_POLL_MS = 5 * 60_000;
+const FAILED_POLL_MS = 30_000;
+
+/**
+ * When to ask again: when the snapshot behind the answer is next refreshed,
+ * a little after so the next answer is a new one.
+ */
+export function nextLiveScanPoll(payload: LiveScanPayload | null, failed: boolean, now: number): number {
+  if (failed || !payload) return FAILED_POLL_MS;
+  if (payload.status === "starting") return STARTING_POLL_MS;
+  if (payload.status === "closed") return CLOSED_POLL_MS;
+  const refresh = Math.max(MIN_POLL_MS, payload.refreshMs || MIN_POLL_MS);
+  if (payload.takenAt == null) return refresh;
+  // One second after the next refresh lands, or a full interval when that is already past.
+  const due = payload.takenAt + refresh + 1_000 - now;
+  return due >= MIN_POLL_MS ? Math.min(due, refresh + 1_000) : refresh;
+}
+
+export interface LiveScanFeedState {
+  payload: LiveScanPayload | null;
+  /** The last refresh's failure; the last matches stay. */
+  error: string | null;
+  loading: boolean;
+}
+
+interface Timers {
+  set(callback: () => void, ms: number): unknown;
+  clear(handle: unknown): void;
+}
+
+const realTimers: Timers = {
+  set: (callback, ms) => setTimeout(callback, ms),
+  clear: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
+};
+
+/**
+ * Runs one scan: asks, waits for the snapshot's next refresh, asks again.
+ * A new definition drops the old answer and asks at once; stopping keeps the
+ * last answer on screen. Only the newest request may answer.
+ */
+export class LiveScanPoller {
+  private definition: LiveScanWireDefinition | null = null;
+  private key = "";
+  private enabled = false;
+  private timer: unknown = null;
+  private controller: AbortController | null = null;
+  private generation = 0;
+  private state: LiveScanFeedState = { payload: null, error: null, loading: false };
+
+  constructor(
+    private readonly client: LiveScanClient,
+    private readonly onState: (state: LiveScanFeedState) => void,
+    private readonly timers: Timers = realTimers,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  setScan(definition: LiveScanWireDefinition | null, key: string): void {
+    if (key === this.key) return;
+    this.key = key;
+    this.definition = definition;
+    this.cancel();
+    this.emit({ payload: null, error: null, loading: !!definition && this.enabled });
+    if (this.enabled) this.ask();
+  }
+
+  setEnabled(enabled: boolean): void {
+    if (enabled === this.enabled) return;
+    this.enabled = enabled;
+    if (!enabled) {
+      this.cancel();
+      if (this.state.loading) this.emit({ ...this.state, loading: false });
+      return;
+    }
+    this.ask();
+  }
+
+  /** Ask now, as `r` does. */
+  reload(): void {
+    if (this.enabled) this.ask();
+  }
+
+  dispose(): void {
+    this.enabled = false;
+    this.cancel();
+  }
+
+  private cancel(): void {
+    this.generation++;
+    this.controller?.abort();
+    this.controller = null;
+    if (this.timer != null) this.timers.clear(this.timer);
+    this.timer = null;
+  }
+
+  private emit(next: LiveScanFeedState): void {
+    this.state = next;
+    this.onState(next);
+  }
+
+  private ask(): void {
+    this.cancel();
+    const definition = this.definition;
+    if (!definition) return;
+    const generation = this.generation;
+    const controller = new AbortController();
+    this.controller = controller;
+    if (!this.state.loading && !this.state.payload) this.emit({ ...this.state, loading: true });
+    this.client.getLiveScan(definition, controller.signal).then(
+      (payload) => {
+        if (generation !== this.generation) return;
+        this.emit({ payload, error: null, loading: false });
+        this.schedule(nextLiveScanPoll(payload, false, this.now()));
+      },
+      (error: unknown) => {
+        if (generation !== this.generation) return;
+        this.emit({ payload: this.state.payload, error: errorMessage(error), loading: false });
+        this.schedule(nextLiveScanPoll(this.state.payload, true, this.now()));
+      },
+    );
+  }
+
+  private schedule(ms: number): void {
+    if (!this.enabled) return;
+    const generation = this.generation;
+    this.timer = this.timers.set(() => {
+      if (generation === this.generation) this.ask();
+    }, ms);
+  }
+}
+
+/**
+ * The live answer to one scan while `enabled`. Leaving the pane on screen or
+ * keeping its alerts on is the caller's call.
+ */
+export function useLiveScanFeed(
+  definition: LiveScanWireDefinition | null,
+  key: string,
+  enabled: boolean,
+): LiveScanFeedState & { reload: () => void } {
+  const client = useContext(LiveScanClientContext) ?? apiClient;
+  const [state, setState] = useState<LiveScanFeedState>({ payload: null, error: null, loading: !!definition && enabled });
+  const pollerRef = useRef<LiveScanPoller | null>(null);
+  const poller = useMemo(() => new LiveScanPoller(client, setState), [client]);
+  pollerRef.current = poller;
+  useEffect(() => () => poller.dispose(), [poller]);
+  // The definition is read through its key.
+  useEffect(() => {
+    poller.setScan(definition, key);
+  }, [poller, key]);
+  useEffect(() => {
+    poller.setEnabled(enabled);
+  }, [poller, enabled]);
+  return useMemo(() => ({ ...state, reload: () => pollerRef.current?.reload() }), [state]);
+}

package/src/plugins/builtin/scanner/live-headless.ts

@@ -0,0 +1,138 @@
+import type { LiveScanPayload, LiveScanWireDefinition } from "../../../api-client/live-scan";
+import type {
+  HeadlessPaneDefinition,
+  HeadlessPaneFreshness,
+  HeadlessSnapshotResult,
+} from "../../../types/plugin";
+import { formatPercentRaw } from "../../../utils/format";
+import {
+  conditionColumnLabel,
+  conditionText,
+  DEFAULT_LIVE_SCAN,
+  formatMultiple,
+  LIVE_SCAN_SECTORS,
+  parseUniverseValue,
+  readLiveScan,
+  warmingWindowsText,
+  type LiveScan,
+} from "./live-model";
+import { LIVE_SCAN_INDEXES } from "../../../api-client/live-scan";
+
+/** `all`, an index (`sp500`) or a sector (`Energy`), as `--universe` takes it. */
+function parseHeadlessUniverse(value: string): LiveScan["universe"] {
+  const text = value.trim();
+  if (!text || text.toLowerCase() === "all") return { kind: "all" };
+  const index = LIVE_SCAN_INDEXES.find((candidate) => candidate === text.toLowerCase());
+  if (index) return parseUniverseValue(`index:${index}`);
+  const sector = LIVE_SCAN_SECTORS.find((candidate) => candidate.toLowerCase() === text.toLowerCase());
+  if (sector) return { kind: "sector", sector };
+  throw new Error(`Universe must be all, ${LIVE_SCAN_INDEXES.join(", ")} or a sector: ${LIVE_SCAN_SECTORS.join(", ")}.`);
+}
+
+/** `--scan` is the conditions and floors as SCAN keeps them, in JSON; the default scan without it. */
+function headlessScan(universe: string, json: string): LiveScan {
+  let scan = DEFAULT_LIVE_SCAN;
+  if (json.trim()) {
+    let raw: unknown;
+    try {
+      raw = JSON.parse(json);
+    } catch {
+      throw new Error("--scan must be JSON, such as {\"conditions\":[{\"kind\":\"new_high\",\"within\":5}],\"minPrice\":5}.");
+    }
+    scan = readLiveScan(raw);
+  }
+  return { ...scan, universe: parseHeadlessUniverse(universe) };
+}
+
+function freshness(payload: LiveScanPayload): HeadlessPaneFreshness {
+  if (payload.status === "closed") return { status: "not-a-feed", basis: "closed session" };
+  if (payload.status === "degraded" || payload.status === "starting") return { status: "stale" };
+  return payload.access === "realtime" ? { status: "live" } : { status: "delayed", delayMinutes: payload.delayMinutes };
+}
+
+/** Why a scan lists nothing, as the pane says it: still starting, warming up, closed, or no match. */
+function emptyText(payload: LiveScanPayload): string {
+  if (payload.status === "starting") return "The scanner is starting. Matches appear within a minute.";
+  if (payload.status === "closed") return "Nothing matched at the close. The scan runs again at the open.";
+  const warming = warmingWindowsText(payload);
+  if (warming) return `The scanner is warming up: conditions over ${warming} match nothing until that much of the session has been watched.`;
+  return "Nothing matches right now.";
+}
+
+const number = (value: unknown) => (typeof value === "number" ? value : undefined);
+
+function projectLiveScan(payload: LiveScanPayload, scan: LiveScan): HeadlessSnapshotResult {
+  return {
+    asOf: new Date(payload.asOf ?? payload.takenAt ?? Date.now()).toISOString(),
+    empty: emptyText(payload),
+    items: payload.matches.map((match) => ({
+      symbol: match.symbol,
+      exchange: match.exchange ?? null,
+      name: match.name,
+      price: match.price,
+      changePercent: match.changePercent,
+      ...Object.fromEntries(scan.conditions.map((condition, index) => [conditionColumnLabel(condition), match.values[index] ?? null])),
+      relativeVolume: match.relativeVolume,
+      volume: match.volume,
+      vwapPercent: match.vwapPercent,
+      gapPercent: match.gapPercent,
+    })),
+    ...(payload.status === "degraded" ? { errors: ["Live scanner degraded"] } : {}),
+    freshness: freshness(payload),
+    metadata: {
+      ...(payload.access === "delayed" ? { notices: [`Delayed ${payload.delayMinutes} minutes`] } : {}),
+      ...(payload.warnings.length ? { warnings: payload.warnings } : {}),
+      status: payload.status,
+      access: payload.access,
+      scanned: payload.scanned,
+      matched: payload.matched,
+      conditions: scan.conditions.map(conditionText),
+      ...(payload.warmingWindows?.length ? { warmingWindows: payload.warmingWindows } : {}),
+    },
+  };
+}
+
+export const liveScanHeadless: HeadlessPaneDefinition<"snapshot"> = {
+  shape: "snapshot",
+  description: "US stocks matching intraday conditions now: moves over the last minutes, volume spikes, new highs and lows, VWAP crosses and gaps.",
+  argument: { kind: "none" },
+  options: [
+    {
+      key: "universe",
+      description: "all, an index (sp500, sp400, sp600, russell1000, russell2000) or a sector.",
+      type: "string",
+      defaultValue: "all",
+      example: "--universe sp500",
+      shot: { reportOnly: "picks the universe the report scans" },
+    },
+    {
+      key: "scan",
+      description: "Conditions and floors as JSON; the pane's default scan without it.",
+      type: "string",
+      defaultValue: "",
+      placeholder: "json",
+      shot: { reportOnly: "sets the conditions the report scans for" },
+    },
+  ],
+  columns: [
+    { key: "symbol", header: "Symbol" },
+    { key: "name", header: "Name" },
+    { key: "price", header: "Price", align: "right" },
+    { key: "changePercent", header: "Chg %", align: "right", format: (value) => formatPercentRaw(number(value)) },
+    { key: "relativeVolume", header: "RVol", align: "right", format: (value) => formatMultiple(number(value)) },
+    { key: "volume", header: "Volume", align: "right" },
+  ],
+  describe: "Live Scanner",
+  async load(args, ctx) {
+    const scan = headlessScan(String(args.options.universe ?? "all"), String(args.options.scan ?? ""));
+    const definition: LiveScanWireDefinition = {
+      version: 1,
+      universe: scan.universe.kind === "watchlist" ? { kind: "all" } : scan.universe,
+      conditions: scan.conditions,
+      ...(scan.minPrice != null ? { minPrice: scan.minPrice } : {}),
+      ...(scan.minMarketCap != null ? { minMarketCap: scan.minMarketCap } : {}),
+      ...(scan.minVolume != null ? { minVolume: scan.minVolume } : {}),
+    };
+    return projectLiveScan(await ctx.apiClient.getLiveScan(definition, ctx.signal), scan);
+  },
+};