cloudflare-next-intl 0.3.3 → 0.4.0

package/README.md

@@ -185,6 +185,46 @@ import ThemeSwitcher from "cloudflare-next-intl/ThemeSwitcher";
 <ThemeSwitcher lightLabelText="Light" darkLabelText="Dark" />
 ```
 
+### Cookie consent
+
+Set `cookieConsent` on your `RoutingConfig` to enable — `IntlProvider` then
+auto-wires `CookieConsentProvider` (and `CookieConsentAnalytics`, if
+`cookieConsent.secrets`/`getSecrets` is set) with no manual nesting needed.
+
+```typescript
+// intl-config.ts
+export default setIntlConfig({
+    locales: ["en", "de"],
+    defaultLocale: "en",
+    cookieConsent: {
+        privacyPolicyDate: "2026-01-01",
+    },
+});
+```
+
+```tsx
+import { CookieConsentDialog, PrivacyPolicyUpdateDialog, useCookieConsent } from "cloudflare-next-intl/cookieConsent";
+
+export default function Layout({ children }) {
+    return (
+        <>
+            {children}
+            <CookieConsentDialog />
+            <PrivacyPolicyUpdateDialog />
+        </>
+    );
+}
+```
+
+```tsx
+"use client";
+import { useCookieConsent } from "cloudflare-next-intl/useCookieConsent";
+
+const { consent, setConsent } = useCookieConsent();
+```
+
+See [`package/src/cookie_consent/README.md`](package/src/cookie_consent/README.md) for layout, customization, and gotchas.
+
 ## License
 
 MIT

package/dist/src/client/components/client_provider.d.ts

@@ -1,16 +1,19 @@
 import type { TranslationObject } from "../../types/types";
 import type { SerializedAuthUser } from "../../firebase_auth/types";
+import type { CookieConsentAnalyticsSecrets } from "../../types/types";
 interface LocaleContextType {
     language: string;
     messages: TranslationObject;
 }
 export declare const LocaleContext: import("react").Context<LocaleContextType | undefined>;
-export default function LocationzationClientProvider({ language, messages, initialAuthUser, skipAuthProvider, children }: {
+export default function LocationzationClientProvider({ language, messages, initialAuthUser, skipAuthProvider, analyticsSecrets, children }: {
     language: string;
     messages: TranslationObject;
     initialAuthUser?: SerializedAuthUser | null;
     /** Set when `firebaseAuth.autoWireClientProvider` is `false` — skips wrapping `children` in the client `AuthUserProvider` entirely. */
     skipAuthProvider?: boolean;
+    /** Resolved server-side from `cookieConsent.secrets`/`getSecrets` when `autoWireAnalytics` isn't `false`. */
+    analyticsSecrets?: CookieConsentAnalyticsSecrets;
     children: React.ReactNode;
 }): Component;
 export {};

package/dist/src/client/components/client_provider.js

@@ -1,5 +1,5 @@
 "use client";
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { setLocaleCache, setMessageForLocaleCache } from "../../general/cache_variables";
 import { createContext, useMemo } from "react";
 import dynamic from "next/dynamic";
@@ -13,7 +13,9 @@ export const LocaleContext = createContext(undefined);
 // update (and a `getIdToken(true)` refresh) that causes another render —
 // an infinite loop of session-cookie writes, one per render.
 const AuthUserProvider = dynamic(() => import("../../firebase_auth/client/auth_user_provider"));
-export default function LocationzationClientProvider({ language, messages, initialAuthUser = null, skipAuthProvider = false, children }) {
+const CookieConsentProvider = dynamic(() => import("../../cookie_consent/client/cookie_consent_provider"));
+const CookieConsentAnalytics = dynamic(() => import("../../cookie_consent/client/components/cookie_consent_analytics"));
+export default function LocationzationClientProvider({ language, messages, initialAuthUser = null, skipAuthProvider = false, analyticsSecrets, children }) {
     setLocaleCache(language);
     setMessageForLocaleCache(language, messages);
     // `LocaleContext.Provider` stays the outermost element here — the
@@ -25,6 +27,9 @@ export default function LocationzationClientProvider({ language, messages, initi
     if (config.firebaseAuth && !skipAuthProvider) {
         providedChildren = _jsx(AuthUserProvider, { initialUser: initialAuthUser, children: children });
     }
+    if (config.cookieConsent) {
+        providedChildren = _jsxs(CookieConsentProvider, { children: [providedChildren, analyticsSecrets && _jsx(CookieConsentAnalytics, { secrets: analyticsSecrets })] });
+    }
     const contextValue = useMemo(() => ({ language, messages }), [language, messages]);
     return _jsx(LocaleContext.Provider, { value: contextValue, children: providedChildren });
 }

package/dist/src/config/cookie_key.d.ts

@@ -1,3 +1,5 @@
 export declare const localeCookieName = "__user_locale_key__";
 export declare const isBotCookieKey = "__is_bot_key__";
 export declare const isDarkCookieKey = "__is_dark_key__";
+export declare const cookieConsentCookieKey = "__cookie_consent_key__";
+export declare const privacyPolicyDateCookieKey = "__privacy_policy_date_key__";

package/dist/src/config/cookie_key.js

@@ -1,3 +1,5 @@
 export const localeCookieName = '__user_locale_key__';
 export const isBotCookieKey = '__is_bot_key__';
 export const isDarkCookieKey = '__is_dark_key__';
+export const cookieConsentCookieKey = '__cookie_consent_key__';
+export const privacyPolicyDateCookieKey = '__privacy_policy_date_key__';

package/dist/src/config/index.d.ts

@@ -1,4 +1,4 @@
-export { isBotCookieKey, localeCookieName, isDarkCookieKey } from './cookie_key';
+export { isBotCookieKey, localeCookieName, isDarkCookieKey, cookieConsentCookieKey, privacyPolicyDateCookieKey } from './cookie_key';
 export { default as intlMiddleware } from './middleware';
 export { setIntlConfig } from './init_config';
 export { default as generateIntlSitemap } from './intl_sitemap';

package/dist/src/config/index.js

@@ -1,4 +1,4 @@
-export { isBotCookieKey, localeCookieName, isDarkCookieKey } from './cookie_key'; // Export specific middleware function
+export { isBotCookieKey, localeCookieName, isDarkCookieKey, cookieConsentCookieKey, privacyPolicyDateCookieKey } from './cookie_key'; // Export specific middleware function
 export { default as intlMiddleware } from './middleware'; // Export specific middleware function
 export { setIntlConfig } from './init_config';
 export { default as generateIntlSitemap } from './intl_sitemap';

package/dist/src/cookie_consent/client/components/cookie_consent_analytics.bench.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/cookie_consent/client/components/cookie_consent_analytics.bench.js

@@ -0,0 +1,14 @@
+import { bench, describe } from 'vitest';
+import { googleConsentModeBootstrapScript } from './cookie_consent_analytics';
+describe('googleConsentModeBootstrapScript', () => {
+    bench('all providers configured', () => {
+        googleConsentModeBootstrapScript({
+            googleAnalyticsId: 'G-XXX',
+            googleAdsId: 'AW-YYY',
+            googleAdSenseId: 'ca-pub-ZZZ',
+        });
+    });
+    bench('no providers configured', () => {
+        googleConsentModeBootstrapScript({});
+    });
+});

package/dist/src/cookie_consent/client/components/cookie_consent_analytics.d.ts

@@ -0,0 +1,19 @@
+import type { CookieConsentAnalyticsSecrets } from '../../../types/types';
+/**
+ * Renders whichever analytics/ads scripts have a resolved secret, gated on
+ * consent: Google Consent Mode bootstrap always loads (defaults to
+ * `denied`, only sends `update` once `consent` is decided); Cloudflare Web
+ * Analytics beacon and Microsoft Clarity only load once `consent === true`.
+ * Rendered automatically by `IntlProvider` when `cookieConsent.secrets`/
+ * `getSecrets` resolves at least one field and `autoWireAnalytics` isn't
+ * `false` — render manually instead if you set `autoWireAnalytics: false`.
+ */
+export default function CookieConsentAnalytics({ secrets }: {
+    secrets: CookieConsentAnalyticsSecrets;
+}): React.ReactElement | null;
+/**
+ * Denies storage by default and loads the configured Google tags; the
+ * effect above sends the `update` once consent is known. Only IDs present
+ * in `secrets` are included.
+ */
+export declare function googleConsentModeBootstrapScript(secrets: CookieConsentAnalyticsSecrets): string;

package/dist/src/cookie_consent/client/components/cookie_consent_analytics.js

@@ -0,0 +1,91 @@
+'use client';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect } from 'react';
+import useCookieConsent from '../use_cookie_consent';
+/**
+ * Renders whichever analytics/ads scripts have a resolved secret, gated on
+ * consent: Google Consent Mode bootstrap always loads (defaults to
+ * `denied`, only sends `update` once `consent` is decided); Cloudflare Web
+ * Analytics beacon and Microsoft Clarity only load once `consent === true`.
+ * Rendered automatically by `IntlProvider` when `cookieConsent.secrets`/
+ * `getSecrets` resolves at least one field and `autoWireAnalytics` isn't
+ * `false` — render manually instead if you set `autoWireAnalytics: false`.
+ */
+export default function CookieConsentAnalytics({ secrets }) {
+    const { consent } = useCookieConsent();
+    useEffect(() => {
+        if (consent === null)
+            return;
+        const w = window;
+        if (typeof w.gtag !== 'function')
+            return;
+        const state = consent ? 'granted' : 'denied';
+        w.gtag('consent', 'update', {
+            ad_storage: state,
+            ad_user_data: state,
+            ad_personalization: state,
+            analytics_storage: state,
+        });
+    }, [consent]);
+    const hasGoogle = Boolean(secrets.googleAnalyticsId || secrets.googleAdsId || secrets.googleAdSenseId);
+    return (_jsxs(_Fragment, { children: [hasGoogle && (_jsx("script", { id: "cookie-consent-google-consent-mode", dangerouslySetInnerHTML: { __html: googleConsentModeBootstrapScript(secrets) } })), consent === true && secrets.cloudflareBeaconToken && (_jsx("script", { defer: true, src: "https://static.cloudflareinsights.com/beacon.min.js", "data-cf-beacon": secrets.cloudflareBeaconToken })), consent === true && secrets.clarityProjectId && _jsx(ClarityScript, { projectId: secrets.clarityProjectId })] }));
+}
+let cachedClarityModule;
+function getClarityModule() {
+    if (!cachedClarityModule) {
+        cachedClarityModule = import('@microsoft/clarity');
+    }
+    return cachedClarityModule;
+}
+function ClarityScript({ projectId }) {
+    useEffect(() => {
+        getClarityModule()
+            .then(({ default: Clarity }) => {
+            Clarity.init(projectId);
+            Clarity.consent();
+        })
+            .catch((error) => console.error(`cloudflare-next-intl: failed to load @microsoft/clarity: ${error}`));
+    }, [projectId]);
+    return null;
+}
+/**
+ * Denies storage by default and loads the configured Google tags; the
+ * effect above sends the `update` once consent is known. Only IDs present
+ * in `secrets` are included.
+ */
+export function googleConsentModeBootstrapScript(secrets) {
+    const configCalls = [secrets.googleAnalyticsId, secrets.googleAdsId]
+        .filter(Boolean)
+        .map((id) => `gtag('config', '${id}');`)
+        .join('\n');
+    const gtagLoader = secrets.googleAnalyticsId || secrets.googleAdsId
+        ? `(function(){
+  var s = document.createElement('script');
+  s.async = true;
+  s.src = 'https://www.googletagmanager.com/gtag/js?id=${secrets.googleAnalyticsId ?? secrets.googleAdsId}';
+  document.head.appendChild(s);
+})();`
+        : '';
+    const adSenseLoader = secrets.googleAdSenseId
+        ? `(function(){
+  var a = document.createElement('script');
+  a.async = true;
+  a.crossOrigin = 'anonymous';
+  a.src = 'https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js?client=${secrets.googleAdSenseId}';
+  document.head.appendChild(a);
+})();`
+        : '';
+    return `window.dataLayer = window.dataLayer || [];
+function gtag(){dataLayer.push(arguments);}
+gtag('consent', 'default', {
+  'ad_storage': 'denied',
+  'ad_user_data': 'denied',
+  'ad_personalization': 'denied',
+  'analytics_storage': 'denied',
+  'wait_for_update': 500
+});
+gtag('js', new Date());
+${configCalls}
+${gtagLoader}
+${adSenseLoader}`;
+}

package/dist/src/cookie_consent/client/components/cookie_consent_dialog.d.ts

@@ -0,0 +1,28 @@
+import type { CookieDialogClassNames, CookieDialogStyles } from '../../types';
+export interface CookieConsentDialogProps {
+    /** Banner message text. */
+    message?: React.ReactNode;
+    /** Optional link element rendered right after `message` (e.g. a privacy-policy link). */
+    link?: React.ReactNode;
+    acceptText?: string;
+    declineText?: string;
+    /** Hides the decline ("necessary only") button, leaving only accept. */
+    hideDecline?: boolean;
+    id?: string;
+    classNames?: CookieDialogClassNames;
+    styles?: CookieDialogStyles;
+    /**
+     * Full custom render — receives the resolved consent state/actions and
+     * bypasses the default markup entirely. Use for a fully bespoke dialog.
+     */
+    render?: (props: {
+        setConsent: (value: boolean) => void;
+    }) => React.ReactNode;
+}
+/**
+ * Cookie-consent banner. Renders `null` once `consent` is already decided.
+ * Every visual aspect is overridable via `classNames`/`styles` (per-slot) or
+ * `render` (full custom markup) — none of it is hardcoded to Tailwind or any
+ * particular design system.
+ */
+export default function CookieConsentDialog({ message, link, acceptText, declineText, hideDecline, id, classNames, styles, render, }: CookieConsentDialogProps): React.ReactElement | null;

package/dist/src/cookie_consent/client/components/cookie_consent_dialog.js

@@ -0,0 +1,17 @@
+'use client';
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import useCookieConsent from '../use_cookie_consent';
+/**
+ * Cookie-consent banner. Renders `null` once `consent` is already decided.
+ * Every visual aspect is overridable via `classNames`/`styles` (per-slot) or
+ * `render` (full custom markup) — none of it is hardcoded to Tailwind or any
+ * particular design system.
+ */
+export default function CookieConsentDialog({ message = 'We use cookies to improve your experience.', link, acceptText = 'Accept', declineText = 'Necessary only', hideDecline = false, id = 'cookie-consent-dialog', classNames, styles, render, }) {
+    const { consent, setConsent } = useCookieConsent();
+    if (consent !== null)
+        return null;
+    if (render)
+        return _jsx(_Fragment, { children: render({ setConsent }) });
+    return (_jsxs("div", { id: id, role: "dialog", "aria-modal": "false", "aria-labelledby": `${id}-title`, className: classNames?.root, style: styles?.root, children: [_jsxs("p", { id: `${id}-title`, className: classNames?.message, style: styles?.message, children: [message, link ? _jsxs("span", { className: classNames?.link, style: styles?.link, children: [" ", link] }) : null] }), _jsxs("div", { className: classNames?.actions, style: styles?.actions, children: [!hideDecline && (_jsx("button", { type: "button", onClick: () => setConsent(false), className: classNames?.declineButton, style: styles?.declineButton, children: declineText })), _jsx("button", { type: "button", onClick: () => setConsent(true), className: classNames?.acceptButton, style: styles?.acceptButton, children: acceptText })] })] }));
+}

package/dist/src/cookie_consent/client/components/privacy_policy_update_dialog.d.ts

@@ -0,0 +1,24 @@
+import type { CookieDialogClassNames, CookieDialogStyles } from '../../types';
+export interface PrivacyPolicyUpdateDialogProps {
+    message?: React.ReactNode;
+    /** Optional link element rendered right after `message` (e.g. to your privacy-policy page). */
+    link?: React.ReactNode;
+    closeText?: string;
+    id?: string;
+    classNames?: CookieDialogClassNames;
+    styles?: CookieDialogStyles;
+    /**
+     * Full custom render — receives the acknowledge action and bypasses the
+     * default markup entirely.
+     */
+    render?: (props: {
+        acknowledge: () => void;
+    }) => React.ReactNode;
+}
+/**
+ * "Privacy policy updated" banner. Auto-enabled only when
+ * `cookieConsent.privacyPolicyDate` is set on the `RoutingConfig` — renders
+ * `null` otherwise, or once acknowledged. Every visual aspect is overridable
+ * via `classNames`/`styles` (per-slot) or `render` (full custom markup).
+ */
+export default function PrivacyPolicyUpdateDialog({ message, link, closeText, id, classNames, styles, render, }: PrivacyPolicyUpdateDialogProps): React.ReactElement | null;

package/dist/src/cookie_consent/client/components/privacy_policy_update_dialog.js

@@ -0,0 +1,17 @@
+'use client';
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import useCookieConsent from '../use_cookie_consent';
+/**
+ * "Privacy policy updated" banner. Auto-enabled only when
+ * `cookieConsent.privacyPolicyDate` is set on the `RoutingConfig` — renders
+ * `null` otherwise, or once acknowledged. Every visual aspect is overridable
+ * via `classNames`/`styles` (per-slot) or `render` (full custom markup).
+ */
+export default function PrivacyPolicyUpdateDialog({ message = 'Our privacy policy has been updated.', link, closeText = 'Got it', id = 'privacy-policy-update-dialog', classNames, styles, render, }) {
+    const { privacyPolicyUpdated, acknowledgePrivacyPolicyUpdate } = useCookieConsent();
+    if (!privacyPolicyUpdated)
+        return null;
+    if (render)
+        return _jsx(_Fragment, { children: render({ acknowledge: acknowledgePrivacyPolicyUpdate }) });
+    return (_jsxs("div", { id: id, role: "dialog", "aria-modal": "false", "aria-labelledby": `${id}-title`, className: classNames?.root, style: styles?.root, children: [_jsxs("p", { id: `${id}-title`, className: classNames?.message, style: styles?.message, children: [message, link ? _jsxs("span", { className: classNames?.link, style: styles?.link, children: [" ", link] }) : null] }), _jsx("button", { type: "button", onClick: acknowledgePrivacyPolicyUpdate, "aria-label": closeText, className: classNames?.closeButton, style: styles?.closeButton, children: closeText })] }));
+}

package/dist/src/cookie_consent/client/cookie_consent_provider.d.ts

@@ -0,0 +1,27 @@
+import type { CookieConsentContextType } from '../types';
+export declare const CookieConsentContext: import("react").Context<CookieConsentContextType | null>;
+/**
+ * Provides cookie-consent + privacy-policy-update state to
+ * `useCookieConsent()` and the default `CookieConsentDialog`/
+ * `PrivacyPolicyUpdateDialog` components. Requires `cookieConsent` to be set
+ * on the `RoutingConfig` passed to `setIntlConfig` — throws a descriptive
+ * error otherwise.
+ *
+ * The privacy-policy-update banner turns on automatically, and only when
+ * `cookieConsent.privacyPolicyDate` is configured: once a visitor has
+ * consented, if their stored consent date predates `privacyPolicyDate`,
+ * `privacyPolicyUpdated` becomes `true` until they call
+ * `acknowledgePrivacyPolicyUpdate()`.
+ *
+ * @example
+ * ```tsx
+ * <CookieConsentProvider>
+ *   {children}
+ *   <CookieConsentDialog />
+ *   <PrivacyPolicyUpdateDialog />
+ * </CookieConsentProvider>
+ * ```
+ */
+export default function CookieConsentProvider({ children }: {
+    children: React.ReactNode;
+}): React.ReactElement;

package/dist/src/cookie_consent/client/cookie_consent_provider.js

@@ -0,0 +1,82 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useCallback, useEffect, useMemo, useState } from 'react';
+import config from '../../config/intl_config';
+import requireCookieConsentConfig from '../require_config';
+import getCookie from '../../client/functions/get_cookie';
+import setCookie from '../../client/functions/set_cookie';
+import { cookieConsentCookieKey, privacyPolicyDateCookieKey } from '../../config/cookie_key';
+export const CookieConsentContext = createContext(null);
+function parseConsent(raw) {
+    if (raw === 'true')
+        return true;
+    if (raw === 'false')
+        return false;
+    return null;
+}
+/**
+ * Provides cookie-consent + privacy-policy-update state to
+ * `useCookieConsent()` and the default `CookieConsentDialog`/
+ * `PrivacyPolicyUpdateDialog` components. Requires `cookieConsent` to be set
+ * on the `RoutingConfig` passed to `setIntlConfig` — throws a descriptive
+ * error otherwise.
+ *
+ * The privacy-policy-update banner turns on automatically, and only when
+ * `cookieConsent.privacyPolicyDate` is configured: once a visitor has
+ * consented, if their stored consent date predates `privacyPolicyDate`,
+ * `privacyPolicyUpdated` becomes `true` until they call
+ * `acknowledgePrivacyPolicyUpdate()`.
+ *
+ * @example
+ * ```tsx
+ * <CookieConsentProvider>
+ *   {children}
+ *   <CookieConsentDialog />
+ *   <PrivacyPolicyUpdateDialog />
+ * </CookieConsentProvider>
+ * ```
+ */
+export default function CookieConsentProvider({ children }) {
+    const { consentCookieName, dateCookieName, maxAge, policyDate } = useMemo(() => {
+        const cc = requireCookieConsentConfig(config.cookieConsent);
+        return {
+            consentCookieName: cc.consentCookieName ?? cookieConsentCookieKey,
+            dateCookieName: cc.privacyPolicyDateCookieName ?? privacyPolicyDateCookieKey,
+            maxAge: cc.cookieMaxAge ?? 31536000,
+            policyDate: cc.privacyPolicyDate ? new Date(cc.privacyPolicyDate) : null,
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    const [consent, setConsentState] = useState(null);
+    const [privacyPolicyUpdated, setPrivacyPolicyUpdated] = useState(false);
+    useEffect(() => {
+        const storedConsent = parseConsent(getCookie(consentCookieName));
+        setConsentState(storedConsent);
+        if (storedConsent === null || !policyDate)
+            return;
+        const storedDateRaw = getCookie(dateCookieName);
+        if (!storedDateRaw) {
+            setCookie({ name: dateCookieName, value: policyDate.toISOString(), maxAge });
+            return;
+        }
+        const storedDate = new Date(storedDateRaw);
+        setPrivacyPolicyUpdated(!Number.isNaN(storedDate.getTime()) && storedDate < policyDate);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    const setConsent = useCallback((value) => {
+        setCookie({ name: consentCookieName, value, maxAge });
+        if (policyDate)
+            setCookie({ name: dateCookieName, value: policyDate.toISOString(), maxAge });
+        setConsentState(value);
+        setPrivacyPolicyUpdated(false);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    const acknowledgePrivacyPolicyUpdate = useCallback(() => {
+        if (policyDate)
+            setCookie({ name: dateCookieName, value: policyDate.toISOString(), maxAge });
+        setPrivacyPolicyUpdated(false);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    const contextValue = useMemo(() => ({ consent, privacyPolicyUpdated, setConsent, acknowledgePrivacyPolicyUpdate }), [consent, privacyPolicyUpdated, setConsent, acknowledgePrivacyPolicyUpdate]);
+    return (_jsx(CookieConsentContext.Provider, { value: contextValue, children: children }));
+}

package/dist/src/cookie_consent/client/use_cookie_consent.d.ts

@@ -0,0 +1,6 @@
+import type { CookieConsentContextType } from '../types';
+/**
+ * Reads cookie-consent + privacy-policy-update state. Must be called within
+ * a `CookieConsentProvider`.
+ */
+export default function useCookieConsent(): CookieConsentContextType;

package/dist/src/cookie_consent/client/use_cookie_consent.js

@@ -0,0 +1,14 @@
+'use client';
+import { useContext } from 'react';
+import { CookieConsentContext } from './cookie_consent_provider';
+/**
+ * Reads cookie-consent + privacy-policy-update state. Must be called within
+ * a `CookieConsentProvider`.
+ */
+export default function useCookieConsent() {
+    const context = useContext(CookieConsentContext);
+    if (context === null) {
+        throw new Error('useCookieConsent must be used within a CookieConsentProvider');
+    }
+    return context;
+}

package/dist/src/cookie_consent/index.d.ts

@@ -0,0 +1,7 @@
+export { default as CookieConsentProvider } from './client/cookie_consent_provider';
+export { default as useCookieConsent } from './client/use_cookie_consent';
+export { default as CookieConsentDialog } from './client/components/cookie_consent_dialog';
+export { default as PrivacyPolicyUpdateDialog } from './client/components/privacy_policy_update_dialog';
+export { default as CookieConsentAnalytics } from './client/components/cookie_consent_analytics';
+export type { CookieConsentContextType, ConsentValue, CookieDialogClassNames, CookieDialogStyles } from './types';
+export type { CookieConsentRoutingConfig, CookieConsentAnalyticsSecrets } from '../types/types';

package/dist/src/cookie_consent/index.js

@@ -0,0 +1,5 @@
+export { default as CookieConsentProvider } from './client/cookie_consent_provider';
+export { default as useCookieConsent } from './client/use_cookie_consent';
+export { default as CookieConsentDialog } from './client/components/cookie_consent_dialog';
+export { default as PrivacyPolicyUpdateDialog } from './client/components/privacy_policy_update_dialog';
+export { default as CookieConsentAnalytics } from './client/components/cookie_consent_analytics';

package/dist/src/cookie_consent/require_config.d.ts

@@ -0,0 +1,7 @@
+import type { CookieConsentRoutingConfig } from '../types/types';
+/**
+ * Throws a descriptive error instead of silently no-op'ing when the
+ * `cookie_consent` submodule is used without `cookieConsent` set on the
+ * `RoutingConfig` passed to `setIntlConfig`.
+ */
+export default function requireCookieConsentConfig(value: CookieConsentRoutingConfig | undefined): CookieConsentRoutingConfig;

package/dist/src/cookie_consent/require_config.js

@@ -0,0 +1,13 @@
+/**
+ * Throws a descriptive error instead of silently no-op'ing when the
+ * `cookie_consent` submodule is used without `cookieConsent` set on the
+ * `RoutingConfig` passed to `setIntlConfig`.
+ */
+export default function requireCookieConsentConfig(value) {
+    if (!value) {
+        throw new Error('cloudflare-next-intl: `cookieConsent` is not set on your `RoutingConfig`. ' +
+            'Add a `cookieConsent` block (see `CookieConsentRoutingConfig`) to the config ' +
+            'object passed to `setIntlConfig` before using `CookieConsentProvider`/`useCookieConsent`.');
+    }
+    return value;
+}

package/dist/src/cookie_consent/types.d.ts

@@ -0,0 +1,37 @@
+/** Consent value: `true` accepted, `false` necessary-only, `null` not yet decided. */
+export type ConsentValue = boolean | null;
+/** Context value returned by `useCookieConsent()`. */
+export interface CookieConsentContextType {
+    /** Current consent value; `null` until the visitor decides. */
+    consent: ConsentValue;
+    /**
+     * `true` once a privacy-policy update has been detected (stored consent
+     * predates `cookieConsent.privacyPolicyDate`) and hasn't been
+     * acknowledged yet. Always `false` when `privacyPolicyDate` is unset.
+     */
+    privacyPolicyUpdated: boolean;
+    /** Accepts (or rejects, with `false`) cookie consent and persists it. */
+    setConsent: (value: boolean) => void;
+    /** Acknowledges the privacy-policy update banner and persists the new date. */
+    acknowledgePrivacyPolicyUpdate: () => void;
+}
+/** Slot-level style/class overrides accepted by the default dialog components. */
+export interface CookieDialogClassNames {
+    root?: string;
+    message?: string;
+    link?: string;
+    actions?: string;
+    acceptButton?: string;
+    declineButton?: string;
+    closeButton?: string;
+}
+/** Slot-level inline-style overrides accepted by the default dialog components. */
+export interface CookieDialogStyles {
+    root?: React.CSSProperties;
+    message?: React.CSSProperties;
+    link?: React.CSSProperties;
+    actions?: React.CSSProperties;
+    acceptButton?: React.CSSProperties;
+    declineButton?: React.CSSProperties;
+    closeButton?: React.CSSProperties;
+}

package/dist/src/cookie_consent/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/firebase_auth/client/auth_user_provider.js

@@ -7,7 +7,7 @@ import config from '@intl-config';
 import requireFirebaseAuthConfig from '../require_config';
 import { getFirebaseAuthClient, getFirebaseAuthModule } from './firebase_client';
 import { setAuthUserCache } from './auth_user_cache';
-import { defaultSessionCookieName } from '../middleware/update_session';
+import { defaultRefreshTokenCookieName, defaultSessionCookieName } from '../middleware/update_session';
 import setCookie from '../../client/functions/set_cookie';
 // `null` default (instead of a `{ loading: true, ... }` stand-in) lets
 // `useAuthUser` distinguish "not wrapped in AuthUserProvider" (throw) from
@@ -19,6 +19,12 @@ function writeSessionCookie(sessionCookieName, idToken, maxAge) {
 function clearSessionCookie(sessionCookieName) {
     setCookie({ name: sessionCookieName, value: '', maxAge: 0 });
 }
+function writeRefreshTokenCookie(refreshTokenCookieName, user, maxAge) {
+    setCookie({ name: refreshTokenCookieName, value: user.refreshToken, maxAge });
+}
+function clearRefreshTokenCookie(refreshTokenCookieName) {
+    setCookie({ name: refreshTokenCookieName, value: '', maxAge: 0 });
+}
 /**
  * Client-side auth-state provider for `firebase_auth`. Wrap your root layout
  * (or a client boundary below it) with this to make `useAuthUser()`
@@ -46,6 +52,8 @@ export default function AuthUserProvider({ initialUser = null, children }) {
     const isWhiteListed = fa.whiteListPaths?.includes(pathname) ?? false;
     const maxAge = fa.sessionCookieMaxAge ?? 60 * 60 * 24 * 5;
     const sessionCookieName = fa.sessionCookieName ?? defaultSessionCookieName;
+    const refreshTokenMaxAge = fa.refreshTokenCookieMaxAge ?? 60 * 60 * 24 * 365;
+    const refreshTokenCookieName = fa.refreshTokenCookieName ?? defaultRefreshTokenCookieName;
     const [state, setState] = useState({
         user: initialUser,
         loading: initialUser === null,
@@ -86,10 +94,18 @@ export default function AuthUserProvider({ initialUser = null, children }) {
                 const previous = syncedSignedIn.current;
                 try {
                     if (user) {
-                        writeSessionCookie(sessionCookieName, await user.getIdToken(true), maxAge);
+                        try {
+                            writeRefreshTokenCookie(refreshTokenCookieName, user, refreshTokenMaxAge);
+                        }
+                        catch (e) {
+                            console.error('AuthUserProvider: refresh-token cookie sync failed', e);
+                        }
+                        const token = await user.getIdToken(true);
+                        writeSessionCookie(sessionCookieName, token, maxAge);
                     }
                     else if (previous) {
                         clearSessionCookie(sessionCookieName);
+                        clearRefreshTokenCookie(refreshTokenCookieName);
                     }
                 }
                 catch (e) {
@@ -122,7 +138,7 @@ export default function AuthUserProvider({ initialUser = null, children }) {
             unsubscribe?.();
         };
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [router, isAuthPage, maxAge, sessionCookieName]);
+    }, [router, isAuthPage, maxAge, sessionCookieName, refreshTokenMaxAge, refreshTokenCookieName]);
     const reloadUser = useCallback(async () => {
         const { auth } = await getFirebaseAuthClient();
         const user = auth.currentUser;
@@ -131,6 +147,12 @@ export default function AuthUserProvider({ initialUser = null, children }) {
         try {
             const { reload } = await getFirebaseAuthModule();
             await reload(user);
+            try {
+                writeRefreshTokenCookie(refreshTokenCookieName, user, refreshTokenMaxAge);
+            }
+            catch (e) {
+                console.error('AuthUserProvider: refresh-token cookie sync failed', e);
+            }
             writeSessionCookie(sessionCookieName, await user.getIdToken(true), maxAge);
             setAuthUserCache(user);
             setState({ user, loading: false });
@@ -155,9 +177,10 @@ export default function AuthUserProvider({ initialUser = null, children }) {
         }
         finally {
             clearSessionCookie(sessionCookieName);
+            clearRefreshTokenCookie(refreshTokenCookieName);
             window.location.assign(fa.redirectAuthPath);
         }
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [fa.redirectAuthPath, sessionCookieName]);
+    }, [fa.redirectAuthPath, sessionCookieName, refreshTokenCookieName]);
     return _jsx(AuthUserContext.Provider, { value: { ...state, reloadUser, sendVerificationEmail, logout }, children: children });
 }

package/dist/src/server/components/server_provider.js

@@ -55,5 +55,11 @@ export default async function LocationzationProvider({ language, messages, child
         }
         initialAuthUser = await authUserServerProviderModule.resolveAuthUserAndRedirect();
     }
-    return _jsx(LocationzationClientProvider, { language: language, messages: messagesValue, initialAuthUser: initialAuthUser, skipAuthProvider: !autoWireClientProvider, children: children });
+    let analyticsSecrets;
+    if (config.cookieConsent && config.cookieConsent.autoWireAnalytics !== false) {
+        analyticsSecrets = config.cookieConsent.getSecrets
+            ? await config.cookieConsent.getSecrets()
+            : config.cookieConsent.secrets;
+    }
+    return _jsx(LocationzationClientProvider, { language: language, messages: messagesValue, initialAuthUser: initialAuthUser, skipAuthProvider: !autoWireClientProvider, analyticsSecrets: analyticsSecrets, children: children });
 }

package/dist/src/types/index.d.ts

@@ -1 +1 @@
-export type { CookieAttributes, LocalePrefixMode, Locales, ReturnType, RoutingConfig, TranslationEntry, TranslationObject, TranslatorReturnType, Alternates, changeFrequency, IntlSitemap, } from './types';
+export type { CookieAttributes, LocalePrefixMode, Locales, ReturnType, RoutingConfig, TranslationEntry, TranslationObject, TranslatorReturnType, Alternates, changeFrequency, IntlSitemap, CookieConsentRoutingConfig, CookieConsentAnalyticsSecrets, } from './types';

package/dist/src/types/types.d.ts

@@ -81,6 +81,65 @@ export interface RoutingConfig<AppLocales extends Locales, AppLocalePrefixMode e
      * if this field is missing at call time rather than silently no-op'ing.
      */
     firebaseAuth?: FirebaseAuthRoutingConfig;
+    /**
+     * Configures the optional `cookie_consent` submodule (cookie-consent +
+     * privacy-policy-update banners). Omit entirely to keep it disabled —
+     * `useCookieConsent()`/`CookieConsentProvider` will throw a descriptive
+     * error if called without this set.
+     */
+    cookieConsent?: CookieConsentRoutingConfig;
+}
+export interface CookieConsentRoutingConfig {
+    /**
+     * Date the current privacy policy was last modified, e.g. `"2026-07-20"`
+     * or a `Date`. When set, the "privacy policy updated" banner
+     * automatically shows to any visitor whose stored consent predates this
+     * date. Omit to disable the privacy-policy-update banner entirely (the
+     * cookie-consent banner still works independently).
+     */
+    privacyPolicyDate?: string | Date;
+    /** Cookie-consent cookie name. Defaults to `'__cookie_consent_key__'`. */
+    consentCookieName?: string;
+    /** Privacy-policy-date cookie name. Defaults to `'__privacy_policy_date_key__'`. */
+    privacyPolicyDateCookieName?: string;
+    /** Cookie max-age in seconds for both cookies above. Defaults to 1 year (31536000). */
+    cookieMaxAge?: number;
+    /**
+     * Whether `IntlProvider` should automatically render the analytics/ads
+     * scripts (Cloudflare Web Analytics beacon, Google Consent Mode + gtag,
+     * Microsoft Clarity — whichever secrets resolve below) once consent is
+     * granted, and gate them behind the cookie-consent banner otherwise.
+     * Defaults to `true` when `secrets`/`getSecrets` is set; set `false` to
+     * keep `cookieConsent` configured for the dialogs/hook only and wire
+     * analytics yourself.
+     */
+    autoWireAnalytics?: boolean;
+    /**
+     * Static secrets/IDs for the analytics providers below. Use this OR
+     * `getSecrets`, not both — `getSecrets` takes precedence when both are
+     * set (e.g. secrets only available at request time from a Cloudflare
+     * `env` binding).
+     */
+    secrets?: CookieConsentAnalyticsSecrets;
+    /**
+     * Resolves the same secrets at request time — e.g. from Cloudflare's
+     * `getCloudflareContext().env` (via `@opennextjs/cloudflare`, not a
+     * dependency of this package — pass your own getter). Any field left
+     * `undefined` in the returned object disables that provider's script.
+     */
+    getSecrets?: () => CookieConsentAnalyticsSecrets | Promise<CookieConsentAnalyticsSecrets>;
+}
+export interface CookieConsentAnalyticsSecrets {
+    /** Cloudflare Web Analytics beacon token, e.g. `'{"token": "..."}'` (the raw `data-cf-beacon` attribute value). */
+    cloudflareBeaconToken?: string;
+    /** Google Analytics measurement ID, e.g. `"G-XXXXXXX"`. */
+    googleAnalyticsId?: string;
+    /** Google Ads conversion ID, e.g. `"AW-XXXXXXXXX"`. */
+    googleAdsId?: string;
+    /** Google AdSense publisher ID, e.g. `"ca-pub-XXXXXXXXXXXXXXXX"`. */
+    googleAdSenseId?: string;
+    /** Microsoft Clarity project ID. */
+    clarityProjectId?: string;
 }
 export interface FirebaseAuthRoutingConfig {
     /**

package/llms.txt

@@ -34,6 +34,15 @@ other subpath can be used.
 - `./firebaseAuthActions` — `createLoginAction`/`createSignUpAction`/`createForgotPasswordAction`: factories returning React `useActionState`-shaped form actions.
 - `./firebaseAuthMiddleware` — `updateSession`: session-cookie refresh, called automatically by `./middleware`'s default handler.
 
+## `cookieConsent*` subpaths (require `cookieConsent` set on your `RoutingConfig`)
+
+- `./cookieConsent` — barrel: `CookieConsentProvider`, `useCookieConsent`, `CookieConsentDialog`, `PrivacyPolicyUpdateDialog`, `CookieConsentAnalytics`.
+- `./CookieConsentProvider` — context provider; reads/writes consent + privacy-policy-date cookies. Auto-wired by `IntlProvider` when `cookieConsent` is configured — manual nesting is optional.
+- `./useCookieConsent` — context hook; throws `"useCookieConsent must be used within a CookieConsentProvider"` if called outside one.
+- `./CookieConsentDialog` — default cookie-consent banner; accepts per-slot `classNames`/`styles` or a `render` prop for fully custom markup.
+- `./PrivacyPolicyUpdateDialog` — "privacy policy updated" banner; auto-enabled only when `cookieConsent.privacyPolicyDate` is set.
+- `./cookieConsentAnalytics` — `CookieConsentAnalytics`: gates Cloudflare Web Analytics / Google Ads / Google Analytics / AdSense / Microsoft Clarity behind consent; rendered automatically by `IntlProvider` when `cookieConsent.secrets` or `getSecrets` is set (and `autoWireAnalytics !== false`).
+
 ## Conventions
 
 - Every exported function/component has a JSDoc comment with an `@example` where usage isn't obvious from the signature alone.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cloudflare-next-intl",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "Optimized Next Intl Package Special for App Router and Cloudflare",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -115,6 +115,30 @@
     "./firebaseAuthMiddleware": {
       "types": "./dist/src/firebase_auth/middleware/update_session.d.ts",
       "import": "./dist/src/firebase_auth/middleware/update_session.js"
+    },
+    "./cookieConsent": {
+      "types": "./dist/src/cookie_consent/index.d.ts",
+      "import": "./dist/src/cookie_consent/index.js"
+    },
+    "./CookieConsentProvider": {
+      "types": "./dist/src/cookie_consent/client/cookie_consent_provider.d.ts",
+      "import": "./dist/src/cookie_consent/client/cookie_consent_provider.js"
+    },
+    "./useCookieConsent": {
+      "types": "./dist/src/cookie_consent/client/use_cookie_consent.d.ts",
+      "import": "./dist/src/cookie_consent/client/use_cookie_consent.js"
+    },
+    "./CookieConsentDialog": {
+      "types": "./dist/src/cookie_consent/client/components/cookie_consent_dialog.d.ts",
+      "import": "./dist/src/cookie_consent/client/components/cookie_consent_dialog.js"
+    },
+    "./PrivacyPolicyUpdateDialog": {
+      "types": "./dist/src/cookie_consent/client/components/privacy_policy_update_dialog.d.ts",
+      "import": "./dist/src/cookie_consent/client/components/privacy_policy_update_dialog.js"
+    },
+    "./cookieConsentAnalytics": {
+      "types": "./dist/src/cookie_consent/client/components/cookie_consent_analytics.d.ts",
+      "import": "./dist/src/cookie_consent/client/components/cookie_consent_analytics.js"
     }
   },
   "scripts": {
@@ -158,6 +182,7 @@
   },
   "homepage": "https://github.com/demian-ilnytskyi/cloudflare-next-intl#readme",
   "peerDependencies": {
+    "@microsoft/clarity": ">=1.0.0",
     "firebase": ">=10.0.0",
     "next": ">=12.0.0",
     "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || >=19.0.0-rc <19.0.0 || ^19.0.0",
@@ -169,11 +194,15 @@
     },
     "firebase": {
       "optional": true
+    },
+    "@microsoft/clarity": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3",
     "@eslint/js": "^9.27.0",
+    "@microsoft/clarity": "^1.0.2",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^7.0.0",
     "@testing-library/react": "^16.3.2",