bsuir-iis-api 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -1,12 +1,50 @@
 # 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
 

package/README.md

@@ -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,7 +97,8 @@ 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 })`
@@ -151,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.

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

@@ -21,6 +21,10 @@ export { ApiDateResponse }
 export { ApiDateResponse as ApiDateResponse_alias_1 }
 export { ApiDateResponse as ApiDateResponse_alias_2 }
 
+export declare function assertApiDateResponse(payload: unknown, endpoint: string): asserts payload is ApiDateResponse;
+
+export declare function assertArrayResponse(payload: unknown, endpoint: string): asserts payload is unknown[];
+
 export declare function assertEmployeeUrlId(value: unknown, fieldName?: string): asserts value is string;
 
 export declare function assertGroupNumber(value: unknown, fieldName?: string): asserts value is string;
@@ -29,6 +33,8 @@ export declare function assertNonEmptyString(value: unknown, fieldName: string):
 
 export declare function assertPositiveInt(value: unknown, fieldName: string): asserts value is number;
 
+export declare function assertScheduleResponse(payload: unknown, endpoint: string): asserts payload is ScheduleResponse;
+
 declare interface Auditory {
     id: number;
     name: string;
@@ -71,18 +77,21 @@ export { BsuirApiError }
 export { BsuirApiError as BsuirApiError_alias_1 }
 
 /**
- * Public client contract returned by {@link createBsuirClient}.
+ * Public client contract returned by `createBsuirClient`.
+ * Use `BsuirClientShape<true>` or `BsuirClientShape<false>` for typed overloads.
  */
 declare type BsuirClient = ReturnType<typeof createBsuirClient>;
 export { BsuirClient }
 export { BsuirClient as BsuirClient_alias_1 }
 
 /**
- * Options accepted by {@link createBsuirClient}.
+ * Options accepted by `createBsuirClient`.
  */
 declare interface BsuirClientOptions {
     baseUrl?: string;
     fetch?: typeof globalThis.fetch;
+    /** Optional global signal to cancel all client requests. */
+    signal?: AbortSignal;
     /** Request timeout per attempt, in milliseconds. */
     timeoutMs?: number;
     /** Number of retry attempts for retriable GET failures. */
@@ -95,12 +104,70 @@ declare interface BsuirClientOptions {
     retryJitter?: boolean;
     /** Optional User-Agent header (used mainly in Node.js runtimes). */
     userAgent?: string;
-    /** Force raw API payload for schedule endpoints by default. */
+    /** In-memory cache configuration for successful GET responses. */
+    cache?: CacheOptions;
+    /** Enables in-flight GET request deduplication by URL. */
+    dedupeInFlight?: boolean;
+    /** Enables runtime validation of API response shapes. */
+    validateResponses?: boolean;
+    /** Lifecycle hooks for request/response/retry/error events. */
+    hooks?: ClientHooks;
+    /**
+     * Force raw API payload for schedule endpoints by default.
+     * This changes return types for `schedule.getGroup/getEmployee` when `raw` is omitted.
+     *
+     * Per-call `raw` option always takes precedence over this default.
+     *
+     * @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 });
+     * ```
+     */
     defaultRaw?: boolean;
 }
 export { BsuirClientOptions }
 export { BsuirClientOptions as BsuirClientOptions_alias_1 }
 
+/**
+ * Fully-typed public shape of the BSUIR API client.
+ * All module types are inlined so API Extractor never needs to reach into private helpers.
+ *
+ * `TRawDefault` controls the default return type of
+ * `schedule.getGroup` / `schedule.getEmployee` when the per-call `raw` option is omitted:
+ * - `false` (default) → returns `NormalizedScheduleResponse`
+ * - `true`            → returns `ScheduleResponse` (raw API payload)
+ *
+ * Per-call `raw` always takes precedence over this default.
+ *
+ * @example
+ * ```ts
+ * // Default (normalized):
+ * 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
+ * ```
+ */
+export declare interface BsuirClientShape<TRawDefault extends boolean> {
+    schedule: ReturnType<typeof createScheduleModule<TRawDefault>>;
+    groups: ReturnType<typeof createGroupsModule>;
+    employees: ReturnType<typeof createEmployeesModule>;
+    faculties: ReturnType<typeof createFacultiesModule>;
+    departments: ReturnType<typeof createDepartmentsModule>;
+    specialities: ReturnType<typeof createSpecialitiesModule>;
+    announcements: ReturnType<typeof createAnnouncementsModule>;
+    auditories: ReturnType<typeof createAuditoriesModule>;
+}
+
 declare class BsuirConfigurationError extends Error {
     constructor(message: string);
 }
@@ -109,16 +176,22 @@ export { BsuirConfigurationError as BsuirConfigurationError_alias_1 }
 
 declare class BsuirNetworkError extends Error {
     readonly endpoint: string;
-    readonly causeError: unknown;
-    constructor(message: string, endpoint: string, causeError: unknown);
+    constructor(message: string, endpoint: string, cause: unknown);
 }
 export { BsuirNetworkError }
 export { BsuirNetworkError as BsuirNetworkError_alias_1 }
 
+declare class BsuirResponseValidationError extends Error {
+    readonly endpoint: string;
+    constructor(message: string, endpoint: string);
+}
+export { BsuirResponseValidationError }
+export { BsuirResponseValidationError as BsuirResponseValidationError_alias_1 }
+
 declare class BsuirTimeoutError extends Error {
     readonly endpoint: string;
     readonly timeoutMs: number;
-    constructor(message: string, endpoint: string, timeoutMs: number);
+    constructor(message: string, endpoint: string, timeoutMs: number, cause?: unknown);
 }
 export { BsuirTimeoutError }
 export { BsuirTimeoutError as BsuirTimeoutError_alias_1 }
@@ -137,7 +210,29 @@ export { BuildingNumber }
 export { BuildingNumber as BuildingNumber_alias_1 }
 export { BuildingNumber as BuildingNumber_alias_2 }
 
-export declare function createAnnouncementsModule(config: InternalClientConfig): {
+declare interface CacheOptions {
+    /**
+     * Cache TTL for successful GET responses, in milliseconds.
+     */
+    ttlMs: number;
+    /**
+     * Maximum number of cached entries kept in memory.
+     */
+    maxEntries?: number;
+}
+export { CacheOptions }
+export { CacheOptions as CacheOptions_alias_1 }
+
+declare interface ClientHooks {
+    onRequest?: (context: RequestHookContext) => void;
+    onRetry?: (context: RetryHookContext) => void;
+    onResponse?: (context: ResponseHookContext) => void;
+    onError?: (context: ErrorHookContext) => void;
+}
+export { ClientHooks }
+export { ClientHooks as ClientHooks_alias_1 }
+
+declare function createAnnouncementsModule(config: Readonly<InternalClientConfig>): {
     /**
      * Lists announcements for an employee. IIS may return HTTP `404` or `400` (no list / endpoint quirks); the SDK maps those to `[]`.
      */
@@ -147,8 +242,10 @@ export declare function createAnnouncementsModule(config: InternalClientConfig):
      */
     byDepartment(id: number, options?: ReadOptions): Promise<Announcement[]>;
 };
+export { createAnnouncementsModule }
+export { createAnnouncementsModule as createAnnouncementsModule_alias_1 }
 
-export declare function createAuditoriesModule(config: InternalClientConfig): {
+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).
@@ -159,63 +256,39 @@ export declare function createAuditoriesModule(config: InternalClientConfig): {
      */
     listAll(options?: ReadOptions): Promise<Auditory[]>;
 };
+export { createAuditoriesModule }
+export { createAuditoriesModule as createAuditoriesModule_alias_1 }
 
 /**
  * Creates a configured BSUIR IIS API client.
+ *
+ * Pass `{ defaultRaw: true }` to switch the default return shape of
+ * `schedule.getGroup` and `schedule.getEmployee` from `NormalizedScheduleResponse`
+ * to the raw `ScheduleResponse`. Per-call `raw` option always takes precedence.
+ *
+ * @example
+ * ```ts
+ * // Normalized (default):
+ * const client = createBsuirClient();
+ *
+ * // Raw by default:
+ * const rawClient = createBsuirClient({ defaultRaw: true });
+ *
+ * // Custom fetch + timeout:
+ * const client = createBsuirClient({ fetch: myFetch, timeoutMs: 5_000 });
+ * ```
  */
-declare function createBsuirClient(options?: BsuirClientOptions): {
-    schedule: {
-        getGroup: <TRaw extends boolean | undefined = undefined>(groupNumber: string, options?: ReadOptions & {
-            raw?: TRaw;
-        }) => Promise<TRaw extends true ? ScheduleResponse : NormalizedScheduleResponse>;
-        getEmployee: <TRaw extends boolean | undefined = undefined>(urlId: string, options?: ReadOptions & {
-            raw?: TRaw;
-        }) => Promise<TRaw extends true ? ScheduleResponse : NormalizedScheduleResponse>;
-        getGroupFiltered: (groupNumber: string, filter: ScheduleFilterOptions, options?: ReadOptions) => Promise<FlattenedScheduleItem[]>;
-        getEmployeeFiltered: (urlId: string, filter: ScheduleFilterOptions, options?: ReadOptions) => Promise<FlattenedScheduleItem[]>;
-        getGroupExams(groupNumber: string, options?: ReadOptions): Promise<FlattenedScheduleItem[]>;
-        getEmployeeExams(urlId: string, options?: ReadOptions): Promise<FlattenedScheduleItem[]>;
-        getGroupBySubgroup(groupNumber: string, subgroup: number, options?: ReadOptions): Promise<FlattenedScheduleItem[]>;
-        getEmployeeBySubgroup(urlId: string, subgroup: number, options?: ReadOptions): Promise<FlattenedScheduleItem[]>;
-        getCurrentWeek: (options?: ReadOptions) => Promise<number>;
-        getLastUpdateByGroup(params: {
-            groupNumber: string;
-        } | {
-            id: number;
-        }, options?: ReadOptions): Promise<ApiDateResponse>;
-        getLastUpdateByEmployee(params: {
-            urlId: string;
-        } | {
-            id: number;
-        }, options?: ReadOptions): Promise<ApiDateResponse>;
-    };
-    groups: {
-        listAll(options?: ReadOptions): Promise<StudentGroupCatalogItem[]>;
-    };
-    employees: {
-        listAll(options?: ReadOptions): Promise<EmployeeCatalogItem[]>;
-    };
-    faculties: {
-        listAll(options?: ReadOptions): Promise<Faculty[]>;
-    };
-    departments: {
-        listAll(options?: ReadOptions): Promise<Department[]>;
-    };
-    specialities: {
-        listAll(options?: ReadOptions): Promise<Speciality[]>;
-    };
-    announcements: {
-        byEmployee(urlId: string, options?: ReadOptions): Promise<Announcement[]>;
-        byDepartment(id: number, options?: ReadOptions): Promise<Announcement[]>;
-    };
-    auditories: {
-        listAll(options?: ReadOptions): Promise<Auditory[]>;
-    };
-};
+declare function createBsuirClient(options: BsuirClientOptions & {
+    defaultRaw: true;
+}): BsuirClientShape<true>;
+
+declare function createBsuirClient(options?: BsuirClientOptions & {
+    defaultRaw?: false | undefined;
+}): BsuirClientShape<false>;
 export { createBsuirClient }
 export { createBsuirClient as createBsuirClient_alias_1 }
 
-export declare function createDepartmentsModule(config: InternalClientConfig): {
+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).
@@ -226,8 +299,10 @@ export declare function createDepartmentsModule(config: InternalClientConfig): {
      */
     listAll(options?: ReadOptions): Promise<Department[]>;
 };
+export { createDepartmentsModule }
+export { createDepartmentsModule as createDepartmentsModule_alias_1 }
 
-export declare function createEmployeesModule(config: InternalClientConfig): {
+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).
@@ -238,8 +313,10 @@ export declare function createEmployeesModule(config: InternalClientConfig): {
      */
     listAll(options?: ReadOptions): Promise<EmployeeCatalogItem[]>;
 };
+export { createEmployeesModule }
+export { createEmployeesModule as createEmployeesModule_alias_1 }
 
-export declare function createFacultiesModule(config: InternalClientConfig): {
+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).
@@ -250,8 +327,10 @@ export declare function createFacultiesModule(config: InternalClientConfig): {
      */
     listAll(options?: ReadOptions): Promise<Faculty[]>;
 };
+export { createFacultiesModule }
+export { createFacultiesModule as createFacultiesModule_alias_1 }
 
-export declare function createGroupsModule(config: InternalClientConfig): {
+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).
@@ -262,16 +341,18 @@ export declare function createGroupsModule(config: InternalClientConfig): {
      */
     listAll(options?: ReadOptions): Promise<StudentGroupCatalogItem[]>;
 };
+export { createGroupsModule }
+export { createGroupsModule as createGroupsModule_alias_1 }
 
 export declare function createJsonResponse({ status, headers, body }: MockResponseInit): Response;
 
-export declare function createScheduleModule(config: InternalClientConfig): {
+declare function createScheduleModule<TRawDefault extends boolean>(config: Readonly<InternalClientConfig<TRawDefault>>): {
     getGroup: <TRaw extends boolean | undefined = undefined>(groupNumber: string, options?: ReadOptions & {
         raw?: TRaw;
-    }) => Promise<TRaw extends true ? ScheduleResponse : NormalizedScheduleResponse>;
+    }) => Promise<ScheduleResponseByRawOption<TRaw, TRawDefault>>;
     getEmployee: <TRaw extends boolean | undefined = undefined>(urlId: string, options?: ReadOptions & {
         raw?: TRaw;
-    }) => Promise<TRaw extends true ? ScheduleResponse : NormalizedScheduleResponse>;
+    }) => Promise<ScheduleResponseByRawOption<TRaw, TRawDefault>>;
     getGroupFiltered: (groupNumber: string, filter: ScheduleFilterOptions, options?: ReadOptions) => Promise<FlattenedScheduleItem[]>;
     getEmployeeFiltered: (urlId: string, filter: ScheduleFilterOptions, options?: ReadOptions) => Promise<FlattenedScheduleItem[]>;
     getGroupExams(groupNumber: string, options?: ReadOptions): Promise<FlattenedScheduleItem[]>;
@@ -298,8 +379,10 @@ export declare function createScheduleModule(config: InternalClientConfig): {
         id: number;
     }, options?: ReadOptions): Promise<ApiDateResponse>;
 };
+export { createScheduleModule }
+export { createScheduleModule as createScheduleModule_alias_1 }
 
-export declare function createSpecialitiesModule(config: InternalClientConfig): {
+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).
@@ -310,6 +393,8 @@ export declare function createSpecialitiesModule(config: InternalClientConfig):
      */
     listAll(options?: ReadOptions): Promise<Speciality[]>;
 };
+export { createSpecialitiesModule }
+export { createSpecialitiesModule as createSpecialitiesModule_alias_1 }
 
 export declare const default_alias: Options | Options[] | ((overrideOptions: Options) => Options | Options[] | Promise<Options | Options[]>);
 
@@ -367,6 +452,13 @@ export { EmployeeCatalogItem }
 export { EmployeeCatalogItem as EmployeeCatalogItem_alias_1 }
 export { EmployeeCatalogItem as EmployeeCatalogItem_alias_2 }
 
+declare interface ErrorHookContext extends RequestHookContext {
+    durationMs: number;
+    error: unknown;
+}
+export { ErrorHookContext }
+export { ErrorHookContext as ErrorHookContext_alias_1 }
+
 declare interface Faculty {
     id: number;
     name: string;
@@ -376,7 +468,27 @@ export { Faculty }
 export { Faculty as Faculty_alias_1 }
 export { Faculty as Faculty_alias_2 }
 
-declare type FlattenedLessonsByDay = Partial<Record<Weekday, FlattenedScheduleItem[]>>;
+/**
+ * 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: ["лк", "лекция"] });
+ * ```
+ */
+declare function filterLessons(response: NormalizedScheduleResponse, filter: ScheduleFilterOptions): FlattenedScheduleItem[];
+export { filterLessons }
+export { filterLessons as filterLessons_alias_1 }
+
+declare type FlattenedLessonsByDay = Record<Weekday, FlattenedScheduleItem[]>;
 export { FlattenedLessonsByDay }
 export { FlattenedLessonsByDay as FlattenedLessonsByDay_alias_1 }
 export { FlattenedLessonsByDay as FlattenedLessonsByDay_alias_2 }
@@ -389,16 +501,28 @@ export { FlattenedScheduleItem }
 export { FlattenedScheduleItem as FlattenedScheduleItem_alias_1 }
 export { FlattenedScheduleItem as FlattenedScheduleItem_alias_2 }
 
-export declare interface InternalClientConfig {
+export declare interface InternalClientConfig<TRawDefault extends boolean = boolean> {
     baseUrl: string;
     fetchImpl: typeof globalThis.fetch;
+    signal: AbortSignal | undefined;
     timeoutMs: number;
     retries: number;
     retryDelayMs: number;
     retryMaxDelayMs: number;
     retryJitter: boolean;
     userAgent: string | undefined;
-    defaultRaw: boolean;
+    cacheTtlMs: number | undefined;
+    cacheMaxEntries: number;
+    dedupeInFlight: boolean;
+    validateResponses: boolean;
+    hooks: ClientHooks;
+    responseCache: Map<string, {
+        expiresAt: number;
+        value: unknown;
+        accessedAt: number;
+    }>;
+    inFlightRequests: Map<string, Promise<unknown>>;
+    defaultRaw: TRawDefault;
 }
 
 export declare function isAbortError(error: unknown): boolean;
@@ -420,14 +544,21 @@ export { Maybe as Maybe_alias_1 }
 export { Maybe as Maybe_alias_2 }
 
 /**
- * Combines an optional caller {@link AbortSignal} with a per-attempt timeout.
+ * Combines multiple abort signals and/or a timeout into a single signal.
  * When `AbortSignal.any` exists at runtime, delegates to the platform implementation.
- * Otherwise uses a manual merge so the timeout still applies alongside a caller signal.
+ * Otherwise uses a manual merge so all signals are respected.
+ *
+ * @param signalsOrFirst - Array of signals to merge, or a single signal (legacy signature)
+ * @param timeoutMs - Optional timeout in milliseconds to include as an additional signal
+ *
+ * @remarks
+ * Calling with no signals and no timeout (e.g. `mergeSignals([])`) returns a signal
+ * that is never aborted — the caller is responsible for not doing this intentionally.
  */
-export declare function mergeSignals(signal: AbortSignal | undefined, timeoutMs: number): AbortSignal;
+export declare function mergeSignals(signalsOrFirst: AbortSignal[] | (AbortSignal | undefined), timeoutMs?: number): AbortSignal;
 
 /** Used when `AbortSignal.any` is unavailable; exposed for unit tests. */
-export declare function mergeSignalsManual(signal: AbortSignal | undefined, timeoutMs: number): AbortSignal;
+export declare function mergeSignalsManual(signals: AbortSignal[], timeoutMs?: number): AbortSignal;
 
 export declare function mockFetchSequence(responses: Array<Response | Error>): typeof globalThis.fetch;
 
@@ -449,6 +580,31 @@ export { NormalizedScheduleResponse }
 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
+ * ```
+ */
+declare function normalizeSchedule(response: ScheduleResponse): NormalizedScheduleResponse;
+export { normalizeSchedule }
+export { normalizeSchedule as normalizeSchedule_alias_1 }
+
 /**
  * Normalizes current week payload from API to a positive integer.
  * API can return plain text (`"1\n"`) or number.
@@ -464,7 +620,11 @@ export declare type QueryValue = string | number | boolean | null | undefined;
 /**
  * Read options used by all module methods.
  */
-declare interface ReadOptions extends RequestOptions {
+declare interface ReadOptions {
+    /**
+     * Optional signal to cancel request from the caller side.
+     */
+    signal?: AbortSignal | undefined;
     /**
      * When true, return raw API payload where supported.
      */
@@ -473,10 +633,23 @@ declare interface ReadOptions extends RequestOptions {
 export { ReadOptions }
 export { ReadOptions as ReadOptions_alias_1 }
 
-export declare function requestJson<T>(config: InternalClientConfig, path: string, options?: RequestOptions): Promise<T>;
+declare interface RequestHookContext {
+    method: RequestMethod;
+    path: string;
+    endpoint: string;
+    attempt: number;
+    maxAttempts: number;
+    query: QueryParams | undefined;
+}
+export { RequestHookContext }
+export { RequestHookContext as RequestHookContext_alias_1 }
+
+export declare function requestJson<T>(config: Readonly<InternalClientConfig>, path: string, options?: RequestOptions): Promise<T>;
+
+export declare type RequestMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
 
 /**
- * Common request options shared by read-only API methods.
+ * Low-level HTTP request options used by internal request pipeline.
  */
 declare interface RequestOptions {
     /**
@@ -487,10 +660,38 @@ declare interface RequestOptions {
      * Optional signal to cancel request from the caller side.
      */
     signal?: AbortSignal | undefined;
+    /**
+     * HTTP method. Defaults to `GET`.
+     */
+    method?: RequestMethod | undefined;
+    /**
+     * JSON body payload for mutating requests.
+     */
+    body?: unknown;
+    /**
+     * Additional request headers.
+     */
+    headers?: HeadersInit | undefined;
 }
 export { RequestOptions }
 export { RequestOptions as RequestOptions_alias_1 }
 
+declare interface ResponseHookContext extends RequestHookContext {
+    status: number;
+    durationMs: number;
+    fromCache: boolean;
+}
+export { ResponseHookContext }
+export { ResponseHookContext as ResponseHookContext_alias_1 }
+
+declare interface RetryHookContext extends RequestHookContext {
+    delayMs: number;
+    reason: "http_status" | "network_error";
+    status: number | undefined;
+}
+export { RetryHookContext }
+export { RetryHookContext as RetryHookContext_alias_1 }
+
 declare interface ScheduleFilterOptions {
     source?: "schedules" | "exams";
     weekday?: Weekday;
@@ -515,7 +716,7 @@ declare interface ScheduleItem {
     subject: string;
     subjectFullName: string;
     note: Maybe<string>;
-    lessonTypeAbbrev: string | null;
+    lessonTypeAbbrev: Maybe<string>;
     dateLesson: Maybe<string>;
     startLessonDate: Maybe<string>;
     endLessonDate: Maybe<string>;
@@ -541,6 +742,8 @@ export { ScheduleResponse }
 export { ScheduleResponse as ScheduleResponse_alias_1 }
 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;
+
 declare interface Speciality {
     id: number;
     name: string;