@c15t/backend 1.0.0 → 1.1.0-canary.0

package/src/testing/contract-testing.ts

@@ -0,0 +1,437 @@
+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 ContractTestHelpers = {
+	validateInput?: (
+		input: unknown
+	) => z.SafeParseReturnType<unknown, unknown> | undefined;
+	validateOutput: (
+		output: unknown
+	) => z.SafeParseReturnType<unknown, unknown> | 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) => {
+		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 z.SafeParseReturnType<
+			unknown,
+			unknown
+		>;
+	};
+
+	const validateOutput = (output: unknown) => {
+		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 z.SafeParseReturnType<
+			unknown,
+			unknown
+		>;
+	};
+
+	// 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(`uses '${discriminator}' as discriminator`, () => {
+				if (!schemas.input) {
+					return;
+				}
+				// Only check Zod schemas for discriminated unions
+				if ('_def' in schemas.input) {
+					const schema = schemas.input as z.ZodDiscriminatedUnion<
+						string,
+						z.ZodObject<z.ZodRawShape>[]
+					>;
+					expect(schema._def.typeName).toBe('ZodDiscriminatedUnion');
+					expect(schema._def.discriminator).toBe(discriminator);
+				}
+			});
+
+			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);
+					if (!result?.success) {
+						expect(
+							result?.error.issues.some(
+								(issue) => issue.code === 'invalid_type'
+							)
+						).toBe(true);
+					}
+				}
+			});
+		});
+	};
+
+	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];
+					if (
+						'_def' in fieldSchema &&
+						fieldSchema._def.typeName === 'ZodString'
+					) {
+						// Extract min/max length if they exist
+						const checks = fieldSchema._def.checks || [];
+						for (const check of checks) {
+							if (check.kind === 'min') {
+								minLengths.add(check.value);
+							}
+							if (check.kind === 'max') {
+								maxLengths.add(check.value);
+							}
+						}
+					}
+				}
+
+				// 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);
+		});
+	});
+}

package/src/types/context.ts

@@ -2,7 +2,7 @@ import type { DoubleTieContext } from '~/pkgs/types/context';
 import type { C15TPlugin, InferPluginContexts } from './plugins';
 
 /**
- * Complete C15T context type for consent management
+ * Complete c15t context type for consent management
  *
  * This type combines the base consent context with plugin-specific context extensions.
  * It's the primary context type used throughout the consent management system.

package/src/types/index.ts

@@ -1,7 +1,7 @@
 /**
- * C15T Types Package
+ * c15t Types Package
  *
- * This package provides type definitions specific to the C15T consent management system.
+ * This package provides type definitions specific to the c15t consent management system.
  * It extends the base DoubleTie framework types with consent management specific functionality.
  *
  * The types in this folder should be used for consent management specific features, while

package/src/types/options.ts

@@ -1,3 +1,4 @@
+import type { OpenAPIGeneratorOptions } from '@orpc/openapi';
 /**
  * c15t Consent Management System Configuration Types
  *
@@ -8,7 +9,7 @@
 import type { DoubleTieOptions } from '~/pkgs/types/options';
 import type { C15TPlugin } from './plugins';
 
-import type { LoggerOptions } from '~/pkgs/logger';
+import type { LoggerOptions } from '@doubletie/logger';
 // Import table configuration types from the schema module
 import type { TablesConfig } from '~/schema/types';
 /**
@@ -24,7 +25,6 @@ import type { TablesConfig } from '~/schema/types';
  * // Basic consent management configuration
  * const options: C15TOptions = {
  *   appName: "My Consent App",
- *   secret: process.env.SECRET_KEY,
  *   baseURL: "https://example.com",
  *   trustedOrigins: ["https://example.com"]
  * };
@@ -53,7 +53,7 @@ export interface C15TOptions<PluginType extends C15TPlugin[] = C15TPlugin[]>
 	secret?: string;
 
 	/**
-	 * Plugins specific to C15T
+	 * Plugins specific to c15t
 	 */
 	plugins?: PluginType;
 
@@ -66,4 +66,39 @@ export interface C15TOptions<PluginType extends C15TPlugin[] = C15TPlugin[]>
 	 * Logger configuration
 	 */
 	logger?: LoggerOptions;
+
+	/**
+	 * OpenAPI configuration options
+	 */
+	openapi?: {
+		/**
+		 * Enable/disable OpenAPI spec generation
+		 * @default true
+		 */
+		enabled?: boolean;
+
+		/**
+		 * Path to serve the OpenAPI JSON spec
+		 * @default "/spec.json"
+		 */
+		specPath?: string;
+
+		/**
+		 * Path to serve the API documentation UI
+		 * @default "/docs"
+		 */
+		docsPath?: string;
+
+		/**
+		 * OpenAPI specification options
+		 * These are passed to the OpenAPIGenerator.generate() method
+		 */
+		options?: Partial<OpenAPIGeneratorOptions>;
+
+		/**
+		 * Custom template for rendering the API documentation UI
+		 * If provided, this will be used instead of the default Scalar UI
+		 */
+		customUiTemplate?: string;
+	};
 }

package/src/types/plugins.ts

@@ -1,4 +1,3 @@
-import type { H3Event } from 'h3';
 import type { Migration } from 'kysely';
 import type { DoubleTieContext, DoubleTieOptions } from '~/pkgs/types';
 import type { Endpoint, EndpointMiddleware } from '~/pkgs/types/endpoints';
@@ -60,12 +59,12 @@ export interface DoubleTiePlugin {
 	/**
 	 * Handler for intercepting and potentially modifying incoming requests
 	 */
-	onRequest?: (event: H3Event, ctx: DoubleTieContext) => Promise<unknown>;
+	onRequest?: (request: Request, ctx: DoubleTieContext) => Promise<unknown>;
 
 	/**
 	 * Handler for intercepting and potentially modifying outgoing responses
 	 */
-	onResponse?: (event: H3Event, ctx: DoubleTieContext) => Promise<unknown>;
+	onResponse?: (response: Response, ctx: DoubleTieContext) => Promise<unknown>;
 
 	/**
 	 * Schema the plugin needs
@@ -138,7 +137,7 @@ export interface C15TPlugin extends Omit<DoubleTiePlugin, 'endpoints'> {
 	/**
 	 * Handler for intercepting and potentially modifying outgoing responses
 	 */
-	onResponse?: (event: H3Event, ctx: C15TContext) => Promise<unknown>;
+	onResponse?: (response: Response, ctx: C15TContext) => Promise<unknown>;
 
 	/**
 	 * Schema the plugin needs for consent data