@c15t/backend 0.0.1-rc.10

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

@@ -0,0 +1,142 @@
+import type { Field } from '~/db/core/fields';
+import type { C15TOptions } from '~/types';
+import { consentPurposeJunctionSchema } from './schema';
+
+/**
+ * Generates the database table configuration for the consent-purpose junction entity.
+ *
+ * This function creates a schema definition that implements a many-to-many relationship
+ * between consents and purposes. The resulting schema is used for database migrations,
+ * schema validation, and query building.
+ *
+ * @param options - C15T configuration options that may contain junction table customizations
+ * @param junctionFields - Additional fields from plugins to include in the junction table
+ * @returns A complete table schema definition with fields, model name, and metadata
+ *
+ * @example
+ * ```typescript
+ * const junctionTableSchema = getPurposeJunctionTable(c15tOptions);
+ * // Use the schema for migrations or data access
+ * const migrationPlans = generateMigrations(junctionTableSchema);
+ * ```
+ */
+export function getPurposeJunctionTable(
+	options: C15TOptions,
+	junctionFields?: Record<string, Field>
+) {
+	const purposeJunctionConfig = options.tables?.consentPurposeJunction;
+	const consentConfig = options.tables?.consent;
+	const purposeConfig = options.tables?.consentPurpose;
+
+	return {
+		/**
+		 * The name of the junction table in the database, configurable through options
+		 */
+		entityName: purposeJunctionConfig?.entityName || 'consentPurposeJunction',
+
+		/**
+		 * The ID prefix for the consentPurpose junction table
+		 * Used to generate unique prefixed IDs for consentPurpose junctions
+		 */
+		entityPrefix: purposeJunctionConfig?.entityPrefix || 'pjx',
+
+		/**
+		 * The schema for the consentPurpose junction table
+		 */
+		schema: consentPurposeJunctionSchema,
+
+		/**
+		 * Field definitions for the consent-purpose junction table
+		 */
+		fields: {
+			/**
+			 * Reference to the consent record this junction is associated with
+			 */
+			consentId: {
+				type: 'string',
+				required: true,
+				fieldName: purposeJunctionConfig?.fields?.consentId || 'consentId',
+				references: {
+					model: consentConfig?.entityName || 'consent',
+					field: 'id',
+				},
+			},
+
+			/**
+			 * Reference to the consentPurpose record this junction is associated with
+			 */
+			purposeId: {
+				type: 'string',
+				required: true,
+				fieldName: purposeJunctionConfig?.fields?.purposeId || 'purposeId',
+				references: {
+					model: purposeConfig?.entityName || 'consentPurpose',
+					field: 'id',
+				},
+			},
+
+			/**
+			 * Status of this specific consent-purpose relationship
+			 * Default: 'active'
+			 */
+			status: {
+				type: 'string',
+				defaultValue: () => 'active',
+				required: true,
+				fieldName: purposeJunctionConfig?.fields?.status || 'status',
+			},
+
+			/**
+			 * Additional metadata about this specific consent-purpose relationship
+			 */
+			metadata: {
+				type: 'json',
+				required: false,
+				fieldName: purposeJunctionConfig?.fields?.metadata || 'metadata',
+			},
+
+			/**
+			 * When the junction record was created
+			 * Automatically set to current time by default
+			 */
+			createdAt: {
+				type: 'date',
+				defaultValue: () => new Date(),
+				required: true,
+				fieldName: purposeJunctionConfig?.fields?.createdAt || 'createdAt',
+			},
+
+			/**
+			 * When the junction record was last updated
+			 * Optional, set during updates
+			 */
+			updatedAt: {
+				type: 'date',
+				required: false,
+				fieldName: purposeJunctionConfig?.fields?.updatedAt || 'updatedAt',
+			},
+
+			// Include additional fields from plugins
+			...(junctionFields || {}),
+
+			// Include additional fields from configuration
+			...(purposeJunctionConfig?.additionalFields || {}),
+		},
+
+		/**
+		 * Add unique constraint to ensure a consentPurpose can only be associated with a consent once
+		 */
+		uniqueConstraints: [
+			{
+				name: 'unique_consent_purpose',
+				fields: ['consentId', 'purposeId'],
+			},
+		],
+
+		/**
+		 * Execution order during migrations (lower numbers run first)
+		 * Junction table needs to be created after the consent and consentPurpose tables it references
+		 */
+		order: 4,
+	};
+}

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

@@ -0,0 +1,14 @@
+import type { BaseEntityConfig } from '../types';
+
+/**
+ * ConsentPurpose junction entity configuration
+ * @default entityName: "consentPurposeJunction", entityPrefix: "pjx"
+ */
+export interface ConsentPurposeJunctionEntityConfig extends BaseEntityConfig {
+	fields?: Record<string, string> & {
+		id?: string;
+		consentId?: string;
+		purposeId?: string;
+		isAccepted?: string;
+	};
+}

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

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

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

@@ -0,0 +1,209 @@
+import type { Where } from '~/db/adapters/types';
+import { getWithHooks } from '~/db/hooks';
+import type { GenericEndpointContext, RegistryContext } from '~/types';
+import { validateEntityOutput } from '../definition';
+import type { ConsentRecord } from './schema';
+
+/**
+ * Creates and returns a set of consent record-related adapter methods to interact with the database.
+ * These methods provide a consistent interface for creating and querying consent 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 record operations
+ *
+ * @example
+ * ```typescript
+ * const recordAdapter = createRecordAdapter(
+ *   databaseAdapter,
+ *   createWithHooks,
+ *   c15tOptions
+ * );
+ *
+ * // Create a new consent record
+ * const record = await recordAdapter.createConsentRecord({
+ *   subjectId: 'sub_x1pftyoufsm7xgo1kv',
+ *   consentId: 'cns_hadt8w7nngm7xmx2bn',
+ *   actionType: 'given',
+ *   details: { ip: '192.168.1.1', userAgent: 'Mozilla/5.0...' }
+ * });
+ * ```
+ */
+export function consentRecordRegistry({ adapter, ...ctx }: RegistryContext) {
+	const { createWithHooks } = getWithHooks(adapter, ctx);
+	return {
+		/**
+		 * Creates a new consent record in the database.
+		 * Automatically sets creation timestamp and applies any
+		 * configured hooks during the creation process.
+		 *
+		 * @param record - Consent record data to create (without id and timestamp)
+		 * @param context - Optional endpoint context for hooks
+		 * @returns The created consent record with all fields populated
+		 * @throws May throw an error if hooks prevent creation or if database operations fail
+		 */
+		createConsentRecord: async (
+			record: Omit<ConsentRecord, 'id' | 'createdAt' | 'updatedAt'> &
+				Partial<ConsentRecord>,
+			context?: GenericEndpointContext
+		) => {
+			const createdRecord = await createWithHooks({
+				data: {
+					createdAt: record.createdAt || new Date(),
+					updatedAt: record.updatedAt || new Date(),
+					...record,
+				},
+				model: 'consentRecord',
+				customFn: undefined,
+				context,
+			});
+
+			if (!createdRecord) {
+				throw new Error(
+					'Failed to create consent record - operation returned null'
+				);
+			}
+
+			return createdRecord as ConsentRecord;
+		},
+
+		/**
+		 * Finds all consent records matching specified filters.
+		 * Returns records with processed output fields according to the schema configuration.
+		 *
+		 * @param subjectId - Optional subject ID to filter records
+		 * @param consentId - Optional consent ID to filter records
+		 * @param actionType - Optional action type to filter records
+		 * @param limit - Optional maximum number of records to return
+		 * @returns Array of consent records matching the criteria
+		 */
+		findConsentRecords: async (
+			subjectId?: string,
+			consentId?: string,
+			actionType?: string,
+			limit?: number
+		) => {
+			const whereConditions: Where<'consentRecord'> = [];
+
+			if (subjectId) {
+				whereConditions.push({
+					field: 'subjectId',
+					value: subjectId,
+				});
+			}
+
+			if (consentId) {
+				whereConditions.push({
+					field: 'consentId',
+					value: consentId,
+				});
+			}
+
+			if (actionType) {
+				whereConditions.push({
+					field: 'actionType',
+					value: actionType,
+				});
+			}
+
+			const records = await adapter.findMany({
+				model: 'consentRecord',
+				where: whereConditions,
+				sortBy: {
+					field: 'createdAt',
+					direction: 'desc',
+				},
+				limit,
+			});
+
+			return records.map((record) =>
+				validateEntityOutput('consentRecord', record, ctx.options)
+			);
+		},
+
+		/**
+		 * Finds a consent record by its unique ID.
+		 * Returns the record with processed output fields according to the schema configuration.
+		 *
+		 * @param recordId - The unique identifier of the consent record
+		 * @returns The consent record object if found, null otherwise
+		 */
+		findConsentRecordById: async (recordId: string) => {
+			const record = await adapter.findOne({
+				model: 'consentRecord',
+				where: [
+					{
+						field: 'id',
+						value: recordId,
+					},
+				],
+			});
+			return record
+				? validateEntityOutput('consentRecord', record, ctx.options)
+				: null;
+		},
+
+		/**
+		 * Finds all consent records for a specific subject.
+		 * Returns records with processed output fields according to the schema configuration.
+		 *
+		 * @param subjectId - The subject ID to find consent records for
+		 * @param limit - Optional maximum number of records to return
+		 * @returns Array of consent records associated with the subject
+		 */
+		findConsentRecordsBySubjectId: async (
+			subjectId: string,
+			limit?: number
+		) => {
+			const records = await adapter.findMany({
+				model: 'consentRecord',
+				where: [
+					{
+						field: 'subjectId',
+						value: subjectId,
+					},
+				],
+				sortBy: {
+					field: 'createdAt',
+					direction: 'desc',
+				},
+				limit,
+			});
+			return records.map((record) =>
+				validateEntityOutput('consentRecord', record, ctx.options)
+			);
+		},
+
+		/**
+		 * Finds all consent records for a specific consent.
+		 * Returns records with processed output fields according to the schema configuration.
+		 *
+		 * @param consentId - The consent ID to find records for
+		 * @param limit - Optional maximum number of records to return
+		 * @returns Array of consent records associated with the consent
+		 */
+		findConsentRecordsByConsentId: async (
+			consentId: string,
+			limit?: number
+		) => {
+			const records = await adapter.findMany({
+				model: 'consentRecord',
+				where: [
+					{
+						field: 'consentId',
+						value: consentId,
+					},
+				],
+				sortBy: {
+					field: 'createdAt',
+					direction: 'desc',
+				},
+				limit,
+			});
+			return records.map((record) =>
+				validateEntityOutput('consentRecord', record, ctx.options)
+			);
+		},
+	};
+}

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

@@ -0,0 +1,42 @@
+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.unknown()).optional(),
+	createdAt: z.date().default(() => new Date()),
+	updatedAt: z.date().default(() => 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/db/schema/consent-record/table.ts

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

@@ -0,0 +1,21 @@
+/**
+ * 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/db/schema/consent-withdrawal/index.ts

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