@primitivedotdev/sdk 1.26.0 → 1.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primitivedotdev/sdk",
-  "version": "1.26.0",
+  "version": "1.27.0",
   "description": "Official Primitive Node.js SDK: webhook, api, openapi, contract, and parser runtime modules.",
   "type": "module",
   "module": "./dist/index.js",
@@ -71,8 +71,8 @@
     "test:coverage": "vitest run --coverage",
     "test:watch": "vitest",
     "typecheck": "pnpm generate && tsc --noEmit -p tsconfig.typecheck.json",
-    "lint": "biome check --error-on-warnings src/index.ts src/validation.ts src/types.ts src/webhook src/contract src/parser src/api/index.ts src/x402 src/openapi/index.ts src/payloads src/interactions tests/",
-    "lint:fix": "biome check --write --error-on-warnings src/index.ts src/validation.ts src/types.ts src/webhook src/contract src/parser src/api/index.ts src/x402 src/openapi/index.ts src/payloads src/interactions tests/",
+    "lint": "biome check --error-on-warnings src/index.ts src/validation.ts src/types.ts src/webhook src/contract src/parser src/api/index.ts src/api/events.ts src/api/event-transport.ts src/x402 src/openapi/index.ts src/payloads src/interactions tests/",
+    "lint:fix": "biome check --write --error-on-warnings src/index.ts src/validation.ts src/types.ts src/webhook src/contract src/parser src/api/index.ts src/api/events.ts src/api/event-transport.ts src/x402 src/openapi/index.ts src/payloads src/interactions tests/",
     "prepublishOnly": "pnpm build"
   },
   "keywords": [

package/dist/errors-Bo0f7eId.js

@@ -1,673 +0,0 @@
-import { n as parseFromHeaderLoose, t as parseFromHeader } from "./address-parser-C2JJzLdA.js";
-import isEmail from "validator/lib/isEmail.js";
-//#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
-	};
-}
-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 {
-		address: address.address.trim().toLowerCase(),
-		name: address.name ?? null
-	};
-}
-function parseHeaderAddress(value) {
-	const parsed = parseFromHeaderLoose(value);
-	if (!parsed) return null;
-	return {
-		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
-/**
-* 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.
-*/
-const MIN_SECURE_KEY_BITS = 1024;
-/**
-* 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
-*
-* **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
-* 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',
-*   }],
-* });
-*
-* // result.verdict === 'legit'
-* // result.confidence === 'high'
-* // result.reasons === ['DMARC passed with DKIM alignment']
-* ```
-*/
-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
-			};
-		}
-		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
-		};
-	}
-	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
-		};
-	}
-	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/trust.ts
-/**
-* Domain-Anchored Sender Trust
-*
-* `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).
-*
-* @example
-* ```typescript
-* import { isTrustedSender } from '@primitivedotdev/sdk/api';
-*
-* 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);
-* }
-* ```
-*
-* @packageDocumentation
-*/
-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
-	};
-}
-/**
-* Check whether an inbound email is authenticated as an expected domain
-* (and optionally an exact sender address).
-*
-* `trusted` is true only when ALL of the following hold:
-*
-* 1. `validateEmailAuth(event.email.auth)` returns a `legit` verdict.
-* 2. `event.email.auth.dmarcFromDomain` (the domain the server's DMARC
-*    evaluation ran against) equals `options.domain`.
-* 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).
-*
-* ## Why the extra checks beyond the verdict
-*
-* 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`
-* closes that. The strict From parse defends the remaining gaps:
-*
-* - 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).
-*
-* @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 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);
-	}
-	const dmarcFromDomain = typeof auth.dmarcFromDomain === "string" ? auth.dmarcFromDomain.trim().toLowerCase() : "";
-	if (dmarcFromDomain === "" || dmarcFromDomain !== domain) 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
-	};
-}
-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 {
-		domain,
-		sender
-	};
-}
-//#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
-export { normalizeReceivedEmail as C, formatAddress as S, ForwardVerdict as _, VERIFICATION_ERRORS as a, buildForwardSubject as b, WebhookVerificationError as c, AuthConfidence as d, AuthVerdict as f, EventType as g, DmarcResult as h, RawEmailDecodeError as i, isTrustedSender as l, DmarcPolicy as m, PrimitiveWebhookError as n, WebhookPayloadError as o, DkimResult as p, RAW_EMAIL_ERRORS as r, WebhookValidationError as s, PAYLOAD_ERRORS as t, validateEmailAuth as u, ParsedStatus as v, parseHeaderAddress as w, buildReplySubject as x, SpfResult as y };