@hogsend/engine 0.46.1 → 0.51.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/README.md +6 -0
- package/package.json +13 -10
- package/src/campaigns/cohort-sql.ts +8 -9
- package/src/connectors/presets/index.ts +8 -2
- package/src/container.ts +150 -8
- package/src/destinations/define-destination.ts +2 -2
- package/src/destinations/presets/posthog.ts +7 -0
- package/src/destinations/presets/segment.ts +5 -0
- package/src/env.ts +38 -0
- package/src/flags/reconcile.ts +200 -0
- package/src/index.ts +79 -0
- package/src/journeys/authoring.ts +32 -0
- package/src/journeys/define-journey.ts +45 -40
- package/src/journeys/execute-journey-run.ts +73 -32
- package/src/journeys/journey-boundary.ts +76 -0
- package/src/journeys/journey-context.ts +128 -70
- package/src/journeys/journey-task-factory.ts +31 -0
- package/src/journeys/journey-task-runtime.ts +31 -0
- package/src/journeys/journey-version.test.ts +236 -0
- package/src/journeys/journey-version.ts +158 -0
- package/src/journeys/record-once.ts +28 -2
- package/src/lib/campaign-send-key.ts +9 -18
- package/src/lib/connector-actions.test.ts +36 -0
- package/src/lib/connector-actions.ts +42 -4
- package/src/lib/contacts.ts +49 -0
- package/src/lib/conversions.test.ts +33 -0
- package/src/lib/conversions.ts +9 -1
- package/src/lib/crm-deals.ts +1 -1
- package/src/lib/crm-ingest.ts +1 -1
- package/src/lib/email.ts +23 -2
- package/src/lib/enrollment-policy.ts +51 -0
- package/src/lib/event-names.ts +7 -1
- package/src/lib/feed.ts +55 -3
- package/src/lib/flags-registry.ts +48 -0
- package/src/lib/flags.ts +498 -0
- package/src/lib/frequency-cap.ts +4 -2
- package/src/lib/funnel-progress.ts +1 -1
- package/src/lib/fx.ts +374 -0
- package/src/lib/global-control-readout.ts +166 -0
- package/src/lib/groups.ts +362 -0
- package/src/lib/holdout.ts +1 -1
- package/src/lib/ingestion.ts +38 -0
- package/src/lib/journey-lift.ts +142 -0
- package/src/lib/journey-suppress.ts +4 -2
- package/src/lib/lift-stats.ts +2 -2
- package/src/lib/operator-settings.ts +71 -0
- package/src/lib/outbound.ts +147 -0
- package/src/lib/preferences.ts +6 -80
- package/src/lib/recipient-preferences.ts +53 -0
- package/src/lib/sms.ts +21 -2
- package/src/lib/stable-stringify.test.ts +42 -0
- package/src/lib/stable-stringify.ts +23 -0
- package/src/lib/tracked.ts +9 -2
- package/src/lib/variant.ts +99 -0
- package/src/lib/webhook-signing.ts +16 -1
- package/src/lists/registry.ts +6 -2
- package/src/lists/subscription.ts +13 -0
- package/src/routes/admin/attribution.ts +1 -2
- package/src/routes/admin/campaigns.ts +84 -45
- package/src/routes/admin/contacts.ts +53 -4
- package/src/routes/admin/conversions.ts +138 -1
- package/src/routes/admin/deals.ts +43 -34
- package/src/routes/admin/emails.ts +4 -6
- package/src/routes/admin/events.ts +128 -1
- package/src/routes/admin/flags.ts +369 -0
- package/src/routes/admin/groups.ts +900 -0
- package/src/routes/admin/impact-schemas.ts +44 -0
- package/src/routes/admin/impact-wire.test.ts +181 -0
- package/src/routes/admin/impact.ts +486 -0
- package/src/routes/admin/index.ts +12 -0
- package/src/routes/admin/journey-impact.ts +446 -0
- package/src/routes/admin/journeys.ts +70 -100
- package/src/routes/admin/settings.ts +145 -0
- package/src/routes/admin/targeting.ts +259 -0
- package/src/routes/events/index.ts +11 -0
- package/src/routes/flags/index.ts +120 -0
- package/src/routes/groups/index.ts +417 -0
- package/src/routes/index.ts +23 -1
- package/src/testing.ts +25 -0
- package/src/webhook-sources/presets/index.ts +5 -1
- package/src/webhook-sources/presets/intercom.ts +230 -0
- package/src/webhook-sources/presets/segment.ts +56 -4
- package/src/worker.ts +3 -0
- package/src/workflows/bucket-backfill.ts +1 -14
- package/src/workflows/crm-reconcile.ts +1 -1
- package/src/workflows/impact-digest.ts +761 -0
- package/src/workflows/journey-blueprint-interpreter.ts +18 -1
- package/src/middleware/auth.ts +0 -24
|
@@ -0,0 +1,236 @@
|
|
|
1
|
+
import assert from "node:assert/strict";
|
|
2
|
+
import test from "node:test";
|
|
3
|
+
import type { JourneyMeta, JourneyMetaInput } from "@hogsend/core/types";
|
|
4
|
+
import { stableStringify } from "../lib/stable-stringify.js";
|
|
5
|
+
import { defineJourney } from "./define-journey.js";
|
|
6
|
+
import {
|
|
7
|
+
computeJourneyVersionHash,
|
|
8
|
+
normalizeRunSource,
|
|
9
|
+
} from "./journey-version.js";
|
|
10
|
+
|
|
11
|
+
const GOLDEN_META: JourneyMeta = {
|
|
12
|
+
id: "golden-journey",
|
|
13
|
+
name: "Golden Journey",
|
|
14
|
+
enabled: true,
|
|
15
|
+
trigger: { event: "user.created" },
|
|
16
|
+
entryLimit: "once",
|
|
17
|
+
suppress: { hours: 24 },
|
|
18
|
+
};
|
|
19
|
+
|
|
20
|
+
const GOLDEN_BODY =
|
|
21
|
+
'async (user, ctx) => {\n // welcome\n await sendEmail({ to: user.email, template: "welcome" });\n}';
|
|
22
|
+
|
|
23
|
+
test("golden values — frozen compatibility contract (hsv1)", () => {
|
|
24
|
+
// Changing normalizeRunSource, stableStringify, the meta exclusion list,
|
|
25
|
+
// or HASH_INPUT_VERSION forks every live cohort exactly once. These
|
|
26
|
+
// literals are the lock: a failing golden means you are knowingly
|
|
27
|
+
// reforking and must bump HASH_INPUT_VERSION instead.
|
|
28
|
+
assert.equal(
|
|
29
|
+
computeJourneyVersionHash({ meta: GOLDEN_META, body: GOLDEN_BODY }),
|
|
30
|
+
"8996a5ccc0e7",
|
|
31
|
+
);
|
|
32
|
+
assert.equal(
|
|
33
|
+
computeJourneyVersionHash({ meta: GOLDEN_META }),
|
|
34
|
+
"8823399b83eb",
|
|
35
|
+
);
|
|
36
|
+
});
|
|
37
|
+
|
|
38
|
+
test("12-hex determinism", () => {
|
|
39
|
+
const h1 = computeJourneyVersionHash({
|
|
40
|
+
meta: GOLDEN_META,
|
|
41
|
+
body: GOLDEN_BODY,
|
|
42
|
+
});
|
|
43
|
+
const h2 = computeJourneyVersionHash({
|
|
44
|
+
meta: GOLDEN_META,
|
|
45
|
+
body: GOLDEN_BODY,
|
|
46
|
+
});
|
|
47
|
+
assert.equal(h1, h2);
|
|
48
|
+
assert.match(h1, /^[0-9a-f]{12}$/);
|
|
49
|
+
});
|
|
50
|
+
|
|
51
|
+
test("whitespace- and comment-only edits do not fork the hash", () => {
|
|
52
|
+
const a = "async (user) => { /* v1 */ await go(user); }";
|
|
53
|
+
const b = "async (user) => {\n // v2 comment\n await go(user);\n}";
|
|
54
|
+
assert.equal(normalizeRunSource(a), "async (user) => { await go(user); }");
|
|
55
|
+
assert.equal(normalizeRunSource(a), normalizeRunSource(b));
|
|
56
|
+
assert.equal(
|
|
57
|
+
computeJourneyVersionHash({ meta: GOLDEN_META, body: a }),
|
|
58
|
+
computeJourneyVersionHash({ meta: GOLDEN_META, body: b }),
|
|
59
|
+
);
|
|
60
|
+
});
|
|
61
|
+
|
|
62
|
+
test("// inside string literals is NOT stripped", () => {
|
|
63
|
+
assert.equal(
|
|
64
|
+
normalizeRunSource('const u = "https://x.dev//a"; // trailing'),
|
|
65
|
+
'const u = "https://x.dev//a";',
|
|
66
|
+
);
|
|
67
|
+
const withEscapes = 'const s = "a\\"//b"; return s;';
|
|
68
|
+
assert.equal(normalizeRunSource(withEscapes), withEscapes);
|
|
69
|
+
});
|
|
70
|
+
|
|
71
|
+
test("hash forks on every behavior-bearing meta field and on the body", () => {
|
|
72
|
+
const h = (meta: JourneyMeta, body?: string) =>
|
|
73
|
+
computeJourneyVersionHash({ meta, body });
|
|
74
|
+
const H0 = h(GOLDEN_META, GOLDEN_BODY);
|
|
75
|
+
const forks: JourneyMeta[] = [
|
|
76
|
+
{ ...GOLDEN_META, trigger: { event: "user.signup" } },
|
|
77
|
+
{
|
|
78
|
+
...GOLDEN_META,
|
|
79
|
+
trigger: {
|
|
80
|
+
event: "user.created",
|
|
81
|
+
where: [
|
|
82
|
+
{ type: "property", property: "plan", operator: "eq", value: "pro" },
|
|
83
|
+
],
|
|
84
|
+
},
|
|
85
|
+
},
|
|
86
|
+
{ ...GOLDEN_META, entryLimit: "unlimited" },
|
|
87
|
+
{ ...GOLDEN_META, exitOn: [{ event: "user.churned" }] },
|
|
88
|
+
{ ...GOLDEN_META, suppress: { hours: 48 } },
|
|
89
|
+
{ ...GOLDEN_META, holdout: { percent: 10 } },
|
|
90
|
+
{ ...GOLDEN_META, category: "onboarding" },
|
|
91
|
+
{ ...GOLDEN_META, goal: "revenue" },
|
|
92
|
+
];
|
|
93
|
+
for (const meta of forks) {
|
|
94
|
+
assert.notEqual(h(meta, GOLDEN_BODY), H0);
|
|
95
|
+
}
|
|
96
|
+
assert.notEqual(h(GOLDEN_META, "async () => { await other(); }"), H0);
|
|
97
|
+
});
|
|
98
|
+
|
|
99
|
+
test("display/toggle fields never fork: enabled, name, description, version label", () => {
|
|
100
|
+
const H0 = computeJourneyVersionHash({
|
|
101
|
+
meta: GOLDEN_META,
|
|
102
|
+
body: GOLDEN_BODY,
|
|
103
|
+
});
|
|
104
|
+
const same: JourneyMeta[] = [
|
|
105
|
+
{ ...GOLDEN_META, enabled: false },
|
|
106
|
+
{ ...GOLDEN_META, name: "Renamed" },
|
|
107
|
+
{ ...GOLDEN_META, description: "New copy" },
|
|
108
|
+
{ ...GOLDEN_META, version: "v2-label-only" },
|
|
109
|
+
{ ...GOLDEN_META, versionHash: "aaaaaaaaaaaa" },
|
|
110
|
+
];
|
|
111
|
+
for (const meta of same) {
|
|
112
|
+
assert.equal(computeJourneyVersionHash({ meta, body: GOLDEN_BODY }), H0);
|
|
113
|
+
}
|
|
114
|
+
});
|
|
115
|
+
|
|
116
|
+
test("meta key order never forks the hash", () => {
|
|
117
|
+
const reordered = {
|
|
118
|
+
suppress: { hours: 24 },
|
|
119
|
+
entryLimit: "once",
|
|
120
|
+
trigger: { event: "user.created" },
|
|
121
|
+
enabled: true,
|
|
122
|
+
name: "Golden Journey",
|
|
123
|
+
id: "golden-journey",
|
|
124
|
+
} as JourneyMeta;
|
|
125
|
+
assert.equal(
|
|
126
|
+
computeJourneyVersionHash({ meta: reordered, body: GOLDEN_BODY }),
|
|
127
|
+
computeJourneyVersionHash({ meta: GOLDEN_META, body: GOLDEN_BODY }),
|
|
128
|
+
);
|
|
129
|
+
});
|
|
130
|
+
|
|
131
|
+
test("normalizeRunSource never throws and stays deterministic on pathological input", () => {
|
|
132
|
+
// Known limits (spec D1): a // inside a regex literal is misread as a
|
|
133
|
+
// comment start; the scanner exits `template` state at the first
|
|
134
|
+
// backtick, so nested templates / strings / comments inside ${...} are
|
|
135
|
+
// misclassified. In every case the output is a PURE function of the
|
|
136
|
+
// input — determinism is what these assertions lock.
|
|
137
|
+
const cases = [
|
|
138
|
+
'const s = "unterminated',
|
|
139
|
+
"/* never closed",
|
|
140
|
+
"const t = `a${`b`}c`;",
|
|
141
|
+
'const t = `x${ /* c */ "y" }z`;',
|
|
142
|
+
"const re = /a//; more();",
|
|
143
|
+
"",
|
|
144
|
+
];
|
|
145
|
+
for (const input of cases) {
|
|
146
|
+
const once = normalizeRunSource(input);
|
|
147
|
+
assert.equal(normalizeRunSource(input), once);
|
|
148
|
+
assert.equal(typeof once, "string");
|
|
149
|
+
}
|
|
150
|
+
assert.equal(normalizeRunSource(""), "");
|
|
151
|
+
});
|
|
152
|
+
|
|
153
|
+
test("blueprint graph bodies (URLs, escaped quotes) hash stably", () => {
|
|
154
|
+
const graph = {
|
|
155
|
+
journeyId: "bp-golden",
|
|
156
|
+
nodes: [
|
|
157
|
+
{
|
|
158
|
+
id: "start",
|
|
159
|
+
type: "start",
|
|
160
|
+
title: "start",
|
|
161
|
+
meta: { url: "https://example.com/a//b", note: 'she said "hi"' },
|
|
162
|
+
},
|
|
163
|
+
],
|
|
164
|
+
edges: [],
|
|
165
|
+
};
|
|
166
|
+
const body = stableStringify(graph);
|
|
167
|
+
// The string-aware scanner protects // inside double-quoted JSON string
|
|
168
|
+
// values, including \" escapes.
|
|
169
|
+
assert.ok(normalizeRunSource(body).includes("https://example.com/a//b"));
|
|
170
|
+
const meta: JourneyMeta = {
|
|
171
|
+
id: "bp-golden",
|
|
172
|
+
name: "Blueprint bp-golden",
|
|
173
|
+
enabled: true,
|
|
174
|
+
trigger: { event: "bp.enroll" },
|
|
175
|
+
entryLimit: "unlimited",
|
|
176
|
+
suppress: {},
|
|
177
|
+
};
|
|
178
|
+
const h1 = computeJourneyVersionHash({ meta, body });
|
|
179
|
+
// jsonb round-trip key reordering cannot fork: stableStringify sorts.
|
|
180
|
+
const reorderedGraph = {
|
|
181
|
+
edges: [],
|
|
182
|
+
nodes: [
|
|
183
|
+
{
|
|
184
|
+
meta: { note: 'she said "hi"', url: "https://example.com/a//b" },
|
|
185
|
+
title: "start",
|
|
186
|
+
type: "start",
|
|
187
|
+
id: "start",
|
|
188
|
+
},
|
|
189
|
+
],
|
|
190
|
+
journeyId: "bp-golden",
|
|
191
|
+
};
|
|
192
|
+
assert.equal(
|
|
193
|
+
computeJourneyVersionHash({ meta, body: stableStringify(reorderedGraph) }),
|
|
194
|
+
h1,
|
|
195
|
+
);
|
|
196
|
+
assert.equal(h1, "858e91668b94");
|
|
197
|
+
});
|
|
198
|
+
|
|
199
|
+
test("defineJourney attaches the content hash and overwrites any authored value", () => {
|
|
200
|
+
const base: JourneyMetaInput = {
|
|
201
|
+
id: "jv-attach",
|
|
202
|
+
name: "Attach",
|
|
203
|
+
enabled: true,
|
|
204
|
+
trigger: { event: "jv.test" },
|
|
205
|
+
entryLimit: "once",
|
|
206
|
+
suppress: {},
|
|
207
|
+
version: "v1",
|
|
208
|
+
};
|
|
209
|
+
const run = async () => {};
|
|
210
|
+
const j1 = defineJourney({ meta: base, run });
|
|
211
|
+
assert.match(j1.meta.versionHash ?? "", /^[0-9a-f]{12}$/);
|
|
212
|
+
// Self-consistent: recomputing over the attached meta + captured source
|
|
213
|
+
// reproduces the hash (versionHash and version are excluded inputs).
|
|
214
|
+
assert.equal(
|
|
215
|
+
computeJourneyVersionHash({ meta: j1.meta, body: j1.runSource }),
|
|
216
|
+
j1.meta.versionHash,
|
|
217
|
+
);
|
|
218
|
+
// Label-only change: same content hash, new label.
|
|
219
|
+
const j2 = defineJourney({ meta: { ...base, version: "v2" }, run });
|
|
220
|
+
assert.equal(j2.meta.versionHash, j1.meta.versionHash);
|
|
221
|
+
assert.equal(j2.meta.version, "v2");
|
|
222
|
+
// An authored versionHash (JS caller — the type omits it) is overwritten.
|
|
223
|
+
const j3 = defineJourney({
|
|
224
|
+
meta: { ...base, versionHash: "aaaaaaaaaaaa" } as JourneyMetaInput,
|
|
225
|
+
run,
|
|
226
|
+
});
|
|
227
|
+
assert.equal(j3.meta.versionHash, j1.meta.versionHash);
|
|
228
|
+
// A body change forks.
|
|
229
|
+
const j4 = defineJourney({
|
|
230
|
+
meta: base,
|
|
231
|
+
run: async () => {
|
|
232
|
+
return;
|
|
233
|
+
},
|
|
234
|
+
});
|
|
235
|
+
assert.notEqual(j4.meta.versionHash, j1.meta.versionHash);
|
|
236
|
+
});
|
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
import { createHash } from "node:crypto";
|
|
2
|
+
import type { JourneyMeta } from "@hogsend/core/types";
|
|
3
|
+
import { stableStringify } from "../lib/stable-stringify.js";
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* Bump when normalization/hash-input rules change. Forks every hash exactly
|
|
7
|
+
* once on upgrade (a global, labeled refork — honest and self-documenting).
|
|
8
|
+
* FROZEN COMPATIBILITY CONTRACT (replay law) locked by the golden-value
|
|
9
|
+
* tests in journey-version.test.ts.
|
|
10
|
+
*/
|
|
11
|
+
const HASH_INPUT_VERSION = "hsv1";
|
|
12
|
+
|
|
13
|
+
type ScanState =
|
|
14
|
+
| "code"
|
|
15
|
+
| "single"
|
|
16
|
+
| "double"
|
|
17
|
+
| "template"
|
|
18
|
+
| "lineComment"
|
|
19
|
+
| "blockComment";
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* Deterministic, dependency-free normalization of a Function.prototype
|
|
23
|
+
* .toString() capture, so formatting- and comment-only edits do not fork a
|
|
24
|
+
* version cohort:
|
|
25
|
+
* 1. strip // line and block comments with a string-aware single-pass
|
|
26
|
+
* scanner (states: code | single | double | template | lineComment |
|
|
27
|
+
* blockComment; a \ inside any string state consumes the next char;
|
|
28
|
+
* each stripped comment is replaced by one space),
|
|
29
|
+
* 2. collapse every whitespace run to a single space, trim.
|
|
30
|
+
* KNOWN LIMITS (documented, deterministic): (a) a // inside a regex literal
|
|
31
|
+
* is misread as a comment start and mangles the rest of that line; (b) the
|
|
32
|
+
* scanner exits `template` state at the first backtick, so a nested
|
|
33
|
+
* template or a string/comment inside ${...} is misclassified. In both
|
|
34
|
+
* cases the output is still a pure function of the input, so the hash
|
|
35
|
+
* stays stable — the only cost is fork-detection fidelity on those lines.
|
|
36
|
+
* Never throws; empty input → "".
|
|
37
|
+
*/
|
|
38
|
+
export function normalizeRunSource(source: string): string {
|
|
39
|
+
let out = "";
|
|
40
|
+
let state: ScanState = "code";
|
|
41
|
+
for (let i = 0; i < source.length; i++) {
|
|
42
|
+
const ch = source[i] as string;
|
|
43
|
+
const next = source[i + 1];
|
|
44
|
+
switch (state) {
|
|
45
|
+
case "code":
|
|
46
|
+
if (ch === "/" && next === "/") {
|
|
47
|
+
state = "lineComment";
|
|
48
|
+
i++;
|
|
49
|
+
} else if (ch === "/" && next === "*") {
|
|
50
|
+
state = "blockComment";
|
|
51
|
+
i++;
|
|
52
|
+
} else {
|
|
53
|
+
out += ch;
|
|
54
|
+
if (ch === "'") state = "single";
|
|
55
|
+
else if (ch === '"') state = "double";
|
|
56
|
+
else if (ch === "`") state = "template";
|
|
57
|
+
}
|
|
58
|
+
break;
|
|
59
|
+
case "single":
|
|
60
|
+
case "double":
|
|
61
|
+
case "template":
|
|
62
|
+
out += ch;
|
|
63
|
+
if (ch === "\\") {
|
|
64
|
+
if (next !== undefined) {
|
|
65
|
+
out += next;
|
|
66
|
+
i++;
|
|
67
|
+
}
|
|
68
|
+
} else if (
|
|
69
|
+
(state === "single" && ch === "'") ||
|
|
70
|
+
(state === "double" && ch === '"') ||
|
|
71
|
+
(state === "template" && ch === "`")
|
|
72
|
+
) {
|
|
73
|
+
state = "code";
|
|
74
|
+
}
|
|
75
|
+
break;
|
|
76
|
+
case "lineComment":
|
|
77
|
+
if (ch === "\n") {
|
|
78
|
+
out += " ";
|
|
79
|
+
state = "code";
|
|
80
|
+
}
|
|
81
|
+
break;
|
|
82
|
+
case "blockComment":
|
|
83
|
+
if (ch === "*" && next === "/") {
|
|
84
|
+
out += " ";
|
|
85
|
+
state = "code";
|
|
86
|
+
i++;
|
|
87
|
+
}
|
|
88
|
+
break;
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
return out.replace(/\s+/g, " ").trim();
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/**
|
|
95
|
+
* Content fingerprint of one journey version: sha256, first 12 hex chars
|
|
96
|
+
* (48 bits — per-journey version counts are tiny; collision negligible).
|
|
97
|
+
* Input = HASH_INPUT_VERSION + "\n" + normalizeRunSource(body ?? "") +
|
|
98
|
+
* "\n" + stableStringify(hashable meta).
|
|
99
|
+
*
|
|
100
|
+
* Hashable meta = the meta MINUS `enabled` (toggling — including the
|
|
101
|
+
* journey_configs admin override — is not a content change), `version`
|
|
102
|
+
* (display label), `versionHash` (self), `name`, `description` (display
|
|
103
|
+
* only — display fields don't fork cohorts; this exclusion list is FROZEN
|
|
104
|
+
* at first release, since changing it later reforks every journey once).
|
|
105
|
+
* Everything else is included BY DEFAULT via rest-destructuring — id,
|
|
106
|
+
* trigger, entryLimit, entryPeriod, exitOn, category, suppress, holdout,
|
|
107
|
+
* goal, sourceBucketId, reactionKind, dwellSchedule, and any FUTURE meta
|
|
108
|
+
* field — because missing a real behavior change is worse than a spurious
|
|
109
|
+
* fork.
|
|
110
|
+
*
|
|
111
|
+
* For blueprints, `body` is stableStringify(row.graph), which ALSO passes
|
|
112
|
+
* through normalizeRunSource. Safe: stableStringify emits no whitespace or
|
|
113
|
+
* comments outside JSON strings, and // inside double-quoted string values
|
|
114
|
+
* (URLs in graph node config) is protected by the string-aware scanner,
|
|
115
|
+
* including \" escapes.
|
|
116
|
+
*
|
|
117
|
+
* ACCEPTED HASH CHURN ACROSS BUILD MODES: runSource is captured from the
|
|
118
|
+
* RUNNING artifact (define-journey.ts) — tsx dev output differs from the
|
|
119
|
+
* consumer tsup bundle, and esbuild identifier aliasing / toolchain-bump
|
|
120
|
+
* emit drift can fork a prod cohort once with zero content change.
|
|
121
|
+
* Accepted: forks are append-only cohort noise; labels give continuity.
|
|
122
|
+
* All readout/digest consumers MUST treat a new hash as "possible new
|
|
123
|
+
* version", never proof of change.
|
|
124
|
+
*
|
|
125
|
+
* TEMPLATE EDITS ARE NOT IN THE HASH: email template components (the
|
|
126
|
+
* consumer's src/emails/*.tsx) are referenced by registry KEY, and that
|
|
127
|
+
* key is all the run source carries — rewriting template copy forks NO
|
|
128
|
+
* cohort. Documented operator practice: bump `meta.version` (the display
|
|
129
|
+
* label) when you rework a template; the impact digest reports a label
|
|
130
|
+
* change as a first-class shipped signal (change: "new_label"). The real
|
|
131
|
+
* fix — folding a rendered-template-registry hash into the body input —
|
|
132
|
+
* is an explicit out-of-scope follow-up.
|
|
133
|
+
*
|
|
134
|
+
* Determinism: `where` builder fns are resolved ONCE into POJOs by
|
|
135
|
+
* normalizeWhere at defineJourney time, so the hashed meta is canonical
|
|
136
|
+
* data, never a function; stableStringify sorts keys and drops undefined,
|
|
137
|
+
* so key order and optional-field spreading cannot churn the hash. NO RNG,
|
|
138
|
+
* NO clock (the replay law).
|
|
139
|
+
*/
|
|
140
|
+
export function computeJourneyVersionHash(opts: {
|
|
141
|
+
meta: JourneyMeta;
|
|
142
|
+
/** runSource for code journeys; stableStringify(graph) for blueprints. */
|
|
143
|
+
body?: string;
|
|
144
|
+
}): string {
|
|
145
|
+
const {
|
|
146
|
+
enabled: _e,
|
|
147
|
+
version: _v,
|
|
148
|
+
versionHash: _h,
|
|
149
|
+
name: _n,
|
|
150
|
+
description: _d,
|
|
151
|
+
...hashable
|
|
152
|
+
} = opts.meta;
|
|
153
|
+
const body = opts.body ? normalizeRunSource(opts.body) : "";
|
|
154
|
+
return createHash("sha256")
|
|
155
|
+
.update(`${HASH_INPUT_VERSION}\n${body}\n${stableStringify(hashable)}`)
|
|
156
|
+
.digest("hex")
|
|
157
|
+
.slice(0, 12);
|
|
158
|
+
}
|
|
@@ -5,15 +5,20 @@ import { eq, sql } from "drizzle-orm";
|
|
|
5
5
|
* under. A closed union — the ONLY values reachable at the SQL path, so the
|
|
6
6
|
* token can be interpolated into the jsonb path (see {@link recordOnce}) while
|
|
7
7
|
* `key`/value stay bound parameters. */
|
|
8
|
-
export type RecordNamespace =
|
|
8
|
+
export type RecordNamespace =
|
|
9
|
+
| "__once__"
|
|
10
|
+
| "__digest__"
|
|
11
|
+
| "__throttle__"
|
|
12
|
+
| "__variants__";
|
|
9
13
|
|
|
10
|
-
// Closed-union → validated path token. NOT user input: only these
|
|
14
|
+
// Closed-union → validated path token. NOT user input: only these four literals
|
|
11
15
|
// reach the interpolated jsonb path below, so it is injection-safe. `key` and the
|
|
12
16
|
// JSON-stringified value are ALWAYS bound parameters regardless.
|
|
13
17
|
const NAMESPACE_TOKEN: Record<RecordNamespace, string> = {
|
|
14
18
|
__once__: "__once__",
|
|
15
19
|
__digest__: "__digest__",
|
|
16
20
|
__throttle__: "__throttle__",
|
|
21
|
+
__variants__: "__variants__",
|
|
17
22
|
};
|
|
18
23
|
|
|
19
24
|
/** Extract the `(namespace)` sub-bag from an already-fetched context, `{}` when
|
|
@@ -108,3 +113,24 @@ export async function recordOnce<T>(opts: {
|
|
|
108
113
|
}
|
|
109
114
|
return value;
|
|
110
115
|
}
|
|
116
|
+
|
|
117
|
+
/**
|
|
118
|
+
* Drop ALL reserved record-once namespace keys from an event-properties bag.
|
|
119
|
+
* Enrollment seeds `journey_states.context` from trigger-event properties
|
|
120
|
+
* (execute-journey-run.ts — BOTH the fresh-entry and held_out inserts);
|
|
121
|
+
* without this strip a publishable-key browser event carrying e.g.
|
|
122
|
+
* `__variants__` could pre-fill a reserved bag — choosing its own ctx.variant
|
|
123
|
+
* arm AND injecting arbitrary strings into the impact readout's GROUP BY
|
|
124
|
+
* dimension. One filter protects every bag at once. Engine-supplied
|
|
125
|
+
* `extraContext` (e.g. `__blueprintVersion`) is deliberately NOT passed
|
|
126
|
+
* through this filter.
|
|
127
|
+
*/
|
|
128
|
+
export function stripRecordNamespaces<T>(
|
|
129
|
+
properties: Record<string, T>,
|
|
130
|
+
): Record<string, T> {
|
|
131
|
+
return Object.fromEntries(
|
|
132
|
+
Object.entries(properties).filter(
|
|
133
|
+
([key]) => !Object.hasOwn(NAMESPACE_TOKEN, key),
|
|
134
|
+
),
|
|
135
|
+
) as Record<string, T>;
|
|
136
|
+
}
|
|
@@ -1,16 +1,18 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* The deterministic per-recipient idempotency key a campaign send writes to
|
|
3
|
-
* `email_sends.idempotency_key`.
|
|
4
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
3
|
+
* `email_sends.idempotency_key`. The key exists for DEDUP; campaign
|
|
4
|
+
* attribution is the `email_sends.campaign_id` column (stamped on every
|
|
5
|
+
* campaign-dispatched row including suppressed sends, which write no key at
|
|
6
|
+
* all; legacy rows backfilled by migration 0051). The one thing the key
|
|
7
|
+
* still uniquely carries is the STEP NUMBER of a multi-step campaign, which
|
|
8
|
+
* is why the per-step stats breakdown matches `campaignStepSendKeyPattern`
|
|
9
|
+
* (scoped to the campaign_id FK first).
|
|
8
10
|
*
|
|
9
11
|
* Two formats, chosen by the campaign's step count (NOT per call site):
|
|
10
12
|
*
|
|
11
13
|
* - Single-step campaigns (steps.length === 1 or a NULL steps blob) ALWAYS
|
|
12
|
-
* use the legacy `campaign:<id>:<email>` — behavior
|
|
13
|
-
*
|
|
14
|
+
* use the legacy `campaign:<id>:<email>` — behavior and any in-flight
|
|
15
|
+
* campaign at deploy time are byte-for-byte unchanged.
|
|
14
16
|
* - Multi-step campaigns use `campaign:<id>:<step>:<email>` for ALL steps
|
|
15
17
|
* including 0. No ambiguity with the legacy format is possible (no
|
|
16
18
|
* multi-step campaign exists before this ships), and per-step stats
|
|
@@ -34,17 +36,6 @@ function escapeLike(value: string): string {
|
|
|
34
36
|
return value.replace(/([\\%_])/g, "\\$1");
|
|
35
37
|
}
|
|
36
38
|
|
|
37
|
-
/**
|
|
38
|
-
* SQL LIKE pattern matching every send of one campaign — a correct superset
|
|
39
|
-
* of BOTH key formats (legacy and step-scoped), so campaign-level stats need
|
|
40
|
-
* no format awareness. The id is escaped so LIKE metacharacters in it can't
|
|
41
|
-
* widen the match (ids are UUIDs today, but the route accepts arbitrary
|
|
42
|
-
* strings).
|
|
43
|
-
*/
|
|
44
|
-
export function campaignSendKeyPattern(campaignId: string): string {
|
|
45
|
-
return `campaign:${escapeLike(campaignId)}:%`;
|
|
46
|
-
}
|
|
47
|
-
|
|
48
39
|
/**
|
|
49
40
|
* SQL LIKE pattern matching every send of ONE step of a multi-step campaign
|
|
50
41
|
* (`campaign:<id>:<step>:%`). Meaningless against legacy single-step keys —
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
import assert from "node:assert/strict";
|
|
2
|
+
import test from "node:test";
|
|
3
|
+
import {
|
|
4
|
+
type JourneyBoundary,
|
|
5
|
+
runWithJourneyBoundary,
|
|
6
|
+
} from "../journeys/journey-boundary.js";
|
|
7
|
+
import { sendConnectorAction } from "./connector-actions.js";
|
|
8
|
+
|
|
9
|
+
test("a scoped connector override requires registration validation before capture", async () => {
|
|
10
|
+
let captures = 0;
|
|
11
|
+
const boundary: JourneyBoundary = {
|
|
12
|
+
stateId: "test-state",
|
|
13
|
+
runAnchor: "test-run",
|
|
14
|
+
currentLabel: undefined,
|
|
15
|
+
seenKeys: new Set(),
|
|
16
|
+
seenRecordLabels: new Set(),
|
|
17
|
+
memoize: async (_deps, fn) => fn(),
|
|
18
|
+
services: {
|
|
19
|
+
connector: async () => {
|
|
20
|
+
captures += 1;
|
|
21
|
+
return { delivered: true };
|
|
22
|
+
},
|
|
23
|
+
},
|
|
24
|
+
};
|
|
25
|
+
|
|
26
|
+
await assert.rejects(
|
|
27
|
+
runWithJourneyBoundary(boundary, () =>
|
|
28
|
+
sendConnectorAction({
|
|
29
|
+
connectorId: "discord",
|
|
30
|
+
action: "unregistered",
|
|
31
|
+
}),
|
|
32
|
+
),
|
|
33
|
+
/requires connectorActionExists/,
|
|
34
|
+
);
|
|
35
|
+
assert.equal(captures, 0);
|
|
36
|
+
});
|
|
@@ -6,7 +6,6 @@ import type {
|
|
|
6
6
|
DefinedConnectorAction,
|
|
7
7
|
ResolvedActionContact,
|
|
8
8
|
} from "../connectors/define-action.js";
|
|
9
|
-
import { env } from "../env.js";
|
|
10
9
|
import {
|
|
11
10
|
deriveJourneyKey,
|
|
12
11
|
getJourneyBoundary,
|
|
@@ -15,9 +14,13 @@ import {
|
|
|
15
14
|
import { getListRegistry } from "../lists/registry-singleton.js";
|
|
16
15
|
import { getDb } from "./db.js";
|
|
17
16
|
import { createLogger } from "./logger.js";
|
|
18
|
-
import { readRecipientPreferences } from "./preferences.js";
|
|
17
|
+
import { readRecipientPreferences } from "./recipient-preferences.js";
|
|
19
18
|
|
|
20
|
-
|
|
19
|
+
// This module is part of the side-effect-free journey-authoring surface used by
|
|
20
|
+
// `@hogsend/testing`. Reading the raw optional value keeps importing a journey
|
|
21
|
+
// from validating the complete production environment; the full container still
|
|
22
|
+
// validates env at boot.
|
|
23
|
+
const logger = createLogger(process.env.LOG_LEVEL);
|
|
21
24
|
|
|
22
25
|
/**
|
|
23
26
|
* Matches the canonical UUID form of `contacts.id` (8-4-4-4-12 hex). Gates the
|
|
@@ -240,6 +243,42 @@ export interface SendConnectorActionArgs {
|
|
|
240
243
|
export async function sendConnectorAction(
|
|
241
244
|
input: SendConnectorActionArgs,
|
|
242
245
|
): Promise<unknown> {
|
|
246
|
+
const boundary = getJourneyBoundary();
|
|
247
|
+
const override = boundary?.services?.connector;
|
|
248
|
+
if (boundary && override) {
|
|
249
|
+
const actionExists = boundary.services?.connectorActionExists;
|
|
250
|
+
if (!actionExists) {
|
|
251
|
+
throw new Error(
|
|
252
|
+
"Scoped connector override requires connectorActionExists validation",
|
|
253
|
+
);
|
|
254
|
+
}
|
|
255
|
+
if (!actionExists(input.connectorId, input.action)) {
|
|
256
|
+
throw new Error(
|
|
257
|
+
`no connector action "${input.connectorId}:${input.action}" is registered ` +
|
|
258
|
+
"(pass it via createJourneyTest({ connectorActions }))",
|
|
259
|
+
);
|
|
260
|
+
}
|
|
261
|
+
const site =
|
|
262
|
+
input.idempotencyLabel ??
|
|
263
|
+
boundary.currentLabel ??
|
|
264
|
+
`${input.connectorId}:${input.action}`;
|
|
265
|
+
const scopedKey = deriveJourneyKey({
|
|
266
|
+
kind: "connector",
|
|
267
|
+
anchor: boundary.runAnchor,
|
|
268
|
+
site,
|
|
269
|
+
discriminant: `${input.connectorId}:${input.action}`,
|
|
270
|
+
});
|
|
271
|
+
registerKey(boundary, scopedKey);
|
|
272
|
+
return boundary.memoize([scopedKey], () =>
|
|
273
|
+
override({
|
|
274
|
+
connectorId: input.connectorId,
|
|
275
|
+
action: input.action,
|
|
276
|
+
...(input.args !== undefined ? { args: input.args } : {}),
|
|
277
|
+
idempotencyKey: scopedKey,
|
|
278
|
+
}),
|
|
279
|
+
);
|
|
280
|
+
}
|
|
281
|
+
|
|
243
282
|
const action = getConnectorActionRegistry().get(
|
|
244
283
|
input.connectorId,
|
|
245
284
|
input.action,
|
|
@@ -300,7 +339,6 @@ export async function sendConnectorAction(
|
|
|
300
339
|
|
|
301
340
|
// Outside a journey run (an admin/manual send) there is no replay to defend
|
|
302
341
|
// against and no boundary to key from — gate then run the action directly.
|
|
303
|
-
const boundary = getJourneyBoundary();
|
|
304
342
|
if (!boundary) return gate(doRun);
|
|
305
343
|
|
|
306
344
|
// The replay-stable, branch-derived key shared by BOTH defense layers. `site`
|
package/src/lib/contacts.ts
CHANGED
|
@@ -7,6 +7,7 @@ import {
|
|
|
7
7
|
deals,
|
|
8
8
|
emailPreferences,
|
|
9
9
|
emailSends,
|
|
10
|
+
groupMemberships,
|
|
10
11
|
journeyStates,
|
|
11
12
|
userEvents,
|
|
12
13
|
} from "@hogsend/db";
|
|
@@ -963,6 +964,14 @@ async function mergeContacts(
|
|
|
963
964
|
.set({ contactId: survivor.id })
|
|
964
965
|
.where(eq(crmLinks.contactId, loser.id));
|
|
965
966
|
|
|
967
|
+
// (vi-c) group_memberships FOLD: another contact_id uuid FK the key
|
|
968
|
+
// rewrites never touch. The loser is SOFT-deleted, so `onDelete: cascade`
|
|
969
|
+
// never fires — without this the loser's memberships are stranded on a dead
|
|
970
|
+
// row (the survivor's drawer shows "no groups", and the group's member
|
|
971
|
+
// count/list disagree). uq(group_id, contact_id) forbids a blind rewrite
|
|
972
|
+
// when BOTH already belong to the same group, so fold-then-rewrite.
|
|
973
|
+
await foldGroupMemberships(tx, survivor.id, loser.id);
|
|
974
|
+
|
|
966
975
|
// (ix) RECORD aliases for each loser key → survivor.
|
|
967
976
|
await recordMergeAliases(tx, survivor.id, loser);
|
|
968
977
|
}
|
|
@@ -1279,6 +1288,46 @@ async function foldBucketMemberships(
|
|
|
1279
1288
|
.where(inArray(bucketMemberships.userId, loserKeys));
|
|
1280
1289
|
}
|
|
1281
1290
|
|
|
1291
|
+
/**
|
|
1292
|
+
* group_memberships fold (vi-c). Unlike buckets this join is keyed on the uuid
|
|
1293
|
+
* `contact_id`, and it carries no lifecycle (no status/dwell/left_at) — just
|
|
1294
|
+
* `role` + `joined_at` — so the fold is a plain dedupe-then-rewrite:
|
|
1295
|
+
* 1. DROP the loser's membership in any group the survivor ALREADY belongs to
|
|
1296
|
+
* (uq(group_id, contact_id) forbids two rows for the same (group, contact);
|
|
1297
|
+
* the survivor's row wins, keeping its authoritative role/joinedAt).
|
|
1298
|
+
* 2. Re-point the rest onto the survivor.
|
|
1299
|
+
* Hard-delete (not soft-leave) matches how a membership is removed everywhere
|
|
1300
|
+
* else in the group service.
|
|
1301
|
+
*/
|
|
1302
|
+
async function foldGroupMemberships(
|
|
1303
|
+
tx: Tx,
|
|
1304
|
+
survivorId: string,
|
|
1305
|
+
loserId: string,
|
|
1306
|
+
): Promise<void> {
|
|
1307
|
+
const survivorGroups = await tx
|
|
1308
|
+
.select({ groupId: groupMemberships.groupId })
|
|
1309
|
+
.from(groupMemberships)
|
|
1310
|
+
.where(eq(groupMemberships.contactId, survivorId));
|
|
1311
|
+
|
|
1312
|
+
const occupied = survivorGroups.map((g) => g.groupId);
|
|
1313
|
+
|
|
1314
|
+
if (occupied.length > 0) {
|
|
1315
|
+
await tx
|
|
1316
|
+
.delete(groupMemberships)
|
|
1317
|
+
.where(
|
|
1318
|
+
and(
|
|
1319
|
+
eq(groupMemberships.contactId, loserId),
|
|
1320
|
+
inArray(groupMemberships.groupId, occupied),
|
|
1321
|
+
),
|
|
1322
|
+
);
|
|
1323
|
+
}
|
|
1324
|
+
|
|
1325
|
+
await tx
|
|
1326
|
+
.update(groupMemberships)
|
|
1327
|
+
.set({ contactId: survivorId, updatedAt: new Date() })
|
|
1328
|
+
.where(eq(groupMemberships.contactId, loserId));
|
|
1329
|
+
}
|
|
1330
|
+
|
|
1282
1331
|
/**
|
|
1283
1332
|
* email_preferences FOLD (risk 6 — suppression/unsubscribe must NEVER be lost).
|
|
1284
1333
|
* For each of the loser's pref rows, fold it into whatever currently sits at
|