gloomberb 0.18.0 → 0.18.1

package/src/portfolio/mutations.ts

@@ -39,6 +39,13 @@ export interface SetManualPortfolioPositionInput {
    * read does not unsize it.
    */
   multiplier?: number;
+  /** The purchase date, YYYY-MM-DD. Left out, a single manual lot keeps the one it had. */
+  dateAcquired?: string;
+  /**
+   * The rate the cost was bought at: one unit of `currency` in `costFx.currency`.
+   * Null clears it; left out, a single manual lot in the same currency keeps the one it had.
+   */
+  costFx?: { rate: number; currency: string } | null;
 }
 
 /** What a position's size counts, as its field and messages name it. */
@@ -406,8 +413,14 @@ export function setManualPortfolioPosition(
   const replacedPositionCount = replacedPositions.length;
   // Editing a single snapshot (for example after a split) does not change its
   // acquisition date. A consolidated replacement of several lots has no one date.
-  const dateAcquired = replacedPositions.length === 1 && replacedPositions[0]?.broker === "manual"
-    ? replacedPositions[0].dateAcquired : undefined;
+  const single = replacedPositions.length === 1 && replacedPositions[0]?.broker === "manual" ? replacedPositions[0] : null;
+  const dateAcquired = input.dateAcquired ?? single?.dateAcquired;
+  // The rate the cost was bought at goes with its cost: a lot kept in its currency keeps it unless it is replaced or cleared.
+  const keptCostFx = single && single.currency?.trim().toUpperCase() === nextCurrency
+    && typeof single.costFxRate === "number" && single.costFxCurrency
+    ? { rate: single.costFxRate, currency: single.costFxCurrency } : null;
+  const costFx = input.costFx === undefined ? keptCostFx : input.costFx;
+  if (costFx && !(Number.isFinite(costFx.rate) && costFx.rate > 0)) throw new Error("The cost FX rate must be a positive number.");
   // A contract's size does not change with the count held; one the lots agree on carries over.
   const keptMultipliers = new Set(replacedPositions.map((position) => position.multiplier));
   const keptMultiplier = keptMultipliers.size === 1 ? [...keptMultipliers][0] : undefined;
@@ -422,6 +435,7 @@ export function setManualPortfolioPosition(
     currency: nextCurrency,
     broker: "manual",
     ...(dateAcquired ? { dateAcquired } : {}),
+    ...(costFx ? { costFxRate: costFx.rate, costFxCurrency: costFx.currency.trim().toUpperCase() } : {}),
     ...(multiplier !== undefined ? { multiplier } : {}),
   });
 

package/src/portfolio/position-metrics.ts

@@ -3,7 +3,7 @@ import type { Quote } from "../types/financials";
 import type { PriceBasis } from "../types/instrument";
 import { resolvePriceBasis } from "../market-data/market/price-basis";
 import { getActiveQuoteDisplay, type ActiveQuoteDisplay } from "../market-data/market/status";
-import { resolveCurrencyUnit } from "../utils/currency-units";
+import { heldCurrencyUnit, resolveCurrencyUnit } from "../utils/currency-units";
 import { isFuturesTicker } from "./futures-positions";
 
 export interface PortfolioPositionMetrics {
@@ -103,6 +103,42 @@ function resolvePositionCostMultiplier(position: TickerRecord["metadata"]["posit
   return withoutMultiplierError < withMultiplierError ? 1 : priceMultiplier;
 }
 
+/**
+ * The rate a lot's cost converts at when valued in `valuationCurrency`: the
+ * one it was bought at (`costFxRate`), when that rate converts into this very
+ * currency and the lot is held in another. Null otherwise, and the cost
+ * converts at today's rate as its value does.
+ */
+export function lotCostFxRate(
+  position: Pick<TickerPosition, "costFxRate" | "costFxCurrency">,
+  positionCurrency: string,
+  valuationCurrency: string,
+): number | null {
+  const rate = position.costFxRate;
+  const into = position.costFxCurrency?.trim();
+  if (typeof rate !== "number" || !Number.isFinite(rate) || rate <= 0 || !into) return null;
+  return into === valuationCurrency.trim() && !sameCurrency(positionCurrency, into) ? rate : null;
+}
+
+/** Two currency codes in one currency, its minor units included: GBp is GBP, USX is USD. */
+export function sameCurrency(left: string, right: string): boolean {
+  return heldCurrencyUnit(left).currency === heldCurrencyUnit(right).currency;
+}
+
+/**
+ * Whether a lot's cost, valued in `valuationCurrency`, converts at today's
+ * rate: it is held in another currency and no rate from when it was bought
+ * applies, so its P&L leaves out the currency's move since.
+ */
+export function lotCostAtTodaysRate(
+  position: Pick<TickerPosition, "costFxRate" | "costFxCurrency">,
+  positionCurrency: string,
+  valuationCurrency: string,
+): boolean {
+  return !!positionCurrency.trim() && !sameCurrency(positionCurrency, valuationCurrency)
+    && lotCostFxRate(position, positionCurrency, valuationCurrency) === null;
+}
+
 export function getPortfolioPositionMetrics(
   ticker: TickerRecord,
   activeTab: string | undefined,
@@ -128,6 +164,11 @@ export function getPortfolioPositionMetrics(
     if (!currency) return Number.NaN;
     return valuation ? valuation.convert(value, currency) : currencies.size > 1 ? Number.NaN : value;
   };
+  // A cost converts at the rate the lot was bought at, when it has one into the valuation's currency.
+  const convertCost = (value: number, position: typeof positions[number]) => {
+    const bought = valuation ? lotCostFxRate(position, currencyFor(position), valuation.currency) : null;
+    return bought !== null ? value * bought : convert(value, position);
+  };
   const metrics: PortfolioPositionMetrics = {
     positionCurrency, positionCount: positions.length, hasShorts: false,
     totalShares: 0, totalCost: 0, hasCostBasis: positions.length > 0, priceBasis, signedCost: 0, totalCostUnits: 0,
@@ -169,8 +210,8 @@ export function getPortfolioPositionMetrics(
     metrics.unknownContractSize ||= unknownSize && !Number.isFinite(position.marketValue);
     if (Number.isFinite(contractMultiplier)) metrics.multiplierHint = Math.max(metrics.multiplierHint, contractMultiplier);
     metrics.totalShares += magnitude * direction;
-    metrics.totalCost += convert(cost, position);
-    metrics.signedCost += direction * convert(cost, position);
+    metrics.totalCost += convertCost(cost, position);
+    metrics.signedCost += direction * convertCost(cost, position);
     metrics.totalCostUnits += magnitude * costMultiplier;
     metrics.totalPriceUnits += magnitude * quoteMultiplier * direction;
     metrics.grossPriceUnits += magnitude * quoteMultiplier;
@@ -191,7 +232,7 @@ export function getPortfolioPositionMetrics(
     if (pnl == null || !Number.isFinite(pnl)) metrics.hasBrokerPnl = false;
     else metrics.brokerPnl += convert(pnl, position);
     metrics.pnlLots.push({
-      signedCost: direction * convert(cost, position),
+      signedCost: direction * convertCost(cost, position),
       priceUnits: magnitude * quoteMultiplier * direction,
       direction,
       brokerMarketValue: marketValue != null && Number.isFinite(marketValue) ? convert(marketValue, position) : null,

package/src/portfolio/position-quantity.ts

@@ -0,0 +1,43 @@
+import { resolveAssetDisplayKind } from "../market-data/market/format";
+import type { TickerRecord } from "../types/ticker";
+import { ambiguousNumberMessage, thousandsDotReadings } from "../utils/decimal-comma";
+import { isKnownNonUsListing } from "../utils/sec";
+import { isFuturesTicker } from "./futures-positions";
+import { positionQuantityLabel, type PositionQuantityLabel } from "./mutations";
+
+/** Fund units are issued in fractions wherever the fund is listed. */
+const FRACTIONAL_FUND_TYPES = new Set(["FUND", "MUTUALFUND"]);
+
+/**
+ * Whether a listing is held in whole units: a future's or an option's
+ * contracts, and shares listed outside the US, which trade in whole lots
+ * (THYAO.IS, SAP:XETRA). US shares, which brokers split into fractions,
+ * mutual funds, coins, currencies and bonds may be held in fractions.
+ */
+function tradesInWholeUnits(ticker: TickerRecord): boolean {
+  const kind = resolveAssetDisplayKind({ assetCategory: ticker.metadata.assetCategory });
+  if (isFuturesTicker(ticker) || kind === "contract") return true;
+  const category = ticker.metadata.assetCategory?.trim().toUpperCase().replace(/[\s_-]/g, "") ?? "";
+  const shares = kind === "equity" ? !FRACTIONAL_FUND_TYPES.has(category) : kind === "other" && !category;
+  return shares && isKnownNonUsListing(ticker);
+}
+
+/**
+ * Why a typed size cannot be stored as read: a dot and three digits (`1.250`)
+ * on a listing held in whole units, where it is far likelier the thousands
+ * grouping many locales write (1,250 shares) than a quarter of a share, so the
+ * command asks which, as it does for `1,250`. Null for any other size, and
+ * for a listing that may be held in fractions, where `1.250` is 1.25.
+ */
+export function wholeUnitQuantityProblem(
+  typed: string,
+  ticker: TickerRecord,
+  options: { label?: PositionQuantityLabel; listing?: string } = {},
+): string | null {
+  const reading = thousandsDotReadings(typed);
+  if (!reading || !tradesInWholeUnits(ticker)) return null;
+  const label = options.label ?? positionQuantityLabel(ticker);
+  const listing = options.listing ?? ticker.metadata.ticker;
+  const because = `${listing} trades in whole ${label === "Contracts" ? "contracts" : "shares"}`;
+  return `${label} ${ambiguousNumberMessage(typed, reading, { because })}.`;
+}

package/src/sources/gloomberb-cloud/fred-series.ts

@@ -53,9 +53,34 @@ export function resetFredSeriesPersistence(): void {
   cache.reset();
 }
 
-/** The series' page on the FRED site, where its notes and release schedule live. */
+/** Who publishes a series Gloom Cloud serves in FRED's shape that FRED does not carry, and its page. */
+interface SeriesNotOnFred {
+  /** Who compiles the figures (TurkStat). */
+  publisher: string;
+  /** Whose publication they are read from (the CBRT). */
+  via: string;
+  url: string;
+}
+
+const TURKISH_CPI: SeriesNotOnFred = {
+  publisher: "TurkStat",
+  via: "the CBRT",
+  url: "https://www.tcmb.gov.tr/wps/wcm/connect/EN/TCMB+EN/Main+Menu/Statistics/Inflation+Data/Consumer+Prices",
+};
+
+const NOT_ON_FRED: Readonly<Record<string, SeriesNotOnFred>> = {
+  TURCPIYOY: TURKISH_CPI,
+  TURCPIMOM: TURKISH_CPI,
+};
+
+/** The publisher of a served series FRED does not carry; null for FRED's own. */
+export function seriesNotOnFred(seriesId: string): SeriesNotOnFred | null {
+  return NOT_ON_FRED[seriesId.trim().toUpperCase()] ?? null;
+}
+
+/** The series' page on the FRED site, where its notes and release schedule live, or its publisher's page when FRED does not carry it. */
 export function fredSeriesUrl(seriesId: string): string {
-  return `https://fred.stlouisfed.org/series/${seriesId}`;
+  return seriesNotOnFred(seriesId)?.url ?? `https://fred.stlouisfed.org/series/${seriesId}`;
 }
 
 function cacheKey(request: FredSeriesRequest): string {

package/src/sync/core-contributors.ts

@@ -264,6 +264,7 @@ function sanitizePosition(position: TickerPosition): TickerPosition {
     avgCost: position.avgCost,
     currency: position.currency,
     dateAcquired: position.dateAcquired,
+    ...(position.costFxRate != null && position.costFxCurrency ? { costFxRate: position.costFxRate, costFxCurrency: position.costFxCurrency } : {}),
     broker: position.broker,
     side: position.side,
     marketValue: position.marketValue,

package/src/team/collections.ts

@@ -174,6 +174,8 @@ export function applyMembership(
       currency: position?.currency ?? currency,
       broker: "manual",
       ...(!flipped && position?.dateAcquired ? { dateAcquired: position.dateAcquired } : {}),
+      // So does the rate its cost was bought at, with its cost.
+      ...(!flipped && position?.costFxRate != null && position.costFxCurrency ? { costFxRate: position.costFxRate, costFxCurrency: position.costFxCurrency } : {}),
       // A future's contract size stays with the holding when the team changes its count.
       ...(position?.multiplier ? { multiplier: position.multiplier } : {}),
     });

package/src/tickers/metadata.ts

@@ -9,6 +9,15 @@ const DEFAULT_TICKER_METADATA: Omit<TickerMetadata, "ticker" | "exchange" | "cur
   tags: [],
 };
 
+/** A lot's cost FX rate, kept only whole: a positive rate and the currency it converts into. */
+function hydrateCostFx(raw: Record<string, unknown>): Pick<TickerPosition, "costFxRate" | "costFxCurrency"> {
+  const rate = raw.costFxRate ?? raw.cost_fx_rate;
+  const currency = raw.costFxCurrency ?? raw.cost_fx_currency;
+  return typeof rate === "number" && Number.isFinite(rate) && rate > 0 && typeof currency === "string" && currency.trim()
+    ? { costFxRate: rate, costFxCurrency: currency.trim() }
+    : {};
+}
+
 function hydratePosition(raw: Record<string, unknown>): TickerPosition {
   const avgCost = Object.hasOwn(raw, "avgCost") ? raw.avgCost : raw.avg_cost;
   return {
@@ -18,6 +27,7 @@ function hydratePosition(raw: Record<string, unknown>): TickerPosition {
     priceBasis: raw.priceBasis === "per-unit" || raw.priceBasis === "percent-of-par" ? raw.priceBasis : undefined,
     currency: (raw.currency as string) ?? undefined,
     dateAcquired: (raw.dateAcquired ?? raw.date_acquired) as string | undefined,
+    ...hydrateCostFx(raw),
     broker: (raw.broker as string) ?? "manual",
     side: (raw.side as "long" | "short") ?? undefined,
     marketValue: (raw.marketValue ?? raw.market_value) as number | undefined,

package/src/types/ticker.ts

@@ -8,6 +8,15 @@ export interface TickerPosition {
   priceBasis?: PriceBasis;
   currency?: string;
   dateAcquired?: string;
+  /**
+   * What one unit of the lot's `currency` cost in `costFxCurrency` when it was
+   * bought: entered with the position, or the FX close of its purchase date.
+   * Valued in that currency, the lot's cost converts at this rate rather than
+   * today's, so its P&L carries the currency's move since.
+   */
+  costFxRate?: number;
+  /** The currency `costFxRate` converts the cost into: the portfolio's when it was entered. */
+  costFxCurrency?: string;
   broker: string; // "manual" | future broker plugin IDs
   side?: "long" | "short";
   marketValue?: number;

package/src/utils/currency-units.ts

@@ -64,6 +64,15 @@ export interface CurrencyUnitInfo {
   divisor: number;
 }
 
+/**
+ * The currency money held in a code is counted in, and how many of the code
+ * make one of it: resolveCurrencyUnit's, and US cents as a hundredth of a
+ * dollar, which a lot's cost in USX is.
+ */
+export function heldCurrencyUnit(currency?: string | null): CurrencyUnitInfo {
+  return currency?.trim().toUpperCase() === US_CENTS ? { currency: "USD", divisor: 100 } : resolveCurrencyUnit(currency);
+}
+
 interface ExchangeSubUnitOptions {
   allowDefaultCurrency?: boolean;
   allowMissingCurrency?: boolean;