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

@@ -1,5 +1,4 @@
import { useSubmit, Outlet, useLoaderData, useActionData } from "react-router";
import { useEffect } from "react";
import { useTranslation } from "react-i18next";
import InfoBanner from "~/components/ui/banners/InfoBanner";
import WarningBanner from "~/components/ui/banners/WarningBanner";
@@ -8,7 +7,7 @@ import TableSimple from "~/components/ui/tables/TableSimple";
import { useAppOrAdminData } from "~/utils/data/useAppOrAdminData";
import { EmailSenderWithoutApiKey } from "../../db/emailSender";
import { Senders_List } from "../../routes/Senders_List";
import toast from "react-hot-toast";
import { useSaveToast } from "~/hooks/use-save-toast";
export default function SendersListRoute() {
const data = useLoaderData<Senders_List.LoaderData>();
@@ -18,13 +17,7 @@ export default function SendersListRoute() {
const actionData = useActionData<Senders_List.ActionData>();
const hasMailjetSenders = data.items.some((item) => item.provider === "mailjet");
useEffect(() => {
if (actionData?.success) {
toast.success(actionData.success);
} else if (actionData?.error) {
toast.error(actionData.error);
}
}, [actionData]);
useSaveToast(actionData);
function sendTest(item: EmailSenderWithoutApiKey) {
const email = window.prompt(t("emailMarketing:senders.testEmail.prompt"), appOrAdminData.user?.email);
@@ -1,17 +1,65 @@
// @vitest-environment node
import { describe, expect, test } from "vitest";
import { readRepoFile } from "~/utils/testing/repoPaths";
import { beforeEach, describe, expect, it, vi } from "vitest";
const source = readRepoFile("apps/web/app/modules/emailMarketing/db/campaigns.db.server.ts");
vi.mock("~/utils/db.server", () => ({
db: {
$executeRaw: vi.fn(),
$transaction: vi.fn(async (callback: (tx: unknown) => Promise<unknown>) =>
callback({
$executeRaw: vi.fn(),
campaign: { findMany: vi.fn() },
}),
),
campaign: {
findMany: vi.fn(),
},
},
}));
describe("campaign db tenant scope", () => {
test("updates campaigns and recipient replacement through tenant scope", () => {
expect(source).toContain("export async function updateCampaign(");
expect(source).toContain("tenantId: string | null,");
expect(source).toContain("db.campaign.updateMany");
expect(source).toContain("where: {\n id,\n tenantId,");
expect(source).toContain('throw new Error("Campaign not found for tenant scope.")');
expect(source).toContain("db.outboundEmail.deleteMany");
expect(source).toContain("campaignId: id,\n tenantId,");
import { db } from "~/utils/db.server";
import { getAllCampaigns, getCampaignOptions } from "./campaigns.db.server";
const findManyMock = vi.mocked(db.campaign.findMany);
describe("campaign list queries", () => {
beforeEach(() => {
vi.clearAllMocks();
findManyMock.mockResolvedValue([]);
vi.mocked(db.$transaction).mockImplementation(async (callback) =>
callback({
$executeRaw: vi.fn(),
campaign: { findMany: findManyMock },
} as never),
);
});
it("selects only list metrics instead of loading bodies, senders, variants, and tracking event rows", async () => {
await getAllCampaigns("tenant-1");
expect(findManyMock).toHaveBeenCalledWith({
where: { tenantId: "tenant-1" },
select: {
id: true,
name: true,
status: true,
sentAt: true,
recipients: {
select: {
deliveredAt: true,
_count: { select: { opens: true, clicks: true } },
},
},
},
orderBy: { sentAt: "desc" },
});
});
it("uses an id/name-only query for outbound-email filter options", async () => {
await getCampaignOptions("tenant-1");
expect(findManyMock).toHaveBeenCalledWith({
where: { tenantId: "tenant-1" },
select: { id: true, name: true },
orderBy: [{ sentAt: "desc" }, { name: "asc" }],
});
});
});
@@ -1,55 +1,90 @@
import type { Campaign, EmailSender, OutboundEmail, OutboundEmailClick, OutboundEmailOpen } from "@hivegrid/db/prisma-browser";
import { db } from "~/utils/db.server";
import type { Campaign, CampaignVariant, EmailSender, OutboundEmail, OutboundEmailClick, OutboundEmailOpen } from "@hivegrid/db/prisma-browser";
import { withEmailMarketingScope } from "./emailMarketingScope.server";
// R-P14C (AD-2): the legacy Entity-Builder contactRow join is removed. The typed
// recipient link is the bare `kontaktId` scalar on OutboundEmail (AK-P14b).
export type CampaignWithDetails = Campaign & {
emailSender: EmailSender;
variants: CampaignVariant[];
recipients: (OutboundEmail & {
campaign: Campaign | null;
opens: OutboundEmailOpen[];
clicks: OutboundEmailClick[];
})[];
};
export async function getAllCampaigns(tenantId: string | null, status?: string): Promise<CampaignWithDetails[]> {
return await db.campaign.findMany({
where: {
tenantId,
status,
},
include: {
emailSender: true,
recipients: {
include: {
campaign: true,
opens: true,
clicks: true,
export type CampaignListItem = Pick<Campaign, "id" | "name" | "status" | "sentAt"> & {
recipients: Array<{
deliveredAt: Date | null;
_count: { opens: number; clicks: number };
}>;
};
export type CampaignOption = Pick<Campaign, "id" | "name">;
export async function getAllCampaigns(tenantId: string | null, status?: string, query?: string): Promise<CampaignListItem[]> {
return withEmailMarketingScope(tenantId, (client) =>
client.campaign.findMany({
where: {
tenantId,
...(status ? { status } : {}),
...(query?.trim()
? {
OR: [{ name: { contains: query.trim(), mode: "insensitive" } }, { subject: { contains: query.trim(), mode: "insensitive" } }],
}
: {}),
},
select: {
id: true,
name: true,
status: true,
sentAt: true,
recipients: {
select: {
deliveredAt: true,
_count: {
select: { opens: true, clicks: true },
},
},
},
},
},
orderBy: {
sentAt: "desc",
},
});
orderBy: {
sentAt: "desc",
},
})
);
}
export async function getCampaignOptions(tenantId: string | null): Promise<CampaignOption[]> {
return withEmailMarketingScope(tenantId, (client) =>
client.campaign.findMany({
where: { tenantId },
select: { id: true, name: true },
orderBy: [{ sentAt: "desc" }, { name: "asc" }],
})
);
}
export async function getCampaign(id: string, tenantId: string | null): Promise<CampaignWithDetails | null> {
return await db.campaign.findFirst({
where: {
id,
tenantId,
},
include: {
emailSender: true,
recipients: {
include: {
campaign: true,
opens: true,
clicks: true,
return withEmailMarketingScope(tenantId, (client) =>
client.campaign.findFirst({
where: {
id,
tenantId,
},
include: {
emailSender: true,
variants: true,
recipients: {
include: {
campaign: true,
opens: true,
clicks: true,
},
},
},
},
});
})
) as Promise<CampaignWithDetails | null>;
}
export async function createCampaign(
@@ -64,23 +99,23 @@ export async function createCampaign(
},
recipients: { fromSenderId: string; email: string; kontaktId: string }[]
): Promise<Campaign> {
const item = await db.campaign.create({
data: {
...data,
recipients: {
create: recipients.map((recipient) => {
return {
tenantId: data.tenantId,
kontaktId: recipient.kontaktId,
email: recipient.email,
fromSenderId: recipient.fromSenderId,
};
}),
return withEmailMarketingScope(data.tenantId, (client) =>
client.campaign.create({
data: {
...data,
recipients: {
create: recipients.map((recipient) => {
return {
tenantId: data.tenantId,
kontaktId: recipient.kontaktId,
email: recipient.email,
fromSenderId: recipient.fromSenderId,
};
}),
},
},
},
});
return item;
})
);
}
export async function updateCampaign(
@@ -97,62 +132,55 @@ export async function updateCampaign(
},
recipients?: { fromSenderId: string; email: string; kontaktId: string }[]
): Promise<Campaign> {
const result = await db.campaign.updateMany({
where: {
id,
tenantId,
},
data,
});
if (result.count !== 1) {
throw new Error("Campaign not found for tenant scope.");
}
const item = await db.campaign.findFirstOrThrow({
where: {
id,
tenantId,
},
});
if (recipients) {
await db.outboundEmail.deleteMany({
return withEmailMarketingScope(tenantId, async (client) => {
const result = await client.campaign.updateMany({
where: {
campaignId: id,
id,
tenantId,
},
data,
});
await db.outboundEmail.createMany({
data: recipients.map((recipient) => {
return {
if (result.count !== 1) {
throw new Error("Campaign not found for tenant scope.");
}
const item = await client.campaign.findFirstOrThrow({ where: { id, tenantId } });
if (recipients) {
await client.outboundEmail.deleteMany({ where: { campaignId: id, tenantId } });
await client.outboundEmail.createMany({
data: recipients.map((recipient) => ({
tenantId: item.tenantId,
campaignId: id,
kontaktId: recipient.kontaktId,
email: recipient.email,
fromSenderId: recipient.fromSenderId,
};
}),
});
}
return item;
})),
});
}
return item;
});
}
export async function deleteCampaign(id: string, tenantId: string | null) {
return await db.campaign.deleteMany({
where: {
id,
tenantId,
},
});
return withEmailMarketingScope(tenantId, (client) =>
client.campaign.deleteMany({
where: {
id,
tenantId,
},
})
);
}
export async function groupCampaigns(tenantId: string | null) {
return await db.campaign.groupBy({
by: ["status"],
where: {
tenantId,
},
_count: {
_all: true,
},
});
return withEmailMarketingScope(tenantId, (client) =>
client.campaign.groupBy({
by: ["status"],
where: {
tenantId,
},
_count: {
_all: true,
},
})
);
}
@@ -0,0 +1,15 @@
import type { Prisma } from "@hivegrid/db/prisma-browser";
import { withTenantRLS } from "~/utils/db/.server/tenantRls.server";
import { db } from "~/utils/db.server";
/**
* Binds tenant routes to the transaction-local Forced-RLS context. The null
* branch is intentionally limited to already-authenticated platform-admin
* routes, which have no tenant role or tenant GUC to bind.
*/
export function withEmailMarketingScope<T>(tenantId: string | null, callback: (client: Prisma.TransactionClient) => Promise<T>): Promise<T> {
if (tenantId) {
return withTenantRLS(tenantId, callback);
}
return callback(db as unknown as Prisma.TransactionClient);
}
@@ -1,60 +1,66 @@
import type { EmailSender } from "@hivegrid/db/prisma-browser";
import { db } from "~/utils/db.server";
import { withEmailMarketingScope } from "./emailMarketingScope.server";
export type EmailSenderWithoutApiKey = Omit<EmailSender, "apiKey" | "apiSecret">;
export async function getAllEmailSenders(tenantId: string | null): Promise<EmailSenderWithoutApiKey[]> {
return await db.emailSender.findMany({
where: {
tenantId,
},
select: {
id: true,
tenantId: true,
provider: true,
stream: true,
fromName: true,
fromEmail: true,
replyToEmail: true,
isDefault: true,
isDemoData: true,
sendingDomainId: true,
},
orderBy: [
{
fromName: "asc",
return withEmailMarketingScope(tenantId, (client) =>
client.emailSender.findMany({
where: {
tenantId,
},
],
});
select: {
id: true,
tenantId: true,
provider: true,
stream: true,
fromName: true,
fromEmail: true,
replyToEmail: true,
isDefault: true,
isDemoData: true,
sendingDomainId: true,
},
orderBy: [
{
fromName: "asc",
},
],
})
);
}
export async function getEmailSender(id: string, tenantId: string | null): Promise<EmailSender | null> {
return await db.emailSender.findFirst({
where: {
id,
tenantId,
},
});
return withEmailMarketingScope(tenantId, (client) =>
client.emailSender.findFirst({
where: {
id,
tenantId,
},
})
);
}
export async function getEmailSenderWithoutApiKey(id: string, tenantId: string | null): Promise<EmailSenderWithoutApiKey | null> {
return await db.emailSender.findFirst({
where: {
id,
tenantId,
},
select: {
id: true,
tenantId: true,
provider: true,
stream: true,
fromName: true,
fromEmail: true,
replyToEmail: true,
isDefault: true,
isDemoData: true,
sendingDomainId: true,
},
});
return withEmailMarketingScope(tenantId, (client) =>
client.emailSender.findFirst({
where: {
id,
tenantId,
},
select: {
id: true,
tenantId: true,
provider: true,
stream: true,
fromName: true,
fromEmail: true,
replyToEmail: true,
isDefault: true,
isDemoData: true,
sendingDomainId: true,
},
})
);
}
export async function createEmailSender(data: {
@@ -67,11 +73,7 @@ export async function createEmailSender(data: {
fromName?: string;
replyToEmail?: string;
}): Promise<EmailSender> {
const item = await db.emailSender.create({
data,
});
return item;
return withEmailMarketingScope(data.tenantId, (client) => client.emailSender.create({ data }));
}
export async function updateEmailSender(
@@ -85,37 +87,22 @@ export async function updateEmailSender(
replyToEmail?: string;
}
): Promise<EmailSender> {
const result = await db.emailSender.updateMany({
where: { id, tenantId },
data,
return withEmailMarketingScope(tenantId, async (client) => {
const result = await client.emailSender.updateMany({ where: { id, tenantId }, data });
if (result.count !== 1) throw new Error("Email sender not found");
const item = await client.emailSender.findFirst({ where: { id, tenantId } });
if (!item) throw new Error("Email sender not found");
return item;
});
if (result.count !== 1) {
throw new Error("Email sender not found");
}
const item = await getEmailSender(id, tenantId);
if (!item) {
throw new Error("Email sender not found");
}
return item;
}
export async function deleteEmailSender(id: string, tenantId: string | null): Promise<EmailSender> {
const existing = await getEmailSender(id, tenantId);
if (!existing) {
throw new Error("Email sender not found");
}
await db.outboundEmail.deleteMany({
where: { fromSenderId: id, tenantId },
return withEmailMarketingScope(tenantId, async (client) => {
const existing = await client.emailSender.findFirst({ where: { id, tenantId } });
if (!existing) throw new Error("Email sender not found");
await client.outboundEmail.deleteMany({ where: { fromSenderId: id, tenantId } });
const result = await client.emailSender.deleteMany({ where: { id, tenantId } });
if (result.count !== 1) throw new Error("Email sender not found");
return existing;
});
const result = await db.emailSender.deleteMany({
where: { id, tenantId },
});
if (result.count !== 1) {
throw new Error("Email sender not found");
}
return existing;
}
@@ -0,0 +1,68 @@
import { beforeEach, describe, expect, it, vi } from "vitest";
const mocks = vi.hoisted(() => ({
outboundEmail: {
findMany: vi.fn(),
count: vi.fn(),
findFirst: vi.fn(),
},
}));
vi.mock("~/utils/db.server", () => ({
db: {
outboundEmail: mocks.outboundEmail,
$transaction: vi.fn(async (callback: (tx: unknown) => Promise<unknown>) =>
callback({
$executeRaw: vi.fn(),
outboundEmail: mocks.outboundEmail,
}),
),
},
}));
import { getAllOutboundEmails, hasDeliveredOutboundEmail } from "./outboundEmails.db.server";
describe("outbound email activity list projection", () => {
beforeEach(() => {
vi.clearAllMocks();
mocks.outboundEmail.findMany.mockResolvedValue([]);
mocks.outboundEmail.count.mockResolvedValue(0);
});
it("selects only display fields and never signed recipient handles", async () => {
await getAllOutboundEmails("tenant-a", { pagination: { page: 1, pageSize: 25 } });
const query = mocks.outboundEmail.findMany.mock.calls[0]?.[0];
expect(query.where).toEqual({ tenantId: "tenant-a" });
expect(query).not.toHaveProperty("include");
expect(query.select).not.toHaveProperty("unsubscribeToken");
expect(query.select).not.toHaveProperty("trackingToken");
expect(query.select).not.toHaveProperty("kontaktId");
expect(query.select).toMatchObject({
id: true,
email: true,
campaign: { select: { id: true, name: true } },
opens: { select: { createdAt: true, firstOpen: true } },
clicks: { select: { createdAt: true, link: true } },
});
});
});
describe("hasDeliveredOutboundEmail", () => {
beforeEach(() => vi.clearAllMocks());
it("loads only one id instead of the complete delivery history", async () => {
mocks.outboundEmail.findFirst.mockResolvedValue({ id: "email_1" });
await expect(hasDeliveredOutboundEmail("tenant_1")).resolves.toBe(true);
expect(mocks.outboundEmail.findFirst).toHaveBeenCalledWith({
where: { tenantId: "tenant_1", deliveredAt: { not: null } },
select: { id: true },
});
});
it("returns false when no delivery exists", async () => {
mocks.outboundEmail.findFirst.mockResolvedValue(null);
await expect(hasDeliveredOutboundEmail("tenant_1")).resolves.toBe(false);
});
});
@@ -1,15 +1,28 @@
import type { Campaign, OutboundEmail, OutboundEmailClick, OutboundEmailOpen, Prisma } from "@hivegrid/db/prisma-browser";
import type { OutboundEmail, Prisma } from "@hivegrid/db/prisma-browser";
import Constants from "~/application/Constants";
import { PaginationDto } from "~/application/dtos/data/PaginationDto";
import { db } from "~/utils/db.server";
import { withEmailMarketingScope } from "./emailMarketingScope.server";
// R-P14C (AD-2): the legacy Entity-Builder contactRow join is removed; the typed
// recipient link is the bare `kontaktId` scalar on OutboundEmail (AK-P14b).
export type OutboundEmailWithDetails = OutboundEmail & {
campaign: Campaign | null;
opens: OutboundEmailOpen[];
clicks: OutboundEmailClick[];
};
const OUTBOUND_EMAIL_LIST_SELECT = {
id: true,
createdAt: true,
campaignId: true,
email: true,
isPreview: true,
error: true,
sentAt: true,
deliveredAt: true,
bouncedAt: true,
spamComplainedAt: true,
unsubscribedAt: true,
campaign: { select: { id: true, name: true } },
opens: { select: { createdAt: true, firstOpen: true } },
clicks: { select: { createdAt: true, link: true } },
} as const satisfies Prisma.OutboundEmailSelect;
// Explicit loader DTO: signed unsubscribe/tracking handles and unrelated
// recipient ledger fields must never be serialized by the activity list.
export type OutboundEmailWithDetails = Prisma.OutboundEmailGetPayload<{ select: typeof OUTBOUND_EMAIL_LIST_SELECT }>;
export async function getAllOutboundEmails(
tenantId: string | null,
@@ -18,86 +31,57 @@ export async function getAllOutboundEmails(
pagination: { page: number; pageSize: number };
}
): Promise<{ items: OutboundEmailWithDetails[]; pagination: PaginationDto }> {
const items = await db.outboundEmail.findMany({
take: options.pagination.pageSize,
skip: options.pagination.pageSize * (options.pagination.page - 1),
where: {
tenantId,
...options.where,
},
include: {
campaign: true,
opens: true,
clicks: true,
},
orderBy: [{ sentAt: "desc" }],
});
const totalItems = await db.outboundEmail.count({
where: {
tenantId,
...options.where,
},
});
return {
items,
pagination: {
page: options.pagination?.page ?? 1,
pageSize: options.pagination.pageSize ?? Constants.DEFAULT_PAGE_SIZE,
totalItems,
totalPages: Math.ceil(totalItems / (options.pagination?.pageSize ?? Constants.DEFAULT_PAGE_SIZE)),
},
};
}
export async function findOutboundEmails(
tenantId: string | null,
options: {
where?: Prisma.OutboundEmailWhereInput;
}
) {
return await db.outboundEmail.findMany({
where: {
tenantId,
...options.where,
},
include: {
campaign: true,
opens: true,
clicks: true,
},
orderBy: [{ sentAt: "desc" }],
return withEmailMarketingScope(tenantId, async (client) => {
const items = await client.outboundEmail.findMany({
take: options.pagination.pageSize,
skip: options.pagination.pageSize * (options.pagination.page - 1),
where: { tenantId, ...options.where },
select: OUTBOUND_EMAIL_LIST_SELECT,
orderBy: [{ sentAt: "desc" }],
});
const totalItems = await client.outboundEmail.count({ where: { tenantId, ...options.where } });
return {
items,
pagination: {
page: options.pagination?.page ?? 1,
pageSize: options.pagination.pageSize ?? Constants.DEFAULT_PAGE_SIZE,
totalItems,
totalPages: Math.ceil(totalItems / (options.pagination?.pageSize ?? Constants.DEFAULT_PAGE_SIZE)),
},
};
});
}
export async function getOutboundEmail(id: string) {
return await db.outboundEmail.findFirst({
where: {
id,
},
include: {
campaign: true,
opens: true,
clicks: true,
},
export async function hasDeliveredOutboundEmail(tenantId: string | null): Promise<boolean> {
return withEmailMarketingScope(tenantId, async (client) => {
const delivered = await client.outboundEmail.findFirst({
where: { tenantId, deliveredAt: { not: null } },
select: { id: true },
});
return delivered !== null;
});
}
export async function createOutboundEmailTest(data: {
tenantId: string | null;
email: string;
fromSenderId: string;
}): Promise<OutboundEmail> {
const item = await db.outboundEmail.create({
data: {
...data,
isPreview: true,
},
});
return item;
export async function getOutboundEmail(id: string, tenantId: string | null) {
return withEmailMarketingScope(tenantId, (client) =>
client.outboundEmail.findFirst({
where: { id, tenantId },
include: {
campaign: true,
opens: true,
clicks: true,
},
})
);
}
export async function createOutboundEmailTest(data: { tenantId: string | null; email: string; fromSenderId: string }): Promise<OutboundEmail> {
return withEmailMarketingScope(data.tenantId, (client) => client.outboundEmail.create({ data: { ...data, isPreview: true } }));
}
export async function updateOutboundEmail(
id: string,
tenantId: string | null,
data: {
error?: string;
sentAt?: Date;
@@ -107,57 +91,47 @@ export async function updateOutboundEmail(
unsubscribedAt?: Date;
}
) {
const item = await db.outboundEmail.update({
where: {
id,
},
data,
return withEmailMarketingScope(tenantId, async (client) => {
const result = await client.outboundEmail.updateMany({ where: { id, tenantId }, data });
if (result.count !== 1) throw new Error("Outbound email not found");
return client.outboundEmail.findFirstOrThrow({ where: { id, tenantId } });
});
return item;
}
export async function openedOutboundEmail(outboundEmailId: string, data: { firstOpen: boolean }) {
const item = await db.outboundEmailOpen.create({
data: {
outboundEmailId,
firstOpen: data.firstOpen,
},
export async function openedOutboundEmail(tenantId: string, outboundEmailId: string, data: { firstOpen: boolean }) {
return withEmailMarketingScope(tenantId, async (client) => {
const outbound = await client.outboundEmail.findFirst({ where: { id: outboundEmailId, tenantId }, select: { id: true } });
if (!outbound) throw new Error("Outbound email not found");
return client.outboundEmailOpen.create({ data: { outboundEmailId, firstOpen: data.firstOpen } });
});
return item;
}
export async function clickedOutboundEmail(
tenantId: string,
outboundEmailId: string,
data: {
link: string;
}
) {
const item = await db.outboundEmailClick.create({
data: {
outboundEmailId,
link: data.link,
},
return withEmailMarketingScope(tenantId, async (client) => {
const outbound = await client.outboundEmail.findFirst({ where: { id: outboundEmailId, tenantId }, select: { id: true } });
if (!outbound) throw new Error("Outbound email not found");
return client.outboundEmailClick.create({ data: { outboundEmailId, link: data.link } });
});
return item;
}
export async function unsubscribeCampaignRecipient(
id: string,
tenantId: string,
data: {
unsubscribedAt: Date;
}
) {
const item = await db.outboundEmail.update({
where: {
id,
},
data,
return withEmailMarketingScope(tenantId, async (client) => {
const result = await client.outboundEmail.updateMany({ where: { id, tenantId }, data });
if (result.count !== 1) throw new Error("Outbound email not found");
return client.outboundEmail.findFirstOrThrow({ where: { id, tenantId } });
});
return item;
}
export async function countOutboundEmails(
@@ -166,10 +140,12 @@ export async function countOutboundEmails(
where: Prisma.OutboundEmailWhereInput;
}
): Promise<number> {
return await db.outboundEmail.count({
where: {
tenantId,
...options?.where,
},
});
return withEmailMarketingScope(tenantId, (client) =>
client.outboundEmail.count({
where: {
tenantId,
...options?.where,
},
})
);
}
@@ -3,6 +3,7 @@ import { getTranslations } from "~/locale/i18next.server";
import { getTenantIdOrNull } from "~/utils/services/.server/urlService";
import { countOutboundEmails } from "../db/outboundEmails.db.server";
import { requireAuth } from "~/utils/loaders.middleware";
import { requireEmailMarketingViewAccess } from "./emailMarketingAccess.server";
export namespace EmailMarketing_Summary {
// R-P14C: summary is computed inline from the typed OutboundEmail counters
@@ -43,8 +44,9 @@ export namespace EmailMarketing_Summary {
export const loader = async ({ request, params }: LoaderFunctionArgs) => {
await requireAuth({ request, params });
const { t } = await getTranslations(request);
const tenantId = await getTenantIdOrNull({ request, params });
await requireEmailMarketingViewAccess({ request, params, tenantId });
const { t } = await getTranslations(request);
const data: LoaderData = {
title: `${t("emailMarketing:title")} | ${process.env.APP_NAME}`,
summary: await buildSummary(tenantId),
@@ -4,10 +4,11 @@ import { PaginationDto } from "~/application/dtos/data/PaginationDto";
import { getTranslations } from "~/locale/i18next.server";
import { getFiltersFromCurrentUrl, getPaginationFromCurrentUrl } from "~/utils/helpers/RowPaginationHelper";
import { getTenantIdOrNull } from "~/utils/services/.server/urlService";
import { getAllCampaigns } from "../db/campaigns.db.server";
import { getCampaignOptions } from "../db/campaigns.db.server";
import { getAllEmailSenders } from "../db/emailSender";
import { OutboundEmailWithDetails, getAllOutboundEmails } from "../db/outboundEmails.db.server";
import { requireAuth } from "~/utils/loaders.middleware";
import { requireEmailMarketingViewAccess } from "./emailMarketingAccess.server";
export namespace OutboundEmails_List {
export type LoaderData = {
@@ -17,10 +18,11 @@ export namespace OutboundEmails_List {
};
export const loader = async ({ request, params }: LoaderFunctionArgs) => {
await requireAuth({ request, params });
const { t } = await getTranslations(request);
const tenantId = await getTenantIdOrNull({ request, params });
await requireEmailMarketingViewAccess({ request, params, tenantId });
const { t } = await getTranslations(request);
const emailSenders = await getAllEmailSenders(tenantId);
const campaigns = await getAllCampaigns(tenantId);
const campaigns = await getCampaignOptions(tenantId);
const filterableProperties: FilterablePropertyDto[] = [
{
name: "senderId",
@@ -56,7 +58,7 @@ export namespace OutboundEmails_List {
const { items, pagination } = await getAllOutboundEmails(tenantId, {
where: {
fromSenderId,
campaignId: campaignId === "null" ? null : campaignId ?? undefined,
campaignId: campaignId === "null" ? null : (campaignId ?? undefined),
},
pagination: currentPagination,
});
@@ -5,7 +5,7 @@ import { EmailSenderWithoutApiKey, getEmailSenderWithoutApiKey, getEmailSender,
import { requireAuth } from "~/utils/loaders.middleware";
import { adminPath, appPath } from "~/utils/app/CanonicalUrlUtils";
import { validateCSRFToken } from "~/utils/session.server";
import { requireEmailMarketingMutationAccess } from "./emailMarketingAccess.server";
import { requireEmailMarketingMutationAccess, requireEmailMarketingViewAccess } from "./emailMarketingAccess.server";
export namespace Senders_Edit {
export type LoaderData = {
@@ -14,6 +14,7 @@ export namespace Senders_Edit {
export const loader = async ({ request, params }: LoaderFunctionArgs) => {
await requireAuth({ request, params });
const tenantId = await getTenantIdOrNull({ request, params });
await requireEmailMarketingViewAccess({ request, params, tenantId });
const item = await getEmailSenderWithoutApiKey(params.id!, tenantId);
if (!item) {
return redirect(params.tenant ? appPath({ tenantSlug: params.tenant, path: "email-marketing/senders", mode: "host-aware" }) : adminPath("email-marketing/senders", { mode: "host-aware" }));
@@ -58,13 +59,23 @@ export namespace Senders_Edit {
fromName,
replyToEmail,
});
return redirect(params.tenant ? appPath({ tenantSlug: params.tenant, path: "email-marketing/senders", mode: "host-aware" }) : adminPath("email-marketing/senders", { mode: "host-aware" }));
const listPath = params.tenant
? appPath({ tenantSlug: params.tenant, path: "email-marketing/senders", mode: "host-aware" })
: adminPath("email-marketing/senders", { mode: "host-aware" });
return redirect(
`${listPath}?toast=${encodeURIComponent("emailMarketing:senders.toast.saved")}`
);
} catch (e: any) {
return badRequest({ error: e.message });
}
} else if (action === "delete") {
await deleteEmailSender(existing.id, tenantId);
return redirect(params.tenant ? appPath({ tenantSlug: params.tenant, path: "email-marketing/senders", mode: "host-aware" }) : adminPath("email-marketing/senders", { mode: "host-aware" }));
const listPath = params.tenant
? appPath({ tenantSlug: params.tenant, path: "email-marketing/senders", mode: "host-aware" })
: adminPath("email-marketing/senders", { mode: "host-aware" });
return redirect(
`${listPath}?toast=${encodeURIComponent("emailMarketing:senders.toast.deleted")}`
);
}
return badRequest({ error: t("shared.invalidForm") });
};
@@ -2,50 +2,137 @@ import { LoaderFunctionArgs, ActionFunction } from "react-router";
import { getTranslations } from "~/locale/i18next.server";
import { getTenantIdOrNull } from "~/utils/services/.server/urlService";
import { EmailSenderWithoutApiKey, getAllEmailSenders, getEmailSender } from "../db/emailSender";
import { createOutboundEmailTest, findOutboundEmails, updateOutboundEmail } from "../db/outboundEmails.db.server";
import { createOutboundEmailTest, hasDeliveredOutboundEmail, updateOutboundEmail } from "../db/outboundEmails.db.server";
import { requireAuth } from "~/utils/loaders.middleware";
import { sendBroadcast } from "../services/EmailMarketingSenderService.server";
import { validateCSRFToken } from "~/utils/session.server";
import { requireEmailMarketingMutationAccess } from "./emailMarketingAccess.server";
import { requireEmailMarketingMutationAccess, requireEmailMarketingViewAccess } from "./emailMarketingAccess.server";
import { recordEmailSuppression } from "@hivegrid/db/email-suppression.server";
import { withEmailMarketingScope } from "../db/emailMarketingScope.server";
import { createScopedLogger } from "~/utils/logger.server";
import { createAuditEvent } from "@hivegrid/db/audit-events.server";
import { z } from "zod";
const logger = createScopedLogger("email-marketing-senders");
const SenderActionSchema = z.discriminatedUnion("action", [
z.object({
action: z.literal("record-suppression"),
email: z.string().trim().email().max(320),
reason: z.enum(["bounce", "complaint", "manual"]).optional().default("manual"),
detail: z.string().trim().max(1_000).optional().default(""),
}),
z.object({
action: z.literal("send-test"),
email: z.string().trim().email().max(320),
senderId: z.string().trim().min(1).max(128),
}),
]);
export namespace Senders_List {
export type SuppressionRow = {
id: string;
emailAddress: string;
reason: string;
detail: string | null;
createdAtIso: string;
};
export type LoaderData = {
items: EmailSenderWithoutApiKey[];
hasSetWebhooks: boolean;
suppressionRows: SuppressionRow[];
};
export const loader = async ({ request, params }: LoaderFunctionArgs) => {
await requireAuth({ request, params });
const tenantId = await getTenantIdOrNull({ request, params });
const items = await getAllEmailSenders(tenantId);
const deliveredEmails = await findOutboundEmails(tenantId, {
where: {
deliveredAt: { not: null },
},
});
await requireEmailMarketingViewAccess({ request, params, tenantId });
const [items, hasDeliveredEmails, suppressionRows] = await Promise.all([
getAllEmailSenders(tenantId),
hasDeliveredOutboundEmail(tenantId),
tenantId
? withEmailMarketingScope(tenantId, (client) =>
client.emailSuppressionList.findMany({
where: { tenantId },
orderBy: { createdAt: "desc" },
take: 50,
})
)
: Promise.resolve([]),
]);
const data: LoaderData = {
items,
hasSetWebhooks: deliveredEmails.length > 0,
hasSetWebhooks: hasDeliveredEmails,
suppressionRows: suppressionRows.map((row) => ({
id: row.id,
emailAddress: row.emailAddress,
reason: row.reason,
detail: row.detail,
createdAtIso: row.createdAt.toISOString(),
})),
};
return data;
};
export type ActionData = {
error?: string;
success?: string;
intent: "record-suppression" | "send-test" | "invalid";
ok?: true;
messageKey?: string;
errorKey?: string;
errorValues?: Record<string, string>;
};
export const action: ActionFunction = async ({ request, params }) => {
await requireAuth({ request, params });
const auth = await requireAuth({ request, params });
const { t } = await getTranslations(request);
const tenantId = await getTenantIdOrNull({ request, params });
await requireEmailMarketingMutationAccess({ request, params, tenantId });
await validateCSRFToken(request);
const form = await request.formData();
const action = form.get("action")?.toString() ?? "";
const email = form.get("email")?.toString() ?? "";
const senderId = form.get("senderId")?.toString() ?? "";
const payload = SenderActionSchema.safeParse(Object.fromEntries(form));
if (!payload.success) {
return Response.json(
{ intent: "invalid", errorKey: "shared.invalidForm" } satisfies ActionData,
{ status: 400 }
);
}
const { action, email } = payload.data;
if (action === "record-suppression") {
if (!tenantId) {
return Response.json(
{ intent: "record-suppression", errorKey: "shared.invalidForm" } satisfies ActionData,
{ status: 400 }
);
}
await recordEmailSuppression({
tenantId,
emailAddress: email,
reason: payload.data.reason,
detail: payload.data.detail || undefined,
});
await createAuditEvent({
tenantId,
actorId: auth.userId,
actorType: "user",
action: "EMAIL_SUPPRESSION_RECORDED",
targetType: "EmailSuppressionList",
targetId: email.trim().toLocaleLowerCase("en-US"),
sourceModule: "email-marketing",
}).catch(() => undefined);
return Response.json(
{
intent: "record-suppression",
ok: true,
messageKey: "emailMarketing.suppression.added",
} satisfies ActionData,
{ status: 200 }
);
}
if (action === "send-test") {
const { senderId } = payload.data;
const sender = await getEmailSender(senderId, tenantId);
if (!sender) {
return Response.json({ error: t("emailMarketing:errors.invalidSender") }, { status: 400 });
return Response.json(
{ intent: "send-test", errorKey: "emailMarketing:errors.invalidSender" } satisfies ActionData,
{ status: 400 }
);
}
const outbountEmail = await createOutboundEmailTest({
tenantId,
@@ -64,18 +151,64 @@ export namespace Senders_List {
outboundEmailId: outbountEmail.id,
},
});
await updateOutboundEmail(outbountEmail.id, {
await updateOutboundEmail(outbountEmail.id, tenantId, {
sentAt: new Date(),
});
return Response.json({ success: t("shared.sent") }, { status: 200 });
} catch (e: any) {
await updateOutboundEmail(outbountEmail.id, {
error: e.message,
});
return Response.json({ error: e.message }, { status: 400 });
await createAuditEvent({
tenantId,
actorId: auth.userId,
actorType: "user",
action: "EMAIL_SENDER_TEST_SENT",
targetType: "OutboundEmail",
targetId: outbountEmail.id,
sourceModule: "email-marketing",
}).catch(() => undefined);
return Response.json(
{
intent: "send-test",
ok: true,
messageKey: "emailMarketing:senders.toast.testSent",
} satisfies ActionData,
{ status: 200 }
);
} catch (error) {
const reference = crypto.randomUUID();
logger.error(
{
event: "email_marketing.sender_test_failed",
reference,
tenantId,
senderId,
errorName: error instanceof Error ? error.name : "UnknownError",
},
"Email sender test failed"
);
const safeError = `emailMarketing.senderTest.providerFailed:${reference}`;
await updateOutboundEmail(outbountEmail.id, tenantId, { error: safeError });
await createAuditEvent({
tenantId,
actorId: auth.userId,
actorType: "user",
action: "EMAIL_SENDER_TEST_FAILED",
targetType: "OutboundEmail",
targetId: outbountEmail.id,
sourceModule: "email-marketing",
metadata: { reference },
}).catch(() => undefined);
return Response.json(
{
intent: "send-test",
errorKey: "emailMarketing:errors.providerUnavailable",
errorValues: { reference },
} satisfies ActionData,
{ status: 400 }
);
}
} else {
return Response.json({ error: t("shared.invalidForm") }, { status: 400 });
return Response.json(
{ intent: "invalid", errorKey: "shared.invalidForm" } satisfies ActionData,
{ status: 400 }
);
}
};
}
@@ -53,7 +53,12 @@ export namespace Senders_New {
fromName,
replyToEmail,
});
return redirect(params.tenant ? appPath({ tenantSlug: params.tenant, path: "email-marketing/senders", mode: "host-aware" }) : adminPath("email-marketing/senders", { mode: "host-aware" }));
const listPath = params.tenant
? appPath({ tenantSlug: params.tenant, path: "email-marketing/senders", mode: "host-aware" })
: adminPath("email-marketing/senders", { mode: "host-aware" });
return redirect(
`${listPath}?toast=${encodeURIComponent("emailMarketing:senders.toast.created")}`
);
} catch (e: any) {
return badRequest({ error: e.message });
}
@@ -13,8 +13,15 @@ const emailMarketingMutationHandlers = [
"modules/emailMarketing/routes/Senders_New.ts",
];
const emailMarketingReadHandlers = [
"modules/emailMarketing/routes/OutboundEmails_List.ts",
"modules/emailMarketing/routes/Senders_List.ts",
"modules/emailMarketing/routes/Senders_Edit.ts",
"modules/emailMarketing/routes/EmailMarketing_Summary.ts",
];
describe("email marketing route authorization boundary", () => {
test("requires tenant admin access and csrf before parsing mutating forms", () => {
test("requires explicit email-marketing mutation access and csrf before parsing mutating forms", () => {
for (const relativePath of emailMarketingMutationHandlers) {
const source = fs.readFileSync(path.join(appRoot, relativePath), "utf8");
expect(source.indexOf("await requireEmailMarketingMutationAccess({ request, params, tenantId })"), relativePath).toBeGreaterThanOrEqual(0);
@@ -25,4 +32,17 @@ describe("email marketing route authorization boundary", () => {
expect(source.indexOf("await validateCSRFToken(request)"), relativePath).toBeLessThan(source.indexOf("await request.formData()"));
}
});
test("requires email marketing view access in every legacy tenant loader", () => {
for (const relativePath of emailMarketingReadHandlers) {
const source = fs.readFileSync(path.join(appRoot, relativePath), "utf8");
const loaderAt = source.indexOf("export const loader");
const requireAuthAt = source.indexOf("await requireAuth({ request, params })", loaderAt);
const viewAccessAt = source.indexOf("await requireEmailMarketingViewAccess({ request, params, tenantId })", loaderAt);
expect(loaderAt, relativePath).toBeGreaterThanOrEqual(0);
expect(requireAuthAt, relativePath).toBeGreaterThan(loaderAt);
expect(viewAccessAt, relativePath).toBeGreaterThan(requireAuthAt);
}
});
});
@@ -0,0 +1,81 @@
import { beforeEach, describe, expect, it, vi } from "vitest";
import { foundationErrors } from "@hivegrid/foundation";
const mocks = vi.hoisted(() => ({
getUserInfo: vi.fn(),
getPermissionsByUser: vi.fn(),
requireTenantProductAccess: vi.fn(),
}));
vi.mock("~/utils/session.server", () => ({ getUserInfo: mocks.getUserInfo }));
vi.mock("~/utils/db/permissions/userRoles.db.server", () => ({ getPermissionsByUser: mocks.getPermissionsByUser }));
vi.mock("~/utils/entitlements/.server/productAccess.server", () => ({
requireTenantProductAccess: mocks.requireTenantProductAccess,
}));
import { requireEmailMarketingMutationAccess, requireEmailMarketingViewAccess } from "./emailMarketingAccess.server";
const request = new Request("http://app.localhost/acme/email-marketing/activity");
describe("email marketing read access", () => {
beforeEach(() => {
vi.clearAllMocks();
mocks.getUserInfo.mockResolvedValue({ userId: "user-a" });
mocks.getPermissionsByUser.mockResolvedValue([]);
mocks.requireTenantProductAccess.mockResolvedValue({ allowed: true });
});
it("denies a tenant member without view or manage permission as not found", async () => {
await expect(requireEmailMarketingViewAccess({ request, params: { tenant: "acme" }, tenantId: "tenant-a" })).rejects.toMatchObject({
code: foundationErrors.notFound.code,
});
expect(mocks.getPermissionsByUser).toHaveBeenCalledWith("user-a", "tenant-a");
expect(mocks.requireTenantProductAccess).toHaveBeenCalledWith({
request,
params: { tenant: "acme" },
featureKey: "email-marketing",
});
});
it.each([["emailMarketing.view"], ["emailMarketing.manage"]])("allows %s", async (permission) => {
mocks.getPermissionsByUser.mockResolvedValueOnce([permission]);
await expect(requireEmailMarketingViewAccess({ request, params: { tenant: "acme" }, tenantId: "tenant-a" })).resolves.toBeUndefined();
});
it("keeps admin-console reads on the existing admin identity boundary", async () => {
await expect(requireEmailMarketingViewAccess({ request, params: {}, tenantId: null })).resolves.toBeUndefined();
expect(mocks.getUserInfo).not.toHaveBeenCalled();
expect(mocks.getPermissionsByUser).not.toHaveBeenCalled();
expect(mocks.requireTenantProductAccess).not.toHaveBeenCalled();
});
});
describe("email marketing mutation access", () => {
beforeEach(() => {
vi.clearAllMocks();
mocks.getUserInfo.mockResolvedValue({ userId: "user-a" });
mocks.getPermissionsByUser.mockResolvedValue([]);
mocks.requireTenantProductAccess.mockResolvedValue({ allowed: true });
});
it("denies Tenant-Admin without the explicit manage permission", async () => {
await expect(requireEmailMarketingMutationAccess({ request, params: { tenant: "acme" }, tenantId: "tenant-a" })).rejects.toMatchObject({
code: foundationErrors.notFound.code,
});
});
it("allows a tenant member with emailMarketing.manage", async () => {
mocks.getPermissionsByUser.mockResolvedValueOnce(["emailMarketing.manage"]);
await expect(requireEmailMarketingMutationAccess({ request, params: { tenant: "acme" }, tenantId: "tenant-a" })).resolves.toBeUndefined();
});
it("keeps admin-console writes on the existing admin identity boundary", async () => {
await expect(requireEmailMarketingMutationAccess({ request, params: {}, tenantId: null })).resolves.toBeUndefined();
expect(mocks.getUserInfo).not.toHaveBeenCalled();
expect(mocks.requireTenantProductAccess).not.toHaveBeenCalled();
});
});
@@ -1,5 +1,48 @@
import type { Params } from "react-router";
import { requireSuperUserOrAdmin } from "~/utils/loaders.middleware";
import { CatalogError, foundationErrors } from "@hivegrid/foundation";
import { featureKeys } from "@hivegrid/entitlements";
import { getPermissionsByUser } from "~/utils/db/permissions/userRoles.db.server";
import { getUserInfo } from "~/utils/session.server";
import { requireTenantProductAccess } from "~/utils/entitlements/.server/productAccess.server";
export const EMAIL_MARKETING_PERMISSIONS = {
view: "emailMarketing.view",
manage: "emailMarketing.manage",
} as const;
export function emailMarketingCanView(permissions: readonly string[]): boolean {
return permissions.includes(EMAIL_MARKETING_PERMISSIONS.view) || permissions.includes(EMAIL_MARKETING_PERMISSIONS.manage);
}
export function emailMarketingCanManage(permissions: readonly string[]): boolean {
return permissions.includes(EMAIL_MARKETING_PERMISSIONS.manage);
}
export async function requireEmailMarketingViewAccess({
request,
params,
tenantId,
}: {
request: Request;
params: Params;
tenantId: string | null;
}): Promise<void> {
// Admin-console routes are already protected by requireAuth's admin identity
// check and have no tenant whose role permissions could be evaluated here.
if (!tenantId) {
return;
}
await requireTenantProductAccess({ request, params, featureKey: featureKeys.emailMarketing });
const { userId } = await getUserInfo(request);
if (!userId) {
throw new CatalogError(foundationErrors.notFound);
}
const permissions = await getPermissionsByUser(userId, tenantId);
if (!emailMarketingCanView(permissions)) {
throw new CatalogError(foundationErrors.notFound, { permission: EMAIL_MARKETING_PERMISSIONS.view });
}
}
export async function requireEmailMarketingMutationAccess({
request,
@@ -10,7 +53,20 @@ export async function requireEmailMarketingMutationAccess({
params: Params;
tenantId: string | null;
}) {
if (tenantId) {
await requireSuperUserOrAdmin({ request, params });
// Admin-console routes have no tenant role to evaluate and remain protected by
// their existing admin identity boundary. Tenant routes must use the explicit
// object permission; Tenant-Admin alone never implies marketing write access.
if (!tenantId) {
return;
}
await requireTenantProductAccess({ request, params, featureKey: featureKeys.emailMarketing });
const { userId } = await getUserInfo(request);
if (!userId) {
throw new CatalogError(foundationErrors.notFound);
}
const permissions = await getPermissionsByUser(userId, tenantId);
if (!emailMarketingCanManage(permissions)) {
throw new CatalogError(foundationErrors.notFound, { permission: EMAIL_MARKETING_PERMISSIONS.manage });
}
}
@@ -0,0 +1,85 @@
import { readFileSync } from "node:fs";
import { describe, expect, it } from "vitest";
import { resolveRepoPath } from "~/utils/testing/repoPaths";
function source(path: string): string {
return readFileSync(resolveRepoPath(path), "utf8");
}
describe("R-UX2 security and delivery contracts", () => {
it("gates the sidebar and parent route with feature plus explicit object permission", () => {
const sidebar = source("apps/web/app/application/sidebar/AppSidebar.tsx");
const parent = source("apps/web/app/routes/app.$tenant/email-marketing.tsx");
expect(sidebar).toContain('permission: "emailMarketing.view"');
expect(parent).toContain("requireTenantProductAccess");
expect(parent).toContain("emailMarketingCanView(ctx.permissions)");
});
it("rechecks the paid feature in shared child-route boundaries", () => {
const typedBoundary = source("apps/web/app/utils/integrations/emailDomainService.server.ts");
const legacyBoundary = source("apps/web/app/modules/emailMarketing/routes/emailMarketingAccess.server.ts");
expect(typedBoundary).toContain("requireTenantProductAccess({ request, params, featureKey: featureKeys.emailMarketing })");
expect(legacyBoundary.match(/requireTenantProductAccess\(\{ request, params, featureKey: featureKeys\.emailMarketing \}\)/gu)).toHaveLength(2);
});
it("validates CSRF before parsing every touched mutation form", () => {
for (const path of [
"apps/web/app/routes/app.$tenant/email-marketing/segments.tsx",
"apps/web/app/routes/app.$tenant/email-marketing/sending-domain.tsx",
"apps/web/app/routes/app.$tenant/email-marketing/campaigns/new.tsx",
"apps/web/app/routes/app.$tenant/email-marketing/campaigns/$id.tsx",
"apps/web/app/modules/emailMarketing/routes/Senders_List.ts",
]) {
const route = source(path);
expect(route.indexOf("await validateCSRFToken(request)"), path).toBeGreaterThan(-1);
expect(route.indexOf("await validateCSRFToken(request)"), path).toBeLessThan(route.indexOf("await request.formData()"));
}
});
it("parses every touched mutation through a typed schema", () => {
for (const path of [
"apps/web/app/routes/app.$tenant/email-marketing/segments.tsx",
"apps/web/app/routes/app.$tenant/email-marketing/sending-domain.tsx",
"apps/web/app/routes/app.$tenant/email-marketing/campaigns/new.tsx",
"apps/web/app/routes/app.$tenant/email-marketing/campaigns/$id.tsx",
"apps/web/app/modules/emailMarketing/routes/Senders_List.ts",
]) {
expect(source(path), path).toContain(".safeParse(");
}
});
it("uses a typed six-step draft, an advisory-locked version, and no raw provider error in action responses", () => {
const route = source("apps/web/app/routes/app.$tenant/email-marketing/campaigns/new.tsx");
const vm = source("packages/view-models/src/email/campaign-draft.vm.ts");
expect(route).toContain("DraftPayloadSchema.safeParse");
expect(route).toContain("pg_advisory_xact_lock");
expect(vm).toContain('["basics", "content", "audience", "test", "schedule", "review"]');
expect(route).not.toMatch(/Response\.json\(\s*\{\s*error[^}]*error\.message/gu);
});
it("resolves the untitled campaign draft name from the request locale", () => {
const route = source("apps/web/app/routes/app.$tenant/email-marketing/campaigns/new.tsx");
expect(route).toContain("const { t } = await getTranslations(request);");
expect(route).toContain('saveDraft(ctx, form, String(t("emailMarketing.campaign.editor.untitledDraft")))');
expect(route).toContain("name: payload.name || untitledDraftName");
expect(route).not.toContain('payload.name || "Unbenannter Entwurf"');
});
it("shares one preflight implementation between review and the idempotent command", () => {
const detail = source("apps/web/app/routes/app.$tenant/email-marketing/campaigns/$id.tsx");
const send = source("apps/web/app/modules/emailMarketing/services/CampaignSendService.server.ts");
expect(detail).toContain("loadCampaignPreflight({");
expect(send).toContain("loadCampaignPreflight({");
expect(detail).not.toContain("buildPresendChecklistVM({");
});
it("keeps all touched P14 DB entry points on the Forced-RLS scope helper", () => {
for (const path of [
"apps/web/app/modules/emailMarketing/db/campaigns.db.server.ts",
"apps/web/app/modules/emailMarketing/db/emailSender.ts",
"apps/web/app/modules/emailMarketing/db/outboundEmails.db.server.ts",
]) {
expect(source(path), path).toContain("withEmailMarketingScope(");
}
});
});
@@ -0,0 +1,52 @@
// @vitest-environment node
import fs from "node:fs";
import path from "node:path";
import { describe, expect, it } from "vitest";
const repoRoot = process.cwd();
function readSource(relativePath: string) {
return fs.readFileSync(path.join(repoRoot, relativePath), "utf8");
}
describe("email sender toast contract", () => {
it("uses redirect toasts for create, save and delete", () => {
const source = [
readSource("apps/web/app/modules/emailMarketing/routes/Senders_New.ts"),
readSource("apps/web/app/modules/emailMarketing/routes/Senders_Edit.ts"),
].join("\n");
expect(source).toContain("emailMarketing:senders.toast.created");
expect(source).toContain("emailMarketing:senders.toast.saved");
expect(source).toContain("emailMarketing:senders.toast.deleted");
expect(source).toContain("?toast=");
});
it("uses the shared toast hook for non-redirecting test and suppression actions", () => {
const routeSource = readSource(
"apps/web/app/modules/emailMarketing/routes/Senders_List.ts"
);
const componentSource = readSource(
"apps/web/app/modules/emailMarketing/components/senders/SendersListRoute.tsx"
);
expect(routeSource).toContain("emailMarketing:senders.toast.testSent");
expect(routeSource).toContain('intent: "record-suppression"');
expect(componentSource).toContain("useSaveToast(actionData)");
expect(componentSource).not.toContain('from "sonner"');
});
it("keeps English and German sender toast keys in parity", () => {
const en = JSON.parse(
readSource("apps/web/public/locales/en/emailMarketing.json")
) as { senders: { toast: Record<string, string> } };
const de = JSON.parse(
readSource("apps/web/public/locales/de/emailMarketing.json")
) as { senders: { toast: Record<string, string> } };
expect(Object.keys(de.senders.toast).sort()).toEqual(
Object.keys(en.senders.toast).sort()
);
});
});
@@ -0,0 +1,133 @@
import { buildPresendChecklistVM, evaluatePresendChecklist, type PresendChecklistResult, type PresendChecklistVM } from "@hivegrid/view-models";
import { withTenantRLS } from "~/utils/db/.server/tenantRls.server";
import type { CrmVisibilityContext } from "~/utils/integrations/crm/crmService.server";
import { resolveSegment } from "./SegmentService.server";
export type PreflightCampaignRow = {
id: string;
tenantId: string | null;
emailSenderId: string;
subject: string;
htmlBody: string;
textBody: string | null;
footerHtml: string | null;
recipientSegmentId: string | null;
scheduledAt: Date | null;
track: boolean;
status: string;
};
export interface CampaignPreflight {
campaign: PreflightCampaignRow;
variants: Array<{ label: "a" | "b"; subject: string; htmlBody: string; textBody: string | null; weightPercent: number }>;
recipientIds: string[];
domainVerified: boolean;
dailyCapUsed: number;
checklist: PresendChecklistResult;
checklistVM: PresendChecklistVM;
}
function resolveDailyCap(): number | null {
const raw = process.env.EMAIL_MARKETING_DAILY_CAP;
if (!raw) return null;
const limit = Number(raw);
return Number.isFinite(limit) && limit > 0 ? limit : null;
}
export async function loadCampaignPreflight(input: {
tenantId: string;
ctx: CrmVisibilityContext;
campaignId: string;
now?: Date;
}): Promise<CampaignPreflight | null> {
const now = input.now ?? new Date();
const loaded = await withTenantRLS(input.tenantId, async (tx) => {
const campaign = (await tx.campaign.findFirst({
where: { id: input.campaignId, tenantId: input.tenantId },
select: {
id: true,
tenantId: true,
emailSenderId: true,
subject: true,
htmlBody: true,
textBody: true,
footerHtml: true,
recipientSegmentId: true,
scheduledAt: true,
track: true,
status: true,
},
})) as PreflightCampaignRow | null;
if (!campaign) return null;
const [sender, variants, segment, dailyCapUsed] = await Promise.all([
tx.emailSender.findFirst({ where: { tenantId: input.tenantId, id: campaign.emailSenderId }, select: { sendingDomainId: true } }),
tx.campaignVariant.findMany({
where: { tenantId: input.tenantId, campaignId: campaign.id },
select: { label: true, subject: true, htmlBody: true, textBody: true, weightPercent: true },
}),
campaign.recipientSegmentId
? tx.recipientSegment.findFirst({
where: { tenantId: input.tenantId, id: campaign.recipientSegmentId },
select: { id: true, isStaticSnapshot: true, filterDefinition: true },
})
: Promise.resolve(null),
tx.outboundEmail.count({
where: { tenantId: input.tenantId, sentAt: { gte: new Date(now.getTime() - 24 * 60 * 60 * 1000) } },
}),
]);
const domain = sender?.sendingDomainId
? await tx.tenantSendingDomain.findFirst({
where: { tenantId: input.tenantId, id: sender.sendingDomainId },
select: { verificationStatus: true },
})
: null;
const staticRecipientIds =
segment?.isStaticSnapshot && campaign.recipientSegmentId
? (
await tx.segmentSnapshotMember.findMany({
where: { tenantId: input.tenantId, segmentId: campaign.recipientSegmentId },
select: { kontaktId: true },
})
).map((row) => row.kontaktId)
: null;
return {
campaign,
variants,
segment,
staticRecipientIds,
domainVerified: domain?.verificationStatus === "verified",
dailyCapUsed,
};
});
if (!loaded) return null;
const recipientIds = loaded.staticRecipientIds
? loaded.staticRecipientIds
: loaded.segment
? (
await resolveSegment({
tenantId: input.tenantId,
ctx: input.ctx,
filterDefinition: loaded.segment.filterDefinition,
})
).eligibleKontaktIds
: [];
const checklistInput = {
domainVerified: loaded.domainVerified,
footerConfigured: Boolean(loaded.campaign.footerHtml?.trim()),
subject: loaded.campaign.subject,
recipientCount: recipientIds.length,
dailyCapUsed: loaded.dailyCapUsed,
dailyCapLimit: resolveDailyCap(),
};
const checklist = evaluatePresendChecklist(checklistInput);
return {
campaign: loaded.campaign,
variants: loaded.variants,
recipientIds,
domainVerified: loaded.domainVerified,
dailyCapUsed: loaded.dailyCapUsed,
checklist,
checklistVM: buildPresendChecklistVM(checklistInput),
};
}
@@ -0,0 +1,97 @@
// @vitest-environment node
import { beforeEach, describe, expect, it, vi } from "vitest";
const mocks = vi.hoisted(() => ({
tx: {
campaign: {
findFirst: vi.fn(),
updateMany: vi.fn(),
},
},
publishOutboxEvent: vi.fn(),
}));
vi.mock("~/utils/db/.server/tenantRls.server", () => ({
withTenantRLS: async (_tenantId: string, operation: (tx: typeof mocks.tx) => Promise<unknown>) => operation(mocks.tx),
}));
vi.mock("@hivegrid/db/outbox", async (importOriginal) => {
const actual = await importOriginal<typeof import("@hivegrid/db/outbox")>();
return { ...actual, publishOutboxEvent: mocks.publishOutboxEvent };
});
import { CampaignSendError, cancelCampaignSchedule } from "./CampaignSendService.server";
describe("cancelCampaignSchedule", () => {
beforeEach(() => {
vi.clearAllMocks();
mocks.tx.campaign.findFirst.mockResolvedValue({
id: "campaign-1",
scheduledAt: new Date("2026-07-25T14:00:00.000Z"),
});
mocks.tx.campaign.updateMany.mockResolvedValue({ count: 1 });
mocks.publishOutboxEvent.mockResolvedValue({ id: "outbox-cancel-1" });
});
it("claims a future schedule and publishes an idempotent worker cancellation", async () => {
const now = new Date("2026-07-25T12:00:00.000Z");
await expect(
cancelCampaignSchedule({
tenantId: "tenant-1",
campaignId: "campaign-1",
now: () => now,
}),
).resolves.toEqual({
campaignId: "campaign-1",
scheduledAt: new Date("2026-07-25T14:00:00.000Z"),
});
expect(mocks.tx.campaign.findFirst).toHaveBeenCalledWith({
where: {
id: "campaign-1",
tenantId: "tenant-1",
status: "scheduled",
scheduledAt: { gt: now },
archivedAt: null,
},
select: { id: true, scheduledAt: true },
});
expect(mocks.tx.campaign.updateMany).toHaveBeenCalledWith({
where: {
id: "campaign-1",
tenantId: "tenant-1",
status: "scheduled",
scheduledAt: new Date("2026-07-25T14:00:00.000Z"),
},
data: { status: "cancelling" },
});
expect(mocks.publishOutboxEvent).toHaveBeenCalledWith(mocks.tx, {
tenantId: "tenant-1",
type: "mail.campaign.cancel-schedule",
dispatchKey: "campaign-cancel:campaign-1:1784988000000",
payload: {
tenantId: "tenant-1",
metadata: {
campaignId: "campaign-1",
scheduledAt: "2026-07-25T14:00:00.000Z",
},
},
priority: 100,
});
});
it("rejects an elapsed or non-scheduled campaign", async () => {
mocks.tx.campaign.findFirst.mockResolvedValue(null);
await expect(
cancelCampaignSchedule({
tenantId: "tenant-1",
campaignId: "campaign-1",
}),
).rejects.toMatchObject<Partial<CampaignSendError>>({
messageKey: "emailMarketing.send.error.cancellationUnavailable",
});
expect(mocks.publishOutboxEvent).not.toHaveBeenCalled();
});
});
@@ -0,0 +1,407 @@
// @vitest-environment node
import { beforeEach, describe, expect, test, vi } from "vitest";
type Contact = {
id: string;
vorname: string;
nachname: string;
orgName: string | null;
primaerEmail: string;
};
type OutboundRow = {
id: string;
createdAt: Date;
tenantId: string;
campaignId: string;
kontaktId: string;
email: string;
unsubscribeToken: string | null;
sentAt: Date | null;
};
type OutboxRow = {
dispatchKey: string;
eventType: string;
tenantId: string;
scheduledAt: Date;
payload: Record<string, unknown>;
};
const moduleMocks = vi.hoisted(() => ({
runTransaction: undefined as unknown as (callback: (tx: unknown) => Promise<unknown>) => Promise<unknown>,
listSuppressedEmailAddresses: vi.fn(async () => new Set<string>()),
assertEmailMarketingQuotaReservation: vi.fn(async () => undefined),
}));
vi.mock("~/utils/db/.server/tenantRls.server", () => ({
withTenantRLS: async (_tenantId: string, callback: (tx: unknown) => Promise<unknown>) => moduleMocks.runTransaction(callback),
}));
vi.mock("@hivegrid/db/email-suppression.server", async (importOriginal) => {
const actual = await importOriginal<typeof import("@hivegrid/db/email-suppression.server")>();
return { ...actual, listSuppressedEmailAddresses: moduleMocks.listSuppressedEmailAddresses };
});
vi.mock("./SegmentService.server", () => ({
resolveSegment: vi.fn(),
}));
vi.mock("~/services/billing/email-marketing-quota.server", () => ({
assertEmailMarketingQuotaReservation: moduleMocks.assertEmailMarketingQuotaReservation,
EmailMarketingQuotaError: class EmailMarketingQuotaError extends Error {
constructor(readonly code: "EMAIL_MARKETING_PLAN_REQUIRED" | "EMAIL_MARKETING_QUOTA_EXCEEDED") {
super(code);
}
},
}));
import {
buildCampaignRecipientIdempotencyKey,
buildCampaignRecipientOutboundId,
CAMPAIGN_IN_QUERY_BATCH_SIZE,
CampaignSendError,
dispatchCampaign,
} from "./CampaignSendService.server";
const NOW = new Date("2026-07-12T10:00:00.000Z");
const TENANT_ID = "tenant-1";
const CAMPAIGN_ID = "campaign-1";
function deferred() {
let resolve!: () => void;
const promise = new Promise<void>((done) => {
resolve = done;
});
return { promise, resolve };
}
function cloneOutbounds(rows: Map<string, OutboundRow>): Map<string, OutboundRow> {
return new Map([...rows].map(([id, row]) => [id, { ...row }]));
}
function cloneOutbox(rows: Map<string, OutboxRow>): Map<string, OutboxRow> {
return new Map([...rows].map(([key, row]) => [key, { ...row, payload: structuredClone(row.payload) }]));
}
function createHarness(contacts: Contact[], options: { htmlBody?: string } = {}) {
const state = {
campaignStatus: "draft",
campaignSentAt: null as Date | null,
outbounds: new Map<string, OutboundRow>(),
outbox: new Map<string, OutboxRow>(),
createdSequence: 0,
beforeCampaignReadReturn: undefined as undefined | (() => Promise<void>),
failCompletionOnce: false,
};
const campaignFindFirst = vi.fn(async () => {
const status = state.campaignStatus;
const sentAt = state.campaignSentAt;
await state.beforeCampaignReadReturn?.();
return {
id: CAMPAIGN_ID,
tenantId: TENANT_ID,
emailSenderId: "sender-1",
subject: "Hello {{vorname}}",
htmlBody: options.htmlBody ?? "<p>Hello {{vorname}}</p>",
textBody: "Hello {{vorname}}",
footerHtml: "<p>Impressum {{unsubscribeUrl}}</p>",
recipientSegmentId: "segment-1",
scheduledAt: null,
track: true,
status,
sentAt,
};
});
const campaignUpdateMany = vi.fn(async ({ where, data }: { where: Record<string, unknown>; data: { status?: string; sentAt?: Date } }) => {
if (where.id !== CAMPAIGN_ID || where.tenantId !== TENANT_ID) return { count: 0 };
if (typeof where.status === "string" && where.status !== state.campaignStatus) return { count: 0 };
if (where.sentAt === null && state.campaignSentAt !== null) return { count: 0 };
if (data.sentAt && state.failCompletionOnce) {
state.failCompletionOnce = false;
throw new Error("campaign completion failed");
}
if (data.status) state.campaignStatus = data.status;
if (data.sentAt) state.campaignSentAt = data.sentAt;
return { count: 1 };
});
const outboundFindMany = vi.fn(async ({ where }: { where: Record<string, unknown> }) => {
const rows = [...state.outbounds.values()];
const idFilter = where.id as { in?: string[] } | undefined;
const kontaktFilter = where.kontaktId as { in?: string[] } | undefined;
return rows.filter((row) => {
if (where.tenantId && row.tenantId !== where.tenantId) return false;
if (where.campaignId && row.campaignId !== where.campaignId) return false;
if (where.sentAt === null && row.sentAt !== null) return false;
if (idFilter?.in && !idFilter.in.includes(row.id)) return false;
if (kontaktFilter?.in && !kontaktFilter.in.includes(row.kontaktId)) return false;
return true;
});
});
const outboundCreateMany = vi.fn(async ({ data }: { data: Array<Record<string, unknown>> }) => {
let count = 0;
for (const item of data) {
const id = String(item.id);
if (state.outbounds.has(id)) continue;
state.createdSequence += 1;
state.outbounds.set(id, {
id,
createdAt: new Date(NOW.getTime() + state.createdSequence),
tenantId: String(item.tenantId),
campaignId: String(item.campaignId),
kontaktId: String(item.kontaktId),
email: String(item.email),
unsubscribeToken: typeof item.unsubscribeToken === "string" ? item.unsubscribeToken : null,
sentAt: null,
});
count += 1;
}
return { count };
});
const outboundUpdateMany = vi.fn(async ({ where, data }: { where: Record<string, unknown>; data: { sentAt?: Date } }) => {
const ids = (where.id as { in: string[] }).in;
let count = 0;
for (const id of ids) {
const row = state.outbounds.get(id);
if (!row || row.tenantId !== where.tenantId || row.campaignId !== where.campaignId) continue;
if (where.sentAt === null && row.sentAt !== null) continue;
row.sentAt = data.sentAt ?? row.sentAt;
count += 1;
}
return { count };
});
const outboxCreateMany = vi.fn(async ({ data }: { data: OutboxRow[] }) => {
let count = 0;
for (const row of data) {
if (state.outbox.has(row.dispatchKey)) continue;
state.outbox.set(row.dispatchKey, structuredClone(row));
count += 1;
}
return { count };
});
const tx = {
campaign: { findFirst: campaignFindFirst, updateMany: campaignUpdateMany },
emailSender: { findFirst: vi.fn(async () => ({ id: "sender-1", sendingDomainId: "domain-1" })) },
campaignVariant: { findMany: vi.fn(async () => []) },
recipientSegment: { findFirst: vi.fn(async () => ({ isStaticSnapshot: true })) },
tenantSendingDomain: { findFirst: vi.fn(async () => ({ verificationStatus: "verified" })) },
segmentSnapshotMember: { findMany: vi.fn(async () => contacts.map(({ id }) => ({ kontaktId: id }))) },
kontakt: {
findMany: vi.fn(async ({ where }: { where: { id: { in: string[] } } }) =>
contacts.filter((row) => where.id.in.includes(row.id)).sort((left, right) => left.id.localeCompare(right.id)),
),
},
customFieldDefinition: { findMany: vi.fn(async () => []) },
customFieldValue: { findMany: vi.fn(async () => []) },
outboundEmail: {
count: vi.fn(async () => 0),
findMany: outboundFindMany,
createMany: outboundCreateMany,
updateMany: outboundUpdateMany,
},
outboxEvent: { createMany: outboxCreateMany },
};
moduleMocks.runTransaction = async (callback) => {
const snapshot = {
campaignStatus: state.campaignStatus,
campaignSentAt: state.campaignSentAt,
outbounds: cloneOutbounds(state.outbounds),
outbox: cloneOutbox(state.outbox),
createdSequence: state.createdSequence,
};
try {
return await callback(tx);
} catch (error) {
// A lost atomic-claim race performed no writes in this transaction. Do
// not restore its stale snapshot over the concurrent winner's commit.
if (!(error && typeof error === "object" && "messageKey" in error && error.messageKey === "emailMarketing.send.error.alreadyDispatched")) {
state.campaignStatus = snapshot.campaignStatus;
state.campaignSentAt = snapshot.campaignSentAt;
state.outbounds = snapshot.outbounds;
state.outbox = snapshot.outbox;
state.createdSequence = snapshot.createdSequence;
}
throw error;
}
};
return { state, tx };
}
function contact(id: string, email: string): Contact {
return { id, vorname: id, nachname: "Example", orgName: "HiveGrid", primaerEmail: email };
}
function dispatch() {
return dispatchCampaign({
tenantId: TENANT_ID,
ctx: { userId: "user-1", permissions: ["emailMarketing.manage"] },
campaignId: CAMPAIGN_ID,
baseUrl: "https://app.example.test",
now: () => NOW,
});
}
describe("CampaignSendService idempotency", () => {
beforeEach(() => {
vi.clearAllMocks();
process.env.MARKETING_TOKEN_SECRET = "campaign-test-secret-with-at-least-32-bytes";
moduleMocks.listSuppressedEmailAddresses.mockResolvedValue(new Set());
moduleMocks.assertEmailMarketingQuotaReservation.mockResolvedValue(undefined);
});
test("derives stable, recipient-specific outbound ids and outbox/provider keys", () => {
const input = { tenantId: TENANT_ID, campaignId: CAMPAIGN_ID, kontaktId: "kontakt-1" };
expect(buildCampaignRecipientOutboundId(input)).toBe(buildCampaignRecipientOutboundId({ ...input }));
expect(buildCampaignRecipientIdempotencyKey(input)).toBe(buildCampaignRecipientIdempotencyKey({ ...input }));
expect(buildCampaignRecipientOutboundId(input)).not.toBe(buildCampaignRecipientOutboundId({ ...input, kontaktId: "kontakt-2" }));
expect(buildCampaignRecipientIdempotencyKey(input)).not.toContain(TENANT_ID);
expect(buildCampaignRecipientIdempotencyKey(input)).toMatch(/^campaign-send:campaign-1:/u);
});
test("rolls back a fully materialized partial attempt and safely retries once", async () => {
const first = contact("kontakt-1", "first@example.test");
const second = contact("kontakt-2", "second@example.test");
const { state, tx } = createHarness([first, second]);
state.failCompletionOnce = true;
await expect(dispatch()).rejects.toThrow("campaign completion failed");
expect(state.campaignStatus).toBe("draft");
expect(state.campaignSentAt).toBeNull();
expect(state.outbounds).toHaveLength(0);
expect(state.outbox).toHaveLength(0);
await expect(dispatch()).resolves.toMatchObject({ enqueued: 2, recipientCount: 2 });
expect(state.campaignStatus).toBe("sending");
expect(state.campaignSentAt).toEqual(NOW);
expect(state.outbounds).toHaveLength(2);
expect(state.outbox).toHaveLength(2);
expect([...state.outbounds.values()].every((row) => row.sentAt?.getTime() === NOW.getTime())).toBe(true);
expect(tx.outboundEmail.createMany).toHaveBeenCalledTimes(2);
expect(tx.outboxEvent.createMany).toHaveBeenCalledTimes(2);
expect(moduleMocks.assertEmailMarketingQuotaReservation).toHaveBeenCalledWith(tx, TENANT_ID, 2, NOW);
expect(tx.outboundEmail.findMany.mock.calls[0]?.[0]).toEqual(
expect.objectContaining({ where: expect.objectContaining({ tenantId: TENANT_ID, sentAt: null }) })
);
const secondKey = buildCampaignRecipientIdempotencyKey({ tenantId: TENANT_ID, campaignId: CAMPAIGN_ID, kontaktId: second.id });
expect(state.outbox.get(secondKey)).toMatchObject({
dispatchKey: secondKey,
eventType: "mail.transactional.send",
tenantId: TENANT_ID,
payload: {
to: [second.primaerEmail],
precedenceBulk: true,
listUnsubscribe: expect.stringContaining("/unsubscribe/"),
settings: { trackOpens: true, trackClicks: true },
metadata: {
idempotencyKey: buildCampaignRecipientOutboundId({ tenantId: TENANT_ID, campaignId: CAMPAIGN_ID, kontaktId: second.id }),
outboundEmailId: buildCampaignRecipientOutboundId({ tenantId: TENANT_ID, campaignId: CAMPAIGN_ID, kontaktId: second.id }),
campaignId: CAMPAIGN_ID,
},
},
});
});
test("allows exactly one concurrent caller to atomically claim a draft", async () => {
const recipient = contact("kontakt-1", "only@example.test");
const { state } = createHarness([recipient]);
const bothRead = deferred();
const releaseReads = deferred();
let readCount = 0;
state.beforeCampaignReadReturn = async () => {
readCount += 1;
if (readCount === 2) bothRead.resolve();
await releaseReads.promise;
};
const first = dispatch();
const second = dispatch();
await bothRead.promise;
releaseReads.resolve();
const results = await Promise.allSettled([first, second]);
const fulfilled = results.filter((result) => result.status === "fulfilled");
const rejected = results.filter((result): result is PromiseRejectedResult => result.status === "rejected");
expect(fulfilled).toHaveLength(1);
expect(rejected).toHaveLength(1);
expect(rejected[0]?.reason).toBeInstanceOf(CampaignSendError);
expect((rejected[0]?.reason as CampaignSendError).messageKey).toBe("emailMarketing.send.error.alreadyDispatched");
expect(state.outbounds).toHaveLength(1);
expect(state.outbox).toHaveLength(1);
expect(state.campaignStatus).toBe("sending");
});
test("rejects a retry after commit without creating another outbox event", async () => {
const { state, tx } = createHarness([contact("kontakt-1", "only@example.test")]);
await expect(dispatch()).resolves.toMatchObject({ enqueued: 1 });
await expect(dispatch()).rejects.toMatchObject({
messageKey: "emailMarketing.send.error.alreadyDispatched",
});
expect(state.outbox).toHaveLength(1);
expect(tx.outboxEvent.createMany).toHaveBeenCalledTimes(1);
});
test("rolls back and returns a clear error when one outbox payload exceeds its safety limit", async () => {
const { state } = createHarness([contact("kontakt-1", "only@example.test")], { htmlBody: `<p>${"x".repeat(70 * 1024)}</p>` });
await expect(dispatch()).rejects.toMatchObject({
messageKey: "emailMarketing.send.error.contentTooLarge",
});
expect(state.campaignStatus).toBe("draft");
expect(state.outbounds).toHaveLength(0);
expect(state.outbox).toHaveLength(0);
});
test.each([
["EMAIL_MARKETING_PLAN_REQUIRED", "emailMarketing.send.error.planRequired"],
["EMAIL_MARKETING_QUOTA_EXCEEDED", "emailMarketing.send.error.quotaExceeded"],
] as const)("rolls back when billing rejects the reservation with %s", async (code, messageKey) => {
const { state } = createHarness([contact("kontakt-1", "only@example.test")]);
const { EmailMarketingQuotaError } = await import("~/services/billing/email-marketing-quota.server");
moduleMocks.assertEmailMarketingQuotaReservation.mockRejectedValueOnce(new EmailMarketingQuotaError(code));
await expect(dispatch()).rejects.toMatchObject({ messageKey });
expect(state.campaignStatus).toBe("draft");
expect(state.outbounds).toHaveLength(0);
expect(state.outbox).toHaveLength(0);
});
test("chunks every large audience id lookup below the database parameter limit", async () => {
const contacts = Array.from({ length: CAMPAIGN_IN_QUERY_BATCH_SIZE + 1 }, (_, index) =>
contact(`kontakt-${String(index).padStart(5, "0")}`, `recipient-${index}@example.test`),
);
const { tx } = createHarness(contacts);
await expect(dispatch()).resolves.toMatchObject({ enqueued: contacts.length, recipientCount: contacts.length });
expect(tx.kontakt.findMany).toHaveBeenCalledTimes(2);
expect(tx.customFieldValue.findMany).toHaveBeenCalledTimes(2);
expect(tx.outboundEmail.updateMany).toHaveBeenCalledTimes(2);
for (const [query] of tx.kontakt.findMany.mock.calls) {
expect(query.where.id.in.length).toBeLessThanOrEqual(CAMPAIGN_IN_QUERY_BATCH_SIZE);
}
for (const [query] of tx.customFieldValue.findMany.mock.calls) {
expect(query.where.entityId.in.length).toBeLessThanOrEqual(CAMPAIGN_IN_QUERY_BATCH_SIZE);
}
for (const [query] of tx.outboundEmail.findMany.mock.calls) {
const values = query.where.kontaktId?.in ?? query.where.id?.in;
expect(values.length).toBeLessThanOrEqual(CAMPAIGN_IN_QUERY_BATCH_SIZE);
}
for (const [query] of tx.outboundEmail.updateMany.mock.calls) {
expect(query.where.id.in.length).toBeLessThanOrEqual(CAMPAIGN_IN_QUERY_BATCH_SIZE);
}
}, 30_000);
});
@@ -1,38 +1,39 @@
// AK-P14b (P14 email marketing) — campaign send-engine (BullMQ).
// AK-P14b (P14 email marketing) — campaign send-engine (transactional outbox → BullMQ).
//
// Orchestrates a DSGVO-safe campaign send on the TYPED path (AD-2):
// 1. resolve the audience from the campaign's RecipientSegment (dynamic) or its
// frozen snapshot (static) — eligibility already excludes unsubscribed /
// suppressed / no-opt-in / archived / no-email (SegmentService, S2);
// 2. HARD pre-send checklist gate (S5 core) — a red check throws, never sends;
// 3. per recipient: defensive suppression re-check (AK-P14a), persist an
// OutboundEmail row with a signed per-recipient unsubscribe token, and
// enqueue ONE `mail.transactional` job (List-Unsubscribe header + throttled
// timezone-aware sendAt) onto the existing email queue.
// 3. atomically claim the draft, batch-check suppression (AK-P14a), persist a
// stable OutboundEmail ledger row and one idempotent `mail.transactional`
// outbox event per recipient (List-Unsubscribe header + throttled
// timezone-aware scheduledAt) in the same database transaction.
//
// The pure planning (A/B split, throttle, footer/token injection) lives in
// campaignSendPlan.ts. Enqueue uses the boilerplate email queue + producer — no
// new worker queue. NO React/UI imports. Audit is automatic (M001 middleware);
// the caller (route) fires notify() (M011) from the returned result.
// campaignSendPlan.ts. The existing outbox.mail bridge owns Redis/BullMQ
// delivery, retries, and dead-letter handling. NO React/UI imports. Audit is
// automatic (M001 middleware); the caller fires notify() from the result.
import { buildTransactionalMailJob, enqueueJob, queueNames, resolveRedisConnectionOptionsFromProcessEnv, type TypedQueue } from "@hivegrid/queue";
import { createHash } from "node:crypto";
import { withTenantRLS, type TenantRlsClient } from "~/utils/db/.server/tenantRls.server";
import { isEmailSuppressed } from "@hivegrid/db/email-suppression";
import { listSuppressedEmailAddresses, normalizeSuppressionAddress } from "@hivegrid/db/email-suppression.server";
import { OutboxPublishError, publishOutboxEvent, publishOutboxEvents } from "@hivegrid/db/outbox";
import type { CrmVisibilityContext } from "~/utils/integrations/crm/crmService.server";
import { resolveSegment } from "./SegmentService.server";
import { planCampaignSend, type PlanRecipient, type PlanVariant } from "~/utils/integrations/email/campaignSendPlan";
import { evaluatePresendChecklist, type PresendChecklistResult } from "@hivegrid/view-models";
import { signMarketingToken } from "~/utils/email/marketingToken.server";
import type { PresendChecklistResult } from "@hivegrid/view-models";
import { signWithEnv } from "~/utils/email/marketingToken.server";
import { loadCampaignPreflight } from "./CampaignPreflightService.server";
import {
assertEmailMarketingQuotaReservation,
EmailMarketingQuotaError,
} from "~/services/billing/email-marketing-quota.server";
const KONTAKT_ENTITY_TYPE = "kontakt";
// Default daily send cap per tenant; override via EMAIL_MARKETING_DAILY_CAP
// ("0"/unset ⇒ no cap). Documented default-decision (Ticket-Doc lückenhaft).
function resolveDailyCap(): number | null {
const raw = process.env.EMAIL_MARKETING_DAILY_CAP;
if (!raw) return null;
const n = Number(raw);
return Number.isFinite(n) && n > 0 ? n : null;
}
const CLAIMED_CAMPAIGN_STATUS = "sending";
const SENDABLE_CAMPAIGN_STATUS = "draft";
const OUTBOUND_WRITE_BATCH_SIZE = 500;
export const CAMPAIGN_IN_QUERY_BATCH_SIZE = 5_000;
function resolveRatePerMinute(): number | undefined {
const raw = process.env.EMAIL_MARKETING_RATE_PER_MINUTE;
const n = raw ? Number(raw) : NaN;
@@ -65,72 +66,138 @@ export interface DispatchCampaignInput {
campaignId: string;
/** Public base URL for unsubscribe links (e.g. https://app.tenant.de). */
baseUrl: string;
/** Injected clock + queue for tests; default to env-derived queue. */
/** Injected clock for deterministic tests. */
now?: () => Date;
queue?: TypedQueue<typeof queueNames.email>;
}
type CampaignRow = {
export interface CancelCampaignScheduleInput {
tenantId: string;
campaignId: string;
now?: () => Date;
}
type OutboundLedgerRow = {
id: string;
tenantId: string | null;
emailSenderId: string;
subject: string;
htmlBody: string;
textBody: string | null;
footerHtml: string | null;
recipientSegmentId: string | null;
scheduledAt: Date | null;
track: boolean;
status: string;
createdAt: Date;
kontaktId: string | null;
email: string;
unsubscribeToken: string | null;
sentAt: Date | null;
};
async function loadAudienceKontaktIds(input: DispatchCampaignInput, campaign: CampaignRow, segmentIsStatic: boolean): Promise<string[]> {
if (!campaign.recipientSegmentId) return [];
if (segmentIsStatic) {
return withTenantRLS(input.tenantId, async (tx) => {
const rows = await tx.segmentSnapshotMember.findMany({
where: { tenantId: input.tenantId, segmentId: campaign.recipientSegmentId! },
select: { kontaktId: true },
});
return rows.map((r) => r.kontaktId);
});
type CampaignKontaktRow = {
id: string;
vorname: string | null;
nachname: string | null;
orgName: string | null;
primaerEmail: string | null;
};
function campaignQueryBatches<T>(items: readonly T[]): T[][] {
const batches: T[][] = [];
for (let index = 0; index < items.length; index += CAMPAIGN_IN_QUERY_BATCH_SIZE) {
batches.push(items.slice(index, index + CAMPAIGN_IN_QUERY_BATCH_SIZE));
}
const segment = await withTenantRLS(input.tenantId, async (tx) =>
tx.recipientSegment.findFirst({ where: { tenantId: input.tenantId, id: campaign.recipientSegmentId! }, select: { filterDefinition: true } })
);
if (!segment) return [];
const resolution = await resolveSegment({ tenantId: input.tenantId, ctx: input.ctx, filterDefinition: segment.filterDefinition });
return resolution.eligibleKontaktIds;
return batches;
}
function campaignRecipientDigest(input: { tenantId: string; campaignId: string; kontaktId: string }): string {
return createHash("sha256")
.update(JSON.stringify([input.tenantId, input.campaignId, input.kontaktId]))
.digest("base64url");
}
/** Stable across processes and retries; avoids a schema migration for a new unique key. */
export function buildCampaignRecipientOutboundId(input: { tenantId: string; campaignId: string; kontaktId: string }): string {
return `campaign_out_${campaignRecipientDigest(input)}`;
}
/** Shared by BullMQ job-id derivation and the outbound provider request. */
export function buildCampaignRecipientIdempotencyKey(input: { tenantId: string; campaignId: string; kontaktId: string }): string {
return `campaign-send:${input.campaignId}:${campaignRecipientDigest(input)}`;
}
export async function cancelCampaignSchedule(input: CancelCampaignScheduleInput): Promise<{ campaignId: string; scheduledAt: Date }> {
const now = input.now ? input.now() : new Date();
return withTenantRLS(input.tenantId, async (tx) => {
const campaign = await tx.campaign.findFirst({
where: {
id: input.campaignId,
tenantId: input.tenantId,
status: "scheduled",
scheduledAt: { gt: now },
archivedAt: null,
},
select: { id: true, scheduledAt: true },
});
if (!campaign?.scheduledAt) {
throw new CampaignSendError("emailMarketing.send.error.cancellationUnavailable");
}
const claimed = await tx.campaign.updateMany({
where: {
id: campaign.id,
tenantId: input.tenantId,
status: "scheduled",
scheduledAt: campaign.scheduledAt,
},
data: { status: "cancelling" },
});
if (claimed.count !== 1) {
throw new CampaignSendError("emailMarketing.send.error.cancellationUnavailable");
}
await publishOutboxEvent(tx, {
tenantId: input.tenantId,
type: "mail.campaign.cancel-schedule",
dispatchKey: `campaign-cancel:${campaign.id}:${campaign.scheduledAt.getTime()}`,
payload: {
tenantId: input.tenantId,
metadata: {
campaignId: campaign.id,
scheduledAt: campaign.scheduledAt.toISOString(),
},
},
priority: 100,
});
return { campaignId: campaign.id, scheduledAt: campaign.scheduledAt };
});
}
function selectCanonicalOutboundRows(rows: readonly OutboundLedgerRow[]): Map<string, OutboundLedgerRow> {
const byKontaktId = new Map<string, OutboundLedgerRow>();
for (const row of rows) {
if (!row.kontaktId) continue;
const current = byKontaktId.get(row.kontaktId);
// A queued row is authoritative. For legacy duplicates, otherwise retain
// the oldest row so every retry converges on the same outbound record.
if (!current || (!current.sentAt && row.sentAt) || (Boolean(current.sentAt) === Boolean(row.sentAt) && row.createdAt < current.createdAt)) {
byKontaktId.set(row.kontaktId, row);
}
}
return byKontaktId;
}
/** Build per-kontakt custom-field token maps (`cf.<key>`) for the audience. */
async function loadCustomFieldTokens(tx: TenantRlsClient, tenantId: string, kontaktIds: string[]): Promise<Map<string, Record<string, string>>> {
const result = new Map<string, Record<string, string>>();
if (kontaktIds.length === 0) return result;
const [defs, values] = await Promise.all([
tx.customFieldDefinition.findMany({ where: { tenantId, entityType: KONTAKT_ENTITY_TYPE }, select: { id: true, key: true } }),
tx.customFieldValue.findMany({ where: { tenantId, entityType: KONTAKT_ENTITY_TYPE, entityId: { in: kontaktIds } }, select: { definitionId: true, entityId: true, wert: true } }),
]);
const defs = await tx.customFieldDefinition.findMany({ where: { tenantId, entityType: KONTAKT_ENTITY_TYPE }, select: { id: true, key: true } });
const keyByDef = new Map(defs.map((d) => [d.id, d.key]));
for (const v of values) {
const key = keyByDef.get(v.definitionId);
if (!key) continue;
const map = result.get(v.entityId) ?? {};
map[key] = v.wert == null ? "" : typeof v.wert === "string" ? v.wert : JSON.stringify(v.wert);
result.set(v.entityId, map);
for (const kontaktIdBatch of campaignQueryBatches(kontaktIds)) {
const values = await tx.customFieldValue.findMany({
where: { tenantId, entityType: KONTAKT_ENTITY_TYPE, entityId: { in: kontaktIdBatch } },
select: { definitionId: true, entityId: true, wert: true },
});
for (const value of values) {
const key = keyByDef.get(value.definitionId);
if (!key) continue;
const map = result.get(value.entityId) ?? {};
map[key] = value.wert == null ? "" : typeof value.wert === "string" ? value.wert : JSON.stringify(value.wert);
result.set(value.entityId, map);
}
}
return result;
}
async function acquireQueue(input: DispatchCampaignInput): Promise<{ queue: TypedQueue<typeof queueNames.email>; close: boolean }> {
if (input.queue) return { queue: input.queue, close: false };
const connection = resolveRedisConnectionOptionsFromProcessEnv();
if (!connection) throw new CampaignSendError("emailMarketing.send.error.noQueue");
const queueRuntimeModule = "@hivegrid/queue/runtime";
const { createQueue } = (await import(/* @vite-ignore */ queueRuntimeModule)) as typeof import("@hivegrid/queue/runtime");
return { queue: createQueue(queueNames.email, { connection }), close: true };
}
/**
* Dispatch a campaign: gate on the pre-send checklist, then persist + enqueue one
* throttled transactional mail per eligible recipient. Throws CampaignSendError
@@ -138,126 +205,268 @@ async function acquireQueue(input: DispatchCampaignInput): Promise<{ queue: Type
*/
export async function dispatchCampaign(input: DispatchCampaignInput): Promise<CampaignSendResult> {
const nowMs = (input.now ? input.now() : new Date()).getTime();
// Load campaign + sender + variants + segment meta (read tx).
const loaded = await withTenantRLS(input.tenantId, async (tx) => {
const campaign = (await tx.campaign.findFirst({
where: { id: input.campaignId, tenantId: input.tenantId },
select: {
id: true, tenantId: true, emailSenderId: true, subject: true, htmlBody: true, textBody: true,
footerHtml: true, recipientSegmentId: true, scheduledAt: true, track: true, status: true,
},
})) as CampaignRow | null;
if (!campaign) return null;
const [sender, variants, segment] = await Promise.all([
tx.emailSender.findFirst({ where: { id: campaign.emailSenderId }, select: { id: true, sendingDomainId: true } }),
tx.campaignVariant.findMany({ where: { tenantId: input.tenantId, campaignId: campaign.id }, select: { label: true, subject: true, htmlBody: true, textBody: true, weightPercent: true } }),
campaign.recipientSegmentId
? tx.recipientSegment.findFirst({ where: { tenantId: input.tenantId, id: campaign.recipientSegmentId }, select: { isStaticSnapshot: true } })
: Promise.resolve(null),
]);
const domain = sender?.sendingDomainId
? await tx.tenantSendingDomain.findFirst({ where: { tenantId: input.tenantId, id: sender.sendingDomainId }, select: { verificationStatus: true } })
: null;
const dailyCapUsed = await tx.outboundEmail.count({ where: { tenantId: input.tenantId, sentAt: { gte: new Date(nowMs - 24 * 60 * 60 * 1000) } } });
return { campaign, variants, segmentIsStatic: segment?.isStaticSnapshot ?? false, domainVerified: domain?.verificationStatus === "verified", dailyCapUsed };
});
if (!loaded) throw new CampaignSendError("emailMarketing.send.error.notFound");
const { campaign, variants, segmentIsStatic, domainVerified, dailyCapUsed } = loaded;
// Resolve audience (own tx) and load recipient details.
const kontaktIds = await loadAudienceKontaktIds(input, campaign, segmentIsStatic);
const checklist = evaluatePresendChecklist({
domainVerified,
footerConfigured: Boolean(campaign.footerHtml && campaign.footerHtml.trim().length > 0),
subject: campaign.subject,
recipientCount: kontaktIds.length,
dailyCapUsed,
dailyCapLimit: resolveDailyCap(),
const preflight = await loadCampaignPreflight({
tenantId: input.tenantId,
ctx: input.ctx,
campaignId: input.campaignId,
now: new Date(nowMs),
});
if (!preflight) throw new CampaignSendError("emailMarketing.send.error.notFound");
const { campaign, variants, recipientIds: kontaktIds, checklist } = preflight;
if (campaign.status !== SENDABLE_CAMPAIGN_STATUS) {
throw new CampaignSendError("emailMarketing.send.error.alreadyDispatched");
}
if (checklist.blocked) {
throw new CampaignSendError("emailMarketing.send.error.checklistBlocked", checklist);
}
// Persist OutboundEmail rows + collect plan recipients (write tx).
const planRecipients = await withTenantRLS(input.tenantId, async (tx) => {
const kontakte = await tx.kontakt.findMany({
where: { tenantId: input.tenantId, id: { in: kontaktIds }, archivedAt: null, primaerEmail: { not: null } },
select: { id: true, vorname: true, nachname: true, orgName: true, primaerEmail: true },
// The claim, recipient ledger, mail outbox, and final campaign state share one
// DB transaction. No mail becomes visible to the dispatcher before commit;
// any failure rolls the claim and every partial write back together.
return withTenantRLS(input.tenantId, async (tx) => {
const claimed = await tx.campaign.updateMany({
where: {
id: campaign.id,
tenantId: input.tenantId,
status: SENDABLE_CAMPAIGN_STATUS,
sentAt: null,
},
data: { status: CLAIMED_CAMPAIGN_STATUS },
});
if (claimed.count !== 1) {
throw new CampaignSendError("emailMarketing.send.error.alreadyDispatched");
}
// Persist/reuse one canonical OutboundEmail row per recipient. Deterministic
// ids plus skipDuplicates close legacy/retry races without a schema change.
const kontakte: CampaignKontaktRow[] = [];
for (const kontaktIdBatch of campaignQueryBatches(kontaktIds)) {
kontakte.push(
...(await tx.kontakt.findMany({
where: { tenantId: input.tenantId, id: { in: kontaktIdBatch }, archivedAt: null, primaerEmail: { not: null } },
select: { id: true, vorname: true, nachname: true, orgName: true, primaerEmail: true },
}))
);
}
kontakte.sort((left, right) => left.id.localeCompare(right.id));
const cfTokens = await loadCustomFieldTokens(tx, input.tenantId, kontaktIds);
const recipients: PlanRecipient[] = [];
let skippedSuppressed = 0;
for (const k of kontakte) {
const email = k.primaerEmail!;
if (await isEmailSuppressed({ tenantId: input.tenantId, emailAddress: email }, tx)) {
skippedSuppressed += 1;
continue;
}
const unsubscribeToken = signMarketingToken({ purpose: "unsub", tenantId: input.tenantId, kontaktId: k.id, campaignId: campaign.id });
const trackingToken = signMarketingToken({ purpose: "unsub", tenantId: input.tenantId, kontaktId: k.id, campaignId: campaign.id, now: () => new Date(nowMs + 1) });
const outbound = await tx.outboundEmail.create({
data: { tenantId: input.tenantId, campaignId: campaign.id, kontaktId: k.id, email, fromSenderId: campaign.emailSenderId, unsubscribeToken, trackingToken },
select: { id: true },
const suppressedAddresses = await listSuppressedEmailAddresses(
{ tenantId: input.tenantId, emailAddresses: kontakte.map((kontakt) => kontakt.primaerEmail!) },
tx
);
const eligible = kontakte.filter((kontakt) => !suppressedAddresses.has(normalizeSuppressionAddress(kontakt.primaerEmail!)));
const candidates = eligible.map((kontakt) => {
const email = kontakt.primaerEmail!;
const stableInput = { tenantId: input.tenantId, campaignId: campaign.id, kontaktId: kontakt.id };
const unsubscribeToken = signWithEnv({
purpose: "unsub",
tenantId: input.tenantId,
kontaktId: kontakt.id,
campaignId: campaign.id,
now: () => new Date(nowMs),
});
recipients.push({
outboundEmailId: outbound.id,
kontaktId: k.id,
const trackingToken = signWithEnv({
purpose: "unsub",
tenantId: input.tenantId,
kontaktId: kontakt.id,
campaignId: campaign.id,
now: () => new Date(nowMs + 1_000),
});
return {
kontakt,
email,
unsubscribeToken,
tokens: { vorname: k.vorname, nachname: k.nachname, email, orgName: k.orgName, customFields: cfTokens.get(k.id) ?? {} },
});
}
return { recipients, skippedSuppressed };
});
// Plan (A/B split + throttle + footer/token injection).
const planVariants: PlanVariant[] = variants.map((v) => ({ label: v.label, subject: v.subject, htmlBody: v.htmlBody, textBody: v.textBody, weightPercent: v.weightPercent }));
const startAt = campaign.scheduledAt ? campaign.scheduledAt.getTime() : nowMs;
const plan = planCampaignSend({
recipients: planRecipients.recipients,
base: { subject: campaign.subject, htmlBody: campaign.htmlBody, textBody: campaign.textBody },
variants: planVariants,
footerHtml: campaign.footerHtml ?? "",
unsubscribeBaseUrl: input.baseUrl,
startAt,
ratePerMinute: resolveRatePerMinute(),
});
// Enqueue one transactional mail per planned send.
const { queue, close } = await acquireQueue(input);
try {
for (const p of plan) {
const descriptor = buildTransactionalMailJob({
to: [p.email],
subject: p.subject,
html: p.html,
text: p.text || undefined,
tenantId: input.tenantId,
precedenceBulk: true,
listUnsubscribe: p.listUnsubscribe,
settings: { trackOpens: campaign.track, trackClicks: campaign.track },
tags: ["email-marketing", `campaign:${campaign.id}`],
metadata: { idempotencyKey: p.outboundEmailId, outboundEmailId: p.outboundEmailId, ...(p.variantLabel ? { variant: p.variantLabel } : {}) },
});
// BullMQ `delay` carries the throttle/timezone-aware schedule (the worker
// releases the job at sendAt); no provider-side sendAt to avoid double-delay.
const delay = Math.max(0, p.sendAt - nowMs);
await enqueueJob(queue, descriptor, { tenantId: input.tenantId, ...(delay > 0 ? { delay } : {}) });
}
} finally {
if (close) await queue.close();
}
// Mark campaign as scheduled/sending (audited by M001 middleware).
await withTenantRLS(input.tenantId, async (tx) => {
await tx.campaign.update({
where: { id: campaign.id },
data: { status: campaign.scheduledAt && campaign.scheduledAt.getTime() > nowMs ? "scheduled" : "sending", sentAt: new Date(nowMs) },
trackingToken,
outboundEmailId: buildCampaignRecipientOutboundId(stableInput),
};
});
});
return { campaignId: campaign.id, enqueued: plan.length, skippedSuppressed: planRecipients.skippedSuppressed, recipientCount: kontaktIds.length, checklist };
const existingRows: OutboundLedgerRow[] = [];
for (const candidateBatch of campaignQueryBatches(candidates)) {
existingRows.push(
...((await tx.outboundEmail.findMany({
where: {
tenantId: input.tenantId,
campaignId: campaign.id,
kontaktId: { in: candidateBatch.map(({ kontakt }) => kontakt.id) },
// Uses the existing (tenantId, sentAt) index. A draft can only
// contain unsent rows left by the legacy direct-queue path; rows
// committed by this transactional path finalize the campaign.
sentAt: null,
},
select: { id: true, createdAt: true, kontaktId: true, email: true, unsubscribeToken: true, sentAt: true },
orderBy: { createdAt: "asc" },
})) as OutboundLedgerRow[])
);
}
const outboundByKontaktId = selectCanonicalOutboundRows(existingRows);
const missing = candidates.filter(({ kontakt }) => !outboundByKontaktId.has(kontakt.id));
if (missing.length > 0) {
for (let index = 0; index < missing.length; index += OUTBOUND_WRITE_BATCH_SIZE) {
await tx.outboundEmail.createMany({
data: missing.slice(index, index + OUTBOUND_WRITE_BATCH_SIZE).map(({ kontakt, email, unsubscribeToken, trackingToken, outboundEmailId }) => ({
id: outboundEmailId,
tenantId: input.tenantId,
campaignId: campaign.id,
kontaktId: kontakt.id,
email,
fromSenderId: campaign.emailSenderId,
unsubscribeToken,
trackingToken,
})),
skipDuplicates: true,
});
}
const insertedRows: OutboundLedgerRow[] = [];
for (const missingBatch of campaignQueryBatches(missing)) {
insertedRows.push(
...((await tx.outboundEmail.findMany({
where: { tenantId: input.tenantId, campaignId: campaign.id, id: { in: missingBatch.map(({ outboundEmailId }) => outboundEmailId) } },
select: { id: true, createdAt: true, kontaktId: true, email: true, unsubscribeToken: true, sentAt: true },
})) as OutboundLedgerRow[])
);
}
for (const [kontaktId, row] of selectCanonicalOutboundRows(insertedRows)) {
outboundByKontaktId.set(kontaktId, row);
}
}
const alreadyQueuedOutboundIds = new Set<string>();
const recipients: PlanRecipient[] = candidates.map(({ kontakt, email, unsubscribeToken }) => {
const outbound = outboundByKontaktId.get(kontakt.id);
if (!outbound) throw new CampaignSendError("emailMarketing.send.error.persistenceFailed");
if (outbound.sentAt) alreadyQueuedOutboundIds.add(outbound.id);
return {
outboundEmailId: outbound.id,
kontaktId: kontakt.id,
email,
unsubscribeToken: outbound.unsubscribeToken ?? unsubscribeToken,
tokens: {
vorname: kontakt.vorname,
nachname: kontakt.nachname,
email,
orgName: kontakt.orgName,
customFields: cfTokens.get(kontakt.id) ?? {},
},
};
});
// Plan the full stable audience first, then remove persisted successes. This
// preserves A/B assignment and throttling indices across partial retries.
const planVariants: PlanVariant[] = variants.map((variant) => ({
label: variant.label,
subject: variant.subject,
htmlBody: variant.htmlBody,
textBody: variant.textBody,
weightPercent: variant.weightPercent,
}));
const startAt = campaign.scheduledAt ? campaign.scheduledAt.getTime() : nowMs;
const plan = planCampaignSend({
recipients,
base: { subject: campaign.subject, htmlBody: campaign.htmlBody, textBody: campaign.textBody },
variants: planVariants,
footerHtml: campaign.footerHtml ?? "",
unsubscribeBaseUrl: input.baseUrl,
startAt,
ratePerMinute: resolveRatePerMinute(),
}).filter(({ outboundEmailId }) => !alreadyQueuedOutboundIds.has(outboundEmailId));
if (plan.length > 0) {
try {
await assertEmailMarketingQuotaReservation(tx, input.tenantId, plan.length, new Date(nowMs));
} catch (error) {
if (error instanceof EmailMarketingQuotaError) {
throw new CampaignSendError(
error.code === "EMAIL_MARKETING_PLAN_REQUIRED"
? "emailMarketing.send.error.planRequired"
: "emailMarketing.send.error.quotaExceeded"
);
}
throw error;
}
try {
await publishOutboxEvents(
tx,
plan.map((plannedEmail) => {
const dispatchKey = buildCampaignRecipientIdempotencyKey({
tenantId: input.tenantId,
campaignId: campaign.id,
kontaktId: plannedEmail.kontaktId,
});
return {
tenantId: input.tenantId,
type: "mail.transactional.send",
dispatchKey,
scheduledAt: new Date(plannedEmail.sendAt),
payload: {
tenantId: input.tenantId,
to: [plannedEmail.email],
subject: plannedEmail.subject,
html: plannedEmail.html,
...(plannedEmail.text ? { text: plannedEmail.text } : {}),
precedenceBulk: true,
listUnsubscribe: plannedEmail.listUnsubscribe,
settings: { trackOpens: campaign.track, trackClicks: campaign.track },
tags: ["email-marketing", `campaign:${campaign.id}`],
metadata: {
// Matches the pre-outbox BullMQ key for safe rollout retries.
idempotencyKey: plannedEmail.outboundEmailId,
outboundEmailId: plannedEmail.outboundEmailId,
campaignId: campaign.id,
...(plannedEmail.variantLabel ? { variant: plannedEmail.variantLabel } : {}),
},
},
};
})
);
} catch (error) {
if (error instanceof OutboxPublishError && error.code === "PAYLOAD_TOO_LARGE") {
throw new CampaignSendError("emailMarketing.send.error.contentTooLarge");
}
throw error;
}
let persistedCount = 0;
for (const planBatch of campaignQueryBatches(plan)) {
const persisted = await tx.outboundEmail.updateMany({
where: {
id: { in: planBatch.map(({ outboundEmailId }) => outboundEmailId) },
tenantId: input.tenantId,
campaignId: campaign.id,
sentAt: null,
},
data: { sentAt: new Date(nowMs) },
});
persistedCount += persisted.count;
}
if (persistedCount !== plan.length) {
throw new CampaignSendError("emailMarketing.send.error.persistenceFailed");
}
}
const completed = await tx.campaign.updateMany({
where: {
id: campaign.id,
tenantId: input.tenantId,
status: CLAIMED_CAMPAIGN_STATUS,
sentAt: null,
},
data: {
status: campaign.scheduledAt && campaign.scheduledAt.getTime() > nowMs ? "scheduled" : "sending",
sentAt: new Date(nowMs),
},
});
if (completed.count !== 1) {
throw new CampaignSendError("emailMarketing.send.error.persistenceFailed");
}
return {
campaignId: campaign.id,
enqueued: plan.length,
skippedSuppressed: kontakte.length - eligible.length,
recipientCount: kontaktIds.length,
checklist,
};
});
}
@@ -0,0 +1,132 @@
import { describe, expect, it, vi, beforeEach } from "vitest";
const rlsMocks = vi.hoisted(() => ({ tx: undefined as unknown }));
const tokenMocks = vi.hoisted(() => ({
sign: vi.fn(() => "signed-token"),
verify: vi.fn<(token: string | null | undefined, opts: { expectedPurpose: string }) => unknown>(() => null),
}));
vi.mock("~/utils/db/.server/tenantRls.server", () => ({
withTenantRLS: vi.fn(async (_tenantId: string, callback: (tx: unknown) => Promise<unknown>) => callback(rlsMocks.tx)),
}));
vi.mock("~/utils/email/marketingToken.server", () => ({
signMarketingToken: tokenMocks.sign,
verifyMarketingToken: tokenMocks.verify,
}));
import { confirmOptIn, getMarketingUnsubscribeConfirmationStatus, getOptInConfirmationStatus, startDoubleOptIn, unsubscribeKontakt } from "./ConsentService.server";
const NOW = new Date("2026-07-17T10:00:00.000Z");
function makeTx() {
return {
kontaktMarketingConsent: {
upsert: vi.fn(async () => ({})),
findUnique: vi.fn(async () => null as unknown),
updateMany: vi.fn(async () => ({ count: 1 })),
},
unsubscribe: {
findFirst: vi.fn(async () => null as unknown),
create: vi.fn(async () => ({})),
},
};
}
beforeEach(() => {
tokenMocks.sign.mockClear();
tokenMocks.verify.mockReset();
tokenMocks.verify.mockReturnValue(null);
});
describe("startDoubleOptIn", () => {
it("upserts a single consent with the minted token and clears unsubscribedAt on re-opt-in", async () => {
const tx = makeTx();
rlsMocks.tx = tx;
const result = await startDoubleOptIn({ tenantId: "t1", kontaktId: "k1", source: "form", now: () => NOW });
expect(result).toEqual({ token: "signed-token", status: "single" });
expect(tokenMocks.sign).toHaveBeenCalledWith(expect.objectContaining({ purpose: "optin", tenantId: "t1", kontaktId: "k1" }));
const upsert = tx.kontaktMarketingConsent.upsert.mock.calls[0][0] as {
create: Record<string, unknown>;
update: Record<string, unknown>;
};
expect(upsert.create).toMatchObject({ tenantId: "t1", kontaktId: "k1", status: "single", optInSource: "form", optInAt: NOW, doubleOptInToken: "signed-token" });
expect(upsert.update).toMatchObject({ status: "single", doubleOptInToken: "signed-token", unsubscribedAt: null });
});
});
describe("confirmOptIn", () => {
it("returns invalid for a bad token without touching the database", async () => {
const tx = makeTx();
rlsMocks.tx = tx;
expect(await confirmOptIn("bad")).toBe("invalid");
expect(tx.kontaktMarketingConsent.upsert).not.toHaveBeenCalled();
});
it("flips consent to double exactly once (idempotent on re-confirm)", async () => {
const tx = makeTx();
rlsMocks.tx = tx;
tokenMocks.verify.mockReturnValue({ purpose: "optin", tenantId: "t1", kontaktId: "k1" });
expect(await confirmOptIn("token", () => NOW)).toBe("confirmed");
const upsert = tx.kontaktMarketingConsent.upsert.mock.calls[0][0] as { update: Record<string, unknown> };
expect(upsert.update).toMatchObject({ status: "double", confirmedAt: NOW, unsubscribedAt: null });
tx.kontaktMarketingConsent.findUnique.mockResolvedValue({ status: "double" });
expect(await confirmOptIn("token", () => NOW)).toBe("already_confirmed");
expect(tx.kontaktMarketingConsent.upsert).toHaveBeenCalledTimes(1);
});
});
describe("getOptInConfirmationStatus", () => {
it("maps token/consent state to the public page status", async () => {
const tx = makeTx();
rlsMocks.tx = tx;
expect(await getOptInConfirmationStatus("bad")).toBe("invalid");
tokenMocks.verify.mockReturnValue({ purpose: "optin", tenantId: "t1", kontaktId: "k1" });
expect(await getOptInConfirmationStatus("token")).toBe("confirm");
tx.kontaktMarketingConsent.findUnique.mockResolvedValue({ status: "double" });
expect(await getOptInConfirmationStatus("token")).toBe("already_confirmed");
});
});
describe("unsubscribeKontakt", () => {
it("creates an unsubscribe row and stamps consent", async () => {
const tx = makeTx();
rlsMocks.tx = tx;
const result = await unsubscribeKontakt({ tenantId: "t1", kontaktId: "k1", campaignId: "c1", reason: "no-interest", now: () => NOW });
expect(result).toBe("unsubscribed");
expect(tx.unsubscribe.create).toHaveBeenCalledWith({
data: { tenantId: "t1", kontaktId: "k1", scope: "all", campaignId: "c1", reason: "no-interest" },
});
expect(tx.kontaktMarketingConsent.updateMany).toHaveBeenCalledWith({
where: { tenantId: "t1", kontaktId: "k1" },
data: { unsubscribedAt: NOW },
});
});
it("is idempotent for an existing all-scope unsubscribe", async () => {
const tx = makeTx();
rlsMocks.tx = tx;
tx.unsubscribe.findFirst.mockResolvedValue({ id: "u1" });
expect(await unsubscribeKontakt({ tenantId: "t1", kontaktId: "k1" })).toBe("already_unsubscribed");
expect(tx.unsubscribe.create).not.toHaveBeenCalled();
expect(tx.kontaktMarketingConsent.updateMany).not.toHaveBeenCalled();
});
});
describe("getMarketingUnsubscribeConfirmationStatus", () => {
it("maps token/unsubscribe state to the public page status", async () => {
const tx = makeTx();
rlsMocks.tx = tx;
expect(await getMarketingUnsubscribeConfirmationStatus("bad")).toBe("invalid");
tokenMocks.verify.mockReturnValue({ purpose: "unsub", tenantId: "t1", kontaktId: "k1" });
expect(await getMarketingUnsubscribeConfirmationStatus("token")).toBe("confirm");
tx.unsubscribe.findFirst.mockResolvedValue({ id: "u1" });
expect(await getMarketingUnsubscribeConfirmationStatus("token")).toBe("already_unsubscribed");
});
});
@@ -25,7 +25,14 @@ export async function startDoubleOptIn(input: { tenantId: string; kontaktId: str
await withTenantRLS(input.tenantId, async (tx) => {
await tx.kontaktMarketingConsent.upsert({
where: { tenantId_kontaktId: { tenantId: input.tenantId, kontaktId: input.kontaktId } },
create: { tenantId: input.tenantId, kontaktId: input.kontaktId, status: "single", optInSource: input.source ?? null, optInAt: at, doubleOptInToken: token },
create: {
tenantId: input.tenantId,
kontaktId: input.kontaktId,
status: "single",
optInSource: input.source ?? null,
optInAt: at,
doubleOptInToken: token,
},
update: { status: "single", optInSource: input.source ?? null, optInAt: at, doubleOptInToken: token, unsubscribedAt: null },
});
});
@@ -34,6 +41,21 @@ export async function startDoubleOptIn(input: { tenantId: string; kontaktId: str
export type ConfirmOptInResult = "confirmed" | "already_confirmed" | "invalid";
export type OptInConfirmationStatus = "confirm" | "already_confirmed" | "invalid";
/** Read-only status check used by the public confirmation page. */
export async function getOptInConfirmationStatus(token: string | null | undefined): Promise<OptInConfirmationStatus> {
const payload = verifyMarketingToken(token, { expectedPurpose: "optin" });
if (!payload) return "invalid";
return withTenantRLS(payload.tenantId, async (tx) => {
const existing = await tx.kontaktMarketingConsent.findUnique({
where: { tenantId_kontaktId: { tenantId: payload.tenantId, kontaktId: payload.kontaktId } },
select: { status: true },
});
return existing?.status === "double" ? "already_confirmed" : "confirm";
});
}
/** Verify a double-opt-in token and flip the contact's consent to `double`. */
export async function confirmOptIn(token: string | null | undefined, now?: ClockFn): Promise<ConfirmOptInResult> {
const payload = verifyMarketingToken(token, { expectedPurpose: "optin" });
@@ -56,6 +78,21 @@ export async function confirmOptIn(token: string | null | undefined, now?: Clock
export type UnsubscribeResult = "unsubscribed" | "already_unsubscribed";
export type MarketingUnsubscribeConfirmationStatus = "confirm" | "already_unsubscribed" | "invalid";
/** Read-only status check used by the public unsubscribe page. */
export async function getMarketingUnsubscribeConfirmationStatus(token: string | null | undefined): Promise<MarketingUnsubscribeConfirmationStatus> {
const payload = verifyMarketingToken(token, { expectedPurpose: "unsub" });
if (!payload) return "invalid";
return withTenantRLS(payload.tenantId, async (tx) => {
const existing = await tx.unsubscribe.findFirst({
where: { tenantId: payload.tenantId, kontaktId: payload.kontaktId, scope: "all" },
select: { id: true },
});
return existing ? "already_unsubscribed" : "confirm";
});
}
/** Write a tenant-scoped unsubscribe (one-click). Idempotent on (tenant, kontakt)
* for scope `all`; also stamps the consent row's `unsubscribedAt`. */
export async function unsubscribeKontakt(input: {
@@ -0,0 +1,31 @@
import { buildEmailMarketingSetupVM, type EmailMarketingSetupVM } from "@hivegrid/view-models";
import { withTenantRLS } from "~/utils/db/.server/tenantRls.server";
function footerIsReady(value: string | null): boolean {
const normalized = value?.toLocaleLowerCase("de-DE") ?? "";
return normalized.includes("unsubscribe") && (normalized.includes("impressum") || normalized.includes("imprint"));
}
export async function loadEmailMarketingSetup(tenantId: string): Promise<EmailMarketingSetupVM> {
const setup = await withTenantRLS(tenantId, async (tx) => {
const [domain, senderCount, footerCampaign] = await Promise.all([
tx.tenantSendingDomain.findFirst({
where: { tenantId, archivedAt: null },
orderBy: { createdAt: "desc" },
select: { domain: true, verificationStatus: true },
}),
tx.emailSender.count({ where: { tenantId } }),
tx.campaign.findFirst({
where: { tenantId, archivedAt: null, footerHtml: { not: null } },
orderBy: { sentAt: "desc" },
select: { footerHtml: true },
}),
]);
return {
domain: domain ? { status: domain.verificationStatus, label: domain.domain } : null,
senderCount,
footerReady: footerIsReady(footerCampaign?.footerHtml ?? null),
};
});
return buildEmailMarketingSetupVM(setup);
}
@@ -0,0 +1,162 @@
import { describe, expect, it, vi } from "vitest";
const rlsMocks = vi.hoisted(() => ({ tx: undefined as unknown }));
vi.mock("~/utils/db/.server/tenantRls.server", () => ({
withTenantRLS: vi.fn(async (_tenantId: string, callback: (tx: unknown) => Promise<unknown>) => callback(rlsMocks.tx)),
}));
import { resolveSegment, snapshotSegment } from "./SegmentService.server";
describe("large segment database fan-out", () => {
it("evaluates polymorphic lookups through bounded tenant-correlated EXISTS queries", async () => {
const tagId = "tag'; DROP TABLE \"Kontakt\"; --";
const customValue = "DE' OR TRUE --";
const rows = [
{
id: "kontakt-1",
createdAt: new Date("2026-07-13T10:00:00.000Z"),
vorname: "Ada",
nachname: "Lovelace",
orgName: null,
primaerEmail: "ada@example.test",
archivedAt: null,
},
];
const queryRawUnsafe = vi.fn(async (sql: string) => (sql.includes("COUNT(*)") ? [{ count: 1n }] : rows));
const tagAssignmentFindMany = vi.fn();
const customFieldValueFindMany = vi.fn();
const kontaktCount = vi.fn();
const kontaktFindMany = vi.fn();
rlsMocks.tx = {
$queryRawUnsafe: queryRawUnsafe,
kontakt: { count: kontaktCount, findMany: kontaktFindMany },
tagAssignment: { findMany: tagAssignmentFindMany },
customFieldValue: { findMany: customFieldValueFindMany },
unsubscribe: { findMany: vi.fn(async () => []) },
kontaktMarketingConsent: { findMany: vi.fn(async () => [{ kontaktId: "kontakt-1", status: "double" }]) },
emailSuppressionList: { findMany: vi.fn(async () => []) },
};
const resolution = await resolveSegment({
tenantId: "tenant-1",
ctx: { userId: "user-1", permissions: ["crm.read_own"] },
filterDefinition: {
op: "and",
children: [
{ field: "tag", tagId },
{ field: "customFieldEquals", definitionId: "country", value: customValue },
],
},
});
expect(resolution.eligibleKontaktIds).toEqual(["kontakt-1"]);
expect(tagAssignmentFindMany).not.toHaveBeenCalled();
expect(customFieldValueFindMany).not.toHaveBeenCalled();
expect(kontaktCount).not.toHaveBeenCalled();
expect(kontaktFindMany).not.toHaveBeenCalled();
expect(queryRawUnsafe).toHaveBeenCalledTimes(2);
for (const [sql, ...parameters] of queryRawUnsafe.mock.calls) {
expect(sql).toContain('ta."tenantId" = k."tenantId"');
expect(sql).toContain('cf."tenantId" = k."tenantId"');
expect(sql).not.toContain(tagId);
expect(sql).not.toContain(customValue);
expect(parameters.length).toBeLessThan(10);
expect(parameters.every((parameter) => !Array.isArray(parameter))).toBe(true);
}
expect(queryRawUnsafe.mock.calls[0]?.slice(1)).toEqual([tagId, "country", JSON.stringify(customValue), "tenant-1", "user-1"]);
});
it("keeps every exclusion query below the PostgreSQL bind limit across a 65k+ audience", async () => {
const audienceSize = 65_537;
const rows = Array.from({ length: audienceSize }, (_, index) => ({
id: `kontakt-${index}`,
createdAt: new Date(1_800_000_000_000 - index),
vorname: "Ada",
nachname: String(index),
orgName: null,
primaerEmail: `ada.${index}@example.test`,
archivedAt: null,
}));
let offset = 0;
const kontaktFindMany = vi.fn(async ({ take }: { take: number }) => {
const page = rows.slice(offset, offset + take);
offset += page.length;
return page;
});
const unsubscribeFindMany = vi.fn(async () => []);
const consentFindMany = vi.fn(async ({ where }: { where: { kontaktId: { in: string[] } } }) =>
where.kontaktId.in.map((kontaktId) => ({ kontaktId, status: "double" }))
);
const suppressionFindMany = vi.fn(async () => []);
rlsMocks.tx = {
kontakt: { count: vi.fn(async () => audienceSize), findMany: kontaktFindMany },
unsubscribe: { findMany: unsubscribeFindMany },
kontaktMarketingConsent: { findMany: consentFindMany },
emailSuppressionList: { findMany: suppressionFindMany },
};
const resolution = await resolveSegment({
tenantId: "tenant-1",
ctx: { userId: "user-1", permissions: ["crm.read_all"] },
filterDefinition: { field: "hasPrimaerEmail", value: true },
});
expect(resolution.matched).toBe(audienceSize);
expect(resolution.eligible).toBe(audienceSize);
expect(resolution.eligibleKontaktIds).toHaveLength(audienceSize);
expect(resolution.scanCapped).toBe(false);
expect(kontaktFindMany).toHaveBeenCalledTimes(7);
for (const mock of [unsubscribeFindMany, consentFindMany, suppressionFindMany]) {
expect(mock).toHaveBeenCalledTimes(7);
}
for (const call of consentFindMany.mock.calls) {
expect(call[0].where.kontaktId.in.length).toBeLessThanOrEqual(10_000);
}
expect(kontaktFindMany.mock.calls[1]?.[0]).toMatchObject({ cursor: { id: "kontakt-9999" }, skip: 1 });
});
it("writes a large static snapshot in bounded batches inside the tenant transaction", async () => {
const audienceSize = 4_001;
const rows = Array.from({ length: audienceSize }, (_, index) => ({
id: `kontakt-${index}`,
createdAt: new Date(1_800_000_000_000 - index),
vorname: null,
nachname: null,
orgName: `Company ${index}`,
primaerEmail: `company.${index}@example.test`,
archivedAt: null,
}));
const createMany = vi.fn(async () => ({ count: 0 }));
rlsMocks.tx = {
kontakt: {
count: vi.fn(async () => audienceSize),
findMany: vi.fn().mockResolvedValueOnce(rows),
},
unsubscribe: { findMany: vi.fn(async () => []) },
kontaktMarketingConsent: {
findMany: vi.fn(async ({ where }: { where: { kontaktId: { in: string[] } } }) =>
where.kontaktId.in.map((kontaktId) => ({ kontaktId, status: "double" }))
),
},
emailSuppressionList: { findMany: vi.fn(async () => []) },
segmentSnapshotMember: {
deleteMany: vi.fn(async () => ({ count: 0 })),
createMany,
},
};
await expect(
snapshotSegment({
tenantId: "tenant-1",
ctx: { userId: "user-1", permissions: ["crm.read_all"] },
segmentId: "segment-1",
filterDefinition: { field: "hasPrimaerEmail", value: true },
})
).resolves.toEqual({ memberCount: audienceSize });
expect(createMany).toHaveBeenCalledTimes(3);
expect(createMany.mock.calls.map(([input]) => input.data.length)).toEqual([2_000, 2_000, 1]);
expect(createMany.mock.calls.every(([input]) => input.skipDuplicates === true)).toBe(true);
});
});
@@ -2,21 +2,20 @@
//
// Resolves a RecipientSegment's nested AND/OR filter tree against the R-P6 TYPED
// Kontakt model (AD-2: NOT the Entity-Builder / CrmService). Tags + custom fields
// are polymorphic in crm.prisma (no Kontakt relation), so their leaves are
// resolved to Kontakt id-sets first (mirrors crmService.resolveKontaktBrowserWhere)
// and fed into the pure where-builder. Auto-exclusion removes contacts that must
// are polymorphic in crm.prisma (no Kontakt relation); their leaves are evaluated
// through tenant-correlated SQL EXISTS predicates so audience-sized ID lists are
// never materialized into Prisma IN parameters. Auto-exclusion removes contacts that must
// not receive marketing: archived, no e-mail, unsubscribed, suppressed (AK-P14a)
// or without a confirmed double-opt-in. Always tenant + owner scoped via
// withTenantRLS. NO React/UI imports.
import { withTenantRLS, type TenantRlsClient } from "~/utils/db/.server/tenantRls.server";
import { withTenantRLS } from "~/utils/db/.server/tenantRls.server";
import { ownerScopeWhere, type CrmVisibilityContext } from "~/utils/integrations/crm/crmService.server";
import {
buildKontaktWhere,
buildKontaktSqlPredicate,
collectLookupRefs,
lookupRefKey,
validateSegmentTree,
type LookupRef,
type SegmentNode,
type SegmentValidationError,
} from "~/utils/integrations/email/segmentFilter";
@@ -26,6 +25,8 @@ const KONTAKT_ENTITY_TYPE = "kontakt";
// segments larger than this are reported as capped (see `scanCapped`).
const MAX_SEGMENT_SCAN = 100_000;
const SAMPLE_SIZE = 50;
const SEGMENT_READ_BATCH_SIZE = 10_000;
const SEGMENT_SNAPSHOT_WRITE_BATCH_SIZE = 2_000;
/** Domain error carrying an i18n message key (M002 Klartext). */
export class SegmentServiceError extends Error {
@@ -64,6 +65,7 @@ export interface SegmentResolution {
type MatchedRow = {
id: string;
createdAt: Date;
vorname: string | null;
nachname: string | null;
orgName: string | null;
@@ -71,31 +73,20 @@ type MatchedRow = {
archivedAt: Date | null;
};
type SegmentCountRow = { count: bigint | number | string };
function numericCount(value: bigint | number | string | undefined): number {
if (typeof value === "bigint") return Number(value);
if (typeof value === "number") return value;
const parsed = Number(value ?? 0);
return Number.isFinite(parsed) ? parsed : 0;
}
function displayName(row: MatchedRow): string {
const person = [row.vorname, row.nachname].filter(Boolean).join(" ").trim();
return row.orgName?.trim() || person || row.primaerEmail || row.id;
}
/** Resolve one lookup leaf to the set of matching Kontakt ids (tenant-scoped). */
async function resolveLookupRef(tx: TenantRlsClient, tenantId: string, ref: LookupRef): Promise<string[]> {
if (ref.kind === "tag") {
const rows = await tx.tagAssignment.findMany({
where: { tenantId, entityType: KONTAKT_ENTITY_TYPE, tagId: ref.tagId },
select: { entityId: true },
});
return [...new Set(rows.map((r) => r.entityId))];
}
// custom-field leaves. `wert` is a Json column; for an equality leaf we compare
// the stored scalar in JS (Prisma returns the parsed value) — avoids the Json
// filter typing and is correct for string/number/boolean custom fields.
const rows = await tx.customFieldValue.findMany({
where: { tenantId, entityType: KONTAKT_ENTITY_TYPE, definitionId: ref.definitionId },
select: { entityId: true, wert: true },
});
const matched = ref.kind === "customFieldEquals" ? rows.filter((r) => r.wert === ref.value) : rows;
return [...new Set(matched.map((r) => r.entityId))];
}
/**
* Resolve a segment filter to a count / eligibility breakdown / sample. The
* returned `eligibleKontaktIds` is the audience the send-engine (S3) uses.
@@ -112,63 +103,132 @@ export async function resolveSegment(input: {
const tree: SegmentNode = validation.tree;
return withTenantRLS(input.tenantId, async (tx) => {
// 1. Resolve lookup leaves (tags / custom fields) to Kontakt id-sets.
// 1. Native-only trees stay on Prisma. Polymorphic lookup leaves use a
// bounded parameterized SQL predicate with correlated EXISTS subqueries.
const refs = collectLookupRefs(tree);
const resolved = new Map<string, readonly string[]>();
for (const ref of refs) {
resolved.set(lookupRefKey(ref), await resolveLookupRef(tx, input.tenantId, ref));
const lookupPredicate = refs.length > 0 ? buildKontaktSqlPredicate(tree) : null;
const ownerUserId = ownerScopeWhere(input.ctx).zustaendigerUserId;
const where = lookupPredicate
? null
: { AND: [{ tenantId: input.tenantId }, ownerScopeWhere(input.ctx), buildKontaktWhere(tree, new Map())] };
let total: number;
if (lookupPredicate) {
const parameters = [...lookupPredicate.parameters];
const bind = (value: unknown): string => {
parameters.push(value);
return `$${parameters.length}`;
};
const conditions = [`k."tenantId" = ${bind(input.tenantId)}`, `(${lookupPredicate.sql})`];
if (ownerUserId) conditions.push(`k."zustaendigerUserId" = ${bind(ownerUserId)}`);
const rows = await tx.$queryRawUnsafe<SegmentCountRow[]>(
`SELECT COUNT(*)::bigint AS "count" FROM "Kontakt" AS k WHERE ${conditions.join(" AND ")}`,
...parameters
);
total = numericCount(rows[0]?.count);
} else {
total = await tx.kontakt.count({ where: where! });
}
// 2. Build the typed where and pull the matched rows (archived included so we
// can attribute the "archived" exclusion reason).
const segmentWhere = buildKontaktWhere(tree, resolved);
const where = { AND: [{ tenantId: input.tenantId }, ownerScopeWhere(input.ctx), segmentWhere] };
const total = await tx.kontakt.count({ where });
const matchedRows = (await tx.kontakt.findMany({
where,
select: { id: true, vorname: true, nachname: true, orgName: true, primaerEmail: true, archivedAt: true },
orderBy: { createdAt: "desc" },
take: MAX_SEGMENT_SCAN,
})) as MatchedRow[];
const scanCapped = total > matchedRows.length;
// 3. Load auto-exclusion sources for the tenant.
const matchedIds = matchedRows.map((r) => r.id);
const matchedEmails = matchedRows.map((r) => r.primaerEmail).filter((e): e is string => Boolean(e));
const [unsubRows, consentRows, suppressionRows] = await Promise.all([
tx.unsubscribe.findMany({ where: { tenantId: input.tenantId, scope: "all", kontaktId: { in: matchedIds } }, select: { kontaktId: true } }),
tx.kontaktMarketingConsent.findMany({ where: { tenantId: input.tenantId, kontaktId: { in: matchedIds } }, select: { kontaktId: true, status: true } }),
tx.emailSuppressionList.findMany({ where: { tenantId: input.tenantId, emailAddress: { in: matchedEmails } }, select: { emailAddress: true } }),
]);
const unsubscribed = new Set(unsubRows.map((r) => r.kontaktId));
const confirmed = new Set(consentRows.filter((r) => r.status === "double").map((r) => r.kontaktId));
const suppressed = new Set(suppressionRows.map((r) => r.emailAddress.toLowerCase()));
// 4. Partition in priority order (non-overlapping).
// 3. Read and classify in bounded keyset pages. This preserves the existing
// scan cap while avoiding PostgreSQL's bind-parameter limit for large
// audiences. Normal-sized segments still complete in one page.
const exclusion: SegmentExclusionBreakdown = { archived: 0, noEmail: 0, unsubscribed: 0, suppressed: 0, noOptIn: 0 };
const eligibleKontaktIds: string[] = [];
const sample: SegmentSampleRow[] = [];
for (const row of matchedRows) {
if (row.archivedAt) {
exclusion.archived += 1;
} else if (!row.primaerEmail) {
exclusion.noEmail += 1;
} else if (unsubscribed.has(row.id)) {
exclusion.unsubscribed += 1;
} else if (suppressed.has(row.primaerEmail.toLowerCase())) {
exclusion.suppressed += 1;
} else if (!confirmed.has(row.id)) {
exclusion.noOptIn += 1;
let scanned = 0;
let cursor: Pick<MatchedRow, "id" | "createdAt"> | undefined;
while (scanned < MAX_SEGMENT_SCAN) {
const take = Math.min(SEGMENT_READ_BATCH_SIZE, MAX_SEGMENT_SCAN - scanned);
let matchedRows: MatchedRow[];
if (lookupPredicate) {
const parameters = [...lookupPredicate.parameters];
const bind = (value: unknown): string => {
parameters.push(value);
return `$${parameters.length}`;
};
const conditions = [`k."tenantId" = ${bind(input.tenantId)}`, `(${lookupPredicate.sql})`];
if (ownerUserId) conditions.push(`k."zustaendigerUserId" = ${bind(ownerUserId)}`);
if (cursor) {
conditions.push(`(k."createdAt", k."id") < (${bind(cursor.createdAt)}, ${bind(cursor.id)})`);
}
const limit = bind(take);
matchedRows = await tx.$queryRawUnsafe<MatchedRow[]>(
`SELECT k."id", k."createdAt", k."vorname", k."nachname", k."orgName", k."primaerEmail", k."archivedAt"
FROM "Kontakt" AS k
WHERE ${conditions.join(" AND ")}
ORDER BY k."createdAt" DESC, k."id" DESC
LIMIT ${limit}`,
...parameters
);
} else {
eligibleKontaktIds.push(row.id);
if (sample.length < SAMPLE_SIZE) {
sample.push({ kontaktId: row.id, name: displayName(row), email: row.primaerEmail });
matchedRows = (await tx.kontakt.findMany({
where: where!,
select: { id: true, createdAt: true, vorname: true, nachname: true, orgName: true, primaerEmail: true, archivedAt: true },
orderBy: [{ createdAt: "desc" }, { id: "desc" }],
take,
...(cursor ? { cursor: { id: cursor.id }, skip: 1 } : {}),
})) as MatchedRow[];
}
if (matchedRows.length === 0) break;
const matchedIds = matchedRows.map((row) => row.id);
const matchedEmails = [
...new Set(matchedRows.map((row) => row.primaerEmail).filter((email): email is string => Boolean(email))),
];
const [unsubRows, consentRows, suppressionRows] = await Promise.all([
tx.unsubscribe.findMany({
where: { tenantId: input.tenantId, scope: "all", kontaktId: { in: matchedIds } },
select: { kontaktId: true },
}),
tx.kontaktMarketingConsent.findMany({
where: { tenantId: input.tenantId, kontaktId: { in: matchedIds } },
select: { kontaktId: true, status: true },
}),
tx.emailSuppressionList.findMany({
where: { tenantId: input.tenantId, emailAddress: { in: matchedEmails } },
select: { emailAddress: true },
}),
]);
const unsubscribed = new Set(unsubRows.map((row) => row.kontaktId));
const confirmed = new Set(consentRows.filter((row) => row.status === "double").map((row) => row.kontaktId));
const suppressed = new Set(suppressionRows.map((row) => row.emailAddress.toLowerCase()));
// Partition in priority order so exclusion buckets remain non-overlapping.
for (const row of matchedRows) {
if (row.archivedAt) {
exclusion.archived += 1;
} else if (!row.primaerEmail) {
exclusion.noEmail += 1;
} else if (unsubscribed.has(row.id)) {
exclusion.unsubscribed += 1;
} else if (suppressed.has(row.primaerEmail.toLowerCase())) {
exclusion.suppressed += 1;
} else if (!confirmed.has(row.id)) {
exclusion.noOptIn += 1;
} else {
eligibleKontaktIds.push(row.id);
if (sample.length < SAMPLE_SIZE) {
sample.push({ kontaktId: row.id, name: displayName(row), email: row.primaerEmail });
}
}
}
scanned += matchedRows.length;
const lastRow = matchedRows.at(-1);
cursor = lastRow ? { id: lastRow.id, createdAt: lastRow.createdAt } : undefined;
if (matchedRows.length < take || !cursor) break;
}
return { matched: total, eligible: eligibleKontaktIds.length, exclusion, eligibleKontaktIds, sample, scanCapped };
return {
matched: total,
eligible: eligibleKontaktIds.length,
exclusion,
eligibleKontaktIds,
sample,
scanCapped: total > scanned,
};
});
}
@@ -232,9 +292,10 @@ export async function snapshotSegment(input: {
const resolution = await resolveSegment({ tenantId: input.tenantId, ctx: input.ctx, filterDefinition: input.filterDefinition });
await withTenantRLS(input.tenantId, async (tx) => {
await tx.segmentSnapshotMember.deleteMany({ where: { tenantId: input.tenantId, segmentId: input.segmentId } });
if (resolution.eligibleKontaktIds.length > 0) {
for (let offset = 0; offset < resolution.eligibleKontaktIds.length; offset += SEGMENT_SNAPSHOT_WRITE_BATCH_SIZE) {
const kontaktIds = resolution.eligibleKontaktIds.slice(offset, offset + SEGMENT_SNAPSHOT_WRITE_BATCH_SIZE);
await tx.segmentSnapshotMember.createMany({
data: resolution.eligibleKontaktIds.map((kontaktId) => ({ tenantId: input.tenantId, segmentId: input.segmentId, kontaktId })),
data: kontaktIds.map((kontaktId) => ({ tenantId: input.tenantId, segmentId: input.segmentId, kontaktId })),
skipDuplicates: true,
});
}