@ecomconsult/consentkit 0.3.2

package/npm/index.d.ts

@@ -0,0 +1,224 @@
+/**
+ * ConsentKit — type declarations for the public API, config and React hook.
+ *
+ * Deliberately dependency-free: nothing is imported from 'react', so these
+ * types check with a bare `tsc --noEmit` and no @types packages installed.
+ */
+
+/** Consent category. `necessary` is always granted and cannot be switched off. */
+export type CkCategory = 'necessary' | 'functional' | 'analytics' | 'marketing';
+
+/** Opt-in categories — everything except `necessary`. */
+export type CkOptInCategory = 'functional' | 'analytics' | 'marketing';
+
+/** Per-category grant map. */
+export interface CkCategories {
+  /** Always `true`. */
+  necessary: boolean;
+  functional: boolean;
+  analytics: boolean;
+  marketing: boolean;
+}
+
+/** How the current decision was made. `null` while undecided. */
+export type CkMethod = 'accept_all' | 'reject_all' | 'custom' | null;
+
+/** Public consent state, as returned by `getState()`. */
+export interface CkState {
+  /** `false` until the visitor makes a choice — the banner shows while false. */
+  decided: boolean;
+  /** UUID of the stored decision, `null` while undecided. */
+  id: string | null;
+  /** ISO timestamp of the decision, `null` while undecided. */
+  ts: string | null;
+  /** Policy version the decision was recorded against. */
+  policyVersion: string;
+  categories: CkCategories;
+  method: CkMethod;
+}
+
+/** Argument to `accept()`: `'all'`, or an explicit per-category selection. */
+export type CkAcceptArg = 'all' | Partial<Record<CkOptInCategory, boolean>>;
+
+/** Banner placement. `bar` uses bottom/top; `box` uses the corner positions. */
+export type CkLayoutType = 'bar' | 'modal' | 'box';
+
+export type CkLayoutPosition = 'bottom' | 'top' | 'bottom-right' | 'bottom-left';
+
+export interface CkLayoutConfig {
+  /** Default `'bar'`. Unknown combinations degrade to `bar` / `bottom`. */
+  type?: CkLayoutType;
+  /** `bar`: `'bottom'` (default) | `'top'`. `box`: `'bottom-left'` (default) | `'bottom-right'`. */
+  position?: CkLayoutPosition;
+}
+
+/** Optional override for the dark palette (v0.2). */
+export interface CkDarkTheme {
+  bg?: string;
+  ink?: string;
+  accent?: string;
+}
+
+export interface CkThemeConfig {
+  /** Accent colour, exposed as `--ck-accent`. Default `'#2B50D8'`. */
+  accent?: string;
+  /** Corner radius, exposed as `--ck-radius`. Default `'10px'`. */
+  radius?: string;
+  /** v0.2. Default `'auto'` — follows `prefers-color-scheme`. */
+  mode?: 'auto' | 'light' | 'dark';
+  /** v0.2. Overrides the built-in dark palette. */
+  dark?: CkDarkTheme;
+}
+
+/** Whether a category is offered in the preferences panel at all. */
+export interface CkCategoryConfig {
+  enabled?: boolean;
+}
+
+export interface CkCategoriesConfig {
+  functional?: CkCategoryConfig;
+  analytics?: CkCategoryConfig;
+  marketing?: CkCategoryConfig;
+}
+
+export interface CkIntegrationsConfig {
+  /** Google Consent Mode v2 signals. Default `true`. */
+  gcm?: boolean;
+  /** Push consent events to `window.dataLayer`. Default `true`. */
+  gtmDataLayer?: boolean;
+}
+
+/** One declared cookie, shown under its category in the preferences panel. */
+export interface CkCookieTableEntry {
+  name: string;
+  category: CkCategory;
+  vendor?: string;
+  purpose?: string;
+  expiry?: string;
+}
+
+/** Configuration accepted by `init()`. Every field is optional. */
+export interface CkConfig {
+  /** Bump to invalidate stored decisions and re-show the banner. Default `'1'`. */
+  policyVersion?: string | number;
+  /** `'auto'` resolves from `navigator.language`. Default `'auto'`. */
+  language?: string;
+  layout?: CkLayoutConfig;
+  theme?: CkThemeConfig;
+  categories?: CkCategoriesConfig;
+  /** Lifetime of the stored decision, in days. Default `365`. */
+  consentTtlDays?: number;
+  integrations?: CkIntegrationsConfig;
+  cookieTable?: CkCookieTableEntry[];
+}
+
+/** Detail payload of `ck:init`. */
+export interface CkInitEventDetail {
+  state: CkState;
+  config: CkConfig;
+}
+
+/** Detail payload of `ck:consent` and `ck:change`. */
+export interface CkStateEventDetail {
+  state: CkState;
+}
+
+/** The public API, also available as `window.ConsentKit`. */
+export interface ConsentKitApi {
+  readonly version: string;
+  /** The merged, effective config. Populated by `init()`. */
+  config: CkConfig;
+  /** Idempotent. Restores stored state, then dispatches `ck:init`. */
+  init(config?: CkConfig): CkState;
+  allowed(category: CkCategory | string): boolean;
+  getState(): CkState;
+  /** `accept('all')` grants everything; an object records `method: 'custom'`. */
+  accept(choice?: CkAcceptArg): CkState;
+  rejectAll(): CkState;
+  /** Clears storage and known cookies, sets `decided:false`, sends GCM denied. */
+  withdraw(): CkState;
+  /** Dispatches `ck:ui:open-preferences`. */
+  show(): void;
+  /** Dispatches `ck:ui:close`. */
+  hide(): void;
+}
+
+declare const ConsentKit: ConsentKitApi;
+
+export default ConsentKit;
+export { ConsentKit };
+
+export declare function init(config?: CkConfig): CkState;
+export declare function allowed(category: CkCategory | string): boolean;
+export declare function getState(): CkState;
+export declare function accept(choice?: CkAcceptArg): CkState;
+export declare function rejectAll(): CkState;
+export declare function withdraw(): CkState;
+export declare function show(): void;
+export declare function hide(): void;
+
+declare global {
+  interface Window {
+    ConsentKit?: ConsentKitApi;
+    /** Extra locale packs contributed by `src/ck-locales.js`. */
+    __ckLocales?: Record<string, Record<string, string>>;
+  }
+
+  interface DocumentEventMap {
+    'ck:init': CustomEvent<CkInitEventDetail>;
+    'ck:consent': CustomEvent<CkStateEventDetail>;
+    'ck:change': CustomEvent<CkStateEventDetail>;
+    'ck:ui:open-preferences': CustomEvent<CkInitEventDetail>;
+    'ck:ui:close': CustomEvent<CkStateEventDetail>;
+  }
+}
+
+declare module '@ecomconsult/consentkit' {
+  const ConsentKit: ConsentKitApi;
+  export default ConsentKit;
+  export { ConsentKit };
+  export function init(config?: CkConfig): CkState;
+  export function allowed(category: CkCategory | string): boolean;
+  export function getState(): CkState;
+  export function accept(choice?: CkAcceptArg): CkState;
+  export function rejectAll(): CkState;
+  export function withdraw(): CkState;
+  export function show(): void;
+  export function hide(): void;
+}
+
+declare module '@ecomconsult/consentkit/core' {
+  const ConsentKit: ConsentKitApi;
+  export default ConsentKit;
+  export { ConsentKit };
+  export function init(config?: CkConfig): CkState;
+  export function allowed(category: CkCategory | string): boolean;
+  export function getState(): CkState;
+  export function accept(choice?: CkAcceptArg): CkState;
+  export function rejectAll(): CkState;
+  export function withdraw(): CkState;
+  export function show(): void;
+  export function hide(): void;
+}
+
+/** Return value of `useConsent()`. */
+export interface UseConsentResult {
+  /** Current state. On the server, an undecided snapshot. */
+  state: CkState;
+  allowed(category: CkCategory | string): boolean;
+  /** Defaults to `'all'` when called with no argument. */
+  accept(choice?: CkAcceptArg): CkState;
+  rejectAll(): CkState;
+  withdraw(): CkState;
+  /** Opens the preferences panel. */
+  show(): void;
+}
+
+declare module '@ecomconsult/consentkit/react' {
+  /**
+   * Subscribes to `ck:init` / `ck:consent` / `ck:change` and re-renders on
+   * change. SSR-safe: returns `decided:false` and no-op actions on the server.
+   */
+  export function useConsent(): UseConsentResult;
+  export default useConsent;
+}

package/npm/index.mjs

@@ -0,0 +1,47 @@
+/*!
+ * consentkit — ESM entry. Side-effect: loads core, locales and UI, then
+ * re-exports the public API.
+ *
+ * Load order is contractual: ck-core.js (blocking starts at parse time) →
+ * ck-locales.js (extra language packs) → ck-ui.js (Shadow DOM layer).
+ *
+ * Only the core is DOM-optional. `src/ck-ui.js` touches `document` at module
+ * scope, so it is imported dynamically behind a `typeof document` guard —
+ * otherwise `import '@ecomconsult/consentkit'` would throw during SSR. Locales
+ * are imported dynamically too, so a build that ships without that file still
+ * works.
+ */
+
+import { resolveApi } from './internal-stub.mjs';
+
+// Static side-effect import: the core is safe in Node and must run first.
+import '../src/ck-core.js';
+
+const hasDom = typeof document !== 'undefined' && typeof window !== 'undefined';
+
+if (hasDom) {
+  // Optional: ck-locales.js may not be present in a trimmed install.
+  try {
+    await import('../src/ck-locales.js');
+  } catch (e) { /* locales are optional; ck-ui falls back to built-in en/ru */ }
+
+  // Required in the browser, fatal in Node — hence the guard above.
+  try {
+    await import('../src/ck-ui.js');
+  } catch (e) { /* UI is best-effort; the core keeps enforcing consent */ }
+}
+
+const ConsentKit = resolveApi();
+
+export default ConsentKit;
+export const {
+  init,
+  allowed,
+  getState,
+  accept,
+  rejectAll,
+  withdraw,
+  show,
+  hide
+} = ConsentKit;
+export { ConsentKit };

package/npm/internal-stub.mjs

@@ -0,0 +1,83 @@
+/*!
+ * Internal: locates the ConsentKit global, or hands back a safe no-op stub.
+ * Not a public entry point — no `exports` subpath maps here.
+ */
+
+const CATEGORIES = ['necessary', 'functional', 'analytics', 'marketing'];
+
+function emptyCategories() {
+  return { necessary: true, functional: false, analytics: false, marketing: false };
+}
+
+/** Undecided state, shape-identical to what the real core returns. */
+export function undecidedState() {
+  return {
+    decided: false,
+    id: null,
+    ts: null,
+    policyVersion: '1',
+    categories: emptyCategories(),
+    method: null
+  };
+}
+
+/**
+ * No-op API with the exact public surface, for environments where the core
+ * could not attach itself. Every method is safe to call and returns the same
+ * shape as the real one, so consumer code needs no branching.
+ */
+export function createStub() {
+  const stub = {
+    version: '0.2.0',
+    config: {},
+    init: function () { return undecidedState(); },
+    allowed: function (cat) { return cat === 'necessary'; },
+    getState: undecidedState,
+    accept: function () { return undecidedState(); },
+    rejectAll: function () { return undecidedState(); },
+    withdraw: function () { return undecidedState(); },
+    show: function () {},
+    hide: function () {},
+    _categories: CATEGORIES.slice(),
+    _isStub: true
+  };
+  return stub;
+}
+
+/**
+ * Candidate global objects, in the order the core itself prefers them.
+ *
+ * `src/ck-core.js` binds to `typeof window !== 'undefined' ? window :
+ * globalThis`, so `window` must be checked FIRST. In a browser the two are the
+ * same object and the order is moot, but under jsdom, Web Workers or an SSR
+ * DOM shim `window` is a distinct object and the API lands only there —
+ * checking `globalThis` alone would silently fall back to the stub.
+ */
+function globalCandidates() {
+  const seen = [];
+  const push = (g) => { if (g && seen.indexOf(g) === -1) seen.push(g); };
+  try { if (typeof window !== 'undefined') push(window); } catch (e) { /* noop */ }
+  try { if (typeof globalThis !== 'undefined') push(globalThis); } catch (e) { /* noop */ }
+  try { if (typeof global !== 'undefined') push(global); } catch (e) { /* noop */ }
+  try { if (typeof self !== 'undefined') push(self); } catch (e) { /* noop */ }
+  return seen;
+}
+
+/** The global object, whatever the host calls it. */
+export function getGlobal() {
+  return globalCandidates()[0];
+}
+
+/**
+ * Returns the live ConsentKit API. `src/ck-core.js` assigns it to the global at
+ * parse time; under ESM its module namespace is empty, so the global is the
+ * contract. Falls back to the stub only if the core is genuinely absent.
+ */
+export function resolveApi() {
+  const candidates = globalCandidates();
+  for (let i = 0; i < candidates.length; i++) {
+    const api = candidates[i].ConsentKit;
+    if (api && typeof api.getState === 'function') return api;
+  }
+  return createStub();
+}

package/npm/react.mjs

@@ -0,0 +1,153 @@
+/*!
+ * @ecomconsult/consentkit/react — `useConsent()` hook.
+ *
+ * React is a peerDependency (>=17), never a dependency: this file imports it,
+ * the host app provides it.
+ *
+ * Two details that are easy to get wrong and are handled here:
+ *
+ * 1. `ConsentKit.getState()` builds a NEW object on every call. Feeding that
+ *    straight to `useSyncExternalStore` makes `Object.is` fail on every render
+ *    and loops forever. The snapshot is cached in a module-level variable and
+ *    only replaced when a ck:* event actually fires.
+ * 2. On the server there is no `document` to subscribe to, so `subscribe`
+ *    no-ops and `getServerSnapshot` returns a frozen undecided state.
+ */
+
+import { useCallback, useSyncExternalStore } from 'react';
+
+import { resolveApi, undecidedState } from './internal-stub.mjs';
+
+// Side-effect import of the core only. The UI layer is intentionally NOT
+// imported here — apps that want the banner also import
+// '@ecomconsult/consentkit'.
+import '../src/ck-core.js';
+
+const EVENTS = ['ck:init', 'ck:consent', 'ck:change'];
+
+/**
+ * Evaluated per call, never cached at import time: a DOM shim (jsdom, a test
+ * harness, a hydration polyfill) may be installed after this module loads, and
+ * a captured `false` would strand the hook in its server branch forever.
+ */
+function hasDom() {
+  return typeof document !== 'undefined' && !!document.addEventListener;
+}
+
+/** Frozen, referentially stable snapshot for SSR and the first client paint. */
+const SERVER_SNAPSHOT = Object.freeze(undecidedState());
+
+function api() {
+  return resolveApi();
+}
+
+/**
+ * Cached snapshot. Replaced only inside the event listener, so `getSnapshot`
+ * returns a stable reference between events.
+ */
+let snapshot = null;
+
+function readSnapshot() {
+  // Filled on first read rather than at import time, for the same reason.
+  if (snapshot === null) {
+    snapshot = hasDom() ? api().getState() : SERVER_SNAPSHOT;
+  }
+  return snapshot;
+}
+
+function readServerSnapshot() {
+  return SERVER_SNAPSHOT;
+}
+
+/**
+ * Subscribes to the consent event bus. Returns the cleanup that removes every
+ * listener it added — React calls it on unmount and on re-subscribe.
+ */
+function subscribe(onStoreChange) {
+  if (!hasDom()) return function () {};
+
+  const handler = function () {
+    const next = api().getState();
+    // Cheap structural compare: skip the re-render when nothing really moved.
+    if (!sameState(snapshot, next)) {
+      snapshot = next;
+      onStoreChange();
+    }
+  };
+
+  EVENTS.forEach(function (name) {
+    document.addEventListener(name, handler, false);
+  });
+
+  // Close the render→subscribe gap. React reads the snapshot during render but
+  // only attaches this subscription in an effect; consent restored in between
+  // (the usual `ConsentKit.init()` in a client effect dispatching ck:init)
+  // would otherwise be missed until the next event, leaving a returning
+  // visitor rendered as undecided. `sameState` keeps the reference stable when
+  // nothing actually changed, so this never forces a spurious render.
+  handler();
+
+  return function cleanup() {
+    EVENTS.forEach(function (name) {
+      document.removeEventListener(name, handler, false);
+    });
+  };
+}
+
+function sameState(a, b) {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  if (a.decided !== b.decided || a.id !== b.id || a.ts !== b.ts) return false;
+  if (a.method !== b.method || a.policyVersion !== b.policyVersion) return false;
+  const ca = a.categories || {};
+  const cb = b.categories || {};
+  return ca.necessary === cb.necessary &&
+    ca.functional === cb.functional &&
+    ca.analytics === cb.analytics &&
+    ca.marketing === cb.marketing;
+}
+
+/**
+ * React binding for the consent state.
+ *
+ * @returns {{
+ *   state: object,
+ *   allowed: (cat: string) => boolean,
+ *   accept: (choice?: any) => object,
+ *   rejectAll: () => object,
+ *   withdraw: () => object,
+ *   show: () => void
+ * }}
+ */
+export function useConsent() {
+  const state = useSyncExternalStore(subscribe, readSnapshot, readServerSnapshot);
+
+  const allowed = useCallback(function (cat) {
+    if (!hasDom()) return cat === 'necessary';
+    try { return api().allowed(cat); } catch (e) { return false; }
+  }, []);
+
+  const accept = useCallback(function (choice) {
+    if (!hasDom()) return SERVER_SNAPSHOT;
+    return api().accept(choice === undefined ? 'all' : choice);
+  }, []);
+
+  const rejectAll = useCallback(function () {
+    if (!hasDom()) return SERVER_SNAPSHOT;
+    return api().rejectAll();
+  }, []);
+
+  const withdraw = useCallback(function () {
+    if (!hasDom()) return SERVER_SNAPSHOT;
+    return api().withdraw();
+  }, []);
+
+  const show = useCallback(function () {
+    if (!hasDom()) return;
+    api().show();
+  }, []);
+
+  return { state, allowed, accept, rejectAll, withdraw, show };
+}
+
+export default useConsent;

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@ecomconsult/consentkit",
+  "version": "0.3.2",
+  "description": "GDPR cookie consent core with blocking engine, Shadow DOM UI and Google Consent Mode v2. Zero dependencies, no build step.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vermoh/ConsentKit.git"
+  },
+  "homepage": "https://vermoh.github.io/ConsentKit/",
+  "bugs": {
+    "url": "https://github.com/vermoh/ConsentKit/issues"
+  },
+  "keywords": [
+    "gdpr",
+    "cookie",
+    "consent",
+    "cookie-banner",
+    "consent-mode",
+    "privacy"
+  ],
+  "author": "E-COM CONSULT PLUS",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": true,
+  "types": "./npm/index.d.ts",
+  "main": "./npm/index.cjs",
+  "module": "./npm/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./npm/index.d.ts",
+      "import": "./npm/index.mjs",
+      "require": "./npm/index.cjs",
+      "default": "./npm/index.mjs"
+    },
+    "./react": {
+      "types": "./npm/index.d.ts",
+      "import": "./npm/react.mjs",
+      "default": "./npm/react.mjs"
+    },
+    "./core": {
+      "types": "./npm/index.d.ts",
+      "import": "./npm/core.mjs",
+      "require": "./npm/core.cjs",
+      "default": "./npm/core.mjs"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "npm",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "react": ">=17"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=16"
+  }
+}