@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
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 {
|
|
@@ -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,
|
|
@@ -31,6 +36,7 @@ import {
|
|
|
31
36
|
supportsEviction,
|
|
32
37
|
} from "./journey-boundary.js";
|
|
33
38
|
import { createJourneyContext, TERMINAL_STATUSES } from "./journey-context.js";
|
|
39
|
+
import { logTransition } from "./journey-log.js";
|
|
34
40
|
import { getJourneyRegistrySingleton } from "./registry-singleton.js";
|
|
35
41
|
|
|
36
42
|
const logger = createLogger(process.env.LOG_LEVEL);
|
|
@@ -65,12 +71,111 @@ interface EventPayloadInput {
|
|
|
65
71
|
export interface DefinedJourney {
|
|
66
72
|
meta: JourneyMeta;
|
|
67
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;
|
|
68
171
|
}
|
|
69
172
|
|
|
70
173
|
export function defineJourney(options: {
|
|
71
174
|
meta: JourneyMetaInput;
|
|
72
175
|
run: JourneyRunFn;
|
|
73
176
|
}): DefinedJourney {
|
|
177
|
+
const runSource = safeRunSource(options.run);
|
|
178
|
+
const source = captureCallSite();
|
|
74
179
|
const { trigger, exitOn, ...rest } = options.meta;
|
|
75
180
|
const triggerWhere = normalizeWhere(trigger.where);
|
|
76
181
|
const meta: JourneyMeta = {
|
|
@@ -222,6 +327,20 @@ export function defineJourney(options: {
|
|
|
222
327
|
}
|
|
223
328
|
|
|
224
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
|
+
|
|
225
344
|
// The replay-stable key anchor: prefer the run id (constant across replays
|
|
226
345
|
// of this run), fall back to stateId when the engine has no run id.
|
|
227
346
|
const runAnchor = workflowRunId || stateId;
|
|
@@ -339,6 +458,15 @@ export function defineJourney(options: {
|
|
|
339
458
|
})
|
|
340
459
|
.where(eq(journeyStates.id, stateId));
|
|
341
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
|
+
|
|
342
470
|
await hatchet.events.push("journey:completed", {
|
|
343
471
|
journeyId: meta.id,
|
|
344
472
|
stateId,
|
|
@@ -414,6 +542,18 @@ export function defineJourney(options: {
|
|
|
414
542
|
error: message,
|
|
415
543
|
});
|
|
416
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
|
+
|
|
417
557
|
await hatchet.events.push("journey:failed", {
|
|
418
558
|
journeyId: meta.id,
|
|
419
559
|
stateId,
|
|
@@ -426,5 +566,5 @@ export function defineJourney(options: {
|
|
|
426
566
|
},
|
|
427
567
|
});
|
|
428
568
|
|
|
429
|
-
return { meta, task };
|
|
569
|
+
return { meta, task, runSource, source };
|
|
430
570
|
}
|