gloomberb 0.11.3 → 0.13.1

package/src/api-client/index.ts

@@ -9,7 +9,9 @@ import { CloudApiSocket } from "./socket";
 import type {
   CloudCdsParams,
   CloudCongressHouseParams,
+  CloudEarningsCallsParams,
   CloudFredSeriesParams,
+  CloudSearchParams,
   CloudSecFilingParams,
   CloudSecFilingsParams,
   CloudHistoryParams,
@@ -48,9 +50,19 @@ import type {
   CloudEquityDiagnosticResult,
   CloudCdsResponse,
   CloudFredSeriesPayload,
+  CloudShillerPayload,
   CloudYieldPointPayload,
   CloudCongressHousePayload,
+  CloudEarningsCallListPayload,
+  CloudEarningsTranscriptPayload,
   CloudNewsPayload,
+  CloudSavedSearch,
+  CloudSavedSearchInput,
+  CloudSearchDocType,
+  CloudSearchDocument,
+  CloudSearchDocumentResponse,
+  CloudSearchHit,
+  CloudSearchResponse,
   CloudSecContentResponse,
   CloudSecDocumentsResponse,
   CloudSecFilingsResponse,
@@ -92,6 +104,8 @@ const ASSIST_REQUEST_TIMEOUT_MS = 6_000;
 class GloomApiClient {
   private currentUser: AuthUser | null = null;
   private sessionChecked = false;
+  /** Last few session transitions, content-free, for app://auth. */
+  private authTrace: Array<{ at: number; event: string; token: boolean; user: string }> = [];
   private sessionRequest: Promise<AuthUser | null> | null = null;
   private readonly currentUserListeners = new Set<() => void>();
   private readonly transport = new CloudApiRequestTransport();
@@ -154,6 +168,7 @@ class GloomApiClient {
     const changed = this.transport.getSessionToken() !== token;
     this.sessionChecked = false;
     this.transport.setSessionToken(token);
+    this.traceAuth(changed ? "setSessionToken:changed" : "setSessionToken:same");
     if (!token) {
       this.currentUser = null;
       this.emitCurrentUserChange();
@@ -196,8 +211,58 @@ class GloomApiClient {
     return this.transport.hasSessionCredential() && !!this.currentUser?.emailVerified;
   }
 
+  /**
+   * What this client currently believes about its session, with no secrets.
+   * Exposed over remote control so a "shows my username but not my
+   * subscription" report can be answered from the running app instead of
+   * from guesses about it.
+   */
+  describeAuthState(): {
+    hasSessionCredential: boolean;
+    hasSessionToken: boolean;
+    sessionChecked: boolean;
+    sessionRequestInFlight: boolean;
+    trace: Array<{ at: number; event: string; token: boolean; user: string }>;
+    currentUser: {
+      id: string;
+      emailVerified: boolean;
+      plan: string | null;
+      effectivePlan: string | null;
+      trialEndsAt: string | null;
+    } | null;
+  } {
+    const user = this.currentUser;
+    return {
+      hasSessionCredential: this.transport.hasSessionCredential(),
+      hasSessionToken: !!this.transport.getSessionToken(),
+      sessionChecked: this.sessionChecked,
+      sessionRequestInFlight: !!this.sessionRequest,
+      trace: [...this.authTrace],
+      currentUser: user
+        ? {
+          id: user.id,
+          emailVerified: user.emailVerified === true,
+          plan: user.plan ?? null,
+          effectivePlan: user.effectivePlan ?? null,
+          trialEndsAt: user.trialEndsAt ?? null,
+        }
+        : null,
+    };
+  }
+
+  private traceAuth(event: string, user: AuthUser | null = this.currentUser): void {
+    this.authTrace.push({
+      at: Date.now(),
+      event,
+      token: !!this.transport.getSessionToken(),
+      user: user ? (user.emailVerified ? "verified" : "unverified") : "none",
+    });
+    if (this.authTrace.length > 24) this.authTrace.shift();
+  }
+
   private setCurrentUser(user: AuthUser | null): void {
     const changed = this.socketEntitlementKey(this.currentUser) !== this.socketEntitlementKey(user);
+    this.traceAuth("setCurrentUser", user);
     this.currentUser = user;
     this.socket.syncAuthState({ reconnect: changed });
     this.emitCurrentUserChange();
@@ -265,12 +330,20 @@ class GloomApiClient {
   }
 
   async getSession(): Promise<AuthUser | null> {
-    if (this.sessionRequest) return this.sessionRequest;
+    if (this.sessionRequest) {
+      this.traceAuth("getSession:joined-inflight");
+      return this.sessionRequest;
+    }
+    this.traceAuth("getSession:start");
     this.sessionRequest = this.auth.getSession();
     try {
       const user = await this.sessionRequest;
       this.sessionChecked = true;
+      this.traceAuth("getSession:done", user);
       return user;
+    } catch (error) {
+      this.traceAuth(`getSession:error:${error instanceof Error ? error.message.slice(0, 60) : "unknown"}`);
+      throw error;
     } finally {
       this.sessionRequest = null;
     }
@@ -289,8 +362,16 @@ class GloomApiClient {
   }
 
   /** Creates a Stripe checkout session for Cloud Pro; the URL opens in a browser. */
-  async createCloudCheckout(): Promise<{ url: string }> {
-    return this.request<{ url: string }>("/stripe/checkout", { method: "POST", body: JSON.stringify({}) });
+  async createCloudCheckout(returnTo?: string): Promise<{ url: string }> {
+    return this.request<{ url: string }>("/stripe/checkout", { method: "POST", body: JSON.stringify({ returnTo }) });
+  }
+
+  async recordResearchActivity(payload: {
+    event: import("./research-activity").ResearchActivity; eventId: string;
+    surface: "web" | "desktop" | "tui" | "cli"; anonymousId?: string;
+    attribution?: Record<string, string>; feature?: import("./research-activity").ResearchFeature;
+  }): Promise<void> {
+    await this.request("/activity/research", { method: "POST", body: JSON.stringify(payload) });
   }
 
   /** Stores a verified user's public terminal snapshot or pane handoff. */
@@ -640,6 +721,10 @@ class GloomApiClient {
     return this.data.getCloudFredSeries(seriesId, params);
   }
 
+  async getCloudShiller(): Promise<CloudShillerPayload> {
+    return this.data.getCloudShiller();
+  }
+
   async getCloudYieldCurve(): Promise<CloudYieldPointPayload[]> {
     return this.data.getCloudYieldCurve();
   }
@@ -652,6 +737,16 @@ class GloomApiClient {
     return this.data.getCloudCongressHouse(params);
   }
 
+  async getCloudEarningsCalls(
+    params: CloudEarningsCallsParams = {},
+  ): Promise<CloudEarningsCallListPayload> {
+    return this.data.getCloudEarningsCalls(params);
+  }
+
+  async getCloudEarningsTranscript(id: string): Promise<CloudEarningsTranscriptPayload> {
+    return this.data.getCloudEarningsTranscript(id);
+  }
+
   async getCloudSecFilings(params: CloudSecFilingsParams): Promise<CloudSecFilingsResponse> {
     return this.data.getCloudSecFilings(params);
   }
@@ -668,6 +763,47 @@ class GloomApiClient {
     return this.data.getCloudSec13F(path, params);
   }
 
+  async searchCloudDocuments(
+    params: CloudSearchParams,
+    options?: { signal?: AbortSignal },
+  ): Promise<CloudSearchResponse> {
+    return this.data.searchCloudDocuments(params, options);
+  }
+
+  async getCloudSearchDocument(
+    docType: CloudSearchDocType,
+    sourceId: string,
+    options?: { signal?: AbortSignal },
+  ): Promise<CloudSearchDocument> {
+    return this.data.getCloudSearchDocument(docType, sourceId, options);
+  }
+
+  async getCloudSavedSearches(options?: { signal?: AbortSignal }): Promise<CloudSavedSearch[]> {
+    return this.data.getCloudSavedSearches(options);
+  }
+
+  async createCloudSavedSearch(input: CloudSavedSearchInput): Promise<CloudSavedSearch> {
+    return this.data.createCloudSavedSearch(input);
+  }
+
+  async updateCloudSavedSearch(
+    id: string,
+    update: Partial<CloudSavedSearchInput>,
+  ): Promise<CloudSavedSearch> {
+    return this.data.updateCloudSavedSearch(id, update);
+  }
+
+  async deleteCloudSavedSearch(id: string): Promise<void> {
+    return this.data.deleteCloudSavedSearch(id);
+  }
+
+  async getCloudSavedSearchHits(
+    id: string,
+    options?: { signal?: AbortSignal },
+  ): Promise<CloudSearchHit[]> {
+    return this.data.getCloudSavedSearchHits(id, options);
+  }
+
   async getCloudNews(params: CloudNewsParams = {}): Promise<CloudNewsListResponse> {
     return this.data.getCloudNews(params);
   }

package/src/api-client/normalizers.ts

@@ -3,11 +3,50 @@ import type {
   ChatMessage,
   ChatNotification,
   ChatStateResponse,
+  CloudSavedSearch,
+  CloudSearchHit,
+  CloudSearchResponse,
   CloudTweetPayload,
   CloudTweetSearchResponse,
 } from "./types";
 import { normalizeTimestamp } from "../utils/timestamp";
 
+/**
+ * Saved-search writes answer with either the record itself or `{ search }`.
+ * Both shapes are accepted so a server-side envelope change cannot silently
+ * hand the pane an object with no `id`.
+ */
+export function normalizeSavedSearchResponse(response: unknown): CloudSavedSearch {
+  const envelope = response as { search?: CloudSavedSearch } | CloudSavedSearch | null;
+  const search = envelope && "search" in envelope && envelope.search
+    ? envelope.search
+    : envelope as CloudSavedSearch | null;
+  if (!search?.id) throw new Error("The saved search response was missing a record.");
+  return search;
+}
+
+export function normalizeSavedSearchHits(response: unknown): CloudSearchHit[] {
+  const hits = (response as { hits?: unknown } | null)?.hits;
+  return Array.isArray(hits) ? (hits as CloudSearchHit[]).map(normalizeSearchHit) : [];
+}
+
+/**
+ * A wire story or filing need not name an issuer, and the server sends `ticker:
+ * null` when it does not. Coerced to an empty string at the boundary so the
+ * declared `string` is true of every hit: consumers test it for truthiness,
+ * join it into search text, and hand it to a badge, and a null reaches each of
+ * those as an empty chip, the literal "null", or a crash.
+ */
+export function normalizeSearchHit(hit: CloudSearchHit): CloudSearchHit {
+  return hit.ticker ? hit : { ...hit, ticker: "" };
+}
+
+export function normalizeSearchResponse(response: CloudSearchResponse): CloudSearchResponse {
+  const hits = response.hits;
+  if (!Array.isArray(hits)) return { ...response, hits: [] };
+  return { ...response, hits: hits.map(normalizeSearchHit) };
+}
+
 export function normalizeChatMessage(message: ChatMessage): ChatMessage {
   return {
     ...message,

package/src/api-client/paths.ts

@@ -1,4 +1,4 @@
-import type { CloudTweetQueryType } from "./types";
+import type { CloudSearchDocType, CloudSearchSort, CloudTweetQueryType } from "./types";
 import { normalizeSymbol, publicTickerKey } from "../utils/exchanges";
 
 export type CloudHistoryParams = {
@@ -34,6 +34,14 @@ export type CloudCongressHouseParams = {
   refresh?: boolean;
 };
 
+export type CloudEarningsCallsParams = {
+  ticker?: string;
+  limit?: number;
+  offset?: number;
+  /** Include calls still working through the transcription pipeline. */
+  includePending?: boolean;
+};
+
 export type CloudNewsParams = {
   feed?: "latest" | "top" | "breaking" | "ticker" | "sector" | "topic";
   ticker?: string;
@@ -131,6 +139,10 @@ export function cloudHistoryPath(symbol: string, exchange: string, params: Cloud
   return appendQuery("/market/history", search);
 }
 
+export function cloudShillerPath(): string {
+  return "/cloud/econ/shiller";
+}
+
 export function cloudExchangeRatePath(fromCurrency: string): string {
   return appendQuery("/market/exchange-rate", new URLSearchParams({ fromCurrency }));
 }
@@ -181,6 +193,19 @@ export function cloudCongressHousePath(params: CloudCongressHouseParams = {}): s
   return appendQuery("/cloud/congress/house", search);
 }
 
+export function cloudEarningsCallsPath(params: CloudEarningsCallsParams = {}): string {
+  const search = new URLSearchParams();
+  if (params.ticker) search.set("ticker", params.ticker);
+  if (params.limit != null) search.set("limit", String(params.limit));
+  if (params.offset != null) search.set("offset", String(params.offset));
+  if (params.includePending) search.set("includePending", "true");
+  return appendQuery("/cloud/transcripts", search);
+}
+
+export function cloudEarningsTranscriptPath(id: string): string {
+  return `/cloud/transcripts/${encodeURIComponent(id)}`;
+}
+
 export function cloudSecFilingsPath(params: CloudSecFilingsParams): string {
   const search = new URLSearchParams({ ticker: params.ticker });
   if (params.limit != null) search.set("limit", String(params.limit));
@@ -218,6 +243,65 @@ export function cloudSec13FPath(path: string, params: Record<string, string | nu
   return appendQuery(`/cloud/sec/13f/${normalized}`, search);
 }
 
+export type CloudSearchParams = {
+  query: string;
+  tickers?: readonly string[];
+  docTypes?: readonly CloudSearchDocType[];
+  sources?: readonly string[];
+  /** Inclusive ISO date or timestamp bounds on `publishedAt`. */
+  from?: string;
+  to?: string;
+  sort?: CloudSearchSort;
+  limit?: number;
+  offset?: number;
+  /** Set false to skip the total-count pass when only the top hits are shown. */
+  count?: boolean;
+  /** One row per source document instead of one per matching chunk. */
+  distinct?: boolean;
+};
+
+function csvParam(values: readonly string[] | undefined): string | null {
+  if (!values) return null;
+  const cleaned = values.map((value) => value.trim()).filter((value) => value.length > 0);
+  return cleaned.length > 0 ? cleaned.join(",") : null;
+}
+
+export function cloudSearchPath(params: CloudSearchParams): string {
+  const search = new URLSearchParams({ q: params.query.trim() });
+  const tickers = csvParam(params.tickers?.map(normalizeSymbol));
+  if (tickers) search.set("tickers", tickers);
+  const docTypes = csvParam(params.docTypes);
+  if (docTypes) search.set("docTypes", docTypes);
+  const sources = csvParam(params.sources);
+  if (sources) search.set("sources", sources);
+  if (params.from) search.set("from", params.from);
+  if (params.to) search.set("to", params.to);
+  if (params.sort) search.set("sort", params.sort);
+  if (params.limit != null) search.set("limit", String(params.limit));
+  // Offset 0 is the default page, so sending it only lengthens the cache key.
+  if (params.offset) search.set("offset", String(params.offset));
+  // Counting is the server default, so only opting out is worth a parameter.
+  if (params.count === false) search.set("count", "false");
+  if (params.distinct) search.set("distinct", "true");
+  return appendQuery("/cloud/search", search);
+}
+
+export function cloudSearchDocumentPath(docType: CloudSearchDocType, sourceId: string): string {
+  return `/cloud/search/documents/${encodeURIComponent(docType)}/${encodeURIComponent(sourceId)}`;
+}
+
+export function cloudSavedSearchesPath(): string {
+  return "/cloud/search/saved";
+}
+
+export function cloudSavedSearchPath(id: string): string {
+  return `/cloud/search/saved/${encodeURIComponent(id)}`;
+}
+
+export function cloudSavedSearchHitsPath(id: string): string {
+  return `${cloudSavedSearchPath(id)}/hits`;
+}
+
 export function cloudNewsPath(params: CloudNewsParams = {}): string {
   const search = new URLSearchParams();
   if (params.feed) search.set("feed", params.feed);

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

@@ -0,0 +1,61 @@
+import { apiClient } from "./index";
+import { getCurrentPluginTarget } from "../plugins/current-target";
+
+export type ResearchActivity = "workspace_opened" | "research_viewed" | "ticker_saved" | "pro_feature_used" | "upgrade_intent";
+export type ResearchFeature = "overview" | "chart" | "financials" | "news" | "transcripts" | "search" | "research";
+const sent = new Set<string>();
+let anonymousId: string | undefined;
+let attribution: Record<string, string> = {};
+
+/** Hosted web analytics only. Native local use never creates an identifier. */
+export function initializeBrowserResearchActivity(): void {
+  try {
+    if (navigator.doNotTrack === "1" || (navigator as Navigator & { globalPrivacyControl?: boolean }).globalPrivacyControl) return;
+    const url = new URL(location.href);
+    const incoming = url.searchParams.get("_gloom");
+    const stored = localStorage.getItem("gloomberb.web.anonymous-id");
+    anonymousId = [incoming, stored].find((value) => value && /^[a-f0-9-]{36}$/.test(value)) ?? crypto.randomUUID();
+    localStorage.setItem("gloomberb.web.anonymous-id", anonymousId);
+    const keys = ["utm_source", "utm_medium", "utm_campaign", "utm_content", "utm_term", "twclid"];
+    const saved = JSON.parse(localStorage.getItem("gloomberb.web.attribution") ?? "{}");
+    const age = Date.now() - Date.parse(saved?.last_touch_at ?? "");
+    attribution = Number.isFinite(age) && age >= 0 && age < 30 * 24 * 60 * 60 * 1000 ? saved : {};
+    if (keys.some((key) => url.searchParams.has(key))) {
+      // A new campaign replaces the old click id instead of inheriting it.
+      attribution = { last_touch_at: new Date().toISOString() };
+      for (const key of keys) {
+        const value = url.searchParams.get(key);
+        if (value) attribution[key] = value.slice(0, 300);
+      }
+    }
+    localStorage.setItem("gloomberb.web.attribution", JSON.stringify(attribution));
+    url.searchParams.delete("_gloom");
+    history.replaceState(history.state, "", url.href);
+  } catch { /* Private browsing must still work. */ }
+}
+
+/** Counts milestones once per feature/session/account, never their content. */
+export function recordResearchActivity(event: ResearchActivity, feature?: ResearchFeature): void {
+  const target = getCurrentPluginTarget();
+  const user = apiClient.getCurrentUser();
+  if (target === "web" ? !anonymousId : !user) return;
+  const key = `${user?.id ?? "guest"}:${event}:${feature ?? ""}`;
+  if (sent.has(key)) return;
+  sent.add(key);
+  if (event !== "workspace_opened") recordResearchActivity("workspace_opened");
+  void apiClient.recordResearchActivity({ event, eventId: crypto.randomUUID(),
+    surface: target === "desktop" ? "desktop" : target,
+    anonymousId: target === "web" ? anonymousId : undefined,
+    attribution: target === "web" ? attribution : undefined, feature,
+  }).catch(() => { sent.delete(key); });
+}
+
+export function researchUpgradeUrl(returnTo?: string): string {
+  const url = new URL("https://gloom.sh/cloud?upgrade=pro");
+  if (returnTo) url.searchParams.set("returnTo", returnTo);
+  if (anonymousId) url.searchParams.set("_gloom", anonymousId);
+  for (const [key, value] of Object.entries(attribution)) {
+    if (/^(utm_(source|medium|campaign|content|term)|twclid)$/.test(key)) url.searchParams.set(key, value);
+  }
+  return url.href;
+}

package/src/api-client/types.ts

@@ -346,6 +346,28 @@ export interface CloudFredSeriesPayload {
   info: CloudFredSeriesInfoPayload | 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.
+ */
+export 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;
@@ -466,6 +488,181 @@ export interface CloudCongressHousePayload {
   members: CloudCongressMemberPayload[];
 }
 
+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;
+}
+
+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;
+}
+
+export interface CloudTranscriptTurnPayload {
+  speaker: string;
+  role?: string;
+  company?: string;
+  text: string;
+  isQa: boolean;
+  /** Offset into the recording; null when the company published the transcript as a document. */
+  startSeconds: number | null;
+}
+
+export 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[];
+  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;
+}
+
+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;
+}
+
+export 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[];
+}
+
 export interface CloudSecFilingPayload {
   accessionNumber: string;
   form: string;