@hogsend/engine 0.40.0 → 0.42.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 +11 -8
- package/src/buckets/check-membership.ts +6 -1
- package/src/campaigns/cohort-sql.ts +198 -0
- package/src/campaigns/define-campaign.ts +207 -28
- package/src/campaigns/reconcile.ts +105 -11
- package/src/campaigns/steps.ts +48 -0
- package/src/connectors/define-action.ts +70 -0
- package/src/container.ts +124 -42
- package/src/destinations/presets/posthog.ts +7 -1
- package/src/index.ts +96 -2
- package/src/journeys/constants.ts +10 -0
- package/src/journeys/define-journey.ts +14 -405
- package/src/journeys/execute-journey-run.ts +641 -0
- package/src/journeys/graph/build-graph.ts +212 -56
- package/src/journeys/journey-boundary.ts +54 -0
- package/src/journeys/journey-context.ts +406 -59
- package/src/journeys/record-once.ts +110 -0
- package/src/lib/blueprint-lock.ts +21 -0
- package/src/lib/blueprints.ts +803 -0
- package/src/lib/campaign-send-key.ts +58 -0
- package/src/lib/connector-actions.ts +203 -19
- package/src/lib/contacts.ts +54 -0
- package/src/lib/email-service-types.ts +4 -1
- package/src/lib/email.ts +13 -2
- package/src/lib/event-names.ts +143 -0
- package/src/lib/feed.ts +77 -57
- package/src/lib/frequency-cap.ts +45 -15
- package/src/lib/hatchet-duration.ts +22 -0
- package/src/lib/html.ts +1 -0
- package/src/lib/ingestion.ts +145 -4
- package/src/lib/journey-suppress.ts +87 -0
- package/src/lib/links.ts +204 -18
- package/src/lib/outbound.ts +20 -0
- package/src/lib/preferences.ts +80 -1
- package/src/lib/tracked.ts +44 -29
- package/src/lib/tracking-event-names.ts +8 -0
- package/src/lib/tracking.ts +1 -5
- package/src/lib/webhook-signing.ts +6 -1
- package/src/lists/channels.ts +75 -0
- package/src/lists/define-list.ts +34 -0
- package/src/lists/registry.ts +29 -2
- package/src/mcp/authoring-guide.ts +160 -0
- package/src/mcp/blueprint-tools.ts +390 -0
- package/src/middleware/require-admin.ts +13 -0
- package/src/routes/admin/api-keys.ts +72 -0
- package/src/routes/admin/blueprints.ts +795 -0
- package/src/routes/admin/campaigns.ts +179 -3
- package/src/routes/admin/emails.ts +13 -0
- package/src/routes/admin/events.ts +55 -0
- package/src/routes/admin/index.ts +4 -0
- package/src/routes/admin/journeys.ts +4 -2
- package/src/routes/admin/links.ts +303 -36
- package/src/routes/admin/lists.ts +51 -0
- package/src/routes/campaigns/index.ts +44 -6
- package/src/routes/email/preferences.ts +50 -13
- package/src/routes/feed/recipient.ts +2 -43
- package/src/routes/index.ts +6 -0
- package/src/routes/lists/index.ts +138 -18
- package/src/routes/tracking/arrive.ts +260 -0
- package/src/routes/tracking/click-pipeline.ts +329 -0
- package/src/routes/tracking/click.ts +5 -270
- package/src/routes/tracking/index.ts +2 -0
- package/src/routes/tracking/vanity.ts +64 -0
- package/src/worker.ts +5 -0
- package/src/workflows/bucket-backfill.ts +4 -2
- package/src/workflows/bucket-reconcile.ts +11 -4
- package/src/workflows/check-alerts.ts +130 -1
- package/src/workflows/journey-blueprint-interpreter.ts +656 -0
- package/src/workflows/send-campaign.ts +574 -180
package/src/index.ts
CHANGED
|
@@ -108,6 +108,7 @@ export {
|
|
|
108
108
|
type ReconcileResult,
|
|
109
109
|
reconcileDefinedCampaigns,
|
|
110
110
|
} from "./campaigns/reconcile.js";
|
|
111
|
+
export { step } from "./campaigns/steps.js";
|
|
111
112
|
// --- Cold-connect (email-confirmed chat-platform contact linking) ---
|
|
112
113
|
export {
|
|
113
114
|
type ColdConnect,
|
|
@@ -124,8 +125,11 @@ export {
|
|
|
124
125
|
} from "./connectors/action-registry-singleton.js";
|
|
125
126
|
export {
|
|
126
127
|
type ConnectorActionCtx,
|
|
128
|
+
type ConnectorActionSkipped,
|
|
127
129
|
type DefinedConnectorAction,
|
|
128
130
|
defineConnectorAction,
|
|
131
|
+
isConnectorActionSkipped,
|
|
132
|
+
type MemberAudience,
|
|
129
133
|
type ResolvedActionContact,
|
|
130
134
|
} from "./connectors/define-action.js";
|
|
131
135
|
// --- Inbound connectors: unified authoring layer ---
|
|
@@ -193,11 +197,21 @@ export {
|
|
|
193
197
|
// --- Env ---
|
|
194
198
|
export { API_VERSION, env } from "./env.js";
|
|
195
199
|
// --- Journeys ---
|
|
200
|
+
export { BLUEPRINT_RUN_EVENT } from "./journeys/constants.js";
|
|
196
201
|
export {
|
|
197
202
|
type DefinedJourney,
|
|
198
203
|
defineJourney,
|
|
199
204
|
} from "./journeys/define-journey.js";
|
|
200
205
|
export { JourneyExitedError } from "./journeys/errors.js";
|
|
206
|
+
export {
|
|
207
|
+
type EventPayloadInput,
|
|
208
|
+
type ExecuteJourneyRunOptions,
|
|
209
|
+
type ExecuteJourneyRunResult,
|
|
210
|
+
executeJourneyRun,
|
|
211
|
+
insertEnrollment,
|
|
212
|
+
type JourneyDurableCtx,
|
|
213
|
+
type JourneyStateRow,
|
|
214
|
+
} from "./journeys/execute-journey-run.js";
|
|
201
215
|
// --- Journey graph extractor (Studio visual workflow) ---
|
|
202
216
|
export {
|
|
203
217
|
buildJourneyGraph,
|
|
@@ -210,6 +224,7 @@ export {
|
|
|
210
224
|
type JourneyBoundary,
|
|
211
225
|
parseJourneySendSite,
|
|
212
226
|
registerKey,
|
|
227
|
+
registerRecordLabel,
|
|
213
228
|
runWithJourneyBoundary,
|
|
214
229
|
} from "./journeys/journey-boundary.js";
|
|
215
230
|
export { createJourneyContext } from "./journeys/journey-context.js";
|
|
@@ -229,6 +244,10 @@ export {
|
|
|
229
244
|
resetJourneySources,
|
|
230
245
|
setJourneySources,
|
|
231
246
|
} from "./journeys/journey-sources-singleton.js";
|
|
247
|
+
export {
|
|
248
|
+
type RecordNamespace,
|
|
249
|
+
recordOnce,
|
|
250
|
+
} from "./journeys/record-once.js";
|
|
232
251
|
export {
|
|
233
252
|
buildJourneyRegistry,
|
|
234
253
|
parseEnabledFilter,
|
|
@@ -273,6 +292,30 @@ export {
|
|
|
273
292
|
type SendBannerResult,
|
|
274
293
|
sendBanner,
|
|
275
294
|
} from "./lib/banner.js";
|
|
295
|
+
// --- Journey blueprints: service layer shared by admin routes + tools (§9) ---
|
|
296
|
+
export {
|
|
297
|
+
type BlueprintRegistryContainer,
|
|
298
|
+
type BlueprintRow,
|
|
299
|
+
type BlueprintServiceContainer,
|
|
300
|
+
blueprintCreateBaseSchema,
|
|
301
|
+
blueprintPatchFieldsSchema,
|
|
302
|
+
type CreateBlueprintInput,
|
|
303
|
+
type CreateBlueprintResult,
|
|
304
|
+
createBlueprint,
|
|
305
|
+
type DisableBlueprintResult,
|
|
306
|
+
disableBlueprint,
|
|
307
|
+
type EnableBlueprintResult,
|
|
308
|
+
enableBlueprint,
|
|
309
|
+
findBlueprintRow,
|
|
310
|
+
type PromoteBlueprintResult,
|
|
311
|
+
promoteBlueprint,
|
|
312
|
+
type SerializedBlueprint,
|
|
313
|
+
serializeBlueprint,
|
|
314
|
+
type UpdateBlueprintPatch,
|
|
315
|
+
type UpdateBlueprintResult,
|
|
316
|
+
updateBlueprint,
|
|
317
|
+
validateBlueprintGraphForSave,
|
|
318
|
+
} from "./lib/blueprints.js";
|
|
276
319
|
// --- Boot output (engine-owned startup banner / structured ready log) ---
|
|
277
320
|
export {
|
|
278
321
|
type ApiReadyInfo,
|
|
@@ -375,7 +418,7 @@ export {
|
|
|
375
418
|
type SendFeedItemResult,
|
|
376
419
|
sendFeedItem,
|
|
377
420
|
} from "./lib/feed.js";
|
|
378
|
-
export { isFrequencyCapped } from "./lib/frequency-cap.js";
|
|
421
|
+
export { countRecentSends, isFrequencyCapped } from "./lib/frequency-cap.js";
|
|
379
422
|
export { addrSpecOf, hostOfFromAddress } from "./lib/from-address.js";
|
|
380
423
|
export { hatchet } from "./lib/hatchet.js";
|
|
381
424
|
// --- Identity service (resolve/merge + analytics merge propagation, §7) ---
|
|
@@ -393,6 +436,7 @@ export {
|
|
|
393
436
|
} from "./lib/identity-token.js";
|
|
394
437
|
// --- Ingestion pipeline ---
|
|
395
438
|
export {
|
|
439
|
+
checkBlueprintTriggers,
|
|
396
440
|
type IngestEvent,
|
|
397
441
|
type IngestResult,
|
|
398
442
|
ingestEvent,
|
|
@@ -405,11 +449,17 @@ export {
|
|
|
405
449
|
renewLeaderLease,
|
|
406
450
|
} from "./lib/leader-lease.js";
|
|
407
451
|
// --- Managed tracked links (channel-agnostic mint — Studio/Discord/share) ---
|
|
452
|
+
// NOTE: the QR scan-row plumbing (ensureQrTrackedLink, the canonical-row
|
|
453
|
+
// filter, the 'qr' source marker) is deliberately NOT exported — it is
|
|
454
|
+
// internal mechanics behind the /qr endpoint, not semver surface.
|
|
408
455
|
export {
|
|
409
456
|
type LinkType,
|
|
410
457
|
type MintedLink,
|
|
411
458
|
type MintLinkOptions,
|
|
412
459
|
mintLink,
|
|
460
|
+
normalizeSlug,
|
|
461
|
+
SlugTakenError,
|
|
462
|
+
vanityUrlFor,
|
|
413
463
|
} from "./lib/links.js";
|
|
414
464
|
// --- Logging ---
|
|
415
465
|
export { createLogger, type Logger } from "./lib/logger.js";
|
|
@@ -436,6 +486,11 @@ export {
|
|
|
436
486
|
export { getPostHog } from "./lib/posthog.js";
|
|
437
487
|
// --- PostHog OAuth scopes (front-loaded set; gap-detector source of truth) ---
|
|
438
488
|
export { EXPECTED_POSTHOG_SCOPES } from "./lib/posthog-scopes.js";
|
|
489
|
+
// --- Recipient preferences (shared aggregated read across email/feed/connectors) ---
|
|
490
|
+
export {
|
|
491
|
+
type RecipientPreferences,
|
|
492
|
+
readRecipientPreferences,
|
|
493
|
+
} from "./lib/preferences.js";
|
|
439
494
|
// --- Provider credentials (encrypted-at-rest OAuth token store) ---
|
|
440
495
|
export {
|
|
441
496
|
type CredentialKind,
|
|
@@ -545,9 +600,15 @@ export {
|
|
|
545
600
|
type WebhookEventType,
|
|
546
601
|
} from "./lib/webhook-signing.js";
|
|
547
602
|
// --- Lists (D3) ---
|
|
603
|
+
// NOTE: `IN_APP_LIST_ID` is canonically defined in `./lists/channels.js` but
|
|
604
|
+
// exported here via `./lib/feed.js` (which re-exports it) to keep its
|
|
605
|
+
// pre-existing import path stable — do NOT also export it from channels.js
|
|
606
|
+
// (a duplicate named export).
|
|
607
|
+
export { synthesizeChannelLists } from "./lists/channels.js";
|
|
548
608
|
export {
|
|
549
609
|
type DefinedList,
|
|
550
610
|
defineList,
|
|
611
|
+
type ListKind,
|
|
551
612
|
type ListMeta,
|
|
552
613
|
} from "./lists/define-list.js";
|
|
553
614
|
export { buildListRegistry, ListRegistry } from "./lists/registry.js";
|
|
@@ -556,6 +617,27 @@ export {
|
|
|
556
617
|
resetListRegistry,
|
|
557
618
|
setListRegistry,
|
|
558
619
|
} from "./lists/registry-singleton.js";
|
|
620
|
+
// --- Journey blueprints: shared authoring-guide text (tools + @hogsend/mcp) ---
|
|
621
|
+
export {
|
|
622
|
+
BLUEPRINT_AUTHORING_GUIDE,
|
|
623
|
+
GRAPH_FORMAT,
|
|
624
|
+
ISSUE_LOOP_HINT,
|
|
625
|
+
} from "./mcp/authoring-guide.js";
|
|
626
|
+
// --- Journey blueprints: agent-facing authoring tools (spec §9, phase 4) ---
|
|
627
|
+
export {
|
|
628
|
+
type BlueprintToolDefinition,
|
|
629
|
+
type BlueprintToolInvalidInput,
|
|
630
|
+
type BlueprintToolIssue,
|
|
631
|
+
createJourneyBlueprintTools,
|
|
632
|
+
type JourneyBlueprintTools,
|
|
633
|
+
type JourneyBlueprintToolsOptions,
|
|
634
|
+
} from "./mcp/blueprint-tools.js";
|
|
635
|
+
export {
|
|
636
|
+
createRateLimit,
|
|
637
|
+
type RateLimitOptions,
|
|
638
|
+
} from "./middleware/rate-limit.js";
|
|
639
|
+
// --- Middleware (consumer-mounted routes, e.g. the @hogsend/mcp hosted route) ---
|
|
640
|
+
export { requireAdmin } from "./middleware/require-admin.js";
|
|
559
641
|
// --- Webhook sources ---
|
|
560
642
|
export {
|
|
561
643
|
type DefinedWebhookSource,
|
|
@@ -592,7 +674,10 @@ export {
|
|
|
592
674
|
bucketExpiryTask,
|
|
593
675
|
bucketReconcileTask,
|
|
594
676
|
} from "./workflows/bucket-reconcile.js";
|
|
595
|
-
export {
|
|
677
|
+
export {
|
|
678
|
+
checkAlertsTask,
|
|
679
|
+
surfaceStrandedWaiting,
|
|
680
|
+
} from "./workflows/check-alerts.js";
|
|
596
681
|
// --- Outbound webhooks: durable delivery task + reaper (Section 1.5) ---
|
|
597
682
|
export {
|
|
598
683
|
deliverWebhookTask,
|
|
@@ -607,6 +692,15 @@ export {
|
|
|
607
692
|
type SuppressionImportRow,
|
|
608
693
|
type SuppressionReason,
|
|
609
694
|
} from "./workflows/import-suppressions.js";
|
|
695
|
+
// --- Journey blueprints: the generic interpreter task (spec §5/§6) ---
|
|
696
|
+
export {
|
|
697
|
+
type BlueprintRunPayload,
|
|
698
|
+
blueprintMetaFromRow,
|
|
699
|
+
type JourneyBlueprintRow,
|
|
700
|
+
journeyBlueprintInterpreter,
|
|
701
|
+
type WalkBlueprintGraphOptions,
|
|
702
|
+
walkBlueprintGraph,
|
|
703
|
+
} from "./workflows/journey-blueprint-interpreter.js";
|
|
610
704
|
export {
|
|
611
705
|
reapStuckCampaignsTask,
|
|
612
706
|
sendCampaignTask,
|
|
@@ -21,3 +21,13 @@ export const JOURNEY_EXECUTION_TIMEOUT = `${JOURNEY_EXECUTION_TIMEOUT_HOURS}h`;
|
|
|
21
21
|
* stranded. 15m gives resumes head-room to land on a freed slot.
|
|
22
22
|
*/
|
|
23
23
|
export const JOURNEY_SCHEDULE_TIMEOUT = "15m";
|
|
24
|
+
|
|
25
|
+
/**
|
|
26
|
+
* The internal Hatchet event that dispatches ONE blueprint enrollment to the
|
|
27
|
+
* generic `journey-blueprint-interpreter` durable task (spec §5). Pushed by
|
|
28
|
+
* `checkBlueprintTriggers` (ingest) for each enabled `journey_blueprints` row
|
|
29
|
+
* matching the ingested event; the interpreter is the only task subscribed.
|
|
30
|
+
* Lives here (a dependency-free module) so the ingest pipeline and the
|
|
31
|
+
* interpreter share it without a workflows↔lib import cycle.
|
|
32
|
+
*/
|
|
33
|
+
export const BLUEPRINT_RUN_EVENT = "blueprint:run";
|
|
@@ -1,72 +1,20 @@
|
|
|
1
1
|
import { fileURLToPath } from "node:url";
|
|
2
|
-
import type {
|
|
3
|
-
import {
|
|
4
|
-
evaluatePropertyConditions,
|
|
5
|
-
type JourneySourceLocation,
|
|
6
|
-
normalizeWhere,
|
|
7
|
-
} from "@hogsend/core";
|
|
2
|
+
import type { JourneySourceLocation } from "@hogsend/core";
|
|
3
|
+
import { normalizeWhere } from "@hogsend/core";
|
|
8
4
|
import type {
|
|
9
5
|
JourneyMeta,
|
|
10
6
|
JourneyMetaInput,
|
|
11
7
|
JourneyRunFn,
|
|
12
|
-
JourneyUser,
|
|
13
8
|
} from "@hogsend/core/types";
|
|
14
|
-
import { contacts, journeyConfigs, journeyStates } from "@hogsend/db";
|
|
15
|
-
import { and, eq, inArray, notInArray } from "drizzle-orm";
|
|
16
|
-
import { getAnalytics } from "../lib/analytics-singleton.js";
|
|
17
|
-
import { getDb } from "../lib/db.js";
|
|
18
|
-
import {
|
|
19
|
-
checkEmailPreferences,
|
|
20
|
-
checkEntryLimit,
|
|
21
|
-
} from "../lib/enrollment-guards.js";
|
|
22
9
|
import { hatchet } from "../lib/hatchet.js";
|
|
23
|
-
import { createLogger } from "../lib/logger.js";
|
|
24
|
-
import { emitOutbound } from "../lib/outbound.js";
|
|
25
|
-
import { resolveTimezoneWithSource } from "../lib/timezone.js";
|
|
26
|
-
import { getClientScheduleDefaults } from "./client-defaults-singleton.js";
|
|
27
10
|
import {
|
|
28
11
|
JOURNEY_EXECUTION_TIMEOUT,
|
|
29
12
|
JOURNEY_SCHEDULE_TIMEOUT,
|
|
30
13
|
} from "./constants.js";
|
|
31
|
-
import { JourneyExitedError } from "./errors.js";
|
|
32
14
|
import {
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
supportsEviction,
|
|
37
|
-
} from "./journey-boundary.js";
|
|
38
|
-
import { createJourneyContext, TERMINAL_STATUSES } from "./journey-context.js";
|
|
39
|
-
import { logTransition } from "./journey-log.js";
|
|
40
|
-
import { getJourneyRegistrySingleton } from "./registry-singleton.js";
|
|
41
|
-
|
|
42
|
-
const logger = createLogger(process.env.LOG_LEVEL);
|
|
43
|
-
|
|
44
|
-
/**
|
|
45
|
-
* Log whether Hatchet's durable `memo` (Layer-1 fast path) is actually durable
|
|
46
|
-
* on this engine — ONCE per worker process. `supportsEviction === false`
|
|
47
|
-
* (hatchet-lite < v0.80.0) means `memo` silently no-ops, so Layer 2 (the
|
|
48
|
-
* Postgres `email_sends`/`user_events` unique-index dedup) is the sole live
|
|
49
|
-
* guarantee. Surfaced at boot so the team knows which layer is carrying the load.
|
|
50
|
-
*/
|
|
51
|
-
let evictionSupportLogged = false;
|
|
52
|
-
function logEvictionSupportOnce(hatchetCtx: unknown): void {
|
|
53
|
-
if (evictionSupportLogged) return;
|
|
54
|
-
evictionSupportLogged = true;
|
|
55
|
-
const live = supportsEviction(hatchetCtx);
|
|
56
|
-
logger.info(
|
|
57
|
-
live
|
|
58
|
-
? "journey replay-safety: Layer-1 memo fast path is LIVE (engine supports eviction)"
|
|
59
|
-
: "journey replay-safety: Layer-1 memo is INERT (engine < v0.80.0); " +
|
|
60
|
-
"exactly-once relies on the Layer-2 Postgres unique-index dedup",
|
|
61
|
-
);
|
|
62
|
-
}
|
|
63
|
-
|
|
64
|
-
interface EventPayloadInput {
|
|
65
|
-
userId: JsonValue;
|
|
66
|
-
userEmail: JsonValue;
|
|
67
|
-
properties: JsonValue;
|
|
68
|
-
[key: string]: JsonValue;
|
|
69
|
-
}
|
|
15
|
+
type EventPayloadInput,
|
|
16
|
+
executeJourneyRun,
|
|
17
|
+
} from "./execute-journey-run.js";
|
|
70
18
|
|
|
71
19
|
export interface DefinedJourney {
|
|
72
20
|
meta: JourneyMeta;
|
|
@@ -215,355 +163,16 @@ export function defineJourney(options: {
|
|
|
215
163
|
// a slot instead of being cancelled (which strands the enrollment). Unlike
|
|
216
164
|
// retries this adds NO replay — it is pure head-room, so it is safe on its own.
|
|
217
165
|
scheduleTimeout: JOURNEY_SCHEDULE_TIMEOUT,
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
// The replay-stable anchor for this enrollment: the Hatchet run id is
|
|
228
|
-
// preserved across replays of the SAME logical durable run (crash / OOM /
|
|
229
|
-
// eviction / redeploy mid-run), whereas a freshly-minted journeyStates.id
|
|
230
|
-
// is not. Both dedup-key derivation AND the enrollment-recovery below key
|
|
231
|
-
// on it so a replay re-derives the SAME stateId and the SAME keys.
|
|
232
|
-
const workflowRunId = hatchetCtx.workflowRunId();
|
|
233
|
-
|
|
234
|
-
// REPLAY RECOVERY — must run BEFORE the enrollment guards below. An
|
|
235
|
-
// eviction-capable Hatchet engine (hatchet-lite >= v0.80.0) replays `fn`
|
|
236
|
-
// from the top on every durable-wait resume, so every statement above the
|
|
237
|
-
// first durable primitive re-runs on each resume. The enrollment guards
|
|
238
|
-
// (entryLimit / preferences / trigger conditions / enabled / active-state)
|
|
239
|
-
// are ENTRY gates: re-running them on a resume is wrong. In particular a
|
|
240
|
-
// `once` journey's own entry-limit guard would find the row it created on
|
|
241
|
-
// first entry and skip EVERY resume, stranding the journey in `waiting` and
|
|
242
|
-
// silently dropping all sends after the first. Recovering by the run-stable
|
|
243
|
-
// id first lets a resume reuse its enrollment and bypass the entry gates (a
|
|
244
|
-
// resume is not an entry). It also keeps the original purpose: a journey
|
|
245
|
-
// whose prior enrollment reached a TERMINAL status (unlimited /
|
|
246
|
-
// once_per_period) recovers the SAME stateId so derived keys still collide.
|
|
247
|
-
const recovered = workflowRunId
|
|
248
|
-
? await db.query.journeyStates.findFirst({
|
|
249
|
-
where: and(
|
|
250
|
-
eq(journeyStates.hatchetRunId, workflowRunId),
|
|
251
|
-
eq(journeyStates.journeyId, meta.id),
|
|
252
|
-
),
|
|
253
|
-
})
|
|
254
|
-
: undefined;
|
|
255
|
-
|
|
256
|
-
let state = recovered;
|
|
257
|
-
|
|
258
|
-
// FIRST ENTRY ONLY — the enrollment guards gate ENTRY, not resume. A
|
|
259
|
-
// recovered enrollment already passed them on first entry, so it skips
|
|
260
|
-
// straight to resuming the run. (Sends inside `run` still re-check
|
|
261
|
-
// subscription via `ctx.guard.isSubscribed()` after every wait, so
|
|
262
|
-
// bypassing the entry-time preference gate never emails an unsubscriber.)
|
|
263
|
-
if (!state) {
|
|
264
|
-
if (!meta.enabled) {
|
|
265
|
-
return { status: "skipped", reason: "journey_disabled" };
|
|
266
|
-
}
|
|
267
|
-
|
|
268
|
-
const configOverride = await db.query.journeyConfigs.findFirst({
|
|
269
|
-
where: eq(journeyConfigs.journeyId, meta.id),
|
|
270
|
-
});
|
|
271
|
-
if (configOverride && !configOverride.enabled) {
|
|
272
|
-
return { status: "skipped", reason: "journey_disabled_by_admin" };
|
|
273
|
-
}
|
|
274
|
-
|
|
275
|
-
if (meta.trigger.where?.length) {
|
|
276
|
-
if (
|
|
277
|
-
!evaluatePropertyConditions({
|
|
278
|
-
conditions: meta.trigger.where,
|
|
279
|
-
properties,
|
|
280
|
-
})
|
|
281
|
-
) {
|
|
282
|
-
return { status: "skipped", reason: "trigger_conditions_not_met" };
|
|
283
|
-
}
|
|
284
|
-
}
|
|
285
|
-
|
|
286
|
-
const entryAllowed = await checkEntryLimit({
|
|
287
|
-
db,
|
|
288
|
-
journey: meta,
|
|
289
|
-
userId,
|
|
290
|
-
});
|
|
291
|
-
if (!entryAllowed.allowed) {
|
|
292
|
-
return { status: "skipped", reason: entryAllowed.reason };
|
|
293
|
-
}
|
|
294
|
-
|
|
295
|
-
const prefs = await checkEmailPreferences({ db, userId });
|
|
296
|
-
if (prefs.unsubscribed) {
|
|
297
|
-
return { status: "skipped", reason: "user_unsubscribed" };
|
|
298
|
-
}
|
|
299
|
-
|
|
300
|
-
const activeState = await db.query.journeyStates.findFirst({
|
|
301
|
-
where: and(
|
|
302
|
-
eq(journeyStates.userId, userId),
|
|
303
|
-
eq(journeyStates.journeyId, meta.id),
|
|
304
|
-
inArray(journeyStates.status, ["active", "waiting"]),
|
|
305
|
-
),
|
|
306
|
-
});
|
|
307
|
-
if (activeState) {
|
|
308
|
-
return { status: "skipped", reason: "already_active" };
|
|
309
|
-
}
|
|
310
|
-
|
|
311
|
-
[state] = await db
|
|
312
|
-
.insert(journeyStates)
|
|
313
|
-
.values({
|
|
314
|
-
userId,
|
|
315
|
-
userEmail,
|
|
316
|
-
journeyId: meta.id,
|
|
317
|
-
currentNodeId: "start",
|
|
318
|
-
status: "active",
|
|
319
|
-
context: properties,
|
|
320
|
-
hatchetRunId: workflowRunId,
|
|
321
|
-
})
|
|
322
|
-
.returning();
|
|
323
|
-
}
|
|
324
|
-
|
|
325
|
-
if (!state) {
|
|
326
|
-
return { status: "skipped", reason: "state_creation_failed" };
|
|
327
|
-
}
|
|
328
|
-
|
|
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
|
-
|
|
344
|
-
// The replay-stable key anchor: prefer the run id (constant across replays
|
|
345
|
-
// of this run), fall back to stateId when the engine has no run id.
|
|
346
|
-
const runAnchor = workflowRunId || stateId;
|
|
347
|
-
|
|
348
|
-
const user: JourneyUser = {
|
|
349
|
-
id: userId,
|
|
350
|
-
email: userEmail,
|
|
351
|
-
properties,
|
|
352
|
-
stateId,
|
|
353
|
-
journeyId: meta.id,
|
|
354
|
-
journeyName: meta.name,
|
|
355
|
-
};
|
|
356
|
-
|
|
357
|
-
// The injected analytics instance (set by createHogsendClient). Same
|
|
358
|
-
// object as container.analytics; undefined when POSTHOG_API_KEY is unset.
|
|
359
|
-
const posthog = getAnalytics();
|
|
360
|
-
const scheduleDefaults = getClientScheduleDefaults();
|
|
361
|
-
|
|
362
|
-
// Resolve the user's timezone via the precedence chain (explicit is N/A
|
|
363
|
-
// at enrollment; PostHog person props → contacts row → client default →
|
|
364
|
-
// UTC). Best-effort: failures fall through to the client default tz.
|
|
365
|
-
// Independent I/O — fetch the contact row and PostHog person props
|
|
366
|
-
// concurrently. PostHog failures fall through to undefined.
|
|
367
|
-
const [contact, posthogProperties] = await Promise.all([
|
|
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),
|
|
376
|
-
posthog?.getPersonProperties(userId).catch(() => undefined),
|
|
377
|
-
]);
|
|
378
|
-
|
|
379
|
-
const tz = resolveTimezoneWithSource({
|
|
380
|
-
posthogProperties,
|
|
381
|
-
contactTimezone: contact?.timezone ?? null,
|
|
382
|
-
contactProperties: contact?.properties ?? null,
|
|
383
|
-
defaultTimezone: scheduleDefaults.timezone,
|
|
384
|
-
logger,
|
|
385
|
-
});
|
|
386
|
-
|
|
387
|
-
// Opportunistic cache write: when the tz came from a PostHog source and
|
|
388
|
-
// the contacts.timezone column is empty, persist it (fire-and-forget;
|
|
389
|
-
// PostHog/JSONB remain authoritative so nothing blocks on the column).
|
|
390
|
-
if (
|
|
391
|
-
(tz.source === "posthog_timezone" || tz.source === "posthog_geoip") &&
|
|
392
|
-
contact &&
|
|
393
|
-
!contact.timezone
|
|
394
|
-
) {
|
|
395
|
-
db.update(contacts)
|
|
396
|
-
.set({ timezone: tz.timezone, updatedAt: new Date() })
|
|
397
|
-
.where(eq(contacts.id, contact.id))
|
|
398
|
-
.catch(() => {
|
|
399
|
-
// best-effort cache write; never block the journey
|
|
400
|
-
});
|
|
401
|
-
}
|
|
402
|
-
|
|
403
|
-
const ctx = createJourneyContext({
|
|
404
|
-
db,
|
|
405
|
-
hatchet,
|
|
406
|
-
// The real DurableContext structurally satisfies the (widened) config —
|
|
407
|
-
// it exposes `sleepFor`/`waitFor` AND a replay-memoized `now()` (SDK
|
|
408
|
-
// 1.22.3). Forwarding it whole lets ctx clock reads (ctx.when,
|
|
409
|
-
// sleepUntil delta, lookback, ctx.now) read the memoized clock on an
|
|
410
|
-
// eviction-capable engine, falling back to the live clock pre-eviction.
|
|
166
|
+
// The full enrollment + run lifecycle lives in `executeJourneyRun`, shared
|
|
167
|
+
// verbatim with the blueprint interpreter task (spec §6) — code journeys
|
|
168
|
+
// and blueprints execute through the IDENTICAL machinery.
|
|
169
|
+
fn: async (input: EventPayloadInput, hatchetCtx) =>
|
|
170
|
+
executeJourneyRun({
|
|
171
|
+
meta,
|
|
172
|
+
run: options.run,
|
|
173
|
+
input,
|
|
411
174
|
hatchetCtx,
|
|
412
|
-
|
|
413
|
-
logger,
|
|
414
|
-
stateId,
|
|
415
|
-
userId,
|
|
416
|
-
userEmail,
|
|
417
|
-
journeyContext: { ...properties },
|
|
418
|
-
resolvedTimezone: tz.timezone,
|
|
419
|
-
defaultSendWindow: scheduleDefaults.sendWindow,
|
|
420
|
-
});
|
|
421
|
-
|
|
422
|
-
// The journey boundary makes journey side effects (sendEmail, ctx.trigger)
|
|
423
|
-
// EXACTLY-ONCE across a durable replay WITHOUT any change to journey
|
|
424
|
-
// authoring. It is established once around `run()`: a replay-from-top
|
|
425
|
-
// re-enters this scope from the top. Its `runAnchor` is the replay-stable
|
|
426
|
-
// Hatchet run id (recovered above so the SAME stateId is reused on replay),
|
|
427
|
-
// so the derived keys collide across a replay of the same run even if the
|
|
428
|
-
// enrollment row had to be recovered rather than freshly inserted.
|
|
429
|
-
// `memoize` is the Layer-1 fast path (durable only when the engine supports
|
|
430
|
-
// eviction); the auto-derived `email_sends`/`user_events` idempotency keys
|
|
431
|
-
// (anchored on `runAnchor`) are the version-independent Layer-2 guarantee.
|
|
432
|
-
logEvictionSupportOnce(hatchetCtx);
|
|
433
|
-
const boundary: JourneyBoundary = {
|
|
434
|
-
stateId,
|
|
435
|
-
runAnchor,
|
|
436
|
-
currentLabel: undefined,
|
|
437
|
-
seenKeys: new Set<string>(),
|
|
438
|
-
memoize: createMemoize(hatchetCtx),
|
|
439
|
-
};
|
|
440
|
-
|
|
441
|
-
// Seed the context's memoized-clock snapshot ONCE before run() so a
|
|
442
|
-
// `ctx.when` chain used BEFORE the first durable step reads a replay-stable
|
|
443
|
-
// instant (on an eviction engine) instead of the construction-time
|
|
444
|
-
// `new Date()` seed. Best-effort: on a pre-eviction engine this reads the
|
|
445
|
-
// live clock, same as before.
|
|
446
|
-
await ctx.now();
|
|
447
|
-
|
|
448
|
-
try {
|
|
449
|
-
await runWithJourneyBoundary(boundary, () => options.run(user, ctx));
|
|
450
|
-
|
|
451
|
-
const completedAt = new Date();
|
|
452
|
-
await db
|
|
453
|
-
.update(journeyStates)
|
|
454
|
-
.set({
|
|
455
|
-
status: "completed",
|
|
456
|
-
completedAt,
|
|
457
|
-
updatedAt: completedAt,
|
|
458
|
-
})
|
|
459
|
-
.where(eq(journeyStates.id, stateId));
|
|
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
|
-
|
|
470
|
-
await hatchet.events.push("journey:completed", {
|
|
471
|
-
journeyId: meta.id,
|
|
472
|
-
stateId,
|
|
473
|
-
userId,
|
|
474
|
-
});
|
|
475
|
-
|
|
476
|
-
// OUTBOUND `journey.completed` — fired alongside the internal
|
|
477
|
-
// `journey:completed` push. Runs in the WORKER (this durable task), so it
|
|
478
|
-
// uses the engine `db`/`hatchet`/`logger` singletons. `dedupeKey` =
|
|
479
|
-
// `journey.completed:<stateId>`: a Hatchet re-execution recomputes the
|
|
480
|
-
// identical key and the unique `(endpointId, dedupeKey)` index absorbs the
|
|
481
|
-
// duplicate (risk 3). `journey:failed` is NOT in the catalog → no emit.
|
|
482
|
-
void emitOutbound({
|
|
483
|
-
db,
|
|
484
|
-
hatchet,
|
|
485
|
-
logger,
|
|
486
|
-
event: "journey.completed",
|
|
487
|
-
dedupeKey: `journey.completed:${stateId}`,
|
|
488
|
-
payload: {
|
|
489
|
-
journeyId: meta.id,
|
|
490
|
-
journeyName: meta.name,
|
|
491
|
-
stateId,
|
|
492
|
-
userId,
|
|
493
|
-
userEmail,
|
|
494
|
-
completedAt: completedAt.toISOString(),
|
|
495
|
-
},
|
|
496
|
-
}).catch(logger.warn);
|
|
497
|
-
|
|
498
|
-
return { stateId, status: "completed" };
|
|
499
|
-
} catch (err) {
|
|
500
|
-
// The journey reached a terminal state (exitOn / cancel) while suspended
|
|
501
|
-
// in a durable wait. The state row is already terminal — stop gracefully
|
|
502
|
-
// without marking it "failed" or re-pushing a journey:failed event.
|
|
503
|
-
if (err instanceof JourneyExitedError) {
|
|
504
|
-
return { stateId, status: "exited" };
|
|
505
|
-
}
|
|
506
|
-
|
|
507
|
-
const message =
|
|
508
|
-
err instanceof Error ? err.message : "Unknown error during journey";
|
|
509
|
-
|
|
510
|
-
// Mark "failed" ONLY if the row isn't already terminal. A run cancelled
|
|
511
|
-
// by exitOn (ingestEvent sets "exited" then `runs.cancel`) or by the
|
|
512
|
-
// admin route surfaces here as a Hatchet AbortError thrown from the
|
|
513
|
-
// suspended waitFor/sleepFor — NOT a JourneyExitedError. Guarding on a
|
|
514
|
-
// non-terminal status prevents clobbering that "exited" row to "failed"
|
|
515
|
-
// and emitting a spurious journey:failed event.
|
|
516
|
-
const [failed] = await db
|
|
517
|
-
.update(journeyStates)
|
|
518
|
-
.set({
|
|
519
|
-
status: "failed",
|
|
520
|
-
errorMessage: message,
|
|
521
|
-
updatedAt: new Date(),
|
|
522
|
-
})
|
|
523
|
-
.where(
|
|
524
|
-
and(
|
|
525
|
-
eq(journeyStates.id, stateId),
|
|
526
|
-
notInArray(journeyStates.status, [...TERMINAL_STATUSES]),
|
|
527
|
-
),
|
|
528
|
-
)
|
|
529
|
-
.returning({ id: journeyStates.id });
|
|
530
|
-
|
|
531
|
-
if (!failed) {
|
|
532
|
-
// Already terminal (cancelled after exit) — swallow the cancellation
|
|
533
|
-
// so the run doesn't double-report as failed.
|
|
534
|
-
return { stateId, status: "exited" };
|
|
535
|
-
}
|
|
536
|
-
|
|
537
|
-
logger.error("Journey run failed", {
|
|
538
|
-
journeyId: meta.id,
|
|
539
|
-
journeyName: meta.name,
|
|
540
|
-
stateId,
|
|
541
|
-
userId,
|
|
542
|
-
error: message,
|
|
543
|
-
});
|
|
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
|
-
|
|
557
|
-
await hatchet.events.push("journey:failed", {
|
|
558
|
-
journeyId: meta.id,
|
|
559
|
-
stateId,
|
|
560
|
-
userId,
|
|
561
|
-
error: message,
|
|
562
|
-
});
|
|
563
|
-
|
|
564
|
-
throw err;
|
|
565
|
-
}
|
|
566
|
-
},
|
|
175
|
+
}),
|
|
567
176
|
});
|
|
568
177
|
|
|
569
178
|
return { meta, task, runSource, source };
|