@hogsend/engine 0.46.1 → 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.
Files changed (69) hide show
  1. package/README.md +6 -0
  2. package/package.json +13 -10
  3. package/src/connectors/presets/index.ts +8 -2
  4. package/src/container.ts +149 -7
  5. package/src/destinations/presets/posthog.ts +7 -0
  6. package/src/destinations/presets/segment.ts +5 -0
  7. package/src/env.ts +38 -0
  8. package/src/flags/reconcile.ts +195 -0
  9. package/src/index.ts +79 -0
  10. package/src/journeys/authoring.ts +32 -0
  11. package/src/journeys/define-journey.ts +45 -40
  12. package/src/journeys/execute-journey-run.ts +73 -32
  13. package/src/journeys/journey-boundary.ts +76 -0
  14. package/src/journeys/journey-context.ts +128 -70
  15. package/src/journeys/journey-task-factory.ts +31 -0
  16. package/src/journeys/journey-task-runtime.ts +31 -0
  17. package/src/journeys/journey-version.test.ts +236 -0
  18. package/src/journeys/journey-version.ts +158 -0
  19. package/src/journeys/record-once.ts +28 -2
  20. package/src/lib/connector-actions.test.ts +36 -0
  21. package/src/lib/connector-actions.ts +42 -4
  22. package/src/lib/contacts.ts +49 -0
  23. package/src/lib/conversions.test.ts +33 -0
  24. package/src/lib/conversions.ts +8 -0
  25. package/src/lib/email.ts +23 -2
  26. package/src/lib/enrollment-policy.ts +51 -0
  27. package/src/lib/feed.ts +55 -3
  28. package/src/lib/flags-registry.ts +48 -0
  29. package/src/lib/flags.ts +498 -0
  30. package/src/lib/fx.ts +374 -0
  31. package/src/lib/global-control-readout.ts +166 -0
  32. package/src/lib/groups.ts +362 -0
  33. package/src/lib/ingestion.ts +38 -0
  34. package/src/lib/journey-lift.ts +142 -0
  35. package/src/lib/operator-settings.ts +71 -0
  36. package/src/lib/outbound.ts +147 -0
  37. package/src/lib/preferences.ts +6 -80
  38. package/src/lib/recipient-preferences.ts +53 -0
  39. package/src/lib/sms.ts +21 -2
  40. package/src/lib/stable-stringify.test.ts +42 -0
  41. package/src/lib/stable-stringify.ts +23 -0
  42. package/src/lib/variant.ts +99 -0
  43. package/src/lib/webhook-signing.ts +16 -1
  44. package/src/lists/registry.ts +6 -2
  45. package/src/lists/subscription.ts +13 -0
  46. package/src/routes/admin/contacts.ts +53 -4
  47. package/src/routes/admin/conversions.ts +137 -0
  48. package/src/routes/admin/flags.ts +369 -0
  49. package/src/routes/admin/groups.ts +866 -0
  50. package/src/routes/admin/impact-schemas.ts +44 -0
  51. package/src/routes/admin/impact-wire.test.ts +181 -0
  52. package/src/routes/admin/impact.ts +486 -0
  53. package/src/routes/admin/index.ts +12 -0
  54. package/src/routes/admin/journey-impact.ts +446 -0
  55. package/src/routes/admin/journeys.ts +70 -100
  56. package/src/routes/admin/settings.ts +145 -0
  57. package/src/routes/admin/targeting.ts +256 -0
  58. package/src/routes/events/index.ts +11 -0
  59. package/src/routes/flags/index.ts +120 -0
  60. package/src/routes/groups/index.ts +417 -0
  61. package/src/routes/index.ts +23 -1
  62. package/src/testing.ts +25 -0
  63. package/src/webhook-sources/presets/index.ts +5 -1
  64. package/src/webhook-sources/presets/intercom.ts +230 -0
  65. package/src/webhook-sources/presets/segment.ts +56 -4
  66. package/src/worker.ts +3 -0
  67. package/src/workflows/bucket-backfill.ts +1 -14
  68. package/src/workflows/impact-digest.ts +761 -0
  69. package/src/workflows/journey-blueprint-interpreter.ts +18 -1
@@ -0,0 +1,362 @@
1
+ import type { AnalyticsProvider, Group, GroupMembership } from "@hogsend/core";
2
+ import { contacts, type Database, groupMemberships, groups } from "@hogsend/db";
3
+ import { and, desc, eq, isNull, sql } from "drizzle-orm";
4
+ import { getAnalytics } from "./analytics-singleton.js";
5
+ import type { Logger } from "./logger.js";
6
+
7
+ /**
8
+ * Sovereign, DB-first group helpers — Hogsend's standalone answer to PostHog
9
+ * group analytics. Every function is single-object-in / result-object-out with
10
+ * `db` injected, mirroring the house style in {@link file://./contacts.ts}.
11
+ *
12
+ * A group is identified by its `(groupType, groupKey)` natural key. The `groups`
13
+ * unique index is PARTIAL (`WHERE deleted_at IS NULL`), so every upsert MUST
14
+ * name that predicate as the conflict arbiter — see {@link identifyGroup}.
15
+ */
16
+
17
+ /**
18
+ * Thrown by {@link addGroupMember} when the target contact does not exist (or is
19
+ * soft-deleted). Signalled BEFORE the group is resolve-or-created, so a bad
20
+ * contact id never mints an orphan group; the route catches it → 404. Mirrors
21
+ * the typed-error pattern in {@link file://./contacts.ts}
22
+ * (`PublishableAnonymousMergeError`).
23
+ */
24
+ export class GroupContactNotFoundError extends Error {
25
+ constructor(public readonly contactId: string) {
26
+ super(`Contact not found: ${contactId}`);
27
+ this.name = "GroupContactNotFoundError";
28
+ }
29
+ }
30
+
31
+ /** Rows returned by drizzle's select match the portable `Group` shape 1:1. */
32
+ type GroupRow = typeof groups.$inferSelect;
33
+
34
+ /** Clamp a caller-supplied page size to a sane default + hard cap. */
35
+ function clampLimit(
36
+ limit: number | undefined,
37
+ fallback = 50,
38
+ cap = 200,
39
+ ): number {
40
+ if (limit === undefined || !Number.isFinite(limit) || limit <= 0) {
41
+ return fallback;
42
+ }
43
+ return Math.min(Math.floor(limit), cap);
44
+ }
45
+
46
+ /** Non-negative page offset. */
47
+ function clampOffset(offset: number | undefined): number {
48
+ if (offset === undefined || !Number.isFinite(offset) || offset <= 0) return 0;
49
+ return Math.floor(offset);
50
+ }
51
+
52
+ /**
53
+ * Identify (upsert) a group by its `(groupType, groupKey)` natural key and,
54
+ * best-effort, mirror the property WRITE to the active analytics provider
55
+ * (PostHog `groupIdentify`).
56
+ *
57
+ * CRITICAL — the `groups_type_key_unique_idx` unique index is PARTIAL
58
+ * (`WHERE deleted_at IS NULL`). For `onConflictDoUpdate` the arbiter predicate
59
+ * matching that partial index goes in **`targetWhere`** (NOT `where`, which is
60
+ * ambiguous and silently misbehaves → duplicate rows / 42P10). On conflict we
61
+ * MERGE properties with the exact jsonb idiom `contacts.ts` uses
62
+ * (`coalesce(existing,'{}'::jsonb) || <new>::jsonb`, new wins), COALESCE the
63
+ * displayName (a caller who omits it never nulls an existing name), and bump
64
+ * `lastSeenAt` + `updatedAt`; `firstSeenAt` is preserved.
65
+ */
66
+ export async function identifyGroup(opts: {
67
+ db: Database;
68
+ groupType: string;
69
+ groupKey: string;
70
+ displayName?: string;
71
+ properties?: Record<string, unknown>;
72
+ organizationId?: string;
73
+ analytics?: AnalyticsProvider;
74
+ logger?: Logger;
75
+ }): Promise<{ group: Group }> {
76
+ const { db, groupType, groupKey, displayName, properties, organizationId } =
77
+ opts;
78
+ const now = new Date();
79
+
80
+ const updateSet: Record<string, unknown> = {
81
+ lastSeenAt: now,
82
+ updatedAt: now,
83
+ };
84
+ // Merge only when properties were supplied — an association-only upsert
85
+ // (associateGroups / resolveGroupId) must not rewrite the property bag.
86
+ if (properties) {
87
+ updateSet.properties = sql`coalesce(${groups.properties}, '{}'::jsonb) || ${JSON.stringify(properties)}::jsonb`;
88
+ }
89
+ // COALESCE displayName: only set when the caller supplied one, so an omitted
90
+ // name never clobbers an existing one.
91
+ if (displayName !== undefined) {
92
+ updateSet.displayName = displayName;
93
+ }
94
+
95
+ const inserted = await db
96
+ .insert(groups)
97
+ .values({
98
+ groupType,
99
+ groupKey,
100
+ displayName: displayName ?? null,
101
+ properties: properties ?? {},
102
+ organizationId: organizationId ?? null,
103
+ firstSeenAt: now,
104
+ lastSeenAt: now,
105
+ })
106
+ .onConflictDoUpdate({
107
+ target: [groups.groupType, groups.groupKey],
108
+ targetWhere: sql`${groups.deletedAt} is null`,
109
+ set: updateSet,
110
+ })
111
+ .returning();
112
+
113
+ const row = inserted[0];
114
+ if (!row) throw new Error("Group upsert returned no row");
115
+
116
+ // Best-effort analytics group-property WRITE (the PostHog groupIdentify path).
117
+ // Association-only upserts pass no properties, so this stays a no-op there.
118
+ const analytics = opts.analytics ?? getAnalytics();
119
+ if (properties && analytics?.capabilities.groups && analytics.groupIdentify) {
120
+ try {
121
+ analytics.groupIdentify({ groupType, groupKey, properties });
122
+ } catch (err) {
123
+ opts.logger?.debug("groupIdentify failed (non-fatal)", {
124
+ err,
125
+ groupType,
126
+ groupKey,
127
+ });
128
+ }
129
+ }
130
+
131
+ return { group: row };
132
+ }
133
+
134
+ /**
135
+ * Resolve-or-create the LIVE group for `(groupType, groupKey)` WITHOUT touching
136
+ * its property bag or firing analytics (association context only). Reuses
137
+ * {@link identifyGroup}'s atomic partial-index upsert — passing no `properties`
138
+ * skips the merge AND the groupIdentify wire — so the select-then-insert race
139
+ * the campaigns route guards against never arises (the upsert is one statement).
140
+ */
141
+ async function resolveGroupId(
142
+ db: Database,
143
+ groupType: string,
144
+ groupKey: string,
145
+ ): Promise<string> {
146
+ const { group } = await identifyGroup({ db, groupType, groupKey });
147
+ return group.id;
148
+ }
149
+
150
+ /**
151
+ * INGEST helper (Phase 2.2): associate a contact with each group in a
152
+ * `groupType → groupKey` map. Ensures every group row exists (association only,
153
+ * NO property write, NO analytics) then upserts a `group_memberships` row per
154
+ * group via `onConflictDoNothing` (its unique index is NOT partial, so no
155
+ * arbiter predicate is needed). No-ops cleanly on an empty map. Returns the
156
+ * number of groups whose membership is now in place.
157
+ */
158
+ export async function associateGroups(opts: {
159
+ db: Database;
160
+ contactId: string;
161
+ groups: Record<string, string>;
162
+ }): Promise<{ associated: number }> {
163
+ const { db, contactId } = opts;
164
+ const entries = Object.entries(opts.groups ?? {});
165
+ if (entries.length === 0) return { associated: 0 };
166
+
167
+ let associated = 0;
168
+ for (const [groupType, groupKey] of entries) {
169
+ if (!groupType || !groupKey) continue;
170
+ const groupId = await resolveGroupId(db, groupType, groupKey);
171
+ await db
172
+ .insert(groupMemberships)
173
+ .values({ groupId, contactId })
174
+ .onConflictDoNothing({
175
+ target: [groupMemberships.groupId, groupMemberships.contactId],
176
+ });
177
+ associated += 1;
178
+ }
179
+ return { associated };
180
+ }
181
+
182
+ /**
183
+ * Add a contact to a group. FIRST assert the contact exists (else the FK-bound
184
+ * membership insert would 23503 AFTER the group was resolve-or-created, minting
185
+ * an orphan group and 500-ing) — a missing/soft-deleted contact throws
186
+ * {@link GroupContactNotFoundError} BEFORE any group is touched. Then
187
+ * resolve-or-create the live group (association only) and INSERT the membership
188
+ * via `onConflictDoNothing`; when nothing is returned the contact is already a
189
+ * member, so we read the existing row. `created` reflects whether THIS call
190
+ * inserted the membership.
191
+ */
192
+ export async function addGroupMember(opts: {
193
+ db: Database;
194
+ groupType: string;
195
+ groupKey: string;
196
+ contactId: string;
197
+ role?: string;
198
+ }): Promise<{ membership: GroupMembership; created: boolean }> {
199
+ const { db, groupType, groupKey, contactId, role } = opts;
200
+
201
+ // Contact-existence guard — BEFORE `resolveGroupId` so a bad id never creates
202
+ // an orphan group. The route validated `contactId` is a well-formed uuid, so
203
+ // this select cannot 22P02. Only live (non-deleted) contacts qualify.
204
+ const contactRows = await db
205
+ .select({ id: contacts.id })
206
+ .from(contacts)
207
+ .where(and(eq(contacts.id, contactId), isNull(contacts.deletedAt)))
208
+ .limit(1);
209
+ if (!contactRows[0]) {
210
+ throw new GroupContactNotFoundError(contactId);
211
+ }
212
+
213
+ const groupId = await resolveGroupId(db, groupType, groupKey);
214
+
215
+ const inserted = await db
216
+ .insert(groupMemberships)
217
+ .values({ groupId, contactId, role: role ?? null })
218
+ .onConflictDoNothing({
219
+ target: [groupMemberships.groupId, groupMemberships.contactId],
220
+ })
221
+ .returning();
222
+
223
+ if (inserted[0]) {
224
+ return { membership: inserted[0], created: true };
225
+ }
226
+
227
+ // Already a member — the conflict swallowed the insert; read the live row.
228
+ const existing = await db
229
+ .select()
230
+ .from(groupMemberships)
231
+ .where(
232
+ and(
233
+ eq(groupMemberships.groupId, groupId),
234
+ eq(groupMemberships.contactId, contactId),
235
+ ),
236
+ )
237
+ .limit(1);
238
+
239
+ const row = existing[0];
240
+ if (!row) throw new Error("Membership upsert returned no row");
241
+ return { membership: row, created: false };
242
+ }
243
+
244
+ /**
245
+ * Remove a contact from a group. Hard-deletes the membership row (memberships
246
+ * have no soft-delete column). Resolves the LIVE group first; a missing group or
247
+ * absent membership yields `{ removed: false }`.
248
+ */
249
+ export async function removeGroupMember(opts: {
250
+ db: Database;
251
+ groupType: string;
252
+ groupKey: string;
253
+ contactId: string;
254
+ }): Promise<{ removed: boolean }> {
255
+ const { db, groupType, groupKey, contactId } = opts;
256
+ const { group } = await getGroup({ db, groupType, groupKey });
257
+ if (!group) return { removed: false };
258
+
259
+ const deleted = await db
260
+ .delete(groupMemberships)
261
+ .where(
262
+ and(
263
+ eq(groupMemberships.groupId, group.id),
264
+ eq(groupMemberships.contactId, contactId),
265
+ ),
266
+ )
267
+ .returning({ id: groupMemberships.id });
268
+
269
+ return { removed: deleted.length > 0 };
270
+ }
271
+
272
+ /** Fetch the single LIVE group for `(groupType, groupKey)`, or null. */
273
+ export async function getGroup(opts: {
274
+ db: Database;
275
+ groupType: string;
276
+ groupKey: string;
277
+ }): Promise<{ group: Group | null }> {
278
+ const { db, groupType, groupKey } = opts;
279
+ const rows = await db
280
+ .select()
281
+ .from(groups)
282
+ .where(
283
+ and(
284
+ eq(groups.groupType, groupType),
285
+ eq(groups.groupKey, groupKey),
286
+ isNull(groups.deletedAt),
287
+ ),
288
+ )
289
+ .limit(1);
290
+ const row: GroupRow | undefined = rows[0];
291
+ return { group: row ?? null };
292
+ }
293
+
294
+ /**
295
+ * List LIVE groups, newest-seen first, with an optional `groupType` filter and
296
+ * clamped pagination (default 50, hard cap 200).
297
+ */
298
+ export async function listGroups(opts: {
299
+ db: Database;
300
+ groupType?: string;
301
+ limit?: number;
302
+ offset?: number;
303
+ }): Promise<{ groups: Group[] }> {
304
+ const { db, groupType } = opts;
305
+ const where = groupType
306
+ ? and(eq(groups.groupType, groupType), isNull(groups.deletedAt))
307
+ : isNull(groups.deletedAt);
308
+
309
+ const rows = await db
310
+ .select()
311
+ .from(groups)
312
+ .where(where)
313
+ .orderBy(desc(groups.lastSeenAt))
314
+ .limit(clampLimit(opts.limit))
315
+ .offset(clampOffset(opts.offset));
316
+
317
+ return { groups: rows };
318
+ }
319
+
320
+ /**
321
+ * List the members of a LIVE group (joining `group_memberships → contacts`),
322
+ * newest-joined first, with clamped pagination. Only live contacts are
323
+ * surfaced. Returns `[]` when the group does not exist.
324
+ */
325
+ export async function listGroupMembers(opts: {
326
+ db: Database;
327
+ groupType: string;
328
+ groupKey: string;
329
+ limit?: number;
330
+ offset?: number;
331
+ }): Promise<{
332
+ members: Array<{
333
+ contactId: string;
334
+ email: string | null;
335
+ externalId: string | null;
336
+ role: string | null;
337
+ joinedAt: Date;
338
+ }>;
339
+ }> {
340
+ const { db, groupType, groupKey } = opts;
341
+ const { group } = await getGroup({ db, groupType, groupKey });
342
+ if (!group) return { members: [] };
343
+
344
+ const members = await db
345
+ .select({
346
+ contactId: groupMemberships.contactId,
347
+ email: contacts.email,
348
+ externalId: contacts.externalId,
349
+ role: groupMemberships.role,
350
+ joinedAt: groupMemberships.joinedAt,
351
+ })
352
+ .from(groupMemberships)
353
+ .innerJoin(contacts, eq(groupMemberships.contactId, contacts.id))
354
+ .where(
355
+ and(eq(groupMemberships.groupId, group.id), isNull(contacts.deletedAt)),
356
+ )
357
+ .orderBy(desc(groupMemberships.joinedAt))
358
+ .limit(clampLimit(opts.limit))
359
+ .offset(clampOffset(opts.offset));
360
+
361
+ return { members };
362
+ }
@@ -2,6 +2,7 @@ import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
2
2
  import type {
3
3
  AnalyticsEventMirrorConfig,
4
4
  AnalyticsProvider,
5
+ GroupsAssociation,
5
6
  PropertyCondition,
6
7
  } from "@hogsend/core";
7
8
  import { evaluatePropertyConditions } from "@hogsend/core";
@@ -41,6 +42,7 @@ import {
41
42
  import { getCrmSyncConfig } from "./crm-registry-singleton.js";
42
43
  import { recordFunnelProgressAtIngest } from "./funnel-progress.js";
43
44
  import { applyFunnelTransitionsAtIngest } from "./funnel-transitions.js";
45
+ import { associateGroups } from "./groups.js";
44
46
  import type { Logger } from "./logger.js";
45
47
 
46
48
  export interface IngestEvent {
@@ -69,6 +71,14 @@ export interface IngestEvent {
69
71
  eventProperties: Record<string, unknown>;
70
72
  /** D2: → `contacts.properties` merge ONLY. */
71
73
  contactProperties?: Record<string, unknown>;
74
+ /**
75
+ * The groupType→groupKey association map for this event — persisted on
76
+ * `user_events.groups`, drives group membership (each group row is ensured +
77
+ * a `group_memberships` row upserted for the resolved contact), and forwards
78
+ * to analytics as `$groups` alongside the mirrored capture. Optional (null on
79
+ * `user_events` when unset).
80
+ */
81
+ groups?: GroupsAssociation;
72
82
  /**
73
83
  * The event's own monetary worth (deal value, order total). Stored on the
74
84
  * first-class `user_events.value` column — the revenue spine every rollup,
@@ -393,6 +403,7 @@ export async function ingestEvent(opts: {
393
403
  userId: resolvedKey,
394
404
  event: event.event,
395
405
  properties: event.eventProperties,
406
+ groups: event.groups ?? null,
396
407
  value,
397
408
  currency,
398
409
  source: event.source ?? null,
@@ -416,6 +427,7 @@ export async function ingestEvent(opts: {
416
427
  userId: resolvedKey,
417
428
  event: event.event,
418
429
  properties: event.eventProperties,
430
+ groups: event.groups ?? null,
419
431
  value,
420
432
  currency,
421
433
  source: event.source ?? null,
@@ -476,6 +488,10 @@ export async function ingestEvent(opts: {
476
488
  mirrorProvider.capture({
477
489
  distinctId: resolvedKey,
478
490
  event: event.event,
491
+ // Group context rides the mirrored capture as `$groups` so PostHog (et
492
+ // al.) can attribute the event to its account/team. Undefined when the
493
+ // event carries no group association.
494
+ groups: event.groups,
479
495
  // The revenue spine fans out with the event: `value`/`currency` ride as
480
496
  // plain properties so the analytics tool (PostHog et al.) can sum
481
497
  // revenue without a Hogsend round-trip. Property-bag keys of the same
@@ -495,6 +511,28 @@ export async function ingestEvent(opts: {
495
511
  }
496
512
  }
497
513
 
514
+ // (2d) Sovereign group association — the STANDALONE (DB-first) path, run on
515
+ // every ingest regardless of the analytics mirror config above. Ensures each
516
+ // group row exists and upserts a `group_memberships` row for the resolved
517
+ // contact (idempotent, no property write, no analytics). Placed on the
518
+ // fresh-insert side of the idempotency guard (the duplicate path returned at
519
+ // the early `stored:false`), so a same-key replay never re-associates.
520
+ // Best-effort: the `user_events` row is already durably stored (the plain
521
+ // path has NO idempotency key, so a thrown error + ingest retry would
522
+ // DOUBLE-insert the event) — a group-write hiccup must never fail an
523
+ // already-stored event.
524
+ if (event.groups && Object.keys(event.groups).length > 0) {
525
+ try {
526
+ await associateGroups({ db, contactId, groups: event.groups });
527
+ } catch (err) {
528
+ logger.warn("group association failed (non-fatal)", {
529
+ event: event.event,
530
+ userId: resolvedKey,
531
+ error: err instanceof Error ? err.message : String(err),
532
+ });
533
+ }
534
+ }
535
+
498
536
  // (3) Build the JSON-serializable subset of eventProperties for the Hatchet
499
537
  // push payload (scalars only — the SDK serializes the envelope).
500
538
  const serializableProperties = Object.fromEntries(
@@ -0,0 +1,142 @@
1
+ import { type Database, journeyStates } from "@hogsend/db";
2
+ import { and, eq, sql } from "drizzle-orm";
3
+ import { computeLift, type LiftVerdict } from "./lift-stats.js";
4
+
5
+ /**
6
+ * Counts-only cohort: the /lift route merges per-currency values back in
7
+ * (computeLiftValues); the phase-2b /impact overall block and the phase-3b
8
+ * digest consume counts as-is.
9
+ */
10
+ export interface LiftCohort {
11
+ contacts: number;
12
+ converters: number;
13
+ rate: number;
14
+ }
15
+
16
+ export interface JourneyLiftResult {
17
+ treatment: LiftCohort;
18
+ control: LiftCohort;
19
+ verdict: LiftVerdict;
20
+ }
21
+
22
+ interface LiftQueryOpts {
23
+ db: Database;
24
+ journeyId: string;
25
+ since: Date;
26
+ /** Snapshot instant; defaults to now (both bounds become no-ops). */
27
+ asOf?: Date;
28
+ /** Scope the outcome to one conversion definition; default any. */
29
+ definitionId?: string;
30
+ }
31
+
32
+ /** Shared SQL fragments for one (journeyId, since, asOf, definitionId). */
33
+ function liftFragments(opts: LiftQueryOpts) {
34
+ const asOf = opts.asOf ?? new Date();
35
+ return {
36
+ sinceTs: sql`${opts.since.toISOString()}::timestamptz`,
37
+ asOfTs: sql`${asOf.toISOString()}::timestamptz`,
38
+ definitionSql: opts.definitionId
39
+ ? sql` and c.definition_id = ${opts.definitionId}`
40
+ : sql``,
41
+ };
42
+ }
43
+
44
+ /**
45
+ * Holdout lift for one journey — the ONE implementation of the causal math
46
+ * (routes/admin/funnels.ts:16 law). Treatment = status != 'held_out';
47
+ * control = status = 'held_out'; outcome = ≥1 qualifying conversions row
48
+ * with occurred_at >= the state row's created_at (intent-to-treat clock).
49
+ *
50
+ * `asOf` (default: now) snapshots the read: cohort rows require
51
+ * created_at < asOf and conversions require occurred_at <= asOf. With
52
+ * asOf = now both bounds are no-ops (future-dated rows cannot exist), so
53
+ * the /lift route's behavior is unchanged by the extraction — pinned by a
54
+ * regression fixture (apps/api journey-lift.test.ts).
55
+ */
56
+ export async function computeJourneyLift(
57
+ opts: LiftQueryOpts,
58
+ ): Promise<JourneyLiftResult> {
59
+ const { db, journeyId } = opts;
60
+ const { sinceTs, asOfTs, definitionSql } = liftFragments(opts);
61
+
62
+ // Outcome: the contact fired ≥1 qualifying conversion AFTER their state
63
+ // row was created (post-assignment — the intent-to-treat clock) and at
64
+ // or before the asOf snapshot instant.
65
+ const convertedSql = sql`exists (
66
+ select 1 from conversions c
67
+ where c.user_key = ${journeyStates.userId}
68
+ and c.occurred_at >= ${journeyStates.createdAt}
69
+ and c.occurred_at <= ${asOfTs}${definitionSql}
70
+ )`;
71
+
72
+ const cohort = async (control: boolean): Promise<LiftCohort> => {
73
+ const statusFilter = control
74
+ ? eq(journeyStates.status, "held_out")
75
+ : sql`${journeyStates.status} != 'held_out'`;
76
+ const [row] = await db
77
+ .select({
78
+ contacts: sql<number>`count(distinct ${journeyStates.userId})::int`,
79
+ converters: sql<number>`(count(distinct ${journeyStates.userId}) filter (where ${convertedSql}))::int`,
80
+ })
81
+ .from(journeyStates)
82
+ .where(
83
+ and(
84
+ eq(journeyStates.journeyId, journeyId),
85
+ sql`${journeyStates.createdAt} >= ${sinceTs}`,
86
+ sql`${journeyStates.createdAt} < ${asOfTs}`,
87
+ statusFilter,
88
+ ),
89
+ );
90
+ const contacts = Number(row?.contacts ?? 0);
91
+ const converters = row?.converters ?? 0;
92
+ return {
93
+ contacts,
94
+ converters,
95
+ rate: contacts > 0 ? converters / contacts : 0,
96
+ };
97
+ };
98
+
99
+ const [treatment, control] = await Promise.all([cohort(false), cohort(true)]);
100
+ return { treatment, control, verdict: computeLift({ treatment, control }) };
101
+ }
102
+
103
+ /**
104
+ * Per-currency qualifying conversion value for both cohorts (full value,
105
+ * not fractional credit). Kept SEPARATE from the counts helper: /lift
106
+ * composes it into its wire shape; the digest and overview never need it.
107
+ */
108
+ export async function computeLiftValues(opts: LiftQueryOpts): Promise<{
109
+ treatment: Array<{ currency: string | null; value: number }>;
110
+ control: Array<{ currency: string | null; value: number }>;
111
+ }> {
112
+ const { db, journeyId } = opts;
113
+ const { sinceTs, asOfTs, definitionSql } = liftFragments(opts);
114
+
115
+ const values = async (control: boolean) => {
116
+ const rows = await db.execute<{ currency: string | null; value: number }>(
117
+ sql`
118
+ select c.currency, coalesce(sum(c.value), 0)::float8 as value
119
+ from conversions c
120
+ where c.value is not null
121
+ and c.occurred_at <= ${asOfTs}
122
+ and exists (
123
+ select 1 from journey_states js
124
+ where js.journey_id = ${journeyId}
125
+ and js.created_at >= ${sinceTs}
126
+ and js.created_at < ${asOfTs}
127
+ and ${control ? sql`js.status = 'held_out'` : sql`js.status != 'held_out'`}
128
+ and js.user_id = c.user_key
129
+ and c.occurred_at >= js.created_at
130
+ )${definitionSql}
131
+ group by c.currency
132
+ `,
133
+ );
134
+ return [...rows].map((r) => ({
135
+ currency: r.currency,
136
+ value: Number(r.value),
137
+ }));
138
+ };
139
+
140
+ const [treatment, control] = await Promise.all([values(false), values(true)]);
141
+ return { treatment, control };
142
+ }
@@ -0,0 +1,71 @@
1
+ import type { Database } from "@hogsend/db";
2
+ import { operatorSettings } from "@hogsend/db";
3
+ import { eq } from "drizzle-orm";
4
+
5
+ /**
6
+ * Typed access to `operator_settings` — the generic overlay for GLOBAL
7
+ * operator choices made in Studio (the `journey_configs` DB-config-overlay
8
+ * pattern generalized to a KV keyed by setting name). An ABSENT row means
9
+ * "the operator made no choice" and env/boot defaults decide; a PRESENT row
10
+ * is the operator's explicit word and overlays env — including an explicit
11
+ * "off".
12
+ *
13
+ * Deliberately NO cache (lean-first): every reader is a low-QPS admin/lens
14
+ * surface where a primary-key lookup is nothing, and a cache would only add
15
+ * an invalidation story across the API + worker processes for zero felt win.
16
+ */
17
+
18
+ /** The `"fx"` operator setting — the Studio-chosen base currency. */
19
+ export const FX_SETTINGS_KEY = "fx";
20
+
21
+ /**
22
+ * Value shape under {@link FX_SETTINGS_KEY}. `baseCurrency: null` is the
23
+ * operator EXPLICITLY turning the lens off (beats env `BASE_CURRENCY`);
24
+ * "fall back to env" is expressed by DELETING the row, never by a value.
25
+ */
26
+ export interface FxSetting {
27
+ baseCurrency: string | null;
28
+ }
29
+
30
+ /** Read one operator setting's value, or null when the row doesn't exist. */
31
+ export async function getOperatorSetting<T>(
32
+ db: Database,
33
+ key: string,
34
+ ): Promise<T | null> {
35
+ const [row] = await db
36
+ .select({ value: operatorSettings.value })
37
+ .from(operatorSettings)
38
+ .where(eq(operatorSettings.key, key))
39
+ .limit(1);
40
+ return row ? (row.value as T) : null;
41
+ }
42
+
43
+ /** Upsert one operator setting (create and update are the same write). */
44
+ export async function putOperatorSetting(
45
+ db: Database,
46
+ key: string,
47
+ value: unknown,
48
+ ): Promise<void> {
49
+ await db
50
+ .insert(operatorSettings)
51
+ .values({ key, value })
52
+ .onConflictDoUpdate({
53
+ target: operatorSettings.key,
54
+ set: { value, updatedAt: new Date() },
55
+ });
56
+ }
57
+
58
+ /**
59
+ * Remove one operator setting — "clear the override, fall back to env".
60
+ * Returns whether a row was actually deleted (idempotent either way).
61
+ */
62
+ export async function deleteOperatorSetting(
63
+ db: Database,
64
+ key: string,
65
+ ): Promise<boolean> {
66
+ const deleted = await db
67
+ .delete(operatorSettings)
68
+ .where(eq(operatorSettings.key, key))
69
+ .returning({ key: operatorSettings.key });
70
+ return deleted.length > 0;
71
+ }