bcchapi 1.0.9 → 2.0.0

package/CHANGELOG.md

@@ -2,59 +2,21 @@
 
 All notable changes to this project will be documented in this file.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [1.0.9] - 2025-02-19
+---
 
-### Changed
+## [0.1.0] - 2026-03-10
 
-- Replaced `querystring` with `URLSearchParams` in client
-
-## [1.0.8] - 2025-02-19
-
-### Fixed
-
-- Fixed `extends` missing full path in `tsconfig.json`
-
-## [1.0.7] - 2025-02-19
-
-### Changed
-
-- Moved API response handlers from `utils.ts` to new `handlers.ts` file
-- Improved date handling in `utils.ts`
-- Fixed date validation in client test
-- Updated dependencies:
-  - `@vitest/coverage-v8` from `^1.6.0` to `^3.0.6`
-  - `rimraf` from `^5.0.7` to `^6.0.1`
-  - `vitest` from `^1.6.0` to `^3.0.6`
-
-## [1.0.6] - 2024-06-13
-
-### Changed
-
-- Updated the following dependencies:
-  - `@types/node` from `20.12.7` to `2.14.2`
-  - `@vitest/coverage-v8` from `1.5.1` to `1.6.0`
-  - `rimraf` from `5.0.5` to `5.0.7`
-  - `prettier` from `3.2.5` to `3.3.2`
-  - `vitest` from `1.5.1` to `1.6.0`
-
-## [1.0.5] - 2024-04-24
 
 ### Added
 
-- This CHANGELOG file to document changes to the project.
+- Add date, transform, and stats utility functions
+- Add SERIES constants with curated well-known series IDs
+- Add Client, ApiError, and HttpError with full test coverage
+
 
-### Changed
+---
 
-- Updated the following dependencies:
-  - `@tsconfig/node20` from `20.1.2` to `20.1.4`
-  - `@types/node` from `20.11.5` to `2.12.7`
-  - `@typescript-eslint/eslint-plugin` from `6.19.0` to `6.21.0`
-  - `@typescript-eslint/parser` from `6.19.0` to `6.21.0`
-  - `@vitest/coverage-v8` from `1.2.1` to `1.5.1`
-  - `eslint` from `8.56.0` to `8.57.0`
-  - `prettier` from `3.2.4` to `3.2.5`
-  - `typescript` from `5.3.3` to `5.4.5`
-  - `vitest` from `1.2.1` to `1.5.1`
+[0.1.0]: https://github.com/airarrazaval/bcch/compare/v0.0.1...v0.1.0
+[Unreleased]: https://github.com/airarrazaval/bcch/compare/v0.1.0...HEAD

package/LICENSE

@@ -1,7 +1,21 @@
-Copyright 2024 Alfredo Irarrazaval
+MIT License
 
-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:
+Copyright (c) 2026 airarrazaval
 
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+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 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.
+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

@@ -1,124 +1,116 @@
-# BCCHAPI
+# Node.js Library Template
 
-[Statistical Data Base API](https://si3.bcentral.cl/Siete/es/Siete/API) client of the Central Bank of Chile.
+A minimal, opinionated template for publishing Node.js libraries written in TypeScript.
 
-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.
+## Features
 
-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).
+- **TypeScript** with strict settings and `NodeNext` module resolution
+- **ESM-only** output (`"type": "module"`)
+- **Node.js 24+** target
+- **Testing** via Node.js built-in test runner (`node:test`) with [tsx](https://github.com/privatenumber/tsx) for TypeScript support
+- **Linting** with [oxlint](https://oxc.rs/docs/guide/usage/linter)
+- **Formatting** with [oxfmt](https://github.com/nicolo-ribaudo/oxfmt)
+- **Type declarations** and source maps included in the build output
+- **API documentation** generation with [TypeDoc](https://typedoc.org) and TSDoc comments
+- **Changelog** generation from [Conventional Commits](https://www.conventionalcommits.org) via [git-cliff](https://git-cliff.org)
+- **CI/CD** via GitHub Actions: automated checks on PRs and tag-triggered npm publishing with SLSA provenance
 
-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**.
+## Getting Started
 
-## Installation
+1. Click **Use this template** on GitHub to create a new repository.
+2. Clone your new repo and install dependencies:
 
-```
-npm i -S bcchapi
-```
+   ```sh
+   npm install
+   ```
 
-## Usage
+3. Replace the contents of [src/index.ts](src/index.ts) with your library code.
+4. Update `name`, `version`, and `description` in [package.json](package.json).
+5. Update the `exports` field in [package.json](package.json) if you need multiple entry points.
+6. Add an `NPM_TOKEN` secret to your repository under **Settings → Secrets and variables → Actions**.
 
-```javascript
-// ESM
-import { Client } from 'bcchapi';
+## Project Structure
 
-// CommonJS
-const { Client } = require('bcchapi');
+```text
+src/           # Library source code
+tests/         # Test files (*.test.ts)
+dist/          # Compiled output (generated, not committed)
+tsconfig.json          # TypeScript config for type-checking
+tsconfig.build.json    # TypeScript config for compilation
 ```
 
-### Authentication
+## Development
 
-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.
+Start the test watcher while you write code:
 
-```js
-const client = new Client({
-  user: 'jdoe@example.com',
-  pass: 'secret',
-});
+```sh
+npm run dev
 ```
 
-### GetSeries
+Before opening a pull request, verify everything passes:
 
-Allows you to retrieve historic data series.
+```sh
+npm run typecheck && npm run lint && npm run format:check && npm test
+```
 
-- 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)
+## Scripts
 
-#### Parameters
+| Command                 | Description                                                    |
+| ----------------------- | -------------------------------------------------------------- |
+| `npm run dev`           | Run tests in watch mode                                        |
+| `npm run build`         | Compile TypeScript to `dist/`                                  |
+| `npm test`              | Run tests                                                      |
+| `npm run test:coverage` | Run tests with coverage report                                 |
+| `npm run typecheck`     | Type-check without emitting files                              |
+| `npm run lint`          | Lint source and tests                                          |
+| `npm run lint:fix`      | Lint and auto-fix issues                                       |
+| `npm run format`        | Format all files                                               |
+| `npm run format:check`  | Check formatting without modifying files                       |
+| `npm run clean`         | Remove `dist/` and `docs/`                                     |
+| `npm run docs`          | Generate API documentation in `docs/`                          |
+| `npm run changelog`     | Regenerate `CHANGELOG.md` from commits (used before releasing) |
 
-| 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'`         |
+## GitHub Actions
 
-> **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.
+### CI (`ci.yml`)
 
-#### Example
+Runs on every pull request and push to `main`:
 
-```js
-const series = await client.getSeries({
-  series: 'F072.EUR.USD.N.O.D',
-  since: '2020-12-01',
-  until: '2020-12-02',
-});
+1. Verify package signatures (`npm audit signatures`)
+2. Audit production dependencies for vulnerabilities (`npm audit --omit=dev`)
+3. Typecheck
+4. Lint
+5. Format check
+6. Test
+7. Build
 
-console.log(series);
-```
+### Publish (`publish.yml`)
 
-_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 }
-  ]
-}
-```
+Runs automatically when a version tag (e.g. `v1.2.3`) is pushed. Runs `prepublishOnly`
+(typecheck → lint → clean → build) then publishes to npm with
+[SLSA provenance attestation](https://docs.npmjs.com/generating-provenance-statements).
 
-### SearchSeries
+**Do not run `npm publish` manually.** Use the release flow below instead.
 
-Allows you to search for series by their frequency code (ie: daily, monthly, quarterly, yearly).
+## Releasing
 
-#### Parameters
+```sh
+# 1. Regenerate CHANGELOG.md from commits (auto-determines next version)
+npm run changelog
 
-| name      | type     | required | description                                                              | example   |
-| --------- | -------- | -------- | ------------------------------------------------------------------------ | --------- |
-| frequency | `string` | Yes      | The frequency code to search (`DAILY`, `MONTHLY`, `QUARTERLY`, `ANNUAL`) | `'DAILY'` |
+# 2. Review CHANGELOG.md, update comparison links at the bottom, then commit
+git add CHANGELOG.md && git commit -m "chore: release vX.Y.Z"
 
-#### Example
+# 3. Bump version in package.json to match what git-cliff determined
+npm version patch  # or minor / major
 
-```js
-import { Frequency } from 'bcchapi';
+# 4. Push — the publish workflow triggers automatically on the version tag
+git push --follow-tags
+```
 
-const result = await client.searchSeries({ frequency: Frequency.DAILY });
+Only `dist/`, `README.md`, `CHANGELOG.md`, and `LICENSE` are included in the published
+package (see `files` in [package.json](package.json)).
 
-console.log(result);
-```
+## Requirements
 
-_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'
-  },
-  ...
-]
-```
+- Node.js >= 24.0.0

package/dist/client/client.d.ts

@@ -0,0 +1,60 @@
+import type { ClientOptions, Frequency, GetSeriesOptions, SeriesData, SeriesInfo } from './types.js';
+/**
+ * HTTP client for the Banco Central de Chile REST API.
+ *
+ * @example
+ * ```ts
+ * import { Client } from 'bcch/client';
+ *
+ * const client = new Client({ user: 'me@example.com', pass: 'secret' });
+ * const data = await client.getSeries('F022.TPM.TIN.D001.NO.Z.D', {
+ *   firstdate: '2024-01-01',
+ * });
+ * console.log(data.observations);
+ * ```
+ */
+export declare class Client {
+    private readonly user;
+    private readonly pass;
+    private readonly fetch;
+    constructor(options: ClientOptions);
+    /**
+     * Fetches observations for a single time series.
+     *
+     * @param seriesId - BCCH series identifier (e.g. `'F022.TPM.TIN.D001.NO.Z.D'`).
+     *   Values from the `SERIES` constants in `bcch/series` are accepted directly.
+     * @param options - Optional date range filter.
+     * @returns Parsed series data including all observations in the requested range.
+     * @throws {ApiError} When the API returns a non-zero `Codigo`.
+     * @throws {HttpError} When the API returns a non-ok HTTP status.
+     * @throws {Error} When a network failure occurs; original error is set as `cause`.
+     *
+     * @example
+     * ```ts
+     * const data = await client.getSeries('F073.UFF.PRE.Z.D', {
+     *   firstdate: '2024-01-01',
+     *   lastdate: '2024-12-31',
+     * });
+     * ```
+     */
+    getSeries(seriesId: string, options?: GetSeriesOptions): Promise<SeriesData>;
+    /**
+     * Searches for available series filtered by observation frequency.
+     *
+     * @param frequency - One of `'DAILY'`, `'MONTHLY'`, `'QUARTERLY'`, or `'ANNUAL'`.
+     * @returns Array of series metadata matching the given frequency.
+     * @throws {ApiError} When the API returns a non-zero `Codigo`.
+     * @throws {HttpError} When the API returns a non-ok HTTP status.
+     * @throws {Error} When a network failure occurs; original error is set as `cause`.
+     *
+     * @example
+     * ```ts
+     * const monthlySeries = await client.searchSeries('MONTHLY');
+     * console.log(monthlySeries.map(s => s.englishTitle));
+     * ```
+     */
+    searchSeries(frequency: Frequency): Promise<SeriesInfo[]>;
+    private baseParams;
+    private request;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,aAAa,EACb,SAAS,EACT,gBAAgB,EAEhB,UAAU,EACV,UAAU,EACX,MAAM,YAAY,CAAC;AAyCpB;;;;;;;;;;;;;GAaG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0B;gBAEpC,OAAO,EAAE,aAAa;IAMlC;;;;;;;;;;;;;;;;;;OAkBG;IACG,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IA+BlF;;;;;;;;;;;;;;OAcG;IACG,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAuB/D,OAAO,CAAC,UAAU;YAOJ,OAAO;CAgBtB"}

package/dist/client/client.js

@@ -0,0 +1,126 @@
+import { ApiError, HttpError } from './types.js';
+const API_URL = 'https://si3.bcentral.cl/SieteRestWS/SieteRestWS.ashx';
+/**
+ * HTTP client for the Banco Central de Chile REST API.
+ *
+ * @example
+ * ```ts
+ * import { Client } from 'bcch/client';
+ *
+ * const client = new Client({ user: 'me@example.com', pass: 'secret' });
+ * const data = await client.getSeries('F022.TPM.TIN.D001.NO.Z.D', {
+ *   firstdate: '2024-01-01',
+ * });
+ * console.log(data.observations);
+ * ```
+ */
+export class Client {
+    user;
+    pass;
+    fetch;
+    constructor(options) {
+        this.user = options.user;
+        this.pass = options.pass;
+        this.fetch = options.fetch ?? globalThis.fetch;
+    }
+    /**
+     * Fetches observations for a single time series.
+     *
+     * @param seriesId - BCCH series identifier (e.g. `'F022.TPM.TIN.D001.NO.Z.D'`).
+     *   Values from the `SERIES` constants in `bcch/series` are accepted directly.
+     * @param options - Optional date range filter.
+     * @returns Parsed series data including all observations in the requested range.
+     * @throws {ApiError} When the API returns a non-zero `Codigo`.
+     * @throws {HttpError} When the API returns a non-ok HTTP status.
+     * @throws {Error} When a network failure occurs; original error is set as `cause`.
+     *
+     * @example
+     * ```ts
+     * const data = await client.getSeries('F073.UFF.PRE.Z.D', {
+     *   firstdate: '2024-01-01',
+     *   lastdate: '2024-12-31',
+     * });
+     * ```
+     */
+    async getSeries(seriesId, options) {
+        const params = this.baseParams();
+        params.set('function', 'GetSeries');
+        params.set('timeseries', seriesId);
+        if (options?.firstdate !== undefined) {
+            params.set('firstdate', options.firstdate);
+        }
+        if (options?.lastdate !== undefined) {
+            params.set('lastdate', options.lastdate);
+        }
+        const raw = await this.request(params);
+        if (raw.Codigo !== 0 || raw.Series === null) {
+            throw new ApiError(`BCCH API error: ${raw.Descripcion}`, raw.Codigo, raw.Descripcion);
+        }
+        const observations = raw.Series.Obs.map((obs) => ({
+            indexDateString: obs.indexDateString,
+            value: obs.value,
+            statusCode: obs.statusCode,
+        }));
+        return {
+            seriesId: raw.Series.seriesId,
+            descripEsp: raw.Series.descripEsp,
+            descripIng: raw.Series.descripIng,
+            observations,
+        };
+    }
+    /**
+     * Searches for available series filtered by observation frequency.
+     *
+     * @param frequency - One of `'DAILY'`, `'MONTHLY'`, `'QUARTERLY'`, or `'ANNUAL'`.
+     * @returns Array of series metadata matching the given frequency.
+     * @throws {ApiError} When the API returns a non-zero `Codigo`.
+     * @throws {HttpError} When the API returns a non-ok HTTP status.
+     * @throws {Error} When a network failure occurs; original error is set as `cause`.
+     *
+     * @example
+     * ```ts
+     * const monthlySeries = await client.searchSeries('MONTHLY');
+     * console.log(monthlySeries.map(s => s.englishTitle));
+     * ```
+     */
+    async searchSeries(frequency) {
+        const params = this.baseParams();
+        params.set('function', 'SearchSeries');
+        params.set('frequency', frequency);
+        const raw = await this.request(params);
+        if (raw.Codigo !== 0) {
+            throw new ApiError(`BCCH API error: ${raw.Descripcion}`, raw.Codigo, raw.Descripcion);
+        }
+        return (raw.SeriesInfos ?? []).map((info) => ({
+            seriesId: info.seriesId,
+            frequencyCode: info.frequencyCode,
+            spanishTitle: info.spanishTitle,
+            englishTitle: info.englishTitle,
+            firstObservation: info.firstObservation,
+            lastObservation: info.lastObservation,
+            updatedAt: info.updatedAt,
+            createdAt: info.createdAt,
+        }));
+    }
+    baseParams() {
+        const params = new URLSearchParams();
+        params.set('user', this.user);
+        params.set('pass', this.pass);
+        return params;
+    }
+    async request(params) {
+        const url = `${API_URL}?${params.toString()}`;
+        let response;
+        try {
+            response = await this.fetch(url);
+        }
+        catch (err) {
+            throw new Error('BCCH request failed', { cause: err });
+        }
+        if (!response.ok) {
+            throw new HttpError(`HTTP error ${response.status}`, response.status);
+        }
+        return response.json();
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client/client.ts"],"names":[],"mappings":"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"}

package/dist/client/index.d.ts

@@ -0,0 +1,4 @@
+export { Client } from './client.js';
+export { ApiError, HttpError } from './types.js';
+export type { ClientOptions, Frequency, GetSeriesOptions, Observation, SeriesData, SeriesInfo, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACjD,YAAY,EACV,aAAa,EACb,SAAS,EACT,gBAAgB,EAChB,WAAW,EACX,UAAU,EACV,UAAU,GACX,MAAM,YAAY,CAAC"}

package/dist/client/index.js

@@ -0,0 +1,3 @@
+export { Client } from './client.js';
+export { ApiError, HttpError } from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC"}

package/dist/client/types.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Credentials and configuration for {@link Client}.
+ */
+export interface ClientOptions {
+    /** BCCH account email. */
+    user: string;
+    /** BCCH account password. */
+    pass: string;
+    /**
+     * HTTP client used for all requests.
+     *
+     * Defaults to the global `fetch`. Inject a custom implementation in tests
+     * to avoid real network calls.
+     *
+     * @defaultValue `globalThis.fetch`
+     */
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * A single observation returned by the BCCH API.
+ *
+ * Dates are in the wire format `"DD-MM-YYYY"` as returned by the API.
+ * Values are raw numeric strings; an empty string indicates a data gap.
+ * Use {@link https://github.com/airarrazaval/bcch | bcch/utils} to parse
+ * and transform observations.
+ */
+export interface Observation {
+    /** Observation date in `"DD-MM-YYYY"` format. */
+    indexDateString: string;
+    /**
+     * Numeric value as a string.
+     *
+     * An empty string (`""`) indicates a gap in the series (no observation
+     * for that date). Use `parseValue` from `bcch/utils` to convert to a
+     * `number | null`.
+     */
+    value: string;
+    /** Observation status code (e.g. `"OK"`, `"NO_OBS"`). */
+    statusCode: string;
+}
+/**
+ * Time series data returned by {@link Client.getSeries}.
+ */
+export interface SeriesData {
+    /** BCCH series identifier. */
+    seriesId: string;
+    /** Series description in Spanish. */
+    descripEsp: string;
+    /** Series description in English. */
+    descripIng: string;
+    /** Ordered array of observations, earliest first. */
+    observations: Observation[];
+}
+/**
+ * Date range filter for {@link Client.getSeries}.
+ */
+export interface GetSeriesOptions {
+    /**
+     * Start date in `"YYYY-MM-DD"` format.
+     *
+     * Defaults to the earliest available observation when omitted.
+     */
+    firstdate?: string;
+    /**
+     * End date in `"YYYY-MM-DD"` format.
+     *
+     * Defaults to the most recent available observation when omitted.
+     */
+    lastdate?: string;
+}
+/**
+ * Metadata for a single series returned by {@link Client.searchSeries}.
+ */
+export interface SeriesInfo {
+    /** BCCH series identifier. */
+    seriesId: string;
+    /** Frequency code (e.g. `"DAILY"`, `"MONTHLY"`). */
+    frequencyCode: string;
+    /** Series title in Spanish. */
+    spanishTitle: string;
+    /** Series title in English. */
+    englishTitle: string;
+    /** Date of the first available observation in `"DD-MM-YYYY"` format. */
+    firstObservation: string;
+    /** Date of the last available observation in `"DD-MM-YYYY"` format. */
+    lastObservation: string;
+    /** Date the series was last updated in `"DD-MM-YYYY"` format. */
+    updatedAt: string;
+    /** Date the series was created in `"DD-MM-YYYY"` format. */
+    createdAt: string;
+}
+/**
+ * Observation frequency accepted by {@link Client.searchSeries}.
+ */
+export type Frequency = 'DAILY' | 'MONTHLY' | 'QUARTERLY' | 'ANNUAL';
+/**
+ * Thrown when the BCCH API returns a non-zero `Codigo` in the response body.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.getSeries('INVALID');
+ * } catch (err) {
+ *   if (err instanceof ApiError) {
+ *     console.error(`API error ${err.codigo}: ${err.descripcion}`);
+ *   }
+ * }
+ * ```
+ */
+export declare class ApiError extends Error {
+    /** Non-zero `Codigo` value from the API response. */
+    readonly codigo: number;
+    /** `Descripcion` string from the API response. */
+    readonly descripcion: string;
+    constructor(message: string, codigo: number, descripcion: string);
+}
+/**
+ * Thrown when the BCCH API returns a non-ok HTTP status code.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await client.getSeries('F022.TPM.TIN.D001.NO.Z.D');
+ * } catch (err) {
+ *   if (err instanceof HttpError) {
+ *     console.error(`HTTP ${err.status}`);
+ *   }
+ * }
+ * ```
+ */
+export declare class HttpError extends Error {
+    /** HTTP status code. */
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/client/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/client/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IAEb,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,iDAAiD;IACjD,eAAe,EAAE,MAAM,CAAC;IAExB;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IAEjB,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IAEnB,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IAEnB,qDAAqD;IACrD,YAAY,EAAE,WAAW,EAAE,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IAEjB,oDAAoD;IACpD,aAAa,EAAE,MAAM,CAAC;IAEtB,+BAA+B;IAC/B,YAAY,EAAE,MAAM,CAAC;IAErB,+BAA+B;IAC/B,YAAY,EAAE,MAAM,CAAC;IAErB,wEAAwE;IACxE,gBAAgB,EAAE,MAAM,CAAC;IAEzB,uEAAuE;IACvE,eAAe,EAAE,MAAM,CAAC;IAExB,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;IAElB,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;AAMrE;;;;;;;;;;;;;GAaG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,qDAAqD;IACrD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,kDAAkD;IAClD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBAEjB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM;CAMjE;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,wBAAwB;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAK5C"}