@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
@@ -0,0 +1,900 @@
1
+ import type { Database } from "@hogsend/db";
2
+ import { contacts, groupMemberships, groups, userEvents } from "@hogsend/db";
3
+ import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
4
+ import type { SQL } from "drizzle-orm";
5
+ import {
6
+ and,
7
+ asc,
8
+ count,
9
+ desc,
10
+ eq,
11
+ ilike,
12
+ inArray,
13
+ isNull,
14
+ or,
15
+ sql,
16
+ } from "drizzle-orm";
17
+ import type { AppEnv } from "../../app.js";
18
+ import type { FxRatesToBase } from "../../lib/fx.js";
19
+ import type { Logger } from "../../lib/logger.js";
20
+ import { trustedValuedEventFilter } from "../../lib/revenue.js";
21
+
22
+ /**
23
+ * Read-only admin surface over the sovereign group model — the endpoints the
24
+ * Studio OBSERVE view consumes. Groups are pure DB rows (`groups` /
25
+ * `group_memberships`), so unlike buckets there is no registry: every query hits
26
+ * the tables directly. All dates serialize to ISO strings; the router inherits
27
+ * the admin router's `requireAdmin` guard, so it never re-auths here.
28
+ */
29
+
30
+ const groupSchema = z.object({
31
+ id: z.string(),
32
+ groupType: z.string(),
33
+ groupKey: z.string(),
34
+ displayName: z.string().nullable(),
35
+ properties: z.record(z.string(), z.unknown()),
36
+ memberCount: z.number(),
37
+ // Money on this group's tagged events, GROUPED PER CURRENCY and never summed
38
+ // across them (the revenue spine's law — a GBP deal and a USD deal don't add),
39
+ // mirroring the contact rollup's `totals` shape. Empty when the group has no
40
+ // valued events. See `groupRevenueTotals`.
41
+ revenueTotals: z.array(
42
+ z.object({ currency: z.string().nullable(), total: z.number() }),
43
+ ),
44
+ // The group's money CONVERTED into the operator's base currency — the
45
+ // opt-in FX lens (docs/groups.md §Base-currency lens), a view layered on
46
+ // top of `revenueTotals`, never a replacement for it. Null when the lens is
47
+ // off/unavailable, or when ANY of this group's currencies lacks a rate — a
48
+ // partial sum is a lie. 0 when the lens is on and the group has no money.
49
+ revenueBase: z.number().nullable(),
50
+ firstSeenAt: z.string(),
51
+ lastSeenAt: z.string(),
52
+ });
53
+
54
+ // Non-null exactly when the base-currency lens served this response, so the
55
+ // Studio can label converted figures honestly ("≈ in USD, rates as of <date>").
56
+ const fxSchema = z.object({
57
+ baseCurrency: z.string(),
58
+ asOf: z.string().nullable(),
59
+ });
60
+
61
+ const memberSchema = z.object({
62
+ contactId: z.string(),
63
+ email: z.string().nullable(),
64
+ externalId: z.string().nullable(),
65
+ role: z.string().nullable(),
66
+ joinedAt: z.string(),
67
+ });
68
+
69
+ const eventSchema = z.object({
70
+ id: z.string(),
71
+ event: z.string(),
72
+ occurredAt: z.string(),
73
+ userId: z.string(),
74
+ });
75
+
76
+ const errorSchema = z.object({ error: z.string() });
77
+
78
+ /** The columns a serialized group needs — the row may come from the query
79
+ * builder (list/detail) or from the raw aggregate-sorted statement below. */
80
+ type GroupRowLike = Pick<
81
+ typeof groups.$inferSelect,
82
+ | "id"
83
+ | "groupType"
84
+ | "groupKey"
85
+ | "displayName"
86
+ | "properties"
87
+ | "firstSeenAt"
88
+ | "lastSeenAt"
89
+ >;
90
+
91
+ /** One currency's worth of a group's money — the displayable unit. */
92
+ interface RevenueTotal {
93
+ currency: string | null;
94
+ total: number;
95
+ }
96
+
97
+ /**
98
+ * The lens's per-group converted figure: sum over the per-currency totals of
99
+ * `total × rate(currency→base)`. Null when the lens is off (`rates` null) OR
100
+ * any currency present lacks a rate — including the null "no currency
101
+ * recorded" bucket — because a partial sum would LIE (it would display a
102
+ * group as smaller than it is). Empty totals with the lens on = 0: no money
103
+ * is zero in any currency.
104
+ */
105
+ function revenueBaseOf(
106
+ totals: RevenueTotal[],
107
+ rates: Record<string, number> | null,
108
+ ): number | null {
109
+ if (!rates) return null;
110
+ let sum = 0;
111
+ for (const t of totals) {
112
+ const rate = t.currency === null ? undefined : rates[t.currency];
113
+ if (rate === undefined) return null;
114
+ sum += t.total * rate;
115
+ }
116
+ return sum;
117
+ }
118
+
119
+ function serializeGroup(
120
+ row: GroupRowLike,
121
+ memberCount: number,
122
+ revenueTotals: RevenueTotal[],
123
+ rates: Record<string, number> | null,
124
+ ) {
125
+ return {
126
+ id: row.id,
127
+ groupType: row.groupType,
128
+ groupKey: row.groupKey,
129
+ displayName: row.displayName,
130
+ properties: (row.properties ?? {}) as Record<string, unknown>,
131
+ memberCount,
132
+ revenueTotals,
133
+ revenueBase: revenueBaseOf(revenueTotals, rates),
134
+ firstSeenAt: row.firstSeenAt.toISOString(),
135
+ lastSeenAt: row.lastSeenAt.toISOString(),
136
+ };
137
+ }
138
+
139
+ function serializeMember(row: {
140
+ contactId: string;
141
+ email: string | null;
142
+ externalId: string | null;
143
+ role: string | null;
144
+ joinedAt: Date;
145
+ }) {
146
+ return {
147
+ contactId: row.contactId,
148
+ email: row.email,
149
+ externalId: row.externalId,
150
+ role: row.role,
151
+ joinedAt: row.joinedAt.toISOString(),
152
+ };
153
+ }
154
+
155
+ function serializeEvent(row: {
156
+ id: string;
157
+ event: string;
158
+ occurredAt: Date;
159
+ userId: string;
160
+ }) {
161
+ return {
162
+ id: row.id,
163
+ event: row.event,
164
+ occurredAt: row.occurredAt.toISOString(),
165
+ userId: row.userId,
166
+ };
167
+ }
168
+
169
+ // --- Revenue rollup ---
170
+
171
+ /**
172
+ * Money belongs to a group when a valued event's `groups` association map
173
+ * CONTAINS that group. Two shapes serve two different needs:
174
+ *
175
+ * - `revenueForPage` — what is DISPLAYED. Grouped PER CURRENCY and never summed
176
+ * across currencies (`lib/revenue.ts`'s law: a GBP deal and a USD deal don't
177
+ * add), exactly like the contact rollup's `totals`.
178
+ * - `groupRevenueRanking` — what ORDERS `sort=revenue`. A single cross-currency
179
+ * scalar, an ordering HEURISTIC only: exact for a single-currency deployment
180
+ * (the common case), an approximation for a mixed-currency one — the same
181
+ * trade the contacts list already makes with its `minRevenue` threshold. It
182
+ * ranks; it never reaches the response.
183
+ *
184
+ * Both share `trustedValuedEventFilter()` — the gate the contact rollup uses —
185
+ * so a group's revenue and its members' revenue can never disagree: no
186
+ * re-counting the CRM machinery events that carry one deal's value on every
187
+ * stage change, and no browser-minted (`inapp`) values.
188
+ */
189
+
190
+ /**
191
+ * Escape LIKE/ILIKE metacharacters so a search string can't widen its own match
192
+ * (`promo_50` must match `promo_50`, not `promoX50`; a trailing `\` must not
193
+ * break the pattern). Same idiom as the event-name search in `lib/event-names`.
194
+ */
195
+ function escapeLike(value: string): string {
196
+ return value.replace(/[\\%_]/g, (m) => `\\${m}`);
197
+ }
198
+
199
+ /**
200
+ * "This event is tagged with this group" — jsonb containment against the
201
+ * association map, the shape the partial GIN index is built for.
202
+ */
203
+ function groupContainment(groupType: string, groupKey: string): SQL {
204
+ return sql`${userEvents.groups} @> ${JSON.stringify({
205
+ [groupType]: groupKey,
206
+ })}::jsonb`;
207
+ }
208
+
209
+ /**
210
+ * `(groupType, groupKey)` as a Map key. The NUL separator cannot occur inside
211
+ * a Postgres text value, so no two distinct natural keys can collide.
212
+ */
213
+ function naturalKey(groupType: string, groupKey: string): string {
214
+ return `${groupType}\u0000${groupKey}`;
215
+ }
216
+
217
+ /**
218
+ * Per-currency revenue for JUST the groups on a page (≤ `limit` of them), keyed
219
+ * by natural key.
220
+ *
221
+ * The rows are selected by an OR of jsonb CONTAINMENTS, which the partial GIN
222
+ * (`user_events_valued_groups_idx`, over the valued+grouped slice) serves — so
223
+ * the displayed money never costs a scan of the event spine. The lateral then
224
+ * expands only those matched rows, and the `(kv.key, kv.value) IN (…)` residual
225
+ * drops the OTHER groups an event may also be tagged with (an event tagged both
226
+ * `company` and `team` yields a kv row for each; only the page's pairs count).
227
+ */
228
+ async function revenueForPage(
229
+ db: Database,
230
+ rows: readonly GroupRowLike[],
231
+ ): Promise<Map<string, RevenueTotal[]>> {
232
+ const totals = new Map<string, RevenueTotal[]>();
233
+ if (rows.length === 0) return totals;
234
+
235
+ const contains = sql.join(
236
+ rows.map((r) => groupContainment(r.groupType, r.groupKey)),
237
+ sql` or `,
238
+ );
239
+ const pairs = sql.join(
240
+ rows.map((r) => sql`(${r.groupType}, ${r.groupKey})`),
241
+ sql`, `,
242
+ );
243
+
244
+ const revenueRows = await db.execute<{
245
+ group_type: string;
246
+ group_key: string;
247
+ currency: string | null;
248
+ total: string;
249
+ }>(sql`
250
+ select kv.key as group_type,
251
+ kv.value as group_key,
252
+ ${userEvents.currency} as currency,
253
+ sum(${userEvents.value})::float8 as total
254
+ from ${userEvents}, lateral jsonb_each_text(${userEvents.groups}) kv
255
+ where ${trustedValuedEventFilter()}
256
+ and (${contains})
257
+ and (kv.key, kv.value) in (${pairs})
258
+ group by kv.key, kv.value, ${userEvents.currency}
259
+ `);
260
+
261
+ for (const row of revenueRows) {
262
+ const key = naturalKey(row.group_type, row.group_key);
263
+ const bucket = totals.get(key) ?? [];
264
+ bucket.push({ currency: row.currency, total: Number(row.total) });
265
+ totals.set(key, bucket);
266
+ }
267
+ // Biggest first within a group, mirroring `getContactRevenue`'s totals.
268
+ for (const bucket of totals.values()) {
269
+ bucket.sort((a, b) => b.total - a.total);
270
+ }
271
+ return totals;
272
+ }
273
+
274
+ /**
275
+ * The cross-currency RANKING scalar behind `sort=revenue` — every group in one
276
+ * grouped pass, because the order has to be decided across ALL groups before the
277
+ * page is cut, so it cannot be page-scoped (and therefore cannot ride the GIN).
278
+ * That full pass covers only the valued+grouped slice, which is small by design
279
+ * and kept tight by the partial index.
280
+ */
281
+ function groupRevenueRanking(): SQL {
282
+ return sql`
283
+ select kv.key as group_type,
284
+ kv.value as group_key,
285
+ sum(${userEvents.value})::float8 as revenue
286
+ from ${userEvents}, lateral jsonb_each_text(${userEvents.groups}) kv
287
+ where ${trustedValuedEventFilter()}
288
+ group by kv.key, kv.value
289
+ `;
290
+ }
291
+
292
+ /**
293
+ * The base-CONVERTED twin of {@link groupRevenueRanking}, used for
294
+ * `sort=revenue` when the FX lens is active AND every currency in play has a
295
+ * rate: the resolved quote→base map joins in as a VALUES list, so each
296
+ * event's value converts in SQL (`value × rate`) and the ranking scalar
297
+ * becomes real base-currency money instead of the cross-currency heuristic.
298
+ * The comma-join on currency is safe precisely because the caller proved
299
+ * convertibility first ({@link unconvertibleCurrencies}) — nothing can drop.
300
+ */
301
+ function groupRevenueRankingInBase(rates: Record<string, number>): SQL {
302
+ const values = sql.join(
303
+ Object.entries(rates).map(
304
+ ([currency, rate]) => sql`(${currency}::text, ${rate}::float8)`,
305
+ ),
306
+ sql`, `,
307
+ );
308
+ return sql`
309
+ select kv.key as group_type,
310
+ kv.value as group_key,
311
+ sum(${userEvents.value} * fxr.rate)::float8 as revenue
312
+ from ${userEvents},
313
+ lateral jsonb_each_text(${userEvents.groups}) kv,
314
+ (values ${values}) as fxr(currency, rate)
315
+ where ${trustedValuedEventFilter()}
316
+ and ${userEvents.currency} = fxr.currency
317
+ group by kv.key, kv.value
318
+ `;
319
+ }
320
+
321
+ /**
322
+ * The convertibility PROBE behind the ranking's wholesale-fallback rule: the
323
+ * distinct currencies on trusted valued events tagged with a group matching
324
+ * this request's filter, minus the ones the rate sheet covers. Scoped to the
325
+ * FILTERED groups (not the whole valued+grouped slice) because only their
326
+ * revenues decide this page's order — an exotic currency on some unrelated
327
+ * group must not knock a clean single-currency view off the converted
328
+ * ranking. A null currency (a valued event ingested without one) can never
329
+ * have a rate and reports as "(none)".
330
+ */
331
+ async function unconvertibleCurrencies(
332
+ db: Database,
333
+ where: SQL,
334
+ rates: Record<string, number>,
335
+ ): Promise<string[]> {
336
+ const rows = await db.execute<{ currency: string | null }>(sql`
337
+ select distinct ${userEvents.currency} as currency
338
+ from ${userEvents}, lateral jsonb_each_text(${userEvents.groups}) kv
339
+ inner join ${groups}
340
+ on ${groups.groupType} = kv.key
341
+ and ${groups.groupKey} = kv.value
342
+ where ${trustedValuedEventFilter()}
343
+ and (${where})
344
+ `);
345
+ return rows
346
+ .map((r) => r.currency)
347
+ .filter((c) => c === null || rates[c] === undefined)
348
+ .map((c) => c ?? "(none)");
349
+ }
350
+
351
+ // --- List paths (column-sorted vs aggregate-sorted) ---
352
+
353
+ interface ListOpts {
354
+ where: SQL;
355
+ sort: "lastSeen" | "members" | "revenue" | "name";
356
+ order: "asc" | "desc";
357
+ limit: number;
358
+ offset: number;
359
+ /**
360
+ * The resolved quote→base rate map when the FX lens is ACTIVE (base
361
+ * currency set AND the provider served rates), else null. Drives the
362
+ * per-group `revenueBase` figure on both list paths and, on
363
+ * `sort=revenue`, the base-converted ranking.
364
+ */
365
+ rates: Record<string, number> | null;
366
+ logger: Logger;
367
+ }
368
+
369
+ /**
370
+ * One grouped count over the page's group ids — mirrors how buckets maps its
371
+ * per-bucket status counts back onto the listed rows. Joined to LIVE contacts
372
+ * so the count matches exactly the set the members endpoint lists (a membership
373
+ * whose contact is soft-deleted must not over-count).
374
+ */
375
+ async function memberCountsForPage(
376
+ db: Database,
377
+ groupIds: string[],
378
+ ): Promise<Map<string, number>> {
379
+ if (groupIds.length === 0) return new Map();
380
+ const rows = await db
381
+ .select({ groupId: groupMemberships.groupId, count: count() })
382
+ .from(groupMemberships)
383
+ .innerJoin(contacts, eq(groupMemberships.contactId, contacts.id))
384
+ .where(
385
+ and(
386
+ inArray(groupMemberships.groupId, groupIds),
387
+ isNull(contacts.deletedAt),
388
+ ),
389
+ )
390
+ .groupBy(groupMemberships.groupId);
391
+ return new Map(rows.map((r) => [r.groupId, r.count]));
392
+ }
393
+
394
+ /**
395
+ * Sorts that live on a `groups` column (`lastSeen`, `name`): the page is cut
396
+ * from `groups` alone, then both aggregates are resolved for JUST that page.
397
+ */
398
+ async function listByColumn(db: Database, opts: ListOpts) {
399
+ const direction = opts.order === "asc" ? asc : desc;
400
+ const sortCol =
401
+ opts.sort === "name"
402
+ ? sql`coalesce(${groups.displayName}, ${groups.groupKey})`
403
+ : groups.lastSeenAt;
404
+
405
+ const rows = await db
406
+ .select()
407
+ .from(groups)
408
+ .where(opts.where)
409
+ // `id` breaks ties so paging over equal sort keys stays stable.
410
+ .orderBy(direction(sortCol), asc(groups.id))
411
+ .limit(opts.limit)
412
+ .offset(opts.offset);
413
+
414
+ const [countMap, revenueMap] = await Promise.all([
415
+ memberCountsForPage(
416
+ db,
417
+ rows.map((r) => r.id),
418
+ ),
419
+ revenueForPage(db, rows),
420
+ ]);
421
+
422
+ return rows.map((r) =>
423
+ serializeGroup(
424
+ r,
425
+ countMap.get(r.id) ?? 0,
426
+ revenueMap.get(naturalKey(r.groupType, r.groupKey)) ?? [],
427
+ opts.rates,
428
+ ),
429
+ );
430
+ }
431
+
432
+ /**
433
+ * Sorts driven by an aggregate (`members`, `revenue`): the order has to be
434
+ * decided across ALL matching groups BEFORE the page is cut, so both aggregates
435
+ * become grouped CTEs joined to the filtered groups and the ORDER BY reads one
436
+ * of them. Sorting the rows a `lastSeen` page happened to contain would rank a
437
+ * page-local lie. Each aggregate is still computed exactly once — no per-row
438
+ * queries.
439
+ *
440
+ * `revenue` here is the cross-currency RANKING scalar (see the rollup note
441
+ * above); the money the page DISPLAYS is re-read per currency by
442
+ * `revenueForPage`, so a mixed-currency deployment gets an approximate order but
443
+ * never an invented number.
444
+ *
445
+ * With the FX lens active, `revenue` upgrades to the base-CONVERTED sum — but
446
+ * only WHOLESALE: if any currency on the filtered groups' events lacks a
447
+ * rate, the whole request falls back to the heuristic scalar (warned once).
448
+ * Excluding the unconvertible rows would zero-out a real account; converting
449
+ * only some of a group's money would rank a partial sum. Approximate-but-
450
+ * honest beats precise-but-wrong.
451
+ *
452
+ * The statement ranks + pages the IDS; the group rows themselves are hydrated
453
+ * through the query builder, which parses the column types — drizzle's raw
454
+ * `execute` hands back every column as text.
455
+ */
456
+ async function listByAggregate(db: Database, opts: ListOpts) {
457
+ const direction = opts.order === "asc" ? sql`asc` : sql`desc`;
458
+ const sortExpr =
459
+ opts.sort === "members"
460
+ ? sql`coalesce(mc.member_count, 0)`
461
+ : sql`coalesce(gr.revenue, 0)`;
462
+
463
+ let revenueCte = groupRevenueRanking();
464
+ if (opts.sort === "revenue" && opts.rates) {
465
+ const missing = await unconvertibleCurrencies(db, opts.where, opts.rates);
466
+ if (missing.length === 0) {
467
+ revenueCte = groupRevenueRankingInBase(opts.rates);
468
+ } else {
469
+ opts.logger.warn(
470
+ `groups sort=revenue: no base-currency rate for ${missing.join(", ")} — this request ranked by the cross-currency heuristic instead (a partial conversion would misrank real money). Add the missing rate(s) to restore base-currency ranking.`,
471
+ );
472
+ }
473
+ }
474
+
475
+ const ranked = Array.from(
476
+ await db.execute<{
477
+ id: string;
478
+ member_count: string;
479
+ }>(sql`
480
+ with member_counts as (
481
+ select ${groupMemberships.groupId} as group_id,
482
+ count(*)::int as member_count
483
+ from ${groupMemberships}
484
+ inner join ${contacts}
485
+ on ${contacts.id} = ${groupMemberships.contactId}
486
+ where ${contacts.deletedAt} is null
487
+ group by ${groupMemberships.groupId}
488
+ ),
489
+ group_revenue as (${revenueCte})
490
+ select ${groups.id} as id,
491
+ coalesce(mc.member_count, 0) as member_count
492
+ from ${groups}
493
+ left join member_counts mc on mc.group_id = ${groups.id}
494
+ left join group_revenue gr
495
+ on gr.group_type = ${groups.groupType}
496
+ and gr.group_key = ${groups.groupKey}
497
+ where ${opts.where}
498
+ -- id breaks ties so paging over equal aggregates stays stable.
499
+ order by ${sortExpr} ${direction}, ${groups.id} asc
500
+ limit ${opts.limit} offset ${opts.offset}
501
+ `),
502
+ );
503
+ if (ranked.length === 0) return [];
504
+
505
+ const rows = await db
506
+ .select()
507
+ .from(groups)
508
+ .where(
509
+ inArray(
510
+ groups.id,
511
+ ranked.map((r) => r.id),
512
+ ),
513
+ );
514
+ const byId = new Map(rows.map((r) => [r.id, r]));
515
+ const revenueMap = await revenueForPage(db, rows);
516
+
517
+ // Re-imposes the ranked order the hydration lookup doesn't preserve.
518
+ return ranked.flatMap((r) => {
519
+ const row = byId.get(r.id);
520
+ if (!row) return [];
521
+ return [
522
+ serializeGroup(
523
+ row,
524
+ Number(r.member_count),
525
+ revenueMap.get(naturalKey(row.groupType, row.groupKey)) ?? [],
526
+ opts.rates,
527
+ ),
528
+ ];
529
+ });
530
+ }
531
+
532
+ // --- Route definitions ---
533
+
534
+ const listRoute = createRoute({
535
+ method: "get",
536
+ path: "/",
537
+ tags: ["Admin — Groups"],
538
+ summary: "List groups",
539
+ request: {
540
+ query: z.object({
541
+ limit: z.coerce.number().min(1).max(100).default(50),
542
+ offset: z.coerce.number().min(0).default(0),
543
+ groupType: z.string().optional(),
544
+ // Case-insensitive substring over the group's identity: its key or its
545
+ // display name. LIKE metacharacters are escaped, so it matches literally.
546
+ search: z.string().optional(),
547
+ // `revenue` ranks on the CROSS-CURRENCY sum — an ordering heuristic
548
+ // (exact for a single-currency deployment, approximate for a mixed one),
549
+ // never a displayed figure: the money itself comes back per currency in
550
+ // `revenueTotals`. Same trade as the contacts list's `minRevenue`.
551
+ // With the FX lens active (BASE_CURRENCY + rates) the ranking upgrades
552
+ // to the base-converted sum — falling back WHOLESALE to the heuristic
553
+ // when any currency in play lacks a rate.
554
+ sort: z
555
+ .enum(["lastSeen", "members", "revenue", "name"])
556
+ .default("lastSeen"),
557
+ order: z.enum(["desc", "asc"]).default("desc"),
558
+ }),
559
+ },
560
+ responses: {
561
+ 200: {
562
+ content: {
563
+ "application/json": {
564
+ schema: z.object({
565
+ groups: z.array(groupSchema),
566
+ total: z.number(),
567
+ limit: z.number(),
568
+ offset: z.number(),
569
+ fx: fxSchema.nullable(),
570
+ }),
571
+ },
572
+ },
573
+ description: "Paginated group list, newest-seen first by default",
574
+ },
575
+ },
576
+ });
577
+
578
+ const listTypesRoute = createRoute({
579
+ method: "get",
580
+ path: "/types",
581
+ tags: ["Admin — Groups"],
582
+ summary: "List distinct group types",
583
+ responses: {
584
+ 200: {
585
+ content: {
586
+ "application/json": {
587
+ schema: z.object({
588
+ types: z.array(
589
+ z.object({ groupType: z.string(), count: z.number() }),
590
+ ),
591
+ }),
592
+ },
593
+ },
594
+ description:
595
+ "Distinct group types across live groups with per-type counts, largest first",
596
+ },
597
+ },
598
+ });
599
+
600
+ const getRoute = createRoute({
601
+ method: "get",
602
+ path: "/{groupType}/{groupKey}",
603
+ tags: ["Admin — Groups"],
604
+ summary: "Get group detail",
605
+ request: {
606
+ params: z.object({ groupType: z.string(), groupKey: z.string() }),
607
+ },
608
+ responses: {
609
+ 200: {
610
+ content: {
611
+ "application/json": {
612
+ schema: z.object({
613
+ group: groupSchema.extend({
614
+ recentMembers: z.array(memberSchema),
615
+ recentEvents: z.array(eventSchema),
616
+ }),
617
+ fx: fxSchema.nullable(),
618
+ }),
619
+ },
620
+ },
621
+ description: "Group detail with recent members and recent tagged events",
622
+ },
623
+ 404: {
624
+ content: { "application/json": { schema: errorSchema } },
625
+ description: "Group not found",
626
+ },
627
+ },
628
+ });
629
+
630
+ const listMembersRoute = createRoute({
631
+ method: "get",
632
+ path: "/{groupType}/{groupKey}/members",
633
+ tags: ["Admin — Groups"],
634
+ summary: "List group members",
635
+ request: {
636
+ params: z.object({ groupType: z.string(), groupKey: z.string() }),
637
+ query: z.object({
638
+ limit: z.coerce.number().min(1).max(100).default(50),
639
+ offset: z.coerce.number().min(0).default(0),
640
+ }),
641
+ },
642
+ responses: {
643
+ 200: {
644
+ content: {
645
+ "application/json": {
646
+ schema: z.object({
647
+ members: z.array(memberSchema),
648
+ total: z.number(),
649
+ limit: z.number(),
650
+ offset: z.number(),
651
+ }),
652
+ },
653
+ },
654
+ description: "Paginated group members, newest-joined first",
655
+ },
656
+ 404: {
657
+ content: { "application/json": { schema: errorSchema } },
658
+ description: "Group not found",
659
+ },
660
+ },
661
+ });
662
+
663
+ // --- Handlers ---
664
+
665
+ /** The `fx` response block: non-null exactly when the lens served rates. */
666
+ function fxResponseOf(sheet: FxRatesToBase | null) {
667
+ return sheet ? { baseCurrency: sheet.baseCurrency, asOf: sheet.asOf } : null;
668
+ }
669
+
670
+ export const groupsRouter = new OpenAPIHono<AppEnv>()
671
+ .openapi(listRoute, async (c) => {
672
+ const container = c.get("container");
673
+ const { db, logger } = container;
674
+ const { limit, offset, groupType, search, sort, order } =
675
+ c.req.valid("query");
676
+
677
+ // Resolve the FX lens ONCE per request (fail-soft: off/unavailable ⇒
678
+ // null) so every row on the page converts through the same sheet.
679
+ const fxSheet = await container.fx.getRatesToBase();
680
+ const rates = fxSheet?.rates ?? null;
681
+
682
+ // Every filter lives on `groups`, so one predicate serves the page, the
683
+ // aggregate-sorted statement, and `total` alike.
684
+ const where: SQL =
685
+ and(
686
+ isNull(groups.deletedAt),
687
+ ...(groupType ? [eq(groups.groupType, groupType)] : []),
688
+ ...(search
689
+ ? [
690
+ or(
691
+ ilike(groups.groupKey, `%${escapeLike(search)}%`),
692
+ ilike(groups.displayName, `%${escapeLike(search)}%`),
693
+ ),
694
+ ]
695
+ : []),
696
+ ) ?? sql`true`;
697
+
698
+ const totalPromise = db
699
+ .select({ count: count() })
700
+ .from(groups)
701
+ .where(where);
702
+
703
+ const listOpts = { where, sort, order, limit, offset, rates, logger };
704
+ const rowsPromise =
705
+ sort === "members" || sort === "revenue"
706
+ ? listByAggregate(db, listOpts)
707
+ : listByColumn(db, listOpts);
708
+
709
+ const [rows, totalRows] = await Promise.all([rowsPromise, totalPromise]);
710
+
711
+ return c.json(
712
+ {
713
+ groups: rows,
714
+ total: totalRows[0]?.count ?? 0,
715
+ limit,
716
+ offset,
717
+ fx: fxResponseOf(fxSheet),
718
+ },
719
+ 200,
720
+ );
721
+ })
722
+ // Registered before the `/{groupType}/{groupKey}` param route so the
723
+ // literal "types" isn't captured as a groupType.
724
+ .openapi(listTypesRoute, async (c) => {
725
+ const { db } = c.get("container");
726
+ const rows = await db
727
+ .select({ groupType: groups.groupType, count: count() })
728
+ .from(groups)
729
+ .where(isNull(groups.deletedAt))
730
+ .groupBy(groups.groupType)
731
+ .orderBy(desc(count()), asc(groups.groupType));
732
+ return c.json({ types: rows }, 200);
733
+ })
734
+ .openapi(listMembersRoute, async (c) => {
735
+ const { db } = c.get("container");
736
+ const { groupType, groupKey } = c.req.valid("param");
737
+ const { limit, offset } = c.req.valid("query");
738
+
739
+ const groupRows = await db
740
+ .select({ id: groups.id })
741
+ .from(groups)
742
+ .where(
743
+ and(
744
+ eq(groups.groupType, groupType),
745
+ eq(groups.groupKey, groupKey),
746
+ isNull(groups.deletedAt),
747
+ ),
748
+ )
749
+ .limit(1);
750
+ const group = groupRows[0];
751
+ if (!group) {
752
+ return c.json({ error: "Group not found" }, 404);
753
+ }
754
+
755
+ // Join to LIVE contacts so a soft-deleted contact never surfaces; the total
756
+ // counts the same joined set the page is drawn from.
757
+ const memberWhere = and(
758
+ eq(groupMemberships.groupId, group.id),
759
+ isNull(contacts.deletedAt),
760
+ );
761
+
762
+ const [rows, totalRows] = await Promise.all([
763
+ db
764
+ .select({
765
+ contactId: groupMemberships.contactId,
766
+ email: contacts.email,
767
+ externalId: contacts.externalId,
768
+ role: groupMemberships.role,
769
+ joinedAt: groupMemberships.joinedAt,
770
+ })
771
+ .from(groupMemberships)
772
+ .innerJoin(contacts, eq(groupMemberships.contactId, contacts.id))
773
+ .where(memberWhere)
774
+ .orderBy(desc(groupMemberships.joinedAt))
775
+ .limit(limit)
776
+ .offset(offset),
777
+ db
778
+ .select({ count: count() })
779
+ .from(groupMemberships)
780
+ .innerJoin(contacts, eq(groupMemberships.contactId, contacts.id))
781
+ .where(memberWhere),
782
+ ]);
783
+
784
+ return c.json(
785
+ {
786
+ members: rows.map(serializeMember),
787
+ total: totalRows[0]?.count ?? 0,
788
+ limit,
789
+ offset,
790
+ },
791
+ 200,
792
+ );
793
+ })
794
+ .openapi(getRoute, async (c) => {
795
+ const container = c.get("container");
796
+ const { db } = container;
797
+ const { groupType, groupKey } = c.req.valid("param");
798
+
799
+ const groupRows = await db
800
+ .select()
801
+ .from(groups)
802
+ .where(
803
+ and(
804
+ eq(groups.groupType, groupType),
805
+ eq(groups.groupKey, groupKey),
806
+ isNull(groups.deletedAt),
807
+ ),
808
+ )
809
+ .limit(1);
810
+ const group = groupRows[0];
811
+ if (!group) {
812
+ return c.json({ error: "Group not found" }, 404);
813
+ }
814
+
815
+ // Containment against this ONE group's natural key — the single-group twin
816
+ // of the list's lateral rollup, no expansion needed, and GIN-served.
817
+ const taggedEvents = groupContainment(groupType, groupKey);
818
+
819
+ const [memberCountRows, revenueRows, recentMemberRows, recentEventRows] =
820
+ await Promise.all([
821
+ // Same LIVE-contact join as recentMembers below (and as the members
822
+ // endpoint) so memberCount never disagrees with the list it heads.
823
+ db
824
+ .select({ count: count() })
825
+ .from(groupMemberships)
826
+ .innerJoin(contacts, eq(groupMemberships.contactId, contacts.id))
827
+ .where(
828
+ and(
829
+ eq(groupMemberships.groupId, group.id),
830
+ isNull(contacts.deletedAt),
831
+ ),
832
+ ),
833
+ // Per currency, never summed across them — the same law (and the same
834
+ // trust gate) as the list rollup and `getContactRevenue`.
835
+ db
836
+ .select({
837
+ currency: userEvents.currency,
838
+ total: sql<number>`sum(${userEvents.value})::float8`,
839
+ })
840
+ .from(userEvents)
841
+ .where(and(trustedValuedEventFilter(), taggedEvents))
842
+ .groupBy(userEvents.currency),
843
+ db
844
+ .select({
845
+ contactId: groupMemberships.contactId,
846
+ email: contacts.email,
847
+ externalId: contacts.externalId,
848
+ role: groupMemberships.role,
849
+ joinedAt: groupMemberships.joinedAt,
850
+ })
851
+ .from(groupMemberships)
852
+ .innerJoin(contacts, eq(groupMemberships.contactId, contacts.id))
853
+ .where(
854
+ and(
855
+ eq(groupMemberships.groupId, group.id),
856
+ isNull(contacts.deletedAt),
857
+ ),
858
+ )
859
+ .orderBy(desc(groupMemberships.joinedAt))
860
+ .limit(10),
861
+ // Events carry a `groups` association map (groupType → groupKey); the
862
+ // jsonb containment operator selects those tagged with this group.
863
+ db
864
+ .select({
865
+ id: userEvents.id,
866
+ event: userEvents.event,
867
+ occurredAt: userEvents.occurredAt,
868
+ userId: userEvents.userId,
869
+ })
870
+ .from(userEvents)
871
+ .where(taggedEvents)
872
+ .orderBy(desc(userEvents.occurredAt))
873
+ .limit(20),
874
+ ]);
875
+
876
+ const memberCount = memberCountRows[0]?.count ?? 0;
877
+ const revenueTotals: RevenueTotal[] = revenueRows
878
+ .map((r) => ({ currency: r.currency, total: Number(r.total) }))
879
+ .sort((a, b) => b.total - a.total);
880
+
881
+ // Same lens as the list: one sheet per request, fail-soft to null.
882
+ const fxSheet = await container.fx.getRatesToBase();
883
+
884
+ return c.json(
885
+ {
886
+ group: {
887
+ ...serializeGroup(
888
+ group,
889
+ memberCount,
890
+ revenueTotals,
891
+ fxSheet?.rates ?? null,
892
+ ),
893
+ recentMembers: recentMemberRows.map(serializeMember),
894
+ recentEvents: recentEventRows.map(serializeEvent),
895
+ },
896
+ fx: fxResponseOf(fxSheet),
897
+ },
898
+ 200,
899
+ );
900
+ });