@walkeros/web-source-cmp-usercentrics 3.4.1 → 3.4.2

package/dist/index.d.mts

@@ -21,6 +21,93 @@ interface UsercentricsEventDetail {
 declare global {
     interface WindowEventMap {
         ucEvent: CustomEvent<UsercentricsEventDetail>;
+        UC_UI_CMP_EVENT: CustomEvent<UsercentricsV3CmpEventDetail>;
+    }
+}
+/**
+ * Usercentrics V2 service info shape returned by `UC_UI.getServicesBaseInfo()`.
+ * Only the fields we use are typed — minimal surface, not a full V2 API mirror.
+ */
+interface UsercentricsV2Service {
+    /** Category slug: 'essential' | 'functional' | 'marketing' | custom */
+    categorySlug: string;
+    /** Consent state for this service */
+    consent: {
+        status: boolean;
+    };
+}
+/**
+ * Usercentrics V2 window API (`window.UC_UI`).
+ *
+ * Methods are synchronous (unlike V3). All methods are optional because
+ * Usercentrics does not guarantee every deployment exposes every method.
+ */
+interface UsercentricsV2Api {
+    isInitialized?: () => boolean;
+    getServicesBaseInfo?: () => UsercentricsV2Service[];
+    areAllConsentsAccepted?: () => boolean;
+}
+/**
+ * Usercentrics V3 category state. The SDK may add future states; we handle
+ * unknowns conservatively as non-accepting.
+ */
+type UsercentricsV3CategoryState = 'ALL_ACCEPTED' | 'ALL_DENIED' | 'SOME_ACCEPTED' | 'NO_STATE' | string;
+/**
+ * Minimal V3 CategoryData — only fields the adapter reads.
+ */
+interface UsercentricsV3CategoryData {
+    state: UsercentricsV3CategoryState;
+    name: string;
+}
+/**
+ * Minimal V3 ConsentData — only the `type` field is used to distinguish
+ * explicit vs implicit consent. Other fields (status, version, etc.) exist on
+ * the real SDK but are not read by this adapter.
+ */
+interface UsercentricsV3ConsentData {
+    type: 'EXPLICIT' | 'IMPLICIT' | string;
+}
+/**
+ * Minimal V3 ConsentDetails — only the fields the adapter reads.
+ * The real SDK also exposes `services`, but the adapter currently operates
+ * at category level only.
+ */
+interface UsercentricsV3ConsentDetails {
+    consent: UsercentricsV3ConsentData;
+    categories: Record<string, UsercentricsV3CategoryData>;
+}
+/**
+ * Usercentrics V3 window API (`window.__ucCmp`).
+ *
+ * Only the methods this adapter calls are typed — the real SDK surface is
+ * much wider but we intentionally keep this narrow.
+ */
+interface UsercentricsV3Api {
+    isInitialized: () => Promise<boolean>;
+    getConsentDetails: () => Promise<UsercentricsV3ConsentDetails>;
+}
+/**
+ * V3 CMP event detail. Fired on `UC_UI_CMP_EVENT` (or custom name).
+ * `source: 'CMP'` + a decision `type` tells us a user action has been taken.
+ */
+interface UsercentricsV3CmpEventDetail {
+    source?: string;
+    type?: string;
+}
+declare global {
+    interface Window {
+        /**
+         * Usercentrics V2 CMP API. Attached once the V2 Browser SDK is
+         * initialized. Optional because the SDK loads asynchronously — guard
+         * with a truthiness check before access.
+         */
+        UC_UI?: UsercentricsV2Api;
+        /**
+         * Usercentrics V3 CMP API. Attached once the V3 Browser SDK is
+         * initialized. Optional because the SDK loads asynchronously — guard
+         * with a truthiness check before access.
+         */
+        __ucCmp?: UsercentricsV3Api;
     }
 }
 /**
@@ -41,8 +128,9 @@ interface Settings {
      * Values: walkerOS consent group names
      *
      * Applied in both group-level and service-level consent modes.
-     * When multiple source categories map to the same group, OR logic applies:
-     * if ANY source category is true, the target group is true.
+     * When multiple source categories map to the same group, strict AND logic
+     * applies: ALL contributing source categories must be true for the target
+     * group to be true. Any single false denies consent.
      *
      * Default: {} (pass through category names as-is)
      */
@@ -55,6 +143,28 @@ interface Settings {
      * Default: true
      */
     explicitOnly?: boolean;
+    /**
+     * Which Usercentrics API to target.
+     * - 'auto' (default): detect at init. If `window.__ucCmp` is present, use V3.
+     *   If only `window.UC_UI` is present, use V2. If neither is present yet,
+     *   register listeners for both so late-loading CMPs are still caught.
+     * - 'v2': force legacy `window.UC_UI` path.
+     * - 'v3': force current `window.__ucCmp` path.
+     */
+    apiVersion?: 'auto' | 'v2' | 'v3';
+    /**
+     * V3 window event name to listen for consent changes.
+     *
+     * Usercentrics V3 hardcodes its built-in event names (`UC_UI_CMP_EVENT`,
+     * `UC_UI_INITIALIZED`, `UC_UI_VIEW_CHANGED`, `UC_CONSENT`) — they cannot be
+     * renamed. However, the Usercentrics admin dashboard (Implementation >
+     * Data Layer & Events) lets admins configure an ADDITIONAL custom window
+     * event. Use this setting to point at that custom event name if
+     * configured; otherwise leave as default.
+     *
+     * Default: 'UC_UI_CMP_EVENT'
+     */
+    v3EventName?: string;
 }
 /**
  * User input settings (all optional)
@@ -92,8 +202,16 @@ type index_Push = Push;
 type index_Settings = Settings;
 type index_Types = Types;
 type index_UsercentricsEventDetail = UsercentricsEventDetail;
+type index_UsercentricsV2Api = UsercentricsV2Api;
+type index_UsercentricsV2Service = UsercentricsV2Service;
+type index_UsercentricsV3Api = UsercentricsV3Api;
+type index_UsercentricsV3CategoryData = UsercentricsV3CategoryData;
+type index_UsercentricsV3CategoryState = UsercentricsV3CategoryState;
+type index_UsercentricsV3CmpEventDetail = UsercentricsV3CmpEventDetail;
+type index_UsercentricsV3ConsentData = UsercentricsV3ConsentData;
+type index_UsercentricsV3ConsentDetails = UsercentricsV3ConsentDetails;
 declare namespace index {
-  export type { index_Config as Config, index_Env as Env, index_InitSettings as InitSettings, index_Mapping as Mapping, index_Push as Push, index_Settings as Settings, index_Types as Types, index_UsercentricsEventDetail as UsercentricsEventDetail };
+  export type { index_Config as Config, index_Env as Env, index_InitSettings as InitSettings, index_Mapping as Mapping, index_Push as Push, index_Settings as Settings, index_Types as Types, index_UsercentricsEventDetail as UsercentricsEventDetail, index_UsercentricsV2Api as UsercentricsV2Api, index_UsercentricsV2Service as UsercentricsV2Service, index_UsercentricsV3Api as UsercentricsV3Api, index_UsercentricsV3CategoryData as UsercentricsV3CategoryData, index_UsercentricsV3CategoryState as UsercentricsV3CategoryState, index_UsercentricsV3CmpEventDetail as UsercentricsV3CmpEventDetail, index_UsercentricsV3ConsentData as UsercentricsV3ConsentData, index_UsercentricsV3ConsentDetails as UsercentricsV3ConsentDetails };
 }
 
 /**
@@ -199,8 +317,10 @@ declare const trigger: (input: unknown, env: Record<string, unknown>) => void |
 /**
  * Usercentrics consent management source for walkerOS.
  *
- * This source listens to Usercentrics CMP events and translates
- * consent states to walkerOS consent commands.
+ * Listens to Usercentrics CMP events and translates consent states to
+ * walkerOS consent commands. Supports both the legacy V2 API
+ * (`window.UC_UI` + `ucEvent`) and the current V3 API
+ * (`window.__ucCmp` + `UC_UI_CMP_EVENT`).
  *
  * @example
  * ```typescript

package/dist/index.d.ts

@@ -21,6 +21,93 @@ interface UsercentricsEventDetail {
 declare global {
     interface WindowEventMap {
         ucEvent: CustomEvent<UsercentricsEventDetail>;
+        UC_UI_CMP_EVENT: CustomEvent<UsercentricsV3CmpEventDetail>;
+    }
+}
+/**
+ * Usercentrics V2 service info shape returned by `UC_UI.getServicesBaseInfo()`.
+ * Only the fields we use are typed — minimal surface, not a full V2 API mirror.
+ */
+interface UsercentricsV2Service {
+    /** Category slug: 'essential' | 'functional' | 'marketing' | custom */
+    categorySlug: string;
+    /** Consent state for this service */
+    consent: {
+        status: boolean;
+    };
+}
+/**
+ * Usercentrics V2 window API (`window.UC_UI`).
+ *
+ * Methods are synchronous (unlike V3). All methods are optional because
+ * Usercentrics does not guarantee every deployment exposes every method.
+ */
+interface UsercentricsV2Api {
+    isInitialized?: () => boolean;
+    getServicesBaseInfo?: () => UsercentricsV2Service[];
+    areAllConsentsAccepted?: () => boolean;
+}
+/**
+ * Usercentrics V3 category state. The SDK may add future states; we handle
+ * unknowns conservatively as non-accepting.
+ */
+type UsercentricsV3CategoryState = 'ALL_ACCEPTED' | 'ALL_DENIED' | 'SOME_ACCEPTED' | 'NO_STATE' | string;
+/**
+ * Minimal V3 CategoryData — only fields the adapter reads.
+ */
+interface UsercentricsV3CategoryData {
+    state: UsercentricsV3CategoryState;
+    name: string;
+}
+/**
+ * Minimal V3 ConsentData — only the `type` field is used to distinguish
+ * explicit vs implicit consent. Other fields (status, version, etc.) exist on
+ * the real SDK but are not read by this adapter.
+ */
+interface UsercentricsV3ConsentData {
+    type: 'EXPLICIT' | 'IMPLICIT' | string;
+}
+/**
+ * Minimal V3 ConsentDetails — only the fields the adapter reads.
+ * The real SDK also exposes `services`, but the adapter currently operates
+ * at category level only.
+ */
+interface UsercentricsV3ConsentDetails {
+    consent: UsercentricsV3ConsentData;
+    categories: Record<string, UsercentricsV3CategoryData>;
+}
+/**
+ * Usercentrics V3 window API (`window.__ucCmp`).
+ *
+ * Only the methods this adapter calls are typed — the real SDK surface is
+ * much wider but we intentionally keep this narrow.
+ */
+interface UsercentricsV3Api {
+    isInitialized: () => Promise<boolean>;
+    getConsentDetails: () => Promise<UsercentricsV3ConsentDetails>;
+}
+/**
+ * V3 CMP event detail. Fired on `UC_UI_CMP_EVENT` (or custom name).
+ * `source: 'CMP'` + a decision `type` tells us a user action has been taken.
+ */
+interface UsercentricsV3CmpEventDetail {
+    source?: string;
+    type?: string;
+}
+declare global {
+    interface Window {
+        /**
+         * Usercentrics V2 CMP API. Attached once the V2 Browser SDK is
+         * initialized. Optional because the SDK loads asynchronously — guard
+         * with a truthiness check before access.
+         */
+        UC_UI?: UsercentricsV2Api;
+        /**
+         * Usercentrics V3 CMP API. Attached once the V3 Browser SDK is
+         * initialized. Optional because the SDK loads asynchronously — guard
+         * with a truthiness check before access.
+         */
+        __ucCmp?: UsercentricsV3Api;
     }
 }
 /**
@@ -41,8 +128,9 @@ interface Settings {
      * Values: walkerOS consent group names
      *
      * Applied in both group-level and service-level consent modes.
-     * When multiple source categories map to the same group, OR logic applies:
-     * if ANY source category is true, the target group is true.
+     * When multiple source categories map to the same group, strict AND logic
+     * applies: ALL contributing source categories must be true for the target
+     * group to be true. Any single false denies consent.
      *
      * Default: {} (pass through category names as-is)
      */
@@ -55,6 +143,28 @@ interface Settings {
      * Default: true
      */
     explicitOnly?: boolean;
+    /**
+     * Which Usercentrics API to target.
+     * - 'auto' (default): detect at init. If `window.__ucCmp` is present, use V3.
+     *   If only `window.UC_UI` is present, use V2. If neither is present yet,
+     *   register listeners for both so late-loading CMPs are still caught.
+     * - 'v2': force legacy `window.UC_UI` path.
+     * - 'v3': force current `window.__ucCmp` path.
+     */
+    apiVersion?: 'auto' | 'v2' | 'v3';
+    /**
+     * V3 window event name to listen for consent changes.
+     *
+     * Usercentrics V3 hardcodes its built-in event names (`UC_UI_CMP_EVENT`,
+     * `UC_UI_INITIALIZED`, `UC_UI_VIEW_CHANGED`, `UC_CONSENT`) — they cannot be
+     * renamed. However, the Usercentrics admin dashboard (Implementation >
+     * Data Layer & Events) lets admins configure an ADDITIONAL custom window
+     * event. Use this setting to point at that custom event name if
+     * configured; otherwise leave as default.
+     *
+     * Default: 'UC_UI_CMP_EVENT'
+     */
+    v3EventName?: string;
 }
 /**
  * User input settings (all optional)
@@ -92,8 +202,16 @@ type index_Push = Push;
 type index_Settings = Settings;
 type index_Types = Types;
 type index_UsercentricsEventDetail = UsercentricsEventDetail;
+type index_UsercentricsV2Api = UsercentricsV2Api;
+type index_UsercentricsV2Service = UsercentricsV2Service;
+type index_UsercentricsV3Api = UsercentricsV3Api;
+type index_UsercentricsV3CategoryData = UsercentricsV3CategoryData;
+type index_UsercentricsV3CategoryState = UsercentricsV3CategoryState;
+type index_UsercentricsV3CmpEventDetail = UsercentricsV3CmpEventDetail;
+type index_UsercentricsV3ConsentData = UsercentricsV3ConsentData;
+type index_UsercentricsV3ConsentDetails = UsercentricsV3ConsentDetails;
 declare namespace index {
-  export type { index_Config as Config, index_Env as Env, index_InitSettings as InitSettings, index_Mapping as Mapping, index_Push as Push, index_Settings as Settings, index_Types as Types, index_UsercentricsEventDetail as UsercentricsEventDetail };
+  export type { index_Config as Config, index_Env as Env, index_InitSettings as InitSettings, index_Mapping as Mapping, index_Push as Push, index_Settings as Settings, index_Types as Types, index_UsercentricsEventDetail as UsercentricsEventDetail, index_UsercentricsV2Api as UsercentricsV2Api, index_UsercentricsV2Service as UsercentricsV2Service, index_UsercentricsV3Api as UsercentricsV3Api, index_UsercentricsV3CategoryData as UsercentricsV3CategoryData, index_UsercentricsV3CategoryState as UsercentricsV3CategoryState, index_UsercentricsV3CmpEventDetail as UsercentricsV3CmpEventDetail, index_UsercentricsV3ConsentData as UsercentricsV3ConsentData, index_UsercentricsV3ConsentDetails as UsercentricsV3ConsentDetails };
 }
 
 /**
@@ -199,8 +317,10 @@ declare const trigger: (input: unknown, env: Record<string, unknown>) => void |
 /**
  * Usercentrics consent management source for walkerOS.
  *
- * This source listens to Usercentrics CMP events and translates
- * consent states to walkerOS consent commands.
+ * Listens to Usercentrics CMP events and translates consent states to
+ * walkerOS consent commands. Supports both the legacy V2 API
+ * (`window.UC_UI` + `ucEvent`) and the current V3 API
+ * (`window.__ucCmp` + `UC_UI_CMP_EVENT`).
  *
  * @example
  * ```typescript