@hogsend/engine 0.13.2 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/engine",
-  "version": "0.13.2",
+  "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.13.2",
-    "@hogsend/plugin-posthog": "^0.13.2",
-    "@hogsend/db": "^0.13.2",
-    "@hogsend/plugin-resend": "^0.13.2",
-    "@hogsend/email": "^0.13.2"
+    "@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.13.2"
+    "@hogsend/plugin-postmark": "^0.16.0"
   },
   "devDependencies": {
     "@types/node": "^22.15.3",

package/src/destinations/presets/posthog.ts

@@ -53,6 +53,41 @@ export const posthogDestination = defineDestination({
       userEmail?: string | null;
     };
     const distinctId = data.userId ?? data.to ?? data.userEmail ?? undefined;
+    // `email.action` is the semantic-link envelope: the CONSUMER's event name
+    // (data.event, e.g. "nps.submitted") is what PostHog should capture, with
+    // the author's properties flattened to the top level. Other catalog events
+    // capture under their spine name (with the optional remap).
+    if (envelope.type === "email.action") {
+      const action = envelope.data as {
+        event: string;
+        properties: Record<string, unknown> | null;
+        emailSendId: string;
+        templateKey: string | null;
+        linkId: string;
+        linkUrl: string;
+        to: string;
+        userId: string | null;
+        at: string;
+      };
+      return {
+        url: `${host}/capture/`,
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          api_key: config.apiKey,
+          event: action.event,
+          distinct_id: distinctId,
+          timestamp: envelope.timestamp,
+          properties: {
+            ...(action.properties ?? {}),
+            emailSendId: action.emailSendId,
+            templateKey: action.templateKey,
+            linkId: action.linkId,
+            $lib: "hogsend",
+          },
+        }),
+      };
+    }
     // Optional event-name remap (identity by default).
     const eventName = config.eventNames?.[envelope.type] ?? envelope.type;
     return {

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,
@@ -229,6 +235,13 @@ export {
 } from "./lib/redis.js";
 // --- Self-service password reset (engine-owned, self-contained email) ---
 export { sendResetPasswordEmail } from "./lib/reset-email.js";
+export {
+  type ConfirmSemanticClickInput,
+  type ConfirmSemanticClickResult,
+  confirmSemanticClick,
+  SEMANTIC_BURST_DISTINCT_LINKS,
+  SEMANTIC_BURST_WINDOW_MS,
+} from "./lib/semantic-click.js";
 export { type MountStudioResult, mountStudio } from "./lib/studio.js";
 export {
   type ResolveTimezoneInput,

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/journeys/journey-context.ts

@@ -22,11 +22,17 @@ import type {
   IfPast,
   JourneyContext,
   TimeOfDayBuilder,
+  WaitForEventResult,
   Weekday,
   WhenBuilder,
 } from "@hogsend/core/types";
-import { type Database, emailSends, journeyStates } from "@hogsend/db";
-import { and, count, eq, max, notInArray } from "drizzle-orm";
+import {
+  type Database,
+  emailSends,
+  journeyStates,
+  userEvents,
+} from "@hogsend/db";
+import { and, count, desc, eq, gte, max, notInArray } from "drizzle-orm";
 import { checkEmailPreferences } from "../lib/enrollment-guards.js";
 import { ingestEvent } from "../lib/ingestion.js";
 import type { Logger } from "../lib/logger.js";
@@ -206,7 +212,8 @@ export function createJourneyContext(
     event: string,
     timeout: DurationObject,
     nodeId: string,
-  ): Promise<{ timedOut: boolean }> => {
+    lookback?: DurationObject,
+  ): Promise<WaitForEventResult> => {
     // Reject a timeout longer than the journey task's executionTimeout up front
     // so it fails fast at authoring time. (Eviction-capable engines may allow
     // longer wall-clock waits, but we cap to the configured ceiling — raise
@@ -217,6 +224,41 @@ export function createJourneyContext(
       );
     }
 
+    // Optional lookback: the durable wait only matches events pushed AFTER it
+    // is established, so an answer landing in the gap (between a send and its
+    // wait, or between two back-to-back waits) would otherwise be permanently
+    // unobservable — its first-answer idempotency key is already claimed and
+    // can never re-push. A recent matching user_events row resolves the wait
+    // immediately, payload included.
+    if (lookback) {
+      const since = new Date(Date.now() - durationToMs(lookback));
+      const recent = await db
+        .select({ properties: userEvents.properties })
+        .from(userEvents)
+        .where(
+          and(
+            eq(userEvents.userId, userId),
+            eq(userEvents.event, event),
+            gte(userEvents.occurredAt, since),
+          ),
+        )
+        .orderBy(desc(userEvents.occurredAt))
+        .limit(1);
+      const row = recent[0];
+      if (row) {
+        const scalars = Object.fromEntries(
+          Object.entries(row.properties ?? {}).filter(
+            ([, v]) =>
+              typeof v === "string" ||
+              typeof v === "number" ||
+              typeof v === "boolean" ||
+              v === null,
+          ),
+        ) as NonNullable<WaitForEventResult["properties"]>;
+        return { timedOut: false, properties: scalars };
+      }
+    }
+
     await enterWait(nodeId);
 
     // Wait for the user-scoped event or the timeout. The event branch filters on
@@ -241,9 +283,34 @@ export function createJourneyContext(
       {}) as Record<string, unknown>;
     const timedOut = !("event" in fired);
 
+    // Surface the matched event's payload (best-effort). The engine returns
+    // matches as `[{ id, data }]` where `data` is the pushed ingest payload
+    // ({ userId, userEmail, properties }); the pre-eviction path may hand the
+    // payload back un-wrapped — tolerate both, mirroring the CREATE-strip.
+    let properties: WaitForEventResult["properties"];
+    if (!timedOut) {
+      const matches = fired.event;
+      const first = Array.isArray(matches) ? matches[0] : matches;
+      const payload =
+        first && typeof first === "object" && "data" in first
+          ? (first as { data?: unknown }).data
+          : first;
+      const candidate =
+        payload && typeof payload === "object" && "properties" in payload
+          ? (payload as { properties?: unknown }).properties
+          : undefined;
+      if (
+        candidate &&
+        typeof candidate === "object" &&
+        !Array.isArray(candidate)
+      ) {
+        properties = candidate as NonNullable<WaitForEventResult["properties"]>;
+      }
+    }
+
     await resumeFromWait();
 
-    return { timedOut };
+    return { timedOut, ...(properties ? { properties } : {}) };
   };
 
   return {
@@ -275,11 +342,12 @@ export function createJourneyContext(
       );
     },
 
-    async waitForEvent({ event, timeout, label }) {
+    async waitForEvent({ event, timeout, label, lookback }) {
       return performWaitForEvent(
         event,
         timeout,
         label ?? `wait-event:${event}`,
+        lookback,
       );
     },
 

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/ingestion.ts

@@ -68,6 +68,7 @@ export async function ingestEvent(opts: {
 
   // (2) Idempotency dedup + `user_events` insert keyed on the resolved key, with
   // ONLY eventProperties in the properties bag (D2).
+  let idempotentInsertId: string | undefined;
   if (event.idempotencyKey) {
     const result = await db
       .insert(userEvents)
@@ -86,6 +87,7 @@ export async function ingestEvent(opts: {
     if (result.length === 0) {
       return { stored: false, exits: [] };
     }
+    idempotentInsertId = result[0]?.id;
   } else {
     await db.insert(userEvents).values({
       userId: resolvedKey,
@@ -109,7 +111,13 @@ export async function ingestEvent(opts: {
 
   // (4) Hatchet push + (5) checkExits, both keyed on the resolved key. The push
   // payload wire key STAYS `properties` (bucket tests assert on it — risk 9).
-  const [, exits] = await Promise.all([
+  //
+  // An idempotency claim must not outlive a FAILED publish: journeys were never
+  // notified, and the consumed key would make every retry a silent no-op (the
+  // event becomes permanently invisible to journeys/destinations). So on a push
+  // failure the just-inserted row is compensating-deleted before rethrowing —
+  // the caller's retry (same key) can then re-claim and re-publish.
+  const [pushResult, exitsResult] = await Promise.allSettled([
     hatchet.events.push(event.event, {
       userId: resolvedKey,
       userEmail: event.userEmail ?? "",
@@ -121,6 +129,29 @@ export async function ingestEvent(opts: {
       properties: event.eventProperties,
     }),
   ]);
+  if (pushResult.status === "rejected") {
+    if (idempotentInsertId) {
+      try {
+        await db
+          .delete(userEvents)
+          .where(eq(userEvents.id, idempotentInsertId));
+      } catch (cleanupErr) {
+        logger.warn("ingestEvent: failed to roll back idempotency claim", {
+          event: event.event,
+          idempotencyKey: event.idempotencyKey,
+          error:
+            cleanupErr instanceof Error
+              ? cleanupErr.message
+              : String(cleanupErr),
+        });
+      }
+    }
+    throw pushResult.reason;
+  }
+  if (exitsResult.status === "rejected") {
+    throw exitsResult.reason;
+  }
+  const exits = exitsResult.value;
 
   // (6) Real-time bucket membership re-evaluation (Section 6.1). NOT part of the
   // Promise.all above: its property eval reads contact state ⊕ this-ingest

package/src/lib/outbound.ts

@@ -90,6 +90,23 @@ export interface OutboundPayloads {
   "email.delivered": EmailEventPayload;
   "email.opened": EmailEventPayload;
   "email.clicked": EmailEventPayload & { linkUrl?: string; linkId?: string };
+  /**
+   * A SEMANTIC link answered — the in-email action event (consumer-named, e.g.
+   * "nps.submitted"). Emitted at most once per (send, event name): first
+   * answer wins, scanner bursts are suppressed. `event`/`properties` carry the
+   * consumer semantics; the rest is send context.
+   */
+  "email.action": {
+    event: string;
+    properties: Record<string, unknown> | null;
+    emailSendId: string;
+    templateKey: string | null;
+    userId: string | null;
+    to: string;
+    at: string;
+    linkId: string;
+    linkUrl: string;
+  };
   "email.bounced": EmailEventPayload & {
     bounceType?: string;
     bounceReason?: string;

package/src/lib/seed-posthog-destination.ts

@@ -18,6 +18,7 @@ const POSTHOG_FUNNEL_EVENTS = [
   "email.delivered",
   "email.opened",
   "email.clicked",
+  "email.action",
   "email.bounced",
   "email.complained",
 ] as const;
@@ -51,7 +52,11 @@ export async function seedPostHogDestination(opts: {
     );
 
     const existing = await tx
-      .select({ id: webhookEndpoints.id })
+      .select({
+        id: webhookEndpoints.id,
+        url: webhookEndpoints.url,
+        eventTypes: webhookEndpoints.eventTypes,
+      })
       .from(webhookEndpoints)
       .where(
         and(
@@ -61,7 +66,34 @@ export async function seedPostHogDestination(opts: {
       )
       .limit(1);
 
-    if (existing.length > 0) {
+    const found = existing[0];
+    if (found) {
+      // Reconcile the ENGINE-seeded row (identified by its sentinel URL) when
+      // the funnel list has grown since it was inserted — its stored
+      // eventTypes are a snapshot, and emitOutbound matches by jsonb
+      // containment, so a pre-upgrade row would silently never receive newer
+      // events (e.g. email.action). Operator-created endpoints are left
+      // untouched: subscriber-chooses-events is the contract there.
+      if (found.url === "posthog://capture") {
+        const current = Array.isArray(found.eventTypes)
+          ? (found.eventTypes as string[])
+          : [];
+        const missing = POSTHOG_FUNNEL_EVENTS.filter(
+          (e) => !current.includes(e),
+        );
+        if (missing.length > 0) {
+          await tx
+            .update(webhookEndpoints)
+            .set({
+              eventTypes: [...current, ...missing],
+              updatedAt: new Date(),
+            })
+            .where(eq(webhookEndpoints.id, found.id));
+          logger.info("Reconciled seeded PostHog destination event types", {
+            added: missing,
+          });
+        }
+      }
       return { seeded: false };
     }