@graffico/legal 0.3.7 → 0.3.9

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.
package/README.md CHANGED
@@ -1,341 +1,341 @@
1
- # @graffico/legal
2
-
3
- CMP GDPR drop-in per React / Next.js. Banner + modale, policy server-rendered, **tracker terzi che caricano solo dopo consenso**, plugin Next.js per security headers.
4
-
5
- ```bash
6
- pnpm add @graffico/legal
7
- ```
8
-
9
- ---
10
-
11
- ## 1. Setup minimo
12
-
13
- `src/config/legal.ts`:
14
-
15
- ```ts
16
- import type { CompanyConfig } from "@graffico/legal";
17
-
18
- export const legalConfig: CompanyConfig = {
19
- name: "Mia Azienda",
20
- domain: "azienda.it",
21
- owners: "Mario Rossi",
22
- addresses: "Via Roma 1, Milano",
23
- vatNumbers: "01234567890",
24
- email: "privacy@azienda.it",
25
- policyVersion: "2026.05", // cambiarla invalida i consensi vecchi
26
- services: ["google-analytics", "facebook-pixel", "contact-form"],
27
- primaryColor: "#2c5282",
28
- language: "it",
29
- };
30
- ```
31
-
32
- `app/layout.tsx`:
33
-
34
- ```tsx
35
- import { LegalProvider } from "@graffico/legal/server";
36
- import { legalConfig } from "@/config/legal";
37
-
38
- export default function RootLayout({ children }) {
39
- return (
40
- <html>
41
- <body>
42
- <LegalProvider config={legalConfig}>{children}</LegalProvider>
43
- </body>
44
- </html>
45
- );
46
- }
47
- ```
48
-
49
- `<LegalProvider>` monta automaticamente banner + modale + floating toggle.
50
-
51
- ### Tailwind / globals.css
52
-
53
- La libreria usa Tailwind utility classes inline (niente CSS bundle). Devi dire al JIT di Tailwind di scansionare i file della libreria, altrimenti banner e modale appariranno senza stili.
54
-
55
- **Tailwind v4** — aggiungi una direttiva `@source` in `src/app/globals.css` (o equivalente):
56
-
57
- ```css
58
- @import "tailwindcss";
59
- @source "../../node_modules/@graffico/legal/dist/**/*.{js,cjs}";
60
- ```
61
-
62
- > Il path `../../` parte da `src/app/`. Se il tuo `globals.css` sta altrove, regola la profondità relativa. In monorepo con workspace, il dist è raggiungibile via `node_modules` simlink.
63
-
64
- **Tailwind v3** — aggiungi al `tailwind.config.js`:
65
-
66
- ```js
67
- module.exports = {
68
- content: [
69
- "./src/**/*.{js,ts,jsx,tsx}",
70
- "./node_modules/@graffico/legal/dist/**/*.{js,cjs}",
71
- ],
72
- };
73
- ```
74
-
75
- ---
76
-
77
- ## 2. Tracker — drop-in con consenso integrato
78
-
79
- Importi il componente Legal, passi le API key. Lo script parte **solo dopo consenso**.
80
-
81
- ```tsx
82
- import {
83
- ConsentModeBoot,
84
- GoogleAnalyticsLegal,
85
- GoogleAdsLegal,
86
- MetaPixelLegal,
87
- HotjarLegal,
88
- GTMLegal,
89
- EmailJSLegal,
90
- } from "@graffico/legal";
91
-
92
- <LegalProvider config={legalConfig}>
93
- <ConsentModeBoot /> {/* Google Consent Mode v2 default = denied */}
94
- <GoogleAnalyticsLegal gaId="G-XXXX" />
95
- <GoogleAdsLegal
96
- conversionId="AW-XXXX"
97
- conversions={{ formSubmit: { sendTo: "AW-XXXX/abc", value: 1, currency: "EUR" } }}
98
- />
99
- <MetaPixelLegal pixelId="123456" events={["Lead", "Contact"]} />
100
- <HotjarLegal siteId={1234567} />
101
- <EmailJSLegal
102
- serviceId={process.env.NEXT_PUBLIC_EMAILJS_SERVICE_ID!}
103
- templateId={process.env.NEXT_PUBLIC_EMAILJS_TEMPLATE_ID!}
104
- publicKey={process.env.NEXT_PUBLIC_EMAILJS_USER_ID!}
105
- />
106
- {children}
107
- </LegalProvider>
108
- ```
109
-
110
- | Componente | Categoria default | Script gated | Note |
111
- |---|---|---|---|
112
- | `ConsentModeBoot` | — | — | Boot gtag stub + Consent Mode v2. **Sempre per primo.** |
113
- | `GoogleAnalyticsLegal` | `statistical` | `gtag/js?id=G-…` | Anonymize IP on di default. |
114
- | `GoogleAdsLegal` | `marketing` | `gtag/js?id=AW-…` | Mappa conversioni dichiarativa. |
115
- | `MetaPixelLegal` | `marketing` | `fbevents.js` | Whitelist `events` opzionale. Su revoca → `fbq('consent','revoke')`. |
116
- | `HotjarLegal` | `statistical` | `static.hotjar.com/c/hotjar-…` | Session recording + heatmap. |
117
- | `GTMLegal` | `marketing` | `gtm.js?id=GTM-…` | Lascia ai tag interni la granularità. |
118
- | `EmailJSLegal` | — (art. 6.1.b) | — | Config holder per `useEmailJS()`. |
119
-
120
- ---
121
-
122
- ## 3. Hook trigger eventi
123
-
124
- Nei tuoi componenti `"use client"`:
125
-
126
- ```tsx
127
- import { useGAEvent, useMetaEvent, useAdsConversion, useHotjarEvent } from "@graffico/legal";
128
-
129
- const trackGA = useGAEvent();
130
- const trackLead = useMetaEvent("Lead");
131
- const fireConversion = useAdsConversion("formSubmit");
132
- const trackHj = useHotjarEvent();
133
-
134
- // Tutti diventano no-op senza consenso — chiama liberamente
135
- trackGA("button_click", { id: "hero" });
136
- trackLead({ value: 99, currency: "EUR" });
137
- fireConversion();
138
- trackHj("scroll_to_pricing");
139
- ```
140
-
141
- ---
142
-
143
- ## 4. Form contatto con consenso
144
-
145
- ```tsx
146
- "use client";
147
- import { useEmailJS, ConsentCheckbox } from "@graffico/legal";
148
-
149
- export function ContactForm() {
150
- const { send, status } = useEmailJS();
151
-
152
- async function onSubmit(e: React.FormEvent<HTMLFormElement>) {
153
- e.preventDefault();
154
- const res = await send(e.currentTarget);
155
- if (!res.ok) console.warn(res.error); // CONSENT_MISSING | CONFIG_MISSING | SEND_FAILED
156
- }
157
-
158
- return (
159
- <form onSubmit={onSubmit}>
160
- <input name="name" required />
161
- <input name="email" type="email" required />
162
- <textarea name="message" required />
163
- <ConsentCheckbox /> {/* obbligatorio: blocca submit se non spuntato */}
164
- <button disabled={status === "loading"}>Invia</button>
165
- </form>
166
- );
167
- }
168
- ```
169
-
170
- `send()` inietta automaticamente nel payload mail: `_consentId`, `_consentTimestamp`, `_policyVersion` (prova legale art. 7.1).
171
-
172
- ---
173
-
174
- ## 5. Pagine policy
175
-
176
- Auto-renderizzate dalla config — incluse sezioni Processors / Transfers / Retention / DPO se valorizzati.
177
-
178
- ```tsx
179
- // app/privacy-policy/page.tsx
180
- import { PrivacyPolicy } from "@graffico/legal/server";
181
- import { legalConfig } from "@/config/legal";
182
- export default () => <PrivacyPolicy config={legalConfig} />;
183
-
184
- // app/cookie-policy/page.tsx
185
- import { CookiePolicy } from "@graffico/legal/server";
186
- export default () => <CookiePolicy config={legalConfig} />;
187
- ```
188
-
189
- ---
190
-
191
- ## 6. Gate per embed terzi
192
-
193
- ```tsx
194
- import { ConsentGate, useConsentCategory } from "@graffico/legal";
195
-
196
- <ConsentGate
197
- category="marketing"
198
- fallback={<p>Abilita cookie marketing per vedere il video.</p>}
199
- >
200
- <iframe src="https://youtube.com/embed/…" />
201
- </ConsentGate>
202
- ```
203
-
204
- ---
205
-
206
- ## 7. Next.js plugin — security headers
207
-
208
- CSP derivata dai `services[]` + `processors[]`. HSTS, X-Frame, Permissions-Policy, COOP, Referrer-Policy.
209
-
210
- ```ts
211
- // next.config.ts
212
- import { withLegal } from "@graffico/legal/next";
213
- import { legalConfig } from "@/config/legal";
214
-
215
- const nextConfig = { /* … */ };
216
-
217
- export default withLegal(nextConfig, legalConfig, {
218
- cspReportOnly: process.env.CSP_ENFORCE !== "1", // rollout: 7gg report-only → enforce
219
- });
220
- ```
221
-
222
- Per `netlify.toml`:
223
-
224
- ```ts
225
- import { emitNetlifyHeaders } from "@graffico/legal/next";
226
- console.log(emitNetlifyHeaders(legalConfig));
227
- ```
228
-
229
- ---
230
-
231
- ## 8. `CompanyConfig`
232
-
233
- ```ts
234
- interface CompanyConfig {
235
- name: string;
236
- domain: string;
237
- owners: string;
238
- addresses: string | string[];
239
- vatNumbers: string | string[];
240
- email: string;
241
-
242
- policyVersion?: string; // cambiarla invalida i consensi pregressi
243
- lastUpdated?: string; // ISO date, default oggi
244
-
245
- services?: ServiceReference[]; // tracker dichiarati (preset id o oggetto)
246
- processors?: Processor[]; // destinatari/responsabili esterni
247
- retention?: RetentionMap; // tempi di conservazione per categoria
248
- dpo?: DpoInfo; // se nominato (art. 37 GDPR)
249
-
250
- theme?: "light" | "dark";
251
- primaryColor?: string;
252
- language?: "it" | "en";
253
- togglePosition?: "bottom-right" | "bottom-left" | "top-right" | "top-left";
254
- }
255
-
256
- interface Processor {
257
- name: string;
258
- purpose: string;
259
- country: string;
260
- transferBasis?: string; // "DPF + SCC 2021/914", "SCC", …
261
- privacyUrl?: string;
262
- }
263
-
264
- interface RetentionMap {
265
- contactForms?: string; // "90d"
266
- analytics?: string; // "14m"
267
- marketing?: string; // "2y"
268
- [k: string]: string | undefined;
269
- }
270
-
271
- interface DpoInfo {
272
- name: string;
273
- email: string;
274
- phone?: string;
275
- }
276
- ```
277
-
278
- ---
279
-
280
- ## 9. Conformità GDPR / ePrivacy — cosa fa già la lib
281
-
282
- - **TTL consenso 180 giorni** (`CONSENT_TTL_MS`), allineato al Garante 10/06/2021. Scaduto → re-prompt.
283
- - **Re-prompt automatico** al cambio `policyVersion`.
284
- - **Auto-decline su GPC / DNT** (`navigator.globalPrivacyControl`, `Sec-GPC`) senza UI.
285
- - **Prova legale**: `consentId` UUID + `timestamp` ISO + `policyVersion` + `source` in localStorage e nel payload mail.
286
- - **Parità grafica reject/accept** nel banner (Garante 10/06/2021 §4).
287
- - **Categorie indipendenti**: `necessary` / `statistical` / `marketing`. Default OFF.
288
- - **Niente cookie wall**: il sito resta fruibile senza consenso.
289
- - **Zero telemetria** della libreria stessa.
290
-
291
- ---
292
-
293
- ## 10. Service preset (id stringa per `services[]`)
294
-
295
- | Categoria | Id |
296
- |---|---|
297
- | Analytics | `google-analytics`, `microsoft-clarity`, `hotjar` |
298
- | Marketing | `facebook-pixel`, `google-ads`, `linkedin-insight`, `tiktok-pixel` |
299
- | Tag manager | `google-tag-manager` |
300
- | Pagamenti | `stripe`, `paypal` |
301
- | Contenuti | `youtube`, `google-maps`, `google-fonts` |
302
- | Form / mail | `contact-form`, `mailchimp`, `newsletter` |
303
-
304
- Servizio inline custom:
305
-
306
- ```ts
307
- {
308
- id: "crm",
309
- name: "CRM Interno",
310
- category: "provided", // "automatic" | "provided" | "marketing"
311
- purposes: ["Gestione clienti"],
312
- dataCollected: ["Email", "Nome"],
313
- }
314
- ```
315
-
316
- ---
317
-
318
- ## 11. API export
319
-
320
- **`@graffico/legal/server`** — `LegalProvider`, `PrivacyPolicy`, `CookiePolicy`.
321
-
322
- **`@graffico/legal`** (client) —
323
- - Tracker: `ConsentModeBoot`, `GoogleAnalyticsLegal`, `GoogleAdsLegal`, `MetaPixelLegal`, `HotjarLegal`, `GTMLegal`, `EmailJSLegal`
324
- - Hook: `useConsent`, `useConsentCategory`, `useIsHydrated`, `useGAEvent`, `useAdsConversion`, `useMetaEvent`, `useHotjarEvent`, `useHotjarIdentify`, `useEmailJS`, `useT`, `useLegalLanguage`
325
- - UI: `ConsentBanner`, `PreferenceModal`, `FloatingConsentToggle`, `ConsentGate`, `ConsentCheckbox`, `ServiceGrid`
326
- - Azioni: `acceptAll`, `declineAll`, `savePreferences`, `resetConsent`, `setModalOpen`, `setLanguage`
327
- - Primitive: `subscribeConsent`, `getConsentSnapshot`, `CONSENT_TTL_MS`, `SERVICE_PRESETS`
328
-
329
- **`@graffico/legal/next`** — `withLegal`, `emitNetlifyHeaders`, `buildLegalHeaders`, `buildCspFromConfig`.
330
-
331
- ---
332
-
333
- ## Requisiti
334
-
335
- - React ≥ 18 (App Router consigliato)
336
- - Tailwind opzionale (la UI usa classi Tailwind)
337
- - `@emailjs/browser` ≥ 4 — peer optional, solo se usi `EmailJSLegal`
338
-
339
- ---
340
-
341
- Made by **Graffico Studio**.
1
+ # @graffico/legal
2
+
3
+ CMP GDPR drop-in per React / Next.js. Banner + modale, policy server-rendered, **tracker terzi che caricano solo dopo consenso**, plugin Next.js per security headers.
4
+
5
+ ```bash
6
+ pnpm add @graffico/legal
7
+ ```
8
+
9
+ ---
10
+
11
+ ## 1. Setup minimo
12
+
13
+ `src/config/legal.ts`:
14
+
15
+ ```ts
16
+ import type { CompanyConfig } from "@graffico/legal";
17
+
18
+ export const legalConfig: CompanyConfig = {
19
+ name: "Mia Azienda",
20
+ domain: "azienda.it",
21
+ owners: "Mario Rossi",
22
+ addresses: "Via Roma 1, Milano",
23
+ vatNumbers: "01234567890",
24
+ email: "privacy@azienda.it",
25
+ policyVersion: "2026.05", // cambiarla invalida i consensi vecchi
26
+ services: ["google-analytics", "facebook-pixel", "contact-form"],
27
+ primaryColor: "#2c5282",
28
+ language: "it",
29
+ };
30
+ ```
31
+
32
+ `app/layout.tsx`:
33
+
34
+ ```tsx
35
+ import { LegalProvider } from "@graffico/legal/server";
36
+ import { legalConfig } from "@/config/legal";
37
+
38
+ export default function RootLayout({ children }) {
39
+ return (
40
+ <html>
41
+ <body>
42
+ <LegalProvider config={legalConfig}>{children}</LegalProvider>
43
+ </body>
44
+ </html>
45
+ );
46
+ }
47
+ ```
48
+
49
+ `<LegalProvider>` monta automaticamente banner + modale + floating toggle.
50
+
51
+ ### Tailwind / globals.css
52
+
53
+ La libreria usa Tailwind utility classes inline (niente CSS bundle). Devi dire al JIT di Tailwind di scansionare i file della libreria, altrimenti banner e modale appariranno senza stili.
54
+
55
+ **Tailwind v4** — aggiungi una direttiva `@source` in `src/app/globals.css` (o equivalente):
56
+
57
+ ```css
58
+ @import "tailwindcss";
59
+ @source "../../node_modules/@graffico/legal/dist/**/*.{js,cjs}";
60
+ ```
61
+
62
+ > Il path `../../` parte da `src/app/`. Se il tuo `globals.css` sta altrove, regola la profondità relativa. In monorepo con workspace, il dist è raggiungibile via `node_modules` simlink.
63
+
64
+ **Tailwind v3** — aggiungi al `tailwind.config.js`:
65
+
66
+ ```js
67
+ module.exports = {
68
+ content: [
69
+ "./src/**/*.{js,ts,jsx,tsx}",
70
+ "./node_modules/@graffico/legal/dist/**/*.{js,cjs}",
71
+ ],
72
+ };
73
+ ```
74
+
75
+ ---
76
+
77
+ ## 2. Tracker — drop-in con consenso integrato
78
+
79
+ Importi il componente Legal, passi le API key. Lo script parte **solo dopo consenso**.
80
+
81
+ ```tsx
82
+ import {
83
+ ConsentModeBoot,
84
+ GoogleAnalyticsLegal,
85
+ GoogleAdsLegal,
86
+ MetaPixelLegal,
87
+ HotjarLegal,
88
+ GTMLegal,
89
+ EmailJSLegal,
90
+ } from "@graffico/legal";
91
+
92
+ <LegalProvider config={legalConfig}>
93
+ <ConsentModeBoot /> {/* Google Consent Mode v2 default = denied */}
94
+ <GoogleAnalyticsLegal gaId="G-XXXX" />
95
+ <GoogleAdsLegal
96
+ conversionId="AW-XXXX"
97
+ conversions={{ formSubmit: { sendTo: "AW-XXXX/abc", value: 1, currency: "EUR" } }}
98
+ />
99
+ <MetaPixelLegal pixelId="123456" events={["Lead", "Contact"]} />
100
+ <HotjarLegal siteId={1234567} />
101
+ <EmailJSLegal
102
+ serviceId={process.env.NEXT_PUBLIC_EMAILJS_SERVICE_ID!}
103
+ templateId={process.env.NEXT_PUBLIC_EMAILJS_TEMPLATE_ID!}
104
+ publicKey={process.env.NEXT_PUBLIC_EMAILJS_USER_ID!}
105
+ />
106
+ {children}
107
+ </LegalProvider>
108
+ ```
109
+
110
+ | Componente | Categoria default | Script gated | Note |
111
+ |---|---|---|---|
112
+ | `ConsentModeBoot` | — | — | Boot gtag stub + Consent Mode v2. **Sempre per primo.** |
113
+ | `GoogleAnalyticsLegal` | `statistical` | `gtag/js?id=G-…` | Anonymize IP on di default. |
114
+ | `GoogleAdsLegal` | `marketing` | `gtag/js?id=AW-…` | Mappa conversioni dichiarativa. |
115
+ | `MetaPixelLegal` | `marketing` | `fbevents.js` | Whitelist `events` opzionale. Su revoca → `fbq('consent','revoke')`. |
116
+ | `HotjarLegal` | `statistical` | `static.hotjar.com/c/hotjar-…` | Session recording + heatmap. |
117
+ | `GTMLegal` | `marketing` | `gtm.js?id=GTM-…` | Lascia ai tag interni la granularità. |
118
+ | `EmailJSLegal` | — (art. 6.1.b) | — | Config holder per `useEmailJS()`. |
119
+
120
+ ---
121
+
122
+ ## 3. Hook trigger eventi
123
+
124
+ Nei tuoi componenti `"use client"`:
125
+
126
+ ```tsx
127
+ import { useGAEvent, useMetaEvent, useAdsConversion, useHotjarEvent } from "@graffico/legal";
128
+
129
+ const trackGA = useGAEvent();
130
+ const trackLead = useMetaEvent("Lead");
131
+ const fireConversion = useAdsConversion("formSubmit");
132
+ const trackHj = useHotjarEvent();
133
+
134
+ // Tutti diventano no-op senza consenso — chiama liberamente
135
+ trackGA("button_click", { id: "hero" });
136
+ trackLead({ value: 99, currency: "EUR" });
137
+ fireConversion();
138
+ trackHj("scroll_to_pricing");
139
+ ```
140
+
141
+ ---
142
+
143
+ ## 4. Form contatto con consenso
144
+
145
+ ```tsx
146
+ "use client";
147
+ import { useEmailJS, ConsentCheckbox } from "@graffico/legal";
148
+
149
+ export function ContactForm() {
150
+ const { send, status } = useEmailJS();
151
+
152
+ async function onSubmit(e: React.FormEvent<HTMLFormElement>) {
153
+ e.preventDefault();
154
+ const res = await send(e.currentTarget);
155
+ if (!res.ok) console.warn(res.error); // CONSENT_MISSING | CONFIG_MISSING | SEND_FAILED
156
+ }
157
+
158
+ return (
159
+ <form onSubmit={onSubmit}>
160
+ <input name="name" required />
161
+ <input name="email" type="email" required />
162
+ <textarea name="message" required />
163
+ <ConsentCheckbox /> {/* obbligatorio: blocca submit se non spuntato */}
164
+ <button disabled={status === "loading"}>Invia</button>
165
+ </form>
166
+ );
167
+ }
168
+ ```
169
+
170
+ `send()` inietta automaticamente nel payload mail: `_consentId`, `_consentTimestamp`, `_policyVersion` (prova legale art. 7.1).
171
+
172
+ ---
173
+
174
+ ## 5. Pagine policy
175
+
176
+ Auto-renderizzate dalla config — incluse sezioni Processors / Transfers / Retention / DPO se valorizzati.
177
+
178
+ ```tsx
179
+ // app/privacy-policy/page.tsx
180
+ import { PrivacyPolicy } from "@graffico/legal/server";
181
+ import { legalConfig } from "@/config/legal";
182
+ export default () => <PrivacyPolicy config={legalConfig} />;
183
+
184
+ // app/cookie-policy/page.tsx
185
+ import { CookiePolicy } from "@graffico/legal/server";
186
+ export default () => <CookiePolicy config={legalConfig} />;
187
+ ```
188
+
189
+ ---
190
+
191
+ ## 6. Gate per embed terzi
192
+
193
+ ```tsx
194
+ import { ConsentGate, useConsentCategory } from "@graffico/legal";
195
+
196
+ <ConsentGate
197
+ category="marketing"
198
+ fallback={<p>Abilita cookie marketing per vedere il video.</p>}
199
+ >
200
+ <iframe src="https://youtube.com/embed/…" />
201
+ </ConsentGate>
202
+ ```
203
+
204
+ ---
205
+
206
+ ## 7. Next.js plugin — security headers
207
+
208
+ CSP derivata dai `services[]` + `processors[]`. HSTS, X-Frame, Permissions-Policy, COOP, Referrer-Policy.
209
+
210
+ ```ts
211
+ // next.config.ts
212
+ import { withLegal } from "@graffico/legal/next";
213
+ import { legalConfig } from "@/config/legal";
214
+
215
+ const nextConfig = { /* … */ };
216
+
217
+ export default withLegal(nextConfig, legalConfig, {
218
+ cspReportOnly: process.env.CSP_ENFORCE !== "1", // rollout: 7gg report-only → enforce
219
+ });
220
+ ```
221
+
222
+ Per `netlify.toml`:
223
+
224
+ ```ts
225
+ import { emitNetlifyHeaders } from "@graffico/legal/next";
226
+ console.log(emitNetlifyHeaders(legalConfig));
227
+ ```
228
+
229
+ ---
230
+
231
+ ## 8. `CompanyConfig`
232
+
233
+ ```ts
234
+ interface CompanyConfig {
235
+ name: string;
236
+ domain: string;
237
+ owners: string;
238
+ addresses: string | string[];
239
+ vatNumbers: string | string[];
240
+ email: string;
241
+
242
+ policyVersion?: string; // cambiarla invalida i consensi pregressi
243
+ lastUpdated?: string; // ISO date, default oggi
244
+
245
+ services?: ServiceReference[]; // tracker dichiarati (preset id o oggetto)
246
+ processors?: Processor[]; // destinatari/responsabili esterni
247
+ retention?: RetentionMap; // tempi di conservazione per categoria
248
+ dpo?: DpoInfo; // se nominato (art. 37 GDPR)
249
+
250
+ theme?: "light" | "dark";
251
+ primaryColor?: string;
252
+ language?: "it" | "en";
253
+ togglePosition?: "bottom-right" | "bottom-left" | "top-right" | "top-left";
254
+ }
255
+
256
+ interface Processor {
257
+ name: string;
258
+ purpose: string;
259
+ country: string;
260
+ transferBasis?: string; // "DPF + SCC 2021/914", "SCC", …
261
+ privacyUrl?: string;
262
+ }
263
+
264
+ interface RetentionMap {
265
+ contactForms?: string; // "90d"
266
+ analytics?: string; // "14m"
267
+ marketing?: string; // "2y"
268
+ [k: string]: string | undefined;
269
+ }
270
+
271
+ interface DpoInfo {
272
+ name: string;
273
+ email: string;
274
+ phone?: string;
275
+ }
276
+ ```
277
+
278
+ ---
279
+
280
+ ## 9. Conformità GDPR / ePrivacy — cosa fa già la lib
281
+
282
+ - **TTL consenso 180 giorni** (`CONSENT_TTL_MS`), allineato al Garante 10/06/2021. Scaduto → re-prompt.
283
+ - **Re-prompt automatico** al cambio `policyVersion`.
284
+ - **Auto-decline su GPC / DNT** (`navigator.globalPrivacyControl`, `Sec-GPC`) senza UI.
285
+ - **Prova legale**: `consentId` UUID + `timestamp` ISO + `policyVersion` + `source` in localStorage e nel payload mail.
286
+ - **Parità grafica reject/accept** nel banner (Garante 10/06/2021 §4).
287
+ - **Categorie indipendenti**: `necessary` / `statistical` / `marketing`. Default OFF.
288
+ - **Niente cookie wall**: il sito resta fruibile senza consenso.
289
+ - **Zero telemetria** della libreria stessa.
290
+
291
+ ---
292
+
293
+ ## 10. Service preset (id stringa per `services[]`)
294
+
295
+ | Categoria | Id |
296
+ |---|---|
297
+ | Analytics | `google-analytics`, `microsoft-clarity`, `hotjar` |
298
+ | Marketing | `facebook-pixel`, `google-ads`, `linkedin-insight`, `tiktok-pixel` |
299
+ | Tag manager | `google-tag-manager` |
300
+ | Pagamenti | `stripe`, `paypal` |
301
+ | Contenuti | `youtube`, `google-maps`, `google-fonts` |
302
+ | Form / mail | `contact-form`, `mailchimp`, `newsletter` |
303
+
304
+ Servizio inline custom:
305
+
306
+ ```ts
307
+ {
308
+ id: "crm",
309
+ name: "CRM Interno",
310
+ category: "provided", // "automatic" | "provided" | "marketing"
311
+ purposes: ["Gestione clienti"],
312
+ dataCollected: ["Email", "Nome"],
313
+ }
314
+ ```
315
+
316
+ ---
317
+
318
+ ## 11. API export
319
+
320
+ **`@graffico/legal/server`** — `LegalProvider`, `PrivacyPolicy`, `CookiePolicy`.
321
+
322
+ **`@graffico/legal`** (client) —
323
+ - Tracker: `ConsentModeBoot`, `GoogleAnalyticsLegal`, `GoogleAdsLegal`, `MetaPixelLegal`, `HotjarLegal`, `GTMLegal`, `EmailJSLegal`
324
+ - Hook: `useConsent`, `useConsentCategory`, `useIsHydrated`, `useGAEvent`, `useAdsConversion`, `useMetaEvent`, `useHotjarEvent`, `useHotjarIdentify`, `useEmailJS`, `useT`, `useLegalLanguage`
325
+ - UI: `ConsentBanner`, `PreferenceModal`, `FloatingConsentToggle`, `ConsentGate`, `ConsentCheckbox`, `ServiceGrid`
326
+ - Azioni: `acceptAll`, `declineAll`, `savePreferences`, `resetConsent`, `setModalOpen`, `setLanguage`
327
+ - Primitive: `subscribeConsent`, `getConsentSnapshot`, `CONSENT_TTL_MS`, `SERVICE_PRESETS`
328
+
329
+ **`@graffico/legal/next`** — `withLegal`, `emitNetlifyHeaders`, `buildLegalHeaders`, `buildCspFromConfig`.
330
+
331
+ ---
332
+
333
+ ## Requisiti
334
+
335
+ - React ≥ 18 (App Router consigliato)
336
+ - Tailwind opzionale (la UI usa classi Tailwind)
337
+ - `@emailjs/browser` ≥ 4 — peer optional, solo se usi `EmailJSLegal`
338
+
339
+ ---
340
+
341
+ Made by **Graffico Studio**.