bsuir-iis-api 0.10.0 → 0.11.0

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

@@ -13,6 +13,26 @@ export { Announcement }
 export { Announcement as Announcement_alias_1 }
 export { Announcement as Announcement_alias_2 }
 
+/**
+ * Options accepted by `announcements.byEmployee` and `announcements.byDepartment`.
+ *
+ * The BSUIR IIS API responds with HTTP 404 when no announcements exist for an
+ * employee or department. By default this SDK converts that 404 into an empty
+ * array. Set `treat404AsEmpty: false` to receive a `BsuirApiError` instead —
+ * useful when you want to distinguish "entity not found" from "entity has no
+ * announcements" at the call site.
+ */
+export declare interface AnnouncementReadOptions extends ReadOptions {
+    /**
+     * When `true` (the default), HTTP 404 responses from the announcements endpoint
+     * are converted to an empty array. When `false`, the underlying `BsuirApiError`
+     * is rethrown.
+     *
+     * @defaultValue true
+     */
+    treat404AsEmpty?: boolean;
+}
+
 /** Payload from IIS legacy `last-update-date/*` endpoints (`schedule.getLastUpdateByGroup` / `getLastUpdateByEmployee`). */
 declare interface ApiDateResponse {
     lastUpdateDate: string;
@@ -21,18 +41,39 @@ export { ApiDateResponse }
 export { ApiDateResponse as ApiDateResponse_alias_1 }
 export { ApiDateResponse as ApiDateResponse_alias_2 }
 
+/**
+ * Asserts that payload matches `{ lastUpdateDate: string }`.
+ */
 export declare function assertApiDateResponse(payload: unknown, endpoint: string): asserts payload is ApiDateResponse;
 
+/**
+ * Asserts that payload is an array response.
+ */
 export declare function assertArrayResponse(payload: unknown, endpoint: string): asserts payload is unknown[];
 
+/**
+ * Asserts that an employee urlId is a non-empty slug.
+ */
 export declare function assertEmployeeUrlId(value: unknown, fieldName?: string): asserts value is string;
 
+/**
+ * Asserts that a group number is a non-empty string containing only digits.
+ */
 export declare function assertGroupNumber(value: unknown, fieldName?: string): asserts value is string;
 
+/**
+ * Asserts that a value is a non-empty string.
+ */
 export declare function assertNonEmptyString(value: unknown, fieldName: string): asserts value is string;
 
+/**
+ * Asserts that a value is a positive integer.
+ */
 export declare function assertPositiveInt(value: unknown, fieldName: string): asserts value is number;
 
+/**
+ * Asserts that payload is a schedule response envelope.
+ */
 export declare function assertScheduleResponse(payload: unknown, endpoint: string): asserts payload is ScheduleResponse;
 
 declare interface Auditory {
@@ -78,9 +119,8 @@ export { BsuirApiError as BsuirApiError_alias_1 }
 
 /**
  * Public client contract returned by `createBsuirClient`.
- * Use `BsuirClientShape<true>` or `BsuirClientShape<false>` for typed overloads.
  */
-declare type BsuirClient = ReturnType<typeof createBsuirClient>;
+declare type BsuirClient = BsuirClientShape;
 export { BsuirClient }
 export { BsuirClient as BsuirClient_alias_1 }
 
@@ -98,6 +138,7 @@ declare interface BsuirClientOptions {
      * Allows using `http://` for `baseUrl`.
      *
      * Keep disabled unless you explicitly need local/non-TLS endpoints in tests.
+     * When enabled, `http://` is allowed only for localhost/loopback hosts.
      *
      * @defaultValue false
      */
@@ -127,9 +168,9 @@ declare interface BsuirClientOptions {
      * 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.
+     * Note: caching is disabled only when the signal is already aborted at the
+     * time the request is made. A live (non-aborted) global signal is fine:
+     * caching remains enabled and in-flight deduplication can still be used.
      */
     signal?: AbortSignal;
     /**
@@ -185,11 +226,19 @@ declare interface BsuirClientOptions {
      *
      * 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.
+     * `fromCache: true`. The cache uses `Map` insertion order as LRU:
+     * cache reads "touch" entries and eviction removes oldest keys first.
+     *
+     * Caching is automatically skipped for requests where the relevant
+     * `AbortSignal` (per-call or global) is already aborted, to prevent
+     * serving stale data after cancellation.
+     *
+     * Caching is also automatically skipped when request headers include
+     * credentials/private identity data such as `Authorization`, `Cookie`,
+     * `Proxy-Authorization`, or `X-API-Key`.
      *
-     * Caching is automatically skipped for requests that carry an `AbortSignal`
-     * (per-call or global) to prevent serving stale data after cancellation.
+     * For server-side multi-tenant apps, prefer one client instance per identity
+     * (per user/session/token) to avoid accidental data sharing.
      *
      * @example
      * ```ts
@@ -201,15 +250,17 @@ declare interface BsuirClientOptions {
      */
     cache?: CacheOptions;
     /**
-     * Enables in-flight GET request deduplication by full URL.
+     * Enables in-flight GET request deduplication by method + URL + headers.
      *
      * 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`.
+     * Disabled automatically when the relevant `AbortSignal` is already aborted.
+     * Also disabled for per-call signals, non-default cache modes, and requests
+     * with private credential headers.
      *
-     * @defaultValue true
+     * @defaultValue false
      */
     dedupeInFlight?: boolean;
     /**
@@ -224,14 +275,14 @@ declare interface BsuirClientOptions {
      * 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,
+     * at runtime. A `BsuirResponseValidationError` 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
+     * @defaultValue false
      *
      * @example
      * ```ts
@@ -262,34 +313,6 @@ declare interface BsuirClientOptions {
      * ```
      */
     hooks?: ClientHooks;
-    /**
-     * 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.
-     *
-     * A per-call `raw` option always takes precedence over this default.
-     *
-     * @defaultValue false
-     *
-     * @example
-     * ```ts
-     * // 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;
 }
 export { BsuirClientOptions }
 export { BsuirClientOptions as BsuirClientOptions_alias_1 }
@@ -298,29 +321,13 @@ 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
- * ```
+ * Use explicit raw/envelope helpers on the `schedule` module to obtain the
+ * API's raw `ScheduleResponse` when required (e.g. `getGroupRaw`,
+ * `getEmployeeRaw`, `getGroupEnvelope`). The default `getGroup`/`getEmployee`
+ * return a normalized payload.
  */
-export declare interface BsuirClientShape<TRawDefault extends boolean> {
-    schedule: ReturnType<typeof createScheduleModule<TRawDefault>>;
+declare interface BsuirClientShape {
+    schedule: ReturnType<typeof createScheduleModule>;
     groups: ReturnType<typeof createGroupsModule>;
     employees: ReturnType<typeof createEmployeesModule>;
     faculties: ReturnType<typeof createFacultiesModule>;
@@ -329,6 +336,8 @@ export declare interface BsuirClientShape<TRawDefault extends boolean> {
     announcements: ReturnType<typeof createAnnouncementsModule>;
     auditories: ReturnType<typeof createAuditoriesModule>;
 }
+export { BsuirClientShape }
+export { BsuirClientShape as BsuirClientShape_alias_1 }
 
 declare class BsuirConfigurationError extends Error {
     constructor(message: string);
@@ -343,6 +352,15 @@ declare class BsuirNetworkError extends Error {
 export { BsuirNetworkError }
 export { BsuirNetworkError as BsuirNetworkError_alias_1 }
 
+declare class BsuirResponsePayloadTooLargeError extends Error {
+    readonly status: number;
+    readonly endpoint: string;
+    readonly maxResponseBytes: number;
+    constructor(message: string, status: number, endpoint: string, maxResponseBytes: number);
+}
+export { BsuirResponsePayloadTooLargeError }
+export { BsuirResponsePayloadTooLargeError as BsuirResponsePayloadTooLargeError_alias_1 }
+
 declare class BsuirResponseValidationError extends Error {
     readonly endpoint: string;
     constructor(message: string, endpoint: string);
@@ -359,7 +377,9 @@ export { BsuirTimeoutError }
 export { BsuirTimeoutError as BsuirTimeoutError_alias_1 }
 
 declare class BsuirValidationError extends Error {
-    constructor(message: string);
+    readonly field: string | undefined;
+    readonly value: unknown;
+    constructor(message: string, field?: string, value?: unknown);
 }
 export { BsuirValidationError }
 export { BsuirValidationError as BsuirValidationError_alias_1 }
@@ -372,8 +392,75 @@ export { BuildingNumber }
 export { BuildingNumber as BuildingNumber_alias_1 }
 export { BuildingNumber as BuildingNumber_alias_2 }
 
+/**
+ * Builds lightweight day models for schedule screens.
+ *
+ * Uses local calendar dates. Returns day objects with lessons,
+ * "today" marker, and optional current/next lesson metadata for the current day.
+ * `currentLesson` and `nextLesson` are only computed for today (`isToday === true`).
+ *
+ * @param normalizedSchedule - Normalized schedule payload from {@link normalizeSchedule}.
+ * @param options - Builder options for date range and filtering.
+ * @returns Day models ready for direct UI rendering.
+ *
+ * @example
+ * ```ts
+ * const days = buildScheduleDays(schedule, { days: 7, includeEmptyDays: false });
+ * // Use days?.lessons for in-day progress:
+ * const current = getCurrentLesson(days?.lessons ?? []);
+ * ```
+ */
+declare function buildScheduleDays(normalizedSchedule: NormalizedScheduleResponse, options?: BuildScheduleDaysOptions): ScheduleDay[];
+export { buildScheduleDays }
+export { buildScheduleDays as buildScheduleDays_alias_1 }
+export { buildScheduleDays as buildScheduleDays_alias_2 }
+
+/**
+ * Options for {@link buildScheduleDays}.
+ */
+declare interface BuildScheduleDaysOptions {
+    /** Reference moment for "today" and current/next lesson detection. Defaults to `new Date()`. */
+    now?: Date;
+    /** First day of the range. Defaults to `now`. */
+    startDate?: Date;
+    /** Number of days to build. Must be a positive integer. Defaults to `7`. */
+    days?: number;
+    /**
+     * Whether to include days with no lessons.
+     * @defaultValue `true`
+     */
+    includeEmptyDays?: boolean;
+    /**
+     * Whether to compute `currentLesson` and `nextLesson` for today.
+     * @defaultValue `true`
+     */
+    includeCurrentAndNextLessons?: boolean;
+    /**
+     * Callback fired once per lesson whose `startLessonTime` or `endLessonTime`
+     * cannot be parsed as `HH:MM`. The lesson is otherwise still included in the
+     * day's `lessons` array but sorted to the end. Use this to surface upstream
+     * data issues that would otherwise be silently ignored.
+     *
+     * Errors thrown by the hook are caught and discarded.
+     */
+    onInvalidTime?: (info: {
+        field: "startLessonTime" | "endLessonTime";
+        value: string;
+        lesson: {
+            startLessonTime: string;
+            endLessonTime: string;
+        };
+    }) => void;
+}
+export { BuildScheduleDaysOptions }
+export { BuildScheduleDaysOptions as BuildScheduleDaysOptions_alias_1 }
+export { BuildScheduleDaysOptions as BuildScheduleDaysOptions_alias_2 }
+
 /**
  * Builds absolute endpoint URL from base URL, path and query params.
+ *
+ * Query parameters are sorted by key to produce deterministic URLs - important
+ * for cache key stability and for reproducible request fingerprints.
  */
 export declare function buildUrl(baseUrl: string, path: string, query?: QueryParams): string;
 
@@ -413,15 +500,12 @@ declare interface ClientHooks {
 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 `[]`.
-     */
-    byEmployee(urlId: string, options?: ReadOptions): Promise<Announcement[]>;
-    /**
-     * Lists announcements for a department. IIS may return HTTP `404` or `400` (no list / endpoint quirks); the SDK maps those to `[]`.
-     */
-    byDepartment(id: number, options?: ReadOptions): Promise<Announcement[]>;
+    byEmployee(urlId: string, options?: AnnouncementReadOptions): Promise<Announcement[]>;
+    byDepartment(id: number, options?: AnnouncementReadOptions): Promise<Announcement[]>;
 };
 export { createAnnouncementsModule }
 export { createAnnouncementsModule as createAnnouncementsModule_alias_1 }
@@ -429,74 +513,46 @@ export { createAnnouncementsModule as createAnnouncementsModule_alias_1 }
 /**
  * Creates API module for `/auditories`.
  */
-declare function createAuditoriesModule(config: Readonly<InternalClientConfig>): {
-    listAll(options?: ReadOptions): Promise<Auditory[]>;
-};
+declare function createAuditoriesModule(config: Readonly<InternalClientConfig>): ListModule<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 });
- * ```
+ * The `schedule` module exposes both normalized and explicit raw/envelope
+ * helpers. Use `getGroup` / `getEmployee` for normalized payloads and
+ * `getGroupRaw` / `getEmployeeRaw` when you need the original API envelope.
  */
-declare function createBsuirClient(options: BsuirClientOptions & {
-    defaultRaw: true;
-}): BsuirClientShape<true>;
-
-declare function createBsuirClient(options?: BsuirClientOptions & {
-    defaultRaw?: false | undefined;
-}): BsuirClientShape<false>;
+declare function createBsuirClient(options?: BsuirClientOptions): BsuirClientShape;
 export { createBsuirClient }
 export { createBsuirClient as createBsuirClient_alias_1 }
 
 /**
  * Creates API module for `/departments`.
  */
-declare function createDepartmentsModule(config: Readonly<InternalClientConfig>): {
-    listAll(options?: ReadOptions): Promise<Department[]>;
-};
+declare function createDepartmentsModule(config: Readonly<InternalClientConfig>): ListModule<Department>;
 export { createDepartmentsModule }
 export { createDepartmentsModule as createDepartmentsModule_alias_1 }
 
 /**
  * Creates API module for `/employees/all`.
  */
-declare function createEmployeesModule(config: Readonly<InternalClientConfig>): {
-    listAll(options?: ReadOptions): Promise<EmployeeCatalogItem[]>;
-};
+declare function createEmployeesModule(config: Readonly<InternalClientConfig>): ListModule<EmployeeCatalogItem>;
 export { createEmployeesModule }
 export { createEmployeesModule as createEmployeesModule_alias_1 }
 
 /**
  * Creates API module for `/faculties`.
  */
-declare function createFacultiesModule(config: Readonly<InternalClientConfig>): {
-    listAll(options?: ReadOptions): Promise<Faculty[]>;
-};
+declare function createFacultiesModule(config: Readonly<InternalClientConfig>): ListModule<Faculty>;
 export { createFacultiesModule }
 export { createFacultiesModule as createFacultiesModule_alias_1 }
 
 /**
  * Creates API module for `/student-groups`.
  */
-declare function createGroupsModule(config: Readonly<InternalClientConfig>): {
-    listAll(options?: ReadOptions): Promise<StudentGroupCatalogItem[]>;
-};
+declare function createGroupsModule(config: Readonly<InternalClientConfig>): ListModule<StudentGroupCatalogItem>;
 export { createGroupsModule }
 export { createGroupsModule as createGroupsModule_alias_1 }
 
@@ -505,59 +561,12 @@ export declare function createJsonResponse({ status, headers, body }: MockRespon
 /**
  * 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[]>;
-};
+export declare function createListModule<T>(config: Readonly<InternalClientConfig>, endpoint: string): ListModule<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;
-    }) => Promise<ScheduleResponseByRawOption<TRaw, TRawDefault>>;
-    getEmployee: <TRaw extends boolean | undefined = undefined>(urlId: string, options?: ReadOptions & {
-        raw?: TRaw;
-    }) => 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`.
-     */
-    getLastUpdateByGroup(params: {
-        groupNumber: string;
-    } | {
-        id: number;
-    }, options?: ReadOptions): Promise<ApiDateResponse>;
-    /**
-     * Calls IIS `/last-update-date/employee`.
-     */
-    getLastUpdateByEmployee(params: {
-        urlId: string;
-    } | {
-        id: number;
-    }, options?: ReadOptions): Promise<ApiDateResponse>;
-};
+declare function createScheduleModule(config: Readonly<InternalClientConfig>): ScheduleModule;
 export { createScheduleModule }
 export { createScheduleModule as createScheduleModule_alias_1 }
 export { createScheduleModule as createScheduleModule_alias_2 }
@@ -565,9 +574,7 @@ export { createScheduleModule as createScheduleModule_alias_2 }
 /**
  * Creates API module for `/specialities`.
  */
-declare function createSpecialitiesModule(config: Readonly<InternalClientConfig>): {
-    listAll(options?: ReadOptions): Promise<Speciality[]>;
-};
+declare function createSpecialitiesModule(config: Readonly<InternalClientConfig>): ListModule<Speciality>;
 export { createSpecialitiesModule }
 export { createSpecialitiesModule as createSpecialitiesModule_alias_1 }
 
@@ -664,12 +671,269 @@ export { FlattenedScheduleItem }
 export { FlattenedScheduleItem as FlattenedScheduleItem_alias_1 }
 export { FlattenedScheduleItem as FlattenedScheduleItem_alias_2 }
 
+/**
+ * Formats an employee name as `"Фамилия И.О."`.
+ *
+ * Falls back gracefully when first or middle name is missing.
+ *
+ * @example
+ * ```ts
+ * formatEmployeeShortName(employee); // "Иванов И.И."
+ * ```
+ */
+declare function formatEmployeeShortName(employee: Pick<Employee, "lastName" | "firstName" | "middleName">): string;
+export { formatEmployeeShortName }
+export { formatEmployeeShortName as formatEmployeeShortName_alias_1 }
+export { formatEmployeeShortName as formatEmployeeShortName_alias_2 }
+
+/**
+ * Formats a list of auditories as a comma-separated string.
+ *
+ * @returns `"101-2, 102-3"` or `""` when the list is empty.
+ *
+ * @example
+ * ```ts
+ * formatLessonAuditories(lesson); // "101-2, 102-3"
+ * ```
+ */
+declare function formatLessonAuditories(lesson: Pick<FlattenedScheduleItem, "auditories">): string;
+export { formatLessonAuditories }
+export { formatLessonAuditories as formatLessonAuditories_alias_1 }
+export { formatLessonAuditories as formatLessonAuditories_alias_2 }
+
+/**
+ * Formats all lesson employees as short names joined by `", "`.
+ *
+ * @returns `"Иванов И.И., Петров П.П."` or `""` when employees list is absent.
+ *
+ * @example
+ * ```ts
+ * formatLessonEmployees(lesson); // "Иванов И.И."
+ * ```
+ */
+declare function formatLessonEmployees(lesson: Pick<FlattenedScheduleItem, "employees">): string;
+export { formatLessonEmployees }
+export { formatLessonEmployees as formatLessonEmployees_alias_1 }
+export { formatLessonEmployees as formatLessonEmployees_alias_2 }
+
+/**
+ * Returns a human-readable subgroup label.
+ *
+ * @returns `"1 подгруппа"` / `"2 подгруппа"` etc., or `""` when `numSubgroup` is 0.
+ *
+ * @example
+ * ```ts
+ * formatLessonSubgroup(lesson); // "1 подгруппа"
+ * ```
+ */
+declare function formatLessonSubgroup(lesson: Pick<FlattenedScheduleItem, "numSubgroup">): string;
+export { formatLessonSubgroup }
+export { formatLessonSubgroup as formatLessonSubgroup_alias_1 }
+export { formatLessonSubgroup as formatLessonSubgroup_alias_2 }
+
+/**
+ * Formats lesson start and end time as a range string.
+ *
+ * @returns `"HH:MM–HH:MM"`, or an empty string when both times are missing.
+ *
+ * @example
+ * ```ts
+ * formatLessonTimeRange(lesson); // "10:00–11:30"
+ * ```
+ */
+declare function formatLessonTimeRange(lesson: Pick<FlattenedScheduleItem, "startLessonTime" | "endLessonTime">): string;
+export { formatLessonTimeRange }
+export { formatLessonTimeRange as formatLessonTimeRange_alias_1 }
+export { formatLessonTimeRange as formatLessonTimeRange_alias_2 }
+
+/**
+ * Returns the lesson type abbreviation.
+ *
+ * @returns The abbreviation string (e.g. `"ЛК"`, `"ПЗ"`, `"ЛР"`),
+ * or an empty string when the field is absent.
+ *
+ * @example
+ * ```ts
+ * formatLessonType(lesson); // "ЛК"
+ * ```
+ */
+declare function formatLessonType(lesson: Pick<FlattenedScheduleItem, "lessonTypeAbbrev">): string;
+export { formatLessonType }
+export { formatLessonType as formatLessonType_alias_1 }
+export { formatLessonType as formatLessonType_alias_2 }
+
+/**
+ * Formats the week numbers list as a compact string.
+ *
+ * Returns `"кажд. нед."` when `weekNumber` is `null` or empty.
+ * Returns `"1, 3 нед."` for a specific set of weeks.
+ *
+ * @example
+ * ```ts
+ * formatLessonWeekNumbers({ weekNumber: [1, 3] }); // "1, 3 нед."
+ * formatLessonWeekNumbers({ weekNumber: null });    // "кажд. нед."
+ * ```
+ */
+declare function formatLessonWeekNumbers(lesson: Pick<FlattenedScheduleItem, "weekNumber">): string;
+export { formatLessonWeekNumbers }
+export { formatLessonWeekNumbers as formatLessonWeekNumbers_alias_1 }
+export { formatLessonWeekNumbers as formatLessonWeekNumbers_alias_2 }
+
+/**
+ * Returns the lesson active at the specified moment.
+ *
+ * Time comparison uses local hours/minutes: `startLessonTime <= now < endLessonTime`.
+ * A lesson is not considered active exactly at its end time.
+ *
+ * @param lessons - Lessons for one day (or any same-day set).
+ * @param now - Optional current moment override.
+ * @returns Current lesson or `null` when none is active.
+ *
+ * @example
+ * ```ts
+ * const current = getCurrentLesson(todayLessons, new Date());
+ * ```
+ */
+declare function getCurrentLesson<T extends LessonWithTime>(lessons: readonly T[], now?: Date, options?: {
+    onInvalidTime?: InvalidLessonTimeHook | undefined;
+}): T | null;
+export { getCurrentLesson }
+export { getCurrentLesson as getCurrentLesson_alias_1 }
+export { getCurrentLesson as getCurrentLesson_alias_2 }
+
+/**
+ * Returns lessons scheduled for a specific calendar date.
+ *
+ * Date matching uses local calendar date semantics from the provided `date` object.
+ * Lessons with `dateLesson` are matched directly by date key.
+ * Weekly schedule lessons are matched by weekday and inferred week number.
+ * Exams without `dateLesson` but with a date range appear on every day within that range —
+ * in practice BSUIR exams have `dateLesson` set, so this branch handles edge cases only.
+ *
+ * @param normalizedSchedule - Normalized schedule payload from {@link normalizeSchedule}.
+ * @param date - Target date. Must be a `Date` object — local calendar date is used.
+ * @returns Lessons for that date sorted by start time.
+ *
+ * @example
+ * ```ts
+ * const lessons = getLessonsForDate(schedule, new Date(2026, 1, 10));
+ * ```
+ */
+declare function getLessonsForDate(normalizedSchedule: NormalizedScheduleResponse, date: Date): FlattenedScheduleItem[];
+export { getLessonsForDate }
+export { getLessonsForDate as getLessonsForDate_alias_1 }
+export { getLessonsForDate as getLessonsForDate_alias_2 }
+
+/**
+ * Returns regular schedule lessons for a specific week number.
+ *
+ * @param normalizedSchedule - Normalized schedule payload from {@link normalizeSchedule}.
+ * @param weekNumber - Positive week number to match.
+ * @returns Matching regular lessons sorted by start time.
+ *
+ * @example
+ * ```ts
+ * const secondWeek = getLessonsForWeek(schedule, 2);
+ * ```
+ */
+declare function getLessonsForWeek(normalizedSchedule: NormalizedScheduleResponse, weekNumber: number): FlattenedScheduleItem[];
+export { getLessonsForWeek }
+export { getLessonsForWeek as getLessonsForWeek_alias_1 }
+export { getLessonsForWeek as getLessonsForWeek_alias_2 }
+
+/**
+ * Returns a cleanup callback for manually merged signals, when available.
+ */
+export declare function getMergedSignalCleanup(signal: AbortSignal): (() => void) | undefined;
+
+/**
+ * Returns the nearest upcoming lesson after the specified moment.
+ *
+ * A lesson starting exactly at `now` is not returned (use {@link getCurrentLesson} instead).
+ * A lesson that just ended at `now` is also not returned as current — the next one is.
+ *
+ * @param lessons - Lessons for one day (or any same-day set).
+ * @param now - Optional current moment override.
+ * @returns Next lesson or `null` when there is no upcoming lesson.
+ *
+ * @example
+ * ```ts
+ * const next = getNextLesson(todayLessons, new Date());
+ * ```
+ */
+declare function getNextLesson<T extends LessonWithTime>(lessons: readonly T[], now?: Date, options?: {
+    onInvalidTime?: InvalidLessonTimeHook | undefined;
+}): T | null;
+export { getNextLesson }
+export { getNextLesson as getNextLesson_alias_1 }
+export { getNextLesson as getNextLesson_alias_2 }
+
+/**
+ * Calculates retry behavior for the current attempt.
+ *
+ * If server-provided `Retry-After` exceeds a sane safety bound, retry is rejected
+ * to avoid long caller stalls caused by hostile or misconfigured upstreams.
+ */
+export declare function getRetryDecision(config: Readonly<InternalClientConfig>, attempt: number, retryAfterHeader?: string | null): RetryDecision;
+
 /**
  * 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> {
+/**
+ * Returns lessons for the local current day.
+ *
+ * @param normalizedSchedule - Normalized schedule payload from {@link normalizeSchedule}.
+ * @param now - Optional current moment override for deterministic usage.
+ * @returns Lessons for today sorted by start time.
+ *
+ * @example
+ * ```ts
+ * const todayLessons = getTodayLessons(schedule, new Date());
+ * ```
+ */
+declare function getTodayLessons(normalizedSchedule: NormalizedScheduleResponse, now?: Date): FlattenedScheduleItem[];
+export { getTodayLessons }
+export { getTodayLessons as getTodayLessons_alias_1 }
+export { getTodayLessons as getTodayLessons_alias_2 }
+
+/**
+ * Returns lessons for the next local calendar day.
+ *
+ * @param normalizedSchedule - Normalized schedule payload from {@link normalizeSchedule}.
+ * @param now - Optional current moment override for deterministic usage.
+ * @returns Lessons for tomorrow sorted by start time.
+ *
+ * @example
+ * ```ts
+ * const tomorrowLessons = getTomorrowLessons(schedule, new Date());
+ * ```
+ */
+declare function getTomorrowLessons(normalizedSchedule: NormalizedScheduleResponse, now?: Date): FlattenedScheduleItem[];
+export { getTomorrowLessons }
+export { getTomorrowLessons as getTomorrowLessons_alias_1 }
+export { getTomorrowLessons as getTomorrowLessons_alias_2 }
+
+/**
+ * Groups lessons by weekday.
+ *
+ * Lessons with `day === null` (e.g., date-specific exams) are omitted from groups.
+ *
+ * @param lessons - Lessons to group.
+ * @returns Weekday map with arrays sorted by time for each day.
+ *
+ * @example
+ * ```ts
+ * const grouped = groupLessonsByDay(response.lessons);
+ * ```
+ */
+declare function groupLessonsByDay(lessons: readonly FlattenedScheduleItem[]): FlattenedLessonsByDay;
+export { groupLessonsByDay }
+export { groupLessonsByDay as groupLessonsByDay_alias_1 }
+export { groupLessonsByDay as groupLessonsByDay_alias_2 }
+
+export declare interface InternalClientConfig {
     baseUrl: string;
     fetchImpl: typeof globalThis.fetch;
     signal: AbortSignal | undefined;
@@ -688,12 +952,35 @@ export declare interface InternalClientConfig<TRawDefault extends boolean = bool
     responseCache: Map<string, {
         expiresAt: number;
         value: unknown;
-        accessedAt: number;
     }>;
     inFlightRequests: Map<string, Promise<unknown>>;
-    defaultRaw: TRawDefault;
 }
 
+/**
+ * Optional callback invoked when a lesson's `startLessonTime` or `endLessonTime`
+ * cannot be parsed as `HH:MM`. Use this to surface upstream data issues that the
+ * default behavior (sorting such lessons to the end, ignoring them for
+ * current/next lookups) would otherwise hide.
+ *
+ * The callback is fired at most once per malformed value per call site. It must
+ * not throw — exceptions from a hook are caught and discarded.
+ *
+ * @example
+ * ```ts
+ * const sorted = sortLessonsByTime(lessons, {
+ *   onInvalidTime: (info) => logger.warn("malformed lesson time", info),
+ * });
+ * ```
+ */
+export declare type InvalidLessonTimeHook = (info: {
+    field: "startLessonTime" | "endLessonTime";
+    value: string;
+    lesson: LessonWithTime;
+}) => void;
+
+/**
+ * Returns `true` if the error object represents an abort/cancellation.
+ */
 export declare function isAbortError(error: unknown): boolean;
 
 declare interface LessonStudentGroup {
@@ -707,6 +994,19 @@ export { LessonStudentGroup }
 export { LessonStudentGroup as LessonStudentGroup_alias_1 }
 export { LessonStudentGroup as LessonStudentGroup_alias_2 }
 
+/**
+ * Minimal time fields required for lesson-time helpers.
+ * Used as a constraint for generic helpers like {@link sortLessonsByTime}.
+ */
+declare type LessonWithTime = Pick<FlattenedScheduleItem, "startLessonTime" | "endLessonTime">;
+export { LessonWithTime }
+export { LessonWithTime as LessonWithTime_alias_1 }
+export { LessonWithTime as LessonWithTime_alias_2 }
+
+export declare interface ListModule<T> {
+    listAll(options?: ReadOptions): Promise<T[]>;
+}
+
 declare type Maybe<T> = T | null;
 export { Maybe }
 export { Maybe as Maybe_alias_1 }
@@ -716,15 +1016,8 @@ export { Maybe as Maybe_alias_2 }
  * 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 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(signalsOrFirst: AbortSignal[] | (AbortSignal | undefined), timeoutMs?: number): AbortSignal;
+export declare function mergeSignals(signals: readonly (AbortSignal | undefined)[], timeoutMs?: number): AbortSignal;
 
 /** Used when `AbortSignal.any` is unavailable; exposed for unit tests. */
 export declare function mergeSignalsManual(signals: AbortSignal[], timeoutMs?: number): AbortSignal;
@@ -752,13 +1045,17 @@ export { NormalizedScheduleResponse as NormalizedScheduleResponse_alias_2 }
 /**
  * Transforms raw schedule response into normalized structure with flattened lessons.
  */
-declare function normalizeSchedule(response: ScheduleResponse): NormalizedScheduleResponse;
+declare function normalizeSchedule(response: ScheduleResponse, options?: {
+    validate?: boolean;
+    endpoint?: string;
+}): 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.
+ * Returns `null` for empty non-JSON bodies.
  * Throws `BsuirApiError` for declared JSON payloads that are empty/invalid.
  */
 export declare function parseBody(response: Response, maxResponseBytes: number): Promise<unknown>;
@@ -769,11 +1066,18 @@ export declare function parseBody(response: Response, maxResponseBytes: number):
  */
 export declare function parseCurrentWeek(payload: unknown): number;
 
+/**
+ *
+ */
 export declare function parseDdMmYyyy(value: string | null): Date | null;
 
-export declare type QueryParams = Record<string, QueryValue>;
+declare type QueryParams = Record<string, QueryValue>;
+export { QueryParams }
+export { QueryParams as QueryParams_alias_1 }
 
-export declare type QueryValue = string | number | boolean | null | undefined;
+declare type QueryValue = string | number | boolean | null | undefined;
+export { QueryValue }
+export { QueryValue as QueryValue_alias_1 }
 
 /**
  * Read options used by all module methods.
@@ -784,13 +1088,17 @@ declare interface ReadOptions {
      */
     signal?: AbortSignal | undefined;
     /**
-     * When true, return raw API payload where supported.
+     * Per-request cache mode.
      */
-    raw?: boolean;
+    cache?: RequestCacheMode | undefined;
 }
 export { ReadOptions }
 export { ReadOptions as ReadOptions_alias_1 }
 
+declare type RequestCacheMode = "default" | "no-store" | "reload";
+export { RequestCacheMode }
+export { RequestCacheMode as RequestCacheMode_alias_1 }
+
 declare interface RequestHookContext {
     method: RequestMethod;
     path: string;
@@ -809,7 +1117,9 @@ declare function requestJson<T>(config: Readonly<InternalClientConfig>, path: st
 export { requestJson }
 export { requestJson as requestJson_alias_1 }
 
-export declare type RequestMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+declare type RequestMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+export { RequestMethod }
+export { RequestMethod as RequestMethod_alias_1 }
 
 /**
  * Low-level HTTP request options used by internal request pipeline.
@@ -835,6 +1145,21 @@ declare interface RequestOptions {
      * Additional request headers.
      */
     headers?: HeadersInit | undefined;
+    /**
+     * Per-request cache mode for successful GET requests.
+     *
+     * - `"default"`: read from cache and write to cache.
+     * - `"no-store"`: always bypass cache read/write.
+     * - `"reload"`: bypass cache read, but write fresh response to cache.
+     *
+     * @defaultValue "default"
+     */
+    cache?: RequestCacheMode | undefined;
+    /**
+     * Optional response validator invoked for network responses before caching.
+     * Used by internal modules to avoid repeated validation on cache hits.
+     */
+    responseValidator?: ((payload: unknown) => void) | undefined;
 }
 export { RequestOptions }
 export { RequestOptions as RequestOptions_alias_1 }
@@ -850,14 +1175,55 @@ export { ResponseHookContext as ResponseHookContext_alias_1 }
 /** HTTP status codes retriable by the request pipeline. */
 export declare const RETRIABLE_STATUS_CODES: Set<number>;
 
+export declare type RetryDecision = {
+    retryable: true;
+    delayMs: number;
+} | {
+    retryable: false;
+    rejectedDelayMs: number;
+};
+
 declare interface RetryHookContext extends RequestHookContext {
     delayMs: number;
-    reason: "http_status" | "network_error";
+    reason: "http_status" | "network_error" | "retry_after_too_large";
     status: number | undefined;
 }
 export { RetryHookContext }
 export { RetryHookContext as RetryHookContext_alias_1 }
 
+/**
+ * A single day model produced by {@link buildScheduleDays}.
+ */
+declare interface ScheduleDay {
+    /** Local calendar date for this day. */
+    date: Date;
+    /** ISO-style date key in `"YYYY-MM-DD"` format for fast equality checks. */
+    dateKey: string;
+    /** BSUIR weekday name, or `null` for Sunday. */
+    weekday: Weekday | null;
+    /** Display label: weekday name, or `"Воскресенье"` for Sunday. */
+    weekdayLabel: string;
+    /** Lessons for this day sorted by start time. */
+    lessons: FlattenedScheduleItem[];
+    /** Whether this day matches the reference `now` date. */
+    isToday: boolean;
+    /** Whether there are any lessons on this day. */
+    hasLessons: boolean;
+    /**
+     * Lesson active at `now`, or `null`.
+     * Always `null` for days other than today, or when `includeCurrentAndNextLessons` is `false`.
+     */
+    currentLesson: FlattenedScheduleItem | null;
+    /**
+     * Next upcoming lesson after `now`, or `null`.
+     * Always `null` for days other than today, or when `includeCurrentAndNextLessons` is `false`.
+     */
+    nextLesson: FlattenedScheduleItem | null;
+}
+export { ScheduleDay }
+export { ScheduleDay as ScheduleDay_alias_1 }
+export { ScheduleDay as ScheduleDay_alias_2 }
+
 declare interface ScheduleFilterOptions {
     source?: "schedules" | "exams";
     weekday?: Weekday;
@@ -894,35 +1260,123 @@ export { ScheduleItem }
 export { ScheduleItem as ScheduleItem_alias_1 }
 export { ScheduleItem as ScheduleItem_alias_2 }
 
+declare interface ScheduleModule {
+    getGroup(groupNumber: string, options?: ReadOptions): Promise<NormalizedScheduleResponse>;
+    getEmployee(urlId: string, options?: ReadOptions): Promise<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[]>;
+    getGroupRaw(groupNumber: string, options?: ReadOptions): Promise<ScheduleResponse>;
+    getGroupEnvelope(groupNumber: string, subgroup: number, options?: ReadOptions): Promise<ScheduleResponse>;
+    getEmployeeRaw(urlId: string, options?: ReadOptions): Promise<ScheduleResponse>;
+    getEmployeeEnvelope(urlId: string, subgroup: number, options?: ReadOptions): Promise<ScheduleResponse>;
+    getGroupBySubgroup(groupNumber: string, subgroup: number, options: ReadOptions & {
+        rawEnvelope: true;
+    }): Promise<ScheduleResponse>;
+    getGroupBySubgroup(groupNumber: string, subgroup: number, options: ReadOptions & {
+        raw: true;
+        rawEnvelope?: false | undefined;
+    }): Promise<ScheduleItem[]>;
+    getGroupBySubgroup(groupNumber: string, subgroup: number, options: ReadOptions & {
+        raw: boolean;
+        rawEnvelope?: false | undefined;
+    }): Promise<ScheduleItem[] | FlattenedScheduleItem[]>;
+    getGroupBySubgroup(groupNumber: string, subgroup: number, options?: ReadOptions & {
+        raw?: false | undefined;
+        rawEnvelope?: false | undefined;
+    }): Promise<FlattenedScheduleItem[]>;
+    getEmployeeBySubgroup(urlId: string, subgroup: number, options: ReadOptions & {
+        rawEnvelope: true;
+    }): Promise<ScheduleResponse>;
+    getEmployeeBySubgroup(urlId: string, subgroup: number, options: ReadOptions & {
+        raw: true;
+        rawEnvelope?: false | undefined;
+    }): Promise<ScheduleItem[]>;
+    getEmployeeBySubgroup(urlId: string, subgroup: number, options: ReadOptions & {
+        raw: boolean;
+        rawEnvelope?: false | undefined;
+    }): Promise<ScheduleItem[] | FlattenedScheduleItem[]>;
+    getEmployeeBySubgroup(urlId: string, subgroup: number, options?: ReadOptions & {
+        raw?: false | undefined;
+        rawEnvelope?: false | undefined;
+    }): 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>;
+}
+export { ScheduleModule }
+export { ScheduleModule as ScheduleModule_alias_1 }
+
 declare interface ScheduleResponse {
     employeeDto: Maybe<Employee>;
     studentGroupDto: Maybe<StudentGroupCatalogItem>;
     schedules: WeekScheduleMap | null;
+    /** Additional schedules, e.g. for the next term. Shape not yet stable. */
+    nextSchedules?: WeekScheduleMap | null;
     exams: ScheduleItem[] | null;
     startDate: Maybe<string>;
     endDate: Maybe<string>;
     startExamsDate: Maybe<string>;
     endExamsDate: Maybe<string>;
+    /** Current academic term identifier. Shape not yet stable. */
+    currentTerm?: unknown;
+    /** Next academic term identifier. Shape not yet stable. */
+    nextTerm?: unknown;
+    /** Current period within the term. Shape not yet stable. */
+    currentPeriod?: unknown;
+    /** Whether the group follows a zaochnik or distance learning schedule. */
+    isZaochOrDist?: boolean | null;
 }
 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;
-
 /**
- * Writes response value to cache and performs eviction when size approaches capacity.
+ * Writes response value to cache and performs expiration/LRU eviction.
+ *
+ * Throws if the value is not a JSON-compatible structure — the cache is designed to
+ * hold parsed JSON only, and storing other shapes (Map/Set/Date/typed arrays/class
+ * instances) would either fail later on read or silently lose data on
+ * structuredClone-based eviction strategies.
  */
-export declare function setCache(config: Readonly<InternalClientConfig>, key: string, value: unknown): void;
+export declare function setCache<T>(config: Readonly<InternalClientConfig>, key: string, value: T): T | undefined;
 
 /** Delays execution for a specified number of milliseconds. */
 export declare function sleep(ms: number): Promise<void>;
 
+/**
+ * Returns a new lessons array sorted by start time, then by end time.
+ * Invalid or missing time strings are kept at the end in original order.
+ *
+ * @param lessons - Lessons to sort.
+ * @returns New sorted lessons array.
+ *
+ * @example
+ * ```ts
+ * const sorted = sortLessonsByTime(response.lessons);
+ * ```
+ */
+declare function sortLessonsByTime<T extends LessonWithTime>(lessons: readonly T[], options?: {
+    onInvalidTime?: InvalidLessonTimeHook | undefined;
+}): T[];
+export { sortLessonsByTime }
+export { sortLessonsByTime as sortLessonsByTime_alias_1 }
+export { sortLessonsByTime as sortLessonsByTime_alias_2 }
+
 declare interface Speciality {
     id: number;
     name: string;
     abbrev: string;
-    educationForm: EducationForm[];
+    educationForm: SpecialityEducationForm;
     facultyId: number;
     code: string;
 }
@@ -930,6 +1384,15 @@ export { Speciality }
 export { Speciality as Speciality_alias_1 }
 export { Speciality as Speciality_alias_2 }
 
+/**
+ * The live IIS API returns `educationForm` as either a single object or an array
+ * depending on the endpoint and context. Use `Array.isArray(educationForm)` to distinguish.
+ */
+declare type SpecialityEducationForm = EducationForm | EducationForm[];
+export { SpecialityEducationForm }
+export { SpecialityEducationForm as SpecialityEducationForm_alias_1 }
+export { SpecialityEducationForm as SpecialityEducationForm_alias_2 }
+
 declare interface StudentGroupCatalogItem {
     name: string;
     facultyId: number;
@@ -957,14 +1420,24 @@ export { StudentGroupShort as StudentGroupShort_alias_2 }
 
 /**
  * Reads a cached response value by key, applying TTL validation and LRU touch update.
+ *
+ * Returns the cached value directly (deep-frozen on write) instead of cloning on every
+ * read. Callers that need a mutable copy must clone explicitly. This avoids paying
+ * structuredClone() cost on every cache hit, which can dominate latency for large
+ * schedule payloads on a hot cache path.
  */
 export declare function tryReadCache(config: Readonly<InternalClientConfig>, key: string): unknown;
 
-declare type Weekday = "Понедельник" | "Вторник" | "Среда" | "Четверг" | "Пятница" | "Суббота";
+declare type Weekday = (typeof WEEKDAYS)[number];
 export { Weekday }
 export { Weekday as Weekday_alias_1 }
 export { Weekday as Weekday_alias_2 }
 
+declare const WEEKDAYS: readonly ["Понедельник", "Вторник", "Среда", "Четверг", "Пятница", "Суббота"];
+export { WEEKDAYS }
+export { WEEKDAYS as WEEKDAYS_alias_1 }
+export { WEEKDAYS as WEEKDAYS_alias_2 }
+
 declare type WeekScheduleMap = Partial<Record<Weekday, ScheduleItem[]>>;
 export { WeekScheduleMap }
 export { WeekScheduleMap as WeekScheduleMap_alias_1 }