@c15t/backend 1.8.0 → 2.0.0-rc.0

package/src/handlers/init/geo.ts

@@ -0,0 +1,195 @@
+import type { C15TOptions } from '~/types';
+import type { JurisdictionCode } from '~/types/api';
+
+/**
+ * Normalizes a header value to a string or null.
+ */
+function normalizeHeader(
+	value: string | string[] | null | undefined
+): string | null {
+	if (!value) {
+		return null;
+	}
+	return Array.isArray(value) ? (value[0] ?? null) : value;
+}
+
+/**
+ * Gets geo-related headers from the request.
+ */
+function getGeoHeaders(headers: Headers) {
+	const countryCode =
+		normalizeHeader(headers.get('x-c15t-country')) ??
+		normalizeHeader(headers.get('cf-ipcountry')) ??
+		normalizeHeader(headers.get('x-vercel-ip-country')) ??
+		normalizeHeader(headers.get('x-amz-cf-ipcountry')) ??
+		normalizeHeader(headers.get('x-country-code'));
+
+	const regionCode =
+		normalizeHeader(headers.get('x-c15t-region')) ??
+		normalizeHeader(headers.get('x-vercel-ip-country-region')) ??
+		normalizeHeader(headers.get('x-region-code'));
+
+	return { countryCode, regionCode };
+}
+
+/**
+ * Determines the applicable jurisdiction based on country and region codes.
+ *
+ * @remarks
+ * - EU/EEA/UK map to GDPR-style regimes.
+ * - Specific countries map to their local laws (CH, BR, CA, AU, JP, KR).
+ * - CCPA is applied for certain US regions (e.g. California).
+ */
+export function checkJurisdiction(
+	countryCode: string | null,
+	regionCode?: string | null
+): JurisdictionCode {
+	// Country/region sets for different jurisdictions
+	const jurisdictions = {
+		EU: new Set([
+			'AT',
+			'BE',
+			'BG',
+			'HR',
+			'CY',
+			'CZ',
+			'DK',
+			'EE',
+			'FI',
+			'FR',
+			'DE',
+			'GR',
+			'HU',
+			'IE',
+			'IT',
+			'LV',
+			'LT',
+			'LU',
+			'MT',
+			'NL',
+			'PL',
+			'PT',
+			'RO',
+			'SK',
+			'SI',
+			'ES',
+			'SE',
+		]),
+		EEA: new Set(['IS', 'NO', 'LI']),
+		UK: new Set(['GB']),
+		CH: new Set(['CH']),
+		BR: new Set(['BR']),
+		CA: new Set(['CA']),
+		AU: new Set(['AU']),
+		JP: new Set(['JP']),
+		KR: new Set(['KR']),
+		US_CCPA_REGIONS: new Set([
+			// California (CCPA/CPRA)
+			'CA',
+		]),
+		CA_QC_REGIONS: new Set([
+			// Quebec (Law 25)
+			'QC',
+		]),
+	};
+
+	// Default to no jurisdiction
+	let jurisdiction: JurisdictionCode = 'NONE';
+
+	// Check country/region codes against jurisdiction sets
+	if (countryCode) {
+		// Normalize for case-insensitive comparison
+		const normalizedCountryCode = countryCode.toUpperCase();
+		// Normalize region code: handle dash-separated formats like "CA-QC" or "US-CA"
+		// by extracting the last segment as the subdivision code
+		const normalizedRegionCode =
+			regionCode && typeof regionCode === 'string'
+				? (regionCode.includes('-')
+						? regionCode.split('-').pop()!
+						: regionCode
+					).toUpperCase()
+				: null;
+
+		// CCPA-style rules: currently applied for certain US regions only
+		if (
+			normalizedCountryCode === 'US' &&
+			normalizedRegionCode &&
+			jurisdictions.US_CCPA_REGIONS.has(normalizedRegionCode)
+		) {
+			return 'CCPA';
+		}
+
+		// Quebec (Law 25): opt-in consent required
+		if (
+			normalizedCountryCode === 'CA' &&
+			normalizedRegionCode &&
+			jurisdictions.CA_QC_REGIONS.has(normalizedRegionCode)
+		) {
+			return 'QC_LAW25';
+		}
+
+		const jurisdictionMap = [
+			{
+				sets: [jurisdictions.UK],
+				code: 'UK_GDPR' as const,
+			},
+			{
+				sets: [jurisdictions.EU, jurisdictions.EEA],
+				code: 'GDPR' as const,
+			},
+			{ sets: [jurisdictions.CH], code: 'CH' as const },
+			{ sets: [jurisdictions.BR], code: 'BR' as const },
+			{ sets: [jurisdictions.CA], code: 'PIPEDA' as const },
+			{ sets: [jurisdictions.AU], code: 'AU' as const },
+			{ sets: [jurisdictions.JP], code: 'APPI' as const },
+			{ sets: [jurisdictions.KR], code: 'PIPA' as const },
+		];
+
+		// Find matching jurisdiction
+		for (const { sets, code } of jurisdictionMap) {
+			if (sets.some((set) => set.has(normalizedCountryCode))) {
+				jurisdiction = code;
+				break;
+			}
+		}
+	}
+
+	return jurisdiction;
+}
+
+/**
+ * Gets the location from the request headers.
+ *
+ * @param request - The incoming request
+ * @param options - The C15T options
+ * @returns The location object with countryCode and regionCode
+ */
+export async function getLocation(
+	request: Request,
+	options: C15TOptions
+): Promise<{ countryCode: string | null; regionCode: string | null }> {
+	if (options.advanced?.disableGeoLocation) {
+		return { countryCode: null, regionCode: null };
+	}
+
+	const { countryCode, regionCode } = getGeoHeaders(request.headers);
+	return { countryCode, regionCode };
+}
+
+/**
+ * Gets the jurisdiction based on location and options.
+ *
+ * @param location - The location object
+ * @param options - The C15T options
+ * @returns The jurisdiction code
+ */
+export function getJurisdiction(
+	location: { countryCode: string | null; regionCode: string | null },
+	options: C15TOptions
+): JurisdictionCode {
+	if (options.advanced?.disableGeoLocation) {
+		return 'GDPR';
+	}
+
+	return checkJurisdiction(location.countryCode, location.regionCode);
+}

package/src/handlers/init/index.test.ts

@@ -0,0 +1,205 @@
+import { baseTranslations } from '@c15t/translations';
+import { describe, expect, it } from 'vitest';
+import type { C15TOptions } from '~/types';
+import { checkJurisdiction, getJurisdiction, getLocation } from './geo';
+import {
+	buildResponse,
+	getHeaders,
+	getTranslationsData,
+	parseAcceptLanguage,
+} from './index';
+
+describe('Init Handler Utilities', () => {
+	describe('getHeaders', () => {
+		it('extracts country code from cf-ipcountry header', () => {
+			const headers = new Headers({ 'cf-ipcountry': 'DE' });
+			const result = getHeaders(headers);
+			expect(result.countryCode).toBe('DE');
+		});
+
+		it('falls back to alternative country code headers', () => {
+			const headers = new Headers({ 'x-vercel-ip-country': 'FR' });
+			const result = getHeaders(headers);
+			expect(result.countryCode).toBe('FR');
+		});
+
+		it('prioritizes cf-ipcountry over other headers', () => {
+			const headers = new Headers({
+				'cf-ipcountry': 'DE',
+				'x-vercel-ip-country': 'FR',
+			});
+			const result = getHeaders(headers);
+			expect(result.countryCode).toBe('DE');
+		});
+
+		it('extracts region code from headers', () => {
+			const headers = new Headers({
+				'cf-ipcountry': 'US',
+				'x-vercel-ip-country-region': 'CA',
+			});
+			const result = getHeaders(headers);
+			expect(result.countryCode).toBe('US');
+			expect(result.regionCode).toBe('CA');
+		});
+
+		it('handles missing headers gracefully', () => {
+			const headers = new Headers({});
+			const result = getHeaders(headers);
+			expect(result.countryCode).toBeNull();
+			expect(result.regionCode).toBeNull();
+		});
+
+		it('handles undefined headers', () => {
+			const result = getHeaders(undefined);
+			expect(result.countryCode).toBeNull();
+			expect(result.regionCode).toBeNull();
+			expect(result.acceptLanguage).toBeNull();
+		});
+	});
+
+	describe('checkJurisdiction', () => {
+		it('returns GDPR for EU countries', () => {
+			expect(checkJurisdiction('DE', null)).toBe('GDPR');
+			expect(checkJurisdiction('FR', null)).toBe('GDPR');
+			expect(checkJurisdiction('IT', null)).toBe('GDPR');
+		});
+
+		it('returns UK_GDPR for UK', () => {
+			expect(checkJurisdiction('GB', null)).toBe('UK_GDPR');
+		});
+
+		it('returns CCPA for California', () => {
+			expect(checkJurisdiction('US', 'CA')).toBe('CCPA');
+		});
+
+		it('returns NONE for non-regulated regions', () => {
+			expect(checkJurisdiction('US', null)).toBe('NONE');
+			expect(checkJurisdiction('US', 'TX')).toBe('NONE');
+		});
+
+		it('returns PIPEDA for Canada', () => {
+			expect(checkJurisdiction('CA', null)).toBe('PIPEDA');
+		});
+
+		it('returns CH for Switzerland', () => {
+			expect(checkJurisdiction('CH', null)).toBe('CH');
+		});
+
+		it('handles null country code', () => {
+			expect(checkJurisdiction(null, null)).toBe('NONE');
+		});
+	});
+
+	describe('parseAcceptLanguage', () => {
+		it('returns en for null input', () => {
+			expect(parseAcceptLanguage(null)).toBe('en');
+		});
+
+		it('parses simple language code', () => {
+			expect(parseAcceptLanguage('de')).toBe('de');
+		});
+
+		it('parses language with region', () => {
+			expect(parseAcceptLanguage('de-DE')).toBe('de');
+		});
+
+		it('parses Accept-Language with quality factors', () => {
+			expect(parseAcceptLanguage('de-DE,de;q=0.9,en;q=0.8')).toBe('de');
+		});
+	});
+
+	describe('getTranslationsData', () => {
+		it('returns en translations for null Accept-Language', () => {
+			const result = getTranslationsData(null);
+			expect(result.language).toBe('en');
+			expect(result.translations.cookieBanner.title).toBe(
+				baseTranslations.en.cookieBanner.title
+			);
+		});
+
+		it('returns de translations for de-DE', () => {
+			const result = getTranslationsData('de-DE,de;q=0.9,en;q=0.8');
+			expect(result.language).toBe('de');
+			expect(result.translations.cookieBanner.title).toBe(
+				baseTranslations.de.cookieBanner.title
+			);
+		});
+
+		it('merges custom translations', () => {
+			const customTranslations = {
+				en: { cookieBanner: { title: 'Custom Title' } },
+			};
+			const result = getTranslationsData('en-US', customTranslations);
+			expect(result.translations.cookieBanner.title).toBe('Custom Title');
+		});
+	});
+
+	describe('buildResponse', () => {
+		it('returns properly structured response', () => {
+			const result = buildResponse({
+				jurisdiction: 'GDPR',
+				location: { countryCode: 'DE', regionCode: null },
+				acceptLanguage: 'en',
+				customTranslations: undefined,
+				branding: 'c15t',
+			});
+
+			expect(result).toHaveProperty('jurisdiction');
+			expect(result).toHaveProperty('location');
+			expect(result).toHaveProperty('translations');
+			expect(result).toHaveProperty('branding');
+			expect(result.jurisdiction).toBe('GDPR');
+			expect(result.branding).toBe('c15t');
+		});
+	});
+
+	describe('getLocation', () => {
+		it('returns null location when geo is disabled', async () => {
+			const request = new Request('http://localhost', {
+				headers: { 'cf-ipcountry': 'DE' },
+			});
+			const options: C15TOptions = {
+				trustedOrigins: [],
+				adapter: {} as C15TOptions['adapter'],
+				advanced: { disableGeoLocation: true },
+			};
+
+			const result = await getLocation(request, options);
+			expect(result.countryCode).toBeNull();
+			expect(result.regionCode).toBeNull();
+		});
+	});
+
+	describe('getJurisdiction', () => {
+		it('returns GDPR when geo is disabled', () => {
+			const options: C15TOptions = {
+				trustedOrigins: [],
+				adapter: {} as C15TOptions['adapter'],
+				advanced: { disableGeoLocation: true },
+			};
+
+			const result = getJurisdiction(
+				{ countryCode: 'US', regionCode: null },
+				options
+			);
+			expect(result).toBe('GDPR');
+		});
+
+		it('returns appropriate jurisdiction based on location', () => {
+			const options: C15TOptions = {
+				trustedOrigins: [],
+				adapter: {} as C15TOptions['adapter'],
+			};
+
+			expect(
+				getJurisdiction({ countryCode: 'DE', regionCode: null }, options)
+			).toBe('GDPR');
+			expect(
+				getJurisdiction({ countryCode: 'US', regionCode: 'CA' }, options)
+			).toBe('CCPA');
+			expect(
+				getJurisdiction({ countryCode: 'GB', regionCode: null }, options)
+			).toBe('UK_GDPR');
+		});
+	});
+});

package/src/handlers/init/index.ts

@@ -0,0 +1,114 @@
+import type { GlobalVendorList, NonIABVendor } from '@c15t/schema/types';
+import type { Translations } from '@c15t/translations';
+import type { Branding } from '~/types';
+import type { JurisdictionCode } from '~/types/api';
+import { getTranslationsData } from './translations';
+
+/**
+ * Gets the headers from the context.
+ *
+ * @param headers - The headers to get the headers from.
+ * @returns The headers or null if the headers are not present.
+ */
+export function getHeaders(headers: Headers | undefined) {
+	if (!headers) {
+		return {
+			countryCode: null,
+			regionCode: null,
+			acceptLanguage: null,
+		};
+	}
+
+	// Add this conversion to ensure headers are always string or null
+	const normalizeHeader = (
+		value: string | string[] | null | undefined
+	): string | null => {
+		if (!value) {
+			return null;
+		}
+
+		return Array.isArray(value) ? (value[0] ?? null) : value;
+	};
+
+	const countryCode =
+		normalizeHeader(headers.get('x-c15t-country')) ??
+		normalizeHeader(headers.get('cf-ipcountry')) ??
+		normalizeHeader(headers.get('x-vercel-ip-country')) ??
+		normalizeHeader(headers.get('x-amz-cf-ipcountry')) ??
+		normalizeHeader(headers.get('x-country-code'));
+
+	const regionCode =
+		normalizeHeader(headers.get('x-c15t-region')) ??
+		normalizeHeader(headers.get('x-vercel-ip-country-region')) ??
+		normalizeHeader(headers.get('x-region-code'));
+
+	// Get preferred language from Accept-Language header
+	const acceptLanguage = normalizeHeader(headers.get('accept-language'));
+
+	return {
+		countryCode,
+		regionCode,
+		acceptLanguage,
+	};
+}
+
+/**
+ * Parse Accept-Language header to get the primary language code.
+ *
+ * @param acceptLanguage - The Accept-Language header value
+ * @returns The primary language code (e.g., "en", "de"), defaults to "en"
+ */
+export function parseAcceptLanguage(acceptLanguage: string | null): string {
+	if (!acceptLanguage) {
+		return 'en';
+	}
+
+	// Parse "en-US,en;q=0.9,de;q=0.8" format
+	// Split by comma, take the first part, then extract language code
+	const firstLanguage = acceptLanguage.split(',')[0];
+	if (!firstLanguage) {
+		return 'en';
+	}
+
+	// Remove quality factor if present (e.g., "en;q=0.9" -> "en")
+	const languageWithRegion = firstLanguage.split(';')[0]?.trim();
+	if (!languageWithRegion) {
+		return 'en';
+	}
+
+	// Extract language code without region (e.g., "en-US" -> "en")
+	const languageCode = languageWithRegion.split('-')[0]?.toLowerCase();
+
+	return languageCode ?? 'en';
+}
+
+export function buildResponse({
+	jurisdiction,
+	location,
+	acceptLanguage,
+	customTranslations,
+	branding = 'c15t',
+	gvl,
+	customVendors,
+}: {
+	jurisdiction: JurisdictionCode;
+	location: { countryCode: string | null; regionCode: string | null };
+	acceptLanguage: string | null;
+	customTranslations: Record<string, Partial<Translations>> | undefined;
+	branding?: Branding;
+	gvl?: GlobalVendorList;
+	customVendors?: NonIABVendor[];
+}) {
+	return {
+		jurisdiction,
+		location,
+		translations: getTranslationsData(acceptLanguage, customTranslations),
+		branding: branding,
+		gvl: gvl ?? null,
+		customVendors: customVendors ?? undefined,
+	};
+}
+
+export { checkJurisdiction, getJurisdiction, getLocation } from './geo';
+// Re-export translations functions
+export { getTranslations, getTranslationsData } from './translations';

package/src/handlers/init/translations.test.ts

@@ -0,0 +1,121 @@
+import { baseTranslations } from '@c15t/translations';
+import { describe, expect, it } from 'vitest';
+import { getTranslationsData } from './translations';
+
+describe('showBanner > getTranslationsData', () => {
+	it("should return 'en' translations when Accept-Language is null", () => {
+		const { translations, language } = getTranslationsData(null);
+		expect(language).toBe('en');
+		expect(translations.cookieBanner.title).toBe(
+			baseTranslations.en.cookieBanner.title
+		);
+	});
+
+	it("should return 'en' translations for unsupported language", () => {
+		const { translations, language } = getTranslationsData('xx-XX,en;q=0.9');
+		expect(language).toBe('en');
+		expect(translations.cookieBanner.title).toBe(
+			baseTranslations.en.cookieBanner.title
+		);
+	});
+
+	it("should return 'de' translations for 'de-DE'", () => {
+		const { translations, language } = getTranslationsData(
+			'de-DE,de;q=0.9,en;q=0.8'
+		);
+		expect(language).toBe('de');
+		expect(translations.cookieBanner.title).toBe(
+			baseTranslations.de.cookieBanner.title
+		);
+	});
+
+	it('should merge custom translations for the preferred language', () => {
+		const customTranslations = {
+			en: {
+				cookieBanner: {
+					title: 'My Custom Cookie Title',
+				},
+			},
+		};
+		const { translations, language } = getTranslationsData(
+			'en-US,en;q=0.9',
+			customTranslations
+		);
+		expect(language).toBe('en');
+		expect(translations.cookieBanner.title).toBe('My Custom Cookie Title');
+		// Check if other properties from base translations are still there
+		expect(translations.cookieBanner.description).toBeDefined();
+	});
+
+	it('should not merge custom translations for a different language', () => {
+		const customTranslations = {
+			de: {
+				cookieBanner: {
+					title: 'Meine benutzerdefinierte Cookie-Überschrift',
+				},
+			},
+		};
+		const { translations, language } = getTranslationsData(
+			'en-US,en;q=0.9',
+			customTranslations
+		);
+		expect(language).toBe('en');
+		expect(translations.cookieBanner.title).toBe(
+			baseTranslations.en.cookieBanner.title
+		);
+	});
+
+	it('should handle partially provided custom translations', () => {
+		const customTranslations = {
+			en: {
+				cookieBanner: {
+					// Title is NOT provided, description is.
+					description: 'My custom description.',
+				},
+			},
+		};
+		const { translations, language } = getTranslationsData(
+			'en-US,en;q=0.9',
+			customTranslations
+		);
+		expect(language).toBe('en');
+		// Title should come from base
+		expect(translations.cookieBanner.title).toBe(
+			baseTranslations.en.cookieBanner.title
+		);
+		// Description should be from custom
+		expect(translations.cookieBanner.description).toBe(
+			'My custom description.'
+		);
+	});
+
+	it('should return base translations if custom translations are empty for the language', () => {
+		const customTranslations = {
+			de: {},
+		};
+		const { translations, language } = getTranslationsData(
+			'de-DE,de;q=0.9',
+			customTranslations
+		);
+		expect(language).toBe('de');
+		expect(translations.cookieBanner.title).toBe(
+			baseTranslations.de.cookieBanner.title
+		);
+	});
+
+	it('should return custom translations for unsupported base language', () => {
+		const { translations, language } = getTranslationsData('xx-XX,en;q=0.9', {
+			xx: {
+				cookieBanner: {
+					title: 'XX Title',
+				},
+			},
+		});
+
+		expect(language).toBe('xx');
+		expect(translations.cookieBanner.title).toBe('XX Title');
+		expect(translations.cookieBanner.description).toBe(
+			baseTranslations.en.cookieBanner.description
+		);
+	});
+});

package/src/handlers/init/translations.ts

@@ -0,0 +1,72 @@
+import {
+	baseTranslations,
+	type CompleteTranslations,
+	deepMergeTranslations,
+	selectLanguage,
+	type Translations,
+} from '@c15t/translations';
+
+type SupportedBaseLanguage = keyof typeof baseTranslations;
+
+function isSupportedBaseLanguage(lang: string): lang is SupportedBaseLanguage {
+	return lang in baseTranslations;
+}
+
+/**
+ * Gets the translations data for a given language, merging custom translations if provided.
+ *
+ * @param acceptLanguage - The `Accept-Language` header from the request.
+ * @param customTranslations - An object containing custom translations to merge with the base translations.
+ * @returns An object containing the final translations and the determined language.
+ */
+export function getTranslationsData(
+	acceptLanguage: string | null,
+	customTranslations?: Record<string, Partial<Translations>>
+) {
+	const supportedDefaultLanguages = Object.keys(baseTranslations);
+	const supportedCustomLanguages = Object.keys(customTranslations || {});
+
+	const supportedLanguages = [
+		...supportedDefaultLanguages,
+		...supportedCustomLanguages,
+	];
+
+	const preferredLanguage = selectLanguage(supportedLanguages, {
+		header: acceptLanguage,
+		fallback: 'en',
+	});
+
+	const base = isSupportedBaseLanguage(preferredLanguage)
+		? baseTranslations[preferredLanguage]
+		: baseTranslations.en;
+
+	const custom = supportedCustomLanguages.includes(preferredLanguage)
+		? customTranslations?.[preferredLanguage]
+		: {};
+
+	const translations = custom ? deepMergeTranslations(base, custom) : base;
+
+	return {
+		translations: translations as CompleteTranslations,
+		language: preferredLanguage,
+	};
+}
+
+/**
+ * Gets the translations for a given language from options.
+ *
+ * @param acceptLanguage - The `Accept-Language` header from the request.
+ * @param options - The C15T options containing custom translations.
+ * @returns An object containing the final translations and the determined language.
+ */
+export async function getTranslations(
+	acceptLanguage: string,
+	options: {
+		advanced?: { customTranslations?: Record<string, Partial<Translations>> };
+	}
+) {
+	return getTranslationsData(
+		acceptLanguage,
+		options.advanced?.customTranslations
+	);
+}