mymx 0.3.5 → 0.3.7

package/dist/index.cjs

@@ -1,869 +0,0 @@
-"use strict";
-const require_errors = require('./errors-DOkb_I6u.cjs');
-const require_signing = require('./signing-Bqe14lp0.cjs');
-const require_zod = require('./zod-CyQz4zEa.cjs');
-const node_crypto = require_errors.__toESM(require("node:crypto"));
-
-//#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",
-					"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",
-					"const": "email.received",
-					"description": "Event type identifier. Always `\"email.received\"` for this event type."
-				},
-				"version": {
-					"$ref": "#/definitions/WebhookVersion",
-					"description": "API version in date format (YYYY-MM-DD). Use this to detect version mismatches between webhook and SDK."
-				},
-				"delivery": {
-					"type": "object",
-					"properties": {
-						"endpoint_id": {
-							"type": "string",
-							"description": "ID of the webhook endpoint receiving this event. Matches the endpoint ID from your MyMX dashboard."
-						},
-						"attempt": {
-							"type": "number",
-							"description": "Delivery attempt number, starting at 1. Increments with each retry if previous attempts failed."
-						},
-						"attempted_at": {
-							"type": "string",
-							"description": "ISO 8601 timestamp (UTC) when this delivery was attempted.",
-							"examples": ["2025-01-15T10:30:00.000Z"]
-						}
-					},
-					"required": [
-						"endpoint_id",
-						"attempt",
-						"attempted_at"
-					],
-					"additionalProperties": false,
-					"description": "Metadata about this webhook delivery."
-				},
-				"email": {
-					"type": "object",
-					"properties": {
-						"id": {
-							"type": "string",
-							"description": "Unique email ID in MyMX. Use this ID when calling MyMX APIs to reference this email."
-						},
-						"received_at": {
-							"type": "string",
-							"description": "ISO 8601 timestamp (UTC) when MyMX 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" },
-									"description": "SMTP envelope recipients (RCPT TO commands). All addresses that received this email in a single delivery."
-								}
-							},
-							"required": [
-								"helo",
-								"mail_from",
-								"rcpt_to"
-							],
-							"additionalProperties": false,
-							"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",
-									"description": "From header value. May include display name: `\"John Doe\" <john@example.com>`"
-								},
-								"to": {
-									"type": "string",
-									"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"
-							],
-							"additionalProperties": false,
-							"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",
-											"description": "HTTPS URL to download the raw email. Returns the email as-is in RFC 5322 format."
-										},
-										"expires_at": {
-											"type": "string",
-											"description": "ISO 8601 timestamp (UTC) when this URL expires. Download before this time or the URL will return 403."
-										}
-									},
-									"required": ["url", "expires_at"],
-									"additionalProperties": false,
-									"description": "Download information for the raw email. Always present, even if raw content is inline."
-								}
-							},
-							"required": ["raw", "download"],
-							"additionalProperties": false,
-							"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": {
-							"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"],
-								"additionalProperties": false,
-								"description": "SpamAssassin analysis results."
-							} },
-							"required": ["spamassassin"],
-							"additionalProperties": false,
-							"description": "Email analysis and classification results. May be absent if analysis was not performed."
-						}
-					},
-					"required": [
-						"id",
-						"received_at",
-						"smtp",
-						"headers",
-						"content",
-						"parsed"
-					],
-					"additionalProperties": false,
-					"description": "The email that triggered this event."
-				}
-			},
-			"required": [
-				"id",
-				"event",
-				"version",
-				"delivery",
-				"email"
-			],
-			"additionalProperties": false,
-			"description": "Webhook payload for the `email.received` event.\n\nThis is delivered to your webhook endpoint when MyMX receives an email matching your domain configuration."
-		},
-		"WebhookVersion": {
-			"type": "string",
-			"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": "number",
-					"description": "Maximum size in bytes for inline inclusion. Emails larger than this threshold require download."
-				},
-				"size_bytes": {
-					"type": "number",
-					"description": "Actual size of the raw email in bytes."
-				},
-				"sha256": {
-					"type": "string",
-					"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"
-			],
-			"additionalProperties": false,
-			"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": "number",
-					"description": "Maximum size in bytes for inline inclusion. The email exceeded this threshold."
-				},
-				"size_bytes": {
-					"type": "number",
-					"description": "Actual size of the raw email in bytes."
-				},
-				"sha256": {
-					"type": "string",
-					"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"
-			],
-			"additionalProperties": false,
-			"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."
-				},
-				"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"],
-					"description": "HTTPS URL to download all attachments as a tar.gz archive. Null if the email had no attachments. URL expires - check the expiration before downloading."
-				}
-			},
-			"required": [
-				"status",
-				"error",
-				"body_text",
-				"body_html",
-				"reply_to",
-				"cc",
-				"bcc",
-				"in_reply_to",
-				"references",
-				"attachments",
-				"attachments_download_url"
-			],
-			"additionalProperties": false,
-			"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"],
-			"additionalProperties": false,
-			"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": "number",
-					"description": "Size of the attachment in bytes."
-				},
-				"sha256": {
-					"type": "string",
-					"description": "SHA-256 hash of the attachment content (hex-encoded). Use this to verify attachment integrity after download."
-				},
-				"part_index": {
-					"type": "number",
-					"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"
-			],
-			"additionalProperties": false,
-			"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."
-				},
-				"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",
-				"in_reply_to",
-				"references",
-				"attachments",
-				"attachments_download_url"
-			],
-			"additionalProperties": false,
-			"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"
-			],
-			"additionalProperties": false,
-			"description": "Error details when email parsing fails."
-		}
-	}
-};
-
-//#endregion
-//#region src/parsing.ts
-/**
-* 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 : require_signing.bufferToString(rawBody, "request body");
-	if (!bodyStr || bodyStr.trim() === "") throw new require_errors.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 positionMatch = jsonError.message.match(/position\s*(\d+)/i);
-		const position = positionMatch?.[1];
-		throw new require_errors.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/index.ts
-/**
-* Cast input to EmailReceivedEvent after verifying event type.
-* NOTE: This only checks the event field, not the full schema.
-* For full validation, use handleWebhook() or validateEmailReceivedEvent().
-* @internal
-*/
-function asEmailReceivedEvent(input) {
-	const obj = input;
-	if (obj.event !== "email.received") throw new require_errors.WebhookPayloadError("PAYLOAD_UNKNOWN_EVENT", `Unknown event type "${obj.event}"`, obj.event === void 0 ? "The 'event' field is undefined. Make sure the webhook payload is complete." : `Expected "email.received" event but got "${obj.event}".`);
-	return input;
-}
-/**
-* Parse a webhook payload, returning typed events for known types
-* and UnknownEvent for future event types.
-*
-* This provides forward-compatibility: when MyMX adds new event types,
-* your code won't break - you'll receive an UnknownEvent that you can
-* handle or ignore.
-*
-* For most use cases, prefer `handleWebhook()` which also verifies
-* the signature and validates the payload schema.
-*
-* @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
-*
-* @example
-* ```typescript
-* import { parseWebhookEvent } from 'mymx';
-*
-* 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) {
-	if (input === null) throw new require_errors.WebhookPayloadError("PAYLOAD_NULL", "Received null instead of webhook payload", "Check that your request body variable is defined.");
-	if (input === void 0) throw new require_errors.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 require_errors.WebhookPayloadError("PAYLOAD_IS_ARRAY", "Received array instead of webhook payload object", "Webhook payloads must be objects, not arrays.");
-	if (typeof input !== "object") throw new require_errors.WebhookPayloadError("PAYLOAD_WRONG_TYPE", `Received ${typeof input} instead of webhook payload object`, "Webhook payloads must be objects.");
-	const obj = input;
-	if (!("event" in obj) || typeof obj.event !== "string") throw new require_errors.WebhookPayloadError("PAYLOAD_MISSING_EVENT", "Missing 'event' field in payload", "This doesn't look like a MyMX webhook payload.");
-	switch (obj.event) {
-		case "email.received": return asEmailReceivedEvent(input);
-		default: return input;
-	}
-}
-/**
-* Type guard to check if a webhook event is an EmailReceivedEvent.
-*
-* @example
-* ```typescript
-* const event = parseWebhookEvent(payload);
-* if (isEmailReceivedEvent(event)) {
-*   // TypeScript knows event is EmailReceivedEvent
-*   console.log(event.email.headers.subject);
-* }
-* ```
-*/
-function isEmailReceivedEvent(event) {
-	return typeof event === "object" && event !== null && "event" in event && event.event === "email.received";
-}
-/**
-* Extract signature header from various header formats.
-*/
-function getSignatureHeader(headers) {
-	if (headers instanceof Headers) return headers.get("mymx-signature") ?? "";
-	const obj = headers;
-	const key = Object.keys(obj).find((k) => k.toLowerCase() === "mymx-signature");
-	if (!key) return "";
-	const value = obj[key];
-	if (Array.isArray(value)) return value[0] ?? "";
-	return value ?? "";
-}
-/**
-* Verify, parse, and validate a webhook in one call.
-*
-* This is the recommended way to handle MyMX webhooks. It:
-* 1. Verifies the signature to ensure the webhook is authentic
-* 2. Parses the JSON body
-* 3. Validates the payload against the schema with Zod
-* 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, MyMXWebhookError } from 'mymx';
-*
-* app.post('/webhooks/email', express.raw({ type: 'application/json' }), (req, res) => {
-*   try {
-*     const event = handleWebhook({
-*       body: req.body,
-*       headers: req.headers,
-*       secret: process.env.MYMX_WEBHOOK_SECRET,
-*     });
-*
-*     console.log('Email from:', event.email.headers.from);
-*     res.json({ received: true });
-*   } catch (err) {
-*     if (err instanceof MyMXWebhookError) {
-*       console.error(`[${err.code}] ${err.message}`);
-*       return res.status(400).json({ error: err.code });
-*     }
-*     throw err;
-*   }
-* });
-* ```
-*/
-function handleWebhook(options) {
-	const { body, headers, secret, toleranceSeconds } = options;
-	const signature = getSignatureHeader(headers);
-	require_signing.verifyWebhookSignature({
-		rawBody: body,
-		signatureHeader: signature,
-		secret,
-		toleranceSeconds
-	});
-	const parsed = parseJsonBody(body);
-	return require_zod.validateEmailReceivedEvent(parsed);
-}
-/**
-* Returns headers for the optional "content discard" feature.
-*
-* If you have the "content discard" setting enabled in your MyMX dashboard,
-* returning this header tells MyMX 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', (req, res) => {
-*   const event = handleWebhook({ ... });
-*   // Durably save the email first!
-*   await db.saveEmail(event);
-*   res.set(confirmedHeaders()).json({ received: true });
-* });
-* ```
-*
-* @example Fetch API / Next.js (only if using content discard)
-* ```typescript
-* return new Response(JSON.stringify({ received: true }), {
-*   status: 200,
-*   headers: {
-*     'Content-Type': 'application/json',
-*     ...confirmedHeaders(),
-*   },
-* });
-* ```
-*/
-function confirmedHeaders() {
-	return { [require_signing.MYMX_CONFIRMED_HEADER]: "true" };
-}
-/**
-* Check if the download URL for a webhook event has expired.
-*
-* @param event - The webhook event
-* @param now - Optional current time for testing (defaults to Date.now())
-* @returns true if the download URL has expired
-*
-* @example
-* ```typescript
-* if (isDownloadExpired(event)) {
-*   console.log("Download URL has expired, cannot fetch raw email");
-* } else {
-*   const response = await fetch(event.email.content.download.url);
-* }
-* ```
-*/
-function isDownloadExpired(event, now = Date.now()) {
-	const expiresAt = new Date(event.email.content.download.expires_at).getTime();
-	return now >= expiresAt;
-}
-/**
-* 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 'mymx';
-*
-* 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 require_errors.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}`);
-	const decoded = Buffer.from(raw.data, "base64");
-	if (verify) {
-		const hash = (0, node_crypto.createHash)("sha256").update(decoded).digest("hex");
-		if (hash !== raw.sha256) throw new require_errors.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 MyMX 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 'mymx';
-*
-* 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 = (0, node_crypto.createHash)("sha256").update(buffer).digest("hex");
-	const expected = event.email.content.raw.sha256;
-	if (hash !== expected) throw new require_errors.RawEmailDecodeError("HASH_MISMATCH", `SHA-256 hash mismatch. Expected: ${expected}, got: ${hash}. The downloaded content may be corrupted.`);
-	return buffer;
-}
-
-//#endregion
-exports.MYMX_CONFIRMED_HEADER = require_signing.MYMX_CONFIRMED_HEADER
-exports.MYMX_SIGNATURE_HEADER = require_signing.MYMX_SIGNATURE_HEADER
-exports.MyMXWebhookError = require_errors.MyMXWebhookError
-exports.PAYLOAD_ERRORS = require_errors.PAYLOAD_ERRORS
-exports.RAW_EMAIL_ERRORS = require_errors.RAW_EMAIL_ERRORS
-exports.RawEmailDecodeError = require_errors.RawEmailDecodeError
-exports.VERIFICATION_ERRORS = require_errors.VERIFICATION_ERRORS
-exports.WEBHOOK_VERSION = require_errors.WEBHOOK_VERSION
-exports.WebhookPayloadError = require_errors.WebhookPayloadError
-exports.WebhookValidationError = require_errors.WebhookValidationError
-exports.WebhookVerificationError = require_errors.WebhookVerificationError
-exports.confirmedHeaders = confirmedHeaders
-exports.decodeRawEmail = decodeRawEmail
-exports.emailReceivedEventJsonSchema = emailReceivedEventJsonSchema
-exports.getDownloadTimeRemaining = getDownloadTimeRemaining
-exports.handleWebhook = handleWebhook
-exports.isDownloadExpired = isDownloadExpired
-exports.isEmailReceivedEvent = isEmailReceivedEvent
-exports.isRawIncluded = isRawIncluded
-exports.parseWebhookEvent = parseWebhookEvent
-exports.verifyRawEmailDownload = verifyRawEmailDownload
-exports.verifyWebhookSignature = require_signing.verifyWebhookSignature