@hogsend/engine 0.38.2 → 0.39.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 -7
- package/src/container.ts +133 -10
- package/src/index.ts +23 -0
- package/src/journeys/define-journey.ts +142 -2
- package/src/journeys/graph/build-graph.ts +1159 -0
- package/src/journeys/journey-boundary.ts +33 -0
- package/src/journeys/journey-context.ts +58 -8
- package/src/journeys/journey-log.ts +64 -0
- package/src/journeys/journey-source-locations-singleton.ts +19 -0
- package/src/journeys/journey-sources-singleton.ts +14 -0
- package/src/journeys/registry.ts +148 -5
- package/src/lib/email.ts +17 -6
- package/src/lib/ingestion.ts +13 -0
- package/src/lib/tracked.ts +32 -0
- package/src/lists/define-list.ts +19 -3
- package/src/routes/admin/index.ts +2 -0
- package/src/routes/admin/journeys.ts +278 -0
- package/src/routes/admin/open-editor.ts +106 -0
- package/src/routes/emails/index.ts +25 -1
- package/src/worker.ts +15 -2
|
@@ -152,6 +152,39 @@ export function deriveJourneyKey(opts: {
|
|
|
152
152
|
return `${KEY_PREFIX[opts.kind]}:${opts.anchor}:${opts.site}:${opts.discriminant}`;
|
|
153
153
|
}
|
|
154
154
|
|
|
155
|
+
/**
|
|
156
|
+
* Recover the `<site>` discriminant embedded in a journey SEND idempotency key
|
|
157
|
+
* (`journeySend:<anchor>:<site>:<discriminant>`), given the replay-stable
|
|
158
|
+
* `anchor` (`boundary.runAnchor`) and the `discriminant` (the send's
|
|
159
|
+
* templateKey). Returns undefined when `key` is absent or is not a `journeySend:`
|
|
160
|
+
* key with the expected anchor/discriminant framing.
|
|
161
|
+
*
|
|
162
|
+
* This is how the SEND transition log recovers the EXACT `site` the mailer used
|
|
163
|
+
* when it derived the key via {@link deriveJourneyKey} — the SAME value
|
|
164
|
+
* `buildJourneyGraph` uses for the send node id (`send:<site>`) — so the log row
|
|
165
|
+
* joins the graph node WITHOUT recomputing the site (a recompute of
|
|
166
|
+
* `currentLabel ?? templateKey` would miss an explicit `idempotencyLabel`). Site
|
|
167
|
+
* strings may themselves contain `:` (e.g. `wait-event:foo`), so we strip the
|
|
168
|
+
* exact prefix/suffix rather than split on `:`.
|
|
169
|
+
*/
|
|
170
|
+
export function parseJourneySendSite(opts: {
|
|
171
|
+
key: string | null | undefined;
|
|
172
|
+
anchor: string;
|
|
173
|
+
discriminant: string;
|
|
174
|
+
}): string | undefined {
|
|
175
|
+
if (!opts.key) return undefined;
|
|
176
|
+
const prefix = `${KEY_PREFIX.send}:${opts.anchor}:`;
|
|
177
|
+
const suffix = `:${opts.discriminant}`;
|
|
178
|
+
if (
|
|
179
|
+
!opts.key.startsWith(prefix) ||
|
|
180
|
+
!opts.key.endsWith(suffix) ||
|
|
181
|
+
opts.key.length <= prefix.length + suffix.length
|
|
182
|
+
) {
|
|
183
|
+
return undefined;
|
|
184
|
+
}
|
|
185
|
+
return opts.key.slice(prefix.length, opts.key.length - suffix.length);
|
|
186
|
+
}
|
|
187
|
+
|
|
155
188
|
/**
|
|
156
189
|
* Record `key` as used in this run, throwing loudly if it collides with a key an
|
|
157
190
|
* earlier side effect in the same run already derived. A collision means two
|
|
@@ -53,6 +53,7 @@ import {
|
|
|
53
53
|
getJourneyBoundary,
|
|
54
54
|
registerKey,
|
|
55
55
|
} from "./journey-boundary.js";
|
|
56
|
+
import { logTransition } from "./journey-log.js";
|
|
56
57
|
|
|
57
58
|
/** Journey statuses that are terminal — a journey in any of these must never be
|
|
58
59
|
* resurrected back to "active" by a wait resuming. Exported so the durable task
|
|
@@ -211,7 +212,10 @@ export function createJourneyContext(
|
|
|
211
212
|
// Enter a durable wait: flip "active" → "waiting", but ONLY if the journey
|
|
212
213
|
// hasn't already reached a terminal state (e.g. exitOn fired before we got
|
|
213
214
|
// here). A no-op update means the journey is already done — abort the run.
|
|
214
|
-
const enterWait = async (
|
|
215
|
+
const enterWait = async (
|
|
216
|
+
nodeId: string,
|
|
217
|
+
action: "sleep" | "wait",
|
|
218
|
+
): Promise<void> => {
|
|
215
219
|
const entered = await db
|
|
216
220
|
.update(journeyStates)
|
|
217
221
|
.set({ status: "waiting", currentNodeId: nodeId, updatedAt: new Date() })
|
|
@@ -226,13 +230,27 @@ export function createJourneyContext(
|
|
|
226
230
|
if (entered.length === 0) {
|
|
227
231
|
throw new JourneyExitedError(stateId);
|
|
228
232
|
}
|
|
233
|
+
|
|
234
|
+
// Fire-and-forget transition log (best-effort; never affects the wait). The
|
|
235
|
+
// boundary's current label (if any) is the node we're leaving.
|
|
236
|
+
const prior = getJourneyBoundary()?.currentLabel;
|
|
237
|
+
logTransition({
|
|
238
|
+
db,
|
|
239
|
+
journeyStateId: stateId,
|
|
240
|
+
from: prior && prior !== nodeId ? prior : null,
|
|
241
|
+
to: nodeId,
|
|
242
|
+
action,
|
|
243
|
+
});
|
|
229
244
|
};
|
|
230
245
|
|
|
231
246
|
// Resume from a durable wait: flip "waiting" → "active", but ONLY if the row
|
|
232
247
|
// is still "waiting". If an exit/cancel landed during the wait the row is no
|
|
233
248
|
// longer "waiting" — abort instead of reviving a terminated journey to active
|
|
234
249
|
// (which would let a post-wait side effect fire after the journey exited).
|
|
235
|
-
const resumeFromWait = async (
|
|
250
|
+
const resumeFromWait = async (
|
|
251
|
+
nodeId: string,
|
|
252
|
+
detail?: Record<string, unknown>,
|
|
253
|
+
): Promise<void> => {
|
|
236
254
|
const resumed = await db
|
|
237
255
|
.update(journeyStates)
|
|
238
256
|
.set({ status: "active", updatedAt: new Date() })
|
|
@@ -244,6 +262,16 @@ export function createJourneyContext(
|
|
|
244
262
|
if (resumed.length === 0) {
|
|
245
263
|
throw new JourneyExitedError(stateId);
|
|
246
264
|
}
|
|
265
|
+
|
|
266
|
+
// Fire-and-forget resume transition (best-effort; never affects the run).
|
|
267
|
+
logTransition({
|
|
268
|
+
db,
|
|
269
|
+
journeyStateId: stateId,
|
|
270
|
+
from: null,
|
|
271
|
+
to: nodeId,
|
|
272
|
+
action: "resume",
|
|
273
|
+
...(detail ? { detail } : {}),
|
|
274
|
+
});
|
|
247
275
|
};
|
|
248
276
|
|
|
249
277
|
// Durable sleep with the guarded waiting → active lifecycle. `sleep` passes a
|
|
@@ -254,10 +282,10 @@ export function createJourneyContext(
|
|
|
254
282
|
nodeId: string,
|
|
255
283
|
): Promise<{ sleptAt: string; resumedAt: string }> => {
|
|
256
284
|
const sleptAt = new Date().toISOString();
|
|
257
|
-
await enterWait(nodeId);
|
|
285
|
+
await enterWait(nodeId, "sleep");
|
|
258
286
|
await hatchetCtx.sleepFor(durationOrMs);
|
|
259
287
|
const resumedAt = new Date().toISOString();
|
|
260
|
-
await resumeFromWait();
|
|
288
|
+
await resumeFromWait(nodeId);
|
|
261
289
|
// Refresh the memoized clock snapshot so a `ctx.when` chain used right after
|
|
262
290
|
// this wait reads a replay-stable instant (on an eviction engine) instead of
|
|
263
291
|
// the construction-time seed — see `latestNow`.
|
|
@@ -380,7 +408,7 @@ export function createJourneyContext(
|
|
|
380
408
|
return { timedOut: false, properties: preHit };
|
|
381
409
|
}
|
|
382
410
|
|
|
383
|
-
await enterWait(nodeId);
|
|
411
|
+
await enterWait(nodeId, "wait");
|
|
384
412
|
|
|
385
413
|
let outcome: WaitForEventResult;
|
|
386
414
|
while (true) {
|
|
@@ -433,7 +461,7 @@ export function createJourneyContext(
|
|
|
433
461
|
// if it matches, else re-arms toward the durable deadline.
|
|
434
462
|
}
|
|
435
463
|
|
|
436
|
-
await resumeFromWait();
|
|
464
|
+
await resumeFromWait(nodeId, { timedOut: outcome.timedOut });
|
|
437
465
|
await clearDeadline();
|
|
438
466
|
return outcome;
|
|
439
467
|
};
|
|
@@ -524,7 +552,7 @@ export function createJourneyContext(
|
|
|
524
552
|
}
|
|
525
553
|
}
|
|
526
554
|
|
|
527
|
-
await enterWait(nodeId);
|
|
555
|
+
await enterWait(nodeId, "wait");
|
|
528
556
|
|
|
529
557
|
// Wait for the user-scoped event or the timeout. The event branch filters on
|
|
530
558
|
// the pushed payload's top-level `userId` (see `ingestEvent`); the SDK turns
|
|
@@ -573,7 +601,7 @@ export function createJourneyContext(
|
|
|
573
601
|
}
|
|
574
602
|
}
|
|
575
603
|
|
|
576
|
-
await resumeFromWait();
|
|
604
|
+
await resumeFromWait(nodeId, { timedOut });
|
|
577
605
|
// Refresh the memoized clock snapshot so a `ctx.when` chain after this wait
|
|
578
606
|
// reads a replay-stable instant (eviction engine) rather than the seed.
|
|
579
607
|
await refreshNow();
|
|
@@ -629,12 +657,22 @@ export function createJourneyContext(
|
|
|
629
657
|
},
|
|
630
658
|
|
|
631
659
|
async checkpoint(label) {
|
|
660
|
+
const prior = getJourneyBoundary()?.currentLabel;
|
|
632
661
|
// A checkpoint also advances the "site" the next side effect inherits.
|
|
633
662
|
setBoundaryLabel(label);
|
|
634
663
|
await db
|
|
635
664
|
.update(journeyStates)
|
|
636
665
|
.set({ currentNodeId: label, updatedAt: new Date() })
|
|
637
666
|
.where(eq(journeyStates.id, stateId));
|
|
667
|
+
|
|
668
|
+
// Fire-and-forget checkpoint transition (best-effort; never throws).
|
|
669
|
+
logTransition({
|
|
670
|
+
db,
|
|
671
|
+
journeyStateId: stateId,
|
|
672
|
+
from: prior && prior !== label ? prior : null,
|
|
673
|
+
to: label,
|
|
674
|
+
action: "checkpoint",
|
|
675
|
+
});
|
|
638
676
|
},
|
|
639
677
|
|
|
640
678
|
async trigger({
|
|
@@ -692,6 +730,18 @@ export function createJourneyContext(
|
|
|
692
730
|
} else {
|
|
693
731
|
await runIngest();
|
|
694
732
|
}
|
|
733
|
+
|
|
734
|
+
// Fire-and-forget trigger transition (best-effort; never throws). Inside
|
|
735
|
+
// the exactly-once path, so a replay re-logs — acceptable for a timeline.
|
|
736
|
+
// `to` mirrors the graph's trigger node id (`trigger:<event>`).
|
|
737
|
+
logTransition({
|
|
738
|
+
db,
|
|
739
|
+
journeyStateId: stateId,
|
|
740
|
+
from: boundary?.currentLabel ?? null,
|
|
741
|
+
to: `trigger:${event}`,
|
|
742
|
+
action: "trigger",
|
|
743
|
+
detail: { event },
|
|
744
|
+
});
|
|
695
745
|
},
|
|
696
746
|
|
|
697
747
|
async now() {
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
import { type Database, journeyLogs } from "@hogsend/db";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* The transition-log action vocabulary. These strings are written verbatim to
|
|
5
|
+
* `journey_logs.action` (a free-text column) and read by the Studio instance
|
|
6
|
+
* drawer timeline + the Phase-3 per-node *reached* funnel. Keep them in lockstep
|
|
7
|
+
* with the graph extractor's node semantics.
|
|
8
|
+
*/
|
|
9
|
+
export type JourneyLogAction =
|
|
10
|
+
| "entered"
|
|
11
|
+
| "sleep"
|
|
12
|
+
| "wait"
|
|
13
|
+
| "resume"
|
|
14
|
+
| "checkpoint"
|
|
15
|
+
| "send"
|
|
16
|
+
| "trigger"
|
|
17
|
+
| "completed"
|
|
18
|
+
| "failed"
|
|
19
|
+
| "exited";
|
|
20
|
+
|
|
21
|
+
export interface LogTransitionArgs {
|
|
22
|
+
db: Database;
|
|
23
|
+
journeyStateId: string;
|
|
24
|
+
/** Source node id (best-effort; null/undefined when unknown or not tracked). */
|
|
25
|
+
from?: string | null;
|
|
26
|
+
/** Destination node id (the node reached by this transition). */
|
|
27
|
+
to?: string | null;
|
|
28
|
+
action: JourneyLogAction;
|
|
29
|
+
detail?: Record<string, unknown>;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* Best-effort, STRICTLY fire-and-forget transition log. Inserts one
|
|
34
|
+
* `journey_logs` row for observability.
|
|
35
|
+
*
|
|
36
|
+
* SAFETY: this runs on the replay-safe journey hot path, so it must NEVER reject
|
|
37
|
+
* into or alter journey execution / replay-safety. Any failure — a synchronous
|
|
38
|
+
* build/dispatch throw OR a rejected insert — is swallowed to a silent no-op. It
|
|
39
|
+
* returns `void`; callers must NOT `await` it in a way that could throw, and no
|
|
40
|
+
* existing side effect may be reordered or gated on it.
|
|
41
|
+
*
|
|
42
|
+
* REPLAY: a journey is a Hatchet durable task that replays-from-top on eviction,
|
|
43
|
+
* so a replay RE-LOGS (duplicate rows). That is acceptable for a timeline — the
|
|
44
|
+
* Phase-3 reach-counts use `count(DISTINCT journey_state_id)` per `to_node_id`.
|
|
45
|
+
* Do NOT attempt to dedupe log rows.
|
|
46
|
+
*/
|
|
47
|
+
export function logTransition(args: LogTransitionArgs): void {
|
|
48
|
+
try {
|
|
49
|
+
void args.db
|
|
50
|
+
.insert(journeyLogs)
|
|
51
|
+
.values({
|
|
52
|
+
journeyStateId: args.journeyStateId,
|
|
53
|
+
fromNodeId: args.from ?? null,
|
|
54
|
+
toNodeId: args.to ?? null,
|
|
55
|
+
action: args.action,
|
|
56
|
+
detail: args.detail ?? null,
|
|
57
|
+
})
|
|
58
|
+
.catch(() => {
|
|
59
|
+
// best-effort timeline write — never surface into journey execution
|
|
60
|
+
});
|
|
61
|
+
} catch {
|
|
62
|
+
// synchronous build/dispatch failure — swallow; logging must never throw
|
|
63
|
+
}
|
|
64
|
+
}
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
import type { JourneySourceLocation } from "@hogsend/core";
|
|
2
|
+
import { createSingleton } from "../lib/singleton.js";
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* Process-singleton: enabled journey id → its `defineJourney` call-site
|
|
6
|
+
* `{ path, line }`, installed by `buildJourneyRegistry` alongside the run-source
|
|
7
|
+
* map. Read by the container so the Studio journey-graph route can hand the
|
|
8
|
+
* editor a `cursor://file/<path>:<line>` deep link. Only journeys whose
|
|
9
|
+
* call-site was captured are present (e.g. bucket-generated reaction journeys
|
|
10
|
+
* have none).
|
|
11
|
+
*/
|
|
12
|
+
const singleton = createSingleton<Map<string, JourneySourceLocation>>(
|
|
13
|
+
"Journey source locations",
|
|
14
|
+
);
|
|
15
|
+
|
|
16
|
+
export const setJourneySourceLocations = singleton.set;
|
|
17
|
+
export const getJourneySourceLocations = singleton.get;
|
|
18
|
+
/** Reset the singleton — only for test cleanup. */
|
|
19
|
+
export const resetJourneySourceLocations = singleton.reset;
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import { createSingleton } from "../lib/singleton.js";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Process-singleton holding the map of enabled journey ids → their captured
|
|
5
|
+
* `run` source (`meta.id → runSource`), installed by `buildJourneyRegistry` and
|
|
6
|
+
* read by the container so the Studio journey-graph route can parse a journey's
|
|
7
|
+
* source lazily. Only journeys whose `runSource` was captured are present.
|
|
8
|
+
*/
|
|
9
|
+
const singleton = createSingleton<Map<string, string>>("Journey sources");
|
|
10
|
+
|
|
11
|
+
export const setJourneySources = singleton.set;
|
|
12
|
+
export const getJourneySources = singleton.get;
|
|
13
|
+
/** Reset the singleton — only for test cleanup. */
|
|
14
|
+
export const resetJourneySources = singleton.reset;
|
package/src/journeys/registry.ts
CHANGED
|
@@ -1,10 +1,15 @@
|
|
|
1
|
+
import type { JourneySourceLocation } from "@hogsend/core";
|
|
1
2
|
import { JourneyRegistry } from "@hogsend/core/registry";
|
|
2
3
|
import type { DefinedJourney } from "./define-journey.js";
|
|
4
|
+
import { setJourneySourceLocations } from "./journey-source-locations-singleton.js";
|
|
5
|
+
import { setJourneySources } from "./journey-sources-singleton.js";
|
|
3
6
|
import { setJourneyRegistry } from "./registry-singleton.js";
|
|
4
7
|
|
|
5
8
|
/**
|
|
6
9
|
* Parse the `ENABLED_JOURNEYS` filter. Returns `"*"` to enable all journeys, or
|
|
7
|
-
* a `Set` of journey ids to enable.
|
|
10
|
+
* a `Set` of journey ids to enable. Only an empty/undefined value or a literal
|
|
11
|
+
* `"*"` (after trim) means all; a whitespace-only value (e.g. `" "`) falls
|
|
12
|
+
* through to an empty `Set` (enables nothing).
|
|
8
13
|
*/
|
|
9
14
|
export function parseEnabledFilter(filter?: string): "*" | Set<string> {
|
|
10
15
|
if (!filter || filter.trim() === "*") return "*";
|
|
@@ -16,37 +21,175 @@ export function parseEnabledFilter(filter?: string): "*" | Set<string> {
|
|
|
16
21
|
);
|
|
17
22
|
}
|
|
18
23
|
|
|
24
|
+
/**
|
|
25
|
+
* Iterative Levenshtein edit distance (two-row). Private helper backing the
|
|
26
|
+
* "did you mean" suggestion in {@link resolveEnabledFilter}; there is no shared
|
|
27
|
+
* edit-distance utility in the repo.
|
|
28
|
+
*/
|
|
29
|
+
function levenshtein(a: string, b: string): number {
|
|
30
|
+
const m = a.length;
|
|
31
|
+
const n = b.length;
|
|
32
|
+
if (m === 0) return n;
|
|
33
|
+
if (n === 0) return m;
|
|
34
|
+
|
|
35
|
+
// `?? 0` guards are unreachable (indices stay in-bounds) but satisfy
|
|
36
|
+
// `noUncheckedIndexedAccess`.
|
|
37
|
+
let prev: number[] = Array.from({ length: n + 1 }, (_, i) => i);
|
|
38
|
+
for (let i = 1; i <= m; i++) {
|
|
39
|
+
const curr: number[] = [i];
|
|
40
|
+
for (let j = 1; j <= n; j++) {
|
|
41
|
+
const cost = a[i - 1] === b[j - 1] ? 0 : 1;
|
|
42
|
+
curr[j] = Math.min(
|
|
43
|
+
(prev[j] ?? 0) + 1, // deletion
|
|
44
|
+
(curr[j - 1] ?? 0) + 1, // insertion
|
|
45
|
+
(prev[j - 1] ?? 0) + cost, // substitution
|
|
46
|
+
);
|
|
47
|
+
}
|
|
48
|
+
prev = curr;
|
|
49
|
+
}
|
|
50
|
+
return prev[n] ?? 0;
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/**
|
|
54
|
+
* Closest known id to `id` within a small edit-distance threshold, or
|
|
55
|
+
* `undefined` when nothing is close enough to be a plausible typo. The
|
|
56
|
+
* threshold scales with id length so short ids don't over-suggest.
|
|
57
|
+
*/
|
|
58
|
+
function closestKnownId(id: string, knownIds: string[]): string | undefined {
|
|
59
|
+
const threshold = Math.max(2, Math.floor(id.length / 3));
|
|
60
|
+
let best: string | undefined;
|
|
61
|
+
let bestDistance = Number.POSITIVE_INFINITY;
|
|
62
|
+
for (const known of knownIds) {
|
|
63
|
+
const distance = levenshtein(id, known);
|
|
64
|
+
if (distance < bestDistance) {
|
|
65
|
+
bestDistance = distance;
|
|
66
|
+
best = known;
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
return best !== undefined && bestDistance <= threshold ? best : undefined;
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/**
|
|
73
|
+
* Resolve AND validate the `ENABLED_JOURNEYS` filter against the closed set of
|
|
74
|
+
* known journey ids. `ENABLED_JOURNEYS` is operator config over a fully-known
|
|
75
|
+
* universe (`journeys.map(j => j.meta.id)` plus `extraKnownIds`), so a filter id
|
|
76
|
+
* that matches no journey is a typo or a stale reference to a renamed/removed
|
|
77
|
+
* journey — silently dropping it means the intended journey never registers and
|
|
78
|
+
* never fires in prod. Fail loud instead (the analog of the EMAIL_PROVIDER /
|
|
79
|
+
* ANALYTICS_PROVIDER boot throws):
|
|
80
|
+
*
|
|
81
|
+
* - `"*"` / empty → `"*"` (enable all); no validation, no throw.
|
|
82
|
+
* - **Empty top-level `journeys[]`** → no validation, no throw. `ENABLED_JOURNEYS`
|
|
83
|
+
* restricts the top-level journeys; a bucket-only client injects none here
|
|
84
|
+
* (its bucket-reaction journeys are registered separately, gated by
|
|
85
|
+
* `ENABLED_BUCKETS`), so there is nothing this filter can validate.
|
|
86
|
+
* - Otherwise validate every filter id against ALL known ids — the top-level
|
|
87
|
+
* journey ids (INCLUDING `meta.enabled: false` ones, since a disabled journey
|
|
88
|
+
* is a known id, not a typo) PLUS `extraKnownIds` (the bucket-reaction journey
|
|
89
|
+
* ids `bucket-<id>-on-<kind>`, which ARE registered journeys even though they
|
|
90
|
+
* bypass this filter). Unknown ids throw a single error naming each one (with a
|
|
91
|
+
* `(did you mean "…"?)` when a close known id exists) plus the known-id list.
|
|
92
|
+
* - An empty `Set` (e.g. filter `","`) has nothing to validate → no throw
|
|
93
|
+
* (enables nothing; pre-existing behavior).
|
|
94
|
+
*
|
|
95
|
+
* @param extraKnownIds additional valid ids not present in `journeys[]` (e.g.
|
|
96
|
+
* bucket-reaction journey ids) — accepted in the filter without a throw.
|
|
97
|
+
*
|
|
98
|
+
* Pure/synchronous; both boot paths ({@link buildJourneyRegistry} at container
|
|
99
|
+
* boot, {@link selectJourneyTasks} at worker boot) route through it.
|
|
100
|
+
*/
|
|
101
|
+
export function resolveEnabledFilter(
|
|
102
|
+
journeys: DefinedJourney[],
|
|
103
|
+
enabledFilter?: string,
|
|
104
|
+
extraKnownIds?: string[],
|
|
105
|
+
): "*" | Set<string> {
|
|
106
|
+
const enabled = parseEnabledFilter(enabledFilter);
|
|
107
|
+
if (enabled === "*") return enabled;
|
|
108
|
+
// Nothing to validate when no top-level journeys were injected.
|
|
109
|
+
if (journeys.length === 0) return enabled;
|
|
110
|
+
|
|
111
|
+
const allKnown = [
|
|
112
|
+
...journeys.map((j) => j.meta.id),
|
|
113
|
+
...(extraKnownIds ?? []),
|
|
114
|
+
];
|
|
115
|
+
const knownSet = new Set(allKnown);
|
|
116
|
+
const unknown = [...enabled].filter((id) => !knownSet.has(id));
|
|
117
|
+
if (unknown.length === 0) return enabled;
|
|
118
|
+
|
|
119
|
+
const details = unknown
|
|
120
|
+
.map((id) => {
|
|
121
|
+
const suggestion = closestKnownId(id, allKnown);
|
|
122
|
+
return suggestion ? `"${id}" (did you mean "${suggestion}"?)` : `"${id}"`;
|
|
123
|
+
})
|
|
124
|
+
.join(", ");
|
|
125
|
+
// `knownSet` is non-empty here (journeys[] was non-empty per the early
|
|
126
|
+
// return above), so there is always at least one known id to list.
|
|
127
|
+
const known = [...knownSet].map((id) => `"${id}"`).join(", ");
|
|
128
|
+
|
|
129
|
+
throw new Error(
|
|
130
|
+
`ENABLED_JOURNEYS references ${
|
|
131
|
+
unknown.length === 1 ? "an unknown journey id" : "unknown journey ids"
|
|
132
|
+
}: ${details}. Known journey ids: ${known}.`,
|
|
133
|
+
);
|
|
134
|
+
}
|
|
135
|
+
|
|
19
136
|
/**
|
|
20
137
|
* Build a {@link JourneyRegistry} from an injected array of journeys, applying
|
|
21
138
|
* the enabled filter, and install it as the process singleton (so durable tasks
|
|
22
|
-
* can resolve it). Returns the registry.
|
|
139
|
+
* can resolve it). Returns the registry. Throws (via
|
|
140
|
+
* {@link resolveEnabledFilter}) when the filter references an unknown journey.
|
|
141
|
+
*
|
|
142
|
+
* @param extraKnownIds additional valid ids (e.g. bucket-reaction journey ids)
|
|
143
|
+
* accepted in the filter without a throw — see {@link resolveEnabledFilter}.
|
|
23
144
|
*/
|
|
24
145
|
export function buildJourneyRegistry(
|
|
25
146
|
journeys: DefinedJourney[],
|
|
26
147
|
enabledFilter?: string,
|
|
148
|
+
extraKnownIds?: string[],
|
|
27
149
|
): JourneyRegistry {
|
|
28
150
|
const registry = new JourneyRegistry();
|
|
29
|
-
const enabled =
|
|
151
|
+
const enabled = resolveEnabledFilter(journeys, enabledFilter, extraKnownIds);
|
|
152
|
+
|
|
153
|
+
// Captured `run` sources for the enabled journeys (skip ones whose source
|
|
154
|
+
// failed to serialize). Installed as a sibling singleton so the container can
|
|
155
|
+
// expose it and the Studio journey-graph route can parse lazily.
|
|
156
|
+
const sources = new Map<string, string>();
|
|
157
|
+
// Captured `defineJourney` call-sites (skip ones with no capturable frame).
|
|
158
|
+
// Sibling singleton so the Studio route can build an "open in editor" link.
|
|
159
|
+
const locations = new Map<string, JourneySourceLocation>();
|
|
30
160
|
|
|
31
161
|
for (const journey of journeys) {
|
|
32
162
|
if (enabled === "*" || enabled.has(journey.meta.id)) {
|
|
33
163
|
registry.register(journey.meta);
|
|
164
|
+
if (journey.runSource) {
|
|
165
|
+
sources.set(journey.meta.id, journey.runSource);
|
|
166
|
+
}
|
|
167
|
+
if (journey.source) {
|
|
168
|
+
locations.set(journey.meta.id, journey.source);
|
|
169
|
+
}
|
|
34
170
|
}
|
|
35
171
|
}
|
|
36
172
|
|
|
37
173
|
setJourneyRegistry(registry);
|
|
174
|
+
setJourneySources(sources);
|
|
175
|
+
setJourneySourceLocations(locations);
|
|
38
176
|
return registry;
|
|
39
177
|
}
|
|
40
178
|
|
|
41
179
|
/**
|
|
42
180
|
* Select the Hatchet durable tasks for the enabled journeys from an injected
|
|
43
|
-
* array of journeys.
|
|
181
|
+
* array of journeys. Throws (via {@link resolveEnabledFilter}) when the filter
|
|
182
|
+
* references an unknown journey.
|
|
183
|
+
*
|
|
184
|
+
* @param extraKnownIds additional valid ids (e.g. bucket-reaction journey ids)
|
|
185
|
+
* accepted in the filter without a throw — see {@link resolveEnabledFilter}.
|
|
44
186
|
*/
|
|
45
187
|
export function selectJourneyTasks(
|
|
46
188
|
journeys: DefinedJourney[],
|
|
47
189
|
enabledFilter?: string,
|
|
190
|
+
extraKnownIds?: string[],
|
|
48
191
|
) {
|
|
49
|
-
const enabled =
|
|
192
|
+
const enabled = resolveEnabledFilter(journeys, enabledFilter, extraKnownIds);
|
|
50
193
|
return journeys
|
|
51
194
|
.filter((j) => enabled === "*" || enabled.has(j.meta.id))
|
|
52
195
|
.map((j) => j.task);
|
package/src/lib/email.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { generateUnsubscribeUrl } from "@hogsend/email";
|
|
1
|
+
import { generateUnsubscribeUrl, type TemplateName } from "@hogsend/email";
|
|
2
2
|
import {
|
|
3
3
|
deriveJourneyKey,
|
|
4
4
|
getJourneyBoundary,
|
|
@@ -29,7 +29,17 @@ export const getEmailService = _service.get;
|
|
|
29
29
|
export interface SendEmailOptions {
|
|
30
30
|
to: string;
|
|
31
31
|
userId: string;
|
|
32
|
-
|
|
32
|
+
/**
|
|
33
|
+
* The template to send. Typed as {@link TemplateName} — the union of keys the
|
|
34
|
+
* consumer has registered by augmenting `@hogsend/email`'s
|
|
35
|
+
* `TemplateRegistryMap` (see the consumer's `src/emails/templates.d.ts`). A
|
|
36
|
+
* key that was never registered (a typo, or a slash-key when the registry
|
|
37
|
+
* uses hyphen-keys) is a COMPILE error here, so a journey can no longer ship
|
|
38
|
+
* pointing at an email that doesn't exist. `getTemplate` also throws a loud,
|
|
39
|
+
* actionable error at send time as a runtime backstop for keys resolved
|
|
40
|
+
* dynamically (e.g. the public `POST /v1/emails`).
|
|
41
|
+
*/
|
|
42
|
+
template: TemplateName;
|
|
33
43
|
subject: string;
|
|
34
44
|
journeyName?: string;
|
|
35
45
|
journeyStateId?: string;
|
|
@@ -102,10 +112,11 @@ export async function sendEmail(
|
|
|
102
112
|
headers["List-Unsubscribe-Post"] = "List-Unsubscribe=One-Click";
|
|
103
113
|
}
|
|
104
114
|
|
|
105
|
-
// `sendEmail` is the
|
|
106
|
-
//
|
|
107
|
-
//
|
|
108
|
-
// `
|
|
115
|
+
// `sendEmail` is the journey entry point: the template key is typed against
|
|
116
|
+
// the registry (see `SendEmailOptions.template`), but `props` stay loose here
|
|
117
|
+
// (the helper injects `name`/`journeyName`/`body`/… below), so we build the
|
|
118
|
+
// options untyped and hand them to the typed `service.send`. Fully type-safe
|
|
119
|
+
// call sites use `container.emailService.send({ template, props })` directly.
|
|
109
120
|
const sendOptions = {
|
|
110
121
|
template: opts.template,
|
|
111
122
|
props: {
|
package/src/lib/ingestion.ts
CHANGED
|
@@ -8,6 +8,7 @@ import type { JourneyRegistry } from "@hogsend/core/registry";
|
|
|
8
8
|
import { type Database, journeyStates, userEvents } from "@hogsend/db";
|
|
9
9
|
import { and, eq, inArray, isNull } from "drizzle-orm";
|
|
10
10
|
import { checkBucketMembership } from "../buckets/check-membership.js";
|
|
11
|
+
import { logTransition } from "../journeys/journey-log.js";
|
|
11
12
|
import {
|
|
12
13
|
logResidualTwins,
|
|
13
14
|
mergeAnalyticsIdentities,
|
|
@@ -497,6 +498,18 @@ async function checkExits(
|
|
|
497
498
|
})
|
|
498
499
|
.where(inArray(journeyStates.id, statesToExit));
|
|
499
500
|
|
|
501
|
+
// Fire-and-forget EXIT transition logs (best-effort; the exit path is
|
|
502
|
+
// already best-effort around the hatchet cancel below). Never throws.
|
|
503
|
+
for (const id of statesToExit) {
|
|
504
|
+
logTransition({
|
|
505
|
+
db,
|
|
506
|
+
journeyStateId: id,
|
|
507
|
+
from: null,
|
|
508
|
+
to: "end-exited",
|
|
509
|
+
action: "exited",
|
|
510
|
+
});
|
|
511
|
+
}
|
|
512
|
+
|
|
500
513
|
// Cancel the live durable runs so a journey suspended in a sleep or
|
|
501
514
|
// `waitForEvent` can't resume and fire after it has exited. Best-effort: a
|
|
502
515
|
// run may have already finished, and the in-run resume guard
|
package/src/lib/tracked.ts
CHANGED
|
@@ -16,8 +16,10 @@ import { eq } from "drizzle-orm";
|
|
|
16
16
|
import {
|
|
17
17
|
deriveJourneyKey,
|
|
18
18
|
getJourneyBoundary,
|
|
19
|
+
parseJourneySendSite,
|
|
19
20
|
registerKey,
|
|
20
21
|
} from "../journeys/journey-boundary.js";
|
|
22
|
+
import { logTransition } from "../journeys/journey-log.js";
|
|
21
23
|
import { getListRegistry } from "../lists/registry-singleton.js";
|
|
22
24
|
import type { TestModeState } from "./domain-status.js";
|
|
23
25
|
import {
|
|
@@ -455,6 +457,36 @@ async function sendTrackedEmailInner<K extends TemplateName>(
|
|
|
455
457
|
})
|
|
456
458
|
.where(eq(emailSends.id, emailSendId));
|
|
457
459
|
|
|
460
|
+
// Fire-and-forget SEND transition log — journey sends only (journeyStateId
|
|
461
|
+
// present). `to` MUST be `send:<site>` where <site> is the EXACT discriminant
|
|
462
|
+
// the mailer embedded in the idempotency key
|
|
463
|
+
// (`journeySend:<anchor>:<site>:<templateKey>`), parsed back out so it equals
|
|
464
|
+
// the id `buildJourneyGraph` emits for this send node (A2) — this joins the
|
|
465
|
+
// log row to the graph node in Phase 3. Recomputing `currentLabel ?? template`
|
|
466
|
+
// would MISS an explicit `idempotencyLabel`, so we reuse the embedded value;
|
|
467
|
+
// fall back to that only when there is no journey `journeySend:` key. Mirrors
|
|
468
|
+
// the fire-and-forget `emitOutbound` call below; never throws into the send.
|
|
469
|
+
if (options.journeyStateId) {
|
|
470
|
+
const boundary = getJourneyBoundary();
|
|
471
|
+
const site =
|
|
472
|
+
(boundary
|
|
473
|
+
? parseJourneySendSite({
|
|
474
|
+
key: options.idempotencyKey,
|
|
475
|
+
anchor: boundary.runAnchor,
|
|
476
|
+
discriminant: String(options.templateKey),
|
|
477
|
+
})
|
|
478
|
+
: undefined) ??
|
|
479
|
+
boundary?.currentLabel ??
|
|
480
|
+
String(options.templateKey);
|
|
481
|
+
logTransition({
|
|
482
|
+
db,
|
|
483
|
+
journeyStateId: options.journeyStateId,
|
|
484
|
+
to: `send:${site}`,
|
|
485
|
+
action: "send",
|
|
486
|
+
detail: { template: options.templateKey, emailSendId },
|
|
487
|
+
});
|
|
488
|
+
}
|
|
489
|
+
|
|
458
490
|
// OUTBOUND `email.sent` — fired ONLY on a real provider-accepted send (this
|
|
459
491
|
// success branch). Suppressed/frequency-capped/failed branches and the
|
|
460
492
|
// `db === undefined` mailer fallback do NOT reach here, so they never emit.
|
package/src/lists/define-list.ts
CHANGED
|
@@ -10,8 +10,24 @@
|
|
|
10
10
|
* categories (`transactional`, `journey`) and rejected here (open risk #11).
|
|
11
11
|
*/
|
|
12
12
|
|
|
13
|
-
/**
|
|
14
|
-
|
|
13
|
+
/**
|
|
14
|
+
* List ids that collide with the engine's built-in, non-list
|
|
15
|
+
* `email_preferences.categories` keys — rejected by {@link defineList}, and
|
|
16
|
+
* ALSO the allowlist of categories a template may legitimately carry that are
|
|
17
|
+
* NOT a defined list (the boot-time template-category guard in `container.ts`
|
|
18
|
+
* reuses this set so the two can never drift). Exported for that reuse.
|
|
19
|
+
*/
|
|
20
|
+
export const RESERVED_LIST_IDS = new Set(["transactional", "journey"]);
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* Is `id` one of the reserved built-in categories ({@link RESERVED_LIST_IDS})?
|
|
24
|
+
* Case-insensitive, matching the `defineList` reservation check — so callers
|
|
25
|
+
* (e.g. the container's template-category validation) never re-implement the
|
|
26
|
+
* comparison and can't drift from the reservation rule.
|
|
27
|
+
*/
|
|
28
|
+
export function isReservedListId(id: string): boolean {
|
|
29
|
+
return RESERVED_LIST_IDS.has(id.toLowerCase());
|
|
30
|
+
}
|
|
15
31
|
|
|
16
32
|
/** Allowed list-id shape: alphanumerics, dash, underscore (case-insensitive). */
|
|
17
33
|
const LIST_ID_PATTERN = /^[a-z0-9_-]+$/i;
|
|
@@ -60,7 +76,7 @@ export function defineList<const Id extends string>(meta: {
|
|
|
60
76
|
);
|
|
61
77
|
}
|
|
62
78
|
|
|
63
|
-
if (
|
|
79
|
+
if (isReservedListId(id)) {
|
|
64
80
|
throw new Error(
|
|
65
81
|
`Reserved list id "${id}": "transactional" and "journey" are built-in email-preference categories and cannot be used as list ids.`,
|
|
66
82
|
);
|
|
@@ -20,6 +20,7 @@ import { journeyLogsRouter } from "./journey-logs.js";
|
|
|
20
20
|
import { journeysRouter } from "./journeys.js";
|
|
21
21
|
import { linksRouter } from "./links.js";
|
|
22
22
|
import { metricsRouter } from "./metrics.js";
|
|
23
|
+
import { openEditorRouter } from "./open-editor.js";
|
|
23
24
|
import { preferencesRouter } from "./preferences.js";
|
|
24
25
|
import { providerCredentialsRouter } from "./provider-credentials.js";
|
|
25
26
|
import { readinessRouter } from "./readiness.js";
|
|
@@ -38,6 +39,7 @@ adminRouter.route("/contacts", contactsRouter);
|
|
|
38
39
|
adminRouter.route("/contacts", preferencesRouter);
|
|
39
40
|
adminRouter.route("/contacts", timelineRouter);
|
|
40
41
|
adminRouter.route("/journeys", journeysRouter);
|
|
42
|
+
adminRouter.route("/open-in-editor", openEditorRouter);
|
|
41
43
|
adminRouter.route("/buckets", bucketsRouter);
|
|
42
44
|
adminRouter.route("/events", eventsRouter);
|
|
43
45
|
adminRouter.route("/emails", emailsRouter);
|