react-lgpd-consent 0.9.6 → 0.9.8

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/API.md CHANGED
@@ -8,46 +8,46 @@ Este documento é a referência técnica oficial para a API da biblioteca `react
8
8
 
9
9
  ## Exports Principais
10
10
 
11
- | Nome | Tipo | Descrição |
12
- | ----------------------------------- | ---------- | ------------------------------------------------------------------------------- |
13
- | `ConsentProvider` | Componente | O provedor de contexto principal que gerencia todo o estado e a UI. |
14
- | `useConsent` | Hook | Hook principal para interagir com o estado de consentimento. |
15
- | `useCategories` | Hook | Retorna a lista de categorias ativas no projeto. |
16
- | `useCategoryStatus` | Hook | Verifica o status de uma categoria específica. |
17
- | `useOpenPreferencesModal` | Hook | Retorna uma função para abrir o modal de preferências de forma programática. |
18
- | `openPreferencesModal` | Função | Versão da função acima para ser usada fora do contexto React. |
19
- | `ConsentGate` | Componente | Renderiza componentes filhos apenas se uma categoria de cookie for consentida. |
11
+ | Nome | Tipo | Descrição |
12
+ | ----------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------- |
13
+ | `ConsentProvider` | Componente | O provedor de contexto principal que gerencia todo o estado e a UI. |
14
+ | `useConsent` | Hook | Hook principal para interagir com o estado de consentimento. |
15
+ | `useCategories` | Hook | Retorna a lista de categorias ativas no projeto. |
16
+ | `useCategoryStatus` | Hook | Verifica o status de uma categoria específica. |
17
+ | `useOpenPreferencesModal` | Hook | Retorna uma função para abrir o modal de preferências de forma programática. |
18
+ | `openPreferencesModal` | Função | Versão da função acima para ser usada fora do contexto React. |
19
+ | `ConsentGate` | Componente | Renderiza componentes filhos apenas se uma categoria de cookie for consentida. |
20
20
  | `ConsentScriptLoader` | Componente | Carrega scripts de terceiros (como Google Analytics) com base no consentimento. Suporta Consent Mode v2 automático. |
21
- | `registerScript()` | Função | Registra um script na fila global para execução condicional ao consentimento. Retorna função de cleanup. |
22
- | `RegisteredScript` | Tipo | Interface para scripts registrados programaticamente (id, category, execute, priority, onConsentUpdate). |
23
- | `buildConsentStorageKey` | Função | (v0.5.2) Gera nomes de cookies `namespace__vX` a partir de namespace/versão. |
24
- | `createGoogleAnalyticsIntegration` | Função | Factory para integração nativa com o Google Analytics. |
25
- | `createGoogleTagManagerIntegration` | Função | Factory para integração nativa com o Google Tag Manager. |
26
- | `createUserWayIntegration` | Função | Factory para integração nativa com o UserWay. |
27
- | `createFacebookPixelIntegration` | Função | (v0.4.1) Integração nativa com Facebook Pixel. |
28
- | `createHotjarIntegration` | Função | (v0.4.1) Integração nativa com Hotjar. |
29
- | `createMixpanelIntegration` | Função | (v0.4.1) Integração nativa com Mixpanel. |
30
- | `createClarityIntegration` | Função | (v0.4.1) Integração nativa com Microsoft Clarity. |
31
- | `createIntercomIntegration` | Função | (v0.4.1) Integração nativa com Intercom (chat). |
32
- | `createZendeskChatIntegration` | Função | (v0.4.1) Integração nativa com Zendesk Chat. |
33
- | `createSuggestedIntegration` | Função | (v0.7.2) Cria integração customizada com categoria sugerida automaticamente. |
34
- | `suggestCategoryForScript` | Função | (v0.4.1) Sugere categoria(s) LGPD para um script conhecido. |
35
- | `discoverRuntimeCookies` | Função | (v0.4.1) Descobre cookies em tempo real no navegador. |
36
- | `categorizeDiscoveredCookies` | Função | (v0.4.1) Categoriza cookies descobertos usando padrões LGPD. |
37
- | `getCookiesInfoForCategory` | Função | Retorna informações detalhadas dos cookies de uma categoria específica. |
38
- | `resolveTexts` | Função | (v0.4.1) Resolve textos baseados em templates e contexto. |
39
- | `createConsentAuditEntry` | Função | **(v0.7.0)** Cria entrada de auditoria de consentimento para logs. |
40
- | `ANPD_CATEGORY_PRESETS` | Constante | **(v0.7.0)** Presets de categorias conforme diretrizes LGPD/ANPD. |
41
- | `createAnpdCategoriesConfig` | Função | **(v0.7.0)** Helper para gerar configurações tipadas com presets ANPD. |
42
- | `TEXT_TEMPLATES` | Constante | (v0.4.1) Templates pré-configurados (ecommerce, saas, governo). |
43
- | `AdvancedConsentTexts` | Tipo | (v0.4.1) Interface expandida com i18n e contextos. |
44
- | `DesignTokens` | Tipo | (v0.4.1) Sistema completo com 200+ pontos de customização. |
45
- | `createECommerceIntegrations` | Função | (v0.4.1) Cria integrações comuns para e-commerce. |
46
- | `createSaaSIntegrations` | Função | (v0.4.1) Cria integrações comuns para SaaS. |
47
- | `createCorporateIntegrations` | Função | (v0.4.1) Cria integrações comuns para ambientes corporativos. |
48
- | `INTEGRATION_TEMPLATES` | Constante | (v0.4.1) Presets com IDs essenciais/opcionais e categorias por tipo de negócio. |
49
- | `SuggestedIntegrationConfig` | Tipo | (v0.7.2) Configuração para integração customizada com categoria sugerida. |
50
- | `setDebugLogging` | Função | Habilita/desabilita o logging de debug da biblioteca. |
21
+ | `registerScript()` | Função | Registra um script na fila global para execução condicional ao consentimento. Retorna função de cleanup. |
22
+ | `RegisteredScript` | Tipo | Interface para scripts registrados programaticamente (id, category, execute, priority, onConsentUpdate). |
23
+ | `buildConsentStorageKey` | Função | (v0.5.2) Gera nomes de cookies `namespace__vX` a partir de namespace/versão. |
24
+ | `createGoogleAnalyticsIntegration` | Função | Factory para integração nativa com o Google Analytics. |
25
+ | `createGoogleTagManagerIntegration` | Função | Factory para integração nativa com o Google Tag Manager. |
26
+ | `createUserWayIntegration` | Função | Factory para integração nativa com o UserWay. |
27
+ | `createFacebookPixelIntegration` | Função | (v0.4.1) Integração nativa com Facebook Pixel. |
28
+ | `createHotjarIntegration` | Função | (v0.4.1) Integração nativa com Hotjar. |
29
+ | `createMixpanelIntegration` | Função | (v0.4.1) Integração nativa com Mixpanel. |
30
+ | `createClarityIntegration` | Função | (v0.4.1) Integração nativa com Microsoft Clarity. |
31
+ | `createIntercomIntegration` | Função | (v0.4.1) Integração nativa com Intercom (chat). |
32
+ | `createZendeskChatIntegration` | Função | (v0.4.1) Integração nativa com Zendesk Chat. |
33
+ | `createSuggestedIntegration` | Função | (v0.7.2) Cria integração customizada com categoria sugerida automaticamente. |
34
+ | `suggestCategoryForScript` | Função | (v0.4.1) Sugere categoria(s) LGPD para um script conhecido. |
35
+ | `discoverRuntimeCookies` | Função | (v0.4.1) Descobre cookies em tempo real no navegador. |
36
+ | `categorizeDiscoveredCookies` | Função | (v0.4.1) Categoriza cookies descobertos usando padrões LGPD. |
37
+ | `getCookiesInfoForCategory` | Função | Retorna informações detalhadas dos cookies de uma categoria específica. |
38
+ | `resolveTexts` | Função | (v0.4.1) Resolve textos baseados em templates e contexto. |
39
+ | `createConsentAuditEntry` | Função | **(v0.7.0)** Cria entrada de auditoria de consentimento para logs. |
40
+ | `ANPD_CATEGORY_PRESETS` | Constante | **(v0.7.0)** Presets de categorias conforme diretrizes LGPD/ANPD. |
41
+ | `createAnpdCategoriesConfig` | Função | **(v0.7.0)** Helper para gerar configurações tipadas com presets ANPD. |
42
+ | `TEXT_TEMPLATES` | Constante | (v0.4.1) Templates pré-configurados (ecommerce, saas, governo). |
43
+ | `AdvancedConsentTexts` | Tipo | (v0.4.1) Interface expandida com i18n e contextos. |
44
+ | `DesignTokens` | Tipo | (v0.4.1) Sistema completo com 200+ pontos de customização. |
45
+ | `createECommerceIntegrations` | Função | (v0.4.1) Cria integrações comuns para e-commerce. |
46
+ | `createSaaSIntegrations` | Função | (v0.4.1) Cria integrações comuns para SaaS. |
47
+ | `createCorporateIntegrations` | Função | (v0.4.1) Cria integrações comuns para ambientes corporativos. |
48
+ | `INTEGRATION_TEMPLATES` | Constante | (v0.4.1) Presets com IDs essenciais/opcionais e categorias por tipo de negócio. |
49
+ | `SuggestedIntegrationConfig` | Tipo | (v0.7.2) Configuração para integração customizada com categoria sugerida. |
50
+ | `setDebugLogging` | Função | Habilita/desabilita o logging de debug da biblioteca. |
51
51
 
52
52
  ---
53
53
 
@@ -71,7 +71,10 @@ O pacote publica **dual build** (ESM + CJS) via `exports`:
71
71
  module.exports = {
72
72
  testEnvironment: 'jsdom',
73
73
  transform: {
74
- '^.+\\.(t|j)sx?$': ['babel-jest', { presets: ['@babel/preset-env', '@babel/preset-react', '@babel/preset-typescript'] }],
74
+ '^.+\\.(t|j)sx?$': [
75
+ 'babel-jest',
76
+ { presets: ['@babel/preset-env', '@babel/preset-react', '@babel/preset-typescript'] },
77
+ ],
75
78
  },
76
79
  transformIgnorePatterns: ['/node_modules/(?!react-lgpd-consent|@react-lgpd-consent)/'],
77
80
  }
@@ -116,9 +119,7 @@ import { ConsentProvider } from 'react-lgpd-consent'
116
119
 
117
120
  function App() {
118
121
  return (
119
- <ConsentProvider
120
- categories={{ enabledCategories: ['analytics', 'marketing'] }}
121
- >
122
+ <ConsentProvider categories={{ enabledCategories: ['analytics', 'marketing'] }}>
122
123
  {/* Seu aplicativo aqui */}
123
124
  </ConsentProvider>
124
125
  )
@@ -127,35 +128,35 @@ function App() {
127
128
 
128
129
  **Todas as Props:**
129
130
 
130
- | Prop | Tipo | Descrição |
131
- | --- | --- | --- |
132
- | `categories` | `ProjectCategoriesConfig` | **Obrigatório.** Fonte única de verdade sobre as categorias habilitadas; usada por UI, hooks e integrações. |
133
- | `texts` | `Partial<AdvancedConsentTexts>` | Customiza todos os textos exibidos (banner, modal, botão). |
134
- | `language` | `'pt' \| 'en' \| 'es' \| 'fr' \| 'de' \| 'it'` | Resolve textos via i18n no Provider. |
135
- | `textVariant` | `'formal' \| 'casual' \| 'concise' \| 'detailed'` | Aplica variação de tom sobre os textos base. |
136
- | `designTokens` | `DesignTokens` | Ajuste visual granular (cores, spacing, tipografia, overlays). |
137
- | `blocking` | `boolean` | Ativa overlay bloqueante até o usuário decidir. Padrão: `false`. |
138
- | `blockingMode` | `'soft' \| 'hard'` | Intensidade do bloqueio; `hard` torna o conteúdo da aplicação inerte (sem foco/teclado). |
139
- | `blockingStrategy` | `'auto' \| 'provider' \| 'component'` | Controla quem desenha o overlay quando `blocking` está ativo. |
140
- | `hideBranding` | `boolean` | Oculta o selo “fornecido por”. |
141
- | `disableDeveloperGuidance` | `boolean` | Suprime avisos/sugestões no console em desenvolvimento. |
142
- | `disableFloatingPreferencesButton` | `boolean` | Remove o botão flutuante padrão. |
143
- | `onConsentGiven` | `(state: ConsentState) => void` | Dispara na primeira vez que o usuário aceita/rejeita. Útil para inicializar analytics. |
144
- | `onPreferencesSaved` | `(prefs: ConsentPreferences) => void` | Executa toda vez que o usuário salva preferências no modal. |
145
- | `onConsentInit` | `(state: ConsentState) => void` | **(v0.7.0)** Callback executado após hidratação inicial do consentimento. |
146
- | `onConsentChange` | `(state: ConsentState, previous: ConsentState) => void` | **(v0.7.0)** Callback executado sempre que o estado de consentimento muda. |
147
- | `onAuditLog` | `(entry: ConsentAuditEntry) => void` | **(v0.7.0)** Callback para registrar eventos de auditoria (init, update, reset). |
148
- | `cookie` | `Partial<ConsentCookieOptions>` | Override fino das opções de cookie (nome, expiração, sameSite, secure, path, domain). Se `name` não for informado, o valor deriva de `storage`. |
149
- | `storage` | `ConsentStorageConfig` | Define namespace, versão e domínio compartilhado. Gera automaticamente o nome da chave (`namespace__vX`). Alterar `version` força re-consentimento. |
150
- | `onConsentVersionChange` | `(context: ConsentVersionChangeContext) => void` | Notificado após mudança da chave de storage. O reset já é automático; use o hook para limpar caches externos ou registrar eventos. |
151
- | `CookieBannerComponent` | `React.ComponentType<CustomCookieBannerProps>` | Substitui o banner padrão. |
152
- | `PreferencesModalComponent` | `React.ComponentType<CustomPreferencesModalProps>` | Substitui o modal padrão. |
153
- | `FloatingPreferencesButtonComponent` | `React.ComponentType<CustomFloatingPreferencesButtonProps>` | Substitui o botão flutuante padrão. |
154
- | `cookieBannerProps` | `Record<string, unknown>` | Props adicionais repassadas ao banner (padrão `{}`). |
155
- | `preferencesModalProps` | `Record<string, unknown>` | Props adicionais repassadas ao modal (padrão `{}`). |
156
- | `floatingPreferencesButtonProps` | `Record<string, unknown>` | Props adicionais para o botão flutuante (padrão `{}`). |
157
- | `theme` | `any` (Tema MUI) | Aplica um `ThemeProvider` local aos componentes padrão (apenas no pacote MUI). |
158
- | `initialState` | `ConsentState` | Hidratação SSR para evitar flash do banner. |
131
+ | Prop | Tipo | Descrição |
132
+ | ------------------------------------ | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
133
+ | `categories` | `ProjectCategoriesConfig` | **Obrigatório.** Fonte única de verdade sobre as categorias habilitadas; usada por UI, hooks e integrações. |
134
+ | `texts` | `Partial<AdvancedConsentTexts>` | Customiza todos os textos exibidos (banner, modal, botão). |
135
+ | `language` | `'pt' \| 'en' \| 'es' \| 'fr' \| 'de' \| 'it'` | Resolve textos via i18n no Provider. |
136
+ | `textVariant` | `'formal' \| 'casual' \| 'concise' \| 'detailed'` | Aplica variação de tom sobre os textos base. |
137
+ | `designTokens` | `DesignTokens` | Ajuste visual granular (cores, spacing, tipografia, overlays). |
138
+ | `blocking` | `boolean` | Ativa overlay bloqueante até o usuário decidir. Padrão: `false`. |
139
+ | `blockingMode` | `'soft' \| 'hard'` | Intensidade do bloqueio; `hard` torna o conteúdo da aplicação inerte (sem foco/teclado). |
140
+ | `blockingStrategy` | `'auto' \| 'provider' \| 'component'` | Controla quem desenha o overlay quando `blocking` está ativo. |
141
+ | `hideBranding` | `boolean` | Oculta o selo “fornecido por”. |
142
+ | `disableDeveloperGuidance` | `boolean` | Suprime avisos/sugestões no console em desenvolvimento. |
143
+ | `disableFloatingPreferencesButton` | `boolean` | Remove o botão flutuante padrão. |
144
+ | `onConsentGiven` | `(state: ConsentState) => void` | Dispara na primeira vez que o usuário aceita/rejeita. Útil para inicializar analytics. |
145
+ | `onPreferencesSaved` | `(prefs: ConsentPreferences) => void` | Executa toda vez que o usuário salva preferências no modal. |
146
+ | `onConsentInit` | `(state: ConsentState) => void` | **(v0.7.0)** Callback executado após hidratação inicial do consentimento. |
147
+ | `onConsentChange` | `(state: ConsentState, previous: ConsentState) => void` | **(v0.7.0)** Callback executado sempre que o estado de consentimento muda. |
148
+ | `onAuditLog` | `(entry: ConsentAuditEntry) => void` | **(v0.7.0)** Callback para registrar eventos de auditoria (init, update, reset). |
149
+ | `cookie` | `Partial<ConsentCookieOptions>` | Override fino das opções de cookie (nome, expiração, sameSite, secure, path, domain). Se `name` não for informado, o valor deriva de `storage`. |
150
+ | `storage` | `ConsentStorageConfig` | Define namespace, versão e domínio compartilhado. Gera automaticamente o nome da chave (`namespace__vX`). Alterar `version` força re-consentimento. |
151
+ | `onConsentVersionChange` | `(context: ConsentVersionChangeContext) => void` | Notificado após mudança da chave de storage. O reset já é automático; use o hook para limpar caches externos ou registrar eventos. |
152
+ | `CookieBannerComponent` | `React.ComponentType<CustomCookieBannerProps>` | Substitui o banner padrão. |
153
+ | `PreferencesModalComponent` | `React.ComponentType<CustomPreferencesModalProps>` | Substitui o modal padrão. |
154
+ | `FloatingPreferencesButtonComponent` | `React.ComponentType<CustomFloatingPreferencesButtonProps>` | Substitui o botão flutuante padrão. |
155
+ | `cookieBannerProps` | `Record<string, unknown>` | Props adicionais repassadas ao banner (padrão `{}`). |
156
+ | `preferencesModalProps` | `Record<string, unknown>` | Props adicionais repassadas ao modal (padrão `{}`). |
157
+ | `floatingPreferencesButtonProps` | `Record<string, unknown>` | Props adicionais para o botão flutuante (padrão `{}`). |
158
+ | `theme` | `any` (Tema MUI) | Aplica um `ThemeProvider` local aos componentes padrão (apenas no pacote MUI). |
159
+ | `initialState` | `ConsentState` | Hidratação SSR para evitar flash do banner. |
159
160
 
160
161
  #### Versionamento de consentimento (namespace + versão)
161
162
 
@@ -181,7 +182,11 @@ function ConsentBoundary({ children }: { children: React.ReactNode }) {
181
182
  // Opcional: persistir um nome de auditoria específico
182
183
  name: buildConsentStorageKey({ namespace: 'acme-suite', version: '2025-Q4' }),
183
184
  }}
184
- onConsentVersionChange={({ previousKey, nextKey, resetConsent }: ConsentVersionChangeContext) => {
185
+ onConsentVersionChange={({
186
+ previousKey,
187
+ nextKey,
188
+ resetConsent,
189
+ }: ConsentVersionChangeContext) => {
185
190
  audit.log('consent:bump', { previousKey, nextKey })
186
191
  localStorage.removeItem('marketingOverrides')
187
192
  resetConsent()
@@ -235,9 +240,11 @@ function MyComponent() {
235
240
  Gerencia o carregamento de scripts de terceiros (ex: Google Analytics) com base no consentimento do usuário. Veja o guia `INTEGRACOES.md` para mais detalhes.
236
241
 
237
242
  **Novidades v0.7.1:**
243
+
238
244
  - ✨ **Google Consent Mode v2 automático**: GA4 e GTM agora enviam `consent('default', 'denied')` no bootstrap e `consent('update', 'granted')` após consentimento
239
245
  - 🎯 **Sistema de fila com prioridade**: Scripts são executados ordenadamente (necessary → categoria → prioridade → timestamp)
240
246
  - 🔄 **Callbacks de atualização**: `onConsentUpdate` dispara quando preferências mudam
247
+ - 🔗 **Compatibilidade externa revisada**: GTM respeita `dataLayerName` na URL, Clarity usa Consent API v2, Intercom sincroniza `update`/`shutdown`, e Zendesk usa a API Messaging de cookies
241
248
 
242
249
  ```tsx
243
250
  import { ConsentScriptLoader, createGoogleAnalyticsIntegration, registerScript } from 'react-lgpd-consent'
@@ -265,6 +272,13 @@ const cleanup = registerScript({
265
272
  // Scripts só reexecutam se allowReload=true; sempre use o cleanup ao desmontar.
266
273
  ```
267
274
 
275
+ Integrações com opções específicas:
276
+
277
+ - `createGoogleTagManagerIntegration({ dataLayerName })`: quando o layer não é `dataLayer`, a URL do `gtm.js` recebe `&l=<dataLayerName>`.
278
+ - `createClarityIntegration({ consentMode, analyticsStorageCategory, adStorageCategory })`: envia `clarity('consentv2', ...)` em mudanças de consentimento.
279
+ - `createIntercomIntegration({ api_base, settings, updateOnConsent, shutdownOnRevoke })`: configura região/settings e sincroniza lifecycle do Messenger.
280
+ - `createZendeskChatIntegration({ cookieRange, syncCookies })`: sincroniza cookies com `zE('messenger:set', 'cookies', ...)`.
281
+
268
282
  ---
269
283
 
270
284
  ## Hooks
@@ -275,17 +289,17 @@ O hook principal para interagir com o estado de consentimento.
275
289
 
276
290
  **Retorno:**
277
291
 
278
- | Chave | Tipo | Descrição |
279
- | ----------------- | ------------------------------------- | ---------------------------------------------------------------------------------------- |
280
- | `consented` | `boolean` | `true` se o usuário já interagiu com o banner/modal. |
281
- | `preferences` | `ConsentPreferences` | Um objeto com o estado de consentimento para cada categoria (ex: `{ analytics: true }`). |
282
- | `isModalOpen` | `boolean` | `true` se o modal de preferências estiver aberto. |
283
- | `acceptAll` | `() => void` | Aceita todas as categorias de cookies. |
284
- | `rejectAll` | `() => void` | Rejeita todas as categorias não essenciais. |
285
- | `setPreference` | `(cat: string, value: boolean) => void` | Define consentimento para uma categoria específica (predefinida ou customizada). |
286
- | `setPreferences` | `(prefs: ConsentPreferences) => void` | Salva um novo conjunto de preferências. |
287
- | `openPreferences` | `() => void` | Abre o modal de preferências. |
288
- | `resetConsent` | `() => void` | Reseta o consentimento, fazendo o banner aparecer novamente. |
292
+ | Chave | Tipo | Descrição |
293
+ | ----------------- | --------------------------------------- | ---------------------------------------------------------------------------------------- |
294
+ | `consented` | `boolean` | `true` se o usuário já interagiu com o banner/modal. |
295
+ | `preferences` | `ConsentPreferences` | Um objeto com o estado de consentimento para cada categoria (ex: `{ analytics: true }`). |
296
+ | `isModalOpen` | `boolean` | `true` se o modal de preferências estiver aberto. |
297
+ | `acceptAll` | `() => void` | Aceita todas as categorias de cookies. |
298
+ | `rejectAll` | `() => void` | Rejeita todas as categorias não essenciais. |
299
+ | `setPreference` | `(cat: string, value: boolean) => void` | Define consentimento para uma categoria específica (predefinida ou customizada). |
300
+ | `setPreferences` | `(prefs: ConsentPreferences) => void` | Salva um novo conjunto de preferências. |
301
+ | `openPreferences` | `() => void` | Abre o modal de preferências. |
302
+ | `resetConsent` | `() => void` | Reseta o consentimento, fazendo o banner aparecer novamente. |
289
303
 
290
304
  ### `useCategories()`
291
305
 
@@ -572,11 +586,11 @@ Função utilitária que retorna informações detalhadas sobre os cookies de um
572
586
 
573
587
  ```typescript
574
588
  interface CookieDescriptor {
575
- name: string // Nome ou padrão do cookie (ex: '_ga', '_ga_*')
576
- purpose?: string // Finalidade do cookie
577
- duration?: string // Tempo de retenção (ex: '2 anos', '24 horas')
578
- domain?: string // Domínio associado (ex: '.example.com')
579
- provider?: string // Provedor ou serviço (ex: 'Google Analytics')
589
+ name: string // Nome ou padrão do cookie (ex: '_ga', '_ga_*')
590
+ purpose?: string // Finalidade do cookie
591
+ duration?: string // Tempo de retenção (ex: '2 anos', '24 horas')
592
+ domain?: string // Domínio associado (ex: '.example.com')
593
+ provider?: string // Provedor ou serviço (ex: 'Google Analytics')
580
594
  }
581
595
  ```
582
596
 
@@ -592,16 +606,13 @@ function DetalhesCookies() {
592
606
  return (
593
607
  <div>
594
608
  {allCategories.map((categoria) => {
595
- const cookiesDetalhados = getCookiesInfoForCategory(
596
- categoria.id as any,
597
- integracoesUsadas
598
- )
609
+ const cookiesDetalhados = getCookiesInfoForCategory(categoria.id as any, integracoesUsadas)
599
610
 
600
611
  return (
601
612
  <div key={categoria.id}>
602
613
  <h3>{categoria.name}</h3>
603
614
  <p>{categoria.description}</p>
604
-
615
+
605
616
  {cookiesDetalhados.map((cookie) => (
606
617
  <div key={cookie.name}>
607
618
  <strong>{cookie.name}</strong>
@@ -635,26 +646,28 @@ const ModalPersonalizado: React.FC<CustomPreferencesModalProps> = ({
635
646
  <div>
636
647
  {allCategories.map((categoria) => {
637
648
  const cookies = getCookiesInfoForCategory(categoria.id as any, integracoes)
638
-
649
+
639
650
  return (
640
651
  <div key={categoria.id}>
641
652
  <label>
642
653
  <input
643
654
  type="checkbox"
644
655
  checked={preferences[categoria.id] || false}
645
- onChange={(e) => setPreferences({
646
- ...preferences,
647
- [categoria.id]: e.target.checked
648
- })}
656
+ onChange={(e) =>
657
+ setPreferences({
658
+ ...preferences,
659
+ [categoria.id]: e.target.checked,
660
+ })
661
+ }
649
662
  disabled={categoria.essential}
650
663
  />
651
664
  {categoria.name}
652
665
  </label>
653
-
666
+
654
667
  {/* Detalhes expandíveis dos cookies */}
655
668
  <details>
656
669
  <summary>Ver cookies ({cookies.length})</summary>
657
- {cookies.map(cookie => (
670
+ {cookies.map((cookie) => (
658
671
  <div key={cookie.name}>
659
672
  <code>{cookie.name}</code>: {cookie.purpose}
660
673
  </div>
@@ -687,6 +700,7 @@ Para customizações avançadas e tipagem, você pode importar os seguintes tipo
687
700
  - `ConsentPreferences`: Objeto com as preferências de consentimento para cada categoria.
688
701
  - `ConsentTexts`: Tipo base com textos essenciais da UI (pt-BR).
689
702
  - `Category`: Objeto que representa a definição de uma categoria de cookie.
703
+
690
704
  ### Exemplos de categorias (mínimo e completo)
691
705
 
692
706
  Somente necessários (mínimo):
@@ -762,14 +776,18 @@ interface ConsentAuditEntry {
762
776
  Use presets conformes com diretrizes da ANPD:
763
777
 
764
778
  ```tsx
765
- import { ConsentProvider, createAnpdCategoriesConfig, ANPD_CATEGORY_PRESETS } from 'react-lgpd-consent'
779
+ import {
780
+ ConsentProvider,
781
+ createAnpdCategoriesConfig,
782
+ ANPD_CATEGORY_PRESETS,
783
+ } from 'react-lgpd-consent'
766
784
 
767
785
  // Preset BÁSICO (necessary + analytics)
768
786
  const basicConfig = createAnpdCategoriesConfig({ include: ['analytics'] })
769
787
 
770
788
  // Preset COMPLETO (todas as categorias)
771
789
  const fullConfig = createAnpdCategoriesConfig({
772
- include: ['analytics', 'marketing', 'functional', 'social', 'personalization']
790
+ include: ['analytics', 'marketing', 'functional', 'social', 'personalization'],
773
791
  })
774
792
 
775
793
  // Preset MÍNIMO (apenas necessary)
@@ -779,7 +797,7 @@ const minimalConfig = createAnpdCategoriesConfig({ include: [] })
779
797
  const customConfig = createAnpdCategoriesConfig({
780
798
  include: ['analytics', 'marketing'],
781
799
  names: { analytics: 'Análises' },
782
- descriptions: { marketing: 'Anúncios personalizados baseados no seu perfil.' }
800
+ descriptions: { marketing: 'Anúncios personalizados baseados no seu perfil.' },
783
801
  })
784
802
 
785
803
  function App() {
@@ -795,12 +813,12 @@ function App() {
795
813
 
796
814
  ```typescript
797
815
  export const ANPD_CATEGORY_PRESETS: Record<Category, CategoryDefinition> = {
798
- necessary: { /* ... */ },
799
- analytics: { /* ... */ },
800
- functional: { /* ... */ },
801
- marketing: { /* ... */ },
802
- social: { /* ... */ },
803
- personalization: { /* ... */ }
816
+ necessary: {/* ... */},
817
+ analytics: {/* ... */},
818
+ functional: {/* ... */},
819
+ marketing: {/* ... */},
820
+ social: {/* ... */},
821
+ personalization: {/* ... */},
804
822
  }
805
823
  ```
806
824
 
@@ -830,15 +848,15 @@ const auditEntry = createConsentAuditEntry(
830
848
  {
831
849
  action: 'update',
832
850
  storageKey: 'lgpd-consent__v1',
833
- consentVersion: '1'
834
- }
851
+ consentVersion: '1',
852
+ },
835
853
  )
836
854
 
837
855
  // Enviar para backend
838
856
  await fetch('/api/audit', {
839
857
  method: 'POST',
840
- body: JSON.stringify(auditEntry)
858
+ body: JSON.stringify(auditEntry),
841
859
  })
842
860
  ```
843
861
 
844
- Consulte [TROUBLESHOOTING.md - Auditoria e log de consentimento](../../TROUBLESHOOTING.md#auditoria-e-log-de-consentimento) para exemplos completos de integração com backend.
862
+ Consulte [TROUBLESHOOTING.md - Auditoria e log de consentimento](../../doc/TROUBLESHOOTING.md#auditoria-e-log-de-consentimento) para exemplos completos de integração com backend.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,37 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.9.8
4
+
5
+ ### Patch Changes
6
+
7
+ - [`04d07b8`](https://github.com/lucianoedipo/react-lgpd-consent/commit/04d07b8c66287f4a84592d470c7820d9320a661d) Thanks [@lucianoedipo](https://github.com/lucianoedipo)! - Atualiza compatibilidade das integrações externas e estabiliza a configuração TypeScript/CI.
8
+
9
+ - GTM passa a incluir `&l=<dataLayerName>` quando um data layer customizado é usado.
10
+ - Clarity passa a sincronizar consentimento com `clarity('consentv2', ...)`, mantendo `upload` apenas como compatibilidade legada.
11
+ - Intercom passa a aceitar `api_base`, `settings` e sincronizar `update`/`shutdown` conforme revogação de consentimento.
12
+ - Zendesk Messaging passa a sincronizar cookies via `zE('messenger:set', 'cookies', ...)`.
13
+ - Remove usos diretos de `process` no código de produção em favor de leitura SSR-safe via `globalThis`.
14
+ - Ajusta `rootDir` dos pacotes que resolvem fontes internas por `paths`, evitando diagnósticos TS6059 no monorepo.
15
+ - Corrige `lint:ci` no Turbo e atualiza o workflow de CI para validar changesets em PRs.
16
+
17
+ - Updated dependencies [[`04d07b8`](https://github.com/lucianoedipo/react-lgpd-consent/commit/04d07b8c66287f4a84592d470c7820d9320a661d)]:
18
+ - @react-lgpd-consent/core@0.9.8
19
+ - @react-lgpd-consent/mui@0.9.8
20
+
21
+ ## 0.9.7
22
+
23
+ ### Patch Changes
24
+
25
+ - [`679fde1`](https://github.com/lucianoedipo/react-lgpd-consent/commit/679fde1f64980fde3026c9a4d5f548468e422f30) Thanks [@lucianoedipo](https://github.com/lucianoedipo)! - fix: preparar release após atualização de dependências
26
+ - Ajusta compatibilidade com as regras atuais do React Hooks/React Compiler.
27
+ - Mantém os peer dependencies compatíveis com React 18/19 e MUI 5/6/7.
28
+ - Corrige referências de documentação usadas pelo TypeDoc.
29
+ - Fortalece workflows de CI/CD contra falhas de fork, tags que não disparam release e versões desalinhadas.
30
+
31
+ - Updated dependencies [[`679fde1`](https://github.com/lucianoedipo/react-lgpd-consent/commit/679fde1f64980fde3026c9a4d5f548468e422f30)]:
32
+ - @react-lgpd-consent/core@0.9.7
33
+ - @react-lgpd-consent/mui@0.9.7
34
+
3
35
  ## 0.9.6
4
36
 
5
37
  ### Patch Changes
package/INTEGRACOES.md CHANGED
@@ -44,6 +44,16 @@ O componente `ConsentScriptLoader` gerencia o carregamento desses scripts automa
44
44
 
45
45
  > 💡 **Procurando exemplos práticos?** Veja [RECIPES.md](../../doc/RECIPES.md) para receitas passo a passo de Google Consent Mode v2, Next.js App Router e CSP/nonce.
46
46
 
47
+ ### Atualização de compatibilidade externa (02/07/2026)
48
+
49
+ As integrações nativas foram revisadas contra a documentação oficial dos provedores:
50
+
51
+ - **GTM com `dataLayerName` customizado**: a URL agora inclui `&l=<dataLayerName>`, como no snippet oficial do Google Tag Manager.
52
+ - **Microsoft Clarity**: a integração envia `clarity('consentv2', ...)` automaticamente em `onConsentUpdate`, preservando `upload` apenas como compatibilidade legada.
53
+ - **Intercom**: suporta `api_base`, `settings`, `Intercom('update')` quando o consentimento segue válido e `Intercom('shutdown')` quando a categoria é revogada.
54
+ - **Zendesk Messaging**: usa `zE('messenger:set', 'cookies', range)` para sincronizar `all`, `functional` ou `none`.
55
+ - **Mixpanel**: mantém `api_host` para projetos com residência regional de dados.
56
+
47
57
  ## 🎯 Integrações Nativas Disponíveis
48
58
 
49
59
  ### 1. Google Analytics 4 (GA4)
@@ -82,7 +92,7 @@ import { createGoogleTagManagerIntegration } from 'react-lgpd-consent'
82
92
  const integrations = [
83
93
  createGoogleTagManagerIntegration({
84
94
  containerId: 'GTM-XXXXXXX',
85
- dataLayerName: 'dataLayer', // opcional
95
+ dataLayerName: 'customLayer', // opcional; gera &l=customLayer na URL do gtm.js
86
96
  }),
87
97
  ]
88
98
  // ✅ Consent Mode v2 no dataLayer customizado automaticamente
@@ -116,48 +126,72 @@ const integrations = [createHotjarIntegration({ siteId: '123456', version: 6 })]
116
126
 
117
127
  - **Categoria**: `analytics`
118
128
  - **Função**: `createMixpanelIntegration(config)`
119
- - **Descrição**: Integração com o Mixpanel para análise de produtos. Suporta `token` e configurações customizadas.
129
+ - **Descrição**: Integração com o Mixpanel para análise de produtos. Suporta `token`, configurações customizadas e `api_host` para residência regional de dados.
120
130
 
121
131
  ```tsx
122
132
  import { createMixpanelIntegration } from 'react-lgpd-consent'
123
133
 
124
- const integrations = [createMixpanelIntegration({ token: 'YOUR_TOKEN' })]
134
+ const integrations = [
135
+ createMixpanelIntegration({
136
+ token: 'YOUR_TOKEN',
137
+ api_host: 'https://api-eu.mixpanel.com', // use quando seu projeto exigir endpoint regional
138
+ }),
139
+ ]
125
140
  ```
126
141
 
127
142
  ### 6. Microsoft Clarity
128
143
 
129
144
  - **Categoria**: `analytics`
130
145
  - **Função**: `createClarityIntegration(config)`
131
- - **Descrição**: Integração com o Microsoft Clarity. Suporta `projectId`.
146
+ - **Descrição**: Integração com o Microsoft Clarity. Suporta `projectId` e sincroniza a Consent API v2 (`consentv2`) quando as preferências mudam.
132
147
 
133
148
  ```tsx
134
149
  import { createClarityIntegration } from 'react-lgpd-consent'
135
150
 
136
- const integrations = [createClarityIntegration({ projectId: 'abcdef' })]
151
+ const integrations = [
152
+ createClarityIntegration({
153
+ projectId: 'abcdef',
154
+ analyticsStorageCategory: 'analytics', // padrão
155
+ adStorageCategory: 'marketing', // padrão
156
+ }),
157
+ ]
137
158
  ```
138
159
 
160
+ > A partir de 31/10/2025, a Microsoft exige sinal de consentimento válido para funcionalidade completa do Clarity em visitas originadas de EEA/UK/CH. A integração envia `ad_Storage` e `analytics_Storage` conforme as categorias configuradas.
161
+
139
162
  ### 7. Intercom
140
163
 
141
164
  - **Categoria**: `functional`
142
165
  - **Função**: `createIntercomIntegration(config)`
143
- - **Descrição**: Adiciona o widget de chat do Intercom. Suporta `app_id`.
166
+ - **Descrição**: Adiciona o widget de chat do Intercom. Suporta `app_id`, `api_base`, `settings`, atualização em SPA e encerramento de sessão na revogação de consentimento.
144
167
 
145
168
  ```tsx
146
169
  import { createIntercomIntegration } from 'react-lgpd-consent'
147
170
 
148
- const integrations = [createIntercomIntegration({ app_id: 'your_app_id' })]
171
+ const integrations = [
172
+ createIntercomIntegration({
173
+ app_id: 'your_app_id',
174
+ api_base: 'https://api-iam.eu.intercom.io', // opcional: US/EU/Australia
175
+ settings: { custom_launcher_selector: '#help' },
176
+ }),
177
+ ]
149
178
  ```
150
179
 
151
180
  ### 8. Zendesk Chat
152
181
 
153
182
  - **Categoria**: `functional`
154
183
  - **Função**: `createZendeskChatIntegration(config)`
155
- - **Descrição**: Adiciona o widget do Zendesk Chat. Suporta `key`.
184
+ - **Descrição**: Adiciona o widget do Zendesk Messaging. Suporta `key` e sincronização de cookies via `messenger:set`.
156
185
 
157
186
  ```tsx
158
187
  import { createZendeskChatIntegration } from 'react-lgpd-consent'
159
188
 
160
- const integrations = [createZendeskChatIntegration({ key: 'your_zendesk_key' })]
189
+ const integrations = [
190
+ createZendeskChatIntegration({
191
+ key: 'your_zendesk_key',
192
+ cookieRange: 'functional', // opcional: all | functional | none
193
+ }),
194
+ ]
161
195
  ```
162
196
 
163
197
  ### 9. UserWay (Acessibilidade)
@@ -463,6 +497,21 @@ interface ConsentUpdatedEvent {
463
497
 
464
498
  ---
465
499
 
500
+ ## 🔗 Fontes Oficiais Consultadas
501
+
502
+ - Google tag (`gtag.js`): https://developers.google.com/tag-platform/gtagjs
503
+ - Google Consent Mode: https://developers.google.com/tag-platform/security/guides/consent
504
+ - Google Tag Manager web container: https://support.google.com/tagmanager/answer/14842164
505
+ - Microsoft Clarity setup: https://learn.microsoft.com/en-us/clarity/setup-and-installation/clarity-setup
506
+ - Microsoft Clarity Consent Mode: https://learn.microsoft.com/en-us/clarity/setup-and-installation/consent-mode
507
+ - Microsoft Clarity Consent API v2: https://learn.microsoft.com/en-us/clarity/setup-and-installation/clarity-consent-api-v2
508
+ - Intercom Web installation: https://developers.intercom.com/installing-intercom/web/installation
509
+ - Intercom SPA guidance: https://www.intercom.com/help/en/articles/170-integrate-intercom-in-a-single-page-app
510
+ - Mixpanel JavaScript SDK: https://docs.mixpanel.com/docs/tracking-methods/sdks/javascript
511
+ - Zendesk Web Widget Messaging API: https://developer.zendesk.com/api-reference/widget-messaging/web/core/
512
+
513
+ ---
514
+
466
515
  ## 🆕 Recursos Avançados v0.7.0
467
516
 
468
517
  ### Monitoramento com Callbacks de Lifecycle
@@ -546,4 +595,4 @@ const customConfig = createAnpdCategoriesConfig({
546
595
  - [TROUBLESHOOTING.md](../../doc/TROUBLESHOOTING.md) – Solução de problemas comuns
547
596
  - [CONFORMIDADE.md](../../doc/CONFORMIDADE.md) – Conformidade LGPD e ANPD
548
597
 
549
- **Problemas de integração?** Consulte [TROUBLESHOOTING.md - Seção de Integrations](../../TROUBLESHOOTING.md#integrações-de-terceiros).
598
+ **Problemas de integração?** Consulte [TROUBLESHOOTING.md - Seção de Integrations](../../doc/TROUBLESHOOTING.md#integrações-de-terceiros).
package/README.en.md CHANGED
@@ -118,7 +118,7 @@ const audit = createConsentAuditEntry(state, {
118
118
  })
119
119
  ```
120
120
 
121
- 📖 **Full documentation:** [API.md](./API.md) | [TROUBLESHOOTING.md](../../TROUBLESHOOTING.md)
121
+ 📖 **Full documentation:** [API.md](./API.md) | [TROUBLESHOOTING.md](../../doc/TROUBLESHOOTING.md)
122
122
 
123
123
  ---
124
124
 
@@ -134,9 +134,9 @@ const audit = createConsentAuditEntry(state, {
134
134
 
135
135
  ## Documentation & Examples
136
136
 
137
- - **[🚀 Quickstart](../../QUICKSTART.en.md)** - Step-by-step tutorial
138
- - **[📖 Recipes](../../RECIPES.md)** - Practical guide with common use cases (Next.js, CSP, Consent Mode v2)
139
- - **[⚙️ Workflows](../../WORKFLOWS.md)** - CI/CD workflows documentation
137
+ - **[🚀 Quickstart](../../doc/QUICKSTART.en.md)** - Step-by-step tutorial
138
+ - **[📖 Recipes](../../doc/RECIPES.md)** - Practical guide with common use cases (Next.js, CSP, Consent Mode v2)
139
+ - **[⚙️ Workflows](../../doc/WORKFLOWS.md)** - CI/CD workflows documentation
140
140
  - **[API Reference](./API.md)** - Complete API reference
141
141
  - **[Integrations](./INTEGRACOES.md)** - GA4, GTM, Facebook Pixel
142
142
  - **[Storybook](https://lucianoedipo.github.io/react-lgpd-consent/storybook/)** - Interactive components
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "react-lgpd-consent",
3
- "version": "0.9.6",
3
+ "version": "0.9.8",
4
4
  "description": "Biblioteca de consentimento LGPD, integrações nativas e sistema extensível para React.",
5
5
  "keywords": [
6
6
  "lgpd",
@@ -80,10 +80,10 @@
80
80
  },
81
81
  "homepage": "https://lucianoedipo.github.io/react-lgpd-consent/",
82
82
  "peerDependencies": {
83
- "@mui/icons-material": "^7.3.9",
84
- "@mui/material": "^7.3.9",
85
- "react": "^19.2.4",
86
- "react-dom": "^19.2.4"
83
+ "@mui/icons-material": "^7.0.0 || ^6.0.0 || ^5.15.0",
84
+ "@mui/material": "^7.0.0 || ^6.0.0 || ^5.15.0",
85
+ "react": "^18.2.0 || ^19.0.0",
86
+ "react-dom": "^18.2.0 || ^19.0.0"
87
87
  },
88
88
  "peerDependenciesMeta": {
89
89
  "@mui/icons-material": {
@@ -94,8 +94,8 @@
94
94
  }
95
95
  },
96
96
  "dependencies": {
97
- "@react-lgpd-consent/core": "^0.9.6",
98
- "@react-lgpd-consent/mui": "^0.9.6"
97
+ "@react-lgpd-consent/core": "^0.9.8",
98
+ "@react-lgpd-consent/mui": "^0.9.8"
99
99
  },
100
100
  "size-limit": [
101
101
  {
@@ -121,8 +121,8 @@
121
121
  }
122
122
  ],
123
123
  "devDependencies": {
124
- "@mui/icons-material": "7.3.9",
125
- "@mui/material": "7.3.9"
124
+ "@mui/icons-material": "7.3.11",
125
+ "@mui/material": "7.3.11"
126
126
  },
127
127
  "scripts": {
128
128
  "clean": "rimraf dist",