@c15t/backend 1.0.0 → 1.1.0-canary.0

package/src/handlers/consent/post.handler.ts

@@ -0,0 +1,273 @@
+import { ORPCError } from '@orpc/server';
+import { os } from '~/contracts';
+import type { Adapter } from '~/pkgs/db-adapters/types';
+import type { Consent } from '~/schema/consent';
+import type { ConsentRecord } from '~/schema/consent-record';
+import type { C15TContext } from '~/types';
+
+/**
+ * Handles the creation of a new consent record.
+ *
+ * This handler processes consent submissions, creates necessary records in the database,
+ * and returns a formatted response. It handles different types of consent (cookie banner,
+ * policy-based, and other types) with their specific requirements.
+ *
+ * @throws {ORPCError} When:
+ * - Subject creation fails
+ * - Policy is not found or inactive
+ * - Database transaction fails
+ * - Required fields are missing
+ *
+ * @example
+ * ```ts
+ * // Cookie banner consent
+ * const response = await postConsent({
+ *   type: 'cookie_banner',
+ *   domain: 'example.com',
+ *   preferences: { analytics: true, marketing: false }
+ * });
+ * ```
+ */
+
+export const postConsent = os.consent.post.handler(
+	async ({ input, context }) => {
+		const typedContext = context as C15TContext;
+
+		const logger = typedContext.logger;
+		logger.info('Handling post-consent request');
+
+		const {
+			type,
+			subjectId,
+			externalSubjectId,
+			domain,
+			metadata,
+			preferences,
+		} = input;
+
+		logger.debug('Request parameters', {
+			type,
+			subjectId,
+			externalSubjectId,
+			domain,
+		});
+
+		try {
+			const subject = await typedContext.registry.findOrCreateSubject({
+				subjectId,
+				externalSubjectId,
+				ipAddress: typedContext.ipAddress || 'unknown',
+			});
+
+			if (!subject) {
+				throw new ORPCError('SUBJECT_CREATION_FAILED', {
+					data: {
+						subjectId,
+						externalSubjectId,
+					},
+				});
+			}
+
+			logger.debug('Subject found/created', { subjectId: subject.id });
+			const domainRecord =
+				await typedContext.registry.findOrCreateDomain(domain);
+
+			if (!domainRecord) {
+				throw new ORPCError('DOMAIN_CREATION_FAILED', {
+					data: {
+						domain,
+					},
+				});
+			}
+
+			const now = new Date();
+			let policyId: string | undefined;
+			let purposeIds: string[] = [];
+
+			if ('policyId' in input && input.policyId) {
+				policyId = input.policyId;
+
+				// Verify the policy exists and is active
+				const policy =
+					await typedContext.registry.findConsentPolicyById(policyId);
+				if (!policy) {
+					throw new ORPCError('POLICY_NOT_FOUND', {
+						data: {
+							policyId,
+							type,
+						},
+					});
+				}
+				if (!policy.isActive) {
+					throw new ORPCError('POLICY_INACTIVE', {
+						data: {
+							policyId,
+							type,
+						},
+					});
+				}
+			} else {
+				const policy = await typedContext.registry.findOrCreatePolicy(type);
+				if (!policy) {
+					throw new ORPCError('POLICY_CREATION_FAILED', {
+						data: {
+							type,
+						},
+					});
+				}
+				policyId = policy.id;
+			}
+
+			// Handle purposes if they exist
+			if (preferences) {
+				const consentedPurposes = Object.entries(preferences)
+					.filter(([_, isConsented]) => isConsented)
+					.map(([purposeCode]) => purposeCode);
+
+				// Batch fetch all existing purposes
+				const existingPurposes = await Promise.all(
+					consentedPurposes.map((purposeCode) =>
+						typedContext.registry.findConsentPurposeByCode(purposeCode)
+					)
+				);
+
+				// Find which purposes need to be created
+				const purposesToCreate = consentedPurposes.filter(
+					(_purposeCode, index) => !existingPurposes[index]
+				);
+
+				// Batch create missing purposes
+				const createdPurposes = await Promise.all(
+					purposesToCreate.map((purposeCode) =>
+						typedContext.registry.createConsentPurpose({
+							code: purposeCode,
+							name: purposeCode,
+							description: `Auto-created consentPurpose for ${purposeCode}`,
+							isActive: true,
+							isEssential: false,
+							legalBasis: 'consent',
+							createdAt: now,
+							updatedAt: now,
+						})
+					)
+				);
+
+				// Combine existing and newly created purposes
+				purposeIds = [
+					...existingPurposes
+						.filter((p): p is NonNullable<typeof p> => p !== null)
+						.map((p) => p.id),
+					...createdPurposes
+						.filter((p): p is NonNullable<typeof p> => p !== null)
+						.map((p) => p.id),
+				];
+
+				// Verify all purposes were created successfully
+				if (purposeIds.length !== consentedPurposes.length) {
+					throw new ORPCError('PURPOSE_CREATION_FAILED', {
+						data: {
+							purposeCode:
+								purposesToCreate[purposeIds.length - consentedPurposes.length],
+						},
+					});
+				}
+			}
+
+			const result = await typedContext.adapter.transaction({
+				callback: async (tx: Adapter) => {
+					// Create consent record
+					const consentRecord = (await tx.create({
+						model: 'consent',
+						data: {
+							subjectId: subject.id,
+							domainId: domainRecord.id,
+							policyId,
+							purposeIds,
+							status: 'active',
+							isActive: true,
+							givenAt: now,
+							ipAddress: typedContext.ipAddress || 'unknown',
+							agent: typedContext.userAgent || 'unknown',
+							history: [],
+						},
+					})) as unknown as Consent;
+
+					// Create record entry
+					const record = (await tx.create({
+						model: 'consentRecord',
+						data: {
+							subjectId: subject.id,
+							consentId: consentRecord.id,
+							actionType: 'consent_given',
+							details: metadata,
+							createdAt: now,
+						},
+					})) as unknown as ConsentRecord;
+
+					// Create audit log entry
+					await tx.create({
+						model: 'auditLog',
+						data: {
+							subjectId: subject.id,
+							entityType: 'consent',
+							entityId: consentRecord.id,
+							actionType: 'consent_given',
+							details: {
+								consentId: consentRecord.id,
+								type,
+							},
+							timestamp: now,
+							ipAddress: typedContext.ipAddress || 'unknown',
+							agent: typedContext.userAgent || 'unknown',
+						},
+					});
+
+					return {
+						consent: consentRecord,
+						record,
+					};
+				},
+			});
+
+			if (!result || !result.consent || !result.record) {
+				throw new ORPCError('CONSENT_CREATION_FAILED', {
+					data: {
+						subjectId: subject.id,
+						domain,
+					},
+				});
+			}
+
+			// Return the response in the format defined by the contract
+			return {
+				id: result.consent.id,
+				subjectId: subject.id,
+				externalSubjectId: subject.externalId ?? undefined,
+				domainId: domainRecord.id,
+				domain: domainRecord.name,
+				type,
+				status: result.consent.status,
+				recordId: result.record.id,
+				metadata,
+				givenAt: result.consent.givenAt,
+			};
+		} catch (error) {
+			// Log all errors properly
+			logger.error('Error in post-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),
+			});
+		}
+	}
+);

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

@@ -0,0 +1,148 @@
+import { describe, expect, it, vi } from 'vitest';
+import { JurisdictionMessages } from '~/contracts/shared/jurisdiction.schema';
+import { showConsentBanner } from './show-banner.handler';
+
+// First, mock the oRPC handler
+vi.mock('~/contracts', () => ({
+	os: {
+		consent: {
+			showBanner: {
+				handler: (fn: unknown) => fn, // Make the handler function directly callable for testing
+			},
+		},
+	},
+}));
+
+describe('Show Consent Banner Handler', () => {
+	// Helper to create mock context with headers
+	const createMockContext = (headers: Record<string, string>) => {
+		return {
+			context: {
+				headers: new Headers(headers),
+			},
+		};
+	};
+
+	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('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();
+		});
+	});
+
+	describe('Jurisdiction determination', () => {
+		it('identifies EU countries as GDPR', async () => {
+			//@ts-expect-error
+			const result = await showConsentBanner(
+				createMockContext({ 'cf-ipcountry': 'DE' })
+			);
+
+			expect(result.showConsentBanner).toBe(true);
+			expect(result.jurisdiction.code).toBe('GDPR');
+			expect(result.jurisdiction.message).toBe(JurisdictionMessages.GDPR);
+		});
+
+		it('identifies UK as GDPR', async () => {
+			//@ts-expect-error
+			const result = await showConsentBanner(
+				createMockContext({ 'cf-ipcountry': 'GB' })
+			);
+
+			expect(result.showConsentBanner).toBe(true);
+			expect(result.jurisdiction.code).toBe('GDPR');
+		});
+
+		it('identifies other jurisdictions correctly', async () => {
+			const cases = [
+				{ country: 'CH', code: 'CH' },
+				{ country: 'BR', code: 'BR' },
+				{ country: 'CA', code: 'PIPEDA' },
+				{ country: 'AU', code: 'AU' },
+				{ country: 'JP', code: 'APPI' },
+				{ country: 'KR', code: 'PIPA' },
+			];
+
+			for (const testCase of cases) {
+				//@ts-expect-error
+				const result = await showConsentBanner(
+					createMockContext({ 'cf-ipcountry': testCase.country })
+				);
+
+				expect(result.showConsentBanner).toBe(true);
+				expect(result.jurisdiction.code).toBe(testCase.code);
+
+				expect(result.jurisdiction.message).toBe(
+					JurisdictionMessages[
+						testCase.code as keyof typeof JurisdictionMessages
+					]
+				);
+			}
+		});
+
+		it('identifies non-regulated countries', async () => {
+			//@ts-expect-error
+			const result = await showConsentBanner(
+				createMockContext({ 'cf-ipcountry': 'US' })
+			);
+
+			expect(result.showConsentBanner).toBe(false);
+			expect(result.jurisdiction.code).toBe('NONE');
+			expect(result.jurisdiction.message).toBe(JurisdictionMessages.NONE);
+		});
+	});
+
+	describe('Response format', () => {
+		it('returns properly structured response', async () => {
+			//@ts-expect-error
+			const result = await showConsentBanner(
+				createMockContext({ 'cf-ipcountry': 'DE' })
+			);
+
+			expect(result).toEqual({
+				showConsentBanner: true,
+				jurisdiction: {
+					code: 'GDPR',
+					message: JurisdictionMessages.GDPR,
+				},
+				location: {
+					countryCode: 'DE',
+					regionCode: null,
+				},
+			});
+		});
+	});
+});

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

@@ -0,0 +1,150 @@
+import { ORPCError } from '@orpc/server';
+import { os } from '~/contracts';
+import {
+	type JurisdictionCode,
+	JurisdictionMessages,
+} from '~/contracts/shared/jurisdiction.schema';
+import type { C15TContext } from '~/types';
+
+/**
+ * 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;
+
+		// Extract country and region from request headers
+		const headers = typedContext.headers;
+		if (!headers) {
+			throw new ORPCError('LOCATION_DETECTION_FAILED', {
+				data: {
+					reason: 'No headers found in request context',
+				},
+			});
+		}
+
+		// 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('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'));
+
+		// If no location headers found, throw error
+
+		// Determine jurisdiction based on country
+		const { showConsentBanner, jurisdictionCode, message } =
+			checkJurisdiction(countryCode);
+
+		// Return properly structured response
+		return {
+			showConsentBanner,
+			jurisdiction: {
+				code: jurisdictionCode,
+				message,
+			},
+			location: { countryCode, regionCode },
+		};
+	}
+);
+
+/**
+ * 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
+	let showConsentBanner = false;
+	let jurisdictionCode: JurisdictionCode = 'NONE';
+
+	// Check country code against jurisdiction sets
+	if (countryCode) {
+		// 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(countryCode))) {
+				showConsentBanner = true;
+				jurisdictionCode = code;
+				break;
+			}
+		}
+	}
+
+	// Get corresponding message from shared schema
+	const message = JurisdictionMessages[jurisdictionCode];
+
+	return {
+		showConsentBanner,
+		jurisdictionCode,
+		message,
+	};
+}