@codefast/tracking 0.0.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/LICENSE +21 -0
- package/README.md +90 -0
- package/dist/client/consent-storage.d.mts +11 -0
- package/dist/client/consent-storage.mjs +27 -0
- package/dist/client/create-client-tracker.d.mts +27 -0
- package/dist/client/create-client-tracker.mjs +53 -0
- package/dist/client/gpc.d.mts +8 -0
- package/dist/client/gpc.mjs +10 -0
- package/dist/client/index.d.mts +8 -0
- package/dist/client/index.mjs +8 -0
- package/dist/client/lifecycle.d.mts +18 -0
- package/dist/client/lifecycle.mjs +28 -0
- package/dist/client/local-storage.d.mts +10 -0
- package/dist/client/local-storage.mjs +24 -0
- package/dist/client/queue.d.mts +42 -0
- package/dist/client/queue.mjs +69 -0
- package/dist/client/router.d.mts +26 -0
- package/dist/client/router.mjs +15 -0
- package/dist/core/consent.d.mts +37 -0
- package/dist/core/consent.mjs +25 -0
- package/dist/core/destination.d.mts +13 -0
- package/dist/core/destination.mjs +1 -0
- package/dist/core/event-catalog.d.mts +28 -0
- package/dist/core/event-catalog.mjs +10 -0
- package/dist/core/event-id.d.mts +8 -0
- package/dist/core/event-id.mjs +10 -0
- package/dist/core/index.d.mts +6 -0
- package/dist/core/index.mjs +4 -0
- package/dist/core/tracked-event.d.mts +15 -0
- package/dist/core/tracked-event.mjs +1 -0
- package/dist/destinations/http-destination.d.mts +15 -0
- package/dist/destinations/http-destination.mjs +23 -0
- package/dist/destinations/index.d.mts +3 -0
- package/dist/destinations/index.mjs +3 -0
- package/dist/destinations/vercel-analytics.d.mts +11 -0
- package/dist/destinations/vercel-analytics.mjs +27 -0
- package/dist/index.d.mts +6 -0
- package/dist/index.mjs +4 -0
- package/dist/react/consent-banner.d.mts +41 -0
- package/dist/react/consent-banner.mjs +42 -0
- package/dist/react/index.d.mts +3 -0
- package/dist/react/index.mjs +3 -0
- package/dist/react/use-consent.d.mts +24 -0
- package/dist/react/use-consent.mjs +31 -0
- package/dist/server/create-server-tracker.d.mts +28 -0
- package/dist/server/create-server-tracker.mjs +48 -0
- package/dist/server/index.d.mts +3 -0
- package/dist/server/index.mjs +3 -0
- package/dist/server/region.d.mts +16 -0
- package/dist/server/region.mjs +52 -0
- package/package.json +242 -0
- package/src/client/consent-storage.ts +30 -0
- package/src/client/create-client-tracker.ts +97 -0
- package/src/client/gpc.ts +11 -0
- package/src/client/index.ts +17 -0
- package/src/client/lifecycle.ts +45 -0
- package/src/client/local-storage.ts +29 -0
- package/src/client/queue.ts +110 -0
- package/src/client/router.ts +33 -0
- package/src/core/consent.ts +58 -0
- package/src/core/destination.ts +10 -0
- package/src/core/event-catalog.ts +32 -0
- package/src/core/event-id.ts +7 -0
- package/src/core/index.ts +11 -0
- package/src/core/tracked-event.ts +12 -0
- package/src/destinations/http-destination.ts +28 -0
- package/src/destinations/index.ts +4 -0
- package/src/destinations/vercel-analytics.ts +37 -0
- package/src/index.ts +13 -0
- package/src/react/consent-banner.tsx +64 -0
- package/src/react/index.ts +5 -0
- package/src/react/use-consent.ts +53 -0
- package/src/server/create-server-tracker.ts +105 -0
- package/src/server/index.ts +4 -0
- package/src/server/region.ts +66 -0
package/package.json
ADDED
|
@@ -0,0 +1,242 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@codefast/tracking",
|
|
3
|
+
"version": "0.0.0",
|
|
4
|
+
"description": "Fullstack, type-safe event tracking for TanStack Start — isomorphic client/server trackers over a per-app Zod event catalog",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"analytics",
|
|
7
|
+
"codefast",
|
|
8
|
+
"consent",
|
|
9
|
+
"tanstack-start",
|
|
10
|
+
"tracking",
|
|
11
|
+
"typescript",
|
|
12
|
+
"zod"
|
|
13
|
+
],
|
|
14
|
+
"homepage": "https://github.com/codefastlabs/codefast/tree/main/packages/tracking#readme",
|
|
15
|
+
"bugs": {
|
|
16
|
+
"url": "https://github.com/codefastlabs/codefast/issues"
|
|
17
|
+
},
|
|
18
|
+
"license": "MIT",
|
|
19
|
+
"author": "Vuong Phan <mr.thevuong@gmail.com>",
|
|
20
|
+
"repository": {
|
|
21
|
+
"type": "git",
|
|
22
|
+
"url": "git+https://github.com/codefastlabs/codefast.git",
|
|
23
|
+
"directory": "packages/tracking"
|
|
24
|
+
},
|
|
25
|
+
"files": [
|
|
26
|
+
"dist",
|
|
27
|
+
"src",
|
|
28
|
+
"CHANGELOG.md",
|
|
29
|
+
"README.md",
|
|
30
|
+
"LICENSE"
|
|
31
|
+
],
|
|
32
|
+
"type": "module",
|
|
33
|
+
"sideEffects": false,
|
|
34
|
+
"main": "./dist/index.mjs",
|
|
35
|
+
"module": "./dist/index.mjs",
|
|
36
|
+
"types": "./dist/index.d.mts",
|
|
37
|
+
"imports": {
|
|
38
|
+
"#/tests/*": [
|
|
39
|
+
"./tests/*",
|
|
40
|
+
"./tests/*.ts",
|
|
41
|
+
"./tests/*.tsx",
|
|
42
|
+
"./tests/*/index.ts",
|
|
43
|
+
"./tests/*/index.tsx"
|
|
44
|
+
],
|
|
45
|
+
"#/*": [
|
|
46
|
+
"./src/*",
|
|
47
|
+
"./src/*.ts",
|
|
48
|
+
"./src/*.tsx",
|
|
49
|
+
"./src/*/index.ts",
|
|
50
|
+
"./src/*/index.tsx"
|
|
51
|
+
]
|
|
52
|
+
},
|
|
53
|
+
"exports": {
|
|
54
|
+
".": {
|
|
55
|
+
"source": "./src/index.ts",
|
|
56
|
+
"types": "./dist/index.d.mts",
|
|
57
|
+
"import": "./dist/index.mjs"
|
|
58
|
+
},
|
|
59
|
+
"./client": {
|
|
60
|
+
"source": "./src/client/index.ts",
|
|
61
|
+
"types": "./dist/client/index.d.mts",
|
|
62
|
+
"import": "./dist/client/index.mjs"
|
|
63
|
+
},
|
|
64
|
+
"./client/consent-storage": {
|
|
65
|
+
"source": "./src/client/consent-storage.ts",
|
|
66
|
+
"types": "./dist/client/consent-storage.d.mts",
|
|
67
|
+
"import": "./dist/client/consent-storage.mjs"
|
|
68
|
+
},
|
|
69
|
+
"./client/create-client-tracker": {
|
|
70
|
+
"source": "./src/client/create-client-tracker.ts",
|
|
71
|
+
"types": "./dist/client/create-client-tracker.d.mts",
|
|
72
|
+
"import": "./dist/client/create-client-tracker.mjs"
|
|
73
|
+
},
|
|
74
|
+
"./client/gpc": {
|
|
75
|
+
"source": "./src/client/gpc.ts",
|
|
76
|
+
"types": "./dist/client/gpc.d.mts",
|
|
77
|
+
"import": "./dist/client/gpc.mjs"
|
|
78
|
+
},
|
|
79
|
+
"./client/lifecycle": {
|
|
80
|
+
"source": "./src/client/lifecycle.ts",
|
|
81
|
+
"types": "./dist/client/lifecycle.d.mts",
|
|
82
|
+
"import": "./dist/client/lifecycle.mjs"
|
|
83
|
+
},
|
|
84
|
+
"./client/local-storage": {
|
|
85
|
+
"source": "./src/client/local-storage.ts",
|
|
86
|
+
"types": "./dist/client/local-storage.d.mts",
|
|
87
|
+
"import": "./dist/client/local-storage.mjs"
|
|
88
|
+
},
|
|
89
|
+
"./client/queue": {
|
|
90
|
+
"source": "./src/client/queue.ts",
|
|
91
|
+
"types": "./dist/client/queue.d.mts",
|
|
92
|
+
"import": "./dist/client/queue.mjs"
|
|
93
|
+
},
|
|
94
|
+
"./client/router": {
|
|
95
|
+
"source": "./src/client/router.ts",
|
|
96
|
+
"types": "./dist/client/router.d.mts",
|
|
97
|
+
"import": "./dist/client/router.mjs"
|
|
98
|
+
},
|
|
99
|
+
"./core": {
|
|
100
|
+
"source": "./src/core/index.ts",
|
|
101
|
+
"types": "./dist/core/index.d.mts",
|
|
102
|
+
"import": "./dist/core/index.mjs"
|
|
103
|
+
},
|
|
104
|
+
"./core/consent": {
|
|
105
|
+
"source": "./src/core/consent.ts",
|
|
106
|
+
"types": "./dist/core/consent.d.mts",
|
|
107
|
+
"import": "./dist/core/consent.mjs"
|
|
108
|
+
},
|
|
109
|
+
"./core/destination": {
|
|
110
|
+
"source": "./src/core/destination.ts",
|
|
111
|
+
"types": "./dist/core/destination.d.mts",
|
|
112
|
+
"import": "./dist/core/destination.mjs"
|
|
113
|
+
},
|
|
114
|
+
"./core/event-catalog": {
|
|
115
|
+
"source": "./src/core/event-catalog.ts",
|
|
116
|
+
"types": "./dist/core/event-catalog.d.mts",
|
|
117
|
+
"import": "./dist/core/event-catalog.mjs"
|
|
118
|
+
},
|
|
119
|
+
"./core/event-id": {
|
|
120
|
+
"source": "./src/core/event-id.ts",
|
|
121
|
+
"types": "./dist/core/event-id.d.mts",
|
|
122
|
+
"import": "./dist/core/event-id.mjs"
|
|
123
|
+
},
|
|
124
|
+
"./core/tracked-event": {
|
|
125
|
+
"source": "./src/core/tracked-event.ts",
|
|
126
|
+
"types": "./dist/core/tracked-event.d.mts",
|
|
127
|
+
"import": "./dist/core/tracked-event.mjs"
|
|
128
|
+
},
|
|
129
|
+
"./destinations": {
|
|
130
|
+
"source": "./src/destinations/index.ts",
|
|
131
|
+
"types": "./dist/destinations/index.d.mts",
|
|
132
|
+
"import": "./dist/destinations/index.mjs"
|
|
133
|
+
},
|
|
134
|
+
"./destinations/http-destination": {
|
|
135
|
+
"source": "./src/destinations/http-destination.ts",
|
|
136
|
+
"types": "./dist/destinations/http-destination.d.mts",
|
|
137
|
+
"import": "./dist/destinations/http-destination.mjs"
|
|
138
|
+
},
|
|
139
|
+
"./destinations/vercel-analytics": {
|
|
140
|
+
"source": "./src/destinations/vercel-analytics.ts",
|
|
141
|
+
"types": "./dist/destinations/vercel-analytics.d.mts",
|
|
142
|
+
"import": "./dist/destinations/vercel-analytics.mjs"
|
|
143
|
+
},
|
|
144
|
+
"./react": {
|
|
145
|
+
"source": "./src/react/index.ts",
|
|
146
|
+
"types": "./dist/react/index.d.mts",
|
|
147
|
+
"import": "./dist/react/index.mjs"
|
|
148
|
+
},
|
|
149
|
+
"./react/consent-banner": {
|
|
150
|
+
"source": "./src/react/consent-banner.tsx",
|
|
151
|
+
"types": "./dist/react/consent-banner.d.mts",
|
|
152
|
+
"import": "./dist/react/consent-banner.mjs"
|
|
153
|
+
},
|
|
154
|
+
"./react/use-consent": {
|
|
155
|
+
"source": "./src/react/use-consent.ts",
|
|
156
|
+
"types": "./dist/react/use-consent.d.mts",
|
|
157
|
+
"import": "./dist/react/use-consent.mjs"
|
|
158
|
+
},
|
|
159
|
+
"./server": {
|
|
160
|
+
"source": "./src/server/index.ts",
|
|
161
|
+
"types": "./dist/server/index.d.mts",
|
|
162
|
+
"import": "./dist/server/index.mjs"
|
|
163
|
+
},
|
|
164
|
+
"./server/create-server-tracker": {
|
|
165
|
+
"source": "./src/server/create-server-tracker.ts",
|
|
166
|
+
"types": "./dist/server/create-server-tracker.d.mts",
|
|
167
|
+
"import": "./dist/server/create-server-tracker.mjs"
|
|
168
|
+
},
|
|
169
|
+
"./server/region": {
|
|
170
|
+
"source": "./src/server/region.ts",
|
|
171
|
+
"types": "./dist/server/region.d.mts",
|
|
172
|
+
"import": "./dist/server/region.mjs"
|
|
173
|
+
},
|
|
174
|
+
"./package.json": "./package.json"
|
|
175
|
+
},
|
|
176
|
+
"publishConfig": {
|
|
177
|
+
"access": "public"
|
|
178
|
+
},
|
|
179
|
+
"dependencies": {
|
|
180
|
+
"zod": "^4.4.3"
|
|
181
|
+
},
|
|
182
|
+
"devDependencies": {
|
|
183
|
+
"@testing-library/dom": "^10.4.1",
|
|
184
|
+
"@testing-library/jest-dom": "^6.9.1",
|
|
185
|
+
"@testing-library/react": "^16.3.2",
|
|
186
|
+
"@testing-library/user-event": "^14.6.1",
|
|
187
|
+
"@types/node": "^26.1.0",
|
|
188
|
+
"@types/react": "^19.2.17",
|
|
189
|
+
"@types/react-dom": "^19.2.3",
|
|
190
|
+
"@typescript/native-preview": "7.0.0-dev.20260704.1",
|
|
191
|
+
"@vercel/analytics": "^2.0.1",
|
|
192
|
+
"@vitejs/plugin-react": "^6.0.3",
|
|
193
|
+
"@vitest/coverage-v8": "^4.1.9",
|
|
194
|
+
"expect-type": "^1.4.0",
|
|
195
|
+
"jsdom": "^29.1.1",
|
|
196
|
+
"react": "^19.2.7",
|
|
197
|
+
"react-dom": "^19.2.7",
|
|
198
|
+
"tsdown": "^0.22.3",
|
|
199
|
+
"typescript": "^6.0.3",
|
|
200
|
+
"vitest": "^4.1.9",
|
|
201
|
+
"@codefast/typescript-config": "0.5.0-canary.3"
|
|
202
|
+
},
|
|
203
|
+
"peerDependencies": {
|
|
204
|
+
"@types/react": ">=19.0.0",
|
|
205
|
+
"@types/react-dom": ">=19.0.0",
|
|
206
|
+
"@vercel/analytics": ">=1.0.0",
|
|
207
|
+
"react": ">=19.0.0",
|
|
208
|
+
"react-dom": ">=19.0.0"
|
|
209
|
+
},
|
|
210
|
+
"peerDependenciesMeta": {
|
|
211
|
+
"@types/react": {
|
|
212
|
+
"optional": true
|
|
213
|
+
},
|
|
214
|
+
"@types/react-dom": {
|
|
215
|
+
"optional": true
|
|
216
|
+
},
|
|
217
|
+
"@vercel/analytics": {
|
|
218
|
+
"optional": true
|
|
219
|
+
},
|
|
220
|
+
"react": {
|
|
221
|
+
"optional": true
|
|
222
|
+
},
|
|
223
|
+
"react-dom": {
|
|
224
|
+
"optional": true
|
|
225
|
+
}
|
|
226
|
+
},
|
|
227
|
+
"engines": {
|
|
228
|
+
"node": ">=24.0.0"
|
|
229
|
+
},
|
|
230
|
+
"scripts": {
|
|
231
|
+
"build": "tsdown",
|
|
232
|
+
"check-types": "tsgo --noEmit",
|
|
233
|
+
"clean": "rm -rf dist",
|
|
234
|
+
"test": "vitest run",
|
|
235
|
+
"test:coverage": "vitest run --coverage",
|
|
236
|
+
"test:e2e": "vitest run tests/e2e",
|
|
237
|
+
"test:integration": "vitest run tests/integration",
|
|
238
|
+
"test:type": "vitest run tests/types",
|
|
239
|
+
"test:unit": "vitest run tests/unit",
|
|
240
|
+
"test:watch": "vitest"
|
|
241
|
+
}
|
|
242
|
+
}
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
import type { ConsentRecord, ConsentStorage } from "#/core/consent";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* `localStorage`-backed consent storage — corrupt/missing state is treated as "no
|
|
5
|
+
* decision yet" rather than thrown, so a storage glitch degrades to re-prompting for
|
|
6
|
+
* consent instead of crashing the app.
|
|
7
|
+
*/
|
|
8
|
+
export function createLocalStorageConsentStorage(storageKey: string): ConsentStorage {
|
|
9
|
+
return {
|
|
10
|
+
clear(): void {
|
|
11
|
+
localStorage.removeItem(storageKey);
|
|
12
|
+
},
|
|
13
|
+
load(): ConsentRecord | undefined {
|
|
14
|
+
const raw = localStorage.getItem(storageKey);
|
|
15
|
+
|
|
16
|
+
if (!raw) {
|
|
17
|
+
return undefined;
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
try {
|
|
21
|
+
return JSON.parse(raw) as ConsentRecord;
|
|
22
|
+
} catch {
|
|
23
|
+
return undefined;
|
|
24
|
+
}
|
|
25
|
+
},
|
|
26
|
+
save(record: ConsentRecord): void {
|
|
27
|
+
localStorage.setItem(storageKey, JSON.stringify(record));
|
|
28
|
+
},
|
|
29
|
+
};
|
|
30
|
+
}
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
import type { z } from "zod";
|
|
2
|
+
|
|
3
|
+
import { EventQueue, type EventQueueStorage } from "#/client/queue";
|
|
4
|
+
import type { Destination } from "#/core/destination";
|
|
5
|
+
import type { EventCatalog, EventsOf } from "#/core/event-catalog";
|
|
6
|
+
import { generateEventId } from "#/core/event-id";
|
|
7
|
+
import type { TrackedEvent } from "#/core/tracked-event";
|
|
8
|
+
|
|
9
|
+
export interface ClientTrackerOptions<Catalog extends EventCatalog> {
|
|
10
|
+
anonymousId: string;
|
|
11
|
+
catalog: Catalog;
|
|
12
|
+
destinations: Array<Destination>;
|
|
13
|
+
maxQueueSize?: number;
|
|
14
|
+
maxRetries?: number;
|
|
15
|
+
storage: EventQueueStorage;
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
export interface ClientTracker<Catalog extends EventCatalog> {
|
|
19
|
+
/** Drops every pending event without sending it — call this when consent is revoked. */
|
|
20
|
+
clear: () => void;
|
|
21
|
+
flush: () => Promise<void>;
|
|
22
|
+
/** Synchronous, best-effort flush via `navigator.sendBeacon` — for page unload only. */
|
|
23
|
+
flushWithBeacon: (endpoint: string) => void;
|
|
24
|
+
identify: (userId: string, traits?: Record<string, unknown>) => void;
|
|
25
|
+
page: (name?: string, props?: Record<string, unknown>) => void;
|
|
26
|
+
track: <Name extends keyof EventsOf<Catalog, "client">>(
|
|
27
|
+
name: Name,
|
|
28
|
+
props: z.infer<EventsOf<Catalog, "client">[Name]["schema"]>,
|
|
29
|
+
) => void;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
export function createClientTracker<Catalog extends EventCatalog>(
|
|
33
|
+
options: ClientTrackerOptions<Catalog>,
|
|
34
|
+
): ClientTracker<Catalog> {
|
|
35
|
+
const queue = new EventQueue({
|
|
36
|
+
destinations: options.destinations,
|
|
37
|
+
maxQueueSize: options.maxQueueSize,
|
|
38
|
+
maxRetries: options.maxRetries,
|
|
39
|
+
storage: options.storage,
|
|
40
|
+
});
|
|
41
|
+
let userId: string | undefined;
|
|
42
|
+
|
|
43
|
+
function enqueue(name: string, props: Record<string, unknown>): void {
|
|
44
|
+
const envelope: TrackedEvent = {
|
|
45
|
+
anonymousId: options.anonymousId,
|
|
46
|
+
eventId: generateEventId(),
|
|
47
|
+
name,
|
|
48
|
+
owner: "client",
|
|
49
|
+
props,
|
|
50
|
+
timestamp: Date.now(),
|
|
51
|
+
...(userId === undefined ? {} : { userId }),
|
|
52
|
+
};
|
|
53
|
+
|
|
54
|
+
queue.enqueue(envelope);
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
return {
|
|
58
|
+
clear: () => {
|
|
59
|
+
queue.clear();
|
|
60
|
+
},
|
|
61
|
+
flush: () => queue.flush(),
|
|
62
|
+
flushWithBeacon(endpoint) {
|
|
63
|
+
const events = queue.drain();
|
|
64
|
+
|
|
65
|
+
if (events.length === 0) {
|
|
66
|
+
return;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
const delivered = navigator.sendBeacon(endpoint, JSON.stringify(events));
|
|
70
|
+
|
|
71
|
+
if (!delivered) {
|
|
72
|
+
for (const event of events) {
|
|
73
|
+
queue.enqueue(event);
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
},
|
|
77
|
+
identify(id, traits = {}) {
|
|
78
|
+
userId = id;
|
|
79
|
+
enqueue("$identify", traits);
|
|
80
|
+
},
|
|
81
|
+
page(name, props = {}) {
|
|
82
|
+
enqueue("$page_viewed", name === undefined ? props : { name, ...props });
|
|
83
|
+
},
|
|
84
|
+
track(name, props) {
|
|
85
|
+
// noUncheckedIndexedAccess types this as possibly undefined; the owner check also
|
|
86
|
+
// guards callers who bypass the EventsOf filter with an `as` cast.
|
|
87
|
+
const definition = options.catalog[name];
|
|
88
|
+
|
|
89
|
+
if (!definition || definition.owner !== "client") {
|
|
90
|
+
throw new Error(`Unknown client-owned event: ${String(name)}`);
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
definition.schema.parse(props);
|
|
94
|
+
enqueue(name as string, props as Record<string, unknown>);
|
|
95
|
+
},
|
|
96
|
+
};
|
|
97
|
+
}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
interface NavigatorWithGpc extends Navigator {
|
|
2
|
+
globalPrivacyControl?: boolean;
|
|
3
|
+
}
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* Global Privacy Control isn't in lib.dom yet, hence the local interface extension.
|
|
7
|
+
* CCPA/CPRA requires honoring this as an opt-out signal even under the opt-out default.
|
|
8
|
+
*/
|
|
9
|
+
export function hasGlobalPrivacyControlSignal(): boolean {
|
|
10
|
+
return (navigator as NavigatorWithGpc).globalPrivacyControl === true;
|
|
11
|
+
}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
export type { ClientTracker, ClientTrackerOptions } from "#/client/create-client-tracker";
|
|
2
|
+
export { createClientTracker } from "#/client/create-client-tracker";
|
|
3
|
+
|
|
4
|
+
export { createLocalStorageConsentStorage } from "#/client/consent-storage";
|
|
5
|
+
|
|
6
|
+
export { hasGlobalPrivacyControlSignal } from "#/client/gpc";
|
|
7
|
+
|
|
8
|
+
export type { ClientLifecycleOptions } from "#/client/lifecycle";
|
|
9
|
+
export { attachClientLifecycle } from "#/client/lifecycle";
|
|
10
|
+
|
|
11
|
+
export { createLocalStorageQueueStorage } from "#/client/local-storage";
|
|
12
|
+
|
|
13
|
+
export type { EventQueueOptions, EventQueueStorage } from "#/client/queue";
|
|
14
|
+
export { EventQueue } from "#/client/queue";
|
|
15
|
+
|
|
16
|
+
export type { RouterLike } from "#/client/router";
|
|
17
|
+
export { attachRouterPageTracking } from "#/client/router";
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
import type { ClientTracker } from "#/client/create-client-tracker";
|
|
2
|
+
import type { EventCatalog } from "#/core/event-catalog";
|
|
3
|
+
|
|
4
|
+
export interface ClientLifecycleOptions {
|
|
5
|
+
/** `sendBeacon` target used on unload — omit to skip the unload flush entirely. */
|
|
6
|
+
beaconEndpoint?: string;
|
|
7
|
+
flushIntervalMs?: number;
|
|
8
|
+
}
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* Wires the two flush triggers the queue itself can't own (batch-size is handled inside
|
|
12
|
+
* `EventQueue`): a periodic interval flush, and a best-effort `sendBeacon` flush on
|
|
13
|
+
* unload — `fetch` isn't reliable once the page starts unloading, `sendBeacon` is.
|
|
14
|
+
* Returns a cleanup function to remove all listeners/timers.
|
|
15
|
+
*/
|
|
16
|
+
export function attachClientLifecycle<Catalog extends EventCatalog>(
|
|
17
|
+
tracker: Pick<ClientTracker<Catalog>, "flush" | "flushWithBeacon">,
|
|
18
|
+
options: ClientLifecycleOptions = {},
|
|
19
|
+
): () => void {
|
|
20
|
+
const flushIntervalMs = options.flushIntervalMs ?? 10_000;
|
|
21
|
+
const intervalId = setInterval(() => {
|
|
22
|
+
void tracker.flush();
|
|
23
|
+
}, flushIntervalMs);
|
|
24
|
+
|
|
25
|
+
function flushOnUnload(): void {
|
|
26
|
+
if (options.beaconEndpoint !== undefined) {
|
|
27
|
+
tracker.flushWithBeacon(options.beaconEndpoint);
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
function handleVisibilityChange(): void {
|
|
32
|
+
if (document.visibilityState === "hidden") {
|
|
33
|
+
flushOnUnload();
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
document.addEventListener("visibilitychange", handleVisibilityChange);
|
|
38
|
+
window.addEventListener("pagehide", flushOnUnload);
|
|
39
|
+
|
|
40
|
+
return () => {
|
|
41
|
+
clearInterval(intervalId);
|
|
42
|
+
document.removeEventListener("visibilitychange", handleVisibilityChange);
|
|
43
|
+
window.removeEventListener("pagehide", flushOnUnload);
|
|
44
|
+
};
|
|
45
|
+
}
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import type { EventQueueStorage } from "#/client/queue";
|
|
2
|
+
import type { TrackedEvent } from "#/core/tracked-event";
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* `localStorage`-backed queue storage — corrupt/missing state is treated as empty
|
|
6
|
+
* rather than thrown, since a lost offline queue is preferable to a crashing app.
|
|
7
|
+
*/
|
|
8
|
+
export function createLocalStorageQueueStorage(storageKey: string): EventQueueStorage {
|
|
9
|
+
return {
|
|
10
|
+
load(): Array<TrackedEvent> {
|
|
11
|
+
const raw = localStorage.getItem(storageKey);
|
|
12
|
+
|
|
13
|
+
if (!raw) {
|
|
14
|
+
return [];
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
try {
|
|
18
|
+
const parsed: unknown = JSON.parse(raw);
|
|
19
|
+
|
|
20
|
+
return Array.isArray(parsed) ? (parsed as Array<TrackedEvent>) : [];
|
|
21
|
+
} catch {
|
|
22
|
+
return [];
|
|
23
|
+
}
|
|
24
|
+
},
|
|
25
|
+
save(events: Array<TrackedEvent>): void {
|
|
26
|
+
localStorage.setItem(storageKey, JSON.stringify(events));
|
|
27
|
+
},
|
|
28
|
+
};
|
|
29
|
+
}
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
import type { Destination } from "#/core/destination";
|
|
2
|
+
import type { TrackedEvent } from "#/core/tracked-event";
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* Persistence backend for the offline queue — a thin wrapper so tests and non-browser
|
|
6
|
+
* environments can swap in an in-memory implementation instead of real `localStorage`.
|
|
7
|
+
*/
|
|
8
|
+
export interface EventQueueStorage {
|
|
9
|
+
load: () => Array<TrackedEvent>;
|
|
10
|
+
save: (events: Array<TrackedEvent>) => void;
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
export interface EventQueueOptions {
|
|
14
|
+
destinations: Array<Destination>;
|
|
15
|
+
flushBatchSize?: number | undefined;
|
|
16
|
+
maxQueueSize?: number | undefined;
|
|
17
|
+
maxRetries?: number | undefined;
|
|
18
|
+
storage: EventQueueStorage;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
interface QueuedEvent {
|
|
22
|
+
attempts: number;
|
|
23
|
+
event: TrackedEvent;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* Client-side batching/offline queue: persists across reloads, caps its size
|
|
28
|
+
* (drop-oldest), and retries a failed batch up to `maxRetries` times.
|
|
29
|
+
*/
|
|
30
|
+
export class EventQueue {
|
|
31
|
+
private readonly destinations: Array<Destination>;
|
|
32
|
+
private readonly flushBatchSize: number;
|
|
33
|
+
private readonly maxQueueSize: number;
|
|
34
|
+
private readonly maxRetries: number;
|
|
35
|
+
private pending: Array<QueuedEvent>;
|
|
36
|
+
private readonly storage: EventQueueStorage;
|
|
37
|
+
|
|
38
|
+
constructor(options: EventQueueOptions) {
|
|
39
|
+
this.destinations = options.destinations;
|
|
40
|
+
this.storage = options.storage;
|
|
41
|
+
this.maxQueueSize = options.maxQueueSize ?? 500;
|
|
42
|
+
this.maxRetries = options.maxRetries ?? 3;
|
|
43
|
+
this.flushBatchSize = options.flushBatchSize ?? 20;
|
|
44
|
+
this.pending = this.storage.load().map((event) => ({ attempts: 0, event }));
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
get size(): number {
|
|
48
|
+
return this.pending.length;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/** Drops every pending event without sending it — used on consent revoke. */
|
|
52
|
+
clear(): void {
|
|
53
|
+
this.pending = [];
|
|
54
|
+
this.persist();
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/** Empties the queue synchronously for `navigator.sendBeacon`, which can't be awaited. */
|
|
58
|
+
drain(): Array<TrackedEvent> {
|
|
59
|
+
const events = this.pending.map((queued) => queued.event);
|
|
60
|
+
|
|
61
|
+
this.pending = [];
|
|
62
|
+
this.persist();
|
|
63
|
+
|
|
64
|
+
return events;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
enqueue(event: TrackedEvent): void {
|
|
68
|
+
this.pending.push({ attempts: 0, event });
|
|
69
|
+
|
|
70
|
+
if (this.pending.length > this.maxQueueSize) {
|
|
71
|
+
this.pending = this.pending.slice(this.pending.length - this.maxQueueSize);
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
this.persist();
|
|
75
|
+
|
|
76
|
+
if (this.pending.length >= this.flushBatchSize) {
|
|
77
|
+
void this.flush();
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
async flush(): Promise<void> {
|
|
82
|
+
if (this.pending.length === 0) {
|
|
83
|
+
return;
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
const batch = this.pending;
|
|
87
|
+
|
|
88
|
+
this.pending = [];
|
|
89
|
+
|
|
90
|
+
const results = await Promise.allSettled(
|
|
91
|
+
batch.map(async (queued) => {
|
|
92
|
+
await Promise.all(this.destinations.map(async (destination) => destination.send(queued.event)));
|
|
93
|
+
}),
|
|
94
|
+
);
|
|
95
|
+
|
|
96
|
+
for (const [index, result] of results.entries()) {
|
|
97
|
+
const queued = batch[index];
|
|
98
|
+
|
|
99
|
+
if (result.status === "rejected" && queued && queued.attempts < this.maxRetries) {
|
|
100
|
+
this.pending.push({ attempts: queued.attempts + 1, event: queued.event });
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
this.persist();
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
private persist(): void {
|
|
108
|
+
this.storage.save(this.pending.map((queued) => queued.event));
|
|
109
|
+
}
|
|
110
|
+
}
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import type { ClientTracker } from "#/client/create-client-tracker";
|
|
2
|
+
import type { EventCatalog } from "#/core/event-catalog";
|
|
3
|
+
|
|
4
|
+
interface ResolvedNavigation {
|
|
5
|
+
toLocation: {
|
|
6
|
+
href: string;
|
|
7
|
+
pathname: string;
|
|
8
|
+
};
|
|
9
|
+
}
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* Structurally matches `Router["subscribe"]` from `@tanstack/router-core` for the
|
|
13
|
+
* `"onResolved"` event — duck-typed so this package doesn't depend on TanStack Router.
|
|
14
|
+
*/
|
|
15
|
+
export interface RouterLike {
|
|
16
|
+
subscribe: (eventType: "onResolved", fn: (event: ResolvedNavigation) => void) => () => void;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
/**
|
|
20
|
+
* `onResolved` (not `popstate`) is what fires on SPA navigation in TanStack Router;
|
|
21
|
+
* `popstate` only fires for browser back/forward. Page views are low-frequency, so this
|
|
22
|
+
* flushes right away instead of waiting on the batch queue's interval/size threshold —
|
|
23
|
+
* a slow navigation shouldn't leave a pageview stranded if the tab closes right after.
|
|
24
|
+
*/
|
|
25
|
+
export function attachRouterPageTracking<Catalog extends EventCatalog>(
|
|
26
|
+
tracker: Pick<ClientTracker<Catalog>, "flush" | "page">,
|
|
27
|
+
router: RouterLike,
|
|
28
|
+
): () => void {
|
|
29
|
+
return router.subscribe("onResolved", (event) => {
|
|
30
|
+
tracker.page(event.toLocation.pathname, { href: event.toLocation.href });
|
|
31
|
+
void tracker.flush();
|
|
32
|
+
});
|
|
33
|
+
}
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
export type ConsentRegion = "eu" | "other" | "us" | "vn";
|
|
2
|
+
|
|
3
|
+
export type ConsentMode = "opt-in" | "opt-out";
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* GDPR (EU) and Nghị định 13/2023 (VN) require explicit opt-in before any non-essential
|
|
7
|
+
* tracking; CCPA/CPRA (US) defaults to opt-out instead. There is no single global default
|
|
8
|
+
* that satisfies both, so the mode is resolved per region.
|
|
9
|
+
*/
|
|
10
|
+
export function resolveConsentMode(region: ConsentRegion): ConsentMode {
|
|
11
|
+
switch (region) {
|
|
12
|
+
case "eu":
|
|
13
|
+
case "vn": {
|
|
14
|
+
return "opt-in";
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
case "other":
|
|
18
|
+
case "us": {
|
|
19
|
+
return "opt-out";
|
|
20
|
+
}
|
|
21
|
+
}
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/**
|
|
25
|
+
* Under CCPA/CPRA, a Global Privacy Control signal must be honored as an opt-out even
|
|
26
|
+
* though the region default is opt-out. Under opt-in regions, tracking never starts
|
|
27
|
+
* until consent is explicitly granted, GPC signal or not.
|
|
28
|
+
*/
|
|
29
|
+
export function shouldTrackByDefault(mode: ConsentMode, hasGlobalPrivacyControlSignal: boolean): boolean {
|
|
30
|
+
if (mode === "opt-in") {
|
|
31
|
+
return false;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
return !hasGlobalPrivacyControlSignal;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
export type ConsentDecision = "denied" | "granted";
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* NĐ 13/2023 and GDPR both expect a record of *when* and *under what policy* consent
|
|
41
|
+
* was given, not just a yes/no flag — `policyVersion` lets a later policy change
|
|
42
|
+
* invalidate stale consent.
|
|
43
|
+
*/
|
|
44
|
+
export interface ConsentRecord {
|
|
45
|
+
decision: ConsentDecision;
|
|
46
|
+
policyVersion: string;
|
|
47
|
+
timestamp: number;
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* Persistence backend for the visitor's consent decision — mirrors `EventQueueStorage`
|
|
52
|
+
* so a non-browser environment can swap in its own implementation.
|
|
53
|
+
*/
|
|
54
|
+
export interface ConsentStorage {
|
|
55
|
+
clear: () => void;
|
|
56
|
+
load: () => ConsentRecord | undefined;
|
|
57
|
+
save: (record: ConsentRecord) => void;
|
|
58
|
+
}
|