ecb-exchange-rates-ts 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ntelikatos
+
+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,172 @@
+# ecb-exchange-rates-ts
+
+A typed TypeScript wrapper for the **European Central Bank** exchange rates SDMX API. Zero dependencies, production-ready, fully typed.
+
+## Features
+
+- **Zero dependencies** — uses only native `fetch` (Node.js 18+)
+- **Fully typed** — strict TypeScript with exported types for everything
+- **Configurable base currency** — defaults to EUR, but can be changed per-client or per-query
+- **Dual ESM/CJS** — works with `import` and `require`
+- **SOLID architecture** — modular, testable, extensible
+- **Dependency injection** — swap HTTP fetcher for testing or custom transports
+
+## Installation
+
+```bash
+npm install ecb-exchange-rates-ts
+# or
+pnpm add ecb-exchange-rates-ts
+```
+
+## Quick Start
+
+```ts
+import { EcbClient } from "ecb-exchange-rates-ts";
+
+const ecb = new EcbClient();
+
+// Get a rate for a specific date
+const result = await ecb.getRate("USD", "2025-01-15");
+console.log(result.rates.get("2025-01-15")); // 1.03
+
+// Convert 100 of the base currency to USD
+const conversion = await ecb.convert(100, "USD", "2025-01-15");
+console.log(conversion); // { amount: 103, rate: 1.03, date: "2025-01-15", currency: "USD" }
+
+// Get rate history
+const history = await ecb.getRateHistory("USD", "2025-01-01", "2025-01-31");
+for (const [date, rate] of history.rates) {
+  console.log(`${date}: ${rate}`);
+}
+
+// Multiple currencies at once
+const multi = await ecb.getRates({
+  currencies: ["USD", "GBP", "JPY"],
+  startDate: "2025-01-01",
+  endDate: "2025-01-31",
+});
+for (const [date, rates] of multi.rates) {
+  console.log(`${date}: USD=${rates.USD}, GBP=${rates.GBP}, JPY=${rates.JPY}`);
+}
+
+// Raw observations (full control)
+const observations = await ecb.getObservations({
+  currencies: ["USD"],
+  startDate: "2025-01-01",
+  endDate: "2025-01-31",
+  frequency: "D",
+});
+```
+
+## API Reference
+
+### `EcbClient`
+
+#### Constructor
+
+```ts
+new EcbClient(config?: EcbClientConfig)
+```
+
+| Option         | Type       | Default                                  | Description                         |
+| -------------- | ---------- | ---------------------------------------- | ----------------------------------- |
+| `baseCurrency` | `string`   | `"EUR"`                                  | Default base (denomination) currency |
+| `baseUrl`      | `string`   | `https://data-api.ecb.europa.eu/service` | ECB API base URL                    |
+| `timeoutMs`    | `number`   | `30000`                                  | Request timeout in ms               |
+| `fetchFn`      | `Function` | `globalThis.fetch`                       | Custom fetch for DI                 |
+
+#### Methods
+
+| Method            | Description                                       | Returns                            |
+| ----------------- | ------------------------------------------------- | ---------------------------------- |
+| `getRate`         | Single currency, single date                      | `ExchangeRateResult`               |
+| `getRateHistory`  | Single currency, date range                       | `ExchangeRateResult`               |
+| `getRates`        | Multiple currencies, date range                   | `ExchangeRatesResult`              |
+| `getObservations` | Raw observation array                             | `ExchangeRateObservation[]`        |
+| `convert`         | Convert base currency amount to target currency   | `{ amount, rate, date, currency }` |
+
+#### Static Factory
+
+```ts
+// Inject a custom HTTP fetcher (useful for testing)
+const client = EcbClient.withFetcher(myCustomFetcher, { baseCurrency: "USD" });
+```
+
+### Base Currency Configuration
+
+The base currency defaults to `"EUR"` but can be configured at three levels:
+
+```ts
+// 1. Client-level default
+const client = new EcbClient({ baseCurrency: "USD" });
+
+// 2. Per-query override
+const result = await client.getRates({
+  currencies: ["GBP", "JPY"],
+  startDate: "2025-01-15",
+  baseCurrency: "CHF", // overrides client default for this query
+});
+
+// 3. The result's `base` field is derived from the API response
+console.log(result.base); // "CHF"
+```
+
+## Architecture
+
+```
+src/
+├── types/          # Type definitions (interfaces, SDMX-JSON shapes)
+├── errors/         # Error hierarchy (EcbError -> EcbApiError, EcbNetworkError, etc.)
+├── parsers/        # SDMX-JSON response parser
+├── services/       # HTTP fetcher abstraction
+├── utils/          # URL builder, query validation
+├── client.ts       # Main EcbClient facade
+└── index.ts        # Public API barrel export
+```
+
+### SOLID Principles
+
+- **S** — Each module has a single responsibility (parsing, fetching, validating, URL building)
+- **O** — New formats/transports can be added without modifying existing code
+- **L** — All error types extend `EcbError` and are interchangeable
+- **I** — `HttpFetcher` interface exposes only what consumers need
+- **D** — `EcbClient` depends on the `HttpFetcher` abstraction, not `fetch` directly
+
+## Error Handling
+
+```ts
+import { EcbApiError, EcbNetworkError, EcbValidationError } from "ecb-exchange-rates-ts";
+
+try {
+  const result = await ecb.getRate("USD", "2025-01-15");
+} catch (error) {
+  if (error instanceof EcbValidationError) {
+    // Invalid query parameters
+  } else if (error instanceof EcbApiError) {
+    // HTTP error from ECB (error.statusCode, error.statusText)
+  } else if (error instanceof EcbNetworkError) {
+    // Network failure / timeout
+  }
+}
+```
+
+## Testing
+
+```bash
+pnpm test              # Run tests
+pnpm test:coverage     # Run tests with coverage
+pnpm typecheck         # Type check
+pnpm lint              # Lint + format check
+```
+
+## Notes
+
+- **No API key required** — the ECB API is free and open access.
+- **No weekend/holiday data** — the ECB only publishes rates on TARGET business days.
+- **Historical data from 1999** — data is available from January 4, 1999.
+- **Rates published at ~16:00 CET** — reference rates are set daily around 16:00 CET.
+
+## License
+
+[MIT](LICENSE)

package/dist/index.cjs

@@ -0,0 +1,359 @@
+'use strict';
+
+// src/errors/index.ts
+var EcbError = class extends Error {
+  code;
+  constructor(message, code, options) {
+    super(message, options);
+    this.name = "EcbError";
+    this.code = code;
+  }
+};
+var EcbApiError = class extends EcbError {
+  statusCode;
+  statusText;
+  constructor(statusCode, statusText, body) {
+    const message = `ECB API returned ${statusCode} ${statusText}${body ? `: ${body}` : ""}`;
+    super(message, "ECB_API_ERROR");
+    this.name = "EcbApiError";
+    this.statusCode = statusCode;
+    this.statusText = statusText;
+  }
+};
+var EcbNetworkError = class extends EcbError {
+  constructor(message, cause) {
+    super(message, "ECB_NETWORK_ERROR", { cause });
+    this.name = "EcbNetworkError";
+  }
+};
+var EcbParseError = class extends EcbError {
+  constructor(message, cause) {
+    super(message, "ECB_PARSE_ERROR", { cause });
+    this.name = "EcbParseError";
+  }
+};
+var EcbValidationError = class extends EcbError {
+  constructor(message) {
+    super(message, "ECB_VALIDATION_ERROR");
+    this.name = "EcbValidationError";
+  }
+};
+
+// src/parsers/sdmx-json-parser.ts
+function parseJsonResponse(data) {
+  const dataSets = data.dataSets;
+  if (!dataSets || dataSets.length === 0) {
+    return [];
+  }
+  const structure = data.structure;
+  if (!structure?.dimensions) {
+    throw new EcbParseError("SDMX-JSON response missing structure.dimensions.");
+  }
+  const seriesDims = structure.dimensions.series;
+  const obsDims = structure.dimensions.observation;
+  const currencyDimIndex = findDimensionIndex(seriesDims, "CURRENCY");
+  const denomDimIndex = findDimensionIndex(seriesDims, "CURRENCY_DENOM");
+  const timeDimIndex = findObservationDimensionIndex(obsDims, "TIME_PERIOD");
+  const currencyValues = seriesDims[currencyDimIndex]?.values;
+  const denomValues = seriesDims[denomDimIndex]?.values;
+  const timeValues = obsDims[timeDimIndex]?.values;
+  if (!currencyValues || !denomValues || !timeValues) {
+    throw new EcbParseError("SDMX-JSON response missing dimension values.");
+  }
+  const observations = [];
+  for (const dataSet of dataSets) {
+    const series = dataSet.series;
+    if (!series) continue;
+    for (const [seriesKey, seriesData] of Object.entries(series)) {
+      const dimIndices = seriesKey.split(":").map(Number);
+      const currencyIdx = dimIndices[currencyDimIndex];
+      const denomIdx = dimIndices[denomDimIndex];
+      if (currencyIdx === void 0 || denomIdx === void 0) {
+        continue;
+      }
+      const currency = currencyValues[currencyIdx]?.id;
+      const baseCurrency = denomValues[denomIdx]?.id;
+      if (!currency || !baseCurrency) continue;
+      for (const [obsKey, obsValues] of Object.entries(seriesData.observations)) {
+        const timeIdx = Number(obsKey);
+        const date = timeValues[timeIdx]?.id;
+        const rate = obsValues[0];
+        if (!date || rate === null || rate === void 0) continue;
+        observations.push({ date, currency, baseCurrency, rate });
+      }
+    }
+  }
+  return observations;
+}
+function parseSdmxJson(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    throw new EcbParseError("Failed to parse ECB JSON response.", error);
+  }
+}
+function findDimensionIndex(dims, id) {
+  const index = dims.findIndex((d) => d.id === id);
+  if (index === -1) {
+    throw new EcbParseError(`Missing series dimension "${id}" in SDMX-JSON structure.`);
+  }
+  return index;
+}
+function findObservationDimensionIndex(dims, id) {
+  const index = dims.findIndex((d) => d.id === id);
+  if (index === -1) {
+    throw new EcbParseError(`Missing observation dimension "${id}" in SDMX-JSON structure.`);
+  }
+  return index;
+}
+
+// src/services/http-fetcher.ts
+var FetchHttpFetcher = class {
+  fetchFn;
+  timeoutMs;
+  constructor(fetchFn = globalThis.fetch.bind(globalThis), timeoutMs = 3e4) {
+    this.fetchFn = fetchFn;
+    this.timeoutMs = timeoutMs;
+  }
+  async get(url, externalSignal) {
+    const timeoutController = new AbortController();
+    const timeoutId = setTimeout(() => timeoutController.abort(), this.timeoutMs);
+    const signal = externalSignal ? AbortSignal.any([externalSignal, timeoutController.signal]) : timeoutController.signal;
+    try {
+      const response = await this.fetchFn(url, {
+        method: "GET",
+        headers: { Accept: "application/json" },
+        signal
+      });
+      if (!response.ok) {
+        const body = await response.text().catch(() => "");
+        throw new EcbApiError(response.status, response.statusText, body);
+      }
+      return await response.text();
+    } catch (error) {
+      if (error instanceof EcbApiError) {
+        throw error;
+      }
+      if (error instanceof Error && error.name === "AbortError") {
+        throw new EcbNetworkError(`Request timed out after ${this.timeoutMs}ms: ${url}`, error);
+      }
+      throw new EcbNetworkError(
+        `Network request failed for ${url}: ${error instanceof Error ? error.message : String(error)}`,
+        error
+      );
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+};
+
+// src/utils/url-builder.ts
+var DEFAULT_BASE_URL = "https://data-api.ecb.europa.eu/service";
+function buildExchangeRateUrl(query, baseUrl = DEFAULT_BASE_URL) {
+  const frequency = query.frequency ?? "D";
+  const currencyKey = query.currencies.join("+");
+  const baseCurrency = query.baseCurrency ?? "EUR";
+  const seriesKey = `${frequency}.${currencyKey}.${baseCurrency}.SP00.A`;
+  const url = new URL(`${baseUrl}/data/EXR/${seriesKey}`);
+  url.searchParams.set("startPeriod", query.startDate);
+  if (query.endDate !== void 0) {
+    url.searchParams.set("endPeriod", query.endDate);
+  }
+  return url.toString();
+}
+
+// src/utils/validation.ts
+var ISO_DATE_REGEX = /^\d{4}-\d{2}-\d{2}$/;
+var CURRENCY_REGEX = /^[A-Z]{3}$/;
+function validateQuery(query) {
+  if (query.currencies.length === 0) {
+    throw new EcbValidationError("At least one currency must be specified.");
+  }
+  for (const currency of query.currencies) {
+    if (!CURRENCY_REGEX.test(currency)) {
+      throw new EcbValidationError(
+        `Invalid currency code "${currency}". Must be a 3-letter ISO 4217 code.`
+      );
+    }
+  }
+  if (!ISO_DATE_REGEX.test(query.startDate)) {
+    throw new EcbValidationError(
+      `Invalid startDate "${query.startDate}". Expected format: YYYY-MM-DD.`
+    );
+  }
+  if (query.endDate !== void 0 && !ISO_DATE_REGEX.test(query.endDate)) {
+    throw new EcbValidationError(
+      `Invalid endDate "${query.endDate}". Expected format: YYYY-MM-DD.`
+    );
+  }
+  if (query.endDate !== void 0 && query.startDate > query.endDate) {
+    throw new EcbValidationError(
+      `startDate "${query.startDate}" must not be after endDate "${query.endDate}".`
+    );
+  }
+  if (query.baseCurrency !== void 0 && !CURRENCY_REGEX.test(query.baseCurrency)) {
+    throw new EcbValidationError(
+      `Invalid baseCurrency "${query.baseCurrency}". Must be a 3-letter ISO 4217 code.`
+    );
+  }
+}
+
+// src/client.ts
+var DEFAULT_BASE_URL2 = "https://data-api.ecb.europa.eu/service";
+var DEFAULT_BASE_CURRENCY = "EUR";
+var EcbClient = class _EcbClient {
+  baseUrl;
+  baseCurrency;
+  fetcher;
+  constructor(config = {}) {
+    this.baseUrl = config.baseUrl ?? DEFAULT_BASE_URL2;
+    this.baseCurrency = config.baseCurrency ?? DEFAULT_BASE_CURRENCY;
+    this.fetcher = new FetchHttpFetcher(config.fetchFn, config.timeoutMs);
+  }
+  /**
+   * Creates an EcbClient with a custom HttpFetcher implementation.
+   * Useful for testing or when you need full control over HTTP behavior.
+   */
+  static withFetcher(fetcher, config = {}) {
+    const client = new _EcbClient(config);
+    Object.defineProperty(client, "fetcher", { value: fetcher });
+    return client;
+  }
+  /**
+   * Get the exchange rate for a single currency against the base currency.
+   *
+   * @param currency - Target currency code (e.g. "USD")
+   * @param date - The date to query (YYYY-MM-DD). Returns the nearest available rate.
+   */
+  async getRate(currency, date) {
+    const query = {
+      currencies: [currency],
+      startDate: date,
+      endDate: date
+    };
+    return this.getSingleCurrencyRates(query);
+  }
+  /**
+   * Get the exchange rate for a single currency over a date range.
+   *
+   * @param currency - Target currency code (e.g. "USD")
+   * @param startDate - Start date (YYYY-MM-DD)
+   * @param endDate - End date (YYYY-MM-DD)
+   * @param frequency - Data frequency (default: "D" daily)
+   */
+  async getRateHistory(currency, startDate, endDate, frequency = "D") {
+    const query = {
+      currencies: [currency],
+      startDate,
+      endDate,
+      frequency
+    };
+    return this.getSingleCurrencyRates(query);
+  }
+  /**
+   * Get exchange rates for multiple currencies.
+   *
+   * @param query - The query parameters
+   */
+  async getRates(query) {
+    const resolved = this.resolveQuery(query);
+    validateQuery(resolved);
+    const observations = await this.fetchAndParse(resolved);
+    return this.transformToMultiCurrencyResult(observations, resolved);
+  }
+  /**
+   * Get raw observations — useful when you need full control over the data.
+   *
+   * @param query - The query parameters
+   */
+  async getObservations(query) {
+    const resolved = this.resolveQuery(query);
+    validateQuery(resolved);
+    return this.fetchAndParse(resolved);
+  }
+  /**
+   * Convert an amount from the base currency to a target currency at a specific date.
+   *
+   * @param amount - The amount in the base currency
+   * @param currency - Target currency code
+   * @param date - The date for the exchange rate (YYYY-MM-DD)
+   * @returns The converted amount, or null if no rate is available
+   */
+  async convert(amount, currency, date) {
+    const result = await this.getRate(currency, date);
+    const firstEntry = result.rates.entries().next();
+    if (firstEntry.done) {
+      return null;
+    }
+    const [actualDate, rate] = firstEntry.value;
+    return {
+      amount: Math.round(amount * rate * 100) / 100,
+      rate,
+      date: actualDate,
+      currency
+    };
+  }
+  // ── Private helpers ──────────────────────────────────────────────────
+  /**
+   * Resolves a query by applying the client's default baseCurrency
+   * when the query doesn't specify one.
+   */
+  resolveQuery(query) {
+    if (query.baseCurrency !== void 0) {
+      return query;
+    }
+    return { ...query, baseCurrency: this.baseCurrency };
+  }
+  async fetchAndParse(query) {
+    const url = buildExchangeRateUrl(query, this.baseUrl);
+    const raw = await this.fetcher.get(url);
+    const json = parseSdmxJson(raw);
+    return parseJsonResponse(json);
+  }
+  async getSingleCurrencyRates(query) {
+    const resolved = this.resolveQuery(query);
+    validateQuery(resolved);
+    const observations = await this.fetchAndParse(resolved);
+    const rates = /* @__PURE__ */ new Map();
+    for (const obs of observations) {
+      rates.set(obs.date, obs.rate);
+    }
+    const base = observations[0]?.baseCurrency ?? resolved.baseCurrency ?? this.baseCurrency;
+    return {
+      base,
+      currency: resolved.currencies[0],
+      rates
+    };
+  }
+  transformToMultiCurrencyResult(observations, query) {
+    const rates = /* @__PURE__ */ new Map();
+    for (const obs of observations) {
+      let dateRates = rates.get(obs.date);
+      if (!dateRates) {
+        dateRates = {};
+        rates.set(obs.date, dateRates);
+      }
+      dateRates[obs.currency] = obs.rate;
+    }
+    const base = observations[0]?.baseCurrency ?? query.baseCurrency ?? this.baseCurrency;
+    return {
+      base,
+      currencies: query.currencies,
+      rates
+    };
+  }
+};
+
+exports.EcbApiError = EcbApiError;
+exports.EcbClient = EcbClient;
+exports.EcbError = EcbError;
+exports.EcbNetworkError = EcbNetworkError;
+exports.EcbParseError = EcbParseError;
+exports.EcbValidationError = EcbValidationError;
+exports.FetchHttpFetcher = FetchHttpFetcher;
+exports.buildExchangeRateUrl = buildExchangeRateUrl;
+exports.parseJsonResponse = parseJsonResponse;
+exports.parseSdmxJson = parseSdmxJson;
+exports.validateQuery = validateQuery;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors/index.ts","../src/parsers/sdmx-json-parser.ts","../src/services/http-fetcher.ts","../src/utils/url-builder.ts","../src/utils/validation.ts","../src/client.ts"],"names":["DEFAULT_BASE_URL"],"mappings":";;;AAIO,IAAM,QAAA,GAAN,cAAuB,KAAA,CAAM;AAAA,EAClB,IAAA;AAAA,EAEhB,WAAA,CAAY,OAAA,EAAiB,IAAA,EAAc,OAAA,EAAwB;AACjE,IAAA,KAAA,CAAM,SAAS,OAAO,CAAA;AACtB,IAAA,IAAA,CAAK,IAAA,GAAO,UAAA;AACZ,IAAA,IAAA,CAAK,IAAA,GAAO,IAAA;AAAA,EACd;AACF;AAKO,IAAM,WAAA,GAAN,cAA0B,QAAA,CAAS;AAAA,EACxB,UAAA;AAAA,EACA,UAAA;AAAA,EAEhB,WAAA,CAAY,UAAA,EAAoB,UAAA,EAAoB,IAAA,EAAe;AACjE,IAAA,MAAM,OAAA,GAAU,CAAA,iBAAA,EAAoB,UAAU,CAAA,CAAA,EAAI,UAAU,GAAG,IAAA,GAAO,CAAA,EAAA,EAAK,IAAI,CAAA,CAAA,GAAK,EAAE,CAAA,CAAA;AACtF,IAAA,KAAA,CAAM,SAAS,eAAe,CAAA;AAC9B,IAAA,IAAA,CAAK,IAAA,GAAO,aAAA;AACZ,IAAA,IAAA,CAAK,UAAA,GAAa,UAAA;AAClB,IAAA,IAAA,CAAK,UAAA,GAAa,UAAA;AAAA,EACpB;AACF;AAKO,IAAM,eAAA,GAAN,cAA8B,QAAA,CAAS;AAAA,EAC5C,WAAA,CAAY,SAAiB,KAAA,EAAiB;AAC5C,IAAA,KAAA,CAAM,OAAA,EAAS,mBAAA,EAAqB,EAAE,KAAA,EAAO,CAAA;AAC7C,IAAA,IAAA,CAAK,IAAA,GAAO,iBAAA;AAAA,EACd;AACF;AAKO,IAAM,aAAA,GAAN,cAA4B,QAAA,CAAS;AAAA,EAC1C,WAAA,CAAY,SAAiB,KAAA,EAAiB;AAC5C,IAAA,KAAA,CAAM,OAAA,EAAS,iBAAA,EAAmB,EAAE,KAAA,EAAO,CAAA;AAC3C,IAAA,IAAA,CAAK,IAAA,GAAO,eAAA;AAAA,EACd;AACF;AAKO,IAAM,kBAAA,GAAN,cAAiC,QAAA,CAAS;AAAA,EAC/C,YAAY,OAAA,EAAiB;AAC3B,IAAA,KAAA,CAAM,SAAS,sBAAsB,CAAA;AACrC,IAAA,IAAA,CAAK,IAAA,GAAO,oBAAA;AAAA,EACd;AACF;;;AC3CO,SAAS,kBAAkB,IAAA,EAAmD;AACnF,EAAA,MAAM,WAAW,IAAA,CAAK,QAAA;AACtB,EAAA,IAAI,CAAC,QAAA,IAAY,QAAA,CAAS,MAAA,KAAW,CAAA,EAAG;AACtC,IAAA,OAAO,EAAC;AAAA,EACV;AAEA,EAAA,MAAM,YAAY,IAAA,CAAK,SAAA;AACvB,EAAA,IAAI,CAAC,WAAW,UAAA,EAAY;AAC1B,IAAA,MAAM,IAAI,cAAc,kDAAkD,CAAA;AAAA,EAC5E;AAEA,EAAA,MAAM,UAAA,GAAa,UAAU,UAAA,CAAW,MAAA;AACxC,EAAA,MAAM,OAAA,GAAU,UAAU,UAAA,CAAW,WAAA;AAErC,EAAA,MAAM,gBAAA,GAAmB,kBAAA,CAAmB,UAAA,EAAY,UAAU,CAAA;AAClE,EAAA,MAAM,aAAA,GAAgB,kBAAA,CAAmB,UAAA,EAAY,gBAAgB,CAAA;AACrE,EAAA,MAAM,YAAA,GAAe,6BAAA,CAA8B,OAAA,EAAS,aAAa,CAAA;AAEzE,EAAA,MAAM,cAAA,GAAiB,UAAA,CAAW,gBAAgB,CAAA,EAAG,MAAA;AACrD,EAAA,MAAM,WAAA,GAAc,UAAA,CAAW,aAAa,CAAA,EAAG,MAAA;AAC/C,EAAA,MAAM,UAAA,GAAa,OAAA,CAAQ,YAAY,CAAA,EAAG,MAAA;AAE1C,EAAA,IAAI,CAAC,cAAA,IAAkB,CAAC,WAAA,IAAe,CAAC,UAAA,EAAY;AAClD,IAAA,MAAM,IAAI,cAAc,8CAA8C,CAAA;AAAA,EACxE;AAEA,EAAA,MAAM,eAA0C,EAAC;AAEjD,EAAA,KAAA,MAAW,WAAW,QAAA,EAAU;AAC9B,IAAA,MAAM,SAAS,OAAA,CAAQ,MAAA;AACvB,IAAA,IAAI,CAAC,MAAA,EAAQ;AAEb,IAAA,KAAA,MAAW,CAAC,SAAA,EAAW,UAAU,KAAK,MAAA,CAAO,OAAA,CAAQ,MAAM,CAAA,EAAG;AAC5D,MAAA,MAAM,aAAa,SAAA,CAAU,KAAA,CAAM,GAAG,CAAA,CAAE,IAAI,MAAM,CAAA;AAElD,MAAA,MAAM,WAAA,GAAc,WAAW,gBAAgB,CAAA;AAC/C,MAAA,MAAM,QAAA,GAAW,WAAW,aAAa,CAAA;AAEzC,MAAA,IAAI,WAAA,KAAgB,MAAA,IAAa,QAAA,KAAa,MAAA,EAAW;AACvD,QAAA;AAAA,MACF;AAEA,MAAA,MAAM,QAAA,GAAW,cAAA,CAAe,WAAW,CAAA,EAAG,EAAA;AAC9C,MAAA,MAAM,YAAA,GAAe,WAAA,CAAY,QAAQ,CAAA,EAAG,EAAA;AAE5C,MAAA,IAAI,CAAC,QAAA,IAAY,CAAC,YAAA,EAAc;AAEhC,MAAA,KAAA,MAAW,CAAC,QAAQ,SAAS,CAAA,IAAK,OAAO,OAAA,CAAQ,UAAA,CAAW,YAAY,CAAA,EAAG;AACzE,QAAA,MAAM,OAAA,GAAU,OAAO,MAAM,CAAA;AAC7B,QAAA,MAAM,IAAA,GAAO,UAAA,CAAW,OAAO,CAAA,EAAG,EAAA;AAClC,QAAA,MAAM,IAAA,GAAO,UAAU,CAAC,CAAA;AAExB,QAAA,IAAI,CAAC,IAAA,IAAQ,IAAA,KAAS,IAAA,IAAQ,SAAS,MAAA,EAAW;AAElD,QAAA,YAAA,CAAa,KAAK,EAAE,IAAA,EAAM,QAAA,EAAU,YAAA,EAAc,MAAM,CAAA;AAAA,MAC1D;AAAA,IACF;AAAA,EACF;AAEA,EAAA,OAAO,YAAA;AACT;AAKO,SAAS,cAAc,GAAA,EAA+B;AAC3D,EAAA,IAAI;AACF,IAAA,OAAO,IAAA,CAAK,MAAM,GAAG,CAAA;AAAA,EACvB,SAAS,KAAA,EAAO;AACd,IAAA,MAAM,IAAI,aAAA,CAAc,oCAAA,EAAsC,KAAK,CAAA;AAAA,EACrE;AACF;AAIA,SAAS,kBAAA,CAAmB,MAA6C,EAAA,EAAoB;AAC3F,EAAA,MAAM,QAAQ,IAAA,CAAK,SAAA,CAAU,CAAC,CAAA,KAAM,CAAA,CAAE,OAAO,EAAE,CAAA;AAC/C,EAAA,IAAI,UAAU,EAAA,EAAI;AAChB,IAAA,MAAM,IAAI,aAAA,CAAc,CAAA,0BAAA,EAA6B,EAAE,CAAA,yBAAA,CAA2B,CAAA;AAAA,EACpF;AACA,EAAA,OAAO,KAAA;AACT;AAEA,SAAS,6BAAA,CACP,MACA,EAAA,EACQ;AACR,EAAA,MAAM,QAAQ,IAAA,CAAK,SAAA,CAAU,CAAC,CAAA,KAAM,CAAA,CAAE,OAAO,EAAE,CAAA;AAC/C,EAAA,IAAI,UAAU,EAAA,EAAI;AAChB,IAAA,MAAM,IAAI,aAAA,CAAc,CAAA,+BAAA,EAAkC,EAAE,CAAA,yBAAA,CAA2B,CAAA;AAAA,EACzF;AACA,EAAA,OAAO,KAAA;AACT;;;AC1FO,IAAM,mBAAN,MAA8C;AAAA,EAClC,OAAA;AAAA,EACA,SAAA;AAAA,EAEjB,WAAA,CACE,UAAmC,UAAA,CAAW,KAAA,CAAM,KAAK,UAAU,CAAA,EACnE,YAAY,GAAA,EACZ;AACA,IAAA,IAAA,CAAK,OAAA,GAAU,OAAA;AACf,IAAA,IAAA,CAAK,SAAA,GAAY,SAAA;AAAA,EACnB;AAAA,EAEA,MAAM,GAAA,CAAI,GAAA,EAAa,cAAA,EAA+C;AACpE,IAAA,MAAM,iBAAA,GAAoB,IAAI,eAAA,EAAgB;AAC9C,IAAA,MAAM,YAAY,UAAA,CAAW,MAAM,kBAAkB,KAAA,EAAM,EAAG,KAAK,SAAS,CAAA;AAG5E,IAAA,MAAM,MAAA,GAAS,cAAA,GACX,WAAA,CAAY,GAAA,CAAI,CAAC,gBAAgB,iBAAA,CAAkB,MAAM,CAAC,CAAA,GAC1D,iBAAA,CAAkB,MAAA;AAEtB,IAAA,IAAI;AACF,MAAA,MAAM,QAAA,GAAW,MAAM,IAAA,CAAK,OAAA,CAAQ,GAAA,EAAK;AAAA,QACvC,MAAA,EAAQ,KAAA;AAAA,QACR,OAAA,EAAS,EAAE,MAAA,EAAQ,kBAAA,EAAmB;AAAA,QACtC;AAAA,OACD,CAAA;AAED,MAAA,IAAI,CAAC,SAAS,EAAA,EAAI;AAChB,QAAA,MAAM,OAAO,MAAM,QAAA,CAAS,MAAK,CAAE,KAAA,CAAM,MAAM,EAAE,CAAA;AACjD,QAAA,MAAM,IAAI,WAAA,CAAY,QAAA,CAAS,MAAA,EAAQ,QAAA,CAAS,YAAY,IAAI,CAAA;AAAA,MAClE;AAEA,MAAA,OAAO,MAAM,SAAS,IAAA,EAAK;AAAA,IAC7B,SAAS,KAAA,EAAO;AACd,MAAA,IAAI,iBAAiB,WAAA,EAAa;AAChC,QAAA,MAAM,KAAA;AAAA,MACR;AAEA,MAAA,IAAI,KAAA,YAAiB,KAAA,IAAS,KAAA,CAAM,IAAA,KAAS,YAAA,EAAc;AACzD,QAAA,MAAM,IAAI,gBAAgB,CAAA,wBAAA,EAA2B,IAAA,CAAK,SAAS,CAAA,IAAA,EAAO,GAAG,IAAI,KAAK,CAAA;AAAA,MACxF;AAEA,MAAA,MAAM,IAAI,eAAA;AAAA,QACR,CAAA,2BAAA,EAA8B,GAAG,CAAA,EAAA,EAAK,KAAA,YAAiB,QAAQ,KAAA,CAAM,OAAA,GAAU,MAAA,CAAO,KAAK,CAAC,CAAA,CAAA;AAAA,QAC5F;AAAA,OACF;AAAA,IACF,CAAA,SAAE;AACA,MAAA,YAAA,CAAa,SAAS,CAAA;AAAA,IACxB;AAAA,EACF;AACF;;;AClEA,IAAM,gBAAA,GAAmB,wCAAA;AAWlB,SAAS,oBAAA,CACd,KAAA,EACA,OAAA,GAAkB,gBAAA,EACV;AACR,EAAA,MAAM,SAAA,GAAY,MAAM,SAAA,IAAa,GAAA;AACrC,EAAA,MAAM,WAAA,GAAc,KAAA,CAAM,UAAA,CAAW,IAAA,CAAK,GAAG,CAAA;AAC7C,EAAA,MAAM,YAAA,GAAe,MAAM,YAAA,IAAgB,KAAA;AAG3C,EAAA,MAAM,YAAY,CAAA,EAAG,SAAS,CAAA,CAAA,EAAI,WAAW,IAAI,YAAY,CAAA,OAAA,CAAA;AAE7D,EAAA,MAAM,MAAM,IAAI,GAAA,CAAI,GAAG,OAAO,CAAA,UAAA,EAAa,SAAS,CAAA,CAAE,CAAA;AACtD,EAAA,GAAA,CAAI,YAAA,CAAa,GAAA,CAAI,aAAA,EAAe,KAAA,CAAM,SAAS,CAAA;AAEnD,EAAA,IAAI,KAAA,CAAM,YAAY,MAAA,EAAW;AAC/B,IAAA,GAAA,CAAI,YAAA,CAAa,GAAA,CAAI,WAAA,EAAa,KAAA,CAAM,OAAO,CAAA;AAAA,EACjD;AAEA,EAAA,OAAO,IAAI,QAAA,EAAS;AACtB;;;AC7BA,IAAM,cAAA,GAAiB,qBAAA;AACvB,IAAM,cAAA,GAAiB,YAAA;AAMhB,SAAS,cAAc,KAAA,EAAgC;AAC5D,EAAA,IAAI,KAAA,CAAM,UAAA,CAAW,MAAA,KAAW,CAAA,EAAG;AACjC,IAAA,MAAM,IAAI,mBAAmB,0CAA0C,CAAA;AAAA,EACzE;AAEA,EAAA,KAAA,MAAW,QAAA,IAAY,MAAM,UAAA,EAAY;AACvC,IAAA,IAAI,CAAC,cAAA,CAAe,IAAA,CAAK,QAAQ,CAAA,EAAG;AAClC,MAAA,MAAM,IAAI,kBAAA;AAAA,QACR,0BAA0B,QAAQ,CAAA,oCAAA;AAAA,OACpC;AAAA,IACF;AAAA,EACF;AAEA,EAAA,IAAI,CAAC,cAAA,CAAe,IAAA,CAAK,KAAA,CAAM,SAAS,CAAA,EAAG;AACzC,IAAA,MAAM,IAAI,kBAAA;AAAA,MACR,CAAA,mBAAA,EAAsB,MAAM,SAAS,CAAA,+BAAA;AAAA,KACvC;AAAA,EACF;AAEA,EAAA,IAAI,KAAA,CAAM,YAAY,MAAA,IAAa,CAAC,eAAe,IAAA,CAAK,KAAA,CAAM,OAAO,CAAA,EAAG;AACtE,IAAA,MAAM,IAAI,kBAAA;AAAA,MACR,CAAA,iBAAA,EAAoB,MAAM,OAAO,CAAA,+BAAA;AAAA,KACnC;AAAA,EACF;AAEA,EAAA,IAAI,MAAM,OAAA,KAAY,MAAA,IAAa,KAAA,CAAM,SAAA,GAAY,MAAM,OAAA,EAAS;AAClE,IAAA,MAAM,IAAI,kBAAA;AAAA,MACR,CAAA,WAAA,EAAc,KAAA,CAAM,SAAS,CAAA,6BAAA,EAAgC,MAAM,OAAO,CAAA,EAAA;AAAA,KAC5E;AAAA,EACF;AAEA,EAAA,IAAI,KAAA,CAAM,iBAAiB,MAAA,IAAa,CAAC,eAAe,IAAA,CAAK,KAAA,CAAM,YAAY,CAAA,EAAG;AAChF,IAAA,MAAM,IAAI,kBAAA;AAAA,MACR,CAAA,sBAAA,EAAyB,MAAM,YAAY,CAAA,oCAAA;AAAA,KAC7C;AAAA,EACF;AACF;;;ACjCA,IAAMA,iBAAAA,GAAmB,wCAAA;AACzB,IAAM,qBAAA,GAAwB,KAAA;AA6BvB,IAAM,SAAA,GAAN,MAAM,UAAA,CAAU;AAAA,EACJ,OAAA;AAAA,EACA,YAAA;AAAA,EACA,OAAA;AAAA,EAEjB,WAAA,CAAY,MAAA,GAA0B,EAAC,EAAG;AACxC,IAAA,IAAA,CAAK,OAAA,GAAU,OAAO,OAAA,IAAWA,iBAAAA;AACjC,IAAA,IAAA,CAAK,YAAA,GAAe,OAAO,YAAA,IAAgB,qBAAA;AAC3C,IAAA,IAAA,CAAK,UAAU,IAAI,gBAAA,CAAiB,MAAA,CAAO,OAAA,EAAS,OAAO,SAAS,CAAA;AAAA,EACtE;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,OAAO,WAAA,CACL,OAAA,EACA,MAAA,GAA4D,EAAC,EAClD;AACX,IAAA,MAAM,MAAA,GAAS,IAAI,UAAA,CAAU,MAAM,CAAA;AACnC,IAAA,MAAA,CAAO,eAAe,MAAA,EAAQ,SAAA,EAAW,EAAE,KAAA,EAAO,SAAS,CAAA;AAC3D,IAAA,OAAO,MAAA;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,MAAM,OAAA,CAAQ,QAAA,EAAkB,IAAA,EAA2C;AACzE,IAAA,MAAM,KAAA,GAA2B;AAAA,MAC/B,UAAA,EAAY,CAAC,QAAQ,CAAA;AAAA,MACrB,SAAA,EAAW,IAAA;AAAA,MACX,OAAA,EAAS;AAAA,KACX;AACA,IAAA,OAAO,IAAA,CAAK,uBAAuB,KAAK,CAAA;AAAA,EAC1C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,MAAM,cAAA,CACJ,QAAA,EACA,SAAA,EACA,OAAA,EACA,YAAuB,GAAA,EACM;AAC7B,IAAA,MAAM,KAAA,GAA2B;AAAA,MAC/B,UAAA,EAAY,CAAC,QAAQ,CAAA;AAAA,MACrB,SAAA;AAAA,MACA,OAAA;AAAA,MACA;AAAA,KACF;AACA,IAAA,OAAO,IAAA,CAAK,uBAAuB,KAAK,CAAA;AAAA,EAC1C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,SAAS,KAAA,EAAwD;AACrE,IAAA,MAAM,QAAA,GAAW,IAAA,CAAK,YAAA,CAAa,KAAK,CAAA;AACxC,IAAA,aAAA,CAAc,QAAQ,CAAA;AAEtB,IAAA,MAAM,YAAA,GAAe,MAAM,IAAA,CAAK,aAAA,CAAc,QAAQ,CAAA;AACtD,IAAA,OAAO,IAAA,CAAK,8BAAA,CAA+B,YAAA,EAAc,QAAQ,CAAA;AAAA,EACnE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,gBAAgB,KAAA,EAA8D;AAClF,IAAA,MAAM,QAAA,GAAW,IAAA,CAAK,YAAA,CAAa,KAAK,CAAA;AACxC,IAAA,aAAA,CAAc,QAAQ,CAAA;AACtB,IAAA,OAAO,IAAA,CAAK,cAAc,QAAQ,CAAA;AAAA,EACpC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,MAAM,OAAA,CACJ,MAAA,EACA,QAAA,EACA,IAAA,EACkF;AAClF,IAAA,MAAM,MAAA,GAAS,MAAM,IAAA,CAAK,OAAA,CAAQ,UAAU,IAAI,CAAA;AAChD,IAAA,MAAM,UAAA,GAAa,MAAA,CAAO,KAAA,CAAM,OAAA,GAAU,IAAA,EAAK;AAE/C,IAAA,IAAI,WAAW,IAAA,EAAM;AACnB,MAAA,OAAO,IAAA;AAAA,IACT;AAEA,IAAA,MAAM,CAAC,UAAA,EAAY,IAAI,CAAA,GAAI,UAAA,CAAW,KAAA;AAEtC,IAAA,OAAO;AAAA,MACL,QAAQ,IAAA,CAAK,KAAA,CAAM,MAAA,GAAS,IAAA,GAAO,GAAG,CAAA,GAAI,GAAA;AAAA,MAC1C,IAAA;AAAA,MACA,IAAA,EAAM,UAAA;AAAA,MACN;AAAA,KACF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQQ,aAAa,KAAA,EAA6C;AAChE,IAAA,IAAI,KAAA,CAAM,iBAAiB,MAAA,EAAW;AACpC,MAAA,OAAO,KAAA;AAAA,IACT;AACA,IAAA,OAAO,EAAE,GAAG,KAAA,EAAO,YAAA,EAAc,KAAK,YAAA,EAAa;AAAA,EACrD;AAAA,EAEA,MAAc,cAAc,KAAA,EAA8D;AACxF,IAAA,MAAM,GAAA,GAAM,oBAAA,CAAqB,KAAA,EAAO,IAAA,CAAK,OAAO,CAAA;AACpD,IAAA,MAAM,GAAA,GAAM,MAAM,IAAA,CAAK,OAAA,CAAQ,IAAI,GAAG,CAAA;AACtC,IAAA,MAAM,IAAA,GAAO,cAAc,GAAG,CAAA;AAC9B,IAAA,OAAO,kBAAkB,IAAI,CAAA;AAAA,EAC/B;AAAA,EAEA,MAAc,uBAAuB,KAAA,EAAuD;AAC1F,IAAA,MAAM,QAAA,GAAW,IAAA,CAAK,YAAA,CAAa,KAAK,CAAA;AACxC,IAAA,aAAA,CAAc,QAAQ,CAAA;AAEtB,IAAA,MAAM,YAAA,GAAe,MAAM,IAAA,CAAK,aAAA,CAAc,QAAQ,CAAA;AAEtD,IAAA,MAAM,KAAA,uBAAY,GAAA,EAAoB;AACtC,IAAA,KAAA,MAAW,OAAO,YAAA,EAAc;AAC9B,MAAA,KAAA,CAAM,GAAA,CAAI,GAAA,CAAI,IAAA,EAAM,GAAA,CAAI,IAAI,CAAA;AAAA,IAC9B;AAGA,IAAA,MAAM,OAAO,YAAA,CAAa,CAAC,GAAG,YAAA,IAAgB,QAAA,CAAS,gBAAgB,IAAA,CAAK,YAAA;AAE5E,IAAA,OAAO;AAAA,MACL,IAAA;AAAA,MACA,QAAA,EAAU,QAAA,CAAS,UAAA,CAAW,CAAC,CAAA;AAAA,MAC/B;AAAA,KACF;AAAA,EACF;AAAA,EAEQ,8BAAA,CACN,cACA,KAAA,EACqB;AACrB,IAAA,MAAM,KAAA,uBAAY,GAAA,EAAoC;AAEtD,IAAA,KAAA,MAAW,OAAO,YAAA,EAAc;AAC9B,MAAA,IAAI,SAAA,GAAY,KAAA,CAAM,GAAA,CAAI,GAAA,CAAI,IAAI,CAAA;AAClC,MAAA,IAAI,CAAC,SAAA,EAAW;AACd,QAAA,SAAA,GAAY,EAAC;AACb,QAAA,KAAA,CAAM,GAAA,CAAI,GAAA,CAAI,IAAA,EAAM,SAAS,CAAA;AAAA,MAC/B;AACA,MAAA,SAAA,CAAU,GAAA,CAAI,QAAQ,CAAA,GAAI,GAAA,CAAI,IAAA;AAAA,IAChC;AAGA,IAAA,MAAM,OAAO,YAAA,CAAa,CAAC,GAAG,YAAA,IAAgB,KAAA,CAAM,gBAAgB,IAAA,CAAK,YAAA;AAEzE,IAAA,OAAO;AAAA,MACL,IAAA;AAAA,MACA,YAAY,KAAA,CAAM,UAAA;AAAA,MAClB;AAAA,KACF;AAAA,EACF;AACF","file":"index.cjs","sourcesContent":["/**\n * Base error for all ECB client errors.\n * Follows the Liskov Substitution Principle — all subtypes are interchangeable.\n */\nexport class EcbError extends Error {\n  public readonly code: string;\n\n  constructor(message: string, code: string, options?: ErrorOptions) {\n    super(message, options);\n    this.name = \"EcbError\";\n    this.code = code;\n  }\n}\n\n/**\n * Thrown when the ECB API returns an HTTP error.\n */\nexport class EcbApiError extends EcbError {\n  public readonly statusCode: number;\n  public readonly statusText: string;\n\n  constructor(statusCode: number, statusText: string, body?: string) {\n    const message = `ECB API returned ${statusCode} ${statusText}${body ? `: ${body}` : \"\"}`;\n    super(message, \"ECB_API_ERROR\");\n    this.name = \"EcbApiError\";\n    this.statusCode = statusCode;\n    this.statusText = statusText;\n  }\n}\n\n/**\n * Thrown when the network request fails (timeout, DNS, connection refused, etc.).\n */\nexport class EcbNetworkError extends EcbError {\n  constructor(message: string, cause?: unknown) {\n    super(message, \"ECB_NETWORK_ERROR\", { cause });\n    this.name = \"EcbNetworkError\";\n  }\n}\n\n/**\n * Thrown when the API response cannot be parsed.\n */\nexport class EcbParseError extends EcbError {\n  constructor(message: string, cause?: unknown) {\n    super(message, \"ECB_PARSE_ERROR\", { cause });\n    this.name = \"EcbParseError\";\n  }\n}\n\n/**\n * Thrown when query parameters are invalid.\n */\nexport class EcbValidationError extends EcbError {\n  constructor(message: string) {\n    super(message, \"ECB_VALIDATION_ERROR\");\n    this.name = \"EcbValidationError\";\n  }\n}\n","import { EcbParseError } from \"../errors/index.js\";\nimport type { ExchangeRateObservation, SdmxJsonResponse, SdmxStructure } from \"../types/index.js\";\n\n/**\n * Parses an SDMX-JSON response from the ECB into typed observations.\n *\n * Single Responsibility: only concerned with SDMX-JSON → typed data transformation.\n *\n * The ECB SDMX-JSON format uses index-based keys:\n * - Series keys (e.g. \"0:0:0:0:0\") map to dimension value indices\n * - Observation keys (e.g. \"0\") map to observation-dimension value indices\n * - Observation values are tuples: [rate, ...attributeIndices]\n *\n * @see https://data.ecb.europa.eu/help/api/data\n */\nexport function parseJsonResponse(data: SdmxJsonResponse): ExchangeRateObservation[] {\n  const dataSets = data.dataSets;\n  if (!dataSets || dataSets.length === 0) {\n    return [];\n  }\n\n  const structure = data.structure;\n  if (!structure?.dimensions) {\n    throw new EcbParseError(\"SDMX-JSON response missing structure.dimensions.\");\n  }\n\n  const seriesDims = structure.dimensions.series;\n  const obsDims = structure.dimensions.observation;\n\n  const currencyDimIndex = findDimensionIndex(seriesDims, \"CURRENCY\");\n  const denomDimIndex = findDimensionIndex(seriesDims, \"CURRENCY_DENOM\");\n  const timeDimIndex = findObservationDimensionIndex(obsDims, \"TIME_PERIOD\");\n\n  const currencyValues = seriesDims[currencyDimIndex]?.values;\n  const denomValues = seriesDims[denomDimIndex]?.values;\n  const timeValues = obsDims[timeDimIndex]?.values;\n\n  if (!currencyValues || !denomValues || !timeValues) {\n    throw new EcbParseError(\"SDMX-JSON response missing dimension values.\");\n  }\n\n  const observations: ExchangeRateObservation[] = [];\n\n  for (const dataSet of dataSets) {\n    const series = dataSet.series;\n    if (!series) continue;\n\n    for (const [seriesKey, seriesData] of Object.entries(series)) {\n      const dimIndices = seriesKey.split(\":\").map(Number);\n\n      const currencyIdx = dimIndices[currencyDimIndex];\n      const denomIdx = dimIndices[denomDimIndex];\n\n      if (currencyIdx === undefined || denomIdx === undefined) {\n        continue;\n      }\n\n      const currency = currencyValues[currencyIdx]?.id;\n      const baseCurrency = denomValues[denomIdx]?.id;\n\n      if (!currency || !baseCurrency) continue;\n\n      for (const [obsKey, obsValues] of Object.entries(seriesData.observations)) {\n        const timeIdx = Number(obsKey);\n        const date = timeValues[timeIdx]?.id;\n        const rate = obsValues[0];\n\n        if (!date || rate === null || rate === undefined) continue;\n\n        observations.push({ date, currency, baseCurrency, rate });\n      }\n    }\n  }\n\n  return observations;\n}\n\n/**\n * Safely parses a raw JSON string into an SdmxJsonResponse.\n */\nexport function parseSdmxJson(raw: string): SdmxJsonResponse {\n  try {\n    return JSON.parse(raw) as SdmxJsonResponse;\n  } catch (error) {\n    throw new EcbParseError(\"Failed to parse ECB JSON response.\", error);\n  }\n}\n\n// ── Private helpers ────────────────────────────────────────────────────\n\nfunction findDimensionIndex(dims: SdmxStructure[\"dimensions\"][\"series\"], id: string): number {\n  const index = dims.findIndex((d) => d.id === id);\n  if (index === -1) {\n    throw new EcbParseError(`Missing series dimension \"${id}\" in SDMX-JSON structure.`);\n  }\n  return index;\n}\n\nfunction findObservationDimensionIndex(\n  dims: SdmxStructure[\"dimensions\"][\"observation\"],\n  id: string,\n): number {\n  const index = dims.findIndex((d) => d.id === id);\n  if (index === -1) {\n    throw new EcbParseError(`Missing observation dimension \"${id}\" in SDMX-JSON structure.`);\n  }\n  return index;\n}\n","import { EcbApiError, EcbNetworkError } from \"../errors/index.js\";\n\n/**\n * Contract for HTTP fetching — enables dependency inversion.\n * Consumers depend on this abstraction, not on concrete fetch implementations.\n */\nexport interface HttpFetcher {\n  get(url: string, signal?: AbortSignal): Promise<string>;\n}\n\n/**\n * Default HTTP fetcher using the global `fetch` API.\n * Single Responsibility: only concerned with HTTP GET and error mapping.\n *\n * Dependency Inversion: Accepts `fetch` as a constructor parameter,\n * allowing tests or consumers to inject alternatives.\n */\nexport class FetchHttpFetcher implements HttpFetcher {\n  private readonly fetchFn: typeof globalThis.fetch;\n  private readonly timeoutMs: number;\n\n  constructor(\n    fetchFn: typeof globalThis.fetch = globalThis.fetch.bind(globalThis),\n    timeoutMs = 30_000,\n  ) {\n    this.fetchFn = fetchFn;\n    this.timeoutMs = timeoutMs;\n  }\n\n  async get(url: string, externalSignal?: AbortSignal): Promise<string> {\n    const timeoutController = new AbortController();\n    const timeoutId = setTimeout(() => timeoutController.abort(), this.timeoutMs);\n\n    // Combine external abort signal with our timeout signal\n    const signal = externalSignal\n      ? AbortSignal.any([externalSignal, timeoutController.signal])\n      : timeoutController.signal;\n\n    try {\n      const response = await this.fetchFn(url, {\n        method: \"GET\",\n        headers: { Accept: \"application/json\" },\n        signal,\n      });\n\n      if (!response.ok) {\n        const body = await response.text().catch(() => \"\");\n        throw new EcbApiError(response.status, response.statusText, body);\n      }\n\n      return await response.text();\n    } catch (error) {\n      if (error instanceof EcbApiError) {\n        throw error;\n      }\n\n      if (error instanceof Error && error.name === \"AbortError\") {\n        throw new EcbNetworkError(`Request timed out after ${this.timeoutMs}ms: ${url}`, error);\n      }\n\n      throw new EcbNetworkError(\n        `Network request failed for ${url}: ${error instanceof Error ? error.message : String(error)}`,\n        error,\n      );\n    } finally {\n      clearTimeout(timeoutId);\n    }\n  }\n}\n","import type { ExchangeRateQuery } from \"../types/index.js\";\n\nconst DEFAULT_BASE_URL = \"https://data-api.ecb.europa.eu/service\";\n\n/**\n * Builds the ECB SDMX API URL for exchange rate queries.\n * Single Responsibility: only concerned with URL construction.\n *\n * URL pattern: {base}/data/EXR/{freq}.{currencies}.{baseCurrency}.SP00.A?params\n *\n * Content format is controlled via the HTTP Accept header (application/json),\n * not via a URL parameter.\n */\nexport function buildExchangeRateUrl(\n  query: ExchangeRateQuery,\n  baseUrl: string = DEFAULT_BASE_URL,\n): string {\n  const frequency = query.frequency ?? \"D\";\n  const currencyKey = query.currencies.join(\"+\");\n  const baseCurrency = query.baseCurrency ?? \"EUR\";\n\n  // EXR series key: FREQ.CURRENCY.CURRENCY_DENOM.EXR_TYPE.EXR_SUFFIX\n  const seriesKey = `${frequency}.${currencyKey}.${baseCurrency}.SP00.A`;\n\n  const url = new URL(`${baseUrl}/data/EXR/${seriesKey}`);\n  url.searchParams.set(\"startPeriod\", query.startDate);\n\n  if (query.endDate !== undefined) {\n    url.searchParams.set(\"endPeriod\", query.endDate);\n  }\n\n  return url.toString();\n}\n","import { EcbValidationError } from \"../errors/index.js\";\nimport type { ExchangeRateQuery } from \"../types/index.js\";\n\nconst ISO_DATE_REGEX = /^\\d{4}-\\d{2}-\\d{2}$/;\nconst CURRENCY_REGEX = /^[A-Z]{3}$/;\n\n/**\n * Validates exchange rate query parameters.\n * Single Responsibility: only concerned with input validation.\n */\nexport function validateQuery(query: ExchangeRateQuery): void {\n  if (query.currencies.length === 0) {\n    throw new EcbValidationError(\"At least one currency must be specified.\");\n  }\n\n  for (const currency of query.currencies) {\n    if (!CURRENCY_REGEX.test(currency)) {\n      throw new EcbValidationError(\n        `Invalid currency code \"${currency}\". Must be a 3-letter ISO 4217 code.`,\n      );\n    }\n  }\n\n  if (!ISO_DATE_REGEX.test(query.startDate)) {\n    throw new EcbValidationError(\n      `Invalid startDate \"${query.startDate}\". Expected format: YYYY-MM-DD.`,\n    );\n  }\n\n  if (query.endDate !== undefined && !ISO_DATE_REGEX.test(query.endDate)) {\n    throw new EcbValidationError(\n      `Invalid endDate \"${query.endDate}\". Expected format: YYYY-MM-DD.`,\n    );\n  }\n\n  if (query.endDate !== undefined && query.startDate > query.endDate) {\n    throw new EcbValidationError(\n      `startDate \"${query.startDate}\" must not be after endDate \"${query.endDate}\".`,\n    );\n  }\n\n  if (query.baseCurrency !== undefined && !CURRENCY_REGEX.test(query.baseCurrency)) {\n    throw new EcbValidationError(\n      `Invalid baseCurrency \"${query.baseCurrency}\". Must be a 3-letter ISO 4217 code.`,\n    );\n  }\n}\n","import { parseJsonResponse, parseSdmxJson } from \"./parsers/sdmx-json-parser.js\";\nimport { FetchHttpFetcher, type HttpFetcher } from \"./services/http-fetcher.js\";\nimport type {\n  EcbClientConfig,\n  ExchangeRateObservation,\n  ExchangeRateQuery,\n  ExchangeRateResult,\n  ExchangeRatesResult,\n  Frequency,\n} from \"./types/index.js\";\nimport { buildExchangeRateUrl } from \"./utils/url-builder.js\";\nimport { validateQuery } from \"./utils/validation.js\";\n\nconst DEFAULT_BASE_URL = \"https://data-api.ecb.europa.eu/service\";\nconst DEFAULT_BASE_CURRENCY = \"EUR\";\n\n/**\n * ECB Exchange Rates Client.\n *\n * Provides a clean, typed interface to the European Central Bank's\n * exchange rate reference data via the SDMX RESTful API.\n *\n * Uses the `Accept: application/json` header to receive SDMX-JSON\n * responses, then parses them into strongly-typed results.\n *\n * Design principles:\n * - **Single Responsibility**: Orchestrates query → fetch → parse → transform.\n * - **Open/Closed**: New data sources can be added via the `HttpFetcher` interface.\n * - **Dependency Inversion**: Depends on `HttpFetcher` abstraction, not `fetch` directly.\n * - **Interface Segregation**: Exposes focused methods for specific use cases.\n *\n * @example\n * ```ts\n * const client = new EcbClient();\n *\n * // Get rate for a specific date (defaults to EUR base)\n * const result = await client.getRate(\"USD\", \"2025-01-15\");\n * console.log(result.rates.get(\"2025-01-15\")); // e.g. 1.03\n *\n * // Use a different base currency\n * const client2 = new EcbClient({ baseCurrency: \"USD\" });\n * ```\n */\nexport class EcbClient {\n  private readonly baseUrl: string;\n  private readonly baseCurrency: string;\n  private readonly fetcher: HttpFetcher;\n\n  constructor(config: EcbClientConfig = {}) {\n    this.baseUrl = config.baseUrl ?? DEFAULT_BASE_URL;\n    this.baseCurrency = config.baseCurrency ?? DEFAULT_BASE_CURRENCY;\n    this.fetcher = new FetchHttpFetcher(config.fetchFn, config.timeoutMs);\n  }\n\n  /**\n   * Creates an EcbClient with a custom HttpFetcher implementation.\n   * Useful for testing or when you need full control over HTTP behavior.\n   */\n  static withFetcher(\n    fetcher: HttpFetcher,\n    config: Pick<EcbClientConfig, \"baseUrl\" | \"baseCurrency\"> = {},\n  ): EcbClient {\n    const client = new EcbClient(config);\n    Object.defineProperty(client, \"fetcher\", { value: fetcher });\n    return client;\n  }\n\n  /**\n   * Get the exchange rate for a single currency against the base currency.\n   *\n   * @param currency - Target currency code (e.g. \"USD\")\n   * @param date - The date to query (YYYY-MM-DD). Returns the nearest available rate.\n   */\n  async getRate(currency: string, date: string): Promise<ExchangeRateResult> {\n    const query: ExchangeRateQuery = {\n      currencies: [currency],\n      startDate: date,\n      endDate: date,\n    };\n    return this.getSingleCurrencyRates(query);\n  }\n\n  /**\n   * Get the exchange rate for a single currency over a date range.\n   *\n   * @param currency - Target currency code (e.g. \"USD\")\n   * @param startDate - Start date (YYYY-MM-DD)\n   * @param endDate - End date (YYYY-MM-DD)\n   * @param frequency - Data frequency (default: \"D\" daily)\n   */\n  async getRateHistory(\n    currency: string,\n    startDate: string,\n    endDate: string,\n    frequency: Frequency = \"D\",\n  ): Promise<ExchangeRateResult> {\n    const query: ExchangeRateQuery = {\n      currencies: [currency],\n      startDate,\n      endDate,\n      frequency,\n    };\n    return this.getSingleCurrencyRates(query);\n  }\n\n  /**\n   * Get exchange rates for multiple currencies.\n   *\n   * @param query - The query parameters\n   */\n  async getRates(query: ExchangeRateQuery): Promise<ExchangeRatesResult> {\n    const resolved = this.resolveQuery(query);\n    validateQuery(resolved);\n\n    const observations = await this.fetchAndParse(resolved);\n    return this.transformToMultiCurrencyResult(observations, resolved);\n  }\n\n  /**\n   * Get raw observations — useful when you need full control over the data.\n   *\n   * @param query - The query parameters\n   */\n  async getObservations(query: ExchangeRateQuery): Promise<ExchangeRateObservation[]> {\n    const resolved = this.resolveQuery(query);\n    validateQuery(resolved);\n    return this.fetchAndParse(resolved);\n  }\n\n  /**\n   * Convert an amount from the base currency to a target currency at a specific date.\n   *\n   * @param amount - The amount in the base currency\n   * @param currency - Target currency code\n   * @param date - The date for the exchange rate (YYYY-MM-DD)\n   * @returns The converted amount, or null if no rate is available\n   */\n  async convert(\n    amount: number,\n    currency: string,\n    date: string,\n  ): Promise<{ amount: number; rate: number; date: string; currency: string } | null> {\n    const result = await this.getRate(currency, date);\n    const firstEntry = result.rates.entries().next();\n\n    if (firstEntry.done) {\n      return null;\n    }\n\n    const [actualDate, rate] = firstEntry.value;\n\n    return {\n      amount: Math.round(amount * rate * 100) / 100,\n      rate,\n      date: actualDate,\n      currency,\n    };\n  }\n\n  // ── Private helpers ──────────────────────────────────────────────────\n\n  /**\n   * Resolves a query by applying the client's default baseCurrency\n   * when the query doesn't specify one.\n   */\n  private resolveQuery(query: ExchangeRateQuery): ExchangeRateQuery {\n    if (query.baseCurrency !== undefined) {\n      return query;\n    }\n    return { ...query, baseCurrency: this.baseCurrency };\n  }\n\n  private async fetchAndParse(query: ExchangeRateQuery): Promise<ExchangeRateObservation[]> {\n    const url = buildExchangeRateUrl(query, this.baseUrl);\n    const raw = await this.fetcher.get(url);\n    const json = parseSdmxJson(raw);\n    return parseJsonResponse(json);\n  }\n\n  private async getSingleCurrencyRates(query: ExchangeRateQuery): Promise<ExchangeRateResult> {\n    const resolved = this.resolveQuery(query);\n    validateQuery(resolved);\n\n    const observations = await this.fetchAndParse(resolved);\n\n    const rates = new Map<string, number>();\n    for (const obs of observations) {\n      rates.set(obs.date, obs.rate);\n    }\n\n    // Derive base from parsed response when available, fall back to query\n    const base = observations[0]?.baseCurrency ?? resolved.baseCurrency ?? this.baseCurrency;\n\n    return {\n      base,\n      currency: resolved.currencies[0] as string,\n      rates,\n    };\n  }\n\n  private transformToMultiCurrencyResult(\n    observations: ExchangeRateObservation[],\n    query: ExchangeRateQuery,\n  ): ExchangeRatesResult {\n    const rates = new Map<string, Record<string, number>>();\n\n    for (const obs of observations) {\n      let dateRates = rates.get(obs.date);\n      if (!dateRates) {\n        dateRates = {};\n        rates.set(obs.date, dateRates);\n      }\n      dateRates[obs.currency] = obs.rate;\n    }\n\n    // Derive base from parsed response when available, fall back to query\n    const base = observations[0]?.baseCurrency ?? query.baseCurrency ?? this.baseCurrency;\n\n    return {\n      base,\n      currencies: query.currencies,\n      rates,\n    };\n  }\n}\n"]}