@c15t/backend 1.5.0 → 1.6.0

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

@@ -0,0 +1,79 @@
+import {
+	baseTranslations,
+	type CompleteTranslations,
+	deepMergeTranslations,
+	type Translations,
+} from '@c15t/translations';
+
+type SupportedBaseLanguage = keyof typeof baseTranslations;
+
+function isSupportedBaseLanguage(lang: string): lang is SupportedBaseLanguage {
+	return lang in baseTranslations;
+}
+
+/**
+ * Extracts the preferred language from Accept-Language header
+ * Falls back to 'en' if no supported language is found
+ */
+function getPreferredLanguage(
+	acceptLanguage: string | null,
+	supportedLanguages: string[]
+): string {
+	if (!acceptLanguage) {
+		return 'en';
+	}
+
+	// Get the primary language code
+	const primaryLang = acceptLanguage
+		.split(',')[0]
+		?.split(';')[0]
+		?.split('-')[0]
+		?.toLowerCase();
+
+	// Check if it's a supported language
+	if (primaryLang && supportedLanguages.includes(primaryLang)) {
+		return primaryLang;
+	}
+
+	return 'en';
+}
+
+/**
+ * Gets the translations 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 getTranslations(
+	acceptLanguage: string | null,
+	customTranslations?: Record<string, Partial<Translations>>
+) {
+	const supportedDefaultLanguages = Object.keys(baseTranslations);
+	const supportedCustomLanguages = Object.keys(customTranslations || {});
+
+	const supportedLanguages = [
+		...supportedDefaultLanguages,
+		...supportedCustomLanguages,
+	];
+
+	const preferredLanguage = getPreferredLanguage(
+		acceptLanguage,
+		supportedLanguages
+	);
+
+	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,
+	};
+}

package/src/v2/handlers/consent/verify.handler.ts

@@ -0,0 +1,288 @@
+import { ORPCError } from '@orpc/server';
+import type { z } from 'zod';
+import { os } from '~/v2/contracts';
+import type { PolicyTypeSchema } from '~/v2/db/schema';
+import type { C15TContext } from '~/v2/types';
+
+/**
+ * Type representing a consent record with required fields
+ */
+interface Consent {
+	id: string;
+	purposeIds: string[];
+	[key: string]: unknown;
+}
+
+/**
+ * Input type for verifying consent
+ */
+type VerifyConsentInput = {
+	subjectId?: string;
+	externalSubjectId?: string;
+	domain: string;
+	type: z.infer<typeof PolicyTypeSchema>;
+	policyId?: string;
+	preferences?: string[];
+};
+
+/**
+ * Response type for consent verification
+ */
+type VerifyConsentOutput = {
+	isValid: boolean;
+	reasons?: string[];
+	consent?: Consent;
+};
+
+/**
+ * Parameters for checking policy consent
+ */
+interface PolicyConsentCheckParams {
+	policyId: string;
+	subjectId: string;
+	domainId: string;
+	purposeIds?: string[];
+	type: z.infer<typeof PolicyTypeSchema>;
+	context: C15TContext;
+}
+
+/**
+ * Handles verification of consent records.
+ *
+ * This handler checks if a subject has given valid consent for a specific policy
+ * and domain, optionally verifying specific purpose preferences.
+ *
+ * @throws {ORPCError} When:
+ * - Subject creation fails
+ * - Domain is not found
+ * - Policy is not found or invalid
+ * - Database query fails
+ *
+ * @example
+ * ```ts
+ * // Verify cookie banner consent
+ * const response = await verifyConsent({
+ *   type: 'cookie_banner',
+ *   domain: 'example.com',
+ *   preferences: ['analytics', 'marketing']
+ * });
+ * ```
+ */
+export const verifyConsent = os.consent.verify.handler(
+	async ({ input, context }) => {
+		const typedContext = context as C15TContext;
+		const logger = typedContext.logger;
+		logger.info('Handling verify-consent request');
+
+		const {
+			type,
+			subjectId,
+			externalSubjectId,
+			domain,
+			policyId,
+			preferences,
+		} = input as VerifyConsentInput;
+
+		logger.debug('Request parameters', {
+			type,
+			subjectId,
+			externalSubjectId,
+			domain,
+			policyId,
+			preferences,
+		});
+
+		try {
+			// Find domain
+			const domainRecord = await typedContext.registry.findDomainByName(domain);
+
+			if (!domainRecord) {
+				throw new ORPCError('DOMAIN_NOT_FOUND', {
+					data: {
+						domain,
+					},
+				});
+			}
+
+			// Find subject
+			const subject = await typedContext.registry.findOrCreateSubject({
+				subjectId,
+				externalSubjectId,
+				ipAddress: typedContext.ipAddress ?? 'unknown',
+			});
+
+			if (!subject) {
+				throw new ORPCError('SUBJECT_NOT_FOUND', {
+					data: {
+						subjectId,
+						externalSubjectId,
+					},
+				});
+			}
+
+			if (
+				type === 'cookie_banner' &&
+				(!preferences || preferences.length === 0)
+			) {
+				// Validate preferences for cookie banner
+				throw new ORPCError('COOKIE_BANNER_PREFERENCES_REQUIRED', {
+					data: {
+						type: 'cookie_banner',
+					},
+				});
+			}
+
+			// Find purpose IDs if preferences are provided
+			const purposePromises = preferences?.map((purpose: string) =>
+				typedContext.registry.findOrCreateConsentPurposeByCode(purpose)
+			);
+
+			const rawPurposes = await Promise.all(purposePromises ?? []);
+
+			const purposeIds = rawPurposes
+				.filter(
+					(purpose): purpose is NonNullable<typeof purpose> => purpose !== null
+				)
+				.map((purpose) => purpose.id);
+
+			if (purposeIds.length !== (preferences?.length ?? 0)) {
+				throw new ORPCError('PURPOSES_NOT_FOUND', {
+					data: {
+						preferences: preferences ?? [],
+						foundPurposes: rawPurposes
+							.filter((p): p is NonNullable<typeof p> => p !== null)
+							.map((p) => p.code),
+					},
+				});
+			}
+
+			if (policyId) {
+				// Check policy consent
+				const policy =
+					await typedContext.registry.findConsentPolicyById(policyId);
+				if (!policy || policy.type !== type) {
+					throw new ORPCError('POLICY_NOT_FOUND', {
+						data: {
+							policyId,
+							type,
+						},
+					});
+				}
+
+				return await checkPolicyConsent({
+					policyId: policy.id,
+					subjectId: subject.id,
+					domainId: domainRecord.id,
+					purposeIds,
+					type,
+					context: typedContext,
+				});
+			}
+
+			// Check latest policy consent
+			const latestPolicy = await typedContext.registry.findOrCreatePolicy(type);
+			if (!latestPolicy) {
+				throw new ORPCError('POLICY_NOT_FOUND', {
+					data: {
+						policyId: 'latest',
+						type,
+					},
+				});
+			}
+
+			return await checkPolicyConsent({
+				policyId: latestPolicy.id,
+				subjectId: subject.id,
+				domainId: domainRecord.id,
+				purposeIds,
+				type,
+				context: typedContext,
+			});
+		} catch (error) {
+			logger.error('Error in verify-consent handler', {
+				error: error instanceof Error ? error.message : String(error),
+				errorType:
+					error instanceof Error ? error.constructor.name : typeof error,
+			});
+
+			// Re-throw ORPCError instances
+			if (error instanceof ORPCError) {
+				throw error;
+			}
+
+			// Convert other errors to internal server error
+			throw new ORPCError('INTERNAL_SERVER_ERROR', {
+				message: error instanceof Error ? error.message : String(error),
+			});
+		}
+	}
+);
+
+/**
+ * Checks if consent has been given for a specific policy.
+ *
+ * @param params - Parameters for checking policy consent
+ * @returns Verification result with consent details if valid
+ *
+ * @throws {ORPCError} When database operations fail
+ */
+async function checkPolicyConsent({
+	policyId,
+	subjectId,
+	domainId,
+	purposeIds,
+	type,
+	context,
+}: PolicyConsentCheckParams): Promise<VerifyConsentOutput> {
+	const { registry, db } = context;
+
+	const rawConsents = await db.findMany('consent', {
+		where: (b) =>
+			b.and(
+				b('subjectId', '=', subjectId),
+				b('policyId', '=', policyId),
+				b('domainId', '=', domainId)
+			),
+		orderBy: ['givenAt', 'desc'],
+	});
+
+	// Filter consents by purpose IDs if provided
+	const filteredConsents = rawConsents.filter((consent) => {
+		if (!purposeIds) {
+			return true;
+		}
+		return purposeIds.every((id) =>
+			(consent.purposeIds as string[]).some((purposeId) => purposeId === id)
+		);
+	});
+
+	await registry.createAuditLog({
+		subjectId,
+		entityType: 'consent_policy',
+		entityId: policyId,
+		actionType: 'verify_consent',
+		metadata: {
+			type,
+			policyId,
+			purposeIds,
+			success: filteredConsents.length !== 0,
+			...(filteredConsents.length > 0
+				? {
+						consentId: filteredConsents[0]?.id,
+					}
+				: {}),
+		},
+		eventTimezone: 'UTC',
+	});
+
+	if (rawConsents.length === 0 || filteredConsents.length === 0) {
+		return {
+			isValid: false,
+		};
+	}
+
+	return {
+		isValid: true,
+		consent: filteredConsents[0] as Consent,
+	};
+}

package/src/v2/handlers/meta/index.ts

@@ -0,0 +1,5 @@
+import { statusHandler } from './status.handler';
+
+export const metaHandlers = {
+	status: statusHandler,
+};

package/src/v2/handlers/meta/status.handler.ts

@@ -0,0 +1,43 @@
+import { os } from '~/v2/contracts';
+import type { C15TContext } from '~/v2/types';
+import { version } from '~/version';
+
+// Use os.meta.status.handler to connect to the contract
+export const statusHandler = os.meta.status.handler(({ context }) => {
+	const typedContext = context as C15TContext;
+
+	// Extract country and region from request headers
+	const headers = typedContext.headers;
+	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('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-vercel-ip-country-region')) ??
+		normalizeHeader(headers?.get('x-region-code'));
+
+	return {
+		status: 'ok' as const,
+		version,
+		timestamp: new Date(),
+		client: {
+			ip: typedContext.ipAddress ?? null,
+			userAgent: typedContext.userAgent ?? null,
+			region: {
+				countryCode,
+				regionCode,
+			},
+		},
+	};
+});

package/src/v2/init.test.ts

@@ -0,0 +1,114 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import type { C15TOptions } from './types';
+
+// Mock OpenTelemetry modules before any imports
+vi.mock('@opentelemetry/sdk-node', () => ({
+	NodeSDK: vi.fn().mockImplementation(() => ({
+		start: vi.fn(),
+	})),
+}));
+
+vi.mock('@opentelemetry/resources', () => ({
+	resourceFromAttributes: vi.fn().mockImplementation((attributes) => ({
+		attributes,
+	})),
+}));
+
+vi.mock('@opentelemetry/sdk-trace-base', () => ({
+	ConsoleSpanExporter: vi.fn().mockImplementation(() => ({})),
+}));
+
+// Mock local modules
+vi.mock('./utils/logger', () => ({
+	initLogger: vi.fn().mockReturnValue({
+		debug: vi.fn(),
+		info: vi.fn(),
+		warn: vi.fn(),
+		error: vi.fn(),
+	}),
+}));
+
+vi.mock('./db/registry', () => ({
+	createRegistry: vi.fn().mockReturnValue({}),
+}));
+
+vi.mock('./db/schema', () => ({
+	DB: {
+		client: vi.fn().mockImplementation((adapter) => ({
+			orm: vi.fn().mockResolvedValue({ adapter }),
+		})),
+	},
+}));
+
+afterEach(() => {
+	vi.clearAllMocks();
+});
+
+interface SetupParams {
+	telemetryDisabled?: boolean;
+	appName?: string;
+}
+
+async function setup(params: SetupParams = {}) {
+	const { telemetryDisabled = false, appName } = params;
+
+	// Reset the module cache to ensure a fresh instance for every test run
+	vi.resetModules();
+
+	// Get the mocked modules
+	const { NodeSDK } = await import('@opentelemetry/sdk-node');
+	const { DB } = await import('./db/schema');
+
+	// Get the start mock from the NodeSDK instance
+	const startMock = vi.fn();
+	const nodeSDKMock = NodeSDK as any;
+	nodeSDKMock.mockImplementation(() => ({
+		start: startMock,
+	}));
+
+	const { init } = await import('./init');
+
+	const options: Record<string, unknown> = {
+		trustedOrigins: [],
+		advanced: {
+			telemetry: telemetryDisabled ? { disabled: true } : {},
+		},
+		database: {},
+	};
+
+	if (appName !== undefined) {
+		options.appName = appName;
+	}
+
+	const context = init(options as unknown as C15TOptions);
+
+	return {
+		context,
+		startMock,
+		clientMock: DB.client,
+	};
+}
+
+describe('init', () => {
+	it('uses "c15t" as default appName when none is provided', async () => {
+		const { context, clientMock } = await setup();
+		expect(context.appName).toBe('c15t');
+		expect(clientMock).toHaveBeenCalledTimes(1);
+	});
+
+	it('uses the provided appName', async () => {
+		const appName = 'MyAmazingApp';
+		const { context } = await setup({ appName });
+		expect(context.appName).toBe(appName);
+	});
+
+	it('initialises telemetry when telemetry is enabled', async () => {
+		const { startMock } = await setup();
+		expect(startMock).toHaveBeenCalledTimes(1);
+	});
+
+	it('does not initialise telemetry when disabled via options', async () => {
+		const { startMock } = await setup({ telemetryDisabled: true });
+		expect(startMock).not.toHaveBeenCalled();
+	});
+});

package/src/v2/init.ts

@@ -0,0 +1,126 @@
+import { resourceFromAttributes } from '@opentelemetry/resources';
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { ConsoleSpanExporter } from '@opentelemetry/sdk-trace-base';
+import type { C15TContext, C15TOptions } from '~/v2/types';
+import { version as packageVersion } from '../version';
+import { createRegistry } from './db/registry';
+import { DB } from './db/schema';
+import { createTelemetryOptions } from './utils/create-telemetry-options';
+import { initLogger } from './utils/logger';
+
+// SDK instance should be at module level for proper lifecycle management
+let telemetrySdk: NodeSDK | undefined;
+
+/**
+ * Initializes telemetry SDK with the provided configuration
+ *
+ * @param appName - The application name for telemetry service identification
+ * @param telemetryOptions - Telemetry configuration options
+ * @param logger - Logger instance for telemetry status reporting
+ * @returns Whether telemetry was successfully initialized
+ */
+const initializeTelemetry = (
+	appName: string,
+	telemetryOptions: ReturnType<typeof createTelemetryOptions>,
+	logger: ReturnType<typeof initLogger>
+): boolean => {
+	// Skip if SDK already initialized or telemetry is disabled
+	if (telemetrySdk) {
+		logger.debug('Telemetry SDK already initialized, skipping');
+		return true;
+	}
+
+	if (telemetryOptions?.disabled) {
+		logger.info('Telemetry is disabled by configuration');
+		return false;
+	}
+
+	try {
+		// Create a telemetry resource with provided values or safe defaults
+		const resource = resourceFromAttributes({
+			'service.name': appName,
+			'service.version': packageVersion,
+			...(telemetryOptions?.defaultAttributes || {}),
+		});
+
+		logger.debug('Initializing telemetry with resource attributes', {
+			attributes: resource.attributes,
+		});
+
+		// Use provided tracer or fallback to console exporter
+		const traceExporter = telemetryOptions?.tracer
+			? undefined // SDK will use the provided tracer
+			: new ConsoleSpanExporter();
+
+		// Create and start the SDK
+		telemetrySdk = new NodeSDK({
+			resource,
+			traceExporter,
+		});
+
+		telemetrySdk.start();
+		logger.info('Telemetry successfully initialized');
+		return true;
+	} catch (error) {
+		// Log the error but don't crash the application
+		logger.error('Telemetry initialization failed', {
+			error: error instanceof Error ? error.message : String(error),
+			stack: error instanceof Error ? error.stack : undefined,
+		});
+		logger.warn('Continuing without telemetry');
+		return false;
+	}
+};
+
+export const init = (options: C15TOptions): C15TContext => {
+	const appName = options.appName || 'c15t';
+
+	const logger = initLogger({
+		...options.logger,
+		appName: String(appName),
+	});
+
+	// Create telemetry options
+	const telemetryOptions = createTelemetryOptions(
+		String(appName),
+		options.advanced?.telemetry
+	);
+
+	// Initialize telemetry
+	const telemetryInitialized = initializeTelemetry(
+		String(appName),
+		telemetryOptions,
+		logger
+	);
+
+	// Log final telemetry status
+	if (telemetryOptions?.disabled) {
+		logger.info('Telemetry is disabled by configuration');
+	} else if (telemetryInitialized) {
+		logger.info('Telemetry initialized successfully');
+	} else {
+		logger.warn(
+			'Telemetry initialization failed, continuing without telemetry'
+		);
+	}
+
+	// Initialize core components
+	const client = DB.client(options.adapter);
+
+	const orm = client.orm('1.0.0');
+
+	const context: C15TContext = {
+		...options,
+		appName,
+		logger,
+		db: orm,
+		registry: createRegistry({
+			db: orm,
+			ctx: {
+				logger,
+			},
+		}),
+	};
+
+	return context;
+};