@primitivedotdev/sdk 1.26.0 → 1.27.0

package/dist/webhook-B72YFapb.js

@@ -0,0 +1,2132 @@
+import { F as WebhookPayloadError, L as WebhookVerificationError, N as RawEmailDecodeError, _ as parseWebhookEvent, h as normalizeReceivedEmail, k as validateEmailReceivedEvent } from "./trust-DBOnyTHV.js";
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+//#region src/webhook/download-tokens.ts
+/**
+* Signed download tokens.
+*
+* A download token is a self-describing bearer credential for fetching a
+* specific email's raw bytes or attachment bundle from a per-deployment
+* download endpoint. It binds:
+*
+* - `email_id`: the specific email the token authorizes.
+* - `aud`: a caller-chosen audience label (e.g. the resource kind being
+*   downloaded). Tokens minted for one audience will not verify under another.
+* - `exp`: an absolute expiration time (unix seconds).
+*
+* Format: `<base64url(payload)>.<base64url(signature)>` where `signature`
+* is HMAC-SHA256 over the base64url-encoded payload using the shared secret.
+*
+* The audience is an opaque caller-chosen string. Both the issuer and the
+* verifier must agree on the exact bytes; the SDK does not prescribe a
+* convention. New integrations are encouraged to namespace audiences
+* (e.g. `primitive:raw-download`).
+*
+* Tokens are stateless: verification needs only the shared secret. Keep
+* expirations as short as operationally tolerable.
+*/
+const BASE64URL_PATTERN = /^[A-Za-z0-9_-]+$/;
+/**
+* Issue a signed download token.
+*
+* The resulting token is `<base64url-payload>.<base64url-signature>`, where
+* the payload is `{"email_id":"...","exp":...,"aud":"..."}` (snake_case,
+* field order fixed) and the signature is HMAC-SHA256 of the base64url
+* payload string using `secret`.
+*
+* @param params - Token inputs.
+* @returns The signed token string.
+*/
+function generateDownloadToken(params) {
+	const { emailId, expiresAt, audience, secret } = params;
+	const payloadJson = JSON.stringify({
+		email_id: emailId,
+		exp: expiresAt,
+		aud: audience
+	});
+	const payloadStr = Buffer.from(payloadJson, "utf8").toString("base64url");
+	return `${payloadStr}.${createHmac("sha256", secret).update(payloadStr).digest("base64url")}`;
+}
+/**
+* Verify a signed download token.
+*
+* Returns a discriminated-union result. The function never throws for
+* verification failures. Only malformed inputs at the crypto layer would
+* surface. Callers should check `result.valid` and log `result.error`.
+*
+* @param params - Verification inputs.
+* @returns Whether the token is valid, plus a reason on failure.
+*/
+function verifyDownloadToken(params) {
+	const { token, emailId, audience, secret, nowSeconds } = params;
+	if (typeof token !== "string" || token.length === 0) return {
+		valid: false,
+		error: "Token is empty"
+	};
+	const firstDot = token.indexOf(".");
+	const lastDot = token.lastIndexOf(".");
+	if (firstDot === -1 || firstDot !== lastDot) return {
+		valid: false,
+		error: "Token is malformed: expected one '.'"
+	};
+	const payloadStr = token.slice(0, firstDot);
+	const providedSignature = token.slice(firstDot + 1);
+	if (payloadStr.length === 0 || providedSignature.length === 0) return {
+		valid: false,
+		error: "Token is malformed: empty part"
+	};
+	const expectedSignature = createHmac("sha256", secret).update(payloadStr).digest("base64url");
+	const providedBytes = Buffer.from(providedSignature, "base64url");
+	const expectedBytes = Buffer.from(expectedSignature, "base64url");
+	if (providedBytes.length !== expectedBytes.length || !timingSafeEqual(providedBytes, expectedBytes)) return {
+		valid: false,
+		error: "Invalid signature"
+	};
+	if (!BASE64URL_PATTERN.test(payloadStr)) return {
+		valid: false,
+		error: "Token payload is not valid base64url"
+	};
+	const decodedJson = Buffer.from(payloadStr, "base64url").toString("utf8");
+	let payload;
+	try {
+		payload = JSON.parse(decodedJson);
+	} catch {
+		return {
+			valid: false,
+			error: "Token payload is not valid JSON"
+		};
+	}
+	if (!payload || typeof payload !== "object" || Array.isArray(payload) || typeof payload.email_id !== "string" || typeof payload.aud !== "string" || typeof payload.exp !== "number") return {
+		valid: false,
+		error: "Token payload has wrong shape"
+	};
+	const { email_id, aud, exp } = payload;
+	if (aud !== audience) return {
+		valid: false,
+		error: "Audience mismatch"
+	};
+	if (email_id !== emailId) return {
+		valid: false,
+		error: "Email ID mismatch"
+	};
+	if (exp <= (nowSeconds ?? Math.floor(Date.now() / 1e3))) return {
+		valid: false,
+		error: "Token is expired"
+	};
+	return { valid: true };
+}
+//#endregion
+//#region src/webhook/encoding.ts
+/**
+* Buffer encoding utilities
+*/
+const utf8Decoder = new TextDecoder("utf-8", { fatal: true });
+/**
+* Convert a Buffer to string with strict UTF-8 validation.
+* Throws if the buffer contains invalid UTF-8 sequences.
+*
+* Uses TextDecoder with `fatal: true` for robust validation that catches
+* all invalid UTF-8 sequences, not just those that produce replacement characters.
+*
+* @param buffer - The buffer to convert
+* @param label - Label for error messages (e.g., "request body")
+* @returns The UTF-8 decoded string
+* @throws WebhookPayloadError if the buffer contains invalid UTF-8
+*/
+function bufferToString(buffer, label) {
+	try {
+		return utf8Decoder.decode(buffer);
+	} catch (err) {
+		throw new WebhookPayloadError("INVALID_ENCODING", `${label} contains invalid UTF-8 bytes`, `Ensure the ${label} is valid UTF-8 encoded text. If the data is binary, it should be base64 encoded first.`, err instanceof Error ? err : void 0);
+	}
+}
+//#endregion
+//#region src/webhook/signing.ts
+/**
+* Webhook HMAC Signing (Stripe-style format)
+*
+* Implements HMAC-SHA256 signature for webhook security with timestamp validation.
+* Prevents replay attacks by including timestamp in signature.
+*
+* Header format:
+*   Primitive-Signature: t=<unix_seconds>,v1=<hex_hmac_sha256>
+*
+* Signed payload format: "{timestamp}.{raw_body}"
+*
+* This format matches Stripe's webhook signature scheme, which is widely understood
+* and easy to implement in any language with ~15 lines of code.
+*/
+/**
+* WeakMap cache for computed signatures.
+* Only works for Buffer bodies (strings cannot be WeakMap keys).
+* Automatically garbage collected when Buffer is no longer referenced.
+*/
+const signatureCache = /* @__PURE__ */ new WeakMap();
+/**
+* Hash a secret for cache key comparison.
+* @internal
+*/
+function hashSecret(secret) {
+	return createHash("sha256").update(secret).digest("hex");
+}
+/** Header name for incoming webhook signature */
+const PRIMITIVE_SIGNATURE_HEADER = "Primitive-Signature";
+/** Legacy header name kept for backward compatibility with older servers */
+const LEGACY_SIGNATURE_HEADER = "MyMX-Signature";
+/** Header name to confirm webhook was processed (prevents retries) */
+const PRIMITIVE_CONFIRMED_HEADER = "X-Primitive-Confirmed";
+/** Legacy confirmed header name kept for backward compatibility */
+const LEGACY_CONFIRMED_HEADER = "X-MyMX-Confirmed";
+/** Default max age for webhook requests (5 minutes) */
+const DEFAULT_TOLERANCE_SECONDS$1 = 300;
+/** Future clock skew tolerance (1 minute) */
+const FUTURE_TOLERANCE_SECONDS$1 = 60;
+/** Valid hex pattern for signature verification */
+const HEX_PATTERN = /^[0-9a-f]+$/i;
+/** Strict unix-seconds pattern for the timestamp component */
+const UNIX_SECONDS_PATTERN = /^\d+$/;
+/**
+* Sign a webhook payload using HMAC-SHA256.
+*
+* Useful for:
+* - Internal testing and dogfooding
+* - Generating test vectors
+* - Integration tests
+*
+* @param rawBody - The raw JSON body string to sign
+* @param secret - The webhook secret key
+* @param timestamp - Unix timestamp in seconds (defaults to current time)
+*/
+function signWebhookPayload(rawBody, secret, timestamp) {
+	const ts = timestamp ?? Math.floor(Date.now() / 1e3);
+	const signedPayloadString = `${ts}.${typeof rawBody === "string" ? rawBody : bufferToString(rawBody, "rawBody")}`;
+	const hmac = createHmac("sha256", secret);
+	hmac.update(signedPayloadString);
+	const v1 = hmac.digest("hex");
+	return {
+		header: `t=${ts},v1=${v1}`,
+		timestamp: ts,
+		v1
+	};
+}
+/**
+* Parse the Primitive-Signature header into its components.
+* Tolerant of whitespace around keys/values.
+*
+* @internal
+*/
+function parseSignatureHeader(signatureHeader) {
+	if (!signatureHeader || typeof signatureHeader !== "string") return null;
+	const parts = signatureHeader.split(",");
+	let timestamp = null;
+	const signatures = [];
+	for (const part of parts) {
+		const idx = part.indexOf("=");
+		if (idx === -1) continue;
+		const key = part.slice(0, idx).trim();
+		const value = part.slice(idx + 1).trim();
+		if (!key || !value) continue;
+		if (key === "t") {
+			if (!UNIX_SECONDS_PATTERN.test(value)) continue;
+			const parsed = Number(value);
+			if (Number.isSafeInteger(parsed)) timestamp = parsed;
+		} else if (key === "v1") signatures.push(value);
+	}
+	if (timestamp === null || signatures.length === 0) return null;
+	return {
+		timestamp,
+		signatures
+	};
+}
+/**
+* Check if a string is valid lowercase hex of expected length
+*/
+function isValidHex(str, expectedLength) {
+	return str.length === expectedLength && HEX_PATTERN.test(str);
+}
+/**
+* Verify a webhook signature.
+*
+* Throws `WebhookVerificationError` on failure with a specific error code.
+*
+* @example
+* ```typescript
+* import { verifyWebhookSignature, WebhookVerificationError } from '@primitivedotdev/sdk';
+*
+* try {
+*   const signatureHeader = req.headers['primitive-signature'];
+*   if (typeof signatureHeader !== 'string') {
+*     throw new Error('Missing Primitive-Signature header');
+*   }
+*   verifyWebhookSignature({
+*     rawBody: req.body, // raw string, NOT parsed JSON
+*     signatureHeader,
+*     secret: process.env.PRIMITIVE_WEBHOOK_SECRET!,
+*   });
+*   // Signature is valid, process the webhook
+* } catch (err) {
+*   if (err instanceof WebhookVerificationError) {
+*     console.error('Invalid webhook:', err.code, err.message);
+*   }
+*   return res.status(400).send('Invalid signature');
+* }
+* ```
+*/
+function verifyWebhookSignature(opts) {
+	const { rawBody, signatureHeader, secret, toleranceSeconds = DEFAULT_TOLERANCE_SECONDS$1, nowSeconds } = opts;
+	if (!secret || typeof secret === "string" && secret.length === 0 || Buffer.isBuffer(secret) && secret.length === 0) throw new WebhookVerificationError("MISSING_SECRET", "Webhook secret is required but was empty or not provided");
+	const parsed = parseSignatureHeader(signatureHeader);
+	if (!parsed) throw new WebhookVerificationError("INVALID_SIGNATURE_HEADER", "Invalid Primitive-Signature header format. Expected: t={timestamp},v1={signature}");
+	const { timestamp, signatures } = parsed;
+	const age = (nowSeconds ?? Math.floor(Date.now() / 1e3)) - timestamp;
+	if (age > toleranceSeconds) throw new WebhookVerificationError("TIMESTAMP_OUT_OF_RANGE", `Webhook timestamp too old (${age}s). Max age is ${toleranceSeconds}s.`);
+	if (age < -FUTURE_TOLERANCE_SECONDS$1) throw new WebhookVerificationError("TIMESTAMP_OUT_OF_RANGE", "Webhook timestamp is too far in the future. Check server clock sync.");
+	const body = typeof rawBody === "string" ? rawBody : bufferToString(rawBody, "request body");
+	let expectedHex;
+	if (Buffer.isBuffer(rawBody)) {
+		const cached = signatureCache.get(rawBody);
+		const currentSecretHash = hashSecret(secret);
+		if (cached && cached.body === body && cached.timestamp === timestamp && cached.secretHash === currentSecretHash) expectedHex = cached.computed;
+		else {
+			const signedPayloadString = `${timestamp}.${body}`;
+			const hmac = createHmac("sha256", secret);
+			hmac.update(signedPayloadString);
+			expectedHex = hmac.digest("hex");
+			signatureCache.set(rawBody, {
+				secretHash: currentSecretHash,
+				timestamp,
+				body,
+				computed: expectedHex
+			});
+		}
+	} else {
+		const signedPayloadString = `${timestamp}.${body}`;
+		const hmac = createHmac("sha256", secret);
+		hmac.update(signedPayloadString);
+		expectedHex = hmac.digest("hex");
+	}
+	for (const receivedHex of signatures) {
+		if (!isValidHex(receivedHex, 64)) continue;
+		if (timingSafeEqual(Buffer.from(receivedHex, "hex"), Buffer.from(expectedHex, "hex"))) return true;
+	}
+	const reserializationHint = detectReserializedBody(body);
+	throw new WebhookVerificationError("SIGNATURE_MISMATCH", reserializationHint ? `No valid signature found. ${reserializationHint}` : "No valid signature found. Verify the webhook secret matches and you're using the raw request body (not re-serialized JSON).");
+}
+/**
+* Detect if a body looks like it was re-serialized by a framework.
+* Returns a helpful message if detected, null otherwise.
+* @internal
+*/
+function detectReserializedBody(body) {
+	if (/^\s*\{[\s\S]*\n\s{2,}/.test(body)) return "Request body appears re-serialized (pretty-printed). Use the raw request body before any JSON.parse() or JSON.stringify() calls.";
+	return null;
+}
+//#endregion
+//#region src/webhook/standard-webhooks.ts
+/**
+* Standard Webhooks Verification & Signing
+*
+* Implements the Standard Webhooks spec (standardwebhooks.com) for webhook
+* signature verification and payload signing.
+*
+* Header format:
+*   webhook-id: <msg_id>
+*   webhook-timestamp: <unix_seconds>
+*   webhook-signature: v1,<base64_hmac_sha256> [v1,<base64_2> ...]
+*
+* Signed payload format: "{msg_id}.{timestamp}.{raw_body}"
+*
+* Secrets are base64-encoded, optionally prefixed with "whsec_".
+*/
+const WHSEC_PREFIX = "whsec_";
+const BASE64_PATTERN$1 = /^[A-Za-z0-9+/]*={0,2}$/;
+/** Default max age for webhook requests (5 minutes) */
+const DEFAULT_TOLERANCE_SECONDS = 300;
+/** Future clock skew tolerance (1 minute) */
+const FUTURE_TOLERANCE_SECONDS = 60;
+/** Standard Webhooks header names */
+const STANDARD_WEBHOOK_ID_HEADER = "webhook-id";
+const STANDARD_WEBHOOK_TIMESTAMP_HEADER = "webhook-timestamp";
+const STANDARD_WEBHOOK_SIGNATURE_HEADER = "webhook-signature";
+/**
+* Prepare a Standard Webhooks secret for HMAC computation.
+*
+* Strips the "whsec_" prefix if present, then base64-decodes the remainder
+* to produce the raw HMAC key bytes.
+*
+* @internal
+*/
+function prepareStandardWebhooksSecret(secret) {
+	if (Buffer.isBuffer(secret)) {
+		if (secret.length === 0) throw new WebhookVerificationError("MISSING_SECRET", "Webhook secret is required but was empty or not provided");
+		return secret;
+	}
+	let keyStr = secret;
+	if (keyStr.startsWith(WHSEC_PREFIX)) keyStr = keyStr.slice(6);
+	if (!keyStr || !BASE64_PATTERN$1.test(keyStr)) throw new WebhookVerificationError("MISSING_SECRET", "Standard Webhooks secret must be base64-encoded (optionally with whsec_ prefix)");
+	const decoded = Buffer.from(keyStr, "base64");
+	if (decoded.length === 0) throw new WebhookVerificationError("MISSING_SECRET", "Webhook secret is required but was empty or not provided");
+	return decoded;
+}
+/**
+* Parse the webhook-signature header into base64 signature strings.
+*
+* The header format is space-delimited entries like "v1,<base64>".
+* Only v1 entries are returned.
+*
+* @internal
+*/
+function parseStandardWebhooksSignatures(header) {
+	if (!header) return [];
+	const signatures = [];
+	for (const entry of header.split(" ")) {
+		const trimmed = entry.trim();
+		if (!trimmed) continue;
+		const commaIdx = trimmed.indexOf(",");
+		if (commaIdx === -1) continue;
+		const version = trimmed.slice(0, commaIdx);
+		const sig = trimmed.slice(commaIdx + 1);
+		if (version === "v1" && sig) signatures.push(sig);
+	}
+	return signatures;
+}
+/**
+* Sign a webhook payload using the Standard Webhooks format.
+*
+* @param rawBody - The raw JSON body string to sign
+* @param secret - The webhook secret (with or without whsec_ prefix)
+* @param msgId - The message ID (used in webhook-id header)
+* @param timestamp - Unix timestamp in seconds (defaults to current time)
+*/
+function signStandardWebhooksPayload(rawBody, secret, msgId, timestamp) {
+	const ts = timestamp ?? Math.floor(Date.now() / 1e3);
+	const body = typeof rawBody === "string" ? rawBody : bufferToString(rawBody, "rawBody");
+	const key = prepareStandardWebhooksSecret(secret);
+	if (key.length === 0) throw new WebhookVerificationError("MISSING_SECRET", "Webhook secret is required but was empty or not provided");
+	const signedPayload = `${msgId}.${ts}.${body}`;
+	return {
+		signature: `v1,${createHmac("sha256", key).update(signedPayload).digest("base64")}`,
+		msgId,
+		timestamp: ts
+	};
+}
+/**
+* Verify a Standard Webhooks signature.
+*
+* Throws `WebhookVerificationError` on failure with a specific error code.
+*/
+function verifyStandardWebhooksSignature(opts) {
+	const { rawBody, msgId, timestamp: timestampStr, signatureHeader, secret, toleranceSeconds = DEFAULT_TOLERANCE_SECONDS, nowSeconds } = opts;
+	const key = prepareStandardWebhooksSecret(secret);
+	if (key.length === 0) throw new WebhookVerificationError("MISSING_SECRET", "Webhook secret is required but was empty or not provided");
+	if (!timestampStr || !/^\d+$/.test(timestampStr)) throw new WebhookVerificationError("INVALID_SIGNATURE_HEADER", `Invalid webhook-timestamp header: "${timestampStr}". Expected a unix timestamp in seconds`);
+	const timestamp = Number(timestampStr);
+	if (!Number.isInteger(timestamp) || timestamp < 0) throw new WebhookVerificationError("INVALID_SIGNATURE_HEADER", `Invalid webhook-timestamp header: "${timestampStr}". Expected a unix timestamp in seconds`);
+	const age = (nowSeconds ?? Math.floor(Date.now() / 1e3)) - timestamp;
+	if (age > toleranceSeconds) throw new WebhookVerificationError("TIMESTAMP_OUT_OF_RANGE", `Webhook timestamp too old (${age}s). Max age is ${toleranceSeconds}s.`);
+	if (age < -FUTURE_TOLERANCE_SECONDS) throw new WebhookVerificationError("TIMESTAMP_OUT_OF_RANGE", "Webhook timestamp is too far in the future. Check server clock sync.");
+	const signedPayload = `${msgId}.${timestamp}.${typeof rawBody === "string" ? rawBody : bufferToString(rawBody, "request body")}`;
+	const expectedSig = createHmac("sha256", key).update(signedPayload).digest("base64");
+	const signatures = parseStandardWebhooksSignatures(signatureHeader);
+	if (signatures.length === 0) throw new WebhookVerificationError("INVALID_SIGNATURE_HEADER", "Invalid webhook-signature header format. Expected: \"v1,<base64>\"");
+	const expectedBytes = Buffer.from(expectedSig, "base64");
+	for (const sig of signatures) {
+		if (!BASE64_PATTERN$1.test(sig)) continue;
+		const sigBytes = Buffer.from(sig, "base64");
+		if (sigBytes.length === expectedBytes.length && timingSafeEqual(sigBytes, expectedBytes)) return true;
+	}
+	throw new WebhookVerificationError("SIGNATURE_MISMATCH", "No valid signature found. Verify the webhook secret matches and you're using the raw request body (not re-serialized JSON).");
+}
+//#endregion
+//#region src/schema.generated.ts
+const emailReceivedEventJsonSchema = {
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"$ref": "#/definitions/EmailReceivedEvent",
+	"definitions": {
+		"EmailReceivedEvent": {
+			"type": "object",
+			"properties": {
+				"id": {
+					"type": "string",
+					"pattern": "^evt_[a-f0-9]{64}$",
+					"description": "Unique delivery event ID.\n\nThis ID is stable across retries to the same endpoint - use it as your idempotency/dedupe key. Note that the same email delivered to different endpoints will have different event IDs.\n\nFormat: `evt_` prefix followed by a SHA-256 hash (64 hex characters). Example: `evt_a1b2c3d4e5f6...` (68 characters total)"
+				},
+				"event": {
+					"type": "string",
+					"enum": [
+						"email.received",
+						"email.bounced",
+						"email.tls_report",
+						"email.dmarc_report",
+						"email.dmarc_failure"
+					],
+					"description": "Event type identifier.\n\n- `email.received` - A normal inbound email.\n- `email.bounced` - A delivery status notification (DSN) reporting that a message delivery failed. Carries `email.analysis.bounce`.\n- `email.tls_report` - An SMTP TLS report (RFC 8460). Carries `email.analysis.tls_report`.\n- `email.dmarc_report` - A DMARC aggregate report (RFC 7489). Carries `email.analysis.dmarc_report`.\n- `email.dmarc_failure` - A DMARC failure (forensic) report.\n\nMachine-generated mail (bounces and the report types above) is delivered under its own event type rather than `email.received`, so an endpoint subscribed only to `email.received` receives just normal inbound mail. The payload shape is otherwise identical across event types; the type-specific details live under `email.analysis`."
+				},
+				"version": {
+					"$ref": "#/definitions/WebhookVersion",
+					"description": "API version in date format (YYYY-MM-DD). Use this to detect version mismatches between webhook and SDK."
+				},
+				"routing": {
+					"$ref": "#/definitions/RoutingDecision",
+					"description": "The recipient-routing decision for this email: where it was delivered and why. Present only when recipient routing ran for the organization; omitted otherwise. This is the compact decision also recorded on the email's routing metadata."
+				},
+				"delivery": {
+					"type": "object",
+					"properties": {
+						"endpoint_id": {
+							"type": "string",
+							"description": "ID of the webhook endpoint receiving this event. Matches the endpoint ID from your Primitive dashboard."
+						},
+						"attempt": {
+							"type": "integer",
+							"minimum": 1,
+							"description": "Delivery attempt number, starting at 1. Increments with each retry if previous attempts failed."
+						},
+						"attempted_at": {
+							"type": "string",
+							"format": "date-time",
+							"description": "ISO 8601 timestamp (UTC) when this delivery was attempted.",
+							"examples": ["2025-01-15T10:30:00.000Z"]
+						}
+					},
+					"required": [
+						"endpoint_id",
+						"attempt",
+						"attempted_at"
+					],
+					"description": "Metadata about this webhook delivery."
+				},
+				"email": {
+					"type": "object",
+					"properties": {
+						"id": {
+							"type": "string",
+							"description": "Unique email ID in Primitive. Use this ID when calling Primitive APIs to reference this email."
+						},
+						"thread_id": {
+							"type": ["string", "null"],
+							"description": "Conversation thread this email belongs to. Inbound and outbound messages in the same conversation share a thread_id; fetch GET /v1/threads/{thread_id} for the full thread. Null on messages received before threading was enabled."
+						},
+						"received_at": {
+							"type": "string",
+							"format": "date-time",
+							"description": "ISO 8601 timestamp (UTC) when Primitive received the email.",
+							"examples": ["2025-01-15T10:29:55.123Z"]
+						},
+						"smtp": {
+							"type": "object",
+							"properties": {
+								"helo": {
+									"type": ["string", "null"],
+									"description": "HELO/EHLO hostname from the sending server. Null if not provided during SMTP transaction."
+								},
+								"mail_from": {
+									"type": "string",
+									"description": "SMTP envelope sender (MAIL FROM command). This is the bounce address, which may differ from the From header."
+								},
+								"rcpt_to": {
+									"type": "array",
+									"items": { "type": "string" },
+									"minItems": 1,
+									"description": "SMTP envelope recipients (RCPT TO commands). All addresses that received this email in a single delivery."
+								}
+							},
+							"required": [
+								"helo",
+								"mail_from",
+								"rcpt_to"
+							],
+							"description": "SMTP envelope information. This is the \"real\" sender/recipient info from the SMTP transaction, which may differ from the headers (e.g., BCC recipients)."
+						},
+						"headers": {
+							"type": "object",
+							"properties": {
+								"message_id": {
+									"type": ["string", "null"],
+									"description": "Message-ID header value. Null if the email had no Message-ID header."
+								},
+								"subject": {
+									"type": ["string", "null"],
+									"description": "Subject header value. Null if the email had no Subject header."
+								},
+								"from": {
+									"type": "string",
+									"minLength": 1,
+									"description": "From header value. May include display name: `\"John Doe\" <john@example.com>`"
+								},
+								"to": {
+									"type": "string",
+									"minLength": 1,
+									"description": "To header value. May include multiple addresses or display names."
+								},
+								"date": {
+									"type": ["string", "null"],
+									"description": "Date header value as it appeared in the email. Null if the email had no Date header."
+								}
+							},
+							"required": [
+								"message_id",
+								"subject",
+								"from",
+								"to",
+								"date"
+							],
+							"description": "Parsed email headers. These are extracted from the email content, not the SMTP envelope."
+						},
+						"content": {
+							"type": "object",
+							"properties": {
+								"raw": {
+									"$ref": "#/definitions/RawContent",
+									"description": "Raw email in RFC 5322 format. May be inline (base64) or download-only depending on size."
+								},
+								"download": {
+									"type": "object",
+									"properties": {
+										"url": {
+											"type": "string",
+											"format": "uri",
+											"pattern": "^https?://",
+											"description": "URL to download the raw email as-is in RFC 5322 format. Managed Primitive always issues HTTPS. Self-host deployments may issue HTTP URLs that resolve inside the operator's network (e.g. `http://localhost:4001/...`). Receivers that want to refuse plaintext downloads should check the scheme explicitly."
+										},
+										"expires_at": {
+											"type": "string",
+											"format": "date-time",
+											"description": "ISO 8601 timestamp (UTC) when this URL expires. Download before this time or the URL will return 403."
+										}
+									},
+									"required": ["url", "expires_at"],
+									"description": "Download information for the raw email. Always present, even if raw content is inline."
+								}
+							},
+							"required": ["raw", "download"],
+							"description": "Raw email content and download information."
+						},
+						"parsed": {
+							"$ref": "#/definitions/ParsedData",
+							"description": "Parsed email content (body text, HTML, attachments). Check `status` to determine if parsing succeeded."
+						},
+						"analysis": {
+							"$ref": "#/definitions/EmailAnalysis",
+							"description": "Email analysis and classification results."
+						},
+						"auth": {
+							"$ref": "#/definitions/EmailAuth",
+							"description": "Email authentication results (SPF, DKIM, DMARC)."
+						}
+					},
+					"required": [
+						"id",
+						"received_at",
+						"smtp",
+						"headers",
+						"content",
+						"parsed",
+						"analysis",
+						"auth"
+					],
+					"description": "The email that triggered this event."
+				}
+			},
+			"required": [
+				"id",
+				"event",
+				"version",
+				"delivery",
+				"email"
+			],
+			"description": "Webhook payload for the `email.received` event.\n\nThis is delivered to your webhook endpoint when Primitive receives an email matching your domain configuration."
+		},
+		"RoutingDecision": {
+			"type": "object",
+			"description": "The recipient-routing decision for an inbound email: which endpoint it resolved to and why. Present on the event only when recipient routing ran for the organization.",
+			"properties": {
+				"version": {
+					"type": "integer",
+					"description": "Decision schema version, so consumers can detect shape changes."
+				},
+				"outcome": {
+					"type": "string",
+					"enum": [
+						"matched",
+						"defaulted",
+						"none"
+					],
+					"description": "How the destination was chosen: `matched` a recipient route, fell back to a `defaulted` destination (domain or org), or `none` (no destination resolved)."
+				},
+				"endpoint_id": {
+					"type": ["string", "null"],
+					"description": "The endpoint the email was delivered to, or null when no destination resolved."
+				},
+				"matched_route_id": {
+					"type": ["string", "null"],
+					"description": "The recipient route that matched, or null when the outcome was not `matched`."
+				},
+				"matched_tier": {
+					"type": ["string", "null"],
+					"enum": [
+						"exact",
+						"wildcard",
+						"regex",
+						null
+					],
+					"description": "The match tier of the route that matched, or null when the outcome was not `matched`."
+				},
+				"default_scope": {
+					"type": ["string", "null"],
+					"enum": [
+						"domain",
+						"org",
+						null
+					],
+					"description": "When the outcome was `defaulted`, whether the default came from the domain or the organization; null otherwise."
+				}
+			},
+			"required": ["outcome"]
+		},
+		"WebhookVersion": {
+			"type": "string",
+			"pattern": "^(?:(?:\\d{4}-(?:(?:01|03|05|07|08|10|12)-(?:0[1-9]|[12]\\d|3[01])|(?:04|06|09|11)-(?:0[1-9]|[12]\\d|30)|02-(?:0[1-9]|1\\d|2[0-8])))|(?:(?:[02468][048]00|[13579][26]00|\\d{2}(?:0[48]|[2468][048]|[13579][26]))-02-29))$",
+			"description": "Valid webhook version format (YYYY-MM-DD date string). The SDK accepts any valid date-formatted version, not just the current one, for forward and backward compatibility."
+		},
+		"RawContent": {
+			"anyOf": [{ "$ref": "#/definitions/RawContentInline" }, { "$ref": "#/definitions/RawContentDownloadOnly" }],
+			"description": "Raw email content - a discriminated union on `included`."
+		},
+		"RawContentInline": {
+			"type": "object",
+			"properties": {
+				"included": {
+					"type": "boolean",
+					"const": true,
+					"description": "Discriminant indicating raw content is included inline."
+				},
+				"encoding": {
+					"type": "string",
+					"const": "base64",
+					"description": "Encoding used for the data field. Always \"base64\"."
+				},
+				"max_inline_bytes": {
+					"type": "integer",
+					"minimum": 1,
+					"description": "Maximum size in bytes for inline inclusion. Emails larger than this threshold require download."
+				},
+				"size_bytes": {
+					"type": "integer",
+					"minimum": 0,
+					"description": "Actual size of the raw email in bytes."
+				},
+				"sha256": {
+					"type": "string",
+					"pattern": "^[a-fA-F0-9]{64}$",
+					"description": "SHA-256 hash of the raw email content (hex-encoded). Use this to verify integrity after base64 decoding."
+				},
+				"data": {
+					"type": "string",
+					"description": "Base64-encoded raw email (RFC 5322 format). Decode with `Buffer.from(data, 'base64')` in Node.js."
+				}
+			},
+			"required": [
+				"included",
+				"encoding",
+				"max_inline_bytes",
+				"size_bytes",
+				"sha256",
+				"data"
+			],
+			"description": "Raw email content included inline (base64 encoded).\n\nWhen the raw email is small enough (under  {@link  max_inline_bytes } ), it's included directly in the webhook payload for convenience."
+		},
+		"RawContentDownloadOnly": {
+			"type": "object",
+			"properties": {
+				"included": {
+					"type": "boolean",
+					"const": false,
+					"description": "Discriminant indicating raw content must be downloaded."
+				},
+				"reason_code": {
+					"type": "string",
+					"const": "size_exceeded",
+					"description": "Reason the content wasn't included inline."
+				},
+				"max_inline_bytes": {
+					"type": "integer",
+					"minimum": 1,
+					"description": "Maximum size in bytes for inline inclusion. The email exceeded this threshold."
+				},
+				"size_bytes": {
+					"type": "integer",
+					"minimum": 0,
+					"description": "Actual size of the raw email in bytes."
+				},
+				"sha256": {
+					"type": "string",
+					"pattern": "^[a-fA-F0-9]{64}$",
+					"description": "SHA-256 hash of the raw email content (hex-encoded). Use this to verify integrity after download."
+				}
+			},
+			"required": [
+				"included",
+				"reason_code",
+				"max_inline_bytes",
+				"size_bytes",
+				"sha256"
+			],
+			"description": "Raw email content not included (must be downloaded).\n\nWhen the raw email exceeds  {@link  max_inline_bytes } , it's not included in the webhook payload. Use the download URL from  {@link  EmailReceivedEvent.email.content.download  }  to fetch it."
+		},
+		"ParsedData": {
+			"anyOf": [{ "$ref": "#/definitions/ParsedDataComplete" }, { "$ref": "#/definitions/ParsedDataFailed" }],
+			"description": "Parsed email content - a discriminated union on `status`."
+		},
+		"ParsedDataComplete": {
+			"type": "object",
+			"properties": {
+				"status": {
+					"type": "string",
+					"const": "complete",
+					"description": "Discriminant indicating successful parsing."
+				},
+				"error": {
+					"type": "null",
+					"description": "Always null when parsing succeeds."
+				},
+				"body_text": {
+					"type": ["string", "null"],
+					"description": "Plain text body of the email. Null if the email had no text/plain part."
+				},
+				"body_html": {
+					"type": ["string", "null"],
+					"description": "HTML body of the email. Null if the email had no text/html part."
+				},
+				"reply_to": {
+					"anyOf": [{
+						"type": "array",
+						"items": { "$ref": "#/definitions/EmailAddress" }
+					}, { "type": "null" }],
+					"description": "Parsed Reply-To header addresses. Null if the email had no Reply-To header."
+				},
+				"cc": {
+					"anyOf": [{
+						"type": "array",
+						"items": { "$ref": "#/definitions/EmailAddress" }
+					}, { "type": "null" }],
+					"description": "Parsed CC header addresses. Null if the email had no CC header."
+				},
+				"bcc": {
+					"anyOf": [{
+						"type": "array",
+						"items": { "$ref": "#/definitions/EmailAddress" }
+					}, { "type": "null" }],
+					"description": "Parsed BCC header addresses. Null if the email had no BCC header. Note: BCC is only available for outgoing emails or when explicitly provided."
+				},
+				"to_addresses": {
+					"anyOf": [{
+						"type": "array",
+						"items": { "$ref": "#/definitions/EmailAddress" }
+					}, { "type": "null" }],
+					"description": "Parsed To header addresses. Null if the email had no To header."
+				},
+				"in_reply_to": {
+					"anyOf": [{
+						"type": "array",
+						"items": { "type": "string" }
+					}, { "type": "null" }],
+					"description": "In-Reply-To header values (Message-IDs of the email(s) being replied to). Null if the email had no In-Reply-To header. Per RFC 5322, this can contain multiple Message-IDs, though typically just one.",
+					"examples": [["<original-message-id@example.com>"]]
+				},
+				"references": {
+					"anyOf": [{
+						"type": "array",
+						"items": { "type": "string" }
+					}, { "type": "null" }],
+					"description": "References header values (Message-IDs of the email thread). Null if the email had no References header.",
+					"examples": [["<msg1@example.com>", "<msg2@example.com>"]]
+				},
+				"attachments": {
+					"type": "array",
+					"items": { "$ref": "#/definitions/WebhookAttachment" },
+					"description": "List of attachments with metadata. Use  {@link  attachments_download_url }  to download the actual files."
+				},
+				"attachments_download_url": {
+					"type": ["string", "null"],
+					"format": "uri",
+					"pattern": "^https?://",
+					"description": "URL to download all attachments as a tar.gz archive. Null if the email had no attachments. Managed Primitive always issues HTTPS. Self-host deployments may issue HTTP URLs that resolve inside the operator's network. URL expires - check the expiration before downloading."
+				}
+			},
+			"required": [
+				"status",
+				"error",
+				"body_text",
+				"body_html",
+				"reply_to",
+				"cc",
+				"bcc",
+				"to_addresses",
+				"in_reply_to",
+				"references",
+				"attachments",
+				"attachments_download_url"
+			],
+			"description": "Parsed email content when parsing succeeded.\n\nUse the discriminant `status: \"complete\"` to narrow from  {@link  ParsedData } ."
+		},
+		"EmailAddress": {
+			"type": "object",
+			"properties": {
+				"address": {
+					"type": "string",
+					"description": "The email address portion (e.g., \"john@example.com\").\n\nThis is the raw value from the email header with no validation applied. May contain unusual but valid formats like quoted local parts."
+				},
+				"name": {
+					"type": ["string", "null"],
+					"description": "The display name portion, if present. Null if the address had no display name.\n\nMay contain any characters including unicode, emoji, or special characters as they appeared in the original email header."
+				}
+			},
+			"required": ["address", "name"],
+			"description": "A parsed email address with optional display name.\n\nThis structure is used in the `parsed` section of the webhook payload (e.g., `reply_to`, `cc`, `bcc`). For unparsed header strings, see the `headers` section (e.g., `event.email.headers.from`)."
+		},
+		"WebhookAttachment": {
+			"type": "object",
+			"properties": {
+				"filename": {
+					"type": ["string", "null"],
+					"description": "Original filename from the email. May be null if the attachment had no filename specified."
+				},
+				"content_type": {
+					"type": "string",
+					"description": "MIME content type (e.g., \"application/pdf\", \"image/png\")."
+				},
+				"size_bytes": {
+					"type": "integer",
+					"minimum": 0,
+					"description": "Size of the attachment in bytes."
+				},
+				"sha256": {
+					"type": "string",
+					"pattern": "^[a-fA-F0-9]{64}$",
+					"description": "SHA-256 hash of the attachment content (hex-encoded). Use this to verify attachment integrity after download."
+				},
+				"part_index": {
+					"type": "integer",
+					"minimum": 0,
+					"description": "Zero-based index of this part in the MIME structure."
+				},
+				"tar_path": {
+					"type": "string",
+					"description": "Path to this attachment within the downloaded tar.gz archive."
+				}
+			},
+			"required": [
+				"filename",
+				"content_type",
+				"size_bytes",
+				"sha256",
+				"part_index",
+				"tar_path"
+			],
+			"description": "Metadata for an email attachment.\n\nAttachment content is not included directly in the webhook payload. Use the `attachments_download_url` from  {@link  ParsedDataComplete }  to download all attachments as a tar.gz archive."
+		},
+		"ParsedDataFailed": {
+			"type": "object",
+			"properties": {
+				"status": {
+					"type": "string",
+					"const": "failed",
+					"description": "Discriminant indicating parsing failed."
+				},
+				"error": {
+					"$ref": "#/definitions/ParsedError",
+					"description": "Details about why parsing failed."
+				},
+				"body_text": {
+					"type": "null",
+					"description": "Always null when parsing fails."
+				},
+				"body_html": {
+					"type": "null",
+					"description": "Always null when parsing fails."
+				},
+				"reply_to": {
+					"type": "null",
+					"description": "Always null when parsing fails."
+				},
+				"cc": {
+					"type": "null",
+					"description": "Always null when parsing fails."
+				},
+				"bcc": {
+					"type": "null",
+					"description": "Always null when parsing fails."
+				},
+				"to_addresses": {
+					"type": "null",
+					"description": "Always null when parsing fails."
+				},
+				"in_reply_to": {
+					"type": "null",
+					"description": "Always null when parsing fails."
+				},
+				"references": {
+					"type": "null",
+					"description": "Always null when parsing fails."
+				},
+				"attachments": {
+					"type": "array",
+					"items": { "$ref": "#/definitions/WebhookAttachment" },
+					"description": "May contain partial attachment metadata even when parsing failed. Useful for debugging or recovering partial data."
+				},
+				"attachments_download_url": {
+					"type": "null",
+					"description": "Always null when parsing fails."
+				}
+			},
+			"required": [
+				"status",
+				"error",
+				"body_text",
+				"body_html",
+				"reply_to",
+				"cc",
+				"bcc",
+				"to_addresses",
+				"in_reply_to",
+				"references",
+				"attachments",
+				"attachments_download_url"
+			],
+			"description": "Parsed email content when parsing failed.\n\nUse the discriminant `status: \"failed\"` to narrow from  {@link  ParsedData } ."
+		},
+		"ParsedError": {
+			"type": "object",
+			"properties": {
+				"code": {
+					"type": "string",
+					"enum": ["PARSE_FAILED", "ATTACHMENT_EXTRACTION_FAILED"],
+					"description": "Error code indicating the type of failure.\n- `PARSE_FAILED`: The email could not be parsed (e.g., malformed MIME)\n- `ATTACHMENT_EXTRACTION_FAILED`: Email parsed but attachments couldn't be extracted"
+				},
+				"message": {
+					"type": "string",
+					"description": "Human-readable error message describing what went wrong."
+				},
+				"retryable": {
+					"type": "boolean",
+					"description": "Whether retrying might succeed. If true, the error was transient (e.g., timeout). If false, the email itself is problematic."
+				}
+			},
+			"required": [
+				"code",
+				"message",
+				"retryable"
+			],
+			"description": "Error details when email parsing fails."
+		},
+		"EmailAnalysis": {
+			"type": "object",
+			"properties": {
+				"spamassassin": {
+					"type": "object",
+					"properties": { "score": {
+						"type": "number",
+						"description": "Overall spam score (sum of all rule scores). Higher scores indicate higher likelihood of spam. Unbounded - can be negative (ham) or very high (spam)."
+					} },
+					"required": ["score"],
+					"description": "SpamAssassin analysis results.\n\nOptional. Present when the email was processed by a SpamAssassin-equipped pipeline (always present in Primitive's managed service). When absent, spam scoring was not performed on this email."
+				},
+				"forward": {
+					"$ref": "#/definitions/ForwardAnalysis",
+					"description": "Forward detection and analysis results.\n\nOptional. In Primitive's managed service this object is included only when forwarded content is detected; when absent, no forward was detected or forward detection was not performed."
+				},
+				"bounce": {
+					"$ref": "#/definitions/BounceAnalysis",
+					"description": "Bounce (delivery status notification) analysis.\n\nPresent on `email.bounced` events: the parsed DSN reporting that a message you sent could not be delivered. Absent on all other event types."
+				},
+				"tls_report": {
+					"$ref": "#/definitions/TlsReportAnalysis",
+					"description": "SMTP TLS report analysis (RFC 8460).\n\nPresent on `email.tls_report` events: a remote MTA's report of TLS negotiation results for mail sent to your domain. Absent on all other event types."
+				},
+				"dmarc_report": {
+					"$ref": "#/definitions/DmarcReportAnalysis",
+					"description": "DMARC aggregate report analysis (RFC 7489).\n\nPresent on `email.dmarc_report` events: a receiver's periodic aggregate report of DMARC authentication results for your domain. Absent on all other event types."
+				}
+			},
+			"description": "Email analysis and classification results.\n\nAll properties in this object are optional. Which fields are present depends on the analysis pipeline processing the email. Primitive's managed service populates all fields. Self-hosted or third-party deployments may include some, all, or none of these fields depending on their pipeline configuration.\n\nWhen a field is absent, it means that particular analysis was not performed, not that the analysis produced no results. For example, a missing `spamassassin` field means SpamAssassin was not run, not that the email scored 0.\n\nThese fields may be omitted from the payload entirely but must not be set to null."
+		},
+		"BounceAnalysis": {
+			"type": "object",
+			"properties": {
+				"is_bounce": {
+					"type": "boolean",
+					"const": true,
+					"description": "Always `true` on a parsed bounce."
+				},
+				"kind": {
+					"type": "string",
+					"const": "dsn",
+					"description": "The machine-mail kind. Always `dsn` for a bounce."
+				},
+				"type": {
+					"type": "string",
+					"enum": [
+						"permanent",
+						"transient",
+						"undetermined"
+					],
+					"description": "Whether the failure is permanent (hard bounce), transient (soft bounce, may be retried), or undetermined."
+				},
+				"category": {
+					"type": "string",
+					"enum": [
+						"mailbox_does_not_exist",
+						"domain_does_not_exist",
+						"domain_not_accepting_mail",
+						"mailbox_full",
+						"mailbox_inactive",
+						"message_too_large",
+						"content_rejected",
+						"policy_blocked",
+						"auth_failure",
+						"relay_denied",
+						"rate_limited",
+						"network_error",
+						"recipient_moved",
+						"expired",
+						"undetermined"
+					],
+					"description": "Best-effort reason category for the failure."
+				},
+				"classified_by": {
+					"type": "string",
+					"enum": [
+						"status_code",
+						"smtp_code",
+						"pattern",
+						"provider",
+						"none"
+					],
+					"description": "Which signal produced `category` (for transparency and debugging)."
+				},
+				"failed_recipient": {
+					"type": ["string", "null"],
+					"description": "The recipient address that failed, if the report identifies one."
+				},
+				"smtp_code": {
+					"type": ["integer", "null"],
+					"description": "SMTP reply code (e.g. `550`), if reported."
+				},
+				"status_code": {
+					"type": ["string", "null"],
+					"description": "Enhanced mail system status code (RFC 3463, e.g. `5.1.1`), if reported."
+				},
+				"diagnostic_code": {
+					"type": ["string", "null"],
+					"description": "Raw diagnostic text from the reporting MTA, if present."
+				},
+				"reported_by_mta": {
+					"type": ["string", "null"],
+					"description": "The MTA that generated the report, if identifiable."
+				},
+				"original_message_id": {
+					"type": ["string", "null"],
+					"description": "Message-ID of the original message that bounced, if recoverable. Match this against the `message_id` of a message you sent to correlate the bounce."
+				},
+				"reasons": {
+					"type": "array",
+					"items": { "type": "string" },
+					"description": "Human-readable reason strings extracted from the report."
+				}
+			},
+			"required": [
+				"is_bounce",
+				"kind",
+				"type",
+				"category",
+				"classified_by",
+				"failed_recipient",
+				"smtp_code",
+				"status_code",
+				"diagnostic_code",
+				"reported_by_mta",
+				"original_message_id",
+				"reasons"
+			],
+			"description": "Parsed delivery status notification (bounce). Present as `email.analysis.bounce` on `email.bounced` events."
+		},
+		"TlsReportFailure": {
+			"type": "object",
+			"properties": {
+				"result_type": {
+					"type": ["string", "null"],
+					"description": "Failure result type (e.g. `certificate-expired`, `starttls-not-supported`)."
+				},
+				"count": {
+					"type": "integer",
+					"description": "Number of sessions that hit this failure."
+				},
+				"sending_mta_ip": { "type": ["string", "null"] },
+				"receiving_mx_hostname": { "type": ["string", "null"] }
+			},
+			"required": [
+				"result_type",
+				"count",
+				"sending_mta_ip",
+				"receiving_mx_hostname"
+			]
+		},
+		"TlsReportPolicy": {
+			"type": "object",
+			"properties": {
+				"policy_domain": { "type": ["string", "null"] },
+				"policy_type": {
+					"type": ["string", "null"],
+					"description": "Policy type the sessions were evaluated against (e.g. `sts`, `tlsa`, `no-policy-found`)."
+				},
+				"successful_sessions": { "type": "integer" },
+				"failed_sessions": { "type": "integer" },
+				"failures": {
+					"type": "array",
+					"items": { "$ref": "#/definitions/TlsReportFailure" }
+				}
+			},
+			"required": [
+				"policy_domain",
+				"policy_type",
+				"successful_sessions",
+				"failed_sessions",
+				"failures"
+			]
+		},
+		"TlsReportAnalysis": {
+			"type": "object",
+			"properties": {
+				"kind": {
+					"type": "string",
+					"const": "tls_report"
+				},
+				"organization": {
+					"type": ["string", "null"],
+					"description": "Reporting organization name."
+				},
+				"report_id": { "type": ["string", "null"] },
+				"contact": {
+					"type": ["string", "null"],
+					"description": "Reporter contact, if provided."
+				},
+				"date_range": {
+					"type": "object",
+					"properties": {
+						"start": {
+							"type": ["string", "null"],
+							"description": "ISO 8601 start of the reporting window."
+						},
+						"end": {
+							"type": ["string", "null"],
+							"description": "ISO 8601 end of the reporting window."
+						}
+					},
+					"required": ["start", "end"]
+				},
+				"total_successful_sessions": { "type": "integer" },
+				"total_failed_sessions": { "type": "integer" },
+				"policies": {
+					"type": "array",
+					"items": { "$ref": "#/definitions/TlsReportPolicy" }
+				}
+			},
+			"required": [
+				"kind",
+				"organization",
+				"report_id",
+				"contact",
+				"date_range",
+				"total_successful_sessions",
+				"total_failed_sessions",
+				"policies"
+			],
+			"description": "Parsed SMTP TLS report (RFC 8460). Present as `email.analysis.tls_report` on `email.tls_report` events."
+		},
+		"DmarcRecord": {
+			"type": "object",
+			"properties": {
+				"source_ip": { "type": ["string", "null"] },
+				"count": { "type": "integer" },
+				"disposition": {
+					"type": ["string", "null"],
+					"description": "Disposition applied by the receiver: `none`, `quarantine`, or `reject`."
+				},
+				"dkim": {
+					"type": ["string", "null"],
+					"description": "DKIM alignment result: `pass` or `fail`."
+				},
+				"spf": {
+					"type": ["string", "null"],
+					"description": "SPF alignment result: `pass` or `fail`."
+				},
+				"header_from": { "type": ["string", "null"] }
+			},
+			"required": [
+				"source_ip",
+				"count",
+				"disposition",
+				"dkim",
+				"spf",
+				"header_from"
+			]
+		},
+		"DmarcReportAnalysis": {
+			"type": "object",
+			"properties": {
+				"kind": {
+					"type": "string",
+					"const": "dmarc_report"
+				},
+				"organization": { "type": ["string", "null"] },
+				"report_id": { "type": ["string", "null"] },
+				"date_range": {
+					"type": "object",
+					"properties": {
+						"start": {
+							"type": ["string", "null"],
+							"description": "ISO 8601 start of the reporting window."
+						},
+						"end": {
+							"type": ["string", "null"],
+							"description": "ISO 8601 end of the reporting window."
+						}
+					},
+					"required": ["start", "end"]
+				},
+				"policy_published": {
+					"type": "object",
+					"properties": {
+						"domain": { "type": ["string", "null"] },
+						"p": {
+							"type": ["string", "null"],
+							"description": "Published domain policy: `none`, `quarantine`, or `reject`."
+						},
+						"sp": {
+							"type": ["string", "null"],
+							"description": "Published subdomain policy."
+						},
+						"pct": {
+							"type": ["integer", "null"],
+							"description": "Percentage of messages the policy is applied to."
+						},
+						"adkim": {
+							"type": ["string", "null"],
+							"description": "DKIM alignment mode: `r` (relaxed) or `s` (strict)."
+						},
+						"aspf": {
+							"type": ["string", "null"],
+							"description": "SPF alignment mode: `r` (relaxed) or `s` (strict)."
+						}
+					},
+					"required": [
+						"domain",
+						"p",
+						"sp",
+						"pct",
+						"adkim",
+						"aspf"
+					]
+				},
+				"total_count": {
+					"type": "integer",
+					"description": "Total messages covered by the report."
+				},
+				"dkim_pass_count": { "type": "integer" },
+				"spf_pass_count": { "type": "integer" },
+				"records": {
+					"type": "array",
+					"items": { "$ref": "#/definitions/DmarcRecord" }
+				}
+			},
+			"required": [
+				"kind",
+				"organization",
+				"report_id",
+				"date_range",
+				"policy_published",
+				"total_count",
+				"dkim_pass_count",
+				"spf_pass_count",
+				"records"
+			],
+			"description": "Parsed DMARC aggregate report (RFC 7489). Present as `email.analysis.dmarc_report` on `email.dmarc_report` events."
+		},
+		"ForwardAnalysis": {
+			"type": "object",
+			"properties": {
+				"detected": {
+					"type": "boolean",
+					"description": "Whether any forwards were detected in the email."
+				},
+				"results": {
+					"type": "array",
+					"items": { "$ref": "#/definitions/ForwardResult" },
+					"description": "Analysis results for each detected forward."
+				},
+				"attachments_found": {
+					"type": "integer",
+					"minimum": 0,
+					"description": "Total number of .eml attachments found."
+				},
+				"attachments_analyzed": {
+					"type": "integer",
+					"minimum": 0,
+					"description": "Number of .eml attachments that were analyzed."
+				},
+				"attachments_limit": {
+					"type": ["integer", "null"],
+					"minimum": 1,
+					"description": "Maximum number of attachments that will be analyzed, or null if unlimited."
+				}
+			},
+			"required": [
+				"detected",
+				"results",
+				"attachments_found",
+				"attachments_analyzed",
+				"attachments_limit"
+			],
+			"description": "Forward detection and analysis results."
+		},
+		"ForwardResult": {
+			"anyOf": [
+				{ "$ref": "#/definitions/ForwardResultInline" },
+				{ "$ref": "#/definitions/ForwardResultAttachmentAnalyzed" },
+				{ "$ref": "#/definitions/ForwardResultAttachmentSkipped" }
+			],
+			"description": "Result for a single forwarded email detected in the message.\n\nUse the `type` and `analyzed` fields to narrow the type:\n- `type: 'inline'` - Inline forward, always analyzed\n- `type: 'attachment'` + `analyzed: true` - Analyzed attachment\n- `type: 'attachment'` + `analyzed: false` - Skipped attachment"
+		},
+		"ForwardResultInline": {
+			"type": "object",
+			"properties": {
+				"type": {
+					"type": "string",
+					"const": "inline"
+				},
+				"original_sender": {
+					"anyOf": [{ "$ref": "#/definitions/ForwardOriginalSender" }, { "type": "null" }],
+					"description": "Original sender of the forwarded email, if extractable."
+				},
+				"verification": {
+					"$ref": "#/definitions/ForwardVerification",
+					"description": "Verification result for the forwarded email."
+				},
+				"summary": {
+					"type": "string",
+					"description": "Human-readable summary of the forward analysis."
+				}
+			},
+			"required": [
+				"type",
+				"original_sender",
+				"verification",
+				"summary"
+			],
+			"description": "Result for an inline forward that was detected and analyzed. Inline forwards are always analyzed when forward detection is enabled."
+		},
+		"ForwardOriginalSender": {
+			"type": "object",
+			"properties": {
+				"email": {
+					"type": "string",
+					"description": "Email address of the original sender."
+				},
+				"domain": {
+					"type": "string",
+					"description": "Domain of the original sender."
+				}
+			},
+			"required": ["email", "domain"],
+			"description": "Original sender information extracted from the forwarded email."
+		},
+		"ForwardVerification": {
+			"type": "object",
+			"properties": {
+				"verdict": {
+					"$ref": "#/definitions/ForwardVerdict",
+					"description": "Overall verdict on whether the forward is authentic."
+				},
+				"confidence": {
+					"$ref": "#/definitions/AuthConfidence",
+					"description": "Confidence level for this verdict."
+				},
+				"dkim_verified": {
+					"type": "boolean",
+					"description": "Whether a valid DKIM signature was found that verifies the original sender."
+				},
+				"dkim_domain": {
+					"type": ["string", "null"],
+					"description": "Domain of the DKIM signature that verified the forward, if any."
+				},
+				"dmarc_policy": {
+					"$ref": "#/definitions/DmarcPolicy",
+					"description": "DMARC policy of the original sender's domain."
+				}
+			},
+			"required": [
+				"verdict",
+				"confidence",
+				"dkim_verified",
+				"dkim_domain",
+				"dmarc_policy"
+			],
+			"description": "Verification result for a forwarded email."
+		},
+		"ForwardVerdict": {
+			"type": "string",
+			"enum": ["legit", "unknown"],
+			"description": "Verdict for forwarded email verification.\n\n- `legit`: DKIM signature verified the original sender\n- `unknown`: Could not verify the forwarded email's authenticity"
+		},
+		"AuthConfidence": {
+			"type": "string",
+			"enum": [
+				"high",
+				"medium",
+				"low"
+			],
+			"description": "Confidence level for the authentication verdict.\n\n- `high`: Strong cryptographic evidence (DKIM aligned + DMARC pass)\n- `medium`: Good evidence but with caveats (SPF-only alignment)\n- `low`: Weak evidence (missing authentication or unclear results)"
+		},
+		"DmarcPolicy": {
+			"type": ["string", "null"],
+			"enum": [
+				"reject",
+				"quarantine",
+				"none",
+				null
+			],
+			"description": "DMARC policy action specified in the domain's DMARC record.\n\n- `reject`: The domain owner requests that receivers reject failing emails\n- `quarantine`: The domain owner requests that failing emails be treated as suspicious\n- `none`: The domain owner is only monitoring (no action requested)\n- `null`: No DMARC policy was found for the domain"
+		},
+		"ForwardResultAttachmentAnalyzed": {
+			"type": "object",
+			"properties": {
+				"type": {
+					"type": "string",
+					"const": "attachment"
+				},
+				"attachment_tar_path": {
+					"type": "string",
+					"description": "Path to the attachment in the attachments tar archive."
+				},
+				"attachment_filename": {
+					"type": ["string", "null"],
+					"description": "Original filename of the attachment, if available."
+				},
+				"analyzed": {
+					"type": "boolean",
+					"const": true,
+					"description": "Whether this attachment was analyzed."
+				},
+				"original_sender": {
+					"anyOf": [{ "$ref": "#/definitions/ForwardOriginalSender" }, { "type": "null" }],
+					"description": "Original sender of the forwarded email, if extractable."
+				},
+				"verification": {
+					"$ref": "#/definitions/ForwardVerification",
+					"description": "Verification result for the forwarded email."
+				},
+				"summary": {
+					"type": "string",
+					"description": "Human-readable summary of the forward analysis."
+				}
+			},
+			"required": [
+				"type",
+				"attachment_tar_path",
+				"attachment_filename",
+				"analyzed",
+				"original_sender",
+				"verification",
+				"summary"
+			],
+			"description": "Result for an attachment forward that was analyzed."
+		},
+		"ForwardResultAttachmentSkipped": {
+			"type": "object",
+			"properties": {
+				"type": {
+					"type": "string",
+					"const": "attachment"
+				},
+				"attachment_tar_path": {
+					"type": "string",
+					"description": "Path to the attachment in the attachments tar archive."
+				},
+				"attachment_filename": {
+					"type": ["string", "null"],
+					"description": "Original filename of the attachment, if available."
+				},
+				"analyzed": {
+					"type": "boolean",
+					"const": false,
+					"description": "Whether this attachment was analyzed."
+				},
+				"original_sender": {
+					"type": "null",
+					"description": "Always null when not analyzed."
+				},
+				"verification": {
+					"type": "null",
+					"description": "Always null when not analyzed."
+				},
+				"summary": {
+					"type": "string",
+					"description": "Human-readable summary explaining why analysis was skipped."
+				}
+			},
+			"required": [
+				"type",
+				"attachment_tar_path",
+				"attachment_filename",
+				"analyzed",
+				"original_sender",
+				"verification",
+				"summary"
+			],
+			"description": "Result for an attachment forward that was detected but not analyzed. This occurs when attachment analysis is disabled or the limit was reached."
+		},
+		"EmailAuth": {
+			"type": "object",
+			"properties": {
+				"spf": {
+					"$ref": "#/definitions/SpfResult",
+					"description": "SPF verification result.\n\nSPF checks if the sending IP is authorized by the envelope sender's domain. \"pass\" means the IP is authorized; \"fail\" means it's explicitly not allowed."
+				},
+				"dmarc": {
+					"$ref": "#/definitions/DmarcResult",
+					"description": "DMARC verification result.\n\nDMARC passes if either SPF or DKIM passes AND aligns with the From: domain. \"pass\" means the email is authenticated according to the sender's policy."
+				},
+				"dmarcPolicy": {
+					"$ref": "#/definitions/DmarcPolicy",
+					"description": "DMARC policy from the sender's DNS record.\n\n- `reject`: Domain wants receivers to reject failing emails\n- `quarantine`: Domain wants failing emails marked as suspicious\n- `none`: Domain is monitoring only (no action requested)\n- `null`: No DMARC record found for this domain"
+				},
+				"dmarcFromDomain": {
+					"type": ["string", "null"],
+					"description": "The organizational domain used for DMARC lookups.\n\nFor example, if the From: address is `user@mail.example.com`, the DMARC lookup checks `_dmarc.mail.example.com`, then falls back to `_dmarc.example.com`. This field shows which domain's policy was used."
+				},
+				"dmarcSpfAligned": {
+					"type": "boolean",
+					"description": "Whether SPF aligned with the From: domain for DMARC purposes.\n\nTrue if the envelope sender domain matches the From: domain (per alignment mode)."
+				},
+				"dmarcDkimAligned": {
+					"type": "boolean",
+					"description": "Whether DKIM aligned with the From: domain for DMARC purposes.\n\nTrue if at least one DKIM signature's domain matches the From: domain."
+				},
+				"dmarcSpfStrict": {
+					"type": ["boolean", "null"],
+					"description": "Whether DMARC SPF alignment mode is strict.\n\n- `true`: Strict alignment required (exact domain match)\n- `false`: Relaxed alignment allowed (organizational domain match)\n- `null`: No DMARC record found"
+				},
+				"dmarcDkimStrict": {
+					"type": ["boolean", "null"],
+					"description": "Whether DMARC DKIM alignment mode is strict.\n\n- `true`: Strict alignment required (exact domain match)\n- `false`: Relaxed alignment allowed (organizational domain match)\n- `null`: No DMARC record found"
+				},
+				"dkimSignatures": {
+					"type": "array",
+					"items": { "$ref": "#/definitions/DkimSignature" },
+					"description": "All DKIM signatures found in the email with their verification results.\n\nMay be empty if no DKIM signatures were present."
+				}
+			},
+			"required": [
+				"spf",
+				"dmarc",
+				"dmarcPolicy",
+				"dmarcFromDomain",
+				"dmarcSpfAligned",
+				"dmarcDkimAligned",
+				"dmarcSpfStrict",
+				"dmarcDkimStrict",
+				"dkimSignatures"
+			],
+			"description": "Email authentication results for SPF, DKIM, and DMARC.\n\nUse `validateEmailAuth()` to compute a verdict based on these results."
+		},
+		"SpfResult": {
+			"type": "string",
+			"enum": [
+				"pass",
+				"fail",
+				"softfail",
+				"neutral",
+				"none",
+				"temperror",
+				"permerror"
+			],
+			"description": "SPF verification result."
+		},
+		"DmarcResult": {
+			"type": "string",
+			"enum": [
+				"pass",
+				"fail",
+				"none",
+				"temperror",
+				"permerror"
+			],
+			"description": "DMARC verification result."
+		},
+		"DkimSignature": {
+			"type": "object",
+			"properties": {
+				"domain": {
+					"type": "string",
+					"description": "The domain that signed this DKIM signature (d= tag). This may differ from the From: domain (that's what alignment checks)."
+				},
+				"selector": {
+					"type": ["string", "null"],
+					"description": "The DKIM selector used to locate the public key (s= tag). Combined with the domain to form the DNS lookup: `selector._domainkey.domain`\n\nOptional in self-hosted environments where the milter may not provide selector info."
+				},
+				"result": {
+					"$ref": "#/definitions/DkimResult",
+					"description": "Verification result for this specific signature."
+				},
+				"aligned": {
+					"type": "boolean",
+					"description": "Whether this signature's domain aligns with the From: domain (for DMARC).\n\nAlignment can be \"strict\" (exact match) or \"relaxed\" (organizational domain match). For example, if From: is `user@sub.example.com` and DKIM is signed by `example.com`:\n- Relaxed alignment: true (same organizational domain)\n- Strict alignment: false (not exact match)"
+				},
+				"keyBits": {
+					"type": ["integer", "null"],
+					"minimum": 1,
+					"maximum": 16384,
+					"description": "Key size in bits (e.g., 1024, 2048). Null if the key size couldn't be determined.\n\nOptional in self-hosted environments."
+				},
+				"algo": {
+					"type": ["string", "null"],
+					"description": "Signing algorithm (e.g., \"rsa-sha256\", \"ed25519-sha256\").\n\nOptional in self-hosted environments."
+				}
+			},
+			"required": [
+				"domain",
+				"selector",
+				"result",
+				"aligned",
+				"keyBits",
+				"algo"
+			],
+			"description": "Details about a single DKIM signature found in the email.\n\nAn email may have multiple DKIM signatures (e.g., one from the sending domain and one from the ESP). Each signature is verified independently."
+		},
+		"DkimResult": {
+			"type": "string",
+			"enum": [
+				"pass",
+				"fail",
+				"temperror",
+				"permerror"
+			],
+			"description": "DKIM signature verification result for a single signature."
+		}
+	}
+};
+//#endregion
+//#region src/webhook/version.ts
+/**
+* Webhook API Version
+*
+* Single source of truth for the webhook version.
+* Update this file when bumping the API version.
+*/
+/**
+* The current webhook API version this SDK is built for.
+* Webhooks may be sent with different versions - the SDK accepts any valid
+* YYYY-MM-DD formatted version string. Compare against this constant if you
+* need to handle version-specific behavior.
+*/
+const WEBHOOK_VERSION = "2025-12-14";
+//#endregion
+//#region src/webhook/parsing.ts
+/**
+* JSON parsing utilities with helpful error messages.
+* @internal
+*/
+/**
+* Parse a raw body string/Buffer into JSON with helpful error messages.
+*
+* Handles:
+* - Empty/whitespace bodies
+* - BOM (byte order mark) prefix stripping
+* - Detailed JSON syntax error messages with position
+*
+* @param rawBody - The raw request body (string or Buffer)
+* @returns The parsed JSON value
+* @throws WebhookPayloadError with helpful message on failure
+* @internal
+*/
+function parseJsonBody(rawBody) {
+	const bodyStr = typeof rawBody === "string" ? rawBody : bufferToString(rawBody, "request body");
+	if (!bodyStr || bodyStr.trim() === "") throw new WebhookPayloadError("PAYLOAD_EMPTY_BODY", "Received empty request body", "The request body is empty. Check your web framework is correctly passing the request body.");
+	try {
+		const cleanBody = bodyStr.charCodeAt(0) === 65279 ? bodyStr.slice(1) : bodyStr;
+		return JSON.parse(cleanBody);
+	} catch (e) {
+		const jsonError = e;
+		const position = jsonError.message.match(/position\s*(\d+)/i)?.[1];
+		throw new WebhookPayloadError("JSON_PARSE_FAILED", "Failed to parse webhook body as JSON", position ? `Invalid JSON at position ${position}. Check your web framework isn't truncating the request body.` : `Invalid JSON: ${jsonError.message}. Check the raw request body is valid JSON.`, jsonError);
+	}
+}
+//#endregion
+//#region src/webhook/index.ts
+const BASE64_PATTERN = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+/**
+* The header that names the webhook event for ALL event families
+* (`email.*`, `payment.*`, `interaction.*`). It is the primary discriminator
+* the parser keys on, because the stored body is sent verbatim with no envelope.
+*/
+const WEBHOOK_EVENT_HEADER = "X-Webhook-Event";
+const SIGNATURE_HEADER_NAMES = ["primitive-signature", "mymx-signature"];
+/**
+* Read the `X-Webhook-Event` header value (case-insensitive). Returns null when
+* the header is absent.
+*/
+function getEventHeader(headers) {
+	if (headers instanceof Headers) return headers.get("x-webhook-event");
+	const obj = headers;
+	const key = Object.keys(obj).find((k) => k.toLowerCase() === "x-webhook-event");
+	if (!key) return null;
+	const value = obj[key];
+	if (Array.isArray(value)) return value[0] ?? null;
+	return value ?? null;
+}
+const STANDARD_WEBHOOKS_HEADER_NAMES = [
+	"webhook-signature",
+	"webhook-id",
+	"webhook-timestamp"
+];
+/**
+* Extract signature header from various header formats.
+* Checks for Primitive-Signature first, then falls back to the legacy
+* MyMX-Signature for backward compatibility with older servers.
+*/
+function getSignatureHeader(headers) {
+	if (headers instanceof Headers) {
+		for (const name of SIGNATURE_HEADER_NAMES) {
+			const value = headers.get(name);
+			if (value) return value;
+		}
+		return "";
+	}
+	const obj = headers;
+	const keys = Object.keys(obj);
+	for (const name of SIGNATURE_HEADER_NAMES) {
+		const key = keys.find((k) => k.toLowerCase() === name);
+		if (!key) continue;
+		const value = obj[key];
+		if (Array.isArray(value)) return value[0] ?? "";
+		if (value) return value;
+	}
+	return "";
+}
+/**
+* Extract Standard Webhooks headers from various header formats.
+*
+* Returns all three required headers if `webhook-signature` is present.
+* If `webhook-signature` is found but `webhook-id` or `webhook-timestamp`
+* is missing, throws an error (partial Standard Webhooks headers indicate
+* a misconfiguration, not a Primitive-format webhook).
+*
+* Returns null if `webhook-signature` is not present (fall through to Primitive).
+*/
+function getStandardWebhooksHeaders(headers) {
+	let signature = "";
+	let msgId = "";
+	let timestamp = "";
+	let hasSignatureKey = false;
+	if (headers instanceof Headers) {
+		hasSignatureKey = headers.has("webhook-signature");
+		if (!hasSignatureKey) return null;
+		signature = headers.get("webhook-signature") ?? "";
+		msgId = headers.get("webhook-id") ?? "";
+		timestamp = headers.get("webhook-timestamp") ?? "";
+	} else {
+		const obj = headers;
+		const keys = Object.keys(obj);
+		for (const name of STANDARD_WEBHOOKS_HEADER_NAMES) {
+			const key = keys.find((k) => k.toLowerCase() === name);
+			const raw = key ? obj[key] : void 0;
+			const value = Array.isArray(raw) ? raw[0] ?? "" : raw ?? "";
+			if (name === "webhook-signature") {
+				hasSignatureKey = key !== void 0;
+				signature = value;
+			} else if (name === "webhook-id") msgId = value;
+			else if (name === "webhook-timestamp") timestamp = value;
+		}
+		if (!hasSignatureKey) return null;
+	}
+	if (!signature) throw new WebhookVerificationError("INVALID_SIGNATURE_HEADER", "Empty webhook-signature header. Expected: \"v1,<base64>\"");
+	if (!msgId || !timestamp) throw new WebhookVerificationError("INVALID_SIGNATURE_HEADER", `Found webhook-signature header but missing ${!msgId ? "webhook-id" : "webhook-timestamp"} header. Standard Webhooks requires all three headers: webhook-id, webhook-timestamp, webhook-signature.`);
+	return {
+		msgId,
+		timestamp,
+		signature
+	};
+}
+/**
+* Verify, parse, and validate a webhook in one call.
+*
+* This is the recommended way to handle Primitive webhooks. It:
+* 1. Verifies the signature to ensure the webhook is authentic
+* 2. Parses the JSON body
+* 3. Validates the payload against the canonical JSON schema
+* 4. Returns a fully typed EmailReceivedEvent
+*
+* @param options - The webhook data and secret
+* @returns A validated EmailReceivedEvent
+* @throws {WebhookVerificationError} If signature verification fails
+* @throws {WebhookPayloadError} If JSON parsing fails
+* @throws {WebhookValidationError} If schema validation fails
+*
+* @example
+* ```typescript
+* import { handleWebhook, PrimitiveWebhookError } from '@primitivedotdev/sdk';
+*
+* app.post('/webhooks/email', express.raw({ type: 'application/json' }), (req, res) => {
+*   try {
+*     const event = handleWebhook({
+*       body: req.body,
+*       headers: req.headers,
+*       secret: process.env.PRIMITIVE_WEBHOOK_SECRET,
+*     });
+*
+*     console.log('Email from:', event.email.headers.from);
+*     res.json({ received: true });
+*   } catch (err) {
+*     if (err instanceof PrimitiveWebhookError) {
+*       console.error(`[${err.code}] ${err.message}`);
+*       return res.status(400).json({ error: err.code });
+*     }
+*     throw err;
+*   }
+* });
+* ```
+*/
+function verifyWebhookRequest(options) {
+	const { body, headers, secret, toleranceSeconds } = options;
+	const swHeaders = getStandardWebhooksHeaders(headers);
+	if (swHeaders) verifyStandardWebhooksSignature({
+		rawBody: body,
+		msgId: swHeaders.msgId,
+		timestamp: swHeaders.timestamp,
+		signatureHeader: swHeaders.signature,
+		secret,
+		toleranceSeconds
+	});
+	else verifyWebhookSignature({
+		rawBody: body,
+		signatureHeader: getSignatureHeader(headers),
+		secret,
+		toleranceSeconds
+	});
+}
+/**
+* Verify, then parse any webhook event into a typed value.
+*
+* Unlike {@link handleWebhook}, this returns the full {@link WebhookEvent}
+* union, so it handles `payment.*` and `interaction.x402.*` events in addition
+* to `email.*`. The flow is:
+*
+* 1. Verify the signature over the RAW body (works for every event family).
+* 2. Parse the JSON body.
+* 3. Classify on the `X-Webhook-Event` HEADER (the primary discriminator),
+*    returning a typed event for known types and an UnknownEvent for the rest.
+*
+* @example
+* ```typescript
+* const event = handleWebhookEvent({ body, headers, secret });
+* if (isPaymentSettledEvent(event)) {
+*   // typed PaymentSettledEvent
+* } else if (isInteractionX402Event(event)) {
+*   // typed interaction.x402.* event
+* }
+* ```
+*/
+function handleWebhookEvent(options) {
+	verifyWebhookRequest(options);
+	return parseWebhookEvent(parseJsonBody(options.body), getEventHeader(options.headers));
+}
+function handleWebhook(options) {
+	verifyWebhookRequest(options);
+	return validateEmailReceivedEvent(parseJsonBody(options.body));
+}
+function receive(input, options) {
+	if (input instanceof Request) return receiveFromRequest(input, options);
+	return normalizeReceivedEmail(handleWebhook(input));
+}
+async function receiveFromRequest(request, options) {
+	if (!options?.secret) throw new WebhookVerificationError("MISSING_SECRET", "Webhook secret is required but was empty or not provided");
+	return normalizeReceivedEmail(handleWebhook({
+		body: Buffer.from(await request.arrayBuffer()),
+		headers: request.headers,
+		secret: options.secret,
+		toleranceSeconds: options.toleranceSeconds
+	}));
+}
+/**
+* Returns headers for the optional "content discard" feature.
+*
+* If you have the "content discard" setting enabled in your Primitive dashboard,
+* returning this header tells Primitive to permanently delete the email content
+* after successful delivery. Requires BOTH the dashboard setting AND this header.
+*
+* **Warning:** Only use this if you can durably guarantee you've processed the email.
+* Once discarded, the email content is gone forever.
+*
+* @returns Headers object to spread into your response
+*
+* @example Express (only if using content discard)
+* ```typescript
+* app.post('/webhook', async (req, res) => {
+*   const event = handleWebhook({ ... });
+*   // Durably save the email first!
+*   await db.saveEmail(event);
+*   res.set(confirmedHeaders()).json({ received: true });
+* });
+* ```
+*
+* @example Fetch API / Next.js (only if using content discard)
+* ```typescript
+* return new Response(JSON.stringify({ received: true }), {
+*   status: 200,
+*   headers: {
+*     'Content-Type': 'application/json',
+*     ...confirmedHeaders(),
+*   },
+* });
+* ```
+*/
+function confirmedHeaders() {
+	return {
+		[PRIMITIVE_CONFIRMED_HEADER]: "true",
+		[LEGACY_CONFIRMED_HEADER]: "true"
+	};
+}
+/**
+* Check if the download URL for a webhook event has expired.
+*
+* @param event - The webhook event
+* @param now - Optional current time for testing (defaults to Date.now())
+* @returns true if the download URL has expired
+*
+* @example
+* ```typescript
+* if (isDownloadExpired(event)) {
+*   console.log("Download URL has expired, cannot fetch raw email");
+* } else {
+*   const response = await fetch(event.email.content.download.url);
+* }
+* ```
+*/
+function isDownloadExpired(event, now = Date.now()) {
+	return now >= new Date(event.email.content.download.expires_at).getTime();
+}
+/**
+* Get the time remaining (in milliseconds) before the download URL expires.
+* Returns 0 if already expired.
+*
+* @param event - The webhook event
+* @param now - Optional current time for testing (defaults to Date.now())
+* @returns Milliseconds until expiration, or 0 if expired
+*
+* @example
+* ```typescript
+* const remaining = getDownloadTimeRemaining(event);
+* if (remaining > 60000) {
+*   // More than 1 minute left, safe to download
+* }
+* ```
+*/
+function getDownloadTimeRemaining(event, now = Date.now()) {
+	const expiresAt = new Date(event.email.content.download.expires_at).getTime();
+	return Math.max(0, expiresAt - now);
+}
+/**
+* Check if the raw email content is included inline in the event.
+*
+* Use this to check before calling `decodeRawEmail()` to avoid try/catch.
+*
+* @param event - The webhook event
+* @returns true if raw content is included inline, false if download required
+*
+* @example
+* ```typescript
+* if (isRawIncluded(event)) {
+*   const rawEmail = decodeRawEmail(event);
+* } else {
+*   const response = await fetch(event.email.content.download.url);
+* }
+* ```
+*/
+function isRawIncluded(event) {
+	return event.email.content.raw.included;
+}
+/**
+* Decode the raw email content from an EmailReceivedEvent.
+*
+* Throws if the raw content is not included inline (i.e., must be downloaded).
+* By default, verifies the SHA-256 hash matches after decoding.
+*
+* NOTE: This function assumes a well-formed event from `handleWebhook()`.
+* Passing a manually constructed event with missing fields (e.g., `raw.data`
+* undefined when `raw.included` is true) will result in undefined behavior.
+*
+* @param event - The webhook event containing the raw email
+* @param options - Decoding options
+* @returns The decoded raw email as a Buffer
+* @throws {RawEmailDecodeError} If content not included or hash mismatch
+*
+* @example
+* ```typescript
+* import { handleWebhook, decodeRawEmail, isRawIncluded } from '@primitivedotdev/sdk';
+*
+* const event = handleWebhook({ body, headers, secret });
+*
+* if (isRawIncluded(event)) {
+*   const rawEmail = decodeRawEmail(event);
+*   // rawEmail is a Buffer containing the RFC 5322 email
+* } else {
+*   // Must download from event.email.content.download.url
+* }
+* ```
+*/
+function decodeRawEmail(event, options = {}) {
+	const { verify = true } = options;
+	const raw = event.email.content.raw;
+	if (!raw.included) throw new RawEmailDecodeError("NOT_INCLUDED", `Raw email not included inline (size: ${raw.size_bytes} bytes, threshold: ${raw.max_inline_bytes} bytes). Download from: ${event.email.content.download.url}`);
+	if (!BASE64_PATTERN.test(raw.data)) throw new RawEmailDecodeError("INVALID_BASE64", "Raw email data is not valid base64. The raw email data may be malformed.");
+	const decoded = Buffer.from(raw.data, "base64");
+	if (verify) {
+		const hash = createHash("sha256").update(decoded).digest("hex");
+		if (hash !== raw.sha256.toLowerCase()) throw new RawEmailDecodeError("HASH_MISMATCH", `SHA-256 hash mismatch. Expected: ${raw.sha256}, got: ${hash}. The raw email data may be corrupted.`);
+	}
+	return decoded;
+}
+/**
+* Verify downloaded raw email content against the SHA-256 hash in the event.
+*
+* Use this after fetching from `event.email.content.download.url` to ensure
+* the downloaded content matches what Primitive received.
+*
+* @param downloaded - The downloaded raw email content (Buffer, ArrayBuffer, or Uint8Array)
+* @param event - The webhook event containing the expected hash
+* @returns The verified content as a Buffer
+* @throws {RawEmailDecodeError} If hash doesn't match
+*
+* @example
+* ```typescript
+* import { handleWebhook, verifyRawEmailDownload, isRawIncluded } from '@primitivedotdev/sdk';
+*
+* const event = handleWebhook({ body, headers, secret });
+*
+* if (!isRawIncluded(event)) {
+*   const response = await fetch(event.email.content.download.url);
+*   const arrayBuffer = await response.arrayBuffer();
+*   const verified = verifyRawEmailDownload(arrayBuffer, event);
+*   // verified is a Buffer containing the RFC 5322 email
+* }
+* ```
+*/
+function verifyRawEmailDownload(downloaded, event) {
+	const buffer = Buffer.isBuffer(downloaded) ? downloaded : Buffer.from(downloaded);
+	const hash = createHash("sha256").update(buffer).digest("hex");
+	const expected = event.email.content.raw.sha256;
+	if (hash !== expected.toLowerCase()) throw new RawEmailDecodeError("HASH_MISMATCH", `SHA-256 hash mismatch. Expected: ${expected}, got: ${hash}. The downloaded content may be corrupted.`);
+	return buffer;
+}
+//#endregion
+export { signWebhookPayload as C, verifyDownloadToken as E, PRIMITIVE_SIGNATURE_HEADER as S, generateDownloadToken as T, signStandardWebhooksPayload as _, getEventHeader as a, LEGACY_SIGNATURE_HEADER as b, isDownloadExpired as c, verifyRawEmailDownload as d, WEBHOOK_VERSION as f, STANDARD_WEBHOOK_TIMESTAMP_HEADER as g, STANDARD_WEBHOOK_SIGNATURE_HEADER as h, getDownloadTimeRemaining as i, isRawIncluded as l, STANDARD_WEBHOOK_ID_HEADER as m, confirmedHeaders as n, handleWebhook as o, emailReceivedEventJsonSchema as p, decodeRawEmail as r, handleWebhookEvent as s, WEBHOOK_EVENT_HEADER as t, receive as u, verifyStandardWebhooksSignature as v, verifyWebhookSignature as w, PRIMITIVE_CONFIRMED_HEADER as x, LEGACY_CONFIRMED_HEADER as y };