@gloom-sh/terminal 0.0.0-stage → 0.18.5

package/src/api-client/types.ts

@@ -0,0 +1,2341 @@
+import type {
+  AnalystResearchData,
+  CorporateActionsData,
+  HolderData,
+  HolderRecord,
+  OptionsChain,
+  PriceHistorySource,
+  Quote,
+  TickerFinancials,
+} from "../types/financials";
+import type { SyncSettings, SyncSnapshot } from "../sync/types";
+import type { ChatPaneLink } from "./chat-pane-link";
+
+/**
+ * What stands behind a chat account. `discord` is a person on the Gloom
+ * Discord who has not linked a Gloom account: a ghost with no profile, no DMs.
+ * A server that predates the field leaves it out, which reads as a human.
+ */
+export type ChatAccountType = "human" | "managed_llm" | "discord";
+
+/** Where a message was written. A message without one came from the app. */
+export type ChatMessageOrigin = "app" | "discord";
+
+/** A badge an account earns in chat: `team` for Gloom staff, `pro` with Pro access. */
+export type ChatUserBadge = "team" | "pro";
+
+export interface ChatUserSummary {
+  id: string;
+  /** A person, a managed assistant (Gloombot), or a Discord user bridged into public channels. */
+  accountType?: ChatAccountType;
+  username: string | null;
+  displayName: string;
+  bio?: string | null;
+  company?: string | null;
+  title?: string | null;
+  profilePublic?: boolean;
+  acceptUnknownDms?: boolean;
+  portfolioAnalytics?: PublicPortfolioAnalytics | null;
+  /** Badges the account earns. A server that predates them, or a person with none, leaves this out. */
+  badges?: ChatUserBadge[];
+  /**
+   * The person's current offset from UTC in minutes, as their app last
+   * reported it: left out while they keep their local time hidden.
+   */
+  utcOffsetMinutes?: number;
+  /** The desks (equities, options, ...) the person chose to show; left out unless they did. */
+  desks?: string[];
+}
+
+/**
+ * An image in a chat message, as the server stored it: `width`, `height`,
+ * `size` and `mime` describe the stored copy, not the upload. `url` opens in an
+ * <img> without headers; signed links last one to two hours, and a fresh copy
+ * of the message carries a fresh one.
+ */
+export interface ChatAttachment {
+  id: string;
+  mime: string;
+  width: number;
+  height: number;
+  size: number;
+  url: string;
+}
+
+/** Someone who reacted, as a reaction lists the first few. */
+export interface ChatReactionUser {
+  id: string;
+  username: string | null;
+  displayName: string;
+  accountType?: ChatAccountType | null;
+}
+
+/**
+ * One emoji on a message: how many reacted, whether you did, and the first
+ * few who did, oldest first. `emoji` is the character, or `:name:` for a
+ * custom Discord server emoji.
+ */
+export interface ChatReaction {
+  emoji: string;
+  count: number;
+  me: boolean;
+  users?: ChatReactionUser[];
+}
+
+/** A message's reactions as they stand after a change, from the `chat.reactions` frame or a reaction request. */
+export interface ChatReactionsUpdate {
+  channelId: string;
+  messageId: string;
+  reactions: ChatReaction[];
+}
+
+export interface ChatMessage {
+  id: string;
+  channelId: string;
+  content: string;
+  replyToId: string | null;
+  createdAt: string;
+  editedAt?: string | null;
+  user: ChatUserSummary;
+  origin?: ChatMessageOrigin;
+  replyTo?: {
+    content: string;
+    user: { id?: string; username: string };
+    /** Images on the quoted message. */
+    attachmentCount?: number;
+  } | null;
+  /** Images in display order. A server that predates them leaves this out. */
+  attachments?: ChatAttachment[];
+  /**
+   * Emoji reactions in the order they first appeared. Message lists from a
+   * server that knows reactions always carry it; a live copy of a message
+   * (an edit) leaves it out, and the reactions held stay.
+   */
+  reactions?: ChatReaction[];
+  /**
+   * Only on the author's copy of a public message whose images are still being
+   * checked ("pending") or could not be checked ("failed"). Nobody else has the
+   * message yet.
+   */
+  attachmentReview?: "pending" | "failed";
+  /** What the message opens in the terminal (a Gloom Wire story or calendar). Only the server sets it. */
+  paneLink?: ChatPaneLink;
+  /**
+   * An announcement Gloom posted, drawn as one. Only the server sets it, and
+   * only on one that still stands: a retracted announcement is the removal
+   * placeholder without it.
+   */
+  announcement?: true;
+  clientStatus?: "sending" | "failed";
+  clientError?: string | null;
+  /** The idempotency key a local send went out with, so a retry repeats it. */
+  clientMessageId?: string;
+}
+
+/** Whether this account is tied to a person on the Gloom Discord, and whether its public messages go there. */
+export interface ChatDiscordLink {
+  linked: boolean;
+  discordUsername?: string;
+  mirror: boolean;
+  /** False when the server has linking switched off. A server that predates the field is available. */
+  available: boolean;
+}
+
+export interface ChatChannel {
+  id: string;
+  name: string;
+  kind?: "public" | "direct" | "group" | "team";
+  created_at: string;
+  teamId?: string;
+  dmUser?: ChatUserSummary | null;
+  members?: ChatUserSummary[];
+  /**
+   * When the newest message you can see in a direct or group conversation was
+   * sent; null when it has none. Absent from channels of other kinds and from
+   * servers that do not report it.
+   */
+  lastMessageAt?: string | null;
+}
+
+/** Minimal identities scoped by the server to this channel and existing DMs. */
+export interface ChatMentionCandidate {
+  id: string;
+  username: string;
+  displayName: string | null;
+  channelActivityAt: string | null;
+  conversationActivityAt: string | null;
+}
+
+export interface ChatChannelState {
+  channelId: string;
+  notificationsEnabled: boolean;
+  lastReadMessageId: string | null;
+  unreadCount: number;
+}
+
+export interface ChatNotification {
+  id: string;
+  type: "reply" | "mention" | "channel";
+  channelId: string;
+  messageId: string;
+  createdAt: string;
+  message: ChatMessage;
+}
+
+export interface ChatStateResponse {
+  channels: ChatChannel[];
+  onlineCount: number;
+  channelStates: ChatChannelState[];
+  notifications: ChatNotification[];
+}
+
+export interface AuthUser {
+  id: string;
+  name: string;
+  email: string;
+  username: string | null;
+  emailVerified: boolean;
+  image: string | null;
+  plan?: "free" | "pro";
+  /** ISO timestamp when the free Pro trial ends; null once it has lapsed or was never started. */
+  trialEndsAt?: string | null;
+  /** Plan the server actually entitles right now, i.e. `plan` upgraded to "pro" while a trial is running. */
+  effectivePlan?: "free" | "pro";
+  company?: string | null;
+  title?: string | null;
+  bio?: string | null;
+  profilePublic?: boolean;
+  publicEmail?: string | null;
+  xAccount?: string | null;
+  sharedPortfolioId?: string | null;
+  acceptUnknownDms?: boolean;
+  chatEmailNotificationsEnabled?: boolean;
+  portfolioAnalytics?: PublicPortfolioAnalytics | null;
+  syncEnabled?: boolean;
+  weeklyRoundupEnabled?: boolean;
+  positionAlertsEnabled?: boolean;
+  lastSyncAt?: string | null;
+  lastRoundupEmailAt?: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export type PersistedAuthUser = Pick<AuthUser, "id" | "emailVerified"> &
+  Partial<AuthUser>;
+
+export interface AccountProfile {
+  id: string;
+  email: string;
+  emailVerified: boolean;
+  plan: "free" | "pro";
+  /** ISO timestamp when the free Pro trial ends; null once it has lapsed or was never started. */
+  trialEndsAt?: string | null;
+  /** Plan the server actually entitles right now, i.e. `plan` upgraded to "pro" while a trial is running. */
+  effectivePlan?: "free" | "pro";
+  username: string | null;
+  name: string;
+  company: string | null;
+  title: string | null;
+  bio: string | null;
+  profilePublic: boolean;
+  publicEmail: string | null;
+  xAccount: string | null;
+  sharedPortfolioId: string | null;
+  acceptUnknownDms: boolean;
+  chatEmailNotificationsEnabled: boolean;
+  portfolioAnalytics?: PublicPortfolioAnalytics | null;
+  /** Chat shows your local time on your card. A server that predates the setting leaves it out. */
+  showLocalTime?: boolean;
+  /** The desks chat shows beside your name; empty shows none. */
+  chatDesks?: string[];
+  /** Your answer to "What do you trade?" at the first run: private, it pre-fills `chatDesks`. */
+  onboardingDesks?: string[];
+  syncEnabled: boolean;
+  weeklyRoundupEnabled: boolean;
+  positionAlertsEnabled: boolean;
+  lastSyncAt: string | null;
+  lastRoundupEmailAt: string | null;
+  updatedAt: string | null;
+}
+
+export interface PublicPortfolioAnalytics {
+  oneYearReturn?: number | null;
+  spyBeta?: number | null;
+  /** "account": the broker's own returns. "holdings": estimated from today's holdings. */
+  basis?: "account" | "holdings" | null;
+}
+
+export interface BuildoutAccountResponse {
+  user: {
+    id: string;
+    email: string;
+    emailVerified: boolean;
+  };
+  subscription: {
+    product: "buildout";
+    plan: "free" | "pro";
+    active: boolean;
+    billingInterval: "month" | "year" | null;
+    stripeSubscriptionId: string | null;
+    stripeSubscriptionStatus: string | null;
+  };
+  prices: {
+    monthly: {
+      priceId: string;
+      amountUsd: number;
+      interval: "month";
+    };
+    yearly: {
+      priceId: string;
+      amountUsd: number;
+      interval: "year";
+    };
+  };
+}
+
+export interface BuildoutTokenResponse {
+  token: string;
+  expiresAt: string;
+}
+
+interface CloudPricingTier {
+  /** Charged amount, in integer cents. */
+  amount: number;
+}
+
+/** `/account/cloud`, reduced to the plan fields the apps read. */
+export interface CloudAccountPlan {
+  effectivePlan?: "free" | "pro";
+  /** Whether a checkout started now comes with the free trial attached. */
+  trialAvailable?: boolean;
+  /** The last charge failed; checkout opens the unpaid invoice instead. */
+  paymentFailed?: boolean;
+}
+
+/** Public `/pricing` payload; no session required. */
+export interface CloudPricing {
+  currency: "usd";
+  trialDays: number;
+  monthly: CloudPricingTier;
+  yearly: CloudPricingTier;
+}
+
+/**
+ * What an MCP key reaches beyond market data: `data` is market and filing
+ * tools only, `read` adds notes, teams and collections, `write` lets the agent
+ * save notes and change collection items.
+ */
+export type McpKeyScope = "data" | "read" | "write";
+
+/**
+ * A key just created with `POST /account/mcp/keys`. `token` is the secret,
+ * which the server never returns again: show it once, never store it.
+ */
+export interface CreatedMcpKey {
+  token: string;
+  apiKey: { id: string; name: string; scope: McpKeyScope };
+}
+
+/** The account's private calendar feed link (`/account/calendar-feed`). */
+export interface CalendarFeed {
+  url: string;
+  createdAt: string;
+  /** The last time a calendar app read it, to the hour. */
+  lastFetchedAt: string | null;
+}
+
+/** One command-bar prefix described for `/assist/command`. */
+export interface AssistCommandDescriptor {
+  prefix: string;
+  name: string;
+  description?: string;
+  arg?: {
+    placeholder?: string;
+    kind: "text" | "ticker" | "ticker-list";
+    /** The command also runs with no argument at all. */
+    optional?: boolean;
+    /** Named values the argument accepts; a command may take others too (COT takes any CFTC code). */
+    options?: { value: string; label: string }[];
+  };
+}
+
+/** A command-bar line the assistant believes answers the query. */
+export interface AssistCommandCandidate {
+  /** Exact command-bar text to run, e.g. "G NVDA AMD". */
+  input: string;
+  title: string;
+  prefix: string;
+  confidence: number;
+}
+
+export interface AssistCommandResponse {
+  candidates: AssistCommandCandidate[];
+  /**
+   * The server's record of this ask, for the command-search report to point
+   * at. Only present when the ask was sent with `log: true`.
+   */
+  searchId?: string;
+}
+
+export type AccountProfileUpdate = Partial<{
+  username: string;
+  name: string;
+  company: string | null;
+  title: string | null;
+  bio: string | null;
+  profilePublic: boolean;
+  publicEmail: string | null;
+  xAccount: string | null;
+  sharedPortfolioId: string | null;
+  acceptUnknownDms: boolean;
+  chatEmailNotificationsEnabled: boolean;
+  portfolioAnalytics: PublicPortfolioAnalytics | null;
+  syncEnabled: boolean;
+  weeklyRoundupEnabled: boolean;
+  positionAlertsEnabled: boolean;
+  showLocalTime: boolean;
+  /** Null or empty shows no desks. */
+  chatDesks: string[] | null;
+}>;
+
+export interface CloudSyncSnapshotResponse {
+  snapshot: SyncSnapshot | null;
+  revision: number | null;
+  updatedAt: string | null;
+  settings: SyncSettings;
+}
+
+export interface CloudSyncPushResponse {
+  revision: number;
+  updatedAt: string;
+  settings: SyncSettings;
+}
+
+export interface CloudQuotePayload extends Omit<Quote, "change" | "changePercent" | "priceBasis" | "priceObservation"> {
+  /** The service labels daily NAV here; the app separates observation kind from price units. */
+  priceBasis?: Quote["priceBasis"] | "nav";
+  // JSON encodes the provider's unavailable numeric values as null.
+  change?: number | null;
+  changePercent?: number | null;
+  providerId: "gloomberb-cloud";
+  dataSource: "live" | "delayed";
+}
+
+export interface CloudFinancialsPayload extends Omit<TickerFinancials, "quote"> {
+  quote?: CloudQuotePayload;
+}
+
+export interface CloudWorldVenuePayload {
+  mic: string;
+  name: string;
+  title: string;
+  country: string;
+  countryCode: string;
+  city: string;
+  timezone: string;
+  latitude: number;
+  longitude: number;
+  isOpen: boolean;
+  timeAfterOpenSeconds?: number;
+  timeToOpenSeconds?: number;
+  timeToCloseSeconds?: number;
+}
+
+export interface CloudWorldVenueMapPayload {
+  providerId: "gloomberb-cloud";
+  checkedAt: number;
+  refreshAt: number;
+  stale?: boolean;
+  venues: CloudWorldVenuePayload[];
+}
+
+export interface CloudOptionsChainPayload extends OptionsChain {
+  providerId: "gloomberb-cloud";
+}
+
+interface CloudHolderPayload extends HolderRecord {
+  providerId: "gloomberb-cloud";
+  ownerType: "institution";
+}
+
+export interface CloudHoldersPayload extends HolderData {
+  providerId: "gloomberb-cloud";
+  holders: CloudHolderPayload[];
+}
+
+export interface CloudAnalystResearchPayload extends AnalystResearchData {
+  providerId: "gloomberb-cloud";
+}
+
+export interface CloudCorporateActionsPayload extends CorporateActionsData {
+  providerId: "gloomberb-cloud";
+}
+
+export interface CloudPricePointPayload {
+  /** @deprecated No longer read; a history's boundary is its response `coverage`. */
+  historySource?: PriceHistorySource;
+  date: string;
+  open?: number;
+  high?: number;
+  low?: number;
+  close: number;
+  volume?: number;
+  /**
+   * One venue's count for a bar whose market volume is unavailable (a US session still trading, counted on IEX
+   * alone), served in place of `volume`.
+   */
+  venueVolume?: { venue: string; volume: number };
+  /** A daily bar still forming when served: a coin's UTC day, or the trade date a future is trading. */
+  partial?: boolean;
+  /** A coin's daily bar whose prices were rebuilt from hourly bars; a day the source left empty has no volume. */
+  filled?: boolean;
+  /** A future's closed session whose settlement is not confirmed yet: it closes on the last trade. */
+  unsettled?: boolean;
+}
+
+type CloudEconImpact = "high" | "medium" | "low";
+
+export interface CloudEconEventPayload {
+  id: string;
+  date: string;
+  time: string;
+  country: string;
+  event: string;
+  actual: string | null;
+  forecast: string | null;
+  prior: string | null;
+  impact: CloudEconImpact;
+  /** Rows the calendar adds beside its feeds: a central bank's kept decision or a statistics office's listed release. */
+  kind?: "central-bank-decision" | "statistics-release";
+  /** The publisher's own clock time and its IANA zone; null when it states no time. */
+  localTime?: string | null;
+  timeZone?: string;
+  /** Why a row has no time, when its publisher states none. */
+  timeNote?: string | null;
+  priorAsOf?: string | null;
+  referencePeriod?: string | null;
+  /** Who publishes the release (Freddie Mac for the 30-year mortgage rate), and its page when one is named. */
+  source?: { name: string; url?: string };
+  /**
+   * The indicator this release is of, the same from one release to the next
+   * (US CPI m/m on every month's row), where `id` names the one row. Absent
+   * until Gloom Cloud names indicators; exports leave the column empty.
+   */
+  indicatorId?: string | null;
+}
+
+/** One currency's short-term rate, as GET /cloud/econ/short-rates serves it. */
+export interface CloudShortRate {
+  currency: string;
+  /** "SOFR", "TIIE 28d". */
+  name: string;
+  /** "overnight" or the term the rate is for. */
+  tenor: string;
+  tenorDays: number;
+  /** Days in the year the rate is quoted over. */
+  dayCountBasis: 360 | 365;
+  publisher: string;
+  sourceUrl: string;
+  /** Percent a year; null when it could not be read. */
+  value: number | null;
+  /** The day the rate is for. */
+  asOf: string | null;
+  fetchedAt: string | null;
+  stale: boolean;
+  unavailableReason: string | null;
+}
+
+export interface CloudShortRatesPayload {
+  generatedAt: string;
+  rates: CloudShortRate[];
+}
+
+/** CPI, payrolls and FOMC statement days as published, as GET /cloud/econ/release-days serves them. */
+export interface CloudMacroReleaseDaysPayload {
+  /** When the publishers' pages were read, ISO. */
+  checkedAt: string;
+  /** The last New York day the lists are complete for. */
+  coveredThrough: string;
+  sources: string[];
+  /** New York dates, oldest first. Brazil's IPCA days when the server can vouch for them. */
+  releases: Record<"cpi" | "jobs" | "fomc", string[]> & { ipca?: string[] };
+  /** Each kind's figures by New York release day, for the days they are known. */
+  figures?: Partial<Record<"cpi" | "jobs" | "fomc" | "ipca", Record<string, {
+    event: string;
+    actual: string | null;
+    forecast: string | null;
+    prior: string | null;
+    /** Above the consensus (hot), below it (cool), at it (in-line); null without both. */
+    surprise: "hot" | "cool" | "in-line" | null;
+  }>>>;
+}
+
+export interface CloudFredObservationPayload {
+  date: string;
+  value: number | null;
+  /**
+   * Who published a value FRED does not list yet, such as a Treasury yield
+   * Gloom Cloud read from the Treasury first. Absent on FRED's own values.
+   */
+  publisher?: string;
+  /** When that publisher's value was first read, ISO in UTC. */
+  publishedAt?: string;
+  /**
+   * The day FRED's source released this value (`YYYY-MM-DD`), on the newest
+   * observation of a weekly to annual series: September's permits are dated
+   * 1 Sep and were released 20 Oct. Absent on daily series and older points.
+   */
+  releasedOn?: string;
+}
+
+export interface CloudFredSeriesInfoPayload {
+  id: string;
+  title: string;
+  units: string;
+  frequency: string;
+  seasonalAdjustment: string;
+  source: string;
+  notes: string;
+  lastUpdated?: string;
+  observationStart?: string;
+  observationEnd?: string;
+}
+
+export interface CloudFredSeriesPayload {
+  observations: CloudFredObservationPayload[];
+  info: CloudFredSeriesInfoPayload | null;
+  fetchedAt?: string;
+  stale?: boolean;
+  coverage?: { observations: "available"; info: "available" | "unavailable" };
+}
+
+/** The FRED series Gloom Cloud serves, from `GET /cloud/econ/series`; any other id is refused. */
+export interface CloudFredSeriesCatalogPayload {
+  series: Array<{ id: string; title?: string | null; group?: string | null }>;
+}
+
+/**
+ * One month of Robert Shiller's dataset. FRED carries no long-run S&P earnings,
+ * so this is what every earnings-based valuation ratio is built from.
+ */
+interface CloudShillerObservationPayload {
+  date: string;
+  price: number | null;
+  dividend: number | null;
+  earnings: number | null;
+  cpi: number | null;
+  longRate: number | null;
+  cape: number | null;
+  /** CAPE earnings yield over the real 10-year rate; Shiller's equity risk premium. */
+  excessCapeYield: number | null;
+}
+
+export interface CloudShillerPayload {
+  observations: CloudShillerObservationPayload[];
+  sourceUrl: string;
+  fetchedAt: string;
+}
+
+/** One publicly disseminated single-name CDS transaction report. */
+export interface CloudCdsTradePayload {
+  disseminationId: string;
+  originalDisseminationId: string | null;
+  actionType: string;
+  eventTimestamp: string;
+  executionTimestamp: string | null;
+  effectiveDate: string | null;
+  expirationDate: string | null;
+  maturityDate: string | null;
+  issuerName: string | null;
+  underlierId: string | null;
+  underlierIdSource: string | null;
+  upi: string | null;
+  upiFisn: string | null;
+  upiUnderlierName: string | null;
+  notionalAmount: number | null;
+  /** Reported notional is a regulatory cap, so the real trade was at least this size. */
+  notionalCapped: boolean;
+  notionalCurrency: string | null;
+  fixedRate: number | null;
+  reportedSpread: number | null;
+  /** Unit of `reportedSpread`, e.g. basis points or percent. */
+  spreadNotation: string | null;
+  upfrontAmount: number | null;
+  upfrontCurrency: string | null;
+}
+
+export interface CloudCdsResponse {
+  source: string;
+  asOf: string | null;
+  trades: CloudCdsTradePayload[];
+}
+
+/** One New York trade date of an issuer's on-the-run 5Y spread. */
+export interface CloudCdsHistoryPointPayload {
+  date: string;
+  /** Median of the day's prints in basis points. */
+  spreadBp: number;
+  prints: number;
+  /** Prints that reported the spread; the rest were converted from their upfront. */
+  reported: number;
+  /** The contract on the run that day, e.g. "2031-12-20". */
+  maturity: string;
+  /** For a line quoted upfront: that day's level in points on the line's coupon. */
+  upfrontPts?: number;
+}
+
+/**
+ * Past 2,000bp a name is quoted in points upfront on its running coupon, the
+ * level and its moves alike; `spreadBp` and the bp moves stay beside them.
+ * Absent from servers before it, which read as `spread`.
+ */
+interface CloudCdsUpfrontQuote {
+  quote?: "spread" | "upfront";
+  /** The line's running coupon, bp. */
+  couponBp?: number | null;
+  upfrontPts?: number | null;
+  change1WPts?: number | null;
+  change1MPts?: number | null;
+}
+
+export interface CloudCdsHistoryResponse extends CloudCdsUpfrontQuote {
+  source: string;
+  /** The matched reference entity, or null when nothing on the tape matched. */
+  issuer: string | null;
+  tenor: string;
+  currency: string | null;
+  asOf: string | null;
+  points: CloudCdsHistoryPointPayload[];
+  /**
+   * The last point's move over a week and a month in bp, on one contract and
+   * chained through the contract before across a roll, as the index board's.
+   * Null without a comparable level, or once the level is more than 5 trading
+   * days behind the tape; absent from servers before them.
+   */
+  change1W?: number | null;
+  change1M?: number | null;
+  /**
+   * Why the line has no level in the month to its newest print, when one
+   * cause explains it: `upfront-side-unknown` when the prints carry an
+   * upfront without the side that paid it and nothing else places the level.
+   */
+  noLevelReason?: string | null;
+}
+
+/** An issuer's latest 5Y level: the last point of its history over the last month. */
+export interface CloudCdsLevelPayload extends CloudCdsUpfrontQuote {
+  /** The reference entity as the history response names it. */
+  issuer: string;
+  spreadBp: number;
+  date: string;
+  /** As the history response's moves for the same name. */
+  change1W?: number | null;
+  change1M?: number | null;
+}
+
+export interface CloudCdsLevelsResponse {
+  source: string;
+  tenor: string;
+  asOf: string | null;
+  /** Every issuer traded in the last month whose 5Y line has a level in it. */
+  levels: CloudCdsLevelPayload[];
+}
+
+interface CloudShortInterestPointPayload {
+  settlementDate: string;
+  shortPercentFloat?: number | null;
+  /** The 10-K or 10-Q cover share count known when FINRA published the settlement. Absent on servers older than the field. */
+  sharesOutstanding?: number;
+  /** YYYY-MM-DD that count was taken. */
+  sharesOutstandingAsOf?: string;
+  sharesShort: number;
+  previousSharesShort: number | null;
+  averageDailyVolume: number | null;
+  daysToCover: number | null;
+  changePercent: number | null;
+  revised: boolean;
+}
+
+export interface CloudShortInterestPayload {
+  source?: "finra" | "gloom";
+  symbol: string;
+  issueName: string | null;
+  points: CloudShortInterestPointPayload[];
+}
+
+export interface CloudYieldPointPayload {
+  maturity: string;
+  maturityYears: number;
+  yield: number | null;
+  /** FRED observation date. Absent on servers older than the field. */
+  asOf?: string | null;
+  fetchedAt?: string;
+  stale?: boolean;
+}
+
+type CloudCongressTradeSide = "BUY" | "SELL" | "EXCHANGE" | "OTHER";
+
+export interface CloudCongressTradePayload {
+  id: string;
+  chamber: "house" | "senate";
+  filingId: string;
+  docId: string;
+  memberName: string;
+  stateDistrict: string;
+  filingDate: string;
+  transactionDate: string | null;
+  notificationDate: string | null;
+  lagDays: number | null;
+  side: CloudCongressTradeSide;
+  transactionType: string;
+  ticker: string | null;
+  assetName: string;
+  assetType: string | null;
+  owner: string;
+  rawOwner: string;
+  amount: string;
+  amountLow: number | null;
+  amountHigh: number | null;
+  capGainsOver200: boolean | null;
+  filingStatus: string | null;
+  subholdingOf: string | null;
+  description: string | null;
+  sourceUrl: string;
+  returnSinceTx?: number | null;
+  returnSinceFiling?: number | null;
+  returnAsOf?: string | null;
+  party?: string | null;
+  committees?: string[];
+}
+
+export interface CloudCongressMemberPayload {
+  id: string;
+  memberName: string;
+  stateDistrict: string;
+  tradeCount: number;
+  buyCount: number;
+  sellCount: number;
+  exchangeCount: number;
+  otherCount: number;
+  estimatedLow: number | null;
+  estimatedHigh: number | null;
+  lastFilingDate: string | null;
+  avgLagDays: number | null;
+  medianReturn?: number | null;
+  buyHitRate?: number | null;
+  pricedTradeCount?: number;
+  pricedBuyCount?: number;
+  party?: string | null;
+  committees?: string[];
+}
+
+export interface CloudCongressTickerPayload {
+  ticker: string;
+  tradeCount: number;
+  buyCount: number;
+  sellCount: number;
+  exchangeCount: number;
+  otherCount: number;
+  memberCount: number;
+  memberIds: string[];
+  estimatedLow: number | null;
+  estimatedHigh: number | null;
+  lastFilingDate: string | null;
+}
+
+export interface CloudCongressHousePayload {
+  asOf: string;
+  /** "all" pages both chambers' filings as one date-ordered index. */
+  chamber: "house" | "senate" | "all";
+  source: "house-clerk" | "senate-efd" | "congress";
+  year: number;
+  indexUpdatedAt: string | null;
+  filingsScanned: number;
+  /** Filings in the window the server could read. */
+  filingsParsed?: number;
+  /** Filings the source refused; the server retries them on its own schedule. */
+  filingsFailed?: number;
+  /** Filings left unread because the server's daily document budget is spent. */
+  filingsPending?: number;
+  /** Scanned Senate paper filings: listed and linked, not read. */
+  filingsPaper?: number;
+  /** The merged feed could not reach the Senate source; this window is House only. */
+  senateUnavailable?: boolean;
+  filingCount: number;
+  filingOffset?: number;
+  hasMore?: boolean;
+  hasMoreFilings?: boolean;
+  nextOffset?: number;
+  nextFilingOffset?: number;
+  trades: CloudCongressTradePayload[];
+  members: CloudCongressMemberPayload[];
+  tickers?: CloudCongressTickerPayload[];
+}
+
+export interface CloudEarningsCallPayload {
+  id: string;
+  ticker: string;
+  companyName: string | null;
+  fiscalYear: number | null;
+  fiscalQuarter: number | null;
+  callAt: string | null;
+  status: string;
+  durationSeconds: number | null;
+  wordCount: number | null;
+  hasTranscript: boolean;
+  sentiment: number | null;
+  /** The replay or event page the transcript came from. */
+  webcastUrl?: string | null;
+  /**
+   * Whether `callAt` is the call's start or its day alone (00:00 UTC of that
+   * New York day). Absent from a server that predates it.
+   */
+  callTimeKnown?: boolean;
+}
+
+interface CloudJobsSeriesPoint {
+  day: string;
+  open: number;
+  /** Null on the first observed day, when the whole board is seen for the first time. */
+  new: number | null;
+  closed: number;
+  /** Open standing roles the company hires for continuously. */
+  evergreen?: number;
+  /** Open contract and temporary roles. */
+  contract?: number;
+}
+
+export interface CloudJobsBucket {
+  id: string;
+  label: string;
+  count: number;
+  share: number;
+  /** Count 30 days ago from the daily roll-up, when the history reaches back. */
+  previous: number | null;
+}
+
+export interface CloudJobsPosting {
+  id: number;
+  title: string;
+  function: string | null;
+  seniority: string | null;
+  location: string | null;
+  country: string | null;
+  remote: boolean | null;
+  employmentKind?: string | null;
+  /** A standing posting for a continuous-hiring role; null when unjudged. */
+  evergreen?: boolean | null;
+  postedAt: string | null;
+  postedPrecision: "exact" | "approximate" | "floor" | null;
+  firstSeenAt: string;
+  url: string | null;
+  salaryMin: number | null;
+  salaryMax: number | null;
+  salaryCurrency: string | null;
+  salaryPeriod: string | null;
+  tags: string[];
+}
+
+/** One posting as its detail view reads it. */
+export interface CloudJobsPostingDetail extends CloudJobsPosting {
+  /** The careers system's own id. */
+  externalId: string;
+  /** As the careers system writes it ("Full time", "FULL_TIME", "CDI"). */
+  employmentType: string | null;
+  /** The start of the role's description, as read from its page. */
+  description: string | null;
+  closedAt: string | null;
+}
+
+export interface CloudJobsChange {
+  count: number;
+  percent: number | null;
+}
+
+export interface CloudJobsSummaryPayload {
+  status: "ok";
+  ticker: string;
+  companyName: string | null;
+  coverage: {
+    status: string;
+    vendor: string | null;
+    careersUrl: string | null;
+    lastCollectedAt: string | null;
+    firstObservedAt: string | null;
+    daysObserved: number;
+    employeeCount: number | null;
+  };
+  openCount: number;
+  openPerThousandEmployees: number | null;
+  new7d: number;
+  new30d: number;
+  closed30d: number;
+  change30d: CloudJobsChange | null;
+  change90d: CloudJobsChange | null;
+  /** False when the careers system re-dates every role on refresh, so dates are withheld. */
+  datesReliable?: boolean;
+  /** Open postings the system dates within the last 30 days. */
+  posted30d?: number | null;
+  remoteShare: number | null;
+  /**
+   * Open roles that are standing postings for continuous-hiring positions
+   * (baristas, servers, store associates, nurses). One more of those says
+   * nothing about the company's plans; open minus evergreen is the count of
+   * specific roles.
+   */
+  evergreenCount?: number;
+  evergreenShare?: number | null;
+  /** Share of open roles that are contract or temporary, among those known. */
+  contractShare?: number | null;
+  medianAgeDays: number | null;
+  series: CloudJobsSeriesPoint[];
+  /** The current backlog by how long each role has been posted. */
+  ageBuckets?: Array<{ id: string; label: string; count: number }>;
+  functions: CloudJobsBucket[];
+  countries: CloudJobsBucket[];
+  seniority: CloudJobsBucket[];
+  tags: CloudJobsBucket[];
+  salary: {
+    count: number;
+    currency: string;
+    period: string;
+    medianMin: number;
+    medianMax: number;
+    byFunction: Array<{ id: string; label: string; count: number; medianMin: number; medianMax: number }>;
+  } | null;
+  recent: CloudJobsPosting[];
+}
+
+interface CloudJobsPendingPayload {
+  status: "pending";
+  ticker: string;
+  queued: boolean;
+  message: string;
+}
+
+export type CloudJobsResponse = CloudJobsSummaryPayload | CloudJobsPendingPayload;
+
+export interface CloudJobsPostingsPayload {
+  postings: CloudJobsPosting[];
+  total: number;
+}
+
+export interface CloudJobsMoverPayload {
+  ticker: string;
+  companyName: string | null;
+  openCount: number;
+  employeeCount: number | null;
+  change30d: CloudJobsChange | null;
+  /** Open roles the system dates within the last 30 days, null when its dates cannot be read. */
+  posted30d?: number | null;
+  new7d: number;
+  topFunction: string | null;
+  topCountry?: { code: string; share: number } | null;
+}
+
+export interface CloudJobsMoversPayload {
+  asOf: string;
+  covered: number;
+  /** Companies in the ranking; `movers` is one page of them. */
+  total?: number;
+  movers: CloudJobsMoverPayload[];
+}
+
+export interface CloudEarningsCallListPayload {
+  calls: CloudEarningsCallPayload[];
+  /** Set when asking about a company started a search that is still running. */
+  pending?: boolean;
+  /** Set when the requested symbol is not one the SEC knows. */
+  unknownTicker?: boolean;
+}
+
+/** One row of a proxy statement's Summary Compensation Table, in dollars. */
+export interface CloudExecutiveRowPayload {
+  name: string;
+  title: string;
+  salary: number | null;
+  bonus: number | null;
+  stockAwards: number | null;
+  optionAwards: number | null;
+  nonEquityIncentive: number | null;
+  pensionAndDeferred: number | null;
+  allOther: number | null;
+  total: number | null;
+}
+
+interface CloudProxyStatementSummaryPayload {
+  id: string;
+  ticker: string;
+  company: {
+    ticker: string;
+    cik: string | null;
+    name: string;
+    shortName: string;
+  };
+  /** Year of the filing date: what people call "the 2026 proxy". */
+  proxyYear: number;
+  fiscalYear: number | null;
+  fiscalYearLabel: string | null;
+  filedAt: string;
+  meetingDate: string | null;
+  updatedAt: string;
+  ceoName: string | null;
+  ceoTitle: string | null;
+  ceoTotal: number | null;
+  ceoPriorYearTotal: number | null;
+  payRatio: number | null;
+  medianEmployeePay: number | null;
+}
+
+export interface CloudProxyStatementPayload extends CloudProxyStatementSummaryPayload {
+  /**
+   * `preview` for an account without Pro: each executive's total pay from
+   * the latest proxy, with the breakdown, the year before, the pay ratio,
+   * say-on-pay, highlights, key figures and other years null or empty.
+   * Absent on Pro's full statement.
+   */
+  access?: "preview";
+  docUrl: string;
+  ceo: (CloudExecutiveRowPayload & { priorYearTotal: number | null }) | null;
+  namedExecutives: CloudExecutiveRowPayload[];
+  sayOnPayPriorSupport: number | null;
+  highlights: string | null;
+  keyFigures: CloudTranscriptKeyFigurePayload[];
+  otherYears: CloudProxyStatementSummaryPayload[];
+}
+
+interface CloudRiskFactorPayload {
+  heading: string;
+  group: string | null;
+  excerpt: string;
+  words: number;
+}
+
+export interface CloudRiskNotePayload {
+  /** Position of the risk in `risks` (or in the prior year's list, for removed). */
+  index: number;
+  text: string;
+}
+
+interface CloudRiskReportSummaryPayload {
+  id: string;
+  ticker: string;
+  company: {
+    ticker: string;
+    cik: string | null;
+    name: string;
+    shortName: string;
+  };
+  /** Year of the filing date: "the 2026 10-K". */
+  reportYear: number;
+  filedAt: string;
+  updatedAt: string;
+  riskCount: number;
+  groupCount: number;
+  wordCount: number;
+  addedCount: number | null;
+  removedCount: number | null;
+  rewordedCount: number | null;
+  overview: string | null;
+}
+
+export interface CloudRiskReportPayload extends CloudRiskReportSummaryPayload {
+  docUrl: string;
+  groups: string[];
+  risks: CloudRiskFactorPayload[];
+  diff: {
+    added: number[];
+    removed: Array<{ heading: string; group: string | null; excerpt: string }>;
+    reworded: Array<{
+      index: number;
+      similarity: number;
+      headingChanged: boolean;
+      priorHeading: string | null;
+    }>;
+    matched: number;
+    priorRiskCount: number;
+  } | null;
+  notes: {
+    added: CloudRiskNotePayload[];
+    removed: CloudRiskNotePayload[];
+    reworded: CloudRiskNotePayload[];
+    top: CloudRiskNotePayload[];
+  };
+  otherYears: CloudRiskReportSummaryPayload[];
+}
+
+export interface CloudRiskReportListPayload {
+  company: {
+    ticker: string;
+    cik: string | null;
+    name: string;
+    shortName: string;
+  } | null;
+  reports: CloudRiskReportSummaryPayload[];
+}
+
+interface CloudFilingPersonPayload {
+  name: string;
+  role: string;
+  action: string;
+  effective: string | null;
+}
+
+/** An 8-K, classified by its items and, when it carried news, read. */
+export interface CloudFilingEventPayload {
+  id: string;
+  ticker: string;
+  company: {
+    ticker: string;
+    cik: string | null;
+    name: string;
+    shortName: string;
+  };
+  filedAt: string;
+  /** Verified SEC filing calendar date; filedAt may instead be an acceptance instant. */
+  filingDate?: string | null;
+  /** "8-K", or "8-K/A" for an amendment. Older servers omit it. */
+  form?: string;
+  docUrl: string;
+  items: string[];
+  labels: string[];
+  kinds: string[];
+  material: boolean;
+  headline: string | null;
+  summary: string | null;
+  people: CloudFilingPersonPayload[];
+  /** True when the headline and points are the model's reading rather than the item labels. */
+  read: boolean;
+}
+
+export interface CloudProxyStatementListPayload {
+  company: {
+    ticker: string;
+    cik: string | null;
+    name: string;
+    shortName: string;
+  };
+  proxies: CloudProxyStatementSummaryPayload[];
+  /** `preview` for an account without Pro: the latest proxy alone, without the year before or the pay ratio. */
+  access?: "preview";
+}
+
+export interface CloudTranscriptTurnPayload {
+  speaker: string;
+  role?: string;
+  company?: string;
+  text: string;
+  /** `text` cut where the speaker paused or changed topic; absent on older transcripts. */
+  paragraphs?: string[];
+  isQa: boolean;
+  /** Offset into the recording; null when the company published the transcript as a document. */
+  startSeconds: number | null;
+  /** Where each of `paragraphs` starts in the recording, in seconds; absent without timings or on older servers. */
+  paragraphStarts?: number[];
+}
+
+interface CloudTranscriptKeyFigurePayload {
+  /** What the number is, e.g. "Q3 revenue guidance". */
+  label: string;
+  /** As management said it, e.g. "$108B ± 2%". */
+  value: string;
+  /** Comparison or qualifier, e.g. "vs $96B in Q2". */
+  note?: string;
+}
+
+interface CloudTranscriptParticipantPayload {
+  name: string;
+  role?: string;
+  company?: string;
+}
+
+export interface CloudEarningsTranscriptPayload {
+  id: string;
+  ticker: string;
+  companyName: string | null;
+  fiscalYear: number | null;
+  fiscalQuarter: number | null;
+  callAt: string | null;
+  timing: string | null;
+  webcastUrl: string | null;
+  durationSeconds: number | null;
+  status: string;
+  fullText: string;
+  turns: CloudTranscriptTurnPayload[];
+  participants: CloudTranscriptParticipantPayload[];
+  /** The numbers management gave, picked for a card; empty on older transcripts. */
+  keyFigures?: CloudTranscriptKeyFigurePayload[];
+  summary: string | null;
+  guidance: string | null;
+  riskFactors: string | null;
+  analystFocus: string | null;
+  notable: string | null;
+  sentiment: number | null;
+  sentimentRationale: string | null;
+  qaStartTurn: number | null;
+  wordCount: number | null;
+  asrModel: string | null;
+  updatedAt: string | null;
+}
+
+/**
+ * A call's audio to play beside its transcript. `kind` names what it is; a
+ * stored recording is the only kind so far.
+ */
+export interface CloudEarningsCallAudioPayload {
+  kind: "recording";
+  /** A signed address that plays until `expiresAt`, seeking included. */
+  url: string;
+  expiresAt: string;
+  durationSeconds: number | null;
+  bytes?: number;
+  contentType?: string;
+}
+
+export type CloudSearchDocType = "transcript" | "news" | "filing";
+
+export type CloudSearchSort = "relevance" | "newest" | "oldest";
+
+/**
+ * Per-chunk provenance. Which keys are present depends on `docType`: transcripts
+ * carry speaker attribution, news carries the wire source, filings carry the
+ * form and section. Kept as one optional-key record so an unknown docType from a
+ * newer server still renders instead of failing to parse.
+ */
+export interface CloudSearchChunkMetadata {
+  speaker?: string;
+  role?: string;
+  company?: string;
+  isQa?: boolean;
+  startSeconds?: number;
+  turnIndex?: number;
+  source?: string;
+  summary?: string;
+  form?: string;
+  accession?: string;
+  section?: string;
+}
+
+export interface CloudSearchHit {
+  id: string;
+  docType: CloudSearchDocType;
+  sourceId: string;
+  chunkIndex: number;
+  ticker: string;
+  publishedAt: string;
+  title: string;
+  url: string;
+  /** Matched terms wrapped in `<mark>`, fragments joined by an ellipsis. */
+  snippet: string;
+  score: number;
+  metadata: CloudSearchChunkMetadata;
+  /**
+   * Chunks of this document that matched. Only sent for a distinct search,
+   * where the row stands for the document rather than for one chunk.
+   */
+  matchCount?: number;
+}
+
+export interface CloudSearchResponse {
+  hits: CloudSearchHit[];
+  total: number;
+  /** The server stopped counting past its cap, so `total` is a lower bound. */
+  countCapped: boolean;
+  hasMore: boolean;
+  nextOffset: number;
+  tookMs: number;
+}
+
+interface CloudSearchDocumentChunk {
+  id: string;
+  chunkIndex: number;
+  body: string;
+  metadata: CloudSearchChunkMetadata;
+}
+
+export interface CloudSearchDocument {
+  docType: CloudSearchDocType;
+  sourceId: string;
+  ticker: string;
+  title: string;
+  url: string;
+  publishedAt: string;
+  chunks: CloudSearchDocumentChunk[];
+}
+
+export interface CloudSearchDocumentResponse {
+  document: CloudSearchDocument;
+}
+
+export interface CloudSavedSearchFilters {
+  tickers?: string[];
+  docTypes?: CloudSearchDocType[];
+  sources?: string[];
+  from?: string;
+  to?: string;
+}
+
+export interface CloudSavedSearch {
+  id: string;
+  name: string;
+  query: string;
+  filters: CloudSavedSearchFilters;
+  alertEnabled: boolean;
+  alertChannels: string[];
+  lastRunAt: string | null;
+  lastMatchAt: string | null;
+  matchCount: number;
+  createdAt: string;
+}
+
+export interface CloudSavedSearchListResponse {
+  searches: CloudSavedSearch[];
+}
+
+export interface CloudSavedSearchInput {
+  name: string;
+  query: string;
+  filters?: CloudSavedSearchFilters;
+  alertEnabled?: boolean;
+  alertChannels?: string[];
+}
+
+interface CloudSecFilingPayload {
+  accessionNumber: string;
+  form: string;
+  filingDate: string;
+  acceptedAt?: string;
+  /** Unmodified SEC acceptanceDateTime; a missing timezone is not inferred. */
+  acceptedAtRaw?: string;
+  primaryDocument?: string;
+  primaryDocDescription?: string;
+  items?: string;
+  /** SEC's period of report, YYYY-MM-DD: a 10-Q's or 10-K's balance-sheet date. Absent from older servers. */
+  reportDate?: string;
+  cik: string;
+  companyName?: string;
+  filingUrl: string;
+  primaryDocumentUrl?: string;
+  /** The filing's SEC file number for this company, empty when it has none. Absent from older servers. */
+  fileNumber?: string;
+  /** In a fund's list from a trust that runs several funds: filed for the fund's own series. Absent from older servers. */
+  fundSeries?: boolean;
+}
+
+interface CloudSecDocumentPayload {
+  sequence?: string;
+  type: string;
+  description?: string;
+  document: string;
+  url: string;
+  size?: string;
+  isPrimary: boolean;
+}
+
+export interface CloudSecFilingsResponse {
+  filings: CloudSecFilingPayload[];
+  hasMore: boolean;
+  nextOffset: number;
+}
+
+export interface CloudSecDocumentsResponse {
+  documents: CloudSecDocumentPayload[];
+}
+
+interface CloudSecForm4Payload {
+  filingDate: string;
+  reportedName: string;
+  title: string;
+  transactionType: "P" | "S" | "A" | "D" | "";
+  shares: number;
+  pricePerShare: number | null;
+  totalValue: number | null;
+  sharesOwned: number | null;
+  form: string;
+}
+
+export interface CloudSecContentResponse {
+  content: string | null;
+  form4: CloudSecForm4Payload | null;
+}
+
+interface CloudNewsEntityPayload {
+  id: string;
+  entityType: string;
+  name: string;
+  symbol: string | null;
+  exchange: string | null;
+  canonicalTicker: string | null;
+  role: string | null;
+  confidence: number | null;
+}
+
+interface CloudNewsTickerLinkPayload {
+  symbol: string;
+  exchange: string;
+  canonicalTicker: string;
+  relationType: string;
+  displayTier: "primary" | "related";
+  confidence: number;
+  relevanceScore: number;
+  impactScore?: number;
+  sentiment?: "positive" | "neutral" | "negative" | null;
+}
+
+export interface CloudNewsStoryItemPayload {
+  id: string;
+  sourceKey: string;
+  sourceName: string;
+  title: string;
+  summary?: string;
+  url: string;
+  publishedAt: string;
+  hasArticleText?: boolean;
+}
+
+export interface CloudNewsPayload {
+  id: string;
+  headline: string;
+  summary: string;
+  topic?: string;
+  topics?: string[];
+  category: string;
+  sentiment: "positive" | "neutral" | "negative";
+  sectors: string[];
+  scope?: string;
+  firstPublishedAt: string;
+  lastPublishedAt: string;
+  firstSeenAt: string;
+  lastSeenAt: string;
+  primaryUrl: string;
+  /** Routing key of the representative item, for source filters. */
+  primarySource: string;
+  /** Who published the representative item (FT, SEC, @unusual_whales). */
+  primaryPublisher?: string;
+  publishers?: string[];
+  scores?: {
+    importance?: number;
+    urgency?: number;
+    marketImpact?: number;
+    novelty?: number;
+    confidence?: number;
+  };
+  flags?: {
+    breaking?: boolean;
+    developing?: boolean;
+    stale?: boolean;
+  };
+  variantCount: number;
+  sourceCount: number;
+  sources: string[];
+  entities: CloudNewsEntityPayload[];
+  tickerLinks: CloudNewsTickerLinkPayload[];
+  items?: CloudNewsStoryItemPayload[];
+}
+
+export interface CloudNewsListResponse {
+  items: CloudNewsPayload[];
+  nextCursor: string | null;
+}
+
+interface CloudTweetUserPayload {
+  id: string;
+  userName: string;
+  name: string;
+}
+
+interface CloudTweetMetricsPayload {
+  retweets: number | null;
+  replies: number | null;
+  likes: number | null;
+  quotes: number | null;
+  views: number | null;
+  bookmarks: number | null;
+}
+
+interface CloudTweetMediaPayload {
+  type?: string;
+  url?: string;
+  mediaUrl?: string;
+  media_url?: string;
+  media_url_https?: string;
+  previewImageUrl?: string;
+  preview_image_url?: string;
+}
+
+export interface CloudTweetPayload {
+  id: string;
+  url: string;
+  text: string;
+  createdAt: string;
+  lang: string;
+  isReply: boolean;
+  author: CloudTweetUserPayload;
+  metrics: CloudTweetMetricsPayload;
+  media?: CloudTweetMediaPayload[];
+  photos?: CloudTweetMediaPayload[];
+  images?: CloudTweetMediaPayload[];
+}
+
+export type CloudTweetQueryType = "Latest" | "Top";
+
+export interface CloudTweetSearchResponse {
+  ticker?: string;
+  cashtag?: string;
+  query: string;
+  queryType: CloudTweetQueryType;
+  since: string;
+  until: string;
+  limit: number;
+  offset?: number;
+  /** More tweets sit behind this page. Absent on servers without paging. */
+  hasMore?: boolean;
+  hours: number;
+  includeReplies?: boolean;
+  cached: boolean;
+  cacheTtlMs: number;
+  asOf: string;
+  tweets: CloudTweetPayload[];
+}
+
+type CloudMarketStatus =
+  | "success"
+  | "partial"
+  | "empty"
+  | "unsupported"
+  | "retryable_error"
+  | "fatal_error";
+
+/** The dates a history source vouches for. Which boundary fields appear depends on the reason. */
+export interface CloudHistoryCoverage {
+  source: string;
+  reasonCode?: string;
+  /** First date (YYYY-MM-DD) whose share lineage the source verified. */
+  verifiedLineageStart?: string;
+  /** First bar date (YYYY-MM-DD) the source serves, such as a fund's inception. */
+  firstAllowedBarDate?: string;
+  inceptionDate?: string;
+  /** Why nothing earlier is served, such as "old-shekel quotes before 1992 are not served". */
+  note?: string;
+  sourceUrl?: string;
+  firstBarDate: string | null;
+  lastBarDate: string | null;
+  barCount: number;
+}
+
+export interface CloudMarketResponse<T> {
+  status: CloudMarketStatus;
+  data: T | null;
+  reasonCode?: string;
+  /** Untrusted, human-readable reason the answer is empty. Cleaned before it is shown. */
+  message?: string;
+  asOf?: string;
+  staleAt?: string;
+  stale?: boolean;
+  currency?: string;
+  /** Untrusted history-only failure evidence, validated by the history adapter. */
+  historyRetention?: unknown;
+  /** Source-declared history semantics; validated separately from quote metadata. */
+  historySession?: unknown;
+  /** "extended" when the history includes the pre-market and after-hours bars asked for. */
+  session?: unknown;
+  /** "1day" when daily bars answer an intraday range: the listing has no intraday bars. */
+  servedResolution?: unknown;
+  /**
+   * Untrusted: daily sessions the bars leave out and why, as
+   * `[{ date: "2020-04-20", reason: "non-positive-close" }]`. Validated by the history adapter.
+   */
+  omittedSessions?: unknown;
+  /** Untrusted until the history adapter validates its boundary dates. */
+  coverage?: CloudHistoryCoverage;
+  /**
+   * Untrusted: a US listing that no longer trades, `{ status, lastTradeDate,
+   * historyStart }`. Its history ends on `lastTradeDate`. Read by parseListingDelisting.
+   */
+  delisting?: unknown;
+  providerMeta?: {
+    provider?: string;
+    upstream?: string;
+    status?: CloudMarketStatus;
+    reasonCode?: string;
+    normalizedSymbol?: string;
+    normalizedExchange?: string;
+    stale?: boolean;
+    fallbackReason?: string;
+    requestedResolution?: string;
+    servedResolution?: string;
+    latencyMs?: number;
+    range?: string;
+    granularity?: string;
+    timezone?: string;
+    currency?: string;
+    barCount?: number;
+  };
+}
+
+export interface CloudMarketBatchTarget {
+  symbol: string;
+  exchange?: string;
+}
+
+export interface CloudMarketBatchItem<T> {
+  symbol: string;
+  exchange: string;
+  status: CloudMarketStatus;
+  data: T | null;
+  reasonCode?: string;
+  /** Untrusted, human-readable reason this item is empty. Cleaned before it is shown. */
+  message?: string;
+  stale?: boolean;
+}
+
+export interface CloudMarketBatchPayload<T> {
+  items: Array<CloudMarketBatchItem<T>>;
+}
+
+export type CloudMarketScreenerCategory = "gainers" | "losers" | "most-active";
+
+/**
+ * What Gloom Cloud selects and ranks Gainers and Losers by: `regular` the last
+ * completed regular session's move, the Chg% a row shows; `extended` the
+ * latest print, after-hours or pre-market included. While the regular session
+ * trades the two are one list. A server that predates the choice ignores it
+ * and ranks by the latest print.
+ */
+export type CloudMoverSession = "regular" | "extended";
+
+/**
+ * A movers row's quote sessions, under the quote's field names and meaning:
+ * the session it was read in, the day its change is dated to, the last
+ * completed regular session's close and move, and an open pre-market or
+ * after-hours print with its move from that close. Older servers send none.
+ */
+export type CloudMoverSessionFields = Partial<Pick<Quote,
+  | "marketState" | "changeSessionDate"
+  | "regularClose" | "regularCloseSessionDate" | "regularChange" | "regularChangePercent"
+  | "preMarketPrice" | "preMarketChange" | "preMarketChangePercent"
+  | "postMarketPrice" | "postMarketChange" | "postMarketChangePercent">>;
+
+/** price, change and changePercent are the live print the server ranks the list by; the session fields say how it reads. */
+export interface CloudMarketScreenerItem extends CloudMoverSessionFields {
+  rank: number;
+  symbol: string;
+  name: string;
+  price: number;
+  change: number;
+  changePercent: number;
+  previousClose?: number;
+  volume: number;
+  /** Available average volume for this listing, independent of public ranking membership. */
+  avgVolume?: number;
+  /** Observation time of the optional retained metadata. */
+  metadataAsOf?: string;
+  tradeCount?: number;
+  currency: string;
+  high52w?: number;
+  low52w?: number;
+  dayHigh?: number;
+  dayLow?: number;
+  exchange: string;
+  lastUpdated: number;
+  dataSource: "live";
+}
+
+export interface CloudMarketScreenerPayload {
+  providerId: "gloomberb-cloud";
+  category: CloudMarketScreenerCategory;
+  asOf: string;
+  stale?: boolean;
+  items: CloudMarketScreenerItem[];
+}
+
+/** Cache reuse policy for one Equity Diagnostic request. */
+export type CloudEquityDiagnosticMode = "cache-first" | "refresh";
+
+export type CloudEquityDiagnosticFindingKind =
+  "red_flag" | "green_flag" | "anomaly";
+
+/** 3 is the most severe. */
+type CloudEquityDiagnosticSeverity = 1 | 2 | 3;
+
+export interface CloudEquityDiagnosticFinding {
+  id: string;
+  kind: CloudEquityDiagnosticFindingKind;
+  severity: CloudEquityDiagnosticSeverity;
+  confidence: number;
+  title: string;
+  /** What the data says, with no reading attached. */
+  observation: string;
+  /** What the observation may mean; kept apart from the observation on purpose. */
+  interpretation: string;
+  /** Ids into `evidence`; unresolved ids are dropped by the client. */
+  evidenceIds: string[];
+}
+
+export interface CloudEquityDiagnosticCoverage {
+  dataset: string;
+  status: "available" | "no_data" | "unsupported" | "failed";
+  asOf?: string;
+  provider?: string;
+  note?: string;
+}
+
+/** The server owns citation URLs; the client never builds them. */
+export interface CloudEquityDiagnosticEvidence {
+  id: string;
+  dataset: string;
+  label: string;
+  asOf?: string;
+  provider?: string;
+  url?: string;
+}
+
+interface CloudEquityDiagnosticPending {
+  status: "generating";
+  retryAfterMs: number;
+}
+
+export interface CloudEquityDiagnosticResponse {
+  schemaVersion: 1;
+  access: "preview" | "full";
+  symbol: string;
+  exchange: string;
+  companyName?: string;
+  status: "complete" | "partial" | "insufficient_data";
+  verdict: "risk_skewed" | "balanced" | "opportunity_skewed" | "unclear";
+  summary: string;
+  confidence: number;
+  findings: CloudEquityDiagnosticFinding[];
+  watchItems: string[];
+  coverage: CloudEquityDiagnosticCoverage[];
+  evidence: CloudEquityDiagnosticEvidence[];
+  generatedAt: string;
+  expiresAt: string;
+  /** Before this instant a `refresh` request may still answer from cache. */
+  refreshAllowedAt: string;
+  cached: boolean;
+  stale: boolean;
+  promptVersion: 1;
+  /** The model that answered. Diagnostic only: never rendered to the user. */
+  model: string;
+}
+
+export type CloudEquityDiagnosticResult =
+  CloudEquityDiagnosticPending | CloudEquityDiagnosticResponse;
+
+export interface CloudVerificationResponse {
+  sent: boolean;
+  email?: string;
+  alreadyVerified?: boolean;
+}
+
+/** A short-lived, single-use browser URL that establishes the existing desktop session. */
+export interface CloudBrowserHandoffResponse {
+  url: string;
+}
+
+export interface DeviceAuthStartResponse {
+  deviceCode: string;
+  /** 8 characters formatted "XXXX-XXXX", shown so a user without the app can type it. */
+  userCode: string;
+  expiresAt: string;
+  /** Like https://gloom.sh/link/<userCode>; this is what the QR code encodes. */
+  verificationUri: string;
+  pollIntervalMs: number;
+}
+
+/** The approved response is single-use; polling again returns a non-approved status. */
+export type DeviceAuthTokenResponse =
+  | { status: "pending" }
+  | { status: "denied" }
+  | { status: "expired" }
+  | { status: "approved"; sessionToken: string; user: AuthUser };
+
+/** Shared server-computed scanners fanned out to every subscriber. */
+export type ScannerKind = "hilo" | "flow";
+
+export type ScannerStatus = "live" | "starting" | "closed" | "degraded";
+
+interface ScannerWindowCounts {
+  highs: number;
+  lows: number;
+}
+
+export interface ScannerHiloExtreme {
+  symbol: string;
+  price: number;
+  volume?: number | null;
+  /** Times this symbol printed a new session extreme today. */
+  count: number;
+  at: number;
+}
+
+/** Which entitlement tier produced the payload: free accounts get a delayed instance. */
+interface ScannerAccessInfo {
+  access: "realtime" | "delayed";
+  /** 0 on the realtime instance, 15 on the delayed one. */
+  delayMinutes: number;
+}
+
+export interface ScannerHiloPayload extends ScannerAccessInfo {
+  status: ScannerStatus;
+  asOf: number;
+  windows: {
+    s30: ScannerWindowCounts;
+    m1: ScannerWindowCounts;
+    m5: ScannerWindowCounts;
+  };
+  highs: ScannerHiloExtreme[];
+  lows: ScannerHiloExtreme[];
+}
+
+export interface ScannerFlowEvent {
+  id: string;
+  at: number;
+  underlying: string;
+  contract: string;
+  right: "C" | "P";
+  strike: number;
+  expiry: string;
+  side: "ask" | "bid" | "mid" | "unknown";
+  kind: "sweep" | "block" | "split" | "trade";
+  size: number;
+  price: number;
+  premium: number;
+  volume?: number | null;
+  openInterest?: number | null;
+  volOi?: number | null;
+  iv?: number | null;
+}
+
+export interface ScannerFlowPayload extends ScannerAccessInfo {
+  status: ScannerStatus;
+  asOf: number;
+  events: ScannerFlowEvent[];
+}
+
+/** Filters for recorded flow prints, matching the FLOW pane's own. */
+export interface ScannerFlowHistoryQuery {
+  /** Page before this print (newest first); omit for the latest prints. */
+  before?: { at: number; id: string };
+  limit?: number;
+  minPremium?: number;
+  right?: "C" | "P";
+  kind?: "sweep" | "block";
+  minVolOi?: number;
+  maxExpiryDays?: number;
+  /** Only these listed symbols (the pane's "mine" universe). */
+  symbols?: string[];
+}
+
+export interface ScannerFlowHistoryPage {
+  events: ScannerFlowEvent[];
+  hasMore: boolean;
+}
+
+export type ScannerPayload = ScannerHiloPayload | ScannerFlowPayload;
+
+/** What a scanner subscriber receives: data, or the entitlement refusal. */
+export type ScannerFeedEvent<T extends ScannerPayload = ScannerPayload> =
+  { type: "data"; payload: T } | { type: "denied"; reason: string };
+
+export interface QuoteStreamTarget {
+  symbol: string;
+  exchange?: string;
+  surface?:
+    | "portfolio"
+    | "watchlist"
+    | "detail"
+    | "monitor"
+    | "inline"
+    | "options"
+    | "screener"
+    | "unknown";
+  visible?: boolean;
+  selected?: boolean;
+  weight?: number;
+}
+
+const TEAM_ACCENT_COLORS = [
+  "amber",
+  "blue",
+  "cyan",
+  "green",
+  "magenta",
+  "orange",
+  "red",
+  "violet",
+] as const;
+
+export type TeamAccentColor = (typeof TEAM_ACCENT_COLORS)[number];
+
+export type TeamRole = "owner" | "admin" | "member";
+
+export interface TeamSummary {
+  id: string;
+  name: string;
+  slug: string;
+  accentColor: TeamAccentColor;
+  shortName: string;
+  allowMemberInvites: boolean;
+  /** Seats the team can fill; a Team plan deal sets it, otherwise 25. */
+  memberLimit?: number;
+  channelId: string;
+  createdAt: string;
+  role: TeamRole;
+  memberCount: number;
+}
+
+export interface TeamMember {
+  id: string;
+  role: TeamRole;
+  joinedAt: string;
+  user: { id: string; username: string | null; displayName: string };
+}
+
+export interface TeamInviteLink {
+  token: string;
+  url: string;
+  teamId: string;
+  createdBy: string;
+  expiresAt: string;
+  maxUses: number | null;
+  uses: number;
+  createdAt: string;
+}
+
+/** A Better Auth organization invitation as returned by /auth/organization/* endpoints. */
+export interface TeamUser {
+  id: string;
+  username: string | null;
+  displayName: string;
+}
+
+/** An invitation addressed to the signed-in person. */
+export interface TeamReceivedInvitation {
+  id: string;
+  role: TeamRole;
+  expiresAt: string;
+  createdAt: string;
+  team: {
+    id: string;
+    name: string;
+    slug: string;
+    accentColor: TeamAccentColor;
+    shortName: string;
+    memberCount: number;
+  };
+  inviter: TeamUser;
+}
+
+/** An invitation a team sent; the invitee is null for addresses without an account. */
+export interface TeamSentInvitation {
+  id: string;
+  status: string;
+  role: TeamRole;
+  expiresAt: string;
+  createdAt: string;
+  inviter: TeamUser;
+  invitee: TeamUser | null;
+}
+
+export interface TeamUpdatedEvent {
+  teamId: string;
+  change: "settings" | "members" | "channels" | "deleted";
+}
+
+export interface TeamUsernameInvitation {
+  id: string;
+  status: string;
+  expiresAt: string;
+  invitee: { id: string; username: string | null; displayName: string };
+}
+
+interface TeamActor {
+  id: string;
+  username: string | null;
+  displayName: string;
+}
+
+interface TeamNotificationTeam {
+  id: string;
+  name: string;
+  accentColor: TeamAccentColor;
+  shortName: string;
+}
+
+type TeamNotificationData =
+  | {
+      kind: "team-invite";
+      team: TeamNotificationTeam;
+      invitationId: string;
+      expiresAt: string;
+      inviter: TeamActor;
+    }
+  | { kind: "team-joined"; team: TeamNotificationTeam; member: TeamActor }
+  | {
+      kind: "layout-updated";
+      team: TeamNotificationTeam;
+      layoutId: string;
+      layoutName: string;
+      revision: number;
+      author: TeamActor;
+    };
+
+type TeamNotificationType = TeamNotificationData["kind"];
+
+export interface TeamNotification {
+  id: string;
+  type: TeamNotificationType;
+  channelId: string;
+  createdAt: string;
+  data: TeamNotificationData;
+}
+
+// Cloud notes
+
+type NoteOwnerKind = "user" | "team";
+export type NoteKind = "ticker" | "quick";
+
+interface CloudNoteOwner {
+  kind: NoteOwnerKind;
+  id: string;
+}
+
+export interface CloudNoteSummary {
+  id: string;
+  owner: CloudNoteOwner;
+  kind: NoteKind;
+  key: string;
+  title: string | null;
+  revision: number;
+  updatedBy: { id: string; username: string | null; displayName: string };
+  createdAt: string;
+  updatedAt: string;
+  size: number;
+}
+
+export interface CloudNote extends Omit<CloudNoteSummary, "size"> {
+  content: string;
+}
+
+export interface CloudNoteScope {
+  scope: NoteOwnerKind;
+  teamId?: string;
+}
+
+// Theses
+
+export type ThesisStatus = "watching" | "active" | "closed";
+export type ThesisHealth = "unverified" | "intact" | "weakening" | "broken";
+export type ThesisPillarStatus = ThesisHealth;
+
+interface ThesisInstrument {
+  symbol: string;
+  exchange?: string;
+  side: "long" | "short";
+  role: "core" | "hedge";
+}
+
+interface ThesisMetricBound {
+  key: string;
+  op: ">=" | "<=";
+  value: number;
+  unit?: string;
+}
+
+export interface ThesisPillar {
+  id: string;
+  text: string;
+  kind: "qualitative" | "metric";
+  metric?: ThesisMetricBound;
+  /** Symbol the claim is about; absent means the thesis as a whole. */
+  scope?: string;
+  status: ThesisPillarStatus;
+  note?: string;
+}
+
+export interface ThesisKillCondition {
+  id: string;
+  text: string;
+  triggered: boolean;
+  note?: string;
+}
+
+export interface ThesisCatalyst {
+  id: string;
+  text: string;
+  date?: string;
+  status: "pending" | "hit" | "missed";
+}
+
+export interface ThesisDocument {
+  summary: string;
+  instruments: ThesisInstrument[];
+  evidence: { symbols: string[]; keywords: string[] };
+  pillars: ThesisPillar[];
+  killConditions: ThesisKillCondition[];
+  catalysts: ThesisCatalyst[];
+  target?: { price?: number; note?: string };
+  entry?: { date?: string; price?: number };
+}
+
+interface ThesisOutcome {
+  verdict: "right" | "wrong" | "lucky" | "unlucky";
+  returnPct?: number;
+  lesson?: string;
+}
+
+interface ThesisEditor {
+  id: string;
+  username: string | null;
+  displayName: string;
+}
+
+export interface CloudThesis {
+  id: string;
+  owner: CloudNoteOwner;
+  title: string;
+  status: ThesisStatus;
+  conviction: number;
+  horizon: string | null;
+  reviewEveryDays: number;
+  document: ThesisDocument;
+  outcome: ThesisOutcome | null;
+  health: ThesisHealth;
+  revision: number;
+  /** Signals waiting for a verdict. */
+  openSignals: number;
+  createdBy: string;
+  updatedBy: ThesisEditor;
+  createdAt: string;
+  updatedAt: string;
+  reviewedAt: string | null;
+  closedAt: string | null;
+}
+
+type ThesisSignalTargetKind = "pillar" | "kill" | "catalyst" | "thesis";
+type ThesisSignalVerdict = "supports" | "challenges" | "breaks" | "neutral";
+type ThesisSignalStatus = "open" | "accepted" | "dismissed" | "snoozed" | "noted";
+
+interface ThesisSignalSource {
+  kind: "news" | "filing" | "transcript" | "metric" | "review" | "user";
+  id?: string;
+  title?: string;
+  url?: string;
+  at?: string;
+  symbol?: string;
+}
+
+export interface ThesisSignal {
+  id: string;
+  thesisId: string;
+  targetKind: ThesisSignalTargetKind;
+  targetId: string | null;
+  verdict: ThesisSignalVerdict;
+  confidence: number | null;
+  reason: string;
+  source: ThesisSignalSource | null;
+  origin: "ai" | "rule" | "user";
+  status: ThesisSignalStatus;
+  resolutionNote: string | null;
+  createdBy: ThesisEditor | null;
+  resolvedBy: ThesisEditor | null;
+  createdAt: string;
+  resolvedAt: string | null;
+  snoozedUntil: string | null;
+}
+
+export interface ThesisDraft extends ThesisDocument {
+  title: string;
+  horizon: string | null;
+}
+
+export interface ThesisPatch {
+  title?: string;
+  status?: ThesisStatus;
+  conviction?: number;
+  horizon?: string | null;
+  reviewEveryDays?: number;
+  document?: ThesisDocument;
+  outcome?: ThesisOutcome | null;
+  note?: string | null;
+  reviewed?: boolean;
+}
+
+// Team collections
+
+export type TeamCollectionKind = "watchlist" | "portfolio";
+
+export interface TeamCollection {
+  id: string;
+  teamId: string;
+  kind: TeamCollectionKind;
+  name: string;
+  currency: string | null;
+  createdBy: string;
+  createdAt: string;
+  updatedAt: string;
+  itemCount: number;
+}
+
+export interface TeamCollectionItem {
+  collectionId: string;
+  symbol: string;
+  exchange: string;
+  quantity: number | null;
+  note: string | null;
+  /**
+   * A portfolio holding's purchase date (YYYY-MM-DD), its currency, and the
+   * rate its cost was bought at (one unit of `currency` in `costFxCurrency`).
+   * Null when no one has sent one; missing from a server that keeps none.
+   */
+  dateAcquired?: string | null;
+  currency?: string | null;
+  costFxRate?: number | null;
+  costFxCurrency?: string | null;
+  addedBy: string;
+  addedAt: string;
+  updatedAt: string;
+}
+
+type TeamCollectionChange =
+  | { change: "created"; collection: TeamCollection }
+  | { change: "updated"; collection: TeamCollection }
+  | { change: "deleted"; collectionId: string }
+  | { change: "item-added" | "item-updated" | "item-removed"; collectionId: string; item: TeamCollectionItem };
+
+export type TeamCollectionEvent = TeamCollectionChange & { teamId: string; actorId: string };
+
+// Team views and plugin state
+
+export interface TeamView {
+  id: string;
+  teamId: string;
+  name: string;
+  revision: number;
+  spec: Record<string, unknown>;
+  createdBy: string;
+  author: { username: string | null; displayName: string };
+  createdAt: string;
+  updatedAt: string;
+  publishedAt: string;
+}
+
+export type TeamViewEvent =
+  | { teamId: string; actorId: string; view: TeamView }
+  | { teamId: string; actorId: string; viewId: string };
+
+export interface TeamPluginStateEntry {
+  teamId: string;
+  pluginId: string;
+  key: string;
+  value: unknown;
+  revision: number;
+  updatedBy: string;
+  updatedAt: string;
+}
+
+export type TeamPluginStateEvent =
+  | { teamId: string; actorId: string; state: TeamPluginStateEntry }
+  | { teamId: string; actorId: string; pluginId: string; key: string; deleted: true };