@thematica/prism-tui 0.0.0-stage → 0.1.0-beta.0

package/dist/src/market/amounts.d.ts

@@ -0,0 +1,208 @@
+/**
+ * Amounts in other currencies, in US dollars (Ben, 2026-10-22: "Use the Federal Reserve's daily
+ * rates, at each report's period end", shown in US dollars with the original in brackets). Pure
+ * functions: reading a fact's amount as its sheet writes it ("R$6.5 billion", "CHF 45 million"),
+ * with its quote and its report's currency; picking the dated rate for it; converting it. The rates
+ * come from assets.exchange_rates (src/market/exchange-rates.ts). A stored fact never changes: the
+ * dollar figure is derived, and carries the rate, its day and its source.
+ *
+ * An amount is converted only when its currency is clear (Prism's rule, 2026-10-23); otherwise it is
+ * shown as written. A mark that names one currency ("R$", "RMB", "€", "US$", "CHF") is clear. An
+ * ambiguous one ("¥", "Ps.", a bare "$") is settled by the fact's quote, when a clear mark or code
+ * stands beside the same number there ("approximately RMB 600 million", "10 million RMB"), else by
+ * the report's currency where the rules below allow, else not at all. A clear mark the quote
+ * contradicts gives nothing.
+ *
+ * And how every amount is written for readers (Ben, 2026-10-23: "Use the standard format: US$303.2B
+ * in lists, US$303,154 million beside the quote, ISO codes where a currency symbol is shared"): the
+ * currency's label (currencyLabel), then the number short in lists and sentences (amountShort,
+ * figureDisplay) or as the filing writes it with its scale word beside a quote (amountFull).
+ */
+/** An amount read from its text: the currency's ISO code, the number as written and what it is counted in. */
+export interface AmountReading {
+    /** ISO 4217 code: "BRL" for "R$6.5 billion". */
+    currency: string;
+    /** The number as written, negative when it is in brackets or has a minus sign: 6.5 for "R$6.5 billion". */
+    number: number;
+    /** What the number counts in: 1e9 for "billion", 1e3 for "thousand", 1 when nothing is said. */
+    multiplier: number;
+    /** A word before the amount that says it is not exact, as written: "approximately", "over", "more than". */
+    qualifier?: string;
+}
+/**
+ * The currencies a fact's quote names beside a number, as a clear mark or code before it or words
+ * after it. Ambiguous marks ("$", "¥", "Ps.") name none. Empty when the quote does not hold the
+ * number, or holds it with no clear currency.
+ */
+export declare function quoteCurrencies(quote: string | null | undefined, numberText: string): Set<string>;
+/**
+ * An amount's parts as written, for showing it (since 2026-10-23; readAmountParts). `currency` is null
+ * for an amount of money whose currency is not clear.
+ */
+export interface AmountParts extends Omit<AmountReading, "currency"> {
+    /** ISO 4217 code, or null when it is not clear: no mark at all ("2,995,255 thousand"), an ambiguous mark nothing settles, or a mark the quote contradicts. */
+    currency: string | null;
+    /** The number exactly as written, with its sign or brackets: "303,154", "(1,404)", "1,2". */
+    written: string;
+    /** Its scale word as Prism writes it: "million" for "million", "mn" or "Mio."; "thousand" for "ThUS$"; "" for none. */
+    scale: string;
+    /** Words after the amount, such as "per share" or "a year"; "" for none. */
+    tail: string;
+}
+/**
+ * A fact's amount as its sheet writes it, read as currency, number and multiplier; null when it is
+ * not an amount of money with a clear currency: a count ("50 years", "158,000 sites"), a share, a
+ * range, two amounts, an unknown mark, a number with no currency at all, a number written unclearly
+ * ("US$1,271,1 million", "R$534.669 thousand", "R$5 mil"), or an ambiguous mark that neither the
+ * quote nor the report settles. `reportCurrency` is the currency of the report the sheet was written
+ * from (asset_data.filings.currency); null reads as a report in US dollars. `quote` is the fact's own
+ * quote: a clear currency beside the same number there settles an ambiguous mark, and one that
+ * differs from a clear mark makes the amount unclear. The amount must start the text, after a word
+ * such as "approximately"; words after it, such as "a year" or "per share", are allowed.
+ */
+export declare function readAmount(text: string | null | undefined, reportCurrency: string | null | undefined, quote?: string | null): AmountReading | null;
+/**
+ * An amount read as readAmount reads it, with what showing it needs: the number as written, its
+ * scale word and the words after it. Where readAmount gives nothing only because the currency is not
+ * clear, this gives the amount with `currency` null: a number with no mark at all and nothing after
+ * it ("2,995,255 thousand"; a count names its unit, "50 years", and stays no amount), an ambiguous
+ * mark neither the quote nor the report settles ("¥700 million" in a report in reais), or a mark the
+ * quote contradicts. Whether the text is an amount at all does not depend on the report or the quote.
+ */
+export declare function readAmountParts(text: string | null | undefined, reportCurrency: string | null | undefined, quote?: string | null): AmountParts | null;
+/** A word before an amount that says it is not exact ("over €1 billion" gives "over"), or "". */
+export declare function leadingQualifier(text: string | null | undefined): string;
+/** One dated rate: US dollars per one unit of the currency on a day, and where it came from. */
+export interface Rate {
+    currency: string;
+    /** The day the rate is for, YYYY-MM-DD. */
+    date: string;
+    usdPerUnit: number;
+    /** "federal-reserve-h10". */
+    source: string;
+}
+/** The rates an amount may be converted at. */
+export interface RateTable {
+    /** Each currency's rates, newest first. */
+    readonly byCurrency: ReadonlyMap<string, readonly Rate[]>;
+    /** Each currency's latest stored day: a period end after it waits for a later load. */
+    readonly lastDay: ReadonlyMap<string, string>;
+}
+/** A table of rates. `lastDay` is each currency's latest stored day; left out, it is the latest of `rates`. */
+export declare function rateTable(rates: readonly Rate[], lastDay?: ReadonlyMap<string, string>): RateTable;
+/** No rates at all: every amount in another currency is shown as written. */
+export declare const NO_RATES: RateTable;
+/** How far back from a report's period end a rate may be: weekends and holidays have none (Prism's rule, 2026-10-23). */
+export declare const RATE_WINDOW_DAYS = 10;
+/** The day `days` before a YYYY-MM-DD day. */
+export declare function daysBefore(day: string, days: number): string;
+/**
+ * The rate on `day`, or the latest one before it within RATE_WINDOW_DAYS; null when there is none,
+ * and when `day` is after the currency's latest stored day: until a load reaches that day, the last
+ * rate before it may not be the one for it.
+ */
+export declare function pickRate(table: RateTable, currency: string, day: string): Rate | null;
+/**
+ * The rate an amount was converted at, as the API gives it: the amount's currency, US dollars per
+ * unit, its day and source. A type, not an interface, so an answer holding it is still JSON to Kysely.
+ */
+export type Fx = {
+    currency: string;
+    rate: number;
+    date: string;
+    source: string;
+};
+/** The report an amount comes from: its currency and its period end (asset_data.filings.currency and report_date). */
+export interface ReportOf {
+    currency: string | null;
+    periodEnd: string | null;
+}
+/**
+ * An amount in US dollars: as written when it is in dollars (fx null), or at the rate on its report's
+ * period end (fx says which). Null when the text is not an amount with a clear currency (readAmount,
+ * with the fact's quote), or no rate is near enough; such an amount is shown only as written.
+ */
+export declare function inUsd(text: string | null | undefined, report: ReportOf, rates: RateTable, quote?: string | null): {
+    usd: number;
+    fx: Fx | null;
+} | null;
+/**
+ * Several amounts given as one figure (the most-money line joins a company's figures with " + "),
+ * each with its fact's quote: their sum in US dollars, with the one rate used. Null when any of them
+ * has no dollars, or when they are in two currencies other than the dollar, so the line shows its
+ * originals only.
+ */
+export declare function sumInUsd(parts: ReadonlyArray<{
+    text: string;
+    quote?: string | null;
+}>, report: ReportOf, rates: RateTable): {
+    usd: number;
+    fx: Fx | null;
+} | null;
+/**
+ * The label an amount's number follows: "US$", "C$", "€" or "R$"; for every other currency, and any
+ * whose symbol other currencies share (¥ for yen and yuan, kr, Ps., S/, R, Fr), its ISO code and a
+ * space: "JPY ", "CNY ", "PEN ".
+ */
+export declare const currencyLabel: (code: string) => string;
+/**
+ * A million or more written short, with one decimal in billions and trillions (Ben, 2026-10-23:
+ * "US$303.2B"): "1.2T", "303.2B", "19.2B", "962M", and under ten million one decimal, "2.5M".
+ */
+export declare function shortNumber(v: number): string;
+/** US dollars written short, as an amount Prism converted reads: "US$1.2B", "US$962M", "US$2.5M", "US$37,313", "US$1.33". */
+export declare function usdShort(usd: number): string;
+/** The rate amounts were converted at, in words said once after them: "at the Federal Reserve's rate of 2025-12-31"; empty when none was converted. */
+export declare function rateNote(fxs: ReadonlyArray<Fx | null | undefined>): string;
+/**
+ * An amount to show: its text as the sheet writes it; its parts (readAmountParts), null when the text
+ * is not one amount of money; and `scaleConfirmed` false when the fact's value says its scale is not
+ * confirmed (`scale_confirmed: false`, set by the scale repair).
+ */
+export interface AmountToShow {
+    text: string;
+    parts: AmountParts | null;
+    scaleConfirmed?: boolean;
+}
+/**
+ * An amount in its own currency, and the notes on what is not clear about it, apart, so a caller can
+ * put them in brackets after it or after a comma inside brackets. Short: the label and the number
+ * written short ("R$14.2B"); below a million, or with a decimal comma, the full number. Full: the
+ * label, the number as the filing writes it and its scale word ("R$14,153.8 million"). Not an amount:
+ * as written. An amount whose currency is not clear: as written, noted.
+ */
+export declare function amountAndNotes(a: AmountToShow, form: "short" | "full"): {
+    text: string;
+    notes: string[];
+};
+/** An amount in lists and sentences: "US$303.2B", "PEN 10.9B", "¥700 million (currency not stated)", "US$303,154 (scale not confirmed)". */
+export declare const amountShort: (a: AmountToShow) => string;
+/** An amount beside its quote: "US$303,154 million", "R$14,153.8 million", "PEN 10,876,215,000". */
+export declare const amountFull: (a: AmountToShow) => string;
+/** What a converted amount is in US dollars, said beside the full form: "(about US$2.6B at the Federal Reserve's rate of 2025-12-31)"; empty when it was not converted. */
+export declare function aboutUsd(usd: number | null | undefined, fx: Fx | null | undefined): string;
+/**
+ * A figure of one or more amounts (the most-money line joins them with " + ") as lists and sentences
+ * show it: each amount short; when Prism converted it into US dollars, the dollars first and the
+ * originals in brackets, "US$2.6B (R$14.2B)", a word such as "over" kept with both, and any note
+ * after the whole. The rate is said by whoever shows the figure, after its period.
+ */
+export declare function figureDisplay(amounts: readonly AmountToShow[], converted: {
+    usd: number;
+    fx: Fx | null;
+} | null | undefined): string;
+/**
+ * What the API gives with a figure so callers can show it (since 2026-10-23): its currency, null
+ * when it is not clear or not money, or when the figure's amounts are in different currencies; its
+ * multiplier as read (1, 1,000, 1,000,000, 1,000,000,000), null when its amounts differ; and
+ * `display`, the figure exactly as Prism's lists and sentences show it (figureDisplay).
+ */
+export declare function amountFields(amounts: readonly AmountToShow[], converted: {
+    usd: number;
+    fx: Fx | null;
+} | null | undefined): {
+    currency: string | null;
+    multiplier: number | null;
+    display: string;
+};
+//# sourceMappingURL=amounts.d.ts.map

package/dist/src/market/amounts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"amounts.d.ts","sourceRoot":"","sources":["../../../../../src/market/amounts.ts"],"names":[],"mappings":"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"}