npm - cookie-app - Versions diffs - 2.0.0 - Mend

cookie-app 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/dist/index.d.mts ADDED Viewed

@@ -0,0 +1,357 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+/** The level of consent granted by the user. */
+type ConsentLevel = 'all' | 'necessary';
+/** Banner language. `'auto'` detects from `navigator.language`. */
+type Language = 'fr' | 'en' | 'auto';
+/** Banner display style. */
+type BannerStyle = 'bar' | 'popup' | 'corner';
+/** Banner position (applies to bar and corner styles). */
+type BannerPosition = 'top' | 'bottom';
+/** Color theme for the banner. */
+type BannerTheme = 'light' | 'dark';
+/** Animation type for the banner entrance/exit. */
+type Animation = 'slide' | 'fade';
+/** Custom text overrides for one language. */
+interface ConsentTexts {
+    /** Banner title. */
+    title?: string;
+    /** Banner message/description. */
+    message?: string;
+    /** Accept button label. */
+    accept?: string;
+    /** Reject button label. */
+    reject?: string;
+    /** Privacy policy link text. */
+    privacy?: string;
+    /** "Powered by" text (only shown when `poweredBy` is true). */
+    powered?: string;
+}
+/** Props for the `<CookieConsent>` component. */
+interface CookieConsentProps {
+    /**
+     * Banner language. `'auto'` detects from `navigator.language`.
+     * @default 'fr'
+     */
+    lang?: Language;
+    /**
+     * Banner position — applies to `bar` and `corner` styles.
+     * @default 'bottom'
+     */
+    position?: BannerPosition;
+    /**
+     * Color theme.
+     * @default 'light'
+     */
+    theme?: BannerTheme;
+    /**
+     * Banner display style.
+     * - `'bar'` — full-width bar fixed to top or bottom.
+     * - `'popup'` — centered modal with overlay.
+     * - `'corner'` — small widget in the corner.
+     * @default 'bar'
+     */
+    style?: BannerStyle;
+    /**
+     * Enable glassmorphism (frosted glass) effect.
+     * @default false
+     */
+    glassmorphism?: boolean;
+    /**
+     * URL to your privacy policy page.
+     * @default '/politique-de-confidentialite'
+     */
+    privacyUrl?: string;
+    /**
+     * Show a "Powered by Rayels" attribution link.
+     * @default false
+     */
+    poweredBy?: boolean;
+    /**
+     * Brand color for the Accept button and reconsent button.
+     * Any valid CSS color string.
+     * @default '#1d4ed8'
+     */
+    brandColor?: string;
+    /**
+     * Number of days before consent expires and the banner reappears.
+     * @default 365
+     */
+    expiryDays?: number;
+    /**
+     * Show a floating reconsent button after the user makes a choice.
+     * @default true
+     */
+    showReconsent?: boolean;
+    /**
+     * Animation type for banner entrance and exit.
+     * @default 'slide'
+     */
+    animation?: Animation;
+    /**
+     * Show cookie emoji icon in the banner title and reconsent button.
+     * @default true
+     */
+    showIcon?: boolean;
+    /**
+     * Custom CSS injected as a `<style>` tag. Target `#loi25-banner`
+     * and `#loi25-reconsent`.
+     * @default ''
+     */
+    customCss?: string;
+    /**
+     * Custom texts for the French banner. Unset fields use built-in defaults.
+     */
+    textsFr?: ConsentTexts;
+    /**
+     * Custom texts for the English banner. Unset fields use built-in defaults.
+     */
+    textsEn?: ConsentTexts;
+    /**
+     * Callback fired when the user makes a consent choice.
+     * Use this to log consent to your backend, analytics, etc.
+     */
+    onConsent?: (level: ConsentLevel) => void;
+    /**
+     * Enable Google Consent Mode v2. Automatically manages `ad_storage`,
+     * `analytics_storage`, `ad_user_data`, and `ad_personalization` signals.
+     *
+     * For full compliance, also place a synchronous `<script>` in `<head>`
+     * using `getConsentModeScript()` **before** the Google tag loads.
+     * @default false
+     */
+    consentMode?: boolean;
+    /**
+     * When `true` and `ad_storage` is denied, ad click identifiers in pings
+     * are redacted and requests go through a cookieless domain.
+     * Maps to `gtag('set', 'ads_data_redaction', true)`.
+     * @default false
+     */
+    adsDataRedaction?: boolean;
+    /**
+     * When `true`, passes ad click information (GCLID / DCLID) through URL
+     * parameters across pages when `ad_storage` is denied.
+     * Maps to `gtag('set', 'url_passthrough', true)`.
+     * @default false
+     */
+    urlPassthrough?: boolean;
+    /**
+     * ISO 3166-2 region codes to scope the consent default.
+     * Example: `['CA-QC']` for Quebec only.
+     * When set, the consent defaults only apply to visitors from those regions,
+     * preserving full measurement for visitors elsewhere.
+     */
+    consentModeRegion?: string[];
+    /**
+     * Milliseconds Google tags wait for a consent update before firing.
+     * Required because React banners always load asynchronously.
+     * @default 500
+     */
+    waitForUpdate?: number;
+    /**
+     * Raw HTML string of analytics/tracking scripts to block until consent.
+     * Scripts are only injected into `<head>` after the user clicks "Accept All".
+     *
+     * Supports Google Analytics, Google Tag Manager, Meta Pixel, Hotjar, etc.
+     * @default ''
+     */
+    scripts?: string;
+    /**
+     * Force a page reload after "Accept All" when `scripts` are provided.
+     * Useful for scripts that must run at page load time (e.g., GTM).
+     * @default false
+     */
+    reloadOnConsent?: boolean;
+}
+/** Return type for the `useConsent` hook. */
+interface ConsentState {
+    /** Current consent level, or `null` if no valid consent exists. */
+    consent: ConsentLevel | null;
+    /** Whether the user has given any consent that hasn't expired. */
+    hasConsent: boolean;
+    /** Reset consent — clears stored consent and triggers the banner to reappear. */
+    resetConsent: () => void;
+    /** Programmatically set the consent level. */
+    setConsent: (level: ConsentLevel) => void;
+}
+/**
+ * Quebec Law 25 cookie consent banner.
+ *
+ * Drop-in React component with script blocking, Google Consent Mode v2,
+ * 3 banner styles (bar / popup / corner), bilingual support, and smooth
+ * animations. Zero external dependencies.
+ *
+ * **Google Consent Mode v2 compliance** requires a synchronous inline
+ * `<script>` in `<head>` that sets consent defaults **before** Google tags
+ * load. Use `getConsentModeScript()` for this. The `<CookieConsent>`
+ * component then handles the `consent('update', ...)` calls when the user
+ * interacts with the banner.
+ *
+ * @example
+ * ```tsx
+ * // app/layout.tsx (Next.js 15 App Router)
+ * import { CookieConsent, getConsentModeScript } from 'cookie-app';
+ *
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <html lang="fr">
+ *       <head>
+ *         // 1. Consent defaults — MUST come before the Google tag
+ *         <script dangerouslySetInnerHTML=&#123;&#123; __html: getConsentModeScript() &#125;&#125; />
+ *         // 2. Google tag (gtag.js)
+ *         <script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXX" />
+ *       </head>
+ *       <body>
+ *         {children}
+ *         // 3. Consent banner — handles consent('update') on user choice
+ *         <CookieConsent
+ *           lang="auto"
+ *           style="popup"
+ *           theme="dark"
+ *           glassmorphism
+ *           consentMode
+ *           adsDataRedaction
+ *           urlPassthrough
+ *           privacyUrl="/privacy"
+ *           onConsent={(level) => console.log('Consent:', level)}
+ *         />
+ *       </body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ */
+declare function CookieConsent({ lang, position, theme, style, glassmorphism, privacyUrl, poweredBy, brandColor, expiryDays, showReconsent, animation, showIcon, customCss, textsFr, textsEn, onConsent, consentMode, adsDataRedaction, urlPassthrough, consentModeRegion, waitForUpdate, scripts, reloadOnConsent, }: CookieConsentProps): react_jsx_runtime.JSX.Element | null;
+/**
+ * React hook to read and manage cookie consent state.
+ *
+ * SSR-safe — returns `null` consent on the server.
+ * Automatically syncs across tabs and with the `<CookieConsent>` component.
+ *
+ * @param expiryDays - Number of days before consent expires. Default: 365.
+ *
+ * @example
+ * ```tsx
+ * const { consent, hasConsent, resetConsent } = useConsent();
+ *
+ * if (hasConsent && consent === 'all') {
+ *   // User accepted all cookies
+ * }
+ * ```
+ */
+declare function useConsent(expiryDays?: number): ConsentState;
+/** Options for the synchronous consent mode default script. */
+interface ConsentModeDefaults {
+    /** Default state for advertising cookie storage. @default 'denied' */
+    analytics_storage?: 'granted' | 'denied';
+    /** Default state for analytics cookie storage. @default 'denied' */
+    ad_storage?: 'granted' | 'denied';
+    /** Default state for sending user data to Google for advertising. @default 'denied' */
+    ad_user_data?: 'granted' | 'denied';
+    /** Default state for personalized advertising. @default 'denied' */
+    ad_personalization?: 'granted' | 'denied';
+    /** Default state for functionality storage (e.g. language settings). @default 'granted' */
+    functionality_storage?: 'granted' | 'denied';
+    /** Default state for personalization storage (e.g. video recommendations). @default 'granted' */
+    personalization_storage?: 'granted' | 'denied';
+    /** Default state for security storage (e.g. authentication, fraud prevention). @default 'granted' */
+    security_storage?: 'granted' | 'denied';
+    /**
+     * Milliseconds Google tags wait for a consent update before firing.
+     * Required for async consent banners (React components always load async).
+     * @default 500
+     */
+    wait_for_update?: number;
+    /**
+     * ISO 3166-2 region codes to scope the consent defaults.
+     * Example: `['CA-QC']` for Quebec only.
+     */
+    region?: string[];
+    /**
+     * When `true` and `ad_storage` is denied, ad click identifiers in pings
+     * are redacted and requests go through a cookieless domain.
+     * @default false
+     */
+    ads_data_redaction?: boolean;
+    /**
+     * When `true`, passes ad click information (GCLID/DCLID) through URL
+     * parameters across pages when `ad_storage` is denied.
+     * @default false
+     */
+    url_passthrough?: boolean;
+    /**
+     * Number of days before stored consent expires.
+     * Must match the `expiryDays` prop on `<CookieConsent>`.
+     * @default 365
+     */
+    expiry_days?: number;
+}
+/**
+ * Returns a self-contained JavaScript string that sets Google Consent Mode v2
+ * defaults **synchronously**. Place this in `<head>` **before** the Google tag
+ * (gtag.js or GTM) so that consent defaults are visible when tags initialize.
+ *
+ * On returning visits where the user previously accepted all cookies, the
+ * script also calls `consent('update', ...)` immediately so tags fire with
+ * full measurement data without waiting for the React banner to hydrate.
+ *
+ * @example
+ * ```tsx
+ * // app/layout.tsx (Next.js App Router)
+ * import { getConsentModeScript } from 'cookie-app';
+ *
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <html lang="fr">
+ *       <head>
+ *         // Consent defaults — MUST come before the Google tag
+ *         <script dangerouslySetInnerHTML=&#123;&#123; __html: getConsentModeScript() &#125;&#125; />
+ *         // Google tag (gtag.js) goes AFTER the consent default
+ *       </head>
+ *       <body>
+ *         {children}
+ *         <CookieConsent consentMode />
+ *       </body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ */
+declare function getConsentModeScript(options?: ConsentModeDefaults): string;
+/** localStorage key for consent level ('all' | 'necessary'). */
+declare const STORAGE_KEY = "loi25-consent";
+/** localStorage key for consent timestamp. */
+declare const STORAGE_DATE_KEY = "loi25-consent-date";
+/** Custom event name dispatched when consent changes programmatically. */
+declare const CONSENT_CHANGE_EVENT = "loi25-consent-change";
+/** Default brand color (blue). */
+declare const DEFAULT_BRAND_COLOR = "#1d4ed8";
+/** Default consent expiry in days. */
+declare const DEFAULT_EXPIRY_DAYS = 365;
+/** Default wait_for_update value in milliseconds for Google Consent Mode v2. */
+declare const DEFAULT_WAIT_FOR_UPDATE = 500;
+/** Default banner texts for both languages. */
+declare const DEFAULT_TEXTS: {
+    readonly fr: {
+        readonly title: "Respect de votre vie privée";
+        readonly message: "Ce site utilise des témoins (cookies) pour améliorer votre expérience. Conformément à la Loi 25 du Québec, nous demandons votre consentement.";
+        readonly accept: "Tout accepter";
+        readonly reject: "Nécessaires seulement";
+        readonly privacy: "Politique de confidentialité";
+        readonly powered: "Propulsé par";
+    };
+    readonly en: {
+        readonly title: "Your Privacy Matters";
+        readonly message: "This website uses cookies to improve your experience. In compliance with Quebec's Law 25, we ask for your consent.";
+        readonly accept: "Accept All";
+        readonly reject: "Necessary Only";
+        readonly privacy: "Privacy Policy";
+        readonly powered: "Powered by";
+    };
+};
+export { type Animation, type BannerPosition, type BannerStyle, type BannerTheme, CONSENT_CHANGE_EVENT, type ConsentLevel, type ConsentModeDefaults, type ConsentState, type ConsentTexts, CookieConsent, type CookieConsentProps, DEFAULT_BRAND_COLOR, DEFAULT_EXPIRY_DAYS, DEFAULT_TEXTS, DEFAULT_WAIT_FOR_UPDATE, type Language, STORAGE_DATE_KEY, STORAGE_KEY, getConsentModeScript, useConsent };