gloomberb 0.18.4 → 0.19.0

package/src/utils/trailing-dividend.ts

@@ -51,7 +51,9 @@ export function inferCadence(payments: readonly Pick<CashDistribution, "exDate">
 }
 
 /**
- * Trailing twelve-month cash as known at `asOf`, one payment per regular period.
+ * The payments trailing twelve-month cash is made of as known at `asOf`, one
+ * per regular period, and how many a year the issuer's cadence pays (null
+ * without a regular cadence).
  *
  * A fixed one-year ex-date window counts a fifth quarterly (or thirteenth
  * monthly) payment when this year's ex-date is a few days earlier than last
@@ -61,13 +63,13 @@ export function inferCadence(payments: readonly Pick<CashDistribution, "exDate">
  * the window holds fewer than one year of payments. Irregular cash uses the
  * plain window, so special distributions are neither dropped nor extended.
  */
-export function trailingCashAt<Payment extends CashDistribution>(payments: readonly Payment[], asOf: Date): number {
+function trailingPayments<Payment extends CashDistribution>(payments: readonly Payment[], asOf: Date): { counted: Payment[]; perYear: number | null; cadence: DistributionCadence | null } {
   const known = payments.filter((payment) => payment.exDate <= asOf && Number.isFinite(payment.amount) && payment.amount > 0)
     .sort((a, b) => a.exDate.getTime() - b.exDate.getTime());
   const cutoff = calendarMonthsBefore(asOf, 12);
   const cadence = inferCadence(known, asOf);
   const regular = cadence ? REGULAR_CADENCE[cadence] : undefined;
-  if (!regular) return known.filter((payment) => payment.exDate > cutoff).reduce((sum, payment) => sum + payment.amount, 0);
+  if (!regular) return { counted: known.filter((payment) => payment.exDate > cutoff), perYear: null, cadence };
 
   const halfPeriod = regular.halfPeriodDays * DAY;
   const graceCutoff = new Date(cutoff.getTime() - Math.min(regular.halfPeriodDays, MAX_LATE_GRACE_DAYS) * DAY);
@@ -94,7 +96,54 @@ export function trailingCashAt<Payment extends CashDistribution>(payments: reado
   const late = candidates.filter((payment) => payment.exDate <= cutoff && payment.exDate > graceCutoff && !superseded.has(payment))
     .reverse()
     .slice(0, Math.max(0, regular.perYear - counted.length));
-  return [...counted, ...late].reduce((sum, payment) => sum + payment.amount, 0);
+  return { counted: [...counted, ...late], perYear: regular.perYear, cadence };
+}
+
+/** Trailing twelve-month cash as known at `asOf` (trailingPayments). */
+export function trailingCashAt<Payment extends CashDistribution>(payments: readonly Payment[], asOf: Date): number {
+  return trailingPayments(payments, asOf).counted.reduce((sum, payment) => sum + payment.amount, 0);
+}
+
+/** How many payments trailing cash counts against how many a year the issuer's cadence pays. */
+export interface TrailingPayments {
+  counted: number;
+  expected: number;
+  cadence: DistributionCadence;
+}
+
+/**
+ * The payments a regular payer's trailing cash counts when it is fewer than
+ * its cadence pays in a year: a hole in the history (ECC's monthly July to
+ * September 2026 distributions), a missed or late payment, or a fund under a
+ * year old. Null for a full year, an irregular payer and an issuer with no
+ * cadence, whose trailing cash is the plain window.
+ */
+export function trailingPaymentShortfall(payments: readonly CashDistribution[], asOf: Date): TrailingPayments | null {
+  const { counted, perYear, cadence } = trailingPayments(payments, asOf);
+  return perYear != null && cadence && counted.length < perYear ? { counted: counted.length, expected: perYear, cadence } : null;
+}
+
+/** Over this ratio between a regular payer's largest and smallest payment of a year, no one payment stands for the year. */
+const UNEVEN_PAYMENT_RATIO = 1.5;
+
+/**
+ * A regular payer's payments of the trailing year when they differ widely:
+ * exactly as many as its cadence pays, the largest more than 1.5 times the
+ * smallest (HSBC's final beside its interims, AstraZeneca's interim beside its
+ * final). Their total is the year's cash, where the latest one annualized is
+ * not (HSBA's interim read as 2.17% a year beside the 4.08% it paid). Null for
+ * an even year, one with a hole or an extra payment, an annual payer and an
+ * irregular one. `latest` is the newest payment's ex-date.
+ */
+export function unevenRegularPayments(payments: readonly CashDistribution[], asOf: Date): { total: number; latest: Date } | null {
+  const { counted, perYear } = trailingPayments(payments, asOf);
+  if (perYear == null || perYear < 2 || counted.length !== perYear) return null;
+  const amounts = counted.map((payment) => payment.amount);
+  if (Math.max(...amounts) <= UNEVEN_PAYMENT_RATIO * Math.min(...amounts)) return null;
+  return {
+    total: atSourcePrecision(amounts.reduce((sum, amount) => sum + amount, 0)),
+    latest: new Date(Math.max(...counted.map((payment) => payment.exDate.getTime()))),
+  };
 }
 
 /** A history row as a paid distribution; null when its date is not a calendar day or its amount is no cash. */

package/src/plugins/builtin/clinical-trials/ticker-sponsor.ts

@@ -1,17 +0,0 @@
-import type { DataProvider } from "../../../types/data-provider";
-import { shortCompanyName } from "../../../tickers/company-name";
-import { classifyInstrumentKind } from "../../../tickers/search/ranking";
-
-/**
- * The company a ticker is, by the name a registry files its studies under:
- * VKTX is "Viking Therapeutics". Read from the listing's quote, which names
- * it; a fund or a contract is no sponsor. Null when no share trades under it.
- */
-export async function tickerSponsorName(dataProvider: Pick<DataProvider, "getQuote"> | null, ticker: string): Promise<string | null> {
-  const symbol = ticker.trim().toUpperCase();
-  if (!dataProvider || !symbol) return null;
-  const quote = await dataProvider.getQuote(symbol).catch(() => null);
-  const name = quote?.name?.trim();
-  const kind = classifyInstrumentKind(quote?.instrumentType);
-  return name && kind !== "fund" && kind !== "derivative" ? shortCompanyName(name) : null;
-}

package/src/renderers/browser/first-screen.ts

@@ -1,193 +0,0 @@
-/**
- * The web terminal's first screen for a new visitor: the `web_first_screen`
- * experiment. The control is today's six-pane workspace; `calm` opens two of
- * the same panes (config-host.ts). Nothing else differs between the arms.
- *
- * The arm is asked for once, when the first layout is chosen, before the dock
- * first paints, and that request is the exposure (`exposeWebExperiment`, see
- * web-experiments.ts for who is never asked). A browser with a saved workspace
- * keeps it and is not asked, so a returning visitor is never moved between
- * layouts or counted again. A link that hands over a shared pane or layout
- * lands on what was shared, so it keeps today's screen and is not asked
- * either. When the API answers late the visitor gets the control and the
- * request is dropped.
- *
- * The measure is the visitor's first action in that first browser session:
- * opening a function, changing the ticker, or typing in the command bar. It
- * goes out once as `first_screen_engaged`, with only the placement; never the
- * function, the ticker or the text.
- */
-import type { StorageLike } from "../../api-client/web-experiments";
-import type { LayoutConfig } from "../../types/config";
-import type { DesktopDeepLinkBridge } from "../../types/desktop-deeplink";
-import { settleWithin } from "../../utils/async-deadline";
-import type { BrowserFirstScreen } from "./config-host";
-
-export const FIRST_SCREEN_EXPERIMENT = "web_first_screen";
-/** The exposure's and the engagement's placement. */
-export const FIRST_SCREEN_PLACEMENT = "first-screen";
-/** How long the first paint waits for the arm before showing the control. */
-const FIRST_SCREEN_DEADLINE_MS = 1_500;
-const ENGAGEMENT_SESSION_KEY = "gloomberb.web.first-screen";
-const WATCHING = "watching";
-const ENGAGED = "engaged";
-
-export interface FirstScreenVisit {
-  /** A workspace saved on an earlier visit. */
-  savedLayout: boolean;
-  /** The address hands over a shared pane or layout to open. */
-  handoff: boolean;
-  /**
-   * Asks for the arm and counts the exposure; null when the visitor is not in
-   * the experiment. The signal fires at the deadline.
-   */
-  expose(signal: AbortSignal): Promise<string | null>;
-  deadlineMs?: number;
-}
-
-/**
- * The first screen this visit was counted in, or null when it was not counted:
- * the visitor sees what they would have without the experiment (a saved
- * workspace, or today's first screen).
- */
-export async function exposeFirstScreen(visit: FirstScreenVisit): Promise<BrowserFirstScreen | null> {
-  if (visit.savedLayout || visit.handoff) return null;
-  const deadlineMs = visit.deadlineMs ?? FIRST_SCREEN_DEADLINE_MS;
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), deadlineMs);
-  try {
-    let request: Promise<string | null>;
-    try {
-      request = visit.expose(controller.signal);
-    } catch {
-      return null;
-    }
-    const variant = await settleWithin(request, deadlineMs);
-    if (variant === "calm") return "calm";
-    return variant === null ? null : "control";
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
-function read(storage: StorageLike, key: string): string | null {
-  try {
-    return storage.getItem(key);
-  } catch {
-    return null;
-  }
-}
-
-function write(storage: StorageLike, key: string, value: string): void {
-  try {
-    storage.setItem(key, value);
-  } catch {
-    /* Without session storage only this page load is watched. */
-  }
-}
-
-/** The ticker without its venue, so a link's listing settling (7203:TSE to 7203:JPX) is not a change. */
-function baseSymbol(symbol: string): string {
-  return symbol.split(":")[0]!.trim().toUpperCase();
-}
-
-interface FirstScreenSources {
-  subscribeFunctionOpens(listener: () => void): () => void;
-  subscribeCommandBarQuery(listener: (query: string) => void): () => void;
-}
-
-interface Watcher {
-  engage(): void;
-  /** Tickers on screen so far in this page load; a new one is a change. */
-  seen: Set<string>;
-  /** Set while the app handles the address it was opened with. */
-  handlingLink: boolean;
-}
-
-let watcher: Watcher | null = null;
-
-/**
- * Watches this browser session for the visitor's first action once the first
- * screen was counted, and resumes after a reload in the same session. Sends
- * `record` at most once; a later session is never watched.
- */
-export function watchFirstScreenEngagement({
-  counted,
-  session,
-  layout,
-  record,
-  sources,
-}: {
-  /** This page load was counted in the experiment. */
-  counted: boolean;
-  session: StorageLike;
-  /** The workspace it opens on; its tickers are not a change. */
-  layout: LayoutConfig;
-  record: () => void;
-  sources: FirstScreenSources;
-}): () => void {
-  if (counted) write(session, ENGAGEMENT_SESSION_KEY, WATCHING);
-  if (read(session, ENGAGEMENT_SESSION_KEY) !== WATCHING) return () => {};
-
-  const unsubscribes: Array<() => void> = [];
-  const stop = () => {
-    for (const unsubscribe of unsubscribes.splice(0)) unsubscribe();
-    if (watcher === current) watcher = null;
-  };
-  const current: Watcher = {
-    seen: new Set(layout.instances.flatMap((instance) => (
-      instance.binding?.kind === "fixed" ? [baseSymbol(instance.binding.symbol)] : []
-    ))),
-    handlingLink: false,
-    engage() {
-      if (current.handlingLink || read(session, ENGAGEMENT_SESSION_KEY) !== WATCHING) return;
-      write(session, ENGAGEMENT_SESSION_KEY, ENGAGED);
-      stop();
-      record();
-    },
-  };
-  watcher = current;
-  unsubscribes.push(
-    sources.subscribeFunctionOpens(() => current.engage()),
-    sources.subscribeCommandBarQuery((query) => {
-      if (query.trim()) current.engage();
-    }),
-  );
-  return stop;
-}
-
-/**
- * The focused pane's ticker changed (the app's `ticker:selected`). Moving focus
- * between panes that show tickers already on screen is not a change; a ticker
- * that was not on screen yet is.
- */
-export function noteFirstScreenTicker(symbol: string | null, previous: string | null): void {
-  const current = watcher;
-  if (!current) return;
-  if (previous) current.seen.add(baseSymbol(previous));
-  if (!symbol) return;
-  const next = baseSymbol(symbol);
-  if (current.seen.has(next)) return;
-  current.seen.add(next);
-  current.engage();
-}
-
-/**
- * The address the terminal was opened with (a research link) opens its pane as
- * if asked; that is the landing, not the visitor's first action.
- */
-export function observeLandingLinks(bridge: DesktopDeepLinkBridge): DesktopDeepLinkBridge {
-  return {
-    subscribe(listener) {
-      return bridge.subscribe((link) => {
-        const current = watcher;
-        if (current) current.handlingLink = true;
-        try {
-          listener(link);
-        } finally {
-          if (current) current.handlingLink = false;
-        }
-      });
-    },
-  };
-}