bsuir-iis-api 0.10.1 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # Changelog
 
+## 0.12.0
+
+### Minor Changes
+
+- b77c694: Code review follow-ups across HTTP client, cache, schedule modules, and helpers.
+  - normalizeSchedule clones each lesson once instead of re-cloning during flattening.
+  - Response cache stores deep-frozen JSON values; reads return the frozen reference instead of cloning on every hit. setCache now rejects non-JSON values with `BsuirConfigurationError`.
+  - `requestJson` no longer disables response caching when a non-aborted `AbortSignal` is passed; only an already-aborted signal skips cache. In-flight deduplication remains disabled for per-call signals to avoid cross-caller cancellation semantics.
+  - README now documents `validateResponses` as opt-in and oversized payloads as `BsuirResponsePayloadTooLargeError`.
+  - Query keys are sorted deterministically in `buildUrl` for stable cache keys.
+  - Relaxed query key validation: any non-control, non-whitespace, non-URL-structural character is allowed.
+  - Private-header detection switched from substring sniffing to an explicit denylist.
+  - Request body now passes through `BodyInit` shapes (`FormData`/`URLSearchParams`/`Blob`/`ArrayBuffer`/`ReadableStream`) instead of being JSON-stringified.
+  - `Retry-After` numeric branch now applies the same internal cap as the date branch.
+  - `allowInsecureHttp: true` rejects any non-loopback host in `allowedBaseUrlHosts`.
+  - `mergeSignalsManual` cleanup is idempotent and listeners are recorded before registration to avoid leaks.
+  - `normalizeSchedule` always performs a minimal envelope check; full validation delegates to the single `assertScheduleResponse` source of truth.
+  - `schedule.getGroupBySubgroup` and `schedule.getEmployeeBySubgroup` accept `rawEnvelope: true` for envelope-preserving raw output (existing `raw` and default behaviors unchanged).
+  - `schedule.getGroup` / `getEmployee` now always return normalized payloads; explicit raw helpers (`getGroupRaw`, `getEmployeeRaw`, `getGroupEnvelope`, `getEmployeeEnvelope`) provide raw API envelopes.
+  - Removed `defaultRaw` and per-call `raw` selection from `getGroup` / `getEmployee` to make response shapes explicit.
+  - `announcements.byEmployee` / `byDepartment` accept `treat404AsEmpty` (default `true`) instead of relying on a body-marker heuristic to detect "no announcements" 404 responses.
+  - Added optional `onInvalidTime` hook to `sortLessonsByTime` / `getCurrentLesson` / `getNextLesson` / `buildScheduleDays` for surfacing malformed `HH:MM` lesson times.
+
+## [0.11.0] - 2026-05-24
+
+### Added
+
+- `schedule.getGroupBySubgroup()` and `schedule.getEmployeeBySubgroup()` accept `rawEnvelope: true` for envelope-preserving raw subgroup output.
+- `announcements.byEmployee()` / `byDepartment()` accept `treat404AsEmpty` (default `true`) to opt out of mapping IIS `404`/`400` empty-announcement responses to `[]`.
+- Optional `onInvalidTime` hook for `sortLessonsByTime()`, `getCurrentLesson()`, `getNextLesson()`, and `buildScheduleDays()`.
+
+### Changed
+
+- `schedule.getGroup()` / `getEmployee()` now always return normalized payloads; use `getGroupRaw()`, `getEmployeeRaw()`, `getGroupEnvelope()`, or `getEmployeeEnvelope()` for raw API envelopes.
+- Response cache stores deep-frozen JSON values, returns the cached frozen reference on hits, and rejects non-JSON cache writes with `BsuirConfigurationError`.
+- `requestJson` keeps response caching enabled for non-aborted `AbortSignal`s; in-flight deduplication remains disabled for per-call signals to avoid cross-caller cancellation semantics.
+- Query keys are sorted deterministically for stable cache keys, query key validation is relaxed for safe non-structural characters, and private-header detection now uses an explicit denylist.
+- Request bodies pass through native `BodyInit` shapes (`FormData`, `URLSearchParams`, `Blob`, `ArrayBuffer`, `ReadableStream`) instead of being JSON-stringified.
+- `Retry-After` numeric values now use the same internal cap as date-based values.
+- `allowInsecureHttp: true` rejects non-loopback hosts in `allowedBaseUrlHosts`.
+- `normalizeSchedule` clones lessons once, always performs a minimal envelope check, and delegates full validation to `assertScheduleResponse`.
+- `mergeSignalsManual` cleanup is idempotent and records listeners before registration to avoid leaks.
+
+### Documentation
+
+- README now documents explicit raw schedule helpers, `validateResponses` as opt-in, `BsuirResponsePayloadTooLargeError` for oversized payloads, and the Changesets release flow.
+
+### Potentially Breaking
+
+- Removed `defaultRaw` and per-call `raw` selection from `schedule.getGroup()` / `getEmployee()`; callers should use explicit raw helpers instead.
+- Cached responses are frozen shared references; callers that need mutation should clone returned values first.
+- Native `BodyInit` request bodies are no longer JSON-stringified.
+- `allowInsecureHttp: true` is limited to loopback hosts.
+
 ## [0.10.1] - 2026-05-13
 
 ### Documentation

package/README.md

@@ -16,7 +16,7 @@ npm install bsuir-iis-api
 
 ## Quick start
 
-Default schedule calls return a **normalized** payload (`defaultRaw: false`). That shape includes `lessons`, `lessonsByDay`, `scheduleLessons`, and `examLessons` (see types). With `{ raw: true }` you get the API’s raw `ScheduleResponse` instead—no `lessons` field; use `schedules` / `exams` and match examples to the option you use.
+Default schedule calls return a **normalized** payload. That shape includes `lessons`, `lessonsByDay`, `scheduleLessons`, and `examLessons` (see types). Use explicit raw helpers such as `client.schedule.getGroupRaw()` / `getEmployeeRaw()` to obtain the API’s raw `ScheduleResponse` (which has `schedules` / `exams` and may omit `lessons`).
 
 ```ts
 import { createBsuirClient } from "bsuir-iis-api";
@@ -50,8 +50,7 @@ const client = createBsuirClient({
     onRetry: ({ endpoint, delayMs, reason }) => {
       console.log("retry", endpoint, delayMs, reason);
     }
-  },
-  defaultRaw: false
+  }
 });
 ```
 
@@ -60,10 +59,10 @@ const client = createBsuirClient({
 - `allowedBaseUrlHosts` controls which hosts are allowed for `baseUrl` (defaults to `["iis.bsuir.by"]`).
 - `allowInsecureHttp` enables `http://` only for trusted local/test endpoints.
 - `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).
+- `cache` stores successful GET responses in-memory for the configured TTL. A live `AbortSignal` can still use cache; an already-aborted signal skips cache.
+- `dedupeInFlight` reuses the same in-flight GET request for concurrent callers. It is disabled for per-request signals, non-default cache modes, private credential headers, and already-aborted signals.
 - `maxResponseBytes` limits body size per response to protect against memory spikes.
-- `validateResponses` enables runtime payload-shape checks for key endpoints (enabled by default).
+- `validateResponses` enables opt-in runtime payload-shape checks for key endpoints.
 - `hooks` provides lifecycle callbacks (`onRequest`, `onRetry`, `onResponse`, `onError`) for observability.
 - `AbortSignal` is supported by all read methods.
 
@@ -105,8 +104,8 @@ When IIS responds with HTTP `404` or `400` (no list, missing resource, or endpoi
 
 - Core runtime API: `createBsuirClient`, `BsuirClient`
 - Client/runtime option types: `BsuirClientOptions`, `CacheOptions`, `ClientHooks`, `RequestOptions`, `ReadOptions`, `RequestHookContext`, `RetryHookContext`, `ResponseHookContext`, `ErrorHookContext`
-- Schedule utilities: `normalizeSchedule`, `filterLessons`, `ScheduleFilterOptions`
-- Error classes: `BsuirApiError`, `BsuirNetworkError`, `BsuirTimeoutError`, `BsuirValidationError`, `BsuirResponseValidationError`, `BsuirConfigurationError`
+- Schedule utilities: `normalizeSchedule`, `filterLessons`, `getLessonsForDate`, `getTodayLessons`, `getTomorrowLessons`, `getLessonsForWeek`, `sortLessonsByTime`, `groupLessonsByDay`, `getCurrentLesson`, `getNextLesson`, `buildScheduleDays`, `ScheduleFilterOptions`
+- Error classes: `BsuirApiError`, `BsuirNetworkError`, `BsuirTimeoutError`, `BsuirValidationError`, `BsuirResponseValidationError`, `BsuirResponsePayloadTooLargeError`, `BsuirConfigurationError`
 - Domain types: `Announcement`, `ApiDateResponse`, `Auditory`, `AuditoryDepartment`, `AuditoryType`, `BuildingNumber`, `Department`, `EducationForm`, `Employee`, `EmployeeCatalogItem`, `Faculty`, `FlattenedLessonsByDay`, `FlattenedScheduleItem`, `LessonStudentGroup`, `Maybe`, `NormalizedScheduleResponse`, `ScheduleItem`, `ScheduleResponse`, `Speciality`, `StudentGroupCatalogItem`, `StudentGroupShort`, `Weekday`, `WeekScheduleMap`
 
 ## Errors
@@ -114,7 +113,7 @@ 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).
-- `BsuirApiError` is also used when response body size exceeds configured `maxResponseBytes`.
+- `BsuirResponsePayloadTooLargeError` when response body size exceeds configured `maxResponseBytes`.
 - `BsuirNetworkError` for transport errors (contains `endpoint` and standard `cause`)
 - `BsuirResponseValidationError` for invalid payload shapes when `validateResponses: true`
 - `BsuirTimeoutError` for timeouts (contains `endpoint`, `timeoutMs`)
@@ -126,7 +125,7 @@ Validation rules:
 - `groupNumber` must contain digits only
 - `urlId` must be a slug with letters/digits/hyphens (for example `s-nesterenkov`)
 - `id` and `subgroup` parameters must be positive integers
-Retry and abort behavior:
+  Retry and abort behavior:
 
 - Retries are applied to GET requests for transport/network errors and HTTP `429`, `500`, `502`, `503`, `504`
 - `Retry-After` is respected for retriable responses
@@ -142,7 +141,7 @@ For **2xx** responses the client reads the body as text, then applies `JSON.pars
 - 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.
-- If response body size exceeds `maxResponseBytes`, the client throws `BsuirApiError`.
+- If response body size exceeds `maxResponseBytes`, the client throws `BsuirResponsePayloadTooLargeError`.
 
 ## Raw vs normalized schedule response
 
@@ -152,11 +151,10 @@ By default, schedule methods return a **normalized** `NormalizedScheduleResponse
 import { createBsuirClient } from "bsuir-iis-api";
 
 const client = createBsuirClient();
-const raw = await client.schedule.getGroup("053503", { raw: true });
+const raw = await client.schedule.getGroupRaw("053503");
 ```
 
-Use `defaultRaw: true` in `createBsuirClient` to change global behavior.
-When `raw` is omitted, `getGroup()` and `getEmployee()` follow client `defaultRaw` (`false` by default, so normalized unless explicitly changed to `true`).
+Use explicit helpers `getGroupRaw` / `getEmployeeRaw` to obtain raw envelopes. `getGroup()` / `getEmployee()` return normalized payloads by default.
 In raw mode API may return `schedules: null`; normalized mode always converts it to `{}`.
 In raw mode some lesson fields may also be nullable (`weekNumber`, `lessonTypeAbbrev`), so keep null checks if you consume raw payload directly.
 README examples match the installed package version; if types and docs ever diverge, rely on `NormalizedScheduleResponse` / `ScheduleResponse` from the same release.
@@ -185,6 +183,17 @@ const client = createBsuirClient();
 const subgroupLessons = await client.schedule.getEmployeeBySubgroup("s-nesterenkov", 1);
 ```
 
+## Schedule helpers for UI
+
+```ts
+import { buildScheduleDays, getTodayLessons } from "bsuir-iis-api";
+
+const todayLessons = getTodayLessons(schedule, new Date());
+const days = buildScheduleDays(schedule, { days: 7, includeEmptyDays: false });
+```
+
+Use `getCurrentLesson(days[0].lessons)` / `getNextLesson(days[0].lessons)` for in-day progress indicators.
+
 ## Development
 
 ```bash
@@ -218,9 +227,11 @@ CI has a manual `workflow_dispatch` path that also runs live contracts (`live-co
 ## Release checklist
 
 1. Run `npm run check:full`.
-2. Update version and `CHANGELOG.md` in the same release commit.
-3. Push to `main` to trigger GitHub Actions release workflow.
-4. Verify published package in a clean project:
+2. Add or update a `.changeset/*.md` entry for user-visible changes.
+3. Run `npx changeset version` to bump `package.json`, update `CHANGELOG.md`, and consume changesets.
+4. Run `npm run api:report:check` and `npm run release:dry`.
+5. Push to `main` to trigger GitHub Actions release workflow.
+6. Verify published package in a clean project:
 
 ```bash
 mkdir bsuir-iis-smoke && cd bsuir-iis-smoke
@@ -229,7 +240,7 @@ npm install bsuir-iis-api@latest
 node -e "import('bsuir-iis-api').then(m=>console.log(typeof m.createBsuirClient))"
 ```
 
-The project keeps `CHANGELOG.md` manually curated for stable release notes.
+The project uses Changesets for version bumps and changelog generation; edit pending changeset text before versioning when release notes need refinement.
 
 ## License