gloomberb 0.14.0 → 0.15.0

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

@@ -0,0 +1,11 @@
+import { expect, test } from "bun:test";
+import { parseApiErrorMessage } from "./errors";
+
+test("an HTML error page from the proxy becomes its title, not raw markup", () => {
+  const cloudflare = `<!DOCTYPE html>\n<!--[if lt IE 7]> <html class="no-js ie6 oldie" lang="en-US"> <![endif]-->\n<html><head><title>api.gloom.sh | 502: Bad gateway</title></head><body>...</body></html>`;
+  expect(parseApiErrorMessage(cloudflare)).toBe("502: Bad gateway");
+  expect(parseApiErrorMessage("<html><body>down</body></html>")).toBe("The server returned an error page.");
+  expect(parseApiErrorMessage(JSON.stringify({ error: "Senate PTR filings are unavailable right now." })))
+    .toBe("Senate PTR filings are unavailable right now.");
+  expect(parseApiErrorMessage("plain text")).toBe("plain text");
+});

package/src/api-client/errors.ts

@@ -43,10 +43,20 @@ export function parseApiErrorMessage(body: string): string {
     );
     return parts.join(" ") || body;
   } catch {
-    return body;
+    return htmlErrorTitle(body) ?? body;
   }
 }
 
+/**
+ * A proxy in front of the API (Cloudflare) can replace an error body with its
+ * own HTML page; its title ("api.gloom.sh | 502: Bad gateway") is the message.
+ */
+function htmlErrorTitle(body: string): string | null {
+  if (!/^\s*<(?:!doctype\s+html|html)[\s>]/i.test(body)) return null;
+  const title = /<title[^>]*>([^<]*)<\/title>/i.exec(body)?.[1]?.replace(/\s+/g, " ").trim();
+  return title?.split(" | ").at(-1) || "The server returned an error page.";
+}
+
 export function isHardSessionInvalidMessage(message: string): boolean {
   const normalized = message.replace(/[_-]+/g, " ");
   return HARD_SESSION_INVALID_PATTERNS.some((pattern) =>

package/src/api-client/estimate-revisions.ts

@@ -0,0 +1,113 @@
+export interface PercentileStatistics {
+  percentile: number | null;
+  rank: number | null;
+  samples: number;
+  min: number | null;
+  max: number | null;
+  mean: number | null;
+}
+export type EstimateStatus = "available" | "partial" | "unavailable";
+export interface EstimateSourceState {
+  status: EstimateStatus;
+  fetchedAt: string | null;
+  stale: boolean;
+  reason: string | null;
+}
+export interface EstimateObservation {
+  date: string;
+  recordedAt: string | null;
+  average: number | null;
+  low: number | null;
+  high: number | null;
+  analysts: number | null;
+  range: number | null;
+  relativeRange: number | null;
+  source: "yahoo" | "yahoo-eps-trend";
+}
+export interface RevisionBreadth {
+  days: 7 | 30;
+  up: number | null;
+  down: number | null;
+  net: number | null;
+  ratio: number | null;
+  asOf: string | null;
+  percentile: null;
+}
+export interface EstimatePeriod {
+  id: string;
+  frequency: "quarterly" | "annual";
+  periodEnd: string;
+  currency: string | null;
+  label: string;
+  current: (EstimateObservation & { growth: number | null }) | null;
+  revenue: {
+    average: number | null;
+    low: number | null;
+    high: number | null;
+    currency: string | null;
+    analysts: number | null;
+    asOf: string | null;
+  } | null;
+  recorded: EstimateObservation[];
+  lookbacks: EstimateObservation[];
+  percentile: PercentileStatistics & {
+    window: "1Y";
+    firstDate: string | null;
+    lastDate: string | null;
+  };
+  dispersionPercentile: PercentileStatistics;
+  change: {
+    value: number | null;
+    percent: number | null;
+    fromDate: string | null;
+    toDate: string | null;
+  };
+  breadth: RevisionBreadth[];
+}
+export interface EstimateSurprise {
+  date: string;
+  dateType: "announcement" | "fiscal-period-end" | "unspecified";
+  currency: string | null;
+  estimate: number | null;
+  actual: number | null;
+  difference: number | null;
+  percent: number | null;
+  percentile: number | null;
+  samples: number;
+  source: string;
+}
+export interface EstimateGuidance {
+  callDate: string | null;
+  fiscalYear: number;
+  fiscalQuarter: number;
+  publishedAt: string;
+  text: string;
+  transcriptURL: string;
+  webcastURL: string | null;
+  source: "public-transcript-summary";
+  numericComparison: null;
+}
+export interface EstimateRevisionsPayload {
+  symbol: string;
+  exchange: string;
+  generatedAt: string;
+  status: EstimateStatus;
+  sources: {
+    consensus: EstimateSourceState;
+    history: EstimateSourceState;
+    reported: EstimateSourceState;
+    guidance: EstimateSourceState;
+  };
+  periods: EstimatePeriod[];
+  surprises: EstimateSurprise[];
+  guidance: EstimateGuidance | null;
+  historyCoverage: {
+    since: string;
+    until: string;
+    truncated: boolean;
+    excludedRows: number;
+    recordedDays: number;
+    lookbackRows: number;
+  };
+  gaps: string[];
+}

package/src/api-client/feedback.ts

@@ -0,0 +1,35 @@
+import type {
+  FeedbackListResponse,
+  FeedbackReportSummary,
+  FeedbackSubmitRequest,
+  FeedbackSubmitResponse,
+} from "../feedback/types";
+import { withDeadline } from "../utils/async-deadline";
+
+type CloudApiRequest = <T>(path: string, options?: RequestInit) => Promise<T>;
+
+/** Long enough for a screenshot on a slow uplink, short enough that Send never hangs. */
+const SUBMIT_TIMEOUT_MS = 45_000;
+
+export class CloudFeedbackApi {
+  constructor(private readonly request: CloudApiRequest) {}
+
+  submitFeedback(report: FeedbackSubmitRequest): Promise<FeedbackSubmitResponse> {
+    const controller = new AbortController();
+    return withDeadline(
+      this.request<FeedbackSubmitResponse>("/feedback", {
+        method: "POST",
+        body: JSON.stringify(report),
+        signal: controller.signal,
+      }),
+      SUBMIT_TIMEOUT_MS,
+      "Sending took too long. Check your connection and try again.",
+      (error) => controller.abort(error),
+    );
+  }
+
+  async listFeedback(): Promise<FeedbackReportSummary[]> {
+    const body = await this.request<FeedbackListResponse>("/feedback");
+    return body.reports;
+  }
+}

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

@@ -0,0 +1,53 @@
+/** Gloom Cloud futures prices retain provider denomination and explicit quote units. */
+export interface FuturesContract {
+  symbol: string
+  label: string
+  expiration: string
+  price: number | null
+  asOf: string | null
+  currency: string
+  quoteUnit: string
+  volume: number | null
+  openInterest: number | null
+  delayMinutes: number | null
+  stale: boolean
+  percentile: number | null
+  samples: number
+  historyStart: string | null
+  historyEnd: string | null
+}
+
+export interface FuturesCurvePayload {
+  root: string
+  name: string
+  source: "yahoo" | "cboe"
+  currency: string | null
+  quoteUnit: string | null
+  asOf: string | null
+  fetchedAt: string
+  status: "available" | "partial" | "unavailable"
+  stale: boolean
+  catalogue: { method: "provider" | "bounded-search"; complete: boolean; horizonEnd: string | null }
+  contracts: FuturesContract[]
+  ghosts: Array<{
+    label: "1W" | "1M" | "1Y"
+    requestedDate: string
+    asOf: string | null
+    points: Array<{ symbol: string; expiration: string; price: number | null; asOf: string | null }>
+  }>
+  slope: {
+    frontSymbol: string | null
+    nextSymbol: string | null
+    value: number | null
+    annualizedRollYield: number | null
+    percentile: number | null
+    rollPercentile: number | null
+    samples: number
+    historyStart: string | null
+    historyEnd: string | null
+    asOf: string | null
+    state: "contango" | "backwardation" | "flat" | "unavailable"
+  }
+  gaps: string[]
+}
+

package/src/api-client/index.ts

@@ -25,6 +25,7 @@ import { ApiRequestError } from "./errors";
 import { CloudApiRequestTransport } from "./request";
 import { CloudApiSocket } from "./socket";
 import { CloudCollectionsApi } from "./collections";
+import { CloudFeedbackApi } from "./feedback";
 import { CloudNotesApi } from "./notes";
 import { CloudTeamsApi } from "./teams";
 import { CloudThesesApi } from "./theses";
@@ -109,6 +110,7 @@ class GloomApiClient {
   });
   private readonly data: CloudDataApi = new CloudDataApi((path, options) => this.request(path, options));
   private readonly notes: CloudNotesApi = new CloudNotesApi((path, options) => this.request(path, options));
+  private readonly feedback: CloudFeedbackApi = new CloudFeedbackApi((path, options) => this.request(path, options));
   private readonly theses: CloudThesesApi = new CloudThesesApi((path, options) => this.request(path, options));
   private readonly collections: CloudCollectionsApi = new CloudCollectionsApi((path, options) => this.request(path, options));
   private readonly views: CloudViewsApi = new CloudViewsApi((path, options) => this.request(path, options));
@@ -629,6 +631,8 @@ class GloomApiClient {
   listCloudNotes = this.notes.listNotes.bind(this.notes);
   getCloudNote = this.notes.getNote.bind(this.notes);
   putCloudNote = this.notes.putNote.bind(this.notes);
+  submitFeedback = this.feedback.submitFeedback.bind(this.feedback);
+  listFeedback = this.feedback.listFeedback.bind(this.feedback);
   deleteCloudNote = this.notes.deleteNote.bind(this.notes);
   listTheses = this.theses.listTheses.bind(this.theses);
   getThesis = this.theses.getThesis.bind(this.theses);
@@ -660,6 +664,7 @@ class GloomApiClient {
   deleteTeamPluginState = this.views.deleteTeamPluginState.bind(this.views);
 
   /** Subscribes to a shared scanner feed; all panes of one kind share one upstream subscription. */
+  subscribeTape = this.socket.subscribeTape.bind(this.socket);
   subscribeScanner = this.socket.subscribeScanner.bind(this.socket);
 
   dispose(): void {
@@ -688,7 +693,22 @@ class GloomApiClient {
   getCloudEconomicCalendar = this.data.getCloudEconomicCalendar.bind(this.data);
   getCloudEquityDiagnostic = this.data.getCloudEquityDiagnostic.bind(this.data);
   getCloudFredSeries = this.data.getCloudFredSeries.bind(this.data);
+  getCloudCryptoMarkets = this.data.getCloudCryptoMarkets.bind(this.data);
+  getCloudCentralBankRates = this.data.getCloudCentralBankRates.bind(this.data);
+  getMobileAlertHistory = this.data.getMobileAlertHistory.bind(this.data);
+  getScannerFlowHistory = this.data.getScannerFlowHistory.bind(this.data);
+  getCloudEstimateRevisions = this.data.getCloudEstimateRevisions.bind(this.data);
+  getCloudMoneyMarkets = this.data.getCloudMoneyMarkets.bind(this.data);
+  equityScreener = this.data.equityScreener.bind(this.data);
+  impliedVolatility = this.data.impliedVolatility.bind(this.data);
+  getCloudDebtMaturities = this.data.getCloudDebtMaturities.bind(this.data);
+  getCloudShortVolume = this.data.getCloudShortVolume.bind(this.data);
+  getCloudFuturesCurve = this.data.getCloudFuturesCurve.bind(this.data);
+  getCloudRatePath = this.data.getCloudRatePath.bind(this.data);
   getCloudShiller = this.data.getCloudShiller.bind(this.data);
+  getCloudCotBoard = this.data.getCloudCotBoard.bind(this.data);
+  getCloudCotContract = this.data.getCloudCotContract.bind(this.data);
+  getCloudTape = this.data.getCloudTape.bind(this.data);
   getCloudYieldCurve = this.data.getCloudYieldCurve.bind(this.data);
   getCloudCds = this.data.getCloudCds.bind(this.data);
   getCloudCongressHouse = this.data.getCloudCongressHouse.bind(this.data);
@@ -720,3 +740,5 @@ class GloomApiClient {
 }
 
 export const apiClient = new GloomApiClient();
+
+export type { FuturesCurvePayload, FuturesContract } from "./futures-curve";

package/src/api-client/money-markets.ts

@@ -0,0 +1,57 @@
+/** Money-market observations from Cloud. Rates use percent; liquidity uses USD billions. */
+export interface MoneyMarketObservation {
+  date: string;
+  value: number | null;
+}
+
+export interface MoneyMarketPercentile {
+  value: number | null;
+  rank: number | null;
+  sampleCount: number;
+  windowStart: string | null;
+  windowEnd: string | null;
+  min: number | null;
+  max: number | null;
+  mean: number | null;
+}
+
+export interface MoneyMarketRow {
+  id: string;
+  label: string;
+  seriesId: string | null;
+  sourceSeriesIds: string[];
+  sourceUrl: string | null;
+  group: "rates" | "bills" | "liquidity";
+  unit: "percent" | "usd-billions";
+  frequency: "daily" | "weekly";
+  value: number | null;
+  asOf: string | null;
+  previousValue: number | null;
+  previousAsOf: string | null;
+  change: number | null;
+  changeUnit: "basis-points" | "usd-billions";
+  percentile: MoneyMarketPercentile;
+  history: MoneyMarketObservation[];
+  status: "available" | "stale" | "unavailable";
+  fetchedAt: string | null;
+  unavailableReason: "source-unavailable" | "metadata-unavailable" | "metadata-mismatch" | "no-observations" | "components-unavailable" | null;
+  notes: string[];
+}
+
+interface BillSnapshot {
+  asOf: string | null;
+  points: Array<{ tenor: string; maturityYears: number; seriesId: string; value: number }>;
+}
+
+export interface MoneyMarketsPayload {
+  generatedAt: string;
+  status: "available" | "partial" | "unavailable";
+  rows: MoneyMarketRow[];
+  billsCurve: BillSnapshot & {
+    status: MoneyMarketRow["status"];
+    basis: "discount";
+    comparisons: Array<BillSnapshot & { period: "1W" | "1M" | "1Y"; targetDate: string | null }>;
+    slope: { valueBps: number | null; asOf: string | null; percentile: MoneyMarketPercentile; history: MoneyMarketObservation[] };
+  };
+  netLiquidity: MoneyMarketRow;
+}

package/src/api-client/paths.ts

@@ -4,6 +4,7 @@ import type {
   CloudTweetQueryType,
 } from "./types";
 import { normalizeSymbol, parsePublicTickerKey, publicTickerKey } from "../utils/exchanges";
+import type { HistoryRetention } from "../sources/history-retention";
 
 export type CloudHistoryParams = {
   interval?: string;
@@ -11,6 +12,7 @@ export type CloudHistoryParams = {
   startDate?: string;
   endDate?: string;
   rangeKey?: string;
+  historyRecovery?: HistoryRetention;
 };
 
 export type CloudFredSeriesParams = {
@@ -27,7 +29,11 @@ export type CloudCdsParams = {
   limit?: number;
 };
 
+export type CloudCongressChamber = "all" | "house" | "senate";
+
 export type CloudCongressHouseParams = {
+  /** Which feed to read; House when omitted. */
+  chamber?: CloudCongressChamber;
   year?: number;
   limit?: number;
   offset?: number;
@@ -36,6 +42,10 @@ export type CloudCongressHouseParams = {
   member?: string;
   ticker?: string;
   refresh?: boolean;
+  side?: "BUY" | "SELL" | "EXCHANGE" | "OTHER";
+  owner?: "self" | "spouse" | "joint" | "dependent" | "other";
+  assetType?: "stock" | "option" | "other";
+  minAmount?: number;
 };
 
 export type CloudEarningsCallsParams = {
@@ -165,6 +175,7 @@ export function cloudHistoryPath(
   if (params.startDate) search.set("startDate", params.startDate);
   if (params.endDate) search.set("endDate", params.endDate);
   if (params.rangeKey) search.set("rangeKey", params.rangeKey);
+  if (params.historyRecovery) search.set("historyRecovery", JSON.stringify(params.historyRecovery));
   return appendQuery("/market/history", search);
 }
 
@@ -231,8 +242,12 @@ export function cloudCongressHousePath(
     search.set("filingOffset", String(params.filingOffset));
   if (params.member) search.set("member", params.member);
   if (params.ticker) search.set("ticker", params.ticker);
+  if (params.side) search.set("side", params.side);
+  if (params.owner) search.set("owner", params.owner);
+  if (params.assetType) search.set("assetType", params.assetType);
+  if (params.minAmount != null) search.set("minAmount", String(params.minAmount));
   if (params.refresh != null) search.set("refresh", String(params.refresh));
-  return appendQuery("/cloud/congress/house", search);
+  return appendQuery(`/cloud/congress/${params.chamber ?? "house"}`, search);
 }
 
 const US_ISSUER_LISTINGS = new Set(["NASDAQ", "NYSE", "AMEX", "ARCA", "BATS"]);

package/src/api-client/rates.ts

@@ -0,0 +1,56 @@
+/** Gloom Cloud rate-path contract. Rates are percentage points; probabilities are fractions. */
+export interface RateMetric {
+  value: number | null;
+  asOf: string | null;
+  percentile: number | null;
+  samples: number;
+  source: "fred" | "nyfed" | null;
+  stale?: boolean;
+}
+
+export interface RateContract {
+  symbol: string;
+  month: string;
+  price: number | null;
+  impliedRate: number | null;
+  asOf: string | null;
+  percentile: number | null;
+  samples: number;
+  status: "available" | "unavailable";
+  stale: boolean;
+}
+
+export interface RateMeeting {
+  date: string;
+  impliedRate: number | null;
+  targetMidpoint: number | null;
+  changeBps: number | null;
+  percentile: number | null;
+  samples: number;
+  asOf: string | null;
+  probabilities: Array<{ targetMidpoint: number; probability: number }>;
+  method: "following-month" | "monthly-weighted" | null;
+  reason: string | null;
+}
+
+export interface RatePathPayload {
+  asOf: string | null;
+  fetchedAt: string;
+  stale: boolean;
+  status: "available" | "partial" | "unavailable";
+  current: { effr: RateMetric; targetLower: RateMetric; targetUpper: RateMetric };
+  meetings: RateMeeting[];
+  fedFunds: RateContract[];
+  sofr: RateContract[];
+  ghosts: Array<{
+    label: "1W" | "1M" | "1Y";
+    requestedDate: string;
+    asOf: string | null;
+    points: Array<{ date: string; impliedRate: number | null }>;
+  }>;
+  dotPlot: { asOf: string; sourceUrl: string; points: Array<{ year: number | "longer-run"; rate: number }> };
+  schedule: { sourceUrl: string; verifiedAt: string; through: string };
+  probabilityAssumption: string;
+  slope: { valueBps: number | null; percentile: number | null; samples: number; asOf: string | null };
+  gaps: string[];
+}

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

@@ -1,9 +1,12 @@
-import { describe, expect, test } from "bun:test";
+import { afterEach, describe, expect, test } from "bun:test";
 import {
   ConnectionHealthRegistry,
   registerGloomCloudConnectionSources,
 } from "../core/connection-health";
-import { CloudApiRequestTransport } from "./request";
+import {
+  CloudApiRequestTransport,
+  setCloudApiFetchTransport,
+} from "./request";
 
 function responseWithBody(body: () => Promise<string>): Response {
   return {
@@ -55,6 +58,46 @@ describe("CloudApiRequestTransport connection reporting", () => {
   });
 });
 
+describe("CloudApiRequestTransport streaming", () => {
+  afterEach(() => setCloudApiFetchTransport(null));
+
+  test("a buffered transport with a stream fetch can still open a live body", async () => {
+    const opened: Array<{ url: string; method?: string }> = [];
+    setCloudApiFetchTransport(
+      async () => responseWithBody(async () => "{}"),
+      {
+        streamFetch: async (url, init) => {
+          opened.push({ url, ...(init?.method ? { method: init.method } : {}) });
+          return {
+            ok: true,
+            status: 200,
+            statusText: "OK",
+            headers: new Headers({ "content-type": "text/event-stream" }),
+            body: new ReadableStream<Uint8Array>({
+              start(controller) {
+                controller.close();
+              },
+            }),
+          } as unknown as Response;
+        },
+      },
+    );
+    const transport = new CloudApiRequestTransport();
+
+    expect(transport.isStreamingSupported()).toBe(true);
+    const response = await transport.openStream("/askg/session/s1/turn", { method: "POST" });
+    expect(response.body).toBeTruthy();
+    expect(opened).toEqual([
+      { url: `${transport.baseUrl}/askg/session/s1/turn`, method: "POST" },
+    ]);
+  });
+
+  test("a buffered transport with no stream fetch still refuses to stream", () => {
+    setCloudApiFetchTransport(async () => responseWithBody(async () => "{}"));
+    expect(new CloudApiRequestTransport().isStreamingSupported()).toBe(false);
+  });
+});
+
 describe("CloudApiRequestTransport market deadlines", () => {
   test("aborts when response headers never arrive", async () => {
     let signal: AbortSignal | null | undefined;

package/src/api-client/request.ts

@@ -40,11 +40,18 @@ export interface CloudApiFetchTransportOptions {
    * server-sent events on it would never see a first token.
    */
   streaming?: boolean;
+  /**
+   * A second transport for responses that must be read as they arrive, used
+   * when the main one buffers. The desktop has exactly this shape: JSON goes
+   * through a buffered RPC call, and a live body is forwarded chunk by chunk.
+   */
+  streamFetch?: CloudApiStreamFetch;
 }
 
 let cloudApiFetchTransport: CloudApiFetchTransport = httpFetch;
 let cloudApiTransportInstalled = false;
 let cloudApiFetchStreaming = true;
+let cloudApiStreamFetch: CloudApiStreamFetch | null = null;
 
 export function setCloudApiFetchTransport(
   transport: CloudApiFetchTransport | null,
@@ -53,6 +60,7 @@ export function setCloudApiFetchTransport(
   cloudApiFetchTransport = transport ?? httpFetch;
   cloudApiTransportInstalled = !!transport;
   cloudApiFetchStreaming = transport ? (options.streaming ?? false) : true;
+  cloudApiStreamFetch = transport ? options.streamFetch ?? null : null;
 }
 
 /**
@@ -61,6 +69,7 @@ export function setCloudApiFetchTransport(
  */
 export function getCloudApiStreamFetch(): CloudApiStreamFetch | null {
   if (cloudApiTransportInstalled) {
+    if (cloudApiStreamFetch) return cloudApiStreamFetch;
     // A transport that declares streaming returns a real Response.
     return cloudApiFetchStreaming
       ? (cloudApiFetchTransport as CloudApiStreamFetch)

package/src/api-client/short-volume.ts

@@ -0,0 +1,55 @@
+export type ShortVolumeScope = "nms" | "otc";
+
+export interface ShortVolumeObservation {
+  date: string;
+  shortVolume: string | null;
+  shortExemptVolume: string | null;
+  totalVolume: string | null;
+  ratioPercent: number | null;
+  markets: string[];
+  fetchedAt: string | null;
+  sourceUrl: string;
+  refreshFailed: boolean;
+  unavailableReason: "missing_file" | "not_reported" | "zero_volume" | null;
+}
+
+export interface ShortVolumePayload {
+  version: 1;
+  symbol: string;
+  finraSymbol: string;
+  scope: ShortVolumeScope;
+  status: "available" | "partial" | "unavailable";
+  fetchedAt: string;
+  asOf: string | null;
+  sourceAsOf: string | null;
+  source: { name: string; url: string; cadence: string };
+  latest: (ShortVolumeObservation & {
+    changePp: number | null;
+    previousDate: string | null;
+    percentile: {
+      value: number | null;
+      rank: number | null;
+      sampleCount: number;
+      windowStart: string;
+      windowEnd: string;
+      historyStart: string | null;
+      historyEnd: string | null;
+      completeWindow: boolean;
+      min: number | null;
+      max: number | null;
+      mean: number | null;
+    };
+  }) | null;
+  coverage: {
+    windowStart: string;
+    windowEnd: string;
+    expectedFiles: number;
+    ingestedFiles: number;
+    missingFiles: number;
+    expectedMonths: number;
+    discoveredMonths: number;
+    completeWindow: boolean;
+  };
+  history: ShortVolumeObservation[];
+  warnings: string[];
+}