bcv-today 0.0.0-stage → 1.0.0
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.
- package/CHANGELOG.md +20 -0
- package/LICENSE +201 -0
- package/README.md +152 -2
- package/dist/chunk-2JWU4TEK.js +412 -0
- package/dist/cli.js +854 -0
- package/dist/index.cjs +874 -0
- package/dist/index.d.cts +316 -0
- package/dist/index.d.ts +316 -0
- package/dist/index.js +854 -0
- package/dist/stdio-HI6U6UUH.js +838 -0
- package/package.json +88 -4
package/dist/index.d.cts
ADDED
|
@@ -0,0 +1,316 @@
|
|
|
1
|
+
/** Foreign currencies published by BCV, in display order. */
|
|
2
|
+
declare const CURRENCIES: readonly ["USD", "EUR", "CNY", "TRY", "RUB"];
|
|
3
|
+
type Currency = (typeof CURRENCIES)[number];
|
|
4
|
+
/** Currencies accepted by conversions: the bolivar plus the published ones. */
|
|
5
|
+
declare const ANY_CURRENCIES: readonly ["VES", "USD", "EUR", "CNY", "TRY", "RUB"];
|
|
6
|
+
type AnyCurrency = (typeof ANY_CURRENCIES)[number];
|
|
7
|
+
/** Attribution string attached to every result. */
|
|
8
|
+
declare const SOURCE = "Banco Central de Venezuela (BCV), via https://bcv.today";
|
|
9
|
+
/** Unit of every rate value. */
|
|
10
|
+
declare const UNIT = "VES (bolivars) per 1 unit of the currency";
|
|
11
|
+
/** First calendar day with a /api/v1/history/{date}.json snapshot. */
|
|
12
|
+
declare const EARLIEST_SNAPSHOT = "2021-08-02";
|
|
13
|
+
/** history.json keeps (at most) this many daily entries. */
|
|
14
|
+
declare const MAX_HISTORY_DAYS = 1830;
|
|
15
|
+
/** One daily entry as published by the API (rate.json, history.json items, day snapshots). */
|
|
16
|
+
interface RateEntry {
|
|
17
|
+
date: string;
|
|
18
|
+
effective_date?: string;
|
|
19
|
+
updated_at?: string;
|
|
20
|
+
source?: string;
|
|
21
|
+
USD?: number;
|
|
22
|
+
EUR?: number;
|
|
23
|
+
CNY?: number;
|
|
24
|
+
TRY?: number;
|
|
25
|
+
RUB?: number;
|
|
26
|
+
}
|
|
27
|
+
/** /api/v1/status.json as published. */
|
|
28
|
+
interface StatusDoc {
|
|
29
|
+
status?: string;
|
|
30
|
+
updated_at?: string;
|
|
31
|
+
generated_at?: string;
|
|
32
|
+
date?: string;
|
|
33
|
+
effective_date?: string;
|
|
34
|
+
timezone?: string;
|
|
35
|
+
source?: string;
|
|
36
|
+
supported_currencies?: string[];
|
|
37
|
+
api_version?: string;
|
|
38
|
+
currencies?: Record<string, boolean>;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
declare const DEFAULT_BASE_URL = "https://bcv.today";
|
|
42
|
+
type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
|
|
43
|
+
|
|
44
|
+
/** Bolivars (VES) per one unit of each published currency. */
|
|
45
|
+
type RateMap = Partial<Record<Currency, number>>;
|
|
46
|
+
/** The official BCV rates currently in effect (`/api/v1/rate.json`). */
|
|
47
|
+
interface Rates {
|
|
48
|
+
/** Bolivars per unit, keyed by currency code, in USD, EUR, CNY, TRY, RUB order. */
|
|
49
|
+
rates: RateMap;
|
|
50
|
+
/** Calendar date of the snapshot. */
|
|
51
|
+
date: string;
|
|
52
|
+
/** Official BCV validity date ("fecha valor"). */
|
|
53
|
+
effectiveDate: string;
|
|
54
|
+
/** UTC capture time of the rate, when known. */
|
|
55
|
+
updatedAt: Date | null;
|
|
56
|
+
unit: string;
|
|
57
|
+
source: string;
|
|
58
|
+
/** One-line English description. */
|
|
59
|
+
summary: string;
|
|
60
|
+
/** The entry as published by the API. */
|
|
61
|
+
raw: RateEntry;
|
|
62
|
+
}
|
|
63
|
+
/** The BCV rate(s) in effect on one calendar day (`/api/v1/history/{date}.json`). */
|
|
64
|
+
interface DayRate {
|
|
65
|
+
/** The calendar day that was requested. */
|
|
66
|
+
date: string;
|
|
67
|
+
/** Date of the BCV publication in effect that day (earlier on weekends/holidays). */
|
|
68
|
+
effectiveDate: string;
|
|
69
|
+
/** True when `effectiveDate` differs from `date` (rate carried forward). */
|
|
70
|
+
carriedForward: boolean;
|
|
71
|
+
/** Bolivars per unit (only the requested currency when one was given). */
|
|
72
|
+
rates: RateMap;
|
|
73
|
+
/** The single rate when exactly one currency is present (e.g. `on(d, "USD")`). */
|
|
74
|
+
rate: number | undefined;
|
|
75
|
+
updatedAt: Date | null;
|
|
76
|
+
/** Human explanation of the carry-forward, when it applies. */
|
|
77
|
+
note: string | null;
|
|
78
|
+
unit: string;
|
|
79
|
+
source: string;
|
|
80
|
+
summary: string;
|
|
81
|
+
raw: RateEntry;
|
|
82
|
+
}
|
|
83
|
+
/** One daily entry of a `History` series. */
|
|
84
|
+
interface HistoryPoint {
|
|
85
|
+
date: string;
|
|
86
|
+
effectiveDate: string;
|
|
87
|
+
/** Bolivars per unit of the series currency. */
|
|
88
|
+
rate: number;
|
|
89
|
+
carriedForward: boolean;
|
|
90
|
+
}
|
|
91
|
+
/** A daily rate series for one currency, oldest first (never empty). */
|
|
92
|
+
interface History {
|
|
93
|
+
currency: Currency;
|
|
94
|
+
points: HistoryPoint[];
|
|
95
|
+
/** First date of the series. */
|
|
96
|
+
start: string;
|
|
97
|
+
/** Last date of the series. */
|
|
98
|
+
end: string;
|
|
99
|
+
first: HistoryPoint;
|
|
100
|
+
last: HistoryPoint;
|
|
101
|
+
/** Lowest rate (earliest day on ties). */
|
|
102
|
+
min: HistoryPoint;
|
|
103
|
+
/** Highest rate (earliest day on ties). */
|
|
104
|
+
max: HistoryPoint;
|
|
105
|
+
/** `last.rate - first.rate`, exact (as a number). */
|
|
106
|
+
change: number;
|
|
107
|
+
/** `last.rate - first.rate`, exact decimal string. */
|
|
108
|
+
changeExact: string;
|
|
109
|
+
/** Percentage change from first to last, rounded half-up to 4 decimals. */
|
|
110
|
+
changePct: number;
|
|
111
|
+
/** Explanation when the requested range was clipped to the available data. */
|
|
112
|
+
note: string | null;
|
|
113
|
+
unit: string;
|
|
114
|
+
source: string;
|
|
115
|
+
summary: string;
|
|
116
|
+
}
|
|
117
|
+
/**
|
|
118
|
+
* Result of `BCV.convert()`.
|
|
119
|
+
*
|
|
120
|
+
* `resultExact` is `amount * vesPerFrom / vesPerTo` (VES counts as 1) computed
|
|
121
|
+
* with exact decimal arithmetic (division to 28 significant digits, half-up);
|
|
122
|
+
* `result`/`resultText` are rounded half-up to `decimals` places.
|
|
123
|
+
*/
|
|
124
|
+
interface Conversion {
|
|
125
|
+
/** The amount, as a number. */
|
|
126
|
+
amount: number;
|
|
127
|
+
/** The amount, as an exact decimal string. */
|
|
128
|
+
amountExact: string;
|
|
129
|
+
from: AnyCurrency;
|
|
130
|
+
to: AnyCurrency;
|
|
131
|
+
/** Rounded result as a number (e.g. 91664.77). */
|
|
132
|
+
result: number;
|
|
133
|
+
/** Rounded result with exactly `decimals` places (e.g. "91664.77", "1.10"). */
|
|
134
|
+
resultText: string;
|
|
135
|
+
/** Unrounded result, exact decimal string (28 significant digits for divisions). */
|
|
136
|
+
resultExact: string;
|
|
137
|
+
/** Units of `to` per 1 unit of `from`, as a number. */
|
|
138
|
+
rate: number;
|
|
139
|
+
/** Units of `to` per 1 unit of `from`, exact decimal string (28 significant digits). */
|
|
140
|
+
rateExact: string;
|
|
141
|
+
/** Bolivars per unit for the non-VES side(s) of the conversion. */
|
|
142
|
+
ratesUsed: RateMap;
|
|
143
|
+
/** Requested date, or the date of the latest snapshot. */
|
|
144
|
+
date: string;
|
|
145
|
+
effectiveDate: string;
|
|
146
|
+
carriedForward: boolean;
|
|
147
|
+
/** Decimal places of `result` (`null` = not rounded). */
|
|
148
|
+
decimals: number | null;
|
|
149
|
+
note: string | null;
|
|
150
|
+
source: string;
|
|
151
|
+
summary: string;
|
|
152
|
+
}
|
|
153
|
+
/** Freshness of the published data (`/api/v1/status.json`). */
|
|
154
|
+
interface Status {
|
|
155
|
+
status: string;
|
|
156
|
+
updatedAt: Date | null;
|
|
157
|
+
generatedAt: Date | null;
|
|
158
|
+
date: string | null;
|
|
159
|
+
effectiveDate: string | null;
|
|
160
|
+
/** Hours since `updatedAt` (one decimal), when known. */
|
|
161
|
+
ageHours: number | null;
|
|
162
|
+
/** True when status is not "ok" or the last capture is older than 96 hours. */
|
|
163
|
+
stale: boolean;
|
|
164
|
+
supportedCurrencies: string[];
|
|
165
|
+
currencies: Record<string, boolean>;
|
|
166
|
+
timezone: string | null;
|
|
167
|
+
apiVersion: string | null;
|
|
168
|
+
summary: string;
|
|
169
|
+
raw: StatusDoc;
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
declare const DEFAULT_USER_AGENT = "bcv-today-js/1.0.0 (+https://bcv.today)";
|
|
173
|
+
/** A calendar day: "YYYY-MM-DD" or a Date (its UTC calendar day is used). */
|
|
174
|
+
type DateInput = string | Date;
|
|
175
|
+
/** An amount: a number, a decimal string ("12.50", "1_000") or a bigint. */
|
|
176
|
+
type AmountInput = number | string | bigint;
|
|
177
|
+
interface BCVOptions {
|
|
178
|
+
/** API origin. Default "https://bcv.today". */
|
|
179
|
+
baseUrl?: string;
|
|
180
|
+
/** Per-request timeout in milliseconds (default 10000; 0 disables it). */
|
|
181
|
+
timeoutMs?: number;
|
|
182
|
+
/** How long responses stay in the in-memory cache, in ms (default 300000; 0 disables it). */
|
|
183
|
+
cacheTtlMs?: number;
|
|
184
|
+
/** fetch implementation (default: the global fetch). */
|
|
185
|
+
fetch?: FetchLike;
|
|
186
|
+
/** User-Agent header (default "bcv-today-js/<version> (+https://bcv.today)"); not sent by browsers. */
|
|
187
|
+
userAgent?: string;
|
|
188
|
+
/** Clock used for "today in Caracas" and data age (testing hook). */
|
|
189
|
+
now?: () => Date | number;
|
|
190
|
+
}
|
|
191
|
+
interface HistoryOptions {
|
|
192
|
+
/** Last N calendar days ending on the latest published date (1 to 1830, default 30). */
|
|
193
|
+
days?: number;
|
|
194
|
+
/** Inclusive range start (overrides `days`). */
|
|
195
|
+
start?: DateInput;
|
|
196
|
+
/** Inclusive range end (overrides `days`). */
|
|
197
|
+
end?: DateInput;
|
|
198
|
+
}
|
|
199
|
+
interface ConvertOptions {
|
|
200
|
+
/** Use the rate in effect that day instead of the latest one. */
|
|
201
|
+
date?: DateInput;
|
|
202
|
+
/** Decimal places of `result` (0 to 12, default 2, rounded half-up); `null` keeps full precision. */
|
|
203
|
+
decimals?: number | null;
|
|
204
|
+
}
|
|
205
|
+
/**
|
|
206
|
+
* Client for the free, read-only BCV Today API (https://bcv.today/api/).
|
|
207
|
+
*
|
|
208
|
+
* Rates are bolivars (VES) per one unit of USD, EUR, CNY, TRY or RUB, as
|
|
209
|
+
* published by Banco Central de Venezuela. Unofficial project, not affiliated
|
|
210
|
+
* with the bank.
|
|
211
|
+
*
|
|
212
|
+
* @example
|
|
213
|
+
* const bcv = new BCV();
|
|
214
|
+
* const { rates } = await bcv.latest(); // { USD: 916.6477, ... }
|
|
215
|
+
* const c = await bcv.convert(100, "USD", "VES"); // c.resultText === "91664.77"
|
|
216
|
+
*/
|
|
217
|
+
declare class BCV {
|
|
218
|
+
readonly baseUrl: string;
|
|
219
|
+
readonly timeoutMs: number;
|
|
220
|
+
readonly cacheTtlMs: number;
|
|
221
|
+
readonly userAgent: string;
|
|
222
|
+
private readonly api;
|
|
223
|
+
private readonly cache;
|
|
224
|
+
private readonly clock;
|
|
225
|
+
constructor(options?: BCVOptions);
|
|
226
|
+
/** Forgets every cached response. */
|
|
227
|
+
clearCache(): void;
|
|
228
|
+
private today;
|
|
229
|
+
private latestEntry;
|
|
230
|
+
private dayEntry;
|
|
231
|
+
/** Official rates currently in effect (`/api/v1/rate.json`). */
|
|
232
|
+
latest(): Promise<Rates>;
|
|
233
|
+
/**
|
|
234
|
+
* Rate(s) in effect on a calendar day.
|
|
235
|
+
*
|
|
236
|
+
* BCV does not publish on weekends and holidays: the last published rate stays
|
|
237
|
+
* in effect, so `effectiveDate` may be earlier than `date` and `carriedForward`
|
|
238
|
+
* is then true (with an explanatory `note`). Data starts on 2021-08-02; dates
|
|
239
|
+
* after tomorrow (Caracas time) throw `DateOutOfRange`.
|
|
240
|
+
*
|
|
241
|
+
* @param date "YYYY-MM-DD" or a Date (its UTC calendar day).
|
|
242
|
+
* @param currency Restrict the result to one currency (throws `CurrencyNotAvailable` if it was not published that day).
|
|
243
|
+
*/
|
|
244
|
+
on(date: DateInput, currency?: string): Promise<DayRate>;
|
|
245
|
+
/**
|
|
246
|
+
* Daily series for one currency, oldest first: the last `days` calendar days
|
|
247
|
+
* ending on the latest published date (default 30, max 1830), or an inclusive
|
|
248
|
+
* `start`/`end` range (`days` is then ignored). Uses `/api/v1/history.json`,
|
|
249
|
+
* which keeps the latest 1830 daily entries; ranges are clipped to what it
|
|
250
|
+
* covers and `note` says so.
|
|
251
|
+
*/
|
|
252
|
+
history(currency: string, options?: HistoryOptions): Promise<History>;
|
|
253
|
+
/**
|
|
254
|
+
* Converts `amount` between VES, USD, EUR, CNY, TRY and RUB at the BCV rate.
|
|
255
|
+
*
|
|
256
|
+
* Cross rates go through the bolivar: `amount * vesPerFrom / vesPerTo`. The
|
|
257
|
+
* math is exact decimal (no float drift; divisions keep 28 significant
|
|
258
|
+
* digits, half-up), then `result` is rounded half-up to `decimals` places
|
|
259
|
+
* (default 2; `null` keeps full precision). `resultExact` is the unrounded
|
|
260
|
+
* value as a string. Numbers are read via their shortest decimal string
|
|
261
|
+
* (0.1 is exactly "0.1"); pass a string for amounts beyond float precision.
|
|
262
|
+
*/
|
|
263
|
+
convert(amount: AmountInput, from: string, to: string, options?: ConvertOptions): Promise<Conversion>;
|
|
264
|
+
/** Freshness of the published data (`/api/v1/status.json`). */
|
|
265
|
+
status(): Promise<Status>;
|
|
266
|
+
}
|
|
267
|
+
|
|
268
|
+
/** Base class of every error thrown by `bcv-today`. */
|
|
269
|
+
declare class BCVError extends Error {
|
|
270
|
+
name: string;
|
|
271
|
+
constructor(message: string, options?: {
|
|
272
|
+
cause?: unknown;
|
|
273
|
+
});
|
|
274
|
+
}
|
|
275
|
+
/** An argument passed by the caller is invalid. */
|
|
276
|
+
declare class InvalidArgument extends BCVError {
|
|
277
|
+
name: string;
|
|
278
|
+
}
|
|
279
|
+
/** A date is malformed or not a real calendar day (expected `YYYY-MM-DD`). */
|
|
280
|
+
declare class InvalidDate extends InvalidArgument {
|
|
281
|
+
name: string;
|
|
282
|
+
}
|
|
283
|
+
/** A currency code is not one of VES, USD, EUR, CNY, TRY or RUB (or is misused). */
|
|
284
|
+
declare class InvalidCurrency extends InvalidArgument {
|
|
285
|
+
name: string;
|
|
286
|
+
}
|
|
287
|
+
/** An amount is negative, not finite, too large or not a number (or `decimals` is invalid). */
|
|
288
|
+
declare class InvalidAmount extends InvalidArgument {
|
|
289
|
+
name: string;
|
|
290
|
+
}
|
|
291
|
+
/** The date is valid but no BCV data exists for it (too old, future or not published). */
|
|
292
|
+
declare class DateOutOfRange extends BCVError {
|
|
293
|
+
name: string;
|
|
294
|
+
}
|
|
295
|
+
/** The currency is supported, but the BCV data has no rate for it on that day. */
|
|
296
|
+
declare class CurrencyNotAvailable extends BCVError {
|
|
297
|
+
name: string;
|
|
298
|
+
}
|
|
299
|
+
/** The BCV Today API answered HTTP 404 for a path. */
|
|
300
|
+
declare class NotFound extends BCVError {
|
|
301
|
+
name: string;
|
|
302
|
+
}
|
|
303
|
+
/** The BCV Today API could not be reached or returned an unusable response. */
|
|
304
|
+
declare class UpstreamError extends BCVError {
|
|
305
|
+
name: string;
|
|
306
|
+
/** HTTP status code, when the error came from an HTTP response. */
|
|
307
|
+
readonly status: number | undefined;
|
|
308
|
+
constructor(message: string, status?: number, options?: {
|
|
309
|
+
cause?: unknown;
|
|
310
|
+
});
|
|
311
|
+
}
|
|
312
|
+
|
|
313
|
+
/** Version of the bcv-today package (kept in sync with package.json by a test). */
|
|
314
|
+
declare const VERSION = "1.0.0";
|
|
315
|
+
|
|
316
|
+
export { ANY_CURRENCIES, type AmountInput, type AnyCurrency, BCV, BCVError, type BCVOptions, CURRENCIES, type Conversion, type ConvertOptions, type Currency, CurrencyNotAvailable, DEFAULT_BASE_URL, DEFAULT_USER_AGENT, type DateInput, DateOutOfRange, type DayRate, EARLIEST_SNAPSHOT, type FetchLike, type History, type HistoryOptions, type HistoryPoint, InvalidAmount, InvalidArgument, InvalidCurrency, InvalidDate, MAX_HISTORY_DAYS, NotFound, type RateEntry, type RateMap, type Rates, SOURCE, type Status, type StatusDoc, UNIT, UpstreamError, VERSION };
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,316 @@
|
|
|
1
|
+
/** Foreign currencies published by BCV, in display order. */
|
|
2
|
+
declare const CURRENCIES: readonly ["USD", "EUR", "CNY", "TRY", "RUB"];
|
|
3
|
+
type Currency = (typeof CURRENCIES)[number];
|
|
4
|
+
/** Currencies accepted by conversions: the bolivar plus the published ones. */
|
|
5
|
+
declare const ANY_CURRENCIES: readonly ["VES", "USD", "EUR", "CNY", "TRY", "RUB"];
|
|
6
|
+
type AnyCurrency = (typeof ANY_CURRENCIES)[number];
|
|
7
|
+
/** Attribution string attached to every result. */
|
|
8
|
+
declare const SOURCE = "Banco Central de Venezuela (BCV), via https://bcv.today";
|
|
9
|
+
/** Unit of every rate value. */
|
|
10
|
+
declare const UNIT = "VES (bolivars) per 1 unit of the currency";
|
|
11
|
+
/** First calendar day with a /api/v1/history/{date}.json snapshot. */
|
|
12
|
+
declare const EARLIEST_SNAPSHOT = "2021-08-02";
|
|
13
|
+
/** history.json keeps (at most) this many daily entries. */
|
|
14
|
+
declare const MAX_HISTORY_DAYS = 1830;
|
|
15
|
+
/** One daily entry as published by the API (rate.json, history.json items, day snapshots). */
|
|
16
|
+
interface RateEntry {
|
|
17
|
+
date: string;
|
|
18
|
+
effective_date?: string;
|
|
19
|
+
updated_at?: string;
|
|
20
|
+
source?: string;
|
|
21
|
+
USD?: number;
|
|
22
|
+
EUR?: number;
|
|
23
|
+
CNY?: number;
|
|
24
|
+
TRY?: number;
|
|
25
|
+
RUB?: number;
|
|
26
|
+
}
|
|
27
|
+
/** /api/v1/status.json as published. */
|
|
28
|
+
interface StatusDoc {
|
|
29
|
+
status?: string;
|
|
30
|
+
updated_at?: string;
|
|
31
|
+
generated_at?: string;
|
|
32
|
+
date?: string;
|
|
33
|
+
effective_date?: string;
|
|
34
|
+
timezone?: string;
|
|
35
|
+
source?: string;
|
|
36
|
+
supported_currencies?: string[];
|
|
37
|
+
api_version?: string;
|
|
38
|
+
currencies?: Record<string, boolean>;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
declare const DEFAULT_BASE_URL = "https://bcv.today";
|
|
42
|
+
type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
|
|
43
|
+
|
|
44
|
+
/** Bolivars (VES) per one unit of each published currency. */
|
|
45
|
+
type RateMap = Partial<Record<Currency, number>>;
|
|
46
|
+
/** The official BCV rates currently in effect (`/api/v1/rate.json`). */
|
|
47
|
+
interface Rates {
|
|
48
|
+
/** Bolivars per unit, keyed by currency code, in USD, EUR, CNY, TRY, RUB order. */
|
|
49
|
+
rates: RateMap;
|
|
50
|
+
/** Calendar date of the snapshot. */
|
|
51
|
+
date: string;
|
|
52
|
+
/** Official BCV validity date ("fecha valor"). */
|
|
53
|
+
effectiveDate: string;
|
|
54
|
+
/** UTC capture time of the rate, when known. */
|
|
55
|
+
updatedAt: Date | null;
|
|
56
|
+
unit: string;
|
|
57
|
+
source: string;
|
|
58
|
+
/** One-line English description. */
|
|
59
|
+
summary: string;
|
|
60
|
+
/** The entry as published by the API. */
|
|
61
|
+
raw: RateEntry;
|
|
62
|
+
}
|
|
63
|
+
/** The BCV rate(s) in effect on one calendar day (`/api/v1/history/{date}.json`). */
|
|
64
|
+
interface DayRate {
|
|
65
|
+
/** The calendar day that was requested. */
|
|
66
|
+
date: string;
|
|
67
|
+
/** Date of the BCV publication in effect that day (earlier on weekends/holidays). */
|
|
68
|
+
effectiveDate: string;
|
|
69
|
+
/** True when `effectiveDate` differs from `date` (rate carried forward). */
|
|
70
|
+
carriedForward: boolean;
|
|
71
|
+
/** Bolivars per unit (only the requested currency when one was given). */
|
|
72
|
+
rates: RateMap;
|
|
73
|
+
/** The single rate when exactly one currency is present (e.g. `on(d, "USD")`). */
|
|
74
|
+
rate: number | undefined;
|
|
75
|
+
updatedAt: Date | null;
|
|
76
|
+
/** Human explanation of the carry-forward, when it applies. */
|
|
77
|
+
note: string | null;
|
|
78
|
+
unit: string;
|
|
79
|
+
source: string;
|
|
80
|
+
summary: string;
|
|
81
|
+
raw: RateEntry;
|
|
82
|
+
}
|
|
83
|
+
/** One daily entry of a `History` series. */
|
|
84
|
+
interface HistoryPoint {
|
|
85
|
+
date: string;
|
|
86
|
+
effectiveDate: string;
|
|
87
|
+
/** Bolivars per unit of the series currency. */
|
|
88
|
+
rate: number;
|
|
89
|
+
carriedForward: boolean;
|
|
90
|
+
}
|
|
91
|
+
/** A daily rate series for one currency, oldest first (never empty). */
|
|
92
|
+
interface History {
|
|
93
|
+
currency: Currency;
|
|
94
|
+
points: HistoryPoint[];
|
|
95
|
+
/** First date of the series. */
|
|
96
|
+
start: string;
|
|
97
|
+
/** Last date of the series. */
|
|
98
|
+
end: string;
|
|
99
|
+
first: HistoryPoint;
|
|
100
|
+
last: HistoryPoint;
|
|
101
|
+
/** Lowest rate (earliest day on ties). */
|
|
102
|
+
min: HistoryPoint;
|
|
103
|
+
/** Highest rate (earliest day on ties). */
|
|
104
|
+
max: HistoryPoint;
|
|
105
|
+
/** `last.rate - first.rate`, exact (as a number). */
|
|
106
|
+
change: number;
|
|
107
|
+
/** `last.rate - first.rate`, exact decimal string. */
|
|
108
|
+
changeExact: string;
|
|
109
|
+
/** Percentage change from first to last, rounded half-up to 4 decimals. */
|
|
110
|
+
changePct: number;
|
|
111
|
+
/** Explanation when the requested range was clipped to the available data. */
|
|
112
|
+
note: string | null;
|
|
113
|
+
unit: string;
|
|
114
|
+
source: string;
|
|
115
|
+
summary: string;
|
|
116
|
+
}
|
|
117
|
+
/**
|
|
118
|
+
* Result of `BCV.convert()`.
|
|
119
|
+
*
|
|
120
|
+
* `resultExact` is `amount * vesPerFrom / vesPerTo` (VES counts as 1) computed
|
|
121
|
+
* with exact decimal arithmetic (division to 28 significant digits, half-up);
|
|
122
|
+
* `result`/`resultText` are rounded half-up to `decimals` places.
|
|
123
|
+
*/
|
|
124
|
+
interface Conversion {
|
|
125
|
+
/** The amount, as a number. */
|
|
126
|
+
amount: number;
|
|
127
|
+
/** The amount, as an exact decimal string. */
|
|
128
|
+
amountExact: string;
|
|
129
|
+
from: AnyCurrency;
|
|
130
|
+
to: AnyCurrency;
|
|
131
|
+
/** Rounded result as a number (e.g. 91664.77). */
|
|
132
|
+
result: number;
|
|
133
|
+
/** Rounded result with exactly `decimals` places (e.g. "91664.77", "1.10"). */
|
|
134
|
+
resultText: string;
|
|
135
|
+
/** Unrounded result, exact decimal string (28 significant digits for divisions). */
|
|
136
|
+
resultExact: string;
|
|
137
|
+
/** Units of `to` per 1 unit of `from`, as a number. */
|
|
138
|
+
rate: number;
|
|
139
|
+
/** Units of `to` per 1 unit of `from`, exact decimal string (28 significant digits). */
|
|
140
|
+
rateExact: string;
|
|
141
|
+
/** Bolivars per unit for the non-VES side(s) of the conversion. */
|
|
142
|
+
ratesUsed: RateMap;
|
|
143
|
+
/** Requested date, or the date of the latest snapshot. */
|
|
144
|
+
date: string;
|
|
145
|
+
effectiveDate: string;
|
|
146
|
+
carriedForward: boolean;
|
|
147
|
+
/** Decimal places of `result` (`null` = not rounded). */
|
|
148
|
+
decimals: number | null;
|
|
149
|
+
note: string | null;
|
|
150
|
+
source: string;
|
|
151
|
+
summary: string;
|
|
152
|
+
}
|
|
153
|
+
/** Freshness of the published data (`/api/v1/status.json`). */
|
|
154
|
+
interface Status {
|
|
155
|
+
status: string;
|
|
156
|
+
updatedAt: Date | null;
|
|
157
|
+
generatedAt: Date | null;
|
|
158
|
+
date: string | null;
|
|
159
|
+
effectiveDate: string | null;
|
|
160
|
+
/** Hours since `updatedAt` (one decimal), when known. */
|
|
161
|
+
ageHours: number | null;
|
|
162
|
+
/** True when status is not "ok" or the last capture is older than 96 hours. */
|
|
163
|
+
stale: boolean;
|
|
164
|
+
supportedCurrencies: string[];
|
|
165
|
+
currencies: Record<string, boolean>;
|
|
166
|
+
timezone: string | null;
|
|
167
|
+
apiVersion: string | null;
|
|
168
|
+
summary: string;
|
|
169
|
+
raw: StatusDoc;
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
declare const DEFAULT_USER_AGENT = "bcv-today-js/1.0.0 (+https://bcv.today)";
|
|
173
|
+
/** A calendar day: "YYYY-MM-DD" or a Date (its UTC calendar day is used). */
|
|
174
|
+
type DateInput = string | Date;
|
|
175
|
+
/** An amount: a number, a decimal string ("12.50", "1_000") or a bigint. */
|
|
176
|
+
type AmountInput = number | string | bigint;
|
|
177
|
+
interface BCVOptions {
|
|
178
|
+
/** API origin. Default "https://bcv.today". */
|
|
179
|
+
baseUrl?: string;
|
|
180
|
+
/** Per-request timeout in milliseconds (default 10000; 0 disables it). */
|
|
181
|
+
timeoutMs?: number;
|
|
182
|
+
/** How long responses stay in the in-memory cache, in ms (default 300000; 0 disables it). */
|
|
183
|
+
cacheTtlMs?: number;
|
|
184
|
+
/** fetch implementation (default: the global fetch). */
|
|
185
|
+
fetch?: FetchLike;
|
|
186
|
+
/** User-Agent header (default "bcv-today-js/<version> (+https://bcv.today)"); not sent by browsers. */
|
|
187
|
+
userAgent?: string;
|
|
188
|
+
/** Clock used for "today in Caracas" and data age (testing hook). */
|
|
189
|
+
now?: () => Date | number;
|
|
190
|
+
}
|
|
191
|
+
interface HistoryOptions {
|
|
192
|
+
/** Last N calendar days ending on the latest published date (1 to 1830, default 30). */
|
|
193
|
+
days?: number;
|
|
194
|
+
/** Inclusive range start (overrides `days`). */
|
|
195
|
+
start?: DateInput;
|
|
196
|
+
/** Inclusive range end (overrides `days`). */
|
|
197
|
+
end?: DateInput;
|
|
198
|
+
}
|
|
199
|
+
interface ConvertOptions {
|
|
200
|
+
/** Use the rate in effect that day instead of the latest one. */
|
|
201
|
+
date?: DateInput;
|
|
202
|
+
/** Decimal places of `result` (0 to 12, default 2, rounded half-up); `null` keeps full precision. */
|
|
203
|
+
decimals?: number | null;
|
|
204
|
+
}
|
|
205
|
+
/**
|
|
206
|
+
* Client for the free, read-only BCV Today API (https://bcv.today/api/).
|
|
207
|
+
*
|
|
208
|
+
* Rates are bolivars (VES) per one unit of USD, EUR, CNY, TRY or RUB, as
|
|
209
|
+
* published by Banco Central de Venezuela. Unofficial project, not affiliated
|
|
210
|
+
* with the bank.
|
|
211
|
+
*
|
|
212
|
+
* @example
|
|
213
|
+
* const bcv = new BCV();
|
|
214
|
+
* const { rates } = await bcv.latest(); // { USD: 916.6477, ... }
|
|
215
|
+
* const c = await bcv.convert(100, "USD", "VES"); // c.resultText === "91664.77"
|
|
216
|
+
*/
|
|
217
|
+
declare class BCV {
|
|
218
|
+
readonly baseUrl: string;
|
|
219
|
+
readonly timeoutMs: number;
|
|
220
|
+
readonly cacheTtlMs: number;
|
|
221
|
+
readonly userAgent: string;
|
|
222
|
+
private readonly api;
|
|
223
|
+
private readonly cache;
|
|
224
|
+
private readonly clock;
|
|
225
|
+
constructor(options?: BCVOptions);
|
|
226
|
+
/** Forgets every cached response. */
|
|
227
|
+
clearCache(): void;
|
|
228
|
+
private today;
|
|
229
|
+
private latestEntry;
|
|
230
|
+
private dayEntry;
|
|
231
|
+
/** Official rates currently in effect (`/api/v1/rate.json`). */
|
|
232
|
+
latest(): Promise<Rates>;
|
|
233
|
+
/**
|
|
234
|
+
* Rate(s) in effect on a calendar day.
|
|
235
|
+
*
|
|
236
|
+
* BCV does not publish on weekends and holidays: the last published rate stays
|
|
237
|
+
* in effect, so `effectiveDate` may be earlier than `date` and `carriedForward`
|
|
238
|
+
* is then true (with an explanatory `note`). Data starts on 2021-08-02; dates
|
|
239
|
+
* after tomorrow (Caracas time) throw `DateOutOfRange`.
|
|
240
|
+
*
|
|
241
|
+
* @param date "YYYY-MM-DD" or a Date (its UTC calendar day).
|
|
242
|
+
* @param currency Restrict the result to one currency (throws `CurrencyNotAvailable` if it was not published that day).
|
|
243
|
+
*/
|
|
244
|
+
on(date: DateInput, currency?: string): Promise<DayRate>;
|
|
245
|
+
/**
|
|
246
|
+
* Daily series for one currency, oldest first: the last `days` calendar days
|
|
247
|
+
* ending on the latest published date (default 30, max 1830), or an inclusive
|
|
248
|
+
* `start`/`end` range (`days` is then ignored). Uses `/api/v1/history.json`,
|
|
249
|
+
* which keeps the latest 1830 daily entries; ranges are clipped to what it
|
|
250
|
+
* covers and `note` says so.
|
|
251
|
+
*/
|
|
252
|
+
history(currency: string, options?: HistoryOptions): Promise<History>;
|
|
253
|
+
/**
|
|
254
|
+
* Converts `amount` between VES, USD, EUR, CNY, TRY and RUB at the BCV rate.
|
|
255
|
+
*
|
|
256
|
+
* Cross rates go through the bolivar: `amount * vesPerFrom / vesPerTo`. The
|
|
257
|
+
* math is exact decimal (no float drift; divisions keep 28 significant
|
|
258
|
+
* digits, half-up), then `result` is rounded half-up to `decimals` places
|
|
259
|
+
* (default 2; `null` keeps full precision). `resultExact` is the unrounded
|
|
260
|
+
* value as a string. Numbers are read via their shortest decimal string
|
|
261
|
+
* (0.1 is exactly "0.1"); pass a string for amounts beyond float precision.
|
|
262
|
+
*/
|
|
263
|
+
convert(amount: AmountInput, from: string, to: string, options?: ConvertOptions): Promise<Conversion>;
|
|
264
|
+
/** Freshness of the published data (`/api/v1/status.json`). */
|
|
265
|
+
status(): Promise<Status>;
|
|
266
|
+
}
|
|
267
|
+
|
|
268
|
+
/** Base class of every error thrown by `bcv-today`. */
|
|
269
|
+
declare class BCVError extends Error {
|
|
270
|
+
name: string;
|
|
271
|
+
constructor(message: string, options?: {
|
|
272
|
+
cause?: unknown;
|
|
273
|
+
});
|
|
274
|
+
}
|
|
275
|
+
/** An argument passed by the caller is invalid. */
|
|
276
|
+
declare class InvalidArgument extends BCVError {
|
|
277
|
+
name: string;
|
|
278
|
+
}
|
|
279
|
+
/** A date is malformed or not a real calendar day (expected `YYYY-MM-DD`). */
|
|
280
|
+
declare class InvalidDate extends InvalidArgument {
|
|
281
|
+
name: string;
|
|
282
|
+
}
|
|
283
|
+
/** A currency code is not one of VES, USD, EUR, CNY, TRY or RUB (or is misused). */
|
|
284
|
+
declare class InvalidCurrency extends InvalidArgument {
|
|
285
|
+
name: string;
|
|
286
|
+
}
|
|
287
|
+
/** An amount is negative, not finite, too large or not a number (or `decimals` is invalid). */
|
|
288
|
+
declare class InvalidAmount extends InvalidArgument {
|
|
289
|
+
name: string;
|
|
290
|
+
}
|
|
291
|
+
/** The date is valid but no BCV data exists for it (too old, future or not published). */
|
|
292
|
+
declare class DateOutOfRange extends BCVError {
|
|
293
|
+
name: string;
|
|
294
|
+
}
|
|
295
|
+
/** The currency is supported, but the BCV data has no rate for it on that day. */
|
|
296
|
+
declare class CurrencyNotAvailable extends BCVError {
|
|
297
|
+
name: string;
|
|
298
|
+
}
|
|
299
|
+
/** The BCV Today API answered HTTP 404 for a path. */
|
|
300
|
+
declare class NotFound extends BCVError {
|
|
301
|
+
name: string;
|
|
302
|
+
}
|
|
303
|
+
/** The BCV Today API could not be reached or returned an unusable response. */
|
|
304
|
+
declare class UpstreamError extends BCVError {
|
|
305
|
+
name: string;
|
|
306
|
+
/** HTTP status code, when the error came from an HTTP response. */
|
|
307
|
+
readonly status: number | undefined;
|
|
308
|
+
constructor(message: string, status?: number, options?: {
|
|
309
|
+
cause?: unknown;
|
|
310
|
+
});
|
|
311
|
+
}
|
|
312
|
+
|
|
313
|
+
/** Version of the bcv-today package (kept in sync with package.json by a test). */
|
|
314
|
+
declare const VERSION = "1.0.0";
|
|
315
|
+
|
|
316
|
+
export { ANY_CURRENCIES, type AmountInput, type AnyCurrency, BCV, BCVError, type BCVOptions, CURRENCIES, type Conversion, type ConvertOptions, type Currency, CurrencyNotAvailable, DEFAULT_BASE_URL, DEFAULT_USER_AGENT, type DateInput, DateOutOfRange, type DayRate, EARLIEST_SNAPSHOT, type FetchLike, type History, type HistoryOptions, type HistoryPoint, InvalidAmount, InvalidArgument, InvalidCurrency, InvalidDate, MAX_HISTORY_DAYS, NotFound, type RateEntry, type RateMap, type Rates, SOURCE, type Status, type StatusDoc, UNIT, UpstreamError, VERSION };
|