Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/packages/db/src/email-tracking.server.ts
T

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" };
}