gloomberb 0.15.8 → 0.16.0

package/src/api-client/data.ts

@@ -1,8 +1,27 @@
+import type { AttentionPayload, AttentionWindow } from "./attention";
+import type { HiringBoard, HiringPayload } from "./hiring";
+import type { AppAttentionFilter, AppAttentionPayload, AppRankPayload } from "./app-attention";
+import type { CatalystResponse, CatalystDetail, CatalystFilters, CatalystStatus, CatalystChanges } from "./catalysts";
+import type { KpisPayload, GuidancePayload, KpiQueryOptions } from "./company-kpis";
+import { companyDisclosurePath } from "./company-kpis";
+import type { PowerBoard, PowerDetail, PowerFilter, PowerHistory } from "./power";
+import type { PerpBoardPayload, PerpHistoryPayload, PerpRankingsPayload, PerpBoardQuery, PerpHistoryQuery, PerpMarketPayload } from "./perps";
+import type { ExposureRequest, ExposurePayload, ExposureScenario } from "./exposure";
+import type { SupplyChainPayload, SupplyOptions } from "./supply-chain";
+import { supplyGraphQuery, type GraphOptions, type GraphPayload } from "./supply-chain-graph";
+import type { AwardDetailPayload, AwardFilter, AwardsPayload } from "./awards";
 import type { EarningsEvent } from "../types/data-provider";
 import type { MarketDividendsPayload, MarketHeatmapResult, MarketHeatmapUniverseId, MarketMoversPayload } from "./market-discovery";
 import type { DebtMaturitiesPayload } from "./debt-maturities";
 import type { RevenueBreakdownPayload, RevenueBreakdownView } from "./revenue-breakdown";
 import type { MnaDealPayload, MnaDealsParams, MnaDealsPayload } from "./mna";
+import {
+  distressQuery,
+  type DistressDesignationsParams,
+  type DistressFilingsParams,
+  type GoingConcernParams,
+  type InsolvencyNoticesParams,
+} from "./distress";
 import type { IpoCalendarParams, IpoCalendarPayload } from "./ipo";
 import type { CryptoMarketsPayload } from "./crypto-markets";
 import type { CentralBankRatesPayload } from "./central-bank-rates";
@@ -15,6 +34,8 @@ import type { SocialMentionDayPosts, SocialMentionsPayload, SocialMentionsRange
 import type { FuturesCurveAsOfPayload, FuturesCurvePayload } from "./futures-curve";
 import type { CotBoardPayload, CotContractPayload, CotFamily, CotClass } from "./cot";
 import type { DoeBoardPayload } from "./doe";
+import type { GpuBoardPayload, GpuEventsPayload, GpuHistoryPayload, GpuHistoryQuery } from "./gpu";
+import type { CpiBoardPayload } from "./cpi";
 import type { TapeSnapshot } from "./tape";
 import type { ExchangeRateSnapshot } from "../types/exchange-rate";
 import type { RatePathPayload } from "./rates";
@@ -146,10 +167,12 @@ export class CloudDataApi {
     path: string,
     targets: CloudMarketBatchTarget[],
     mode: "cache-first" | "refresh",
+    signal?: AbortSignal,
   ): Promise<CloudMarketResponse<CloudMarketBatchPayload<T>>> {
     return this.request<CloudMarketResponse<CloudMarketBatchPayload<T>>>(path, {
       method: "POST",
       body: JSON.stringify({ targets, mode }),
+      ...(signal ? { signal } : {}),
     });
   }
 
@@ -158,6 +181,14 @@ export class CloudDataApi {
     return this.request<T>(`/cloud/equity-screener/${path}`, init);
   }
 
+  getCloudThemes() {
+    return this.request<import("./themes").ThemesPayload>("/cloud/themes");
+  }
+
+  getCloudThemeMembers(id: string) {
+    return this.request<import("./themes").ThemeMembersPayload>(`/cloud/themes/${encodeURIComponent(id)}`);
+  }
+
   /** Stored implied volatility (HIVG, VCA, OVDV dates); one prefix-scoped method, like EQS. */
   impliedVolatility<T>(path: string, init?: RequestInit) {
     return this.request<T>(`/cloud/iv/${path}`, init);
@@ -204,8 +235,9 @@ export class CloudDataApi {
   async getCloudQuotesBatch(
     targets: CloudMarketBatchTarget[],
     mode: "cache-first" | "refresh" = "cache-first",
+    options: { signal?: AbortSignal } = {},
   ): Promise<CloudMarketResponse<CloudMarketBatchPayload<CloudQuotePayload>>> {
-    return this.postMarketBatch("/market/quotes/batch", targets, mode);
+    return this.postMarketBatch("/market/quotes/batch", targets, mode, options.signal);
   }
 
   async getCloudWorldVenues(): Promise<
@@ -324,9 +356,11 @@ export class CloudDataApi {
     symbol: string,
     exchange: string,
     params: CloudHistoryParams = {},
+    options: { signal?: AbortSignal } = {},
   ): Promise<CloudMarketResponse<CloudPricePointPayload[]>> {
     return this.request<CloudMarketResponse<CloudPricePointPayload[]>>(
       cloudHistoryPath(symbol, exchange, params),
+      options.signal ? { signal: options.signal } : undefined,
     );
   }
 
@@ -368,9 +402,11 @@ export class CloudDataApi {
   async getCloudFredSeries(
     seriesId: string,
     params: CloudFredSeriesParams = {},
+    options: { signal?: AbortSignal } = {},
   ): Promise<CloudFredSeriesPayload> {
     return this.request<CloudFredSeriesPayload>(
       cloudFredSeriesPath(seriesId, params),
+      options.signal ? { signal: options.signal } : undefined,
     );
   }
 
@@ -386,10 +422,140 @@ export class CloudDataApi {
     return this.request<CotContractPayload>(`/cloud/cot/contracts/${encodeURIComponent(code)}?${new URLSearchParams({ report })}`);
   }
 
+  /** 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}`);
+  }
+
+  async getCloudHiring(symbol?: string, query: { limit?: number; offset?: number } = {}, signal?: AbortSignal): Promise<HiringBoard | HiringPayload> {
+    const params = new URLSearchParams({ limit: String(query.limit ?? 100), offset: String(query.offset ?? 0) });
+    return this.request<HiringBoard | HiringPayload>(symbol ? `/cloud/hiring/${encodeURIComponent(symbol)}` : `/cloud/hiring?${params}`, { signal });
+  }
+
+  async getCloudAppRankHistory(store: "app-store" | "google-play", appId: string, query: AppAttentionFilter = {}, signal?: AbortSignal): Promise<AppRankPayload> {
+    const params = new URLSearchParams(Object.entries(query).filter(([, value]) => value !== undefined).map(([key, value]) => [key, String(value)]));
+    return this.request<AppRankPayload>(`/cloud/app-attention/app/${store}/${encodeURIComponent(appId)}?${params}`, { signal });
+  }
+
+  async getCloudAppAttention(query: AppAttentionFilter = {}, signal?: AbortSignal): Promise<AppAttentionPayload> {
+    const { symbol, ...filters } = query;
+    const params = new URLSearchParams(Object.entries(filters).filter(([, value]) => value !== undefined).map(([key, value]) => [key, String(value)]));
+    return this.request<AppAttentionPayload>(`/cloud/app-attention/${symbol ? encodeURIComponent(symbol) : "board"}?${params}`, { signal });
+  }
+
+  async getCloudCatalysts(query: CatalystFilters = {}, signal?: AbortSignal): Promise<CatalystResponse> {
+    const params = new URLSearchParams(Object.entries(query).filter(([, value]) => value !== undefined).map(([key, value]) => [key, String(value)]));
+    const route = query.litigation && query.symbol ? `/cloud/catalysts/litigation/${encodeURIComponent(query.symbol)}` : "/cloud/catalysts";
+    return this.request<CatalystResponse>(`${route}?${params}`, { signal });
+  }
+
+  async getCloudCatalystChanges(query: { since: string; cursor?: string; limit?: number }, signal?: AbortSignal): Promise<CatalystChanges> {
+    const params = new URLSearchParams(Object.entries(query).filter(([, value]) => value !== undefined).map(([key, value]) => [key, String(value)]));
+    return this.request<CatalystChanges>(`/cloud/catalysts/changes?${params}`, { signal });
+  }
+
+  async getCloudCatalystEvent(id: string, signal?: AbortSignal, query: { offset?: number; limit?: number } = {}): Promise<CatalystDetail> {
+    const params = new URLSearchParams(Object.entries(query).filter(([, value]) => value !== undefined).map(([key, value]) => [key, String(value)]));
+    return this.request<CatalystDetail>(`/cloud/catalysts/events/${encodeURIComponent(id)}?${params}`, { signal });
+  }
+
+  async getCloudCatalystStatus(): Promise<CatalystStatus> {
+    return this.request<CatalystStatus>("/cloud/catalysts/status");
+  }
+
+  async getCloudCompanyKpis(symbol: string, options: KpiQueryOptions = {}): Promise<KpisPayload> {
+    return this.request<KpisPayload>(companyDisclosurePath("kpis", symbol, options));
+  }
+
+  async getCloudCompanyGuidance(symbol: string, options: KpiQueryOptions = {}): Promise<GuidancePayload> {
+    return this.request<GuidancePayload>(companyDisclosurePath("guidance", symbol, options));
+  }
+  async getCloudPerpsBoard(query: PerpBoardQuery = {}): Promise<PerpBoardPayload> {
+    return this.request(`/cloud/perps/board?${new URLSearchParams(Object.entries(query).filter(([, value]) => value !== undefined).map(([key, value]) => [key, String(value)]))}`);
+  }
+  async getCloudPerpsHistory(query: PerpHistoryQuery): Promise<PerpHistoryPayload> {
+    return this.request(`/cloud/perps/history?${new URLSearchParams(Object.entries(query).filter(([, value]) => value !== undefined).map(([key, value]) => [key, String(value)]))}`);
+  }
+  async getCloudPerpsRankings(): Promise<PerpRankingsPayload> { return this.request("/cloud/perps/rankings"); }
+  async getCloudPerpsCompare(baseAsset: string): Promise<PerpBoardPayload> { return this.request(`/cloud/perps/compare?${new URLSearchParams({ baseAsset })}`); }
+  async getCloudPerpsEquity(symbol: string): Promise<PerpBoardPayload> { return this.request(`/cloud/perps/equity/${encodeURIComponent(symbol)}`); }
+  async getCloudPerpsMarket(marketId: string): Promise<PerpMarketPayload> { return this.request(`/cloud/perps/market?${new URLSearchParams({ marketId })}`); }
+
+  async analyzeCloudExposure(request: ExposureRequest): Promise<ExposurePayload> {
+    return this.request<ExposurePayload>("/cloud/exposure/analyze", { method: "POST", body: JSON.stringify(request) });
+  }
+
+  async getCloudExposureScenarios(): Promise<{ scenarios: ExposureScenario[] }> {
+    return this.request<{ scenarios: ExposureScenario[] }>("/cloud/exposure/scenarios");
+  }
+
+  async getCloudSupplyChain(symbol: string, options: SupplyOptions = {}): Promise<SupplyChainPayload> {
+    const query = new URLSearchParams();
+    if (options.tiers?.length) query.set("tiers", options.tiers.join(","));
+    if (options.includeLeads) query.set("includeLeads", "1");
+    return this.request<SupplyChainPayload>(`/cloud/supply-chain/${encodeURIComponent(symbol)}${query.size ? `?${query}` : ""}`);
+  }
+
+  getCloudAwards(query: AwardFilter = {}, signal?: AbortSignal): Promise<AwardsPayload> {
+    const params = new URLSearchParams(Object.entries(query).filter(([, value]) => value != null).map(([key, value]) => [key, `${value}`]));
+    return this.request<AwardsPayload>(`/cloud/awards?${params}`, { signal });
+  }
+
+  getCloudAward(id: string, signal?: AbortSignal, revisionsCursor?: string): Promise<AwardDetailPayload> {
+    const query = revisionsCursor ? `?${new URLSearchParams({ revisionsCursor })}` : "";
+    return this.request<AwardDetailPayload>(`/cloud/awards/detail/${encodeURIComponent(id)}${query}`, { signal });
+  }
+
+  async getCloudSupplyGraph(symbol: string, options: Partial<GraphOptions> = {}): Promise<GraphPayload> {
+    return this.request<GraphPayload>(`/cloud/supply-chain/${encodeURIComponent(symbol)}/graph?${supplyGraphQuery(options)}`);
+  }
+
+  async getCloudSupplyPaths(from: string, to: string, options: Partial<GraphOptions> = {}): Promise<GraphPayload> {
+    return this.request<GraphPayload>(`/cloud/supply-chain/paths?from=${encodeURIComponent(from)}&to=${encodeURIComponent(to)}&${supplyGraphQuery(options)}`);
+  }
+
   async getCloudDoeBoard(): Promise<DoeBoardPayload> {
     return this.request<DoeBoardPayload>("/cloud/doe/board");
   }
 
+  async getCloudAttention(window: AttentionWindow = "now", symbol?: string): Promise<AttentionPayload> {
+    const path = symbol ? `/cloud/attention/${encodeURIComponent(symbol)}` : "/cloud/attention";
+    return this.request<AttentionPayload>(`${path}?window=${window}`);
+  }
+
+  async getCloudPowerBoard(query: PowerFilter = {}, signal?: AbortSignal): Promise<PowerBoard> {
+    const params = new URLSearchParams(Object.entries(query).filter(([, value]) => value !== undefined).map(([key, value]) => [key, String(value)]));
+    return this.request<PowerBoard>(`/cloud/power/board?${params}`, { signal });
+  }
+
+  async getCloudPowerHistory(query: PowerFilter = {}): Promise<PowerHistory> {
+    const params = new URLSearchParams(Object.entries(query).filter(([, value]) => value !== undefined).map(([key, value]) => [key, String(value)]));
+    return this.request<PowerHistory>(`/cloud/power/history?${params}`);
+  }
+
+  async getCloudPowerProject(id: string, query: Pick<PowerFilter, "offset" | "limit"> = {}, signal?: AbortSignal): Promise<PowerDetail> {
+    const params = new URLSearchParams(Object.entries(query).filter(([, value]) => value !== undefined).map(([key, value]) => [key, String(value)]));
+    return this.request<PowerDetail>(`/cloud/power/projects/${encodeURIComponent(id)}?${params}`, { signal });
+  }
+
+  async getCloudGpuBoard(): Promise<GpuBoardPayload> {
+    return this.request<GpuBoardPayload>("/cloud/gpu/board");
+  }
+
+  async getCloudGpuHistory(query: GpuHistoryQuery = {}): Promise<GpuHistoryPayload> {
+    const params = new URLSearchParams(Object.entries(query).filter(([, value]) => value !== undefined).map(([key, value]) => [key, String(value)]));
+    return this.request<GpuHistoryPayload>(`/cloud/gpu/history?${params}`);
+  }
+
+  async getCloudGpuEvents(gpuModel?: string): Promise<GpuEventsPayload> {
+    const params = new URLSearchParams({ limit: "1000", ...(gpuModel ? { gpuModel } : {}) });
+    return this.request<GpuEventsPayload>(`/cloud/gpu/events?${params}`);
+  }
+
+  async getCloudCpiBoard(): Promise<CpiBoardPayload> {
+    return this.request<CpiBoardPayload>("/cloud/cpi/board");
+  }
+
   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) });
   }
@@ -454,6 +620,24 @@ export class CloudDataApi {
     return this.request<MnaDealPayload>(`/cloud/mna/deals/${encodeURIComponent(id)}`, { signal: options?.signal ?? AbortSignal.timeout(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) });
+  }
+
+  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) });
+  }
+
+  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) });
+  }
+
+  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) });
+  }
+
   async getCloudIpoCalendar(params: IpoCalendarParams = {}, options?: { signal?: AbortSignal }): Promise<IpoCalendarPayload> {
     const query = new URLSearchParams();
     for (const [key, value] of Object.entries(params)) {
@@ -620,8 +804,8 @@ export class CloudDataApi {
   }
 
   /**
-   * Cross-document full-text search. Pro-gated: unentitled accounts get a 402,
-   * which the caller turns into the access gate rather than an empty result.
+   * Cross-document full-text search, open to every signed-in account; signed
+   * out it answers 401. Only alerts on a saved search need Pro.
    */
   async searchCloudDocuments(
     params: CloudSearchParams,

package/src/api-client/distress.ts

@@ -0,0 +1,164 @@
+/**
+ * Public records about companies in difficulty: US 8-K filings under the
+ * bankruptcy, obligation and listing items, SEC going-concern disclosures,
+ * exchange listing designations and company insolvency notices. Every route
+ * is anonymous; field names follow the server, which serves the last three in
+ * snake case.
+ */
+import type { CloudFilingEventPayload } from "./types";
+
+/** `distress` is Items 1.03 and 2.04; `listing` is Item 3.01. */
+export type DistressFilingKind = "distress" | "listing";
+
+export interface DistressFilingsParams {
+  kind: DistressFilingKind;
+  /** 1 to 200; the route has no offset, so this is the whole list. */
+  limit?: number;
+}
+
+export interface DistressFilingsPayload {
+  events: CloudFilingEventPayload[];
+}
+
+export type GoingConcernVerdict = "doubt_raised" | "doubt_alleviated" | "policy_only" | "unclear";
+
+export interface GoingConcernParams {
+  verdict?: GoingConcernVerdict;
+  limit?: number;
+  offset?: number;
+}
+
+export interface GoingConcernDisclosure {
+  id: string;
+  cik: string;
+  /** Venue-qualified trading symbol (`BMRA:NASDAQ`), null for a filer without one. */
+  ticker: string | null;
+  accession: string;
+  form: string;
+  period_end: string | null;
+  filed_at: string;
+  fact_date: string | null;
+  tag: string;
+  verdict: GoingConcernVerdict;
+  /** Whether the filing frames its assessment over one year; null when it does not say. */
+  within_one_year: boolean | null;
+  source_within_one_year: boolean | null;
+  summary: string;
+  quote: string;
+  text: string;
+  text_truncated: boolean;
+  dataset_month: string;
+  company: { ticker: string; cik: string | null; name: string; shortName: string };
+  filing_url: string;
+}
+
+export interface GoingConcernPayload {
+  disclosures: GoingConcernDisclosure[];
+  hasMore: boolean;
+  limit: number;
+  offset: number;
+}
+
+export type DesignationDateBasis = "designation" | "effective" | "first_observed";
+
+export interface DistressDesignationsParams {
+  kind?: string;
+  exchange?: string;
+  limit?: number;
+  offset?: number;
+}
+
+export interface DistressDesignation {
+  id: string;
+  source: string;
+  region: string;
+  exchange: string;
+  /** Canonical listing key, e.g. `2867:TWSE`. */
+  symbol: string | null;
+  local_code: string;
+  entity_name: string;
+  entity_name_en: string | null;
+  market_segment: string | null;
+  /** `delisted`, `changed_trading_method` or `suspended`. */
+  kind: string;
+  designated_at: string | null;
+  effective_at: string | null;
+  first_seen_at: string;
+  last_seen_at: string;
+  ended_at: string | null;
+  remarks: string;
+  source_url: string;
+  notice_url: string | null;
+  date_basis: DesignationDateBasis;
+}
+
+/** The licence terms a source's rows are published under, reproduced with them. */
+export interface DistressAttribution {
+  source: string;
+  organization: string;
+  dataset: string | null;
+  version: string | null;
+  year: number | null;
+  datasetUrls: string[];
+  licence: string;
+  licenceUrl: string;
+  notice: string;
+}
+
+export interface DistressDesignationsPayload {
+  designations: DistressDesignation[];
+  hasMore: boolean;
+  limit: number;
+  offset: number;
+  attributions: DistressAttribution[];
+}
+
+export interface InsolvencyNoticesParams {
+  country?: string;
+  kind?: string;
+  /** Company name prefix, two characters or more. */
+  name_prefix?: string;
+  limit?: number;
+  offset?: number;
+}
+
+export interface InsolvencyNotice {
+  source: string;
+  country: string;
+  /** SIREN in France, the Companies House number in the UK. */
+  registry_id: string;
+  entity_name: string;
+  symbol: string | null;
+  kind: string;
+  /** The official judgment label (France) or Gazette notice code (UK). */
+  raw_code: string;
+  /** Judgment or procedure date, when the notice states one. */
+  notice_date: string | null;
+  published_date: string;
+  court: string;
+  notice_id: string;
+  notice_url: string;
+  /** `annonce`, `rectificatif` or `annulation`. */
+  notice_type: string;
+  original_notice_id: string | null;
+  /** `active`, `superseded` or `cancelled`. */
+  status: string;
+}
+
+export interface InsolvencyNoticesPayload {
+  notices: InsolvencyNotice[];
+  hasMore: boolean;
+  limit: number;
+  offset: number;
+  attributions: DistressAttribution[];
+}
+
+/** `?a=1&b=2` from the defined, non-empty values; empty when there are none. */
+export function distressQuery(params: object): string {
+  const query = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined && value !== null && value !== "") query.set(key, String(value));
+  }
+  const text = query.toString();
+  return text ? `?${text}` : "";
+}

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

@@ -1,4 +1,7 @@
+/** Cited company disclosures; Pro, omitted by older servers. */
+export const KPI_FIELDS = ["kpiArr", "kpiNrrPercent", "kpiRpo", "kpiCrpo", "kpiSubscribers", "kpiDau", "kpiMau", "kpiGmv", "kpiTakeRatePercent", "kpiSameStoreSalesPercent", "kpiStores", "kpiBacklog", "kpiBookToBill", "kpiNimPercent", "kpiCet1Percent", "kpiCombinedRatioPercent", "kpiOccupancyPercent", "kpiLoadFactorPercent", "guideRevenueChangePercent", "guideEpsChangePercent"] as const;
 export const NUMERIC_FIELDS = [
+  ...KPI_FIELDS,
   "price",
   "changePercent",
   "volume",
@@ -26,6 +29,8 @@ export const NUMERIC_FIELDS = [
   "xPostsVsMedian",
   "wikiViewsPerDay",
   "wikiViewsVsMedian",
+  "attentionResearchUnits",
+  "attentionZScore",
   "return1WPercent",
   "return1MPercent",
   "return3MPercent",
@@ -40,9 +45,14 @@ export const NUMERIC_FIELDS = [
   "analystUpsidePercent",
   "ivRank",
   "ivToHv",
+  "hiringOpenRoles", "hiringNetAddsWeek", "hiringRemotePercent", "hiringZScore",
+  "appAttentionScore", "appRankVelocity7d", "appRatingDrift7d", "appRatingCountGrowth7d",
 ] as const;
+/** Hiring and app attention are optional when connecting to an older server. */
+export const HIRING_APP_FIELDS = ["hiringOpenRoles", "hiringNetAddsWeek", "hiringRemotePercent", "hiringZScore", "appAttentionScore", "appRankVelocity7d", "appRatingDrift7d", "appRatingCountGrowth7d"] as const;
 /** Social attention; a server from before them omits these metrics. */
 export const SOCIAL_FIELDS = ["xPostsPerDay", "xPostsVsMedian", "wikiViewsPerDay", "wikiViewsVsMedian"] as const;
+export const ATTENTION_FIELDS = ["attentionResearchUnits", "attentionZScore"] as const;
 /** Returns, valuation, estimates and options; a server from before them omits these metrics. */
 export const RESEARCH_FIELDS = [
   "return1WPercent", "return1MPercent", "return3MPercent", "returnYtdPercent", "return1YPercent", "fromHigh52WPercent",
@@ -147,6 +157,7 @@ export interface SavedScreen {
   updatedAt: string;
 }
 export interface ScreenFieldDefinition {
+  access?: "pro";
   id: ScreenField;
   label: string;
   kind: "number" | "category";

package/src/api-client/exposure.ts

@@ -0,0 +1,202 @@
+type EvidenceTier = "structured" | "primary" | "secondary" | "imported";
+
+export type ExposureRange = { low: number; high: number }
+export type ExposureBasis =
+  | "revenue"
+  | "cost"
+  | "purchases"
+  | "receivables"
+  | "operating_income"
+  | "interest_expense"
+  | "debt"
+type ExposureShockKind =
+  | "country"
+  | "commodity"
+  | "rate"
+  | "fx"
+  | "tariff"
+  | "supplier"
+  | "customer"
+/** Percentages are percentage points. Weights alone are fractions of NAV. */
+interface ExposureShock {
+  id: string
+  kind: ExposureShockKind
+  /** ISO country/currency code, commodity, or exact entity id/ticker/name. */
+  target: string
+  changePct?: number
+  changeBps?: number
+  /** Optional product restriction, e.g. a country export ban on semiconductors. */
+  products?: string[]
+  /** An explicit user assumption, never represented as a sourced disclosure. */
+  transmission?: {
+    basis: ExposureBasis
+    exposurePct: ExposureRange
+    /** Change in the denominator per unit change in the shock. */
+    factor: ExposureRange
+    direction?: 1 | -1
+  }
+}
+export interface ExposureScenario {
+  id?: string
+  label: string
+  shocks: ExposureShock[]
+}
+export interface ExposureHolding {
+  symbol: string
+  /** Signed fraction of NAV; 0.25 = 25%, -0.1 = 10% short. */
+  weight: number
+}
+export interface ExposureRequest {
+  holdings: ExposureHolding[]
+  scenario: ExposureScenario
+  depth?: number
+  /** Cash weight in NAV fractions, never used to renormalize holding weights. */
+  cashWeight?: number
+}
+export interface ExposureEvidence {
+  id: string
+  source: string
+  tier: EvidenceTier | "profile" | "user"
+  url: string | null
+  quote: string | null
+  asOf: string | null
+  period: string | null
+  units: string
+  currency: string | null
+  confidence: number | null
+  /** Corrections must supersede explicitly; adapters return the current revision. */
+  revision?: string | null
+}
+export interface ExposureExtensionObservation {
+  id: string
+  label: string
+  kind: "kpi" | "credit" | "guidance"
+  value: number | null
+  units: string
+  evidence: ExposureEvidence[]
+  currency?: string | null
+  period?: string | null
+  asOf?: string | null
+  basis?: string
+  dimensions?: Record<string, string>
+  qualifier?: string
+  range?: { low: number | null; high: number | null }
+  valueText?: string
+  status?: string
+  notes?: string[]
+  sensitivity?: {
+    kind: ExposureShockKind
+    target: string
+    basis: ExposureBasis
+    period: string
+    exposurePct: ExposureRange
+    factor: ExposureRange
+    direction: 1 | -1
+  } | null
+}
+interface ExposurePathHop {
+  from: { id: string; name: string; symbol: string | null; country: string | null }
+  to: { id: string; name: string; symbol: string | null; country: string | null }
+  evidence: ExposureEvidence[]
+  pct: number | null
+  basis: ExposureBasis | null
+  denominatorEntityId: string | null
+}
+export interface ExposureComponent {
+  id: string
+  shockId: string
+  label: string
+  channel: "geography" | "product" | "supplier" | "customer" | "profile" | "assumption" | "extension"
+  order: number
+  basis: ExposureBasis | null
+  period: string | null
+  classification: "disclosed" | "estimated" | "unknown"
+  exposurePct: ExposureRange | null
+  /** Estimated operating-denominator change; never a stock-return forecast. */
+  impactPct: ExposureRange | null
+  proportionalEstimatePct?: number | null
+  evidence: ExposureEvidence[]
+  path: ExposurePathHop[]
+  unknowns: string[]
+  /** Used only internally for validated disjoint revenue partitions. */
+  partition?: string | null
+}
+interface ExposureMeasure {
+  shockId: string
+  basis: ExposureBasis
+  period: string
+  exposurePct: ExposureRange
+  impactPct: ExposureRange | null
+  classification: "disclosed" | "estimated"
+  componentIds: string[]
+  /** True when an unquantified matching relationship prevents a complete bound. */
+  incomplete: boolean
+}
+interface ExposureHoldingResult {
+  symbol: string
+  name: string | null
+  weight: number
+  status: "quantified" | "partial" | "unknown"
+  measures: ExposureMeasure[]
+  components: ExposureComponent[]
+  extensions: ExposureExtensionObservation[]
+  unknowns: string[]
+  coverage: {
+    revenueRows: number
+    graphNodes: number
+    graphLinks: number
+    matchedPaths: number
+    quantifiedComponents: number
+    unknownComponents: number
+    graphComplete: boolean
+    oldestEvidenceAt: string | null
+    latestEvidenceAt: string | null
+  }
+}
+interface ExposurePortfolioMeasure {
+  shockId: string
+  basis: ExposureBasis
+  period: string
+  /** Holding-weighted operating exposure, in NAV-weighted percentage points. */
+  signedExposurePct: ExposureRange
+  grossExposurePct: ExposureRange
+  impactPct: ExposureRange | null
+  coveredGrossWeight: number
+  unknownGrossWeight: number
+  symbols: string[]
+}
+interface ExposureConcentration {
+  kind: "country" | "supplier" | "customer"
+  key: string
+  label: string
+  basis: ExposureBasis | null
+  period: string | null
+  grossExposurePct: ExposureRange | null
+  signedExposurePct: ExposureRange | null
+  grossHoldingWeight: number
+  symbols: string[]
+  evidence: ExposureEvidence[]
+  incomplete: boolean
+}
+export interface ExposurePayload {
+  version: 1
+  scenario: ExposureScenario
+  evaluatedAt: string
+  access: "full" | "preview"
+  depth: number
+  requestedHoldings: number
+  lockedHoldings: number
+  holdings: ExposureHoldingResult[]
+  portfolio: {
+    grossWeight: number
+    netWeight: number
+    cashWeight: number | null
+    /** 1 - net holding weights - explicit cash, financing/residual if not zero. */
+    residualWeight: number
+    measures: ExposurePortfolioMeasure[]
+    concentrations: ExposureConcentration[]
+    unknownGrossWeight: number
+  }
+  unknowns: string[]
+  methodology: string[]
+}