@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.
- package/package.json +12 -12
- package/src/container.ts +77 -0
- package/src/index.ts +78 -0
- package/src/lib/contacts.ts +70 -0
- package/src/lib/ingestion.ts +61 -0
- package/src/lib/links.ts +94 -11
- package/src/lib/outbound.ts +94 -0
- package/src/lib/referral-intent.ts +723 -0
- package/src/lib/referral-link.ts +200 -0
- package/src/lib/referral-registry.ts +83 -0
- package/src/lib/referral-report.ts +739 -0
- package/src/lib/referral-runtime.ts +49 -0
- package/src/lib/referrals-no-emit.test.ts +109 -0
- package/src/lib/referrals.ts +712 -0
- package/src/lib/webhook-signing.ts +10 -0
- package/src/routes/admin/api-keys.ts +5 -0
- package/src/routes/admin/index.ts +2 -0
- package/src/routes/admin/links.ts +14 -5
- package/src/routes/admin/referrals.ts +565 -0
- package/src/routes/contacts/index.ts +78 -0
- package/src/routes/index.ts +39 -0
- package/src/routes/referrals/index.ts +41 -0
- package/src/routes/referrals/me.ts +123 -0
- package/src/routes/referrals/report.ts +285 -0
- package/src/routes/referrals/shared.ts +34 -0
- package/src/routes/referrals/touch.ts +313 -0
- package/src/routes/tracking/arrive.ts +90 -0
- package/src/routes/tracking/click-pipeline.ts +8 -0
|
@@ -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
|
+
}
|