@codefast/tracking 0.7.0 → 0.7.1

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 (159) hide show
  1. package/CHANGELOG.md +8 -0
  2. package/README.md +1 -1
  3. package/dist/adapters/tanstack-start.d.ts +11 -7
  4. package/dist/adapters/tanstack-start.d.ts.map +1 -1
  5. package/dist/adapters/tanstack-start.js +4 -4
  6. package/dist/adapters/tanstack-start.js.map +1 -1
  7. package/dist/client/ad-framework-consent.d.ts +8 -6
  8. package/dist/client/ad-framework-consent.d.ts.map +1 -1
  9. package/dist/client/ad-framework-consent.js +3 -3
  10. package/dist/client/ad-framework-consent.js.map +1 -1
  11. package/dist/client/browser-cookie.d.ts +1 -1
  12. package/dist/client/browser-cookie.js +1 -1
  13. package/dist/client/consent-runtime.d.ts +5 -3
  14. package/dist/client/consent-runtime.d.ts.map +1 -1
  15. package/dist/client/consent-runtime.js +1 -1
  16. package/dist/client/consent-runtime.js.map +1 -1
  17. package/dist/client/consent-withdrawal.d.ts +4 -2
  18. package/dist/client/consent-withdrawal.d.ts.map +1 -1
  19. package/dist/client/consent-withdrawal.js +1 -1
  20. package/dist/client/consent-withdrawal.js.map +1 -1
  21. package/dist/client/cookie-anonymous-id.d.ts +7 -3
  22. package/dist/client/cookie-anonymous-id.d.ts.map +1 -1
  23. package/dist/client/cookie-anonymous-id.js +1 -1
  24. package/dist/client/cookie-anonymous-id.js.map +1 -1
  25. package/dist/client/create-client-tracker.d.ts +7 -1
  26. package/dist/client/create-client-tracker.d.ts.map +1 -1
  27. package/dist/client/create-client-tracker.js +2 -0
  28. package/dist/client/create-client-tracker.js.map +1 -1
  29. package/dist/client/initial-consent-store.d.ts +6 -4
  30. package/dist/client/initial-consent-store.d.ts.map +1 -1
  31. package/dist/client/initial-consent-store.js +1 -1
  32. package/dist/client/initial-consent-store.js.map +1 -1
  33. package/dist/client/is-analytics-allowed.d.ts +4 -2
  34. package/dist/client/is-analytics-allowed.d.ts.map +1 -1
  35. package/dist/client/is-analytics-allowed.js +1 -1
  36. package/dist/client/is-analytics-allowed.js.map +1 -1
  37. package/dist/client/server-persisted-anonymous-id.d.ts +4 -2
  38. package/dist/client/server-persisted-anonymous-id.d.ts.map +1 -1
  39. package/dist/client/server-persisted-anonymous-id.js +1 -1
  40. package/dist/client/server-persisted-anonymous-id.js.map +1 -1
  41. package/dist/core/consent-config.d.ts +2 -2
  42. package/dist/core/consent-config.js +1 -1
  43. package/dist/core/consent-receipt.d.ts +6 -6
  44. package/dist/core/consent-receipt.js +1 -1
  45. package/dist/core/consent.d.ts +23 -11
  46. package/dist/core/consent.d.ts.map +1 -1
  47. package/dist/core/consent.js +12 -8
  48. package/dist/core/consent.js.map +1 -1
  49. package/dist/core/cookie.d.ts +2 -2
  50. package/dist/core/cookie.js +2 -2
  51. package/dist/core/event-catalog.d.ts +1 -1
  52. package/dist/core/event-catalog.js +1 -1
  53. package/dist/destinations/ad-consent.d.ts +2 -2
  54. package/dist/destinations/ad-consent.js +1 -1
  55. package/dist/destinations/google-analytics.d.ts +16 -8
  56. package/dist/destinations/google-analytics.d.ts.map +1 -1
  57. package/dist/destinations/google-analytics.js +4 -4
  58. package/dist/destinations/google-analytics.js.map +1 -1
  59. package/dist/destinations/google-consent.d.ts +9 -7
  60. package/dist/destinations/google-consent.d.ts.map +1 -1
  61. package/dist/destinations/google-consent.js +5 -5
  62. package/dist/destinations/google-consent.js.map +1 -1
  63. package/dist/destinations/meta.d.ts +7 -5
  64. package/dist/destinations/meta.d.ts.map +1 -1
  65. package/dist/destinations/meta.js +2 -2
  66. package/dist/destinations/meta.js.map +1 -1
  67. package/dist/destinations/microsoft-uet.d.ts +7 -5
  68. package/dist/destinations/microsoft-uet.d.ts.map +1 -1
  69. package/dist/destinations/microsoft-uet.js +2 -2
  70. package/dist/destinations/microsoft-uet.js.map +1 -1
  71. package/dist/destinations/shared.d.ts +7 -3
  72. package/dist/destinations/shared.d.ts.map +1 -1
  73. package/dist/destinations/shared.js +3 -1
  74. package/dist/destinations/shared.js.map +1 -1
  75. package/dist/destinations/tiktok.d.ts +7 -5
  76. package/dist/destinations/tiktok.d.ts.map +1 -1
  77. package/dist/destinations/tiktok.js +2 -2
  78. package/dist/destinations/tiktok.js.map +1 -1
  79. package/dist/destinations/vercel-analytics.d.ts +3 -1
  80. package/dist/destinations/vercel-analytics.d.ts.map +1 -1
  81. package/dist/destinations/vercel-analytics.js.map +1 -1
  82. package/dist/react/consent-banner.d.ts +28 -0
  83. package/dist/react/consent-banner.d.ts.map +1 -1
  84. package/dist/react/consent-banner.js +11 -7
  85. package/dist/react/consent-banner.js.map +1 -1
  86. package/dist/react/gtag-consent-bootstrap.d.ts +4 -2
  87. package/dist/react/gtag-consent-bootstrap.d.ts.map +1 -1
  88. package/dist/react/gtag-consent-bootstrap.js +1 -1
  89. package/dist/react/gtag-consent-bootstrap.js.map +1 -1
  90. package/dist/react/use-consent.d.ts +4 -0
  91. package/dist/react/use-consent.d.ts.map +1 -1
  92. package/dist/react/use-consent.js.map +1 -1
  93. package/dist/react/use-google-consent-sync.d.ts +4 -2
  94. package/dist/react/use-google-consent-sync.d.ts.map +1 -1
  95. package/dist/react/use-google-consent-sync.js +1 -1
  96. package/dist/react/use-google-consent-sync.js.map +1 -1
  97. package/dist/react/use-initial-consent.d.ts +1 -1
  98. package/dist/react/use-initial-consent.js +1 -1
  99. package/dist/server/anonymous-id-cookie.d.ts +7 -5
  100. package/dist/server/anonymous-id-cookie.d.ts.map +1 -1
  101. package/dist/server/anonymous-id-cookie.js +4 -4
  102. package/dist/server/anonymous-id-cookie.js.map +1 -1
  103. package/dist/server/consent-receipt-store.d.ts +4 -4
  104. package/dist/server/consent-receipt-store.js +2 -2
  105. package/dist/server/consent-receipt.d.ts +4 -4
  106. package/dist/server/consent-receipt.js +3 -3
  107. package/dist/server/initial-consent.d.ts +4 -2
  108. package/dist/server/initial-consent.d.ts.map +1 -1
  109. package/dist/server/initial-consent.js +1 -1
  110. package/dist/server/initial-consent.js.map +1 -1
  111. package/dist/server/measurement-protocol.d.ts +9 -7
  112. package/dist/server/measurement-protocol.d.ts.map +1 -1
  113. package/dist/server/measurement-protocol.js +3 -3
  114. package/dist/server/measurement-protocol.js.map +1 -1
  115. package/dist/server/region.d.ts +2 -2
  116. package/dist/server/region.js +2 -2
  117. package/dist/server/user-deletion.d.ts +9 -5
  118. package/dist/server/user-deletion.d.ts.map +1 -1
  119. package/dist/server/user-deletion.js +2 -2
  120. package/dist/server/user-deletion.js.map +1 -1
  121. package/dist/tooling/import-protection.d.ts +1 -1
  122. package/dist/tooling/import-protection.js +1 -1
  123. package/package.json +7 -7
  124. package/src/adapters/tanstack-start.ts +11 -7
  125. package/src/client/ad-framework-consent.ts +8 -6
  126. package/src/client/browser-cookie.ts +1 -1
  127. package/src/client/consent-runtime.ts +5 -3
  128. package/src/client/consent-withdrawal.ts +4 -2
  129. package/src/client/cookie-anonymous-id.ts +7 -3
  130. package/src/client/create-client-tracker.ts +7 -1
  131. package/src/client/initial-consent-store.ts +6 -4
  132. package/src/client/is-analytics-allowed.ts +4 -2
  133. package/src/client/server-persisted-anonymous-id.ts +4 -2
  134. package/src/core/consent-config.ts +2 -2
  135. package/src/core/consent-receipt.ts +6 -6
  136. package/src/core/consent.ts +23 -11
  137. package/src/core/cookie.ts +2 -2
  138. package/src/core/event-catalog.ts +1 -1
  139. package/src/destinations/ad-consent.ts +2 -2
  140. package/src/destinations/google-analytics.ts +16 -8
  141. package/src/destinations/google-consent.ts +9 -7
  142. package/src/destinations/meta.ts +7 -5
  143. package/src/destinations/microsoft-uet.ts +7 -5
  144. package/src/destinations/shared.ts +10 -4
  145. package/src/destinations/tiktok.ts +7 -5
  146. package/src/destinations/vercel-analytics.ts +3 -1
  147. package/src/react/consent-banner.tsx +34 -8
  148. package/src/react/gtag-consent-bootstrap.tsx +4 -2
  149. package/src/react/use-consent.ts +4 -0
  150. package/src/react/use-google-consent-sync.ts +4 -2
  151. package/src/react/use-initial-consent.ts +1 -1
  152. package/src/server/anonymous-id-cookie.ts +7 -5
  153. package/src/server/consent-receipt-store.ts +4 -4
  154. package/src/server/consent-receipt.ts +4 -4
  155. package/src/server/initial-consent.ts +4 -2
  156. package/src/server/measurement-protocol.ts +9 -7
  157. package/src/server/region.ts +2 -2
  158. package/src/server/user-deletion.ts +9 -5
  159. package/src/tooling/import-protection.ts +1 -1
@@ -21,7 +21,7 @@ type GtagPropertyValue = FlatPropertyValue;
21
21
  * two separate `declare global` augmentations with different signatures for the same
22
22
  * property is a TS error, not a merge.
23
23
  *
24
- * @since 1.0.0-canary.6
24
+ * @since 0.5.0-canary.6
25
25
  */
26
26
  export type GtagFunction = {
27
27
  (command: "config", targetId: string, params?: Record<string, GtagPropertyValue>): void;
@@ -53,7 +53,9 @@ function gtagScriptSrc(gaMeasurementId: string, dataLayerName: string): string {
53
53
  }
54
54
 
55
55
  /**
56
- * @since 1.0.0-canary.6
56
+ * Options for `ensureGtag`.
57
+ *
58
+ * @since 0.5.0-canary.6
57
59
  */
58
60
  export interface EnsureGtagOptions {
59
61
  /**
@@ -67,7 +69,7 @@ export interface EnsureGtagOptions {
67
69
  * Ensures the standard gtag.js queueing stub exists so consent commands can be issued
68
70
  * before the tag itself loads — gtag.js replays the queue in order once it boots.
69
71
  *
70
- * @since 1.0.0-canary.6
72
+ * @since 0.5.0-canary.6
71
73
  */
72
74
  export function ensureGtag(options: EnsureGtagOptions = {}): GtagFunction | undefined {
73
75
  if (typeof window === "undefined") {
@@ -88,7 +90,9 @@ export function ensureGtag(options: EnsureGtagOptions = {}): GtagFunction | unde
88
90
  }
89
91
 
90
92
  /**
91
- * @since 1.0.0-canary.6
93
+ * Options for `loadGtagScript`.
94
+ *
95
+ * @since 0.5.0-canary.6
92
96
  */
93
97
  export interface LoadGtagScriptOptions {
94
98
  /**
@@ -115,7 +119,7 @@ export interface LoadGtagScriptOptions {
115
119
  * (advanced Consent Mode always injects the tag after the default); use this when the
116
120
  * bootstrap did not run, or as an idempotent safety net after a runtime grant.
117
121
  *
118
- * @since 1.0.0-canary.6
122
+ * @since 0.5.0-canary.6
119
123
  */
120
124
  export function loadGtagScript(options: LoadGtagScriptOptions): void {
121
125
  if (typeof document === "undefined" || document.querySelector(`script[src^="${GTAG_SCRIPT_BASE_URL}"]`) !== null) {
@@ -154,7 +158,7 @@ export function loadGtagScript(options: LoadGtagScriptOptions): void {
154
158
  * domain. Consent Mode stops using them once denied but never removes them — call from
155
159
  * a consent-withdrawal handler so a revoke does not leave identifier cookies behind.
156
160
  *
157
- * @since 1.0.0-canary.6
161
+ * @since 0.5.0-canary.6
158
162
  */
159
163
  export function clearGoogleAnalyticsCookies(): void {
160
164
  if (typeof document === "undefined") {
@@ -186,7 +190,9 @@ export function updateGoogleConsent(decision: ConsentDecision, options: EnsureGt
186
190
  }
187
191
 
188
192
  /**
189
- * @since 1.0.0-canary.6
193
+ * Options for `buildGtagConsentBootstrapScript`.
194
+ *
195
+ * @since 0.5.0-canary.6
190
196
  */
191
197
  export interface GtagConsentBootstrapOptions {
192
198
  /** The same object `useConsent` receives — the bootstrap reads its `storageKey` and `policyVersion`. */
@@ -223,7 +229,7 @@ export interface GtagConsentBootstrapOptions {
223
229
  * so the already-loaded tag picks up the grant/deny — this only covers the page-load
224
230
  * default + script injection.
225
231
  *
226
- * @since 1.0.0-canary.6
232
+ * @since 0.5.0-canary.6
227
233
  */
228
234
  export function buildGtagConsentBootstrapScript(options: GtagConsentBootstrapOptions): string {
229
235
  const {
@@ -259,6 +265,8 @@ export function buildGtagConsentBootstrapScript(options: GtagConsentBootstrapOpt
259
265
  }
260
266
 
261
267
  /**
268
+ * Options for `createGoogleAnalyticsDestination`.
269
+ *
262
270
  * @since 0.5.0-canary.4
263
271
  */
264
272
  export interface GoogleAnalyticsDestinationOptions {
@@ -4,7 +4,7 @@ import { CONSENT_CATEGORIES } from "#/core/consent";
4
4
  /**
5
5
  * gtag.js/gtm.js's default queue-array name — shared so the gtag and GTM helpers cannot disagree.
6
6
  *
7
- * @since 1.0.0-canary.6
7
+ * @since 0.5.0-canary.6
8
8
  */
9
9
  export const DEFAULT_DATA_LAYER_NAME = "dataLayer";
10
10
 
@@ -14,7 +14,7 @@ type GoogleConsentState = "denied" | "granted";
14
14
  * Consent Mode v2 params issued via `gtag('consent', …)` — shared by the gtag and GTM
15
15
  * bootstraps so signal mapping cannot drift between them.
16
16
  *
17
- * @since 1.0.0-canary.6
17
+ * @since 0.5.0-canary.6
18
18
  */
19
19
  export interface GoogleConsentParams {
20
20
  ad_personalization: GoogleConsentState;
@@ -44,7 +44,7 @@ type GoogleConsentSignal = keyof typeof GOOGLE_CONSENT_SIGNAL_CATEGORIES;
44
44
  /**
45
45
  * Maps a package `ConsentDecision` onto Consent Mode v2's four storage signals.
46
46
  *
47
- * @since 1.0.0-canary.6
47
+ * @since 0.5.0-canary.6
48
48
  */
49
49
  export function toGoogleConsentParams(decision: ConsentDecision): GoogleConsentParams {
50
50
  // Derived from the signal map (not hand-written per signal) so the runtime params and
@@ -79,7 +79,9 @@ function consentSignalAssignmentsExpression(): string {
79
79
  }
80
80
 
81
81
  /**
82
- * @since 1.0.0-canary.6
82
+ * Options for `buildGoogleConsentBootstrapPreamble`.
83
+ *
84
+ * @since 0.5.0-canary.6
83
85
  */
84
86
  export interface GoogleConsentBootstrapPreambleOptions {
85
87
  /** localStorage key holding the package's `ConsentRecord`. */
@@ -96,7 +98,7 @@ export interface GoogleConsentBootstrapPreambleOptions {
96
98
  * "default" signal. The builders append only their tag-specific tail, so the consent
97
99
  * logic cannot drift between them.
98
100
  *
99
- * @since 1.0.0-canary.6
101
+ * @since 0.5.0-canary.6
100
102
  */
101
103
  export function buildGoogleConsentBootstrapPreamble(options: GoogleConsentBootstrapPreambleOptions): string {
102
104
  const dataLayerAccess = `window[${JSON.stringify(options.dataLayerName)}]`;
@@ -120,7 +122,7 @@ export function buildGoogleConsentBootstrapPreamble(options: GoogleConsentBootst
120
122
  /**
121
123
  * Reads or creates a named `window[dataLayerName]` queue array.
122
124
  *
123
- * @since 1.0.0-canary.6
125
+ * @since 0.5.0-canary.6
124
126
  */
125
127
  export function ensureDataLayer(dataLayerName: string): Array<unknown> | undefined {
126
128
  if (typeof window === "undefined") {
@@ -149,7 +151,7 @@ function isGa4EventName(name: string): boolean {
149
151
  /**
150
152
  * Warns and returns `false` when `eventName` would be rejected by GA4.
151
153
  *
152
- * @since 1.0.0-canary.6
154
+ * @since 0.5.0-canary.6
153
155
  */
154
156
  export function warnUnlessGa4EventName(destinationName: string, eventName: string): boolean {
155
157
  if (isGa4EventName(eventName)) {
@@ -10,7 +10,7 @@ import { flattenEventProps } from "#/destinations/shared";
10
10
  * country `1` (USA) / state `1000` (California) are documented codes (spec-destinations §5).
11
11
  * `[]` applies no restriction.
12
12
  *
13
- * @since 1.0.0-canary.7
13
+ * @since 0.5.0-canary.6
14
14
  */
15
15
  export interface MetaDataProcessingOptions {
16
16
  country: number;
@@ -21,7 +21,7 @@ export interface MetaDataProcessingOptions {
21
21
  /**
22
22
  * Maps a `ConsentDecision` to Meta's `dataProcessingOptions`: LDU when `ads` is denied.
23
23
  *
24
- * @since 1.0.0-canary.7
24
+ * @since 0.5.0-canary.6
25
25
  */
26
26
  export function toMetaDataProcessingOptions(decision: ConsentDecision): MetaDataProcessingOptions {
27
27
  return toAdConsentState(decision).limitedDataUse
@@ -32,7 +32,7 @@ export function toMetaDataProcessingOptions(decision: ConsentDecision): MetaData
32
32
  /**
33
33
  * The mapped per-event payload handed to a Meta transport (Pixel `fbq` or a CAPI request).
34
34
  *
35
- * @since 1.0.0-canary.7
35
+ * @since 0.5.0-canary.6
36
36
  */
37
37
  export interface MetaEventPayload {
38
38
  dataProcessingOptions: MetaDataProcessingOptions;
@@ -41,7 +41,9 @@ export interface MetaEventPayload {
41
41
  }
42
42
 
43
43
  /**
44
- * @since 1.0.0-canary.7
44
+ * Options for `createMetaDestination`.
45
+ *
46
+ * @since 0.5.0-canary.6
45
47
  */
46
48
  export interface MetaDestinationOptions {
47
49
  /**
@@ -68,7 +70,7 @@ export interface MetaDestinationOptions {
68
70
  * are the integrator's to supply. `consentRequirement` stays `"required"`: an ad sink is
69
71
  * never exempt.
70
72
  *
71
- * @since 1.0.0-canary.7
73
+ * @since 0.5.0-canary.6
72
74
  */
73
75
  export function createMetaDestination(options: MetaDestinationOptions): Destination {
74
76
  // Erasure halts delivery for the rest of the session — Meta has no per-visitor deletion API.
@@ -10,7 +10,7 @@ import { flattenEventProps } from "#/destinations/shared";
10
10
  * models the one enforced signal (spec-destinations §5). Pushed via
11
11
  * `uetq.push('consent','update', …)`.
12
12
  *
13
- * @since 1.0.0-canary.7
13
+ * @since 0.5.0-canary.6
14
14
  */
15
15
  export interface MicrosoftUetConsent {
16
16
  ad_storage: "denied" | "granted";
@@ -20,7 +20,7 @@ export interface MicrosoftUetConsent {
20
20
  * Maps a `ConsentDecision` to UET's enforced `ad_storage` signal via the shared ad lever, so
21
21
  * it can't drift from Meta/TikTok — `ad_storage` is the inverse of Limited Data Use.
22
22
  *
23
- * @since 1.0.0-canary.7
23
+ * @since 0.5.0-canary.6
24
24
  */
25
25
  export function toMicrosoftUetConsent(decision: ConsentDecision): MicrosoftUetConsent {
26
26
  return { ad_storage: toAdConsentState(decision).limitedDataUse ? "denied" : "granted" };
@@ -29,7 +29,7 @@ export function toMicrosoftUetConsent(decision: ConsentDecision): MicrosoftUetCo
29
29
  /**
30
30
  * The mapped per-event payload handed to a UET transport (`uetq.push`).
31
31
  *
32
- * @since 1.0.0-canary.7
32
+ * @since 0.5.0-canary.6
33
33
  */
34
34
  export interface MicrosoftUetEventPayload {
35
35
  consent: MicrosoftUetConsent;
@@ -38,7 +38,9 @@ export interface MicrosoftUetEventPayload {
38
38
  }
39
39
 
40
40
  /**
41
- * @since 1.0.0-canary.7
41
+ * Options for `createMicrosoftUetDestination`.
42
+ *
43
+ * @since 0.5.0-canary.6
42
44
  */
43
45
  export interface MicrosoftUetDestinationOptions {
44
46
  /** Erasure cookie-clear seam — UET exposes no per-visitor deletion API, so erasure is cookie-clear + stop-send (DSR-V4). */
@@ -59,7 +61,7 @@ export interface MicrosoftUetDestinationOptions {
59
61
  * mapping only — the tag id and `uetq` transport are the integrator's. `consentRequirement`
60
62
  * stays `"required"`.
61
63
  *
62
- * @since 1.0.0-canary.7
64
+ * @since 0.5.0-canary.6
63
65
  */
64
66
  export function createMicrosoftUetDestination(options: MicrosoftUetDestinationOptions): Destination {
65
67
  let stopped = false;
@@ -1,5 +1,7 @@
1
1
  /**
2
- * @since 1.0.0-canary.6
2
+ * A primitive value every destination accepts as an event parameter.
3
+ *
4
+ * @since 0.5.0-canary.6
3
5
  */
4
6
  export type FlatPropertyValue = boolean | number | string;
5
7
 
@@ -12,18 +14,22 @@ interface FlattenEventPropsOptions {
12
14
  * Event params must be flat string/number/boolean (optionally `null`) — stringify
13
15
  * anything else instead of letting the destination silently drop it.
14
16
  *
15
- * @since 1.0.0-canary.6
17
+ * @since 0.5.0-canary.6
16
18
  */
17
19
  export function flattenEventProps(properties: Record<string, unknown>): Record<string, FlatPropertyValue>;
18
20
  /**
19
- * @since 1.0.0-canary.6
21
+ * Flattens event properties while also passing `null` through for destinations that accept it.
22
+ *
23
+ * @since 0.5.0-canary.6
20
24
  */
21
25
  export function flattenEventProps(
22
26
  properties: Record<string, unknown>,
23
27
  options: { allowNull: true },
24
28
  ): Record<string, FlatPropertyValue | null>;
25
29
  /**
26
- * @since 1.0.0-canary.6
30
+ * Shared implementation backing both overloads.
31
+ *
32
+ * @since 0.5.0-canary.6
27
33
  */
28
34
  export function flattenEventProps(
29
35
  properties: Record<string, unknown>,
@@ -10,7 +10,7 @@ import { flattenEventProps } from "#/destinations/shared";
10
10
  * transmission gate (`ttq.grantConsent()`/`revokeConsent()`) follows `analytics` and is the
11
11
  * tracker's job; this models the `ads`-driven LDU lever.
12
12
  *
13
- * @since 1.0.0-canary.7
13
+ * @since 0.5.0-canary.6
14
14
  */
15
15
  export interface TiktokConsent {
16
16
  limited_data_use: boolean;
@@ -19,7 +19,7 @@ export interface TiktokConsent {
19
19
  /**
20
20
  * Maps a `ConsentDecision` to TikTok's LDU boolean — on when `ads` is denied.
21
21
  *
22
- * @since 1.0.0-canary.7
22
+ * @since 0.5.0-canary.6
23
23
  */
24
24
  export function toTiktokConsent(decision: ConsentDecision): TiktokConsent {
25
25
  return { limited_data_use: toAdConsentState(decision).limitedDataUse };
@@ -28,7 +28,7 @@ export function toTiktokConsent(decision: ConsentDecision): TiktokConsent {
28
28
  /**
29
29
  * The mapped per-event payload handed to a TikTok transport (`ttq.track` / Events API).
30
30
  *
31
- * @since 1.0.0-canary.7
31
+ * @since 0.5.0-canary.6
32
32
  */
33
33
  export interface TiktokEventPayload {
34
34
  consent: TiktokConsent;
@@ -37,7 +37,9 @@ export interface TiktokEventPayload {
37
37
  }
38
38
 
39
39
  /**
40
- * @since 1.0.0-canary.7
40
+ * Options for `createTiktokDestination`.
41
+ *
42
+ * @since 0.5.0-canary.6
41
43
  */
42
44
  export interface TiktokDestinationOptions {
43
45
  /** Erasure cookie-clear seam — TikTok exposes no per-visitor deletion API, so erasure is cookie-clear + stop-send (DSR-V4). */
@@ -58,7 +60,7 @@ export interface TiktokDestinationOptions {
58
60
  * only — the pixel id and `ttq` transport are the integrator's. `consentRequirement` stays
59
61
  * `"required"`.
60
62
  *
61
- * @since 1.0.0-canary.7
63
+ * @since 0.5.0-canary.6
62
64
  */
63
65
  export function createTiktokDestination(options: TiktokDestinationOptions): Destination {
64
66
  let stopped = false;
@@ -4,7 +4,9 @@ import type { Destination } from "#/core/destination";
4
4
  import { flattenEventProps } from "#/destinations/shared";
5
5
 
6
6
  /**
7
- * @since 1.0.0-canary.6
7
+ * Options for `createVercelAnalyticsDestination`.
8
+ *
9
+ * @since 0.5.0-canary.6
8
10
  */
9
11
  export interface VercelAnalyticsDestinationOptions {
10
12
  /**
@@ -1,7 +1,7 @@
1
1
  "use client";
2
2
 
3
3
  import type { ComponentProps, Dispatch, ReactNode, SetStateAction } from "react";
4
- import { createContext, useContext, useEffect, useState } from "react";
4
+ import { createContext, useContext, useState } from "react";
5
5
 
6
6
  import type { ConsentCategory, ConsentDecision } from "#/core/consent";
7
7
  import type { UseConsentResult } from "#/react/use-consent";
@@ -26,6 +26,8 @@ function useConsentBannerContext(part: string): ConsentBannerContextValue {
26
26
  }
27
27
 
28
28
  /**
29
+ * Props for {@link ConsentBanner}.
30
+ *
29
31
  * @since 0.5.0-canary.4
30
32
  */
31
33
  export interface ConsentBannerProps extends ComponentProps<"section"> {
@@ -49,18 +51,16 @@ export interface ConsentBannerProps extends ComponentProps<"section"> {
49
51
  * @since 0.5.0-canary.4
50
52
  */
51
53
  export function ConsentBanner({ children, consent, open, ...props }: ConsentBannerProps): ReactNode {
52
- const [pending, setPending] = useState<ConsentDecision | undefined>(undefined);
53
-
54
54
  const isVisible = open ?? consent.isPromptNeeded;
55
55
 
56
- // Closing must reset the layer — a reopened banner starts at the prompt, not mid-preferences.
57
- useEffect(() => {
58
- if (!isVisible) {
56
+ const [pending, setPending] = useState<ConsentDecision | undefined>(undefined);
57
+
58
+ if (!isVisible) {
59
+ // Closing resets the layer — a reopened banner starts at the prompt, not mid-preferences.
60
+ if (pending !== undefined) {
59
61
  setPending(undefined);
60
62
  }
61
- }, [isVisible]);
62
63
 
63
- if (!isVisible) {
64
64
  return null;
65
65
  }
66
66
 
@@ -79,11 +79,15 @@ export function ConsentBanner({ children, consent, open, ...props }: ConsentBann
79
79
  }
80
80
 
81
81
  /**
82
+ * Props for {@link ConsentBannerTitle}.
83
+ *
82
84
  * @since 0.5.0-canary.5
83
85
  */
84
86
  export interface ConsentBannerTitleProps extends ComponentProps<"h2"> {}
85
87
 
86
88
  /**
89
+ * Renders the banner's heading.
90
+ *
87
91
  * @since 0.5.0-canary.5
88
92
  */
89
93
  export function ConsentBannerTitle({ children, ...props }: ConsentBannerTitleProps): ReactNode {
@@ -95,6 +99,8 @@ export function ConsentBannerTitle({ children, ...props }: ConsentBannerTitlePro
95
99
  }
96
100
 
97
101
  /**
102
+ * Props for {@link ConsentBannerDescription}.
103
+ *
98
104
  * @since 0.5.0-canary.5
99
105
  */
100
106
  export interface ConsentBannerDescriptionProps extends ComponentProps<"p"> {}
@@ -109,11 +115,15 @@ export function ConsentBannerDescription(props: ConsentBannerDescriptionProps):
109
115
  }
110
116
 
111
117
  /**
118
+ * Props for {@link ConsentBannerActions}.
119
+ *
112
120
  * @since 0.5.0-canary.5
113
121
  */
114
122
  export interface ConsentBannerActionsProps extends ComponentProps<"div"> {}
115
123
 
116
124
  /**
125
+ * Renders the container grouping the banner's action buttons.
126
+ *
117
127
  * @since 0.5.0-canary.5
118
128
  */
119
129
  export function ConsentBannerActions(props: ConsentBannerActionsProps): ReactNode {
@@ -121,6 +131,8 @@ export function ConsentBannerActions(props: ConsentBannerActionsProps): ReactNod
121
131
  }
122
132
 
123
133
  /**
134
+ * Props for {@link ConsentBannerAccept}.
135
+ *
124
136
  * @since 0.5.0-canary.5
125
137
  */
126
138
  export interface ConsentBannerAcceptProps extends Omit<ComponentProps<"button">, "type"> {}
@@ -150,11 +162,15 @@ export function ConsentBannerAccept({ onClick, ...props }: ConsentBannerAcceptPr
150
162
  }
151
163
 
152
164
  /**
165
+ * Props for {@link ConsentBannerReject}.
166
+ *
153
167
  * @since 0.5.0-canary.5
154
168
  */
155
169
  export interface ConsentBannerRejectProps extends Omit<ComponentProps<"button">, "type"> {}
156
170
 
157
171
  /**
172
+ * Denies every category via the consent hook's `denyAll` — rejecting stays as easy as accepting.
173
+ *
158
174
  * @since 0.5.0-canary.5
159
175
  */
160
176
  export function ConsentBannerReject({ onClick, ...props }: ConsentBannerRejectProps): ReactNode {
@@ -177,6 +193,8 @@ export function ConsentBannerReject({ onClick, ...props }: ConsentBannerRejectPr
177
193
  }
178
194
 
179
195
  /**
196
+ * Props for {@link ConsentBannerCustomize}.
197
+ *
180
198
  * @since 0.5.0-canary.5
181
199
  */
182
200
  export interface ConsentBannerCustomizeProps extends Omit<ComponentProps<"button">, "type"> {}
@@ -211,6 +229,8 @@ export function ConsentBannerCustomize({ onClick, ...props }: ConsentBannerCusto
211
229
  }
212
230
 
213
231
  /**
232
+ * Props for {@link ConsentBannerPreferences}.
233
+ *
214
234
  * @since 0.5.0-canary.5
215
235
  */
216
236
  export interface ConsentBannerPreferencesProps extends ComponentProps<"div"> {}
@@ -231,6 +251,8 @@ export function ConsentBannerPreferences(props: ConsentBannerPreferencesProps):
231
251
  }
232
252
 
233
253
  /**
254
+ * Props for {@link ConsentBannerCategory}.
255
+ *
234
256
  * @since 0.5.0-canary.5
235
257
  */
236
258
  export interface ConsentBannerCategoryProps extends ComponentProps<"label"> {
@@ -265,6 +287,8 @@ export function ConsentBannerCategory({ category, children, ...props }: ConsentB
265
287
  }
266
288
 
267
289
  /**
290
+ * Props for {@link ConsentBannerSave}.
291
+ *
268
292
  * @since 0.5.0-canary.5
269
293
  */
270
294
  export interface ConsentBannerSaveProps extends Omit<ComponentProps<"button">, "type"> {}
@@ -298,6 +322,8 @@ export function ConsentBannerSave({ onClick, ...props }: ConsentBannerSaveProps)
298
322
  }
299
323
 
300
324
  /**
325
+ * Props for {@link ConsentToggle}.
326
+ *
301
327
  * @since 0.5.0-canary.4
302
328
  */
303
329
  export interface ConsentToggleProps extends Omit<ComponentProps<"button">, "children" | "onClick" | "type"> {
@@ -4,7 +4,9 @@ import type { GtagConsentBootstrapOptions } from "#/destinations/google-analytic
4
4
  import { buildGtagConsentBootstrapScript } from "#/destinations/google-analytics";
5
5
 
6
6
  /**
7
- * @since 1.0.0-canary.6
7
+ * Props for {@link GtagConsentBootstrap}.
8
+ *
9
+ * @since 0.5.0-canary.6
8
10
  */
9
11
  export interface GtagConsentBootstrapProps
10
12
  extends
@@ -17,7 +19,7 @@ export interface GtagConsentBootstrapProps
17
19
  * only sets the attribute on the host script — the generated source also stamps it onto
18
20
  * the injected gtag.js tag when `nonce` is provided.
19
21
  *
20
- * @since 1.0.0-canary.6
22
+ * @since 0.5.0-canary.6
21
23
  */
22
24
  export function GtagConsentBootstrap({
23
25
  config,
@@ -7,6 +7,8 @@ import { CONSENT_CATEGORIES, createConsentDecision, readStoredDecision, resolveD
7
7
  import type { ConsentConfig } from "#/core/consent-config";
8
8
 
9
9
  /**
10
+ * Options for `useConsent`.
11
+ *
10
12
  * @since 0.5.0-canary.4
11
13
  */
12
14
  export interface UseConsentOptions {
@@ -20,6 +22,8 @@ export interface UseConsentOptions {
20
22
  }
21
23
 
22
24
  /**
25
+ * The live consent state and decision actions returned by `useConsent`.
26
+ *
23
27
  * @since 0.5.0-canary.4
24
28
  */
25
29
  export interface UseConsentResult {
@@ -6,7 +6,9 @@ import { updateGoogleConsent } from "#/destinations/google-analytics";
6
6
  import type { UseConsentResult } from "#/react/use-consent";
7
7
 
8
8
  /**
9
- * @since 1.0.0-canary.6
9
+ * Options for `useGoogleConsentSync`.
10
+ *
11
+ * @since 0.5.0-canary.6
10
12
  */
11
13
  export interface UseGoogleConsentSyncOptions {
12
14
  /**
@@ -21,7 +23,7 @@ export interface UseGoogleConsentSyncOptions {
21
23
  * decision exists (including cross-tab / privacy-page saves), and optionally loads gtag
22
24
  * when analytics is effective. Mount once on a page-wide surface (e.g. the footer gate).
23
25
  *
24
- * @since 1.0.0-canary.6
26
+ * @since 0.5.0-canary.6
25
27
  */
26
28
  export function useGoogleConsentSync(consent: UseConsentResult, options: UseGoogleConsentSyncOptions = {}): void {
27
29
  const { loadGtagScript } = options;
@@ -10,7 +10,7 @@ import type { InitialConsentSnapshot, InitialConsentStore } from "#/client/initi
10
10
  * answers. SSR and the first client render read the strictest snapshot, so hydration can
11
11
  * never mismatch on region.
12
12
  *
13
- * @since 1.0.0-canary.6
13
+ * @since 0.5.0-canary.6
14
14
  */
15
15
  export function useInitialConsent(store: InitialConsentStore): InitialConsentSnapshot {
16
16
  // Post-hydration safety net — idempotent with an earlier, pre-hydration kick.
@@ -11,7 +11,7 @@ const COOKIE_NAME_PATTERN = /^[\w-]+$/;
11
11
  *
12
12
  * @throws Error when `cookieName` is not a valid token.
13
13
  *
14
- * @since 1.0.0-canary.7
14
+ * @since 0.5.0-canary.6
15
15
  */
16
16
  export function assertValidAnonymousIdCookieName(cookieName: string): void {
17
17
  if (!COOKIE_NAME_PATTERN.test(cookieName)) {
@@ -24,14 +24,16 @@ export function assertValidAnonymousIdCookieName(cookieName: string): void {
24
24
  * writes its input into a `Set-Cookie`, so only an exactly-UUID-shaped value may pass —
25
25
  * anything else is a header-injection attempt or corruption, never a valid id.
26
26
  *
27
- * @since 1.0.0-canary.6
27
+ * @since 0.5.0-canary.6
28
28
  */
29
29
  export function isValidAnonymousId(value: string): boolean {
30
30
  return UUID_PATTERN.test(value);
31
31
  }
32
32
 
33
33
  /**
34
- * @since 1.0.0-canary.6
34
+ * Options for persisting a client-minted anonymous id via a server `Set-Cookie`.
35
+ *
36
+ * @since 0.5.0-canary.6
35
37
  */
36
38
  export interface AnonymousIdCookieOptions {
37
39
  /** Cookie name — must match what the client tracker reads. */
@@ -56,7 +58,7 @@ export interface AnonymousIdCookieOptions {
56
58
  *
57
59
  * @throws Error when `id` is not UUID-shaped or `cookieName` is not a valid token.
58
60
  *
59
- * @since 1.0.0-canary.6
61
+ * @since 0.5.0-canary.6
60
62
  */
61
63
  export function resolveAnonymousIdCookie(options: AnonymousIdCookieOptions): {
62
64
  maxAge: number;
@@ -89,7 +91,7 @@ export function resolveAnonymousIdCookie(options: AnonymousIdCookieOptions): {
89
91
  *
90
92
  * @throws Error when `cookieName` is not a valid token.
91
93
  *
92
- * @since 1.0.0-canary.6
94
+ * @since 0.5.0-canary.6
93
95
  */
94
96
  export function resolveClearAnonymousIdCookie(cookieName: string): {
95
97
  name: string;
@@ -6,7 +6,7 @@ import type { ConsentReceipt } from "#/core/consent-receipt";
6
6
  * and an update/withdrawal is a new receipt referencing the prior one (spec-consent-receipts §3).
7
7
  * May be async so a real backend can await its write.
8
8
  *
9
- * @since 1.0.0-canary.7
9
+ * @since 0.5.0-canary.6
10
10
  */
11
11
  export interface ReceiptStore {
12
12
  append: (receipt: ConsentReceipt) => Promise<void> | void;
@@ -23,7 +23,7 @@ export interface ReceiptStore {
23
23
  * Append is idempotent-by-id: re-appending the same `receiptId` is ignored, preserving the
24
24
  * append-only guarantee even if a client retries.
25
25
  *
26
- * @since 1.0.0-canary.7
26
+ * @since 0.5.0-canary.6
27
27
  */
28
28
  export function createInMemoryReceiptStore(): ReceiptStore {
29
29
  const receipts = new Map<string, ConsentReceipt>();
@@ -45,7 +45,7 @@ export function createInMemoryReceiptStore(): ReceiptStore {
45
45
  * Keeping it this small lets an integrator back receipts with any store (Vercel KV, Postgres,
46
46
  * an append-only log) by implementing two methods rather than the full {@link ReceiptStore}.
47
47
  *
48
- * @since 1.0.0-canary.7
48
+ * @since 0.5.0-canary.6
49
49
  */
50
50
  export interface ReceiptStoreBackend {
51
51
  get: (receiptId: string) => Promise<ConsentReceipt | undefined>;
@@ -65,7 +65,7 @@ export interface ReceiptStoreBackend {
65
65
  * client (no database dependency is baked in). Pair it with a real backend in production,
66
66
  * where {@link createInMemoryReceiptStore} is not a lawful store on its own.
67
67
  *
68
- * @since 1.0.0-canary.7
68
+ * @since 0.5.0-canary.6
69
69
  */
70
70
  export function createDurableReceiptStore(options: { backend: ReceiptStoreBackend }): ReceiptStore {
71
71
  return {
@@ -4,7 +4,7 @@ import type { ConsentReceipt, ConsentReceiptInput } from "#/core/consent-receipt
4
4
  * The receipt information-structure version this builder emits (ISO/IEC TS 27560-shaped).
5
5
  * Bump when the receipt field set changes; stored receipts carry it so a reader can migrate.
6
6
  *
7
- * @since 1.0.0-canary.7
7
+ * @since 0.5.0-canary.6
8
8
  */
9
9
  export const RECEIPT_SCHEMA_VERSION = "1.0.0";
10
10
 
@@ -17,7 +17,7 @@ const IPV4_PATTERN = /^(\d{1,3}\.){3}\d{1,3}$/;
17
17
  * a controller may widen it under counsel, but the builder never returns a full address.
18
18
  * Returns `undefined` for a missing or malformed input rather than storing a bad value.
19
19
  *
20
- * @since 1.0.0-canary.7
20
+ * @since 0.5.0-canary.6
21
21
  */
22
22
  export function coarsenIp(ip: string | null | undefined): string | undefined {
23
23
  if (!ip) {
@@ -58,7 +58,7 @@ export function coarsenIp(ip: string | null | undefined): string | undefined {
58
58
  * function to stamp an `integrityKey`, letting a client prove its state matches the stored
59
59
  * original (spec-consent-receipts §5). Omit it and receipts carry no integrity key.
60
60
  *
61
- * @since 1.0.0-canary.7
61
+ * @since 0.5.0-canary.6
62
62
  */
63
63
  export interface BuildConsentReceiptOptions {
64
64
  input: ConsentReceiptInput;
@@ -72,7 +72,7 @@ export interface BuildConsentReceiptOptions {
72
72
  * (`receiptId`, `timestamp`, coarsened IP, optional `integrityKey`). Pure except for the
73
73
  * id/clock it stamps — pass those in via a seam if a deterministic build is needed.
74
74
  *
75
- * @since 1.0.0-canary.7
75
+ * @since 0.5.0-canary.6
76
76
  */
77
77
  export function buildConsentReceipt(options: BuildConsentReceiptOptions): ConsentReceipt {
78
78
  const base: Omit<ConsentReceipt, "integrityKey"> = {