@hogsend/engine 0.66.0 → 0.67.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.
@@ -0,0 +1,739 @@
1
+ import type { Database } from "@hogsend/db";
2
+ import { sql } from "drizzle-orm";
3
+
4
+ /**
5
+ * THE REFERRAL REPORT (PRD 05 §5.3). Model, window, depth and level weights
6
+ * are REQUEST parameters; nothing weighted is persisted, so changing your mind
7
+ * costs one query and backfills nothing.
8
+ *
9
+ * The whole tree walk is ONE recursive CTE. Doing it in TypeScript would mean
10
+ * shipping every edge of every referrer to the process to multiply five
11
+ * numbers, and the cycle guard (a referee who later refers an ancestor) would
12
+ * have to be re-implemented over the wire. Postgres already has `ARRAY` and
13
+ * `WITH RECURSIVE`.
14
+ *
15
+ * ## Currencies are never converted
16
+ *
17
+ * `conversions.value` carries `conversions.currency`, and this file has no FX
18
+ * rate and no business asking for one. Every monetary answer is a LIST of
19
+ * `{ currency, value }` pairs. The only place currency is flattened is the
20
+ * beneficiary ORDER (a leaderboard needs one axis), and that is documented at
21
+ * the sort itself rather than leaking into a returned number.
22
+ */
23
+
24
+ /**
25
+ * The referral model vocabulary. Deliberately NOT `@hogsend/attribution`'s
26
+ * `ATTRIBUTION_MODELS`: that list is a marketing-touchpoint vocabulary
27
+ * (`lastNonDirect`, `blended`, `positionU` vs `positionW`) whose ids do not
28
+ * name the thing a referral edge is. These five are the models a referral
29
+ * report can answer with the columns `referral_touches` actually has.
30
+ */
31
+ export const REFERRAL_MODELS = [
32
+ "first_touch",
33
+ "last_touch",
34
+ "linear",
35
+ "time_decay",
36
+ "position",
37
+ ] as const;
38
+
39
+ export type ReferralModel = (typeof REFERRAL_MODELS)[number];
40
+
41
+ /** Time-decay half-life, matching `@hogsend/attribution`'s default. */
42
+ const TIME_DECAY_HALF_LIFE_DAYS = 7;
43
+
44
+ /** PRD 05 §5.3: the walk is capped, in the engine, at five levels. */
45
+ export const REFERRAL_REPORT_MAX_DEPTH = 5;
46
+
47
+ /** ISO 4217's "no currency" code - used when a conversion carries none. */
48
+ export const NO_CURRENCY = "XXX";
49
+
50
+ const MS = {
51
+ s: 1_000,
52
+ m: 60_000,
53
+ h: 3_600_000,
54
+ d: 86_400_000,
55
+ w: 604_800_000,
56
+ } as const;
57
+
58
+ const WINDOW_RE = /^(\d+(?:\.\d+)?)(ms|s|m|h|d|w)$/;
59
+
60
+ export class InvalidWindowError extends Error {}
61
+
62
+ /**
63
+ * Parse a duration string (`"30d"`, `"12h"`, `"90m"`) to milliseconds. The
64
+ * window applies to the TOUCH -> BIND gap: an edge whose referee identified
65
+ * later than this after the touch is not eligible for the report, whatever the
66
+ * program's own `bindWindow` was when the row was written.
67
+ */
68
+ export function parseWindowMs(input: string): number {
69
+ const match = WINDOW_RE.exec(input.trim());
70
+ if (!match) {
71
+ throw new InvalidWindowError(
72
+ `invalid window "${input}" - use <number><unit> with unit ` +
73
+ "ms, s, m, h, d or w (for example 30d)",
74
+ );
75
+ }
76
+ const value = Number(match[1]);
77
+ const unit = match[2] as keyof typeof MS | "ms";
78
+ const ms = unit === "ms" ? value : value * MS[unit as keyof typeof MS];
79
+ if (!(ms > 0)) {
80
+ throw new InvalidWindowError(`window "${input}" is not positive`);
81
+ }
82
+ return ms;
83
+ }
84
+
85
+ /**
86
+ * The level weight vector. Level 1 (the direct referrer) defaults to 1 and
87
+ * every deeper level to 0, so adding `depth` WITHOUT adding weights widens the
88
+ * tree counts but changes no revenue number.
89
+ */
90
+ export function resolveLevelWeights(
91
+ depth: number,
92
+ weights: number[] | undefined,
93
+ ): number[] {
94
+ const out: number[] = [];
95
+ for (let level = 1; level <= depth; level++) {
96
+ const supplied = weights?.[level - 1];
97
+ out.push(supplied ?? (level === 1 ? 1 : 0));
98
+ }
99
+ return out;
100
+ }
101
+
102
+ export interface CurrencyValue {
103
+ currency: string;
104
+ value: number;
105
+ }
106
+
107
+ export interface ReferralTreeLevel {
108
+ level: number;
109
+ /** Distinct referee contacts at this level of this beneficiary's tree. */
110
+ referees: number;
111
+ /** Conversions those referees fired inside `from`/`to`. */
112
+ conversions: number;
113
+ /** `levelWeight * edgeWeightProduct * conversion value`, per currency. */
114
+ value: CurrencyValue[];
115
+ }
116
+
117
+ export interface ReferralBeneficiary {
118
+ contactId: string;
119
+ direct: { touched: number; bound: number; qualified: number };
120
+ tree: ReferralTreeLevel[];
121
+ /** The tree's value, summed across levels, per currency. */
122
+ value: CurrencyValue[];
123
+ }
124
+
125
+ export interface ReferralReportOptions {
126
+ db: Database;
127
+ referralId: string;
128
+ model: ReferralModel;
129
+ /** Touch -> bind gap ceiling, in milliseconds. */
130
+ windowMs: number;
131
+ depth: number;
132
+ /** One weight per level, index 0 = level 1. */
133
+ levelWeights: number[];
134
+ from?: Date;
135
+ to?: Date;
136
+ limit: number;
137
+ offset: number;
138
+ }
139
+
140
+ export interface ReferralReport {
141
+ beneficiaries: ReferralBeneficiary[];
142
+ /** Opaque cursor for the next page, or null at the end. */
143
+ nextOffset: number | null;
144
+ }
145
+
146
+ interface TreeRow {
147
+ beneficiary: string;
148
+ level: number;
149
+ referees: number;
150
+ currency: string | null;
151
+ conversions: number | null;
152
+ value: number | null;
153
+ }
154
+
155
+ interface DirectRow {
156
+ referrer: string;
157
+ touched: number;
158
+ bound: number;
159
+ qualified: number;
160
+ }
161
+
162
+ /**
163
+ * The eligible-edge + per-referee weighting CTE, shared by the report and the
164
+ * tree drill-in. Emits `(referee, referrer, weight)` with each referee's
165
+ * weights summing to 1.
166
+ */
167
+ function edgesCte(opts: {
168
+ referralId: string;
169
+ model: ReferralModel;
170
+ windowMs: number;
171
+ }) {
172
+ const { referralId, model, windowMs } = opts;
173
+ const windowSeconds = windowMs / 1000;
174
+ const halfLifeSeconds = TIME_DECAY_HALF_LIFE_DAYS * 86_400;
175
+ return sql`
176
+ elig AS (
177
+ SELECT t.id, t.referee_contact_id AS referee,
178
+ t.referrer_contact_id AS referrer, t.touched_at
179
+ FROM referral_touches t
180
+ WHERE t.referral_id = ${referralId}
181
+ AND t.referee_contact_id IS NOT NULL
182
+ AND t.status IN ('bound', 'qualified')
183
+ AND t.bound_at IS NOT NULL
184
+ AND EXTRACT(EPOCH FROM (t.bound_at - t.touched_at))
185
+ <= ${windowSeconds}::float8
186
+ ),
187
+ ranked AS (
188
+ SELECT e.*,
189
+ row_number() OVER (
190
+ PARTITION BY e.referee ORDER BY e.touched_at, e.id
191
+ ) AS rn,
192
+ count(*) OVER (PARTITION BY e.referee) AS n,
193
+ max(e.touched_at) OVER (PARTITION BY e.referee) AS last_at
194
+ FROM elig e
195
+ ),
196
+ scored AS (
197
+ SELECT r.referee, r.referrer,
198
+ CASE ${model}::text
199
+ WHEN 'first_touch' THEN CASE WHEN r.rn = 1 THEN 1 ELSE 0 END
200
+ WHEN 'last_touch' THEN CASE WHEN r.rn = r.n THEN 1 ELSE 0 END
201
+ WHEN 'linear' THEN 1.0 / r.n
202
+ WHEN 'time_decay' THEN power(
203
+ 0.5,
204
+ EXTRACT(EPOCH FROM (r.last_at - r.touched_at))
205
+ / ${halfLifeSeconds}::float8
206
+ )
207
+ WHEN 'position' THEN CASE
208
+ WHEN r.n = 1 THEN 1
209
+ WHEN r.n = 2 THEN 0.5
210
+ WHEN r.rn = 1 OR r.rn = r.n THEN 0.4
211
+ ELSE 0.2 / (r.n - 2)
212
+ END
213
+ END::float8 AS raw
214
+ FROM ranked r
215
+ ),
216
+ edges AS (
217
+ SELECT s.referee, s.referrer,
218
+ s.raw / NULLIF(SUM(s.raw) OVER (PARTITION BY s.referee), 0)
219
+ AS weight
220
+ FROM scored s
221
+ WHERE s.raw > 0
222
+ )
223
+ `;
224
+ }
225
+
226
+ /** `conversions` filtered to the report window, as `(referee, id, ...)`. */
227
+ function conversionsCte(from: Date | undefined, to: Date | undefined) {
228
+ return sql`
229
+ conv AS (
230
+ SELECT c.contact_id AS referee, c.id,
231
+ COALESCE(c.value, 0)::float8 AS value,
232
+ COALESCE(c.currency, ${NO_CURRENCY}) AS currency
233
+ FROM conversions c
234
+ WHERE (${from ? sql`c.occurred_at >= ${from.toISOString()}::timestamptz` : sql`TRUE`})
235
+ AND (${to ? sql`c.occurred_at <= ${to.toISOString()}::timestamptz` : sql`TRUE`})
236
+ )
237
+ `;
238
+ }
239
+
240
+ /**
241
+ * Run the report. Two queries: the tree (one recursive CTE) and the direct
242
+ * touch counts for the page's beneficiaries. The direct counts are deliberately
243
+ * NOT model-filtered - "how many people did this person touch" is a fact about
244
+ * the referrer, not about the model the reader picked today.
245
+ */
246
+ export async function getReferralReport(
247
+ opts: ReferralReportOptions,
248
+ ): Promise<ReferralReport> {
249
+ const { db, referralId, depth, levelWeights, from, to, limit, offset } = opts;
250
+
251
+ const weightRows = levelWeights.map(
252
+ (weight, i) => sql`(${i + 1}::int, ${weight}::float8)`,
253
+ );
254
+
255
+ const rows = (await db.execute(sql`
256
+ WITH RECURSIVE
257
+ ${edgesCte(opts)},
258
+ lw(level, level_weight) AS (VALUES ${sql.join(weightRows, sql`, `)}),
259
+ ${conversionsCte(from, to)},
260
+ tree AS (
261
+ SELECT e.referee, e.referrer AS beneficiary, 1 AS level,
262
+ e.weight AS weight,
263
+ ARRAY[e.referee, e.referrer] AS path
264
+ FROM edges e
265
+ UNION ALL
266
+ SELECT t.referee, e.referrer, t.level + 1, t.weight * e.weight,
267
+ t.path || e.referrer
268
+ FROM tree t
269
+ JOIN edges e ON e.referee = t.beneficiary
270
+ WHERE t.level < ${depth}::int
271
+ AND NOT (e.referrer = ANY(t.path))
272
+ ),
273
+ levels AS (
274
+ SELECT t.beneficiary, t.level, count(DISTINCT t.referee)::int AS referees
275
+ FROM tree t
276
+ GROUP BY 1, 2
277
+ ),
278
+ vals AS (
279
+ SELECT t.beneficiary, t.level, cv.currency,
280
+ count(DISTINCT cv.id)::int AS conversions,
281
+ SUM(cv.value * t.weight * lw.level_weight)::float8 AS value
282
+ FROM tree t
283
+ JOIN conv cv ON cv.referee = t.referee
284
+ JOIN lw ON lw.level = t.level
285
+ GROUP BY 1, 2, 3
286
+ )
287
+ SELECT l.beneficiary::text AS beneficiary, l.level, l.referees,
288
+ v.currency, v.conversions, v.value
289
+ FROM levels l
290
+ LEFT JOIN vals v
291
+ ON v.beneficiary = l.beneficiary AND v.level = l.level
292
+ ORDER BY l.beneficiary, l.level
293
+ `)) as unknown as { rows?: TreeRow[] } | TreeRow[];
294
+
295
+ const treeRows: TreeRow[] = Array.isArray(rows) ? rows : (rows.rows ?? []);
296
+
297
+ // Fold (beneficiary, level, currency) rows into the nested output shape.
298
+ const byBeneficiary = new Map<string, Map<number, ReferralTreeLevel>>();
299
+ for (const row of treeRows) {
300
+ const levels =
301
+ byBeneficiary.get(row.beneficiary) ??
302
+ new Map<number, ReferralTreeLevel>();
303
+ byBeneficiary.set(row.beneficiary, levels);
304
+ const level = levels.get(row.level) ?? {
305
+ level: row.level,
306
+ referees: Number(row.referees),
307
+ conversions: 0,
308
+ value: [],
309
+ };
310
+ if (row.currency) {
311
+ level.conversions += Number(row.conversions ?? 0);
312
+ const value = Number(row.value ?? 0);
313
+ if (value !== 0) {
314
+ level.value.push({ currency: row.currency, value });
315
+ }
316
+ }
317
+ levels.set(row.level, level);
318
+ }
319
+
320
+ const all: ReferralBeneficiary[] = [...byBeneficiary.entries()].map(
321
+ ([contactId, levels]) => {
322
+ const tree = [...levels.values()].sort((a, b) => a.level - b.level);
323
+ const totals = new Map<string, number>();
324
+ for (const level of tree) {
325
+ for (const entry of level.value) {
326
+ totals.set(
327
+ entry.currency,
328
+ (totals.get(entry.currency) ?? 0) + entry.value,
329
+ );
330
+ }
331
+ }
332
+ return {
333
+ contactId,
334
+ direct: { touched: 0, bound: 0, qualified: 0 },
335
+ tree,
336
+ value: [...totals.entries()]
337
+ .map(([currency, value]) => ({ currency, value }))
338
+ .sort((a, b) => a.currency.localeCompare(b.currency)),
339
+ };
340
+ },
341
+ );
342
+
343
+ // The leaderboard ORDER sums across currencies. That is a sort key, never a
344
+ // returned number: no rate is applied and no converted total is exposed.
345
+ all.sort((a, b) => {
346
+ const sum = (x: ReferralBeneficiary) =>
347
+ x.value.reduce((acc, v) => acc + v.value, 0);
348
+ const delta = sum(b) - sum(a);
349
+ return delta !== 0 ? delta : a.contactId.localeCompare(b.contactId);
350
+ });
351
+
352
+ const page = all.slice(offset, offset + limit);
353
+ const nextOffset = offset + limit < all.length ? offset + limit : null;
354
+
355
+ if (page.length > 0) {
356
+ const ids = page.map((b) => b.contactId);
357
+ const direct = (await db.execute(sql`
358
+ SELECT t.referrer_contact_id::text AS referrer,
359
+ count(*) FILTER (WHERE t.status <> 'rejected')::int AS touched,
360
+ count(*) FILTER (
361
+ WHERE t.status IN ('bound', 'qualified')
362
+ )::int AS bound,
363
+ count(*) FILTER (WHERE t.status = 'qualified')::int AS qualified
364
+ FROM referral_touches t
365
+ WHERE t.referral_id = ${referralId}
366
+ AND t.referrer_contact_id IN (${sql.join(
367
+ ids.map((id) => sql`${id}::uuid`),
368
+ sql`, `,
369
+ )})
370
+ GROUP BY 1
371
+ `)) as unknown as { rows?: DirectRow[] } | DirectRow[];
372
+ const directRows: DirectRow[] = Array.isArray(direct)
373
+ ? direct
374
+ : (direct.rows ?? []);
375
+ const byId = new Map(directRows.map((r) => [r.referrer, r]));
376
+ for (const beneficiary of page) {
377
+ const row = byId.get(beneficiary.contactId);
378
+ if (!row) continue;
379
+ beneficiary.direct = {
380
+ touched: Number(row.touched),
381
+ bound: Number(row.bound),
382
+ qualified: Number(row.qualified),
383
+ };
384
+ }
385
+ }
386
+
387
+ return { beneficiaries: page, nextOffset };
388
+ }
389
+
390
+ // ---------------------------------------------------------------------------
391
+ // tree drill-in
392
+ // ---------------------------------------------------------------------------
393
+
394
+ export interface ReferralTreeNode {
395
+ contactId: string;
396
+ level: number;
397
+ /** The contact one hop up - the beneficiary's own referrer at `level - 1`. */
398
+ viaContactId: string;
399
+ status: string;
400
+ touchedAt: string;
401
+ boundAt: string | null;
402
+ qualifiedAt: string | null;
403
+ conversions: number;
404
+ value: CurrencyValue[];
405
+ }
406
+
407
+ export interface ReferralTreeOptions {
408
+ db: Database;
409
+ referralId: string;
410
+ contactId: string;
411
+ depth: number;
412
+ limit: number;
413
+ }
414
+
415
+ interface TreeNodeRow {
416
+ contact_id: string;
417
+ level: number;
418
+ via_contact_id: string;
419
+ status: string;
420
+ touched_at: string | Date;
421
+ bound_at: string | Date | null;
422
+ qualified_at: string | Date | null;
423
+ currency: string | null;
424
+ conversions: number | null;
425
+ value: number | null;
426
+ }
427
+
428
+ /**
429
+ * The DESCENDANTS of one referrer, to `depth`. Unlike the report this is a
430
+ * ledger view, not a model: every non-rejected edge is walked, no window is
431
+ * applied, and nothing is weighted. It answers "who did this person bring in,
432
+ * and what happened to them".
433
+ */
434
+ export async function getReferralTree(
435
+ opts: ReferralTreeOptions,
436
+ ): Promise<ReferralTreeNode[]> {
437
+ const { db, referralId, contactId, depth, limit } = opts;
438
+
439
+ const rows = (await db.execute(sql`
440
+ WITH RECURSIVE
441
+ live AS (
442
+ SELECT t.referrer_contact_id AS referrer,
443
+ t.referee_contact_id AS referee,
444
+ t.status, t.touched_at, t.bound_at, t.qualified_at
445
+ FROM referral_touches t
446
+ WHERE t.referral_id = ${referralId}
447
+ AND t.referee_contact_id IS NOT NULL
448
+ AND t.status <> 'rejected'
449
+ ),
450
+ walk AS (
451
+ SELECT l.referee AS contact_id, 1 AS level,
452
+ l.referrer AS via_contact_id, l.status,
453
+ l.touched_at, l.bound_at, l.qualified_at,
454
+ ARRAY[l.referrer, l.referee] AS path
455
+ FROM live l
456
+ WHERE l.referrer = ${contactId}::uuid
457
+ UNION ALL
458
+ SELECT l.referee, w.level + 1, l.referrer, l.status,
459
+ l.touched_at, l.bound_at, l.qualified_at,
460
+ w.path || l.referee
461
+ FROM walk w
462
+ JOIN live l ON l.referrer = w.contact_id
463
+ WHERE w.level < ${depth}::int
464
+ AND NOT (l.referee = ANY(w.path))
465
+ ),
466
+ conv AS (
467
+ SELECT c.contact_id AS referee,
468
+ COALESCE(c.currency, ${NO_CURRENCY}) AS currency,
469
+ count(*)::int AS conversions,
470
+ COALESCE(SUM(c.value), 0)::float8 AS value
471
+ FROM conversions c
472
+ GROUP BY 1, 2
473
+ ),
474
+ -- The cap is on NODES. Applying it after the currency join would let a
475
+ -- two-currency node consume two slots and cut its own value list short.
476
+ nodes AS (
477
+ SELECT * FROM walk
478
+ ORDER BY level, touched_at
479
+ LIMIT ${limit}::int
480
+ )
481
+ SELECT w.contact_id::text AS contact_id, w.level,
482
+ w.via_contact_id::text AS via_contact_id, w.status,
483
+ w.touched_at, w.bound_at, w.qualified_at,
484
+ cv.currency, cv.conversions, cv.value
485
+ FROM nodes w
486
+ LEFT JOIN conv cv ON cv.referee = w.contact_id
487
+ ORDER BY w.level, w.touched_at, cv.currency
488
+ `)) as unknown as { rows?: TreeNodeRow[] } | TreeNodeRow[];
489
+
490
+ const nodeRows: TreeNodeRow[] = Array.isArray(rows)
491
+ ? rows
492
+ : (rows.rows ?? []);
493
+
494
+ const byNode = new Map<string, ReferralTreeNode>();
495
+ for (const row of nodeRows) {
496
+ const key = `${row.contact_id}:${row.level}:${row.via_contact_id}`;
497
+ const node = byNode.get(key) ?? {
498
+ contactId: row.contact_id,
499
+ level: Number(row.level),
500
+ viaContactId: row.via_contact_id,
501
+ status: row.status,
502
+ touchedAt: new Date(row.touched_at).toISOString(),
503
+ boundAt: row.bound_at ? new Date(row.bound_at).toISOString() : null,
504
+ qualifiedAt: row.qualified_at
505
+ ? new Date(row.qualified_at).toISOString()
506
+ : null,
507
+ conversions: 0,
508
+ value: [],
509
+ };
510
+ if (row.currency) {
511
+ node.conversions += Number(row.conversions ?? 0);
512
+ node.value.push({
513
+ currency: row.currency,
514
+ value: Number(row.value ?? 0),
515
+ });
516
+ }
517
+ byNode.set(key, node);
518
+ }
519
+ return [...byNode.values()];
520
+ }
521
+
522
+ // ---------------------------------------------------------------------------
523
+ // overview
524
+ // ---------------------------------------------------------------------------
525
+
526
+ export interface ReferralOverviewOptions {
527
+ db: Database;
528
+ referralId: string;
529
+ /** Period start; omitted = all time. */
530
+ from?: Date;
531
+ to?: Date;
532
+ }
533
+
534
+ export interface ReferralSeriesPoint {
535
+ date: string;
536
+ touched: number;
537
+ bound: number;
538
+ qualified: number;
539
+ }
540
+
541
+ export interface ReferralOverview {
542
+ /** Distinct referrers with at least one non-rejected touch in the period. */
543
+ referrers: number;
544
+ /** Live `shared` links minted for this referral (not period-bounded). */
545
+ links: number;
546
+ funnel: {
547
+ touched: number;
548
+ bound: number;
549
+ qualified: number;
550
+ /** Bound/qualified referees with at least one conversion in the period. */
551
+ converted: number;
552
+ };
553
+ rejected: { total: number; byReason: { reason: string; count: number }[] };
554
+ sources: { source: string; count: number }[];
555
+ /**
556
+ * Conversions fired by referred contacts in the period, per currency: the
557
+ * ledger's number, before any model or level weight. The leaderboard's
558
+ * weighted totals can only be less than or equal to this.
559
+ */
560
+ refereeValue: CurrencyValue[];
561
+ /** `day` under ~3 months of range, else `week`. */
562
+ granularity: "day" | "week";
563
+ series: ReferralSeriesPoint[];
564
+ }
565
+
566
+ interface CountRow {
567
+ key: string | null;
568
+ count: number;
569
+ }
570
+
571
+ const WEEK_THRESHOLD_MS = 92 * MS.d;
572
+
573
+ function rowsOf<T>(result: unknown): T[] {
574
+ return Array.isArray(result)
575
+ ? (result as T[])
576
+ : ((result as { rows?: T[] }).rows ?? []);
577
+ }
578
+
579
+ /**
580
+ * The program-level numbers the Studio header reads. Every count comes from
581
+ * `referral_touches` (plus `links` for the mint count and `conversions` for
582
+ * the money), bounded by the same `from`/`to` the leaderboard takes, so the
583
+ * tiles and the table describe one period.
584
+ */
585
+ export async function getReferralOverview(
586
+ opts: ReferralOverviewOptions,
587
+ ): Promise<ReferralOverview> {
588
+ const { db, referralId, from, to } = opts;
589
+ const inPeriod = (col: ReturnType<typeof sql>) => sql`
590
+ (${from ? sql`${col} >= ${from.toISOString()}::timestamptz` : sql`TRUE`})
591
+ AND (${to ? sql`${col} <= ${to.toISOString()}::timestamptz` : sql`TRUE`})
592
+ `;
593
+
594
+ const [totals, rejected, sources, value, linkCount, bounds] =
595
+ await Promise.all([
596
+ db.execute(sql`
597
+ SELECT
598
+ count(*) FILTER (WHERE t.status <> 'rejected')::int AS touched,
599
+ count(*) FILTER (WHERE t.status IN ('bound','qualified'))::int AS bound,
600
+ count(*) FILTER (WHERE t.status = 'qualified')::int AS qualified,
601
+ count(DISTINCT t.referrer_contact_id)
602
+ FILTER (WHERE t.status <> 'rejected')::int AS referrers,
603
+ count(DISTINCT t.referee_contact_id) FILTER (
604
+ WHERE t.status IN ('bound','qualified')
605
+ AND EXISTS (
606
+ SELECT 1 FROM conversions c
607
+ WHERE c.contact_id = t.referee_contact_id
608
+ AND ${inPeriod(sql`c.occurred_at`)}
609
+ )
610
+ )::int AS converted
611
+ FROM referral_touches t
612
+ WHERE t.referral_id = ${referralId}
613
+ AND ${inPeriod(sql`t.touched_at`)}
614
+ `),
615
+ db.execute(sql`
616
+ SELECT t.rejected_reason AS key, count(*)::int AS count
617
+ FROM referral_touches t
618
+ WHERE t.referral_id = ${referralId}
619
+ AND t.status = 'rejected'
620
+ AND ${inPeriod(sql`t.touched_at`)}
621
+ GROUP BY 1 ORDER BY 2 DESC
622
+ `),
623
+ db.execute(sql`
624
+ SELECT t.source AS key, count(*)::int AS count
625
+ FROM referral_touches t
626
+ WHERE t.referral_id = ${referralId}
627
+ AND ${inPeriod(sql`t.touched_at`)}
628
+ GROUP BY 1 ORDER BY 2 DESC
629
+ `),
630
+ db.execute(sql`
631
+ SELECT COALESCE(c.currency, ${NO_CURRENCY}) AS key,
632
+ COALESCE(SUM(c.value), 0)::float8 AS count
633
+ FROM conversions c
634
+ WHERE ${inPeriod(sql`c.occurred_at`)}
635
+ AND EXISTS (
636
+ SELECT 1 FROM referral_touches t
637
+ WHERE t.referral_id = ${referralId}
638
+ AND t.referee_contact_id = c.contact_id
639
+ AND t.status IN ('bound','qualified')
640
+ )
641
+ GROUP BY 1 ORDER BY 1
642
+ `),
643
+ db.execute(sql`
644
+ SELECT count(*)::int AS count, NULL::text AS key
645
+ FROM links l
646
+ WHERE l.referral_id = ${referralId} AND l.archived_at IS NULL
647
+ `),
648
+ db.execute(sql`
649
+ SELECT min(t.touched_at) AS key, count(*)::int AS count
650
+ FROM referral_touches t
651
+ WHERE t.referral_id = ${referralId}
652
+ `),
653
+ ]);
654
+
655
+ const totalRow = rowsOf<{
656
+ touched: number;
657
+ bound: number;
658
+ qualified: number;
659
+ referrers: number;
660
+ converted: number;
661
+ }>(totals)[0];
662
+
663
+ // The series needs a concrete start: the period's `from`, else the first
664
+ // touch on record, else now (an empty program draws an empty chart).
665
+ const firstTouch = rowsOf<CountRow>(bounds)[0]?.key;
666
+ const start = from ?? (firstTouch ? new Date(firstTouch) : new Date());
667
+ const end = to ?? new Date();
668
+ const granularity: "day" | "week" =
669
+ end.getTime() - start.getTime() > WEEK_THRESHOLD_MS ? "week" : "day";
670
+
671
+ const series = rowsOf<{
672
+ bucket: string | Date;
673
+ touched: number;
674
+ bound: number;
675
+ qualified: number;
676
+ }>(
677
+ await db.execute(sql`
678
+ WITH buckets AS (
679
+ SELECT generate_series(
680
+ date_trunc(${granularity}, ${start.toISOString()}::timestamptz),
681
+ date_trunc(${granularity}, ${end.toISOString()}::timestamptz),
682
+ ${granularity === "day" ? "1 day" : "1 week"}::interval
683
+ ) AS bucket
684
+ ),
685
+ t AS (
686
+ SELECT * FROM referral_touches
687
+ WHERE referral_id = ${referralId}
688
+ )
689
+ SELECT b.bucket,
690
+ (SELECT count(*)::int FROM t
691
+ WHERE t.status <> 'rejected'
692
+ AND date_trunc(${granularity}, t.touched_at) = b.bucket) AS touched,
693
+ (SELECT count(*)::int FROM t
694
+ WHERE t.bound_at IS NOT NULL AND t.status <> 'rejected'
695
+ AND date_trunc(${granularity}, t.bound_at) = b.bucket) AS bound,
696
+ (SELECT count(*)::int FROM t
697
+ WHERE t.qualified_at IS NOT NULL
698
+ AND date_trunc(${granularity}, t.qualified_at) = b.bucket) AS qualified
699
+ FROM buckets b
700
+ ORDER BY b.bucket
701
+ `),
702
+ );
703
+
704
+ const asCounts = (result: unknown, fallback: string) =>
705
+ rowsOf<CountRow>(result).map((r) => ({
706
+ key: r.key ?? fallback,
707
+ count: Number(r.count),
708
+ }));
709
+ const rejectedRows = asCounts(rejected, "unknown");
710
+
711
+ return {
712
+ referrers: Number(totalRow?.referrers ?? 0),
713
+ links: Number(rowsOf<CountRow>(linkCount)[0]?.count ?? 0),
714
+ funnel: {
715
+ touched: Number(totalRow?.touched ?? 0),
716
+ bound: Number(totalRow?.bound ?? 0),
717
+ qualified: Number(totalRow?.qualified ?? 0),
718
+ converted: Number(totalRow?.converted ?? 0),
719
+ },
720
+ rejected: {
721
+ total: rejectedRows.reduce((acc, r) => acc + r.count, 0),
722
+ byReason: rejectedRows.map((r) => ({ reason: r.key, count: r.count })),
723
+ },
724
+ sources: asCounts(sources, "unknown").map((r) => ({
725
+ source: r.key,
726
+ count: r.count,
727
+ })),
728
+ refereeValue: rowsOf<CountRow>(value)
729
+ .map((r) => ({ currency: r.key ?? NO_CURRENCY, value: Number(r.count) }))
730
+ .filter((v) => v.value !== 0),
731
+ granularity,
732
+ series: series.map((p) => ({
733
+ date: new Date(p.bucket).toISOString(),
734
+ touched: Number(p.touched),
735
+ bound: Number(p.bound),
736
+ qualified: Number(p.qualified),
737
+ })),
738
+ };
739
+ }