@consentify/core 0.1.0 → 1.0.0

package/README.md

@@ -13,7 +13,7 @@ npm install @consentify/core
 ```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.
@@ -31,11 +31,11 @@ const manager = createConsentify({
 });
 
 // Ask user... then set decisions
-manager.client.set({ analytics: true });
+consent.client.set({ analytics: true });
 
 // Query on client
-const canAnalytics = manager.client.get('analytics'); // boolean
-const state = manager.client.get(); // { decision: 'decided' | 'unset', snapshot? }
+const canAnalytics = consent.client.get('analytics'); // boolean
+const state = consent.client.get(); // { decision: 'decided' | 'unset', snapshot? }
 ```
 
 ### SSR usage
@@ -44,15 +44,57 @@ Use the server API with a raw Cookie header. It never touches the DOM.
 
 ```ts
 // Read consent on the server
-const state = manager.server.get(request.headers.get('cookie'));
+const state = consent.server.get(request.headers.get('cookie'));
 const canAnalytics = state.decision === 'decided' && !!state.snapshot.choices.analytics;
 
 // 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'));
+const setCookieHeader = consent.server.set({ analytics: true }, request.headers.get('cookie'));
 // Then attach header:  res.setHeader('Set-Cookie', setCookieHeader)
 
 // Clear consent cookie on the server
-const clearCookieHeader = manager.server.clear();
+const clearCookieHeader = consent.server.clear();
+```
+
+### 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';
+
+// Create once at module level
+const consent = createConsentify({
+  policy: { categories: defaultCategories, identifier: 'policy-v1' },
+});
+
+// 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();
+
+  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 })}>
+        Accept All
+      </button>
+      <button onClick={() => consent.client.set({ analytics: false, marketing: false })}>
+        Reject Optional
+      </button>
+    </div>
+  );
+}
 ```
 
 ### API
@@ -63,10 +105,12 @@ Creates a consent manager bound to a `policy`. Cookie is the canonical store; yo
 
 - `policy`: `{ categories: string[]; identifier: string }`
 - `client`:
-  - `get(): ConsentState<T>` — re-reads storage and returns `{ decision: 'decided', snapshot } | { decision: 'unset' }`.
+  - `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.
-  - `clear(): void` — removes stored consent (cookie and any mirror).
+  - `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.
@@ -89,6 +133,7 @@ Notes:
 
 - `'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.
 
 ### Types
 
@@ -97,21 +142,52 @@ Notes:
 - `Choices<T>` — map of consent by category plus `'necessary'`.
 - `ConsentState<T>` — `{ decision: 'decided', snapshot } | { decision: 'unset' }`.
 - `defaultCategories`/`DefaultCategory` — reusable defaults.
+- `StorageKind` — `'cookie' | 'localStorage'`.
 
 ### Example: custom categories
 
 ```ts
 type Cat = 'analytics' | 'ads' | 'functional';
-const manager = createConsentify({
-  policy: { categories: ['analytics','ads','functional'] as const, identifier: 'policy-v1' },
+const consent = createConsentify({
+  policy: { categories: ['analytics', 'ads', 'functional'] as const, identifier: 'policy-v1' },
 });
 
-manager.client.set({ analytics: true, ads: false });
-if (manager.client.get('analytics')) {
+consent.client.set({ analytics: true, ads: false });
+if (consent.client.get('analytics')) {
   // load analytics
 }
 ```
 
+### Example: Next.js App Router
+
+```tsx
+// lib/consent.ts
+import { createConsentify, defaultCategories } from '@consentify/core';
+
+export const consent = createConsentify({
+  policy: { categories: defaultCategories, identifier: 'policy-v1' },
+});
+
+// app/layout.tsx (Server Component)
+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 />}
+      </body>
+    </html>
+  );
+}
+```
+
 ### Support
 
 If you find this library useful, consider supporting its development:
@@ -122,5 +198,3 @@ If you find this library useful, consider supporting its development:
 ### License
 
 MIT © 2025 [Roman Denysov](https://github.com/RomanDenysov)
-
-

package/dist/index.d.ts

@@ -83,6 +83,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

@@ -131,7 +131,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);
     };
@@ -190,14 +189,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 +229,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.0.0",
   "description": "Minimal headless cookie consent SDK (TypeScript, SSR-ready, lazy-init).",
   "author": {
     "name": "Roman Denysov",