@allratestoday/sdk 1.3.10 → 1.4.0

package/README.md

@@ -15,6 +15,7 @@
 - 📡 **Real-Time Data** — Rates updated every 60 seconds
 - 💹 **Mid-Market Rates** — No retail spread or markup baked in
 - 🌍 **160+ Currencies** — Major, minor, and exotic currency pairs
+- 🏛️ **Official Rates Too** — latest tables from 121 central banks + 3 tax authorities via `officialRates()`, no key needed
 - 🔷 **Type-Safe** — Full TypeScript support with intelligent autocomplete
 - 🌐 **Universal** — Works seamlessly in Node.js 18+ and modern browsers
 - 🧑‍💻 **Developer-Friendly** — Simple API, extensive documentation, and great DX
@@ -257,6 +258,34 @@ const rate = await client.getRate('USD', 'EUR', 500);
 console.log(`$500 = €${rate.to.amount}`);
 ```
 
+### Official Central-Bank & Tax-Authority Rates (no key needed)
+
+The methods above return live mid-market rates. For the **official rate an
+institution published** — what invoices, VAT returns, customs declarations and
+audits require — use `officialRates()`. It covers 121 central banks plus HMRC,
+the US Treasury and Swiss BAZG, and the latest table needs **no API key**:
+
+```typescript
+const client = new AllRatesToday(); // no key
+
+// Full ECB reference table
+const table = await client.officialRates('ecb');
+console.log(table.rate_date, table.rates); // [{ base: 'EUR', quote: 'USD', type: 'reference', value: 1.17 }, …]
+
+// One pair (cross-computed inside the bank's own table if not published directly → `derived: true`)
+const usd = await client.officialRates('ecb', { source: 'EUR', target: 'USD' });
+console.log(`ECB ${usd.rate_date}: 1 EUR = ${usd.rate} USD`);
+
+// Which sources exist, and which are behind their publication schedule
+const { sources } = await client.officialSources();
+console.log(sources.map((s) => `${s.code} ${s.latest}${s.stale ? ' (stale)' : ''}`));
+```
+
+Always cite the returned `rate_date` — it is the institution's publication date,
+not the time of your call. Dated tables, history and publication calendars sit
+behind the free key on `/api/v1/central-bank/{bank}/{date}`; see the
+[central bank rates API](https://allratestoday.com/central-bank-rates-api/).
+
 ### Historical Rates by Period
 
 Get historical rates using preset periods — no date math needed:
@@ -470,6 +499,8 @@ console.log({ labels, values });
 | `getRate(from, to, amount?, options?)` | Get a single exchange rate |
 | `getRates(source, target, options?)` | Get rates with full metadata |
 | `getHistoricalRates(source, target, period?, options?)` | Historical rates by preset period (1d/7d/30d/1y) |
+| `officialRates(bank, options?)` | Latest official table (or one pair) published by a central bank / tax authority — **keyless** |
+| `officialSources(options?)` | Every covered official source with latest publication date and freshness — **keyless** |
 
 ---
 

package/dist/index.d.mts

@@ -90,6 +90,60 @@ interface HistoricalRateResponse {
 interface SymbolsResponse {
     symbols: Record<string, string>;
 }
+interface OfficialRateOptions extends RequestOptions {
+    /** Base currency of the pair, e.g. `USD`. Give together with `target` to narrow to one pair. */
+    source?: string;
+    /** Quote currency of the pair, e.g. `EUR`. Give together with `source` to narrow to one pair. */
+    target?: string;
+}
+interface OfficialRateEntry {
+    base: string;
+    quote: string;
+    /** Rate type as the institution labels it, e.g. `reference`, `buy`, `sell`, `mid`. */
+    type: string;
+    value: number;
+}
+interface OfficialRateAttribution {
+    source: string;
+    url: string;
+    terms: string;
+}
+interface OfficialRatesResponse {
+    /** Source code, e.g. `ecb`, `fed`, `hmrc`. */
+    bank: string;
+    /** Publication date of the table (YYYY-MM-DD) — cite this, not today's date. */
+    rate_date: string;
+    /** Full published table. Present when no pair was requested. */
+    rates?: OfficialRateEntry[];
+    /** Pair fields. Present when `source` and `target` were given. */
+    source?: string;
+    target?: string;
+    rate?: number;
+    rate_type?: string;
+    /** True when the pair was cross-computed inside the bank's own table rather than published directly. */
+    derived?: boolean;
+    method?: 'published' | 'inverse';
+    /** True when the institution is behind its own publication schedule. */
+    stale?: boolean;
+    attribution: OfficialRateAttribution;
+    free_key: string;
+}
+interface OfficialSource {
+    /** Pass this as `bank` to `officialRates()`. */
+    code: string;
+    name: string;
+    /** Latest publication date, or null if never ingested. */
+    latest: string | null;
+    stale?: boolean;
+    [extra: string]: unknown;
+}
+interface OfficialSourcesResponse {
+    sources: OfficialSource[];
+    stale_count: number;
+    checked_at: string;
+    docs: string;
+    free_key: string;
+}
 declare class AllRatesTodayError extends Error {
     /** HTTP status code (when available). */
     status?: number;
@@ -166,6 +220,35 @@ declare class AllRatesToday {
      * ```
      */
     symbols(options?: RequestOptions): Promise<SymbolsResponse>;
+    /**
+     * Latest table of OFFICIAL rates published by a central bank or tax
+     * authority (121 central banks + HMRC, US Treasury, Swiss BAZG). These are
+     * the fixed, citable rates for invoicing, tax, customs and accounting — not
+     * live market rates. **No API key needed.**
+     *
+     * ```ts
+     * // Full ECB reference table
+     * 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
+     * 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}`.
+     */
+    officialRates(bank: string, options?: OfficialRateOptions): Promise<OfficialRatesResponse>;
+    /**
+     * Every covered official source with its code, name, latest publication
+     * date and whether it is behind schedule. **No API key needed.**
+     *
+     * ```ts
+     * const { sources } = await client.officialSources();
+     * const behind = sources.filter((s) => s.stale).map((s) => s.code);
+     * ```
+     */
+    officialSources(options?: RequestOptions): Promise<OfficialSourcesResponse>;
     /**
      * Get exchange rate between two currencies.
      *
@@ -215,4 +298,4 @@ declare class AllRatesToday {
     convert(from: string, to: string, amount: number, options?: ConvertOptions): Promise<ConvertResponse>;
 }
 
-export { AllRatesToday, AllRatesTodayError, type AllRatesTodayOptions, type AuthRateResponse, type ConvertOptions, type ConvertResponse, type ForDateOptions, type ForDateResponse, type HistoricalRateResponse, type LatestOptions, type LatestResponse, type RateResponse, type RequestOptions, type SymbolsResponse, type TimeSeriesOptions, type TimeSeriesResponse, AllRatesToday as default };
+export { AllRatesToday, AllRatesTodayError, type AllRatesTodayOptions, type AuthRateResponse, type ConvertOptions, type ConvertResponse, type ForDateOptions, type ForDateResponse, type HistoricalRateResponse, type LatestOptions, type LatestResponse, type OfficialRateAttribution, type OfficialRateEntry, type OfficialRateOptions, type OfficialRatesResponse, type OfficialSource, type OfficialSourcesResponse, type RateResponse, type RequestOptions, type SymbolsResponse, type TimeSeriesOptions, type TimeSeriesResponse, AllRatesToday as default };

package/dist/index.d.ts

@@ -90,6 +90,60 @@ interface HistoricalRateResponse {
 interface SymbolsResponse {
     symbols: Record<string, string>;
 }
+interface OfficialRateOptions extends RequestOptions {
+    /** Base currency of the pair, e.g. `USD`. Give together with `target` to narrow to one pair. */
+    source?: string;
+    /** Quote currency of the pair, e.g. `EUR`. Give together with `source` to narrow to one pair. */
+    target?: string;
+}
+interface OfficialRateEntry {
+    base: string;
+    quote: string;
+    /** Rate type as the institution labels it, e.g. `reference`, `buy`, `sell`, `mid`. */
+    type: string;
+    value: number;
+}
+interface OfficialRateAttribution {
+    source: string;
+    url: string;
+    terms: string;
+}
+interface OfficialRatesResponse {
+    /** Source code, e.g. `ecb`, `fed`, `hmrc`. */
+    bank: string;
+    /** Publication date of the table (YYYY-MM-DD) — cite this, not today's date. */
+    rate_date: string;
+    /** Full published table. Present when no pair was requested. */
+    rates?: OfficialRateEntry[];
+    /** Pair fields. Present when `source` and `target` were given. */
+    source?: string;
+    target?: string;
+    rate?: number;
+    rate_type?: string;
+    /** True when the pair was cross-computed inside the bank's own table rather than published directly. */
+    derived?: boolean;
+    method?: 'published' | 'inverse';
+    /** True when the institution is behind its own publication schedule. */
+    stale?: boolean;
+    attribution: OfficialRateAttribution;
+    free_key: string;
+}
+interface OfficialSource {
+    /** Pass this as `bank` to `officialRates()`. */
+    code: string;
+    name: string;
+    /** Latest publication date, or null if never ingested. */
+    latest: string | null;
+    stale?: boolean;
+    [extra: string]: unknown;
+}
+interface OfficialSourcesResponse {
+    sources: OfficialSource[];
+    stale_count: number;
+    checked_at: string;
+    docs: string;
+    free_key: string;
+}
 declare class AllRatesTodayError extends Error {
     /** HTTP status code (when available). */
     status?: number;
@@ -166,6 +220,35 @@ declare class AllRatesToday {
      * ```
      */
     symbols(options?: RequestOptions): Promise<SymbolsResponse>;
+    /**
+     * Latest table of OFFICIAL rates published by a central bank or tax
+     * authority (121 central banks + HMRC, US Treasury, Swiss BAZG). These are
+     * the fixed, citable rates for invoicing, tax, customs and accounting — not
+     * live market rates. **No API key needed.**
+     *
+     * ```ts
+     * // Full ECB reference table
+     * 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
+     * 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}`.
+     */
+    officialRates(bank: string, options?: OfficialRateOptions): Promise<OfficialRatesResponse>;
+    /**
+     * Every covered official source with its code, name, latest publication
+     * date and whether it is behind schedule. **No API key needed.**
+     *
+     * ```ts
+     * const { sources } = await client.officialSources();
+     * const behind = sources.filter((s) => s.stale).map((s) => s.code);
+     * ```
+     */
+    officialSources(options?: RequestOptions): Promise<OfficialSourcesResponse>;
     /**
      * Get exchange rate between two currencies.
      *
@@ -215,4 +298,4 @@ declare class AllRatesToday {
     convert(from: string, to: string, amount: number, options?: ConvertOptions): Promise<ConvertResponse>;
 }
 
-export { AllRatesToday, AllRatesTodayError, type AllRatesTodayOptions, type AuthRateResponse, type ConvertOptions, type ConvertResponse, type ForDateOptions, type ForDateResponse, type HistoricalRateResponse, type LatestOptions, type LatestResponse, type RateResponse, type RequestOptions, type SymbolsResponse, type TimeSeriesOptions, type TimeSeriesResponse, AllRatesToday as default };
+export { AllRatesToday, AllRatesTodayError, type AllRatesTodayOptions, type AuthRateResponse, type ConvertOptions, type ConvertResponse, type ForDateOptions, type ForDateResponse, type HistoricalRateResponse, type LatestOptions, type LatestResponse, type OfficialRateAttribution, type OfficialRateEntry, type OfficialRateOptions, type OfficialRatesResponse, type OfficialSource, type OfficialSourcesResponse, type RateResponse, type RequestOptions, type SymbolsResponse, type TimeSeriesOptions, type TimeSeriesResponse, AllRatesToday as default };

package/dist/index.js

@@ -225,6 +225,55 @@ var AllRatesToday = class {
     const key = this.resolveKey(options.apiKey);
     return this.request("/api/v1/symbols", {}, key);
   }
+  /**
+   * Latest table of OFFICIAL rates published by a central bank or tax
+   * authority (121 central banks + HMRC, US Treasury, Swiss BAZG). These are
+   * the fixed, citable rates for invoicing, tax, customs and accounting — not
+   * live market rates. **No API key needed.**
+   *
+   * ```ts
+   * // Full ECB reference table
+   * 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
+   * 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}`.
+   */
+  async officialRates(bank, options = {}) {
+    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 params = {};
+    if (options.source && options.target) {
+      params.source = options.source.toUpperCase();
+      params.target = options.target.toUpperCase();
+    }
+    return this.request(
+      `/api/open/central-bank/${encodeURIComponent(code)}`,
+      params,
+      options.apiKey
+    );
+  }
+  /**
+   * Every covered official source with its code, name, latest publication
+   * date and whether it is behind schedule. **No API key needed.**
+   *
+   * ```ts
+   * const { sources } = await client.officialSources();
+   * const behind = sources.filter((s) => s.stale).map((s) => s.code);
+   * ```
+   */
+  async officialSources(options = {}) {
+    return this.request("/api/open/central-banks", {}, options.apiKey);
+  }
   /**
    * Get exchange rate between two currencies.
    *

package/dist/index.mjs

@@ -199,6 +199,55 @@ var AllRatesToday = class {
     const key = this.resolveKey(options.apiKey);
     return this.request("/api/v1/symbols", {}, key);
   }
+  /**
+   * Latest table of OFFICIAL rates published by a central bank or tax
+   * authority (121 central banks + HMRC, US Treasury, Swiss BAZG). These are
+   * the fixed, citable rates for invoicing, tax, customs and accounting — not
+   * live market rates. **No API key needed.**
+   *
+   * ```ts
+   * // Full ECB reference table
+   * 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
+   * 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}`.
+   */
+  async officialRates(bank, options = {}) {
+    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 params = {};
+    if (options.source && options.target) {
+      params.source = options.source.toUpperCase();
+      params.target = options.target.toUpperCase();
+    }
+    return this.request(
+      `/api/open/central-bank/${encodeURIComponent(code)}`,
+      params,
+      options.apiKey
+    );
+  }
+  /**
+   * Every covered official source with its code, name, latest publication
+   * date and whether it is behind schedule. **No API key needed.**
+   *
+   * ```ts
+   * const { sources } = await client.officialSources();
+   * const behind = sources.filter((s) => s.stale).map((s) => s.code);
+   * ```
+   */
+  async officialSources(options = {}) {
+    return this.request("/api/open/central-banks", {}, options.apiKey);
+  }
   /**
    * Get exchange rate between two currencies.
    *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allratestoday/sdk",
-  "version": "1.3.10",
+  "version": "1.4.0",
   "description": "Exchange Rate API — Real-time mid-market currency exchange rates for Node.js and browsers. 160+ currencies, zero dependencies, free tier.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",