Tag every event with a random per-installation ID (0.4.0)

[dmccoystephenson]

Ports trace-client-java 0.5.0's per-installation ID to the JS/TS client, so the trace server can count distinct installations rather than raw events. Version bumped 0.3.0 → 0.4.0 (minor; API-compatible — nothing changes unless a new option is passed).

What changes

• New constructor options:
  • installId — an ID the program stores itself. Trimmed; null/undefined/blank means none; over 255 characters throws, the same way an overlong version does.
  • installIdFile — a path the program chooses. Read, or created with a random UUID, via TraceClient.installIdFromFile(path). installId wins over it.
• TraceClient.installIdFromFile(path) (static): the first line matching [A-Za-z0-9_.-]{1,255} (trimmed) is the ID; a missing file, or one with no such line, gets a fresh crypto.randomUUID() written to it (parent directories created). A file that exists but cannot be read (e.g. a directory), any write failure, a blank path, or a runtime without node:fs yields an in-memory UUID; it never throws. There is no default location.
• trace.installId getter: the ID in use, null when disabled or none configured.
• Every event carries the tag install (applied after version); an event's own install tag wins, and it is not added once an event already has 32 tags (TraceClient.MAX_TAGS). Also exposed: TraceClient.INSTALL_TAG.
• Resolved only after the existing opt-outs (TRACE_USAGE_REPORTING, DO_NOT_TRACK, enabled: false, no key): a disabled client never reads, generates or writes an ID.

Edge runtimes

No top-level node:fs import was added. The file is reached through process.getBuiltinModule("node:fs") (Node 22.3+) at call time, and only when installIdFile is used; where that is missing (Next.js Edge, Workers, older Node) the ID is kept in memory. npm run typecheck still passes against ES2022 + DOM with no @types/node, and the module's exported values are unchanged (the new API hangs off TraceClient).

Docs and tests

• README: new section "Every event carries a random installation ID" (what is sent, where it lives, how to reset, opt-outs stop it, explicit-ID example), options table and wire-format note updated. CHANGELOG entry for 0.4.0.
• 9 new tests mirroring the Java suite: persist once + reuse (with nested parent dirs), first-valid-line parsing, unreadable/unwritable path → in-memory without throwing, disabled (all four opt-outs) → nothing written and installId null, no ID configured → no tag, explicit ID wins/blank = none/overlong throws, event install tag override, 32-tag cap, no getBuiltinModule → in-memory.
• Local: npm ci && npm run typecheck && npm test — 53 tests, 53 passing (Node 22).

Not tagged or released; consumers are not touched.

🤖 Generated with Claude Code

https://claude.ai/code/session_014ztkfamsbEqQfcu76me5SL

---

drafted by Claude on behalf of Daniel Stephenson