@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,200 @@
|
|
|
1
|
+
import {
|
|
2
|
+
DEFAULT_REFERRAL_ID,
|
|
3
|
+
type DefinedReferral,
|
|
4
|
+
type ReferralLinkSubject,
|
|
5
|
+
} from "@hogsend/core";
|
|
6
|
+
import { contacts, type Database } from "@hogsend/db";
|
|
7
|
+
import { eq } from "drizzle-orm";
|
|
8
|
+
import { mintLink, SlugTakenError } from "./links.js";
|
|
9
|
+
import { createLogger } from "./logger.js";
|
|
10
|
+
import type { ReferralRegistry } from "./referral-registry.js";
|
|
11
|
+
import { getReferralRuntime } from "./referral-runtime.js";
|
|
12
|
+
|
|
13
|
+
/**
|
|
14
|
+
* `getReferralLink` (PRD 05 §7.2): the referrer's share link, journey-safe and
|
|
15
|
+
* idempotent. THE ONE mint path for a `shared` link, so `links.referral_id`,
|
|
16
|
+
* `owner_contact_id` and `append_ref` can never be set inconsistently.
|
|
17
|
+
*
|
|
18
|
+
* Journey-safe means two things. It issues NO durable Hatchet call, so it is
|
|
19
|
+
* invisible to the replay journal and needs no `ctx.once` wrap. And it is
|
|
20
|
+
* IDEMPOTENT at the database: a replay re-minting the same referrer's link
|
|
21
|
+
* recovers the existing row rather than minting a second one, either by the
|
|
22
|
+
* vanity slug or by the deterministic idempotency key below.
|
|
23
|
+
*/
|
|
24
|
+
|
|
25
|
+
/** The subset of the container this needs, structurally - avoids a cycle. */
|
|
26
|
+
export interface ReferralLinkContainer {
|
|
27
|
+
db: Database;
|
|
28
|
+
env: { API_PUBLIC_URL: string };
|
|
29
|
+
referrals: ReferralRegistry;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
export interface GetReferralLinkOptions {
|
|
33
|
+
/** The `defineReferral` id, or the definition itself. Default `"default"`. */
|
|
34
|
+
referral?: string | DefinedReferral;
|
|
35
|
+
/** The REFERRER - the contact who earns the credit for this link. */
|
|
36
|
+
contactId: string;
|
|
37
|
+
/**
|
|
38
|
+
* The request container, when the caller has one. Omitted inside a journey /
|
|
39
|
+
* durable task, where the process runtime installed by `createHogsendClient`
|
|
40
|
+
* is read instead.
|
|
41
|
+
*/
|
|
42
|
+
container?: ReferralLinkContainer;
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
export interface ReferralLink {
|
|
46
|
+
/**
|
|
47
|
+
* The share URL. The VANITY url (`/l/<slug>`) when the referral derives a
|
|
48
|
+
* slug, else the UUID redirect - so a program with `slugFrom` hands out the
|
|
49
|
+
* typeable code and one without hands out the durable one.
|
|
50
|
+
*/
|
|
51
|
+
url: string;
|
|
52
|
+
/** The normalized vanity slug, or null when the program derives none. */
|
|
53
|
+
slug: string | null;
|
|
54
|
+
/** The durable `links.id`. */
|
|
55
|
+
linkId: string;
|
|
56
|
+
/** The `tracked_links.id` - the `:id` in `/v1/t/c/:id`. */
|
|
57
|
+
trackedLinkId: string;
|
|
58
|
+
/** The referral this link belongs to. */
|
|
59
|
+
referralId: string;
|
|
60
|
+
/** True when the mint RECOVERED an existing link rather than inserting one. */
|
|
61
|
+
existing: boolean;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
const fallbackLogger = createLogger(process.env.LOG_LEVEL);
|
|
65
|
+
|
|
66
|
+
/** Warn ONCE per (referral, slug) that a slug collided and we fell back. */
|
|
67
|
+
const warnedSlugFallbacks = new Set<string>();
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* Resolve (or mint) the `shared` link that credits `contactId` under
|
|
71
|
+
* `referral`. Safe to call on every journey run: the second call returns the
|
|
72
|
+
* first call's link.
|
|
73
|
+
*/
|
|
74
|
+
export async function getReferralLink(
|
|
75
|
+
opts: GetReferralLinkOptions,
|
|
76
|
+
): Promise<ReferralLink> {
|
|
77
|
+
const runtime = opts.container
|
|
78
|
+
? {
|
|
79
|
+
db: opts.container.db,
|
|
80
|
+
baseUrl: opts.container.env.API_PUBLIC_URL,
|
|
81
|
+
referrals: opts.container.referrals,
|
|
82
|
+
}
|
|
83
|
+
: getReferralRuntime();
|
|
84
|
+
if (!runtime) {
|
|
85
|
+
throw new Error(
|
|
86
|
+
"getReferralLink: no referrals are configured. Pass them to " +
|
|
87
|
+
"createHogsendClient({ referrals: [myReferral] }) in BOTH index.ts " +
|
|
88
|
+
"and worker.ts",
|
|
89
|
+
);
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
const referral =
|
|
93
|
+
typeof opts.referral === "object" && opts.referral !== null
|
|
94
|
+
? opts.referral
|
|
95
|
+
: runtime.referrals.get(opts.referral ?? DEFAULT_REFERRAL_ID);
|
|
96
|
+
const requestedId =
|
|
97
|
+
typeof opts.referral === "string" ? opts.referral : opts.referral?.id;
|
|
98
|
+
if (!referral) {
|
|
99
|
+
throw new Error(
|
|
100
|
+
`getReferralLink: no referral "${requestedId ?? DEFAULT_REFERRAL_ID}" ` +
|
|
101
|
+
`is registered (registered: ${
|
|
102
|
+
runtime.referrals.ids().join(", ") || "none"
|
|
103
|
+
}). Pass it to createHogsendClient({ referrals: [...] })`,
|
|
104
|
+
);
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
const subject = await loadSubject(runtime.db, opts.contactId);
|
|
108
|
+
const { destination, slugFrom, campaign } = referral.meta.link;
|
|
109
|
+
const url =
|
|
110
|
+
typeof destination === "function" ? destination(subject) : destination;
|
|
111
|
+
const slug = slugFrom?.(subject) ?? null;
|
|
112
|
+
|
|
113
|
+
const base = {
|
|
114
|
+
db: runtime.db,
|
|
115
|
+
baseUrl: runtime.baseUrl,
|
|
116
|
+
url,
|
|
117
|
+
source: "referral",
|
|
118
|
+
type: "shared" as const,
|
|
119
|
+
ownerContactId: opts.contactId,
|
|
120
|
+
referralId: referral.id,
|
|
121
|
+
// Arrival attribution is what makes a COLD referral touch possible at all:
|
|
122
|
+
// the click carries no clicker key (a shared link stitches nobody), so the
|
|
123
|
+
// referee's anonymous id only appears when the landing page reports the
|
|
124
|
+
// appended `hs_ref` back to POST /v1/t/arrive.
|
|
125
|
+
appendRef: true,
|
|
126
|
+
...(campaign ? { campaign } : {}),
|
|
127
|
+
};
|
|
128
|
+
// `mintLink` rejects slug + idempotencyKey together (a slug IS an
|
|
129
|
+
// idempotency key), so the two idempotency strategies are exclusive by
|
|
130
|
+
// construction: WITH a slug, re-mint recovery is slug + same-url + same-type
|
|
131
|
+
// + same-owner; WITHOUT one, the deterministic key below.
|
|
132
|
+
const idempotencyKey = `referral:${referral.id}:${opts.contactId}`;
|
|
133
|
+
|
|
134
|
+
if (slug) {
|
|
135
|
+
try {
|
|
136
|
+
const minted = await mintLink({ ...base, slug });
|
|
137
|
+
return toResult(minted, referral.id);
|
|
138
|
+
} catch (err) {
|
|
139
|
+
if (!(err instanceof SlugTakenError)) throw err;
|
|
140
|
+
// Someone else holds the slug (two referrers whose `slugFrom` collide,
|
|
141
|
+
// or an archived link still reserving it). A referrer with no link at
|
|
142
|
+
// all is the worse failure, so fall back to the slugless idempotent
|
|
143
|
+
// mint - they get a working share URL, just not the pretty one.
|
|
144
|
+
const warnKey = `${referral.id}:${slug}`;
|
|
145
|
+
if (!warnedSlugFallbacks.has(warnKey)) {
|
|
146
|
+
warnedSlugFallbacks.add(warnKey);
|
|
147
|
+
fallbackLogger.warn(
|
|
148
|
+
"referral slug is already taken - minting a slugless link instead",
|
|
149
|
+
{ referralId: referral.id, slug, contactId: opts.contactId },
|
|
150
|
+
);
|
|
151
|
+
}
|
|
152
|
+
}
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
const minted = await mintLink({ ...base, idempotencyKey });
|
|
156
|
+
return toResult(minted, referral.id);
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
function toResult(
|
|
160
|
+
minted: Awaited<ReturnType<typeof mintLink>>,
|
|
161
|
+
referralId: string,
|
|
162
|
+
): ReferralLink {
|
|
163
|
+
return {
|
|
164
|
+
url: minted.vanityUrl ?? minted.url,
|
|
165
|
+
slug: minted.slug,
|
|
166
|
+
linkId: minted.linkId,
|
|
167
|
+
trackedLinkId: minted.trackedLinkId,
|
|
168
|
+
referralId,
|
|
169
|
+
existing: minted.existing,
|
|
170
|
+
};
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
/** The referrer as `link.destination` / `link.slugFrom` see them. */
|
|
174
|
+
async function loadSubject(
|
|
175
|
+
db: Database,
|
|
176
|
+
contactId: string,
|
|
177
|
+
): Promise<ReferralLinkSubject> {
|
|
178
|
+
const [row] = await db
|
|
179
|
+
.select({
|
|
180
|
+
id: contacts.id,
|
|
181
|
+
externalId: contacts.externalId,
|
|
182
|
+
anonymousId: contacts.anonymousId,
|
|
183
|
+
email: contacts.email,
|
|
184
|
+
properties: contacts.properties,
|
|
185
|
+
})
|
|
186
|
+
.from(contacts)
|
|
187
|
+
.where(eq(contacts.id, contactId))
|
|
188
|
+
.limit(1);
|
|
189
|
+
if (!row) {
|
|
190
|
+
// A link owned by a contact that does not exist would fail the FK anyway;
|
|
191
|
+
// failing here names the actual problem.
|
|
192
|
+
throw new Error(`getReferralLink: no contact ${contactId}`);
|
|
193
|
+
}
|
|
194
|
+
return {
|
|
195
|
+
contactId: row.id,
|
|
196
|
+
userId: row.externalId ?? row.anonymousId ?? row.id,
|
|
197
|
+
email: row.email,
|
|
198
|
+
properties: (row.properties ?? {}) as Record<string, unknown>,
|
|
199
|
+
};
|
|
200
|
+
}
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
import type { DefinedReferral } from "@hogsend/core";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Container-held registry of referral definitions, keyed by `DefinedReferral.id`
|
|
5
|
+
* - a structural mirror of {@link AccountLinkProviderRegistry}
|
|
6
|
+
* (`lib/account-link-provider-registry.ts`).
|
|
7
|
+
*
|
|
8
|
+
* There is NO env preset and NO "active referral": a referral is authored in
|
|
9
|
+
* code or it does not exist, and a product may run several programs at once
|
|
10
|
+
* (each link carries its own `links.referral_id`). So an empty registry is the
|
|
11
|
+
* normal state of a deploy that never asked for referrals, and every wired
|
|
12
|
+
* site - the click/arrive touch, the bind at identity adoption, the qualify
|
|
13
|
+
* evaluation in `ingestEvent` - is INERT while it stays empty.
|
|
14
|
+
*
|
|
15
|
+
* Last-writer-wins on `id`, matching every other registry merge in the engine.
|
|
16
|
+
* `defineReferral()` already validates the id charset, so this does not
|
|
17
|
+
* re-validate it (a second copy of that rule is a second place to update).
|
|
18
|
+
*/
|
|
19
|
+
export class ReferralRegistry {
|
|
20
|
+
private byId = new Map<string, DefinedReferral>();
|
|
21
|
+
/**
|
|
22
|
+
* `qualify.event` → the referrals watching it. Built at construction because
|
|
23
|
+
* `ingestEvent` asks this question on EVERY event: a miss must cost one map
|
|
24
|
+
* lookup, not a scan of every definition.
|
|
25
|
+
*/
|
|
26
|
+
private byEvent = new Map<string, DefinedReferral[]>();
|
|
27
|
+
|
|
28
|
+
constructor(referrals: DefinedReferral[] = []) {
|
|
29
|
+
for (const referral of referrals) this.register(referral);
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/** Register (or replace) a referral. Last-writer-wins on `id`. */
|
|
33
|
+
register(referral: DefinedReferral): void {
|
|
34
|
+
const id = referral.id;
|
|
35
|
+
if (!id) {
|
|
36
|
+
throw new TypeError(
|
|
37
|
+
"referral has no id - the id keys the registry and is stamped on " +
|
|
38
|
+
"every touch row, so it is required (author referrals with " +
|
|
39
|
+
"defineReferral, which resolves it)",
|
|
40
|
+
);
|
|
41
|
+
}
|
|
42
|
+
const prior = this.byId.get(id);
|
|
43
|
+
if (prior) this.unindexEvent(prior);
|
|
44
|
+
this.byId.set(id, referral);
|
|
45
|
+
const event = referral.meta.qualify?.event;
|
|
46
|
+
if (event) {
|
|
47
|
+
const watchers = this.byEvent.get(event) ?? [];
|
|
48
|
+
watchers.push(referral);
|
|
49
|
+
this.byEvent.set(event, watchers);
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
private unindexEvent(referral: DefinedReferral): void {
|
|
54
|
+
const event = referral.meta.qualify?.event;
|
|
55
|
+
if (!event) return;
|
|
56
|
+
const watchers = (this.byEvent.get(event) ?? []).filter(
|
|
57
|
+
(r) => r !== referral,
|
|
58
|
+
);
|
|
59
|
+
if (watchers.length > 0) this.byEvent.set(event, watchers);
|
|
60
|
+
else this.byEvent.delete(event);
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
get(id: string): DefinedReferral | undefined {
|
|
64
|
+
return this.byId.get(id);
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
list(): DefinedReferral[] {
|
|
68
|
+
return [...this.byId.values()];
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
ids(): string[] {
|
|
72
|
+
return [...this.byId.keys()];
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
count(): number {
|
|
76
|
+
return this.byId.size;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
/** Every referral whose `qualify.event` is `event`. Empty when none watch it. */
|
|
80
|
+
byQualifyEvent(event: string): DefinedReferral[] {
|
|
81
|
+
return this.byEvent.get(event) ?? [];
|
|
82
|
+
}
|
|
83
|
+
}
|