@hogsend/engine 0.46.1 → 0.51.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/README.md +6 -0
- package/package.json +13 -10
- package/src/campaigns/cohort-sql.ts +8 -9
- package/src/connectors/presets/index.ts +8 -2
- package/src/container.ts +150 -8
- package/src/destinations/define-destination.ts +2 -2
- package/src/destinations/presets/posthog.ts +7 -0
- package/src/destinations/presets/segment.ts +5 -0
- package/src/env.ts +38 -0
- package/src/flags/reconcile.ts +200 -0
- package/src/index.ts +79 -0
- package/src/journeys/authoring.ts +32 -0
- package/src/journeys/define-journey.ts +45 -40
- package/src/journeys/execute-journey-run.ts +73 -32
- package/src/journeys/journey-boundary.ts +76 -0
- package/src/journeys/journey-context.ts +128 -70
- package/src/journeys/journey-task-factory.ts +31 -0
- package/src/journeys/journey-task-runtime.ts +31 -0
- package/src/journeys/journey-version.test.ts +236 -0
- package/src/journeys/journey-version.ts +158 -0
- package/src/journeys/record-once.ts +28 -2
- package/src/lib/campaign-send-key.ts +9 -18
- package/src/lib/connector-actions.test.ts +36 -0
- package/src/lib/connector-actions.ts +42 -4
- package/src/lib/contacts.ts +49 -0
- package/src/lib/conversions.test.ts +33 -0
- package/src/lib/conversions.ts +9 -1
- package/src/lib/crm-deals.ts +1 -1
- package/src/lib/crm-ingest.ts +1 -1
- package/src/lib/email.ts +23 -2
- package/src/lib/enrollment-policy.ts +51 -0
- package/src/lib/event-names.ts +7 -1
- package/src/lib/feed.ts +55 -3
- package/src/lib/flags-registry.ts +48 -0
- package/src/lib/flags.ts +498 -0
- package/src/lib/frequency-cap.ts +4 -2
- package/src/lib/funnel-progress.ts +1 -1
- package/src/lib/fx.ts +374 -0
- package/src/lib/global-control-readout.ts +166 -0
- package/src/lib/groups.ts +362 -0
- package/src/lib/holdout.ts +1 -1
- package/src/lib/ingestion.ts +38 -0
- package/src/lib/journey-lift.ts +142 -0
- package/src/lib/journey-suppress.ts +4 -2
- package/src/lib/lift-stats.ts +2 -2
- package/src/lib/operator-settings.ts +71 -0
- package/src/lib/outbound.ts +147 -0
- package/src/lib/preferences.ts +6 -80
- package/src/lib/recipient-preferences.ts +53 -0
- package/src/lib/sms.ts +21 -2
- package/src/lib/stable-stringify.test.ts +42 -0
- package/src/lib/stable-stringify.ts +23 -0
- package/src/lib/tracked.ts +9 -2
- package/src/lib/variant.ts +99 -0
- package/src/lib/webhook-signing.ts +16 -1
- package/src/lists/registry.ts +6 -2
- package/src/lists/subscription.ts +13 -0
- package/src/routes/admin/attribution.ts +1 -2
- package/src/routes/admin/campaigns.ts +84 -45
- package/src/routes/admin/contacts.ts +53 -4
- package/src/routes/admin/conversions.ts +138 -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/flags.ts +369 -0
- package/src/routes/admin/groups.ts +900 -0
- package/src/routes/admin/impact-schemas.ts +44 -0
- package/src/routes/admin/impact-wire.test.ts +181 -0
- package/src/routes/admin/impact.ts +486 -0
- package/src/routes/admin/index.ts +12 -0
- package/src/routes/admin/journey-impact.ts +446 -0
- package/src/routes/admin/journeys.ts +70 -100
- package/src/routes/admin/settings.ts +145 -0
- package/src/routes/admin/targeting.ts +259 -0
- package/src/routes/events/index.ts +11 -0
- package/src/routes/flags/index.ts +120 -0
- package/src/routes/groups/index.ts +417 -0
- package/src/routes/index.ts +23 -1
- package/src/testing.ts +25 -0
- package/src/webhook-sources/presets/index.ts +5 -1
- package/src/webhook-sources/presets/intercom.ts +230 -0
- package/src/webhook-sources/presets/segment.ts +56 -4
- package/src/worker.ts +3 -0
- package/src/workflows/bucket-backfill.ts +1 -14
- package/src/workflows/crm-reconcile.ts +1 -1
- package/src/workflows/impact-digest.ts +761 -0
- package/src/workflows/journey-blueprint-interpreter.ts +18 -1
- package/src/middleware/auth.ts +0 -24
|
@@ -1,10 +1,6 @@
|
|
|
1
1
|
import type { Conditions } from "@hatchet-dev/typescript-sdk/v1/index.js";
|
|
2
2
|
import type { JsonValue } from "@hatchet-dev/typescript-sdk/v1/types.js";
|
|
3
|
-
import {
|
|
4
|
-
type DurationObject,
|
|
5
|
-
durationToMs,
|
|
6
|
-
evaluatePropertyConditions,
|
|
7
|
-
} from "@hogsend/core";
|
|
3
|
+
import { type DurationObject, durationToMs } from "@hogsend/core";
|
|
8
4
|
import type {
|
|
9
5
|
JourneyMeta,
|
|
10
6
|
JourneyRunFn,
|
|
@@ -24,6 +20,7 @@ import {
|
|
|
24
20
|
checkEmailPreferences,
|
|
25
21
|
checkEntryLimit,
|
|
26
22
|
} from "../lib/enrollment-guards.js";
|
|
23
|
+
import { evaluateEnrollmentPolicy } from "../lib/enrollment-policy.js";
|
|
27
24
|
import { hatchet } from "../lib/hatchet.js";
|
|
28
25
|
import { isHeldOut } from "../lib/holdout.js";
|
|
29
26
|
import { ingestEvent } from "../lib/ingestion.js";
|
|
@@ -40,6 +37,7 @@ import {
|
|
|
40
37
|
} from "./journey-boundary.js";
|
|
41
38
|
import { createJourneyContext, TERMINAL_STATUSES } from "./journey-context.js";
|
|
42
39
|
import { logTransition } from "./journey-log.js";
|
|
40
|
+
import { stripRecordNamespaces } from "./record-once.js";
|
|
43
41
|
import { getJourneyRegistrySingleton } from "./registry-singleton.js";
|
|
44
42
|
|
|
45
43
|
const logger = createLogger(process.env.LOG_LEVEL);
|
|
@@ -134,6 +132,15 @@ export async function insertEnrollment(opts: {
|
|
|
134
132
|
* lock-free (the default).
|
|
135
133
|
*/
|
|
136
134
|
serializeWithGraphLock?: boolean;
|
|
135
|
+
/**
|
|
136
|
+
* Content fingerprint + label of the definition this enrollment enters
|
|
137
|
+
* under (meta.versionHash / meta.version). Stamped once here; never
|
|
138
|
+
* updated — no UPDATE path in the engine ever touches the version
|
|
139
|
+
* columns. Optional for API back-compat (dogfood tests call this
|
|
140
|
+
* directly); executeJourneyRun always passes them.
|
|
141
|
+
*/
|
|
142
|
+
journeyVersionHash?: string | null;
|
|
143
|
+
journeyVersionLabel?: string | null;
|
|
137
144
|
}): Promise<JourneyStateRow | undefined> {
|
|
138
145
|
const values = {
|
|
139
146
|
userId: opts.userId,
|
|
@@ -143,6 +150,8 @@ export async function insertEnrollment(opts: {
|
|
|
143
150
|
status: "active" as const,
|
|
144
151
|
context: opts.context,
|
|
145
152
|
hatchetRunId: opts.hatchetRunId,
|
|
153
|
+
journeyVersionHash: opts.journeyVersionHash ?? null,
|
|
154
|
+
journeyVersionLabel: opts.journeyVersionLabel ?? null,
|
|
146
155
|
};
|
|
147
156
|
const onConflict = {
|
|
148
157
|
target: [journeyStates.userId, journeyStates.journeyId],
|
|
@@ -266,6 +275,7 @@ export async function executeJourneyRun(
|
|
|
266
275
|
// subscription via `ctx.guard.isSubscribed()` after every wait, so
|
|
267
276
|
// bypassing the entry-time preference gate never emails an unsubscriber.)
|
|
268
277
|
if (!state) {
|
|
278
|
+
// Preserve the cheap first gate: disabled definitions never touch the DB.
|
|
269
279
|
if (!meta.enabled) {
|
|
270
280
|
return { status: "skipped", reason: "journey_disabled" };
|
|
271
281
|
}
|
|
@@ -273,19 +283,15 @@ export async function executeJourneyRun(
|
|
|
273
283
|
const configOverride = await db.query.journeyConfigs.findFirst({
|
|
274
284
|
where: eq(journeyConfigs.journeyId, meta.id),
|
|
275
285
|
});
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
})
|
|
286
|
-
) {
|
|
287
|
-
return { status: "skipped", reason: "trigger_conditions_not_met" };
|
|
288
|
-
}
|
|
286
|
+
const basePolicy = evaluateEnrollmentPolicy({
|
|
287
|
+
journey: meta,
|
|
288
|
+
properties,
|
|
289
|
+
facts: {
|
|
290
|
+
...(configOverride ? { adminEnabled: configOverride.enabled } : {}),
|
|
291
|
+
},
|
|
292
|
+
});
|
|
293
|
+
if (!basePolicy.allowed) {
|
|
294
|
+
return { status: "skipped", reason: basePolicy.reason };
|
|
289
295
|
}
|
|
290
296
|
|
|
291
297
|
const entryAllowed = await checkEntryLimit({
|
|
@@ -293,16 +299,23 @@ export async function executeJourneyRun(
|
|
|
293
299
|
journey: meta,
|
|
294
300
|
userId,
|
|
295
301
|
});
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
302
|
+
const entryPolicy = evaluateEnrollmentPolicy({
|
|
303
|
+
journey: meta,
|
|
304
|
+
properties,
|
|
305
|
+
facts: { entry: entryAllowed },
|
|
306
|
+
});
|
|
307
|
+
if (!entryPolicy.allowed) {
|
|
308
|
+
return { status: "skipped", reason: entryPolicy.reason };
|
|
301
309
|
}
|
|
302
310
|
|
|
303
311
|
const prefs = await checkEmailPreferences({ db, userId });
|
|
304
|
-
|
|
305
|
-
|
|
312
|
+
const preferencePolicy = evaluateEnrollmentPolicy({
|
|
313
|
+
journey: meta,
|
|
314
|
+
properties,
|
|
315
|
+
facts: { unsubscribed: prefs.unsubscribed },
|
|
316
|
+
});
|
|
317
|
+
if (!preferencePolicy.allowed) {
|
|
318
|
+
return { status: "skipped", reason: preferencePolicy.reason };
|
|
306
319
|
}
|
|
307
320
|
|
|
308
321
|
// HOLDOUT DIVERSION (impact plan §4.1) — deliberately LAST in the guard
|
|
@@ -320,7 +333,12 @@ export async function executeJourneyRun(
|
|
|
320
333
|
percent: meta.holdout.percent,
|
|
321
334
|
salt: meta.holdout.salt,
|
|
322
335
|
});
|
|
323
|
-
|
|
336
|
+
const holdoutPolicy = evaluateEnrollmentPolicy({
|
|
337
|
+
journey: meta,
|
|
338
|
+
properties,
|
|
339
|
+
facts: { heldOut: diverted },
|
|
340
|
+
});
|
|
341
|
+
if (!holdoutPolicy.allowed) {
|
|
324
342
|
const priorHoldout = await db.query.journeyStates.findFirst({
|
|
325
343
|
where: and(
|
|
326
344
|
eq(journeyStates.userId, userId),
|
|
@@ -338,7 +356,17 @@ export async function executeJourneyRun(
|
|
|
338
356
|
journeyId: meta.id,
|
|
339
357
|
currentNodeId: "held-out",
|
|
340
358
|
status: "held_out",
|
|
341
|
-
|
|
359
|
+
// Reserved record-once namespaces are STRIPPED from event
|
|
360
|
+
// properties before seeding (injection fix): a publishable-key
|
|
361
|
+
// event must never pre-fill __once__/__digest__/__throttle__/
|
|
362
|
+
// __variants__.
|
|
363
|
+
context: stripRecordNamespaces(properties),
|
|
364
|
+
// Stamped so the per-version lift readout can match control
|
|
365
|
+
// by SAME hash (D4): held_out rows are once-ever per
|
|
366
|
+
// (user, journey), so this diversion-era stamp anchors that
|
|
367
|
+
// version's control cohort forever.
|
|
368
|
+
journeyVersionHash: meta.versionHash ?? null,
|
|
369
|
+
journeyVersionLabel: meta.version ?? null,
|
|
342
370
|
exitedAt: heldOutAt,
|
|
343
371
|
})
|
|
344
372
|
.returning({ id: journeyStates.id });
|
|
@@ -392,7 +420,7 @@ export async function executeJourneyRun(
|
|
|
392
420
|
}).catch(logger.warn);
|
|
393
421
|
}
|
|
394
422
|
}
|
|
395
|
-
return { status: "skipped", reason:
|
|
423
|
+
return { status: "skipped", reason: holdoutPolicy.reason };
|
|
396
424
|
}
|
|
397
425
|
}
|
|
398
426
|
|
|
@@ -403,8 +431,13 @@ export async function executeJourneyRun(
|
|
|
403
431
|
inArray(journeyStates.status, ["active", "waiting"]),
|
|
404
432
|
),
|
|
405
433
|
});
|
|
406
|
-
|
|
407
|
-
|
|
434
|
+
const activePolicy = evaluateEnrollmentPolicy({
|
|
435
|
+
journey: meta,
|
|
436
|
+
properties,
|
|
437
|
+
facts: { alreadyActive: Boolean(activeState) },
|
|
438
|
+
});
|
|
439
|
+
if (!activePolicy.allowed) {
|
|
440
|
+
return { status: "skipped", reason: activePolicy.reason };
|
|
408
441
|
}
|
|
409
442
|
|
|
410
443
|
// A successful insert always returns exactly one row, so undefined here
|
|
@@ -416,10 +449,15 @@ export async function executeJourneyRun(
|
|
|
416
449
|
userId,
|
|
417
450
|
userEmail,
|
|
418
451
|
journeyId: meta.id,
|
|
452
|
+
// Same strip as the held_out site. `extraContext` is engine-supplied
|
|
453
|
+
// (e.g. the blueprint interpreter's __blueprintVersion pin) and is
|
|
454
|
+
// deliberately NOT filtered.
|
|
419
455
|
context: options.extraContext
|
|
420
|
-
? { ...properties, ...options.extraContext }
|
|
421
|
-
: properties,
|
|
456
|
+
? { ...stripRecordNamespaces(properties), ...options.extraContext }
|
|
457
|
+
: stripRecordNamespaces(properties),
|
|
422
458
|
hatchetRunId: workflowRunId,
|
|
459
|
+
journeyVersionHash: meta.versionHash ?? null,
|
|
460
|
+
journeyVersionLabel: meta.version ?? null,
|
|
423
461
|
serializeWithGraphLock: options.serializeEnrollment,
|
|
424
462
|
});
|
|
425
463
|
if (!state) {
|
|
@@ -547,6 +585,9 @@ export async function executeJourneyRun(
|
|
|
547
585
|
seenKeys: new Set<string>(),
|
|
548
586
|
seenRecordLabels: new Set<string>(),
|
|
549
587
|
memoize: createMemoize(hatchetCtx),
|
|
588
|
+
// Keep production behavior on the real wall clock while allowing scoped
|
|
589
|
+
// test boundaries to substitute a deterministic virtual clock.
|
|
590
|
+
now: () => new Date(),
|
|
550
591
|
journeyId: meta.id,
|
|
551
592
|
// `meta.suppress` is a required DurationObject, but a `{}` / zero
|
|
552
593
|
// duration must yield 0 (disabled); `durationToMs` maps both to 0.
|
|
@@ -15,6 +15,72 @@ export interface HatchetMemoCtx {
|
|
|
15
15
|
supportsEviction?: boolean;
|
|
16
16
|
}
|
|
17
17
|
|
|
18
|
+
export interface JourneyEmailEffect {
|
|
19
|
+
to: string;
|
|
20
|
+
userId: string;
|
|
21
|
+
template: string;
|
|
22
|
+
subject?: string;
|
|
23
|
+
props: Record<string, unknown>;
|
|
24
|
+
category: string;
|
|
25
|
+
journeyName?: string;
|
|
26
|
+
journeyStateId?: string;
|
|
27
|
+
idempotencyKey?: string;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
export interface JourneySmsEffect {
|
|
31
|
+
to: string;
|
|
32
|
+
userId: string;
|
|
33
|
+
template: string;
|
|
34
|
+
props: Record<string, unknown>;
|
|
35
|
+
category: string;
|
|
36
|
+
journeyName?: string;
|
|
37
|
+
journeyStateId?: string;
|
|
38
|
+
idempotencyKey?: string;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
export interface JourneyConnectorEffect {
|
|
42
|
+
connectorId: string;
|
|
43
|
+
action: string;
|
|
44
|
+
args?: unknown;
|
|
45
|
+
idempotencyKey?: string;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
export interface JourneyFeedEffect {
|
|
49
|
+
recipient: { userId?: string; email?: string; anonymousId?: string };
|
|
50
|
+
type: string;
|
|
51
|
+
title?: string;
|
|
52
|
+
body?: string;
|
|
53
|
+
blocks?: unknown[];
|
|
54
|
+
actionUrl?: string;
|
|
55
|
+
metadata?: Record<string, unknown>;
|
|
56
|
+
category: string;
|
|
57
|
+
templateKey?: string;
|
|
58
|
+
journeyStateId?: string;
|
|
59
|
+
idempotencyKey?: string;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/** Scoped service replacements, primarily for deterministic journey tests. */
|
|
63
|
+
export interface JourneyServiceOverrides {
|
|
64
|
+
email?: (
|
|
65
|
+
effect: JourneyEmailEffect,
|
|
66
|
+
) => Promise<{ emailSendId: string; sentAt: string }>;
|
|
67
|
+
sms?: (effect: JourneySmsEffect) => Promise<{
|
|
68
|
+
smsSendId: string;
|
|
69
|
+
status: "sent" | "suppressed" | "unsubscribed" | "no_consent" | "skipped";
|
|
70
|
+
reason?: string;
|
|
71
|
+
sentAt?: string;
|
|
72
|
+
}>;
|
|
73
|
+
connector?: (effect: JourneyConnectorEffect) => Promise<unknown>;
|
|
74
|
+
/** Required with `connector`; validates an action before scoped capture. */
|
|
75
|
+
connectorActionExists?: (connectorId: string, action: string) => boolean;
|
|
76
|
+
feed?: (effect: JourneyFeedEffect) => Promise<{
|
|
77
|
+
feedItemId: string | null;
|
|
78
|
+
recipientKey: string | null;
|
|
79
|
+
suppressed: boolean;
|
|
80
|
+
createdAt: string | null;
|
|
81
|
+
}>;
|
|
82
|
+
}
|
|
83
|
+
|
|
18
84
|
/**
|
|
19
85
|
* Per-enrollment, per-run state threaded through `AsyncLocalStorage` so the
|
|
20
86
|
* standalone `sendEmail` / `ctx.trigger` side-effect helpers can be made
|
|
@@ -91,6 +157,16 @@ export interface JourneyBoundary {
|
|
|
91
157
|
* harness contexts) compile unchanged.
|
|
92
158
|
*/
|
|
93
159
|
category?: string;
|
|
160
|
+
/** Async-scope-local effects used before process singletons or databases. */
|
|
161
|
+
services?: JourneyServiceOverrides;
|
|
162
|
+
/**
|
|
163
|
+
* Scope-local wall clock for synchronous side-effect metadata such as
|
|
164
|
+
* unsubscribe-token expiry. Production supplies the real clock; deterministic
|
|
165
|
+
* harnesses can supply their virtual clock without installing process-global
|
|
166
|
+
* fake timers. Optional so existing non-production boundary fixtures keep the
|
|
167
|
+
* historical real-time fallback.
|
|
168
|
+
*/
|
|
169
|
+
now?: () => Date;
|
|
94
170
|
}
|
|
95
171
|
|
|
96
172
|
const journeyBoundaryAls = new AsyncLocalStorage<JourneyBoundary>();
|
|
@@ -15,28 +15,17 @@ import {
|
|
|
15
15
|
normalizeWhere,
|
|
16
16
|
} from "@hogsend/core";
|
|
17
17
|
import type { JourneyRegistry } from "@hogsend/core/registry";
|
|
18
|
-
import {
|
|
19
|
-
isValidTimeZone,
|
|
20
|
-
resolveAfter,
|
|
21
|
-
resolveNextLocalTime,
|
|
22
|
-
resolveNextWeekday,
|
|
23
|
-
resolveTomorrow,
|
|
24
|
-
type SendWindow,
|
|
25
|
-
} from "@hogsend/core/schedule";
|
|
18
|
+
import { createWhenBuilder, type SendWindow } from "@hogsend/core/schedule";
|
|
26
19
|
import type {
|
|
27
20
|
DigestEvent,
|
|
28
21
|
DigestOptions,
|
|
29
22
|
DigestResult,
|
|
30
|
-
IfPast,
|
|
31
23
|
JourneyContext,
|
|
32
24
|
PropertyCondition,
|
|
33
25
|
RecentEvent,
|
|
34
26
|
ThrottleOptions,
|
|
35
27
|
ThrottleResult,
|
|
36
|
-
TimeOfDayBuilder,
|
|
37
28
|
WaitForEventResult,
|
|
38
|
-
Weekday,
|
|
39
|
-
WhenBuilder,
|
|
40
29
|
} from "@hogsend/core/types";
|
|
41
30
|
import {
|
|
42
31
|
type Database,
|
|
@@ -52,6 +41,7 @@ import {
|
|
|
52
41
|
desc,
|
|
53
42
|
eq,
|
|
54
43
|
gte,
|
|
44
|
+
isNotNull,
|
|
55
45
|
lte,
|
|
56
46
|
max,
|
|
57
47
|
notInArray,
|
|
@@ -62,6 +52,11 @@ import { countRecentSends } from "../lib/frequency-cap.js";
|
|
|
62
52
|
import { toSleepDuration } from "../lib/hatchet-duration.js";
|
|
63
53
|
import { ingestEvent } from "../lib/ingestion.js";
|
|
64
54
|
import type { Logger } from "../lib/logger.js";
|
|
55
|
+
import {
|
|
56
|
+
pickVariant,
|
|
57
|
+
validateVariantArms,
|
|
58
|
+
validateVariantKey,
|
|
59
|
+
} from "../lib/variant.js";
|
|
65
60
|
import {
|
|
66
61
|
JOURNEY_EXECUTION_TIMEOUT,
|
|
67
62
|
JOURNEY_EXECUTION_TIMEOUT_HOURS,
|
|
@@ -98,6 +93,26 @@ const DIGEST_DEFAULT_LOOKBACK: DurationObject = { minutes: 15 };
|
|
|
98
93
|
*/
|
|
99
94
|
const digestWarned = new Set<string>();
|
|
100
95
|
|
|
96
|
+
/**
|
|
97
|
+
* `journeyId:key` pairs already warned about a recorded-arm / arms-array
|
|
98
|
+
* divergence this process. Warn-once so a replay-from-top (which re-runs the
|
|
99
|
+
* whole `run()`) doesn't spam the log with the same advisory (mirrors
|
|
100
|
+
* digestWarned above).
|
|
101
|
+
*/
|
|
102
|
+
const variantWarned = new Set<string>();
|
|
103
|
+
|
|
104
|
+
function warnVariantOnce(
|
|
105
|
+
logger: Logger,
|
|
106
|
+
journeyId: string,
|
|
107
|
+
key: string,
|
|
108
|
+
message: string,
|
|
109
|
+
): void {
|
|
110
|
+
const warnKey = `${journeyId}:${key}`;
|
|
111
|
+
if (variantWarned.has(warnKey)) return;
|
|
112
|
+
variantWarned.add(warnKey);
|
|
113
|
+
logger.warn(message);
|
|
114
|
+
}
|
|
115
|
+
|
|
101
116
|
/**
|
|
102
117
|
* Quote a string as a CEL single-quoted string literal, escaping backslashes
|
|
103
118
|
* then single quotes. Used to embed an externally-supplied userId into a CEL
|
|
@@ -173,64 +188,6 @@ interface JourneyContextConfig {
|
|
|
173
188
|
entryPeriod?: DurationObject;
|
|
174
189
|
}
|
|
175
190
|
|
|
176
|
-
/**
|
|
177
|
-
* Build the timezone-bound fluent scheduler. A thin wrapper over the pure core
|
|
178
|
-
* resolvers: it injects the user's resolved tz, the real current instant, and
|
|
179
|
-
* the (optionally overridden) send window, returning absolute `Date`s.
|
|
180
|
-
*/
|
|
181
|
-
function createWhenBuilder(opts: {
|
|
182
|
-
timezone: string;
|
|
183
|
-
window?: SendWindow;
|
|
184
|
-
ifPast: IfPast;
|
|
185
|
-
/**
|
|
186
|
-
* The current instant, supplied by the context so `ctx.when` reads the
|
|
187
|
-
* replay-stable (memoized) clock instead of a raw `new Date()` — the resolved
|
|
188
|
-
* instant must be identical across a durable replay or a scheduled `.next(...)`
|
|
189
|
-
* could land on a different day the second time through.
|
|
190
|
-
*/
|
|
191
|
-
now: () => Date;
|
|
192
|
-
}): WhenBuilder {
|
|
193
|
-
const baseOpts = () => ({
|
|
194
|
-
timezone: opts.timezone,
|
|
195
|
-
now: opts.now(),
|
|
196
|
-
window: opts.window,
|
|
197
|
-
ifPast: opts.ifPast,
|
|
198
|
-
});
|
|
199
|
-
|
|
200
|
-
const timeBuilder = (resolve: (time: string) => Date): TimeOfDayBuilder => ({
|
|
201
|
-
at: (time) => resolve(time),
|
|
202
|
-
});
|
|
203
|
-
|
|
204
|
-
return {
|
|
205
|
-
next(weekday: Weekday) {
|
|
206
|
-
return timeBuilder((time) =>
|
|
207
|
-
resolveNextWeekday(weekday, time, baseOpts()),
|
|
208
|
-
);
|
|
209
|
-
},
|
|
210
|
-
nextLocal(time: string) {
|
|
211
|
-
return resolveNextLocalTime(time, baseOpts());
|
|
212
|
-
},
|
|
213
|
-
tomorrow() {
|
|
214
|
-
return timeBuilder((time) => resolveTomorrow(time, baseOpts()));
|
|
215
|
-
},
|
|
216
|
-
in(duration: DurationObject) {
|
|
217
|
-
return timeBuilder((time) => resolveAfter(duration, time, baseOpts()));
|
|
218
|
-
},
|
|
219
|
-
tz(timezone: string) {
|
|
220
|
-
if (!isValidTimeZone(timezone)) {
|
|
221
|
-
throw new TypeError(`ctx.when.tz: invalid timezone "${timezone}"`);
|
|
222
|
-
}
|
|
223
|
-
return createWhenBuilder({ ...opts, timezone });
|
|
224
|
-
},
|
|
225
|
-
window(start: string, end: string) {
|
|
226
|
-
return createWhenBuilder({ ...opts, window: { start, end } });
|
|
227
|
-
},
|
|
228
|
-
ifPast(strategy: IfPast) {
|
|
229
|
-
return createWhenBuilder({ ...opts, ifPast: strategy });
|
|
230
|
-
},
|
|
231
|
-
};
|
|
232
|
-
}
|
|
233
|
-
|
|
234
191
|
export function createJourneyContext(
|
|
235
192
|
config: JourneyContextConfig,
|
|
236
193
|
): JourneyContext {
|
|
@@ -955,6 +912,103 @@ export function createJourneyContext(
|
|
|
955
912
|
});
|
|
956
913
|
};
|
|
957
914
|
|
|
915
|
+
// Deterministic experiment arm (ctx.variant, impact experiments Decision
|
|
916
|
+
// B). Assignment is a pure sha256 bucket (lib/variant.ts), RECORDED once
|
|
917
|
+
// per enrollment under the reserved __variants__ bag; the recorded value
|
|
918
|
+
// wins VERBATIM on every later call within this enrollment — including a
|
|
919
|
+
// replay after a deploy that changed `arms`. compute is SYNCHRONOUS and
|
|
920
|
+
// pure (hash only): no clock, no awaits, no durable calls — ctx.variant is
|
|
921
|
+
// positionally invisible in Hatchet's journal, like ctx.throttle. NO
|
|
922
|
+
// registerRecordLabel: re-reading the same key returning the same arm is
|
|
923
|
+
// intended reuse, not an authoring bug. No boundary-label write, no
|
|
924
|
+
// transition log — the jsonb bag IS the observability.
|
|
925
|
+
const performVariant = async <const A extends readonly [string, ...string[]]>(
|
|
926
|
+
key: string,
|
|
927
|
+
arms: A,
|
|
928
|
+
): Promise<A[number]> => {
|
|
929
|
+
// 1. KEY SYNTAX ONLY — runs BEFORE the recordOnce read (it gates the
|
|
930
|
+
// jsonb path). Arms validation is deliberately NOT here: a deploy that
|
|
931
|
+
// ships malformed arms must degrade in-flight enrollments to the
|
|
932
|
+
// recorded fast path (no crash), while FRESH assignments still fail
|
|
933
|
+
// loudly in dev via the compute below.
|
|
934
|
+
validateVariantKey(key);
|
|
935
|
+
const journeyId = config.journeyId;
|
|
936
|
+
if (!journeyId) {
|
|
937
|
+
throw new Error(
|
|
938
|
+
"ctx.variant requires the journey id on the context (always set by " +
|
|
939
|
+
"the engine; pass journeyId in test configs)",
|
|
940
|
+
);
|
|
941
|
+
}
|
|
942
|
+
|
|
943
|
+
// 2. RECORD ONCE — first winning writer computes; everyone after
|
|
944
|
+
// (replay, reuse, zombie racer) reads the committed arm back.
|
|
945
|
+
const assigned = await recordOnce({
|
|
946
|
+
db,
|
|
947
|
+
stateId,
|
|
948
|
+
namespace: "__variants__",
|
|
949
|
+
key,
|
|
950
|
+
compute: () => {
|
|
951
|
+
validateVariantArms(arms);
|
|
952
|
+
return pickVariant({ journeyId, key, userId, arms });
|
|
953
|
+
},
|
|
954
|
+
});
|
|
955
|
+
|
|
956
|
+
// 3. TYPE GUARD — a fast-path value that is NOT a string is never
|
|
957
|
+
// returned into author code (defends against pre-stripping legacy rows
|
|
958
|
+
// with injected objects). Recompute from the pure hash (replay-stable by
|
|
959
|
+
// construction) and repair the poisoned slot under a type guard so the
|
|
960
|
+
// impact readout's GROUP BY dimension stays a clean string set. The
|
|
961
|
+
// guarded jsonb_set only ever replaces a NON-string value, so it can
|
|
962
|
+
// never clobber a legitimately committed arm; concurrent repairers
|
|
963
|
+
// compute the identical pure value.
|
|
964
|
+
if (typeof assigned !== "string") {
|
|
965
|
+
warnVariantOnce(
|
|
966
|
+
logger,
|
|
967
|
+
journeyId,
|
|
968
|
+
key,
|
|
969
|
+
`ctx.variant: journey "${journeyId}" key "${key}" carried a ` +
|
|
970
|
+
"non-string recorded value (pre-strip legacy row); recomputed " +
|
|
971
|
+
"the arm deterministically and repaired the record",
|
|
972
|
+
);
|
|
973
|
+
validateVariantArms(arms);
|
|
974
|
+
const fresh = pickVariant({ journeyId, key, userId, arms });
|
|
975
|
+
await db
|
|
976
|
+
.update(journeyStates)
|
|
977
|
+
.set({
|
|
978
|
+
context: sql`jsonb_set(
|
|
979
|
+
coalesce(${journeyStates.context}, '{}'::jsonb),
|
|
980
|
+
ARRAY['__variants__', ${key}]::text[],
|
|
981
|
+
to_jsonb(${fresh}::text),
|
|
982
|
+
true
|
|
983
|
+
)`,
|
|
984
|
+
updatedAt: new Date(),
|
|
985
|
+
})
|
|
986
|
+
.where(
|
|
987
|
+
and(
|
|
988
|
+
eq(journeyStates.id, stateId),
|
|
989
|
+
sql`jsonb_typeof(${journeyStates.context} -> '__variants__' -> ${key}) IS DISTINCT FROM 'string'`,
|
|
990
|
+
),
|
|
991
|
+
);
|
|
992
|
+
return fresh as A[number];
|
|
993
|
+
}
|
|
994
|
+
|
|
995
|
+
// 4. STALE-ARM ADVISORY — recorded value wins VERBATIM (Decision B),
|
|
996
|
+
// even when a redeploy changed the arms mid-enrollment. Warn once per
|
|
997
|
+
// process per journeyId:key; NEVER throw here.
|
|
998
|
+
if (!(arms as readonly string[]).includes(assigned)) {
|
|
999
|
+
warnVariantOnce(
|
|
1000
|
+
logger,
|
|
1001
|
+
journeyId,
|
|
1002
|
+
key,
|
|
1003
|
+
`ctx.variant: journey "${journeyId}" key "${key}" recorded arm ` +
|
|
1004
|
+
`"${assigned}" is not in the current arms [${arms.join(", ")}]; ` +
|
|
1005
|
+
"returning the recorded arm verbatim (an enrollment keeps its " +
|
|
1006
|
+
"entry-time assignment across deploys)",
|
|
1007
|
+
);
|
|
1008
|
+
}
|
|
1009
|
+
return assigned as A[number];
|
|
1010
|
+
};
|
|
1011
|
+
|
|
958
1012
|
return {
|
|
959
1013
|
when: createWhenBuilder({
|
|
960
1014
|
timezone: resolvedTimezone,
|
|
@@ -1139,6 +1193,8 @@ export function createJourneyContext(
|
|
|
1139
1193
|
return recordOnce({ db, stateId, namespace: "__once__", key, compute });
|
|
1140
1194
|
},
|
|
1141
1195
|
|
|
1196
|
+
variant: performVariant,
|
|
1197
|
+
|
|
1142
1198
|
digest(opts) {
|
|
1143
1199
|
return performDigest(opts);
|
|
1144
1200
|
},
|
|
@@ -1203,6 +1259,7 @@ export function createJourneyContext(
|
|
|
1203
1259
|
and(
|
|
1204
1260
|
eq(emailSends.toEmail, targetEmail),
|
|
1205
1261
|
eq(emailSends.templateKey, template),
|
|
1262
|
+
isNotNull(emailSends.sentAt),
|
|
1206
1263
|
),
|
|
1207
1264
|
);
|
|
1208
1265
|
|
|
@@ -1228,6 +1285,7 @@ export function createJourneyContext(
|
|
|
1228
1285
|
and(
|
|
1229
1286
|
eq(smsSends.toPhone, phone),
|
|
1230
1287
|
eq(smsSends.templateKey, template),
|
|
1288
|
+
isNotNull(smsSends.sentAt),
|
|
1231
1289
|
),
|
|
1232
1290
|
);
|
|
1233
1291
|
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
|
|
2
|
+
import type { JourneyMeta, JourneyRunFn } from "@hogsend/core/types";
|
|
3
|
+
|
|
4
|
+
/** The durable Hatchet declaration attached to a production journey. */
|
|
5
|
+
export type JourneyTask = ReturnType<HatchetClient["durableTask"]>;
|
|
6
|
+
|
|
7
|
+
type JourneyTaskFactory = (meta: JourneyMeta, run: JourneyRunFn) => JourneyTask;
|
|
8
|
+
|
|
9
|
+
let taskFactory: JourneyTaskFactory | undefined;
|
|
10
|
+
|
|
11
|
+
/** Install the production Hatchet binding without coupling authoring imports to env. */
|
|
12
|
+
export function installJourneyTaskFactory(factory: JourneyTaskFactory): void {
|
|
13
|
+
taskFactory = factory;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
export function hasJourneyTaskFactory(): boolean {
|
|
17
|
+
return taskFactory !== undefined;
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
export function createJourneyTask(
|
|
21
|
+
meta: JourneyMeta,
|
|
22
|
+
run: JourneyRunFn,
|
|
23
|
+
): JourneyTask {
|
|
24
|
+
if (!taskFactory) {
|
|
25
|
+
throw new Error(
|
|
26
|
+
"Journey tasks require the production @hogsend/engine runtime. " +
|
|
27
|
+
"Import createWorker from @hogsend/engine before selecting tasks.",
|
|
28
|
+
);
|
|
29
|
+
}
|
|
30
|
+
return taskFactory(meta, run);
|
|
31
|
+
}
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
import type { JourneyMeta, JourneyRunFn } from "@hogsend/core/types";
|
|
2
|
+
import { hatchet } from "../lib/hatchet.js";
|
|
3
|
+
import {
|
|
4
|
+
JOURNEY_EXECUTION_TIMEOUT,
|
|
5
|
+
JOURNEY_SCHEDULE_TIMEOUT,
|
|
6
|
+
} from "./constants.js";
|
|
7
|
+
import {
|
|
8
|
+
type EventPayloadInput,
|
|
9
|
+
executeJourneyRun,
|
|
10
|
+
} from "./execute-journey-run.js";
|
|
11
|
+
import { installJourneyTaskFactory } from "./journey-task-factory.js";
|
|
12
|
+
|
|
13
|
+
/**
|
|
14
|
+
* Bind pure journey definitions to Hatchet only in production engine entry
|
|
15
|
+
* points. `@hogsend/engine/journeys` deliberately does not import this module,
|
|
16
|
+
* which keeps authoring modules importable without runtime credentials.
|
|
17
|
+
*/
|
|
18
|
+
installJourneyTaskFactory((meta: JourneyMeta, run: JourneyRunFn) =>
|
|
19
|
+
hatchet.durableTask({
|
|
20
|
+
name: `journey-${meta.id}`,
|
|
21
|
+
onEvents: [meta.trigger.event],
|
|
22
|
+
executionTimeout: JOURNEY_EXECUTION_TIMEOUT,
|
|
23
|
+
// retries STAYS 0 — deliberately. A retry replays `run()` from the top, and
|
|
24
|
+
// provider delivery cannot yet be made atomic with the durable status flip.
|
|
25
|
+
retries: 0,
|
|
26
|
+
// Give durable-wait resumes enough queue headroom during deploy saturation.
|
|
27
|
+
scheduleTimeout: JOURNEY_SCHEDULE_TIMEOUT,
|
|
28
|
+
fn: async (input: EventPayloadInput, hatchetCtx) =>
|
|
29
|
+
executeJourneyRun({ meta, run, input, hatchetCtx }),
|
|
30
|
+
}),
|
|
31
|
+
);
|