trace-client 0.3.0: every event carries the program's version

[dmccoystephenson]

Summary

Every event the client sends now carries the program's own version as the tag version, mirroring Stephenson-Software/trace-client-java#5 (Java 0.4.0). Breaking change, so the client is bumped to 0.3.0.

• TraceClientOptions.version: string is required (typed non-optional). It is trimmed; missing, blank, or longer than 255 characters after trimming (TraceClient.MAX_VERSION_LENGTH) throws an Error.
• Every event (startup, page-view, command, anything) is sent with tags.version = that version. An event's own version tag wins. The caller's tags object is copied, never modified. A null/undefined event version is dropped as before, so the program's version fills it (same as the Java client's withVersion).
• TraceClient.disabled() still takes no arguments; it uses the internal placeholder version "disabled".
• The User-Agent is unchanged in shape and still carries the client's version: trace-client-js/0.3.0 (<application>).
• There are no other default tags in this client, so precedence is simply event tags > program version.
• Version bumped in TRACE_CLIENT_VERSION, the file header, package.json, package-lock.json, README and CHANGELOG. Top-level exports are unchanged.

Consumer call:

const trace = new TraceClient("https://trace.danielstephenson.dev", "my-site", {
  version: "1.4.0",
  key: process.env.USAGE_REPORTING_KEY,
  enabled: process.env.USAGE_REPORTING_ENABLED !== "false",
});

Docs

README example passes version; a new "Every event carries the program's version" section covers the requirement, the tag on every event, the event's own tag winning, and upgrading from 0.2.0 (add version; hand-added version tags may be dropped). The wire-format example now shows version in tags. CHANGELOG has a 0.3.0 entry.

Testing

• npm run typecheck: clean. Additionally checked that new TraceClient(url, app) and { key } without version fail to compile.
• npm test: 44/44 pass. Existing tests were moved to the new signature and expected bodies; new tests cover the trimmed version on every event, an event's own version winning, the caller's tags object (plain and frozen) not being mutated, and missing/blank/non-string/overlong versions being rejected (255 after trimming accepted).
• Mutation probe: with the version injection removed, 5 tests fail (39/44); with withVersion mutating the caller's object in place, 2 tests fail (42/44). Both restored; 44/44 again.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AuTszT2gqv7nLVYrtKD4ji

---

drafted by Claude on behalf of Daniel Stephenson