bcchapi 1.0.0 → 1.0.2

package/src/client.ts

@@ -1,16 +1,10 @@
 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 = {
+import { GetSeriesResponse, SearchSeriesResponse, ApiResponse } from './types';
+import { parseGetSeriesResponse, parseSearchSeriesResponse } from './helpers/parsers';
+import isValidDate from './helpers/is-valid-date';
+
+export interface ClientConfig {
   /**
    * Client username (registered email).
    */
@@ -19,33 +13,20 @@ export type ClientConfig = {
    * 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 enum Frequency {
+  Daily = 'DAILY',
+  Monthly = 'MONTHLY',
+  Quarterly = 'QUARTERLY',
+  Annual = 'ANNUAL',
+}
 
 export class Client {
   static apiURL = 'https://si3.bcentral.cl/SieteRestWS/SieteRestWS.ashx';
+
   private username: string;
+
   private password: string;
 
   constructor(config: ClientConfig) {
@@ -53,59 +34,77 @@ export class Client {
     this.password = config.pass;
   }
 
-  async request(params: Record<string, string>): Promise<ApiResponse> {
-    const query = querystring.stringify({
+  async request(query: Record<string, string>): Promise<ApiResponse> {
+    const queryString = querystring.stringify({
       user: this.username,
       pass: this.password,
-      ...params,
+      ...query,
     });
 
-    return (await fetch(`${Client.apiURL}?${query}`)).json() as Promise<ApiResponse>;
+    return (await fetch(`${Client.apiURL}?${queryString}`)).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;
+  async 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> {
+    const { series, since, until } = params;
 
     assert.ok(series && typeof series === 'string', 'series must be a non-empty string');
 
-    const params: Record<string, string> = {
+    const query: 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);
+      query.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);
+      query.lastdate = typeof until === 'string' ? until : until.toISOString().slice(0, 10);
     }
 
-    if (params.firstdate && params.lastdate) {
-      assert.ok(params.firstdate <= params.lastdate, 'invalid date range');
+    if (query.firstdate && query.lastdate) {
+      assert.ok(query.firstdate <= query.lastdate, 'invalid date range');
     }
 
-    return this.request(params).then(parseGetSeriesResponse);
+    return this.request(query).then(parseGetSeriesResponse);
   }
 
   /**
    * Fetches the list of available series by frequency and their metadata.
    */
-  async searchSeries(input: SearchSeriesInput): Promise<SearchSeriesResponse> {
-    const { frequency } = input;
-  
+  async searchSeries(params: {
+    /**
+     * Frequency for which you want to consult the catalog of available series.
+     */
+    frequency: Frequency;
+  }): Promise<SearchSeriesResponse> {
+    const { frequency } = params;
+
     assert.ok(frequency && typeof frequency === 'string', 'frequency must be a non-empty string');
-    
-    const params: Record<string, string> = {
+
+    const query: Record<string, string> = {
       frequency,
       function: 'SearchSeries',
     };
 
-    return this.request(params).then(parseSearchSeriesResponse);
+    return this.request(query).then(parseSearchSeriesResponse);
   }
-}
+}

package/src/errors.ts

@@ -1,4 +1,4 @@
-import { ErrorResponse } from './response';
+import { ErrorResponse } from './types';
 
 export enum ErrorCodes {
   InvalidCredentials = -5,
@@ -33,4 +33,4 @@ export class InvalidSeriesError extends WebServiceError {
   constructor(response?: ErrorResponse) {
     super(response, 'Invalid series id');
   }
-}
+}

package/src/helpers/is-valid-date.ts

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

package/src/helpers/parsers.ts

@@ -0,0 +1,56 @@
+import reverseDate from './reverse-date';
+import {
+  ErrorCodes,
+  InvalidFrequencyError,
+  InvalidCredentialsError,
+  InvalidSeriesError,
+  WebServiceError,
+} from '../errors';
+import { ApiResponse, ErrorResponse, GetSeriesResponse, SearchSeriesResponse } from '../types';
+
+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);
+    }
+  }
+
+  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/src/helpers/reverse-date.ts

@@ -0,0 +1,3 @@
+export default function reverseDate(date: string): string {
+  return date.split('-').reverse().join('-');
+}

package/src/index.ts

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

package/src/types.ts

@@ -0,0 +1,113 @@
+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;
+}>;

package/test/client.test.ts

@@ -1,6 +1,6 @@
-import { expect, describe, it, vi, afterEach, afterAll, beforeEach } from 'vitest';
-import { Client } from '../src';
+import { expect, describe, it, vi, afterEach, beforeEach } from 'vitest';
 import {
+  Client,
   Frequency,
   InvalidCredentialsError,
   InvalidSeriesError,
@@ -8,9 +8,8 @@ import {
 } from '../src';
 import fetchMock from './mocks/fetch.mock';
 import fixtures from './fixtures';
-import { reverseDate } from '../src/helpers';
+import reverseDate from '../src/helpers/reverse-date';
 
-// global.fetch = vi.fn().mockImplementation(fetchMock);
 const fetchSpy = vi.spyOn(global, 'fetch').mockImplementation(fetchMock);
 
 describe('Client', () => {
@@ -23,7 +22,7 @@ describe('Client', () => {
     user: '',
     pass: '',
   });
-  
+
   it('should create a Client instance', () => {
     expect(client).toBeInstanceOf(Client);
   });
@@ -37,46 +36,62 @@ describe('Client', () => {
     });
 
     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');
+      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');
+      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);
+      await expect(invalidClient.getSeries({ series: 'TEST' })).rejects.toThrow(
+        InvalidCredentialsError,
+      );
       expect(fetchSpy).toHaveBeenCalledTimes(1);
     });
 
@@ -89,16 +104,20 @@ describe('Client', () => {
       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);
+        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');
@@ -111,7 +130,7 @@ describe('Client', () => {
         series: 'TEST',
         until: '2020-12-05',
       });
-      
+
       expect(fetchSpy).toHaveBeenCalledTimes(1);
 
       expect(series).toBeDefined();
@@ -119,10 +138,14 @@ describe('Client', () => {
       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);
+        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');
@@ -137,14 +160,13 @@ describe('Client', () => {
       });
 
       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', () => {
@@ -156,28 +178,36 @@ describe('Client', () => {
     });
 
     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');
+      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);
+      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);
+      await expect(
+        client.searchSeries({
+          frequency: 'invalid' as Frequency,
+        }),
+      ).rejects.toThrow(InvalidFrequencyError);
 
       expect(fetchSpy).toHaveBeenCalledTimes(1);
     });
@@ -188,9 +218,9 @@ describe('Client', () => {
       });
 
       expect(fetchSpy).toHaveBeenCalledTimes(1);
-      
+
       expect(series).toBeInstanceOf(Array);
       expect(series).toHaveLength(1);
     });
   });
-});
+});

package/test/fixtures/index.ts

@@ -12,4 +12,4 @@ export default {
     searchSeriesInvalid,
     searchSeriesSuccess,
   },
-};
+};

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

@@ -8,4 +8,4 @@
     "Obs": null
   },
   "SeriesInfos": []
-}
+}

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

@@ -8,4 +8,4 @@
     "Obs": null
   },
   "SeriesInfos": []
-}
+}

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

@@ -84,4 +84,4 @@
     ]
   },
   "SeriesInfo": []
-}
+}

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

@@ -8,4 +8,4 @@
     "Obs": null
   },
   "SeriesInfos": []
-}
+}