@krysmalskipl/astro-consent-mode 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## 0.1.0 - 2026-10-12
+
+### Features
+
+- Initial release of `@krysmalski/astro-consent-mode`.
+- Astro integration supporting Google Consent Mode v2 with both `basic` and `advanced` loading strategies.
+- Zero-config integration with vanilla-cookieconsent v3.
+- Native tag loaders for Google Tag Manager (GTM), Google Analytics 4 (GA4), Meta Pixel, and Microsoft Clarity.
+- Support for Microsoft Clarity Consent API v2 (`clarity('consentv2', ...)`).
+- Synchronous cookie inspection in `<head>` for returning visitors to eliminate consent lag.
+- Auto-cleaning of analytics and marketing cookies when consent is revoked.
+- 8 ready-made banner layout presets (`box-left`, `box-right`, `box-center`, `box-wide`, `cloud`, `bar-bottom`, `bar-top`, `modal`) plus optional `overlay` backdrop dimming.
+- Dynamic categorization based on configured service IDs.
+- Full Polish (`pl`) and English (`en`) built-in translations with deep customization support.
+- Fully typed configuration with TypeScript declarations and JSDoc annotations.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Krysmalski (https://krysmalski.pl)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,227 @@
-# Temporary Holding Version
+# @krysmalskipl/astro-consent-mode
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Google Consent Mode v2 for Astro - cookie banner, GTM, GA4, Meta Pixel and Microsoft Clarity with zero config.
+
+## Features
+
+- **Google Consent Mode v2**: Full support for `ad_storage`, `ad_user_data`, `ad_personalization`, and `analytics_storage`.
+- **Integrated Cookie Banner**: Powered by vanilla-cookieconsent v3 with an accessible and customizable UI.
+- **Multi-Service Loaders**: First-class support for Google Tag Manager, Google Analytics 4, Meta Pixel (Facebook Pixel), and Microsoft Clarity.
+- **Microsoft Clarity Consent API v2**: Implements `clarity('consentv2', ...)` for proper European Economic Area compliance.
+- **Two Consent Modes**: Choose between `basic` (strict tag blocking until consent) and `advanced` (cookieless pings with default denied).
+- **Synchronous Returning Visitor Handling**: Reads consent synchronously in `<head>` to prevent tagging delays on subsequent page visits.
+- **Auto Cookie Cleanup**: Removes tracking cookies (`_ga`, `_fbp`, `_clck`, etc.) when consent is withdrawn.
+- **Bilingual by Default**: Built-in Polish (`pl`) and English (`en`) translations with deep customization.
+- **Fully Typed**: Includes comprehensive TypeScript definitions and JSDoc documentation.
+
+## Installation
+
+Add the integration to your Astro project:
+
+```bash
+npx astro add @krysmalskipl/astro-consent-mode
+```
+
+Or install manually via npm:
+
+```bash
+npm install @krysmalskipl/astro-consent-mode vanilla-cookieconsent
+```
+
+Then register the integration in your `astro.config.mjs`:
+
+```javascript
+import { defineConfig } from 'astro/config';
+import consent from '@krysmalskipl/astro-consent-mode';
+
+export default defineConfig({
+  integrations: [
+    consent({
+      gtmId: 'GTM-XXXXXX',
+    }),
+  ],
+});
+```
+
+## Usage
+
+```javascript
+import { defineConfig } from 'astro/config';
+import consent from '@krysmalskipl/astro-consent-mode';
+
+export default defineConfig({
+  integrations: [
+    consent({
+      // Tracking IDs
+      gtmId: 'GTM-XXXXXX',        // Optional: Google Tag Manager ID
+      ga4Id: 'G-XXXXXXXXXX',      // Optional: Used if gtmId is omitted
+      metaPixelId: '1234567890',  // Optional: Meta Pixel ID
+      clarityId: 'abcdef1234',    // Optional: Microsoft Clarity ID
+
+      // Strategy and Language
+      mode: 'basic',              // 'basic' | 'advanced' (default: 'basic')
+      lang: 'pl',                 // 'pl' | 'en' (default: 'pl')
+      privacyUrl: '/polityka-prywatnosci/', // Link to Privacy Policy
+
+      // Revisions & Customizations
+      revision: 0,                // Increment to force re-consent
+      texts: {                    // Custom text overrides
+        consentModal: {
+          title: 'Dbamy o Twoją prywatność',
+        },
+      },
+      gui: {
+        consentModal: {
+          layout: 'box',
+          position: 'bottom left',
+        },
+      },
+    }),
+  ],
+});
+```
+
+## Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `gtmId` | `string` | `undefined` | Google Tag Manager ID (e.g. `'GTM-XXXXXX'`). Takes precedence over `ga4Id`. |
+| `ga4Id` | `string` | `undefined` | Google Analytics 4 Measurement ID (e.g. `'G-XXXXXX'`). |
+| `metaPixelId` | `string` | `undefined` | Meta Pixel ID (numeric string, e.g. `'1234567890'`). |
+| `clarityId` | `string` | `undefined` | Microsoft Clarity Project ID (alphanumeric string). |
+| `mode` | `'basic' \| 'advanced'` | `'basic'` | Tag loading strategy. In `basic`, tags are blocked until consent. In `advanced`, Google and Clarity load immediately with default `denied`. |
+| `lang` | `'pl' \| 'en'` | `'pl'` | Default language for cookie consent modal. |
+| `privacyUrl` | `string` | `'/polityka-prywatnosci/'` (pl) or `'/privacy-policy/'` (en) | Target URL for privacy policy link. |
+| `texts` | `object` | `undefined` | DeepPartial object overriding default modal translations. |
+| `banner` | `string` | `'box-left'` | Banner layout preset - see [Banner layouts](#banner-layouts). |
+| `overlay` | `boolean` | `true` for `'modal'`, otherwise `false` | Dim the page and block interaction until the visitor decides. |
+| `gui` | `object` | `{}` | Low-level vanilla-cookieconsent `guiOptions`, merged on top of the `banner` preset. |
+| `revision` | `number` | `0` | Revision counter. Incrementing invalidates stored cookies and re-prompts visitors. |
+| `urlPassthrough` | `boolean` | `true` | Enables `url_passthrough` in Google tag to retain ad click info across pages without cookies. |
+| `adsDataRedaction` | `boolean` | `true` | Enables `ads_data_redaction` in Google tag when ad consent is denied. |
+| `waitForUpdate` | `number` | `500` | Milliseconds Google tag waits for consent update before firing. |
+| `enabled` | `boolean` | `true` (when any ID is provided) | Explicit toggle to enable or disable the integration completely. |
+
+## How it works
+
+### Lifecycle & Loading Flow
+
+1. **Default Denied (`<head>`)**:
+   Before any tags load, an inline script in `<head>` sets Google Consent Mode v2 default signals to `denied` for all storage categories (`ad_storage`, `ad_user_data`, `ad_personalization`, `analytics_storage`).
+2. **Synchronous Cookie Check**:
+   The script checks `document.cookie` for an existing `cc_cookie`. If valid consent is found (matching current `revision`), consent signals are updated immediately and granted tags begin loading without waiting for the client bundle.
+3. **Cookie Banner Evaluation**:
+   If no consent is recorded, the cookie banner displays on the client.
+4. **Consent Update & Dynamic Tag Dispatch**:
+   When the user grants or revokes consent via `onConsent` or `onChange`, `window.__acm.apply(categories)` updates Google signals, loads allowed scripts idempotently, and updates Meta Pixel and Microsoft Clarity consent states.
+
+### Service Loading Matrix
+
+| Service | Category | `basic` Mode (Before Consent) | `basic` Mode (After Consent) | `advanced` Mode (Before Consent) | `advanced` Mode (After Consent) |
+| --- | --- | --- | --- | --- | --- |
+| Google Tag Manager | Analytics / Marketing | Blocked | Loaded upon `analytics` or `marketing` consent | Loaded immediately (denied signals) | Signals updated to granted |
+| Google Analytics 4 | Analytics | Blocked | Loaded upon `analytics` consent | Loaded immediately (denied signals) | Signals updated to granted |
+| Meta Pixel | Marketing | Blocked | Loaded upon `marketing` consent | Blocked (always requires marketing consent) | Loaded upon `marketing` consent |
+| Microsoft Clarity | Analytics | Blocked | Loaded upon `analytics` consent | Loaded immediately (`consentv2` denied) | `consentv2` updated to granted |
+
+## Opening Preferences
+
+Visitors can reopen the cookie preferences modal anytime by clicking any HTML element that includes `data-cc="show-preferencesModal"`:
+
+```html
+<button type="button" data-cc="show-preferencesModal">
+  Cookie settings
+</button>
+```
+
+You can also open it programmatically in your client scripts:
+
+```javascript
+import { showPreferences } from '@krysmalskipl/astro-consent-mode/client';
+
+showPreferences();
+```
+
+## Banner layouts
+
+Choose a ready-made layout using the `banner` option:
+
+| Preset | Description |
+|---|---|
+| `'box-left'` *(default)* | Compact card in the bottom-left corner |
+| `'box-right'` | Compact card in the bottom-right corner |
+| `'box-center'` | Compact card centered at the bottom |
+| `'box-wide'` | Wider card in the bottom-left corner |
+| `'cloud'` | Floating card centered at the bottom, buttons aligned beside the text |
+| `'bar-bottom'` | Full-width bar anchored to the bottom edge |
+| `'bar-top'` | Full-width bar anchored to the top edge |
+| `'modal'` | Centered modal window with a dimmed page backdrop (sets `overlay: true` automatically) |
+
+You can also dim the page background and prevent page interactions for any layout by setting `overlay: true`:
+
+```ts
+consent({
+  gtmId: 'GTM-XXXXXX',
+  banner: 'box-right',
+  overlay: true,
+})
+```
+
+## Styling
+
+The banner is styled using vanilla-cookieconsent v3 CSS variables. You can override colors, fonts, and border radius in your global CSS stylesheet:
+
+```css
+:root {
+  --cc-font-family: inherit;
+  --cc-btn-primary-bg: #2563eb;
+  --cc-btn-primary-hover-bg: #1d4ed8;
+  --cc-btn-primary-color: #ffffff;
+  --cc-btn-secondary-bg: #f1f5f9;
+  --cc-btn-secondary-hover-bg: #e2e8f0;
+  --cc-btn-secondary-color: #0f172a;
+  --cc-modal-border-radius: 1rem;
+  --cc-btn-border-radius: 0.5rem;
+}
+```
+
+## Translations
+
+Built-in translations support Polish (`pl`) and English (`en`). You can override specific labels or add additional languages via the `texts` option:
+
+```javascript
+consent({
+  lang: 'pl',
+  texts: {
+    consentModal: {
+      title: 'Dbamy o Twoją prywatność',
+      acceptAllBtn: 'Zezwól na wszystkie',
+    },
+  },
+})
+```
+
+## Testing with Google Tag Assistant
+
+To verify that Google Consent Mode v2 is functioning correctly:
+
+1. Open [Google Tag Assistant](https://tagassistant.google.com/) and connect your site.
+2. Check the **Consent** tab: you should see `Consent Default` with all storage types `denied` right after page load.
+3. Accept cookies in the banner: Tag Assistant will record a `Consent Update` event with updated `granted` values.
+
+## Limitations
+
+- **Not a Google-certified CMP**: This integration provides Google Consent Mode v2 for standard tracking setups (GA4, Google Ads, Meta Pixel, Clarity). However, publishers serving ads via Google AdSense, Google Ad Manager, or AdMob in the EEA, UK, or Switzerland must use a Google-certified Consent Management Platform supporting TCF v2.2.
+- **Legal Disclaimer**: This software is provided as a technical solution and does not constitute legal advice. Ensure your privacy policy and cookie categories comply with local regulations (such as GDPR and ePrivacy).
+
+## Po polsku
+
+Integracja Astro dla Google Consent Mode v2 z gotowym banerem cookies, obsługą GTM, GA4, Meta Pixel oraz Microsoft Clarity. Działa od razu po instalacji z domyślnym językiem polskim i automatycznym czyszczeniem ciasteczek po wycofaniu zgody. Więcej o nowoczesnych stronach na Astro: [krysmalski.pl](https://krysmalski.pl).
+
+## License
+
+MIT - Copyright (c) 2026 Krysmalski.
+
+## Author
+
+Built and maintained by [Krysmalski](https://krysmalski.pl) - websites and Astro development.

package/dist/client.js

@@ -0,0 +1,71 @@
+// src/client.ts
+import css from "vanilla-cookieconsent/dist/cookieconsent.css?inline";
+import * as CookieConsent from "vanilla-cookieconsent";
+import config from "virtual:astro-consent-mode/config";
+if (typeof document !== "undefined" && !document.getElementById("acm-style")) {
+  const style = document.createElement("style");
+  style.id = "acm-style";
+  style.textContent = css;
+  document.head.prepend(style);
+}
+function showPreferences2() {
+  if (typeof window !== "undefined") {
+    CookieConsent.showPreferences();
+  }
+}
+var categories = {
+  necessary: {
+    enabled: true,
+    readOnly: true
+  }
+};
+if (config.hasAnalytics) {
+  categories.analytics = {
+    autoClear: {
+      cookies: [
+        { name: /^_ga/ },
+        { name: "_gid" },
+        { name: /^_gat/ },
+        { name: /^_clck/ },
+        { name: /^_clsk/ },
+        { name: "CLID" }
+      ],
+      reloadPage: true
+    }
+  };
+}
+if (config.hasMarketing) {
+  categories.marketing = {
+    autoClear: {
+      cookies: [
+        { name: /^_gcl/ },
+        { name: /^_fbp/ },
+        { name: /^_fbc/ }
+      ],
+      reloadPage: true
+    }
+  };
+}
+var syncConsent = () => {
+  const preferences = CookieConsent.getUserPreferences();
+  const acceptedCategories = preferences.acceptedCategories || [];
+  window.__acm?.apply(acceptedCategories);
+};
+if (typeof window !== "undefined") {
+  CookieConsent.run({
+    revision: config.revision,
+    // Resolved at build time from the `banner` preset merged with `gui`.
+    guiOptions: config.gui,
+    disablePageInteraction: config.overlay,
+    categories,
+    language: {
+      default: config.lang,
+      translations: config.translations
+    },
+    onConsent: syncConsent,
+    onChange: syncConsent
+  });
+}
+export {
+  showPreferences2 as showPreferences
+};

package/dist/index.d.ts

@@ -0,0 +1,231 @@
+import { AstroIntegration } from 'astro';
+
+/**
+ * Recursive partial utility type.
+ */
+type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends (infer U)[] ? DeepPartial<U>[] : T[P] extends readonly (infer U)[] ? readonly DeepPartial<U>[] : T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+/**
+ * Text configuration for the initial consent modal banner.
+ */
+interface ConsentModalTranslation {
+    /** Title of the consent modal */
+    title?: string;
+    /** Main description explaining cookie usage */
+    description?: string;
+    /** Label for the "Accept all" button */
+    acceptAllBtn?: string;
+    /** Label for the "Reject non-essential / Necessary only" button */
+    acceptNecessaryBtn?: string;
+    /** Label for the "Preferences / Settings" button */
+    showPreferencesBtn?: string;
+    /** HTML footer content, e.g. link to Privacy Policy */
+    footer?: string;
+}
+/**
+ * Section item in the cookie preferences modal.
+ */
+interface PreferencesSection {
+    /** Optional title of the preferences category/section */
+    title?: string;
+    /** Informational description of the category or policy */
+    description?: string;
+    /** Linked cookie consent category (e.g. 'necessary', 'analytics', 'marketing') */
+    linkedCategory?: string;
+}
+/**
+ * Text configuration for the detailed cookie preferences modal.
+ */
+interface PreferencesModalTranslation {
+    /** Title of the preferences modal */
+    title?: string;
+    /** Label for the "Accept all" button inside preferences */
+    acceptAllBtn?: string;
+    /** Label for the "Necessary only" button inside preferences */
+    acceptNecessaryBtn?: string;
+    /** Label for the "Save choices" button inside preferences */
+    savePreferencesBtn?: string;
+    /** Accessibility label for the close icon */
+    closeIconLabel?: string;
+    /** Array of informational and category sections */
+    sections?: PreferencesSection[];
+}
+/**
+ * Complete set of translations for a single language.
+ */
+interface Translation {
+    /** Texts for the primary cookie consent modal */
+    consentModal: ConsentModalTranslation;
+    /** Texts for the cookie preferences modal */
+    preferencesModal: PreferencesModalTranslation;
+}
+/**
+ * Modal layout options for vanilla-cookieconsent.
+ */
+interface ModalGuiOptions {
+    /** Layout style, e.g. 'box', 'bar', 'cloud' */
+    layout?: string;
+    /** Modal screen position, e.g. 'bottom left', 'bottom right', 'middle center' */
+    position?: string;
+    /** Give all primary action buttons equal visual weight */
+    equalWeightButtons?: boolean;
+    /** Invert button order */
+    flipButtons?: boolean;
+}
+/**
+ * GUI configuration options for vanilla-cookieconsent modals.
+ */
+interface GuiOptions {
+    /** Configuration for the primary consent banner */
+    consentModal?: ModalGuiOptions;
+    /** Configuration for the preferences management modal */
+    preferencesModal?: ModalGuiOptions;
+}
+/**
+ * Ready-made banner layouts. See `ConsentOptions.banner`.
+ */
+type BannerPreset = 'box-left' | 'box-right' | 'box-center' | 'box-wide' | 'cloud' | 'bar-bottom' | 'bar-top' | 'modal';
+/**
+ * Options for configuring @krysmalskipl/astro-consent-mode integration.
+ */
+interface ConsentOptions {
+    /**
+     * Google Tag Manager Container ID (e.g. 'GTM-XXXXXX').
+     * When provided, GTM handles tag deployment.
+     */
+    gtmId?: string;
+    /**
+     * Google Analytics 4 Measurement ID (e.g. 'G-XXXXXX').
+     * Used only when gtmId is not specified.
+     */
+    ga4Id?: string;
+    /**
+     * Meta Pixel (Facebook Pixel) ID (numeric string, e.g. '123456789012345').
+     */
+    metaPixelId?: string;
+    /**
+     * Microsoft Clarity Project ID (alphanumeric string, e.g. 'abcdef1234').
+     */
+    clarityId?: string;
+    /**
+     * Consent Mode loading strategy:
+     * - 'basic': All tracking tags are blocked until the visitor grants consent.
+     * - 'advanced': GTM/GA4 and Clarity load immediately with default 'denied' consent signals.
+     * Defaults to 'basic'.
+     */
+    mode?: 'basic' | 'advanced';
+    /**
+     * Default language for cookie consent text ('pl' | 'en').
+     * Defaults to 'pl'.
+     */
+    lang?: 'pl' | 'en';
+    /**
+     * URL to your privacy policy page.
+     * Defaults to '/polityka-prywatnosci/' for 'pl', or '/privacy-policy/' for 'en'.
+     */
+    privacyUrl?: string;
+    /**
+     * Custom text overrides for translations.
+     * Can be provided as a language map (e.g. { pl: { consentModal: { ... } } })
+     * or directly for the active language (e.g. { consentModal: { ... } }).
+     */
+    texts?: DeepPartial<Record<string, Translation>> | DeepPartial<Translation>;
+    /**
+     * Banner layout preset:
+     * - 'box-left' (default): compact card in the bottom left corner
+     * - 'box-right': compact card in the bottom right corner
+     * - 'box-center': compact card at the bottom center
+     * - 'box-wide': wider card in the bottom left corner
+     * - 'cloud': wide floating card at the bottom center, buttons next to the text
+     * - 'bar-bottom': full-width bar at the bottom of the page
+     * - 'bar-top': full-width bar at the top of the page
+     * - 'modal': centered dialog with a dimmed page overlay (implies `overlay: true`)
+     */
+    banner?: BannerPreset;
+    /**
+     * Dim the page and block interaction until the visitor makes a choice.
+     * Defaults to true for the 'modal' preset, false otherwise.
+     */
+    overlay?: boolean;
+    /**
+     * Low-level UI configuration for consent and preferences modals.
+     * Merged on top of the `banner` preset, so you can fine-tune any of its values.
+     */
+    gui?: GuiOptions;
+    /**
+     * Revision number of the consent configuration.
+     * Incrementing this number invalidates past user consents and re-prompts visitors.
+     * Defaults to 0.
+     */
+    revision?: number;
+    /**
+     * Whether to enable Google Tag url_passthrough to preserve ad click identifiers across pages.
+     * Defaults to true.
+     */
+    urlPassthrough?: boolean;
+    /**
+     * Whether to enable Google Tag ads_data_redaction when ad storage consent is denied.
+     * Defaults to true.
+     */
+    adsDataRedaction?: boolean;
+    /**
+     * Milliseconds Google Consent Mode waits for an updated consent state before firing tags.
+     * Defaults to 500.
+     */
+    waitForUpdate?: number;
+    /**
+     * Explicitly enable or disable the integration.
+     * Defaults to true when any tracking ID is present; false completely disables scripts.
+     */
+    enabled?: boolean;
+}
+/**
+ * Fully resolved integration options.
+ */
+interface ResolvedConsentOptions {
+    gtmId?: string;
+    ga4Id?: string;
+    metaPixelId?: string;
+    clarityId?: string;
+    mode: 'basic' | 'advanced';
+    lang: 'pl' | 'en';
+    privacyUrl: string;
+    texts?: DeepPartial<Record<string, Translation>> | DeepPartial<Translation>;
+    gui: GuiOptions;
+    revision: number;
+    urlPassthrough: boolean;
+    adsDataRedaction: boolean;
+    waitForUpdate: number;
+    enabled: boolean;
+    hasAnalytics: boolean;
+    hasMarketing: boolean;
+    analyticsServices: string[];
+    marketingServices: string[];
+}
+/**
+ * Client runtime configuration passed via virtual module.
+ */
+interface ClientConfig {
+    hasAnalytics: boolean;
+    hasMarketing: boolean;
+    analyticsServices: string[];
+    marketingServices: string[];
+    lang: 'pl' | 'en';
+    privacyUrl: string;
+    translations: Record<string, Translation>;
+    gui: GuiOptions;
+    overlay: boolean;
+    revision: number;
+    mode: 'basic' | 'advanced';
+}
+
+/**
+ * Astro integration for Google Consent Mode v2 + cookie consent banner + GTM / GA4 / Meta Pixel / Clarity.
+ *
+ * @param options Integration options
+ * @returns Astro integration definition
+ */
+declare function consent(options?: ConsentOptions): AstroIntegration;
+
+export { type BannerPreset, type ClientConfig, type ConsentModalTranslation, type ConsentOptions, type DeepPartial, type GuiOptions, type ModalGuiOptions, type PreferencesModalTranslation, type PreferencesSection, type ResolvedConsentOptions, type Translation, consent, consent as default };

package/dist/index.js

@@ -0,0 +1,499 @@
+// src/head.ts
+function buildHeadScript(options) {
+  const {
+    gtmId = "",
+    ga4Id = "",
+    metaPixelId = "",
+    clarityId = "",
+    mode,
+    revision,
+    waitForUpdate,
+    adsDataRedaction,
+    urlPassthrough
+  } = options;
+  const hasGoogle = Boolean(gtmId || ga4Id);
+  const hasMeta = Boolean(metaPixelId);
+  const hasClarity = Boolean(clarityId);
+  return `(function(){
+var mode=${JSON.stringify(mode)};
+var gtmId=${JSON.stringify(gtmId)};
+var ga4Id=${JSON.stringify(ga4Id)};
+var metaPixelId=${JSON.stringify(metaPixelId)};
+var clarityId=${JSON.stringify(clarityId)};
+var rev=${revision};
+var gLoaded=false;
+var metaLoaded=false;
+var clLoaded=false;
+
+function getHead(){return document.head||document.getElementsByTagName('head')[0]||document.documentElement;}
+
+function loadGoogle(){
+  if(gLoaded)return;
+  gLoaded=true;
+  var s=document.createElement('script');
+  s.async=true;
+  if(gtmId){
+    window.dataLayer.push({'gtm.start':Date.now(),event:'gtm.js'});
+    s.src='https://www.googletagmanager.com/gtm.js?id='+gtmId;
+  }else if(ga4Id){
+    s.src='https://www.googletagmanager.com/gtag/js?id='+ga4Id;
+    window.gtag('js',new Date());
+    window.gtag('config',ga4Id);
+  }
+  getHead().appendChild(s);
+}
+
+function loadMeta(){
+  if(metaLoaded||!metaPixelId)return;
+  metaLoaded=true;
+  (function(f,b,e,v,n,t,s){
+    if(f.fbq)return;n=f.fbq=function(){n.callMethod?n.callMethod.apply(n,arguments):n.queue.push(arguments)};
+    if(!f._fbq)f._fbq=n;n.push=n;n.loaded=true;n.version='2.0';n.queue=[];
+    t=b.createElement(e);t.async=true;t.src=v;
+    s=getHead();s.appendChild(t);
+  })(window,document,'script','https://connect.facebook.net/en_US/fbevents.js');
+  window.fbq('init',metaPixelId);
+  window.fbq('track','PageView');
+}
+
+function loadClarity(){
+  if(clLoaded||!clarityId)return;
+  clLoaded=true;
+  (function(c,l,a,r,i,t,y){
+    c[a]=c[a]||function(){(c[a].q=c[a].q||[]).push(arguments)};
+    t=l.createElement(r);t.async=1;t.src="https://www.clarity.ms/tag/"+i;
+    y=getHead();y.appendChild(t);
+  })(window,document,"clarity","script",clarityId);
+}
+
+${hasGoogle ? `window.dataLayer=window.dataLayer||[];
+window.gtag=function(){window.dataLayer.push(arguments);};
+window.gtag('consent','default',{
+  ad_storage:'denied',
+  ad_user_data:'denied',
+  ad_personalization:'denied',
+  analytics_storage:'denied',
+  personalization_storage:'denied',
+  functionality_storage:'granted',
+  security_storage:'granted',
+  wait_for_update:${waitForUpdate}
+});
+${adsDataRedaction ? `window.gtag('set','ads_data_redaction',true);` : ""}
+${urlPassthrough ? `window.gtag('set','url_passthrough',true);` : ""}` : ""}
+
+window.__acm={
+  apply:function(cats){
+    cats=cats||[];
+    var an=cats.indexOf('analytics')!==-1;
+    var mk=cats.indexOf('marketing')!==-1;
+
+    ${hasGoogle ? `if(window.gtag){
+      window.gtag('consent','update',{
+        analytics_storage:an?'granted':'denied',
+        ad_storage:mk?'granted':'denied',
+        ad_user_data:mk?'granted':'denied',
+        ad_personalization:mk?'granted':'denied',
+        personalization_storage:mk?'granted':'denied'
+      });
+    }
+    if(mode==='advanced'||an||mk){
+      loadGoogle();
+    }` : ""}
+
+    ${hasMeta ? `if(mk){
+      if(!metaLoaded){loadMeta();}
+      else if(window.fbq){window.fbq('consent','grant');}
+    }else if(metaLoaded&&window.fbq){
+      window.fbq('consent','revoke');
+    }` : ""}
+
+    ${hasClarity ? `var adState=mk?'granted':'denied';
+    var anState=an?'granted':'denied';
+    if(mode==='advanced'){
+      if(!clLoaded)loadClarity();
+      if(window.clarity){window.clarity('consentv2',{ad_Storage:adState,analytics_Storage:anState});}
+    }else{
+      if(an){
+        if(!clLoaded)loadClarity();
+        if(window.clarity){window.clarity('consentv2',{ad_Storage:adState,analytics_Storage:'granted'});}
+      }else if(clLoaded&&window.clarity){
+        window.clarity('consentv2',{ad_Storage:'denied',analytics_Storage:'denied'});
+      }
+    }` : ""}
+  }
+};
+
+var savedCats=null;
+try{
+  var m=document.cookie.match(/(?:^|; *)cc_cookie=([^;]+)/);
+  if(m){
+    var parsed=JSON.parse(decodeURIComponent(m[1]));
+    var sRev=typeof parsed.revision==='number'?parsed.revision:0;
+    if(sRev===rev&&Array.isArray(parsed.categories)){
+      savedCats=parsed.categories;
+    }
+  }
+}catch(e){}
+
+if(savedCats){
+  window.__acm.apply(savedCats);
+}else if(mode==='advanced'){
+  ${hasGoogle ? `loadGoogle();` : ""}
+  ${hasClarity ? `loadClarity();
+  if(window.clarity){window.clarity('consentv2',{ad_Storage:'denied',analytics_Storage:'denied'});}` : ""}
+}
+})();`;
+}
+
+// src/translations.ts
+function isObject(item) {
+  return item !== null && typeof item === "object" && !Array.isArray(item);
+}
+function deepMerge(target, source) {
+  if (!source || typeof source !== "object") return target;
+  const output = { ...target };
+  const sourceRecord = source;
+  for (const key of Object.keys(sourceRecord)) {
+    const sourceVal = sourceRecord[key];
+    const targetVal = output[key];
+    if (sourceVal === void 0) continue;
+    if (isObject(sourceVal) && isObject(targetVal)) {
+      output[key] = deepMerge(targetVal, sourceVal);
+    } else {
+      output[key] = sourceVal;
+    }
+  }
+  return output;
+}
+function buildDefaultTranslations(params) {
+  const {
+    privacyUrl,
+    hasAnalytics,
+    hasMarketing,
+    analyticsServices,
+    marketingServices
+  } = params;
+  const plAnalyticsSuffix = analyticsServices.length > 0 ? ` (np. ${analyticsServices.join(", ")})` : "";
+  const plMarketingSuffix = marketingServices.length > 0 ? ` (np. ${marketingServices.join(", ")})` : "";
+  const enAnalyticsSuffix = analyticsServices.length > 0 ? ` (e.g. ${analyticsServices.join(", ")})` : "";
+  const enMarketingSuffix = marketingServices.length > 0 ? ` (e.g. ${marketingServices.join(", ")})` : "";
+  const plSections = [
+    {
+      description: `Mo\u017Cesz w ka\u017Cdej chwili zmieni\u0107 swoje wybory. Szczeg\xF3\u0142y znajdziesz w <a href="${privacyUrl}">polityce prywatno\u015Bci</a>.`
+    },
+    {
+      title: "Niezb\u0119dne",
+      description: "Wymagane do dzia\u0142ania strony, np. zapami\u0119tanie Twoich wybor\xF3w dotycz\u0105cych cookies.",
+      linkedCategory: "necessary"
+    }
+  ];
+  if (hasAnalytics) {
+    plSections.push({
+      title: "Analityczne",
+      description: `Pomagaj\u0105 nam zrozumie\u0107, jak korzystasz ze strony${plAnalyticsSuffix}.`,
+      linkedCategory: "analytics"
+    });
+  }
+  if (hasMarketing) {
+    plSections.push({
+      title: "Marketingowe",
+      description: `S\u0142u\u017C\u0105 do mierzenia skuteczno\u015Bci reklam i dopasowania ich do Twoich zainteresowa\u0144${plMarketingSuffix}.`,
+      linkedCategory: "marketing"
+    });
+  }
+  const enSections = [
+    {
+      description: `You can change your choices at any time. For more details, see our <a href="${privacyUrl}">privacy policy</a>.`
+    },
+    {
+      title: "Necessary",
+      description: "Required for the site to function properly, e.g. remembering your cookie choices.",
+      linkedCategory: "necessary"
+    }
+  ];
+  if (hasAnalytics) {
+    enSections.push({
+      title: "Analytics",
+      description: `Help us understand how you use the website${enAnalyticsSuffix}.`,
+      linkedCategory: "analytics"
+    });
+  }
+  if (hasMarketing) {
+    enSections.push({
+      title: "Marketing",
+      description: `Used to measure advertising effectiveness and tailor ads to your interests${enMarketingSuffix}.`,
+      linkedCategory: "marketing"
+    });
+  }
+  const pl = {
+    consentModal: {
+      title: "Szanujemy Twoj\u0105 prywatno\u015B\u0107",
+      description: "U\u017Cywamy plik\xF3w cookies, aby analizowa\u0107 ruch i ulepsza\u0107 stron\u0119. Cookies analityczne i marketingowe w\u0142\u0105czymy tylko za Twoj\u0105 zgod\u0105.",
+      acceptAllBtn: "Akceptuj\u0119 wszystkie",
+      acceptNecessaryBtn: "Tylko niezb\u0119dne",
+      showPreferencesBtn: "Ustawienia",
+      footer: `<a href="${privacyUrl}">Polityka prywatno\u015Bci</a>`
+    },
+    preferencesModal: {
+      title: "Ustawienia cookies",
+      acceptAllBtn: "Akceptuj\u0119 wszystkie",
+      acceptNecessaryBtn: "Tylko niezb\u0119dne",
+      savePreferencesBtn: "Zapisz wyb\xF3r",
+      closeIconLabel: "Zamknij",
+      sections: plSections
+    }
+  };
+  const en = {
+    consentModal: {
+      title: "We value your privacy",
+      description: "We use cookies to analyze traffic and improve the website. Analytics and marketing cookies will only be activated with your consent.",
+      acceptAllBtn: "Accept all",
+      acceptNecessaryBtn: "Necessary only",
+      showPreferencesBtn: "Preferences",
+      footer: `<a href="${privacyUrl}">Privacy policy</a>`
+    },
+    preferencesModal: {
+      title: "Cookie preferences",
+      acceptAllBtn: "Accept all",
+      acceptNecessaryBtn: "Necessary only",
+      savePreferencesBtn: "Save preferences",
+      closeIconLabel: "Close",
+      sections: enSections
+    }
+  };
+  return { pl, en };
+}
+function resolveTranslations(params, defaultLang, customTexts) {
+  const translations = buildDefaultTranslations(params);
+  if (!customTexts) {
+    return translations;
+  }
+  const textsRecord = customTexts;
+  if ("consentModal" in textsRecord || "preferencesModal" in textsRecord) {
+    translations[defaultLang] = deepMerge(
+      translations[defaultLang],
+      textsRecord
+    );
+    return translations;
+  }
+  for (const [langKey, langValue] of Object.entries(textsRecord)) {
+    if (!langValue || typeof langValue !== "object") continue;
+    if (translations[langKey]) {
+      translations[langKey] = deepMerge(
+        translations[langKey],
+        langValue
+      );
+    } else {
+      const base = translations[defaultLang] || translations.en;
+      translations[langKey] = deepMerge(
+        base,
+        langValue
+      );
+    }
+  }
+  return translations;
+}
+
+// src/index.ts
+function virtualConfigPlugin(clientConfig) {
+  const virtualModuleId = "virtual:astro-consent-mode/config";
+  const resolvedVirtualModuleId = "\0" + virtualModuleId;
+  return {
+    name: "vite-plugin-astro-consent-mode-config",
+    resolveId(id) {
+      if (id === virtualModuleId) {
+        return resolvedVirtualModuleId;
+      }
+    },
+    load(id) {
+      if (id === resolvedVirtualModuleId) {
+        return `export default ${JSON.stringify(clientConfig)};`;
+      }
+    }
+  };
+}
+function validateOptions(options) {
+  if (options.gtmId && !/^GTM-[A-Z0-9]+$/i.test(options.gtmId)) {
+    throw new Error(
+      `[@krysmalskipl/astro-consent-mode] Invalid "gtmId": expected format "GTM-XXXXXX", received "${options.gtmId}".`
+    );
+  }
+  if (options.ga4Id && !/^G-[A-Z0-9]+$/i.test(options.ga4Id)) {
+    throw new Error(
+      `[@krysmalskipl/astro-consent-mode] Invalid "ga4Id": expected format "G-XXXXXX", received "${options.ga4Id}".`
+    );
+  }
+  if (options.metaPixelId && !/^\d+$/.test(options.metaPixelId)) {
+    throw new Error(
+      `[@krysmalskipl/astro-consent-mode] Invalid "metaPixelId": expected numeric string, received "${options.metaPixelId}".`
+    );
+  }
+  if (options.clarityId && !/^[a-z0-9]+$/i.test(options.clarityId)) {
+    throw new Error(
+      `[@krysmalskipl/astro-consent-mode] Invalid "clarityId": expected alphanumeric string, received "${options.clarityId}".`
+    );
+  }
+  if (options.mode && options.mode !== "basic" && options.mode !== "advanced") {
+    throw new Error(
+      `[@krysmalskipl/astro-consent-mode] Invalid "mode": expected "basic" | "advanced", received "${options.mode}".`
+    );
+  }
+  if (options.lang && options.lang !== "pl" && options.lang !== "en") {
+    throw new Error(
+      `[@krysmalskipl/astro-consent-mode] Invalid "lang": expected "pl" | "en", received "${options.lang}".`
+    );
+  }
+  if (options.banner && !(options.banner in BANNER_PRESETS)) {
+    throw new Error(
+      `[@krysmalskipl/astro-consent-mode] Invalid "banner": expected one of ${Object.keys(BANNER_PRESETS).map((k) => `"${k}"`).join(" | ")}, received "${options.banner}".`
+    );
+  }
+}
+var BOX_PREFERENCES = { layout: "box", equalWeightButtons: true };
+var BANNER_PRESETS = {
+  "box-left": {
+    consentModal: { layout: "box", position: "bottom left", equalWeightButtons: true },
+    preferencesModal: BOX_PREFERENCES
+  },
+  "box-right": {
+    consentModal: { layout: "box", position: "bottom right", equalWeightButtons: true },
+    preferencesModal: BOX_PREFERENCES
+  },
+  "box-center": {
+    consentModal: { layout: "box", position: "bottom center", equalWeightButtons: true },
+    preferencesModal: BOX_PREFERENCES
+  },
+  "box-wide": {
+    consentModal: { layout: "box wide", position: "bottom left", equalWeightButtons: true },
+    preferencesModal: BOX_PREFERENCES
+  },
+  cloud: {
+    consentModal: { layout: "cloud inline", position: "bottom center", equalWeightButtons: true },
+    preferencesModal: BOX_PREFERENCES
+  },
+  "bar-bottom": {
+    consentModal: { layout: "bar inline", position: "bottom", equalWeightButtons: true },
+    preferencesModal: BOX_PREFERENCES
+  },
+  "bar-top": {
+    consentModal: { layout: "bar inline", position: "top", equalWeightButtons: true },
+    preferencesModal: BOX_PREFERENCES
+  },
+  modal: {
+    consentModal: { layout: "box", position: "middle center", equalWeightButtons: true },
+    preferencesModal: BOX_PREFERENCES
+  }
+};
+function consent(options = {}) {
+  validateOptions(options);
+  const hasAnyId = Boolean(
+    options.gtmId || options.ga4Id || options.metaPixelId || options.clarityId
+  );
+  const isEnabled = options.enabled !== void 0 ? options.enabled : hasAnyId;
+  const mode = options.mode ?? "basic";
+  const lang = options.lang ?? "pl";
+  const defaultPrivacyUrl = lang === "en" ? "/privacy-policy/" : "/polityka-prywatnosci/";
+  const privacyUrl = options.privacyUrl ?? defaultPrivacyUrl;
+  const revision = options.revision ?? 0;
+  const urlPassthrough = options.urlPassthrough ?? true;
+  const adsDataRedaction = options.adsDataRedaction ?? true;
+  const waitForUpdate = options.waitForUpdate ?? 500;
+  const analyticsServices = [];
+  if (options.gtmId) {
+    analyticsServices.push("Google Tag Manager");
+  } else if (options.ga4Id) {
+    analyticsServices.push("Google Analytics");
+  }
+  if (options.clarityId) {
+    analyticsServices.push("Microsoft Clarity");
+  }
+  const marketingServices = [];
+  if (options.gtmId) {
+    marketingServices.push("Google Tag Manager");
+  }
+  if (options.metaPixelId) {
+    marketingServices.push("Meta Pixel");
+  }
+  const hasAnalytics = analyticsServices.length > 0;
+  const hasMarketing = marketingServices.length > 0;
+  const resolvedOptions = {
+    gtmId: options.gtmId,
+    ga4Id: options.gtmId ? void 0 : options.ga4Id,
+    metaPixelId: options.metaPixelId,
+    clarityId: options.clarityId,
+    mode,
+    lang,
+    privacyUrl,
+    texts: options.texts,
+    gui: options.gui || {},
+    revision,
+    urlPassthrough,
+    adsDataRedaction,
+    waitForUpdate,
+    enabled: isEnabled,
+    hasAnalytics,
+    hasMarketing,
+    analyticsServices,
+    marketingServices
+  };
+  const translations = resolveTranslations(
+    {
+      privacyUrl,
+      hasAnalytics,
+      hasMarketing,
+      analyticsServices,
+      marketingServices
+    },
+    lang,
+    options.texts
+  );
+  const banner = options.banner ?? "box-left";
+  const overlay = options.overlay ?? banner === "modal";
+  const preset = BANNER_PRESETS[banner];
+  const gui = {
+    consentModal: { ...preset.consentModal, ...options.gui?.consentModal },
+    preferencesModal: { ...preset.preferencesModal, ...options.gui?.preferencesModal }
+  };
+  const clientConfig = {
+    hasAnalytics,
+    hasMarketing,
+    analyticsServices,
+    marketingServices,
+    lang,
+    privacyUrl,
+    translations,
+    gui,
+    overlay,
+    revision,
+    mode
+  };
+  return {
+    name: "@krysmalskipl/astro-consent-mode",
+    hooks: {
+      "astro:config:setup"({ injectScript, updateConfig, logger }) {
+        if (!isEnabled) {
+          logger.info(
+            "Astro Consent Mode is disabled (no tracking IDs configured or enabled: false)."
+          );
+          return;
+        }
+        injectScript("head-inline", buildHeadScript(resolvedOptions));
+        updateConfig({
+          vite: {
+            plugins: [virtualConfigPlugin(clientConfig)],
+            optimizeDeps: {
+              exclude: ["@krysmalskipl/astro-consent-mode"],
+              include: ["vanilla-cookieconsent"]
+            }
+          }
+        });
+        injectScript("page", "import '@krysmalskipl/astro-consent-mode/client';");
+      }
+    }
+  };
+}
+var index_default = consent;
+export {
+  consent,
+  index_default as default
+};

package/package.json

@@ -1,6 +1,70 @@
 {
   "name": "@krysmalskipl/astro-consent-mode",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "type": "module",
+  "license": "MIT",
+  "description": "Google Consent Mode v2 for Astro - cookie banner, GTM, GA4, Meta Pixel and Microsoft Clarity with zero config.",
+  "author": {
+    "name": "Krysmalski",
+    "url": "https://krysmalski.pl"
+  },
+  "homepage": "https://krysmalski.pl",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/krysmalskipl/astro-consent-mode.git"
+  },
+  "bugs": {
+    "url": "https://github.com/krysmalskipl/astro-consent-mode/issues"
+  },
+  "keywords": [
+    "withastro",
+    "astro-integration",
+    "astro-component",
+    "astro",
+    "cookie-consent",
+    "consent-mode",
+    "consent-mode-v2",
+    "gdpr",
+    "rodo",
+    "google-tag-manager",
+    "ga4",
+    "meta-pixel",
+    "clarity"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./client": "./dist/client.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "astro": ">=5.0.0"
+  },
+  "dependencies": {
+    "vanilla-cookieconsent": "^3.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "astro": "^5.4.2",
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.20.8"
+  }
+}