@hogsend/engine 0.58.0 → 0.60.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 (53) hide show
  1. package/package.json +11 -11
  2. package/src/buckets/bucket-access.ts +19 -10
  3. package/src/buckets/check-membership.ts +61 -8
  4. package/src/buckets/membership-epoch.ts +11 -1
  5. package/src/campaigns/cohort-sql.ts +3 -0
  6. package/src/index.ts +26 -6
  7. package/src/journeys/execute-journey-run.ts +180 -29
  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 +27 -4
  11. package/src/lib/attribution.ts +22 -3
  12. package/src/lib/connector-actions.ts +4 -1
  13. package/src/lib/contacts.ts +518 -148
  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 +23 -2
  19. package/src/lib/journey-lift.ts +17 -5
  20. package/src/lib/preferences.ts +116 -30
  21. package/src/lib/recipient-preferences.ts +16 -2
  22. package/src/lib/revenue.ts +20 -5
  23. package/src/lib/sms-tracked.ts +18 -1
  24. package/src/lib/tracked.ts +50 -8
  25. package/src/lib/tracking-events.ts +28 -0
  26. package/src/lib/unique-violation.ts +44 -0
  27. package/src/routes/admin/buckets.ts +20 -2
  28. package/src/routes/admin/bulk.ts +18 -2
  29. package/src/routes/admin/contacts.ts +4 -3
  30. package/src/routes/admin/conversions.ts +20 -4
  31. package/src/routes/admin/emails.ts +17 -2
  32. package/src/routes/admin/events.ts +32 -41
  33. package/src/routes/admin/funnels.ts +6 -1
  34. package/src/routes/admin/groups.ts +4 -0
  35. package/src/routes/admin/impact.ts +30 -10
  36. package/src/routes/admin/index.ts +2 -0
  37. package/src/routes/admin/journey-impact.ts +18 -9
  38. package/src/routes/admin/journeys.ts +8 -1
  39. package/src/routes/admin/maintenance.ts +216 -0
  40. package/src/routes/admin/preferences.ts +85 -38
  41. package/src/routes/admin/reporting.ts +25 -5
  42. package/src/routes/admin/targeting.ts +1 -0
  43. package/src/routes/admin/timeline.ts +16 -10
  44. package/src/routes/email/preferences.ts +18 -1
  45. package/src/routes/lists/index.ts +11 -6
  46. package/src/worker.ts +20 -0
  47. package/src/workflows/backfill-contact-id.ts +951 -0
  48. package/src/workflows/bucket-backfill.ts +145 -59
  49. package/src/workflows/bucket-reconcile.ts +154 -50
  50. package/src/workflows/check-alerts.ts +4 -0
  51. package/src/workflows/impact-digest.ts +10 -3
  52. package/src/workflows/journey-blueprint-interpreter.ts +8 -1
  53. package/src/workflows/send-campaign.ts +18 -11
@@ -1,3 +1,4 @@
1
+ import { bySubject } from "@hogsend/core";
1
2
  import { emailSends, journeyStates, userEvents } from "@hogsend/db";
2
3
  import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
3
4
  import { and, count, desc, eq, isNull } from "drizzle-orm";
@@ -64,10 +65,15 @@ export const timelineRouter = new OpenAPIHono<AppEnv>().openapi(
64
65
  return c.json({ error: "Contact not found" }, 404);
65
66
  }
66
67
 
67
- // Resolved string key the history tables (user_events/journey_states/
68
- // email_sends) were written under: external_id, else anonymous_id, else the
69
- // contact uuid (matches ingestEvent's resolvedKey).
70
- const externalId = contactKey(contact);
68
+ // The timeline reads history BY SUBJECT. `contact.id` always exists here
69
+ // (the contact was just resolved), so every leg below scopes on the
70
+ // `contact_id` FK — which is what makes the timeline show activity a
71
+ // person accumulated under keys they have since moved off (an anonymous
72
+ // id before they registered). `userKey` is the resolved string key those
73
+ // rows were originally written under (external_id, else anonymous_id,
74
+ // else the contact uuid — matches ingestEvent's resolvedKey); it is the
75
+ // `bySubject` fallback arm and is never reached from here.
76
+ const subject = { contactId: contact.id, userKey: contactKey(contact) };
71
77
  const entries: TimelineEntry[] = [];
72
78
 
73
79
  const shouldFetch = (t: string) => !type || type === t;
@@ -85,7 +91,7 @@ export const timelineRouter = new OpenAPIHono<AppEnv>().openapi(
85
91
  ? db
86
92
  .select()
87
93
  .from(userEvents)
88
- .where(eq(userEvents.userId, externalId))
94
+ .where(bySubject(userEvents, subject))
89
95
  .orderBy(desc(userEvents.occurredAt))
90
96
  .limit(fetchLimit)
91
97
  : Promise.resolve([]),
@@ -95,7 +101,7 @@ export const timelineRouter = new OpenAPIHono<AppEnv>().openapi(
95
101
  .from(journeyStates)
96
102
  .where(
97
103
  and(
98
- eq(journeyStates.userId, externalId),
104
+ bySubject(journeyStates, subject),
99
105
  isNull(journeyStates.deletedAt),
100
106
  ),
101
107
  )
@@ -123,7 +129,7 @@ export const timelineRouter = new OpenAPIHono<AppEnv>().openapi(
123
129
  )
124
130
  .where(
125
131
  and(
126
- eq(journeyStates.userId, externalId),
132
+ bySubject(journeyStates, subject),
127
133
  isNull(journeyStates.deletedAt),
128
134
  ),
129
135
  )
@@ -134,7 +140,7 @@ export const timelineRouter = new OpenAPIHono<AppEnv>().openapi(
134
140
  ? db
135
141
  .select({ count: count() })
136
142
  .from(userEvents)
137
- .where(eq(userEvents.userId, externalId))
143
+ .where(bySubject(userEvents, subject))
138
144
  .then((r) => r[0]?.count ?? 0)
139
145
  : Promise.resolve(0),
140
146
  shouldFetch("journey")
@@ -143,7 +149,7 @@ export const timelineRouter = new OpenAPIHono<AppEnv>().openapi(
143
149
  .from(journeyStates)
144
150
  .where(
145
151
  and(
146
- eq(journeyStates.userId, externalId),
152
+ bySubject(journeyStates, subject),
147
153
  isNull(journeyStates.deletedAt),
148
154
  ),
149
155
  )
@@ -159,7 +165,7 @@ export const timelineRouter = new OpenAPIHono<AppEnv>().openapi(
159
165
  )
160
166
  .where(
161
167
  and(
162
- eq(journeyStates.userId, externalId),
168
+ bySubject(journeyStates, subject),
163
169
  isNull(journeyStates.deletedAt),
164
170
  ),
165
171
  )
@@ -1,3 +1,4 @@
1
+ import { bySubject } from "@hogsend/core";
1
2
  import { emailPreferences } from "@hogsend/db";
2
3
  import type { UnsubscribeTokenPayload } from "@hogsend/email";
3
4
  import {
@@ -8,6 +9,7 @@ import {
8
9
  import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
9
10
  import { and, eq } from "drizzle-orm";
10
11
  import type { AppEnv } from "../../app.js";
12
+ import { lookupContactIdByKey } from "../../lib/contacts.js";
11
13
  import { htmlPage } from "../../lib/html.js";
12
14
  import { getListRegistry } from "../../lists/registry-singleton.js";
13
15
 
@@ -66,12 +68,27 @@ export const preferencesRouter = new OpenAPIHono<AppEnv>().openapi(
66
68
 
67
69
  const { externalId, email } = payload;
68
70
 
71
+ // PRD 05 T6 — the token freezes whatever key the subject had when the mail
72
+ // left. Resolve it to the contact so a key adopted SINCE issuance still
73
+ // reaches the row; a stale/unresolvable key degrades to the string leg
74
+ // (bySubject's else-arm), which matches the old read exactly. D6-wrapped:
75
+ // a bookkeeping probe may never 500 the preference center.
76
+ let tokenContactId: string | null = null;
77
+ try {
78
+ tokenContactId = await lookupContactIdByKey(db, externalId);
79
+ } catch {
80
+ tokenContactId = null;
81
+ }
82
+
69
83
  const rows = await db
70
84
  .select()
71
85
  .from(emailPreferences)
72
86
  .where(
73
87
  and(
74
- eq(emailPreferences.userId, externalId),
88
+ bySubject(emailPreferences, {
89
+ contactId: tokenContactId,
90
+ userKey: externalId,
91
+ }),
75
92
  eq(emailPreferences.email, email),
76
93
  ),
77
94
  )
@@ -410,13 +410,14 @@ export const listsRouter = new OpenAPIHono<AppEnv>()
410
410
  if ((userId || email) && !c.get("publishable")) {
411
411
  const recipient = await resolveRecipient({ db, userId, email });
412
412
  if (recipient) {
413
- const extId = recipient.externalId ?? recipient.contactId;
413
+ // PRD 05 T6 — contact-scoped read; the `externalId ?? contactId`
414
+ // string derivation is retired.
414
415
  const rows = await db
415
416
  .select()
416
417
  .from(emailPreferences)
417
418
  .where(
418
419
  and(
419
- eq(emailPreferences.userId, extId),
420
+ eq(emailPreferences.contactId, recipient.contactId),
420
421
  eq(emailPreferences.email, recipient.email),
421
422
  ),
422
423
  )
@@ -463,15 +464,14 @@ export const listsRouter = new OpenAPIHono<AppEnv>()
463
464
  if (!recipient) {
464
465
  return c.json({ categories: {}, unsubscribedAll: false }, 200);
465
466
  }
466
- // `email_preferences.user_id` is keyed on `external_id ?? contact.id`
467
- // (risk 10) — mirror `resolveRecipient`'s contactId fallback.
468
- const extId = recipient.externalId ?? recipient.contactId;
467
+ // PRD 05 T6 — contact-scoped read; the `externalId ?? contactId` string
468
+ // derivation is retired.
469
469
  const rows = await db
470
470
  .select()
471
471
  .from(emailPreferences)
472
472
  .where(
473
473
  and(
474
- eq(emailPreferences.userId, extId),
474
+ eq(emailPreferences.contactId, recipient.contactId),
475
475
  eq(emailPreferences.email, recipient.email),
476
476
  ),
477
477
  )
@@ -541,6 +541,11 @@ export const listsRouter = new OpenAPIHono<AppEnv>()
541
541
  externalId,
542
542
  email: recipient.email,
543
543
  update: { unsubscribedAll },
544
+ // PRD 04 dual-write: the id is ALREADY in hand from the
545
+ // `resolveOrCreateContact` above (this handler resolves/creates the row
546
+ // before writing preferences), so pass it rather than making
547
+ // `upsertEmailPreference` re-probe the same contact.
548
+ contactId,
544
549
  });
545
550
 
546
551
  return c.json({ unsubscribedAll }, 200);
package/src/worker.ts CHANGED
@@ -18,6 +18,10 @@ import { reportWorkerReady } from "./lib/boot.js";
18
18
  import { hatchet } from "./lib/hatchet.js";
19
19
  import { getRedisIfConnected } from "./lib/redis.js";
20
20
  import { startWorkerHeartbeat } from "./lib/worker-heartbeat.js";
21
+ import {
22
+ contactIdBackfillTask,
23
+ enqueueContactIdBackfill,
24
+ } from "./workflows/backfill-contact-id.js";
21
25
  import {
22
26
  bucketBackfillTask,
23
27
  enqueueBucketBackfills,
@@ -137,6 +141,7 @@ export function createWorker(opts: CreateWorkerOptions): Worker {
137
141
  bucketReconcileTask,
138
142
  bucketBackfillTask,
139
143
  identityAliasBackfillTask,
144
+ contactIdBackfillTask,
140
145
  crmReconcileTask,
141
146
  dispatchConversionTask,
142
147
  ...journeyTasks,
@@ -246,6 +251,21 @@ export function createWorker(opts: CreateWorkerOptions): Worker {
246
251
  });
247
252
  });
248
253
 
254
+ // PRD 04 T5: fill the five history tables' `contact_id` for rows the
255
+ // dual-write never saw. Unlike the alias backfill this is a PERIODIC
256
+ // reconcile sweep (D6) — the enqueue re-fires once the newest completed
257
+ // sweep is older than CONTACT_ID_BACKFILL_RESWEEP_HOURS (default 24h),
258
+ // because the dual-write is best-effort and a miss is otherwise permanent.
259
+ // Cheap by construction: every UPDATE is guarded by `contact_id IS NULL`.
260
+ enqueueContactIdBackfill({
261
+ db: container.db,
262
+ logger: container.logger,
263
+ }).catch((err) => {
264
+ container.logger.warn("Contact-id backfill enqueue (boot) failed", {
265
+ error: err instanceof Error ? err.message : String(err),
266
+ });
267
+ });
268
+
249
269
  // Reconcile code-defined campaigns into scheduled rows (create / sync /
250
270
  // expire — see `reconcileDefinedCampaigns`). Same fire-and-forget stance
251
271
  // as the bucket backfills above: best-effort, never blocks the listener.