bsuir-iis-api 0.6.7 → 0.9.0

package/CHANGELOG.md

@@ -1,12 +1,67 @@
 # Changelog
 
+## 0.9.0
+
+### Minor Changes
+
+- 323feb4: New public APIs, cache, hooks, deps versions update, new JSdoc, etc.
+
 All notable changes to this project are documented in this file.
 
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 This changelog is maintained manually and updated in release commits.
 
-## [Unreleased]
+## [0.8.0] - 2026-05-10
+
+### Added
+
+- Public exports for schedule utilities: `normalizeSchedule` and `filterLessons`.
+- Public re-export of `ScheduleFilterOptions` type from `src/index.ts`.
+- Global cancellation support via `createBsuirClient({ signal })`.
+- `src/modules/index.ts` barrel for module factory imports.
+- In-memory GET cache via `createBsuirClient({ cache: { ttlMs, maxEntries } })`.
+- In-flight GET request deduplication via `dedupeInFlight`.
+- Opt-in runtime response-shape validation via `validateResponses` and `BsuirResponseValidationError`.
+- Request lifecycle hooks via `createBsuirClient({ hooks })`: `onRequest`, `onRetry`, `onResponse`, `onError`.
+- API Extractor configuration (`api-extractor.json`) and npm scripts for local/update and CI checks.
+- `POST` method support in `requestJson` via `options.method` and `options.body`.
+
+### Fixed
+
+- `schedule.getGroup/getEmployee` return typing now follows client-level `defaultRaw` when `raw` is omitted.
+- `normalizeSchedule` no longer duplicates day-item flattening work and avoids repeated `auditories` normalization per lesson.
+- Strict date parsing in `parseDdMmYyyy` now rejects non-existent calendar dates (for example `31.02.2026`).
+- `BsuirNetworkError` now relies on standard `Error.cause` instead of duplicate `causeError` field.
+- Client option validation now rejects invalid timeout/retry configuration values early.
+- `week.ts`: passing an empty string now throws a clear `BsuirValidationError` ("is an empty string") instead of a misleading "must be a positive integer" message.
+- `filterLessons`: `weekNumber: 0` is now rejected with `assertPositiveInt` instead of silently passing.
+- `http.ts`: cache eviction now uses pseudo-LRU (oldest-inserted Map key, O(1)) instead of an O(n) scan; `inFlightPromise` is typed as `Promise<T>` to eliminate unsafe `as Promise<unknown>` cast.
+- `http.ts`: restored file integrity after shell heredoc substitution corrupted ES module imports; fixed `@typescript-eslint/no-unsafe-call` error on `inFlight` read by shifting the `as T` cast to the Promise type before `await`.
+
+### Changed
+
+- JSDoc for `defaultRaw` client option now clarifies that a per-call `raw` option takes priority and includes an `@example` for both cases.
+- Dev tooling: bumped TypeScript to 6.0.3, ESLint to ^10.2.1, Vitest and `@vitest/coverage-v8` to ^4.1.4, `@types/node` to ^25.6.0, `@typescript-eslint/*` and `typescript-eslint` to ^8.58.2, `@changesets/cli` to ^2.31.0, `@microsoft/api-extractor` to ^7.58.5, Prettier to ^3.8.3, `globals` to ^17.5.0; regenerated `package-lock.json`.
+- CI now validates API report compatibility via `npm run api:report:check` (Node 24 job in matrix).
+- `vitest.config.ts`: added coverage thresholds (`lines: 80`, `functions: 80`) to enforce minimum test coverage on CI.
+
+## [0.7.0] - 2026-04-19
+
+### Added
+
+- `BsuirConfigurationError` when the runtime has no `fetch` and none was passed to `createBsuirClient({ fetch })`.
+
+### Changed
+
+- HTTP client (2xx): valid JSON is parsed even when the server omits `application/json` in `Content-Type`; if the header declares JSON and the body is invalid, empty, or truncated, `BsuirApiError` (`Invalid JSON response payload`) is thrown; an empty body without a JSON `Content-Type` yields an empty string `""`.
+- `package.json` `engines.node`: `>=20.0.0`. GitHub Actions **CI** runs on Node.js 20, 22, and 24 (`fail-fast: false`).
+
+### Documentation
+
+- README: **Runtime requirements** (Node 20+ and CI), **Errors** (`BsuirConfigurationError`), **Successful HTTP responses (body parsing)**.
+- JSDoc on catalog `listAll` methods (student groups, employees, faculties, departments, specialities, auditories), including caller abort / `AbortError` behavior.
+- `.cursorrules` in the repository aligned with ESM-only build and the actual stack (Vitest, tsup, ESLint, native `fetch`).
 
 ## [0.6.7] - 2026-04-02
 

package/README.md

@@ -4,7 +4,7 @@ Type-safe ESM SDK for [BSUIR IIS API](https://iis.bsuir.by/api/) with support fo
 
 ## Runtime requirements
 
-- **Node.js** `>=24` as declared in `package.json` (`engines`).
+- **Node.js** `>=20` as declared in `package.json` (`engines`). CI runs on Node 20, 22, and 24.
 - A global **`fetch`** implementation, or pass `fetch` into `createBsuirClient({ fetch })` (for tests or polyfills).
 - **`AbortController` / `AbortSignal`** for cancellation and timeouts. When `AbortSignal.any` is available (current Node and modern browsers), the client combines the per-request timeout with your `signal` using the platform API; otherwise it merges them manually with `setTimeout`, so timeouts still apply together with a caller-provided `AbortSignal`.
 
@@ -38,11 +38,24 @@ const client = createBsuirClient({
   retryDelayMs: 300,
   retryMaxDelayMs: 3000,
   retryJitter: true,
+  cache: { ttlMs: 60_000, maxEntries: 200 },
+  dedupeInFlight: true,
+  validateResponses: false,
+  hooks: {
+    onRetry: ({ endpoint, delayMs, reason }) => {
+      console.log("retry", endpoint, delayMs, reason);
+    }
+  },
   defaultRaw: false
 });
 ```
 
 - `fetch` can be passed for custom runtime/testing.
+- `signal` in `createBsuirClient({ signal })` acts as a global cancellation signal for all requests made by that client.
+- `cache` stores successful GET responses in-memory for the configured TTL.
+- `dedupeInFlight` reuses the same in-flight GET request for concurrent callers (when no per-request signal is passed).
+- `validateResponses` enables runtime payload-shape checks for key endpoints.
+- `hooks` provides lifecycle callbacks (`onRequest`, `onRetry`, `onResponse`, `onError`) for observability.
 - `AbortSignal` is supported by all read methods.
 
 ## API
@@ -84,9 +97,11 @@ When IIS responds with HTTP `404` or `400` (no list, missing resource, or endpoi
 SDK throws typed errors:
 
 - `BsuirApiError` for HTTP errors (contains `status`, `endpoint`, `body`). **Exception:** `client.announcements.byEmployee` / `byDepartment` resolve to `[]` on IIS HTTP `404` or `400` instead of throwing (see Announcements above).
-- `BsuirNetworkError` for transport errors (contains `endpoint`, `causeError`, and standard `cause`)
+- `BsuirNetworkError` for transport errors (contains `endpoint` and standard `cause`)
+- `BsuirResponseValidationError` for invalid payload shapes when `validateResponses: true`
 - `BsuirTimeoutError` for timeouts (contains `endpoint`, `timeoutMs`)
 - `BsuirValidationError` for invalid input parameters
+- `BsuirConfigurationError` when the runtime has no `fetch` and none was passed to `createBsuirClient({ fetch })`
 
 Validation rules:
 
@@ -100,7 +115,15 @@ Retry and abort behavior:
 - Caller-provided aborted `AbortSignal` is re-thrown as native `AbortError`
 - Internal timeout is mapped to `BsuirTimeoutError`
 
-`createBsuirClient()` throws regular `Error` if no `fetch` implementation is available.
+`createBsuirClient()` throws `BsuirConfigurationError` if no `fetch` implementation is available.
+
+## Successful HTTP responses (body parsing)
+
+For **2xx** responses the client reads the body as text, then applies `JSON.parse` when the payload is valid JSON:
+
+- Valid JSON is returned even when `Content-Type` does **not** include `application/json` (mislabeled responses still parse).
+- If `Content-Type` indicates **`application/json`** but the body is empty or not valid JSON, the client throws `BsuirApiError` (`Invalid JSON response payload`), same as for a truncated `{` payload.
+- If the body is **empty** and the content type does **not** indicate JSON, the result is an empty string `""` (analogous to reading plain text). Typical IIS catalog JSON endpoints return a non-empty body.
 
 ## Raw vs normalized schedule response
 
@@ -142,6 +165,7 @@ npm run lint
 npm run lint:fix
 npm run check
 npm run build
+npm run api:report
 ```
 
 `npm run build` uses [tsup](https://tsup.egoist.dev/) with [`experimentalDts`](https://tsup.egoist.dev/) so `.d.ts` output is produced via `@microsoft/api-extractor` rather than the legacy Rollup declaration path (which is awkward with TypeScript 6’s `baseUrl` deprecation). TypeScript’s handbook notes that [`paths` can be used without `baseUrl`](https://www.typescriptlang.org/docs/handbook/modules/reference.html) when you need path mapping.