@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
@@ -25,7 +25,16 @@ import {
25
25
  import type { AppEnv } from "../../app.js";
26
26
  import { buildJourneyGraph } from "../../journeys/graph/build-graph.js";
27
27
  import { ingestEvent } from "../../lib/ingestion.js";
28
- import { computeLift } from "../../lib/lift-stats.js";
28
+ import {
29
+ computeJourneyLift,
30
+ computeLiftValues,
31
+ } from "../../lib/journey-lift.js";
32
+ import {
33
+ cohortSchema,
34
+ type DefinitionSource,
35
+ definitionSourceSchema,
36
+ liftVerdictSchema,
37
+ } from "./impact-schemas.js";
29
38
 
30
39
  /**
31
40
  * Per-process cache of the built {@link JourneyGraph}. A journey's `runSource`
@@ -43,6 +52,16 @@ const journeySchema = z.object({
43
52
  event: z.string(),
44
53
  }),
45
54
  entryLimit: z.enum(["once", "once_per_period", "unlimited"]),
55
+ /** Display-only author label (JourneyMeta.version) of the CURRENT
56
+ * deployed definition. */
57
+ version: z.string().optional(),
58
+ /** Engine-computed content fingerprint (12 hex) of the CURRENT deployed
59
+ * definition — what a fresh enrollment would stamp. Treat a NEW hash as
60
+ * "possible new version": toolchain bumps can fork it (D1). */
61
+ versionHash: z.string().optional(),
62
+ /** Conversion definition id (JourneyMeta.goal) — boot-validated; the
63
+ * /lift + /impact readouts default to it. */
64
+ goal: z.string().optional(),
46
65
  counts: z.object({
47
66
  active: z.number(),
48
67
  waiting: z.number(),
@@ -64,6 +83,10 @@ export const stateSchema = z.object({
64
83
  currentNodeId: z.string(),
65
84
  status: z.string(),
66
85
  hatchetRunId: z.string().nullable(),
86
+ /** Impact experiments (D1): definition fingerprint + label stamped at
87
+ * this row's INSERT. Null = pre-versioning ("unversioned") row. */
88
+ journeyVersionHash: z.string().nullable(),
89
+ journeyVersionLabel: z.string().nullable(),
67
90
  context: z.record(z.string(), z.unknown()),
68
91
  errorMessage: z.string().nullable(),
69
92
  entryCount: z.number(),
@@ -485,19 +508,12 @@ const graphRoute = createRoute({
485
508
  * Holdout lift (impact plan §4.2) — the ONLY surface allowed causal
486
509
  * language. Treatment = entered enrollments in the window; control =
487
510
  * held_out diversions (§4.1). Outcome = the contact fired ≥1 conversion
488
- * AFTER their state row was created. Beta-binomial win probability with a
489
- * suppression floor and a loud small-sample flag (lib/lift-stats.ts).
511
+ * AFTER their state row was created. Cohort math + verdict live in the
512
+ * shared computeJourneyLift/computeLiftValues helpers (lib/journey-lift.ts
513
+ * — also the engine of the phase-2b /impact route and the 3b digest);
514
+ * this route merges the per-currency values into the cohorts to keep its
515
+ * original wire shape.
490
516
  */
491
- const liftCohortSchema = z.object({
492
- contacts: z.number(),
493
- converters: z.number(),
494
- rate: z.number(),
495
- /** Qualifying conversion value per currency (full, not fractional). */
496
- value: z.array(
497
- z.object({ currency: z.string().nullable(), value: z.number() }),
498
- ),
499
- });
500
-
501
517
  const liftRoute = createRoute({
502
518
  method: "get",
503
519
  path: "/{id}/lift",
@@ -507,7 +523,8 @@ const liftRoute = createRoute({
507
523
  params: z.object({ id: z.string() }),
508
524
  query: z.object({
509
525
  days: z.coerce.number().min(1).max(365).default(90),
510
- /** Scope the outcome to one conversion point; default any. */
526
+ /** Scope the outcome to one conversion point. Default: the
527
+ * journey's meta.goal; else any conversion. */
511
528
  definitionId: z.string().optional(),
512
529
  }),
513
530
  },
@@ -518,14 +535,16 @@ const liftRoute = createRoute({
518
535
  schema: z.object({
519
536
  journeyId: z.string(),
520
537
  days: z.number(),
538
+ /** The EFFECTIVE definition scoping the outcome (query param,
539
+ * else the journey's meta.goal); null = any conversion. */
521
540
  definitionId: z.string().nullable(),
522
- treatment: liftCohortSchema,
523
- control: liftCohortSchema,
524
- liftPercent: z.number().nullable(),
525
- /** Null when suppressed (combined conversions < 10). */
526
- winProbability: z.number().nullable(),
527
- suppressed: z.boolean(),
528
- smallSample: z.boolean(),
541
+ /** Where the effective definitionId came from — the single
542
+ * source enum shared with /impact (phase 2b) and the Studio
543
+ * mirror (phase 3a). */
544
+ definitionSource: definitionSourceSchema,
545
+ treatment: cohortSchema,
546
+ control: cohortSchema,
547
+ ...liftVerdictSchema.shape,
529
548
  }),
530
549
  },
531
550
  },
@@ -587,6 +606,9 @@ export const journeysRouter = new OpenAPIHono<AppEnv>()
587
606
  enabled: effectiveEnabled,
588
607
  trigger: { event: j.trigger.event },
589
608
  entryLimit: j.entryLimit,
609
+ version: j.version,
610
+ versionHash: j.versionHash,
611
+ goal: j.goal,
590
612
  counts: countsMap.get(j.id) ?? { ...emptyCounts },
591
613
  };
592
614
  });
@@ -656,6 +678,9 @@ export const journeysRouter = new OpenAPIHono<AppEnv>()
656
678
  where: meta.trigger.where as Record<string, unknown>[] | undefined,
657
679
  },
658
680
  entryLimit: meta.entryLimit,
681
+ version: meta.version,
682
+ versionHash: meta.versionHash,
683
+ goal: meta.goal,
659
684
  exitOn: meta.exitOn?.map((e) => ({
660
685
  event: e.event,
661
686
  where: e.where as Record<string, unknown>[] | undefined,
@@ -1112,94 +1137,39 @@ export const journeysRouter = new OpenAPIHono<AppEnv>()
1112
1137
  );
1113
1138
  })
1114
1139
  .openapi(liftRoute, async (c) => {
1115
- const { db } = c.get("container");
1140
+ const { db, registry } = c.get("container");
1116
1141
  const { id } = c.req.valid("param");
1117
- const { days, definitionId } = c.req.valid("query");
1118
- const since = new Date(
1119
- Date.now() - days * 24 * 60 * 60 * 1000,
1120
- ).toISOString();
1121
- const sinceTs = sql`${since}::timestamptz`;
1122
-
1123
- // Outcome: the contact fired ≥1 qualifying conversion AFTER their state
1124
- // row was created (post-assignment — the intent-to-treat clock).
1125
- const definitionSql = definitionId
1126
- ? sql` and c.definition_id = ${definitionId}`
1127
- : sql``;
1128
- const convertedSql = sql`exists (
1129
- select 1 from conversions c
1130
- where c.user_key = ${journeyStates.userId}
1131
- and c.occurred_at >= ${journeyStates.createdAt}${definitionSql}
1132
- )`;
1133
-
1134
- const cohort = async (control: boolean) => {
1135
- const statusFilter = control
1136
- ? eq(journeyStates.status, "held_out")
1137
- : sql`${journeyStates.status} != 'held_out'`;
1138
- const [row] = await db
1139
- .select({
1140
- contacts: sql<number>`count(distinct ${journeyStates.userId})::int`,
1141
- converters: sql<number>`(count(distinct ${journeyStates.userId}) filter (where ${convertedSql}))::int`,
1142
- })
1143
- .from(journeyStates)
1144
- .where(
1145
- and(
1146
- eq(journeyStates.journeyId, id),
1147
- gteCreated(sinceTs),
1148
- statusFilter,
1149
- ),
1150
- );
1151
- // Full qualifying conversion value per currency (secondary read-out —
1152
- // the rate is the primary lift instrument).
1153
- const valueRows = await db.execute<{
1154
- currency: string | null;
1155
- value: number;
1156
- }>(sql`
1157
- select c.currency, coalesce(sum(c.value), 0)::float8 as value
1158
- from conversions c
1159
- where c.value is not null
1160
- and exists (
1161
- select 1 from journey_states js
1162
- where js.journey_id = ${id}
1163
- and js.created_at >= ${sinceTs}
1164
- and ${control ? sql`js.status = 'held_out'` : sql`js.status != 'held_out'`}
1165
- and js.user_id = c.user_key
1166
- and c.occurred_at >= js.created_at
1167
- )${definitionId ? sql` and c.definition_id = ${definitionId}` : sql``}
1168
- group by c.currency
1169
- `);
1170
- const contacts = Number(row?.contacts ?? 0);
1171
- const converters = row?.converters ?? 0;
1172
- return {
1173
- contacts,
1174
- converters,
1175
- rate: contacts > 0 ? converters / contacts : 0,
1176
- value: [...valueRows].map((r) => ({
1177
- currency: r.currency,
1178
- value: Number(r.value),
1179
- })),
1180
- };
1181
- };
1182
-
1183
- const [treatment, control] = await Promise.all([
1184
- cohort(false),
1185
- cohort(true),
1142
+ const { days, definitionId: queryDefinitionId } = c.req.valid("query");
1143
+ const since = new Date(Date.now() - days * 24 * 60 * 60 * 1000);
1144
+
1145
+ // definitionId resolution: explicit query param > journey meta.goal >
1146
+ // any conversion. registry.get(id) is undefined for (a) deleted/renamed
1147
+ // journeys with historical states and (b) DEFINED journeys excluded by
1148
+ // the ENABLED_JOURNEYS csv — both keep the pre-goal "any" behavior and
1149
+ // report source "none". The route still never 404s.
1150
+ const goal = registry.get(id)?.goal;
1151
+ const definitionId = queryDefinitionId ?? goal;
1152
+ const definitionSource: DefinitionSource = queryDefinitionId
1153
+ ? "query"
1154
+ : goal
1155
+ ? "goal"
1156
+ : "none";
1157
+
1158
+ const [result, values] = await Promise.all([
1159
+ computeJourneyLift({ db, journeyId: id, since, definitionId }),
1160
+ computeLiftValues({ db, journeyId: id, since, definitionId }),
1186
1161
  ]);
1187
- const verdict = computeLift({ treatment, control });
1188
1162
 
1189
1163
  return c.json(
1190
1164
  {
1191
1165
  journeyId: id,
1192
1166
  days,
1193
1167
  definitionId: definitionId ?? null,
1194
- treatment,
1195
- control,
1196
- ...verdict,
1168
+ definitionSource,
1169
+ treatment: { ...result.treatment, value: values.treatment },
1170
+ control: { ...result.control, value: values.control },
1171
+ ...result.verdict,
1197
1172
  },
1198
1173
  200,
1199
1174
  );
1200
1175
  });
1201
-
1202
- /** `created_at >= since` as a reusable fragment (lift cohort windows). */
1203
- function gteCreated(sinceTs: ReturnType<typeof sql>) {
1204
- return sql`${journeyStates.createdAt} >= ${sinceTs}`;
1205
- }
@@ -0,0 +1,145 @@
1
+ import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
2
+ import type { AppEnv } from "../../app.js";
3
+ import type { HogsendClient } from "../../container.js";
4
+ import {
5
+ deleteOperatorSetting,
6
+ FX_SETTINGS_KEY,
7
+ type FxSetting,
8
+ getOperatorSetting,
9
+ putOperatorSetting,
10
+ } from "../../lib/operator-settings.js";
11
+
12
+ /**
13
+ * Operator settings — the Studio-facing surface over `operator_settings`.
14
+ * Mounted at `/v1/admin/settings`, inheriting `requireAdmin` + `rateLimit` +
15
+ * `auditMiddleware` from the admin router root.
16
+ *
17
+ * Today: `/fx`, the base-currency choice behind the FX lens. The precedence
18
+ * the response makes explicit (mirroring the container's resolver):
19
+ *
20
+ * - a setting ROW with a currency → that currency ("set here")
21
+ * - a setting ROW with null → lens explicitly OFF (beats env)
22
+ * - NO row → env `BASE_CURRENCY`, else off
23
+ *
24
+ * PUT writes/updates the row (a null body value = the explicit off); DELETE
25
+ * removes the row entirely, falling back to env. Every mutation returns the
26
+ * same full state as GET so the Studio card never needs a second fetch.
27
+ */
28
+
29
+ const fxStateSchema = z.object({
30
+ // The stored operator choice, or null when no row exists.
31
+ setting: z.object({ baseCurrency: z.string().nullable() }).nullable(),
32
+ // The env bootstrap default (`BASE_CURRENCY`), shown so the card can say
33
+ // where the effective value comes from — and name the static sheet's
34
+ // quoted base when it can't serve the effective one.
35
+ env: z.object({ baseCurrency: z.string().nullable() }),
36
+ // What the lens actually resolves right now (setting ?? env; null = off).
37
+ effective: z.object({ baseCurrency: z.string().nullable() }),
38
+ // The resolved rate source probed against the effective base — null when
39
+ // no provider is configured at all. `servesEffectiveBase: false` with a
40
+ // base set = converted figures will NOT appear (e.g. a USD-quoted static
41
+ // sheet asked for EUR — the honesty rule).
42
+ provider: z
43
+ .object({
44
+ id: z.string(),
45
+ asOf: z.string().nullable(),
46
+ servesEffectiveBase: z.boolean(),
47
+ })
48
+ .nullable(),
49
+ });
50
+
51
+ const putFxBodySchema = z.object({
52
+ baseCurrency: z
53
+ .string()
54
+ .regex(/^[A-Za-z]{3}$/, "must be a 3-letter ISO-4217 code")
55
+ .transform((v) => v.toUpperCase())
56
+ .nullable(),
57
+ });
58
+
59
+ const getFxRoute = createRoute({
60
+ method: "get",
61
+ path: "/fx",
62
+ tags: ["Admin — Settings"],
63
+ summary: "Get the base-currency (FX lens) setting",
64
+ responses: {
65
+ 200: {
66
+ content: { "application/json": { schema: fxStateSchema } },
67
+ description:
68
+ "The stored setting, the env default, the effective base, and the rate source probed against it",
69
+ },
70
+ },
71
+ });
72
+
73
+ const putFxRoute = createRoute({
74
+ method: "put",
75
+ path: "/fx",
76
+ tags: ["Admin — Settings"],
77
+ summary: "Set (or explicitly turn off) the base currency",
78
+ description:
79
+ "Upserts the operator's base-currency choice. `baseCurrency: null` is the EXPLICIT off — it beats an env BASE_CURRENCY. To fall back to env instead, DELETE the setting.",
80
+ request: {
81
+ body: {
82
+ content: { "application/json": { schema: putFxBodySchema } },
83
+ },
84
+ },
85
+ responses: {
86
+ 200: {
87
+ content: { "application/json": { schema: fxStateSchema } },
88
+ description: "The updated state (same shape as GET)",
89
+ },
90
+ },
91
+ });
92
+
93
+ const deleteFxRoute = createRoute({
94
+ method: "delete",
95
+ path: "/fx",
96
+ tags: ["Admin — Settings"],
97
+ summary: "Clear the base-currency setting (fall back to env)",
98
+ responses: {
99
+ 200: {
100
+ content: { "application/json": { schema: fxStateSchema } },
101
+ description:
102
+ "The state after removing the override (idempotent — 200 even when no row existed)",
103
+ },
104
+ },
105
+ });
106
+
107
+ /** Assemble the full GET-shape state the card needs to be honest. */
108
+ async function fxStateOf(container: HogsendClient) {
109
+ const setting = await getOperatorSetting<FxSetting>(
110
+ container.db,
111
+ FX_SETTINGS_KEY,
112
+ );
113
+ const effective = await container.fx.getBaseCurrency();
114
+ // The probe IS getRatesToBase(): it resolves the same effective base per
115
+ // call, so a null sheet with a base set means the source cannot serve it.
116
+ const sheet = effective ? await container.fx.getRatesToBase() : null;
117
+ return {
118
+ setting,
119
+ env: { baseCurrency: container.env.BASE_CURRENCY ?? null },
120
+ effective: { baseCurrency: effective },
121
+ provider: container.fx.providerId
122
+ ? {
123
+ id: container.fx.providerId,
124
+ asOf: sheet?.asOf ?? null,
125
+ servesEffectiveBase: sheet !== null,
126
+ }
127
+ : null,
128
+ };
129
+ }
130
+
131
+ export const settingsRouter = new OpenAPIHono<AppEnv>()
132
+ .openapi(getFxRoute, async (c) => {
133
+ return c.json(await fxStateOf(c.get("container")), 200);
134
+ })
135
+ .openapi(putFxRoute, async (c) => {
136
+ const container = c.get("container");
137
+ const { baseCurrency } = c.req.valid("json");
138
+ await putOperatorSetting(container.db, FX_SETTINGS_KEY, { baseCurrency });
139
+ return c.json(await fxStateOf(container), 200);
140
+ })
141
+ .openapi(deleteFxRoute, async (c) => {
142
+ const container = c.get("container");
143
+ await deleteOperatorSetting(container.db, FX_SETTINGS_KEY);
144
+ return c.json(await fxStateOf(container), 200);
145
+ });
@@ -0,0 +1,259 @@
1
+ import { CANONICAL_STAGES, flagTargetingSchema } from "@hogsend/core";
2
+ import { campaigns, contacts } from "@hogsend/db";
3
+ import { getTemplateNames } from "@hogsend/email";
4
+ import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
5
+ import { desc, isNull, sql } from "drizzle-orm";
6
+ import type { AppEnv } from "../../app.js";
7
+ import {
8
+ eventNameEntrySchema,
9
+ listEventNameVocabulary,
10
+ } from "../../lib/event-names.js";
11
+ import { evaluateTargeting, loadTargetingSnapshot } from "../../lib/flags.js";
12
+
13
+ /**
14
+ * Reusable targeting-builder catalog + a live match-count estimator. The
15
+ * catalog is the raw material a Studio condition builder needs to compose EVERY
16
+ * targeting leaf — the distinct contact-property keys and operator vocabulary
17
+ * (property leaves) plus the id/name lists a builder picks from for the richer
18
+ * snapshot leaves (buckets, journeys, deal stages) and the scan leaves (event
19
+ * names) and campaigns. Named generically (`/targeting/catalog`, not
20
+ * `/flags/catalog`) because the same vocabulary feeds any targeting UI.
21
+ * `POST /targeting/count` estimates how many live contacts a targeting tree
22
+ * matches, over a bounded sample. Both inherit the admin router's
23
+ * `requireAdmin` guard.
24
+ */
25
+
26
+ /** Cap on distinct property keys returned — a builder combobox, not an export. */
27
+ const MAX_PROPERTY_KEYS = 200;
28
+
29
+ /** Cap on event names returned in the catalog (observed + declared vocabulary). */
30
+ const MAX_EVENT_NAMES = 200;
31
+
32
+ /**
33
+ * Cap on contacts SAMPLED for key discovery. The catalog only needs the shape
34
+ * of the property vocabulary, not every key that ever existed, so we bound the
35
+ * SCAN (not just the output): without this, `distinct` + `order by` must expand
36
+ * every live contact's property object before `limit` can trim, i.e. a full
37
+ * sequential scan on every fetch. Sampling the most-recently-updated slice
38
+ * keeps the work bounded and the vocabulary current.
39
+ */
40
+ const MAX_SAMPLED_CONTACTS = 2000;
41
+
42
+ /**
43
+ * Cap on contacts SAMPLED for a match-count estimate. Mirrors the catalog's
44
+ * ~2000 most-recently-updated sampling so the estimate is bounded regardless of
45
+ * table size — each sampled contact costs one targeting snapshot (a fixed set
46
+ * of indexed queries), so this endpoint is O(sample), never O(all contacts).
47
+ */
48
+ const MAX_COUNT_SAMPLE = 2000;
49
+
50
+ /**
51
+ * How many sampled contacts to evaluate concurrently. Each evaluation loads a
52
+ * snapshot (a few indexed queries) and, in server mode, may run scan leaves; a
53
+ * small fixed fan-out bounds in-flight DB work instead of firing all
54
+ * `MAX_COUNT_SAMPLE` at once.
55
+ */
56
+ const COUNT_CONCURRENCY = 25;
57
+
58
+ /**
59
+ * The 9 property operators (see `PropertyCondition`) with human labels. `unary`
60
+ * operators (`exists`/`not_exists`) take no comparison value, so the builder
61
+ * hides the value input for them.
62
+ */
63
+ const OPERATORS: Array<{ value: string; label: string; unary: boolean }> = [
64
+ { value: "eq", label: "equals", unary: false },
65
+ { value: "neq", label: "does not equal", unary: false },
66
+ { value: "gt", label: "greater than", unary: false },
67
+ { value: "gte", label: "greater than or equal to", unary: false },
68
+ { value: "lt", label: "less than", unary: false },
69
+ { value: "lte", label: "less than or equal to", unary: false },
70
+ { value: "contains", label: "contains", unary: false },
71
+ { value: "exists", label: "is set", unary: true },
72
+ { value: "not_exists", label: "is not set", unary: true },
73
+ ];
74
+
75
+ /**
76
+ * The deal-stage vocabulary a `deal` leaf's `stage` predicate picks from: the
77
+ * deployment's canonical ladder plus the reserved terminal `"lost"`.
78
+ */
79
+ const DEAL_STAGES: string[] = [...CANONICAL_STAGES, "lost"];
80
+
81
+ const idNameSchema = z.object({ id: z.string(), name: z.string() });
82
+
83
+ const catalogSchema = z.object({
84
+ properties: z.array(z.string()),
85
+ operators: z.array(
86
+ z.object({
87
+ value: z.string(),
88
+ label: z.string(),
89
+ unary: z.boolean(),
90
+ }),
91
+ ),
92
+ buckets: z.array(idNameSchema),
93
+ journeys: z.array(idNameSchema),
94
+ dealStages: z.array(z.string()),
95
+ events: z.array(eventNameEntrySchema),
96
+ campaigns: z.array(idNameSchema),
97
+ templates: z.array(z.string()),
98
+ });
99
+
100
+ const catalogRoute = createRoute({
101
+ method: "get",
102
+ path: "/catalog",
103
+ tags: ["Admin — Targeting"],
104
+ summary: "Targeting builder catalog (every leaf's vocabulary)",
105
+ responses: {
106
+ 200: {
107
+ content: { "application/json": { schema: catalogSchema } },
108
+ description:
109
+ "Property keys + operators, plus buckets, journeys, deal stages, event names, and campaigns",
110
+ },
111
+ },
112
+ });
113
+
114
+ const countBodySchema = z.object({
115
+ /** One condition set's targeting tree (or the legacy bare property array). */
116
+ targeting: flagTargetingSchema,
117
+ });
118
+
119
+ const countResponseSchema = z.object({
120
+ /** Sampled contacts the tree matched. */
121
+ matched: z.number(),
122
+ /** Sampled contacts evaluated (≤ MAX_COUNT_SAMPLE, ≤ live contacts). */
123
+ sampled: z.number(),
124
+ /**
125
+ * Honest estimate of matching LIVE contacts: `matched/sampled` scaled by the
126
+ * live-contact count. Exact when the sample covers every live contact.
127
+ */
128
+ estimatedTotal: z.number(),
129
+ });
130
+
131
+ const countRoute = createRoute({
132
+ method: "post",
133
+ path: "/count",
134
+ tags: ["Admin — Targeting"],
135
+ summary: "Estimate how many live contacts a targeting tree matches",
136
+ request: {
137
+ body: {
138
+ content: { "application/json": { schema: countBodySchema } },
139
+ },
140
+ },
141
+ responses: {
142
+ 200: {
143
+ content: { "application/json": { schema: countResponseSchema } },
144
+ description: "Sampled match count + scaled estimate",
145
+ },
146
+ },
147
+ });
148
+
149
+ export const targetingRouter = new OpenAPIHono<AppEnv>()
150
+ .openapi(catalogRoute, async (c) => {
151
+ const { db, registry, bucketRegistry, templates } = c.get("container");
152
+
153
+ // Distinct top-level property keys across a bounded SAMPLE of the most
154
+ // recently-updated live contacts, sorted + capped. Sampling first (inner
155
+ // limit) keeps `jsonb_object_keys` — which fans each contact's properties
156
+ // object out to one row per key — from expanding the whole table on every
157
+ // fetch. `coalesce` guards NULL/absent property maps. The property scan and
158
+ // the event/campaign lookups are independent, so they go out together.
159
+ const [propertyRows, events, campaignRows] = await Promise.all([
160
+ db.execute<{ key: string }>(sql`
161
+ select distinct key
162
+ from (
163
+ select properties
164
+ from contacts
165
+ where deleted_at is null
166
+ order by updated_at desc
167
+ limit ${MAX_SAMPLED_CONTACTS}
168
+ ) as sampled,
169
+ jsonb_object_keys(coalesce(properties, '{}'::jsonb)) as key
170
+ order by key
171
+ limit ${MAX_PROPERTY_KEYS}
172
+ `),
173
+ listEventNameVocabulary({ db, registry, limit: MAX_EVENT_NAMES }),
174
+ db
175
+ .select({ id: campaigns.id, name: campaigns.name })
176
+ .from(campaigns)
177
+ .orderBy(desc(campaigns.createdAt))
178
+ .limit(MAX_PROPERTY_KEYS),
179
+ ]);
180
+
181
+ const properties = Array.from(propertyRows, (r) => r.key);
182
+ const buckets = bucketRegistry
183
+ .getAll()
184
+ .map((b) => ({ id: b.id, name: b.name }));
185
+ const journeys = registry.getAll().map((j) => ({ id: j.id, name: j.name }));
186
+
187
+ return c.json(
188
+ {
189
+ properties,
190
+ operators: OPERATORS,
191
+ buckets,
192
+ journeys,
193
+ dealStages: DEAL_STAGES,
194
+ events: events.events,
195
+ campaigns: campaignRows,
196
+ templates: getTemplateNames(templates),
197
+ },
198
+ 200,
199
+ );
200
+ })
201
+ .openapi(countRoute, async (c) => {
202
+ const { db } = c.get("container");
203
+ const { targeting } = c.req.valid("json");
204
+
205
+ // Bounded, most-recently-updated sample + the live-contact total for
206
+ // scaling. `id` is the trusted uuid for property/deal reads; the logical
207
+ // `contactKey` (external_id ?? anonymous_id ?? id) keys the
208
+ // bucket/journey/event reads — the same identity split the flag readers use.
209
+ const [sample, totalRows] = await Promise.all([
210
+ db
211
+ .select({
212
+ id: contacts.id,
213
+ externalId: contacts.externalId,
214
+ anonymousId: contacts.anonymousId,
215
+ })
216
+ .from(contacts)
217
+ .where(isNull(contacts.deletedAt))
218
+ .orderBy(desc(contacts.updatedAt))
219
+ .limit(MAX_COUNT_SAMPLE),
220
+ db
221
+ .select({ total: sql<number>`count(*)`.mapWith(Number) })
222
+ .from(contacts)
223
+ .where(isNull(contacts.deletedAt)),
224
+ ]);
225
+
226
+ const liveTotal = totalRows[0]?.total ?? 0;
227
+
228
+ const evaluateOne = async (row: (typeof sample)[number]) => {
229
+ const contactKey = row.externalId ?? row.anonymousId ?? row.id;
230
+ const snapshot = await loadTargetingSnapshot({
231
+ db,
232
+ contactKey,
233
+ contactId: row.id,
234
+ });
235
+ // Server mode so bucket/journey/deal AND the scan leaves
236
+ // (event/email_engagement) all resolve for the estimate.
237
+ return evaluateTargeting(targeting, {
238
+ snapshot,
239
+ mode: "server",
240
+ db,
241
+ userId: contactKey,
242
+ });
243
+ };
244
+
245
+ // Bounded fan-out: evaluate in fixed-size chunks so at most
246
+ // COUNT_CONCURRENCY snapshots are loading at once.
247
+ let matched = 0;
248
+ for (let i = 0; i < sample.length; i += COUNT_CONCURRENCY) {
249
+ const chunk = sample.slice(i, i + COUNT_CONCURRENCY);
250
+ const results = await Promise.all(chunk.map(evaluateOne));
251
+ for (const hit of results) if (hit) matched += 1;
252
+ }
253
+
254
+ const sampled = sample.length;
255
+ const estimatedTotal =
256
+ sampled === 0 ? 0 : Math.round((matched / sampled) * liveTotal);
257
+
258
+ return c.json({ matched, sampled, estimatedTotal }, 200);
259
+ });
@@ -31,6 +31,14 @@ const eventRequestSchema = z.object({
31
31
  .regex(/^[A-Za-z]{3}$/)
32
32
  .optional(),
33
33
  lists: z.record(z.string(), z.boolean()).optional(),
34
+ // groupType → groupKey association map (e.g. `{ company: "acme.com" }`). The
35
+ // event is recorded against each group (`user_events.groups`), its membership
36
+ // is ensured, and the map is forwarded to analytics as `$groups`. This is
37
+ // ASSOCIATION-ONLY: the ingest path writes NO group properties, so a
38
+ // publishable (pk_) key can reference a group key here but can never write
39
+ // group properties or read groups (those live on the secret-only
40
+ // `/v1/groups` router).
41
+ groups: z.record(z.string().min(1), z.string().min(1)).optional(),
34
42
  idempotencyKey: z.string().optional(),
35
43
  timestamp: z.string().datetime().optional(),
36
44
  // Publishable-key identity assertion (§Phase 1). A pk_ key is anon-only
@@ -133,6 +141,9 @@ export const eventsRouter = new OpenAPIHono<AppEnv>().openapi(
133
141
  contactProperties: body.contactProperties,
134
142
  value: body.value,
135
143
  currency: body.currency,
144
+ // groupType→groupKey association (association-only; no property write).
145
+ // Forwarded as `$groups` on the mirrored analytics capture.
146
+ groups: body.groups,
136
147
  idempotencyKey,
137
148
  // §2.5: caller-supplied event time (backfill/replay). The validated
138
149
  // ISO string is coerced to a Date inside ingestEvent.