@codefast/tracking 0.5.0-canary.5 → 0.5.0-canary.6

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.
Files changed (276) hide show
  1. package/CHANGELOG.md +467 -0
  2. package/README.md +176 -126
  3. package/dist/adapters/tanstack-start.d.ts +80 -0
  4. package/dist/adapters/tanstack-start.d.ts.map +1 -0
  5. package/dist/adapters/tanstack-start.js +74 -0
  6. package/dist/adapters/tanstack-start.js.map +1 -0
  7. package/dist/client/ad-framework-consent.d.ts +62 -0
  8. package/dist/client/ad-framework-consent.d.ts.map +1 -0
  9. package/dist/client/ad-framework-consent.js +40 -0
  10. package/dist/client/ad-framework-consent.js.map +1 -0
  11. package/dist/client/browser-cookie.d.ts +9 -0
  12. package/dist/client/browser-cookie.d.ts.map +1 -0
  13. package/dist/client/browser-cookie.js +15 -0
  14. package/dist/client/browser-cookie.js.map +1 -0
  15. package/dist/client/consent-runtime.d.ts +53 -0
  16. package/dist/client/consent-runtime.d.ts.map +1 -0
  17. package/dist/client/consent-runtime.js +33 -0
  18. package/dist/client/consent-runtime.js.map +1 -0
  19. package/dist/client/{consent-storage.d.mts → consent-storage.d.ts} +8 -6
  20. package/dist/client/consent-storage.d.ts.map +1 -0
  21. package/dist/client/consent-storage.js +109 -0
  22. package/dist/client/consent-storage.js.map +1 -0
  23. package/dist/client/consent-withdrawal.d.ts +18 -0
  24. package/dist/client/consent-withdrawal.d.ts.map +1 -0
  25. package/dist/client/consent-withdrawal.js +17 -0
  26. package/dist/client/consent-withdrawal.js.map +1 -0
  27. package/dist/client/cookie-anonymous-id.d.ts +41 -0
  28. package/dist/client/cookie-anonymous-id.d.ts.map +1 -0
  29. package/dist/client/cookie-anonymous-id.js +65 -0
  30. package/dist/client/cookie-anonymous-id.js.map +1 -0
  31. package/dist/client/create-client-tracker.d.ts +60 -0
  32. package/dist/client/create-client-tracker.d.ts.map +1 -0
  33. package/dist/client/create-client-tracker.js +91 -0
  34. package/dist/client/create-client-tracker.js.map +1 -0
  35. package/dist/client/gpc.d.ts +10 -0
  36. package/dist/client/gpc.d.ts.map +1 -0
  37. package/dist/client/gpc.js +12 -0
  38. package/dist/client/gpc.js.map +1 -0
  39. package/dist/client/initial-consent-store.d.ts +63 -0
  40. package/dist/client/initial-consent-store.d.ts.map +1 -0
  41. package/dist/client/initial-consent-store.js +138 -0
  42. package/dist/client/initial-consent-store.js.map +1 -0
  43. package/dist/client/is-analytics-allowed.d.ts +26 -0
  44. package/dist/client/is-analytics-allowed.d.ts.map +1 -0
  45. package/dist/client/is-analytics-allowed.js +22 -0
  46. package/dist/client/is-analytics-allowed.js.map +1 -0
  47. package/dist/client/server-persisted-anonymous-id.d.ts +30 -0
  48. package/dist/client/server-persisted-anonymous-id.d.ts.map +1 -0
  49. package/dist/client/server-persisted-anonymous-id.js +72 -0
  50. package/dist/client/server-persisted-anonymous-id.js.map +1 -0
  51. package/dist/core/consent-config.d.ts +24 -0
  52. package/dist/core/consent-config.d.ts.map +1 -0
  53. package/dist/core/consent-config.js +9 -0
  54. package/dist/core/consent-config.js.map +1 -0
  55. package/dist/core/consent-receipt.d.ts +71 -0
  56. package/dist/core/consent-receipt.d.ts.map +1 -0
  57. package/dist/core/consent-receipt.js +39 -0
  58. package/dist/core/consent-receipt.js.map +1 -0
  59. package/dist/core/consent.d.ts +182 -0
  60. package/dist/core/consent.d.ts.map +1 -0
  61. package/dist/core/consent.js +159 -0
  62. package/dist/core/consent.js.map +1 -0
  63. package/dist/core/cookie.d.ts +15 -0
  64. package/dist/core/cookie.d.ts.map +1 -0
  65. package/dist/core/cookie.js +26 -0
  66. package/dist/core/cookie.js.map +1 -0
  67. package/dist/core/destination.d.ts +29 -0
  68. package/dist/core/destination.d.ts.map +1 -0
  69. package/dist/core/destination.js +2 -0
  70. package/dist/core/destination.js.map +1 -0
  71. package/dist/core/event-catalog.d.ts +35 -0
  72. package/dist/core/event-catalog.d.ts.map +1 -0
  73. package/dist/core/event-catalog.js +30 -0
  74. package/dist/core/event-catalog.js.map +1 -0
  75. package/dist/core/event-id.d.ts +7 -0
  76. package/dist/core/event-id.d.ts.map +1 -0
  77. package/dist/core/event-id.js +9 -0
  78. package/dist/core/event-id.js.map +1 -0
  79. package/dist/core/tracked-event.d.ts +15 -0
  80. package/dist/core/tracked-event.d.ts.map +1 -0
  81. package/dist/core/tracked-event.js +2 -0
  82. package/dist/core/tracked-event.js.map +1 -0
  83. package/dist/destinations/ad-consent.d.ts +23 -0
  84. package/dist/destinations/ad-consent.d.ts.map +1 -0
  85. package/dist/destinations/ad-consent.js +12 -0
  86. package/dist/destinations/ad-consent.js.map +1 -0
  87. package/dist/destinations/google-analytics.d.ts +148 -0
  88. package/dist/destinations/google-analytics.d.ts.map +1 -0
  89. package/dist/destinations/google-analytics.js +156 -0
  90. package/dist/destinations/google-analytics.js.map +1 -0
  91. package/dist/destinations/google-consent.d.ts +62 -0
  92. package/dist/destinations/google-consent.d.ts.map +1 -0
  93. package/dist/destinations/google-consent.js +109 -0
  94. package/dist/destinations/google-consent.js.map +1 -0
  95. package/dist/destinations/meta.d.ts +63 -0
  96. package/dist/destinations/meta.d.ts.map +1 -0
  97. package/dist/destinations/meta.js +44 -0
  98. package/dist/destinations/meta.js.map +1 -0
  99. package/dist/destinations/microsoft-uet.d.ts +56 -0
  100. package/dist/destinations/microsoft-uet.d.ts.map +1 -0
  101. package/dist/destinations/microsoft-uet.js +41 -0
  102. package/dist/destinations/microsoft-uet.js.map +1 -0
  103. package/dist/destinations/shared.d.ts +18 -0
  104. package/dist/destinations/shared.d.ts.map +1 -0
  105. package/dist/destinations/shared.js +19 -0
  106. package/dist/destinations/shared.js.map +1 -0
  107. package/dist/destinations/tiktok.d.ts +55 -0
  108. package/dist/destinations/tiktok.d.ts.map +1 -0
  109. package/dist/destinations/tiktok.js +40 -0
  110. package/dist/destinations/tiktok.js.map +1 -0
  111. package/dist/destinations/vercel-analytics.d.ts +25 -0
  112. package/dist/destinations/vercel-analytics.d.ts.map +1 -0
  113. package/dist/destinations/vercel-analytics.js +23 -0
  114. package/dist/destinations/vercel-analytics.js.map +1 -0
  115. package/dist/index.d.ts +64 -0
  116. package/dist/index.d.ts.map +1 -0
  117. package/dist/index.js +41 -0
  118. package/dist/index.js.map +1 -0
  119. package/dist/react/consent-banner.d.ts +155 -0
  120. package/dist/react/consent-banner.d.ts.map +1 -0
  121. package/dist/react/consent-banner.js +171 -0
  122. package/dist/react/consent-banner.js.map +1 -0
  123. package/dist/react/gtag-consent-bootstrap.d.ts +17 -0
  124. package/dist/react/gtag-consent-bootstrap.d.ts.map +1 -0
  125. package/dist/react/gtag-consent-bootstrap.js +22 -0
  126. package/dist/react/gtag-consent-bootstrap.js.map +1 -0
  127. package/dist/react/use-consent.d.ts +42 -0
  128. package/dist/react/use-consent.d.ts.map +1 -0
  129. package/dist/react/use-consent.js +60 -0
  130. package/dist/react/use-consent.js.map +1 -0
  131. package/dist/react/use-google-consent-sync.d.ts +20 -0
  132. package/dist/react/use-google-consent-sync.d.ts.map +1 -0
  133. package/dist/react/use-google-consent-sync.js +22 -0
  134. package/dist/react/use-google-consent-sync.js.map +1 -0
  135. package/dist/react/use-initial-consent.d.ts +11 -0
  136. package/dist/react/use-initial-consent.d.ts.map +1 -0
  137. package/dist/react/use-initial-consent.js +18 -0
  138. package/dist/react/use-initial-consent.js.map +1 -0
  139. package/dist/server/anonymous-id-cookie.d.ts +67 -0
  140. package/dist/server/anonymous-id-cookie.d.ts.map +1 -0
  141. package/dist/server/anonymous-id-cookie.js +71 -0
  142. package/dist/server/anonymous-id-cookie.js.map +1 -0
  143. package/dist/server/consent-receipt-store.d.ts +56 -0
  144. package/dist/server/consent-receipt-store.d.ts.map +1 -0
  145. package/dist/server/consent-receipt-store.js +44 -0
  146. package/dist/server/consent-receipt-store.js.map +1 -0
  147. package/dist/server/consent-receipt.d.ts +41 -0
  148. package/dist/server/consent-receipt.d.ts.map +1 -0
  149. package/dist/server/consent-receipt.js +60 -0
  150. package/dist/server/consent-receipt.js.map +1 -0
  151. package/dist/server/initial-consent.d.ts +26 -0
  152. package/dist/server/initial-consent.d.ts.map +1 -0
  153. package/dist/server/initial-consent.js +31 -0
  154. package/dist/server/initial-consent.js.map +1 -0
  155. package/dist/server/measurement-protocol.d.ts +69 -0
  156. package/dist/server/measurement-protocol.d.ts.map +1 -0
  157. package/dist/server/measurement-protocol.js +61 -0
  158. package/dist/server/measurement-protocol.js.map +1 -0
  159. package/dist/server/region.d.ts +27 -0
  160. package/dist/server/region.d.ts.map +1 -0
  161. package/dist/server/region.js +69 -0
  162. package/dist/server/region.js.map +1 -0
  163. package/dist/server/user-deletion.d.ts +64 -0
  164. package/dist/server/user-deletion.d.ts.map +1 -0
  165. package/dist/server/user-deletion.js +54 -0
  166. package/dist/server/user-deletion.js.map +1 -0
  167. package/dist/tooling/import-protection.d.ts +19 -0
  168. package/dist/tooling/import-protection.d.ts.map +1 -0
  169. package/dist/tooling/import-protection.js +23 -0
  170. package/dist/tooling/import-protection.js.map +1 -0
  171. package/package.json +201 -107
  172. package/src/adapters/tanstack-start.ts +135 -0
  173. package/src/client/ad-framework-consent.ts +86 -0
  174. package/src/client/browser-cookie.ts +16 -0
  175. package/src/client/consent-runtime.ts +80 -0
  176. package/src/client/consent-storage.ts +31 -1
  177. package/src/client/consent-withdrawal.ts +32 -0
  178. package/src/client/cookie-anonymous-id.ts +112 -0
  179. package/src/client/create-client-tracker.ts +128 -86
  180. package/src/client/gpc.ts +4 -2
  181. package/src/client/initial-consent-store.ts +218 -0
  182. package/src/client/is-analytics-allowed.ts +43 -0
  183. package/src/client/server-persisted-anonymous-id.ts +102 -0
  184. package/src/core/consent-config.ts +27 -0
  185. package/src/core/consent-receipt.ts +115 -0
  186. package/src/core/consent.ts +164 -10
  187. package/src/core/cookie.ts +29 -0
  188. package/src/core/destination.ts +17 -8
  189. package/src/core/event-catalog.ts +29 -15
  190. package/src/core/event-id.ts +1 -2
  191. package/src/core/tracked-event.ts +4 -4
  192. package/src/destinations/ad-consent.ts +29 -0
  193. package/src/destinations/google-analytics.ts +196 -133
  194. package/src/destinations/google-consent.ts +164 -0
  195. package/src/destinations/meta.ts +96 -0
  196. package/src/destinations/microsoft-uet.ts +86 -0
  197. package/src/destinations/shared.ts +45 -0
  198. package/src/destinations/tiktok.ts +85 -0
  199. package/src/destinations/vercel-analytics.ts +23 -24
  200. package/src/index.ts +165 -8
  201. package/src/react/consent-banner.tsx +40 -14
  202. package/src/react/gtag-consent-bootstrap.tsx +48 -0
  203. package/src/react/use-consent.ts +53 -45
  204. package/src/react/use-google-consent-sync.ts +38 -0
  205. package/src/react/use-initial-consent.ts +22 -0
  206. package/src/server/anonymous-id-cookie.ts +103 -0
  207. package/src/server/consent-receipt-store.ts +79 -0
  208. package/src/server/consent-receipt.ts +89 -0
  209. package/src/server/initial-consent.ts +46 -0
  210. package/src/server/measurement-protocol.ts +114 -0
  211. package/src/server/region.ts +22 -15
  212. package/src/server/user-deletion.ts +93 -0
  213. package/src/tooling/import-protection.ts +22 -0
  214. package/dist/client/consent-storage.mjs +0 -63
  215. package/dist/client/create-client-tracker.d.mts +0 -37
  216. package/dist/client/create-client-tracker.mjs +0 -66
  217. package/dist/client/gpc.d.mts +0 -10
  218. package/dist/client/gpc.mjs +0 -12
  219. package/dist/client/index.d.mts +0 -8
  220. package/dist/client/index.mjs +0 -8
  221. package/dist/client/lifecycle.d.mts +0 -23
  222. package/dist/client/lifecycle.mjs +0 -30
  223. package/dist/client/local-storage.d.mts +0 -13
  224. package/dist/client/local-storage.mjs +0 -31
  225. package/dist/client/queue.d.mts +0 -49
  226. package/dist/client/queue.mjs +0 -71
  227. package/dist/client/router.d.mts +0 -30
  228. package/dist/client/router.mjs +0 -17
  229. package/dist/core/consent.d.mts +0 -89
  230. package/dist/core/consent.mjs +0 -57
  231. package/dist/core/destination.d.mts +0 -23
  232. package/dist/core/destination.mjs +0 -1
  233. package/dist/core/event-catalog.d.mts +0 -36
  234. package/dist/core/event-catalog.mjs +0 -12
  235. package/dist/core/event-id.d.mts +0 -10
  236. package/dist/core/event-id.mjs +0 -12
  237. package/dist/core/index.d.mts +0 -6
  238. package/dist/core/index.mjs +0 -4
  239. package/dist/core/tracked-event.d.mts +0 -17
  240. package/dist/core/tracked-event.mjs +0 -1
  241. package/dist/destinations/ga4-measurement-protocol.d.mts +0 -54
  242. package/dist/destinations/ga4-measurement-protocol.mjs +0 -89
  243. package/dist/destinations/google-analytics.d.mts +0 -98
  244. package/dist/destinations/google-analytics.mjs +0 -126
  245. package/dist/destinations/http-destination.d.mts +0 -20
  246. package/dist/destinations/http-destination.mjs +0 -25
  247. package/dist/destinations/index.d.mts +0 -5
  248. package/dist/destinations/index.mjs +0 -5
  249. package/dist/destinations/vercel-analytics.d.mts +0 -13
  250. package/dist/destinations/vercel-analytics.mjs +0 -30
  251. package/dist/index.d.mts +0 -6
  252. package/dist/index.mjs +0 -4
  253. package/dist/react/consent-banner.d.mts +0 -163
  254. package/dist/react/consent-banner.mjs +0 -209
  255. package/dist/react/index.d.mts +0 -3
  256. package/dist/react/index.mjs +0 -3
  257. package/dist/react/use-consent.d.mts +0 -49
  258. package/dist/react/use-consent.mjs +0 -54
  259. package/dist/server/create-server-tracker.d.mts +0 -42
  260. package/dist/server/create-server-tracker.mjs +0 -67
  261. package/dist/server/index.d.mts +0 -3
  262. package/dist/server/index.mjs +0 -3
  263. package/dist/server/region.d.mts +0 -20
  264. package/dist/server/region.mjs +0 -56
  265. package/src/client/index.ts +0 -17
  266. package/src/client/lifecycle.ts +0 -50
  267. package/src/client/local-storage.ts +0 -44
  268. package/src/client/queue.ts +0 -117
  269. package/src/client/router.ts +0 -37
  270. package/src/core/index.ts +0 -24
  271. package/src/destinations/ga4-measurement-protocol.ts +0 -166
  272. package/src/destinations/http-destination.ts +0 -33
  273. package/src/destinations/index.ts +0 -20
  274. package/src/react/index.ts +0 -29
  275. package/src/server/create-server-tracker.ts +0 -128
  276. package/src/server/index.ts +0 -4
@@ -1,49 +0,0 @@
1
- import { TrackedEvent } from "../core/tracked-event.mjs";
2
- import { Destination } from "../core/destination.mjs";
3
-
4
- //#region src/client/queue.d.ts
5
- /**
6
- * Persistence backend for the offline queue — a thin wrapper so tests and non-browser
7
- * environments can swap in an in-memory implementation instead of real `localStorage`.
8
- *
9
- * @since 0.5.0-canary.4
10
- */
11
- interface EventQueueStorage {
12
- load: () => Array<TrackedEvent>;
13
- save: (events: Array<TrackedEvent>) => void;
14
- }
15
- /**
16
- * @since 0.5.0-canary.4
17
- */
18
- interface EventQueueOptions {
19
- destinations: Array<Destination>;
20
- flushBatchSize?: number | undefined;
21
- maxQueueSize?: number | undefined;
22
- maxRetries?: number | undefined;
23
- storage: EventQueueStorage;
24
- }
25
- /**
26
- * Client-side batching/offline queue: persists across reloads, caps its size
27
- * (drop-oldest), and retries a failed batch up to `maxRetries` times.
28
- *
29
- * @since 0.5.0-canary.4
30
- */
31
- declare class EventQueue {
32
- private readonly destinations;
33
- private readonly flushBatchSize;
34
- private readonly maxQueueSize;
35
- private readonly maxRetries;
36
- private pending;
37
- private readonly storage;
38
- constructor(options: EventQueueOptions);
39
- get size(): number;
40
- /** Drops every pending event without sending it — used on consent revoke. */
41
- clear(): void;
42
- /** Empties the queue synchronously for `navigator.sendBeacon`, which can't be awaited. */
43
- drain(): Array<TrackedEvent>;
44
- enqueue(event: TrackedEvent): void;
45
- flush(): Promise<void>;
46
- private persist;
47
- }
48
- //#endregion
49
- export { EventQueue, EventQueueOptions, EventQueueStorage };
@@ -1,71 +0,0 @@
1
- //#region src/client/queue.ts
2
- /**
3
- * Client-side batching/offline queue: persists across reloads, caps its size
4
- * (drop-oldest), and retries a failed batch up to `maxRetries` times.
5
- *
6
- * @since 0.5.0-canary.4
7
- */
8
- var EventQueue = class {
9
- destinations;
10
- flushBatchSize;
11
- maxQueueSize;
12
- maxRetries;
13
- pending;
14
- storage;
15
- constructor(options) {
16
- this.destinations = options.destinations;
17
- this.storage = options.storage;
18
- this.maxQueueSize = options.maxQueueSize ?? 500;
19
- this.maxRetries = options.maxRetries ?? 3;
20
- this.flushBatchSize = options.flushBatchSize ?? 20;
21
- this.pending = this.storage.load().map((event) => ({
22
- attempts: 0,
23
- event
24
- }));
25
- }
26
- get size() {
27
- return this.pending.length;
28
- }
29
- /** Drops every pending event without sending it — used on consent revoke. */
30
- clear() {
31
- this.pending = [];
32
- this.persist();
33
- }
34
- /** Empties the queue synchronously for `navigator.sendBeacon`, which can't be awaited. */
35
- drain() {
36
- const events = this.pending.map((queued) => queued.event);
37
- this.pending = [];
38
- this.persist();
39
- return events;
40
- }
41
- enqueue(event) {
42
- this.pending.push({
43
- attempts: 0,
44
- event
45
- });
46
- if (this.pending.length > this.maxQueueSize) this.pending = this.pending.slice(this.pending.length - this.maxQueueSize);
47
- this.persist();
48
- if (this.pending.length >= this.flushBatchSize) this.flush();
49
- }
50
- async flush() {
51
- if (this.pending.length === 0) return;
52
- const batch = this.pending;
53
- this.pending = [];
54
- const results = await Promise.allSettled(batch.map(async (queued) => {
55
- await Promise.all(this.destinations.map(async (destination) => destination.send(queued.event)));
56
- }));
57
- for (const [index, result] of results.entries()) {
58
- const queued = batch[index];
59
- if (result.status === "rejected" && queued && queued.attempts < this.maxRetries) this.pending.push({
60
- attempts: queued.attempts + 1,
61
- event: queued.event
62
- });
63
- }
64
- this.persist();
65
- }
66
- persist() {
67
- this.storage.save(this.pending.map((queued) => queued.event));
68
- }
69
- };
70
- //#endregion
71
- export { EventQueue };
@@ -1,30 +0,0 @@
1
- import { EventCatalog } from "../core/event-catalog.mjs";
2
- import { ClientTracker } from "./create-client-tracker.mjs";
3
-
4
- //#region src/client/router.d.ts
5
- interface ResolvedNavigation {
6
- toLocation: {
7
- href: string;
8
- pathname: string;
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
- * @since 0.5.0-canary.4
16
- */
17
- interface RouterLike {
18
- subscribe: (eventType: "onResolved", fn: (event: ResolvedNavigation) => void) => () => void;
19
- }
20
- /**
21
- * `onResolved` (not `popstate`) is what fires on SPA navigation in TanStack Router;
22
- * `popstate` only fires for browser back/forward. Page views are low-frequency, so this
23
- * flushes right away instead of waiting on the batch queue's interval/size threshold —
24
- * a slow navigation shouldn't leave a pageview stranded if the tab closes right after.
25
- *
26
- * @since 0.5.0-canary.4
27
- */
28
- declare function attachRouterPageTracking<Catalog extends EventCatalog>(tracker: Pick<ClientTracker<Catalog>, "flush" | "page">, router: RouterLike): () => void;
29
- //#endregion
30
- export { RouterLike, attachRouterPageTracking };
@@ -1,17 +0,0 @@
1
- //#region src/client/router.ts
2
- /**
3
- * `onResolved` (not `popstate`) is what fires on SPA navigation in TanStack Router;
4
- * `popstate` only fires for browser back/forward. Page views are low-frequency, so this
5
- * flushes right away instead of waiting on the batch queue's interval/size threshold —
6
- * a slow navigation shouldn't leave a pageview stranded if the tab closes right after.
7
- *
8
- * @since 0.5.0-canary.4
9
- */
10
- function attachRouterPageTracking(tracker, router) {
11
- return router.subscribe("onResolved", (event) => {
12
- tracker.page(event.toLocation.pathname, { href: event.toLocation.href });
13
- tracker.flush();
14
- });
15
- }
16
- //#endregion
17
- export { attachRouterPageTracking };
@@ -1,89 +0,0 @@
1
- //#region src/core/consent.d.ts
2
- /**
3
- * @since 0.5.0-canary.4
4
- */
5
- type ConsentRegion = "eu" | "other" | "us" | "vn";
6
- /**
7
- * @since 0.5.0-canary.4
8
- */
9
- type ConsentMode = "opt-in" | "opt-out";
10
- /**
11
- * GDPR (EU) and Nghị định 13/2023 (VN) require explicit opt-in before any non-essential
12
- * tracking; CCPA/CPRA (US) defaults to opt-out instead. There is no single global default
13
- * that satisfies both, so the mode is resolved per region.
14
- *
15
- * @since 0.5.0-canary.4
16
- */
17
- declare function resolveConsentMode(region: ConsentRegion): ConsentMode;
18
- /**
19
- * Consent purposes, mirroring Google Consent Mode v2's split: `analytics` gates
20
- * measurement (`analytics_storage`), `ads` gates advertising storage and data sharing
21
- * (`ad_storage`/`ad_user_data`/`ad_personalization`).
22
- *
23
- * @since 0.5.0-canary.4
24
- */
25
- type ConsentCategory = "ads" | "analytics";
26
- /**
27
- * @since 0.5.0-canary.4
28
- */
29
- declare const CONSENT_CATEGORIES: ReadonlyArray<ConsentCategory>;
30
- /**
31
- * Per-category consent — GDPR consent must be granular per purpose, so a single
32
- * granted/denied flag can't represent it. `true` means the visitor granted that purpose.
33
- *
34
- * @since 0.5.0-canary.4
35
- */
36
- type ConsentDecision = Record<ConsentCategory, boolean>;
37
- /**
38
- * A decision granting exactly the given categories and denying every other one.
39
- *
40
- * @since 0.5.0-canary.4
41
- */
42
- declare function createConsentDecision(grantedCategories: ReadonlyArray<ConsentCategory>): ConsentDecision;
43
- /**
44
- * Guards stored JSON — the record is tamperable, so every category must be an explicit boolean.
45
- *
46
- * @since 0.5.0-canary.4
47
- */
48
- declare function isConsentDecision(value: unknown): value is ConsentDecision;
49
- /**
50
- * The effective consent before the visitor decides: opt-in regions start all-denied,
51
- * opt-out regions grant the categories the app asks for.
52
- *
53
- * @remarks
54
- * A Global Privacy Control signal is a "do not sell or share" opt-out (CCPA/CPRA), so it
55
- * forces `ads` denied — it does not withdraw first-party analytics measurement.
56
- *
57
- * @since 0.5.0-canary.4
58
- */
59
- declare function resolveDefaultConsent(mode: ConsentMode, requestedCategories: ReadonlyArray<ConsentCategory>, hasGlobalPrivacyControlSignal: boolean): ConsentDecision;
60
- /**
61
- * NĐ 13/2023 and GDPR both expect a record of *when* and *under what policy* consent
62
- * was given, not just per-category flags — `policyVersion` lets a later policy change
63
- * invalidate stale consent.
64
- *
65
- * @since 0.5.0-canary.4
66
- */
67
- interface ConsentRecord {
68
- decision: ConsentDecision;
69
- policyVersion: string;
70
- timestamp: number;
71
- }
72
- /**
73
- * Persistence backend for the visitor's consent decision — swap in your own
74
- * implementation for non-browser environments or a different persistence layer.
75
- *
76
- * @since 0.5.0-canary.4
77
- */
78
- interface ConsentStorage {
79
- clear: () => void;
80
- load: () => ConsentRecord | undefined;
81
- save: (record: ConsentRecord) => void;
82
- /**
83
- * Notify on any change to the stored record, including writes from other tabs — this
84
- * is what drives `useConsent`'s external-store subscription. Returns an unsubscribe.
85
- */
86
- subscribe: (listener: () => void) => () => void;
87
- }
88
- //#endregion
89
- export { CONSENT_CATEGORIES, ConsentCategory, ConsentDecision, ConsentMode, ConsentRecord, ConsentRegion, ConsentStorage, createConsentDecision, isConsentDecision, resolveConsentMode, resolveDefaultConsent };
@@ -1,57 +0,0 @@
1
- //#region src/core/consent.ts
2
- /**
3
- * GDPR (EU) and Nghị định 13/2023 (VN) require explicit opt-in before any non-essential
4
- * tracking; CCPA/CPRA (US) defaults to opt-out instead. There is no single global default
5
- * that satisfies both, so the mode is resolved per region.
6
- *
7
- * @since 0.5.0-canary.4
8
- */
9
- function resolveConsentMode(region) {
10
- switch (region) {
11
- case "eu":
12
- case "vn": return "opt-in";
13
- case "other":
14
- case "us": return "opt-out";
15
- }
16
- }
17
- /**
18
- * @since 0.5.0-canary.4
19
- */
20
- const CONSENT_CATEGORIES = ["ads", "analytics"];
21
- /**
22
- * A decision granting exactly the given categories and denying every other one.
23
- *
24
- * @since 0.5.0-canary.4
25
- */
26
- function createConsentDecision(grantedCategories) {
27
- return {
28
- ads: grantedCategories.includes("ads"),
29
- analytics: grantedCategories.includes("analytics")
30
- };
31
- }
32
- /**
33
- * Guards stored JSON — the record is tamperable, so every category must be an explicit boolean.
34
- *
35
- * @since 0.5.0-canary.4
36
- */
37
- function isConsentDecision(value) {
38
- return typeof value === "object" && value !== null && CONSENT_CATEGORIES.every((category) => typeof value[category] === "boolean");
39
- }
40
- /**
41
- * The effective consent before the visitor decides: opt-in regions start all-denied,
42
- * opt-out regions grant the categories the app asks for.
43
- *
44
- * @remarks
45
- * A Global Privacy Control signal is a "do not sell or share" opt-out (CCPA/CPRA), so it
46
- * forces `ads` denied — it does not withdraw first-party analytics measurement.
47
- *
48
- * @since 0.5.0-canary.4
49
- */
50
- function resolveDefaultConsent(mode, requestedCategories, hasGlobalPrivacyControlSignal) {
51
- if (mode === "opt-in") return createConsentDecision([]);
52
- const decision = createConsentDecision(requestedCategories);
53
- if (hasGlobalPrivacyControlSignal) decision.ads = false;
54
- return decision;
55
- }
56
- //#endregion
57
- export { CONSENT_CATEGORIES, createConsentDecision, isConsentDecision, resolveConsentMode, resolveDefaultConsent };
@@ -1,23 +0,0 @@
1
- import { TrackedEvent } from "./tracked-event.mjs";
2
-
3
- //#region src/core/destination.d.ts
4
- /**
5
- * Fan-out target for tracked events (PostHog, GA4, a self-hosted store, ...).
6
- * Trackers depend only on this interface, never on a specific provider SDK.
7
- *
8
- * @since 0.5.0-canary.4
9
- */
10
- interface Destination {
11
- /**
12
- * "immediate" for SDK-backed destinations that own their transport (gtag.js, Vercel's
13
- * in-page queue) — the client tracker calls `send` at track time and never queues,
14
- * persists, or retries for them.
15
- *
16
- * @defaultValue "queued"
17
- */
18
- delivery?: "immediate" | "queued";
19
- name: string;
20
- send: (event: TrackedEvent) => Promise<void> | void;
21
- }
22
- //#endregion
23
- export { Destination };
@@ -1 +0,0 @@
1
- export {};
@@ -1,36 +0,0 @@
1
- import { z } from "zod";
2
-
3
- //#region src/core/event-catalog.d.ts
4
- /**
5
- * One event's Zod schema plus which side of the app is allowed to fire it.
6
- *
7
- * @since 0.5.0-canary.4
8
- */
9
- interface EventDefinition<Schema extends z.ZodType = z.ZodType> {
10
- owner: "client" | "server";
11
- schema: Schema;
12
- }
13
- /**
14
- * An app-defined map of event name to its definition. `@codefast/tracking` ships no
15
- * events of its own — every consuming app builds and passes in its own catalog.
16
- *
17
- * @since 0.5.0-canary.4
18
- */
19
- type EventCatalog = Record<string, EventDefinition>;
20
- /**
21
- * Filters a catalog down to the events a given owner may fire. Client and server
22
- * trackers are built from this, so calling a server-owned event from client code
23
- * (or vice versa) is a compile-time error, not a runtime surprise.
24
- *
25
- * @since 0.5.0-canary.4
26
- */
27
- type EventsOf<Catalog extends EventCatalog, Owner extends "client" | "server"> = { [Key in keyof Catalog as Catalog[Key]["owner"] extends Owner ? Key : never]: Catalog[Key] };
28
- /**
29
- * Identity helper for declaring a catalog with inference — nicer call-site than
30
- * `satisfies EventCatalog` when the catalog is assembled across multiple files.
31
- *
32
- * @since 0.5.0-canary.4
33
- */
34
- declare function defineEventCatalog<Catalog extends EventCatalog>(catalog: Catalog): Catalog;
35
- //#endregion
36
- export { EventCatalog, EventDefinition, EventsOf, defineEventCatalog };
@@ -1,12 +0,0 @@
1
- //#region src/core/event-catalog.ts
2
- /**
3
- * Identity helper for declaring a catalog with inference — nicer call-site than
4
- * `satisfies EventCatalog` when the catalog is assembled across multiple files.
5
- *
6
- * @since 0.5.0-canary.4
7
- */
8
- function defineEventCatalog(catalog) {
9
- return catalog;
10
- }
11
- //#endregion
12
- export { defineEventCatalog };
@@ -1,10 +0,0 @@
1
- //#region src/core/event-id.d.ts
2
- /**
3
- * Client-owned events use this at enqueue time; server-owned events derive an ID
4
- * from the request instead so retries of the same request don't double-count.
5
- *
6
- * @since 0.5.0-canary.4
7
- */
8
- declare function generateEventId(): string;
9
- //#endregion
10
- export { generateEventId };
@@ -1,12 +0,0 @@
1
- //#region src/core/event-id.ts
2
- /**
3
- * Client-owned events use this at enqueue time; server-owned events derive an ID
4
- * from the request instead so retries of the same request don't double-count.
5
- *
6
- * @since 0.5.0-canary.4
7
- */
8
- function generateEventId() {
9
- return crypto.randomUUID();
10
- }
11
- //#endregion
12
- export { generateEventId };
@@ -1,6 +0,0 @@
1
- import { CONSENT_CATEGORIES, ConsentCategory, ConsentDecision, ConsentMode, ConsentRecord, ConsentRegion, ConsentStorage, createConsentDecision, isConsentDecision, resolveConsentMode, resolveDefaultConsent } from "./consent.mjs";
2
- import { TrackedEvent } from "./tracked-event.mjs";
3
- import { Destination } from "./destination.mjs";
4
- import { EventCatalog, EventDefinition, EventsOf, defineEventCatalog } from "./event-catalog.mjs";
5
- import { generateEventId } from "./event-id.mjs";
6
- export { CONSENT_CATEGORIES, type ConsentCategory, type ConsentDecision, type ConsentMode, type ConsentRecord, type ConsentRegion, type ConsentStorage, type Destination, type EventCatalog, type EventDefinition, type EventsOf, type TrackedEvent, createConsentDecision, defineEventCatalog, generateEventId, isConsentDecision, resolveConsentMode, resolveDefaultConsent };
@@ -1,4 +0,0 @@
1
- import { CONSENT_CATEGORIES, createConsentDecision, isConsentDecision, resolveConsentMode, resolveDefaultConsent } from "./consent.mjs";
2
- import { defineEventCatalog } from "./event-catalog.mjs";
3
- import { generateEventId } from "./event-id.mjs";
4
- export { CONSENT_CATEGORIES, createConsentDecision, defineEventCatalog, generateEventId, isConsentDecision, resolveConsentMode, resolveDefaultConsent };
@@ -1,17 +0,0 @@
1
- //#region src/core/tracked-event.d.ts
2
- /**
3
- * Envelope every tracker (client/server) builds before handing an event to a destination.
4
- *
5
- * @since 0.5.0-canary.4
6
- */
7
- interface TrackedEvent {
8
- anonymousId: string;
9
- eventId: string;
10
- name: string;
11
- owner: "client" | "server";
12
- props: Record<string, unknown>;
13
- timestamp: number;
14
- userId?: string | undefined;
15
- }
16
- //#endregion
17
- export { TrackedEvent };
@@ -1 +0,0 @@
1
- export {};
@@ -1,54 +0,0 @@
1
- import { Destination } from "../core/destination.mjs";
2
-
3
- //#region src/destinations/ga4-measurement-protocol.d.ts
4
- /**
5
- * Reads gtag.js's own client ID from a request Cookie header — `_ga=GA1.1.123.456` →
6
- * `123.456`. This (not an app-generated anonymous ID) is the value GA4 joins hits on, so
7
- * pass it as `clientId` to make server events land on the same user as the visitor's
8
- * client-side hits.
9
- *
10
- * @since 0.5.0-canary.4
11
- */
12
- declare function extractGa4ClientId(cookieHeader: string | undefined): string | undefined;
13
- /**
14
- * Reads the current GA4 session ID from the per-stream `_ga_<suffix>` cookie
15
- * (`G-ABC123` → `_ga_ABC123`) — handles both the dot-delimited `GS1` and the
16
- * `$`-delimited `GS2` value formats.
17
- *
18
- * @since 0.5.0-canary.4
19
- */
20
- declare function extractGa4SessionId(cookieHeader: string | undefined, measurementId: string): string | undefined;
21
- /**
22
- * @since 0.5.0-canary.4
23
- */
24
- interface Ga4MeasurementProtocolDestinationOptions {
25
- apiSecret: string;
26
- /**
27
- * gtag.js's client ID for this visitor (see `extractGa4ClientId`). Without it the
28
- * event falls back to the tracker's anonymous ID, which GA4 treats as a *different
29
- * user* than the visitor's client-side hits — pass it whenever the request carries a
30
- * `_ga` cookie.
31
- */
32
- clientId?: string | undefined;
33
- /** Routes to GA4's `/debug/mp/collect` validation endpoint — hits are validated but never recorded. */
34
- debug?: boolean;
35
- measurementId: string;
36
- name?: string;
37
- /**
38
- * Current GA4 session for this visitor (see `extractGa4SessionId`). Without a
39
- * `session_id`, GA4 accepts the event but leaves it out of session-scoped and realtime
40
- * reporting.
41
- */
42
- sessionId?: string | undefined;
43
- }
44
- /**
45
- * Server-side GA4 via the Measurement Protocol — for server-owned events (checkout,
46
- * signup) that must land in GA4 without depending on client-side gtag.js. MP is designed
47
- * to *augment* gtag.js data, so correlation hinges on echoing gtag's own identifiers:
48
- * `clientId` from the `_ga` cookie and `sessionId` from the `_ga_<stream>` cookie.
49
- *
50
- * @since 0.5.0-canary.4
51
- */
52
- declare function createGa4MeasurementProtocolDestination(options: Ga4MeasurementProtocolDestinationOptions): Destination;
53
- //#endregion
54
- export { Ga4MeasurementProtocolDestinationOptions, createGa4MeasurementProtocolDestination, extractGa4ClientId, extractGa4SessionId };
@@ -1,89 +0,0 @@
1
- //#region src/destinations/ga4-measurement-protocol.ts
2
- /**
3
- * Measurement Protocol event params must be flat string/number/boolean — stringify
4
- * anything else instead of letting GA4 silently drop it.
5
- */
6
- function toMeasurementProtocolParams(props) {
7
- const result = {};
8
- for (const [key, value] of Object.entries(props)) if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") result[key] = value;
9
- else if (value !== void 0 && value !== null) result[key] = JSON.stringify(value);
10
- return result;
11
- }
12
- function readCookie(cookieHeader, cookieName) {
13
- if (!cookieHeader) return;
14
- for (const part of cookieHeader.split(";")) {
15
- const separatorIndex = part.indexOf("=");
16
- if (separatorIndex !== -1 && part.slice(0, separatorIndex).trim() === cookieName) return part.slice(separatorIndex + 1).trim();
17
- }
18
- }
19
- /**
20
- * Reads gtag.js's own client ID from a request Cookie header — `_ga=GA1.1.123.456` →
21
- * `123.456`. This (not an app-generated anonymous ID) is the value GA4 joins hits on, so
22
- * pass it as `clientId` to make server events land on the same user as the visitor's
23
- * client-side hits.
24
- *
25
- * @since 0.5.0-canary.4
26
- */
27
- function extractGa4ClientId(cookieHeader) {
28
- const value = readCookie(cookieHeader, "_ga");
29
- if (!value) return;
30
- const segments = value.split(".");
31
- return segments.length >= 4 ? segments.slice(-2).join(".") : void 0;
32
- }
33
- /**
34
- * Reads the current GA4 session ID from the per-stream `_ga_<suffix>` cookie
35
- * (`G-ABC123` → `_ga_ABC123`) — handles both the dot-delimited `GS1` and the
36
- * `$`-delimited `GS2` value formats.
37
- *
38
- * @since 0.5.0-canary.4
39
- */
40
- function extractGa4SessionId(cookieHeader, measurementId) {
41
- const value = readCookie(cookieHeader, `_ga_${measurementId.replace(/^G-/, "")}`);
42
- if (!value) return;
43
- return /^GS\d+\.\d+\.s?(\d+)/.exec(value)?.[1];
44
- }
45
- /**
46
- * Server-side GA4 via the Measurement Protocol — for server-owned events (checkout,
47
- * signup) that must land in GA4 without depending on client-side gtag.js. MP is designed
48
- * to *augment* gtag.js data, so correlation hinges on echoing gtag's own identifiers:
49
- * `clientId` from the `_ga` cookie and `sessionId` from the `_ga_<stream>` cookie.
50
- *
51
- * @since 0.5.0-canary.4
52
- */
53
- function createGa4MeasurementProtocolDestination(options) {
54
- const name = options.name ?? "ga4-measurement-protocol";
55
- const endpoint = `${options.debug ? "https://www.google-analytics.com/debug/mp/collect" : "https://www.google-analytics.com/mp/collect"}?measurement_id=${encodeURIComponent(options.measurementId)}&api_secret=${encodeURIComponent(options.apiSecret)}`;
56
- return {
57
- name,
58
- async send(event) {
59
- if (event.name === "$alias") return;
60
- const eventName = event.name === "$group" ? "join_group" : event.name;
61
- const params = toMeasurementProtocolParams(event.name === "$group" ? renameGroupIdProp(event.props) : event.props);
62
- if (options.sessionId !== void 0 && params.session_id === void 0) params.session_id = options.sessionId;
63
- params.engagement_time_msec ??= 100;
64
- const response = await fetch(endpoint, {
65
- body: JSON.stringify({
66
- client_id: options.clientId ?? event.anonymousId,
67
- events: [{
68
- name: eventName,
69
- params
70
- }],
71
- timestamp_micros: event.timestamp * 1e3,
72
- ...event.userId === void 0 ? {} : { user_id: event.userId }
73
- }),
74
- headers: { "content-type": "application/json" },
75
- method: "POST"
76
- });
77
- if (!response.ok) throw new Error(`"${name}" destination responded with ${String(response.status)}`);
78
- }
79
- };
80
- }
81
- function renameGroupIdProp(props) {
82
- const { groupId, ...traits } = props;
83
- return {
84
- group_id: groupId,
85
- ...traits
86
- };
87
- }
88
- //#endregion
89
- export { createGa4MeasurementProtocolDestination, extractGa4ClientId, extractGa4SessionId };