@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.
- package/package.json +10 -7
- package/src/campaigns/define-campaign.ts +122 -0
- package/src/campaigns/reconcile.ts +297 -0
- package/src/container.ts +153 -10
- package/src/env.ts +14 -0
- package/src/index.ts +39 -1
- 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/auth.ts +33 -1
- 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/campaigns.ts +165 -0
- package/src/routes/admin/index.ts +4 -0
- package/src/routes/admin/journeys.ts +278 -0
- package/src/routes/admin/open-editor.ts +106 -0
- package/src/routes/campaigns/index.ts +259 -50
- package/src/routes/emails/index.ts +25 -1
- package/src/worker.ts +37 -2
- package/src/workflows/send-campaign.ts +167 -15
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,13 +15,14 @@ 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 {
|
|
21
22
|
buildBucketRegistry,
|
|
22
23
|
collectBucketReactionJourneys,
|
|
23
24
|
} from "./buckets/registry.js";
|
|
25
|
+
import type { DefinedCampaign } from "./campaigns/define-campaign.js";
|
|
24
26
|
import {
|
|
25
27
|
ConnectorActionRegistry,
|
|
26
28
|
setConnectorActionRegistry,
|
|
@@ -41,6 +43,8 @@ import {
|
|
|
41
43
|
import { env } from "./env.js";
|
|
42
44
|
import { setClientScheduleDefaults } from "./journeys/client-defaults-singleton.js";
|
|
43
45
|
import type { DefinedJourney } from "./journeys/define-journey.js";
|
|
46
|
+
import { getJourneySourceLocations } from "./journeys/journey-source-locations-singleton.js";
|
|
47
|
+
import { getJourneySources } from "./journeys/journey-sources-singleton.js";
|
|
44
48
|
import { buildJourneyRegistry } from "./journeys/registry.js";
|
|
45
49
|
import {
|
|
46
50
|
isAnalyticsProvider,
|
|
@@ -75,7 +79,11 @@ import { createRedisSecondaryStorage, getRedis } from "./lib/redis.js";
|
|
|
75
79
|
import { sendResetPasswordEmail } from "./lib/reset-email.js";
|
|
76
80
|
import { seedPostHogDestination } from "./lib/seed-posthog-destination.js";
|
|
77
81
|
import { prepareTrackedHtml } from "./lib/tracking.js";
|
|
78
|
-
import
|
|
82
|
+
import {
|
|
83
|
+
type DefinedList,
|
|
84
|
+
isReservedListId,
|
|
85
|
+
RESERVED_LIST_IDS,
|
|
86
|
+
} from "./lists/define-list.js";
|
|
79
87
|
import { buildListRegistry, type ListRegistry } from "./lists/registry.js";
|
|
80
88
|
import {
|
|
81
89
|
type DefinedWebhookSource,
|
|
@@ -147,6 +155,20 @@ export interface HogsendClient {
|
|
|
147
155
|
*/
|
|
148
156
|
identity: IdentityService;
|
|
149
157
|
registry: JourneyRegistry;
|
|
158
|
+
/**
|
|
159
|
+
* Map of enabled journey id → its captured `run` source string. Populated by
|
|
160
|
+
* `buildJourneyRegistry` (skips journeys whose source failed to serialize).
|
|
161
|
+
* Consumed by the Studio journey-graph route, which parses the source lazily
|
|
162
|
+
* with acorn to derive a visual workflow. Empty when no journeys are wired.
|
|
163
|
+
*/
|
|
164
|
+
journeySources: Map<string, string>;
|
|
165
|
+
/**
|
|
166
|
+
* Map of enabled journey id → its `defineJourney` call-site `{ path, line }`.
|
|
167
|
+
* Populated by `buildJourneyRegistry`. Consumed by the Studio journey-graph
|
|
168
|
+
* route to build an "open in editor" deep link. Absent ids had no capturable
|
|
169
|
+
* call-site (e.g. bucket-generated reaction journeys).
|
|
170
|
+
*/
|
|
171
|
+
journeySourceLocations: Map<string, JourneySourceLocation>;
|
|
150
172
|
/**
|
|
151
173
|
* The bucket registry (id map + event/property inverted indexes for candidate
|
|
152
174
|
* narrowing). Built and installed as the process singleton at client build;
|
|
@@ -162,6 +184,12 @@ export interface HogsendClient {
|
|
|
162
184
|
* elsewhere via `getListRegistry()`). Empty when no lists are wired.
|
|
163
185
|
*/
|
|
164
186
|
listRegistry: ListRegistry;
|
|
187
|
+
/**
|
|
188
|
+
* Code-defined one-shot campaigns (broadcasts), verbatim from
|
|
189
|
+
* `opts.campaigns`. The worker's boot reconciler turns them into scheduled
|
|
190
|
+
* `campaigns` rows; empty when none are wired.
|
|
191
|
+
*/
|
|
192
|
+
campaigns: DefinedCampaign[];
|
|
165
193
|
/**
|
|
166
194
|
* The unified inbound CONNECTOR registry, keyed by `meta.id`. Holds every
|
|
167
195
|
* transport: webhook (the `:sourceId` dispatch + legacy webhookSources),
|
|
@@ -205,6 +233,13 @@ export interface HogsendClientOptions {
|
|
|
205
233
|
* preference center. Defaults to none (empty registry ⇒ legacy opt-in).
|
|
206
234
|
*/
|
|
207
235
|
lists?: DefinedList[];
|
|
236
|
+
/**
|
|
237
|
+
* Code-defined one-shot campaigns (broadcasts) — `defineCampaign()` files.
|
|
238
|
+
* Carried on the client so the worker's boot reconciler can schedule them
|
|
239
|
+
* (see `reconcileDefinedCampaigns`); the API process only stores them.
|
|
240
|
+
* Defaults to none.
|
|
241
|
+
*/
|
|
242
|
+
campaigns?: DefinedCampaign[];
|
|
208
243
|
/**
|
|
209
244
|
* Email is a first-class channel. Its config is grouped here rather than
|
|
210
245
|
* spread across top-level args — the engine owns the cohesive email pipeline
|
|
@@ -379,16 +414,26 @@ export function createHogsendClient(
|
|
|
379
414
|
const created = createDatabase({ url: env.DATABASE_URL });
|
|
380
415
|
const db = opts.overrides?.db ?? created.db;
|
|
381
416
|
|
|
417
|
+
// Resolve buckets + their reaction journeys BEFORE the journey registry so the
|
|
418
|
+
// reaction ids (`bucket-<id>-on-<kind>`, registered separately below) are part
|
|
419
|
+
// of ENABLED_JOURNEYS's known set. They ARE registered journeys, so listing a
|
|
420
|
+
// real reaction id in ENABLED_JOURNEYS must NOT be rejected as a typo.
|
|
421
|
+
const buckets = opts.buckets ?? [];
|
|
422
|
+
const enabledBuckets = opts.enabledBuckets ?? env.ENABLED_BUCKETS;
|
|
423
|
+
const reactionJourneys = collectBucketReactionJourneys(
|
|
424
|
+
buckets,
|
|
425
|
+
enabledBuckets,
|
|
426
|
+
);
|
|
427
|
+
|
|
382
428
|
const registry = buildJourneyRegistry(
|
|
383
429
|
opts.journeys ?? [],
|
|
384
430
|
opts.enabledJourneys ?? env.ENABLED_JOURNEYS,
|
|
431
|
+
reactionJourneys.map((r) => r.meta.id),
|
|
385
432
|
);
|
|
386
433
|
|
|
387
434
|
// Installs the bucket registry singleton in BOTH the API and worker processes
|
|
388
435
|
// (both call createHogsendClient); the real-time ingest path reads it via
|
|
389
436
|
// getBucketRegistrySingleton().
|
|
390
|
-
const buckets = opts.buckets ?? [];
|
|
391
|
-
const enabledBuckets = opts.enabledBuckets ?? env.ENABLED_BUCKETS;
|
|
392
437
|
const bucketRegistry = buildBucketRegistry(buckets, enabledBuckets);
|
|
393
438
|
|
|
394
439
|
// Register the reaction journeys generated by `bucket.on()` into the journey
|
|
@@ -398,10 +443,7 @@ export function createHogsendClient(
|
|
|
398
443
|
// be subject to the journeys csv (Section 9). Both API and worker call
|
|
399
444
|
// createHogsendClient, so the singleton carries reaction metas in both
|
|
400
445
|
// processes (needed for admin feedsJourneys + the dwell-cron lookup).
|
|
401
|
-
for (const reaction of
|
|
402
|
-
buckets,
|
|
403
|
-
enabledBuckets,
|
|
404
|
-
)) {
|
|
446
|
+
for (const reaction of reactionJourneys) {
|
|
405
447
|
registry.register(reaction.meta);
|
|
406
448
|
}
|
|
407
449
|
|
|
@@ -500,6 +542,81 @@ export function createHogsendClient(
|
|
|
500
542
|
|
|
501
543
|
const templates = opts.email?.templates ?? ({} as TemplateRegistry);
|
|
502
544
|
|
|
545
|
+
// Boot-validate every template's `category` against the resolvable list
|
|
546
|
+
// namespace BEFORE the mailer/emailService is constructed — fail CLOSED.
|
|
547
|
+
//
|
|
548
|
+
// A template's `category` (TemplateDefinition.category) IS the
|
|
549
|
+
// email-preferences list key: at send time `lib/tracked.ts` resolves the
|
|
550
|
+
// effective category and `checkSuppression` gates it through
|
|
551
|
+
// `ListRegistry.isSubscribed`, whose `isSubscribedByDefault` legacy fallback
|
|
552
|
+
// is `this.get(id)?.defaultOptIn ?? true`. So a TYPO'd category (e.g.
|
|
553
|
+
// "product-update" when the opt-in list id is "product-updates") resolves to
|
|
554
|
+
// an UNKNOWN id → `?? true` opt-in default → treated as subscribed → NOT
|
|
555
|
+
// suppressed. The consent/opt-in email would then be delivered to EVERY
|
|
556
|
+
// recipient (including never-subscribed) AND anyone who unsubscribed under the
|
|
557
|
+
// correct key would still receive it — CAN-SPAM/GDPR-grade. This guard makes a
|
|
558
|
+
// mismatched category a loud boot failure so it can never reach that fallback.
|
|
559
|
+
//
|
|
560
|
+
// Known-good set = reserved built-ins ∪ DEFINED lists (`opts.lists`), NOT just
|
|
561
|
+
// the ENABLED registry — mirroring the ENABLED_JOURNEYS lesson (validate
|
|
562
|
+
// against DEFINED, not just ENABLED). A DEFINED-but-registry-EXCLUDED list
|
|
563
|
+
// (removed from the registry by an ENABLED_LISTS allowlist that doesn't name
|
|
564
|
+
// it) does NOT auto-warn: excluding it flips the send-time gate by POLARITY,
|
|
565
|
+
// so we branch on `defaultOptIn` (below). We carry each list's `defaultOptIn`
|
|
566
|
+
// (not just its id) so that branch can decide THROW vs WARN. This does NOT
|
|
567
|
+
// change the send-time suppression logic; it only prevents a bad/consent-
|
|
568
|
+
// flipping category reaching it.
|
|
569
|
+
const definedLists = new Map(
|
|
570
|
+
(opts.lists ?? []).map((l) => [l.meta.id, l.meta.defaultOptIn] as const),
|
|
571
|
+
);
|
|
572
|
+
for (const [templateKey, def] of Object.entries(templates)) {
|
|
573
|
+
const category = (def as TemplateDefinition | undefined)?.category;
|
|
574
|
+
// No category ⇒ no per-list gating for this template; nothing to validate.
|
|
575
|
+
if (!category) continue;
|
|
576
|
+
// Reserved built-in category (transactional / journey) — never a list, but
|
|
577
|
+
// a legitimate `email_preferences.categories` key. OK.
|
|
578
|
+
if (isReservedListId(category)) continue;
|
|
579
|
+
// Category names a REGISTERED list ⇒ suppression/preferences gate correctly.
|
|
580
|
+
// (Note: a `defineList({ enabled:false })` is STILL registered — the
|
|
581
|
+
// registry filters on ENABLED_LISTS only, never `meta.enabled` — so it
|
|
582
|
+
// lands here, not in the excluded branch below.)
|
|
583
|
+
if (listRegistry.has(category)) continue;
|
|
584
|
+
// Category names a DEFINED list that is EXCLUDED from the registry by an
|
|
585
|
+
// ENABLED_LISTS allowlist that doesn't name it. Excluding it makes the
|
|
586
|
+
// send-time check fall back to the legacy `?? true` opt-in default, which
|
|
587
|
+
// FLIPS the gate by polarity:
|
|
588
|
+
// • opt-IN list (`defaultOptIn:false`, consent required): enabled →
|
|
589
|
+
// `categories[id] === true` (never-consented = NOT subscribed =
|
|
590
|
+
// suppressed); excluded → `categories[id] !== false` (never-consented =
|
|
591
|
+
// SUBSCRIBED = NOT suppressed) → the consent email SHIPS to someone who
|
|
592
|
+
// never opted in. Disabling un-gates consent → THROW (fail closed).
|
|
593
|
+
// • opt-OUT list (`defaultOptIn:true`): both enabled and excluded compute
|
|
594
|
+
// `categories[id] !== false` — IDENTICAL, behavior-preserving → WARN.
|
|
595
|
+
const definedOptIn = definedLists.get(category);
|
|
596
|
+
if (definedOptIn !== undefined) {
|
|
597
|
+
if (definedOptIn === false) {
|
|
598
|
+
throw new Error(
|
|
599
|
+
`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.`,
|
|
600
|
+
);
|
|
601
|
+
}
|
|
602
|
+
logger.warn(
|
|
603
|
+
`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.`,
|
|
604
|
+
);
|
|
605
|
+
continue;
|
|
606
|
+
}
|
|
607
|
+
// Unknown category: neither a reserved built-in nor a defined list. At send
|
|
608
|
+
// time this resolves to the `?? true` opt-in default, bypassing
|
|
609
|
+
// suppression/consent. Fail CLOSED with an actionable message.
|
|
610
|
+
const knownLists = [...definedLists.keys()];
|
|
611
|
+
throw new Error(
|
|
612
|
+
`Email template "${templateKey}" has category "${category}", which is neither a reserved built-in category (${[
|
|
613
|
+
...RESERVED_LIST_IDS,
|
|
614
|
+
].join(", ")}) nor a defined email list (${
|
|
615
|
+
knownLists.length ? knownLists.join(", ") : "none"
|
|
616
|
+
}). 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.`,
|
|
617
|
+
);
|
|
618
|
+
}
|
|
619
|
+
|
|
503
620
|
const emailService =
|
|
504
621
|
opts.overrides?.mailer ??
|
|
505
622
|
createTrackedMailer(
|
|
@@ -557,6 +674,11 @@ export function createHogsendClient(
|
|
|
557
674
|
db,
|
|
558
675
|
secret: env.BETTER_AUTH_SECRET,
|
|
559
676
|
baseURL: env.BETTER_AUTH_URL,
|
|
677
|
+
// Give the engine (Studio/dogfood, e.g. t.hogsend.com) its OWN cookie
|
|
678
|
+
// namespace so its session cookie stops colliding with a sibling web
|
|
679
|
+
// app's `.hogsend.com` cross-subdomain SSO cookie. Env default is
|
|
680
|
+
// "hogsend"; no deploy needs to set AUTH_COOKIE_PREFIX explicitly.
|
|
681
|
+
cookiePrefix: env.AUTH_COOKIE_PREFIX,
|
|
560
682
|
secondaryStorage: authSecondaryStorage,
|
|
561
683
|
// Always trust the public API origin; add any explicitly configured ones
|
|
562
684
|
// (e.g. a remote Studio origin) on top. baseURL is trusted automatically.
|
|
@@ -611,11 +733,29 @@ export function createHogsendClient(
|
|
|
611
733
|
: wrapLegacyAnalyticsService(analyticsOpt as PostHogService);
|
|
612
734
|
analyticsProviders.register(analytics);
|
|
613
735
|
} else {
|
|
736
|
+
// Resolve the ONE active analytics provider by id — the analytics sibling of
|
|
737
|
+
// the email-provider resolution above, and fail loud on an unresolved
|
|
738
|
+
// active id exactly like `EMAIL_PROVIDER` does. `env.ANALYTICS_PROVIDER`
|
|
739
|
+
// carries a zod `.default("posthog")`, so the resolved id is never empty —
|
|
740
|
+
// that default is what AUTO-ACTIVATES the PostHog env preset when
|
|
741
|
+
// `POSTHOG_API_KEY` is set. Because of that default we must NOT fail boot
|
|
742
|
+
// merely because the resolved id is unregistered: an operator who wired NO
|
|
743
|
+
// analytics still resolves "posthog" and legitimately has no provider (leave
|
|
744
|
+
// `analytics` undefined — reads/mirror stay no-ops). So the throw is gated on
|
|
745
|
+
// the id being EXPLICITLY requested — a code `defaultProvider` OR a SET
|
|
746
|
+
// `ANALYTICS_PROVIDER` env. The RAW `process.env` read (mirroring the
|
|
747
|
+
// `REDIS_URL` read above) is what distinguishes an explicit request from the
|
|
748
|
+
// zod default; without this gate a bogus `ANALYTICS_PROVIDER` typo would
|
|
749
|
+
// SILENTLY disable analytics (killing tz person-reads + the event mirror)
|
|
750
|
+
// instead of failing loud.
|
|
614
751
|
const activeId = analyticsGroup?.defaultProvider ?? env.ANALYTICS_PROVIDER;
|
|
752
|
+
const explicitlyRequested = Boolean(
|
|
753
|
+
analyticsGroup?.defaultProvider ?? process.env.ANALYTICS_PROVIDER,
|
|
754
|
+
);
|
|
615
755
|
analytics = analyticsProviders.get(activeId);
|
|
616
|
-
if (
|
|
756
|
+
if (explicitlyRequested && !analytics) {
|
|
617
757
|
throw new Error(
|
|
618
|
-
`analytics
|
|
758
|
+
`analytics provider "${activeId}" is not registered (registered: ${analyticsProviders
|
|
619
759
|
.getAll()
|
|
620
760
|
.map((p) => p.meta.id)
|
|
621
761
|
.join(", ")})`,
|
|
@@ -773,8 +913,11 @@ export function createHogsendClient(
|
|
|
773
913
|
analytics,
|
|
774
914
|
identity,
|
|
775
915
|
registry,
|
|
916
|
+
journeySources: getJourneySources(),
|
|
917
|
+
journeySourceLocations: getJourneySourceLocations(),
|
|
776
918
|
bucketRegistry,
|
|
777
919
|
listRegistry,
|
|
920
|
+
campaigns: opts.campaigns ?? [],
|
|
778
921
|
connectorRegistry,
|
|
779
922
|
connectorActionRegistry,
|
|
780
923
|
hatchet: opts.overrides?.hatchet ?? hatchet,
|
package/src/env.ts
CHANGED
|
@@ -55,6 +55,20 @@ export const env = createEnv({
|
|
|
55
55
|
// comma-separated. Needed when the Studio is served from a different origin
|
|
56
56
|
// than the API — e.g. the `hogsend studio` CLI pointing at a remote instance.
|
|
57
57
|
BETTER_AUTH_TRUSTED_ORIGINS: z.string().optional(),
|
|
58
|
+
// Cookie NAMESPACE for the engine's own Better Auth (the Studio/dogfood at
|
|
59
|
+
// e.g. t.hogsend.com). Better Auth derives the session cookie name as
|
|
60
|
+
// `<__Secure->?<prefix>.session_token`; with Better Auth's default
|
|
61
|
+
// "better-auth" prefix the engine cookie shares a NAME with any sibling web
|
|
62
|
+
// app that sets a cross-subdomain cookie on the shared parent (e.g.
|
|
63
|
+
// course/docs on `.hogsend.com`), which the browser also delivers to the
|
|
64
|
+
// Studio host — same name, DIFFERENT database → null session → Studio login
|
|
65
|
+
// loop. Defaulting to "hogsend" gives the engine its own namespace
|
|
66
|
+
// (__Secure-hogsend.session_token) so that sibling cookie is simply ignored
|
|
67
|
+
// here. MUST stay optional-with-default — a required value would fail env
|
|
68
|
+
// validation on every deploy that doesn't set it. Prefix affects the cookie
|
|
69
|
+
// NAME only; it is orthogonal to crossSubDomainCookies (the Domain attr),
|
|
70
|
+
// which the engine never sets (host-only).
|
|
71
|
+
AUTH_COOKIE_PREFIX: z.string().min(1).default("hogsend"),
|
|
58
72
|
// Optional: a deploy may run a non-Resend provider (Postmark, SES…) and set
|
|
59
73
|
// no Resend key at all. Read directly ONLY in the lazy-resend default branch
|
|
60
74
|
// (container.ts) and the future `emailProvidersFromEnv` preset. With this
|
package/src/index.ts
CHANGED
|
@@ -96,6 +96,18 @@ export {
|
|
|
96
96
|
resetBucketRegistry,
|
|
97
97
|
setBucketRegistry,
|
|
98
98
|
} from "./buckets/registry-singleton.js";
|
|
99
|
+
// --- Campaigns (one-shot broadcasts) ---
|
|
100
|
+
export {
|
|
101
|
+
type CampaignAudience,
|
|
102
|
+
type CampaignMeta,
|
|
103
|
+
DEFINED_CAMPAIGN_KEY_PREFIX,
|
|
104
|
+
type DefinedCampaign,
|
|
105
|
+
defineCampaign,
|
|
106
|
+
} from "./campaigns/define-campaign.js";
|
|
107
|
+
export {
|
|
108
|
+
type ReconcileResult,
|
|
109
|
+
reconcileDefinedCampaigns,
|
|
110
|
+
} from "./campaigns/reconcile.js";
|
|
99
111
|
// --- Cold-connect (email-confirmed chat-platform contact linking) ---
|
|
100
112
|
export {
|
|
101
113
|
type ColdConnect,
|
|
@@ -186,18 +198,41 @@ export {
|
|
|
186
198
|
defineJourney,
|
|
187
199
|
} from "./journeys/define-journey.js";
|
|
188
200
|
export { JourneyExitedError } from "./journeys/errors.js";
|
|
201
|
+
// --- Journey graph extractor (Studio visual workflow) ---
|
|
202
|
+
export {
|
|
203
|
+
buildJourneyGraph,
|
|
204
|
+
degradedGraphFromMeta,
|
|
205
|
+
} from "./journeys/graph/build-graph.js";
|
|
189
206
|
export {
|
|
190
207
|
createMemoize,
|
|
191
208
|
deriveJourneyKey,
|
|
192
209
|
getJourneyBoundary,
|
|
193
210
|
type JourneyBoundary,
|
|
211
|
+
parseJourneySendSite,
|
|
194
212
|
registerKey,
|
|
195
213
|
runWithJourneyBoundary,
|
|
196
214
|
} from "./journeys/journey-boundary.js";
|
|
197
215
|
export { createJourneyContext } from "./journeys/journey-context.js";
|
|
216
|
+
// --- Journey transition log (journey_logs writer — Phase 2 per-stage metrics) ---
|
|
217
|
+
export {
|
|
218
|
+
type JourneyLogAction,
|
|
219
|
+
type LogTransitionArgs,
|
|
220
|
+
logTransition,
|
|
221
|
+
} from "./journeys/journey-log.js";
|
|
222
|
+
export {
|
|
223
|
+
getJourneySourceLocations,
|
|
224
|
+
resetJourneySourceLocations,
|
|
225
|
+
setJourneySourceLocations,
|
|
226
|
+
} from "./journeys/journey-source-locations-singleton.js";
|
|
227
|
+
export {
|
|
228
|
+
getJourneySources,
|
|
229
|
+
resetJourneySources,
|
|
230
|
+
setJourneySources,
|
|
231
|
+
} from "./journeys/journey-sources-singleton.js";
|
|
198
232
|
export {
|
|
199
233
|
buildJourneyRegistry,
|
|
200
234
|
parseEnabledFilter,
|
|
235
|
+
resolveEnabledFilter,
|
|
201
236
|
selectJourneyTasks,
|
|
202
237
|
} from "./journeys/registry.js";
|
|
203
238
|
export {
|
|
@@ -572,7 +607,10 @@ export {
|
|
|
572
607
|
type SuppressionImportRow,
|
|
573
608
|
type SuppressionReason,
|
|
574
609
|
} from "./workflows/import-suppressions.js";
|
|
575
|
-
export {
|
|
610
|
+
export {
|
|
611
|
+
reapStuckCampaignsTask,
|
|
612
|
+
sendCampaignTask,
|
|
613
|
+
} from "./workflows/send-campaign.js";
|
|
576
614
|
// --- Built-in Hatchet workflow tasks ---
|
|
577
615
|
export { sendEmailTask } from "./workflows/send-email.js";
|
|
578
616
|
export { sendFeedTask } from "./workflows/send-feed.js";
|
|
@@ -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
|
}
|