diff --git a/apps/api/src/controllers/Analytics.ts b/apps/api/src/controllers/Analytics.ts index ba407b0e7..ea61b2369 100644 --- a/apps/api/src/controllers/Analytics.ts +++ b/apps/api/src/controllers/Analytics.ts @@ -5,6 +5,7 @@ import type {NextFunction, Request, Response} from 'express'; import {type FieldError, ValidationError} from '../exceptions/index.js'; import {requireAuth, requireEmailVerified} from '../middleware/auth.js'; import {type AnalyticsQuery, AnalyticsService} from '../services/AnalyticsService.js'; +import {EmailService} from '../services/EmailService.js'; import {CatchAsync} from '../utils/asyncHandler.js'; const STREAMS: AnalyticsStream[] = ['ALL', 'TRANSACTIONAL', 'CAMPAIGN', 'WORKFLOW']; @@ -20,8 +21,10 @@ const DAY_MS = 24 * 60 * 60 * 1000; * * Clients should send stable bounds (day boundaries rather than "now") so repeat loads hit * the cache; the server never draws buckets past the current time. + * + * The streams sent with open and click tracking come from the project's tracking mode. */ -function parseQuery(req: Request, res: Response): AnalyticsQuery { +async function parseQuery(req: Request, res: Response): Promise { const errors: FieldError[] = []; const parseDate = (field: 'from' | 'to'): Date | undefined => { @@ -61,7 +64,8 @@ function parseQuery(req: Request, res: Response): AnalyticsQuery { throw new ValidationError(errors); } - return {projectId: res.locals.auth.projectId, from, to, tz, stream}; + const projectId: string = res.locals.auth.projectId; + return {projectId, from, to, tz, stream, trackedStreams: await EmailService.trackedStreams(projectId)}; } function isValidTimezone(tz: string): boolean { @@ -83,7 +87,7 @@ export class Analytics { @Middleware([requireAuth, requireEmailVerified]) @CatchAsync public async getOverview(req: Request, res: Response, _next: NextFunction) { - return res.status(200).json(await AnalyticsService.getOverview(parseQuery(req, res))); + return res.status(200).json(await AnalyticsService.getOverview(await parseQuery(req, res))); } /** @@ -94,7 +98,7 @@ export class Analytics { @Middleware([requireAuth, requireEmailVerified]) @CatchAsync public async getTimeseries(req: Request, res: Response, _next: NextFunction) { - return res.status(200).json(await AnalyticsService.getTimeseries(parseQuery(req, res))); + return res.status(200).json(await AnalyticsService.getTimeseries(await parseQuery(req, res))); } /** @@ -105,7 +109,7 @@ export class Analytics { @Middleware([requireAuth, requireEmailVerified]) @CatchAsync public async getDeliverability(req: Request, res: Response, _next: NextFunction) { - return res.status(200).json(await AnalyticsService.getDeliverability(parseQuery(req, res))); + return res.status(200).json(await AnalyticsService.getDeliverability(await parseQuery(req, res))); } /** @@ -116,7 +120,7 @@ export class Analytics { @Middleware([requireAuth, requireEmailVerified]) @CatchAsync public async getLeaderboard(req: Request, res: Response, _next: NextFunction) { - const query = parseQuery(req, res); + const query = await parseQuery(req, res); const kind = String(req.query.kind ?? 'campaigns') as AnalyticsLeaderboardKind; if (!LEADERBOARD_KINDS.includes(kind)) { @@ -136,7 +140,7 @@ export class Analytics { @Middleware([requireAuth, requireEmailVerified]) @CatchAsync public async getLinks(req: Request, res: Response, _next: NextFunction) { - return res.status(200).json(await AnalyticsService.getLinks(parseQuery(req, res))); + return res.status(200).json(await AnalyticsService.getLinks(await parseQuery(req, res))); } /** @@ -147,7 +151,7 @@ export class Analytics { @Middleware([requireAuth, requireEmailVerified]) @CatchAsync public async getHeatmap(req: Request, res: Response, _next: NextFunction) { - return res.status(200).json(await AnalyticsService.getHeatmap(parseQuery(req, res))); + return res.status(200).json(await AnalyticsService.getHeatmap(await parseQuery(req, res))); } /** @@ -158,7 +162,7 @@ export class Analytics { @Middleware([requireAuth, requireEmailVerified]) @CatchAsync public async getAudience(req: Request, res: Response, _next: NextFunction) { - return res.status(200).json(await AnalyticsService.getAudience(parseQuery(req, res))); + return res.status(200).json(await AnalyticsService.getAudience(await parseQuery(req, res))); } /** @@ -169,6 +173,6 @@ export class Analytics { @Middleware([requireAuth, requireEmailVerified]) @CatchAsync public async getTopEvents(req: Request, res: Response, _next: NextFunction) { - return res.status(200).json(await AnalyticsService.getTopEvents(parseQuery(req, res))); + return res.status(200).json(await AnalyticsService.getTopEvents(await parseQuery(req, res))); } } diff --git a/apps/api/src/services/ActivityService.ts b/apps/api/src/services/ActivityService.ts index c6edb5fb2..e28b52f6f 100644 --- a/apps/api/src/services/ActivityService.ts +++ b/apps/api/src/services/ActivityService.ts @@ -6,6 +6,7 @@ import signale from 'signale'; import {prisma} from '../database/prisma.js'; import {redis} from '../database/redis.js'; import {HttpException} from '../exceptions/index.js'; +import {EmailService} from './EmailService.js'; import {Keys} from './keys.js'; /** @@ -193,8 +194,17 @@ export class ActivityService { * Falls back to database aggregation if cache miss */ public static async getStats(projectId: string, startDate?: Date, endDate?: Date): Promise { + // Opens and clicks are measured against the streams the project tracks now, so they are + // part of the cache key: changing the tracking mode must not serve stats from the old one + const trackedStreams = await EmailService.trackedStreams(projectId); + // Try to get from cache - const cacheKey = Keys.Activity.stats(projectId, startDate?.getTime() || 'all', endDate?.getTime() || 'now'); + const cacheKey = Keys.Activity.stats( + projectId, + startDate?.getTime() || 'all', + endDate?.getTime() || 'now', + trackedStreams.join(','), + ); try { const cached = await redis.get(cacheKey); @@ -214,7 +224,7 @@ export class ActivityService { }; // Compute stats from database (in parallel for performance) - const [totalEvents, emailStats] = await Promise.all([ + const [totalEvents, emailGroups] = await Promise.all([ // Count total events prisma.event.count({ where: { @@ -223,16 +233,17 @@ export class ActivityService { }, }), - // Aggregate email stats - prisma.email.aggregate({ + // Email counts per stream, so opens and clicks can be measured against tracked emails. + // Every column read here is in emails_projectId_createdAt_stats_idx, so the counts are + // served from that index alone + prisma.email.groupBy({ + by: ['sourceType', 'simulated'], where: { projectId, createdAt: dateFilter, }, - // _all rather than id: COUNT(*) can be served from emails_projectId_createdAt_stats_idx - // alone, COUNT("id") would need every row fetched since id is not in that index _count: { - _all: true, + sentAt: true, openedAt: true, clickedAt: true, }, @@ -249,18 +260,25 @@ export class ActivityService { }, }); - const totalEmailsSent = emailStats._count._all; - const totalEmailsOpened = emailStats._count.openedAt || 0; - const totalEmailsClicked = emailStats._count.clickedAt || 0; + // Measured as analytics does: outbound emails that went out, leaving out mail to the SES + // mailbox simulator, which never reaches anyone + const outbound = emailGroups.filter(group => !group.simulated && group.sourceType !== 'INBOUND'); + const tracked = outbound.filter(group => trackedStreams.includes(group.sourceType)); + + const totalEmailsSent = outbound.reduce((sum, group) => sum + group._count.sentAt, 0); + const totalEmailsTracked = tracked.reduce((sum, group) => sum + group._count.sentAt, 0); + const totalEmailsOpened = tracked.reduce((sum, group) => sum + group._count.openedAt, 0); + const totalEmailsClicked = tracked.reduce((sum, group) => sum + group._count.clickedAt, 0); const stats: ActivityStats = { totalEvents, totalEmailsSent, + totalEmailsTracked, totalEmailsOpened, totalEmailsClicked, totalWorkflowsStarted, - openRate: totalEmailsSent > 0 ? (totalEmailsOpened / totalEmailsSent) * 100 : 0, - clickRate: totalEmailsSent > 0 ? (totalEmailsClicked / totalEmailsSent) * 100 : 0, + openRate: totalEmailsTracked > 0 ? (totalEmailsOpened / totalEmailsTracked) * 100 : 0, + clickRate: totalEmailsTracked > 0 ? (totalEmailsClicked / totalEmailsTracked) * 100 : 0, }; // Cache for 5 minutes diff --git a/apps/api/src/services/AnalyticsService.ts b/apps/api/src/services/AnalyticsService.ts index 6fa958c39..8a2eb3fee 100644 --- a/apps/api/src/services/AnalyticsService.ts +++ b/apps/api/src/services/AnalyticsService.ts @@ -1,3 +1,4 @@ +import type {EmailSourceType} from '@plunk/db'; import {Prisma} from '@plunk/db'; import type { AnalyticsAudience, @@ -34,6 +35,11 @@ export interface AnalyticsQuery { /** IANA timezone used to bucket by local hour and day */ tz: string; stream: AnalyticsStream; + /** + * Streams sent with open and click tracking under the project's current tracking mode, + * resolved by the controller from the project + */ + trackedStreams: EmailSourceType[]; } type CountRow = Record, bigint>; @@ -87,8 +93,10 @@ export class AnalyticsService { /** * Rates are measured against emails sent, matching the campaign stats endpoint, so the - * same campaign shows the same open rate here and on its own page. Click-to-open is the - * one exception: it answers "of the people who opened, how many clicked". + * same campaign shows the same rates here and on its own page. Opens and clicks are + * measured against the emails sent with tracking, since no other email can record them, + * which keeps that match for every campaign the project tracks. Click-to-open answers + * "of the people who opened, how many clicked". */ public static toMetrics(counts: EmailMetricCounts): EmailMetrics { const pct = (part: number, whole: number) => (whole > 0 ? Math.round((part / whole) * 10000) / 100 : 0); @@ -96,8 +104,8 @@ export class AnalyticsService { return { ...counts, deliveryRate: pct(counts.delivered, counts.sent), - openRate: pct(counts.opened, counts.sent), - clickRate: pct(counts.clicked, counts.sent), + openRate: pct(counts.opened, counts.tracked), + clickRate: pct(counts.clicked, counts.tracked), clickToOpenRate: pct(counts.clicked, counts.opened), bounceRate: pct(counts.bounced, counts.sent), complaintRate: pct(counts.complained, counts.sent), @@ -142,7 +150,7 @@ export class AnalyticsService { private static async countsByStream(query: AnalyticsQuery): Promise> { const [counts, unsubscribes] = await Promise.all([ prisma.$queryRaw<(CountRow & {stream: string})[]>` - SELECT e."sourceType"::text AS stream, ${COUNT_COLUMNS} + SELECT e."sourceType"::text AS stream, ${countColumns(query)} FROM "emails" e WHERE ${emailScope(query, 'ALL')} GROUP BY e."sourceType" @@ -190,7 +198,7 @@ export class AnalyticsService { const rows = await prisma.$queryRaw<(CountRow & {bucket: string; unsubscribed: bigint})[]>` WITH buckets AS (${bucketSeries(query, granularity)}), counts AS ( - SELECT ${bucket} AS bucket, ${COUNT_COLUMNS} + SELECT ${bucket} AS bucket, ${countColumns(query)} FROM "emails" e WHERE ${emailScope(query)} GROUP BY 1 @@ -203,7 +211,7 @@ export class AnalyticsService { GROUP BY 1 ) SELECT to_char(b.bucket, 'YYYY-MM-DD"T"HH24:MI') AS bucket, - COALESCE(c.sent, 0) AS sent, COALESCE(c.delivered, 0) AS delivered, + COALESCE(c.sent, 0) AS sent, COALESCE(c.tracked, 0) AS tracked, COALESCE(c.delivered, 0) AS delivered, COALESCE(c.opened, 0) AS opened, COALESCE(c.clicked, 0) AS clicked, COALESCE(c.bounced, 0) AS bounced, COALESCE(c.complained, 0) AS complained, COALESCE(u.unsubscribed, 0) AS unsubscribed @@ -240,7 +248,7 @@ export class AnalyticsService { ${eventStreamFilter(query.stream)} `, prisma.$queryRaw<(CountRow & {domain: string})[]>` - SELECT lower(split_part(c."email", '@', 2)) AS domain, ${COUNT_COLUMNS} + SELECT lower(split_part(c."email", '@', 2)) AS domain, ${countColumns(query)} FROM "emails" e JOIN "contacts" c ON c."id" = e."contactId" WHERE ${emailScope(query)} @@ -259,6 +267,7 @@ export class AnalyticsService { return { domain: row.domain, sent: metrics.sent, + tracked: metrics.tracked, deliveryRate: metrics.deliveryRate, openRate: metrics.openRate, bounceRate: metrics.bounceRate, @@ -290,7 +299,10 @@ export class AnalyticsService { /** * Campaigns keep reconciled counters on their own row, so this reads those instead of - * recounting their emails, and the numbers match the campaign page exactly. A campaign + * recounting their emails, and the numbers match the campaign page exactly, except that a + * campaign the current tracking mode does not track has no open or click rate here. Its + * type sets the stream of every email it sends (CampaignService passes it as + * isTransactional), so the current mode tracks a campaign whole or not at all. A campaign * belongs to the period it started sending in. */ private static async campaignLeaderboard(query: AnalyticsQuery): Promise { @@ -303,6 +315,7 @@ export class AnalyticsService { select: { id: true, name: true, + type: true, sentAt: true, sentCount: true, deliveredCount: true, @@ -316,27 +329,32 @@ export class AnalyticsService { take: this.LEADERBOARD_LIMIT, }); - return campaigns.map(c => ({ - id: c.id, - name: c.name, - sentAt: c.sentAt?.toISOString() ?? null, - ...this.toMetrics({ - sent: c.sentCount, - delivered: c.deliveredCount, - opened: c.openedCount, - clicked: c.clickedCount, - bounced: c.bouncedCount, - complained: c.complainedCount, - unsubscribed: c.unsubscribedCount, - }), - })); + return campaigns.map(c => { + const stream: EmailSourceType = c.type === 'TRANSACTIONAL' ? 'TRANSACTIONAL' : 'CAMPAIGN'; + const tracked = query.trackedStreams.includes(stream); + return { + id: c.id, + name: c.name, + sentAt: c.sentAt?.toISOString() ?? null, + ...this.toMetrics({ + sent: c.sentCount, + tracked: tracked ? c.sentCount : 0, + delivered: c.deliveredCount, + opened: tracked ? c.openedCount : 0, + clicked: tracked ? c.clickedCount : 0, + bounced: c.bouncedCount, + complained: c.complainedCount, + unsubscribed: c.unsubscribedCount, + }), + }; + }); } private static async templateLeaderboard(query: AnalyticsQuery): Promise { const scoped = {...query, stream: 'TRANSACTIONAL' as const}; const [counts, unsubscribes] = await Promise.all([ prisma.$queryRaw<(CountRow & {id: string | null})[]>` - SELECT e."templateId" AS id, ${COUNT_COLUMNS} + SELECT e."templateId" AS id, ${countColumns(scoped)} FROM "emails" e WHERE ${emailScope(scoped)} GROUP BY 1 @@ -365,7 +383,7 @@ export class AnalyticsService { const scoped = {...query, stream: 'WORKFLOW' as const}; const [counts, unsubscribes] = await Promise.all([ prisma.$queryRaw<(CountRow & {id: string})[]>` - SELECT we."workflowId" AS id, ${COUNT_COLUMNS} + SELECT we."workflowId" AS id, ${countColumns(scoped)} FROM "emails" e JOIN "workflow_executions" we ON we."id" = e."workflowExecutionId" WHERE ${emailScope(scoped)} @@ -585,7 +603,7 @@ export class AnalyticsService { const key = Keys.Analytics.query( query.projectId, kind, - `${query.from.toISOString()}:${query.to.toISOString()}:${query.tz}:${query.stream}`, + `${query.from.toISOString()}:${query.to.toISOString()}:${query.tz}:${query.stream}:${query.trackedStreams.join(',')}`, ); const hit = await redis.get(key); @@ -675,26 +693,54 @@ function eventStreamFilter(stream: AnalyticsStream): Prisma.Sql { return stream === 'ALL' ? Prisma.empty : Prisma.sql`AND ev."data"->>'sourceType' = ${stream}`; } -const COUNT_COLUMNS = Prisma.sql` - COUNT(e."sentAt") AS sent, - COUNT(e."deliveredAt") AS delivered, - COUNT(e."openedAt") AS opened, - COUNT(e."clickedAt") AS clicked, - COUNT(e."bouncedAt") AS bounced, - COUNT(e."complainedAt") AS complained -`; +/** + * Opens and clicks only count on the streams the project tracks, the same streams that + * make up `tracked`, so neither rate can pass 100% after the tracking mode changes + */ +function countColumns(query: AnalyticsQuery): Prisma.Sql { + const tracked = trackedFilter(query); + return Prisma.sql` + COUNT(e."sentAt") AS sent, + COUNT(e."sentAt") FILTER (WHERE ${tracked}) AS tracked, + COUNT(e."deliveredAt") AS delivered, + COUNT(e."openedAt") FILTER (WHERE ${tracked}) AS opened, + COUNT(e."clickedAt") FILTER (WHERE ${tracked}) AS clicked, + COUNT(e."bouncedAt") AS bounced, + COUNT(e."complainedAt") AS complained + `; +} + +/** + * Each stream as a SQL literal rather than a bound parameter: Postgres casts a literal to + * "EmailSourceType" once, while a parameter cast to it is cast again on every row counted + */ +const STREAM_SQL: Record = { + TRANSACTIONAL: Prisma.sql`'TRANSACTIONAL'`, + CAMPAIGN: Prisma.sql`'CAMPAIGN'`, + WORKFLOW: Prisma.sql`'WORKFLOW'`, + INBOUND: Prisma.sql`'INBOUND'`, +}; + +/** Emails in a stream sent with open and click tracking; none when tracking is disabled */ +function trackedFilter(query: AnalyticsQuery): Prisma.Sql { + if (query.trackedStreams.length === 0) { + return Prisma.sql`FALSE`; + } + return Prisma.sql`e."sourceType" IN (${Prisma.join(query.trackedStreams.map(stream => STREAM_SQL[stream]))})`; +} // ============================================================================= // HELPERS // ============================================================================= function emptyCounts(): EmailMetricCounts { - return {sent: 0, delivered: 0, opened: 0, clicked: 0, bounced: 0, complained: 0, unsubscribed: 0}; + return {sent: 0, tracked: 0, delivered: 0, opened: 0, clicked: 0, bounced: 0, complained: 0, unsubscribed: 0}; } function addCounts(a: EmailMetricCounts, b: EmailMetricCounts): EmailMetricCounts { return { sent: a.sent + b.sent, + tracked: a.tracked + b.tracked, delivered: a.delivered + b.delivered, opened: a.opened + b.opened, clicked: a.clicked + b.clicked, @@ -707,6 +753,7 @@ function addCounts(a: EmailMetricCounts, b: EmailMetricCounts): EmailMetricCount function toCounts(row: CountRow): Omit { return { sent: Number(row.sent), + tracked: Number(row.tracked), delivered: Number(row.delivered), opened: Number(row.opened), clicked: Number(row.clicked), diff --git a/apps/api/src/services/EmailService.ts b/apps/api/src/services/EmailService.ts index 9d466745b..450201f39 100644 --- a/apps/api/src/services/EmailService.ts +++ b/apps/api/src/services/EmailService.ts @@ -3,13 +3,14 @@ import {EmailSourceType, EmailStatus, TrackingMode} from '@plunk/db'; import {toPrismaJson} from '@plunk/types'; import signale from 'signale'; -import {DASHBOARD_URI, LANDING_URI, STRIPE_ENABLED} from '../app/constants.js'; +import {DASHBOARD_URI, LANDING_URI, STRIPE_ENABLED, TRACKING_TOGGLE_ENABLED} from '../app/constants.js'; import {prisma} from '../database/prisma.js'; import {HttpException} from '../exceptions/index.js'; import {createTranslatorSync, renderTemplate} from '@plunk/shared'; import {BillingLimitService} from './BillingLimitService.js'; import {withSourceEmail} from './EmailHeaderService.js'; +import {ProjectService} from './ProjectService.js'; import {QueueService} from './QueueService.js'; interface Attachment { @@ -317,6 +318,33 @@ export class EmailService { } } + /** + * The outbound streams sent with open and click tracking under a tracking mode, so stats + * measure opens and clicks only against emails that could record them. Mirrors + * SESService: without a no-tracking configuration set every email goes out tracked. + */ + public static trackedSourceTypes( + trackingMode: TrackingMode, + toggleEnabled: boolean = TRACKING_TOGGLE_ENABLED, + ): EmailSourceType[] { + const outbound = Object.values(EmailSourceType).filter(type => type !== EmailSourceType.INBOUND); + return toggleEnabled ? outbound.filter(type => this.shouldTrackEmail(trackingMode, type)) : outbound; + } + + /** + * The tracked streams of a project under its current tracking mode. A project that cannot + * be found or read counts as tracking everything, the default mode, so stats still load. + */ + public static async trackedStreams(projectId: string): Promise { + try { + const project = await ProjectService.id(projectId); + return this.trackedSourceTypes(project?.tracking ?? TrackingMode.ENABLED); + } catch (error) { + signale.warn('[EMAIL] Failed to read the tracking mode, measuring stats as if everything is tracked:', error); + return this.trackedSourceTypes(TrackingMode.ENABLED); + } + } + /** * Detects if HTML contains custom patterns that indicate it was written in the HTML editor * rather than the visual editor. Mirrors the same logic in apps/web/src/lib/emailStyles.ts. diff --git a/apps/api/src/services/__tests__/ActivityService.test.ts b/apps/api/src/services/__tests__/ActivityService.test.ts index f7489f6f7..b15c3084e 100644 --- a/apps/api/src/services/__tests__/ActivityService.test.ts +++ b/apps/api/src/services/__tests__/ActivityService.test.ts @@ -1,8 +1,18 @@ -import {beforeEach, describe, expect, it} from 'vitest'; +import {beforeEach, describe, expect, it, vi} from 'vitest'; +import {EmailSourceType, EmailStatus, TrackingMode} from '@plunk/db'; import {ActivityType} from '@plunk/types'; +import {redis} from '../../database/redis'; import {ActivityService} from '../ActivityService'; +import {Keys} from '../keys'; import {factories, getPrismaClient} from '../../../../../test/helpers'; +// Stats follow the no-tracking configuration set toggle; pin it on so they do not depend +// on the environment the suite runs in +vi.mock('../../app/constants.js', async importOriginal => ({ + ...(await importOriginal()), + TRACKING_TOGGLE_ENABLED: true, +})); + /** * Subscription changes are stored as reserved-name events (`contact.subscribed`, * `contact.unsubscribed`) rather than in their own table, so the feed has to @@ -263,3 +273,100 @@ describe('ActivityService - workflow activity', () => { expect(seen).toEqual(started.map(execution => `${execution.id}_started`)); }); }); + +/** + * The dashboard measures its open rate the way analytics does: against emails that went + * out with tracking, under the project's current tracking mode. + */ +describe('ActivityService - stats', () => { + const prisma = getPrismaClient(); + + const setUp = async (tracking: TrackingMode) => { + const project = await factories.createProject({tracking}); + const contact = await factories.createContact({projectId: project.id}); + const send = (sourceType: EmailSourceType, options: {openedAt?: Date} = {}) => + factories.createEmail({ + projectId: project.id, + contactId: contact.id, + sourceType, + status: EmailStatus.SENT, + sentAt: new Date(), + ...options, + }); + return {project, contact, send}; + }; + + it('measures the open rate against tracked emails only when transactional mail is not tracked', async () => { + const {project, send} = await setUp(TrackingMode.MARKETING_ONLY); + await send(EmailSourceType.TRANSACTIONAL); + await send(EmailSourceType.CAMPAIGN, {openedAt: new Date()}); + + const stats = await ActivityService.getStats(project.id); + + expect(stats).toMatchObject({totalEmailsTracked: 1, totalEmailsOpened: 1, openRate: 100}); + }); + + it('leaves inbound, simulated and unsent emails out of the open rate', async () => { + const {project, contact, send} = await setUp(TrackingMode.ENABLED); + await send(EmailSourceType.CAMPAIGN, {openedAt: new Date()}); + const simulated = await send(EmailSourceType.CAMPAIGN); + await prisma.email.update({where: {id: simulated.id}, data: {simulated: true}}); + await factories.createEmail({ + projectId: project.id, + contactId: contact.id, + sourceType: EmailSourceType.INBOUND, + status: EmailStatus.RECEIVED, + }); + await factories.createEmail({ + projectId: project.id, + contactId: contact.id, + sourceType: EmailSourceType.WORKFLOW, + status: EmailStatus.FAILED, + }); + + const stats = await ActivityService.getStats(project.id); + + expect(stats.openRate).toBe(100); + }); + + it('counts only emails that went out as emails sent', async () => { + const {project, contact, send} = await setUp(TrackingMode.ENABLED); + await send(EmailSourceType.CAMPAIGN); + const simulated = await send(EmailSourceType.CAMPAIGN); + await prisma.email.update({where: {id: simulated.id}, data: {simulated: true}}); + for (const [sourceType, status] of [ + [EmailSourceType.INBOUND, EmailStatus.RECEIVED], + [EmailSourceType.WORKFLOW, EmailStatus.FAILED], + [EmailSourceType.TRANSACTIONAL, EmailStatus.PENDING], + ] as const) { + await factories.createEmail({projectId: project.id, contactId: contact.id, sourceType, status}); + } + + const stats = await ActivityService.getStats(project.id); + + expect(stats.totalEmailsSent).toBe(1); + }); + + it('follows a change of tracking mode instead of serving stats cached under the old one', async () => { + const {project, send} = await setUp(TrackingMode.ENABLED); + await send(EmailSourceType.TRANSACTIONAL); + await send(EmailSourceType.CAMPAIGN, {openedAt: new Date()}); + + expect((await ActivityService.getStats(project.id)).openRate).toBe(50); + + await prisma.project.update({where: {id: project.id}, data: {tracking: TrackingMode.MARKETING_ONLY}}); + await redis.del(Keys.Project.id(project.id)); + + expect((await ActivityService.getStats(project.id)).openRate).toBe(100); + }); + + it('measures nothing when tracking is disabled', async () => { + const {project, send} = await setUp(TrackingMode.DISABLED); + await send(EmailSourceType.CAMPAIGN, {openedAt: new Date()}); + await send(EmailSourceType.TRANSACTIONAL); + + const stats = await ActivityService.getStats(project.id); + + expect(stats).toMatchObject({totalEmailsTracked: 0, totalEmailsOpened: 0, openRate: 0, clickRate: 0}); + }); +}); diff --git a/apps/api/src/services/__tests__/AnalyticsService.test.ts b/apps/api/src/services/__tests__/AnalyticsService.test.ts new file mode 100644 index 000000000..7b2bc03cc --- /dev/null +++ b/apps/api/src/services/__tests__/AnalyticsService.test.ts @@ -0,0 +1,133 @@ +import {CampaignStatus, EmailSourceType, EmailStatus, TemplateType} from '@plunk/db'; +import {beforeEach, describe, expect, it} from 'vitest'; + +import {type AnalyticsQuery, AnalyticsService} from '../AnalyticsService'; +import {factories, getPrismaClient} from '../../../../../test/helpers'; + +// The streams each tracking mode sends with open and click tracking +const ENABLED = [EmailSourceType.TRANSACTIONAL, EmailSourceType.CAMPAIGN, EmailSourceType.WORKFLOW]; +const MARKETING_ONLY = [EmailSourceType.CAMPAIGN, EmailSourceType.WORKFLOW]; +const DISABLED: EmailSourceType[] = []; + +/** + * Opens and clicks can only be recorded on emails sent with tracking, so their rates are + * measured against those emails alone. Counting untracked transactional mail in the + * denominator diluted the rate of every project tracking marketing mail only. + */ +describe('AnalyticsService - open and click rates against tracked emails', () => { + const prisma = getPrismaClient(); + let projectId: string; + let contactId: string; + + beforeEach(async () => { + const project = await factories.createProject(); + projectId = project.id; + const contact = await factories.createContact({projectId}); + contactId = contact.id; + }); + + const send = (sourceType: EmailSourceType, options: {openedAt?: Date; clickedAt?: Date} = {}) => + factories.createEmail({projectId, contactId, sourceType, status: EmailStatus.SENT, sentAt: new Date(), ...options}); + + const query = (trackedStreams: EmailSourceType[]): AnalyticsQuery => ({ + projectId, + from: new Date(Date.now() - 24 * 60 * 60 * 1000), + to: new Date(Date.now() + 60 * 1000), + tz: 'UTC', + stream: 'ALL', + trackedStreams, + }); + + it('measures opens against tracked emails only when transactional mail is not tracked', async () => { + await send(EmailSourceType.TRANSACTIONAL); + await send(EmailSourceType.CAMPAIGN, {openedAt: new Date()}); + + const overview = await AnalyticsService.getOverview(query(MARKETING_ONLY)); + + expect(overview.current).toMatchObject({sent: 2, tracked: 1, opened: 1, openRate: 100}); + expect(overview.streams.find(row => row.stream === 'TRANSACTIONAL')).toMatchObject({sent: 1, tracked: 0}); + }); + + it('keeps the rates of a project that tracks everything as they were', async () => { + await send(EmailSourceType.TRANSACTIONAL); + await send(EmailSourceType.CAMPAIGN, {openedAt: new Date(), clickedAt: new Date()}); + + const {current} = await AnalyticsService.getOverview(query(ENABLED)); + + expect(current.sent).toBe(2); + expect(current.opened).toBe(1); + expect(current.openRate).toBe(50); + expect(current.clickRate).toBe(50); + }); + + it('measures nothing when tracking is disabled', async () => { + await send(EmailSourceType.CAMPAIGN, {openedAt: new Date()}); + await send(EmailSourceType.TRANSACTIONAL); + + const {current} = await AnalyticsService.getOverview(query(DISABLED)); + + expect(current).toMatchObject({sent: 2, tracked: 0, opened: 0, clicked: 0, openRate: 0, clickRate: 0}); + }); + + it('leaves out opens of emails the current mode does not track, so no rate passes 100%', async () => { + // Opened while the project still tracked transactional mail + await send(EmailSourceType.TRANSACTIONAL, {openedAt: new Date()}); + await send(EmailSourceType.CAMPAIGN, {openedAt: new Date()}); + + const {current} = await AnalyticsService.getOverview(query(MARKETING_ONLY)); + + expect(current).toMatchObject({tracked: 1, opened: 1, openRate: 100}); + }); + + it('leaves emails sent to the SES mailbox simulator out of every count', async () => { + const simulated = await send(EmailSourceType.CAMPAIGN); + await prisma.email.update({where: {id: simulated.id}, data: {simulated: true}}); + await send(EmailSourceType.CAMPAIGN, {openedAt: new Date()}); + + const {current} = await AnalyticsService.getOverview(query(ENABLED)); + + expect(current.sent).toBe(1); + expect(current.openRate).toBe(100); + }); + + it('carries the tracked count on every point of the timeseries', async () => { + await send(EmailSourceType.TRANSACTIONAL); + await send(EmailSourceType.CAMPAIGN, {openedAt: new Date()}); + + const series = await AnalyticsService.getTimeseries(query(MARKETING_ONLY)); + const total = (key: 'sent' | 'tracked' | 'opened') => series.current.reduce((sum, point) => sum + point[key], 0); + + expect({sent: total('sent'), tracked: total('tracked'), opened: total('opened')}).toEqual({ + sent: 2, + tracked: 1, + opened: 1, + }); + }); + + it('measures mailbox providers against tracked emails', async () => { + await send(EmailSourceType.TRANSACTIONAL); + await send(EmailSourceType.CAMPAIGN, {openedAt: new Date()}); + + const {providers} = await AnalyticsService.getDeliverability(query(MARKETING_ONLY)); + + expect(providers).toHaveLength(1); + expect(providers[0]).toMatchObject({sent: 2, tracked: 1, openRate: 100}); + }); + + it('marks campaigns sent as transactional as untracked when only marketing mail is tracked', async () => { + const started = async (type: TemplateType) => { + const campaign = await factories.createCampaign({projectId, type}); + return prisma.campaign.update({ + where: {id: campaign.id}, + data: {status: CampaignStatus.SENT, sentAt: new Date(), sentCount: 10, openedCount: 4}, + }); + }; + const transactional = await started(TemplateType.TRANSACTIONAL); + const marketing = await started(TemplateType.MARKETING); + + const {rows} = await AnalyticsService.getLeaderboard(query(MARKETING_ONLY), 'campaigns'); + + expect(rows.find(row => row.id === transactional.id)).toMatchObject({sent: 10, tracked: 0, opened: 0}); + expect(rows.find(row => row.id === marketing.id)).toMatchObject({sent: 10, tracked: 10, openRate: 40}); + }); +}); diff --git a/apps/api/src/services/__tests__/EmailService.test.ts b/apps/api/src/services/__tests__/EmailService.test.ts index bf7eaf6ad..149ea47ae 100644 --- a/apps/api/src/services/__tests__/EmailService.test.ts +++ b/apps/api/src/services/__tests__/EmailService.test.ts @@ -1,7 +1,8 @@ import {beforeEach, describe, expect, it, vi, type Mock} from 'vitest'; -import {EmailSourceType, EmailStatus, TemplateType} from '@plunk/db'; +import {EmailSourceType, EmailStatus, TemplateType, TrackingMode} from '@plunk/db'; import {ActionSchemas} from '@plunk/shared'; import {EmailService} from '../EmailService'; +import {ProjectService} from '../ProjectService'; import {sendRawEmail} from '../SESService'; import {factories} from '../../../../../test/helpers'; @@ -1042,3 +1043,58 @@ describe('Template rendering — hostile contact data keys (no DB)', () => { expect(EmailService.format({subject: 'Hi {{missing}}', body: 'x', data: {}}).subject).toBe('Hi '); }); }); + +/** + * Stats measure opens and clicks only against emails that could record them, so the + * streams a mode tracks have to match what the send path does (shouldTrackEmail, plus + * SESService sending everything tracked without a no-tracking configuration set). + */ +describe('EmailService.trackedSourceTypes', () => { + const {TRANSACTIONAL, CAMPAIGN, WORKFLOW} = EmailSourceType; + + it('tracks every outbound stream when tracking is enabled', () => { + expect(EmailService.trackedSourceTypes(TrackingMode.ENABLED, true)).toEqual([TRANSACTIONAL, CAMPAIGN, WORKFLOW]); + }); + + it('tracks campaigns and workflows only in marketing-only mode', () => { + expect(EmailService.trackedSourceTypes(TrackingMode.MARKETING_ONLY, true)).toEqual([CAMPAIGN, WORKFLOW]); + }); + + it('tracks nothing when tracking is disabled', () => { + expect(EmailService.trackedSourceTypes(TrackingMode.DISABLED, true)).toEqual([]); + }); + + it('tracks everything whatever the mode without a no-tracking configuration set', () => { + for (const mode of [TrackingMode.ENABLED, TrackingMode.MARKETING_ONLY, TrackingMode.DISABLED]) { + expect(EmailService.trackedSourceTypes(mode, false)).toEqual([TRANSACTIONAL, CAMPAIGN, WORKFLOW]); + } + }); +}); + +describe('EmailService.trackedStreams', () => { + it("reads the project's tracking mode", async () => { + const project = await factories.createProject({tracking: TrackingMode.MARKETING_ONLY}); + + expect(await EmailService.trackedStreams(project.id)).toEqual([EmailSourceType.CAMPAIGN, EmailSourceType.WORKFLOW]); + }); + + it('treats a project it cannot find as tracking everything', async () => { + expect(await EmailService.trackedStreams('00000000-0000-0000-0000-000000000000')).toEqual([ + EmailSourceType.TRANSACTIONAL, + EmailSourceType.CAMPAIGN, + EmailSourceType.WORKFLOW, + ]); + }); + + it('still answers when the project cannot be read, so stats keep loading', async () => { + const project = await factories.createProject({tracking: TrackingMode.MARKETING_ONLY}); + const read = vi.spyOn(ProjectService, 'id').mockRejectedValueOnce(new Error('Redis unavailable')); + + expect(await EmailService.trackedStreams(project.id)).toEqual([ + EmailSourceType.TRANSACTIONAL, + EmailSourceType.CAMPAIGN, + EmailSourceType.WORKFLOW, + ]); + read.mockRestore(); + }); +}); diff --git a/apps/api/src/services/keys.ts b/apps/api/src/services/keys.ts index a985911b2..ab312c53c 100644 --- a/apps/api/src/services/keys.ts +++ b/apps/api/src/services/keys.ts @@ -59,8 +59,8 @@ export const Keys = { }, }, Activity: { - stats(projectId: string, startTime: number | string, endTime: number | string): string { - return `activity:stats:${projectId}:${startTime}:${endTime}`; + stats(projectId: string, startTime: number | string, endTime: number | string, trackedStreams: string): string { + return `activity:stats:${projectId}:${startTime}:${endTime}:${trackedStreams}`; }, recentCount(projectId: string, minutes: number): string { return `activity:recent-count:${projectId}:${minutes}`; diff --git a/apps/web/src/components/analytics/DeliverabilityTab.tsx b/apps/web/src/components/analytics/DeliverabilityTab.tsx index f1158c477..a3fbfd7a0 100644 --- a/apps/web/src/components/analytics/DeliverabilityTab.tsx +++ b/apps/web/src/components/analytics/DeliverabilityTab.tsx @@ -13,6 +13,7 @@ import {type Column, RateTable} from './RateTable'; const bounce = metric('bounceRate'); const complaint = metric('complaintRate'); +const open = metric('openRate'); export function DeliverabilityTab({filters}: {filters: AnalyticsFilters}) { const overview = useAnalyticsData('overview', filters); @@ -110,7 +111,12 @@ function Providers({data, error, retry}: {data?: AnalyticsDeliverability; error: }, {key: 'sent', label: 'Sent', render: row => formatCount(row.sent), sortValue: row => row.sent}, {key: 'deliveryRate', label: 'Delivered', render: row => formatRate(row.deliveryRate), sortValue: row => row.deliveryRate}, - {key: 'openRate', label: 'Opened', render: row => formatRate(row.openRate), sortValue: row => row.openRate}, + { + key: 'openRate', + label: 'Opened', + render: row => (open.volume(row) > 0 ? formatRate(row.openRate) : '—'), + sortValue: row => row.openRate, + }, { key: 'bounceRate', label: 'Bounced', diff --git a/apps/web/src/components/analytics/EngagementTab.tsx b/apps/web/src/components/analytics/EngagementTab.tsx index 7441455cc..afe0be33f 100644 --- a/apps/web/src/components/analytics/EngagementTab.tsx +++ b/apps/web/src/components/analytics/EngagementTab.tsx @@ -54,9 +54,9 @@ function Leaderboard({filters}: {filters: AnalyticsFilters}) { const rate = (key: MetricKey, label: string): Column => ({ key, label, - render: row => (row.sent > 0 ? formatRate(row[key]) : '—'), + render: row => (metric(key).volume(row) > 0 ? formatRate(row[key]) : '—'), sortValue: row => row[key], - tone: row => thresholdTone(metric(key), row[key], row.sent), + tone: row => thresholdTone(metric(key), row[key], metric(key).volume(row)), }); const columns: Column[] = [ diff --git a/apps/web/src/components/analytics/OverviewTab.tsx b/apps/web/src/components/analytics/OverviewTab.tsx index 20104a8b2..67cbb1605 100644 --- a/apps/web/src/components/analytics/OverviewTab.tsx +++ b/apps/web/src/components/analytics/OverviewTab.tsx @@ -32,13 +32,15 @@ export function OverviewTab({filters}: {filters: AnalyticsFilters}) { const current = overview.data?.current; const previous = overview.data?.previous; const empty = current?.sent === 0; + // Emails went out, but none with the tracking the selected figure is built on + const untracked = current !== undefined && !empty && def.volume(current) === 0; // Context that changes how the numbers should be read, shown only when it applies const notes: string[] = []; if (filters.range === 'today') { notes.push('Emails sent today are still being opened and clicked, so the rates above rise through the day.'); } - if (selected === 'openRate' || selected === 'clickToOpenRate') { + if ((selected === 'openRate' || selected === 'clickToOpenRate') && !untracked) { notes.push( 'Apple Mail and some corporate filters open every message on delivery, so open rates read high. Clicks are the more dependable signal of attention.', ); @@ -56,9 +58,10 @@ export function OverviewTab({filters}: {filters: AnalyticsFilters}) { {METRICS.map(m => { const active = m.key === selected; const value = current?.[m.key]; + const measured = current !== undefined && m.volume(current) > 0; const delta = current && previous && value !== undefined - ? computeDelta(m, value, previous[m.key], previous.sent) + ? computeDelta(m, value, previous[m.key], m.volume(previous)) : null; return (