@hogsend/engine 0.46.0 → 0.50.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/connectors/presets/index.ts +8 -2
- package/src/container.ts +149 -7
- 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 +195 -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/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 +8 -0
- package/src/lib/email.ts +23 -2
- package/src/lib/enrollment-policy.ts +51 -0
- 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/fx.ts +374 -0
- package/src/lib/global-control-readout.ts +166 -0
- package/src/lib/groups.ts +362 -0
- package/src/lib/ingestion.ts +38 -0
- package/src/lib/journey-lift.ts +142 -0
- 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/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/contacts.ts +53 -4
- package/src/routes/admin/conversions.ts +137 -0
- package/src/routes/admin/flags.ts +369 -0
- package/src/routes/admin/groups.ts +866 -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/readiness.ts +8 -8
- package/src/routes/admin/settings.ts +145 -0
- package/src/routes/admin/targeting.ts +256 -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/impact-digest.ts +761 -0
- package/src/workflows/journey-blueprint-interpreter.ts +18 -1
package/src/lib/outbound.ts
CHANGED
|
@@ -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
|
package/src/lib/preferences.ts
CHANGED
|
@@ -1,11 +1,16 @@
|
|
|
1
1
|
import type { Database } from "@hogsend/db";
|
|
2
2
|
import { emailPreferences } from "@hogsend/db";
|
|
3
|
-
import {
|
|
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
|
+
}
|
|
@@ -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
|
|
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];
|
package/src/lists/registry.ts
CHANGED
|
@@ -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
|
-
|
|
65
|
-
|
|
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
|
+
}
|