Update hivegrid-cloud reference to latest main

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
davidandClaude Fable 5 committed 2026-07-08 16:15:37 +02:00
1 parent e98d38e716
commit 7b21524c86
3781 files changed
+373484 -225607

No files matched your search

@@ -0,0 +1,302 @@
// 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 <a@x.de>, b@y.de"). Deliberately
* simple: split on commas outside quotes/brackets, extract `<addr>` 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(/=+$/, "");
}