@consentify/core 0.1.0 → 1.1.0

package/README.md

@@ -1,126 +1,292 @@
-## @consentify/core
+# @consentify/core
 
-Headless cookie consent SDK — zero-deps, TypeScript-first, SSR-safe. Stores a compact snapshot in a cookie and provides a minimal, strongly-typed API.
+[![npm version](https://img.shields.io/npm/v/@consentify/core.svg)](https://www.npmjs.com/package/@consentify/core)
+[![npm downloads](https://img.shields.io/npm/dm/@consentify/core.svg)](https://www.npmjs.com/package/@consentify/core)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/@consentify/core)](https://bundlephobia.com/package/@consentify/core)
+[![license](https://img.shields.io/npm/l/@consentify/core.svg)](./LICENSE)
 
-### Install
+> Headless cookie consent SDK — zero dependencies, TypeScript-first, SSR-ready.
+
+## Why Consentify?
+
+- **🪶 Lightweight** — Zero runtime dependencies, ~2KB minified + gzipped
+- **🔒 Type-safe** — Full TypeScript support with inference for your categories
+- **⚡ SSR-ready** — Separate server/client APIs that never touch the DOM on server
+- **⚛️ React-ready** — Built-in `useSyncExternalStore` support for React 18+
+- **🎯 Headless** — Bring your own UI, we handle the state
+- **📋 Compliant** — Built for GDPR, CCPA, and similar regulations
+
+## Install
 
 ```bash
 npm install @consentify/core
+# or
+pnpm add @consentify/core
+# or
+yarn add @consentify/core
 ```
 
-### Quick start
+## Quick Start
 
 ```ts
 import { createConsentify, defaultCategories } from '@consentify/core';
 
-const manager = createConsentify({
+const consent = createConsentify({
   policy: {
-    // Prefer to set a stable identifier derived from your policy document/version.
-    // If omitted, a deterministic hash of categories is used.
-    identifier: 'policy-v1',
-    categories: defaultCategories,
+    identifier: 'v1.0',
+    categories: defaultCategories, // ['preferences', 'analytics', 'marketing', 'functional', 'unclassified']
   },
-  cookie: {
-    name: 'consentify',
-    path: '/',
-    sameSite: 'Lax',
-    secure: true,
-  },
-  // Cookie is canonical. Optionally mirror to localStorage for fast client reads.
-  // storage: ['localStorage', 'cookie']
 });
 
-// Ask user... then set decisions
-manager.client.set({ analytics: true });
+// Set user choices
+consent.client.set({ analytics: true, marketing: false });
+
+// Check consent
+if (consent.client.get('analytics')) {
+  loadAnalytics();
+}
 
-// Query on client
-const canAnalytics = manager.client.get('analytics'); // boolean
-const state = manager.client.get(); // { decision: 'decided' | 'unset', snapshot? }
+// Get full state
+const state = consent.client.get();
+// → { decision: 'decided', snapshot: { policy: '...', givenAt: '...', choices: {...} } }
+// → { decision: 'unset' } (if no consent given yet)
 ```
 
-### SSR usage
+## React Integration
 
-Use the server API with a raw Cookie header. It never touches the DOM.
+For React projects, use the [`@consentify/react`](https://www.npmjs.com/package/@consentify/react) package which provides a ready-to-use hook:
 
-```ts
-// Read consent on the server
-const state = manager.server.get(request.headers.get('cookie'));
-const canAnalytics = state.decision === 'decided' && !!state.snapshot.choices.analytics;
+```bash
+npm install @consentify/react
+```
 
-// Write consent on the server (e.g., after a POST to your consent endpoint)
-const setCookieHeader = manager.server.set({ analytics: true }, request.headers.get('cookie'));
-// Then attach header:  res.setHeader('Set-Cookie', setCookieHeader)
+```tsx
+import { createConsentify, defaultCategories, useConsentify } from '@consentify/react';
+
+const consent = createConsentify({
+  policy: { identifier: 'v1.0', categories: defaultCategories },
+});
 
-// Clear consent cookie on the server
-const clearCookieHeader = manager.server.clear();
+function CookieBanner() {
+  const state = useConsentify(consent);
+
+  if (state.decision === 'decided') return null;
+
+  return (
+    <div className="cookie-banner">
+      <p>We use cookies to enhance your experience.</p>
+      <button onClick={() => consent.client.set({
+        analytics: true,
+        marketing: true,
+        preferences: true
+      })}>
+        Accept All
+      </button>
+      <button onClick={() => consent.client.set({
+        analytics: false,
+        marketing: false,
+        preferences: false
+      })}>
+        Essential Only
+      </button>
+    </div>
+  );
+}
 ```
 
-### API
+<details>
+<summary>Manual integration with useSyncExternalStore</summary>
 
-#### createConsentify(init)
+If you prefer not to add the React package, you can use `useSyncExternalStore` directly:
 
-Creates a consent manager bound to a `policy`. Cookie is the canonical store; you can optionally mirror to `localStorage` for client-side speed. Returns:
+```tsx
+import { useSyncExternalStore } from 'react';
+import { createConsentify, defaultCategories } from '@consentify/core';
 
-- `policy`: `{ categories: string[]; identifier: string }`
-- `client`:
-  - `get(): ConsentState<T>` — re-reads storage and returns `{ decision: 'decided', snapshot } | { decision: 'unset' }`.
-  - `get(category: 'necessary' | T): boolean` — boolean check; `'necessary'` always returns `true`.
-  - `set(choices: Partial<Choices<T>>): void` — merges and saves; writes only if changed.
-  - `clear(): void` — removes stored consent (cookie and any mirror).
-- `server`:
-  - `get(cookieHeader: string | null | undefined): ConsentState<T>` — raw Cookie header in, state out.
-  - `set(choices: Partial<Choices<T>>, currentCookieHeader?: string): string` — returns `Set-Cookie` header string.
-  - `clear(): string` — returns `Set-Cookie` header string to delete the cookie.
+const consent = createConsentify({
+  policy: { identifier: 'v1.0', categories: defaultCategories },
+});
 
-Options (init):
+function useConsent() {
+  return useSyncExternalStore(
+    consent.client.subscribe,
+    consent.client.get,
+    consent.client.getServerSnapshot
+  );
+}
+```
 
-- `policy`: `{ categories: readonly T[]; identifier?: string }`
-  - `identifier` is recommended and should come from your actual policy version/content. If omitted, a deterministic hash of the categories is used.
-- `cookie`:
-  - `name?: string` (default: `consentify`)
-  - `maxAgeSec?: number` (default: 1 year)
-  - `sameSite?: 'Lax' | 'Strict' | 'None'` (default: `'Lax'`)
-  - `secure?: boolean` (forced `true` when `sameSite==='None'`)
-  - `path?: string` (default: `/`)
-  - `domain?: string`
-- `storage?: ('cookie' | 'localStorage')[]` (default: `['cookie']`)
+</details>
 
-Notes:
+## Server-Side Usage
 
-- `'necessary'` is always `true` and cannot be disabled.
-- The snapshot is invalidated automatically when the policy identity changes (identifier/hash).
+The server API works with raw `Cookie` headers — perfect for Next.js, Remix, or any Node.js framework:
 
-### Types
+```ts
+// Read consent from request
+const state = consent.server.get(request.headers.get('cookie'));
+
+if (state.decision === 'decided' && state.snapshot.choices.analytics) {
+  // User consented to analytics
+}
+
+// Set consent (returns Set-Cookie header string)
+const setCookieHeader = consent.server.set(
+  { analytics: true },
+  request.headers.get('cookie')
+);
+response.headers.set('Set-Cookie', setCookieHeader);
+
+// Clear consent
+const clearHeader = consent.server.clear();
+```
+
+### Next.js App Router Example
+
+```tsx
+// lib/consent.ts
+import { createConsentify, defaultCategories } from '@consentify/core';
+
+export const consent = createConsentify({
+  policy: { identifier: 'v1.0', categories: defaultCategories },
+});
+
+// app/layout.tsx
+import { cookies } from 'next/headers';
+import { consent } from '@/lib/consent';
+
+export default async function RootLayout({ children }) {
+  const cookieStore = await cookies();
+  const state = consent.server.get(cookieStore.toString());
+  
+  return (
+    <html>
+      <body>
+        {children}
+        {state.decision === 'decided' && state.snapshot.choices.analytics && (
+          <Analytics />
+        )}
+      </body>
+    </html>
+  );
+}
+```
+
+## Custom Categories
 
-- `Policy<T>` — `{ identifier?: string; categories: readonly T[] }`.
-- `Snapshot<T>` — `{ policy: string; givenAt: string; choices: Record<'necessary'|T, boolean> }`.
-- `Choices<T>` — map of consent by category plus `'necessary'`.
-- `ConsentState<T>` — `{ decision: 'decided', snapshot } | { decision: 'unset' }`.
-- `defaultCategories`/`DefaultCategory` — reusable defaults.
+Define your own consent categories with full type safety:
 
-### Example: custom categories
+```ts
+const consent = createConsentify({
+  policy: {
+    identifier: 'v1.0',
+    categories: ['analytics', 'ads', 'personalization'] as const,
+  },
+});
+
+// TypeScript knows your categories!
+consent.client.set({ analytics: true, ads: false });
+consent.client.get('personalization'); // ✓ valid
+consent.client.get('unknown');         // ✗ type error
+```
+
+## Configuration
 
 ```ts
-type Cat = 'analytics' | 'ads' | 'functional';
-const manager = createConsentify({
-  policy: { categories: ['analytics','ads','functional'] as const, identifier: 'policy-v1' },
+createConsentify({
+  policy: {
+    identifier: 'v1.0',           // Recommended: version your policy
+    categories: defaultCategories,
+  },
+  // Consent validity (when to re-prompt user)
+  consentMaxAgeDays: 365,         // Optional: re-consent after N days
+  // Cookie storage settings (browser retention)
+  cookie: {
+    name: 'consent',              // Default: 'consentify'
+    maxAgeSec: 60 * 60 * 24 * 365, // Default: 1 year (browser storage)
+    sameSite: 'Lax',              // 'Lax' | 'Strict' | 'None'
+    secure: true,                 // Forced true when sameSite='None'
+    path: '/',
+    domain: '.example.com',       // Optional: for cross-subdomain
+  },
+  storage: ['cookie'],            // ['cookie'] | ['localStorage', 'cookie']
 });
+```
+
+## API Reference
+
+### `createConsentify(options)`
+
+Returns an object with `policy`, `client`, and `server` properties.
+
+#### `client` (browser)
 
-manager.client.set({ analytics: true, ads: false });
-if (manager.client.get('analytics')) {
-  // load analytics
+| Method | Description |
+|--------|-------------|
+| `get()` | Returns `ConsentState` — `{ decision: 'decided', snapshot }` or `{ decision: 'unset' }` |
+| `get(category)` | Returns `boolean` — `true` if category is consented (`'necessary'` always returns `true`) |
+| `set(choices)` | Merges choices and persists; notifies subscribers if changed |
+| `clear()` | Removes stored consent; notifies subscribers |
+| `subscribe(cb)` | Subscribe to changes; returns unsubscribe function |
+| `getServerSnapshot()` | Returns `{ decision: 'unset' }` for SSR hydration |
+
+#### `server` (Node.js)
+
+| Method | Description |
+|--------|-------------|
+| `get(cookieHeader)` | Parse consent from `Cookie` header string |
+| `set(choices, cookieHeader?)` | Returns `Set-Cookie` header string |
+| `clear()` | Returns `Set-Cookie` header string to delete cookie |
+
+### Types
+
+```ts
+type ConsentState<T> = 
+  | { decision: 'unset' }
+  | { decision: 'decided'; snapshot: Snapshot<T> };
+
+interface Snapshot<T> {
+  policy: string;      // Policy identifier/hash
+  givenAt: string;     // ISO timestamp
+  choices: Choices<T>; // { necessary: true, ...categories }
 }
+
+type Choices<T> = Record<'necessary' | T, boolean>;
 ```
 
-### Support
+### Default Categories
 
-If you find this library useful, consider supporting its development:
+```ts
+const defaultCategories = [
+  'preferences',   // User preferences (language, theme)
+  'analytics',     // Analytics and performance
+  'marketing',     // Advertising and marketing
+  'functional',    // Enhanced functionality
+  'unclassified',  // Uncategorized cookies
+] as const;
+```
 
-- ⭐ [GitHub Sponsors](https://github.com/sponsors/RomanDenysov)
-- ☕ [Ko-fi](https://ko-fi.com/romandenysov)
+## How It Works
 
-### License
+1. **Policy versioning** — Consent is tied to a policy identifier. When you update your policy (change `identifier`), previous consent is invalidated.
 
-MIT © 2025 [Roman Denysov](https://github.com/RomanDenysov)
+2. **Necessary cookies** — The `'necessary'` category is always `true` and cannot be disabled.
+
+3. **Storage** — Cookie is the canonical store (works on server). Optionally mirror to `localStorage` for faster client reads.
+
+4. **Compact format** — Consent is stored as a URL-encoded JSON snapshot in a single cookie.
+
+5. **Consent expiration** — Optional `consentMaxAgeDays` invalidates consent after N days, requiring users to re-consent. This is independent of `cookie.maxAgeSec` (which controls how long the browser stores the cookie).
 
+## Support
 
+If you find this library useful:
+
+- ⭐ Star the repo on [GitHub](https://github.com/RomanDenysov/consentify)
+- 💖 [Sponsor on GitHub](https://github.com/sponsors/RomanDenysov)
+- ☕ [Buy me a coffee on Ko-fi](https://ko-fi.com/romandenysov)
+- ☕ [Buy me a coffee](https://buymeacoffee.com/romandenysov)
+
+## License
+
+MIT © 2025 [Roman Denysov](https://github.com/RomanDenysov)

package/dist/index.d.ts

@@ -59,6 +59,11 @@ export interface CreateConsentifyInit<Cs extends readonly string[]> {
         path?: string;
         domain?: string;
     };
+    /**
+     * Maximum age of consent in days. If set, consent older than this
+     * will be treated as expired, requiring re-consent.
+     */
+    consentMaxAgeDays?: number;
     /**
      * Client-side storage priority. Server-side access is cookie-only.
      * Supported: 'cookie' (canonical), 'localStorage' (optional mirror for fast reads)
@@ -83,6 +88,8 @@ export declare function createConsentify<Cs extends readonly string[]>(init: Cre
         };
         set: (choices: Partial<Choices<ArrToUnion<Cs>>>) => void;
         clear: () => void;
+        subscribe: (callback: () => void) => (() => void);
+        getServerSnapshot: () => ConsentState<ArrToUnion<Cs>>;
     };
 };
 export declare const defaultCategories: readonly ["preferences", "analytics", "marketing", "functional", "unclassified"];

package/dist/index.js

@@ -29,6 +29,13 @@ catch {
     return null;
 } };
 const toISO = () => new Date().toISOString();
+function isValidSnapshot(s) {
+    return (typeof s === 'object' && s !== null &&
+        typeof s.policy === 'string' &&
+        typeof s.givenAt === 'string' &&
+        typeof s.choices === 'object' &&
+        s.choices !== null);
+}
 function readCookie(name, cookieStr) {
     const src = cookieStr ?? (typeof document !== 'undefined' ? document.cookie : '');
     if (!src)
@@ -59,6 +66,16 @@ export function createConsentify(init) {
         domain: init.cookie?.domain,
     };
     const storageOrder = (init.storage && init.storage.length > 0) ? init.storage : ['cookie'];
+    const consentMaxAgeDays = init.consentMaxAgeDays;
+    const isExpired = (givenAt) => {
+        if (!consentMaxAgeDays)
+            return false;
+        const givenTime = new Date(givenAt).getTime();
+        if (isNaN(givenTime))
+            return true; // Invalid date = expired
+        const maxAgeMs = consentMaxAgeDays * 24 * 60 * 60 * 1000;
+        return Date.now() - givenTime > maxAgeMs;
+    };
     const allowed = new Set(['necessary', ...init.policy.categories]);
     const normalize = (choices) => {
         const base = { necessary: true };
@@ -131,7 +148,6 @@ export function createConsentify(init) {
     const writeClientRaw = (value) => {
         const primary = firstAvailableStore();
         writeToStore(primary, value);
-        // Mirror to cookie if requested anywhere in order and not already writing cookie
         if (primary !== 'cookie' && storageOrder.includes('cookie'))
             writeToStore('cookie', value);
     };
@@ -139,10 +155,12 @@ export function createConsentify(init) {
     const readClient = () => {
         const raw = readClientRaw();
         const s = raw ? dec(raw) : null;
-        if (!s)
+        if (!s || !isValidSnapshot(s))
             return null;
         if (s.policy !== policyHash)
             return null;
+        if (isExpired(s.givenAt))
+            return null;
         return s;
     };
     const writeClientIfChanged = (next) => {
@@ -165,10 +183,12 @@ export function createConsentify(init) {
         get: (cookieHeader) => {
             const raw = cookieHeader ? readCookie(cookieName, cookieHeader) : null;
             const s = raw ? dec(raw) : null;
-            if (!s)
+            if (!s || !isValidSnapshot(s))
                 return { decision: 'unset' };
             if (s.policy !== policyHash)
                 return { decision: 'unset' };
+            if (isExpired(s.givenAt))
+                return { decision: 'unset' };
             return { decision: 'decided', snapshot: s };
         },
         set: (choices, currentCookieHeader) => {
@@ -190,14 +210,35 @@ export function createConsentify(init) {
             return h;
         }
     };
-    function clientGet(category) {
+    // ========== NEW: Subscribe pattern for React ==========
+    const listeners = new Set();
+    const unsetState = { decision: 'unset' };
+    let cachedState = unsetState;
+    const syncState = () => {
         const s = readClient();
-        const state = s ? { decision: 'decided', snapshot: s } : { decision: 'unset' };
+        if (!s) {
+            cachedState = unsetState;
+        }
+        else {
+            cachedState = { decision: 'decided', snapshot: s };
+        }
+    };
+    const notifyListeners = () => {
+        listeners.forEach(cb => cb());
+    };
+    // Init cache on browser
+    if (isBrowser()) {
+        syncState();
+    }
+    function clientGet(category) {
+        // Return cached state for React compatibility
         if (typeof category === 'undefined')
-            return state;
+            return cachedState;
         if (category === 'necessary')
             return true;
-        return state.decision === 'decided' ? !!state.snapshot.choices[category] : false;
+        return cachedState.decision === 'decided'
+            ? !!cachedState.snapshot.choices[category]
+            : false;
     }
     const client = {
         get: clientGet,
@@ -209,14 +250,26 @@ export function createConsentify(init) {
                 givenAt: toISO(),
                 choices: normalize({ ...base, ...choices }),
             };
-            writeClientIfChanged(next);
+            const changed = writeClientIfChanged(next);
+            if (changed) {
+                syncState();
+                notifyListeners();
+            }
         },
         clear: () => {
             for (const k of new Set([...storageOrder, 'cookie']))
                 clearStore(k);
+            syncState();
+            notifyListeners();
+        },
+        // NEW: Subscribe for React useSyncExternalStore
+        subscribe: (callback) => {
+            listeners.add(callback);
+            return () => listeners.delete(callback);
         },
+        // NEW: Server snapshot for SSR (always unset)
+        getServerSnapshot: () => unsetState,
     };
-    // ---- single entry (DX aliases)
     return {
         policy: {
             categories: init.policy.categories,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@consentify/core",
-  "version": "0.1.0",
+  "version": "1.1.0",
   "description": "Minimal headless cookie consent SDK (TypeScript, SSR-ready, lazy-init).",
   "author": {
     "name": "Roman Denysov",
@@ -14,6 +14,10 @@
     {
       "type": "ko-fi",
       "url": "https://ko-fi.com/romandenysov"
+    },
+    {
+      "type": "buymeacoffee",
+      "url": "https://buymeacoffee.com/romandenysov"
     }
   ],
   "engines": {
@@ -63,6 +67,7 @@
     "@types/node": "24.7.0"
   },
   "scripts": {
-    "build": "rimraf dist && tsc -p tsconfig.build.json"
+    "build": "rimraf dist && tsc -p tsconfig.build.json",
+    "check": "tsc --noEmit"
   }
 }