@c15t/backend 1.5.0 → 1.6.0

package/src/v2/handlers/consent/show-banner/geo.ts

@@ -0,0 +1,96 @@
+import {
+	type JurisdictionCode,
+	JurisdictionMessages,
+} from '~/v2/contracts/shared/jurisdiction.schema';
+
+/**
+ * Determines if a consent banner should be shown based on country code
+ * and returns appropriate jurisdiction information
+ */
+export function checkJurisdiction(countryCode: string | null) {
+	// Country code 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']),
+	};
+
+	// Default to no jurisdiction, but show banner
+	let showConsentBanner = true;
+	let jurisdictionCode: JurisdictionCode = 'NONE';
+
+	// Check country code against jurisdiction sets
+	if (countryCode) {
+		// Normalize country code to uppercase for case-insensitive comparison
+		const normalizedCountryCode = countryCode.toUpperCase();
+
+		// Default to false as we don't know if it fits any jurisdiction yet
+		showConsentBanner = false;
+
+		// Map jurisdiction sets to their respective codes
+		const jurisdictionMap = [
+			{
+				sets: [jurisdictions.EU, jurisdictions.EEA, jurisdictions.UK],
+				code: 'GDPR',
+			},
+			{ sets: [jurisdictions.CH], code: 'CH' },
+			{ sets: [jurisdictions.BR], code: 'BR' },
+			{ sets: [jurisdictions.CA], code: 'PIPEDA' },
+			{ sets: [jurisdictions.AU], code: 'AU' },
+			{ sets: [jurisdictions.JP], code: 'APPI' },
+			{ sets: [jurisdictions.KR], code: 'PIPA' },
+		] as const;
+
+		// Find matching jurisdiction
+		for (const { sets, code } of jurisdictionMap) {
+			if (sets.some((set) => set.has(normalizedCountryCode))) {
+				jurisdictionCode = code;
+				showConsentBanner = true;
+				break;
+			}
+		}
+	}
+
+	// Get corresponding message from shared schema
+	const message = JurisdictionMessages[jurisdictionCode];
+
+	return {
+		showConsentBanner,
+		jurisdictionCode,
+		message,
+	};
+}

package/src/v2/handlers/consent/show-banner/handler.test.ts

@@ -0,0 +1,374 @@
+import { baseTranslations } from '@c15t/translations';
+import { describe, expect, it, vi } from 'vitest';
+import type { C15TContext } from '~/v2/types';
+import { showConsentBanner } from './handler';
+
+// First, mock the oRPC handler
+vi.mock('~/v2/contracts', () => ({
+	os: {
+		consent: {
+			showBanner: {
+				handler: (fn: typeof showConsentBanner) => fn,
+			},
+		},
+	},
+}));
+
+describe('Show Consent Banner Handler', () => {
+	// Helper to create mock context with headers
+	const createMockContext = (
+		headers: Record<string, string>,
+		advanced?: Partial<C15TContext['advanced']>
+	) => {
+		return {
+			context: {
+				headers: new Headers(headers),
+				advanced: {
+					...(advanced ?? {}),
+				},
+			},
+		};
+	};
+
+	describe('Header extraction', () => {
+		it('extracts country code from cf-ipcountry header', async () => {
+			//@ts-expect-error
+			const result = await showConsentBanner(
+				createMockContext({ 'cf-ipcountry': 'DE' })
+			);
+
+			expect(result.location.countryCode).toBe('DE');
+		});
+
+		it('falls back to alternative country code headers', async () => {
+			//@ts-expect-error
+			const result = await showConsentBanner(
+				createMockContext({ 'x-vercel-ip-country': 'FR' })
+			);
+
+			expect(result.location.countryCode).toBe('FR');
+		});
+
+		it('prioritizes cf-ipcountry over other headers when multiple are present', async () => {
+			//@ts-expect-error
+			const result = await showConsentBanner(
+				createMockContext({
+					'cf-ipcountry': 'DE',
+					'x-vercel-ip-country': 'FR',
+				})
+			);
+
+			expect(result.location.countryCode).toBe('DE');
+		});
+
+		it('extracts region code from headers', async () => {
+			//@ts-expect-error
+			const result = await showConsentBanner(
+				createMockContext({
+					'cf-ipcountry': 'US',
+					'x-vercel-ip-country-region': 'CA',
+				})
+			);
+
+			expect(result.location.countryCode).toBe('US');
+			expect(result.location.regionCode).toBe('CA');
+		});
+
+		it('handles missing headers gracefully', async () => {
+			//@ts-expect-error
+			const result = await showConsentBanner(createMockContext({}));
+
+			expect(result.location.countryCode).toBeNull();
+			expect(result.location.regionCode).toBeNull();
+		});
+
+		it('handles case-insensitive header names', async () => {
+			//@ts-expect-error
+			const result = await showConsentBanner(
+				createMockContext({ 'CF-IPCountry': 'GB' })
+			);
+
+			expect(result.location.countryCode).toBe('GB');
+		});
+	});
+
+	describe('Integration and response structure', () => {
+		it('returns properly structured response with all required fields', async () => {
+			//@ts-expect-error
+			const result = await showConsentBanner(
+				createMockContext({ 'cf-ipcountry': 'DE' })
+			);
+
+			// Verify structure
+			expect(result).toHaveProperty('showConsentBanner');
+			expect(result).toHaveProperty('jurisdiction');
+			expect(result).toHaveProperty('location');
+			expect(result).toHaveProperty('translations');
+
+			// Verify types
+			expect(typeof result.showConsentBanner).toBe('boolean');
+			expect(typeof result.jurisdiction.code).toBe('string');
+			expect(typeof result.jurisdiction.message).toBe('string');
+			expect(result.location.countryCode).toBe('DE');
+			expect(typeof result.translations.language).toBe('string');
+			expect(typeof result.translations.translations).toBe('object');
+		});
+
+		it('integrates geo logic correctly for regulated countries', async () => {
+			//@ts-expect-error
+			const result = await showConsentBanner(
+				createMockContext({ 'cf-ipcountry': 'DE' })
+			);
+
+			// Should show banner for regulated country
+			expect(result.showConsentBanner).toBe(true);
+			expect(result.jurisdiction.code).not.toBe('NONE');
+		});
+
+		it('integrates geo logic correctly for non-regulated countries', async () => {
+			//@ts-expect-error
+			const result = await showConsentBanner(
+				createMockContext({ 'cf-ipcountry': 'US' })
+			);
+
+			// Should not show banner for non-regulated country
+			expect(result.showConsentBanner).toBe(false);
+			expect(result.jurisdiction.code).toBe('NONE');
+		});
+
+		it('integrates translations correctly', async () => {
+			//@ts-expect-error
+			const result = await showConsentBanner(createMockContext({}));
+
+			expect(result.translations.translations).toStrictEqual(
+				baseTranslations.en
+			);
+			expect(result.translations.language).toBe('en');
+		});
+
+		it('handles custom translations when provided', async () => {
+			const customTranslations = {
+				en: { cookieBanner: { title: 'Custom Title' } },
+			};
+
+			//@ts-expect-error
+			const result = await showConsentBanner(
+				createMockContext({}, { customTranslations })
+			);
+
+			expect(result.translations.translations.cookieBanner.title).toBe(
+				'Custom Title'
+			);
+		});
+
+		it('maintains consistency between location and jurisdiction', async () => {
+			// Test that the country code extracted matches the jurisdiction determination
+			//@ts-expect-error
+			const result = await showConsentBanner(
+				createMockContext({ 'cf-ipcountry': 'CH' })
+			);
+
+			expect(result.location.countryCode).toBe('CH');
+			expect(result.jurisdiction.code).toBe('CH');
+			expect(result.showConsentBanner).toBe(true);
+		});
+	});
+
+	describe('Geo location disabling', () => {
+		it('disables geo logic when disableGeoLocation is true for regulated country', async () => {
+			//@ts-expect-error
+			const result = await showConsentBanner(
+				createMockContext(
+					{ 'cf-ipcountry': 'DE' }, // Normally would show banner
+					{ disableGeoLocation: true }
+				)
+			);
+
+			// Should show banner despite being in a regulated country when geo-location is disabled
+			expect(result.showConsentBanner).toBe(true);
+			expect(result.jurisdiction.code).toBe('NONE');
+			expect(result.location.countryCode).toBeNull();
+			expect(result.location.regionCode).toBeNull();
+		});
+
+		it('disables geo logic when disableGeoLocation is true for non-regulated country', async () => {
+			//@ts-expect-error
+			const result = await showConsentBanner(
+				createMockContext(
+					{ 'cf-ipcountry': 'US' }, // Normally would not show banner
+					{ disableGeoLocation: true }
+				)
+			);
+
+			// Should still not show banner and have consistent response
+			expect(result.showConsentBanner).toBe(true);
+			expect(result.jurisdiction.code).toBe('NONE');
+			expect(result.location.countryCode).toBeNull();
+			expect(result.location.regionCode).toBeNull();
+		});
+
+		it('still provides translations when geo location is disabled', async () => {
+			//@ts-expect-error
+			const result = await showConsentBanner(
+				createMockContext(
+					{ 'cf-ipcountry': 'DE' },
+					{ disableGeoLocation: true }
+				)
+			);
+
+			// Translations should still be provided
+			expect(result.translations.translations).toStrictEqual(
+				baseTranslations.en
+			);
+			expect(result.translations.language).toBe('en');
+		});
+
+		it('respects custom translations when geo location is disabled', async () => {
+			const customTranslations = {
+				en: { cookieBanner: { title: 'Custom Disabled Title' } },
+			};
+
+			//@ts-expect-error
+			const result = await showConsentBanner(
+				createMockContext(
+					{ 'cf-ipcountry': 'DE' },
+					{ disableGeoLocation: true, customTranslations }
+				)
+			);
+
+			expect(result.translations.translations.cookieBanner.title).toBe(
+				'Custom Disabled Title'
+			);
+			expect(result.showConsentBanner).toBe(true);
+			expect(result.jurisdiction.code).toBe('NONE');
+		});
+
+		it('ignores all geo headers when geo location is disabled', async () => {
+			//@ts-expect-error
+			const result = await showConsentBanner(
+				createMockContext(
+					{
+						'cf-ipcountry': 'DE',
+						'x-vercel-ip-country': 'FR',
+						'x-vercel-ip-country-region': 'IDF',
+					},
+					{ disableGeoLocation: true }
+				)
+			);
+
+			// Should ignore all geo headers
+			expect(result.location.countryCode).toBeNull();
+			expect(result.location.regionCode).toBeNull();
+			expect(result.showConsentBanner).toBe(true);
+			expect(result.jurisdiction.code).toBe('NONE');
+		});
+
+		it('applies normal geo logic when disableGeoLocation is false', async () => {
+			//@ts-expect-error
+			const result = await showConsentBanner(
+				createMockContext(
+					{ 'cf-ipcountry': 'DE' },
+					{ disableGeoLocation: false }
+				)
+			);
+
+			// Should apply normal geo logic
+			expect(result.showConsentBanner).toBe(true);
+			expect(result.jurisdiction.code).not.toBe('NONE');
+			expect(result.location.countryCode).toBe('DE');
+		});
+
+		it('applies normal geo logic when disableGeoLocation is undefined', async () => {
+			//@ts-expect-error
+			const result = await showConsentBanner(
+				createMockContext(
+					{ 'cf-ipcountry': 'DE' },
+					{ disableGeoLocation: undefined }
+				)
+			);
+
+			// Should apply normal geo logic when undefined
+			expect(result.showConsentBanner).toBe(true);
+			expect(result.jurisdiction.code).not.toBe('NONE');
+			expect(result.location.countryCode).toBe('DE');
+		});
+
+		it('maintains consistent response structure when geo is disabled', async () => {
+			//@ts-expect-error
+			const result = await showConsentBanner(
+				createMockContext(
+					{ 'cf-ipcountry': 'DE' },
+					{ disableGeoLocation: true }
+				)
+			);
+
+			// Verify the response has the same structure as normal responses
+			expect(result).toHaveProperty('showConsentBanner');
+			expect(result).toHaveProperty('jurisdiction');
+			expect(result).toHaveProperty('location');
+			expect(result).toHaveProperty('translations');
+
+			// Verify specific disabled values
+			expect(typeof result.showConsentBanner).toBe('boolean');
+			expect(typeof result.jurisdiction.code).toBe('string');
+			expect(typeof result.jurisdiction.message).toBe('string');
+			expect(result.location.countryCode).toBeNull();
+			expect(result.location.regionCode).toBeNull();
+			expect(typeof result.translations.language).toBe('string');
+			expect(typeof result.translations.translations).toBe('object');
+		});
+	});
+
+	describe('Edge cases and error handling', () => {
+		it('handles malformed headers gracefully', async () => {
+			//@ts-expect-error
+			const result = await showConsentBanner(
+				createMockContext({
+					'cf-ipcountry': '', // Empty string
+					'x-vercel-ip-country-region': '   ', // Whitespace
+				})
+			);
+
+			// Should handle gracefully without throwing
+			expect(result).toHaveProperty('showConsentBanner');
+			expect(result).toHaveProperty('jurisdiction');
+			expect(result).toHaveProperty('location');
+			expect(result).toHaveProperty('translations');
+		});
+
+		it('handles undefined context options gracefully', async () => {
+			const contextWithoutOptions = {
+				context: {
+					headers: new Headers({ 'cf-ipcountry': 'DE' }),
+					options: {}, // No advanced options
+				},
+			};
+
+			//@ts-expect-error
+			const result = await showConsentBanner(contextWithoutOptions);
+
+			expect(result.translations.translations).toStrictEqual(
+				baseTranslations.en
+			);
+		});
+
+		it('handles malformed headers gracefully when geo is disabled', async () => {
+			//@ts-expect-error
+			const result = await showConsentBanner(
+				createMockContext(
+					{
+						'cf-ipcountry': '', // Empty string
+						'x-vercel-ip-country-region': '   ', // Whitespace
+					},
+					{ disableGeoLocation: true }
+				)
+			);
+
+			// Should handle gracefully and ignore malformed headers
+			expect(result.showConsentBanner).toBe(true);
+			expect(result.jurisdiction.code).toBe('NONE');
+			expect(result.location.countryCode).toBeNull();
+			expect(result.location.regionCode).toBeNull();
+		});
+	});
+});

package/src/v2/handlers/consent/show-banner/handler.ts

@@ -0,0 +1,123 @@
+import type { Translations } from '@c15t/translations';
+import { os } from '~/v2/contracts';
+import {
+	type JurisdictionCode,
+	JurisdictionMessages,
+} from '~/v2/contracts/shared/jurisdiction.schema';
+import type { Branding, C15TContext } from '~/v2/types';
+import { checkJurisdiction } from './geo';
+import { getTranslations } from './translations';
+
+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,
+	};
+}
+
+function buildResponse({
+	shouldShowBanner,
+	jurisdiction,
+	location,
+	acceptLanguage,
+	customTranslations,
+	branding = 'c15t',
+}: {
+	shouldShowBanner: boolean;
+
+	jurisdiction: {
+		code: JurisdictionCode;
+		message: string;
+	};
+	location: { countryCode: string | null; regionCode: string | null };
+	acceptLanguage: string | null;
+	customTranslations: Record<string, Partial<Translations>> | undefined;
+	branding?: Branding;
+}) {
+	return {
+		showConsentBanner: shouldShowBanner,
+		jurisdiction,
+		location,
+		translations: getTranslations(acceptLanguage, customTranslations),
+		branding: branding,
+	};
+}
+
+/**
+ * Handler for the show consent banner endpoint
+ * Determines if a user should see a consent banner based on their location
+ */
+export const showConsentBanner = os.consent.showBanner.handler(
+	({ context }) => {
+		const typedContext = context as C15TContext;
+		const { customTranslations, disableGeoLocation, branding } =
+			typedContext.advanced ?? {};
+		const { countryCode, regionCode, acceptLanguage } = getHeaders(
+			typedContext.headers
+		);
+
+		if (disableGeoLocation) {
+			return buildResponse({
+				shouldShowBanner: true,
+				jurisdiction: {
+					code: 'NONE',
+					message: JurisdictionMessages.NONE,
+				},
+				location: { countryCode: null, regionCode: null },
+				acceptLanguage,
+				customTranslations,
+				branding,
+			});
+		}
+
+		const { showConsentBanner, jurisdictionCode, message } =
+			checkJurisdiction(countryCode);
+
+		return buildResponse({
+			shouldShowBanner: showConsentBanner,
+			jurisdiction: {
+				code: jurisdictionCode,
+				message,
+			},
+			location: { countryCode, regionCode },
+			acceptLanguage,
+			customTranslations,
+			branding,
+		});
+	}
+);

package/src/v2/handlers/consent/show-banner/translations.test.ts

@@ -0,0 +1,121 @@
+import { baseTranslations } from '@c15t/translations';
+import { describe, expect, it } from 'vitest';
+import { getTranslations } from './translations';
+
+describe('showBanner > getTranslations', () => {
+	it("should return 'en' translations when Accept-Language is null", () => {
+		const { translations, language } = getTranslations(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 } = getTranslations('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 } = getTranslations(
+			'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 } = getTranslations(
+			'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 } = getTranslations(
+			'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 } = getTranslations(
+			'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 } = getTranslations(
+			'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 } = getTranslations('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
+		);
+	});
+});