@hogsend/engine 0.13.2 → 0.16.0

package/src/lib/semantic-click.ts

@@ -0,0 +1,194 @@
+import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
+import type { JourneyRegistry } from "@hogsend/core/registry";
+import {
+  type Database,
+  linkClicks,
+  trackedLinks,
+  userEvents,
+} from "@hogsend/db";
+import { and, countDistinct, eq, gte, isNull, lte } from "drizzle-orm";
+import type { Logger } from "./logger.js";
+import { emitOutbound } from "./outbound.js";
+import {
+  pushTrackingEvent,
+  resolveEmailSendContext,
+} from "./tracking-events.js";
+
+/**
+ * Scanner-burst window: SafeLinks/Proofpoint-style scanners follow EVERY link
+ * in an email within seconds of delivery; humans don't. Confirmation of a
+ * semantic answer is DEFERRED until the window around the candidate click has
+ * fully elapsed, so the gate sees the WHOLE burst — including clicks that land
+ * AFTER the candidate. An inline check could never suppress a scanner's first
+ * click (the burst isn't visible yet); this one can.
+ */
+export const SEMANTIC_BURST_WINDOW_MS = 30_000;
+export const SEMANTIC_BURST_DISTINCT_LINKS = 3;
+
+// Type alias (NOT interface) so it picks up an implicit index signature and
+// satisfies Hatchet's JsonObject task-input constraint.
+export type ConfirmSemanticClickInput = {
+  trackedLinkId: string;
+  /** ISO instant of the candidate click. */
+  clickedAt: string;
+};
+
+export type ConfirmSemanticClickResult =
+  | { status: "confirmed"; event: string }
+  | { status: "suppressed"; distinctLinks: number }
+  /** Another link's answer claimed this send's slot first. */
+  | { status: "lost" }
+  | { status: "skipped"; reason: string };
+
+export interface ConfirmSemanticClickDeps {
+  db: Database;
+  hatchet: HatchetClient;
+  registry: JourneyRegistry;
+  logger: Logger;
+}
+
+/**
+ * Confirm (or suppress) one provisional semantic-link answer. Idempotent end
+ * to end, so the wrapping Hatchet task can retry safely:
+ *
+ *  1. Sleep out the remainder of the burst window past the candidate click.
+ *  2. Count DISTINCT links of the send clicked inside the window around the
+ *     candidate — at/over the threshold the whole burst is scanner traffic
+ *     and the answer is suppressed (the raw clicks stay recorded).
+ *  3. Claim the send's answer slot via `ingestEvent` with the
+ *     `sem:<emailSendId>:<event>` idempotency key (first answer wins; a
+ *     failed Hatchet publish rolls the claim back inside `ingestEvent`, so a
+ *     retry re-claims).
+ *  4. If we claimed (or a crashed earlier attempt of THIS link did — detected
+ *     by the stored row's `linkId`), stamp `semanticEmittedAt` and emit the
+ *     `email.action` outbound envelope with the same key as `dedupeKey`, so
+ *     re-runs are per-endpoint no-ops.
+ */
+export async function confirmSemanticClick(
+  deps: ConfirmSemanticClickDeps,
+  input: ConfirmSemanticClickInput,
+): Promise<ConfirmSemanticClickResult> {
+  const { db, hatchet, registry, logger } = deps;
+
+  const clickedAtMs = Date.parse(input.clickedAt);
+  if (Number.isNaN(clickedAtMs)) {
+    return { status: "skipped", reason: "bad_clicked_at" };
+  }
+
+  const rows = await db
+    .select({
+      id: trackedLinks.id,
+      emailSendId: trackedLinks.emailSendId,
+      originalUrl: trackedLinks.originalUrl,
+      event: trackedLinks.event,
+      eventProperties: trackedLinks.eventProperties,
+    })
+    .from(trackedLinks)
+    .where(eq(trackedLinks.id, input.trackedLinkId))
+    .limit(1);
+  const link = rows[0];
+  if (!link?.event) {
+    return { status: "skipped", reason: "not_semantic" };
+  }
+  const semanticEvent = link.event;
+
+  // (1) Let the burst window close before judging the click.
+  const remainingMs = clickedAtMs + SEMANTIC_BURST_WINDOW_MS - Date.now();
+  if (remainingMs > 0) {
+    await new Promise((resolve) => setTimeout(resolve, remainingMs));
+  }
+
+  // (2) Whole-burst check: distinct links of this send clicked in the window
+  // AROUND the candidate (before AND after — the deferral is what makes the
+  // "after" half visible).
+  const windowStart = new Date(clickedAtMs - SEMANTIC_BURST_WINDOW_MS);
+  const windowEnd = new Date(clickedAtMs + SEMANTIC_BURST_WINDOW_MS);
+  const burst = await db
+    .select({ n: countDistinct(linkClicks.trackedLinkId) })
+    .from(linkClicks)
+    .innerJoin(trackedLinks, eq(linkClicks.trackedLinkId, trackedLinks.id))
+    .where(
+      and(
+        eq(trackedLinks.emailSendId, link.emailSendId),
+        gte(linkClicks.clickedAt, windowStart),
+        lte(linkClicks.clickedAt, windowEnd),
+      ),
+    );
+  const distinctLinks = burst[0]?.n ?? 0;
+  if (distinctLinks >= SEMANTIC_BURST_DISTINCT_LINKS) {
+    logger.warn("Semantic answer suppressed: scanner-like click burst", {
+      emailSendId: link.emailSendId,
+      linkId: link.id,
+      event: semanticEvent,
+      distinctLinks,
+    });
+    return { status: "suppressed", distinctLinks };
+  }
+
+  const ctx = await resolveEmailSendContext(db, link.emailSendId);
+  if (!ctx) {
+    return { status: "skipped", reason: "no_send_context" };
+  }
+
+  // (3) Claim the answer slot. Duplicate key → stored=false BEFORE the Hatchet
+  // push, so journeys/destinations see at most one answer per (send, event).
+  const semKey = `sem:${link.emailSendId}:${semanticEvent}`;
+  const result = await pushTrackingEvent({
+    db,
+    hatchet,
+    registry,
+    logger,
+    event: semanticEvent,
+    emailSendId: link.emailSendId,
+    properties: {
+      ...(link.eventProperties ?? {}),
+      linkId: link.id,
+    },
+    resolvedContext: ctx,
+    idempotencyKey: semKey,
+  });
+
+  // (4) Claimer determination. stored=false usually means another link won —
+  // but if the stored row carries THIS link's id, it is a crashed earlier
+  // attempt of this very confirmation, and the (idempotent) tail must re-run.
+  let isClaimer = result?.stored ?? false;
+  if (!isClaimer) {
+    const existing = await db
+      .select({ properties: userEvents.properties })
+      .from(userEvents)
+      .where(eq(userEvents.idempotencyKey, semKey))
+      .limit(1);
+    isClaimer = existing[0]?.properties?.linkId === link.id;
+    if (!isClaimer) {
+      return { status: "lost" };
+    }
+  }
+
+  await db
+    .update(trackedLinks)
+    .set({ semanticEmittedAt: new Date(), updatedAt: new Date() })
+    .where(
+      and(eq(trackedLinks.id, link.id), isNull(trackedLinks.semanticEmittedAt)),
+    );
+
+  await emitOutbound({
+    db,
+    hatchet,
+    logger,
+    event: "email.action",
+    dedupeKey: semKey,
+    payload: {
+      event: semanticEvent,
+      properties: link.eventProperties ?? null,
+      emailSendId: link.emailSendId,
+      templateKey: ctx.templateKey ?? null,
+      userId: ctx.userId ?? null,
+      to: ctx.to ?? ctx.userEmail ?? "",
+      at: new Date().toISOString(),
+      linkId: link.id,
+      linkUrl: link.originalUrl,
+    },
+  });
+
+  return { status: "confirmed", event: semanticEvent };
+}

package/src/lib/tracking-events.ts

@@ -2,7 +2,7 @@ import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
 import type { JourneyRegistry } from "@hogsend/core/registry";
 import { type Database, emailSends, journeyStates } from "@hogsend/db";
 import { eq } from "drizzle-orm";
-import { ingestEvent } from "./ingestion.js";
+import { type IngestResult, ingestEvent } from "./ingestion.js";
 import type { Logger } from "./logger.js";
 
 interface EmailSendContext {
@@ -122,6 +122,13 @@ export interface PushTrackingEventOpts {
    * lazily.
    */
   resolvedContext?: EmailSendContext | null;
+  /**
+   * Threaded straight into `ingestEvent` — a duplicate key returns
+   * `{ stored: false }` BEFORE the Hatchet push, so journeys never see the
+   * duplicate. Semantic link answers use `sem:<emailSendId>:<event>` for
+   * first-answer-per-send semantics.
+   */
+  idempotencyKey?: string;
 }
 
 /**
@@ -136,14 +143,14 @@ export interface PushTrackingEventOpts {
  */
 export async function pushTrackingEvent(
   opts: PushTrackingEventOpts,
-): Promise<void> {
+): Promise<IngestResult | undefined> {
   const { db, hatchet, registry, logger, event, emailSendId } = opts;
 
   const ctx =
     opts.resolvedContext !== undefined
       ? opts.resolvedContext
       : await resolveEmailSendContext(db, emailSendId);
-  if (!ctx) return;
+  if (!ctx) return undefined;
 
   const properties: Record<string, unknown> = {
     emailSendId,
@@ -151,7 +158,7 @@ export async function pushTrackingEvent(
     ...opts.properties,
   };
 
-  await ingestEvent({
+  return await ingestEvent({
     db,
     registry,
     hatchet,
@@ -161,6 +168,7 @@ export async function pushTrackingEvent(
       userId: ctx.userId,
       userEmail: ctx.userEmail,
       eventProperties: properties,
+      idempotencyKey: opts.idempotencyKey,
     },
   });
 }

package/src/lib/tracking.ts

@@ -1,14 +1,129 @@
+import { randomUUID } from "node:crypto";
 import type { Database } from "@hogsend/db";
 import { trackedLinks } from "@hogsend/db";
+import {
+  EMAIL_ACTION_EVENT_ATTR,
+  EMAIL_ACTION_PROPS_ATTR,
+  HOSTED_ANSWER_HREF,
+} from "@hogsend/email";
 
-const HREF_RE = /href="(https?:\/\/[^"]+)"/gi;
+const ANCHOR_RE = /<a\b[^>]*>/gi;
+const HREF_RE = /\bhref="(https?:\/\/[^"]+)"/i;
+const SENTINEL_HREF_RE = new RegExp(`\\bhref="${HOSTED_ANSWER_HREF}"`, "i");
+const EVENT_ATTR_RE = new RegExp(
+  `\\b${EMAIL_ACTION_EVENT_ATTR}="([^"]*)"`,
+  "i",
+);
+const PROPS_ATTR_RE = new RegExp(
+  `\\b${EMAIL_ACTION_PROPS_ATTR}="([^"]*)"`,
+  "i",
+);
+const STRIP_SEMANTIC_ATTRS_RE = new RegExp(
+  `\\s*(?:${EMAIL_ACTION_EVENT_ATTR}|${EMAIL_ACTION_PROPS_ATTR})="[^"]*"`,
+  "gi",
+);
 
 const SKIP_PATTERNS = ["/v1/email/unsubscribe", "/v1/email/preferences"];
 
+// Engine-owned event vocabularies (both `email.opened` dot-style and
+// `journey:completed` colon-style exist) — a consumer semantic event in these
+// namespaces would corrupt insights or trigger engine-internal logic.
+const RESERVED_EVENT_NAME_RE = /^(?:email|journey|bucket|contact)[.:]/;
+
+// Semantic payloads re-emit on every answer and persist indefinitely — keep
+// them small and scalar (non-scalars don't survive the Hatchet wire anyway).
+const MAX_PROPS_JSON_LENGTH = 2048;
+
 function shouldSkipUrl(url: string): boolean {
   return SKIP_PATTERNS.some((pattern) => url.includes(pattern));
 }
 
+// React entity-escapes attribute values at render time. Decode the five
+// entities it emits; `&amp;` LAST so `&amp;quot;` round-trips to `&quot;`.
+function decodeAttributeValue(value: string): string {
+  return value
+    .replace(/&quot;/g, '"')
+    .replace(/&#x27;/g, "'")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&amp;/g, "&");
+}
+
+interface SemanticAttrs {
+  event: string;
+  /** Raw (encoded) props attribute — part of the dedupe key. */
+  propsRaw: string | null;
+  properties: Record<string, unknown> | null;
+}
+
+/**
+ * Extract + validate the semantic metadata off one `<a …>` tag. Returns null
+ * for a plain link. Throws on author error — a semantic link that can't be
+ * honored must fail the SEND loudly, not degrade into a silent plain link.
+ */
+function parseSemanticAttrs(tag: string): SemanticAttrs | null {
+  const eventMatch = tag.match(EVENT_ATTR_RE);
+  if (!eventMatch) return null;
+
+  const event = decodeAttributeValue(eventMatch[1] ?? "").trim();
+  if (!event) {
+    throw new Error(`Semantic link has an empty ${EMAIL_ACTION_EVENT_ATTR}`);
+  }
+  if (RESERVED_EVENT_NAME_RE.test(event)) {
+    throw new Error(
+      `Semantic link event "${event}" uses a reserved namespace (email/journey/bucket/contact)`,
+    );
+  }
+
+  const propsMatch = tag.match(PROPS_ATTR_RE);
+  if (!propsMatch) return { event, propsRaw: null, properties: null };
+
+  const propsRaw = propsMatch[1] ?? "";
+  const decoded = decodeAttributeValue(propsRaw);
+  if (decoded.length > MAX_PROPS_JSON_LENGTH) {
+    throw new Error(
+      `Semantic link "${event}" properties exceed ${MAX_PROPS_JSON_LENGTH} chars`,
+    );
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(decoded);
+  } catch {
+    throw new Error(
+      `Semantic link "${event}" has unparseable ${EMAIL_ACTION_PROPS_ATTR}`,
+    );
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(
+      `Semantic link "${event}" properties must be a JSON object`,
+    );
+  }
+  for (const [key, value] of Object.entries(parsed)) {
+    const t = typeof value;
+    if (value !== null && t !== "string" && t !== "number" && t !== "boolean") {
+      throw new Error(
+        `Semantic link "${event}" property "${key}" must be a scalar (string/number/boolean/null)`,
+      );
+    }
+  }
+
+  return {
+    event,
+    propsRaw,
+    properties: parsed as Record<string, unknown>,
+  };
+}
+
+// One tracked_links row per distinct (url, event, props) tuple: identical
+// semantic links share a row; the same URL under DIFFERENT events/props must
+// NOT collapse (the old URL-only dedupe would merge "yes" and "no" answers
+// that point at the same thanks page).
+function linkKey(url: string, semantic: SemanticAttrs | null): string {
+  const sep = String.fromCharCode(0);
+  return [url, semantic?.event ?? "", semantic?.propsRaw ?? ""].join(sep);
+}
+
 export async function rewriteLinks(opts: {
   html: string;
   emailSendId: string;
@@ -17,32 +132,81 @@ export async function rewriteLinks(opts: {
 }): Promise<string> {
   const { html, emailSendId, baseUrl, db } = opts;
 
-  const uniqueUrls = new Set<string>();
+  const pending = new Map<
+    string,
+    { id: string; url: string; semantic: SemanticAttrs | null }
+  >();
 
-  for (const match of html.matchAll(HREF_RE)) {
-    const url = match[1];
-    if (url && !shouldSkipUrl(url)) {
-      uniqueUrls.add(url);
-    }
-  }
+  for (const match of html.matchAll(ANCHOR_RE)) {
+    const tag = match[0];
+    const semantic = parseSemanticAttrs(tag);
 
-  if (uniqueUrls.size === 0) return html;
+    // Sentinel destination: the engine-hosted answer page. Only meaningful on
+    // a semantic link, and resolvable only here (the page URL embeds the
+    // tracked link's own id, generated client-side below).
+    if (SENTINEL_HREF_RE.test(tag)) {
+      if (!semantic) {
+        throw new Error(
+          `href="${HOSTED_ANSWER_HREF}" is only valid on a semantic link (EmailAction)`,
+        );
+      }
+      const key = linkKey(HOSTED_ANSWER_HREF, semantic);
+      if (!pending.has(key)) {
+        const id = randomUUID();
+        pending.set(key, {
+          id,
+          url: `${baseUrl}/v1/t/a/${id}`,
+          semantic,
+        });
+      }
+      continue;
+    }
 
-  const urlList = [...uniqueUrls];
-  const rows = await db
-    .insert(trackedLinks)
-    .values(urlList.map((url) => ({ emailSendId, originalUrl: url })))
-    .returning({ id: trackedLinks.id, originalUrl: trackedLinks.originalUrl });
+    const url = tag.match(HREF_RE)?.[1];
+    if (!url || shouldSkipUrl(url)) {
+      if (semantic) {
+        throw new Error(
+          `Semantic link "${semantic.event}" needs an absolute http(s) href outside unsubscribe/preference URLs`,
+        );
+      }
+      continue;
+    }
 
-  const urlToId = new Map<string, string>();
-  for (const row of rows) {
-    urlToId.set(row.originalUrl, row.id);
+    const key = linkKey(url, semantic);
+    if (!pending.has(key)) {
+      pending.set(key, { id: randomUUID(), url, semantic });
+    }
   }
 
-  return html.replace(HREF_RE, (full, url: string) => {
-    if (shouldSkipUrl(url)) return full;
-    const linkId = urlToId.get(url);
-    return linkId ? `href="${baseUrl}/v1/t/c/${linkId}"` : full;
+  if (pending.size === 0) return html;
+
+  await db.insert(trackedLinks).values(
+    [...pending.values()].map((link) => ({
+      id: link.id,
+      emailSendId,
+      originalUrl: link.url,
+      event: link.semantic?.event,
+      eventProperties: link.semantic?.properties ?? undefined,
+    })),
+  );
+
+  return html.replace(ANCHOR_RE, (tag) => {
+    if (SENTINEL_HREF_RE.test(tag)) {
+      const link = pending.get(
+        linkKey(HOSTED_ANSWER_HREF, parseSemanticAttrs(tag)),
+      );
+      if (!link) return tag;
+      return tag
+        .replace(SENTINEL_HREF_RE, `href="${baseUrl}/v1/t/c/${link.id}"`)
+        .replace(STRIP_SEMANTIC_ATTRS_RE, "");
+    }
+    const url = tag.match(HREF_RE)?.[1];
+    if (!url || shouldSkipUrl(url)) return tag;
+    const link = pending.get(linkKey(url, parseSemanticAttrs(tag)));
+    if (!link) return tag;
+    return tag
+      .replace(HREF_RE, `href="${baseUrl}/v1/t/c/${link.id}"`)
+      .replace(STRIP_SEMANTIC_ATTRS_RE, "");
   });
 }
 

package/src/lib/webhook-signing.ts

@@ -25,7 +25,7 @@ import { Webhook } from "svix";
  */
 
 /**
- * The 13-event catalog — the SINGLE source of truth (schema, routes, client,
+ * The 14-event catalog — the SINGLE source of truth (schema, routes, client,
  * CLI all derive from this). The `webhook.test` sentinel is intentionally NOT a
  * member (it is delivered out-of-band regardless of an endpoint's `eventTypes`).
  */
@@ -38,6 +38,7 @@ export const WEBHOOK_EVENT_TYPES = [
   "email.delivered",
   "email.opened",
   "email.clicked",
+  "email.action",
   "email.bounced",
   "email.complained",
   "journey.completed",

package/src/routes/tracking/answer.ts

@@ -0,0 +1,187 @@
+import { trackedLinks } from "@hogsend/db";
+import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
+import { eq } from "drizzle-orm";
+import type { AppEnv } from "../../app.js";
+import { htmlPage } from "../../lib/html.js";
+import {
+  pushTrackingEvent,
+  resolveEmailSendContext,
+} from "../../lib/tracking-events.js";
+
+/**
+ * The hosted answer page — the engine-served landing for a semantic link
+ * whose author has no page of their own (`href={HOSTED_ANSWER_HREF}` in
+ * `EmailAction`). Possession of the unguessable link id is the auth, the
+ * same trust model as unsubscribe.
+ *
+ * GET shows the recorded answer and an optional free-text box; POST ingests
+ * the comment as `<event>.comment` — a real consumer event journeys and
+ * destinations can react to. ONE comment per (send, event): the
+ * `semc:` idempotency key mirrors first-answer-wins, which also caps what a
+ * forwarded link can inject.
+ */
+
+const COMMENT_MAX = 2000;
+
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#x27;");
+}
+
+function describeAnswer(properties: Record<string, unknown> | null): string {
+  if (!properties) return "";
+  const parts = Object.entries(properties)
+    .filter(([, v]) => v !== null && v !== undefined)
+    .map(([k, v]) => `${escapeHtml(k)}: ${escapeHtml(String(v))}`);
+  return parts.join(" · ");
+}
+
+async function loadSemanticLink(
+  db: AppEnv["Variables"]["container"]["db"],
+  id: string,
+) {
+  const rows = await db
+    .select({
+      id: trackedLinks.id,
+      emailSendId: trackedLinks.emailSendId,
+      event: trackedLinks.event,
+      eventProperties: trackedLinks.eventProperties,
+    })
+    .from(trackedLinks)
+    .where(eq(trackedLinks.id, id))
+    .limit(1);
+  const link = rows[0];
+  return link?.event ? link : null;
+}
+
+const answerPageRoute = createRoute({
+  method: "get",
+  path: "/a/:id",
+  tags: ["Tracking"],
+  summary: "Hosted answer page for a semantic link",
+  request: {
+    params: z.object({ id: z.string().uuid() }),
+  },
+  responses: {
+    200: {
+      description: "Answer page",
+      content: { "text/html": { schema: z.string() } },
+    },
+    404: { description: "Not a semantic link" },
+  },
+});
+
+const answerCommentRoute = createRoute({
+  method: "post",
+  path: "/a/:id",
+  tags: ["Tracking"],
+  summary: "Attach a free-text comment to a semantic answer",
+  request: {
+    params: z.object({ id: z.string().uuid() }),
+    body: {
+      content: {
+        "application/x-www-form-urlencoded": {
+          schema: z.object({ comment: z.string().min(1).max(COMMENT_MAX) }),
+        },
+      },
+    },
+  },
+  responses: {
+    200: {
+      description: "Comment recorded",
+      content: { "text/html": { schema: z.string() } },
+    },
+    404: { description: "Not a semantic link" },
+  },
+});
+
+export const answerRouter = new OpenAPIHono<AppEnv>()
+  .openapi(answerPageRoute, async (c) => {
+    const { id } = c.req.valid("param");
+    const { db } = c.get("container");
+
+    const link = await loadSemanticLink(db, id);
+    if (!link) {
+      return c.html(
+        htmlPage({
+          title: "Not found",
+          body: "<h1>Nothing here</h1><p>This link doesn't lead anywhere.</p>",
+        }),
+        404,
+      );
+    }
+
+    const answer = describeAnswer(link.eventProperties);
+    return c.html(
+      htmlPage({
+        title: "Thanks — answer recorded",
+        body: `
+  <h1>Thanks — that's recorded.</h1>
+  ${answer ? `<p>Your answer: <strong>${answer}</strong></p>` : ""}
+  <p>Anything you'd like to add? A sentence here goes straight to the team.</p>
+  <form method="post" action="">
+    <textarea name="comment" rows="4" maxlength="${COMMENT_MAX}" required
+      style="width:100%;padding:10px;border:1px solid #e5e7eb;border-radius:8px;font:inherit"></textarea>
+    <button type="submit"
+      style="margin-top:12px;padding:10px 18px;border:0;border-radius:8px;background:#1a1a1a;color:#fff;font:inherit;cursor:pointer">
+      Send
+    </button>
+  </form>`,
+      }),
+    );
+  })
+  .openapi(answerCommentRoute, async (c) => {
+    const { id } = c.req.valid("param");
+    const { comment } = c.req.valid("form");
+    const { db, hatchet, registry, logger } = c.get("container");
+
+    const link = await loadSemanticLink(db, id);
+    if (!link) {
+      return c.html(
+        htmlPage({
+          title: "Not found",
+          body: "<h1>Nothing here</h1><p>This link doesn't lead anywhere.</p>",
+        }),
+        404,
+      );
+    }
+
+    const ctx = await resolveEmailSendContext(db, link.emailSendId);
+    if (ctx) {
+      // `<event>.comment` is a consumer-namespace event — journeys can wait
+      // on it and destinations receive it like any other. First comment per
+      // (send, event) wins; repeats are no-ops.
+      await pushTrackingEvent({
+        db,
+        hatchet,
+        registry,
+        logger,
+        event: `${link.event}.comment`,
+        emailSendId: link.emailSendId,
+        properties: {
+          comment,
+          parentEvent: link.event,
+          ...(link.eventProperties ?? {}),
+          linkId: link.id,
+        },
+        resolvedContext: ctx,
+        idempotencyKey: `semc:${link.emailSendId}:${link.event}`,
+      }).catch((err) => {
+        logger.warn("Failed to ingest answer comment", {
+          linkId: link.id,
+          error: err instanceof Error ? err.message : String(err),
+        });
+      });
+    }
+
+    return c.html(
+      htmlPage({
+        title: "Thank you",
+        body: "<h1>Thank you.</h1><p>Your note is on its way to the team. You can close this tab.</p>",
+      }),
+    );
+  });