Telemetry contracts

Validate telemetry batches, event unions, replay manifests, and trace context with published schemas.

@askdepth/contractsv0.2.0

On this page

@askdepth/contracts exports TypeScript types and Zod 3 schemas for browser telemetry, replay metadata, and trace context. Audience Connector requests use the separate Audience contract package.

$ npm install @askdepth/contracts

Construct a valid batch

import {
  createTelemetryEnvelope,
  parseTelemetryEnvelope,
  type TelemetryEnvelope,
} from '@askdepth/contracts';

const envelope: TelemetryEnvelope = createTelemetryEnvelope({
  sdk_name: '@askdepth/core',
  sdk_version: '0.3.0',
  environment: 'production',
  session_id: crypto.randomUUID(),
  batch_id: crypto.randomUUID(),
  sent_at: new Date().toISOString(),
  events: [{
    event_id: crypto.randomUUID(),
    timestamp: new Date().toISOString(),
    type: 'track',
    name: 'report_opened',
    properties: { source: 'dashboard' },
  }],
});

const validated = parseTelemetryEnvelope(JSON.parse(JSON.stringify(envelope)));

createTelemetryEnvelope supplies the current protocol_version and validates the result. It does not create missing session, batch, event IDs, or timestamps. Wire keys are snake_case; projectId, sessionId, and sampled are not substitutes for these fields.

Envelope fields

Field	Validation
`protocol_version`	Literal `'0.1.0'`.
`sdk_name`	Nonempty string.
`sdk_version`	SemVer-shaped string.
`environment`	`'production'`, `'staging'`, or `'development'`.
`session_id`, `batch_id`	UUID strings.
`sent_at`	ISO datetime, with timezone offsets allowed.
`events`	Array of event envelopes.

Every event requires event_id as a UUID and may include an ISO timestamp. The body does not authorize a project; ingestion uses the write-key header.

TelemetryEnvelopeSchema.parse and parseTelemetryEnvelope throw on invalid input. Use .safeParse or isTelemetryEnvelope(input) when validation failures are expected. TelemetryEnvelopeHeaderSchema and TelemetryEnvelopeHeader describe the envelope without events.

Event schemas

TelemetryEventSchema is a union of anomalies, track, and identify. AnomalyEventSchema contains the three frustration types.

Export	Discriminator and notable fields
`RageClickEventSchema`	`RAGE_CLICK`; target, at least three coordinate records, click count, tag, optional component.
`DeadClickEventSchema`	`DEAD_CLICK`; target, computed styles, duration exactly `800`, interactive flag.
`ErrorClickEventSchema`	`ERROR_CLICK`; `js_exception` or `network_error` details with different bounds.
`TrackEventSchema`	`track`; nonempty name up to 200 characters and optional properties.
`IdentifyEventSchema`	`identify`; nonempty `user_id` up to 200 characters and optional traits.

CustomPropertiesSchema validates the bounds documented under events and identity. Validation does not apply core's sensitive-key filtering or guarantee that an object contains no personal data. Schema validity is separate from collection policy.

Replay schemas

RRWebEventSchema describes { type: integer, data: unknown, timestamp: number }. It does not fully validate every rrweb event's internal data.

ReplaySliceManifestSchema includes slice/anomaly/session identifiers, environment, timestamps, duration from 0 to 45,000 ms, baseline presence, event/byte counts, compression algorithm, and optional positive sequence number.

ReplayUploadPayloadSchema describes { manifest, payload, part_index, total_parts }, where payload is a nonempty string or Uint8Array. This is an engine-level model. The shipped replay uploader transmits binary chunks and identifying headers, not this entire object as JSON. See Replay API.

Last reviewed October 12, 2026SDK issue?