bsuir-iis-api 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,18 +1,44 @@
 # Changelog
 
-## 0.9.0
+## [0.10.0] - 2026-05-13
 
-### Minor Changes
+### Added
+
+- `createBsuirClient` options: `allowedBaseUrlHosts`, `allowInsecureHttp`, and `maxResponseBytes`.
+- HTTP internals split into focused modules under `src/client/http/*` (`requestJson`, `response`, `cache`, `retry`, `url`).
+- Schedule internals split into `scheduleApi`, `scheduleFilter`, and `scheduleNormalize`.
+- Shared `createListModule` used by catalog modules to remove duplicated list/read logic.
+- CI/release workflows now generate CycloneDX SBOM (`sbom.cdx.json`) on Node 24.
+
+### Changed
+
+- `createBsuirClient` now validates and normalizes `baseUrl` strictly (absolute URL, no credentials/query/hash, host allowlist, HTTPS by default).
+- `validateResponses` is now enabled by default.
+- Example scripts now fail with non-zero exit code on unhandled errors.
+- GitHub Actions in CI/release workflows are pinned to commit SHAs.
+- Dev dependencies in `package.json` are now pinned to exact versions.
+
+### Fixed
+
+- Response parser now enforces `maxResponseBytes` for both `Content-Length` pre-checks and streamed body reads.
+- `BsuirTimeoutError` now preserves upstream abort timeout cause.
+- Public API report updates for schedule typings (`FlattenedLessonsByDay` and `lessonTypeAbbrev`) and utility export documentation.
+
+## [0.9.1] - 2026-05-10
 
-- 323feb4: New public APIs, cache, hooks, deps versions update, new JSdoc, etc.
+### Fixed
+
+- `http.ts`: cache eviction now performs true LRU — entries are sorted by `accessedAt` timestamp before eviction instead of relying on Map insertion order (which produced FIFO behaviour, not LRU).
+- `http.ts`: `setCache` now removes the key before re-inserting on a cache refresh, ensuring Map insertion order stays consistent with actual last-write time.
+- `http.ts`: `canUseCaching` and `canUseDedup` now check `config.signal?.aborted` in addition to per-request `options.signal`; previously a globally aborted client signal did not suppress cache reads, which could return stale data after cancellation.
 
-All notable changes to this project are documented in this file.
+### Documentation
 
-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.
+- `types.ts`: all `BsuirClientOptions` fields now have full JSDoc — description, `@defaultValue`, `@example`, and side-effect notes where applicable.
+- `types.ts`: `validateResponses` JSDoc explicitly recommends `process.env.NODE_ENV !== "production"` as a sensible default pattern and clarifies the performance trade-off.
+- `types.ts`: `signal` JSDoc clarifies that an aborted global signal suppresses both cache reads and in-flight deduplication.
 
-## [0.8.0] - 2026-05-10
+## [0.9.0] - 2026-05-10
 
 ### Added
 

package/README.md

@@ -33,6 +33,8 @@ console.log(schedule.lessons.length);
 ```ts
 const client = createBsuirClient({
   baseUrl: "https://iis.bsuir.by/api/v1",
+  allowedBaseUrlHosts: ["iis.bsuir.by"],
+  allowInsecureHttp: false,
   timeoutMs: 10000,
   retries: 2,
   retryDelayMs: 300,
@@ -40,7 +42,8 @@ const client = createBsuirClient({
   retryJitter: true,
   cache: { ttlMs: 60_000, maxEntries: 200 },
   dedupeInFlight: true,
-  validateResponses: false,
+  maxResponseBytes: 5_000_000,
+  validateResponses: true,
   hooks: {
     onRetry: ({ endpoint, delayMs, reason }) => {
       console.log("retry", endpoint, delayMs, reason);
@@ -51,10 +54,14 @@ const client = createBsuirClient({
 ```
 
 - `fetch` can be passed for custom runtime/testing.
+- `baseUrl` is normalized and validated (absolute URL, no credentials/query/hash, host allowlist).
+- `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).
-- `validateResponses` enables runtime payload-shape checks for key endpoints.
+- `maxResponseBytes` limits body size per response to protect against memory spikes.
+- `validateResponses` enables runtime payload-shape checks for key endpoints (enabled by default).
 - `hooks` provides lifecycle callbacks (`onRequest`, `onRetry`, `onResponse`, `onError`) for observability.
 - `AbortSignal` is supported by all read methods.
 

package/dist/_tsup-dts-rollup.d.ts

@@ -88,43 +88,205 @@ export { BsuirClient as BsuirClient_alias_1 }
  * Options accepted by `createBsuirClient`.
  */
 declare interface BsuirClientOptions {
+    /**
+     * Base URL of the BSUIR IIS API.
+     *
+     * @defaultValue "https://iis.bsuir.by/api/v1"
+     */
     baseUrl?: string;
+    /**
+     * Allows using `http://` for `baseUrl`.
+     *
+     * Keep disabled unless you explicitly need local/non-TLS endpoints in tests.
+     *
+     * @defaultValue false
+     */
+    allowInsecureHttp?: boolean;
+    /**
+     * Allowed hostnames for `baseUrl`.
+     *
+     * Requests are rejected if `baseUrl` hostname is not in this list.
+     *
+     * @defaultValue ["iis.bsuir.by"]
+     */
+    allowedBaseUrlHosts?: string[];
+    /**
+     * Custom `fetch` implementation. Useful for environments where the global
+     * `fetch` is unavailable (older Node.js versions) or when you want to wrap
+     * requests with a proxy, MSW handler, or test mock.
+     *
+     * @defaultValue globalThis.fetch
+     * @example
+     * ```ts
+     * import nodeFetch from "node-fetch";
+     * const client = createBsuirClient({ fetch: nodeFetch as typeof fetch });
+     * ```
+     */
     fetch?: typeof globalThis.fetch;
-    /** Optional global signal to cancel all client requests. */
+    /**
+     * Global `AbortSignal` that cancels **all** requests made by this client
+     * instance. Per-call signals are combined with this one.
+     *
+     * Note: caching and in-flight deduplication are disabled for requests that
+     * carry a signal (per-call or global) to prevent stale data from being
+     * returned after cancellation.
+     */
     signal?: AbortSignal;
-    /** Request timeout per attempt, in milliseconds. */
+    /**
+     * Request timeout per attempt, in milliseconds.
+     *
+     * If a single fetch attempt does not complete within this window it is
+     * aborted and a `BsuirTimeoutError` is thrown (or the request is retried
+     * if retries remain).
+     *
+     * @defaultValue 10_000 (10 seconds)
+     */
     timeoutMs?: number;
-    /** Number of retry attempts for retriable GET failures. */
+    /**
+     * Number of additional retry attempts for retriable GET failures (HTTP 429,
+     * 500, 502, 503, 504 and network errors). Set to `0` to disable retries.
+     *
+     * @defaultValue 1
+     */
     retries?: number;
-    /** Base retry delay before backoff, in milliseconds. */
+    /**
+     * Base delay before the first retry, in milliseconds. Subsequent retries use
+     * exponential backoff: `retryDelayMs * 2^attempt`, capped by `retryMaxDelayMs`.
+     *
+     * @defaultValue 300
+     */
     retryDelayMs?: number;
-    /** Upper bound for retry delay, in milliseconds. */
+    /**
+     * Upper bound for the retry delay after backoff, in milliseconds.
+     *
+     * @defaultValue 3_000 (3 seconds)
+     */
     retryMaxDelayMs?: number;
-    /** Enable jitter for retry backoff to avoid synchronized retries. */
+    /**
+     * When `true`, a random jitter factor (±25 %) is applied to each retry delay
+     * to avoid synchronized retries from multiple clients hitting the API at the
+     * same time.
+     *
+     * @defaultValue true
+     */
     retryJitter?: boolean;
-    /** Optional User-Agent header (used mainly in Node.js runtimes). */
+    /**
+     * Value sent as the `User-Agent` request header. Mainly useful in Node.js
+     * environments where servers can log the client identity.
+     *
+     * @example
+     * ```ts
+     * const client = createBsuirClient({ userAgent: "my-app/1.0.0" });
+     * ```
+     */
     userAgent?: string;
-    /** In-memory cache configuration for successful GET responses. */
+    /**
+     * In-memory response cache configuration for successful GET requests.
+     *
+     * When configured, responses are stored in a `Map` keyed by the full request
+     * URL. Cache hits skip the network entirely and fire `onResponse` with
+     * `fromCache: true`. The cache uses a true LRU eviction policy — the
+     * least-recently-*read* entry is evicted first when `maxEntries` is exceeded.
+     *
+     * Caching is automatically skipped for requests that carry an `AbortSignal`
+     * (per-call or global) to prevent serving stale data after cancellation.
+     *
+     * @example
+     * ```ts
+     * // Cache for 5 minutes, keep at most 500 entries
+     * const client = createBsuirClient({
+     *   cache: { ttlMs: 5 * 60 * 1000, maxEntries: 500 },
+     * });
+     * ```
+     */
     cache?: CacheOptions;
-    /** Enables in-flight GET request deduplication by URL. */
+    /**
+     * Enables in-flight GET request deduplication by full URL.
+     *
+     * When two identical GET requests are made concurrently, only the first one
+     * hits the network; the second one awaits the same `Promise`. This prevents
+     * duplicate API calls in scenarios like parallel component rendering.
+     *
+     * Disabled automatically when the request carries an `AbortSignal`.
+     *
+     * @defaultValue true
+     */
     dedupeInFlight?: boolean;
-    /** Enables runtime validation of API response shapes. */
+    /**
+     * Maximum allowed response body size (in bytes) for a single request.
+     *
+     * Helps prevent excessive memory usage on unexpectedly large payloads.
+     *
+     * @defaultValue 5_000_000 (5 MB)
+     */
+    maxResponseBytes?: number;
+    /**
+     * Enables runtime shape validation of API responses.
+     *
+     * When `true`, each response is checked against the expected TypeScript type
+     * at runtime. An `BsuirApiError` is thrown if the payload does not match,
+     * which makes integration issues with the upstream API visible immediately
+     * instead of causing silent type-cast bugs later.
+     *
+     * **Recommended to enable during development and in test environments.**
+     * Can be left `false` in production for a small performance gain.
+     *
+     * @defaultValue true
+     *
+     * @example
+     * ```ts
+     * // Enable only in non-production environments
+     * const client = createBsuirClient({
+     *   validateResponses: process.env.NODE_ENV !== "production",
+     * });
+     * ```
+     */
     validateResponses?: boolean;
-    /** Lifecycle hooks for request/response/retry/error events. */
+    /**
+     * Lifecycle hooks called at various stages of the request pipeline.
+     *
+     * Useful for logging, metrics collection, or custom error reporting.
+     *
+     * @example
+     * ```ts
+     * const client = createBsuirClient({
+     *   hooks: {
+     *     onRequest: ({ method, path }) => console.log(`→ ${method} ${path}`),
+     *     onResponse: ({ path, durationMs, fromCache }) =>
+     *       console.log(`← ${path} ${durationMs}ms${fromCache ? " (cache)" : ""}`),
+     *     onRetry: ({ path, attempt, reason }) =>
+     *       console.warn(`↺ ${path} retry #${attempt} (${reason})`),
+     *     onError: ({ path, error }) => console.error(`✗ ${path}`, error),
+     *   },
+     * });
+     * ```
+     */
     hooks?: ClientHooks;
     /**
-     * Force raw API payload for schedule endpoints by default.
-     * This changes return types for `schedule.getGroup/getEmployee` when `raw` is omitted.
+     * Controls the default return type of `schedule.getGroup` and
+     * `schedule.getEmployee` when the per-call `raw` option is omitted.
+     *
+     * - `false` (default) — returns `NormalizedScheduleResponse` with flattened
+     *   `lessons`, `lessonsByDay`, `scheduleLessons`, and `examLessons` arrays.
+     * - `true` — returns the raw `ScheduleResponse` exactly as received from the
+     *   BSUIR IIS API.
      *
-     * Per-call `raw` option always takes precedence over this default.
+     * A per-call `raw` option always takes precedence over this default.
+     *
+     * @defaultValue false
      *
      * @example
      * ```ts
-     * const client = createBsuirClient({ defaultRaw: true });
-     * // Returns ScheduleResponse (raw)
-     * const raw = await client.schedule.getGroup("053503");
-     * // Returns NormalizedScheduleResponse (per-call override)
-     * const normalized = await client.schedule.getGroup("053503", { raw: false });
+     * // Normalized (default):
+     * const client = createBsuirClient();
+     * const norm = await client.schedule.getGroup("053503"); // NormalizedScheduleResponse
+     *
+     * // Raw by default:
+     * const rawClient = createBsuirClient({ defaultRaw: true });
+     * const raw = await rawClient.schedule.getGroup("053503"); // ScheduleResponse
+     *
+     * // Per-call override (always wins):
+     * const override = await client.schedule.getGroup("053503", { raw: true }); // ScheduleResponse
      * ```
      */
     defaultRaw?: boolean;
@@ -210,13 +372,32 @@ export { BuildingNumber }
 export { BuildingNumber as BuildingNumber_alias_1 }
 export { BuildingNumber as BuildingNumber_alias_2 }
 
+/**
+ * Builds absolute endpoint URL from base URL, path and query params.
+ */
+export declare function buildUrl(baseUrl: string, path: string, query?: QueryParams): string;
+
 declare interface CacheOptions {
     /**
      * Cache TTL for successful GET responses, in milliseconds.
+     *
+     * After this duration has elapsed the cached entry is considered stale and
+     * the next request will hit the network again.
+     *
+     * @example
+     * ```ts
+     * // Cache responses for 5 minutes
+     * const client = createBsuirClient({ cache: { ttlMs: 5 * 60 * 1000 } });
+     * ```
      */
     ttlMs: number;
     /**
-     * Maximum number of cached entries kept in memory.
+     * Maximum number of entries kept in the in-memory cache.
+     *
+     * When the limit is exceeded the least-recently-used (LRU) entries are evicted
+     * first. Expired entries are always removed before LRU eviction runs.
+     *
+     * @defaultValue 200
      */
     maxEntries?: number;
 }
@@ -245,15 +426,10 @@ declare function createAnnouncementsModule(config: Readonly<InternalClientConfig
 export { createAnnouncementsModule }
 export { createAnnouncementsModule as createAnnouncementsModule_alias_1 }
 
+/**
+ * Creates API module for `/auditories`.
+ */
 declare function createAuditoriesModule(config: Readonly<InternalClientConfig>): {
-    /**
-     * Returns the full list of auditories from `/auditories`.
-     * If the caller aborts `options.signal`, the platform propagates `AbortError` (not wrapped by the SDK).
-     *
-     * @throws {BsuirApiError} When the API returns a non-success HTTP status
-     * @throws {BsuirNetworkError} On transport failures after retries
-     * @throws {BsuirTimeoutError} When the request exceeds `timeoutMs`
-     */
     listAll(options?: ReadOptions): Promise<Auditory[]>;
 };
 export { createAuditoriesModule }
@@ -288,57 +464,37 @@ declare function createBsuirClient(options?: BsuirClientOptions & {
 export { createBsuirClient }
 export { createBsuirClient as createBsuirClient_alias_1 }
 
+/**
+ * Creates API module for `/departments`.
+ */
 declare function createDepartmentsModule(config: Readonly<InternalClientConfig>): {
-    /**
-     * Returns the full list of departments from `/departments`.
-     * If the caller aborts `options.signal`, the platform propagates `AbortError` (not wrapped by the SDK).
-     *
-     * @throws {BsuirApiError} When the API returns a non-success HTTP status
-     * @throws {BsuirNetworkError} On transport failures after retries
-     * @throws {BsuirTimeoutError} When the request exceeds `timeoutMs`
-     */
     listAll(options?: ReadOptions): Promise<Department[]>;
 };
 export { createDepartmentsModule }
 export { createDepartmentsModule as createDepartmentsModule_alias_1 }
 
+/**
+ * Creates API module for `/employees/all`.
+ */
 declare function createEmployeesModule(config: Readonly<InternalClientConfig>): {
-    /**
-     * Returns the full list of employees from `/employees/all`.
-     * If the caller aborts `options.signal`, the platform propagates `AbortError` (not wrapped by the SDK).
-     *
-     * @throws {BsuirApiError} When the API returns a non-success HTTP status
-     * @throws {BsuirNetworkError} On transport failures after retries
-     * @throws {BsuirTimeoutError} When the request exceeds `timeoutMs`
-     */
     listAll(options?: ReadOptions): Promise<EmployeeCatalogItem[]>;
 };
 export { createEmployeesModule }
 export { createEmployeesModule as createEmployeesModule_alias_1 }
 
+/**
+ * Creates API module for `/faculties`.
+ */
 declare function createFacultiesModule(config: Readonly<InternalClientConfig>): {
-    /**
-     * Returns the full list of faculties from `/faculties`.
-     * If the caller aborts `options.signal`, the platform propagates `AbortError` (not wrapped by the SDK).
-     *
-     * @throws {BsuirApiError} When the API returns a non-success HTTP status
-     * @throws {BsuirNetworkError} On transport failures after retries
-     * @throws {BsuirTimeoutError} When the request exceeds `timeoutMs`
-     */
     listAll(options?: ReadOptions): Promise<Faculty[]>;
 };
 export { createFacultiesModule }
 export { createFacultiesModule as createFacultiesModule_alias_1 }
 
+/**
+ * Creates API module for `/student-groups`.
+ */
 declare function createGroupsModule(config: Readonly<InternalClientConfig>): {
-    /**
-     * Returns the full list of student groups from `/student-groups`.
-     * If the caller aborts `options.signal`, the platform propagates `AbortError` (not wrapped by the SDK).
-     *
-     * @throws {BsuirApiError} When the API returns a non-success HTTP status
-     * @throws {BsuirNetworkError} On transport failures after retries
-     * @throws {BsuirTimeoutError} When the request exceeds `timeoutMs`
-     */
     listAll(options?: ReadOptions): Promise<StudentGroupCatalogItem[]>;
 };
 export { createGroupsModule }
@@ -346,6 +502,19 @@ export { createGroupsModule as createGroupsModule_alias_1 }
 
 export declare function createJsonResponse({ status, headers, body }: MockResponseInit): Response;
 
+/**
+ * Creates a simple catalog-like module exposing `listAll()` for a fixed endpoint.
+ */
+export declare function createListModule<T>(config: Readonly<InternalClientConfig>, endpoint: string): {
+    /**
+     * Returns all items from the configured endpoint.
+     */
+    listAll(options?: ReadOptions): Promise<T[]>;
+};
+
+/**
+ * Creates schedule API module with raw/normalized response support.
+ */
 declare function createScheduleModule<TRawDefault extends boolean>(config: Readonly<InternalClientConfig<TRawDefault>>): {
     getGroup: <TRaw extends boolean | undefined = undefined>(groupNumber: string, options?: ReadOptions & {
         raw?: TRaw;
@@ -355,14 +524,25 @@ declare function createScheduleModule<TRawDefault extends boolean>(config: Reado
     }) => Promise<ScheduleResponseByRawOption<TRaw, TRawDefault>>;
     getGroupFiltered: (groupNumber: string, filter: ScheduleFilterOptions, options?: ReadOptions) => Promise<FlattenedScheduleItem[]>;
     getEmployeeFiltered: (urlId: string, filter: ScheduleFilterOptions, options?: ReadOptions) => Promise<FlattenedScheduleItem[]>;
+    /**
+     * Returns exams for a group.
+     */
     getGroupExams(groupNumber: string, options?: ReadOptions): Promise<FlattenedScheduleItem[]>;
+    /**
+     * Returns exams for an employee.
+     */
     getEmployeeExams(urlId: string, options?: ReadOptions): Promise<FlattenedScheduleItem[]>;
+    /**
+     * Returns regular schedule lessons of a specific subgroup for a group.
+     */
     getGroupBySubgroup(groupNumber: string, subgroup: number, options?: ReadOptions): Promise<FlattenedScheduleItem[]>;
+    /**
+     * Returns regular schedule lessons of a specific subgroup for an employee.
+     */
     getEmployeeBySubgroup(urlId: string, subgroup: number, options?: ReadOptions): Promise<FlattenedScheduleItem[]>;
     getCurrentWeek: (options?: ReadOptions) => Promise<number>;
     /**
-     * Calls IIS `/last-update-date/student-group`. That route is legacy and unsupported on the server;
-     * it may return an error for newer group numbers (e.g. six-digit `524404`).
+     * Calls IIS `/last-update-date/student-group`.
      */
     getLastUpdateByGroup(params: {
         groupNumber: string;
@@ -370,8 +550,7 @@ declare function createScheduleModule<TRawDefault extends boolean>(config: Reado
         id: number;
     }, options?: ReadOptions): Promise<ApiDateResponse>;
     /**
-     * Calls IIS `/last-update-date/employee`. That route is legacy and unsupported on the server; prefer
-     * not relying on it for critical cache logic.
+     * Calls IIS `/last-update-date/employee`.
      */
     getLastUpdateByEmployee(params: {
         urlId: string;
@@ -381,16 +560,12 @@ declare function createScheduleModule<TRawDefault extends boolean>(config: Reado
 };
 export { createScheduleModule }
 export { createScheduleModule as createScheduleModule_alias_1 }
+export { createScheduleModule as createScheduleModule_alias_2 }
 
+/**
+ * Creates API module for `/specialities`.
+ */
 declare function createSpecialitiesModule(config: Readonly<InternalClientConfig>): {
-    /**
-     * Returns the full list of specialities from `/specialities`.
-     * If the caller aborts `options.signal`, the platform propagates `AbortError` (not wrapped by the SDK).
-     *
-     * @throws {BsuirApiError} When the API returns a non-success HTTP status
-     * @throws {BsuirNetworkError} On transport failures after retries
-     * @throws {BsuirTimeoutError} When the request exceeds `timeoutMs`
-     */
     listAll(options?: ReadOptions): Promise<Speciality[]>;
 };
 export { createSpecialitiesModule }
@@ -469,24 +644,12 @@ export { Faculty as Faculty_alias_1 }
 export { Faculty as Faculty_alias_2 }
 
 /**
- * Filters normalized schedule lessons by specified criteria.
- *
- * @param response - Normalized schedule response containing lessons
- * @param filter - Filter options with optional fields: source, weekday, weekNumber, subgroup,
- *                 lessonTypeAbbrev, subjectQuery, employeeUrlId, auditory
- * @returns Array of lessons matching all provided filter criteria
- *
- * @example
- * ```ts
- * const schedule = await client.schedule.getGroup("053503");
- * const mondayLessons = filterLessons(schedule, { weekday: "Понедельник" });
- * const practiceLessons = filterLessons(schedule, { lessonTypeAbbrev: "пр" });
- * const lectureLessons = filterLessons(schedule, { lessonTypeAbbrev: ["лк", "лекция"] });
- * ```
+ * Filters normalized schedule lessons by criteria.
  */
 declare function filterLessons(response: NormalizedScheduleResponse, filter: ScheduleFilterOptions): FlattenedScheduleItem[];
 export { filterLessons }
 export { filterLessons as filterLessons_alias_1 }
+export { filterLessons as filterLessons_alias_2 }
 
 declare type FlattenedLessonsByDay = Record<Weekday, FlattenedScheduleItem[]>;
 export { FlattenedLessonsByDay }
@@ -501,6 +664,11 @@ export { FlattenedScheduleItem }
 export { FlattenedScheduleItem as FlattenedScheduleItem_alias_1 }
 export { FlattenedScheduleItem as FlattenedScheduleItem_alias_2 }
 
+/**
+ * Calculates retry delay using `Retry-After` when present, otherwise exponential backoff.
+ */
+export declare function getRetryDelayMs(config: Readonly<InternalClientConfig>, attempt: number, retryAfterHeader?: string | null): number;
+
 export declare interface InternalClientConfig<TRawDefault extends boolean = boolean> {
     baseUrl: string;
     fetchImpl: typeof globalThis.fetch;
@@ -514,6 +682,7 @@ export declare interface InternalClientConfig<TRawDefault extends boolean = bool
     cacheTtlMs: number | undefined;
     cacheMaxEntries: number;
     dedupeInFlight: boolean;
+    maxResponseBytes: number;
     validateResponses: boolean;
     hooks: ClientHooks;
     responseCache: Map<string, {
@@ -581,29 +750,18 @@ export { NormalizedScheduleResponse as NormalizedScheduleResponse_alias_1 }
 export { NormalizedScheduleResponse as NormalizedScheduleResponse_alias_2 }
 
 /**
- * Transforms raw API schedule response into a normalized structure with flattened lessons.
- *
- * Raw API response contains lessons grouped by weekday (`schedules` object with day keys)
- * and exams in a separate array. This function flattens them into a single `lessons` array
- * for easier filtering and iteration, while preserving day-grouped view in `lessonsByDay`.
- *
- * @param response - Raw schedule response from API
- * @returns Normalized schedule with additional computed fields: `lessons` (flattened array),
- *          `lessonsByDay` (grouped by weekday), `scheduleLessons`, and `examLessons`
- *
- * @example
- * ```ts
- * const rawSchedule = await client.schedule.getGroup("053503", { raw: true });
- * const normalized = normalizeSchedule(rawSchedule);
- * console.log(normalized.lessons.length); // All lessons + exams flattened
- * console.log(normalized.lessonsByDay["Понедельник"]); // Monday-only lessons
- * console.log(normalized.scheduleLessons.length); // Only regular schedule
- * console.log(normalized.examLessons.length); // Only exams
- * ```
+ * Transforms raw schedule response into normalized structure with flattened lessons.
  */
 declare function normalizeSchedule(response: ScheduleResponse): NormalizedScheduleResponse;
 export { normalizeSchedule }
 export { normalizeSchedule as normalizeSchedule_alias_1 }
+export { normalizeSchedule as normalizeSchedule_alias_2 }
+
+/**
+ * Parses response body as JSON when possible, otherwise returns text.
+ * Throws `BsuirApiError` for declared JSON payloads that are empty/invalid.
+ */
+export declare function parseBody(response: Response, maxResponseBytes: number): Promise<unknown>;
 
 /**
  * Normalizes current week payload from API to a positive integer.
@@ -644,7 +802,12 @@ declare interface RequestHookContext {
 export { RequestHookContext }
 export { RequestHookContext as RequestHookContext_alias_1 }
 
-export declare function requestJson<T>(config: Readonly<InternalClientConfig>, path: string, options?: RequestOptions): Promise<T>;
+/**
+ * Executes JSON HTTP request with timeout, retry/backoff, deduplication and cache support.
+ */
+declare function requestJson<T>(config: Readonly<InternalClientConfig>, path: string, options?: RequestOptions): Promise<T>;
+export { requestJson }
+export { requestJson as requestJson_alias_1 }
 
 export declare type RequestMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
 
@@ -684,6 +847,9 @@ declare interface ResponseHookContext extends RequestHookContext {
 export { ResponseHookContext }
 export { ResponseHookContext as ResponseHookContext_alias_1 }
 
+/** HTTP status codes retriable by the request pipeline. */
+export declare const RETRIABLE_STATUS_CODES: Set<number>;
+
 declare interface RetryHookContext extends RequestHookContext {
     delayMs: number;
     reason: "http_status" | "network_error";
@@ -744,6 +910,14 @@ export { ScheduleResponse as ScheduleResponse_alias_2 }
 
 declare type ScheduleResponseByRawOption<TRaw extends boolean | undefined, TRawDefault extends boolean> = TRaw extends true ? ScheduleResponse : TRaw extends false ? NormalizedScheduleResponse : TRawDefault extends true ? ScheduleResponse : NormalizedScheduleResponse;
 
+/**
+ * Writes response value to cache and performs eviction when size approaches capacity.
+ */
+export declare function setCache(config: Readonly<InternalClientConfig>, key: string, value: unknown): void;
+
+/** Delays execution for a specified number of milliseconds. */
+export declare function sleep(ms: number): Promise<void>;
+
 declare interface Speciality {
     id: number;
     name: string;
@@ -781,6 +955,11 @@ export { StudentGroupShort }
 export { StudentGroupShort as StudentGroupShort_alias_1 }
 export { StudentGroupShort as StudentGroupShort_alias_2 }
 
+/**
+ * Reads a cached response value by key, applying TTL validation and LRU touch update.
+ */
+export declare function tryReadCache(config: Readonly<InternalClientConfig>, key: string): unknown;
+
 declare type Weekday = "Понедельник" | "Вторник" | "Среда" | "Четверг" | "Пятница" | "Суббота";
 export { Weekday }
 export { Weekday as Weekday_alias_1 }