@consentify/core 0.1.0

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2025 Roman Denysov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+

package/README.md

@@ -0,0 +1,126 @@
+## @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.
+
+### Install
+
+```bash
+npm install @consentify/core
+```
+
+### Quick start
+
+```ts
+import { createConsentify, defaultCategories } from '@consentify/core';
+
+const manager = 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,
+  },
+  // Cookie is canonical. Optionally mirror to localStorage for fast client reads.
+  // storage: ['localStorage', 'cookie']
+});
+
+// Ask user... then set decisions
+manager.client.set({ analytics: true });
+
+// Query on client
+const canAnalytics = manager.client.get('analytics'); // boolean
+const state = manager.client.get(); // { decision: 'decided' | 'unset', snapshot? }
+```
+
+### SSR usage
+
+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 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'));
+// Then attach header:  res.setHeader('Set-Cookie', setCookieHeader)
+
+// Clear consent cookie on the server
+const clearCookieHeader = manager.server.clear();
+```
+
+### 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:
+
+- `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.
+
+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']`)
+
+Notes:
+
+- `'necessary'` is always `true` and cannot be disabled.
+- The snapshot is invalidated automatically when the policy identity changes (identifier/hash).
+
+### Types
+
+- `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.
+
+### Example: custom categories
+
+```ts
+type Cat = 'analytics' | 'ads' | 'functional';
+const manager = createConsentify({
+  policy: { categories: ['analytics','ads','functional'] as const, identifier: 'policy-v1' },
+});
+
+manager.client.set({ analytics: true, ads: false });
+if (manager.client.get('analytics')) {
+  // load analytics
+}
+```
+
+### Support
+
+If you find this library useful, consider supporting its development:
+
+- ⭐ [GitHub Sponsors](https://github.com/sponsors/RomanDenysov)
+- ☕ [Ko-fi](https://ko-fi.com/romandenysov)
+
+### License
+
+MIT © 2025 [Roman Denysov](https://github.com/RomanDenysov)
+
+

package/dist/index.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 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';
+} | {
+    decision: 'decided';
+    snapshot: Snapshot<T>;
+};
+type ArrToUnion<T extends readonly string[]> = T[number];
+export type StorageKind = 'cookie' | 'localStorage';
+export interface CreateConsentifyInit<Cs extends readonly string[]> {
+    policy: {
+        categories: Cs;
+        identifier?: string;
+    };
+    cookie?: {
+        name?: string;
+        maxAgeSec?: number;
+        sameSite?: 'Lax' | 'Strict' | 'None';
+        secure?: boolean;
+        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']
+     */
+    storage?: StorageKind[];
+}
+export declare function createConsentify<Cs extends readonly string[]>(init: CreateConsentifyInit<Cs>): {
+    readonly policy: {
+        readonly categories: Cs;
+        readonly identifier: string;
+    };
+    readonly server: {
+        get: (cookieHeader: string | null | undefined) => ConsentState<ArrToUnion<Cs>>;
+        set: (choices: Partial<Choices<ArrToUnion<Cs>>>, currentCookieHeader?: string) => string;
+        clear: () => string;
+    };
+    readonly client: {
+        get: {
+            (): ConsentState<ArrToUnion<Cs>>;
+            (category: "necessary" | ArrToUnion<Cs>): boolean;
+        };
+        set: (choices: Partial<Choices<ArrToUnion<Cs>>>) => void;
+        clear: () => void;
+    };
+};
+export declare const defaultCategories: readonly ["preferences", "analytics", "marketing", "functional", "unclassified"];
+export type DefaultCategory = typeof defaultCategories[number];
+export {};

package/dist/index.js

@@ -0,0 +1,230 @@
+function stableStringify(o) {
+    if (o === null || typeof o !== 'object')
+        return JSON.stringify(o);
+    if (Array.isArray(o))
+        return `[${o.map(stableStringify).join(',')}]`;
+    const e = Object.entries(o).sort((a, b) => a[0].localeCompare(b[0]));
+    return `{${e.map(([k, v]) => JSON.stringify(k) + ':' + stableStringify(v)).join(',')}}`;
+}
+function fnv1a(str) {
+    let h = 0x811c9dc5 >>> 0;
+    for (let i = 0; i < str.length; i++) {
+        h ^= str.charCodeAt(i);
+        h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;
+    }
+    return ('00000000' + h.toString(16)).slice(-8);
+}
+function hashPolicy(categories, identifier) {
+    // Deterministic identity for the policy. If you provide `identifier`, it is folded into the hash,
+    // but consider using `identifier` itself as the canonical version key for clarity.
+    return fnv1a(stableStringify({ categories: [...categories].sort(), identifier: identifier ?? null }));
+}
+// --- Internals ---
+const DEFAULT_COOKIE = 'consentify';
+const enc = (o) => encodeURIComponent(JSON.stringify(o));
+const dec = (s) => { try {
+    return JSON.parse(decodeURIComponent(s));
+}
+catch {
+    return null;
+} };
+const toISO = () => new Date().toISOString();
+function readCookie(name, cookieStr) {
+    const src = cookieStr ?? (typeof document !== 'undefined' ? document.cookie : '');
+    if (!src)
+        return null;
+    const m = src.split(';').map(v => v.trim()).find(v => v.startsWith(name + '='));
+    return m ? m.slice(name.length + 1) : null;
+}
+function writeCookie(name, value, opt) {
+    if (typeof document === 'undefined')
+        return;
+    let c = `${name}=${value}; Path=${opt.path}; Max-Age=${opt.maxAgeSec}; SameSite=${opt.sameSite}`;
+    if (opt.domain)
+        c += `; Domain=${opt.domain}`;
+    if (opt.secure)
+        c += `; Secure`;
+    document.cookie = c;
+}
+// --- Unified Factory (single entry point) ---
+export function createConsentify(init) {
+    const policyHash = init.policy.identifier ?? hashPolicy(init.policy.categories);
+    const cookieName = init.cookie?.name ?? DEFAULT_COOKIE;
+    const sameSite = init.cookie?.sameSite ?? 'Lax';
+    const cookieCfg = {
+        path: init.cookie?.path ?? '/',
+        maxAgeSec: init.cookie?.maxAgeSec ?? 60 * 60 * 24 * 365,
+        sameSite,
+        secure: sameSite === 'None' ? true : (init.cookie?.secure ?? true),
+        domain: init.cookie?.domain,
+    };
+    const storageOrder = (init.storage && init.storage.length > 0) ? init.storage : ['cookie'];
+    const allowed = new Set(['necessary', ...init.policy.categories]);
+    const normalize = (choices) => {
+        const base = { necessary: true };
+        for (const c of init.policy.categories)
+            base[c] = false;
+        if (choices) {
+            for (const [k, v] of Object.entries(choices)) {
+                if (allowed.has(k))
+                    base[k] = !!v;
+            }
+        }
+        base.necessary = true;
+        return base;
+    };
+    // --- client-side storage helpers ---
+    const isBrowser = () => typeof window !== 'undefined' && typeof document !== 'undefined';
+    const canLocal = () => { try {
+        return isBrowser() && !!window.localStorage;
+    }
+    catch {
+        return false;
+    } };
+    const readFromStore = (kind) => {
+        switch (kind) {
+            case 'cookie': return readCookie(cookieName);
+            case 'localStorage': return canLocal() ? window.localStorage.getItem(cookieName) : null;
+            default: return null;
+        }
+    };
+    const writeToStore = (kind, value) => {
+        switch (kind) {
+            case 'cookie':
+                writeCookie(cookieName, value, cookieCfg);
+                break;
+            case 'localStorage':
+                if (canLocal())
+                    window.localStorage.setItem(cookieName, value);
+                break;
+        }
+    };
+    const clearStore = (kind) => {
+        switch (kind) {
+            case 'cookie':
+                if (isBrowser())
+                    document.cookie = `${cookieName}=; Path=${cookieCfg.path}; Max-Age=0; SameSite=${cookieCfg.sameSite}${cookieCfg.domain ? `; Domain=${cookieCfg.domain}` : ''}${cookieCfg.secure ? '; Secure' : ''}`;
+                break;
+            case 'localStorage':
+                if (canLocal())
+                    window.localStorage.removeItem(cookieName);
+                break;
+        }
+    };
+    const firstAvailableStore = () => {
+        for (const k of storageOrder) {
+            if (k === 'cookie')
+                return 'cookie';
+            if (k === 'localStorage' && canLocal())
+                return 'localStorage';
+        }
+        return 'cookie';
+    };
+    const readClientRaw = () => {
+        for (const k of storageOrder) {
+            const v = readFromStore(k);
+            if (v)
+                return v;
+        }
+        return null;
+    };
+    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);
+    };
+    // --- read helpers ---
+    const readClient = () => {
+        const raw = readClientRaw();
+        const s = raw ? dec(raw) : null;
+        if (!s)
+            return null;
+        if (s.policy !== policyHash)
+            return null;
+        return s;
+    };
+    const writeClientIfChanged = (next) => {
+        const prev = readClient();
+        const same = !!(prev && prev.policy === next.policy && JSON.stringify(prev.choices) === JSON.stringify(next.choices));
+        if (!same)
+            writeClientRaw(enc(next));
+        return !same;
+    };
+    function buildSetCookieHeader(name, value, opt) {
+        let header = `${name}=${value}; Path=${opt.path}; Max-Age=${opt.maxAgeSec}; SameSite=${opt.sameSite}`;
+        if (opt.domain)
+            header += `; Domain=${opt.domain}`;
+        if (opt.secure)
+            header += `; Secure`;
+        return header;
+    }
+    // ---- server API
+    const server = {
+        get: (cookieHeader) => {
+            const raw = cookieHeader ? readCookie(cookieName, cookieHeader) : null;
+            const s = raw ? dec(raw) : null;
+            if (!s)
+                return { decision: 'unset' };
+            if (s.policy !== policyHash)
+                return { decision: 'unset' };
+            return { decision: 'decided', snapshot: s };
+        },
+        set: (choices, currentCookieHeader) => {
+            const prev = currentCookieHeader ? server.get(currentCookieHeader) : { decision: 'unset' };
+            const base = prev.decision === 'decided' ? prev.snapshot.choices : normalize();
+            const snapshot = {
+                policy: policyHash,
+                givenAt: toISO(),
+                choices: normalize({ ...base, ...choices }),
+            };
+            return buildSetCookieHeader(cookieName, enc(snapshot), cookieCfg);
+        },
+        clear: () => {
+            let h = `${cookieName}=; Path=${cookieCfg.path}; Max-Age=0; SameSite=${cookieCfg.sameSite}`;
+            if (cookieCfg.domain)
+                h += `; Domain=${cookieCfg.domain}`;
+            if (cookieCfg.secure)
+                h += `; Secure`;
+            return h;
+        }
+    };
+    function clientGet(category) {
+        const s = readClient();
+        const state = s ? { decision: 'decided', snapshot: s } : { decision: 'unset' };
+        if (typeof category === 'undefined')
+            return state;
+        if (category === 'necessary')
+            return true;
+        return state.decision === 'decided' ? !!state.snapshot.choices[category] : false;
+    }
+    const client = {
+        get: clientGet,
+        set: (choices) => {
+            const prev = client.get();
+            const base = prev.decision === 'decided' ? prev.snapshot.choices : normalize();
+            const next = {
+                policy: policyHash,
+                givenAt: toISO(),
+                choices: normalize({ ...base, ...choices }),
+            };
+            writeClientIfChanged(next);
+        },
+        clear: () => {
+            for (const k of new Set([...storageOrder, 'cookie']))
+                clearStore(k);
+        },
+    };
+    // ---- single entry (DX aliases)
+    return {
+        policy: {
+            categories: init.policy.categories,
+            identifier: policyHash,
+        },
+        server,
+        client,
+    };
+}
+// Common predefined category names you can reuse in your policy.
+export const defaultCategories = ['preferences', 'analytics', 'marketing', 'functional', 'unclassified'];

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@consentify/core",
+  "version": "0.1.0",
+  "description": "Minimal headless cookie consent SDK (TypeScript, SSR-ready, lazy-init).",
+  "author": {
+    "name": "Roman Denysov",
+    "url": "https://github.com/RomanDenysov"
+  },
+  "funding": [
+    {
+      "type": "github",
+      "url": "https://github.com/sponsors/RomanDenysov"
+    },
+    {
+      "type": "ko-fi",
+      "url": "https://ko-fi.com/romandenysov"
+    }
+  ],
+  "engines": {
+    "node": ">=20.0.0",
+    "pnpm": ">=9"
+  },
+  "keywords": [
+    "cookie",
+    "consent",
+    "gdpr",
+    "ccpa",
+    "privacy",
+    "typescript",
+    "ssr"
+  ],
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RomanDenysov/consentify.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/RomanDenysov/consentify/issues"
+  },
+  "homepage": "https://github.com/RomanDenysov/consentify#readme",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "rimraf": "6.0.1",
+    "typescript": "5.9.3",
+    "@types/node": "24.7.0"
+  },
+  "scripts": {
+    "build": "rimraf dist && tsc -p tsconfig.build.json"
+  }
+}