@codefast/tracking 0.0.0 → 0.5.0-canary.5

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 (73) hide show
  1. package/CHANGELOG.md +44 -0
  2. package/README.md +79 -9
  3. package/dist/client/consent-storage.d.mts +11 -3
  4. package/dist/client/consent-storage.mjs +45 -9
  5. package/dist/client/create-client-tracker.d.mts +10 -0
  6. package/dist/client/create-client-tracker.mjs +14 -1
  7. package/dist/client/gpc.d.mts +2 -0
  8. package/dist/client/gpc.mjs +2 -0
  9. package/dist/client/lifecycle.d.mts +5 -0
  10. package/dist/client/lifecycle.mjs +2 -0
  11. package/dist/client/local-storage.d.mts +5 -2
  12. package/dist/client/local-storage.mjs +12 -5
  13. package/dist/client/queue.d.mts +7 -0
  14. package/dist/client/queue.mjs +2 -0
  15. package/dist/client/router.d.mts +4 -0
  16. package/dist/client/router.mjs +2 -0
  17. package/dist/core/consent.d.mts +61 -9
  18. package/dist/core/consent.mjs +39 -7
  19. package/dist/core/destination.d.mts +10 -0
  20. package/dist/core/event-catalog.d.mts +8 -0
  21. package/dist/core/event-catalog.mjs +2 -0
  22. package/dist/core/event-id.d.mts +2 -0
  23. package/dist/core/event-id.mjs +2 -0
  24. package/dist/core/index.d.mts +2 -2
  25. package/dist/core/index.mjs +2 -2
  26. package/dist/core/tracked-event.d.mts +2 -0
  27. package/dist/destinations/ga4-measurement-protocol.d.mts +54 -0
  28. package/dist/destinations/ga4-measurement-protocol.mjs +89 -0
  29. package/dist/destinations/google-analytics.d.mts +98 -0
  30. package/dist/destinations/google-analytics.mjs +126 -0
  31. package/dist/destinations/http-destination.d.mts +5 -0
  32. package/dist/destinations/http-destination.mjs +2 -0
  33. package/dist/destinations/index.d.mts +3 -1
  34. package/dist/destinations/index.mjs +3 -1
  35. package/dist/destinations/vercel-analytics.d.mts +4 -2
  36. package/dist/destinations/vercel-analytics.mjs +5 -2
  37. package/dist/index.d.mts +2 -2
  38. package/dist/index.mjs +2 -2
  39. package/dist/react/consent-banner.d.mts +140 -18
  40. package/dist/react/consent-banner.mjs +195 -28
  41. package/dist/react/index.d.mts +2 -2
  42. package/dist/react/index.mjs +2 -2
  43. package/dist/react/use-consent.d.mts +30 -5
  44. package/dist/react/use-consent.mjs +38 -15
  45. package/dist/server/create-server-tracker.d.mts +14 -0
  46. package/dist/server/create-server-tracker.mjs +24 -5
  47. package/dist/server/region.d.mts +4 -0
  48. package/dist/server/region.mjs +4 -0
  49. package/package.json +13 -2
  50. package/src/client/consent-storage.ts +75 -10
  51. package/src/client/create-client-tracker.ts +30 -1
  52. package/src/client/gpc.ts +2 -0
  53. package/src/client/lifecycle.ts +5 -0
  54. package/src/client/local-storage.ts +21 -6
  55. package/src/client/queue.ts +7 -0
  56. package/src/client/router.ts +4 -0
  57. package/src/core/consent.ts +85 -11
  58. package/src/core/destination.ts +10 -0
  59. package/src/core/event-catalog.ts +8 -0
  60. package/src/core/event-id.ts +2 -0
  61. package/src/core/index.ts +15 -2
  62. package/src/core/tracked-event.ts +2 -0
  63. package/src/css/consent.css +119 -0
  64. package/src/destinations/ga4-measurement-protocol.ts +166 -0
  65. package/src/destinations/google-analytics.ts +233 -0
  66. package/src/destinations/http-destination.ts +5 -0
  67. package/src/destinations/index.ts +16 -0
  68. package/src/destinations/vercel-analytics.ts +5 -2
  69. package/src/react/consent-banner.tsx +301 -31
  70. package/src/react/index.ts +26 -2
  71. package/src/react/use-consent.ts +81 -23
  72. package/src/server/create-server-tracker.ts +39 -16
  73. package/src/server/region.ts +4 -0
@@ -1,41 +1,163 @@
1
+ import { ConsentCategory } from "../core/consent.mjs";
1
2
  import { UseConsentResult } from "./use-consent.mjs";
2
- import { ReactNode } from "react";
3
+ import { ComponentProps, ReactNode } from "react";
3
4
 
4
5
  //#region src/react/consent-banner.d.ts
5
- interface ConsentBannerProps {
6
- acceptLabel?: string;
7
- className?: string;
6
+ /**
7
+ * @since 0.5.0-canary.4
8
+ */
9
+ interface ConsentBannerProps extends ComponentProps<"section"> {
8
10
  consent: UseConsentResult;
9
- message?: string;
10
- rejectLabel?: string;
11
+ /** Overrides the default `needsPrompt` gating — e.g. to reopen the banner as a settings panel. */
12
+ open?: boolean | undefined;
11
13
  }
12
14
  /**
13
- * Blocking opt-in prompt for GDPR/NĐ 13 regions — renders nothing once a decision
14
- * exists or the region defaults to opt-out (`consent.needsPrompt` covers both). No
15
- * styling is baked in; pass `className` to match the host app's design system.
15
+ * Non-blocking opt-in prompt for GDPR/NĐ 13 regions, as composable parts — the root owns
16
+ * the visibility gating and the preferences-layer state; the `Accept`/`Reject`/`Customize`/
17
+ * `Save` parts wire their own clicks to the consent hook, so any markup (including a
18
+ * design system's button styles via `className`) slots in. Renders nothing once a decision
19
+ * exists or the region defaults to opt-out (`consent.needsPrompt`), unless `open` says
20
+ * otherwise. Rendered as a labeled region, not a `<dialog>`: an open non-modal dialog
21
+ * neither traps focus nor blocks the page, so the dialog semantics would over-promise.
22
+ * Unstyled by default — style via `className`/`data-slot` selectors, or import the
23
+ * optional `@codefast/tracking/css/consent.css` theme. `data-state` on the root flips
24
+ * between `prompt` and `preferences` for state-dependent styling.
25
+ *
26
+ * @since 0.5.0-canary.4
16
27
  */
17
28
  declare function ConsentBanner({
18
- acceptLabel,
19
- className,
29
+ children,
20
30
  consent,
21
- message,
22
- rejectLabel
31
+ open,
32
+ ...props
23
33
  }: ConsentBannerProps): ReactNode;
24
- interface ConsentToggleProps {
34
+ /**
35
+ * @since 0.5.0-canary.5
36
+ */
37
+ interface ConsentBannerTitleProps extends ComponentProps<"h2"> {}
38
+ /**
39
+ * @since 0.5.0-canary.5
40
+ */
41
+ declare function ConsentBannerTitle({
42
+ children,
43
+ ...props
44
+ }: ConsentBannerTitleProps): ReactNode;
45
+ /**
46
+ * @since 0.5.0-canary.5
47
+ */
48
+ interface ConsentBannerDescriptionProps extends ComponentProps<"p"> {}
49
+ /**
50
+ * Hosts the message and the privacy-policy link informed consent requires.
51
+ *
52
+ * @since 0.5.0-canary.5
53
+ */
54
+ declare function ConsentBannerDescription(props: ConsentBannerDescriptionProps): ReactNode;
55
+ /**
56
+ * @since 0.5.0-canary.5
57
+ */
58
+ interface ConsentBannerActionsProps extends ComponentProps<"div"> {}
59
+ /**
60
+ * @since 0.5.0-canary.5
61
+ */
62
+ declare function ConsentBannerActions(props: ConsentBannerActionsProps): ReactNode;
63
+ /**
64
+ * @since 0.5.0-canary.5
65
+ */
66
+ interface ConsentBannerAcceptProps extends Omit<ComponentProps<"button">, "type"> {}
67
+ /**
68
+ * Grants the categories the app requested (`useConsent`'s `categories`) — never more.
69
+ *
70
+ * @since 0.5.0-canary.5
71
+ */
72
+ declare function ConsentBannerAccept({
73
+ onClick,
74
+ ...props
75
+ }: ConsentBannerAcceptProps): ReactNode;
76
+ /**
77
+ * @since 0.5.0-canary.5
78
+ */
79
+ interface ConsentBannerRejectProps extends Omit<ComponentProps<"button">, "type"> {}
80
+ /**
81
+ * @since 0.5.0-canary.5
82
+ */
83
+ declare function ConsentBannerReject({
84
+ onClick,
85
+ ...props
86
+ }: ConsentBannerRejectProps): ReactNode;
87
+ /**
88
+ * @since 0.5.0-canary.5
89
+ */
90
+ interface ConsentBannerCustomizeProps extends Omit<ComponentProps<"button">, "type"> {}
91
+ /**
92
+ * Opens the per-category preferences layer, starting from the current effective state so
93
+ * nothing arrives pre-ticked in an opt-in region (pre-ticked consent is invalid under
94
+ * GDPR). Hidden while the layer is open — `ConsentBannerSave` takes over.
95
+ *
96
+ * @since 0.5.0-canary.5
97
+ */
98
+ declare function ConsentBannerCustomize({
99
+ onClick,
100
+ ...props
101
+ }: ConsentBannerCustomizeProps): ReactNode;
102
+ /**
103
+ * @since 0.5.0-canary.5
104
+ */
105
+ interface ConsentBannerPreferencesProps extends ComponentProps<"div"> {}
106
+ /**
107
+ * Container for the per-category rows — renders only while the preferences layer is open.
108
+ *
109
+ * @since 0.5.0-canary.5
110
+ */
111
+ declare function ConsentBannerPreferences(props: ConsentBannerPreferencesProps): ReactNode;
112
+ /**
113
+ * @since 0.5.0-canary.5
114
+ */
115
+ interface ConsentBannerCategoryProps extends ComponentProps<"label"> {
116
+ category: ConsentCategory;
117
+ }
118
+ /**
119
+ * One checkbox row of the preferences layer — `children` is the visitor-facing wording.
120
+ *
121
+ * @since 0.5.0-canary.5
122
+ */
123
+ declare function ConsentBannerCategory({
124
+ category,
125
+ children,
126
+ ...props
127
+ }: ConsentBannerCategoryProps): ReactNode;
128
+ /**
129
+ * @since 0.5.0-canary.5
130
+ */
131
+ interface ConsentBannerSaveProps extends Omit<ComponentProps<"button">, "type"> {}
132
+ /**
133
+ * Persists the pending per-category selection — renders only while the preferences layer is open.
134
+ *
135
+ * @since 0.5.0-canary.5
136
+ */
137
+ declare function ConsentBannerSave({
138
+ onClick,
139
+ ...props
140
+ }: ConsentBannerSaveProps): ReactNode;
141
+ /**
142
+ * @since 0.5.0-canary.4
143
+ */
144
+ interface ConsentToggleProps extends Omit<ComponentProps<"button">, "children" | "onClick" | "type"> {
25
145
  allowLabel?: string;
26
- className?: string;
27
146
  consent: UseConsentResult;
28
147
  denyLabel?: string;
29
148
  }
30
149
  /**
31
150
  * Always-visible control for opt-out regions — CCPA/CPRA requires a persistent
32
151
  * "Do Not Sell or Share My Personal Information" mechanism, not just a one-time prompt.
152
+ * Flips between denying everything and re-granting the app's requested categories.
153
+ *
154
+ * @since 0.5.0-canary.4
33
155
  */
34
156
  declare function ConsentToggle({
35
157
  allowLabel,
36
- className,
37
158
  consent,
38
- denyLabel
159
+ denyLabel,
160
+ ...props
39
161
  }: ConsentToggleProps): ReactNode;
40
162
  //#endregion
41
- export { ConsentBanner, ConsentBannerProps, ConsentToggle, ConsentToggleProps };
163
+ export { ConsentBanner, ConsentBannerAccept, ConsentBannerAcceptProps, ConsentBannerActions, ConsentBannerActionsProps, ConsentBannerCategory, ConsentBannerCategoryProps, ConsentBannerCustomize, ConsentBannerCustomizeProps, ConsentBannerDescription, ConsentBannerDescriptionProps, ConsentBannerPreferences, ConsentBannerPreferencesProps, ConsentBannerProps, ConsentBannerReject, ConsentBannerRejectProps, ConsentBannerSave, ConsentBannerSaveProps, ConsentBannerTitle, ConsentBannerTitleProps, ConsentToggle, ConsentToggleProps };
@@ -1,42 +1,209 @@
1
+ import { CONSENT_CATEGORIES } from "../core/consent.mjs";
2
+ import { createContext, useContext, useEffect, useState } from "react";
1
3
  import { jsx, jsxs } from "react/jsx-runtime";
2
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
+ }
11
+ /**
12
+ * Non-blocking opt-in prompt for GDPR/NĐ 13 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.needsPrompt`), 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.
22
+ *
23
+ * @since 0.5.0-canary.4
24
+ */
25
+ function ConsentBanner({ children, consent, open, ...props }) {
26
+ const [pending, setPending] = useState(void 0);
27
+ const isVisible = open ?? consent.needsPrompt;
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 `categories`) — 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
+ }
3
134
  /**
4
- * Blocking opt-in prompt for GDPR/NĐ 13 regions — renders nothing once a decision
5
- * exists or the region defaults to opt-out (`consent.needsPrompt` covers both). No
6
- * styling is baked in; pass `className` to match the host app's design system.
7
- */
8
- function ConsentBanner({ acceptLabel = "Accept", className, consent, message = "We use cookies to understand how you use this site.", rejectLabel = "Reject" }) {
9
- if (!consent.needsPrompt) return null;
10
- return /* @__PURE__ */ jsxs("dialog", {
11
- "aria-live": "polite",
12
- className,
13
- open: true,
14
- children: [
15
- /* @__PURE__ */ jsx("p", { children: message }),
16
- /* @__PURE__ */ jsx("button", {
17
- onClick: consent.grant,
18
- type: "button",
19
- children: acceptLabel
20
- }),
21
- /* @__PURE__ */ jsx("button", {
22
- onClick: consent.deny,
23
- type: "button",
24
- children: rejectLabel
25
- })
26
- ]
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",
182
+ ...props,
183
+ onClick: (event) => {
184
+ onClick?.(event);
185
+ consent.save(pending);
186
+ setPending(void 0);
187
+ },
188
+ type: "button"
27
189
  });
28
190
  }
29
191
  /**
30
192
  * Always-visible control for opt-out regions — CCPA/CPRA requires a persistent
31
193
  * "Do Not Sell or Share My Personal Information" mechanism, not just a one-time prompt.
194
+ * Flips between denying everything and re-granting the app's requested categories.
195
+ *
196
+ * @since 0.5.0-canary.4
32
197
  */
33
- function ConsentToggle({ allowLabel = "Allow tracking", className, consent, denyLabel = "Do Not Sell or Share My Personal Information" }) {
198
+ function ConsentToggle({ allowLabel = "Allow tracking", consent, denyLabel = "Do Not Sell or Share My Personal Information", ...props }) {
199
+ const anyAllowed = CONSENT_CATEGORIES.some((category) => consent.effectiveConsent[category]);
34
200
  return /* @__PURE__ */ jsx("button", {
35
- className,
36
- onClick: consent.isTrackingAllowed ? consent.deny : consent.grant,
201
+ "data-slot": "consent-toggle",
202
+ ...props,
203
+ onClick: anyAllowed ? consent.denyAll : consent.grantAll,
37
204
  type: "button",
38
- children: consent.isTrackingAllowed ? denyLabel : allowLabel
205
+ children: anyAllowed ? denyLabel : allowLabel
39
206
  });
40
207
  }
41
208
  //#endregion
42
- export { ConsentBanner, ConsentToggle };
209
+ export { ConsentBanner, ConsentBannerAccept, ConsentBannerActions, ConsentBannerCategory, ConsentBannerCustomize, ConsentBannerDescription, ConsentBannerPreferences, ConsentBannerReject, ConsentBannerSave, ConsentBannerTitle, ConsentToggle };
@@ -1,3 +1,3 @@
1
1
  import { UseConsentOptions, UseConsentResult, useConsent } from "./use-consent.mjs";
2
- import { ConsentBanner, ConsentBannerProps, ConsentToggle, ConsentToggleProps } from "./consent-banner.mjs";
3
- export { ConsentBanner, type ConsentBannerProps, 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
+ 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, type UseConsentOptions, type UseConsentResult, useConsent };
@@ -1,3 +1,3 @@
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
2
  import { useConsent } from "./use-consent.mjs";
3
- export { ConsentBanner, ConsentToggle, useConsent };
3
+ export { ConsentBanner, ConsentBannerAccept, ConsentBannerActions, ConsentBannerCategory, ConsentBannerCustomize, ConsentBannerDescription, ConsentBannerPreferences, ConsentBannerReject, ConsentBannerSave, ConsentBannerTitle, ConsentToggle, useConsent };
@@ -1,23 +1,48 @@
1
- import { ConsentDecision, ConsentMode, ConsentStorage } from "../core/consent.mjs";
1
+ import { ConsentCategory, ConsentDecision, ConsentMode, ConsentStorage } from "../core/consent.mjs";
2
2
 
3
3
  //#region src/react/use-consent.d.ts
4
+ /**
5
+ * @since 0.5.0-canary.4
6
+ */
4
7
  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>;
5
14
  hasGlobalPrivacyControlSignal?: boolean;
6
15
  mode: ConsentMode;
7
16
  onDecision?: (decision: ConsentDecision) => void;
8
17
  policyVersion: string;
18
+ /** Must be a stable reference (module-level or memoized) — a new object per render resubscribes every render. */
9
19
  storage: ConsentStorage;
10
20
  }
21
+ /**
22
+ * @since 0.5.0-canary.4
23
+ */
11
24
  interface UseConsentResult {
12
- deny: () => void;
13
- grant: () => void;
25
+ /** The stored decision under the current policy version — `undefined` until the visitor makes one. */
26
+ decision: ConsentDecision | undefined;
27
+ denyAll: () => void;
28
+ /** What tags must obey right now — the stored decision, or the region default before one exists. */
29
+ effectiveConsent: ConsentDecision;
30
+ grantAll: () => void;
31
+ /** Effective `analytics` consent — gates this package's own tracker pipeline. */
14
32
  isTrackingAllowed: boolean;
15
33
  /** True only for opt-in regions with no stored decision yet — drives whether to render the banner. */
16
34
  needsPrompt: boolean;
35
+ /** Persist a granular per-category choice, e.g. from a preferences panel. */
36
+ save: (decision: ConsentDecision) => void;
17
37
  }
18
38
  /**
19
- * Bridges `resolveConsentMode`/`shouldTrackByDefault` (core, region-aware) to React state,
20
- * persisting the visitor's decision via the given `ConsentStorage`.
39
+ * Bridges `resolveConsentMode`/`resolveDefaultConsent` (core, region-aware) to React via
40
+ * `useSyncExternalStore`: the stored record is the single source of truth, hydration is
41
+ * safe by construction (the server snapshot is always "no decision yet", matching what
42
+ * prerendered HTML could know), and a decision made in another tab syncs through the
43
+ * storage subscription.
44
+ *
45
+ * @since 0.5.0-canary.4
21
46
  */
22
47
  declare function useConsent(options: UseConsentOptions): UseConsentResult;
23
48
  //#endregion
@@ -1,30 +1,53 @@
1
- import { shouldTrackByDefault } from "../core/consent.mjs";
2
- import { useCallback, useState } from "react";
1
+ import { CONSENT_CATEGORIES, createConsentDecision, isConsentDecision, resolveDefaultConsent } from "../core/consent.mjs";
2
+ import { useRef, useSyncExternalStore } from "react";
3
3
  //#region src/react/use-consent.ts
4
+ const DEFAULT_CATEGORIES = ["analytics"];
4
5
  /**
5
- * Bridges `resolveConsentMode`/`shouldTrackByDefault` (core, region-aware) to React state,
6
- * persisting the visitor's decision via the given `ConsentStorage`.
6
+ * Bridges `resolveConsentMode`/`resolveDefaultConsent` (core, region-aware) to React via
7
+ * `useSyncExternalStore`: the stored record is the single source of truth, hydration is
8
+ * safe by construction (the server snapshot is always "no decision yet", matching what
9
+ * prerendered HTML could know), and a decision made in another tab syncs through the
10
+ * storage subscription.
11
+ *
12
+ * @since 0.5.0-canary.4
7
13
  */
8
14
  function useConsent(options) {
9
- const [decision, setDecision] = useState(() => options.storage.load()?.decision);
10
- const decide = useCallback((next) => {
11
- options.storage.save({
15
+ const { storage } = options;
16
+ const categories = options.categories ?? DEFAULT_CATEGORIES;
17
+ const cachedDecision = useRef(void 0);
18
+ const decision = useSyncExternalStore(storage.subscribe, () => {
19
+ const record = storage.load();
20
+ if (record?.policyVersion !== options.policyVersion || !isConsentDecision(record.decision)) {
21
+ cachedDecision.current = void 0;
22
+ return;
23
+ }
24
+ const stored = record.decision;
25
+ const cached = cachedDecision.current;
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]));
28
+ return cachedDecision.current;
29
+ }, () => void 0);
30
+ function save(next) {
31
+ storage.save({
12
32
  decision: next,
13
33
  policyVersion: options.policyVersion,
14
34
  timestamp: Date.now()
15
35
  });
16
- setDecision(next);
17
36
  options.onDecision?.(next);
18
- }, [options]);
37
+ }
38
+ const effectiveConsent = decision ?? resolveDefaultConsent(options.mode, categories, options.hasGlobalPrivacyControlSignal ?? false);
19
39
  return {
20
- deny: () => {
21
- decide("denied");
40
+ decision,
41
+ denyAll: () => {
42
+ save(createConsentDecision([]));
22
43
  },
23
- grant: () => {
24
- decide("granted");
44
+ effectiveConsent,
45
+ grantAll: () => {
46
+ save(createConsentDecision(categories));
25
47
  },
26
- isTrackingAllowed: decision === void 0 ? shouldTrackByDefault(options.mode, options.hasGlobalPrivacyControlSignal ?? false) : decision === "granted",
27
- needsPrompt: options.mode === "opt-in" && decision === void 0
48
+ isTrackingAllowed: effectiveConsent.analytics,
49
+ needsPrompt: options.mode === "opt-in" && decision === void 0,
50
+ save
28
51
  };
29
52
  }
30
53
  //#endregion
@@ -4,10 +4,16 @@ import { EventCatalog, EventsOf } from "../core/event-catalog.mjs";
4
4
  import { z } from "zod";
5
5
 
6
6
  //#region src/server/create-server-tracker.d.ts
7
+ /**
8
+ * @since 0.5.0-canary.4
9
+ */
7
10
  interface ServerTrackContext {
8
11
  anonymousId: string;
9
12
  userId?: string | undefined;
10
13
  }
14
+ /**
15
+ * @since 0.5.0-canary.4
16
+ */
11
17
  interface ServerTrackerOptions<Catalog extends EventCatalog> {
12
18
  catalog: Catalog;
13
19
  destinations: Array<Destination>;
@@ -16,12 +22,20 @@ interface ServerTrackerOptions<Catalog extends EventCatalog> {
16
22
  onDestinationError?: (error: unknown, destination: Destination, event: TrackedEvent) => void;
17
23
  retryDelayMs?: number;
18
24
  }
25
+ /**
26
+ * @since 0.5.0-canary.4
27
+ */
19
28
  interface ServerTracker<Catalog extends EventCatalog> {
29
+ /** Explicit anonymous → known-user merge, for when `identify` timing can't do it. */
30
+ alias: (previousId: string, userId: string, context: ServerTrackContext) => Promise<void>;
31
+ group: (groupId: string, traits: Record<string, unknown> | undefined, context: ServerTrackContext) => Promise<void>;
20
32
  track: <Name extends keyof EventsOf<Catalog, "server">>(name: Name, props: z.infer<EventsOf<Catalog, "server">[Name]["schema"]>, context: ServerTrackContext) => Promise<void>;
21
33
  }
22
34
  /**
23
35
  * No dead-letter queue yet (self-host storage is Phase 2) — a destination that keeps
24
36
  * failing after retries is only logged via `onDestinationError`, never re-queued.
37
+ *
38
+ * @since 0.5.0-canary.4
25
39
  */
26
40
  declare function createServerTracker<Catalog extends EventCatalog>(options: ServerTrackerOptions<Catalog>): ServerTracker<Catalog>;
27
41
  //#endregion
@@ -20,6 +20,8 @@ async function sendWithRetry(destination, event, maxRetries, retryDelayMs, onErr
20
20
  /**
21
21
  * No dead-letter queue yet (self-host storage is Phase 2) — a destination that keeps
22
22
  * failing after retries is only logged via `onDestinationError`, never re-queued.
23
+ *
24
+ * @since 0.5.0-canary.4
23
25
  */
24
26
  function createServerTracker(options) {
25
27
  const maxRetries = options.maxRetries ?? 2;
@@ -28,10 +30,7 @@ function createServerTracker(options) {
28
30
  const onError = options.onDestinationError ?? ((error, destination, event) => {
29
31
  console.error(`[tracking] destination "${destination.name}" failed for event "${event.name}"`, error);
30
32
  });
31
- return { async track(name, props, context) {
32
- const definition = options.catalog[name];
33
- if (!definition || definition.owner !== "server") throw new Error(`Unknown server-owned event: ${String(name)}`);
34
- definition.schema.parse(props);
33
+ async function sendEvent(name, props, context) {
35
34
  const event = {
36
35
  anonymousId: context.anonymousId,
37
36
  eventId: createId(),
@@ -42,7 +41,27 @@ function createServerTracker(options) {
42
41
  ...context.userId === void 0 ? {} : { userId: context.userId }
43
42
  };
44
43
  await Promise.all(options.destinations.map(async (destination) => sendWithRetry(destination, event, maxRetries, retryDelayMs, onError)));
45
- } };
44
+ }
45
+ return {
46
+ async alias(previousId, userId, context) {
47
+ await sendEvent("$alias", {
48
+ previousId,
49
+ userId
50
+ }, context);
51
+ },
52
+ async group(groupId, traits, context) {
53
+ await sendEvent("$group", {
54
+ groupId,
55
+ ...traits
56
+ }, context);
57
+ },
58
+ async track(name, props, context) {
59
+ const definition = options.catalog[name];
60
+ if (!definition || definition.owner !== "server") throw new Error(`Unknown server-owned event: ${String(name)}`);
61
+ definition.schema.parse(props);
62
+ await sendEvent(name, props, context);
63
+ }
64
+ };
46
65
  }
47
66
  //#endregion
48
67
  export { createServerTracker };
@@ -5,11 +5,15 @@ import { ConsentRegion } from "../core/consent.mjs";
5
5
  * Missing/unrecognized codes fall back to "other", which `resolveConsentMode` treats
6
6
  * as opt-out — the least restrictive default, safe only because opt-in regions (EU/VN)
7
7
  * are matched explicitly above it.
8
+ *
9
+ * @since 0.5.0-canary.4
8
10
  */
9
11
  declare function resolveRegionFromCountryCode(countryCode: string | undefined): ConsentRegion;
10
12
  /**
11
13
  * Reads the hosting platform's geo header (e.g. Vercel's `x-vercel-ip-country`) — pass
12
14
  * the incoming request's `Headers` from server-function/middleware context.
15
+ *
16
+ * @since 0.5.0-canary.4
13
17
  */
14
18
  declare function resolveRegion(headers: Headers, headerName?: string): ConsentRegion;
15
19
  //#endregion