trace-client 0.2.0: environment opt-outs and disabledReason

[dmccoystephenson]

trace-client-js is brought level with trace-client-java and trace-client-python 0.2.0: the constructor now honours TRACE_USAGE_REPORTING=off|false|0|no and DO_NOT_TRACK=1|true|yes before enabled and the key, and the reason a client sends nothing is exposed as disabledReason ("environment", "config", "no key"; null when on). Until now every JavaScript consumer had to re-implement that check in its own wrapper. The file stays one file with zero dependencies, and it stays API-compatible with 0.1.0: its exported values are exactly the same four (TRACE_CLIENT_VERSION, TraceClient, pagePath, isBot) because everything new is a static member of TraceClient, so the Next.js sites' wrappers and dpc-mcp-server's CommonJS derivation (which checks that export list) need no change on re-vendor.

• trace-client.ts
  • The environment is process.env when the runtime has one, read by the two literal names (so Next.js can inline them for the Edge runtime) inside a guard: no process, or a process.env that throws, opts nothing out and never fails. process is declared locally, so the file still type-checks against ES2022 + DOM with no @types/node, and also alongside @types/node in a consumer project.
  • New env option replaces process.env (Workers-style runtimes, tests).
  • New disabledReason getter, fixed at construction (close() turns enabled off but keeps the reason); TraceClient.REASON_ENVIRONMENT / REASON_CONFIG / REASON_NO_KEY, ENV_TRACE_USAGE_REPORTING / ENV_DO_NOT_TRACK, and TraceClient.environmentOptsOut(env?).
  • Header, TRACE_CLIENT_VERSION and the User-Agent bumped to 0.2.0.
• tests/trace-client.test.ts: the documented values and near-misses, precedence (environment, then enabled, then key), default process.env reading, env replacing process.env, a runtime with no process and one whose env throws, a hostile env, the unchanged export list and 0.1.0 call shapes. The developer's own opt-out variables are cleared for the file so the delivery tests are not silently turned into no-ops.
• README.md, CHANGELOG.md, package.json / package-lock.json: a "Turning it off from the environment" section, the 0.2.0 entry, version 0.2.0.

Verification: npm run typecheck and npm test (32 tests) pass locally on Node 22.23. The new file was also type-checked with @types/node@22 present, re-derived through dpc-mcp-server's tools/vendor-trace-client.js --from (derivation accepted; its npm test 75/75 with 0.2.0), and dropped into danielstephenson-dot-dev's utils/trace-client.ts (its four usage-reporting vitest files 30/30 and tsc --noEmit clean). Those consumer checks were run in scratch clones only; nothing was pushed to them. Merging and tagging 0.2.0 are left to the coordinator.

🤖 Generated with Claude Code

---

drafted by Claude on behalf of Daniel Stephenson