@primitivedotdev/sdk 1.26.0 → 1.27.0

package/dist/{webhook-BtyuJtUF.js → trust-DBOnyTHV.js}

@@ -1,5 +1,5 @@
-import { C as normalizeReceivedEmail, c as WebhookVerificationError, i as RawEmailDecodeError, o as WebhookPayloadError, s as WebhookValidationError } from "./errors-Bo0f7eId.js";
-import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+import { n as parseFromHeaderLoose, t as parseFromHeader } from "./address-parser-BxXv4vx0.js";
+import isEmail from "validator/lib/isEmail.js";
 //#region src/generated/email-received-event.validator.generated.ts
 /**
 * AUTO-GENERATED - DO NOT EDIT
@@ -8035,6 +8035,224 @@ function validate10(data, { instancePath = "", parentData, parentDataProperty, r
 	return errors === 0;
 }
 //#endregion
+//#region src/webhook/errors.ts
+/**
+* Verification error definitions.
+* Use these for documentation, dashboards, and i18n.
+*/
+const VERIFICATION_ERRORS = {
+	INVALID_SIGNATURE_HEADER: {
+		message: "Missing or malformed Primitive-Signature header",
+		suggestion: "Check that you're reading the correct header (Primitive-Signature) and it's being passed correctly from your web framework."
+	},
+	TIMESTAMP_OUT_OF_RANGE: {
+		message: "Timestamp is too old (possible replay attack)",
+		suggestion: "This could indicate a replay attack, network delay, or server clock drift. Check your server's time is synced."
+	},
+	SIGNATURE_MISMATCH: {
+		message: "Signature doesn't match expected value",
+		suggestion: "Verify the webhook secret matches and you're using the raw request body (not re-serialized JSON)."
+	},
+	MISSING_SECRET: {
+		message: "No webhook secret was provided",
+		suggestion: "Pass your webhook secret from the Primitive dashboard. Check that the environment variable is set."
+	}
+};
+/**
+* Payload parsing error definitions.
+* Use these for documentation, dashboards, and i18n.
+*/
+const PAYLOAD_ERRORS = {
+	PAYLOAD_NULL: {
+		message: "Webhook payload is null",
+		suggestion: "Ensure you're passing the parsed JSON body, not null. Check your framework's body parsing middleware."
+	},
+	PAYLOAD_UNDEFINED: {
+		message: "Webhook payload is undefined",
+		suggestion: "The payload was not provided. Make sure you're passing the request body to the handler."
+	},
+	PAYLOAD_WRONG_TYPE: {
+		message: "Webhook payload must be an object",
+		suggestion: "The payload should be a parsed JSON object. Check that you're not passing a string or other primitive."
+	},
+	PAYLOAD_IS_ARRAY: {
+		message: "Webhook payload is an array, expected object",
+		suggestion: "Primitive webhooks are single event objects, not arrays. Check the payload structure."
+	},
+	PAYLOAD_MISSING_EVENT: {
+		message: "Webhook payload missing 'event' field",
+		suggestion: "All webhook payloads must have an 'event' field. This may not be a valid Primitive webhook."
+	},
+	PAYLOAD_UNKNOWN_EVENT: {
+		message: "Unknown webhook event type",
+		suggestion: "This event type is not recognized. You may need to update your SDK or handle unknown events gracefully."
+	},
+	PAYLOAD_EMPTY_BODY: {
+		message: "Request body is empty",
+		suggestion: "The request body was empty. Ensure the webhook is sending data and your framework is parsing it correctly."
+	},
+	JSON_PARSE_FAILED: {
+		message: "Failed to parse JSON body",
+		suggestion: "The request body is not valid JSON. Check the raw body content and Content-Type header."
+	},
+	INVALID_ENCODING: {
+		message: "Invalid body encoding",
+		suggestion: "The request body encoding is not supported. Primitive webhooks use UTF-8 encoded JSON."
+	}
+};
+/**
+* Raw email decode error definitions.
+* Use these for documentation, dashboards, and i18n.
+*/
+const RAW_EMAIL_ERRORS = {
+	NOT_INCLUDED: {
+		message: "Raw email content not included inline",
+		suggestion: "Use the download URL at event.email.content.download.url to fetch the raw email."
+	},
+	INVALID_BASE64: {
+		message: "Raw email content is not valid base64",
+		suggestion: "The raw email data is malformed. Fetch the raw email from the download URL or regenerate the webhook payload."
+	},
+	HASH_MISMATCH: {
+		message: "SHA-256 hash verification failed",
+		suggestion: "The raw email data may be corrupted. Try downloading from the URL instead."
+	}
+};
+/**
+* Base class for all Primitive webhook errors.
+*
+* Catch this to handle any error from the SDK in a single catch block.
+*
+* @example
+* ```typescript
+* import { handleWebhook, PrimitiveWebhookError } from '@primitivedotdev/sdk';
+*
+* try {
+*   const event = handleWebhook({ body, headers, secret });
+* } catch (err) {
+*   if (err instanceof PrimitiveWebhookError) {
+*     console.error(`[${err.code}] ${err.message}`);
+*     return res.status(400).json({ error: err.code });
+*   }
+*   throw err;
+* }
+* ```
+*/
+var PrimitiveWebhookError = class extends Error {
+	/**
+	* Formats the error for logging/display.
+	*/
+	toString() {
+		return `${this.name} [${this.code}]: ${this.message}\n\nSuggestion: ${this.suggestion}`;
+	}
+	/**
+	* Serializes cleanly for structured logging (Datadog, CloudWatch, etc.)
+	*/
+	toJSON() {
+		return {
+			name: this.name,
+			code: this.code,
+			message: this.message,
+			suggestion: this.suggestion
+		};
+	}
+};
+/**
+* Error thrown when webhook signature verification fails.
+*
+* Use the `code` property to programmatically handle specific error cases.
+*/
+var WebhookVerificationError = class extends PrimitiveWebhookError {
+	code;
+	suggestion;
+	constructor(code, message, suggestion) {
+		super(message ?? VERIFICATION_ERRORS[code].message);
+		this.name = "WebhookVerificationError";
+		this.code = code;
+		this.suggestion = suggestion ?? VERIFICATION_ERRORS[code].suggestion;
+	}
+};
+/**
+* Error thrown when webhook payload parsing fails (lightweight parser).
+*
+* Use the `code` property for programmatic handling and monitoring.
+* The `suggestion` property contains actionable guidance for fixing the issue.
+*/
+var WebhookPayloadError = class extends PrimitiveWebhookError {
+	code;
+	suggestion;
+	/** Original error if this wraps another error (e.g., JSON.parse failure) */
+	cause;
+	constructor(code, message, suggestion, cause) {
+		super(message ?? PAYLOAD_ERRORS[code].message);
+		this.name = "WebhookPayloadError";
+		this.code = code;
+		this.suggestion = suggestion ?? PAYLOAD_ERRORS[code].suggestion;
+		this.cause = cause;
+	}
+};
+/**
+* Error thrown when schema validation fails.
+*/
+var WebhookValidationError = class extends PrimitiveWebhookError {
+	code = "SCHEMA_VALIDATION_FAILED";
+	suggestion;
+	/** The specific field path that failed (e.g., "email.headers.from") */
+	field;
+	/** Original schema validation errors for advanced debugging */
+	validationErrors;
+	/** Number of additional validation errors beyond the first */
+	additionalErrorCount;
+	constructor(field, message, suggestion, validationErrors) {
+		super(message);
+		this.name = "WebhookValidationError";
+		this.field = field;
+		this.suggestion = suggestion;
+		this.validationErrors = validationErrors;
+		this.additionalErrorCount = Math.max(0, validationErrors.length - 1);
+	}
+	/**
+	* Formats the error for logging/display.
+	* Includes error count and suggestion.
+	*/
+	toString() {
+		let output = `${this.name} [${this.code}]: ${this.message}`;
+		if (this.additionalErrorCount > 0) output += ` (and ${this.additionalErrorCount} more validation error${this.additionalErrorCount > 1 ? "s" : ""})`;
+		output += `\n\nSuggestion: ${this.suggestion}`;
+		return output;
+	}
+	/**
+	* Serializes cleanly for structured logging (Datadog, CloudWatch, etc.)
+	*/
+	toJSON() {
+		return {
+			name: this.name,
+			code: this.code,
+			field: this.field,
+			message: this.message,
+			suggestion: this.suggestion,
+			additionalErrorCount: this.additionalErrorCount
+		};
+	}
+};
+/**
+* Error thrown when raw email decoding or verification fails.
+*
+* Use the `code` property to determine the failure reason:
+* - `NOT_INCLUDED`: Raw email not inline, must download from URL
+* - `HASH_MISMATCH`: SHA-256 verification failed, content may be corrupted
+*/
+var RawEmailDecodeError = class extends PrimitiveWebhookError {
+	code;
+	suggestion;
+	constructor(code, message) {
+		super(message ?? RAW_EMAIL_ERRORS[code].message);
+		this.name = "RawEmailDecodeError";
+		this.code = code;
+		this.suggestion = RAW_EMAIL_ERRORS[code].suggestion;
+	}
+};
+//#endregion
 //#region src/validation.ts
 const validateSchema = email_received_event_validator_generated_default;
 function toFieldPath(instancePath) {
@@ -8222,121 +8440,6 @@ function safeValidateEmailReceivedEvent(input) {
 	};
 }
 //#endregion
-//#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/events.ts
 /**
 * The five first-party email events (subject = an email).
@@ -8425,2078 +8528,499 @@ function isInteractionX402Event(event) {
 	return eventName(event)?.startsWith("interaction.x402.") ?? false;
 }
 //#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);
+//#region src/webhook/parse-event.ts
+function parseWebhookEvent(input, eventType) {
+	if (input === null) throw new WebhookPayloadError("PAYLOAD_NULL", "Received null instead of webhook payload", "Check that your request body variable is defined.");
+	if (input === void 0) throw new WebhookPayloadError("PAYLOAD_UNDEFINED", "Received undefined instead of webhook payload", "Make sure you're passing the request body to parseWebhookEvent()");
+	if (Array.isArray(input)) throw new WebhookPayloadError("PAYLOAD_IS_ARRAY", "Received array instead of webhook payload object", "Webhook payloads must be objects, not arrays.");
+	if (typeof input !== "object") throw new WebhookPayloadError("PAYLOAD_WRONG_TYPE", `Received ${typeof input} instead of webhook payload object`, "Webhook payloads must be objects.");
+	const obj = input;
+	const resolvedEvent = typeof eventType === "string" && eventType || (typeof obj.event === "string" ? obj.event : void 0);
+	if (!resolvedEvent) throw new WebhookPayloadError("PAYLOAD_MISSING_EVENT", "Missing event discriminator: no X-Webhook-Event header and no 'event' field in payload", "Pass the X-Webhook-Event header (the canonical discriminator) or call handleWebhookEvent, which reads it for you.");
+	switch (resolvedEvent) {
+		case "email.received": return validateEmailReceivedEvent(input);
+		case "payment.settled":
+		case "payment.failed": return {
+			...obj,
+			event: resolvedEvent
+		};
+		default:
+			if (isKnownWebhookEventType(resolvedEvent)) return {
+				...obj,
+				event: resolvedEvent
+			};
+			return {
+				...obj,
+				event: resolvedEvent
+			};
 	}
 }
 //#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");
+//#region src/webhook/received-email.ts
+const REPLY_PREFIX_RE = /^re\s*:/i;
+const FORWARD_PREFIX_RE = /^(fwd?|fw)\s*:/i;
+function normalizeReceivedEmail(event) {
+	const receivedBy = event.email.smtp.rcpt_to[0];
+	if (!receivedBy) throw new Error("email.smtp.rcpt_to must contain at least one recipient");
+	const sender = parseHeaderAddress(event.email.headers.from) ?? {
+		address: event.email.smtp.mail_from.trim().toLowerCase(),
+		name: null
+	};
+	const replyTarget = firstStructuredAddress(event.email.parsed.reply_to) ?? sender;
+	const subject = event.email.headers.subject ?? null;
+	const references = event.email.parsed.references ?? [];
+	const messageId = event.email.headers.message_id ?? null;
+	return {
+		id: event.email.id,
+		eventId: event.id,
+		receivedAt: event.email.received_at,
+		sender,
+		replyTarget,
+		receivedBy,
+		receivedByAll: [...event.email.smtp.rcpt_to],
+		subject,
+		replySubject: buildReplySubject(subject),
+		forwardSubject: buildForwardSubject(subject),
+		text: event.email.parsed.body_text ?? null,
+		thread: {
+			messageId,
+			inReplyTo: event.email.parsed.in_reply_to ?? [],
+			references
+		},
+		attachments: event.email.parsed.attachments ?? [],
+		auth: event.email.auth,
+		analysis: event.email.analysis,
+		raw: event
+	};
 }
-/** 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");
+function buildReplySubject(subject) {
+	const trimmed = subject?.trim() ?? "";
+	if (trimmed.length === 0) return "Re:";
+	return REPLY_PREFIX_RE.test(trimmed) ? trimmed : `Re: ${trimmed}`;
+}
+function buildForwardSubject(subject) {
+	const trimmed = subject?.trim() ?? "";
+	if (trimmed.length === 0) return "Fwd:";
+	return FORWARD_PREFIX_RE.test(trimmed) ? trimmed : `Fwd: ${trimmed}`;
+}
+function formatAddress(address) {
+	return address.name ? `${address.name} <${address.address}>` : address.address;
+}
+function firstStructuredAddress(addresses) {
+	const address = addresses?.[0];
+	if (!address) return null;
 	return {
-		header: `t=${ts},v1=${v1}`,
-		timestamp: ts,
-		v1
+		address: address.address.trim().toLowerCase(),
+		name: address.name ?? null
 	};
 }
-/**
-* 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;
+function parseHeaderAddress(value) {
+	const parsed = parseFromHeaderLoose(value);
+	if (!parsed) return null;
 	return {
-		timestamp,
-		signatures
+		address: parsed.address,
+		name: parsed.name?.trim() || null
 	};
 }
+//#endregion
+//#region src/types.ts
+const EventType = {
+	EmailReceived: "email.received",
+	EmailBounced: "email.bounced",
+	EmailTlsReport: "email.tls_report",
+	EmailDmarcReport: "email.dmarc_report",
+	EmailDmarcFailure: "email.dmarc_failure"
+};
+const ParsedStatus = {
+	Complete: "complete",
+	Failed: "failed"
+};
+const ForwardVerdict = {
+	Legit: "legit",
+	Unknown: "unknown"
+};
+const SpfResult = {
+	Pass: "pass",
+	Fail: "fail",
+	Softfail: "softfail",
+	Neutral: "neutral",
+	None: "none",
+	Temperror: "temperror",
+	Permerror: "permerror"
+};
+const DmarcResult = {
+	Pass: "pass",
+	Fail: "fail",
+	None: "none",
+	Temperror: "temperror",
+	Permerror: "permerror"
+};
+const DmarcPolicy = {
+	Reject: "reject",
+	Quarantine: "quarantine",
+	None: "none"
+};
+const DkimResult = {
+	Pass: "pass",
+	Fail: "fail",
+	Temperror: "temperror",
+	Permerror: "permerror"
+};
+const AuthConfidence = {
+	High: "high",
+	Medium: "medium",
+	Low: "low"
+};
+const AuthVerdict = {
+	Legit: "legit",
+	Suspicious: "suspicious",
+	Unknown: "unknown"
+};
+//#endregion
+//#region src/webhook/auth.ts
 /**
-* Check if a string is valid lowercase hex of expected length
+* Minimum DKIM key size considered acceptable.
+*
+* 1024-bit RSA keys are cryptographically weak by modern standards (NIST
+* deprecated them in 2013), but they remain extremely common in email due to:
+* - DNS TXT record size limits (255 bytes per string)
+* - Legacy infrastructure constraints
+* - Major ESPs like Amazon SES and Resend still use 1024-bit keys
+*
+* We flag keys <1024 bits as weak (these are truly dangerous), while accepting
+* >=1024 bits to avoid false positives against legitimate senders. For maximum
+* security, domain owners should use 2048+ bit keys where possible.
 */
-function isValidHex(str, expectedLength) {
-	return str.length === expectedLength && HEX_PATTERN.test(str);
-}
+const MIN_SECURE_KEY_BITS = 1024;
 /**
-* Verify a webhook signature.
+* Validate email authentication and compute a verdict.
+*
+* This function analyzes SPF, DKIM, and DMARC results to determine
+* whether an email is likely authentic ("legit"), potentially spoofed
+* ("suspicious"), or indeterminate ("unknown").
+*
+* ## Verdict Logic
+*
+* **Legit (high confidence):**
+* - DMARC pass with DKIM alignment (cryptographic proof of authenticity)
+*
+* **Legit (medium confidence):**
+* - DMARC pass with SPF alignment only (no DKIM)
+*   - Note: SPF can break through forwarding, but DMARC pass is still meaningful
+*
+* **Suspicious (high confidence):**
+* - DMARC fail when domain has `reject` or `quarantine` policy
+*   - The domain owner explicitly says to distrust failing emails
+* - SPF explicitly fails (IP not authorized by sender)
+*
+* **Suspicious (low confidence):**
+* - DMARC fail when domain has `none` policy (monitoring mode)
+* - No DMARC record but SPF/DKIM fail
 *
-* Throws `WebhookVerificationError` on failure with a specific error code.
+* **Unknown:**
+* - No DMARC record and no clear pass/fail
+* - Temporary errors during authentication
+* - No authentication data available
+*
+* A `legit` verdict means the email authenticated as its own From
+* domain, not as any particular domain you trust. For authorization
+* decisions, pair the verdict with a domain anchor via
+* {@link isTrustedSender} instead of checking the verdict alone.
+*
+* @param auth - Email authentication results from the webhook
+* @returns Verdict, confidence level, and explanatory reasons
 *
 * @example
 * ```typescript
-* import { verifyWebhookSignature, WebhookVerificationError } from '@primitivedotdev/sdk';
+* const result = validateEmailAuth({
+*   spf: 'pass',
+*   dmarc: 'pass',
+*   dmarcPolicy: 'reject',
+*   dmarcFromDomain: 'example.com',
+*   dmarcSpfAligned: true,
+*   dmarcDkimAligned: true,
+*   dmarcSpfStrict: false,
+*   dmarcDkimStrict: false,
+*   dkimSignatures: [{
+*     domain: 'example.com',
+*     selector: 'default',
+*     result: 'pass',
+*     aligned: true,
+*     keyBits: 2048,
+*     algo: 'rsa-sha256',
+*   }],
+* });
 *
-* 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');
-* }
+* // result.verdict === 'legit'
+* // result.confidence === 'high'
+* // result.reasons === ['DMARC passed with DKIM alignment']
 * ```
 */
-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
-			});
+function validateEmailAuth(auth) {
+	const reasons = [];
+	let verdict;
+	let confidence;
+	if (auth.dmarc === "temperror" || auth.dmarc === "permerror") return {
+		verdict: "unknown",
+		confidence: "low",
+		reasons: [`DMARC verification error (${auth.dmarc})`, "Cannot determine email authenticity due to DNS or policy errors"]
+	};
+	if (auth.spf === "temperror" || auth.spf === "permerror") reasons.push(`SPF verification error (${auth.spf})`);
+	const weakKeySignatures = auth.dkimSignatures.filter((sig) => sig.keyBits != null && sig.keyBits < MIN_SECURE_KEY_BITS);
+	if (weakKeySignatures.length > 0) for (const sig of weakKeySignatures) reasons.push(`Weak DKIM key (${sig.keyBits} bits) for ${sig.domain} - minimum ${MIN_SECURE_KEY_BITS} bits recommended`);
+	if (auth.dmarc === "pass") {
+		const alignedSigs = auth.dkimSignatures.filter((sig) => sig.result === "pass" && sig.aligned);
+		if (auth.dmarcDkimAligned && alignedSigs.length > 0) {
+			const domains = alignedSigs.map((sig) => sig.domain).join(", ");
+			reasons.unshift(`DMARC passed with DKIM alignment (${domains})`);
+			verdict = "legit";
+			confidence = weakKeySignatures.length > 0 ? "medium" : "high";
+			return {
+				verdict,
+				confidence,
+				reasons
+			};
 		}
-	} else {
-		const signedPayloadString = `${timestamp}.${body}`;
-		const hmac = createHmac("sha256", secret);
-		hmac.update(signedPayloadString);
-		expectedHex = hmac.digest("hex");
+		if (auth.dmarcSpfAligned && auth.spf === "pass") {
+			reasons.unshift("DMARC passed with SPF alignment");
+			reasons.push("No aligned DKIM signature (SPF can break through forwarding)");
+			return {
+				verdict: "legit",
+				confidence: "medium",
+				reasons
+			};
+		}
+		reasons.unshift("DMARC passed");
+		return {
+			verdict: "legit",
+			confidence: "medium",
+			reasons
+		};
 	}
-	for (const receivedHex of signatures) {
-		if (!isValidHex(receivedHex, 64)) continue;
-		if (timingSafeEqual(Buffer.from(receivedHex, "hex"), Buffer.from(expectedHex, "hex"))) return true;
+	if (auth.dmarc === "fail") {
+		if (auth.dmarcPolicy === "reject") {
+			reasons.unshift("DMARC failed and domain has reject policy");
+			reasons.push("The sender's domain explicitly rejects emails that fail authentication");
+			return {
+				verdict: "suspicious",
+				confidence: "high",
+				reasons
+			};
+		}
+		if (auth.dmarcPolicy === "quarantine") {
+			reasons.unshift("DMARC failed and domain has quarantine policy");
+			reasons.push("The sender's domain marks failing emails as suspicious");
+			return {
+				verdict: "suspicious",
+				confidence: "high",
+				reasons
+			};
+		}
+		reasons.unshift("DMARC failed (domain is in monitoring mode)");
+		if (auth.spf === "fail") {
+			reasons.push("SPF failed - sending IP not authorized");
+			return {
+				verdict: "suspicious",
+				confidence: "medium",
+				reasons
+			};
+		}
+		return {
+			verdict: "suspicious",
+			confidence: "low",
+			reasons
+		};
 	}
-	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;
+	if (auth.dmarc === "none") {
+		if (auth.spf === "fail") {
+			reasons.push("No DMARC record for sender domain");
+			reasons.push("SPF failed - sending IP not authorized");
+			return {
+				verdict: "suspicious",
+				confidence: "medium",
+				reasons
+			};
+		}
+		const passingDkim = auth.dkimSignatures.filter((sig) => sig.result === "pass");
+		if (passingDkim.length > 0) {
+			const domains = passingDkim.map((sig) => sig.domain).join(", ");
+			reasons.push("No DMARC record for sender domain");
+			reasons.push(`DKIM verified for: ${domains}`);
+			if (auth.spf === "pass") reasons.push("SPF passed");
+			return {
+				verdict: "unknown",
+				confidence: "low",
+				reasons
+			};
+		}
+		if (auth.spf === "pass") {
+			reasons.push("No DMARC record for sender domain");
+			reasons.push("No DKIM signatures present");
+			reasons.push("SPF passed (but SPF alone is weak authentication)");
+			return {
+				verdict: "unknown",
+				confidence: "low",
+				reasons
+			};
+		}
+		reasons.push("No DMARC record for sender domain");
+		reasons.push("No valid authentication found");
+		return {
+			verdict: "unknown",
+			confidence: "low",
+			reasons
+		};
+	}
+	return {
+		verdict: "unknown",
+		confidence: "low",
+		reasons: ["Unable to determine email authenticity"]
+	};
 }
 //#endregion
-//#region src/webhook/standard-webhooks.ts
+//#region src/webhook/trust.ts
 /**
-* Standard Webhooks Verification & Signing
+* Domain-Anchored Sender Trust
 *
-* Implements the Standard Webhooks spec (standardwebhooks.com) for webhook
-* signature verification and payload signing.
+* `validateEmailAuth()` answers "was this email authenticated?" but not
+* "authenticated AS WHOM?". A fully authenticated email from any domain
+* returns a `legit` verdict, so a verdict check alone cannot gate actions
+* on "this really came from our domain". `isTrustedSender()` closes that
+* gap by anchoring the verdict to an expected From domain (and optionally
+* an exact sender address).
 *
-* Header format:
-*   webhook-id: <msg_id>
-*   webhook-timestamp: <unix_seconds>
-*   webhook-signature: v1,<base64_hmac_sha256> [v1,<base64_2> ...]
+* @example
+* ```typescript
+* import { isTrustedSender } from '@primitivedotdev/sdk/api';
 *
-* Signed payload format: "{msg_id}.{timestamp}.{raw_body}"
+* const trust = isTrustedSender(event, { domain: 'example.com' });
+* if (trust.trusted) {
+*   // Authenticated mail whose From domain is example.com
+* } else if (trust.retryable) {
+*   // Transient DNS failure during DMARC evaluation; return a 5xx so
+*   // webhook redelivery retries with fresh DNS.
+* } else {
+*   console.warn('Untrusted email:', trust.reason, trust.auth.reasons);
+* }
+* ```
 *
-* Secrets are base64-encoded, optionally prefixed with "whsec_".
+* @packageDocumentation
 */
-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";
+const SENDER_OPTION_EMAIL_OPTIONS = {
+	allow_ip_domain: true,
+	require_tld: true,
+	allow_display_name: false,
+	allow_utf8_local_part: true
+};
+function untrusted(reason, auth, retryable = false) {
+	return {
+		trusted: false,
+		retryable,
+		reason,
+		auth
+	};
+}
+function hasSubdomainIdentity(auth, domain, dmarcDomain) {
+	if (auth.dmarc !== "pass" || auth.dmarcDkimAligned !== true || !domain.endsWith(`.${dmarcDomain}`)) return false;
+	const managedInbox = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.primitive\.email$/.test(domain);
+	return auth.dkimSignatures.some((signature) => {
+		const signer = typeof signature.domain === "string" ? signature.domain.trim().toLowerCase() : "";
+		const strongKey = signature.algo === "ed25519-sha256" || signature.algo === "rsa-sha256" && typeof signature.keyBits === "number" && signature.keyBits >= 1024;
+		return signature.result === "pass" && signature.aligned === true && strongKey && (signer === domain || managedInbox && dmarcDomain === "primitive.email" && signer === "primitive.email");
+	});
+}
 /**
-* Prepare a Standard Webhooks secret for HMAC computation.
+* Check whether an inbound email is authenticated as an expected domain
+* (and optionally an exact sender address).
 *
-* Strips the "whsec_" prefix if present, then base64-decodes the remainder
-* to produce the raw HMAC key bytes.
+* `trusted` is true only when ALL of the following hold:
 *
-* @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.
+* 1. `validateEmailAuth(event.email.auth)` returns a `legit` verdict.
+* 2. The reported DMARC domain equals `options.domain`, or is its parent
+*    and passing, aligned DKIM uses the exact expected domain.
+*    A direct child of primitive.email may instead use primitive.email
+*    as its signer, trusting Primitive to authorize the sending identity.
+* 3. The From header strict-parses to exactly one valid address whose
+*    domain equals `options.domain`.
+* 4. When `options.sender` is given, the parsed From address equals it
+*    exactly (case-insensitive).
 *
-* The header format is space-delimited entries like "v1,<base64>".
-* Only v1 entries are returned.
+* ## Why the extra checks beyond the verdict
 *
-* @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.
+* The verdict alone says an email was authenticated, not which domain
+* it was authenticated as: a fully authenticated email from an
+* attacker-controlled domain is `legit`. Anchoring `dmarcFromDomain`
+* and requiring DKIM proof for subdomain exceptions closes that. A shared
+* organizational domain or SPF-only pass never suffices for the exception.
+* The qualifying signature must use RSA-SHA256 with at least 1024 reported
+* key bits, or Ed25519-SHA256. Unknown algorithms or RSA sizes fail closed.
+* The strict From parse defends the remaining gaps:
 *
-* @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.
+* - Naively regexing the raw From header is unsafe. A header like
+*   `From: "trusted@example.com" <x@evil.com>` plants an allowlisted
+*   address in the display name while DMARC evaluates (and passes for)
+*   `evil.com`. The strict parser extracts only the real addr-spec and
+*   rejects multi-address and group forms outright.
+* - `normalizeReceivedEmail().sender` is NOT a safe anchor for
+*   authorization: it uses a lenient parser and falls back to the SMTP
+*   envelope sender (`smtp.mail_from`), which the sender fully
+*   controls. The same goes for Reply-To (`replyTarget`). This function
+*   never consults either.
+* - An `unknown` verdict is not one thing: a DMARC temperror is
+*   transient (surfaced as `retryable: true`, respond 5xx and let
+*   webhook redelivery retry), while "no DMARC record" is permanent
+*   for the email and surfaced as non-retryable.
+*
+* Never throws for malformed event content; malformed input yields an
+* untrusted result with a reason. Throws `TypeError` only for invalid
+* `options` (programmer error).
 *
-* Throws `WebhookVerificationError` on failure with a specific error code.
+* @param event - The verified `email.received` webhook event
+* @param options - Expected domain and optional exact sender
+* @returns Trust decision with a stable reason code and the underlying
+*   auth result
 */
-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;
+function isTrustedSender(event, options) {
+	const { domain, sender } = normalizeOptions(options);
+	const auth = event?.email?.auth;
+	if (auth === null || typeof auth !== "object" || !Array.isArray(auth.dkimSignatures)) return untrusted("auth-missing", {
+		verdict: "unknown",
+		confidence: "low",
+		reasons: ["Missing or malformed email.auth on event"]
+	});
+	const authResult = validateEmailAuth(auth);
+	if (authResult.verdict === "suspicious") return untrusted("auth-suspicious", authResult);
+	if (authResult.verdict === "unknown") {
+		if (auth.dmarc === "temperror") return untrusted("dmarc-temperror", authResult, true);
+		return untrusted("auth-unknown", authResult);
 	}
-	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).");
+	const dmarcFromDomain = typeof auth.dmarcFromDomain === "string" ? auth.dmarcFromDomain.trim().toLowerCase() : "";
+	if (dmarcFromDomain === "" || dmarcFromDomain !== domain && !hasSubdomainIdentity(auth, domain, dmarcFromDomain)) return untrusted("dmarc-domain-mismatch", authResult);
+	const parsed = parseFromHeader(event.email?.headers?.from);
+	if (!parsed.ok) return untrusted(parsed.reason === "multiple_addresses" ? "from-header-multiple-addresses" : "from-header-invalid", authResult);
+	const fromAddress = parsed.value.address;
+	if (fromAddress.slice(fromAddress.lastIndexOf("@") + 1) !== domain) return untrusted("from-domain-mismatch", authResult);
+	if (sender !== void 0 && fromAddress !== sender) return untrusted("sender-mismatch", authResult);
+	return {
+		trusted: true,
+		retryable: false,
+		reason: "trusted",
+		auth: authResult
+	};
 }
-//#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}=)?$/;
-/**
-* Parse a webhook payload, returning typed events for known types
-* and UnknownEvent for future event types.
-*
-* This provides forward-compatibility: when Primitive adds new event types,
-* your code won't break - you'll receive an UnknownEvent that you can
-* handle or ignore.
-*
-* Known event types are validated against the canonical schema. Unknown
-* event types are returned as-is for forward compatibility.
-*
-* For most use cases, prefer `handleWebhook()` which also verifies the
-* signature before parsing the payload.
-*
-* @param input - The parsed JSON payload
-* @returns Typed event for known types, UnknownEvent for unknown types
-* @throws WebhookPayloadError if the input is not a valid webhook structure
-* @throws WebhookValidationError if a known event fails schema validation
-*
-* @example
-* ```typescript
-* import { parseWebhookEvent } from '@primitivedotdev/sdk';
-*
-* const event = parseWebhookEvent(JSON.parse(rawBody));
-*
-* if (event.event === "email.received") {
-*   // TypeScript knows this is EmailReceivedEvent
-*   console.log(event.email.headers.subject);
-* } else {
-*   // Handle or log unknown event types
-*   console.log("Unknown event:", event.event);
-* }
-* ```
-*/
-function parseWebhookEvent(input, eventType) {
-	if (input === null) throw new WebhookPayloadError("PAYLOAD_NULL", "Received null instead of webhook payload", "Check that your request body variable is defined.");
-	if (input === void 0) throw new WebhookPayloadError("PAYLOAD_UNDEFINED", "Received undefined instead of webhook payload", "Make sure you're passing the request body to parseWebhookEvent()");
-	if (Array.isArray(input)) throw new WebhookPayloadError("PAYLOAD_IS_ARRAY", "Received array instead of webhook payload object", "Webhook payloads must be objects, not arrays.");
-	if (typeof input !== "object") throw new WebhookPayloadError("PAYLOAD_WRONG_TYPE", `Received ${typeof input} instead of webhook payload object`, "Webhook payloads must be objects.");
-	const obj = input;
-	const resolvedEvent = typeof eventType === "string" && eventType || (typeof obj.event === "string" ? obj.event : void 0);
-	if (!resolvedEvent) throw new WebhookPayloadError("PAYLOAD_MISSING_EVENT", "Missing event discriminator: no X-Webhook-Event header and no 'event' field in payload", "Pass the X-Webhook-Event header (the canonical discriminator) or call handleWebhookEvent, which reads it for you.");
-	switch (resolvedEvent) {
-		case "email.received": return validateEmailReceivedEvent(input);
-		case "payment.settled":
-		case "payment.failed": return {
-			...obj,
-			event: resolvedEvent
-		};
-		default:
-			if (isKnownWebhookEventType(resolvedEvent)) return {
-				...obj,
-				event: resolvedEvent
-			};
-			return {
-				...obj,
-				event: resolvedEvent
-			};
-	}
-}
-/**
-* 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() {
+function normalizeOptions(options) {
+	if (typeof options?.domain !== "string") throw new TypeError("options.domain is required");
+	const domain = options.domain.trim().toLowerCase();
+	if (domain.length === 0) throw new TypeError("options.domain must be a non-empty domain name");
+	if (domain.includes("@") || /\s/.test(domain)) throw new TypeError("options.domain must be a bare domain name without @ or whitespace");
+	if (options.sender === void 0) return { domain };
+	if (typeof options.sender !== "string") throw new TypeError("options.sender must be a string when provided");
+	const sender = options.sender.trim().toLowerCase();
+	if (!isEmail(sender, SENDER_OPTION_EMAIL_OPTIONS)) throw new TypeError("options.sender must be a single bare email address (user@example.com)");
 	return {
-		[PRIMITIVE_CONFIRMED_HEADER]: "true",
-		[LEGACY_CONFIRMED_HEADER]: "true"
+		domain,
+		sender
 	};
 }
-/**
-* 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 { isEmailReceivedEvent as A, PRIMITIVE_SIGNATURE_HEADER as C, INTERACTION_EVENT_TYPES as D, EMAIL_EVENT_TYPES as E, isPaymentSettledEvent as F, generateDownloadToken as I, verifyDownloadToken as L, isKnownWebhookEventType as M, isPaymentEvent as N, PAYMENT_EVENT_TYPES as O, isPaymentFailedEvent as P, safeValidateEmailReceivedEvent as R, PRIMITIVE_CONFIRMED_HEADER as S, verifyWebhookSignature as T, STANDARD_WEBHOOK_TIMESTAMP_HEADER as _, getEventHeader as a, LEGACY_CONFIRMED_HEADER as b, isDownloadExpired as c, receive as d, verifyRawEmailDownload as f, STANDARD_WEBHOOK_SIGNATURE_HEADER as g, STANDARD_WEBHOOK_ID_HEADER as h, getDownloadTimeRemaining as i, isInteractionX402Event as j, WEBHOOK_EVENT_TYPES as k, isRawIncluded as l, emailReceivedEventJsonSchema as m, confirmedHeaders as n, handleWebhook as o, WEBHOOK_VERSION as p, decodeRawEmail as r, handleWebhookEvent as s, WEBHOOK_EVENT_HEADER as t, parseWebhookEvent as u, signStandardWebhooksPayload as v, signWebhookPayload as w, LEGACY_SIGNATURE_HEADER as x, verifyStandardWebhooksSignature as y, validateEmailReceivedEvent as z };
+export { PAYLOAD_ERRORS as A, isInteractionX402Event as C, isPaymentSettledEvent as D, isPaymentFailedEvent as E, WebhookPayloadError as F, WebhookValidationError as I, WebhookVerificationError as L, RAW_EMAIL_ERRORS as M, RawEmailDecodeError as N, safeValidateEmailReceivedEvent as O, VERIFICATION_ERRORS as P, isEmailReceivedEvent as S, isPaymentEvent as T, parseWebhookEvent as _, DkimResult as a, PAYMENT_EVENT_TYPES as b, EventType as c, SpfResult as d, buildForwardSubject as f, parseHeaderAddress as g, normalizeReceivedEmail as h, AuthVerdict as i, PrimitiveWebhookError as j, validateEmailReceivedEvent as k, ForwardVerdict as l, formatAddress as m, validateEmailAuth as n, DmarcPolicy as o, buildReplySubject as p, AuthConfidence as r, DmarcResult as s, isTrustedSender as t, ParsedStatus as u, EMAIL_EVENT_TYPES as v, isKnownWebhookEventType as w, WEBHOOK_EVENT_TYPES as x, INTERACTION_EVENT_TYPES as y };