@gloom-sh/terminal 0.0.0-stage → 0.19.0

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

@@ -0,0 +1,100 @@
+import type { MnaDealsParams, MnaRegionFilter, MnaStatusFilter, MnaTargetFilter } from "../../../api-client/mna";
+import type { HeadlessPaneColumn, HeadlessPaneDefinition } from "../../../types/plugin";
+import { fetchMnaDeals } from "./client";
+import { dealsSymbol, formatDealValue, formatExpectedClose, stageLabel, termsLabel } from "./model";
+import { REPORT_ROWS } from "../shared/headless-options";
+
+const text = (value: unknown) => (typeof value === "string" ? value : "");
+
+const COLUMNS: HeadlessPaneColumn[] = [
+  { key: "announced", header: "Announced" },
+  { key: "target", header: "Target" },
+  { key: "targetSymbol", header: "Symbol" },
+  { key: "acquirer", header: "Acquirer" },
+  { key: "terms", header: "Terms" },
+  { key: "value", header: "Value", align: "right" },
+  { key: "stage", header: "Stage" },
+  { key: "expectedClose", header: "Close", format: (value) => formatExpectedClose(text(value) || null) },
+  { key: "closed", header: "Closed" },
+];
+
+export const mnaHeadless: HeadlessPaneDefinition<"rows"> = {
+  shape: "rows",
+  freshness: { status: "not-a-feed", basis: "reported deals" },
+  argument: {
+    kind: "ticker",
+    optional: true,
+    description: "Optional ticker: deals where it is the target or the buyer.",
+  },
+  discovery: {
+    aliases: ["MA"],
+    dataRequirements: ["Gloom Cloud M&A deals read from news stories, press releases and SEC filings"],
+    limitations: [
+      "Free accounts see deals 7 days after they were first reported.",
+      "Spreads need live quotes and are drawn by the pane, not listed here.",
+      "A private or non-US deal completes only when a story reports it.",
+    ],
+  },
+  options: [
+    { key: "status", description: "Deal status.", type: "enum", defaultValue: "pending", values: ["pending", "talks", "completed", "terminated", "all"].map((value) => ({ value })) },
+    { key: "target", description: "Public or private targets.", type: "enum", defaultValue: "public", values: ["all", "public", "private"].map((value) => ({ value })) },
+    { key: "region", description: "US or international targets.", type: "enum", defaultValue: "all", values: ["all", "us", "intl"].map((value) => ({ value })) },
+    { key: "query", shot: { reportOnly: "searches the text report, and the pane opens without a search" }, description: "Company name or ticker.", type: "string" },
+    { key: "limit", shot: REPORT_ROWS, aliases: ["count", "rows"], description: "Maximum rows.", type: "integer", defaultValue: 50, minimum: 1, maximum: 100 },
+  ],
+  describe: (args) => `M&A${args.symbols[0] ? ` | ${args.symbols[0]}` : ""} | ${text(args.options.status) || "pending"}`,
+  // The filters the pane keeps, as asked for; one company's deals keep their status apart and have no target or region filter.
+  shotState: (args, _load, given) => {
+    const symbol = args.symbols[0];
+    const unused = symbol ? ["target", "region"].filter((key) => given.has(key)) : [];
+    if (unused.length) {
+      throw new Error(`One company's deals have no ${unused.map((key) => `--${key}`).join(" or ")} filter. Drop it from shot, or leave out ${symbol} for the market's deals.`);
+    }
+    const prefix = symbol ? "ticker." : "";
+    const state = Object.fromEntries(["status", "target", "region"].filter((key) => given.has(key)).map((key) => [`${prefix}${key}`, args.options[key]]));
+    return Object.keys(state).length ? { pluginState: { "ticker-research": state } } : {};
+  },
+  async load(args, ctx) {
+    const symbol = args.symbols[0];
+    // A listing abroad (ATH:TSX) asks by the quote symbol its deals are filed under (ATH.TO), as the pane does.
+    const filed = symbol ? dealsSymbol(symbol) : "";
+    const params: MnaDealsParams = {
+      status: ((args.options.status as MnaStatusFilter | undefined) ?? (symbol ? "all" : "pending")),
+      target: symbol ? undefined : (args.options.target as MnaTargetFilter | undefined),
+      region: symbol ? undefined : (args.options.region as MnaRegionFilter | undefined),
+      symbol: filed || undefined,
+      query: text(args.options.query) || undefined,
+      limit: Number(args.options.limit ?? 50),
+    };
+    const payload = await fetchMnaDeals(params, ctx.apiClient);
+    return {
+      columns: COLUMNS,
+      rows: payload.deals.map((deal) => ({
+        id: deal.id,
+        announced: deal.announced,
+        target: deal.target.name,
+        targetSymbol: deal.target.symbol,
+        targetCountry: deal.target.country,
+        acquirer: deal.acquirer?.name ?? null,
+        acquirerSymbol: deal.acquirer?.symbol ?? null,
+        status: deal.status,
+        stage: stageLabel(deal),
+        terms: termsLabel(deal.terms),
+        cashPerShare: deal.terms.cashPerShare,
+        exchangeRatio: deal.terms.exchangeRatio,
+        ratioSymbol: deal.terms.ratioSymbol,
+        election: deal.terms.election === true,
+        currency: deal.terms.currency,
+        value: formatDealValue(deal.value, deal.valueCurrency),
+        valueUsd: deal.valueUsd,
+        expectedClose: deal.expectedClose,
+        closed: deal.closed,
+        headline: deal.headline,
+      })),
+      errors: payload.lockedDeals > 0 ? [`${payload.lockedDeals} deals from the last ${payload.delayDays} days need Gloom Pro`] : [],
+      metadata: {
+        asOf: payload.asOf, access: payload.access, delayDays: payload.delayDays, hasMore: payload.hasMore,
+      },
+    };
+  },
+};

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

@@ -0,0 +1,74 @@
+import type { PluginModule } from "../plugin-module";
+import { mnaDealCache, mnaDealsCache } from "./client";
+import { DISTRESS_CACHES } from "./distress/client";
+import { distressHeadless } from "./distress/headless";
+import { mnaHeadless } from "./headless";
+import { MNA_PANE_ID } from "./model";
+import { MnaPane, MnaTickerTab } from "./pane";
+
+export const mnaModule: PluginModule = {
+  setup(ctx) {
+    mnaDealsCache.attach(ctx.persistence);
+    mnaDealCache.attach(ctx.persistence);
+    for (const cache of DISTRESS_CACHES) cache.attach(ctx.persistence);
+    ctx.registerTickerResearchTab({
+      id: "mna",
+      name: "M&A",
+      order: 36,
+      component: MnaTickerTab,
+      instruments: ["equity"],
+    });
+  },
+
+  dispose() {
+    mnaDealsCache.reset();
+    mnaDealCache.reset();
+    for (const cache of DISTRESS_CACHES) cache.reset();
+  },
+
+  panes: [
+    {
+      id: MNA_PANE_ID,
+      name: "M&A",
+      icon: "M",
+      component: MnaPane,
+      // MA and DIST open this pane: DIST sets the tab param, MA a ticker.
+      identitySettings: ["ticker"],
+      defaultPosition: "right",
+      tickerFollower: true,
+      instruments: ["equity"],
+      defaultMode: "floating",
+      defaultFloatingSize: { width: 120, height: 30 },
+      tableExport: true,
+    },
+  ],
+
+  paneTemplates: [
+    {
+      id: "mna-pane",
+      paneId: MNA_PANE_ID,
+      label: "M&A",
+      description: "Pending, rumored and closed mergers and acquisitions, with live arbitrage spreads on listed targets.",
+      keywords: ["m&a", "mna", "merger", "mergers", "acquisition", "acquisitions", "takeover", "tender offer", "deal", "arbitrage", "spread"],
+      shortcut: { prefix: "MA", argPlaceholder: "ticker", argKind: "ticker", argOptional: true },
+      headless: mnaHeadless,
+      createInstance: (_context, options) => {
+        const symbol = (options?.symbol ?? options?.arg)?.trim().toUpperCase();
+        return symbol
+          ? { instanceId: `${MNA_PANE_ID}:${symbol}`, title: `M&A ${symbol}`, binding: { kind: "fixed" as const, symbol }, placement: "floating", settings: { ticker: symbol } }
+          : { placement: "floating" };
+      },
+    },
+    {
+      // The M&A pane on its Distress tab, not a pane of its own.
+      id: "distress-pane",
+      paneId: MNA_PANE_ID,
+      label: "Distress",
+      description: "Dated public records about companies in difficulty: US 8-K bankruptcy, obligation and listing filings, SEC going-concern disclosures, Taiwan listing designations, and French and UK insolvency notices.",
+      keywords: ["distress", "distressed", "bankruptcy", "chapter 11", "receivership", "going concern", "substantial doubt", "insolvency", "liquidation", "administration", "delisting", "delisted", "suspended", "special situations"],
+      shortcut: { prefix: "DIST" },
+      headless: distressHeadless,
+      createInstance: () => ({ placement: "floating", params: { tab: "distress" } }),
+    },
+  ],
+};

package/src/plugins/builtin/mna/model.ts

@@ -0,0 +1,282 @@
+import type { MnaDeal, MnaStatus, MnaTerms } from "../../../api-client/mna";
+import type { Quote } from "../../../types/financials";
+import { getListingSymbol } from "../../../sources/listing-symbols";
+import { parsePublicTickerKey } from "../../../utils/exchanges";
+import { formatCompact } from "../../../utils/format";
+import { nonUsSecListingVenue } from "../../../utils/sec";
+
+export const MNA_PANE_ID = "mna";
+export const MISSING = "--";
+
+const MS_PER_DAY = 86_400_000;
+
+const CURRENCY_SIGNS: Record<string, string> = { USD: "$", EUR: "€", GBP: "£", JPY: "¥", CNY: "¥", INR: "₹", KRW: "₩" };
+
+/** "$10.50", "€4.20", "1,250p", "CHF 88.00". */
+export function formatPerShare(amount: number, currency: string | null, maxDigits = 4): string {
+  const code = (currency ?? "USD").trim();
+  if (code === "GBp" || code === "GBX") return `${amount.toLocaleString("en-US", { maximumFractionDigits: 2 })}p`;
+  const fixed = amount.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: maxDigits });
+  const sign = CURRENCY_SIGNS[code.toUpperCase()];
+  return sign ? `${sign}${fixed}` : `${code} ${fixed}`;
+}
+
+/** A headline amount: "$1.8B", "€420M", "GBP 1.2B". */
+export function formatDealValue(value: number | null, currency: string | null): string {
+  if (value == null || !Number.isFinite(value) || value <= 0) return MISSING;
+  const compact = formatCompact(value, { fixedDecimals: false });
+  const code = currency?.trim().toUpperCase() ?? "";
+  if (!code) return compact;
+  const sign = CURRENCY_SIGNS[code];
+  return sign ? `${sign}${compact}` : `${code} ${compact}`;
+}
+
+function ratioLabel(ratio: number, symbol: string | null): string {
+  const shares = ratio.toLocaleString("en-US", { maximumFractionDigits: 4 });
+  return symbol ? `${shares} ${symbol}` : `${shares} sh`;
+}
+
+/**
+ * The symbol a company's deals are filed under, from the ticker a pane is
+ * linked to. A deal carries its companies' quote symbols: plain for a US
+ * listing, suffixed by the venue elsewhere (ATH.TO, SHEL.L, 9984.T). A
+ * listing abroad therefore asks by that quote symbol: its bare symbol is
+ * another company's US ticker (ATH is Athene in New York, Athabasca in
+ * Toronto). A US listing, a symbol with no venue and a symbol already
+ * suffixed go as they are, so a US ticker is asked for exactly as before.
+ * `savedExchange` is the venue the saved ticker names, for a key with none.
+ */
+export function dealsSymbol(key: string | null | undefined, savedExchange = ""): string {
+  const value = key?.trim();
+  if (!value) return "";
+  if (nonUsSecListingVenue(value, savedExchange)) return getListingSymbol(value, savedExchange).toUpperCase();
+  return parsePublicTickerKey(value).symbol;
+}
+
+/** Each holder gets the cash or the shares, not both. Older servers never say so. */
+export function isElection(terms: MnaTerms): boolean {
+  return terms.election === true && terms.cashPerShare != null && terms.exchangeRatio != null;
+}
+
+/** What one target share gets, in as few characters as the terms allow. */
+export function termsLabel(terms: MnaTerms): string {
+  const parts: string[] = [];
+  if (terms.cashPerShare != null) {
+    parts.push(terms.exchangeRatio == null
+      ? `${formatPerShare(terms.cashPerShare, terms.currency)} cash`
+      : formatPerShare(terms.cashPerShare, terms.currency));
+  }
+  if (terms.exchangeRatio != null) parts.push(ratioLabel(terms.exchangeRatio, terms.ratioSymbol));
+  if (parts.length === 0) {
+    parts.push(terms.consideration === "cash" ? "Cash"
+      : terms.consideration === "stock" ? "Stock"
+        : terms.consideration === "mixed" ? "Cash and stock"
+          : MISSING);
+  }
+  let label = parts.join(isElection(terms) ? " or " : " + ");
+  if (terms.cvr) label += " + CVR";
+  if (terms.partial) label += ", partial";
+  return label;
+}
+
+const STATUS_LABELS: Record<MnaStatus, string> = {
+  talks: "Talks",
+  pending: "Pending",
+  completed: "Completed",
+  terminated: "Terminated",
+};
+
+/** The stage says more than "Pending" once a deal has one. */
+export function stageLabel(deal: MnaDeal): string {
+  if (deal.stale) return `No news since ${formatListDate(deal.lastReported)}`;
+  if (deal.status === "pending") return deal.hostile ? `Hostile${deal.stage ? `, ${deal.stage.toLowerCase()}` : ""}` : deal.stage ?? "Pending";
+  if (deal.status === "talks") return deal.acquirer ? "Talks" : "Exploring sale";
+  return STATUS_LABELS[deal.status];
+}
+
+const PENCE = new Set(["GBp", "GBX"]);
+
+/**
+ * London quotes arrive in pounds while UK offers are often in pence, so the
+ * two compare after scaling; any other currency mismatch has no price.
+ */
+export function inQuoteCurrency(amount: number, from: string | null, quoteCurrency: string | undefined): number | null {
+  const offer = from ?? "USD";
+  const quote = quoteCurrency ?? "USD";
+  if (offer === quote) return amount;
+  if (offer === "GBP" && PENCE.has(quote)) return amount * 100;
+  if (PENCE.has(offer) && quote === "GBP") return amount / 100;
+  if (PENCE.has(offer) || PENCE.has(quote)) return null;
+  return offer.toUpperCase() === quote.toUpperCase() ? amount : null;
+}
+
+function cashLeg(terms: MnaTerms, targetQuote: Quote | null): number | null {
+  return terms.cashPerShare == null ? null : inQuoteCurrency(terms.cashPerShare, terms.currency, targetQuote?.currency);
+}
+
+function stockLeg(terms: MnaTerms, targetQuote: Quote | null, ratioQuote: Quote | null): number | null {
+  const price = ratioQuote?.price;
+  if (terms.exchangeRatio == null || !terms.ratioSymbol || price == null || !Number.isFinite(price) || price <= 0) return null;
+  const leg = inQuoteCurrency(price, ratioQuote?.currency ?? null, targetQuote?.currency);
+  return leg == null ? null : terms.exchangeRatio * leg;
+}
+
+/**
+ * The leg an election is priced at. It pays each holder the cash or the
+ * shares, never both, so it is priced at its cash leg: the legs are set about
+ * equal at signing, proration means a holder cannot count on getting the
+ * stock, and the cash does not move. The stock leg stands in only when the
+ * cash cannot be compared with the target's quote. Without a quote, the cash.
+ */
+export function electionLeg(terms: MnaTerms, targetQuote: Quote | null): "cash" | "stock" {
+  return !targetQuote || cashLeg(terms, targetQuote) != null ? "cash" : "stock";
+}
+
+/**
+ * What the terms pay per target share at the latest prices, in the target
+ * quote's currency. Null when a leg cannot be priced: no terms, a ratio
+ * without its listing, or cash in another currency. An election is one leg,
+ * the one {@link electionLeg} picks.
+ */
+function offerValue(deal: MnaDeal, targetQuote: Quote | null, ratioQuote: Quote | null): number | null {
+  const { terms } = deal;
+  if (terms.cashPerShare == null && terms.exchangeRatio == null) return null;
+  let total: number | null;
+  if (isElection(terms)) {
+    total = electionLeg(terms, targetQuote) === "cash"
+      ? cashLeg(terms, targetQuote)
+      : stockLeg(terms, targetQuote, ratioQuote);
+  } else {
+    const cash = terms.cashPerShare == null ? 0 : cashLeg(terms, targetQuote);
+    const stock = terms.exchangeRatio == null ? 0 : stockLeg(terms, targetQuote, ratioQuote);
+    total = cash == null || stock == null ? null : cash + stock;
+  }
+  return total != null && total > 0 ? total : null;
+}
+
+/**
+ * What the terms were worth each day since the announcement: flat for cash,
+ * the ratio times the paying listing's close for stock. An election draws
+ * the one leg its Offer is priced at (`leg`, from {@link electionLeg}), its
+ * stock leg in the target quote's currency as the Offer converts it.
+ */
+export function offerSeries(
+  deal: MnaDeal,
+  ratioCloses: readonly { date: Date; close: number }[],
+  days: readonly string[],
+  leg: "cash" | "stock" | null,
+  toQuote: (close: number) => number | null = (close) => close,
+): Array<{ day: string; value: number }> {
+  const { cashPerShare, exchangeRatio, currency } = deal.terms;
+  if (cashPerShare == null && exchangeRatio == null) return [];
+  const pence = currency === "GBp" || currency === "GBX";
+  const cash = cashPerShare == null || leg === "stock" ? 0 : pence ? cashPerShare / 100 : cashPerShare;
+  const ratioByDay = new Map(ratioCloses.map((point) => [point.date.toISOString().slice(0, 10), point.close]));
+  const out: Array<{ day: string; value: number }> = [];
+  let lastRatio: number | null = null;
+  for (const day of days) {
+    if (day < deal.announced) continue;
+    if (exchangeRatio == null || leg === "cash") {
+      out.push({ day, value: cash });
+      continue;
+    }
+    const close = ratioByDay.get(day);
+    lastRatio = close == null ? lastRatio : toQuote(close) ?? lastRatio;
+    if (lastRatio != null) out.push({ day, value: cash + exchangeRatio * lastRatio });
+  }
+  return out;
+}
+
+export interface DealSpread {
+  offer: number;
+  price: number;
+  /** Fraction of the target price, e.g. 0.004 for 0.4%. */
+  spread: number;
+  /** Simple annualized spread to the expected close; null past it or without a date. */
+  annualized: number | null;
+}
+
+/** Last day of a "Q1 2027", "H2 2026" or "2026" close; a full date passes through. */
+export function expectedCloseDate(value: string | null): Date | null {
+  if (!value) return null;
+  const text = value.trim();
+  const day = /^(\d{4})-(\d{2})-(\d{2})$/.exec(text);
+  if (day) {
+    const date = new Date(Date.UTC(Number(day[1]), Number(day[2]) - 1, Number(day[3])));
+    return date.toISOString().slice(0, 10) === text ? date : null;
+  }
+  const quarter = /^Q([1-4])\s+(\d{4})$/i.exec(text);
+  if (quarter) return new Date(Date.UTC(Number(quarter[2]), Number(quarter[1]) * 3, 0));
+  const half = /^H([12])\s+(\d{4})$/i.exec(text);
+  if (half) return new Date(Date.UTC(Number(half[2]), Number(half[1]) * 6, 0));
+  const year = /^(\d{4})$/.exec(text);
+  if (year) return new Date(Date.UTC(Number(year[1]), 12, 0));
+  return null;
+}
+
+/** "Oct 15", "Q1 27", "2027". */
+export function formatExpectedClose(value: string | null, now = new Date()): string {
+  if (!value) return MISSING;
+  const text = value.trim();
+  const day = /^(\d{4})-(\d{2})-(\d{2})$/.exec(text);
+  if (day) {
+    const date = new Date(`${text}T00:00:00Z`);
+    const month = date.toLocaleString("en-US", { month: "short", timeZone: "UTC" });
+    return date.getUTCFullYear() === now.getUTCFullYear() ? `${month} ${Number(day[3])}` : `${month} ${day[1]!.slice(2)}`;
+  }
+  const period = /^([QH][1-4])\s+(\d{4})$/i.exec(text);
+  if (period) return `${period[1]!.toUpperCase()} ${period[2]!.slice(2)}`;
+  return text;
+}
+
+/**
+ * The arbitrage spread of a pending deal at the latest prices. A partial
+ * offer's spread applies only to the prorated slice, so it has no
+ * annualized figure; neither has a negative spread, which says the market
+ * expects better terms rather than a return.
+ */
+export function dealSpread(
+  deal: MnaDeal,
+  targetQuote: Quote | null,
+  ratioQuote: Quote | null,
+  now = Date.now(),
+): DealSpread | null {
+  if (deal.status !== "pending" || !deal.target.symbol) return null;
+  const price = targetQuote?.price;
+  if (price == null || !Number.isFinite(price) || price <= 0) return null;
+  const offer = offerValue(deal, targetQuote, ratioQuote);
+  if (offer == null) return null;
+  const spread = offer / price - 1;
+  const close = expectedCloseDate(deal.expectedClose);
+  const days = close ? (close.getTime() - now) / MS_PER_DAY : null;
+  const annualized = !deal.terms.partial && spread > 0 && days != null && days >= 1
+    ? spread * 365 / days
+    : null;
+  return { offer, price, spread, annualized };
+}
+
+/** Target name for a table cell: the symbol when listed, else the name. */
+export function partyCell(party: { name: string; symbol: string | null } | null, preferSymbol: boolean): string {
+  if (!party) return MISSING;
+  return preferSymbol && party.symbol ? party.symbol : party.name;
+}
+
+/** "Sep 10" this year, "Dec 2025" before it. */
+export function formatListDate(value: string, now = new Date()): string {
+  const date = new Date(`${value}T00:00:00Z`);
+  if (!Number.isFinite(date.getTime())) return MISSING;
+  const month = date.toLocaleString("en-US", { month: "short", timeZone: "UTC" });
+  return date.getUTCFullYear() === now.getUTCFullYear() ? `${month} ${date.getUTCDate()}` : `${month} ${date.getUTCFullYear()}`;
+}
+
+/** 0.0038 is "0.38%", -0.049 is "-4.9%": tight arb spreads keep two decimals. */
+export function formatPercentShort(value: number): string {
+  const percent = value * 100;
+  const digits = Math.abs(percent) < 1 ? 2 : 1;
+  const fixed = percent.toFixed(digits);
+  return `${/[1-9]/.test(fixed) ? fixed : fixed.replace("-", "")}%`;
+}
+
+export function formatPrice(value: number): string {
+  return value.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: value < 1 ? 4 : 2 });
+}