@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
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hogsend/engine",
3
- "version": "0.58.0",
3
+ "version": "0.60.0",
4
4
  "type": "module",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -53,18 +53,18 @@
53
53
  "svix": "^1.95.1",
54
54
  "winston": "^3.19.0",
55
55
  "zod": "^4.4.3",
56
- "@hogsend/attribution": "^0.58.0",
57
- "@hogsend/core": "^0.58.0",
58
- "@hogsend/db": "^0.58.0",
59
- "@hogsend/email": "^0.58.0",
60
- "@hogsend/plugin-posthog": "^0.58.0",
61
- "@hogsend/plugin-resend": "^0.58.0",
62
- "@hogsend/sms": "^0.58.0"
56
+ "@hogsend/attribution": "^0.60.0",
57
+ "@hogsend/core": "^0.60.0",
58
+ "@hogsend/db": "^0.60.0",
59
+ "@hogsend/email": "^0.60.0",
60
+ "@hogsend/plugin-posthog": "^0.60.0",
61
+ "@hogsend/plugin-resend": "^0.60.0",
62
+ "@hogsend/sms": "^0.60.0"
63
63
  },
64
64
  "optionalDependencies": {
65
- "@hogsend/plugin-apollo": "^0.58.0",
66
- "@hogsend/plugin-postmark": "^0.58.0",
67
- "@hogsend/plugin-twilio": "^0.58.0"
65
+ "@hogsend/plugin-apollo": "^0.60.0",
66
+ "@hogsend/plugin-postmark": "^0.60.0",
67
+ "@hogsend/plugin-twilio": "^0.60.0"
68
68
  },
69
69
  "devDependencies": {
70
70
  "@types/node": "^22.15.3",
@@ -57,10 +57,14 @@ function toError(err: unknown): Error {
57
57
  * container re-binds the accessors with a `dbResolver` that returns its own
58
58
  * `db`; the `getDb()` default bypasses the container.
59
59
  *
60
- * Every query `innerJoin`s `contacts` on `externalId` and filters
61
- * `isNull(deletedAt)` on both tables — GDPR parity with every reconcile/admin
62
- * query. No method throws (except the iterator on a page error); failures are
63
- * carried in the result's `error`.
60
+ * Every query `innerJoin`s `contacts` on the membership's OWNING CONTACT
61
+ * (`bucket_memberships.contact_id`) and filters `isNull(deletedAt)` on both
62
+ * tables — GDPR parity with every reconcile/admin query. The join used to run
63
+ * on the mutable text key (`coalesce(external_id, anonymous_id, id) =
64
+ * user_id`); it now runs on the FK, so a membership adopted onto a contact
65
+ * under a since-stale key stays visible instead of dropping out of every count
66
+ * and page. No method throws (except the iterator on a page error); failures
67
+ * are carried in the result's `error`.
64
68
  */
65
69
  export function createBucketAccessor(
66
70
  bucketId: string,
@@ -75,7 +79,7 @@ export function createBucketAccessor(
75
79
  const rows = await db
76
80
  .select({ value: countFn() })
77
81
  .from(bucketMemberships)
78
- .innerJoin(contacts, eq(contactKeySql(), bucketMemberships.userId))
82
+ .innerJoin(contacts, eq(contacts.id, bucketMemberships.contactId))
79
83
  .where(
80
84
  and(
81
85
  eq(bucketMemberships.bucketId, bucketId),
@@ -95,15 +99,20 @@ export function createBucketAccessor(
95
99
  ): Promise<{ data: boolean; error: Error | null }> {
96
100
  try {
97
101
  const db = dbResolver();
98
- // O(1) probe on the partial active unique index (uq_user_bucket_active).
102
+ // The subject predicate moves to the CONTACT side: `userId` is the caller's
103
+ // canonical key, so we name the contact it resolves to and let the FK join
104
+ // find that contact's membership. Probing `bucket_memberships.user_id`
105
+ // instead answers "false" for a member whose row was adopted under an
106
+ // anon-era key — the person is in the bucket, `has()` says they are not,
107
+ // and every gate built on it silently opens.
99
108
  const rows = await db
100
109
  .select({ id: bucketMemberships.id })
101
110
  .from(bucketMemberships)
102
- .innerJoin(contacts, eq(contactKeySql(), bucketMemberships.userId))
111
+ .innerJoin(contacts, eq(contacts.id, bucketMemberships.contactId))
103
112
  .where(
104
113
  and(
105
114
  eq(bucketMemberships.bucketId, bucketId),
106
- eq(bucketMemberships.userId, userId),
115
+ eq(contactKeySql(), userId),
107
116
  eq(bucketMemberships.status, "active"),
108
117
  isNull(bucketMemberships.deletedAt),
109
118
  isNull(contacts.deletedAt),
@@ -145,7 +154,7 @@ export function createBucketAccessor(
145
154
  entryCount: bucketMemberships.entryCount,
146
155
  })
147
156
  .from(bucketMemberships)
148
- .innerJoin(contacts, eq(contactKeySql(), bucketMemberships.userId))
157
+ .innerJoin(contacts, eq(contacts.id, bucketMemberships.contactId))
149
158
  .where(and(...conditions))
150
159
  .orderBy(bucketMemberships.id)
151
160
  // +1 peek to detect a next page.
@@ -153,7 +162,7 @@ export function createBucketAccessor(
153
162
  db
154
163
  .select({ value: countFn() })
155
164
  .from(bucketMemberships)
156
- .innerJoin(contacts, eq(contactKeySql(), bucketMemberships.userId))
165
+ .innerJoin(contacts, eq(contacts.id, bucketMemberships.contactId))
157
166
  .where(
158
167
  and(
159
168
  eq(bucketMemberships.bucketId, bucketId),
@@ -1,6 +1,7 @@
1
1
  import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
2
2
  import {
3
3
  type BucketMeta,
4
+ bySubject,
4
5
  collectPropertyNames,
5
6
  durationToMs,
6
7
  evaluateCondition,
@@ -235,10 +236,17 @@ export async function checkBucketMembership(opts: {
235
236
  if (!bucket.criteria) continue;
236
237
 
237
238
  // wasMember — current active, non-deleted membership row (cheap pre-filter;
238
- // the authoritative guard is the RETURNING-gated mutation below).
239
+ // the authoritative guard is the RETURNING-gated mutation below). Read by
240
+ // SUBJECT: a membership adopted onto this contact under a since-stale key
241
+ // is invisible to a `user_id` probe, and missing it re-runs the JOIN path,
242
+ // which then loses the arbiter-less race and no-ops — a member who silently
243
+ // never re-emits and never leaves.
239
244
  const active = await db.query.bucketMemberships.findFirst({
240
245
  where: and(
241
- eq(bucketMemberships.userId, userId),
246
+ bySubject(bucketMemberships, {
247
+ contactId: contactId ?? null,
248
+ userKey: userId,
249
+ }),
242
250
  eq(bucketMemberships.bucketId, bucket.id),
243
251
  eq(bucketMemberships.status, "active"),
244
252
  isNull(bucketMemberships.deletedAt),
@@ -252,7 +260,16 @@ export async function checkBucketMembership(opts: {
252
260
  // sub-conditions read the merged journeyContext.
253
261
  const isMember = await evaluateCondition({
254
262
  condition: bucket.criteria,
255
- ctx: { db, userId, journeyContext },
263
+ ctx: {
264
+ db,
265
+ userId,
266
+ // `ingestEvent` resolved the subject before calling us, so the event /
267
+ // count legs read this person's whole history — including the rows
268
+ // adopted from an anon-era key — instead of only what the current
269
+ // string key happens to name.
270
+ contactId: contactId ?? null,
271
+ journeyContext,
272
+ },
256
273
  });
257
274
 
258
275
  if (!wasMember && isMember) {
@@ -324,13 +341,27 @@ async function handleJoin(opts: {
324
341
  // this (user, bucket) (Section 6.3 / 8.2). priorCount also drives the entryLimit
325
342
  // gate. Shared with the reconcile-discovered join path so the ordinal can
326
343
  // never drift between the two writers.
327
- const priorCount = await countPriorMemberships(db, bucket.id, userId);
344
+ const priorCount = await countPriorMemberships(
345
+ db,
346
+ bucket.id,
347
+ userId,
348
+ contactId ?? null,
349
+ );
328
350
  const epoch = priorCount + 1;
329
351
 
330
- // INSERT a FRESH active row. ON CONFLICT DO NOTHING targets the partial active
352
+ // INSERT a FRESH active row. ON CONFLICT DO NOTHING covers the partial active
331
353
  // unique index (uq_user_bucket_active): a concurrent emitter that already
332
354
  // inserted the active row makes THIS insert return zero rows → we do NOT emit
333
355
  // (the loser mutates nothing — Section 6.3 governing rule).
356
+ //
357
+ // PRD 05 T3 — the DO NOTHING is deliberately ARBITER-LESS. Two partial unique
358
+ // indexes now guard this table (uq_user_bucket_active and its contact-scoped
359
+ // twin uq_contact_bucket_active), Postgres allows only ONE conflict target per
360
+ // statement, and both must land in the same "already a member" branch: the
361
+ // contact one is what catches an adopted row whose `user_id` still differs.
362
+ // Narrowing this to a column target would let that collision escape as a raw
363
+ // 23505 — and a target naming `contact_id` would additionally miss every
364
+ // contactless (NULL) member.
334
365
  const expiresAt = computeExpiresAt(bucket);
335
366
  // Unconditional TTL deadline — set once on join, swept by the reconcile cron.
336
367
  const maxDwellAt = computeMaxDwellAt(bucket);
@@ -346,6 +377,12 @@ async function handleJoin(opts: {
346
377
  expiresAt,
347
378
  maxDwellAt,
348
379
  lastEvaluatedAt: new Date(),
380
+ // PRD 04 dual-write. `contactId` is already a documented param of this
381
+ // function (`ingestEvent` resolved the subject before calling us), so this
382
+ // is ZERO new queries and has no failure mode to wrap: `undefined` — a
383
+ // pin-less caller or a refused resolve — stamps NULL and the join is
384
+ // recorded exactly as before (memberships are text-keyed, no contact FK).
385
+ contactId: contactId ?? null,
349
386
  })
350
387
  .onConflictDoNothing()
351
388
  .returning({ id: bucketMemberships.id });
@@ -380,7 +417,15 @@ async function handleJoin(opts: {
380
417
  // The active row is always written (Studio size must reflect reality) and the
381
418
  // epoch always advances via the real insert; only the bucket:entered emission
382
419
  // is gated by the entryLimit policy (Section 6.3).
383
- if (await shouldEmitJoin({ db, bucket, userId, priorCount })) {
420
+ if (
421
+ await shouldEmitJoin({
422
+ db,
423
+ bucket,
424
+ userId,
425
+ contactId: contactId ?? null,
426
+ priorCount,
427
+ })
428
+ ) {
384
429
  await emitBucketTransition({
385
430
  db,
386
431
  registry,
@@ -526,9 +571,17 @@ export async function shouldEmitJoin(opts: {
526
571
  db: Database;
527
572
  bucket: BucketMeta;
528
573
  userId: string;
574
+ /**
575
+ * The owning contact's `contacts.id`, or `null` when the caller has none.
576
+ * REQUIRED (not optional) on purpose: the prior-cycle lookup below is the
577
+ * cooldown gate, and an optional field a caller forgets silently drops it
578
+ * back onto the mutable text key — which misses the adopted prior cycle and
579
+ * re-emits a `once` join. Pass `null` explicitly for a contactless subject.
580
+ */
581
+ contactId: string | null;
529
582
  priorCount: number;
530
583
  }): Promise<boolean> {
531
- const { db, bucket, userId, priorCount } = opts;
584
+ const { db, bucket, userId, contactId, priorCount } = opts;
532
585
  // First-ever join always emits.
533
586
  if (priorCount === 0) return true;
534
587
  switch (bucket.entryLimit ?? "unlimited") {
@@ -550,7 +603,7 @@ export async function shouldEmitJoin(opts: {
550
603
  .from(bucketMemberships)
551
604
  .where(
552
605
  and(
553
- eq(bucketMemberships.userId, userId),
606
+ bySubject(bucketMemberships, { contactId, userKey: userId }),
554
607
  eq(bucketMemberships.bucketId, bucket.id),
555
608
  eq(bucketMemberships.status, "left"),
556
609
  isNotNull(bucketMemberships.leftAt),
@@ -1,5 +1,6 @@
1
1
  import {
2
2
  type BucketMeta,
3
+ bySubject,
3
4
  type ConditionEval,
4
5
  type DurationObject,
5
6
  durationToMs,
@@ -25,18 +26,27 @@ export const BUCKET_EVENT_PREFIX = "bucket:";
25
26
  *
26
27
  * The predicate MUST stay status-agnostic — narrowing it (e.g. to active-only)
27
28
  * would corrupt entryCount and the entryLimit cooldown.
29
+ *
30
+ * `contactId` is REQUIRED (not optional) for the same reason
31
+ * `checkEntryLimit`'s is: an optional field silently defaults a new caller onto
32
+ * the mutable text key, and here that under-counts the epoch — a person whose
33
+ * anon-era memberships were adopted would re-enter at ordinal 1 and slip the
34
+ * `once`/`once_per_period` gate. Pass `null` explicitly for a subject with no
35
+ * contact; that is a permanent, supported state (memberships are text-keyed
36
+ * with no contact FK).
28
37
  */
29
38
  export async function countPriorMemberships(
30
39
  db: Database,
31
40
  bucketId: string,
32
41
  userId: string,
42
+ contactId: string | null,
33
43
  ): Promise<number> {
34
44
  const [counted] = await db
35
45
  .select({ priorCount: sql<number>`count(*)::int` })
36
46
  .from(bucketMemberships)
37
47
  .where(
38
48
  and(
39
- eq(bucketMemberships.userId, userId),
49
+ bySubject(bucketMemberships, { contactId, userKey: userId }),
40
50
  eq(bucketMemberships.bucketId, bucketId),
41
51
  ),
42
52
  );
@@ -161,6 +161,9 @@ function eventSql(condition: EventCondition, startedAt: Date): SQL {
161
161
  Date.now() - durationToMs(condition.within),
162
162
  ).toISOString()}::timestamptz`
163
163
  : sql.empty();
164
+ // PRD 05 T8 — this correlation STAYS string-keyed: `campaign_recipients`
165
+ // has no `contact_id` column, so the text key is the only subject available
166
+ // on the outer side of the join.
164
167
  const positive = sql`exists (
165
168
  select 1 from ${userEvents}
166
169
  where ${userEvents.userId} = ${campaignRecipients.userId}
package/src/index.ts CHANGED
@@ -37,14 +37,18 @@ export type {
37
37
  // types) so content can import everything from `@hogsend/engine`.
38
38
  export * from "@hogsend/core";
39
39
  // --- Capability-provider contracts (canonical origin: @hogsend/core) ---
40
- // Email provider contract + analytics contract, re-exported so consumers can
41
- // import them from `@hogsend/engine`. (`SendEmailOptions` is intentionally
42
- // omitted here: the engine's public `SendEmailOptions` is the high-level
43
- // journey-facing send options from `./lib/email.js`; the provider-contract
44
- // `SendEmailOptions` remains available via `@hogsend/core`.)
45
- export {
40
+ // Email provider contract + analytics contract, plus `bySubject` (the
41
+ // either/or history scope every engine-side history read is expected to move
42
+ // onto), re-exported so consumers can import them from `@hogsend/engine`.
43
+ // (`SendEmailOptions` is intentionally omitted here: the engine's public
44
+ // `SendEmailOptions` is the high-level journey-facing send options from
45
+ // `./lib/email.js`; the provider-contract `SendEmailOptions` remains available
46
+ // via `@hogsend/core`.)
47
+ export {
48
+ bySubject,
46
49
  defineAnalyticsProvider,
47
50
  defineEmailProvider,
51
+ type Subject,
48
52
  WebhookHandshakeSignal,
49
53
  } from "@hogsend/core";
50
54
  export {
@@ -916,6 +920,22 @@ export {
916
920
  createWorker,
917
921
  type Worker,
918
922
  } from "./worker.js";
923
+ // --- History contact_id backfill (PRD 04): periodic reconcile sweep + enqueue,
924
+ // --- plus T6's invariant probe (`flipReady` = the read-flip entry gate) ---
925
+ export {
926
+ CONTACT_ID_BACKFILL_FORMAT,
927
+ type ContactIdBackfillCounts,
928
+ type ContactIdBackfillInput,
929
+ type ContactIdBackfillResult,
930
+ type ContactIdBackfillTable,
931
+ type ContactIdVerifyCounts,
932
+ type ContactIdVerifyResult,
933
+ contactIdBackfillTask,
934
+ contactIdResweepIntervalMs,
935
+ enqueueContactIdBackfill,
936
+ runContactIdBackfill,
937
+ verifyContactIdBackfill,
938
+ } from "./workflows/backfill-contact-id.js";
919
939
  export {
920
940
  type BucketBackfillInput,
921
941
  bucketBackfillTask,