@hogsend/engine 0.22.0 → 0.23.1

package/src/routes/tracking/click.ts

@@ -38,6 +38,8 @@ export const clickRouter = new OpenAPIHono<AppEnv>().openapi(
         id: trackedLinks.id,
         originalUrl: trackedLinks.originalUrl,
         emailSendId: trackedLinks.emailSendId,
+        distinctId: trackedLinks.distinctId,
+        source: trackedLinks.source,
         event: trackedLinks.event,
         eventProperties: trackedLinks.eventProperties,
       })
@@ -56,10 +58,17 @@ export const clickRouter = new OpenAPIHono<AppEnv>().openapi(
       null;
     const userAgent = c.req.header("user-agent") ?? null;
 
+    // The linkClicks insert + clickCount increment stay UNCONDITIONAL — every
+    // tracked link counts clicks, email or not.
+    //
     // First-touch state UPDATE: the `WHERE clickedAt IS NULL` sets `clickedAt`
     // exactly once (the first click), which is the row-level state we keep. The
     // outbound emit is NO LONGER gated on this — every destination must receive
-    // EVERY click (owner decision 1), so the emit below fires per-hit.
+    // EVERY click (owner decision 1), so the emit below fires per-hit. The
+    // emailSends update is GATED on `emailSendId != null` (MF-6): a non-email
+    // link has no send row to mark. This was previously safe-by-accident
+    // (`WHERE id = NULL` matches nothing) — the gate makes it explicit.
+    const emailSendId = link.emailSendId;
     await Promise.all([
       db.insert(linkClicks).values({
         trackedLinkId: link.id,
@@ -73,18 +82,22 @@ export const clickRouter = new OpenAPIHono<AppEnv>().openapi(
           updatedAt: new Date(),
         })
         .where(eq(trackedLinks.id, link.id)),
-      db
-        .update(emailSends)
-        .set({
-          clickedAt: new Date(),
-          updatedAt: new Date(),
-        })
-        .where(
-          and(
-            eq(emailSends.id, link.emailSendId),
-            isNull(emailSends.clickedAt),
-          ),
-        ),
+      ...(emailSendId
+        ? [
+            db
+              .update(emailSends)
+              .set({
+                clickedAt: new Date(),
+                updatedAt: new Date(),
+              })
+              .where(
+                and(
+                  eq(emailSends.id, emailSendId),
+                  isNull(emailSends.clickedAt),
+                ),
+              ),
+          ]
+        : []),
     ]);
 
     const { hatchet, registry, logger } = c.get("container");
@@ -93,8 +106,11 @@ export const clickRouter = new OpenAPIHono<AppEnv>().openapi(
     // deferred past the scanner-burst window (a Hatchet task) so the gate can
     // see the WHOLE burst — an inline check could never suppress a scanner's
     // first click. The task claims the send's answer slot (first answer wins)
-    // and emits the consumer event + email.action outbound.
-    if (link.event) {
+    // and emits the consumer event + email.action outbound. GATED on
+    // `emailSendId != null` (MF-6): the confirm task is email-semantic (it
+    // claims a send's answer slot + emits `email.action`), so a non-email
+    // semantic link would have no send to confirm against.
+    if (link.event && emailSendId) {
       void confirmSemanticClickTask
         .runNoWait({
           trackedLinkId: link.id,
@@ -110,27 +126,48 @@ export const clickRouter = new OpenAPIHono<AppEnv>().openapi(
     }
 
     // Cross-device identity stitch (opt-in): append a short-lived signed
-    // `hs_t` token to the destination so the landing site can identify the
-    // session. This is the ONE path that needs the send context BEFORE the
-    // redirect — the awaited resolve is shared with the async chain below so
-    // the read still happens once.
+    // `hs_t` token to the destination so the landing site can fold its own anon
+    // session INTO the subject at `/v1/t/identify`. Two mint sources by link
+    // type (§6.5): a stitch-bearing NON-email link mints from its own
+    // `distinct_id` (`src: "<source>:<id>"`); an EMAIL link mints from the
+    // resolved send context; a BROADCAST link (no `distinct_id`, no send) mints
+    // nothing. The token is minted at CLICK time only — never stored on the
+    // shareable `/v1/t/c/:id` artifact (§6.3). The awaited send resolve is
+    // shared with the async chain below so the read still happens once.
     let redirectUrl = link.originalUrl;
     let preResolved: Awaited<
       ReturnType<typeof resolveEmailSendContext>
     > | null = null;
     let preResolvedSet = false;
     if (env.TRACKING_IDENTITY_TOKEN) {
-      preResolved = await resolveEmailSendContext(db, link.emailSendId);
-      preResolvedSet = true;
-      if (preResolved?.userId) {
+      let tokenDistinctId: string | null = null;
+      let tokenSrc: string | null = null;
+      if (link.distinctId) {
+        // Stitch-bearing non-email link: the subject is the link's own
+        // `distinct_id` (canonical key). No send resolve needed.
+        tokenDistinctId = link.distinctId;
+        tokenSrc = `${link.source ?? "link"}:${link.id}`;
+      } else if (emailSendId) {
+        // Email link: resolve the recipient's canonical key from the send row.
+        preResolved = await resolveEmailSendContext(db, emailSendId);
+        preResolvedSet = true;
+        if (preResolved?.userId) {
+          tokenDistinctId = preResolved.userId;
+          tokenSrc = `email:${emailSendId}`;
+        }
+      }
+      // else: broadcast link (no distinctId, no send) — mint nothing.
+
+      if (tokenDistinctId && tokenSrc) {
         try {
           const url = new URL(link.originalUrl);
           url.searchParams.set(
             "hs_t",
             generateIdentityToken({
               secret: env.BETTER_AUTH_SECRET,
-              distinctId: preResolved.userId,
-              emailSendId: link.emailSendId,
+              distinctId: tokenDistinctId,
+              src: tokenSrc,
+              emailSendId: emailSendId ?? undefined,
             }),
           );
           redirectUrl = url.toString();
@@ -141,58 +178,80 @@ export const clickRouter = new OpenAPIHono<AppEnv>().openapi(
       }
     }
 
-    // Resolve the send context ONCE (off the response path) and feed both the
-    // re-ingest and the PER-HIT outbound emit — avoiding a duplicate
-    // `resolveEmailSendContext` read on the click hot path. NO `dedupeKey`: a
-    // NULL dedupe key is distinct in Postgres, so every click creates a fresh
-    // delivery to every subscribed destination (per-hit, not first-touch).
-    const emailSendId = link.emailSendId;
-    void (
-      preResolvedSet
-        ? Promise.resolve(preResolved)
-        : resolveEmailSendContext(db, emailSendId)
-    )
-      .then(async (ctx) => {
-        await pushTrackingEvent({
-          db,
-          hatchet,
-          registry,
-          logger,
-          event: EMAIL_LINK_CLICKED,
-          emailSendId,
-          properties: { linkUrl: link.originalUrl, linkId: link.id },
-          resolvedContext: ctx,
-        }).catch((err) => {
-          logger.warn("Failed to push click tracking event", {
-            linkId: link.id,
-            error: err instanceof Error ? err.message : String(err),
-          });
-        });
-
-        // Only emit when the send-context resolved. A missing emailSends row
-        // (orphaned tracked link / deleted send) has no userId or recipient to
-        // attribute, and a keyed destination (PostHog) would otherwise receive
-        // an empty distinct_id. A normal click always resolves a non-null userId.
-        if (ctx) {
-          await emitOutbound({
+    // PER-HIT outbound emit, off the response path. EMAIL links re-ingest the
+    // first-party `email.link_clicked` event (journey routing + userEvents) and
+    // emit `email.clicked`; NON-email links emit `link.clicked` instead — never
+    // a malformed `email.clicked` (MF-missing #3). NO `dedupeKey`: a NULL dedupe
+    // key is distinct in Postgres, so every click creates a fresh delivery to
+    // every subscribed destination (per-hit, not first-touch).
+    if (emailSendId) {
+      void (
+        preResolvedSet
+          ? Promise.resolve(preResolved)
+          : resolveEmailSendContext(db, emailSendId)
+      )
+        .then(async (ctx) => {
+          await pushTrackingEvent({
             db,
             hatchet,
+            registry,
             logger,
-            event: "email.clicked",
-            payload: {
-              emailSendId,
-              messageId: ctx.messageId ?? null,
-              templateKey: ctx.templateKey ?? null,
-              userId: ctx.userId ?? null,
-              to: ctx.to ?? ctx.userEmail ?? "",
-              at: new Date().toISOString(),
-              linkUrl: link.originalUrl,
+            event: EMAIL_LINK_CLICKED,
+            emailSendId,
+            properties: { linkUrl: link.originalUrl, linkId: link.id },
+            resolvedContext: ctx,
+          }).catch((err) => {
+            logger.warn("Failed to push click tracking event", {
               linkId: link.id,
-            },
+              error: err instanceof Error ? err.message : String(err),
+            });
           });
-        }
-      })
-      .catch(logger.warn);
+
+          // Only emit when the send-context resolved. A missing emailSends row
+          // (orphaned tracked link / deleted send) has no userId or recipient to
+          // attribute, and a keyed destination (PostHog) would otherwise receive
+          // an empty distinct_id. A normal click always resolves a non-null userId.
+          if (ctx) {
+            await emitOutbound({
+              db,
+              hatchet,
+              logger,
+              event: "email.clicked",
+              payload: {
+                emailSendId,
+                messageId: ctx.messageId ?? null,
+                templateKey: ctx.templateKey ?? null,
+                userId: ctx.userId ?? null,
+                to: ctx.to ?? ctx.userEmail ?? "",
+                at: new Date().toISOString(),
+                linkUrl: link.originalUrl,
+                linkId: link.id,
+              },
+            });
+          }
+        })
+        .catch(logger.warn);
+    } else {
+      // Non-email tracked link: emit the catalogued `link.clicked` (NOT
+      // `email.clicked`). `userId` is the link's stitch subject when
+      // identity-bearing, else null for a broadcast link. No re-ingest — the
+      // first-party `email.link_clicked` bus event is email-semantic.
+      void emitOutbound({
+        db,
+        hatchet,
+        logger,
+        event: "link.clicked",
+        payload: {
+          linkId: link.id,
+          source: link.source ?? null,
+          userId: link.distinctId ?? null,
+          emailSendId: null,
+          messageId: null,
+          linkUrl: link.originalUrl,
+          at: new Date().toISOString(),
+        },
+      }).catch(logger.warn);
+    }
 
     return c.redirect(redirectUrl, 302);
   },

package/src/routes/tracking/identify.ts

@@ -6,26 +6,40 @@ import {
 } from "../../lib/identity-token.js";
 
 /**
- * Exchange a redirect identity token (`hs_t`) for the distinct id. Called by
- * the LANDING SITE's frontend (CORS is open app-wide) after the user arrives
- * from a tracked email link; the site then calls `posthog.identify` (or its
- * analytics equivalent) with the result — ideally gated behind whatever
- * analytics consent the site already operates under.
+ * Exchange a redirect identity token (`hs_t`) for the distinct id, AND — when
+ * the caller supplies its own browser anon id (`currentDistinctId`) and the
+ * active analytics provider can merge — fire a SERVER-SIDE `alias` folding the
+ * caller's own anon session INTO the token's canonical subject. Called by the
+ * LANDING SITE's frontend (CORS is open app-wide) after the user arrives from a
+ * tracked link.
  *
  * Possession of a fresh signed token IS the authorization (the same trust
  * model as unsubscribe links): tokens are signed with BETTER_AUTH_SECRET,
- * expire after an hour, and resolve to nothing but the distinct id + send id.
+ * expire after an hour, and resolve to nothing but the canonical key + src.
+ *
+ * ANTI-HIJACK (MF-4): the route NEVER passes `currentDistinctId` as the
+ * survivor and NEVER server-identifies it. A forwarded-token holder can, at
+ * worst, fold THEIR OWN anon session into the subject — never overwrite the
+ * subject, never become the subject, never name a victim's anon id (they don't
+ * know it). A scanner following the redirect runs no posthog-js, so it supplies
+ * no `currentDistinctId` and the merge no-ops — the exchange is inert for
+ * headless prefetch.
  */
 const identifyRoute = createRoute({
   method: "post",
   path: "/identify",
   tags: ["Tracking"],
-  summary: "Exchange a redirect identity token for the distinct id",
+  summary: "Exchange a redirect identity token + optionally alias the caller",
   request: {
     body: {
       content: {
         "application/json": {
-          schema: z.object({ token: z.string().min(1).max(2048) }),
+          schema: z.object({
+            token: z.string().min(1).max(2048),
+            // The caller's OWN browser anon distinct id, to be folded INTO the
+            // token subject. Optional — absent = legacy resolve-only behaviour.
+            currentDistinctId: z.string().min(1).max(200).optional(),
+          }),
         },
       },
     },
@@ -35,8 +49,11 @@ const identifyRoute = createRoute({
       description: "Resolved identity",
       content: {
         "application/json": {
+          // ONE response schema across §6 (MF-5): `src` is the new field,
+          // `emailSendId` retained for the one-minor deprecation window.
           schema: z.object({
             distinctId: z.string(),
+            src: z.string(),
             emailSendId: z.string().optional(),
           }),
         },
@@ -49,23 +66,53 @@ const identifyRoute = createRoute({
 export const identifyRouter = new OpenAPIHono<AppEnv>().openapi(
   identifyRoute,
   async (c) => {
-    const { token } = c.req.valid("json");
-    const { env } = c.get("container");
+    const { token, currentDistinctId } = c.req.valid("json");
+    const { env, analytics, logger } = c.get("container");
 
+    let payload: ReturnType<typeof validateIdentityToken>;
     try {
-      const payload = validateIdentityToken({
+      payload = validateIdentityToken({
         token,
         secret: env.BETTER_AUTH_SECRET,
       });
-      return c.json(
-        { distinctId: payload.distinctId, emailSendId: payload.emailSendId },
-        200,
-      );
     } catch (err) {
       if (err instanceof InvalidIdentityTokenError) {
         return c.body(null, 400);
       }
       throw err;
     }
+
+    // MF-5 — fire the alias FIRE-AND-FORGET (never await on the response path)
+    // and respond synchronously. The token-proven canonical key is the survivor;
+    // the caller's own session is the absorbed (anonymous) side. A provider
+    // without `identityMerge` (or no provider) skips the merge cleanly — the
+    // client falls back to its existing best-effort `posthog.identify`.
+    if (
+      currentDistinctId &&
+      analytics?.capabilities.identityMerge &&
+      analytics.mergeIdentities &&
+      currentDistinctId !== payload.distinctId
+    ) {
+      try {
+        analytics.mergeIdentities({
+          distinctId: payload.distinctId,
+          alias: currentDistinctId,
+        });
+      } catch (err) {
+        // Best-effort — a provider error must never fail the exchange.
+        logger.warn("identify: mergeIdentities failed", {
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+
+    return c.json(
+      {
+        distinctId: payload.distinctId,
+        src: payload.src,
+        emailSendId: payload.emailSendId,
+      },
+      200,
+    );
   },
 );