@allratestoday/hmrc-exchange-rate 1.1.2 → 1.2.0

package/README.md

@@ -1,65 +1,247 @@
-# HM Revenue & Customs Exchange Rate API client
+# HM Revenue & Customs Exchange Rate API — hmrc-exchange-rate
 
-Official **HM Revenue & Customs** (the United Kingdom) monthly exchange rates in Node.js / TypeScript — 141 currencies against the GBP, with history back to 2021. Zero dependencies, works in Node 18+, Bun, Deno, and edge runtimes (uses global `fetch`).
+[![npm version](https://img.shields.io/npm/v/@allratestoday%2Fhmrc-exchange-rate.svg)](https://www.npmjs.com/package/@allratestoday/hmrc-exchange-rate)
+[![license](https://img.shields.io/npm/l/@allratestoday%2Fhmrc-exchange-rate.svg)](https://github.com/AllRates-Today/hmrc-exchange-rate/blob/main/LICENSE)
+[![zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](https://www.npmjs.com/package/@allratestoday/hmrc-exchange-rate)
+[![TypeScript](https://img.shields.io/badge/TypeScript-types%20included-3178C6.svg)](https://www.typescriptlang.org/)
 
-These are the *published tax authority rates* required for tax filings, customs valuations, audits, and compliant invoicing — not moving market rates. Every response carries the publisher's own publication date.
+**Official HM Revenue & Customs (the United Kingdom) monthly exchange rates for Node.js and TypeScript. The published tax authority rates behind tax filings, customs valuations, audits, and compliant invoicing — not market estimates, but the numbers HM Revenue & Customs itself prints, every month.**
 
-Powered by [AllRatesToday](https://allratestoday.com/tax-authority-rates-api/hmrc/). Get a free API key at [allratestoday.com/register](https://allratestoday.com/register) — no credit card required.
+## 🚀 Why this client?
 
-## Install
+- 🏛️ **Official published rates** — HM Revenue & Customs's own table, with the publisher's own `rate_date` on every response
+- 📅 **History back to 2021** — 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
+
+## 🔑 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 @allratestoday/hmrc-exchange-rate
 ```
 
-## Quick start
+```bash
+yarn add @allratestoday/hmrc-exchange-rate
+```
+
+```bash
+pnpm add @allratestoday/hmrc-exchange-rate
+```
+
+Scoped mirror of [`hmrc-exchange-rate`](https://www.npmjs.com/package/hmrc-exchange-rate) — same code, same versions.
+
+## 🏁 Quick start
 
 ```js
-import { getRate, getLatestRates } from '@allratestoday/hmrc-exchange-rate';
+import { getRate } from '@allratestoday/hmrc-exchange-rate';
 
-// One pair at the official HM Revenue & Customs rate
 const pair = await getRate('GBP', 'USD', { apiKey: 'art_live_...' });
-console.log(pair.rate, pair.rate_date); // e.g. GBP -> USD on the bank's own date
+console.log(pair.rate, pair.rate_date); // the official HM Revenue & Customs rate, on the tax authority'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 tax authority 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 tax authority does not print directly are resolved from its table and flagged (see *Published vs derived rates* below).
+
+```js
+const pair = await getRate('GBP', 'USD', { apiKey: 'art_live_...' });
+```
+
+**Response:**
+
+```javascript
+{
+  bank: 'hmrc',
+  name: 'HM Revenue & Customs',
+  rate_date: '2026-08-01',   // HM Revenue & Customs's own publication date
+  source: 'GBP',
+  target: 'USD',
+  rate: 1.3367,
+  rate_type: 'monthly',
+  derived: false,
+  method: 'published',
+  disclaimer: '…'
+}
+```
+
+### Full published table
+
+Free plan and up. The complete table for the latest publication date.
+
+```js
+import { getLatestRates } from '@allratestoday/hmrc-exchange-rate';
 
-// 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)
+**Response:**
+
+```javascript
+{
+  bank: 'hmrc',
+  name: 'HM Revenue & Customs',
+  rate_date: '2026-08-01',
+  rates: [
+    { "base": "GBP", "quote": "USD", "type": "monthly", "value": 1.3367 },
+    // … the rest of the published table (141 currencies vs GBP)
+  ],
+  disclaimer: '…'
+}
+```
+
+### Table for a date
+
+Paid plans. The official table for any date since 2021 — 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, getHistory } from '@allratestoday/hmrc-exchange-rate';
+import { getRatesForDate } from '@allratestoday/hmrc-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_...' });
+// Optionally narrow to one pair:
+const one = await getRatesForDate('2026-06-30', { apiKey: 'art_live_...', source: 'GBP', target: 'USD' });
+```
+
+**Response:**
+
+```javascript
+{
+  bank: 'hmrc',
+  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 '@allratestoday/hmrc-exchange-rate';
 
-// Daily series for one pair
 const series = await getHistory(
-  { source: 'GBP', target: 'USD', from: '2026-01-01' },
+  { source: 'GBP', target: 'USD', from: '2026-01-01', to: '2026-08-01' },
   { apiKey: 'art_live_...' }
 );
 ```
 
-## Currencies covered
+**Response:**
+
+```javascript
+{
+  bank: 'hmrc',
+  source: 'GBP',
+  target: 'USD',
+  from: '2026-01-01',
+  to: '2026-08-01',
+  count: 152,
+  rates: [
+    // one entry per publication date
+    { date: '2026-08-01', rate: 1.3367, rate_type: 'monthly', 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
 
 HM Revenue & Customs currently publishes rates covering **142 currencies** (as of the latest table):
 
 `AED` · `ALL` · `AMD` · `AOA` · `ARS` · `AUD` · `AWG` · `AZN` · `BAM` · `BBD` · `BDT` · `BHD` · `BIF` · `BMD` · `BND` · `BOB` · `BRL` · `BSD` · `BTN` · `BWP` · `BYN` · `BZD` · `CAD` · `CDF` · `CHF` · `CLP` · `CNY` · `COP` · `CRC` · `CUP` · `CVE` · `CZK` · `DJF` · `DKK` · `DOP` · `DZD` · `EGP` · `ERN` · `ETB` · `EUR` · `FJD` · `GBP` · `GEL` · `GHS` · `GMD` · `GNF` · `GTQ` · `GYD` · `HKD` · `HNL` · `HTG` · `HUF` · `IDR` · `ILS` · `INR` · `IQD` · `ISK` · `JMD` · `JOD` · `JPY` · `KES` · `KGS` · `KHR` · `KMF` · `KRW` · `KWD` · `KYD` · `KZT` · `LAK` · `LBP` · `LKR` · `LRD` · `LSL` · `LYD` · `MAD` · `MDL` · `MGA` · `MKD` · `MMK` · `MNT` · `MOP` · `MRU` · `MUR` · `MVR` · `MWK` · `MXN` · `MYR` · `MZN` · `NGN` · `NIO` · `NOK` · `NPR` · `NZD` · `OMR` · `PAB` · `PEN` · `PGK` · `PHP` · `PKR` · `PLN` · `PYG` · `QAR` · `RON` · `RSD` · `RUB` · `RWF` · `SAR` · `SBD` · `SCR` · `SDG` · `SEK` · `SGD` · `SLE` · `SOS` · `SRD` · `SVC` · `SZL` · `THB` · `TMT` · `TND` · `TOP` · `TRY` · `TTD` · `TWD` · `TZS` · `UAH` · `UGX` · `USD` · `UYU` · `UZS` · `VES` · `VND` · `VUV` · `WST` · `XAF` · `XCD` · `XOF` · `XPF` · `YER` · `ZAR` · `ZMW` · `ZWG`
 
-Pairs the tax authority does not print directly are resolved from this table (see below).
+## ⚖️ Published vs derived rates
+
+If HM Revenue & Customs does not print a pair directly, the API resolves it from the tax authority's own table and says so — official and computed values are never confused:
+
+| `method` | `derived` | Meaning |
+| --- | --- | --- |
+| `published` | `false` | The tax authority printed this pair directly |
+| `inverse` | `true` | Computed as 1 ÷ the published opposite direction |
+| `cross` | `true` | Computed via GBP 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('GBP', '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 HM Revenue & Customs |
+| `429` | Monthly quota exceeded |
+
+## 🔷 TypeScript
+
+Full definitions ship with the package — no `@types` install:
+
+```ts
+import type { LatestRates, PairRate, DatedRates, RateEntry, HistoryQuery, RequestOptions } from '@allratestoday/hmrc-exchange-rate';
+```
+
+## 📦 CommonJS
+
+```javascript
+const { getRate } = require('@allratestoday/hmrc-exchange-rate');
+
+getRate('GBP', 'USD', { apiKey: 'art_live_...' }).then((pair) => console.log(pair.rate));
+```
+
+## 💡 Quota tips
+
+- Rates change once a month — 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.
 
-## Published vs derived rates
+## 📖 Methods reference
 
-If HM Revenue & Customs does not print a pair directly, the API resolves it from the bank's table (inverse, or a cross rate via GBP) and flags it `derived: true` with the `method` — so official and computed values are never confused.
+| Method | Plan | Description |
+| ------ | ---- | ----------- |
+| `getRate(source, target, { apiKey })` | Free | Latest rate for one pair, resolved from the published table |
+| `getLatestRates({ apiKey })` | Free | The tax authority'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 2021 |
 
-## Notes
+## 🔗 Links
 
-- 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 sources: [tax authority rates API](https://allratestoday.com/tax-authority-rates-api/)
+- [HM Revenue & Customs rates page](https://allratestoday.com/tax-authority-rates-api/hmrc/) — live table, publication cadence, FAQ
+- [All tax authority sources](https://allratestoday.com/tax-authority-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/hmrc-exchange-rate)
 
-## License
+## 📜 License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allratestoday/hmrc-exchange-rate",
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "Official HM Revenue & Customs (United Kingdom) monthly exchange rates — 141 currencies vs GBP, history since 2021. Zero-dependency Node.js/TypeScript client.",
   "keywords": [
     "hmrc",