@hogsend/engine 0.14.0 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/engine",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -40,14 +40,14 @@
     "svix": "^1.95.1",
     "winston": "^3.19.0",
     "zod": "^4.4.3",
-    "@hogsend/core": "^0.14.0",
-    "@hogsend/db": "^0.14.0",
-    "@hogsend/email": "^0.14.0",
-    "@hogsend/plugin-posthog": "^0.14.0",
-    "@hogsend/plugin-resend": "^0.14.0"
+    "@hogsend/core": "^0.16.0",
+    "@hogsend/db": "^0.16.0",
+    "@hogsend/email": "^0.16.0",
+    "@hogsend/plugin-posthog": "^0.16.0",
+    "@hogsend/plugin-resend": "^0.16.0"
   },
   "optionalDependencies": {
-    "@hogsend/plugin-postmark": "^0.14.0"
+    "@hogsend/plugin-postmark": "^0.16.0"
   },
   "devDependencies": {
     "@types/node": "^22.15.3",

package/src/env.ts

@@ -141,6 +141,13 @@ export const env = createEnv({
     // Default OFF to avoid a surprise double-emit alongside the existing
     // fire-and-forget PostHog capture path.
     ENABLE_POSTHOG_DESTINATION: z.coerce.boolean().default(false),
+    /**
+     * Append a short-lived signed identity token (`hs_t`) to tracked-link
+     * redirect destinations, so the landing site can stitch the email click
+     * to its web session (`POST /v1/t/identify` + posthog.identify). Opt-in:
+     * it changes outbound URLs, which can break pre-signed destinations.
+     */
+    TRACKING_IDENTITY_TOKEN: z.coerce.boolean().default(false),
     RESEND_WEBHOOK_SECRET: z.string().min(1).optional(),
     ADMIN_API_KEY: z.string().min(1).optional(),
     API_PUBLIC_URL: z.string().url().default("http://localhost:3002"),

package/src/index.ts

@@ -205,6 +205,12 @@ export { checkEmailPreferences } from "./lib/enrollment-guards.js";
 export { isFrequencyCapped } from "./lib/frequency-cap.js";
 export { addrSpecOf, hostOfFromAddress } from "./lib/from-address.js";
 export { hatchet } from "./lib/hatchet.js";
+export {
+  generateIdentityToken,
+  type IdentityTokenPayload,
+  InvalidIdentityTokenError,
+  validateIdentityToken,
+} from "./lib/identity-token.js";
 // --- Ingestion pipeline ---
 export {
   type IngestEvent,

package/src/journeys/define-journey.ts

@@ -1,9 +1,12 @@
 import type { JsonValue } from "@hatchet-dev/typescript-sdk/v1/types.js";
-import { evaluatePropertyConditions } from "@hogsend/core";
+import { criteriaBuilder, evaluatePropertyConditions } from "@hogsend/core";
 import type {
   JourneyMeta,
+  JourneyMetaInput,
   JourneyRunFn,
   JourneyUser,
+  JourneyWhere,
+  PropertyCondition,
 } from "@hogsend/core/types";
 import { contacts, journeyConfigs, journeyStates } from "@hogsend/db";
 import { and, eq, inArray, notInArray } from "drizzle-orm";
@@ -37,11 +40,45 @@ export interface DefinedJourney {
   task: ReturnType<typeof hatchet.durableTask>;
 }
 
+/**
+ * Resolve a builder-function `where` to its `PropertyCondition[]` — a
+ * one-shot, definition-time call mirroring `defineBucket`'s criteria
+ * normalization. A declarative array passes straight through, so existing
+ * journeys are unaffected; downstream (registry parse, checkExits, admin
+ * routes, Studio) only ever sees plain data.
+ */
+function normalizeWhere(
+  where: JourneyWhere | undefined,
+): PropertyCondition[] | undefined {
+  if (typeof where !== "function") return where;
+  const resolved = where(criteriaBuilder);
+  return Array.isArray(resolved) ? resolved : [resolved];
+}
+
 export function defineJourney(options: {
-  meta: JourneyMeta;
+  meta: JourneyMetaInput;
   run: JourneyRunFn;
 }): DefinedJourney {
-  const { meta } = options;
+  const { trigger, exitOn, ...rest } = options.meta;
+  const triggerWhere = normalizeWhere(trigger.where);
+  const meta: JourneyMeta = {
+    ...rest,
+    trigger: {
+      event: trigger.event,
+      ...(triggerWhere ? { where: triggerWhere } : {}),
+    },
+    ...(exitOn
+      ? {
+          exitOn: exitOn.map((exit) => {
+            const exitWhere = normalizeWhere(exit.where);
+            return {
+              event: exit.event,
+              ...(exitWhere ? { where: exitWhere } : {}),
+            };
+          }),
+        }
+      : {}),
+  };
 
   const task = hatchet.durableTask({
     name: `journey-${meta.id}`,

package/src/lib/identity-token.ts

@@ -0,0 +1,112 @@
+import {
+  createCipheriv,
+  createDecipheriv,
+  createHash,
+  randomBytes,
+} from "node:crypto";
+
+/**
+ * Short-lived identity token appended to tracked-link redirects as `hs_t`
+ * (opt-in via TRACKING_IDENTITY_TOKEN). The landing site exchanges it at
+ * `POST /v1/t/identify` for the distinct id and calls `posthog.identify` —
+ * stitching the email click to the web session.
+ *
+ * ENCRYPTED (AES-256-GCM keyed off BETTER_AUTH_SECRET), not merely signed:
+ * the distinct id can fall back to an email address, and a signed-but-
+ * readable token would put a base64-decodable email in the URL — into
+ * browser history, referrers, and any script on the landing page. The GCM
+ * auth tag also covers integrity, so tampering fails decryption.
+ */
+
+export interface IdentityTokenPayload {
+  /** The distinct id the landing site should identify as. */
+  distinctId: string;
+  emailSendId: string;
+  exp: number;
+}
+
+export class InvalidIdentityTokenError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "InvalidIdentityTokenError";
+  }
+}
+
+const DEFAULT_EXPIRY_SECONDS = 60 * 60; // 1 hour — a click-to-landing hop
+const IV_LENGTH = 12;
+const TAG_LENGTH = 16;
+
+function deriveKey(secret: string): Buffer {
+  return createHash("sha256").update(secret).digest();
+}
+
+export function generateIdentityToken(opts: {
+  secret: string;
+  distinctId: string;
+  emailSendId: string;
+  expiresInSeconds?: number;
+}): string {
+  const payload: IdentityTokenPayload = {
+    distinctId: opts.distinctId,
+    emailSendId: opts.emailSendId,
+    exp:
+      Math.floor(Date.now() / 1000) +
+      (opts.expiresInSeconds ?? DEFAULT_EXPIRY_SECONDS),
+  };
+  const iv = randomBytes(IV_LENGTH);
+  const cipher = createCipheriv("aes-256-gcm", deriveKey(opts.secret), iv);
+  const ciphertext = Buffer.concat([
+    cipher.update(JSON.stringify(payload), "utf-8"),
+    cipher.final(),
+  ]);
+  return Buffer.concat([iv, ciphertext, cipher.getAuthTag()]).toString(
+    "base64url",
+  );
+}
+
+export function validateIdentityToken(opts: {
+  token: string;
+  secret: string;
+}): IdentityTokenPayload {
+  let raw: Buffer;
+  try {
+    raw = Buffer.from(opts.token, "base64url");
+  } catch {
+    throw new InvalidIdentityTokenError("Malformed token");
+  }
+  if (raw.length <= IV_LENGTH + TAG_LENGTH) {
+    throw new InvalidIdentityTokenError("Malformed token");
+  }
+
+  const iv = raw.subarray(0, IV_LENGTH);
+  const ciphertext = raw.subarray(IV_LENGTH, raw.length - TAG_LENGTH);
+  const tag = raw.subarray(raw.length - TAG_LENGTH);
+
+  let payload: IdentityTokenPayload;
+  try {
+    const decipher = createDecipheriv(
+      "aes-256-gcm",
+      deriveKey(opts.secret),
+      iv,
+    );
+    decipher.setAuthTag(tag);
+    const plaintext = Buffer.concat([
+      decipher.update(ciphertext),
+      decipher.final(),
+    ]).toString("utf-8");
+    payload = JSON.parse(plaintext);
+  } catch {
+    throw new InvalidIdentityTokenError("Bad token");
+  }
+
+  if (
+    typeof payload.distinctId !== "string" ||
+    typeof payload.exp !== "number"
+  ) {
+    throw new InvalidIdentityTokenError("Invalid payload shape");
+  }
+  if (payload.exp < Math.floor(Date.now() / 1000)) {
+    throw new InvalidIdentityTokenError("Token expired");
+  }
+  return payload;
+}

package/src/lib/tracking.ts

@@ -4,10 +4,12 @@ import { trackedLinks } from "@hogsend/db";
 import {
   EMAIL_ACTION_EVENT_ATTR,
   EMAIL_ACTION_PROPS_ATTR,
+  HOSTED_ANSWER_HREF,
 } from "@hogsend/email";
 
 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",
@@ -137,9 +139,30 @@ export async function rewriteLinks(opts: {
 
   for (const match of html.matchAll(ANCHOR_RE)) {
     const tag = match[0];
-    const url = tag.match(HREF_RE)?.[1];
     const semantic = parseSemanticAttrs(tag);
 
+    // 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 url = tag.match(HREF_RE)?.[1];
     if (!url || shouldSkipUrl(url)) {
       if (semantic) {
         throw new Error(
@@ -168,6 +191,15 @@ export async function rewriteLinks(opts: {
   );
 
   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)));

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>",
+      }),
+    );
+  });

package/src/routes/tracking/click.ts

@@ -2,6 +2,7 @@ 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 {
@@ -108,13 +109,49 @@ 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.
+    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,
@@ -157,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);