@c15t/backend 1.8.0 → 2.0.0-rc.1

package/src/schema/consent-purpose/registry.ts

@@ -1,168 +0,0 @@
-import { getWithHooks } from '~/pkgs/data-model';
-import { DoubleTieError, ERROR_CODES } from '~/pkgs/results';
-import type { GenericEndpointContext, RegistryContext } from '~/pkgs/types';
-
-import { validateEntityOutput } from '../definition';
-import type { ConsentPurpose } from './schema';
-
-/**
- * Creates and returns a set of consent purpose adapter methods to interact with the database.
- * These methods provide a consistent interface for creating and finding
- * consent purpose records while applying hooks and enforcing data validation rules.
- *
- * The consent purpose registry manages purpose definitions that describe specific
- * data processing activities for which consent may be given. Each purpose has a unique
- * code, name, description, and essential status flag indicating whether it's required
- * for core system functionality.
- *
- * @param params - Registry context parameters
- * @param params.adapter - The database adapter used for direct database operations
- * @param params.ctx - Additional context properties containing hooks and options
- * @returns An object containing type-safe consent purpose operations
- *
- * @example
- * ```ts
- * const registry = consentPurposeRegistry({
- *   adapter: databaseAdapter,
- *   hooks: customHooks,
- *   options: validationOptions
- * });
- *
- * // Create a marketing purpose
- * const marketingPurpose = await registry.createConsentPurpose({
- *   code: 'marketing',
- *   name: 'Marketing Communications',
- *   description: 'Allow us to send you promotional materials and offers',
- *   isEssential: false
- * });
- * ```
- *
- * @see {@link RegistryContext} For details on the context parameters
- * @see {@link ConsentPurpose} For the structure of consent purpose objects
- */
-export function consentPurposeRegistry({ adapter, ...ctx }: RegistryContext) {
-	const { createWithHooks } = getWithHooks(adapter, ctx);
-	return {
-		/**
-		 * Creates a new consent purpose record in the database.
-		 *
-		 * This method creates a purpose definition that subjects can consent to.
-		 * Purposes represent specific data processing activities (such as marketing,
-		 * analytics, or personalization) that require user consent. The method
-		 * automatically sets creation and update timestamps and applies any
-		 * configured hooks during the creation process.
-		 *
-		 * @param consentPurpose - ConsentPurpose data to create (without id and timestamps)
-		 * @param consentPurpose.code - Unique code identifying the purpose (e.g., 'marketing')
-		 * @param consentPurpose.name - Human-readable name for the purpose
-		 * @param consentPurpose.description - Detailed explanation of what the purpose entails
-		 * @param consentPurpose.isEssential - Whether this purpose is required for core functionality
-		 * @param context - Optional endpoint context for hooks execution
-		 * @returns Promise resolving to the created purpose with all fields populated
-		 * @throws {Error} When the creation operation fails or returns null
-		 * @throws May also throw errors if hooks prevent creation or if validation fails
-		 *
-		 * @example
-		 * ```ts
-		 * // Create an analytics purpose
-		 * const analyticsPurpose = await registry.createConsentPurpose({
-		 *   code: 'analytics',
-		 *   name: 'Usage Analytics',
-		 *   description: 'Collect anonymous usage data to improve our services',
-		 *   isEssential: false,
-		 *   metadata: {
-		 *     category: 'Tracking',
-		 *     dataRetention: '90 days'
-		 *   }
-		 * });
-		 *
-		 * // Create an essential purpose
-		 * const essentialPurpose = await registry.createConsentPurpose({
-		 *   code: 'security',
-		 *   name: 'Security & Fraud Prevention',
-		 *   description: 'Process data necessary to protect against unauthorized access',
-		 *   isEssential: true,
-		 *   metadata: {
-		 *     category: 'Core',
-		 *     legalBasis: 'legitimate interest'
-		 *   }
-		 * });
-		 * ```
-		 *
-		 * @see {@link ConsentPurpose} For the complete structure of consent purpose objects
-		 * @see {@link GenericEndpointContext} For details on the context object
-		 */
-		createConsentPurpose: async (
-			consentPurpose: Omit<ConsentPurpose, 'id' | 'createdAt' | 'updatedAt'> &
-				Partial<ConsentPurpose>,
-			context?: GenericEndpointContext
-		) => {
-			const createdPurpose = await createWithHooks({
-				data: {
-					id: consentPurpose.id || '',
-					createdAt: new Date(),
-					updatedAt: new Date(),
-					...consentPurpose,
-				},
-				model: 'consentPurpose',
-				context,
-			});
-
-			if (!createdPurpose) {
-				throw new DoubleTieError(
-					'Failed to create consent purpose - operation returned null',
-					{
-						code: ERROR_CODES.INTERNAL_SERVER_ERROR,
-						status: 500,
-					}
-				);
-			}
-
-			return validateEntityOutput(
-				'consentPurpose',
-				createdPurpose,
-				ctx.options
-			);
-		},
-
-		/**
-		 * Finds a consent purpose by its unique code.
-		 *
-		 * This method retrieves a single consent purpose that matches the provided code.
-		 * The code serves as a unique identifier for purposes across the system.
-		 * The resulting purpose is validated against the schema before being returned.
-		 *
-		 * @param code - The unique code of the purpose to find
-		 * @returns Promise resolving to the validated purpose object if found, null otherwise
-		 *
-		 * @example
-		 * ```ts
-		 * // Find the marketing purpose
-		 * const marketingPurpose = await registry.findConsentPurposeByCode('marketing');
-		 * if (marketingPurpose) {
-		 *   console.log(`Found purpose: ${marketingPurpose.name}`);
-		 *   console.log(`Description: ${marketingPurpose.description}`);
-		 *   console.log(`Essential: ${marketingPurpose.isEssential ? 'Yes' : 'No'}`);
-		 * } else {
-		 *   console.log('Purpose not found');
-		 * }
-		 * ```
-		 *
-		 * @see {@link ConsentPurpose} For the structure of the returned purpose object
-		 */
-		findConsentPurposeByCode: async (code: string) => {
-			const consentPurpose = await adapter.findOne({
-				model: 'consentPurpose',
-				where: [
-					{
-						field: 'code',
-						value: code,
-					},
-				],
-			});
-			return consentPurpose
-				? validateEntityOutput('consentPurpose', consentPurpose, ctx.options)
-				: null;
-		},
-	};
-}

package/src/schema/consent-purpose/schema.ts

@@ -1,58 +0,0 @@
-import { z } from 'zod';
-
-/**
- * Zod schema for validating consent consentPurpose entities.
- *
- * This defines the structure and validation rules for consent consentPurpose records:
- * - Required fields: code, name, description
- * - Default value of false for isEssential
- * - Default value of true for isActive
- * - Optional fields for dataCategory and legalBasis
- * - Default current date/time for creation and update timestamps
- *
- * @example
- * ```typescript
- * const purposeData = {
- *   id: 'pur_e8zyhgozr3im7xj59it',
- *   code: 'marketing',
- *   name: 'Marketing Communications',
- *   description: 'Allow us to send you marketing materials',
- *   isEssential: false
- * };
- *
- * // Validate and parse the consentPurpose data
- * const validPurpose = purposeSchema.parse(purposeData);
- *
- * // Example with missing fields (defaults will be applied)
- * const minimalPurposeData = {
- *   id: 'pur_e8zyhgozr3im7xj59it',
- *   code: 'marketing',
- *   name: 'Marketing Communications',
- *   description: 'Allow us to send you marketing materials',
- * };
- *
- * // isEssential will default to false, isActive to true, etc.
- * const purposeWithDefaults = purposeSchema.parse(minimalPurposeData);
- * ```
- */
-export const purposeSchema = z.object({
-	id: z.string(),
-	code: z.string(),
-	name: z.string(),
-	description: z.string(),
-	isEssential: z.boolean().prefault(false),
-	dataCategory: z.string().nullish(),
-	legalBasis: z.string().nullish(),
-	isActive: z.boolean().prefault(true),
-	createdAt: z.date().prefault(() => new Date()),
-	updatedAt: z.date().prefault(() => new Date()),
-});
-
-/**
- * Type definition for ConsentPurpose
- *
- * This type represents the structure of a consent consentPurpose record
- * as defined by the purposeSchema. It includes all fields
- * that are part of the consent consentPurpose entity.
- */
-export type ConsentPurpose = z.infer<typeof purposeSchema>;

package/src/schema/consent-purpose/table.ts

@@ -1,154 +0,0 @@
-import type { Field } from '~/pkgs/data-model';
-import type { C15TOptions } from '~/types';
-import { purposeSchema } from './schema';
-
-/**
- * Generates the database table configuration for the consent consentPurpose entity.
- *
- * This function creates a schema definition that includes all standard consent consentPurpose 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 consentPurpose table customizations
- * @param purposeFields - Additional fields from plugins to include in the consentPurpose table
- * @returns A complete table schema definition with fields, model name, and metadata
- *
- * @example
- * ```typescript
- * const purposeTableSchema = getPurposeTable(c15tOptions);
- * // Use the schema for migrations or data access
- * const migrationPlans = generateMigrations(purposeTableSchema);
- * ```
- */
-export function getPurposeTable(
-	options: C15TOptions,
-	purposeFields?: Record<string, Field>
-) {
-	const purposeConfig = options.tables?.consentPurpose;
-
-	return {
-		/**
-		 * The name of the consentPurpose table in the database, configurable through options
-		 */
-		entityName: purposeConfig?.entityName || 'consentPurpose',
-
-		/**
-		 * The ID prefix for the consentPurpose table
-		 * Used to generate unique prefixed IDs for purposes
-		 */
-		entityPrefix: purposeConfig?.entityPrefix || 'pur',
-
-		/**
-		 * The schema for the consentPurpose table
-		 */
-		schema: purposeSchema,
-
-		/**
-		 * Field definitions for the consent consentPurpose table
-		 */
-		fields: {
-			/**
-			 * Unique code for the consentPurpose, used for programmatic identification
-			 */
-			code: {
-				type: 'string',
-				required: true,
-				fieldName: purposeConfig?.fields?.code || 'code',
-			},
-
-			/**
-			 * Human-readable name of the consentPurpose
-			 */
-			name: {
-				type: 'string',
-				required: true,
-				fieldName: purposeConfig?.fields?.name || 'name',
-			},
-
-			/**
-			 * Detailed description of the consentPurpose, shown to subjects
-			 */
-			description: {
-				type: 'string',
-				required: true,
-				fieldName: purposeConfig?.fields?.description || 'description',
-			},
-
-			/**
-			 * Whether this is an essential consentPurpose that doesn't require explicit consent
-			 * Default: false
-			 */
-			isEssential: {
-				type: 'boolean',
-				defaultValue: () => false,
-				required: true,
-				fieldName: purposeConfig?.fields?.isEssential || 'isEssential',
-			},
-
-			/**
-			 * Category of data this consentPurpose processes (e.g., 'personal', 'profile')
-			 * Optional field
-			 */
-			dataCategory: {
-				type: 'string',
-				required: false,
-				fieldName: purposeConfig?.fields?.dataCategory || 'dataCategory',
-			},
-
-			/**
-			 * Legal basis for data processing (e.g., 'consent', 'legitimate interest')
-			 * Optional field
-			 */
-			legalBasis: {
-				type: 'string',
-				required: false,
-				fieldName: purposeConfig?.fields?.legalBasis || 'legalBasis',
-			},
-
-			/**
-			 * Whether this consentPurpose is currently active
-			 * Default: true
-			 */
-			isActive: {
-				type: 'boolean',
-				defaultValue: true,
-				required: true,
-				fieldName: purposeConfig?.fields?.isActive || 'isActive',
-			},
-
-			/**
-			 * When the consentPurpose record was created
-			 * Automatically set to current time by default
-			 */
-			createdAt: {
-				type: 'date',
-				defaultValue: () => new Date(),
-				required: true,
-				fieldName: purposeConfig?.fields?.createdAt || 'createdAt',
-			},
-
-			/**
-			 * When the consentPurpose record was last updated
-			 * Automatically updated on each modification
-			 */
-			updatedAt: {
-				type: 'date',
-				defaultValue: () => new Date(),
-				required: true,
-				fieldName: purposeConfig?.fields?.updatedAt || 'updatedAt',
-			},
-
-			// Include additional fields from plugins
-			...(purposeFields || {}),
-
-			// Include additional fields from configuration
-			...(purposeConfig?.additionalFields || {}),
-		},
-
-		/**
-		 * Execution order during migrations (lower numbers run first)
-		 * ConsentPurpose table needs to be created relatively early as other tables reference it
-		 */
-		order: 1,
-	};
-}

package/src/schema/consent-purpose/types.ts

@@ -1,16 +0,0 @@
-import type { ActiveEntityConfig } from '../types';
-
-/**
- * ConsentPurpose entity configuration
- * @default entityName: "consentPurpose", entityPrefix: "pur"
- */
-export interface ConsentPurposeEntityConfig extends ActiveEntityConfig {
-	fields?: Record<string, string> & {
-		id?: string;
-		name?: string;
-		description?: string;
-		isActive?: string;
-		createdAt?: string;
-		updatedAt?: string;
-	};
-}

package/src/schema/consent-record/index.ts

@@ -1,2 +0,0 @@
-export * from './schema';
-export * from './table';

package/src/schema/consent-record/schema.ts

@@ -1,42 +0,0 @@
-import { z } from 'zod';
-
-/**
- * Zod schema for validating consent record entities.
- *
- * This defines the structure and validation rules for consent records:
- * - Required fields: subjectId, actionType (given, withdrawn, updated, etc.)
- * - Optional fields: consentId, details
- * - Default current date/time for creation and update timestamps
- *
- * @example
- * ```typescript
- * const recordData = {
- *   id: 'rec_w5qufx2a66m7xkn3ty',
- *   subjectId: 'sub_x1pftyoufsm7xgo1kv',
- *   consentId: 'cns_hadt8w7nngm7xmx2bn',
- *   actionType: 'given',
- *   details: { ip: '192.168.1.1', userAgent: 'Mozilla/5.0...' }
- * };
- *
- * // Validate and parse the record data
- * const validRecord = consentRecordSchema.parse(recordData);
- * ```
- */
-export const consentRecordSchema = z.object({
-	id: z.string(),
-	subjectId: z.string(),
-	consentId: z.string().optional(),
-	actionType: z.string(),
-	details: z.record(z.string(), z.unknown()).optional(),
-	createdAt: z.date().prefault(() => new Date()),
-	updatedAt: z.date().prefault(() => new Date()),
-});
-
-/**
- * Type definition for Record
- *
- * This type represents the structure of a consent record
- * as defined by the consentRecordSchema. It includes all fields
- * that are part of the consent record entity.
- */
-export type ConsentRecord = z.infer<typeof consentRecordSchema>;

package/src/schema/consent-record/table.ts

@@ -1,124 +0,0 @@
-import type { Field } from '~/pkgs/data-model';
-import type { C15TOptions } from '~/types';
-import { consentRecordSchema } from './schema';
-
-/**
- * Generates the database table configuration for the consent record entity.
- *
- * This function creates a schema definition that includes all standard consent record 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 consent record table customizations
- * @param recordFields - Additional fields from plugins to include in the consent record table
- * @returns A complete table schema definition with fields, model name, and metadata
- *
- * @example
- * ```typescript
- * const recordTableSchema = getConsentRecordTable(c15tOptions);
- * // Use the schema for migrations or data access
- * const migrationPlans = generateMigrations(recordTableSchema);
- * ```
- */
-export function getConsentRecordTable(
-	options: C15TOptions,
-	recordFields?: Record<string, Field>
-) {
-	// Get record config, supporting both the new tables.record and legacy record format
-	const recordConfig = options.tables?.record;
-	const subjectConfig = options.tables?.subject;
-	const consentConfig = options.tables?.consent;
-
-	return {
-		/**
-		 * The name of the consent record table in the database, configurable through options
-		 */
-		entityName: recordConfig?.entityName || 'consentRecord',
-
-		/**
-		 * The ID prefix for the consent record table
-		 * Used to generate unique prefixed IDs for records
-		 */
-		entityPrefix: recordConfig?.entityPrefix || 'rec',
-
-		/**
-		 * The schema for the consent record table
-		 */
-		schema: consentRecordSchema,
-
-		/**
-		 * Field definitions for the consent record table
-		 */
-		fields: {
-			/**
-			 * Reference to the subject associated with this consent record
-			 */
-			subjectId: {
-				type: 'string',
-				required: true,
-				fieldName: recordConfig?.fields?.subjectId || 'subjectId',
-				references: {
-					model: subjectConfig?.entityName || 'subject',
-					field: 'id',
-				},
-			},
-
-			/**
-			 * Optional reference to the specific consent this record is about
-			 * May be null for general consent actions not related to a specific consent
-			 */
-			consentId: {
-				type: 'string',
-				required: false,
-				fieldName: recordConfig?.fields?.consentId || 'consentId',
-				references: {
-					model: consentConfig?.entityName || 'consent',
-					field: 'id',
-				},
-			},
-
-			/**
-			 * Type of consent action this record represents
-			 * Common values: 'given', 'withdrawn', 'updated', 'expired', 'requested'
-			 */
-			actionType: {
-				type: 'string',
-				required: true,
-				fieldName: recordConfig?.fields?.actionType || 'actionType',
-			},
-
-			/**
-			 * Additional details about the consent action
-			 * May include IP address, subject agent, reason for withdrawal, etc.
-			 */
-			details: {
-				type: 'json',
-				required: false,
-				fieldName: recordConfig?.fields?.details || 'details',
-			},
-
-			/**
-			 * When the consent record was created
-			 * Automatically set to current time by default
-			 */
-			createdAt: {
-				type: 'date',
-				defaultValue: () => new Date(),
-				required: true,
-				fieldName: recordConfig?.fields?.createdAt || 'createdAt',
-			},
-
-			// Include additional fields from plugins
-			...(recordFields || {}),
-
-			// Include additional fields from configuration
-			...(recordConfig?.additionalFields || {}),
-		},
-
-		/**
-		 * Execution order during migrations (lower numbers run first)
-		 * Consent record table needs to be created after the subject and consent tables it references
-		 */
-		order: 4,
-	};
-}

package/src/schema/consent-record/types.ts

@@ -1,21 +0,0 @@
-/**
- * Record Entity Type Definitions
- *
- * This module contains type definitions specific to the record entity.
- */
-import type { BaseEntityConfig } from '../types';
-
-/**
- * Record entity configuration
- * @default entityName: "record", entityPrefix: "rec"
- */
-export interface ConsentRecordEntityConfig extends BaseEntityConfig {
-	fields?: Record<string, string> & {
-		id?: string;
-		subjectId?: string;
-		consentId?: string;
-		actionType?: string;
-		details?: string;
-		createdAt?: string;
-	};
-}

package/src/schema/create-registry.ts

@@ -1,21 +0,0 @@
-import type { RegistryContext } from '~/pkgs/types';
-
-import {
-	auditLogRegistry,
-	consentPurposeRegistry,
-	consentRegistry,
-	domainRegistry,
-	policyRegistry,
-	subjectRegistry,
-} from './index';
-
-export const createRegistry = (ctx: RegistryContext) => {
-	return {
-		...auditLogRegistry(ctx),
-		...consentRegistry(ctx),
-		...domainRegistry(ctx),
-		...consentPurposeRegistry(ctx),
-		...policyRegistry(ctx),
-		...subjectRegistry(ctx),
-	};
-};