@gloom-sh/terminal 0.0.0-stage → 0.19.0

package/src/utils/sec-filings.ts

@@ -0,0 +1,245 @@
+import type { SecFilingItem } from "../types/data-provider";
+import { secFilingItemCodes } from "./sec";
+
+/**
+ * How many filings a full list asks for: the most the filings service
+ * returns for one issuer. A filter searches only these, so when an issuer has
+ * this many, older matching filings may exist.
+ */
+export const SEC_FILING_FETCH_LIMIT = 20_000;
+
+/**
+ * 8-K items in a few words, as a reader scans them: what happened, not the
+ * SEC's full caption. 9.01 (exhibits) comes with most reports and says little.
+ */
+const CURRENT_REPORT_ITEMS: Record<string, string> = {
+  "1.01": "Material agreement",
+  "1.02": "Agreement terminated",
+  "1.03": "Bankruptcy or receivership",
+  "1.04": "Mine safety",
+  "1.05": "Cybersecurity incident",
+  "2.01": "Acquisition or disposal",
+  "2.02": "Results of operations",
+  "2.03": "New financial obligation",
+  "2.04": "Obligation accelerated",
+  "2.05": "Exit or restructuring costs",
+  "2.06": "Impairment",
+  "3.01": "Listing standard notice",
+  "3.02": "Unregistered equity sale",
+  "3.03": "Shareholder rights modified",
+  "4.01": "Auditor change",
+  "4.02": "Non-reliance on financials",
+  "5.01": "Change in control",
+  "5.02": "Officer or director change",
+  "5.03": "Charter or bylaws amended",
+  "5.04": "Benefit plan trading suspension",
+  "5.05": "Code of ethics change",
+  "5.06": "Shell company status change",
+  "5.07": "Shareholder vote results",
+  "5.08": "Director nominations",
+  // An asset-backed issuer's (Regulation AB) events.
+  "6.01": "ABS informational material",
+  "6.02": "Servicer or trustee change",
+  "6.03": "Credit enhancement change",
+  "6.04": "Missed required distribution",
+  "6.05": "Securities Act update",
+  "6.06": "Static pool",
+  "6.10": "Alternative ABS filing",
+  "7.01": "Regulation FD disclosure",
+  "8.01": "Other events",
+  "9.01": "Exhibits",
+};
+
+export const isCurrentReportForm = (form: string) => /^(?:8-K|6-K)(?:\/A)?$/i.test(form.trim());
+
+/** The items a current report names, exhibits only when nothing else is reported. */
+function reportedItems(items: string | null | undefined): Array<{ code: string; name: string }> {
+  const codes = (secFilingItemCodes(items) ?? "").split(",").filter(Boolean);
+  return codes.filter((code) => code !== "9.01" || codes.length === 1)
+    .map((code) => ({ code, name: CURRENT_REPORT_ITEMS[code] ?? `Item ${code}` }));
+}
+
+/** `Results of operations; Regulation FD disclosure` from `2.02,7.01,9.01`. */
+export function currentReportItemNames(items: string | null | undefined): string | null {
+  const named = reportedItems(items).map((item) => item.name);
+  return named.length > 0 ? named.join("; ") : null;
+}
+
+/**
+ * `2.02 Results of operations; 7.01 Regulation FD disclosure` from
+ * `2.02,7.01,9.01`: the items with their numbers, for a list with no column
+ * of its own that says what a filing reports, so the earnings 8-K reads apart
+ * from another 8-K filed the same day.
+ */
+export function currentReportItemsLabel(items: string | null | undefined): string | null {
+  const named = reportedItems(items).map((item) => `${item.code} ${item.name}`);
+  return named.length > 0 ? named.join("; ") : null;
+}
+
+/** A form without its amendment suffix: `424B2/A` is `424B2`. */
+const formBase = (form: string) => form.trim().toUpperCase().replace(/\/A$/, "");
+
+/** The forms a note shelf files for each note it sells. */
+const isNoteSupplementForm = (form: string) => {
+  const base = formBase(form);
+  return base === "424B2" || base === "FWP";
+};
+
+/**
+ * The pricing supplements and term sheets of the notes an issuer sells off
+ * its shelf: a bank files one for each structured note, hundreds a week
+ * (JPM, WFC), as a 424B2 or a free writing prospectus. Another 424B
+ * prospectus counts when it calls itself one; a 424B3 is otherwise often a
+ * merger or resale prospectus, which stays, unless a note shelf files it
+ * among its supplements (pricingSupplementTest).
+ */
+export function isPricingSupplement(filing: Pick<SecFilingItem, "form" | "primaryDocDescription">): boolean {
+  if (isNoteSupplementForm(filing.form)) return true;
+  return /^424B\d$/.test(formBase(filing.form)) && /\b(?:PRICING SUPPLEMENT|TERM SHEET)\b/i.test(filing.primaryDocDescription ?? "");
+}
+
+/**
+ * A plain 424B3 is a note's term sheet when its filer filed at least this
+ * many 424B2 or FWP within SHELF_DAYS of it. A note shelf files hundreds a
+ * month (JPM, GS, MS, C, BAC) or dozens (US Bancorp, up to 52 in two months);
+ * a company selling bonds a handful (in any two months since 1994, AT&T at
+ * most 10, Apple 9). Over a list read back to 1994 Apple's, AT&T's and
+ * Microsoft's add up to dozens, so they are counted near the 424B3 only.
+ */
+const SHELF_SUPPLEMENTS = 20;
+const SHELF_DAYS = 30;
+const DAY_MS = 86_400_000;
+
+/** A filing date as a time; persistence can hand back the Date as a string. */
+const filedAt = (filing: Pick<SecFilingItem, "filingDate">) => new Date(filing.filingDate as Date | string).getTime();
+
+/** How many of the sorted `times` fall within [from, to]. */
+function countWithin(times: readonly number[], from: number, to: number): number {
+  const firstAtOrAfter = (value: number) => {
+    let low = 0;
+    let high = times.length;
+    while (low < high) {
+      const middle = (low + high) >> 1;
+      if (times[middle]! < value) low = middle + 1;
+      else high = middle;
+    }
+    return low;
+  };
+  return firstAtOrAfter(to + 1) - firstAtOrAfter(from);
+}
+
+/**
+ * Which of an issuer's filings are pricing supplements, read over the
+ * filings loaded: those isPricingSupplement names, and a plain 424B3 filed
+ * among a structured-note shelf's supplements (JPM files its note term
+ * sheets as `FORM 424B3`). A company's 424B3 merger or resale prospectus
+ * stays. Each filer (CIK) is read on its own.
+ */
+export function pricingSupplementTest(
+  filings: readonly SecFilingItem[],
+): (filing: Pick<SecFilingItem, "form" | "primaryDocDescription" | "cik" | "filingDate">) => boolean {
+  const supplements = new Map<string, number[]>();
+  for (const filing of filings) {
+    const time = filedAt(filing);
+    if (!isNoteSupplementForm(filing.form) || !Number.isFinite(time)) continue;
+    const times = supplements.get(filing.cik) ?? [];
+    times.push(time);
+    supplements.set(filing.cik, times);
+  }
+  for (const times of supplements.values()) times.sort((left, right) => left - right);
+  return (filing) => {
+    if (isPricingSupplement(filing)) return true;
+    if (formBase(filing.form) !== "424B3") return false;
+    const times = supplements.get(filing.cik);
+    const time = filedAt(filing);
+    if (!times || times.length < SHELF_SUPPLEMENTS || !Number.isFinite(time)) return false;
+    return countWithin(times, time - SHELF_DAYS * DAY_MS, time + SHELF_DAYS * DAY_MS) >= SHELF_SUPPLEMENTS;
+  };
+}
+
+/** A 13D or 13G beneficial-ownership schedule or its amendment, under the old (`SC 13G`) or current (`SCHEDULE 13G`) form name. */
+function isOwnershipSchedule(form: string): boolean {
+  return /^(?:SC|SCHEDULE) 13[DG](?:\/A)?$/i.test(form.trim());
+}
+
+/**
+ * A 13D or 13G the company filed as a holder of another company's shares.
+ * EDGAR lists a schedule under its filer as well as its subject, so a bank's
+ * or an asset manager's list holds hundreds about other companies (197 of
+ * JPM's last 199), and only one about the company carries its 005- file
+ * number. Who submitted it does not tell: an agent files both kinds. A
+ * filing whose file number the source did not give is kept.
+ */
+export function isScheduleAboutAnotherCompany(filing: Pick<SecFilingItem, "form" | "fileNumber">): boolean {
+  return typeof filing.fileNumber === "string" && isOwnershipSchedule(filing.form) && !/^005-/.test(filing.fileNumber.trim());
+}
+
+/** The filings a short list left out, by kind. */
+export interface HiddenFilings {
+  pricingSupplements: number;
+  /** The 13D/13G the company filed as a holder of other companies. */
+  ownershipReportsAboutOthers: number;
+}
+
+/**
+ * The first `limit` filings that are not left out, and how many of each kind
+ * sat among them: those filed since the last filing kept, or all of them when
+ * fewer than `limit` are kept.
+ */
+function keptFilings(
+  filings: readonly SecFilingItem[],
+  limit: number,
+  schedulesAboutOthers: boolean,
+): { filings: SecFilingItem[]; hidden: HiddenFilings } {
+  const kept: SecFilingItem[] = [];
+  const hidden: HiddenFilings = { pricingSupplements: 0, ownershipReportsAboutOthers: 0 };
+  const isSupplement = pricingSupplementTest(filings);
+  for (const filing of filings) {
+    if (kept.length >= limit) break;
+    if (isSupplement(filing)) hidden.pricingSupplements += 1;
+    else if (schedulesAboutOthers && isScheduleAboutAnotherCompany(filing)) hidden.ownershipReportsAboutOthers += 1;
+    else kept.push(filing);
+  }
+  return { filings: kept, hidden };
+}
+
+/**
+ * "28 pricing supplements and 22 ownership reports about other companies
+ * hidden, --all to show", or null when nothing was.
+ */
+export function hiddenFilingsNote(hidden: HiddenFilings): string | null {
+  const count = (value: number, one: string, many: string) =>
+    value > 0 ? `${value.toLocaleString("en-US")} ${value === 1 ? one : many}` : null;
+  const parts = [
+    count(hidden.pricingSupplements, "pricing supplement", "pricing supplements"),
+    count(hidden.ownershipReportsAboutOthers, "ownership report about another company", "ownership reports about other companies"),
+  ].filter((part): part is string => part != null);
+  return parts.length > 0 ? `${parts.join(" and ")} hidden, --all to show` : null;
+}
+
+/** Filings asked for first, a few times the rows wanted: supplements come in runs of dozens. */
+const FIRST_READ_MIN = 200;
+/** A read that leaves the list short is followed by one this many times larger. */
+const READ_GROWTH = 5;
+
+/**
+ * An issuer's latest `limit` filings without its pricing supplements and,
+ * with `schedulesAboutOthers`, the 13D/13G it filed as a holder of other
+ * companies. A bank's last hundreds of filings can be nearly all of these
+ * (192 of WFC's last 200 are supplements), so a first read asks for a few
+ * hundred, and each read that leaves the list short is followed by a five
+ * times larger one, up to the issuer in full.
+ */
+export async function loadLatestFilings(
+  load: (count: number) => Promise<SecFilingItem[]>,
+  limit: number,
+  { schedulesAboutOthers = false }: { schedulesAboutOthers?: boolean } = {},
+): Promise<{ filings: SecFilingItem[]; hidden: HiddenFilings }> {
+  let count = Math.min(SEC_FILING_FETCH_LIMIT, Math.max(FIRST_READ_MIN, limit * 4));
+  for (;;) {
+    const read = await load(count);
+    const kept = keptFilings(read, limit, schedulesAboutOthers);
+    if (kept.filings.length >= limit || read.length < count || count >= SEC_FILING_FETCH_LIMIT) return kept;
+    count = Math.min(SEC_FILING_FETCH_LIMIT, count * READ_GROWTH);
+  }
+}

package/src/utils/sec.ts

@@ -0,0 +1,258 @@
+import type { TickerRecord } from "../types/ticker";
+import { tickerHasListingSuffix } from "../sources/listing-symbols";
+import { canonicalExchange, exchangeLabel, parsePublicTickerKey, resolveExchangeTimeZone, US_LISTING_EXCHANGES } from "./exchanges";
+import { shortListingTitle } from "../tickers/company-name";
+
+/** Canonical US equity venues: the listing exchanges plus other lit and OTC venues. */
+const US_EQUITY_EXCHANGES = new Set([
+  ...US_LISTING_EXCHANGES,
+  "BYX",
+  "IEX",
+  "OTC",
+  "PINK",
+  // Listing codes for the OTC Markets tiers.
+  "PNK",
+  "OQB",
+  "OQX",
+  "OEM",
+  "OBB",
+]);
+
+/** Order-routing destinations, not listings. */
+const ROUTING_EXCHANGES = new Set(["SMART"]);
+
+function normalize(value?: string): string {
+  return (value ?? "").trim().toUpperCase();
+}
+
+function isUsExchange(value?: string): boolean {
+  return US_EQUITY_EXCHANGES.has(canonicalExchange(value));
+}
+
+function isEquityType(value?: string): boolean {
+  const normalized = normalize(value).replace(/[\s_-]/g, "");
+  return normalized.length === 0
+    || ["STK", "EQUITY", "ADR", "AMERICANDEPOSITARYRECEIPT", "COMMONSTOCK", "DEPOSITARYRECEIPT"].includes(normalized);
+}
+
+const FUND_TYPES = new Set(["ETF", "ETP", "FUND", "MUTUALFUND", "CEF", "CLOSEDEND", "CLOSEDENDFUND"]);
+
+/** An instrument type that names a fund (ETF, closed-end fund), which reports no earnings of its own. */
+export function isFundType(value?: string): boolean {
+  return FUND_TYPES.has(normalize(value).replace(/[\s_-]/g, ""));
+}
+
+/**
+ * Whether an equity SEC pane (filings, insider transactions) can show the
+ * ticker: an equity, or a type not filled in yet, that is not known to be
+ * listed outside the US. A ticker whose venue and currency were never filled
+ * in, as when its quote is unavailable, is looked up as a US ticker, as the
+ * SEC issuer lookup does with a symbol that names no venue.
+ */
+export function mayBeUsEquityTicker(ticker: TickerRecord | null | undefined): boolean {
+  return mayBeUsListingOfType(ticker, isEquityType);
+}
+
+/**
+ * `mayBeUsEquityTicker`, or an equity listed abroad on a venue its metadata
+ * names. The SEC lookup takes such a listing by its company, which either
+ * files there (Sanofi, a foreign private issuer) or files nothing
+ * (`noSecReportsNotice`); without the venue it cannot place the listing.
+ */
+export function mayBeSecEquityListing(ticker: TickerRecord | null | undefined): boolean {
+  if (mayBeUsEquityTicker(ticker)) return true;
+  return isTickerOfType(ticker, isEquityType) && nonUsSecListingVenue(ticker!.metadata.ticker, ticker!.metadata.exchange) != null;
+}
+
+/** The same for a view that also lists a US-listed fund's filings, which funds file with the SEC. */
+export function mayBeUsEquityOrFundTicker(ticker: TickerRecord | null | undefined): boolean {
+  return mayBeUsListingOfType(ticker, (type) => isEquityType(type) || isFundType(type));
+}
+
+function isTickerOfType(ticker: TickerRecord | null | undefined, acceptsType: (type?: string) => boolean): boolean {
+  if (!ticker) return false;
+  const primaryContract = ticker.metadata.broker_contracts?.[0];
+  return acceptsType(primaryContract?.secType ?? ticker.metadata.assetCategory);
+}
+
+function mayBeUsListingOfType(
+  ticker: TickerRecord | null | undefined,
+  acceptsType: (type?: string) => boolean,
+): boolean {
+  return isTickerOfType(ticker, acceptsType) && !isKnownNonUsListing(ticker);
+}
+
+/**
+ * The metadata places the listing outside the US: a non-USD currency, venues
+ * none of which is a US exchange, or, with no venue, a symbol that names one
+ * abroad (SAN:EPA, VOD.L, 7203.T). A missing currency or venue is unknown
+ * rather than foreign. SEC filings, FINRA short interest, 13F and
+ * congressional disclosures only cover US listings.
+ */
+export function isKnownNonUsListing(ticker: TickerRecord | null | undefined): boolean {
+  if (!ticker) return false;
+  const primaryContract = ticker.metadata.broker_contracts?.[0];
+  const currency = normalize(primaryContract?.currency ?? ticker.metadata.currency);
+  if (currency && currency !== "USD") return true;
+  const venues = [primaryContract?.primaryExchange, primaryContract?.exchange, ticker.metadata.exchange]
+    .map(normalize)
+    .filter((exchange) => exchange.length > 0 && !ROUTING_EXCHANGES.has(exchange));
+  if (venues.length > 0) return !venues.some((exchange) => isUsExchange(exchange));
+  const symbol = parsePublicTickerKey(ticker.metadata.ticker ?? "");
+  if (symbol.exchange) return !ROUTING_EXCHANGES.has(symbol.exchange) && !isUsExchange(symbol.exchange);
+  return tickerHasListingSuffix(symbol.symbol);
+}
+
+/**
+ * The metadata shows the ticker is not a US equity: a non-equity type or a
+ * listing known to be outside the US. A ticker with no venue or currency is
+ * unknown rather than foreign, e.g. an unsaved symbol whose quote is
+ * unavailable.
+ */
+export function isKnownNonUsEquityTicker(ticker: TickerRecord | null | undefined): boolean {
+  return !!ticker && !mayBeUsEquityTicker(ticker);
+}
+
+/**
+ * The venue an SEC issuer lookup has to respect: a listing outside the US,
+ * whose bare symbol the SEC may know as another company (SAN is Banco
+ * Santander in New York, Sanofi in Paris). Null for a US venue, a routing
+ * destination or no venue at all, which look the symbol up as a US ticker.
+ */
+export function nonUsSecListingVenue(ticker: string, exchange?: string): string | null {
+  const venue = parsePublicTickerKey(ticker).exchange ?? canonicalExchange(exchange);
+  if (!venue || ROUTING_EXCHANGES.has(venue) || isUsExchange(venue)) return null;
+  return venue;
+}
+
+// The zones of the US exchanges; a venue in another is abroad.
+const US_TIME_ZONES = new Set(["America/New_York", "America/Chicago"]);
+
+/**
+ * The exchange abroad a listing key names, for data that covers US listings
+ * only (US options and trades, FINRA short interest, the US earnings board):
+ * EPA for SAN:EPA, JPX for 7203:JPX. Null for a US exchange, no exchange, and
+ * venues with no home market (futures, currency and crypto venues), which
+ * such data reads by symbol.
+ */
+export function listingAbroadVenue(key: string): string | null {
+  const venue = nonUsSecListingVenue(key);
+  const zone = venue ? resolveExchangeTimeZone(venue) : null;
+  return venue && zone && zone !== "UTC" && !US_TIME_ZONES.has(zone) ? venue : null;
+}
+
+/** What `ticker` and ETF say of a fund listed abroad: the facts Gloom collects are the US-listed funds'. */
+export const US_FUND_FACTS_ONLY = "Fund facts (fee, NAV, premium) cover US-listed funds only.";
+
+/**
+ * The symbol data that covers US listings only reads a listing by: AAPL for
+ * AAPL:NASDAQ, ^SPX as it is. A listing abroad throws, naming what covers US
+ * listings only, rather than read its bare symbol, which can be another
+ * company's US ticker (SAN:EPA is Sanofi, SAN in New York Banco Santander).
+ */
+export function usListingSymbol(key: string, what: string): string {
+  const parsed = parsePublicTickerKey(key.trim());
+  const venue = listingAbroadVenue(key);
+  if (venue) throw new Error(`${what} covers US listings only, and ${parsed.symbol}:${venue} is listed on ${exchangeLabel(venue)}.`);
+  return parsed.symbol.toUpperCase();
+}
+
+/**
+ * "CAR Group (ASX) files no SEC reports.": what the SEC functions (filings,
+ * holders --form, insider and INS, in the CLI and the pane) say for a listing
+ * abroad whose company the SEC has nothing from.
+ */
+export function noSecReportsNotice(listing: { symbol: string; exchange: string; name: string | null }): string {
+  return `${shortListingTitle(listing)} files no SEC reports.`;
+}
+
+/** The country of a venue abroad, ISO 3166 alpha-2, for the companies an SEC report may list there. */
+const VENUE_COUNTRY: Readonly<Record<string, string>> = {
+  TSX: "CA", TSXV: "CA", CSE: "CA", NEO: "CA",
+  LSE: "GB",
+  ASX: "AU", CXA: "AU", NZX: "NZ",
+  SWX: "CH",
+  XETRA: "DE", FWB2: "DE", EPA: "FR", AMS: "NL", BRU: "BE", LIS: "PT", BIT: "IT", MCE: "ES", ISE: "IE",
+  SFB: "SE", HEL: "FI", CPH: "DK", OSL: "NO", ICEX: "IS", WSE: "PL", PSE: "CZ", VIE: "AT", WBDM: "AT",
+  JPX: "JP", HKEX: "HK", KRX: "KR", KOSDAQ: "KR", TWSE: "TW", TPEX: "TW", SSE: "CN", SZSE: "CN",
+  NSE: "IN", BSE: "IN", SGX: "SG", SET: "TH",
+  BMV: "MX", B3: "BR", BYMA: "AR", JSE: "ZA", TASE: "IL", BIST: "TR", TADAWUL: "SA",
+};
+
+/** The European Economic Area, whose issuers report managers' dealings under the Market Abuse Regulation. */
+const EEA = new Set(["AT", "BE", "CZ", "DE", "DK", "ES", "FI", "FR", "IE", "IS", "IT", "NL", "NO", "PL", "PT", "SE"]);
+
+/** Insider reports outside the SEC by the name they go by, by the issuer's country. */
+const HOME_INSIDER_REPORTS: Readonly<Record<string, string>> = {
+  CA: "Canadian insider reports (SEDI)",
+  GB: "UK insider reports (PDMR notifications)",
+  AU: "Australian insider reports (Appendix 3Y)",
+};
+
+/** The country of a venue abroad that a company's insiders may report in (TSX is CA); null for a US venue or one not placed. */
+export function venueHomeCountry(exchange: string | null | undefined): string | null {
+  return VENUE_COUNTRY[canonicalExchange(exchange ?? "")] ?? null;
+}
+
+/** A country's English name ("Japan"), or null when the runtime has none. */
+function countryName(code: string): string | null {
+  try {
+    const name = new Intl.DisplayNames(["en"], { type: "region" }).of(code);
+    return name && name !== code ? name : null;
+  } catch {
+    // Intentional ignore: a runtime without region names leaves the home market unnamed.
+    return null;
+  }
+}
+
+/**
+ * What a company from abroad's insiders report at home, which Form 4 data
+ * does not cover: "Canadian insider reports (SEDI) not covered." Where home
+ * is comes from the company's country (Gloom Cloud's issuer listings: RY in
+ * New York is Royal Bank of Canada), else its listing's venue abroad (RY:TSX).
+ * A foreign private issuer placed by neither gets its home market unnamed.
+ * Null for a US company, and for a US listing of a company that files as a
+ * domestic one, whose insiders file Form 4.
+ */
+export function homeInsiderReportsNote({ country, exchange, foreignPrivateIssuer = false }: {
+  /** The company's country, ISO 3166 alpha-2, when known. */
+  country?: string | null;
+  /** The listing's venue. */
+  exchange?: string | null;
+  foreignPrivateIssuer?: boolean;
+}): string | null {
+  const venueHome = venueHomeCountry(exchange) ?? "";
+  if (!venueHome && !foreignPrivateIssuer) return null;
+  // ZZ is the service's own word for a country it does not know.
+  const given = normalize(country ?? "");
+  const home = (given !== "ZZ" ? given : "") || venueHome;
+  if (home === "US") return null;
+  if (!home) return foreignPrivateIssuer ? "Home-market insider reports not covered." : null;
+  const named = HOME_INSIDER_REPORTS[home] ?? (EEA.has(home) ? "European insider reports (MAR managers' transactions)" : null);
+  if (named) return `${named} not covered.`;
+  const place = countryName(home);
+  return place ? `Insider reports filed in ${place} not covered.` : "Home-market insider reports not covered.";
+}
+
+/**
+ * The key an issuer read is cached and deduplicated under: the ticker as given
+ * for a US listing or a symbol with no venue, SYMBOL:VENUE for a listing
+ * elsewhere, so SAN in Paris and SAN in New York never share an entry.
+ */
+export function secListingKey(ticker: string, exchange?: string): string {
+  const venue = nonUsSecListingVenue(ticker, exchange);
+  return venue ? `${parsePublicTickerKey(ticker).symbol}:${venue}` : normalize(ticker);
+}
+
+/**
+ * The item codes in EDGAR's `items` field ("2.02,9.01"). EDGAR fills the same
+ * field with other values for some forms, such as the order dates of a CT
+ * ORDER ("20250123,20250123"); those are not items and are dropped.
+ */
+export function secFilingItemCodes(items: string | null | undefined): string | null {
+  const codes = (items ?? "")
+    .split(",")
+    .map((code) => code.trim())
+    .filter((code) => /^\d{1,2}\.\d{2}$/.test(code));
+  return codes.length > 0 ? codes.join(",") : null;
+}

package/src/utils/selection-clipboard.ts

@@ -0,0 +1,99 @@
+import { logFailure } from "./log-failure";
+import { type NativeRendererHost as CliRenderer } from "../ui";
+import { type KeyEventLike as KeyEvent } from "../react/input";
+
+function isDarwinWithBunSpawnSync(): boolean {
+  return typeof process !== "undefined"
+    && process.platform === "darwin"
+    && typeof Bun !== "undefined"
+    && typeof Bun.spawnSync === "function";
+}
+
+function readTextFromSystemClipboard(): string | null {
+  if (!isDarwinWithBunSpawnSync()) {
+    return null;
+  }
+
+  try {
+    const result = Bun.spawnSync(["pbpaste"], {
+      stdout: "pipe",
+      stderr: "ignore",
+    });
+    if (!result.success) {
+      return null;
+    }
+    return result.stdout.toString().replace(/\r\n/g, "\n");
+  } catch (error) {
+    logFailure("utils-selection-clipboard", "Could not read system clipboard")(error);
+    return null;
+  }
+}
+
+function copyTextToSystemClipboard(text: string): boolean {
+  if (text.length === 0 || !isDarwinWithBunSpawnSync()) {
+    return false;
+  }
+
+  try {
+    const result = Bun.spawnSync(["pbcopy"], {
+      stdin: new Blob([text]),
+      stdout: "ignore",
+      stderr: "ignore",
+    });
+    return result.success;
+  } catch (error) {
+    logFailure("utils-selection-clipboard", "Could not write system clipboard")(error);
+    return false;
+  }
+}
+
+function copySelectionText(
+  renderer: Pick<CliRenderer, "copyToClipboardOSC52">,
+  text: string,
+): boolean {
+  if (text.length === 0) {
+    return false;
+  }
+
+  return renderer.copyToClipboardOSC52?.(text) === true || copyTextToSystemClipboard(text);
+}
+
+export function copyActiveSelection(
+  renderer: Pick<CliRenderer, "getSelection" | "copyToClipboardOSC52">,
+): boolean {
+  const text = renderer.getSelection?.()?.getSelectedText() ?? "";
+  return copySelectionText(renderer, text);
+}
+
+export function isCopyShortcut(
+  event: Pick<KeyEvent, "name" | "super" | "meta" | "ctrl" | "shift">,
+): boolean {
+  const keyName = event.name?.toLowerCase() ?? "";
+  return keyName === "c" && (
+    event.super === true
+    || event.meta === true
+    || (event.ctrl === true && event.shift === true)
+  );
+}
+
+export function isPasteShortcut(
+  event: Pick<KeyEvent, "name" | "super" | "meta" | "ctrl" | "shift">,
+): boolean {
+  const keyName = event.name?.toLowerCase() ?? "";
+  return keyName === "v" && (
+    event.super === true
+    || event.meta === true
+    || (event.ctrl === true && event.shift === true)
+  );
+}
+
+export function pasteSystemClipboard(
+  renderer: Pick<CliRenderer, "keyInput">,
+): boolean {
+  const text = readTextFromSystemClipboard();
+  if (!text || !renderer.keyInput?.processPaste) {
+    return false;
+  }
+  renderer.keyInput.processPaste(new TextEncoder().encode(text));
+  return true;
+}