gloomberb 0.16.1 → 0.16.3

package/src/api-client/paths.ts

@@ -4,7 +4,9 @@ import type {
   CloudTweetQueryType,
 } from "./types";
 import { isUsListingExchange, normalizeSymbol, parsePublicTickerKey, publicTickerKey } from "../utils/exchanges";
+import { nonUsSecListingVenue } from "../utils/sec";
 import type { HistoryRetention } from "../sources/history-retention";
+import type { CloudBeneficialOwnersParams } from "./beneficial-owners";
 
 export type CloudHistoryParams = {
   interval?: string;
@@ -228,6 +230,10 @@ export function cloudCreditBoardPath(board: "cdx" | "sovr", params: { days?: num
 
 export type CloudSecFilingsParams = {
   ticker: string;
+  /** The listing's venue. Sent only for a venue outside the US, with `name`. */
+  exchange?: string;
+  /** The listing's company name, from its own quote. */
+  name?: string;
   limit?: number;
   offset?: number;
 };
@@ -343,13 +349,36 @@ export function cloudProxyStatementPath(ticker: string, year: number): string {
   return `/cloud/proxies/${encodeURIComponent(normalizeIssuerResearchTicker(ticker))}/${year}`;
 }
 
+/**
+ * A US listing, or a symbol with no venue, looks up its US ticker as before.
+ * A listing elsewhere sends its bare symbol with the venue and company name:
+ * its symbol can be another company's US ticker.
+ */
 export function cloudSecFilingsPath(params: CloudSecFilingsParams): string {
-  const search = new URLSearchParams({ ticker: normalizeIssuerResearchTicker(params.ticker) });
+  const venue = nonUsSecListingVenue(params.ticker, params.exchange);
+  const search = new URLSearchParams({
+    ticker: venue ? parsePublicTickerKey(params.ticker).symbol : normalizeIssuerResearchTicker(params.ticker),
+  });
   if (params.limit != null) search.set("limit", String(params.limit));
   if (params.offset != null) search.set("offset", String(params.offset));
+  if (venue) {
+    search.set("exchange", venue);
+    const name = params.name?.trim();
+    if (name) search.set("name", name);
+  }
   return appendQuery("/cloud/sec/filings", search);
 }
 
+/** Schedule 13D and 13G reports about the issuer behind `ticker`. */
+export function cloudSecBeneficialOwnersPath(params: CloudBeneficialOwnersParams): string {
+  const search = new URLSearchParams({ ticker: normalizeIssuerResearchTicker(params.ticker) });
+  if (params.form) search.set("form", params.form);
+  if (params.history) search.set("history", "1");
+  if (params.limit != null) search.set("limit", String(params.limit));
+  if (params.offset != null) search.set("offset", String(params.offset));
+  return appendQuery("/cloud/sec/beneficial-owners", search);
+}
+
 export function cloudSecFilingDocumentsPath(
   params: CloudSecFilingParams,
 ): string {

package/src/api-client/perps.ts

@@ -79,6 +79,28 @@ interface UnderlyingReference {
   sourceUrl: string
 }
 
+/**
+ * The venue's latest long/short account reading for one contract, in its own hourly bucket. Shares are
+ * fractions and may sum to less than one (flat accounts); OKX publishes only the ratio, so its shares are derived.
+ */
+export interface PerpLongShortRatio {
+  venue: string
+  /** Key of what is counted, such as `accounts_all`; `definitionText` says it in words. */
+  definition: string
+  definitionText: string
+  period: string
+  longShare: number
+  shortShare: number
+  ratio: number | null
+  derived: boolean
+  bucketAt: string
+  observedAt: string
+  /** The bucket is more than three hours old. */
+  stale: boolean
+}
+/** Why a row has no reading: the venue publishes none, collection is off, or nothing is stored yet. */
+type PerpLongShortReason = "unsupported" | "off" | "collecting"
+
 export interface PerpBoardRow extends PerpMarket {
   equityMatch?: { listing: PerpEquityListing; underlying: PerpEquityListing; basis: "listing" | "issuer" }
   stale: boolean
@@ -89,6 +111,19 @@ export interface PerpBoardRow extends PerpMarket {
   underlying: UnderlyingReference | null
   underlyingPremium: number | null
   closedMarketPremium: number | null
+  /** Absent from servers older than the long/short series: read as null. */
+  longShortRatio?: PerpLongShortRatio | null
+  longShortRatioReason?: PerpLongShortReason | null
+}
+
+export type PerpLongShortPoint = {
+  time: string
+  definition: string
+  longShare: number
+  shortShare: number
+  ratio: number | null
+  derived: boolean
+  observedAt: string
 }
 
 type PerpHistoryPoint = {
@@ -114,6 +149,8 @@ export interface PerpBoardPayload {
 export interface PerpEquityListing { symbol: string; exchange: string }
 export interface PerpHistoryPayload {
   status: string; marketId: string; rows: PerpHistoryPoint[]; funding: PerpFunding[]; candles: PerpCandle[];
+  /** Absent from servers older than the long/short series: read as empty. */
+  longShortRatio?: PerpLongShortPoint[];
   locked: boolean; access: "pro" | "preview"; asOf: string | null;
   from?: string; to?: string; resolution?: "minute" | "hour" | "day"; truncated?: boolean;
 }

package/src/api-client/request.ts

@@ -3,6 +3,7 @@ import { withDeadline } from "../utils/async-deadline";
 import {
   ApiRequestError,
   parseApiErrorCode,
+  parseApiErrorDetails,
   parseApiErrorMessage,
   parseRetryAfterMs,
   type RevisionConflictError,
@@ -391,6 +392,7 @@ export class CloudApiRequestTransport {
           res.status,
           parseRetryAfterMs(res.headers.get("Retry-After")),
           parseApiErrorCode(text),
+          parseApiErrorDetails(text),
         );
       }
 
@@ -404,8 +406,9 @@ export class CloudApiRequestTransport {
     };
     // Crash reports, usage counts and command-search reports are background
     // traffic: a rate-limited, timed-out or missing one must not show up as a
-    // Cloud outage in the connections pane.
-    if (path.startsWith("/telemetry/") || path === "/assist/searches") return request();
+    // Cloud outage in the connections pane. Nor must the map's probe for geo
+    // layers, which a server without them answers with 404.
+    if (path.startsWith("/telemetry/") || path === "/assist/searches" || path === "/cloud/geo/layers") return request();
     return this.connectionHealth.track(
       GLOOM_CLOUD_HTTP_CONNECTION_ID,
       operation,

package/src/api-client/types.ts

@@ -12,6 +12,8 @@ import type { SyncSettings, SyncSnapshot } from "../sync/types";
 
 export interface ChatUserSummary {
   id: string;
+  /** A person, a managed assistant (Gloombot), or a Discord user bridged into public channels. */
+  accountType?: "human" | "managed_llm" | "discord";
   username: string | null;
   displayName: string;
   bio?: string | null;

package/src/brokers/account-cache.ts

@@ -1,4 +1,5 @@
 import type { AppResourceStorePort } from "../core/app-service-ports";
+import type { CachedResourceRecord, ResourceCacheKey } from "../data/resource-store";
 import type { BrokerAdapter } from "../types/broker";
 import type { BrokerInstanceConfig } from "../types/config";
 import type { CachePolicy } from "../types/persistence";
@@ -21,6 +22,50 @@ function brokerAccountNamespace(instance: BrokerInstanceConfig): string {
   return `plugin:${instance.brokerType}`;
 }
 
+/** A saved account snapshot, which a renderer without the cache database has to keep elsewhere. */
+export function isBrokerAccountSnapshotKey(key: Pick<ResourceCacheKey, "namespace" | "kind">): boolean {
+  return key.kind === BROKER_ACCOUNT_SNAPSHOT_KIND && key.namespace.startsWith("plugin:");
+}
+
+/**
+ * Saves an account snapshot written by a process without the cache database
+ * (the desktop view), keeping its own times. Anything else is refused.
+ */
+export function saveBrokerAccountRecord(
+  resources: Pick<AppResourceStorePort, "set">,
+  record: CachedResourceRecord | null | undefined,
+): boolean {
+  if (!record || typeof record.namespace !== "string" || typeof record.entityKey !== "string"
+    || !isBrokerAccountSnapshotKey(record)
+    || ![record.fetchedAt, record.staleAt, record.expiresAt].every(Number.isFinite)) return false;
+  resources.set(record, record.value, {
+    schemaVersion: record.schemaVersion,
+    provenance: record.provenance,
+    fetchedAt: record.fetchedAt,
+    cachePolicy: { staleMs: record.staleAt - record.fetchedAt, expireMs: record.expiresAt - record.fetchedAt },
+  });
+  return true;
+}
+
+export function deleteBrokerAccountRecord(resources: Pick<AppResourceStorePort, "delete">, key: ResourceCacheKey): void {
+  if (isBrokerAccountSnapshotKey(key)) resources.delete(key);
+}
+
+/** Every unexpired account snapshot saved for these profiles, as stored. */
+export function listPersistedBrokerAccountRecords(
+  resources: Pick<AppResourceStorePort, "list">,
+  brokerInstances: readonly BrokerInstanceConfig[],
+): CachedResourceRecord[] {
+  return brokerInstances.flatMap((instance) => resources.list<PersistedBrokerAccountSnapshot>({
+    namespace: brokerAccountNamespace(instance),
+    kind: BROKER_ACCOUNT_SNAPSHOT_KIND,
+    entityKey: instance.id,
+  }, {
+    schemaVersion: BROKER_ACCOUNT_SNAPSHOT_SCHEMA_VERSION,
+    touch: false,
+  }));
+}
+
 export function getBrokerAccountCacheSourceKey(
   instance: BrokerInstanceConfig,
   broker?: BrokerAdapter | null,
@@ -84,6 +129,30 @@ export function loadPersistedBrokerAccounts(
   })?.value.accounts ?? null;
 }
 
+/**
+ * The newest saved account snapshot of a profile, for readers without its
+ * adapter such as the CLI. Read only: without the adapter the current source
+ * key is unknown, so nothing is pruned.
+ */
+export function peekPersistedBrokerAccounts(
+  resources: Pick<AppResourceStorePort, "list">,
+  instance: BrokerInstanceConfig,
+): BrokerAccount[] | null {
+  const records = resources.list<PersistedBrokerAccountSnapshot>({
+    namespace: brokerAccountNamespace(instance),
+    kind: BROKER_ACCOUNT_SNAPSHOT_KIND,
+    entityKey: instance.id,
+  }, {
+    schemaVersion: BROKER_ACCOUNT_SNAPSHOT_SCHEMA_VERSION,
+    allowExpired: true,
+  });
+  const newest = records.reduce<(typeof records)[number] | null>(
+    (latest, record) => (!latest || record.fetchedAt > latest.fetchedAt ? record : latest),
+    null,
+  );
+  return newest?.value.accounts ?? null;
+}
+
 export function persistBrokerAccounts(
   resources: AppResourceStorePort,
   instance: BrokerInstanceConfig,

package/src/cli/command-options.ts

@@ -0,0 +1,74 @@
+import type { CliCommandDef } from "../types/plugin";
+import { fail } from "./errors";
+import { suggestCliOption } from "./help";
+
+/** A built-in command, which may say more about an option it does not take than the list of those it does. */
+export interface BuiltinCliCommandDef extends CliCommandDef {
+  /** A sentence for an unknown option people reach for, such as `--from` on `history`; null for the rest. */
+  unknownOptionHint?(flag: string): string | null;
+}
+
+interface DeclaredOption {
+  flag: string;
+  takesValue: boolean;
+}
+
+/** `--range`, `--range=5Y`: an option. `-5`, `---`, `--` and plain words are not. */
+const OPTION_TOKEN = /^--[a-z]/i;
+
+/**
+ * The options a command's help declares, from each spelling such as
+ * `--range <range>` (takes a value) or `--all` (a switch). Null when it takes
+ * any option: `--<option> <value>` on `fn` and `shot`.
+ */
+function declaredOptions(command: CliCommandDef): Map<string, DeclaredOption> | null {
+  const declared = new Map<string, DeclaredOption>();
+  for (const option of command.help?.options ?? []) {
+    for (const spelling of option.flags.split(",")) {
+      const trimmed = spelling.trim();
+      if (trimmed.startsWith("--<")) return null;
+      const match = /^(--?[a-z][\w-]*)(?:[ =](.+))?$/i.exec(trimmed);
+      if (match) declared.set(match[1]!, { flag: match[1]!, takesValue: match[2] != null });
+    }
+  }
+  return declared;
+}
+
+function failUnknownOption(command: BuiltinCliCommandDef, flag: string, declared: Map<string, DeclaredOption>): never {
+  const flags = [...declared.keys()];
+  const suggestion = suggestCliOption(flag, flags);
+  const help = `See gloomberb help ${command.name}.`;
+  fail(`Unknown option ${flag} for ${command.name}.`, [
+    command.unknownOptionHint?.(flag) ?? "",
+    suggestion ? `Did you mean ${suggestion}?` : "",
+    flags.length > 0 ? `Options: ${flags.join(", ")}. ${help}` : `${command.name} takes no options. ${help}`,
+  ].filter(Boolean).join("\n"));
+}
+
+/**
+ * Fails on the first `--option` a built-in command does not declare, which it
+ * would otherwise ignore and answer as if it had not been given: `history
+ * --from 1995-01-01` printing the default year. Global flags are already out
+ * of `args`; a declared option's value is skipped whatever it looks like, and
+ * nothing from `literalStart` on (after a bare `--`) is read as an option.
+ */
+export function checkCliCommandOptions(
+  command: BuiltinCliCommandDef,
+  args: readonly string[],
+  literalStart = args.length,
+): void {
+  const declared = declaredOptions(command);
+  if (!declared) return;
+  for (let index = 0; index < Math.min(literalStart, args.length); index += 1) {
+    const arg = args[index]!;
+    if (!OPTION_TOKEN.test(arg)) continue;
+    const equals = arg.indexOf("=");
+    const flag = equals >= 0 ? arg.slice(0, equals) : arg;
+    const option = declared.get(flag);
+    if (!option) failUnknownOption(command, flag, declared);
+    if (!option.takesValue && equals >= 0) {
+      fail(`${flag} takes no value.`, `Write it alone, as ${flag}. See gloomberb help ${command.name}.`);
+    }
+    if (option.takesValue && equals < 0) index += 1;
+  }
+}

package/src/cli/commands/command-utils.ts

@@ -15,6 +15,14 @@ export function takeOption(args: string[], name: string): string | undefined {
   return value;
 }
 
+/** Removes a boolean flag (`--history`) from `args` and says whether it was there. */
+export function takeFlag(args: string[], name: string): boolean {
+  const index = args.indexOf(name);
+  if (index < 0) return false;
+  args.splice(index, 1);
+  return true;
+}
+
 export function parseJsonPayload(value: string | undefined, ctx: CliCommandContext): unknown {
   if (!value) return {};
   try {
@@ -38,6 +46,35 @@ export function requireArg(value: string | undefined, usage: string, ctx: CliCom
   return value;
 }
 
+/**
+ * Fails on arguments past the `max` a command takes rather than dropping them:
+ * `fx NGN ZAR` printing NGN alone reads as an answer for both. `usage` is the
+ * command's usage line without `gloomberb`, `takes` what it takes ("one
+ * currency", "no arguments").
+ */
+export function rejectExtraArgs(
+  args: readonly string[],
+  max: number,
+  { usage, takes, advice }: { usage: string; takes: string; advice?: string },
+  ctx: Pick<CliCommandContext, "fail">,
+): void {
+  if (args.length <= max) return;
+  const command = usage.split(" ")[0];
+  ctx.fail(`${command} takes ${takes}; got ${args.join(" ")}.`, [advice, `Usage: gloomberb ${usage}`].filter(Boolean).join("\n"));
+}
+
+/** The one argument a command takes, such as a symbol: missing fails with the usage line, extras are not dropped. */
+export function requireOneArg(
+  args: readonly string[],
+  usage: string,
+  noun: string,
+  ctx: CliCommandContext,
+): string {
+  const value = requireArg(args[0], `Usage: gloomberb ${usage}`, ctx);
+  rejectExtraArgs(args, 1, { usage, takes: `one ${noun}`, advice: `Run it once per ${noun}.` }, ctx);
+  return value;
+}
+
 export function isoDate(value: unknown): string {
   if (value instanceof Date) return value.toISOString();
   if (typeof value === "number") return new Date(value).toISOString();

package/src/cli/commands/crypto-hints.ts

@@ -0,0 +1,75 @@
+import { isCryptoInstrumentType } from "../../tickers/search/ranking";
+import type { Quote } from "../../types/financials";
+import { isCryptoPairSymbol } from "../../utils/crypto-pair";
+
+/** Where a crypto pair that will not load can still be read. `fn CRYP` takes no argument. */
+export const CRYPTO_BOARD_HINT = "Crypto prices may be briefly unavailable; the CRYP function (gloomberb fn CRYP) shows the crypto board.";
+
+// The coins whose bare ticker is most often typed for the coin itself. The label is how the note
+// names the coin and what a listing's name has to say before the note applies.
+const MAJOR_COINS = new Map([
+  ["BTC", "bitcoin"],
+  ["ETH", "ethereum"],
+  ["SOL", "solana"],
+  ["XRP", "XRP"],
+  ["DOGE", "dogecoin"],
+  ["ADA", "cardano"],
+  ["LTC", "litecoin"],
+  ["BCH", "bitcoin cash"],
+  ["AVAX", "avalanche"],
+  ["DOT", "polkadot"],
+  ["LINK", "chainlink"],
+  ["BNB", "BNB"],
+]);
+
+/**
+ * A bare coin ticker usually resolves to a listed fund, not the coin. The note applies only when
+ * the listing is not crypto and its own name says the coin (a "Bitcoin" trust), so a company that
+ * happens to share the letters (Interlink Electronics on LINK) is left alone.
+ */
+function notTheCoinNote(symbol: string, quote: Pick<Quote, "name" | "instrumentType"> | null | undefined): string | null {
+  const coin = MAJOR_COINS.get(symbol);
+  const type = quote?.instrumentType?.trim();
+  const name = quote?.name?.trim();
+  if (!coin || !name || !type || isCryptoInstrumentType(type)) return null;
+  if (!new RegExp(`\\b${coin}\\b`, "i").test(name)) return null;
+  return `${symbol} is ${name}, not ${coin}. For ${coin} use ${symbol}-USD.`;
+}
+
+interface QuoteNoteResult {
+  target: { symbol: string };
+  quote: Pick<Quote, "name" | "instrumentType"> | null;
+  error: string | null;
+}
+
+/** The router words a failure as "<reason> for <symbol>"; drop the symbol so equal reasons group. */
+function failureReason(message: string, symbol: string): string {
+  const line = (message.split("\n")[0] ?? "").trim().replace(/\.+$/, "");
+  const suffix = ` for ${symbol}`;
+  return line.toLowerCase().endsWith(suffix.toLowerCase()) ? line.slice(0, -suffix.length) : line;
+}
+
+/**
+ * Text-mode notes under a quote table: one line per distinct failure reason (with the crypto board
+ * pointer when a failed symbol is a crypto pair), then a line for each bare coin ticker that
+ * resolved to something else. `--exchange` names the listing on purpose, so it gets no coin note.
+ */
+export function quoteNotes(results: QuoteNoteResult[], options: { exchange?: string } = {}): string[] {
+  const failures = new Map<string, string[]>();
+  for (const result of results) {
+    if (!result.error || result.quote) continue;
+    const reason = failureReason(result.error, result.target.symbol);
+    const symbols = failures.get(reason) ?? [];
+    if (!symbols.includes(result.target.symbol)) failures.set(reason, [...symbols, result.target.symbol]);
+  }
+  const notes = [...failures].map(([reason, symbols]) => (
+    `${symbols.join(", ")}: ${reason}${symbols.some(isCryptoPairSymbol) ? `. ${CRYPTO_BOARD_HINT}` : ""}`
+  ));
+  if (!options.exchange) {
+    for (const result of results) {
+      const note = notTheCoinNote(result.target.symbol, result.quote);
+      if (note) notes.push(note);
+    }
+  }
+  return notes;
+}