gloomberb 0.18.3 → 0.18.4

package/src/api-client/hiring.ts

@@ -108,3 +108,304 @@ export interface HiringBoard {
   locked: number
   companies: HiringSummary[]
 }
+
+/**
+ * Why a company's week is not measured: the collection changed, so its new
+ * roles say nothing about hiring (docs/hiring-app-attention.md, Moves).
+ */
+export type HiringMoveExclusion =
+  | "first_read" | "source_added" | "identity_reset" | "catch_up" | "retired" | "truncated" | "rediscovered"
+  | "recipe_restored" | "careers_url_dropped" | "read_gap" | "collapsed" | "no_read" | "vendor_wide"
+
+export interface HiringMoveWeek {
+  week: string
+  newRoles: number | null
+  closedRoles: number | null
+  openRoles: number | null
+  reads: number
+  measured: boolean
+  excluded: HiringMoveExclusion[]
+}
+
+/**
+ * Why a move is held from alerts and ranked after the others: one day carried
+ * most of its new roles, its boards were read too seldom to tell a steady
+ * rise from a batch, or it is more roles than the boards ever held open.
+ */
+export type HiringMoveFlag = "one_day_batch" | "few_reads" | "outsized"
+
+/** A company's new roles in one UTC week against its own measured weeks before and its peers'. */
+export interface HiringMove {
+  symbol: string
+  name: string
+  sector: string | null
+  industry: string | null
+  sourceTickers: string[]
+  week: string
+  newRoles: number
+  closedRoles: number
+  openRoles: number
+  /** `values` is empty in a free read: the weeks are history. */
+  baseline: { weeks: number; mean: number; sd: number; values: Array<{ week: string; newRoles: number }> }
+  ratio: number | null
+  zScore: number
+  peers: { group: "industry" | "sector" | "universe"; label: string; companies: number; medianRatio: number | null }
+  peerRelative: number | null
+  direction: "accelerating" | "slowing" | null
+  /** `with_peers`: the company moved, and so did its peers. */
+  signal: "accelerating" | "slowing" | "with_peers" | null
+  /** Role families behind the move, each scaled to the week's measured new roles. */
+  drivers: Array<{ id: string; label: string; newRoles: number; baselineMean: number }>
+  topTitles: Array<{ title: string; count: number }>
+  /** Absent from a server before flags. */
+  flags?: HiringMoveFlag[]
+  /** The day with the most new roles that week, and how many. */
+  peakDay?: { day: string; newRoles: number } | null
+  /** A board that cannot place its new roles on a day: its reads that week and the days they counted. */
+  unplacedRead?: { reads: number; days: number | null } | null
+  /** The most roles the company's boards held open in a week before. */
+  priorMaxOpen?: number | null
+  why: string
+  firstComputedAt: string
+  computedAt: string
+  /** Since when the current signal has held; it alerts once a pass 12 hours on keeps it. */
+  signalSince?: string
+  confirmed?: boolean
+}
+
+export interface HiringMovePosting {
+  id: string
+  title: string
+  url: string | null
+  location: string | null
+  country: string | null
+  jobFunction: string | null
+  seniority: string | null
+  firstSeenAt: string
+  closedAt: string | null
+  sourceTicker: string
+}
+
+export type HiringMovesFilter = "all" | "moves" | "accelerating" | "slowing"
+
+export interface HiringMovesBoard {
+  generatedAt: string
+  proRequired: true
+  preview: boolean
+  week: string | null
+  /** A free read is always the own moves, whatever was asked. */
+  filter?: HiringMovesFilter
+  total: number
+  locked: number
+  coverage: {
+    measured: number
+    signals: { accelerating: number; slowing: number; withPeers: number }
+    unmeasured: number
+    unmeasuredReasons: Partial<Record<HiringMoveExclusion, number>>
+    computedAt: string | null
+    baselineWeeks: number
+  }
+  moves: HiringMove[]
+}
+
+export interface HiringCompanyMoves {
+  generatedAt: string
+  proRequired: true
+  preview: boolean
+  symbol: string
+  requestedSymbol?: string
+  name: string | null
+  latest: HiringMove | null
+  /** The latest week, measured or not. */
+  week: HiringMoveWeek | null
+  weeks: HiringMoveWeek[]
+  history: Array<Pick<HiringMove, "week" | "newRoles" | "ratio" | "zScore" | "peerRelative" | "direction" | "signal" | "computedAt">>
+  evidence: { added: HiringMovePosting[]; closed: HiringMovePosting[] }
+  evidenceTotals: { added: number; closed: number }
+  /** `move`: a free read of a company off the free board keeps its week, not its move. */
+  locked: { history: number; added: number; closed: number; move?: number }
+}
+
+/**
+ * HIRE's Expansion and Anomalies tabs: a company's first roles in a country
+ * or city, one place or role family far above its own weeks, and role
+ * families it never posted, in the latest complete week.
+ */
+export type HiringSignalGroup = "expansion" | "anomalies"
+export type HiringSignalKind = "new_country" | "new_city" | "location_spike" | "function_spike" | "new_role_type"
+export type HiringSignalsFilter = "all" | HiringSignalKind
+/** Why a company's week gives no signal at all. */
+export type HiringSignalHold = "unmeasured" | "short_watch" | "recounted"
+/** Why a kind was not looked for at a company, or a first or a spike was dropped. */
+export type HiringSignalSkip = "thin_history" | "unplaced_history" | "unplaced_cities" | "unclassified_history" | "reformatted" | "posted_before_watch" | "similar_city" | "one_day"
+/** A spike shown last: a seldom-read board, or a week Moves flagged. */
+export type HiringSignalFlag = "few_reads" | "one_day_batch"
+
+export interface HiringWeekSignal {
+  symbol: string
+  name: string
+  sector: string | null
+  industry: string | null
+  sourceTickers: string[]
+  week: string
+  kind: HiringSignalKind
+  group: HiringSignalGroup
+  dimension: "country" | "city" | "function"
+  /** `MX`, `austin|US`, `data_ai`. */
+  key: string
+  /** `Mexico`, `Austin, TX, US`, `Data & AI`. */
+  label: string
+  country: string | null
+  newRoles: number
+  titles: number
+  /** How far back "never" goes: every board read since `watchedSince`, and the postings seen before the week. */
+  history: { watchedSince: string; priorPostings: number; priorShare: number | null }
+  /** A spike's weeks before; `values` is empty in a free read. */
+  baseline: { weeks: number; mean: number; values: Array<{ week: string; newRoles: number }> } | null
+  ratio: number | null
+  zScore: number | null
+  /** The company's own pace in the same terms, for a spike. */
+  companyRatio: number | null
+  flags: HiringSignalFlag[]
+  reads: number | null
+  topTitles: Array<{ title: string; count: number }>
+  places: Array<{ label: string; count: number }>
+  postings: HiringMovePosting[]
+  why: string
+  firstComputedAt: string
+  computedAt: string
+}
+
+export interface HiringSignalsBoard {
+  generatedAt: string
+  proRequired: true
+  preview: boolean
+  group: HiringSignalGroup
+  /** A free read is always the group's first three, whatever was asked. */
+  filter: HiringSignalsFilter
+  week: string | null
+  total: number
+  locked: number
+  coverage: {
+    measured: number
+    counts: Partial<Record<HiringSignalKind, number>>
+    held: Partial<Record<HiringSignalHold, number>>
+    skipped: Partial<Record<HiringSignalSkip, number>>
+    /** The earliest and latest first read of a measured company: how far back "never" goes. */
+    watchedFrom: string | null
+    watchedTo: string | null
+    computedAt: string | null
+  }
+  signals: HiringWeekSignal[]
+}
+
+export interface HiringCompanySignals {
+  generatedAt: string
+  proRequired: true
+  preview: boolean
+  symbol: string
+  requestedSymbol?: string
+  name: string | null
+  week: string | null
+  watchedSince: string | null
+  held: HiringSignalHold | null
+  skipped: HiringSignalSkip[]
+  /** The latest week's signals, both groups. */
+  signals: HiringWeekSignal[]
+  history: HiringWeekSignal[]
+  /** What a free read holds back: this week's, earlier weeks', and both by tab. Absent by tab from a server before it. */
+  locked: { signals: number; history: number } & Partial<Record<HiringSignalGroup, number>>
+}
+
+/**
+ * HIRE's Building tab: the role families and themes whose share of a
+ * company's new roles rose against its own weeks before, and each company's
+ * whole mix, recent weeks against the weeks before.
+ */
+type HiringBuildingDimension = "function" | "theme"
+export type HiringBuildingFilter = "all" | HiringBuildingDimension
+/** Why a company has no mix to compare. */
+export type HiringBuildingHold = "shared_board" | "unmeasured" | "recounted" | "rescoped" | "short_watch" | "thin"
+/** Compared in part: no family mix, or some themes not yet read. */
+export type HiringBuildingSkip = "unclassified" | "unread_titles"
+
+export interface HiringMixRow {
+  dimension: HiringBuildingDimension
+  /** `sales`, `ai_ml`. */
+  key: string
+  /** `Sales`, `AI & machine learning`. */
+  label: string
+  recentRoles: number
+  /** Of the recent weeks' roles with a role family (a family), or of all of them (a theme). */
+  recentShare: number
+  beforeRoles: number
+  beforeShare: number
+  change: number
+  /** A theme whose titles have all been read; a family always is. */
+  read: boolean
+}
+
+interface HiringBuildingWeek { week: string; roles: number; classified: number }
+
+export interface HiringBuildingShift {
+  symbol: string
+  name: string
+  sector: string | null
+  industry: string | null
+  sourceTickers: string[]
+  week: string
+  dimension: HiringBuildingDimension
+  key: string
+  label: string
+  /** `values` is empty in a free read. */
+  recent: { weeks: number; roles: number; total: number; share: number; values: Array<{ week: string; roles: number; total: number }> }
+  before: { weeks: number; roles: number; total: number; share: number; values: Array<{ week: string; roles: number; total: number }> }
+  change: number
+  ratio: number | null
+  zScore: number
+  titles: number
+  topTitles: Array<{ title: string; count: number }>
+  postings: HiringMovePosting[]
+  why: string
+  firstComputedAt: string
+  computedAt: string
+}
+
+export interface HiringBuildingBoard {
+  generatedAt: string
+  proRequired: true
+  preview: boolean
+  /** A free read is always the first three, whatever was asked. */
+  filter: HiringBuildingFilter
+  week: string | null
+  total: number
+  locked: number
+  coverage: {
+    measured: number
+    counts: Partial<Record<HiringBuildingDimension, number>>
+    held: Partial<Record<HiringBuildingHold, number>>
+    skipped: Partial<Record<HiringBuildingSkip, number>>
+    /** Theme titles in the weeks compared, and how many the model has read. */
+    themeTitles: { titles: number; read: number }
+    computedAt: string | null
+  }
+  shifts: HiringBuildingShift[]
+}
+
+export interface HiringCompanyBuilding {
+  generatedAt: string
+  proRequired: true
+  preview: boolean
+  symbol: string
+  requestedSymbol?: string
+  name: string | null
+  week: string | null
+  held: HiringBuildingHold | null
+  skipped: HiringBuildingSkip[]
+  window: { recent: HiringBuildingWeek[]; before: HiringBuildingWeek[] } | null
+  functions: HiringMixRow[]
+  themes: HiringMixRow[]
+  shifts: HiringBuildingShift[]
+  history: HiringBuildingShift[]
+  locked: { functions: number; themes: number; shifts: number; history: number }
+}

package/src/api-client/index.ts

@@ -62,7 +62,7 @@ export type {
 /** Server-side caps for `/assist/command`; enforced here so a 422 is never sent. */
 const ASSIST_QUERY_MAX_LENGTH = 200;
 const ASSIST_COMMAND_LIMIT = 150;
-/** The futures curve's root list is the longest a command sends: 76 since GLO-783. */
+/** The futures curve's root list is the longest a command sends: 76. */
 export const ASSIST_ARG_OPTION_LIMIT = 128;
 const ASSIST_ARG_OPTION_VALUE_MAX_LENGTH = 40;
 const ASSIST_ARG_OPTION_LABEL_MAX_LENGTH = 60;
@@ -373,9 +373,13 @@ class GloomApiClient {
   requestPasswordReset = this.auth.requestPasswordReset.bind(this.auth);
   createBrowserHandoff = this.auth.createBrowserHandoff.bind(this.auth);
 
-  /** Creates a Stripe checkout session for Cloud Pro; the URL opens in a browser. */
-  async createCloudCheckout(returnTo?: string, interval: "month" | "year" = "month"): Promise<{ url: string }> {
-    return this.request<{ url: string }>("/stripe/checkout", { method: "POST", body: JSON.stringify({ returnTo, interval }) });
+  /**
+   * Creates a Stripe checkout session for Cloud Pro; the URL opens in a browser.
+   * `link` is a short link to the same checkout, to read or scan on another
+   * device. Older servers send none.
+   */
+  async createCloudCheckout(returnTo?: string, interval: "month" | "year" = "month"): Promise<{ url: string; link?: string }> {
+    return this.request<{ url: string; link?: string }>("/stripe/checkout", { method: "POST", body: JSON.stringify({ returnTo, interval }) });
   }
 
   async recordResearchActivity(payload: {
@@ -404,7 +408,7 @@ class GloomApiClient {
   async brokerRequest<T>(
     broker: string,
     path: string,
-    options: { method?: "GET" | "POST" | "DELETE"; body?: unknown; signal?: AbortSignal } = {},
+    options: { method?: "GET" | "POST" | "PUT" | "DELETE"; body?: unknown; signal?: AbortSignal } = {},
   ): Promise<T> {
     if (!/^[a-z][a-z0-9-]{0,31}$/.test(broker)) throw new Error(`Invalid broker id "${broker}".`);
     if (path !== "" && (!/^\/[A-Za-z0-9/_.~%?=&-]*$/.test(path) || path.includes(".."))) {
@@ -782,6 +786,7 @@ class GloomApiClient {
   getCloudEconomicCalendar = this.data.getCloudEconomicCalendar.bind(this.data);
   getCloudEconomicCalendarFrom = this.data.getCloudEconomicCalendarFrom.bind(this.data);
   getCloudMacroReleaseDays = this.data.getCloudMacroReleaseDays.bind(this.data);
+  getCloudShortRates = this.data.getCloudShortRates.bind(this.data);
   getCloudEquityDiagnostic = this.data.getCloudEquityDiagnostic.bind(this.data);
   getCloudEarningsCalendar = this.data.getCloudEarningsCalendar.bind(this.data);
   getCloudEarningsHistory = this.data.getCloudEarningsHistory.bind(this.data);
@@ -790,6 +795,7 @@ class GloomApiClient {
   getCloudCryptoMarkets = this.data.getCloudCryptoMarkets.bind(this.data);
   getCloudStablecoinSupply = this.data.getCloudStablecoinSupply.bind(this.data);
   getCloudStablecoinSupplyHistory = this.data.getCloudStablecoinSupplyHistory.bind(this.data);
+  getCloudDefiTvl = this.data.getCloudDefiTvl.bind(this.data);
   getCloudCentralBankRates = this.data.getCloudCentralBankRates.bind(this.data);
   getMobileAlertHistory = this.data.getMobileAlertHistory.bind(this.data);
   getScannerFlowHistory = this.data.getScannerFlowHistory.bind(this.data);
@@ -800,6 +806,7 @@ class GloomApiClient {
   getFundMembers = this.data.getFundMembers.bind(this.data);
   getFundChanges = this.data.getFundChanges.bind(this.data);
   getFundFacts = this.data.getFundFacts.bind(this.data);
+  getCloudExchangeAnnouncements = this.data.getCloudExchangeAnnouncements.bind(this.data);
   getCloudThemes = this.data.getCloudThemes.bind(this.data);
   getCloudThemeMembers = this.data.getCloudThemeMembers.bind(this.data);
   impliedVolatility = this.data.impliedVolatility.bind(this.data);
@@ -815,7 +822,10 @@ class GloomApiClient {
   getPublicInsolvencyNotices = this.data.getPublicInsolvencyNotices.bind(this.data);
   getPublicLetters = this.data.getPublicLetters.bind(this.data);
   getCloudIpoCalendar = this.data.getCloudIpoCalendar.bind(this.data);
+  getCloudFailsToDeliver = this.data.getCloudFailsToDeliver.bind(this.data);
+  getCloudOtcVolume = this.data.getCloudOtcVolume.bind(this.data);
   getCloudShortVolume = this.data.getCloudShortVolume.bind(this.data);
+  getCloudCryptoEtfFlows = this.data.getCloudCryptoEtfFlows.bind(this.data);
   getCloudSocialMentions = this.data.getCloudSocialMentions.bind(this.data);
   getCloudSocialMentionPosts = this.data.getCloudSocialMentionPosts.bind(this.data);
   getCloudFuturesCurve = this.data.getCloudFuturesCurve.bind(this.data);
@@ -828,6 +838,11 @@ class GloomApiClient {
   creditDocuments = this.data.creditDocuments.bind(this.data);
   geo = this.data.geo.bind(this.data);
   getCloudHiring = this.data.getCloudHiring.bind(this.data);
+  getCloudHiringMoves = this.data.getCloudHiringMoves.bind(this.data);
+  getCloudHiringSignals = this.data.getCloudHiringSignals.bind(this.data);
+  getCloudHiringCompanySignals = this.data.getCloudHiringCompanySignals.bind(this.data);
+  getCloudHiringBuilding = this.data.getCloudHiringBuilding.bind(this.data);
+  getCloudHiringCompanyBuilding = this.data.getCloudHiringCompanyBuilding.bind(this.data);
   getCloudAppRankHistory = this.data.getCloudAppRankHistory.bind(this.data);
   getCloudAppAttention = this.data.getCloudAppAttention.bind(this.data);
   getCloudCatalystChanges = this.data.getCloudCatalystChanges.bind(this.data);
@@ -872,6 +887,7 @@ class GloomApiClient {
   getCloudTape = this.data.getCloudTape.bind(this.data);
   getCloudYieldCurve = this.data.getCloudYieldCurve.bind(this.data);
   getCloudCurve = this.data.getCloudCurve.bind(this.data);
+  getCloudSwapCurve = this.data.getCloudSwapCurve.bind(this.data);
   getCloudCurveHistory = this.data.getCloudCurveHistory.bind(this.data);
   getCloudWorldCurves = this.data.getCloudWorldCurves.bind(this.data);
   getCloudCds = this.data.getCloudCds.bind(this.data);
@@ -882,6 +898,7 @@ class GloomApiClient {
   getCloudCongressHouse = this.data.getCloudCongressHouse.bind(this.data);
   getCloudJobs = this.data.getCloudJobs.bind(this.data);
   getCloudJobsPostings = this.data.getCloudJobsPostings.bind(this.data);
+  getCloudJobsPosting = this.data.getCloudJobsPosting.bind(this.data);
   getCloudJobsMovers = this.data.getCloudJobsMovers.bind(this.data);
   getCloudEarningsCalls = this.data.getCloudEarningsCalls.bind(this.data);
   getCloudEarningsTranscript = this.data.getCloudEarningsTranscript.bind(this.data);

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[];

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

@@ -16,6 +16,7 @@ import {
   type ConnectionHealthRegistry,
 } from "../core/connection-health";
 import { SESSION_COOKIE_NAMES } from "./session-cookie";
+import { asDataServiceFailure } 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";
@@ -162,6 +163,22 @@ function throwIfRequestAborted(signal: AbortSignal | null | undefined): void {
   );
 }
 
+/**
+ * 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.
+ */
+async function reachService<R>(fetch: () => Promise<R>, signal: AbortSignal | null | undefined): Promise<R> {
+  try {
+    return await fetch();
+  } catch (error) {
+    if (signal?.aborted) throw error;
+    throw asDataServiceFailure(error);
+  }
+}
+
 export class CloudApiRequestTransport {
   private sessionToken: string | null = null;
   private sessionCookieName: SessionCookieName | null = null;
@@ -263,11 +280,11 @@ export class CloudApiRequestTransport {
       GLOOM_CLOUD_HTTP_CONNECTION_ID,
       operation,
       async () => {
-        const response = await streamFetch(`${this.baseUrl}${path}`, {
+        const response = await 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", ""));
@@ -372,14 +389,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 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/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>;