@hogsend/engine 0.17.0 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hogsend/engine",
-  "version": "0.17.0",
+  "version": "0.18.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.17.0",
-    "@hogsend/db": "^0.17.0",
-    "@hogsend/email": "^0.17.0",
-    "@hogsend/plugin-posthog": "^0.17.0",
-    "@hogsend/plugin-resend": "^0.17.0"
+    "@hogsend/core": "^0.18.0",
+    "@hogsend/db": "^0.18.0",
+    "@hogsend/email": "^0.18.0",
+    "@hogsend/plugin-posthog": "^0.18.0",
+    "@hogsend/plugin-resend": "^0.18.0"
   },
   "optionalDependencies": {
-    "@hogsend/plugin-postmark": "^0.17.0"
+    "@hogsend/plugin-postmark": "^0.18.0"
   },
   "devDependencies": {
     "@types/node": "^22.15.3",

package/src/lib/contacts.ts

@@ -122,6 +122,10 @@ interface ResolveKey {
   value: string;
 }
 
+/** Postgres uuid syntax — guards the `contacts.id` fallback cast below. */
+const UUID_PATTERN =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
 /**
  * Look up the single live contact owning `(kind, value)`, falling back to
  * `contact_aliases` on a miss so a stale (loser/promoted) key still resolves to
@@ -153,14 +157,34 @@ async function findByKey(tx: Tx, key: ResolveKey): Promise<ContactRow | null> {
       ),
     )
     .limit(1);
-  if (!alias[0]) return null;
+  if (alias[0]) {
+    const aliased = await tx
+      .select()
+      .from(contacts)
+      .where(
+        and(eq(contacts.id, alias[0].contactId), isNull(contacts.deletedAt)),
+      )
+      .limit(1);
+    if (aliased[0]) return aliased[0];
+  }
 
-  const aliased = await tx
-    .select()
-    .from(contacts)
-    .where(and(eq(contacts.id, alias[0].contactId), isNull(contacts.deletedAt)))
-    .limit(1);
-  return aliased[0] ?? null;
+  // Row-id fallback (external keys only): an email-only / anonymous-only
+  // contact's canonical key (`external_id ?? anonymous_id ?? id`) IS its row id,
+  // and that key leaves the system — in Hatchet event payloads, outbound
+  // destination `userId`s, and `hs_t` identity tokens. When such a key round-trips
+  // back through ingest as a `userId` (e.g. a PostHog webhook forwarding events
+  // for a person identified via the `hs_t` stitch), it must resolve to the SAME
+  // contact, not mint a duplicate keyed by the old row's id.
+  if (key.kind === "external" && UUID_PATTERN.test(key.value)) {
+    const byId = await tx
+      .select()
+      .from(contacts)
+      .where(and(eq(contacts.id, key.value), isNull(contacts.deletedAt)))
+      .limit(1);
+    return byId[0] ?? null;
+  }
+
+  return null;
 }
 
 /**
@@ -929,6 +953,20 @@ async function recordMergeAliases(
       reason: "merge",
     });
   }
+  // When the loser had neither external_id nor anonymous_id, its CANONICAL key
+  // (`external_id ?? anonymous_id ?? id`) was its row id — and that key has
+  // circulated (Hatchet payloads, outbound `userId`s, `hs_t` tokens). Alias it
+  // as an external key so a round-trip still resolves to the survivor after the
+  // soft-delete takes the row out of findByKey's id fallback.
+  if (!loser.externalId && !loser.anonymousId) {
+    aliasRows.push({
+      contactId: survivorId,
+      aliasKind: "external",
+      aliasValue: loser.id,
+      fromContactId: loser.id,
+      reason: "merge",
+    });
+  }
 
   if (aliasRows.length === 0) return;
 

package/src/lib/ingestion.ts

@@ -36,6 +36,15 @@ export interface ExitResult {
 export interface IngestResult {
   stored: boolean;
   exits: ExitResult[];
+  /**
+   * The contact's canonical text key after this ingest's identity resolve
+   * (`external_id ?? anonymous_id ?? id`). This is the same key outbound
+   * destinations emit as `userId` and `hs_t` identity tokens carry — callers
+   * (e.g. a site's subscribe endpoint) can hand it to their analytics
+   * `identify()` so the session joins the person the contact's email events
+   * land on, without any PII leaving Hogsend.
+   */
+  contactKey: string;
 }
 
 export async function ingestEvent(opts: {
@@ -85,7 +94,7 @@ export async function ingestEvent(opts: {
       .returning({ id: userEvents.id });
 
     if (result.length === 0) {
-      return { stored: false, exits: [] };
+      return { stored: false, exits: [], contactKey: resolvedKey };
     }
     idempotentInsertId = result[0]?.id;
   } else {
@@ -185,7 +194,7 @@ export async function ingestEvent(opts: {
     exits: exits.filter((e) => e.exited).length,
   });
 
-  return { stored: true, exits };
+  return { stored: true, exits, contactKey: resolvedKey };
 }
 
 async function checkExits(

package/src/lib/studio.ts

@@ -88,7 +88,13 @@ export function mountStudio(app: OpenAPIHono<AppEnv>): MountStudioResult {
   });
 
   // Redirect the bare `/studio` to `/studio/` so relative/base assets resolve.
-  app.get("/studio", (c) => c.redirect("/studio/"));
+  // The query string MUST survive the hop: better-auth's password-reset link
+  // redirects to `/studio?token=…`, and dropping the token here strands the
+  // user on the login card instead of the reset form.
+  app.get("/studio", (c) => {
+    const { search } = new URL(c.req.url);
+    return c.redirect(`/studio/${search}`);
+  });
 
   // Static assets (js/css/images) under /studio/*.
   app.use("/studio/*", staticHandler);

package/src/routes/events/index.ts

@@ -25,6 +25,11 @@ const eventResponseSchema = z.object({
       exited: z.boolean(),
     }),
   ),
+  // The contact's canonical key (`external_id ?? anonymous_id ?? id`) — the
+  // same key outbound destinations and `hs_t` identity tokens carry, so the
+  // caller can `identify()` its analytics session against the contact without
+  // any PII round-trip.
+  contactKey: z.string(),
   // Present only when the event was durably ingested but the (non-atomic,
   // post-ingest) list-membership write failed. The ingest itself succeeded —
   // surfaced as a warning on a 202, not a 400 that conflates "nothing happened"