@consenti/ui 0.5.0 → 0.6.0

package/README.md

@@ -183,14 +183,17 @@ const widget = new ConsentiSetup({
 
     // Client-side geo resolver (used only when api.enabled = false)
     // 'default' → browser timezone + navigator.language heuristic (built-in, zero deps)
-    // WidgetCountryResolverFn → custom async function: () => Promise<{ country, region, confidence }>
+    // WidgetCountryResolverFn → custom async function: ({ timezone, language, languages, locale }) => Promise<{ country, region, confidence }>
     geoDataProvider: 'default',
 
     // Only meaningful when api.enabled = false (ignored, with a warning, otherwise — the server
     // resolves the group in that mode). Only overrides country→group mapping; country/region
     // detection above always uses the embedded geo data.
     // 'default' → embedded map (default) | a URL string (fetched; the browser's own HTTP cache
-    // honors whatever Cache-Control/ETag the response sends) | an inline ComplianceMapData object
+    // honors whatever Cache-Control/ETag the response sends) | an inline ComplianceMapData object.
+    // A country the map doesn't list falls back to the embedded mapping, unless the document sets
+    // `override: true` — then it gets the strictest group ('opt-in'). Unlike the server, an omitted
+    // `override` is NOT true here: widget maps have always merged over the embedded mapping.
     complianceMap: 'default',
 
     // TCF (IAB Transparency & Consent Framework) client stub (optional) — see "TCF" section below

package/dist/angular.d.cts

@@ -64,6 +64,10 @@ type ComplianceType = 'auto' | ComplianceGroupId | (string & {}) | Symbol;
 
 interface ComplianceMapData {
     version: string;
+    /** `true` (default): this map replaces the embedded one entirely, so only the countries listed here
+     * resolve (server side). `false`: `countries` is merged over the embedded map — a listed country
+     * replaces its embedded entry wholesale, every unlisted country keeps its built-in mapping. */
+    override?: boolean;
     countries: Record<string, CountryComplianceEntry>;
 }
 interface CountryComplianceEntry {
@@ -83,6 +87,9 @@ interface ConsentDbRecord {
     tenantId: string;
     visitorId: string;
     profileId: string;
+    /** The profile's `version` when this consent was last given — with `profileId`, pins the exact
+     * on-disk snapshot (the banner text the visitor saw). Absent on records from before it was tracked. */
+    profileVersion?: number;
     locale: string;
     consentJson: ConsentValue;
     gpcDetected: boolean;
@@ -281,7 +288,12 @@ interface ResolvedProfile {
     /** Apply WCAG 2.1 AA accessibility enhancements to the widget. */
     enhanceAccessibility?: boolean;
 }
-type WidgetCountryResolverFn = () => Promise<{
+type WidgetCountryResolverFn = (hints: {
+    timezone: string;
+    language: string;
+    languages: string[];
+    locale: string;
+}) => Promise<{
     country: string | null;
     region: string | null;
     confidence: number;
@@ -340,8 +352,11 @@ interface ComplianceWidgetConfig {
      * document from (the browser's own HTTP cache honors whatever `Cache-Control`/`ETag` the
      * response sends — no custom caching here), or an inline operator-supplied `ComplianceMapData`
      * object. Invalid data from either a URL or an object logs a warning and falls back to
-     * `'default'`. Only overrides the country→group mapping — country/region detection itself
-     * always uses the embedded geo data. */
+     * `'default'`. Only overrides the country→group mapping — country/region detection itself always
+     * uses the embedded geo data. A country the map doesn't list falls back to the embedded mapping
+     * unless the document sets `override: true` (then it gets the strictest group, `'opt-in'`).
+     * Unlike the server, an omitted `override` is NOT `true` here: widget maps have always merged
+     * over the embedded mapping, and that stays the default. */
     complianceMap?: 'default' | string | ComplianceMapData;
     tcf?: TcfWidgetConfig;
     gpp?: GppWidgetConfig;

package/dist/angular.d.ts

@@ -64,6 +64,10 @@ type ComplianceType = 'auto' | ComplianceGroupId | (string & {}) | Symbol;
 
 interface ComplianceMapData {
     version: string;
+    /** `true` (default): this map replaces the embedded one entirely, so only the countries listed here
+     * resolve (server side). `false`: `countries` is merged over the embedded map — a listed country
+     * replaces its embedded entry wholesale, every unlisted country keeps its built-in mapping. */
+    override?: boolean;
     countries: Record<string, CountryComplianceEntry>;
 }
 interface CountryComplianceEntry {
@@ -83,6 +87,9 @@ interface ConsentDbRecord {
     tenantId: string;
     visitorId: string;
     profileId: string;
+    /** The profile's `version` when this consent was last given — with `profileId`, pins the exact
+     * on-disk snapshot (the banner text the visitor saw). Absent on records from before it was tracked. */
+    profileVersion?: number;
     locale: string;
     consentJson: ConsentValue;
     gpcDetected: boolean;
@@ -281,7 +288,12 @@ interface ResolvedProfile {
     /** Apply WCAG 2.1 AA accessibility enhancements to the widget. */
     enhanceAccessibility?: boolean;
 }
-type WidgetCountryResolverFn = () => Promise<{
+type WidgetCountryResolverFn = (hints: {
+    timezone: string;
+    language: string;
+    languages: string[];
+    locale: string;
+}) => Promise<{
     country: string | null;
     region: string | null;
     confidence: number;
@@ -340,8 +352,11 @@ interface ComplianceWidgetConfig {
      * document from (the browser's own HTTP cache honors whatever `Cache-Control`/`ETag` the
      * response sends — no custom caching here), or an inline operator-supplied `ComplianceMapData`
      * object. Invalid data from either a URL or an object logs a warning and falls back to
-     * `'default'`. Only overrides the country→group mapping — country/region detection itself
-     * always uses the embedded geo data. */
+     * `'default'`. Only overrides the country→group mapping — country/region detection itself always
+     * uses the embedded geo data. A country the map doesn't list falls back to the embedded mapping
+     * unless the document sets `override: true` (then it gets the strictest group, `'opt-in'`).
+     * Unlike the server, an omitted `override` is NOT `true` here: widget maps have always merged
+     * over the embedded mapping, and that stays the default. */
     complianceMap?: 'default' | string | ComplianceMapData;
     tcf?: TcfWidgetConfig;
     gpp?: GppWidgetConfig;

package/dist/index.d.ts

@@ -64,6 +64,10 @@ type ComplianceType = 'auto' | ComplianceGroupId | (string & {}) | Symbol;
 
 interface ComplianceMapData {
     version: string;
+    /** `true` (default): this map replaces the embedded one entirely, so only the countries listed here
+     * resolve (server side). `false`: `countries` is merged over the embedded map — a listed country
+     * replaces its embedded entry wholesale, every unlisted country keeps its built-in mapping. */
+    override?: boolean;
     countries: Record<string, CountryComplianceEntry>;
 }
 interface CountryComplianceEntry {
@@ -83,6 +87,9 @@ interface ConsentDbRecord {
     tenantId: string;
     visitorId: string;
     profileId: string;
+    /** The profile's `version` when this consent was last given — with `profileId`, pins the exact
+     * on-disk snapshot (the banner text the visitor saw). Absent on records from before it was tracked. */
+    profileVersion?: number;
     locale: string;
     consentJson: ConsentValue;
     gpcDetected: boolean;
@@ -401,7 +408,12 @@ interface ResolvedProfile {
     /** Apply WCAG 2.1 AA accessibility enhancements to the widget. */
     enhanceAccessibility?: boolean;
 }
-type WidgetCountryResolverFn = () => Promise<{
+type WidgetCountryResolverFn = (hints: {
+    timezone: string;
+    language: string;
+    languages: string[];
+    locale: string;
+}) => Promise<{
     country: string | null;
     region: string | null;
     confidence: number;
@@ -460,8 +472,11 @@ interface ComplianceWidgetConfig {
      * document from (the browser's own HTTP cache honors whatever `Cache-Control`/`ETag` the
      * response sends — no custom caching here), or an inline operator-supplied `ComplianceMapData`
      * object. Invalid data from either a URL or an object logs a warning and falls back to
-     * `'default'`. Only overrides the country→group mapping — country/region detection itself
-     * always uses the embedded geo data. */
+     * `'default'`. Only overrides the country→group mapping — country/region detection itself always
+     * uses the embedded geo data. A country the map doesn't list falls back to the embedded mapping
+     * unless the document sets `override: true` (then it gets the strictest group, `'opt-in'`).
+     * Unlike the server, an omitted `override` is NOT `true` here: widget maps have always merged
+     * over the embedded mapping, and that stays the default. */
     complianceMap?: 'default' | string | ComplianceMapData;
     tcf?: TcfWidgetConfig;
     gpp?: GppWidgetConfig;