@hogsend/engine 0.39.0 → 0.41.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.
Files changed (64) hide show
  1. package/package.json +9 -7
  2. package/src/buckets/check-membership.ts +6 -1
  3. package/src/campaigns/cohort-sql.ts +198 -0
  4. package/src/campaigns/define-campaign.ts +301 -0
  5. package/src/campaigns/reconcile.ts +391 -0
  6. package/src/campaigns/steps.ts +48 -0
  7. package/src/connectors/define-action.ts +70 -0
  8. package/src/container.ts +144 -42
  9. package/src/destinations/presets/posthog.ts +7 -1
  10. package/src/env.ts +14 -0
  11. package/src/index.ts +98 -3
  12. package/src/journeys/constants.ts +10 -0
  13. package/src/journeys/define-journey.ts +14 -405
  14. package/src/journeys/execute-journey-run.ts +608 -0
  15. package/src/journeys/graph/build-graph.ts +212 -56
  16. package/src/journeys/journey-boundary.ts +54 -0
  17. package/src/journeys/journey-context.ts +374 -59
  18. package/src/journeys/record-once.ts +110 -0
  19. package/src/lib/auth.ts +33 -1
  20. package/src/lib/blueprints.ts +576 -0
  21. package/src/lib/campaign-send-key.ts +58 -0
  22. package/src/lib/connector-actions.ts +203 -19
  23. package/src/lib/contacts.ts +54 -0
  24. package/src/lib/email-service-types.ts +4 -1
  25. package/src/lib/email.ts +13 -2
  26. package/src/lib/feed.ts +77 -57
  27. package/src/lib/frequency-cap.ts +45 -15
  28. package/src/lib/hatchet-duration.ts +22 -0
  29. package/src/lib/html.ts +1 -0
  30. package/src/lib/ingestion.ts +145 -4
  31. package/src/lib/journey-suppress.ts +87 -0
  32. package/src/lib/links.ts +204 -18
  33. package/src/lib/outbound.ts +20 -0
  34. package/src/lib/preferences.ts +80 -1
  35. package/src/lib/tracked.ts +44 -29
  36. package/src/lib/tracking-event-names.ts +8 -0
  37. package/src/lib/webhook-signing.ts +6 -1
  38. package/src/lists/channels.ts +75 -0
  39. package/src/lists/define-list.ts +34 -0
  40. package/src/lists/registry.ts +29 -2
  41. package/src/mcp/blueprint-tools.ts +460 -0
  42. package/src/routes/admin/blueprints.ts +711 -0
  43. package/src/routes/admin/campaigns.ts +341 -0
  44. package/src/routes/admin/emails.ts +13 -0
  45. package/src/routes/admin/index.ts +6 -0
  46. package/src/routes/admin/journeys.ts +4 -2
  47. package/src/routes/admin/links.ts +303 -36
  48. package/src/routes/admin/lists.ts +51 -0
  49. package/src/routes/campaigns/index.ts +297 -50
  50. package/src/routes/email/preferences.ts +50 -13
  51. package/src/routes/feed/recipient.ts +2 -43
  52. package/src/routes/index.ts +6 -0
  53. package/src/routes/lists/index.ts +138 -18
  54. package/src/routes/tracking/arrive.ts +260 -0
  55. package/src/routes/tracking/click-pipeline.ts +329 -0
  56. package/src/routes/tracking/click.ts +5 -270
  57. package/src/routes/tracking/index.ts +2 -0
  58. package/src/routes/tracking/vanity.ts +64 -0
  59. package/src/worker.ts +27 -0
  60. package/src/workflows/bucket-backfill.ts +4 -2
  61. package/src/workflows/bucket-reconcile.ts +11 -4
  62. package/src/workflows/check-alerts.ts +130 -1
  63. package/src/workflows/journey-blueprint-interpreter.ts +561 -0
  64. package/src/workflows/send-campaign.ts +673 -127
package/src/container.ts CHANGED
@@ -22,6 +22,7 @@ import {
22
22
  buildBucketRegistry,
23
23
  collectBucketReactionJourneys,
24
24
  } from "./buckets/registry.js";
25
+ import type { DefinedCampaign } from "./campaigns/define-campaign.js";
25
26
  import {
26
27
  ConnectorActionRegistry,
27
28
  setConnectorActionRegistry,
@@ -78,6 +79,7 @@ import { createRedisSecondaryStorage, getRedis } from "./lib/redis.js";
78
79
  import { sendResetPasswordEmail } from "./lib/reset-email.js";
79
80
  import { seedPostHogDestination } from "./lib/seed-posthog-destination.js";
80
81
  import { prepareTrackedHtml } from "./lib/tracking.js";
82
+ import { synthesizeChannelLists } from "./lists/channels.js";
81
83
  import {
82
84
  type DefinedList,
83
85
  isReservedListId,
@@ -183,6 +185,12 @@ export interface HogsendClient {
183
185
  * elsewhere via `getListRegistry()`). Empty when no lists are wired.
184
186
  */
185
187
  listRegistry: ListRegistry;
188
+ /**
189
+ * Code-defined one-shot campaigns (broadcasts), verbatim from
190
+ * `opts.campaigns`. The worker's boot reconciler turns them into scheduled
191
+ * `campaigns` rows; empty when none are wired.
192
+ */
193
+ campaigns: DefinedCampaign[];
186
194
  /**
187
195
  * The unified inbound CONNECTOR registry, keyed by `meta.id`. Holds every
188
196
  * transport: webhook (the `:sourceId` dispatch + legacy webhookSources),
@@ -226,6 +234,13 @@ export interface HogsendClientOptions {
226
234
  * preference center. Defaults to none (empty registry ⇒ legacy opt-in).
227
235
  */
228
236
  lists?: DefinedList[];
237
+ /**
238
+ * Code-defined one-shot campaigns (broadcasts) — `defineCampaign()` files.
239
+ * Carried on the client so the worker's boot reconciler can schedule them
240
+ * (see `reconcileDefinedCampaigns`); the API process only stores them.
241
+ * Defaults to none.
242
+ */
243
+ campaigns?: DefinedCampaign[];
229
244
  /**
230
245
  * Email is a first-class channel. Its config is grouped here rather than
231
246
  * spread across top-level args — the engine owns the cohesive email pipeline
@@ -393,6 +408,96 @@ export interface HogsendClientOptions {
393
408
  };
394
409
  }
395
410
 
411
+ /**
412
+ * Boot-validate ONE email-preference `category` against the resolvable list
413
+ * namespace — shared by both the template loop and the journey loop below so a
414
+ * category typo/consent-flip is caught fail-CLOSED wherever a category is
415
+ * declared. `owner` is the human-readable prefix naming the offending
416
+ * declaration (e.g. `Email template "welcome"` / `Journey "my-journey"`), so the
417
+ * throw/warn messages read naturally for either source.
418
+ *
419
+ * A `category` IS the `email_preferences.categories` key: at send time
420
+ * `lib/tracked.ts` resolves the effective category and `checkSuppression` gates
421
+ * it through `ListRegistry.isSubscribed`, whose legacy fallback is
422
+ * `this.get(id)?.defaultOptIn ?? true`. So an UNKNOWN/typo'd id resolves to the
423
+ * `?? true` opt-in default → treated as subscribed → NOT suppressed → an opt-in/
424
+ * consent email delivered to everyone (CAN-SPAM/GDPR-grade). This guard makes a
425
+ * mismatched category a loud boot failure so it can never reach that fallback.
426
+ *
427
+ * Branch semantics (preserved from the original inline template loop):
428
+ * - CHANNEL list (`kind:"channel"`) → THROW. A channel gates a delivery
429
+ * transport, not an email topic; using one as an email category is a category
430
+ * error (it would also opt-out-gate the send by the connector's channel).
431
+ * - reserved built-in (`transactional`/`journey`) → OK.
432
+ * - registered topic list → OK.
433
+ * - DEFINED but registry-EXCLUDED (ENABLED_LISTS) → THROW for an opt-in list
434
+ * (excluding it un-gates consent), WARN for an opt-out list (behavior-
435
+ * preserving, but the preference-center entry is hidden while excluded).
436
+ * - unknown → THROW.
437
+ */
438
+ function validateListCategory(opts: {
439
+ owner: string;
440
+ category: string;
441
+ listRegistry: ListRegistry;
442
+ /** id → `defaultOptIn` for every DEFINED list (`opts.lists`), enabled or not. */
443
+ definedLists: Map<string, boolean>;
444
+ logger: Logger;
445
+ }): void {
446
+ const { owner, category, listRegistry, definedLists, logger } = opts;
447
+
448
+ // A channel list is a registered list (so `has()`/`isSubscribed` treat it as
449
+ // known), which means the reserved/registered OK branches below would wave it
450
+ // through. Reject it FIRST: a channel gates a delivery transport (the in-app
451
+ // feed, a connector), never an email topic.
452
+ if (listRegistry.isChannel(category)) {
453
+ throw new Error(
454
+ `${owner} uses category "${category}": a channel preference list gates a delivery transport, not an email topic — pick a topic list or a built-in category.`,
455
+ );
456
+ }
457
+ // Reserved built-in category (transactional / journey) — never a list, but a
458
+ // legitimate `email_preferences.categories` key. OK.
459
+ if (isReservedListId(category)) return;
460
+ // Category names a REGISTERED topic list ⇒ suppression/preferences gate
461
+ // correctly. (A `defineList({ enabled:false })` is STILL registered — the
462
+ // registry filters on ENABLED_LISTS only, never `meta.enabled` — so it lands
463
+ // here, not in the excluded branch below.)
464
+ if (listRegistry.has(category)) return;
465
+ // Category names a DEFINED list that is EXCLUDED from the registry by an
466
+ // ENABLED_LISTS allowlist that doesn't name it. Excluding it makes the
467
+ // send-time check fall back to the legacy `?? true` opt-in default, which
468
+ // FLIPS the gate by polarity:
469
+ // • opt-IN list (`defaultOptIn:false`, consent required): enabled →
470
+ // `categories[id] === true` (never-consented = NOT subscribed =
471
+ // suppressed); excluded → `categories[id] !== false` (never-consented =
472
+ // SUBSCRIBED = NOT suppressed) → the consent email SHIPS to someone who
473
+ // never opted in. Disabling un-gates consent → THROW (fail closed).
474
+ // • opt-OUT list (`defaultOptIn:true`): both enabled and excluded compute
475
+ // `categories[id] !== false` — IDENTICAL, behavior-preserving → WARN.
476
+ const definedOptIn = definedLists.get(category);
477
+ if (definedOptIn !== undefined) {
478
+ if (definedOptIn === false) {
479
+ throw new Error(
480
+ `${owner} 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 category) — disabling an opt-in list must not silently flip its consent gate open.`,
481
+ );
482
+ }
483
+ logger.warn(
484
+ `${owner} 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 category.`,
485
+ );
486
+ return;
487
+ }
488
+ // Unknown category: neither a reserved built-in nor a defined list. At send
489
+ // time this resolves to the `?? true` opt-in default, bypassing suppression/
490
+ // consent. Fail CLOSED with an actionable message.
491
+ const knownLists = [...definedLists.keys()];
492
+ throw new Error(
493
+ `${owner} has category "${category}", which is neither a reserved built-in category (${[
494
+ ...RESERVED_LIST_IDS,
495
+ ].join(", ")}) nor a defined email list (${
496
+ knownLists.length ? knownLists.join(", ") : "none"
497
+ }). A 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.`,
498
+ );
499
+ }
500
+
396
501
  export function createHogsendClient(
397
502
  opts: HogsendClientOptions = {},
398
503
  ): HogsendClient {
@@ -452,9 +557,17 @@ export function createHogsendClient(
452
557
  // worker (both call createHogsendClient), so `getListRegistry()` resolves the
453
558
  // wired lists in the mailer's suppression check and the preference center in
454
559
  // either process. `buildListRegistry` installs the process singleton.
560
+ //
561
+ // Channel lists (the in-app feed + one per connector exposing member-directed
562
+ // actions) are synthesized from the raw `opts.connectorActions` array — which
563
+ // is available here before the connector-action registry is built, and is
564
+ // identical in both the API and worker processes — then registered
565
+ // unconditionally (bypassing ENABLED_LISTS) after the user lists.
566
+ const channelLists = synthesizeChannelLists(opts.connectorActions ?? []);
455
567
  const listRegistry = buildListRegistry(
456
568
  opts.lists ?? [],
457
569
  opts.enabledLists ?? env.ENABLED_LISTS,
570
+ channelLists,
458
571
  );
459
572
 
460
573
  // Build the email provider registry, then resolve the single active provider
@@ -559,48 +672,31 @@ export function createHogsendClient(
559
672
  const category = (def as TemplateDefinition | undefined)?.category;
560
673
  // No category ⇒ no per-list gating for this template; nothing to validate.
561
674
  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
- );
675
+ validateListCategory({
676
+ owner: `Email template "${templateKey}"`,
677
+ category,
678
+ listRegistry,
679
+ definedLists,
680
+ logger,
681
+ });
682
+ }
683
+
684
+ // Boot-validate every journey's `meta.category` through the SAME helper (same
685
+ // fail-closed branch semantics as templates). A journey stamps its category on
686
+ // every `sendEmail` at send time (overriding the template's own category), so
687
+ // a typo/channel/consent-flip here is exactly as dangerous as on a template.
688
+ // Bucket-reaction journeys never carry a `category`, so `opts.journeys` is the
689
+ // complete set to check. Placed right beside the template loop.
690
+ for (const journey of opts.journeys ?? []) {
691
+ const category = journey.meta.category;
692
+ if (!category) continue;
693
+ validateListCategory({
694
+ owner: `Journey "${journey.meta.id}"`,
695
+ category,
696
+ listRegistry,
697
+ definedLists,
698
+ logger,
699
+ });
604
700
  }
605
701
 
606
702
  const emailService =
@@ -660,6 +756,11 @@ export function createHogsendClient(
660
756
  db,
661
757
  secret: env.BETTER_AUTH_SECRET,
662
758
  baseURL: env.BETTER_AUTH_URL,
759
+ // Give the engine (Studio/dogfood, e.g. t.hogsend.com) its OWN cookie
760
+ // namespace so its session cookie stops colliding with a sibling web
761
+ // app's `.hogsend.com` cross-subdomain SSO cookie. Env default is
762
+ // "hogsend"; no deploy needs to set AUTH_COOKIE_PREFIX explicitly.
763
+ cookiePrefix: env.AUTH_COOKIE_PREFIX,
663
764
  secondaryStorage: authSecondaryStorage,
664
765
  // Always trust the public API origin; add any explicitly configured ones
665
766
  // (e.g. a remote Studio origin) on top. baseURL is trusted automatically.
@@ -898,6 +999,7 @@ export function createHogsendClient(
898
999
  journeySourceLocations: getJourneySourceLocations(),
899
1000
  bucketRegistry,
900
1001
  listRegistry,
1002
+ campaigns: opts.campaigns ?? [],
901
1003
  connectorRegistry,
902
1004
  connectorActionRegistry,
903
1005
  hatchet: opts.overrides?.hatchet ?? hatchet,
@@ -162,8 +162,14 @@ export const posthogDestination = defineDestination({
162
162
  userId?: string | null;
163
163
  to?: string | null;
164
164
  userEmail?: string | null;
165
+ anonymousId?: string | null;
165
166
  };
166
- const distinctId = data.userId ?? data.to ?? data.userEmail ?? undefined;
167
+ // `anonymousId` covers anon-tier arrivals (`link.arrived`): a raw browser
168
+ // anon id IS a legitimate PostHog distinct_id, and without it the capture
169
+ // would ship no distinct_id at all — PostHog 400s and the delivery
170
+ // dead-letters (<500 = non-retryable).
171
+ const distinctId =
172
+ data.userId ?? data.anonymousId ?? data.to ?? data.userEmail ?? undefined;
167
173
  // `email.action` is the semantic-link envelope: the CONSUMER's event name
168
174
  // (data.event, e.g. "nps.submitted") is what PostHog should capture, with
169
175
  // the author's properties flattened to the top level. Other catalog events
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,19 @@ 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";
111
+ export { step } from "./campaigns/steps.js";
99
112
  // --- Cold-connect (email-confirmed chat-platform contact linking) ---
100
113
  export {
101
114
  type ColdConnect,
@@ -112,8 +125,11 @@ export {
112
125
  } from "./connectors/action-registry-singleton.js";
113
126
  export {
114
127
  type ConnectorActionCtx,
128
+ type ConnectorActionSkipped,
115
129
  type DefinedConnectorAction,
116
130
  defineConnectorAction,
131
+ isConnectorActionSkipped,
132
+ type MemberAudience,
117
133
  type ResolvedActionContact,
118
134
  } from "./connectors/define-action.js";
119
135
  // --- Inbound connectors: unified authoring layer ---
@@ -181,11 +197,21 @@ export {
181
197
  // --- Env ---
182
198
  export { API_VERSION, env } from "./env.js";
183
199
  // --- Journeys ---
200
+ export { BLUEPRINT_RUN_EVENT } from "./journeys/constants.js";
184
201
  export {
185
202
  type DefinedJourney,
186
203
  defineJourney,
187
204
  } from "./journeys/define-journey.js";
188
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";
189
215
  // --- Journey graph extractor (Studio visual workflow) ---
190
216
  export {
191
217
  buildJourneyGraph,
@@ -198,6 +224,7 @@ export {
198
224
  type JourneyBoundary,
199
225
  parseJourneySendSite,
200
226
  registerKey,
227
+ registerRecordLabel,
201
228
  runWithJourneyBoundary,
202
229
  } from "./journeys/journey-boundary.js";
203
230
  export { createJourneyContext } from "./journeys/journey-context.js";
@@ -217,6 +244,10 @@ export {
217
244
  resetJourneySources,
218
245
  setJourneySources,
219
246
  } from "./journeys/journey-sources-singleton.js";
247
+ export {
248
+ type RecordNamespace,
249
+ recordOnce,
250
+ } from "./journeys/record-once.js";
220
251
  export {
221
252
  buildJourneyRegistry,
222
253
  parseEnabledFilter,
@@ -261,6 +292,28 @@ export {
261
292
  type SendBannerResult,
262
293
  sendBanner,
263
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 SerializedBlueprint,
311
+ serializeBlueprint,
312
+ type UpdateBlueprintPatch,
313
+ type UpdateBlueprintResult,
314
+ updateBlueprint,
315
+ validateBlueprintGraphForSave,
316
+ } from "./lib/blueprints.js";
264
317
  // --- Boot output (engine-owned startup banner / structured ready log) ---
265
318
  export {
266
319
  type ApiReadyInfo,
@@ -363,7 +416,7 @@ export {
363
416
  type SendFeedItemResult,
364
417
  sendFeedItem,
365
418
  } from "./lib/feed.js";
366
- export { isFrequencyCapped } from "./lib/frequency-cap.js";
419
+ export { countRecentSends, isFrequencyCapped } from "./lib/frequency-cap.js";
367
420
  export { addrSpecOf, hostOfFromAddress } from "./lib/from-address.js";
368
421
  export { hatchet } from "./lib/hatchet.js";
369
422
  // --- Identity service (resolve/merge + analytics merge propagation, §7) ---
@@ -381,6 +434,7 @@ export {
381
434
  } from "./lib/identity-token.js";
382
435
  // --- Ingestion pipeline ---
383
436
  export {
437
+ checkBlueprintTriggers,
384
438
  type IngestEvent,
385
439
  type IngestResult,
386
440
  ingestEvent,
@@ -393,11 +447,17 @@ export {
393
447
  renewLeaderLease,
394
448
  } from "./lib/leader-lease.js";
395
449
  // --- Managed tracked links (channel-agnostic mint — Studio/Discord/share) ---
450
+ // NOTE: the QR scan-row plumbing (ensureQrTrackedLink, the canonical-row
451
+ // filter, the 'qr' source marker) is deliberately NOT exported — it is
452
+ // internal mechanics behind the /qr endpoint, not semver surface.
396
453
  export {
397
454
  type LinkType,
398
455
  type MintedLink,
399
456
  type MintLinkOptions,
400
457
  mintLink,
458
+ normalizeSlug,
459
+ SlugTakenError,
460
+ vanityUrlFor,
401
461
  } from "./lib/links.js";
402
462
  // --- Logging ---
403
463
  export { createLogger, type Logger } from "./lib/logger.js";
@@ -424,6 +484,11 @@ export {
424
484
  export { getPostHog } from "./lib/posthog.js";
425
485
  // --- PostHog OAuth scopes (front-loaded set; gap-detector source of truth) ---
426
486
  export { EXPECTED_POSTHOG_SCOPES } from "./lib/posthog-scopes.js";
487
+ // --- Recipient preferences (shared aggregated read across email/feed/connectors) ---
488
+ export {
489
+ type RecipientPreferences,
490
+ readRecipientPreferences,
491
+ } from "./lib/preferences.js";
427
492
  // --- Provider credentials (encrypted-at-rest OAuth token store) ---
428
493
  export {
429
494
  type CredentialKind,
@@ -533,9 +598,15 @@ export {
533
598
  type WebhookEventType,
534
599
  } from "./lib/webhook-signing.js";
535
600
  // --- Lists (D3) ---
601
+ // NOTE: `IN_APP_LIST_ID` is canonically defined in `./lists/channels.js` but
602
+ // exported here via `./lib/feed.js` (which re-exports it) to keep its
603
+ // pre-existing import path stable — do NOT also export it from channels.js
604
+ // (a duplicate named export).
605
+ export { synthesizeChannelLists } from "./lists/channels.js";
536
606
  export {
537
607
  type DefinedList,
538
608
  defineList,
609
+ type ListKind,
539
610
  type ListMeta,
540
611
  } from "./lists/define-list.js";
541
612
  export { buildListRegistry, ListRegistry } from "./lists/registry.js";
@@ -544,6 +615,15 @@ export {
544
615
  resetListRegistry,
545
616
  setListRegistry,
546
617
  } from "./lists/registry-singleton.js";
618
+ // --- Journey blueprints: agent-facing authoring tools (spec §9, phase 4) ---
619
+ export {
620
+ type BlueprintToolDefinition,
621
+ type BlueprintToolInvalidInput,
622
+ type BlueprintToolIssue,
623
+ createJourneyBlueprintTools,
624
+ type JourneyBlueprintTools,
625
+ type JourneyBlueprintToolsOptions,
626
+ } from "./mcp/blueprint-tools.js";
547
627
  // --- Webhook sources ---
548
628
  export {
549
629
  type DefinedWebhookSource,
@@ -580,7 +660,10 @@ export {
580
660
  bucketExpiryTask,
581
661
  bucketReconcileTask,
582
662
  } from "./workflows/bucket-reconcile.js";
583
- export { checkAlertsTask } from "./workflows/check-alerts.js";
663
+ export {
664
+ checkAlertsTask,
665
+ surfaceStrandedWaiting,
666
+ } from "./workflows/check-alerts.js";
584
667
  // --- Outbound webhooks: durable delivery task + reaper (Section 1.5) ---
585
668
  export {
586
669
  deliverWebhookTask,
@@ -595,7 +678,19 @@ export {
595
678
  type SuppressionImportRow,
596
679
  type SuppressionReason,
597
680
  } from "./workflows/import-suppressions.js";
598
- export { sendCampaignTask } from "./workflows/send-campaign.js";
681
+ // --- Journey blueprints: the generic interpreter task (spec §5/§6) ---
682
+ export {
683
+ type BlueprintRunPayload,
684
+ blueprintMetaFromRow,
685
+ type JourneyBlueprintRow,
686
+ journeyBlueprintInterpreter,
687
+ type WalkBlueprintGraphOptions,
688
+ walkBlueprintGraph,
689
+ } from "./workflows/journey-blueprint-interpreter.js";
690
+ export {
691
+ reapStuckCampaignsTask,
692
+ sendCampaignTask,
693
+ } from "./workflows/send-campaign.js";
599
694
  // --- Built-in Hatchet workflow tasks ---
600
695
  export { sendEmailTask } from "./workflows/send-email.js";
601
696
  export { sendFeedTask } from "./workflows/send-feed.js";
@@ -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";