bsuir-iis-api 0.9.1 → 0.10.0

package/dist/index.js

@@ -177,25 +177,7 @@ function isAbortError(error) {
   return false;
 }
 
-// src/client/http.ts
-var RETRIABLE_STATUS_CODES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
-function buildUrl(baseUrl, path, query) {
-  const normalizedBase = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
-  const normalizedPath = path.startsWith("/") ? path : `/${path}`;
-  const url = new URL(`${normalizedBase}${normalizedPath}`);
-  if (query) {
-    for (const [key, value] of Object.entries(query)) {
-      if (value === void 0 || value === null) {
-        continue;
-      }
-      url.searchParams.set(key, String(value));
-    }
-  }
-  return url.toString();
-}
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
+// src/client/http/cache.ts
 function tryReadCache(config, key) {
   const entry = config.responseCache.get(key);
   if (!entry) {
@@ -240,14 +222,81 @@ function setCache(config, key, value) {
     }
   }
 }
-function combineAbortSignals(first, second) {
-  if (!first) {
-    return second;
+
+// src/client/http/response.ts
+async function readBodyTextWithLimit(response, maxResponseBytes) {
+  const contentLengthHeader = response.headers.get("content-length");
+  if (contentLengthHeader) {
+    const parsedLength = Number(contentLengthHeader);
+    if (Number.isFinite(parsedLength) && parsedLength > maxResponseBytes) {
+      throw new BsuirApiError(
+        `Response body exceeds maxResponseBytes limit (${String(maxResponseBytes)} bytes)`,
+        response.status,
+        response.url,
+        null
+      );
+    }
   }
-  if (!second) {
-    return first;
+  if (!response.body || typeof response.body.getReader !== "function") {
+    const fallbackText = await response.text();
+    if (new TextEncoder().encode(fallbackText).byteLength > maxResponseBytes) {
+      throw new BsuirApiError(
+        `Response body exceeds maxResponseBytes limit (${String(maxResponseBytes)} bytes)`,
+        response.status,
+        response.url,
+        null
+      );
+    }
+    return fallbackText;
+  }
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let bytesRead = 0;
+  let text = "";
+  for (; ; ) {
+    const { done, value } = await reader.read();
+    if (done) {
+      break;
+    }
+    bytesRead += value.byteLength;
+    if (bytesRead > maxResponseBytes) {
+      await reader.cancel();
+      throw new BsuirApiError(
+        `Response body exceeds maxResponseBytes limit (${String(maxResponseBytes)} bytes)`,
+        response.status,
+        response.url,
+        null
+      );
+    }
+    text += decoder.decode(value, { stream: true });
   }
-  return mergeSignals([first, second]);
+  text += decoder.decode();
+  return text;
+}
+async function parseBody(response, maxResponseBytes) {
+  const contentType = response.headers.get("content-type") ?? "";
+  const declaredJson = contentType.includes("application/json");
+  const text = await readBodyTextWithLimit(response, maxResponseBytes);
+  if (text.length === 0) {
+    if (declaredJson) {
+      throw new BsuirApiError("Invalid JSON response payload", response.status, response.url, null);
+    }
+    return "";
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    if (declaredJson) {
+      throw new BsuirApiError("Invalid JSON response payload", response.status, response.url, null);
+    }
+    return text;
+  }
+}
+
+// src/client/http/retry.ts
+var RETRIABLE_STATUS_CODES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
 }
 function parseRetryAfterMs(retryAfter) {
   if (!retryAfter || retryAfter.trim().length === 0) {
@@ -281,24 +330,32 @@ function getRetryDelayMs(config, attempt, retryAfterHeader) {
   const jitterFactor = 0.75 + Math.random() * 0.5;
   return Math.floor(baseDelay * jitterFactor);
 }
-async function parseBody(response) {
-  const contentType = response.headers.get("content-type") ?? "";
-  const declaredJson = contentType.includes("application/json");
-  const text = await response.text();
-  if (text.length === 0) {
-    if (declaredJson) {
-      throw new BsuirApiError("Invalid JSON response payload", response.status, response.url, null);
+
+// src/client/http/url.ts
+function buildUrl(baseUrl, path, query) {
+  const normalizedBase = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+  const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+  const url = new URL(`${normalizedBase}${normalizedPath}`);
+  if (query) {
+    for (const [key, value] of Object.entries(query)) {
+      if (value === void 0 || value === null) {
+        continue;
+      }
+      url.searchParams.set(key, String(value));
     }
-    return "";
   }
-  try {
-    return JSON.parse(text);
-  } catch {
-    if (declaredJson) {
-      throw new BsuirApiError("Invalid JSON response payload", response.status, response.url, null);
-    }
-    return text;
+  return url.toString();
+}
+
+// src/client/http/requestJson.ts
+function combineAbortSignals(first, second) {
+  if (!first) {
+    return second;
+  }
+  if (!second) {
+    return first;
   }
+  return mergeSignals([first, second]);
 }
 function baseHookContext(method, path, endpoint, attempt, maxAttempts, query) {
   return {
@@ -367,7 +424,7 @@ async function requestJson(config, path, options = {}) {
         }
         const response = await config.fetchImpl(endpoint, requestInit);
         if (!response.ok) {
-          const errorBody = await parseBody(response);
+          const errorBody = await parseBody(response, config.maxResponseBytes);
           if (attempt < maxRetries && RETRIABLE_STATUS_CODES.has(response.status)) {
             const delayMs = getRetryDelayMs(config, attempt, response.headers.get("retry-after"));
             const retryCtx = {
@@ -394,7 +451,7 @@ async function requestJson(config, path, options = {}) {
           config.hooks.onError?.(errorCtx);
           throw apiError;
         }
-        const parsed = await parseBody(response);
+        const parsed = await parseBody(response, config.maxResponseBytes);
         const responseCtx = {
           ...hookCtx,
           status: response.status,
@@ -596,119 +653,47 @@ function createAnnouncementsModule(config) {
   };
 }
 
-// src/modules/auditories.ts
-function createAuditoriesModule(config) {
+// src/modules/createListModule.ts
+function createListModule(config, endpoint) {
   return {
     /**
-     * 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`
-      */
+     * Returns all items from the configured endpoint.
+     */
     async listAll(options = {}) {
-      const payload = await requestJson(config, "/auditories", {
+      const payload = await requestJson(config, endpoint, {
         signal: options.signal
       });
       if (config.validateResponses) {
-        assertArrayResponse(payload, "/auditories");
+        assertArrayResponse(payload, endpoint);
       }
       return payload;
     }
   };
 }
 
+// src/modules/auditories.ts
+function createAuditoriesModule(config) {
+  return createListModule(config, "/auditories");
+}
+
 // src/modules/departments.ts
 function createDepartmentsModule(config) {
-  return {
-    /**
-     * 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`
-      */
-    async listAll(options = {}) {
-      const payload = await requestJson(config, "/departments", {
-        signal: options.signal
-      });
-      if (config.validateResponses) {
-        assertArrayResponse(payload, "/departments");
-      }
-      return payload;
-    }
-  };
+  return createListModule(config, "/departments");
 }
 
 // src/modules/employees.ts
 function createEmployeesModule(config) {
-  return {
-    /**
-     * 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`
-      */
-    async listAll(options = {}) {
-      const payload = await requestJson(config, "/employees/all", {
-        signal: options.signal
-      });
-      if (config.validateResponses) {
-        assertArrayResponse(payload, "/employees/all");
-      }
-      return payload;
-    }
-  };
+  return createListModule(config, "/employees/all");
 }
 
 // src/modules/faculties.ts
 function createFacultiesModule(config) {
-  return {
-    /**
-     * 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`
-      */
-    async listAll(options = {}) {
-      const payload = await requestJson(config, "/faculties", {
-        signal: options.signal
-      });
-      if (config.validateResponses) {
-        assertArrayResponse(payload, "/faculties");
-      }
-      return payload;
-    }
-  };
+  return createListModule(config, "/faculties");
 }
 
 // src/modules/groups.ts
 function createGroupsModule(config) {
-  return {
-    /**
-     * 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`
-      */
-    async listAll(options = {}) {
-      const payload = await requestJson(config, "/student-groups", {
-        signal: options.signal
-      });
-      if (config.validateResponses) {
-        assertArrayResponse(payload, "/student-groups");
-      }
-      return payload;
-    }
-  };
+  return createListModule(config, "/student-groups");
 }
 
 // src/utils/week.ts
@@ -747,7 +732,58 @@ function parseCurrentWeekInternal(payload, depth) {
   throw new BsuirValidationError("'currentWeek' response payload must be a positive integer");
 }
 
-// src/modules/schedule.ts
+// src/modules/scheduleFilter.ts
+function lessonAuditories(item) {
+  const { auditories } = item;
+  return Array.isArray(auditories) ? auditories : [];
+}
+function matchesFilter(item, filter) {
+  if (filter.source && item.source !== filter.source) {
+    return false;
+  }
+  if (filter.weekday && item.day !== filter.weekday) {
+    return false;
+  }
+  if (typeof filter.weekNumber === "number") {
+    if (!Array.isArray(item.weekNumber) || !item.weekNumber.includes(filter.weekNumber)) {
+      return false;
+    }
+  }
+  if (typeof filter.subgroup === "number" && item.numSubgroup !== filter.subgroup) {
+    return false;
+  }
+  if (filter.lessonTypeAbbrev) {
+    const types = Array.isArray(filter.lessonTypeAbbrev) ? filter.lessonTypeAbbrev : [filter.lessonTypeAbbrev];
+    if (!item.lessonTypeAbbrev || !types.includes(item.lessonTypeAbbrev)) {
+      return false;
+    }
+  }
+  if (filter.subjectQuery) {
+    const query = filter.subjectQuery.toLowerCase();
+    const haystack = `${item.subject} ${item.subjectFullName} ${item.note ?? ""}`.toLowerCase();
+    if (!haystack.includes(query)) {
+      return false;
+    }
+  }
+  if (filter.employeeUrlId) {
+    const employeeMatch = item.employees?.some((employee) => employee.urlId === filter.employeeUrlId);
+    if (!employeeMatch) {
+      return false;
+    }
+  }
+  if (filter.auditory && !lessonAuditories(item).includes(filter.auditory)) {
+    return false;
+  }
+  return true;
+}
+function filterLessons(response, filter) {
+  if (typeof filter.weekNumber === "number") {
+    assertPositiveInt(filter.weekNumber, "filter.weekNumber");
+  }
+  return response.lessons.filter((item) => matchesFilter(item, filter));
+}
+
+// src/modules/scheduleNormalize.ts
 var WEEKDAYS = [
   "\u041F\u043E\u043D\u0435\u0434\u0435\u043B\u044C\u043D\u0438\u043A",
   "\u0412\u0442\u043E\u0440\u043D\u0438\u043A",
@@ -756,7 +792,7 @@ var WEEKDAYS = [
   "\u041F\u044F\u0442\u043D\u0438\u0446\u0430",
   "\u0421\u0443\u0431\u0431\u043E\u0442\u0430"
 ];
-function lessonAuditories(item) {
+function lessonAuditories2(item) {
   const { auditories } = item;
   return Array.isArray(auditories) ? auditories : [];
 }
@@ -772,7 +808,7 @@ function normalizeSchedule(response) {
   for (const day of WEEKDAYS) {
     const dayItems = safeSchedules[day] ?? [];
     const flattenedDayItems = dayItems.map((item) => {
-      const auditories = lessonAuditories(item);
+      const auditories = lessonAuditories2(item);
       return {
         ...item,
         auditories,
@@ -785,12 +821,11 @@ function normalizeSchedule(response) {
     scheduleLessons.push(...flattenedDayItems);
   }
   for (const exam of safeExams) {
-    const auditories = lessonAuditories(exam);
+    const auditories = lessonAuditories2(exam);
     const flattenedExam = {
       ...exam,
       auditories,
       day: null,
-      // Exams are not grouped by weekday in API response.
       source: "exams"
     };
     lessons.push(flattenedExam);
@@ -806,51 +841,8 @@ function normalizeSchedule(response) {
     examLessons
   };
 }
-function matchesFilter(item, filter) {
-  if (filter.source && item.source !== filter.source) {
-    return false;
-  }
-  if (filter.weekday && item.day !== filter.weekday) {
-    return false;
-  }
-  if (typeof filter.weekNumber === "number") {
-    if (!Array.isArray(item.weekNumber) || !item.weekNumber.includes(filter.weekNumber)) {
-      return false;
-    }
-  }
-  if (typeof filter.subgroup === "number" && item.numSubgroup !== filter.subgroup) {
-    return false;
-  }
-  if (filter.lessonTypeAbbrev) {
-    const types = Array.isArray(filter.lessonTypeAbbrev) ? filter.lessonTypeAbbrev : [filter.lessonTypeAbbrev];
-    if (!item.lessonTypeAbbrev || !types.includes(item.lessonTypeAbbrev)) {
-      return false;
-    }
-  }
-  if (filter.subjectQuery) {
-    const query = filter.subjectQuery.toLowerCase();
-    const haystack = `${item.subject} ${item.subjectFullName} ${item.note ?? ""}`.toLowerCase();
-    if (!haystack.includes(query)) {
-      return false;
-    }
-  }
-  if (filter.employeeUrlId) {
-    const employeeMatch = item.employees?.some((employee) => employee.urlId === filter.employeeUrlId);
-    if (!employeeMatch) {
-      return false;
-    }
-  }
-  if (filter.auditory && !lessonAuditories(item).includes(filter.auditory)) {
-    return false;
-  }
-  return true;
-}
-function filterLessons(response, filter) {
-  if (typeof filter.weekNumber === "number") {
-    assertPositiveInt(filter.weekNumber, "filter.weekNumber");
-  }
-  return response.lessons.filter((item) => matchesFilter(item, filter));
-}
+
+// src/modules/scheduleApi.ts
 function createScheduleModule(config) {
   async function getGroup(groupNumber, options = {}) {
     assertGroupNumber(groupNumber, "groupNumber");
@@ -895,24 +887,35 @@ function createScheduleModule(config) {
     getEmployee,
     getGroupFiltered,
     getEmployeeFiltered,
+    /**
+     * Returns exams for a group.
+     */
     async getGroupExams(groupNumber, options = {}) {
       return getGroupFiltered(groupNumber, { source: "exams" }, options);
     },
+    /**
+     * Returns exams for an employee.
+     */
     async getEmployeeExams(urlId, options = {}) {
       return getEmployeeFiltered(urlId, { source: "exams" }, options);
     },
+    /**
+     * Returns regular schedule lessons of a specific subgroup for a group.
+     */
     async getGroupBySubgroup(groupNumber, subgroup, options = {}) {
       assertPositiveInt(subgroup, "subgroup");
       return getGroupFiltered(groupNumber, { source: "schedules", subgroup }, options);
     },
+    /**
+     * Returns regular schedule lessons of a specific subgroup for an employee.
+     */
     async getEmployeeBySubgroup(urlId, subgroup, options = {}) {
       assertPositiveInt(subgroup, "subgroup");
       return getEmployeeFiltered(urlId, { source: "schedules", subgroup }, options);
     },
     getCurrentWeek,
     /**
-     * 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`.
      */
     async getLastUpdateByGroup(params, options = {}) {
       let query;
@@ -933,8 +936,7 @@ function createScheduleModule(config) {
       return payload;
     },
     /**
-     * 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`.
      */
     async getLastUpdateByEmployee(params, options = {}) {
       let query;
@@ -959,29 +961,13 @@ function createScheduleModule(config) {
 
 // src/modules/specialities.ts
 function createSpecialitiesModule(config) {
-  return {
-    /**
-     * 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`
-      */
-    async listAll(options = {}) {
-      const payload = await requestJson(config, "/specialities", {
-        signal: options.signal
-      });
-      if (config.validateResponses) {
-        assertArrayResponse(payload, "/specialities");
-      }
-      return payload;
-    }
-  };
+  return createListModule(config, "/specialities");
 }
 
 // src/client/createClient.ts
 var DEFAULT_BASE_URL = "https://iis.bsuir.by/api/v1";
+var DEFAULT_ALLOWED_BASE_URL_HOSTS = ["iis.bsuir.by"];
+var DEFAULT_MAX_RESPONSE_BYTES = 5e6;
 var MAX_TIMEOUT_MS = 3e5;
 function resolveFetch(customFetch) {
   if (customFetch) {
@@ -1005,6 +991,39 @@ function assertIntegerOption(value, name, minInclusive) {
   }
   return value;
 }
+function normalizeBaseUrl(rawBaseUrl, allowInsecureHttp, allowedHosts) {
+  let parsed;
+  try {
+    parsed = new URL(rawBaseUrl);
+  } catch {
+    throw new BsuirConfigurationError("'baseUrl' must be a valid absolute URL");
+  }
+  if (parsed.username || parsed.password) {
+    throw new BsuirConfigurationError("'baseUrl' must not include credentials");
+  }
+  if (parsed.search || parsed.hash) {
+    throw new BsuirConfigurationError("'baseUrl' must not include query string or hash");
+  }
+  if (parsed.protocol !== "https:" && !(allowInsecureHttp && parsed.protocol === "http:")) {
+    throw new BsuirConfigurationError(
+      "'baseUrl' must use HTTPS. Set 'allowInsecureHttp: true' only for trusted local/test endpoints."
+    );
+  }
+  const normalizedAllowedHosts = new Set(
+    allowedHosts.map((host2) => host2.trim().toLowerCase()).filter((host2) => host2.length > 0)
+  );
+  if (normalizedAllowedHosts.size === 0) {
+    throw new BsuirConfigurationError("'allowedBaseUrlHosts' must contain at least one hostname");
+  }
+  const host = parsed.hostname.toLowerCase();
+  if (!normalizedAllowedHosts.has(host)) {
+    throw new BsuirConfigurationError(
+      `'baseUrl' host '${host}' is not allowed. Allowed hosts: ${[...normalizedAllowedHosts].join(", ")}`
+    );
+  }
+  const normalizedPath = parsed.pathname.replace(/\/+$/, "");
+  return `${parsed.origin}${normalizedPath}`;
+}
 function createInternalConfig(options) {
   const timeoutMs = assertIntegerOption(options.timeoutMs, "timeoutMs", 1) ?? 1e4;
   if (timeoutMs > MAX_TIMEOUT_MS) {
@@ -1017,13 +1036,16 @@ function createInternalConfig(options) {
   const retryMaxDelayMs = assertIntegerOption(options.retryMaxDelayMs, "retryMaxDelayMs", 0) ?? 3e3;
   const cacheTtlMs = assertIntegerOption(options.cache?.ttlMs, "cache.ttlMs", 1);
   const cacheMaxEntries = assertIntegerOption(options.cache?.maxEntries, "cache.maxEntries", 1) ?? 200;
+  const maxResponseBytes = assertIntegerOption(options.maxResponseBytes, "maxResponseBytes", 1) ?? DEFAULT_MAX_RESPONSE_BYTES;
+  const allowInsecureHttp = options.allowInsecureHttp ?? false;
+  const allowedBaseUrlHosts = options.allowedBaseUrlHosts ?? DEFAULT_ALLOWED_BASE_URL_HOSTS;
   if (retryDelayMs > retryMaxDelayMs) {
     throw new BsuirConfigurationError(
       "'retryDelayMs' must be less than or equal to 'retryMaxDelayMs'"
     );
   }
   return {
-    baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
+    baseUrl: normalizeBaseUrl(options.baseUrl ?? DEFAULT_BASE_URL, allowInsecureHttp, allowedBaseUrlHosts),
     fetchImpl: resolveFetch(options.fetch),
     signal: options.signal,
     timeoutMs,
@@ -1035,7 +1057,8 @@ function createInternalConfig(options) {
     cacheTtlMs,
     cacheMaxEntries,
     dedupeInFlight: options.dedupeInFlight ?? true,
-    validateResponses: options.validateResponses ?? false,
+    maxResponseBytes,
+    validateResponses: options.validateResponses ?? true,
     hooks: options.hooks ?? {},
     responseCache: /* @__PURE__ */ new Map(),
     inFlightRequests: /* @__PURE__ */ new Map(),