npm - @freshjuice/zest - Versions diffs - 2.0.0 → 2.2.0 - Mend

@freshjuice/zest 2.0.0 → 2.2.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 (53) hide show

package/dist/zest.d.ts +247 -0
package/dist/zest.de.js +107 -3
package/dist/zest.de.js.map +1 -1
package/dist/zest.de.min.js +1 -1
package/dist/zest.en.js +107 -3
package/dist/zest.en.js.map +1 -1
package/dist/zest.en.min.js +1 -1
package/dist/zest.es.js +107 -3
package/dist/zest.es.js.map +1 -1
package/dist/zest.es.min.js +1 -1
package/dist/zest.esm.js +107 -3
package/dist/zest.esm.js.map +1 -1
package/dist/zest.esm.min.js +1 -1
package/dist/zest.fr.js +107 -3
package/dist/zest.fr.js.map +1 -1
package/dist/zest.fr.min.js +1 -1
package/dist/zest.headless.d.ts +211 -0
package/dist/zest.headless.esm.js +107 -3
package/dist/zest.headless.esm.js.map +1 -1
package/dist/zest.headless.esm.min.js +1 -1
package/dist/zest.it.js +107 -3
package/dist/zest.it.js.map +1 -1
package/dist/zest.it.min.js +1 -1
package/dist/zest.ja.js +107 -3
package/dist/zest.ja.js.map +1 -1
package/dist/zest.ja.min.js +1 -1
package/dist/zest.js +107 -3
package/dist/zest.js.map +1 -1
package/dist/zest.min.js +1 -1
package/dist/zest.nl.js +107 -3
package/dist/zest.nl.js.map +1 -1
package/dist/zest.nl.min.js +1 -1
package/dist/zest.pl.js +107 -3
package/dist/zest.pl.js.map +1 -1
package/dist/zest.pl.min.js +1 -1
package/dist/zest.pt.js +107 -3
package/dist/zest.pt.js.map +1 -1
package/dist/zest.pt.min.js +1 -1
package/dist/zest.ru.js +107 -3
package/dist/zest.ru.js.map +1 -1
package/dist/zest.ru.min.js +1 -1
package/dist/zest.uk.js +107 -3
package/dist/zest.uk.js.map +1 -1
package/dist/zest.uk.min.js +1 -1
package/dist/zest.zh.js +107 -3
package/dist/zest.zh.js.map +1 -1
package/dist/zest.zh.min.js +1 -1
package/package.json +9 -2
package/src/config/defaults.js +48 -0
package/src/core/pattern-matcher.js +37 -0
package/src/core-lifecycle.js +23 -4
package/src/types/zest.d.ts +247 -0
package/src/types/zest.headless.d.ts +211 -0

package/dist/zest.d.ts ADDED Viewed

@@ -0,0 +1,247 @@
+/**
+ * Type definitions for `@freshjuice/zest` (full build with UI).
+ *
+ * The full build ships the consent engine plus a Shadow-DOM banner,
+ * settings modal, and floating widget. It auto-initialises on script
+ * load when included via `<script>`, or you can drive it manually via
+ * `Zest.init()`.
+ *
+ * For a logic-only build without UI, import from
+ * `@freshjuice/zest/headless` instead.
+ *
+ * @example
+ * ```ts
+ * import Zest from '@freshjuice/zest';
+ *
+ * Zest.init({
+ *   position: 'bottom-right',
+ *   theme: 'auto',
+ *   accentColor: '#0071e3',
+ *   policyUrl: '/privacy'
+ * });
+ * ```
+ */
+/** Built-in consent categories. */
+export type ConsentCategory =
+  | 'essential'
+  | 'functional'
+  | 'analytics'
+  | 'marketing';
+/**
+ * Per-category boolean consent state. `essential` is always `true` —
+ * consent for it cannot be revoked because it covers strictly-necessary
+ * processing.
+ */
+export type ConsentState =
+  & Partial<Record<ConsentCategory, boolean>>
+  & { essential: true };
+/** Snapshot returned by `init()`. */
+export interface InitSnapshot {
+  consent: ConsentState;
+  hasDecision: boolean;
+  dntApplied: boolean;
+}
+/** Tamper-evident proof of the user's last consent decision. */
+export interface ConsentProof {
+  version: string;
+  timestamp: number;
+  categories: ConsentState;
+}
+/** Output of `getDNTDetails()`. */
+export interface DNTDetails {
+  dnt: boolean;
+  gpc: boolean;
+  doNotTrack: string | null;
+  globalPrivacyControl: boolean;
+}
+/** Behaviour when DNT / GPC is detected at init time. */
+export type DNTBehavior = 'reject' | 'preselect' | 'ignore';
+/** Banner position on the page. */
+export type BannerPosition = 'bottom' | 'bottom-left' | 'bottom-right' | 'top';
+/** UI theme. `auto` follows `prefers-color-scheme`. */
+export type ZestTheme = 'light' | 'dark' | 'auto';
+/** Script-blocking strictness. */
+export type ZestMode = 'manual' | 'safe' | 'strict' | 'doomsday';
+/**
+ * Optional consumer callbacks. Each is wrapped in a try/catch internally
+ * so a thrown error never breaks the consent pipeline.
+ */
+export interface ZestCallbacks {
+  onAccept?: (consent: ConsentState) => void;
+  onReject?: (consent: ConsentState) => void;
+  onChange?: (consent: ConsentState) => void;
+  onReady?: (consent: ConsentState) => void;
+}
+/**
+ * Granular toggles for Zest's interceptor layer. Default is `true` on
+ * every channel — back-compat with previous versions.
+ *
+ * Consumers that gate optional scripts and storage themselves can
+ * disable interception per channel and use Zest as a pure consent-state
+ * engine.
+ */
+export interface InterceptToggles {
+  cookies?: boolean;
+  storage?: boolean;
+  scripts?: boolean;
+}
+/** Configuration accepted by `init()` and `window.ZestConfig`. */
+export interface InitOptions {
+  /** Display language. `'auto'` detects from `<html lang>` / browser. */
+  lang?:
+    | 'auto'
+    | 'en' | 'de' | 'es' | 'fr' | 'it' | 'pt'
+    | 'nl' | 'pl' | 'uk' | 'ru' | 'ja' | 'zh';
+  /** Banner position. Default `'bottom'`. */
+  position?: BannerPosition;
+  /** UI theme. Default `'auto'`. */
+  theme?: ZestTheme;
+  /** Hex accent color for buttons (e.g. `'#0071e3'`). */
+  accentColor?: string;
+  /** Link to the host site's privacy policy. */
+  policyUrl?: string;
+  /** Show floating "manage cookies" widget after a decision. Default `true`. */
+  showWidget?: boolean;
+  /** Cookie expiration in days. Default `365`. */
+  expiration?: number;
+  /** Script-blocking mode. Default `'safe'`. */
+  mode?: ZestMode;
+  /** Auto-initialise on script load. Default `true` for the UI build. */
+  autoInit?: boolean;
+  /** Respect Do Not Track / Global Privacy Control. Default `true`. */
+  respectDNT?: boolean;
+  /** What to do when DNT/GPC is on. Default `'reject'`. */
+  dntBehavior?: DNTBehavior;
+  /** Disable individual interceptors. Default: all on. */
+  intercept?: InterceptToggles;
+  /**
+   * Exact storage / cookie names to treat as strictly-necessary. Each
+   * is appended to the essential category as a fully-anchored regex,
+   * so the built-in essential patterns (zest_*, csrf*, …) stay intact.
+   */
+  essentialKeys?: string[];
+  /**
+   * Regex source strings to treat as strictly-necessary. Validated via
+   * safeRegExp, appended (not replaced) to the essential category.
+   */
+  essentialPatterns?: string[];
+  /**
+   * Override patterns per category. Note: this REPLACES the category's
+   * built-in patterns. Prefer `essentialKeys` / `essentialPatterns` if
+   * you only want to add to the essential category.
+   */
+  patterns?: Partial<Record<ConsentCategory, string[]>>;
+  /** Consumer callbacks. */
+  callbacks?: ZestCallbacks;
+  /** Anything else — Zest tolerates unknown keys at runtime. */
+  [key: string]: unknown;
+}
+/** Event names emitted on `document.documentElement`. */
+export interface ZestEvents {
+  READY: 'zest:ready';
+  CONSENT: 'zest:consent';
+  REJECT: 'zest:reject';
+  CHANGE: 'zest:change';
+  SHOW: 'zest:show';
+  HIDE: 'zest:hide';
+}
+export type ZestEventName = ZestEvents[keyof ZestEvents];
+/** Detail payload of consent events. */
+export interface ZestEventDetail {
+  consent: ConsentState;
+  previous?: ConsentState;
+}
+declare const Zest: {
+  /** Initialise. Auto-called when the script loads unless `autoInit: false`. */
+  init(options?: InitOptions): InitSnapshot;
+  /** Show the consent banner. */
+  show(): void;
+  /** Hide the consent banner. */
+  hide(): void;
+  /** Open the per-category settings modal. */
+  showSettings(): void;
+  /** Close the settings modal. */
+  hideSettings(): void;
+  /** Show the persistent "manage cookies" widget. */
+  showWidget(): void;
+  /** Hide the widget without removing it. */
+  hideWidget(): void;
+  /** Current consent state (clone, safe to mutate). */
+  getConsent(): ConsentState;
+  /** Has the user granted consent for `category`? */
+  hasConsent(category: ConsentCategory): boolean;
+  /** Has the user made any consent decision yet? */
+  hasConsentDecision(): boolean;
+  /** Tamper-evident snapshot of the last consent decision. */
+  getConsentProof(): ConsentProof | null;
+  /** Grant consent for every category and run accept callbacks. */
+  acceptAll(): void;
+  /** Revoke consent for every non-essential category and run reject callbacks. */
+  rejectAll(): void;
+  /** Wipe all consent state and reshow the banner. */
+  reset(): void;
+  /** True if the browser is sending DNT or GPC. */
+  isDoNotTrackEnabled(): boolean;
+  /** Why `isDoNotTrackEnabled()` returned what it did. */
+  getDNTDetails(): DNTDetails;
+  /** Subscribe to a consent event. Returns an unsubscribe function. */
+  on(
+    eventName: ZestEventName,
+    handler: (event: CustomEvent<ZestEventDetail>) => void
+  ): () => void;
+  /** Subscribe once; auto-unsubscribes after the first call. */
+  once(
+    eventName: ZestEventName,
+    handler: (event: CustomEvent<ZestEventDetail>) => void
+  ): () => void;
+  /** Constants for `on()` / `once()`. */
+  EVENTS: ZestEvents;
+  /** Active configuration after `init()`. */
+  getConfig(): InitOptions | null;
+};
+export default Zest;
+declare global {
+  interface Window {
+    /** Set before loading `zest.min.js` to configure auto-initialisation. */
+    ZestConfig?: InitOptions;
+    /** The Zest singleton, attached after auto-init. */
+    Zest?: typeof Zest;
+  }
+}

package/dist/zest.de.js CHANGED Viewed

@@ -258,10 +258,47 @@ var Zest = (function () {
   let patterns = { ...DEFAULT_PATTERNS };
+  /** Escape a string so it can be embedded in a regex literal verbatim. */
+  function escapeRegex(value) {
+    return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  }
+  /**
+   * Append patterns to a single category without replacing what's already
+   * there. Used by `essentialKeys` and `essentialPatterns` config to extend
+   * the strictly-necessary category with consumer-specific entries while
+   * keeping the built-in defaults (zest_*, csrf*, xsrf*, etc.).
+   *
+   * `keys` is an array of exact storage/cookie names; each one is
+   * compiled as a fully-anchored regex via `escapeRegex`.
+   * `patternStrings` is an array of regex source strings, each validated
+   * via `safeRegExp`. Invalid entries are dropped silently.
+   */
+  function appendPatternsToCategory(category, { keys = [], patternStrings = [] } = {}) {
+    if (!patterns[category]) patterns[category] = [];
+    for (const key of keys) {
+      if (typeof key !== 'string' || !key) continue;
+      const re = safeRegExp(`^${escapeRegex(key)}$`);
+      if (re) patterns[category].push(re);
+    }
+    for (const p of patternStrings) {
+      if (typeof p !== 'string' || !p) continue;
+      const re = safeRegExp(p);
+      if (re) patterns[category].push(re);
+    }
+  }
   /**
    * Set custom patterns. User-supplied strings are validated with safeRegExp,
    * which rejects catastrophic-backtracking shapes and syntax errors.
    * Invalid patterns are silently dropped with a console warning.
+   *
+   * Note: this REPLACES the patterns for any category present in
+   * `customPatterns`. To extend the essential category without losing the
+   * built-in defaults, use `appendPatternsToCategory()` (or pass
+   * `essentialKeys` / `essentialPatterns` to `Zest.init()`).
    */
   function setPatterns(customPatterns) {
     patterns = { ...DEFAULT_PATTERNS };
@@ -1292,6 +1329,32 @@ var Zest = (function () {
     // Blocking mode: 'manual' | 'safe' | 'strict' | 'doomsday'
     mode: 'safe',
+    // Interceptor toggles. By default Zest installs cookie + storage
+    // interceptors that route writes through the consent layer. Consumers
+    // who manage gating themselves (typically headless mode with custom
+    // analytics integrations) can opt out per channel.
+    intercept: {
+      cookies: true,
+      storage: true,
+      scripts: true
+    },
+    // Strictly-necessary declarations. Both fields *append* to whatever
+    // the essential category already matches via the pattern matcher
+    // defaults — they do not replace.
+    //
+    // - essentialKeys:    array of exact storage / cookie names to treat
+    //                     as strictly-necessary. Easiest case.
+    // - essentialPatterns: array of regex source strings, validated via
+    //                      safeRegExp. For prefix or family matches.
+    //
+    // Use these instead of `patterns.essential` when you only want to
+    // ADD entries to the essential category without replacing the
+    // built-in patterns (zest_*, csrf*, xsrf*, session*, __host-*,
+    // __secure-*).
+    essentialKeys: [],
+    essentialPatterns: [],
     // Custom domains to block (in addition to mode-based blocking)
     blockedDomains: [], // days
@@ -1374,6 +1437,28 @@ var Zest = (function () {
       config.patterns = userConfig.patterns;
     }
+    // Interceptor toggles — shallow-merge so consumers can pass partial
+    // overrides like `intercept: { storage: false }` without losing the
+    // other defaults.
+    if (userConfig.intercept && typeof userConfig.intercept === 'object') {
+      config.intercept = {
+        ...DEFAULTS.intercept,
+        ...userConfig.intercept
+      };
+    }
+    // Strictly-necessary declarations
+    if (Array.isArray(userConfig.essentialKeys)) {
+      config.essentialKeys = userConfig.essentialKeys.filter(
+        (k) => typeof k === 'string' && k.length > 0 && k.length <= 200
+      );
+    }
+    if (Array.isArray(userConfig.essentialPatterns)) {
+      config.essentialPatterns = userConfig.essentialPatterns.filter(
+        (p) => typeof p === 'string' && p.length > 0 && p.length <= 500
+      );
+    }
     return config;
   }
@@ -1816,13 +1901,32 @@ var Zest = (function () {
       setPatterns(currentConfig.patterns);
     }
+    // Append consumer-declared strictly-necessary entries on top of
+    // whatever's already in the essential category. This is the friendly
+    // alternative to overriding via `patterns.essential` directly.
+    if (
+      (Array.isArray(currentConfig.essentialKeys) && currentConfig.essentialKeys.length > 0) ||
+      (Array.isArray(currentConfig.essentialPatterns) && currentConfig.essentialPatterns.length > 0)
+    ) {
+      appendPatternsToCategory('essential', {
+        keys: currentConfig.essentialKeys,
+        patternStrings: currentConfig.essentialPatterns
+      });
+    }
     setConsentChecker$2(checkConsent);
     setConsentChecker$1(checkConsent);
     setConsentChecker(checkConsent);
-    interceptCookies();
-    interceptStorage();
-    startScriptBlocking(currentConfig.mode, currentConfig.blockedDomains);
+    // Interceptor toggles. By default everything is intercepted (back-compat
+    // with v2.0 / v2.1). Consumers that gate scripts and storage themselves
+    // can opt out per channel via `intercept: { storage: false, … }`.
+    const intercept = currentConfig.intercept || { cookies: true, storage: true, scripts: true };
+    if (intercept.cookies !== false) interceptCookies();
+    if (intercept.storage !== false) interceptStorage();
+    if (intercept.scripts !== false) {
+      startScriptBlocking(currentConfig.mode, currentConfig.blockedDomains);
+    }
     const consent = loadConsent();
     initialized = true;