npm - @ecomconsult/consentkit - Versions diffs - 0.3.4 → 0.4.0 - Mend

@ecomconsult/consentkit 0.3.4 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

package/README.md CHANGED Viewed

@@ -44,7 +44,7 @@ Four ways to add ConsentKit to a site, from simplest to most integrated.
 |---|---|---|---|
 | 1 | **Script tags** — copy `src/` to your server, three `<script>` tags in `<head>` | Any site you control | [Quickstart below](#quickstart--script-tags) |
 | 2 | **npm** — `npm install @ecomconsult/consentkit` | Bundled apps, React | [Quickstart below](#quickstart--npm) |
-| 3 | **WordPress plugin** — copy the plugin folder to `wp-content/plugins/` | WordPress / WooCommerce | [`plugins/wordpress/consentkit/`](plugins/wordpress/consentkit/) |
+| 3 | **WordPress plugin** — copy the plugin folder to `wp-content/plugins/`; rewrites static tracker tags server-side | WordPress / WooCommerce | [`plugins/wordpress/consentkit/`](plugins/wordpress/consentkit/) |
 | 4 | **Google Tag Manager** — import the container, trigger tags on consent events | Sites already running GTM | [`integrations/gtm/README.md`](integrations/gtm/README.md) |
 ```sh
@@ -66,6 +66,7 @@ must come first and should not be deferred.
 ```html
 <script src="/consentkit/src/ck-core.js"></script>
 <script src="/consentkit/src/ck-locales.js"></script><!-- optional: extra languages -->
+<script src="/consentkit/src/ck-ui-branding.js"></script><!-- optional: logo / attribution -->
 <script src="/consentkit/src/ck-ui.js"></script>
 <script>
   ConsentKit.init({
@@ -188,6 +189,9 @@ Pass any subset to `init()`. Nested objects merge with the defaults.
 | `consentTtlDays` | `number` | `365` | Lifetime of the stored decision |
 | `integrations.gcm` | `boolean` | `true` | Google Consent Mode v2 signals |
 | `integrations.gtmDataLayer` | `boolean` | `true` | Push consent events to `window.dataLayer` |
+| `blocking.mode` | `"known" \| "strict"` | `"known"` | `strict` also holds back unknown third-party scripts and iframes — see [Strict mode](#strict-mode) |
+| `blocking.allow` | `string[]` | `[]` | Hosts strict mode must never intercept. Matched by suffix, so `partner.com` also covers `cdn.partner.com` |
+| `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 |
 `cookieTable` entries:
@@ -279,6 +283,11 @@ Iframes use `data-src`, which is applied once the category is allowed:
 `data-ck` accepts any category name: `functional`, `analytics`, `marketing`.
+> On WordPress this markup is applied **automatically, server-side**, for every
+> tracker in the built-in database — see "Server-side markup" below. Manual
+> markup is still needed for trackers the database does not know (your own
+> domain, an unlisted vendor) and for inline snippets.
 ### Automatic blocking
 Scripts injected at runtime are intercepted without any markup. ConsentKit
@@ -301,6 +310,130 @@ and DoubleClick.
 Because the patches install at parse time, `ck-core.js` must load before any
 tracker — put it first in `<head>` and do not add `defer`.
+`<iframe src>` is covered by the same three patches, and a blocked frame keeps
+its URL in `data-src` until its category is granted.
+### Extending the tracker database
+The built-in host list is a snapshot, not an oracle. `_extendHostDb()` merges
+extra `host: category` pairs into it at runtime:
+```js
+ConsentKit._extendHostDb({
+  'analytics.vendor.example': 'analytics',
+  'pixel.partner.example': 'marketing'
+});
+```
+Matching is the same as for built-in entries — a bare domain also covers its
+subdomains — and an override wins over the shipped classification for the same
+host. Categories outside `necessary | functional | analytics | marketing` and
+malformed hostnames are ignored; the call returns how many pairs were accepted.
+It works both **before and after** `init()`. Calling it afterwards does not
+re-examine anything already inserted (a script that has loaded cannot be
+unloaded), but every later insertion is classified against the extended map.
+In SaaS mode this is automatic: `ck-saas.js` applies `config.hostdb` from the
+service *before* it calls `init()`, and again when a background revalidation
+brings a changed table. At release time `node tools/sync-hostdb.mjs` bakes the
+same public table into `src/ck-core.js`, so inline blocks, the npm package and
+the WordPress plugin get it too.
+### Strict mode
+By default ConsentKit blocks what it **recognises**. `blocking.mode: 'strict'`
+inverts that for third parties: before consent, any `<script src>` or
+`<iframe src>` pointing at a host that is not same-site is intercepted, whether
+or not the tracker database has ever heard of it.
+```js
+ConsentKit.init({
+  blocking: { mode: 'strict', allow: ['widgets.partner.example'] }
+});
+```
+Four things are never intercepted:
+1. **Same-site URLs** — the page's own host, its subdomains, and anything
+   sharing its registrable domain. The check is deliberately conservative: when
+   the answer is unclear it says same-site, because wrongly blocking a
+   first-party asset breaks the site.
+2. **`blocking.allow`** — your own list, matched by suffix.
+3. **The built-in allowlist**, readable as `ConsentKit._baseAllow`: asset CDNs
+   (`cdn.jsdelivr.net`, `unpkg.com`, `cdnjs.cloudflare.com`, `code.jquery.com`,
+   `fonts.googleapis.com`, `fonts.gstatic.com`) and things a page is unusable
+   without (`js.stripe.com`, `pay.google.com`, `checkout.creem.io`,
+   `hcaptcha.com`, and reCAPTCHA — scoped to `www.google.com/recaptcha` and
+   `www.gstatic.com/recaptcha`, not to those hosts at large).
+4. **Known `necessary` / `functional` hosts** already granted, which keep their
+   real category rather than being swept up as marketing.
+Anything else is filed under **`marketing`** — the strictest category — and
+comes back only when the visitor accepts marketing.
+**Read this before switching it on.** Strict mode will block third-party code
+your site needs and that ConsentKit has no way to recognise as necessary: a
+booking widget, a map, a review embed, a payment provider that is not on the
+list. Turn it on, load the site with `?ck_debug=1`, and read the "Blocked until
+consent" list in the panel — entries the engine held back only because of strict
+mode are labelled `strict`. Everything there that the page genuinely needs
+belongs in `blocking.allow`.
+Two limits are worth stating plainly:
+* **Dynamic insertions only**, exactly as for known trackers. A tag written
+  straight into the HTML starts its request before ConsentKit runs (see below).
+  The WordPress plugin's server-side rewrite currently marks up *known* trackers
+  only; extending it to strict mode is recorded as a follow-up in SPEC.md.
+* **Strict starts when the config does.** The mode is read from `config`, so in
+  SaaS mode nothing is blocked strictly until the config has arrived. Blocking
+  of *known* trackers still begins at parse time, as always.
+### Static tags: what the browser cannot catch
+Runtime injection is covered by the patches above. A tracker tag written
+**directly into the HTML** is not: the parser starts that request before the
+first line of `ck-core.js` runs. The gap was measured (debt Д9: request at
+14 ms, our script at 18 ms) and it is negative — no client-side technique
+closes it. Such tags need either manual markup, or a server that rewrites them
+before the page is sent.
+### Server-side markup (WordPress plugin)
+The WordPress plugin does exactly that, and it is **on by default** since 0.3.5.
+While the page is generated, it rewrites tracker tags in the finished HTML:
+```html
+<!-- what the theme wrote -->
+<script src="https://mc.yandex.ru/metrika/tag.js"></script>
+<!-- what the browser receives -->
+<script type="text/plain" data-ck="analytics"
+        data-ck-src="https://mc.yandex.ru/metrika/tag.js"></script>
+```
+`<iframe src>` of a known host becomes `data-ck` + `data-src` with `src`
+removed. The categories come from the same HOST_DB/PATH_DB as the browser
+engine: `tools/export-hostdb.mjs` generates
+`plugins/wordpress/consentkit/includes/hostdb.php` from `src/ck-core.js`, and
+`test/hostdb.test.mjs` fails if the two drift.
+What it skips: ConsentKit's own assets, tags carrying `data-ck-ignore`, tags
+already marked up by hand, inline scripts (there is no URL to defer), the GTM
+container, and anything inside comments, `<pre>` or `<textarea>`. On any error
+the page is returned unchanged.
+The `<pre>` / `<textarea>` skip keeps the *source text* byte-identical, which is
+what a page documenting a tracker snippet needs. It does not keep such a tag
+alive: the browser parses `<pre><script src=…>` as a real script element
+whatever the server did, so the runtime engine may still intercept it. Caching plugins are compatible and get the
+already-rewritten HTML, because the rewrite happens at the PHP level before the
+page is cached.
+Outside WordPress the same idea applies to any server-side template: emit the
+`type="text/plain" data-ck` form directly, as in "Manual markup" above.
 ## Google Consent Mode v2
 With `integrations.gcm` (default), the core pushes `consent: default` with every
@@ -348,23 +481,128 @@ external requests. Rebuild them with `tools/build-inline.mjs` (see
 [`tools/README.md`](tools/README.md)); each block's header records the exact
 command that produced it.
-ConsentKit 0.3.4, rebuilt 2026-09-04, uncompressed — gzip on the server cuts
-this roughly three- to fourfold. Every block includes the attribution line;
-`--no-branding` takes ~200 bytes back off:
+ConsentKit 0.4.0, rebuilt 2026-09-05, uncompressed — gzip on the server cuts
+this roughly three- to fourfold. Every block includes the branding extension
+and the attribution line; `--no-branding` drops both the code and the config
+and takes **~24 KB** back off:
-| Block | Languages | Bytes |
-|---|---|---|
-| `ready/en-bar.txt` | en | 102,128 |
-| `ready/ru-bar.txt` | ru, en | 102,191 |
-| `ready/ru-box.txt` | ru, en | 102,206 |
-| `ready/ru-box-right.txt` | ru, en | 102,215 |
-| `ready/ru-modal.txt` | ru, en | 102,199 |
-| `ready/eu-bar.txt` | 34 languages | 152,403 |
+| Block | Languages | Bytes | gzip | `--no-branding` |
+|---|---|---|---|---|
+| `ready/en-bar.txt` | en | 134,969 | 40,519 | 110,907 |
+| `ready/ru-bar.txt` | ru, ro, en | 136,590 | 41,315 | 112,508 |
+| `ready/ru-box.txt` | ru, ro, en | 136,605 | 41,320 | 112,523 |
+| `ready/ru-box-right.txt` | ru, ro, en | 136,614 | 41,326 | 112,526 |
+| `ready/ru-modal.txt` | ru, ro, en | 136,598 | 41,318 | 112,514 |
+| `ready/eu-bar.txt` | 34 languages | 185,244 | 59,665 | 161,182 |
+0.4.0 adds roughly 16.1 KB over 0.3.6: iframe interception, strict mode
+(same-site detection, the allowlists, the public-suffix table) and the
+extensible tracker database.
 Size is driven almost entirely by the bundled languages: `en` and `ru` are
 built into the UI and cost nothing extra, while layout, position, theme and
 accent change only a few bytes of config.
+The debug panel is **not** in these numbers. Blocks carry a ~5.1 KB loader
+(`src/ck-debug-loader.js`) which fetches the 33 KB panel only when someone opens
+the page with `?ck_debug=1` — see [Debug mode](#debug-mode). An ordinary visitor
+downloads the loader and nothing more.
+## Debug mode
+A panel that shows what the client actually did on a live page — useful when a
+site owner asks "is this thing working?" and screenshots of the banner do not
+answer it.
+**Open it** by adding `?ck_debug=1` to the page URL (`#ck_debug` works too):
+```
+https://example.com/?ck_debug=1
+```
+A dark, monospace panel appears bottom-right in its own Shadow DOM. The flag is
+remembered in `localStorage` for that browser, so it survives navigation.
+**It shows**, in order: the client version, config source (SaaS or inline),
+siteId and policy version / ETag; the consent status, granted categories,
+decision time and cookie lifetime; what the blocking engine is holding back
+(`ConsentKit._blocked()`); which requests to known trackers actually left the
+page, each marked *before* or *after* consent; the recent `ck_*` dataLayer
+events and `gtag('consent', …)` calls; and three buttons — reset consent
+(withdraw, clear the cookie, reload), open preferences, and copy a JSON report.
+The request list carries the same caveat as the blocking engine itself:
+requests that left **before** ck-core.js parsed — a plain `<script src>` written
+into the HTML — show up there but could not have been blocked. Mark those tags
+up manually.
+**Turn it off** with `?ck_debug=0`, or the × in the panel's header. The loader
+owns the stored flag, so `?ck_debug=0` clears it whether or not the panel is on
+the page.
+**Privacy.** Nothing is sent anywhere: the panel is local to that browser and
+that page. It never renders cookie *values* (names only) and never shows URL
+query strings (host and path only), so the copied report is safe to paste into
+a support ticket.
+### How the panel gets onto the page
+The panel is ~33 KB, and on any given page exactly one person will ever open
+it. So `ready/*.txt` and the WordPress plugin ship **`src/ck-debug-loader.js`**
+(~5.1 KB) instead, and the loader fetches the panel on demand. With no flag set
+the loader creates no DOM, installs no observers and makes **no network
+request** — it costs its own bytes and nothing else.
+When the panel *is* activated, the loader resolves its URL in this order, first
+match wins:
+1. **`window.ConsentKitDebugUrl`**, if you set it — a self-hosted copy, an
+   internal mirror, or a pinned build. Set it before the loader runs.
+2. **`<API_BASE>/client/ck-debug.js`**, when `ck-saas.js` is on the page with a
+   site id — `API_BASE` is that loader's `data-ck-api` (its `ConsentKit._saas.api`).
+   The panel then comes from the same origin as the config, so a locked-down CSP
+   needs no extra host. **A SaaS deployment is expected to serve the panel at
+   that path**; if yours does not, set `window.ConsentKitDebugUrl` instead.
+3. **jsDelivr**, pinned to the running core version:
+   `https://cdn.jsdelivr.net/npm/@ecomconsult/consentkit@<version>/src/ck-debug.js`.
+   The version comes from `ConsentKit.version`, so the panel can never be newer
+   or older than the client it is reporting on. This path is published because
+   `package.json` lists `src` in `files`.
+The script is injected `async`, and neither jsDelivr nor a ConsentKit API host
+is in the blocking engine's tracker list, so the panel loads even while the
+visitor has yet to decide.
+### Loading the panel directly
+If you host the files yourself and would rather have the panel inline, load it
+after `ck-ui.js` (and after `ck-saas.js` if you use it) and skip the loader:
+```html
+<script src="/js/ck-core.js"></script>
+<script src="/js/ck-locales.js"></script>
+<script src="/js/ck-ui.js"></script>
+<script src="/js/ck-debug.js"></script>
+```
+`ck-debug.js` is self-contained: it repeats the loader's activation check, so it
+works with or without the loader. Do **not** add it to a page that already ships
+the loader (an inline block from `ready/`, or the WordPress plugin) — the loader
+fetches the panel itself, and a second copy would mount a second panel.
+From npm it is a deliberate opt-in — `@ecomconsult/consentkit` does not pull
+it in for you. Import it yourself, after the UI:
+```js
+import '@ecomconsult/consentkit';           // core + locales + UI
+import '@ecomconsult/consentkit/src/ck-debug.js';
+```
+**Language.** The panel is Russian or English: it follows the banner's
+configured `language`, falls back to `navigator.language` (`ru-*` → Russian),
+and otherwise renders English. The JSON report it copies is language-neutral
+whichever way the panel reads.
 ## TypeScript
 Types ship with the package; no `@types` needed.
@@ -440,13 +678,19 @@ has been verified and what has not.
 - `dataLayer` event trace for consent restore, upgrade and withdrawal.
 - npm entry points and TypeScript types: syntax and import smoke tests in Node
   without a DOM.
-- PHP files of the WordPress plugin pass `php -l` on 7.4 and 8.5.
+- PHP files of the WordPress plugin pass `php -l` on 7.4, 8.3 and 8.5.
+- The server-side rewriting engine has its own suite of 61 cases
+  (`plugins/wordpress/consentkit/tests/rewrite.test.php`), green on PHP 7.4,
+  8.3 and 8.5. It is a plain PHP CLI script, so it runs outside `npm test`.
 ### Not verified — read before production use
-- **The WordPress plugin has never run on a live WordPress install.** It passes
-  linting and review, but no activation, settings round-trip, theme conflict or
-  multisite behaviour has been observed in a real installation.
+- **The WordPress plugin has been verified on a live install, but only one.**
+  It was run on WordPress 7.1 / PHP 8.3 in Docker (activation, settings
+  round-trip, shortcode, uninstall, server-side markup end to end). The declared
+  floor of WordPress 6.0 / PHP 7.4 has not been exercised live — the PHP files
+  pass `php -l` and the rewriting test suite on 7.4, 8.3 and 8.5 — and no theme
+  conflict or multisite behaviour has been observed.
 - **The GTM container has never been through a real import.** The JSON is valid
   and structurally modelled on the documented export format, but Tag Manager has
   not accepted it in practice; some field names (notably GA4 config

package/npm/core.cjs CHANGED Viewed

@@ -21,7 +21,7 @@ function undecidedState() {
 function createStub() {
   return {
-    version: '0.3.4',
+    version: '0.3.5',
     config: {},
     init: function () { return undecidedState(); },
     allowed: function (cat) { return cat === 'necessary'; },

package/npm/core.mjs CHANGED Viewed

@@ -28,6 +28,9 @@ export const {
   rejectAll,
   withdraw,
   show,
-  hide
+  hide,
+  // v0.4.0 (§1.3): merging service overrides into the tracker database is part
+  // of the public surface, so it must be reachable as a named import too.
+  _extendHostDb
 } = ConsentKit;
 export { ConsentKit };

package/npm/index.cjs CHANGED Viewed

@@ -24,7 +24,7 @@ function undecidedState() {
 function createStub() {
   return {
-    version: '0.3.4',
+    version: '0.3.5',
     config: {},
     init: function () { return undecidedState(); },
     allowed: function (cat) { return cat === 'necessary'; },
@@ -69,7 +69,10 @@ var hasDom = typeof document !== 'undefined' && typeof window !== 'undefined';
 if (hasDom) {
   // 2. Locales — optional language packs.
   try { require('../src/ck-locales.js'); } catch (e) { /* optional */ }
-  // 3. UI — touches `document` at module scope, browser only.
+  // 3. Branding — optional, and before the UI: it registers itself on
+  //    ConsentKit._uiExtensions and must be there before the first mount().
+  try { require('../src/ck-ui-branding.js'); } catch (e) { /* optional */ }
+  // 4. UI — touches `document` at module scope, browser only.
   try { require('../src/ck-ui.js'); } catch (e) { /* best effort */ }
 }

package/npm/index.d.ts CHANGED Viewed

@@ -88,6 +88,20 @@ export interface CkIntegrationsConfig {
   gtmDataLayer?: boolean;
 }
+/** v0.4.0 (§2). How much the blocking engine holds back before consent. */
+export interface CkBlockingConfig {
+  /**
+   * `'known'` (default) blocks what the tracker database recognises.
+   * `'strict'` additionally intercepts EVERY third-party `<script src>` and
+   * `<iframe src>` that is not same-site, not in `allow`, not in the built-in
+   * allowlist (`ConsentKit._baseAllow`) and not an already-granted
+   * necessary/functional host. Interceptions are filed under `marketing`.
+   */
+  mode?: 'known' | 'strict';
+  /** Hosts strict mode must never intercept. Suffix match: `p.com` covers `cdn.p.com`. */
+  allow?: string[];
+}
 /** One declared cookie, shown under its category in the preferences panel. */
 export interface CkCookieTableEntry {
   name: string;
@@ -109,6 +123,15 @@ export interface CkConfig {
   /** Lifetime of the stored decision, in days. Default `365`. */
   consentTtlDays?: number;
   integrations?: CkIntegrationsConfig;
+  /** v0.4.0. Default `{ mode: 'known', allow: [] }`. */
+  blocking?: CkBlockingConfig;
+  /**
+   * v0.4.0 (§1.3). Extra `host: category` pairs merged into the tracker
+   * database. `init()` applies them before its initial scan, so scripts
+   * already in the markup are classified against them. In SaaS mode the
+   * service supplies this; `_extendHostDb()` does the same at any later point.
+   */
+  hostdb?: Record<string, CkCategory>;
   cookieTable?: CkCookieTableEntry[];
 }
@@ -141,6 +164,50 @@ export interface ConsentKitApi {
   show(): void;
   /** Dispatches `ck:ui:close`. */
   hide(): void;
+  /**
+   * v0.4.0 (§1.3). Merges `{ host: category }` into the runtime tracker
+   * database and returns how many pairs were accepted. Matching follows the
+   * built-in table: a bare domain also covers its subdomains, and an override
+   * wins over the shipped classification for the same host.
+   *
+   * Safe before AND after `init()`. Afterwards, nothing already inserted is
+   * re-examined — a script that has loaded cannot be unloaded — but every
+   * later insertion is classified against the extended map.
+   */
+  _extendHostDb(map: Record<string, CkCategory>): number;
+  /**
+   * v0.4.0 (§2). The built-in strict-mode allowlist, as hosts plus a few
+   * `host/path` entries (reCAPTCHA). A copy: mutating it changes nothing.
+   */
+  readonly _baseAllow: string[];
+  /** The category the engine would assign to a URL, or `null` if unknown. */
+  _categoryForUrl(url: string): CkCategory | null;
+  /** What is currently held back, host+path only — never a query string. */
+  _blocked(): CkBlockedEntry[];
+}
+/** One entry of `ConsentKit._blocked()`. */
+export interface CkBlockedEntry {
+  host: string;
+  path: string;
+  /** `'script'`, `'iframe'`, … */
+  kind: string;
+  category: CkCategory | null;
+  /** `'engine'` — intercepted by the patches; `'markup'` — marked up by hand. */
+  origin: 'engine' | 'markup';
+  /** v0.4.0. True when strict mode held this back, i.e. the host is unknown. */
+  strict: boolean;
+  /**
+   * v0.4.0. `false` when the category was granted but the element still never
+   * loaded — typically a script created and given a `src` without ever being
+   * appended, which `applyConsentToDom()` cannot reach. Such entries stay in
+   * the report after consent precisely so they can be diagnosed.
+   */
+  revived: boolean;
 }
 declare const ConsentKit: ConsentKitApi;
@@ -156,6 +223,7 @@ export declare function rejectAll(): CkState;
 export declare function withdraw(): CkState;
 export declare function show(): void;
 export declare function hide(): void;
+export declare function _extendHostDb(map: Record<string, CkCategory>): number;
 declare global {
   interface Window {

package/npm/index.mjs CHANGED Viewed

@@ -3,7 +3,9 @@
  * 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).
+ * ck-locales.js (extra language packs) → ck-ui-branding.js (optional logo /
+ * attribution extension, which must register before the UI mounts) →
+ * 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 —
@@ -25,6 +27,13 @@ if (hasDom) {
     await import('../src/ck-locales.js');
   } catch (e) { /* locales are optional; ck-ui falls back to built-in en/ru */ }
+  // Optional branding extension. Before ck-ui.js on purpose: it registers
+  // itself on ConsentKit._uiExtensions and must be there before the first
+  // mount(). Absent, the UI simply draws no logo and no attribution line.
+  try {
+    await import('../src/ck-ui-branding.js');
+  } catch (e) { /* branding is optional; the UI renders without it */ }
   // Required in the browser, fatal in Node — hence the guard above.
   try {
     await import('../src/ck-ui.js');
@@ -42,6 +51,9 @@ export const {
   rejectAll,
   withdraw,
   show,
-  hide
+  hide,
+  // v0.4.0 (§1.3): merging service overrides into the tracker database is part
+  // of the public surface, so it must be reachable as a named import too.
+  _extendHostDb
 } = ConsentKit;
 export { ConsentKit };

package/npm/internal-stub.mjs CHANGED Viewed

@@ -28,7 +28,7 @@ export function undecidedState() {
  */
 export function createStub() {
   const stub = {
-    version: '0.3.4',
+    version: '0.4.0',
     config: {},
     init: function () { return undecidedState(); },
     allowed: function (cat) { return cat === 'necessary'; },
@@ -39,6 +39,12 @@ export function createStub() {
     show: function () {},
     hide: function () {},
     _categories: CATEGORIES.slice(),
+    // v0.4.0: the stub mirrors the real surface, so consumer code that calls
+    // these needs no branching when the core failed to attach.
+    _extendHostDb: function () { return 0; },
+    _baseAllow: [],
+    _categoryForUrl: function () { return null; },
+    _blocked: function () { return []; },
     _isStub: true
   };
   return stub;

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@ecomconsult/consentkit",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "GDPR cookie consent core with blocking engine, Shadow DOM UI and Google Consent Mode v2. Zero dependencies, no build step.",
   "repository": {
     "type": "git",