Track HiveGrid Cloud planning reference
This commit is contained in:
1 parent
b3d5ea6764
commit
e341c5938a
5784 files changed
+1104929
-3
No files matched your search
+48
@@ -0,0 +1,48 @@
|
||||
import type { EmailSender } from "@toolctrl/db/prisma-browser";
|
||||
import { createMailjetProvider } from "@toolctrl/mail";
|
||||
|
||||
type BroadcastEmail = {
|
||||
sender: EmailSender;
|
||||
to: string;
|
||||
subject: string;
|
||||
htmlBody: string;
|
||||
textBody: string;
|
||||
track: boolean;
|
||||
metadata: { [key: string]: string };
|
||||
};
|
||||
|
||||
async function sendMailjetBroadcast({ sender, to, subject, htmlBody, textBody, track }: BroadcastEmail) {
|
||||
if (!sender.apiKey || !sender.apiSecret) {
|
||||
throw Error("Invalid Mailjet API credentials");
|
||||
}
|
||||
|
||||
const mailjet = createMailjetProvider({
|
||||
apiKey: sender.apiKey,
|
||||
secretKey: sender.apiSecret,
|
||||
fromEmail: sender.fromEmail,
|
||||
fromName: sender.fromName ?? undefined,
|
||||
});
|
||||
|
||||
return await mailjet.send({
|
||||
from: { email: sender.fromEmail, name: sender.fromName ?? undefined },
|
||||
to: [to],
|
||||
replyTo: sender.replyToEmail ? { email: sender.replyToEmail, name: sender.fromName ?? undefined } : undefined,
|
||||
subject,
|
||||
html: htmlBody,
|
||||
text: textBody,
|
||||
tags: ["email-marketing"],
|
||||
settings: {
|
||||
trackClicks: track,
|
||||
trackOpens: track,
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
export async function sendBroadcast(email: BroadcastEmail) {
|
||||
switch (email.sender.provider) {
|
||||
case "mailjet":
|
||||
return await sendMailjetBroadcast(email);
|
||||
default:
|
||||
throw Error(`Unsupported email marketing sender provider: ${email.sender.provider}`);
|
||||
}
|
||||
}
|
||||
+171
@@ -0,0 +1,171 @@
|
||||
// @vitest-environment node
|
||||
import { beforeEach, describe, expect, it, vi } from "vitest";
|
||||
|
||||
const mocks = vi.hoisted(() => ({
|
||||
getContact: vi.fn(),
|
||||
getContactsInRowIds: vi.fn(),
|
||||
countOutboundEmails: vi.fn(),
|
||||
getAllOutboundEmails: vi.fn(),
|
||||
updateCampaign: vi.fn(),
|
||||
updateOutboundEmail: vi.fn(),
|
||||
sendBroadcast: vi.fn(),
|
||||
}));
|
||||
|
||||
vi.mock("~/modules/crm/services/CrmService", () => ({
|
||||
default: {
|
||||
getContact: mocks.getContact,
|
||||
getContactsInRowIds: mocks.getContactsInRowIds,
|
||||
},
|
||||
}));
|
||||
|
||||
vi.mock("../db/campaigns.db.server", () => ({
|
||||
createCampaign: vi.fn(),
|
||||
updateCampaign: mocks.updateCampaign,
|
||||
}));
|
||||
|
||||
vi.mock("../db/outboundEmails.db.server", () => ({
|
||||
countOutboundEmails: mocks.countOutboundEmails,
|
||||
getAllOutboundEmails: mocks.getAllOutboundEmails,
|
||||
createOutboundEmailTest: vi.fn(),
|
||||
updateOutboundEmail: mocks.updateOutboundEmail,
|
||||
createOutboundEmail: vi.fn(),
|
||||
}));
|
||||
|
||||
vi.mock("./EmailMarketingSenderService.server", () => ({
|
||||
sendBroadcast: mocks.sendBroadcast,
|
||||
}));
|
||||
|
||||
function campaignWithRecipients(count: number) {
|
||||
return {
|
||||
id: "campaign_1",
|
||||
tenantId: "tenant_1",
|
||||
emailSender: { id: "sender_1", email: "marketing@example.com" },
|
||||
subject: "Hello {{firstName}}",
|
||||
htmlBody: "<p>{{email}}</p>",
|
||||
textBody: "Hi {{firstName}}",
|
||||
track: true,
|
||||
recipients: Array.from({ length: count }, (_, index) => ({
|
||||
id: `outbound_${index + 1}`,
|
||||
email: `recipient-${index + 1}@example.com`,
|
||||
contactRowId: `row_${index + 1}`,
|
||||
contactRow: { id: `row_${index + 1}` },
|
||||
opens: [],
|
||||
clicks: [],
|
||||
campaign: null,
|
||||
})),
|
||||
};
|
||||
}
|
||||
|
||||
describe("EmailMarketingService.sendCampaign", () => {
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
mocks.getContact.mockImplementation(async (rowId: string) => ({
|
||||
id: rowId,
|
||||
email: `${rowId}@example.com`,
|
||||
firstName: rowId,
|
||||
lastName: "Recipient",
|
||||
jobTitle: "Buyer",
|
||||
company: { name: "Acme" },
|
||||
marketingSubscriber: true,
|
||||
}));
|
||||
mocks.getContactsInRowIds.mockImplementation(async (rowIds: string[]) =>
|
||||
rowIds.map((rowId) => ({
|
||||
id: rowId,
|
||||
email: `${rowId}@example.com`,
|
||||
firstName: rowId,
|
||||
lastName: "Recipient",
|
||||
jobTitle: "Buyer",
|
||||
company: { name: "Acme" },
|
||||
marketingSubscriber: true,
|
||||
}))
|
||||
);
|
||||
mocks.updateCampaign.mockResolvedValue({});
|
||||
mocks.updateOutboundEmail.mockResolvedValue({});
|
||||
});
|
||||
|
||||
it("limits concurrent broadcasts while completing a campaign", async () => {
|
||||
let active = 0;
|
||||
let maxActive = 0;
|
||||
mocks.sendBroadcast.mockImplementation(async () => {
|
||||
active += 1;
|
||||
maxActive = Math.max(maxActive, active);
|
||||
await Promise.resolve();
|
||||
active -= 1;
|
||||
});
|
||||
|
||||
const EmailMarketingService = (await import("./EmailMarketingService")).default;
|
||||
const campaign = campaignWithRecipients(6) as Parameters<typeof EmailMarketingService.sendCampaign>[0];
|
||||
await EmailMarketingService.sendCampaign(campaign, { concurrency: 2 });
|
||||
|
||||
expect(mocks.sendBroadcast).toHaveBeenCalledTimes(6);
|
||||
expect(mocks.getContact).not.toHaveBeenCalled();
|
||||
expect(mocks.getContactsInRowIds).toHaveBeenCalledTimes(1);
|
||||
expect(mocks.getContactsInRowIds).toHaveBeenCalledWith(
|
||||
["row_1", "row_2", "row_3", "row_4", "row_5", "row_6"],
|
||||
"tenant_1"
|
||||
);
|
||||
expect(maxActive).toBeLessThanOrEqual(2);
|
||||
expect(mocks.updateCampaign).toHaveBeenNthCalledWith(1, "campaign_1", "tenant_1", { status: "sending" });
|
||||
expect(mocks.updateCampaign).toHaveBeenLastCalledWith("campaign_1", "tenant_1", { status: "completed" });
|
||||
}, 10000);
|
||||
|
||||
it("marks missing prefetched contacts as incomplete without sending to them", async () => {
|
||||
mocks.getContactsInRowIds.mockImplementation(async (rowIds: string[]) =>
|
||||
rowIds
|
||||
.filter((rowId) => rowId !== "row_2")
|
||||
.map((rowId) => ({
|
||||
id: rowId,
|
||||
email: `${rowId}@example.com`,
|
||||
firstName: rowId,
|
||||
lastName: "Recipient",
|
||||
jobTitle: "Buyer",
|
||||
company: { name: "Acme" },
|
||||
marketingSubscriber: true,
|
||||
}))
|
||||
);
|
||||
|
||||
const EmailMarketingService = (await import("./EmailMarketingService")).default;
|
||||
const campaign = campaignWithRecipients(3) as Parameters<typeof EmailMarketingService.sendCampaign>[0];
|
||||
await EmailMarketingService.sendCampaign(campaign, { concurrency: 2 });
|
||||
|
||||
expect(mocks.getContact).not.toHaveBeenCalled();
|
||||
expect(mocks.getContactsInRowIds).toHaveBeenCalledTimes(1);
|
||||
expect(mocks.sendBroadcast).toHaveBeenCalledTimes(2);
|
||||
expect(mocks.updateOutboundEmail).toHaveBeenCalledWith("outbound_2", {
|
||||
error: "Could not parse contact not found: recipient-2@example.com",
|
||||
});
|
||||
expect(mocks.updateCampaign).toHaveBeenLastCalledWith("campaign_1", "tenant_1", { status: "incomplete" });
|
||||
});
|
||||
});
|
||||
|
||||
describe("EmailMarketingService.getSummary", () => {
|
||||
beforeEach(() => {
|
||||
vi.clearAllMocks();
|
||||
});
|
||||
|
||||
it("uses aggregate counts instead of loading detailed outbound email rows", async () => {
|
||||
mocks.countOutboundEmails
|
||||
.mockResolvedValueOnce(10)
|
||||
.mockResolvedValueOnce(8)
|
||||
.mockResolvedValueOnce(6)
|
||||
.mockResolvedValueOnce(5)
|
||||
.mockResolvedValueOnce(2);
|
||||
|
||||
const EmailMarketingService = (await import("./EmailMarketingService")).default;
|
||||
|
||||
await expect(EmailMarketingService.getSummary("tenant_1")).resolves.toEqual({
|
||||
avgOpenRate: 50,
|
||||
avgClickRate: 20,
|
||||
outboundEmails: {
|
||||
sent: 8,
|
||||
delivered: 6,
|
||||
},
|
||||
});
|
||||
expect(mocks.getAllOutboundEmails).not.toHaveBeenCalled();
|
||||
expect(mocks.countOutboundEmails).toHaveBeenNthCalledWith(1, "tenant_1");
|
||||
expect(mocks.countOutboundEmails).toHaveBeenNthCalledWith(2, "tenant_1", { where: { sentAt: { not: null } } });
|
||||
expect(mocks.countOutboundEmails).toHaveBeenNthCalledWith(3, "tenant_1", { where: { deliveredAt: { not: null } } });
|
||||
expect(mocks.countOutboundEmails).toHaveBeenNthCalledWith(4, "tenant_1", { where: { opens: { some: {} } } });
|
||||
expect(mocks.countOutboundEmails).toHaveBeenNthCalledWith(5, "tenant_1", { where: { clicks: { some: {} } } });
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,323 @@
|
||||
import type { Campaign, EmailSender } from "@toolctrl/db/prisma-browser";
|
||||
import { mapWithConcurrency } from "@toolctrl/foundation";
|
||||
import { EntityViewsApi } from "~/utils/api/.server/EntityViewsApi";
|
||||
import CrmService, { ContactDto } from "~/modules/crm/services/CrmService";
|
||||
import { createCampaign, CampaignWithDetails, updateCampaign } from "../db/campaigns.db.server";
|
||||
import { countOutboundEmails, createOutboundEmailTest, updateOutboundEmail, createOutboundEmail } from "../db/outboundEmails.db.server";
|
||||
import { sendBroadcast } from "./EmailMarketingSenderService.server";
|
||||
import { t as i18nT } from "i18next";
|
||||
|
||||
export type EmailMarketingSummaryDto = {
|
||||
avgOpenRate: number;
|
||||
avgClickRate: number;
|
||||
outboundEmails: {
|
||||
sent: number;
|
||||
delivered: number;
|
||||
};
|
||||
};
|
||||
async function getSummary(tenantId: string | null): Promise<EmailMarketingSummaryDto> {
|
||||
const [total, sent, delivered, outboundEmailsWithOpens, outboundEmailsWithClicks] = await Promise.all([
|
||||
countOutboundEmails(tenantId),
|
||||
countOutboundEmails(tenantId, { where: { sentAt: { not: null } } }),
|
||||
countOutboundEmails(tenantId, { where: { deliveredAt: { not: null } } }),
|
||||
countOutboundEmails(tenantId, { where: { opens: { some: {} } } }),
|
||||
countOutboundEmails(tenantId, { where: { clicks: { some: {} } } }),
|
||||
]);
|
||||
const avgOpenRate = total > 0 ? (outboundEmailsWithOpens / total) * 100 : 0;
|
||||
const avgClickRate = total > 0 ? (outboundEmailsWithClicks / total) * 100 : 0;
|
||||
return {
|
||||
avgOpenRate,
|
||||
avgClickRate,
|
||||
outboundEmails: {
|
||||
sent,
|
||||
delivered,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
async function sendPreview({
|
||||
from,
|
||||
email,
|
||||
}: {
|
||||
from: { tenantId: string | null; sender: EmailSender };
|
||||
email: { to: string; subject: string; htmlBody: string; textBody: string; track: true };
|
||||
}): Promise<boolean> {
|
||||
const outbountEmail = await createOutboundEmailTest({
|
||||
tenantId: from.tenantId,
|
||||
email: email.to,
|
||||
fromSenderId: from.sender.id,
|
||||
});
|
||||
try {
|
||||
email.htmlBody = replaceVariables(email.htmlBody, undefined);
|
||||
email.textBody = replaceVariables(email.textBody, undefined);
|
||||
email.subject = replaceVariables(email.subject, undefined);
|
||||
await sendBroadcast({
|
||||
sender: from.sender,
|
||||
to: email.to,
|
||||
subject: email.subject,
|
||||
htmlBody: email.htmlBody,
|
||||
textBody: email.textBody,
|
||||
track: email.track,
|
||||
metadata: { outboundEmailId: outbountEmail.id },
|
||||
});
|
||||
await updateOutboundEmail(outbountEmail.id, {
|
||||
sentAt: new Date(),
|
||||
});
|
||||
return true;
|
||||
} catch (e: any) {
|
||||
await updateOutboundEmail(outbountEmail.id, {
|
||||
error: e.message,
|
||||
});
|
||||
|
||||
throw e;
|
||||
}
|
||||
}
|
||||
|
||||
async function sendContactPreview({
|
||||
contactRowId,
|
||||
from,
|
||||
email,
|
||||
}: {
|
||||
contactRowId: string;
|
||||
from: { tenantId: string | null; sender: EmailSender };
|
||||
email: { to: string; subject: string; htmlBody: string; textBody: string; track: boolean };
|
||||
}): Promise<boolean> {
|
||||
const contact = await CrmService.getContact(contactRowId, from.tenantId);
|
||||
if (!contact) {
|
||||
throw Error("Contact not found: " + contactRowId);
|
||||
}
|
||||
const outbountEmail = await createOutboundEmail({
|
||||
tenantId: from.tenantId,
|
||||
contactRowId,
|
||||
email: email.to,
|
||||
fromSenderId: from.sender.id,
|
||||
});
|
||||
try {
|
||||
if (!contact.marketingSubscriber) {
|
||||
throw new Error(`Contact ${contact.email} is not a marketing subscriber`);
|
||||
}
|
||||
email.htmlBody = replaceVariables(email.htmlBody, contact);
|
||||
email.textBody = replaceVariables(email.textBody, contact);
|
||||
email.subject = replaceVariables(email.subject, contact);
|
||||
await sendBroadcast({
|
||||
sender: from.sender,
|
||||
to: email.to,
|
||||
subject: email.subject,
|
||||
htmlBody: email.htmlBody,
|
||||
textBody: email.textBody,
|
||||
track: email.track,
|
||||
metadata: { outboundEmailId: outbountEmail.id },
|
||||
});
|
||||
await updateOutboundEmail(outbountEmail.id, {
|
||||
sentAt: new Date(),
|
||||
});
|
||||
return true;
|
||||
} catch (e: any) {
|
||||
await updateOutboundEmail(outbountEmail.id, {
|
||||
error: e.message,
|
||||
});
|
||||
|
||||
throw e;
|
||||
}
|
||||
}
|
||||
|
||||
function replaceVariables(value: string, contact?: ContactDto): string {
|
||||
value = value.replace(/{{firstName}}/g, contact?.firstName ?? "");
|
||||
value = value.replace(/{{lastName}}/g, contact?.lastName ?? "");
|
||||
value = value.replace(/{{email}}/g, contact?.email ?? "");
|
||||
value = value.replace(/{{job_title}}/g, contact?.jobTitle ?? "");
|
||||
value = value.replace(/{{company_name}}/g, contact?.company?.name ?? "");
|
||||
return value;
|
||||
}
|
||||
|
||||
async function getCampaignRecipientContacts(campaign: CampaignWithDetails): Promise<Map<string, ContactDto>> {
|
||||
const contactRowIds = Array.from(
|
||||
new Set(campaign.recipients.map((recipient) => recipient.contactRow?.id).filter((id): id is string => Boolean(id)))
|
||||
);
|
||||
const contacts = contactRowIds.length > 0 ? await CrmService.getContactsInRowIds(contactRowIds, campaign.tenantId) : [];
|
||||
return new Map(contacts.map((contact) => [contact.id, contact]));
|
||||
}
|
||||
|
||||
async function createCampaignDraft({
|
||||
name,
|
||||
contactViewId,
|
||||
from,
|
||||
email,
|
||||
}: {
|
||||
name: string;
|
||||
contactViewId: string | undefined;
|
||||
from: { tenantId: string | null; sender: EmailSender };
|
||||
email: {
|
||||
subject: string;
|
||||
htmlBody: string;
|
||||
textBody: string | undefined;
|
||||
track: boolean;
|
||||
};
|
||||
}): Promise<Campaign> {
|
||||
const contacts = await getContactMarketingSubscribersFromView({ contactViewId, tenantId: from.tenantId });
|
||||
if (contacts.length === 0) {
|
||||
throw new Error("No contacts found that are marketing subscribers");
|
||||
}
|
||||
const campaign = await createCampaign(
|
||||
{
|
||||
emailSenderId: from.sender.id,
|
||||
tenantId: from.tenantId,
|
||||
name,
|
||||
subject: email.subject,
|
||||
htmlBody: email.htmlBody,
|
||||
textBody: email.textBody,
|
||||
track: email.track,
|
||||
},
|
||||
contacts.map((contact) => {
|
||||
return { contactRowId: contact.id, email: contact.email, fromSenderId: from.sender.id };
|
||||
})
|
||||
);
|
||||
|
||||
if (!campaign) {
|
||||
throw new Error("Failed to create campaign");
|
||||
}
|
||||
return campaign;
|
||||
}
|
||||
|
||||
async function getContactMarketingSubscribersFromView({
|
||||
contactViewId,
|
||||
tenantId,
|
||||
}: {
|
||||
contactViewId: string | undefined;
|
||||
tenantId: string | null;
|
||||
}): Promise<ContactDto[]> {
|
||||
const contactView = await EntityViewsApi.get(contactViewId, {
|
||||
tenantId,
|
||||
entityName: "contact",
|
||||
pageSize: -1,
|
||||
});
|
||||
if (!contactView) {
|
||||
if (contactViewId) {
|
||||
throw new Error("Contact view not found: " + contactViewId);
|
||||
} else {
|
||||
throw Error("Contact default view not found");
|
||||
}
|
||||
}
|
||||
if (contactView.rowsData.items.length === 0) {
|
||||
throw Error("No contacts found");
|
||||
}
|
||||
const contacts = await CrmService.getContactsInRowIds(
|
||||
contactView.rowsData.items.map((i) => i.id),
|
||||
tenantId
|
||||
);
|
||||
if (contacts.length === 0) {
|
||||
if (contactView.rowsData.currentView) {
|
||||
throw Error("No contacts found in view: " + contactView.rowsData.currentView.name);
|
||||
} else {
|
||||
throw Error("No contacts found in default view");
|
||||
}
|
||||
}
|
||||
const notMarketingSubscribers = contacts.filter((c) => !c.marketingSubscriber);
|
||||
if (notMarketingSubscribers.length > 0) {
|
||||
throw Error(
|
||||
`${notMarketingSubscribers.length}/${contacts.length} contacts are not marketing subscribers: ${notMarketingSubscribers.map((c) => c.email).join(", ")}`
|
||||
);
|
||||
}
|
||||
return contacts;
|
||||
}
|
||||
|
||||
async function sendCampaignTest(campaign: CampaignWithDetails, email: string): Promise<boolean> {
|
||||
if (campaign.recipients.length === 0) {
|
||||
throw new Error("No recipients found");
|
||||
}
|
||||
const notContacts = campaign.recipients.filter((r) => !r.contactRowId);
|
||||
if (notContacts.length > 0) {
|
||||
throw new Error("Campaign has non-contact recipients: " + notContacts.map((r) => r.email).join(", "));
|
||||
}
|
||||
let maxTests = 5;
|
||||
let recipients = campaign.recipients.slice(0, maxTests);
|
||||
await Promise.all(
|
||||
recipients.map(async (recipient, idx) => {
|
||||
await sendContactPreview({
|
||||
contactRowId: recipient.contactRowId ?? "",
|
||||
from: {
|
||||
tenantId: campaign.tenantId,
|
||||
sender: campaign.emailSender,
|
||||
},
|
||||
email: {
|
||||
to: email,
|
||||
subject: i18nT("emailMarketing:campaignPreview.testSubject", {
|
||||
index: idx + 1,
|
||||
total: campaign.recipients.length,
|
||||
subject: campaign.subject,
|
||||
}),
|
||||
htmlBody: campaign.htmlBody,
|
||||
textBody: campaign.textBody ?? "",
|
||||
track: campaign.track,
|
||||
},
|
||||
});
|
||||
})
|
||||
);
|
||||
return true;
|
||||
}
|
||||
|
||||
async function sendCampaign(campaign: CampaignWithDetails, options: { concurrency?: number } = {}): Promise<boolean> {
|
||||
if (campaign.recipients.length === 0) {
|
||||
throw new Error("No recipients found");
|
||||
}
|
||||
|
||||
const notContacts = campaign.recipients.filter((r) => !r.contactRowId);
|
||||
if (notContacts.length > 0) {
|
||||
throw new Error("Campaign has non-contact recipients: " + notContacts.map((r) => r.email).join(", "));
|
||||
}
|
||||
await updateCampaign(campaign.id, campaign.tenantId, {
|
||||
status: "sending",
|
||||
});
|
||||
const contactsByRowId = await getCampaignRecipientContacts(campaign);
|
||||
let totalSent = 0;
|
||||
await mapWithConcurrency(campaign.recipients, options.concurrency ?? 5, async (recipient) => {
|
||||
try {
|
||||
if (!recipient.contactRow) {
|
||||
throw new Error("Contact not found: " + recipient.email);
|
||||
}
|
||||
const contact = contactsByRowId.get(recipient.contactRow.id);
|
||||
if (!contact) {
|
||||
throw new Error("Could not parse contact not found: " + recipient.email);
|
||||
}
|
||||
await updateOutboundEmail(recipient.id, {
|
||||
sentAt: new Date(),
|
||||
error: undefined,
|
||||
});
|
||||
await sendBroadcast({
|
||||
sender: campaign.emailSender,
|
||||
to: recipient.email,
|
||||
subject: replaceVariables(campaign.subject, contact),
|
||||
htmlBody: replaceVariables(campaign.htmlBody, contact),
|
||||
textBody: replaceVariables(campaign.textBody ?? "", contact),
|
||||
track: campaign.track,
|
||||
metadata: { outboundEmailId: recipient.id },
|
||||
});
|
||||
totalSent++;
|
||||
} catch (e: any) {
|
||||
await updateOutboundEmail(recipient.id, {
|
||||
error: e.message,
|
||||
});
|
||||
}
|
||||
});
|
||||
|
||||
if (totalSent === campaign.recipients.length) {
|
||||
await updateCampaign(campaign.id, campaign.tenantId, {
|
||||
status: "completed",
|
||||
});
|
||||
} else {
|
||||
await updateCampaign(campaign.id, campaign.tenantId, {
|
||||
status: "incomplete",
|
||||
});
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
export default {
|
||||
getSummary,
|
||||
getContactMarketingSubscribersFromView,
|
||||
sendPreview,
|
||||
sendContactPreview,
|
||||
createCampaignDraft,
|
||||
sendCampaignTest,
|
||||
sendCampaign,
|
||||
};
|
||||
Reference in new issue
Block a user