@hogsend/engine 0.13.2 → 0.16.0

package/src/routes/tracking/click.ts

@@ -2,12 +2,14 @@ import { emailSends, linkClicks, trackedLinks } from "@hogsend/db";
 import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
 import { and, eq, isNull, sql } from "drizzle-orm";
 import type { AppEnv } from "../../app.js";
+import { generateIdentityToken } from "../../lib/identity-token.js";
 import { emitOutbound } from "../../lib/outbound.js";
 import { EMAIL_LINK_CLICKED } from "../../lib/tracking-event-names.js";
 import {
   pushTrackingEvent,
   resolveEmailSendContext,
 } from "../../lib/tracking-events.js";
+import { confirmSemanticClickTask } from "../../workflows/confirm-semantic-click.js";
 
 const clickRoute = createRoute({
   method: "get",
@@ -36,6 +38,8 @@ export const clickRouter = new OpenAPIHono<AppEnv>().openapi(
         id: trackedLinks.id,
         originalUrl: trackedLinks.originalUrl,
         emailSendId: trackedLinks.emailSendId,
+        event: trackedLinks.event,
+        eventProperties: trackedLinks.eventProperties,
       })
       .from(trackedLinks)
       .where(eq(trackedLinks.id, id))
@@ -85,13 +89,69 @@ export const clickRouter = new OpenAPIHono<AppEnv>().openapi(
 
     const { hatchet, registry, logger } = c.get("container");
 
+    // SEMANTIC link: the click is a PROVISIONAL answer. Confirmation is
+    // 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) {
+      void confirmSemanticClickTask
+        .runNoWait({
+          trackedLinkId: link.id,
+          clickedAt: new Date().toISOString(),
+        })
+        .catch((err: unknown) => {
+          logger.warn("Failed to enqueue semantic click confirmation", {
+            linkId: link.id,
+            event: link.event,
+            error: err instanceof Error ? err.message : String(err),
+          });
+        });
+    }
+
+    // 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.
+    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) {
+        try {
+          const url = new URL(link.originalUrl);
+          url.searchParams.set(
+            "hs_t",
+            generateIdentityToken({
+              secret: env.BETTER_AUTH_SECRET,
+              distinctId: preResolved.userId,
+              emailSendId: link.emailSendId,
+            }),
+          );
+          redirectUrl = url.toString();
+        } catch {
+          // Unparseable destination — redirect untouched rather than break it.
+          redirectUrl = link.originalUrl;
+        }
+      }
+    }
+
     // 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 resolveEmailSendContext(db, emailSendId)
+    void (
+      preResolvedSet
+        ? Promise.resolve(preResolved)
+        : resolveEmailSendContext(db, emailSendId)
+    )
       .then(async (ctx) => {
         await pushTrackingEvent({
           db,
@@ -134,6 +194,6 @@ export const clickRouter = new OpenAPIHono<AppEnv>().openapi(
       })
       .catch(logger.warn);
 
-    return c.redirect(link.originalUrl, 302);
+    return c.redirect(redirectUrl, 302);
   },
 );

package/src/routes/tracking/identify.ts

@@ -0,0 +1,71 @@
+import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
+import type { AppEnv } from "../../app.js";
+import {
+  InvalidIdentityTokenError,
+  validateIdentityToken,
+} 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.
+ *
+ * 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.
+ */
+const identifyRoute = createRoute({
+  method: "post",
+  path: "/identify",
+  tags: ["Tracking"],
+  summary: "Exchange a redirect identity token for the distinct id",
+  request: {
+    body: {
+      content: {
+        "application/json": {
+          schema: z.object({ token: z.string().min(1).max(2048) }),
+        },
+      },
+    },
+  },
+  responses: {
+    200: {
+      description: "Resolved identity",
+      content: {
+        "application/json": {
+          schema: z.object({
+            distinctId: z.string(),
+            emailSendId: z.string().optional(),
+          }),
+        },
+      },
+    },
+    400: { description: "Invalid or expired token" },
+  },
+});
+
+export const identifyRouter = new OpenAPIHono<AppEnv>().openapi(
+  identifyRoute,
+  async (c) => {
+    const { token } = c.req.valid("json");
+    const { env } = c.get("container");
+
+    try {
+      const 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;
+    }
+  },
+);

package/src/routes/tracking/index.ts

@@ -1,9 +1,13 @@
 import { OpenAPIHono } from "@hono/zod-openapi";
 import type { AppEnv } from "../../app.js";
+import { answerRouter } from "./answer.js";
 import { clickRouter } from "./click.js";
+import { identifyRouter } from "./identify.js";
 import { openRouter } from "./open.js";
 
 export const trackingRouter = new OpenAPIHono<AppEnv>();
 
 trackingRouter.route("/", clickRouter);
 trackingRouter.route("/", openRouter);
+trackingRouter.route("/", answerRouter);
+trackingRouter.route("/", identifyRouter);

package/src/worker.ts

@@ -16,6 +16,7 @@ import {
 } from "./workflows/bucket-backfill.js";
 import { bucketReconcileTask } from "./workflows/bucket-reconcile.js";
 import { checkAlertsTask } from "./workflows/check-alerts.js";
+import { confirmSemanticClickTask } from "./workflows/confirm-semantic-click.js";
 import {
   deliverWebhookTask,
   reapDueWebhookDeliveriesTask,
@@ -81,6 +82,7 @@ export function createWorker(opts: CreateWorkerOptions): Worker {
     reapStuckCampaignsTask,
     deliverWebhookTask,
     reapDueWebhookDeliveriesTask,
+    confirmSemanticClickTask,
     checkAlertsTask,
     bucketReconcileTask,
     bucketBackfillTask,

package/src/workflows/confirm-semantic-click.ts

@@ -0,0 +1,37 @@
+import { getJourneyRegistrySingleton } from "../journeys/registry-singleton.js";
+import { getDb } from "../lib/db.js";
+import { hatchet } from "../lib/hatchet.js";
+import { createLogger } from "../lib/logger.js";
+import {
+  type ConfirmSemanticClickInput,
+  confirmSemanticClick,
+} from "../lib/semantic-click.js";
+
+/**
+ * Deferred confirmation of a semantic-link answer, enqueued per candidate
+ * click by the click route. The deferral (≈ the burst window, 30s) is the
+ * point: an inline gate can never suppress a scanner's FIRST click because
+ * the rest of the burst hasn't happened yet — this task judges the click with
+ * the whole window visible on both sides.
+ *
+ * Retries are safe: the claim is an idempotency-keyed `user_events` insert
+ * whose failed-publish path rolls back inside `ingestEvent`, the stamp is
+ * `IS NULL`-guarded, and the outbound emit carries a `dedupeKey`. Self-
+ * bootstraps deps from the process (cron-style; no request container).
+ */
+export const confirmSemanticClickTask = hatchet.task({
+  name: "confirm-semantic-click",
+  retries: 3,
+  executionTimeout: "90s",
+  fn: async (input: ConfirmSemanticClickInput) => {
+    return confirmSemanticClick(
+      {
+        db: getDb(),
+        hatchet,
+        registry: getJourneyRegistrySingleton(),
+        logger: createLogger(process.env.LOG_LEVEL ?? "info"),
+      },
+      input,
+    );
+  },
+});