gloomberb 0.16.3 → 0.16.5

package/src/account/upgrade-tickers.ts

@@ -0,0 +1,124 @@
+/**
+ * The tickers an upgrade surface may name for the `upgrade_personalized`
+ * experiment: the account's own holdings, or with none, the tickers it chose
+ * to watch, read from this device's portfolios and watchlists. They stay on
+ * the device; nothing here is sent anywhere.
+ */
+import { tf } from "../i18n";
+import type { TickerFinancials } from "../types/financials";
+import type { TickerRecord, Watchlist } from "../types/ticker";
+import { isUsListingExchange } from "../utils/exchanges";
+import { getPortfolioPositionValue } from "../portfolio/position-value";
+import { STARTER_SYMBOLS } from "../tickers/starter-symbols";
+
+const UPGRADE_TICKER_LIMIT = 3;
+/** One to five letters and an optional class letter: BRK.B, never BTC-USD, ES=F, ^GSPC, SHOP.TO or 7203. */
+const PLAIN_TICKER = /^[A-Z]{1,5}(?:\.[A-Z])?$/;
+/** Every candidate is a US listing, so values compare in dollars without a rate. */
+const DOLLARS = new Map([["USD", 1]]);
+/** Stocks and exchange-traded funds; not mutual funds, which have no intraday quote. */
+const LISTED_TYPES = new Set(["", "STK", "EQUITY", "COMMONSTOCK", "ADR", "DEPOSITARYRECEIPT", "ETF", "ETP", "CEF", "CLOSEDEND", "CLOSEDENDFUND"]);
+
+/** A stock or fund on a US listing exchange (not OTC), priced in dollars. */
+function isUsListedStockOrFund(ticker: TickerRecord): boolean {
+  const contract = ticker.metadata.broker_contracts?.[0];
+  const type = (contract?.secType ?? ticker.metadata.assetCategory ?? "").trim().toUpperCase().replace(/[\s_-]/g, "");
+  const currency = (contract?.currency ?? ticker.metadata.currency ?? "").trim().toUpperCase();
+  return LISTED_TYPES.has(type)
+    && (currency === "USD" || currency === "")
+    && [contract?.primaryExchange, contract?.exchange, ticker.metadata.exchange].some((exchange) => isUsListingExchange(exchange));
+}
+
+/**
+ * The symbol when it is a plain US stock or fund someone can get a real-time
+ * quote for: not cash, an option, a future, a crypto pair or a foreign listing.
+ */
+function plainSymbol(ticker: TickerRecord): string | null {
+  const symbol = ticker.metadata.ticker.trim().toUpperCase();
+  if (!PLAIN_TICKER.test(symbol) || !isUsListedStockOrFund(ticker)) return null;
+  // A contract multiplier means the holding is an option or a future on it.
+  if (ticker.metadata.positions.some((position) => (position.multiplier ?? 1) !== 1)) return null;
+  return symbol;
+}
+
+interface Holding {
+  /** The market value is known on this device: a quote it already has, or the broker's own value. */
+  priced: boolean;
+  value: number;
+}
+
+/**
+ * Gross market value of the shares held, valued like the portfolio pane from
+ * what the device already has; null when none are held. Without a quote or a
+ * broker value it falls back to what was paid, and says so with `priced`.
+ */
+function heldValue(ticker: TickerRecord, financials: TickerFinancials | undefined): Holding | null {
+  const held = ticker.metadata.positions.filter((position) => position.shares !== 0);
+  if (held.length === 0) return null;
+  const value = getPortfolioPositionValue({
+    ticker,
+    financials: financials ?? null,
+    portfolioId: null,
+    baseCurrency: "USD",
+    exchangeRates: DOLLARS,
+  });
+  if (Number.isFinite(value)) return { priced: true, value };
+  const cost = held.reduce((total, position) => total + Math.abs(position.shares * (position.avgCost ?? 0)), 0);
+  return { priced: false, value: Number.isFinite(cost) ? cost : 0 };
+}
+
+/**
+ * Up to three tickers, or none for the generic copy:
+ * - the biggest holdings across every portfolio, those with a known market
+ *   value first by that value, then any the device cannot value yet by cost;
+ * - with nothing held, the first watchlist tickers in list order (lists in
+ *   their order, each sorted by ticker as the pane shows it). Team lists and
+ *   the names the app seeds on first run are skipped: nobody here picked them.
+ */
+export function selectUpgradeTickers(
+  tickers: Iterable<TickerRecord>,
+  financials: ReadonlyMap<string, TickerFinancials>,
+  watchlists: readonly Watchlist[],
+): string[] {
+  const records = [...tickers];
+  const holdings = new Map<string, Holding>();
+  for (const ticker of records) {
+    const symbol = plainSymbol(ticker);
+    if (!symbol) continue;
+    const holding = heldValue(ticker, financials.get(ticker.metadata.ticker));
+    if (holding) holdings.set(symbol, holding);
+  }
+  if (holdings.size > 0) {
+    return [...holdings]
+      .sort(([leftSymbol, left], [rightSymbol, right]) => (
+        Number(right.priced) - Number(left.priced)
+        || right.value - left.value
+        || leftSymbol.localeCompare(rightSymbol)
+      ))
+      .slice(0, UPGRADE_TICKER_LIMIT)
+      .map(([symbol]) => symbol);
+  }
+
+  const picked: string[] = [];
+  for (const watchlist of watchlists) {
+    if (watchlist.teamId) continue;
+    const members = records
+      .filter((ticker) => ticker.metadata.watchlists.includes(watchlist.id))
+      .sort((left, right) => left.metadata.ticker.localeCompare(right.metadata.ticker));
+    for (const ticker of members) {
+      const symbol = plainSymbol(ticker);
+      if (!symbol || STARTER_SYMBOLS.has(symbol) || picked.includes(symbol)) continue;
+      picked.push(symbol);
+      if (picked.length === UPGRADE_TICKER_LIMIT) return picked;
+    }
+  }
+  return picked;
+}
+
+/** "NVDA", "NVDA and AAPL", "NVDA, AAPL and MSFT". */
+export function upgradeTickerList(tickers: readonly string[]): string {
+  const [first = "", second, third] = tickers;
+  if (third) return tf("{first}, {second} and {third}", { first, second: second!, third });
+  if (second) return tf("{first} and {second}", { first, second });
+  return first;
+}

package/src/{plugins/builtin/cloud → account}/verification-panel.tsx

@@ -1,10 +1,10 @@
 import { useCallback, useEffect, useRef, useState } from "react";
-import { apiClient, type AuthUser } from "../../../api-client";
-import { Button } from "../../../components/ui/button";
-import { useShortcut } from "../../../react/input";
-import { Box, Text } from "../../../ui";
-import { colors } from "../../../theme/colors";
-import { isPlainKey } from "../../../utils/keyboard";
+import { apiClient, type AuthUser } from "../api-client";
+import { Button } from "../components/ui/button";
+import { useShortcut } from "../react/input";
+import { Box, Text } from "../ui";
+import { colors } from "../theme/colors";
+import { isPlainKey } from "../utils/keyboard";
 
 /** Shared continuation after email signup in the terminal and browser. */
 export function CloudVerificationPanel({ onVerified, onContinueFree }: {

package/src/api-client/askg.ts

@@ -1,7 +1,10 @@
 import {
   ASKG_PROTOCOL_VERSION,
+  type ASKGCapabilities,
   type ASKGDoneReason,
   type ASKGErrorCode,
+  type ASKGFeedback,
+  type ASKGFeedbackRequest,
   type ASKGSessionStartRequest,
   type ASKGSessionStartResponse,
   type ASKGSseEvent,
@@ -90,10 +93,14 @@ interface ASKGConversationMessage {
   tools: ASKGConversationTool[];
   turnId: string | null;
   createdAt: string;
+  /** On an answer: the person's own rating, null when unrated. */
+  feedback?: ASKGFeedback | null;
 }
 
 export interface ASKGConversationDetail extends ASKGConversationSummary {
   messages: ASKGConversationMessage[];
+  /** `feedback: 1` when this server takes ratings; absent from an older one. */
+  capabilities?: ASKGCapabilities;
 }
 
 export interface ASKGTransport {
@@ -134,6 +141,16 @@ export interface ASKGTransport {
     id: string,
     options?: { signal?: AbortSignal },
   ): Promise<boolean>;
+  /**
+   * Rates one answer and returns the rating as stored. Null when the server
+   * has no answer of this person's under that id, which is also what a
+   * server without the route says.
+   */
+  sendFeedback(
+    turnId: string,
+    request: ASKGFeedbackRequest,
+    options?: { signal?: AbortSignal },
+  ): Promise<ASKGFeedback | null>;
 }
 
 /** One decoded server-sent event frame. */
@@ -662,4 +679,30 @@ export class CloudASKGApi implements ASKGTransport {
       throw classifyASKGRequestError(error);
     }
   }
+
+  async sendFeedback(
+    turnId: string,
+    request: ASKGFeedbackRequest,
+    options: { signal?: AbortSignal } = {},
+  ): Promise<ASKGFeedback | null> {
+    try {
+      const stored = await this.options.request<Partial<ASKGFeedback> | null>(
+        `/askg/turns/${encodeURIComponent(turnId)}/feedback`,
+        {
+          method: "PUT",
+          body: JSON.stringify(request),
+          signal: options.signal,
+        },
+      );
+      // What the server stored, read defensively: the control shows it.
+      return {
+        rating: stored?.rating === "down" ? "down" : stored?.rating === "up" ? "up" : request.rating,
+        reason: stored?.reason ?? null,
+        shared: stored?.shared === true,
+      };
+    } catch (error) {
+      if (error instanceof ApiRequestError && error.status === 404) return null;
+      throw classifyASKGRequestError(error);
+    }
+  }
 }

package/src/api-client/auth.ts

@@ -11,8 +11,10 @@ import type {
   CloudBrowserHandoffResponse,
   CloudPricing,
   CloudVerificationResponse,
+  CreatedMcpKey,
   DeviceAuthStartResponse,
   DeviceAuthTokenResponse,
+  McpKeyScope,
   PersistedAuthUser,
 } from "./types";
 
@@ -269,6 +271,19 @@ export class CloudAuthApi {
     return result.feed;
   }
 
+  /**
+   * Creates an MCP key for an agent, the same call as Cloud settings, Agents.
+   * Needs Pro (402 otherwise) and fails with 409 at the per-account limit. The
+   * token in the answer is never returned again, so callers show it once and
+   * keep it out of logs and storage.
+   */
+  async createMcpKey(input: { name: string; scope: McpKeyScope }): Promise<CreatedMcpKey> {
+    return this.options.request<CreatedMcpKey>("/account/mcp/keys", {
+      method: "POST",
+      body: JSON.stringify({ name: input.name, scope: input.scope }),
+    });
+  }
+
   /** A new calendar feed link; the old one stops working. */
   async rotateCalendarFeed(): Promise<CalendarFeed> {
     const result = await this.options.request<{ feed: CalendarFeed }>(

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

@@ -85,6 +85,10 @@ export interface BeneficialOwnersPayload {
 
 export interface CloudBeneficialOwnersParams {
   ticker: string;
+  /** The listing's venue. Sent only for a venue outside the US, with `name`. */
+  exchange?: string;
+  /** The listing's company name, from its ticker or its own quote. */
+  name?: string;
   form?: BeneficialOwnersForm;
   history?: boolean;
   limit?: number;

package/src/api-client/chat.ts

@@ -1,6 +1,7 @@
 import {
   normalizeChatAttachments,
   normalizeChatChannel,
+  normalizeChatDiscordLink,
   normalizeChatMessage,
   normalizeChatMessages,
   normalizeChatState,
@@ -10,6 +11,7 @@ import type {
   ChatAttachment,
   ChatChannel,
   ChatChannelState,
+  ChatDiscordLink,
   ChatMessage,
   ChatNotification,
   ChatStateResponse,
@@ -256,6 +258,23 @@ export class CloudChatApi {
     return normalizeChatMessage(message);
   }
 
+  /** Whether this account is tied to a Discord person. Throws a 404 or 501 `ApiRequestError` on a server without Discord sync. */
+  async getDiscordLink(): Promise<ChatDiscordLink> {
+    return normalizeChatDiscordLink(await this.options.request<unknown>("/chat/discord/link"));
+  }
+
+  async unlinkDiscord(): Promise<void> {
+    await this.options.request<unknown>("/chat/discord/link", { method: "DELETE" });
+  }
+
+  /** Turns the mirroring of your own public messages to Discord on or off. */
+  async setDiscordMirror(enabled: boolean): Promise<void> {
+    await this.options.request<unknown>("/chat/discord/mirror", {
+      method: "PUT",
+      body: JSON.stringify({ enabled }),
+    });
+  }
+
   connectChannel(
     channelId: string,
     onMessage: (msg: ChatMessage) => void,

package/src/api-client/company-kpis.ts

@@ -1,3 +1,5 @@
+import { listingAbroad, type IssuerListingParams } from "./paths";
+
 type QuoteMatchMode = "exact" | "whitespace" | "nfkc_whitespace";
 
 type KpiBasis = "reported" | "adjusted" | "constant_currency" | "organic"
@@ -147,7 +149,17 @@ export interface KpiQueryOptions {
   /** Point-in-time publication cutoff; excludes later restatements and actuals. */
   asOf?: string
 }
-export function companyDisclosurePath(section: "kpis" | "guidance", symbol: string, options: KpiQueryOptions): string {
+/**
+ * A US listing or a bare symbol asks for the symbol as before. A listing abroad
+ * asks for its bare symbol with its venue and company, so it never reads the
+ * disclosures of a US company that has the same symbol.
+ */
+export function companyDisclosurePath(section: "kpis" | "guidance", symbol: string, options: KpiQueryOptions, listing: IssuerListingParams = {}): string {
   const query = new URLSearchParams(Object.entries(options).filter((entry): entry is [string, string] => entry[1] != null));
-  return `/cloud/company-${section}/${encodeURIComponent(symbol)}?${query}`;
+  const abroad = listingAbroad(symbol, listing.exchange, listing.name);
+  if (abroad) {
+    query.set("exchange", abroad.exchange);
+    if (abroad.name) query.set("name", abroad.name);
+  }
+  return `/cloud/company-${section}/${encodeURIComponent(abroad?.symbol ?? symbol)}?${query}`;
 }

package/src/api-client/data.ts

@@ -27,12 +27,12 @@ import type { CryptoMarketsPayload } from "./crypto-markets";
 import type { CentralBankRatesPayload } from "./central-bank-rates";
 import type { EstimateRevisionsPayload } from "./estimate-revisions";
 import type { MoneyMarketsPayload } from "./money-markets";
-import type { CloudCurveId, CloudCurveView, CloudWorldCurves } from "./yield-curves";
+import type { CloudCurveHistory, 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 { FuturesContractTermsPayload, 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";
@@ -65,11 +65,14 @@ import {
   cloudJobsPath,
   cloudJobsPostingsPath,
   type CloudJobsPostingsParams,
+  type IssuerListingParams,
   cloudProxyStatementPath,
+  cloudDebtMaturitiesPath,
   cloudFilingEventsPath,
   cloudRiskReportPath,
   cloudRiskReportsPath,
   cloudProxyStatementsPath,
+  cloudRevenueBreakdownPath,
   cloudExchangeRatePath,
   cloudSec13FPath,
   cloudSecBeneficialOwnersPath,
@@ -82,6 +85,7 @@ import {
   cloudMarketSearchPath,
   cloudMarketSymbolPath,
   cloudNewsPath,
+  cloudNewsSearchPath,
   cloudOptionsChainPath,
   cloudSavedSearchPath,
   cloudSavedSearchesPath,
@@ -120,8 +124,10 @@ import type {
   CloudRiskReportPayload,
   CloudCorporateActionsPayload,
   CloudEconEventPayload,
+  CloudMacroReleaseDaysPayload,
   CloudEquityDiagnosticMode,
   CloudEquityDiagnosticResult,
+  CloudFredSeriesCatalogPayload,
   CloudFredSeriesPayload,
   CloudShillerPayload,
   CloudFinancialsPayload,
@@ -414,6 +420,10 @@ export class CloudDataApi {
     return this.request<CloudEconEventPayload[]>("/cloud/econ/calendar");
   }
 
+  async getCloudMacroReleaseDays(): Promise<CloudMacroReleaseDaysPayload> {
+    return this.request<CloudMacroReleaseDaysPayload>("/cloud/econ/release-days");
+  }
+
   async getCloudFredSeries(
     seriesId: string,
     params: CloudFredSeriesParams = {},
@@ -425,6 +435,11 @@ export class CloudDataApi {
     );
   }
 
+  /** Every series `getCloudFredSeries` serves. A server older than the list answers 404. */
+  async getCloudFredSeriesCatalog(): Promise<CloudFredSeriesCatalogPayload> {
+    return this.request<CloudFredSeriesCatalogPayload>("/cloud/econ/series");
+  }
+
   async getCloudShiller(): Promise<CloudShillerPayload> {
     return this.request<CloudShillerPayload>(cloudShillerPath());
   }
@@ -483,12 +498,13 @@ export class CloudDataApi {
     return this.request<CatalystStatus>("/cloud/catalysts/status");
   }
 
-  async getCloudCompanyKpis(symbol: string, options: KpiQueryOptions = {}): Promise<KpisPayload> {
-    return this.request<KpisPayload>(companyDisclosurePath("kpis", symbol, options));
+  /** `listing` names a listing abroad's venue and company; a US listing needs neither. */
+  async getCloudCompanyKpis(symbol: string, options: KpiQueryOptions = {}, listing: IssuerListingParams = {}): Promise<KpisPayload> {
+    return this.request<KpisPayload>(companyDisclosurePath("kpis", symbol, options, listing));
   }
 
-  async getCloudCompanyGuidance(symbol: string, options: KpiQueryOptions = {}): Promise<GuidancePayload> {
-    return this.request<GuidancePayload>(companyDisclosurePath("guidance", symbol, options));
+  async getCloudCompanyGuidance(symbol: string, options: KpiQueryOptions = {}, listing: IssuerListingParams = {}): Promise<GuidancePayload> {
+    return this.request<GuidancePayload>(companyDisclosurePath("guidance", symbol, options, listing));
   }
   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)]))}`);
@@ -593,6 +609,15 @@ export class CloudDataApi {
     return this.request<CloudCurveView>(`/cloud/econ/curves/${encodeURIComponent(curve)}${query}`, { signal: AbortSignal.timeout(30_000) });
   }
 
+  /** One tenor of a curve from `from` (all stored sessions without one), oldest first. */
+  async getCloudCurveHistory(curve: CloudCurveId, tenor: string, from?: string | null): Promise<CloudCurveHistory> {
+    const query = new URLSearchParams({ tenor, ...(from ? { from } : {}) });
+    return this.request<CloudCurveHistory>(
+      `/cloud/econ/curves/${encodeURIComponent(curve)}/history?${query}`,
+      { signal: AbortSignal.timeout(30_000) },
+    );
+  }
+
   /** Each market's latest curve and the session before, each on its own date. */
   async getCloudWorldCurves(): Promise<CloudWorldCurves> {
     return this.request<CloudWorldCurves>("/cloud/econ/curves", { signal: AbortSignal.timeout(30_000) });
@@ -619,14 +644,12 @@ export class CloudDataApi {
     return this.request<MoneyMarketsPayload>("/cloud/econ/money-markets", { signal: AbortSignal.timeout(45_000) });
   }
 
-  async getCloudDebtMaturities(symbol: string): Promise<DebtMaturitiesPayload> {
-    const params = new URLSearchParams({ symbol });
-    return this.request<DebtMaturitiesPayload>(`/cloud/debt-maturities?${params}`, { signal: AbortSignal.timeout(45_000) });
+  async getCloudDebtMaturities(symbol: string, listing?: IssuerListingParams): Promise<DebtMaturitiesPayload> {
+    return this.request<DebtMaturitiesPayload>(cloudDebtMaturitiesPath(symbol, listing), { signal: AbortSignal.timeout(45_000) });
   }
 
-  async getCloudRevenueBreakdown(symbol: string, view?: RevenueBreakdownView): Promise<RevenueBreakdownPayload> {
-    const params = new URLSearchParams({ symbol, ...(view ? { view } : {}) });
-    return this.request<RevenueBreakdownPayload>(`/cloud/revenue-breakdown?${params}`, { signal: AbortSignal.timeout(30_000) });
+  async getCloudRevenueBreakdown(symbol: string, view?: RevenueBreakdownView, listing?: IssuerListingParams): Promise<RevenueBreakdownPayload> {
+    return this.request<RevenueBreakdownPayload>(cloudRevenueBreakdownPath(symbol, view, listing), { signal: AbortSignal.timeout(30_000) });
   }
 
   async getCloudMnaDeals(params: MnaDealsParams = {}, options?: { signal?: AbortSignal }): Promise<MnaDealsPayload> {
@@ -690,6 +713,11 @@ export class CloudDataApi {
     return this.request<FuturesCurvePayload>(`/cloud/futures/curve/${encodeURIComponent(root)}`, { signal: AbortSignal.timeout(60_000) });
   }
 
+  /** 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 getCloudFuturesCurveAsOf(root: string, date: string): Promise<FuturesCurveAsOfPayload> {
     return this.request<FuturesCurveAsOfPayload>(`/cloud/futures/curve/${encodeURIComponent(root)}/as-of/${encodeURIComponent(date)}`,
       { signal: AbortSignal.timeout(30_000) });
@@ -756,44 +784,49 @@ export class CloudDataApi {
     );
   }
 
+  // A listing outside the US also sends its venue and company (listingAbroad).
   async getProxyStatements(
     ticker: string,
+    listing?: IssuerListingParams,
   ): Promise<CloudProxyStatementListPayload> {
     return this.request<CloudProxyStatementListPayload>(
-      cloudProxyStatementsPath(ticker),
+      cloudProxyStatementsPath(ticker, listing),
     );
   }
 
   async getProxyStatement(
     ticker: string,
     year: number,
+    listing?: IssuerListingParams,
   ): Promise<CloudProxyStatementPayload> {
     return this.request<CloudProxyStatementPayload>(
-      cloudProxyStatementPath(ticker, year),
+      cloudProxyStatementPath(ticker, year, listing),
     );
   }
 
   async getFilingEvents(
     ticker: string,
     limit?: number,
+    listing?: IssuerListingParams,
   ): Promise<{ ticker: string; events: CloudFilingEventPayload[] }> {
     return this.request<{ ticker: string; events: CloudFilingEventPayload[] }>(
-      cloudFilingEventsPath(ticker, limit),
+      cloudFilingEventsPath(ticker, limit, listing),
     );
   }
 
-  async getRiskReports(ticker: string): Promise<CloudRiskReportListPayload> {
+  async getRiskReports(ticker: string, listing?: IssuerListingParams): Promise<CloudRiskReportListPayload> {
     return this.request<CloudRiskReportListPayload>(
-      cloudRiskReportsPath(ticker),
+      cloudRiskReportsPath(ticker, listing),
     );
   }
 
   async getRiskReport(
     ticker: string,
     year: number,
+    listing?: IssuerListingParams,
   ): Promise<CloudRiskReportPayload> {
     return this.request<CloudRiskReportPayload>(
-      cloudRiskReportPath(ticker, year),
+      cloudRiskReportPath(ticker, year, listing),
     );
   }
 
@@ -908,6 +941,13 @@ export class CloudDataApi {
     return this.request<CloudNewsListResponse>(cloudNewsPath(params));
   }
 
+  async searchCloudNews(
+    query: string,
+    limit?: number,
+  ): Promise<CloudNewsListResponse> {
+    return this.request<CloudNewsListResponse>(cloudNewsSearchPath(query, limit));
+  }
+
   async getCloudNewsStory(storyId: string): Promise<CloudNewsPayload> {
     return this.request<CloudNewsPayload>(
       `/news/${encodeURIComponent(storyId)}`,

package/src/api-client/earnings.ts

@@ -1,3 +1,5 @@
+import type { EarningsDateStatus, EarningsEpsBasis } from "../types/financials";
+
 /** Before the open, during the session, after the close. */
 export type EarningsTiming = "bmo" | "dmh" | "amc";
 
@@ -44,6 +46,8 @@ export interface EarningsReport {
   revenueAnalysts: number | null;
   implied: EarningsImpliedMove | null;
   realized: EarningsRealizedMove | null;
+  /** Whether the date is out, announced or projected; absent from older servers. */
+  dateStatus?: EarningsDateStatus;
 }
 
 export interface EarningsCalendarReport extends EarningsReport {
@@ -61,6 +65,8 @@ export interface EarningsCalendarPayload {
 
 interface EarningsHistoryReport extends EarningsReport {
   revenueActual: number | null;
+  /** Null when the basis cannot be determined; absent from older servers. */
+  epsBasis?: EarningsEpsBasis | null;
 }
 
 export interface EarningsHistoryPayload {

package/src/api-client/futures-curve.ts

@@ -1,3 +1,37 @@
+/** What one contract of a root is, from the exchange's rulebook. */
+export interface FuturesContractSpec {
+  /** What a quoted price counts: "USD / troy oz", "US cents / bushel", "index points". */
+  unit: string
+  /** One contract as the exchange words it: "100 troy oz", "$50 x index". */
+  size: string
+  /** US dollars a move of 1.0 in the quoted price makes on one contract. */
+  pointValue: number
+  /** The smallest outright price move, in the quoted unit. */
+  tick: number
+  /** US dollars one tick makes on one contract. */
+  tickValue: number
+  settlement: "physical" | "cash"
+}
+
+/** What a futures symbol trades: the contract behind it, its terms and its latest confirmed settlement. */
+export interface FuturesContractTermsPayload {
+  /** The symbol asked for: GC=F, GCZ26 or CL1. */
+  symbol: string
+  root: string
+  name: string
+  /** The listed contract the symbol prices today (GCZ26 for GC=F); null where it cannot be placed. */
+  contract: string | null
+  contractSymbol: string | null
+  deliveryMonth: string | null
+  spec: FuturesContractSpec | null
+  lastTrade: string | null
+  firstNotice: string | null
+  /** Past first notice: a long can be assigned delivery. */
+  inDelivery: boolean
+  /** The newest exchange settlement confirmed for the contract, with its session. */
+  settlement: { price: number; date: string } | null
+}
+
 /** Gloom Cloud futures prices retain provider denomination and explicit quote units. */
 export interface FuturesContract {
   symbol: string
@@ -17,6 +51,18 @@ export interface FuturesContract {
   samples: number
   historyStart: string | null
   historyEnd: string | null
+  /**
+   * The exchange settlement for the curve's settlementDate; null when none is
+   * confirmed for that session. `price` is the latest trade, never a settlement,
+   * except on a Cboe curve, whose prices are settlements.
+   */
+  settlement?: number | null
+  /** The last trading day. */
+  lastTrade?: string | null
+  /** First notice day of a physically delivered contract; null where there is none. */
+  firstNotice?: string | null
+  /** Past first notice: a long can be assigned delivery. */
+  inDelivery?: boolean
 }
 
 export interface FuturesCurvePayload {
@@ -51,6 +97,10 @@ export interface FuturesCurvePayload {
     state: "contango" | "backwardation" | "flat" | "unavailable"
   }
   gaps: string[]
+  /** The session the contracts' settlements are for; null when none is confirmed. */
+  settlementDate?: string | null
+  /** The root's contract terms; null where they are not listed. */
+  spec?: FuturesContractSpec | null
 }
 
 
@@ -78,6 +128,12 @@ export interface FuturesCurveAsOfPayload {
     /** When the price was made; older than tradeDate when the contract did not trade that day. */
     asOf: string
     stale: boolean
+    /** The price is the exchange settlement for tradeDate; otherwise that session's last trade or, when stale, an earlier price. */
+    settled?: boolean
+    lastTrade?: string | null
+    firstNotice?: string | null
+    inDelivery?: boolean
   }>
   gaps: string[]
+  spec?: FuturesContractSpec | null
 }