@hogsend/engine 0.59.0 → 0.61.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/package.json +11 -11
  2. package/src/buckets/bucket-access.ts +34 -11
  3. package/src/buckets/check-membership.ts +74 -10
  4. package/src/buckets/membership-epoch.ts +11 -1
  5. package/src/campaigns/cohort-sql.ts +10 -0
  6. package/src/index.ts +10 -6
  7. package/src/journeys/execute-journey-run.ts +139 -70
  8. package/src/journeys/journey-context.ts +43 -7
  9. package/src/lib/agent/tools.ts +29 -4
  10. package/src/lib/attribution-backfill.ts +35 -4
  11. package/src/lib/attribution.ts +22 -3
  12. package/src/lib/connector-actions.ts +17 -17
  13. package/src/lib/contacts.ts +541 -175
  14. package/src/lib/conversion-dispatch.ts +16 -2
  15. package/src/lib/enrollment-guards.ts +19 -12
  16. package/src/lib/feed.ts +5 -5
  17. package/src/lib/flags.ts +26 -9
  18. package/src/lib/ingestion.ts +14 -2
  19. package/src/lib/journey-lift.ts +17 -5
  20. package/src/lib/preferences.ts +78 -29
  21. package/src/lib/recipient-preferences.ts +16 -2
  22. package/src/lib/refine.ts +16 -10
  23. package/src/lib/revenue.ts +20 -5
  24. package/src/lib/sms-inbound.ts +6 -1
  25. package/src/lib/sms-tracked.ts +18 -1
  26. package/src/lib/timezone.ts +11 -1
  27. package/src/lib/tracked.ts +19 -8
  28. package/src/lib/tracking-events.ts +28 -0
  29. package/src/lib/unique-violation.ts +44 -0
  30. package/src/routes/admin/buckets.ts +21 -1
  31. package/src/routes/admin/bulk.ts +14 -2
  32. package/src/routes/admin/contacts.ts +20 -7
  33. package/src/routes/admin/conversions.ts +20 -4
  34. package/src/routes/admin/emails.ts +17 -2
  35. package/src/routes/admin/events.ts +32 -41
  36. package/src/routes/admin/funnels.ts +6 -1
  37. package/src/routes/admin/groups.ts +4 -0
  38. package/src/routes/admin/impact.ts +30 -10
  39. package/src/routes/admin/journey-impact.ts +18 -9
  40. package/src/routes/admin/journeys.ts +8 -1
  41. package/src/routes/admin/maintenance.ts +7 -1
  42. package/src/routes/admin/preferences.ts +85 -46
  43. package/src/routes/admin/reporting.ts +25 -5
  44. package/src/routes/admin/targeting.ts +1 -0
  45. package/src/routes/admin/timeline.ts +16 -10
  46. package/src/routes/email/preferences.ts +18 -1
  47. package/src/routes/feed/recipient.ts +5 -0
  48. package/src/routes/lists/index.ts +6 -6
  49. package/src/workflows/backfill-contact-id.ts +210 -30
  50. package/src/workflows/bucket-backfill.ts +145 -67
  51. package/src/workflows/bucket-reconcile.ts +164 -51
  52. package/src/workflows/check-alerts.ts +4 -0
  53. package/src/workflows/impact-digest.ts +10 -3
  54. package/src/workflows/journey-blueprint-interpreter.ts +8 -1
  55. package/src/workflows/send-campaign.ts +18 -11
@@ -1,6 +1,7 @@
1
1
  import { isValidTimeZone, type TimeZone } from "@hogsend/core/schedule";
2
2
  import { contacts, type Database } from "@hogsend/db";
3
3
  import { eq } from "drizzle-orm";
4
+ import { lookupContactIdByKey } from "./contacts.js";
4
5
 
5
6
  export interface ResolveTimezoneInput {
6
7
  /** Explicit per-call override, e.g. from `ctx.when.tz("Area/City")`. */
@@ -116,10 +117,19 @@ export async function setContactTimezone(opts: {
116
117
  throw new TypeError(`setContactTimezone: invalid timezone "${timezone}"`);
117
118
  }
118
119
 
120
+ // Resolve the canonical key the alias-aware way, then write BY ROW ID. The
121
+ // old `external_id = :userId` probe was wrong twice over: it never saw an
122
+ // anon-keyed (or uuid-keyed) contact, and — carrying no `deleted_at` filter —
123
+ // a merged-away loser still holds its `external_id`, so a stale key wrote the
124
+ // timezone onto the TOMBSTONE while the live survivor kept none. A key that
125
+ // owns no live contact still returns `{ updated: false }`, unchanged.
126
+ const contactId = await lookupContactIdByKey(db, userId);
127
+ if (!contactId) return { updated: false };
128
+
119
129
  const rows = await db
120
130
  .update(contacts)
121
131
  .set({ timezone, updatedAt: new Date() })
122
- .where(eq(contacts.externalId, userId))
132
+ .where(eq(contacts.id, contactId))
123
133
  .returning({ id: contacts.id });
124
134
 
125
135
  return { updated: rows.length > 0 };
@@ -223,11 +223,11 @@ async function sendTrackedEmailInner<K extends TemplateName>(
223
223
  const subject = options.subject ?? defaultSubject;
224
224
 
225
225
  if (!options.skipPreferenceCheck) {
226
- const suppression = await checkSuppression(
227
- db,
228
- options.to,
229
- effectiveCategory,
230
- );
226
+ const suppression = await checkSuppression(db, {
227
+ email: options.to,
228
+ contactId: sendContactId,
229
+ category: effectiveCategory,
230
+ });
231
231
  if (suppression) {
232
232
  const rows = await db
233
233
  .insert(emailSends)
@@ -662,13 +662,24 @@ type SuppressionReason = EmailSuppressionError["reason"] | null;
662
662
 
663
663
  async function checkSuppression(
664
664
  db: Database,
665
- email: string,
666
- category?: string,
665
+ opts: {
666
+ email: string;
667
+ /**
668
+ * The send's resolved contact (the dual-write stamp already in hand at the
669
+ * call site). PRD 05 T6: an opt-out recorded under an earlier address or
670
+ * an earlier canonical key is reachable ONLY through the contact scope —
671
+ * the address leg alone would mail an unsubscribed person who changed
672
+ * email. Null for a journeyless/raw send (address leg only, unchanged).
673
+ */
674
+ contactId: string | null;
675
+ category?: string;
676
+ },
667
677
  ): Promise<SuppressionReason> {
678
+ const { email, contactId, category } = opts;
668
679
  // Aggregated across ALL `email_preferences` rows for this address by the shared
669
680
  // reader — an address can legitimately have MORE THAN ONE row (multi-row
670
681
  // (user_id, email) aggregation rationale lives in readRecipientPreferences).
671
- const prefs = await readRecipientPreferences(db, { email });
682
+ const prefs = await readRecipientPreferences(db, { email, contactId });
672
683
 
673
684
  if (prefs.suppressed) return "suppressed";
674
685
  if (prefs.unsubscribedAll) return "unsubscribed";
@@ -14,6 +14,14 @@ import { LINK_CLICKED } from "./tracking-event-names.js";
14
14
  interface EmailSendContext {
15
15
  userId: string;
16
16
  userEmail: string;
17
+ /**
18
+ * PRD 05 T6 — the send's owning contact (`email_sends.contact_id`, falling
19
+ * back to the enrollment's stamp). The denormalized `userId` string above is
20
+ * FROZEN at send time and goes stale when the contact adopts a new key; the
21
+ * re-ingest pins this id so tracking events land on the contact, not on
22
+ * whatever key happened to be canonical when the mail left.
23
+ */
24
+ contactId: string | null;
17
25
  templateKey: string | null;
18
26
  messageId: string | null;
19
27
  to: string;
@@ -41,9 +49,11 @@ export async function resolveEmailSendContext(
41
49
  templateKey: emailSends.templateKey,
42
50
  messageId: emailSends.messageId,
43
51
  campaignId: emailSends.campaignId,
52
+ sendContactId: emailSends.contactId,
44
53
  userId: journeyStates.userId,
45
54
  userEmail: journeyStates.userEmail,
46
55
  journeyId: journeyStates.journeyId,
56
+ enrollmentContactId: journeyStates.contactId,
47
57
  })
48
58
  .from(emailSends)
49
59
  .leftJoin(journeyStates, eq(emailSends.journeyStateId, journeyStates.id))
@@ -56,6 +66,7 @@ export async function resolveEmailSendContext(
56
66
  return {
57
67
  userId: row.userId ?? row.toEmail,
58
68
  userEmail: row.userEmail ?? row.toEmail,
69
+ contactId: row.sendContactId ?? row.enrollmentContactId ?? null,
59
70
  templateKey: row.templateKey,
60
71
  messageId: row.messageId,
61
72
  to: row.toEmail,
@@ -68,6 +79,8 @@ export interface EmailSendContextByMessageId {
68
79
  emailSendId: string;
69
80
  userId: string;
70
81
  userEmail: string;
82
+ /** See {@link EmailSendContext.contactId}. */
83
+ contactId: string | null;
71
84
  templateKey: string | null;
72
85
  to: string;
73
86
  }
@@ -99,8 +112,10 @@ export async function resolveEmailSendContextByMessageId(
99
112
  emailSendId: emailSends.id,
100
113
  toEmail: emailSends.toEmail,
101
114
  templateKey: emailSends.templateKey,
115
+ sendContactId: emailSends.contactId,
102
116
  userId: journeyStates.userId,
103
117
  userEmail: journeyStates.userEmail,
118
+ enrollmentContactId: journeyStates.contactId,
104
119
  sendUserId: emailSends.userId,
105
120
  sendUserEmail: emailSends.userEmail,
106
121
  })
@@ -116,6 +131,7 @@ export async function resolveEmailSendContextByMessageId(
116
131
  emailSendId: row.emailSendId,
117
132
  userId: row.userId ?? row.sendUserId ?? row.toEmail,
118
133
  userEmail: row.userEmail ?? row.sendUserEmail ?? row.toEmail,
134
+ contactId: row.sendContactId ?? row.enrollmentContactId ?? null,
119
135
  templateKey: row.templateKey,
120
136
  to: row.toEmail,
121
137
  };
@@ -193,6 +209,9 @@ export async function pushTrackingEvent(
193
209
  event,
194
210
  userId: ctx.userId,
195
211
  userEmail: ctx.userEmail,
212
+ // PRD 05 T6 — pin the send's owning contact so the tracking event
213
+ // resolves to the contact even when the frozen send-time key went stale.
214
+ contactId: ctx.contactId ?? undefined,
196
215
  eventProperties: properties,
197
216
  source: "tracking",
198
217
  idempotencyKey: opts.idempotencyKey,
@@ -310,6 +329,11 @@ export interface SmsSendContext {
310
329
  */
311
330
  userId: string | null;
312
331
  userEmail: string | null;
332
+ /**
333
+ * PRD 05 T6 — the enrollment's contact stamp (`sms_sends` itself carries no
334
+ * dual-write column). Null for a journeyless send.
335
+ */
336
+ contactId: string | null;
313
337
  templateKey: string | null;
314
338
  messageId: string | null;
315
339
  to: string;
@@ -340,6 +364,7 @@ export async function resolveSmsSendContext(
340
364
  userId: journeyStates.userId,
341
365
  userEmail: journeyStates.userEmail,
342
366
  journeyId: journeyStates.journeyId,
367
+ enrollmentContactId: journeyStates.contactId,
343
368
  })
344
369
  .from(smsSends)
345
370
  .leftJoin(journeyStates, eq(smsSends.journeyStateId, journeyStates.id))
@@ -352,6 +377,7 @@ export async function resolveSmsSendContext(
352
377
  return {
353
378
  userId: row.userId ?? row.sendUserId ?? null,
354
379
  userEmail: row.userEmail ?? null,
380
+ contactId: row.enrollmentContactId ?? null,
355
381
  templateKey: row.templateKey,
356
382
  messageId: row.messageId,
357
383
  to: row.toPhone,
@@ -399,6 +425,8 @@ export async function pushSmsTrackingEvent(
399
425
  event,
400
426
  userId: ctx.userId,
401
427
  userEmail: ctx.userEmail ?? undefined,
428
+ // PRD 05 T6 — see pushTrackingEvent.
429
+ contactId: ctx.contactId ?? undefined,
402
430
  eventProperties: {
403
431
  smsSendId,
404
432
  templateKey: ctx.templateKey,
@@ -0,0 +1,44 @@
1
+ /**
2
+ * PRD 05 T3 — the shared "was this a unique_violation on THAT index?" probe.
3
+ *
4
+ * The contact-scoped uniqueness indexes are pure CONSTRAINTS: no upsert names
5
+ * them as an `ON CONFLICT` arbiter, because drizzle can only target columns and
6
+ * a bare `(contact_id, …)` arbiter would never fire for the NULL (contactless)
7
+ * population — an anonymous re-trigger would then insert a second row and die on
8
+ * the retained string index. So each writer keeps its string arbiter and
9
+ * converts THIS error into its own already-exists branch.
10
+ *
11
+ * Postgres reports the code as 23505 and names the index in `constraint_name`,
12
+ * but drizzle wraps the driver error in a `DrizzleQueryError`, so the real
13
+ * payload lives on `cause` (sometimes nested) — walk the chain, bounded. Mirrors
14
+ * `isSlugUniqueViolation` (lib/links.ts) and `isPhoneUniqueViolation`
15
+ * (lib/contacts.ts); this is the extracted, shared form.
16
+ */
17
+ export function isUniqueViolationOn(err: unknown, index: string): boolean {
18
+ for (let e = err, depth = 0; e && depth < 5; depth++) {
19
+ const candidate = e as {
20
+ code?: string;
21
+ constraint_name?: string;
22
+ constraint?: string;
23
+ message?: string;
24
+ cause?: unknown;
25
+ };
26
+ if (
27
+ candidate.code === "23505" &&
28
+ (candidate.constraint_name === index ||
29
+ candidate.constraint === index ||
30
+ (candidate.message?.includes(index) ?? false))
31
+ ) {
32
+ return true;
33
+ }
34
+ e = candidate.cause;
35
+ }
36
+ return false;
37
+ }
38
+
39
+ /** `journey_states` — one live enrollment per (contact, journey). */
40
+ export const UQ_CONTACT_JOURNEY_ACTIVE = "uq_contact_journey_active";
41
+
42
+ /** `email_preferences` — one row per (contact, email). */
43
+ export const UQ_CONTACT_EMAIL_PREFERENCES =
44
+ "email_preferences_contact_email_idx";
@@ -1,7 +1,9 @@
1
+ import { bySubject } from "@hogsend/core";
1
2
  import { bucketConfigs, bucketMemberships } from "@hogsend/db";
2
3
  import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
3
4
  import { and, count, desc, eq, inArray, isNull } from "drizzle-orm";
4
5
  import type { AppEnv } from "../../app.js";
6
+ import { lookupContactIdByKey } from "../../lib/contacts.js";
5
7
 
6
8
  const bucketSchema = z.object({
7
9
  id: z.string(),
@@ -464,7 +466,25 @@ export const bucketsRouter = new OpenAPIHono<AppEnv>()
464
466
  isNull(bucketMemberships.deletedAt),
465
467
  ];
466
468
  if (userId) {
467
- conditions.push(eq(bucketMemberships.userId, userId));
469
+ // The `userId` filter is a canonical key typed by an operator, so resolve
470
+ // it to the contact it names and scope by SUBJECT. A raw
471
+ // `user_id = :userId` filter hides every row this person accumulated
472
+ // under an earlier key — the exact history Studio is being asked to show.
473
+ // No live contact for the key → fall back to the string arm, which is
474
+ // also the right answer for a contactless (anonymous) subject.
475
+ //
476
+ // PRD 07 T7 — resolution runs through the alias-aware primitive (same
477
+ // live-contact scope as the `coalesce(...) = :userId` probe it replaces),
478
+ // so an operator pasting a merged-away key sees the SURVIVOR's rows
479
+ // instead of dropping to the string arm and showing only the fragment
480
+ // still literally keyed on it.
481
+ const ownerId = await lookupContactIdByKey(db, userId);
482
+ conditions.push(
483
+ bySubject(bucketMemberships, {
484
+ contactId: ownerId,
485
+ userKey: userId,
486
+ }),
487
+ );
468
488
  }
469
489
 
470
490
  const where = and(...conditions);
@@ -1,8 +1,12 @@
1
+ import { bySubject } from "@hogsend/core";
1
2
  import { contacts, emailSends, importJobs, userEvents } from "@hogsend/db";
2
3
  import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
3
4
  import { and, desc, eq, gte, inArray, isNull, lte } from "drizzle-orm";
4
5
  import type { AppEnv } from "../../app.js";
5
- import { contactSearchFilter } from "../../lib/contacts.js";
6
+ import {
7
+ contactSearchFilter,
8
+ lookupContactIdByKey,
9
+ } from "../../lib/contacts.js";
6
10
  import { ingestEvent } from "../../lib/ingestion.js";
7
11
  import { errorSchema } from "../../lib/schemas.js";
8
12
  import { importContactsTask } from "../../workflows/import-contacts.js";
@@ -388,8 +392,16 @@ export const bulkRouter = new OpenAPIHono<AppEnv>()
388
392
  if (body.filter?.event) {
389
393
  conditions.push(eq(userEvents.event, body.filter.event));
390
394
  }
395
+ // Replay by subject, not by string: resolve the supplied key to its
396
+ // owning contact so a replay covers the events that person emitted
397
+ // under keys they have since moved off. No contact for the key → the
398
+ // literal string match, as before.
391
399
  if (body.filter?.userId) {
392
- conditions.push(eq(userEvents.userId, body.filter.userId));
400
+ const filterKey = body.filter.userId;
401
+ const contactId = await lookupContactIdByKey(db, filterKey);
402
+ conditions.push(
403
+ bySubject(userEvents, { contactId, userKey: filterKey }),
404
+ );
393
405
  }
394
406
  if (body.filter?.from) {
395
407
  conditions.push(gte(userEvents.occurredAt, new Date(body.filter.from)));
@@ -9,6 +9,7 @@ import { and, asc, count, desc, eq, isNull, not, sql } from "drizzle-orm";
9
9
  import type { AppEnv } from "../../app.js";
10
10
  import {
11
11
  ALL_IDENTITY_KINDS,
12
+ contactKeySql,
12
13
  contactSearchFilter,
13
14
  deleteIdentityAliasesForContact,
14
15
  identifiedContactFilter,
@@ -375,9 +376,17 @@ export const contactsRouter = new OpenAPIHono<AppEnv>()
375
376
  : desc(contacts.lastSeenAt),
376
377
  ];
377
378
 
378
- // Valued events are keyed by the contact's canonical event key
379
- // (external_id ?? anonymous_id ?? id) — same precedence ingestEvent
380
- // resolves. Served by the partial user_events_valued_user_idx.
379
+ // Valued events are owned the PRD 05 way: by `contact_id` when the row
380
+ // carries one, and only otherwise by the contact's canonical event key
381
+ // (external_id ?? anonymous_id ?? id — the same precedence `ingestEvent`
382
+ // resolves, served by the partial user_events_valued_user_idx). The FK arm
383
+ // is what the string arm cannot do: adoption stamps `contact_id` WITHOUT
384
+ // rewriting the frozen `user_id`, so a person's pre-identify (or
385
+ // merged-away) revenue sat under a key that no longer equals their
386
+ // canonical one and this filter never counted it. The `contact_id is null`
387
+ // guard on the string arm keeps it to rows nobody owns — an unowned row
388
+ // whose key happens to collide with another contact's is the bug PRD 05
389
+ // exists to close.
381
390
  // Exclusions come from lib/revenue.ts (static machinery events + funnel
382
391
  // milestone triggers + the browser trust gate): one deal's value rides
383
392
  // several rows, and pk_-minted values are forgeable.
@@ -386,7 +395,10 @@ export const contactsRouter = new OpenAPIHono<AppEnv>()
386
395
  ? sql`(
387
396
  select coalesce(sum(ue.value), 0)
388
397
  from user_events ue
389
- where ue.user_id = coalesce(${contacts.externalId}, ${contacts.anonymousId}, ${contacts.id}::text)
398
+ where (
399
+ ue.contact_id = ${contacts.id}
400
+ or (ue.contact_id is null and ue.user_id = ${contactKeySql()})
401
+ )
390
402
  and ue.value is not null
391
403
  and ue.event not in (${sql.join(
392
404
  revenueExcludedEvents().map((e) => sql`${e}`),
@@ -453,19 +465,20 @@ export const contactsRouter = new OpenAPIHono<AppEnv>()
453
465
  return c.json({ error: "Contact not found" }, 404);
454
466
  }
455
467
 
456
- // email_preferences.user_id uses external_id when present, else the contact
457
- // uuid as the deterministic fallback (risk 10 — email-only contacts).
468
+ // PRD 05 T6 — preference rows are read by ownership stamp; the old
469
+ // `external_id ?? id` string derivation goes stale on adoption.
458
470
  const [prefRows, revenue, groupRows] = await Promise.all([
459
471
  db
460
472
  .select()
461
473
  .from(emailPreferences)
462
- .where(eq(emailPreferences.userId, contact.externalId ?? contact.id))
474
+ .where(eq(emailPreferences.contactId, contact.id))
463
475
  .limit(1),
464
476
  // Valued events are keyed by the contact's canonical event key — the
465
477
  // same precedence ingestEvent resolves (`external ?? anon ?? id`).
466
478
  getContactRevenue({
467
479
  db,
468
480
  key: contact.externalId ?? contact.anonymousId ?? contact.id,
481
+ contactId: contact.id,
469
482
  }),
470
483
  // The contact's live group memberships (mirrors the admin groups router's
471
484
  // join idiom): `group_memberships` → `groups`, live groups only, ordered
@@ -313,19 +313,35 @@ export const adminConversionsRouter = new OpenAPIHono<AppEnv>()
313
313
  // Per subject: the anchor instant + its subject key. A journey subject is
314
314
  // one enrollment row (created_at); an event subject is a contact's FIRST
315
315
  // occurrence of the named event in the window.
316
+ //
317
+ // `subject_key` is the owning contact when the `contact_id` FK is stamped,
318
+ // else the mutable text key — `bySubject` written in SQL. Two things the
319
+ // coalesce is protecting, both of which fail SILENTLY:
320
+ // (1) the event leg GROUPS BY this expression, so a bare `contact_id`
321
+ // would collapse every contactless (anonymous) event into ONE group
322
+ // and crush the `anchored` denominator to a single subject;
323
+ // (2) the journey leg would drop nothing but would lose the row's
324
+ // identity entirely for contactless enrollments.
325
+ // The correlated conversion probe below joins `c.contact_id::text` to it:
326
+ // `conversions.contact_id` is NOT NULL, so a text-keyed (contactless)
327
+ // subject correctly matches no conversion — it has no contact, therefore
328
+ // no conversion can belong to it — while still being COUNTED in the
329
+ // denominator, which is what makes the rate honest.
316
330
  const subjects =
317
331
  anchorType === "journey"
318
332
  ? sql`
319
- select js.created_at as anchor_at, js.user_id as subject_key
333
+ select js.created_at as anchor_at,
334
+ coalesce(js.contact_id::text, js.user_id) as subject_key
320
335
  from journey_states js
321
336
  where js.journey_id = ${anchorId}
322
337
  and js.created_at >= ${since}::timestamptz`
323
338
  : sql`
324
- select min(ue.occurred_at) as anchor_at, ue.user_id as subject_key
339
+ select min(ue.occurred_at) as anchor_at,
340
+ coalesce(ue.contact_id::text, ue.user_id) as subject_key
325
341
  from user_events ue
326
342
  where ue.event = ${anchorId}
327
343
  and ue.occurred_at >= ${since}::timestamptz
328
- group by ue.user_id`;
344
+ group by coalesce(ue.contact_id::text, ue.user_id)`;
329
345
 
330
346
  // For each subject, the first conversion of this definition at/after the
331
347
  // anchor (correlated scalar). Latency = first_conv - anchor_at.
@@ -348,7 +364,7 @@ export const adminConversionsRouter = new OpenAPIHono<AppEnv>()
348
364
  (
349
365
  select min(c.occurred_at)
350
366
  from conversions c
351
- where c.user_key = subj.subject_key
367
+ where c.contact_id::text = subj.subject_key
352
368
  and c.definition_id = ${definitionId}
353
369
  and c.occurred_at >= subj.anchor_at
354
370
  ) as first_conv
@@ -1,3 +1,4 @@
1
+ import { bySubject } from "@hogsend/core";
1
2
  import {
2
3
  type Database,
3
4
  emailSends,
@@ -21,6 +22,7 @@ import {
21
22
  or,
22
23
  } from "drizzle-orm";
23
24
  import type { AppEnv } from "../../app.js";
25
+ import { lookupContactIdByKey } from "../../lib/contacts.js";
24
26
 
25
27
  const emailSchema = z.object({
26
28
  id: z.string(),
@@ -282,10 +284,17 @@ export const emailsRouter = new OpenAPIHono<AppEnv>()
282
284
  conditions.push(eq(emailSends.campaignId, campaignId));
283
285
  }
284
286
  // Match the denormalized identity OR the journey-state join, so journeyless
285
- // sends (which only carry the denormalized userId) are still filterable.
287
+ // sends (which only carry the denormalized identity) are still filterable.
288
+ // Both legs go through `bySubject` off ONE resolved contact: the operator
289
+ // typed a text key, and the person's sends may be split across the keys
290
+ // they held over time. The `or` here is across two TABLES (send row vs.
291
+ // its enrollment), not two arms of one subject — `bySubject` still picks
292
+ // exactly one predicate per table.
286
293
  if (userId) {
294
+ const contactId = await lookupContactIdByKey(db, userId);
295
+ const subject = { contactId, userKey: userId };
287
296
  conditions.push(
288
- or(eq(emailSends.userId, userId), eq(journeyStates.userId, userId)),
297
+ or(bySubject(emailSends, subject), bySubject(journeyStates, subject)),
289
298
  );
290
299
  }
291
300
  if (engagement) conditions.push(isNotNull(engagementColumn[engagement]));
@@ -305,6 +314,10 @@ export const emailsRouter = new OpenAPIHono<AppEnv>()
305
314
  const [rows, totalRows] = await Promise.all([
306
315
  db
307
316
  .select({
317
+ // Display echo of the text key this send was stamped under, NOT a
318
+ // scoping predicate — the response's `userId` field is a string by
319
+ // contract. Deliberately left on `user_id`; PRD 05 flips scoping
320
+ // reads, not the wire format.
308
321
  ...getTableColumns(emailSends),
309
322
  identityUserId: journeyStates.userId,
310
323
  identityJourneyId: journeyStates.journeyId,
@@ -360,6 +373,8 @@ export const emailsRouter = new OpenAPIHono<AppEnv>()
360
373
  ? db
361
374
  .select({
362
375
  journeyId: journeyStates.journeyId,
376
+ // Display echo of the stamped text key (see the list route) —
377
+ // `journeyContext.userId` is a string by contract.
363
378
  userId: journeyStates.userId,
364
379
  status: journeyStates.status,
365
380
  currentNodeId: journeyStates.currentNodeId,
@@ -1,3 +1,4 @@
1
+ import { bySubject } from "@hogsend/core";
1
2
  import { contacts, userEvents } from "@hogsend/db";
2
3
  import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
3
4
  import {
@@ -11,11 +12,9 @@ import {
11
12
  lte,
12
13
  max,
13
14
  min,
14
- or,
15
- sql,
16
15
  } from "drizzle-orm";
17
16
  import type { AppEnv } from "../../app.js";
18
- import type { HogsendClient } from "../../container.js";
17
+ import { lookupContactIdByKey } from "../../lib/contacts.js";
19
18
  import {
20
19
  eventNameEntrySchema,
21
20
  listEventNameVocabulary,
@@ -30,8 +29,8 @@ const eventSchema = z.object({
30
29
  occurredAt: z.string(),
31
30
  // Where the event entered the pipeline ("posthog", "api", "studio", …).
32
31
  source: z.string().nullable(),
33
- // Resolved from THE live contact whose key (externalId, anonymousId, or
34
- // id) matches user_events.userId — shows WHO an event is from.
32
+ // Resolved from the event's owning contact (`user_events.contact_id`) when
33
+ // that contact is still live — shows WHO an event is from.
35
34
  userEmail: z.string().nullable(),
36
35
  contactId: z.string().nullable(),
37
36
  });
@@ -59,36 +58,21 @@ function serializeEvent(row: JoinedEvent) {
59
58
  }
60
59
 
61
60
  /**
62
- * LATERAL pick of THE live contact for an event's userId. `userEvents.userId`
63
- * holds the resolved canonical key (`external_id ?? anonymous_id ?? id`), so
64
- * match all three — covering email-only/anonymous contacts, not just
65
- * externalId-keyed ones. Each column is partial-unique among live rows, but
66
- * the three namespaces are NOT guaranteed disjoint across contacts: a
67
- * mis-keyed emitter can park one contact's key in another contact's
68
- * anonymous_id, and a bare OR-join then matches BOTH — fanning every event
69
- * out into one display row per matching contact. The lateral picks exactly
70
- * one, by the same precedence ingest resolves keys with.
61
+ * The event's owning contact, named directly by the `contact_id` FK.
62
+ *
63
+ * This replaces a LATERAL that re-derived the owner by matching
64
+ * `user_events.user_id` against all three key columns (external_id,
65
+ * anonymous_id, id::text) under a priority `case`, because the three
66
+ * namespaces are not guaranteed disjoint and a bare OR-join fanned one event
67
+ * into a display row per matching contact. The FK carries the answer, so the
68
+ * three-way guess is gone. `deleted_at IS NULL` stays inside the join
69
+ * condition: a soft-deleted owner must yield NO contact rather than a
70
+ * tombstone.
71
71
  */
72
- function liveContactFor(db: HogsendClient["db"]) {
73
- return db
74
- .select({ id: contacts.id, email: contacts.email })
75
- .from(contacts)
76
- .where(
77
- and(
78
- or(
79
- eq(contacts.externalId, userEvents.userId),
80
- eq(contacts.anonymousId, userEvents.userId),
81
- eq(sql`${contacts.id}::text`, userEvents.userId),
82
- ),
83
- isNull(contacts.deletedAt),
84
- ),
85
- )
86
- .orderBy(
87
- sql`case when ${contacts.externalId} = ${userEvents.userId} then 0 when ${contacts.anonymousId} = ${userEvents.userId} then 1 else 2 end`,
88
- )
89
- .limit(1)
90
- .as("live_contact");
91
- }
72
+ const liveContactJoin = and(
73
+ eq(contacts.id, userEvents.contactId),
74
+ isNull(contacts.deletedAt),
75
+ );
92
76
 
93
77
  const listRoute = createRoute({
94
78
  method: "get",
@@ -308,7 +292,16 @@ export const eventsRouter = new OpenAPIHono<AppEnv>()
308
292
  c.req.valid("query");
309
293
 
310
294
  const conditions = [];
311
- if (userId) conditions.push(eq(userEvents.userId, userId));
295
+ // The `userId` filter is a text key an operator typed (or clicked through
296
+ // from a contact row). Resolve it to the owning contact first so the
297
+ // filter returns that person's WHOLE history — including events stamped
298
+ // under a key they have since moved off (anon → external). On a key no
299
+ // contact owns, `bySubject` falls back to the literal string match, which
300
+ // is the pre-flip behaviour.
301
+ if (userId) {
302
+ const contactId = await lookupContactIdByKey(db, userId);
303
+ conditions.push(bySubject(userEvents, { contactId, userKey: userId }));
304
+ }
312
305
  if (event) conditions.push(eq(userEvents.event, event));
313
306
  if (source) conditions.push(eq(userEvents.source, source));
314
307
  if (from) conditions.push(gte(userEvents.occurredAt, new Date(from)));
@@ -316,15 +309,14 @@ export const eventsRouter = new OpenAPIHono<AppEnv>()
316
309
 
317
310
  const where = conditions.length > 0 ? and(...conditions) : undefined;
318
311
 
319
- const liveContact = liveContactFor(db);
320
312
  const [rows, totalRows] = await Promise.all([
321
313
  db
322
314
  .select({
323
315
  event: userEvents,
324
- contact: { id: liveContact.id, email: liveContact.email },
316
+ contact: { id: contacts.id, email: contacts.email },
325
317
  })
326
318
  .from(userEvents)
327
- .leftJoinLateral(liveContact, sql`true`)
319
+ .leftJoin(contacts, liveContactJoin)
328
320
  .where(where)
329
321
  .orderBy(desc(userEvents.occurredAt))
330
322
  .limit(limit)
@@ -423,14 +415,13 @@ export const eventsRouter = new OpenAPIHono<AppEnv>()
423
415
  const { db } = c.get("container");
424
416
  const { id } = c.req.valid("param");
425
417
 
426
- const liveContact = liveContactFor(db);
427
418
  const rows = await db
428
419
  .select({
429
420
  event: userEvents,
430
- contact: { id: liveContact.id, email: liveContact.email },
421
+ contact: { id: contacts.id, email: contacts.email },
431
422
  })
432
423
  .from(userEvents)
433
- .leftJoinLateral(liveContact, sql`true`)
424
+ .leftJoin(contacts, liveContactJoin)
434
425
  .where(eq(userEvents.id, id))
435
426
  .limit(1);
436
427
 
@@ -140,10 +140,15 @@ export const adminFunnelsRouter = new OpenAPIHono<AppEnv>().openapi(
140
140
  );
141
141
  // Exposure: ≥1 stamped touchpoint BEFORE the outcome instant (the next
142
142
  // stage's reach, or now for non-converters) — association framing.
143
+ // The exposure probe joins the contact FK, not the text key.
144
+ // `funnel_progress.contact_id` is NOT NULL, so there is always a contact
145
+ // to join to and no text fallback is needed — and the events a person
146
+ // emitted before they registered (stamped under an anonymous key) now
147
+ // count as exposure, which the `user_key` string compare missed.
143
148
  const exposed = scopeKey
144
149
  ? sql`exists (
145
150
  select 1 from user_events ue
146
- where ue.user_id = ${funnelProgress.userKey}
151
+ where ue.contact_id = ${funnelProgress.contactId}
147
152
  and ue.event in (${touchEventList})
148
153
  and ue.properties->>${sql.raw(`'${scopeKey}'`)} = ${scopeValue}
149
154
  and ue.occurred_at <= coalesce(${next.reachedAt}, now())
@@ -865,6 +865,10 @@ export const groupsRouter = new OpenAPIHono<AppEnv>()
865
865
  id: userEvents.id,
866
866
  event: userEvents.event,
867
867
  occurredAt: userEvents.occurredAt,
868
+ // Display echo of the key the event was stamped under — not a
869
+ // scoping predicate. The rows are already scoped by the group's
870
+ // jsonb association (`taggedEvents`), and the response field is a
871
+ // string by contract.
868
872
  userId: userEvents.userId,
869
873
  })
870
874
  .from(userEvents)