@referalli/sdk 0.0.0-stage → 0.3.20
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/CHANGELOG.md +128 -0
- package/LICENSE +21 -0
- package/README.md +236 -2
- package/dist/cjs/attribution.d.ts +105 -0
- package/dist/cjs/attribution.js +200 -0
- package/dist/cjs/browser.d.ts +41 -0
- package/dist/cjs/browser.js +88 -0
- package/dist/cjs/client.d.ts +97 -0
- package/dist/cjs/client.js +301 -0
- package/dist/cjs/consent/adapters/cookiebot.d.ts +7 -0
- package/dist/cjs/consent/adapters/cookiebot.js +49 -0
- package/dist/cjs/consent/adapters/cookiemunch.d.ts +8 -0
- package/dist/cjs/consent/adapters/cookiemunch.js +56 -0
- package/dist/cjs/consent/adapters/custom.d.ts +8 -0
- package/dist/cjs/consent/adapters/custom.js +39 -0
- package/dist/cjs/consent/adapters/didomi.d.ts +9 -0
- package/dist/cjs/consent/adapters/didomi.js +67 -0
- package/dist/cjs/consent/adapters/gcm.d.ts +10 -0
- package/dist/cjs/consent/adapters/gcm.js +78 -0
- package/dist/cjs/consent/adapters/gpp.d.ts +9 -0
- package/dist/cjs/consent/adapters/gpp.js +92 -0
- package/dist/cjs/consent/adapters/none.d.ts +3 -0
- package/dist/cjs/consent/adapters/none.js +30 -0
- package/dist/cjs/consent/adapters/onetrust.d.ts +8 -0
- package/dist/cjs/consent/adapters/onetrust.js +71 -0
- package/dist/cjs/consent/adapters/osano.d.ts +9 -0
- package/dist/cjs/consent/adapters/osano.js +71 -0
- package/dist/cjs/consent/adapters/tcf.d.ts +8 -0
- package/dist/cjs/consent/adapters/tcf.js +79 -0
- package/dist/cjs/consent/adapters/termly.d.ts +10 -0
- package/dist/cjs/consent/adapters/termly.js +61 -0
- package/dist/cjs/consent/adapters/usercentrics.d.ts +9 -0
- package/dist/cjs/consent/adapters/usercentrics.js +106 -0
- package/dist/cjs/consent/conformance.d.ts +22 -0
- package/dist/cjs/consent/conformance.js +33 -0
- package/dist/cjs/consent/gate.d.ts +23 -0
- package/dist/cjs/consent/gate.js +220 -0
- package/dist/cjs/consent/port.d.ts +105 -0
- package/dist/cjs/consent/port.js +72 -0
- package/dist/cjs/consent/registry.d.ts +17 -0
- package/dist/cjs/consent/registry.js +61 -0
- package/dist/cjs/consent/served.d.ts +15 -0
- package/dist/cjs/consent/served.js +26 -0
- package/dist/cjs/core.d.ts +77 -0
- package/dist/cjs/core.js +64 -0
- package/dist/cjs/errors.d.ts +42 -0
- package/dist/cjs/errors.generated.d.ts +183 -0
- package/dist/cjs/errors.generated.js +279 -0
- package/dist/cjs/errors.js +47 -0
- package/dist/cjs/generated.d.ts +15146 -0
- package/dist/cjs/generated.js +625 -0
- package/dist/cjs/index.d.ts +22 -0
- package/dist/cjs/index.js +93 -0
- package/dist/cjs/mobile.d.ts +66 -0
- package/dist/cjs/mobile.js +69 -0
- package/dist/cjs/node.d.ts +209 -0
- package/dist/cjs/node.js +140 -0
- package/dist/cjs/outbox.d.ts +186 -0
- package/dist/cjs/outbox.js +324 -0
- package/dist/cjs/package.json +3 -0
- package/dist/cjs/resources.generated.d.ts +6002 -0
- package/dist/cjs/resources.generated.js +2090 -0
- package/dist/cjs/served.d.ts +25 -0
- package/dist/cjs/served.js +214 -0
- package/dist/cjs/sha256.d.ts +2 -0
- package/dist/cjs/sha256.js +86 -0
- package/dist/cjs/snippet.d.ts +99 -0
- package/dist/cjs/snippet.js +213 -0
- package/dist/cjs/stripe-events.d.ts +25 -0
- package/dist/cjs/stripe-events.js +117 -0
- package/dist/cjs/version.d.ts +2 -0
- package/dist/cjs/version.js +5 -0
- package/dist/cjs/webhooks.d.ts +76 -0
- package/dist/cjs/webhooks.js +159 -0
- package/dist/esm/attribution.d.ts +105 -0
- package/dist/esm/attribution.js +186 -0
- package/dist/esm/browser.d.ts +41 -0
- package/dist/esm/browser.js +68 -0
- package/dist/esm/client.d.ts +97 -0
- package/dist/esm/client.js +297 -0
- package/dist/esm/consent/adapters/cookiebot.d.ts +7 -0
- package/dist/esm/consent/adapters/cookiebot.js +46 -0
- package/dist/esm/consent/adapters/cookiemunch.d.ts +8 -0
- package/dist/esm/consent/adapters/cookiemunch.js +53 -0
- package/dist/esm/consent/adapters/custom.d.ts +8 -0
- package/dist/esm/consent/adapters/custom.js +36 -0
- package/dist/esm/consent/adapters/didomi.d.ts +9 -0
- package/dist/esm/consent/adapters/didomi.js +64 -0
- package/dist/esm/consent/adapters/gcm.d.ts +10 -0
- package/dist/esm/consent/adapters/gcm.js +75 -0
- package/dist/esm/consent/adapters/gpp.d.ts +9 -0
- package/dist/esm/consent/adapters/gpp.js +89 -0
- package/dist/esm/consent/adapters/none.d.ts +3 -0
- package/dist/esm/consent/adapters/none.js +27 -0
- package/dist/esm/consent/adapters/onetrust.d.ts +8 -0
- package/dist/esm/consent/adapters/onetrust.js +68 -0
- package/dist/esm/consent/adapters/osano.d.ts +9 -0
- package/dist/esm/consent/adapters/osano.js +68 -0
- package/dist/esm/consent/adapters/tcf.d.ts +8 -0
- package/dist/esm/consent/adapters/tcf.js +76 -0
- package/dist/esm/consent/adapters/termly.d.ts +10 -0
- package/dist/esm/consent/adapters/termly.js +58 -0
- package/dist/esm/consent/adapters/usercentrics.d.ts +9 -0
- package/dist/esm/consent/adapters/usercentrics.js +103 -0
- package/dist/esm/consent/conformance.d.ts +22 -0
- package/dist/esm/consent/conformance.js +30 -0
- package/dist/esm/consent/gate.d.ts +23 -0
- package/dist/esm/consent/gate.js +217 -0
- package/dist/esm/consent/port.d.ts +105 -0
- package/dist/esm/consent/port.js +67 -0
- package/dist/esm/consent/registry.d.ts +17 -0
- package/dist/esm/consent/registry.js +55 -0
- package/dist/esm/consent/served.d.ts +15 -0
- package/dist/esm/consent/served.js +22 -0
- package/dist/esm/core.d.ts +77 -0
- package/dist/esm/core.js +60 -0
- package/dist/esm/errors.d.ts +42 -0
- package/dist/esm/errors.generated.d.ts +183 -0
- package/dist/esm/errors.generated.js +231 -0
- package/dist/esm/errors.js +40 -0
- package/dist/esm/generated.d.ts +15146 -0
- package/dist/esm/generated.js +622 -0
- package/dist/esm/index.d.ts +22 -0
- package/dist/esm/index.js +22 -0
- package/dist/esm/mobile.d.ts +66 -0
- package/dist/esm/mobile.js +64 -0
- package/dist/esm/node.d.ts +209 -0
- package/dist/esm/node.js +135 -0
- package/dist/esm/outbox.d.ts +186 -0
- package/dist/esm/outbox.js +316 -0
- package/dist/esm/package.json +3 -0
- package/dist/esm/resources.generated.d.ts +6002 -0
- package/dist/esm/resources.generated.js +2086 -0
- package/dist/esm/served.d.ts +25 -0
- package/dist/esm/served.js +207 -0
- package/dist/esm/sha256.d.ts +2 -0
- package/dist/esm/sha256.js +82 -0
- package/dist/esm/snippet.d.ts +99 -0
- package/dist/esm/snippet.js +210 -0
- package/dist/esm/stripe-events.d.ts +25 -0
- package/dist/esm/stripe-events.js +114 -0
- package/dist/esm/version.d.ts +2 -0
- package/dist/esm/version.js +2 -0
- package/dist/esm/webhooks.d.ts +76 -0
- package/dist/esm/webhooks.js +153 -0
- package/dist/tsconfig.build.tsbuildinfo +1 -0
- package/dist/tsconfig.cjs.tsbuildinfo +1 -0
- package/package.json +105 -4
- package/src/attribution.ts +216 -0
- package/src/browser.ts +107 -0
- package/src/client.ts +351 -0
- package/src/codegen.ts +130 -0
- package/src/consent/adapters/cookiebot.ts +42 -0
- package/src/consent/adapters/cookiemunch.ts +49 -0
- package/src/consent/adapters/custom.ts +37 -0
- package/src/consent/adapters/didomi.ts +59 -0
- package/src/consent/adapters/gcm.ts +68 -0
- package/src/consent/adapters/gpp.ts +81 -0
- package/src/consent/adapters/none.ts +28 -0
- package/src/consent/adapters/onetrust.ts +64 -0
- package/src/consent/adapters/osano.ts +63 -0
- package/src/consent/adapters/tcf.ts +67 -0
- package/src/consent/adapters/termly.ts +54 -0
- package/src/consent/adapters/usercentrics.ts +97 -0
- package/src/consent/conformance.ts +47 -0
- package/src/consent/gate.ts +216 -0
- package/src/consent/port.ts +148 -0
- package/src/consent/registry.ts +60 -0
- package/src/consent/served.ts +24 -0
- package/src/core.ts +127 -0
- package/src/errors.generated.ts +277 -0
- package/src/errors.ts +57 -0
- package/src/generated.ts +14540 -0
- package/src/index.ts +100 -0
- package/src/mobile.ts +96 -0
- package/src/node.ts +291 -0
- package/src/outbox.ts +452 -0
- package/src/resources.generated.ts +2097 -0
- package/src/served.ts +229 -0
- package/src/sha256.ts +82 -0
- package/src/snippet.ts +305 -0
- package/src/stripe-events.ts +130 -0
- package/src/version.ts +2 -0
- package/src/webhooks.ts +207 -0
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* The first-party referral context, shared by the browser tracker (`aff.js`,
|
|
4
|
+
* `referalli/browser`) and the server kits (`@referalli/next`,
|
|
5
|
+
* `@referalli/express`): what it is, how a landing URL updates it, and how it
|
|
6
|
+
* is stored in a cookie on the merchant's own domain. Isomorphic and
|
|
7
|
+
* dependency-free.
|
|
8
|
+
*/
|
|
9
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
10
|
+
exports.clampDays = exports.DEFAULT_COOKIE_DAYS = exports.CLICK_ID_PARAM = exports.REFERRAL_PARAMS = exports.REFERRAL_COOKIE_NAMES = exports.LEGACY_REFERRAL_COOKIE = exports.REFERRAL_COOKIE = void 0;
|
|
11
|
+
exports.newAnonId = newAnonId;
|
|
12
|
+
exports.referralFromUrl = referralFromUrl;
|
|
13
|
+
exports.parseReferral = parseReferral;
|
|
14
|
+
exports.referralFromCookieHeader = referralFromCookieHeader;
|
|
15
|
+
exports.mergeReferral = mergeReferral;
|
|
16
|
+
exports.serializeReferralCookie = serializeReferralCookie;
|
|
17
|
+
exports.serializeReferralCookies = serializeReferralCookies;
|
|
18
|
+
exports.clearReferralCookies = clearReferralCookies;
|
|
19
|
+
exports.associateFields = associateFields;
|
|
20
|
+
exports.hashEmail = hashEmail;
|
|
21
|
+
/** Cookie (and localStorage key) holding the context. A wire name shared with every `aff.js` install; don't change it. */
|
|
22
|
+
exports.REFERRAL_COOKIE = 'referalli_ctx';
|
|
23
|
+
/**
|
|
24
|
+
* The pre-rename name of the same context. The browser tracker (`aff.js`,
|
|
25
|
+
* `referalli/browser`) writes the context under BOTH names, with the same
|
|
26
|
+
* value, attributes and expiry, and reads either.
|
|
27
|
+
*
|
|
28
|
+
* Why: integrations that read the cookie themselves may still read the pre-rename
|
|
29
|
+
* name. Atlas's connector and Cookie Munch's preset both read `referalli_ctx` now.
|
|
30
|
+
* The twin is written until 2027-01-31, announced in the changelog and on
|
|
31
|
+
* /docs/renamed-from-referally, then dropped (reading stays tolerant).
|
|
32
|
+
*
|
|
33
|
+
* TODO(legacy-ctx, 2027-01-31): stop writing the legacy name; keep reading it for
|
|
34
|
+
* one more cookie window after that.
|
|
35
|
+
*/
|
|
36
|
+
exports.LEGACY_REFERRAL_COOKIE = 'referally_ctx';
|
|
37
|
+
/** Every name the context is written and read under, current first. */
|
|
38
|
+
exports.REFERRAL_COOKIE_NAMES = [exports.REFERRAL_COOKIE, exports.LEGACY_REFERRAL_COOKIE];
|
|
39
|
+
/** Query parameters that carry a partner's referral code, in priority order. */
|
|
40
|
+
exports.REFERRAL_PARAMS = ['via', 'ref', 'aff'];
|
|
41
|
+
/** Query parameter carrying a click id from a Referalli redirect link (`/go/...`). */
|
|
42
|
+
exports.CLICK_ID_PARAM = 'ref_click_id';
|
|
43
|
+
exports.DEFAULT_COOKIE_DAYS = 60;
|
|
44
|
+
const DAY_MS = 86_400_000;
|
|
45
|
+
const clampDays = (days) => Math.max(1, Math.min(400, Math.round(days ?? exports.DEFAULT_COOKIE_DAYS)));
|
|
46
|
+
exports.clampDays = clampDays;
|
|
47
|
+
/** A fresh anonymous id: `a_` + 20 random base-36 characters. */
|
|
48
|
+
function newAnonId() {
|
|
49
|
+
const chars = 'abcdefghijklmnopqrstuvwxyz0123456789';
|
|
50
|
+
const c = globalThis.crypto;
|
|
51
|
+
const bytes = new Uint8Array(20);
|
|
52
|
+
if (c?.getRandomValues)
|
|
53
|
+
c.getRandomValues(bytes);
|
|
54
|
+
else
|
|
55
|
+
for (let i = 0; i < 20; i++)
|
|
56
|
+
bytes[i] = Math.floor(Math.random() * 256);
|
|
57
|
+
let out = 'a_';
|
|
58
|
+
for (const b of bytes)
|
|
59
|
+
out += chars[b % chars.length];
|
|
60
|
+
return out;
|
|
61
|
+
}
|
|
62
|
+
/** The referral a URL carries: the first of `params` that is set, and `ref_click_id`. */
|
|
63
|
+
function referralFromUrl(url, params = exports.REFERRAL_PARAMS) {
|
|
64
|
+
let u;
|
|
65
|
+
try {
|
|
66
|
+
u = typeof url === 'string' ? new URL(url, 'http://localhost') : url;
|
|
67
|
+
}
|
|
68
|
+
catch {
|
|
69
|
+
return { code: null, clickId: null };
|
|
70
|
+
}
|
|
71
|
+
let code = null;
|
|
72
|
+
for (const p of params) {
|
|
73
|
+
const v = u.searchParams.get(p);
|
|
74
|
+
if (v) {
|
|
75
|
+
code = v.slice(0, 120);
|
|
76
|
+
break;
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
const clickId = u.searchParams.get(exports.CLICK_ID_PARAM)?.slice(0, 80) || null;
|
|
80
|
+
return { code, clickId };
|
|
81
|
+
}
|
|
82
|
+
/** Parse a stored context (the cookie's or localStorage's value, URI-encoded or not). Expired or malformed → null. */
|
|
83
|
+
function parseReferral(raw, now = Date.now()) {
|
|
84
|
+
if (!raw)
|
|
85
|
+
return null;
|
|
86
|
+
let text = raw;
|
|
87
|
+
try {
|
|
88
|
+
if (raw.startsWith('%7B') || raw.startsWith('%7b'))
|
|
89
|
+
text = decodeURIComponent(raw);
|
|
90
|
+
}
|
|
91
|
+
catch {
|
|
92
|
+
return null;
|
|
93
|
+
}
|
|
94
|
+
try {
|
|
95
|
+
const parsed = JSON.parse(text);
|
|
96
|
+
if (!parsed || typeof parsed.anonId !== 'string')
|
|
97
|
+
return null;
|
|
98
|
+
if (parsed.exp && parsed.exp < now)
|
|
99
|
+
return null;
|
|
100
|
+
return {
|
|
101
|
+
anonId: parsed.anonId,
|
|
102
|
+
code: typeof parsed.code === 'string' ? parsed.code : null,
|
|
103
|
+
clickId: typeof parsed.clickId === 'string' ? parsed.clickId : null,
|
|
104
|
+
ts: typeof parsed.ts === 'number' ? parsed.ts : now,
|
|
105
|
+
...(typeof parsed.exp === 'number' ? { exp: parsed.exp } : {}),
|
|
106
|
+
};
|
|
107
|
+
}
|
|
108
|
+
catch {
|
|
109
|
+
return null;
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
/**
|
|
113
|
+
* The context from a `Cookie` request header. `names` are tried in order
|
|
114
|
+
* (default: `REFERRAL_COOKIE_NAMES`, the current name then the legacy one);
|
|
115
|
+
* add an older cookie name to keep reading contexts saved under it.
|
|
116
|
+
*/
|
|
117
|
+
function referralFromCookieHeader(cookieHeader, now = Date.now(), names = exports.REFERRAL_COOKIE_NAMES) {
|
|
118
|
+
if (!cookieHeader)
|
|
119
|
+
return null;
|
|
120
|
+
const jar = new Map();
|
|
121
|
+
for (const part of cookieHeader.split(';')) {
|
|
122
|
+
const i = part.indexOf('=');
|
|
123
|
+
if (i > 0)
|
|
124
|
+
jar.set(part.slice(0, i).trim(), part.slice(i + 1).trim());
|
|
125
|
+
}
|
|
126
|
+
for (const name of names) {
|
|
127
|
+
const raw = jar.get(name);
|
|
128
|
+
if (raw === undefined)
|
|
129
|
+
continue;
|
|
130
|
+
try {
|
|
131
|
+
const ctx = parseReferral(decodeURIComponent(raw), now);
|
|
132
|
+
if (ctx)
|
|
133
|
+
return ctx;
|
|
134
|
+
}
|
|
135
|
+
catch {
|
|
136
|
+
/* malformed: try the next name */
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
return null;
|
|
140
|
+
}
|
|
141
|
+
/**
|
|
142
|
+
* The context after a page view: a new referral in the URL replaces the
|
|
143
|
+
* stored one (unless `firstTouch` keeps an unexpired one), and a referral
|
|
144
|
+
* restarts the expiry window. Same rules as `aff.js`.
|
|
145
|
+
*/
|
|
146
|
+
function mergeReferral(stored, fromUrl, opts = {}) {
|
|
147
|
+
const now = opts.now ?? Date.now();
|
|
148
|
+
const days = (0, exports.clampDays)(opts.cookieDays);
|
|
149
|
+
const referred = Boolean(fromUrl.code || fromUrl.clickId);
|
|
150
|
+
const keep = Boolean(opts.firstTouch && (stored?.code || stored?.clickId));
|
|
151
|
+
return {
|
|
152
|
+
anonId: stored?.anonId ?? (opts.randomId ?? newAnonId)(),
|
|
153
|
+
code: keep ? (stored?.code ?? null) : (fromUrl.code ?? stored?.code ?? null),
|
|
154
|
+
clickId: keep ? (stored?.clickId ?? null) : (fromUrl.clickId ?? stored?.clickId ?? null),
|
|
155
|
+
ts: stored?.ts ?? now,
|
|
156
|
+
exp: keep && stored?.exp ? stored.exp : referred || !stored?.exp ? now + days * DAY_MS : stored.exp,
|
|
157
|
+
};
|
|
158
|
+
}
|
|
159
|
+
/**
|
|
160
|
+
* A `Set-Cookie` header value for the context. Not HttpOnly on purpose: the
|
|
161
|
+
* browser tracker reads the same cookie.
|
|
162
|
+
*/
|
|
163
|
+
function serializeReferralCookie(ctx, opts = {}) {
|
|
164
|
+
const days = (0, exports.clampDays)(opts.cookieDays);
|
|
165
|
+
const domain = opts.domain && /^\.?[a-z0-9.-]+$/i.test(opts.domain) ? `; Domain=${opts.domain}` : '';
|
|
166
|
+
const secure = opts.secure === false ? '' : '; Secure';
|
|
167
|
+
return `${exports.REFERRAL_COOKIE}=${encodeURIComponent(JSON.stringify(ctx))}; Path=/; Max-Age=${days * 86_400}; SameSite=Lax${domain}${secure}`;
|
|
168
|
+
}
|
|
169
|
+
/**
|
|
170
|
+
* `Set-Cookie` values for the context under every name: `referalli_ctx` and
|
|
171
|
+
* its legacy twin `referally_ctx`, same value, attributes and expiry (see
|
|
172
|
+
* LEGACY_REFERRAL_COOKIE). Server kits append each one.
|
|
173
|
+
*/
|
|
174
|
+
function serializeReferralCookies(ctx, opts = {}) {
|
|
175
|
+
const value = serializeReferralCookie(ctx, opts);
|
|
176
|
+
const tail = value.slice(exports.REFERRAL_COOKIE.length);
|
|
177
|
+
return exports.REFERRAL_COOKIE_NAMES.map((name) => `${name}${tail}`);
|
|
178
|
+
}
|
|
179
|
+
/** `Set-Cookie` values that delete the context under every name (consent denied or withdrawn). */
|
|
180
|
+
function clearReferralCookies(opts = {}) {
|
|
181
|
+
const domain = opts.domain && /^\.?[a-z0-9.-]+$/i.test(opts.domain) ? `; Domain=${opts.domain}` : '';
|
|
182
|
+
const secure = opts.secure === false ? '' : '; Secure';
|
|
183
|
+
return exports.REFERRAL_COOKIE_NAMES.map((name) => `${name}=; Path=/; Max-Age=0; SameSite=Lax${domain}${secure}`);
|
|
184
|
+
}
|
|
185
|
+
/** Fields for `associate` (server-side attribution at signup) from a context. */
|
|
186
|
+
function associateFields(ctx) {
|
|
187
|
+
if (!ctx)
|
|
188
|
+
return {};
|
|
189
|
+
return {
|
|
190
|
+
...(ctx.anonId ? { anonId: ctx.anonId } : {}),
|
|
191
|
+
...(ctx.clickId ? { referralToken: ctx.clickId } : {}),
|
|
192
|
+
...(ctx.code ? { couponCode: ctx.code } : {}),
|
|
193
|
+
};
|
|
194
|
+
}
|
|
195
|
+
/** SHA-256 hex of a normalised (trimmed, lower-cased) email, for `emailHash` (WebCrypto). */
|
|
196
|
+
async function hashEmail(email) {
|
|
197
|
+
const data = new TextEncoder().encode(email.trim().toLowerCase());
|
|
198
|
+
const digest = await globalThis.crypto.subtle.digest('SHA-256', data);
|
|
199
|
+
return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, '0')).join('');
|
|
200
|
+
}
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `referalli/browser`: the referral tracker for your own pages. It reads
|
|
3
|
+
* `?via=` / `?ref=` / `?aff=` and `ref_click_id` from the landing URL, keeps
|
|
4
|
+
* the context in a first-party cookie (and localStorage) on your domain,
|
|
5
|
+
* records the visit, and attributes the visitor when they sign up.
|
|
6
|
+
*
|
|
7
|
+
* import { createTracker } from '@referalli/sdk/browser';
|
|
8
|
+
* const tracker = await createTracker({ publishableKey: 'tk_...' });
|
|
9
|
+
* // after signup:
|
|
10
|
+
* await tracker.trackSignup({ customerRef: user.id, email: user.email });
|
|
11
|
+
*
|
|
12
|
+
* Consent: pass `consent: 'auto'` (or a CMP id such as `'onetrust'`) and
|
|
13
|
+
* nothing is stored or sent until the visitor's CMP grants it; the referral
|
|
14
|
+
* still reaches `signupMetadata()` from memory. Without a CMP, call
|
|
15
|
+
* `tracker.consent(true | false)`. The default, `'none'`, always stores.
|
|
16
|
+
*
|
|
17
|
+
* Only your public tracking token goes in the browser, never an `rk_` key.
|
|
18
|
+
* Tree-shakeable and dependency-free.
|
|
19
|
+
*/
|
|
20
|
+
import { type ReferralContext } from './attribution.js';
|
|
21
|
+
import { type AffApi, type SnippetConfig } from './snippet.js';
|
|
22
|
+
export { associateFields, hashEmail, mergeReferral, parseReferral, LEGACY_REFERRAL_COOKIE, REFERRAL_COOKIE, REFERRAL_COOKIE_NAMES, REFERRAL_PARAMS, referralFromCookieHeader, referralFromUrl, serializeReferralCookie, serializeReferralCookies, clearReferralCookies, type ReferralContext, type StoredReferral, } from './attribution.js';
|
|
23
|
+
export type { AffApi } from './snippet.js';
|
|
24
|
+
export { AUTO_ORDER, CONSENT_ADAPTER_IDS, type ConsentAdapterId, type ConsentConfig, type ConsentEvidence, type ConsentMode, type ConsentOptions, type ConsentState, } from './consent/port.js';
|
|
25
|
+
export interface TrackerOptions extends Omit<SnippetConfig, 'token' | 'baseUrl'> {
|
|
26
|
+
/** Your org's public tracking token (Settings → Tracking). Safe to ship to browsers. */
|
|
27
|
+
publishableKey: string;
|
|
28
|
+
/** Default `https://referalli.com` (or your tracking domain). */
|
|
29
|
+
baseUrl?: string;
|
|
30
|
+
}
|
|
31
|
+
export interface Tracker extends AffApi {
|
|
32
|
+
/** Attribute this visitor to the customer they just became (hashes `email` in the browser). */
|
|
33
|
+
trackSignup(input: {
|
|
34
|
+
customerRef?: string;
|
|
35
|
+
email?: string;
|
|
36
|
+
}): Promise<void>;
|
|
37
|
+
}
|
|
38
|
+
/** Start tracking this page view. Resolves once the visit beacon is sent (it never rejects for network errors). */
|
|
39
|
+
export declare function createTracker(opts: TrackerOptions): Promise<Tracker>;
|
|
40
|
+
/** The stored referral context without starting a tracker (no network). Null on the server or when there is none. */
|
|
41
|
+
export declare function getReferral(): ReferralContext | null;
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.CONSENT_ADAPTER_IDS = exports.AUTO_ORDER = exports.clearReferralCookies = exports.serializeReferralCookies = exports.serializeReferralCookie = exports.referralFromUrl = exports.referralFromCookieHeader = exports.REFERRAL_PARAMS = exports.REFERRAL_COOKIE_NAMES = exports.REFERRAL_COOKIE = exports.LEGACY_REFERRAL_COOKIE = exports.parseReferral = exports.mergeReferral = exports.hashEmail = exports.associateFields = void 0;
|
|
4
|
+
exports.createTracker = createTracker;
|
|
5
|
+
exports.getReferral = getReferral;
|
|
6
|
+
/**
|
|
7
|
+
* `referalli/browser`: the referral tracker for your own pages. It reads
|
|
8
|
+
* `?via=` / `?ref=` / `?aff=` and `ref_click_id` from the landing URL, keeps
|
|
9
|
+
* the context in a first-party cookie (and localStorage) on your domain,
|
|
10
|
+
* records the visit, and attributes the visitor when they sign up.
|
|
11
|
+
*
|
|
12
|
+
* import { createTracker } from '@referalli/sdk/browser';
|
|
13
|
+
* const tracker = await createTracker({ publishableKey: 'tk_...' });
|
|
14
|
+
* // after signup:
|
|
15
|
+
* await tracker.trackSignup({ customerRef: user.id, email: user.email });
|
|
16
|
+
*
|
|
17
|
+
* Consent: pass `consent: 'auto'` (or a CMP id such as `'onetrust'`) and
|
|
18
|
+
* nothing is stored or sent until the visitor's CMP grants it; the referral
|
|
19
|
+
* still reaches `signupMetadata()` from memory. Without a CMP, call
|
|
20
|
+
* `tracker.consent(true | false)`. The default, `'none'`, always stores.
|
|
21
|
+
*
|
|
22
|
+
* Only your public tracking token goes in the browser, never an `rk_` key.
|
|
23
|
+
* Tree-shakeable and dependency-free.
|
|
24
|
+
*/
|
|
25
|
+
const attribution_js_1 = require("./attribution.js");
|
|
26
|
+
const snippet_js_1 = require("./snippet.js");
|
|
27
|
+
var attribution_js_2 = require("./attribution.js");
|
|
28
|
+
Object.defineProperty(exports, "associateFields", { enumerable: true, get: function () { return attribution_js_2.associateFields; } });
|
|
29
|
+
Object.defineProperty(exports, "hashEmail", { enumerable: true, get: function () { return attribution_js_2.hashEmail; } });
|
|
30
|
+
Object.defineProperty(exports, "mergeReferral", { enumerable: true, get: function () { return attribution_js_2.mergeReferral; } });
|
|
31
|
+
Object.defineProperty(exports, "parseReferral", { enumerable: true, get: function () { return attribution_js_2.parseReferral; } });
|
|
32
|
+
Object.defineProperty(exports, "LEGACY_REFERRAL_COOKIE", { enumerable: true, get: function () { return attribution_js_2.LEGACY_REFERRAL_COOKIE; } });
|
|
33
|
+
Object.defineProperty(exports, "REFERRAL_COOKIE", { enumerable: true, get: function () { return attribution_js_2.REFERRAL_COOKIE; } });
|
|
34
|
+
Object.defineProperty(exports, "REFERRAL_COOKIE_NAMES", { enumerable: true, get: function () { return attribution_js_2.REFERRAL_COOKIE_NAMES; } });
|
|
35
|
+
Object.defineProperty(exports, "REFERRAL_PARAMS", { enumerable: true, get: function () { return attribution_js_2.REFERRAL_PARAMS; } });
|
|
36
|
+
Object.defineProperty(exports, "referralFromCookieHeader", { enumerable: true, get: function () { return attribution_js_2.referralFromCookieHeader; } });
|
|
37
|
+
Object.defineProperty(exports, "referralFromUrl", { enumerable: true, get: function () { return attribution_js_2.referralFromUrl; } });
|
|
38
|
+
Object.defineProperty(exports, "serializeReferralCookie", { enumerable: true, get: function () { return attribution_js_2.serializeReferralCookie; } });
|
|
39
|
+
Object.defineProperty(exports, "serializeReferralCookies", { enumerable: true, get: function () { return attribution_js_2.serializeReferralCookies; } });
|
|
40
|
+
Object.defineProperty(exports, "clearReferralCookies", { enumerable: true, get: function () { return attribution_js_2.clearReferralCookies; } });
|
|
41
|
+
var port_js_1 = require("./consent/port.js");
|
|
42
|
+
Object.defineProperty(exports, "AUTO_ORDER", { enumerable: true, get: function () { return port_js_1.AUTO_ORDER; } });
|
|
43
|
+
Object.defineProperty(exports, "CONSENT_ADAPTER_IDS", { enumerable: true, get: function () { return port_js_1.CONSENT_ADAPTER_IDS; } });
|
|
44
|
+
/** Start tracking this page view. Resolves once the visit beacon is sent (it never rejects for network errors). */
|
|
45
|
+
async function createTracker(opts) {
|
|
46
|
+
if (typeof window === 'undefined')
|
|
47
|
+
throw new Error('referalli/browser: createTracker runs in the browser only');
|
|
48
|
+
const { publishableKey, baseUrl, ...rest } = opts;
|
|
49
|
+
let storage = null;
|
|
50
|
+
try {
|
|
51
|
+
storage = window.localStorage;
|
|
52
|
+
}
|
|
53
|
+
catch {
|
|
54
|
+
/* blocked (privacy mode) */
|
|
55
|
+
}
|
|
56
|
+
const api = await (0, snippet_js_1.initSnippet)({
|
|
57
|
+
win: window,
|
|
58
|
+
doc: document,
|
|
59
|
+
storage,
|
|
60
|
+
fetchFn: (url, init) => fetch(url, { ...init, keepalive: true }),
|
|
61
|
+
consentWindow: window,
|
|
62
|
+
}, { ...rest, token: publishableKey, baseUrl: (baseUrl ?? 'https://referalli.com').replace(/\/+$/, '') });
|
|
63
|
+
return {
|
|
64
|
+
...api,
|
|
65
|
+
trackSignup: async ({ customerRef, email }) => api.identify({ customerRef, emailHash: email ? await (0, attribution_js_1.hashEmail)(email) : undefined }),
|
|
66
|
+
};
|
|
67
|
+
}
|
|
68
|
+
/** The stored referral context without starting a tracker (no network). Null on the server or when there is none. */
|
|
69
|
+
function getReferral() {
|
|
70
|
+
if (typeof document === 'undefined')
|
|
71
|
+
return null;
|
|
72
|
+
// Either name: `referalli_ctx`, or its legacy twin `referally_ctx`.
|
|
73
|
+
let stored = null;
|
|
74
|
+
for (const key of attribution_js_1.REFERRAL_COOKIE_NAMES) {
|
|
75
|
+
try {
|
|
76
|
+
stored = (0, attribution_js_1.parseReferral)(window.localStorage.getItem(key));
|
|
77
|
+
}
|
|
78
|
+
catch {
|
|
79
|
+
/* storage may be blocked */
|
|
80
|
+
}
|
|
81
|
+
if (stored)
|
|
82
|
+
break;
|
|
83
|
+
}
|
|
84
|
+
stored ??= (0, attribution_js_1.referralFromCookieHeader)(document.cookie);
|
|
85
|
+
if (!stored)
|
|
86
|
+
return null;
|
|
87
|
+
return { anonId: stored.anonId, code: stored.code, clickId: stored.clickId, ts: stored.ts };
|
|
88
|
+
}
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
import { ListPromise, type ListEnvelope, type OperationInput, type RequestOptions } from './core.js';
|
|
2
|
+
import type * as T from './generated.js';
|
|
3
|
+
import { type OperationId, type Resources } from './resources.generated.js';
|
|
4
|
+
import { type Webhooks } from './webhooks.js';
|
|
5
|
+
/** Production API. */
|
|
6
|
+
export declare const DEFAULT_BASE_URL = "https://referalli.com";
|
|
7
|
+
type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
|
|
8
|
+
export interface ReferalliOptions {
|
|
9
|
+
/** Your secret `rk_` key. Defaults to the `REFERALLI_API_KEY` environment variable. Keep it on your server. */
|
|
10
|
+
apiKey?: string;
|
|
11
|
+
/** Default `https://referalli.com` (or `REFERALLI_BASE_URL`). */
|
|
12
|
+
baseUrl?: string;
|
|
13
|
+
/**
|
|
14
|
+
* The `referalli-version` to send. Defaults to the version this SDK was
|
|
15
|
+
* generated against; `null` sends none (your key's pinned version applies).
|
|
16
|
+
*/
|
|
17
|
+
apiVersion?: string | null;
|
|
18
|
+
/**
|
|
19
|
+
* Sent as `referalli-mode`. Only needed for session auth; an API key's mode
|
|
20
|
+
* is fixed, and a mismatching header is refused with `mode_mismatch`.
|
|
21
|
+
*/
|
|
22
|
+
mode?: 'live' | 'test';
|
|
23
|
+
/** Milliseconds per attempt. Default 60 000. */
|
|
24
|
+
timeout?: number;
|
|
25
|
+
/** Retries after the first attempt (network errors, timeouts, 408, 429, 5xx). Default 2. */
|
|
26
|
+
maxRetries?: number;
|
|
27
|
+
/** First backoff in milliseconds; doubles per retry, with jitter, up to 8 s. Default 500. */
|
|
28
|
+
retryBaseDelay?: number;
|
|
29
|
+
/** A custom fetch (tests, proxies, instrumentation). Defaults to the global fetch. */
|
|
30
|
+
fetch?: FetchLike;
|
|
31
|
+
/** Headers sent with every request. */
|
|
32
|
+
headers?: Record<string, string>;
|
|
33
|
+
}
|
|
34
|
+
/** One raw request. `kind` says how to read a success: JSON, text, or nothing. */
|
|
35
|
+
export interface RawRequest extends RequestOptions {
|
|
36
|
+
method: string;
|
|
37
|
+
path: string;
|
|
38
|
+
query?: object;
|
|
39
|
+
body?: unknown;
|
|
40
|
+
kind?: 'json' | 'list' | 'text' | 'empty';
|
|
41
|
+
}
|
|
42
|
+
/**
|
|
43
|
+
* The Referalli API client. Every operation is a typed method, grouped by
|
|
44
|
+
* resource:
|
|
45
|
+
*
|
|
46
|
+
* const referalli = new Referalli({ apiKey: process.env.REFERALLI_API_KEY });
|
|
47
|
+
* const link = await referalli.links.create({ programId, partnerId, destinationUrl });
|
|
48
|
+
* for await (const r of referalli.referrals.list({ status: 'active' })) console.log(r.id);
|
|
49
|
+
*
|
|
50
|
+
* POSTs carry an idempotency key (generated unless you pass one) that is
|
|
51
|
+
* reused across retries. Idempotent and keyed requests are retried on network
|
|
52
|
+
* errors, timeouts, 408, 429 and 5xx with exponential backoff and jitter,
|
|
53
|
+
* honouring `Retry-After`. Errors are typed per code (`NotFoundError`, …).
|
|
54
|
+
*/
|
|
55
|
+
export interface Referalli extends Resources {
|
|
56
|
+
}
|
|
57
|
+
export declare class Referalli {
|
|
58
|
+
readonly baseUrl: string;
|
|
59
|
+
readonly apiVersion: string | null;
|
|
60
|
+
readonly mode: 'live' | 'test' | undefined;
|
|
61
|
+
readonly timeout: number;
|
|
62
|
+
readonly maxRetries: number;
|
|
63
|
+
readonly retryBaseDelay: number;
|
|
64
|
+
/** Webhook verification (`await referalli.webhooks.constructEvent(body, headers, secret)`). */
|
|
65
|
+
readonly webhooks: Webhooks;
|
|
66
|
+
private readonly apiKey;
|
|
67
|
+
private readonly fetchFn;
|
|
68
|
+
private readonly headers;
|
|
69
|
+
constructor(options?: ReferalliOptions);
|
|
70
|
+
/** Call any operation by its id (`postPartners`, `getReferralsId`, … see `operations`). */
|
|
71
|
+
call<R = unknown>(id: OperationId, input?: OperationInput & {
|
|
72
|
+
idempotencyKey?: string;
|
|
73
|
+
}, options?: RequestOptions): Promise<R>;
|
|
74
|
+
/** Every item of a list operation, following `next_cursor`: `for await (const p of referalli.listAll('getPartners'))`. */
|
|
75
|
+
listAll<Item = unknown>(id: OperationId, input?: OperationInput, options?: RequestOptions): ListPromise<Item, ListEnvelope<Item>>;
|
|
76
|
+
private listPages;
|
|
77
|
+
/** A raw request to any path (`/v1/...`), with the client's auth, retries and error mapping. */
|
|
78
|
+
request<R = unknown>(req: RawRequest): Promise<R>;
|
|
79
|
+
private backoff;
|
|
80
|
+
/** Attribute a new customer to the partner who referred them: the key server-side call at signup. */
|
|
81
|
+
associate(body: T.PostReferralsAssociateBody, options?: RequestOptions): Promise<T.PostReferralsAssociateResponse>;
|
|
82
|
+
/** Report a customer's product event (`activation` or a custom name) that can pay a bounty. */
|
|
83
|
+
trackEvent(body: {
|
|
84
|
+
programId: string;
|
|
85
|
+
customerRef: string;
|
|
86
|
+
event: string;
|
|
87
|
+
occurredAt?: string;
|
|
88
|
+
idempotencyKey?: string;
|
|
89
|
+
}, options?: RequestOptions): Promise<T.PostTrackEventsResponse>;
|
|
90
|
+
/** Report value facts (payments, credit, costs). Up to 500 per call, each idempotent by `externalId`. */
|
|
91
|
+
reportValueEvents(events: T.PostValueEventsBody['events'], options?: RequestOptions): Promise<T.PostValueEventsResponse>;
|
|
92
|
+
/** A payment, with the cash received and any store credit or discount that paid part of it. */
|
|
93
|
+
reportPayment(input: ValueFact, options?: RequestOptions): Promise<T.PostValueEventsResponse>;
|
|
94
|
+
}
|
|
95
|
+
type ValueEvent = T.PostValueEventsBody['events'][number];
|
|
96
|
+
type ValueFact = Omit<ValueEvent, 'kind'>;
|
|
97
|
+
export {};
|