Validate a telemetry envelope

FaultAtlas protocol contracts let you validate an envelope before transport. The parser strips unknown top-level fields and redacts sensitive strings.

Parse a versioned envelope

Negotiate the supported version before parsing data from an untrusted boundary. Version 1 accepts peers within one supported version and selects the lower version.

import {
  envelopeSchema,
  negotiateVersion,
  parseEnvelope,
} from "@faultatlas/protocol";

const version = negotiateVersion(1, 1);
if (version.status !== "accepted") throw new Error(version.reason);

const envelope = parseEnvelope({
  version: version.negotiatedVersion,
  projectKey: "project_demo",
  occurredAt: "2026-08-10T12:00:00.000Z",
  kind: "error",
  message: "Contact dev@example.com",
});

envelopeSchema.parse(envelope);

The returned envelope masks known email, phone, token, and cookie values. It also redacts unknown records in context and breadcrumb data.

Envelope lifecycle

1. Negotiate a compatible version.
2. Parse and normalize untrusted input.
3. Redact sensitive strings and discard unknown top-level fields.
4. Buffer or transport only the returned envelope.
5. Handle the explicit acknowledgement or rejection outcome.

Do not send the original input after parsing. The normalized return value is the privacy boundary used by every FaultAtlas producer.

Return a transport outcome

Use ackEnvelope for accepted payloads and rejectEnvelope for terminal validation failures. parseBatch returns per-batch validation without binding the contract to HTTP or another transport.

Limits and failures

The contract bounds messages, contexts, breadcrumbs, network entries, stacks, and batches. Invalid or oversized input is rejected with a stable reason; transport code can decide whether to retry without guessing from an exception string.

For a failed parse, keep the reason and correlation metadata only. Do not log the rejected body because it is still untrusted and may contain credentials or personal data.

See browser capture when you need a producer for these envelopes.