gloomberb 0.16.1 → 0.16.3

package/README.md

@@ -86,7 +86,8 @@ Press `Ctrl+P` to open the command bar, or press `` ` `` to search for a ticker.
 | `TOP` | Market stories |
 | `WIRP` / `FFIP` | US rate path and conditional FOMC probabilities |
 | `BTMM` | Funding rates, bill curves and Federal Reserve liquidity |
-| `CTM [root]` | Futures contract curve, historical ghosts, roll yield and open interest, including `CTM VX` |
+| `CTM [root]` | Futures contract curve, historical ghosts, roll yield and open interest, including `CTM VX` and CME crypto (`CTM BTC`) |
+| `MAP ships` / `CHOKE` | Ships, ports, energy and airports on one map, and chokepoint transits as chart series ([guide](docs/world-map.md)) |
 | `PF` | Portfolios and watchlists |
 | `HELP` | Commands and keyboard shortcuts |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gloomberb",
-  "version": "0.16.1",
+  "version": "0.16.3",
   "packageManager": "bun@1.3.11",
   "description": "Market research and portfolio tracker for the terminal",
   "module": "src/public/index.ts",
@@ -66,6 +66,7 @@
     "plugins:manifest:check": "bun run scripts/generate-plugin-manifest.ts --check",
     "plugins:registry:check": "bun run scripts/check-registry-plugins.ts",
     "web:proxy-hosts": "bun run scripts/generate-web-proxy-hosts.ts",
+    "map:data": "bun run scripts/generate-world-map-data.ts",
     "web:proxy-hosts:check": "bun run scripts/generate-web-proxy-hosts.ts --check",
     "typecheck": "bun run typecheck:opentui && bun run typecheck:dom && bun run typecheck:cloudflare && bun run typecheck:scripts && bun run typecheck:plugin-tests",
     "typecheck:opentui": "tsc --project tsconfig.opentui.json",

package/src/api-client/beneficial-owners.ts

@@ -0,0 +1,92 @@
+/**
+ * Schedule 13D and 13G beneficial ownership reports about one issuer, as
+ * `GET /cloud/sec/beneficial-owners` returns them. Percentages are percent
+ * points (7.3 means 7.3% of the class) and dates are `YYYY-MM-DD`.
+ */
+
+type BeneficialOwnerKind = "13D" | "13G";
+/**
+ * What the filer's latest report says it holds: `below-threshold` is a
+ * reported stake under 5% (still a stake, no longer reportable), `exited` a
+ * report of zero shares or 0%.
+ */
+export type BeneficialOwnerStatus = "holder" | "below-threshold" | "exited";
+/** Which reports to list; the route takes the kind in capitals. */
+export type BeneficialOwnersForm = "all" | BeneficialOwnerKind;
+
+export interface BeneficialOwnerReportingPerson {
+  name: string;
+  cik: string | null;
+  percentOfClass: number | null;
+  shares: number | null;
+}
+
+/**
+ * One report: the latest per filer in `owners`, every report in `filings`.
+ * The previous-report fields and `status` come only with `owners`.
+ */
+export interface BeneficialOwnerFiling {
+  filerCik: string | null;
+  filerName: string;
+  /** The EDGAR form type as filed, such as `SCHEDULE 13G/A`. */
+  form: string;
+  kind: BeneficialOwnerKind;
+  amendment: boolean;
+  amendmentNo: number | null;
+  percentOfClass: number | null;
+  shares: number | null;
+  classTitle: string | null;
+  cusip: string | null;
+  eventDate: string | null;
+  filingDate: string;
+  accessionNumber: string;
+  filingUrl: string;
+  /** The same filer's percentage in its report before this one. */
+  previousPercent?: number | null;
+  previousFilingDate?: string | null;
+  status?: BeneficialOwnerStatus;
+  /**
+   * Only with `owners`: a filing the route could not read may be this filer's
+   * newer report or its real previous one, so the row and its change may be off.
+   */
+  provisional?: boolean;
+  /** `text` and `index` reports could not be read in full; their missing numbers stay null. */
+  source: "xml" | "text" | "index";
+  reportingPersons: BeneficialOwnerReportingPerson[];
+}
+
+export interface BeneficialOwnersCoverage {
+  from: string | null;
+  /** Reports listed for the issuer in the window. */
+  filings: number;
+  /** Reports whose cover page was read. */
+  parsed: number;
+  /** Reports known only from the EDGAR index: listed, with their figures missing. */
+  unparsed: number;
+  /** Reports that could not be read this time and are left out until a later request. */
+  unavailable?: number;
+  /** Every report in the window was read; when false the owners are provisional. */
+  complete?: boolean;
+}
+
+export interface BeneficialOwnersPayload {
+  ticker: string;
+  cik: string;
+  companyName: string;
+  /** When the server assembled the list, an ISO time. */
+  asOf: string | null;
+  owners: BeneficialOwnerFiling[];
+  /** Only when the request asked for the history. Newest first. */
+  filings?: BeneficialOwnerFiling[];
+  hasMore: boolean;
+  nextOffset: number | null;
+  coverage: BeneficialOwnersCoverage | null;
+}
+
+export interface CloudBeneficialOwnersParams {
+  ticker: string;
+  form?: BeneficialOwnersForm;
+  history?: boolean;
+  limit?: number;
+  offset?: number;
+}

package/src/api-client/data.ts

@@ -30,6 +30,7 @@ import type { MoneyMarketsPayload } from "./money-markets";
 import type { CloudCurveId, CloudCurveView, CloudWorldCurves } from "./yield-curves";
 import type { CdxBoardPayload, CloudCreditBoardParams, SovrBoardPayload } from "./credit-boards";
 import type { ShortVolumePayload, ShortVolumeScope } from "./short-volume";
+import type { BeneficialOwnersPayload, CloudBeneficialOwnersParams } from "./beneficial-owners";
 import type { SocialMentionDayPosts, SocialMentionsPayload, SocialMentionsRange } from "./social-mentions";
 import type { FuturesCurveAsOfPayload, FuturesCurvePayload } from "./futures-curve";
 import type { CotBoardPayload, CotContractPayload, CotFamily, CotClass } from "./cot";
@@ -37,6 +38,7 @@ import type { DoeBoardPayload } from "./doe";
 import type { GpuBoardPayload, GpuEventsPayload, GpuHistoryPayload, GpuHistoryQuery } from "./gpu";
 import type { CpiBoardPayload } from "./cpi";
 import type { TapeSnapshot } from "./tape";
+import { signalWithTimeout } from "../utils/async-deadline";
 import type { ExchangeRateSnapshot } from "../types/exchange-rate";
 import type { RatePathPayload } from "./rates";
 import type { EarningsCalendarPayload, EarningsCalendarQuery, EarningsHistoryPayload } from "./earnings";
@@ -70,6 +72,7 @@ import {
   cloudProxyStatementsPath,
   cloudExchangeRatePath,
   cloudSec13FPath,
+  cloudSecBeneficialOwnersPath,
   cloudSecFilingContentPath,
   cloudSecFilingDocumentsPath,
   cloudSecFilingsPath,
@@ -434,6 +437,11 @@ export class CloudDataApi {
     return this.request<CotContractPayload>(`/cloud/cot/contracts/${encodeURIComponent(code)}?${new URLSearchParams({ report })}`);
   }
 
+  /** Geo layers (the map's layers, entities and series); one prefix-scoped method, like EQS. */
+  geo<T>(path: string, init?: RequestInit): Promise<T> {
+    return this.request<T>(`/cloud/geo/${path}`, init);
+  }
+
   /** Credit-document paths stay with their pane; keep the shared client small. */
   creditDocuments<T>(path: string): Promise<T> {
     return this.request<T>(`/cloud/credit-documents/${path}`);
@@ -572,7 +580,7 @@ export class CloudDataApi {
   }
 
   async getCloudTape(symbol: string, exchange: string, signal?: AbortSignal): Promise<TapeSnapshot> {
-    return this.request<TapeSnapshot>(`/cloud/tape/${encodeURIComponent(symbol)}?exchange=${encodeURIComponent(exchange)}`, { signal: signal ?? AbortSignal.timeout(30_000) });
+    return this.request<TapeSnapshot>(`/cloud/tape/${encodeURIComponent(symbol)}?exchange=${encodeURIComponent(exchange)}`, { signal: signalWithTimeout(signal, 30_000) });
   }
 
   async getCloudYieldCurve(): Promise<CloudYieldPointPayload[]> {
@@ -628,29 +636,29 @@ export class CloudDataApi {
     }
     const text = query.toString();
     const suffix = text ? `?${text}` : "";
-    return this.request<MnaDealsPayload>(`/cloud/mna/deals${suffix}`, { signal: options?.signal ?? AbortSignal.timeout(30_000) });
+    return this.request<MnaDealsPayload>(`/cloud/mna/deals${suffix}`, { signal: signalWithTimeout(options?.signal, 30_000) });
   }
 
   async getCloudMnaDeal(id: string, options?: { signal?: AbortSignal }): Promise<MnaDealPayload> {
-    return this.request<MnaDealPayload>(`/cloud/mna/deals/${encodeURIComponent(id)}`, { signal: options?.signal ?? AbortSignal.timeout(30_000) });
+    return this.request<MnaDealPayload>(`/cloud/mna/deals/${encodeURIComponent(id)}`, { signal: signalWithTimeout(options?.signal, 30_000) });
   }
 
   // Public records about companies in difficulty. The answers are unchecked
   // JSON: the distress tab's parsers validate them before anything is drawn.
   async getPublicDistressFilings(params: DistressFilingsParams, options?: { signal?: AbortSignal }): Promise<unknown> {
-    return this.request<unknown>(`/public/events${distressQuery(params)}`, { signal: options?.signal ?? AbortSignal.timeout(30_000) });
+    return this.request<unknown>(`/public/events${distressQuery(params)}`, { signal: signalWithTimeout(options?.signal, 30_000) });
   }
 
   async getPublicGoingConcern(params: GoingConcernParams = {}, options?: { signal?: AbortSignal }): Promise<unknown> {
-    return this.request<unknown>(`/public/going-concern${distressQuery(params)}`, { signal: options?.signal ?? AbortSignal.timeout(30_000) });
+    return this.request<unknown>(`/public/going-concern${distressQuery(params)}`, { signal: signalWithTimeout(options?.signal, 30_000) });
   }
 
   async getPublicDistressDesignations(params: DistressDesignationsParams = {}, options?: { signal?: AbortSignal }): Promise<unknown> {
-    return this.request<unknown>(`/public/distress-designations${distressQuery(params)}`, { signal: options?.signal ?? AbortSignal.timeout(30_000) });
+    return this.request<unknown>(`/public/distress-designations${distressQuery(params)}`, { signal: signalWithTimeout(options?.signal, 30_000) });
   }
 
   async getPublicInsolvencyNotices(params: InsolvencyNoticesParams = {}, options?: { signal?: AbortSignal }): Promise<unknown> {
-    return this.request<unknown>(`/public/insolvency-notices${distressQuery(params)}`, { signal: options?.signal ?? AbortSignal.timeout(30_000) });
+    return this.request<unknown>(`/public/insolvency-notices${distressQuery(params)}`, { signal: signalWithTimeout(options?.signal, 30_000) });
   }
 
   async getCloudIpoCalendar(params: IpoCalendarParams = {}, options?: { signal?: AbortSignal }): Promise<IpoCalendarPayload> {
@@ -660,7 +668,7 @@ export class CloudDataApi {
     }
     const text = query.toString();
     const suffix = text ? `?${text}` : "";
-    return this.request<IpoCalendarPayload>(`/cloud/ipo/calendar${suffix}`, { signal: options?.signal ?? AbortSignal.timeout(30_000) });
+    return this.request<IpoCalendarPayload>(`/cloud/ipo/calendar${suffix}`, { signal: signalWithTimeout(options?.signal, 30_000) });
   }
 
   async getCloudShortVolume(symbol: string, scope: ShortVolumeScope = "nms"): Promise<ShortVolumePayload> {
@@ -795,6 +803,16 @@ export class CloudDataApi {
     return this.request<CloudSecFilingsResponse>(cloudSecFilingsPath(params));
   }
 
+  /** Schedule 13D/13G reports about an issuer. Unknown tickers answer 404; no reports is an empty `owners`. */
+  async getCloudSecBeneficialOwners(
+    params: CloudBeneficialOwnersParams,
+    options?: { signal?: AbortSignal },
+  ): Promise<BeneficialOwnersPayload> {
+    return this.request<BeneficialOwnersPayload>(cloudSecBeneficialOwnersPath(params), {
+      signal: options?.signal,
+    });
+  }
+
   async getCloudSecFilingDocuments(
     params: CloudSecFilingParams,
   ): Promise<CloudSecDocumentsResponse> {

package/src/api-client/errors.ts

@@ -12,6 +12,8 @@ export class ApiRequestError extends Error {
     readonly retryAfterMs?: number,
     /** The body's `error` field, e.g. a broker route's "unsupported" or "tool_error". */
     readonly code?: string,
+    /** The rest of a JSON error body, for a route that says more, e.g. which user refused a chat. */
+    readonly details?: Readonly<Record<string, unknown>>,
   ) {
     super(message);
     this.name = "ApiRequestError";
@@ -79,6 +81,16 @@ export function parseApiErrorMessage(body: string): string {
   }
 }
 
+/** A JSON error body as an object, or undefined for any other body. */
+export function parseApiErrorDetails(body: string): Readonly<Record<string, unknown>> | undefined {
+  try {
+    const parsed = JSON.parse(body) as unknown;
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed as Record<string, unknown> : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /** The JSON body's `error` field, which routes that name their failures set to a code. */
 export function parseApiErrorCode(body: string): string | undefined {
   try {

package/src/api-client/geo.ts

@@ -0,0 +1,363 @@
+/**
+ * Geo layers, as GET /cloud/geo/* serves them: anything with a place (a ship,
+ * a port, a pipeline) as map features, an entity table and chart series. The
+ * types mirror the server's wire contract field for field. The app knows only
+ * this contract, so a layer the server adds needs no release.
+ *
+ * Failures carry `{ error, message }`: 404 `not_found`, 400 `invalid_bbox`,
+ * 403 `pro_required`, 429 `geo_rate_limited` with Retry-After, 503
+ * `geo_unavailable`. A layer that cannot serve still answers 200 with an
+ * empty body and its `status` and `statusNote`.
+ */
+type Lon = number;
+type Lat = number;
+
+type GeoGeometry =
+  | { type: "Point"; coordinates: [Lon, Lat] }
+  | { type: "LineString"; coordinates: [Lon, Lat][] }
+  | { type: "MultiLineString"; coordinates: [Lon, Lat][][] }
+  | { type: "Polygon"; coordinates: [Lon, Lat][][] };
+
+export interface GeoTickerLink {
+  symbol: string;
+  exchange?: string;
+  /** How the entity relates to the company. */
+  via: "owner" | "operator" | "route" | "sector";
+  confidence: "reviewed" | "inferred";
+  /** Short, e.g. "Operates the pipeline". */
+  note?: string;
+}
+
+export type GeoPropValue = string | number | boolean | null;
+
+export interface GeoFeature {
+  /** Stable within the layer, e.g. "mmsi:123456789", "iata:JFK", "choke:suez". */
+  id: string;
+  layer: string;
+  entityKind: string;
+  label: string;
+  geometry: GeoGeometry;
+  /** ISO time of the observation; null for static layers. */
+  ts: string | null;
+  /** Flat, display-ready values. */
+  props: Record<string, GeoPropValue>;
+  tickers?: GeoTickerLink[];
+}
+
+/** `percent1` values are percentage points: 12.3 reads 12.3%. */
+export type GeoColumnFormat = "text" | "int" | "decimal1" | "percent1" | "datetime" | "knots" | "km";
+
+export interface GeoColumn {
+  key: string;
+  label: string;
+  align?: "left" | "right";
+  format?: GeoColumnFormat;
+}
+
+export interface GeoSeriesInfo {
+  id: string;
+  name: string;
+  unit: string;
+  frequency: "daily" | "weekly" | "monthly";
+  entityId?: string;
+}
+
+type GeoLayerGroup = "ships" | "air" | "energy" | "ports" | "infrastructure";
+type GeoLayerStatus = "ok" | "partial" | "unavailable";
+
+export interface GeoLayerInfo {
+  id: string;
+  name: string;
+  /** A group the app does not know yet still lists, under its own name. */
+  group: GeoLayerGroup | (string & {});
+  geometry: "point" | "line" | "area";
+  cadence: "live" | "daily" | "static";
+  /** How often a client should re-request features; null for static layers. */
+  refreshSeconds: number | null;
+  asOf: string | null;
+  count: number | null;
+  status: GeoLayerStatus;
+  /** Short plain words, never a source name. */
+  statusNote?: string;
+  access: "free" | "pro";
+  /** The entity table's columns; the first is the label. */
+  columns: GeoColumn[];
+  series: GeoSeriesInfo[];
+  defaultVisible: boolean;
+  /** Below this zoom the client requests nothing. */
+  minZoom?: number;
+}
+
+export interface GeoLayersPayload {
+  layers: GeoLayerInfo[];
+  asOf: string | null;
+}
+
+export interface GeoCluster {
+  id: string;
+  lon: Lon;
+  lat: Lat;
+  count: number;
+  kinds?: Record<string, number>;
+}
+
+/**
+ * A clustering answer has no features: everything is in `clusters`. Closer
+ * in, a capped answer keeps the top features by rank and sets `truncated`.
+ */
+export interface GeoFeaturesPayload {
+  layer: string;
+  asOf: string | null;
+  features: GeoFeature[];
+  total: number;
+  truncated: boolean;
+  clusters?: GeoCluster[];
+  /** Present when the layer cannot serve right now, with the same words as the catalog. */
+  status?: GeoLayerStatus;
+  statusNote?: string;
+}
+
+export interface GeoEntityRow {
+  id: string;
+  label: string;
+  lon: Lon;
+  lat: Lat;
+  props: Record<string, GeoPropValue>;
+  tickers?: GeoTickerLink[];
+}
+
+export interface GeoEntitiesPayload {
+  layer: string;
+  asOf: string | null;
+  columns: GeoColumn[];
+  rows: GeoEntityRow[];
+  total: number;
+  status?: GeoLayerStatus;
+  statusNote?: string;
+}
+
+/** Longitude, latitude and the ISO time the entity was seen there. */
+type GeoTrailPoint = [Lon, Lat, string];
+
+export interface GeoEntityPayload {
+  feature: GeoFeature;
+  detail: Record<string, GeoPropValue>;
+  /** Oldest first. */
+  trail?: GeoTrailPoint[];
+  series?: GeoSeriesInfo[];
+}
+
+/** `alias` is the short form G takes (SUEZ, HORMUZ.TANKER); ids are the server's own. */
+export type GeoSeriesSearchHit = GeoSeriesInfo & { layer: string; alias?: string };
+
+export interface GeoSeriesSearchPayload {
+  series: GeoSeriesSearchHit[];
+}
+
+export interface GeoSeriesPayload {
+  id: string;
+  name: string;
+  unit: string;
+  frequency: GeoSeriesInfo["frequency"];
+  /** [YYYY-MM-DD, value], oldest first. */
+  points: [string, number][];
+  asOf: string | null;
+}
+
+/** West, south, east, north in degrees. */
+export type GeoBbox = [number, number, number, number];
+
+/** A request under /cloud/geo/, through the shared Cloud client (`apiClient.geo`). */
+export type GeoRequest = <T>(path: string, init?: RequestInit) => Promise<T>;
+
+/** The server's default cap on one features answer; above it a point layer answers clusters. */
+export const GEO_FEATURE_LIMIT = 1500;
+const GEO_FEATURE_LIMIT_MAX = 5000;
+/** Live layers a client may keep refreshing at once. */
+export const GEO_MAX_LIVE_LAYERS = 2;
+const CATALOG_TTL_MS = 5 * 60_000;
+/** A server without geo layers is asked again only after this long. */
+const ABSENT_TTL_MS = 10 * 60_000;
+
+function query(params: Record<string, string | number | undefined | null>): string {
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined || value === null || value === "") continue;
+    search.set(key, String(value));
+  }
+  // Commas stay literal (bbox=w,s,e,n), as the contract writes them and caches key them.
+  const text = search.toString().replaceAll("%2C", ",");
+  return text ? `?${text}` : "";
+}
+
+function segment(value: string): string {
+  return encodeURIComponent(value);
+}
+
+function bboxParam(bbox: GeoBbox | undefined): string | undefined {
+  return bbox ? bbox.map((value) => Number(value.toFixed(3))).join(",") : undefined;
+}
+
+export interface GeoFeaturesQuery {
+  bbox?: GeoBbox;
+  zoom?: number;
+  limit?: number;
+}
+
+export function getGeoFeatures(
+  request: GeoRequest,
+  layerId: string,
+  options: GeoFeaturesQuery = {},
+  signal?: AbortSignal,
+): Promise<GeoFeaturesPayload> {
+  const limit = Math.max(1, Math.min(options.limit ?? GEO_FEATURE_LIMIT, GEO_FEATURE_LIMIT_MAX));
+  return request<GeoFeaturesPayload>(
+    `layers/${segment(layerId)}/features${query({ bbox: bboxParam(options.bbox), zoom: options.zoom, limit })}`,
+    signal ? { signal } : undefined,
+  );
+}
+
+export interface GeoEntitiesQuery {
+  q?: string;
+  sort?: string;
+  dir?: "asc" | "desc";
+  limit?: number;
+  offset?: number;
+  bbox?: GeoBbox;
+}
+
+export function getGeoEntities(
+  request: GeoRequest,
+  layerId: string,
+  options: GeoEntitiesQuery = {},
+  signal?: AbortSignal,
+): Promise<GeoEntitiesPayload> {
+  return request<GeoEntitiesPayload>(
+    `layers/${segment(layerId)}/entities${query({
+      q: options.q?.trim(),
+      sort: options.sort,
+      dir: options.sort ? options.dir : undefined,
+      limit: options.limit,
+      offset: options.offset,
+      bbox: bboxParam(options.bbox),
+    })}`,
+    signal ? { signal } : undefined,
+  );
+}
+
+export function getGeoEntity(
+  request: GeoRequest,
+  layerId: string,
+  entityId: string,
+  signal?: AbortSignal,
+): Promise<GeoEntityPayload> {
+  return request<GeoEntityPayload>(`entities/${segment(layerId)}/${segment(entityId)}`, signal ? { signal } : undefined);
+}
+
+export function searchGeoSeries(request: GeoRequest, q: string, signal?: AbortSignal): Promise<GeoSeriesSearchPayload> {
+  return request<GeoSeriesSearchPayload>(`series${query({ q: q.trim() })}`, signal ? { signal } : undefined);
+}
+
+export function getGeoSeries(
+  request: GeoRequest,
+  seriesId: string,
+  range: { from?: string; to?: string } = {},
+  signal?: AbortSignal,
+): Promise<GeoSeriesPayload> {
+  return request<GeoSeriesPayload>(`series/${segment(seriesId)}${query(range)}`, signal ? { signal } : undefined);
+}
+
+/**
+ * Finds a series by id or short alias (SUEZ). Exact matches win over a series
+ * whose name merely contains the text.
+ */
+export async function resolveGeoSeries(
+  request: GeoRequest,
+  token: string,
+  signal?: AbortSignal,
+): Promise<GeoSeriesSearchHit | null> {
+  const needle = token.trim().toLowerCase();
+  if (!needle) return null;
+  const { series } = await searchGeoSeries(request, token, signal);
+  return series.find((hit) => hit.id.toLowerCase() === needle)
+    ?? series.find((hit) => hit.alias?.toLowerCase() === needle)
+    ?? null;
+}
+
+interface CatalogEntry {
+  at: number;
+  payload: GeoLayersPayload | null;
+}
+
+let catalogEntry: CatalogEntry | null = null;
+let catalogInFlight: Promise<GeoLayersPayload | null> | null = null;
+
+function validLayer(value: unknown): value is GeoLayerInfo {
+  if (!value || typeof value !== "object") return false;
+  const layer = value as Partial<GeoLayerInfo>;
+  return typeof layer.id === "string" && !!layer.id && typeof layer.name === "string"
+    && (layer.geometry === "point" || layer.geometry === "line" || layer.geometry === "area")
+    && Array.isArray(layer.columns);
+}
+
+function normalizeCatalog(payload: unknown): GeoLayersPayload | null {
+  if (!payload || typeof payload !== "object" || !Array.isArray((payload as GeoLayersPayload).layers)) return null;
+  const raw = payload as GeoLayersPayload;
+  const layers = raw.layers.filter(validLayer).map((layer) => ({
+    ...layer,
+    series: Array.isArray(layer.series) ? layer.series : [],
+    refreshSeconds: typeof layer.refreshSeconds === "number" && layer.refreshSeconds > 0 ? layer.refreshSeconds : null,
+  }));
+  return layers.length ? { layers, asOf: raw.asOf ?? null } : null;
+}
+
+/**
+ * The layer catalog, or null when this server has no geo layers. A 404, a
+ * failed request or an empty answer all read as "no layers", so the map stays
+ * the venue map it was, without errors. Answers are kept for a few minutes.
+ */
+export async function loadGeoCatalog(
+  request: GeoRequest,
+  options: { force?: boolean; signal?: AbortSignal; now?: number } = {},
+): Promise<GeoLayersPayload | null> {
+  const now = options.now ?? Date.now();
+  if (!options.force && catalogEntry) {
+    const ttl = catalogEntry.payload ? CATALOG_TTL_MS : ABSENT_TTL_MS;
+    if (now - catalogEntry.at < ttl) return catalogEntry.payload;
+  }
+  if (!catalogInFlight) {
+    catalogInFlight = request<unknown>("layers")
+      .then(normalizeCatalog)
+      // A missing route or a refusal is an answer; a network blip is too, for a while.
+      .catch(() => null)
+      .then((payload) => {
+        catalogEntry = { at: options.now ?? Date.now(), payload };
+        return payload;
+      })
+      .finally(() => {
+        catalogInFlight = null;
+      });
+  }
+  const pending = catalogInFlight;
+  if (!options.signal) return pending;
+  return new Promise((resolve, reject) => {
+    const abort = () => reject(options.signal!.reason ?? new DOMException("Aborted", "AbortError"));
+    if (options.signal!.aborted) return abort();
+    options.signal!.addEventListener("abort", abort, { once: true });
+    void pending.then((value) => {
+      options.signal!.removeEventListener("abort", abort);
+      resolve(value);
+    });
+  });
+}
+
+/** The last catalog answer without asking the server, for synchronous readers such as pane settings. */
+export function peekGeoCatalog(): GeoLayersPayload | null {
+  return catalogEntry?.payload ?? null;
+}
+
+/** Test seam: forget what the server answered. */
+export function resetGeoCatalogCache(): void {
+  catalogEntry = null;
+  catalogInFlight = null;
+}

package/src/api-client/index.ts

@@ -768,6 +768,7 @@ class GloomApiClient {
   getCloudCotBoard = this.data.getCloudCotBoard.bind(this.data);
   getCloudCotContract = this.data.getCloudCotContract.bind(this.data);
   creditDocuments = this.data.creditDocuments.bind(this.data);
+  geo = this.data.geo.bind(this.data);
   getCloudHiring = this.data.getCloudHiring.bind(this.data);
   getCloudAppRankHistory = this.data.getCloudAppRankHistory.bind(this.data);
   getCloudAppAttention = this.data.getCloudAppAttention.bind(this.data);
@@ -819,6 +820,7 @@ class GloomApiClient {
   getRiskReports = this.data.getRiskReports.bind(this.data);
   getRiskReport = this.data.getRiskReport.bind(this.data);
   getCloudSecFilings = this.data.getCloudSecFilings.bind(this.data);
+  getCloudSecBeneficialOwners = this.data.getCloudSecBeneficialOwners.bind(this.data);
   getCloudSecFilingDocuments = this.data.getCloudSecFilingDocuments.bind(this.data);
   getCloudSecFilingContent = this.data.getCloudSecFilingContent.bind(this.data);
   getCloudSec13F = this.data.getCloudSec13F.bind(this.data);

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

@@ -46,6 +46,12 @@ export interface MarketHeatmapAsset {
   industry: string | null;
   marketState: string | null;
   source: MarketHeatmapSource;
+  /**
+   * The move of the last completed regular session, which `price`, `change`
+   * and `changePercent` then are. Null while the regular session trades, and
+   * for a name without that session's close.
+   */
+  regularChangePercent?: number | null;
 }
 
 export interface MarketHeatmapResult {
@@ -53,6 +59,10 @@ export interface MarketHeatmapResult {
   universe: MarketHeatmapUniverseId;
   source: MarketHeatmapSource;
   fetchedAt: number;
+  /** The US market session the snapshot describes; null when the server cannot tell. */
+  session?: "REGULAR" | "PRE" | "POST" | "CLOSED" | null;
+  /** The completed regular session every stored tile describes outside the regular session, as a New York date; null while it trades. */
+  regularSessionDate?: string | null;
   assets: MarketHeatmapAsset[];
 }