// AK-P14a · P14 Email — open/click tracking service. // // Records pixel opens and link clicks for an OutboundEmail. The client IP is // stored ONLY as a truncated sha256 hash (never the raw address) — matching the // marketing-lead `lastIpHash` convention. `firstOpen` flags the first open of a // given email so the campaign KPI ("unique opens") can be derived without a // second pass. // // This is the tracking INFRASTRUCTURE only; embedding the pixel / rewriting the // links at send time belongs to the marketing send path (AK-P14b). The client is // injectable so the unit tests run against an in-memory fake. import { createHash } from "node:crypto"; import { getDbClient } from "./client.server.js"; /** Truncated sha256 of the client IP — never the raw address. Null when unknown. */ export function anonymizeTrackingIp(ip: string | null | undefined): string | null { if (!ip || !ip.trim()) { return null; } return createHash("sha256").update(ip.trim()).digest("hex").slice(0, 32); } /** * Validate a click-through target before redirecting. Only absolute http(s) * URLs are allowed — prevents the tracking endpoint from becoming an * open-redirect to `javascript:` / `data:` / relative paths. */ export function safeRedirectTarget(raw: string | null | undefined): string | null { if (!raw) { return null; } let parsed: URL; try { parsed = new URL(raw); } catch { return null; } if (parsed.protocol !== "http:" && parsed.protocol !== "https:") { return null; } return parsed.toString(); } type OutboundEmailRef = { id: string; tenantId: string | null }; export type EmailTrackingClient = { outboundEmail: { findUnique(args: { where: { id: string }; select: { id: true; tenantId: true } }): Promise; }; outboundEmailOpen: { findFirst(args: { where: { outboundEmailId: string } }): Promise<{ id: string } | null>; create(args: { data: { outboundEmailId: string; firstOpen: boolean; ipHash: string | null } }): Promise<{ id: string }>; }; outboundEmailClick: { create(args: { data: { outboundEmailId: string; link: string; ipHash: string | null } }): Promise<{ id: string }>; }; }; export type RecordEmailOpenResult = { status: "recorded"; firstOpen: boolean } | { status: "unknown_email" }; export type RecordEmailClickResult = { status: "recorded" } | { status: "unknown_email" }; /** Record a pixel open. The first open of an email is flagged `firstOpen`. */ export async function recordEmailOpen( input: { tenantId: string; outboundEmailId: string; ipHash: string | null }, client: EmailTrackingClient = getDbClient() as unknown as EmailTrackingClient, ): Promise { const email = await client.outboundEmail.findUnique({ where: { id: input.outboundEmailId }, select: { id: true, tenantId: true } }); if (!email || email.tenantId !== input.tenantId) { return { status: "unknown_email" }; } const prior = await client.outboundEmailOpen.findFirst({ where: { outboundEmailId: input.outboundEmailId } }); const firstOpen = prior === null; await client.outboundEmailOpen.create({ data: { outboundEmailId: input.outboundEmailId, firstOpen, ipHash: input.ipHash } }); return { status: "recorded", firstOpen }; } /** Record a link click (already-validated target). */ export async function recordEmailClick( input: { tenantId: string; outboundEmailId: string; link: string; ipHash: string | null }, client: EmailTrackingClient = getDbClient() as unknown as EmailTrackingClient, ): Promise { const email = await client.outboundEmail.findUnique({ where: { id: input.outboundEmailId }, select: { id: true, tenantId: true } }); if (!email || email.tenantId !== input.tenantId) { return { status: "unknown_email" }; } await client.outboundEmailClick.create({ data: { outboundEmailId: input.outboundEmailId, link: input.link, ipHash: input.ipHash } }); return { status: "recorded" }; }