gloomberb 0.15.8 → 0.16.0

package/src/api-client/chat.ts

@@ -1,11 +1,13 @@
 import {
+  normalizeChatAttachments,
   normalizeChatChannel,
   normalizeChatMessage,
   normalizeChatMessages,
   normalizeChatState,
 } from "./normalizers";
-import type { CloudApiSocket } from "./socket";
+import { CHAT_ATTACHMENTS_FEATURE, type CloudApiSocket } from "./socket";
 import type {
+  ChatAttachment,
   ChatChannel,
   ChatChannelState,
   ChatMessage,
@@ -16,26 +18,114 @@ import type { CloudApiRequest } from "./request";
 type ChatNotificationListener = (notification: ChatNotification) => void;
 type ChatPresenceListener = (onlineCount: number) => void;
 
+/** REST requests list the protocol features this client reads, comma separated. */
+const CHAT_FEATURES_HEADER = "X-Gloom-Features";
+
+/** The bytes of one image to upload, with the type and name the picker or clipboard gave it. */
+export interface ChatAttachmentUpload {
+  name: string;
+  type: string;
+  data: Blob | Uint8Array;
+}
+
+export interface ChatAttachmentUploadOptions {
+  signal?: AbortSignal;
+  /** The fraction of the body sent, where the transport can tell. */
+  onProgress?: (fraction: number) => void;
+}
+
+type CloudChatUpload = <T>(
+  path: string,
+  body: Blob | Uint8Array,
+  options: {
+    contentType: string;
+    headers?: HeadersInit;
+    signal?: AbortSignal;
+    onProgress?: (fraction: number) => void;
+  },
+) => Promise<T>;
+
 interface CloudChatApiOptions {
   request: CloudApiRequest;
+  upload: CloudChatUpload;
   socket: CloudApiSocket;
 }
 
+function withChatFeatures(options: RequestInit = {}): RequestInit {
+  const headers = new Headers(options.headers);
+  headers.set(CHAT_FEATURES_HEADER, CHAT_ATTACHMENTS_FEATURE);
+  return { ...options, headers };
+}
+
+/** A server that knows images sends `attachments` on every message, empty or not. */
+function carriesAttachments(messages: readonly unknown[]): boolean {
+  return messages.some((message) => (
+    !!message && typeof message === "object" && Array.isArray((message as { attachments?: unknown }).attachments)
+  ));
+}
+
 export class CloudChatApi {
+  /** Set once a REST answer showed the server knows images, whatever the socket said. */
+  private restAttachmentSupport = false;
+  private readonly attachmentSupportListeners = new Set<() => void>();
+  private unsubscribeServerFeatures: (() => void) | null = null;
+  private announcedSupport = false;
+
   constructor(private readonly options: CloudChatApiOptions) {}
 
+  private request<T>(path: string, options?: RequestInit): Promise<T> {
+    return this.options.request<T>(path, withChatFeatures(options));
+  }
+
+  /**
+   * Whether the server takes images: its socket "ready" frame offered
+   * chat.attachments, or a REST answer carried them. Until then the client
+   * keeps to text, so an older server never sees an upload.
+   */
+  attachmentsSupported(): boolean {
+    return this.restAttachmentSupport || this.options.socket.serverOffers(CHAT_ATTACHMENTS_FEATURE);
+  }
+
+  subscribeAttachmentSupport(listener: () => void): () => void {
+    if (this.attachmentSupportListeners.size === 0) this.announcedSupport = this.attachmentsSupported();
+    this.attachmentSupportListeners.add(listener);
+    this.unsubscribeServerFeatures ??= this.options.socket.subscribeServerFeatures(() => {
+      this.emitAttachmentSupport();
+    });
+    return () => {
+      this.attachmentSupportListeners.delete(listener);
+      if (this.attachmentSupportListeners.size > 0) return;
+      this.unsubscribeServerFeatures?.();
+      this.unsubscribeServerFeatures = null;
+    };
+  }
+
+  private emitAttachmentSupport(): void {
+    const supported = this.attachmentsSupported();
+    if (supported === this.announcedSupport) return;
+    this.announcedSupport = supported;
+    for (const listener of this.attachmentSupportListeners) listener();
+  }
+
+  private noteMessages(messages: readonly unknown[]): void {
+    if (this.restAttachmentSupport || !carriesAttachments(messages)) return;
+    this.restAttachmentSupport = true;
+    this.emitAttachmentSupport();
+  }
+
   async getChannels(): Promise<ChatChannel[]> {
     const channels =
-      await this.options.request<ChatChannel[]>("/chat/channels");
+      await this.request<ChatChannel[]>("/chat/channels");
     return channels.map((channel) => normalizeChatChannel(channel));
   }
 
   async getPresence(): Promise<{ onlineCount: number }> {
-    return this.options.request<{ onlineCount: number }>("/chat/presence");
+    return this.request<{ onlineCount: number }>("/chat/presence");
   }
 
   async getState(): Promise<ChatStateResponse> {
-    const state = await this.options.request<ChatStateResponse>("/chat/state");
+    const state = await this.request<ChatStateResponse>("/chat/state");
+    this.noteMessages((state.notifications ?? []).map((notification) => notification?.message));
     return normalizeChatState(state);
   }
 
@@ -43,7 +133,7 @@ export class CloudChatApi {
     channelId: string,
     body: { notificationsEnabled?: boolean; readThroughMessageId?: string },
   ): Promise<ChatChannelState> {
-    return this.options.request<ChatChannelState>(
+    return this.request<ChatChannelState>(
       `/chat/channels/${channelId}/state`,
       {
         method: "PATCH",
@@ -55,7 +145,7 @@ export class CloudChatApi {
   async markNotificationsDelivered(
     notificationIds: string[],
   ): Promise<{ delivered: number }> {
-    return this.options.request<{ delivered: number }>(
+    return this.request<{ delivered: number }>(
       "/chat/notifications/delivered",
       {
         method: "POST",
@@ -68,7 +158,7 @@ export class CloudChatApi {
     userId?: string;
     username?: string;
   }): Promise<ChatChannel> {
-    const channel = await this.options.request<ChatChannel>("/chat/direct", {
+    const channel = await this.request<ChatChannel>("/chat/direct", {
       method: "POST",
       body: JSON.stringify(target),
     });
@@ -80,7 +170,7 @@ export class CloudChatApi {
     usernames?: string[];
     name?: string;
   }): Promise<ChatChannel> {
-    const channel = await this.options.request<ChatChannel>("/chat/groups", {
+    const channel = await this.request<ChatChannel>("/chat/groups", {
       method: "POST",
       body: JSON.stringify(body),
     });
@@ -96,25 +186,58 @@ export class CloudChatApi {
     if (opts?.before) params.set("before", opts.before);
     if (opts?.limit) params.set("limit", String(opts.limit));
     const qs = params.toString();
-    const messages = await this.options.request<ChatMessage[]>(
+    const messages = await this.request<ChatMessage[]>(
       `/chat/channels/${channelId}/messages${qs ? `?${qs}` : ""}`,
     );
+    this.noteMessages(messages);
     return normalizeChatMessages(messages);
   }
 
+  /**
+   * Uploads one image to a channel ahead of the message that shows it. The
+   * answer describes the stored copy (it may be smaller, or WebP) and its `id`
+   * goes into `sendMessage`'s `attachmentIds`.
+   */
+  async uploadAttachment(
+    channelId: string,
+    upload: ChatAttachmentUpload,
+    options: ChatAttachmentUploadOptions = {},
+  ): Promise<ChatAttachment> {
+    const stored = await this.options.upload<ChatAttachment>(
+      `/chat/channels/${channelId}/attachments`,
+      upload.data,
+      {
+        contentType: upload.type || "application/octet-stream",
+        headers: { [CHAT_FEATURES_HEADER]: CHAT_ATTACHMENTS_FEATURE },
+        signal: options.signal,
+        onProgress: options.onProgress,
+      },
+    );
+    const [attachment] = normalizeChatAttachments([stored]);
+    if (!attachment) throw new Error("The upload answer had no image.");
+    return attachment;
+  }
+
   async sendMessage(
     channelId: string,
     content: string,
     replyToId?: string,
     clientMessageId?: string,
+    attachmentIds?: string[],
   ): Promise<ChatMessage> {
-    const message = await this.options.request<ChatMessage>(
+    const message = await this.request<ChatMessage>(
       `/chat/channels/${channelId}/messages`,
       {
         method: "POST",
-        body: JSON.stringify({ content, replyToId, clientMessageId }),
+        body: JSON.stringify({
+          content,
+          replyToId,
+          clientMessageId,
+          ...(attachmentIds?.length ? { attachmentIds } : {}),
+        }),
       },
     );
+    this.noteMessages([message]);
     return normalizeChatMessage(message);
   }
 
@@ -123,7 +246,7 @@ export class CloudChatApi {
     messageId: string,
     content: string,
   ): Promise<ChatMessage> {
-    const message = await this.options.request<ChatMessage>(
+    const message = await this.request<ChatMessage>(
       `/chat/channels/${channelId}/messages/${messageId}`,
       {
         method: "PATCH",
@@ -142,8 +265,8 @@ export class CloudChatApi {
       channelId,
       onMessage,
       onError,
-      (content, replyToId, clientMessageId) =>
-        this.sendMessage(channelId, content, replyToId, clientMessageId),
+      (content, replyToId, clientMessageId, attachmentIds) =>
+        this.sendMessage(channelId, content, replyToId, clientMessageId, attachmentIds),
     );
   }
 

package/src/api-client/company-kpis.ts

@@ -0,0 +1,153 @@
+type QuoteMatchMode = "exact" | "whitespace" | "nfkc_whitespace";
+
+type KpiBasis = "reported" | "adjusted" | "constant_currency" | "organic"
+export type KpiUnit = "currency" | "currency_per_share" | "currency_per_unit" | "percent" | "basis_points" | "count" | "ratio" | "volume"
+type KpiSourceKind = "press_release" | "filing" | "transcript" | "opendart" | "ir" | "esef" | "edinet"
+type GuidanceDirection = "raised" | "cut" | "reiterated" | "mixed" | "initiated" | "withdrawn" | "not_comparable"
+type GuidanceHedge = "exact" | "approximately" | "at_least" | "at_most" | "greater_than" | "less_than" | "qualitative" | "withdrawn"
+
+export interface KpiPeriod {
+  /** ISO dates; a quarter's dates must never be inferred from its fiscal label. */
+  start: string | null
+  end: string | null
+  kind: "quarter" | "half" | "year" | "ytd" | "instant" | "other"
+  fiscalYear: number | null
+  fiscalQuarter: number | null
+  label: string
+}
+interface KpiMetric {
+  id: string
+  name: string
+  sector: string
+  unit: KpiUnit
+  definition: string
+  aliases: Record<string, string[]>
+  /** Economic preference, independent of whether the numeric guide was raised. */
+  favorable: "higher" | "lower" | "neutral"
+}
+export interface KpiEvidence {
+  id: string
+  documentId: string
+  sourceId: string
+  sourceKind: KpiSourceKind
+  url: string
+  title: string
+  publishedAt: string
+  country: string
+  language: string
+  quote: string
+  quoteOffset: number
+  quoteSourceLength: number
+  quoteMatchMode: QuoteMatchMode
+  confidence: number
+}
+interface KpiObservationInput {
+  metricId: string
+  period: KpiPeriod
+  value: number
+  valueQualifier?: "exact" | "approximately" | "at_least" | "at_most" | "greater_than" | "less_than"
+  unit: KpiUnit
+  currency: string | null
+  /** Scale of the supplied numeric value (1e6 means millions). Stored values use scale 1. */
+  scale?: number
+  basis: KpiBasis
+  /** Named segment, geography, product, cohort, denominator or physical volume unit. */
+  dimensions: Record<string, string>
+  quote: string
+  confidence: number
+  /** Required when an actual explicitly restates a prior disclosed observation. */
+  revisionReason?: string | null
+}
+interface KpiGuidanceInput extends Omit<KpiObservationInput, "value" | "valueQualifier"> {
+  issuedDate: string
+  low: number | null
+  high: number | null
+  point: number | null
+  hedge: GuidanceHedge
+  /** Exact source phrasing, including qualitative ranges and conditions. */
+  rangeText: string
+  conditions?: string | null
+  status: "active" | "withdrawn"
+}
+export interface KpiObservation extends Omit<KpiObservationInput, "quote" | "scale"> {
+  id: string
+  symbol: string
+  metric: KpiMetric
+  seriesKey: string
+  asOf: string
+  supersedesId: string | null
+  revision: number
+  current: boolean
+  conflict: boolean
+  contested?: boolean
+  evidence: KpiEvidence[]
+}
+export interface KpiGuidance extends Omit<KpiGuidanceInput, "quote" | "scale"> {
+  id: string
+  symbol: string
+  metric: KpiMetric
+  seriesKey: string
+  asOf: string
+  supersedesId: string | null
+  revision: number
+  current: boolean
+  evidence: KpiEvidence[]
+  direction: GuidanceDirection
+  previousId: string | null
+  midpointChangePct: number | null
+  actual: { observationId: string; value: number; outcome: "above" | "below" | "within"; favorable: "beat" | "miss" | "in_line" | "neutral"; difference: number; differencePct: number | null } | null
+}
+interface KpiCoverage {
+  country: string | null
+  languages: string[]
+  documents: number
+  observations: number
+  guidance: number
+  firstPeriod: string | null
+  lastPeriod: string | null
+  lastPublishedAt: string | null
+  sourceKinds: KpiSourceKind[]
+  conflicts: number
+}
+export interface KpiSeries {
+  key: string
+  metric: KpiMetric
+  unit: KpiUnit
+  currency: string | null
+  basis: KpiBasis
+  dimensions: Record<string, string>
+  latest: KpiObservation
+  observations: KpiObservation[]
+}
+export interface KpisPayload {
+  symbol: string
+  status: "available" | "unavailable"
+  asOf: string | null
+  coverage: KpiCoverage
+  series: KpiSeries[]
+  /** Immutable prior actuals, including unresolved conflicting disclosures. */
+  revisions: KpiObservation[]
+  dictionary: KpiMetric[]
+  access: "full" | "preview"
+  lockedRows: number
+  totalRows: number
+  truncated: boolean
+  previewRows: number | null
+  methodology: string
+}
+export interface GuidancePayload extends Omit<KpisPayload, "series" | "revisions"> {
+  guidance: KpiGuidance[]
+  history: KpiGuidance[]
+}
+export interface KpiQueryOptions {
+  metric?: string
+  basis?: KpiBasis
+  from?: string
+  to?: string
+  /** Point-in-time publication cutoff; excludes later restatements and actuals. */
+  asOf?: string
+}
+export function companyDisclosurePath(section: "kpis" | "guidance", symbol: string, options: KpiQueryOptions): string {
+  const query = new URLSearchParams(Object.entries(options).filter((entry): entry is [string, string] => entry[1] != null));
+  return `/cloud/company-${section}/${encodeURIComponent(symbol)}?${query}`;
+}

package/src/api-client/cpi.ts

@@ -0,0 +1,52 @@
+/** US consumer prices by component, as GET /cloud/cpi/board serves them. */
+
+export interface CpiRow {
+  id: string;
+  /** BLS item code; null for a row computed from two published ones (services ex shelter). */
+  code: string | null;
+  label: string;
+  /** 0 at the top level. */
+  depth: number;
+  parent: string | null;
+  /** All items and core, which stay on top whatever the sort. */
+  pinned: boolean;
+  derived: boolean;
+  /** Relative importance of the month before, percent of all items. */
+  weight: number | null;
+  /** Seasonally adjusted change on the month, percent. */
+  change: number | null;
+  /** Seasonally adjusted change over three and six months, annualised, percent. */
+  annualized3m: number | null;
+  annualized6m: number | null;
+  /** Unadjusted change over twelve months, percent. */
+  yoy: number | null;
+  /** Effect on the headline's monthly change, percentage points. */
+  contribution: number | null;
+  /** Effect on the headline's twelve-month change, percentage points. */
+  contributionYoy: number | null;
+  /** One plain sentence worked out from the numbers. */
+  read: string | null;
+  /** [YYYY-MM, change on the month, change over twelve months], oldest first. */
+  history: Array<[string, number | null, number | null]>;
+}
+
+export interface CpiReleaseStatus {
+  /** The month the board covers, YYYY-MM. */
+  period: string | null;
+  releasedAt: string | null;
+  /** The month the weights refer to, YYYY-MM. */
+  weightsPeriod: string | null;
+  nextPeriod: string | null;
+  nextReleaseAt: string | null;
+}
+
+export interface CpiBoardPayload {
+  source: "BLS";
+  generatedAt: string;
+  /** When the index levels were last retrieved. */
+  retrievedAt: string | null;
+  status: "available" | "partial" | "unavailable";
+  gaps: string[];
+  release: CpiReleaseStatus;
+  rows: CpiRow[];
+}

package/src/api-client/credit-documents.ts

@@ -0,0 +1,107 @@
+export type CreditValue = string | number | boolean | null | CreditValue[] | { [key: string]: CreditValue };
+export interface CreditFact {
+  id: string;
+  instrumentId: string;
+  documentId: string;
+  instrumentKey: string;
+  instrumentName: string;
+  field: string;
+  factKey: string;
+  value: CreditValue;
+  unit: string | null;
+  currency: string | null;
+  asOf: string;
+  confidence: number;
+  quote: string;
+  source: string;
+  filingUrl: string;
+  form: string;
+  filedAt: string;
+  periodEnd: string | null;
+  effectiveDate?: string | null;
+  language: string;
+  quoteOffset: number;
+  quoteSourceLength: number;
+  quoteMatchMode: string;
+  status: "active" | "superseded" | "pending";
+  supersedesId: string | null;
+}
+export interface CreditInstrument {
+  lifecycle?: string | null;
+  id: string;
+  key: string;
+  name: string;
+  currency: string | null;
+  facilityType: string | null;
+  principal: number | null;
+  commitment: number | null;
+  drawn: number | null;
+  maturity: string | null;
+  facts: CreditFact[];
+  history?: CreditFact[];
+}
+export interface CreditHeadroom {
+  id: string;
+  instrumentId: string;
+  instrumentName: string;
+  metric: string;
+  comparator: "maximum" | "minimum";
+  inclusive?: boolean;
+  threshold: number;
+  current: number | null;
+  headroomPercent: number | null;
+  asOf: string;
+  testDate: string | null;
+  status: "compliant" | "breach" | "uncomputable" | "stale" | "conditional";
+  reason: string | null;
+  evidenceIds: string[];
+}
+export interface CreditMaturityBucket {
+  year: number;
+  currency: string;
+  principal: number;
+  instruments: Array<{ id: string; name: string; principal: number; evidenceIds: string[] }>;
+}
+interface CreditControlExposure {
+  instrumentId: string;
+  instrumentName: string;
+  currency: string | null;
+  principal: number | null;
+  trigger: string;
+  putPercent: number | null;
+  evidenceIds: string[];
+}
+export interface CreditDocumentsPayload {
+  version: 1;
+  symbol: string;
+  issuer: { id: string; name: string; jurisdiction: string } | null;
+  status: "available" | "partial" | "unavailable";
+  asOf: string | null;
+  access: "full" | "preview";
+  lockedRows: number;
+  instruments: CreditInstrument[];
+  covenants: CreditHeadroom[];
+  maturities: CreditMaturityBucket[];
+  changeOfControl: CreditControlExposure[];
+  warnings: string[];
+}
+export interface CreditScreenRow {
+  symbol: string;
+  issuerName: string;
+  instrumentId: string;
+  instrumentName: string;
+  kind: "headroom" | "springing_maturity";
+  value: number | null;
+  date: string | null;
+  currency: string | null;
+  reason: string;
+  evidence: CreditFact[];
+}
+export interface CreditScreenPayload {
+  truncated: boolean;
+  rows: CreditScreenRow[];
+  access: "full" | "preview";
+  lockedRows: number;
+  asOf: string | null;
+}
+export interface CreditScreenQuery { headroomBelow?: number; springingWithinMonths?: number; limit?: number }