bitpay-rates 1.2.18 → 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) colkito
+
+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

@@ -1,79 +1,141 @@
 # bitpay-rates
 
-![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/colkito/bitpay-rates/npm-publish.yml?style=flat-square)
+![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/colkito/bitpay-rates/ci.yml?style=flat-square)
+[![npm](https://img.shields.io/npm/v/bitpay-rates.svg?style=flat-square)](https://www.npmjs.com/package/bitpay-rates)
 [![BundlePhobia](https://img.shields.io/bundlephobia/min/bitpay-rates.svg?style=flat-square)](https://bundlephobia.com/result?p=bitpay-rates)
 [![BundlePhobia](https://img.shields.io/bundlephobia/minzip/bitpay-rates.svg?style=flat-square)](https://bundlephobia.com/result?p=bitpay-rates)
 
-A lightweight Node.js wrapper for [BitPay's](https://bitpay.com/rates) exchange rates API, now in TypeScript.
+A lightweight Node.js wrapper for [BitPay exchange rates](https://www.bitpay.com/exchange-rates), written in TypeScript.
 
-Zero-dependency, `promise` and `callback` support for easy integration into your project. ✨
+Zero runtime dependencies, promise-based, dual ESM + CommonJS. Talks to the
+official public [Rates API](https://developer.bitpay.com/reference/rates)
+(`X-Accept-Version: 2.0.0`).
 
 ## Requirements
 
-- nodejs >= 12.x
+- Node.js >= 22
 
-## Examples
+```bash
+npm install bitpay-rates
+```
 
-Getting a rate by `code`:
+## Breaking changes in v3
 
-```js
-import bitpayRates from 'bitpay-rates';
+- **Promise-only.** The legacy callback signature (`get(code, cb)`) is gone —
+  use `async/await` or `.then()` / `.catch()`.
+- **Named arguments.** `get()` now takes a single `{ base, quote }` object, so
+  there is no argument order to remember: `get('USD', 'ETH')` becomes
+  `get({ base: 'ETH', quote: 'USD' })`.
+- `get({ base })` returns the **whole table** for that base, which v2 could not
+  express. `get({ quote })` returns that one rate against BTC.
+- Dual ESM + CJS with an `exports` map (`import` and `require` both work).
+- Node.js >= 22.
+- Requests time out after 10 seconds.
+- Currency codes are validated (`/^[A-Z0-9]{2,10}$/`); anything else rejects
+  with a `TypeError` before a request is made.
+
+## Usage
+
+### ESM / TypeScript
+
+```ts
+import { get, type RateObj } from 'bitpay-rates';
+
+const all: RateObj[] = await get();
+// GET /rates/BTC  → every rate against BTC
 
-const code = 'ARS'; // see list of codes bellow
+const vsEth: RateObj[] = await get({ base: 'ETH' });
+// GET /rates/ETH  → every rate against ETH
 
-// Using promise
-bitpayRates
-  .get(code)
-  .then((rate) => console.log('Promise Rate:', rate))
-  .catch((err) => console.error('Promise Error:', err));
+const usd: RateObj = await get({ quote: 'USD' });
+// GET /rates/BTC/USD  → { code: 'USD', name: 'US Dollar', rate: 76471.42 }
+
+const ethUsd: RateObj = await get({ base: 'ETH', quote: 'USD' });
+// GET /rates/ETH/USD
 ```
 
-Successful response:
+`base` is the cryptocurrency you are pricing (default `BTC`); `quote` is the
+currency you want the price in. Omitting `quote` gives the full table. The
+return type follows from that: `RateObj[]` without `quote`, `RateObj` with it.
+
+The default export is a namespace object holding the same function, so the v2
+import style keeps working:
+
+```ts
+import bitpayRates from 'bitpay-rates';
 
-```json
-{
-  "code": "ARS",
-  "name": "Argentine Peso",
-  "rate": 3793422.92
-}
+const usd = await bitpayRates.get({ quote: 'USD' });
 ```
 
-Getting `all` the rates:
+### CommonJS
 
 ```js
-import bitpayRates from 'bitpay-rates';
+const { get } = require('bitpay-rates');
+// or: const bitpayRates = require('bitpay-rates'); bitpayRates.get({ quote: 'USD' })
 
-// Using callback
-bitpayRates.get((err, res) => {
-  console.error('Callback Error:', err);
-  console.log('Callback Rates:', res);
-});
+get({ quote: 'USD' })
+  .then((rate) => console.log(rate))
+  .catch((err) => console.error(err));
 ```
 
-Successful response:
-
-```json
-[
-  {
-    "code": "ARS",
-    "name": "Argentine Peso",
-    "rate": 5291987.02
-  },
-  {
-    "code": "BUSD",
-    "name": "Binance USD",
-    "rate": 57818.28
-  },
-  {...}
-]
+All four styles — named or default, ESM or CommonJS — are asserted against the
+built artifact on every CI run and before every publish (`npm run smoke`).
+
+### Errors
+
+`get()` rejects when BitPay returns a non-2xx status, an `{ error }` payload,
+malformed JSON, a network failure, or when the request exceeds 10 seconds. It
+rejects with a `TypeError` — before any request — when a code is not 2-10
+alphanumeric characters.
+
+It also rejects when the response shape does not match what you asked for.
+`GET /rates/{code}` is polymorphic: a base with a rate table answers with a
+list, anything else answers with a single rate. So `get({ base: 'USD' })`
+rejects rather than handing you a `RateObj` typed as `RateObj[]`.
+
+```js
+import { get } from 'bitpay-rates';
+
+get({ quote: 'INVALID' })
+  .then((rate) => console.log(rate))
+  .catch((err) => console.error(err));
 ```
 
-More examples [here](example/rates-example.js).
+More examples in [`example/rates-example.mjs`](example/rates-example.mjs)
+(run `npm run build` first).
+
+## Types
+
+```ts
+type RateObj = { code: string; name: string; rate: number };
+type RateQuery = { base?: string; quote?: string };
+
+function get(): Promise<RateObj[]>;
+function get(query: { base?: string; quote?: undefined }): Promise<RateObj[]>;
+function get(query: { base?: string; quote: string }): Promise<RateObj>;
+```
+
+Both codes are uppercased automatically and must match `/^[A-Z0-9]{2,10}$/`.
+Default `base` is `BTC`.
+
+## Available codes
+
+See [CODES.md](CODES.md). It is regenerated from `GET /rates/BTC` on every
+release PR (`npm run update-codes`). Codes containing `_` (chain-specific
+variants such as `USDC_arb`) appear in that table, but BitPay rejects them as a
+`base` or `quote`, so they cannot be queried individually.
+
+## Security
+
+Zero runtime dependencies, published from CI only via npm Trusted Publishing
+(OIDC) with a provenance attestation, and every release is gated on a human
+publishing the draft GitHub Release. See
+[SECURITY.md](.github/SECURITY.md) to report a vulnerability.
 
-## Available Codes (updated: 2024-01-24)
+## Contributing
 
-[Follow this link](CODES.md) to see the complete list of codes.
+PRs only — see [CONTRIBUTING.md](.github/CONTRIBUTING.md). MIT licensed.
 
-## Related Packages
+## Related packages
 
 - [Blockchain Exchange Rates API](https://npmjs.com/blockchain-rates)

package/dist/index.cjs

@@ -0,0 +1 @@
+Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:`Module`}});const e=`https://bitpay.com/rates`,t=1e4,n=/^[A-Z0-9]{2,10}$/,r={"X-Accept-Version":`2.0.0`,Accept:`application/json`,"User-Agent":`bitpay-rates`};async function i(n={}){let{quote:r}=n,i=a(n.base??`BTC`,`base`),s=r===void 0,c=s?`${e}/${i}`:`${e}/${i}/${a(r,`quote`)}`,l=new AbortController,u,d=new Promise((e,n)=>{u=setTimeout(()=>{let e=Error(`Request to ${c} timed out after ${t}ms`);l.abort(e),n(e)},t)});try{return await Promise.race([o(c,l.signal,s),d])}finally{u!==void 0&&clearTimeout(u)}}function a(e,t){let r=e.toUpperCase();if(!n.test(r))throw TypeError(`Invalid ${t} currency code: ${JSON.stringify(e)}`);return r}async function o(e,t,n){let i=await fetch(e,{headers:r,signal:t}),a=await i.text(),o;try{o=JSON.parse(a)}catch(t){throw i.ok?t:Error(`Request to ${e} failed with HTTP ${i.status}`)}if(s(o)&&o.error!=null)throw Error(String(o.error));if(!i.ok)throw Error(`Request to ${e} failed with HTTP ${i.status}`);let l=s(o)?o.data:void 0;if(n){if(!Array.isArray(l)||!l.every(c))throw Error(`Unexpected response from ${e}: expected a list of rates`)}else if(!c(l))throw Error(`Unexpected response from ${e}: expected a single rate`);return l}function s(e){return typeof e==`object`&&!!e}function c(e){return s(e)&&typeof e.code==`string`&&typeof e.name==`string`&&typeof e.rate==`number`}var l={get:i};exports.default=l,exports.get=i;

package/dist/index.d.cts

@@ -0,0 +1,53 @@
+//#region src/index.d.mts
+export type RateObj = {
+  code: string;
+  name: string;
+  rate: number;
+};
+export type RateResponse = RateObj | RateObj[];
+/** Arguments for {@link get}. Named so neither code can be passed in the wrong position. */
+export type RateQuery = {
+  /**
+   * Base cryptocurrency: the asset being priced.
+   *
+   * @defaultValue `'BTC'`
+   */
+  base?: string;
+  /**
+   * Quote currency: what to price `base` in. Omit for every rate against
+   * `base`.
+   */
+  quote?: string;
+};
+/**
+ * Fetch BitPay exchange rates.
+ *
+ * @param query - `{ base, quote }`. Omit `quote` for the full table, omit both for BTC.
+ * @returns Every rate for `base` when `quote` is omitted, otherwise that single {@link RateObj}.
+ * @throws `TypeError` if a code is not 2-10 alphanumeric characters, before any request is made.
+ *
+ * @example
+ * await get();                              // every rate against BTC
+ * await get({ base: 'ETH' });               // every rate against ETH
+ * await get({ quote: 'USD' });              // BTC/USD
+ * await get({ base: 'ETH', quote: 'USD' }); // ETH/USD
+ */
+export declare function get(): Promise<RateObj[]>;
+export declare function get(query: {
+  base?: string;
+  quote?: undefined;
+}): Promise<RateObj[]>;
+export declare function get(query: {
+  base?: string;
+  quote: string;
+}): Promise<RateObj>;
+/**
+ * Namespace object, so both import styles work in ESM and CommonJS:
+ * `import { get }` / `const { get } = require(...)`, and
+ * `import bitpayRates` / `const bitpayRates = require(...)` + `bitpayRates.get()`.
+ */
+declare const _default: {
+  get: typeof get;
+};
+//#endregion
+export { _default as default };

package/dist/index.d.mts

@@ -0,0 +1,53 @@
+//#region src/index.d.mts
+export type RateObj = {
+  code: string;
+  name: string;
+  rate: number;
+};
+export type RateResponse = RateObj | RateObj[];
+/** Arguments for {@link get}. Named so neither code can be passed in the wrong position. */
+export type RateQuery = {
+  /**
+   * Base cryptocurrency: the asset being priced.
+   *
+   * @defaultValue `'BTC'`
+   */
+  base?: string;
+  /**
+   * Quote currency: what to price `base` in. Omit for every rate against
+   * `base`.
+   */
+  quote?: string;
+};
+/**
+ * Fetch BitPay exchange rates.
+ *
+ * @param query - `{ base, quote }`. Omit `quote` for the full table, omit both for BTC.
+ * @returns Every rate for `base` when `quote` is omitted, otherwise that single {@link RateObj}.
+ * @throws `TypeError` if a code is not 2-10 alphanumeric characters, before any request is made.
+ *
+ * @example
+ * await get();                              // every rate against BTC
+ * await get({ base: 'ETH' });               // every rate against ETH
+ * await get({ quote: 'USD' });              // BTC/USD
+ * await get({ base: 'ETH', quote: 'USD' }); // ETH/USD
+ */
+export declare function get(): Promise<RateObj[]>;
+export declare function get(query: {
+  base?: string;
+  quote?: undefined;
+}): Promise<RateObj[]>;
+export declare function get(query: {
+  base?: string;
+  quote: string;
+}): Promise<RateObj>;
+/**
+ * Namespace object, so both import styles work in ESM and CommonJS:
+ * `import { get }` / `const { get } = require(...)`, and
+ * `import bitpayRates` / `const bitpayRates = require(...)` + `bitpayRates.get()`.
+ */
+declare const _default: {
+  get: typeof get;
+};
+//#endregion
+export { _default as default };

package/dist/index.mjs

@@ -0,0 +1 @@
+const e=`https://bitpay.com/rates`,t=1e4,n=/^[A-Z0-9]{2,10}$/,r={"X-Accept-Version":`2.0.0`,Accept:`application/json`,"User-Agent":`bitpay-rates`};async function i(n={}){let{quote:r}=n,i=a(n.base??`BTC`,`base`),s=r===void 0,c=s?`${e}/${i}`:`${e}/${i}/${a(r,`quote`)}`,l=new AbortController,u,d=new Promise((e,n)=>{u=setTimeout(()=>{let e=Error(`Request to ${c} timed out after ${t}ms`);l.abort(e),n(e)},t)});try{return await Promise.race([o(c,l.signal,s),d])}finally{u!==void 0&&clearTimeout(u)}}function a(e,t){let r=e.toUpperCase();if(!n.test(r))throw TypeError(`Invalid ${t} currency code: ${JSON.stringify(e)}`);return r}async function o(e,t,n){let i=await fetch(e,{headers:r,signal:t}),a=await i.text(),o;try{o=JSON.parse(a)}catch(t){throw i.ok?t:Error(`Request to ${e} failed with HTTP ${i.status}`)}if(s(o)&&o.error!=null)throw Error(String(o.error));if(!i.ok)throw Error(`Request to ${e} failed with HTTP ${i.status}`);let l=s(o)?o.data:void 0;if(n){if(!Array.isArray(l)||!l.every(c))throw Error(`Unexpected response from ${e}: expected a list of rates`)}else if(!c(l))throw Error(`Unexpected response from ${e}: expected a single rate`);return l}function s(e){return typeof e==`object`&&!!e}function c(e){return s(e)&&typeof e.code==`string`&&typeof e.name==`string`&&typeof e.rate==`number`}var l={get:i};export{l as default,i as get};

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "bitpay-rates",
-  "version": "1.2.18",
+  "version": "3.0.0",
   "description": "A tiny Node.js wrapper for the BitPay Rates API",
   "engines": {
-    "node": ">=12"
+    "node": ">=22"
   },
   "keywords": [
     "bitcoin",
@@ -12,10 +12,23 @@
     "countries",
     "price"
   ],
-  "author": "Mario Colque <dev@colkito.com>",
+  "author": "colkito <dev@colkito.com>",
   "license": "MIT",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "type": "commonjs",
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/colkito/bitpay-rates.git"
@@ -25,38 +38,40 @@
   },
   "homepage": "https://github.com/colkito/bitpay-rates#readme",
   "scripts": {
-    "test": "jest",
-    "test:watch": "jest --watch",
-    "test:coverage": "jest --coverage",
-    "build": "tsc --declaration && tsc --removeComments && npm run minifyDeclarations && npm run minify",
-    "format": "prettier --write \"src/**/*.ts\"",
-    "lint": "tsc --noEmit && eslint '*/**/*.{js,ts}' --quiet --fix",
-    "minify": "jsmin -l 3 -o dist/index.js dist/index.js",
-    "minifyDeclarations": "jsmin -l 3 -o dist/index.d.ts dist/index.d.ts",
-    "prepublishOnly": "npm test && npm run lint && npm run build",
-    "preversion": "npm run lint",
-    "version": "npm run format && git add -A src package.json",
-    "postversion": "git push && git push --tags"
+    "verify": "npm run lint && npm run knip && npm test && npm run build && npm run smoke",
+    "test": "node --test src/index.test.mts scripts/codes-markdown.test.mts scripts/guard-protected-refs.test.mts",
+    "test:watch": "node --test --watch src/index.test.mts scripts/codes-markdown.test.mts scripts/guard-protected-refs.test.mts",
+    "test:coverage": "node --test --experimental-test-coverage src/index.test.mts scripts/codes-markdown.test.mts scripts/guard-protected-refs.test.mts",
+    "lint": "tsc --noEmit && biome check",
+    "format": "biome check --write",
+    "knip": "knip",
+    "build": "tsdown",
+    "smoke": "node scripts/smoke.mts",
+    "update-codes": "node scripts/update-codes.mts",
+    "prepare": "node scripts/install-git-hooks.mjs",
+    "prepublishOnly": "npm run build && npm run smoke"
   },
-  "devDependencies": {
-    "@types/jest": "^26.0.21",
-    "@types/node": "^14.14.37",
-    "@typescript-eslint/eslint-plugin": "^4.18.0",
-    "@typescript-eslint/parser": "^4.18.0",
-    "eslint": "^7.21.0",
-    "eslint-config-prettier": "^8.1.0",
-    "eslint-plugin-prettier": "^3.3.1",
-    "jest": "^26.6.3",
-    "jsmin": "^1.0.1",
-    "nock": "^13.0.11",
-    "prettier": "^2.2.1",
-    "ts-jest": "^26.5.4",
-    "typescript": "^4.2.3"
+  "knip": {
+    "ignore": [
+      "example/**"
+    ]
   },
-  "resolutions": {
-    "json-schema": "^0.4.0"
+  "devDependencies": {
+    "@biomejs/biome": "2.5.13",
+    "@types/node": "26.4.1",
+    "knip": "6.35.1",
+    "tsdown": "0.23.0",
+    "typescript": "7.0.2"
   },
+  "sideEffects": false,
   "files": [
-    "dist/**/*"
-  ]
+    "dist"
+  ],
+  "devEngines": {
+    "runtime": {
+      "name": "node",
+      "version": ">=22.18.0",
+      "onFail": "error"
+    }
+  }
 }

package/dist/index.d.ts

@@ -1 +0,0 @@
-export type RateObj={code:string;name:string;rate:number;};export type RateResponse=RateObj|[RateObj];export type Callback=(error:Error|null,data?:RateResponse)=>void;export declare const get:(code?:string|Callback,callback?:Callback)=>Promise<RateResponse>|void;declare const _default:{get:(code?:string|Callback|undefined,callback?:Callback|undefined)=>void|Promise<RateResponse>;};export default _default;

package/dist/index.js

@@ -1 +0,0 @@
-"use strict";var __importDefault=(this&&this.__importDefault)||function(mod){return(mod&&mod.__esModule)?mod:{"default":mod};};Object.defineProperty(exports,"__esModule",{value:true});exports.get=void 0;const https_1=__importDefault(require("https"));const defaultOptions={host:'bitpay.com',path:'/rates',headers:{},agent:false,};const returnPromise=(options)=>{return new Promise((resolve,reject)=>{returnCallback(options,(err,data)=>{if(err)return reject(err);return resolve(data);});});};const returnCallback=(options,callback)=>{https_1.default.get(options,(res)=>{let dataBuffer='';res.on('data',(chunk)=>{dataBuffer+=chunk.toString('utf8');});res.on('end',()=>{try{const{data}=JSON.parse(dataBuffer);return callback(null,data);}catch(err){return callback(err);}});}).on('error',(err)=>{return callback(err);});};const get=(code,callback)=>{const options={...defaultOptions};if(typeof code==='string'){options.path+=`/${code.toUpperCase()}`;}if(typeof code==='function'){return returnCallback(options,code);}else if(callback){return returnCallback(options,callback);}else{return returnPromise(options);}};exports.get=get;exports.default={get:exports.get};