@allratestoday/bcstp-exchange-rate 1.3.2

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,308 @@
+# Banco Central de São Tomé e Príncipe Exchange Rates API — bcstp-exchange-rate
+
+[![npm version](https://img.shields.io/npm/v/@allratestoday%2Fbcstp-exchange-rate.svg)](https://www.npmjs.com/package/@allratestoday/bcstp-exchange-rate)
+[![license](https://img.shields.io/npm/l/@allratestoday%2Fbcstp-exchange-rate.svg)](https://github.com/AllRates-Today/bcstp-exchange-rate/blob/main/LICENSE)
+[![zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](https://www.npmjs.com/package/@allratestoday/bcstp-exchange-rate)
+[![TypeScript](https://img.shields.io/badge/TypeScript-types%20included-3178C6.svg)](https://www.typescriptlang.org/)
+
+**Official Banco Central de São Tomé e Príncipe (São Tomé and Príncipe) 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 Banco Central de São Tomé e Príncipe itself prints, every business day.**
+
+## 🚀 Why this client?
+
+- 🏛️ **Official published rates** — Banco Central de São Tomé e Príncipe's own table, with the publisher's own `rate_date` on every response
+- 📅 **History back to 2026** — 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 Banco Central de São Tomé e Príncipe 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.
+
+## ⚡ Try it without a key
+
+The latest Banco Central de São Tomé e Príncipe 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/bcstp?source=USD&target=STN"
+```
+
+```js
+const r = await fetch('https://allratestoday.com/api/open/central-bank/bcstp').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
+
+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/bcstp-exchange-rate
+```
+
+```bash
+yarn add @allratestoday/bcstp-exchange-rate
+```
+
+```bash
+pnpm add @allratestoday/bcstp-exchange-rate
+```
+
+Requires Node 18+ (global `fetch`); also runs on Bun, Deno and edge runtimes. Scoped mirror of [`bcstp-exchange-rate`](https://www.npmjs.com/package/bcstp-exchange-rate) — same code, same versions.
+
+## 🏁 Quick start
+
+```js
+import { getRate } from '@allratestoday/bcstp-exchange-rate';
+
+const pair = await getRate('USD', 'STN', { apiKey: 'art_live_...' });
+console.log(pair.rate, pair.rate_date); // the official Banco Central de São Tomé e Príncipe 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', 'STN', { apiKey: 'art_live_...' });
+```
+
+**Response:**
+
+```javascript
+{
+  bank: 'bcstp',
+  name: 'Banco Central de São Tomé e Príncipe',
+  rate_date: '2026-09-25',   // Banco Central de São Tomé e Príncipe's own publication date
+  source: 'USD',
+  target: 'STN',
+  rate: 21.7153,
+  rate_type: 'middle',
+  derived: false,
+  method: 'published',
+  disclaimer: 'Official rates as published by the named central bank. On weekends/holidays the most recent published rate_date is returned.'
+}
+```
+
+### Full published table
+
+Free plan and up. The complete table for the latest publication date.
+
+```js
+import { getLatestRates } from '@allratestoday/bcstp-exchange-rate';
+
+const table = await getLatestRates({ apiKey: 'art_live_...' });
+console.log(table.rate_date, table.rates.length);
+```
+
+**Response:**
+
+```javascript
+{
+  bank: 'bcstp',
+  name: 'Banco Central de São Tomé e Príncipe',
+  rate_date: '2026-09-25',
+  rates: [
+    { "base": "USD", "quote": "STN", "type": "buy", "value": 21.5536 },
+    { "base": "USD", "quote": "STN", "type": "sell", "value": 21.8769 },
+    { "base": "USD", "quote": "STN", "type": "middle", "value": 21.7153 },
+    // … the rest of the published table (14 currencies vs STN)
+  ],
+  disclaimer: '…'
+}
+```
+
+### Table for a date
+
+Paid plans. The official table for any date since 2026 — 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 '@allratestoday/bcstp-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: 'STN' });
+```
+
+**Response:**
+
+```javascript
+{
+  bank: 'bcstp',
+  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/bcstp-exchange-rate';
+
+const series = await getHistory(
+  { source: 'USD', target: 'STN', from: '2026-01-01', to: '2026-09-25' },
+  { apiKey: 'art_live_...' }
+);
+```
+
+**Response:**
+
+```javascript
+{
+  bank: 'bcstp',
+  source: 'USD',
+  target: 'STN',
+  from: '2026-01-01',
+  to: '2026-09-25',
+  count: 152,
+  rates: [
+    // one entry per publication date
+    { date: '2026-09-25', rate: 21.7153, rate_type: 'middle', 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
+
+Banco Central de São Tomé e Príncipe currently publishes rates covering **14 currencies** against the STN (as of the latest table):
+
+🇧🇷 `BRL` · 🇨🇦 `CAD` · 🇨🇭 `CHF` · 🇨🇳 `CNY` · 🇩🇰 `DKK` · 🇪🇺 `EUR` · 🇬🇧 `GBP` · 🇯🇵 `JPY` · 🇳🇴 `NOK` · 🇸🇪 `SEK` · 🇺🇸 `USD` · `XAF` · `XDR` · 🇿🇦 `ZAR`
+
+## 🏛️ Source
+
+Banco Central de São Tomé e Príncipe publishes a daily exchange bulletin for the dobra (STN): buying, selling and mid rates for 14 currencies and the SDR. The dobra has been pegged to the euro at 24.5 since 2010, so the euro line is fixed and the dollar, pound, yen, CFA franc, real and the rest move with the euro's crosses. The bulletin is the official rate for customs and tax purposes in São Tomé; the bank publishes the table in force only, so our archive builds forward from September 2026.
+
+- Publisher's own page: [Boletim de Câmbio](https://www.bcstp.st/Cambio) · [www.bcstp.st](https://www.bcstp.st)
+- Publication: every business day; the exact schedule, freshness status and any current delay are on the [Banco Central de São Tomé e Príncipe rates page](https://allratestoday.com/central-bank-rates-api/bcstp/)
+- 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).
+- Banco Central de São Tomé e Príncipe quotes **STN per 1 unit of foreign currency** (e.g. `base: "USD", quote: "STN"` means STN 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 (`middle` here); some publishers print buy/sell or several fixings for the same pair.
+
+## 🧩 ERP & accounting systems
+
+Loading the official Banco Central de São Tomé e Príncipe 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/bcstp/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 Banco Central de São Tomé e Príncipe 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 STN 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 Banco Central de São Tomé e Príncipe |
+| `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/bcstp-exchange-rate';
+```
+
+## 📦 CommonJS
+
+```javascript
+const { getRate } = require('@allratestoday/bcstp-exchange-rate');
+
+getRate('USD', 'STN', { 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 2026 |
+
+## 📥 Bulk data (no key)
+
+Need the whole archive rather than an API call? The same published tables are mirrored daily as open data:
+
+- Hugging Face: [AllRates/central-bank-exchange-rates](https://huggingface.co/datasets/AllRates/central-bank-exchange-rates) — one CSV per institution (`rates/bcstp.csv`)
+- Kaggle: [allratestoday/central-bank-exchange-rates](https://www.kaggle.com/datasets/allratestoday/central-bank-exchange-rates)
+- CDN JSON: `https://cdn.jsdelivr.net/gh/AllRates-Today/central-bank-exchange-rates@main/data/bcstp/latest.json`
+
+## 🔗 Links
+
+- [Banco Central de São Tomé e Príncipe rates page](https://allratestoday.com/central-bank-rates-api/bcstp/) — live table, publication cadence, FAQ
+- [All central bank sources](https://allratestoday.com/central-bank-rates-api/)
+- [Package docs on the site](https://allratestoday.com/docs/sdk/bcstp-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/bcstp-exchange-rate)
+
+## 📜 License
+
+MIT

package/index.cjs

@@ -0,0 +1,47 @@
+'use strict';
+// Banco Central de São Tomé e Príncipe exchange rates via the AllRatesToday API.
+const BASE = 'https://allratestoday.com/api/v1/central-bank/bcstp';
+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', 'STN', { 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: 'bcstp';
+  name: string;
+  rate_date: string;
+  rates: RateEntry[];
+  disclaimer: string;
+}
+
+export interface PairRate {
+  bank: 'bcstp';
+  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 @@
+// Banco Central de São Tomé e Príncipe exchange rates via the AllRatesToday API.
+const BASE = 'https://allratestoday.com/api/v1/central-bank/bcstp';
+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', 'STN', { 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,58 @@
+{
+  "name": "@allratestoday/bcstp-exchange-rate",
+  "version": "1.3.2",
+  "description": "Official Banco Central de São Tomé e Príncipe (São Tomé and Príncipe) daily exchange rates — 14 currencies vs STN, history since 2026. Zero-dependency Node.js/TypeScript client.",
+  "keywords": [
+    "bcstp",
+    "banco",
+    "central",
+    "de",
+    "são",
+    "tomé",
+    "e",
+    "príncipe",
+    "exchange-rate",
+    "exchange-rates",
+    "currency",
+    "forex",
+    "fx",
+    "stn",
+    "central-bank",
+    "official-rates",
+    "são-tomé-and-príncipe",
+    "api",
+    "typescript"
+  ],
+  "homepage": "https://allratestoday.com/central-bank-rates-api/bcstp/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AllRates-Today/bcstp-exchange-rate.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AllRates-Today/bcstp-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
+}