@consenti/ui 0.1.0

package/dist/angular.d.cts

@@ -0,0 +1,481 @@
+type ConsentStatus = 'granted' | 'denied' | 'objected';
+type ConsentValue = Record<string, ConsentStatus>;
+interface Cookie {
+    id: string;
+    type?: 'consent' | 'legitimate_interest';
+    mandatory?: boolean;
+    listenGpc?: boolean;
+    expiry?: number;
+    tcfVendorId?: number;
+    tcfPurposes?: number[];
+    cpraCategory?: 'sale' | 'sharing' | 'sensitive';
+}
+type ButtonStyle = 'primary' | 'secondary' | 'text' | 'accent';
+type ButtonAction = 'submit' | 'manage' | 'close' | 'custom' | 'link';
+interface Button {
+    text: string;
+    style: ButtonStyle;
+    action: ButtonAction;
+    cookies?: string[] | '*' | '!';
+    url?: string;
+}
+interface MainBanner {
+    position: 'top' | 'bottom' | 'middle' | 'left-bottom' | 'right-bottom';
+    overlayOpacity?: number;
+    showClose?: boolean;
+    showLocaleSwitcher?: boolean;
+    heading?: string;
+    headingTag?: string;
+    htmlText: string;
+    buttons: Button[];
+}
+type GpcBanner = MainBanner;
+interface Category {
+    id: string;
+    heading: string;
+    headingTag?: string;
+    htmlText: string;
+    mandatory?: boolean;
+    type?: 'consent' | 'legitimate_interest';
+    legitimateInterest?: {
+        enabled?: boolean;
+        description?: string;
+    };
+    cookies: string[];
+}
+interface PreferenceModal {
+    position?: 'left' | 'right' | 'center';
+    overlayOpacity?: number;
+    showClose?: boolean;
+    showLocaleSwitcher?: boolean;
+    heading?: string;
+    headingTag?: string;
+    subheading?: string;
+    htmlText?: string;
+    buttons: Button[];
+    categories: Category[];
+    persistent?: boolean;
+}
+interface DpdpaConfig {
+    dataFiduciary: string;
+    grievanceEmail: string;
+    purposeDescription?: string;
+}
+interface ResolvedProfile {
+    id: number;
+    version: number;
+    defaultLocale: string;
+    locales?: string[];
+    cookies: Cookie[];
+    mainBanner: MainBanner;
+    gpcBanner?: GpcBanner;
+    preferenceModal: PreferenceModal;
+    cookieSigningKey?: string;
+    dpdpa?: DpdpaConfig;
+    darkMode?: boolean;
+}
+interface GtmConfig {
+    containerId?: string;
+    events?: string[];
+    dataLayer?: string;
+    urlPassthrough?: boolean;
+    adsDataRedaction?: boolean;
+}
+interface UtilsConfig {
+    gtm?: GtmConfig;
+}
+interface ApiConfig {
+    enabled?: boolean;
+    baseUrl?: string;
+    authToken?: string;
+}
+interface ThemeConfig {
+    bgColor?: string;
+    textColor?: string;
+    primaryColor?: string;
+    primaryTextColor?: string;
+    secondaryColor?: string;
+    secondaryTextColor?: string;
+    borderColor?: string;
+    fontFamily?: string;
+    fontSizeBase?: string;
+    fontSizeHeading?: string;
+    fontSizeMultiplier?: string;
+    borderRadius?: string;
+    buttonBorderRadius?: string;
+    toggleBgOn?: string;
+    toggleBgOff?: string;
+    accentColor?: string;
+    accentTextColor?: string;
+}
+interface CoreConfig {
+    profileId?: number;
+    autoHonorGPC?: boolean | 'strict';
+    locale?: string;
+    disableCssTemplate?: boolean;
+    signCookies?: boolean;
+    cookieSigningKey?: string;
+    allowReceipt?: boolean;
+    cookieDomains?: string;
+    storage?: 'cookie' | 'localStorage';
+    theme?: ThemeConfig;
+    privacyPolicyUrl?: string;
+    regulation?: 'gdpr' | 'ccpa' | 'cpra' | 'dpdpa' | 'uk-gdpr' | 'lgpd' | 'pipeda' | 'popia' | 'pdpa-th' | 'appi' | 'kvkk';
+    userId?: string;
+}
+interface ConsentiConfig {
+    core: CoreConfig;
+    rootEl?: string | HTMLElement;
+    darkMode?: boolean;
+    autoInit?: boolean;
+    api?: ApiConfig;
+    utils?: UtilsConfig;
+    plugins?: ConsentiPlugin[];
+    profileOverride?: Partial<ResolvedProfile>;
+}
+interface ConsentiWidgetAPI {
+    hasConsent(): boolean;
+    getConsent(): ConsentValue | null;
+    getConsentDate(): Date | false;
+    getGTMConsent(): Record<string, string> | null;
+    bannerVisibility(): 'main' | 'gpc' | false;
+    modalVisibility(): 'preference' | false;
+    getProfile(): ResolvedProfile | null;
+    showBanner(gpc?: boolean): void;
+    hideBanner(): void;
+    showModal(triggerEl?: HTMLElement): void;
+    hideModal(): void;
+    submitConsent(consent: Partial<ConsentValue>): Promise<void>;
+    deleteConsent(): Promise<void>;
+    reConsent(): Promise<void>;
+    getRootElement(): HTMLElement | null;
+    getBannerElement(): HTMLElement | null;
+    getModalElement(): HTMLElement | null;
+    switchLocale(locale: string): void;
+    init(): Promise<void>;
+    onReady(callback: () => void): void;
+    destroy(): void;
+}
+declare abstract class ConsentiPlugin {
+    abstract initialize(widget: ConsentiWidgetAPI): void | Promise<void>;
+    abstract destroy(): void;
+    onConsentSubmit?(consent: ConsentValue): void | Promise<void>;
+    onBannerShow?(): void | Promise<void>;
+    onBannerHide?(): void | Promise<void>;
+    onModalShow?(): void | Promise<void>;
+    onModalHide?(): void | Promise<void>;
+}
+
+/**
+ * Main entry point for the Consenti widget.
+ *
+ * Instantiate one `ConsentiSetup` per page (or per profile ID if you run multiple
+ * consent contexts on the same page). The constructor is safe to call during SSR —
+ * it silently no-ops when `window` is not defined.
+ *
+ * @example
+ * ```ts
+ * const widget = new ConsentiSetup({
+ *   core: { profileId: 0 },
+ * })
+ * await widget.ready
+ * console.log(widget.hasConsent())
+ * ```
+ */
+
+declare class ConsentiSetup implements ConsentiWidgetAPI {
+    private config;
+    private initialized;
+    private initializing;
+    private profile;
+    private consentStore;
+    private eventBus;
+    private banner;
+    private modal;
+    private renderer;
+    private broadcastChannel;
+    private readyResolve;
+    private readyPromise;
+    private plugins;
+    /** Signature from the most recent `writeAndSign` call. Included in consent receipts. */
+    private lastSignature;
+    /** Tracks which banner variant is currently visible, or null when hidden. */
+    private _bannerVariant;
+    /**
+     * Creates and initialises the consent widget.
+     *
+     * Construction is synchronous; the async `init()` is launched in the background.
+     * Use `await widget.ready` or `widget.onReady(cb)` to run code after init completes.
+     *
+     * @param config - Widget configuration. See `ConsentiConfig` for all options.
+     */
+    constructor(config: ConsentiConfig);
+    private profileId;
+    /**
+     * Starts widget initialisation. Called automatically unless `autoInit: false` is set.
+     * Can be called explicitly after construction when `autoInit: false`, or after `destroy()`
+     * to re-initialise the same instance.
+     */
+    init(): Promise<void>;
+    /** Applies the `consenti-root--dark` class based on config or profile flag. */
+    private applyDarkMode;
+    /**
+     * Injects CSS custom property overrides supplied via `core.theme` into the
+     * Consenti root element so they cascade down to all widget elements.
+     */
+    private applyTheme;
+    private runPlugins;
+    /**
+     * Invokes an optional plugin hook on all registered plugins.
+     * Async hooks are awaited; errors are caught and logged so a broken plugin
+     * never interferes with the consent flow.
+     *
+     * @param invoke - Function that calls the desired hook method on a single plugin.
+     */
+    private callPluginHook;
+    private buildHandlers;
+    /**
+     * Classifies a consent submission as `accept_all`, `reject_all`, `custom`, or `update`.
+     * Used to enrich events and API payloads with intent metadata.
+     */
+    private deriveAction;
+    private handleBroadcastMessage;
+    /**
+     * Returns `true` if the visitor has saved consent for the active profile.
+     * Always returns `false` during SSR.
+     */
+    hasConsent(): boolean;
+    /**
+     * Returns the stored consent map, or `null` if no consent has been saved.
+     * Always returns `null` during SSR.
+     */
+    getConsent(): ConsentValue | null;
+    /**
+     * Returns the `Date` when consent was last saved, or `false` if no consent exists.
+     * Always returns `false` during SSR.
+     */
+    getConsentDate(): Date | false;
+    /**
+     * Returns the consent map in Google Consent Mode v2 format, ready to pass to
+     * `gtag('consent', 'update', ...)`. Returns `null` if no consent has been saved.
+     *
+     * Maps Consenti cookie IDs to the seven Google Consent Mode v2 parameters.
+     * Cookies whose IDs exactly match a GCM v2 key are forwarded directly.
+     * Non-GCM cookies are ignored by this method (they appear in `getConsent()` only).
+     */
+    getGTMConsent(): Record<string, string> | null;
+    /**
+     * Records and persists the user's consent choices.
+     *
+     * Mandatory cookies are always forced to `'granted'` regardless of what is passed.
+     * Non-mandatory cookies not present in `consent` default to `'denied'`.
+     *
+     * @param consent    - Partial or full map of cookie ID → status.
+     * @param gpcDerived - Internal flag set to `true` when called from the GPC strict path.
+     */
+    submitConsent(consent: Partial<ConsentValue>, gpcDerived?: boolean): Promise<void>;
+    /**
+     * Returns the currently visible banner variant, or `false` if no banner is shown.
+     * Useful for programmatically checking state before calling `showBanner` / `hideBanner`.
+     */
+    bannerVisibility(): 'main' | 'gpc' | false;
+    /**
+     * Returns `'preference'` when the preference modal is open, or `false` when closed.
+     */
+    modalVisibility(): 'preference' | false;
+    /**
+     * Mounts and shows the consent banner.
+     *
+     * No-ops if the requested variant is already visible. If a different variant is
+     * currently shown (e.g. switching from main to GPC), the existing banner is replaced.
+     *
+     * @param useGpcVariant - When `true` and the profile has a `gpcBanner`, that variant
+     *                        is shown instead of `mainBanner`. Used by the GPC flow.
+     */
+    showBanner(useGpcVariant?: boolean): void;
+    /** Hides the banner and notifies other tabs via BroadcastChannel. No-op if already hidden. */
+    hideBanner(): void;
+    /**
+     * Opens the preference modal and hides the banner while the modal is open.
+     * No-ops if the modal is already open.
+     * If the modal is closed without saving consent, the banner is re-shown automatically
+     * (see `hideModal()`). Only one banner or modal is visible at a time.
+     *
+     * @param triggerEl - The element that triggered the modal open. Focus returns here on close.
+     */
+    showModal(triggerEl?: HTMLElement): void;
+    /**
+     * Closes the preference modal and returns focus to the element that opened it.
+     * No-ops if the modal is already closed.
+     * If the user has not yet given consent, the banner is re-shown automatically.
+     */
+    hideModal(): void;
+    /**
+     * Registers a callback to run once the widget has finished initialising.
+     * If the widget is already initialised, the callback is invoked synchronously.
+     *
+     * @param callback - Function to call when the widget is ready.
+     */
+    onReady(callback: () => void): void;
+    /**
+     * A `Promise` that resolves once the widget has finished initialising.
+     * Equivalent to wrapping `onReady()` in a `Promise`.
+     *
+     * @example
+     * ```ts
+     * await widget.ready
+     * console.log('Widget ready')
+     * ```
+     */
+    get ready(): Promise<void>;
+    /**
+     * Deletes the stored consent record and notifies other tabs.
+     * The banner will reappear on the next page load (or immediately if the
+     * receiving tab calls `showBanner()` in response to `consentDeleted`).
+     */
+    deleteConsent(): Promise<void>;
+    /**
+     * Removes existing consent and immediately re-shows the consent banner so the user
+     * can review and update their preferences.
+     *
+     * Equivalent to calling `deleteConsent()` followed by `showBanner()`, but in a single
+     * method so callers do not need to coordinate the async deletion with the banner display.
+     *
+     * Use this to power "Review my consent" links in footers or privacy dashboards.
+     */
+    reConsent(): Promise<void>;
+    /**
+     * Returns the fully resolved profile for the current session, or `null` during the
+     * async init phase (before the profile has been fetched/resolved).
+     *
+     * Plugins can use this to read cookie definitions, banner config, modal categories,
+     * and the profile version without accessing internal state.
+     */
+    getProfile(): ResolvedProfile | null;
+    /**
+     * Returns the `#consenti-root` container element that wraps all widget DOM,
+     * or `null` before the widget has mounted or after `destroy()`.
+     *
+     * Plugins can use this to append custom elements, apply extra CSS variables,
+     * or observe mutations within the widget container.
+     */
+    getRootElement(): HTMLElement | null;
+    /**
+     * Returns the `#consenti-banner` element when it is present in the DOM, or `null`.
+     * The element may be hidden (`display: none`) — check `bannerVisibility()` for visibility state.
+     *
+     * Useful for adding extra content, custom event listeners, or mutation observers on the banner.
+     */
+    getBannerElement(): HTMLElement | null;
+    /**
+     * Returns the `#consenti-modal` element when the modal has been built, or `null`.
+     * The element is built on first `showModal()` call and reused on subsequent opens.
+     *
+     * Useful for injecting extra content into the modal or listening to modal-specific events.
+     */
+    getModalElement(): HTMLElement | null;
+    /**
+     * Switches the active locale, re-resolves the profile, and re-renders the widget.
+     * Called by the locale switcher UI when the user selects a different language.
+     *
+     * @param locale - BCP 47 locale code to switch to (e.g. `'fr'`, `'de-AT'`).
+     */
+    switchLocale(locale: string): void;
+    /**
+     * Destroys the widget — removes all DOM elements, disconnects the BroadcastChannel,
+     * and calls `destroy()` on all registered plugins.
+     *
+     * After `destroy()`, the instance should not be used again.
+     */
+    destroy(): void;
+}
+
+/**
+ * Angular integration for `@consenti/ui`.
+ *
+ * Import from the `@consenti/ui/angular` subpath to keep this module
+ * tree-shaken out of vanilla JS, React, and Vue bundles.
+ *
+ * Designed for **Angular 15+** with standalone components or NgModule-based projects.
+ * Initialise `ConsentiSetup` once (typically in `app.component.ts` or a root service)
+ * and call `setConsentiWidget()` so that `injectConsent()` can read from it in any
+ * component or service.
+ *
+ * @example
+ * ```ts
+ * // app.component.ts
+ * import { Component, OnInit, OnDestroy } from '@angular/core'
+ * import { ConsentiSetup } from '@consenti/ui'
+ * import { setConsentiWidget } from '@consenti/ui/angular'
+ *
+ * @Component({ selector: 'app-root', template: '<router-outlet />' })
+ * export class AppComponent implements OnInit, OnDestroy {
+ *   private widget!: ConsentiSetup
+ *
+ *   ngOnInit() {
+ *     this.widget = new ConsentiSetup({ core: { profileId: 0 } })
+ *     setConsentiWidget(this.widget)
+ *   }
+ *
+ *   ngOnDestroy() {
+ *     this.widget.destroy()
+ *   }
+ * }
+ *
+ * // any-component.ts
+ * import { Component, ChangeDetectorRef, OnInit, OnDestroy } from '@angular/core'
+ * import { injectConsent } from '@consenti/ui/angular'
+ *
+ * @Component({ selector: 'app-cookie-status', template: `
+ *   <p *ngIf="consent.hasConsent()">Consent given on {{ consent.getConsentDate() | date }}</p>
+ *   <button *ngIf="!consent.hasConsent()" (click)="consent.submitConsent({ analytics_storage: 'granted' })">
+ *     Accept Analytics
+ *   </button>
+ * ` })
+ * export class CookieStatusComponent implements OnInit, OnDestroy {
+ *   consent = injectConsent()
+ *   private unsub!: () => void
+ *
+ *   constructor(private cdr: ChangeDetectorRef) {}
+ *
+ *   ngOnInit() {
+ *     this.unsub = this.consent.onConsentChange(() => this.cdr.markForCheck())
+ *   }
+ *
+ *   ngOnDestroy() {
+ *     this.unsub()
+ *   }
+ * }
+ * ```
+ */
+
+/**
+ * Registers the active `ConsentiSetup` instance so `injectConsent()` can read from it.
+ * Call this once after creating your widget, typically in `AppComponent.ngOnInit()` or
+ * a root-level Angular service.
+ *
+ * @param widget - The `ConsentiSetup` instance to register.
+ */
+declare function setConsentiWidget(widget: ConsentiSetup): void;
+/**
+ * Returns a consent accessor object for use in Angular components and services.
+ *
+ * Unlike the React and Vue integrations, Angular uses its `ChangeDetectorRef` to
+ * trigger UI updates rather than a reactive primitive. Call `onConsentChange()` in
+ * `ngOnInit` to subscribe to consent changes and `cdr.markForCheck()` inside the
+ * callback to schedule re-renders in `OnPush` components.
+ *
+ * Returns SSR-safe fallback values when `window` is not defined (Angular Universal).
+ *
+ * @returns An object with `hasConsent`, `getConsent`, `submitConsent`, `getConsentDate`,
+ *          and `onConsentChange` (subscription helper).
+ */
+declare function injectConsent(): {
+    hasConsent: () => boolean;
+    getConsent: () => ConsentValue | null;
+    submitConsent: (_consent: Partial<ConsentValue>) => Promise<void>;
+    getConsentDate: () => Date | false;
+    onConsentChange: (_cb: () => void) => () => void;
+};
+
+export { injectConsent, setConsentiWidget };