add logging hooks

Author: andrewkoltsov

CHANGELOG.md

@@ -10,6 +10,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 - Generated OpenAPI documents for the supported `gateway_api_20` and
   `wiadomosci.librus.pl/api` surfaces.
+- Secret-safe SDK logging hooks for Portal login and Synergia request lifecycle
+  events, plus CLI `--verbose` and `LIBRUS_LOG_LEVEL` stderr diagnostics.
 
 ## [0.7.1] - 2026-05-20
 

README.md

@@ -83,6 +83,7 @@ these variables:
 | `LIBRUS_GATEWAY_PASSWORD` | `gateway_api_20` | Password for the Gateway API 2.0 login.                            |
 | `LIBRUS_CHILD`            | No               | Optional default child id or login for `api_v3` CLI commands.      |
 | `LIBRUS_TIMEOUT_MS`       | No               | Positive integer request timeout in milliseconds.                  |
+| `LIBRUS_LOG_LEVEL`        | No               | Optional CLI SDK log level: `debug`, `info`, `warn`, or `error`.   |
 
 If no timeout is configured, portal and child-scoped SDK requests default to
 `30000` milliseconds. Invalid timeout values fail fast with
@@ -117,6 +118,7 @@ import {
   generateWiadomosciOpenApiDocument,
   LibrusSdkError,
   type LibrusApiBackend,
+  type Logger,
 } from "librus-sdk";
 ```
 
@@ -127,6 +129,7 @@ import {
 | `GatewayApi20AuthClient`              | Lower-level Gateway API 2.0 login/password auth client for `synergia.librus.pl/gateway/api/2.0` cookie-backed requests.               |
 | `PortalClient`                        | Lower-level portal session client for `portal.librus.pl` login, `/Me`, and `/SynergiaAccounts`.                                       |
 | `SynergiaApiClient`                   | Child-scoped GET client for the supported `https://api.librus.pl/3.0` surface when you already have a bearer token.                   |
+| `Logger`                              | Minimal structured logging interface accepted by SDK clients and sessions.                                                            |
 | `generateOpenApiDocument`             | Generates the shipped OpenAPI document for the supported `api_v3` child-scoped GET subset.                                            |
 | `generateGatewayApi20OpenApiDocument` | Generates the shipped OpenAPI document for the supported `gateway_api_20` GET subset.                                                 |
 | `generateWiadomosciOpenApiDocument`   | Generates the shipped OpenAPI document for the supported `wiadomosci.librus.pl/api` inbox subset.                                     |
@@ -143,6 +146,26 @@ const grades = await client.getGrades();
 console.log(grades);
 ```
 
+Custom logger:
+
+```ts
+import { LibrusSession, type Logger } from "librus-sdk";
+import pino from "pino";
+
+const pinoLogger = pino();
+const logger: Logger = {
+  log: (level, event, fields) => pinoLogger[level]({ event, ...fields }),
+};
+
+const session = LibrusSession.fromEnv(process.env, { logger });
+const client = await session.forChild("child-login");
+await client.getGrades();
+```
+
+SDK logs are structured and secret-safe. They include request URLs, status,
+durations, auth mode, and stable error codes, but never include passwords,
+bearer tokens, cookie values, request bodies, or response bodies.
+
 Gateway API 2.0 flow:
 
 ```bash
@@ -171,9 +194,9 @@ with `UNSUPPORTED_BACKEND` in `gateway_api_20`.
 
 Current high-level methods on `LibrusSession`:
 
-- `LibrusSession.fromEnv(env?)`
+- `LibrusSession.fromEnv(env?, options?)`
 - `LibrusSession.fromGatewayCredentials(credentials, options?)`
-- `new LibrusSession({ apiBackend?, credentials, portalClient?, portalClientOptions?, gatewayApi20AuthClient?, gatewayApi20AuthClientOptions?, bffClientOptions?, synergiaClientOptions?, wiadomosciClientOptions?, requestTimeoutMs? })`
+- `new LibrusSession({ apiBackend?, credentials, portalClient?, portalClientOptions?, gatewayApi20AuthClient?, gatewayApi20AuthClientOptions?, bffClientOptions?, synergiaClientOptions?, wiadomosciClientOptions?, requestTimeoutMs?, logger? })`
 - `login()`
 - `getApiBackend()`
 - `getPortalMe()`
@@ -311,6 +334,7 @@ Root CLI commands:
 
 - `librus-sdk --help`
 - `librus-sdk --version`
+- `librus-sdk --verbose <command>`
 
 Every leaf command supports `--format <text|json>`. In `api_v3`, child-scoped
 commands require a child selector: pass `--child <id-or-login>` or set
@@ -320,6 +344,10 @@ explicit `--child` fails with `UNSUPPORTED_BACKEND`. Portal-only commands such
 as `children list`, `messages bff-list`, and `messages wiadomosci-list` are not
 available in `gateway_api_20`.
 
+`--verbose` enables debug-level SDK diagnostics on stderr. `LIBRUS_LOG_LEVEL`
+can enable diagnostics without a flag and filters by minimum level. Successful
+command payloads still go to stdout, so `--format json` remains machine-readable.
+
 | Family           | Subcommands                                                                                                 | Extra selectors and flags                                                                                                                                                                          |
 | ---------------- | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `children`       | `list`                                                                                                      | Portal-only; no child selector.                                                                                                                                                                    |

src/cli/commands/common.ts

@@ -4,6 +4,7 @@ import { InvalidArgumentError, type Command } from "commander";
 import {
   LibrusSession,
   LibrusSdkError,
+  type Logger,
   type ChildAccount,
   type ChildAccountSummary,
   type LibrusApiBackend,
@@ -33,7 +34,7 @@ export interface CliOutput {
 export interface CliContext {
   stdout: CliOutput;
   stderr: CliOutput;
-  createSession: () => LibrusSession;
+  createSession: (logger?: Logger) => LibrusSession;
   outputWidth?: number;
   writeFile?: (path: string, data: Uint8Array) => void;
 }

src/cli/logger.ts

@@ -0,0 +1,90 @@
+import {
+  LibrusConfigurationError,
+  type Logger,
+  type LogLevel,
+} from "../sdk/index.js";
+import type { CliOutput } from "./commands/common.js";
+
+const LOG_LEVELS: LogLevel[] = ["debug", "info", "warn", "error"];
+const LOG_LEVEL_PRIORITY: Record<LogLevel, number> = {
+  debug: 10,
+  info: 20,
+  warn: 30,
+  error: 40,
+};
+
+export function createCliLogger(
+  output: CliOutput,
+  minimumLevel: LogLevel,
+): Logger {
+  return {
+    log(level, event, fields = {}) {
+      if (LOG_LEVEL_PRIORITY[level] < LOG_LEVEL_PRIORITY[minimumLevel]) {
+        return;
+      }
+
+      output.write(
+        `${new Date().toISOString()} ${level.toUpperCase()} ${event}${formatFields(fields)}\n`,
+      );
+    },
+  };
+}
+
+export function resolveCliLogLevel(
+  argv: string[],
+  env: NodeJS.ProcessEnv = process.env,
+): LogLevel | undefined {
+  if (argv.includes("--verbose")) {
+    return "debug";
+  }
+
+  const rawLogLevel = env.LIBRUS_LOG_LEVEL;
+
+  if (rawLogLevel === undefined) {
+    return undefined;
+  }
+
+  const logLevel = rawLogLevel.trim().toLowerCase();
+
+  if (isLogLevel(logLevel)) {
+    return logLevel;
+  }
+
+  throw new LibrusConfigurationError(
+    'Invalid LIBRUS_LOG_LEVEL. Expected "debug", "info", "warn", or "error".',
+  );
+}
+
+function isLogLevel(value: string): value is LogLevel {
+  return LOG_LEVELS.includes(value as LogLevel);
+}
+
+function formatFields(fields: Record<string, unknown>): string {
+  const entries = Object.entries(fields).filter(
+    ([, value]) => value !== undefined,
+  );
+
+  if (entries.length === 0) {
+    return "";
+  }
+
+  return ` ${entries
+    .map(([key, value]) => `${key}=${formatFieldValue(value)}`)
+    .join(" ")}`;
+}
+
+function formatFieldValue(value: unknown): string {
+  if (
+    value === null ||
+    typeof value === "number" ||
+    typeof value === "boolean"
+  ) {
+    return String(value);
+  }
+
+  if (typeof value === "string") {
+    return JSON.stringify(value);
+  }
+
+  return JSON.stringify(value);
+}

src/cli/main.ts

@@ -26,6 +26,7 @@ import { createMeCommand } from "./commands/me.js";
 import { createNotesCommand } from "./commands/notes.js";
 import { createNotificationsCommand } from "./commands/notifications.js";
 import { createTimetableCommand } from "./commands/timetable.js";
+import { createCliLogger, resolveCliLogLevel } from "./logger.js";
 
 const packageJson = JSON.parse(
   readFileSync(new URL("../../package.json", import.meta.url), "utf8"),
@@ -39,7 +40,10 @@ export function createDefaultCliContext(): CliContext {
     stderr: {
       write: (chunk) => process.stderr.write(chunk),
     },
-    createSession: () => LibrusSession.fromEnv(),
+    createSession: (logger) =>
+      logger === undefined
+        ? LibrusSession.fromEnv()
+        : LibrusSession.fromEnv(process.env, { logger }),
     outputWidth: process.stdout.columns ?? 80,
     writeFile: (path, data) => writeFileSync(path, data),
   };
@@ -50,7 +54,8 @@ export function createProgram(context: CliContext): Command {
     new Command()
       .name("librus-sdk")
       .description("CLI for the Librus family portal flow")
-      .version(packageJson.version),
+      .version(packageJson.version)
+      .option("--verbose", "Write diagnostic logs to stderr"),
     context,
   );
 
@@ -76,19 +81,35 @@ export async function runCli(
   argv = process.argv,
   context = createDefaultCliContext(),
 ): Promise<number> {
-  const program = createProgram(context);
   const userArgs = argv.slice(2);
+  const helpProgram = createProgram(context);
 
   if (
     userArgs.length === 0 ||
     (userArgs.length === 1 &&
       (userArgs[0] === "--help" || userArgs[0] === "-h"))
   ) {
-    context.stdout.write(program.helpInformation());
+    context.stdout.write(helpProgram.helpInformation());
     return 0;
   }
 
   try {
+    const logLevel = isInformationalCliInvocation(userArgs)
+      ? undefined
+      : resolveCliLogLevel(userArgs);
+    const logger =
+      logLevel === undefined
+        ? undefined
+        : createCliLogger(context.stderr, logLevel);
+    const runtimeContext =
+      logger === undefined
+        ? context
+        : {
+            ...context,
+            createSession: () => context.createSession(logger),
+          };
+    const program = createProgram(runtimeContext);
+
     await program.parseAsync(argv);
     return 0;
   } catch (error) {
@@ -119,6 +140,13 @@ export async function runCli(
   }
 }
 
+function isInformationalCliInvocation(argv: string[]): boolean {
+  return argv.some(
+    (arg) =>
+      arg === "--help" || arg === "-h" || arg === "--version" || arg === "-V",
+  );
+}
+
 export function isCliEntryPoint(
   argv = process.argv,
   moduleUrl = import.meta.url,

src/sdk/LibrusSession.ts

@@ -30,6 +30,7 @@ import {
   validateOptionalRequestTimeoutMs,
 } from "./requestTimeout.js";
 import { emitDeprecationWarningOnce } from "./deprecationWarnings.js";
+import type { Logger } from "./logger.js";
 
 type PortalCredentialEnvName =
   | "LIBRUS_EMAIL"
@@ -103,6 +104,7 @@ export interface LibrusSessionOptions {
     "ensurePortalLogin" | "portalClient"
   >;
   requestTimeoutMs?: number;
+  logger?: Logger;
 }
 
 export class LibrusSession {
@@ -154,9 +156,13 @@ export class LibrusSession {
       options.portalClientOptions,
       requestTimeoutMs,
     );
-    const synergiaClientOptions = applyRequestTimeout(
-      options.synergiaClientOptions,
-      requestTimeoutMs,
+    const loggedPortalClientOptions = applyLogger(
+      portalClientOptions,
+      options.logger,
+    );
+    const synergiaClientOptions = applyLogger(
+      applyRequestTimeout(options.synergiaClientOptions, requestTimeoutMs),
+      options.logger,
     );
     const bffClientOptions = applyRequestTimeout(
       options.bffClientOptions,
@@ -175,7 +181,7 @@ export class LibrusSession {
     if (this.apiBackend === "api_v3") {
       this.portalCredentials = normalizePortalCredentials(options.credentials);
       this.portalClient =
-        options.portalClient ?? new PortalClient(portalClientOptions);
+        options.portalClient ?? new PortalClient(loggedPortalClientOptions);
     } else {
       this.gatewayCredentials = normalizeGatewayCredentials(
         options.credentials,
@@ -191,22 +197,34 @@ export class LibrusSession {
     this.wiadomosciClientOptions = wiadomosciClientOptions;
   }
 
-  static fromEnv(env: NodeJS.ProcessEnv = process.env): LibrusSession {
+  static fromEnv(
+    env: NodeJS.ProcessEnv = process.env,
+    options: Omit<
+      LibrusSessionOptions,
+      "apiBackend" | "authMode" | "credentials"
+    > = {},
+  ): LibrusSession {
     const apiBackend = resolveApiBackend(env);
     const requestTimeoutMs = parseRequestTimeoutMsFromEnv(
       env.LIBRUS_TIMEOUT_MS,
     );
-    const options = requestTimeoutMs === undefined ? {} : { requestTimeoutMs };
+    const sessionOptions =
+      requestTimeoutMs === undefined
+        ? options
+        : {
+            ...options,
+            requestTimeoutMs: options.requestTimeoutMs ?? requestTimeoutMs,
+          };
 
     if (apiBackend === "gateway_api_20") {
       return LibrusSession.fromGatewayCredentials(
         resolveGatewayCredentialsFromEnv(env),
-        options,
+        sessionOptions,
       );
     }
 
     return new LibrusSession({
-      ...options,
+      ...sessionOptions,
       apiBackend: "api_v3",
       credentials: resolvePortalCredentialsFromEnv(env),
     });
@@ -738,3 +756,14 @@ function applyRequestTimeout<T extends { requestTimeoutMs?: number }>(
     ? { ...options, requestTimeoutMs }
     : ({ requestTimeoutMs } as T);
 }
+
+function applyLogger<T extends { logger?: Logger }>(
+  options: T | undefined,
+  logger: Logger | undefined,
+): T | undefined {
+  if (options?.logger !== undefined || logger === undefined) {
+    return options;
+  }
+
+  return options ? { ...options, logger } : ({ logger } as T);
+}

src/sdk/index.ts

@@ -1,4 +1,5 @@
 export { BffApiClient } from "./bff/BffApiClient.js";
+export { noopLogger, type Logger, type LogLevel } from "./logger.js";
 export {
   LibrusSession,
   type LibrusApiBackend,