@gloom-sh/terminal 0.19.0 → 0.19.1

package/src/utils/crypto-pair.ts

@@ -1,4 +1,4 @@
-import { canonicalExchange, parsePublicTickerKey } from "./exchanges";
+import { canonicalExchange, EXCHANGE_TIME_ZONES, isKnownExchangeCode, parsePublicTickerKey } from "./exchanges";
 
 // The fiat codes a pair against USD is read as FX for, never as a coin. The
 // list Cloud reads: it serves these pairs by the same rule, so a copy judged
@@ -9,8 +9,8 @@ const FIAT_CURRENCY_CODES = new Set([
 ]);
 
 const USD_COIN_PAIR = /^([A-Z0-9]+)[-/]USD$/;
-// The other currencies and coins the crypto venue quotes a coin in (BTC-EUR, ETH-BTC).
-const QUOTED_COIN_PAIR = /^([A-Z0-9]+)[-/](?:USDT|USDC|EUR|GBP|BTC|ETH)$/;
+// The other currencies and coins the crypto venue quotes a coin in (BTC-EUR, BTC-JPY, ETH-BTC).
+const QUOTED_COIN_PAIR = /^([A-Z0-9]+)[-/](?:USDT|USDC|EUR|GBP|JPY|KRW|CAD|INR|CNY|AUD|BTC|ETH)$/;
 
 /** A coin quoted in dollars (BTC-USD, ETH/USD). EUR-USD is spot FX, not a coin. */
 function isUsdCoinPair(symbol: string): boolean {
@@ -35,10 +35,18 @@ export function isRoundTheClockCoin(symbol?: string, exchange?: string): boolean
   const parsed = symbol ? parsePublicTickerKey(symbol) : null;
   const venue = canonicalExchange(parsed?.exchange ?? exchange) || canonicalExchange(exchange);
   if (venue === "CCC" || canonicalExchange(exchange) === "CCC") return true;
+  if (parsed && exchangeLineCoinListing(parsed.symbol, venue)) return true;
   return !!parsed && (isUsdCoinPair(parsed.symbol) || (!venue && isQuotedCoinPair(parsed.symbol)));
 }
 
-const SLASH_COIN_PAIR = /^([A-Z0-9]{1,15})\/(USD|EUR|GBP|USDT|USDC|BTC)$/;
+const SLASH_COIN_PAIR = /^([A-Z0-9]{1,15})\/(USD|EUR|GBP|JPY|KRW|CAD|INR|CNY|AUD|USDT|USDC|BTC|ETH)$/;
+
+/**
+ * What the crypto venue (CCC) quotes a coin in: BTC-GBP, BTC-KRW, LINK-ETH.
+ * It has no coin in a stablecoin (BTC-USDT) or in most other currencies
+ * (BTC-TRY, BTC-BRL).
+ */
+const VENUE_QUOTE_LEGS: ReadonlySet<string> = new Set(["USD", "EUR", "GBP", "JPY", "KRW", "CAD", "INR", "CNY", "AUD", "BTC", "ETH"]);
 
 let isoCurrencyCodes: ReadonlySet<string> | null = null;
 
@@ -58,9 +66,114 @@ export function dashedCoinPair(symbol: string): string | null {
   return `${match[1]}-${match[2]}`;
 }
 
+/**
+ * The crypto exchanges whose own lines of a coin pair search lists in a currency the crypto venue quotes coins in,
+ * and the venue itself. A slash pair saved on any other venue, or on none, is not read as a coin: on the commodity
+ * or currency venue it is spot crude, gold by the gram or a currency (WTI/USD, GAU/USD, RUB/USD).
+ */
+const COIN_EXCHANGES: ReadonlySet<string> = new Set([
+  "CCC", "BIGONE", "BINANCE", "BITBANK", "BITBNS", "BITFINEX", "BITFLYER", "BITHUMB", "BITMART", "BITRUE", "BITSTAMP",
+  "BTC MARKETS", "BYBIT", "CEX.IO", "COINBASE PRO", "COINONE", "CRYPTO.COM EXCHANGE", "FREIEXCHANGE", "GATE.IO", "HITBTC",
+  "HUOBI", "INDEPENDENT RESERVE", "KRAKEN", "KUCOIN", "LATOKEN", "MEXC", "MXC", "OKEX", "OKX", "POLONIEX", "SYNTHETIC",
+  "UNISWAP", "UPBIT", "WAZIRX", "XT.COM", "YOBIT", "ZAIF",
+]);
+
+/** Venues whose slash pairs are commodities or currencies, never coins, whatever a row's type says. */
+const NOT_COIN_VENUES: ReadonlySet<string> = new Set(["COMMODITY", "CCY", "FX", "FOREX", "CURRENCY", "PHYSICAL CURRENCY"]);
+
+/**
+ * Spot commodities written as a pair: gold, silver, platinum and palladium, gold and silver by the gram (GAU,
+ * XAGG), WTI, Brent (XBR) and Urals crude, and copper (HG1). Never a coin, though tokens share the letters
+ * (GAU-USD is Gamer Arena).
+ */
+const SPOT_COMMODITY_BASES: ReadonlySet<string> = new Set(["XAU", "GAU", "XAG", "XAGG", "XPT", "XPD", "WTI", "XBR", "URALS", "HG1"]);
+
+/** A spot commodity's pair (WTI/USD, GAU/USD) or a pair on the commodity or currency venue, which no coin is. */
+export function isSpotCommodityOrCurrencyPair(symbol: string, exchange?: string): boolean {
+  const parsed = parsePublicTickerKey(symbol.trim().toUpperCase());
+  const named = (parsed.exchange ?? exchange ?? "").trim().toUpperCase();
+  const base = /^([A-Z0-9]{1,15})\//.exec(parsed.symbol)?.[1];
+  return !!base && (SPOT_COMMODITY_BASES.has(base) || NOT_COIN_VENUES.has(named) || NOT_COIN_VENUES.has(canonicalExchange(named)));
+}
+
+/** The crypto venue's listing of a coin pair written with a slash (BTC/GBP); null for a currency, a spot commodity or another leg. */
+function slashCoinPairListing(symbol: string): { symbol: string; exchange: "CCC"; currency: string } | null {
+  const match = SLASH_COIN_PAIR.exec(symbol.trim().toUpperCase());
+  if (!match) return null;
+  const [, base, quote] = match as unknown as [string, string, string];
+  if (isIsoCurrencyCode(base) || SPOT_COMMODITY_BASES.has(base) || !VENUE_QUOTE_LEGS.has(quote)) return null;
+  return { symbol: `${base}-${quote}`, exchange: "CCC", currency: quote };
+}
+
+/**
+ * A crypto exchange's own line of a coin pair (BTC/GBP on COINBASE PRO, LINK/EUR on KRAKEN, DOGE/BTC on BINANCE)
+ * as the crypto venue's listing of it, in the currency it is quoted in: BTC-GBP on CCC, in pounds. Search offers
+ * those lines, and no source quotes them.
+ *
+ * Only a pair on a crypto exchange (COIN_EXCHANGES) is one, or a search row whose type says it is a coin
+ * (`coinRow`) on a venue that is no stock, commodity or currency venue. Null for a currency pair (EUR/USD,
+ * RUB/USD), a spot commodity (XAU/USD, WTI/USD), a pair the venue quotes in no such currency (BTC/USDT), a pair
+ * with no venue, and a slash on a stock exchange, which is a share class (BRK/B).
+ */
+export function exchangeLineCoinListing(
+  symbol: string,
+  exchange?: string,
+  { coinRow = false }: { coinRow?: boolean } = {},
+): { symbol: string; exchange: "CCC"; currency: string } | null {
+  const parsed = parsePublicTickerKey(symbol);
+  const listing = slashCoinPairListing(parsed.symbol);
+  if (!listing) return null;
+  const named = (parsed.exchange ?? exchange ?? "").trim().toUpperCase();
+  const venue = canonicalExchange(named);
+  if (COIN_EXCHANGES.has(named) || COIN_EXCHANGES.has(venue)) return listing;
+  if (!coinRow || !venue || NOT_COIN_VENUES.has(named) || NOT_COIN_VENUES.has(venue)) return null;
+  // The crypto venues trade around the clock; a venue the app knows that does not is a stock exchange.
+  return isKnownExchangeCode(venue) && EXCHANGE_TIME_ZONES[venue] !== "UTC" ? null : listing;
+}
+
+/**
+ * A coin pair typed with a slash (btc/gbp) as the crypto venue's listing of it, BTC-GBP on CCC; with a venue
+ * (BTC/GBP:KRAKEN), as that exchange's line reads (exchangeLineCoinListing). Null for a currency pair, a spot
+ * commodity (wti/usd) and a pair the venue quotes in no such currency.
+ */
+export function typedCoinPairListing(query: string): { symbol: string; exchange: "CCC"; currency: string } | null {
+  const parsed = parsePublicTickerKey(query.trim().toUpperCase());
+  return parsed.exchange ? exchangeLineCoinListing(parsed.symbol, parsed.exchange) : slashCoinPairListing(parsed.symbol);
+}
+
+/**
+ * Search rows with each crypto exchange's line of a coin pair (ETH/EUR on KRAKEN, COINBASE PRO, BITSTAMP and
+ * BINANCE) as the crypto venue's one listing of it, ETH-EUR on CCC in euros, where the first line stood. A pair
+ * already offered on the venue is not offered twice. Newer servers send the listing themselves.
+ */
+export function withExchangeLinesAsCoinListings<T extends { symbol: string; exchange: string; type: string; currency?: string; brokerContract?: unknown }>(rows: T[]): T[] {
+  const offered = new Set(rows.filter((row) => canonicalExchange(row.exchange) === "CCC").map((row) => row.symbol.trim().toUpperCase()));
+  let changed = false;
+  const mapped = rows.flatMap((row) => {
+    const coin = !row.brokerContract && isCoinRowType(row.type) ? exchangeLineCoinListing(row.symbol, row.exchange, { coinRow: true }) : null;
+    if (!coin) return [row];
+    changed = true;
+    if (offered.has(coin.symbol)) return [];
+    offered.add(coin.symbol);
+    return [{ ...row, symbol: coin.symbol, exchange: coin.exchange, currency: row.currency || coin.currency }];
+  });
+  return changed ? mapped : rows;
+}
+
+/** Whether a search row's type says it is a coin (CRYPTOCURRENCY, Digital Currency). */
+export function isCoinRowType(type: string | undefined): boolean {
+  return /CRYPTO|DIGITAL|COIN/i.test(type ?? "");
+}
+
+/** The currency or coin a pair on the crypto venue is quoted in: GBP for BTC-GBP; null for anything else. */
+export function coinPairQuoteCurrency(symbol: string): string | null {
+  const match = /^([A-Z0-9]{1,15})-([A-Z]{3})$/.exec(parsePublicTickerKey(symbol).symbol);
+  return match && !isIsoCurrencyCode(match[1]!) && VENUE_QUOTE_LEGS.has(match[2]!) ? match[2]! : null;
+}
+
 // A base-quote pair such as BTC-USD or SOL-EUR. Equities with a share-class dash (BRK-B) and
 // currency pairs (EURUSD=X) do not match.
-const CRYPTO_PAIR = /^[A-Z0-9]{1,15}-(?:USD|EUR|GBP|USDT|USDC|BTC)$/;
+const CRYPTO_PAIR = /^[A-Z0-9]{1,15}-(?:USD|EUR|GBP|JPY|KRW|CAD|INR|CNY|AUD|USDT|USDC|BTC|ETH)$/;
 
 /**
  * Wider than isUsdCoinPair, for the hint under a pair that will not load: it
@@ -135,9 +248,10 @@ export const TOP_COIN_NAMES: ReadonlyMap<string, string> = new Map([
   ["RENDER", "render"],
 ]);
 
-const COIN_PAIR = /^([A-Z0-9]{1,15})[-/](?:USD|EUR|GBP|USDT|USDC|BTC)$/;
+const COIN_PAIR = /^([A-Z0-9]{1,15})[-/](?:USD|EUR|GBP|JPY|KRW|CAD|INR|CNY|AUD|USDT|USDC|BTC|ETH)$/;
 // What a pair's listing name adds after the coin's: its quote currency, an id in brackets.
-const PAIR_NAME_SUFFIX = /(?:\s*\([^)]*\))+$|\s+(?:USD|EUR|GBP|USDT|USDC|BTC|US Dollars?)$/i;
+// Not ETH, which ends coins' own names (Lido Staked ETH).
+const PAIR_NAME_SUFFIX = /(?:\s*\([^)]*\))+$|\s+(?:USD|EUR|GBP|JPY|KRW|CAD|INR|CNY|AUD|USDT|USDC|BTC|US Dollars?)$/i;
 
 /**
  * The coin a crypto pair trades, as stories name it: "bitcoin" for BTC-USD

package/src/utils/declared-dividends.ts

@@ -34,6 +34,6 @@ export function declaredDividends(
     const at = Date.parse(`${exDate}T00:00:00Z`);
     if (paid.some((time) => Math.abs(time - at) <= SAME_DISTRIBUTION_DAYS * DAY_MS)) return [];
     return [{ exDate, amount: row.amount, ...declarationDate ? { declarationDate } : {},
-      ...recordDate ? { recordDate } : {}, ...payDate ? { payDate } : {} }];
+      ...recordDate ? { recordDate } : {}, ...payDate ? { payDate } : {}, ...row.special === true ? { special: true as const } : {} }];
   }).sort((left, right) => left.exDate.localeCompare(right.exDate));
 }

package/src/utils/fundamentals.ts

@@ -2,6 +2,7 @@ import { formatFxRate } from "../cli/fx-pair";
 import type { EnterpriseValueCheck, Fundamentals, Quote, TickerFinancials } from "../types/financials";
 import { quotedFxPair } from "./currency-pair";
 import { resolveCurrencyUnit } from "./currency-units";
+import { isUsListingExchange } from "./exchanges";
 import { formatCompact } from "./format";
 import { formatUtcTime } from "./utc-time";
 
@@ -119,24 +120,53 @@ export function computedEnterpriseValueNote(fundamentals: Parameters<typeof ente
 }
 
 /** What names the currency of the trailing figures: the fundamentals' own labels, else the statements' on a listing that trades in theirs. */
-type FundamentalsCurrencies = Pick<TickerFinancials, "financialCurrency"> & {
+type FundamentalsCurrencies = Pick<TickerFinancials, "financialCurrency" | "statementHistory"> & {
   fundamentals?: Pick<Fundamentals, "financialCurrency" | "epsCurrency" | "marketCapCurrency"> | null;
-  quote?: Pick<Quote, "currency"> | null;
+  quote?: Pick<Quote, "currency" | "exchangeName" | "listingExchangeName" | "isDepositaryReceipt"> | null;
 };
 
+/** What a caller knows of the listing beyond its quote: the day it listed (its IPO's), when known. */
+interface ListingAge {
+  listedSince?: string | null;
+  now?: Date;
+}
+
+/** A listing that started within about a year: its statements may not be served yet. */
+const RECENT_LISTING_DAYS = 372;
+
+/**
+ * The listing's own currency, standing in for figures with no statements to tell their currency by: only for a
+ * listing of the last year or so (a recent IPO such as HAWK) or a US listing in dollars that is no receipt, and
+ * never after a statements read that failed. A minor unit (GBp) does not say whether figures are pence or pounds.
+ */
+function listingCurrencyFallback(financials: FundamentalsCurrencies | null | undefined, listing: ListingAge): string | undefined {
+  const listed = financials?.fundamentals?.marketCapCurrency?.trim() || financials?.quote?.currency?.trim();
+  if (!listed || resolveCurrencyUnit(listed).divisor !== 1) return undefined;
+  if (financials?.statementHistory?.status === "retryable-failure") return undefined;
+  const currency = resolveCurrencyUnit(listed).currency;
+  const since = listing.listedSince ? Date.parse(`${listing.listedSince.slice(0, 10)}T00:00:00Z`) : NaN;
+  const recent = Number.isFinite(since) && (listing.now ?? new Date()).getTime() - since <= RECENT_LISTING_DAYS * 86_400_000;
+  const quote = financials?.quote;
+  const home = currency === "USD" && quote?.isDepositaryReceipt !== true
+    && isUsListingExchange(quote?.listingExchangeName || quote?.exchangeName);
+  return recent || home ? currency : undefined;
+}
+
 /**
  * The currency of the trailing EPS, revenue, income and cash flows: the one the fundamentals declare for themselves.
  * A block that declares none is in the statements' currency only when the listing trades in it; on a listing quoted
  * in another (a receipt in USD beside TWD books, YPFD in ARS beside USD statements) its currency is unknown, since
- * Gloom Cloud labels every block whose currency it can tell. Never the quote's.
+ * Gloom Cloud labels every block whose currency it can tell. With no statements to tell by, the listing's own
+ * currency where that is safe (listingCurrencyFallback).
  */
 export function fundamentalsCurrency(
   financials: FundamentalsCurrencies | null | undefined,
+  listing: ListingAge = {},
 ): string | undefined {
   const declared = financials?.fundamentals?.financialCurrency?.trim();
   if (declared) return declared;
   const statements = financials?.financialCurrency?.trim();
-  if (!statements) return undefined;
+  if (!statements) return listingCurrencyFallback(financials, listing);
   const listed = financials?.fundamentals?.marketCapCurrency?.trim() || financials?.quote?.currency?.trim();
   return !listed || resolveCurrencyUnit(listed).currency === resolveCurrencyUnit(statements).currency ? statements : undefined;
 }
@@ -147,8 +177,9 @@ export function fundamentalsCurrency(
  */
 export function fundamentalsEpsCurrency(
   financials: FundamentalsCurrencies | null | undefined,
+  listing: ListingAge = {},
 ): string | undefined {
-  return financials?.fundamentals?.epsCurrency?.trim() || fundamentalsCurrency(financials);
+  return financials?.fundamentals?.epsCurrency?.trim() || fundamentalsCurrency(financials, listing);
 }
 
 const ISO_DAY = /^\d{4}-\d{2}-\d{2}$/;

package/src/version.ts

@@ -3,7 +3,7 @@ import packageJson from "../package.json" with { type: "json" };
 export const VERSION = packageJson.version;
 
 /**
- * The npm package this copy came from: `gloomberb`, or `@gloom-sh/terminal`
- * once releases are also published under that name.
+ * The npm package this copy came from: `@gloom-sh/terminal` or `gloomberb`,
+ * which every release publishes with the same build.
  */
 export const PACKAGE_NAME = packageJson.name;