@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
@@ -9,12 +9,19 @@
9
9
  import { type CampaignStep, durationToMs } from "@hogsend/core";
10
10
  import { campaigns, emailSends } from "@hogsend/db";
11
11
  import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
12
- import { and, count, desc, eq, inArray, like, max, sql } from "drizzle-orm";
13
- import type { AppEnv } from "../../app.js";
14
12
  import {
15
- campaignSendKeyPattern,
16
- campaignStepSendKeyPattern,
17
- } from "../../lib/campaign-send-key.js";
13
+ and,
14
+ count,
15
+ desc,
16
+ eq,
17
+ inArray,
18
+ like,
19
+ max,
20
+ type SQL,
21
+ sql,
22
+ } from "drizzle-orm";
23
+ import type { AppEnv } from "../../app.js";
24
+ import { campaignStepSendKeyPattern } from "../../lib/campaign-send-key.js";
18
25
  import { errorSchema } from "../../lib/schemas.js";
19
26
  import { campaignSchema, serializeCampaign } from "../campaigns/index.js";
20
27
 
@@ -68,9 +75,12 @@ const getRouteDef = createRoute({
68
75
  /**
69
76
  * One row of the per-step breakdown for a multi-step campaign: the step's
70
77
  * identity (`kind` + `templateKey` for send steps, `durationMs` for wait
71
- * steps) plus the same engagement aggregate as the campaign level, scoped to
72
- * the step's `campaign:<id>:<step>:%` idempotency-key pattern. Wait steps
73
- * deliver nothing, so their counts are zeroed.
78
+ * steps) plus the same engagement aggregate as the campaign level. The step
79
+ * number only lives in the `campaign:<id>:<step>:%` idempotency-key format,
80
+ * so step rows anchor on that pattern (scoped to the campaign_id FK first) —
81
+ * which also means suppressed sends (no key) can never attribute to a step,
82
+ * so step rows carry no `skipped` (it lives at the campaign level only).
83
+ * Wait steps deliver nothing, so their counts are zeroed.
74
84
  */
75
85
  const campaignStepStatsSchema = z.object({
76
86
  index: z.number(),
@@ -89,13 +99,16 @@ const campaignStepStatsSchema = z.object({
89
99
 
90
100
  /**
91
101
  * Post-dispatch engagement for one campaign, aggregated from the `email_sends`
92
- * rows the blast wrote (attributed via the `campaign:<id>:…` idempotency
93
- * key — there is no campaign FK on email_sends). Complements the counters on
94
- * the campaign row itself: the row knows sent/skipped/failed at dispatch time,
95
- * this knows what happened to the mail AFTERWARDS (delivered/opened/clicked/
96
- * bounced/complained via first-party tracking + provider webhooks). Multi-step
97
- * campaigns additionally carry `steps` — one entry per step, in step order
98
- * (the campaign-level numbers are a superset of every step's).
102
+ * rows the blast wrote — attributed via the indexed `campaign_id` column
103
+ * (stamped at send time, backfilled from legacy idempotency keys by migration
104
+ * 0051), NOT by parsing the key: suppressed sends write no key at all, so a
105
+ * key scan can never see them. Complements the counters on the campaign row
106
+ * itself: the row knows sent/skipped/failed at dispatch time, this knows what
107
+ * happened to the mail AFTERWARDS (delivered/opened/clicked/bounced/complained
108
+ * via first-party tracking + provider webhooks) plus the policy-suppressed
109
+ * rows (status `suppressed`) as `skipped`. Multi-step campaigns additionally
110
+ * carry `steps` — one entry per step, in step order (the campaign-level
111
+ * numbers are a superset of every step's).
99
112
  */
100
113
  const campaignStatsSchema = z.object({
101
114
  sends: z.number(),
@@ -105,6 +118,7 @@ const campaignStatsSchema = z.object({
105
118
  bounced: z.number(),
106
119
  complained: z.number(),
107
120
  failed: z.number(),
121
+ skipped: z.number(),
108
122
  lastSentAt: z.string().nullable(),
109
123
  steps: z.array(campaignStepStatsSchema).optional(),
110
124
  });
@@ -213,15 +227,22 @@ export const adminCampaignsRouter = new OpenAPIHono<AppEnv>()
213
227
  }
214
228
 
215
229
  // count(column) counts non-NULL values, so each engagement timestamp
216
- // doubles as its own tally. No campaign FK on email_sends — the LIKE on the
217
- // deterministic idempotency key is the attribution (admin-plane traffic, so
218
- // the prefix scan is acceptable without a dedicated index). Shared by the
230
+ // doubles as its own tally. Attribution is the indexed `campaign_id`
231
+ // column (stamped on every campaign row including suppressed sends;
232
+ // legacy rows backfilled by migration 0051). The status column carries
233
+ // the dispatch verdict: policy-gated rows are `suppressed` (the `skipped`
234
+ // bucket), everything else was a dispatch attempt (`sends`), and `failed`
235
+ // means failed AT dispatch — a provider failure releases its idempotency
236
+ // key, so key-nullness deliberately plays no part here. Shared by the
219
237
  // campaign-level aggregate and the per-step breakdown.
220
- const aggregate = async (pattern: string) => {
238
+ const aggregate = async (where: SQL | undefined) => {
221
239
  const agg = (
222
240
  await db
223
241
  .select({
224
- sends: count(),
242
+ sends:
243
+ sql<number>`count(*) filter (where ${emailSends.status} <> 'suppressed')`.mapWith(
244
+ Number,
245
+ ),
225
246
  delivered: count(emailSends.deliveredAt),
226
247
  opened: count(emailSends.openedAt),
227
248
  clicked: count(emailSends.clickedAt),
@@ -231,10 +252,14 @@ export const adminCampaignsRouter = new OpenAPIHono<AppEnv>()
231
252
  sql<number>`count(*) filter (where ${emailSends.status} = 'failed')`.mapWith(
232
253
  Number,
233
254
  ),
255
+ skipped:
256
+ sql<number>`count(*) filter (where ${emailSends.status} = 'suppressed')`.mapWith(
257
+ Number,
258
+ ),
234
259
  lastSentAt: max(emailSends.sentAt),
235
260
  })
236
261
  .from(emailSends)
237
- .where(like(emailSends.idempotencyKey, pattern))
262
+ .where(where)
238
263
  )[0];
239
264
  return {
240
265
  sends: agg?.sends ?? 0,
@@ -244,21 +269,23 @@ export const adminCampaignsRouter = new OpenAPIHono<AppEnv>()
244
269
  bounced: agg?.bounced ?? 0,
245
270
  complained: agg?.complained ?? 0,
246
271
  failed: agg?.failed ?? 0,
272
+ skipped: agg?.skipped ?? 0,
247
273
  lastSentAt: agg?.lastSentAt ? agg.lastSentAt.toISOString() : null,
248
274
  };
249
275
  };
250
276
 
251
- // The campaign-level pattern (`campaign:<id>:%`) is a superset of both
252
- // key formats, so these numbers are format-agnostic and unchanged for
253
- // legacy single-send rows.
254
- const campaignLevel = await aggregate(campaignSendKeyPattern(id));
277
+ // Campaign-level: the FK matches every row of both key formats AND the
278
+ // keyless suppressed rows, so these numbers are format-agnostic and
279
+ // unchanged for legacy single-send rows.
280
+ const campaignLevel = await aggregate(eq(emailSends.campaignId, id));
255
281
 
256
282
  // Per-step breakdown, only when the row carries a steps blob (NULL =
257
- // legacy single-send — no `steps` in the response). Send-step aggregates
258
- // filter on the step-scoped pattern (`campaign:<id>:<k>:%` — multi-step
259
- // campaigns key ALL steps including 0 that way); wait steps deliver
260
- // nothing. One query per step is fine at the ≤10-step cap on the
261
- // admin plane.
283
+ // legacy single-send — no `steps` in the response). The step number only
284
+ // exists inside the key, so send-step aggregates still filter on the
285
+ // step-scoped pattern (`campaign:<id>:<k>:%` — multi-step campaigns key
286
+ // ALL steps including 0 that way), anchored on the indexed FK first; wait
287
+ // steps deliver nothing. The step queries are independent, so they run
288
+ // concurrently.
262
289
  const blob = row.steps;
263
290
  if (!blob) {
264
291
  return c.json(campaignLevel, 200);
@@ -267,18 +294,30 @@ export const adminCampaignsRouter = new OpenAPIHono<AppEnv>()
267
294
  // db cannot import @hogsend/core, so the blob's elements are opaque
268
295
  // Record<string, unknown> there; the engine owns the narrowing.
269
296
  const defs = blob.steps as unknown as CampaignStep[];
270
- const steps: z.infer<typeof campaignStepStatsSchema>[] = [];
271
- for (const [index, step] of defs.entries()) {
272
- if (step.kind === "send") {
273
- steps.push({
274
- index,
275
- kind: step.kind,
276
- templateKey: step.template,
277
- durationMs: null,
278
- ...(await aggregate(campaignStepSendKeyPattern(id, index))),
279
- });
280
- } else {
281
- steps.push({
297
+ const steps: z.infer<typeof campaignStepStatsSchema>[] = await Promise.all(
298
+ defs.map(async (step, index) => {
299
+ if (step.kind === "send") {
300
+ // Suppressed rows write no key, so they can never match the
301
+ // step-scoped pattern — the always-zero `skipped` is dropped from
302
+ // step rows rather than reported as a dead field.
303
+ const { skipped: _campaignOnly, ...stepStats } = await aggregate(
304
+ and(
305
+ eq(emailSends.campaignId, id),
306
+ like(
307
+ emailSends.idempotencyKey,
308
+ campaignStepSendKeyPattern(id, index),
309
+ ),
310
+ ),
311
+ );
312
+ return {
313
+ index,
314
+ kind: step.kind,
315
+ templateKey: step.template,
316
+ durationMs: null,
317
+ ...stepStats,
318
+ };
319
+ }
320
+ return {
282
321
  index,
283
322
  kind: step.kind,
284
323
  templateKey: null,
@@ -291,9 +330,9 @@ export const adminCampaignsRouter = new OpenAPIHono<AppEnv>()
291
330
  complained: 0,
292
331
  failed: 0,
293
332
  lastSentAt: null,
294
- });
295
- }
296
- }
333
+ };
334
+ }),
335
+ );
297
336
 
298
337
  return c.json({ ...campaignLevel, steps }, 200);
299
338
  })
@@ -1,6 +1,11 @@
1
- import { contacts, emailPreferences } from "@hogsend/db";
1
+ import {
2
+ contacts,
3
+ emailPreferences,
4
+ groupMemberships,
5
+ groups,
6
+ } from "@hogsend/db";
2
7
  import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
3
- import { and, count, desc, eq, isNull, sql } from "drizzle-orm";
8
+ import { and, asc, count, desc, eq, isNull, sql } from "drizzle-orm";
4
9
  import type { AppEnv } from "../../app.js";
5
10
  import {
6
11
  contactSearchFilter,
@@ -49,6 +54,17 @@ const revenueSchema = z.object({
49
54
  lastValuedAt: z.string().nullable(),
50
55
  });
51
56
 
57
+ // The contact's live group memberships (`group_memberships` joined to `groups`),
58
+ // each linking to that group's Studio page. A contact is many-to-many with
59
+ // groups; soft-deleted groups are excluded.
60
+ const contactGroupSchema = z.object({
61
+ groupType: z.string(),
62
+ groupKey: z.string(),
63
+ displayName: z.string().nullable(),
64
+ role: z.string().nullable(),
65
+ joinedAt: z.string(),
66
+ });
67
+
52
68
  const listRoute = createRoute({
53
69
  method: "get",
54
70
  path: "/",
@@ -99,6 +115,7 @@ const getRoute = createRoute({
99
115
  contact: contactSchema,
100
116
  preferences: preferencesSchema,
101
117
  revenue: revenueSchema,
118
+ groups: z.array(contactGroupSchema),
102
119
  }),
103
120
  },
104
121
  },
@@ -301,7 +318,7 @@ export const contactsRouter = new OpenAPIHono<AppEnv>()
301
318
 
302
319
  // email_preferences.user_id uses external_id when present, else the contact
303
320
  // uuid as the deterministic fallback (risk 10 — email-only contacts).
304
- const [prefRows, revenue] = await Promise.all([
321
+ const [prefRows, revenue, groupRows] = await Promise.all([
305
322
  db
306
323
  .select()
307
324
  .from(emailPreferences)
@@ -313,12 +330,44 @@ export const contactsRouter = new OpenAPIHono<AppEnv>()
313
330
  db,
314
331
  key: contact.externalId ?? contact.anonymousId ?? contact.id,
315
332
  }),
333
+ // The contact's live group memberships (mirrors the admin groups router's
334
+ // join idiom): `group_memberships` → `groups`, live groups only, ordered
335
+ // by group type then most-recently-joined.
336
+ db
337
+ .select({
338
+ groupType: groups.groupType,
339
+ groupKey: groups.groupKey,
340
+ displayName: groups.displayName,
341
+ role: groupMemberships.role,
342
+ joinedAt: groupMemberships.joinedAt,
343
+ })
344
+ .from(groupMemberships)
345
+ .innerJoin(groups, eq(groupMemberships.groupId, groups.id))
346
+ .where(
347
+ and(
348
+ eq(groupMemberships.contactId, contact.id),
349
+ isNull(groups.deletedAt),
350
+ ),
351
+ )
352
+ .orderBy(asc(groups.groupType), desc(groupMemberships.joinedAt)),
316
353
  ]);
317
354
 
318
355
  const prefs = prefRows[0] ? serializePrefs(prefRows[0]) : null;
356
+ const groupsList = groupRows.map((r) => ({
357
+ groupType: r.groupType,
358
+ groupKey: r.groupKey,
359
+ displayName: r.displayName,
360
+ role: r.role,
361
+ joinedAt: r.joinedAt.toISOString(),
362
+ }));
319
363
 
320
364
  return c.json(
321
- { contact: serializeContact(contact), preferences: prefs, revenue },
365
+ {
366
+ contact: serializeContact(contact),
367
+ preferences: prefs,
368
+ revenue,
369
+ groups: groupsList,
370
+ },
322
371
  200,
323
372
  );
324
373
  })
@@ -4,7 +4,7 @@ import { and, asc, count, desc, eq, sql } from "drizzle-orm";
4
4
  import type { AppEnv } from "../../app.js";
5
5
 
6
6
  /**
7
- * Admin conversions API (docs/revenue-attribution-plan.md §5b.2) — fired
7
+ * Admin conversions API — fired
8
8
  * conversion points and their per-destination delivery state. Answers the
9
9
  * operator question "did the ad platform actually receive the sale?".
10
10
  */
@@ -103,6 +103,64 @@ const statsRoute = createRoute({
103
103
  },
104
104
  });
105
105
 
106
+ const timingSchema = z.object({
107
+ definitionId: z.string(),
108
+ /** What each subject is anchored on: a journey enrollment or an event. */
109
+ anchor: z.object({
110
+ type: z.enum(["journey", "event"]),
111
+ id: z.string(),
112
+ }),
113
+ days: z.number(),
114
+ /** Subjects anchored in the window (denominator). */
115
+ anchored: z.number(),
116
+ /** Subjects that fired the conversion at/after their anchor (numerator). */
117
+ converted: z.number(),
118
+ /** converted / anchored (0 when nobody was anchored). */
119
+ rate: z.number(),
120
+ /** How many converted within N days of the anchor (cumulative buckets). */
121
+ convertedWithin: z.object({
122
+ d1: z.number(),
123
+ d7: z.number(),
124
+ d14: z.number(),
125
+ d30: z.number(),
126
+ }),
127
+ /** Median days from anchor to first conversion among converters. */
128
+ medianDays: z.number().nullable(),
129
+ /** 90th-percentile days from anchor to first conversion among converters. */
130
+ p90Days: z.number().nullable(),
131
+ /**
132
+ * Always true — anchoring on an enrollment/event self-selects engaged
133
+ * contacts, so "how long after" is association, not causation. Holdouts
134
+ * are the causal instrument (mirrors the funnels report).
135
+ */
136
+ correlational: z.literal(true),
137
+ });
138
+
139
+ const timingRoute = createRoute({
140
+ method: "get",
141
+ path: "/timing",
142
+ tags: ["Admin"],
143
+ summary: "Time-to-conversion distribution after an anchor (correlational)",
144
+ request: {
145
+ query: z.object({
146
+ /** The conversion definition to measure the latency of. */
147
+ definitionId: z.string(),
148
+ /** Anchor each subject on a journey enrollment or an event. */
149
+ anchorType: z.enum(["journey", "event"]),
150
+ /** The journey id (anchorType=journey) or event name (anchorType=event). */
151
+ anchorId: z.string(),
152
+ days: z.coerce.number().min(1).max(365).default(90),
153
+ }),
154
+ },
155
+ responses: {
156
+ 200: {
157
+ content: { "application/json": { schema: timingSchema } },
158
+ description:
159
+ "Conversion rate + latency percentiles + within-N-day buckets, anchored on an enrollment or event",
160
+ },
161
+ },
162
+ });
163
+
106
164
  export const adminConversionsRouter = new OpenAPIHono<AppEnv>()
107
165
  .openapi(listRoute, async (c) => {
108
166
  const { db } = c.get("container");
@@ -244,4 +302,83 @@ export const adminConversionsRouter = new OpenAPIHono<AppEnv>()
244
302
  },
245
303
  200,
246
304
  );
305
+ })
306
+ .openapi(timingRoute, async (c) => {
307
+ const { db } = c.get("container");
308
+ const { definitionId, anchorType, anchorId, days } = c.req.valid("query");
309
+ const since = new Date(
310
+ Date.now() - days * 24 * 60 * 60 * 1000,
311
+ ).toISOString();
312
+
313
+ // Per subject: the anchor instant + its subject key. A journey subject is
314
+ // one enrollment row (created_at); an event subject is a contact's FIRST
315
+ // occurrence of the named event in the window.
316
+ const subjects =
317
+ anchorType === "journey"
318
+ ? sql`
319
+ select js.created_at as anchor_at, js.user_id as subject_key
320
+ from journey_states js
321
+ where js.journey_id = ${anchorId}
322
+ and js.created_at >= ${since}::timestamptz`
323
+ : sql`
324
+ select min(ue.occurred_at) as anchor_at, ue.user_id as subject_key
325
+ from user_events ue
326
+ where ue.event = ${anchorId}
327
+ and ue.occurred_at >= ${since}::timestamptz
328
+ group by ue.user_id`;
329
+
330
+ // For each subject, the first conversion of this definition at/after the
331
+ // anchor (correlated scalar). Latency = first_conv - anchor_at.
332
+ const latencyDays = sql`extract(epoch from (s.first_conv - s.anchor_at)) / 86400`;
333
+ const rows = await db.execute(sql`
334
+ select
335
+ (count(*))::int as anchored,
336
+ (count(s.first_conv))::int as converted,
337
+ (count(*) filter (where s.first_conv <= s.anchor_at + interval '1 day'))::int as w1,
338
+ (count(*) filter (where s.first_conv <= s.anchor_at + interval '7 days'))::int as w7,
339
+ (count(*) filter (where s.first_conv <= s.anchor_at + interval '14 days'))::int as w14,
340
+ (count(*) filter (where s.first_conv <= s.anchor_at + interval '30 days'))::int as w30,
341
+ percentile_cont(0.5) within group (order by ${latencyDays})
342
+ filter (where s.first_conv is not null) as median_days,
343
+ percentile_cont(0.9) within group (order by ${latencyDays})
344
+ filter (where s.first_conv is not null) as p90_days
345
+ from (
346
+ select
347
+ subj.anchor_at,
348
+ (
349
+ select min(c.occurred_at)
350
+ from conversions c
351
+ where c.user_key = subj.subject_key
352
+ and c.definition_id = ${definitionId}
353
+ and c.occurred_at >= subj.anchor_at
354
+ ) as first_conv
355
+ from (${subjects}) subj
356
+ ) s`);
357
+
358
+ const [row = {}] = rows as unknown as Record<string, unknown>[];
359
+ const num = (v: unknown) => Number(v ?? 0);
360
+ const nullableNum = (v: unknown) => (v == null ? null : Number(v));
361
+ const anchored = num(row.anchored);
362
+ const converted = num(row.converted);
363
+
364
+ return c.json(
365
+ {
366
+ definitionId,
367
+ anchor: { type: anchorType, id: anchorId },
368
+ days,
369
+ anchored,
370
+ converted,
371
+ rate: anchored > 0 ? converted / anchored : 0,
372
+ convertedWithin: {
373
+ d1: num(row.w1),
374
+ d7: num(row.w7),
375
+ d14: num(row.w14),
376
+ d30: num(row.w30),
377
+ },
378
+ medianDays: nullableNum(row.median_days),
379
+ p90Days: nullableNum(row.p90_days),
380
+ correlational: true as const,
381
+ },
382
+ 200,
383
+ );
247
384
  });
@@ -17,7 +17,7 @@ import type { AnyPgColumn } from "drizzle-orm/pg-core";
17
17
  import type { AppEnv } from "../../app.js";
18
18
 
19
19
  /**
20
- * Admin deals API (docs/revenue-attribution-plan.md §4b.1) — the ledger view
20
+ * Admin deals API — the ledger view
21
21
  * over the `deals` projection: filterable list for the Studio pipeline board
22
22
  * + the revenue stats block (per-currency, never cross-summed). Stages are
23
23
  * per-funnel ladders (`client.funnels`), not a fixed enum; the `funnel`
@@ -140,6 +140,8 @@ const statsSchema = z.object({
140
140
  ),
141
141
  /** Mean sold-deal cycle time in hours (created → soldAt), lifetime. */
142
142
  avgTimeToCloseHours: z.number().nullable(),
143
+ /** Distinct deal providers in this funnel — the list filter's vocabulary. */
144
+ providers: z.array(z.string()),
143
145
  });
144
146
 
145
147
  const statsRoute = createRoute({
@@ -389,39 +391,45 @@ export const adminDealsRouter = new OpenAPIHono<AppEnv>()
389
391
  Date.now() - 30 * 24 * 60 * 60 * 1000,
390
392
  ).toISOString();
391
393
 
392
- const [stageRows, rankRows, currencyRows, cycleRows] = await Promise.all([
393
- db
394
- .select({ stage: deals.canonicalStage, n: count() })
395
- .from(deals)
396
- .where(scopeWhere)
397
- .groupBy(deals.canonicalStage),
398
- db
399
- .select({ rank: deals.stageRank, n: count() })
400
- .from(deals)
401
- .where(scopeWhere)
402
- .groupBy(deals.stageRank),
403
- db
404
- .select({
405
- currency: deals.currency,
406
- soldRevenue30d: sql<number>`coalesce(sum(${deals.value}) filter (where ${deals.soldAt} >= ${thirtyDaysAgo}::timestamptz), 0)::float8`,
407
- soldRevenueLifetime: sql<number>`coalesce(sum(${deals.value}) filter (where ${deals.soldAt} is not null), 0)::float8`,
408
- soldCount30d: sql<number>`count(*) filter (where ${deals.soldAt} >= ${thirtyDaysAgo}::timestamptz)::int`,
409
- soldCountLifetime: sql<number>`count(*) filter (where ${deals.soldAt} is not null)::int`,
410
- openPipelineValue: sql<number>`coalesce(sum(${deals.value}) filter (where ${deals.soldAt} is null and ${deals.canonicalStage} != 'lost'), 0)::float8`,
411
- openPipelineCount: sql<number>`count(*) filter (where ${deals.soldAt} is null and ${deals.canonicalStage} != 'lost')::int`,
412
- })
413
- .from(deals)
414
- .where(scopeWhere)
415
- .groupBy(deals.currency),
416
- db
417
- .select({
418
- avgHours: sql<
419
- number | null
420
- >`avg(extract(epoch from (${deals.soldAt} - ${deals.createdAt})) / 3600)::float8`,
421
- })
422
- .from(deals)
423
- .where(and(sql`${deals.soldAt} is not null`, ...scope)),
424
- ]);
394
+ const [stageRows, rankRows, currencyRows, cycleRows, providerRows] =
395
+ await Promise.all([
396
+ db
397
+ .select({ stage: deals.canonicalStage, n: count() })
398
+ .from(deals)
399
+ .where(scopeWhere)
400
+ .groupBy(deals.canonicalStage),
401
+ db
402
+ .select({ rank: deals.stageRank, n: count() })
403
+ .from(deals)
404
+ .where(scopeWhere)
405
+ .groupBy(deals.stageRank),
406
+ db
407
+ .select({
408
+ currency: deals.currency,
409
+ soldRevenue30d: sql<number>`coalesce(sum(${deals.value}) filter (where ${deals.soldAt} >= ${thirtyDaysAgo}::timestamptz), 0)::float8`,
410
+ soldRevenueLifetime: sql<number>`coalesce(sum(${deals.value}) filter (where ${deals.soldAt} is not null), 0)::float8`,
411
+ soldCount30d: sql<number>`count(*) filter (where ${deals.soldAt} >= ${thirtyDaysAgo}::timestamptz)::int`,
412
+ soldCountLifetime: sql<number>`count(*) filter (where ${deals.soldAt} is not null)::int`,
413
+ openPipelineValue: sql<number>`coalesce(sum(${deals.value}) filter (where ${deals.soldAt} is null and ${deals.canonicalStage} != 'lost'), 0)::float8`,
414
+ openPipelineCount: sql<number>`count(*) filter (where ${deals.soldAt} is null and ${deals.canonicalStage} != 'lost')::int`,
415
+ })
416
+ .from(deals)
417
+ .where(scopeWhere)
418
+ .groupBy(deals.currency),
419
+ db
420
+ .select({
421
+ avgHours: sql<
422
+ number | null
423
+ >`avg(extract(epoch from (${deals.soldAt} - ${deals.createdAt})) / 3600)::float8`,
424
+ })
425
+ .from(deals)
426
+ .where(and(sql`${deals.soldAt} is not null`, ...scope)),
427
+ db
428
+ .selectDistinct({ provider: deals.provider })
429
+ .from(deals)
430
+ .where(scopeWhere)
431
+ .orderBy(asc(deals.provider)),
432
+ ]);
425
433
 
426
434
  const stageOrder = [...ladder.stages, "lost"];
427
435
  const stages: Record<string, number> = {};
@@ -466,6 +474,7 @@ export const adminDealsRouter = new OpenAPIHono<AppEnv>()
466
474
  }))
467
475
  .sort((a, b) => b.soldRevenueLifetime - a.soldRevenueLifetime),
468
476
  avgTimeToCloseHours: cycleRows[0]?.avgHours ?? null,
477
+ providers: providerRows.map((row) => row.provider),
469
478
  },
470
479
  200,
471
480
  );
@@ -17,12 +17,10 @@ import {
17
17
  inArray,
18
18
  isNotNull,
19
19
  isNull,
20
- like,
21
20
  lte,
22
21
  or,
23
22
  } from "drizzle-orm";
24
23
  import type { AppEnv } from "../../app.js";
25
- import { campaignSendKeyPattern } from "../../lib/campaign-send-key.js";
26
24
 
27
25
  const emailSchema = z.object({
28
26
  id: z.string(),
@@ -142,7 +140,7 @@ const listRoute = createRoute({
142
140
  * Only the sends of one campaign — matched on the deterministic
143
141
  * `campaign:<id>:<email>` idempotency key the blast wrote per recipient.
144
142
  */
145
- campaignId: z.string().optional(),
143
+ campaignId: z.string().uuid().optional(),
146
144
  userId: z.string().optional(),
147
145
  category: z.string().optional(),
148
146
  engagement: z
@@ -278,10 +276,10 @@ export const emailsRouter = new OpenAPIHono<AppEnv>()
278
276
  if (status) conditions.push(eq(emailSends.status, status));
279
277
  if (category) conditions.push(eq(emailSends.category, category));
280
278
  if (journeyId) conditions.push(eq(journeyStates.journeyId, journeyId));
279
+ // The indexed campaign_id column is the attribution — a key scan would
280
+ // miss suppressed sends, which write no idempotency key at all.
281
281
  if (campaignId) {
282
- conditions.push(
283
- like(emailSends.idempotencyKey, campaignSendKeyPattern(campaignId)),
284
- );
282
+ conditions.push(eq(emailSends.campaignId, campaignId));
285
283
  }
286
284
  // Match the denormalized identity OR the journey-state join, so journeyless
287
285
  // sends (which only carry the denormalized userId) are still filterable.