@hogsend/engine 0.50.0 → 0.52.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 +10 -10
- package/src/campaigns/cohort-sql.ts +8 -9
- package/src/container.ts +1 -1
- package/src/destinations/define-destination.ts +2 -2
- package/src/flags/reconcile.ts +7 -2
- package/src/index.ts +9 -1
- package/src/journeys/execute-journey-run.ts +15 -0
- package/src/journeys/group-scope.ts +153 -0
- package/src/journeys/journey-context.ts +152 -19
- package/src/journeys/record-once.ts +27 -2
- package/src/lib/campaign-send-key.ts +9 -18
- package/src/lib/conversions.ts +1 -1
- package/src/lib/crm-deals.ts +1 -1
- package/src/lib/crm-ingest.ts +1 -1
- package/src/lib/event-names.ts +7 -1
- package/src/lib/frequency-cap.ts +4 -2
- package/src/lib/funnel-progress.ts +1 -1
- package/src/lib/holdout.ts +1 -1
- package/src/lib/ingestion.ts +6 -0
- package/src/lib/journey-suppress.ts +4 -2
- package/src/lib/lift-stats.ts +2 -2
- package/src/lib/tracked.ts +9 -2
- package/src/routes/admin/attribution.ts +1 -2
- package/src/routes/admin/campaigns.ts +84 -45
- package/src/routes/admin/conversions.ts +1 -1
- package/src/routes/admin/deals.ts +43 -34
- package/src/routes/admin/emails.ts +4 -6
- package/src/routes/admin/events.ts +128 -1
- package/src/routes/admin/groups.ts +34 -0
- package/src/routes/admin/impact.ts +19 -19
- package/src/routes/admin/targeting.ts +4 -1
- package/src/workflows/crm-reconcile.ts +1 -1
- package/src/middleware/auth.ts +0 -24
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@hogsend/engine",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.52.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -53,17 +53,17 @@
|
|
|
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.52.0",
|
|
57
|
+
"@hogsend/core": "^0.52.0",
|
|
58
|
+
"@hogsend/db": "^0.52.0",
|
|
59
|
+
"@hogsend/email": "^0.52.0",
|
|
60
|
+
"@hogsend/plugin-posthog": "^0.52.0",
|
|
61
|
+
"@hogsend/plugin-resend": "^0.52.0",
|
|
62
|
+
"@hogsend/sms": "^0.52.0"
|
|
63
63
|
},
|
|
64
64
|
"optionalDependencies": {
|
|
65
|
-
"@hogsend/plugin-postmark": "^0.
|
|
66
|
-
"@hogsend/plugin-twilio": "^0.
|
|
65
|
+
"@hogsend/plugin-postmark": "^0.52.0",
|
|
66
|
+
"@hogsend/plugin-twilio": "^0.52.0"
|
|
67
67
|
},
|
|
68
68
|
"devDependencies": {
|
|
69
69
|
"@types/node": "^22.15.3",
|
|
@@ -29,7 +29,6 @@ import {
|
|
|
29
29
|
} from "@hogsend/db";
|
|
30
30
|
import { type SQL, sql } from "drizzle-orm";
|
|
31
31
|
import type { PgColumn } from "drizzle-orm/pg-core";
|
|
32
|
-
import { campaignSendKeyPattern } from "../lib/campaign-send-key.js";
|
|
33
32
|
|
|
34
33
|
/**
|
|
35
34
|
* The v1 linked-identity map: connector id → the `contacts` column that holds
|
|
@@ -107,13 +106,13 @@ export function waveConditionSql(opts: {
|
|
|
107
106
|
}
|
|
108
107
|
|
|
109
108
|
/**
|
|
110
|
-
* Engagement over THIS campaign's prior deliveries
|
|
111
|
-
*
|
|
112
|
-
*
|
|
113
|
-
*
|
|
114
|
-
*
|
|
115
|
-
*
|
|
116
|
-
*
|
|
109
|
+
* Engagement over THIS campaign's prior deliveries, anchored on the indexed
|
|
110
|
+
* `campaign_id` column (stamped on every campaign-dispatched row regardless
|
|
111
|
+
* of key format; suppressed rows carry it too but have no engagement
|
|
112
|
+
* timestamps, so they can never match positively). Negative checks are NOT
|
|
113
|
+
* EXISTS of the same positive-engagement subquery, so `notOpened()` reads
|
|
114
|
+
* "no opened send of this campaign", including members who received nothing
|
|
115
|
+
* (e.g. suppressed on the prior wave).
|
|
117
116
|
*/
|
|
118
117
|
function engagementSql(
|
|
119
118
|
condition: EmailEngagementCondition,
|
|
@@ -129,7 +128,7 @@ function engagementSql(
|
|
|
129
128
|
: sql.empty();
|
|
130
129
|
const positive = sql`exists (
|
|
131
130
|
select 1 from ${emailSends}
|
|
132
|
-
where ${emailSends.
|
|
131
|
+
where ${emailSends.campaignId} = ${campaignId}
|
|
133
132
|
and ${emailSends.toEmail} = ${campaignRecipients.email}
|
|
134
133
|
and ${engagedAt} is not null${templateFilter}
|
|
135
134
|
)`;
|
package/src/container.ts
CHANGED
|
@@ -490,7 +490,7 @@ export interface HogsendClientOptions {
|
|
|
490
490
|
*/
|
|
491
491
|
conversionDestinations?: ConversionDestination[];
|
|
492
492
|
/**
|
|
493
|
-
* CRM sync providers
|
|
493
|
+
* CRM sync providers — the pluggable
|
|
494
494
|
* layer that pushes leads INTO client CRMs and lands pipeline stage changes
|
|
495
495
|
* + deal values back on the event spine as `funnel.stage_changed`. Register
|
|
496
496
|
* one (`provider`) or many (`providers`); each is webhook-served at
|
|
@@ -23,8 +23,8 @@ import type { OutboundEventName } from "../lib/outbound.js";
|
|
|
23
23
|
* NOTE: `defineDestination` is for event FAN-OUT to product/data tools
|
|
24
24
|
* (PostHog, Segment, Slack, a CRM, a warehouse). Ad-platform conversion
|
|
25
25
|
* forwarding (Meta CAPI, Google Enhanced Conversions) is Hogsend-native but
|
|
26
|
-
* lives in its own sibling layer (`defineConversionDestination
|
|
27
|
-
*
|
|
26
|
+
* lives in its own sibling layer (`defineConversionDestination`) — it needs
|
|
27
|
+
* identifier hashing, click-id
|
|
28
28
|
* joins, and deterministic event_id idempotency this generic pipe deliberately
|
|
29
29
|
* does not have. It is NOT deferred to any third-party CDP: the money path has
|
|
30
30
|
* no external dependency.
|
package/src/flags/reconcile.ts
CHANGED
|
@@ -117,10 +117,15 @@ export async function reconcileDefinedFlags(opts: {
|
|
|
117
117
|
}
|
|
118
118
|
|
|
119
119
|
// A same-key flag owned by an operator/Studio (origin != "code") is never
|
|
120
|
-
// clobbered by a code definition — leave it and warn.
|
|
120
|
+
// clobbered by a code definition — leave it and warn. The warn names the
|
|
121
|
+
// resolution because this is easy to trip innocently: `origin` defaults
|
|
122
|
+
// to "native" on insert, so any row seeded out-of-band (SQL, a seed
|
|
123
|
+
// script) for a code-defined key lands here on every boot.
|
|
121
124
|
if (existing.origin !== "code") {
|
|
122
125
|
logger.warn(
|
|
123
|
-
|
|
126
|
+
`flags: key "${key}" already owned by a non-code flag (origin "${existing.origin}") — leaving it untouched. ` +
|
|
127
|
+
"If this row should be code-owned (contract-synced from defineFlag), set origin = 'code' on it; " +
|
|
128
|
+
"otherwise remove the defineFlag that shares this key.",
|
|
124
129
|
{ key, origin: existing.origin },
|
|
125
130
|
);
|
|
126
131
|
result.skipped++;
|
package/src/index.ts
CHANGED
|
@@ -227,6 +227,11 @@ export {
|
|
|
227
227
|
buildJourneyGraph,
|
|
228
228
|
degradedGraphFromMeta,
|
|
229
229
|
} from "./journeys/graph/build-graph.js";
|
|
230
|
+
export {
|
|
231
|
+
type GroupScopeOption,
|
|
232
|
+
GroupScopeUnresolvableError,
|
|
233
|
+
resolveGroupScope,
|
|
234
|
+
} from "./journeys/group-scope.js";
|
|
230
235
|
export {
|
|
231
236
|
createMemoize,
|
|
232
237
|
deriveJourneyKey,
|
|
@@ -242,7 +247,10 @@ export {
|
|
|
242
247
|
registerRecordLabel,
|
|
243
248
|
runWithJourneyBoundary,
|
|
244
249
|
} from "./journeys/journey-boundary.js";
|
|
245
|
-
export {
|
|
250
|
+
export {
|
|
251
|
+
buildGroupEventFilter,
|
|
252
|
+
createJourneyContext,
|
|
253
|
+
} from "./journeys/journey-context.js";
|
|
246
254
|
// --- Journey transition log (journey_logs writer — Phase 2 per-stage metrics) ---
|
|
247
255
|
export {
|
|
248
256
|
type JourneyLogAction,
|
|
@@ -67,6 +67,12 @@ export interface EventPayloadInput {
|
|
|
67
67
|
userId: JsonValue;
|
|
68
68
|
userEmail: JsonValue;
|
|
69
69
|
properties: JsonValue;
|
|
70
|
+
/** The event's groupType→groupKey association map (`ingestEvent` pushes it
|
|
71
|
+
* on every event) — a group-scoped wait's trigger-association scope input. */
|
|
72
|
+
groups?: Record<string, string>;
|
|
73
|
+
/** The resolved subject contact row id (`ingestEvent` pushes it) — group
|
|
74
|
+
* membership auto-resolution input. */
|
|
75
|
+
contactId?: string;
|
|
70
76
|
[key: string]: JsonValue;
|
|
71
77
|
}
|
|
72
78
|
|
|
@@ -565,6 +571,15 @@ export async function executeJourneyRun(
|
|
|
565
571
|
journeyId: meta.id,
|
|
566
572
|
entryLimit: meta.entryLimit,
|
|
567
573
|
...(meta.entryPeriod ? { entryPeriod: meta.entryPeriod } : {}),
|
|
574
|
+
// Group-scope resolution inputs: the trigger event's association map
|
|
575
|
+
// (rides the task input, replay-stable) and the subject contact id —
|
|
576
|
+
// the pushed contactId when present, else the contact row already
|
|
577
|
+
// fetched for timezone above (best-effort: undefined only defers the
|
|
578
|
+
// resolver's no-contact throw to the membership leg).
|
|
579
|
+
...(input.groups ? { triggerGroups: input.groups } : {}),
|
|
580
|
+
...((input.contactId ?? contact?.id)
|
|
581
|
+
? { contactId: input.contactId ?? contact?.id }
|
|
582
|
+
: {}),
|
|
568
583
|
});
|
|
569
584
|
|
|
570
585
|
// The journey boundary makes journey side effects (sendEmail, ctx.trigger)
|
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
import { type Database, groupMemberships, groups } from "@hogsend/db";
|
|
2
|
+
import { and, eq, isNull } from "drizzle-orm";
|
|
3
|
+
import { readRecordedValue, recordOnce } from "./record-once.js";
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* Thrown when a group-scoped primitive cannot pin its scope to a single group
|
|
7
|
+
* key: the enrolled contact has no live membership of the requested type, has
|
|
8
|
+
* more than one (ambiguous), or no contact was resolvable at all. A loud throw
|
|
9
|
+
* (not a silent skip) — an unresolvable scope is an authoring/data problem the
|
|
10
|
+
* journey must surface, exactly like an intra-run key collision.
|
|
11
|
+
*/
|
|
12
|
+
export class GroupScopeUnresolvableError extends Error {
|
|
13
|
+
readonly journeyId: string;
|
|
14
|
+
readonly groupType: string;
|
|
15
|
+
|
|
16
|
+
constructor(opts: { journeyId: string; groupType: string; detail: string }) {
|
|
17
|
+
super(
|
|
18
|
+
`Journey "${opts.journeyId}" could not resolve a group scope for type ` +
|
|
19
|
+
`"${opts.groupType}": ${opts.detail}`,
|
|
20
|
+
);
|
|
21
|
+
this.name = "GroupScopeUnresolvableError";
|
|
22
|
+
this.journeyId = opts.journeyId;
|
|
23
|
+
this.groupType = opts.groupType;
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/** The `group` option as authored: a bare type (auto-resolve the key) or an
|
|
28
|
+
* explicit `{ type, key }` pin. */
|
|
29
|
+
export type GroupScopeOption = string | { type: string; key?: string };
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* Look up the contact's LIVE memberships of `type` and return the sole group
|
|
33
|
+
* key — throwing {@link GroupScopeUnresolvableError} on 0 or ≥2 rows (the
|
|
34
|
+
* count is named in the ambiguous message, so no LIMIT).
|
|
35
|
+
*/
|
|
36
|
+
async function lookupSoleMembership(opts: {
|
|
37
|
+
db: Database;
|
|
38
|
+
journeyId: string;
|
|
39
|
+
type: string;
|
|
40
|
+
contactId: string | undefined;
|
|
41
|
+
}): Promise<string> {
|
|
42
|
+
const { db, journeyId, type, contactId } = opts;
|
|
43
|
+
if (!contactId) {
|
|
44
|
+
throw new GroupScopeUnresolvableError({
|
|
45
|
+
journeyId,
|
|
46
|
+
groupType: type,
|
|
47
|
+
detail:
|
|
48
|
+
"no membership — no contact was resolvable for this enrollment, so " +
|
|
49
|
+
"membership auto-resolution has nothing to look up",
|
|
50
|
+
});
|
|
51
|
+
}
|
|
52
|
+
const rows = await db
|
|
53
|
+
.select({ groupKey: groups.groupKey })
|
|
54
|
+
.from(groupMemberships)
|
|
55
|
+
.innerJoin(groups, eq(groupMemberships.groupId, groups.id))
|
|
56
|
+
.where(
|
|
57
|
+
and(
|
|
58
|
+
eq(groupMemberships.contactId, contactId),
|
|
59
|
+
eq(groups.groupType, type),
|
|
60
|
+
isNull(groups.deletedAt),
|
|
61
|
+
),
|
|
62
|
+
);
|
|
63
|
+
const sole = rows[0];
|
|
64
|
+
if (rows.length === 1 && sole) {
|
|
65
|
+
return sole.groupKey;
|
|
66
|
+
}
|
|
67
|
+
if (rows.length === 0) {
|
|
68
|
+
throw new GroupScopeUnresolvableError({
|
|
69
|
+
journeyId,
|
|
70
|
+
groupType: type,
|
|
71
|
+
detail: `no membership — the contact belongs to no live "${type}" group`,
|
|
72
|
+
});
|
|
73
|
+
}
|
|
74
|
+
throw new GroupScopeUnresolvableError({
|
|
75
|
+
journeyId,
|
|
76
|
+
groupType: type,
|
|
77
|
+
detail: `ambiguous: ${rows.length} memberships of type "${type}"`,
|
|
78
|
+
});
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/**
|
|
82
|
+
* Resolve a `group` option to a concrete replay-stable `{ type, key }` scope.
|
|
83
|
+
* Resolution order (DECISIONS §3.3) — EXACTLY this sequence:
|
|
84
|
+
*
|
|
85
|
+
* 1. **Explicit key** (`{ type, key }`): returned verbatim, NEVER recorded —
|
|
86
|
+
* it wins even over a recorded `__groupKeys__[type]`, and two same-type
|
|
87
|
+
* call sites with different explicit keys stay independent.
|
|
88
|
+
* 2. **Trigger association** (`triggerGroups[type]`): returned, NOT recorded —
|
|
89
|
+
* it rides the task input, so it is replay-stable by construction.
|
|
90
|
+
* 3. **Recorded** `journey_states.context.__groupKeys__[type]`: returned
|
|
91
|
+
* verbatim (only ever holds membership-resolved keys).
|
|
92
|
+
* 4. **Sole live membership**: exactly one live membership of `type` → its
|
|
93
|
+
* key, RECORDED under `__groupKeys__[type]` via `recordOnce` (read-back
|
|
94
|
+
* semantics converge concurrent racers — the committed value is returned,
|
|
95
|
+
* never the locally computed one). 0 or ≥2 rows → throw
|
|
96
|
+
* {@link GroupScopeUnresolvableError}.
|
|
97
|
+
*
|
|
98
|
+
* `record: false` (future ctx.history use) keeps the order identical but step
|
|
99
|
+
* 4 resolves WITHOUT writing.
|
|
100
|
+
*/
|
|
101
|
+
export async function resolveGroupScope(opts: {
|
|
102
|
+
db: Database;
|
|
103
|
+
stateId: string;
|
|
104
|
+
journeyId: string;
|
|
105
|
+
contactId: string | undefined;
|
|
106
|
+
triggerGroups: Record<string, string> | undefined;
|
|
107
|
+
option: GroupScopeOption;
|
|
108
|
+
record?: boolean;
|
|
109
|
+
}): Promise<{ type: string; key: string }> {
|
|
110
|
+
const { db, stateId, journeyId, contactId, triggerGroups, option } = opts;
|
|
111
|
+
const record = opts.record ?? true;
|
|
112
|
+
const type = typeof option === "string" ? option : option.type;
|
|
113
|
+
|
|
114
|
+
// 1. Explicit key — verbatim, never recorded.
|
|
115
|
+
if (typeof option === "object" && option.key !== undefined) {
|
|
116
|
+
return { type, key: option.key };
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
// 2. Trigger association — replay-stable via the task input, not recorded.
|
|
120
|
+
const triggered = triggerGroups?.[type];
|
|
121
|
+
if (triggered !== undefined) {
|
|
122
|
+
return { type, key: triggered };
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
if (record) {
|
|
126
|
+
// 3+4. recordOnce's read-first IS step 3 (a recorded key returns without
|
|
127
|
+
// computing); its compute IS step 4 (the membership lookup, throwing when
|
|
128
|
+
// unresolvable — nothing is written on a throw). The returned value is
|
|
129
|
+
// the committed read-back, so concurrent racers converge.
|
|
130
|
+
const key = await recordOnce({
|
|
131
|
+
db,
|
|
132
|
+
stateId,
|
|
133
|
+
namespace: "__groupKeys__",
|
|
134
|
+
key: type,
|
|
135
|
+
compute: () => lookupSoleMembership({ db, journeyId, type, contactId }),
|
|
136
|
+
});
|
|
137
|
+
return { type, key };
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
// record: false — same order, no write. 3: read the recorded bag directly.
|
|
141
|
+
const recorded = await readRecordedValue({
|
|
142
|
+
db,
|
|
143
|
+
stateId,
|
|
144
|
+
namespace: "__groupKeys__",
|
|
145
|
+
key: type,
|
|
146
|
+
});
|
|
147
|
+
if (recorded !== undefined) {
|
|
148
|
+
return { type, key: recorded as string };
|
|
149
|
+
}
|
|
150
|
+
// 4 without the record.
|
|
151
|
+
const key = await lookupSoleMembership({ db, journeyId, type, contactId });
|
|
152
|
+
return { type, key };
|
|
153
|
+
}
|
|
@@ -62,6 +62,7 @@ import {
|
|
|
62
62
|
JOURNEY_EXECUTION_TIMEOUT_HOURS,
|
|
63
63
|
} from "./constants.js";
|
|
64
64
|
import { JourneyExitedError } from "./errors.js";
|
|
65
|
+
import { type GroupScopeOption, resolveGroupScope } from "./group-scope.js";
|
|
65
66
|
import {
|
|
66
67
|
deriveJourneyKey,
|
|
67
68
|
getJourneyBoundary,
|
|
@@ -69,7 +70,7 @@ import {
|
|
|
69
70
|
registerRecordLabel,
|
|
70
71
|
} from "./journey-boundary.js";
|
|
71
72
|
import { logTransition } from "./journey-log.js";
|
|
72
|
-
import { recordOnce } from "./record-once.js";
|
|
73
|
+
import { readRecordedValue, recordOnce } from "./record-once.js";
|
|
73
74
|
|
|
74
75
|
/** Journey statuses that are terminal — a journey in any of these must never be
|
|
75
76
|
* resurrected back to "active" by a wait resuming. Exported so the durable task
|
|
@@ -122,6 +123,21 @@ function celStringLiteral(value: string): string {
|
|
|
122
123
|
return `'${value.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
|
|
123
124
|
}
|
|
124
125
|
|
|
126
|
+
/**
|
|
127
|
+
* CEL filter for a group-scoped wait: matches an event whose pushed payload
|
|
128
|
+
* carries the group association `groups[type] == key`. Membership is tested
|
|
129
|
+
* before indexing so an event with no `groups` map (an older producer) can
|
|
130
|
+
* never error the expression; both literals go through `celStringLiteral` so
|
|
131
|
+
* an externally-supplied type/key cannot break out of the filter.
|
|
132
|
+
*/
|
|
133
|
+
export function buildGroupEventFilter(type: string, key: string): string {
|
|
134
|
+
const typeLit = celStringLiteral(type);
|
|
135
|
+
return (
|
|
136
|
+
`'groups' in input && ${typeLit} in input.groups && ` +
|
|
137
|
+
`input.groups[${typeLit}] == ${celStringLiteral(key)}`
|
|
138
|
+
);
|
|
139
|
+
}
|
|
140
|
+
|
|
125
141
|
/** SQL eq-pushdown predicates for a `where` — a COARSE narrowing pre-filter,
|
|
126
142
|
* never the verdict: jsonb `->>` extracts TEXT (a stored string "50"
|
|
127
143
|
* text-matches `.eq(50)`), so every consumer MUST re-verify fetched rows with
|
|
@@ -186,6 +202,13 @@ interface JourneyContextConfig {
|
|
|
186
202
|
entryLimit?: "once" | "once_per_period" | "unlimited";
|
|
187
203
|
/** The journey's entry period (for `once_per_period`). */
|
|
188
204
|
entryPeriod?: DurationObject;
|
|
205
|
+
/** The trigger event's groupType→groupKey association map (rides the task
|
|
206
|
+
* input, so replay-stable) — group-scope resolution leg 2. */
|
|
207
|
+
triggerGroups?: Record<string, string>;
|
|
208
|
+
/** The enrolled contact's row id — group membership auto-resolution
|
|
209
|
+
* (leg 4). Undefined defers to the resolver's no-contact throw, which
|
|
210
|
+
* only fires when that leg is actually reached. */
|
|
211
|
+
contactId?: string;
|
|
189
212
|
}
|
|
190
213
|
|
|
191
214
|
export function createJourneyContext(
|
|
@@ -355,7 +378,42 @@ export function createJourneyContext(
|
|
|
355
378
|
nodeId: string,
|
|
356
379
|
where: PropertyCondition[],
|
|
357
380
|
lookback?: DurationObject,
|
|
381
|
+
// When present, the wait matches ANY member's event carrying this group
|
|
382
|
+
// association instead of the enrolled user's events (both the SQL scan
|
|
383
|
+
// and the live CEL filter swap their user predicate for the group one).
|
|
384
|
+
groupScope?: { type: string; key: string },
|
|
358
385
|
): Promise<WaitForEventResult> => {
|
|
386
|
+
// Terminal mark (the digest pattern): the recorded outcome — NOT the
|
|
387
|
+
// deadline — is what makes this wait replay-stable. `waitDeadline` is a
|
|
388
|
+
// shared column cleared at resolution so the NEXT wait site can mint its
|
|
389
|
+
// own, which means a replay-from-top of an ALREADY-RESOLVED wait re-derives
|
|
390
|
+
// a shifted scan window in which the resolving row is typically invisible —
|
|
391
|
+
// a re-armed wait could then flip to the timeout branch (duplicate-but-
|
|
392
|
+
// different sends downstream: the exact divergence class this engine's
|
|
393
|
+
// replay-safety design forbids). So the outcome is frozen set-once under
|
|
394
|
+
// `__waits__` and a replay returns it verbatim before touching the
|
|
395
|
+
// deadline. Registering the label makes an intra-run duplicate wait label
|
|
396
|
+
// a loud authoring error instead of a silent stale-outcome replay.
|
|
397
|
+
registerRecordLabel(getJourneyBoundary(), `wait:${nodeId}`);
|
|
398
|
+
const outcomeKey = `${nodeId}:result`;
|
|
399
|
+
const priorOutcome = await readRecordedValue({
|
|
400
|
+
db,
|
|
401
|
+
stateId,
|
|
402
|
+
namespace: "__waits__",
|
|
403
|
+
key: outcomeKey,
|
|
404
|
+
});
|
|
405
|
+
if (priorOutcome !== undefined) {
|
|
406
|
+
return priorOutcome as WaitForEventResult;
|
|
407
|
+
}
|
|
408
|
+
const recordOutcome = (o: WaitForEventResult) =>
|
|
409
|
+
recordOnce({
|
|
410
|
+
db,
|
|
411
|
+
stateId,
|
|
412
|
+
namespace: "__waits__",
|
|
413
|
+
key: outcomeKey,
|
|
414
|
+
compute: () => o,
|
|
415
|
+
});
|
|
416
|
+
|
|
359
417
|
// Durable deadline: read-first / set-once.
|
|
360
418
|
const stateRow = await db
|
|
361
419
|
.select({ waitDeadline: journeyStates.waitDeadline })
|
|
@@ -393,15 +451,23 @@ export function createJourneyContext(
|
|
|
393
451
|
// Narrowing only — `scanForMatch` re-verifies every row in JS.
|
|
394
452
|
const eqPreds = eqPushdownPreds(where);
|
|
395
453
|
|
|
396
|
-
const scanForMatch = async (): Promise<
|
|
397
|
-
WaitForEventResult["properties"]
|
|
398
|
-
|
|
454
|
+
const scanForMatch = async (): Promise<{
|
|
455
|
+
properties: NonNullable<WaitForEventResult["properties"]>;
|
|
456
|
+
actorUserId: string;
|
|
457
|
+
} | null> => {
|
|
399
458
|
const recent = await db
|
|
400
|
-
.select({
|
|
459
|
+
.select({
|
|
460
|
+
properties: userEvents.properties,
|
|
461
|
+
userId: userEvents.userId,
|
|
462
|
+
})
|
|
401
463
|
.from(userEvents)
|
|
402
464
|
.where(
|
|
403
465
|
and(
|
|
404
|
-
|
|
466
|
+
// Group scope matches ANY member's row via the persisted
|
|
467
|
+
// association map; user scope keeps the enrolled-user predicate.
|
|
468
|
+
groupScope
|
|
469
|
+
? sql`${userEvents.groups} ->> ${groupScope.type} = ${groupScope.key}`
|
|
470
|
+
: eq(userEvents.userId, userId),
|
|
405
471
|
eq(userEvents.event, event),
|
|
406
472
|
gte(userEvents.occurredAt, scanSince),
|
|
407
473
|
...eqPreds,
|
|
@@ -417,7 +483,7 @@ export function createJourneyContext(
|
|
|
417
483
|
if (
|
|
418
484
|
evaluatePropertyConditions({ conditions: where, properties: props })
|
|
419
485
|
) {
|
|
420
|
-
return narrowScalars(props);
|
|
486
|
+
return { properties: narrowScalars(props), actorUserId: row.userId };
|
|
421
487
|
}
|
|
422
488
|
}
|
|
423
489
|
return null;
|
|
@@ -427,7 +493,7 @@ export function createJourneyContext(
|
|
|
427
493
|
const preHit = await scanForMatch();
|
|
428
494
|
if (preHit) {
|
|
429
495
|
await clearDeadline();
|
|
430
|
-
return { timedOut: false,
|
|
496
|
+
return recordOutcome({ timedOut: false, ...preHit });
|
|
431
497
|
}
|
|
432
498
|
|
|
433
499
|
await enterWait(nodeId, "wait");
|
|
@@ -436,7 +502,7 @@ export function createJourneyContext(
|
|
|
436
502
|
while (true) {
|
|
437
503
|
const hit = await scanForMatch();
|
|
438
504
|
if (hit) {
|
|
439
|
-
outcome = { timedOut: false,
|
|
505
|
+
outcome = { timedOut: false, ...hit };
|
|
440
506
|
break;
|
|
441
507
|
}
|
|
442
508
|
|
|
@@ -462,7 +528,9 @@ export function createJourneyContext(
|
|
|
462
528
|
Or(
|
|
463
529
|
new UserEventCondition(
|
|
464
530
|
event,
|
|
465
|
-
|
|
531
|
+
groupScope
|
|
532
|
+
? buildGroupEventFilter(groupScope.type, groupScope.key)
|
|
533
|
+
: `input.userId == ${celStringLiteral(userId)}`,
|
|
466
534
|
"event",
|
|
467
535
|
),
|
|
468
536
|
new SleepCondition(toSleepDuration(remainingMs), "timeout"),
|
|
@@ -474,9 +542,7 @@ export function createJourneyContext(
|
|
|
474
542
|
// Timeout branch — one final scan for an event landing exactly as the
|
|
475
543
|
// sleep expired, then conclude.
|
|
476
544
|
const last = await scanForMatch();
|
|
477
|
-
outcome = last
|
|
478
|
-
? { timedOut: false, properties: last }
|
|
479
|
-
: { timedOut: true };
|
|
545
|
+
outcome = last ? { timedOut: false, ...last } : { timedOut: true };
|
|
480
546
|
break;
|
|
481
547
|
}
|
|
482
548
|
// Event branch: loop — the next scan picks up the (already persisted) row
|
|
@@ -485,7 +551,7 @@ export function createJourneyContext(
|
|
|
485
551
|
|
|
486
552
|
await resumeFromWait(nodeId, { timedOut: outcome.timedOut });
|
|
487
553
|
await clearDeadline();
|
|
488
|
-
return outcome;
|
|
554
|
+
return recordOutcome(outcome);
|
|
489
555
|
};
|
|
490
556
|
|
|
491
557
|
// Durably wait for THIS user's `event` OR `timeout`, whichever fires first,
|
|
@@ -496,6 +562,7 @@ export function createJourneyContext(
|
|
|
496
562
|
nodeId: string,
|
|
497
563
|
lookback?: DurationObject,
|
|
498
564
|
where?: PropertyCondition[],
|
|
565
|
+
group?: GroupScopeOption,
|
|
499
566
|
): Promise<WaitForEventResult> => {
|
|
500
567
|
// Reject a timeout longer than the journey task's executionTimeout up front
|
|
501
568
|
// so it fails fast at authoring time. (Eviction-capable engines may allow
|
|
@@ -512,15 +579,34 @@ export function createJourneyContext(
|
|
|
512
579
|
// it — set it before dispatching to either wait path.
|
|
513
580
|
setBoundaryLabel(nodeId);
|
|
514
581
|
|
|
582
|
+
// A group-scoped wait resolves its scope ONCE, up front (explicit key →
|
|
583
|
+
// trigger association → recorded → sole membership; recordOnce is DB-only,
|
|
584
|
+
// so this issues no durable journal node), and ALWAYS takes the filtered
|
|
585
|
+
// leg — the legacy leg below has no re-arm scan and no timeout final scan.
|
|
586
|
+
// An empty `where` there is vacuous (`evaluatePropertyConditions` is
|
|
587
|
+
// Array.every; `eqPushdownPreds([])` is empty).
|
|
588
|
+
let groupScope: { type: string; key: string } | undefined;
|
|
589
|
+
if (group) {
|
|
590
|
+
groupScope = await resolveGroupScope({
|
|
591
|
+
db,
|
|
592
|
+
stateId,
|
|
593
|
+
journeyId: config.journeyId ?? "unknown",
|
|
594
|
+
contactId: config.contactId,
|
|
595
|
+
triggerGroups: config.triggerGroups,
|
|
596
|
+
option: group,
|
|
597
|
+
});
|
|
598
|
+
}
|
|
599
|
+
|
|
515
600
|
// WHERE-filtered wait takes the durable re-arm path; an empty/absent `where`
|
|
516
601
|
// keeps the exact legacy single-wait below byte-for-byte.
|
|
517
|
-
if (where && where.length > 0) {
|
|
602
|
+
if (groupScope || (where && where.length > 0)) {
|
|
518
603
|
return performFilteredWaitForEvent(
|
|
519
604
|
event,
|
|
520
605
|
timeout,
|
|
521
606
|
nodeId,
|
|
522
|
-
where,
|
|
607
|
+
where ?? [],
|
|
523
608
|
lookback,
|
|
609
|
+
groupScope,
|
|
524
610
|
);
|
|
525
611
|
}
|
|
526
612
|
|
|
@@ -570,6 +656,8 @@ export function createJourneyContext(
|
|
|
570
656
|
timedOut: false,
|
|
571
657
|
properties: scalars,
|
|
572
658
|
...(occurredAt ? { occurredAt } : {}),
|
|
659
|
+
// Lookback rows are user-scoped, so the actor IS the enrolled user.
|
|
660
|
+
actorUserId: userId,
|
|
573
661
|
};
|
|
574
662
|
}
|
|
575
663
|
}
|
|
@@ -603,6 +691,7 @@ export function createJourneyContext(
|
|
|
603
691
|
// ({ userId, userEmail, properties }); the pre-eviction path may hand the
|
|
604
692
|
// payload back un-wrapped — tolerate both, mirroring the CREATE-strip.
|
|
605
693
|
let properties: WaitForEventResult["properties"];
|
|
694
|
+
let actorUserId: string | undefined;
|
|
606
695
|
if (!timedOut) {
|
|
607
696
|
const matches = fired.event;
|
|
608
697
|
const first = Array.isArray(matches) ? matches[0] : matches;
|
|
@@ -621,6 +710,13 @@ export function createJourneyContext(
|
|
|
621
710
|
) {
|
|
622
711
|
properties = candidate as NonNullable<WaitForEventResult["properties"]>;
|
|
623
712
|
}
|
|
713
|
+
// This leg's CEL filter is user-scoped, so the actor is the enrolled
|
|
714
|
+
// user; prefer the fired payload's top-level `userId` when carried.
|
|
715
|
+
const actor =
|
|
716
|
+
payload && typeof payload === "object" && "userId" in payload
|
|
717
|
+
? (payload as { userId?: unknown }).userId
|
|
718
|
+
: undefined;
|
|
719
|
+
actorUserId = typeof actor === "string" ? actor : userId;
|
|
624
720
|
}
|
|
625
721
|
|
|
626
722
|
await resumeFromWait(nodeId, { timedOut });
|
|
@@ -628,7 +724,11 @@ export function createJourneyContext(
|
|
|
628
724
|
// reads a replay-stable instant (eviction engine) rather than the seed.
|
|
629
725
|
await refreshNow();
|
|
630
726
|
|
|
631
|
-
return {
|
|
727
|
+
return {
|
|
728
|
+
timedOut,
|
|
729
|
+
...(properties ? { properties } : {}),
|
|
730
|
+
...(actorUserId ? { actorUserId } : {}),
|
|
731
|
+
};
|
|
632
732
|
};
|
|
633
733
|
|
|
634
734
|
// Scan the digest window ONCE at flush: all `event` rows for THIS user in
|
|
@@ -1046,13 +1146,14 @@ export function createJourneyContext(
|
|
|
1046
1146
|
);
|
|
1047
1147
|
},
|
|
1048
1148
|
|
|
1049
|
-
async waitForEvent({ event, timeout, label, lookback, where }) {
|
|
1149
|
+
async waitForEvent({ event, timeout, label, lookback, where, group }) {
|
|
1050
1150
|
return performWaitForEvent(
|
|
1051
1151
|
event,
|
|
1052
1152
|
timeout,
|
|
1053
1153
|
label ?? `wait-event:${event}`,
|
|
1054
1154
|
lookback,
|
|
1055
1155
|
normalizeWhere(where),
|
|
1156
|
+
group,
|
|
1056
1157
|
);
|
|
1057
1158
|
},
|
|
1058
1159
|
|
|
@@ -1211,7 +1312,39 @@ export function createJourneyContext(
|
|
|
1211
1312
|
},
|
|
1212
1313
|
|
|
1213
1314
|
history: {
|
|
1214
|
-
async hasEvent({ userId: targetUserId, event, within }) {
|
|
1315
|
+
async hasEvent({ userId: targetUserId, event, within, group }) {
|
|
1316
|
+
// Group REPLACES the userId scoping: count rows via the persisted
|
|
1317
|
+
// association map (same jsonb predicate as the wait scan). Resolution
|
|
1318
|
+
// is READ-ONLY (`record: false`) — a history read never writes
|
|
1319
|
+
// `__groupKeys__`.
|
|
1320
|
+
if (group) {
|
|
1321
|
+
const scope = await resolveGroupScope({
|
|
1322
|
+
db,
|
|
1323
|
+
stateId,
|
|
1324
|
+
journeyId: config.journeyId ?? "unknown",
|
|
1325
|
+
contactId: config.contactId,
|
|
1326
|
+
triggerGroups: config.triggerGroups,
|
|
1327
|
+
option: group,
|
|
1328
|
+
record: false,
|
|
1329
|
+
});
|
|
1330
|
+
const [row] = await db
|
|
1331
|
+
.select({ count: sql<number>`count(*)` })
|
|
1332
|
+
.from(userEvents)
|
|
1333
|
+
.where(
|
|
1334
|
+
and(
|
|
1335
|
+
sql`${userEvents.groups} ->> ${scope.type} = ${scope.key}`,
|
|
1336
|
+
eq(userEvents.event, event),
|
|
1337
|
+
within
|
|
1338
|
+
? gte(
|
|
1339
|
+
userEvents.occurredAt,
|
|
1340
|
+
new Date(Date.now() - durationToMs(within)),
|
|
1341
|
+
)
|
|
1342
|
+
: undefined,
|
|
1343
|
+
),
|
|
1344
|
+
);
|
|
1345
|
+
const total = Number(row?.count ?? 0);
|
|
1346
|
+
return { found: total > 0, count: total };
|
|
1347
|
+
}
|
|
1215
1348
|
const result = await evaluateEventCondition({
|
|
1216
1349
|
condition: {
|
|
1217
1350
|
type: "event",
|