@ecomconsult/consentkit 0.5.7 → 0.5.9

package/README.md

@@ -199,6 +199,7 @@ Pass any subset to `init()`. Nested objects merge with the defaults.
 | `blocking.placeholders` | `boolean` | `true` | v0.5.7. Draw a card in place of an embed held back before consent — see [Placeholders for blocked embeds](#placeholders-for-blocked-embeds). `false` restores the pre-0.5.7 behaviour: the frame is still blocked, just invisible |
 | `hostdb` | `Record<string, Category>` | — | Extra `host: category` pairs merged into the tracker database, applied before the initial scan. SaaS mode fills this from the service; `ConsentKit._extendHostDb()` does the same at any later point |
 | `cookieTable` | `CkCookieTableEntry[]` | `[]` | Declared cookies, listed per category in the panel |
+| `services` | `CkService[]` | `[]` | v0.5.8. Third-party services the site declares. Each gets its own toggle inside its category group in the panel, and can be refused individually — see [Services](#services). At most 50 |
 
 `cookieTable` entries:
 
@@ -206,6 +207,45 @@ Pass any subset to `init()`. Nested objects merge with the defaults.
 { name: '_ga', category: 'analytics', vendor: 'Google', purpose: 'Visit statistics', expiry: '2 years' }
 ```
 
+### Services
+
+**v0.5.8.** A `services` row names one third party: where its resources come
+from, which cookies it sets and what it is for. The preferences panel lists it
+inside its category group with **its own toggle**, so a visitor can accept
+analytics in general and still refuse one particular service.
+
+```js
+services: [{
+  id: 'hotjar',                                   // stable, ^[a-z0-9-]{1,64}$
+  name: 'Hotjar',
+  vendor: 'Hotjar Ltd',
+  category: 'analytics',
+  hosts: ['hotjar.com'],                          // suffix-matched, like the tracker database
+  paths: ['/hotjar-'],                            // optional, substring-matched
+  cookies: ['_hjSession', '_hjSessionUser'],      // names; matched against cookieTable
+  privacyUrl: 'https://www.hotjar.com/privacy/',  // http(s) only
+  purpose: { ru: '…', ro: '…', en: 'Records how visitors move around the page.' },
+  enabled: true                                   // false: not shown, not blocked separately
+}]
+```
+
+What the toggle does:
+
+- **Group off** — every service of that group is off and blocked, as before.
+- **Group on** — the services come back, *except* the ones the visitor switched
+  off by hand. A refusal survives the group being switched off and on again.
+- A refused service's resources are held back exactly as if its category had no
+  consent, and its cookies are deleted exactly as on a category withdrawal.
+- The «Allow and show» button on a blocked embed's placeholder grants the
+  category **and** clears the refusal on that frame's service.
+
+`hosts` need not already be in the tracker database: `init()` folds them into
+the block map under the row's own category, so a service host ConsentKit has
+never heard of is still held back.
+
+Refusals are stored in `ck_consent` as `services: { '<id>': false }` — denials
+only. An id absent from the map is allowed, subject to its category.
+
 ### Button appearance
 
 Each of the three banner buttons can be styled independently:
@@ -361,9 +401,10 @@ All methods are safe to call at any time and never throw.
 |---|---|---|
 | `init(config?)` | `CkState` | Idempotent. Restores stored consent, then dispatches `ck:init`. Calling again merges config only |
 | `allowed(category)` | `boolean` | `necessary` is always `true` |
+| `allowedService(id)` | `boolean` | v0.5.8. May this one declared service run? True when its category is granted **and** the visitor has not refused it individually. An id the config does not declare is `true` |
 | `getState()` | `CkState` | A fresh object on every call |
 | `accept('all')` | `CkState` | Grants everything. `method: 'accept_all'` |
-| `accept({ ... })` | `CkState` | Per-category choice. `method: 'custom'`. Omitted categories stay denied |
+| `accept({ ... })` | `CkState` | Per-category choice. `method: 'custom'`. Omitted categories stay denied. v0.5.8: an optional `services: { '<id>': false }` replaces the stored refusals wholesale; omit it to leave them untouched |
 | `rejectAll()` | `CkState` | Denies every opt-in category. `method: 'reject_all'` |
 | `withdraw()` | `CkState` | Clears storage and known cookies, sends GCM `denied`, resets to `decided: false` |
 | `show()` | `void` | Opens the preferences panel |
@@ -381,6 +422,7 @@ All methods are safe to call at any time and never throw.
   ts: null,                // ISO timestamp
   policyVersion: '1',
   categories: { necessary: true, functional: false, analytics: false, marketing: false },
+  services: {},            // v0.5.8. Per-service refusals ONLY: { hotjar: false }
   method: null             // 'accept_all' | 'reject_all' | 'custom'
 }
 ```

package/npm/core.cjs

@@ -25,6 +25,9 @@ function createStub() {
     config: {},
     init: function () { return undecidedState(); },
     allowed: function (cat) { return cat === 'necessary'; },
+    // v0.5.8 (SPEC V1.12 §3). `true`: a stub means the engine never attached
+    // and withholds nothing, so it must not claim a refusal it cannot enforce.
+    allowedService: function () { return true; },
     getState: undecidedState,
     accept: function () { return undecidedState(); },
     rejectAll: function () { return undecidedState(); },

package/npm/core.mjs

@@ -23,6 +23,10 @@ export default ConsentKit;
 export const {
   init,
   allowed,
+  // v0.5.8 (SPEC V1.12 §3): «may this ONE declared service run?» — the category
+  // check plus the visitor's per-service refusal, which getState() alone cannot
+  // reconstruct. Part of the public surface, so it is a named import too.
+  allowedService,
   getState,
   accept,
   rejectAll,

package/npm/index.cjs

@@ -28,6 +28,9 @@ function createStub() {
     config: {},
     init: function () { return undecidedState(); },
     allowed: function (cat) { return cat === 'necessary'; },
+    // v0.5.8 (SPEC V1.12 §3). `true`: a stub means the engine never attached
+    // and withholds nothing, so it must not claim a refusal it cannot enforce.
+    allowedService: function () { return true; },
     getState: undecidedState,
     accept: function () { return undecidedState(); },
     rejectAll: function () { return undecidedState(); },

package/npm/index.d.ts

@@ -34,11 +34,26 @@ export interface CkState {
   /** Policy version the decision was recorded against. */
   policyVersion: string;
   categories: CkCategories;
+  /**
+   * v0.5.8 (SPEC V1.12 §3). Per-service refusals, and ONLY refusals:
+   * `{ 'hotjar': false }`. An id absent from the map is allowed, subject to its
+   * category. A denial survives its category being switched off and back on.
+   */
+  services: Record<string, false>;
   method: CkMethod;
 }
 
 /** Argument to `accept()`: `'all'`, or an explicit per-category selection. */
-export type CkAcceptArg = 'all' | Partial<Record<CkOptInCategory, boolean>>;
+export type CkAcceptArg =
+  | 'all'
+  | (Partial<Record<CkOptInCategory, boolean>> & {
+      /**
+       * v0.5.8 (SPEC V1.12 §3). The FULL per-service refusal map for this
+       * decision — it replaces the stored one wholesale. Omit it to leave
+       * the existing refusals untouched.
+       */
+      services?: Record<string, false>;
+    });
 
 /** Banner placement. `bar` uses bottom/top; `box` uses the corner positions. */
 export type CkLayoutType = 'bar' | 'modal' | 'box';
@@ -196,6 +211,31 @@ export interface CkCookieTableEntry {
   expiry?: string;
 }
 
+/**
+ * v0.5.8 (SPEC V1.12 §2). One declared third-party service.
+ *
+ * `hosts` are suffix-matched (a bare domain also covers its subdomains) and
+ * `paths` are matched as case-insensitive substrings of the resolved URL —
+ * the same two rules the built-in tracker database uses.
+ */
+export interface CkService {
+  /** Stable kebab-case id, `^[a-z0-9-]{1,64}$`. */
+  id: string;
+  name: string;
+  vendor: string;
+  category: CkCategory;
+  hosts: string[];
+  paths?: string[];
+  /** Cookie names, matched against `cookieTable` to list them under the service. */
+  cookies: string[];
+  /** `http(s)` only; anything else is dropped rather than rendered as a link. */
+  privacyUrl?: string;
+  /** One line for the visitor, per language. Falls back to `en`. */
+  purpose?: { ru?: string; ro?: string; en?: string };
+  /** Default `true`. `false` hides the row and stops blocking it separately. */
+  enabled?: boolean;
+}
+
 /** Configuration accepted by `init()`. Every field is optional. */
 export interface CkConfig {
   /** Bump to invalidate stored decisions and re-show the banner. Default `'1'`. */
@@ -220,6 +260,17 @@ export interface CkConfig {
    */
   hostdb?: Record<string, CkCategory>;
   cookieTable?: CkCookieTableEntry[];
+  /**
+   * v0.5.8 (SPEC V1.12 §2/§3). The third-party services this site declares.
+   * Each row gets its own switch inside its category group in the preferences
+   * panel, and the engine can hold back that one service while the rest of the
+   * category runs. At most 50 rows; a row with `enabled: false` is neither
+   * shown nor blocked separately.
+   *
+   * `hosts` need not be in the built-in tracker database — `init()` folds them
+   * into the block map under the row's own category.
+   */
+  services?: CkService[];
 }
 
 /** Detail payload of `ck:init`. */
@@ -241,6 +292,13 @@ export interface ConsentKitApi {
   /** Idempotent. Restores stored state, then dispatches `ck:init`. */
   init(config?: CkConfig): CkState;
   allowed(category: CkCategory | string): boolean;
+  /**
+   * v0.5.8 (SPEC V1.12 §3). May this one declared service run? True when its
+   * category is granted AND the visitor has not switched it off individually —
+   * a combination `getState().categories` alone cannot reconstruct. An id the
+   * config does not declare answers `true`.
+   */
+  allowedService(id: string): boolean;
   getState(): CkState;
   /** `accept('all')` grants everything; an object records `method: 'custom'`. */
   accept(choice?: CkAcceptArg): CkState;
@@ -396,6 +454,8 @@ export { ConsentKit };
 
 export declare function init(config?: CkConfig): CkState;
 export declare function allowed(category: CkCategory | string): boolean;
+/** v0.5.8 (SPEC V1.12 §3). */
+export declare function allowedService(id: string): boolean;
 export declare function getState(): CkState;
 export declare function accept(choice?: CkAcceptArg): CkState;
 export declare function rejectAll(): CkState;
@@ -427,6 +487,8 @@ declare module '@ecomconsult/consentkit' {
   export { ConsentKit };
   export function init(config?: CkConfig): CkState;
   export function allowed(category: CkCategory | string): boolean;
+  /** v0.5.8 (SPEC V1.12 §3). */
+  export function allowedService(id: string): boolean;
   export function getState(): CkState;
   export function accept(choice?: CkAcceptArg): CkState;
   export function rejectAll(): CkState;
@@ -442,6 +504,8 @@ declare module '@ecomconsult/consentkit/core' {
   export { ConsentKit };
   export function init(config?: CkConfig): CkState;
   export function allowed(category: CkCategory | string): boolean;
+  /** v0.5.8 (SPEC V1.12 §3). */
+  export function allowedService(id: string): boolean;
   export function getState(): CkState;
   export function accept(choice?: CkAcceptArg): CkState;
   export function rejectAll(): CkState;
@@ -456,6 +520,8 @@ export interface UseConsentResult {
   /** Current state. On the server, an undecided snapshot. */
   state: CkState;
   allowed(category: CkCategory | string): boolean;
+  /** v0.5.8 (SPEC V1.12 §3). May this one declared service run? */
+  allowedService(id: string): boolean;
   /** Defaults to `'all'` when called with no argument. */
   accept(choice?: CkAcceptArg): CkState;
   rejectAll(): CkState;

package/npm/index.mjs

@@ -46,6 +46,10 @@ export default ConsentKit;
 export const {
   init,
   allowed,
+  // v0.5.8 (SPEC V1.12 §3): «may this ONE declared service run?» — the category
+  // check plus the visitor's per-service refusal, which getState() alone cannot
+  // reconstruct. Part of the public surface, so it is a named import too.
+  allowedService,
   getState,
   accept,
   rejectAll,

package/npm/internal-stub.mjs

@@ -28,10 +28,15 @@ export function undecidedState() {
  */
 export function createStub() {
   const stub = {
-    version: '0.5.7',
+    version: '0.5.9',
     config: {},
     init: function () { return undecidedState(); },
     allowed: function (cat) { return cat === 'necessary'; },
+    // v0.5.8 (SPEC V1.12 §3): may this one declared service run? `true` here
+    // for the same reason the real core answers `true` for an unknown id — a
+    // stub means the engine never attached and is withholding nothing, so
+    // claiming a refusal it does not enforce would be a lie consumer code acts on.
+    allowedService: function () { return true; },
     getState: undecidedState,
     accept: function () { return undecidedState(); },
     rejectAll: function () { return undecidedState(); },
@@ -51,6 +56,11 @@ export function createStub() {
     _infra: function () { return []; },
     _isInfra: function () { return false; },
     _blocked: function () { return []; },
+    // v0.5.8 (SPEC V1.12 §3): the service registry. Empty for the same reason
+    // _baseAllow and _infra are — nothing was normalised, nothing is blocked.
+    _serviceForUrl: function () { return null; },
+    _services: function () { return []; },
+    _deniedServices: function () { return []; },
     _isStub: true
   };
   return stub;

package/npm/react.mjs

@@ -113,6 +113,7 @@ function sameState(a, b) {
  * @returns {{
  *   state: object,
  *   allowed: (cat: string) => boolean,
+ *   allowedService: (id: string) => boolean,
  *   accept: (choice?: any) => object,
  *   rejectAll: () => object,
  *   withdraw: () => object,
@@ -127,6 +128,14 @@ export function useConsent() {
     try { return api().allowed(cat); } catch (e) { return false; }
   }, []);
 
+  /* v0.5.8 (SPEC V1.12 §3). On the server there is no stored decision and no
+     service registry, so nothing is being withheld — `true`, matching what the
+     core answers for an id it does not know. */
+  const allowedService = useCallback(function (id) {
+    if (!hasDom()) return true;
+    try { return api().allowedService(id); } catch (e) { return true; }
+  }, []);
+
   const accept = useCallback(function (choice) {
     if (!hasDom()) return SERVER_SNAPSHOT;
     return api().accept(choice === undefined ? 'all' : choice);
@@ -147,7 +156,7 @@ export function useConsent() {
     api().show();
   }, []);
 
-  return { state, allowed, accept, rejectAll, withdraw, show };
+  return { state, allowed, allowedService, accept, rejectAll, withdraw, show };
 }
 
 export default useConsent;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecomconsult/consentkit",
-  "version": "0.5.7",
+  "version": "0.5.9",
   "description": "GDPR cookie consent core with blocking engine, Shadow DOM UI and Google Consent Mode v2. Zero dependencies, no build step.",
   "repository": {
     "type": "git",
@@ -21,7 +21,8 @@
   "author": "E-COM CONSULT PLUS",
   "license": "MIT",
   "scripts": {
-    "test": "node --test test/*.test.mjs"
+    "test": "node --test test/*.test.mjs",
+    "build": "node tools/build-inline.mjs --langs=ru,ro,en --language=auto --layout=bar --position=bottom --accent=#2B50D8 --mode=auto --policy=1 --out=ready/ru-bar.txt && node tools/build-inline.mjs --langs=ru,ro,en --language=auto --layout=box --position=bottom-left --accent=#2B50D8 --mode=auto --policy=1 --out=ready/ru-box.txt && node tools/build-inline.mjs --langs=ru,ro,en --language=auto --layout=box --position=bottom-right --accent=#2B50D8 --mode=auto --policy=1 --out=ready/ru-box-right.txt && node tools/build-inline.mjs --langs=ru,ro,en --language=auto --layout=modal --position=bottom --accent=#2B50D8 --mode=auto --policy=1 --out=ready/ru-modal.txt && node tools/build-inline.mjs --langs=en --language=en --layout=bar --position=bottom --accent=#2B50D8 --mode=auto --policy=1 --out=ready/en-bar.txt && node tools/build-inline.mjs --langs=bg,ca,cs,da,de,el,en,es,et,fi,fr,ga,hr,hu,is,it,lt,lv,mk,mt,nb,nl,no,pl,pt,ro,ru,sk,sl,sq,sr,sv,tr,uk --language=auto --layout=bar --position=bottom --accent=#2B50D8 --mode=auto --policy=1 --out=ready/eu-bar.txt && node tools/export-hostdb.mjs && node tools/sync-site.mjs && node tools/build-site.mjs && cp -f src/ck-core.js src/ck-locales.js src/ck-ui-branding.js src/ck-ui.js src/ck-debug-loader.js plugins/wordpress/consentkit/assets/"
   },
   "type": "module",
   "sideEffects": true,