@hogsend/engine 0.40.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 (62) 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 +207 -28
  5. package/src/campaigns/reconcile.ts +105 -11
  6. package/src/campaigns/steps.ts +48 -0
  7. package/src/connectors/define-action.ts +70 -0
  8. package/src/container.ts +124 -42
  9. package/src/destinations/presets/posthog.ts +7 -1
  10. package/src/index.ts +82 -2
  11. package/src/journeys/constants.ts +10 -0
  12. package/src/journeys/define-journey.ts +14 -405
  13. package/src/journeys/execute-journey-run.ts +608 -0
  14. package/src/journeys/graph/build-graph.ts +212 -56
  15. package/src/journeys/journey-boundary.ts +54 -0
  16. package/src/journeys/journey-context.ts +374 -59
  17. package/src/journeys/record-once.ts +110 -0
  18. package/src/lib/blueprints.ts +576 -0
  19. package/src/lib/campaign-send-key.ts +58 -0
  20. package/src/lib/connector-actions.ts +203 -19
  21. package/src/lib/contacts.ts +54 -0
  22. package/src/lib/email-service-types.ts +4 -1
  23. package/src/lib/email.ts +13 -2
  24. package/src/lib/feed.ts +77 -57
  25. package/src/lib/frequency-cap.ts +45 -15
  26. package/src/lib/hatchet-duration.ts +22 -0
  27. package/src/lib/html.ts +1 -0
  28. package/src/lib/ingestion.ts +145 -4
  29. package/src/lib/journey-suppress.ts +87 -0
  30. package/src/lib/links.ts +204 -18
  31. package/src/lib/outbound.ts +20 -0
  32. package/src/lib/preferences.ts +80 -1
  33. package/src/lib/tracked.ts +44 -29
  34. package/src/lib/tracking-event-names.ts +8 -0
  35. package/src/lib/webhook-signing.ts +6 -1
  36. package/src/lists/channels.ts +75 -0
  37. package/src/lists/define-list.ts +34 -0
  38. package/src/lists/registry.ts +29 -2
  39. package/src/mcp/blueprint-tools.ts +460 -0
  40. package/src/routes/admin/blueprints.ts +711 -0
  41. package/src/routes/admin/campaigns.ts +179 -3
  42. package/src/routes/admin/emails.ts +13 -0
  43. package/src/routes/admin/index.ts +4 -0
  44. package/src/routes/admin/journeys.ts +4 -2
  45. package/src/routes/admin/links.ts +303 -36
  46. package/src/routes/admin/lists.ts +51 -0
  47. package/src/routes/campaigns/index.ts +44 -6
  48. package/src/routes/email/preferences.ts +50 -13
  49. package/src/routes/feed/recipient.ts +2 -43
  50. package/src/routes/index.ts +6 -0
  51. package/src/routes/lists/index.ts +138 -18
  52. package/src/routes/tracking/arrive.ts +260 -0
  53. package/src/routes/tracking/click-pipeline.ts +329 -0
  54. package/src/routes/tracking/click.ts +5 -270
  55. package/src/routes/tracking/index.ts +2 -0
  56. package/src/routes/tracking/vanity.ts +64 -0
  57. package/src/worker.ts +5 -0
  58. package/src/workflows/bucket-backfill.ts +4 -2
  59. package/src/workflows/bucket-reconcile.ts +11 -4
  60. package/src/workflows/check-alerts.ts +130 -1
  61. package/src/workflows/journey-blueprint-interpreter.ts +561 -0
  62. package/src/workflows/send-campaign.ts +574 -180
@@ -1,9 +1,19 @@
1
1
  import type {
2
+ JourneyCheckpointNode,
3
+ JourneyConnectorNode,
4
+ JourneyDigestNode,
2
5
  JourneyEdge,
6
+ JourneyEndNode,
3
7
  JourneyGraph,
4
8
  JourneyMeta,
5
9
  JourneyNode,
6
10
  JourneyNodeType,
11
+ JourneySendNode,
12
+ JourneySleepNode,
13
+ JourneySleepUntilNode,
14
+ JourneyStartNode,
15
+ JourneyTriggerNode,
16
+ JourneyWaitNode,
7
17
  } from "@hogsend/core";
8
18
  import * as acorn from "acorn";
9
19
  import * as walk from "acorn-walk";
@@ -53,12 +63,23 @@ interface OpenEnd {
53
63
  }
54
64
 
55
65
  /** ctx namespaces/methods that are decision inputs / utilities, not nodes. */
56
- const CTX_SKIP = new Set(["history", "guard", "when", "once", "now"]);
66
+ // `throttle` is an advisory frequency check the author branches on (like
67
+ // guard/history) — a decision INPUT, not a durable step, so it never becomes a
68
+ // node (a following `if (!allowed)` still forks as usual).
69
+ const CTX_SKIP = new Set([
70
+ "history",
71
+ "guard",
72
+ "when",
73
+ "once",
74
+ "now",
75
+ "throttle",
76
+ ]);
57
77
  /** ctx primitives that DO become nodes, mapped to their node type. */
58
78
  const CTX_NODE: Record<string, JourneyNodeType> = {
59
79
  sleep: "sleep",
60
80
  sleepUntil: "sleepUntil",
61
81
  waitForEvent: "wait",
82
+ digest: "digest",
62
83
  checkpoint: "checkpoint",
63
84
  trigger: "trigger",
64
85
  };
@@ -170,7 +191,7 @@ function extract(runSource: string, meta: JourneyMeta): JourneyGraph {
170
191
  raws.sort((a, b) => a.start - b.start);
171
192
 
172
193
  // --- Pass B: assign ids (A2 join-key rules) ---
173
- const emitted = assignNodes(raws);
194
+ const emitted = assignNodes(raws, meta.trigger.event);
174
195
  dedupeIds(emitted);
175
196
 
176
197
  const start = startNode(meta);
@@ -518,6 +539,19 @@ function ctxNodeFields(
518
539
  timeout: arg ? extractDuration(objectProp(arg, "timeout")) : undefined,
519
540
  };
520
541
  }
542
+ if (kind === "digest") {
543
+ // ctx.digest({ window, event?, label? }) — `duration` carries the window.
544
+ const label = extractLabel(arg && objectProp(arg, "label"));
545
+ const eventNode = arg ? objectProp(arg, "event") : undefined;
546
+ return {
547
+ kind,
548
+ authoredLabel: label?.value,
549
+ labelUnstable: label?.unstable,
550
+ eventLiteral: stringLiteral(eventNode),
551
+ eventIdent: lastIdentOf(eventNode),
552
+ duration: arg ? extractDuration(objectProp(arg, "window")) : undefined,
553
+ };
554
+ }
521
555
  // trigger
522
556
  const eventNode = arg ? objectProp(arg, "event") : undefined;
523
557
  return {
@@ -543,7 +577,7 @@ function sendFields(arg: acorn.ObjectExpression): ClassifiedFields {
543
577
  // Node id assignment (A2)
544
578
  // ---------------------------------------------------------------------------
545
579
 
546
- function assignNodes(raws: Raw[]): JourneyNode[] {
580
+ function assignNodes(raws: Raw[], triggerEvent?: string): JourneyNode[] {
547
581
  const nodes: JourneyNode[] = [];
548
582
  // The nearest preceding boundary label — the "site" a send inherits when it
549
583
  // has no idempotencyLabel (mirrors the engine's boundary.currentLabel, which
@@ -551,7 +585,12 @@ function assignNodes(raws: Raw[]): JourneyNode[] {
551
585
  let currentLabel: string | undefined;
552
586
 
553
587
  raws.forEach((raw, idx) => {
554
- const { node, boundaryLabel } = nodeFromRaw(raw, idx, currentLabel);
588
+ const { node, boundaryLabel } = nodeFromRaw(
589
+ raw,
590
+ idx,
591
+ currentLabel,
592
+ triggerEvent,
593
+ );
555
594
  if (boundaryLabel !== undefined) currentLabel = boundaryLabel;
556
595
  nodes.push(node);
557
596
  });
@@ -562,15 +601,30 @@ function nodeFromRaw(
562
601
  raw: Raw,
563
602
  idx: number,
564
603
  currentLabel: string | undefined,
604
+ triggerEvent: string | undefined,
565
605
  ): { node: JourneyNode; boundaryLabel?: string } {
566
- const meta: NonNullable<JourneyNode["meta"]> = {};
567
- let id: string;
568
- let title: string;
569
- let subtitle: string | undefined;
570
- let boundaryLabel: string | undefined;
606
+ /** Base fields shared by every variant: id/title + optional subtitle/line. */
607
+ const shell = (
608
+ id: string,
609
+ title: string,
610
+ subtitle?: string,
611
+ ): { id: string; title: string; subtitle?: string; line?: number } => ({
612
+ id,
613
+ title,
614
+ ...(subtitle ? { subtitle } : {}),
615
+ ...(raw.line ? { line: raw.line } : {}),
616
+ });
617
+ /** Omit `meta` entirely when no field was extracted (keeps old shape). */
618
+ const metaSpread = <M extends object>(meta: M): { meta?: M } =>
619
+ Object.keys(meta).length ? { meta } : {};
571
620
 
621
+ // One case per emitted node type, each constructing its own precisely-typed
622
+ // variant of the JourneyNode discriminated union.
572
623
  switch (raw.kind) {
573
624
  case "sleep": {
625
+ const meta: NonNullable<JourneySleepNode["meta"]> = {};
626
+ let id: string;
627
+ let boundaryLabel: string | undefined;
574
628
  if (raw.authoredLabel !== undefined) {
575
629
  id = raw.authoredLabel;
576
630
  boundaryLabel = raw.labelUnstable ? undefined : raw.authoredLabel;
@@ -586,11 +640,20 @@ function nodeFromRaw(
586
640
  }
587
641
  if (raw.duration) meta.duration = raw.duration;
588
642
  if (raw.labelUnstable) meta.unstable = true;
589
- title = raw.authoredLabel ?? "Sleep";
590
- subtitle = raw.duration ? formatDuration(raw.duration) : undefined;
591
- break;
643
+ const subtitle = raw.duration ? formatDuration(raw.duration) : undefined;
644
+ return {
645
+ node: {
646
+ ...shell(id, raw.authoredLabel ?? "Sleep", subtitle),
647
+ type: "sleep",
648
+ ...metaSpread(meta),
649
+ },
650
+ boundaryLabel,
651
+ };
592
652
  }
593
653
  case "sleepUntil": {
654
+ const meta: NonNullable<JourneySleepUntilNode["meta"]> = {};
655
+ let id: string;
656
+ let boundaryLabel: string | undefined;
594
657
  if (raw.authoredLabel !== undefined) {
595
658
  id = raw.authoredLabel;
596
659
  boundaryLabel = raw.labelUnstable ? undefined : raw.authoredLabel;
@@ -599,10 +662,19 @@ function nodeFromRaw(
599
662
  id = `wait-until:${idx}`;
600
663
  meta.unstable = true;
601
664
  }
602
- title = raw.authoredLabel ?? "Sleep until";
603
- break;
665
+ return {
666
+ node: {
667
+ ...shell(id, raw.authoredLabel ?? "Sleep until"),
668
+ type: "sleepUntil",
669
+ ...metaSpread(meta),
670
+ },
671
+ boundaryLabel,
672
+ };
604
673
  }
605
674
  case "wait": {
675
+ const meta: NonNullable<JourneyWaitNode["meta"]> = {};
676
+ let id: string;
677
+ let boundaryLabel: string | undefined;
606
678
  if (raw.authoredLabel !== undefined) {
607
679
  id = raw.authoredLabel;
608
680
  boundaryLabel = raw.labelUnstable ? undefined : raw.authoredLabel;
@@ -618,78 +690,162 @@ function nodeFromRaw(
618
690
  }
619
691
  if (raw.eventLiteral) meta.event = raw.eventLiteral;
620
692
  if (raw.timeout) meta.timeout = raw.timeout;
621
- subtitle = raw.eventLiteral ?? raw.eventIdent;
622
- title = raw.authoredLabel ?? subtitle ?? "Wait for event";
623
- break;
693
+ const subtitle = raw.eventLiteral ?? raw.eventIdent;
694
+ return {
695
+ node: {
696
+ ...shell(
697
+ id,
698
+ raw.authoredLabel ?? subtitle ?? "Wait for event",
699
+ subtitle,
700
+ ),
701
+ type: "wait",
702
+ ...metaSpread(meta),
703
+ },
704
+ boundaryLabel,
705
+ };
706
+ }
707
+ case "digest": {
708
+ // Runtime nodeId = `opts.label ?? digest:${opts.event ?? triggerEvent}`,
709
+ // and digest advances the boundary label (setBoundaryLabel/performSleep)
710
+ // just like sleep/wait — so mirror both here to keep the synthetic id
711
+ // byte-identical to `currentNodeId` and let a following label-less send
712
+ // inherit the digest site.
713
+ const meta: NonNullable<JourneyDigestNode["meta"]> = {};
714
+ let id: string;
715
+ let boundaryLabel: string | undefined;
716
+ if (raw.authoredLabel !== undefined) {
717
+ id = raw.authoredLabel;
718
+ boundaryLabel = raw.labelUnstable ? undefined : raw.authoredLabel;
719
+ if (raw.labelUnstable) meta.unstable = true;
720
+ } else if (raw.eventLiteral !== undefined) {
721
+ id = `digest:${raw.eventLiteral}`;
722
+ boundaryLabel = id;
723
+ } else if (raw.eventIdent === undefined && triggerEvent !== undefined) {
724
+ // No `event` arg → the runtime falls back to the journey's trigger event,
725
+ // which the extractor knows from meta (deterministic + boundary-advancing).
726
+ id = `digest:${triggerEvent}`;
727
+ boundaryLabel = id;
728
+ } else {
729
+ // An explicit but NON-literal event (`Events.X`) resolves to a string the
730
+ // extractor can't see, so the id can't be made byte-identical — synthetic.
731
+ id = `digest:${idx}`;
732
+ meta.unstable = true;
733
+ }
734
+ if (raw.eventLiteral) meta.event = raw.eventLiteral;
735
+ if (raw.duration) meta.duration = raw.duration;
736
+ const subtitle =
737
+ raw.eventLiteral ??
738
+ raw.eventIdent ??
739
+ (raw.duration ? formatDuration(raw.duration) : undefined);
740
+ return {
741
+ node: {
742
+ ...shell(id, raw.authoredLabel ?? "Digest", subtitle),
743
+ type: "digest",
744
+ ...metaSpread(meta),
745
+ },
746
+ boundaryLabel,
747
+ };
624
748
  }
625
749
  case "checkpoint": {
626
- id = raw.authoredLabel ?? `checkpoint:${idx}`;
750
+ const meta: NonNullable<JourneyCheckpointNode["meta"]> = {};
751
+ const id = raw.authoredLabel ?? `checkpoint:${idx}`;
627
752
  if (raw.authoredLabel === undefined || raw.labelUnstable) {
628
753
  meta.unstable = true;
629
754
  }
755
+ let boundaryLabel: string | undefined;
630
756
  if (raw.authoredLabel !== undefined && !raw.labelUnstable) {
631
757
  boundaryLabel = raw.authoredLabel;
632
758
  }
633
- title = "Checkpoint";
634
- subtitle = raw.authoredLabel;
635
- break;
759
+ return {
760
+ node: {
761
+ ...shell(id, "Checkpoint", raw.authoredLabel),
762
+ type: "checkpoint",
763
+ ...metaSpread(meta),
764
+ },
765
+ boundaryLabel,
766
+ };
636
767
  }
637
768
  case "trigger": {
769
+ const meta: NonNullable<JourneyTriggerNode["meta"]> = {};
638
770
  const key = raw.eventLiteral ?? raw.eventIdent ?? String(idx);
639
- id = `trigger:${key}`;
640
771
  if (raw.eventLiteral) meta.event = raw.eventLiteral;
641
- title = "Trigger";
642
- subtitle = raw.eventLiteral ?? raw.eventIdent;
643
- break;
772
+ return {
773
+ node: {
774
+ ...shell(
775
+ `trigger:${key}`,
776
+ "Trigger",
777
+ raw.eventLiteral ?? raw.eventIdent,
778
+ ),
779
+ type: "trigger",
780
+ ...metaSpread(meta),
781
+ },
782
+ };
644
783
  }
645
784
  case "send": {
785
+ const meta: NonNullable<JourneySendNode["meta"]> = {};
646
786
  const site =
647
787
  raw.idempotencyLabel ??
648
788
  currentLabel ??
649
789
  raw.templateLiteral ??
650
790
  raw.templateIdent ??
651
791
  "send";
652
- id = `send:${site}`;
653
792
  if (raw.templateLiteral) meta.template = raw.templateLiteral;
654
793
  if (raw.idempotencyLabel) meta.idempotencyLabel = raw.idempotencyLabel;
655
- title = "Send email";
656
- subtitle =
657
- raw.templateLiteral ?? raw.templateIdent ?? raw.idempotencyLabel;
658
- break;
794
+ return {
795
+ node: {
796
+ ...shell(
797
+ `send:${site}`,
798
+ "Send email",
799
+ raw.templateLiteral ?? raw.templateIdent ?? raw.idempotencyLabel,
800
+ ),
801
+ type: "send",
802
+ ...metaSpread(meta),
803
+ },
804
+ };
659
805
  }
660
806
  case "connector": {
661
- id = `connector:${raw.connectorId ?? idx}:${raw.action ?? idx}`;
807
+ const meta: NonNullable<JourneyConnectorNode["meta"]> = {};
662
808
  if (raw.connectorId) meta.connectorId = raw.connectorId;
663
809
  if (raw.action) meta.action = raw.action;
664
- title = raw.action ?? "Connector action";
665
- subtitle =
666
- [raw.connectorId, raw.action].filter(Boolean).join(" · ") || undefined;
667
- break;
810
+ return {
811
+ node: {
812
+ ...shell(
813
+ `connector:${raw.connectorId ?? idx}:${raw.action ?? idx}`,
814
+ raw.action ?? "Connector action",
815
+ [raw.connectorId, raw.action].filter(Boolean).join(" · ") ||
816
+ undefined,
817
+ ),
818
+ type: "connector",
819
+ ...metaSpread(meta),
820
+ },
821
+ };
668
822
  }
669
823
  case "capture": {
670
- id = `capture:${idx}`;
671
- title = raw.captureMethod === "identify" ? "Identify" : "Capture";
672
- subtitle = raw.captureMethod;
673
- break;
824
+ return {
825
+ node: {
826
+ ...shell(
827
+ `capture:${idx}`,
828
+ raw.captureMethod === "identify" ? "Identify" : "Capture",
829
+ raw.captureMethod,
830
+ ),
831
+ type: "capture",
832
+ },
833
+ };
674
834
  }
675
835
  default: {
676
- // unknown
677
- id = `unknown:${raw.calleeName ?? "call"}:${idx}`;
678
- title = raw.calleeName ?? "Unknown call";
679
- subtitle = "helper call";
680
- break;
836
+ // unknown — the honest escape hatch for unexpanded helper calls.
837
+ return {
838
+ node: {
839
+ ...shell(
840
+ `unknown:${raw.calleeName ?? "call"}:${idx}`,
841
+ raw.calleeName ?? "Unknown call",
842
+ "helper call",
843
+ ),
844
+ type: "unknown",
845
+ },
846
+ };
681
847
  }
682
848
  }
683
-
684
- const node: JourneyNode = {
685
- id,
686
- type: raw.kind,
687
- title,
688
- ...(subtitle ? { subtitle } : {}),
689
- ...(Object.keys(meta).length ? { meta } : {}),
690
- ...(raw.line ? { line: raw.line } : {}),
691
- };
692
- return { node, boundaryLabel };
693
849
  }
694
850
 
695
851
  /** Suffix `#2`, `#3`, … onto any duplicate emitted ids to keep them unique. */
@@ -711,7 +867,7 @@ function dedupeIds(nodes: JourneyNode[]): void {
711
867
  // Terminals
712
868
  // ---------------------------------------------------------------------------
713
869
 
714
- function startNode(meta: JourneyMeta): JourneyNode {
870
+ function startNode(meta: JourneyMeta): JourneyStartNode {
715
871
  return {
716
872
  id: "start",
717
873
  type: "start",
@@ -723,7 +879,7 @@ function startNode(meta: JourneyMeta): JourneyNode {
723
879
  };
724
880
  }
725
881
 
726
- function endNode(): JourneyNode {
882
+ function endNode(): JourneyEndNode {
727
883
  return { id: "end-completed", type: "end-completed", title: "Completed" };
728
884
  }
729
885
 
@@ -52,6 +52,14 @@ export interface JourneyBoundary {
52
52
  * footgun is a fail-fast dev error, never a silently-dropped message.
53
53
  */
54
54
  seenKeys: Set<string>;
55
+ /**
56
+ * Every `ctx.digest`/`ctx.throttle` SITE label seen so far in THIS run. Unlike
57
+ * {@link seenKeys} (auto-derived send/trigger keys), these are the authored
58
+ * site labels the primitives use to anchor their durable record. Reusing one
59
+ * label for two distinct sites would make them share a record and silently
60
+ * over-collapse, so {@link registerRecordLabel} throws loudly on a collision.
61
+ */
62
+ seenRecordLabels: Set<string>;
55
63
  /**
56
64
  * Layer-1 fast path: run `fn` through Hatchet's durable `memo` keyed by
57
65
  * `deps` when (and only when) the engine supports eviction; otherwise fall
@@ -60,6 +68,29 @@ export interface JourneyBoundary {
60
68
  * touched; when it isn't, Layer 2 still guarantees exactly-once.
61
69
  */
62
70
  memoize<T>(deps: unknown[], fn: () => Promise<T> | T): Promise<T>;
71
+ /**
72
+ * The enclosing journey's id (`meta.id`), threaded onto the boundary so the
73
+ * tracked mailer can enforce `meta.suppress` at send time WITHOUT the send
74
+ * call sites having to pass it. Optional so non-journey boundaries (tests,
75
+ * harness contexts) compile unchanged. Undefined ⇒ the suppress guard is inert.
76
+ */
77
+ journeyId?: string;
78
+ /**
79
+ * The enclosing journey's `meta.suppress` resolved to milliseconds
80
+ * (`durationToMs`). > 0 arms the tracked mailer's per-recipient min-gap
81
+ * suppress guard for this journey's sends; 0 (the `{}`/zero-duration default)
82
+ * disables it. Optional for the same reason as {@link journeyId}.
83
+ */
84
+ suppressMs?: number;
85
+ /**
86
+ * The enclosing journey's `meta.category` — the email-preference category
87
+ * stamped on this journey's `sendEmail` sends, overriding the template's own
88
+ * category (the standalone `sendEmail` has no journey reference of its own, so
89
+ * the boundary is the only conduit for it). Undefined ⇒ the send falls back to
90
+ * the built-in `journey` default. Optional so non-journey boundaries (tests,
91
+ * harness contexts) compile unchanged.
92
+ */
93
+ category?: string;
63
94
  }
64
95
 
65
96
  const journeyBoundaryAls = new AsyncLocalStorage<JourneyBoundary>();
@@ -203,3 +234,26 @@ export function registerKey(boundary: JourneyBoundary, key: string): void {
203
234
  }
204
235
  boundary.seenKeys.add(key);
205
236
  }
237
+
238
+ /**
239
+ * Record a `ctx.digest`/`ctx.throttle` SITE label as used in this run, throwing
240
+ * loudly if it collides with a label an earlier primitive call in the same run
241
+ * already used. Two sites sharing a label would share one durable record and
242
+ * silently over-collapse (a second digest folding into the first's window, a
243
+ * throttle verdict bleeding across sites), so we fail fast at dev time instead.
244
+ * No-op when `boundary` is undefined (a unit-test context outside a durable run).
245
+ */
246
+ export function registerRecordLabel(
247
+ boundary: JourneyBoundary | undefined,
248
+ label: string,
249
+ ): void {
250
+ if (!boundary) return;
251
+ if (boundary.seenRecordLabels.has(label)) {
252
+ throw new Error(
253
+ `journey replay-safety: the digest/throttle site label "${label}" was ` +
254
+ "used twice in one journey run. Each ctx.digest/ctx.throttle call needs " +
255
+ "a unique site — pass a distinct `label` to one of them.",
256
+ );
257
+ }
258
+ boundary.seenRecordLabels.add(label);
259
+ }