@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
|
@@ -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
|
-
|
|
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(
|
|
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
|
-
|
|
567
|
-
|
|
568
|
-
|
|
569
|
-
|
|
570
|
-
|
|
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
|
-
|
|
590
|
-
|
|
591
|
-
|
|
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
|
-
|
|
603
|
-
|
|
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
|
-
|
|
623
|
-
|
|
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
|
-
|
|
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
|
-
|
|
634
|
-
|
|
635
|
-
|
|
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
|
-
|
|
642
|
-
|
|
643
|
-
|
|
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
|
-
|
|
656
|
-
|
|
657
|
-
|
|
658
|
-
|
|
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
|
-
|
|
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
|
-
|
|
665
|
-
|
|
666
|
-
|
|
667
|
-
|
|
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
|
-
|
|
671
|
-
|
|
672
|
-
|
|
673
|
-
|
|
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
|
-
|
|
678
|
-
|
|
679
|
-
|
|
680
|
-
|
|
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):
|
|
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():
|
|
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
|
+
}
|