@hogsend/engine 0.43.0 → 0.44.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 (54) hide show
  1. package/package.json +10 -9
  2. package/src/container.ts +229 -2
  3. package/src/destinations/define-destination.ts +7 -3
  4. package/src/destinations/presets/posthog.ts +31 -0
  5. package/src/index.ts +99 -0
  6. package/src/journeys/execute-journey-run.ts +93 -0
  7. package/src/journeys/journey-context.ts +4 -0
  8. package/src/lib/attribution-backfill.ts +285 -0
  9. package/src/lib/attribution.ts +239 -0
  10. package/src/lib/contacts.ts +71 -0
  11. package/src/lib/conversion-dispatch.ts +326 -0
  12. package/src/lib/conversions.ts +197 -0
  13. package/src/lib/crm-deals.ts +320 -0
  14. package/src/lib/crm-ingest.ts +341 -0
  15. package/src/lib/crm-provider-registry.ts +41 -0
  16. package/src/lib/crm-registry-singleton.ts +22 -0
  17. package/src/lib/deal-money-events.ts +85 -0
  18. package/src/lib/email-service-types.ts +16 -1
  19. package/src/lib/event-names.ts +1 -1
  20. package/src/lib/funnel-progress.ts +76 -0
  21. package/src/lib/funnel-registry.ts +108 -0
  22. package/src/lib/funnel-transitions.ts +280 -0
  23. package/src/lib/holdout.ts +62 -0
  24. package/src/lib/ingestion.ts +218 -9
  25. package/src/lib/lift-stats.ts +125 -0
  26. package/src/lib/mailer.ts +1 -0
  27. package/src/lib/operator.ts +31 -0
  28. package/src/lib/outbound.ts +51 -0
  29. package/src/lib/revenue.ts +116 -0
  30. package/src/lib/sms-service-types.ts +7 -1
  31. package/src/lib/sms-tracked.ts +35 -0
  32. package/src/lib/tracked.ts +40 -0
  33. package/src/lib/tracking-events.ts +26 -0
  34. package/src/lib/webhook-signing.ts +7 -0
  35. package/src/routes/admin/attribution.ts +414 -0
  36. package/src/routes/admin/contacts.ts +71 -11
  37. package/src/routes/admin/conversions.ts +247 -0
  38. package/src/routes/admin/deals.ts +472 -0
  39. package/src/routes/admin/funnels.ts +228 -0
  40. package/src/routes/admin/index.ts +8 -0
  41. package/src/routes/admin/journeys.ts +158 -1
  42. package/src/routes/admin/readiness.ts +97 -2
  43. package/src/routes/admin/templates.ts +28 -1
  44. package/src/routes/events/index.ts +12 -0
  45. package/src/routes/tracking/click-pipeline.ts +26 -18
  46. package/src/routes/webhooks/crm-provider.ts +117 -0
  47. package/src/routes/webhooks/index.ts +5 -1
  48. package/src/sources/define-contact-source.ts +159 -0
  49. package/src/sources/registry.ts +71 -0
  50. package/src/sources/webhook-source.ts +109 -0
  51. package/src/worker.ts +4 -0
  52. package/src/workflows/crm-reconcile.ts +129 -0
  53. package/src/workflows/dispatch-conversion.ts +31 -0
  54. package/src/workflows/send-campaign.ts +5 -0
@@ -0,0 +1,472 @@
1
+ import { DEFAULT_FUNNEL_ID } from "@hogsend/core";
2
+ import { contacts, deals } from "@hogsend/db";
3
+ import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
4
+ import {
5
+ and,
6
+ asc,
7
+ count,
8
+ desc,
9
+ eq,
10
+ gte,
11
+ isNull,
12
+ lte,
13
+ or,
14
+ sql,
15
+ } from "drizzle-orm";
16
+ import type { AnyPgColumn } from "drizzle-orm/pg-core";
17
+ import type { AppEnv } from "../../app.js";
18
+
19
+ /**
20
+ * Admin deals API (docs/revenue-attribution-plan.md §4b.1) — the ledger view
21
+ * over the `deals` projection: filterable list for the Studio pipeline board
22
+ * + the revenue stats block (per-currency, never cross-summed). Stages are
23
+ * per-funnel ladders (`client.funnels`), not a fixed enum; the `funnel`
24
+ * param scopes every read (the default funnel also matches pre-funnel
25
+ * null rows).
26
+ */
27
+
28
+ /** Scope a query to one funnel; "default" absorbs pre-funnel null rows. */
29
+ function funnelFilter(funnel: string | undefined) {
30
+ if (!funnel) return [];
31
+ return funnel === DEFAULT_FUNNEL_ID
32
+ ? [or(eq(deals.funnelId, funnel), isNull(deals.funnelId))]
33
+ : [eq(deals.funnelId, funnel)];
34
+ }
35
+
36
+ const dealSchema = z.object({
37
+ id: z.string(),
38
+ provider: z.string(),
39
+ externalId: z.string(),
40
+ contactId: z.string(),
41
+ contactEmail: z.string().nullable(),
42
+ pipelineId: z.string().nullable(),
43
+ funnelId: z.string().nullable(),
44
+ stageId: z.string().nullable(),
45
+ canonicalStage: z.string(),
46
+ value: z.number().nullable(),
47
+ currency: z.string().nullable(),
48
+ quotedAt: z.string().nullable(),
49
+ soldAt: z.string().nullable(),
50
+ lostAt: z.string().nullable(),
51
+ lastStageAt: z.string().nullable(),
52
+ createdAt: z.string(),
53
+ });
54
+
55
+ const listRoute = createRoute({
56
+ method: "get",
57
+ path: "/",
58
+ tags: ["Admin"],
59
+ summary: "List deals (the revenue ledger)",
60
+ request: {
61
+ query: z.object({
62
+ // Plain string: valid stages are the deployment's configured ladder.
63
+ stage: z.string().optional(),
64
+ provider: z.string().optional(),
65
+ /** Scope to one funnel id ("default" includes pre-funnel rows). */
66
+ funnel: z.string().optional(),
67
+ /** Contact email substring match. */
68
+ search: z.string().optional(),
69
+ minValue: z.coerce.number().optional(),
70
+ maxValue: z.coerce.number().optional(),
71
+ since: z.string().datetime().optional(),
72
+ sort: z
73
+ .enum([
74
+ "lastStageAt",
75
+ "value",
76
+ "stage",
77
+ "provider",
78
+ "contactEmail",
79
+ "quotedAt",
80
+ "soldAt",
81
+ "createdAt",
82
+ ])
83
+ .default("lastStageAt"),
84
+ dir: z.enum(["asc", "desc"]).default("desc"),
85
+ limit: z.coerce.number().min(1).max(200).default(50),
86
+ offset: z.coerce.number().min(0).default(0),
87
+ }),
88
+ },
89
+ responses: {
90
+ 200: {
91
+ content: {
92
+ "application/json": {
93
+ schema: z.object({
94
+ deals: z.array(dealSchema),
95
+ total: z.number(),
96
+ limit: z.number(),
97
+ offset: z.number(),
98
+ }),
99
+ },
100
+ },
101
+ description: "Paginated deals, newest stage activity first",
102
+ },
103
+ },
104
+ });
105
+
106
+ const statsSchema = z.object({
107
+ /** The funnel these stats are scoped to. */
108
+ funnelId: z.string(),
109
+ /** Every registered funnel — the Studio switcher's catalog. */
110
+ funnels: z.array(
111
+ z.object({
112
+ id: z.string(),
113
+ name: z.string().nullable(),
114
+ stageOrder: z.array(z.string()),
115
+ }),
116
+ ),
117
+ /** The scoped funnel's ladder in rank order, `lost` last — render columns
118
+ * in THIS order. */
119
+ stageOrder: z.array(z.string()),
120
+ /** Counts per canonical stage (current projection state). */
121
+ stages: z.record(z.string(), z.number()),
122
+ /**
123
+ * TRUE funnel counts: deals that reached each ladder stage OR went
124
+ * further (monotonic rank ≥ stage rank; lost deals count at the rank they
125
+ * got to). Always non-increasing down the ladder.
126
+ */
127
+ reached: z.record(z.string(), z.number()),
128
+ /** Per-currency money blocks — never summed across currencies. */
129
+ currencies: z.array(
130
+ z.object({
131
+ currency: z.string().nullable(),
132
+ soldRevenue30d: z.number(),
133
+ soldRevenueLifetime: z.number(),
134
+ soldCount30d: z.number(),
135
+ soldCountLifetime: z.number(),
136
+ openPipelineValue: z.number(),
137
+ openPipelineCount: z.number(),
138
+ averageOrderValue: z.number().nullable(),
139
+ }),
140
+ ),
141
+ /** Mean sold-deal cycle time in hours (created → soldAt), lifetime. */
142
+ avgTimeToCloseHours: z.number().nullable(),
143
+ });
144
+
145
+ const statsRoute = createRoute({
146
+ method: "get",
147
+ path: "/stats",
148
+ tags: ["Admin"],
149
+ summary: "Revenue stats over the deals ledger",
150
+ request: {
151
+ query: z.object({
152
+ /** Funnel to scope to; defaults to the default funnel. */
153
+ funnel: z.string().optional(),
154
+ }),
155
+ },
156
+ responses: {
157
+ 200: {
158
+ content: { "application/json": { schema: statsSchema } },
159
+ description: "Front-and-center revenue numbers, per funnel",
160
+ },
161
+ 404: {
162
+ content: {
163
+ "application/json": { schema: z.object({ error: z.string() }) },
164
+ },
165
+ description: "Unknown funnel id",
166
+ },
167
+ },
168
+ });
169
+
170
+ const seriesPoint = z.object({ date: z.string(), value: z.number() });
171
+
172
+ const timeseriesSchema = z.object({
173
+ days: z.number(),
174
+ /** Daily sold revenue per currency; sparse (days with sales only). */
175
+ revenue: z.array(
176
+ z.object({
177
+ currency: z.string().nullable(),
178
+ points: z.array(seriesPoint),
179
+ }),
180
+ ),
181
+ /** Currency-agnostic daily activity counts; sparse. */
182
+ counts: z.object({
183
+ sold: z.array(seriesPoint),
184
+ quoted: z.array(seriesPoint),
185
+ created: z.array(seriesPoint),
186
+ }),
187
+ });
188
+
189
+ const timeseriesRoute = createRoute({
190
+ method: "get",
191
+ path: "/timeseries",
192
+ tags: ["Admin"],
193
+ summary: "Daily deal metrics (the dashboard chart series)",
194
+ request: {
195
+ query: z.object({
196
+ days: z.coerce.number().min(7).max(180).default(60),
197
+ /** Scope to one funnel id ("default" includes pre-funnel rows). */
198
+ funnel: z.string().optional(),
199
+ }),
200
+ },
201
+ responses: {
202
+ 200: {
203
+ content: { "application/json": { schema: timeseriesSchema } },
204
+ description:
205
+ "Sparse daily points: sold revenue per currency + sold/quoted/created counts",
206
+ },
207
+ },
208
+ });
209
+
210
+ function dealFilters(query: {
211
+ stage?: string;
212
+ provider?: string;
213
+ funnel?: string;
214
+ search?: string;
215
+ minValue?: number;
216
+ maxValue?: number;
217
+ since?: string;
218
+ }) {
219
+ return [
220
+ ...(query.stage ? [eq(deals.canonicalStage, query.stage)] : []),
221
+ ...(query.provider ? [eq(deals.provider, query.provider)] : []),
222
+ ...funnelFilter(query.funnel),
223
+ // EXISTS keeps the count query join-free. LIKE metachars in the input
224
+ // are escaped so "first_last" doesn't wildcard-match "firstXlast".
225
+ ...(query.search
226
+ ? [
227
+ sql`exists (select 1 from contacts c where c.id = ${deals.contactId} and c.email ilike ${`%${query.search.replace(/[\\%_]/g, "\\$&")}%`} escape '\\')`,
228
+ ]
229
+ : []),
230
+ ...(query.minValue !== undefined ? [gte(deals.value, query.minValue)] : []),
231
+ ...(query.maxValue !== undefined ? [lte(deals.value, query.maxValue)] : []),
232
+ ...(query.since ? [gte(deals.lastStageAt, new Date(query.since))] : []),
233
+ ];
234
+ }
235
+
236
+ export const adminDealsRouter = new OpenAPIHono<AppEnv>()
237
+ .openapi(listRoute, async (c) => {
238
+ const { db } = c.get("container");
239
+ const query = c.req.valid("query");
240
+ const filters = dealFilters(query);
241
+ const where = filters.length > 0 ? and(...filters) : undefined;
242
+
243
+ // Whitelisted sort columns (stage sorts by rank, not alphabetically).
244
+ const sortColumns = {
245
+ lastStageAt: deals.lastStageAt,
246
+ value: deals.value,
247
+ stage: deals.stageRank,
248
+ provider: deals.provider,
249
+ contactEmail: contacts.email,
250
+ quotedAt: deals.quotedAt,
251
+ soldAt: deals.soldAt,
252
+ createdAt: deals.createdAt,
253
+ } as const;
254
+ const sortCol = sortColumns[query.sort];
255
+ const primary = query.dir === "asc" ? asc(sortCol) : desc(sortCol);
256
+
257
+ const [rows, totalRows] = await Promise.all([
258
+ db
259
+ .select({
260
+ deal: deals,
261
+ contactEmail: contacts.email,
262
+ })
263
+ .from(deals)
264
+ .leftJoin(contacts, eq(deals.contactId, contacts.id))
265
+ .where(where)
266
+ .orderBy(primary, desc(deals.createdAt))
267
+ .limit(query.limit)
268
+ .offset(query.offset),
269
+ db.select({ total: count() }).from(deals).where(where),
270
+ ]);
271
+
272
+ return c.json(
273
+ {
274
+ deals: rows.map(({ deal, contactEmail }) => ({
275
+ id: deal.id,
276
+ provider: deal.provider,
277
+ externalId: deal.externalId,
278
+ contactId: deal.contactId,
279
+ contactEmail,
280
+ pipelineId: deal.pipelineId,
281
+ funnelId: deal.funnelId,
282
+ stageId: deal.stageId,
283
+ canonicalStage: deal.canonicalStage,
284
+ value: deal.value,
285
+ currency: deal.currency,
286
+ quotedAt: deal.quotedAt?.toISOString() ?? null,
287
+ soldAt: deal.soldAt?.toISOString() ?? null,
288
+ lostAt: deal.lostAt?.toISOString() ?? null,
289
+ lastStageAt: deal.lastStageAt?.toISOString() ?? null,
290
+ createdAt: deal.createdAt.toISOString(),
291
+ })),
292
+ total: totalRows[0]?.total ?? 0,
293
+ limit: query.limit,
294
+ offset: query.offset,
295
+ },
296
+ 200,
297
+ );
298
+ })
299
+ .openapi(timeseriesRoute, async (c) => {
300
+ const { db } = c.get("container");
301
+ const { days, funnel } = c.req.valid("query");
302
+ // Window starts at the FIRST bucket's UTC midnight (today − days-1) so
303
+ // every fetched point has a client-side day key — no orphaned edge day.
304
+ const start = new Date();
305
+ start.setUTCHours(0, 0, 0, 0);
306
+ start.setUTCDate(start.getUTCDate() - (days - 1));
307
+ const since = start.toISOString();
308
+
309
+ // Day buckets in UTC everywhere ('YYYY-MM-DD' via AT TIME ZONE 'UTC') so
310
+ // the client's UTC zero-fill always finds the keys, whatever the DB
311
+ // session timezone is.
312
+ const dayOf = (col: AnyPgColumn) =>
313
+ sql<string>`to_char(date_trunc('day', ${col} at time zone 'UTC'), 'YYYY-MM-DD')`;
314
+ const bucketCounts = (col: AnyPgColumn) =>
315
+ db
316
+ .select({ day: dayOf(col), n: count() })
317
+ .from(deals)
318
+ .where(
319
+ and(
320
+ sql`${col} is not null and ${col} >= ${since}::timestamptz`,
321
+ ...funnelFilter(funnel),
322
+ ),
323
+ )
324
+ .groupBy(dayOf(col))
325
+ .orderBy(dayOf(col));
326
+
327
+ const [revenueRows, soldRows, quotedRows, createdRows] = await Promise.all([
328
+ db
329
+ .select({
330
+ currency: deals.currency,
331
+ day: dayOf(deals.soldAt),
332
+ value: sql<number>`coalesce(sum(${deals.value}), 0)::float8`,
333
+ })
334
+ .from(deals)
335
+ .where(
336
+ and(
337
+ sql`${deals.soldAt} is not null and ${deals.soldAt} >= ${since}::timestamptz`,
338
+ ...funnelFilter(funnel),
339
+ ),
340
+ )
341
+ .groupBy(deals.currency, dayOf(deals.soldAt))
342
+ .orderBy(dayOf(deals.soldAt)),
343
+ bucketCounts(deals.soldAt),
344
+ bucketCounts(deals.quotedAt),
345
+ bucketCounts(deals.createdAt),
346
+ ]);
347
+
348
+ const byCurrency = new Map<
349
+ string | null,
350
+ Array<{ date: string; value: number }>
351
+ >();
352
+ for (const row of revenueRows) {
353
+ const list = byCurrency.get(row.currency) ?? [];
354
+ list.push({ date: row.day, value: row.value });
355
+ byCurrency.set(row.currency, list);
356
+ }
357
+ const toPoints = (rows: Array<{ day: string; n: number }>) =>
358
+ rows.map((row) => ({ date: row.day, value: Number(row.n) }));
359
+
360
+ return c.json(
361
+ {
362
+ days,
363
+ revenue: [...byCurrency.entries()].map(([currency, points]) => ({
364
+ currency,
365
+ points,
366
+ })),
367
+ counts: {
368
+ sold: toPoints(soldRows),
369
+ quoted: toPoints(quotedRows),
370
+ created: toPoints(createdRows),
371
+ },
372
+ },
373
+ 200,
374
+ );
375
+ })
376
+ .openapi(statsRoute, async (c) => {
377
+ const { db, funnels } = c.get("container");
378
+ const funnelId = c.req.valid("query").funnel ?? DEFAULT_FUNNEL_ID;
379
+ const funnel = funnels.get(funnelId);
380
+ if (!funnel) {
381
+ return c.json({ error: `Unknown funnel "${funnelId}"` }, 404);
382
+ }
383
+ const ladder = funnel.ladder;
384
+ const scope = funnelFilter(funnelId);
385
+ const scopeWhere = scope.length > 0 ? and(...scope) : undefined;
386
+ // ISO string + explicit cast: a raw Date param inside a sql`` fragment
387
+ // serializes as a JS date string postgres cannot parse.
388
+ const thirtyDaysAgo = new Date(
389
+ Date.now() - 30 * 24 * 60 * 60 * 1000,
390
+ ).toISOString();
391
+
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
+ ]);
425
+
426
+ const stageOrder = [...ladder.stages, "lost"];
427
+ const stages: Record<string, number> = {};
428
+ for (const stage of stageOrder) {
429
+ stages[stage] = 0;
430
+ }
431
+ for (const row of stageRows) stages[row.stage] = Number(row.n);
432
+
433
+ // reached[stage_i] = deals whose monotonic rank got to i or beyond.
434
+ const reached: Record<string, number> = {};
435
+ ladder.stages.forEach((stage, i) => {
436
+ reached[stage] = rankRows.reduce(
437
+ (sum, row) => (row.rank >= i ? sum + Number(row.n) : sum),
438
+ 0,
439
+ );
440
+ });
441
+
442
+ return c.json(
443
+ {
444
+ funnelId,
445
+ funnels: funnels.getAll().map((f) => ({
446
+ id: f.meta.id,
447
+ name: f.meta.name ?? null,
448
+ stageOrder: [...f.ladder.stages, "lost"],
449
+ })),
450
+ stageOrder,
451
+ stages,
452
+ reached,
453
+ currencies: currencyRows
454
+ .map((row) => ({
455
+ currency: row.currency,
456
+ soldRevenue30d: row.soldRevenue30d,
457
+ soldRevenueLifetime: row.soldRevenueLifetime,
458
+ soldCount30d: row.soldCount30d,
459
+ soldCountLifetime: row.soldCountLifetime,
460
+ openPipelineValue: row.openPipelineValue,
461
+ openPipelineCount: row.openPipelineCount,
462
+ averageOrderValue:
463
+ row.soldCountLifetime > 0
464
+ ? row.soldRevenueLifetime / row.soldCountLifetime
465
+ : null,
466
+ }))
467
+ .sort((a, b) => b.soldRevenueLifetime - a.soldRevenueLifetime),
468
+ avgTimeToCloseHours: cycleRows[0]?.avgHours ?? null,
469
+ },
470
+ 200,
471
+ );
472
+ });
@@ -0,0 +1,228 @@
1
+ import { TOUCHPOINT_EVENTS } from "@hogsend/core";
2
+ import { funnelProgress } from "@hogsend/db";
3
+ import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
4
+ import { and, count, eq, gte, sql } from "drizzle-orm";
5
+ import { alias } from "drizzle-orm/pg-core";
6
+ import type { AppEnv } from "../../app.js";
7
+
8
+ /**
9
+ * Event-funnel progression + velocity report (impact plan §3.4) — reads the
10
+ * `funnel_progress` projection (event-ladder funnels, §3.3). CRM funnels are
11
+ * covered by the deals dashboard; this is the B2C sibling.
12
+ *
13
+ * Every number here is CORRELATIONAL (design decision 4): exposure is "the
14
+ * contact had ≥1 touchpoint from the scope before reaching the next stage",
15
+ * which self-selects engaged contacts. The response says so; only Phase-4
16
+ * holdout output may use causal language.
17
+ */
18
+
19
+ const cohortSchema = z.object({
20
+ /** Contacts who reached the `from` stage inside the window. */
21
+ entered: z.number(),
22
+ /** Subset who went on to reach the `to` stage. */
23
+ converted: z.number(),
24
+ /** converted / entered (0 when nobody entered). */
25
+ rate: z.number(),
26
+ /** Median days from `from` to `to` among converters; null when none. */
27
+ medianDays: z.number().nullable(),
28
+ });
29
+
30
+ const transitionSchema = z.object({
31
+ from: z.string(),
32
+ to: z.string(),
33
+ all: cohortSchema,
34
+ /** Present only when a scope filter was given. */
35
+ exposed: cohortSchema.optional(),
36
+ unexposed: cohortSchema.optional(),
37
+ });
38
+
39
+ const progressionRoute = createRoute({
40
+ method: "get",
41
+ path: "/{funnelId}/progression",
42
+ tags: ["Admin"],
43
+ summary: "Event-funnel progression + velocity (correlational)",
44
+ request: {
45
+ params: z.object({ funnelId: z.string() }),
46
+ query: z.object({
47
+ days: z.coerce.number().min(1).max(365).default(90),
48
+ /** Exposure scope: touches stamped with this journey. */
49
+ journeyId: z.string().optional(),
50
+ /** Exposure scope: touches stamped with this campaign. */
51
+ campaignId: z.string().optional(),
52
+ }),
53
+ },
54
+ responses: {
55
+ 200: {
56
+ content: {
57
+ "application/json": {
58
+ schema: z.object({
59
+ funnelId: z.string(),
60
+ days: z.number(),
61
+ stages: z.array(
62
+ z.object({
63
+ stage: z.string(),
64
+ rank: z.number(),
65
+ /** Contacts who first-reached this stage in the window. */
66
+ reached: z.number(),
67
+ }),
68
+ ),
69
+ transitions: z.array(transitionSchema),
70
+ /**
71
+ * Always true — exposed-vs-unexposed splits are association,
72
+ * not causation (self-selection: engaged contacts both click
73
+ * and convert more). Holdouts are the causal instrument.
74
+ */
75
+ correlational: z.literal(true),
76
+ }),
77
+ },
78
+ },
79
+ description:
80
+ "Per-stage reach and per-transition conversion + velocity, optionally split by scope exposure",
81
+ },
82
+ 404: {
83
+ content: {
84
+ "application/json": { schema: z.object({ error: z.string() }) },
85
+ },
86
+ description: "Unknown funnel",
87
+ },
88
+ },
89
+ });
90
+
91
+ export const adminFunnelsRouter = new OpenAPIHono<AppEnv>().openapi(
92
+ progressionRoute,
93
+ async (c) => {
94
+ const { db, funnels } = c.get("container");
95
+ const { funnelId } = c.req.valid("param");
96
+ const { days, journeyId, campaignId } = c.req.valid("query");
97
+ const funnel = funnels.get(funnelId);
98
+ if (!funnel) {
99
+ return c.json({ error: `Unknown funnel "${funnelId}"` }, 404);
100
+ }
101
+
102
+ const since = new Date(
103
+ Date.now() - days * 24 * 60 * 60 * 1000,
104
+ ).toISOString();
105
+ const sinceTs = sql`${since}::timestamptz`;
106
+
107
+ const stageRows = await db
108
+ .select({
109
+ stage: funnelProgress.stage,
110
+ rank: funnelProgress.stageRank,
111
+ reached: count(),
112
+ })
113
+ .from(funnelProgress)
114
+ .where(
115
+ and(
116
+ eq(funnelProgress.funnelId, funnelId),
117
+ gte(funnelProgress.reachedAt, sinceTs),
118
+ ),
119
+ )
120
+ .groupBy(funnelProgress.stage, funnelProgress.stageRank);
121
+ const reachedByStage = new Map(
122
+ stageRows.map((row) => [row.stage, Number(row.reached)]),
123
+ );
124
+ const stages = funnel.ladder.stages.map((stage, rank) => ({
125
+ stage,
126
+ rank,
127
+ reached: reachedByStage.get(stage) ?? 0,
128
+ }));
129
+
130
+ // Per adjacent transition: LEFT JOIN the contact's next-stage row, then
131
+ // aggregate counts + median velocity, split by scope exposure when a
132
+ // scope was given. Stage ladders are short, so one query per transition
133
+ // stays cheap and each stays a plain indexed join.
134
+ const next = alias(funnelProgress, "next_stage");
135
+ const scopeKey = journeyId ? "journeyId" : campaignId ? "campaignId" : null;
136
+ const scopeValue = journeyId ?? campaignId ?? null;
137
+ const touchEventList = sql.join(
138
+ TOUCHPOINT_EVENTS.map((event) => sql`${event}`),
139
+ sql`, `,
140
+ );
141
+ // Exposure: ≥1 stamped touchpoint BEFORE the outcome instant (the next
142
+ // stage's reach, or now for non-converters) — association framing.
143
+ const exposed = scopeKey
144
+ ? sql`exists (
145
+ select 1 from user_events ue
146
+ where ue.user_id = ${funnelProgress.userKey}
147
+ and ue.event in (${touchEventList})
148
+ and ue.properties->>${sql.raw(`'${scopeKey}'`)} = ${scopeValue}
149
+ and ue.occurred_at <= coalesce(${next.reachedAt}, now())
150
+ )`
151
+ : null;
152
+
153
+ const medianDaysExpr = (filter?: ReturnType<typeof sql>) =>
154
+ sql<
155
+ number | null
156
+ >`(percentile_cont(0.5) within group (order by extract(epoch from (${next.reachedAt} - ${funnelProgress.reachedAt})) / 86400) filter (where ${next.id} is not null${filter ? sql` and ${filter}` : sql``}))::float8`;
157
+
158
+ const transitions = [];
159
+ for (let i = 0; i < funnel.ladder.stages.length - 1; i++) {
160
+ const from = funnel.ladder.stages[i] as string;
161
+ const to = funnel.ladder.stages[i + 1] as string;
162
+ const [row] = await db
163
+ .select({
164
+ entered: count(),
165
+ converted: sql<number>`count(${next.id})::int`,
166
+ medianDays: medianDaysExpr(),
167
+ ...(exposed
168
+ ? {
169
+ exposedEntered: sql<number>`(count(*) filter (where ${exposed}))::int`,
170
+ exposedConverted: sql<number>`(count(${next.id}) filter (where ${exposed}))::int`,
171
+ exposedMedianDays: medianDaysExpr(exposed),
172
+ unexposedMedianDays: medianDaysExpr(sql`not ${exposed}`),
173
+ }
174
+ : {}),
175
+ })
176
+ .from(funnelProgress)
177
+ .leftJoin(
178
+ next,
179
+ and(
180
+ eq(next.contactId, funnelProgress.contactId),
181
+ eq(next.funnelId, funnelProgress.funnelId),
182
+ eq(next.stage, to),
183
+ gte(next.reachedAt, funnelProgress.reachedAt),
184
+ ),
185
+ )
186
+ .where(
187
+ and(
188
+ eq(funnelProgress.funnelId, funnelId),
189
+ eq(funnelProgress.stage, from),
190
+ gte(funnelProgress.reachedAt, sinceTs),
191
+ ),
192
+ );
193
+
194
+ const entered = Number(row?.entered ?? 0);
195
+ const converted = row?.converted ?? 0;
196
+ const cohort = (n: number, k: number, median: number | null) => ({
197
+ entered: n,
198
+ converted: k,
199
+ rate: n > 0 ? k / n : 0,
200
+ medianDays: median,
201
+ });
202
+ transitions.push({
203
+ from,
204
+ to,
205
+ all: cohort(entered, converted, row?.medianDays ?? null),
206
+ ...(exposed && row
207
+ ? {
208
+ exposed: cohort(
209
+ row.exposedEntered ?? 0,
210
+ row.exposedConverted ?? 0,
211
+ row.exposedMedianDays ?? null,
212
+ ),
213
+ unexposed: cohort(
214
+ entered - (row.exposedEntered ?? 0),
215
+ converted - (row.exposedConverted ?? 0),
216
+ row.unexposedMedianDays ?? null,
217
+ ),
218
+ }
219
+ : {}),
220
+ });
221
+ }
222
+
223
+ return c.json(
224
+ { funnelId, days, stages, transitions, correlational: true as const },
225
+ 200,
226
+ );
227
+ },
228
+ );