gloomberb 0.18.3 → 0.18.4

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

@@ -1,12 +1,12 @@
-import { Box } from "../../../ui";
-import { Button, PaneStatusBody, PaneFooterScope, usePaneTabs } from "../../../components";
+import { Box, type ScrollBoxRenderable } from "../../../ui";
+import { Button, DetailScrollBody, KeyValueRow, Notice, PaneStatusBody, PaneFooterScope, usePaneTabs } from "../../../components";
 import { usePluginPaneState } from "../../runtime";
 import { EventAlertsPane } from "./events-pane";
 import { AlertHistoryPane } from "./history-pane";
-import { useCallback, useEffect, useMemo, useState, useSyncExternalStore } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore, type RefObject } from "react";
 import {
   confirmDialog,
-  DataTableView,
+  DataTableStackView,
   usePaneFooter,
   type DataTableCell,
   type DataTableColumn,
@@ -73,6 +73,39 @@ const ALERT_TABLE_CONTENT_WIDTH = ALERT_COLUMNS.reduce(
   2,
 );
 
+const DETAIL_ROW = { labelWidth: 10, emphasis: false } as const;
+
+/** "AAPL above 400.00": the rule, which titles its detail. */
+function alertTitle(alert: AlertRule): string {
+  return `${alert.symbol} ${conditionLabel(alert.condition).toLowerCase()} ${formatAlertTargetPrice(alert)}`;
+}
+
+/**
+ * One price alert in full: why it has no quote, when there is a reason, then
+ * the figures its row shortens. The title names the rule.
+ */
+function AlertDetail({ alert, scrollRef }: { alert: AlertRule; scrollRef: RefObject<ScrollBoxRenderable | null> }) {
+  const reason = alert.lastCheckError
+    ? alert.lastCheckError.includes(alert.symbol) ? alert.lastCheckError : `${alert.symbol}: ${alert.lastCheckError}`
+    : null;
+  return (
+    <DetailScrollBody ref={scrollRef} resetScrollKey={alert.id}>
+      <Box flexDirection="column">
+        {reason ? <Box paddingBottom={1}><Notice tone="warning">{reason}</Notice></Box> : null}
+        <KeyValueRow {...DETAIL_ROW} label="State" value={alert.status === "triggered" ? "Triggered" : "Active"} tone={alert.status === "triggered" ? "positive" : "muted"} />
+        {/* With no quote the reason above says why; the price and its distance wait for one. */}
+        {reason ? null : <KeyValueRow {...DETAIL_ROW} label="Current" value={formatCurrentPrice(alert, 24)} />}
+        {reason ? null : <KeyValueRow {...DETAIL_ROW} label="Away" value={formatAlertDistance(alert)} />}
+        {reason
+          ? alert.lastCheckedAt ? <KeyValueRow {...DETAIL_ROW} label="Checked" value={relativeTime(alert.lastCheckedAt)} tone="muted" /> : null
+          : <KeyValueRow {...DETAIL_ROW} label="Quote" value={formatQuoteChecked(alert)} tone="muted" />}
+        {alert.triggeredAt ? <KeyValueRow {...DETAIL_ROW} label="Alerted" value={relativeTime(alert.triggeredAt)} /> : null}
+        <KeyValueRow {...DETAIL_ROW} label="Armed" value={relativeTime(alert.armedAt ?? alert.createdAt)} tone="muted" />
+      </Box>
+    </DetailScrollBody>
+  );
+}
+
 export function AlertsPane(props: PaneProps) {
   const [tab, setTab] = usePluginPaneState<string>("tab", "prices");
   // A missed price alert opened from the Unread list selects its rule on Prices.
@@ -107,14 +140,18 @@ export function AlertsPane(props: PaneProps) {
 }
 
 function PriceAlertsPane({ focused, width, height }: PaneProps) {
-  const [alertsJson, setAlertsJson] = usePluginConfigState<string>(ALERTS_KEY, "[]");
-  const { openPluginCommandWorkflow } = usePluginAppActions();
+  const [alertsJson, setAlertsJson] = usePluginConfigState<unknown>(ALERTS_KEY, "[]");
+  const { openPluginCommandWorkflow, notify } = usePluginAppActions();
   const dialog = useDialog();
   const [selectedIdx, setSelectedIdx] = useState(0);
+  const [detailOpen, setDetailOpen] = useState(false);
+  // The alert the open detail shows, by id, so it never becomes whichever alert takes its row.
+  const detailAlertId = useRef<string | null>(null);
+  const detailScrollRef = useRef<ScrollBoxRenderable | null>(null);
   const showHorizontalScrollbar = ALERT_TABLE_CONTENT_WIDTH > width;
   const storeError = useMemo(() => readAlertsStoreError(alertsJson), [alertsJson]);
 
-  const { alerts, rows, quoteError } = useMemo(() => {
+  const { alerts, rows } = useMemo(() => {
     const parsed = deserializeAlerts(alertsJson);
     const activeAlerts = parsed.filter((a) => a.status === "active");
     const triggeredAlerts = parsed
@@ -124,7 +161,6 @@ function PriceAlertsPane({ focused, width, height }: PaneProps) {
     return {
       alerts: parsed,
       rows: [...activeAlerts, ...triggeredAlerts],
-      quoteError: parsed.find((alert) => alert.lastCheckError)?.lastCheckError ?? null,
     };
   }, [alertsJson]);
 
@@ -158,12 +194,16 @@ function PriceAlertsPane({ focused, width, height }: PaneProps) {
     return quote ? { ...alert, ...quoteAlertFields(quote, quote.receivedAt) } : alert;
   }), [liveEntries, rows]);
 
-  const savePaneAlerts = useCallback((next: AlertRule[] | ((current: AlertRule[]) => AlertRule[])) => {
-    setAlertsJson((currentJson) => {
+  const savePaneAlerts = useCallback((next: (current: AlertRule[]) => AlertRule[]): string | null => {
+    let error: string | null = null;
+    setAlertsJson((currentJson: unknown) => {
+      error = readAlertsStoreError(currentJson);
+      // The config hook skips persistence when the updater returns the unchanged value.
+      if (error) return currentJson;
       const current = deserializeAlerts(currentJson);
-      const resolved = typeof next === "function" ? next(current) : next;
-      return serializeAlerts(resolved);
+      return serializeAlerts(next(current));
     });
+    return error;
   }, [setAlertsJson]);
 
   const deleteAlert = useCallback(async (id: string) => {
@@ -175,15 +215,20 @@ function PriceAlertsPane({ focused, width, height }: PaneProps) {
       confirmLabel: "Delete",
     });
     if (!confirmed) return;
-    savePaneAlerts(alerts.filter((a) => a.id !== id));
+    const error = savePaneAlerts((current) => current.filter((a) => a.id !== id));
+    if (error) {
+      notify({ body: error, type: "error" });
+      return;
+    }
     setSelectedIdx((prev) => Math.max(0, Math.min(prev, rows.length - 2)));
-  }, [alerts, dialog, rows.length, savePaneAlerts]);
+  }, [alerts, dialog, notify, rows.length, savePaneAlerts]);
 
   const rearmAlert = useCallback((id: string) => {
-    savePaneAlerts(
-      alerts.map((a) => (a.id === id ? rebuildAlert(a) : a)),
+    const error = savePaneAlerts(
+      (current) => current.map((a) => (a.id === id ? rebuildAlert(a) : a)),
     );
-  }, [alerts, savePaneAlerts]);
+    if (error) notify({ body: error, type: "error" });
+  }, [notify, savePaneAlerts]);
 
   const startAddAlert = useCallback(() => {
     openPluginCommandWorkflow("set-alert");
@@ -195,6 +240,9 @@ function PriceAlertsPane({ focused, width, height }: PaneProps) {
   }, [deleteAlert, rows, selectedIdx]);
 
   const selectedRule = rows[selectedIdx];
+  // A quote one alert could not get is said on its row (Current and Quote),
+  // and in full in its detail.
+  const selectedShown = displayRows[selectedIdx];
   const selectedTarget = useMemo(() => selectedRule ? alertTarget(priceRuleSubject(selectedRule)) : null, [selectedRule]);
   const openTarget = useOpenAlertTarget();
 
@@ -222,11 +270,12 @@ function PriceAlertsPane({ focused, width, height }: PaneProps) {
           onApply={async (value) => {
             const parsed = parseAlertCommandValues({ shortcut: value });
             if (!parsed) throw new Error("Use SYMBOL above|below|crosses PRICE.");
-            savePaneAlerts((current) => current.map((alert) => (
+            const error = savePaneAlerts((current) => current.map((alert) => (
               alert.id === selected.id
                 ? editAlert(alert, parsed.symbol, parsed.condition, parsed.price)
                 : alert
             )));
+            if (error) throw new Error(error);
           }}
         />
       ),
@@ -236,12 +285,11 @@ function PriceAlertsPane({ focused, width, height }: PaneProps) {
   // Quotes come from the plugin's single background poll, which writes into the
   // same persisted store, so the pane never fetches on its own.
 
+  // A quote one alert could not get shows on that alert's row (Current and Quote), not here.
   usePaneFooter("alerts", () => ({
     info: storeError
       ? [{ id: "store-error", parts: [{ text: storeError, tone: "warning" as const }] }]
-      : quoteError
-        ? [{ id: "quote-error", parts: [{ text: quoteError, tone: "warning" as const }] }]
-        : [],
+      : [],
     hints: [
       { id: "add", key: "a", label: "dd alert", onPress: startAddAlert },
       ...alertViewHints(selectedTarget, openTarget),
@@ -271,7 +319,6 @@ function PriceAlertsPane({ focused, width, height }: PaneProps) {
     openTarget,
     rows,
     selectedIdx,
-    quoteError,
     rows.length,
     startAddAlert,
     storeError,
@@ -281,6 +328,20 @@ function PriceAlertsPane({ focused, width, height }: PaneProps) {
     setSelectedIdx((prev) => (rows.length === 0 ? 0 : Math.min(prev, rows.length - 1)));
   }, [rows.length]);
 
+  // While the detail is open, a change to the list keeps it on its alert: it follows the alert to its new row (re-armed
+  // or triggered, it changes group) and goes back to the list once the alert is deleted, from here or elsewhere.
+  // Declared before the effect below, so a delete is checked against the alert shown, not the row that takes its place.
+  useEffect(() => {
+    if (!detailOpen) return;
+    const index = rows.findIndex((row) => row.id === detailAlertId.current);
+    if (index < 0) setDetailOpen(false);
+    else setSelectedIdx(index);
+  }, [detailOpen, rows]);
+  // A new selection while it is open (an alert focused from Unread) is the alert it shows from then on.
+  useEffect(() => {
+    if (detailOpen) detailAlertId.current = rows[selectedIdx]?.id ?? null;
+  }, [detailOpen, selectedIdx]);
+
   // The footer hints bind a, e, d and m; `n` is a second key for adding.
   const handleTableKeyDown = useCallback((event: DataTableKeyEvent) => {
     if (!isPlainKey(event, "n")) return false;
@@ -322,7 +383,7 @@ function PriceAlertsPane({ focused, width, height }: PaneProps) {
       case "quote":
         return {
           text: formatQuoteChecked(alert),
-          color: colors.textDim,
+          color: alert.lastCheckError ? colors.negative : colors.textDim,
         };
       case "triggered":
         return {
@@ -333,8 +394,13 @@ function PriceAlertsPane({ focused, width, height }: PaneProps) {
   }, []);
 
   return (
-    <DataTableView<AlertRule, AlertColumn>
+    <DataTableStackView<AlertRule, AlertColumn>
       focused={focused}
+      detailOpen={detailOpen && !!selectedShown}
+      onBack={() => setDetailOpen(false)}
+      detailTitle={selectedShown ? alertTitle(selectedShown) : undefined}
+      detailContent={selectedShown ? <AlertDetail alert={selectedShown} scrollRef={detailScrollRef} /> : null}
+      detailScrollRef={detailScrollRef}
       selection={{
         kind: "index",
         selectedIndex: selectedIdx,
@@ -349,16 +415,18 @@ function PriceAlertsPane({ focused, width, height }: PaneProps) {
       sortColumnId={null}
       sortDirection="asc"
       getItemKey={(alert) => alert.id}
+      // Enter opens the alert; `m` re-arms a triggered one.
       onActivate={(alert) => {
-        if (alert.status === "triggered") rearmAlert(alert.id);
+        detailAlertId.current = alert.id;
+        setDetailOpen(true);
       }}
       renderCell={renderCell}
       selectedTextOverridesCellColor
-      emptyStateTitle="Saved alerts could not be read."
-      emptyStateHint={storeError ?? undefined}
-      emptyContent={storeError ? undefined : (
+      status={displayRows.length === 0 && storeError ? { error: storeError, subject: "price alerts" } : undefined}
+      emptyStateTitle="No alerts"
+      emptyContent={
         <PaneStatusBody empty emptyTitle="No alerts" actions={<Button label="Add alert" compact onPress={startAddAlert} />} />
-      )}
+      }
       showHorizontalScrollbar={showHorizontalScrollbar}
     />
   );

package/src/plugins/builtin/alerts/price.ts

@@ -0,0 +1,35 @@
+import { ambiguousNumberMessage, parsePastedNumber, type PastedNumber } from "../../../utils/decimal-comma";
+
+const PRICE_SCALES = { k: 1e3, m: 1e6, b: 1e9 } as const;
+/** A price typed with a scale after it: 81k, 1.5m. */
+const SCALED_PRICE = /^([+-]?\d[\d.,]*)\s*([kmb])$/i;
+
+/** What to type for an alert price, as the error for one that reads as none names it. */
+const PRICE_FORMAT = "type 81000 or 81k";
+
+const scaled = (value: number, scale: number) => Number((value * scale).toPrecision(15));
+
+/** A price as `parsePastedNumber` reads it, and `81k` is 81000: the scale applies to either reading of a comma and three digits. */
+export function parseAlertPrice(text: string): PastedNumber {
+  const match = SCALED_PRICE.exec(text.trim());
+  if (!match) return parsePastedNumber(text);
+  const scale = PRICE_SCALES[match[2]!.toLowerCase() as keyof typeof PRICE_SCALES];
+  const base = parsePastedNumber(match[1]);
+  if (base.kind === "number") return { kind: "number", value: scaled(base.value, scale) };
+  if (base.kind === "ambiguous") return { kind: "ambiguous", thousands: scaled(base.thousands, scale), decimal: scaled(base.decimal, scale) };
+  return base;
+}
+
+/**
+ * An alert price as every way of adding an alert reads it (`parseAlertPrice`):
+ * the number, or an error that names what to type. A comma before exactly
+ * three digits (`81,000`) could be thousands or a decimal comma, so it throws
+ * naming both readings rather than storing either; text that is no number
+ * throws with an example.
+ */
+export function readAlertPrice(text: string): number {
+  const price = parseAlertPrice(text);
+  if (price.kind === "ambiguous") throw new Error(ambiguousNumberMessage(text, price));
+  if (price.kind === "invalid") throw new Error(`Alert price must be a number, got "${text.trim()}"; ${PRICE_FORMAT}.`);
+  return price.value;
+}

package/src/plugins/builtin/alerts/quotes.ts

@@ -66,3 +66,27 @@ export function quoteErrorAlertFields(
     lastCheckError: error,
   };
 }
+
+/** How many times the last price a target may be, either way, before it reads as a typo or another instrument's price. */
+const MAX_TARGET_RATIO = 10;
+
+/** A price as typed or quoted, never in exponent form: 85,000, 37.35, 0.0000001234. */
+const priceText = (value: number) => value.toLocaleString("en-US", Math.abs(value) >= 1
+  ? { maximumFractionDigits: 2 }
+  : { maximumSignificantDigits: 4 });
+
+/**
+ * Why a price target is refused: more than ten times the last price, or under
+ * a tenth of it, which is a slip or another instrument's price (bitcoin's,
+ * typed on the BTC fund). `coinNote` is the note `quote` gives a bare coin
+ * ticker on a listing that is not the coin, which says what to use instead.
+ * Null when the target is near enough, or there is no positive last price to
+ * measure it against.
+ */
+export function farTargetMessage(symbol: string, target: number, last: number | null | undefined, coinNote: string | null): string | null {
+  if (last == null || !Number.isFinite(last) || last <= 0) return null;
+  const above = target > last * MAX_TARGET_RATIO;
+  if (!above && target >= last / MAX_TARGET_RATIO) return null;
+  const how = above ? `more than ${MAX_TARGET_RATIO} times` : `under 1/${MAX_TARGET_RATIO} of`;
+  return `A target of ${priceText(target)} is ${how} ${symbol}'s last price of ${priceText(last)}. ${coinNote ?? "Check the price and the symbol."}`;
+}

package/src/plugins/builtin/alerts/research-builder.ts

@@ -1,51 +1,102 @@
 import type { GloomPlugin } from "../../../types/plugin";
-import { DEFAULT_LEAD_DAYS, isResearchAlertKind, MACRO_ALERT_EVENTS, normalizeResearchRule, readResearchRule, RESEARCH_ALERT_FORMS, type MacroAlertEvent, type ResearchAlertKind } from "./research-rules";
+import { DEFAULT_LEAD_DAYS, isResearchAlertKind, MACRO_ALERT_EVENTS, normalizeResearchRule, readResearchRule, RESEARCH_ALERT_FORMS, type IvLevelMetric, type MacroAlertEvent, type ResearchAlertKind } from "./research-rules";
 import type { EventAlertRule } from "./events";
 
 /** What a macro event is called in a rule, a list and a notification. */
 export const MACRO_EVENT_NAMES: Record<MacroAlertEvent, string> = { cpi: "CPI release", fomc: "FOMC decision" };
+/** CPI and FOMC and any other calendar release are one kind of alert to the reader, whichever list keeps the rule. */
 export const RESEARCH_LABELS: Record<ResearchAlertKind, string> = {
-  perps_threshold: "Perpetual threshold", earnings_date: "Earnings date", macro_event: "Macro event", filing_type: "SEC filing", news_keyword: "News keyword", analyst_change: "Analyst change", fifty_two_week: "52-week range", unusual_volume: "Unusual volume", short_interest_change: "Short interest", insider_trade: "Insider trade", iv_spike: "IV spike", options_flow: "Options flow",
+  perps_threshold: "Perpetual threshold", earnings_date: "Earnings date", macro_event: "Macro event", calendar_event: "Macro event", filing_type: "SEC filing", news_keyword: "News keyword", analyst_change: "Analyst change", fifty_two_week: "52-week range", unusual_volume: "Unusual volume", short_interest_change: "Short interest", insider_trade: "Insider trade", iv_spike: "IV spike", iv_level: "IV level", options_flow: "Options flow", hiring_move: "Hiring move",
 };
+/** What an IV level rule follows, as the form, a list and a notification name it. */
+export const IV_LEVEL_NAMES: Record<IvLevelMetric, string> = { atm: "30d ATM IV", rr: "30d 25D RR" };
+/** An IV level in its unit: an ATM IV in percent, a risk reversal in signed vol points. */
+export function formatIvLevel(metric: IvLevelMetric, value: number): string {
+  const rounded = Number(value.toFixed(2));
+  return metric === "atm" ? `${rounded}%` : `${rounded > 0 ? "+" : ""}${rounded} pts`;
+}
+/**
+ * An OCC contract that has not expired, for the IV spike form's example: an
+ * AAPL call on the monthly expiry (the third Friday) two months from `now`.
+ */
+function occContractExample(now = new Date()): string {
+  const month = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() + 2, 1));
+  const thirdFriday = 1 + ((5 - month.getUTCDay() + 7) % 7) + 14;
+  const two = (value: number) => String(value).padStart(2, "0");
+  return `AAPL${two(month.getUTCFullYear() % 100)}${two(month.getUTCMonth() + 1)}${two(thirdFriday)}C00300000`;
+}
 type Command = Parameters<Parameters<NonNullable<GloomPlugin["setup"]>>[0]["registerCommand"]>[0];
 type Field = NonNullable<Command["wizard"]>[number];
+/** An earnings alert goes off days before the report, or once its results are out. */
+const EARNINGS_ALERT_WHEN = [{ value: "before", label: "Days before the date" }, { value: "results", label: "When results are out" }];
 const choices = (values: string[]) => values.map(value => ({label: value.replaceAll("_", " "), value}));
-export const researchWizardFields: Field[] = Object.keys(RESEARCH_LABELS).flatMap(kind => {
+/**
+ * The kinds Add Event Alert offers. A calendar event is added by name from the
+ * shell (`alerts add "NBS PMI"`), which matches it against the calendar; the
+ * form keeps its CPI and FOMC choice under Macro event.
+ */
+export const RESEARCH_FORM_KINDS = (Object.keys(RESEARCH_LABELS) as ResearchAlertKind[]).filter((kind) => kind !== "calendar_event");
+export const researchWizardFields: Field[] = RESEARCH_FORM_KINDS.flatMap(kind => {
   const fields: Field[] = kind === "perps_threshold" ? [
     { key: "marketId", label: "Market", type: "text", placeholder: "hyperliquid:default:BTC", required: true },
     { key: "metric", label: "Metric", type: "select", defaultValue: "funding8h", options: [{ value: "funding8h", label: "Funding / 8h" }, { value: "oiChange24h", label: "OI change / 24h" }, { value: "premium", label: "Premium vs oracle" }, { value: "closedMarketPremium", label: "Closed-market premium" }] },
     { key: "direction", label: "Crossing", type: "select", defaultValue: "above", options: choices(["above", "below"]) },
     { key: "threshold", label: "Threshold (%)", type: "number", defaultValue: "0.1" },
-  ] : kind === "iv_spike" ? [{key:"contract", label:"OCC contract", type:"text", placeholder:"AAPL261016C00300000", required:true}]
+  ] : kind === "iv_spike" ? [{key:"contract", label:"OCC contract", type:"text", placeholder:occContractExample(), required:true}]
     : kind === "macro_event" ? [{key:"event", label:"Release", type:"select", defaultValue:"cpi", options:MACRO_ALERT_EVENTS.map((value) => ({value, label:MACRO_EVENT_NAMES[value]}))}]
+    // HIRE covers listings worldwide; a non-US one is written with its venue.
+    : kind === "hiring_move" ? [{key:"symbol", label:"Symbol", type:"text", placeholder:"RIVN or ADYEN:AMS", required:true}]
     : [{key:"symbol",label:kind === "news_keyword" ? "Symbol (optional)" : kind === "options_flow" ? "Symbol (blank: portfolio and watchlists)" : "Symbol",type:"text",placeholder:"AAPL", required:kind !== "news_keyword" && kind !== "options_flow"},
       {key:"exchange",label:"US exchange",type:"select",defaultValue:"US",options:choices(["US","NASDAQ","NYSE","ARCA","AMEX","BATS","OTC"])}];
-  if (kind === "earnings_date") fields.push({key:"leadDays",label:"Days before earnings",type:"number",defaultValue:String(DEFAULT_LEAD_DAYS)});
+  if (kind === "earnings_date") {
+    fields.push({key:"when",label:"Alert",type:"select",defaultValue:"before",options:EARNINGS_ALERT_WHEN});
+    fields.push({key:"leadDays",label:"Days before earnings",type:"number",defaultValue:String(DEFAULT_LEAD_DAYS)});
+  }
   if (kind === "macro_event") fields.push({key:"leadDays",label:"Days before",type:"number",defaultValue:String(DEFAULT_LEAD_DAYS)});
   if (kind === "filing_type") fields.push({key:"form",label:"Filing type",type:"select",defaultValue:"8-K",options:choices([...RESEARCH_ALERT_FORMS])});
   if (kind === "news_keyword") fields.push({key:"keyword",label:"Keyword or phrase",type:"text",required:true,placeholder:"buyback"});
-  const directions: Partial<Record<ResearchAlertKind, string[]>> = {analyst_change:["any","upgrade","downgrade"],fifty_two_week:["high","low"],short_interest_change:["either","increase","decrease"],insider_trade:["either","buy","sell"],options_flow:["any","calls","puts"]};
+  if (kind === "iv_level") fields.push({key:"metric",label:"Measure",type:"select",defaultValue:"atm",options:[{value:"atm",label:"30d ATM IV (%)"},{value:"rr",label:"30d 25D risk reversal (vol pts)"}]});
+  const directions: Partial<Record<ResearchAlertKind, string[]>> = {iv_level:["above","below"],analyst_change:["any","upgrade","downgrade"],fifty_two_week:["high","low"],short_interest_change:["either","increase","decrease"],insider_trade:["either","buy","sell"],options_flow:["any","calls","puts"],hiring_move:["either","accelerating","slowing"]};
   const direction = directions[kind as ResearchAlertKind];
   if (direction) fields.push({key:"direction",label:kind === "options_flow" ? "Calls or puts" : "Direction",type:"select",defaultValue:direction[0],options:choices(direction)});
   if (kind === "options_flow") {
     fields.push({key:"threshold",label:"Minimum premium ($)",type:"number",defaultValue:"1000000"});
     fields.push({key:"print",label:"Print type",type:"select",defaultValue:"any",options:[{label:"any print",value:"any"},{label:"sweeps only",value:"sweep"},{label:"blocks only",value:"block"}]});
   }
+  if (kind === "iv_level") fields.push({key:"threshold",label:"Level (IV %, RR vol pts)",type:"number",placeholder:"35",required:true});
   if (kind === "unusual_volume" || kind === "short_interest_change" || kind === "iv_spike") fields.push({key:"threshold",label:kind === "unusual_volume" ? "Volume / prior 20-session average" : kind === "iv_spike" ? "IV rise (percentage points)" : "Settlement change (%)",type:"number",defaultValue:kind === "unusual_volume" ? "2" : kind === "iv_spike" ? "5" : "10"});
-  return fields.map(field => ({...field, key:`${kind}:${field.key}`, dependsOn:{key:"event",value:kind}}));
+  return fields.map(field => ({...field, key:`${kind}:${field.key}`, dependsOn: kind === "earnings_date" && field.key === "leadDays"
+    // The lead time is for an alert before the date, not one waiting for results.
+    ? [{key:"event",value:kind}, {key:"earnings_date:when",value:"before"}]
+    : {key:"event",value:kind}}));
 });
+/** The Add Event Alert form filled in for an earnings alert on `symbol` that goes off once its results are out, as ERN opens it. */
+export function earningsResultsAlertValues(symbol: string): Record<string, string> {
+  return { event: "earnings_date", "earnings_date:symbol": symbol, "earnings_date:when": "results" };
+}
 export function createResearchAlert(kind: string, values: Record<string,string>, now = Date.now()): EventAlertRule {
   if (!isResearchAlertKind(kind)) throw new Error("Choose an alert event.");
   const input: Record<string,unknown> = {version:1};
   for (const [key,value] of Object.entries(values)) if (key.startsWith(`${kind}:`)) {
     const field = key.slice(kind.length+1);
     if (kind === "perps_threshold" && field === "threshold" && value.trim()) input[field] = Number(value) / 100;
+    // A level reads as typed, signed (a risk reversal is often below zero) and with or without its unit.
+    else if (kind === "iv_level" && field === "threshold" && value.trim()) {
+      const unitError = ivLevelUnitError(values["iv_level:metric"] === "rr" ? "rr" : "atm", value);
+      if (unitError) throw new Error(`${unitError}.`);
+      input[field] = parseIvLevel(value);
+    }
     else if (value.trim()) input[field] = field === "threshold" || field === "leadDays" ? parseAmount(value) : value;
   }
   const value = normalizeResearchRule(kind,input);
   if (!value) throw new Error(kind === "options_flow"
     ? "Check the symbol and US exchange. The minimum premium is $50,000."
-    : "Check the symbol, US exchange and event fields. Use a valid OCC contract for IV alerts.");
+    : kind === "hiring_move" ? "Check the symbol. Write a non-US listing with its exchange, as ADYEN:AMS."
+    : kind === "iv_level"
+      ? "Check the symbol and US exchange. An ATM IV level is 1 to 500 (%), a risk reversal -50 to 50 (vol pts)."
+      : kind === "iv_spike"
+        ? `Use a valid OCC contract, such as ${occContractExample()}.`
+        : "Check the symbol, US exchange and event fields.");
   return {id:crypto.randomUUID(),kind,target:"rule",value,createdAt:now,status:"active"};
 }
 /** "2.5", "1,000,000", "$250k" and "1.5m" all read as numbers; anything else is NaN. */
@@ -55,11 +106,27 @@ export function parseAmount(value: string): number {
   const scale = { k: 1e3, m: 1e6, b: 1e9 }[match[2]?.toLowerCase() as "k" | "m" | "b"] ?? 1;
   return Number(match[1]!.replace(/[,_]/g, "")) * scale;
 }
-/** $1M, $250K, $1.5B. */
+const IV_LEVEL_PATTERN = /^([+-]?\d+(?:\.\d+)?)\s*(%|pts?|points?|vol pts?|vol points?)?$/i;
+/** "35", "35%", "-4.5", "+2 pts" and "-5.5 vol points" read as numbers; anything else is NaN. */
+export function parseIvLevel(value: string): number {
+  const match = IV_LEVEL_PATTERN.exec(value.trim());
+  return match ? Number(match[1]) : Number.NaN;
+}
+/** Why a level typed with a unit does not suit its measure (`5 pts` for an ATM IV, `-5%` for a risk reversal); null when it does or has none. */
+export function ivLevelUnitError(metric: IvLevelMetric, value: string): string | null {
+  const unit = IV_LEVEL_PATTERN.exec(value.trim())?.[2];
+  if (!unit) return null;
+  const percent = unit === "%";
+  if (metric === "atm" && !percent) return `An ATM IV level is in %, not vol points ("${value.trim()}")`;
+  if (metric === "rr" && percent) return `A risk reversal is in vol points, not % ("${value.trim()}")`;
+  return null;
+}
+/** $1M, $250K, $1.5B, and $500 under a thousand. */
 export function formatPremium(value: number): string {
   if (value >= 1e9) return `$${Number((value / 1e9).toFixed(1))}B`;
   if (value >= 1e6) return `$${Number((value / 1e6).toFixed(1))}M`;
-  return `$${Math.round(value / 1e3)}K`;
+  if (value >= 1e3) return `$${Number((value / 1e3).toFixed(1))}K`;
+  return `$${Number(Math.max(0, value).toFixed(2))}`;
 }
 export function researchAlertDescription(rule: EventAlertRule): string {
   if (!isResearchAlertKind(rule.kind)) return rule.value;
@@ -68,15 +135,21 @@ export function researchAlertDescription(rule: EventAlertRule): string {
   const symbol = config.symbol ?? "All symbols";
   switch(rule.kind) {
     case "perps_threshold": return `${config.marketId} · ${config.metric} ${config.direction} ${((config.threshold ?? 0) * 100).toFixed(3)}%`;
-    case "earnings_date": return `${symbol} · ${config.leadDays}d before`;
+    case "earnings_date": return `${symbol} · ${config.when === "results" ? "results" : `${config.leadDays}d before`}`;
     case "macro_event": return `${MACRO_EVENT_NAMES[config.event as MacroAlertEvent] ?? config.event} · ${config.leadDays}d before`;
+    case "calendar_event": return `${config.event} (${config.country}) · ${config.leadDays}d before`;
     case "filing_type": return `${symbol} · ${config.form}`;
     case "news_keyword": return `${symbol} · ${config.keyword}`;
     case "analyst_change": case "insider_trade": return `${symbol} · ${config.direction}`;
+    case "hiring_move": return `${symbol} · ${config.direction === "either" ? "accelerating or slowing" : config.direction}`;
     case "fifty_two_week": return `${symbol} · 52w ${config.direction}`;
     case "unusual_volume": return `${symbol} · ≥${config.threshold}× 20d`;
     case "short_interest_change": return `${symbol} · ${config.direction} ≥${config.threshold}%`;
     case "iv_spike": return `${config.contract} · +${config.threshold}pt`;
+    case "iv_level": {
+      const metric = config.metric as IvLevelMetric;
+      return `${symbol} · ${IV_LEVEL_NAMES[metric]} ${config.direction} ${formatIvLevel(metric, config.threshold ?? 0)}`;
+    }
     case "options_flow": return [
       config.symbol ?? "Portfolio and watchlists",
       `≥${formatPremium(config.threshold ?? 0)}`,

package/src/plugins/builtin/alerts/research-rules.ts

@@ -2,6 +2,7 @@
 const RESEARCH_ALERT_KINDS = [
   "earnings_date",
   "macro_event",
+  "calendar_event",
   "filing_type",
   "news_keyword",
   "analyst_change",
@@ -10,8 +11,10 @@ const RESEARCH_ALERT_KINDS = [
   "short_interest_change",
   "insider_trade",
   "iv_spike",
+  "iv_level",
   "options_flow",
   "perps_threshold",
+  "hiring_move",
 ] as const
 export type ResearchAlertKind = (typeof RESEARCH_ALERT_KINDS)[number]
 export interface ResearchAlertConfig {
@@ -26,10 +29,32 @@ export interface ResearchAlertConfig {
   contract?: string
   /** Options flow: which prints count (any, sweep or block). */
   marketId?: string
-  metric?: "funding8h" | "oiChange24h" | "premium" | "closedMarketPremium"
+  /** Perpetuals: the market figure. IV level: `atm`, the 30-day ATM IV, or `rr`, the 30-day 25-delta risk reversal. */
+  metric?: "funding8h" | "oiChange24h" | "premium" | "closedMarketPremium" | IvLevelMetric
   print?: string
-  /** Macro event: which scheduled release (`MACRO_ALERT_EVENTS`). */
+  /**
+   * Macro event: which scheduled release (`MACRO_ALERT_EVENTS`). Calendar
+   * event: the release's name as the economic calendar lists it.
+   */
   event?: string
+  /** Calendar event: the country the calendar lists the release for (CN, US, DE for a German release). */
+  country?: string
+  /** Calendar event: who publishes it, when the calendar names them, which tells apart releases of one name. */
+  publisher?: string
+  /**
+   * Earnings: `results` goes off when the report's actual EPS is out, rather
+   * than `leadDays` before the date. Such a rule keeps a lead of 0, so a
+   * server that reads only the lead alerts on the day instead.
+   */
+  when?: "results"
+}
+/** What an IV level rule follows on its symbol's surface: 30-day ATM IV (in %) or 30-day 25-delta risk reversal (in vol points). */
+const IV_LEVEL_METRICS = ["atm", "rr"] as const
+export type IvLevelMetric = (typeof IV_LEVEL_METRICS)[number]
+/** The levels an IV level rule takes: an ATM IV in percent, a risk reversal in vol points either side of zero. */
+export const IV_LEVEL_RANGES: Record<IvLevelMetric, { min: number; max: number }> = {
+  atm: { min: 1, max: 500 },
+  rr: { min: -50, max: 50 },
 }
 /** Days before a scheduled event (earnings, a macro release) an alert fires when none is given, and the most it takes. */
 export const DEFAULT_LEAD_DAYS = 1
@@ -39,6 +64,14 @@ export const MACRO_ALERT_EVENTS = ["cpi", "fomc"] as const
 export type MacroAlertEvent = (typeof MACRO_ALERT_EVENTS)[number]
 export const isMacroAlertEvent = (value: unknown): value is MacroAlertEvent =>
   MACRO_ALERT_EVENTS.includes(value as MacroAlertEvent)
+/** The longest calendar event name or publisher a rule keeps. */
+const MAX_CALENDAR_TEXT = 120
+/** A calendar event's name or publisher as a rule keeps it: trimmed, single-spaced, printable; empty when it is none. */
+const calendarText = (value: unknown): string => {
+  if (typeof value !== "string") return ""
+  const text = value.trim().replace(/\s+/g, " ")
+  return text.length <= MAX_CALENDAR_TEXT && !/[\u0000-\u001f]/.test(text) ? text : ""
+}
 export const RESEARCH_ALERT_FORMS = [
   "8-K",
   "10-K",
@@ -98,6 +131,14 @@ export function normalizeResearchRule(
       const event = typeof input.event === "string" ? input.event.trim().toLowerCase() : ""
       if (!isMacroAlertEvent(event)) return null
       result.event = event
+    } else if (kind === "calendar_event") {
+      const event = calendarText(input.event)
+      const country = typeof input.country === "string" ? input.country.trim().toUpperCase() : ""
+      if (!event || !/^[A-Z]{2}$/.test(country)) return null
+      result.event = event
+      result.country = country
+      const publisher = calendarText(input.publisher)
+      if (publisher) result.publisher = publisher
     } else if (kind === "perps_threshold") {
       const marketId = typeof input.marketId === "string" ? input.marketId.trim() : "";
       const metric = input.metric;
@@ -113,6 +154,14 @@ export function normalizeResearchRule(
       result.symbol = identity.symbol
       result.exchange = "US"
       result.contract = identity.contract
+    } else if (kind === "hiring_move") {
+      // A HIRE company: any listing, a world one with its venue (ADYEN:AMS).
+      const symbol =
+        typeof input.symbol === "string"
+          ? input.symbol.trim().toUpperCase()
+          : ""
+      if (!/^[A-Z0-9][A-Z0-9.:-]{0,31}$/.test(symbol)) return null
+      result.symbol = symbol
     } else if (
       (kind !== "news_keyword" && kind !== "options_flow") ||
       input.symbol
@@ -162,8 +211,17 @@ export function normalizeResearchRule(
         numeric("threshold", 0.001, -100, 100);
         direction(["above", "below"], "above");
         break;
-      case "earnings_date":
+      case "earnings_date": {
+        const when = input.when ?? "before"
+        if (when === "results") {
+          result.leadDays = 0
+          result.when = "results"
+        } else if (when === "before") numeric("leadDays", DEFAULT_LEAD_DAYS, 0, MAX_LEAD_DAYS, true)
+        else throw new Error()
+        break
+      }
       case "macro_event":
+      case "calendar_event":
         numeric("leadDays", DEFAULT_LEAD_DAYS, 0, MAX_LEAD_DAYS, true)
         break
       case "filing_type": {
@@ -211,9 +269,24 @@ export function normalizeResearchRule(
       case "insider_trade":
         direction(["buy", "sell", "either"], "either")
         break
+      case "hiring_move":
+        direction(["either", "accelerating", "slowing"], "either")
+        break
       case "iv_spike":
         numeric("threshold", 5, 0.1, 100)
         break
+      case "iv_level": {
+        const metric = input.metric ?? "atm"
+        if (typeof metric !== "string" || !IV_LEVEL_METRICS.includes(metric as IvLevelMetric))
+          throw new Error()
+        result.metric = metric as IvLevelMetric
+        direction(["above", "below"], "above")
+        const range = IV_LEVEL_RANGES[metric as IvLevelMetric]
+        // No default: a level is what the rule is about.
+        if (input.threshold == null) throw new Error()
+        numeric("threshold", 0, range.min, range.max)
+        break
+      }
       case "options_flow": {
         // Premium in dollars; Cloud records nothing under $50K.
         numeric("threshold", 1_000_000, 50_000, 1_000_000_000)