@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.
- package/package.json +11 -11
- package/src/buckets/bucket-access.ts +19 -10
- package/src/buckets/check-membership.ts +61 -8
- package/src/buckets/membership-epoch.ts +11 -1
- package/src/campaigns/cohort-sql.ts +3 -0
- package/src/index.ts +26 -6
- package/src/journeys/execute-journey-run.ts +180 -29
- package/src/journeys/journey-context.ts +43 -7
- package/src/lib/agent/tools.ts +29 -4
- package/src/lib/attribution-backfill.ts +27 -4
- package/src/lib/attribution.ts +22 -3
- package/src/lib/connector-actions.ts +4 -1
- package/src/lib/contacts.ts +518 -148
- package/src/lib/conversion-dispatch.ts +16 -2
- package/src/lib/enrollment-guards.ts +19 -12
- package/src/lib/feed.ts +5 -5
- package/src/lib/flags.ts +26 -9
- package/src/lib/ingestion.ts +23 -2
- package/src/lib/journey-lift.ts +17 -5
- package/src/lib/preferences.ts +116 -30
- package/src/lib/recipient-preferences.ts +16 -2
- package/src/lib/revenue.ts +20 -5
- package/src/lib/sms-tracked.ts +18 -1
- package/src/lib/tracked.ts +50 -8
- package/src/lib/tracking-events.ts +28 -0
- package/src/lib/unique-violation.ts +44 -0
- package/src/routes/admin/buckets.ts +20 -2
- package/src/routes/admin/bulk.ts +18 -2
- package/src/routes/admin/contacts.ts +4 -3
- package/src/routes/admin/conversions.ts +20 -4
- package/src/routes/admin/emails.ts +17 -2
- package/src/routes/admin/events.ts +32 -41
- package/src/routes/admin/funnels.ts +6 -1
- package/src/routes/admin/groups.ts +4 -0
- package/src/routes/admin/impact.ts +30 -10
- package/src/routes/admin/index.ts +2 -0
- package/src/routes/admin/journey-impact.ts +18 -9
- package/src/routes/admin/journeys.ts +8 -1
- package/src/routes/admin/maintenance.ts +216 -0
- package/src/routes/admin/preferences.ts +85 -38
- package/src/routes/admin/reporting.ts +25 -5
- package/src/routes/admin/targeting.ts +1 -0
- package/src/routes/admin/timeline.ts +16 -10
- package/src/routes/email/preferences.ts +18 -1
- package/src/routes/lists/index.ts +11 -6
- package/src/worker.ts +20 -0
- package/src/workflows/backfill-contact-id.ts +951 -0
- package/src/workflows/bucket-backfill.ts +145 -59
- package/src/workflows/bucket-reconcile.ts +154 -50
- package/src/workflows/check-alerts.ts +4 -0
- package/src/workflows/impact-digest.ts +10 -3
- package/src/workflows/journey-blueprint-interpreter.ts +8 -1
- 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.
|
|
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.
|
|
57
|
-
"@hogsend/core": "^0.
|
|
58
|
-
"@hogsend/db": "^0.
|
|
59
|
-
"@hogsend/email": "^0.
|
|
60
|
-
"@hogsend/plugin-posthog": "^0.
|
|
61
|
-
"@hogsend/plugin-resend": "^0.
|
|
62
|
-
"@hogsend/sms": "^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.
|
|
66
|
-
"@hogsend/plugin-postmark": "^0.
|
|
67
|
-
"@hogsend/plugin-twilio": "^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
|
|
61
|
-
* `isNull(deletedAt)` on both
|
|
62
|
-
*
|
|
63
|
-
*
|
|
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(
|
|
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
|
-
//
|
|
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(
|
|
111
|
+
.innerJoin(contacts, eq(contacts.id, bucketMemberships.contactId))
|
|
103
112
|
.where(
|
|
104
113
|
and(
|
|
105
114
|
eq(bucketMemberships.bucketId, bucketId),
|
|
106
|
-
eq(
|
|
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(
|
|
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(
|
|
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
|
-
|
|
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: {
|
|
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(
|
|
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
|
|
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 (
|
|
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
|
-
|
|
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
|
-
|
|
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,
|
|
41
|
-
//
|
|
42
|
-
//
|
|
43
|
-
//
|
|
44
|
-
// `SendEmailOptions`
|
|
45
|
-
|
|
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,
|