gloomberb 0.18.1 → 0.18.3

package/src/types/trading.ts

@@ -3,6 +3,36 @@ import type { BrokerContractRef } from "./instrument";
 type BrokerOrderAction = "BUY" | "SELL";
 export type BrokerOrderType = "MKT" | "LMT" | "STP" | "STP LMT";
 
+/** Explicit account classification for order confirmation. Missing values are treated as unknown. */
+export type BrokerTradingMode = "simulation" | "live" | "unknown";
+
+/** Synchronous ticket metadata. Adapters may vary this by contract and order type. */
+export interface BrokerTradingCapabilities {
+  enabled: boolean;
+  disabledReason?: string;
+  orderTypes: BrokerOrderType[];
+  tif: string[];
+  extendedHours?: boolean;
+  /** When set, extended hours are available only for these time-in-force values. */
+  extendedHoursTif?: string[];
+  fractionalQuantity?: boolean;
+  /** Explicitly permits sells beyond a known long position. Omission blocks short sales. */
+  shortSelling?: boolean;
+  minQuantity?: number;
+  quantityStep?: number;
+  priceDecimals?: number;
+  /** Broker-reported price increment for this instrument/order. Omit if unknown. */
+  priceStep?: number;
+  modify?: boolean;
+  cancel?: boolean;
+  executionKind?: "fills" | "order-summaries";
+  /**
+   * Multi-leg option orders take up to this many legs (at least 2). Declared
+   * for a combo contract (`secType: "BAG"`); omit when the broker takes none.
+   */
+  maxLegs?: number;
+}
+
 export interface BrokerCashBalance {
   currency: string;
   quantity: number;
@@ -13,6 +43,9 @@ export interface BrokerCashBalance {
 export interface BrokerAccount {
   accountId: string;
   name: string;
+  tradingMode?: BrokerTradingMode;
+  /** Broker-reported account classification, such as Cash or Margin. Omit when unavailable. */
+  accountType?: string;
   currency?: string;
   /** "cloud" is a connection held by the user's Gloom Cloud account. */
   source?: "gateway" | "flex" | "cloud";
@@ -64,10 +97,25 @@ export interface BrokerPortfolioPerformance {
   points: BrokerPortfolioPerformancePoint[];
 }
 
+/**
+ * One leg of a multi-leg option order. The action is what happens to this
+ * contract when the order fills; the ratio is its contracts per spread.
+ */
+export interface BrokerOrderLeg {
+  contract: BrokerContractRef;
+  action: BrokerOrderAction;
+  ratio: number;
+}
+
 export interface BrokerOrderRequest {
   brokerInstanceId?: string;
   accountId?: string;
+  /** A combo contract (`secType: "BAG"`, the underlying's symbol) when the order has legs. */
   contract: BrokerContractRef;
+  /**
+   * BUY pays a net debit and SELL receives a net credit. With legs, the
+   * legs' own actions say which contracts are bought and sold.
+   */
   action: BrokerOrderAction;
   orderType: BrokerOrderType;
   quantity: number;
@@ -75,9 +123,23 @@ export interface BrokerOrderRequest {
   stopPrice?: number;
   tif?: string;
   outsideRth?: boolean;
+  /**
+   * 2 or more option legs filled as one order. `quantity` counts spreads and
+   * `limitPrice` is the positive net price of one spread.
+   */
+  legs?: BrokerOrderLeg[];
 }
 
 export interface BrokerOrderPreview {
+  currency?: string;
+  estimatedCost?: number;
+  fees?: number;
+  buyingPowerBefore?: number;
+  buyingPowerAfter?: number;
+  buyingPowerImpact?: number;
+  warnings?: string[];
+  /** Blocking broker validation errors. A ticket must not submit when these are present. */
+  errors?: string[];
   initMarginBefore?: number;
   initMarginAfter?: number;
   maintMarginBefore?: number;
@@ -91,6 +153,8 @@ export interface BrokerOrderPreview {
 
 export interface BrokerOrder {
   orderId: number;
+  /** Broker-native identity, scoped to profile and account. Numeric orderId remains the mutation handle. */
+  brokerOrderId?: string;
   brokerInstanceId?: string;
   accountId?: string;
   status: string;
@@ -108,12 +172,15 @@ export interface BrokerOrder {
   reviewUrl?: string;
   updatedAt: number;
   contract: BrokerContractRef;
+  /** A multi-leg order's legs, as on its request. */
+  legs?: BrokerOrderLeg[];
 }
 
 export interface BrokerExecution {
   execId: string;
   brokerInstanceId?: string;
   orderId?: number;
+  brokerOrderId?: string;
   accountId?: string;
   side: string;
   shares: number;

package/src/ui/host.tsx

@@ -447,6 +447,8 @@ export interface AsciiTextProps extends BoxProps {
 interface HostTabItem {
   label: string;
   value: string;
+  /** Artwork before the label, such as a logo; decoration only. */
+  leading?: ReactNode;
   disabled?: boolean;
   reorderable?: boolean;
   onClose?: (value: string) => void;
@@ -611,6 +613,8 @@ export interface HostMenuItem {
   checked?: boolean;
   /** Tints the label, e.g. a status in its tone; the words carry the meaning. */
   color?: string;
+  /** Artwork before the label, such as a logo; decoration only. */
+  leading?: ReactNode;
 }
 
 export interface HostMenuProps {

package/src/updater/failure.ts

@@ -0,0 +1,163 @@
+/**
+ * Why an update step failed, as a fixed phase and code rather than the error
+ * text: the header says the reason in a few words, and error tracking gets
+ * the same two values, which carry no path, URL or account name.
+ */
+
+/** The step that failed. `relaunch` is getting back into the app after an install. */
+export type UpdateFailurePhase = "check" | "download" | "verify" | "apply" | "relaunch";
+
+const UPDATE_FAILURE_CODES = [
+  /** No route to the release server: offline, DNS, refused, TLS. */
+  "offline",
+  "timeout",
+  /** GitHub answered 403 or 429, its limit for requests without an account. */
+  "rate_limited",
+  "server_error",
+  /** The release has no such file (404). */
+  "not_found",
+  /** Any other refusal from the release server. */
+  "http_error",
+  /** The release list or manifest did not read as one. */
+  "bad_response",
+  /** The release has no build for this platform, or none with a checksum. */
+  "no_build",
+  /** The download stopped before the whole file arrived. */
+  "interrupted",
+  /** The file arrived whole but does not match its checksum, or does not unpack. */
+  "corrupt",
+  "permission_denied",
+  /** The macOS app runs from where it cannot be replaced: a disk image, App Translocation, another volume. */
+  "wrong_location",
+  /** The downloaded update and the installed app are on different disks, so the one cannot be moved onto the other. */
+  "cross_device",
+  "read_only",
+  "disk_full",
+  /** Another process holds the files being replaced. */
+  "file_in_use",
+  /** The update downloaded earlier is no longer where the install expects it. */
+  "staged_missing",
+  /** A restart into the update came back on the old version. */
+  "not_applied",
+  /** The app quit with a downloaded update waiting and was opened again on the old version. */
+  "not_restarted",
+  /** The install finished but the app did not come back by itself. */
+  "relaunch_missed",
+  "unknown",
+] as const;
+
+export type UpdateFailureCode = typeof UPDATE_FAILURE_CODES[number];
+
+export interface UpdateFailure {
+  phase: UpdateFailurePhase;
+  code: UpdateFailureCode;
+}
+
+/** What an HTTP status from the release server means for an update. */
+export function httpStatusFailureCode(status: number): UpdateFailureCode {
+  if (status === 403 || status === 429) return "rate_limited";
+  if (status === 404 || status === 410) return "not_found";
+  if (status >= 500) return "server_error";
+  return "http_error";
+}
+
+const OFFLINE_ERRNO = new Set([
+  "ENOTFOUND",
+  "EAI_AGAIN",
+  "ECONNREFUSED",
+  "ENETUNREACH",
+  "EHOSTUNREACH",
+  "ENETDOWN",
+  // Bun's fetch
+  "ConnectionRefused",
+  "FailedToOpenSocket",
+  "UnableToConnect",
+  "CERT_HAS_EXPIRED",
+  "UNABLE_TO_GET_ISSUER_CERT_LOCALLY",
+  "SELF_SIGNED_CERT_IN_CHAIN",
+]);
+const INTERRUPTED_ERRNO = new Set(["ECONNRESET", "EPIPE", "ECONNABORTED", "ConnectionClosed"]);
+
+/**
+ * The code for an error a step threw, from its system error code first and its
+ * message second. Only the code leaves the machine; the message stays local.
+ */
+export function classifyUpdateError(error: unknown): UpdateFailureCode {
+  const record = (error && typeof error === "object" ? error : {}) as { code?: unknown; name?: unknown; message?: unknown };
+  const message = typeof record.message === "string" ? record.message : typeof error === "string" ? error : "";
+  // A system error code, or one named in the message ("Failed to replace app: EACCES: ...").
+  const errno = typeof record.code === "string" ? record.code : /\b(E[A-Z]{3,})\b/.exec(message)?.[1] ?? "";
+  switch (errno) {
+    case "EACCES":
+    case "EPERM":
+      return "permission_denied";
+    case "EROFS":
+      return "read_only";
+    case "ENOSPC":
+    case "EDQUOT":
+      return "disk_full";
+    case "EBUSY":
+    case "ETXTBSY":
+      return "file_in_use";
+    case "EXDEV":
+      return "cross_device";
+    case "ETIMEDOUT":
+      return "timeout";
+  }
+  if (OFFLINE_ERRNO.has(errno)) return "offline";
+  if (INTERRUPTED_ERRNO.has(errno)) return "interrupted";
+  if (record.name === "TimeoutError" || record.name === "AbortError") return "timeout";
+
+  const status = /\b(?:HTTP|returned|status|failed:?)\s*\(?(\d{3})\b/i.exec(message)?.[1];
+  if (status) return httpStatusFailureCode(Number(status));
+  if (/checksum mismatch|hash mismatch/i.test(message)) return "corrupt";
+  if (/zstd|decompress|gunzip|incorrect header|unexpected end of (?:file|data)/i.test(message)) return "corrupt";
+  if (/timed? ?out/i.test(message)) return "timeout";
+  if (/rate limit/i.test(message)) return "rate_limited";
+  if (/read-only file system/i.test(message)) return "read_only";
+  if (/cross-device/i.test(message)) return "cross_device";
+  if (/permission denied|operation not permitted|access is denied/i.test(message)) return "permission_denied";
+  if (/no space left|disk full/i.test(message)) return "disk_full";
+  if (/resource busy|text file busy|being used by another process/i.test(message)) return "file_in_use";
+  if (/connection (?:reset|closed|aborted)|socket hang up|premature close|terminated/i.test(message)) return "interrupted";
+  if (/unable to connect|fetch failed|failed to fetch|network|getaddrinfo|could not resolve|certificate/i.test(message)) return "offline";
+  if (/invalid update\.json|unexpected .*payload|json/i.test(message)) return "bad_response";
+  return "unknown";
+}
+
+/** When the failure has no more specific reason: what the step was. */
+const PHASE_REASONS: Record<UpdateFailurePhase, string> = {
+  check: "check failed",
+  download: "download failed",
+  verify: "could not verify the download",
+  apply: "could not install",
+  relaunch: "could not restart",
+};
+
+const CODE_REASONS: Partial<Record<UpdateFailureCode, string>> = {
+  offline: "no connection",
+  timeout: "connection timed out",
+  rate_limited: "GitHub rate limit",
+  server_error: "release server error",
+  not_found: "release server error",
+  http_error: "release server error",
+  bad_response: "unreadable release data",
+  no_build: "no build for this system",
+  interrupted: "download interrupted",
+  corrupt: "download corrupted",
+  permission_denied: "no permission to replace the app",
+  wrong_location: "move the app to Applications",
+  cross_device: "app and update on different disks",
+  read_only: "install folder is read-only",
+  disk_full: "disk full",
+  file_in_use: "app files in use",
+  staged_missing: "downloaded update missing",
+};
+
+/**
+ * The reason in a few words, in English (the caller translates it), sized
+ * for the header: "download interrupted", "no permission to replace the app".
+ */
+export function updateFailureReason(failure: UpdateFailure): string {
+  return CODE_REASONS[failure.code] ?? PHASE_REASONS[failure.phase];
+}

package/src/updater/index.ts

@@ -1,5 +1,13 @@
 import type { UpdateChannel } from "../types/config";
+import { reportUpdateFailure, type UpdateInstallKind } from "../telemetry/update-failures";
 import { compareSemver, isPrereleaseVersion } from "../utils/semver";
+import {
+  classifyUpdateError,
+  httpStatusFailureCode,
+  type UpdateFailure,
+  type UpdateFailureCode,
+  type UpdateFailurePhase,
+} from "./failure";
 import {
   GITHUB_LATEST_RELEASE_API_URL,
   GITHUB_RELEASES_API_URL,
@@ -49,6 +57,8 @@ export interface UpdateProgress {
   message?: string;
   /** With `ready`: this host can apply the update and relaunch on request. */
   canRestart?: boolean;
+  /** With `error`: the step that failed and why, which the header says in a few words. */
+  failure?: UpdateFailure;
 }
 
 export type UpdateAction =
@@ -68,7 +78,7 @@ export type UpdateCheckResult =
   /** `notice`: why a newer-looking state is not an update, such as a nightly build waiting for a stable release. */
   | { kind: "current"; notice?: string }
   | { kind: "disabled" }
-  | { kind: "error"; error: string };
+  | { kind: "error"; error: string; failure?: UpdateFailure };
 
 /**
  * On the stable channel a nightly build is never replaced by an older stable
@@ -302,6 +312,23 @@ export function canSelfUpdate(release: Pick<ReleaseInfo, "updateAction"> | null
   return release?.updateAction.kind === "self" || release?.updateAction.kind === "desktop";
 }
 
+/**
+ * Whether the install-update key has something to retry: a release this build
+ * can install itself whose last attempt failed. A fresh one downloads on its
+ * own, and a manual or managed one names its own command. (A downloaded
+ * desktop update has its own use of the key: restarting into it.)
+ */
+export function canRetryUpdate(state: {
+  updateAvailable: ReleaseInfo | null;
+  updateProgress: UpdateProgress | null;
+  updateCheckInProgress: boolean;
+}): boolean {
+  return !!state.updateAvailable
+    && state.updateProgress?.phase === "error"
+    && !state.updateCheckInProgress
+    && canSelfUpdate(state.updateAvailable);
+}
+
 /** A downloaded update this host can install and relaunch into when the user asks. */
 export function canRestartToApply(progress: UpdateProgress | null | undefined): boolean {
   return progress?.phase === "ready" && progress.canRestart === true;
@@ -344,6 +371,11 @@ export async function checkForUpdateDetailed(
     return { kind: "disabled" };
   }
   const nightly = channel === "nightly" && updateAction.kind === "self";
+  const failed = (error: string, code: UpdateFailureCode, targetVersion?: string): UpdateCheckResult => {
+    const failure: UpdateFailure = { phase: "check", code };
+    reportUpdateFailure(failure, { targetVersion, channel: nightly ? "nightly" : "stable" });
+    return { kind: "error", error, failure };
+  };
 
   let timeout: ReturnType<typeof setTimeout> | undefined;
   try {
@@ -356,7 +388,7 @@ export async function checkForUpdateDetailed(
     });
 
     if (!res.ok) {
-      return { kind: "error", error: `GitHub returned ${res.status}` };
+      return failed(`GitHub returned ${res.status}`, httpStatusFailureCode(res.status));
     }
 
     const payload = await res.json();
@@ -379,16 +411,10 @@ export async function checkForUpdateDetailed(
 
     const asset = resolveReleaseAsset(data.assets);
     if (!asset) {
-      return {
-        kind: "error",
-        error: `No compatible release asset found for ${getAssetBaseName()}`,
-      };
+      return failed(`No compatible release asset found for ${getAssetBaseName()}`, "no_build", version);
     }
     if (!asset.checksum) {
-      return {
-        kind: "error",
-        error: `Release asset ${asset.name} is missing a valid SHA-256 digest`,
-      };
+      return failed(`Release asset ${asset.name} is missing a valid SHA-256 digest`, "no_build", version);
     }
 
     return {
@@ -406,12 +432,10 @@ export async function checkForUpdateDetailed(
     };
   } catch (error: unknown) {
     if (error instanceof Error && error.name === "AbortError") {
-      return { kind: "error", error: "Update check timed out" };
+      return failed("Update check timed out", "timeout");
     }
-    return {
-      kind: "error",
-      error: error instanceof Error ? error.message : "Update check failed",
-    };
+    const code = classifyUpdateError(error);
+    return failed(error instanceof Error ? error.message : "Update check failed", code === "unknown" && error instanceof SyntaxError ? "bad_response" : code);
   } finally {
     if (timeout) clearTimeout(timeout);
   }
@@ -507,14 +531,20 @@ export async function performUpdate(
   }
 
   const checksum = /^[a-f\d]{64}$/i.exec(release.checksum ?? "")?.[0].toLowerCase();
+  const fail = (failure: UpdateFailure, error: string) => {
+    reportUpdateFailure(failure, { targetVersion: release.version, channel: release.channel });
+    onProgress({ phase: "error", error, failure });
+  };
   if (!checksum) {
-    onProgress({ phase: "error", error: "Self-update requires a valid SHA-256 checksum." });
+    fail({ phase: "verify", code: "no_build" }, "Self-update requires a valid SHA-256 checksum.");
     return;
   }
 
   const updatePath = execPath + ".update";
   const oldPath = execPath + ".old";
   let unlinkUpdatePath: ((path: string) => void) | null = null;
+  /** The step under way, which a thrown error is reported against. */
+  let phase: UpdateFailurePhase = "download";
 
   try {
     // Not import(): Bun folds even a specifier held in a variable and bundles
@@ -531,7 +561,7 @@ export async function performUpdate(
 
     const res = await fetch(release.downloadUrl);
     if (!res.ok || !res.body) {
-      throw new Error(`Download failed: ${res.status}`);
+      throw new UpdateStepError({ phase: "download", code: httpStatusFailureCode(res.status) }, `Download failed: ${res.status}`);
     }
 
     const contentLength = Number(res.headers.get("content-length") || 0);
@@ -540,7 +570,18 @@ export async function performUpdate(
     let received = 0;
 
     while (true) {
-      const { done, value } = await reader.read();
+      let chunk: Awaited<ReturnType<typeof reader.read>>;
+      try {
+        chunk = await reader.read();
+      } catch (error) {
+        // The connection broke partway: whatever it says, the file is incomplete.
+        const code = classifyUpdateError(error);
+        throw new UpdateStepError(
+          { phase: "download", code: code === "timeout" ? code : "interrupted" },
+          error instanceof Error ? error.message : "Download interrupted",
+        );
+      }
+      const { done, value } = chunk;
       if (done) break;
       chunks.push(value);
       received += value.length;
@@ -551,7 +592,14 @@ export async function performUpdate(
         });
       }
     }
+    if (contentLength > 0 && received < contentLength) {
+      throw new UpdateStepError(
+        { phase: "download", code: "interrupted" },
+        `Download stopped at ${received} of ${contentLength} bytes`,
+      );
+    }
 
+    phase = "verify";
     const downloaded = new Uint8Array(received);
     let offset = 0;
     for (const chunk of chunks) {
@@ -560,11 +608,12 @@ export async function performUpdate(
     }
     const actual = createHash("sha256").update(downloaded).digest("hex");
     if (actual !== checksum) {
-      throw new Error(`Checksum mismatch: expected ${checksum}, got ${actual}`);
+      throw new UpdateStepError({ phase: "verify", code: "corrupt" }, `Checksum mismatch: expected ${checksum}, got ${actual}`);
     }
     const nextBinary = release.compressed
       ? new Uint8Array(gunzipSync(downloaded))
       : downloaded;
+    phase = "apply";
     await Bun.write(updatePath, nextBinary);
     chmodSync(updatePath, 0o755);
 
@@ -600,9 +649,24 @@ export async function performUpdate(
     try {
       unlinkUpdatePath?.(updatePath);
     } catch { /* Intentional ignore: Remove a partial update download while the original failure is reported through update progress. */ }
-    onProgress({
-      phase: "error",
-      error: err instanceof Error ? err.message : "Update failed",
-    });
+    const failure = err instanceof UpdateStepError ? err.failure : { phase, code: classifyUpdateError(err) };
+    fail(failure, err instanceof Error ? err.message : "Update failed");
   }
 }
+
+/** A failed step whose code is known where it is thrown. */
+class UpdateStepError extends Error {
+  constructor(readonly failure: UpdateFailure, message: string) {
+    super(message);
+    this.name = "UpdateStepError";
+  }
+}
+
+/** How the running terminal app was installed, as update failure reports name it. */
+export function terminalInstallKind(action: UpdateAction | null = detectUpdateAction()): UpdateInstallKind {
+  if (!action) return "terminal-source";
+  if (action.kind === "self") return "terminal-binary";
+  if (action.kind === "managed") return "terminal-managed";
+  if (action.kind === "manual") return "terminal-package-manager";
+  return "unknown";
+}

package/src/utils/base-currency.ts

@@ -0,0 +1,108 @@
+import { currenciesNamed } from "./currency-names";
+import { isCurrencyCode } from "./currency-pair";
+import { isIsoCurrencyCode } from "./crypto-pair";
+
+/**
+ * Signs people write for a currency, as they read them: C$ and US$ as
+ * Canadians and Americans write them, S$, NZ$, R$. These settle a sign the
+ * runtime gives another currency too (C$ is also the cordoba's). The runtime
+ * adds CA$, A$, HK$, €, £, ₹ and the rest, so a sign several currencies use
+ * ($, ¥) names all of them.
+ */
+const EXTRA_SIGNS: ReadonlyArray<readonly [sign: string, code: string]> = [
+  ["US$", "USD"], ["U$S", "USD"], ["C$", "CAD"], ["CAN$", "CAD"], ["AU$", "AUD"], ["S$", "SGD"], ["SG$", "SGD"],
+  ["NZ$", "NZD"], ["R$", "BRL"], ["NT$", "TWD"], ["RMB", "CNY"], ["Fr", "CHF"], ["SFr", "CHF"], ["zł", "PLN"],
+  ["kr", "SEK"], ["kr", "NOK"], ["kr", "DKK"], ["kr", "ISK"], ["Kč", "CZK"], ["Ft", "HUF"], ["RM", "MYR"],
+  ["£", "GBP"], ["¥", "JPY"], ["¥", "CNY"],
+  ["$", "USD"], ["$", "CAD"], ["$", "AUD"], ["$", "NZD"], ["$", "HKD"], ["$", "SGD"], ["$", "MXN"],
+];
+
+/** The most traded currencies, first among those a shared sign ($, ¥, kr) names. */
+const SIGN_ORDER = ["USD", "EUR", "JPY", "GBP", "CNY", "CAD", "AUD", "CHF", "HKD", "SGD", "NZD", "MXN", "SEK", "NOK", "DKK"];
+
+let signIndex: ReadonlyMap<string, readonly string[]> | undefined;
+
+function signKey(sign: string): string {
+  return sign.normalize("NFC").replace(/\s+/g, "").toUpperCase();
+}
+
+function signs(): ReadonlyMap<string, readonly string[]> {
+  if (signIndex) return signIndex;
+  const built = new Map<string, string[]>();
+  const curated = new Set(EXTRA_SIGNS.map(([sign]) => signKey(sign)));
+  const add = (sign: string, code: string, extra = false) => {
+    const key = signKey(sign);
+    // A code is its own spelling, not a sign: CHF reads as the code.
+    if (!key || key === code || (!extra && curated.has(key))) return;
+    const codes = built.get(key) ?? [];
+    if (!codes.includes(code)) codes.push(code);
+    built.set(key, codes);
+  };
+  const codes = typeof Intl.supportedValuesOf === "function" ? Intl.supportedValuesOf("currency") : [];
+  for (const code of codes) {
+    if (!isCurrencyCode(code)) continue;
+    for (const currencyDisplay of ["symbol", "narrowSymbol"] as const) {
+      try {
+        const sign = new Intl.NumberFormat("en-US", { style: "currency", currency: code, currencyDisplay })
+          .formatToParts(0).find((part) => part.type === "currency")?.value;
+        if (sign) add(sign, code);
+      } catch {
+        // Intentional ignore: a code the runtime lists but cannot format has no sign to read.
+      }
+    }
+  }
+  for (const [sign, code] of EXTRA_SIGNS) add(sign, code, true);
+  const rank = (code: string) => {
+    const at = SIGN_ORDER.indexOf(code);
+    return at < 0 ? SIGN_ORDER.length : at;
+  };
+  for (const codesForSign of built.values()) codesForSign.sort((left, right) => rank(left) - rank(right));
+  signIndex = built;
+  return built;
+}
+
+/** The currencies a name (`Canadian dollar`, `yen`) or a sign (`CA$`, `C$`, `€`) stands for, most traded first. */
+function currenciesForNameOrSign(typed: string): string[] {
+  const named = currenciesNamed(typed).map(({ code }) => code);
+  if (named.length > 0) return named;
+  return [...signs().get(signKey(typed.trim())) ?? []];
+}
+
+/** What a typed base currency is: its ISO 4217 code, or why it is none and the codes it may have meant. */
+export type BaseCurrencyReading =
+  | { code: string }
+  | { error: string; suggestions: string[] };
+
+/**
+ * A base currency as `config set baseCurrency` takes it: an ISO 4217 code in
+ * any case (`cad` is CAD). A currency's name or sign (`Canadian dollar`,
+ * `CA$`) is refused with the code it stands for, so the setting is always a
+ * code the conversions can price; so is a code that is no currency (XAU, XYZ).
+ */
+export function readBaseCurrency(typed: string): BaseCurrencyReading {
+  const text = typed.trim();
+  const upper = text.toUpperCase();
+  if (/^[A-Z]{3}$/.test(upper) && isCurrencyCode(upper)) return { code: upper };
+  if (/^[A-Z]{3}$/.test(upper) && isIsoCurrencyCode(upper)) {
+    return { error: `${upper} is a metal, drawing-right or test code, not a currency.`, suggestions: [] };
+  }
+  const suggestions = text ? currenciesForNameOrSign(text) : [];
+  const shown = text ? JSON.stringify(text) : "An empty value";
+  if (suggestions.length === 1) return { error: `${shown} is not a currency code. Did you mean ${suggestions[0]}?`, suggestions };
+  if (suggestions.length > 1) {
+    return { error: `${shown} is not a currency code; it can be ${suggestions.slice(0, 6).join(", ")}.`, suggestions };
+  }
+  return { error: `${shown} is not an ISO 4217 currency code.`, suggestions };
+}
+
+/**
+ * A base currency as it was saved, as the setting reads it now: a code in
+ * capitals, and a name or sign an older version stored (`Canadian dollar`,
+ * `CA$`, `cad`) as the one code it stands for. Anything else stays as saved,
+ * for `doctor` and `config get` to flag, rather than turning into USD.
+ */
+export function normalizeStoredBaseCurrency(value: string): string {
+  const reading = readBaseCurrency(value);
+  if ("code" in reading) return reading.code;
+  return reading.suggestions.length === 1 ? reading.suggestions[0]! : value.trim();
+}