@hogsend/engine 0.31.1 → 0.32.1
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 +7 -7
- package/src/cold-connect/index.ts +1 -0
- package/src/connectors/define-connector.ts +12 -2
- package/src/connectors/runtime.ts +10 -8
- package/src/index.ts +8 -0
- package/src/journeys/define-journey.ts +111 -41
- package/src/journeys/journey-boundary.ts +172 -0
- package/src/journeys/journey-context.ts +391 -23
- package/src/lib/boot.ts +8 -4
- package/src/lib/bot-prefetch.ts +48 -0
- package/src/lib/bucket-emit.ts +2 -0
- package/src/lib/connector-actions.ts +197 -5
- package/src/lib/domain-status.ts +27 -12
- package/src/lib/email.ts +63 -5
- package/src/lib/ingestion.ts +71 -1
- package/src/lib/links.ts +1 -1
- package/src/lib/tracked.ts +111 -37
- package/src/lib/tracking-event-names.ts +9 -0
- package/src/lib/tracking-events.ts +73 -0
- package/src/routes/admin/bulk.ts +2 -0
- package/src/routes/admin/events.ts +51 -11
- package/src/routes/admin/index.ts +2 -0
- package/src/routes/admin/journeys.ts +95 -1
- package/src/routes/admin/links.ts +51 -8
- package/src/routes/admin/readiness.ts +181 -0
- package/src/routes/connectors/index.ts +22 -5
- package/src/routes/events/index.ts +2 -0
- package/src/routes/tracking/click.ts +51 -1
- package/src/routes/webhooks/sources.ts +31 -4
|
@@ -8,7 +8,12 @@ import {
|
|
|
8
8
|
UserEventCondition,
|
|
9
9
|
} from "@hatchet-dev/typescript-sdk/v1/index.js";
|
|
10
10
|
import type { DurationObject } from "@hogsend/core";
|
|
11
|
-
import {
|
|
11
|
+
import {
|
|
12
|
+
durationToMs,
|
|
13
|
+
evaluateEventCondition,
|
|
14
|
+
evaluatePropertyConditions,
|
|
15
|
+
normalizeWhere,
|
|
16
|
+
} from "@hogsend/core";
|
|
12
17
|
import type { JourneyRegistry } from "@hogsend/core/registry";
|
|
13
18
|
import {
|
|
14
19
|
isValidTimeZone,
|
|
@@ -21,6 +26,7 @@ import {
|
|
|
21
26
|
import type {
|
|
22
27
|
IfPast,
|
|
23
28
|
JourneyContext,
|
|
29
|
+
PropertyCondition,
|
|
24
30
|
RecentEvent,
|
|
25
31
|
TimeOfDayBuilder,
|
|
26
32
|
WaitForEventResult,
|
|
@@ -33,7 +39,7 @@ import {
|
|
|
33
39
|
journeyStates,
|
|
34
40
|
userEvents,
|
|
35
41
|
} from "@hogsend/db";
|
|
36
|
-
import { and, count, desc, eq, gte, max, notInArray } from "drizzle-orm";
|
|
42
|
+
import { and, count, desc, eq, gte, max, notInArray, sql } from "drizzle-orm";
|
|
37
43
|
import { checkEmailPreferences } from "../lib/enrollment-guards.js";
|
|
38
44
|
import { ingestEvent } from "../lib/ingestion.js";
|
|
39
45
|
import type { Logger } from "../lib/logger.js";
|
|
@@ -42,6 +48,11 @@ import {
|
|
|
42
48
|
JOURNEY_EXECUTION_TIMEOUT_HOURS,
|
|
43
49
|
} from "./constants.js";
|
|
44
50
|
import { JourneyExitedError } from "./errors.js";
|
|
51
|
+
import {
|
|
52
|
+
deriveJourneyKey,
|
|
53
|
+
getJourneyBoundary,
|
|
54
|
+
registerKey,
|
|
55
|
+
} from "./journey-boundary.js";
|
|
45
56
|
|
|
46
57
|
/** Journey statuses that are terminal — a journey in any of these must never be
|
|
47
58
|
* resurrected back to "active" by a wait resuming. Exported so the durable task
|
|
@@ -73,6 +84,12 @@ interface JourneyContextConfig {
|
|
|
73
84
|
waitFor: (
|
|
74
85
|
conditions: Conditions | Conditions[],
|
|
75
86
|
) => Promise<Record<string, unknown>>;
|
|
87
|
+
// The real `DurableContext.now()` (SDK 1.22.3, public): a clock memoized
|
|
88
|
+
// across replays — same Date on every replay of the same run. Optional so a
|
|
89
|
+
// pre-eviction engine (or a test ctx without it) falls back to the live
|
|
90
|
+
// clock via `nowProvider` below; that only affects RECOMPUTED instants, never
|
|
91
|
+
// the DB-key exactly-once of sends/triggers, so correctness is preserved.
|
|
92
|
+
now?: () => Promise<Date>;
|
|
76
93
|
};
|
|
77
94
|
registry: JourneyRegistry;
|
|
78
95
|
logger: Logger;
|
|
@@ -95,10 +112,17 @@ function createWhenBuilder(opts: {
|
|
|
95
112
|
timezone: string;
|
|
96
113
|
window?: SendWindow;
|
|
97
114
|
ifPast: IfPast;
|
|
115
|
+
/**
|
|
116
|
+
* The current instant, supplied by the context so `ctx.when` reads the
|
|
117
|
+
* replay-stable (memoized) clock instead of a raw `new Date()` — the resolved
|
|
118
|
+
* instant must be identical across a durable replay or a scheduled `.next(...)`
|
|
119
|
+
* could land on a different day the second time through.
|
|
120
|
+
*/
|
|
121
|
+
now: () => Date;
|
|
98
122
|
}): WhenBuilder {
|
|
99
123
|
const baseOpts = () => ({
|
|
100
124
|
timezone: opts.timezone,
|
|
101
|
-
now:
|
|
125
|
+
now: opts.now(),
|
|
102
126
|
window: opts.window,
|
|
103
127
|
ifPast: opts.ifPast,
|
|
104
128
|
});
|
|
@@ -154,6 +178,36 @@ export function createJourneyContext(
|
|
|
154
178
|
defaultSendWindow,
|
|
155
179
|
} = config;
|
|
156
180
|
|
|
181
|
+
// Replay-stable clock: the real DurableContext.now() is memoized across
|
|
182
|
+
// replays; a pre-eviction engine (or a test ctx without it) falls back to the
|
|
183
|
+
// live clock. Only RECOMPUTED instants depend on this — never the DB-key
|
|
184
|
+
// exactly-once of sends/triggers — so a live fallback never breaks correctness.
|
|
185
|
+
const nowProvider = (): Promise<Date> =>
|
|
186
|
+
hatchetCtx.now ? hatchetCtx.now() : Promise.resolve(new Date());
|
|
187
|
+
|
|
188
|
+
// `ctx.when` resolves instants synchronously, but the memoized clock is async.
|
|
189
|
+
// Keep a snapshot of the most recent memoized instant that `ctx.when` reads
|
|
190
|
+
// synchronously; refresh it whenever an async primitive runs AND once at the
|
|
191
|
+
// start of `run()` (define-journey awaits `ctx.now()` before running so the
|
|
192
|
+
// seed below is replaced by the memoized instant before any `ctx.when` read).
|
|
193
|
+
// The live `new Date()` is only a fallback for a context whose `run()` never
|
|
194
|
+
// gets that pre-seed (tests) or a pre-eviction engine (best-effort, unchanged).
|
|
195
|
+
let latestNow = new Date();
|
|
196
|
+
const refreshNow = async (): Promise<Date> => {
|
|
197
|
+
latestNow = await nowProvider();
|
|
198
|
+
return latestNow;
|
|
199
|
+
};
|
|
200
|
+
|
|
201
|
+
// Capture the nearest authored wait/checkpoint label on the active journey
|
|
202
|
+
// boundary so the NEXT side effect (sendEmail / ctx.trigger) inherits it as
|
|
203
|
+
// its idempotency-key "site" discriminant. This is what lets two sends of the
|
|
204
|
+
// SAME template on different branches derive distinct keys for free, without
|
|
205
|
+
// any explicit authoring label. No-op outside a journey run (no boundary).
|
|
206
|
+
const setBoundaryLabel = (label: string): void => {
|
|
207
|
+
const boundary = getJourneyBoundary();
|
|
208
|
+
if (boundary) boundary.currentLabel = label;
|
|
209
|
+
};
|
|
210
|
+
|
|
157
211
|
// Enter a durable wait: flip "active" → "waiting", but ONLY if the journey
|
|
158
212
|
// hasn't already reached a terminal state (e.g. exitOn fired before we got
|
|
159
213
|
// here). A no-op update means the journey is already done — abort the run.
|
|
@@ -204,9 +258,186 @@ export function createJourneyContext(
|
|
|
204
258
|
await hatchetCtx.sleepFor(durationOrMs);
|
|
205
259
|
const resumedAt = new Date().toISOString();
|
|
206
260
|
await resumeFromWait();
|
|
261
|
+
// Refresh the memoized clock snapshot so a `ctx.when` chain used right after
|
|
262
|
+
// this wait reads a replay-stable instant (on an eviction engine) instead of
|
|
263
|
+
// the construction-time seed — see `latestNow`.
|
|
264
|
+
await refreshNow();
|
|
265
|
+
// The just-finished wait's label is the "site" the next side effect inherits.
|
|
266
|
+
setBoundaryLabel(nodeId);
|
|
207
267
|
return { sleptAt, resumedAt };
|
|
208
268
|
};
|
|
209
269
|
|
|
270
|
+
const narrowScalars = (
|
|
271
|
+
props: Record<string, unknown> | null | undefined,
|
|
272
|
+
): NonNullable<WaitForEventResult["properties"]> =>
|
|
273
|
+
Object.fromEntries(
|
|
274
|
+
Object.entries(props ?? {}).filter(
|
|
275
|
+
([, v]) =>
|
|
276
|
+
typeof v === "string" ||
|
|
277
|
+
typeof v === "number" ||
|
|
278
|
+
typeof v === "boolean" ||
|
|
279
|
+
v === null,
|
|
280
|
+
),
|
|
281
|
+
) as NonNullable<WaitForEventResult["properties"]>;
|
|
282
|
+
|
|
283
|
+
// WHERE-filtered durable wait. Unlike the legacy single-wait (which resolves
|
|
284
|
+
// on the FIRST same-name event, ignoring properties), this resolves ONLY on an
|
|
285
|
+
// event whose properties satisfy `where`. Correctness:
|
|
286
|
+
// • DURABLE DEADLINE — persisted to `journey_states.wait_deadline`
|
|
287
|
+
// read-first/set-once, so a Hatchet replay-from-top reuses it instead of
|
|
288
|
+
// extending the wait on every replay (the single-`sleepFor` durability
|
|
289
|
+
// trick does not survive a multi-iteration re-arm).
|
|
290
|
+
// • GAP-PROOF — each iteration re-scans `user_events` over the WHOLE window
|
|
291
|
+
// since the wait began (ingest writes the row BEFORE the Hatchet push), so
|
|
292
|
+
// a match landing in the gap between a non-matching wake and the re-arm is
|
|
293
|
+
// never lost. `lookback` widens the window backward.
|
|
294
|
+
// • enterWait / resumeFromWait fire EXACTLY ONCE around the loop; an `exitOn`
|
|
295
|
+
// landing mid-wait is caught by the per-iteration terminal-status check.
|
|
296
|
+
const performFilteredWaitForEvent = async (
|
|
297
|
+
event: string,
|
|
298
|
+
timeout: DurationObject,
|
|
299
|
+
nodeId: string,
|
|
300
|
+
where: PropertyCondition[],
|
|
301
|
+
lookback?: DurationObject,
|
|
302
|
+
): Promise<WaitForEventResult> => {
|
|
303
|
+
// Durable deadline: read-first / set-once.
|
|
304
|
+
const stateRow = await db
|
|
305
|
+
.select({ waitDeadline: journeyStates.waitDeadline })
|
|
306
|
+
.from(journeyStates)
|
|
307
|
+
.where(eq(journeyStates.id, stateId))
|
|
308
|
+
.limit(1);
|
|
309
|
+
const storedDeadline = stateRow[0]?.waitDeadline ?? null;
|
|
310
|
+
const deadline = storedDeadline
|
|
311
|
+
? new Date(storedDeadline)
|
|
312
|
+
: new Date(Date.now() + durationToMs(timeout));
|
|
313
|
+
if (!storedDeadline) {
|
|
314
|
+
await db
|
|
315
|
+
.update(journeyStates)
|
|
316
|
+
.set({ waitDeadline: deadline, updatedAt: new Date() })
|
|
317
|
+
.where(eq(journeyStates.id, stateId));
|
|
318
|
+
}
|
|
319
|
+
|
|
320
|
+
const clearDeadline = () =>
|
|
321
|
+
db
|
|
322
|
+
.update(journeyStates)
|
|
323
|
+
.set({ waitDeadline: null, updatedAt: new Date() })
|
|
324
|
+
.where(eq(journeyStates.id, stateId));
|
|
325
|
+
|
|
326
|
+
// Scan window: the (durable) instant the wait began — deadline minus the
|
|
327
|
+
// original timeout — widened backward by `lookback`.
|
|
328
|
+
const lookbackMs = lookback ? durationToMs(lookback) : 0;
|
|
329
|
+
const scanSince = new Date(
|
|
330
|
+
deadline.getTime() - durationToMs(timeout) - lookbackMs,
|
|
331
|
+
);
|
|
332
|
+
|
|
333
|
+
// Push `eq` conditions (the common "await THIS specific link/campaign" case)
|
|
334
|
+
// into SQL so the LIMIT below bounds MATCHING rows, not all same-name rows —
|
|
335
|
+
// otherwise a chatty user emitting >LIMIT other same-name events could bury
|
|
336
|
+
// the matching row past the cutoff and the wait would falsely time out.
|
|
337
|
+
// jsonb `->>` extracts as text; scalar eq compares as text (matching how the
|
|
338
|
+
// value was stored). Non-eq operators are left to the JS re-verify below.
|
|
339
|
+
const eqPreds = where
|
|
340
|
+
.filter((c) => c.operator === "eq" && c.value !== undefined)
|
|
341
|
+
.map(
|
|
342
|
+
(c) =>
|
|
343
|
+
sql`${userEvents.properties} ->> ${c.property} = ${String(c.value)}`,
|
|
344
|
+
);
|
|
345
|
+
|
|
346
|
+
const scanForMatch = async (): Promise<NonNullable<
|
|
347
|
+
WaitForEventResult["properties"]
|
|
348
|
+
> | null> => {
|
|
349
|
+
const recent = await db
|
|
350
|
+
.select({ properties: userEvents.properties })
|
|
351
|
+
.from(userEvents)
|
|
352
|
+
.where(
|
|
353
|
+
and(
|
|
354
|
+
eq(userEvents.userId, userId),
|
|
355
|
+
eq(userEvents.event, event),
|
|
356
|
+
gte(userEvents.occurredAt, scanSince),
|
|
357
|
+
...eqPreds,
|
|
358
|
+
),
|
|
359
|
+
)
|
|
360
|
+
.orderBy(desc(userEvents.occurredAt))
|
|
361
|
+
// 100 is a generous backstop for a `where` of ONLY non-eq operators (no
|
|
362
|
+
// SQL pushdown); the eq-pushdown path returns only matching rows, so the
|
|
363
|
+
// cap can never hide a match there.
|
|
364
|
+
.limit(100);
|
|
365
|
+
for (const row of recent) {
|
|
366
|
+
const props = (row.properties ?? {}) as Record<string, unknown>;
|
|
367
|
+
if (
|
|
368
|
+
evaluatePropertyConditions({ conditions: where, properties: props })
|
|
369
|
+
) {
|
|
370
|
+
return narrowScalars(props);
|
|
371
|
+
}
|
|
372
|
+
}
|
|
373
|
+
return null;
|
|
374
|
+
};
|
|
375
|
+
|
|
376
|
+
// Immediate hit (incl. the lookback window) — resolve without a state flip.
|
|
377
|
+
const preHit = await scanForMatch();
|
|
378
|
+
if (preHit) {
|
|
379
|
+
await clearDeadline();
|
|
380
|
+
return { timedOut: false, properties: preHit };
|
|
381
|
+
}
|
|
382
|
+
|
|
383
|
+
await enterWait(nodeId);
|
|
384
|
+
|
|
385
|
+
let outcome: WaitForEventResult;
|
|
386
|
+
while (true) {
|
|
387
|
+
const hit = await scanForMatch();
|
|
388
|
+
if (hit) {
|
|
389
|
+
outcome = { timedOut: false, properties: hit };
|
|
390
|
+
break;
|
|
391
|
+
}
|
|
392
|
+
|
|
393
|
+
// exitOn landing mid-wait flips the row to a terminal status — abort
|
|
394
|
+
// cleanly (no resume, no post-wait side effects) instead of re-arming.
|
|
395
|
+
const st = await db
|
|
396
|
+
.select({ status: journeyStates.status })
|
|
397
|
+
.from(journeyStates)
|
|
398
|
+
.where(eq(journeyStates.id, stateId))
|
|
399
|
+
.limit(1);
|
|
400
|
+
const status = st[0]?.status;
|
|
401
|
+
if (status && (TERMINAL_STATUSES as readonly string[]).includes(status)) {
|
|
402
|
+
throw new JourneyExitedError(stateId);
|
|
403
|
+
}
|
|
404
|
+
|
|
405
|
+
const remainingMs = deadline.getTime() - Date.now();
|
|
406
|
+
if (remainingMs <= 0) {
|
|
407
|
+
outcome = { timedOut: true };
|
|
408
|
+
break;
|
|
409
|
+
}
|
|
410
|
+
|
|
411
|
+
const armed = await hatchetCtx.waitFor(
|
|
412
|
+
Or(
|
|
413
|
+
new UserEventCondition(
|
|
414
|
+
event,
|
|
415
|
+
`input.userId == ${celStringLiteral(userId)}`,
|
|
416
|
+
"event",
|
|
417
|
+
),
|
|
418
|
+
new SleepCondition(remainingMs, "timeout"),
|
|
419
|
+
),
|
|
420
|
+
);
|
|
421
|
+
const fired = (("CREATE" in armed ? armed.CREATE : armed) ??
|
|
422
|
+
{}) as Record<string, unknown>;
|
|
423
|
+
if (!("event" in fired)) {
|
|
424
|
+
// Timeout branch — one final scan for an event landing exactly as the
|
|
425
|
+
// sleep expired, then conclude.
|
|
426
|
+
const last = await scanForMatch();
|
|
427
|
+
outcome = last
|
|
428
|
+
? { timedOut: false, properties: last }
|
|
429
|
+
: { timedOut: true };
|
|
430
|
+
break;
|
|
431
|
+
}
|
|
432
|
+
// Event branch: loop — the next scan picks up the (already persisted) row
|
|
433
|
+
// if it matches, else re-arms toward the durable deadline.
|
|
434
|
+
}
|
|
435
|
+
|
|
436
|
+
await resumeFromWait();
|
|
437
|
+
await clearDeadline();
|
|
438
|
+
return outcome;
|
|
439
|
+
};
|
|
440
|
+
|
|
210
441
|
// Durably wait for THIS user's `event` OR `timeout`, whichever fires first,
|
|
211
442
|
// sharing the same guarded lifecycle as `performSleep`.
|
|
212
443
|
const performWaitForEvent = async (
|
|
@@ -214,6 +445,7 @@ export function createJourneyContext(
|
|
|
214
445
|
timeout: DurationObject,
|
|
215
446
|
nodeId: string,
|
|
216
447
|
lookback?: DurationObject,
|
|
448
|
+
where?: PropertyCondition[],
|
|
217
449
|
): Promise<WaitForEventResult> => {
|
|
218
450
|
// Reject a timeout longer than the journey task's executionTimeout up front
|
|
219
451
|
// so it fails fast at authoring time. (Eviction-capable engines may allow
|
|
@@ -225,6 +457,23 @@ export function createJourneyContext(
|
|
|
225
457
|
);
|
|
226
458
|
}
|
|
227
459
|
|
|
460
|
+
// This wait's label is the "site" the next side effect inherits, regardless
|
|
461
|
+
// of which path (filtered re-arm / lookback hit / event / timeout) resolves
|
|
462
|
+
// it — set it before dispatching to either wait path.
|
|
463
|
+
setBoundaryLabel(nodeId);
|
|
464
|
+
|
|
465
|
+
// WHERE-filtered wait takes the durable re-arm path; an empty/absent `where`
|
|
466
|
+
// keeps the exact legacy single-wait below byte-for-byte.
|
|
467
|
+
if (where && where.length > 0) {
|
|
468
|
+
return performFilteredWaitForEvent(
|
|
469
|
+
event,
|
|
470
|
+
timeout,
|
|
471
|
+
nodeId,
|
|
472
|
+
where,
|
|
473
|
+
lookback,
|
|
474
|
+
);
|
|
475
|
+
}
|
|
476
|
+
|
|
228
477
|
// Optional lookback: the durable wait only matches events pushed AFTER it
|
|
229
478
|
// is established, so an answer landing in the gap (between a send and its
|
|
230
479
|
// wait, or between two back-to-back waits) would otherwise be permanently
|
|
@@ -232,9 +481,14 @@ export function createJourneyContext(
|
|
|
232
481
|
// can never re-push. A recent matching user_events row resolves the wait
|
|
233
482
|
// immediately, payload included.
|
|
234
483
|
if (lookback) {
|
|
235
|
-
const since = new Date(
|
|
484
|
+
const since = new Date(
|
|
485
|
+
(await refreshNow()).getTime() - durationToMs(lookback),
|
|
486
|
+
);
|
|
236
487
|
const recent = await db
|
|
237
|
-
.select({
|
|
488
|
+
.select({
|
|
489
|
+
properties: userEvents.properties,
|
|
490
|
+
occurredAt: userEvents.occurredAt,
|
|
491
|
+
})
|
|
238
492
|
.from(userEvents)
|
|
239
493
|
.where(
|
|
240
494
|
and(
|
|
@@ -256,7 +510,17 @@ export function createJourneyContext(
|
|
|
256
510
|
v === null,
|
|
257
511
|
),
|
|
258
512
|
) as NonNullable<WaitForEventResult["properties"]>;
|
|
259
|
-
|
|
513
|
+
const occurredAt =
|
|
514
|
+
row.occurredAt instanceof Date
|
|
515
|
+
? row.occurredAt.toISOString()
|
|
516
|
+
: row.occurredAt
|
|
517
|
+
? String(row.occurredAt)
|
|
518
|
+
: undefined;
|
|
519
|
+
return {
|
|
520
|
+
timedOut: false,
|
|
521
|
+
properties: scalars,
|
|
522
|
+
...(occurredAt ? { occurredAt } : {}),
|
|
523
|
+
};
|
|
260
524
|
}
|
|
261
525
|
}
|
|
262
526
|
|
|
@@ -310,6 +574,9 @@ export function createJourneyContext(
|
|
|
310
574
|
}
|
|
311
575
|
|
|
312
576
|
await resumeFromWait();
|
|
577
|
+
// Refresh the memoized clock snapshot so a `ctx.when` chain after this wait
|
|
578
|
+
// reads a replay-stable instant (eviction engine) rather than the seed.
|
|
579
|
+
await refreshNow();
|
|
313
580
|
|
|
314
581
|
return { timedOut, ...(properties ? { properties } : {}) };
|
|
315
582
|
};
|
|
@@ -319,6 +586,12 @@ export function createJourneyContext(
|
|
|
319
586
|
timezone: resolvedTimezone,
|
|
320
587
|
window: defaultSendWindow,
|
|
321
588
|
ifPast: "next",
|
|
589
|
+
// `ctx.when` resolves instants synchronously per chain, so it reads the
|
|
590
|
+
// memoized clock through a cached snapshot refreshed on each access. The
|
|
591
|
+
// memoized DurableContext.now() returns the SAME Date across replays, so a
|
|
592
|
+
// synchronous read of the latest resolved value is replay-stable; a
|
|
593
|
+
// pre-eviction fallback uses the live clock (best-effort, unchanged today).
|
|
594
|
+
now: () => latestNow,
|
|
322
595
|
}),
|
|
323
596
|
|
|
324
597
|
async sleep({ duration, label }) {
|
|
@@ -334,25 +607,30 @@ export function createJourneyContext(
|
|
|
334
607
|
throw new TypeError("sleepUntil: invalid date");
|
|
335
608
|
}
|
|
336
609
|
|
|
337
|
-
// Compute the wake delay ONCE. Durability comes
|
|
338
|
-
// the deadline across replays/restarts; a past
|
|
339
|
-
|
|
610
|
+
// Compute the wake delay ONCE off the memoized clock. Durability comes
|
|
611
|
+
// from Hatchet preserving the deadline across replays/restarts; a past
|
|
612
|
+
// instant gives ms = 0. Reading the memoized now keeps the recomputed delta
|
|
613
|
+
// replay-stable on an eviction engine.
|
|
614
|
+
const ms = Math.max(0, target - (await refreshNow()).getTime());
|
|
340
615
|
return performSleep(
|
|
341
616
|
ms,
|
|
342
617
|
opts?.label ?? `wait-until:${new Date(target).toISOString()}`,
|
|
343
618
|
);
|
|
344
619
|
},
|
|
345
620
|
|
|
346
|
-
async waitForEvent({ event, timeout, label, lookback }) {
|
|
621
|
+
async waitForEvent({ event, timeout, label, lookback, where }) {
|
|
347
622
|
return performWaitForEvent(
|
|
348
623
|
event,
|
|
349
624
|
timeout,
|
|
350
625
|
label ?? `wait-event:${event}`,
|
|
351
626
|
lookback,
|
|
627
|
+
normalizeWhere(where),
|
|
352
628
|
);
|
|
353
629
|
},
|
|
354
630
|
|
|
355
631
|
async checkpoint(label) {
|
|
632
|
+
// A checkpoint also advances the "site" the next side effect inherits.
|
|
633
|
+
setBoundaryLabel(label);
|
|
356
634
|
await db
|
|
357
635
|
.update(journeyStates)
|
|
358
636
|
.set({ currentNodeId: label, updatedAt: new Date() })
|
|
@@ -364,23 +642,107 @@ export function createJourneyContext(
|
|
|
364
642
|
userId: targetUserId,
|
|
365
643
|
userEmail: targetEmail,
|
|
366
644
|
properties,
|
|
645
|
+
idempotencyLabel,
|
|
367
646
|
}) {
|
|
368
647
|
// Keep the PUBLIC `TriggerOptions.properties` field name (decision #13 —
|
|
369
648
|
// renaming it would break consumer journeys + scaffold). Map it to the
|
|
370
649
|
// engine-internal `eventProperties` bag here; no `contactProperties` by
|
|
371
650
|
// default (a future `TriggerOptions.contactProperties` is deferred).
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
651
|
+
//
|
|
652
|
+
// EXACTLY-ONCE across a durable replay: when inside a journey run, derive a
|
|
653
|
+
// deterministic key (`journeyTrigger:<runAnchor>:<site>:<event>`) so a
|
|
654
|
+
// replay re-pushing this trigger is a no-op. `site` = explicit `idempotencyLabel`
|
|
655
|
+
// ?? the nearest authored wait label ?? the event name. ingestEvent inserts
|
|
656
|
+
// user_events with onConflictDoNothing on the idempotencyKey index and
|
|
657
|
+
// returns early on a duplicate, so NONE of the Hatchet push, checkExits,
|
|
658
|
+
// contact upsert, or analytics alias re-fire. Layer 1 (memoize) skips the
|
|
659
|
+
// ingest call entirely before the DB is touched when eviction is live.
|
|
660
|
+
const boundary = getJourneyBoundary();
|
|
661
|
+
let idempotencyKey: string | undefined;
|
|
662
|
+
if (boundary) {
|
|
663
|
+
const site = idempotencyLabel ?? boundary.currentLabel ?? event;
|
|
664
|
+
idempotencyKey = deriveJourneyKey({
|
|
665
|
+
kind: "trigger",
|
|
666
|
+
anchor: boundary.runAnchor,
|
|
667
|
+
site,
|
|
668
|
+
discriminant: event,
|
|
669
|
+
});
|
|
670
|
+
registerKey(boundary, idempotencyKey);
|
|
671
|
+
}
|
|
672
|
+
|
|
673
|
+
const runIngest = () =>
|
|
674
|
+
ingestEvent({
|
|
675
|
+
db,
|
|
676
|
+
registry,
|
|
677
|
+
hatchet,
|
|
678
|
+
logger,
|
|
679
|
+
event: {
|
|
680
|
+
event,
|
|
681
|
+
userId: targetUserId,
|
|
682
|
+
userEmail: targetEmail ?? userEmail,
|
|
683
|
+
eventProperties: properties ?? {},
|
|
684
|
+
// Cross-journey trigger (ctx.trigger).
|
|
685
|
+
source: "journey",
|
|
686
|
+
...(idempotencyKey ? { idempotencyKey } : {}),
|
|
687
|
+
},
|
|
688
|
+
});
|
|
689
|
+
|
|
690
|
+
if (boundary && idempotencyKey) {
|
|
691
|
+
await boundary.memoize([idempotencyKey], runIngest);
|
|
692
|
+
} else {
|
|
693
|
+
await runIngest();
|
|
694
|
+
}
|
|
695
|
+
},
|
|
696
|
+
|
|
697
|
+
async now() {
|
|
698
|
+
return refreshNow();
|
|
699
|
+
},
|
|
700
|
+
|
|
701
|
+
async once<T>(key: string, compute: () => Promise<T> | T): Promise<T> {
|
|
702
|
+
// DB-backed record-once, durable on ANY engine. Read the current state
|
|
703
|
+
// row's context; if this key was already recorded (an earlier run of this
|
|
704
|
+
// enrollment, or a replay-from-top), return the stored value WITHOUT
|
|
705
|
+
// re-running `compute`. Otherwise compute, persist under the reserved
|
|
706
|
+
// `__once__` namespace, and return. The persist uses a jsonb merge keyed on
|
|
707
|
+
// a PARAMETERIZED path so an attacker-controlled `key` cannot inject SQL,
|
|
708
|
+
// and so a concurrent `checkpoint`/`once` write to a different path is not
|
|
709
|
+
// clobbered.
|
|
710
|
+
const read = async (): Promise<Record<string, unknown>> => {
|
|
711
|
+
const row = await db.query.journeyStates.findFirst({
|
|
712
|
+
where: eq(journeyStates.id, stateId),
|
|
713
|
+
columns: { context: true },
|
|
714
|
+
});
|
|
715
|
+
const ctxBag = (row?.context ?? {}) as Record<string, unknown>;
|
|
716
|
+
return (ctxBag.__once__ ?? {}) as Record<string, unknown>;
|
|
717
|
+
};
|
|
718
|
+
|
|
719
|
+
const onceBag = await read();
|
|
720
|
+
if (Object.hasOwn(onceBag, key)) {
|
|
721
|
+
return onceBag[key] as T;
|
|
722
|
+
}
|
|
723
|
+
|
|
724
|
+
const value = await compute();
|
|
725
|
+
// Persist under context.__once__.<key>. NOTE jsonb_set with
|
|
726
|
+
// create_missing=true cannot create a NESTED key whose parent object is
|
|
727
|
+
// absent (a fresh '{}' has no '__once__'), so we set the TOP-LEVEL
|
|
728
|
+
// '__once__' to (its existing bag) MERGED with the single new key via `||`.
|
|
729
|
+
// This creates '__once__' when missing AND preserves sibling once-keys.
|
|
730
|
+
// `key` and the value are bound parameters (jsonb_build_object), so the
|
|
731
|
+
// write is injection-safe.
|
|
732
|
+
await db
|
|
733
|
+
.update(journeyStates)
|
|
734
|
+
.set({
|
|
735
|
+
context: sql`jsonb_set(
|
|
736
|
+
coalesce(${journeyStates.context}, '{}'::jsonb),
|
|
737
|
+
'{__once__}',
|
|
738
|
+
coalesce(${journeyStates.context} -> '__once__', '{}'::jsonb)
|
|
739
|
+
|| jsonb_build_object(${key}::text, ${JSON.stringify(value ?? null)}::jsonb),
|
|
740
|
+
true
|
|
741
|
+
)`,
|
|
742
|
+
updatedAt: new Date(),
|
|
743
|
+
})
|
|
744
|
+
.where(eq(journeyStates.id, stateId));
|
|
745
|
+
return value;
|
|
384
746
|
},
|
|
385
747
|
|
|
386
748
|
guard: {
|
|
@@ -455,12 +817,18 @@ export function createJourneyContext(
|
|
|
455
817
|
|
|
456
818
|
async events({
|
|
457
819
|
userId: targetUserId,
|
|
820
|
+
event,
|
|
458
821
|
limit = 50,
|
|
459
822
|
within,
|
|
460
823
|
}): Promise<RecentEvent[]> {
|
|
461
824
|
const conditions = [eq(userEvents.userId, targetUserId)];
|
|
825
|
+
if (event) {
|
|
826
|
+
conditions.push(eq(userEvents.event, event));
|
|
827
|
+
}
|
|
462
828
|
if (within) {
|
|
463
|
-
const since = new Date(
|
|
829
|
+
const since = new Date(
|
|
830
|
+
(await refreshNow()).getTime() - durationToMs(within),
|
|
831
|
+
);
|
|
464
832
|
conditions.push(gte(userEvents.occurredAt, since));
|
|
465
833
|
}
|
|
466
834
|
const rows = await db
|
package/src/lib/boot.ts
CHANGED
|
@@ -25,10 +25,13 @@ import { API_VERSION } from "../env.js";
|
|
|
25
25
|
// rather than risking a stale hard-coded version slipping into structured logs.
|
|
26
26
|
const FALLBACK_ENGINE_VERSION = "unknown";
|
|
27
27
|
|
|
28
|
-
//
|
|
29
|
-
//
|
|
30
|
-
|
|
28
|
+
// The Studio SPA is served by the API itself at `/studio` (static dist with an
|
|
29
|
+
// SPA fallback — see `mountStudio`), so its URL is always the running server's
|
|
30
|
+
// own origin, in dev and prod alike. A scaffolded app has no separate Vite dev
|
|
31
|
+
// server, so we must NOT point at one (the old hard-coded `:5173` 404'd for
|
|
32
|
+
// every consumer).
|
|
31
33
|
const DOCS_URL = "https://docs.hogsend.com";
|
|
34
|
+
const DISCORD_URL = "https://discord.gg/rv6eZNvYrr";
|
|
32
35
|
|
|
33
36
|
let cachedEngineVersion: string | undefined;
|
|
34
37
|
|
|
@@ -135,9 +138,10 @@ export function reportApiReady(info: ApiReadyInfo): void {
|
|
|
135
138
|
testModeLine,
|
|
136
139
|
"",
|
|
137
140
|
` ${label("API")}${color.cyan(localUrl)}`,
|
|
141
|
+
` ${label("Studio")}${color.cyan(`${localUrl}/studio`)}`,
|
|
138
142
|
` ${label("Docs")}${color.cyan(`${localUrl}/docs`)}`,
|
|
139
|
-
` ${label("Studio")}${color.cyan(STUDIO_DEV_URL)}`,
|
|
140
143
|
` ${label("Guides")}${color.cyan(DOCS_URL)}`,
|
|
144
|
+
` ${label("Discord")}${color.cyan(DISCORD_URL)}`,
|
|
141
145
|
"",
|
|
142
146
|
` ${dim("Next")} fire a test event in ${color.cyan("Studio › Debug")} ${dim("·")} run the worker: ${color.cyan("pnpm worker:dev")}`,
|
|
143
147
|
]);
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Pure unfurl-bot + prefetch detection for the click route.
|
|
3
|
+
*
|
|
4
|
+
* Link-preview bots (Discord, Slack, Telegram, Twitter, Facebook, …) AUTO-FETCH
|
|
5
|
+
* any URL the moment it is DM'd/posted — BEFORE a human ever clicks — to render
|
|
6
|
+
* a preview card. Browser/email prefetch does the same. We still record the
|
|
7
|
+
* click + 302 for those hits (they ARE a fetch of the redirect), but we must NOT
|
|
8
|
+
* re-ingest them onto the journey bus: otherwise a single personal link DM'd in
|
|
9
|
+
* Discord would phantom-enroll the recipient before they act. This is the
|
|
10
|
+
* load-bearing guard for the Discord/connector campaign use case.
|
|
11
|
+
*
|
|
12
|
+
* Kept pure (no Hono dependency) so it is trivially unit-testable and reusable.
|
|
13
|
+
*/
|
|
14
|
+
const BOT_UA_RE =
|
|
15
|
+
/Discordbot|Slackbot|Slack-ImgProxy|Twitterbot|TelegramBot|facebookexternalhit|WhatsApp|LinkedInBot|SkypeUriPreview|Googlebot|GoogleImageProxy|Feedfetcher|bingbot|redditbot/i;
|
|
16
|
+
|
|
17
|
+
export interface BotPrefetchHeaders {
|
|
18
|
+
userAgent?: string | null;
|
|
19
|
+
/** `Purpose` request header (legacy Chrome/Safari prefetch). */
|
|
20
|
+
purpose?: string | null;
|
|
21
|
+
/** `X-Purpose` request header (Safari). */
|
|
22
|
+
xPurpose?: string | null;
|
|
23
|
+
/** `X-Moz` request header (Firefox prefetch — value `prefetch`). */
|
|
24
|
+
xMozPrefetch?: string | null;
|
|
25
|
+
/**
|
|
26
|
+
* `Sec-Purpose` request header — modern Chromium (Chrome/Edge 121+)
|
|
27
|
+
* Speculation-Rules prefetch/prerender, sent with a REAL browser UA. Values
|
|
28
|
+
* like `prefetch` or `prefetch;prerender`.
|
|
29
|
+
*/
|
|
30
|
+
secPurpose?: string | null;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* True when the request looks like an automated unfurl bot or a speculative
|
|
35
|
+
* prefetch/prerender rather than a real human click.
|
|
36
|
+
*/
|
|
37
|
+
export function isBotOrPrefetch(headers: BotPrefetchHeaders): boolean {
|
|
38
|
+
const { userAgent, purpose, xPurpose, xMozPrefetch, secPurpose } = headers;
|
|
39
|
+
if (userAgent && BOT_UA_RE.test(userAgent)) return true;
|
|
40
|
+
const p = purpose?.toLowerCase();
|
|
41
|
+
if (p === "prefetch" || p === "preview") return true;
|
|
42
|
+
const xp = xPurpose?.toLowerCase();
|
|
43
|
+
if (xp === "prefetch" || xp === "preview") return true;
|
|
44
|
+
if (xMozPrefetch) return true;
|
|
45
|
+
const sp = secPurpose?.toLowerCase();
|
|
46
|
+
if (sp && (sp.includes("prefetch") || sp.includes("prerender"))) return true;
|
|
47
|
+
return false;
|
|
48
|
+
}
|
package/src/lib/bucket-emit.ts
CHANGED
|
@@ -125,6 +125,7 @@ export async function emitBucketTransition(opts: {
|
|
|
125
125
|
userId,
|
|
126
126
|
userEmail: userEmail ?? "",
|
|
127
127
|
eventProperties: properties,
|
|
128
|
+
source: "bucket",
|
|
128
129
|
idempotencyKey,
|
|
129
130
|
},
|
|
130
131
|
});
|
|
@@ -143,6 +144,7 @@ export async function emitBucketTransition(opts: {
|
|
|
143
144
|
userId,
|
|
144
145
|
userEmail: userEmail ?? "",
|
|
145
146
|
eventProperties: properties,
|
|
147
|
+
source: "bucket",
|
|
146
148
|
idempotencyKey: `bucket:${bucket.id}:${userId}:${kind}:${epoch}:generic`,
|
|
147
149
|
},
|
|
148
150
|
});
|