bna-exchange-rate 1.3.0 → 1.3.3

package/README.md

@@ -1,4 +1,4 @@
-# National Bank of Angola Exchange Rate API — bna-exchange-rate
+# National Bank of Angola Exchange Rates 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)
@@ -16,7 +16,22 @@
 - 🔷 **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.
+> **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 mid-market rate 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.
+
+## ⚡ Try it without a key
+
+The latest National Bank of Angola table is also served keyless, CORS-open and edge-cached, for evaluation, embeds and AI agents:
+
+```bash
+curl "https://allratestoday.com/api/open/central-bank/bna?source=USD&target=AOA"
+```
+
+```js
+const r = await fetch('https://allratestoday.com/api/open/central-bank/bna').then((x) => x.json());
+console.log(r.rate_date, r.rates.length); // the central bank's latest published table, no key
+```
+
+The open endpoint serves the *latest* table only and asks for a visible attribution link. The client below uses the keyed API, which adds point-in-time tables, history, and CSV/XML/Excel output.
 
 ## 🔑 Get your API key
 
@@ -36,7 +51,7 @@ yarn add bna-exchange-rate
 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.
+Requires Node 18+ (global `fetch`); also runs on Bun, Deno and edge runtimes. 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
 
@@ -70,14 +85,14 @@ const pair = await getRate('USD', 'AOA', { apiKey: 'art_live_...' });
 {
   bank: 'bna',
   name: 'National Bank of Angola',
-  rate_date: '2026-09-09',   // National Bank of Angola's own publication date
+  rate_date: '2026-09-25',   // National Bank of Angola's own publication date
   source: 'USD',
   target: 'AOA',
-  rate: 912.843,
+  rate: 913,
   rate_type: 'reference',
   derived: false,
   method: 'published',
-  disclaimer: '…'
+  disclaimer: 'Official rates as published by the named central bank. On weekends/holidays the most recent published rate_date is returned.'
 }
 ```
 
@@ -98,11 +113,11 @@ console.log(table.rate_date, table.rates.length);
 {
   bank: 'bna',
   name: 'National Bank of Angola',
-  rate_date: '2026-09-09',
+  rate_date: '2026-09-25',
   rates: [
-    { "base": "USD", "quote": "AOA", "type": "reference", "value": 912.843 },
-    { "base": "USD", "quote": "AOA", "type": "sell", "value": 912.843 },
-    { "base": "USD", "quote": "AOA", "type": "buy", "value": 912.843 },
+    { "base": "USD", "quote": "AOA", "type": "reference", "value": 913 },
+    { "base": "USD", "quote": "AOA", "type": "sell", "value": 913 },
+    { "base": "USD", "quote": "AOA", "type": "buy", "value": 913 },
     // … the rest of the published table (70 currencies vs AOA)
   ],
   disclaimer: '…'
@@ -142,7 +157,7 @@ Paid plans. One resolved rate per publication date — ready for charting, reval
 import { getHistory } from 'bna-exchange-rate';
 
 const series = await getHistory(
-  { source: 'USD', target: 'AOA', from: '2026-01-01', to: '2026-09-09' },
+  { source: 'USD', target: 'AOA', from: '2026-01-01', to: '2026-09-25' },
   { apiKey: 'art_live_...' }
 );
 ```
@@ -155,11 +170,11 @@ const series = await getHistory(
   source: 'USD',
   target: 'AOA',
   from: '2026-01-01',
-  to: '2026-09-09',
+  to: '2026-09-25',
   count: 152,
   rates: [
     // one entry per publication date
-    { date: '2026-09-09', rate: 912.843, rate_type: 'reference', derived: false, method: 'published' },
+    { date: '2026-09-25', rate: 913, rate_type: 'reference', derived: false, method: 'published' },
     // …
   ],
   disclaimer: '…'
@@ -176,6 +191,40 @@ National Bank of Angola currently publishes rates covering **70 currencies** aga
 
 🇦🇪 `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`
 
+## 🏛️ Source
+
+The National Bank of Angola publishes daily reference kwanza rates — mid, buying and selling — for some 60 currencies. As the central bank of one of Africa's largest oil exporters, its reference rate anchors import pricing and repatriation accounting, with history reaching the 1999 kwanza reform.
+
+- Publisher's own page: [Taxas de câmbio](https://www.bna.ao/#/pt/mercados) · [www.bna.ao](https://www.bna.ao)
+- Publication: every business day; the exact schedule, freshness status and any current delay are on the [National Bank of Angola rates page](https://allratestoday.com/central-bank-rates-api/bna/)
+- Values are stored unmodified, with the publisher's own `rate_date` on every row — see the [methodology](https://allratestoday.com/official-rates-methodology/)
+
+## 🧭 Reading the numbers
+
+- `value` is always **quote currency per 1 unit of base currency** (`base: "EUR", quote: "USD", value: 1.15` means 1 EUR = 1.15 USD).
+- National Bank of Angola quotes **AOA per 1 unit of foreign currency** (e.g. `base: "USD", quote: "AOA"` means AOA per one US dollar).
+- Need the other way round? Ask `getRate(target, source)` and the API inverts or crosses for you, flagged `derived: true` — never divide a published rate yourself in a compliance workflow.
+- Precious-metal codes (`XAU`, `XAG`, `XPT`, `XPD`) are quoted **per troy ounce**.
+- `rate_type` tells you which of the central bank's series a row belongs to (`reference` here); some publishers print buy/sell or several fixings for the same pair.
+
+## 🧩 ERP & accounting systems
+
+Loading the official National Bank of Angola rate into an accounting system is a supported workflow, not a hack. Step-by-step guides with the direction each system expects:
+
+- [Dynamics 365 Business Central](https://allratestoday.com/docs/integrations/business-central/) — built-in Currency Exchange Rate Service, no code
+- [Xero](https://allratestoday.com/docs/integrations/xero/) · [QuickBooks Online](https://allratestoday.com/docs/integrations/quickbooks/) · [SAP S/4HANA and ECC](https://allratestoday.com/docs/integrations/sap/) · [Odoo](https://allratestoday.com/docs/integrations/odoo/)
+
+The same keyed endpoints return `?format=csv`, `?format=xml` and `?format=xlsx`, and accept the key as `?api_key=` on the URL for importers that cannot send headers:
+
+```bash
+curl "https://allratestoday.com/api/v1/central-bank/bna/latest?format=xml&api_key=art_live_..."
+```
+
+## 🤖 AI agents
+
+- MCP server: `npx -y @allratestoday/central-bank-mcp` (stdio) or the hosted endpoint `https://allratestoday.com/api/mcp` — tools for official rates, history, cross-bank comparison and publication calendars
+- Machine-readable site guide: [llms.txt](https://allratestoday.com/llms.txt) · [for-ai-agents](https://allratestoday.com/for-ai-agents/)
+
 ## ⚖️ 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:
@@ -250,7 +299,8 @@ Need the whole archive rather than an API call? The same published tables are mi
 
 - [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/)
+- [Package docs on the site](https://allratestoday.com/docs/sdk/bna-exchange-rate/) · [ERP integration guides](https://allratestoday.com/docs/integrations/)
+- [API documentation](https://allratestoday.com/docs/#central-bank) · [Interactive reference](https://allratestoday.com/api-reference/) · [Methodology](https://allratestoday.com/official-rates-methodology/)
 - [Register (free)](https://allratestoday.com/register) · [Pricing](https://allratestoday.com/pricing/)
 - [GitHub](https://github.com/AllRates-Today/bna-exchange-rate)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bna-exchange-rate",
-  "version": "1.3.0",
+  "version": "1.3.3",
   "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",