gloomberb 0.19.1 → 0.19.3

package/src/api-client/data.ts

@@ -10,6 +10,7 @@ import type { PerpBoardPayload, PerpEquitiesPayload, PerpEquityListing, PerpHist
   PerpMarketPayload, PerpLiquidationsPayload, PerpDepthPayload } from "./perps";
 import type { ExposureRequest, ExposurePayload, ExposureScenario } from "./exposure";
 import type { SupplyChainPayload, SupplyOptions } from "./supply-chain";
+import { createReadCoalescer } from "./coalesce";
 import { supplyGraphQuery, type GraphOptions, type GraphPayload } from "./supply-chain-graph";
 import type { AwardDetailPayload, AwardFilter, AwardsPayload } from "./awards";
 import type { EarningsEvent } from "../types/data-provider";
@@ -30,7 +31,7 @@ import type { IpoCalendarParams, IpoCalendarPayload } from "./ipo";
 import type { TickerChanges } from "../types/ticker-changes";
 import type { IssuerListings } from "../types/issuer-listings";
 import type { OrganizationTickersResponse } from "./organization-tickers";
-import type { CryptoMarketsPayload, DefiTvlPayload, StablecoinSupplyHistoryPayload, StablecoinSupplyPayload } from "./crypto-markets";
+import type { BitcoinNetworkPayload, CryptoMarketsPayload, DefiTvlPayload, StablecoinSupplyHistoryPayload, StablecoinSupplyPayload } from "./crypto-markets";
 import type { CryptoEtfFlowAsset, CryptoEtfFlowsPayload } from "./crypto-etf-flows";
 import type { CentralBankRatesPayload } from "./central-bank-rates";
 import type { EstimateRevisionsPayload } from "./estimate-revisions";
@@ -53,7 +54,7 @@ import type { CpiBoardPayload } from "./cpi";
 import type { TapeRange, TapeSnapshot } from "./tape";
 import { LIVE_SCAN_PATH, type LiveScanPayload, type LiveScanWireDefinition } from "./live-scan";
 import { signalWithTimeout } from "../utils/async-deadline";
-import { ApiRequestError } from "./errors";
+import { ApiRequestError, isRetryableApiError, markAskedTwice } from "./errors";
 import type { ExchangeRateSnapshot } from "../types/exchange-rate";
 import type { RatePathPayload } from "./rates";
 import type { EarningsCalendarPayload, EarningsCalendarQuery, EarningsHistoryPayload } from "./earnings";
@@ -204,8 +205,161 @@ function batchAnswers<K extends string, T>(response: CloudMarketResponse<CloudBa
   return answers;
 }
 
+/** How long a listing read waits before asking again after the service said its source failed. */
+const LISTING_RETRY_DELAY_MS = 400;
+
+/**
+ * Whether a failed listing read is asked again: the service answered that its
+ * own source failed (`retryable_error`, or the catch-all `fatal_error`, with no
+ * data), or failed with a 5xx or a timeout. A rate limit is never asked again,
+ * whatever wait it names: asking again is more of what it refused. An answer of
+ * no data, a refusal, and a request that never reached the service
+ * (`DataServiceUnreachableError`) are not asked again either.
+ */
+function isListingReadRetried(outcome: { response: CloudMarketResponse<unknown> } | { error: unknown }): boolean {
+  if ("response" in outcome) {
+    const { status, data } = outcome.response ?? {};
+    return (status === "retryable_error" || status === "fatal_error") && data == null;
+  }
+  return isRetryableApiError(outcome.error) && (outcome.error as ApiRequestError).status !== 429;
+}
+
+/**
+ * `batch`: the caller asks many reads like this one in the same moment (a
+ * board's rows), so the read may wait a few milliseconds to go out in a batch
+ * request with them. Any other read goes out on its own at once.
+ */
+export interface BatchableRead {
+  batch?: boolean;
+}
+
 export class CloudDataApi {
-  constructor(private readonly request: CloudApiRequest) {}
+  constructor(
+    private readonly request: CloudApiRequest,
+    /** The wait before a failed listing read is asked again (`readListing`); tests set 0. */
+    private readonly listingRetryDelayMs = LISTING_RETRY_DELAY_MS,
+  ) {}
+
+  /**
+   * Histories asked with others (`batch`) in the same moment with the same
+   * bars (a futures board's contracts, SOVR's currencies) go out as
+   * `/market/history/batch` requests, each answered as its own
+   * `/market/history` would be. Sixteen a request, sent side by side: a
+   * board's seventy-two rows are five requests, and the first rows land as
+   * soon as sixteen reads have.
+   */
+  private readonly histories = createReadCoalescer<
+    { symbol: string; exchange: string; params: Pick<CloudHistoryParams, "interval" | "outputsize" | "rangeKey"> },
+    CloudMarketResponse<CloudPricePointPayload[]>
+  >({
+    max: 16,
+    // Reads asked alone after a refused batch stay within what the panes kept in flight before: SOVR four, the board twelve with its terms.
+    fallbackConcurrency: 4,
+    group: ({ params }) => `${params.interval ?? ""}|${params.outputsize ?? ""}|${params.rangeKey ?? ""}`,
+    single: ({ symbol, exchange, params }) => this.request(cloudHistoryPath(symbol, exchange, params)),
+    batch: async (keys) => {
+      const { interval, outputsize, rangeKey } = keys[0]!.params;
+      // The server answers each target in the order asked, so a listing asked twice is asked once.
+      const targetKey = ({ symbol, exchange }: { symbol: string; exchange: string }) => `${symbol}\u001f${exchange}`;
+      const targets = [...new Map(keys.map((key) => [targetKey(key), { symbol: key.symbol, exchange: key.exchange }])).values()];
+      const response = await this.request<CloudMarketResponse<{ items: Array<CloudMarketResponse<CloudPricePointPayload[]>> }>>("/market/history/batch", {
+        method: "POST",
+        body: JSON.stringify({
+          targets,
+          interval: interval ?? "1day",
+          ...(outputsize != null ? { outputsize: String(outputsize) } : {}),
+          ...(rangeKey ? { rangeKey } : {}),
+        }),
+      });
+      const items = response.data?.items;
+      // An answer that does not line up with the targets asked is not matched by place: each read is asked on its own.
+      if (!Array.isArray(items) || items.length !== targets.length) return keys.map(() => undefined);
+      const byTarget = new Map(targets.map((target, index) => [targetKey(target), items[index]]));
+      return keys.map((key) => byTarget.get(targetKey(key)));
+    },
+  });
+
+  /**
+   * Futures terms asked with others in the same moment (a futures board's rows) go out as
+   * `/cloud/futures/contracts` requests, sixteen a request like the histories.
+   * A symbol without known terms answers null there, which reads as the 404
+   * its own request answers.
+   */
+  private readonly futuresTerms = createReadCoalescer<string, FuturesContractTermsPayload | null>({
+    max: 16,
+    // With the board's histories' four, the twelve reads it kept in flight before.
+    fallbackConcurrency: 8,
+    group: () => "",
+    single: (symbol) => this.request<FuturesContractTermsPayload>(`/cloud/futures/contract/${encodeURIComponent(symbol)}`, { signal: AbortSignal.timeout(20_000) }),
+    batch: async (symbols) => {
+      // The server answers each symbol once, by the symbol asked.
+      const { items } = await this.getCloudFuturesContracts([...new Set(symbols)]);
+      const bySymbol = new Map(items.map((item) => [item.symbol, item]));
+      // A failed read is asked again on its own.
+      return symbols.map((symbol) => bySymbol.get(symbol)?.error ? undefined : bySymbol.get(symbol)?.terms);
+    },
+  });
+
+  /**
+   * Expiries of one listing's chain asked with others in the same moment (a
+   * volatility surface's) go out as `/market/options/batch` requests, each answered as
+   * its own `/market/options` would be. Six a request, the server's one round,
+   * sent side by side: a surface's eighteen expiries are three requests.
+   */
+  private readonly optionsChains = createReadCoalescer<
+    { symbol: string; exchange?: string; expirationDate: number },
+    CloudMarketResponse<CloudOptionsChainPayload>
+  >({
+    max: 6,
+    fallbackConcurrency: 4,
+    group: ({ symbol, exchange }) => `${symbol}|${exchange ?? ""}`,
+    single: ({ symbol, exchange, expirationDate }) => this.request(cloudOptionsChainPath(symbol, exchange, expirationDate)),
+    batch: async (keys) => {
+      const { symbol, exchange } = keys[0]!;
+      // The server answers each expiry once, naming it.
+      const expiries = [...new Set(keys.map((key) => key.expirationDate))];
+      const search = new URLSearchParams({ symbol, expirationDates: expiries.join(",") });
+      if (exchange) search.set("exchange", exchange);
+      const response = await this.request<CloudMarketResponse<{ items: Array<CloudMarketResponse<CloudOptionsChainPayload> & { expirationDate?: number }> }>>(
+        `/market/options/batch?${search}`,
+      );
+      const byExpiry = new Map((response.data?.items ?? []).map(({ expirationDate, ...item }) => [expirationDate, item]));
+      return keys.map((key) => byExpiry.get(key.expirationDate));
+    },
+  });
+
+  /**
+   * Whether reads of `kind` asked together go out in batch requests now:
+   * false while the service answers that batch route 404, until it is asked
+   * again. A caller limiting its reads in flight asks them all at once only
+   * when they do.
+   */
+  batchesReads(kind: "history" | "options" | "futures-terms"): boolean {
+    const coalescer = kind === "history" ? this.histories : kind === "options" ? this.optionsChains : this.futuresTerms;
+    return coalescer.batching();
+  }
+
+  /**
+   * A listing's quote, history or financials, asked again once when the
+   * service failed to answer it (`isListingReadRetried`): its source blinks for a
+   * few minutes at a time, and a known listing then read as one no source
+   * covers. A caller's abort stops the second ask.
+   */
+  private async readListing<T>(read: () => Promise<CloudMarketResponse<T>>, signal?: AbortSignal): Promise<CloudMarketResponse<T>> {
+    const first = await read().then((response) => ({ response }), (error: unknown) => ({ error }));
+    const settle = () => {
+      if ("error" in first) throw first.error;
+      return first.response;
+    };
+    if (!isListingReadRetried(first) || signal?.aborted) return settle();
+    if (this.listingRetryDelayMs > 0) await new Promise((resolve) => setTimeout(resolve, this.listingRetryDelayMs));
+    if (signal?.aborted) return settle();
+    const second = await read().then((response) => ({ response }), (error: unknown) => ({ error }));
+    // Failing the same way twice, the service did not answer it (`markAskedTwice`).
+    if (isListingReadRetried(second)) markAskedTwice("error" in second ? second.error : second.response);
+    if ("error" in second) throw second.error;
+    return second.response;
+  }
 
   private requestMarketSymbol<T>(
     path: string,
@@ -315,7 +469,7 @@ export class CloudDataApi {
     symbol: string,
     exchange?: string,
   ): Promise<CloudMarketResponse<CloudQuotePayload>> {
-    return this.requestMarketSymbol("/market/quote", symbol, exchange);
+    return this.readListing(() => this.requestMarketSymbol("/market/quote", symbol, exchange));
   }
 
   async getCloudQuotesBatch(
@@ -323,7 +477,7 @@ export class CloudDataApi {
     mode: "cache-first" | "refresh" = "cache-first",
     options: { signal?: AbortSignal } = {},
   ): Promise<CloudMarketResponse<CloudMarketBatchPayload<CloudQuotePayload>>> {
-    return this.postMarketBatch("/market/quotes/batch", targets, mode, options.signal);
+    return this.readListing(() => this.postMarketBatch("/market/quotes/batch", targets, mode, options.signal), options.signal);
   }
 
   async getCloudWorldVenues(): Promise<
@@ -388,7 +542,10 @@ export class CloudDataApi {
     symbol: string,
     exchange?: string,
     expirationDate?: number,
+    options: BatchableRead = {},
   ): Promise<CloudMarketResponse<CloudOptionsChainPayload>> {
+    // A dated expiry asked with others may go out with the listing's other expiries asked in the same moment.
+    if (expirationDate != null && options.batch) return this.optionsChains.read({ symbol, exchange, expirationDate });
     return this.request<CloudMarketResponse<CloudOptionsChainPayload>>(
       cloudOptionsChainPath(symbol, exchange, expirationDate),
     );
@@ -400,14 +557,14 @@ export class CloudDataApi {
     statementHistory?: "extended",
   ): Promise<CloudMarketResponse<CloudFinancialsPayload>> {
     const path = cloudMarketSymbolPath("/market/financials", symbol, exchange);
-    return this.request(statementHistory === "extended" ? `${path}&statementHistory=extended` : path);
+    return this.readListing(() => this.request(statementHistory === "extended" ? `${path}&statementHistory=extended` : path));
   }
 
   async getCloudFinancialsBatch(
     targets: CloudMarketBatchTarget[],
     mode: "cache-first" | "refresh" = "cache-first",
   ): Promise<CloudMarketResponse<CloudMarketBatchPayload<CloudFinancialsPayload>>> {
-    return this.postMarketBatch("/market/financials/batch", targets, mode);
+    return this.readListing(() => this.postMarketBatch("/market/financials/batch", targets, mode));
   }
 
   async getCloudHolders(
@@ -518,12 +675,16 @@ export class CloudDataApi {
     symbol: string,
     exchange: string,
     params: CloudHistoryParams = {},
-    options: { signal?: AbortSignal } = {},
+    options: { signal?: AbortSignal } & BatchableRead = {},
   ): Promise<CloudMarketResponse<CloudPricePointPayload[]>> {
-    return this.request<CloudMarketResponse<CloudPricePointPayload[]>>(
-      cloudHistoryPath(symbol, exchange, params),
-      options.signal ? { signal: options.signal } : undefined,
-    );
+    // Trailing bars asked with others, not a session, window or recovery of their own, may go out with the others asked in the same moment.
+    const shared = options.batch && !options.signal && !params.startDate && !params.endDate && !params.historyRecovery && !params.session;
+    return this.readListing(() => shared
+      ? this.histories.read({ symbol, exchange, params: { interval: params.interval, outputsize: params.outputsize, rangeKey: params.rangeKey } })
+      : this.request<CloudMarketResponse<CloudPricePointPayload[]>>(
+        cloudHistoryPath(symbol, exchange, params),
+        options.signal ? { signal: options.signal } : undefined,
+      ), options.signal);
   }
 
   async getCloudExchangeRate(
@@ -732,6 +893,19 @@ export class CloudDataApi {
     return this.request<AwardDetailPayload>(`/cloud/awards/detail/${encodeURIComponent(id)}${query}`, { signal });
   }
 
+  /** Many symbols' disclosures, each as getCloudSupplyChain reads it; an item that failed has the status its own read would have had. */
+  async getCloudSupplyChains(symbols: string[], options: SupplyOptions = {}): Promise<{ items: Array<{ symbol: string; chain?: SupplyChainPayload; status?: number }> }> {
+    const query = new URLSearchParams({ symbols: symbols.join(",") });
+    if (options.tiers?.length) query.set("tiers", options.tiers.join(","));
+    if (options.includeLeads) query.set("includeLeads", "1");
+    return this.request(`/cloud/supply-chain/batch?${query}`);
+  }
+
+  /** Many symbols' graphs on the same options, each as getCloudSupplyGraph reads it. */
+  async getCloudSupplyGraphs(symbols: string[], options: Partial<GraphOptions> = {}): Promise<{ items: Array<{ symbol: string; graph?: GraphPayload; status?: number }> }> {
+    return this.request(`/cloud/supply-chain/graphs?symbols=${encodeURIComponent(symbols.join(","))}&${supplyGraphQuery(options)}`);
+  }
+
   async getCloudSupplyGraph(symbol: string, options: Partial<GraphOptions> = {}): Promise<GraphPayload> {
     return this.request<GraphPayload>(`/cloud/supply-chain/${encodeURIComponent(symbol)}/graph?${supplyGraphQuery(options)}`);
   }
@@ -896,6 +1070,11 @@ export class CloudDataApi {
     return this.request<DefiTvlPayload>("/cloud/crypto/defi/tvl", { signal: AbortSignal.timeout(30_000) });
   }
 
+  /** Bitcoin's daily hash rate, the difficulty at each retarget, the next retarget's estimate and derived hashprice. */
+  async getCloudBitcoinNetwork(): Promise<BitcoinNetworkPayload> {
+    return this.request<BitcoinNetworkPayload>("/cloud/crypto/bitcoin/network", { signal: AbortSignal.timeout(30_000) });
+  }
+
   /** Daily net flows of the US spot bitcoin or ether ETFs, per fund, in US$ millions. */
   async getCloudCryptoEtfFlows(asset: CryptoEtfFlowAsset): Promise<CryptoEtfFlowsPayload> {
     return this.request<CryptoEtfFlowsPayload>(
@@ -1023,8 +1202,16 @@ export class CloudDataApi {
   }
 
   /** What a futures symbol (GC=F, GCZ26, CL1) trades: its contract, terms and latest confirmed settlement. */
-  async getCloudFuturesContract(symbol: string): Promise<FuturesContractTermsPayload> {
-    return this.request<FuturesContractTermsPayload>(`/cloud/futures/contract/${encodeURIComponent(symbol)}`, { signal: AbortSignal.timeout(20_000) });
+  async getCloudFuturesContract(symbol: string, options: BatchableRead = {}): Promise<FuturesContractTermsPayload> {
+    if (!options.batch) return this.request<FuturesContractTermsPayload>(`/cloud/futures/contract/${encodeURIComponent(symbol)}`, { signal: AbortSignal.timeout(20_000) });
+    const terms = await this.futuresTerms.read(symbol);
+    if (!terms) throw new ApiRequestError("Not a futures symbol with known contract terms", 404);
+    return terms;
+  }
+
+  /** Many symbols' terms, each as getCloudFuturesContract reads it: null for one without known terms, an error for a failed read. */
+  async getCloudFuturesContracts(symbols: string[]): Promise<{ items: Array<{ symbol: string; terms: FuturesContractTermsPayload | null; error?: string }> }> {
+    return this.request(`/cloud/futures/contracts?${new URLSearchParams({ symbols: symbols.join(",") })}`, { signal: AbortSignal.timeout(30_000) });
   }
 
   async getCloudFuturesCurveAsOf(root: string, date: string): Promise<FuturesCurveAsOfPayload> {

package/src/api-client/equity-screener.ts

@@ -23,6 +23,15 @@ export const OPTION_VOLATILITY_FIELDS = ["iv30Percent", "ivPercentile", "iv30Cha
  * listed only when asked (`include=ownership`), and omitted by a server from before them.
  */
 export const OWNERSHIP_FIELDS = ["sharesOutstanding", "floatShares", "shortPercentOfFloat", "institutionalOwnershipPercent"] as const;
+/**
+ * ROIC, FCF yield, leverage, revenue and EPS CAGRs and consensus growth, on the bases `FA` and `EE` use; listed only
+ * when asked (`include=quality`), and omitted by a server from before them.
+ */
+export const QUALITY_FIELDS = [
+  "roicPercent", "fcfYieldPercent", "netDebtToEbitda", "debtToEquity",
+  "revenueCagr3YPercent", "revenueCagr5YPercent", "epsCagr3YPercent", "epsCagr5YPercent",
+  "forwardRevenueGrowthPercent", "forwardEpsGrowthPercent",
+] as const;
 export const NUMERIC_FIELDS = [
   ...KPI_FIELDS,
   "price",
@@ -73,6 +82,7 @@ export const NUMERIC_FIELDS = [
   "ivToHv",
   ...OPTION_VOLATILITY_FIELDS,
   ...OWNERSHIP_FIELDS,
+  ...QUALITY_FIELDS,
   "hiringOpenRoles", "hiringNetAddsWeek", "hiringRemotePercent", "hiringZScore",
   "appAttentionScore", "appRankVelocity7d", "appRatingDrift7d", "appRatingCountGrowth7d",
 ] as const;

package/src/api-client/errors.ts

@@ -1,3 +1,5 @@
+import { isNetworkFailure } from "../utils/network-failure";
+
 const HARD_SESSION_INVALID_PATTERNS = [
   /\b(user|account)\b.*\b(not found|deleted|removed|disabled|deactivated|suspended)\b/i,
   /\b(user|account)\b.*\bdoes(?:\s+not|n't)\s+exist\b/i,
@@ -61,6 +63,62 @@ export function isRetryableApiError(error: unknown): boolean {
   return error.code === "retryable_error" || status === 408 || status === 429 || (status !== undefined && status >= 500);
 }
 
+/**
+ * A 200 reply saying its data is unavailable this time (a board's `unavailable`
+ * status, a market answer's `retryable_error`): the server's own source did
+ * not answer. Like a 5xx it may pass, so a saved copy answers it with its note.
+ * A permanent reason (a route not served yet, an unsupported symbol or series,
+ * sign-in or entitlement) comes as its status, or as a plain error, and stays
+ * the error.
+ */
+export function sourceDidNotAnswer(message: string): ApiRequestError {
+  return new ApiRequestError(message, undefined, undefined, "retryable_error");
+}
+
+// Registered, so a mark set by another copy of this module is still read.
+const ASKED_TWICE = Symbol.for("gloomberb.listingReadAskedTwice");
+
+/**
+ * Marks a listing read's failure, or its failed answer, as the second of two
+ * asks (`CloudDataApi.readListing`). Only such a failure is said to be the data
+ * service not answering; any other 5xx keeps the server's own words.
+ */
+export function markAskedTwice<T>(value: T): T {
+  if (value && typeof value === "object" && Object.isExtensible(value) && !wasAskedTwice(value)) {
+    Object.defineProperty(value, ASKED_TWICE, { value: true });
+  }
+  return value;
+}
+
+/** Whether a failure, or a failed answer, came from a listing read asked twice (`markAskedTwice`). */
+export function wasAskedTwice(value: unknown): boolean {
+  return !!value && typeof value === "object" && (value as Record<symbol, unknown>)[ASKED_TWICE] === true;
+}
+
+/** Codes of a connection that dropped or stalled after it opened: Node's and the system's, then Bun's. */
+const INTERRUPTED_CODES = new Set(["ECONNRESET", "ECONNABORTED", "EPIPE", "ETIMEDOUT", "ConnectionClosed"]);
+
+/**
+ * A failure asking again later may get past, which a copy saved earlier may
+ * answer for: no connection, a connection that dropped, a timeout, or a server
+ * that was rate limited or overloaded (408, 429, 5xx). Anything else the
+ * server answered (another 4xx) and an answer that failed validation are
+ * refusals to show as errors, saved copy or not. A bare throw with nothing to
+ * classify is not taken for a refusal.
+ */
+export function isTransientFailure(error: unknown): boolean {
+  if (!error || typeof error !== "object") return typeof error !== "string" || isNetworkFailure(error);
+  if (isNetworkFailure(error) || isRetryableApiError(error)) return true;
+  for (let current: unknown = error, depth = 0; current && typeof current === "object" && depth < 4; depth += 1) {
+    if (current instanceof ApiRequestError) return false;
+    const { name, code } = current as { name?: unknown; code?: unknown };
+    if (name === "AbortError" || name === "TimeoutError") return true;
+    if (typeof code === "string" && INTERRUPTED_CODES.has(code)) return true;
+    current = (current as { cause?: unknown }).cause;
+  }
+  return false;
+}
+
 /** Reads `Retry-After` as milliseconds, accepting seconds or an HTTP date. */
 export function parseRetryAfterMs(
   header: string | null,

package/src/api-client/gpu.ts

@@ -45,6 +45,33 @@ export interface GpuBoardRow extends GpuObservation {
   lastError: string | null;
 }
 
+/**
+ * Gloom's daily settle: the official price of one GPU and form factor for a
+ * day, set at 20:00 UTC and never revised. A day with too few prices is
+ * "no-settle" with no price. A correction is a new entry naming the one it
+ * replaces.
+ */
+export interface GpuSettle {
+  id: string;
+  /** The settle day, YYYY-MM-DD. */
+  date: string;
+  /** The moment the price stands for: the day at 20:00 UTC. */
+  settleAt: string;
+  gpuModel: string;
+  formFactor: string;
+  memoryGb: number | null;
+  label: string;
+  status: "settled" | "no-settle";
+  pricePerGpuHr: number | null;
+  currency: "USD";
+  kind: "settle" | "correction";
+  corrects: string | null;
+  publishedAt: string;
+  change1d: number | null;
+  change7d: number | null;
+  change30d: number | null;
+}
+
 export interface GpuBoardPayload {
   access?: GpuAccess;
   generatedAt: string;
@@ -53,6 +80,8 @@ export interface GpuBoardPayload {
   stale: boolean;
   gaps: string[];
   rows: GpuBoardRow[];
+  /** Each GPU's latest daily settle, the same on every plan. Older servers send none. */
+  settles?: GpuSettle[];
 }
 
 export interface GpuHistoryPayload {

package/src/api-client/index.ts

@@ -601,8 +601,6 @@ class GloomApiClient {
   async recordExperimentExposure(payload: {
     eventId: string; surface: "web" | "desktop" | "tui" | "cli"; anonymousId?: string;
     attribution?: Record<string, string>; experiment: string; variant?: string;
-    /** Where the experiment showed, by a content-free id like an upgrade placement. */
-    placement?: string;
   }, signal?: AbortSignal): Promise<import("./web-experiments").ExperimentAnswer> {
     return this.request("/activity/research", {
       method: "POST",
@@ -955,6 +953,7 @@ class GloomApiClient {
   getCloudStablecoinSupply = this.data.getCloudStablecoinSupply.bind(this.data);
   getCloudStablecoinSupplyHistory = this.data.getCloudStablecoinSupplyHistory.bind(this.data);
   getCloudDefiTvl = this.data.getCloudDefiTvl.bind(this.data);
+  getCloudBitcoinNetwork = this.data.getCloudBitcoinNetwork.bind(this.data);
   getCloudCentralBankRates = this.data.getCloudCentralBankRates.bind(this.data);
   getMobileAlertHistory = this.data.getMobileAlertHistory.bind(this.data);
   getScannerFlowHistory = this.data.getScannerFlowHistory.bind(this.data);
@@ -993,6 +992,8 @@ class GloomApiClient {
   getCloudFuturesCurve = this.data.getCloudFuturesCurve.bind(this.data);
   getCloudFuturesCurveAsOf = this.data.getCloudFuturesCurveAsOf.bind(this.data);
   getCloudFuturesContract = this.data.getCloudFuturesContract.bind(this.data);
+  getCloudFuturesContracts = this.data.getCloudFuturesContracts.bind(this.data);
+  batchesReads = this.data.batchesReads.bind(this.data);
   getCloudRatePath = this.data.getCloudRatePath.bind(this.data);
   getCloudShiller = this.data.getCloudShiller.bind(this.data);
   getCloudCotBoard = this.data.getCloudCotBoard.bind(this.data);
@@ -1025,6 +1026,8 @@ class GloomApiClient {
   analyzeCloudExposure = this.data.analyzeCloudExposure.bind(this.data);
   getCloudExposureScenarios = this.data.getCloudExposureScenarios.bind(this.data);
   getCloudSupplyGraph = this.data.getCloudSupplyGraph.bind(this.data);
+  getCloudSupplyChains = this.data.getCloudSupplyChains.bind(this.data);
+  getCloudSupplyGraphs = this.data.getCloudSupplyGraphs.bind(this.data);
   getCloudSupplyPaths = this.data.getCloudSupplyPaths.bind(this.data);
   getCloudSupplyChain = this.data.getCloudSupplyChain.bind(this.data);
   getCloudAwards = this.data.getCloudAwards.bind(this.data);

package/src/api-client/plan-access.ts

@@ -1,6 +1,6 @@
 import { useSyncExternalStore } from "react";
 import { apiClient } from "./index";
-import { resolvePlanAccess, type PlanAccess } from "./plan-rules";
+import { freeQuoteDelayMinutes, resolvePlanAccess, type PlanAccess, type QuoteDelayFacts } from "./plan-rules";
 
 export * from "./plan-rules";
 
@@ -25,3 +25,12 @@ export function usePlanAccess(): PlanAccess {
   );
   return resolvePlanAccess(apiClient.getCurrentUser());
 }
+
+/**
+ * The delay this account sees on a price (see {@link freeQuoteDelayMinutes}):
+ * the free tier's on a price that is not live, null with Pro or a trial.
+ * Follows sign-in and plan changes.
+ */
+export function useFreeQuoteDelay(quote: QuoteDelayFacts | null | undefined): number | null {
+  return freeQuoteDelayMinutes(usePlanAccess(), quote);
+}

package/src/api-client/plan-rules.ts

@@ -1,6 +1,8 @@
 // The plan rules alone, free of React and the API client, so the provider
 // router can gate real-time routing on the same entitlement the panes show.
 
+import type { Quote } from "../types/financials";
+
 /**
  * Minimum shape the plan helpers need. Both `AuthUser` (from `/auth/get-session`)
  * and `AccountProfile` (from `/account/profile`) satisfy it.
@@ -70,6 +72,39 @@ export function hasProAccess(user: PlanAccessUser | null | undefined, now = Date
   return user.effectivePlan === "pro" && !user.trialEndsAt;
 }
 
+/** What of a price decides whether a free account sees it late. */
+export type QuoteDelayFacts = Pick<Quote, "dataSource" | "delisting" | "priceObservation">;
+
+/**
+ * The delay in minutes an account sees on a price: the free tier's quote
+ * delay when the account has no real-time access (signed out, free, a trial
+ * that ended) and the price is not live, null otherwise. A live price (a
+ * coin, a broker's own feed) has none, and neither does a price with no delay
+ * to speak of (a delisted line's last trade, a fund's NAV). Pro and trial
+ * accounts never see one.
+ */
+export function freeQuoteDelayMinutes(
+  access: Pick<PlanAccess, "hasProAccess">,
+  quote: QuoteDelayFacts | null | undefined,
+): number | null {
+  if (access.hasProAccess || !quote) return null;
+  if (quote.dataSource === "live" || quote.delisting || quote.priceObservation === "nav") return null;
+  return CLOUD_QUOTE_DELAY_MINUTES;
+}
+
+/** The delay of the first of `quotes` an account sees late (see {@link freeQuoteDelayMinutes}), or null when none is. */
+export function freeQuotesDelayMinutes(
+  access: Pick<PlanAccess, "hasProAccess">,
+  quotes: Iterable<QuoteDelayFacts | null | undefined>,
+): number | null {
+  if (access.hasProAccess) return null;
+  for (const quote of quotes) {
+    const minutes = freeQuoteDelayMinutes(access, quote);
+    if (minutes != null) return minutes;
+  }
+  return null;
+}
+
 export function resolvePlanAccess(
   user: PlanAccessUser | null | undefined,
   now = Date.now(),

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

@@ -4,7 +4,6 @@ import { getCurrentPluginTarget } from "../plugins/current-target";
 import type { DesktopDeepLinkBridge } from "../types/desktop-deeplink";
 import { exposeExperiment, storedExperimentAssignments } from "./web-experiments";
 import { createWallExperimentSession, type WallExperiment, type WallExperimentContext, type WallTeaserVariant } from "./wall-experiments";
-import { createUpgradeExperimentSession, UPGRADE_PERSONALIZED, type UpgradeExperimentContext, type UpgradePersonalizedVariant } from "./upgrade-experiment";
 import { hasProAccess } from "./plan-rules";
 import { withDeadline } from "../utils/async-deadline";
 import { browserDoNotTrack } from "../telemetry/crash-reports-dom";
@@ -43,7 +42,6 @@ let anonymousId: string | undefined;
 let attribution: Record<string, string> = {};
 const wallExperiment = createWallExperimentSession();
 const signinWallExperiment = createWallExperimentSession("wall_teaser_signin");
-const upgradeExperiment = createUpgradeExperimentSession();
 const WALL_VIEWS_SESSION_KEY = "gloomberb.wall-teaser.views";
 
 // The desktop app also keeps a copy of these two on disk (electrobun/view/view-ids.ts).
@@ -350,7 +348,7 @@ function attributionPayload(): Record<string, string> | undefined {
 }
 
 export interface ResearchActivityDetails {
-  /** The desks picked at "What do you trade?", on the milestone that ends the first run. */
+  /** The desks picked at "What do you trade most?", on the milestone that ends the first run. */
   desks?: readonly string[];
   /**
    * Which prompt raised an `upgrade_intent` (a pane footer, a wall, the
@@ -538,35 +536,6 @@ export function exposeWallTeaser(experiment: WallExperiment = "wall_teaser"): Pr
   });
 }
 
-function upgradeExperimentContext(): UpgradeExperimentContext {
-  const { accountId, pro, optedOut, automated, session } = wallExperimentContext();
-  return { accountId, pro, optedOut, automated, session };
-}
-
-/** The `upgrade_personalized` arm this session already has, without asking; see upgrade-experiment.ts. */
-export function knownUpgradePersonalized(): UpgradePersonalizedVariant | null | undefined {
-  return upgradeExperiment.known(upgradeExperimentContext());
-}
-
-/**
- * Asks for the `upgrade_personalized` arm when an upgrade surface is shown to
- * a free account that has tickers to name, once per account and session. The
- * request says where it showed and nothing about the holdings.
- */
-export function exposeUpgradePersonalized(placement: string): Promise<UpgradePersonalizedVariant | null> {
-  const context = upgradeExperimentContext();
-  const surface = getCurrentPluginTarget();
-  return upgradeExperiment.expose(context, () => {
-    const controller = new AbortController();
-    return withDeadline(apiClient.recordExperimentExposure({
-      eventId: crypto.randomUUID(),
-      surface,
-      experiment: UPGRADE_PERSONALIZED,
-      ...(ACTIVITY_ID.test(placement) ? { placement } : {}),
-    }, controller.signal), 3_000, "Upgrade experiment request timed out", (error) => controller.abort(error));
-  });
-}
-
 /** Records the visible wall once per placement, including visitors outside the experiment. */
 export function recordWallViewed(placement: string, teaserKind?: "summary" | "sample" | "none"): void {
   recordResearchActivity("wall_viewed", undefined, undefined, { placement, teaser_kind: teaserKind });