first commit

docs/observability/monitor/analytics-browser/src/internal/id/id.md

@@ -0,0 +1,51 @@
+# `id.ts`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Internal cryptographically-random ID generator shared by the analytics tracker, the session manager, and any consumer that injects a default `IdGenerator`. Centralising the implementation removes the duplicate `generateId()` that lived in both `tracker.ts` and `session.ts` upstream and guarantees that anonymous IDs, event IDs, and session IDs share a single entropy source. The output is a 32-character hex string drawn from `crypto.getRandomValues`, suitable for use as a public identifier without leaking host state.
+
+## Features
+
+- Single source of randomness — `globalThis.crypto.getRandomValues` directly, no Math.random fallback.
+- Pure synchronous return; no `Promise` overhead on the hot path.
+- Hex-encoded so the ID is URL-safe, log-safe, and 1:1 with the byte length (16 bytes → 32 chars).
+- Re-exported through `src/internal/id/index.ts` so the rest of the package never imports from a flat module.
+
+## Usage: Basic
+
+```ts
+import { generateId } from "@suaveplan/analytics-browser/tracker";
+// ↑ generateId is internal; in tests / docs import from the barrel that
+// happens to re-export it. Production code typically lets the tracker
+// default-construct its own IDs.
+
+const anonymousId = generateId();
+```
+
+## Usage: Advanced
+
+```ts
+import type { IdGenerator } from "@suaveplan/types";
+import { generateId } from "./internal/id/id.js";
+
+// Wrap the function-shape IdGenerator from @suaveplan/types around the
+// shared implementation — useful when a downstream consumer wants to
+// inject a deterministic counter in tests.
+const realIds: IdGenerator = generateId;
+const fakeIds: IdGenerator = (() => {
+    let n = 0;
+    return () => `evt-${(++n).toString().padStart(32, "0")}`;
+})();
+```
+
+## API Reference
+
+- `generateId(): string` — returns a fresh 32-character lowercase hex string. Throws synchronously only if `globalThis.crypto.getRandomValues` is missing or throws (e.g. when the host crypto API is intentionally disabled).
+
+## Implementation Notes
+
+The 16-byte entropy budget gives 128 bits — the same size as a UUIDv4 — without the dash separators or version nibbles. Hex encoding is the simplest reversible representation and is cheap (~16 string concatenations) compared with base32 or base64. The byte length lives in `constants/index.ts` so a future opt-in to 24-byte IDs is a one-line constant change rather than a refactor across call sites.