@allratestoday/sama-exchange-rate 1.3.0 → 1.3.3

package/README.md

@@ -1,4 +1,4 @@
-# Saudi Central Bank (SAMA) Exchange Rate API — sama-exchange-rate
+# Saudi Central Bank (SAMA) Exchange Rates API — sama-exchange-rate
 
 [![npm version](https://img.shields.io/npm/v/@allratestoday%2Fsama-exchange-rate.svg)](https://www.npmjs.com/package/@allratestoday/sama-exchange-rate)
 [![license](https://img.shields.io/npm/l/@allratestoday%2Fsama-exchange-rate.svg)](https://github.com/AllRates-Today/sama-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 Saudi Central Bank (SAMA) 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 Saudi Central Bank (SAMA) 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 Saudi Central Bank (SAMA) 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/sama?source=EUR&target=SAR"
+```
+
+```js
+const r = await fetch('https://allratestoday.com/api/open/central-bank/sama').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 @allratestoday/sama-exchange-rate
 pnpm add @allratestoday/sama-exchange-rate
 ```
 
-Scoped mirror of [`sama-exchange-rate`](https://www.npmjs.com/package/sama-exchange-rate) — same code, same versions.
+Requires Node 18+ (global `fetch`); also runs on Bun, Deno and edge runtimes. Scoped mirror of [`sama-exchange-rate`](https://www.npmjs.com/package/sama-exchange-rate) — same code, same versions.
 
 ## 🏁 Quick start
 
@@ -77,7 +92,7 @@ const pair = await getRate('EUR', 'SAR', { apiKey: 'art_live_...' });
   rate_type: 'close',
   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.'
 }
 ```
 
@@ -175,6 +190,39 @@ Saudi Central Bank (SAMA) currently publishes rates covering **12 currencies** a
 
 🇦🇺 `AUD` · 🇧🇷 `BRL` · 🇨🇭 `CHF` · 🇨🇳 `CNY` · 🇪🇺 `EUR` · 🇬🇧 `GBP` · 🇮🇳 `INR` · 🇯🇵 `JPY` · 🇰🇷 `KRW` · 🇹🇭 `THB` · 🇹🇷 `TRY` · 🇺🇸 `USD`
 
+## 🏛️ Source
+
+The Saudi Central Bank (SAMA) publishes riyal exchange rates monthly — period averages and end-of-period values for 12 currencies — with the riyal itself pegged to the US dollar at 3.75 since 1986. SAMA offers no machine-readable feed of its own, so this series is sourced from the KAPSARC open-data mirror of SAMA’s table and typically trails the calendar by about two months.
+
+- Publisher's own page: [Exchange rates — KAPSARC open-data mirror](https://datasource.kapsarc.org/explore/dataset/exchange-rate/) · [www.sama.gov.sa](https://www.sama.gov.sa)
+- Publication: every month; the exact schedule, freshness status and any current delay are on the [Saudi Central Bank (SAMA) rates page](https://allratestoday.com/central-bank-rates-api/sama/)
+- 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).
+- Saudi Central Bank (SAMA) quotes **SAR per 1 unit of foreign currency** (e.g. `base: "USD", quote: "SAR"` means SAR 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.
+- `rate_type` tells you which of the central bank's series a row belongs to (`close` here); some publishers print buy/sell or several fixings for the same pair.
+
+## 🧩 ERP & accounting systems
+
+Loading the official Saudi Central Bank (SAMA) 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/sama/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 Saudi Central Bank (SAMA) 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:
@@ -249,7 +297,8 @@ Need the whole archive rather than an API call? The same published tables are mi
 
 - [Saudi Central Bank (SAMA) rates page](https://allratestoday.com/central-bank-rates-api/sama/) — 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/sama-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/sama-exchange-rate)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allratestoday/sama-exchange-rate",
-  "version": "1.3.0",
+  "version": "1.3.3",
   "description": "Official Saudi Central Bank (SAMA) (Saudi Arabia) monthly exchange rates — 12 currencies vs SAR, history since 2009. Zero-dependency Node.js/TypeScript client.",
   "keywords": [
     "sama",