@hogsend/engine 0.38.1 → 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/constants.ts +9 -0
- package/src/journeys/define-journey.ts +167 -6
- 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
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@hogsend/engine",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.39.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -31,25 +31,28 @@
|
|
|
31
31
|
"@openrouter/ai-sdk-provider": "^2.9.1",
|
|
32
32
|
"@scalar/hono-api-reference": "^0.10.19",
|
|
33
33
|
"@t3-oss/env-core": "^0.13.11",
|
|
34
|
+
"acorn": "^8.17.0",
|
|
35
|
+
"acorn-walk": "^8.3.5",
|
|
34
36
|
"ai": "^6.0.209",
|
|
35
37
|
"better-auth": "^1.6.11",
|
|
36
38
|
"drizzle-orm": "^0.45.2",
|
|
37
39
|
"hono": "^4.12.22",
|
|
38
40
|
"ioredis": "^5.10.1",
|
|
41
|
+
"launch-editor": "^2.14.1",
|
|
39
42
|
"papaparse": "^5.5.3",
|
|
40
43
|
"picocolors": "^1.1.1",
|
|
41
44
|
"resend": "^6.12.3",
|
|
42
45
|
"svix": "^1.95.1",
|
|
43
46
|
"winston": "^3.19.0",
|
|
44
47
|
"zod": "^4.4.3",
|
|
45
|
-
"@hogsend/core": "^0.
|
|
46
|
-
"@hogsend/db": "^0.
|
|
47
|
-
"@hogsend/email": "^0.
|
|
48
|
-
"@hogsend/plugin-posthog": "^0.
|
|
49
|
-
"@hogsend/plugin-resend": "^0.
|
|
48
|
+
"@hogsend/core": "^0.39.0",
|
|
49
|
+
"@hogsend/db": "^0.39.0",
|
|
50
|
+
"@hogsend/email": "^0.39.0",
|
|
51
|
+
"@hogsend/plugin-posthog": "^0.39.0",
|
|
52
|
+
"@hogsend/plugin-resend": "^0.39.0"
|
|
50
53
|
},
|
|
51
54
|
"optionalDependencies": {
|
|
52
|
-
"@hogsend/plugin-postmark": "^0.
|
|
55
|
+
"@hogsend/plugin-postmark": "^0.39.0"
|
|
53
56
|
},
|
|
54
57
|
"devDependencies": {
|
|
55
58
|
"@types/node": "^22.15.3",
|
package/src/container.ts
CHANGED
|
@@ -3,6 +3,7 @@ import type {
|
|
|
3
3
|
AnalyticsEventMirrorConfig,
|
|
4
4
|
AnalyticsProvider,
|
|
5
5
|
EmailProvider,
|
|
6
|
+
JourneySourceLocation,
|
|
6
7
|
PostHogService,
|
|
7
8
|
TimeZone,
|
|
8
9
|
} from "@hogsend/core";
|
|
@@ -14,7 +15,7 @@ import {
|
|
|
14
15
|
type DatabaseClient,
|
|
15
16
|
type JournalShape,
|
|
16
17
|
} from "@hogsend/db";
|
|
17
|
-
import type { TemplateRegistry } from "@hogsend/email";
|
|
18
|
+
import type { TemplateDefinition, TemplateRegistry } from "@hogsend/email";
|
|
18
19
|
import { createBucketAccessor } from "./buckets/bucket-access.js";
|
|
19
20
|
import type { DefinedBucket } from "./buckets/define-bucket.js";
|
|
20
21
|
import {
|
|
@@ -41,6 +42,8 @@ import {
|
|
|
41
42
|
import { env } from "./env.js";
|
|
42
43
|
import { setClientScheduleDefaults } from "./journeys/client-defaults-singleton.js";
|
|
43
44
|
import type { DefinedJourney } from "./journeys/define-journey.js";
|
|
45
|
+
import { getJourneySourceLocations } from "./journeys/journey-source-locations-singleton.js";
|
|
46
|
+
import { getJourneySources } from "./journeys/journey-sources-singleton.js";
|
|
44
47
|
import { buildJourneyRegistry } from "./journeys/registry.js";
|
|
45
48
|
import {
|
|
46
49
|
isAnalyticsProvider,
|
|
@@ -75,7 +78,11 @@ import { createRedisSecondaryStorage, getRedis } from "./lib/redis.js";
|
|
|
75
78
|
import { sendResetPasswordEmail } from "./lib/reset-email.js";
|
|
76
79
|
import { seedPostHogDestination } from "./lib/seed-posthog-destination.js";
|
|
77
80
|
import { prepareTrackedHtml } from "./lib/tracking.js";
|
|
78
|
-
import
|
|
81
|
+
import {
|
|
82
|
+
type DefinedList,
|
|
83
|
+
isReservedListId,
|
|
84
|
+
RESERVED_LIST_IDS,
|
|
85
|
+
} from "./lists/define-list.js";
|
|
79
86
|
import { buildListRegistry, type ListRegistry } from "./lists/registry.js";
|
|
80
87
|
import {
|
|
81
88
|
type DefinedWebhookSource,
|
|
@@ -147,6 +154,20 @@ export interface HogsendClient {
|
|
|
147
154
|
*/
|
|
148
155
|
identity: IdentityService;
|
|
149
156
|
registry: JourneyRegistry;
|
|
157
|
+
/**
|
|
158
|
+
* Map of enabled journey id → its captured `run` source string. Populated by
|
|
159
|
+
* `buildJourneyRegistry` (skips journeys whose source failed to serialize).
|
|
160
|
+
* Consumed by the Studio journey-graph route, which parses the source lazily
|
|
161
|
+
* with acorn to derive a visual workflow. Empty when no journeys are wired.
|
|
162
|
+
*/
|
|
163
|
+
journeySources: Map<string, string>;
|
|
164
|
+
/**
|
|
165
|
+
* Map of enabled journey id → its `defineJourney` call-site `{ path, line }`.
|
|
166
|
+
* Populated by `buildJourneyRegistry`. Consumed by the Studio journey-graph
|
|
167
|
+
* route to build an "open in editor" deep link. Absent ids had no capturable
|
|
168
|
+
* call-site (e.g. bucket-generated reaction journeys).
|
|
169
|
+
*/
|
|
170
|
+
journeySourceLocations: Map<string, JourneySourceLocation>;
|
|
150
171
|
/**
|
|
151
172
|
* The bucket registry (id map + event/property inverted indexes for candidate
|
|
152
173
|
* narrowing). Built and installed as the process singleton at client build;
|
|
@@ -379,16 +400,26 @@ export function createHogsendClient(
|
|
|
379
400
|
const created = createDatabase({ url: env.DATABASE_URL });
|
|
380
401
|
const db = opts.overrides?.db ?? created.db;
|
|
381
402
|
|
|
403
|
+
// Resolve buckets + their reaction journeys BEFORE the journey registry so the
|
|
404
|
+
// reaction ids (`bucket-<id>-on-<kind>`, registered separately below) are part
|
|
405
|
+
// of ENABLED_JOURNEYS's known set. They ARE registered journeys, so listing a
|
|
406
|
+
// real reaction id in ENABLED_JOURNEYS must NOT be rejected as a typo.
|
|
407
|
+
const buckets = opts.buckets ?? [];
|
|
408
|
+
const enabledBuckets = opts.enabledBuckets ?? env.ENABLED_BUCKETS;
|
|
409
|
+
const reactionJourneys = collectBucketReactionJourneys(
|
|
410
|
+
buckets,
|
|
411
|
+
enabledBuckets,
|
|
412
|
+
);
|
|
413
|
+
|
|
382
414
|
const registry = buildJourneyRegistry(
|
|
383
415
|
opts.journeys ?? [],
|
|
384
416
|
opts.enabledJourneys ?? env.ENABLED_JOURNEYS,
|
|
417
|
+
reactionJourneys.map((r) => r.meta.id),
|
|
385
418
|
);
|
|
386
419
|
|
|
387
420
|
// Installs the bucket registry singleton in BOTH the API and worker processes
|
|
388
421
|
// (both call createHogsendClient); the real-time ingest path reads it via
|
|
389
422
|
// getBucketRegistrySingleton().
|
|
390
|
-
const buckets = opts.buckets ?? [];
|
|
391
|
-
const enabledBuckets = opts.enabledBuckets ?? env.ENABLED_BUCKETS;
|
|
392
423
|
const bucketRegistry = buildBucketRegistry(buckets, enabledBuckets);
|
|
393
424
|
|
|
394
425
|
// Register the reaction journeys generated by `bucket.on()` into the journey
|
|
@@ -398,10 +429,7 @@ export function createHogsendClient(
|
|
|
398
429
|
// be subject to the journeys csv (Section 9). Both API and worker call
|
|
399
430
|
// createHogsendClient, so the singleton carries reaction metas in both
|
|
400
431
|
// processes (needed for admin feedsJourneys + the dwell-cron lookup).
|
|
401
|
-
for (const reaction of
|
|
402
|
-
buckets,
|
|
403
|
-
enabledBuckets,
|
|
404
|
-
)) {
|
|
432
|
+
for (const reaction of reactionJourneys) {
|
|
405
433
|
registry.register(reaction.meta);
|
|
406
434
|
}
|
|
407
435
|
|
|
@@ -500,6 +528,81 @@ export function createHogsendClient(
|
|
|
500
528
|
|
|
501
529
|
const templates = opts.email?.templates ?? ({} as TemplateRegistry);
|
|
502
530
|
|
|
531
|
+
// Boot-validate every template's `category` against the resolvable list
|
|
532
|
+
// namespace BEFORE the mailer/emailService is constructed — fail CLOSED.
|
|
533
|
+
//
|
|
534
|
+
// A template's `category` (TemplateDefinition.category) IS the
|
|
535
|
+
// email-preferences list key: at send time `lib/tracked.ts` resolves the
|
|
536
|
+
// effective category and `checkSuppression` gates it through
|
|
537
|
+
// `ListRegistry.isSubscribed`, whose `isSubscribedByDefault` legacy fallback
|
|
538
|
+
// is `this.get(id)?.defaultOptIn ?? true`. So a TYPO'd category (e.g.
|
|
539
|
+
// "product-update" when the opt-in list id is "product-updates") resolves to
|
|
540
|
+
// an UNKNOWN id → `?? true` opt-in default → treated as subscribed → NOT
|
|
541
|
+
// suppressed. The consent/opt-in email would then be delivered to EVERY
|
|
542
|
+
// recipient (including never-subscribed) AND anyone who unsubscribed under the
|
|
543
|
+
// correct key would still receive it — CAN-SPAM/GDPR-grade. This guard makes a
|
|
544
|
+
// mismatched category a loud boot failure so it can never reach that fallback.
|
|
545
|
+
//
|
|
546
|
+
// Known-good set = reserved built-ins ∪ DEFINED lists (`opts.lists`), NOT just
|
|
547
|
+
// the ENABLED registry — mirroring the ENABLED_JOURNEYS lesson (validate
|
|
548
|
+
// against DEFINED, not just ENABLED). A DEFINED-but-registry-EXCLUDED list
|
|
549
|
+
// (removed from the registry by an ENABLED_LISTS allowlist that doesn't name
|
|
550
|
+
// it) does NOT auto-warn: excluding it flips the send-time gate by POLARITY,
|
|
551
|
+
// so we branch on `defaultOptIn` (below). We carry each list's `defaultOptIn`
|
|
552
|
+
// (not just its id) so that branch can decide THROW vs WARN. This does NOT
|
|
553
|
+
// change the send-time suppression logic; it only prevents a bad/consent-
|
|
554
|
+
// flipping category reaching it.
|
|
555
|
+
const definedLists = new Map(
|
|
556
|
+
(opts.lists ?? []).map((l) => [l.meta.id, l.meta.defaultOptIn] as const),
|
|
557
|
+
);
|
|
558
|
+
for (const [templateKey, def] of Object.entries(templates)) {
|
|
559
|
+
const category = (def as TemplateDefinition | undefined)?.category;
|
|
560
|
+
// No category ⇒ no per-list gating for this template; nothing to validate.
|
|
561
|
+
if (!category) continue;
|
|
562
|
+
// Reserved built-in category (transactional / journey) — never a list, but
|
|
563
|
+
// a legitimate `email_preferences.categories` key. OK.
|
|
564
|
+
if (isReservedListId(category)) continue;
|
|
565
|
+
// Category names a REGISTERED list ⇒ suppression/preferences gate correctly.
|
|
566
|
+
// (Note: a `defineList({ enabled:false })` is STILL registered — the
|
|
567
|
+
// registry filters on ENABLED_LISTS only, never `meta.enabled` — so it
|
|
568
|
+
// lands here, not in the excluded branch below.)
|
|
569
|
+
if (listRegistry.has(category)) continue;
|
|
570
|
+
// Category names a DEFINED list that is EXCLUDED from the registry by an
|
|
571
|
+
// ENABLED_LISTS allowlist that doesn't name it. Excluding it makes the
|
|
572
|
+
// send-time check fall back to the legacy `?? true` opt-in default, which
|
|
573
|
+
// FLIPS the gate by polarity:
|
|
574
|
+
// • opt-IN list (`defaultOptIn:false`, consent required): enabled →
|
|
575
|
+
// `categories[id] === true` (never-consented = NOT subscribed =
|
|
576
|
+
// suppressed); excluded → `categories[id] !== false` (never-consented =
|
|
577
|
+
// SUBSCRIBED = NOT suppressed) → the consent email SHIPS to someone who
|
|
578
|
+
// never opted in. Disabling un-gates consent → THROW (fail closed).
|
|
579
|
+
// • opt-OUT list (`defaultOptIn:true`): both enabled and excluded compute
|
|
580
|
+
// `categories[id] !== false` — IDENTICAL, behavior-preserving → WARN.
|
|
581
|
+
const definedOptIn = definedLists.get(category);
|
|
582
|
+
if (definedOptIn !== undefined) {
|
|
583
|
+
if (definedOptIn === false) {
|
|
584
|
+
throw new Error(
|
|
585
|
+
`Email template "${templateKey}" has category "${category}", an OPT-IN email list (defaultOptIn:false) that is DEFINED but EXCLUDED from the active registry by ENABLED_LISTS. At send time an excluded list falls back to the legacy opt-in default, which UN-GATES consent — the opt-in email would ship to recipients who never subscribed. Re-enable the list in ENABLED_LISTS (or change the template's category) — disabling an opt-in list must not silently flip its consent gate open.`,
|
|
586
|
+
);
|
|
587
|
+
}
|
|
588
|
+
logger.warn(
|
|
589
|
+
`Email template "${templateKey}" has category "${category}", a DEFINED email list EXCLUDED from the active registry by ENABLED_LISTS. It is an opt-out list (defaultOptIn:true), so send-time gating is behavior-preserving — but its preference center entry is hidden while excluded. Re-enable the list in ENABLED_LISTS or change the template's category.`,
|
|
590
|
+
);
|
|
591
|
+
continue;
|
|
592
|
+
}
|
|
593
|
+
// Unknown category: neither a reserved built-in nor a defined list. At send
|
|
594
|
+
// time this resolves to the `?? true` opt-in default, bypassing
|
|
595
|
+
// suppression/consent. Fail CLOSED with an actionable message.
|
|
596
|
+
const knownLists = [...definedLists.keys()];
|
|
597
|
+
throw new Error(
|
|
598
|
+
`Email template "${templateKey}" has category "${category}", which is neither a reserved built-in category (${[
|
|
599
|
+
...RESERVED_LIST_IDS,
|
|
600
|
+
].join(", ")}) nor a defined email list (${
|
|
601
|
+
knownLists.length ? knownLists.join(", ") : "none"
|
|
602
|
+
}). A template's category is its email-preferences list key, so it MUST match a list id (defineList) or a reserved built-in — otherwise an unknown/typo'd category silently defaults to opt-in and un-gates suppression/consent. Fix the category or define the list.`,
|
|
603
|
+
);
|
|
604
|
+
}
|
|
605
|
+
|
|
503
606
|
const emailService =
|
|
504
607
|
opts.overrides?.mailer ??
|
|
505
608
|
createTrackedMailer(
|
|
@@ -611,11 +714,29 @@ export function createHogsendClient(
|
|
|
611
714
|
: wrapLegacyAnalyticsService(analyticsOpt as PostHogService);
|
|
612
715
|
analyticsProviders.register(analytics);
|
|
613
716
|
} else {
|
|
717
|
+
// Resolve the ONE active analytics provider by id — the analytics sibling of
|
|
718
|
+
// the email-provider resolution above, and fail loud on an unresolved
|
|
719
|
+
// active id exactly like `EMAIL_PROVIDER` does. `env.ANALYTICS_PROVIDER`
|
|
720
|
+
// carries a zod `.default("posthog")`, so the resolved id is never empty —
|
|
721
|
+
// that default is what AUTO-ACTIVATES the PostHog env preset when
|
|
722
|
+
// `POSTHOG_API_KEY` is set. Because of that default we must NOT fail boot
|
|
723
|
+
// merely because the resolved id is unregistered: an operator who wired NO
|
|
724
|
+
// analytics still resolves "posthog" and legitimately has no provider (leave
|
|
725
|
+
// `analytics` undefined — reads/mirror stay no-ops). So the throw is gated on
|
|
726
|
+
// the id being EXPLICITLY requested — a code `defaultProvider` OR a SET
|
|
727
|
+
// `ANALYTICS_PROVIDER` env. The RAW `process.env` read (mirroring the
|
|
728
|
+
// `REDIS_URL` read above) is what distinguishes an explicit request from the
|
|
729
|
+
// zod default; without this gate a bogus `ANALYTICS_PROVIDER` typo would
|
|
730
|
+
// SILENTLY disable analytics (killing tz person-reads + the event mirror)
|
|
731
|
+
// instead of failing loud.
|
|
614
732
|
const activeId = analyticsGroup?.defaultProvider ?? env.ANALYTICS_PROVIDER;
|
|
733
|
+
const explicitlyRequested = Boolean(
|
|
734
|
+
analyticsGroup?.defaultProvider ?? process.env.ANALYTICS_PROVIDER,
|
|
735
|
+
);
|
|
615
736
|
analytics = analyticsProviders.get(activeId);
|
|
616
|
-
if (
|
|
737
|
+
if (explicitlyRequested && !analytics) {
|
|
617
738
|
throw new Error(
|
|
618
|
-
`analytics
|
|
739
|
+
`analytics provider "${activeId}" is not registered (registered: ${analyticsProviders
|
|
619
740
|
.getAll()
|
|
620
741
|
.map((p) => p.meta.id)
|
|
621
742
|
.join(", ")})`,
|
|
@@ -773,6 +894,8 @@ export function createHogsendClient(
|
|
|
773
894
|
analytics,
|
|
774
895
|
identity,
|
|
775
896
|
registry,
|
|
897
|
+
journeySources: getJourneySources(),
|
|
898
|
+
journeySourceLocations: getJourneySourceLocations(),
|
|
776
899
|
bucketRegistry,
|
|
777
900
|
listRegistry,
|
|
778
901
|
connectorRegistry,
|
package/src/index.ts
CHANGED
|
@@ -186,18 +186,41 @@ export {
|
|
|
186
186
|
defineJourney,
|
|
187
187
|
} from "./journeys/define-journey.js";
|
|
188
188
|
export { JourneyExitedError } from "./journeys/errors.js";
|
|
189
|
+
// --- Journey graph extractor (Studio visual workflow) ---
|
|
190
|
+
export {
|
|
191
|
+
buildJourneyGraph,
|
|
192
|
+
degradedGraphFromMeta,
|
|
193
|
+
} from "./journeys/graph/build-graph.js";
|
|
189
194
|
export {
|
|
190
195
|
createMemoize,
|
|
191
196
|
deriveJourneyKey,
|
|
192
197
|
getJourneyBoundary,
|
|
193
198
|
type JourneyBoundary,
|
|
199
|
+
parseJourneySendSite,
|
|
194
200
|
registerKey,
|
|
195
201
|
runWithJourneyBoundary,
|
|
196
202
|
} from "./journeys/journey-boundary.js";
|
|
197
203
|
export { createJourneyContext } from "./journeys/journey-context.js";
|
|
204
|
+
// --- Journey transition log (journey_logs writer — Phase 2 per-stage metrics) ---
|
|
205
|
+
export {
|
|
206
|
+
type JourneyLogAction,
|
|
207
|
+
type LogTransitionArgs,
|
|
208
|
+
logTransition,
|
|
209
|
+
} from "./journeys/journey-log.js";
|
|
210
|
+
export {
|
|
211
|
+
getJourneySourceLocations,
|
|
212
|
+
resetJourneySourceLocations,
|
|
213
|
+
setJourneySourceLocations,
|
|
214
|
+
} from "./journeys/journey-source-locations-singleton.js";
|
|
215
|
+
export {
|
|
216
|
+
getJourneySources,
|
|
217
|
+
resetJourneySources,
|
|
218
|
+
setJourneySources,
|
|
219
|
+
} from "./journeys/journey-sources-singleton.js";
|
|
198
220
|
export {
|
|
199
221
|
buildJourneyRegistry,
|
|
200
222
|
parseEnabledFilter,
|
|
223
|
+
resolveEnabledFilter,
|
|
201
224
|
selectJourneyTasks,
|
|
202
225
|
} from "./journeys/registry.js";
|
|
203
226
|
export {
|
|
@@ -12,3 +12,12 @@
|
|
|
12
12
|
*/
|
|
13
13
|
export const JOURNEY_EXECUTION_TIMEOUT_HOURS = 720;
|
|
14
14
|
export const JOURNEY_EXECUTION_TIMEOUT = `${JOURNEY_EXECUTION_TIMEOUT_HOURS}h`;
|
|
15
|
+
|
|
16
|
+
/**
|
|
17
|
+
* Max time a journey task may wait in the queue for a worker slot before Hatchet
|
|
18
|
+
* cancels it (`scheduleTimeout`). The SDK default (~5m) is too tight for a
|
|
19
|
+
* durable-wait RESUME that re-queues during a redeploy when every worker slot is
|
|
20
|
+
* momentarily saturated — the resume would be cancelled and the enrollment
|
|
21
|
+
* stranded. 15m gives resumes head-room to land on a freed slot.
|
|
22
|
+
*/
|
|
23
|
+
export const JOURNEY_SCHEDULE_TIMEOUT = "15m";
|
|
@@ -1,5 +1,10 @@
|
|
|
1
|
+
import { fileURLToPath } from "node:url";
|
|
1
2
|
import type { JsonValue } from "@hatchet-dev/typescript-sdk/v1/types.js";
|
|
2
|
-
import {
|
|
3
|
+
import {
|
|
4
|
+
evaluatePropertyConditions,
|
|
5
|
+
type JourneySourceLocation,
|
|
6
|
+
normalizeWhere,
|
|
7
|
+
} from "@hogsend/core";
|
|
3
8
|
import type {
|
|
4
9
|
JourneyMeta,
|
|
5
10
|
JourneyMetaInput,
|
|
@@ -19,7 +24,10 @@ import { createLogger } from "../lib/logger.js";
|
|
|
19
24
|
import { emitOutbound } from "../lib/outbound.js";
|
|
20
25
|
import { resolveTimezoneWithSource } from "../lib/timezone.js";
|
|
21
26
|
import { getClientScheduleDefaults } from "./client-defaults-singleton.js";
|
|
22
|
-
import {
|
|
27
|
+
import {
|
|
28
|
+
JOURNEY_EXECUTION_TIMEOUT,
|
|
29
|
+
JOURNEY_SCHEDULE_TIMEOUT,
|
|
30
|
+
} from "./constants.js";
|
|
23
31
|
import { JourneyExitedError } from "./errors.js";
|
|
24
32
|
import {
|
|
25
33
|
createMemoize,
|
|
@@ -28,6 +36,7 @@ import {
|
|
|
28
36
|
supportsEviction,
|
|
29
37
|
} from "./journey-boundary.js";
|
|
30
38
|
import { createJourneyContext, TERMINAL_STATUSES } from "./journey-context.js";
|
|
39
|
+
import { logTransition } from "./journey-log.js";
|
|
31
40
|
import { getJourneyRegistrySingleton } from "./registry-singleton.js";
|
|
32
41
|
|
|
33
42
|
const logger = createLogger(process.env.LOG_LEVEL);
|
|
@@ -62,12 +71,111 @@ interface EventPayloadInput {
|
|
|
62
71
|
export interface DefinedJourney {
|
|
63
72
|
meta: JourneyMeta;
|
|
64
73
|
task: ReturnType<typeof hatchet.durableTask>;
|
|
74
|
+
/**
|
|
75
|
+
* The journey's `run` function serialized via `Function.prototype.toString()`,
|
|
76
|
+
* captured at definition time. This is the substrate the Studio journey-graph
|
|
77
|
+
* extractor parses (with acorn) to derive a visual workflow. The bundler never
|
|
78
|
+
* minifies (see `tsup` config), so the string is standard, non-minified JS.
|
|
79
|
+
*
|
|
80
|
+
* Best-effort: `undefined` if serialization throws (some exotic runtimes
|
|
81
|
+
* disallow `.toString()`); the extractor degrades to a meta-only graph. Capture
|
|
82
|
+
* is side-effect-free and must NEVER change execution semantics.
|
|
83
|
+
*/
|
|
84
|
+
runSource?: string;
|
|
85
|
+
/**
|
|
86
|
+
* Absolute file path + 1-based line of the consumer's `defineJourney(...)`
|
|
87
|
+
* call, captured from the stack at definition time (for the Studio "open in
|
|
88
|
+
* editor" affordance). Best-effort: `undefined` when unavailable. Capture is
|
|
89
|
+
* side-effect-free and must NEVER change execution semantics.
|
|
90
|
+
*/
|
|
91
|
+
source?: JourneySourceLocation;
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/**
|
|
95
|
+
* Serialize a function to source, never throwing. Some engines can refuse
|
|
96
|
+
* `Function.prototype.toString()` (e.g. bound/native shims); a failure here must
|
|
97
|
+
* degrade to `undefined`, not break `defineJourney`.
|
|
98
|
+
*/
|
|
99
|
+
function safeRunSource(fn: JourneyRunFn): string | undefined {
|
|
100
|
+
try {
|
|
101
|
+
return fn.toString();
|
|
102
|
+
} catch {
|
|
103
|
+
return undefined;
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
/**
|
|
108
|
+
* Absolute path of THIS module, resolved once. Every stack frame inside
|
|
109
|
+
* define-journey (the capture helper AND `defineJourney` itself) resolves to
|
|
110
|
+
* this path, so the call-site parser skips them and returns the FIRST external
|
|
111
|
+
* frame — the consumer's `defineJourney(...)` site. Works whether the engine
|
|
112
|
+
* runs as `.ts` source (tsx dev, the local dogfood path) or compiled `.js`
|
|
113
|
+
* (dist): self and frames are captured in the same representation.
|
|
114
|
+
*/
|
|
115
|
+
const SELF_FILE = fileURLToPath(import.meta.url);
|
|
116
|
+
|
|
117
|
+
/**
|
|
118
|
+
* Capture the consumer's `defineJourney` call-site `{ path, line }` from a fresh
|
|
119
|
+
* stack, so the Studio can deep-link an editor (`cursor://file/<path>:<line>`).
|
|
120
|
+
* Best-effort + side-effect-free: returns `undefined` if the stack is missing
|
|
121
|
+
* or unparseable. NEVER throws and NEVER changes execution semantics.
|
|
122
|
+
*
|
|
123
|
+
* Handles both frame shapes V8 emits:
|
|
124
|
+
* `at fn (/abs/file.ts:LINE:COL)` (named — tsx source-mapped, bare path)
|
|
125
|
+
* `at file:///abs/file.js:LINE:COL` (anonymous top-level — `file://`, no parens)
|
|
126
|
+
* `fileURLToPath` also URL-decodes `file://` paths (spaces, etc). Skips node
|
|
127
|
+
* internals, node_modules, and every frame inside this module (SELF_FILE).
|
|
128
|
+
*/
|
|
129
|
+
function captureCallSite(): JourneySourceLocation | undefined {
|
|
130
|
+
const original = Error.stackTraceLimit;
|
|
131
|
+
// Default is 10; the external frame sits ~3 deep. Widen defensively for deep
|
|
132
|
+
// re-export/barrel chains, then restore so we don't perturb global behavior.
|
|
133
|
+
Error.stackTraceLimit = 30;
|
|
134
|
+
const stack = new Error().stack;
|
|
135
|
+
Error.stackTraceLimit = original;
|
|
136
|
+
if (!stack) return undefined;
|
|
137
|
+
|
|
138
|
+
for (const rawLine of stack.split("\n").slice(1)) {
|
|
139
|
+
const line = rawLine.trim();
|
|
140
|
+
if (!line.startsWith("at ")) continue;
|
|
141
|
+
|
|
142
|
+
// Location token = the parenthesized group when present, else the text
|
|
143
|
+
// right after "at " (anonymous frames carry no parens).
|
|
144
|
+
const paren = line.match(/\(([^)]+)\)\s*$/);
|
|
145
|
+
const token = paren?.[1] ?? line.slice(3).trim();
|
|
146
|
+
|
|
147
|
+
// Strip the trailing ":line:col" (col optional) to isolate the file part.
|
|
148
|
+
const m =
|
|
149
|
+
token.match(/^(.*?):(\d+):(\d+)$/) ?? token.match(/^(.*?):(\d+)$/);
|
|
150
|
+
const filePart = m?.[1];
|
|
151
|
+
const lineNo = m?.[2];
|
|
152
|
+
if (!filePart || !lineNo) continue;
|
|
153
|
+
|
|
154
|
+
let file = filePart;
|
|
155
|
+
if (file.startsWith("file://")) {
|
|
156
|
+
try {
|
|
157
|
+
file = fileURLToPath(file);
|
|
158
|
+
} catch {
|
|
159
|
+
continue;
|
|
160
|
+
}
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
// First frame that clears all three is the consumer's call site.
|
|
164
|
+
if (file.startsWith("node:")) continue;
|
|
165
|
+
if (file.includes("node_modules")) continue;
|
|
166
|
+
if (file === SELF_FILE) continue;
|
|
167
|
+
|
|
168
|
+
return { path: file, line: Number(lineNo) };
|
|
169
|
+
}
|
|
170
|
+
return undefined;
|
|
65
171
|
}
|
|
66
172
|
|
|
67
173
|
export function defineJourney(options: {
|
|
68
174
|
meta: JourneyMetaInput;
|
|
69
175
|
run: JourneyRunFn;
|
|
70
176
|
}): DefinedJourney {
|
|
177
|
+
const runSource = safeRunSource(options.run);
|
|
178
|
+
const source = captureCallSite();
|
|
71
179
|
const { trigger, exitOn, ...rest } = options.meta;
|
|
72
180
|
const triggerWhere = normalizeWhere(trigger.where);
|
|
73
181
|
const meta: JourneyMeta = {
|
|
@@ -93,7 +201,20 @@ export function defineJourney(options: {
|
|
|
93
201
|
name: `journey-${meta.id}`,
|
|
94
202
|
onEvents: [meta.trigger.event],
|
|
95
203
|
executionTimeout: JOURNEY_EXECUTION_TIMEOUT,
|
|
204
|
+
// retries STAYS 0 — deliberately. A retry replays `run()` from the top, and
|
|
205
|
+
// the tracked mailer / connector machinery is "missed > doubled": a `queued`
|
|
206
|
+
// row is RE-DRIVEN and a failed send NULLs its idempotency key (tracked.ts
|
|
207
|
+
// ~150-176, 496-514). That is safe only while nothing re-invokes a run whose
|
|
208
|
+
// `provider.send()` already delivered but whose durable status flip didn't
|
|
209
|
+
// commit — turning retries on would re-deliver that email/connector message
|
|
210
|
+
// (a DUPLICATE). Enabling retries requires making sends provider-idempotent
|
|
211
|
+
// first (Resend/Postmark `Idempotency-Key`); tracked as a follow-up.
|
|
96
212
|
retries: 0,
|
|
213
|
+
// `scheduleTimeout` widens the queue-wait ceiling (SDK default ~5m) so a
|
|
214
|
+
// durable-wait RESUME re-queued during a redeploy's slot saturation reclaims
|
|
215
|
+
// a slot instead of being cancelled (which strands the enrollment). Unlike
|
|
216
|
+
// retries this adds NO replay — it is pure head-room, so it is safe on its own.
|
|
217
|
+
scheduleTimeout: JOURNEY_SCHEDULE_TIMEOUT,
|
|
97
218
|
fn: async (input: EventPayloadInput, hatchetCtx) => {
|
|
98
219
|
const db = getDb();
|
|
99
220
|
const userId = input.userId as string;
|
|
@@ -206,6 +327,20 @@ export function defineJourney(options: {
|
|
|
206
327
|
}
|
|
207
328
|
|
|
208
329
|
const stateId = state.id;
|
|
330
|
+
|
|
331
|
+
// Fire-and-forget enrollment transition (FRESH entry only — a replay
|
|
332
|
+
// recovers `state` by run id above and must NOT re-log an entry). Writes
|
|
333
|
+
// `journey_logs` best-effort; never throws into / alters execution.
|
|
334
|
+
if (!recovered) {
|
|
335
|
+
logTransition({
|
|
336
|
+
db,
|
|
337
|
+
journeyStateId: stateId,
|
|
338
|
+
from: null,
|
|
339
|
+
to: "start",
|
|
340
|
+
action: "entered",
|
|
341
|
+
});
|
|
342
|
+
}
|
|
343
|
+
|
|
209
344
|
// The replay-stable key anchor: prefer the run id (constant across replays
|
|
210
345
|
// of this run), fall back to stateId when the engine has no run id.
|
|
211
346
|
const runAnchor = workflowRunId || stateId;
|
|
@@ -230,9 +365,14 @@ export function defineJourney(options: {
|
|
|
230
365
|
// Independent I/O — fetch the contact row and PostHog person props
|
|
231
366
|
// concurrently. PostHog failures fall through to undefined.
|
|
232
367
|
const [contact, posthogProperties] = await Promise.all([
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
368
|
+
// Both legs are best-effort tz inputs: a failure here must fall through
|
|
369
|
+
// to the client-default tz, never reject the `Promise.all` and throw out
|
|
370
|
+
// of `fn` BEFORE the try/catch below (which would strand the row —
|
|
371
|
+
// already inserted "active" — outside the failure handling). The PostHog
|
|
372
|
+
// leg already `.catch`es; mirror it on the contact read.
|
|
373
|
+
db.query.contacts
|
|
374
|
+
.findFirst({ where: eq(contacts.externalId, userId) })
|
|
375
|
+
.catch(() => undefined),
|
|
236
376
|
posthog?.getPersonProperties(userId).catch(() => undefined),
|
|
237
377
|
]);
|
|
238
378
|
|
|
@@ -318,6 +458,15 @@ export function defineJourney(options: {
|
|
|
318
458
|
})
|
|
319
459
|
.where(eq(journeyStates.id, stateId));
|
|
320
460
|
|
|
461
|
+
// Fire-and-forget completion transition (best-effort; never throws).
|
|
462
|
+
logTransition({
|
|
463
|
+
db,
|
|
464
|
+
journeyStateId: stateId,
|
|
465
|
+
from: boundary.currentLabel ?? null,
|
|
466
|
+
to: "end-completed",
|
|
467
|
+
action: "completed",
|
|
468
|
+
});
|
|
469
|
+
|
|
321
470
|
await hatchet.events.push("journey:completed", {
|
|
322
471
|
journeyId: meta.id,
|
|
323
472
|
stateId,
|
|
@@ -393,6 +542,18 @@ export function defineJourney(options: {
|
|
|
393
542
|
error: message,
|
|
394
543
|
});
|
|
395
544
|
|
|
545
|
+
// Fire-and-forget failure transition — only reached when a row was
|
|
546
|
+
// actually flipped to "failed" (the guard above). `to` is the best-effort
|
|
547
|
+
// last durable node (approximate — see plan Guardrails). Never throws.
|
|
548
|
+
logTransition({
|
|
549
|
+
db,
|
|
550
|
+
journeyStateId: stateId,
|
|
551
|
+
from: null,
|
|
552
|
+
to: boundary.currentLabel ?? state.currentNodeId ?? null,
|
|
553
|
+
action: "failed",
|
|
554
|
+
detail: { error: message },
|
|
555
|
+
});
|
|
556
|
+
|
|
396
557
|
await hatchet.events.push("journey:failed", {
|
|
397
558
|
journeyId: meta.id,
|
|
398
559
|
stateId,
|
|
@@ -405,5 +566,5 @@ export function defineJourney(options: {
|
|
|
405
566
|
},
|
|
406
567
|
});
|
|
407
568
|
|
|
408
|
-
return { meta, task };
|
|
569
|
+
return { meta, task, runSource, source };
|
|
409
570
|
}
|