Refresh HiveGrid Cloud reference snapshot

This commit is contained in:
david committed 2026-08-03 15:31:14 +02:00
1 parent 5e99e14772
commit 7f88026f79
5955 files changed
+1177325 -188362

No files matched your search

@@ -0,0 +1,291 @@
import type { MappedEmailMessage } from "./email-message-mapping.js";
export type AdminEmailMatchCandidate = {
readonly id: string;
readonly kind: "contact" | "lead";
readonly primary?: boolean;
readonly openDealIds?: readonly string[];
};
export type AdminEmailMatchDecision = {
readonly status: "matched" | "ambiguous" | "unmatched";
readonly contactId: string | null;
readonly leadId: string | null;
readonly dealId: string | null;
readonly reason:
| "exact_contact"
| "exact_lead"
| "subject_deal"
| "single_open_deal"
| "ambiguous_identity"
| "ambiguous_deal"
| "newsletter"
| "no_candidate";
readonly candidates: readonly AdminEmailMatchCandidate[];
};
export type AdminMailboxCursorState = {
readonly cursorToken: string | null;
readonly status: "pending" | "running" | "complete" | "failed";
readonly recoveryGeneration: number;
readonly lastErrorMessageKey: string | null;
};
const DEAL_REFERENCE = /\[\s*Deal\s*#\s*([\w-]+)\s*\]/i;
export function decideAdminEmailMatch(input: {
readonly message: Pick<
MappedEmailMessage,
"direction" | "from" | "to" | "subject" | "isNewsletter"
>;
readonly mailboxAddresses: readonly string[];
readonly candidates: readonly AdminEmailMatchCandidate[];
}): AdminEmailMatchDecision {
if (input.message.isNewsletter) {
return decision("unmatched", "newsletter", input.candidates);
}
const counterpart = adminEmailCounterpartAddress(
input.message,
input.mailboxAddresses
);
const candidates = counterpart
? [...input.candidates].sort((left, right) => left.id.localeCompare(right.id))
: [];
const contacts = candidates.filter((candidate) => candidate.kind === "contact");
const leads = candidates.filter((candidate) => candidate.kind === "lead");
const contact = selectSingleIdentity(contacts);
if (contacts.length > 0 && !contact) {
return decision("ambiguous", "ambiguous_identity", candidates);
}
if (!contact && leads.length > 1) {
return decision("ambiguous", "ambiguous_identity", candidates);
}
const identity = contact ?? leads[0] ?? null;
if (!identity) {
return decision("unmatched", "no_candidate", candidates);
}
const subjectDealId = input.message.subject?.match(DEAL_REFERENCE)?.[1] ?? null;
const openDealIds = [...new Set(identity.openDealIds ?? [])].sort();
if (subjectDealId) {
if (!openDealIds.includes(subjectDealId)) {
return decision("ambiguous", "ambiguous_deal", candidates, identity);
}
return decision("matched", "subject_deal", candidates, identity, subjectDealId);
}
if (openDealIds.length > 1) {
return decision("ambiguous", "ambiguous_deal", candidates, identity);
}
return decision(
"matched",
openDealIds.length === 1
? "single_open_deal"
: identity.kind === "contact"
? "exact_contact"
: "exact_lead",
candidates,
identity,
openDealIds[0] ?? null
);
}
export function adminEmailCounterpartAddress(
message: Pick<MappedEmailMessage, "direction" | "from" | "to">,
mailboxAddresses: readonly string[]
): string | null {
const own = new Set(mailboxAddresses.map(normalizeEmail));
if (message.direction === "inbound") {
const address = normalizeEmail(message.from.address);
return address && !own.has(address) ? address : null;
}
return (
message.to
.map((recipient) => normalizeEmail(recipient.address))
.find((address) => address.length > 0 && !own.has(address)) ?? null
);
}
export function providerMessageKey(input: {
readonly mailboxId: string;
readonly providerMessageId: string;
}): string {
const mailboxId = requiredToken(input.mailboxId, "mailboxId");
const providerMessageId = requiredToken(
input.providerMessageId,
"providerMessageId"
);
return `${mailboxId}:${providerMessageId}`;
}
export function advanceAdminMailboxCursor(input: {
readonly current: AdminMailboxCursorState;
readonly nextCursor: string | null;
readonly outcome: "success" | "retryable_failure" | "cursor_expired";
readonly errorMessageKey?: string | null;
}): AdminMailboxCursorState {
if (input.outcome === "cursor_expired") {
return Object.freeze({
cursorToken: null,
status: "pending",
recoveryGeneration: input.current.recoveryGeneration + 1,
lastErrorMessageKey: "admin.sales.email.sync.cursorExpired",
});
}
if (input.outcome === "retryable_failure") {
return Object.freeze({
...input.current,
status: "failed",
lastErrorMessageKey:
input.errorMessageKey ?? "admin.sales.email.sync.retryableFailure",
});
}
const nextCursor = requiredToken(input.nextCursor ?? "", "nextCursor");
return Object.freeze({
cursorToken: nextCursor,
status: "complete",
recoveryGeneration: input.current.recoveryGeneration,
lastErrorMessageKey: null,
});
}
export type AdminEmailSyncRepository = {
persistBatch(input: {
readonly adminUserId: string;
readonly mailboxId: string;
readonly externalFolderId: string;
readonly expectedCursor: string | null;
readonly nextCursor: string;
readonly messages: ReadonlyArray<{
readonly key: string;
readonly message: MappedEmailMessage;
readonly match: AdminEmailMatchDecision;
readonly attachments: readonly AdminPreparedEmailAttachment[];
}>;
}): Promise<{
readonly upserted: number;
readonly replayed: number;
readonly messages?: readonly {
readonly providerMessageId: string;
readonly messageId: string;
readonly dealId: string | null;
}[];
}>;
};
export type AdminPreparedEmailAttachment = {
readonly providerAttachmentId: string;
readonly filename: string;
readonly mimeType: string | null;
readonly sizeBytes: number;
readonly storageBucket: string;
readonly storageKey: string;
readonly checksumSha256: string;
readonly scannedAt: Date;
};
export function createAdminEmailSyncService(repository: AdminEmailSyncRepository) {
return {
async persistProviderBatch(input: {
readonly adminUserId: string;
readonly mailboxId: string;
readonly mailboxAddresses: readonly string[];
readonly externalFolderId: string;
readonly expectedCursor: string | null;
readonly nextCursor: string;
readonly messages: readonly MappedEmailMessage[];
readonly candidatesFor: (
counterpartAddress: string | null
) => Promise<readonly AdminEmailMatchCandidate[]>;
readonly attachmentsFor?: (
message: MappedEmailMessage
) => Promise<readonly AdminPreparedEmailAttachment[]>;
}) {
const messages = [];
for (const message of input.messages) {
const counterpart = adminEmailCounterpartAddress(
message,
input.mailboxAddresses
);
const candidates = await input.candidatesFor(counterpart);
messages.push({
key: providerMessageKey({
mailboxId: input.mailboxId,
providerMessageId: message.providerMessageId,
}),
message,
match: decideAdminEmailMatch({
message,
mailboxAddresses: input.mailboxAddresses,
candidates,
}),
attachments: input.attachmentsFor
? await input.attachmentsFor(message)
: [],
});
}
return repository.persistBatch({
adminUserId: requiredToken(input.adminUserId, "adminUserId"),
mailboxId: requiredToken(input.mailboxId, "mailboxId"),
externalFolderId: requiredToken(
input.externalFolderId,
"externalFolderId"
),
expectedCursor: input.expectedCursor,
nextCursor: requiredToken(input.nextCursor, "nextCursor"),
messages,
});
},
};
}
function selectSingleIdentity(
candidates: readonly AdminEmailMatchCandidate[]
): AdminEmailMatchCandidate | null {
if (candidates.length === 1) return candidates[0] ?? null;
const primaries = candidates.filter((candidate) => candidate.primary);
return primaries.length === 1 ? primaries[0] ?? null : null;
}
function decision(
status: AdminEmailMatchDecision["status"],
reason: AdminEmailMatchDecision["reason"],
candidates: readonly AdminEmailMatchCandidate[],
identity: AdminEmailMatchCandidate | null = null,
dealId: string | null = null
): AdminEmailMatchDecision {
return Object.freeze({
status,
contactId: identity?.kind === "contact" ? identity.id : null,
leadId: identity?.kind === "lead" ? identity.id : null,
dealId,
reason,
candidates: Object.freeze([...candidates]),
});
}
function normalizeEmail(value: string): string {
return value.trim().toLowerCase();
}
function requiredToken(value: string, field: string): string {
const normalized = value.trim();
if (!normalized || normalized.length > 1_024) {
throw new AdminEmailSyncError("invalid_sync_input", field);
}
return normalized;
}
export class AdminEmailSyncError extends Error {
readonly code = "invalid_sync_input";
readonly field: string;
constructor(code: "invalid_sync_input", field: string) {
super(code);
this.name = "AdminEmailSyncError";
this.field = field;
}
}