@consenti/ui 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,770 @@
+type ConsentStatus = 'granted' | 'denied' | 'objected';
+type ConsentAction = 'accept_all' | 'reject_all' | 'custom' | 'update';
+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 LocaleTranslations {
+    mainBanner: MainBanner;
+    gpcBanner?: GpcBanner;
+    preferenceModal: PreferenceModal;
+}
+interface ProfileTranslations {
+    [locale: string]: LocaleTranslations;
+}
+interface DpdpaConfig {
+    dataFiduciary: string;
+    grievanceEmail: string;
+    purposeDescription?: string;
+}
+interface LocaleTextContent {
+    mainBanner: {
+        heading: string;
+        htmlText: string;
+        buttonLabels: string[];
+    };
+    gpcBanner: {
+        heading: string;
+        htmlText: string;
+        buttonLabels: string[];
+    };
+    preferenceModal: {
+        heading: string;
+        subheading?: string;
+        htmlText?: string;
+        buttonLabels: string[];
+        categories: Array<{
+            id: string;
+            heading: string;
+            htmlText: string;
+        }>;
+    };
+}
+interface ProfileConfig {
+    cookies?: Cookie[];
+    defaultLocale: string;
+    translations?: ProfileTranslations;
+    gpcBanner?: boolean;
+    darkMode?: boolean;
+    allowedOrigins?: string[];
+    dpdpa?: DpdpaConfig;
+    regulation?: 'gdpr' | 'ccpa' | 'cpra' | 'dpdpa' | 'uk-gdpr' | 'lgpd' | 'pipeda' | 'popia' | 'pdpa-th' | 'appi' | 'kvkk';
+    regulations?: string[];
+    cookieTemplateId?: string;
+    uiTemplateId?: string;
+    localeContents?: Record<string, LocaleTextContent>;
+}
+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$1[];
+    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$1 {
+    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>;
+}
+interface CookieOptions {
+    maxAge?: number;
+    path?: string;
+    sameSite?: 'Lax' | 'Strict' | 'None';
+    secure?: boolean;
+    domain?: string;
+}
+interface ParsedConsent {
+    timestamp: string;
+    consent: ConsentValue;
+    signature?: string;
+}
+interface ConsentRecord {
+    visitorId: string;
+    consentId?: string;
+    profileId: number;
+    profileVersion: number;
+    consent: ConsentValue;
+    timestamp: string;
+    gpc?: boolean;
+    action?: ConsentAction;
+    pageUrl?: string;
+}
+interface ConsentReceipt {
+    version: '1.0';
+    issuedAt: string;
+    visitorId: string;
+    profileId: number;
+    profileVersion: number;
+    locale: string;
+    consent: ConsentValue;
+    signature?: string;
+}
+interface ConsentEvent {
+    profileId?: number;
+    consent?: ConsentValue;
+    hasExistingConsent?: boolean;
+    show?: boolean;
+    action?: boolean;
+    consentAction?: ConsentAction;
+    consentId?: string;
+    pageUrl?: string;
+    apiResponse?: unknown;
+    fromBroadcast?: boolean;
+    gpcDetected?: boolean;
+}
+type ConsentiMessage = {
+    type: 'consentUpdated';
+    consent: ConsentValue;
+    profileId: number;
+} | {
+    type: 'bannerClosed';
+} | {
+    type: 'consentDeleted';
+};
+
+/**
+ * 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;
+}
+
+/**
+ * Abstract base class for Consenti UI plugins.
+ *
+ * Extend this class to hook into the widget lifecycle. Each plugin receives the
+ * full `ConsentiWidgetAPI` in `initialize()` — call any public method, inspect
+ * the resolved profile, or manipulate the widget DOM.
+ *
+ * Errors thrown in `initialize()` or `destroy()` are caught by `ConsentiSetup`
+ * and logged as warnings — a broken plugin never blocks the consent flow.
+ *
+ * @example
+ * ```ts
+ * import { ConsentiPlugin } from '@consenti/ui'
+ * import type { ConsentiWidgetAPI } from '@consenti/ui'
+ *
+ * class AnalyticsPlugin extends ConsentiPlugin {
+ *   initialize(widget: ConsentiWidgetAPI) {
+ *     window.addEventListener('consenti:consentSubmitted', () => {
+ *       const consent = widget.getConsent()
+ *       myAnalytics.track('consent_saved', consent)
+ *     })
+ *   }
+ *
+ *   destroy() {
+ *     // remove listeners, clear timers, etc.
+ *   }
+ * }
+ *
+ * class BannerStylePlugin extends ConsentiPlugin {
+ *   initialize(widget: ConsentiWidgetAPI) {
+ *     widget.onReady(() => {
+ *       const banner = widget.getBannerElement()
+ *       if (banner) banner.style.setProperty('--my-custom-prop', 'red')
+ *     })
+ *   }
+ *   destroy() {}
+ * }
+ *
+ * const widget = new ConsentiSetup({
+ *   core: { profileId: 1 },
+ *   plugins: [new AnalyticsPlugin(), new BannerStylePlugin()],
+ * })
+ * ```
+ */
+declare abstract class ConsentiPlugin {
+    /**
+     * Called once after `ConsentiSetup` has finished its async `init()`.
+     * May be async — the widget awaits the result before continuing.
+     *
+     * @param widget - The full public API of the initialised widget.
+     */
+    abstract initialize(widget: ConsentiWidgetAPI): void | Promise<void>;
+    /**
+     * Called when `widget.destroy()` is invoked.
+     * Use this to remove event listeners, cancel timers, and release resources.
+     */
+    abstract destroy(): void;
+    /**
+     * Called after consent has been saved to storage and dispatched to the API.
+     * Receives the full, normalised consent map (mandatory cookies always `'granted'`).
+     *
+     * @param consent - The complete consent record that was saved.
+     */
+    onConsentSubmit?(consent: ConsentValue): void | Promise<void>;
+    /** Called after the consent banner has been mounted and made visible. */
+    onBannerShow?(): void | Promise<void>;
+    /** Called after the consent banner has been hidden. */
+    onBannerHide?(): void | Promise<void>;
+    /** Called after the preference modal has been opened. */
+    onModalShow?(): void | Promise<void>;
+    /** Called after the preference modal has been closed. */
+    onModalHide?(): void | Promise<void>;
+}
+
+/**
+ * Client-side profile builder for API-less deployments.
+ *
+ * `ConsentiProfile` provides a type-safe way to define consent profiles directly
+ * in application code, without running a backend. Each instance is registered in
+ * the module-level profile registry so `ConsentiSetup` can resolve it by ID.
+ *
+ * IDs are auto-assigned starting from 1000 to avoid conflicts with API-backed profiles
+ * (which use small sequential integers assigned by the database).
+ *
+ * @example
+ * ```ts
+ * import { ConsentiProfile, ConsentiSetup } from '@consenti/ui'
+ *
+ * const profile = new ConsentiProfile({
+ *   cookies: [
+ *     { id: 'necessary', mandatory: true },
+ *     { id: 'analytics' },
+ *   ],
+ *   defaultLocale: 'en',
+ *   translations: {
+ *     en: {
+ *       mainBanner: {
+ *         position: 'bottom',
+ *         htmlText: 'We use cookies.',
+ *         buttons: [{ text: 'Accept All', type: 'primary', cookies: '*' }],
+ *       },
+ *       preferenceModal: {
+ *         categories: [],
+ *         buttons: [{ text: 'Save', type: 'submit' }],
+ *       },
+ *     },
+ *   },
+ * })
+ *
+ * const widget = new ConsentiSetup({ core: { profileId: profile.getId() } })
+ * ```
+ */
+
+/**
+ * Defines a local consent profile and registers it for use by `ConsentiSetup`.
+ */
+declare class ConsentiProfile {
+    private config;
+    private id;
+    /**
+     * @param config - Full profile configuration including cookies, locales, and UI text.
+     */
+    constructor(config: ProfileConfig);
+    /** Returns the auto-assigned numeric profile ID. Pass this to `core.profileId`. */
+    getId(): number;
+    /** Returns the raw `ProfileConfig` passed to the constructor. */
+    toJSON(): ProfileConfig;
+}
+
+/**
+ * ConsentScript — conditionally loads/unloads a third-party `<script>` tag
+ * based on a specific consent cookie's status.
+ *
+ * Instantiate after the widget is ready. The script is injected into `<head>`
+ * when the target cookie's consent is `'granted'` and removed when it is
+ * revoked. Ideal for lazy-loading analytics, ad pixels, or chat widgets without
+ * manual `consenti:consentSubmitted` listeners.
+ *
+ * @example
+ * ```ts
+ * import { ConsentiSetup, ConsentScript } from '@consenti/ui'
+ *
+ * const widget = new ConsentiSetup({ core: { profileId: 0 } })
+ * await widget.ready
+ *
+ * const cs = new ConsentScript({
+ *   cookieId: 'analytics_storage',
+ *   widget,
+ *   src: 'https://www.googletagmanager.com/gtag/js?id=G-XXXXXXX',
+ *   attributes: { async: '' },
+ *   onLoad: () => console.log('Analytics loaded'),
+ *   onRevoke: () => console.log('Analytics removed'),
+ * })
+ * ```
+ */
+
+/** Options for constructing a {@link ConsentScript} instance. */
+interface ConsentScriptOptions {
+    /** The consent cookie ID to watch (e.g. `'analytics_storage'`). */
+    cookieId: string;
+    /** The `ConsentiSetup` widget instance to read consent from. */
+    widget: ConsentiSetup;
+    /** Remote script `src` URL to inject when consent is granted. */
+    src?: string;
+    /** Inline JavaScript content to execute when consent is granted. */
+    innerHTML?: string;
+    /**
+     * Additional HTML attributes applied to the injected `<script>` element.
+     * Set a key to an empty string for boolean attributes (e.g. `{ async: '', defer: '' }`).
+     */
+    attributes?: Record<string, string>;
+    /** Called after the `<script>` element has been appended to `<head>`. */
+    onLoad?: () => void;
+    /** Called after the `<script>` element has been removed from the DOM. */
+    onRevoke?: () => void;
+}
+/**
+ * Conditionally injects and removes a `<script>` element based on a specific
+ * cookie's consent status.
+ *
+ * The check runs immediately on construction so existing consent is honoured
+ * without waiting for the next `consenti:consentSubmitted` event. It then
+ * re-evaluates on every future consent change.
+ *
+ * Call {@link ConsentScript.destroy} when the trigger is no longer needed
+ * (e.g. on SPA route unmount) to remove the event listener and the injected
+ * element.
+ */
+declare class ConsentScript {
+    private readonly options;
+    private scriptEl;
+    private readonly handler;
+    constructor(options: ConsentScriptOptions);
+    private evaluate;
+    private inject;
+    private revoke;
+    /**
+     * Removes the event listener and the injected `<script>` element (if present).
+     * Call this when the widget is destroyed or the script is no longer needed.
+     */
+    destroy(): void;
+}
+
+/**
+ * CookieTrigger — a pre-built accessible UI element that reopens the Consenti
+ * preference panel when clicked.
+ *
+ * Use this to add a "Cookie Settings" link in your site footer or cookie policy
+ * page without wiring up the click handler manually or importing the widget module
+ * into your layout component.
+ *
+ * @example
+ * ```ts
+ * import { ConsentiSetup, CookieTrigger } from '@consenti/ui'
+ *
+ * const widget = new ConsentiSetup({ core: { profileId: 0 } })
+ *
+ * // Attach to an existing element
+ * new CookieTrigger({ widget, el: '#footer-cookie-settings' })
+ *
+ * // — or — create a new button and place it yourself
+ * const trigger = new CookieTrigger({ widget, label: 'Cookie Settings' })
+ * document.querySelector('.site-footer')?.appendChild(trigger.getElement())
+ * ```
+ */
+
+/** Options for constructing a {@link CookieTrigger} instance. */
+interface CookieTriggerOptions {
+    /** The widget instance to control when the trigger is clicked. */
+    widget: ConsentiSetup;
+    /**
+     * Element to attach the click handler to.
+     * - `HTMLElement` — used directly.
+     * - `string` — treated as a CSS selector; the first matching element is used.
+     * - Omitted — a new `<button>` is created. Retrieve it with {@link CookieTrigger.getElement}
+     *   and append it to the DOM at the desired location.
+     */
+    el?: HTMLElement | string;
+    /**
+     * Which panel opens on click.
+     * - `'modal'` (default) — preference modal.
+     * - `'banner'` — main consent banner.
+     */
+    action?: 'modal' | 'banner';
+    /**
+     * Label for the auto-created button element.
+     * Ignored when `el` points to an existing element. Defaults to `'Cookie Settings'`.
+     */
+    label?: string;
+}
+/**
+ * Attaches a click handler that opens the Consenti preference panel to a DOM
+ * element, or creates an accessible `<button>` when no existing element is provided.
+ *
+ * The created button uses the `.consenti-btn` and `.consenti-btn--text` classes so
+ * it inherits the widget's theme automatically.
+ */
+declare class CookieTrigger {
+    private readonly el;
+    private readonly clickHandler;
+    /** Whether this instance created the element (used to decide if `destroy()` removes it). */
+    private readonly created;
+    constructor(options: CookieTriggerOptions);
+    /**
+     * Returns the trigger element.
+     * When no `el` was provided, append the returned element to the desired location
+     * in the DOM after construction.
+     */
+    getElement(): HTMLElement;
+    /**
+     * Removes the click handler and, if this instance auto-created the button,
+     * removes it from the DOM.
+     */
+    destroy(): void;
+}
+
+export { type ApiConfig, type Button, type ButtonAction, type ButtonStyle, type Category, type ConsentAction, type ConsentEvent, type ConsentReceipt, type ConsentRecord, ConsentScript, type ConsentScriptOptions, type ConsentStatus, type ConsentValue, type ConsentiConfig, type ConsentiMessage, ConsentiPlugin, ConsentiProfile, ConsentiSetup, type ConsentiWidgetAPI, type Cookie, type CookieOptions, CookieTrigger, type CookieTriggerOptions, type CoreConfig, type GpcBanner, type GtmConfig, type LocaleTranslations, type MainBanner, type ParsedConsent, type PreferenceModal, type ProfileConfig, type ProfileTranslations, type ResolvedProfile, type ThemeConfig, type UtilsConfig };