@primitivedotdev/sdk 0.2.0

package/dist/index.d.ts

@@ -0,0 +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-C6M6oCRS.js";
+import { DecodeRawEmailOptions, HandleWebhookOptions, 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-C9pON-wY.js";
+export { AuthConfidence, AuthVerdict, DecodeRawEmailOptions, DkimResult, DkimSignature, DmarcPolicy, DmarcResult, EmailAddress, EmailAnalysis, EmailAuth, EmailReceivedEvent, EventType, ForwardAnalysis, ForwardOriginalSender, ForwardResult, ForwardResultAttachmentAnalyzed, ForwardResultAttachmentSkipped, ForwardResultInline, ForwardVerdict, ForwardVerification, HandleWebhookOptions, KnownWebhookEvent, 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 };

package/dist/index.js

@@ -0,0 +1,3 @@
+import { AuthConfidence, AuthVerdict, DkimResult, DmarcPolicy, DmarcResult, EventType, ForwardVerdict, 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-h24dbQEE.js";
+
+export { AuthConfidence, AuthVerdict, DkimResult, DmarcPolicy, DmarcResult, EventType, ForwardVerdict, 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 };

package/dist/parser/index.d.ts

@@ -0,0 +1,185 @@
+import { EmailAddress, ParsedDataComplete, WebhookAttachment } from "../types-C6M6oCRS.js";
+
+//#region src/parser/attachment-parser.d.ts
+interface ParsedAttachment {
+  id: string;
+  partIndex: number;
+  filename: string | null;
+  contentType: string | null;
+  contentTypeNorm: string;
+  contentDispositionRaw: string | null;
+  disposition: "attachment" | "inline" | null;
+  contentTransferEncoding: string | null;
+  contentIdRaw: string | null;
+  contentIdNorm: string | null;
+  downloadName: string;
+  tarPath: string;
+  sizeBytes: number;
+  sha256: string;
+  isInline: boolean;
+  isDownloadable: boolean;
+  isSafeForInlineServing: boolean;
+  content: Buffer;
+}
+interface ParsedEmailWithAttachments {
+  bodyText: string | null;
+  bodyHtml: string | null;
+  attachments: ParsedAttachment[];
+  subject: string | null;
+  messageId: string | null;
+  date: Date | null;
+  dateHeader: string | null;
+  from: string | null;
+  to: string | null;
+  replyTo: EmailAddress[] | null;
+  cc: EmailAddress[] | null;
+  bcc: EmailAddress[] | null;
+  inReplyTo: string[] | null;
+  references: string[] | null;
+}
+/**
+ * Parse a raw email buffer and extract body + attachments.
+ * Uses mailparser for the heavy lifting.
+ *
+ * - Mailparser's default converts CID refs to data: URLs in body_html
+ * - Inline images (related=true) are embedded in body_html, NOT in attachments list
+ * - Only "real" attachments are returned for tar.gz bundling
+ */
+declare function parseEmailWithAttachments(emlBuffer: Buffer, options?: {
+  generateAttachmentId?: () => string;
+}): Promise<ParsedEmailWithAttachments>;
+/**
+ * Normalize a Content-Type to lowercase media type without parameters.
+ */
+declare function normalizeContentType(contentType: string | undefined | null): string;
+/**
+ * Compute SHA-256 hash of a buffer as hex string.
+ */
+declare function sha256Hex(buffer: Buffer): string;
+/**
+ * Sanitize a filename for safe use in Content-Disposition headers.
+ * Prevents path traversal, removes control characters, enforces length limits.
+ */
+declare function sanitizeFilename(filename: string | null, partIndex: number): string; //#endregion
+//#region src/parser/attachment-bundler.d.ts
+/**
+ * Result of bundling attachments into a tar.gz archive
+ */
+interface BundleResult {
+  /** The tar.gz archive as a Buffer */
+  tarGzBuffer: Buffer;
+  /** SHA-256 hash of the tar.gz archive */
+  sha256: string;
+  /** Number of attachments included */
+  attachmentCount: number;
+  /** Total size of all attachment bytes (before compression) */
+  totalAttachmentBytes: number;
+}
+/**
+ * Metadata for attachments included in the bundle (for DB storage)
+ */
+interface AttachmentMetadata {
+  filename: string | null;
+  content_type: string;
+  size_bytes: number;
+  sha256: string;
+  part_index: number;
+  tar_path: string;
+}
+/**
+ * Bundle downloadable attachments into a tar.gz archive.
+ *
+ * - Only includes attachments where isDownloadable === true
+ * - Inline images (related=true) are excluded - they're in body_html as data: URLs
+ * - Files are stored at paths: {partIndex}_{sanitized_filename}
+ *
+ * @param attachments - Array of parsed attachments from parseEmailWithAttachments()
+ * @returns BundleResult with the tar.gz buffer and metadata, or null if no downloadable attachments
+ */
+declare function bundleAttachments(attachments: ParsedAttachment[]): Promise<BundleResult | null>;
+/**
+ * Extract metadata for DB storage from parsed attachments.
+ * Only includes downloadable attachments (matches what's in the tar.gz).
+ *
+ * @param attachments - Array of parsed attachments
+ * @returns Array of attachment metadata for DB storage
+ */
+declare function extractAttachmentMetadata(attachments: ParsedAttachment[]): AttachmentMetadata[];
+/**
+ * Generate the storage key for an attachments tar.gz file.
+ *
+ * @param emailId - The email UUID
+ * @param sha256 - SHA-256 hash of the tar.gz file
+ * @returns Storage key in format: attachments/{email_id}_{hash8}.tar.gz
+ */
+declare function getAttachmentsStorageKey(emailId: string, sha256: string): string;
+
+//#endregion
+//#region src/parser/email-parser.d.ts
+interface ParsedEmail {
+  from: string;
+  to: string;
+  subject: string | undefined;
+  text: string | undefined;
+  html: string | undefined;
+  headers: Record<string, string | string[]>;
+  messageId: string | undefined;
+  date: Date | undefined;
+}
+/**
+ * Parse a raw .eml file into structured data
+ * Uses mailparser library for robust email parsing
+ */
+declare function parseEmail(emlRaw: string): Promise<ParsedEmail>;
+
+//#endregion
+//#region src/parser/mapping.d.ts
+/**
+ * Convert parser output to canonical ParsedDataComplete (snake_case).
+ *
+ * Maps `bodyHtml` → `body_html` without mutating the HTML content.
+ * Preserves the original Date header value when available.
+ * Coerces nullable `from`/`to` to non-nullable strings.
+ *
+ * @param parsed - Output from parseEmailWithAttachments()
+ * @param attachmentsDownloadUrl - URL or local path for attachment download (null if no attachments)
+ * @returns Canonical ParsedDataComplete ready for JSON serialization
+ */
+declare function toParsedDataComplete(parsed: ParsedEmailWithAttachments, attachmentsDownloadUrl: string | null): ParsedDataComplete;
+/**
+ * Convert parser attachments to canonical WebhookAttachment[] (JSON-safe subset).
+ *
+ * Filters to only downloadable attachments and strips internal fields
+ * (content Buffer, contentId, disposition, etc.).
+ *
+ * @param attachments - ParsedAttachment[] from the parser
+ * @returns WebhookAttachment[] with only public metadata
+ */
+declare function toWebhookAttachments(attachments: ParsedAttachment[]): WebhookAttachment[];
+/**
+ * Convert AttachmentMetadata[] (from extractAttachmentMetadata) to WebhookAttachment[].
+ *
+ * AttachmentMetadata is already in snake_case and JSON-safe, so this is
+ * essentially a type assertion. Useful when you have metadata from the bundler
+ * rather than raw ParsedAttachment[].
+ */
+declare function attachmentMetadataToWebhookAttachments(metadata: AttachmentMetadata[]): WebhookAttachment[];
+/**
+ * Extract canonical email headers from parser output.
+ *
+ * Converts camelCase parser fields to the shape expected by
+ * EmailReceivedEvent.email.headers.
+ *
+ * @param parsed - Output from parseEmailWithAttachments()
+ * @returns Headers object matching the canonical schema
+ */
+declare function toCanonicalHeaders(parsed: ParsedEmailWithAttachments): {
+  message_id: string | null;
+  subject: string | null;
+  from: string;
+  to: string;
+  date: string | null;
+};
+
+//#endregion
+export { AttachmentMetadata, BundleResult, ParsedAttachment, ParsedEmail, ParsedEmailWithAttachments, attachmentMetadataToWebhookAttachments, bundleAttachments, extractAttachmentMetadata, getAttachmentsStorageKey, normalizeContentType, parseEmail, parseEmailWithAttachments, sanitizeFilename, sha256Hex, toCanonicalHeaders, toParsedDataComplete, toWebhookAttachments };

package/dist/parser/index.js

@@ -0,0 +1,438 @@
+import { createHash } from "node:crypto";
+import { PassThrough } from "node:stream";
+
+//#region src/parser/attachment-bundler.ts
+async function loadArchiver() {
+	const module = await import("archiver");
+	return module.default;
+}
+/**
+* Bundle downloadable attachments into a tar.gz archive.
+*
+* - Only includes attachments where isDownloadable === true
+* - Inline images (related=true) are excluded - they're in body_html as data: URLs
+* - Files are stored at paths: {partIndex}_{sanitized_filename}
+*
+* @param attachments - Array of parsed attachments from parseEmailWithAttachments()
+* @returns BundleResult with the tar.gz buffer and metadata, or null if no downloadable attachments
+*/
+async function bundleAttachments(attachments) {
+	const downloadable = attachments.filter((att) => att.isDownloadable);
+	if (downloadable.length === 0) return null;
+	const archiver = await loadArchiver();
+	const archive = archiver("tar", {
+		gzip: true,
+		gzipOptions: { 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);
+		};
+		const rejectArchive = (error) => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			reject(error);
+		};
+		const handleData = (chunk) => {
+			chunks.push(chunk);
+		};
+		const handleEnd = () => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			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;
+			}
+			archive.finalize().catch(rejectArchive);
+		} catch (error) {
+			rejectArchive(error instanceof Error ? error : new Error(String(error)));
+		}
+	});
+	const sha256 = createHash("sha256").update(tarGzBuffer).digest("hex");
+	return {
+		tarGzBuffer,
+		sha256,
+		attachmentCount: downloadable.length,
+		totalAttachmentBytes
+	};
+}
+/**
+* Extract metadata for DB storage from parsed attachments.
+* Only includes downloadable attachments (matches what's in the tar.gz).
+*
+* @param attachments - Array of parsed attachments
+* @returns Array of attachment metadata for DB storage
+*/
+function extractAttachmentMetadata(attachments) {
+	return attachments.filter((att) => att.isDownloadable).map((att) => ({
+		filename: att.filename,
+		content_type: att.contentTypeNorm,
+		size_bytes: att.sizeBytes,
+		sha256: att.sha256,
+		part_index: att.partIndex,
+		tar_path: att.tarPath
+	}));
+}
+/**
+* Generate the storage key for an attachments tar.gz file.
+*
+* @param emailId - The email UUID
+* @param sha256 - SHA-256 hash of the tar.gz file
+* @returns Storage key in format: attachments/{email_id}_{hash8}.tar.gz
+*/
+function getAttachmentsStorageKey(emailId, sha256) {
+	const hash8 = sha256.substring(0, 8);
+	return `attachments/${emailId}_${hash8}.tar.gz`;
+}
+
+//#endregion
+//#region src/parser/attachment-parser.ts
+async function loadMailparser$1() {
+	return import("mailparser");
+}
+const SIGNATURE_ARTIFACTS = new Set([
+	"application/pkcs7-signature",
+	"application/x-pkcs7-signature",
+	"application/pgp-signature",
+	"application/pgp-keys",
+	"application/pgp-encrypted",
+	"application/ms-tnef"
+]);
+const SAFE_INLINE_TYPES = new Set([
+	"image/png",
+	"image/jpeg",
+	"image/gif",
+	"image/webp",
+	"image/avif"
+]);
+/**
+* Parse a raw email buffer and extract body + attachments.
+* Uses mailparser for the heavy lifting.
+*
+* - Mailparser's default converts CID refs to data: URLs in body_html
+* - Inline images (related=true) are embedded in body_html, NOT in attachments list
+* - Only "real" attachments are returned for tar.gz bundling
+*/
+async function parseEmailWithAttachments(emlBuffer, options) {
+	const generateId = options?.generateAttachmentId ?? (() => crypto.randomUUID());
+	const { simpleParser } = await loadMailparser$1();
+	const parsed = await simpleParser(emlBuffer);
+	const attachments = [];
+	for (let i = 0; i < (parsed.attachments?.length ?? 0); i++) {
+		const att = parsed.attachments[i];
+		const contentTypeNorm = normalizeContentType(att.contentType);
+		if (SIGNATURE_ARTIFACTS.has(contentTypeNorm)) continue;
+		const id = generateId();
+		const contentIdNorm = att.cid?.toLowerCase() ?? null;
+		const isInline = att.related === true;
+		const isDownloadable = !isInline && (att.contentDisposition === "attachment" || !!att.filename || contentTypeNorm === "message/rfc822" || contentTypeNorm === "text/calendar");
+		const downloadName = sanitizeFilename(att.filename ?? null, i);
+		const tarPath = `${i}_${downloadName}`;
+		attachments.push({
+			id,
+			partIndex: i,
+			filename: att.filename ?? null,
+			contentType: getHeaderString(att.headers.get("content-type")),
+			contentTypeNorm,
+			contentDispositionRaw: getHeaderString(att.headers.get("content-disposition")),
+			disposition: parseDisposition(att.contentDisposition),
+			contentTransferEncoding: getHeaderString(att.headers.get("content-transfer-encoding")),
+			contentIdRaw: att.contentId ?? null,
+			contentIdNorm,
+			downloadName,
+			tarPath,
+			sizeBytes: att.content.length,
+			sha256: sha256Hex(att.content),
+			isInline,
+			isDownloadable,
+			isSafeForInlineServing: isInline && SAFE_INLINE_TYPES.has(contentTypeNorm),
+			content: att.content
+		});
+	}
+	let bodyHtml = null;
+	if (parsed.html && typeof parsed.html === "string") bodyHtml = parsed.html;
+	return {
+		bodyText: parsed.text ?? null,
+		bodyHtml,
+		attachments,
+		subject: parsed.subject ?? null,
+		messageId: parsed.messageId ?? null,
+		date: parsed.date ?? null,
+		dateHeader: getOriginalHeaderValue(parsed, "date"),
+		from: parsed.from?.text ?? null,
+		to: Array.isArray(parsed.to) ? parsed.to.map((a) => a.text).join(", ") : parsed.to?.text ?? null,
+		replyTo: extractAddresses(parsed.replyTo),
+		cc: extractAddresses(parsed.cc),
+		bcc: extractAddresses(parsed.bcc),
+		inReplyTo: normalizeReferences(parsed.inReplyTo),
+		references: normalizeReferences(parsed.references)
+	};
+}
+/**
+* Extract email addresses from mailparser's AddressObject format.
+* Handles both single AddressObject and arrays.
+*/
+function extractAddresses(addressObj) {
+	if (!addressObj) return null;
+	const objects = Array.isArray(addressObj) ? addressObj : [addressObj];
+	const addresses = [];
+	for (const obj of objects) if (obj && "value" in obj && obj.value) {
+		for (const addr of obj.value) if (addr.address) addresses.push({
+			address: addr.address,
+			name: addr.name || null
+		});
+	}
+	return addresses.length > 0 ? addresses : null;
+}
+/**
+* Normalize References header to array of message IDs.
+* Can be a string (single ID or space-separated IDs) or array.
+*/
+function normalizeReferences(refs) {
+	if (!refs) return null;
+	if (Array.isArray(refs)) return refs.length > 0 ? refs : null;
+	const parts = refs.split(/\s+/).filter(Boolean);
+	return parts.length > 0 ? parts : null;
+}
+/**
+* Normalize a Content-Type to lowercase media type without parameters.
+*/
+function normalizeContentType(contentType) {
+	if (!contentType?.trim()) return "application/octet-stream";
+	const mediaType = contentType.split(";")[0].trim().toLowerCase();
+	return mediaType || "application/octet-stream";
+}
+/**
+* Parse disposition string to typed value.
+*/
+function parseDisposition(disposition) {
+	if (!disposition) return null;
+	const lower = disposition.toLowerCase();
+	if (lower === "attachment") return "attachment";
+	if (lower === "inline") return "inline";
+	return null;
+}
+/**
+* Get string representation of a header value.
+*/
+function getHeaderString(value) {
+	if (!value) return null;
+	if (typeof value === "string") return value;
+	if (typeof value === "object" && "value" in value) {
+		const v = value;
+		if (v.params && Object.keys(v.params).length > 0) {
+			const params = Object.entries(v.params).map(([k, val]) => `${k}="${val}"`).join("; ");
+			return `${v.value}; ${params}`;
+		}
+		return v.value;
+	}
+	return String(value);
+}
+function getOriginalHeaderValue(parsed, key) {
+	const headerLines = parsed.headerLines;
+	const original = headerLines?.find((header) => header.key?.toLowerCase() === key.toLowerCase())?.line;
+	if (!original) return null;
+	const separator = original.indexOf(":");
+	return separator === -1 ? original : original.slice(separator + 1).trimStart();
+}
+/**
+* Compute SHA-256 hash of a buffer as hex string.
+*/
+function sha256Hex(buffer) {
+	return createHash("sha256").update(buffer).digest("hex");
+}
+/**
+* Sanitize a filename for safe use in Content-Disposition headers.
+* Prevents path traversal, removes control characters, enforces length limits.
+*/
+function sanitizeFilename(filename, partIndex) {
+	if (!filename) return `attachment_${partIndex}`;
+	const trimmed = filename.trim();
+	if (!trimmed || trimmed === "." || trimmed === "..") return `attachment_${partIndex}`;
+	let safe = filename.replace(/[/\\]/g, "_").replace(/:/g, "-").replace(/\.\./g, "_").replace(/[\x00-\x1f\x7f]/g, "").replace(/[^\x20-\x7E]/g, "_").replace(/\s+/g, " ").trim();
+	if (safe.length > 200) {
+		const lastDot = safe.lastIndexOf(".");
+		if (lastDot > 0 && safe.length - lastDot <= 10) {
+			const ext = safe.substring(lastDot);
+			safe = safe.substring(0, 200 - ext.length) + ext;
+		} else safe = safe.substring(0, 200);
+	}
+	if (!safe) return `attachment_${partIndex}`;
+	return safe;
+}
+
+//#endregion
+//#region src/parser/email-parser.ts
+async function loadMailparser() {
+	return import("mailparser");
+}
+/**
+* Parse a raw .eml file into structured data
+* Uses mailparser library for robust email parsing
+*/
+async function parseEmail(emlRaw) {
+	const { simpleParser } = await loadMailparser();
+	const parsed = await simpleParser(emlRaw);
+	const headers = {};
+	parsed.headers.forEach((value, key) => {
+		headers[key] = headerValueToString(value);
+	});
+	const getAddressText = (addr) => {
+		if (!addr) return "";
+		if (Array.isArray(addr)) return addr.map((entry) => entry.text || "").filter(Boolean).join(", ");
+		return addr.text || "";
+	};
+	return {
+		from: getAddressText(parsed.from),
+		to: getAddressText(parsed.to),
+		subject: parsed.subject,
+		text: parsed.text,
+		html: parsed.html ? String(parsed.html) : void 0,
+		headers,
+		messageId: parsed.messageId,
+		date: parsed.date
+	};
+}
+function headerValueToString(value) {
+	if (typeof value === "string") return value;
+	if (Array.isArray(value)) {
+		if (value.every((entry) => typeof entry === "string")) return value;
+		return value.map((entry) => structuredHeaderToString(entry)).filter((entry) => entry.length > 0).join(", ");
+	}
+	if (value instanceof Date) return value.toISOString();
+	if (value && typeof value === "object") return structuredHeaderToString(value);
+	return String(value);
+}
+function structuredHeaderToString(value) {
+	if (!value || typeof value !== "object") return String(value ?? "");
+	if ("text" in value && typeof value.text === "string") return value.text;
+	if ("address" in value || "name" in value) {
+		const address = value.address;
+		return typeof address === "string" ? address : "";
+	}
+	if ("value" in value) {
+		const nested = value.value;
+		if (Array.isArray(nested)) return nested.map((entry) => {
+			if (typeof entry === "string") return entry;
+			if (entry && typeof entry === "object" && "address" in entry) {
+				const address = entry.address;
+				if (typeof address === "string") return address;
+			}
+			return structuredHeaderToString(entry);
+		}).filter((entry) => entry.length > 0).join(", ");
+		if (typeof nested === "string") return nested;
+	}
+	return JSON.stringify(value);
+}
+
+//#endregion
+//#region src/parser/mapping.ts
+/**
+* Convert parser output to canonical ParsedDataComplete (snake_case).
+*
+* Maps `bodyHtml` → `body_html` without mutating the HTML content.
+* Preserves the original Date header value when available.
+* Coerces nullable `from`/`to` to non-nullable strings.
+*
+* @param parsed - Output from parseEmailWithAttachments()
+* @param attachmentsDownloadUrl - URL or local path for attachment download (null if no attachments)
+* @returns Canonical ParsedDataComplete ready for JSON serialization
+*/
+function toParsedDataComplete(parsed, attachmentsDownloadUrl) {
+	const attachments = toWebhookAttachments(parsed.attachments);
+	return {
+		status: "complete",
+		error: null,
+		body_text: parsed.bodyText,
+		body_html: parsed.bodyHtml,
+		reply_to: parsed.replyTo,
+		cc: parsed.cc,
+		bcc: parsed.bcc,
+		in_reply_to: parsed.inReplyTo,
+		references: parsed.references,
+		attachments,
+		attachments_download_url: attachments.length === 0 ? null : attachmentsDownloadUrl
+	};
+}
+/**
+* Convert parser attachments to canonical WebhookAttachment[] (JSON-safe subset).
+*
+* Filters to only downloadable attachments and strips internal fields
+* (content Buffer, contentId, disposition, etc.).
+*
+* @param attachments - ParsedAttachment[] from the parser
+* @returns WebhookAttachment[] with only public metadata
+*/
+function toWebhookAttachments(attachments) {
+	return attachments.filter((att) => att.isDownloadable).map((att) => ({
+		filename: att.filename,
+		content_type: att.contentTypeNorm,
+		size_bytes: att.sizeBytes,
+		sha256: att.sha256,
+		part_index: att.partIndex,
+		tar_path: att.tarPath
+	}));
+}
+/**
+* Convert AttachmentMetadata[] (from extractAttachmentMetadata) to WebhookAttachment[].
+*
+* AttachmentMetadata is already in snake_case and JSON-safe, so this is
+* essentially a type assertion. Useful when you have metadata from the bundler
+* rather than raw ParsedAttachment[].
+*/
+function attachmentMetadataToWebhookAttachments(metadata) {
+	return metadata.map((m) => ({
+		filename: m.filename,
+		content_type: m.content_type,
+		size_bytes: m.size_bytes,
+		sha256: m.sha256,
+		part_index: m.part_index,
+		tar_path: m.tar_path
+	}));
+}
+/**
+* Extract canonical email headers from parser output.
+*
+* Converts camelCase parser fields to the shape expected by
+* EmailReceivedEvent.email.headers.
+*
+* @param parsed - Output from parseEmailWithAttachments()
+* @returns Headers object matching the canonical schema
+*/
+function toCanonicalHeaders(parsed) {
+	const from = requireNonEmptyHeader(parsed.from, "From");
+	const to = requireNonEmptyHeader(parsed.to, "To");
+	return {
+		message_id: parsed.messageId,
+		subject: parsed.subject,
+		from,
+		to,
+		date: parsed.dateHeader ?? null
+	};
+}
+function requireNonEmptyHeader(value, headerName) {
+	if (typeof value !== "string" || value.trim() === "") throw new Error(`Parsed email is missing a usable ${headerName} header value`);
+	return value;
+}
+
+//#endregion
+export { attachmentMetadataToWebhookAttachments, bundleAttachments, extractAttachmentMetadata, getAttachmentsStorageKey, normalizeContentType, parseEmail, parseEmailWithAttachments, sanitizeFilename, sha256Hex, toCanonicalHeaders, toParsedDataComplete, toWebhookAttachments };