gloomberb 0.18.3 → 0.18.5

package/src/api-client/live-scan.ts

@@ -0,0 +1,91 @@
+/**
+ * The live scanner's wire format: a user's own intraday conditions over a
+ * universe of US stocks, evaluated by Gloom Cloud against a market-wide
+ * snapshot it refreshes every few seconds (real-time for Pro, 15 minutes
+ * delayed otherwise). `GET /market/scanner/live?scan=<definition JSON>`.
+ */
+
+/** Minutes a move, a volume window or an event can look back over. */
+export const LIVE_SCAN_WINDOWS = [1, 5, 15, 30, 60] as const;
+export type LiveScanWindow = (typeof LIVE_SCAN_WINDOWS)[number];
+
+export const LIVE_SCAN_INDEXES = ["sp500", "sp400", "sp600", "russell1000", "russell2000"] as const;
+export type LiveScanIndex = (typeof LIVE_SCAN_INDEXES)[number];
+
+/** The universe as Gloom Cloud reads it; a watchlist goes as its symbols. */
+type LiveScanWireUniverse =
+  | { kind: "all" }
+  | { kind: "index"; index: LiveScanIndex }
+  | { kind: "sector"; sector: string }
+  | { kind: "symbols"; symbols: string[] };
+
+export type LiveScanDirection = "up" | "down" | "either";
+
+export type LiveScanCondition =
+  /** Volume over the window (or the session so far) against the 20-session average's pace. */
+  | { kind: "volume_spike"; window: LiveScanWindow | "day"; ratio: number }
+  /** Percent move over the last `window` minutes. */
+  | { kind: "move"; window: LiveScanWindow; direction: LiveScanDirection; percent: number }
+  /** A new session high (low) printed in the last `within` minutes. */
+  | { kind: "new_high" | "new_low"; within: LiveScanWindow }
+  /** Crossed the session VWAP in the last `within` minutes, and still on that side. */
+  | { kind: "vwap_cross"; direction: "above" | "below" | "either"; within: LiveScanWindow }
+  /** The session's open against the previous close. */
+  | { kind: "gap"; direction: LiveScanDirection; percent: number };
+
+export interface LiveScanWireDefinition {
+  version: 1;
+  universe: LiveScanWireUniverse;
+  conditions: LiveScanCondition[];
+  minPrice?: number;
+  minMarketCap?: number;
+  minVolume?: number;
+}
+
+type LiveScanStatus = "live" | "starting" | "closed" | "degraded";
+
+export interface LiveScanMatch {
+  symbol: string;
+  name: string | null;
+  /** Its US venue (NASDAQ, NYSE, ...), null when the screener does not list it. */
+  exchange?: string | null;
+  price: number;
+  changePercent: number | null;
+  volume: number | null;
+  /** The session's volume against the 20-session average's pace so far. */
+  relativeVolume: number | null;
+  /** Price against the session VWAP, in percent. */
+  vwapPercent: number | null;
+  gapPercent: number | null;
+  /**
+   * The figure each condition matched on, in the definition's order: a
+   * percent for a move or a gap, a multiple for a volume spike, the time of
+   * the event (epoch ms) for a new high or low or a VWAP cross.
+   */
+  values: Array<number | null>;
+  /** The latest event a condition matched on. */
+  signalAt: number | null;
+  /** When the price printed. */
+  at: number | null;
+}
+
+export interface LiveScanPayload {
+  status: LiveScanStatus;
+  access: "realtime" | "delayed";
+  delayMinutes: number;
+  /** The market time the snapshot shows. */
+  asOf: number | null;
+  /** When the snapshot was refreshed. */
+  takenAt: number | null;
+  /** How often the snapshot refreshes. */
+  refreshMs: number;
+  scanned: number;
+  matched: number;
+  matches: LiveScanMatch[];
+  /** Windows the scanner cannot measure yet after it started; a condition over one matches nothing until then. */
+  warmingWindows: LiveScanWindow[];
+  warnings: string[];
+}
+
+/** The scan travels in a POST body: a watchlist of 1,000 symbols would not fit a request line. */
+export const LIVE_SCAN_PATH = "/market/scanner/live";

package/src/api-client/market-discovery.ts

@@ -60,6 +60,12 @@ export interface MarketHeatmapResult {
   stale?: boolean;
   universe: MarketHeatmapUniverseId;
   source: MarketHeatmapSource;
+  /**
+   * Whose prices the board carries: `realtime` for a Pro account, priced
+   * from a live read the server takes every 15 seconds; `delayed`, fifteen
+   * minutes behind, otherwise. An older server leaves it out (delayed).
+   */
+  access?: "realtime" | "delayed";
   fetchedAt: number;
   /** The US market session the snapshot describes; null when the server cannot tell. */
   session?: "REGULAR" | "PRE" | "POST" | "CLOSED" | null;
@@ -72,6 +78,14 @@ export interface MarketHeatmapResult {
    * leaves it out.
    */
   regularSessionClosedAt?: number | null;
+  /**
+   * When the prices the board's moves are read at were printed, in epoch
+   * milliseconds, never later than any of them: the oldest delayed print
+   * while the session trades, that session's close outside it. `fetchedAt`
+   * is when the server put the snapshot together, at least fifteen minutes
+   * later. Null when a print is unknown; an older server leaves it out.
+   */
+  pricesAsOf?: number | null;
   assets: MarketHeatmapAsset[];
 }
 

package/src/api-client/members.ts

@@ -7,6 +7,12 @@ export interface FundMember {
   contribution: number | null; stale: boolean;
 }
 export interface FundMembersPayload {
+  /**
+   * Whose prices the members carry: `realtime` for a Pro account, priced from
+   * a live read the server renews every 15 seconds; `delayed`, fifteen
+   * minutes behind, otherwise. An older server leaves it out (delayed).
+   */
+  access?: "realtime" | "delayed";
   fund: MemberFund; asOf: string; fetchedAt: string; excludedDerivatives: number; stale: boolean;
   quotesUnavailable: boolean; snapshotAsOf: string | null; fundDailyAsOf: string | null; quoteCap: number;
   members: FundMember[];
@@ -24,3 +30,15 @@ export interface FundChangesPayload {
   estimateLabel: string; attribution: { text: string; url: string } | null;
 }
 export interface MemberFundsPayload { funds: (MemberFund & { asOf: string | null })[] }
+
+interface BreadthCount { above: number; eligible: number; percent: number | null }
+export interface BreadthDay {
+  date: string; asOf: string; membershipAsOf: string; memberCount: number; observed: number;
+  advances: number; declines: number; unchanged: number; advanceDeclineEligible: number;
+  ma20: BreadthCount; ma50: BreadthCount; ma200: BreadthCount;
+  newHighs: number; newLows: number; highLowEligible: number; adLine: number | null;
+}
+export interface FundBreadthPayload {
+  fund: MemberFund; basis: "daily-close" | "intraday"; access?: "realtime" | "delayed"; membershipBasis: "current-members";
+  latest: BreadthDay | null; history: BreadthDay[]; stale: boolean;
+}

package/src/api-client/mna.ts

@@ -26,6 +26,12 @@ export interface MnaTerms {
   /** The listing the exchange ratio pays in, usually the acquirer's. */
   ratioSymbol: string | null;
   currency: string | null;
+  /**
+   * Each holder chooses the cash or the shares (usually prorated to a fixed
+   * mix) instead of getting both. Older servers leave it out, and read every
+   * deal with both legs as paying them together.
+   */
+  election?: boolean;
   /** A contingent value right rides on top of the per-share terms. */
   cvr: boolean;
   /** The offer is for part of the shares, so the spread applies to a prorated slice. */

package/src/api-client/paths.ts

@@ -74,6 +74,8 @@ export type CloudEarningsCallsParams = IssuerListingParams & {
   offset?: number;
   /** Include calls still working through the transcription pipeline. */
   includePending?: boolean;
+  /** Every company's calls on these New York days (YYYY-MM-DD), earliest first, in place of a company or the shelf. */
+  upcoming?: { from: string; to: string };
 };
 
 export type CloudNewsParams = {
@@ -310,6 +312,14 @@ export function cloudJobsPostingsPath(ticker: string, params: CloudJobsPostingsP
   return appendQuery(`/cloud/jobs/${encodeURIComponent(normalizeIssuerResearchTicker(ticker))}/postings`, search);
 }
 
+/** One posting of a company, by the database id the jobs list carries or the careers system's own id HIRE's evidence carries. */
+export function cloudJobsPostingPath(ticker: string, posting: { id: number } | { externalId: string }): string {
+  const search = new URLSearchParams();
+  if ("id" in posting) search.set("id", String(posting.id));
+  else search.set("externalId", posting.externalId);
+  return appendQuery(`/cloud/jobs/${encodeURIComponent(normalizeIssuerResearchTicker(ticker))}/posting`, search);
+}
+
 export function cloudJobsMoversPath(limit?: number, offset?: number): string {
   const search = new URLSearchParams();
   if (limit != null) search.set("limit", String(limit));
@@ -356,6 +366,11 @@ export function cloudEarningsCallsPath(
   if (params.limit != null) search.set("limit", String(params.limit));
   if (params.offset != null) search.set("offset", String(params.offset));
   if (params.includePending) search.set("includePending", "true");
+  if (params.upcoming) {
+    search.set("upcoming", "true");
+    search.set("from", params.upcoming.from);
+    search.set("to", params.upcoming.to);
+  }
   return appendQuery("/cloud/transcripts", search);
 }
 
@@ -605,9 +620,11 @@ export function cloudNewsPath(params: CloudNewsParams = {}): string {
 }
 
 /** Stories whose headline, summary or publisher matches the text, best match first; the service takes at most 100. */
-export function cloudNewsSearchPath(query: string, limit?: number): string {
+/** `topics` are NI codes the stories must carry: `query=gold&topics=metals` is gold's market news. */
+export function cloudNewsSearchPath(query: string, limit?: number, topics?: readonly string[]): string {
   const search = new URLSearchParams({ query });
   if (limit != null) search.set("limit", String(limit));
+  if (topics?.length) search.set("topics", topics.join(","));
   return appendQuery("/news/search", search);
 }
 

package/src/api-client/request.ts

@@ -1,6 +1,6 @@
 import { logFailure } from "../utils/log-failure";
 import { httpFetch, isHttpFetchStreaming } from "../utils/http-transport";
-import { withDeadline } from "../utils/async-deadline";
+import { OperationTimeoutError } from "../utils/async-deadline";
 import {
   ApiRequestError,
   parseApiErrorCode,
@@ -16,16 +16,59 @@ import {
   type ConnectionHealthRegistry,
 } from "../core/connection-health";
 import { SESSION_COOKIE_NAMES } from "./session-cookie";
+import { asDataServiceFailure, DataServiceUnreachableError } from "../utils/network-failure";
 
 /** The public Gloom Cloud API, which the web app's same-origin `/api` path forwards to. */
 export const DEFAULT_API_URL = "https://api.gloom.sh";
+/**
+ * How long a request waits for the service to answer at all. Nothing back by
+ * then, and nothing else answered meanwhile, is a hung connection: the request
+ * fails as the data service being unreachable, as a refused one does.
+ */
 const DEFAULT_MARKET_REQUEST_TIMEOUT_MS = 10_000;
+/**
+ * A search, which a command and a keystroke wait on, gives up on a connection
+ * that sends nothing back sooner. A slow search on a service that answers
+ * (some take five seconds) still gets the full market deadline.
+ */
+const SEARCH_ANSWER_TIMEOUT_MS = 4_000;
+/**
+ * Once a request went unanswered, later ones wait this long for an answer,
+ * until any answer comes back: a hung connection is not waited out in full by
+ * every request a command or a pane makes after it.
+ */
+const UNREACHABLE_REQUEST_TIMEOUT_MS = 3_000;
+/**
+ * Right after a request hung with nothing back, the requests that follow it
+ * (a fallback, the next step of a command) fail at once rather than each
+ * waiting out a connection that just proved dead. Past this they try again.
+ */
+const HUNG_FAIL_FAST_MS = 5_000;
 const DEFAULT_RESEARCH_REQUEST_TIMEOUT_MS = 45_000;
+/** Requests outside market reads (saves, uploads, drafts) may take the server this long once it is known to answer. */
+const DEFAULT_SERVICE_REQUEST_LIMIT_MS = 120_000;
+const UPLOAD_REQUEST_LIMIT_MS = 300_000;
+/**
+ * How long the check that the service answers at all waits. It runs this long
+ * before a request's answer deadline, unless something answered meanwhile, so
+ * one slow request on a service that answers is waited for and a dead
+ * connection is not.
+ */
+const SERVICE_PROBE_TIMEOUT_MS = 3_000;
+const SERVICE_PROBE_PATH = "/health";
 // Research may fill missing sections after a primary read; quote/history reads remain latency bounded.
 const RESEARCH_MARKET_PATHS = new Set([
   "/market/dividends", "/market/short-interest", "/market/movers", "/market/trending",
   "/market/heatmap", "/market/earnings-calendar",
 ]);
+
+/** When a request gives up: without any answer from the service, and in all. */
+interface RequestDeadline {
+  answerMs: number;
+  limitMs: number;
+  /** When to check that the service answers at all, if nothing has by then; null when the deadline is too short for it. */
+  probeAtMs: number | null;
+}
 /** Local status for "this runtime cannot stream", never returned by the server. */
 export const STREAMING_UNSUPPORTED_STATUS = 0;
 
@@ -73,6 +116,8 @@ type CloudApiUploadTransport = (request: CloudApiUploadRequest) => Promise<Cloud
 let cloudApiFetchTransport: CloudApiFetchTransport = httpFetch;
 let cloudApiUploadTransport: CloudApiUploadTransport | null = null;
 let cloudApiTransportInstalled = false;
+/** Counts installed transports, so what a client learned of one connection is not applied to the next. */
+let cloudApiTransportGeneration = 0;
 let cloudApiFetchStreaming = true;
 let cloudApiStreamFetch: CloudApiStreamFetch | null = null;
 
@@ -82,6 +127,7 @@ export function setCloudApiFetchTransport(
 ): void {
   cloudApiFetchTransport = transport ?? httpFetch;
   cloudApiTransportInstalled = !!transport;
+  cloudApiTransportGeneration += 1;
   cloudApiFetchStreaming = transport ? (options.streaming ?? false) : true;
   cloudApiStreamFetch = transport ? options.streamFetch ?? null : null;
 }
@@ -171,6 +217,17 @@ export class CloudApiRequestTransport {
   private readonly marketRequestTimeoutMs: number;
   private readonly researchRequestTimeoutMs: number;
   private readonly connectionHealth: ConnectionHealthRegistry;
+  /** Answers received from the service, by any request: a request that sees this grow knows the connection works. */
+  private answers = 0;
+  /** The last request went unanswered (refused or hung) and nothing has answered since. */
+  private unreachable = false;
+  /** When a request last hung with nothing back, while nothing has answered since. */
+  private hungAt: number | null = null;
+  /** The installed transport the two above were learned on. */
+  private connectionGeneration = cloudApiTransportGeneration;
+  /** Requests waiting under a deadline: the check that the service answers runs only while one is. */
+  private pending = 0;
+  private probe: AbortController | null = null;
 
   readonly baseUrl = getCloudApiBaseUrl();
 
@@ -263,11 +320,11 @@ export class CloudApiRequestTransport {
       GLOOM_CLOUD_HTTP_CONNECTION_ID,
       operation,
       async () => {
-        const response = await streamFetch(`${this.baseUrl}${path}`, {
+        const response = await this.reachService(() => streamFetch(`${this.baseUrl}${path}`, {
           ...options,
           headers,
           credentials: "include",
-        });
+        }), options.signal);
         throwIfRequestAborted(options.signal);
         if (!response.ok) {
           const text = await response.text().catch(logFailure("cloud-request", "Error response body read failed", ""));
@@ -284,37 +341,178 @@ export class CloudApiRequestTransport {
   }
 
   async request<T>(path: string, options?: RequestInit, canApplySession: () => boolean = () => true): Promise<T> {
-    if (!path.startsWith("/market/")) {
-      return this.performRequest<T>(path, options, canApplySession);
-    }
+    return this.withDeadline(path, this.deadlineFor(path), options?.signal, (signal) => this.performRequest<T>(path, {
+      ...options,
+      signal,
+    }, canApplySession));
+  }
+
+  /**
+   * Every request's deadline. A market read or a search waits about ten
+   * seconds, research and requests outside market data longer. With nothing
+   * back from the service, a request gives up at ten seconds, a search at
+   * four, and any request at three after one went unanswered, until something
+   * answers again. Three seconds before that, a request still unanswered
+   * checks that the service answers at all, so one slow request on a working
+   * connection is waited for and a dead connection is not.
+   */
+  private deadlineFor(path: string, limitMs?: number): RequestDeadline {
+    this.forgetOtherTransport();
+    const pathname = path.split("?")[0]!;
+    const market = pathname.startsWith("/market/");
+    const limit = limitMs ?? (!market ? DEFAULT_SERVICE_REQUEST_LIMIT_MS
+      : RESEARCH_MARKET_PATHS.has(pathname) ? this.researchRequestTimeoutMs : this.marketRequestTimeoutMs);
+    let answerMs = pathname === "/market/search"
+      ? Math.min(this.marketRequestTimeoutMs, SEARCH_ANSWER_TIMEOUT_MS)
+      : this.marketRequestTimeoutMs;
+    if (this.unreachable) answerMs = Math.min(answerMs, UNREACHABLE_REQUEST_TIMEOUT_MS);
+    return {
+      answerMs,
+      limitMs: Math.max(limit, answerMs),
+      probeAtMs: answerMs >= SERVICE_PROBE_TIMEOUT_MS ? answerMs - SERVICE_PROBE_TIMEOUT_MS : null,
+    };
+  }
 
-    const timeoutMs = RESEARCH_MARKET_PATHS.has(path.split("?")[0]!)
-      ? this.researchRequestTimeoutMs : this.marketRequestTimeoutMs;
+  /**
+   * Runs one request under its deadline. Without an answer from the service by
+   * `answerMs` (from this request, any other, or the check that the service
+   * answers at all), the connection is taken as hung: the request is aborted
+   * and fails as the data service being unreachable, as a refused connection
+   * does. A service that answers but is slow gets until `limitMs`, then the
+   * request times out. A caller's abort stays an abort.
+   */
+  private async withDeadline<T>(
+    path: string,
+    deadline: RequestDeadline,
+    callerSignal: AbortSignal | null | undefined,
+    run: (signal: AbortSignal) => Promise<T>,
+  ): Promise<T> {
     const controller = new AbortController();
-    const callerSignal = options?.signal;
     const abortFromCaller = () => controller.abort(callerSignal?.reason);
     if (callerSignal?.aborted) {
       abortFromCaller();
     } else {
       callerSignal?.addEventListener("abort", abortFromCaller, { once: true });
     }
-
+    const answersAtStart = this.answers;
+    const answered = () => this.answers > answersAtStart;
+    const generation = cloudApiTransportGeneration;
+    const what = path.startsWith("/market/") ? "Cloud market request" : "Cloud request";
+    const timedOut = (ms: number) => new OperationTimeoutError(`${what} timed out after ${ms}ms: ${path.split("?")[0]}`);
+    const timers: Array<ReturnType<typeof setTimeout>> = [];
+    if (this.hungAt != null && Date.now() - this.hungAt < HUNG_FAIL_FAST_MS && !controller.signal.aborted) {
+      callerSignal?.removeEventListener("abort", abortFromCaller);
+      throw new DataServiceUnreachableError(new OperationTimeoutError(`${what} not sent: the last one got no answer: ${path.split("?")[0]}`));
+    }
+    this.pending += 1;
     try {
-      const request = this.performRequest<T>(path, {
-        ...options,
-        signal: controller.signal,
-      }, canApplySession);
-      return await withDeadline(
-        request,
-        timeoutMs,
-        `Cloud market request timed out after ${timeoutMs}ms: ${path}`,
-        (error) => controller.abort(error),
-      );
+      const work = run(controller.signal);
+      return await new Promise<T>((resolve, reject) => {
+        const fail = (error: Error) => {
+          reject(error);
+          controller.abort(error);
+        };
+        work.then(resolve, reject);
+        if (deadline.probeAtMs != null) {
+          timers.push(setTimeout(() => {
+            if (!answered()) this.checkServiceAnswers();
+          }, deadline.probeAtMs));
+        }
+        timers.push(setTimeout(() => {
+          // The caller gave up first: its abort settles the request, and says nothing of the connection.
+          if (callerSignal?.aborted) return;
+          if (!answered()) {
+            this.recordNoAnswer(generation, true);
+            fail(new DataServiceUnreachableError(timedOut(deadline.answerMs)));
+          } else if (deadline.limitMs > deadline.answerMs) {
+            timers.push(setTimeout(() => fail(timedOut(deadline.limitMs)), deadline.limitMs - deadline.answerMs));
+          } else {
+            fail(timedOut(deadline.answerMs));
+          }
+        }, deadline.answerMs));
+      });
     } finally {
+      for (const timer of timers) clearTimeout(timer);
       callerSignal?.removeEventListener("abort", abortFromCaller);
+      this.pending -= 1;
+      // Nothing waits on the check any more: it must not hold a command's process open.
+      if (this.pending === 0) this.probe?.abort();
     }
   }
 
+  /**
+   * Sends one request, saying the same thing whichever fetch failed to connect
+   * (Bun's "Unable to connect", a browser's "Failed to fetch", a refused proxy):
+   * every command, pane and status line then reads "Gloom couldn't reach its
+   * data service", and code that falls back to a saved copy can tell it apart.
+   * A caller's abort stays an abort. An answer of any status says the
+   * connection works, for the deadlines of the requests beside it.
+   */
+  private async reachService<R>(fetch: () => Promise<R>, signal: AbortSignal | null | undefined): Promise<R> {
+    const generation = cloudApiTransportGeneration;
+    let response: R;
+    try {
+      response = await fetch();
+    } catch (error) {
+      if (signal?.aborted) throw error;
+      const failure = asDataServiceFailure(error);
+      if (failure instanceof DataServiceUnreachableError) this.recordNoAnswer(generation, false);
+      throw failure;
+    }
+    this.recordAnswer();
+    return response;
+  }
+
+  /** A new transport installed is a new connection: what failed on the last one says nothing about it. */
+  private forgetOtherTransport(): void {
+    if (this.fetchTransport || this.connectionGeneration === cloudApiTransportGeneration) return;
+    this.connectionGeneration = cloudApiTransportGeneration;
+    this.unreachable = false;
+    this.hungAt = null;
+  }
+
+  /** Something came back from the service: the connection works. */
+  private recordAnswer(): void {
+    this.answers += 1;
+    this.unreachable = false;
+    this.hungAt = null;
+  }
+
+  /**
+   * A request sent on the transport installed as `generation` got no answer:
+   * refused, or `hung` with nothing back by its deadline. Once another
+   * transport is installed, what one sent on the last says nothing of it.
+   */
+  private recordNoAnswer(generation: number, hung: boolean): void {
+    if (!this.fetchTransport && generation !== cloudApiTransportGeneration) return;
+    this.unreachable = true;
+    if (hung) this.hungAt = Date.now();
+  }
+
+  /**
+   * Asks the service for anything at all, once at a time, so a request that
+   * is slow can tell a slow server (which answers this) from a dead
+   * connection (which does not). Any status counts as an answer. It stops
+   * when nothing waits on it any more.
+   */
+  private checkServiceAnswers(): void {
+    if (this.probe) return;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), SERVICE_PROBE_TIMEOUT_MS);
+    const done = () => {
+      clearTimeout(timer);
+      if (this.probe === controller) this.probe = null;
+    };
+    // Done once given up on, even through a transport that ignores the abort.
+    controller.signal.addEventListener("abort", done, { once: true });
+    this.probe = controller;
+    (this.fetchTransport ?? cloudApiFetchTransport)(`${this.baseUrl}${SERVICE_PROBE_PATH}`, { signal: controller.signal })
+      .then(() => this.recordAnswer(), () => {
+        // Intentional ignore: an unanswered check only leaves the request it guards to its own deadline.
+      })
+      .finally(done);
+  }
+
   /**
    * POSTs raw bytes, such as an image, and parses the JSON answer like
    * `request`. Progress is reported where the installed upload transport can
@@ -338,17 +536,17 @@ export class CloudApiRequestTransport {
         url,
         body,
         headers: new Headers(init?.headers),
-        signal: options.signal,
+        signal: init?.signal ?? options.signal,
         onProgress: options.onProgress,
       })
       : undefined;
-    return this.performRequest<T>(path, {
+    return this.withDeadline(path, this.deadlineFor(path, UPLOAD_REQUEST_LIMIT_MS), options.signal, (signal) => this.performRequest<T>(path, {
       method: "POST",
       headers,
       // Typed arrays are valid fetch bodies; RequestInit's DOM typing lags behind.
       body: body as BodyInit,
-      signal: options.signal,
-    }, () => true, send);
+      signal,
+    }, () => true, send));
   }
 
   private async performRequest<T>(
@@ -372,14 +570,14 @@ export class CloudApiRequestTransport {
 
     const operation = `${options?.method ?? "GET"} ${path.split("?")[0]}`;
     const request = async () => {
-      const res = await (send ?? this.fetchTransport ?? cloudApiFetchTransport)(
+      const res = await this.reachService(() => (send ?? this.fetchTransport ?? cloudApiFetchTransport)(
         `${this.baseUrl}${path}`,
         {
           ...options,
           headers,
           credentials: "include",
         },
-      );
+      ), options?.signal);
       throwIfRequestAborted(options?.signal);
       const ownsCredential = canApplySession() && this.sessionToken === sessionTokenAtRequestStart;
       if (ownsCredential) this.extractSessionCookie(res);

package/src/api-client/research-activity.ts

@@ -29,10 +29,7 @@ export type ResearchActivity =
   | "onboarding_signed_in"
   | "onboarding_pro_viewed"
   | "onboarding_completed"
-  | "onboarding_skipped"
-  // The first action of a web visitor counted in the first-screen experiment,
-  // in that first session. Keep in sync with the server's list.
-  | "first_screen_engaged";
+  | "onboarding_skipped";
 export type ResearchFeature =
   | "overview"
   | "chart"
@@ -461,10 +458,7 @@ function webExperimentAttribution(): { experiments?: string } {
  * visitors on term.gloom.sh with an analytics id (no Do Not Track or Global
  * Privacy Control) and not driven by automation are asked. See web-experiments.ts.
  */
-export function exposeWebExperiment(
-  experiment: string,
-  { placement, signal }: { placement?: string; signal?: AbortSignal } = {},
-): Promise<string | null> {
+export function exposeWebExperiment(experiment: string): Promise<string | null> {
   if (!researchTelemetryAllowed()) return Promise.resolve(null);
   if (getCurrentPluginTarget() !== "web") return Promise.resolve(null);
   try {
@@ -481,8 +475,7 @@ export function exposeWebExperiment(
         attribution: attributionPayload(),
         experiment: key,
         variant,
-        ...(placement && ACTIVITY_ID.test(placement) ? { placement } : {}),
-      }, signal),
+      }),
     });
   } catch {
     return Promise.resolve(null);

package/src/api-client/short-side-publications.ts

@@ -0,0 +1,37 @@
+/** Daily outstanding fails are separate settlement snapshots, never additive through time. */
+interface FailsToDeliverObservation {
+  date: string;
+  cusip: string;
+  quantity: number;
+  price: number | null;
+  description: string;
+  sourceUrl: string;
+}
+
+/** ATS share is a percentage of published off-exchange shares, not total market volume. */
+interface OtcVolumeObservation {
+  weekStart: string;
+  atsShares: number | null;
+  nonAtsShares: number | null;
+  totalShares: number | null;
+  atsTrades: number | null;
+  nonAtsTrades: number | null;
+  atsSharePercent: number | null;
+  sourceUrl: string;
+}
+
+export interface ShortSidePublication<T> {
+  symbol: string;
+  status: "available" | "partial" | "unavailable";
+  asOf: string | null;
+  sourceAsOf: string | null;
+  fetchedAt: string;
+  loadedAt: string | null;
+  source: { name: string; url: string; cadence: string };
+  warnings: string[];
+  history: T[];
+  coverage: { from: string; to: string; publications: number };
+}
+
+export type FailsToDeliverPayload = ShortSidePublication<FailsToDeliverObservation>;
+export type OtcVolumePayload = ShortSidePublication<OtcVolumeObservation>;