@c15t/backend 0.0.1-rc.10

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

@@ -0,0 +1,188 @@
+import type { Where } from '~/db/adapters/types';
+import { getWithHooks } from '~/db/hooks';
+import type { GenericEndpointContext, RegistryContext } from '~/types';
+import { validateEntityOutput } from '../definition';
+import type { ConsentPurpose } from './schema';
+
+/**
+ * Creates and returns a set of consent consentPurpose-related adapter methods to interact with the database.
+ * These methods provide a consistent interface for creating, finding, and updating
+ * consent consentPurpose records while applying hooks and enforcing data validation rules.
+ *
+ * @param adapter - The database adapter used for direct database operations
+ * @param ctx - The context object containing the database adapter, hooks, and options
+ * @returns An object containing type-safe consent consentPurpose operations
+ *
+ * @example
+ * ```typescript
+ * const purposeAdapter = createConsentPurposeAdapter(
+ *   databaseAdapter,
+ *   createWithHooks,
+ *   updateWithHooks,
+ *   c15tOptions
+ * );
+ *
+ * // Create a new consent consentPurpose
+ * const consentPurpose = await purposeAdapter.createConsentPurpose({
+ *   code: 'pur_e8zyhgozr3im7xj59it',
+ *   name: 'Marketing Communications',
+ *   description: 'Allow us to send you marketing materials',
+ *   isEssential: false
+ * });
+ * ```
+ */
+export function consentPurposeRegistry({ adapter, ...ctx }: RegistryContext) {
+	const { createWithHooks, updateWithHooks } = getWithHooks(adapter, ctx);
+	return {
+		/**
+		 * Creates a new consent consentPurpose record in the database.
+		 * 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 context - Optional endpoint context for hooks
+		 * @returns The created consentPurpose with all fields populated
+		 * @throws May throw an error if hooks prevent creation or if database operations fail
+		 */
+		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 Error(
+					'Failed to create consent consentPurpose - operation returned null'
+				);
+			}
+
+			return validateEntityOutput(
+				'consentPurpose',
+				createdPurpose,
+				ctx.options
+			);
+		},
+
+		/**
+		 * Finds all consent purposes, optionally including inactive ones.
+		 * Returns purposes with processed output fields according to the schema configuration.
+		 *
+		 * @param includeInactive - Whether to include inactive purposes (default: false)
+		 * @returns Array of consent purposes matching the criteria
+		 */
+		findConsentPurposes: async (includeInactive?: boolean) => {
+			const whereConditions: Where<'consentPurpose'> = [];
+
+			if (!includeInactive) {
+				whereConditions.push({
+					field: 'isActive',
+					value: true,
+				});
+			}
+
+			const purposes = await adapter.findMany({
+				model: 'consentPurpose',
+				where: whereConditions,
+				sortBy: {
+					field: 'createdAt',
+					direction: 'asc',
+				},
+			});
+
+			return purposes.map((consentPurpose) =>
+				validateEntityOutput('consentPurpose', consentPurpose, ctx.options)
+			);
+		},
+
+		/**
+		 * Finds a consent consentPurpose by its unique ID.
+		 * Returns the consentPurpose with processed output fields according to the schema configuration.
+		 *
+		 * @param purposeId - The unique identifier of the consentPurpose
+		 * @returns The consentPurpose object if found, null otherwise
+		 */
+		findConsentPurposeById: async (purposeId: string) => {
+			const consentPurpose = await adapter.findOne({
+				model: 'consentPurpose',
+				where: [
+					{
+						field: 'id',
+						value: purposeId,
+					},
+				],
+			});
+			return consentPurpose
+				? validateEntityOutput('consentPurpose', consentPurpose, ctx.options)
+				: null;
+		},
+
+		/**
+		 * Finds a consent consentPurpose by its unique code.
+		 * Returns the consentPurpose with processed output fields according to the schema configuration.
+		 *
+		 * @param code - The unique code of the consentPurpose
+		 * @returns The consentPurpose object if found, null otherwise
+		 */
+		findConsentPurposeByCode: async (code: string) => {
+			const consentPurpose = await adapter.findOne({
+				model: 'consentPurpose',
+				where: [
+					{
+						field: 'code',
+						value: code,
+					},
+				],
+			});
+			return consentPurpose
+				? validateEntityOutput('consentPurpose', consentPurpose, ctx.options)
+				: null;
+		},
+
+		/**
+     * 
+		/**
+     * 
+		 * Updates an existing consent consentPurpose record by ID.
+		 * Applies any configured hooks during the update process and
+		 * processes the output according to schema configuration.
+		 *
+		 * @param purposeId - The unique identifier of the consentPurpose to update
+		 * @param data - The fields to update on the consentPurpose record
+		 * @param context - Optional endpoint context for hooks
+		 * @returns The updated consentPurpose if successful, null if not found or hooks prevented update
+		 */
+		updateConsentPurpose: async (
+			purposeId: string,
+			data: Partial<ConsentPurpose>,
+			context?: GenericEndpointContext
+		) => {
+			const consentPurpose = await updateWithHooks({
+				data: {
+					...data,
+					updatedAt: new Date(),
+				},
+				where: [
+					{
+						field: 'id',
+						value: purposeId,
+					},
+				],
+				model: 'consentPurpose',
+				context,
+			});
+			return consentPurpose
+				? validateEntityOutput('consentPurpose', consentPurpose, ctx.options)
+				: null;
+		},
+	};
+}

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

@@ -0,0 +1,58 @@
+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().default(false),
+	dataCategory: z.string().optional(),
+	legalBasis: z.string().optional(),
+	isActive: z.boolean().default(true),
+	createdAt: z.date().default(() => new Date()),
+	updatedAt: z.date().default(() => 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/db/schema/consent-purpose/table.ts

@@ -0,0 +1,154 @@
+import type { Field } from '~/db/core/fields';
+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/db/schema/consent-purpose/types.ts

@@ -0,0 +1,16 @@
+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/db/schema/consent-purpose-junction/index.ts

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

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

@@ -0,0 +1,189 @@
+import type { GenericEndpointContext, RegistryContext } from '~/types';
+import type { PurposeJunction } from './schema';
+
+import { getWithHooks } from '~/db/hooks';
+import { validateEntityOutput } from '../definition';
+
+/**
+ * Creates and returns a set of consent-purpose junction adapter methods to interact with the database.
+ * These methods provide a consistent interface for creating, finding, and managing
+ * relationships between consents and purposes while applying hooks and enforcing data validation rules.
+ *
+ * @param adapter - The database adapter used for direct database operations
+ * @param ctx - The context object containing the database adapter, hooks, and options
+ * @returns An object containing type-safe consent-purpose junction operations
+ *
+ * @example
+ * ```typescript
+ * const junctionAdapter = createConsentPurposeJunctionAdapter(
+ *   databaseAdapter,
+ *   createWithHooks,
+ *   updateWithHooks,
+ *   c15tOptions
+ * );
+ *
+ * // Create a new junction record
+ * const junction = await junctionAdapter.createConsentPurposeJunction({
+ *   consentId: 'cns_hadt8w7nngm7xmx2bn',
+ *   purposeId: 'pol_tioiyf19tbkm7xn5vpx',
+ *   status: 'active'
+ * });
+ * ```
+ */
+export function consentPurposeJunctionRegistry({
+	adapter,
+	...ctx
+}: RegistryContext) {
+	const { createWithHooks, updateWithHooks } = getWithHooks(adapter, ctx);
+	return {
+		/**
+		 * Creates a new consent-purpose junction record in the database.
+		 * Automatically sets creation timestamp and applies any
+		 * configured hooks during the creation process.
+		 *
+		 * @param junction - Junction data to create (without id and timestamp)
+		 * @param context - Optional endpoint context for hooks
+		 * @returns The created junction record with all fields populated
+		 * @throws May throw an error if hooks prevent creation or if database operations fail
+		 */
+		createConsentPurposeJunction: async (
+			junction: Omit<PurposeJunction, 'id' | 'createdAt' | 'status'> &
+				Partial<PurposeJunction>,
+			context?: GenericEndpointContext
+		) => {
+			const createdJunction = await createWithHooks({
+				data: {
+					createdAt: new Date(),
+
+					...junction,
+					status: 'active',
+				},
+				model: 'consentPurposeJunction',
+				customFn: undefined,
+				context,
+			});
+
+			if (!createdJunction) {
+				throw new Error(
+					'Failed to create consent-purpose junction - operation returned null'
+				);
+			}
+
+			return createdJunction as PurposeJunction;
+		},
+
+		/**
+		 * Finds all junction records for a specific consent.
+		 * Returns junctions with processed output fields according to the schema configuration.
+		 *
+		 * @param consentId - The consent ID to find purposes for
+		 * @returns Array of junction records associated with the consent
+		 */
+		findConsentPurposesByConsentId: async (consentId: string) => {
+			const junctions = await adapter.findMany({
+				model: 'consentPurposeJunction',
+				where: [
+					{
+						field: 'consentId',
+						value: consentId,
+					},
+				],
+				sortBy: {
+					field: 'createdAt',
+					direction: 'desc',
+				},
+			});
+
+			return junctions.map((junction) =>
+				validateEntityOutput('consentPurposeJunction', junction, ctx.options)
+			);
+		},
+
+		/**
+		 * Finds all junction records for a specific consentPurpose.
+		 * Returns junctions with processed output fields according to the schema configuration.
+		 *
+		 * @param purposeId - The consentPurpose ID to find consents for
+		 * @returns Array of junction records associated with the consentPurpose
+		 */
+		findConsentPurposesByPurposeId: async (purposeId: string) => {
+			const junctions = await adapter.findMany({
+				model: 'consentPurposeJunction',
+				where: [
+					{
+						field: 'purposeId',
+						value: purposeId,
+					},
+				],
+				sortBy: {
+					field: 'createdAt',
+					direction: 'desc',
+				},
+			});
+
+			return junctions.map((junction) =>
+				validateEntityOutput('consentPurposeJunction', junction, ctx.options)
+			);
+		},
+
+		/**
+		 * Updates a junction record's status.
+		 * Applies any configured hooks during the update process and
+		 * processes the output according to schema configuration.
+		 *
+		 * @param junctionId - The unique identifier of the junction to update
+		 * @param status - The new status value ('active' or 'withdrawn')
+		 * @param context - Optional endpoint context for hooks
+		 * @returns The updated junction if successful, null if not found or hooks prevented update
+		 */
+		updateConsentPurposeJunction: async (
+			junctionId: string,
+			status: 'active' | 'withdrawn',
+			context?: GenericEndpointContext
+		) => {
+			const junction = await updateWithHooks({
+				data: {
+					status,
+					updatedAt: new Date(),
+				},
+				where: [
+					{
+						field: 'id',
+						value: junctionId,
+					},
+				],
+				model: 'consentPurposeJunction',
+				customFn: undefined,
+				context,
+			});
+			return junction
+				? validateEntityOutput('consentPurposeJunction', junction, ctx.options)
+				: null;
+		},
+
+		/**
+		 * Deletes all junction records for a specific consent.
+		 * This effectively removes all consentPurpose connections for the consent.
+		 *
+		 * @param consentId - The ID of the consent to remove all consentPurpose connections for
+		 * @returns True if successful, false otherwise
+		 */
+		deleteConsentPurposeJunctionsByConsentId: async (consentId: string) => {
+			try {
+				await adapter.deleteMany({
+					model: 'consentPurposeJunction',
+					where: [
+						{
+							field: 'consentId',
+							value: consentId,
+						},
+					],
+				});
+				return true;
+			} catch (error) {
+				ctx.logger.error('Error deleting consent-purpose junctions:', error);
+				return false;
+			}
+		},
+	};
+}

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

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+
+/**
+ * Zod schema for validating consent-purpose junction entities.
+ *
+ * This defines the structure and validation rules for junction records:
+ * - Required fields: consentId, purposeId
+ * - Default value of 'active' for status
+ * - Default current date/time for creation and update timestamps
+ * - Default current date/time for update timestamp
+ *
+ * @example
+ * ```typescript
+ * const junctionData = {
+ *   id: 'pjx_w5qufx2a66m7xkn3ty',
+ *   consentId: 'cns_hadt8w7nngm7xmx2bn',
+ *   purposeId: 'pur_e8zyhgozr3im7xj59it',
+ *   status: 'active'
+ * };
+ *
+ * // Validate and parse the junction data
+ * const validJunction = consentPurposeJunctionSchema.parse(junctionData);
+ * ```
+ */
+export const consentPurposeJunctionSchema = z.object({
+	id: z.string(),
+	consentId: z.string(),
+	consentPurposeId: z.string(),
+	status: z
+		.enum(['active', 'withdrawn'], {
+			errorMap: () => ({
+				message: "Status must be either 'active' or 'withdrawn'",
+			}),
+		})
+		.default('active'),
+
+	metadata: z.record(z.union([z.string(), z.number(), z.boolean()])).optional(),
+	createdAt: z.date().default(() => new Date()),
+	updatedAt: z.date().default(() => new Date()),
+});
+
+/**
+ * Type definition for PurposeJunction
+ *
+ * This type represents the structure of a consent-purpose junction record
+ * as defined by the consentPurposeJunctionSchema. It includes all fields
+ * that are part of the junction entity.
+ */
+export type PurposeJunction = z.infer<typeof consentPurposeJunctionSchema>;