91 lines
3.9 KiB
TypeScript
91 lines
3.9 KiB
TypeScript
// 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<OutboundEmailRef | null>;
|
|
};
|
|
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<RecordEmailOpenResult> {
|
|
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<RecordEmailClickResult> {
|
|
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" };
|
|
}
|