@hogsend/engine 0.65.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/account-links/battlenet.ts +84 -0
- package/src/account-links/epic.ts +87 -0
- package/src/account-links/index.ts +12 -5
- package/src/account-links/riot.ts +82 -0
- package/src/account-links/xbox.ts +92 -0
- package/src/app.ts +9 -1
- package/src/container.ts +77 -0
- package/src/env.ts +18 -2
- package/src/index.ts +84 -0
- package/src/lib/account-links-from-env.ts +94 -30
- package/src/lib/contacts.ts +94 -2
- 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/snippet.ts +76 -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 +45 -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/snippet.test.ts +70 -0
- package/src/routes/snippet.ts +58 -0
- package/src/routes/tracking/arrive.ts +90 -0
- package/src/routes/tracking/click-pipeline.ts +8 -0
- package/src/workflows/import-contacts.ts +6 -0
|
@@ -0,0 +1,723 @@
|
|
|
1
|
+
import type { HatchetClient } from "@hatchet-dev/typescript-sdk/v1/index.js";
|
|
2
|
+
import type { AnalyticsProvider, DefinedReferral } from "@hogsend/core";
|
|
3
|
+
import { evaluatePropertyConditions } from "@hogsend/core";
|
|
4
|
+
import type { JourneyRegistry } from "@hogsend/core/registry";
|
|
5
|
+
import {
|
|
6
|
+
attributionCredits,
|
|
7
|
+
contacts,
|
|
8
|
+
type Database,
|
|
9
|
+
referralTouches,
|
|
10
|
+
userEvents,
|
|
11
|
+
} from "@hogsend/db";
|
|
12
|
+
import { and, asc, eq, inArray, isNull, sql } from "drizzle-orm";
|
|
13
|
+
import { getJourneyRegistrySingleton } from "../journeys/registry-singleton.js";
|
|
14
|
+
import { getAnalytics } from "./analytics-singleton.js";
|
|
15
|
+
import { createLogger, type Logger } from "./logger.js";
|
|
16
|
+
import {
|
|
17
|
+
emitOutbound,
|
|
18
|
+
type OutboundPayloads,
|
|
19
|
+
type ReferralTouchPayload,
|
|
20
|
+
} from "./outbound.js";
|
|
21
|
+
import type { ReferralRegistry } from "./referral-registry.js";
|
|
22
|
+
import { getReferralRuntime } from "./referral-runtime.js";
|
|
23
|
+
import {
|
|
24
|
+
bindTouches,
|
|
25
|
+
qualifyTouch,
|
|
26
|
+
type ReferralTouchRecord,
|
|
27
|
+
type ReferralTouchSource,
|
|
28
|
+
recordTouch,
|
|
29
|
+
} from "./referrals.js";
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* THE REFERRAL INTENT LAYER (PRD 05 §6, stage 3) - the ONLY module that calls
|
|
33
|
+
* the store's mutators AND emits. The split is the same one
|
|
34
|
+
* `lib/account-links.ts` / `lib/account-link-ingest.ts` draw, for the same
|
|
35
|
+
* reason:
|
|
36
|
+
*
|
|
37
|
+
* - `lib/referrals.ts` (the STORE) writes `referral_touches` and NEVER emits.
|
|
38
|
+
* Two tests pin that (`referrals-no-emit.test.ts`).
|
|
39
|
+
* - THIS module calls the store, reads the returned FACTS, and fans each fact
|
|
40
|
+
* out onto BOTH planes, side by side:
|
|
41
|
+
* • the OUTBOUND spine (`emitOutbound`) → `webhook_deliveries` → the
|
|
42
|
+
* customer's subscriber. Full state, dedupe-keyed.
|
|
43
|
+
* • the JOURNEY plane (`ingestEvent`) → `user_events` + a Hatchet push, so
|
|
44
|
+
* `defineJourney({ trigger: { event: "referral.qualified" } })` fires.
|
|
45
|
+
*
|
|
46
|
+
* NEITHER PLANE MAY BE COLLAPSED INTO THE OTHER. Delete either and the other
|
|
47
|
+
* keeps working silently: an outbound-only build leaves every reward journey
|
|
48
|
+
* dead; an ingest-only build leaves every customer mirror stale.
|
|
49
|
+
*
|
|
50
|
+
* ## Identity law
|
|
51
|
+
*
|
|
52
|
+
* Every re-ingest carries the engine-internal `contactId` PIN. The bare
|
|
53
|
+
* canonical key of a referrer is `contactKey()` - possibly an ANONYMOUS id -
|
|
54
|
+
* and passing that alone would have the resolver read it as `external` and
|
|
55
|
+
* mint `external_id = <anonId>` (the ghost-contact law). The referee side of a
|
|
56
|
+
* COLD touch has no contact at all, which is exactly why `referral.touched` is
|
|
57
|
+
* emitted to the REFERRER only: the referee is a browser id, not a person, and
|
|
58
|
+
* minting a CRM row for them is the very thing PRD 02 forbade.
|
|
59
|
+
*
|
|
60
|
+
* ## Replay / exactly-once
|
|
61
|
+
*
|
|
62
|
+
* Every emit is dedupe-keyed off a durable row id, never a clock:
|
|
63
|
+
* `referral:touch:<touchId>`, `referral:bound:<touchId>`,
|
|
64
|
+
* `referral:qualified:<touchId>`, `referral:conv:<conversionId>:<beneficiary>`.
|
|
65
|
+
* The bus keys append the RECIPIENT contact id, because `user_events`
|
|
66
|
+
* `idempotency_key` is globally unique and a two-sided fact (bound / qualified
|
|
67
|
+
* reaches referrer AND referee) would otherwise deliver to one of them only.
|
|
68
|
+
*/
|
|
69
|
+
|
|
70
|
+
const fallbackLogger = createLogger(process.env.LOG_LEVEL);
|
|
71
|
+
|
|
72
|
+
/** The container handles, when the caller has them. */
|
|
73
|
+
export interface ReferralIntentHandles {
|
|
74
|
+
db: Database;
|
|
75
|
+
hatchet?: HatchetClient;
|
|
76
|
+
registry?: JourneyRegistry;
|
|
77
|
+
logger?: Logger;
|
|
78
|
+
analytics?: AnalyticsProvider;
|
|
79
|
+
/** The referral registry; falls back to the process runtime. */
|
|
80
|
+
referrals?: ReferralRegistry;
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
type ReferralEvent =
|
|
84
|
+
| "referral.touched"
|
|
85
|
+
| "referral.bound"
|
|
86
|
+
| "referral.qualified"
|
|
87
|
+
| "referral.converted"
|
|
88
|
+
| "referral.tree_converted"
|
|
89
|
+
| "referral.rejected";
|
|
90
|
+
|
|
91
|
+
/** The identity pin + recipient fields a re-ingest needs. */
|
|
92
|
+
interface ContactPin {
|
|
93
|
+
contactId: string;
|
|
94
|
+
userId: string;
|
|
95
|
+
email: string | null;
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
async function loadPins(
|
|
99
|
+
db: Database,
|
|
100
|
+
ids: string[],
|
|
101
|
+
): Promise<Map<string, ContactPin>> {
|
|
102
|
+
const unique = [...new Set(ids.filter(Boolean))];
|
|
103
|
+
if (unique.length === 0) return new Map();
|
|
104
|
+
const rows = await db
|
|
105
|
+
.select({
|
|
106
|
+
id: contacts.id,
|
|
107
|
+
externalId: contacts.externalId,
|
|
108
|
+
anonymousId: contacts.anonymousId,
|
|
109
|
+
email: contacts.email,
|
|
110
|
+
})
|
|
111
|
+
.from(contacts)
|
|
112
|
+
.where(inArray(contacts.id, unique));
|
|
113
|
+
return new Map(
|
|
114
|
+
rows.map((row) => [
|
|
115
|
+
row.id,
|
|
116
|
+
{
|
|
117
|
+
contactId: row.id,
|
|
118
|
+
userId: row.externalId ?? row.anonymousId ?? row.id,
|
|
119
|
+
email: row.email,
|
|
120
|
+
},
|
|
121
|
+
]),
|
|
122
|
+
);
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
/**
|
|
126
|
+
* Fan ONE fact onto BOTH planes for ONE recipient. Fire-and-forget with an
|
|
127
|
+
* attributed catch: a referral is a side effect of something the visitor
|
|
128
|
+
* already did (a click, an identify, a purchase), so a Hatchet hiccup must
|
|
129
|
+
* never fail that.
|
|
130
|
+
*/
|
|
131
|
+
function emitBoth<E extends ReferralEvent>(opts: {
|
|
132
|
+
handles: ReferralIntentHandles;
|
|
133
|
+
event: E;
|
|
134
|
+
/** The contact this copy of the fact is FOR (the bus subject). */
|
|
135
|
+
recipient: ContactPin | undefined;
|
|
136
|
+
/**
|
|
137
|
+
* The catalogued payload, which doubles VERBATIM as the journey-bus
|
|
138
|
+
* `eventProperties` - hence the scalar intersection. `ingestEvent` filters
|
|
139
|
+
* the Hatchet push down to scalars, so a nested field here would vanish
|
|
140
|
+
* between `user_events` and the journey it was meant to steer.
|
|
141
|
+
*/
|
|
142
|
+
payload: OutboundPayloads[E] &
|
|
143
|
+
Record<string, string | number | boolean | null>;
|
|
144
|
+
dedupeKey: string;
|
|
145
|
+
}): void {
|
|
146
|
+
const { handles, event, recipient, payload, dedupeKey } = opts;
|
|
147
|
+
const runtime = getReferralRuntime();
|
|
148
|
+
const logger = handles.logger ?? runtime?.logger ?? fallbackLogger;
|
|
149
|
+
const db = handles.db;
|
|
150
|
+
|
|
151
|
+
void (async () => {
|
|
152
|
+
// Prefer the CONTAINER's handles (passed, or held on the runtime) over the
|
|
153
|
+
// module singletons: importing `./hatchet.js` runs `HatchetClient.init`,
|
|
154
|
+
// which throws where no real token exists.
|
|
155
|
+
const hatchet =
|
|
156
|
+
handles.hatchet ??
|
|
157
|
+
runtime?.hatchet ??
|
|
158
|
+
(await import("./hatchet.js")).hatchet;
|
|
159
|
+
await emitOutbound({
|
|
160
|
+
db,
|
|
161
|
+
hatchet,
|
|
162
|
+
logger,
|
|
163
|
+
event,
|
|
164
|
+
payload,
|
|
165
|
+
dedupeKey,
|
|
166
|
+
});
|
|
167
|
+
if (!recipient) return;
|
|
168
|
+
// Dynamic import for the same two reasons `account-link-ingest.ts` gives:
|
|
169
|
+
// `lib/contacts.ts` reaches this module (the bind), and `lib/ingestion.ts`
|
|
170
|
+
// reaches `lib/contacts.ts`, so a static import is a module cycle; and
|
|
171
|
+
// importing `./hatchet.js` eagerly runs `HatchetClient.init`.
|
|
172
|
+
const { ingestEvent } = await import("./ingestion.js");
|
|
173
|
+
const analytics = handles.analytics ?? runtime?.analytics ?? getAnalytics();
|
|
174
|
+
await ingestEvent({
|
|
175
|
+
db,
|
|
176
|
+
registry:
|
|
177
|
+
handles.registry ?? runtime?.registry ?? getJourneyRegistrySingleton(),
|
|
178
|
+
hatchet,
|
|
179
|
+
logger,
|
|
180
|
+
...(analytics ? { analytics } : {}),
|
|
181
|
+
event: {
|
|
182
|
+
event,
|
|
183
|
+
// The value key only has to EXIST (the resolver requires one); the pin
|
|
184
|
+
// beside it decides the row and can never mint.
|
|
185
|
+
userId: recipient.userId,
|
|
186
|
+
contactId: recipient.contactId,
|
|
187
|
+
...(recipient.email ? { userEmail: recipient.email } : {}),
|
|
188
|
+
eventProperties: payload,
|
|
189
|
+
source: "referral",
|
|
190
|
+
idempotencyKey: `${dedupeKey}:${recipient.contactId}`,
|
|
191
|
+
},
|
|
192
|
+
});
|
|
193
|
+
})().catch((error: unknown) => {
|
|
194
|
+
logger.error("referral fact emit failed", {
|
|
195
|
+
event,
|
|
196
|
+
dedupeKey,
|
|
197
|
+
error: error instanceof Error ? error.message : String(error),
|
|
198
|
+
});
|
|
199
|
+
});
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
/** Scalar-only payload for a touch-shaped fact. */
|
|
203
|
+
function touchPayload(touch: ReferralTouchRecord): ReferralTouchPayload {
|
|
204
|
+
return {
|
|
205
|
+
referralId: touch.referralId,
|
|
206
|
+
touchId: touch.id,
|
|
207
|
+
referrerContactId: touch.referrerContactId,
|
|
208
|
+
refereeContactId: touch.refereeContactId,
|
|
209
|
+
refereeKey: touch.refereeKey,
|
|
210
|
+
source: touch.source,
|
|
211
|
+
linkId: touch.linkId,
|
|
212
|
+
clickId: touch.clickId,
|
|
213
|
+
status: touch.status,
|
|
214
|
+
touchedAt: touch.touchedAt.toISOString(),
|
|
215
|
+
};
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
// ---------------------------------------------------------------------------
|
|
219
|
+
// touch
|
|
220
|
+
// ---------------------------------------------------------------------------
|
|
221
|
+
|
|
222
|
+
export interface TouchReferralInput extends ReferralIntentHandles {
|
|
223
|
+
referral: DefinedReferral;
|
|
224
|
+
referrerContactId: string;
|
|
225
|
+
/** The toucher's canonical key - an ANONYMOUS id on a cold touch. */
|
|
226
|
+
refereeKey: string;
|
|
227
|
+
/** Set only when the toucher is already a known person. */
|
|
228
|
+
refereeContactId?: string | null;
|
|
229
|
+
linkId?: string | null;
|
|
230
|
+
clickId?: string | null;
|
|
231
|
+
source: ReferralTouchSource;
|
|
232
|
+
properties?: Record<string, unknown>;
|
|
233
|
+
idempotencyKey?: string;
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
export interface TouchReferralResult {
|
|
237
|
+
touch: ReferralTouchRecord | null;
|
|
238
|
+
created: boolean;
|
|
239
|
+
rejected: boolean;
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
/**
|
|
243
|
+
* Record a referral touch and announce it. `referral.touched` goes to the
|
|
244
|
+
* REFERRER only (see the identity note in the module header).
|
|
245
|
+
*/
|
|
246
|
+
export async function touchReferral(
|
|
247
|
+
input: TouchReferralInput,
|
|
248
|
+
): Promise<TouchReferralResult> {
|
|
249
|
+
const { referral, db } = input;
|
|
250
|
+
const result = await recordTouch({
|
|
251
|
+
db,
|
|
252
|
+
referral,
|
|
253
|
+
referralId: referral.id,
|
|
254
|
+
referrerContactId: input.referrerContactId,
|
|
255
|
+
refereeKey: input.refereeKey,
|
|
256
|
+
refereeContactId: input.refereeContactId ?? null,
|
|
257
|
+
linkId: input.linkId ?? null,
|
|
258
|
+
clickId: input.clickId ?? null,
|
|
259
|
+
source: input.source,
|
|
260
|
+
...(input.properties ? { properties: input.properties } : {}),
|
|
261
|
+
...(input.idempotencyKey ? { idempotencyKey: input.idempotencyKey } : {}),
|
|
262
|
+
});
|
|
263
|
+
|
|
264
|
+
// Only a FRESH write is news. A replayed click / same-pair re-touch recovered
|
|
265
|
+
// an existing row and announcing it again would re-fire the reward journey.
|
|
266
|
+
if (!result.created) {
|
|
267
|
+
return { touch: result.touch, created: false, rejected: result.rejected };
|
|
268
|
+
}
|
|
269
|
+
|
|
270
|
+
const pins = await loadPins(db, [
|
|
271
|
+
result.touch.referrerContactId,
|
|
272
|
+
...(result.touch.refereeContactId ? [result.touch.refereeContactId] : []),
|
|
273
|
+
]);
|
|
274
|
+
const referrer = pins.get(result.touch.referrerContactId);
|
|
275
|
+
|
|
276
|
+
if (result.rejected) {
|
|
277
|
+
emitBoth({
|
|
278
|
+
handles: input,
|
|
279
|
+
event: "referral.rejected",
|
|
280
|
+
recipient: referrer,
|
|
281
|
+
payload: {
|
|
282
|
+
...touchPayload(result.touch),
|
|
283
|
+
reason: result.touch.rejectedReason,
|
|
284
|
+
},
|
|
285
|
+
dedupeKey: `referral:rejected:${result.touch.id}`,
|
|
286
|
+
});
|
|
287
|
+
return { touch: result.touch, created: true, rejected: true };
|
|
288
|
+
}
|
|
289
|
+
|
|
290
|
+
emitBoth({
|
|
291
|
+
handles: input,
|
|
292
|
+
event: "referral.touched",
|
|
293
|
+
recipient: referrer,
|
|
294
|
+
payload: touchPayload(result.touch),
|
|
295
|
+
dedupeKey: `referral:touch:${result.touch.id}`,
|
|
296
|
+
});
|
|
297
|
+
|
|
298
|
+
// An already-identified toucher binds at the same instant, so the bind fact
|
|
299
|
+
// is due now: a reward journey listens on `referral.bound`, and only the
|
|
300
|
+
// COLD path reaches `bindReferral` later.
|
|
301
|
+
if (result.touch.status === "bound" && result.touch.refereeContactId) {
|
|
302
|
+
announceBound(input, result.touch, pins);
|
|
303
|
+
// Same law as the cold path in `bindReferral`: a referral with NO qualify
|
|
304
|
+
// config is EARNED at bind. Without this an identified toucher (token
|
|
305
|
+
// arrival, invite, manual) would sit at `bound` forever and no reward
|
|
306
|
+
// journey would ever see `referral.qualified`.
|
|
307
|
+
if (!referral.meta.qualify) {
|
|
308
|
+
await qualifyReferral({ ...input, touch: result.touch, referral });
|
|
309
|
+
}
|
|
310
|
+
}
|
|
311
|
+
|
|
312
|
+
return { touch: result.touch, created: true, rejected: false };
|
|
313
|
+
}
|
|
314
|
+
|
|
315
|
+
// ---------------------------------------------------------------------------
|
|
316
|
+
// bind
|
|
317
|
+
// ---------------------------------------------------------------------------
|
|
318
|
+
|
|
319
|
+
export interface BindReferralInput extends ReferralIntentHandles {
|
|
320
|
+
/** The anonymous/canonical key the visitor touched under. */
|
|
321
|
+
refereeKey: string;
|
|
322
|
+
/** The contact that key just resolved to. */
|
|
323
|
+
contactId: string;
|
|
324
|
+
}
|
|
325
|
+
|
|
326
|
+
/**
|
|
327
|
+
* Bind every unbound touch for a key at identity-adoption time, and announce
|
|
328
|
+
* each outcome. Called POST-COMMIT from `resolveContactShared` - never inside
|
|
329
|
+
* the resolver's transaction, because this emits and a rolled-back merge must
|
|
330
|
+
* never have announced a bind that never happened.
|
|
331
|
+
*/
|
|
332
|
+
export async function bindReferral(input: BindReferralInput): Promise<void> {
|
|
333
|
+
const referrals = resolveRegistry(input);
|
|
334
|
+
if (!referrals || referrals.count() === 0) return;
|
|
335
|
+
|
|
336
|
+
const result = await bindTouches({
|
|
337
|
+
db: input.db,
|
|
338
|
+
refereeKey: input.refereeKey,
|
|
339
|
+
contactId: input.contactId,
|
|
340
|
+
resolveReferral: (id) => referrals.get(id),
|
|
341
|
+
});
|
|
342
|
+
if (result.bound.length === 0 && result.rejected.length === 0) return;
|
|
343
|
+
|
|
344
|
+
const pins = await loadPins(input.db, [
|
|
345
|
+
input.contactId,
|
|
346
|
+
...result.bound.map((t) => t.referrerContactId),
|
|
347
|
+
...result.rejected.map((r) => r.touch.referrerContactId),
|
|
348
|
+
]);
|
|
349
|
+
|
|
350
|
+
for (const touch of result.bound) {
|
|
351
|
+
announceBound(input, touch, pins);
|
|
352
|
+
// A referral with NO qualify config is EARNED at bind: the referee is a
|
|
353
|
+
// known person, which is all the program asked for. Without this the touch
|
|
354
|
+
// would sit at `bound` forever and no reward journey would ever fire.
|
|
355
|
+
const referral = referrals.get(touch.referralId);
|
|
356
|
+
if (referral && !referral.meta.qualify) {
|
|
357
|
+
await qualifyReferral({ ...input, touch, referral });
|
|
358
|
+
}
|
|
359
|
+
}
|
|
360
|
+
|
|
361
|
+
for (const { touch, reason, detail } of result.rejected) {
|
|
362
|
+
emitBoth({
|
|
363
|
+
handles: input,
|
|
364
|
+
event: "referral.rejected",
|
|
365
|
+
recipient: pins.get(touch.referrerContactId),
|
|
366
|
+
payload: {
|
|
367
|
+
...touchPayload(touch),
|
|
368
|
+
reason,
|
|
369
|
+
detail: detail ?? null,
|
|
370
|
+
},
|
|
371
|
+
dedupeKey: `referral:rejected:${touch.id}`,
|
|
372
|
+
});
|
|
373
|
+
}
|
|
374
|
+
}
|
|
375
|
+
|
|
376
|
+
/** `referral.bound` reaches BOTH ends - the referrer and the referee. */
|
|
377
|
+
function announceBound(
|
|
378
|
+
handles: ReferralIntentHandles,
|
|
379
|
+
touch: ReferralTouchRecord,
|
|
380
|
+
pins: Map<string, ContactPin>,
|
|
381
|
+
): void {
|
|
382
|
+
const payload = {
|
|
383
|
+
...touchPayload(touch),
|
|
384
|
+
boundAt: touch.boundAt?.toISOString() ?? new Date().toISOString(),
|
|
385
|
+
};
|
|
386
|
+
emitBoth({
|
|
387
|
+
handles,
|
|
388
|
+
event: "referral.bound",
|
|
389
|
+
recipient: pins.get(touch.referrerContactId),
|
|
390
|
+
payload: { ...payload, side: "referrer" },
|
|
391
|
+
dedupeKey: `referral:bound:${touch.id}`,
|
|
392
|
+
});
|
|
393
|
+
if (touch.refereeContactId) {
|
|
394
|
+
emitBoth({
|
|
395
|
+
handles,
|
|
396
|
+
event: "referral.bound",
|
|
397
|
+
recipient: pins.get(touch.refereeContactId),
|
|
398
|
+
payload: { ...payload, side: "referee" },
|
|
399
|
+
// SAME outbound dedupe key: the customer's subscriber gets ONE delivery
|
|
400
|
+
// of the fact (the payload is the same edge). The bus keys differ only
|
|
401
|
+
// because `emitBoth` appends the recipient id.
|
|
402
|
+
dedupeKey: `referral:bound:${touch.id}`,
|
|
403
|
+
});
|
|
404
|
+
}
|
|
405
|
+
}
|
|
406
|
+
|
|
407
|
+
// ---------------------------------------------------------------------------
|
|
408
|
+
// qualify
|
|
409
|
+
// ---------------------------------------------------------------------------
|
|
410
|
+
|
|
411
|
+
export interface QualifyReferralInput extends ReferralIntentHandles {
|
|
412
|
+
touch: ReferralTouchRecord;
|
|
413
|
+
referral?: DefinedReferral;
|
|
414
|
+
event?: string;
|
|
415
|
+
eventProperties?: Record<string, unknown>;
|
|
416
|
+
conversionId?: string | null;
|
|
417
|
+
}
|
|
418
|
+
|
|
419
|
+
/**
|
|
420
|
+
* Promote a BOUND touch to qualified and announce it to BOTH ends. The store's
|
|
421
|
+
* `qualified_at IS NULL` predicate is the exactly-once guard, so a redelivered
|
|
422
|
+
* qualify event returns `existing` and emits nothing.
|
|
423
|
+
*/
|
|
424
|
+
export async function qualifyReferral(
|
|
425
|
+
input: QualifyReferralInput,
|
|
426
|
+
): Promise<void> {
|
|
427
|
+
const result = await qualifyTouch({
|
|
428
|
+
db: input.db,
|
|
429
|
+
touchId: input.touch.id,
|
|
430
|
+
...(input.referral ? { referral: input.referral } : {}),
|
|
431
|
+
...(input.event ? { event: input.event } : {}),
|
|
432
|
+
...(input.eventProperties
|
|
433
|
+
? { eventProperties: input.eventProperties }
|
|
434
|
+
: {}),
|
|
435
|
+
...(input.conversionId ? { conversionId: input.conversionId } : {}),
|
|
436
|
+
});
|
|
437
|
+
const touch = result.touch;
|
|
438
|
+
if (!touch) return;
|
|
439
|
+
|
|
440
|
+
const pins = await loadPins(input.db, [
|
|
441
|
+
touch.referrerContactId,
|
|
442
|
+
...(touch.refereeContactId ? [touch.refereeContactId] : []),
|
|
443
|
+
]);
|
|
444
|
+
|
|
445
|
+
if (result.rejected) {
|
|
446
|
+
emitBoth({
|
|
447
|
+
handles: input,
|
|
448
|
+
event: "referral.rejected",
|
|
449
|
+
recipient: pins.get(touch.referrerContactId),
|
|
450
|
+
payload: {
|
|
451
|
+
...touchPayload(touch),
|
|
452
|
+
reason: touch.rejectedReason,
|
|
453
|
+
detail: result.reason ?? null,
|
|
454
|
+
},
|
|
455
|
+
dedupeKey: `referral:rejected:${touch.id}`,
|
|
456
|
+
});
|
|
457
|
+
return;
|
|
458
|
+
}
|
|
459
|
+
if (!result.qualified) return;
|
|
460
|
+
|
|
461
|
+
const payload = {
|
|
462
|
+
...touchPayload(touch),
|
|
463
|
+
event: input.event ?? null,
|
|
464
|
+
conversionId: touch.qualifiedConversionId,
|
|
465
|
+
qualifiedAt: touch.qualifiedAt?.toISOString() ?? new Date().toISOString(),
|
|
466
|
+
};
|
|
467
|
+
emitBoth({
|
|
468
|
+
handles: input,
|
|
469
|
+
event: "referral.qualified",
|
|
470
|
+
recipient: pins.get(touch.referrerContactId),
|
|
471
|
+
payload: { ...payload, side: "referrer" },
|
|
472
|
+
dedupeKey: `referral:qualified:${touch.id}`,
|
|
473
|
+
});
|
|
474
|
+
if (touch.refereeContactId) {
|
|
475
|
+
emitBoth({
|
|
476
|
+
handles: input,
|
|
477
|
+
event: "referral.qualified",
|
|
478
|
+
recipient: pins.get(touch.refereeContactId),
|
|
479
|
+
payload: { ...payload, side: "referee" },
|
|
480
|
+
dedupeKey: `referral:qualified:${touch.id}`,
|
|
481
|
+
});
|
|
482
|
+
}
|
|
483
|
+
}
|
|
484
|
+
|
|
485
|
+
/**
|
|
486
|
+
* The `ingestEvent` hook: does THIS event qualify any of this contact's bound
|
|
487
|
+
* touches? Cheap on a miss - one map lookup on the registry - so it is safe to
|
|
488
|
+
* call on every ingested event.
|
|
489
|
+
*/
|
|
490
|
+
export async function qualifyReferralsForEvent(opts: {
|
|
491
|
+
handles: ReferralIntentHandles;
|
|
492
|
+
event: string;
|
|
493
|
+
eventProperties: Record<string, unknown>;
|
|
494
|
+
contactId: string;
|
|
495
|
+
}): Promise<void> {
|
|
496
|
+
const referrals = resolveRegistry(opts.handles);
|
|
497
|
+
const watching = referrals?.byQualifyEvent(opts.event) ?? [];
|
|
498
|
+
if (watching.length === 0) return;
|
|
499
|
+
|
|
500
|
+
const rows = await opts.handles.db
|
|
501
|
+
.select()
|
|
502
|
+
.from(referralTouches)
|
|
503
|
+
.where(
|
|
504
|
+
and(
|
|
505
|
+
eq(referralTouches.refereeContactId, opts.contactId),
|
|
506
|
+
eq(referralTouches.status, "bound"),
|
|
507
|
+
isNull(referralTouches.qualifiedAt),
|
|
508
|
+
inArray(
|
|
509
|
+
referralTouches.referralId,
|
|
510
|
+
watching.map((r) => r.id),
|
|
511
|
+
),
|
|
512
|
+
),
|
|
513
|
+
)
|
|
514
|
+
.orderBy(asc(referralTouches.touchedAt));
|
|
515
|
+
|
|
516
|
+
for (const row of rows) {
|
|
517
|
+
const referral = watching.find((r) => r.id === row.referralId);
|
|
518
|
+
if (!referral) continue;
|
|
519
|
+
// The `where` on `qualify` is the SAME builder journeys use for
|
|
520
|
+
// `trigger.where`, normalized once at `defineReferral` time - so "first
|
|
521
|
+
// paid invoice over 10" needs no custom veto hook.
|
|
522
|
+
if (
|
|
523
|
+
referral.qualifyWhere &&
|
|
524
|
+
!evaluatePropertyConditions({
|
|
525
|
+
conditions: referral.qualifyWhere,
|
|
526
|
+
properties: opts.eventProperties,
|
|
527
|
+
})
|
|
528
|
+
) {
|
|
529
|
+
continue;
|
|
530
|
+
}
|
|
531
|
+
await qualifyReferral({
|
|
532
|
+
...opts.handles,
|
|
533
|
+
touch: toTouchRecord(row),
|
|
534
|
+
referral,
|
|
535
|
+
event: opts.event,
|
|
536
|
+
eventProperties: opts.eventProperties,
|
|
537
|
+
});
|
|
538
|
+
}
|
|
539
|
+
}
|
|
540
|
+
|
|
541
|
+
// ---------------------------------------------------------------------------
|
|
542
|
+
// convert
|
|
543
|
+
// ---------------------------------------------------------------------------
|
|
544
|
+
|
|
545
|
+
/** How far up the tree a conversion is announced. Hard cap (PRD 05 §5.3). */
|
|
546
|
+
export const REFERRAL_TREE_MAX_DEPTH = 5;
|
|
547
|
+
|
|
548
|
+
export interface ConvertReferralInput extends ReferralIntentHandles {
|
|
549
|
+
/** The contact who converted - the REFEREE at level 1. */
|
|
550
|
+
contactId: string;
|
|
551
|
+
conversionId: string;
|
|
552
|
+
value: number | null;
|
|
553
|
+
currency: string | null;
|
|
554
|
+
occurredAt: Date;
|
|
555
|
+
}
|
|
556
|
+
|
|
557
|
+
/**
|
|
558
|
+
* Announce a conversion up the referral tree: `referral.converted` to the
|
|
559
|
+
* DIRECT referrer, `referral.tree_converted` to each ancestor above them, to
|
|
560
|
+
* {@link REFERRAL_TREE_MAX_DEPTH}.
|
|
561
|
+
*
|
|
562
|
+
* `level` is a FACT on the event, never program config - a reward journey
|
|
563
|
+
* filters with `trigger.where: (b) => b.prop("level").eq(1)`. That is the only
|
|
564
|
+
* place levels appear in code, which is what keeps depth and weights
|
|
565
|
+
* report-time parameters.
|
|
566
|
+
*/
|
|
567
|
+
export async function convertReferral(
|
|
568
|
+
input: ConvertReferralInput,
|
|
569
|
+
): Promise<void> {
|
|
570
|
+
const referrals = resolveRegistry(input);
|
|
571
|
+
if (!referrals || referrals.count() === 0) return;
|
|
572
|
+
|
|
573
|
+
const first = await firstBoundTouch(input.db, input.contactId);
|
|
574
|
+
if (!first) return;
|
|
575
|
+
|
|
576
|
+
// Best-effort ledger stamp: tie the credits earned by this touch's own
|
|
577
|
+
// click/arrive touchpoint to the edge, so `attribution_credits` and the
|
|
578
|
+
// referral tree reconcile. Nothing downstream depends on it, so a miss is
|
|
579
|
+
// silent (the touchpoint may predate the ledger window, or the conversion
|
|
580
|
+
// may have no touchpoint rows at all).
|
|
581
|
+
await stampAttributionCredits(input, first).catch((err: unknown) => {
|
|
582
|
+
(input.logger ?? fallbackLogger).warn("referral attribution stamp failed", {
|
|
583
|
+
error: err instanceof Error ? err.message : String(err),
|
|
584
|
+
});
|
|
585
|
+
});
|
|
586
|
+
|
|
587
|
+
// Walk UP: level 1 is the referee's direct referrer, level 2 that person's
|
|
588
|
+
// referrer, and so on. `visited` is the cycle guard - A referred B referred A
|
|
589
|
+
// is legal data (two edges, both valid) and would otherwise loop forever.
|
|
590
|
+
const visited = new Set<string>([input.contactId]);
|
|
591
|
+
let via = input.contactId;
|
|
592
|
+
let touch: ReferralTouchRecord | null = first;
|
|
593
|
+
const pinIds: string[] = [input.contactId];
|
|
594
|
+
|
|
595
|
+
const hops: Array<{
|
|
596
|
+
level: number;
|
|
597
|
+
beneficiary: string;
|
|
598
|
+
via: string;
|
|
599
|
+
touch: ReferralTouchRecord;
|
|
600
|
+
}> = [];
|
|
601
|
+
for (let level = 1; level <= REFERRAL_TREE_MAX_DEPTH && touch; level++) {
|
|
602
|
+
const beneficiary = touch.referrerContactId;
|
|
603
|
+
if (visited.has(beneficiary)) break;
|
|
604
|
+
visited.add(beneficiary);
|
|
605
|
+
hops.push({ level, beneficiary, via, touch });
|
|
606
|
+
pinIds.push(beneficiary);
|
|
607
|
+
via = beneficiary;
|
|
608
|
+
touch = await firstBoundTouch(input.db, beneficiary);
|
|
609
|
+
}
|
|
610
|
+
if (hops.length === 0) return;
|
|
611
|
+
|
|
612
|
+
const pins = await loadPins(input.db, pinIds);
|
|
613
|
+
for (const hop of hops) {
|
|
614
|
+
emitBoth({
|
|
615
|
+
handles: input,
|
|
616
|
+
event: hop.level === 1 ? "referral.converted" : "referral.tree_converted",
|
|
617
|
+
recipient: pins.get(hop.beneficiary),
|
|
618
|
+
payload: {
|
|
619
|
+
referralId: hop.touch.referralId,
|
|
620
|
+
touchId: hop.touch.id,
|
|
621
|
+
level: hop.level,
|
|
622
|
+
beneficiaryContactId: hop.beneficiary,
|
|
623
|
+
refereeContactId: input.contactId,
|
|
624
|
+
// The NEXT hop toward the referee, so a journey can name "your
|
|
625
|
+
// friend's friend" without walking the tree itself.
|
|
626
|
+
viaContactId: hop.via,
|
|
627
|
+
conversionId: input.conversionId,
|
|
628
|
+
// NOT `value` - see `ReferralConversionPayload.conversionValue`.
|
|
629
|
+
conversionValue: input.value,
|
|
630
|
+
currency: input.currency,
|
|
631
|
+
at: input.occurredAt.toISOString(),
|
|
632
|
+
},
|
|
633
|
+
dedupeKey: `referral:conv:${input.conversionId}:${hop.beneficiary}`,
|
|
634
|
+
});
|
|
635
|
+
}
|
|
636
|
+
}
|
|
637
|
+
|
|
638
|
+
/**
|
|
639
|
+
* The FIRST bound touch for a referee, by `touched_at`. First-touch is the pin
|
|
640
|
+
* for the tree walk on purpose: the walk must be STABLE (a later touch would
|
|
641
|
+
* silently re-parent an ancestor chain already announced), while the report
|
|
642
|
+
* picks its own model over the full edge log at query time.
|
|
643
|
+
*/
|
|
644
|
+
async function firstBoundTouch(
|
|
645
|
+
db: Database,
|
|
646
|
+
contactId: string,
|
|
647
|
+
): Promise<ReferralTouchRecord | null> {
|
|
648
|
+
const [row] = await db
|
|
649
|
+
.select()
|
|
650
|
+
.from(referralTouches)
|
|
651
|
+
.where(
|
|
652
|
+
and(
|
|
653
|
+
eq(referralTouches.refereeContactId, contactId),
|
|
654
|
+
inArray(referralTouches.status, ["bound", "qualified"]),
|
|
655
|
+
),
|
|
656
|
+
)
|
|
657
|
+
.orderBy(asc(referralTouches.touchedAt))
|
|
658
|
+
.limit(1);
|
|
659
|
+
return row ? toTouchRecord(row) : null;
|
|
660
|
+
}
|
|
661
|
+
|
|
662
|
+
/**
|
|
663
|
+
* Stamp `attribution_credits.referral_touch_id` on the rows this conversion
|
|
664
|
+
* produced whose touchpoint IS this touch's click/arrive event, so
|
|
665
|
+
* `WHERE channel = 'referral'` reconciles with the tree.
|
|
666
|
+
*/
|
|
667
|
+
async function stampAttributionCredits(
|
|
668
|
+
input: ConvertReferralInput,
|
|
669
|
+
touch: ReferralTouchRecord,
|
|
670
|
+
): Promise<void> {
|
|
671
|
+
if (!touch.clickId) return;
|
|
672
|
+
await input.db
|
|
673
|
+
.update(attributionCredits)
|
|
674
|
+
.set({ referralTouchId: touch.id })
|
|
675
|
+
.where(
|
|
676
|
+
and(
|
|
677
|
+
eq(attributionCredits.conversionId, input.conversionId),
|
|
678
|
+
isNull(attributionCredits.referralTouchId),
|
|
679
|
+
inArray(
|
|
680
|
+
attributionCredits.touchpointEventId,
|
|
681
|
+
input.db
|
|
682
|
+
.select({ id: userEvents.id })
|
|
683
|
+
.from(userEvents)
|
|
684
|
+
.where(
|
|
685
|
+
sql`${userEvents.properties}->>'ref' = ${touch.clickId} or ${userEvents.properties}->>'clickId' = ${touch.clickId}`,
|
|
686
|
+
),
|
|
687
|
+
),
|
|
688
|
+
),
|
|
689
|
+
);
|
|
690
|
+
}
|
|
691
|
+
|
|
692
|
+
// ---------------------------------------------------------------------------
|
|
693
|
+
// shared
|
|
694
|
+
// ---------------------------------------------------------------------------
|
|
695
|
+
|
|
696
|
+
function resolveRegistry(
|
|
697
|
+
handles: ReferralIntentHandles,
|
|
698
|
+
): ReferralRegistry | undefined {
|
|
699
|
+
return handles.referrals ?? getReferralRuntime()?.referrals;
|
|
700
|
+
}
|
|
701
|
+
|
|
702
|
+
/** `referral_touches` row → the store's record shape. */
|
|
703
|
+
function toTouchRecord(
|
|
704
|
+
row: typeof referralTouches.$inferSelect,
|
|
705
|
+
): ReferralTouchRecord {
|
|
706
|
+
return {
|
|
707
|
+
id: row.id,
|
|
708
|
+
referralId: row.referralId,
|
|
709
|
+
referrerContactId: row.referrerContactId,
|
|
710
|
+
refereeKey: row.refereeKey,
|
|
711
|
+
refereeContactId: row.refereeContactId,
|
|
712
|
+
linkId: row.linkId,
|
|
713
|
+
clickId: row.clickId,
|
|
714
|
+
source: row.source,
|
|
715
|
+
touchedAt: row.touchedAt,
|
|
716
|
+
boundAt: row.boundAt,
|
|
717
|
+
status: row.status as ReferralTouchRecord["status"],
|
|
718
|
+
rejectedReason: row.rejectedReason as ReferralTouchRecord["rejectedReason"],
|
|
719
|
+
qualifiedAt: row.qualifiedAt,
|
|
720
|
+
qualifiedConversionId: row.qualifiedConversionId,
|
|
721
|
+
properties: (row.properties ?? {}) as Record<string, unknown>,
|
|
722
|
+
};
|
|
723
|
+
}
|