@consentera/consent-sdk 2.0.0

package/dist/types/types/index.d.ts

@@ -0,0 +1,311 @@
+/**
+ * ConsentEra Consent SDK Type Definitions
+ */
+export interface ConsentEraConfig {
+    /** Secret API key for server-side use (tiq_live_*). REFUSED in a browser. */
+    apiKey?: string;
+    /** Public site key for frontend use (tiq_pub_*). This is what the browser carries. */
+    siteKey?: string;
+    /**
+     * Allow a SECRET `apiKey` although a `window` exists. Refused by default —
+     * the cookie-consent plane needs only a public site key, and a secret in a
+     * bundle is a secret published to every visitor. Every request then warns.
+     */
+    unsafeAllowSecretKeyInBrowser?: boolean;
+    tenantId: string;
+    /**
+     * Your Consentera API origin, e.g. the host your tenant was provisioned on.
+     * REQUIRED — there is no default server, and the constructor refuses a
+     * missing or blank value with `ENDPOINT_REQUIRED`. The SDK calls
+     * `${apiEndpoint}/api/v1/cookie-consent/*`.
+     */
+    apiEndpoint: string;
+    autoShow?: boolean;
+    language?: string;
+    region?: 'IN' | 'EU' | 'US' | 'GLOBAL';
+    regulations?: RegulationType[];
+    theme?: ThemeConfig;
+    callbacks?: ConsentCallbacks;
+    tcf?: TCFConfig;
+    gpp?: GPPConfig;
+    storage?: StorageConfig;
+}
+export type RegulationType = 'DPDP' | 'GDPR' | 'CCPA' | 'LGPD' | 'TCF' | 'GPP';
+export interface ThemeConfig {
+    position?: 'bottom' | 'top' | 'center' | 'bottom-left' | 'bottom-right';
+    type?: 'banner' | 'modal' | 'popup';
+    primaryColor?: string;
+    secondaryColor?: string;
+    backgroundColor?: string;
+    textColor?: string;
+    fontFamily?: string;
+    borderRadius?: string;
+    showLogo?: boolean;
+    logoUrl?: string;
+    customCss?: string;
+}
+export interface ConsentCallbacks {
+    /**
+     * The consent decision could NOT be recorded by the platform. The banner has
+     * been left up and nothing was stored locally: the visitor has not consented
+     * and must be asked again. Before 2.0.0 this case was invisible — the SDK
+     * reported success and kept a local-only record.
+     */
+    onSyncFailed?: (error: Error) => void;
+    onReady?: () => void;
+    onConsentGiven?: (consent: ConsentData) => void;
+    onConsentWithdrawn?: (purposes: string[]) => void;
+    onPreferencesUpdated?: (preferences: ConsentPreferences) => void;
+    onBannerShown?: () => void;
+    onBannerClosed?: () => void;
+    onError?: (error: Error) => void;
+}
+export interface TCFConfig {
+    enabled: boolean;
+    cmpId?: number;
+    cmpVersion?: number;
+    publisherCountryCode?: string;
+    gdprApplies?: boolean;
+}
+export interface GPPConfig {
+    enabled: boolean;
+    sections?: string[];
+}
+export interface StorageConfig {
+    type?: 'cookie' | 'localStorage' | 'sessionStorage';
+    cookieName?: string;
+    cookieDomain?: string;
+    cookieExpiry?: number;
+    cookiePath?: string;
+    secure?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+}
+export interface ConsentData {
+    consentId: string;
+    timestamp: string;
+    version: string;
+    purposes: ConsentPurpose[];
+    vendors?: ConsentVendor[];
+    legalBasis: LegalBasis;
+    regulation: RegulationType;
+    dataPrincipal?: DataPrincipalInfo;
+    metadata?: ConsentMetadata;
+}
+export interface ConsentPurpose {
+    id: string;
+    name: string;
+    description?: string;
+    category: PurposeCategory;
+    required: boolean;
+    consented: boolean;
+    legalBasis?: LegalBasis;
+    retentionPeriod?: string;
+}
+export type PurposeCategory = 'essential' | 'functional' | 'analytics' | 'marketing' | 'personalization' | 'advertising' | 'social_media' | 'third_party';
+export interface ConsentVendor {
+    id: string;
+    name: string;
+    purposes: string[];
+    consented: boolean;
+    policyUrl?: string;
+}
+export type LegalBasis = 'consent' | 'contract' | 'legal_obligation' | 'vital_interests' | 'public_task' | 'legitimate_interest';
+export interface DataPrincipalInfo {
+    id?: string;
+    email?: string;
+    hash?: string;
+    type?: 'registered' | 'anonymous' | 'child' | 'guardian';
+}
+export interface ConsentMetadata {
+    ipAddress?: string;
+    userAgent?: string;
+    pageUrl?: string;
+    referrer?: string;
+    device?: DeviceInfo;
+    geo?: GeoInfo;
+}
+export interface DeviceInfo {
+    type: 'desktop' | 'mobile' | 'tablet';
+    os?: string;
+    browser?: string;
+}
+export interface GeoInfo {
+    country?: string;
+    region?: string;
+    city?: string;
+}
+export interface ConsentPreferences {
+    essential: boolean;
+    functional: boolean;
+    analytics: boolean;
+    marketing: boolean;
+    personalization: boolean;
+    advertising: boolean;
+    thirdParty: boolean;
+    [key: string]: boolean;
+}
+export interface BannerConfig {
+    title?: string;
+    description?: string;
+    acceptAllText?: string;
+    rejectAllText?: string;
+    customizeText?: string;
+    saveText?: string;
+    privacyPolicyUrl?: string;
+    cookiePolicyUrl?: string;
+    showRejectAll?: boolean;
+    showCustomize?: boolean;
+    showPrivacyPolicy?: boolean;
+    blockerMode?: boolean;
+    purposes?: PurposeConfig[];
+}
+export interface PurposeConfig {
+    id: string;
+    name: string;
+    description: string;
+    required: boolean;
+    defaultEnabled?: boolean;
+    category: PurposeCategory;
+    cookies?: CookieInfo[];
+}
+export interface CookieInfo {
+    name: string;
+    provider: string;
+    purpose: string;
+    expiry: string;
+    type: 'first_party' | 'third_party';
+}
+export interface ConsentEvent {
+    type: ConsentEventType;
+    timestamp: string;
+    data?: any;
+}
+export type ConsentEventType = 'banner_shown' | 'banner_closed' | 'consent_given' | 'consent_withdrawn' | 'preferences_opened' | 'preferences_saved' | 'accept_all' | 'reject_all' | 'category_toggled';
+export interface ConsentResponse {
+    success: boolean;
+    consentId?: string;
+    message?: string;
+    error?: string;
+}
+export interface ConfigResponse {
+    tenantId: string;
+    banner: BannerConfig;
+    purposes: PurposeConfig[];
+    theme: ThemeConfig;
+    regulations: RegulationType[];
+    languages: string[];
+}
+export interface CookieConsentCategory {
+    key: string;
+    name: string;
+    description: string;
+    mandatory: boolean;
+    sort_order: number;
+    known_cookies?: string[];
+}
+export interface CookieConsentUIOptions {
+    accept_all: boolean;
+    reject_all: boolean;
+    customize: boolean;
+}
+export interface CookieConsentBannerConfig {
+    layout: string;
+    position: string;
+    messaging: Record<string, string>;
+    theme: Record<string, string>;
+}
+export interface CookieConsentGeoIntelligence {
+    enabled: boolean;
+    detected_country?: string;
+    detected_regulation?: string;
+    require_consent: boolean;
+    require_explicit_consent: boolean;
+    allow_implied_consent: boolean;
+}
+export interface CookieConsentConfigResponse {
+    tenant_id: string;
+    policy_version: string;
+    language_code: string;
+    categories: CookieConsentCategory[];
+    ui_options: CookieConsentUIOptions;
+    banner?: CookieConsentBannerConfig;
+    geo_intelligence?: CookieConsentGeoIntelligence;
+    consent_mode_map?: Record<string, Record<string, string>>;
+    age_gate_enabled: boolean;
+    age_gate_prompt?: string;
+}
+export interface CookieConsentSubmitResponse {
+    status: string;
+    cookie_consent_id: string;
+    effective_at: string;
+    effective_selections: Record<string, boolean>;
+    expires_at?: string;
+    tc_string?: string;
+    tcf_policy_version?: number;
+}
+export interface TCFData {
+    cmpId: number;
+    cmpVersion: number;
+    gdprApplies: boolean;
+    tcString: string;
+    tcfPolicyVersion: number;
+    isServiceSpecific: boolean;
+    useNonStandardStacks: boolean;
+    purposeOneTreatment: boolean;
+    publisherCC: string;
+    vendorConsents: {
+        [vendorId: number]: boolean;
+    };
+    vendorLegitimateInterests: {
+        [vendorId: number]: boolean;
+    };
+    purposeConsents: {
+        [purposeId: number]: boolean;
+    };
+    purposeLegitimateInterests: {
+        [purposeId: number]: boolean;
+    };
+    specialFeatureOptins: {
+        [featureId: number]: boolean;
+    };
+    publisherRestrictions: PublisherRestriction[];
+}
+export interface PublisherRestriction {
+    purposeId: number;
+    restrictionType: 0 | 1 | 2;
+    vendorIds: number[];
+}
+export interface GPPData {
+    gppString: string;
+    sectionIds: number[];
+    applicableSections: number[];
+}
+declare global {
+    interface Window {
+        ConsentEra?: ConsentEraConsent;
+        __tcfapi?: (command: string, version: number, callback: (...args: any[]) => void, parameter?: any) => void;
+        __gpp?: (command: string, callback: (...args: any[]) => void, parameter?: any) => void;
+    }
+}
+export interface ConsentEraConsent {
+    init(): Promise<void>;
+    showBanner(): void;
+    hideBanner(): void;
+    showPreferences(): void;
+    hidePreferences(): void;
+    acceptAll(): Promise<ConsentResponse>;
+    rejectAll(): Promise<ConsentResponse>;
+    savePreferences(preferences: ConsentPreferences): Promise<ConsentResponse>;
+    getConsent(): ConsentData | null;
+    hasConsent(): boolean;
+    withdrawConsent(purposes?: string[]): Promise<ConsentResponse>;
+    isConsentGiven(purpose: string): boolean;
+    getPreferences(): ConsentPreferences;
+    setLanguage(language: string): void;
+    setAgeDeclaration(isAdult: boolean): void;
+    isAgeGateEnabled(): boolean;
+    getAgeGatePrompt(): string | undefined;
+    on(event: ConsentEventType, callback: (...args: any[]) => void): void;
+    off(event: ConsentEventType, callback: (...args: any[]) => void): void;
+    destroy(): void;
+}

package/dist/types/ui/ConsentBanner.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Consent Banner UI Component
+ */
+import { ConfigResponse, ThemeConfig, ConsentEraConsent as ConsentEraConsentType } from '../types';
+export declare class ConsentBanner {
+    private config;
+    private theme;
+    private sdk;
+    private container;
+    private isVisible;
+    constructor(config: ConfigResponse, theme: ThemeConfig, sdk: ConsentEraConsentType);
+    show(): void;
+    hide(): void;
+    private createBanner;
+    private getBannerHTML;
+    private getDefaultLogo;
+    private attachEventListeners;
+    private handleKeyDown;
+    private injectStyles;
+    private getStyles;
+    destroy(): void;
+}

package/dist/types/ui/PreferenceCenter.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Preference Center UI Component
+ */
+import { ConfigResponse, ThemeConfig, ConsentEraConsent as ConsentEraConsentType } from '../types';
+export declare class PreferenceCenter {
+    private config;
+    private theme;
+    private sdk;
+    private container;
+    private overlay;
+    private isVisible;
+    private preferences;
+    constructor(config: ConfigResponse, theme: ThemeConfig, sdk: ConsentEraConsentType);
+    show(): void;
+    hide(): void;
+    private createPreferenceCenter;
+    private getPreferenceCenterHTML;
+    private attachEventListeners;
+    private handleKeyDown;
+    private savePreferences;
+    private injectStyles;
+    private getStyles;
+    destroy(): void;
+}

package/dist/types/utils/EventEmitter.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Simple Event Emitter
+ */
+/**
+ * A listener. Typed as a variadic rather than `Function` so that
+ * `no-unsafe-function-type` passes and, more usefully, so a caller passing a
+ * non-callable is a compile error rather than a runtime one.
+ */
+export type EventListener = (...args: any[]) => void;
+export declare class EventEmitter {
+    private events;
+    /**
+     * Register event listener
+     */
+    on(event: string, callback: EventListener): void;
+    /**
+     * Remove event listener
+     */
+    off(event: string, callback: EventListener): void;
+    /**
+     * Emit event
+     */
+    emit(event: string, ...args: any[]): void;
+    /**
+     * Register one-time event listener
+     */
+    once(event: string, callback: EventListener): void;
+    /**
+     * Remove all listeners
+     */
+    removeAllListeners(event?: string): void;
+}

package/dist/types/utils/Logger.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Logger utility
+ */
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export declare class Logger {
+    private level;
+    private prefix;
+    constructor(level?: LogLevel);
+    private shouldLog;
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+    setLevel(level: LogLevel): void;
+}
+export {};

package/dist/types/utils/browserStorage.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Consentera Consent SDK — guarded browser storage.
+ *
+ * EVERY ACCESS IS WRAPPED, AND THAT IS NOT DEFENSIVENESS. `localStorage` and
+ * `sessionStorage` THROW rather than return null in ordinary, common
+ * configurations: Safari's private browsing on old versions, a site with
+ * cookies blocked, a sandboxed iframe without `allow-same-origin`, a quota that
+ * is full. Before 2.0.0 `ConsentStorage.save()` called `localStorage.setItem`
+ * bare, so a visitor with storage blocked did not get a degraded banner — they
+ * got an exception out of the middle of a consent write.
+ *
+ * ONE implementation, so the "did we remember to try/catch this one" question
+ * is asked once. `ConsenteraConsent.getOrCreateDeviceId` already had the right
+ * shape; it was the only place that did.
+ *
+ * When storage is unavailable the SDK degrades to a per-page memory map: the
+ * flow still works within the page, it just does not survive a reload. That is
+ * the correct trade for a consent handshake, which is short-lived.
+ */
+export type StorageKind = 'local' | 'session';
+/** The one place key names are spelled, so a reader and a writer cannot drift. */
+export declare const storageKeys: {
+    session: (id: string) => string;
+    callback: (id: string) => string;
+    pendingSync: string;
+    deviceId: string;
+};
+/** True when the real browser store is usable; false when we are on memory. */
+export declare function storageAvailable(kind: StorageKind): boolean;
+export declare function readStored(kind: StorageKind, key: string): string | null;
+/** Returns false when the value could not be persisted anywhere durable. */
+export declare function writeStored(kind: StorageKind, key: string, value: string): boolean;
+export declare function removeStored(kind: StorageKind, key: string): void;
+/** Test seam: drop the memory fallback between cases. */
+export declare function __resetMemoryStorage(): void;

package/dist/types/utils/context.d.ts

@@ -0,0 +1,81 @@
+/**
+ * ConsentEra Consent SDK — Context Helpers
+ * Build client context and affirmative action payloads
+ */
+import { AffirmativeAction, ClientContext, DataPrincipalIdentifiers } from '../types/consent-lifecycle';
+/**
+ * How much of the browser's environment goes to the platform with a consent
+ * mutation.
+ *
+ * DEFAULT IS `minimal`, AND THAT IS A CHANGE IN 2.0.0. Before it, every
+ * update / withdraw / renew carried `page_url: window.location.href`, the
+ * document referrer, the raw User-Agent, the screen resolution and the IANA
+ * timezone — with no way to turn any of it off. A real site's URL routinely
+ * carries an order id, a search term, a reset token, sometimes an email in a
+ * query parameter, so the SDK was shipping the host's own PII to us as a side
+ * effect of recording a consent; and UA + screen + timezone is a standard
+ * fingerprinting triple, collected with nothing stated about the basis for it.
+ *
+ *  - `none`     omit `client_context` entirely.
+ *  - `minimal`  (default) the coarse facts an audit trail actually uses:
+ *               platform, device type, browser family, OS family. No versions,
+ *               no UA string, no screen, no timezone, no URL, no referrer —
+ *               nothing that narrows to a person or carries the host's data.
+ *  - `full`     everything above plus the UA string, versions, screen,
+ *               timezone, referrer and the page URL WITH ITS QUERY AND FRAGMENT
+ *               REMOVED. The query is stripped even here: a Data Fiduciary who
+ *               has decided it needs the query adds it in `beforeSend`, which
+ *               makes that a decision someone took rather than a default.
+ */
+export type ContextMode = 'none' | 'minimal' | 'full';
+/**
+ * Build client context from the current browser environment.
+ *
+ * @param sessionId optional consent session to correlate against
+ * @param mode      how much to collect; see {@link ContextMode}. Default `minimal`.
+ */
+export declare function buildClientContext(sessionId?: string, mode?: ContextMode): ClientContext | undefined;
+/**
+ * Build an affirmative action payload.
+ */
+export declare function buildAffirmativeAction(uiEventId: string, type?: 'button' | 'toggle' | 'checkbox'): AffirmativeAction;
+/**
+ * `PrincipalRef` — the ONE way this SDK names a person on a consent lifecycle
+ * road, and the ONE place that shape is declared.
+ *
+ * ─── WHY A TYPE AND A HELPER RATHER THAN A STRING PARAMETER ───────────────
+ *
+ * The roads used to take `dataPrincipalRef: string` and put it on the wire as
+ * `data_principal_ref`. That field is REFUSED OUTRIGHT since the owner ruling
+ * of 2026-09-21 (consent/lifecycle_identity.go:8-11) — there is no transition
+ * period — so a string parameter can only build a request the API answers 400.
+ *
+ * Making it a union means a caller cannot express the refused request at all:
+ * naming nobody, or naming somebody the old way, is a COMPILE error here
+ * instead of a round trip.
+ *
+ * ONE IMPLEMENTATION ON PURPOSE. validate, bulk validate and every other
+ * find-only lifecycle road ask the identical question, and the API answers it
+ * through a single resolve (`resolveLifecyclePrincipal`,
+ * lifecycle_identity.go). A second copy of this shape in a second file is the
+ * thing that drifts.
+ */
+export type PrincipalRef = {
+    data_principal_id: string;
+    data_principal_identifiers?: never;
+} | {
+    data_principal_identifiers: DataPrincipalIdentifiers;
+    data_principal_id?: never;
+};
+/**
+ * Turn a {@link PrincipalRef} into the request-body fields that name the
+ * person. Sends exactly ONE of the two keys, never both and never an empty
+ * object.
+ *
+ * NEVER BOTH, and that is not tidiness: the API refuses a request carrying
+ * `data_principal_ref` even when `data_principal_id` is also present, for the
+ * stated reason that two fields naming a person can disagree and the caller
+ * would never learn which one the answer was about. Sending one key keeps this
+ * SDK on the right side of that rule by construction.
+ */
+export declare function principalBody(who: PrincipalRef): Record<string, unknown>;

package/dist/types/utils/helpers.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Utility helper functions
+ */
+import { DeviceInfo, GeoInfo } from '../types';
+/**
+ * Generate a unique consent ID
+ */
+export declare function generateConsentId(): string;
+/**
+ * Get device information
+ */
+export declare function getDeviceInfo(): DeviceInfo;
+/**
+ * Get geo information (placeholder - would typically use IP-based service)
+ */
+export declare function getGeoInfo(): GeoInfo;
+/**
+ * Debounce function
+ */
+export declare function debounce<T extends (...args: any[]) => any>(func: T, wait: number): (...args: Parameters<T>) => void;
+/**
+ * Throttle function
+ */
+export declare function throttle<T extends (...args: any[]) => any>(func: T, limit: number): (...args: Parameters<T>) => void;
+/**
+ * Deep merge objects
+ */
+export declare function deepMerge<T extends object>(target: T, ...sources: Partial<T>[]): T;
+/**
+ * Parse cookie string
+ */
+export declare function parseCookies(cookieString: string): Record<string, string>;
+/**
+ * Check if running in browser
+ */
+export declare function isBrowser(): boolean;
+/**
+ * Check if third-party cookies are supported
+ */
+export declare function checkThirdPartyCookies(): Promise<boolean>;
+/**
+ * Get language from browser
+ */
+export declare function getBrowserLanguage(): string;
+/**
+ * Format date for display
+ */
+export declare function formatDate(date: Date | string): string;