c15t
Version:
Headless JavaScript consent management platform for cookie banners, privacy preferences, consent storage, and script gating.
243 lines (242 loc) • 7.71 kB
TypeScript
/**
* @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`: Subject must explicitly grant consent
*
* - `description`: Subject-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;
/** Subject-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):
* - Subject 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 declare const consentTypes: ConsentType[];
/**
* Runtime array of all valid consent names.
*
* @remarks
* This array is automatically derived from {@link consentTypes} to ensure
* runtime validation stays in sync with the {@link AllConsentNames} type definition.
* Use this for validation logic where you need to check if a string is a valid consent name.
*
* @example
* ```typescript
* function validateConsentName(name: string): AllConsentNames {
* if (!allConsentNames.includes(name as AllConsentNames)) {
* throw new Error(`Invalid consent name: ${name}`);
* }
* return name as AllConsentNames;
* }
* ```
*
* @see {@link AllConsentNames} for the type definition
* @see {@link consentTypes} for the full consent configurations
* @public
*/
export declare const allConsentNames: AllConsentNames[];
/**
* Information about the consent granted
*/
export type ConsentInfo = {
/**
* The epoch timestamp of when the consent was recorded
* @example 1761911048
*/
time: number;
/**
* The client-generated subject ID in sub_xxx format
*
* @remarks
* This is the primary identifier for the device/browser.
* Generated client-side using generateSubjectId() and stored in cookie.
* New in v2.0 - replaces the server-generated consentId.
*
* @example 'sub_2VZxR7YmNpKq3WfLs8TgHd'
*/
subjectId?: string;
/**
* @deprecated Use subjectId instead. The id field stored the server-generated
* consentId which is no longer used in v2.0.
*
* @remarks
* This field is kept for migration purposes. If present without subjectId,
* it indicates old storage format that should trigger re-consent.
*/
id?: string;
/**
* The external user ID linked to this subject
*
* @remarks
* Set via identifyUser() to link a subject (device) to an authenticated user.
* This is the user's ID from your auth system (e.g., Clerk, Auth0, etc.)
*
* @example 'user_123abc'
*/
externalId?: string;
/**
* Material fingerprint of the active policy when this consent was accepted.
*
* @remarks
* Used client-side to detect when consent should be refreshed because the
* active policy changed in a way that affects consent semantics.
*/
materialPolicyFingerprint?: string;
/**
* The identity provider that provided the external ID
*
* @remarks
* Used to identify which auth system the externalId came from.
*
* @example 'clerk', 'auth0', 'firebase'
*/
identityProvider?: string;
};