@financica/ecb-client 0.1.0

package/src/client.ts

@@ -0,0 +1,246 @@
+import { BASE_CURRENCY } from "./currencies.js";
+import { parseCsv } from "./csv.js";
+import { EcbError, EcbHttpError, NoRateError } from "./errors.js";
+import type {
+	ConvertResult,
+	CurrencyCode,
+	IsoDate,
+	RateSnapshot,
+	ReferenceRate,
+} from "./types.js";
+
+/**
+ * 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.
+ */
+export 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. */
+export interface RateCache {
+	get(key: string): RateSnapshot | undefined;
+	set(key: string, value: RateSnapshot): void;
+}
+
+export 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;
+}
+
+const DEFAULT_BASE_URL = "https://data-api.ecb.europa.eu/service";
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+
+/**
+ * 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}.
+ */
+export class EcbClient {
+	private readonly baseUrl: string;
+	private readonly fetchImpl: FetchLike;
+	private readonly cache: RateCache | null;
+	private readonly timeoutMs: number;
+
+	constructor(options: EcbClientOptions = {}) {
+		this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+		const resolvedFetch =
+			options.fetch ?? (globalThis.fetch as FetchLike | undefined);
+		if (!resolvedFetch) {
+			throw new EcbError(
+				"No fetch implementation available; pass `fetch` in EcbClientOptions",
+			);
+		}
+		this.fetchImpl = resolvedFetch;
+		this.cache =
+			options.cache === undefined ? new MapCache() : options.cache;
+		this.timeoutMs = options.timeoutMs ?? 15000;
+	}
+
+	/**
+	 * 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: CurrencyCode,
+		date: Date | IsoDate,
+	): Promise<ReferenceRate> {
+		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: Date | IsoDate,
+		currencies?: readonly CurrencyCode[],
+	): Promise<RateSnapshot> {
+		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: {
+		amount: number;
+		from: CurrencyCode;
+		to: CurrencyCode;
+		date: Date | IsoDate;
+	}): Promise<ConvertResult> {
+		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 is CurrencyCode => 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,
+		};
+	}
+
+	private legFor(
+		currency: CurrencyCode,
+		snapshot: RateSnapshot,
+		requestedDate: IsoDate,
+	): ReferenceRate {
+		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;
+	}
+
+	private async fetchSnapshot(
+		currencies: readonly CurrencyCode[] | null,
+		requestedDate: IsoDate,
+	): Promise<RateSnapshot> {
+		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: ReferenceRate[] = [];
+		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: RateSnapshot = { requestedDate, rates };
+		this.cache?.set(url, snapshot);
+		return snapshot;
+	}
+
+	private async get(url: string): Promise<string> {
+		const controller =
+			this.timeoutMs > 0 ? new AbortController() : undefined;
+		const timer = controller
+			? setTimeout(() => controller.abort(), this.timeoutMs)
+			: undefined;
+		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);
+		}
+	}
+}
+
+class MapCache implements RateCache {
+	private readonly store = new Map<string, RateSnapshot>();
+	get(key: string): RateSnapshot | undefined {
+		return this.store.get(key);
+	}
+	set(key: string, value: RateSnapshot): void {
+		this.store.set(key, value);
+	}
+}
+
+const normalizeDate = (date: Date | IsoDate): IsoDate => {
+	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;
+};

package/src/csv.ts

@@ -0,0 +1,67 @@
+/**
+ * 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.
+ */
+export const parseCsv = (text: string): Record<string, string>[] => {
+	const rows = splitRows(text);
+	const header = rows.shift();
+	if (!header) return [];
+	const records: Record<string, string>[] = [];
+	for (const row of rows) {
+		// Skip blank trailing lines (a single empty field, no real data).
+		if (row.length === 1 && row[0] === "") continue;
+		const record: Record<string, string> = {};
+		for (let i = 0; i < header.length; i++) {
+			record[header[i] ?? `column_${i}`] = row[i] ?? "";
+		}
+		records.push(record);
+	}
+	return records;
+};
+
+const splitRows = (text: string): string[][] => {
+	const rows: string[][] = [];
+	let row: string[] = [];
+	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;
+		}
+	}
+
+	// Flush a final row when the text does not end with a line break.
+	if (field !== "" || row.length > 0) {
+		row.push(field);
+		rows.push(row);
+	}
+	return rows;
+};

package/src/currencies.ts

@@ -0,0 +1,54 @@
+/**
+ * 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.
+ */
+export const 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",
+] as const;
+
+/** A currency on the ECB's daily reference list. */
+export type EcbCurrency = (typeof ECB_CURRENCIES)[number];
+
+/** The base currency of every ECB reference rate. */
+export const BASE_CURRENCY = "EUR";
+
+const ECB_CURRENCY_SET: ReadonlySet<string> = new Set(ECB_CURRENCIES);
+
+/** Narrowing guard: is `code` on the ECB daily reference list? */
+export const isEcbCurrency = (code: string): code is EcbCurrency =>
+	ECB_CURRENCY_SET.has(code);

package/src/errors.ts

@@ -0,0 +1,35 @@
+import type { CurrencyCode, IsoDate } from "./types.js";
+
+/** Base class for every error thrown by this package. */
+export class EcbError extends Error {
+	constructor(message: string, options?: { cause?: unknown }) {
+		super(message, options);
+		this.name = "EcbError";
+	}
+}
+
+/** The ECB data API returned a non-2xx response. */
+export class EcbHttpError extends EcbError {
+	readonly status: number;
+	readonly body: string;
+
+	constructor(status: number, body: string) {
+		super(`ECB data API returned HTTP ${status}`);
+		this.name = "EcbHttpError";
+		this.status = status;
+		this.body = body;
+	}
+}
+
+/** No reference rate exists for the currency on or before the requested date. */
+export class NoRateError extends EcbError {
+	readonly currency: CurrencyCode;
+	readonly date: IsoDate;
+
+	constructor(currency: CurrencyCode, date: IsoDate) {
+		super(`No ECB reference rate for ${currency} on or before ${date}`);
+		this.name = "NoRateError";
+		this.currency = currency;
+		this.date = date;
+	}
+}

package/src/index.ts

@@ -0,0 +1,29 @@
+/**
+ * Public entry point for @financica/ecb-client.
+ *
+ * A small, dependency-free client for the European Central Bank's euro
+ * foreign-exchange reference rates (data API dataflow `EXR`), with first-class
+ * support for historical single-day lookups and last-business-day fallback.
+ */
+
+export { EcbClient } from "./client.js";
+export type {
+	EcbClientOptions,
+	FetchLike,
+	RateCache,
+} from "./client.js";
+export {
+	BASE_CURRENCY,
+	ECB_CURRENCIES,
+	isEcbCurrency,
+} from "./currencies.js";
+export type { EcbCurrency } from "./currencies.js";
+export { EcbError, EcbHttpError, NoRateError } from "./errors.js";
+export { parseCsv } from "./csv.js";
+export type {
+	ConvertResult,
+	CurrencyCode,
+	IsoDate,
+	RateSnapshot,
+	ReferenceRate,
+} from "./types.js";

package/src/types.ts

@@ -0,0 +1,52 @@
+import type { EcbCurrency } from "./currencies.js";
+
+/** An ISO 8601 calendar date, formatted `YYYY-MM-DD`. */
+export 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.
+ */
+export type CurrencyCode = EcbCurrency | "EUR" | (string & {});
+
+/** A single euro reference-rate observation. */
+export 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. */
+export 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. */
+export 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;
+}