@consenti/api 0.1.0 → 0.2.0

package/README.md

@@ -8,12 +8,12 @@ Zero-dependency, GDPR-compliant Consent Management Platform backend for Node.js.
 
 ---
 
-## Why this package?
+## Why Consenti?
 
 - **Three SQLite drivers** — `node:sqlite` (Node 22.5+ built-in, zero install), `node-sqlite3-wasm` (WASM, zero compilation, optional peer dep), `better-sqlite3` (native, optional peer dep)
 - **One function to mount** — `createConsenti()` returns a router you drop into any Node.js HTTP framework
 - **Self-contained admin dashboard** — full SPA served at your `basePath`, no separate deploy
-- **Multi-regulation** — GDPR, CCPA, CPRA, GPC, TCF v2.2, DPDPA, LGPD, PDPA, PIPEDA, APPI, KVKK, POPIA, UK-GDPR
+- **Multi-regulation** — 76 regulations across EU/EEA, UK, US (22 state laws), India, Brazil, China, Canada, 18 APAC countries, 9 Middle East countries, 14 African countries, and more — with automatic geo-routing via 8 compliance groups
 - **Pluggable storage** — SQLite (zero-config, default) · PostgreSQL · MySQL · MongoDB
 
 ---
@@ -22,7 +22,45 @@ Zero-dependency, GDPR-compliant Consent Management Platform backend for Node.js.
 
 - **Node.js ≥ 20.0.0** — Node 22 or 24 LTS recommended for production
 
-## Which SQLite driver should I use?
+
+## Installation
+
+```bash
+npm install @consenti/api
+```
+
+### Database / Storage
+Consenti by default comes with JSON file based storage, to get started without any installation.
+We have inbuilt SQLite, PostgreSQL, MySQL and MongoDB as storage adaptors, all are optional peer dependencies,  only install any one of them that you need. Thats not all, you can create an adaptor for any other database you want to use by using [adapter.interface.ts](apps/api/src/storage/adapter.interface.ts)
+
+> **Note:** Default JSON file based storage is only for development and small scale deployments, for production it is recommended to use other database options.
+
+```bash
+# Databases (choose any one )
+
+# 1. node:sqlite - Node native SQLite, 
+     # needs no install on Node 22.5+
+
+# OR 2. WASM SQLite — Node 20+, zero compilation (optional, install only if storage.driver: "node-sqlite3-wasm")
+npm install node-sqlite3-wasm   
+
+# OR 3. native SQLite — Node 20+, faster but needs a C++ toolchain (optional, install only if storage.driver: "better-sqlite3")
+npm install better-sqlite3      
+
+# OR 4. PostgreSQL (optional, install only if storage.driver: "postgresql")
+npm install pg        
+
+# OR 5. MySQL (optional, install only if storage.driver: "mysql")
+npm install mysql2    
+
+# OR 6. MongoDB (optional, install only if storage.driver: "mongodb")
+npm install mongodb   
+
+# OR 7. Create your own custom database Adaptor using "apps/api/src/storage/adapter.interface.ts"
+
+```
+
+### Which SQLite driver should I use?
 
 | Driver | Config | Node requirement | Extra install? |
 |---|---|---|---|
@@ -34,29 +72,178 @@ Zero-dependency, GDPR-compliant Consent Management Platform backend for Node.js.
 `node:sqlite` is the only driver that requires no extra install — it ships with Node 22.5+.
 On Node 20/21, choose between `node-sqlite3-wasm` (pure WASM, no compilation) or `better-sqlite3` (native binary, faster but may fail on Alpine/musl/ARM).
 
----
 
-## Installation
+### Geo resolvers - compliance routing
 
-```bash
-npm install @consenti/api
-```
+Consenti ships with four geo resolver options. The default requires zero installation; the others are opt-in.
+
+**Bonus:** You can also supply a custom resolver function via `compliance.geoDataProvider` — it receives `{ ip, timezone, language }` and must return `{ country: string | null, region: string | null, locale: string | null }`.
+
+> **Note:** The default (`'default'`) and `'hosted-geoip-lite'` resolvers are suitable for development and lower-traffic deployments. For high-accuracy production use, choose `'geoip'` or `'maxmind'`.
+
+### Which geo resolver should I use?
 
-All SQLite drivers and other database adapters are optional peer dependencies — only install what you need:
+| Resolver | Config | Extra install? | Notes |
+|---|---|---|---|
+| `default` | `geoDataProvider: 'default'` | **No** | Timezone + Accept-Language heuristic; zero deps; less accurate |
+| `hosted-geoip-lite` | `geoDataProvider: 'hosted-geoip-lite'` | **No** | Calls `ipinfo.io` via `node:https`; requires outbound internet |
+| `geoip` | `geoDataProvider: 'geoip'` | Yes — `npm install geoip-lite` | Local MaxMind GeoLite2 DB via `geoip-lite`; fast, no outbound traffic |
+| `maxmind` | `geoDataProvider: 'maxmind'` | Yes — `npm install maxmind` | Official MaxMind SDK; most accurate; requires `.mmdb` file |
+| `CountryResolverFn` | `geoDataProvider: myFn` | Depends on your impl | Bring your own resolver — see custom example below |
 
 ```bash
-# SQLite (choose one — node:sqlite needs no install on Node 22.5+)
-npm install node-sqlite3-wasm   # WASM SQLite — Node 20+, zero compilation
-npm install better-sqlite3      # native SQLite — Node 20+, faster but needs a C++ toolchain
-
-# Other databases
-npm install pg        # PostgreSQL
-npm install mysql2    # MySQL
-npm install mongodb   # MongoDB
-```
+# Geo resolvers (choose any one ) 
+
+# 1. Default - language+timezone based
+     # No install needed
+
+# OR 2. Hosted Geo-IP (optional — only needed when geoDataProvider: 'hosted-geoip-lite')
+     # No install needed — calls ipinfo.io using Node's built-in node:https
+     # Requires outbound internet access from your server
 
+# OR 3. Geo-IP lite (optional — only needed when geoDataProvider: 'geoip')
+npm install geoip-lite
+
+# OR 4. Maxmind (optional — only needed when geoDataProvider: 'maxmind')
+npm install maxmind
+
+# OR 5. Custom (optional — only needed when geoDataProvider: CountryResolverFn)
+        # Do what it requires, just return `{ country, region, locale }` in supported format
+
+```
 ---
 
+
+## Full Configuration
+Selected values are default
+
+```ts
+import { createConsenti } from '@consenti/api'
+
+const consenti = createConsenti({
+  // ── Storage ─────────────────────────────────────────────────────────────────
+  storage: {
+    driver: 'json',              // 'json' | 'node:sqlite' | 'node-sqlite3-wasm' | 'better-sqlite3' | 'sqlite' | 'postgresql' | 'mysql' | 'mongodb'
+    path: './consenti-data',     // base directory — Consenti creates db/, profiles/, logs/ subdirectories automatically
+    
+    // Optional
+    uri: 'mongodb://localhost:27017/consenti', // db connection string/uri, only for (driver: 'postgresql' | 'mysql' | 'mongodb')
+    database: 'consenti',        // database name when not in above uri
+  },
+
+  // ── Auth ─────────────────────────────────────────────────────────────────────
+  auth: {
+    mode: 'local',               // 'local' | 'jwt' | 'oidc' | 'saml' | 'custom'
+    adminEmail: 'user@consenti.dev',
+    adminPassword: process.env.CONSENTI_ADMIN_PASSWORD ?? "Consenti@123",
+    jwtSecret: process.env.CONSENTI_ADMIN_JWT_SECRET,  // auto-generated if omitted (sessions expire on restart)
+
+    // OIDC (Auth0, Keycloak, Google, etc.)
+    // mode: 'oidc',
+    // oidc: {
+    //   issuer: 'https://your-idp.example.com',
+    //   clientId: 'your-client-id',
+    //   clientSecret: process.env.OIDC_SECRET,
+    //   redirectUri: 'https://app.example.com/consenti/admin/auth/oidc/callback',
+    //   claimsMapping: { email: 'email', roles: 'consenti_roles' },
+    // },
+
+    // SAML
+    // mode: 'saml',
+    // saml: {
+    //   issuer: 'https://idp.example.com',
+    //   entryPoint: 'https://idp.example.com/sso/saml',
+    //   cert: process.env.SAML_CERT!,           // IdP signing cert (PEM, no headers)
+    //   callbackUrl: 'https://app.example.com/consenti/admin/auth/saml/callback',
+    // },
+
+    // Custom — bring your own authentication function
+    // mode: 'custom',
+    // validateUser: async (req: Request) => AdminUser | null,
+  },
+
+  // ── Routing ──────────────────────────────────────────────────────────────────
+  basePath: '/consenti',         // URL prefix for all routes (default: '/consenti')
+  dashboard: true,               // serve built-in admin SPA at basePath (default: true)
+
+  // ── Branding ─────────────────────────────────────────────────────────────────
+  branding: {
+    appName: 'Consenti',              // shown in dashboard header, login page, browser tab
+    appLogoPath: './logo-dark.svg',   // local file path or https:// URL; auto-served as static asset
+    hidePoweredBy: false,             // true = hide "Powered by Consenti" badge
+  },
+
+  // ── Rate limiting ─────────────────────────────────────────────────────────────
+  rateLimit: {
+    enabled: true,
+    windowMs: 60_000,            // rolling window in ms (default: 60 000)
+    maxRequests: 60,             // max requests per IP per window (default: 60)
+  },
+
+  // ── Compliance ───────────────────────────────────────────────────────────────
+  compliance: {
+    // Geo-based auto routing (recommended)
+    type: 'auto',                // 'auto' = geo-resolve per visitor | ComplianceGroupId = one fixed group globally
+    geoDataProvider: 'default',  // 'default' (timezone+language heuristic, zero-dep) | 'hosted-geoip-lite' (no install, calls ipinfo.io) | 'geoip' (optional peer dep) | 'maxmind' (optional peer dep) | CountryResolverFn
+    autoComplianceMap: 'default',// 'default' = embedded 240-country map | operator object | 'auto' = fetch from complianceMapUrl
+    // complianceMapUrl: 'https://consenti.dev/data/v1/compliance-map.json', // used when autoComplianceMap: 'auto'
+  },
+
+  // ── S3 profile file sync (optional) ─────────────────────────────────────────
+  // When enabled, every locale JSON written to disk is also PUT to S3.
+  // /resolve-profile returns an s3:// URL so the widget can fetch directly from CDN.
+  s3Api: {
+    enabled: false,
+    region: 'us-east-1',
+    bucketName: 'consenti-profiles',
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+    // sessionToken: process.env.AWS_SESSION_TOKEN, // for temporary credentials
+  },
+
+  // ── Cache invalidation hook (optional) ──────────────────────────────────────
+  // Called after every profile creation, edit, activation, deactivation, or delete.
+  // isPurge=false = warm the cache at these paths; isPurge=true = purge.
+  handleCache: (paths: string[], version: number, isPurge: boolean) => {
+    // paths: array of file paths that were written or removed
+    // version: current profile version
+    // isPurge: true when files were removed (deactivate/delete); false when written (activate/create)
+    // Example: purge CDN edge nodes, update nginx cache keys, etc.
+  },
+
+  // ── IAB TCF v2.2 ─────────────────────────────────────────────────────────────
+  tcf: {
+    enabled: false,
+    cmpId: 123,                  // your IAB-registered CMP ID (required when enabled)
+    cmpVersion: 1,               // your CMP software version
+  },
+
+  // ── Age gate ─────────────────────────────────────────────────────────────────
+  ageGate: {
+    enabled: false,
+    minimumAge: 13,              // COPPA = 13; GDPR Article 8 = 16
+    requireParentalConsent: false,
+  },
+
+  // ── Data retention ───────────────────────────────────────────────────────────
+  dataRetention: {
+    purgeAfterDays: 365,         // delete consent records older than N days; runs nightly
+  },
+
+  // ── Multi-tenant ─────────────────────────────────────────────────────────────
+  multiTenant: {
+    enabled: false,              // scope all data to tenant from X-Tenant-ID header
+  },
+
+  // ── Proxies & body ───────────────────────────────────────────────────────────
+  trustedProxies: [],            // IP / CIDR of reverse proxies (reads X-Forwarded-For)
+  maxBodySize: 1_048_576,        // request body size limit in bytes (default: 1 MB)
+
+  // ── Plugins ──────────────────────────────────────────────────────────────────
+  plugins: [],                   // ConsentiServerPlugin instances
+})
+```
+
 ## Quick Start
 
 ### Express
@@ -68,7 +255,7 @@ import { createConsenti } from '@consenti/api'
 const app = express()
 
 const consenti = createConsenti({
-  storage: { driver: 'sqlite', path: './consenti.db' },
+  storage: { driver: 'node:sqlite', path: './consenti-data' },
   auth: {
     mode: 'local',
     adminEmail: 'admin@example.com',
@@ -89,10 +276,11 @@ app.listen(3000, () => {
 ### Standalone (no framework)
 
 ```ts
+import { createServer } from 'node:http'
 import { createConsenti } from '@consenti/api'
 
 const consenti = createConsenti({
-  storage: { driver: 'sqlite', path: './consenti.db' },
+  storage: { driver: 'node:sqlite', path: './consenti-data' },
   auth: {
     mode: 'local',
     adminEmail: 'admin@example.com',
@@ -101,9 +289,13 @@ const consenti = createConsenti({
   dashboard: true,
 })
 
-await consenti.start(3001)
-// Admin dashboard → http://localhost:3001/consenti/
-// REST API        → http://localhost:3001/consenti/api/v1/
+await consenti.ready  // wait for DB + bootstrap
+
+const server = createServer(consenti.handler)
+server.listen(3001, () => {
+  console.log('Admin dashboard → http://localhost:3001/consenti/')
+  console.log('REST API        → http://localhost:3001/consenti/api/v1/')
+})
 ```
 
 ---
@@ -122,14 +314,13 @@ app.use(consenti.handler)   // as a terminal handler (no next())
 
 ```ts
 import Fastify from 'fastify'
-const app = Fastify()
+import { createConsenti } from '@consenti/api'
 
+const fastify = Fastify()
 const consenti = createConsenti({ /* ... */ })
 
-app.all('/consenti/*', async (req, reply) => {
-  reply.hijack()
-  consenti.handler(req.raw, reply.raw)
-})
+await fastify.register(consenti.fastifyHandler)
+await fastify.listen({ port: 3000 })
 ```
 
 ### Next.js App Router
@@ -144,7 +335,7 @@ let consenti: Awaited<ReturnType<typeof createConsenti>>
 async function getConsenti() {
   if (!consenti) {
     consenti = createConsenti({
-      storage: { driver: 'sqlite', path: './consenti.db' },
+      storage: { driver: 'sqlite', path: './consenti-data' },
       auth: {
         mode: 'local',
         adminEmail: process.env.CONSENTI_ADMIN_EMAIL!,
@@ -155,12 +346,12 @@ async function getConsenti() {
   return consenti
 }
 
-export async function GET(req: NextRequest) {
+async function consentiHandler(req: NextRequest) {
   const c = await getConsenti()
   return c.handleRequest(req)
 }
 
-export { GET as POST, GET as PUT, GET as DELETE, GET as PATCH }
+export { consentiHandler as POST, consentiHandler as PUT, consentiHandler as DELETE, consentiHandler as PATCH, consentiHandler as GET }
 ```
 
 ### Hono / Fetch-based
@@ -171,133 +362,105 @@ return consenti.honoApp.fetch(request)
 
 ---
 
-## Full Configuration
+## First Boot
 
-```ts
-import { createConsenti } from '@consenti/api'
+On first start with JSON, Consenti:
 
-const consenti = createConsenti({
-  // ── Required ────────────────────────────────────────────────────────────────
-  storage: {
-    driver: 'node-sqlite3-wasm', // 'node-sqlite3-wasm' | 'node:sqlite' | 'better-sqlite3' | 'pg' | 'mongodb' | 'mysql'
-    path: './consenti.db',      // SQLite only — file path
-
-    // PostgreSQL
-    // driver: 'pg',
-    // url: 'postgresql://user:pass@localhost:5432/consenti',
-    // pool: { max: 10, idleTimeoutMillis: 30000 },
-
-    // MongoDB
-    // driver: 'mongodb',
-    // url: 'mongodb://localhost:27017',
-    // dbName: 'consenti',
-
-    // MySQL
-    // driver: 'mysql',
-    // url: 'mysql://user:pass@localhost:3306/consenti',
-  },
-  auth: {
-    mode: 'local',              // 'local' | 'oauth' | 'saml' | 'none'
-    adminEmail: 'admin@example.com',
-    adminPassword: process.env.CONSENTI_ADMIN_PASSWORD!,
-    jwtSecret: process.env.CONSENTI_ADMIN_JWT_SECRET,   // auto-generated if omitted (changes on restart)
-    sessionTtl: 86400,          // JWT TTL in seconds (default: 24 h)
+1. Creates the storage directory at the configured path (see [Storage Directory Structure](#storage-directory-structure))
+2. Runs all migrations (creates `visitors`, `consent_records`, `consent_history`, `profiles`, `admin_users`, `audit_logs` tables, and DB indexes)
+3. Creates the admin user from `auth.adminEmail` + `auth.adminPassword`
+4. Seeds the default profile (`profileId: '0'`)
 
-    // OAuth / OIDC (e.g. Auth0, Keycloak)
-    // mode: 'oauth',
-    // oidc: {
-    //   issuer: 'https://your-idp.example.com',
-    //   clientId: 'your-client-id',
-    //   clientSecret: process.env.OIDC_SECRET,
-    //   redirectUri: 'https://app.example.com/consenti/admin/auth/callback',
-    // },
+Subsequent starts run only pending migrations.
 
-    // SAML
-    // mode: 'saml',
-    // saml: {
-    //   issuer: 'consenti',
-    //   entryPoint: 'https://idp.example.com/sso/saml',
-    //   cert: process.env.SAML_CERT,
-    //   callbackUrl: 'https://app.example.com/consenti/admin/auth/saml/callback',
-    // },
+---
 
-    // Custom — bring your own validator
-    // mode: 'custom',
-    // validateUser: async (req) => ({ id, email, roles, permissions } | null),
-  },
+## Storage Directory Structure
 
-  // ── Optional ────────────────────────────────────────────────────────────────
-  basePath: '/consenti',        // URL prefix (default: '/consenti')
-  dashboard: true,              // serve admin SPA (default: false)
-  trustProxy: false,            // true when behind nginx / Cloudflare
+`storage.path` is a **directory path**. Consenti creates the following layout automatically:
 
-  rateLimit: {
-    enabled: true,
-    windowMs: 60_000,           // rolling window (default: 60 s)
-    maxRequests: 60,            // max requests per IP per window (default: 60)
-  },
+```
+${storage.path}/
+  db/
+    consenti-data.json     # JSON adapter
+    consenti.db            # SQLite adapters
+  profiles/
+    ${tenantId}/
+      ${profileId}/
+        1/                 # version 1 (immutable once written)
+          en.json
+          fr-FR.json
+          default.json     # copy of defaultLocale content (fallback)
+        2/                 # version 2 written on next save
+          …
+      ${complianceGroup}/  # hot-serve path (active profile only)
+        en.json
+        fr-FR.json
+        default.json
+  logs/                    # reserved for future structured logging
+```
 
-  cors: {
-    origins: ['https://yoursite.com'],  // never use '*' in production
-    credentials: true,
-  },
+**Key rules:**
+- Every profile save writes to a new immutable version directory under `${profileId}/${version}/`
+- `${complianceGroup}/` only exists when a profile is **active** for that group
+- On **activate**: locale files are copied from `${profileId}/${currentVersion}/` → `${complianceGroup}/`
+- On **deactivate** / **delete**: `${complianceGroup}/` files are removed
+- `default.json` = full resolved profile for `defaultLocale`; used as locale fallback (303 redirect)
 
-  compliance: {
-    gdpr: true,                 // opt-in enforcement
-    ccpa: false,                // opt-out model
-    gpc: true,                  // store gpc_detected on records
-    tcf: {
-      enabled: false,           // IAB TCF v2.2
-      cmpId: 123,               // your registered CMP ID
-    },
-  },
+**Backward compat:** If `storage.path` has a file extension (`.json`, `.db`), the parent directory is used and a deprecation warning is logged.
 
-  ageGate: {
-    enabled: false,
-    minimumAge: 13,
-    requireParentalConsent: false,
-  },
+---
 
-  dataRetention: {
-    purgeAfterDays: 365,        // auto-purge old records (0 = disabled)
-  },
+## Public REST API
 
-  multiTenant: {
-    enabled: false,             // isolate data per tenant
-  },
+Base path: `/consenti/api/v1` (change with `basePath` in config). No authentication required.
 
-  plugins: [],                  // ConsentiServerPlugin instances
-})
+| Method     | Path                                        | Description                                                            |
+|------------|---------------------------------------------|------------------------------------------------------------------------|
+| `GET`      | `/profiles/:tenantId/:complianceGroup/:locale` | **Hot-serve** — serve locale JSON directly from disk (zero DB)      |
+| `GET`      | `/profiles/:tenantId/:profileId/:version/:locale` | Serve a specific version locale JSON (dashboard preview)         |
+| `GET`      | `/resolve-profile`                          | Geo-resolve compliance group, return file path + locale                |
+| `GET`      | `/profiles/:id`                             | get profile by ID (resolved, DB-backed, default tenant, default locale)|
+| `GET`      | `/profiles/:id/:locale`                     | get profile by ID & locale (resolved, DB-backed, default tenant)       |
+| `GET`      | `/profiles/auto/:locale`                    | Legacy: geo-resolve then return matching active profile                |
+| `POST`     | `/consent`                                  | Submit a consent record                                                |
+| `GET`      | `/consent/:visitorId`                       | Get current consent for a visitor                                      |
+| `PUT`      | `/consent/:visitorId`                       | Update consent for a visitor                                           |
+| `DELETE`   | `/consent/:visitorId`                       | GDPR right-to-erasure — delete all visitor data                        |
+| `GET`      | `/consent/:visitorId/verify`                | Check if consent is still valid                                        |
+
+### Static file serving (hot path)
+
+```http
+GET /consenti/api/v1/profiles/default/opt-in/en
 ```
 
----
+Serves `${storage.path}/profiles/default/opt-in/en.json` directly from disk. No DB involved.
 
-## First Boot
+If the locale file doesn't exist, returns `303 See Other → .../opt-in/default` (which serves `default.json` = `defaultLocale` content).
 
-On first start with SQLite, Consenti:
+Cache headers: `public, max-age=3600, stale-while-revalidate=60` — suitable for CDN caching.
 
-1. Creates the database file at the configured path
-2. Runs all migrations (creates `visitors`, `consent_records`, `consent_history`, `profiles`, `admin_users`, `audit_logs` tables)
-3. Creates the admin user from `auth.adminEmail` + `auth.adminPassword`
-4. Seeds the default profile (`profileId: '0'`)
+### Resolve profile (for `compliance.type: 'auto'`)
 
-Subsequent starts run only pending migrations.
+```http
+GET /consenti/api/v1/resolve-profile?tz=Europe/Paris&lang=fr-FR&locale=fr-FR
+```
 
----
+For widgets using `compliance.type: 'auto'` — call this once on page load to discover which compliance group and locale the visitor should receive:
 
-## Public REST API
-
-Base path: `/consenti/api/v1` (change with `basePath` in config). No authentication required.
+```json
+{
+  "path": "/consenti/api/v1/profiles/default/opt-in/fr-FR",
+  "resolvedLocale": "fr-FR",
+  "resolvedComplianceGroup": "opt-in",
+  "profileId": "gdpr-profile-uuid",
+  "version": 3,
+  "warning": "locale_not_found"   // only present when locale was unavailable; path points to default
+}
+```
 
-| Method     | Path                          | Description                                     |
-|------------|-------------------------------|-------------------------------------------------|
-| `GET`      | `/profiles/:id`               | Get profile resolved in its default locale      |
-| `GET`      | `/profiles/:id/:locale`       | Get profile resolved for a specific locale      |
-| `POST`     | `/consent`                    | Submit a consent record                         |
-| `GET`      | `/consent/:visitorId`         | Get current consent for a visitor               |
-| `PUT`      | `/consent/:visitorId`         | Update consent for a visitor                    |
-| `DELETE`   | `/consent/:visitorId`         | GDPR right-to-erasure — delete all visitor data |
-| `GET`      | `/consent/:visitorId/verify`  | Check if consent is still valid                 |
+Query params: `tz` (IANA timezone), `lang` (Accept-Language value), `locale` (preferred BCP 47 locale).
 
 ### Submit consent
 
@@ -380,13 +543,114 @@ Content-Type: application/json
 
 ### Profiles
 
-| Method     | Path              | Description                              |
-|------------|-------------------|------------------------------------------|
-| `GET`      | `/profiles`       | List all profiles                        |
-| `POST`     | `/profiles`       | Create a profile                         |
-| `GET`      | `/profiles/:id`   | Get a profile                            |
-| `PUT`      | `/profiles/:id`   | Update a profile (auto-bumps version)    |
-| `DELETE`   | `/profiles/:id`   | Delete a profile                         |
+| Method     | Path                             | Description                                                             |
+|------------|----------------------------------|-------------------------------------------------------------------------|
+| `GET`      | `/profiles`                      | List all profiles                                                       |
+| `GET`      | `/profiles?summary=1`            | List profiles as `ProfileSummary[]` (no blob, with template names)     |
+| `POST`     | `/profiles`                      | Create a profile — 422 on compliance errors; `{ conflict, requiresChoice: true }` when an active profile exists on the same `complianceGroup` |
+| `GET`      | `/profiles/:id`                  | Get a profile                                                           |
+| `PUT`      | `/profiles/:id`                  | Update a profile (auto-bumps version) — same compliance validation + conflict detection |
+| `DELETE`   | `/profiles/:id`                  | Delete a profile                                                        |
+| `POST`     | `/profiles/:id/activate`         | Activate a profile — writes locale JSON files to `${complianceGroup}/` |
+| `POST`     | `/profiles/:id/deactivate`       | Deactivate a profile — removes `${complianceGroup}/` locale files       |
+| `GET`      | `/profiles/:id/versions`         | List version history entries (`{ version, createdAt, locales[] }[]`)   |
+| `GET`      | `/profiles/:id/versions/:n`      | Read a specific version locale file (query: `?locale=en`)               |
+| `POST`     | `/profiles/validate`             | Validate cookie template against a compliance group (no save)           |
+| `GET`      | `/compliance-coverage`           | Active profile (or null) per compliance group — powers coverage panel   |
+
+#### Profile Save Conflict Detection
+
+Only one profile per `complianceGroup` can be active at a time. If you attempt to create or update a profile with `isActive: true` and another active profile already exists for the same `complianceGroup`, the backend returns **200** (not an error) with:
+
+```json
+{
+  "conflict": { "id": "existing-profile-uuid", "name": "GDPR Profile v1" },
+  "requiresChoice": true
+}
+```
+
+Re-submit the original request with a `choice` field to resolve:
+
+```json
+{ "choice": "deactivate" }   // deactivate the conflicting profile, then save this one as active
+{ "choice": "inactive" }     // save this profile as inactive (no conflict)
+```
+
+The dashboard profile editor shows a three-button popup when `requiresChoice: true` — "Deactivate existing and activate this one", "Save as inactive", and "Cancel".
+
+#### ProfileSummary shape
+
+```ts
+{
+  id: string
+  name: string
+  defaultLocale: string
+  complianceGroup: ComplianceGroupId | null
+  version: number
+  isActive: boolean
+  cookieTemplateName: string | null
+  uiTemplateName: string | null
+  createdAt: string
+  updatedAt: string
+}
+```
+
+### Cookie Templates
+
+| Method     | Path                                        | Description                                              |
+|------------|---------------------------------------------|----------------------------------------------------------|
+| `GET`      | `/cookie-templates`                         | List cookie templates                                    |
+| `GET`      | `/cookie-templates/:id`                     | Get a cookie template                                    |
+| `POST`     | `/cookie-templates`                         | Create a cookie template                                 |
+| `PUT`      | `/cookie-templates/:id`                     | Update a cookie template — 422 if removing cookies breaks compliance for a dependent profile |
+| `DELETE`   | `/cookie-templates/:id`                     | Delete a cookie template — 422 if any active profiles use it |
+| `POST`     | `/cookie-templates/:id/copy`                | Duplicate a cookie template                              |
+| `GET`      | `/cookie-templates/:id/profile-usage`       | List profiles using this template (`ProfileSummary[]`)   |
+
+#### Cookie Template Safety Guards
+
+**Deletion guard:** `DELETE /cookie-templates/:id` returns `422` with `{ activeProfiles: ProfileSummary[] }` when one or more active profiles reference the template. Deactivate those profiles first, then delete.
+
+**Cookie removal guard:** When updating a template (`PUT`), if cookies are removed, the backend checks all profiles using the template and runs compliance validation with the new cookie set. If any profile's `complianceGroup` requires a cookie that was removed, the response is `422` with:
+
+```json
+{
+  "blockingProfiles": [{ "id": "...", "name": "...", "complianceGroup": "opt-in" }],
+  "removedCookieIds": ["analytics", "marketing"]
+}
+```
+
+Profiles listed in `blockingProfiles` must be updated (switch template or change complianceGroup) before the cookie removal can proceed.
+
+### UI Templates
+
+| Method     | Path                                        | Description                                              |
+|------------|---------------------------------------------|----------------------------------------------------------|
+| `GET`      | `/ui-templates`                             | List UI templates                                        |
+| `GET`      | `/ui-templates/:id`                         | Get a UI template                                        |
+| `POST`     | `/ui-templates`                             | Create a UI template                                     |
+| `PUT`      | `/ui-templates/:id`                         | Update a UI template                                     |
+| `DELETE`   | `/ui-templates/:id`                         | Delete a UI template                                     |
+| `POST`     | `/ui-templates/:id/copy`                    | Duplicate a UI template                                  |
+| `GET`      | `/ui-templates/:id/profile-usage`           | List profiles using this template (`ProfileSummary[]`)   |
+
+### Analytics
+
+| Method | Path                    | Description                                        |
+|--------|-------------------------|----------------------------------------------------|
+| `GET`  | `/analytics/opt-in`     | Opt-in rate stats aggregated by locale and date    |
+
+Query params: `tenantId`, `profileId`, `complianceGroup`, `from` (ISO date), `to` (ISO date), `locale`.
+
+```json
+{
+  "total": 12400,
+  "granted": 6800, "denied": 4100, "managed": 1500,
+  "grantedPct": 54.8, "deniedPct": 33.1, "managedPct": 12.1,
+  "byLocale": { "en": { "total": 8000, "granted": 4400 } },
+  "byDate": [{ "date": "2026-07-01", "total": 400, "granted": 220 }]
+}
+```
 
 ### Consents
 
@@ -408,17 +672,37 @@ IPs are never stored raw — only SHA-256 hashes appear in the `ipHash` field.
 
 ### Users & Roles
 
-| Method     | Path                              | Description                      |
-|------------|-----------------------------------|----------------------------------|
-| `GET`      | `/users`                          | List admin users                 |
-| `POST`     | `/users`                          | Create an admin user             |
-| `PUT`      | `/users/:id`                      | Update an admin user             |
-| `GET`      | `/roles`                          | List roles                       |
-| `POST`     | `/roles`                          | Create a role                    |
-| `GET`      | `/roles/:id/permissions`          | Get permissions for a role       |
-| `POST`     | `/roles/:id/permissions`          | Assign a permission to a role    |
-| `DELETE`   | `/roles/:id/permissions/:permId`  | Revoke a permission from a role  |
-| `GET`      | `/permissions`                    | List all available permissions   |
+| Method     | Path                              | Description                                          |
+|------------|-----------------------------------|------------------------------------------------------|
+| `GET`      | `/users`                          | List admin users                                     |
+| `POST`     | `/users`                          | Create an admin user                                 |
+| `PUT`      | `/users/:id`                      | Update an admin user                                 |
+| `GET`      | `/roles`                          | List roles                                           |
+| `POST`     | `/roles`                          | Create a role                                        |
+| `GET`      | `/roles/:id/permissions`          | Get permissions for a role                           |
+| `POST`     | `/roles/:id/permissions`          | Assign a permission to a role                        |
+| `DELETE`   | `/roles/:id/permissions/:permId`  | Revoke a permission from a role                      |
+| `GET`      | `/permissions`                    | List all available permissions                       |
+
+#### User `allowedTenants`
+
+Admin users can be scoped to specific tenants. When `allowedTenants` is set, the user can only see and manage data for those tenants:
+
+```ts
+// POST /admin/users or PUT /admin/users/:id
+{
+  "name": "APAC Manager",
+  "email": "apac@example.com",
+  "password": "...",
+  "allowedTenants": ["tenant-uuid-1", "tenant-uuid-2"]  // empty = access to all tenants
+}
+```
+
+Users with `role: 'superadmin'` always have access to all tenants regardless of `allowedTenants`.
+
+**Enforcement:** The auth middleware passes `allowedTenants` to every list query. A user whose `allowedTenants` does not include the tenant being queried receives an empty result set (not a 403), so pagination works normally. A user with an empty `allowedTenants` array has no restrictions. Routes for individual resources (`GET /consents/:visitorId`, `GET /consents/:visitorId/history`) return `403 Forbidden` instead of an empty result when the tenant is not in `allowedTenants`.
+
+The **Users** dashboard page includes an **Edit** button on each user row (visible to users with `user:update` permission) that opens a modal for updating `allowedTenants` without changing the user's password or role.
 
 ### API Keys
 
@@ -430,16 +714,17 @@ IPs are never stored raw — only SHA-256 hashes appear in the `ipHash` field.
 
 ### Stats & Reporting
 
-| Method | Path                      | Description                              |
-|--------|---------------------------|------------------------------------------|
-| `GET`  | `/stats/overview`         | Total consents, visitors, GPC count      |
-| `GET`  | `/stats/timeline`         | Daily consent counts (`?days=30`)        |
-| `GET`  | `/stats/categories`       | Per-category grant/deny breakdown        |
-| `GET`  | `/stats/countries`        | Consent count by country                 |
-| `GET`  | `/stats/gpc`              | GPC detection statistics                 |
-| `GET`  | `/export/consents`        | Export consent records (CSV or JSON)     |
-| `GET`  | `/export/consents/xlsx`   | Export as XLSX                           |
-| `GET`  | `/export/audit`           | Export audit log (CSV or JSON)           |
+| Method | Path                              | Description                              |
+|--------|-----------------------------------|------------------------------------------|
+| `GET`  | `/stats/overview`                 | Total consents, visitors, GPC count      |
+| `GET`  | `/stats/timeline`                 | Daily consent counts (`?days=30`)        |
+| `GET`  | `/stats/categories`               | Per-category grant/deny breakdown        |
+| `GET`  | `/stats/countries`                | Consent count by country                 |
+| `GET`  | `/stats/gpc`                      | GPC detection statistics                 |
+| `GET`  | `/export/consents`                | Export consent records (CSV or JSON)     |
+| `GET`  | `/export/consents/xlsx`           | Export as XLSX                           |
+| `GET`  | `/export/audit`                   | Export audit log (CSV or JSON)           |
+| `GET`  | `/export/translations/:profileId` | Export all translatable fields as CSV    |
 
 ### Audit Log
 
@@ -473,46 +758,152 @@ Only active when `tcf.enabled: true`.
 
 Served at `{basePath}/` when `dashboard: true`.
 
-| Section           | Description                                                              |
-|-------------------|--------------------------------------------------------------------------|
-| Dashboard         | Consent overview, timeline chart, country breakdown, GPC stats           |
-| Profiles          | Create / edit / copy / delete consent profiles via 3-step wizard         |
-| Cookie Templates  | Reusable cookie/purpose definitions                                      |
-| UI Templates      | Reusable banner + modal layout settings                                  |
-| Consents          | Browse, filter, export consent records; per-visitor history              |
-| Visitors          | Visitor list with geographic data                                        |
-| Users             | Admin user management                                                    |
-| Roles             | RBAC roles and fine-grained permission assignment                        |
-| Sites             | Multi-tenant site management                                             |
-| TCF Vendors       | IAB Global Vendor List                                                   |
-| Audit Log         | Immutable log of all admin actions                                       |
-| Settings          | API keys, branding                                                       |
+| Section             | Description                                                              |
+|---------------------|--------------------------------------------------------------------------|
+| Dashboard           | Consent overview, timeline chart, country breakdown, GPC stats           |
+| Profiles            | Create / edit / copy / delete / activate / deactivate consent profiles   |
+| Profile History     | Version history viewer — compare locale JSON per version                 |
+| Cookie Templates    | Reusable cookie/purpose definitions (blank by default + Load Defaults)   |
+| UI Templates        | Reusable banner + modal layout settings                                  |
+| Consents            | Browse, filter, export consent records; per-visitor history              |
+| Visitors            | Visitor list with geographic data                                        |
+| Users               | Admin user management with allowed-tenant scoping                        |
+| Roles               | RBAC roles and fine-grained permission assignment                        |
+| Sites               | Multi-tenant site management **(superadmin only)**                       |
+| TCF Vendors         | IAB Global Vendor List                                                   |
+| Audit Log           | Immutable log of all admin actions                                       |
+| Settings / API      | API keys, branding, OpenAPI docs **(superadmin only)**                   |
+
+### Dashboard RBAC
+
+- **Sites** and **API** sections are visible only to users with `role: 'superadmin'`
+- **TCF Vendors** is visible to all authenticated users
 
 ### Profile Creation Wizard
 
-**Step 1 — Cookie Template:** Define cookie IDs and their properties:
+**Step 1 — Profile metadata:**
+
+| Field               | Type                                                 | Description                                                                 |
+|---------------------|------------------------------------------------------|-----------------------------------------------------------------------------|
+| `name`              | `string`                                             | Human-readable profile name                                                 |
+| `defaultLocale`     | `string` (BCP 47)                                    | Locale served when visitor locale is unavailable; written as `default.json` |
+| `complianceGroup`   | `ComplianceGroupId`                                  | Regulation group for geo-routing (e.g. `opt-in`, `opt-out-strict`)          |
+| `gpcMode`           | `'ignore' \| 'honor' \| 'strict'`                   | GPC signal handling. Overrides group default.                               |
+| `darkMode`          | `boolean`                                            | Enable dark mode in the consent banner                                      |
+| `hidePoweredBy`     | `boolean`                                            | Hide "Powered by Consenti" branding link                                    |
+| `allowReceipt`      | `boolean`                                            | Allow visitors to download a PDF consent receipt                            |
+| `allowedOrigins`    | `string[]`                                           | Allowlisted domains for CORS on this profile's consent endpoints            |
+| `complianceConfig`  | `Record<string, string>`                             | Per-compliance extra config (e.g. DPDPA data fiduciary name). Only shown when the selected `complianceGroup` requires it; otherwise omitted. |
+
+**Step 2 — Cookie Template:** Define cookie IDs and their properties. Clicking **Next** at the bottom of Step 2 calls `POST /admin/profiles/validate` with the selected template's cookies and the chosen `complianceGroup`:
 
-| Field               | Type                              | Description                                       |
-|---------------------|-----------------------------------|---------------------------------------------------|
-| `id`                | `string`                          | Unique identifier referenced in button arrays     |
-| `type`              | `'consent' \| 'legitimate_interest'` | Legal basis                                    |
-| `mandatory`         | `boolean`                         | Always granted; toggle disabled in modal          |
-| `listenGpc`         | `boolean`                         | Auto-denied when GPC signal is active             |
-| `expiry`            | `number`                          | Days until re-consent is required (0 = session)  |
+- **Compliance errors** (red panel): block advancing to Step 3 until resolved (e.g. template has no cookie with `listenGpc: true` but the group requires GPC support).
+- **Compliance warnings** (amber panel): show an acknowledgment checkbox; the user must check it before advancing. Warnings do not block save — they surface potential issues.
 
-**Step 2 — UI Template:** Configure banner and modal layout:
+| Field               | Type                                            | Description                                                               |
+|---------------------|-------------------------------------------------|---------------------------------------------------------------------------|
+| `id`                | `string`                                        | Unique identifier referenced in button arrays                             |
+| `legalBasis`        | `'mandatory' \| 'consent' \| 'legitimate_interest'` | Legal basis (replaces deprecated `mandatory`+`type` fields)           |
+| `listenGpc`         | `boolean`                                       | Auto-denied when GPC signal is active                                     |
+| `expiry`            | `number`                                        | Days until re-consent is required (0 = session)                           |
+| `tcfSpecialFeatures`| `number[]`                                      | IAB TCF special feature IDs (SF1, SF2) associated with this cookie        |
+
+**Step 3 — UI Template:** Configure banner and modal layout. New UI templates start **blank** (no prefilled buttons or categories). Click **Load Defaults** in the amber callout to populate a sensible starter structure.
 
 - **Main Banner / GPC Banner:** `position`, `overlayOpacity`, `showClose`, `headingTag`, `buttons`
 - **Preference Modal:** `position`, `overlayOpacity`, `showClose`, `persistent`, `buttons`, `categories`
 - Button `type`: `primary | secondary | text | reject | submit | manage | close`
 - Button `cookies`: `*` (grant all) · `!` (deny all) · comma-separated IDs
 
-**Step 3 — Content:** Enter localised copy with live preview:
+**Step 4 — Content:** Enter localised copy with live preview:
 
 - Main Banner: heading, body HTML
 - GPC Banner: heading, body HTML
 - Preference Modal: heading, subheading, intro HTML, per-category heading + description
 
+**Adding locales:** Click **+ Add locale** to open a searchable `CountrySelecter` dropdown showing all BCP 47 locale options. Select a locale to add its tab instantly.
+
+**Default-locale placeholders:** When editing a non-default locale tab, all heading, subheading, and category-heading inputs show the default locale's value as placeholder text — so translators see the source copy without switching tabs.
+
+**Import / Export:**
+
+| Button | Action |
+|--------|--------|
+| **JSON** | Exports *all* locale tabs as a single `locales.json` file (`{ "en": {...}, "fr-FR": {...} }`) |
+| **CSV** | Exports the *current* locale tab as a `locale-{locale}.csv` file |
+| **Import** | Accepts either format — multi-locale JSON auto-creates missing locale tabs; skipped locales (invalid BCP 47 key) are listed in an amber callout after import |
+
+**Readability callouts:** Inline advisory warnings (yellow) appear beneath `heading` and body HTML fields when:
+- A heading exceeds 80 characters
+- Average sentence length in the body exceeds 25 words
+- Total word count in the body exceeds 150 words
+
+These are informational only — the profile can still be saved.
+
+### Profile Activation
+
+Profiles are **inactive** after creation. To serve them via geo-routing:
+
+1. Click **Activate** in the profile list or use `POST /admin/profiles/:id/activate`
+2. Consenti writes locale JSON files to `${storage.path}/profiles/${tenantId}/${complianceGroup}/`
+3. The static file route starts serving these files immediately (zero DB on the hot path)
+
+Only one profile per `complianceGroup` can be active at a time. Activating a new profile automatically deactivates the existing one.
+
+### Profile Version History
+
+Every profile save creates an immutable snapshot at `${profileId}/${version}/`. The dashboard version history page (`#/banners/profiles/:id/history`) shows:
+- Left panel: list of all versions with dates
+- Right panel: prettified JSON for the selected version; locale switcher dropdown
+
+Via API:
+```http
+GET /consenti/admin/profiles/:id/versions
+GET /consenti/admin/profiles/:id/versions/3?locale=fr-FR
+```
+
+### Template Save Safety
+
+When saving a **Cookie Template** or **UI Template** that is used by one or more profiles, a confirmation dialog appears listing the affected profiles. You must confirm before changes are applied. Uses `GET /admin/cookie-templates/:id/profile-usage` or `GET /admin/ui-templates/:id/profile-usage` internally.
+
+When **deleting** a Cookie Template used by active profiles, the delete is blocked with a 422 error listing those profiles. Deactivate the affected profiles before deleting the template.
+
+When **removing cookies** from a Cookie Template, the backend checks whether the reduced cookie set satisfies the `complianceGroup` rules for every profile using the template. If any profile's compliance would break, the save is blocked with a 422 listing the `blockingProfiles` and `removedCookieIds` — see [Cookie Template Safety Guards](#cookie-template-safety-guards).
+
+---
+
+## EventBus
+
+`createConsenti()` returns an `eventBus` — a standard Node.js `EventEmitter` — that fires events at every data lifecycle step.
+
+| Event | Payload | Description |
+|---|---|---|
+| `ready` | none | Storage connected and admin user bootstrapped |
+| `consent.created` | `ConsentDbRecord` | New consent record saved |
+| `consent.updated` | `{ previous, current: ConsentDbRecord }` | Consent record updated |
+| `consent.erased` | `{ visitorId: string }` | Visitor data erased (GDPR erasure) |
+| `visitor.created` | `Visitor` | New visitor record created |
+| `profile.created` | `Profile` | Profile created |
+| `profile.updated` | `{ previous, current: Profile }` | Profile updated (version bumped) |
+| `profile.deleted` | `{ id: string, previous: Profile }` | Profile deleted |
+| `cache:warm` | `{ paths: string[], version: number }` | Fired after locale JSON files are written; paths to warm in CDN/cache |
+| `cache:purge` | `{ paths: string[], version: number }` | Fired after locale JSON files are removed; paths to purge from CDN/cache |
+
+`cache:warm` and `cache:purge` mirror the `handleCache` config callback — use whichever suits your integration.
+
+```ts
+const { eventBus } = createConsenti({ /* ... */ })
+
+eventBus.on('consent.created', (record) => {
+  // send to analytics, trigger webhook, etc.
+  console.log('New consent from visitor:', record.visitorId)
+})
+
+eventBus.on('consent.erased', ({ visitorId }) => {
+  myDmpClient.deleteVisitor(visitorId)
+})
+```
+
 ---
 
 ## Plugins (Server-side)
@@ -595,13 +986,26 @@ await consenti.destroy()
 
 ## Environment Variables
 
-| Variable                  | Description                                                                 |
-|---------------------------|-----------------------------------------------------------------------------|
-| `NODE_ENV`                | Set to `'production'` to suppress stack traces in error responses           |
-| `CONSENTI_ADMIN_PASSWORD`          | Override `auth.adminPassword` from config                                   |
-| `CONSENTI_ADMIN_JWT_SECRET`              | Override `auth.jwtSecret` from config                                       |
-| `CONSENTI_DB_PATH`        | Override `storage.path` (SQLite)                                            |
-| `CONSENTI_BASE_PATH`      | Override `basePath`                                                         |
+All config fields can be set via environment variables. Code config takes precedence over env vars.
+
+| Variable                            | Config field                       | Default                          |
+|-------------------------------------|------------------------------------|----------------------------------|
+| `NODE_ENV`                          | —                                  | Suppress stack traces when `'production'` |
+| `CONSENTI_BASE_PATH`                | `basePath`                         | `'/consenti'`                    |
+| `CONSENTI_ADMIN_EMAIL`              | `auth.adminEmail`                  | `'user@consenti.dev'`            |
+| `CONSENTI_ADMIN_PASSWORD`           | `auth.adminPassword`               | `'Consenti@123'`                 |
+| `CONSENTI_ADMIN_JWT_SECRET`         | `auth.jwtSecret`                   | random per restart               |
+| `CONSENTI_DB_DRIVER`                | `storage.driver`                   | `'json'`                         |
+| `CONSENTI_DB_PATH`                  | `storage.path`                     | `'./consenti-data'`              |
+| `CONSENTI_DB_URI`                   | `storage.uri`                      | —                                |
+| `CONSENTI_DB_DATABASE`              | `storage.database`                 | —                                |
+| `CONSENTI_DB_HOST`                  | `storage.host`                     | —                                |
+| `CONSENTI_DB_PORT`                  | `storage.port`                     | —                                |
+| `CONSENTI_DB_USER`                  | `storage.user`                     | —                                |
+| `CONSENTI_DB_PASSWORD`              | `storage.password`                 | —                                |
+| `CONSENTI_RATE_LIMIT_WINDOW_MS`     | `rateLimit.windowMs`               | `60000`                          |
+| `CONSENTI_RATE_LIMIT_MAX_REQUESTS`  | `rateLimit.maxRequests`            | `60`                             |
+| `CONSENTI_MAX_BODY_SIZE`            | `maxBodySize`                      | `1048576` (1 MB)                 |
 
 ---
 
@@ -610,6 +1014,15 @@ await consenti.destroy()
 When running, Swagger UI is available at `{basePath}/api/docs`.
 OpenAPI JSON at `{basePath}/api/openapi.json`.
 
+
+---
+
+## Demo
+For detailed API docs, Guides and Demo, visit [consenti.dev](https://consenti.dev) 
+
+Visit author's profile at [santosh.top](https://santosh.top)
+
+
 ---
 
 ## Contributing