bcchapi 1.0.0

package/README.md

@@ -0,0 +1,124 @@
+# BCCHAPI
+
+[Statistical Data Base API](https://si3.bcentral.cl/Siete/es/Siete/API) client of the Central Bank of Chile.
+
+The Central Bank of Chile provides a web service that allows searching and extracting economic information contained in its Statistical Data Base (BDE). The records are displayed in a format useful for developers and analysts who wish to automate their query processes.
+
+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).
+
+## Installation
+
+```
+npm i -S bcchapi
+```
+
+## Usage
+
+```javascript
+// ESM
+import Client from 'bcchapi';
+
+// CommonJS
+const Client = require('bcchapi');
+```
+
+### Authentication
+
+To authenticate the API calls you first need to register at the [Statistical Data Base Website](https://si3.bcentral.cl/Siete/es/Siete/API) of the Central Bank of Chile, login and activate your credentials.
+
+```js
+const client = new Client({
+  user: 'jdoe@example.com',
+  pass: 'secret',
+});
+```
+
+
+### GetSeries
+
+Allows you to retrieve historic data series.
+
+#### 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
+
+```js
+const series = await client.getSeries({
+  series: 'F072.EUR.USD.N.O.D',
+  since: '2020-12-01',
+  until: '2020-12-02',
+});
+
+console.log(series);
+```
+
+*Output*
+```js
+{
+  seriesId: 'F072.EUR.USD.N.O.D',
+  description: 'Euro per US dollar',
+  data: [
+    { date: '2020-12-01', value: 0.8373 },
+    { date: '2020-12-02', value: 0.8304 }
+  ]
+}
+```
+
+### SearchSeries
+
+Allows you to search for series by their frequency code (ie: daily, weekly, monthly, yearly).
+
+#### 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';
+
+const result = await client.searchSeries({ frequency: Frequency.DAILY });
+
+console.log(result);
+```
+
+*Output*
+```js
+[
+  ...
+  {
+    seriesId: 'F021.AHP.STO.N.CLP.0.D',
+    frequency: 'DAILY',
+    title: 'Time savings deposits, including those for housing',
+    firstObservedAt: '2011-01-03',
+    lastObservedAt: '2023-12-29',
+    updatedAt: '2024-01-08',
+    createdAt: '2024-01-08'
+  },
+  {
+    seriesId: 'F021.BMO.STO.N.CLP.0.D',
+    frequency: 'DAILY',
+    title: 'Monetary base ',
+    firstObservedAt: '2011-01-03',
+    lastObservedAt: '2023-12-29',
+    updatedAt: '2024-01-08',
+    createdAt: '2024-01-08'
+  },
+  ...
+]
+```
+

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "bcchapi",
+  "version": "1.0.0",
+  "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"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/airarrazaval/bcchapi.git"
+  },
+  "keywords": [
+    "node",
+    "javascript",
+    "typescript",
+    "bcchapi"
+  ],
+  "author": "Alfredo Irarrazaval",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/airarrazaval/bcchapi/issues"
+  },
+  "homepage": "https://github.com/airarrazaval/bcchapi#readme",
+  "devDependencies": {
+    "@tsconfig/node20": "^20.1.2",
+    "@types/node": "^20.11.5",
+    "@vitest/coverage-v8": "^1.2.1",
+    "rimraf": "^5.0.5",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.3",
+    "vitest": "^1.2.1"
+  },
+  "engines": {
+    "node": ">=18.19.0",
+    "npm": ">=10.2.3"
+  },
+  "volta": {
+    "node": "20.11.0"
+  }
+}

package/src/client.ts

@@ -0,0 +1,111 @@
+import * as querystring from 'node:querystring';
+import * as assert from 'node:assert/strict';
+import {
+  GetSeriesResponse,
+  SearchSeriesResponse,
+  Frequency,
+  parseGetSeriesResponse,
+  parseSearchSeriesResponse,
+  ApiResponse,
+} from './response';
+import { isValidDate } from './helpers';
+
+export type ClientConfig = {
+  /**
+   * Client username (registered email).
+   */
+  user: string;
+  /**
+   * Client password.
+   */
+  pass: string;
+};
+
+export type GetSeriesInput = {
+  /**
+   * Series identifier.
+   */
+  series: string;
+  /**
+   * First date of the range to fetch.
+   */
+  since?: string | Date;
+  /**
+   * Last date of the range to fetch.
+   */
+  until?: string | Date;
+};
+
+export type SearchSeriesInput = {
+  /**
+   * Frequency for which you want to consult the catalog of available series.
+   */
+  frequency: Frequency;
+};
+
+export class Client {
+  static apiURL = 'https://si3.bcentral.cl/SieteRestWS/SieteRestWS.ashx';
+  private username: string;
+  private password: string;
+
+  constructor(config: ClientConfig) {
+    this.username = config.user;
+    this.password = config.pass;
+  }
+
+  async request(params: Record<string, string>): Promise<ApiResponse> {
+    const query = querystring.stringify({
+      user: this.username,
+      pass: this.password,
+      ...params,
+    });
+
+    return (await fetch(`${Client.apiURL}?${query}`)).json() as Promise<ApiResponse>;
+  }
+
+  /**
+   * Fetches the list of observed values for a given series.
+   */
+  async getSeries(input: GetSeriesInput): Promise<GetSeriesResponse> {
+    const { series, since, until } = input;
+
+    assert.ok(series && typeof series === 'string', 'series must be a non-empty string');
+
+    const params: Record<string, string> = {
+      timeseries: series,
+      function: 'GetSeries',
+    };
+
+    if (since) {
+      assert.ok(isValidDate(since), '"since" is not a valid date string or Date object');
+      params.firstdate = typeof since === 'string' ? since : since.toISOString().slice(0, 10);
+    }
+
+    if (until) {
+      assert.ok(isValidDate(until), '"until" is not a valid date string or Date object');
+      params.lastdate = typeof until === 'string' ? until : until.toISOString().slice(0, 10);
+    }
+
+    if (params.firstdate && params.lastdate) {
+      assert.ok(params.firstdate <= params.lastdate, 'invalid date range');
+    }
+
+    return this.request(params).then(parseGetSeriesResponse);
+  }
+
+  /**
+   * Fetches the list of available series by frequency and their metadata.
+   */
+  async searchSeries(input: SearchSeriesInput): Promise<SearchSeriesResponse> {
+    const { frequency } = input;
+  
+    assert.ok(frequency && typeof frequency === 'string', 'frequency must be a non-empty string');
+    
+    const params: Record<string, string> = {
+      frequency,
+      function: 'SearchSeries',
+    };
+
+    return this.request(params).then(parseSearchSeriesResponse);
+  }
+}

package/src/errors.ts

@@ -0,0 +1,36 @@
+import { ErrorResponse } from './response';
+
+export enum ErrorCodes {
+  InvalidCredentials = -5,
+  InvalidFrequency = -1,
+  InvalidSeries = -50,
+  InvalidDateRange = -1,
+  Unknown = -1,
+}
+
+export class WebServiceError extends Error {
+  response?: ErrorResponse;
+
+  constructor(response?: ErrorResponse, message?: string) {
+    super(message || response?.Descripcion || 'Unknown service error');
+    this.response = response;
+  }
+}
+
+export class InvalidFrequencyError extends WebServiceError {
+  constructor(response?: ErrorResponse) {
+    super(response, 'Invalid frequency code (must be DAILY, MONTHLY, QUARTERLY or ANNUAL)');
+  }
+}
+
+export class InvalidCredentialsError extends WebServiceError {
+  constructor(response?: ErrorResponse) {
+    super(response, 'Invalid username or password');
+  }
+}
+
+export class InvalidSeriesError extends WebServiceError {
+  constructor(response?: ErrorResponse) {
+    super(response, 'Invalid series id');
+  }
+}

package/src/helpers.ts

@@ -0,0 +1,13 @@
+export function reverseDate(date: string): string {
+  return date.split('-').reverse().join('-');
+}
+
+export function isValidDate(date: unknown): boolean {
+  if (typeof date === 'string') {
+    return !isNaN(Date.parse(date));
+  }
+  if (date instanceof Date) {
+    return !isNaN(date.getTime());
+  }
+  return false;
+}

package/src/index.ts

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

package/src/response.ts

@@ -0,0 +1,175 @@
+import {
+  ErrorCodes,
+  InvalidFrequencyError,
+  InvalidCredentialsError,
+  InvalidSeriesError,
+  WebServiceError,
+} from './errors';
+import { reverseDate } from './helpers';
+
+export enum Frequency {
+  Daily = 'DAILY',
+  Monthly = 'MONTHLY',
+  Quarterly = 'QUARTERLY',
+  Annual = 'ANNUAL',
+}
+
+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[];
+}
+
+interface SeriesMetadata {
+  /**
+   * Series identifier.
+   */
+  seriesId: string;
+  /**
+   * Series frequency (DAILY, MONTHLY, QUARTERLY, ANNUAL).
+   */
+  frequencyCode: Frequency;
+  /**
+   * 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 | {
+    [key in keyof SeriesHistory]: null;
+  };
+  /**
+   * Series metadata information.
+   */
+  SeriesInfos: SeriesMetadata[];
+}
+
+export interface ErrorResponse extends ApiResponse {
+  Series: {
+    [key in keyof SeriesHistory]: null;
+  };
+  SeriesInfos: never[];
+}
+
+export type GetSeriesResponse = {
+  seriesId: string;
+  description: string;
+  data: ReadonlyArray<{ date: string; value: number; }>;
+}
+
+export type SearchSeriesResponse = ReadonlyArray<{
+  seriesId: string;
+  frequency: Frequency;
+  title: string;
+  firstObservedAt: string;
+  lastObservedAt: string;
+  updatedAt: string;
+  createdAt: string;
+}>;
+
+export function parseGetSeriesResponse<T extends ApiResponse>(response: T): GetSeriesResponse {
+  if (response.Codigo !== 0) {
+    switch (response.Codigo) {
+      case ErrorCodes.InvalidCredentials:
+        throw new InvalidCredentialsError();
+      case ErrorCodes.InvalidSeries:
+        throw new InvalidSeriesError();
+      default:
+        throw new WebServiceError(response as ApiResponse as ErrorResponse);
+    }
+  }
+
+  return {
+    seriesId: response.Series.seriesId || '',
+    description: response.Series.descripIng || '',
+    data: (response.Series.Obs || []).map((obs) => ({
+      date: reverseDate(obs.indexDateString),
+      value: parseFloat(obs.value),
+    })),
+  };
+}
+
+export function parseSearchSeriesResponse<T extends ApiResponse>(response: T): SearchSeriesResponse {
+  if (response.Codigo !== 0) {
+    switch (response.Codigo) {
+      case ErrorCodes.InvalidCredentials:
+        throw new InvalidCredentialsError();
+      case ErrorCodes.InvalidFrequency:
+        throw new InvalidFrequencyError();
+      default:
+        throw new WebServiceError(response as ApiResponse as ErrorResponse);
+    }
+  }
+  console.log(response);
+
+  return response.SeriesInfos.map((series) => ({
+    seriesId: series.seriesId,
+    frequency: series.frequencyCode,
+    title: series.englishTitle,
+    firstObservedAt: reverseDate(series.firstObservation),
+    lastObservedAt: reverseDate(series.lastObservation),
+    updatedAt: reverseDate(series.updatedAt),
+    createdAt: reverseDate(series.createdAt),
+  }));
+}

package/test/client.test.ts

@@ -0,0 +1,196 @@
+import { expect, describe, it, vi, afterEach, afterAll, beforeEach } from 'vitest';
+import { Client } from '../src';
+import {
+  Frequency,
+  InvalidCredentialsError,
+  InvalidSeriesError,
+  InvalidFrequencyError,
+} from '../src';
+import fetchMock from './mocks/fetch.mock';
+import fixtures from './fixtures';
+import { reverseDate } from '../src/helpers';
+
+// global.fetch = vi.fn().mockImplementation(fetchMock);
+const fetchSpy = vi.spyOn(global, 'fetch').mockImplementation(fetchMock);
+
+describe('Client', () => {
+  const client = new Client({
+    user: 'test',
+    pass: 'test',
+  });
+
+  const invalidClient = new Client({
+    user: '',
+    pass: '',
+  });
+  
+  it('should create a Client instance', () => {
+    expect(client).toBeInstanceOf(Client);
+  });
+
+  describe('getSeries', () => {
+    beforeEach(() => {
+      fetchSpy.mockImplementation(fetchMock);
+    });
+    afterEach(() => {
+      fetchSpy.mockReset();
+    });
+
+    it('should throw an error if series is not a non-empty string', async () => {
+      await expect(client.getSeries({
+        series: undefined as unknown as string,
+      })).rejects.toThrow('series must be a non-empty string');
+      await expect(client.getSeries({
+        series: '',
+      })).rejects.toThrow('series must be a non-empty string');
+
+      expect(fetchSpy).not.toHaveBeenCalled();
+    });
+
+    it('should throw an error if date range is invalid', async () => {
+      await expect(client.getSeries({
+        series: 'TEST',
+        since: 'invalid',
+      })).rejects.toThrow('"since" is not a valid date string or Date object');
+      await expect(client.getSeries({
+        series: 'TEST',
+        since: new Date('invalid'),
+      })).rejects.toThrow('"since" is not a valid date string or Date object');
+
+      await expect(client.getSeries({
+        series: 'TEST',
+        until: 'invalid',
+      })).rejects.toThrow('"until" is not a valid date string or Date object');
+      await expect(client.getSeries({
+        series: 'TEST',
+        until: new Date('invalid'),
+      })).rejects.toThrow('"until" is not a valid date string or Date object');
+
+      await expect(client.getSeries({
+        series: 'TEST',
+        since: new Date(2020, 0, 1),
+        until: new Date(2000, 0, 1),
+      })).rejects.toThrow('invalid date range');
+
+      expect(fetchSpy).not.toHaveBeenCalled();
+    });
+
+    it('should throw error if credentials are invalid', async () => {
+      await expect(invalidClient.getSeries({ series: 'TEST' })).rejects.toThrow(InvalidCredentialsError);
+      expect(fetchSpy).toHaveBeenCalledTimes(1);
+    });
+
+    it('should throw error if series does not exist', async () => {
+      await expect(client.getSeries({ series: 'invalid' })).rejects.toThrow(InvalidSeriesError);
+      expect(fetchSpy).toHaveBeenCalledTimes(1);
+    });
+
+    it('should return the series history information', async () => {
+      const series = await client.getSeries({ series: 'TEST' });
+
+      expect(fetchSpy).toHaveBeenCalledTimes(1);
+      
+      expect(series).toBeDefined();
+      expect(series.seriesId).toBe('TEST');
+      expect(series.description).toBe('Test');
+      expect(series.data).toBeInstanceOf(Array);
+      expect(series.data).toHaveLength(15);
+      
+      for (let i = 0; i < series.data.length; i += 1) {
+        expect(reverseDate(series.data[i].date)).toBe(fixtures.response.getSeriesSuccess.Series.Obs[i].indexDateString);
+        expect(series.data[i].value.toFixed(2)).toBe(fixtures.response.getSeriesSuccess.Series.Obs[i].value);
+
+        if (Number.isNaN(series.data[i].value)) {
+          expect(fixtures.response.getSeriesSuccess.Series.Obs[i].statusCode).toBe('ND');
+        }
+      }
+    });
+
+    it('should filter the series history by date range', async () => {
+      const series = await client.getSeries({
+        series: 'TEST',
+        until: '2020-12-05',
+      });
+      
+      expect(fetchSpy).toHaveBeenCalledTimes(1);
+
+      expect(series).toBeDefined();
+      expect(series.seriesId).toBe('TEST');
+      expect(series.description).toBe('Test');
+      expect(series.data).toBeInstanceOf(Array);
+      expect(series.data).toHaveLength(5);
+      
+      for (let i = 0; i < series.data.length; i += 1) {
+        expect(reverseDate(series.data[i].date)).toBe(fixtures.response.getSeriesSuccess.Series.Obs[i].indexDateString);
+        expect(series.data[i].value.toFixed(2)).toBe(fixtures.response.getSeriesSuccess.Series.Obs[i].value);
+
+        if (Number.isNaN(series.data[i].value)) {
+          expect(fixtures.response.getSeriesSuccess.Series.Obs[i].statusCode).toBe('ND');
+        }
+      }
+    });
+
+    it('should return empty results if series has no data', async () => {
+      const series = await client.getSeries({
+        series: 'TEST',
+        since: '2020-12-16',
+      });
+
+      expect(fetchSpy).toHaveBeenCalledTimes(1);
+      
+      expect(series).toBeDefined();
+      expect(series.seriesId).toBe('TEST');
+      expect(series.description).toBe('Test');
+      expect(series.data).toBeInstanceOf(Array);
+      expect(series.data).toHaveLength(0);
+    });
+
+  });
+
+  describe('searchSeries', () => {
+    beforeEach(() => {
+      fetchSpy.mockImplementation(fetchMock);
+    });
+    afterEach(() => {
+      fetchSpy.mockReset();
+    });
+
+    it('should throw an error if frequency is not a non-empty string', async () => {
+      await expect(client.searchSeries({
+        frequency: undefined as unknown as Frequency,
+      })).rejects.toThrow('frequency must be a non-empty string');
+      await expect(client.searchSeries({
+        frequency: '' as Frequency,
+      })).rejects.toThrow('frequency must be a non-empty string');
+
+      expect(fetchSpy).not.toHaveBeenCalled();
+    });
+
+    it('should throw error if credentials are invalid', async () => {
+      await expect(invalidClient.searchSeries({
+        frequency: Frequency.Daily,
+      })).rejects.toThrow(InvalidCredentialsError);
+
+      expect(fetchSpy).toHaveBeenCalledTimes(1);
+    });
+
+    it('should throw error if frequency is invalid', async () => {
+      await expect(client.searchSeries({
+        frequency: 'invalid' as Frequency,
+      })).rejects.toThrow(InvalidFrequencyError);
+
+      expect(fetchSpy).toHaveBeenCalledTimes(1);
+    });
+
+    it('should return the series metadata information', async () => {
+      const series = await client.searchSeries({
+        frequency: Frequency.Daily,
+      });
+
+      expect(fetchSpy).toHaveBeenCalledTimes(1);
+      
+      expect(series).toBeInstanceOf(Array);
+      expect(series).toHaveLength(1);
+    });
+  });
+});

package/test/fixtures/index.ts

@@ -0,0 +1,15 @@
+import getSeriesSuccess from './responses/getseries.success.json';
+import getSeriesInvalid from './responses/getseries.invalid.json';
+import searchSeriesSuccess from './responses/searchseries.success.json';
+import searchSeriesInvalid from './responses/searchseries.invalid.json';
+import credentialsInvalid from './responses/credentials.invalid.json';
+
+export default {
+  response: {
+    credentialsInvalid,
+    getSeriesInvalid,
+    getSeriesSuccess,
+    searchSeriesInvalid,
+    searchSeriesSuccess,
+  },
+};

package/test/fixtures/responses/credentials.invalid.json

@@ -0,0 +1,11 @@
+{
+  "Codigo": -5,
+  "Descripcion": "Invalid username or password",
+  "Series": {
+    "descripEsp": null,
+    "descripIng": null,
+    "seriesId": null,
+    "Obs": null
+  },
+  "SeriesInfos": []
+}

package/test/fixtures/responses/getseries.invalid.json

@@ -0,0 +1,11 @@
+{
+  "Codigo": -50,
+  "Descripcion": "An internal error has occurred, information is not available.",
+  "Series": {
+    "descripEsp": null,
+    "descripIng": null,
+    "seriesId": null,
+    "Obs": null
+  },
+  "SeriesInfos": []
+}

package/test/fixtures/responses/getseries.success.json

@@ -0,0 +1,87 @@
+{
+  "Codigo": 0,
+  "Descripcion": "Success",
+  "Series": {
+    "seriesId": "TEST",
+    "descripEsp": "Test",
+    "descripIng": "Test",
+    "Obs": [
+      {
+        "indexDateString": "01-12-2020",
+        "value": "12.01",
+        "statusCode": "OK"
+      },
+      {
+        "indexDateString": "02-12-2020",
+        "value": "12.02",
+        "statusCode": "OK"
+      },
+      {
+        "indexDateString": "03-12-2020",
+        "value": "12.03",
+        "statusCode": "OK"
+      },
+      {
+        "indexDateString": "04-12-2020",
+        "value": "12.04",
+        "statusCode": "OK"
+      },
+      {
+        "indexDateString": "05-12-2020",
+        "value": "NaN",
+        "statusCode": "ND"
+      },
+      {
+        "indexDateString": "06-12-2020",
+        "value": "NaN",
+        "statusCode": "ND"
+      },
+      {
+        "indexDateString": "07-12-2020",
+        "value": "12.07",
+        "statusCode": "OK"
+      },
+      {
+        "indexDateString": "08-12-2020",
+        "value": "NaN",
+        "statusCode": "ND"
+      },
+      {
+        "indexDateString": "09-12-2020",
+        "value": "12.09",
+        "statusCode": "OK"
+      },
+      {
+        "indexDateString": "10-12-2020",
+        "value": "12.10",
+        "statusCode": "OK"
+      },
+      {
+        "indexDateString": "11-12-2020",
+        "value": "12.11",
+        "statusCode": "OK"
+      },
+      {
+        "indexDateString": "12-12-2020",
+        "value": "NaN",
+        "statusCode": "ND"
+      },
+      {
+        "indexDateString": "13-12-2020",
+        "value": "NaN",
+        "statusCode": "ND"
+      },
+      {
+        "indexDateString": "14-12-2020",
+        "value": "12.14",
+        "statusCode": "OK"
+      },
+      {
+        "indexDateString": "15-12-2020",
+        "value": "12.15",
+        "statusCode": "OK"
+      }
+    ]
+  },
+  "SeriesInfo": []
+}

package/test/fixtures/responses/searchseries.invalid.json

@@ -0,0 +1,11 @@
+{
+  "Codigo": -1,
+  "Descripcion": "FrequencyCode must have a valid code (ie. DAILY, MONTHLY, QUARTERLY or ANNUAL)",
+  "Series": {
+    "descripEsp": null,
+    "descripIng": null,
+    "seriesId": null,
+    "Obs": null
+  },
+  "SeriesInfos": []
+}

package/test/fixtures/responses/searchseries.success.json

@@ -0,0 +1,20 @@
+{
+  "Codigo": 0,
+  "Descripcion": "Success",
+  "Series": {
+    "descripEsp": null,
+    "descripIng": null,
+    "seriesId": null,
+    "Obs": null
+  },
+  "SeriesInfos": [{
+    "seriesId": "TEST",
+    "frequencyCode": "DAILY",
+    "spanishTitle": "Test",
+    "englishTitle": "Test",
+    "firstObservation": "01-12-2020",
+    "lastObservation": "15-12-2020",
+    "updatedAt": "19-01-2024",
+    "createdAt": "19-01-2024"
+  }]
+}

package/test/helpers.test.ts

@@ -0,0 +1,26 @@
+import { describe, it, expect } from 'vitest';
+import { reverseDate, isValidDate } from '../src/helpers';
+
+describe('helpers: reverseDate', () => {
+  it('should reverse correctly a date in DD-MM-YYYY format', () => {
+    const date = '01-02-2020';
+    const reversed = reverseDate(date);
+
+    expect(reversed).toBe('2020-02-01');
+  });
+});
+
+describe('helpers: isValidDate', () => {
+  it('should return true if the date is valid', () => {
+    expect(isValidDate('2020-01-01')).toBe(true);
+    expect(isValidDate(new Date())).toBe(true);
+  });
+
+  it('should return false if the date is invalid', () => {
+    expect(isValidDate('invalid')).toBe(false);
+    expect(isValidDate({})).toBe(false);
+    expect(isValidDate(undefined)).toBe(false);
+    expect(isValidDate(null)).toBe(false);
+    expect(isValidDate(new Date('invalid'))).toBe(false);
+  });
+});

package/test/mocks/fetch.mock.ts

@@ -0,0 +1,71 @@
+import { Frequency } from '../../src/response';
+import { reverseDate } from '../../src/helpers';
+import fixtures from '../fixtures';
+
+export default (input: string | URL | Request) => {
+  const params = new URL(input.toString()).searchParams;
+  const func = params.get('function') || 'GetSeries';
+
+  if (params.get('user') !== 'test' || params.get('pass') !== 'test') {
+    return Promise.resolve({
+      json: () => Promise.resolve(fixtures.response.credentialsInvalid),
+    } as Response);
+  }
+  
+  if (func === 'GetSeries') {
+    if (fixtures.response.getSeriesSuccess.Series.seriesId !== params.get('timeseries')) {
+      return Promise.resolve({
+        json: () => Promise.resolve(fixtures.response.getSeriesInvalid),
+      } as Response);
+    }
+
+    const firstDate = params.get('firstdate');
+    const lastDate = params.get('lastdate');
+    const obs = fixtures.response.getSeriesSuccess.Series.Obs.filter((obs) => {
+      if (firstDate && lastDate) {
+        return reverseDate(obs.indexDateString) >= firstDate && reverseDate(obs.indexDateString) <= lastDate;
+      }
+      if (firstDate) {
+        return reverseDate(obs.indexDateString) >= firstDate;
+      }
+      if (lastDate) {
+        return reverseDate(obs.indexDateString) <= lastDate;
+      }
+      return true;
+    });
+    const series = {
+      ...fixtures.response.getSeriesSuccess.Series,
+      Obs: obs,
+    };
+
+    return Promise.resolve({
+      json: () => Promise.resolve({
+        ...fixtures.response.getSeriesSuccess,
+        Series: series,
+      }),
+    } as Response);
+  }
+
+  if (func === 'SearchSeries') {
+    const frequency = params.get('frequency');
+
+    if (!Object.values(Frequency).includes(frequency as Frequency)) {
+      return Promise.resolve({
+        json: () => Promise.resolve(fixtures.response.searchSeriesInvalid),
+      } as Response);
+    }
+
+    const response = {
+      ...fixtures.response.searchSeriesSuccess,
+      SeriesInfo: fixtures.response.searchSeriesSuccess.SeriesInfos.filter((series) => series.frequencyCode === frequency),
+    };
+
+    return Promise.resolve({
+      json: () => Promise.resolve(response),
+    } as Response);
+  }
+
+  return Promise.resolve({
+    json: () => Promise.resolve({}),
+  } as Response);
+}

package/test/response.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect } from 'vitest';
+import * as Errors from '../src/errors';
+import {
+  ApiResponse,
+  parseGetSeriesResponse,
+  parseSearchSeriesResponse,
+} from '../src/response';
+import fixtures from './fixtures';
+
+describe('parseGetSeriesResponse', () => {
+  it('should parse correctly a valid response', () => {
+    const parsed = parseGetSeriesResponse(fixtures.response.getSeriesSuccess as unknown as ApiResponse);
+
+    expect(parsed).toBeDefined();
+    expect(parsed.seriesId).toBe(fixtures.response.getSeriesSuccess.Series.seriesId);
+    expect(parsed.description).toBe(fixtures.response.getSeriesSuccess.Series.descripIng);
+    expect(parsed.data).toHaveLength(fixtures.response.getSeriesSuccess.Series.Obs.length);
+    
+    for (let i = 0; i < parsed.data.length; i += 1) {
+      expect(parsed.data[i].date).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+      expect(parsed.data[i].value.toFixed(2)).toBe(fixtures.response.getSeriesSuccess.Series.Obs[i].value);
+
+      if (Number.isNaN(parsed.data[i].value)) {
+        expect(fixtures.response.getSeriesSuccess.Series.Obs[i].statusCode).toBe('ND');
+      }
+    }
+  });
+
+  it('should throw an InvalidCredentialsError if the response code is -5', () => {
+    expect(() => parseGetSeriesResponse(fixtures.response.credentialsInvalid as unknown as ApiResponse)).toThrow(Errors.InvalidCredentialsError);
+  });
+
+  it('should throw an InvalidSeriesError if the response code is -50', () => {
+    expect(() => parseGetSeriesResponse(fixtures.response.getSeriesInvalid as unknown as ApiResponse)).toThrow(Errors.InvalidSeriesError);
+  });
+
+  it('should throw a ResponseError if the response code is unknown', () => {
+    expect(() => parseGetSeriesResponse({} as ApiResponse)).toThrow(Errors.WebServiceError);
+  });
+});
+
+describe('parseSearchSeriesResponse', () => {
+  it('should parse correctly a valid response', () => {
+    const parsed = parseSearchSeriesResponse(fixtures.response.searchSeriesSuccess as unknown as ApiResponse);
+
+    expect(parsed).toBeInstanceOf(Array);
+    expect(parsed).toHaveLength(fixtures.response.searchSeriesSuccess.SeriesInfos.length);
+
+    for (let i = 0; i < parsed.length; i += 1) {
+      expect(parsed[i].seriesId).toBe(fixtures.response.searchSeriesSuccess.SeriesInfos[i].seriesId);
+      expect(parsed[i].frequency).toBe(fixtures.response.searchSeriesSuccess.SeriesInfos[i].frequencyCode);
+      expect(parsed[i].title).toBe(fixtures.response.searchSeriesSuccess.SeriesInfos[i].englishTitle);
+      expect(parsed[i].firstObservedAt).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+      expect(parsed[i].lastObservedAt).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+      expect(parsed[i].updatedAt).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+      expect(parsed[i].createdAt).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+    }
+  });
+
+  it('should throw an InvalidCredentialsError if the response code is -5', () => {
+    expect(() => parseSearchSeriesResponse(fixtures.response.credentialsInvalid as unknown as ApiResponse)).toThrow(Errors.InvalidCredentialsError);
+  });
+
+  it('should throw an InvalidFrequencyError if the response code is -1', () => {
+    expect(() => parseSearchSeriesResponse(fixtures.response.searchSeriesInvalid as unknown as ApiResponse)).toThrow(Errors.InvalidFrequencyError);
+  });
+
+  it('should throw a ResponseError if the response code is unknown', () => {
+    expect(() => parseSearchSeriesResponse({} as ApiResponse)).toThrow(Errors.WebServiceError);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "@tsconfig/node20",
+  "compilerOptions": {
+    "outDir": "dist",
+    "resolveJsonModule": true,
+    "declaration": true,
+  },
+  "include": ["src/**/*"]
+}

package/vitest.config.mts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    dir: 'test',
+  },
+});