@allratestoday/sama-exchange-rate 1.3.19 → 1.3.24

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +81 -60
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -7,7 +7,7 @@
7
7
  [![EUR/SAR today](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fallratestoday.com%2Fapi%2Fopen%2Fcentral-bank%2Fsama%3Fsource%3DEUR%26target%3DSAR&query=%24.rate&label=EUR%2FSAR%20published%20by%20Saudi%20Central%20Bank%20(SAMA)&color=0A7E8C&cacheSeconds=3600)](https://allratestoday.com/central-bank-rates-api/sama/)
8
8
  [![rate date](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fallratestoday.com%2Fapi%2Fopen%2Fcentral-bank%2Fsama%3Fsource%3DEUR%26target%3DSAR&query=%24.rate_date&label=rate%20date&color=555&cacheSeconds=3600)](https://allratestoday.com/central-bank-rates-api/sama/)
9
9
 
10
- **Official Saudi Central Bank (SAMA) (Saudi Arabia) monthly 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 Saudi Central Bank (SAMA) itself prints, every month.**
10
+ **Official Saudi Central Bank (SAMA) (Saudi Arabia) 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 Saudi Central Bank (SAMA) itself prints, every business day.**
11
11
 
12
12
  ## 🚀 Why this client?
13
13
 
@@ -24,61 +24,82 @@
24
24
 
25
25
  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.
26
26
 
27
- ## ⚡ Try it without a key
28
-
29
- The latest Saudi Central Bank (SAMA) table is also served keyless, CORS-open and edge-cached, for evaluation, embeds and AI agents:
30
-
31
- ```bash
32
- curl "https://allratestoday.com/api/open/central-bank/sama?source=EUR&target=SAR"
33
- ```
34
-
35
- ```js
36
- const r = await fetch('https://allratestoday.com/api/open/central-bank/sama').then((x) => x.json());
37
- console.log(r.rate_date, r.rates.length); // the central bank's latest published table, no key
38
- ```
39
-
40
- The open endpoint serves the *latest* table only (JSON by default; add `?format=csv`, `xml` or `xlsx` for a file) and is free to use with a visible, followable link where the rates are shown: `<a href="https://allratestoday.com">Exchange rates by AllRatesToday</a>` (terms: <https://allratestoday.com/terms/#attribution>). The client below uses the keyed API, which adds point-in-time tables and history; with a key the link is appreciated, not required.
41
-
42
27
  ## 📈 Latest published table
43
28
 
44
29
  [![Latest Saudi Central Bank (SAMA) table](https://allratestoday.com/api/open/central-bank/sama/table.svg)](https://allratestoday.com/central-bank-rates-api/sama/)
45
30
 
46
- The image is rendered live from the keyless endpoint above, so it follows the central bank's publications on npm and on GitHub alike without a new release. The same table as text is folded below for search and copy-paste: on GitHub [a daily Action](.github/workflows/daily-table.yml) refreshes it whenever the central bank publishes a new table; on npm it is as of the package's publish date.
31
+ The image is rendered live from the keyless endpoint, so it follows the central bank's publications on npm and on GitHub alike without a new release. The same table as text is folded below for search and copy-paste: on GitHub [a daily Action](.github/workflows/daily-table.yml) refreshes it whenever the central bank publishes a new table; on npm it is as of the package's publish date.
47
32
 
48
33
  <!-- daily-table:start -->
49
34
  <details>
50
- <summary>Table as text: published 2026-07-31 by Saudi Central Bank (SAMA) (the API currently flags this table as stale) — 24 rates. Updated 2026-10-27.</summary>
35
+ <summary>Table as text: published 2026-10-29 by Saudi Central Bank (SAMA) — 66 rates, first 60 shown. Updated 2026-10-30.</summary>
51
36
 
52
37
  | Base | Quote | Type | Rate |
53
38
  | --- | --- | --- | ---: |
54
- | AUD | SAR | close | 2.6305805 |
55
- | AUD | SAR | monthly_average | 2.6118306 |
56
- | BRL | SAR | close | 0.73916558 |
57
- | BRL | SAR | monthly_average | 0.73401057 |
58
- | CHF | SAR | close | 4.6253694 |
59
- | CHF | SAR | monthly_average | 4.6229663 |
60
- | CNY | SAR | close | 0.55461841 |
61
- | CNY | SAR | monthly_average | 0.55337878 |
62
- | EUR | SAR | close | 4.2976014 |
63
- | EUR | SAR | monthly_average | 4.2804897 |
64
- | GBP | SAR | close | 5.030462 |
65
- | GBP | SAR | monthly_average | 5.0133182 |
66
- | INR | SAR | close | 0.039235708 |
67
- | INR | SAR | monthly_average | 0.039136208 |
68
- | JPY | SAR | close | 0.023293968 |
69
- | JPY | SAR | monthly_average | 0.023059174 |
70
- | KRW | SAR | close | 0.0025965805 |
71
- | KRW | SAR | monthly_average | 0.0025093839 |
72
- | THB | SAR | close | 0.11198406 |
73
- | THB | SAR | monthly_average | 0.11192007 |
74
- | TRY | SAR | close | 0.078847735 |
75
- | TRY | SAR | monthly_average | 0.079760374 |
76
- | USD | SAR | close | 3.75 |
77
- | USD | SAR | monthly_average | 3.75 |
39
+ | AED | SAR | reference | 1.02094 |
40
+ | AFN | SAR | reference | 0.0577 |
41
+ | ALL | SAR | reference | 0.04597 |
42
+ | ARS | SAR | reference | 0.00243 |
43
+ | AUD | SAR | reference | 2.63868 |
44
+ | BAM | SAR | reference | 2.13583 |
45
+ | BDT | SAR | reference | 0.0303 |
46
+ | BGN | SAR | reference | 2.13583 |
47
+ | BHD | SAR | reference | 9.9364 |
48
+ | BND | SAR | reference | 2.9235 |
49
+ | BRL | SAR | reference | 0.69756 |
50
+ | CAD | SAR | reference | 2.67141 |
51
+ | CHF | SAR | reference | 4.51725 |
52
+ | CLP | SAR | reference | 0.0038 |
53
+ | CNY | SAR | reference | 0.56248 |
54
+ | COP | SAR | reference | 0.00118 |
55
+ | CUP | SAR | reference | 0.15625 |
56
+ | CZK | SAR | reference | 0.17141 |
57
+ | DJF | SAR | reference | 0.02109 |
58
+ | DKK | SAR | reference | 0.5589 |
59
+ | DZD | SAR | reference | 0.02771 |
60
+ | EGP | SAR | reference | 0.06685 |
61
+ | ETB | SAR | reference | 0.02303 |
62
+ | EUR | SAR | reference | 4.17731 |
63
+ | GBP | SAR | reference | 4.98768 |
64
+ | HKD | SAR | reference | 0.47799 |
65
+ | HUF | SAR | reference | 0.01137 |
66
+ | INR | SAR | reference | 0.03937 |
67
+ | ISK | SAR | reference | 0.03075 |
68
+ | JOD | SAR | reference | 5.28913 |
69
+ | JPY | SAR | reference | 0.02369 |
70
+ | KES | SAR | reference | 0.02884 |
71
+ | KRW | SAR | reference | 0.0028 |
72
+ | KWD | SAR | reference | 12.054 |
73
+ | LKR | SAR | reference | 0.01127 |
74
+ | LYD | SAR | reference | 0.5835 |
75
+ | MAD | SAR | reference | 0.38054 |
76
+ | MMK | SAR | reference | 0.00178 |
77
+ | MUR | SAR | reference | 0.07884 |
78
+ | MXN | SAR | reference | 0.20079 |
79
+ | MYR | SAR | reference | 0.91979 |
80
+ | NGN | SAR | reference | 0.00278 |
81
+ | NOK | SAR | reference | 0.4045 |
82
+ | NZD | SAR | reference | 2.10768 |
83
+ | OMR | SAR | reference | 9.74025 |
84
+ | PHP | SAR | reference | 0.05855 |
85
+ | PKR | SAR | reference | 0.01353 |
86
+ | PLN | SAR | reference | 0.94885 |
87
+ | QAR | SAR | reference | 1.02993 |
88
+ | RON | SAR | reference | 0.78077 |
89
+ | RUB | SAR | reference | 0.04648 |
90
+ | SEK | SAR | reference | 0.37787 |
91
+ | SGD | SAR | reference | 2.92329 |
92
+ | SOS | SAR | reference | 0.00659 |
93
+ | THB | SAR | reference | 0.11102 |
94
+ | TJS | SAR | reference | 0.40725 |
95
+ | TND | SAR | reference | 1.25058 |
96
+ | TRY | SAR | reference | 0.07524 |
97
+ | TWD | SAR | reference | 0.11565 |
98
+ | TZS | SAR | reference | 0.00142 |
78
99
 
79
100
  </details>
80
101
 
81
- Source: [Official rates published by SAMA, served by AllRatesToday](https://allratestoday.com/central-bank-rates-api/sama/). Rates are as printed by the central bank; AllRatesToday is not affiliated with it.
102
+ [Full table on the Saudi Central Bank (SAMA) rates page](https://allratestoday.com/central-bank-rates-api/sama/) · Source: [Official rates published by SAMA, served by AllRatesToday](https://allratestoday.com/central-bank-rates-api/sama/). Rates are as printed by the central bank; AllRatesToday is not affiliated with it.
82
103
  <!-- daily-table:end -->
83
104
 
84
105
  ## 📦 Installation
@@ -129,11 +150,11 @@ const pair = await getRate('EUR', 'SAR', { apiKey: 'art_live_...' });
129
150
  {
130
151
  bank: 'sama',
131
152
  name: 'Saudi Central Bank (SAMA)',
132
- rate_date: '2026-07-31', // Saudi Central Bank (SAMA)'s own publication date
153
+ rate_date: '2026-10-27', // Saudi Central Bank (SAMA)'s own publication date
133
154
  source: 'EUR',
134
155
  target: 'SAR',
135
- rate: 4.2976014,
136
- rate_type: 'close',
156
+ rate: 4.2015,
157
+ rate_type: 'reference',
137
158
  derived: false,
138
159
  method: 'published',
139
160
  disclaimer: 'Official rates as published by the named central bank. On weekends/holidays the most recent published rate_date is returned.'
@@ -157,11 +178,10 @@ console.log(table.rate_date, table.rates.length);
157
178
  {
158
179
  bank: 'sama',
159
180
  name: 'Saudi Central Bank (SAMA)',
160
- rate_date: '2026-07-31',
181
+ rate_date: '2026-10-27',
161
182
  rates: [
162
- { "base": "EUR", "quote": "SAR", "type": "close", "value": 4.2976014 },
163
- { "base": "EUR", "quote": "SAR", "type": "monthly_average", "value": 4.2804897 },
164
- // … the rest of the published table (12 currencies vs SAR)
183
+ { "base": "EUR", "quote": "SAR", "type": "reference", "value": 4.2015 },
184
+ // … the rest of the published table (66 currencies vs SAR)
165
185
  ],
166
186
  disclaimer: '…'
167
187
  }
@@ -200,7 +220,7 @@ Paid plans. One resolved rate per publication date — ready for charting, reval
200
220
  import { getHistory } from '@allratestoday/sama-exchange-rate';
201
221
 
202
222
  const series = await getHistory(
203
- { source: 'EUR', target: 'SAR', from: '2026-01-01', to: '2026-07-31' },
223
+ { source: 'EUR', target: 'SAR', from: '2026-01-01', to: '2026-10-27' },
204
224
  { apiKey: 'art_live_...' }
205
225
  );
206
226
  ```
@@ -213,11 +233,11 @@ const series = await getHistory(
213
233
  source: 'EUR',
214
234
  target: 'SAR',
215
235
  from: '2026-01-01',
216
- to: '2026-07-31',
236
+ to: '2026-10-27',
217
237
  count: 152,
218
238
  rates: [
219
239
  // one entry per publication date
220
- { date: '2026-07-31', rate: 4.2976014, rate_type: 'close', derived: false, method: 'published' },
240
+ { date: '2026-10-27', rate: 4.2015, rate_type: 'reference', derived: false, method: 'published' },
221
241
  // …
222
242
  ],
223
243
  disclaimer: '…'
@@ -230,16 +250,17 @@ Pass `{ symbol: 'EUR' }` instead of `source`/`target` to get the raw published r
230
250
 
231
251
  ## 🗺️ Currencies covered
232
252
 
233
- Saudi Central Bank (SAMA) currently publishes rates covering **12 currencies** against the SAR (as of the latest table):
253
+ Saudi Central Bank (SAMA) currently publishes rates covering **66 currencies** against the SAR (as of the latest table):
234
254
 
235
- 🇦🇺 `AUD` · 🇧🇷 `BRL` · 🇨🇭 `CHF` · 🇨🇳 `CNY` · 🇪🇺 `EUR` · 🇬🇧 `GBP` · 🇮🇳 `INR` · 🇯🇵 `JPY` · 🇰🇷 `KRW` · 🇹🇭 `THB` · 🇹🇷 `TRY` · 🇺🇸 `USD`
255
+ 🇦🇪 `AED` · 🇦🇫 `AFN` · 🇦🇱 `ALL` · 🇦🇷 `ARS` · 🇦🇺 `AUD` · 🇧🇦 `BAM` · 🇧🇩 `BDT` · 🇧🇬 `BGN` · 🇧🇭 `BHD` · 🇧🇳 `BND` · 🇧🇷 `BRL` · 🇨🇦 `CAD` · 🇨🇭 `CHF` · 🇨🇱 `CLP` · 🇨🇳 `CNY` · 🇨🇴 `COP` · 🇨🇺 `CUP` · 🇨🇿 `CZK` · 🇩🇯 `DJF` · 🇩🇰 `DKK` · 🇩🇿 `DZD` · 🇪🇬 `EGP` · 🇪🇹 `ETB` · 🇪🇺 `EUR` · 🇬🇧 `GBP` · 🇭🇰 `HKD` · 🇭🇺 `HUF` · 🇮🇳 `INR` · 🇮🇸 `ISK` · 🇯🇴 `JOD` · 🇯🇵 `JPY` · 🇰🇪 `KES` · 🇰🇷 `KRW` · 🇰🇼 `KWD` · 🇱🇰 `LKR` · 🇱🇾 `LYD` · 🇲🇦 `MAD` · 🇲🇲 `MMK` · 🇲🇺 `MUR` · 🇲🇽 `MXN` · 🇲🇾 `MYR` · 🇳🇬 `NGN` · 🇳🇴 `NOK` · 🇳🇿 `NZD` · 🇴🇲 `OMR` · 🇵🇭 `PHP` · 🇵🇰 `PKR` · 🇵🇱 `PLN` · 🇶🇦 `QAR` · 🇷🇴 `RON` · 🇷🇺 `RUB` · 🇸🇪 `SEK` · 🇸🇬 `SGD` · 🇸🇴 `SOS` · 🇹🇭 `THB` · 🇹🇯 `TJS` · 🇹🇳 `TND` · 🇹🇷 `TRY` · 🇹🇼 `TWD` · 🇹🇿 `TZS` · 🇺🇸 `USD` · `XAF` · `XDR` · `XOF` · 🇾🇪 `YER` · 🇿🇦 `ZAR`
236
256
 
237
257
  ## 🏛️ Source
238
258
 
239
- 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.
259
+ The Saudi Central Bank (SAMA) publishes a riyal exchange-rate table every day — 60+ currencies, seven days a week — with the riyal itself pegged to the US dollar at 3.75 since 1986. This series comes straight from SAMA’s own exchange-rate page, with daily history from April 2021 and SAMA’s monthly period averages for 12 currencies back to 2009.
240
260
 
241
- - 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)
242
- - 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/)
261
+ - Publisher's own page: [Exchange rates — sama.gov.sa](https://www.sama.gov.sa/en-US/Currency/FinExc/Pages/Currency.aspx) · [www.sama.gov.sa](https://www.sama.gov.sa)
262
+ - Publication: every business day; 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/)
263
+ - In the API: usually by **17:15 UTC** (measured over the last 14 publications). Schedule a sync at or after that time and retry hourly until `rate_date` moves; every response carries the same figure as `available_by_utc` — see [when to poll](https://allratestoday.com/docs/#when-to-poll)
243
264
  - Values are stored unmodified, with the publisher's own `rate_date` on every row — see the [methodology](https://allratestoday.com/official-rates-methodology/)
244
265
 
245
266
  ## 🧭 Reading the numbers
@@ -247,7 +268,7 @@ The Saudi Central Bank (SAMA) publishes riyal exchange rates monthly — period
247
268
  - `value` is always **quote currency per 1 unit of base currency** (`base: "EUR", quote: "USD", value: 1.15` means 1 EUR = 1.15 USD).
248
269
  - Saudi Central Bank (SAMA) quotes **SAR per 1 unit of foreign currency** (e.g. `base: "USD", quote: "SAR"` means SAR per one US dollar).
249
270
  - 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.
250
- - `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.
271
+ - `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.
251
272
 
252
273
  ## 🧩 ERP & accounting systems
253
274
 
@@ -320,7 +341,7 @@ getRate('EUR', 'SAR', { apiKey: 'art_live_...' }).then((pair) => console.log(pai
320
341
 
321
342
  ## 💡 Quota tips
322
343
 
323
- - Rates change once a month — cache the published table locally and a small monthly quota goes a long way.
344
+ - Rates change once per business day — cache the published table locally and a small monthly quota goes a long way.
324
345
  - Every request counts toward your AllRatesToday quota, shared across all AllRatesToday endpoints on your key.
325
346
 
326
347
  ## 📖 Methods reference
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@allratestoday/sama-exchange-rate",
3
- "version": "1.3.19",
4
- "description": "Official Saudi Central Bank (SAMA) (Saudi Arabia) monthly exchange rates — 12 currencies vs SAR, history since 2009. Zero-dependency Node.js/TypeScript client.",
3
+ "version": "1.3.24",
4
+ "description": "Official Saudi Central Bank (SAMA) (Saudi Arabia) daily exchange rates — 66 currencies vs SAR, history since 2009. Zero-dependency Node.js/TypeScript client.",
5
5
  "keywords": [
6
6
  "sama",
7
7
  "saudi-central-bank-sama",