gloomberb 0.17.5 → 0.18.0

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

@@ -32,14 +32,27 @@ export interface FuturesContractTermsPayload {
   settlement: { price: number; date: string } | null
   /**
    * For a continuous symbol (CL=F) or a front generic: the nearest contract
-   * still trading when the symbol has rolled past it to the most active one,
-   * with its last trade; null when it prices the nearest itself. Absent from
+   * still trading once the symbol has rolled past it on its roll date, with
+   * its last trade; null when it prices the nearest itself. Absent from
    * servers that do not send it.
    */
   nearest?: FuturesNearestContract | null
+  /**
+   * For a continuous symbol or a generic: how it rolls ("1 day before last
+   * trade") and the first session it is on the next contract; the date is
+   * null under the open interest switch. Absent from older servers.
+   */
+  roll?: { label: string; date: string | null } | null
+  /**
+   * The root's front contract (what its continuous symbol and first generic
+   * price) when the symbol prices another one (NGF27, NG2); null on the front.
+   */
+  front?: FuturesNearestContract | null
+  /** The contract that traded the most on the root's newest session with volumes: the day's volume alone. */
+  mostActive?: FuturesMostActiveContract | null
 }
 
-/** The nearest contract still trading, which a continuous symbol has rolled past (CLX26 under CL=F on Dec). */
+/** A listed contract by its code, as the quote endpoints take it (CLX26.NYM), and its last trade. */
 interface FuturesNearestContract {
   contract: string
   contractSymbol: string
@@ -48,6 +61,16 @@ interface FuturesNearestContract {
   lastTrade: string | null
 }
 
+/** The most active contract: its volume on that session (`date`). */
+interface FuturesMostActiveContract {
+  contract: string
+  contractSymbol: string
+  /** YYYY-MM */
+  deliveryMonth: string
+  volume: number
+  date: string
+}
+
 /** Gloom Cloud futures prices retain provider denomination and explicit quote units. */
 export interface FuturesContract {
   symbol: string

package/src/api-client/geo.ts

@@ -9,6 +9,8 @@
  * `geo_unavailable`. A layer that cannot serve still answers 200 with an
  * empty body and its `status` and `statusNote`.
  */
+import { logFailure } from "../utils/log-failure";
+
 type Lon = number;
 type Lat = number;
 
@@ -79,6 +81,12 @@ export interface GeoLayerInfo {
   status: GeoLayerStatus;
   /** Short plain words, never a source name. */
   statusNote?: string;
+  /**
+   * Who published the data, as a reader cites it (`IMF PortWatch`), when the
+   * server names one: a public institution, never a vendor. Reports cite it
+   * as their source and publisher; absent, they cite Gloom Cloud.
+   */
+  publisher?: string;
   access: "free" | "pro";
   /** The entity table's columns; the first is the label. */
   columns: GeoColumn[];
@@ -162,6 +170,8 @@ export interface GeoSeriesPayload {
   /** [YYYY-MM-DD, value], oldest first. */
   points: [string, number][];
   asOf: string | null;
+  /** Its layer's `publisher`, when the server names one. */
+  publisher?: string;
 }
 
 /** West, south, east, north in degrees. */
@@ -329,7 +339,7 @@ export async function loadGeoCatalog(
     catalogInFlight = request<unknown>("layers")
       .then(normalizeCatalog)
       // A missing route or a refusal is an answer; a network blip is too, for a while.
-      .catch(() => null)
+      .catch(logFailure("cloud-geo", "Geo catalog request failed", null))
       .then((payload) => {
         catalogEntry = { at: options.now ?? Date.now(), payload };
         return payload;

package/src/api-client/index.ts

@@ -1,3 +1,4 @@
+import { logFailure } from "../utils/log-failure";
 import {
   isMarketplaceLayoutId,
   parseMarketplaceLayoutEntry,
@@ -420,6 +421,19 @@ class GloomApiClient {
     return this.request<{ url: string }>("/stripe/portal", { method: "POST", body: JSON.stringify({}) });
   }
 
+  /**
+   * Ends the Pro trial and Pro now, unbilled. Call it only once the person
+   * confirmed a warning that says so. `endedNow` is false when the server
+   * scheduled the cancel at the period end instead: the subscription was no
+   * longer in its trial, or the server predates ending a trial early.
+   */
+  async endCloudTrial(): Promise<{ canceled: boolean; endedNow?: boolean }> {
+    return this.request<{ canceled: boolean; endedNow?: boolean }>("/stripe/subscription/cancel", {
+      method: "POST",
+      body: JSON.stringify({ endTrialNow: true }),
+    });
+  }
+
   /**
    * Asks which arm of an app experiment this account or web visitor is in, at the
    * moment it would show. The API counts the answer as the exposure.
@@ -636,8 +650,9 @@ class GloomApiClient {
   reportCommandSearch(report: CommandSearchReport): void {
     try {
       if (!this.isSignedIn()) return;
-      void this.telemetry.reportCommandSearch(report).catch(() => {});
-    } catch {
+      void this.telemetry.reportCommandSearch(report).catch(logFailure("cloud-telemetry", "Command search report failed"));
+    } catch (error) {
+      logFailure("cloud-telemetry", "Command search reporting failed")(error);
       /* A report must never get in the way of the command bar. */
     }
   }
@@ -645,6 +660,8 @@ class GloomApiClient {
   getChannels = this.chat.getChannels.bind(this.chat);
   getChatPresence = this.chat.getPresence.bind(this.chat);
   getChatState = this.chat.getState.bind(this.chat);
+  getChatMentionCandidates = this.chat.getMentionCandidates.bind(this.chat);
+  subscribeChatMentionCandidatesChanged = this.chat.subscribeMentionCandidatesChanged.bind(this.chat);
   updateChatChannelState = this.chat.updateChannelState.bind(this.chat);
   markChatNotificationsDelivered = this.chat.markNotificationsDelivered.bind(this.chat);
   getUnseenChatNotificationIds = this.chat.getUnseenNotificationIds.bind(this.chat);
@@ -756,9 +773,12 @@ class GloomApiClient {
   getCloudCorporateActions = this.data.getCloudCorporateActions.bind(this.data);
   getCloudTickerChanges = this.data.getCloudTickerChanges.bind(this.data);
   getCloudOrganizationTickers = this.data.getCloudOrganizationTickers.bind(this.data);
+  getCloudTickerChangesBatch = this.data.getCloudTickerChangesBatch.bind(this.data);
+  searchInstrumentsBatch = this.data.searchInstrumentsBatch.bind(this.data);
   getCloudHistory = this.data.getCloudHistory.bind(this.data);
   getCloudExchangeRate = this.data.getCloudExchangeRate.bind(this.data);
   getCloudEconomicCalendar = this.data.getCloudEconomicCalendar.bind(this.data);
+  getCloudEconomicCalendarFrom = this.data.getCloudEconomicCalendarFrom.bind(this.data);
   getCloudMacroReleaseDays = this.data.getCloudMacroReleaseDays.bind(this.data);
   getCloudEquityDiagnostic = this.data.getCloudEquityDiagnostic.bind(this.data);
   getCloudEarningsCalendar = this.data.getCloudEarningsCalendar.bind(this.data);
@@ -766,6 +786,8 @@ class GloomApiClient {
   getCloudFredSeries = this.data.getCloudFredSeries.bind(this.data);
   getCloudFredSeriesCatalog = this.data.getCloudFredSeriesCatalog.bind(this.data);
   getCloudCryptoMarkets = this.data.getCloudCryptoMarkets.bind(this.data);
+  getCloudStablecoinSupply = this.data.getCloudStablecoinSupply.bind(this.data);
+  getCloudStablecoinSupplyHistory = this.data.getCloudStablecoinSupplyHistory.bind(this.data);
   getCloudCentralBankRates = this.data.getCloudCentralBankRates.bind(this.data);
   getMobileAlertHistory = this.data.getMobileAlertHistory.bind(this.data);
   getScannerFlowHistory = this.data.getScannerFlowHistory.bind(this.data);
@@ -775,10 +797,12 @@ class GloomApiClient {
   getMemberFunds = this.data.getMemberFunds.bind(this.data);
   getFundMembers = this.data.getFundMembers.bind(this.data);
   getFundChanges = this.data.getFundChanges.bind(this.data);
+  getFundFacts = this.data.getFundFacts.bind(this.data);
   getCloudThemes = this.data.getCloudThemes.bind(this.data);
   getCloudThemeMembers = this.data.getCloudThemeMembers.bind(this.data);
   impliedVolatility = this.data.impliedVolatility.bind(this.data);
   optionsPositioning = this.data.optionsPositioning.bind(this.data);
+  getCloudBankFigures = this.data.getCloudBankFigures.bind(this.data);
   getCloudDebtMaturities = this.data.getCloudDebtMaturities.bind(this.data);
   getCloudRevenueBreakdown = this.data.getCloudRevenueBreakdown.bind(this.data);
   getCloudMnaDeals = this.data.getCloudMnaDeals.bind(this.data);
@@ -826,6 +850,8 @@ class GloomApiClient {
   getCloudAward = this.data.getCloudAward.bind(this.data);
   getCloudDoeBoard = this.data.getCloudDoeBoard.bind(this.data);
   getCloudDoePrices = this.data.getCloudDoePrices.bind(this.data);
+  getCloudJodiBoard = this.data.getCloudJodiBoard.bind(this.data);
+  getCloudPsdBoard = this.data.getCloudPsdBoard.bind(this.data);
   getCloudAttention = this.data.getCloudAttention.bind(this.data);
   getCloudPowerBoard = this.data.getCloudPowerBoard.bind(this.data);
   getCloudPowerHistory = this.data.getCloudPowerHistory.bind(this.data);
@@ -857,6 +883,7 @@ class GloomApiClient {
   getCloudJobsMovers = this.data.getCloudJobsMovers.bind(this.data);
   getCloudEarningsCalls = this.data.getCloudEarningsCalls.bind(this.data);
   getCloudEarningsTranscript = this.data.getCloudEarningsTranscript.bind(this.data);
+  getCloudEarningsCallAudio = this.data.getCloudEarningsCallAudio.bind(this.data);
   getProxyStatements = this.data.getProxyStatements.bind(this.data);
   getProxyStatement = this.data.getProxyStatement.bind(this.data);
   getFilingEvents = this.data.getFilingEvents.bind(this.data);
@@ -864,6 +891,7 @@ class GloomApiClient {
   getRiskReport = this.data.getRiskReport.bind(this.data);
   getCloudSecFilings = this.data.getCloudSecFilings.bind(this.data);
   getCloudSecBeneficialOwners = this.data.getCloudSecBeneficialOwners.bind(this.data);
+  getCloudSecInsiderSignals = this.data.getCloudSecInsiderSignals.bind(this.data);
   getCloudSecFilingDocuments = this.data.getCloudSecFilingDocuments.bind(this.data);
   getCloudSecFilingContent = this.data.getCloudSecFilingContent.bind(this.data);
   getCloudSec13F = this.data.getCloudSec13F.bind(this.data);

package/src/api-client/insider-signals.ts

@@ -0,0 +1,159 @@
+/**
+ * Companies ranked by recent open-market insider buying or selling, as
+ * `GET /cloud/sec/insider-signals` returns them. Buying counts Form 4
+ * purchases (code P), selling the sales (code S) an insider chose to make: a
+ * Rule 10b5-1 plan's, a sell-to-cover's, an option exercise's and an
+ * offering's are left out. Only officers, directors and 10% owners count.
+ * Dates are `YYYY-MM-DD`, values USD.
+ */
+
+export type InsiderSignalRole =
+  | "CEO"
+  | "CFO"
+  | "COO"
+  | "President"
+  | "Chair"
+  | "Officer"
+  | "Director"
+  | "10% owner";
+
+/** Purchases or sales. */
+export type InsiderSignalSide = "buy" | "sell";
+/** Whose trades a ranking reads: everyone, chief officers and other officers, directors, or 10% owners. */
+export type InsiderSignalRoleGroup = "all" | "officers" | "directors" | "owners";
+/** Market value: micro under $300M, small to $2B, mid to $10B, large above. */
+export type InsiderSignalCap = "micro" | "small" | "mid" | "large";
+
+/**
+ * One insider in a row: what they traded in the window. On the sell side
+ * `buys` and `lastBuy` are the days they sold and the last of them.
+ */
+export interface InsiderSignalBuyer {
+  name: string;
+  role: InsiderSignalRole;
+  value: number;
+  /** Days the insider traded in the window. */
+  buys: number;
+  lastBuy: string;
+  /** Left out by servers that predate selling. */
+  shares?: number;
+  /** The holding's change in the window, percent: positive bought, negative sold; null without balances. */
+  stakeChangePct?: number | null;
+  /** Opened a position: held nothing before, or a holding worth under $10K or under 1% of what was bought. */
+  newPosition?: boolean;
+  /** Sold every share and unit the forms report. */
+  exited?: boolean;
+  /**
+   * The insider's trade days in the 90 days ending on their last, the days
+   * before the window included: their nth buy (sale), 1 for a lone day. Null
+   * when they traded both ways. Left out by servers that predate it.
+   */
+  repeatBuys?: number | null;
+  /**
+   * Their largest day in the window against their usual size, to a tenth and
+   * at most 100 ("100x+"); null without enough history, or when they traded
+   * both ways. Left out by servers that predate it.
+   */
+  usualRatio?: number | null;
+  /** Bought and sold in the window: the row counts the net, on the side it falls. */
+  twoWay?: boolean;
+}
+
+/** One fact behind a row, structured, strongest first. */
+interface InsiderWhySignal {
+  kind: "cluster" | "repeat" | "usual" | "stake" | "new" | "exited" | "size" | "both";
+  /** cluster: insiders; repeat: the ordinal; usual: the multiple; stake: percent, negative sold; new, exited, both: 1; size: dollars. */
+  value: number;
+  /** A few characters: "3 insiders", "4th buy", "5x usual", "+56%", "6x stake", "NEW", "both ways". */
+  text: string;
+  /** The insider it is about; null for the company's (a cluster). */
+  insider: { name: string; role: InsiderSignalRole } | null;
+}
+
+export interface InsiderSignalRow {
+  ticker: string;
+  issuerCik: string;
+  company: string;
+  /** 0 to 100. */
+  score: number;
+  /** Why the company ranks, strongest first, in plain words. */
+  reasons: string[];
+  /** Distinct insiders who traded in the window. */
+  insiders: number;
+  /** Insider trade days in the window. */
+  buys: number;
+  value: number;
+  shares: number;
+  firstBuy: string;
+  lastBuy: string;
+  lastFiled: string;
+  signals: {
+    clusterInsiders: number;
+    repeatBuys: number;
+    usualRatio: number | null;
+    stakeIncreasePct: number | null;
+    newPosition: boolean;
+    /** Left out by servers that predate selling. */
+    stakeChangePct?: number | null;
+    exited?: boolean;
+  };
+  /** The reasons' facts, structured; left out by servers that predate them. */
+  whySignals?: InsiderWhySignal[];
+  /** The insiders who traded, largest first, up to ten. */
+  buyers: InsiderSignalBuyer[];
+  /** Stored market value, USD; null when the server has none for it. */
+  marketCap?: number | null;
+}
+
+interface InsiderSignalsFilters {
+  role: InsiderSignalRoleGroup;
+  minValue: number;
+  cluster: boolean;
+  position: "new" | "exited" | null;
+  cap: InsiderSignalCap | null;
+}
+
+export interface InsiderSignalsPayload {
+  /**
+   * The company asked for (`ticker`): `rows` is its row alone, with every
+   * insider, whatever its size. Absent for the ranking, and from a server
+   * that predates the question, which answers the ranking instead.
+   */
+  ticker?: string;
+  /** Left out by servers that predate selling: buying. */
+  side?: InsiderSignalSide;
+  /** Days of trading each row covers, ending `through`. */
+  window: number;
+  filters?: InsiderSignalsFilters;
+  /** Whether rows carry market values, so the cap filter can work. */
+  marketCaps?: "stored" | "unavailable";
+  through: string;
+  /** The newest filing day read. */
+  asOf: string | null;
+  /**
+   * Days whose filings have all been read. `missingDays`: weekdays since
+   * `from` the server no longer reads on its own and has not read whole, a gap
+   * an outage left (left out by servers that predate it).
+   */
+  coverage: { from: string | null; through: string | null; missingDays?: string[] };
+  rows: InsiderSignalRow[];
+}
+
+export interface CloudInsiderSignalsParams {
+  /** Buying unless told. */
+  side?: InsiderSignalSide;
+  /** Days, 1 to 90; the server reads 30 when left out. */
+  window?: number;
+  /** Rows, 1 to 200; the server reads 50 when left out. */
+  limit?: number;
+  role?: InsiderSignalRoleGroup;
+  /** USD the insiders traded in the window, at least. */
+  minValue?: number;
+  /** Only companies where two insiders or more traded within a span. */
+  cluster?: boolean;
+  /** "new" on the buy side, "exited" on the sell side. */
+  position?: "new" | "exited";
+  cap?: InsiderSignalCap;
+  /** One company instead of the ranking: its row, with every insider. */
+  ticker?: string;
+}

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

@@ -19,7 +19,7 @@ export interface ScreenerQuote {
   lastUpdated?: number;
   /** Session-fixed, so the price column reads its decimals from it rather than from each tick. */
   previousClose?: number;
-  /** The quote's sessions beside the live print the list ranks by, when the server sends them. */
+  /** The quote's sessions beside the live print the server ranked the row by, when the server sends them. */
   sessions?: CloudMoverSessionFields;
 }
 

package/src/api-client/normalizers.ts

@@ -134,6 +134,7 @@ export function normalizeChatMessage(message: ChatMessage): ChatMessage {
     if (paneLink) normalized.paneLink = paneLink;
     else delete normalized.paneLink;
   }
+  if ((message.announcement as unknown) !== true) delete normalized.announcement;
   return normalized;
 }
 
@@ -220,6 +221,7 @@ export function normalizeChatChannel(
     ...channel,
     kind: channel.kind ?? fallbackKind,
     created_at: normalizeTimestamp(channel.created_at),
+    ...(typeof channel.lastMessageAt === "string" ? { lastMessageAt: normalizeTimestamp(channel.lastMessageAt) } : {}),
     ...(channel.dmUser ? { dmUser: normalizeChatUser(channel.dmUser) } : {}),
     ...(Array.isArray(channel.members) ? { members: channel.members.map(normalizeChatUser) } : {}),
   };

package/src/api-client/paths.ts

@@ -7,6 +7,7 @@ import { isUsListingExchange, normalizeSymbol, parsePublicTickerKey, publicTicke
 import { nonUsSecListingVenue } from "../utils/sec";
 import type { HistoryRetention } from "../sources/history-retention";
 import type { CloudBeneficialOwnersParams } from "./beneficial-owners";
+import type { CloudInsiderSignalsParams } from "./insider-signals";
 import type { RevenueBreakdownView } from "./revenue-breakdown";
 
 export type CloudHistoryParams = {
@@ -245,6 +246,8 @@ export type CloudSecFilingsParams = {
   name?: string;
   limit?: number;
   offset?: number;
+  /** Only these forms, each with its amendment (`8-K` is also `8-K/A`). A server that predates the filter sends every form. */
+  forms?: readonly string[];
 };
 
 export type CloudSecFilingParams = {
@@ -360,6 +363,10 @@ export function cloudEarningsTranscriptPath(id: string): string {
   return `/cloud/transcripts/${encodeURIComponent(id)}`;
 }
 
+export function cloudEarningsCallAudioPath(id: string): string {
+  return `${cloudEarningsTranscriptPath(id)}/audio`;
+}
+
 /**
  * An issuer read's path: a US listing or a bare symbol keeps its US ticker
  * and sends nothing else; a listing abroad sends its bare symbol with its
@@ -428,10 +435,16 @@ export function cloudSecFilingsPath(params: CloudSecFilingsParams): string {
   });
   if (params.limit != null) search.set("limit", String(params.limit));
   if (params.offset != null) search.set("offset", String(params.offset));
+  if (params.forms?.length) search.set("form", params.forms.join(","));
   setListingAbroad(search, abroad);
   return appendQuery("/cloud/sec/filings", search);
 }
 
+/** A US-listed company's bank figures: SEC deposits and its lead bank's FDIC call report. */
+export function cloudBankFiguresPath(symbol: string): string {
+  return appendQuery("/cloud/bank-figures", new URLSearchParams({ symbol }));
+}
+
 /** Schedule 13D and 13G reports about the issuer behind `ticker`. */
 export function cloudSecBeneficialOwnersPath(params: CloudBeneficialOwnersParams): string {
   const abroad = listingAbroad(params.ticker, params.exchange, params.name);
@@ -444,6 +457,21 @@ export function cloudSecBeneficialOwnersPath(params: CloudBeneficialOwnersParams
   return appendQuery("/cloud/sec/beneficial-owners", search);
 }
 
+/** Companies ranked by recent open-market insider buying or selling. Defaults are left out of the query. */
+export function cloudSecInsiderSignalsPath(params: CloudInsiderSignalsParams = {}): string {
+  const search = new URLSearchParams();
+  if (params.side === "sell") search.set("side", "sell");
+  if (params.window != null) search.set("window", String(params.window));
+  if (params.limit != null) search.set("limit", String(params.limit));
+  if (params.role && params.role !== "all") search.set("role", params.role);
+  if (params.minValue) search.set("minValue", String(params.minValue));
+  if (params.cluster) search.set("cluster", "true");
+  if (params.position) search.set("position", params.position);
+  if (params.cap) search.set("cap", params.cap);
+  if (params.ticker) search.set("ticker", params.ticker);
+  return appendQuery("/cloud/sec/insider-signals", search);
+}
+
 export function cloudSecFilingDocumentsPath(
   params: CloudSecFilingParams,
 ): string {

package/src/api-client/request.ts

@@ -1,3 +1,4 @@
+import { logFailure } from "../utils/log-failure";
 import { httpFetch, isHttpFetchStreaming } from "../utils/http-transport";
 import { withDeadline } from "../utils/async-deadline";
 import {
@@ -148,7 +149,7 @@ export async function putWithRevision<T, Current extends { revision: number }>(
     });
   } catch (error) {
     if (!(error instanceof ApiRequestError) || error.status !== 412) throw error;
-    const current = await revision.loadCurrent().catch(() => null);
+    const current = await revision.loadCurrent().catch(logFailure("cloud-request", "Current revision request failed", null));
     throw new revision.conflict(error.message, current, current?.revision ?? (revision.expected ?? 0) + 1);
   }
 }
@@ -269,7 +270,7 @@ export class CloudApiRequestTransport {
         });
         throwIfRequestAborted(options.signal);
         if (!response.ok) {
-          const text = await response.text().catch(() => "");
+          const text = await response.text().catch(logFailure("cloud-request", "Error response body read failed", ""));
           throw new ApiRequestError(
             parseApiErrorMessage(text),
             response.status,
@@ -411,12 +412,19 @@ export class CloudApiRequestTransport {
     // layers, which a server without them answers with 404, or a ticker
     // change lookup: a note beside a quote, never one of the refused market
     // requests a lookup of many symbols waits out and retries. Nor the
-    // tickers beside a list of organization names, which say so in place.
+    // tickers beside a list of organization names, which say so in place,
+    // or a 13F filer's EDGAR filing list, whose report says it went unchecked.
+    // Nor the batched searches and ticker changes a list of symbols starts
+    // with: a service without them answers 404, and whatever they leave
+    // unanswered is looked up one symbol at a time, which is tracked.
     if (
       path.startsWith("/telemetry/")
       || path === "/assist/searches"
       || path === "/cloud/geo/layers"
+      || path.startsWith("/cloud/sec/13f/filer?")
       || path.startsWith("/market/ticker-changes?")
+      || path === "/market/ticker-changes/batch"
+      || path === "/market/search/batch"
       || path === "/market/organization-tickers"
     ) return request();
     return this.connectionHealth.track(

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

@@ -1,3 +1,4 @@
+import { logFailure } from "../utils/log-failure";
 import { apiClient } from "./index";
 import { getCurrentPluginTarget } from "../plugins/current-target";
 import type { DesktopDeepLinkBridge } from "../types/desktop-deeplink";
@@ -99,6 +100,7 @@ function cleanUrlValue(value: unknown): string | undefined {
     new URL(cleaned);
     return cleaned;
   } catch {
+    // Intentional ignore: Malformed attribution URLs are excluded from the payload.
     return undefined;
   }
 }
@@ -122,7 +124,7 @@ export function readStoredAttribution(stored: string | null, now = Date.now()):
     const parsed: unknown = JSON.parse(stored ?? "{}");
     if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) saved = parsed as Record<string, unknown>;
   } catch {
-    /* Corrupt storage is the same as no storage. */
+    // Intentional ignore: Corrupt optional attribution is treated as absent.
   }
 
   const next: Record<string, string> = {};
@@ -170,6 +172,7 @@ export function carriesHandoff(href: string): boolean {
       FIRST_TOUCH_KEYS.some((key) => params.has(key))
     );
   } catch {
+    // Intentional ignore: Malformed links carry no usable attribution handoff.
     return false;
   }
 }
@@ -258,7 +261,7 @@ export function initializeBrowserResearchActivity(): void {
     stripHandoffParams(url);
     history.replaceState(history.state, "", url.href);
   } catch {
-    /* Private browsing must still work. */
+    // Intentional ignore: Private browsing may deny optional attribution storage.
   }
 }
 
@@ -275,7 +278,7 @@ export function initializeDesktopResearchActivity(storage: StorageLike = localSt
     anonymousId = stored && ANONYMOUS_ID.test(stored) ? stored : undefined;
     attribution = readStoredAttribution(storage.getItem(ATTRIBUTION_STORAGE_KEY));
   } catch {
-    /* A read-only profile still runs the app. */
+    // Intentional ignore: A read-only profile may deny optional attribution storage.
   }
 }
 
@@ -297,6 +300,7 @@ export function adoptDesktopHandoff(href: string, storage: StorageLike = localSt
     storage.setItem(ATTRIBUTION_STORAGE_KEY, JSON.stringify(attribution));
     return true;
   } catch {
+    // Intentional ignore: Optional attribution storage may be unavailable; the deep link still opens.
     return false;
   }
 }
@@ -406,9 +410,10 @@ export function recordResearchActivity(
       if (!wallEvent) return;
       const views = wallSessionViews();
       views.add(key);
-      try { sessionStorage.setItem(WALL_VIEWS_SESSION_KEY, JSON.stringify([...views])); } catch { /* Native sessions use the in-memory set. */ }
+      try { sessionStorage.setItem(WALL_VIEWS_SESSION_KEY, JSON.stringify([...views])); } catch { /* Intentional ignore: Native sessions retain wall views in the in-memory set. */ }
     })
-    .catch(() => {
+    .catch((error) => {
+      logFailure("cloud-telemetry", "Research activity request failed")(error);
       sent.delete(key);
     });
 }
@@ -432,7 +437,8 @@ export function recordResearchTabView(tabId: string, fromExternalPlugin: boolean
 export function identifyResearchUser(): void {
   try {
     recordResearchActivity("workspace_opened");
-  } catch {
+  } catch (error) {
+    logFailure("cloud-telemetry", "Research identity reporting failed")(error);
     /* Analytics never blocks sign-in. */
   }
 }
@@ -444,6 +450,7 @@ function webExperimentAttribution(): { experiments?: string } {
     const experiments = storedExperimentAssignments(localStorage);
     return experiments ? { experiments } : {};
   } catch {
+    // Intentional ignore: Unavailable optional storage contributes no experiment attribution.
     return {};
   }
 }
@@ -499,7 +506,7 @@ function wallExperimentContext(): WallExperimentContext {
   try {
     if (surface === "web") local = localStorage;
     if (surface === "web" || surface === "desktop") session = sessionStorage;
-  } catch { /* Native and private sessions keep their answer in memory. */ }
+  } catch { /* Intentional ignore: Native and private sessions keep experiment answers in memory. */ }
   return {
     surface,
     accountId: user?.id,
@@ -516,7 +523,7 @@ function wallSessionViews(): Set<string> {
   try {
     const saved: unknown = JSON.parse(sessionStorage.getItem(WALL_VIEWS_SESSION_KEY) ?? "[]");
     if (Array.isArray(saved)) return new Set(saved.filter((value): value is string => typeof value === "string"));
-  } catch { /* Native sessions use the in-memory set. */ }
+  } catch { /* Intentional ignore: Native sessions retain wall views in the in-memory set. */ }
   return new Set();
 }
 

package/src/api-client/socket.ts

@@ -1,3 +1,4 @@
+import { logFailure } from "../utils/log-failure";
 import type { TapeFeedEvent } from "./tape";
 import type {
   AuthUser,
@@ -109,6 +110,7 @@ export class CloudApiSocket {
   private reconnectDelayMs = 1000;
 
   private readonly channelListeners = new Map<string, Set<ChannelListener>>();
+  private readonly chatMentionCandidatesListeners = new Set<() => void>();
   private readonly chatNotificationListeners =
     new Set<ChatNotificationListener>();
   private readonly chatChannelStateListeners =
@@ -187,7 +189,7 @@ export class CloudApiSocket {
     try {
       ws?.close();
     } catch {
-      // ignore closed sockets
+      // Intentional ignore: Closing an already closed socket needs no further cleanup.
     }
   }
 
@@ -254,6 +256,11 @@ export class CloudApiSocket {
     };
   }
 
+  subscribeChatMentionCandidatesChanged(listener: () => void): () => void {
+    this.chatMentionCandidatesListeners.add(listener);
+    return () => { this.chatMentionCandidatesListeners.delete(listener); };
+  }
+
   /**
    * The reader's read state or mute changed on another device or window. Like
    * notifications, it never opens the socket by itself.
@@ -306,7 +313,8 @@ export class CloudApiSocket {
     try {
       this.ws.send(JSON.stringify(payload));
       return true;
-    } catch {
+    } catch (error) {
+      logFailure("cloud-socket", "WebSocket frame send failed")(error);
       return false;
     }
   }
@@ -551,7 +559,8 @@ export class CloudApiSocket {
     let parsed: any;
     try {
       parsed = JSON.parse(raw);
-    } catch {
+    } catch (error) {
+      logFailure("cloud-socket", "WebSocket message decoding failed")(error);
       return;
     }
 
@@ -631,6 +640,10 @@ export class CloudApiSocket {
       return;
     }
 
+    if (parsed?.type === "chat.mentions_changed") {
+      for (const listener of this.chatMentionCandidatesListeners) listener();
+      return;
+    }
     if (parsed?.type === "chat.channel_state") {
       const state = normalizeChatChannelStateFrame(parsed.data);
       if (state) {