@financica/ecb-client 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0
+
+Initial release.
+
+- `EcbClient` with `getRate`, `getRates`, and `convert` against the ECB data
+  API (dataflow `EXR`, `text/csv`).
+- Historical single-day lookups with last-business-day fallback via
+  `lastNObservations`; the effective observation date is reported on every rate.
+- Euro-crossed conversion between any two reference currencies.
+- Injectable `fetch`, in-process snapshot cache, request timeout.
+- Zero runtime dependencies; ESM + CJS builds with type declarations.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Financica
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# @financica/ecb-client
+
+Tiny, zero-dependency TypeScript client for the **European Central Bank's euro
+foreign-exchange reference rates**, with first-class support for **historical
+single-day lookups** and **last-business-day fallback**.
+
+- **Authoritative source.** Reads the ECB data API directly (dataflow `EXR`).
+  No third-party middleman, no API key, no SLA in front of your numbers. ECB
+  reference rates are the rates EU tax authorities accept for currency
+  conversion (VAT Directive art. 91).
+- **Point-in-time.** Ask for a rate "on or before" any date; the ECB only
+  publishes on TARGET business days, so weekends and holidays transparently
+  resolve to the most recent prior business day. The effective date is reported
+  back on every rate.
+- **Cross rates.** Every ECB rate is quoted against the euro; the client crosses
+  two foreign currencies through EUR for you.
+- **Tiny & typed.** Zero runtime dependencies, ESM + CJS, strict types, an
+  injectable `fetch`, and an in-process snapshot cache.
+
+## Install
+
+```sh
+npm install @financica/ecb-client
+```
+
+Requires Node 18+ (uses the global `fetch`).
+
+## Usage
+
+```ts
+import { EcbClient } from "@financica/ecb-client";
+
+const ecb = new EcbClient();
+
+// A single rate (units of the currency per 1 EUR) on a given day.
+await ecb.getRate("USD", "2024-01-15");
+// → { currency: "USD", rate: 1.0945, date: "2024-01-15" }
+
+// Weekends/holidays fall back to the last business day; the effective
+// date comes back on the result.
+await ecb.getRate("USD", "2024-01-13"); // a Saturday
+// → { currency: "USD", rate: 1.0942, date: "2024-01-12" }
+
+// Convert an amount. Non-euro pairs cross through EUR.
+await ecb.convert({ amount: 100, from: "USD", to: "EUR", date: "2024-01-15" });
+// → { amount: 91.36…, rate: 0.9136…, from: "USD", to: "EUR",
+//     requestedDate: "2024-01-15", rateDate: "2024-01-15" }
+
+// Several currencies for one date, in a single request.
+const snapshot = await ecb.getRates("2024-01-15", ["USD", "GBP", "CHF"]);
+// → { requestedDate: "2024-01-15", rates: [ { currency, rate, date }, … ] }
+```
+
+## API
+
+### `new EcbClient(options?)`
+
+| option      | default                                      | description                                              |
+| ----------- | -------------------------------------------- | -------------------------------------------------------- |
+| `baseUrl`   | `https://data-api.ecb.europa.eu/service`     | ECB data API base URL.                                   |
+| `fetch`     | global `fetch`                               | Custom fetch (testing, proxying).                        |
+| `cache`     | unbounded in-process `Map`                   | Snapshot cache keyed by request. Pass `null` to disable. |
+| `timeoutMs` | `15000`                                      | Per-request timeout. `0` disables it.                    |
+
+### `getRate(currency, date) → Promise<ReferenceRate>`
+
+The rate for one currency on (or before) `date`. `date` is a `YYYY-MM-DD`
+string or a `Date`. `EUR` returns a unit rate without a network call. Throws
+`NoRateError` when no observation exists on or before the date.
+
+### `getRates(date, currencies?) → Promise<RateSnapshot>`
+
+Rates for several currencies on (or before) `date`. Omit `currencies` to fetch
+every series the ECB publishes — note that **discontinued series resolve to
+their own last-published date**, so check each rate's `date` rather than
+assuming the requested one.
+
+### `convert({ amount, from, to, date }) → Promise<ConvertResult>`
+
+Convert `amount` from one currency to another. Identical currencies are a no-op
+(no request). The result reports the applied `rate` and the `rateDate` actually
+used.
+
+## How rates are quoted
+
+Every value is **units of the quoted currency per 1 EUR** (the ECB convention).
+So `getRate("USD", …).rate === 1.0945` means `1 EUR = 1.0945 USD`. To go from
+USD to EUR, divide; from EUR to USD, multiply; `convert()` handles both and the
+cross-currency case.
+
+## Caveats
+
+- **Business days only.** No observation on weekends or TARGET holidays; the
+  client resolves to the last prior business day for you.
+- **~30 active currencies, all against EUR.** Cross rates are computed through
+  EUR. Discontinued series (e.g. `ARS`) still return, at a stale date.
+- **Be a good citizen.** The ECB data API is a public good with no SLA. The
+  built-in cache deduplicates repeated lookups; cache aggressively in your app.
+
+## License
+
+MIT © Financica

package/dist/index.cjs

@@ -0,0 +1,291 @@
+'use strict';
+
+// src/currencies.ts
+var ECB_CURRENCIES = [
+  "AUD",
+  "BGN",
+  "BRL",
+  "CAD",
+  "CHF",
+  "CNY",
+  "CZK",
+  "DKK",
+  "GBP",
+  "HKD",
+  "HUF",
+  "IDR",
+  "ILS",
+  "INR",
+  "ISK",
+  "JPY",
+  "KRW",
+  "MXN",
+  "MYR",
+  "NOK",
+  "NZD",
+  "PHP",
+  "PLN",
+  "RON",
+  "SEK",
+  "SGD",
+  "THB",
+  "TRY",
+  "USD",
+  "ZAR"
+];
+var BASE_CURRENCY = "EUR";
+var ECB_CURRENCY_SET = new Set(ECB_CURRENCIES);
+var isEcbCurrency = (code) => ECB_CURRENCY_SET.has(code);
+
+// src/csv.ts
+var parseCsv = (text) => {
+  const rows = splitRows(text);
+  const header = rows.shift();
+  if (!header) return [];
+  const records = [];
+  for (const row of rows) {
+    if (row.length === 1 && row[0] === "") continue;
+    const record = {};
+    for (let i = 0; i < header.length; i++) {
+      record[header[i] ?? `column_${i}`] = row[i] ?? "";
+    }
+    records.push(record);
+  }
+  return records;
+};
+var splitRows = (text) => {
+  const rows = [];
+  let row = [];
+  let field = "";
+  let inQuotes = false;
+  for (let i = 0; i < text.length; i++) {
+    const char = text[i];
+    if (inQuotes) {
+      if (char === '"') {
+        if (text[i + 1] === '"') {
+          field += '"';
+          i++;
+        } else {
+          inQuotes = false;
+        }
+      } else {
+        field += char;
+      }
+      continue;
+    }
+    if (char === '"') {
+      inQuotes = true;
+    } else if (char === ",") {
+      row.push(field);
+      field = "";
+    } else if (char === "\n" || char === "\r") {
+      if (char === "\r" && text[i + 1] === "\n") i++;
+      row.push(field);
+      rows.push(row);
+      row = [];
+      field = "";
+    } else {
+      field += char;
+    }
+  }
+  if (field !== "" || row.length > 0) {
+    row.push(field);
+    rows.push(row);
+  }
+  return rows;
+};
+
+// src/errors.ts
+var EcbError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "EcbError";
+  }
+};
+var EcbHttpError = class extends EcbError {
+  status;
+  body;
+  constructor(status, body) {
+    super(`ECB data API returned HTTP ${status}`);
+    this.name = "EcbHttpError";
+    this.status = status;
+    this.body = body;
+  }
+};
+var NoRateError = class extends EcbError {
+  currency;
+  date;
+  constructor(currency, date) {
+    super(`No ECB reference rate for ${currency} on or before ${date}`);
+    this.name = "NoRateError";
+    this.currency = currency;
+    this.date = date;
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://data-api.ecb.europa.eu/service";
+var DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+var EcbClient = class {
+  baseUrl;
+  fetchImpl;
+  cache;
+  timeoutMs;
+  constructor(options = {}) {
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    const resolvedFetch = options.fetch ?? globalThis.fetch;
+    if (!resolvedFetch) {
+      throw new EcbError(
+        "No fetch implementation available; pass `fetch` in EcbClientOptions"
+      );
+    }
+    this.fetchImpl = resolvedFetch;
+    this.cache = options.cache === void 0 ? new MapCache() : options.cache;
+    this.timeoutMs = options.timeoutMs ?? 15e3;
+  }
+  /**
+   * Resolve the reference rate for a single currency on (or before) a date.
+   * `EUR` returns a unit rate without a network call.
+   */
+  async getRate(currency, date) {
+    const requestedDate = normalizeDate(date);
+    if (currency === BASE_CURRENCY) {
+      return { currency: BASE_CURRENCY, rate: 1, date: requestedDate };
+    }
+    const snapshot = await this.fetchSnapshot([currency], requestedDate);
+    const rate = snapshot.rates.find((r) => r.currency === currency);
+    if (!rate) throw new NoRateError(currency, requestedDate);
+    return rate;
+  }
+  /**
+   * Resolve reference rates on (or before) a date. Pass `currencies` to limit
+   * the request, or omit it to fetch every series the ECB publishes (note
+   * that discontinued series resolve to their last published date).
+   */
+  async getRates(date, currencies) {
+    const requestedDate = normalizeDate(date);
+    const wanted = currencies?.filter((c) => c !== BASE_CURRENCY);
+    const snapshot = wanted && wanted.length === 0 ? { requestedDate, rates: [] } : await this.fetchSnapshot(wanted ?? null, requestedDate);
+    if (currencies?.includes(BASE_CURRENCY)) {
+      return {
+        requestedDate,
+        rates: [
+          { currency: BASE_CURRENCY, rate: 1, date: requestedDate },
+          ...snapshot.rates
+        ]
+      };
+    }
+    return snapshot;
+  }
+  /**
+   * Convert `amount` from one currency to another using the reference rates on
+   * (or before) `date`. Non-euro pairs are crossed through the euro.
+   */
+  async convert(params) {
+    const { amount, from, to } = params;
+    const requestedDate = normalizeDate(params.date);
+    if (from === to) {
+      return {
+        amount,
+        rate: 1,
+        from,
+        to,
+        requestedDate,
+        rateDate: requestedDate
+      };
+    }
+    const needed = [from, to].filter(
+      (c) => c !== BASE_CURRENCY
+    );
+    const snapshot = await this.fetchSnapshot(needed, requestedDate);
+    const fromLeg = this.legFor(from, snapshot, requestedDate);
+    const toLeg = this.legFor(to, snapshot, requestedDate);
+    const rate = toLeg.rate / fromLeg.rate;
+    return {
+      amount: amount * rate,
+      rate,
+      from,
+      to,
+      requestedDate,
+      rateDate: fromLeg.date > toLeg.date ? fromLeg.date : toLeg.date
+    };
+  }
+  legFor(currency, snapshot, requestedDate) {
+    if (currency === BASE_CURRENCY) {
+      return { currency: BASE_CURRENCY, rate: 1, date: requestedDate };
+    }
+    const leg = snapshot.rates.find((r) => r.currency === currency);
+    if (!leg) throw new NoRateError(currency, requestedDate);
+    return leg;
+  }
+  async fetchSnapshot(currencies, requestedDate) {
+    const key = currencies && currencies.length ? currencies.join("+") : "";
+    const url = `${this.baseUrl}/data/EXR/D.${key}.EUR.SP00.A?endPeriod=${requestedDate}&lastNObservations=1`;
+    const cached = this.cache?.get(url);
+    if (cached) return cached;
+    const text = await this.get(url);
+    const rates = [];
+    for (const record of parseCsv(text)) {
+      const currency = record["CURRENCY"];
+      const observedAt = record["TIME_PERIOD"];
+      const value = Number(record["OBS_VALUE"]);
+      if (!currency || !observedAt || !Number.isFinite(value)) continue;
+      rates.push({ currency, rate: value, date: observedAt });
+    }
+    const snapshot = { requestedDate, rates };
+    this.cache?.set(url, snapshot);
+    return snapshot;
+  }
+  async get(url) {
+    const controller = this.timeoutMs > 0 ? new AbortController() : void 0;
+    const timer = controller ? setTimeout(() => controller.abort(), this.timeoutMs) : void 0;
+    try {
+      const response = await this.fetchImpl(url, {
+        headers: { Accept: "text/csv" },
+        ...controller ? { signal: controller.signal } : {}
+      });
+      const body = await response.text();
+      if (!response.ok) throw new EcbHttpError(response.status, body);
+      return body;
+    } catch (error) {
+      if (error instanceof EcbError) throw error;
+      throw new EcbError(`ECB data API request failed: ${url}`, {
+        cause: error
+      });
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+};
+var MapCache = class {
+  store = /* @__PURE__ */ new Map();
+  get(key) {
+    return this.store.get(key);
+  }
+  set(key, value) {
+    this.store.set(key, value);
+  }
+};
+var normalizeDate = (date) => {
+  if (date instanceof Date) {
+    if (Number.isNaN(date.getTime())) {
+      throw new EcbError("Invalid Date passed for the rate date");
+    }
+    return date.toISOString().slice(0, 10);
+  }
+  if (!DATE_RE.test(date)) {
+    throw new EcbError(`Invalid date "${date}"; expected YYYY-MM-DD`);
+  }
+  return date;
+};
+
+exports.BASE_CURRENCY = BASE_CURRENCY;
+exports.ECB_CURRENCIES = ECB_CURRENCIES;
+exports.EcbClient = EcbClient;
+exports.EcbError = EcbError;
+exports.EcbHttpError = EcbHttpError;
+exports.NoRateError = NoRateError;
+exports.isEcbCurrency = isEcbCurrency;
+exports.parseCsv = parseCsv;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/currencies.ts","../src/csv.ts","../src/errors.ts","../src/client.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * The currencies for which the European Central Bank publishes daily euro\n * foreign-exchange reference rates, as of the ECB's current daily reference\n * list. Every rate is quoted as units of the currency per 1 EUR.\n *\n * The ECB occasionally adds or suspends currencies. This list is a convenience\n * for callers and the source of the {@link EcbCurrency} literal union; the\n * client never restricts lookups to it, so any ISO 4217 code the ECB exposes\n * (including discontinued series) can still be requested.\n */\nexport const ECB_CURRENCIES = [\n\t\"AUD\",\n\t\"BGN\",\n\t\"BRL\",\n\t\"CAD\",\n\t\"CHF\",\n\t\"CNY\",\n\t\"CZK\",\n\t\"DKK\",\n\t\"GBP\",\n\t\"HKD\",\n\t\"HUF\",\n\t\"IDR\",\n\t\"ILS\",\n\t\"INR\",\n\t\"ISK\",\n\t\"JPY\",\n\t\"KRW\",\n\t\"MXN\",\n\t\"MYR\",\n\t\"NOK\",\n\t\"NZD\",\n\t\"PHP\",\n\t\"PLN\",\n\t\"RON\",\n\t\"SEK\",\n\t\"SGD\",\n\t\"THB\",\n\t\"TRY\",\n\t\"USD\",\n\t\"ZAR\",\n] as const;\n\n/** A currency on the ECB's daily reference list. */\nexport type EcbCurrency = (typeof ECB_CURRENCIES)[number];\n\n/** The base currency of every ECB reference rate. */\nexport const BASE_CURRENCY = \"EUR\";\n\nconst ECB_CURRENCY_SET: ReadonlySet<string> = new Set(ECB_CURRENCIES);\n\n/** Narrowing guard: is `code` on the ECB daily reference list? */\nexport const isEcbCurrency = (code: string): code is EcbCurrency =>\n\tECB_CURRENCY_SET.has(code);\n","/**\n * Minimal RFC 4180 CSV parser, sufficient for the ECB data API's `text/csv`\n * responses. Handles quoted fields containing commas, line breaks and escaped\n * (doubled) quotes — the ECB's `TITLE_COMPL` column, for instance, embeds\n * commas inside quotes.\n */\nexport const parseCsv = (text: string): Record<string, string>[] => {\n\tconst rows = splitRows(text);\n\tconst header = rows.shift();\n\tif (!header) return [];\n\tconst records: Record<string, string>[] = [];\n\tfor (const row of rows) {\n\t\t// Skip blank trailing lines (a single empty field, no real data).\n\t\tif (row.length === 1 && row[0] === \"\") continue;\n\t\tconst record: Record<string, string> = {};\n\t\tfor (let i = 0; i < header.length; i++) {\n\t\t\trecord[header[i] ?? `column_${i}`] = row[i] ?? \"\";\n\t\t}\n\t\trecords.push(record);\n\t}\n\treturn records;\n};\n\nconst splitRows = (text: string): string[][] => {\n\tconst rows: string[][] = [];\n\tlet row: string[] = [];\n\tlet field = \"\";\n\tlet inQuotes = false;\n\n\tfor (let i = 0; i < text.length; i++) {\n\t\tconst char = text[i];\n\t\tif (inQuotes) {\n\t\t\tif (char === '\"') {\n\t\t\t\tif (text[i + 1] === '\"') {\n\t\t\t\t\tfield += '\"';\n\t\t\t\t\ti++;\n\t\t\t\t} else {\n\t\t\t\t\tinQuotes = false;\n\t\t\t\t}\n\t\t\t} else {\n\t\t\t\tfield += char;\n\t\t\t}\n\t\t\tcontinue;\n\t\t}\n\t\tif (char === '\"') {\n\t\t\tinQuotes = true;\n\t\t} else if (char === \",\") {\n\t\t\trow.push(field);\n\t\t\tfield = \"\";\n\t\t} else if (char === \"\\n\" || char === \"\\r\") {\n\t\t\tif (char === \"\\r\" && text[i + 1] === \"\\n\") i++;\n\t\t\trow.push(field);\n\t\t\trows.push(row);\n\t\t\trow = [];\n\t\t\tfield = \"\";\n\t\t} else {\n\t\t\tfield += char;\n\t\t}\n\t}\n\n\t// Flush a final row when the text does not end with a line break.\n\tif (field !== \"\" || row.length > 0) {\n\t\trow.push(field);\n\t\trows.push(row);\n\t}\n\treturn rows;\n};\n","import type { CurrencyCode, IsoDate } from \"./types.js\";\n\n/** Base class for every error thrown by this package. */\nexport class EcbError extends Error {\n\tconstructor(message: string, options?: { cause?: unknown }) {\n\t\tsuper(message, options);\n\t\tthis.name = \"EcbError\";\n\t}\n}\n\n/** The ECB data API returned a non-2xx response. */\nexport class EcbHttpError extends EcbError {\n\treadonly status: number;\n\treadonly body: string;\n\n\tconstructor(status: number, body: string) {\n\t\tsuper(`ECB data API returned HTTP ${status}`);\n\t\tthis.name = \"EcbHttpError\";\n\t\tthis.status = status;\n\t\tthis.body = body;\n\t}\n}\n\n/** No reference rate exists for the currency on or before the requested date. */\nexport class NoRateError extends EcbError {\n\treadonly currency: CurrencyCode;\n\treadonly date: IsoDate;\n\n\tconstructor(currency: CurrencyCode, date: IsoDate) {\n\t\tsuper(`No ECB reference rate for ${currency} on or before ${date}`);\n\t\tthis.name = \"NoRateError\";\n\t\tthis.currency = currency;\n\t\tthis.date = date;\n\t}\n}\n","import { BASE_CURRENCY } from \"./currencies.js\";\nimport { parseCsv } from \"./csv.js\";\nimport { EcbError, EcbHttpError, NoRateError } from \"./errors.js\";\nimport type {\n\tConvertResult,\n\tCurrencyCode,\n\tIsoDate,\n\tRateSnapshot,\n\tReferenceRate,\n} from \"./types.js\";\n\n/**\n * The subset of the WHATWG `fetch` contract this client relies on. The global\n * `fetch` satisfies it, so callers rarely need to pass one — it exists to make\n * the client trivially testable and proxy-friendly.\n */\nexport type FetchLike = (\n\tinput: string,\n\tinit?: { headers?: Record<string, string>; signal?: AbortSignal },\n) => Promise<{ ok: boolean; status: number; text: () => Promise<string> }>;\n\n/** A cache for resolved snapshots, keyed by request URL. */\nexport interface RateCache {\n\tget(key: string): RateSnapshot | undefined;\n\tset(key: string, value: RateSnapshot): void;\n}\n\nexport interface EcbClientOptions {\n\t/**\n\t * Base URL of the ECB data API.\n\t * Default: `https://data-api.ecb.europa.eu/service`.\n\t */\n\tbaseUrl?: string;\n\t/** Custom fetch implementation. Defaults to the global `fetch`. */\n\tfetch?: FetchLike;\n\t/**\n\t * Snapshot cache. Defaults to an unbounded in-process `Map`. Pass `null` to\n\t * disable caching entirely.\n\t */\n\tcache?: RateCache | null;\n\t/** Request timeout in milliseconds. Default `15000`; `0` disables it. */\n\ttimeoutMs?: number;\n}\n\nconst DEFAULT_BASE_URL = \"https://data-api.ecb.europa.eu/service\";\nconst DATE_RE = /^\\d{4}-\\d{2}-\\d{2}$/;\n\n/**\n * A small client for the European Central Bank's euro foreign-exchange\n * reference rates, served from the ECB data API (dataflow `EXR`).\n *\n * Every rate is quoted against the euro (units of the currency per 1 EUR).\n * Requests for a date that is not a TARGET business day resolve to the most\n * recent prior business day, via the data API's `lastNObservations` parameter,\n * and the resolved date is reported on each {@link ReferenceRate}.\n */\nexport class EcbClient {\n\tprivate readonly baseUrl: string;\n\tprivate readonly fetchImpl: FetchLike;\n\tprivate readonly cache: RateCache | null;\n\tprivate readonly timeoutMs: number;\n\n\tconstructor(options: EcbClientOptions = {}) {\n\t\tthis.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\\/+$/, \"\");\n\t\tconst resolvedFetch =\n\t\t\toptions.fetch ?? (globalThis.fetch as FetchLike | undefined);\n\t\tif (!resolvedFetch) {\n\t\t\tthrow new EcbError(\n\t\t\t\t\"No fetch implementation available; pass `fetch` in EcbClientOptions\",\n\t\t\t);\n\t\t}\n\t\tthis.fetchImpl = resolvedFetch;\n\t\tthis.cache =\n\t\t\toptions.cache === undefined ? new MapCache() : options.cache;\n\t\tthis.timeoutMs = options.timeoutMs ?? 15000;\n\t}\n\n\t/**\n\t * Resolve the reference rate for a single currency on (or before) a date.\n\t * `EUR` returns a unit rate without a network call.\n\t */\n\tasync getRate(\n\t\tcurrency: CurrencyCode,\n\t\tdate: Date | IsoDate,\n\t): Promise<ReferenceRate> {\n\t\tconst requestedDate = normalizeDate(date);\n\t\tif (currency === BASE_CURRENCY) {\n\t\t\treturn { currency: BASE_CURRENCY, rate: 1, date: requestedDate };\n\t\t}\n\t\tconst snapshot = await this.fetchSnapshot([currency], requestedDate);\n\t\tconst rate = snapshot.rates.find((r) => r.currency === currency);\n\t\tif (!rate) throw new NoRateError(currency, requestedDate);\n\t\treturn rate;\n\t}\n\n\t/**\n\t * Resolve reference rates on (or before) a date. Pass `currencies` to limit\n\t * the request, or omit it to fetch every series the ECB publishes (note\n\t * that discontinued series resolve to their last published date).\n\t */\n\tasync getRates(\n\t\tdate: Date | IsoDate,\n\t\tcurrencies?: readonly CurrencyCode[],\n\t): Promise<RateSnapshot> {\n\t\tconst requestedDate = normalizeDate(date);\n\t\tconst wanted = currencies?.filter((c) => c !== BASE_CURRENCY);\n\t\tconst snapshot =\n\t\t\twanted && wanted.length === 0\n\t\t\t\t? { requestedDate, rates: [] }\n\t\t\t\t: await this.fetchSnapshot(wanted ?? null, requestedDate);\n\t\tif (currencies?.includes(BASE_CURRENCY)) {\n\t\t\treturn {\n\t\t\t\trequestedDate,\n\t\t\t\trates: [\n\t\t\t\t\t{ currency: BASE_CURRENCY, rate: 1, date: requestedDate },\n\t\t\t\t\t...snapshot.rates,\n\t\t\t\t],\n\t\t\t};\n\t\t}\n\t\treturn snapshot;\n\t}\n\n\t/**\n\t * Convert `amount` from one currency to another using the reference rates on\n\t * (or before) `date`. Non-euro pairs are crossed through the euro.\n\t */\n\tasync convert(params: {\n\t\tamount: number;\n\t\tfrom: CurrencyCode;\n\t\tto: CurrencyCode;\n\t\tdate: Date | IsoDate;\n\t}): Promise<ConvertResult> {\n\t\tconst { amount, from, to } = params;\n\t\tconst requestedDate = normalizeDate(params.date);\n\t\tif (from === to) {\n\t\t\treturn {\n\t\t\t\tamount,\n\t\t\t\trate: 1,\n\t\t\t\tfrom,\n\t\t\t\tto,\n\t\t\t\trequestedDate,\n\t\t\t\trateDate: requestedDate,\n\t\t\t};\n\t\t}\n\t\tconst needed = [from, to].filter(\n\t\t\t(c): c is CurrencyCode => c !== BASE_CURRENCY,\n\t\t);\n\t\tconst snapshot = await this.fetchSnapshot(needed, requestedDate);\n\t\tconst fromLeg = this.legFor(from, snapshot, requestedDate);\n\t\tconst toLeg = this.legFor(to, snapshot, requestedDate);\n\t\tconst rate = toLeg.rate / fromLeg.rate;\n\t\treturn {\n\t\t\tamount: amount * rate,\n\t\t\trate,\n\t\t\tfrom,\n\t\t\tto,\n\t\t\trequestedDate,\n\t\t\trateDate: fromLeg.date > toLeg.date ? fromLeg.date : toLeg.date,\n\t\t};\n\t}\n\n\tprivate legFor(\n\t\tcurrency: CurrencyCode,\n\t\tsnapshot: RateSnapshot,\n\t\trequestedDate: IsoDate,\n\t): ReferenceRate {\n\t\tif (currency === BASE_CURRENCY) {\n\t\t\treturn { currency: BASE_CURRENCY, rate: 1, date: requestedDate };\n\t\t}\n\t\tconst leg = snapshot.rates.find((r) => r.currency === currency);\n\t\tif (!leg) throw new NoRateError(currency, requestedDate);\n\t\treturn leg;\n\t}\n\n\tprivate async fetchSnapshot(\n\t\tcurrencies: readonly CurrencyCode[] | null,\n\t\trequestedDate: IsoDate,\n\t): Promise<RateSnapshot> {\n\t\tconst key = currencies && currencies.length ? currencies.join(\"+\") : \"\";\n\t\tconst url = `${this.baseUrl}/data/EXR/D.${key}.EUR.SP00.A?endPeriod=${requestedDate}&lastNObservations=1`;\n\n\t\tconst cached = this.cache?.get(url);\n\t\tif (cached) return cached;\n\n\t\tconst text = await this.get(url);\n\t\tconst rates: ReferenceRate[] = [];\n\t\tfor (const record of parseCsv(text)) {\n\t\t\tconst currency = record[\"CURRENCY\"];\n\t\t\tconst observedAt = record[\"TIME_PERIOD\"];\n\t\t\tconst value = Number(record[\"OBS_VALUE\"]);\n\t\t\tif (!currency || !observedAt || !Number.isFinite(value)) continue;\n\t\t\trates.push({ currency, rate: value, date: observedAt });\n\t\t}\n\n\t\tconst snapshot: RateSnapshot = { requestedDate, rates };\n\t\tthis.cache?.set(url, snapshot);\n\t\treturn snapshot;\n\t}\n\n\tprivate async get(url: string): Promise<string> {\n\t\tconst controller =\n\t\t\tthis.timeoutMs > 0 ? new AbortController() : undefined;\n\t\tconst timer = controller\n\t\t\t? setTimeout(() => controller.abort(), this.timeoutMs)\n\t\t\t: undefined;\n\t\ttry {\n\t\t\tconst response = await this.fetchImpl(url, {\n\t\t\t\theaders: { Accept: \"text/csv\" },\n\t\t\t\t...(controller ? { signal: controller.signal } : {}),\n\t\t\t});\n\t\t\tconst body = await response.text();\n\t\t\tif (!response.ok) throw new EcbHttpError(response.status, body);\n\t\t\treturn body;\n\t\t} catch (error) {\n\t\t\tif (error instanceof EcbError) throw error;\n\t\t\tthrow new EcbError(`ECB data API request failed: ${url}`, {\n\t\t\t\tcause: error,\n\t\t\t});\n\t\t} finally {\n\t\t\tif (timer) clearTimeout(timer);\n\t\t}\n\t}\n}\n\nclass MapCache implements RateCache {\n\tprivate readonly store = new Map<string, RateSnapshot>();\n\tget(key: string): RateSnapshot | undefined {\n\t\treturn this.store.get(key);\n\t}\n\tset(key: string, value: RateSnapshot): void {\n\t\tthis.store.set(key, value);\n\t}\n}\n\nconst normalizeDate = (date: Date | IsoDate): IsoDate => {\n\tif (date instanceof Date) {\n\t\tif (Number.isNaN(date.getTime())) {\n\t\t\tthrow new EcbError(\"Invalid Date passed for the rate date\");\n\t\t}\n\t\treturn date.toISOString().slice(0, 10);\n\t}\n\tif (!DATE_RE.test(date)) {\n\t\tthrow new EcbError(`Invalid date \"${date}\"; expected YYYY-MM-DD`);\n\t}\n\treturn date;\n};\n"]}

package/dist/index.d.cts

@@ -0,0 +1,168 @@
+/**
+ * The currencies for which the European Central Bank publishes daily euro
+ * foreign-exchange reference rates, as of the ECB's current daily reference
+ * list. Every rate is quoted as units of the currency per 1 EUR.
+ *
+ * The ECB occasionally adds or suspends currencies. This list is a convenience
+ * for callers and the source of the {@link EcbCurrency} literal union; the
+ * client never restricts lookups to it, so any ISO 4217 code the ECB exposes
+ * (including discontinued series) can still be requested.
+ */
+declare const ECB_CURRENCIES: readonly ["AUD", "BGN", "BRL", "CAD", "CHF", "CNY", "CZK", "DKK", "GBP", "HKD", "HUF", "IDR", "ILS", "INR", "ISK", "JPY", "KRW", "MXN", "MYR", "NOK", "NZD", "PHP", "PLN", "RON", "SEK", "SGD", "THB", "TRY", "USD", "ZAR"];
+/** A currency on the ECB's daily reference list. */
+type EcbCurrency = (typeof ECB_CURRENCIES)[number];
+/** The base currency of every ECB reference rate. */
+declare const BASE_CURRENCY = "EUR";
+/** Narrowing guard: is `code` on the ECB daily reference list? */
+declare const isEcbCurrency: (code: string) => code is EcbCurrency;
+
+/** An ISO 8601 calendar date, formatted `YYYY-MM-DD`. */
+type IsoDate = string;
+/**
+ * A currency code. ECB reference currencies are strongly typed for
+ * autocomplete; any other ISO 4217 code is still accepted. The `string & {}`
+ * member preserves literal autocomplete while widening to accept any string.
+ */
+type CurrencyCode = EcbCurrency | "EUR" | (string & {});
+/** A single euro reference-rate observation. */
+interface ReferenceRate {
+    /** ISO 4217 code of the quoted currency. */
+    currency: CurrencyCode;
+    /** Units of {@link currency} per 1 EUR. */
+    rate: number;
+    /**
+     * The date the observation actually applies to. Equal to the requested date
+     * on a TARGET business day, or the most recent prior business day when the
+     * requested date had no published rate (weekend, holiday).
+     */
+    date: IsoDate;
+}
+/** A set of reference rates resolved for a single requested date. */
+interface RateSnapshot {
+    /** The date that was requested, normalized to `YYYY-MM-DD`. */
+    requestedDate: IsoDate;
+    /**
+     * One entry per currency. Each entry's effective {@link ReferenceRate.date}
+     * may differ — discontinued series resolve to their last published date.
+     */
+    rates: ReferenceRate[];
+}
+/** The outcome of converting an amount between two currencies. */
+interface ConvertResult {
+    /** The converted amount, expressed in {@link to}. Not rounded. */
+    amount: number;
+    /** The effective {@link from} → {@link to} rate applied. */
+    rate: number;
+    /** Source currency. */
+    from: CurrencyCode;
+    /** Target currency. */
+    to: CurrencyCode;
+    /** The requested date, normalized to `YYYY-MM-DD`. */
+    requestedDate: IsoDate;
+    /** The effective observation date of the rate(s) applied. */
+    rateDate: IsoDate;
+}
+
+/**
+ * The subset of the WHATWG `fetch` contract this client relies on. The global
+ * `fetch` satisfies it, so callers rarely need to pass one — it exists to make
+ * the client trivially testable and proxy-friendly.
+ */
+type FetchLike = (input: string, init?: {
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    text: () => Promise<string>;
+}>;
+/** A cache for resolved snapshots, keyed by request URL. */
+interface RateCache {
+    get(key: string): RateSnapshot | undefined;
+    set(key: string, value: RateSnapshot): void;
+}
+interface EcbClientOptions {
+    /**
+     * Base URL of the ECB data API.
+     * Default: `https://data-api.ecb.europa.eu/service`.
+     */
+    baseUrl?: string;
+    /** Custom fetch implementation. Defaults to the global `fetch`. */
+    fetch?: FetchLike;
+    /**
+     * Snapshot cache. Defaults to an unbounded in-process `Map`. Pass `null` to
+     * disable caching entirely.
+     */
+    cache?: RateCache | null;
+    /** Request timeout in milliseconds. Default `15000`; `0` disables it. */
+    timeoutMs?: number;
+}
+/**
+ * A small client for the European Central Bank's euro foreign-exchange
+ * reference rates, served from the ECB data API (dataflow `EXR`).
+ *
+ * Every rate is quoted against the euro (units of the currency per 1 EUR).
+ * Requests for a date that is not a TARGET business day resolve to the most
+ * recent prior business day, via the data API's `lastNObservations` parameter,
+ * and the resolved date is reported on each {@link ReferenceRate}.
+ */
+declare class EcbClient {
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly cache;
+    private readonly timeoutMs;
+    constructor(options?: EcbClientOptions);
+    /**
+     * Resolve the reference rate for a single currency on (or before) a date.
+     * `EUR` returns a unit rate without a network call.
+     */
+    getRate(currency: CurrencyCode, date: Date | IsoDate): Promise<ReferenceRate>;
+    /**
+     * Resolve reference rates on (or before) a date. Pass `currencies` to limit
+     * the request, or omit it to fetch every series the ECB publishes (note
+     * that discontinued series resolve to their last published date).
+     */
+    getRates(date: Date | IsoDate, currencies?: readonly CurrencyCode[]): Promise<RateSnapshot>;
+    /**
+     * Convert `amount` from one currency to another using the reference rates on
+     * (or before) `date`. Non-euro pairs are crossed through the euro.
+     */
+    convert(params: {
+        amount: number;
+        from: CurrencyCode;
+        to: CurrencyCode;
+        date: Date | IsoDate;
+    }): Promise<ConvertResult>;
+    private legFor;
+    private fetchSnapshot;
+    private get;
+}
+
+/** Base class for every error thrown by this package. */
+declare class EcbError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The ECB data API returned a non-2xx response. */
+declare class EcbHttpError extends EcbError {
+    readonly status: number;
+    readonly body: string;
+    constructor(status: number, body: string);
+}
+/** No reference rate exists for the currency on or before the requested date. */
+declare class NoRateError extends EcbError {
+    readonly currency: CurrencyCode;
+    readonly date: IsoDate;
+    constructor(currency: CurrencyCode, date: IsoDate);
+}
+
+/**
+ * Minimal RFC 4180 CSV parser, sufficient for the ECB data API's `text/csv`
+ * responses. Handles quoted fields containing commas, line breaks and escaped
+ * (doubled) quotes — the ECB's `TITLE_COMPL` column, for instance, embeds
+ * commas inside quotes.
+ */
+declare const parseCsv: (text: string) => Record<string, string>[];
+
+export { BASE_CURRENCY, type ConvertResult, type CurrencyCode, ECB_CURRENCIES, EcbClient, type EcbClientOptions, type EcbCurrency, EcbError, EcbHttpError, type FetchLike, type IsoDate, NoRateError, type RateCache, type RateSnapshot, type ReferenceRate, isEcbCurrency, parseCsv };