# @xms-ai/real-cookies

> Lightweight, GDPR / UK GDPR / LGPD / PIPEDA-compliant cookie consent banner for vanilla JavaScript projects. No dependencies. Optional Supabase integration for cross-device persistence.

[![npm](https://img.shields.io/npm/v/@xms-ai/real-cookies)](https://www.npmjs.com/package/@xms-ai/real-cookies)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

---

## Features

- **Auto-detect jurisdiction** — uses IP geolocation to show GDPR, UK GDPR, LGPD, or PIPEDA UI
- **Granular consent** — per-category toggles (Necessary, Functional, Analytics, Marketing)
- **Supabase sync** — stores consent records in your Supabase DB (free tier compatible)
- **Zero runtime deps** — vanilla JS, no jQuery, no frameworks
- **Google Consent Mode v2** — automatically calls `gtag('consent', 'update', …)`
- **Accessible** — ARIA roles, keyboard navigation, focus-visible outlines
- **Customizable** — brand color, logo, dark/light theme, bottom/top/popup position

---

## Installation

```bash
npm install @xms-ai/real-cookies
```

Or via CDN:

```html
<script src="https://cdn.jsdelivr.net/npm/@xms-ai/real-cookies/dist/cookie-consent.min.js"></script>
```

---

## Quick Start

### ESM (npm)

```js
import CookieConsent from '@xms-ai/real-cookies';

await CookieConsent.init({
  companyName:  'Acme Corp',
  primaryColor: '#1a73e8',
  privacyUrl:   '/privacy',

  // Optional: Supabase persistence
  supabaseUrl:  'https://xxxx.supabase.co',
  supabaseKey:  'your-anon-public-key',
});
```

### Script tag

```html
<script src="dist/cookie-consent.min.js"></script>
<script>
  CookieConsent.init({
    companyName: 'Acme Corp',
    privacyUrl:  '/privacy',
  });
</script>
```

---

## All Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `companyName` | `string` | `'Our Company'` | Name shown in the banner |
| `companyLogo` | `string` | `null` | URL to a logo image |
| `primaryColor` | `string` | `'#1a73e8'` | Brand color for buttons/toggles |
| `theme` | `'light'\|'dark'` | `'light'` | Banner color scheme |
| `position` | `'bottom'\|'top'\|'popup'` | `'bottom'` | Banner placement |
| `privacyUrl` | `string` | `'#'` | Link to your Privacy Policy |
| `cookiePolicyUrl` | `string` | `null` | Link to your Cookie Policy |
| `supabaseUrl` | `string` | `null` | Supabase project URL |
| `supabaseKey` | `string` | `null` | Supabase anon public key |
| `categories` | `object` | see below | Override/add cookie categories |
| `autoShow` | `boolean` | `true` | Auto-show banner when no consent |
| `cookieExpiry` | `number` | `365` | Days until re-consent required |
| `forceMode` | `string` | `null` | Force compliance mode (`'GDPR'`, `'UK_GDPR'`, `'LGPD'`, `'PIPEDA'`, `'BASIC'`) |

---

## JavaScript API

```js
// Check consent for a category
if (CookieConsent.hasConsent('analytics')) {
  // load analytics
}

// Get full consent object
const consent = CookieConsent.getConsent();
// { type: 'custom', categories: { necessary: true, analytics: false, … }, … }

// Open settings panel programmatically
CookieConsent.openSettings();

// Reset consent and re-show banner
CookieConsent.resetConsent();

// Listen for consent events
window.addEventListener('vc:consent', (e) => {
  console.log('User decision:', e.detail.type); // 'accept_all' | 'reject_all' | 'custom'
  console.log('Categories:', e.detail.categories);
});

// Per-category events
window.addEventListener('vc:consent:analytics', (e) => {
  if (e.detail.enabled) initGoogleAnalytics();
});
```

---

## Supabase Setup

1. Open your [Supabase SQL Editor](https://supabase.com/dashboard)
2. Run the contents of [`supabase-schema.sql`](./supabase-schema.sql)
3. Pass your project URL and **anon** key to `init()`

The schema creates a `cookie_consents` table with Row Level Security enabled so anonymous users can only manage their own records.

---

## Compliance Modes

| Mode | Triggered for | Behavior |
|------|--------------|---------|
| `GDPR` | EU / EEA / Switzerland | Opt-in, Reject All required, granular controls |
| `UK_GDPR` | United Kingdom | Same as GDPR |
| `LGPD` | Brazil | Opt-in, Portuguese text, granular controls |
| `PIPEDA` | Canada | Opt-out model, granular controls |
| `BASIC` | Rest of world | Simple notice with Accept All, Reject All, and granular controls |

---

## Custom Categories

```js
CookieConsent.init({
  categories: {
    analytics: {
      name: 'Analytics',
      description: 'Help us understand how visitors use the site.',
      required: false,
      cookies: [
        { name: '_ga', domain: '.google.com', duration: '2 years', type: 'HTTP', description: 'Google Analytics' },
      ],
    },
    // Add entirely new categories:
    preferences: {
      name: 'Preferences',
      description: 'Remember your settings like language and region.',
      required: false,
      cookies: [],
    },
  },
});
```

---

## Building from Source

```bash
npm install
npm run build
# → dist/cookie-consent.js       (IIFE, readable)
# → dist/cookie-consent.min.js   (IIFE, minified)
# → dist/cookie-consent.esm.js   (ES module)
```

Watch mode:

```bash
node build.js --watch
```

---

## License

MIT © [XMS Ai](https://github.com/XMS-Ai)