bna-exchange-rate 1.2.7

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,251 @@
+# National Bank of Angola Exchange Rate API — bna-exchange-rate
+
+[![npm version](https://img.shields.io/npm/v/bna-exchange-rate.svg)](https://www.npmjs.com/package/bna-exchange-rate)
+[![license](https://img.shields.io/npm/l/bna-exchange-rate.svg)](https://github.com/AllRates-Today/bna-exchange-rate/blob/main/LICENSE)
+[![zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](https://www.npmjs.com/package/bna-exchange-rate)
+[![TypeScript](https://img.shields.io/badge/TypeScript-types%20included-3178C6.svg)](https://www.typescriptlang.org/)
+
+**Official National Bank of Angola (Angola) daily exchange rates for Node.js and TypeScript. The published central bank rates behind tax filings, customs valuations, audits, and compliant invoicing — not market estimates, but the numbers National Bank of Angola itself prints, every business day.**
+
+## 🚀 Why this client?
+
+- 🏛️ **Official published rates** — National Bank of Angola's own table, with the publisher's own `rate_date` on every response
+- 📅 **History back to 1999** — point-in-time tables and daily series for any past date
+- 🔀 **Published vs derived, always flagged** — computed inverse/cross pairs carry `derived: true`, never mixed with official prints
+- ⚡ **Zero dependencies** — pure ESM + CJS over global `fetch`; Node 18+, Bun, Deno, and edge runtimes
+- 🔷 **Type-safe** — full TypeScript definitions shipped with the package
+- 🧾 **Compliance-grade metadata** — `rate_type`, publication date, and source disclaimer on every response
+
+> **Official rate, not mid-market:** every value here is a number National Bank of Angola itself published, fixed once printed and carrying the central bank's own `rate_date` — what filings and audits require. Need the live interbank midpoint for pricing or display instead? Use the [mid-market API](https://allratestoday.com/docs/) or [`@allratestoday/sdk`](https://www.npmjs.com/package/@allratestoday/sdk). The two can diverge by several percent.
+
+## 🔑 Get your API key
+
+Get a free API key at [allratestoday.com/register](https://allratestoday.com/register) — no credit card required. Latest rates are on every plan, including free.
+
+## 📦 Installation
+
+```bash
+npm install bna-exchange-rate
+```
+
+```bash
+yarn add bna-exchange-rate
+```
+
+```bash
+pnpm add bna-exchange-rate
+```
+
+Also published under the org scope as [`@allratestoday/bna-exchange-rate`](https://www.npmjs.com/package/@allratestoday/bna-exchange-rate) — same code, same versions.
+
+## 🏁 Quick start
+
+```js
+import { getRate } from 'bna-exchange-rate';
+
+const pair = await getRate('USD', 'AOA', { apiKey: 'art_live_...' });
+console.log(pair.rate, pair.rate_date); // the official National Bank of Angola rate, on the central bank's own date
+```
+
+## 📚 API reference
+
+- [Latest pair rate](#latest-pair-rate) — one pair from the latest published table
+- [Full published table](#full-published-table) — everything the central bank printed, in one call
+- [Table for a date](#table-for-a-date) — the official table for an invoice or filing date
+- [Daily time series](#daily-time-series) — one pair across a date range
+
+---
+
+### Latest pair rate
+
+Free plan and up. Pairs the central bank does not print directly are resolved from its table and flagged (see *Published vs derived rates* below).
+
+```js
+const pair = await getRate('USD', 'AOA', { apiKey: 'art_live_...' });
+```
+
+**Response:**
+
+```javascript
+{
+  bank: 'bna',
+  name: 'National Bank of Angola',
+  rate_date: '2026-08-21',   // National Bank of Angola's own publication date
+  source: 'USD',
+  target: 'AOA',
+  rate: 912.799,
+  rate_type: 'reference',
+  derived: false,
+  method: 'published',
+  disclaimer: '…'
+}
+```
+
+### Full published table
+
+Free plan and up. The complete table for the latest publication date.
+
+```js
+import { getLatestRates } from 'bna-exchange-rate';
+
+const table = await getLatestRates({ apiKey: 'art_live_...' });
+console.log(table.rate_date, table.rates.length);
+```
+
+**Response:**
+
+```javascript
+{
+  bank: 'bna',
+  name: 'National Bank of Angola',
+  rate_date: '2026-08-21',
+  rates: [
+    { "base": "USD", "quote": "AOA", "type": "reference", "value": 912.799 },
+    { "base": "USD", "quote": "AOA", "type": "sell", "value": 912.799 },
+    { "base": "USD", "quote": "AOA", "type": "buy", "value": 912.799 },
+    // … the rest of the published table (70 currencies vs AOA)
+  ],
+  disclaimer: '…'
+}
+```
+
+### Table for a date
+
+Paid plans. The official table for any date since 1999 — weekends and holidays return the most recent published date, flagged via `published_on_requested_date`, which is exactly the in-force rate a filing needs.
+
+```js
+import { getRatesForDate } from 'bna-exchange-rate';
+
+const day = await getRatesForDate('2026-06-30', { apiKey: 'art_live_...' });
+// Optionally narrow to one pair:
+const one = await getRatesForDate('2026-06-30', { apiKey: 'art_live_...', source: 'USD', target: 'AOA' });
+```
+
+**Response:**
+
+```javascript
+{
+  bank: 'bna',
+  requested_date: '2026-06-30',
+  rate_date: '2026-06-30',                // the date actually published
+  published_on_requested_date: true,      // false when a weekend/holiday fell back
+  rates: [ /* the full table for that date */ ],
+  disclaimer: '…'
+}
+```
+
+### Daily time series
+
+Paid plans. One resolved rate per publication date — ready for charting, revaluation runs, or audit workpapers.
+
+```js
+import { getHistory } from 'bna-exchange-rate';
+
+const series = await getHistory(
+  { source: 'USD', target: 'AOA', from: '2026-01-01', to: '2026-08-21' },
+  { apiKey: 'art_live_...' }
+);
+```
+
+**Response:**
+
+```javascript
+{
+  bank: 'bna',
+  source: 'USD',
+  target: 'AOA',
+  from: '2026-01-01',
+  to: '2026-08-21',
+  count: 152,
+  rates: [
+    // one entry per publication date
+    { date: '2026-08-21', rate: 912.799, rate_type: 'reference', derived: false, method: 'published' },
+    // …
+  ],
+  disclaimer: '…'
+}
+```
+
+Pass `{ symbol: 'USD' }` instead of `source`/`target` to get the raw published rows for one currency (all rate types, no pair resolution).
+
+---
+
+## 🗺️ Currencies covered
+
+National Bank of Angola currently publishes rates covering **70 currencies** against the AOA (as of the latest table):
+
+🇦🇪 `AED` · 🇦🇱 `ALL` · 🇦🇷 `ARS` · 🇦🇺 `AUD` · 🇧🇬 `BGN` · 🇧🇲 `BMD` · 🇧🇴 `BOB` · 🇧🇷 `BRL` · 🇧🇸 `BSD` · 🇧🇼 `BWP` · 🇨🇦 `CAD` · 🇨🇩 `CDF` · 🇨🇭 `CHF` · 🇨🇳 `CNY` · 🇨🇷 `CRC` · 🇨🇺 `CUP` · 🇨🇻 `CVE` · 🇨🇿 `CZK` · 🇩🇰 `DKK` · 🇪🇪 `EEK` · 🇪🇬 `EGP` · 🇪🇹 `ETB` · 🇪🇺 `EUR` · 🇬🇧 `GBP` · 🇭🇰 `HKD` · 🇭🇷 `HRK` · 🇭🇺 `HUF` · 🇮🇩 `IDR` · 🇮🇱 `ILS` · 🇮🇳 `INR` · 🇮🇶 `IQD` · 🇯🇲 `JMD` · 🇯🇵 `JPY` · 🇰🇪 `KES` · 🇰🇷 `KRW` · 🇰🇼 `KWD` · 🇰🇿 `KZT` · 🇱🇧 `LBP` · 🇱🇰 `LKR` · 🇱🇸 `LSL` · 🇲🇦 `MAD` · 🇲🇽 `MXN` · 🇲🇾 `MYR` · 🇲🇿 `MZN` · 🇳🇦 `NAD` · 🇳🇬 `NGN` · 🇳🇴 `NOK` · 🇳🇿 `NZD` · 🇵🇪 `PEN` · 🇵🇰 `PKR` · 🇵🇱 `PLN` · 🇶🇦 `QAR` · 🇷🇴 `RON` · 🇷🇺 `RUB` · 🇸🇦 `SAR` · 🇸🇪 `SEK` · 🇸🇬 `SGD` · 🇸🇹 `STD` · 🇹🇭 `THB` · 🇹🇹 `TTD` · 🇹🇼 `TWD` · 🇹🇿 `TZS` · 🇺🇦 `UAH` · 🇺🇸 `USD` · 🇻🇪 `VEF` · 🇻🇳 `VND` · `XAF` · `XAU` · 🇿🇦 `ZAR` · 🇿🇲 `ZMK`
+
+## ⚖️ Published vs derived rates
+
+If National Bank of Angola does not print a pair directly, the API resolves it from the central bank's own table and says so — official and computed values are never confused:
+
+| `method` | `derived` | Meaning |
+| --- | --- | --- |
+| `published` | `false` | The central bank printed this pair directly |
+| `inverse` | `true` | Computed as 1 ÷ the published opposite direction |
+| `cross` | `true` | Computed via AOA from two published rates |
+
+## 🛡️ Error handling
+
+Errors are thrown as `Error` with `status` (HTTP code) and `body` (the API's JSON error) attached:
+
+```js
+try {
+  const pair = await getRate('USD', 'XXX', { apiKey: 'art_live_...' });
+} catch (err) {
+  console.log(err.message); // human-readable reason
+  console.log(err.status);  // e.g. 404
+}
+```
+
+| Status | Meaning |
+| ------ | ------- |
+| — | Missing `apiKey` (thrown before any request) |
+| `400` | Malformed date or parameters |
+| `401` | Invalid API key |
+| `403` | Endpoint needs a [paid plan](https://allratestoday.com/pricing/) (historical dates & series) |
+| `404` | Pair or date range not covered by National Bank of Angola |
+| `429` | Monthly quota exceeded |
+
+## 🔷 TypeScript
+
+Full definitions ship with the package — no `@types` install:
+
+```ts
+import type { LatestRates, PairRate, DatedRates, RateEntry, HistoryQuery, RequestOptions } from 'bna-exchange-rate';
+```
+
+## 📦 CommonJS
+
+```javascript
+const { getRate } = require('bna-exchange-rate');
+
+getRate('USD', 'AOA', { apiKey: 'art_live_...' }).then((pair) => console.log(pair.rate));
+```
+
+## 💡 Quota tips
+
+- Rates change once per business day — cache the published table locally and a small monthly quota goes a long way.
+- Every request counts toward your AllRatesToday quota, shared across all AllRatesToday endpoints on your key.
+
+## 📖 Methods reference
+
+| Method | Plan | Description |
+| ------ | ---- | ----------- |
+| `getRate(source, target, { apiKey })` | Free | Latest rate for one pair, resolved from the published table |
+| `getLatestRates({ apiKey })` | Free | The central bank's full latest published table |
+| `getRatesForDate(date, { apiKey, source?, target? })` | Paid | The official table (or one pair) for a YYYY-MM-DD date |
+| `getHistory({ symbol \| source+target, from?, to? }, { apiKey })` | Paid | Daily series since 1999 |
+
+## 🔗 Links
+
+- [National Bank of Angola rates page](https://allratestoday.com/central-bank-rates-api/bna/) — live table, publication cadence, FAQ
+- [All central bank sources](https://allratestoday.com/central-bank-rates-api/)
+- [API documentation](https://allratestoday.com/docs/#central-bank) · [Interactive reference](https://allratestoday.com/api-reference/)
+- [Register (free)](https://allratestoday.com/register) · [Pricing](https://allratestoday.com/pricing/)
+- [GitHub](https://github.com/AllRates-Today/bna-exchange-rate)
+
+## 📜 License
+
+MIT

package/index.cjs

@@ -0,0 +1,47 @@
+'use strict';
+// National Bank of Angola exchange rates via the AllRatesToday API.
+const BASE = 'https://allratestoday.com/api/v1/central-bank/bna';
+const KEY_HINT = 'An apiKey is required — get a free key at https://allratestoday.com/register (no credit card required).';
+
+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('USD', 'AOA', { 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: 'bna';
+  name: string;
+  rate_date: string;
+  rates: RateEntry[];
+  disclaimer: string;
+}
+
+export interface PairRate {
+  bank: 'bna';
+  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 @@
+// National Bank of Angola exchange rates via the AllRatesToday API.
+const BASE = 'https://allratestoday.com/api/v1/central-bank/bna';
+const KEY_HINT = 'An apiKey is required — get a free key at https://allratestoday.com/register (no credit card required).';
+
+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('USD', 'AOA', { 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,55 @@
+{
+  "name": "bna-exchange-rate",
+  "version": "1.2.7",
+  "description": "Official National Bank of Angola (Angola) daily exchange rates — 70 currencies vs AOA, history since 1999. Zero-dependency Node.js/TypeScript client.",
+  "keywords": [
+    "bna",
+    "national",
+    "bank",
+    "of",
+    "angola",
+    "exchange-rate",
+    "exchange-rates",
+    "currency",
+    "forex",
+    "fx",
+    "aoa",
+    "central-bank",
+    "official-rates",
+    "angola",
+    "api",
+    "typescript"
+  ],
+  "homepage": "https://allratestoday.com/central-bank-rates-api/bna/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AllRates-Today/bna-exchange-rate.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AllRates-Today/bna-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
+}