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

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 +469 -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 +205 -111
  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
@@ -0,0 +1,96 @@
1
+ import type { ConsentDecision } from "#/core/consent";
2
+ import type { Destination } from "#/core/destination";
3
+ import { toAdConsentState } from "#/destinations/ad-consent";
4
+ import type { FlatPropertyValue } from "#/destinations/shared";
5
+ import { flattenEventProps } from "#/destinations/shared";
6
+
7
+ /**
8
+ * Meta's `dataProcessingOptions` restriction. `['LDU'], 0, 0` turns on Limited Data Use and
9
+ * lets Meta geolocate the user — the recommended default beyond California, where only
10
+ * country `1` (USA) / state `1000` (California) are documented codes (spec-destinations §5).
11
+ * `[]` applies no restriction.
12
+ *
13
+ * @since 1.0.0-canary.7
14
+ */
15
+ export interface MetaDataProcessingOptions {
16
+ country: number;
17
+ options: ReadonlyArray<string>;
18
+ state: number;
19
+ }
20
+
21
+ /**
22
+ * Maps a `ConsentDecision` to Meta's `dataProcessingOptions`: LDU when `ads` is denied.
23
+ *
24
+ * @since 1.0.0-canary.7
25
+ */
26
+ export function toMetaDataProcessingOptions(decision: ConsentDecision): MetaDataProcessingOptions {
27
+ return toAdConsentState(decision).limitedDataUse
28
+ ? { country: 0, options: ["LDU"], state: 0 }
29
+ : { country: 0, options: [], state: 0 };
30
+ }
31
+
32
+ /**
33
+ * The mapped per-event payload handed to a Meta transport (Pixel `fbq` or a CAPI request).
34
+ *
35
+ * @since 1.0.0-canary.7
36
+ */
37
+ export interface MetaEventPayload {
38
+ dataProcessingOptions: MetaDataProcessingOptions;
39
+ name: string;
40
+ properties: Record<string, FlatPropertyValue>;
41
+ }
42
+
43
+ /**
44
+ * @since 1.0.0-canary.7
45
+ */
46
+ export interface MetaDestinationOptions {
47
+ /**
48
+ * Erasure cookie-clear seam — invoked by `onErasure` to drop Meta's `_fbp`/`_fbc` cookies
49
+ * (spec-data-subject-rights DSR-V4). Meta exposes no per-visitor deletion API, so erasure
50
+ * is cookie-clear + stop-send only. Omit if the integrator clears cookies elsewhere.
51
+ */
52
+ clearCookies?: (() => void) | undefined;
53
+ /** Read per event so an `ads` change restricts data use without recreating the destination. */
54
+ getDecision: () => ConsentDecision;
55
+ name?: string | undefined;
56
+ /**
57
+ * Delivers one mapped event — the transport seam. Wire it to `fbq(...)` (Pixel) or a
58
+ * Conversions API request; this package ships the consent mapping, never the credentials
59
+ * or network client.
60
+ */
61
+ transport: (payload: MetaEventPayload) => Promise<void> | void;
62
+ }
63
+
64
+ /**
65
+ * Reference ad destination: maps each event to Meta's shape and applies Limited Data Use
66
+ * from the live `ads` decision (spec-destinations §5), then hands it to an injected
67
+ * transport. Consent-restriction mapping only — the Pixel/CAPI transport and credentials
68
+ * are the integrator's to supply. `consentRequirement` stays `"required"`: an ad sink is
69
+ * never exempt.
70
+ *
71
+ * @since 1.0.0-canary.7
72
+ */
73
+ export function createMetaDestination(options: MetaDestinationOptions): Destination {
74
+ // Erasure halts delivery for the rest of the session — Meta has no per-visitor deletion API.
75
+ let stopped = false;
76
+
77
+ return {
78
+ consentRequirement: "required",
79
+ name: options.name ?? "meta",
80
+ onErasure() {
81
+ stopped = true;
82
+ options.clearCookies?.();
83
+ },
84
+ async send(event) {
85
+ if (stopped) {
86
+ return;
87
+ }
88
+
89
+ await options.transport({
90
+ dataProcessingOptions: toMetaDataProcessingOptions(options.getDecision()),
91
+ name: event.name,
92
+ properties: flattenEventProps(event.properties),
93
+ });
94
+ },
95
+ };
96
+ }
@@ -0,0 +1,86 @@
1
+ import type { ConsentDecision } from "#/core/consent";
2
+ import type { Destination } from "#/core/destination";
3
+ import { toAdConsentState } from "#/destinations/ad-consent";
4
+ import type { FlatPropertyValue } from "#/destinations/shared";
5
+ import { flattenEventProps } from "#/destinations/shared";
6
+
7
+ /**
8
+ * Microsoft UET consent. UET enforces **only** `ad_storage` — it has no `analytics_storage`,
9
+ * and its `ad_user_data`/`ad_personalization` fields have no documented behavior, so this
10
+ * models the one enforced signal (spec-destinations §5). Pushed via
11
+ * `uetq.push('consent','update', …)`.
12
+ *
13
+ * @since 1.0.0-canary.7
14
+ */
15
+ export interface MicrosoftUetConsent {
16
+ ad_storage: "denied" | "granted";
17
+ }
18
+
19
+ /**
20
+ * Maps a `ConsentDecision` to UET's enforced `ad_storage` signal via the shared ad lever, so
21
+ * it can't drift from Meta/TikTok — `ad_storage` is the inverse of Limited Data Use.
22
+ *
23
+ * @since 1.0.0-canary.7
24
+ */
25
+ export function toMicrosoftUetConsent(decision: ConsentDecision): MicrosoftUetConsent {
26
+ return { ad_storage: toAdConsentState(decision).limitedDataUse ? "denied" : "granted" };
27
+ }
28
+
29
+ /**
30
+ * The mapped per-event payload handed to a UET transport (`uetq.push`).
31
+ *
32
+ * @since 1.0.0-canary.7
33
+ */
34
+ export interface MicrosoftUetEventPayload {
35
+ consent: MicrosoftUetConsent;
36
+ name: string;
37
+ properties: Record<string, FlatPropertyValue>;
38
+ }
39
+
40
+ /**
41
+ * @since 1.0.0-canary.7
42
+ */
43
+ export interface MicrosoftUetDestinationOptions {
44
+ /** Erasure cookie-clear seam — UET exposes no per-visitor deletion API, so erasure is cookie-clear + stop-send (DSR-V4). */
45
+ clearCookies?: (() => void) | undefined;
46
+ /** Read per event so an `ads` change updates `ad_storage` without recreating the destination. */
47
+ getDecision: () => ConsentDecision;
48
+ name?: string | undefined;
49
+ /**
50
+ * Delivers one mapped event — the transport seam. Wire it to `uetq.push(...)`; this package
51
+ * ships the consent mapping, never the tag id or network client.
52
+ */
53
+ transport: (payload: MicrosoftUetEventPayload) => Promise<void> | void;
54
+ }
55
+
56
+ /**
57
+ * Reference ad destination for Microsoft UET: maps each event and the live `ads` decision to
58
+ * UET's `ad_storage` signal, then hands it to an injected transport. Consent-restriction
59
+ * mapping only — the tag id and `uetq` transport are the integrator's. `consentRequirement`
60
+ * stays `"required"`.
61
+ *
62
+ * @since 1.0.0-canary.7
63
+ */
64
+ export function createMicrosoftUetDestination(options: MicrosoftUetDestinationOptions): Destination {
65
+ let stopped = false;
66
+
67
+ return {
68
+ consentRequirement: "required",
69
+ name: options.name ?? "microsoft-uet",
70
+ onErasure() {
71
+ stopped = true;
72
+ options.clearCookies?.();
73
+ },
74
+ async send(event) {
75
+ if (stopped) {
76
+ return;
77
+ }
78
+
79
+ await options.transport({
80
+ consent: toMicrosoftUetConsent(options.getDecision()),
81
+ name: event.name,
82
+ properties: flattenEventProps(event.properties),
83
+ });
84
+ },
85
+ };
86
+ }
@@ -0,0 +1,45 @@
1
+ /**
2
+ * @since 1.0.0-canary.6
3
+ */
4
+ export type FlatPropertyValue = boolean | number | string;
5
+
6
+ interface FlattenEventPropsOptions {
7
+ /** Vercel Analytics accepts `null` directly; GA4 (gtag.js/Measurement Protocol) does not. */
8
+ allowNull?: boolean | undefined;
9
+ }
10
+
11
+ /**
12
+ * Event params must be flat string/number/boolean (optionally `null`) — stringify
13
+ * anything else instead of letting the destination silently drop it.
14
+ *
15
+ * @since 1.0.0-canary.6
16
+ */
17
+ export function flattenEventProps(properties: Record<string, unknown>): Record<string, FlatPropertyValue>;
18
+ /**
19
+ * @since 1.0.0-canary.6
20
+ */
21
+ export function flattenEventProps(
22
+ properties: Record<string, unknown>,
23
+ options: { allowNull: true },
24
+ ): Record<string, FlatPropertyValue | null>;
25
+ /**
26
+ * @since 1.0.0-canary.6
27
+ */
28
+ export function flattenEventProps(
29
+ properties: Record<string, unknown>,
30
+ options: FlattenEventPropsOptions = {},
31
+ ): Record<string, FlatPropertyValue | null> {
32
+ const result: Record<string, FlatPropertyValue | null> = {};
33
+
34
+ for (const [key, value] of Object.entries(properties)) {
35
+ if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
36
+ result[key] = value;
37
+ } else if (options.allowNull === true && value === null) {
38
+ result[key] = null;
39
+ } else if (value !== undefined && value !== null) {
40
+ result[key] = JSON.stringify(value);
41
+ }
42
+ }
43
+
44
+ return result;
45
+ }
@@ -0,0 +1,85 @@
1
+ import type { ConsentDecision } from "#/core/consent";
2
+ import type { Destination } from "#/core/destination";
3
+ import { toAdConsentState } from "#/destinations/ad-consent";
4
+ import type { FlatPropertyValue } from "#/destinations/shared";
5
+ import { flattenEventProps } from "#/destinations/shared";
6
+
7
+ /**
8
+ * TikTok consent. TikTok uses a **single Limited Data Use boolean**, not Meta's
9
+ * `dataProcessingOptions` structure and no signal object (spec-destinations §5). Its
10
+ * transmission gate (`ttq.grantConsent()`/`revokeConsent()`) follows `analytics` and is the
11
+ * tracker's job; this models the `ads`-driven LDU lever.
12
+ *
13
+ * @since 1.0.0-canary.7
14
+ */
15
+ export interface TiktokConsent {
16
+ limited_data_use: boolean;
17
+ }
18
+
19
+ /**
20
+ * Maps a `ConsentDecision` to TikTok's LDU boolean — on when `ads` is denied.
21
+ *
22
+ * @since 1.0.0-canary.7
23
+ */
24
+ export function toTiktokConsent(decision: ConsentDecision): TiktokConsent {
25
+ return { limited_data_use: toAdConsentState(decision).limitedDataUse };
26
+ }
27
+
28
+ /**
29
+ * The mapped per-event payload handed to a TikTok transport (`ttq.track` / Events API).
30
+ *
31
+ * @since 1.0.0-canary.7
32
+ */
33
+ export interface TiktokEventPayload {
34
+ consent: TiktokConsent;
35
+ name: string;
36
+ properties: Record<string, FlatPropertyValue>;
37
+ }
38
+
39
+ /**
40
+ * @since 1.0.0-canary.7
41
+ */
42
+ export interface TiktokDestinationOptions {
43
+ /** Erasure cookie-clear seam — TikTok exposes no per-visitor deletion API, so erasure is cookie-clear + stop-send (DSR-V4). */
44
+ clearCookies?: (() => void) | undefined;
45
+ /** Read per event so an `ads` change flips LDU without recreating the destination. */
46
+ getDecision: () => ConsentDecision;
47
+ name?: string | undefined;
48
+ /**
49
+ * Delivers one mapped event — the transport seam. Wire it to `ttq.track(...)` (Pixel) or the
50
+ * Events API; this package ships the consent mapping, never the pixel id or network client.
51
+ */
52
+ transport: (payload: TiktokEventPayload) => Promise<void> | void;
53
+ }
54
+
55
+ /**
56
+ * Reference ad destination for TikTok: maps each event and the live `ads` decision to
57
+ * TikTok's LDU boolean, then hands it to an injected transport. Consent-restriction mapping
58
+ * only — the pixel id and `ttq` transport are the integrator's. `consentRequirement` stays
59
+ * `"required"`.
60
+ *
61
+ * @since 1.0.0-canary.7
62
+ */
63
+ export function createTiktokDestination(options: TiktokDestinationOptions): Destination {
64
+ let stopped = false;
65
+
66
+ return {
67
+ consentRequirement: "required",
68
+ name: options.name ?? "tiktok",
69
+ onErasure() {
70
+ stopped = true;
71
+ options.clearCookies?.();
72
+ },
73
+ async send(event) {
74
+ if (stopped) {
75
+ return;
76
+ }
77
+
78
+ await options.transport({
79
+ consent: toTiktokConsent(options.getDecision()),
80
+ name: event.name,
81
+ properties: flattenEventProps(event.properties),
82
+ });
83
+ },
84
+ };
85
+ }
@@ -1,40 +1,39 @@
1
- import { track } from "@vercel/analytics/react";
1
+ import { track } from "@vercel/analytics";
2
2
 
3
3
  import type { Destination } from "#/core/destination";
4
-
5
- type VercelAnalyticsPropertyValue = boolean | number | string | null;
4
+ import { flattenEventProps } from "#/destinations/shared";
6
5
 
7
6
  /**
8
- * Vercel's `track()` rejects nested objects/arrays outright — flatten anything else
9
- * to a string instead of silently dropping it.
7
+ * @since 1.0.0-canary.6
10
8
  */
11
- function toVercelAnalyticsProps(props: Record<string, unknown>): Record<string, VercelAnalyticsPropertyValue> {
12
- const result: Record<string, VercelAnalyticsPropertyValue> = {};
13
-
14
- for (const [key, value] of Object.entries(props)) {
15
- if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
16
- result[key] = value;
17
- } else if (value !== undefined) {
18
- result[key] = JSON.stringify(value);
19
- }
20
- }
21
-
22
- return result;
9
+ export interface VercelAnalyticsDestinationOptions {
10
+ /**
11
+ * Vercel Analytics is cookieless and its events carry no identifier from this
12
+ * package, so it qualifies for `"exempt"` — it then keeps receiving events while the
13
+ * tracker's analytics gate is closed. Defaults to `"required"` so pre-consent delivery
14
+ * stays an explicit opt-in.
15
+ */
16
+ consentRequirement?: "exempt" | "required" | undefined;
17
+ name?: string | undefined;
23
18
  }
24
19
 
25
20
  /**
26
21
  * `track()` only pushes onto Vercel's own in-page queue (`window.va`/`window.vaq`), which
27
- * handles batching and unload delivery itself — hence `delivery: "immediate"`. Requires
28
- * `<Analytics />` from `@vercel/analytics/react` to be mounted once in the app.
22
+ * handles batching and unload delivery itself. Requires the Vercel Analytics script to be
23
+ * loaded once elsewhere in the app (`<Analytics />` from `@vercel/analytics/react`, or the
24
+ * framework-agnostic `inject()`) — this destination only queues events, so it imports the
25
+ * base `@vercel/analytics` package and has no React dependency of its own.
29
26
  *
30
27
  * @since 0.5.0-canary.4
31
28
  */
32
- export function createVercelAnalyticsDestination(name = "vercel-analytics"): Destination {
29
+ export function createVercelAnalyticsDestination(options: VercelAnalyticsDestinationOptions = {}): Destination {
33
30
  return {
34
- delivery: "immediate",
35
- name,
36
- send(event) {
37
- track(event.name, toVercelAnalyticsProps(event.props));
31
+ consentRequirement: options.consentRequirement ?? "required",
32
+ name: options.name ?? "vercel-analytics",
33
+ // Synchronous today, but declared async so a throw here rejects the returned Promise
34
+ // instead of escaping as a synchronous throw — matches Destination.send's contract.
35
+ async send(event) {
36
+ track(event.name, flattenEventProps(event.properties, { allowNull: true }));
38
37
  },
39
38
  };
40
39
  }
package/src/index.ts CHANGED
@@ -1,13 +1,170 @@
1
1
  /**
2
2
  * \@codefast/tracking
3
3
  *
4
- * Fullstack, type-safe event tracking: apps define a Zod event catalog tagged with an
5
- * owner ("client" | "server"), then build trackers from it that only allow firing
6
- * events owned by that side — enforced at compile time, not by convention.
4
+ * Consent-gated, type-safe event tracking for TanStack Start apps: define an event
5
+ * catalog over any Standard Schema library, wire a `ConsentConfig` + `createConsentRuntime`,
6
+ * and fan tracked events out to gtag / Vercel Analytics destinations.
7
7
  *
8
- * - **Root** (this module): isomorphic catalog types, `Destination`, consent helpers — safe to import from both client and server code.
9
- * - **`@codefast/tracking/client`**: `createClientTracker` — batching, offline queue, retry.
10
- * - **`@codefast/tracking/server`**: `createServerTracker`, region detection for consent.
11
- * - **`@codefast/tracking/destinations`**: `createHttpDestination` and the `Destination` building block.
8
+ * This root is the client entry: it re-exports the isomorphic core plus the whole
9
+ * browser-side surface (tracker, consent runtime, React bindings, client destinations).
10
+ * Server-only lanes are their own subpaths and never belong here — `@codefast/tracking/server/*`
11
+ * and `@codefast/tracking/adapters/*` (deny them in the client environment via
12
+ * `SERVER_ONLY_SUBPATHS`). The Vercel destination stays on `@codefast/tracking/destinations/
13
+ * vercel-analytics` so its `@vercel/analytics` peer is only pulled in when used.
12
14
  */
13
- export * from "#/core";
15
+
16
+ // ── Core (isomorphic) ───────────────────────────────────────────────────────────────
17
+ export type {
18
+ ConsentCategory,
19
+ ConsentDecision,
20
+ ConsentMode,
21
+ ConsentRecord,
22
+ ConsentRegion,
23
+ ConsentStorage,
24
+ InitialConsent,
25
+ ResolveDefaultConsentOptions,
26
+ ResolveEffectiveConsentOptions,
27
+ } from "#/core/consent";
28
+ export {
29
+ CONSENT_CATEGORIES,
30
+ CONSENT_REGIONS,
31
+ createConsentDecision,
32
+ isConsentDecision,
33
+ isConsentRecord,
34
+ isConsentRegion,
35
+ isInitialConsent,
36
+ normalizeConsentDecision,
37
+ readStoredDecision,
38
+ resolveConsentMode,
39
+ resolveDefaultConsent,
40
+ resolveEffectiveConsent,
41
+ STRICTEST_INITIAL_CONSENT,
42
+ } from "#/core/consent";
43
+
44
+ export type { ConsentConfig } from "#/core/consent-config";
45
+ export { defineConsentConfig } from "#/core/consent-config";
46
+
47
+ export type {
48
+ ConsentReceipt,
49
+ ConsentReceiptEventType,
50
+ ConsentReceiptInput,
51
+ ConsentReceiptMethod,
52
+ ConsentReceiptSubjectIdType,
53
+ } from "#/core/consent-receipt";
54
+ export { isConsentReceiptInput } from "#/core/consent-receipt";
55
+
56
+ export { readCookieValue } from "#/core/cookie";
57
+
58
+ export type { Destination } from "#/core/destination";
59
+
60
+ export type { EventCatalog, EventDefinition } from "#/core/event-catalog";
61
+ export { assertValidEventProperties, defineEventCatalog } from "#/core/event-catalog";
62
+
63
+ export { generateEventId } from "#/core/event-id";
64
+
65
+ export type { TrackedEvent } from "#/core/tracked-event";
66
+
67
+ // ── Client ──────────────────────────────────────────────────────────────────────────
68
+ export type { CmpConsentSignal, CmpStatus, ReconcileAdFrameworkConsentOptions } from "#/client/ad-framework-consent";
69
+ export { hasGppApi, hasTcfApi, reconcileAdFrameworkConsent } from "#/client/ad-framework-consent";
70
+
71
+ export type { ConsentRuntime, ConsentRuntimeOptions } from "#/client/consent-runtime";
72
+ export { createConsentRuntime } from "#/client/consent-runtime";
73
+
74
+ export { createLocalStorageConsentStorage } from "#/client/consent-storage";
75
+
76
+ export type { ConsentWithdrawalHandlerOptions } from "#/client/consent-withdrawal";
77
+ export { createConsentWithdrawalHandler } from "#/client/consent-withdrawal";
78
+
79
+ export type { CookieAnonymousId, CookieAnonymousIdOptions } from "#/client/cookie-anonymous-id";
80
+ export { createCookieAnonymousId } from "#/client/cookie-anonymous-id";
81
+
82
+ export type { ClientTracker, ClientTrackerOptions, DeliveryErrorContext } from "#/client/create-client-tracker";
83
+ export { createClientTracker } from "#/client/create-client-tracker";
84
+
85
+ export { hasGlobalPrivacyControlSignal } from "#/client/gpc";
86
+
87
+ export type {
88
+ InitialConsentSnapshot,
89
+ InitialConsentStore,
90
+ InitialConsentStoreOptions,
91
+ } from "#/client/initial-consent-store";
92
+ export { createInitialConsentStore } from "#/client/initial-consent-store";
93
+
94
+ export type { IsAnalyticsAllowedOptions } from "#/client/is-analytics-allowed";
95
+ export { createIsAnalyticsAllowed } from "#/client/is-analytics-allowed";
96
+
97
+ export type { ServerPersistedAnonymousIdOptions } from "#/client/server-persisted-anonymous-id";
98
+ export { createServerPersistedAnonymousId } from "#/client/server-persisted-anonymous-id";
99
+
100
+ // ── React ───────────────────────────────────────────────────────────────────────────
101
+ export type {
102
+ ConsentBannerAcceptProps,
103
+ ConsentBannerActionsProps,
104
+ ConsentBannerCategoryProps,
105
+ ConsentBannerCustomizeProps,
106
+ ConsentBannerDescriptionProps,
107
+ ConsentBannerPreferencesProps,
108
+ ConsentBannerProps,
109
+ ConsentBannerRejectProps,
110
+ ConsentBannerSaveProps,
111
+ ConsentBannerTitleProps,
112
+ ConsentToggleProps,
113
+ } from "#/react/consent-banner";
114
+ export {
115
+ ConsentBanner,
116
+ ConsentBannerAccept,
117
+ ConsentBannerActions,
118
+ ConsentBannerCategory,
119
+ ConsentBannerCustomize,
120
+ ConsentBannerDescription,
121
+ ConsentBannerPreferences,
122
+ ConsentBannerReject,
123
+ ConsentBannerSave,
124
+ ConsentBannerTitle,
125
+ ConsentToggle,
126
+ } from "#/react/consent-banner";
127
+
128
+ export type { GtagConsentBootstrapProps } from "#/react/gtag-consent-bootstrap";
129
+ export { GtagConsentBootstrap } from "#/react/gtag-consent-bootstrap";
130
+
131
+ export type { UseConsentOptions, UseConsentResult } from "#/react/use-consent";
132
+ export { useConsent } from "#/react/use-consent";
133
+
134
+ export type { UseGoogleConsentSyncOptions } from "#/react/use-google-consent-sync";
135
+ export { useGoogleConsentSync } from "#/react/use-google-consent-sync";
136
+
137
+ export { useInitialConsent } from "#/react/use-initial-consent";
138
+
139
+ // ── Destinations (client-lane; Vercel stays on its own subpath) ───────────────────────
140
+ export type { AdConsentState } from "#/destinations/ad-consent";
141
+ export { toAdConsentState } from "#/destinations/ad-consent";
142
+
143
+ export type {
144
+ EnsureGtagOptions,
145
+ GoogleAnalyticsDestinationOptions,
146
+ GtagConsentBootstrapOptions,
147
+ GtagFunction,
148
+ LoadGtagScriptOptions,
149
+ } from "#/destinations/google-analytics";
150
+ export {
151
+ buildGtagConsentBootstrapScript,
152
+ clearGoogleAnalyticsCookies,
153
+ createGoogleAnalyticsDestination,
154
+ ensureGtag,
155
+ loadGtagScript,
156
+ updateGoogleConsent,
157
+ } from "#/destinations/google-analytics";
158
+
159
+ export type { MetaDataProcessingOptions, MetaDestinationOptions, MetaEventPayload } from "#/destinations/meta";
160
+ export { createMetaDestination, toMetaDataProcessingOptions } from "#/destinations/meta";
161
+
162
+ export type {
163
+ MicrosoftUetConsent,
164
+ MicrosoftUetDestinationOptions,
165
+ MicrosoftUetEventPayload,
166
+ } from "#/destinations/microsoft-uet";
167
+ export { createMicrosoftUetDestination, toMicrosoftUetConsent } from "#/destinations/microsoft-uet";
168
+
169
+ export type { TiktokConsent, TiktokDestinationOptions, TiktokEventPayload } from "#/destinations/tiktok";
170
+ export { createTiktokDestination, toTiktokConsent } from "#/destinations/tiktok";