@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.
@@ -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 { durationToMs, evaluateEventCondition } from "@hogsend/core";
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: new Date(),
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(Date.now() - durationToMs(lookback));
484
+ const since = new Date(
485
+ (await refreshNow()).getTime() - durationToMs(lookback),
486
+ );
236
487
  const recent = await db
237
- .select({ properties: userEvents.properties })
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
- return { timedOut: false, properties: scalars };
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 from Hatchet preserving
338
- // the deadline across replays/restarts; a past instant gives ms = 0.
339
- const ms = Math.max(0, target - Date.now());
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
- await ingestEvent({
373
- db,
374
- registry,
375
- hatchet,
376
- logger,
377
- event: {
378
- event,
379
- userId: targetUserId,
380
- userEmail: targetEmail ?? userEmail,
381
- eventProperties: properties ?? {},
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(Date.now() - durationToMs(within));
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
- // Conventional Vite dev-server origin for the Studio package (`pnpm dev` starts
29
- // it). In production the Studio is served by the API at `${API_PUBLIC_URL}/studio`.
30
- const STUDIO_DEV_URL = "http://localhost:5173";
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
+ }
@@ -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
  });