@codefast/tracking 0.5.0-canary.4 → 1.0.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 (134) hide show
  1. package/CHANGELOG.md +171 -0
  2. package/README.md +123 -96
  3. package/dist/client/browser-cookie.d.mts +11 -0
  4. package/dist/client/browser-cookie.mjs +15 -0
  5. package/dist/client/consent-runtime.d.mts +56 -0
  6. package/dist/client/consent-runtime.mjs +35 -0
  7. package/dist/client/consent-storage.d.mts +5 -0
  8. package/dist/client/consent-storage.mjs +20 -1
  9. package/dist/client/consent-withdrawal.d.mts +21 -0
  10. package/dist/client/consent-withdrawal.mjs +17 -0
  11. package/dist/client/cookie-anonymous-id.d.mts +37 -0
  12. package/dist/client/cookie-anonymous-id.mjs +46 -0
  13. package/dist/client/create-client-tracker.d.mts +11 -16
  14. package/dist/client/create-client-tracker.mjs +27 -53
  15. package/dist/client/gpc.d.mts +2 -0
  16. package/dist/client/gpc.mjs +3 -1
  17. package/dist/client/index.d.mts +7 -5
  18. package/dist/client/index.mjs +8 -6
  19. package/dist/client/initial-consent-store.d.mts +66 -0
  20. package/dist/client/initial-consent-store.mjs +119 -0
  21. package/dist/client/is-analytics-allowed.d.mts +29 -0
  22. package/dist/client/is-analytics-allowed.mjs +23 -0
  23. package/dist/client/server-persisted-anonymous-id.d.mts +33 -0
  24. package/dist/client/server-persisted-anonymous-id.mjs +50 -0
  25. package/dist/core/consent-config.d.mts +27 -0
  26. package/dist/core/consent-config.mjs +11 -0
  27. package/dist/core/consent.d.mts +99 -4
  28. package/dist/core/consent.mjs +99 -4
  29. package/dist/core/cookie.d.mts +17 -0
  30. package/dist/core/cookie.mjs +23 -0
  31. package/dist/core/destination.d.mts +10 -8
  32. package/dist/core/event-catalog.d.mts +16 -13
  33. package/dist/core/event-catalog.mjs +19 -1
  34. package/dist/core/event-id.d.mts +1 -2
  35. package/dist/core/event-id.mjs +1 -2
  36. package/dist/core/index.d.mts +6 -4
  37. package/dist/core/index.mjs +5 -3
  38. package/dist/core/tracked-event.d.mts +21 -8
  39. package/dist/destinations/google-analytics.d.mts +100 -48
  40. package/dist/destinations/google-analytics.mjs +89 -85
  41. package/dist/destinations/google-consent.d.mts +64 -0
  42. package/dist/destinations/google-consent.mjs +102 -0
  43. package/dist/destinations/index.d.mts +2 -5
  44. package/dist/destinations/index.mjs +2 -5
  45. package/dist/destinations/shared.d.mts +20 -0
  46. package/dist/destinations/shared.mjs +13 -0
  47. package/dist/destinations/vercel-analytics.d.mts +19 -4
  48. package/dist/destinations/vercel-analytics.mjs +11 -18
  49. package/dist/import-protection.d.mts +19 -0
  50. package/dist/import-protection.mjs +23 -0
  51. package/dist/index.d.mts +6 -4
  52. package/dist/index.mjs +5 -3
  53. package/dist/react/consent-banner.d.mts +143 -38
  54. package/dist/react/consent-banner.mjs +192 -92
  55. package/dist/react/gtag-consent-bootstrap.d.mts +27 -0
  56. package/dist/react/gtag-consent-bootstrap.mjs +29 -0
  57. package/dist/react/index.d.mts +5 -2
  58. package/dist/react/index.mjs +5 -2
  59. package/dist/react/use-consent.d.mts +9 -13
  60. package/dist/react/use-consent.mjs +42 -25
  61. package/dist/react/use-google-consent-sync.d.mts +23 -0
  62. package/dist/react/use-google-consent-sync.mjs +24 -0
  63. package/dist/react/use-initial-consent.d.mts +14 -0
  64. package/dist/react/use-initial-consent.mjs +19 -0
  65. package/dist/server/anonymous-id-cookie.d.mts +46 -0
  66. package/dist/server/anonymous-id-cookie.mjs +51 -0
  67. package/dist/server/index.d.mts +5 -3
  68. package/dist/server/index.mjs +4 -3
  69. package/dist/server/initial-consent.d.mts +29 -0
  70. package/dist/server/initial-consent.mjs +31 -0
  71. package/dist/server/region.d.mts +21 -4
  72. package/dist/server/region.mjs +26 -5
  73. package/dist/tanstack-start/index.d.mts +58 -0
  74. package/dist/tanstack-start/index.mjs +45 -0
  75. package/package.json +27 -110
  76. package/src/client/browser-cookie.ts +16 -0
  77. package/src/client/consent-runtime.ts +80 -0
  78. package/src/client/consent-storage.ts +31 -1
  79. package/src/client/consent-withdrawal.ts +32 -0
  80. package/src/client/cookie-anonymous-id.ts +93 -0
  81. package/src/client/create-client-tracker.ts +56 -85
  82. package/src/client/gpc.ts +4 -2
  83. package/src/client/index.ts +19 -8
  84. package/src/client/initial-consent-store.ts +218 -0
  85. package/src/client/is-analytics-allowed.ts +43 -0
  86. package/src/client/server-persisted-anonymous-id.ts +99 -0
  87. package/src/core/consent-config.ts +27 -0
  88. package/src/core/consent.ts +164 -10
  89. package/src/core/cookie.ts +29 -0
  90. package/src/core/destination.ts +10 -8
  91. package/src/core/event-catalog.ts +28 -15
  92. package/src/core/event-id.ts +1 -2
  93. package/src/core/index.ts +19 -3
  94. package/src/core/tracked-event.ts +22 -7
  95. package/src/css/consent.css +119 -0
  96. package/src/destinations/google-analytics.ts +196 -133
  97. package/src/destinations/google-consent.ts +164 -0
  98. package/src/destinations/index.ts +14 -15
  99. package/src/destinations/shared.ts +45 -0
  100. package/src/destinations/vercel-analytics.ts +23 -24
  101. package/src/import-protection.ts +20 -0
  102. package/src/index.ts +46 -8
  103. package/src/react/consent-banner.tsx +308 -111
  104. package/src/react/gtag-consent-bootstrap.tsx +48 -0
  105. package/src/react/index.ts +34 -2
  106. package/src/react/use-consent.ts +53 -45
  107. package/src/react/use-google-consent-sync.ts +38 -0
  108. package/src/react/use-initial-consent.ts +22 -0
  109. package/src/server/anonymous-id-cookie.ts +76 -0
  110. package/src/server/index.ts +15 -3
  111. package/src/server/initial-consent.ts +48 -0
  112. package/src/server/region.ts +22 -5
  113. package/src/tanstack-start/index.ts +83 -0
  114. package/dist/client/lifecycle.d.mts +0 -23
  115. package/dist/client/lifecycle.mjs +0 -30
  116. package/dist/client/local-storage.d.mts +0 -13
  117. package/dist/client/local-storage.mjs +0 -31
  118. package/dist/client/queue.d.mts +0 -49
  119. package/dist/client/queue.mjs +0 -71
  120. package/dist/client/router.d.mts +0 -30
  121. package/dist/client/router.mjs +0 -17
  122. package/dist/destinations/ga4-measurement-protocol.d.mts +0 -54
  123. package/dist/destinations/ga4-measurement-protocol.mjs +0 -89
  124. package/dist/destinations/http-destination.d.mts +0 -20
  125. package/dist/destinations/http-destination.mjs +0 -25
  126. package/dist/server/create-server-tracker.d.mts +0 -42
  127. package/dist/server/create-server-tracker.mjs +0 -67
  128. package/src/client/lifecycle.ts +0 -50
  129. package/src/client/local-storage.ts +0 -44
  130. package/src/client/queue.ts +0 -117
  131. package/src/client/router.ts +0 -37
  132. package/src/destinations/ga4-measurement-protocol.ts +0 -166
  133. package/src/destinations/http-destination.ts +0 -33
  134. package/src/server/create-server-tracker.ts +0 -128
@@ -1,114 +1,214 @@
1
- import { CONSENT_CATEGORIES } from "../core/consent.mjs";
2
- import { useState } from "react";
3
- import { Fragment, jsx, jsxs } from "react/jsx-runtime";
1
+ "use client";
2
+ import { createContext, useContext, useEffect, useState } from "react";
3
+ import { jsx, jsxs } from "react/jsx-runtime";
4
4
  //#region src/react/consent-banner.tsx
5
+ const ConsentBannerContext = createContext(null);
6
+ function useConsentBannerContext(part) {
7
+ const context = useContext(ConsentBannerContext);
8
+ if (context === null) throw new Error(`\`${part}\` must be rendered inside \`ConsentBanner\``);
9
+ return context;
10
+ }
5
11
  /**
6
- * Non-blocking opt-in prompt for GDPR/NĐ 13 regions — renders nothing once a decision
7
- * exists or the region defaults to opt-out (`consent.needsPrompt` covers both). Accept
8
- * grants only the categories the app requested (`useConsent`'s `categories`), and the
9
- * optional `categories` prop adds a second layer of per-category checkboxes — GDPR
10
- * consent must be granular per purpose, not a single yes/no. Rendered as a labeled
11
- * region, not a `<dialog>`: an open non-modal dialog neither traps focus nor blocks the
12
- * page, so the dialog semantics would over-promise. No styling is baked in — target the
13
- * root via `className` and the parts via their `data-slot` attributes (`consent-message`,
14
- * `consent-actions`, `consent-action`, `consent-preferences`, `consent-category`).
12
+ * Non-blocking opt-in prompt for GDPR/PDPL (VN) regions, as composable parts — the root owns
13
+ * the visibility gating and the preferences-layer state; the `Accept`/`Reject`/`Customize`/
14
+ * `Save` parts wire their own clicks to the consent hook, so any markup (including a
15
+ * design system's button styles via `className`) slots in. Renders nothing once a decision
16
+ * exists or the region defaults to opt-out (`consent.isPromptNeeded`), unless `open` says
17
+ * otherwise. Rendered as a labeled region, not a `<dialog>`: an open non-modal dialog
18
+ * neither traps focus nor blocks the page, so the dialog semantics would over-promise.
19
+ * Unstyled by default — style via `className`/`data-slot` selectors, or import the
20
+ * optional `@codefast/tracking/css/consent.css` theme. `data-state` on the root flips
21
+ * between `prompt` and `preferences` for state-dependent styling.
15
22
  *
16
23
  * @since 0.5.0-canary.4
17
24
  */
18
- function ConsentBanner({ acceptLabel = "Accept", categories, consent, customizeLabel = "Customize", message = "We use cookies to understand how you use this site.", rejectLabel = "Reject", saveLabel = "Save preferences", ...props }) {
25
+ function ConsentBanner({ children, consent, open, ...props }) {
19
26
  const [pending, setPending] = useState(void 0);
20
- if (!consent.needsPrompt) return null;
21
- return /* @__PURE__ */ jsxs("section", {
22
- "aria-label": "Cookie consent",
23
- "data-slot": "consent-banner",
27
+ const isVisible = open ?? consent.isPromptNeeded;
28
+ useEffect(() => {
29
+ if (!isVisible) setPending(void 0);
30
+ }, [isVisible]);
31
+ if (!isVisible) return null;
32
+ return /* @__PURE__ */ jsx(ConsentBannerContext.Provider, {
33
+ value: {
34
+ consent,
35
+ pending,
36
+ setPending
37
+ },
38
+ children: /* @__PURE__ */ jsx("section", {
39
+ "aria-label": "Cookie consent",
40
+ "data-slot": "consent-banner",
41
+ "data-state": pending === void 0 ? "prompt" : "preferences",
42
+ ...props,
43
+ children
44
+ })
45
+ });
46
+ }
47
+ /**
48
+ * @since 0.5.0-canary.5
49
+ */
50
+ function ConsentBannerTitle({ children, ...props }) {
51
+ return /* @__PURE__ */ jsx("h2", {
52
+ "data-slot": "consent-title",
53
+ ...props,
54
+ children
55
+ });
56
+ }
57
+ /**
58
+ * Hosts the message and the privacy-policy link informed consent requires.
59
+ *
60
+ * @since 0.5.0-canary.5
61
+ */
62
+ function ConsentBannerDescription(props) {
63
+ return /* @__PURE__ */ jsx("p", {
64
+ "data-slot": "consent-description",
65
+ ...props
66
+ });
67
+ }
68
+ /**
69
+ * @since 0.5.0-canary.5
70
+ */
71
+ function ConsentBannerActions(props) {
72
+ return /* @__PURE__ */ jsx("div", {
73
+ "data-slot": "consent-actions",
74
+ ...props
75
+ });
76
+ }
77
+ /**
78
+ * Grants the categories the app requested (`useConsent`'s `requestedCategories`) — never more.
79
+ *
80
+ * @since 0.5.0-canary.5
81
+ */
82
+ function ConsentBannerAccept({ onClick, ...props }) {
83
+ const { consent, setPending } = useConsentBannerContext("ConsentBannerAccept");
84
+ return /* @__PURE__ */ jsx("button", {
85
+ "data-action": "accept",
86
+ "data-slot": "consent-action",
87
+ ...props,
88
+ onClick: (event) => {
89
+ onClick?.(event);
90
+ consent.grantAll();
91
+ setPending(void 0);
92
+ },
93
+ type: "button"
94
+ });
95
+ }
96
+ /**
97
+ * @since 0.5.0-canary.5
98
+ */
99
+ function ConsentBannerReject({ onClick, ...props }) {
100
+ const { consent, setPending } = useConsentBannerContext("ConsentBannerReject");
101
+ return /* @__PURE__ */ jsx("button", {
102
+ "data-action": "reject",
103
+ "data-slot": "consent-action",
104
+ ...props,
105
+ onClick: (event) => {
106
+ onClick?.(event);
107
+ consent.denyAll();
108
+ setPending(void 0);
109
+ },
110
+ type: "button"
111
+ });
112
+ }
113
+ /**
114
+ * Opens the per-category preferences layer, starting from the current effective state so
115
+ * nothing arrives pre-ticked in an opt-in region (pre-ticked consent is invalid under
116
+ * GDPR). Hidden while the layer is open — `ConsentBannerSave` takes over.
117
+ *
118
+ * @since 0.5.0-canary.5
119
+ */
120
+ function ConsentBannerCustomize({ onClick, ...props }) {
121
+ const { consent, pending, setPending } = useConsentBannerContext("ConsentBannerCustomize");
122
+ if (pending !== void 0) return null;
123
+ return /* @__PURE__ */ jsx("button", {
124
+ "data-action": "customize",
125
+ "data-slot": "consent-action",
126
+ ...props,
127
+ onClick: (event) => {
128
+ onClick?.(event);
129
+ setPending(consent.effectiveConsent);
130
+ },
131
+ type: "button"
132
+ });
133
+ }
134
+ /**
135
+ * Container for the per-category rows — renders only while the preferences layer is open.
136
+ *
137
+ * @since 0.5.0-canary.5
138
+ */
139
+ function ConsentBannerPreferences(props) {
140
+ const { pending } = useConsentBannerContext("ConsentBannerPreferences");
141
+ if (pending === void 0) return null;
142
+ return /* @__PURE__ */ jsx("div", {
143
+ "data-slot": "consent-preferences",
144
+ ...props
145
+ });
146
+ }
147
+ /**
148
+ * One checkbox row of the preferences layer — `children` is the visitor-facing wording.
149
+ *
150
+ * @since 0.5.0-canary.5
151
+ */
152
+ function ConsentBannerCategory({ category, children, ...props }) {
153
+ const { pending, setPending } = useConsentBannerContext("ConsentBannerCategory");
154
+ if (pending === void 0) return null;
155
+ return /* @__PURE__ */ jsxs("label", {
156
+ "data-slot": "consent-category",
157
+ ...props,
158
+ children: [/* @__PURE__ */ jsx("input", {
159
+ checked: pending[category],
160
+ "data-slot": "consent-category-checkbox",
161
+ onChange: (event) => {
162
+ setPending({
163
+ ...pending,
164
+ [category]: event.target.checked
165
+ });
166
+ },
167
+ type: "checkbox"
168
+ }), children]
169
+ });
170
+ }
171
+ /**
172
+ * Persists the pending per-category selection — renders only while the preferences layer is open.
173
+ *
174
+ * @since 0.5.0-canary.5
175
+ */
176
+ function ConsentBannerSave({ onClick, ...props }) {
177
+ const { consent, pending, setPending } = useConsentBannerContext("ConsentBannerSave");
178
+ if (pending === void 0) return null;
179
+ return /* @__PURE__ */ jsx("button", {
180
+ "data-action": "save",
181
+ "data-slot": "consent-action",
24
182
  ...props,
25
- children: [
26
- /* @__PURE__ */ jsx("p", {
27
- "data-slot": "consent-message",
28
- children: message
29
- }),
30
- pending !== void 0 && categories !== void 0 ? /* @__PURE__ */ jsx("div", {
31
- "data-slot": "consent-preferences",
32
- children: categories.map((option) => /* @__PURE__ */ jsxs("label", {
33
- "data-slot": "consent-category",
34
- children: [
35
- /* @__PURE__ */ jsx("input", {
36
- checked: pending[option.category],
37
- "data-slot": "consent-category-checkbox",
38
- onChange: (event) => {
39
- setPending({
40
- ...pending,
41
- [option.category]: event.target.checked
42
- });
43
- },
44
- type: "checkbox"
45
- }),
46
- /* @__PURE__ */ jsx("span", {
47
- "data-slot": "consent-category-label",
48
- children: option.label
49
- }),
50
- option.description === void 0 ? null : /* @__PURE__ */ jsx("span", {
51
- "data-slot": "consent-category-description",
52
- children: option.description
53
- })
54
- ]
55
- }, option.category))
56
- }) : null,
57
- /* @__PURE__ */ jsx("div", {
58
- "data-slot": "consent-actions",
59
- children: pending === void 0 ? /* @__PURE__ */ jsxs(Fragment, { children: [
60
- /* @__PURE__ */ jsx("button", {
61
- "data-action": "accept",
62
- "data-slot": "consent-action",
63
- onClick: consent.grantAll,
64
- type: "button",
65
- children: acceptLabel
66
- }),
67
- /* @__PURE__ */ jsx("button", {
68
- "data-action": "reject",
69
- "data-slot": "consent-action",
70
- onClick: consent.denyAll,
71
- type: "button",
72
- children: rejectLabel
73
- }),
74
- categories !== void 0 && categories.length > 0 ? /* @__PURE__ */ jsx("button", {
75
- "data-action": "customize",
76
- "data-slot": "consent-action",
77
- onClick: () => {
78
- setPending(consent.effectiveConsent);
79
- },
80
- type: "button",
81
- children: customizeLabel
82
- }) : null
83
- ] }) : /* @__PURE__ */ jsx("button", {
84
- "data-action": "save",
85
- "data-slot": "consent-action",
86
- onClick: () => {
87
- consent.save(pending);
88
- },
89
- type: "button",
90
- children: saveLabel
91
- })
92
- })
93
- ]
183
+ onClick: (event) => {
184
+ onClick?.(event);
185
+ consent.saveDecision(pending);
186
+ setPending(void 0);
187
+ },
188
+ type: "button"
94
189
  });
95
190
  }
96
191
  /**
97
192
  * Always-visible control for opt-out regions — CCPA/CPRA requires a persistent
98
193
  * "Do Not Sell or Share My Personal Information" mechanism, not just a one-time prompt.
99
- * Flips between denying everything and re-granting the app's requested categories.
194
+ * By default it only flips `ads` (same scope as a GPC signal); pass `toggledCategories`
195
+ * to include analytics or both.
100
196
  *
101
197
  * @since 0.5.0-canary.4
102
198
  */
103
- function ConsentToggle({ allowLabel = "Allow tracking", consent, denyLabel = "Do Not Sell or Share My Personal Information", ...props }) {
104
- const anyAllowed = CONSENT_CATEGORIES.some((category) => consent.effectiveConsent[category]);
199
+ function ConsentToggle({ allowLabel = "Allow tracking", consent, denyLabel = "Do Not Sell or Share My Personal Information", toggledCategories = ["ads"], ...props }) {
200
+ const isAnyCategoryGranted = toggledCategories.some((category) => consent.effectiveConsent[category]);
105
201
  return /* @__PURE__ */ jsx("button", {
106
202
  "data-slot": "consent-toggle",
107
203
  ...props,
108
- onClick: anyAllowed ? consent.denyAll : consent.grantAll,
204
+ onClick: () => {
205
+ const next = { ...consent.effectiveConsent };
206
+ for (const category of toggledCategories) next[category] = !isAnyCategoryGranted;
207
+ consent.saveDecision(next);
208
+ },
109
209
  type: "button",
110
- children: anyAllowed ? denyLabel : allowLabel
210
+ children: isAnyCategoryGranted ? denyLabel : allowLabel
111
211
  });
112
212
  }
113
213
  //#endregion
114
- export { ConsentBanner, ConsentToggle };
214
+ export { ConsentBanner, ConsentBannerAccept, ConsentBannerActions, ConsentBannerCategory, ConsentBannerCustomize, ConsentBannerDescription, ConsentBannerPreferences, ConsentBannerReject, ConsentBannerSave, ConsentBannerTitle, ConsentToggle };
@@ -0,0 +1,27 @@
1
+ import { GtagConsentBootstrapOptions } from "../destinations/google-analytics.mjs";
2
+ import { ComponentProps, ReactNode } from "react";
3
+
4
+ //#region src/react/gtag-consent-bootstrap.d.ts
5
+ /**
6
+ * @since 1.0.0-canary.6
7
+ */
8
+ interface GtagConsentBootstrapProps extends Omit<ComponentProps<"script">, "children" | "dangerouslySetInnerHTML" | "nonce" | "src" | "type">, GtagConsentBootstrapOptions {}
9
+ /**
10
+ * Framework-agnostic inline `<script>` that runs `buildGtagConsentBootstrapScript` before
11
+ * hydration. Pass the same `nonce` here and in `loadGtagScript` for CSP; this component
12
+ * only sets the attribute on the host script — the generated source also stamps it onto
13
+ * the injected gtag.js tag when `nonce` is provided.
14
+ *
15
+ * @since 1.0.0-canary.6
16
+ */
17
+ declare function GtagConsentBootstrap({
18
+ config,
19
+ dataLayerName,
20
+ defaultConsent,
21
+ debugMode,
22
+ gaMeasurementId,
23
+ nonce,
24
+ ...props
25
+ }: GtagConsentBootstrapProps): ReactNode;
26
+ //#endregion
27
+ export { GtagConsentBootstrap, GtagConsentBootstrapProps };
@@ -0,0 +1,29 @@
1
+ import { buildGtagConsentBootstrapScript } from "../destinations/google-analytics.mjs";
2
+ import { jsx } from "react/jsx-runtime";
3
+ //#region src/react/gtag-consent-bootstrap.tsx
4
+ /**
5
+ * Framework-agnostic inline `<script>` that runs `buildGtagConsentBootstrapScript` before
6
+ * hydration. Pass the same `nonce` here and in `loadGtagScript` for CSP; this component
7
+ * only sets the attribute on the host script — the generated source also stamps it onto
8
+ * the injected gtag.js tag when `nonce` is provided.
9
+ *
10
+ * @since 1.0.0-canary.6
11
+ */
12
+ function GtagConsentBootstrap({ config, dataLayerName, defaultConsent, debugMode, gaMeasurementId, nonce, ...props }) {
13
+ const bootstrapOptions = {
14
+ config,
15
+ defaultConsent,
16
+ gaMeasurementId,
17
+ ...dataLayerName === void 0 ? {} : { dataLayerName },
18
+ ...debugMode === void 0 ? {} : { debugMode },
19
+ ...nonce === void 0 ? {} : { nonce }
20
+ };
21
+ return /* @__PURE__ */ jsx("script", {
22
+ ...props,
23
+ dangerouslySetInnerHTML: { __html: buildGtagConsentBootstrapScript(bootstrapOptions) },
24
+ ...nonce === void 0 ? {} : { nonce },
25
+ suppressHydrationWarning: true
26
+ });
27
+ }
28
+ //#endregion
29
+ export { GtagConsentBootstrap };
@@ -1,3 +1,6 @@
1
1
  import { UseConsentOptions, UseConsentResult, useConsent } from "./use-consent.mjs";
2
- import { ConsentBanner, ConsentBannerProps, ConsentCategoryOption, ConsentToggle, ConsentToggleProps } from "./consent-banner.mjs";
3
- export { ConsentBanner, type ConsentBannerProps, type ConsentCategoryOption, ConsentToggle, type ConsentToggleProps, type UseConsentOptions, type UseConsentResult, useConsent };
2
+ import { ConsentBanner, ConsentBannerAccept, ConsentBannerAcceptProps, ConsentBannerActions, ConsentBannerActionsProps, ConsentBannerCategory, ConsentBannerCategoryProps, ConsentBannerCustomize, ConsentBannerCustomizeProps, ConsentBannerDescription, ConsentBannerDescriptionProps, ConsentBannerPreferences, ConsentBannerPreferencesProps, ConsentBannerProps, ConsentBannerReject, ConsentBannerRejectProps, ConsentBannerSave, ConsentBannerSaveProps, ConsentBannerTitle, ConsentBannerTitleProps, ConsentToggle, ConsentToggleProps } from "./consent-banner.mjs";
3
+ import { GtagConsentBootstrap, GtagConsentBootstrapProps } from "./gtag-consent-bootstrap.mjs";
4
+ import { useInitialConsent } from "./use-initial-consent.mjs";
5
+ import { UseGoogleConsentSyncOptions, useGoogleConsentSync } from "./use-google-consent-sync.mjs";
6
+ export { ConsentBanner, ConsentBannerAccept, type ConsentBannerAcceptProps, ConsentBannerActions, type ConsentBannerActionsProps, ConsentBannerCategory, type ConsentBannerCategoryProps, ConsentBannerCustomize, type ConsentBannerCustomizeProps, ConsentBannerDescription, type ConsentBannerDescriptionProps, ConsentBannerPreferences, type ConsentBannerPreferencesProps, type ConsentBannerProps, ConsentBannerReject, type ConsentBannerRejectProps, ConsentBannerSave, type ConsentBannerSaveProps, ConsentBannerTitle, type ConsentBannerTitleProps, ConsentToggle, type ConsentToggleProps, GtagConsentBootstrap, type GtagConsentBootstrapProps, type UseConsentOptions, type UseConsentResult, type UseGoogleConsentSyncOptions, useConsent, useGoogleConsentSync, useInitialConsent };
@@ -1,3 +1,6 @@
1
- import { ConsentBanner, ConsentToggle } from "./consent-banner.mjs";
1
+ import { ConsentBanner, ConsentBannerAccept, ConsentBannerActions, ConsentBannerCategory, ConsentBannerCustomize, ConsentBannerDescription, ConsentBannerPreferences, ConsentBannerReject, ConsentBannerSave, ConsentBannerTitle, ConsentToggle } from "./consent-banner.mjs";
2
+ import { GtagConsentBootstrap } from "./gtag-consent-bootstrap.mjs";
2
3
  import { useConsent } from "./use-consent.mjs";
3
- export { ConsentBanner, ConsentToggle, useConsent };
4
+ import { useInitialConsent } from "./use-initial-consent.mjs";
5
+ import { useGoogleConsentSync } from "./use-google-consent-sync.mjs";
6
+ export { ConsentBanner, ConsentBannerAccept, ConsentBannerActions, ConsentBannerCategory, ConsentBannerCustomize, ConsentBannerDescription, ConsentBannerPreferences, ConsentBannerReject, ConsentBannerSave, ConsentBannerTitle, ConsentToggle, GtagConsentBootstrap, useConsent, useGoogleConsentSync, useInitialConsent };
@@ -1,20 +1,16 @@
1
- import { ConsentCategory, ConsentDecision, ConsentMode, ConsentStorage } from "../core/consent.mjs";
1
+ import { ConsentDecision, ConsentMode, ConsentStorage } from "../core/consent.mjs";
2
+ import { ConsentConfig } from "../core/consent-config.mjs";
2
3
 
3
4
  //#region src/react/use-consent.d.ts
4
5
  /**
5
6
  * @since 0.5.0-canary.4
6
7
  */
7
8
  interface UseConsentOptions {
8
- /**
9
- * Categories the app's prompt actually asks about — `grantAll` grants exactly these,
10
- * so an analytics-only banner can never grant ads consent it never asked for.
11
- * Defaults to `["analytics"]`.
12
- */
13
- categories?: ReadonlyArray<ConsentCategory>;
14
- hasGlobalPrivacyControlSignal?: boolean;
9
+ /** Must be the same object the tracker gate and the tag bootstraps receive — one config, every surface. */
10
+ config: ConsentConfig;
11
+ hasGlobalPrivacyControlSignal?: boolean | undefined;
15
12
  mode: ConsentMode;
16
- onDecision?: (decision: ConsentDecision) => void;
17
- policyVersion: string;
13
+ onDecision?: ((decision: ConsentDecision) => void) | undefined;
18
14
  /** Must be a stable reference (module-level or memoized) — a new object per render resubscribes every render. */
19
15
  storage: ConsentStorage;
20
16
  }
@@ -29,11 +25,11 @@ interface UseConsentResult {
29
25
  effectiveConsent: ConsentDecision;
30
26
  grantAll: () => void;
31
27
  /** Effective `analytics` consent — gates this package's own tracker pipeline. */
32
- isTrackingAllowed: boolean;
28
+ isAnalyticsAllowed: boolean;
33
29
  /** True only for opt-in regions with no stored decision yet — drives whether to render the banner. */
34
- needsPrompt: boolean;
30
+ isPromptNeeded: boolean;
35
31
  /** Persist a granular per-category choice, e.g. from a preferences panel. */
36
- save: (decision: ConsentDecision) => void;
32
+ saveDecision: (decision: ConsentDecision) => void;
37
33
  }
38
34
  /**
39
35
  * Bridges `resolveConsentMode`/`resolveDefaultConsent` (core, region-aware) to React via
@@ -1,7 +1,7 @@
1
- import { CONSENT_CATEGORIES, createConsentDecision, isConsentDecision, resolveDefaultConsent } from "../core/consent.mjs";
2
- import { useRef, useSyncExternalStore } from "react";
1
+ "use client";
2
+ import { CONSENT_CATEGORIES, createConsentDecision, readStoredDecision, resolveDefaultConsent } from "../core/consent.mjs";
3
+ import { useCallback, useMemo, useRef, useSyncExternalStore } from "react";
3
4
  //#region src/react/use-consent.ts
4
- const DEFAULT_CATEGORIES = ["analytics"];
5
5
  /**
6
6
  * Bridges `resolveConsentMode`/`resolveDefaultConsent` (core, region-aware) to React via
7
7
  * `useSyncExternalStore`: the stored record is the single source of truth, hydration is
@@ -12,43 +12,60 @@ const DEFAULT_CATEGORIES = ["analytics"];
12
12
  * @since 0.5.0-canary.4
13
13
  */
14
14
  function useConsent(options) {
15
- const { storage } = options;
16
- const categories = options.categories ?? DEFAULT_CATEGORIES;
15
+ const { mode, onDecision, storage } = options;
16
+ const { policyVersion, requestedCategories } = options.config;
17
+ const hasGlobalPrivacyControlSignal = options.hasGlobalPrivacyControlSignal ?? false;
17
18
  const cachedDecision = useRef(void 0);
18
19
  const decision = useSyncExternalStore(storage.subscribe, () => {
19
- const record = storage.load();
20
- if (record?.policyVersion !== options.policyVersion || !isConsentDecision(record.decision)) {
20
+ const stored = readStoredDecision(storage, policyVersion);
21
+ if (stored === void 0) {
21
22
  cachedDecision.current = void 0;
22
23
  return;
23
24
  }
24
- const stored = record.decision;
25
25
  const cached = cachedDecision.current;
26
26
  if (cached !== void 0 && CONSENT_CATEGORIES.every((category) => cached[category] === stored[category])) return cached;
27
- cachedDecision.current = createConsentDecision(CONSENT_CATEGORIES.filter((category) => stored[category]));
27
+ cachedDecision.current = stored;
28
28
  return cachedDecision.current;
29
29
  }, () => void 0);
30
- function save(next) {
30
+ const saveDecision = useCallback((next) => {
31
31
  storage.save({
32
32
  decision: next,
33
- policyVersion: options.policyVersion,
33
+ policyVersion,
34
34
  timestamp: Date.now()
35
35
  });
36
- options.onDecision?.(next);
37
- }
38
- const effectiveConsent = decision ?? resolveDefaultConsent(options.mode, categories, options.hasGlobalPrivacyControlSignal ?? false);
39
- return {
36
+ onDecision?.(next);
37
+ }, [
38
+ onDecision,
39
+ policyVersion,
40
+ storage
41
+ ]);
42
+ const denyAll = useCallback(() => {
43
+ saveDecision(createConsentDecision([]));
44
+ }, [saveDecision]);
45
+ const grantAll = useCallback(() => {
46
+ saveDecision(createConsentDecision(requestedCategories));
47
+ }, [requestedCategories, saveDecision]);
48
+ const effectiveConsent = decision ?? resolveDefaultConsent({
49
+ hasGlobalPrivacyControlSignal,
50
+ mode,
51
+ requestedCategories
52
+ });
53
+ return useMemo(() => ({
40
54
  decision,
41
- denyAll: () => {
42
- save(createConsentDecision([]));
43
- },
55
+ denyAll,
44
56
  effectiveConsent,
45
- grantAll: () => {
46
- save(createConsentDecision(categories));
47
- },
48
- isTrackingAllowed: effectiveConsent.analytics,
49
- needsPrompt: options.mode === "opt-in" && decision === void 0,
50
- save
51
- };
57
+ grantAll,
58
+ isAnalyticsAllowed: effectiveConsent.analytics,
59
+ isPromptNeeded: mode === "opt-in" && decision === void 0,
60
+ saveDecision
61
+ }), [
62
+ decision,
63
+ denyAll,
64
+ effectiveConsent,
65
+ grantAll,
66
+ mode,
67
+ saveDecision
68
+ ]);
52
69
  }
53
70
  //#endregion
54
71
  export { useConsent };
@@ -0,0 +1,23 @@
1
+ import { UseConsentResult } from "./use-consent.mjs";
2
+
3
+ //#region src/react/use-google-consent-sync.d.ts
4
+ /**
5
+ * @since 1.0.0-canary.6
6
+ */
7
+ interface UseGoogleConsentSyncOptions {
8
+ /**
9
+ * Idempotent gtag.js load — advanced Consent Mode already injects the tag from a
10
+ * bootstrap; pass a loader as a safety net after a runtime grant.
11
+ */
12
+ loadGtagScript?: (() => void) | undefined;
13
+ }
14
+ /**
15
+ * Keeps Google Consent Mode v2 in sync with `useConsent`: emits `update` when a stored
16
+ * decision exists (including cross-tab / privacy-page saves), and optionally loads gtag
17
+ * when analytics is effective. Mount once on a page-wide surface (e.g. the footer gate).
18
+ *
19
+ * @since 1.0.0-canary.6
20
+ */
21
+ declare function useGoogleConsentSync(consent: UseConsentResult, options?: UseGoogleConsentSyncOptions): void;
22
+ //#endregion
23
+ export { UseGoogleConsentSyncOptions, useGoogleConsentSync };
@@ -0,0 +1,24 @@
1
+ "use client";
2
+ import { updateGoogleConsent } from "../destinations/google-analytics.mjs";
3
+ import { useEffect } from "react";
4
+ //#region src/react/use-google-consent-sync.ts
5
+ /**
6
+ * Keeps Google Consent Mode v2 in sync with `useConsent`: emits `update` when a stored
7
+ * decision exists (including cross-tab / privacy-page saves), and optionally loads gtag
8
+ * when analytics is effective. Mount once on a page-wide surface (e.g. the footer gate).
9
+ *
10
+ * @since 1.0.0-canary.6
11
+ */
12
+ function useGoogleConsentSync(consent, options = {}) {
13
+ const { loadGtagScript } = options;
14
+ useEffect(() => {
15
+ if (consent.decision !== void 0) updateGoogleConsent(consent.decision);
16
+ if (consent.effectiveConsent.analytics) loadGtagScript?.();
17
+ }, [
18
+ consent.decision,
19
+ consent.effectiveConsent.analytics,
20
+ loadGtagScript
21
+ ]);
22
+ }
23
+ //#endregion
24
+ export { useGoogleConsentSync };
@@ -0,0 +1,14 @@
1
+ import { InitialConsentSnapshot, InitialConsentStore } from "../client/initial-consent-store.mjs";
2
+
3
+ //#region src/react/use-initial-consent.d.ts
4
+ /**
5
+ * Reactive view of a `createInitialConsentStore` — kicks off resolution on mount (a no-op
6
+ * when the app already did so at router creation) and re-renders once the server lane
7
+ * answers. SSR and the first client render read the strictest snapshot, so hydration can
8
+ * never mismatch on region.
9
+ *
10
+ * @since 1.0.0-canary.6
11
+ */
12
+ declare function useInitialConsent(store: InitialConsentStore): InitialConsentSnapshot;
13
+ //#endregion
14
+ export { useInitialConsent };
@@ -0,0 +1,19 @@
1
+ "use client";
2
+ import { useEffect, useSyncExternalStore } from "react";
3
+ //#region src/react/use-initial-consent.ts
4
+ /**
5
+ * Reactive view of a `createInitialConsentStore` — kicks off resolution on mount (a no-op
6
+ * when the app already did so at router creation) and re-renders once the server lane
7
+ * answers. SSR and the first client render read the strictest snapshot, so hydration can
8
+ * never mismatch on region.
9
+ *
10
+ * @since 1.0.0-canary.6
11
+ */
12
+ function useInitialConsent(store) {
13
+ useEffect(() => {
14
+ store.ensureResolved();
15
+ }, [store]);
16
+ return useSyncExternalStore(store.subscribe, store.getSnapshot, store.getServerSnapshot);
17
+ }
18
+ //#endregion
19
+ export { useInitialConsent };
@@ -0,0 +1,46 @@
1
+ //#region src/server/anonymous-id-cookie.d.ts
2
+ /**
3
+ * Whether a value is safe to persist as an anonymous id. The persist endpoint is public
4
+ * and echoes its input into a response header, so only an exactly-UUID-shaped value may
5
+ * pass — anything else is a header-injection attempt or corruption, never a valid id.
6
+ *
7
+ * @since 1.0.0-canary.6
8
+ */
9
+ declare function isValidAnonymousId(value: string): boolean;
10
+ /**
11
+ * @since 1.0.0-canary.6
12
+ */
13
+ interface AnonymousIdSetCookieOptions {
14
+ /** Cookie name — must match what the client tracker reads. */
15
+ cookieName: string;
16
+ /** The client-minted id to persist — throws unless it is exactly UUID-shaped. */
17
+ id: string;
18
+ /** How long the id survives a return visit. Defaults to one year. */
19
+ maxAgeSeconds?: number | undefined;
20
+ }
21
+ /**
22
+ * `Set-Cookie` header value that persists (or prolongs) a client-minted anonymous id from
23
+ * the server. A server-set cookie escapes Safari ITP's 7-day cap on `document.cookie`
24
+ * writes, so the id actually lives its full max-age. The server only ever re-sets an id
25
+ * the client hands it — minting stays client-side, after consent, by design.
26
+ *
27
+ * @remarks
28
+ * Always `Secure` — on a plain-HTTP dev origin a browser may drop it, and the
29
+ * client-written cookie (`createServerPersistedAnonymousId`'s optimistic write) still
30
+ * covers that session. Not `HttpOnly`: the client tracker must read the id to stamp it
31
+ * onto events.
32
+ *
33
+ * @throws Error when `id` is not UUID-shaped or `cookieName` is not a valid token.
34
+ *
35
+ * @since 1.0.0-canary.6
36
+ */
37
+ declare function buildAnonymousIdSetCookie(options: AnonymousIdSetCookieOptions): string;
38
+ /**
39
+ * `Set-Cookie` header value that expires the anonymous-id cookie — the server half of a
40
+ * consent withdrawal, alongside the client's own `document.cookie` expiry.
41
+ *
42
+ * @since 1.0.0-canary.6
43
+ */
44
+ declare function buildClearAnonymousIdSetCookie(cookieName: string): string;
45
+ //#endregion
46
+ export { AnonymousIdSetCookieOptions, buildAnonymousIdSetCookie, buildClearAnonymousIdSetCookie, isValidAnonymousId };