bnb-exchange-rate 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AllRatesToday (https://allratestoday.com)
+
+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,57 @@
+# Bulgarian National Bank Exchange Rate API client
+
+Official **Bulgarian National Bank** (Bulgaria) daily exchange rates in Node.js / TypeScript — ~29 currencies against the EUR, with history back to 2016. Zero dependencies, works in Node 18+, Bun, Deno, and edge runtimes (uses global `fetch`).
+
+These are the *published central bank rates* required for tax filings, customs valuations, audits, and compliant invoicing — not moving market rates. Every response carries the bank's own publication date.
+
+Powered by [AllRatesToday](https://allratestoday.com/central-bank-rates-api/bnb/). Get a free API key at [allratestoday.com/register](https://allratestoday.com/register) — 300 requests/month, no credit card.
+
+## Install
+
+```bash
+npm install bnb-exchange-rate
+```
+
+## Quick start
+
+```js
+import { getRate, getLatestRates } from 'bnb-exchange-rate';
+
+// One pair at the official Bulgarian National Bank rate
+const pair = await getRate('EUR', 'USD', { apiKey: 'art_live_...' });
+console.log(pair.rate, pair.rate_date); // e.g. EUR -> USD on the bank's own date
+
+// The bank's full published table
+const table = await getLatestRates({ apiKey: 'art_live_...' });
+console.log(table.rate_date, table.rates.length);
+```
+
+## Historical data (paid plans)
+
+```js
+import { getRatesForDate, getHistory } from 'bnb-exchange-rate';
+
+// The official table for an invoice date — weekends/holidays return the
+// most recent published date, flagged via published_on_requested_date.
+const day = await getRatesForDate('2026-06-30', { apiKey: 'art_live_...' });
+
+// Daily series for one pair
+const series = await getHistory(
+  { source: 'EUR', target: 'USD', from: '2026-01-01' },
+  { apiKey: 'art_live_...' }
+);
+```
+
+## Published vs derived rates
+
+If Bulgarian National Bank does not print a pair directly, the API resolves it from the bank's table (inverse, or a cross rate via EUR) and flags it `derived: true` with the `method` — so official and computed values are never confused.
+
+## Notes
+
+- Every request counts toward your AllRatesToday monthly quota. Rates change once per business day — cache a day's table locally and a small quota goes a long way.
+- Latest rates are on every plan (including free); historical dates and time series need a [paid plan](https://allratestoday.com/pricing/).
+- Full API reference: [allratestoday.com/docs#central-bank](https://allratestoday.com/docs/#central-bank) · All covered banks: [central bank rates API](https://allratestoday.com/central-bank-rates-api/)
+
+## License
+
+MIT

package/index.cjs

@@ -0,0 +1,47 @@
+'use strict';
+// Bulgarian National Bank exchange rates via the AllRatesToday API.
+const BASE = 'https://allratestoday.com/api/v1/central-bank/bnb';
+const KEY_HINT = 'An apiKey is required — get a free key at https://allratestoday.com/register (300 requests/month, no credit card).';
+
+async function request(path, params, options) {
+  const apiKey = options && options.apiKey;
+  if (!apiKey) throw new Error(KEY_HINT);
+  const url = new URL(BASE + path);
+  for (const [k, v] of Object.entries(params || {})) {
+    if (v !== undefined && v !== null) url.searchParams.set(k, v);
+  }
+  const res = await fetch(url, { headers: { Authorization: 'Bearer ' + apiKey } });
+  let body;
+  try { body = await res.json(); } catch { body = {}; }
+  if (!res.ok) {
+    const err = new Error(body.error || ('Request failed: HTTP ' + res.status));
+    err.status = res.status;
+    err.body = body;
+    throw err;
+  }
+  return body;
+}
+
+/** Latest published table (all plans, including free). */
+async function getLatestRates(options) {
+  return request('/latest', {}, options);
+}
+
+/** Latest rate for one pair, e.g. getRate('EUR', 'USD', { apiKey }). */
+async function getRate(source, target, options) {
+  return request('/latest', { source, target }, options);
+}
+
+/** Published table for a date (YYYY-MM-DD). Paid plans. Weekends/holidays return the most recent published date. */
+async function getRatesForDate(date, options) {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(String(date))) throw new Error('date must be YYYY-MM-DD');
+  return request('/' + date, options && options.source ? { source: options.source, target: options.target } : {}, options);
+}
+
+/** Daily time series. Pass { symbol } or { source, target }, optional from/to (YYYY-MM-DD). Paid plans. */
+async function getHistory(query, options) {
+  const { symbol, source, target, from, to } = query || {};
+  return request('/history', { symbol, source, target, from, to }, options);
+}
+
+module.exports = { getLatestRates, getRate, getRatesForDate, getHistory };

package/index.d.ts

@@ -0,0 +1,52 @@
+export interface RequestOptions {
+  /** AllRatesToday API key — free at https://allratestoday.com/register */
+  apiKey: string;
+}
+
+export interface RateEntry {
+  base: string;
+  quote: string;
+  type: string;
+  value: number;
+}
+
+export interface LatestRates {
+  bank: 'bnb';
+  name: string;
+  rate_date: string;
+  rates: RateEntry[];
+  disclaimer: string;
+}
+
+export interface PairRate {
+  bank: 'bnb';
+  name: string;
+  rate_date: string;
+  source: string;
+  target: string;
+  rate: number;
+  rate_type: string;
+  /** true when the pair was computed (inverse/cross) rather than published directly */
+  derived: boolean;
+  method: 'published' | 'inverse' | 'cross';
+  disclaimer: string;
+}
+
+export interface DatedRates extends Omit<LatestRates, 'rate_date'> {
+  requested_date: string;
+  rate_date: string;
+  published_on_requested_date: boolean;
+}
+
+export interface HistoryQuery {
+  symbol?: string;
+  source?: string;
+  target?: string;
+  from?: string;
+  to?: string;
+}
+
+export declare function getLatestRates(options: RequestOptions): Promise<LatestRates>;
+export declare function getRate(source: string, target: string, options: RequestOptions): Promise<PairRate>;
+export declare function getRatesForDate(date: string, options: RequestOptions & { source?: string; target?: string }): Promise<DatedRates>;
+export declare function getHistory(query: HistoryQuery, options: RequestOptions): Promise<unknown>;

package/index.mjs

@@ -0,0 +1,44 @@
+// Bulgarian National Bank exchange rates via the AllRatesToday API.
+const BASE = 'https://allratestoday.com/api/v1/central-bank/bnb';
+const KEY_HINT = 'An apiKey is required — get a free key at https://allratestoday.com/register (300 requests/month, no credit card).';
+
+async function request(path, params, options) {
+  const apiKey = options && options.apiKey;
+  if (!apiKey) throw new Error(KEY_HINT);
+  const url = new URL(BASE + path);
+  for (const [k, v] of Object.entries(params || {})) {
+    if (v !== undefined && v !== null) url.searchParams.set(k, v);
+  }
+  const res = await fetch(url, { headers: { Authorization: 'Bearer ' + apiKey } });
+  let body;
+  try { body = await res.json(); } catch { body = {}; }
+  if (!res.ok) {
+    const err = new Error(body.error || ('Request failed: HTTP ' + res.status));
+    err.status = res.status;
+    err.body = body;
+    throw err;
+  }
+  return body;
+}
+
+/** Latest published table (all plans, including free). */
+export async function getLatestRates(options) {
+  return request('/latest', {}, options);
+}
+
+/** Latest rate for one pair, e.g. getRate('EUR', 'USD', { apiKey }). */
+export async function getRate(source, target, options) {
+  return request('/latest', { source, target }, options);
+}
+
+/** Published table for a date (YYYY-MM-DD). Paid plans. Weekends/holidays return the most recent published date. */
+export async function getRatesForDate(date, options) {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(String(date))) throw new Error('date must be YYYY-MM-DD');
+  return request('/' + date, options && options.source ? { source: options.source, target: options.target } : {}, options);
+}
+
+/** Daily time series. Pass { symbol } or { source, target }, optional from/to (YYYY-MM-DD). Paid plans. */
+export async function getHistory(query, options) {
+  const { symbol, source, target, from, to } = query || {};
+  return request('/history', { symbol, source, target, from, to }, options);
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "bnb-exchange-rate",
+  "version": "1.0.1",
+  "description": "Official Bulgarian National Bank (Bulgaria) daily exchange rates — ~29 currencies vs EUR, history since 2016. Zero-dependency Node.js/TypeScript client.",
+  "keywords": [
+    "bnb",
+    "bulgarian",
+    "national",
+    "bank",
+    "exchange-rate",
+    "exchange-rates",
+    "currency",
+    "forex",
+    "fx",
+    "eur",
+    "central-bank",
+    "official-rates",
+    "bulgaria",
+    "api",
+    "typescript"
+  ],
+  "homepage": "https://allratestoday.com/central-bank-rates-api/bnb/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AllRates-Today/bnb-exchange-rate.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AllRates-Today/bnb-exchange-rate/issues"
+  },
+  "license": "MIT",
+  "author": "AllRatesToday <hello@allratestoday.com> (https://allratestoday.com)",
+  "type": "module",
+  "main": "./index.cjs",
+  "module": "./index.mjs",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.mjs",
+      "require": "./index.cjs"
+    }
+  },
+  "files": [
+    "index.mjs",
+    "index.cjs",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false
+}