gloomberb 0.10.5 → 0.11.0

package/README.md

@@ -106,6 +106,7 @@ Open command mode with `Ctrl+P`, then type a command. Press `` ` `` to open tick
 | `TOP` | Ranked market stories |
 | `HM` | Market heatmap |
 | `MOST` | Market movers |
+| `HILO` | New highs and new lows |
 | `PF` | Portfolios and watchlists |
 | `KELLY AAPL` | Position sizing |
 | `HELP` | Full in-app shortcut list |
@@ -113,9 +114,19 @@ Open command mode with `Ctrl+P`, then type a command. Press `` ` `` to open tick
 ## What It Does
 
 - Research companies with quotes, charts, financials, filings, holders, insiders, options, analyst ratings, events, and relative valuation.
-- Follow markets with top stories, breaking news, sector feeds, Substack subscriptions, global indices, FX, macro events, yield curves, market movers, and fear/greed.
+- Follow markets with top stories, breaking news, sector feeds, Substack subscriptions, global indices, futures, FX, macro events, yield curves, Treasury auctions, market movers, new-high/new-low and options-flow scanners, and fear/greed.
 - Track portfolios and watchlists, connect brokers, set alerts, keep notes, run AI screens, browse prediction markets, and use Gloom Cloud chat.
 
+### Broker position sync
+
+Use **New Portfolio** or **Add Broker Account** to connect a broker. Gloomberb can import positions from Interactive Brokers, Public, Robinhood, and SimpleFIN.
+
+- Robinhood opens a browser sign-in page. Gloomberb uses only the read-only account and equity-position tools from the Robinhood Trading MCP server.
+- Public needs an API secret from Public API settings. Gloomberb creates a short-lived access token and uses only the account and portfolio endpoints.
+- SimpleFIN needs a one-time setup token from SimpleFIN Bridge. Gloomberb exchanges the token and imports only accounts that contain holdings.
+
+Gloomberb saves the connection data on the local device. It does not include this data in Gloom Cloud synchronization. A later position sync updates the managed portfolios and removes positions that the broker no longer reports.
+
 ## CLI
 
 Running `gloomberb` with no arguments launches the terminal UI. Normal commands run through a headless CLI path; use `gloomberb launch-ui` when a script should explicitly open the UI.
@@ -199,6 +210,7 @@ Use `HELP` inside Gloomberb for the live shortcut list. The common command-bar p
 | `DES <ticker>` / `T <ticker>` | Security details for a ticker |
 | `FA <ticker>` | Financial statement view |
 | `G <series>` | Custom chart composer |
+| `CAT [query]` | Browse and search chartable series |
 | `GP <ticker>` | Price chart |
 | `GIP <ticker>` | Intraday price chart |
 | `HP <ticker>` | Historical OHLCV prices |
@@ -214,7 +226,10 @@ Use `HELP` inside Gloomberb for the live shortcut list. The common command-bar p
 | `ANR <ticker>` | Analyst targets and ratings |
 | `SEC <ticker>` | SEC filings and company disclosures |
 | `OMON <ticker>` | Options monitor |
+| `OVME` | Black-Scholes option calculator with Greeks and implied volatility |
 | `HDS <ticker>` | Institutional holders |
+| `DVD <ticker>` | Dividend yield and history |
+| `SI <ticker>` | Short interest |
 | `13F [fund/ticker/CIK]` | 13F fund filings and holdings |
 | `INS <ticker>` | Insider activity |
 | `EVT <ticker>` | Corporate actions, earnings, and estimates |
@@ -222,7 +237,7 @@ Use `HELP` inside Gloomberb for the live shortcut list. The common command-bar p
 
 ### Chart Composer
 
-`G`, `GP`, `GIP`, `CMP`, `GF`, and `GE` all open the same chart composer with different starting presets. A custom expression can mix unrelated data sources on one synchronized timeline:
+`G`, `GP`, `GIP`, `CMP`, `GF`, and `GE` all open the same chart composer with different starting presets. `CAT` opens a searchable catalog of those chartable series so you can graph one without typing the expression. A custom expression can mix unrelated data sources on one synchronized timeline:
 
 ```text
 G AAPL:price, MSFT:revenue, FRED:CPIAUCSL
@@ -239,6 +254,8 @@ The toolbar controls preset or exact date ranges, intervals from one minute thro
 | `TOP` | Ranked market stories |
 | `HM` | Market heatmap for large US stocks and ETFs |
 | `MOST` | Top gainers, losers, most active, and trending tickers |
+| `HILO` | Session new highs and new lows with 30s/1m/5m momentum |
+| `FLOW` | Unusual options activity: sweeps, blocks, and large premium |
 | `PM <query>` | Polymarket and Kalshi prediction data |
 | `N` | News feed |
 | `CN <ticker>` | Ticker news |
@@ -249,9 +266,15 @@ The toolbar controls preset or exact date ranges, intervals from one minute thro
 | `TBO` | TheBuildout infrastructure intelligence |
 | `CG` | Congress trading disclosures |
 | `WEI` | Global equity indices |
+| `FUT` | Front-month futures across index, rates, energy, metals, grains, and FX |
 | `ECON` | Economic events and releases |
 | `GC` | Yield curve |
+| `AUCT` | Treasury auction results: high rate, bid-to-cover, indirect share, and size |
+| `VIX` | VIX 30-day/3-month implied-volatility curve |
+| `CRD` | Credit spreads |
 | `ERN` | Earnings calendar |
+| `IPO` | Upcoming and recent IPOs |
+| `HALT` | US trading halts with reason and resumption times |
 | `TV` | Live Bloomberg, CNBC, and Yahoo Finance television |
 | `BI` / `SP` | S&P 500 sector performance |
 | `FXC` | Major FX cross rates |
@@ -288,6 +311,10 @@ The toolbar controls preset or exact date ranges, intervals from one minute thro
 | `LANG <locale>` | Change interface language (`auto`, `en`, `es`, `zh-CN`, `zh-TW`, `ja`, or `ko`) |
 | `PL <plugin>` | Manage plugins |
 
+## Gloom Cloud sign-in
+
+Sign in with email and password, or pick `Log In with QR Code` from the command bar and scan the code with the Gloomberb mobile companion app to sign the terminal in without typing. The onboarding wizard offers the same QR option as the recommended path, with email and password as the alternative.
+
 ## Localized interface
 
 Gloomberb includes English, Spanish, Simplified Chinese, Traditional Chinese, Japanese, and Korean UI support. English remains the default fallback language.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gloomberb",
-  "version": "0.10.5",
+  "version": "0.11.0",
   "packageManager": "bun@1.3.11",
   "description": "Market research and portfolio tracker for the terminal",
   "module": "src/index.tsx",
@@ -60,12 +60,14 @@
   "dependencies": {
     "@earendil-works/pi-agent-core": "0.81.1",
     "@earendil-works/pi-ai": "0.81.1",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "@opentui/core": "^0.3.2",
     "@opentui/react": "^0.3.2",
     "@stoqey/ib": "^1.5.6",
     "@tanstack/react-virtual": "^3.14.2",
     "hls.js": "1.6.13",
     "jimp": "1.6.1",
+    "qrcode-generator": "^2.0.4",
     "react": "19.2.7",
     "react-dom": "19.2.7",
     "rxjs": "^7.8.2",

package/src/api-client/auth.ts

@@ -5,8 +5,11 @@ import type {
   AuthUser,
   BuildoutAccountResponse,
   BuildoutTokenResponse,
+  CloudBrowserHandoffResponse,
   CloudPricing,
   CloudVerificationResponse,
+  DeviceAuthStartResponse,
+  DeviceAuthTokenResponse,
   PersistedAuthUser,
 } from "./types";
 
@@ -86,6 +89,26 @@ export class CloudAuthApi {
     return result.user;
   }
 
+  /** Starts a QR / device sign-in; the mobile app approves the returned user code. */
+  async startDeviceSignIn(body: { clientName?: string; clientPlatform?: string }): Promise<DeviceAuthStartResponse> {
+    return this.options.request<DeviceAuthStartResponse>("/auth/device/start", {
+      method: "POST",
+      body: JSON.stringify(body),
+    });
+  }
+
+  /**
+   * Polls a pending device sign-in. Unlike the email flow, approval hands back
+   * a raw session token in the body instead of a Set-Cookie header; the caller
+   * installs it through the same path boot restoration uses.
+   */
+  async pollDeviceSignIn(deviceCode: string): Promise<DeviceAuthTokenResponse> {
+    return this.options.request<DeviceAuthTokenResponse>("/auth/device/token", {
+      method: "POST",
+      body: JSON.stringify({ deviceCode }),
+    });
+  }
+
   async signOut(): Promise<void> {
     try {
       await this.options.request("/auth/sign-out", { method: "POST" });
@@ -118,6 +141,17 @@ export class CloudAuthApi {
     });
   }
 
+  /**
+   * Creates a short-lived browser handoff for the captured native session.
+   * The server deliberately returns an opaque one-time URL, never the session cookie.
+   */
+  async createBrowserHandoff(): Promise<CloudBrowserHandoffResponse> {
+    return this.options.request<CloudBrowserHandoffResponse>("/cloud/auth/browser-handoff", {
+      method: "POST",
+      body: JSON.stringify({}),
+    });
+  }
+
   async getAccountProfile(): Promise<AccountProfile> {
     const result = await this.options.request<{ profile: AccountProfile }>("/account/profile", {
       method: "GET",

package/src/api-client/data.ts

@@ -22,6 +22,7 @@ import {
 } from "./paths";
 import type {
   CloudAnalystResearchPayload,
+  CloudShortInterestPayload,
   CloudCompanyProfile,
   CloudCongressHousePayload,
   CloudCorporateActionsPayload,
@@ -32,6 +33,8 @@ import type {
   CloudMarketBatchPayload,
   CloudMarketBatchTarget,
   CloudMarketResponse,
+  CloudMarketScreenerCategory,
+  CloudMarketScreenerPayload,
   CloudNewsListResponse,
   CloudNewsPayload,
   CloudOptionsChainPayload,
@@ -77,6 +80,22 @@ export class CloudDataApi {
     return this.postMarketBatch("/market/quotes/batch", targets, mode);
   }
 
+  async getCloudMarketScreener(
+    category: CloudMarketScreenerCategory,
+    count = 25,
+    mode: "cache-first" | "refresh" = "cache-first",
+  ): Promise<CloudMarketResponse<CloudMarketScreenerPayload>> {
+    const requestedCount = Number.isFinite(count) ? Math.round(count) : 25;
+    const params = new URLSearchParams({
+      category,
+      count: String(Math.max(1, Math.min(50, requestedCount))),
+      mode,
+    });
+    return this.request<CloudMarketResponse<CloudMarketScreenerPayload>>(
+      `/market/screener?${params.toString()}`,
+    );
+  }
+
   async getCloudOptionsChain(
     symbol: string,
     exchange?: string,
@@ -112,6 +131,12 @@ export class CloudDataApi {
     return this.requestMarketSymbol("/market/analyst", symbol, exchange);
   }
 
+  async getCloudShortInterest(symbol: string, years?: number): Promise<CloudMarketResponse<CloudShortInterestPayload>> {
+    const params = new URLSearchParams({ symbol: symbol.toUpperCase() });
+    if (years != null) params.set("years", String(years));
+    return this.request<CloudMarketResponse<CloudShortInterestPayload>>(`/market/short-interest?${params}`);
+  }
+
   async getCloudCorporateActions(symbol: string, exchange?: string): Promise<CloudMarketResponse<CloudCorporateActionsPayload>> {
     return this.requestMarketSymbol("/market/corporate-actions", symbol, exchange);
   }

package/src/api-client/index.test.ts

@@ -185,6 +185,28 @@ describe("apiClient auth cookies", () => {
     ]);
   });
 
+  test("creates a browser handoff with the captured session instead of exposing it in the URL", async () => {
+    let requestedUrl = "";
+    let requestedCookie: string | null = null;
+    apiClient.setSessionToken("desktop-session-token");
+    globalThis.fetch = mockFetch(async (input: Request | string | URL, init?: RequestInit) => {
+      requestedUrl = String(input);
+      requestedCookie = new Headers(init?.headers).get("Cookie");
+      return createResponse({
+        url: "https://api.gloom.sh/cloud/auth/browser-handoff?token=opaque-one-time-token",
+      });
+    });
+
+    const handoff = await apiClient.createBrowserHandoff();
+
+    expect(new URL(requestedUrl).pathname).toBe("/cloud/auth/browser-handoff");
+    expect(requestedCookie).toBe(
+      "__Secure-gloomberb.session_token=desktop-session-token; gloomberb.session_token=desktop-session-token",
+    );
+    expect(handoff.url).toContain("token=opaque-one-time-token");
+    expect(handoff.url).not.toContain("desktop-session-token");
+  });
+
   test("keeps cached identity when session refresh is rejected without a hard account-missing response", async () => {
     apiClient.setSessionToken("persisted-token.value");
     apiClient.restoreCachedUser(verifiedUser);
@@ -583,6 +605,65 @@ describe("apiClient quote socket", () => {
   });
 });
 
+describe("apiClient scanner subscriptions", () => {
+  test("subscribes once for many panes, fans out, replays the snapshot, and unsubscribes last", () => {
+    const sockets = installTestWebSocket();
+    const first: unknown[] = [];
+    const second: unknown[] = [];
+
+    const unsubscribeFirst = apiClient.subscribeScanner("hilo", (event) => first.push(event));
+    const socket = sockets[0]!;
+    socket.open();
+    expect(socket.sent).toContainEqual({ type: "scanner.subscribe", scanner: "hilo" });
+
+    const payload = {
+      status: "live",
+      asOf: 1,
+      windows: { s30: { highs: 1, lows: 0 }, m1: { highs: 2, lows: 1 }, m5: { highs: 3, lows: 2 } },
+      highs: [],
+      lows: [],
+    };
+    socket.receive({ type: "scanner.hilo", ...payload });
+
+    // A second pane must not open a second upstream subscription, and must not
+    // wait a tick for its first frame.
+    const subscribeCount = () => socket.sent.filter((message: any) => message.type === "scanner.subscribe").length;
+    const before = subscribeCount();
+    const unsubscribeSecond = apiClient.subscribeScanner("hilo", (event) => second.push(event));
+    expect(subscribeCount()).toBe(before);
+    expect(second).toEqual([{ type: "data", payload }]);
+
+    socket.receive({ type: "scanner.hilo", ...payload, asOf: 2 });
+    expect(first).toHaveLength(2);
+    expect(second).toHaveLength(2);
+
+    unsubscribeFirst();
+    expect(socket.sent).not.toContainEqual({ type: "scanner.unsubscribe", scanner: "hilo" });
+    unsubscribeSecond();
+    expect(socket.sent).toContainEqual({ type: "scanner.unsubscribe", scanner: "hilo" });
+  });
+
+  test("replays scanner subscriptions after a reconnect and surfaces denials", () => {
+    const sockets = installTestWebSocket();
+    const seen: unknown[] = [];
+    const unsubscribe = apiClient.subscribeScanner("flow", (event) => seen.push(event));
+
+    const socket = sockets[0]!;
+    socket.open();
+    socket.receive({ type: "scanner.denied", scanner: "flow", reason: "pro_required" });
+    expect(seen).toEqual([{ type: "denied", reason: "pro_required" }]);
+
+    jest.useFakeTimers();
+    socket.closeWith({ code: 1006, reason: "network" });
+    jest.runAllTimers();
+    const reconnected = sockets[1]!;
+    reconnected.open();
+    expect(reconnected.sent).toContainEqual({ type: "scanner.subscribe", scanner: "flow" });
+
+    unsubscribe();
+  });
+});
+
 describe("apiClient chat timestamps", () => {
   test("sends the before cursor when loading older chat messages", async () => {
     let requestedUrl = "";

package/src/api-client/index.ts

@@ -35,6 +35,8 @@ import type {
   CloudFundamentals,
   CloudHoldersPayload,
   CloudAnalystResearchPayload,
+  CloudShortInterestPayload,
+  CloudBrowserHandoffResponse,
   CloudCorporateActionsPayload,
   CloudPricePointPayload,
   CloudEconEventPayload,
@@ -47,11 +49,17 @@ import type {
   CloudMarketResponse,
   CloudMarketBatchTarget,
   CloudMarketBatchPayload,
+  CloudMarketScreenerCategory,
+  CloudMarketScreenerPayload,
   CloudVerificationResponse,
+  DeviceAuthStartResponse,
+  DeviceAuthTokenResponse,
   CloudRoundupPreviewResponse,
   CloudSyncPushResponse,
   CloudSyncSnapshotResponse,
   QuoteStreamTarget,
+  ScannerFeedEvent,
+  ScannerKind,
 } from "./types";
 import type { SyncSettings, SyncSnapshot } from "../sync/types";
 
@@ -205,6 +213,14 @@ class GloomApiClient {
     return this.auth.signIn(email, password);
   }
 
+  async startDeviceSignIn(body: { clientName?: string; clientPlatform?: string }): Promise<DeviceAuthStartResponse> {
+    return this.auth.startDeviceSignIn(body);
+  }
+
+  async pollDeviceSignIn(deviceCode: string): Promise<DeviceAuthTokenResponse> {
+    return this.auth.pollDeviceSignIn(deviceCode);
+  }
+
   async signOut(): Promise<void> {
     return this.auth.signOut();
   }
@@ -217,6 +233,10 @@ class GloomApiClient {
     return this.auth.sendVerification();
   }
 
+  async createBrowserHandoff(): Promise<CloudBrowserHandoffResponse> {
+    return this.auth.createBrowserHandoff();
+  }
+
   async getAccountProfile(): Promise<AccountProfile> {
     return this.auth.getAccountProfile();
   }
@@ -394,6 +414,11 @@ class GloomApiClient {
     return this.socket.subscribeQuotes(targets, onQuote);
   }
 
+  /** Subscribes to a shared scanner feed; all panes of one kind share one upstream subscription. */
+  subscribeScanner(scanner: ScannerKind, listener: (event: ScannerFeedEvent) => void): () => void {
+    return this.socket.subscribeScanner(scanner, listener);
+  }
+
   dispose(): void {
     this.socket.dispose();
   }
@@ -413,6 +438,14 @@ class GloomApiClient {
     return this.data.getCloudQuotesBatch(targets, mode);
   }
 
+  async getCloudMarketScreener(
+    category: CloudMarketScreenerCategory,
+    count = 25,
+    mode: "cache-first" | "refresh" = "cache-first",
+  ): Promise<CloudMarketResponse<CloudMarketScreenerPayload>> {
+    return this.data.getCloudMarketScreener(category, count, mode);
+  }
+
   async getCloudOptionsChain(
     symbol: string,
     exchange?: string,
@@ -444,6 +477,10 @@ class GloomApiClient {
     return this.data.getCloudHolders(symbol, exchange);
   }
 
+  async getCloudShortInterest(symbol: string, years?: number): Promise<CloudMarketResponse<CloudShortInterestPayload>> {
+    return this.data.getCloudShortInterest(symbol, years);
+  }
+
   async getCloudAnalystResearch(symbol: string, exchange?: string): Promise<CloudMarketResponse<CloudAnalystResearchPayload>> {
     return this.data.getCloudAnalystResearch(symbol, exchange);
   }

package/src/api-client/request.test.ts

@@ -1,4 +1,8 @@
 import { describe, expect, test } from "bun:test";
+import {
+  ConnectionHealthRegistry,
+  registerGloomCloudConnectionSources,
+} from "../core/connection-health";
 import { CloudApiRequestTransport } from "./request";
 
 function responseWithBody(body: () => Promise<string>): Response {
@@ -10,6 +14,32 @@ function responseWithBody(body: () => Promise<string>): Response {
   } as Response;
 }
 
+describe("CloudApiRequestTransport connection reporting", () => {
+  test("reports real FRED requests to both Gloom and FRED sources", async () => {
+    const health = new ConnectionHealthRegistry();
+    const dispose = registerGloomCloudConnectionSources(health);
+    const transport = new CloudApiRequestTransport({
+      connectionHealth: health,
+      fetchTransport: async () => responseWithBody(async () => JSON.stringify({ observations: [], info: null })),
+    });
+
+    await transport.request("/cloud/econ/series/VIXCLS?limit=120&sortOrder=desc");
+
+    expect(health.getSnapshot().sources.map((source) => ({
+      id: source.id,
+      status: source.status,
+      operation: source.lastOperation,
+    }))).toEqual([
+      { id: "gloom-cloud-http", status: "connected", operation: "GET /cloud/econ/series/VIXCLS" },
+      { id: "gloom-cloud-socket", status: "idle", operation: null },
+      { id: "gloom-cloud-fred", status: "connected", operation: "GET /cloud/econ/series/VIXCLS" },
+    ]);
+
+    dispose();
+    expect(health.getSnapshot().sources).toEqual([]);
+  });
+});
+
 describe("CloudApiRequestTransport market deadlines", () => {
   test("aborts when response headers never arrive", async () => {
     let signal: AbortSignal | null | undefined;

package/src/api-client/request.ts

@@ -1,6 +1,12 @@
 import { httpFetch } from "../utils/http-transport";
 import { withDeadline } from "../utils/async-deadline";
 import { ApiRequestError, parseApiErrorMessage } from "./errors";
+import {
+  connectionHealth,
+  GLOOM_CLOUD_FRED_CONNECTION_ID,
+  GLOOM_CLOUD_HTTP_CONNECTION_ID,
+  type ConnectionHealthRegistry,
+} from "../core/connection-health";
 
 const DEFAULT_API_URL = "https://api.gloom.sh";
 const DEFAULT_MARKET_REQUEST_TIMEOUT_MS = 10_000;
@@ -16,7 +22,12 @@ export function setCloudApiFetchTransport(transport: CloudApiFetchTransport | nu
   cloudApiFetchTransport = transport ?? httpFetch;
 }
 
+declare const __GLOOMBERB_API_URL__: string | undefined;
+
 function getCloudApiBaseUrl(): string {
+  // Browser bundles have no `process`; the build replaces this with a literal.
+  const bundled = typeof __GLOOMBERB_API_URL__ === "string" ? __GLOOMBERB_API_URL__ : "";
+  if (bundled) return bundled;
   if (typeof process === "undefined") {
     return DEFAULT_API_URL;
   }
@@ -34,15 +45,18 @@ export class CloudApiRequestTransport {
   private websocketToken: string | null = null;
   private readonly fetchTransport: CloudApiFetchTransport | null;
   private readonly marketRequestTimeoutMs: number;
+  private readonly connectionHealth: ConnectionHealthRegistry;
 
   readonly baseUrl = getCloudApiBaseUrl();
 
   constructor(options: {
     fetchTransport?: CloudApiFetchTransport;
     marketRequestTimeoutMs?: number;
+    connectionHealth?: ConnectionHealthRegistry;
   } = {}) {
     this.fetchTransport = options.fetchTransport ?? null;
     this.marketRequestTimeoutMs = options.marketRequestTimeoutMs ?? DEFAULT_MARKET_REQUEST_TIMEOUT_MS;
+    this.connectionHealth = options.connectionHealth ?? connectionHealth;
   }
 
   getSessionToken(): string | null {
@@ -116,27 +130,37 @@ export class CloudApiRequestTransport {
     this.setSessionCookieHeader(headers);
     headers.set("Origin", this.baseUrl);
 
-    const res = await (this.fetchTransport ?? cloudApiFetchTransport)(`${this.baseUrl}${path}`, {
-      ...options,
-      headers,
-      credentials: "include",
-    });
-    throwIfRequestAborted(options?.signal);
-    this.extractSessionCookie(res);
-    const text = await res.text();
-    throwIfRequestAborted(options?.signal);
-
-    if (!res.ok) {
-      const msg = parseApiErrorMessage(text);
-      throw new ApiRequestError(msg, res.status);
-    }
+    const operation = `${options?.method ?? "GET"} ${path.split("?")[0]}`;
+    const request = async () => {
+      const res = await (this.fetchTransport ?? cloudApiFetchTransport)(`${this.baseUrl}${path}`, {
+        ...options,
+        headers,
+        credentials: "include",
+      });
+      throwIfRequestAborted(options?.signal);
+      this.extractSessionCookie(res);
+      const text = await res.text();
+      throwIfRequestAborted(options?.signal);
+
+      if (!res.ok) {
+        const msg = parseApiErrorMessage(text);
+        throw new ApiRequestError(msg, res.status);
+      }
 
-    if (!text) return undefined as T;
-    const parsed = JSON.parse(text) as T & { token?: string };
-    if (typeof parsed?.token === "string" && parsed.token.length > 0) {
-      this.websocketToken = parsed.token;
-    }
-    return parsed as T;
+      if (!text) return undefined as T;
+      const parsed = JSON.parse(text) as T & { token?: string };
+      if (typeof parsed?.token === "string" && parsed.token.length > 0) {
+        this.websocketToken = parsed.token;
+      }
+      return parsed as T;
+    };
+    return this.connectionHealth.track(
+      GLOOM_CLOUD_HTTP_CONNECTION_ID,
+      operation,
+      () => path.startsWith("/cloud/econ/series/")
+        ? this.connectionHealth.track(GLOOM_CLOUD_FRED_CONNECTION_ID, operation, request)
+        : request(),
+    );
   }
 
   private extractSessionCookie(res: CloudApiResponse): void {

package/src/api-client/socket-health.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, test } from "bun:test";
+import {
+  ConnectionHealthRegistry,
+  GLOOM_CLOUD_SOCKET_CONNECTION_ID,
+  type ConnectionHealthStatus,
+} from "../core/connection-health";
+import { CloudApiSocket } from "./socket";
+
+function waitForStatus(
+  health: ConnectionHealthRegistry,
+  status: ConnectionHealthStatus,
+): Promise<void> {
+  if (health.getSnapshot().sources[0]?.status === status) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      unsubscribe();
+      reject(new Error(`Timed out waiting for ${status}`));
+    }, 2_000);
+    const unsubscribe = health.subscribe(() => {
+      if (health.getSnapshot().sources[0]?.status !== status) return;
+      clearTimeout(timer);
+      unsubscribe();
+      resolve();
+    });
+  });
+}
+
+describe("CloudApiSocket connection health", () => {
+  test("reports transitions from a real loopback websocket", async () => {
+    let peer: ServerWebSocket<unknown> | null = null;
+    const server = Bun.serve({
+      hostname: "127.0.0.1",
+      port: 0,
+      fetch(request, server) {
+        return server.upgrade(request) ? undefined : new Response("Upgrade required", { status: 426 });
+      },
+      websocket: {
+        open(socket) {
+          peer = socket;
+        },
+        message() {},
+      },
+    });
+    const health = new ConnectionHealthRegistry();
+    health.registerSource({
+      id: GLOOM_CLOUD_SOCKET_CONNECTION_ID,
+      name: "Gloom Cloud Stream",
+      kind: "websocket",
+    });
+    const socket = new CloudApiSocket({
+      getBaseUrl: () => `http://127.0.0.1:${server.port}`,
+      getSocketAuthToken: () => null,
+      hasVerifiedUser: () => false,
+      isUsingWebSocketToken: () => false,
+      clearWebSocketTokenForFallback: () => false,
+      markCurrentUserUnverified: () => {},
+      updateCurrentUserFromSocket: () => {},
+    }, health);
+
+    try {
+      socket.subscribeQuotes([{ symbol: "AAPL" }], () => {});
+      expect(health.getSnapshot().sources[0]).toMatchObject({
+        status: "connecting",
+        socketState: "connecting",
+      });
+
+      await waitForStatus(health, "connected");
+      peer!.close(1000, "network lost");
+      await waitForStatus(health, "disconnected");
+      expect(health.getSnapshot().sources[0]).toMatchObject({
+        socketState: "closed",
+        currentDetail: "network lost",
+      });
+    } finally {
+      socket.dispose();
+      void server.stop(true);
+    }
+  });
+});