@c15t/backend 1.5.0 → 1.6.0

package/src/v2/contracts/consent/show-banner.contract.test.ts

@@ -0,0 +1,252 @@
+import { baseTranslations } from '@c15t/translations';
+import { describe, expect, it } from 'vitest';
+
+import { showConsentBannerContract } from './show-banner.contract';
+
+// Add custom tests specific to the show-banner contract
+describe('Show Consent Banner Contract Custom Tests', () => {
+	// Helper to access schemas consistently throughout tests
+	const schemas = {
+		input: showConsentBannerContract['~orpc'].inputSchema,
+		output: showConsentBannerContract['~orpc'].outputSchema,
+	};
+
+	const validateOutput = (output: unknown) => {
+		return schemas.output?.safeParse(output);
+	};
+
+	describe('Output Validation', () => {
+		describe('Required fields', () => {
+			it('validates complete output object', () => {
+				const validOutput = {
+					showConsentBanner: true,
+					jurisdiction: {
+						code: 'GDPR',
+						message: 'GDPR or equivalent regulations require a cookie banner.',
+					},
+					location: {
+						countryCode: 'DE',
+						regionCode: null,
+					},
+					translations: {
+						translations: baseTranslations.en,
+						language: 'en',
+					},
+					branding: 'c15t',
+				};
+
+				const result = validateOutput(validOutput);
+				expect(result?.success).toBe(true);
+			});
+
+			it('rejects output without required fields', () => {
+				const invalidOutput = {
+					showConsentBanner: true,
+					// Missing jurisdiction and location
+				};
+
+				const result = validateOutput(invalidOutput);
+				expect(result?.success).toBe(false);
+			});
+		});
+
+		describe('Jurisdiction validation', () => {
+			it('validates all supported jurisdiction codes', () => {
+				const jurisdictionCodes = [
+					'GDPR',
+					'CH',
+					'BR',
+					'PIPEDA',
+					'AU',
+					'APPI',
+					'PIPA',
+					'NONE',
+				];
+
+				for (const code of jurisdictionCodes) {
+					const output = {
+						showConsentBanner: true,
+						jurisdiction: {
+							code,
+							message: 'Test message',
+						},
+						location: {
+							countryCode: 'US',
+							regionCode: null,
+						},
+						translations: {
+							translations: baseTranslations.en,
+							language: 'en',
+						},
+						branding: 'c15t',
+					};
+
+					const result = validateOutput(output);
+					expect(result?.success).toBe(true);
+				}
+			});
+
+			it('rejects invalid jurisdiction codes', () => {
+				const output = {
+					showConsentBanner: true,
+					jurisdiction: {
+						code: 'INVALID_CODE', // Invalid code
+						message: 'Test message',
+					},
+					location: {
+						countryCode: 'US',
+						regionCode: null,
+					},
+					translations: {
+						translations: baseTranslations.en,
+						language: 'en',
+					},
+					branding: 'c15t',
+				};
+
+				const result = validateOutput(output);
+				expect(result?.success).toBe(false);
+			});
+		});
+
+		describe('Location validation', () => {
+			it('accepts null country and region codes', () => {
+				const output = {
+					showConsentBanner: false,
+					jurisdiction: {
+						code: 'NONE',
+						message: 'No specific requirements',
+					},
+					location: {
+						countryCode: null,
+						regionCode: null,
+					},
+					translations: {
+						translations: baseTranslations.en,
+						language: 'en',
+					},
+					branding: 'c15t',
+				};
+
+				const result = validateOutput(output);
+				expect(result?.success).toBe(true);
+			});
+
+			it('accepts valid country and region codes', () => {
+				const output = {
+					showConsentBanner: true,
+					jurisdiction: {
+						code: 'GDPR',
+						message: 'GDPR applies',
+					},
+					location: {
+						countryCode: 'DE',
+						regionCode: 'BY',
+					},
+					translations: {
+						translations: baseTranslations.en,
+						language: 'en',
+					},
+					branding: 'c15t',
+				};
+				const result = validateOutput(output);
+				expect(result?.success).toBe(true);
+			});
+
+			it('rejects non-string non-null country codes', () => {
+				const output = {
+					showConsentBanner: true,
+					jurisdiction: {
+						code: 'GDPR',
+						message: 'GDPR applies',
+					},
+					location: {
+						countryCode: 123, // Invalid type
+						regionCode: null,
+					},
+					translations: {
+						translations: baseTranslations.en,
+						language: 'en',
+					},
+					branding: 'c15t',
+				};
+
+				// Need to use type assertion to bypass TypeScript
+				const result = validateOutput(output);
+				expect(result?.success).toBe(false);
+			});
+		});
+
+		describe('ShowConsentBanner flag', () => {
+			it('validates boolean value', () => {
+				const trueOutput = {
+					showConsentBanner: true,
+					jurisdiction: {
+						code: 'GDPR',
+						message: 'GDPR applies',
+					},
+					location: {
+						countryCode: 'DE',
+						regionCode: null,
+					},
+					translations: {
+						translations: baseTranslations.en,
+						language: 'en',
+					},
+					branding: 'c15t',
+				};
+
+				const falseOutput = {
+					showConsentBanner: false,
+					jurisdiction: {
+						code: 'NONE',
+						message: 'No requirements',
+					},
+					location: {
+						countryCode: 'US',
+						regionCode: null,
+					},
+					translations: {
+						translations: baseTranslations.en,
+						language: 'en',
+					},
+					branding: 'c15t',
+				};
+
+				expect(validateOutput(trueOutput)?.success).toBe(true);
+				expect(validateOutput(falseOutput)?.success).toBe(true);
+			});
+
+			it('rejects non-boolean values', () => {
+				const invalidOutput = {
+					showConsentBanner: 'yes', // Invalid type
+					jurisdiction: {
+						code: 'GDPR',
+						message: 'GDPR applies',
+					},
+					location: {
+						countryCode: 'DE',
+						regionCode: null,
+					},
+					translations: {
+						translations: baseTranslations.en,
+						language: 'en',
+					},
+					branding: 'c15t',
+				};
+
+				// Need to use type assertion to bypass TypeScript
+				const result = validateOutput(invalidOutput);
+				expect(result?.success).toBe(false);
+			});
+		});
+	});
+});
+
+// // Add required fields testing using the utility
+// // No required fields for input since it's an empty object
+// tester.testRequiredFields('output', [
+// 	'showConsentBanner',
+// 	'jurisdiction',
+// 	'location',
+// ]);

package/src/v2/contracts/consent/show-banner.contract.ts

@@ -0,0 +1,73 @@
+import { oc } from '@orpc/contract';
+import { z } from 'zod';
+import { branding } from '~/v2/types';
+import { JurisdictionInfoSchema } from '../shared/jurisdiction.schema';
+
+const TitleDescriptionSchema = z.object({
+	title: z.string(),
+	description: z.string(),
+});
+
+const TranslationsSchema = z.object({
+	common: z.object({
+		acceptAll: z.string(),
+		rejectAll: z.string(),
+		customize: z.string(),
+		save: z.string(),
+	}),
+	cookieBanner: TitleDescriptionSchema,
+	consentManagerDialog: TitleDescriptionSchema,
+	consentTypes: z.object({
+		experience: TitleDescriptionSchema,
+		functionality: TitleDescriptionSchema,
+		marketing: TitleDescriptionSchema,
+		measurement: TitleDescriptionSchema,
+		necessary: TitleDescriptionSchema,
+	}),
+});
+
+export const showConsentBannerContract = oc
+	.route({
+		method: 'GET',
+		path: '/show-consent-banner',
+		description: `Determines if a user should see a consent banner based on their location and applicable privacy regulations.
+This endpoint performs the following checks:
+
+1. Detects the user's location using various header information:
+   - Cloudflare country headers
+   - Vercel IP country headers
+   - AWS CloudFront headers
+   - Custom country code headers
+
+2. Determines the applicable jurisdiction based on the location:
+   - GDPR (EU/EEA/UK)
+   - Swiss Data Protection Act
+   - LGPD (Brazil)
+   - PIPEDA (Canada)
+   - Australian Privacy Principles
+   - APPI (Japan)
+   - PIPA (South Korea)
+
+3. Returns detailed information about:
+   - Whether to show the consent banner
+   - The applicable jurisdiction and its requirements
+   - The user's detected location (country and region)
+
+Use this endpoint to implement geo-targeted consent banners and ensure compliance with regional privacy regulations.`,
+		tags: ['cookie-banner'],
+	})
+	.output(
+		z.object({
+			showConsentBanner: z.boolean(),
+			jurisdiction: JurisdictionInfoSchema,
+			location: z.object({
+				countryCode: z.string().nullable(),
+				regionCode: z.string().nullable(),
+			}),
+			translations: z.object({
+				language: z.string(),
+				translations: TranslationsSchema,
+			}),
+			branding: z.enum(branding),
+		})
+	);

package/src/v2/contracts/consent/verify.contract.test.ts

@@ -0,0 +1,185 @@
+import { describe, expect, it } from 'vitest';
+
+import { createContractTests } from '~/v2/contracts/test.utils';
+import { verifyConsentContract } from './verify.contract';
+
+// Create base tests for the contract using the utility
+const tester = createContractTests('Verify Consent', verifyConsentContract);
+
+// Custom tests specific to verify consent
+describe('Verify Consent Contract Custom Tests', () => {
+	// Helper to access schemas consistently throughout tests
+	const schemas = {
+		input: verifyConsentContract['~orpc'].inputSchema,
+		output: verifyConsentContract['~orpc'].outputSchema,
+	};
+
+	// Helper functions for common test patterns
+	const validateInput = (input: unknown) => {
+		return schemas.input?.safeParse(input);
+	};
+
+	const validateOutput = (output: unknown) => {
+		return schemas.output?.safeParse(output);
+	};
+
+	describe('Input Validation', () => {
+		it('accepts valid input with minimum required fields', () => {
+			const validInput = {
+				domain: 'example.com',
+				type: 'cookie_banner',
+			};
+
+			const result = validateInput(validInput);
+			expect(result?.success).toBe(true);
+		});
+
+		it('accepts valid input with all fields', () => {
+			const validInput = {
+				subjectId: 'subject-123',
+				externalSubjectId: 'ext-123',
+				domain: 'example.com',
+				type: 'privacy_policy',
+				policyId: 'policy-123',
+				preferences: ['analytics', 'marketing'],
+			};
+
+			const result = validateInput(validInput);
+			expect(result?.success).toBe(true);
+		});
+
+		it('rejects input without required domain', () => {
+			const invalidInput = {
+				type: 'cookie_banner',
+			};
+
+			const result = validateInput(invalidInput);
+			expect(result?.success).toBe(false);
+		});
+
+		it('rejects input without required type', () => {
+			const invalidInput = {
+				domain: 'example.com',
+			};
+
+			const result = validateInput(invalidInput);
+			expect(result?.success).toBe(false);
+		});
+
+		it('rejects input with invalid type', () => {
+			const invalidInput = {
+				domain: 'example.com',
+				type: 'invalid_type', // Not in PolicyTypeSchema
+			};
+
+			const result = validateInput(invalidInput);
+			expect(result?.success).toBe(false);
+		});
+
+		it('rejects input with extra properties', () => {
+			const invalidInput = {
+				domain: 'example.com',
+				type: 'cookie_banner',
+				extraProperty: 'should not be allowed',
+			};
+
+			const result = validateInput(invalidInput);
+			expect(result?.success).toBe(false);
+		});
+
+		it('validates preferences as array of strings', () => {
+			const validInput = {
+				domain: 'example.com',
+				type: 'cookie_banner',
+				preferences: ['analytics', 'marketing'],
+			};
+
+			expect(validateInput(validInput)?.success).toBe(true);
+
+			const invalidInput = {
+				domain: 'example.com',
+				type: 'cookie_banner',
+				preferences: { analytics: true }, // Object instead of array
+			};
+
+			expect(validateInput(invalidInput)?.success).toBe(false);
+		});
+	});
+
+	describe('Output Validation', () => {
+		it('validates successful consent verification', () => {
+			const validOutput = {
+				isValid: true,
+				consent: {
+					id: 'consent-123',
+					purposeIds: ['analytics', 'marketing'],
+					additionalProperty: 'allowed by passthrough',
+				},
+			};
+
+			const result = validateOutput(validOutput);
+			expect(result?.success).toBe(true);
+		});
+
+		it('validates unsuccessful consent verification with reasons', () => {
+			const validOutput = {
+				isValid: false,
+				reasons: ['No consent found for the given policy'],
+			};
+
+			const result = validateOutput(validOutput);
+			expect(result?.success).toBe(true);
+		});
+
+		it('rejects output without required isValid field', () => {
+			const invalidOutput = {
+				reasons: ['Some reason'],
+			};
+
+			const result = validateOutput(invalidOutput);
+			expect(result?.success).toBe(false);
+		});
+
+		it('validates consent object structure', () => {
+			const invalidOutput = {
+				isValid: true,
+				consent: {
+					// Missing required id
+					purposeIds: ['analytics'],
+				},
+			};
+
+			expect(validateOutput(invalidOutput)?.success).toBe(false);
+
+			const anotherInvalidOutput = {
+				isValid: true,
+				consent: {
+					id: 'consent-123',
+					// Missing required purposeIds
+				},
+			};
+
+			expect(validateOutput(anotherInvalidOutput)?.success).toBe(false);
+		});
+
+		it('validates reasons as array of strings', () => {
+			const validOutput = {
+				isValid: false,
+				reasons: ['Reason 1', 'Reason 2'],
+			};
+
+			expect(validateOutput(validOutput)?.success).toBe(true);
+
+			const invalidOutput = {
+				isValid: false,
+				reasons: 'Single reason', // String instead of array
+			};
+
+			expect(validateOutput(invalidOutput)?.success).toBe(false);
+		});
+	});
+});
+
+// Add required fields testing
+tester.testRequiredFields('input', ['domain', 'type']);
+tester.testRequiredFields('output', ['isValid']);

package/src/v2/contracts/consent/verify.contract.ts

@@ -0,0 +1,122 @@
+import { oc } from '@orpc/contract';
+import { z } from 'zod';
+import { PolicyTypeSchema } from '~/v2/db/schema';
+
+/**
+ * Contract for the verify consent endpoint
+ * Verifies if a user has given consent for a specific policy
+ */
+
+// Input schema based on VerifyConsentRequestBody
+const verifyConsentInputSchema = z.strictObject({
+	subjectId: z.string().optional(),
+	externalSubjectId: z.string().optional(),
+	domain: z.string(),
+	type: PolicyTypeSchema,
+	policyId: z.string().optional(),
+	preferences: z.array(z.string()).optional(),
+});
+
+// Minimal consent schema based on the response interface
+const consentSchema = z.looseObject({
+	id: z.string(),
+	purposeIds: z.array(z.string()),
+}); // Allow additional properties
+
+// Output schema based on VerifyConsentResponse
+export const verifyConsentContract = oc
+	.route({
+		method: 'POST',
+		path: '/consent/verify',
+		description: `Verifies if a user has given valid consent for a specific policy and domain.
+This endpoint performs comprehensive consent verification by:
+
+1. Validating the subject's identity (using subjectId or externalSubjectId)
+2. Verifying the domain's existence and validity
+3. Checking if the specified policy exists and is active
+4. Validating that all required purposes have been consented to
+5. Ensuring the consent record is current and valid
+
+The endpoint supports different types of consent verification:
+- Cookie banner consent verification
+- Privacy policy consent verification
+- Terms and conditions verification
+- Marketing communications consent verification
+- Age verification
+- Custom consent types
+
+Use this endpoint to ensure compliance with privacy regulations and to verify user consent before processing personal data.`,
+		tags: ['consent'],
+	})
+	.errors({
+		// Input validation errors
+		INPUT_VALIDATION_FAILED: {
+			status: 422,
+			data: z.object({
+				formErrors: z.array(z.string()),
+				fieldErrors: z.record(z.string(), z.array(z.string()).optional()),
+			}),
+			error: 'Invalid input parameters',
+		},
+		// Subject errors
+		SUBJECT_NOT_FOUND: {
+			status: 404,
+			data: z.object({
+				subjectId: z.string().optional(),
+				externalSubjectId: z.string().optional(),
+			}),
+			error: 'Subject not found',
+		},
+		// Domain errors
+		DOMAIN_NOT_FOUND: {
+			status: 404,
+			data: z.object({
+				domain: z.string(),
+			}),
+			error: 'Domain not found',
+		},
+		// Policy errors
+		POLICY_NOT_FOUND: {
+			status: 404,
+			data: z.object({
+				policyId: z.string(),
+				type: z.string(),
+			}),
+			error: 'Policy not found or invalid',
+		},
+		// Purpose errors
+		PURPOSES_NOT_FOUND: {
+			status: 404,
+			data: z.object({
+				preferences: z.array(z.string()),
+				foundPurposes: z.array(z.string()),
+			}),
+			error: 'Could not find all specified purposes',
+		},
+		// Cookie banner specific errors
+		COOKIE_BANNER_PREFERENCES_REQUIRED: {
+			status: 400,
+			data: z.object({
+				type: z.literal('cookie_banner'),
+			}),
+			error: 'Preferences are required for cookie banner consent',
+		},
+		// Consent errors
+		NO_CONSENT_FOUND: {
+			status: 404,
+			data: z.object({
+				policyId: z.string(),
+				subjectId: z.string(),
+				domainId: z.string(),
+			}),
+			error: 'No consent found for the given policy',
+		},
+	})
+	.input(verifyConsentInputSchema)
+	.output(
+		z.object({
+			isValid: z.boolean(),
+			reasons: z.array(z.string()).optional(),
+			consent: consentSchema.optional(),
+		})
+	);

package/src/v2/contracts/index.ts

@@ -0,0 +1,20 @@
+import type {
+	InferContractRouterInputs,
+	InferContractRouterOutputs,
+} from '@orpc/contract';
+import { implement } from '@orpc/server';
+
+import { consentContracts } from './consent';
+import { metaContracts } from './meta';
+
+const config = {
+	consent: consentContracts,
+	meta: metaContracts,
+};
+
+export { config as contracts };
+
+export const os = implement(config);
+
+export type ContractsOutputs = InferContractRouterOutputs<typeof config>;
+export type ContractsInputs = InferContractRouterInputs<typeof config>;

package/src/v2/contracts/meta/index.test.ts

@@ -0,0 +1,5 @@
+import { createConsistencyTests } from '~/v2/contracts/test.utils';
+import { metaContracts } from './index';
+
+// Add consistency tests across all meta contracts
+createConsistencyTests(metaContracts);

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

@@ -0,0 +1,5 @@
+import { statusContract } from './status.contract';
+
+export const metaContracts = {
+	status: statusContract,
+};