@c15t/backend 1.5.0 → 1.6.0

package/src/v2/contracts/meta/status.contract.test.ts

@@ -0,0 +1,226 @@
+import { describe, expect, it } from 'vitest';
+
+import { createContractTests } from '~/v2/contracts/test.utils';
+import { statusContract } from './status.contract';
+
+// Create base tests for the contract using the utility
+const tester = createContractTests('Status', statusContract);
+
+// Add custom tests specific to the status contract
+describe('Status Contract Custom Tests', () => {
+	// Helper to access schemas consistently throughout tests
+	const schemas = {
+		input: statusContract['~orpc'].inputSchema,
+		output: statusContract['~orpc'].outputSchema,
+	};
+
+	// Helper functions for common test patterns
+	const validateInput = (input: unknown) => {
+		//@ts-expect-error
+		return schemas.input?.safeParse(input);
+	};
+
+	const validateOutput = (output: unknown) => {
+		return schemas.output?.safeParse(output);
+	};
+
+	describe('Schema Structure', () => {
+		it('input schema is an undefined', () => {
+			const result = validateInput(undefined);
+			expect(result?.success).toBe(undefined);
+		});
+
+		it('rejects input with extra properties', () => {
+			const result = validateInput({ extraProp: 'value' });
+			expect(result?.success).toBe(undefined);
+		});
+	});
+
+	describe('Output Validation', () => {
+		describe('Required fields', () => {
+			it('validates complete output object', () => {
+				const validOutput = {
+					status: 'ok',
+					version: '1.0.0',
+					timestamp: new Date(),
+					client: {
+						ip: '127.0.0.1',
+						userAgent: 'Mozilla/5.0',
+						region: {
+							countryCode: 'US',
+							regionCode: 'CA',
+						},
+					},
+				};
+
+				const result = validateOutput(validOutput);
+				expect(result?.success).toBe(true);
+			});
+
+			it('rejects output without required fields', () => {
+				const invalidOutput = {
+					status: 'ok',
+					// Missing version, timestamp, and client
+				};
+
+				const result = validateOutput(invalidOutput);
+				expect(result?.success).toBe(false);
+			});
+		});
+
+		describe('Status field validation', () => {
+			it('accepts valid status values', () => {
+				for (const statusValue of ['ok', 'error']) {
+					const output = {
+						status: statusValue,
+						version: '1.0.0',
+						timestamp: new Date(),
+						client: {
+							ip: '127.0.0.1',
+							userAgent: 'Mozilla/5.0',
+							region: {
+								countryCode: 'US',
+								regionCode: 'CA',
+							},
+						},
+					};
+					const result = validateOutput(output);
+					expect(result?.success).toBe(true);
+				}
+			});
+
+			it('rejects invalid status values', () => {
+				const output = {
+					status: 'unknown', // Invalid status
+					version: '1.0.0',
+					timestamp: new Date(),
+					client: {
+						ip: '127.0.0.1',
+						userAgent: 'Mozilla/5.0',
+						region: {
+							countryCode: 'US',
+							regionCode: 'CA',
+						},
+					},
+				};
+				// Need to use type assertion to bypass TypeScript
+				const result = validateOutput(output);
+				expect(result?.success).toBe(false);
+			});
+		});
+
+		describe('Timestamp validation', () => {
+			it('accepts Date objects', () => {
+				const output = {
+					status: 'ok',
+					version: '1.0.0',
+					timestamp: new Date(),
+					client: {
+						ip: '127.0.0.1',
+						userAgent: 'Mozilla/5.0',
+						region: {
+							countryCode: 'US',
+							regionCode: 'CA',
+						},
+					},
+				};
+				const result = validateOutput(output);
+				expect(result?.success).toBe(true);
+			});
+
+			it('rejects string timestamps', () => {
+				const output = {
+					status: 'ok',
+					version: '1.0.0',
+					timestamp: new Date().toISOString(), // String instead of Date
+				};
+
+				// Need to use type assertion to bypass TypeScript
+				const result = validateOutput(output);
+				expect(result?.success).toBe(false);
+			});
+		});
+
+		describe('Client information validation', () => {
+			it('accepts null values for client fields', () => {
+				const output = {
+					status: 'ok',
+					version: '1.0.0',
+					timestamp: new Date(),
+					client: {
+						ip: null,
+						userAgent: null,
+						region: {
+							countryCode: null,
+							regionCode: null,
+						},
+					},
+				};
+
+				const result = validateOutput(output);
+				expect(result?.success).toBe(true);
+			});
+
+			it('validates client object structure', () => {
+				const output = {
+					status: 'ok',
+					version: '1.0.0',
+					timestamp: new Date(),
+					client: {
+						ip: '127.0.0.1',
+						userAgent: 'Mozilla/5.0',
+						region: {
+							countryCode: 'US',
+							regionCode: 'CA',
+						},
+					},
+				};
+
+				const result = validateOutput(output);
+				expect(result?.success).toBe(true);
+			});
+
+			it('rejects invalid client IP format', () => {
+				const output = {
+					status: 'ok',
+					version: '1.0.0',
+					timestamp: new Date(),
+					client: {
+						ip: 123, // Number instead of string
+						userAgent: 'Mozilla/5.0',
+						region: {
+							countryCode: 'US',
+							regionCode: 'CA',
+						},
+					},
+				};
+
+				const result = validateOutput(output);
+				expect(result?.success).toBe(false);
+			});
+
+			it('rejects invalid region structure', () => {
+				const output = {
+					status: 'ok',
+					version: '1.0.0',
+					timestamp: new Date(),
+					client: {
+						ip: '127.0.0.1',
+						userAgent: 'Mozilla/5.0',
+						region: {
+							countryCode: 123, // Number instead of string
+							regionCode: 'CA',
+						},
+					},
+				};
+
+				const result = validateOutput(output);
+				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', ['status', 'version', 'timestamp']);

package/src/v2/contracts/meta/status.contract.ts

@@ -0,0 +1,34 @@
+import { oc } from '@orpc/contract';
+import { z } from 'zod';
+
+export const statusContract = oc
+	.route({
+		method: 'GET',
+		path: '/status',
+		description: `Returns the current operational status and health metrics of the service.
+This endpoint provides real-time information about:
+- Overall service status (ok/error)
+- Current API version
+- Server timestamp
+- Storage system status and availability
+- Client information (IP, User Agent, Region)
+
+Use this endpoint for health checks, monitoring, and service status verification.`,
+		tags: ['meta'],
+	})
+	.output(
+		z.object({
+			status: z.enum(['ok', 'error']),
+			version: z.string(),
+			timestamp: z.date(),
+
+			client: z.object({
+				ip: z.string().nullable(),
+				userAgent: z.string().nullable(),
+				region: z.object({
+					countryCode: z.string().nullable(),
+					regionCode: z.string().nullable(),
+				}),
+			}),
+		})
+	);

package/src/v2/contracts/shared/jurisdiction.schema.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+
+export const JurisdictionMessages = {
+	GDPR: 'GDPR or equivalent regulations require a cookie banner.',
+	CH: 'Switzerland requires similar data protection measures.',
+	BR: "Brazil's LGPD requires consent for cookies.",
+	PIPEDA: 'PIPEDA requires consent for data collection.',
+	AU: "Australia's Privacy Act mandates transparency about data collection.",
+	APPI: "Japan's APPI requires consent for data collection.",
+	PIPA: "South Korea's PIPA requires consent for data collection.",
+	NONE: 'No specific requirements',
+} as const;
+
+export type JurisdictionCode = keyof typeof JurisdictionMessages;
+
+export const JurisdictionCodeSchema = z.enum([
+	'GDPR',
+	'CH',
+	'BR',
+	'PIPEDA',
+	'AU',
+	'APPI',
+	'PIPA',
+	'NONE',
+]);
+
+export const JurisdictionInfoSchema = z.object({
+	code: JurisdictionCodeSchema,
+	message: z.string(),
+});

package/src/v2/contracts/test.utils.ts

@@ -0,0 +1,400 @@
+import type { Schema as ORPCSchema } from '@orpc/contract';
+import { describe, expect, it } from 'vitest';
+import type { ZodIssue, z } from 'zod';
+
+/**
+ * Contract test utilities for creating reusable test patterns
+ * across multiple contracts
+ */
+
+type SafeParseResult = ReturnType<z.ZodTypeAny['safeParse']>;
+
+type ContractTestHelpers = {
+	validateInput?: (input: unknown) => SafeParseResult | undefined;
+	validateOutput: (output: unknown) => SafeParseResult | undefined;
+	testInput: (testName: string, input: unknown, shouldBeValid: boolean) => void;
+	testOutput: (
+		testName: string,
+		output: unknown,
+		shouldBeValid: boolean
+	) => void;
+	testDiscriminatedUnion: (
+		discriminator: string,
+		validValues: string[]
+	) => void;
+	testRequiredFields: (schema: 'input' | 'output', fields: string[]) => void;
+};
+
+type ContractSchema = z.ZodType | ORPCSchema<unknown, unknown>;
+
+/**
+ * Creates a test suite for basic contract validation
+ * @param contractName Display name for the contract
+ * @param contract The contract to test
+ */
+export function createContractTests(
+	contractName: string,
+	contract: {
+		'~orpc'?: { inputSchema?: ContractSchema; outputSchema?: ContractSchema };
+	}
+): ContractTestHelpers {
+	const schemas = {
+		input: contract['~orpc']?.inputSchema,
+		output: contract['~orpc']?.outputSchema,
+	};
+
+	// Helper functions
+	const validateInput = (input: unknown): SafeParseResult | undefined => {
+		const schema = schemas.input;
+		if (!schema) {
+			return undefined;
+		}
+
+		// Handle both Zod and oRPC schemas
+		if ('safeParse' in schema) {
+			return schema.safeParse(input);
+		}
+		// For oRPC schemas, we'll need to implement validation
+		// This is a placeholder - you may need to implement actual validation
+		return { success: true, data: input } as SafeParseResult;
+	};
+
+	const validateOutput = (output: unknown): SafeParseResult | undefined => {
+		const schema = schemas.output;
+		if (!schema) {
+			return undefined;
+		}
+
+		// Handle both Zod and oRPC schemas
+		if ('safeParse' in schema) {
+			return schema.safeParse(output);
+		}
+		// For oRPC schemas, we'll need to implement validation
+		// This is a placeholder - you may need to implement actual validation
+		return { success: true, data: output } as SafeParseResult;
+	};
+
+	// Create base test suite
+	describe(`${contractName} Contract`, () => {
+		describe('Schema Structure', () => {
+			it('has properly defined schemas', () => {
+				// Only require output schema
+				expect(schemas.output).toBeDefined();
+
+				// Input schema is optional
+				if (schemas.input) {
+					expect(schemas.input).toBeDefined();
+				}
+			});
+
+			it('schemas are serializable', () => {
+				// Test serialization for output schema
+				if (schemas.output) {
+					const serialized = JSON.stringify(schemas.output);
+					expect(serialized).toBeDefined();
+					expect(typeof serialized).toBe('string');
+					expect(() => JSON.parse(serialized)).not.toThrow();
+				}
+
+				// Test serialization for input schema if it exists
+				if (schemas.input) {
+					const serialized = JSON.stringify(schemas.input);
+					expect(serialized).toBeDefined();
+					expect(typeof serialized).toBe('string');
+					expect(() => JSON.parse(serialized)).not.toThrow();
+				}
+			});
+		});
+	});
+
+	// Define test helpers
+	const testInput = (
+		testName: string,
+		input: unknown,
+		shouldBeValid: boolean
+	) => {
+		it(`${testName}`, () => {
+			const result = validateInput(input);
+			if (!result) {
+				throw new Error('Validation result is undefined');
+			}
+			expect(result.success).toBe(shouldBeValid);
+		});
+	};
+
+	const testOutput = (
+		testName: string,
+		output: unknown,
+		shouldBeValid: boolean
+	) => {
+		it(`${testName}`, () => {
+			const result = validateOutput(output);
+			if (!result) {
+				throw new Error('Validation result is undefined');
+			}
+			expect(result.success).toBe(shouldBeValid);
+		});
+	};
+
+	const testDiscriminatedUnion = (
+		discriminator: string,
+		validValues: string[]
+	) => {
+		describe('Discriminated Union validation', () => {
+			it(`requires '${discriminator}' discriminator`, () => {
+				if (!schemas.input) return;
+				const result = validateInput({});
+				expect(result?.success).toBe(false);
+			});
+
+			it('validates all defined discriminator values', () => {
+				if (!schemas.input) {
+					return;
+				}
+				for (const value of validValues) {
+					const input = {
+						[discriminator]: value,
+						// Add minimum required fields based on your contract
+					};
+
+					// This test assumes minimal input - you may need to add required fields
+					// based on the specific contract being tested
+					const result = validateInput(input);
+					// Specifically assert that it fails due to missing required fields
+					expect(result?.success).toBe(false);
+					// We no longer assert on internal issue codes; presence of failure is enough
+				}
+			});
+		});
+	};
+
+	const testRequiredFields = (schema: 'input' | 'output', fields: string[]) => {
+		describe(`Required ${schema} fields`, () => {
+			// Skip if testing input fields but no input schema exists
+			if (schema === 'input' && !schemas.input) {
+				it('skips input field tests as no input schema exists', () => {
+					expect(true).toBe(true);
+				});
+				return;
+			}
+
+			// Create a sample of valid data to test against
+			let sampleValid: Record<string, unknown>;
+
+			if (schema === 'input') {
+				// For input schema, we need a valid input based on the contract type
+				sampleValid = {
+					type: 'marketing_communications', // A common type that most contracts would have
+					domain: 'example.com',
+					// Add other fields that might be required by your contracts
+					subjectId: 'test-123',
+					metadata: {},
+				};
+			} else {
+				// For output schema, create a generic valid output
+				sampleValid = {
+					id: 'test-123',
+					domainId: 'domain-123',
+					domain: 'example.com',
+					type: 'marketing_communications',
+					status: 'granted',
+					recordId: 'record-123',
+					givenAt: new Date().toISOString(),
+					metadata: {},
+				};
+			}
+
+			for (const field of fields) {
+				it(`requires '${field}' field`, () => {
+					// Create a copy of the valid data without the tested field
+					const invalidData = { ...sampleValid };
+					delete invalidData[field];
+
+					const validator = schema === 'input' ? validateInput : validateOutput;
+					const result = validator(invalidData);
+
+					if (!result) {
+						throw new Error('Validation result is undefined');
+					}
+
+					expect(result.success).toBe(false);
+					if (!result.success) {
+						expect(
+							result.error.issues.some(
+								(issue: ZodIssue) =>
+									issue.path.some((p) => String(p).includes(field)) ||
+									issue.message.includes('required')
+							)
+						).toBe(true);
+					}
+				});
+			}
+		});
+	};
+
+	// Return the test helpers for re-use
+	return {
+		validateInput,
+		validateOutput,
+		testInput,
+		testOutput,
+		testDiscriminatedUnion,
+		testRequiredFields,
+	};
+}
+
+/**
+ * Creates consistency tests for multiple related contracts
+ */
+export function createConsistencyTests(
+	contracts: Record<
+		string,
+		{
+			'~orpc'?: {
+				inputSchema?: ContractSchema;
+				outputSchema?: ContractSchema;
+			};
+		}
+	>
+) {
+	describe('Contract Consistency', () => {
+		it('all contracts have output schemas', () => {
+			for (const [_name, contract] of Object.entries(contracts)) {
+				expect(contract['~orpc']?.outputSchema).toBeDefined();
+			}
+		});
+
+		// Field type consistency - ensure common fields use same types across contracts
+		// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: excessive cognitive complexity is acceptable here
+		it('common fields have consistent types across contracts', () => {
+			const commonFields = ['id', 'domainId', 'type', 'status'];
+			const contractEntries = Object.entries(contracts);
+
+			for (const field of commonFields) {
+				const fieldTypes = new Set();
+
+				for (const [_name, contract] of contractEntries) {
+					const schema = contract['~orpc']?.outputSchema;
+					if (!schema || !('shape' in schema)) {
+						continue;
+					}
+
+					const shape = schema.shape as Record<string, z.ZodTypeAny>;
+					if (field in shape) {
+						const fieldDef = shape[field];
+						if (fieldDef) {
+							fieldTypes.add(fieldDef.constructor.name);
+						}
+					}
+				}
+
+				// If the field exists in multiple contracts, they should all use the same type
+				if (fieldTypes.size > 0) {
+					expect(
+						fieldTypes.size,
+						`Field '${field}' has inconsistent types across contracts`
+					).toBe(1);
+				}
+			}
+		});
+
+		// Validate enum value consistency across contracts
+		// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: excessive cognitive complexity is acceptable here
+		it('enum values are consistent across contracts', () => {
+			// Example: status field should have the same allowed values in all contracts
+			const statusValues = new Map<string, string[]>();
+
+			for (const [name, contract] of Object.entries(contracts)) {
+				const schema = contract['~orpc']?.outputSchema;
+				if (!schema || !('shape' in schema)) {
+					continue;
+				}
+
+				const shape = schema.shape as Record<string, z.ZodTypeAny>;
+				if (!shape.status) {
+					continue;
+				}
+
+				const statusField = shape.status;
+				if ('_def' in statusField && 'values' in statusField._def) {
+					statusValues.set(name, statusField._def.values as string[]);
+				}
+			}
+
+			// All status enums should have the same values
+			const allValues = Array.from(statusValues.values());
+			if (allValues.length > 1) {
+				for (let i = 1; i < allValues.length; i++) {
+					expect(allValues[i]).toEqual(allValues[0]);
+				}
+			}
+		});
+
+		// Validation rule consistency for common fields
+		// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: excessive cognitive complexity is acceptable here
+		it('validation rules for common fields are consistent', () => {
+			const contractEntries = Object.entries(contracts);
+			const commonStringFields = ['domain', 'subjectId', 'externalSubjectId'];
+
+			for (const field of commonStringFields) {
+				const minLengths = new Set();
+				const maxLengths = new Set();
+
+				for (const [_name, contract] of contractEntries) {
+					const schema = contract['~orpc']?.inputSchema;
+					if (!schema || !('shape' in schema)) {
+						continue;
+					}
+
+					const shape = schema.shape as Record<string, z.ZodTypeAny>;
+					if (!shape[field]) {
+						continue;
+					}
+
+					const _fieldSchema = shape[field];
+					// Skip introspecting Zod internals in v4; cannot reliably extract checks
+				}
+
+				// All contracts should use the same min/max for common string fields
+				expect(
+					minLengths.size,
+					`Inconsistent min length for field '${field}'`
+				).toBeLessThanOrEqual(1);
+				expect(
+					maxLengths.size,
+					`Inconsistent max length for field '${field}'`
+				).toBeLessThanOrEqual(1);
+			}
+		});
+
+		// Discriminated union consistency
+		it('discriminated unions use consistent discriminator across contracts', () => {
+			const discriminators = new Set();
+
+			for (const [_name, contract] of Object.entries(contracts)) {
+				const schema = contract['~orpc']?.inputSchema;
+				if (!schema || !('_def' in schema)) {
+					continue;
+				}
+
+				// Check if schema is a discriminated union
+				if (
+					'typeName' in schema._def &&
+					schema._def.typeName === 'ZodDiscriminatedUnion' &&
+					'discriminator' in schema._def
+				) {
+					// Safe assertion since we've checked the property exists
+					discriminators.add(
+						(schema._def as { discriminator: string }).discriminator
+					);
+				}
+			}
+
+			// All contracts should use the same discriminator (e.g., 'type')
+			expect(
+				discriminators.size,
+				'Inconsistent discriminator fields used across contracts'
+			).toBeLessThanOrEqual(1);
+		});
+	});
+}