@kabeep/forex
Version:
A JavaScript foreign exchange library via fawazahmed0's API
443 lines (436 loc) • 10.9 kB
TypeScript
/**
* @source {@link https://github.com/fawazahmed0/exchange-api}
*/
declare const BASE_URL = "https://cdn.jsdelivr.net/npm/@fawazahmed0/currency-api";
/**
* @source {@link https://github.com/fawazahmed0/exchange-api}
*/
declare const BASE_URL_VERSION = "v1";
/**
* @source {@link https://en.wikipedia.org/wiki/ISO_4217#Active_codes_(list_one)}
*/
declare const LOCALE_CURRENCY: {
AD: string;
AE: string;
AF: string;
AG: string;
AI: string;
AL: string;
AM: string;
AO: string;
AR: string;
AS: string;
AT: string;
AU: string;
AW: string;
AX: string;
AZ: string;
BA: string;
BB: string;
BD: string;
BE: string;
BF: string;
BG: string;
BH: string;
BI: string;
BJ: string;
BL: string;
BM: string;
BN: string;
BO: string;
BQ: string;
BR: string;
BS: string;
BT: string;
BV: string;
BW: string;
BY: string;
BZ: string;
CA: string;
CC: string;
CD: string;
CF: string;
CG: string;
CH: string;
CI: string;
CK: string;
CL: string;
CM: string;
CN: string;
CO: string;
CR: string;
CU: string;
CV: string;
CW: string;
CX: string;
CY: string;
CZ: string;
DE: string;
DJ: string;
DK: string;
DM: string;
DO: string;
DZ: string;
EC: string;
EE: string;
EG: string;
EH: string;
ER: string;
ES: string;
ET: string;
FI: string;
FJ: string;
FK: string;
FM: string;
FO: string;
FR: string;
GA: string;
GB: string;
GD: string;
GE: string;
GF: string;
GG: string;
GH: string;
GI: string;
GL: string;
GM: string;
GN: string;
GP: string;
GQ: string;
GR: string;
GS: string;
GT: string;
GU: string;
GW: string;
GY: string;
HK: string;
HM: string;
HN: string;
HR: string;
HT: string;
HU: string;
ID: string;
IE: string;
IL: string;
IM: string;
IN: string;
IO: string;
IQ: string;
IR: string;
IS: string;
IT: string;
JE: string;
JM: string;
JO: string;
JP: string;
KE: string;
KG: string;
KH: string;
KI: string;
KM: string;
KN: string;
KP: string;
KR: string;
KW: string;
KY: string;
KZ: string;
LA: string;
LB: string;
LC: string;
LI: string;
LK: string;
LR: string;
LS: string;
LT: string;
LU: string;
LV: string;
LY: string;
MA: string;
MC: string;
MD: string;
ME: string;
MF: string;
MG: string;
MH: string;
MK: string;
ML: string;
MM: string;
MN: string;
MO: string;
MP: string;
MQ: string;
MR: string;
MS: string;
MT: string;
MU: string;
MV: string;
MW: string;
MX: string;
MY: string;
MZ: string;
NA: string;
NC: string;
NE: string;
NF: string;
NG: string;
NI: string;
NL: string;
NO: string;
NP: string;
NR: string;
NU: string;
NZ: string;
OM: string;
PA: string;
PE: string;
PF: string;
PG: string;
PH: string;
PK: string;
PL: string;
PM: string;
PN: string;
PR: string;
PS: string;
PT: string;
PW: string;
PY: string;
QA: string;
RE: string;
RO: string;
RS: string;
RU: string;
RW: string;
SA: string;
SB: string;
SC: string;
SD: string;
SE: string;
SG: string;
SH: string;
SI: string;
SJ: string;
SK: string;
SL: string;
SM: string;
SN: string;
SO: string;
SR: string;
ST: string;
SV: string;
SX: string;
SY: string;
SZ: string;
TC: string;
TD: string;
TF: string;
TG: string;
TH: string;
TJ: string;
TK: string;
TL: string;
TM: string;
TN: string;
TO: string;
TR: string;
TT: string;
TV: string;
TW: string;
TZ: string;
UA: string;
UG: string;
UM: string;
US: string;
UY: string;
UZ: string;
VA: string;
VC: string;
VE: string;
VG: string;
VI: string;
VN: string;
VU: string;
WF: string;
WS: string;
YE: string;
YT: string;
ZA: string;
ZM: string;
ZW: string;
};
/**
* @source {@link https://en.wikipedia.org/wiki/ISO_4217#Non-standard_codes}
*/
declare const NON_STANDARD_CODES: {
BDS: string;
CNT: string;
NIS: string;
NTD: string;
STG: string;
RMB: string;
};
interface HttpRequestOptions {
timeout?: number;
headers?: HeadersInit;
}
interface HttpResponse<T> {
code: number;
message: string;
data?: T;
}
declare class HttpRequest {
private static TIMEOUT;
private static REQUEST_HEADER;
protected readonly timeout: number;
protected readonly headers: HeadersInit;
constructor(options?: HttpRequestOptions);
protected _fetch<T = unknown>(options: Request): Promise<HttpResponse<T>>;
private createResponse;
}
declare class HttpClient extends HttpRequest {
constructor(options?: HttpRequestOptions);
protected get<T>(url: string, options?: RequestInit): Promise<HttpResponse<T>>;
}
interface ForexClientOptions extends HttpRequestOptions {
baseCurrency?: string;
minified?: boolean;
}
interface AvailableCurrency {
code: string;
name: string;
}
type OriginalExchangeRates = {
[key: string]: Record<string, number>;
} & {
date: string;
};
interface ExchangeRate {
code: string;
rate: number;
}
/**
* A client to interact with the Forex API for fetching currency rates and conversion data
*/
declare class ForexClient extends HttpClient {
private static MINIFIED;
private readonly options;
/**
* Creates a new instance of ForexClient
* @param {ForexClientOptions} [options={}] - The options for configuring the client
* @param {string} options.baseCurrency - The base currency code
* @param {boolean} options.minified - Minified JSON format
* @param {number} options.timeout - Request timeout (milliseconds)
* @param {HeadersInit} options.headers - Request header
*/
constructor(options?: ForexClientOptions);
/**
* Fetches the list of available currencies
* @param {Date | "latest"} [date="latest"] - The date for fetching currencies, or `"latest"` for the most recent
* @param {RequestInit} [options={}] - Additional request options
* @returns {Promise<HttpResponse<AvailableCurrency[]>>} A list of available currencies
*
* @example
* // => {
* // code: 200,
* // message: 'OK',
* // data: [
* // { code: 'eur', name: 'Euro' },
* // { code: 'usd', name: 'US Dollar' },
* // { code: 'cny', name: 'Chinese Yuan Renminbi' },
* // ... More items
* // ]
* // }
* new ForexClient().getCurrencies('latest');
*/
getCurrencies(date?: Date | 'latest', options?: RequestInit): Promise<HttpResponse<AvailableCurrency[]>>;
/**
* Fetches the exchange rates for a specific currency
* @param {string | undefined} [code=this.options.baseCurrency] - The currency code or locale code to get rates for
* @param {Date | "latest"} [date="latest"] - The date for the rates, or `'latest'` for the most recent
* @param {RequestInit} [options={}] - Additional request options
* @returns {Promise<HttpResponse<ExchangeRate[]>>} A list of exchange rates
*
* @example
* // => {
* // code: 200,
* // message: 'OK',
* // data: [
* // { code: 'eur', rate: 100_000 },
* // { code: 'usd', rate: 100_000 },
* // { code: 'cny', rate: 100_000 },
* // ... More items
* // ]
* // }
* new ForexClient().getRates('BTC');
*/
getRates(code?: string | undefined, date?: Date | 'latest', options?: RequestInit): Promise<HttpResponse<ExchangeRate[]>>;
/**
* Fetches the exchange rate between two currencies
* @param {string | undefined} [baseCode=this.options.baseCurrency] - The base currency code or locale code
* @param {string} destCode - The destination currency code or locale code
* @param {Date | "latest"} [date="latest"] - The date for the rate, or `'latest'` for the most recent
* @param {RequestInit} [options={}] - Additional request options
* @returns {Promise<HttpResponse<number>>} The exchange rate
*
* @example
* // => {
* // code: 200,
* // message: 'OK',
* // data: 100_000
* // }
* new ForexClient().getRate('BTC', 'USD');
*/
getRate(baseCode?: string | undefined, destCode?: string, date?: Date | 'latest', options?: RequestInit): Promise<HttpResponse<number>>;
/**
* Get a valid currency code based on locale
* @param {string} localeCode - The locale code to get currency code for
* @returns {string} The corresponding currency code
*
* @example
* // => 'USD'
* new ForexClient().getCode('US');
*
* @example
* // => 'CNH'
* new ForexClient().getCode('HK');
*
* @example
* // => 'CNY'
* new ForexClient().getCode('RMB');
*/
getCode(localeCode: string): string;
/**
* Converts an amount from one currency to another
* @param {string | undefined} [baseCode=this.options.baseCurrency] - The base currency code or locale code
* @param {string} destCode - The destination currency code or locale code
* @param {number} [amount=0] - The amount to convert
* @param {Date | "latest"} [date="latest"] - The date for the conversion rate, or `'latest'` for the most recent
* @param {RequestInit} [options={}] - Additional request options
* @returns {Promise<HttpResponse<number>>} The converted amount
*
* @example
* // => {
* // code: 200,
* // message: 'OK',
* // data: 100_000
* // }
* new ForexClient().convert('BTC', 'USD', 1);
*
* @example
* // => {
* // code: 200,
* // message: 'OK',
* // data: 7.27
* // }
* new ForexClient().convert('US', 'HK', 1);
*/
convert(baseCode?: string | undefined, destCode?: string, amount?: number | string, date?: Date | 'latest', options?: RequestInit): Promise<HttpResponse<number>>;
private composeDataList;
private validCurrencyCode;
private getApiUrl;
private formatDate;
private isValidDate;
private isDate;
private paddedDate;
}
export { type AvailableCurrency, BASE_URL, BASE_URL_VERSION, type ExchangeRate, ForexClient, type ForexClientOptions, type HttpRequestOptions, type HttpResponse, LOCALE_CURRENCY, NON_STANDARD_CODES, type OriginalExchangeRates };