@tantainnovative/ndpr-toolkit 3.4.0 → 3.5.0

package/dist/consent.d.mts

@@ -1,84 +1,648 @@
-import { c as ConsentBannerProps } from './ConsentBanner-F5ayys5K.mjs';
-export { C as ConsentAnalyticsEvent, a as ConsentBanner, b as ConsentBannerClassNames } from './ConsentBanner-F5ayys5K.mjs';
-import { b as ConsentManagerProps } from './ConsentManager-C7I3PDe8.mjs';
-export { C as ConsentManager, a as ConsentManagerClassNames } from './ConsentManager-C7I3PDe8.mjs';
-import { b as ConsentStorageProps } from './styling-BMDGQDgS.mjs';
-export { C as ConsentStorage, a as ConsentStorageClassNames, r as resolveClass } from './styling-BMDGQDgS.mjs';
-export { u as useConsent } from './useConsent-DCNkIJHR.mjs';
-export { C as ConsentAuditEntry, a as appendAuditEntry, c as createAuditEntry, g as getAuditLog, v as validateConsent, b as validateConsentOptions } from './consent-audit-BdByjYlM.mjs';
-import { C as ConsentOption, a as ConsentSettings } from './consent-CmVzqZUk.mjs';
-export { b as ConsentStorageOptions, L as LawfulBasisType } from './consent-CmVzqZUk.mjs';
-import * as React$1 from 'react';
-import React__default from 'react';
-import { S as StorageAdapter } from './types-DK2CoKOC.mjs';
-
-interface SaveButtonProps {
-    children?: React__default.ReactNode;
-    className?: string;
-    unstyled?: boolean;
-    consents?: Record<string, boolean>;
-}
-declare const SaveButton: React__default.FC<SaveButtonProps>;
-
-interface RejectButtonProps {
-    children?: React__default.ReactNode;
-    className?: string;
-    unstyled?: boolean;
-}
-declare const RejectButton: React__default.FC<RejectButtonProps>;
-
-interface AcceptButtonProps {
-    children?: React__default.ReactNode;
-    className?: string;
-    unstyled?: boolean;
-}
-declare const AcceptButton: React__default.FC<AcceptButtonProps>;
-
-interface OptionListProps {
-    classNames?: {
-        root?: string;
-        optionItem?: string;
-        optionCheckbox?: string;
-        optionLabel?: string;
-        optionDescription?: string;
-    };
-    unstyled?: boolean;
-}
-declare const OptionList: React__default.FC<OptionListProps>;
-
-interface ConsentProviderProps {
-    options: ConsentOption[];
-    adapter?: StorageAdapter<ConsentSettings>;
-    version?: string;
-    onChange?: (settings: ConsentSettings) => void;
-    children: React__default.ReactNode;
-}
-declare const ConsentProvider: React__default.FC<ConsentProviderProps>;
-
-declare const Consent: {
-    Provider: React$1.FC<ConsentProviderProps>;
-    OptionList: React$1.FC<OptionListProps>;
-    AcceptButton: React$1.FC<AcceptButtonProps>;
-    RejectButton: React$1.FC<RejectButtonProps>;
-    SaveButton: React$1.FC<SaveButtonProps>;
-    Banner: React$1.FC<ConsentBannerProps>;
-    Settings: React$1.FC<ConsentManagerProps>;
-    Storage: ({ settings, storageOptions, onLoad, onSave, autoSave, autoLoad, classNames, unstyled, children }: ConsentStorageProps) => React.ReactElement | null;
-};
-
-interface ConsentContextValue {
-    options: ConsentOption[];
-    settings: ConsentSettings | null;
-    hasConsent: (optionId: string) => boolean;
-    updateConsent: (consents: Record<string, boolean>) => void;
-    acceptAll: () => void;
-    rejectAll: () => void;
-    shouldShowBanner: boolean;
-    isValid: boolean;
-    validationErrors: string[];
-    resetConsent: () => void;
-    isLoading: boolean;
-}
-declare function useConsentCompound(): ConsentContextValue;
-
-export { Consent, AcceptButton as ConsentAcceptButton, ConsentOption, OptionList as ConsentOptionList, ConsentProvider, type ConsentProviderProps, RejectButton as ConsentRejectButton, SaveButton as ConsentSaveButton, ConsentSettings, StorageAdapter, useConsentCompound };
+import * as React$1 from 'react';
+import React__default from 'react';
+
+declare interface AcceptButtonProps {
+    children?: React__default.ReactNode;
+    className?: string;
+    unstyled?: boolean;
+}
+
+/**
+ * Appends a single audit entry to the consent audit log in localStorage.
+ * The log is append-only; existing entries are never modified.
+ *
+ * @param entry     - The audit entry to append
+ * @param storageKey - Base storage key (the audit key is derived as `${storageKey}_audit`)
+ */
+export declare function appendAuditEntry(entry: ConsentAuditEntry, storageKey?: string): void;
+
+export declare const Consent: {
+    Provider: React$1.FC<ConsentProviderProps>;
+    OptionList: React$1.FC<OptionListProps>;
+    AcceptButton: React$1.FC<AcceptButtonProps>;
+    RejectButton: React$1.FC<RejectButtonProps>;
+    SaveButton: React$1.FC<SaveButtonProps>;
+    Banner: React$1.FC<ConsentBannerProps>;
+    Settings: React$1.FC<ConsentManagerProps>;
+    Storage: ({ settings, storageOptions, onLoad, onSave, autoSave, autoLoad, classNames, unstyled, children }: ConsentStorageProps) => React.ReactElement | null;
+};
+
+export declare const ConsentAcceptButton: React__default.FC<AcceptButtonProps>;
+
+export declare interface ConsentAnalyticsEvent {
+    action: 'shown' | 'accepted_all' | 'rejected_all' | 'customized' | 'dismissed';
+    timestamp: number;
+    version: string;
+    categories?: Record<string, boolean>;
+}
+
+/**
+ * Represents a single entry in the consent audit trail.
+ * Each entry captures what happened, when, and the full consent state
+ * at that point in time, satisfying NDPA recordkeeping requirements.
+ */
+export declare interface ConsentAuditEntry {
+    /** The type of consent action that occurred */
+    action: 'consent_given' | 'consent_withdrawn' | 'consent_updated' | 'consent_expired';
+    /** Unix timestamp (ms) when the action occurred */
+    timestamp: number;
+    /** Version of the consent form at the time of the action */
+    version: string;
+    /** Full snapshot of consent category states */
+    categories: Record<string, boolean>;
+    /** How consent was collected (e.g. "banner", "customize", "api") */
+    method: string;
+    /** Browser user-agent string for forensic traceability */
+    userAgent?: string;
+}
+
+/**
+ * Consent banner component. Implements NDPA Sections 25-26 consent requirements
+ * for obtaining and managing data subject consent.
+ */
+export declare const ConsentBanner: React__default.FC<ConsentBannerProps>;
+
+export declare interface ConsentBannerClassNames {
+    root?: string;
+    container?: string;
+    title?: string;
+    description?: string;
+    optionsList?: string;
+    optionItem?: string;
+    optionCheckbox?: string;
+    optionLabel?: string;
+    optionDescription?: string;
+    buttonGroup?: string;
+    acceptButton?: string;
+    rejectButton?: string;
+    customizeButton?: string;
+    saveButton?: string;
+    customizePanel?: string;
+    selectAllButton?: string;
+    /** Alias for acceptButton */
+    primaryButton?: string;
+    /** Alias for rejectButton */
+    secondaryButton?: string;
+}
+
+declare interface ConsentBannerProps {
+    /**
+     * Array of consent options to display
+     */
+    options: ConsentOption[];
+    /**
+     * Callback function called when user saves their consent choices
+     */
+    onSave: (settings: ConsentSettings) => void;
+    /**
+     * Title displayed on the banner
+     * @default "We Value Your Privacy"
+     */
+    title?: string;
+    /**
+     * Description text displayed on the banner
+     * @default "We use cookies and similar technologies to provide our services and enhance your experience. Your consent is collected in accordance with NDPA Sections 25-26."
+     */
+    description?: string;
+    /**
+     * Text for the accept all button
+     * @default "Accept All"
+     */
+    acceptAllButtonText?: string;
+    /**
+     * Text for the reject all button
+     * @default "Reject All"
+     */
+    rejectAllButtonText?: string;
+    /**
+     * Text for the customize button
+     * @default "Customize"
+     */
+    customizeButtonText?: string;
+    /**
+     * Text for the save button
+     * @default "Save Preferences"
+     */
+    saveButtonText?: string;
+    /**
+     * Position of the banner.
+     * 'top', 'bottom', and 'center' render via a portal to document.body
+     * with fixed positioning so the banner overlays the page.
+     * 'inline' renders in the normal DOM tree without a portal.
+     * @default "bottom"
+     */
+    position?: 'top' | 'bottom' | 'center' | 'inline';
+    /**
+     * Visual treatment.
+     * - 'bar'   (default): full-width strip pinned to the edge.
+     * - 'card'  : bounded floating card with rounded corners and a margin
+     *             from the screen edges. Pairs well with `position="bottom"`.
+     * - 'modal' : centered card with a backdrop overlay. Forces center
+     *             placement regardless of `position`.
+     * @default "bar"
+     */
+    variant?: 'bar' | 'card' | 'modal';
+    /**
+     * z-index applied to the fixed-position banner.
+     * Ignored when position is 'inline'.
+     * @default 9999
+     */
+    zIndex?: number;
+    /**
+     * Version of the consent form
+     * @default "1.0"
+     */
+    version?: string;
+    /**
+     * Whether to show the banner
+     * If not provided, the banner will be shown if no consent has been saved
+     */
+    show?: boolean;
+    /**
+     * Storage key for consent settings
+     * @default "ndpr_consent"
+     */
+    storageKey?: string;
+    /**
+     * Whether the banner manages its own localStorage persistence.
+     * Set to false when an external storage mechanism (e.g., ConsentStorage)
+     * is responsible for persisting consent settings under the same key.
+     * This avoids race conditions where two writers target the same storage key.
+     * @default true
+     */
+    manageStorage?: boolean;
+    /**
+     * Custom CSS class for the banner
+     */
+    className?: string;
+    /**
+     * Custom CSS class for the buttons
+     */
+    buttonClassName?: string;
+    /**
+     * Custom CSS class for the primary button
+     */
+    primaryButtonClassName?: string;
+    /**
+     * Custom CSS class for the secondary button
+     */
+    secondaryButtonClassName?: string;
+    /**
+     * Object of CSS class overrides keyed by semantic section name.
+     * Takes priority over buttonClassName / primaryButtonClassName / secondaryButtonClassName.
+     */
+    classNames?: ConsentBannerClassNames;
+    /**
+     * When true, all default Tailwind classes are removed so consumers
+     * can style from scratch using classNames.
+     */
+    unstyled?: boolean;
+    /**
+     * Optional analytics callback fired on each user interaction.
+     * Called when the banner is shown, accepted, rejected, customized, or dismissed.
+     */
+    onAnalytics?: (event: ConsentAnalyticsEvent) => void;
+}
+
+declare interface ConsentContextValue {
+    options: ConsentOption[];
+    settings: ConsentSettings | null;
+    hasConsent: (optionId: string) => boolean;
+    updateConsent: (consents: Record<string, boolean>) => void;
+    acceptAll: () => void;
+    rejectAll: () => void;
+    shouldShowBanner: boolean;
+    isValid: boolean;
+    validationErrors: string[];
+    resetConsent: () => void;
+    isLoading: boolean;
+}
+
+/**
+ * Consent management component. Implements NDPA Sections 25-26 consent requirements,
+ * allowing data subjects to review and update their consent preferences.
+ */
+export declare const ConsentManager: React__default.FC<ConsentManagerProps>;
+
+export declare interface ConsentManagerClassNames {
+    root?: string;
+    header?: string;
+    title?: string;
+    description?: string;
+    optionsList?: string;
+    optionItem?: string;
+    toggle?: string;
+    saveButton?: string;
+    resetButton?: string;
+    /** Alias for saveButton */
+    primaryButton?: string;
+    /** Alias for resetButton */
+    secondaryButton?: string;
+}
+
+declare interface ConsentManagerProps {
+    /**
+     * Array of consent options to display
+     */
+    options: ConsentOption[];
+    /**
+     * Current consent settings
+     */
+    settings?: ConsentSettings;
+    /**
+     * Callback function called when user saves their consent choices
+     */
+    onSave: (settings: ConsentSettings) => void;
+    /**
+     * Title displayed in the manager
+     * @default "Manage Your Privacy Settings"
+     */
+    title?: string;
+    /**
+     * Description text displayed in the manager
+     * @default "Update your consent preferences at any time. Required cookies cannot be disabled as they are necessary for the website to function. Consent management is provided in accordance with NDPA Sections 25-26."
+     */
+    description?: string;
+    /**
+     * Text for the save button
+     * @default "Save Preferences"
+     */
+    saveButtonText?: string;
+    /**
+     * Text for the reset button
+     * @default "Reset to Defaults"
+     */
+    resetButtonText?: string;
+    /**
+     * Version of the consent form
+     * @default "1.0"
+     */
+    version?: string;
+    /**
+     * Custom CSS class for the manager
+     */
+    className?: string;
+    /**
+     * Custom CSS class for the buttons
+     */
+    buttonClassName?: string;
+    /**
+     * Custom CSS class for the primary button
+     */
+    primaryButtonClassName?: string;
+    /**
+     * Custom CSS class for the secondary button
+     */
+    secondaryButtonClassName?: string;
+    /**
+     * Object of CSS class overrides keyed by semantic section name.
+     * Takes priority over buttonClassName / primaryButtonClassName / secondaryButtonClassName.
+     */
+    classNames?: ConsentManagerClassNames;
+    /**
+     * When true, all default Tailwind classes are removed so consumers
+     * can style from scratch using classNames.
+     */
+    unstyled?: boolean;
+    /**
+     * Whether to show a success message after saving
+     * @default true
+     */
+    showSuccessMessage?: boolean;
+    /**
+     * Success message to display after saving
+     * @default "Your preferences have been saved."
+     */
+    successMessage?: string;
+    /**
+     * Duration to show the success message (in milliseconds)
+     * @default 3000
+     */
+    successMessageDuration?: number;
+}
+
+/**
+ * Consent types aligned with NDPA 2023 Section 25-26
+ * Consent must be freely given, specific, informed, and unambiguous
+ */
+/**
+ * Represents a consent option that can be presented to users
+ */
+export declare interface ConsentOption {
+    /** Unique identifier for the consent option */
+    id: string;
+    /** Display label for the consent option */
+    label: string;
+    /** Detailed description of what this consent option covers */
+    description: string;
+    /** Whether this consent option is required (cannot be declined) */
+    required: boolean;
+    /**
+     * The specific purpose for which data will be processed
+     * NDPA Section 25(2) requires consent to be specific to each purpose
+     */
+    purpose: string;
+    /**
+     * Default state of the consent option
+     * @default false
+     */
+    defaultValue?: boolean;
+    /**
+     * Categories of personal data covered by this consent option
+     */
+    dataCategories?: string[];
+}
+
+export declare const ConsentOptionList: React__default.FC<OptionListProps>;
+
+export declare const ConsentProvider: React__default.FC<ConsentProviderProps>;
+
+export declare interface ConsentProviderProps {
+    options: ConsentOption[];
+    adapter?: StorageAdapter<ConsentSettings>;
+    version?: string;
+    onChange?: (settings: ConsentSettings) => void;
+    children: React__default.ReactNode;
+}
+
+export declare const ConsentRejectButton: React__default.FC<RejectButtonProps>;
+
+export declare const ConsentSaveButton: React__default.FC<SaveButtonProps>;
+
+/**
+ * Represents the user's consent settings
+ */
+export declare interface ConsentSettings {
+    /** Map of consent option IDs to boolean values indicating consent status */
+    consents: Record<string, boolean>;
+    /** Timestamp when consent was last updated */
+    timestamp: number;
+    /** Version of the consent form that was accepted */
+    version: string;
+    /** Method used to collect consent (e.g., "banner", "settings", "api") */
+    method: string;
+    /** Whether the user has actively made a choice (as opposed to default settings) */
+    hasInteracted: boolean;
+    /**
+     * The lawful basis under which processing is conducted
+     * Required by NDPA Section 25(1)
+     */
+    lawfulBasis?: LawfulBasisType;
+}
+
+export declare const ConsentStorage: ({ settings, storageOptions, onLoad, onSave, autoSave, autoLoad, classNames, unstyled, children }: ConsentStorageProps) => React__default.ReactElement | null;
+
+export declare interface ConsentStorageClassNames {
+    root?: string;
+}
+
+/**
+ * Represents the storage mechanism for consent settings
+ */
+export declare interface ConsentStorageOptions {
+    /**
+     * Storage key for consent settings
+     * @default "ndpr_consent"
+     */
+    storageKey?: string;
+    /**
+     * Storage type to use
+     * @default "localStorage"
+     */
+    storageType?: 'localStorage' | 'sessionStorage' | 'cookie';
+    /**
+     * Cookie options (only used when storageType is "cookie")
+     */
+    cookieOptions?: {
+        /** Domain for the cookie */
+        domain?: string;
+        /**
+         * Path for the cookie
+         * @default "/"
+         */
+        path?: string;
+        /**
+         * Expiration days for the cookie
+         * @default 365
+         */
+        expires?: number;
+        /**
+         * Whether the cookie should be secure
+         * @default true
+         */
+        secure?: boolean;
+        /**
+         * SameSite attribute for the cookie
+         * @default "Lax"
+         */
+        sameSite?: 'Strict' | 'Lax' | 'None';
+    };
+}
+
+declare interface ConsentStorageProps {
+    /**
+     * Current consent settings
+     */
+    settings: ConsentSettings;
+    /**
+     * Storage options for consent settings
+     */
+    storageOptions?: ConsentStorageOptions;
+    /**
+     * Callback function called when settings are loaded from storage
+     */
+    onLoad?: (settings: ConsentSettings | null) => void;
+    /**
+     * Callback function called when settings are saved to storage
+     */
+    onSave?: (settings: ConsentSettings) => void;
+    /**
+     * Whether to automatically save settings to storage
+     * @default true
+     */
+    autoSave?: boolean;
+    /**
+     * Whether to automatically load settings from storage on mount
+     * @default true
+     */
+    autoLoad?: boolean;
+    /**
+     * Object of CSS class overrides keyed by semantic section name.
+     */
+    classNames?: ConsentStorageClassNames;
+    /**
+     * When true, all default classes are removed so consumers
+     * can style from scratch using classNames.
+     */
+    unstyled?: boolean;
+    /**
+     * Children to render
+     * Can be either React nodes or a render prop function that receives storage methods
+     */
+    children?: React__default.ReactNode | ((props: {
+        loadSettings: () => ConsentSettings | null;
+        saveSettings: (settings: ConsentSettings) => void;
+        clearSettings: () => void;
+        loaded: boolean;
+    }) => React__default.ReactNode);
+}
+
+/**
+ * Creates a new audit entry from consent settings. If `previousSettings` is
+ * provided, the action is automatically determined by comparing old and new
+ * states. Otherwise `action` defaults to `'consent_given'`.
+ */
+export declare function createAuditEntry(settings: ConsentSettings, previousSettings?: ConsentSettings | null, actionOverride?: ConsentAuditEntry['action']): ConsentAuditEntry;
+
+/**
+ * Retrieves the full consent audit log from localStorage.
+ * Returns an empty array if no log exists or parsing fails.
+ *
+ * @param storageKey - Base storage key (the audit key is derived as `${storageKey}_audit`)
+ */
+export declare function getAuditLog(storageKey?: string): ConsentAuditEntry[];
+
+/**
+ * Lawful basis for processing personal data per NDPA Section 25(1)
+ */
+export declare type LawfulBasisType = 'consent' | 'contract' | 'legal_obligation' | 'vital_interests' | 'public_interest' | 'legitimate_interests';
+
+declare interface OptionListProps {
+    classNames?: {
+        root?: string;
+        optionItem?: string;
+        optionCheckbox?: string;
+        optionLabel?: string;
+        optionDescription?: string;
+    };
+    unstyled?: boolean;
+}
+
+declare interface RejectButtonProps {
+    children?: React__default.ReactNode;
+    className?: string;
+    unstyled?: boolean;
+}
+
+/**
+ * Resolves class names for a component section.
+ * If unstyled is true, only the override class is used (or empty string).
+ * If an override is provided, it fully REPLACES the default — no appending.
+ * Otherwise the default class string is returned as-is.
+ */
+export declare function resolveClass(defaultClass: string, override?: string, unstyled?: boolean): string;
+
+declare interface SaveButtonProps {
+    children?: React__default.ReactNode;
+    className?: string;
+    unstyled?: boolean;
+    consents?: Record<string, boolean>;
+}
+
+export declare interface StorageAdapter<T = unknown> {
+    /** Load persisted data. Called once on hook mount. */
+    load(): T | null | Promise<T | null>;
+    /** Persist data. Called on every state change. */
+    save(data: T): void | Promise<void>;
+    /** Clear persisted data. Called on reset. */
+    remove(): void | Promise<void>;
+}
+
+/**
+ * Hook for managing user consent in compliance with NDPA
+ */
+export declare function useConsent({ options, adapter, storageOptions, version, onChange, }: UseConsentOptions): UseConsentReturn;
+
+export declare function useConsentCompound(): ConsentContextValue;
+
+declare interface UseConsentOptions {
+    /**
+     * Consent options to present to the user
+     */
+    options: ConsentOption[];
+    /**
+     * Pluggable storage adapter. When provided, takes precedence over storageOptions.
+     */
+    adapter?: StorageAdapter<ConsentSettings>;
+    /**
+     * Storage options for consent settings
+     * @deprecated Use adapter instead
+     */
+    storageOptions?: ConsentStorageOptions;
+    /**
+     * Version of the consent form
+     * @default "1.0"
+     */
+    version?: string;
+    /**
+     * Callback function called when consent settings change
+     */
+    onChange?: (settings: ConsentSettings) => void;
+}
+
+declare interface UseConsentReturn {
+    /**
+     * Current consent settings
+     */
+    settings: ConsentSettings | null;
+    /**
+     * Whether consent has been given for a specific option
+     */
+    hasConsent: (optionId: string) => boolean;
+    /**
+     * Update consent settings
+     */
+    updateConsent: (consents: Record<string, boolean>) => void;
+    /**
+     * Accept all consent options
+     */
+    acceptAll: () => void;
+    /**
+     * Reject all non-required consent options
+     */
+    rejectAll: () => void;
+    /**
+     * Whether the consent banner should be shown
+     */
+    shouldShowBanner: boolean;
+    /**
+     * Whether consent settings are valid
+     */
+    isValid: boolean;
+    /**
+     * Validation errors (if any)
+     */
+    validationErrors: string[];
+    /**
+     * Reset consent settings (clear from storage)
+     */
+    resetConsent: () => void;
+    /**
+     * Whether the adapter is still loading data (relevant for async adapters)
+     */
+    isLoading: boolean;
+}
+
+/**
+ * Validates consent settings to ensure they meet NDPA requirements
+ * @param settings The consent settings to validate
+ * @returns An object containing validation result and any error messages
+ */
+export declare function validateConsent(settings: ConsentSettings): {
+    valid: boolean;
+    errors: string[];
+};
+
+/**
+ * Validates that consent options meet NDPA Section 26 requirements.
+ * Each consent option must specify a purpose for which data will be processed,
+ * as consent must be specific and informed per the Nigeria Data Protection Act.
+ * @param options The consent options to validate
+ * @returns An object containing validation result and any error messages
+ */
+export declare function validateConsentOptions(options: ConsentOption[]): {
+    valid: boolean;
+    errors: string[];
+};
+
+export { }