@primitivedotdev/sdk 0.2.4 → 0.4.0

package/dist/parser/index.js

@@ -1,10 +1,26 @@
 import { createHash } from "node:crypto";
-import { PassThrough } from "node:stream";
-import archiver from "archiver";
+import { createGzip } from "node:zlib";
+import { pack } from "tar-stream";
 import { simpleParser } from "mailparser";
 import DOMPurify from "isomorphic-dompurify";
 
 //#region src/parser/attachment-bundler.ts
+function appendTarEntry(archive, name, content) {
+	return new Promise((resolve, reject) => {
+		archive.entry({
+			mode: 420,
+			name,
+			size: content.length,
+			type: "file"
+		}, content, (error) => {
+			if (error) {
+				reject(error);
+				return;
+			}
+			resolve();
+		});
+	});
+}
 /**
 * Bundle downloadable attachments into a tar.gz archive.
 *
@@ -18,30 +34,28 @@ import DOMPurify from "isomorphic-dompurify";
 async function bundleAttachments(attachments) {
 	const downloadable = attachments.filter((att) => att.isDownloadable);
 	if (downloadable.length === 0) return null;
-	const archive = archiver("tar", {
-		gzip: true,
-		gzipOptions: { level: 6 }
-	});
+	const archive = pack();
+	const gzip = createGzip({ level: 6 });
 	const chunks = [];
-	const passThrough = new PassThrough();
 	let totalAttachmentBytes = 0;
 	const tarGzBuffer = await new Promise((resolve, reject) => {
 		let settled = false;
 		const cleanup = () => {
 			archive.off("error", rejectArchive);
-			archive.off("warning", rejectArchive);
-			passThrough.off("data", handleData);
-			passThrough.off("end", handleEnd);
-			passThrough.off("error", rejectArchive);
+			gzip.off("data", handleData);
+			gzip.off("end", handleEnd);
+			gzip.off("error", rejectArchive);
 		};
 		const rejectArchive = (error) => {
 			if (settled) return;
 			settled = true;
 			cleanup();
+			archive.destroy();
+			gzip.destroy();
 			reject(error);
 		};
 		const handleData = (chunk) => {
-			chunks.push(chunk);
+			chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
 		};
 		const handleEnd = () => {
 			if (settled) return;
@@ -50,20 +64,21 @@ async function bundleAttachments(attachments) {
 			resolve(Buffer.concat(chunks));
 		};
 		archive.on("error", rejectArchive);
-		archive.on("warning", rejectArchive);
-		passThrough.on("data", handleData);
-		passThrough.on("end", handleEnd);
-		passThrough.on("error", rejectArchive);
-		archive.pipe(passThrough);
-		try {
-			for (const att of downloadable) {
-				archive.append(att.content, { name: att.tarPath });
-				totalAttachmentBytes += att.sizeBytes;
+		gzip.on("data", handleData);
+		gzip.on("end", handleEnd);
+		gzip.on("error", rejectArchive);
+		archive.pipe(gzip);
+		(async () => {
+			try {
+				for (const att of downloadable) {
+					await appendTarEntry(archive, att.tarPath, att.content);
+					totalAttachmentBytes += att.sizeBytes;
+				}
+				archive.finalize();
+			} catch (error) {
+				rejectArchive(error instanceof Error ? error : new Error(String(error)));
 			}
-			archive.finalize().catch(rejectArchive);
-		} catch (error) {
-			rejectArchive(error instanceof Error ? error : new Error(String(error)));
-		}
+		})();
 	});
 	const sha256 = createHash("sha256").update(tarGzBuffer).digest("hex");
 	return {

package/dist/{types-B5IgP-Zx.d.ts → types-C3ms4R0d.d.ts}

@@ -399,6 +399,8 @@ interface ParsedError$1 {
 interface EmailAnalysis$1 {
   /**
    * SpamAssassin analysis results.
+   *
+   * Optional. 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.
    */
   spamassassin?: {
     /**
@@ -410,6 +412,8 @@ interface EmailAnalysis$1 {
 }
 /**
  * Forward detection and analysis results.
+ *
+ * Optional. Present when the email was processed by a forward-detection pipeline (always present in Primitive's managed service). When absent, forward detection was not performed on this email.
  */
 interface ForwardAnalysis$1 {
   /**

package/dist/webhook/index.d.ts

@@ -1,3 +1,3 @@
-import { AuthConfidence$1 as AuthConfidence, AuthVerdict$1 as AuthVerdict, DkimResult$1 as DkimResult, DkimSignature, DmarcPolicy$1 as DmarcPolicy, DmarcResult$1 as DmarcResult, EmailAddress, EmailAnalysis, EmailAuth, EmailReceivedEvent, EventType$1 as EventType, ForwardAnalysis, ForwardOriginalSender, ForwardResult, ForwardResultAttachmentAnalyzed, ForwardResultAttachmentSkipped, ForwardResultInline, ForwardVerdict$1 as ForwardVerdict, ForwardVerification, KnownWebhookEvent, ParsedData, ParsedDataComplete, ParsedDataFailed, ParsedError, ParsedStatus$1 as ParsedStatus, RawContent, RawContentDownloadOnly, RawContentInline, SpfResult$1 as SpfResult, UnknownEvent, ValidateEmailAuthResult, WebhookAttachment, WebhookEvent } from "../types-B5IgP-Zx.js";
-import { DecodeRawEmailOptions, HandleWebhookOptions, LEGACY_CONFIRMED_HEADER$1 as LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER$1 as LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS$1 as PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER$1 as PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER$1 as PRIMITIVE_SIGNATURE_HEADER, PrimitiveWebhookError$1 as PrimitiveWebhookError, RAW_EMAIL_ERRORS$1 as RAW_EMAIL_ERRORS, RawEmailDecodeError$1 as RawEmailDecodeError, RawEmailDecodeErrorCode, SignResult, VERIFICATION_ERRORS$1 as VERIFICATION_ERRORS, VerifyOptions, WEBHOOK_VERSION$1 as WEBHOOK_VERSION, WebhookErrorCode, WebhookHeaders, WebhookPayloadError$1 as WebhookPayloadError, WebhookPayloadErrorCode, WebhookValidationError$1 as WebhookValidationError, WebhookValidationErrorCode, WebhookVerificationError$1 as WebhookVerificationError, WebhookVerificationErrorCode, confirmedHeaders$1 as confirmedHeaders, decodeRawEmail$1 as decodeRawEmail, emailReceivedEventJsonSchema$1 as emailReceivedEventJsonSchema, getDownloadTimeRemaining$1 as getDownloadTimeRemaining, handleWebhook$1 as handleWebhook, isDownloadExpired$1 as isDownloadExpired, isEmailReceivedEvent$1 as isEmailReceivedEvent, isRawIncluded$1 as isRawIncluded, parseWebhookEvent$1 as parseWebhookEvent, safeValidateEmailReceivedEvent$1 as safeValidateEmailReceivedEvent, signWebhookPayload$1 as signWebhookPayload, validateEmailAuth$1 as validateEmailAuth, validateEmailReceivedEvent$1 as validateEmailReceivedEvent, verifyRawEmailDownload$1 as verifyRawEmailDownload, verifyWebhookSignature$1 as verifyWebhookSignature } from "../index-BdRIHaXz.js";
-export { AuthConfidence, AuthVerdict, DecodeRawEmailOptions, DkimResult, DkimSignature, DmarcPolicy, DmarcResult, EmailAddress, EmailAnalysis, EmailAuth, EmailReceivedEvent, EventType, ForwardAnalysis, ForwardOriginalSender, ForwardResult, ForwardResultAttachmentAnalyzed, ForwardResultAttachmentSkipped, ForwardResultInline, ForwardVerdict, ForwardVerification, HandleWebhookOptions, KnownWebhookEvent, LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER, ParsedData, ParsedDataComplete, ParsedDataFailed, ParsedError, ParsedStatus, PrimitiveWebhookError, RAW_EMAIL_ERRORS, RawContent, RawContentDownloadOnly, RawContentInline, RawEmailDecodeError, RawEmailDecodeErrorCode, SignResult, SpfResult, UnknownEvent, VERIFICATION_ERRORS, ValidateEmailAuthResult, VerifyOptions, WEBHOOK_VERSION, WebhookAttachment, WebhookErrorCode, WebhookEvent, WebhookHeaders, WebhookPayloadError, WebhookPayloadErrorCode, WebhookValidationError, WebhookValidationErrorCode, WebhookVerificationError, WebhookVerificationErrorCode, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, parseWebhookEvent, safeValidateEmailReceivedEvent, signWebhookPayload, validateEmailAuth, validateEmailReceivedEvent, verifyRawEmailDownload, verifyWebhookSignature };
+import { AuthConfidence$1 as AuthConfidence, AuthVerdict$1 as AuthVerdict, DkimResult$1 as DkimResult, DkimSignature, DmarcPolicy$1 as DmarcPolicy, DmarcResult$1 as DmarcResult, EmailAddress, EmailAnalysis, EmailAuth, EmailReceivedEvent, EventType$1 as EventType, ForwardAnalysis, ForwardOriginalSender, ForwardResult, ForwardResultAttachmentAnalyzed, ForwardResultAttachmentSkipped, ForwardResultInline, ForwardVerdict$1 as ForwardVerdict, ForwardVerification, KnownWebhookEvent, ParsedData, ParsedDataComplete, ParsedDataFailed, ParsedError, ParsedStatus$1 as ParsedStatus, RawContent, RawContentDownloadOnly, RawContentInline, SpfResult$1 as SpfResult, UnknownEvent, ValidateEmailAuthResult, WebhookAttachment, WebhookEvent } from "../types-C3ms4R0d.js";
+import { DecodeRawEmailOptions, HandleWebhookOptions, LEGACY_CONFIRMED_HEADER$1 as LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER$1 as LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS$1 as PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER$1 as PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER$1 as PRIMITIVE_SIGNATURE_HEADER, PrimitiveWebhookError$1 as PrimitiveWebhookError, RAW_EMAIL_ERRORS$1 as RAW_EMAIL_ERRORS, RawEmailDecodeError$1 as RawEmailDecodeError, RawEmailDecodeErrorCode, STANDARD_WEBHOOK_ID_HEADER$1 as STANDARD_WEBHOOK_ID_HEADER, STANDARD_WEBHOOK_SIGNATURE_HEADER$1 as STANDARD_WEBHOOK_SIGNATURE_HEADER, STANDARD_WEBHOOK_TIMESTAMP_HEADER$1 as STANDARD_WEBHOOK_TIMESTAMP_HEADER, SignResult, StandardWebhooksSignResult, StandardWebhooksVerifyOptions, VERIFICATION_ERRORS$1 as VERIFICATION_ERRORS, VerifyOptions, WEBHOOK_VERSION$1 as WEBHOOK_VERSION, WebhookErrorCode, WebhookHeaders, WebhookPayloadError$1 as WebhookPayloadError, WebhookPayloadErrorCode, WebhookValidationError$1 as WebhookValidationError, WebhookValidationErrorCode, WebhookVerificationError$1 as WebhookVerificationError, WebhookVerificationErrorCode, confirmedHeaders$1 as confirmedHeaders, decodeRawEmail$1 as decodeRawEmail, emailReceivedEventJsonSchema$1 as emailReceivedEventJsonSchema, getDownloadTimeRemaining$1 as getDownloadTimeRemaining, handleWebhook$1 as handleWebhook, isDownloadExpired$1 as isDownloadExpired, isEmailReceivedEvent$1 as isEmailReceivedEvent, isRawIncluded$1 as isRawIncluded, parseWebhookEvent$1 as parseWebhookEvent, safeValidateEmailReceivedEvent$1 as safeValidateEmailReceivedEvent, signStandardWebhooksPayload$1 as signStandardWebhooksPayload, signWebhookPayload$1 as signWebhookPayload, validateEmailAuth$1 as validateEmailAuth, validateEmailReceivedEvent$1 as validateEmailReceivedEvent, verifyRawEmailDownload$1 as verifyRawEmailDownload, verifyStandardWebhooksSignature$1 as verifyStandardWebhooksSignature, verifyWebhookSignature$1 as verifyWebhookSignature } from "../index-D2OuDGVz.js";
+export { AuthConfidence, AuthVerdict, DecodeRawEmailOptions, DkimResult, DkimSignature, DmarcPolicy, DmarcResult, EmailAddress, EmailAnalysis, EmailAuth, EmailReceivedEvent, EventType, ForwardAnalysis, ForwardOriginalSender, ForwardResult, ForwardResultAttachmentAnalyzed, ForwardResultAttachmentSkipped, ForwardResultInline, ForwardVerdict, ForwardVerification, HandleWebhookOptions, KnownWebhookEvent, LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER, ParsedData, ParsedDataComplete, ParsedDataFailed, ParsedError, ParsedStatus, PrimitiveWebhookError, RAW_EMAIL_ERRORS, RawContent, RawContentDownloadOnly, RawContentInline, RawEmailDecodeError, RawEmailDecodeErrorCode, STANDARD_WEBHOOK_ID_HEADER, STANDARD_WEBHOOK_SIGNATURE_HEADER, STANDARD_WEBHOOK_TIMESTAMP_HEADER, SignResult, SpfResult, StandardWebhooksSignResult, StandardWebhooksVerifyOptions, UnknownEvent, VERIFICATION_ERRORS, ValidateEmailAuthResult, VerifyOptions, WEBHOOK_VERSION, WebhookAttachment, WebhookErrorCode, WebhookEvent, WebhookHeaders, WebhookPayloadError, WebhookPayloadErrorCode, WebhookValidationError, WebhookValidationErrorCode, WebhookVerificationError, WebhookVerificationErrorCode, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, parseWebhookEvent, safeValidateEmailReceivedEvent, signStandardWebhooksPayload, signWebhookPayload, validateEmailAuth, validateEmailReceivedEvent, verifyRawEmailDownload, verifyStandardWebhooksSignature, verifyWebhookSignature };

package/dist/webhook/index.js

@@ -1,3 +1,3 @@
-import { AuthConfidence, AuthVerdict, DkimResult, DmarcPolicy, DmarcResult, EventType, ForwardVerdict, LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER, ParsedStatus, PrimitiveWebhookError, RAW_EMAIL_ERRORS, RawEmailDecodeError, SpfResult, VERIFICATION_ERRORS, WEBHOOK_VERSION, WebhookPayloadError, WebhookValidationError, WebhookVerificationError, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, parseWebhookEvent, safeValidateEmailReceivedEvent, signWebhookPayload, validateEmailAuth, validateEmailReceivedEvent, verifyRawEmailDownload, verifyWebhookSignature } from "../webhook-Be2vM0F-.js";
+import { AuthConfidence, AuthVerdict, DkimResult, DmarcPolicy, DmarcResult, EventType, ForwardVerdict, LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER, ParsedStatus, PrimitiveWebhookError, RAW_EMAIL_ERRORS, RawEmailDecodeError, STANDARD_WEBHOOK_ID_HEADER, STANDARD_WEBHOOK_SIGNATURE_HEADER, STANDARD_WEBHOOK_TIMESTAMP_HEADER, SpfResult, VERIFICATION_ERRORS, WEBHOOK_VERSION, WebhookPayloadError, WebhookValidationError, WebhookVerificationError, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, parseWebhookEvent, safeValidateEmailReceivedEvent, signStandardWebhooksPayload, signWebhookPayload, validateEmailAuth, validateEmailReceivedEvent, verifyRawEmailDownload, verifyStandardWebhooksSignature, verifyWebhookSignature } from "../webhook-uSco6pyX.js";
 
-export { AuthConfidence, AuthVerdict, DkimResult, DmarcPolicy, DmarcResult, EventType, ForwardVerdict, LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER, ParsedStatus, PrimitiveWebhookError, RAW_EMAIL_ERRORS, RawEmailDecodeError, SpfResult, VERIFICATION_ERRORS, WEBHOOK_VERSION, WebhookPayloadError, WebhookValidationError, WebhookVerificationError, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, parseWebhookEvent, safeValidateEmailReceivedEvent, signWebhookPayload, validateEmailAuth, validateEmailReceivedEvent, verifyRawEmailDownload, verifyWebhookSignature };
+export { AuthConfidence, AuthVerdict, DkimResult, DmarcPolicy, DmarcResult, EventType, ForwardVerdict, LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER, ParsedStatus, PrimitiveWebhookError, RAW_EMAIL_ERRORS, RawEmailDecodeError, STANDARD_WEBHOOK_ID_HEADER, STANDARD_WEBHOOK_SIGNATURE_HEADER, STANDARD_WEBHOOK_TIMESTAMP_HEADER, SpfResult, VERIFICATION_ERRORS, WEBHOOK_VERSION, WebhookPayloadError, WebhookValidationError, WebhookVerificationError, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, parseWebhookEvent, safeValidateEmailReceivedEvent, signStandardWebhooksPayload, signWebhookPayload, validateEmailAuth, validateEmailReceivedEvent, verifyRawEmailDownload, verifyStandardWebhooksSignature, verifyWebhookSignature };

package/dist/{webhook-Be2vM0F-.js → webhook-uSco6pyX.js}

@@ -6090,9 +6090,9 @@ 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 = 5 * 60;
+const DEFAULT_TOLERANCE_SECONDS$1 = 5 * 60;
 /** Future clock skew tolerance (1 minute) */
-const FUTURE_TOLERANCE_SECONDS = 60;
+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 */
@@ -6186,7 +6186,7 @@ function isValidHex(str, expectedLength) {
 * ```
 */
 function verifyWebhookSignature(opts) {
-	const { rawBody, signatureHeader, secret, toleranceSeconds = DEFAULT_TOLERANCE_SECONDS, nowSeconds } = 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}");
@@ -6194,7 +6194,7 @@ function verifyWebhookSignature(opts) {
 	const now = nowSeconds ?? Math.floor(Date.now() / 1e3);
 	const age = now - 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.");
+	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)) {
@@ -6239,6 +6239,111 @@ function detectReserializedBody(body) {
 	return null;
 }
 
+//#endregion
+//#region src/webhook/standard-webhooks.ts
+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 = 5 * 60;
+/** Future clock skew tolerance (1 minute) */
+const FUTURE_TOLERANCE_SECONDS = 60;
+/** Standard Webhooks header names */
+const STANDARD_WEBHOOK_ID_HEADER = "webhook-id";
+const STANDARD_WEBHOOK_TIMESTAMP_HEADER = "webhook-timestamp";
+const STANDARD_WEBHOOK_SIGNATURE_HEADER = "webhook-signature";
+/**
+* Prepare a Standard Webhooks secret for HMAC computation.
+*
+* Strips the "whsec_" prefix if present, then base64-decodes the remainder
+* to produce the raw HMAC key bytes.
+*
+* @internal
+*/
+function prepareStandardWebhooksSecret(secret) {
+	if (Buffer.isBuffer(secret)) {
+		if (secret.length === 0) throw new WebhookVerificationError("MISSING_SECRET", "Webhook secret is required but was empty or not provided");
+		return secret;
+	}
+	let keyStr = secret;
+	if (keyStr.startsWith(WHSEC_PREFIX)) keyStr = keyStr.slice(WHSEC_PREFIX.length);
+	if (!keyStr || !BASE64_PATTERN$1.test(keyStr)) throw new WebhookVerificationError("MISSING_SECRET", "Standard Webhooks secret must be base64-encoded (optionally with whsec_ prefix)");
+	const decoded = Buffer.from(keyStr, "base64");
+	if (decoded.length === 0) throw new WebhookVerificationError("MISSING_SECRET", "Webhook secret is required but was empty or not provided");
+	return decoded;
+}
+/**
+* Parse the webhook-signature header into base64 signature strings.
+*
+* The header format is space-delimited entries like "v1,<base64>".
+* Only v1 entries are returned.
+*
+* @internal
+*/
+function parseStandardWebhooksSignatures(header) {
+	if (!header) return [];
+	const signatures = [];
+	for (const entry of header.split(" ")) {
+		const trimmed = entry.trim();
+		if (!trimmed) continue;
+		const commaIdx = trimmed.indexOf(",");
+		if (commaIdx === -1) continue;
+		const version = trimmed.slice(0, commaIdx);
+		const sig = trimmed.slice(commaIdx + 1);
+		if (version === "v1" && sig) signatures.push(sig);
+	}
+	return signatures;
+}
+/**
+* Sign a webhook payload using the Standard Webhooks format.
+*
+* @param rawBody - The raw JSON body string to sign
+* @param secret - The webhook secret (with or without whsec_ prefix)
+* @param msgId - The message ID (used in webhook-id header)
+* @param timestamp - Unix timestamp in seconds (defaults to current time)
+*/
+function signStandardWebhooksPayload(rawBody, secret, msgId, timestamp) {
+	const ts = timestamp ?? Math.floor(Date.now() / 1e3);
+	const body = typeof rawBody === "string" ? rawBody : bufferToString(rawBody, "rawBody");
+	const key = prepareStandardWebhooksSecret(secret);
+	if (key.length === 0) throw new WebhookVerificationError("MISSING_SECRET", "Webhook secret is required but was empty or not provided");
+	const signedPayload = `${msgId}.${ts}.${body}`;
+	const sig = createHmac("sha256", key).update(signedPayload).digest("base64");
+	return {
+		signature: `v1,${sig}`,
+		msgId,
+		timestamp: ts
+	};
+}
+/**
+* Verify a Standard Webhooks signature.
+*
+* Throws `WebhookVerificationError` on failure with a specific error code.
+*/
+function verifyStandardWebhooksSignature(opts) {
+	const { rawBody, msgId, timestamp: timestampStr, signatureHeader, secret, toleranceSeconds = DEFAULT_TOLERANCE_SECONDS, nowSeconds } = opts;
+	const key = prepareStandardWebhooksSecret(secret);
+	if (key.length === 0) throw new WebhookVerificationError("MISSING_SECRET", "Webhook secret is required but was empty or not provided");
+	if (!timestampStr || !/^\d+$/.test(timestampStr)) throw new WebhookVerificationError("INVALID_SIGNATURE_HEADER", `Invalid webhook-timestamp header: "${timestampStr}". Expected a unix timestamp in seconds`);
+	const timestamp = Number(timestampStr);
+	if (!Number.isInteger(timestamp) || timestamp < 0) throw new WebhookVerificationError("INVALID_SIGNATURE_HEADER", `Invalid webhook-timestamp header: "${timestampStr}". Expected a unix timestamp in seconds`);
+	const now = nowSeconds ?? Math.floor(Date.now() / 1e3);
+	const age = now - 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 body = typeof rawBody === "string" ? rawBody : bufferToString(rawBody, "request body");
+	const signedPayload = `${msgId}.${timestamp}.${body}`;
+	const expectedSig = createHmac("sha256", key).update(signedPayload).digest("base64");
+	const signatures = parseStandardWebhooksSignatures(signatureHeader);
+	if (signatures.length === 0) throw new WebhookVerificationError("INVALID_SIGNATURE_HEADER", "Invalid webhook-signature header format. Expected: \"v1,<base64>\"");
+	const expectedBytes = Buffer.from(expectedSig, "base64");
+	for (const sig of signatures) {
+		if (!BASE64_PATTERN$1.test(sig)) continue;
+		const sigBytes = Buffer.from(sig, "base64");
+		if (sigBytes.length === expectedBytes.length && timingSafeEqual(sigBytes, expectedBytes)) return true;
+	}
+	throw new WebhookVerificationError("SIGNATURE_MISMATCH", "No valid signature found. Verify the webhook secret matches and you're using the raw request body (not re-serialized JSON).");
+}
+
 //#endregion
 //#region src/schema.generated.ts
 const emailReceivedEventJsonSchema = {
@@ -6758,14 +6863,14 @@ const emailReceivedEventJsonSchema = {
 						"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."
+					"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."
+					"description": "Forward detection and analysis results.\n\nOptional. Present when the email was processed by a forward-detection pipeline (always present in Primitive's managed service). When absent, forward detection was not performed on this email."
 				}
 			},
-			"description": "Email analysis and classification results."
+			"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."
 		},
 		"ForwardAnalysis": {
 			"type": "object",
@@ -7493,6 +7598,11 @@ function isEmailReceivedEvent(event) {
 	}
 }
 const SIGNATURE_HEADER_NAMES = ["primitive-signature", "mymx-signature"];
+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
@@ -7518,6 +7628,50 @@ function getSignatureHeader(headers) {
 	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:
@@ -7558,13 +7712,24 @@ function getSignatureHeader(headers) {
 */
 function handleWebhook(options) {
 	const { body, headers, secret, toleranceSeconds } = options;
-	const signature = getSignatureHeader(headers);
-	verifyWebhookSignature({
+	const swHeaders = getStandardWebhooksHeaders(headers);
+	if (swHeaders) verifyStandardWebhooksSignature({
 		rawBody: body,
-		signatureHeader: signature,
+		msgId: swHeaders.msgId,
+		timestamp: swHeaders.timestamp,
+		signatureHeader: swHeaders.signature,
 		secret,
 		toleranceSeconds
 	});
+	else {
+		const signature = getSignatureHeader(headers);
+		verifyWebhookSignature({
+			rawBody: body,
+			signatureHeader: signature,
+			secret,
+			toleranceSeconds
+		});
+	}
 	const parsed = parseJsonBody(body);
 	return validateEmailReceivedEvent(parsed);
 }
@@ -7742,4 +7907,4 @@ function verifyRawEmailDownload(downloaded, event) {
 }
 
 //#endregion
-export { AuthConfidence, AuthVerdict, DkimResult, DmarcPolicy, DmarcResult, EventType, ForwardVerdict, LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER, ParsedStatus, PrimitiveWebhookError, RAW_EMAIL_ERRORS, RawEmailDecodeError, SpfResult, VERIFICATION_ERRORS, WEBHOOK_VERSION, WebhookPayloadError, WebhookValidationError, WebhookVerificationError, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, parseWebhookEvent, safeValidateEmailReceivedEvent, signWebhookPayload, validateEmailAuth, validateEmailReceivedEvent, verifyRawEmailDownload, verifyWebhookSignature };
+export { AuthConfidence, AuthVerdict, DkimResult, DmarcPolicy, DmarcResult, EventType, ForwardVerdict, LEGACY_CONFIRMED_HEADER, LEGACY_SIGNATURE_HEADER, PAYLOAD_ERRORS, PRIMITIVE_CONFIRMED_HEADER, PRIMITIVE_SIGNATURE_HEADER, ParsedStatus, PrimitiveWebhookError, RAW_EMAIL_ERRORS, RawEmailDecodeError, STANDARD_WEBHOOK_ID_HEADER, STANDARD_WEBHOOK_SIGNATURE_HEADER, STANDARD_WEBHOOK_TIMESTAMP_HEADER, SpfResult, VERIFICATION_ERRORS, WEBHOOK_VERSION, WebhookPayloadError, WebhookValidationError, WebhookVerificationError, confirmedHeaders, decodeRawEmail, emailReceivedEventJsonSchema, getDownloadTimeRemaining, handleWebhook, isDownloadExpired, isEmailReceivedEvent, isRawIncluded, parseWebhookEvent, safeValidateEmailReceivedEvent, signStandardWebhooksPayload, signWebhookPayload, validateEmailAuth, validateEmailReceivedEvent, verifyRawEmailDownload, verifyStandardWebhooksSignature, verifyWebhookSignature };