@c15t/backend 0.0.1-rc.10

package/src/db/schema/geo-location/table.ts

@@ -0,0 +1,148 @@
+import type { Field } from '~/db/core/fields';
+import type { C15TOptions } from '~/types';
+import { geoLocationSchema } from './schema';
+
+/**
+ * Generates the database table configuration for the geo-location entity.
+ *
+ * This function creates a schema definition that includes all standard geo-location fields
+ * and any additional fields from plugins or configuration. The resulting schema is used
+ * for database migrations, schema validation, and query building.
+ *
+ * @param options - C15T configuration options that may contain geo-location table customizations
+ * @param geoLocationFields - Additional fields from plugins to include in the geo-location table
+ * @returns A complete table schema definition with fields, model name, and metadata
+ *
+ * @example
+ * ```typescript
+ * const locationTableSchema = getGeoLocationTable(c15tOptions);
+ * // Use the schema for migrations or data access
+ * const migrationPlans = generateMigrations(locationTableSchema);
+ * ```
+ */
+export function getGeoLocationTable(
+	options: C15TOptions,
+	geoLocationFields?: Record<string, Field>
+) {
+	const geoLocationConfig = options.tables?.geoLocation;
+	return {
+		/**
+		 * The name of the geo-location table in the database, configurable through options
+		 */
+		entityName: geoLocationConfig?.entityName || 'geoLocation',
+
+		/**
+		 * The ID prefix for the geo-location table
+		 * Used to generate unique prefixed IDs for geo-locations
+		 */
+		entityPrefix: geoLocationConfig?.entityPrefix || 'geo',
+
+		/**
+		 * The schema for the geo-location table
+		 */
+		schema: geoLocationSchema,
+
+		/**
+		 * Field definitions for the geo-location table
+		 */
+		fields: {
+			/**
+			 * Country code (e.g., 'US', 'DE', 'FR')
+			 */
+			countryCode: {
+				type: 'string',
+				required: true,
+				fieldName: geoLocationConfig?.fields?.countryCode || 'countryCode',
+			},
+
+			/**
+			 * Full country name (e.g., 'United States', 'Germany', 'France')
+			 */
+			countryName: {
+				type: 'string',
+				required: true,
+				fieldName: geoLocationConfig?.fields?.countryName || 'countryName',
+			},
+
+			/**
+			 * Region or state code (e.g., 'CA', 'NY', 'BY')
+			 */
+			regionCode: {
+				type: 'string',
+				required: false,
+				fieldName: geoLocationConfig?.fields?.regionCode || 'regionCode',
+			},
+
+			/**
+			 * Full region or state name (e.g., 'California', 'New York', 'Bavaria')
+			 */
+			regionName: {
+				type: 'string',
+				required: false,
+				fieldName: geoLocationConfig?.fields?.regionName || 'regionName',
+			},
+
+			/**
+			 * Array of regulatory zones that apply to this location (e.g., 'GDPR', 'CCPA')
+			 * Stored as a JSON string in the database
+			 */
+			regulatoryZones: {
+				type: 'json',
+				required: false,
+				fieldName:
+					geoLocationConfig?.fields?.regulatoryZones || 'regulatoryZones',
+				transformer: {
+					input: (value: string[]) => JSON.stringify(value),
+					output: (value: string) => {
+						try {
+							return JSON.parse(value);
+						} catch {
+							return [];
+						}
+					},
+				},
+			},
+
+			/**
+			 * When the geo-location record was created
+			 * Automatically set to current time by default
+			 */
+			createdAt: {
+				type: 'date',
+				defaultValue: () => new Date(),
+				required: true,
+				fieldName: geoLocationConfig?.fields?.createdAt || 'createdAt',
+			},
+
+			// Include additional fields from plugins
+			...(geoLocationFields || {}),
+
+			// Include additional fields from configuration
+			...(geoLocationConfig?.additionalFields || {}),
+		},
+
+		/**
+		 * Add indexes for better query performance
+		 */
+		indexes: [
+			{
+				name: 'country_code_index',
+				fields: ['countryCode'],
+			},
+			{
+				name: 'region_code_index',
+				fields: ['regionCode'],
+			},
+			{
+				name: 'created_at_index',
+				fields: ['createdAt'],
+			},
+		],
+
+		/**
+		 * Execution order during migrations (lower numbers run first)
+		 * Geo-location is a base entity that doesn't depend on other tables
+		 */
+		order: 1,
+	};
+}

package/src/db/schema/geo-location/types.ts

@@ -0,0 +1,18 @@
+import type { BaseEntityConfig } from '../types';
+
+/**
+ * Geo location entity configuration
+ * @default entityName: "geoLocation", entityPrefix: "geo"
+ */
+export interface GeoLocationEntityConfig extends BaseEntityConfig {
+	fields?: Record<string, string> & {
+		id?: string;
+		countryCode?: string;
+		countryName?: string;
+		regionCode?: string;
+		regionName?: string;
+		// For comma-separated values
+		regulatoryZones?: string;
+		createdAt?: string;
+	};
+}

package/src/db/schema/index.ts

@@ -0,0 +1,96 @@
+/**
+ * Schema Module for c15t Consent Management System
+ *
+ * This module serves as the central hub for database schema definitions, validation,
+ * and transformation utilities used throughout the c15t system. It defines the structure
+ * of all database tables and provides tools to work with schema-compliant data.
+ *
+ * @remarks
+ * The Schema Module is organized into three main components:
+ *
+ * 1. Table Definitions - Individual table schemas (subject, consent, consentPurpose, etc.)
+ * 2. Schema Utilities - Functions for retrieving and working with the complete schema
+ * 3. Data Parsing - Validation and transformation of input/output data
+ *
+ * These components work together to provide a type-safe, consistent interface for
+ * interacting with the database, regardless of which database adapter is used.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   getConsentTables,
+ *   parseInputData,
+ *   type C15TDBSchema
+ * } from '@c15t/core/db/schema';
+ *
+ * // Get the complete schema
+ * const tables = getConsentTables(options);
+ *
+ * // Validate input data against the subject table schema
+ * const validSubjectData = parseInputData(
+ *   inputData,
+ *   { fields: tables.subject.fields }
+ * );
+ * ```
+ */
+
+// Table Definition Exports
+/**
+ * Table definitions for core c15t entities
+ *
+ * These exports provide the schema definitions for each table in the c15t database.
+ * Each table definition includes field specifications, relationships, and metadata.
+ */
+export * from './audit-log';
+export * from './consent-geo-location';
+export * from './consent-policy';
+export * from './consent-purpose-junction';
+export * from './consent-purpose';
+export * from './consent-record';
+export * from './consent-withdrawal';
+export * from './consent';
+export * from './domain';
+export * from './geo-location';
+export * from './subject';
+
+// Schema Type Exports
+/**
+ * Type definitions for database schema configuration
+ *
+ * These exports provide interfaces for configuring database entities
+ * and are used throughout the application for type-safe schema definition.
+ *
+ * @see {@link BaseEntityConfig} - Base configuration for all entities
+ * @see {@link TablesConfig} - Configuration for all database tables
+ */
+export * from './types';
+
+// Schema Utility Exports
+/**
+ * Schema utilities for working with the complete database schema
+ *
+ * These exports provide functions for retrieving the complete schema and
+ * working with table definitions at a higher level.
+ *
+ * @see {@link getConsentTables} - Main function to get the complete schema
+ * @see {@link C15TDBSchema} - Type representing the complete database schema
+ */
+export { getConsentTables, type C15TDBSchema } from './definition';
+
+// Data Parsing Exports
+/**
+ * Data parsing and validation utilities
+ *
+ * These exports provide functions for validating and transforming data
+ * according to the schema definitions. They ensure type safety and data integrity
+ * when working with database records.
+ *
+ * @see {@link parseInputData} - Validates input data against a table schema
+ * @see {@link parseEntityOutputData} - Validates output data against a table schema
+ * @see {@link getAllFields} - Retrieves all fields from a schema
+ */
+export {
+	parseInputData,
+	parseEntityOutputData,
+	getAllFields,
+} from './parser';

package/src/db/schema/parser.ts

@@ -0,0 +1,417 @@
+import { BASE_ERROR_CODES, C15TError } from '~/error';
+import type { C15TOptions, C15TPluginSchema } from '~/types';
+import type { Field } from '../core/fields';
+
+/**
+ * Parses and transforms output data according to schema field definitions.
+ *
+ * This function filters and processes entity data being returned from the database,
+ * ensuring that only fields marked as returnable are included in the output.
+ *
+ * @typeParam EntityType - The type of entity being processed
+ *
+ * @param data - The raw data object retrieved from the database
+ * @param schema - The schema containing field definitions
+ * @param schema.fields - Record of field definitions for the entity
+ *
+ * @returns The processed data object with appropriate fields included or excluded
+ *
+ * @example
+ * ```typescript
+ * // Get subject data from database
+ * const subjectData = { id: 'sub_x1pftyoufsm7xgo1kv', };
+ *
+ * // Define schema with password field marked as not returnable
+ * const subjectSchema = {
+ *   fields: {
+ *     id: { name: 'id', type: 'string', returned: true },
+ *   }
+ * };
+ *
+ * // Process the data - password will be excluded
+ * const processedData = parseEntityOutputData(subjectData, subjectSchema);
+ * // Result: { id: 'sub_x1pftyoufsm7xgo1kv',}
+ * ```
+ *
+ * @remarks
+ * - Fields marked with `returned: false` will be excluded from the output
+ * - Fields not found in the schema will be passed through unchanged
+ * - The function preserves the original type of the input data
+ */
+export function parseEntityOutputData<
+	EntityType extends Record<string, unknown>,
+>(
+	data: EntityType,
+	schema: {
+		fields: Record<string, Field>;
+	}
+) {
+	const fields = schema.fields;
+	const parsedData: Record<string, unknown> = {};
+
+	for (const key in data) {
+		if (Object.hasOwn(data, key)) {
+			const field = fields[key];
+			if (!field) {
+				parsedData[key] = data[key];
+				continue;
+			}
+			if (field.returned === false) {
+				continue;
+			}
+			parsedData[key] = data[key];
+		}
+	}
+	return parsedData as EntityType;
+}
+
+/**
+ * Type representing a field conflict resolution strategy
+ */
+export type FieldConflictResolution = {
+	/**
+	 * How to handle conflicting field definitions
+	 * - 'error': Throw an error when conflicts are detected
+	 * - 'warn': Log a warning and use the last definition
+	 * - 'silent': Silently use the last definition
+	 */
+	strategy: 'error' | 'warn' | 'silent';
+
+	/**
+	 * Optional callback for logging warnings
+	 * Only used when strategy is 'warn'
+	 */
+	onWarning?: (message: string) => void;
+};
+
+/**
+ * Retrieves all fields for a specific table, combining base configuration and plugin fields
+ *
+ * @param options - The C15T configuration options
+ * @param table - The table name to get fields for
+ * @param conflictResolution - How to handle conflicting field definitions
+ * @returns Combined fields from configuration and plugins
+ *
+ * @throws {C15TError} When field conflicts are detected and strategy is 'error'
+ *
+ * @example
+ * ```typescript
+ * // Get fields with conflict resolution
+ * const fields = getAllFields(options, 'subject', {
+ *   strategy: 'warn',
+ *   onWarning: (msg) => console.warn(msg)
+ * });
+ * ```
+ */
+export function getAllFields(
+	options: C15TOptions,
+	table: string,
+	conflictResolution: FieldConflictResolution = { strategy: 'error' }
+) {
+	const schema: Record<string, Field> = {};
+	const fieldOrigins = new Map<string, string[]>();
+
+	// Helper to track field origins and handle conflicts
+	const addFields = (fields: Record<string, Field>, source: string) => {
+		for (const [key, field] of Object.entries(fields)) {
+			if (schema[key]) {
+				const origins = fieldOrigins.get(key) || [];
+				origins.push(source);
+				fieldOrigins.set(key, origins);
+
+				// Handle conflict based on strategy
+				if (conflictResolution.strategy === 'error') {
+					throw new C15TError(
+						'A field conflict was detected in the schema. Multiple definitions exist for the same field.',
+						{
+							code: BASE_ERROR_CODES.CONFLICT,
+							status: 500,
+							data: {
+								field: key,
+								table,
+								definedIn: origins.join(', '),
+							},
+						}
+					);
+				}
+				if (
+					conflictResolution.strategy === 'warn' &&
+					conflictResolution.onWarning
+				) {
+					conflictResolution.onWarning(
+						`Field conflict detected for '${key}' in table '${table}'. Using last definition from ${source}.`
+					);
+				}
+			}
+			schema[key] = field;
+		}
+	};
+
+	// Get additional fields from the tables configuration if available
+	if (options.tables && table in options.tables) {
+		const tableConfig = options.tables[table as keyof typeof options.tables];
+		if (tableConfig?.additionalFields) {
+			addFields(tableConfig.additionalFields, 'table configuration');
+		}
+	}
+
+	// Add fields from plugins
+	for (const plugin of options.plugins || []) {
+		const pluginSchema = plugin.schema as C15TPluginSchema | undefined;
+		if (pluginSchema?.[table]) {
+			addFields(
+				pluginSchema[table].fields,
+				`plugin: ${plugin.name || 'unnamed'}`
+			);
+		}
+	}
+
+	return schema;
+}
+
+/**
+ * Configuration for handling extra fields in input data
+ */
+export type ExtraFieldsConfig = {
+	/**
+	 * How to handle fields not defined in the schema
+	 * - 'error': Throw an error when extra fields are detected
+	 * - 'warn': Log a warning and include the fields
+	 * - 'silent': Silently include the fields
+	 * - 'drop': Silently drop the fields
+	 */
+	strategy: 'error' | 'warn' | 'silent' | 'drop';
+
+	/**
+	 * Optional callback for logging warnings
+	 * Only used when strategy is 'warn'
+	 */
+	onWarning?: (message: string) => void;
+
+	/**
+	 * Optional list of field names that are always allowed
+	 * regardless of schema definition
+	 */
+	allowedExtraFields?: string[];
+};
+
+/**
+ * Parses and validates input data according to schema field definitions.
+ *
+ * This function processes data being sent to the database, ensuring it meets
+ * schema requirements by:
+ * - Validating required fields
+ * - Applying transformations
+ * - Setting default values
+ * - Handling field-specific validation
+ *
+ * @typeParam EntityType - The type of entity being processed
+ *
+ * @param data - The input data to validate and transform
+ * @param schema - The schema to validate against
+ * @param schema.fields - Record of field definitions
+ * @param schema.action - The current operation ('create' or 'update')
+ * @param extraFieldsConfig - How to handle fields not defined in the schema
+ *
+ * @returns The validated and transformed data
+ *
+ * @throws {C15TError} When a required field is missing during creation
+ * @throws {C15TError} When extra fields are detected and strategy is 'error'
+ *
+ * @example
+ * ```typescript
+ * // Input data from client
+ * const inputData = {
+ *   email: 'subject@example.com',
+ *   role: 'subject',
+ *   extraField: 'value' // Field not in schema
+ * };
+ *
+ * // Schema with field definitions
+ * const subjectSchema = {
+ *   fields: {
+ *     id: {
+ *       name: 'id',
+ *       type: 'string',
+ *       defaultValue: () => crypto.randomUUID()
+ *     },
+ *     email: {
+ *       name: 'email',
+ *       type: 'string',
+ *       required: true,
+ *       transform: {
+ *         input: (value) => value.toLowerCase()
+ *       }
+ *     },
+ *     role: {
+ *       name: 'role',
+ *       type: 'string',
+ *       defaultValue: 'subject'
+ *     },
+ *     createdAt: {
+ *       name: 'created_at',
+ *       type: 'date',
+ *       defaultValue: () => new Date(),
+ *       input: false
+ *     }
+ *   },
+ *   action: 'create'
+ * };
+ *
+ * // Process the data with extra fields config
+ * const validatedData = parseInputData(inputData, subjectSchema, {
+ *   strategy: 'warn',
+ *   onWarning: (msg) => console.warn(msg),
+ *   allowedExtraFields: ['metadata']
+ * });
+ * ```
+ *
+ * @remarks
+ * - During 'create' operations, required fields must be present or an error is thrown
+ * - Default values are only applied during 'create' operations
+ * - Fields marked with `input: false` are excluded unless they have a default value
+ * - The function handles both modern transform functions and legacy validators
+ */
+export function parseInputData<EntityType extends Record<string, unknown>>(
+	data: EntityType,
+	schema: {
+		fields: Record<string, Field>;
+		action?: 'create' | 'update';
+	},
+	extraFieldsConfig: ExtraFieldsConfig = { strategy: 'error' }
+) {
+	const action = schema.action || 'create';
+	const fields = schema.fields;
+	const parsedData: Record<string, unknown> = {};
+
+	// Track extra fields for potential errors/warnings
+	const extraFields = new Set<string>();
+
+	// Process schema-defined fields
+	for (const key in fields) {
+		if (Object.hasOwn(fields, key)) {
+			if (key in data) {
+				if (fields[key]?.input === false) {
+					if (fields[key]?.defaultValue) {
+						parsedData[key] = fields[key]?.defaultValue;
+						continue;
+					}
+					continue;
+				}
+				// Check if validator exists and is an object with input property (old style)
+				function isLegacyValidator(
+					validator: unknown
+				): validator is { input?: { parse: (value: unknown) => unknown } } {
+					return (
+						typeof validator === 'object' &&
+						validator !== null &&
+						'input' in validator
+					);
+				}
+
+				if (
+					fields[key]?.validator &&
+					isLegacyValidator(fields[key]?.validator) &&
+					fields[key]?.validator.input &&
+					data[key] !== undefined
+				) {
+					parsedData[key] = fields[key]?.validator.input.parse(data[key]);
+					continue;
+				}
+				if (fields[key]?.transform?.input && data[key] !== undefined) {
+					const inputValue = data[key] as
+						| string
+						| number
+						| boolean
+						| Date
+						| string[]
+						| number[];
+					parsedData[key] = fields[key]?.transform?.input(inputValue);
+					continue;
+				}
+				parsedData[key] = data[key];
+				continue;
+			}
+
+			if (fields[key]?.defaultValue && action === 'create') {
+				parsedData[key] = fields[key]?.defaultValue;
+				continue;
+			}
+
+			if (fields[key]?.required && action === 'create') {
+				throw new C15TError('Missing required field', {
+					code: BASE_ERROR_CODES.BAD_REQUEST,
+					status: 400,
+					data: {
+						message: `${key} is required`,
+					},
+				});
+			}
+		}
+	}
+
+	// Handle extra fields
+	for (const key in data) {
+		if (Object.hasOwn(data, key) && !(key in fields)) {
+			extraFields.add(key);
+		}
+	}
+
+	// Process extra fields based on configuration
+	if (extraFields.size > 0) {
+		const allowedFields = new Set(extraFieldsConfig.allowedExtraFields || []);
+		const unallowedFields = Array.from(extraFields).filter(
+			(field) => !allowedFields.has(field)
+		);
+
+		if (unallowedFields.length > 0) {
+			switch (extraFieldsConfig.strategy) {
+				case 'error':
+					throw new C15TError('Unexpected fields found', {
+						code: BASE_ERROR_CODES.BAD_REQUEST,
+						status: 400,
+						data: {
+							message: `Unexpected fields found: ${unallowedFields.join(', ')}`,
+						},
+					});
+				case 'warn': {
+					if (extraFieldsConfig.onWarning) {
+						extraFieldsConfig.onWarning(
+							`Unexpected fields found: ${unallowedFields.join(', ')}`
+						);
+					}
+					// Include all extra fields
+					for (const key of extraFields) {
+						parsedData[key] = data[key];
+					}
+					break;
+				}
+				case 'silent':
+					// Include all extra fields
+					for (const key of extraFields) {
+						parsedData[key] = data[key];
+					}
+					break;
+				case 'drop':
+					// Fields are already dropped, no action needed
+					break;
+				default:
+					// Default to error strategy for type safety
+					throw new C15TError('Unexpected fields found', {
+						code: BASE_ERROR_CODES.BAD_REQUEST,
+						status: 400,
+						data: {
+							message: `Unexpected fields found: ${unallowedFields.join(', ')}`,
+						},
+					});
+			}
+		} else {
+			// Include allowed extra fields
+			for (const key of extraFields) {
+				parsedData[key] = data[key];
+			}
+		}
+	}
+
+	return parsedData as Partial<EntityType>;
+}

package/src/db/schema/schemas.ts

@@ -0,0 +1,35 @@
+import type { z } from 'zod';
+import {
+	auditLogSchema,
+	consentGeoLocationSchema,
+	consentPolicySchema,
+	consentPurposeJunctionSchema,
+	consentRecordSchema,
+	consentSchema,
+	consentWithdrawalSchema,
+	domainSchema,
+	geoLocationSchema,
+	purposeSchema,
+	subjectSchema,
+} from './index';
+
+// Export all schemas
+export const schemas = {
+	auditLog: auditLogSchema,
+	consent: consentSchema,
+	consentGeoLocation: consentGeoLocationSchema,
+	consentPolicy: consentPolicySchema,
+	consentPurpose: purposeSchema,
+	consentPurposeJunction: consentPurposeJunctionSchema,
+	consentRecord: consentRecordSchema,
+	consentWithdrawal: consentWithdrawalSchema,
+	domain: domainSchema,
+	geoLocation: geoLocationSchema,
+	subject: subjectSchema,
+} as const;
+
+// Type for all table names
+export type TableName = keyof typeof schemas;
+
+// Type for inferring the shape of any table
+export type InferTableShape<T extends TableName> = z.infer<(typeof schemas)[T]>;