@allratestoday/sdk 1.4.5 → 1.5.0

package/dist/index.mjs

@@ -2,10 +2,13 @@
 var DEFAULT_BASE_URL = "https://allratestoday.com";
 var DEFAULT_TIMEOUT = 1e4;
 var AllRatesTodayError = class extends Error {
-  constructor(message, status) {
+  constructor(message, status, code, details, options) {
     super(message);
     this.name = "AllRatesTodayError";
     this.status = status;
+    this.code = code ?? (status !== void 0 ? "http" : "invalid_argument");
+    this.details = details;
+    if (options?.cause !== void 0) this.cause = options.cause;
   }
 };
 var AllRatesToday = class {
@@ -30,7 +33,9 @@ var AllRatesToday = class {
     const key = override || this.apiKey;
     if (!key) {
       throw new AllRatesTodayError(
-        "API key is required. Register for free at https://allratestoday.com/register"
+        "API key is required. Register for free at https://allratestoday.com/register",
+        void 0,
+        "missing_key"
       );
     }
     return key;
@@ -47,24 +52,82 @@ var AllRatesToday = class {
     if (apiKey) {
       headers["Authorization"] = `Bearer ${apiKey}`;
     }
-    const response = await fetch(url.toString(), {
-      headers,
-      signal: AbortSignal.timeout(this.timeout)
-    });
+    let response;
+    try {
+      response = await fetch(url.toString(), {
+        headers,
+        signal: AbortSignal.timeout(this.timeout)
+      });
+    } catch (err) {
+      const name = err?.name;
+      if (name === "TimeoutError" || name === "AbortError") {
+        throw new AllRatesTodayError(`Request timed out after ${this.timeout} ms`, void 0, "timeout", void 0, { cause: err });
+      }
+      throw new AllRatesTodayError(
+        `Network error: ${err?.message ?? String(err)}`,
+        void 0,
+        "network",
+        void 0,
+        { cause: err }
+      );
+    }
     if (!response.ok) {
-      const error = await response.json().catch(() => ({ error: response.statusText }));
+      const body = await response.json().catch(() => ({ error: response.statusText }));
+      const details = body && typeof body === "object" ? body : void 0;
       throw new AllRatesTodayError(
-        error.error || `HTTP ${response.status}`,
-        response.status
+        details?.error || `HTTP ${response.status}`,
+        response.status,
+        "http",
+        details
       );
     }
     return response.json();
   }
   formatDate(date) {
-    if (date instanceof Date) {
-      return date.toISOString().split("T")[0];
+    const str = date instanceof Date ? date.toISOString().split("T")[0] : date;
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(str) || Number.isNaN(Date.parse(`${str}T00:00:00Z`))) {
+      throw new AllRatesTodayError(`Invalid date: ${String(date)}. Use YYYY-MM-DD or a Date.`);
+    }
+    return str;
+  }
+  requireSymbols(symbols, method) {
+    if (!symbols?.length) {
+      throw new AllRatesTodayError(`${method}() needs symbols, e.g. { symbols: ['EUR'] }. Each symbol is one request.`);
     }
-    return date;
+    return symbols;
+  }
+  /**
+   * Smallest history window that reaches back to `start`. Market history is
+   * served as windows ending today (7 days, 30 days, 1 year), so older dates
+   * are not available from the market-rate API.
+   */
+  windowFor(start) {
+    const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+    const days = Math.round((Date.parse(`${today}T00:00:00Z`) - Date.parse(`${start}T00:00:00Z`)) / 864e5);
+    if (days < 0) throw new AllRatesTodayError(`Date ${start} is in the future.`);
+    if (days <= 6) return "7d";
+    if (days <= 29) return "30d";
+    if (days <= 364) return "1y";
+    throw new AllRatesTodayError(
+      `Market-rate history covers the last 365 days; ${start} is older. For older dates use official central-bank rates: GET /api/v1/central-bank/{bank}/{date} (e.g. ECB from 1999).`
+    );
+  }
+  async history(source, target, period, key) {
+    const raw = await this.request(
+      "/api/historical-rates",
+      { source, target, period },
+      key
+    );
+    return (raw.data ?? []).slice().sort((a, b) => a.timestamp - b.timestamp);
+  }
+  /** Last point on or before `date` (YYYY-MM-DD). */
+  pointOn(points, date) {
+    let hit;
+    for (const p of points) {
+      if (p.date.slice(0, 10) <= date) hit = p;
+      else break;
+    }
+    return hit;
   }
   // -------------------------------------------------------------------------
   // Public API
@@ -102,89 +165,69 @@ var AllRatesToday = class {
     return { base: params.source, date, rates };
   }
   /**
-   * Get exchange rates for a specific historical date.
+   * Get mid-market rates for a past date within the last 365 days.
    *
-   * ```ts
-   * // Using a string
-   * const data = await client.forDate('2026-01-15');
+   * One history request per symbol. Billed per request by window: dates up to
+   * 29 days ago cost 1 call per symbol, older dates (up to 1 year) cost 12,
+   * because the 1-year window is weekly points. If a day has no point, the
+   * closest earlier one is used and reported in `rateDates`.
    *
-   * // Using a Date object
-   * const data = await client.forDate(new Date('2026-01-15'));
-   *
-   * // With options
-   * const data = await client.forDate('2026-01-15', { base: 'EUR', symbols: ['USD', 'GBP'] });
+   * ```ts
+   * const data = await client.forDate('2026-10-01', { base: 'USD', symbols: ['EUR', 'GBP'] });
+   * // { base: 'USD', date: '2026-10-01', rates: { EUR: 0.85, GBP: 0.74 }, rateDates: { ... } }
    * ```
    */
-  async forDate(date, options = {}) {
-    const key = this.resolveKey(options.apiKey);
+  async forDate(date, options) {
+    const key = this.resolveKey(options?.apiKey);
     const dateStr = this.formatDate(date);
-    const params = {
-      source: options.base || "USD",
-      from: dateStr,
-      to: dateStr
-    };
-    if (options.symbols?.length) {
-      params.target = options.symbols.join(",");
-    }
-    const raw = await this.request(
-      "/api/historical-rates",
-      params,
-      key
-    );
+    const symbols = this.requireSymbols(options?.symbols, "forDate");
+    const base = (options.base || "USD").toUpperCase();
+    const period = this.windowFor(dateStr);
     const rates = {};
-    if (raw.rates?.length) {
-      for (const r of raw.rates) {
-        rates[raw.target] = r.rate;
+    const rateDates = {};
+    for (const sym of symbols) {
+      const target = sym.toUpperCase();
+      const point = this.pointOn(await this.history(base, target, period, key), dateStr);
+      if (point) {
+        rates[target] = point.rate;
+        rateDates[target] = point.date.slice(0, 10);
       }
     }
-    if (raw.current) {
-      rates[raw.target] = raw.current.rate;
-    }
-    return { base: params.source, date: dateStr, rates };
+    return { base, date: dateStr, rates, rateDates };
   }
   /**
-   * Get exchange rate time series between two dates.
+   * Daily mid-market rates between two dates within the last 365 days.
    *
-   * ```ts
-   * const data = await client.timeSeries('2026-01-01', '2026-03-31', {
-   *   base: 'USD',
-   *   symbols: ['EUR', 'GBP'],
-   * });
+   * One history request per symbol. Ranges starting up to 29 days ago return
+   * daily points (1 call per symbol); older starts use the 1-year window,
+   * which has weekly points and costs 12 calls per symbol.
    *
-   * // Access rates by date
-   * console.log(data.rates['2026-01-15']); // { EUR: 0.92, GBP: 0.78 }
+   * ```ts
+   * const data = await client.timeSeries('2026-10-01', '2026-10-10', { symbols: ['EUR', 'GBP'] });
+   * console.log(data.rates['2026-10-05']); // { EUR: 0.86, GBP: 0.75 }
    * ```
    */
-  async timeSeries(startDate, endDate, options = {}) {
-    const key = this.resolveKey(options.apiKey);
+  async timeSeries(startDate, endDate, options) {
+    const key = this.resolveKey(options?.apiKey);
     const start = this.formatDate(startDate);
     const end = this.formatDate(endDate);
-    const source = options.base || "USD";
-    const params = {
-      source,
-      from: start,
-      to: end
-    };
-    if (options.symbols?.length) {
-      params.target = options.symbols.join(",");
-    }
-    const raw = await this.request(
-      "/api/historical-rates",
-      params,
-      key
-    );
+    if (start > end) throw new AllRatesTodayError(`startDate ${start} is after endDate ${end}.`);
+    const symbols = this.requireSymbols(options?.symbols, "timeSeries");
+    const base = (options.base || "USD").toUpperCase();
+    const period = this.windowFor(start);
     const rates = {};
-    if (raw.rates) {
-      for (const point of raw.rates) {
-        const dateKey = point.time.split("T")[0];
-        if (!rates[dateKey]) rates[dateKey] = {};
-        rates[dateKey][raw.target] = point.rate;
+    for (const sym of symbols) {
+      const target = sym.toUpperCase();
+      for (const point of await this.history(base, target, period, key)) {
+        const day = point.date.slice(0, 10);
+        if (day < start || day > end) continue;
+        (rates[day] ?? (rates[day] = {}))[target] = point.rate;
       }
     }
-    return { base: source, startDate: start, endDate: end, rates };
+    return { base, startDate: start, endDate: end, rates };
   }
   /**
-   * Get all supported currency symbols.
+   * Get all supported currency codes and names. **No API key needed.**
    *
    * ```ts
    * const { symbols } = await client.symbols();
@@ -196,8 +239,15 @@ var AllRatesToday = class {
    * ```
    */
   async symbols(options = {}) {
-    const key = this.resolveKey(options.apiKey);
-    return this.request("/api/v1/symbols", {}, key);
+    const raw = await this.request(
+      "/api/v1/symbols",
+      {},
+      options.apiKey
+    );
+    const currencies = raw.currencies ?? [];
+    const symbols = {};
+    for (const c of currencies) symbols[c.code] = c.name;
+    return { symbols, currencies, count: raw.count ?? currencies.length };
   }
   /**
    * Latest table of OFFICIAL rates published by a central bank or tax
@@ -210,12 +260,12 @@ var AllRatesToday = class {
    * const table = await client.officialRates('ecb');
    * console.log(table.rate_date, table.rates);
    *
-   * // One pair — cross-computed inside the bank's table when not published directly
+   * // One pair — published as-is or the inverse of a published rate (`derived: true`)
    * const usd = await client.officialRates('ecb', { source: 'EUR', target: 'USD' });
    * console.log(`ECB ${usd.rate_date}: 1 EUR = ${usd.rate} USD`);
    * ```
    *
-   * Dated tables and history need a free key: see `/api/v1/central-bank/{bank}/{date}`.
+   * Cross pairs and past dates need a key: use `officialRatesOn()`.
    */
   async officialRates(bank, options = {}) {
     const code = bank.trim().toLowerCase();
@@ -236,6 +286,39 @@ var AllRatesToday = class {
       options.apiKey
     );
   }
+  /**
+   * Official table (or one pair) as published on a given date. Needs an API
+   * key; 1 call. On weekends and holidays the last earlier publication is
+   * returned (`published_on_requested_date: false`). Unlike the keyless
+   * `officialRates()`, any pair inside the table can be cross-computed
+   * (`method: 'cross'`), e.g. USD/GBP from the ECB's EUR table.
+   *
+   * ```ts
+   * const r = await client.officialRatesOn('rbi', '2026-09-30', { source: 'USD', target: 'INR' });
+   * console.log(r.rate_date, r.rate); // 2026-09-30 95.9832
+   * ```
+   */
+  async officialRatesOn(bank, date, options = {}) {
+    const key = this.resolveKey(options.apiKey);
+    const code = bank.trim().toLowerCase();
+    if (!/^[a-z0-9_-]{2,20}$/.test(code)) {
+      throw new AllRatesTodayError(`Invalid source code: ${bank}. Call officialSources() for the list.`);
+    }
+    if (Boolean(options.source) !== Boolean(options.target)) {
+      throw new AllRatesTodayError("Provide both source and target, or neither.");
+    }
+    const dateStr = this.formatDate(date);
+    const params = {};
+    if (options.source && options.target) {
+      params.source = options.source.toUpperCase();
+      params.target = options.target.toUpperCase();
+    }
+    return this.request(
+      `/api/v1/central-bank/${encodeURIComponent(code)}/${dateStr}`,
+      params,
+      key
+    );
+  }
   /**
    * Every covered official source with its code, name, latest publication
    * date and whether it is behind schedule. **No API key needed.**
@@ -264,7 +347,20 @@ var AllRatesToday = class {
     const key = this.resolveKey(options.apiKey);
     const params = { source: from, target: to };
     if (amount !== void 0) params.amount = String(amount);
-    return this.request("/api/v1/rates", params, key);
+    const raw = await this.request("/api/v1/rates", params, key);
+    if (Array.isArray(raw) || !("from" in raw)) {
+      const r = Array.isArray(raw) ? raw[0] : raw;
+      if (!r) throw new AllRatesTodayError(`No rate returned for ${from}/${to}`);
+      const qty = amount ?? 1;
+      return {
+        from: { currency: r.source, amount: qty },
+        to: { currency: r.target, amount: Number((qty * r.rate).toFixed(6)) },
+        rate: r.rate,
+        source: "interbank",
+        time: r.time
+      };
+    }
+    return raw;
   }
   /**
    * Get authenticated exchange rates with metadata.
@@ -276,10 +372,12 @@ var AllRatesToday = class {
    */
   async getRates(source, target, options = {}) {
     const key = this.resolveKey(options.apiKey);
-    return this.request("/api/v1/rates", { source, target }, key);
+    const raw = await this.request("/api/v1/rates", { source, target }, key);
+    return Array.isArray(raw) ? raw : [raw];
   }
   /**
-   * Get historical rates by period.
+   * Mid-market history for a preset window ending today: `1d` (hourly),
+   * `7d` / `30d` (daily) or `1y` (weekly). `1y` is billed as 12 calls.
    *
    * ```ts
    * const history = await client.getHistoricalRates('USD', 'EUR', '30d');
@@ -290,11 +388,17 @@ var AllRatesToday = class {
    */
   async getHistoricalRates(source, target, period = "7d", options = {}) {
     const key = this.resolveKey(options.apiKey);
-    return this.request(
-      "/api/historical-rates",
-      { source, target, period },
-      key
-    );
+    const data = await this.history(source, target, period, key);
+    const rates = data.map((p) => ({ rate: p.rate, time: p.date }));
+    const last = rates[rates.length - 1];
+    return {
+      source: source.toUpperCase(),
+      target: target.toUpperCase(),
+      period,
+      current: last ?? { rate: 0, time: "" },
+      rates,
+      data
+    };
   }
   /**
    * Convert an amount between two currencies.
@@ -313,19 +417,21 @@ var AllRatesToday = class {
     const key = this.resolveKey(options.apiKey);
     if (options.date) {
       const dateStr = this.formatDate(options.date);
-      const params = {
-        source: from,
-        target: to,
-        from: dateStr,
-        to: dateStr
+      const target = to.toUpperCase();
+      const day = await this.forDate(dateStr, { base: from, symbols: [target], apiKey: key });
+      const rate = day.rates[target];
+      if (rate === void 0) {
+        throw new AllRatesTodayError(`No ${from}/${to} rate available on or before ${dateStr}`);
+      }
+      return {
+        from,
+        to,
+        amount,
+        result: Number((amount * rate).toFixed(6)),
+        rate,
+        date: dateStr,
+        rateDate: day.rateDates[target]
       };
-      const raw = await this.request(
-        "/api/historical-rates",
-        params,
-        key
-      );
-      const rate = raw.current?.rate ?? raw.rates?.[0]?.rate ?? 0;
-      return { from, to, amount, result: Number((amount * rate).toFixed(6)), rate, date: dateStr };
     }
     const data = await this.request(
       "/api/v1/rates",

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@allratestoday/sdk",
-  "version": "1.4.5",
-  "description": "Exchange Rate API — Real-time mid-market currency exchange rates for Node.js and browsers. 160+ currencies, zero dependencies, free tier.",
+  "version": "1.5.0",
+  "description": "Exchange rate API client: live mid-market rates for 160+ currencies and official rates from 121 central banks. TypeScript, zero dependencies, Node.js 18+.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "CHANGELOG.md"
   ],
   "exports": {
     ".": {