// VA-P23 · provider → neutral message mapping (shared web + worker). // // Pure functions: GmailMessage (MIME payload walk) and GraphMessage map into the // SAME neutral shape the EmailIntegrationMessage row is written from. Living in // @hivegrid/integrations so the apps/web provider adapters AND the worker sync // tasks share one mapping (no drift between the connect-time and cron-time sync). import type { GmailMessage, GmailMessagePart } from "./google/gmailApi.js"; import type { GraphMessage } from "./microsoft/graphMailApi.js"; export interface MappedEmailAddress { readonly address: string; readonly name?: string; } export interface MappedEmailAttachment { readonly attachmentId: string; readonly filename: string; readonly mimeType: string | null; readonly sizeBytes: number; } /** The neutral message shape (field-compatible with EmailIntegrationMessage). */ export interface MappedEmailMessage { readonly providerMessageId: string; readonly providerThreadId: string | null; /** RFC-5322 Message-ID (angle brackets stripped) — cross-provider dedupe key. */ readonly internetMessageId: string | null; readonly direction: "inbound" | "outbound"; readonly from: MappedEmailAddress; readonly to: readonly MappedEmailAddress[]; readonly cc: readonly MappedEmailAddress[]; readonly bcc: readonly MappedEmailAddress[]; readonly subject: string | null; readonly snippet: string | null; readonly bodyHtml: string | null; readonly bodyText: string | null; readonly sentAt: Date; readonly receivedAt: Date | null; readonly isRead: boolean; readonly hasAttachments: boolean; /** True when a List-Unsubscribe header marks a newsletter/bulk sender (M09 E). */ readonly isNewsletter: boolean; readonly providerLabels: readonly string[]; readonly attachments: readonly MappedEmailAttachment[]; } const SNIPPET_MAX = 140; /** Normalize an RFC-5322 Message-ID: strip angle brackets + whitespace. */ export function normalizeInternetMessageId(value: string | null | undefined): string | null { if (!value) return null; const trimmed = value.trim().replace(/^<|>$/g, "").trim(); return trimmed.length > 0 ? trimmed : null; } /** * Parse an RFC-5322 address list ("Alice , b@y.de"). Deliberately * simple: split on commas outside quotes/brackets, extract `` or a bare * address. Display names keep their content, quotes stripped. */ export function parseAddressList(value: string | null | undefined): MappedEmailAddress[] { if (!value) return []; const parts: string[] = []; let depth = 0; let inQuotes = false; let current = ""; for (const char of value) { if (char === '"') inQuotes = !inQuotes; if (!inQuotes) { if (char === "<" || char === "(") depth += 1; if (char === ">" || char === ")") depth = Math.max(0, depth - 1); if (char === "," && depth === 0) { parts.push(current); current = ""; continue; } } current += char; } if (current.trim()) parts.push(current); const result: MappedEmailAddress[] = []; for (const raw of parts) { const piece = raw.trim(); if (!piece) continue; const angled = piece.match(/^(.*?)<([^<>]+)>\s*$/); if (angled) { const name = angled[1].trim().replace(/^"|"$/g, "").trim(); const address = angled[2].trim().toLowerCase(); if (address.includes("@")) { result.push(name ? { address, name } : { address }); } continue; } const bare = piece.replace(/^"|"$/g, "").trim().toLowerCase(); if (bare.includes("@")) { result.push({ address: bare }); } } return result; } function buildSnippet(preferred: string | null | undefined, fallbackText: string | null): string | null { const source = (preferred ?? "").trim() || (fallbackText ?? "").replace(/\s+/g, " ").trim(); if (!source) return null; return source.length > SNIPPET_MAX ? `${source.slice(0, SNIPPET_MAX - 1)}…` : source; } // --- Gmail ------------------------------------------------------------------- function base64UrlDecode(data: string): string { const pad = data.length % 4 === 0 ? "" : "=".repeat(4 - (data.length % 4)); return Buffer.from(data.replace(/-/g, "+").replace(/_/g, "/") + pad, "base64").toString("utf8"); } function headerValue(headers: ReadonlyArray<{ name: string; value: string }> | undefined, name: string): string | null { const match = (headers ?? []).find((h) => h.name.toLowerCase() === name.toLowerCase()); return match?.value ?? null; } interface GmailBodyWalk { html: string | null; text: string | null; attachments: MappedEmailAttachment[]; } function walkParts(part: GmailMessagePart | undefined, acc: GmailBodyWalk): void { if (!part) return; const mime = part.mimeType ?? ""; if (part.filename && part.body?.attachmentId) { acc.attachments.push({ attachmentId: part.body.attachmentId, filename: part.filename, mimeType: mime || null, sizeBytes: part.body.size ?? 0, }); } else if (mime === "text/html" && part.body?.data && acc.html === null) { acc.html = base64UrlDecode(part.body.data); } else if (mime === "text/plain" && part.body?.data && acc.text === null) { acc.text = base64UrlDecode(part.body.data); } for (const child of part.parts ?? []) { walkParts(child, acc); } } /** * Map a Gmail message (format=full) into the neutral shape. Direction comes from * the SENT label; read state from the absence of UNREAD. */ export function mapGmailMessage(message: GmailMessage): MappedEmailMessage { const headers = message.payload?.headers; const walk: GmailBodyWalk = { html: null, text: null, attachments: [] }; walkParts(message.payload, walk); const labels = message.labelIds ?? []; const from = parseAddressList(headerValue(headers, "From"))[0] ?? { address: "" }; const sentAtMs = message.internalDate ? Number(message.internalDate) : NaN; const dateHeader = headerValue(headers, "Date"); const sentAt = Number.isFinite(sentAtMs) ? new Date(sentAtMs) : dateHeader ? new Date(dateHeader) : new Date(0); return { providerMessageId: message.id, providerThreadId: message.threadId ?? null, internetMessageId: normalizeInternetMessageId(headerValue(headers, "Message-ID") ?? headerValue(headers, "Message-Id")), direction: labels.includes("SENT") ? "outbound" : "inbound", from, to: parseAddressList(headerValue(headers, "To")), cc: parseAddressList(headerValue(headers, "Cc")), bcc: parseAddressList(headerValue(headers, "Bcc")), subject: headerValue(headers, "Subject"), snippet: buildSnippet(message.snippet, walk.text), bodyHtml: walk.html, bodyText: walk.text, sentAt, receivedAt: labels.includes("SENT") ? null : sentAt, isRead: !labels.includes("UNREAD"), hasAttachments: walk.attachments.length > 0, isNewsletter: headerValue(headers, "List-Unsubscribe") !== null, providerLabels: labels, attachments: walk.attachments, }; } // --- Microsoft Graph ----------------------------------------------------------- function graphAddress(entry: { emailAddress?: { address?: string; name?: string } } | undefined): MappedEmailAddress | null { const address = entry?.emailAddress?.address?.toLowerCase(); if (!address) return null; const name = entry?.emailAddress?.name; return name ? { address, name } : { address }; } function graphAddresses(list: ReadonlyArray<{ emailAddress?: { address?: string; name?: string } }> | undefined): MappedEmailAddress[] { return (list ?? []).map(graphAddress).filter((a): a is MappedEmailAddress => a !== null); } /** * Map a Graph message into the neutral shape. Direction is derived from the * folder the delta ran on (`sentitems` → outbound) — Graph messages carry no * SENT label. `isNewsletter` needs internetMessageHeaders (only present on a * single-message fetch with $expand) — false when absent. */ export function mapGraphMessage(message: GraphMessage, folderId: string): MappedEmailMessage { const isHtml = (message.body?.contentType ?? "").toLowerCase() === "html"; const bodyContent = message.body?.content ?? null; const listUnsubscribe = (message.internetMessageHeaders ?? []).some((h) => (h.name ?? "").toLowerCase() === "list-unsubscribe"); const sentAt = message.sentDateTime ? new Date(message.sentDateTime) : new Date(0); const direction: MappedEmailMessage["direction"] = folderId === "sentitems" ? "outbound" : "inbound"; return { providerMessageId: message.id, providerThreadId: message.conversationId ?? null, internetMessageId: normalizeInternetMessageId(message.internetMessageId), direction, from: graphAddress(message.from) ?? { address: "" }, to: graphAddresses(message.toRecipients), cc: graphAddresses(message.ccRecipients), bcc: graphAddresses(message.bccRecipients), subject: message.subject ?? null, snippet: buildSnippet(message.bodyPreview, isHtml ? null : bodyContent), bodyHtml: isHtml ? bodyContent : null, bodyText: isHtml ? null : bodyContent, sentAt, receivedAt: message.receivedDateTime ? new Date(message.receivedDateTime) : null, isRead: message.isRead ?? false, hasAttachments: message.hasAttachments ?? false, isNewsletter: listUnsubscribe, providerLabels: [folderId], // Graph attachments are listed via a separate call (listGraphAttachments). attachments: [], }; } /** * Build an RFC-2822 raw message for the Gmail send path (base64url encoding is * the caller's job). Minimal MIME: multipart/mixed when attachments are present, * otherwise a single text/html part. Threading headers (In-Reply-To/References) * keep replies in the recipient's thread (M09 Block G). */ export function buildRfc2822Message(input: { readonly fromAddress: string; readonly fromName?: string; readonly to: readonly MappedEmailAddress[]; readonly cc?: readonly MappedEmailAddress[]; readonly bcc?: readonly MappedEmailAddress[]; readonly subject: string; readonly bodyHtml: string; readonly inReplyToInternetMessageId?: string | null; readonly referencesInternetMessageIds?: readonly string[]; readonly attachments?: ReadonlyArray<{ filename: string; mimeType: string; contentBase64: string }>; }): string { const encodeWord = (value: string): string => /[^\x20-\x7e]/.test(value) ? `=?UTF-8?B?${Buffer.from(value, "utf8").toString("base64")}?=` : value; const formatAddress = (a: MappedEmailAddress): string => (a.name ? `${encodeWord(a.name)} <${a.address}>` : a.address); const headers: string[] = [ `From: ${formatAddress({ address: input.fromAddress, name: input.fromName })}`, `To: ${input.to.map(formatAddress).join(", ")}`, ]; if (input.cc?.length) headers.push(`Cc: ${input.cc.map(formatAddress).join(", ")}`); if (input.bcc?.length) headers.push(`Bcc: ${input.bcc.map(formatAddress).join(", ")}`); headers.push(`Subject: ${encodeWord(input.subject)}`); if (input.inReplyToInternetMessageId) { headers.push(`In-Reply-To: <${input.inReplyToInternetMessageId}>`); } if (input.referencesInternetMessageIds?.length) { headers.push(`References: ${input.referencesInternetMessageIds.map((id) => `<${id}>`).join(" ")}`); } headers.push("MIME-Version: 1.0"); const htmlPart = `Content-Type: text/html; charset="UTF-8"\r\nContent-Transfer-Encoding: base64\r\n\r\n${Buffer.from(input.bodyHtml, "utf8").toString("base64")}`; if (!input.attachments?.length) { return `${headers.join("\r\n")}\r\n${htmlPart}`; } const boundary = `hg_${Math.abs(hashCode(input.subject + input.fromAddress + String(input.to.length)))}_mime`; headers.push(`Content-Type: multipart/mixed; boundary="${boundary}"`); const attachmentParts = input.attachments .map( (a) => `--${boundary}\r\nContent-Type: ${a.mimeType}; name="${a.filename}"\r\nContent-Disposition: attachment; filename="${a.filename}"\r\nContent-Transfer-Encoding: base64\r\n\r\n${a.contentBase64}`, ) .join("\r\n"); return `${headers.join("\r\n")}\r\n\r\n--${boundary}\r\n${htmlPart}\r\n${attachmentParts}\r\n--${boundary}--`; } function hashCode(value: string): number { let hash = 0; for (let i = 0; i < value.length; i += 1) { hash = (hash << 5) - hash + value.charCodeAt(i); hash |= 0; } return hash; } /** Base64url-encode a raw RFC-2822 message for Gmail messages.send. */ export function toBase64Url(raw: string): string { return Buffer.from(raw, "utf8").toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, ""); }