c15t 0.0.1-rc.3

package/src/types/callbacks.ts

@@ -0,0 +1,152 @@
+/**
+ * A generic type for callback functions that can accept an argument of type T.
+ *
+ * @typeParam T - The type of the argument that the callback function accepts. Defaults to `void` if not specified.
+ *
+ * @remarks
+ * This type is used throughout the consent management system to define callback functions
+ * with consistent typing. It ensures type safety when passing callbacks between components.
+ *
+ * @example
+ * ```typescript
+ * // Callback with no arguments
+ * const readyCallback: CallbackFunction = () => {
+ *   console.log('System ready');
+ * };
+ *
+ * // Callback with string argument
+ * const errorCallback: CallbackFunction<string> = (errorMessage) => {
+ *   console.error('Error occurred:', errorMessage);
+ * };
+ * ```
+ *
+ * @public
+ */
+export type CallbackFunction<T = void> = (arg: T) => void;
+
+/**
+ * Defines the structure for callback functions that respond to consent-related events.
+ * These callbacks enable custom actions at different stages of the consent management process.
+ *
+ * @remarks
+ * All callbacks are optional and will be called at specific points in the consent management lifecycle:
+ *
+ * Initialization callbacks:
+ * - `onReady`: System initialization complete, ready to handle consent
+ * - `onError`: Error occurred during operation
+ *
+ * Banner interaction callbacks:
+ * - `onBannerShown`: Consent banner has been displayed
+ * - `onBannerClosed`: User has closed the consent banner
+ *
+ * Consent decision callbacks:
+ * - `onConsentGiven`: User has granted consent
+ * - `onConsentRejected`: User has rejected consent
+ * - `onPreferenceExpressed`: User has made their preferences known
+ *
+ * @example
+ * Basic usage with TypeScript:
+ * ```typescript
+ * const callbacks: Callbacks = {
+ *   onReady: () => {
+ *     console.log('Consent manager ready');
+ *   },
+ *   onError: (error) => {
+ *     console.error('Consent manager error:', error);
+ *   },
+ *   onConsentGiven: () => {
+ *     initializeAnalytics();
+ *   }
+ * };
+ * ```
+ *
+ * @example
+ * Full implementation with all callbacks:
+ * ```typescript
+ * const consentCallbacks: Callbacks = {
+ *   onReady: () => {
+ *     console.log('Consent manager initialized');
+ *     checkInitialConsent();
+ *   },
+ *
+ *   onBannerShown: () => {
+ *     logBannerImpression();
+ *     pauseBackgroundVideos();
+ *   },
+ *
+ *   onBannerClosed: () => {
+ *     resumeBackgroundVideos();
+ *     updateUIState('banner-closed');
+ *   },
+ *
+ *   onConsentGiven: () => {
+ *     enableTracking();
+ *     initializeServices();
+ *   },
+ *
+ *   onConsentRejected: () => {
+ *     disableTracking();
+ *     updatePrivacyMode('strict');
+ *   },
+ *
+ *   onPreferenceExpressed: () => {
+ *     saveUserPreferences();
+ *     updateUI();
+ *   },
+ *
+ *   onError: (errorMessage) => {
+ *     console.error('Consent Error:', errorMessage);
+ *     notifyAdministrator(errorMessage);
+ *   }
+ * };
+ * ```
+ *
+ * @example
+ * Usage with React:
+ * ```tsx
+ * function ConsentManager() {
+ *   const callbacks: Callbacks = useMemo(() => ({
+ *     onReady: () => setIsReady(true),
+ *     onBannerShown: () => trackEvent('banner-shown'),
+ *     onConsentGiven: () => {
+ *       initializeAnalytics();
+ *       refreshAds();
+ *     }
+ *   }), []);
+ *
+ *   return (
+ *     <ConsentProvider callbacks={callbacks}>
+ *       {children}
+ *     </ConsentProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @see {@link CallbackFunction} For the type definition of individual callbacks
+ * @public
+ */
+export interface Callbacks {
+	/** Called when the consent management system is fully initialized and ready */
+	onReady?: CallbackFunction;
+
+	/** Called when the consent banner becomes visible to the user */
+	onBannerShown?: CallbackFunction;
+
+	/** Called when the consent banner is dismissed or hidden */
+	onBannerClosed?: CallbackFunction;
+
+	/** Called when the user grants consent for one or more purposes */
+	onConsentGiven?: CallbackFunction;
+
+	/** Called when the user denies consent for one or more purposes */
+	onConsentRejected?: CallbackFunction;
+
+	/** Called when the user makes any change to their consent preferences */
+	onPreferenceExpressed?: CallbackFunction;
+
+	/**
+	 * Called when an error occurs in the consent management system
+	 * @param errorMessage - A description of the error that occurred
+	 */
+	onError?: CallbackFunction<string>;
+}

package/src/types/compliance.ts

@@ -0,0 +1,205 @@
+import type { AllConsentNames } from './gdpr';
+
+/**
+ * @packageDocumentation
+ * Provides types and interfaces for managing privacy compliance and consent across different regulatory frameworks.
+ */
+
+/**
+ * Represents the state of consents for different types of data processing.
+ *
+ * @remarks
+ * Maps each consent type to a boolean indicating whether consent has been granted.
+ * The consent types are defined by {@link AllConsentNames} and typically include
+ * categories like 'necessary', 'functional', 'analytics', etc.
+ *
+ * @example
+ * ```typescript
+ * const consentState: ConsentState = {
+ *   necessary: true,    // Required functionality
+ *   functional: true,   // Enhanced features
+ *   analytics: false,   // Usage tracking
+ *   marketing: false    // Marketing cookies
+ * };
+ * ```
+ *
+ * @public
+ */
+export type ConsentState = Record<AllConsentNames, boolean>;
+
+/**
+ * Defines supported privacy regulation frameworks and regions.
+ *
+ * @remarks
+ * Each region represents a different privacy regulation framework:
+ * - `gdpr`: European Union's General Data Protection Regulation
+ * - `ccpa`: California Consumer Privacy Act
+ * - `lgpd`: Brazil's Lei Geral de Proteção de Dados
+ * - `usStatePrivacy`: Other U.S. state privacy laws (e.g., VCDPA, CPA)
+ *
+ * @example
+ * ```typescript
+ * function isRegionCompliant(region: ComplianceRegion): boolean {
+ *   switch (region) {
+ *     case 'gdpr':
+ *       return checkGDPRCompliance();
+ *     case 'ccpa':
+ *       return checkCCPACompliance();
+ *     // ... handle other regions
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export type ComplianceRegion = 'gdpr' | 'ccpa' | 'lgpd' | 'usStatePrivacy';
+
+/**
+ * Configuration settings for privacy regulation compliance.
+ *
+ * @remarks
+ * These settings determine how privacy regulations are enforced:
+ * - `enabled`: Activates or deactivates the compliance framework
+ * - `appliesGlobally`: Whether to apply these rules worldwide
+ * - `applies`: Whether the regulation applies in the current context
+ *
+ * @example
+ * ```typescript
+ * const gdprSettings: ComplianceSettings = {
+ *   enabled: true,              // GDPR compliance is active
+ *   appliesGlobally: false,     // Only applies to EU users
+ *   applies: isEUUser()         // Dynamically check if user is in EU
+ * };
+ *
+ * const ccpaSettings: ComplianceSettings = {
+ *   enabled: true,
+ *   appliesGlobally: false,
+ *   applies: isCaliforniaUser() // Check if user is in California
+ * };
+ * ```
+ *
+ * @see {@link ComplianceRegion} for available regions
+ * @public
+ */
+export type ComplianceSettings = {
+	/** Whether the compliance framework is active */
+	enabled: boolean;
+
+	/** Whether to apply compliance rules globally */
+	appliesGlobally: boolean;
+
+	/** Whether the regulation applies in current context */
+	applies: boolean | undefined;
+};
+
+/**
+ * User privacy preference configuration.
+ *
+ * @remarks
+ * Contains settings that affect how user privacy preferences are handled:
+ * - `honorDoNotTrack`: Respects the browser's DNT (Do Not Track) setting
+ *
+ * When `honorDoNotTrack` is true and the user has enabled DNT in their browser:
+ * - All non-essential tracking will be disabled
+ * - Only necessary cookies will be allowed
+ * - Analytics and marketing features will be disabled
+ *
+ * @example
+ * ```typescript
+ * const privacySettings: PrivacySettings = {
+ *   honorDoNotTrack: true // Respect browser's DNT setting
+ * };
+ *
+ * function shouldTrack(): boolean {
+ *   return !(
+ *     privacySettings.honorDoNotTrack &&
+ *     navigator.doNotTrack === "1"
+ *   );
+ * }
+ * ```
+ *
+ * @public
+ */
+export type PrivacySettings = {
+	/** Whether to respect the browser's Do Not Track setting */
+	honorDoNotTrack: boolean;
+};
+
+/**
+ * Records information about a user's consent decision.
+ *
+ * @remarks
+ * This type tracks when and how consent was given:
+ * - `time`: Unix timestamp of when consent was given
+ * - `type`: The scope of consent granted
+ *   - `'all'`: Accepted all consent types
+ *   - `'custom'`: Selected specific consent types
+ *   - `'necessary'`: Only accepted necessary cookies
+ *
+ * Can be `null` if no consent has been recorded yet.
+ *
+ * @example
+ * ```typescript
+ * // User accepted all cookies
+ * const fullConsent: HasConsentedProps = {
+ *   time: Date.now(),
+ *   type: 'all'
+ * };
+ *
+ * // User customized their consent
+ * const customConsent: HasConsentedProps = {
+ *   time: Date.now(),
+ *   type: 'custom'
+ * };
+ *
+ * // No consent recorded yet
+ * const noConsent: HasConsentedProps = null;
+ * ```
+ *
+ * @public
+ */
+export type HasConsentedProps = {
+	/** Timestamp when consent was given */
+	time: number;
+
+	/** Type of consent granted */
+	type: 'all' | 'custom' | 'necessary';
+} | null;
+
+/**
+ * Configuration for the consent manager's namespace.
+ *
+ * @remarks
+ * The namespace is used to:
+ * - Isolate consent manager instances
+ * - Prevent conflicts with other global variables
+ * - Support multiple consent managers on the same page
+ * - Maintain state persistence across page loads
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with default namespace
+ * const defaultConfig: NamespaceProps = {};
+ *
+ * // Custom namespace for multiple instances
+ * const customConfig: NamespaceProps = {
+ *   namespace: 'MyAppConsent'
+ * };
+ *
+ * // Multiple consent managers
+ * const configs = {
+ *   main: { namespace: 'MainAppConsent' },
+ *   subsite: { namespace: 'SubsiteConsent' }
+ * };
+ * ```
+ *
+ * @public
+ */
+export type NamespaceProps = {
+	/**
+	 * Global namespace for the consent manager store.
+	 *
+	 * @defaultValue "c15tStore"
+	 */
+	namespace?: string;
+};

package/src/types/gdpr.ts

@@ -0,0 +1,217 @@
+/**
+ * @packageDocumentation
+ * Provides types and constants for managing GDPR-compliant consent categories and their configurations.
+ */
+
+/**
+ * Defines all possible consent categories that can be managed within the application.
+ *
+ * @remarks
+ * Each consent type represents a specific category of data processing:
+ *
+ * - `necessary`: Essential cookies required for basic site functionality
+ * - `functionality`: Cookies that enable enhanced features and personalization
+ * - `marketing`: Cookies used for advertising and marketing purposes
+ * - `measurement`: Analytics and performance measurement cookies
+ * - `experience`: Cookies that improve user experience and interactions
+ *
+ * @example
+ * ```typescript
+ * function isConsentRequired(type: AllConsentNames): boolean {
+ *   return type !== 'necessary';
+ * }
+ *
+ * function enableFeature(type: AllConsentNames, hasConsent: boolean) {
+ *   switch (type) {
+ *     case 'marketing':
+ *       hasConsent ? enableAds() : disableAds();
+ *       break;
+ *     case 'measurement':
+ *       hasConsent ? enableAnalytics() : disableAnalytics();
+ *       break;
+ *     // ... handle other types
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export type AllConsentNames =
+	| 'experience'
+	| 'functionality'
+	| 'marketing'
+	| 'measurement'
+	| 'necessary';
+
+/**
+ * Defines the configuration structure for each consent type.
+ *
+ * @remarks
+ * Each consent type has specific properties that determine its behavior:
+ *
+ * - `defaultValue`: Initial consent state
+ *   - `true`: Consent is granted by default (typically only for 'necessary' cookies)
+ *   - `false`: User must explicitly grant consent
+ *
+ * - `description`: User-friendly explanation of the consent category
+ *   - Should be clear and concise
+ *   - Must accurately describe data usage
+ *   - Should help users make informed decisions
+ *
+ * - `disabled`: Whether users can modify this consent
+ *   - `true`: Users cannot change the consent state (e.g., necessary cookies)
+ *   - `false` or `undefined`: Users can toggle consent
+ *
+ * - `display`: Visibility in consent UI
+ *   - `true`: Show this option to users
+ *   - `false`: Hide from consent interface
+ *
+ * - `gdprType`: Numeric identifier for GDPR categorization
+ *   - 1: Essential/Necessary
+ *   - 2: Functional
+ *   - 3: Experience/Preferences
+ *   - 4: Analytics/Measurement
+ *   - 5: Marketing/Advertising
+ *
+ * - `name`: Reference to the consent type
+ *   - Must match one of {@link AllConsentNames}
+ *
+ * @example
+ * ```typescript
+ * const analyticsConsent: ConsentType = {
+ *   name: 'measurement',
+ *   gdprType: 4,
+ *   defaultValue: false,
+ *   description: 'Helps us understand how users interact with our site',
+ *   display: true,
+ *   disabled: false
+ * };
+ *
+ * const necessaryConsent: ConsentType = {
+ *   name: 'necessary',
+ *   gdprType: 1,
+ *   defaultValue: true,
+ *   description: 'Required for basic site functionality',
+ *   display: true,
+ *   disabled: true  // Users cannot disable necessary cookies
+ * };
+ * ```
+ *
+ * @see {@link consentTypes} for the predefined consent configurations
+ * @public
+ */
+export type ConsentType = {
+	/** Whether consent is granted by default */
+	defaultValue: boolean;
+
+	/** User-friendly description of what this consent enables */
+	description: string;
+
+	/** Whether users can modify this consent setting */
+	disabled?: boolean;
+
+	/** Whether to show this consent option in the UI */
+	display: boolean;
+
+	/** GDPR category identifier (1-5) */
+	gdprType: number;
+
+	/** The consent category name */
+	name: AllConsentNames;
+};
+
+/**
+ * Predefined consent type configurations that comply with GDPR requirements.
+ *
+ * @remarks
+ * This array defines the standard consent categories and their default configurations.
+ * Each entry represents a specific type of cookie or tracking technology:
+ *
+ * 1. Necessary (Type 1):
+ *    - Required for basic site functionality
+ *    - Cannot be disabled by users
+ *    - Enabled by default
+ *
+ * 2. Functionality (Type 2):
+ *    - Enables enhanced features
+ *    - Optional for users
+ *    - Disabled by default
+ *
+ * 3. Measurement (Type 4):
+ *    - Analytics and performance tracking
+ *    - Optional for users
+ *    - Disabled by default
+ *
+ * 4. Experience (Type 3):
+ *    - User experience improvements
+ *    - Optional for users
+ *    - Disabled by default
+ *
+ * 5. Marketing (Type 5):
+ *    - Advertising and marketing
+ *    - Optional for users
+ *    - Disabled by default
+ *
+ * @example
+ * ```typescript
+ * function getConsentConfig(type: AllConsentNames): ConsentType {
+ *   return consentTypes.find(consent => consent.name === type)!;
+ * }
+ *
+ * function isConsentRequired(type: AllConsentNames): boolean {
+ *   const config = getConsentConfig(type);
+ *   return !config.defaultValue && !config.disabled;
+ * }
+ *
+ * function getDisplayedConsents(): ConsentType[] {
+ *   return consentTypes.filter(consent => consent.display);
+ * }
+ * ```
+ *
+ * @see {@link ConsentType} for the structure of each consent configuration
+ * @see {@link AllConsentNames} for available consent categories
+ * @public
+ */
+export const consentTypes: ConsentType[] = [
+	{
+		defaultValue: true,
+		description:
+			'These trackers are used for activities that are strictly necessary to operate or deliver the service you requested from us and, therefore, do not require you to consent.',
+		disabled: true,
+		display: true,
+		gdprType: 1,
+		name: 'necessary',
+	},
+	{
+		defaultValue: false,
+		description:
+			'These trackers enable basic interactions and functionalities that allow you to access selected features of our service and facilitate your communication with us.',
+		display: false,
+		gdprType: 2,
+		name: 'functionality',
+	},
+	{
+		defaultValue: false,
+		description:
+			'These trackers help us to measure traffic and analyze your behavior to improve our service.',
+		display: false,
+		gdprType: 4,
+		name: 'measurement',
+	},
+	{
+		defaultValue: false,
+		description:
+			'These trackers help us to improve the quality of your user experience and enable interactions with external content, networks, and platforms.',
+		display: false,
+		gdprType: 3,
+		name: 'experience',
+	},
+	{
+		defaultValue: false,
+		description:
+			'These trackers help us to deliver personalized ads or marketing content to you, and to measure their performance.',
+		display: false,
+		gdprType: 5,
+		name: 'marketing',
+	},
+];

package/src/types/index.ts

@@ -0,0 +1,148 @@
+/**
+ * @packageDocumentation
+ * Central export point for all consent management types and interfaces.
+ * This module aggregates and re-exports all type definitions needed for implementing
+ * GDPR-compliant consent management.
+ */
+
+/**
+ * @module
+ * Compliance and Privacy Types
+ *
+ * @remarks
+ * Exports types related to privacy compliance and consent management:
+ * - Region-specific compliance settings
+ * - Consent state tracking
+ * - Privacy preferences
+ * - Namespace configuration
+ *
+ * @example
+ * Import compliance-related types:
+ * ```typescript
+ * import type {
+ *   ComplianceRegion,
+ *   ComplianceSettings,
+ *   PrivacySettings
+ * } from 'c15t/types';
+ *
+ * const euSettings: ComplianceSettings = {
+ *   enabled: true,
+ *   appliesGlobally: false,
+ *   applies: true
+ * };
+ *
+ * const region: ComplianceRegion = 'gdpr';
+ * ```
+ */
+import type {
+	ComplianceRegion,
+	ComplianceSettings,
+	ConsentState,
+	HasConsentedProps,
+	NamespaceProps,
+	PrivacySettings,
+} from './compliance';
+
+export type {
+	ConsentState,
+	ComplianceRegion,
+	ComplianceSettings,
+	PrivacySettings,
+	HasConsentedProps,
+	NamespaceProps,
+};
+
+/**
+ * @module
+ * GDPR Consent Types
+ *
+ * @remarks
+ * Exports types and constants for GDPR-specific consent management:
+ * - Consent category definitions
+ * - Consent type configurations
+ * - Predefined consent settings
+ *
+ * @example
+ * Import and use GDPR-related types:
+ * ```typescript
+ * import {
+ *   type AllConsentNames,
+ *   type ConsentType,
+ *   consentTypes
+ * } from 'c15t/types';
+ *
+ * function isOptionalConsent(type: AllConsentNames): boolean {
+ *   const config = consentTypes.find(c => c.name === type);
+ *   return config ? !config.disabled && !config.defaultValue : false;
+ * }
+ * ```
+ */
+import { type AllConsentNames, type ConsentType, consentTypes } from './gdpr';
+
+export { consentTypes };
+export type { AllConsentNames, ConsentType };
+
+/**
+ * @module
+ * Callback Types
+ *
+ * @remarks
+ * Exports types for consent management callbacks and event handlers:
+ * - Generic callback function type
+ * - Consent-specific callback configurations
+ *
+ * @example
+ * Import and use callback types:
+ * ```typescript
+ * import type {
+ *   CallbackFunction,
+ *   Callbacks
+ * } from 'c15t/types';
+ *
+ * const callbacks: Callbacks = {
+ *   onConsentGiven: () => {
+ *     console.log('Consent granted');
+ *     initializeAnalytics();
+ *   },
+ *   onError: (error) => {
+ *     console.error('Consent error:', error);
+ *   }
+ * };
+ * ```
+ *
+ * @example
+ * Create typed callback functions:
+ * ```typescript
+ * const errorHandler: CallbackFunction<string> =
+ *   (message) => console.error(message);
+ *
+ * const readyHandler: CallbackFunction =
+ *   () => console.log('System ready');
+ * ```
+ */
+import type { CallbackFunction, Callbacks } from './callbacks';
+
+export type { CallbackFunction, Callbacks };
+
+/**
+ * @module
+ * Translation Types
+ *
+ * @remarks
+ * Exports types for translation configuration and translations:
+ * - Translation configuration
+ * - Translation types
+ * - Cookie banner translations
+ * - Consent manager dialog translations
+ * - Consent manager widget translations
+ */
+
+export type {
+	ConsentManagerDialogTranslations,
+	ConsentManagerWidgetTranslations,
+	ConsentTypeTranslations,
+	ConsentTypesTranslations,
+	CookieBannerTranslations,
+	TranslationConfig,
+	Translations,
+} from './translations';