first commit

docs/observability/monitor/analytics-browser/src/session/session.md

@@ -0,0 +1,65 @@
+# `session.ts`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Tracks the lifecycle of a single browser session for `@suaveplan/analytics-browser`. The `SessionManager` owns the session ID, the start time, the page-view counter, the captured `document.referrer`, and the inactivity-timeout state machine. Consumers attach it to a tracker (`tracker.setSessionId(session.getSessionId())`) and call `recordPageView()` / `touch()` as user interaction occurs. The class is fully clock-injectable so tests can drive the inactivity timeout without sleeping.
+
+## Features
+
+- Cryptographically-random session ID (defaults to the package's shared `generateId`).
+- Inactivity timeout — `isActive()` returns `false` after `timeoutMs` of silence; the next `recordPageView()` is a no-op until `renew()` is called.
+- Manual `renew()` — resets the ID, start time, page-view count, and active flag (used on logout / login or app-managed session boundary events).
+- Injectable `clock`, `idGenerator`, and `referrer` for deterministic tests and SSR.
+
+## Usage: Basic
+
+```ts
+import { SessionManager } from "@suaveplan/analytics-browser/session";
+
+const session = new SessionManager({ timeoutMs: 30 * 60 * 1000 });
+session.recordPageView();
+const info = session.getInfo();
+```
+
+## Usage: Advanced
+
+```ts
+import { SessionManager } from "@suaveplan/analytics-browser/session";
+
+let now = 0;
+const session = new SessionManager({
+    timeoutMs: 60_000,
+    clock: () => now,
+    idGenerator: () => "test-session",
+    referrer: "https://example.com",
+});
+
+now = 30_000;
+session.recordPageView();
+now = 120_000; // exceeds timeoutMs since last activity
+session.isActive(); // → false
+session.renew(); // mint a fresh session id
+```
+
+## API Reference
+
+- `class SessionManager`
+  - `new SessionManager(options?)` — `options: SessionOptions { timeoutMs?, referrer?, clock?, idGenerator? }`
+  - `getSessionId(): string`
+  - `getReferrer(): string`
+  - `getPageViews(): number`
+  - `recordPageView(): void` — no-op when session is inactive
+  - `touch(): void` — resets the inactivity clock
+  - `getDuration(): number` — milliseconds since `startedAt`
+  - `isActive(): boolean` — auto-expires past `timeoutMs`
+  - `end(): void` — explicitly terminates the session
+  - `renew(): string` — mints a fresh session id, zeros page views, resets the inactivity clock
+  - `getInfo(): SessionInfo` — `{ id, startedAt, pageViews, duration, referrer, isActive }`
+
+## Implementation Notes
+
+`getDuration` returns the live duration when the session is active, otherwise the duration up to the last activity timestamp. This keeps the duration stable after `end()` is called — repeated `getDuration()` calls on an ended session return the same value rather than drifting upward with wall-clock time. The `document.referrer` lookup is guarded by `typeof document !== "undefined"` so SSR contexts default to `""` rather than throwing.