// AK-P14a · P14 Email — per-tenant suppression list service. // // The suppression list is the system-of-record for addresses that must NOT be // sent to: hard bounces and spam complaints (fed by the Mailjet event webhook) // plus manual additions from the senders/suppression screen. `recordEmailSuppression` // is idempotent (upsert on the (tenantId, emailAddress) unique) so a webhook that // re-fires never duplicates. `isEmailSuppressed` is the pre-send guard the // marketing path (AK-P14b) calls before every send. // // The client is injectable (a narrow structural interface) so the unit tests run // against an in-memory fake — same stance as email-sequences.server.ts. import { getDbClient } from "./client.server.js"; export type EmailSuppressionReason = "bounce" | "complaint" | "manual"; export type RecordEmailSuppressionInput = { tenantId: string; emailAddress: string; reason: EmailSuppressionReason; detail?: string | null; }; export type EmailSuppressionRow = { id: string; tenantId: string; emailAddress: string; reason: EmailSuppressionReason; detail: string | null; }; export type EmailSuppressionClient = { emailSuppressionList: { upsert(args: { where: { tenantId_emailAddress: { tenantId: string; emailAddress: string } }; create: { tenantId: string; emailAddress: string; reason: EmailSuppressionReason; detail: string | null }; update: { reason: EmailSuppressionReason; detail: string | null }; }): Promise; findUnique(args: { where: { tenantId_emailAddress: { tenantId: string; emailAddress: string } }; }): Promise; }; }; /** Normalize an address for storage + comparison: trimmed + lower-cased. */ export function normalizeSuppressionAddress(emailAddress: string): string { return emailAddress.trim().toLowerCase(); } /** * Idempotently record a suppressed address. A repeat call updates the reason + * detail (e.g. a manual entry later confirmed by a real bounce) but never * duplicates. Returns the stored row. */ export function recordEmailSuppression( input: RecordEmailSuppressionInput, client: EmailSuppressionClient = getDbClient() as unknown as EmailSuppressionClient, ): Promise { const emailAddress = normalizeSuppressionAddress(input.emailAddress); const detail = input.detail ?? null; return client.emailSuppressionList.upsert({ where: { tenantId_emailAddress: { tenantId: input.tenantId, emailAddress } }, create: { tenantId: input.tenantId, emailAddress, reason: input.reason, detail }, update: { reason: input.reason, detail }, }); } /** Pre-send guard: true when the address is on the tenant's suppression list. */ export async function isEmailSuppressed( input: { tenantId: string; emailAddress: string }, client: EmailSuppressionClient = getDbClient() as unknown as EmailSuppressionClient, ): Promise { const emailAddress = normalizeSuppressionAddress(input.emailAddress); const row = await client.emailSuppressionList.findUnique({ where: { tenantId_emailAddress: { tenantId: input.tenantId, emailAddress } }, }); return row !== null; }