Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/packages/db/src/email-suppression.server.ts
T
2026-07-08 16:15:37 +02:00

79 lines
3.1 KiB
TypeScript

// 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<EmailSuppressionRow>;
findUnique(args: {
where: { tenantId_emailAddress: { tenantId: string; emailAddress: string } };
}): Promise<EmailSuppressionRow | null>;
};
};
/** 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<EmailSuppressionRow> {
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<boolean> {
const emailAddress = normalizeSuppressionAddress(input.emailAddress);
const row = await client.emailSuppressionList.findUnique({
where: { tenantId_emailAddress: { tenantId: input.tenantId, emailAddress } },
});
return row !== null;
}