@hogsend/engine 0.38.2 → 0.40.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.
@@ -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 (nodeId: string): Promise<void> => {
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 (): Promise<void> => {
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;
@@ -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. An empty/whitespace/`*` value means all.
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 = parseEnabledFilter(enabledFilter);
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 = parseEnabledFilter(enabledFilter);
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/auth.ts CHANGED
@@ -53,12 +53,44 @@ export function createAuth(opts: {
53
53
  * better-auth's in-memory store on a bare instance with no Redis.
54
54
  */
55
55
  secondaryStorage?: AuthSecondaryStorage;
56
+ /**
57
+ * Cookie-name namespace for THIS engine instance's Better Auth (passed to
58
+ * better-auth `advanced.cookiePrefix`). Better Auth names the session cookie
59
+ * `<__Secure->?<prefix>.session_token`; the default "better-auth" prefix
60
+ * collides with a sibling web app's cross-subdomain SSO cookie of the SAME
61
+ * name (e.g. course/docs on `.hogsend.com`) that the browser also delivers to
62
+ * the Studio host — but which resolves against a DIFFERENT database → null
63
+ * session → Studio login loop. Defaulting to "hogsend" gives the engine its
64
+ * own namespace (`__Secure-hogsend.session_token`) so that sibling cookie is
65
+ * simply ignored here. `cookiePrefix` only affects the cookie NAME — it is
66
+ * orthogonal to `crossSubDomainCookies` (the Domain attribute), which the
67
+ * engine never sets (host-only). `createHogsendClient` wires this from
68
+ * `env.AUTH_COOKIE_PREFIX`; the default is baked in below so every call site
69
+ * (including the headless CLI, which issues no cookie) stays aligned.
70
+ */
71
+ cookiePrefix?: string;
56
72
  }) {
57
- const { db, secret, baseURL, trustedOrigins, sendResetPassword } = opts;
73
+ const {
74
+ db,
75
+ secret,
76
+ baseURL,
77
+ trustedOrigins,
78
+ sendResetPassword,
79
+ cookiePrefix,
80
+ } = opts;
58
81
  return betterAuth({
59
82
  basePath: "/api/auth",
60
83
  secret,
61
84
  baseURL,
85
+ // Namespace the engine's Better Auth cookies so its session cookie no longer
86
+ // shares a NAME with a sibling web app's `.hogsend.com` cross-subdomain SSO
87
+ // cookie that is also delivered to the Studio host (same name, different DB
88
+ // → null session → Studio login loop). Prefix-only; the Domain attribute
89
+ // (crossSubDomainCookies) is left UNSET → host-only cookie. Default
90
+ // "hogsend" → prod cookie `__Secure-hogsend.session_token`.
91
+ advanced: {
92
+ cookiePrefix: cookiePrefix ?? "hogsend",
93
+ },
62
94
  ...(trustedOrigins && trustedOrigins.length > 0 ? { trustedOrigins } : {}),
63
95
  // Passing `secondaryStorage` flips better-auth's rate-limit storage from the
64
96
  // per-instance in-memory default to this shared store (see option doc).
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
- template: string;
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 loose, runtime-string entry point used by journeys: the
106
- // template key and props are resolved at runtime, so we build the options
107
- // untyped and hand them to the typed `service.send`. Type-safe call sites use
108
- // `container.emailService.send({ template, props })` directly.
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: {
@@ -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
@@ -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.