@codefast/tracking 0.5.0-canary.4 → 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 (277) hide show
  1. package/CHANGELOG.md +473 -0
  2. package/README.md +177 -95
  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 +202 -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/css/consent.css +119 -0
  193. package/src/destinations/ad-consent.ts +29 -0
  194. package/src/destinations/google-analytics.ts +196 -133
  195. package/src/destinations/google-consent.ts +164 -0
  196. package/src/destinations/meta.ts +96 -0
  197. package/src/destinations/microsoft-uet.ts +86 -0
  198. package/src/destinations/shared.ts +45 -0
  199. package/src/destinations/tiktok.ts +85 -0
  200. package/src/destinations/vercel-analytics.ts +23 -24
  201. package/src/index.ts +165 -8
  202. package/src/react/consent-banner.tsx +308 -111
  203. package/src/react/gtag-consent-bootstrap.tsx +48 -0
  204. package/src/react/use-consent.ts +53 -45
  205. package/src/react/use-google-consent-sync.ts +38 -0
  206. package/src/react/use-initial-consent.ts +22 -0
  207. package/src/server/anonymous-id-cookie.ts +103 -0
  208. package/src/server/consent-receipt-store.ts +79 -0
  209. package/src/server/consent-receipt.ts +89 -0
  210. package/src/server/initial-consent.ts +46 -0
  211. package/src/server/measurement-protocol.ts +114 -0
  212. package/src/server/region.ts +22 -15
  213. package/src/server/user-deletion.ts +93 -0
  214. package/src/tooling/import-protection.ts +22 -0
  215. package/dist/client/consent-storage.mjs +0 -63
  216. package/dist/client/create-client-tracker.d.mts +0 -37
  217. package/dist/client/create-client-tracker.mjs +0 -66
  218. package/dist/client/gpc.d.mts +0 -10
  219. package/dist/client/gpc.mjs +0 -12
  220. package/dist/client/index.d.mts +0 -8
  221. package/dist/client/index.mjs +0 -8
  222. package/dist/client/lifecycle.d.mts +0 -23
  223. package/dist/client/lifecycle.mjs +0 -30
  224. package/dist/client/local-storage.d.mts +0 -13
  225. package/dist/client/local-storage.mjs +0 -31
  226. package/dist/client/queue.d.mts +0 -49
  227. package/dist/client/queue.mjs +0 -71
  228. package/dist/client/router.d.mts +0 -30
  229. package/dist/client/router.mjs +0 -17
  230. package/dist/core/consent.d.mts +0 -89
  231. package/dist/core/consent.mjs +0 -57
  232. package/dist/core/destination.d.mts +0 -23
  233. package/dist/core/destination.mjs +0 -1
  234. package/dist/core/event-catalog.d.mts +0 -36
  235. package/dist/core/event-catalog.mjs +0 -12
  236. package/dist/core/event-id.d.mts +0 -10
  237. package/dist/core/event-id.mjs +0 -12
  238. package/dist/core/index.d.mts +0 -6
  239. package/dist/core/index.mjs +0 -4
  240. package/dist/core/tracked-event.d.mts +0 -17
  241. package/dist/core/tracked-event.mjs +0 -1
  242. package/dist/destinations/ga4-measurement-protocol.d.mts +0 -54
  243. package/dist/destinations/ga4-measurement-protocol.mjs +0 -89
  244. package/dist/destinations/google-analytics.d.mts +0 -98
  245. package/dist/destinations/google-analytics.mjs +0 -126
  246. package/dist/destinations/http-destination.d.mts +0 -20
  247. package/dist/destinations/http-destination.mjs +0 -25
  248. package/dist/destinations/index.d.mts +0 -5
  249. package/dist/destinations/index.mjs +0 -5
  250. package/dist/destinations/vercel-analytics.d.mts +0 -13
  251. package/dist/destinations/vercel-analytics.mjs +0 -30
  252. package/dist/index.d.mts +0 -6
  253. package/dist/index.mjs +0 -4
  254. package/dist/react/consent-banner.d.mts +0 -75
  255. package/dist/react/consent-banner.mjs +0 -114
  256. package/dist/react/index.d.mts +0 -3
  257. package/dist/react/index.mjs +0 -3
  258. package/dist/react/use-consent.d.mts +0 -49
  259. package/dist/react/use-consent.mjs +0 -54
  260. package/dist/server/create-server-tracker.d.mts +0 -42
  261. package/dist/server/create-server-tracker.mjs +0 -67
  262. package/dist/server/index.d.mts +0 -3
  263. package/dist/server/index.mjs +0 -3
  264. package/dist/server/region.d.mts +0 -20
  265. package/dist/server/region.mjs +0 -56
  266. package/src/client/index.ts +0 -17
  267. package/src/client/lifecycle.ts +0 -50
  268. package/src/client/local-storage.ts +0 -44
  269. package/src/client/queue.ts +0 -117
  270. package/src/client/router.ts +0 -37
  271. package/src/core/index.ts +0 -24
  272. package/src/destinations/ga4-measurement-protocol.ts +0 -166
  273. package/src/destinations/http-destination.ts +0 -33
  274. package/src/destinations/index.ts +0 -20
  275. package/src/react/index.ts +0 -5
  276. package/src/server/create-server-tracker.ts +0 -128
  277. package/src/server/index.ts +0 -4
@@ -1,63 +0,0 @@
1
- //#region src/client/consent-storage.ts
2
- /**
3
- * `localStorage`-backed consent storage. Corrupt state, a private-mode/quota error, or no
4
- * `window` (SSR) degrades to an in-memory record — the visitor's decision still applies
5
- * for the session instead of re-prompting in a loop. `subscribe` fires for same-tab
6
- * writes and, via the `storage` event, for decisions made in other tabs.
7
- *
8
- * @remarks
9
- * The record persists as plain `JSON.stringify(ConsentRecord)` — a stable contract, so
10
- * pre-hydration inline scripts (e.g. a Consent Mode default bootstrap) can read the
11
- * decision synchronously before any tag fires.
12
- *
13
- * @since 0.5.0-canary.4
14
- */
15
- function createLocalStorageConsentStorage(storageKey) {
16
- const listeners = /* @__PURE__ */ new Set();
17
- let memoryRecord;
18
- function notify() {
19
- for (const listener of listeners) listener();
20
- }
21
- return {
22
- clear() {
23
- if (typeof globalThis.window === "undefined") return;
24
- memoryRecord = void 0;
25
- try {
26
- globalThis.window.localStorage.removeItem(storageKey);
27
- } catch {}
28
- notify();
29
- },
30
- load() {
31
- if (typeof globalThis.window === "undefined") return;
32
- try {
33
- const raw = globalThis.window.localStorage.getItem(storageKey);
34
- return raw ? JSON.parse(raw) : memoryRecord;
35
- } catch {
36
- return memoryRecord;
37
- }
38
- },
39
- save(record) {
40
- if (typeof globalThis.window === "undefined") return;
41
- try {
42
- globalThis.window.localStorage.setItem(storageKey, JSON.stringify(record));
43
- memoryRecord = void 0;
44
- } catch {
45
- memoryRecord = record;
46
- }
47
- notify();
48
- },
49
- subscribe(listener) {
50
- listeners.add(listener);
51
- function handleStorageEvent(event) {
52
- if (event.key === null || event.key === storageKey) listener();
53
- }
54
- if (typeof globalThis.window !== "undefined") globalThis.window.addEventListener("storage", handleStorageEvent);
55
- return () => {
56
- listeners.delete(listener);
57
- if (typeof globalThis.window !== "undefined") globalThis.window.removeEventListener("storage", handleStorageEvent);
58
- };
59
- }
60
- };
61
- }
62
- //#endregion
63
- export { createLocalStorageConsentStorage };
@@ -1,37 +0,0 @@
1
- import { Destination } from "../core/destination.mjs";
2
- import { EventQueueStorage } from "./queue.mjs";
3
- import { EventCatalog, EventsOf } from "../core/event-catalog.mjs";
4
- import { z } from "zod";
5
-
6
- //#region src/client/create-client-tracker.d.ts
7
- /**
8
- * @since 0.5.0-canary.4
9
- */
10
- interface ClientTrackerOptions<Catalog extends EventCatalog> {
11
- anonymousId: string;
12
- catalog: Catalog;
13
- destinations: Array<Destination>;
14
- maxQueueSize?: number;
15
- maxRetries?: number;
16
- storage: EventQueueStorage;
17
- }
18
- /**
19
- * @since 0.5.0-canary.4
20
- */
21
- interface ClientTracker<Catalog extends EventCatalog> {
22
- /** Drops every pending event without sending it — call this when consent is revoked. */
23
- clear: () => void;
24
- flush: () => Promise<void>;
25
- /** Synchronous, best-effort flush via `navigator.sendBeacon` — for page unload only. */
26
- flushWithBeacon: (endpoint: string) => void;
27
- group: (groupId: string, traits?: Record<string, unknown>) => void;
28
- identify: (userId: string, traits?: Record<string, unknown>) => void;
29
- page: (name?: string, props?: Record<string, unknown>) => void;
30
- track: <Name extends keyof EventsOf<Catalog, "client">>(name: Name, props: z.infer<EventsOf<Catalog, "client">[Name]["schema"]>) => void;
31
- }
32
- /**
33
- * @since 0.5.0-canary.4
34
- */
35
- declare function createClientTracker<Catalog extends EventCatalog>(options: ClientTrackerOptions<Catalog>): ClientTracker<Catalog>;
36
- //#endregion
37
- export { ClientTracker, ClientTrackerOptions, createClientTracker };
@@ -1,66 +0,0 @@
1
- import { generateEventId } from "../core/event-id.mjs";
2
- import { EventQueue } from "./queue.mjs";
3
- //#region src/client/create-client-tracker.ts
4
- /**
5
- * @since 0.5.0-canary.4
6
- */
7
- function createClientTracker(options) {
8
- const immediateDestinations = options.destinations.filter((destination) => destination.delivery === "immediate");
9
- const queue = new EventQueue({
10
- destinations: options.destinations.filter((destination) => destination.delivery !== "immediate"),
11
- maxQueueSize: options.maxQueueSize,
12
- maxRetries: options.maxRetries,
13
- storage: options.storage
14
- });
15
- let userId;
16
- function enqueue(name, props) {
17
- const envelope = {
18
- anonymousId: options.anonymousId,
19
- eventId: generateEventId(),
20
- name,
21
- owner: "client",
22
- props,
23
- timestamp: Date.now(),
24
- ...userId === void 0 ? {} : { userId }
25
- };
26
- for (const destination of immediateDestinations) try {
27
- Promise.resolve(destination.send(envelope)).catch(() => {});
28
- } catch {}
29
- queue.enqueue(envelope);
30
- }
31
- return {
32
- clear: () => {
33
- queue.clear();
34
- },
35
- flush: () => queue.flush(),
36
- flushWithBeacon(endpoint) {
37
- const events = queue.drain();
38
- if (events.length === 0) return;
39
- if (!navigator.sendBeacon(endpoint, JSON.stringify(events))) for (const event of events) queue.enqueue(event);
40
- },
41
- group(groupId, traits = {}) {
42
- enqueue("$group", {
43
- groupId,
44
- ...traits
45
- });
46
- },
47
- identify(id, traits = {}) {
48
- userId = id;
49
- enqueue("$identify", traits);
50
- },
51
- page(name, props = {}) {
52
- enqueue("$page_viewed", name === void 0 ? props : {
53
- name,
54
- ...props
55
- });
56
- },
57
- track(name, props) {
58
- const definition = options.catalog[name];
59
- if (!definition || definition.owner !== "client") throw new Error(`Unknown client-owned event: ${String(name)}`);
60
- definition.schema.parse(props);
61
- enqueue(name, props);
62
- }
63
- };
64
- }
65
- //#endregion
66
- export { createClientTracker };
@@ -1,10 +0,0 @@
1
- //#region src/client/gpc.d.ts
2
- /**
3
- * Global Privacy Control isn't in lib.dom yet, hence the local interface extension.
4
- * CCPA/CPRA requires honoring this as an opt-out signal even under the opt-out default.
5
- *
6
- * @since 0.5.0-canary.4
7
- */
8
- declare function hasGlobalPrivacyControlSignal(): boolean;
9
- //#endregion
10
- export { hasGlobalPrivacyControlSignal };
@@ -1,12 +0,0 @@
1
- //#region src/client/gpc.ts
2
- /**
3
- * Global Privacy Control isn't in lib.dom yet, hence the local interface extension.
4
- * CCPA/CPRA requires honoring this as an opt-out signal even under the opt-out default.
5
- *
6
- * @since 0.5.0-canary.4
7
- */
8
- function hasGlobalPrivacyControlSignal() {
9
- return navigator.globalPrivacyControl === true;
10
- }
11
- //#endregion
12
- export { hasGlobalPrivacyControlSignal };
@@ -1,8 +0,0 @@
1
- import { createLocalStorageConsentStorage } from "./consent-storage.mjs";
2
- import { EventQueue, EventQueueOptions, EventQueueStorage } from "./queue.mjs";
3
- import { ClientTracker, ClientTrackerOptions, createClientTracker } from "./create-client-tracker.mjs";
4
- import { hasGlobalPrivacyControlSignal } from "./gpc.mjs";
5
- import { ClientLifecycleOptions, attachClientLifecycle } from "./lifecycle.mjs";
6
- import { createLocalStorageQueueStorage } from "./local-storage.mjs";
7
- import { RouterLike, attachRouterPageTracking } from "./router.mjs";
8
- export { type ClientLifecycleOptions, type ClientTracker, type ClientTrackerOptions, EventQueue, type EventQueueOptions, type EventQueueStorage, type RouterLike, attachClientLifecycle, attachRouterPageTracking, createClientTracker, createLocalStorageConsentStorage, createLocalStorageQueueStorage, hasGlobalPrivacyControlSignal };
@@ -1,8 +0,0 @@
1
- import { createLocalStorageConsentStorage } from "./consent-storage.mjs";
2
- import { EventQueue } from "./queue.mjs";
3
- import { createClientTracker } from "./create-client-tracker.mjs";
4
- import { hasGlobalPrivacyControlSignal } from "./gpc.mjs";
5
- import { attachClientLifecycle } from "./lifecycle.mjs";
6
- import { createLocalStorageQueueStorage } from "./local-storage.mjs";
7
- import { attachRouterPageTracking } from "./router.mjs";
8
- export { EventQueue, attachClientLifecycle, attachRouterPageTracking, createClientTracker, createLocalStorageConsentStorage, createLocalStorageQueueStorage, hasGlobalPrivacyControlSignal };
@@ -1,23 +0,0 @@
1
- import { EventCatalog } from "../core/event-catalog.mjs";
2
- import { ClientTracker } from "./create-client-tracker.mjs";
3
-
4
- //#region src/client/lifecycle.d.ts
5
- /**
6
- * @since 0.5.0-canary.4
7
- */
8
- interface ClientLifecycleOptions {
9
- /** `sendBeacon` target used on unload — omit to skip the unload flush entirely. */
10
- beaconEndpoint?: string;
11
- flushIntervalMs?: number;
12
- }
13
- /**
14
- * Wires the two flush triggers the queue itself can't own (batch-size is handled inside
15
- * `EventQueue`): a periodic interval flush, and a best-effort `sendBeacon` flush on
16
- * unload — `fetch` isn't reliable once the page starts unloading, `sendBeacon` is.
17
- * Returns a cleanup function to remove all listeners/timers.
18
- *
19
- * @since 0.5.0-canary.4
20
- */
21
- declare function attachClientLifecycle<Catalog extends EventCatalog>(tracker: Pick<ClientTracker<Catalog>, "flush" | "flushWithBeacon">, options?: ClientLifecycleOptions): () => void;
22
- //#endregion
23
- export { ClientLifecycleOptions, attachClientLifecycle };
@@ -1,30 +0,0 @@
1
- //#region src/client/lifecycle.ts
2
- /**
3
- * Wires the two flush triggers the queue itself can't own (batch-size is handled inside
4
- * `EventQueue`): a periodic interval flush, and a best-effort `sendBeacon` flush on
5
- * unload — `fetch` isn't reliable once the page starts unloading, `sendBeacon` is.
6
- * Returns a cleanup function to remove all listeners/timers.
7
- *
8
- * @since 0.5.0-canary.4
9
- */
10
- function attachClientLifecycle(tracker, options = {}) {
11
- const flushIntervalMs = options.flushIntervalMs ?? 1e4;
12
- const intervalId = setInterval(() => {
13
- tracker.flush();
14
- }, flushIntervalMs);
15
- function flushOnUnload() {
16
- if (options.beaconEndpoint !== void 0) tracker.flushWithBeacon(options.beaconEndpoint);
17
- }
18
- function handleVisibilityChange() {
19
- if (document.visibilityState === "hidden") flushOnUnload();
20
- }
21
- document.addEventListener("visibilitychange", handleVisibilityChange);
22
- window.addEventListener("pagehide", flushOnUnload);
23
- return () => {
24
- clearInterval(intervalId);
25
- document.removeEventListener("visibilitychange", handleVisibilityChange);
26
- window.removeEventListener("pagehide", flushOnUnload);
27
- };
28
- }
29
- //#endregion
30
- export { attachClientLifecycle };
@@ -1,13 +0,0 @@
1
- import { EventQueueStorage } from "./queue.mjs";
2
-
3
- //#region src/client/local-storage.d.ts
4
- /**
5
- * `localStorage`-backed queue storage — corrupt/missing state, a private-mode/quota
6
- * error, or no `window` (SSR) are all treated as empty rather than thrown, since a lost
7
- * offline queue is preferable to a crashing app.
8
- *
9
- * @since 0.5.0-canary.4
10
- */
11
- declare function createLocalStorageQueueStorage(storageKey: string): EventQueueStorage;
12
- //#endregion
13
- export { createLocalStorageQueueStorage };
@@ -1,31 +0,0 @@
1
- //#region src/client/local-storage.ts
2
- /**
3
- * `localStorage`-backed queue storage — corrupt/missing state, a private-mode/quota
4
- * error, or no `window` (SSR) are all treated as empty rather than thrown, since a lost
5
- * offline queue is preferable to a crashing app.
6
- *
7
- * @since 0.5.0-canary.4
8
- */
9
- function createLocalStorageQueueStorage(storageKey) {
10
- return {
11
- load() {
12
- if (typeof globalThis.window === "undefined") return [];
13
- try {
14
- const raw = globalThis.window.localStorage.getItem(storageKey);
15
- if (!raw) return [];
16
- const parsed = JSON.parse(raw);
17
- return Array.isArray(parsed) ? parsed : [];
18
- } catch {
19
- return [];
20
- }
21
- },
22
- save(events) {
23
- if (typeof globalThis.window === "undefined") return;
24
- try {
25
- globalThis.window.localStorage.setItem(storageKey, JSON.stringify(events));
26
- } catch {}
27
- }
28
- };
29
- }
30
- //#endregion
31
- export { createLocalStorageQueueStorage };
@@ -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 {};