bcchapi 2.0.0 → 2.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/CHANGELOG.md +17 -7
  2. package/README.md +153 -78
  3. package/package.json +2 -2
package/CHANGELOG.md CHANGED
@@ -6,17 +6,27 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
6
6
 
7
7
  ---
8
8
 
9
- ## [0.1.0] - 2026-03-10
9
+ ## [2.0.1] - 2026-03-10
10
10
 
11
+ ### Changed
11
12
 
12
- ### Added
13
+ - Updated README with full API reference and usage examples
14
+ - Cleaned up CHANGELOG to start from v2.0.0
15
+
16
+ ---
13
17
 
14
- - Add date, transform, and stats utility functions
15
- - Add SERIES constants with curated well-known series IDs
16
- - Add Client, ApiError, and HttpError with full test coverage
18
+ ## [2.0.0] - 2026-03-10
19
+
20
+ ### Added
17
21
 
22
+ - `bcchapi/client` — typed HTTP client (`Client`, `ApiError`, `HttpError`) for the Banco Central de Chile REST API
23
+ - `bcchapi/series` — curated `SERIES` constants covering exchange rates, prices, interest rates, money, national accounts, external sector, employment, public finances, and capital markets
24
+ - `bcchapi/utils` — observation transform functions (`parseValue`, `filterValid`, `toNumbers`, `toMap`, `toArrays`, `parseObservationDate`, `formatQueryDate`) and statistics functions (`mean`, `stdDev`, `min`, `max`, `periodVariation`, `annualVariation`, `rollingMean`)
25
+ - ESM-only output targeting Node.js >= 24
26
+ - Full TypeScript declarations and source maps
27
+ - npm provenance via GitHub Actions (SLSA)
18
28
 
19
29
  ---
20
30
 
21
- [0.1.0]: https://github.com/airarrazaval/bcch/compare/v0.0.1...v0.1.0
22
- [Unreleased]: https://github.com/airarrazaval/bcch/compare/v0.1.0...HEAD
31
+ [2.0.1]: https://github.com/airarrazaval/bcchapi/compare/v2.0.0...v2.0.1
32
+ [2.0.0]: https://github.com/airarrazaval/bcchapi/releases/tag/v2.0.0
package/README.md CHANGED
@@ -1,116 +1,191 @@
1
- # Node.js Library Template
1
+ # bcchapi
2
2
 
3
- A minimal, opinionated template for publishing Node.js libraries written in TypeScript.
3
+ Node.js wrapper for the [Banco Central de Chile REST API](https://si3.bcentral.cl/siete). Features a fully typed HTTP client, curated series ID constants, and utility functions for transforming and analysing macroeconomic observations.
4
4
 
5
- ## Features
5
+ ## Requirements
6
+
7
+ - Node.js >= 24.0.0
8
+
9
+ ## Installation
10
+
11
+ ```sh
12
+ npm install bcchapi
13
+ ```
14
+
15
+ ## Authentication
6
16
 
7
- - **TypeScript** with strict settings and `NodeNext` module resolution
8
- - **ESM-only** output (`"type": "module"`)
9
- - **Node.js 24+** target
10
- - **Testing** via Node.js built-in test runner (`node:test`) with [tsx](https://github.com/privatenumber/tsx) for TypeScript support
11
- - **Linting** with [oxlint](https://oxc.rs/docs/guide/usage/linter)
12
- - **Formatting** with [oxfmt](https://github.com/nicolo-ribaudo/oxfmt)
13
- - **Type declarations** and source maps included in the build output
14
- - **API documentation** generation with [TypeDoc](https://typedoc.org) and TSDoc comments
15
- - **Changelog** generation from [Conventional Commits](https://www.conventionalcommits.org) via [git-cliff](https://git-cliff.org)
16
- - **CI/CD** via GitHub Actions: automated checks on PRs and tag-triggered npm publishing with SLSA provenance
17
+ Register for free at [si3.bcentral.cl](https://si3.bcentral.cl/siete) to obtain API credentials (email + password).
17
18
 
18
- ## Getting Started
19
+ ## Usage
19
20
 
20
- 1. Click **Use this template** on GitHub to create a new repository.
21
- 2. Clone your new repo and install dependencies:
21
+ ### Fetch a time series
22
22
 
23
- ```sh
24
- npm install
25
- ```
23
+ ```ts
24
+ import { Client } from 'bcchapi/client';
25
+ import { SERIES } from 'bcchapi/series';
26
26
 
27
- 3. Replace the contents of [src/index.ts](src/index.ts) with your library code.
28
- 4. Update `name`, `version`, and `description` in [package.json](package.json).
29
- 5. Update the `exports` field in [package.json](package.json) if you need multiple entry points.
30
- 6. Add an `NPM_TOKEN` secret to your repository under **Settings → Secrets and variables → Actions**.
27
+ const client = new Client({ user: 'me@example.com', pass: 'secret' });
31
28
 
32
- ## Project Structure
29
+ const data = await client.getSeries(SERIES.PRICES.UF, {
30
+ firstdate: '2024-01-01',
31
+ lastdate: '2024-12-31',
32
+ });
33
33
 
34
- ```text
35
- src/ # Library source code
36
- tests/ # Test files (*.test.ts)
37
- dist/ # Compiled output (generated, not committed)
38
- tsconfig.json # TypeScript config for type-checking
39
- tsconfig.build.json # TypeScript config for compilation
34
+ console.log(data.descripIng); // "Unidad de Fomento (UF)"
35
+ console.log(data.observations); // [{ indexDateString, value, statusCode }, ...]
40
36
  ```
41
37
 
42
- ## Development
38
+ ### Transform observations
43
39
 
44
- Start the test watcher while you write code:
40
+ ```ts
41
+ import { toNumbers, toArrays, filterValid, mean, rollingMean } from 'bcchapi/utils';
45
42
 
46
- ```sh
47
- npm run dev
43
+ // Parse values to number | null (null for gaps)
44
+ const values = toNumbers(data.observations); // [37000.12, null, 37050.45, ...]
45
+
46
+ // Get parallel Date[] and (number | null)[] arrays
47
+ const { dates, values } = toArrays(data.observations);
48
+
49
+ // Filter out gap observations
50
+ const valid = filterValid(data.observations);
51
+
52
+ // Summary statistics (gaps are ignored)
53
+ const avg = mean(data.observations);
54
+
55
+ // 3-period rolling mean
56
+ const rolling = rollingMean(data.observations, 3);
48
57
  ```
49
58
 
50
- Before opening a pull request, verify everything passes:
59
+ ### Compute variations
51
60
 
52
- ```sh
53
- npm run typecheck && npm run lint && npm run format:check && npm test
61
+ ```ts
62
+ import { periodVariation, annualVariation } from 'bcchapi/utils';
63
+
64
+ // Month-over-month change
65
+ const mom = periodVariation(cpi.observations);
66
+
67
+ // 12-month change for monthly series
68
+ const yoy = annualVariation(cpi.observations, 12);
54
69
  ```
55
70
 
56
- ## Scripts
71
+ ### Search available series
72
+
73
+ ```ts
74
+ const monthlySeries = await client.searchSeries('MONTHLY');
75
+ console.log(monthlySeries.map(s => s.englishTitle));
76
+ ```
57
77
 
58
- | Command | Description |
59
- | ----------------------- | -------------------------------------------------------------- |
60
- | `npm run dev` | Run tests in watch mode |
61
- | `npm run build` | Compile TypeScript to `dist/` |
62
- | `npm test` | Run tests |
63
- | `npm run test:coverage` | Run tests with coverage report |
64
- | `npm run typecheck` | Type-check without emitting files |
65
- | `npm run lint` | Lint source and tests |
66
- | `npm run lint:fix` | Lint and auto-fix issues |
67
- | `npm run format` | Format all files |
68
- | `npm run format:check` | Check formatting without modifying files |
69
- | `npm run clean` | Remove `dist/` and `docs/` |
70
- | `npm run docs` | Generate API documentation in `docs/` |
71
- | `npm run changelog` | Regenerate `CHANGELOG.md` from commits (used before releasing) |
78
+ ### Error handling
79
+
80
+ ```ts
81
+ import { ApiError, HttpError } from 'bcchapi/client';
82
+
83
+ try {
84
+ await client.getSeries('INVALID_ID');
85
+ } catch (err) {
86
+ if (err instanceof ApiError) {
87
+ // Non-zero Codigo in the API response body
88
+ console.error(`API error ${err.codigo}: ${err.descripcion}`);
89
+ } else if (err instanceof HttpError) {
90
+ // Non-ok HTTP status
91
+ console.error(`HTTP ${err.status}`);
92
+ } else {
93
+ // Network failure — original error available as err.cause
94
+ throw err;
95
+ }
96
+ }
97
+ ```
72
98
 
73
- ## GitHub Actions
99
+ ## API
74
100
 
75
- ### CI (`ci.yml`)
101
+ ### `bcchapi/client`
76
102
 
77
- Runs on every pull request and push to `main`:
103
+ #### `new Client(options)`
78
104
 
79
- 1. Verify package signatures (`npm audit signatures`)
80
- 2. Audit production dependencies for vulnerabilities (`npm audit --omit=dev`)
81
- 3. Typecheck
82
- 4. Lint
83
- 5. Format check
84
- 6. Test
85
- 7. Build
105
+ | Option | Type | Description |
106
+ | ------ | ---- | ----------- |
107
+ | `user` | `string` | BCCH account email |
108
+ | `pass` | `string` | BCCH account password |
109
+ | `fetch` | `typeof fetch` | Custom fetch implementation (optional, useful for testing) |
86
110
 
87
- ### Publish (`publish.yml`)
111
+ #### `client.getSeries(seriesId, options?)`
88
112
 
89
- Runs automatically when a version tag (e.g. `v1.2.3`) is pushed. Runs `prepublishOnly`
90
- (typecheck → lint → clean → build) then publishes to npm with
91
- [SLSA provenance attestation](https://docs.npmjs.com/generating-provenance-statements).
113
+ Fetches observations for a single time series.
92
114
 
93
- **Do not run `npm publish` manually.** Use the release flow below instead.
115
+ | Parameter | Type | Description |
116
+ | --------- | ---- | ----------- |
117
+ | `seriesId` | `string` | BCCH series identifier |
118
+ | `options.firstdate` | `string` | Start date `"YYYY-MM-DD"` (defaults to earliest available) |
119
+ | `options.lastdate` | `string` | End date `"YYYY-MM-DD"` (defaults to most recent) |
94
120
 
95
- ## Releasing
121
+ Returns `Promise<SeriesData>`.
122
+
123
+ #### `client.searchSeries(frequency)`
124
+
125
+ Returns metadata for all series with the given frequency. `frequency` is one of `'DAILY' | 'MONTHLY' | 'QUARTERLY' | 'ANNUAL'`.
126
+
127
+ Returns `Promise<SeriesInfo[]>`.
128
+
129
+ ### `bcchapi/series`
130
+
131
+ `SERIES` is a nested `as const` object of curated series IDs grouped by domain:
132
+
133
+ | Group | Description |
134
+ | ----- | ----------- |
135
+ | `SERIES.EXCHANGE_RATE` | USD/CLP and major currency pairs |
136
+ | `SERIES.PRICES` | UF, UTM, IVP, CPI and components |
137
+ | `SERIES.INTEREST_RATES` | MPR, BCP/BCU sovereign bonds, PDBC rates |
138
+ | `SERIES.MONEY` | M1, M2, M3, bank loans by type |
139
+ | `SERIES.NATIONAL_ACCOUNTS` | Imacec and components |
140
+ | `SERIES.EXTERNAL_SECTOR` | Current account, exports, imports, FDI |
141
+ | `SERIES.EMPLOYMENT` | Unemployment rate, labour force, employed/unemployed |
142
+ | `SERIES.PUBLIC_FINANCES` | Government revenue, expenditure, fiscal balance |
143
+ | `SERIES.CAPITAL_MARKET` | IPSA, stock market capitalisation |
144
+
145
+ Use [si3.bcentral.cl](https://si3.bcentral.cl/siete) or `client.searchSeries()` to discover additional series IDs beyond the curated set.
146
+
147
+ ### `bcchapi/utils`
148
+
149
+ #### Transform functions
150
+
151
+ | Function | Description |
152
+ | -------- | ----------- |
153
+ | `parseValue(value)` | Parses a value string to `number \| null` (`null` for empty or non-numeric) |
154
+ | `filterValid(observations)` | Returns only observations with parseable numeric values |
155
+ | `toNumbers(observations)` | Maps observations to `Array<number \| null>` |
156
+ | `toMap(observations)` | Returns a `Map<string, number \| null>` keyed by `indexDateString` |
157
+ | `toArrays(observations)` | Returns `{ dates: Date[], values: Array<number \| null> }` |
158
+ | `parseObservationDate(dateString)` | Parses `"DD-MM-YYYY"` to a UTC `Date` |
159
+ | `formatQueryDate(date)` | Formats a `Date` to `"YYYY-MM-DD"` for use in `getSeries` options |
160
+
161
+ #### Statistics functions
162
+
163
+ All stats functions operate on `Observation[]` and ignore gap values (empty or non-numeric).
164
+
165
+ | Function | Description |
166
+ | -------- | ----------- |
167
+ | `mean(observations)` | Arithmetic mean |
168
+ | `stdDev(observations)` | Sample standard deviation (Bessel's correction) |
169
+ | `min(observations)` | Minimum value |
170
+ | `max(observations)` | Maximum value |
171
+ | `periodVariation(observations)` | Period-over-period fractional change (`value[i] / value[i-1] - 1`) |
172
+ | `annualVariation(observations, periodsPerYear)` | Year-over-year fractional change (`value[i] / value[i - n] - 1`) |
173
+ | `rollingMean(observations, window)` | Rolling mean over a fixed window; `null` if any value in window is a gap |
174
+
175
+ ## Releases
96
176
 
97
177
  ```sh
98
- # 1. Regenerate CHANGELOG.md from commits (auto-determines next version)
178
+ # 1. Regenerate CHANGELOG.md (auto-determines next version)
99
179
  npm run changelog
100
180
 
101
- # 2. Review CHANGELOG.md, update comparison links at the bottom, then commit
181
+ # 2. Commit and bump version
102
182
  git add CHANGELOG.md && git commit -m "chore: release vX.Y.Z"
103
-
104
- # 3. Bump version in package.json to match what git-cliff determined
105
183
  npm version patch # or minor / major
106
184
 
107
- # 4. Push — the publish workflow triggers automatically on the version tag
185
+ # 3. Push — the publish workflow triggers automatically on the version tag
108
186
  git push --follow-tags
109
187
  ```
110
188
 
111
- Only `dist/`, `README.md`, `CHANGELOG.md`, and `LICENSE` are included in the published
112
- package (see `files` in [package.json](package.json)).
113
-
114
- ## Requirements
189
+ ## License
115
190
 
116
- - Node.js >= 24.0.0
191
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "bcchapi",
3
- "version": "2.0.0",
3
+ "version": "2.0.1",
4
4
  "description": "Node.js wrapper for the Banco Central de Chile API. Features a fully typed API client and utility tools to streamline macroeconomic data integration.",
5
5
  "homepage": "https://github.com/airarrazaval/bcchapi#readme",
6
6
  "bugs": {
@@ -71,4 +71,4 @@
71
71
  "engines": {
72
72
  "node": ">=24.0.0"
73
73
  }
74
- }
74
+ }