bcchapi 1.0.0 → 1.0.2

package/.eslintignore

@@ -0,0 +1,3 @@
+node_modules
+coverage
+dist

package/.eslintrc.json

@@ -0,0 +1,21 @@
+{
+  "env": {
+    "es2021": true,
+    "node": true
+  },
+  "extends": ["eslint:recommended", "plugin:@typescript-eslint/recommended", "prettier"],
+  "overrides": [],
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": "latest",
+    "sourceType": "module",
+    "project": "./tsconfig.eslint.json"
+  },
+  "plugins": ["@typescript-eslint"],
+  "rules": {
+    "max-classes-per-file": "off",
+    "eol-last": ["error", "always"],
+    "@typescript-eslint/no-unused-vars": "error",
+    "@typescript-eslint/consistent-type-definitions": ["error", "interface"]
+  }
+}

package/.prettierrc.json

@@ -0,0 +1,17 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "arrowParens": "always",
+  "trailingComma": "all",
+  "tabWidth": 2,
+  "printWidth": 100,
+  "endOfLine": "lf",
+  "overrides": [
+    {
+      "files": "*.json",
+      "options": {
+        "trailingComma": "none"
+      }
+    }
+  ]
+}

package/.vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+  "recommendations": ["esbenp.prettier-vscode"]
+}

package/.vscode/settings.json

@@ -0,0 +1,4 @@
+{
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.formatOnSave": true
+}

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2024 Alfredo Irarrazaval
+
+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

@@ -6,7 +6,7 @@ The Central Bank of Chile provides a web service that allows searching and extra
 
 The API currently supports only to functions: `GetSeries` (default) used for retrieveng historical data on a specific series, and `SearchSeries` used for searching series by frequency code (ie: daily, monthly, quearterly or yearly).
 
-For further information on how to use the API directly, please refer to the [official documentation](https://si3.bcentral.cl/estadisticas/Principal1/Web_Services/doc_en.htm).
+For further information on how to use the API directly, please refer to the [official documentation](https://si3.bcentral.cl/estadisticas/Principal1/Web_Services/doc_en.htm). Usage of the API is subject to the restrictions defined in the [Terms and Conditions](https://si3.bcentral.cl/estadisticas/Principal1/Web_Services/index_BDE_TC.htm) of the Statistical Data Base API of the Central Bank of Chile. As of January of 2024, **the API allows up to 5 requests per second per user**.
 
 ## Installation
 
@@ -18,10 +18,10 @@ npm i -S bcchapi
 
 ```javascript
 // ESM
-import Client from 'bcchapi';
+import { Client } from 'bcchapi';
 
 // CommonJS
-const Client = require('bcchapi');
+const { Client } = require('bcchapi');
 ```
 
 ### Authentication
@@ -35,20 +35,20 @@ const client = new Client({
 });
 ```
 
-
 ### GetSeries
 
 Allows you to retrieve historic data series.
 
+- Series Catalogue: [EN](https://si3.bcentral.cl/estadisticas/Principal1/Web_Services/Webservices/series_EN.xlsx) | [ES](https://si3.bcentral.cl/estadisticas/Principal1/Web_Services/Webservices/series.xlsx)
+
 #### Parameters
 
 | name   | type               | required | description                     | example                |
-|--------|--------------------|----------|---------------------------------|------------------------|
+| ------ | ------------------ | -------- | ------------------------------- | ---------------------- |
 | series | `string`           | Yes      | The series identifier           | `'F072.EUR.USD.N.O.D'` |
 | since  | `string` or `Date` | No       | The starting date of the series | `'2020-12-01'`         |
 | until  | `string` or `Date` | No       | The ending date of the series   | `'2020-12-02'`         |
 
-
 > **NOTE**: The API does not implements pagination, so if you need to retrieve a large amount of data, you should use the `since` and `until` parameters to split the request into smaller chunks.
 
 #### Example
@@ -63,7 +63,8 @@ const series = await client.getSeries({
 console.log(series);
 ```
 
-*Output*
+_Output_
+
 ```js
 {
   seriesId: 'F072.EUR.USD.N.O.D',
@@ -82,21 +83,21 @@ Allows you to search for series by their frequency code (ie: daily, weekly, mont
 #### Parameters
 
 | name      | type     | required | description                                                              | example   |
-|-----------|----------|----------|--------------------------------------------------------------------------|-----------|
+| --------- | -------- | -------- | ------------------------------------------------------------------------ | --------- |
 | frequency | `string` | Yes      | The frequency code to search (`DAILY`, `MONTHLY`, `QUARTERLY`, `ANNUAL`) | `'DAILY'` |
 
-
 #### Example
 
 ```js
-import { Frequency } from 'bcchapi';
+import { Frequency } from 'bcchapi';
 
 const result = await client.searchSeries({ frequency: Frequency.DAILY });
 
 console.log(result);
 ```
 
-*Output*
+_Output_
+
 ```js
 [
   ...
@@ -121,4 +122,3 @@ console.log(result);
   ...
 ]
 ```
-

package/dist/client.d.ts

@@ -0,0 +1,50 @@
+import { GetSeriesResponse, SearchSeriesResponse, ApiResponse } from './types';
+export interface ClientConfig {
+    /**
+     * Client username (registered email).
+     */
+    user: string;
+    /**
+     * Client password.
+     */
+    pass: string;
+}
+export declare enum Frequency {
+    Daily = "DAILY",
+    Monthly = "MONTHLY",
+    Quarterly = "QUARTERLY",
+    Annual = "ANNUAL"
+}
+export declare class Client {
+    static apiURL: string;
+    private username;
+    private password;
+    constructor(config: ClientConfig);
+    request(query: Record<string, string>): Promise<ApiResponse>;
+    /**
+     * Fetches the list of observed values for a given series.
+     */
+    getSeries(params: {
+        /**
+         * Series identifier.
+         */
+        series: string;
+        /**
+         * First date of the range to fetch.
+         */
+        since?: string | Date;
+        /**
+         * Last date of the range to fetch.
+         */
+        until?: string | Date;
+    }): Promise<GetSeriesResponse>;
+    /**
+     * Fetches the list of available series by frequency and their metadata.
+     */
+    searchSeries(params: {
+        /**
+         * Frequency for which you want to consult the catalog of available series.
+         */
+        frequency: Frequency;
+    }): Promise<SearchSeriesResponse>;
+}

package/dist/client.js

@@ -0,0 +1,93 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Client = exports.Frequency = void 0;
+const querystring = __importStar(require("node:querystring"));
+const assert = __importStar(require("node:assert/strict"));
+const parsers_1 = require("./helpers/parsers");
+const is_valid_date_1 = __importDefault(require("./helpers/is-valid-date"));
+var Frequency;
+(function (Frequency) {
+    Frequency["Daily"] = "DAILY";
+    Frequency["Monthly"] = "MONTHLY";
+    Frequency["Quarterly"] = "QUARTERLY";
+    Frequency["Annual"] = "ANNUAL";
+})(Frequency || (exports.Frequency = Frequency = {}));
+class Client {
+    static apiURL = 'https://si3.bcentral.cl/SieteRestWS/SieteRestWS.ashx';
+    username;
+    password;
+    constructor(config) {
+        this.username = config.user;
+        this.password = config.pass;
+    }
+    async request(query) {
+        const queryString = querystring.stringify({
+            user: this.username,
+            pass: this.password,
+            ...query,
+        });
+        return (await fetch(`${Client.apiURL}?${queryString}`)).json();
+    }
+    /**
+     * Fetches the list of observed values for a given series.
+     */
+    async getSeries(params) {
+        const { series, since, until } = params;
+        assert.ok(series && typeof series === 'string', 'series must be a non-empty string');
+        const query = {
+            timeseries: series,
+            function: 'GetSeries',
+        };
+        if (since) {
+            assert.ok((0, is_valid_date_1.default)(since), '"since" is not a valid date string or Date object');
+            query.firstdate = typeof since === 'string' ? since : since.toISOString().slice(0, 10);
+        }
+        if (until) {
+            assert.ok((0, is_valid_date_1.default)(until), '"until" is not a valid date string or Date object');
+            query.lastdate = typeof until === 'string' ? until : until.toISOString().slice(0, 10);
+        }
+        if (query.firstdate && query.lastdate) {
+            assert.ok(query.firstdate <= query.lastdate, 'invalid date range');
+        }
+        return this.request(query).then(parsers_1.parseGetSeriesResponse);
+    }
+    /**
+     * Fetches the list of available series by frequency and their metadata.
+     */
+    async searchSeries(params) {
+        const { frequency } = params;
+        assert.ok(frequency && typeof frequency === 'string', 'frequency must be a non-empty string');
+        const query = {
+            frequency,
+            function: 'SearchSeries',
+        };
+        return this.request(query).then(parsers_1.parseSearchSeriesResponse);
+    }
+}
+exports.Client = Client;

package/dist/errors.d.ts

@@ -0,0 +1,21 @@
+import { ErrorResponse } from './types';
+export declare enum ErrorCodes {
+    InvalidCredentials = -5,
+    InvalidFrequency = -1,
+    InvalidSeries = -50,
+    InvalidDateRange = -1,
+    Unknown = -1
+}
+export declare class WebServiceError extends Error {
+    response?: ErrorResponse;
+    constructor(response?: ErrorResponse, message?: string);
+}
+export declare class InvalidFrequencyError extends WebServiceError {
+    constructor(response?: ErrorResponse);
+}
+export declare class InvalidCredentialsError extends WebServiceError {
+    constructor(response?: ErrorResponse);
+}
+export declare class InvalidSeriesError extends WebServiceError {
+    constructor(response?: ErrorResponse);
+}

package/dist/errors.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidSeriesError = exports.InvalidCredentialsError = exports.InvalidFrequencyError = exports.WebServiceError = exports.ErrorCodes = void 0;
+var ErrorCodes;
+(function (ErrorCodes) {
+    ErrorCodes[ErrorCodes["InvalidCredentials"] = -5] = "InvalidCredentials";
+    ErrorCodes[ErrorCodes["InvalidFrequency"] = -1] = "InvalidFrequency";
+    ErrorCodes[ErrorCodes["InvalidSeries"] = -50] = "InvalidSeries";
+    ErrorCodes[ErrorCodes["InvalidDateRange"] = -1] = "InvalidDateRange";
+    ErrorCodes[ErrorCodes["Unknown"] = -1] = "Unknown";
+})(ErrorCodes || (exports.ErrorCodes = ErrorCodes = {}));
+class WebServiceError extends Error {
+    response;
+    constructor(response, message) {
+        super(message || response?.Descripcion || 'Unknown service error');
+        this.response = response;
+    }
+}
+exports.WebServiceError = WebServiceError;
+class InvalidFrequencyError extends WebServiceError {
+    constructor(response) {
+        super(response, 'Invalid frequency code (must be DAILY, MONTHLY, QUARTERLY or ANNUAL)');
+    }
+}
+exports.InvalidFrequencyError = InvalidFrequencyError;
+class InvalidCredentialsError extends WebServiceError {
+    constructor(response) {
+        super(response, 'Invalid username or password');
+    }
+}
+exports.InvalidCredentialsError = InvalidCredentialsError;
+class InvalidSeriesError extends WebServiceError {
+    constructor(response) {
+        super(response, 'Invalid series id');
+    }
+}
+exports.InvalidSeriesError = InvalidSeriesError;

package/dist/helpers/is-valid-date.d.ts

@@ -0,0 +1 @@
+export default function isValidDate(date: unknown): boolean;

package/dist/helpers/is-valid-date.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+function isValidDate(date) {
+    if (typeof date === 'string') {
+        return !Number.isNaN(Date.parse(date));
+    }
+    if (date instanceof Date) {
+        return !Number.isNaN(date.getTime());
+    }
+    return false;
+}
+exports.default = isValidDate;

package/dist/helpers/parsers.d.ts

@@ -0,0 +1,3 @@
+import { ApiResponse, GetSeriesResponse, SearchSeriesResponse } from '../types';
+export declare function parseGetSeriesResponse<T extends ApiResponse>(response: T): GetSeriesResponse;
+export declare function parseSearchSeriesResponse<T extends ApiResponse>(response: T): SearchSeriesResponse;

package/dist/helpers/parsers.js

@@ -0,0 +1,51 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSearchSeriesResponse = exports.parseGetSeriesResponse = void 0;
+const reverse_date_1 = __importDefault(require("./reverse-date"));
+const errors_1 = require("../errors");
+function parseGetSeriesResponse(response) {
+    if (response.Codigo !== 0) {
+        switch (response.Codigo) {
+            case errors_1.ErrorCodes.InvalidCredentials:
+                throw new errors_1.InvalidCredentialsError();
+            case errors_1.ErrorCodes.InvalidSeries:
+                throw new errors_1.InvalidSeriesError();
+            default:
+                throw new errors_1.WebServiceError(response);
+        }
+    }
+    return {
+        seriesId: response.Series.seriesId || '',
+        description: response.Series.descripIng || '',
+        data: (response.Series.Obs || []).map((obs) => ({
+            date: (0, reverse_date_1.default)(obs.indexDateString),
+            value: parseFloat(obs.value),
+        })),
+    };
+}
+exports.parseGetSeriesResponse = parseGetSeriesResponse;
+function parseSearchSeriesResponse(response) {
+    if (response.Codigo !== 0) {
+        switch (response.Codigo) {
+            case errors_1.ErrorCodes.InvalidCredentials:
+                throw new errors_1.InvalidCredentialsError();
+            case errors_1.ErrorCodes.InvalidFrequency:
+                throw new errors_1.InvalidFrequencyError();
+            default:
+                throw new errors_1.WebServiceError(response);
+        }
+    }
+    return response.SeriesInfos.map((series) => ({
+        seriesId: series.seriesId,
+        frequency: series.frequencyCode,
+        title: series.englishTitle,
+        firstObservedAt: (0, reverse_date_1.default)(series.firstObservation),
+        lastObservedAt: (0, reverse_date_1.default)(series.lastObservation),
+        updatedAt: (0, reverse_date_1.default)(series.updatedAt),
+        createdAt: (0, reverse_date_1.default)(series.createdAt),
+    }));
+}
+exports.parseSearchSeriesResponse = parseSearchSeriesResponse;

package/dist/helpers/reverse-date.d.ts

@@ -0,0 +1 @@
+export default function reverseDate(date: string): string;

package/dist/helpers/reverse-date.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+function reverseDate(date) {
+    return date.split('-').reverse().join('-');
+}
+exports.default = reverseDate;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { Client, ClientConfig, Frequency } from './client';
+export { ApiResponse, ErrorResponse, GetSeriesResponse, SearchSeriesResponse } from './types';
+export { WebServiceError, InvalidCredentialsError, InvalidFrequencyError, InvalidSeriesError, } from './errors';

package/dist/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidSeriesError = exports.InvalidFrequencyError = exports.InvalidCredentialsError = exports.WebServiceError = exports.Frequency = exports.Client = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "Client", { enumerable: true, get: function () { return client_1.Client; } });
+Object.defineProperty(exports, "Frequency", { enumerable: true, get: function () { return client_1.Frequency; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "WebServiceError", { enumerable: true, get: function () { return errors_1.WebServiceError; } });
+Object.defineProperty(exports, "InvalidCredentialsError", { enumerable: true, get: function () { return errors_1.InvalidCredentialsError; } });
+Object.defineProperty(exports, "InvalidFrequencyError", { enumerable: true, get: function () { return errors_1.InvalidFrequencyError; } });
+Object.defineProperty(exports, "InvalidSeriesError", { enumerable: true, get: function () { return errors_1.InvalidSeriesError; } });

package/dist/types.d.ts

@@ -0,0 +1,109 @@
+interface SeriesValue {
+    /**
+     * Series observed date in DD-MM-YYYY format.
+     */
+    indexDateString: string;
+    /**
+     * Series observed value.
+     */
+    value: string;
+    /**
+     * Series observed value status code (ND = no data recorded).
+     */
+    statusCode: 'OK' | 'ND';
+}
+interface SeriesHistory {
+    /**
+     * Series identifier.
+     */
+    seriesId: string;
+    /**
+     * Series name in Spanish.
+     */
+    descripEsp: string;
+    /**
+     * Series name in English.
+     */
+    descripIng: string;
+    /**
+     * List of series observed values.
+     */
+    Obs: SeriesValue[];
+}
+type NullSeries = {
+    [key in keyof SeriesHistory]: null;
+};
+interface SeriesMetadata {
+    /**
+     * Series identifier.
+     */
+    seriesId: string;
+    /**
+     * Series frequency.
+     */
+    frequencyCode: string;
+    /**
+     * Series name in Spanish.
+     */
+    spanishTitle: string;
+    /**
+     * Series name in English.
+     */
+    englishTitle: string;
+    /**
+     * Date of first observation in DD-MM-YYYY format.
+     */
+    firstObservation: string;
+    /**
+     * Date of last observation in DD-MM-YYYY format.
+     */
+    lastObservation: string;
+    /**
+     * Date of last update in DD-MM-YYYY format.
+     */
+    updatedAt: string;
+    /**
+     * Date of creation in DD-MM-YYYY format.
+     */
+    createdAt: string;
+}
+export interface ApiResponse {
+    /**
+     * Response status code.
+     */
+    Codigo: number;
+    /**
+     * Response status message.
+     */
+    Descripcion: string;
+    /**
+     * Series historic information.
+     */
+    Series: SeriesHistory | NullSeries;
+    /**
+     * Series metadata information.
+     */
+    SeriesInfos: SeriesMetadata[];
+}
+export interface ErrorResponse extends ApiResponse {
+    Series: NullSeries;
+    SeriesInfos: never[];
+}
+export interface GetSeriesResponse {
+    seriesId: string;
+    description: string;
+    data: ReadonlyArray<{
+        date: string;
+        value: number;
+    }>;
+}
+export type SearchSeriesResponse = ReadonlyArray<{
+    seriesId: string;
+    frequency: string;
+    title: string;
+    firstObservedAt: string;
+    lastObservedAt: string;
+    updatedAt: string;
+    createdAt: string;
+}>;
+export {};

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "bcchapi",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "API para acceder al Web Service del Banco Central de Chile.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
     "build": "rimraf dist && tsc",
     "test": "vitest",
-    "coverage": "vitest --coverage"
+    "coverage": "vitest --coverage",
+    "lint": "eslint --ignore-path .eslintignore --ext .ts",
+    "format": "prettier --ignore-path .gitignore --write \"**/*.+(js|ts|json)\""
   },
   "repository": {
     "type": "git",
@@ -28,7 +30,13 @@
   "devDependencies": {
     "@tsconfig/node20": "^20.1.2",
     "@types/node": "^20.11.5",
+    "@typescript-eslint/eslint-plugin": "^6.19.0",
+    "@typescript-eslint/parser": "^6.19.0",
     "@vitest/coverage-v8": "^1.2.1",
+    "eslint": "^8.56.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-import": "^2.29.1",
+    "prettier": "^3.2.4",
     "rimraf": "^5.0.5",
     "ts-node": "^10.9.2",
     "typescript": "^5.3.3",