Support API backend selection (#96)

Author: andrewkoltsov

.gitignore

@@ -5,6 +5,7 @@ coverage/
 .env
 .env.integration
 .env.integration.local
+.env.integration.*.local
 .DS_Store
 .claude/
 .serena/

AGENTS.md

@@ -4,8 +4,11 @@ Guidance for coding agents working in this repository.
 
 ## Project summary
 
-- This is a TypeScript SDK and CLI for the Librus family portal flow.
-- The supported path is `portal.librus.pl` authentication plus child-scoped `https://api.librus.pl/3.0` requests.
+- This is a TypeScript SDK and CLI for Librus family portal and Gateway API 2.0 flows.
+- Supported backends are:
+  - `api_v3`: `portal.librus.pl` authentication plus child-scoped `https://api.librus.pl/3.0` requests.
+  - `gateway_api_20`: school-issued login/password authentication plus cookie-backed `https://synergia.librus.pl/gateway/api/2.0` requests.
+- `api_v3` is multi-child. `gateway_api_20` is already scoped to one account and must not pretend to support Portal-style child switching.
 - Do not reintroduce the legacy `synergia.librus.pl` HTML-scraping approach.
 - The package exposes both an SDK entrypoint and a CLI binary named `librus`.
 
@@ -49,6 +52,9 @@ npm run cli -- grades list --child <id-or-login>
 ## Environment and secrets
 
 - Runtime credentials come from `LIBRUS_PORTAL_EMAIL` and `LIBRUS_PORTAL_PASSWORD`.
+- Gateway API 2.0 credentials come from `LIBRUS_GATEWAY_LOGIN` and `LIBRUS_GATEWAY_PASSWORD`.
+- Backend selection uses `LIBRUS_API_BACKEND=api_v3|gateway_api_20` when explicit; otherwise complete Portal credentials win, then complete Gateway credentials, then `api_v3` default errors.
+- `LIBRUS_CHILD` is an optional default child selector for `api_v3` only. CLI `--child` wins over `LIBRUS_CHILD`; explicit `--child` is unsupported for `gateway_api_20`.
 - `LIBRUS_EMAIL` and `LIBRUS_PASSWORD` are kept as compatibility fallbacks.
 - Never hardcode credentials, tokens, or session cookies.
 - Keep CLI and SDK errors secret-safe. Do not leak passwords, bearer tokens, or raw cookie values in output, logs, tests, or thrown error messages.
@@ -60,7 +66,8 @@ npm run cli -- grades list --child <id-or-login>
 - Preserve the JSON-first CLI behavior: normal results go to stdout, structured errors go to stderr, and commands should return non-zero exit codes on failure.
 - Follow the existing class boundaries:
   - `PortalClient` handles portal login/session concerns.
-  - `LibrusSession` orchestrates login, child discovery, and child selection.
+  - `GatewayApi20AuthClient` handles Gateway API 2.0 login/session concerns.
+  - `LibrusSession` orchestrates backend selection, login, child discovery, and child selection.
   - `SynergiaApiClient` handles authenticated API calls for a specific child account.
 - Keep compatibility with Node 22+. Node 22 is the supported runtime floor for
   SDK, CLI, CI, and dependency updates.
@@ -73,7 +80,7 @@ npm run cli -- grades list --child <id-or-login>
 
 ## Change guidance
 
-- Preserve the current portal-based flow unless the task explicitly requires architectural change.
+- Preserve existing `api_v3` behavior unless the task explicitly requires architectural change, and keep `gateway_api_20` feature support limited to what the upstream JSON API actually provides.
 - All code and documentation changes should be made outside `master`. Prefer one worktree per active feature and one branch per mergeable change. Prefer branches cut from an up-to-date `master`, but allow short-lived dependent branches when the work is intentionally stacked.
 - Keep public SDK exports intentional and update `README.md` when user-facing CLI or SDK behavior changes.
 - Update `CHANGELOG.md` for notable user-facing changes.

CHANGELOG.md

@@ -6,6 +6,25 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+### Added
+
+- Gateway API 2.0 login/password authentication through
+  `LIBRUS_GATEWAY_LOGIN` and `LIBRUS_GATEWAY_PASSWORD`, including
+  `LibrusSession.fromGatewayCredentials()` and CLI child-scoped commands that
+  can run without `--child` in `gateway_api_20`.
+- Public API backend selection through `LIBRUS_API_BACKEND`,
+  `LibrusSessionOptions.apiBackend`, and `LibrusSession.getApiBackend()`.
+- Optional `LIBRUS_CHILD` default child selection for `api_v3` CLI commands.
+
+### Changed
+
+- `LIBRUS_EMAIL` and `LIBRUS_PASSWORD` remain documented as deprecated
+  Portal-only compatibility fallbacks. Use `LIBRUS_PORTAL_EMAIL` and
+  `LIBRUS_PORTAL_PASSWORD` for `api_v3`, or `LIBRUS_GATEWAY_LOGIN` and
+  `LIBRUS_GATEWAY_PASSWORD` for `gateway_api_20`.
+- Deprecated compatibility aliases now emit Node deprecation warnings when
+  used.
+
 ## [0.6.2] - 2026-05-17
 
 ### Fixed

README.md

@@ -1,7 +1,7 @@
 {
   "name": "librus-sdk",
   "version": "0.6.2",
-  "description": "TypeScript SDK and CLI for the Librus family portal flow.",
+  "description": "TypeScript SDK and CLI for Librus family portal and Gateway API 2.0 flows.",
   "author": "Andrey Koltsov",
   "repository": {
     "type": "git",
@@ -42,14 +42,26 @@
     "report:integration": "npm run build && node --env-file=.env.integration.local test/integration/report-all.mjs",
     "report:integration:cli": "npm run build && node --env-file=.env.integration.local test/integration/report-cli.mjs",
     "report:integration:sdk": "npm run build && node --env-file=.env.integration.local test/integration/report-sdk.mjs",
+    "report:integration:gateway-api-20": "npm run build && LIBRUS_API_BACKEND=gateway_api_20 node --env-file=.env.integration.gateway-api-20.local test/integration/report-all.mjs",
+    "report:integration:gateway-api-20:cli": "npm run build && LIBRUS_API_BACKEND=gateway_api_20 node --env-file=.env.integration.gateway-api-20.local test/integration/report-cli.mjs",
+    "report:integration:gateway-api-20:sdk": "npm run build && LIBRUS_API_BACKEND=gateway_api_20 node --env-file=.env.integration.gateway-api-20.local test/integration/report-sdk.mjs",
+    "report:integration:synergia": "npm run build && LIBRUS_API_BACKEND=gateway_api_20 node --env-file=.env.integration.synergia.local test/integration/report-all.mjs",
+    "report:integration:synergia:cli": "npm run build && LIBRUS_API_BACKEND=gateway_api_20 node --env-file=.env.integration.synergia.local test/integration/report-cli.mjs",
+    "report:integration:synergia:sdk": "npm run build && LIBRUS_API_BACKEND=gateway_api_20 node --env-file=.env.integration.synergia.local test/integration/report-sdk.mjs",
     "validate": "npm run lint && npm run format:check && npm run build && npm run test:coverage && npm run pack:check",
     "prepublishOnly": "npm run validate",
     "prepare": "husky",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "test:integration": "npm run build && node --env-file=.env.integration.local --test test/integration/*.integration.test.mjs",
     "test:integration:cli": "npm run build && node --env-file=.env.integration.local --test test/integration/cli.integration.test.mjs",
-    "test:integration:sdk": "npm run build && node --env-file=.env.integration.local --test test/integration/sdk.integration.test.mjs"
+    "test:integration:sdk": "npm run build && node --env-file=.env.integration.local --test test/integration/sdk.integration.test.mjs",
+    "test:integration:gateway-api-20": "npm run build && LIBRUS_API_BACKEND=gateway_api_20 node --env-file=.env.integration.gateway-api-20.local --test test/integration/*.integration.test.mjs",
+    "test:integration:gateway-api-20:cli": "npm run build && LIBRUS_API_BACKEND=gateway_api_20 node --env-file=.env.integration.gateway-api-20.local --test test/integration/cli.integration.test.mjs",
+    "test:integration:gateway-api-20:sdk": "npm run build && LIBRUS_API_BACKEND=gateway_api_20 node --env-file=.env.integration.gateway-api-20.local --test test/integration/sdk.integration.test.mjs",
+    "test:integration:synergia": "npm run build && LIBRUS_API_BACKEND=gateway_api_20 node --env-file=.env.integration.synergia.local --test test/integration/*.integration.test.mjs",
+    "test:integration:synergia:cli": "npm run build && LIBRUS_API_BACKEND=gateway_api_20 node --env-file=.env.integration.synergia.local --test test/integration/cli.integration.test.mjs",
+    "test:integration:synergia:sdk": "npm run build && LIBRUS_API_BACKEND=gateway_api_20 node --env-file=.env.integration.synergia.local --test test/integration/sdk.integration.test.mjs"
   },
   "files": [
     "dist",

package.json

@@ -80,6 +80,7 @@ export function fetchPublishedPackageMetadata(packageSpec) {
   }
 }
 
+/* v8 ignore next -- covered by release workflow smoke usage instead of unit import. */
 if (import.meta.url === pathToFileURL(resolve(process.argv[1] ?? "")).href) {
   const [, , packageName, packageVersion] = process.argv;
 

scripts/verify-published-package.mjs

@@ -3,9 +3,11 @@ import { Command } from "commander";
 import type { CliContext } from "./common.js";
 import {
   addFormatOption,
+  addChildOption,
   configureCommand,
+  createChildApiClient,
   type CliFormatOptions,
-  writeChildScopedOutput,
+  writeOptionalChildScopedOutput,
 } from "./common.js";
 
 export function createAnnouncementsCommand(context: CliContext): Command {
@@ -14,38 +16,44 @@ export function createAnnouncementsCommand(context: CliContext): Command {
     context,
   );
   const list = configureCommand(
-    addFormatOption(
-      new Command("list").description("List school announcements"),
+    addChildOption(
+      addFormatOption(
+        new Command("list").description("List school announcements"),
+      ),
     ),
     context,
   );
   const get = configureCommand(
-    addFormatOption(
-      new Command("get").description("Get a school announcement by id"),
+    addChildOption(
+      addFormatOption(
+        new Command("get").description("Get a school announcement by id"),
+      ),
     ),
     context,
   );
 
-  list.requiredOption("--child <id-or-login>", "Child account id or login");
-  list.action(async (options: CliFormatOptions & { child: string }) => {
+  list.action(async (options: CliFormatOptions & { child?: string }) => {
     const session = context.createSession();
-    const child = await session.resolveChild(options.child);
-    const client = await session.forChild(child);
+    const { child, client } = await createChildApiClient(
+      session,
+      options.child,
+    );
     const data = await client.listSchoolNotices();
 
-    writeChildScopedOutput(context, options.format, child, data);
+    writeOptionalChildScopedOutput(context, options.format, child, data);
   });
 
-  get.requiredOption("--child <id-or-login>", "Child account id or login");
   get.requiredOption("--id <id>", "Announcement id");
   get.action(
-    async (options: CliFormatOptions & { child: string; id: string }) => {
+    async (options: CliFormatOptions & { child?: string; id: string }) => {
       const session = context.createSession();
-      const child = await session.resolveChild(options.child);
-      const client = await session.forChild(child);
+      const { child, client } = await createChildApiClient(
+        session,
+        options.child,
+      );
       const data = await client.getSchoolNotice(options.id);
 
-      writeChildScopedOutput(context, options.format, child, data);
+      writeOptionalChildScopedOutput(context, options.format, child, data);
     },
   );
 

src/cli/commands/announcements.ts

@@ -3,9 +3,11 @@ import { Command } from "commander";
 import type { CliContext } from "./common.js";
 import {
   addFormatOption,
+  addChildOption,
   configureCommand,
+  createChildApiClient,
   type CliFormatOptions,
-  writeChildScopedOutput,
+  writeOptionalChildScopedOutput,
 } from "./common.js";
 
 export function createAttendanceCommand(context: CliContext): Command {
@@ -14,20 +16,23 @@ export function createAttendanceCommand(context: CliContext): Command {
     context,
   );
   const list = configureCommand(
-    addFormatOption(
-      new Command("list").description("List attendances for a child"),
+    addChildOption(
+      addFormatOption(
+        new Command("list").description("List attendances for a child"),
+      ),
     ),
     context,
   );
 
-  list.requiredOption("--child <id-or-login>", "Child account id or login");
-  list.action(async (options: CliFormatOptions & { child: string }) => {
+  list.action(async (options: CliFormatOptions & { child?: string }) => {
     const session = context.createSession();
-    const child = await session.resolveChild(options.child);
-    const client = await session.forChild(child);
+    const { child, client } = await createChildApiClient(
+      session,
+      options.child,
+    );
     const data = await client.getAttendances();
 
-    writeChildScopedOutput(context, options.format, child, data);
+    writeOptionalChildScopedOutput(context, options.format, child, data);
   });
 
   attendance.addCommand(list);