Versions and trace context

Package and protocol versions

Package releases and wire contracts are separate version axes. The artifacts inspected for this documentation have these versions:

Do not send an npm version as a protocol header. Core attaches its SDK name/version separately from x-askdepth-protocol-version. Keep your installed packages and collector's accepted wire version compatible.

import { PROTOCOL_VERSION } from '@askdepth/contracts/protocol-version';
import { SDK_NAME, SDK_VERSION } from '@askdepth/core';

console.log({ protocol: PROTOCOL_VERSION, name: SDK_NAME, version: SDK_VERSION });

The protocol-only subpath avoids importing the full runtime schema module. Package exports define supported entry points; do not import internal dist paths.

Format and parse traceparent

import {
  formatTraceparent,
  parseTraceparent,
  TraceparentHeaderSchema,
} from '@askdepth/contracts';

const header = formatTraceparent({
  version: '00',
  traceId: '4bf92f3577b34da6a3ce929d0e0e4736',
  parentId: '00f067aa0ba902b7',
  flags: '01',
});

const parts = parseTraceparent(header);
const result = TraceparentHeaderSchema.safeParse(header);

The current schema accepts version 00, a 32-character lowercase hexadecimal trace ID, a 16-character lowercase hexadecimal parent ID, and two lowercase hexadecimal flag characters. Trace and parent IDs must not be all zeros. There is no sampled boolean property; use flags.

parseTraceparent returns { version, traceId, parentId, flags }. It throws for unsupported or malformed input. formatTraceparent validates both the parts and resulting header. The exported pattern alone checks the header's shape; the schema also rejects zero IDs.

The package handles this supported trace-context format rather than all possible future W3C versions. For automatic propagation, read distributed tracing.

Upgrading

Review the package exports and generated types for the version you install, then exercise a batch and a replay upload against your collector. Published packages are immutable; source changes and README examples are not proof that an installed artifact contains a given API.

Audience signing and capability negotiation belong to the independent Audience Connector contract. Do not interchange its version, signature headers, or secrets with browser telemetry protocol metadata.