@consentify/core 1.0.0 → 2.0.0

package/README.md

@@ -1,200 +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 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,
-  },
-  cookie: {
-    name: 'consentify',
-    path: '/',
-    sameSite: 'Lax',
-    secure: true,
+    identifier: 'v1.0',
+    categories: defaultCategories, // ['preferences', 'analytics', 'marketing', 'functional', 'unclassified']
   },
-  // Cookie is canonical. Optionally mirror to localStorage for fast client reads.
-  // storage: ['localStorage', 'cookie']
 });
 
-// Ask user... then set decisions
-consent.client.set({ analytics: true });
-
-// Query on client
-const canAnalytics = consent.client.get('analytics'); // boolean
-const state = consent.client.get(); // { decision: 'decided' | 'unset', snapshot? }
-```
+// Set user choices
+consent.client.set({ analytics: true, marketing: false });
 
-### SSR usage
+// Check consent
+if (consent.client.get('analytics')) {
+  loadAnalytics();
+}
 
-Use the server API with a raw Cookie header. It never touches the DOM.
+// Get full state
+const state = consent.client.get();
+// → { decision: 'decided', snapshot: { policy: '...', givenAt: '...', choices: {...} } }
+// → { decision: 'unset' } (if no consent given yet)
+```
 
-```ts
-// Read consent on the server
-const state = consent.server.get(request.headers.get('cookie'));
-const canAnalytics = state.decision === 'decided' && !!state.snapshot.choices.analytics;
+## React Integration
 
-// Write consent on the server (e.g., after a POST to your consent endpoint)
-const setCookieHeader = consent.server.set({ analytics: true }, request.headers.get('cookie'));
-// Then attach header:  res.setHeader('Set-Cookie', setCookieHeader)
+For React projects, use the [`@consentify/react`](https://www.npmjs.com/package/@consentify/react) package which provides a ready-to-use hook:
 
-// Clear consent cookie on the server
-const clearCookieHeader = consent.server.clear();
+```bash
+npm install @consentify/react
 ```
 
-### React integration
-
-The client API is designed to work seamlessly with React 18+ `useSyncExternalStore`:
-
 ```tsx
-import { useSyncExternalStore } from 'react';
-import { createConsentify, defaultCategories, type ConsentState, type DefaultCategory } from '@consentify/core';
+import { createConsentify, defaultCategories, useConsentify } from '@consentify/react';
 
-// Create once at module level
 const consent = createConsentify({
-  policy: { categories: defaultCategories, identifier: 'policy-v1' },
+  policy: { identifier: 'v1.0', categories: defaultCategories },
 });
 
-// Custom hook for React
-function useConsent(): ConsentState<DefaultCategory> {
-  return useSyncExternalStore(
-    consent.client.subscribe,
-    consent.client.get,
-    consent.client.getServerSnapshot
-  );
-}
-
-// Usage in components
-function ConsentBanner() {
-  const state = useConsent();
+function CookieBanner() {
+  const state = useConsentify(consent);
 
   if (state.decision === 'decided') return null;
 
   return (
-    <div>
-      <p>We use cookies to improve your experience.</p>
-      <button onClick={() => consent.client.set({ analytics: true, marketing: true })}>
+    <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 })}>
-        Reject Optional
+      <button onClick={() => consent.client.set({
+        analytics: false,
+        marketing: false,
+        preferences: false
+      })}>
+        Essential Only
       </button>
     </div>
   );
 }
 ```
 
-### API
-
-#### createConsentify(init)
-
-Creates a consent manager bound to a `policy`. Cookie is the canonical store; you can optionally mirror to `localStorage` for client-side speed. Returns:
+<details>
+<summary>Manual integration with useSyncExternalStore</summary>
 
-- `policy`: `{ categories: string[]; identifier: string }`
-- `client`:
-  - `get(): ConsentState<T>` — returns cached consent state `{ 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; notifies subscribers.
-  - `clear(): void` — removes stored consent (cookie and any mirror); notifies subscribers.
-  - `subscribe(callback: () => void): () => void` — subscribe to state changes (for React `useSyncExternalStore`).
-  - `getServerSnapshot(): ConsentState<T>` — returns `{ decision: 'unset' }` for SSR hydration.
-- `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.
+If you prefer not to add the React package, you can use `useSyncExternalStore` directly:
 
-Options (init):
-
-- `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']`)
+```tsx
+import { useSyncExternalStore } from 'react';
+import { createConsentify, defaultCategories } from '@consentify/core';
 
-Notes:
+const consent = createConsentify({
+  policy: { identifier: 'v1.0', categories: defaultCategories },
+});
 
-- `'necessary'` is always `true` and cannot be disabled.
-- The snapshot is invalidated automatically when the policy identity changes (identifier/hash).
-- Client state is cached and subscribers are notified on changes for optimal React performance.
+function useConsent() {
+  return useSyncExternalStore(
+    consent.client.subscribe,
+    consent.client.get,
+    consent.client.getServerSnapshot
+  );
+}
+```
 
-### Types
+</details>
 
-- `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.
-- `StorageKind` — `'cookie' | 'localStorage'`.
+## Server-Side Usage
 
-### Example: custom categories
+The server API works with raw `Cookie` headers — perfect for Next.js, Remix, or any Node.js framework:
 
 ```ts
-type Cat = 'analytics' | 'ads' | 'functional';
-const consent = createConsentify({
-  policy: { categories: ['analytics', 'ads', 'functional'] as const, identifier: 'policy-v1' },
-});
+// Read consent from request
+const state = consent.server.get(request.headers.get('cookie'));
 
-consent.client.set({ analytics: true, ads: false });
-if (consent.client.get('analytics')) {
-  // load analytics
+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();
 ```
 
-### Example: Next.js App Router
+### Next.js App Router Example
 
 ```tsx
 // lib/consent.ts
 import { createConsentify, defaultCategories } from '@consentify/core';
 
 export const consent = createConsentify({
-  policy: { categories: defaultCategories, identifier: 'policy-v1' },
+  policy: { identifier: 'v1.0', categories: defaultCategories },
 });
 
-// app/layout.tsx (Server Component)
+// 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());
-  const canLoadAnalytics = state.decision === 'decided' && state.snapshot.choices.analytics;
-
+  
   return (
     <html>
       <body>
         {children}
-        {canLoadAnalytics && <AnalyticsScript />}
+        {state.decision === 'decided' && state.snapshot.choices.analytics && (
+          <Analytics />
+        )}
       </body>
     </html>
   );
 }
 ```
 
-### Support
+## Custom Categories
+
+Define your own consent categories with full type safety:
+
+```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
+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)
+
+| 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>;
+```
+
+### Default Categories
+
+```ts
+const defaultCategories = [
+  'preferences',   // User preferences (language, theme)
+  'analytics',     // Analytics and performance
+  'marketing',     // Advertising and marketing
+  'functional',    // Enhanced functionality
+  'unclassified',  // Uncategorized cookies
+] as const;
+```
+
+## How It Works
+
+1. **Policy versioning** — Consent is tied to a policy identifier. When you update your policy (change `identifier`), previous consent is invalidated.
+
+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, consider supporting its development:
+If you find this library useful:
 
-- ⭐ [GitHub Sponsors](https://github.com/sponsors/RomanDenysov)
-- ☕ [Ko-fi](https://ko-fi.com/romandenysov)
+- ⭐ 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
+## License
 
 MIT © 2025 [Roman Denysov](https://github.com/RomanDenysov)

package/dist/index.d.ts

@@ -1,43 +1,15 @@
-/**
- * Literal type for the non-optional category that is always enabled.
- */
 export type Necessary = 'necessary';
-/**
- * User-defined category identifier (e.g., 'analytics', 'marketing').
- */
 export type UserCategory = string;
-/**
- * Map of consent choices for all categories, including the 'necessary' category.
- * A value of `true` means the user granted consent for the category.
- */
 export type Choices<T extends UserCategory> = Record<Necessary | T, boolean>;
-/**
- * Describes a cookie policy and its consent categories.
- * @template T Category string union used by this policy.
- */
 export interface Policy<T extends UserCategory> {
-    /**
-     * Optional stable identifier for your policy. Prefer supplying a value derived from
-     * your actual policy content/version (e.g., a hash of the policy document).
-     * If omitted, a deterministic hash of the provided categories (and this identifier when present)
-     * will be used to key snapshots.
-     */
     identifier?: string;
     categories: readonly T[];
 }
-/**
- * Immutable snapshot of a user's consent decision for a specific policy version.
- * @template T Category string union captured in the snapshot.
- */
 export interface Snapshot<T extends UserCategory> {
     policy: string;
     givenAt: string;
     choices: Choices<T>;
 }
-/**
- * High-level consent state derived from the presence of a valid snapshot.
- * When no valid snapshot exists for the current policy version, the state is `unset`.
- */
 export type ConsentState<T extends UserCategory> = {
     decision: 'unset';
 } | {
@@ -59,13 +31,14 @@ export interface CreateConsentifyInit<Cs extends readonly string[]> {
         path?: string;
         domain?: string;
     };
-    /**
-     * Client-side storage priority. Server-side access is cookie-only.
-     * Supported: 'cookie' (canonical), 'localStorage' (optional mirror for fast reads)
-     * Default: ['cookie']
-     */
+    consentMaxAgeDays?: number;
     storage?: StorageKind[];
 }
+export interface ConsentifySubscribable<T extends UserCategory> {
+    subscribe: (callback: () => void) => () => void;
+    get: () => ConsentState<T>;
+    getServerSnapshot: () => ConsentState<T>;
+}
 export declare function createConsentify<Cs extends readonly string[]>(init: CreateConsentifyInit<Cs>): {
     readonly policy: {
         readonly categories: Cs;
@@ -79,14 +52,50 @@ export declare function createConsentify<Cs extends readonly string[]>(init: Cre
     readonly client: {
         get: {
             (): ConsentState<ArrToUnion<Cs>>;
-            (category: "necessary" | ArrToUnion<Cs>): boolean;
+            (category: Necessary | ArrToUnion<Cs>): boolean;
         };
         set: (choices: Partial<Choices<ArrToUnion<Cs>>>) => void;
         clear: () => void;
         subscribe: (callback: () => void) => (() => void);
         getServerSnapshot: () => ConsentState<ArrToUnion<Cs>>;
+        guard: (category: Necessary | ArrToUnion<Cs>, onGrant: () => void, onRevoke?: () => void) => (() => void);
+    };
+    readonly get: {
+        (): ConsentState<ArrToUnion<Cs>>;
+        (cookieHeader: string): ConsentState<ArrToUnion<Cs>>;
+        (cookieHeader: null): ConsentState<ArrToUnion<Cs>>;
+    };
+    readonly isGranted: (category: Necessary | ArrToUnion<Cs>) => boolean;
+    readonly set: {
+        (choices: Partial<Choices<ArrToUnion<Cs>>>): void;
+        (choices: Partial<Choices<ArrToUnion<Cs>>>, cookieHeader: string): string;
+    };
+    readonly clear: {
+        (): void;
+        (serverMode: string): string;
     };
+    readonly subscribe: (callback: () => void) => (() => void);
+    readonly getServerSnapshot: () => ConsentState<ArrToUnion<Cs>>;
+    readonly guard: (category: Necessary | ArrToUnion<Cs>, onGrant: () => void, onRevoke?: () => void) => (() => void);
 };
 export declare const defaultCategories: readonly ["preferences", "analytics", "marketing", "functional", "unclassified"];
 export type DefaultCategory = typeof defaultCategories[number];
+export type GoogleConsentType = 'ad_storage' | 'ad_user_data' | 'ad_personalization' | 'analytics_storage' | 'functionality_storage' | 'personalization_storage' | 'security_storage';
+export interface ConsentModeOptions<T extends string> {
+    mapping: Partial<Record<'necessary' | T, GoogleConsentType[]>>;
+    waitForUpdate?: number;
+}
+export declare const defaultConsentModeMapping: {
+    readonly necessary: readonly ["security_storage"];
+    readonly analytics: readonly ["analytics_storage"];
+    readonly marketing: readonly ["ad_storage", "ad_user_data", "ad_personalization"];
+    readonly preferences: readonly ["functionality_storage", "personalization_storage"];
+};
+declare global {
+    interface Window {
+        dataLayer: unknown[];
+        gtag: (...args: unknown[]) => void;
+    }
+}
+export declare function enableConsentMode<T extends string>(instance: ConsentifySubscribable<T>, options: ConsentModeOptions<T>): () => void;
 export {};