@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.
Files changed (88) hide show
  1. package/README.md +6 -0
  2. package/package.json +13 -10
  3. package/src/campaigns/cohort-sql.ts +8 -9
  4. package/src/connectors/presets/index.ts +8 -2
  5. package/src/container.ts +150 -8
  6. package/src/destinations/define-destination.ts +2 -2
  7. package/src/destinations/presets/posthog.ts +7 -0
  8. package/src/destinations/presets/segment.ts +5 -0
  9. package/src/env.ts +38 -0
  10. package/src/flags/reconcile.ts +200 -0
  11. package/src/index.ts +79 -0
  12. package/src/journeys/authoring.ts +32 -0
  13. package/src/journeys/define-journey.ts +45 -40
  14. package/src/journeys/execute-journey-run.ts +73 -32
  15. package/src/journeys/journey-boundary.ts +76 -0
  16. package/src/journeys/journey-context.ts +128 -70
  17. package/src/journeys/journey-task-factory.ts +31 -0
  18. package/src/journeys/journey-task-runtime.ts +31 -0
  19. package/src/journeys/journey-version.test.ts +236 -0
  20. package/src/journeys/journey-version.ts +158 -0
  21. package/src/journeys/record-once.ts +28 -2
  22. package/src/lib/campaign-send-key.ts +9 -18
  23. package/src/lib/connector-actions.test.ts +36 -0
  24. package/src/lib/connector-actions.ts +42 -4
  25. package/src/lib/contacts.ts +49 -0
  26. package/src/lib/conversions.test.ts +33 -0
  27. package/src/lib/conversions.ts +9 -1
  28. package/src/lib/crm-deals.ts +1 -1
  29. package/src/lib/crm-ingest.ts +1 -1
  30. package/src/lib/email.ts +23 -2
  31. package/src/lib/enrollment-policy.ts +51 -0
  32. package/src/lib/event-names.ts +7 -1
  33. package/src/lib/feed.ts +55 -3
  34. package/src/lib/flags-registry.ts +48 -0
  35. package/src/lib/flags.ts +498 -0
  36. package/src/lib/frequency-cap.ts +4 -2
  37. package/src/lib/funnel-progress.ts +1 -1
  38. package/src/lib/fx.ts +374 -0
  39. package/src/lib/global-control-readout.ts +166 -0
  40. package/src/lib/groups.ts +362 -0
  41. package/src/lib/holdout.ts +1 -1
  42. package/src/lib/ingestion.ts +38 -0
  43. package/src/lib/journey-lift.ts +142 -0
  44. package/src/lib/journey-suppress.ts +4 -2
  45. package/src/lib/lift-stats.ts +2 -2
  46. package/src/lib/operator-settings.ts +71 -0
  47. package/src/lib/outbound.ts +147 -0
  48. package/src/lib/preferences.ts +6 -80
  49. package/src/lib/recipient-preferences.ts +53 -0
  50. package/src/lib/sms.ts +21 -2
  51. package/src/lib/stable-stringify.test.ts +42 -0
  52. package/src/lib/stable-stringify.ts +23 -0
  53. package/src/lib/tracked.ts +9 -2
  54. package/src/lib/variant.ts +99 -0
  55. package/src/lib/webhook-signing.ts +16 -1
  56. package/src/lists/registry.ts +6 -2
  57. package/src/lists/subscription.ts +13 -0
  58. package/src/routes/admin/attribution.ts +1 -2
  59. package/src/routes/admin/campaigns.ts +84 -45
  60. package/src/routes/admin/contacts.ts +53 -4
  61. package/src/routes/admin/conversions.ts +138 -1
  62. package/src/routes/admin/deals.ts +43 -34
  63. package/src/routes/admin/emails.ts +4 -6
  64. package/src/routes/admin/events.ts +128 -1
  65. package/src/routes/admin/flags.ts +369 -0
  66. package/src/routes/admin/groups.ts +900 -0
  67. package/src/routes/admin/impact-schemas.ts +44 -0
  68. package/src/routes/admin/impact-wire.test.ts +181 -0
  69. package/src/routes/admin/impact.ts +486 -0
  70. package/src/routes/admin/index.ts +12 -0
  71. package/src/routes/admin/journey-impact.ts +446 -0
  72. package/src/routes/admin/journeys.ts +70 -100
  73. package/src/routes/admin/settings.ts +145 -0
  74. package/src/routes/admin/targeting.ts +259 -0
  75. package/src/routes/events/index.ts +11 -0
  76. package/src/routes/flags/index.ts +120 -0
  77. package/src/routes/groups/index.ts +417 -0
  78. package/src/routes/index.ts +23 -1
  79. package/src/testing.ts +25 -0
  80. package/src/webhook-sources/presets/index.ts +5 -1
  81. package/src/webhook-sources/presets/intercom.ts +230 -0
  82. package/src/webhook-sources/presets/segment.ts +56 -4
  83. package/src/worker.ts +3 -0
  84. package/src/workflows/bucket-backfill.ts +1 -14
  85. package/src/workflows/crm-reconcile.ts +1 -1
  86. package/src/workflows/impact-digest.ts +761 -0
  87. package/src/workflows/journey-blueprint-interpreter.ts +18 -1
  88. package/src/middleware/auth.ts +0 -24
@@ -57,6 +57,25 @@ interface BucketEventPayload {
57
57
  source: string;
58
58
  }
59
59
 
60
+ /**
61
+ * The serialized group shape carried on `group.identified` — mirrors
62
+ * {@link SerializedContact}: the internal columns (`organizationId`,
63
+ * `deletedAt`) are omitted and timestamps are ISO strings. Structurally
64
+ * identical to the `/v1/groups` route's `serializeGroup` output so the emit
65
+ * reuses that one serializer without a layering inversion (lib → routes).
66
+ */
67
+ export interface SerializedGroup {
68
+ id: string;
69
+ groupType: string;
70
+ groupKey: string;
71
+ displayName: string | null;
72
+ properties: Record<string, unknown> | null;
73
+ firstSeenAt: string;
74
+ lastSeenAt: string;
75
+ createdAt: string;
76
+ updatedAt: string;
77
+ }
78
+
60
79
  /**
61
80
  * The typed per-event payload map. `data` in each delivered envelope is exactly
62
81
  * `OutboundPayloads[E]` for the emitted event `E`. Producers (the 12 hook
@@ -237,6 +256,28 @@ export interface OutboundPayloads {
237
256
  userEmail: string;
238
257
  heldOutAt: string;
239
258
  };
259
+ /**
260
+ * Weekly impact digest (impact experiments D5) — facts-only rollup of
261
+ * shipped journey changes and holdout-lift threshold crossings, emitted
262
+ * by the engine-owned cron. Shipped entries are structurally
263
+ * observational (the type carries no lift fields); lift entries are
264
+ * holdout-backed causal. The ONE self-referential catalog event: the
265
+ * cron derives its watermark from its own delivery rows.
266
+ */
267
+ "impact.digest": {
268
+ /** UTC YYYY-MM-DD of the emit — also the dedupeKey day. */
269
+ periodKey: string;
270
+ /** ISO — watermark (last digest delivery, clamped to 30 days back). */
271
+ since: string;
272
+ /** ISO — this run's snapshot instant. */
273
+ until: string;
274
+ /**
275
+ * Lift first (desc |winProbability − 0.5|), then shipped (desc
276
+ * firstSeenAt); capped at 50.
277
+ */
278
+ entries: ImpactDigestEntry[];
279
+ truncated: boolean;
280
+ };
240
281
  "bucket.entered": BucketEventPayload;
241
282
  "bucket.left": BucketEventPayload & { reason?: string };
242
283
  /**
@@ -253,6 +294,34 @@ export interface OutboundPayloads {
253
294
  "deal.quoted": CrmDealEventPayload;
254
295
  /** A deal FIRST reached canonical `sold`. Value = deal value. */
255
296
  "deal.sold": CrmDealEventPayload;
297
+ /**
298
+ * A group was identified (upserted) via `POST /v1/groups` — the serialized
299
+ * group with its merged property bag. Fires on every successful identify
300
+ * (intent-layer only, never the pageview-driven ingest association path).
301
+ */
302
+ "group.identified": SerializedGroup;
303
+ /**
304
+ * A contact was added to a group via `POST /v1/groups/.../members` — emitted
305
+ * ONLY when THIS call inserted the membership (a re-add is a no-op).
306
+ */
307
+ "group.member_added": {
308
+ groupType: string;
309
+ groupKey: string;
310
+ groupId: string;
311
+ contactId: string;
312
+ role: string | null;
313
+ };
314
+ /**
315
+ * A contact was removed from a group via
316
+ * `DELETE /v1/groups/.../members/{contactId}` — emitted ONLY when THIS call
317
+ * actually deleted a membership row.
318
+ */
319
+ "group.member_removed": {
320
+ groupType: string;
321
+ groupKey: string;
322
+ groupId: string;
323
+ contactId: string;
324
+ };
256
325
  }
257
326
 
258
327
  /** Shared payload for the `crm.*` outbound family. */
@@ -273,6 +342,84 @@ export interface CrmDealEventPayload {
273
342
  at: string;
274
343
  }
275
344
 
345
+ /**
346
+ * One journey-version cohort inside an impact digest entry. Exposure-window
347
+ * metadata rides along because current vs previous cohorts have DIFFERENT
348
+ * exposure (a 3-day-old version vs a 60-day-old one is not a fair rate
349
+ * comparison) — subscribers MUST normalize or caveat against these.
350
+ */
351
+ export interface ImpactVersionCohort {
352
+ versionHash: string;
353
+ versionLabel: string | null;
354
+ /**
355
+ * All-time distinct treated users for this version — deliberately NOT
356
+ * windowed by `days` (named to say so; the /impact route's version rows
357
+ * ARE windowed).
358
+ */
359
+ enrollmentsAllTime: number;
360
+ converters: number;
361
+ /** converters / enrollmentsAllTime; 0 when the cohort is empty. */
362
+ conversionRate: number;
363
+ /** ISO min(created_at) of this hash's rows. */
364
+ firstSeenAt: string;
365
+ /** Whole days between firstSeenAt and the digest's `until`. */
366
+ exposureDays: number;
367
+ }
368
+
369
+ /**
370
+ * "You shipped a change" — OBSERVATIONAL by construction: the type carries
371
+ * no liftPercent/winProbability, so causal language is structurally
372
+ * impossible (the causal-language law, routes/admin/funnels.ts:16).
373
+ */
374
+ export interface ImpactDigestShippedEntry {
375
+ kind: "shipped";
376
+ causal: false;
377
+ journeyId: string;
378
+ /** null for blueprint/unregistered journeys. */
379
+ journeyName: string | null;
380
+ versionHash: string;
381
+ versionLabel: string | null;
382
+ change: "new_journey" | "new_version" | "new_label";
383
+ /** Set for new_label (the label that was current before the window). */
384
+ previousVersionLabel: string | null;
385
+ firstSeenAt: string;
386
+ goalDefinitionId: string | null;
387
+ current: ImpactVersionCohort;
388
+ /** null for new_journey / new_label. */
389
+ previous: ImpactVersionCohort | null;
390
+ }
391
+
392
+ /**
393
+ * "This is working / hurting" — a holdout-backed win-probability CROSSING
394
+ * (not level: no weekly re-nag). Suppressed verdicts never produce an
395
+ * entry, so winProbability is never null here; smallSample rides verbatim.
396
+ */
397
+ export interface ImpactDigestLiftEntry {
398
+ kind: "lift";
399
+ causal: true;
400
+ journeyId: string;
401
+ journeyName: string | null;
402
+ goalDefinitionId: string | null;
403
+ /** The lift window in days (90 — mirrors the lift route default). */
404
+ windowDays: number;
405
+ direction: "up" | "down";
406
+ treatment: { contacts: number; converters: number; rate: number };
407
+ control: { contacts: number; converters: number; rate: number };
408
+ liftPercent: number | null;
409
+ winProbability: number;
410
+ /**
411
+ * Last digest's as-REPORTED value when available (frozen-payload
412
+ * override), else the live recompute at the previous watermark; null
413
+ * when neither produced a probability.
414
+ */
415
+ previousWinProbability: number | null;
416
+ smallSample: boolean;
417
+ }
418
+
419
+ export type ImpactDigestEntry =
420
+ | ImpactDigestShippedEntry
421
+ | ImpactDigestLiftEntry;
422
+
276
423
  /**
277
424
  * The signed envelope shape written to `webhook_deliveries.payload` and sent
278
425
  * verbatim to subscribers. `id` is the shared `Webhook-Id`; `timestamp` is the
@@ -1,11 +1,16 @@
1
1
  import type { Database } from "@hogsend/db";
2
2
  import { emailPreferences } from "@hogsend/db";
3
- import { eq, or, sql } from "drizzle-orm";
3
+ import { sql } from "drizzle-orm";
4
4
  import { resolveRecipient } from "./contacts.js";
5
5
  import { hatchet } from "./hatchet.js";
6
6
  import { createLogger } from "./logger.js";
7
7
  import { emitOutbound } from "./outbound.js";
8
8
 
9
+ export {
10
+ type RecipientPreferences,
11
+ readRecipientPreferences,
12
+ } from "./recipient-preferences.js";
13
+
9
14
  const logger = createLogger(process.env.LOG_LEVEL);
10
15
 
11
16
  /**
@@ -153,85 +158,6 @@ export async function upsertEmailPreference(opts: {
153
158
  }
154
159
  }
155
160
 
156
- /**
157
- * Aggregated preference verdict for a recipient, folded across EVERY matching
158
- * `email_preferences` row. See {@link readRecipientPreferences}.
159
- */
160
- export interface RecipientPreferences {
161
- /** true when ANY matching row has unsubscribed_all (global master opt-out). */
162
- unsubscribedAll: boolean;
163
- /**
164
- * true when ANY matching row is suppressed (hard bounce / complaint).
165
- * Email-transport-specific — channel checks must NOT consume this.
166
- */
167
- suppressed: boolean;
168
- /** Category map merged across ALL matching rows, explicit false winning. */
169
- categories: Record<string, boolean>;
170
- }
171
-
172
- /**
173
- * The ONE aggregated preference READ shared by the email mailer (checkSuppression),
174
- * the in-app feed, and connector-send gating. Selects EVERY `email_preferences`
175
- * row matching the given identity keys and folds them into a single verdict.
176
- *
177
- * An address can legitimately have MORE THAN ONE row: the `(user_id, email)`
178
- * composite PK means a suppression imported before the contact existed is keyed
179
- * (email, email) while later interactive writes key (external_id, email). We
180
- * aggregate across ALL matching rows — any suppression signal on ANY row must
181
- * win — so an imported unsubscribe/bounce can never be shadowed by a newer clean
182
- * row for the same address.
183
- *
184
- * Rows are selected `WHERE email = keys.email OR user_id = keys.userId`, each leg
185
- * included ONLY when its key is a non-empty string. With NEITHER key provided we
186
- * do NOT query and return the empty/clean default.
187
- *
188
- * Category maps are merged with explicit FALSE winning: `categories[key] =
189
- * (categories[key] ?? true) && value` over every row's map — an opt-out recorded
190
- * on any row blocks, matching the conservative aggregation above. (In the common
191
- * single-row case this is identical to reading the row's map directly.)
192
- */
193
- export async function readRecipientPreferences(
194
- db: Database,
195
- keys: { email?: string | null; userId?: string | null },
196
- ): Promise<RecipientPreferences> {
197
- // Build the OR legs conditionally — an empty/absent key contributes NO leg, so
198
- // a `{ email }`-only read never matches every `user_id = ''` row and vice versa.
199
- const legs = [];
200
- if (typeof keys.email === "string" && keys.email.length > 0) {
201
- legs.push(eq(emailPreferences.email, keys.email));
202
- }
203
- if (typeof keys.userId === "string" && keys.userId.length > 0) {
204
- legs.push(eq(emailPreferences.userId, keys.userId));
205
- }
206
-
207
- // Neither key: do NOT query — a bare `.where()`/`or()` with no legs would match
208
- // the whole table. Return the clean default instead.
209
- if (legs.length === 0) {
210
- return { unsubscribedAll: false, suppressed: false, categories: {} };
211
- }
212
-
213
- const rows = await db
214
- .select()
215
- .from(emailPreferences)
216
- .where(or(...legs));
217
-
218
- // Merge category maps across rows with explicit FALSE winning (see JSDoc). This
219
- // always runs — an absent/empty map contributes nothing, so the result is `{}`.
220
- const categories: Record<string, boolean> = {};
221
- for (const prefs of rows) {
222
- const map = (prefs.categories ?? {}) as Record<string, boolean>;
223
- for (const [key, value] of Object.entries(map)) {
224
- categories[key] = (categories[key] ?? true) && value;
225
- }
226
- }
227
-
228
- return {
229
- unsubscribedAll: rows.some((r) => r.unsubscribedAll),
230
- suppressed: rows.some((r) => r.suppressed),
231
- categories,
232
- };
233
- }
234
-
235
161
  /**
236
162
  * D3 list-membership write. Resolves the caller's identity to the deterministic
237
163
  * `(externalId | contactId fallback, email)` pair via `resolveRecipient`, then
@@ -0,0 +1,53 @@
1
+ import { type Database, emailPreferences } from "@hogsend/db";
2
+ import { eq, or } from "drizzle-orm";
3
+
4
+ /** Aggregated preference verdict across every row matching a recipient. */
5
+ export interface RecipientPreferences {
6
+ /** true when any matching row has the global master opt-out. */
7
+ unsubscribedAll: boolean;
8
+ /** true when any matching row carries an email suppression signal. */
9
+ suppressed: boolean;
10
+ /** Category map merged across rows, with an explicit false always winning. */
11
+ categories: Record<string, boolean>;
12
+ }
13
+
14
+ /**
15
+ * Read the conservative preference verdict shared by email, feed, and
16
+ * connector delivery. This module intentionally contains no Hatchet/runtime
17
+ * imports so journey authoring modules remain safe to load in unit tests.
18
+ */
19
+ export async function readRecipientPreferences(
20
+ db: Database,
21
+ keys: { email?: string | null; userId?: string | null },
22
+ ): Promise<RecipientPreferences> {
23
+ const legs = [];
24
+ if (typeof keys.email === "string" && keys.email.length > 0) {
25
+ legs.push(eq(emailPreferences.email, keys.email));
26
+ }
27
+ if (typeof keys.userId === "string" && keys.userId.length > 0) {
28
+ legs.push(eq(emailPreferences.userId, keys.userId));
29
+ }
30
+
31
+ if (legs.length === 0) {
32
+ return { unsubscribedAll: false, suppressed: false, categories: {} };
33
+ }
34
+
35
+ const rows = await db
36
+ .select()
37
+ .from(emailPreferences)
38
+ .where(or(...legs));
39
+
40
+ const categories: Record<string, boolean> = {};
41
+ for (const prefs of rows) {
42
+ const map = (prefs.categories ?? {}) as Record<string, boolean>;
43
+ for (const [key, value] of Object.entries(map)) {
44
+ categories[key] = (categories[key] ?? true) && value;
45
+ }
46
+ }
47
+
48
+ return {
49
+ unsubscribedAll: rows.some((row) => row.unsubscribedAll),
50
+ suppressed: rows.some((row) => row.suppressed),
51
+ categories,
52
+ };
53
+ }
package/src/lib/sms.ts CHANGED
@@ -68,8 +68,6 @@ export interface SendSmsResult {
68
68
  * `sms_sends.idempotencyKey` index (Layer 2) and Hatchet's `memo` (Layer 1).
69
69
  */
70
70
  export async function sendSms(opts: SendSmsOptions): Promise<SendSmsResult> {
71
- const service = getSmsService();
72
-
73
71
  const boundary = getJourneyBoundary();
74
72
  let resolvedIdempotencyKey: string | undefined = opts.idempotencyKey;
75
73
  if (!resolvedIdempotencyKey && boundary) {
@@ -100,7 +98,28 @@ export async function sendSms(opts: SendSmsOptions): Promise<SendSmsResult> {
100
98
  category: boundary?.category ?? "journey",
101
99
  } as unknown as SmsServiceSendOptions;
102
100
 
101
+ const effect = {
102
+ to: opts.to,
103
+ userId: opts.userId,
104
+ template: String(opts.template),
105
+ props: sendOptions.props as Record<string, unknown>,
106
+ category: boundary?.category ?? "journey",
107
+ ...(opts.journeyName !== undefined
108
+ ? { journeyName: opts.journeyName }
109
+ : {}),
110
+ ...(opts.journeyStateId !== undefined
111
+ ? { journeyStateId: opts.journeyStateId }
112
+ : {}),
113
+ ...(resolvedIdempotencyKey
114
+ ? { idempotencyKey: resolvedIdempotencyKey }
115
+ : {}),
116
+ };
117
+
103
118
  const doSend = async (): Promise<SendSmsResult> => {
119
+ if (boundary?.services?.sms) {
120
+ return boundary.services.sms(effect);
121
+ }
122
+ const service = getSmsService();
104
123
  const result = await service.send(sendOptions);
105
124
  return {
106
125
  smsSendId: result.smsSendId,
@@ -0,0 +1,42 @@
1
+ import assert from "node:assert/strict";
2
+ import { createHash } from "node:crypto";
3
+ import test from "node:test";
4
+ import { stableStringify } from "./stable-stringify.js";
5
+
6
+ test("sorts keys, drops undefined, handles arrays/primitives/null", () => {
7
+ assert.equal(
8
+ stableStringify({
9
+ type: "property",
10
+ property: "plan",
11
+ operator: "eq",
12
+ value: "pro",
13
+ }),
14
+ '{"operator":"eq","property":"plan","type":"property","value":"pro"}',
15
+ );
16
+ assert.equal(
17
+ stableStringify({ b: 1, a: [2, { d: 3, c: undefined }] }),
18
+ '{"a":[2,{"d":3}],"b":1}',
19
+ );
20
+ assert.equal(stableStringify(null), "null");
21
+ assert.equal(stableStringify("x"), '"x"');
22
+ assert.equal(stableStringify(7), "7");
23
+ });
24
+
25
+ test("criteriaHash stays byte-identical across the hoist", () => {
26
+ // computeCriteriaHash (workflows/bucket-backfill.ts:45-51) is
27
+ // sha256(stableStringify(criteria ?? null)). This golden pins the MOVED
28
+ // implementation to the pre-hoist bytes: if it ever changes, every
29
+ // bucket_configs.criteriaHash would diff at boot and trigger a re-eval
30
+ // storm. Value computed from the implementation at bucket-backfill.ts
31
+ // BEFORE the move.
32
+ const criteria = {
33
+ type: "property",
34
+ property: "plan",
35
+ operator: "eq",
36
+ value: "pro",
37
+ };
38
+ assert.equal(
39
+ createHash("sha256").update(stableStringify(criteria)).digest("hex"),
40
+ "ac3d4442d5fdb740ba31377346a91a230ab0c14b2c24ef97f74eec08edad3e74",
41
+ );
42
+ });
@@ -0,0 +1,23 @@
1
+ /**
2
+ * Deterministic JSON-ish stringify: sorted object keys, `undefined` entries
3
+ * dropped — so key insertion order and optional-field spreading never change
4
+ * the output. Hoisted VERBATIM from workflows/bucket-backfill.ts (impact
5
+ * experiments D1) so the journey version hash
6
+ * (journeys/journey-version.ts) and the bucket criteria hash share ONE
7
+ * byte-identical implementation. `bucket_configs.criteriaHash` values MUST
8
+ * NOT change across this move (no re-eval storm on boot) — locked by the
9
+ * golden-value test in stable-stringify.test.ts.
10
+ */
11
+ export function stableStringify(value: unknown): string {
12
+ if (value === null || typeof value !== "object") {
13
+ return JSON.stringify(value);
14
+ }
15
+ if (Array.isArray(value)) {
16
+ return `[${value.map(stableStringify).join(",")}]`;
17
+ }
18
+ const entries = Object.entries(value as Record<string, unknown>)
19
+ .filter(([, v]) => v !== undefined)
20
+ .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
21
+ .map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`);
22
+ return `{${entries.join(",")}}`;
23
+ }
@@ -213,7 +213,12 @@ async function sendTrackedEmailInner<K extends TemplateName>(
213
213
  campaignId: options.campaignId,
214
214
  userId: options.userId,
215
215
  userEmail: options.userEmail ?? options.to,
216
- status: "failed",
216
+ // First-class "suppressed" status: a provider dispatch failure
217
+ // releases its idempotency key (catch block below), making it
218
+ // byte-identical to this row EXCEPT for the status — so campaign
219
+ // stats can only tell "gated by policy" from "failed at dispatch"
220
+ // if suppression names itself here.
221
+ status: "suppressed",
217
222
  // A suppressed send does NOT consume the idempotency key — leaving it
218
223
  // unset lets a later retry (e.g. after the recipient re-subscribes)
219
224
  // actually attempt the send rather than dedup to the suppressed row.
@@ -398,7 +403,9 @@ async function sendTrackedEmailInner<K extends TemplateName>(
398
403
  campaignId: options.campaignId,
399
404
  userId: options.userId,
400
405
  userEmail: options.userEmail ?? options.to,
401
- status: "failed",
406
+ // Policy-gated like suppression (the provider is never reached), so it
407
+ // shares the "suppressed" status; metadata.testMode marks the cause.
408
+ status: "suppressed",
402
409
  metadata: { testMode: true, originalTo: options.to },
403
410
  })
404
411
  .returning({ id: emailSends.id });
@@ -0,0 +1,99 @@
1
+ import { createHash } from "node:crypto";
2
+
3
+ /**
4
+ * Deterministic experiment-arm assignment for `ctx.variant` (impact
5
+ * experiments, Decision B). NO RNG and NO clock — the replay law: journey
6
+ * tasks replay-from-top on eviction/crash, so the same (journeyId, key,
7
+ * userId) must bucket identically on every evaluation, forever. Mirrors
8
+ * lib/holdout.ts (sha256 first 4 bytes → uniform 0-9999 bucket).
9
+ */
10
+
11
+ /** key charset: jsonb object key + hash segment + future API query param. */
12
+ const VARIANT_KEY_RE = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/;
13
+
14
+ /**
15
+ * Uniform 0-9999 bucket. Hash input is `variant:<journeyId>:<key>:<userId>`
16
+ * — the `variant:` prefix + the key segment make this hash family DISJOINT
17
+ * from holdoutBucket's `<salt>:<journeyId>:<userId>` (holdout.ts:17), so
18
+ * variant assignment is statistically independent of holdout assignment.
19
+ * `key` cannot contain `:` (validated), so segments are unambiguous.
20
+ * FROZEN COMPATIBILITY CONTRACT under the replay law — locked by a
21
+ * golden-value test; changing it re-buckets live experiments mid-flight.
22
+ */
23
+ export function variantBucket(opts: {
24
+ journeyId: string;
25
+ key: string;
26
+ userId: string;
27
+ }): number {
28
+ const digest = createHash("sha256")
29
+ .update(`variant:${opts.journeyId}:${opts.key}:${opts.userId}`)
30
+ .digest();
31
+ return digest.readUInt32BE(0) % 10000;
32
+ }
33
+
34
+ /**
35
+ * Key-syntax-only check — runs BEFORE the recordOnce read (it gates the
36
+ * jsonb path). Throws RangeError. 1-64 chars of [A-Za-z0-9_.-], starting
37
+ * with a letter or digit; no `:` (it delimits the hash-input segments) and
38
+ * no whitespace.
39
+ */
40
+ export function validateVariantKey(key: string): void {
41
+ if (!VARIANT_KEY_RE.test(key)) {
42
+ throw new RangeError(
43
+ `ctx.variant key "${key}" is invalid: 1-64 chars of [A-Za-z0-9_.-], ` +
44
+ "starting with a letter or digit (no ':' — it delimits the hash " +
45
+ "input; no spaces)",
46
+ );
47
+ }
48
+ }
49
+
50
+ /**
51
+ * Arms validation — runs ONLY inside the compute path (see performVariant
52
+ * in journeys/journey-context.ts): an enrollment with a recorded arm must
53
+ * never crash on a later deploy that ships malformed arms. Throws
54
+ * RangeError on: zero arms (JS callers; TS blocks via the tuple type),
55
+ * empty/non-string arm, duplicate arms.
56
+ */
57
+ export function validateVariantArms(arms: readonly string[]): void {
58
+ if (arms.length === 0) {
59
+ throw new RangeError("ctx.variant needs at least one arm");
60
+ }
61
+ for (const arm of arms) {
62
+ if (typeof arm !== "string" || arm.length === 0) {
63
+ throw new RangeError(
64
+ `ctx.variant arms must be non-empty strings (got ${JSON.stringify(
65
+ arm,
66
+ )})`,
67
+ );
68
+ }
69
+ }
70
+ if (new Set(arms).size !== arms.length) {
71
+ throw new RangeError(
72
+ `ctx.variant arms contain duplicates: [${arms.join(", ")}]`,
73
+ );
74
+ }
75
+ }
76
+
77
+ /**
78
+ * Deterministically pick one arm, equal split. Threshold for arm i is
79
+ * Math.round(((i + 1) / arms.length) * 10000); the LAST arm is forced to
80
+ * 10000 so rounding can never leave bucket 9999 unassigned. Weighted arms
81
+ * are deliberately NOT supported (v1 = equal split; a weight edit would
82
+ * remap buckets and reassign re-entrants of unlimited/once_per_period
83
+ * journeys — see the impact-experiments design spec, D2).
84
+ */
85
+ export function pickVariant(opts: {
86
+ journeyId: string;
87
+ key: string;
88
+ userId: string;
89
+ arms: readonly string[];
90
+ }): string {
91
+ const bucket = variantBucket(opts);
92
+ const n = opts.arms.length;
93
+ for (let i = 0; i < n; i += 1) {
94
+ const threshold = i === n - 1 ? 10000 : Math.round(((i + 1) / n) * 10000);
95
+ if (bucket < threshold) return opts.arms[i] as string;
96
+ }
97
+ // Unreachable: the last threshold is 10000 and bucket < 10000.
98
+ return opts.arms[n - 1] as string;
99
+ }
@@ -25,7 +25,7 @@ import { Webhook } from "svix";
25
25
  */
26
26
 
27
27
  /**
28
- * The 21-event catalog — the SINGLE source of truth (schema, routes, client,
28
+ * The 30-event catalog — the SINGLE source of truth (schema, routes, client,
29
29
  * CLI all derive from this). The `webhook.test` sentinel is intentionally NOT a
30
30
  * member (it is delivered out-of-band regardless of an endpoint's `eventTypes`).
31
31
  *
@@ -48,6 +48,11 @@ import { Webhook } from "svix";
48
48
  * `link.arrived` is the landing-confirmed subset of `link.clicked`: the
49
49
  * visitor reported back from the destination (opt-in `hs_ref` +
50
50
  * POST /v1/t/arrive) with identity evidence.
51
+ *
52
+ * `impact.digest` is the weekly facts-only impact rollup (shipped journey
53
+ * versions/labels + holdout-lift threshold crossings). It is the one
54
+ * SELF-REFERENTIAL event: the digest cron derives its watermark from its
55
+ * own `impact.digest` delivery rows in `webhook_deliveries`.
51
56
  */
52
57
  export const WEBHOOK_EVENT_TYPES = [
53
58
  "contact.created",
@@ -78,6 +83,16 @@ export const WEBHOOK_EVENT_TYPES = [
78
83
  "funnel.stage_changed",
79
84
  "deal.quoted",
80
85
  "deal.sold",
86
+ // Group dimension (account/team/company-level). Emitted from the intent-layer
87
+ // `/v1/groups` routes ONLY (never the ingest/associateGroups path):
88
+ // `group.identified` on a successful identify, `group.member_added` /
89
+ // `group.member_removed` on membership mutations.
90
+ "group.identified",
91
+ "group.member_added",
92
+ "group.member_removed",
93
+ // Weekly impact digest (impact experiments D5). Self-referential: the
94
+ // cron watermarks off its own delivery rows.
95
+ "impact.digest",
81
96
  ] as const;
82
97
 
83
98
  export type WebhookEventType = (typeof WEBHOOK_EVENT_TYPES)[number];
@@ -1,6 +1,7 @@
1
1
  import { parseEnabledFilter } from "../journeys/registry.js";
2
2
  import type { DefinedList, ListMeta } from "./define-list.js";
3
3
  import { setListRegistry } from "./registry-singleton.js";
4
+ import { isListSubscribed } from "./subscription.js";
4
5
 
5
6
  /**
6
7
  * In-process index of the defined email lists (D3). Mirrors `BucketRegistry` /
@@ -61,8 +62,11 @@ export class ListRegistry {
61
62
  * {@link ListRegistry.isSubscribedByDefault}), matching legacy semantics.
62
63
  */
63
64
  isSubscribed(categories: Record<string, boolean>, id: string): boolean {
64
- const defaultOptIn = this.isSubscribedByDefault(id);
65
- return defaultOptIn ? categories[id] !== false : categories[id] === true;
65
+ return isListSubscribed({
66
+ categories,
67
+ id,
68
+ defaultOptIn: this.isSubscribedByDefault(id),
69
+ });
66
70
  }
67
71
 
68
72
  /**
@@ -0,0 +1,13 @@
1
+ /**
2
+ * Pure list-polarity decision shared by production registries and deterministic
3
+ * journey tests.
4
+ */
5
+ export function isListSubscribed(opts: {
6
+ categories: Record<string, boolean>;
7
+ id: string;
8
+ defaultOptIn: boolean;
9
+ }): boolean {
10
+ return opts.defaultOptIn
11
+ ? opts.categories[opts.id] !== false
12
+ : opts.categories[opts.id] === true;
13
+ }
@@ -6,8 +6,7 @@ import { backfillAttributionBatch } from "../../lib/attribution-backfill.js";
6
6
  import { getConversionRegistry } from "../../lib/conversions.js";
7
7
 
8
8
  /**
9
- * Admin attribution API (docs/revenue-attribution-plan.md §6.2, extended by
10
- * docs/attribution-impact-plan.md §1.5) — reads over the credit ledger.
9
+ * Admin attribution API — reads over the credit ledger.
11
10
  * Every model was persisted at conversion time, so model comparison is a
12
11
  * GROUP BY, not a re-computation — and since the ledger carries
13
12
  * journey/campaign/template scope, "revenue by journey" is too.