@c15t/backend 0.0.1-rc.10

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

@@ -0,0 +1,219 @@
+import type { Where } from '~/db/adapters/types';
+import { getWithHooks } from '~/db/hooks';
+import type { RegistryContext } from '~/types';
+import type { GenericEndpointContext } from '~/types';
+import { validateEntityOutput } from '../definition';
+import type { Withdrawal } from './schema';
+
+/**
+ * Creates and returns a set of consent withdrawal adapter methods to interact with the database.
+ * These methods provide a consistent interface for creating and querying consentWithdrawal 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 withdrawal operations
+ *
+ * @example
+ * ```typescript
+ * const withdrawalAdapter = createConsentWithdrawalAdapter(
+ *   databaseAdapter,
+ *   createWithHooks,
+ *   c15tOptions
+ * );
+ *
+ * // Create a new consentWithdrawal record
+ * const consentWithdrawal = await withdrawalAdapter.createConsentWithdrawal({
+ *   consentId: 'cns_hadt8w7nngm7xmx2bn',
+ *   subjectId: 'sub_x1pftyoufsm7xgo1kv',
+ *   withdrawalReason: 'No longer wish to receive marketing emails',
+ *   withdrawalMethod: 'subject-initiated'
+ * });
+ * ```
+ */
+export function consentWithdrawalRegistry({
+	adapter,
+	...ctx
+}: RegistryContext) {
+	const { createWithHooks } = getWithHooks(adapter, ctx);
+	return {
+		/**
+		 * Creates a new consent withdrawal record in the database.
+		 * Automatically sets creation timestamp and applies any
+		 * configured hooks during the creation process.
+		 *
+		 * @param consentWithdrawal - Withdrawal data to create (without id and timestamp)
+		 * @param context - Optional endpoint context for hooks
+		 * @returns The created consentWithdrawal record with all fields populated
+		 * @throws May throw an error if hooks prevent creation or if database operations fail
+		 */
+		createConsentWithdrawal: async (
+			consentWithdrawal: Omit<Withdrawal, 'id' | 'createdAt'> &
+				Partial<Withdrawal>,
+			context?: GenericEndpointContext
+		) => {
+			const createdWithdrawal = await createWithHooks({
+				data: {
+					createdAt: new Date(),
+					...consentWithdrawal,
+				},
+				model: 'consentWithdrawal',
+				customFn: undefined,
+				context,
+			});
+
+			if (!createdWithdrawal) {
+				throw new Error(
+					'Failed to create consent withdrawal - operation returned null'
+				);
+			}
+
+			return validateEntityOutput(
+				'consentWithdrawal',
+				createdWithdrawal,
+				ctx.options
+			);
+		},
+
+		/**
+		 * Finds all consentWithdrawal records matching specified filters.
+		 * Returns consentWithdrawals with processed output fields according to the schema configuration.
+		 *
+		 * @param subjectId - Optional subject ID to filter consentWithdrawals
+		 * @param consentId - Optional consent ID to filter consentWithdrawals
+		 * @param limit - Optional maximum number of records to return
+		 * @returns Array of consentWithdrawal records matching the criteria
+		 */
+		findConsentWithdrawals: async (
+			subjectId?: string,
+			consentId?: string,
+			limit?: number
+		) => {
+			const whereConditions: Where<'consentWithdrawal'> = [];
+
+			if (subjectId) {
+				whereConditions.push({
+					field: 'subjectId',
+					value: subjectId,
+				});
+			}
+
+			if (consentId) {
+				whereConditions.push({
+					field: 'consentId',
+					value: consentId,
+				});
+			}
+
+			const consentWithdrawals = await adapter.findMany({
+				model: 'consentWithdrawal',
+				where: whereConditions,
+				sortBy: {
+					field: 'createdAt',
+					direction: 'desc',
+				},
+				limit,
+			});
+
+			return consentWithdrawals.map((consentWithdrawal) =>
+				validateEntityOutput(
+					'consentWithdrawal',
+					consentWithdrawal,
+					ctx.options
+				)
+			);
+		},
+
+		/**
+		 * Finds a consentWithdrawal record by its unique ID.
+		 * Returns the consentWithdrawal with processed output fields according to the schema configuration.
+		 *
+		 * @param withdrawalId - The unique identifier of the consentWithdrawal record
+		 * @returns The consentWithdrawal object if found, null otherwise
+		 */
+		findConsentWithdrawalById: async (withdrawalId: string) => {
+			const consentWithdrawal = await adapter.findOne({
+				model: 'consentWithdrawal',
+				where: [
+					{
+						field: 'id',
+						value: withdrawalId,
+					},
+				],
+			});
+			return consentWithdrawal
+				? validateEntityOutput(
+						'consentWithdrawal',
+						consentWithdrawal,
+						ctx.options
+					)
+				: null;
+		},
+
+		/**
+		 * Finds all consentWithdrawal records for a specific subject.
+		 * Returns consentWithdrawals with processed output fields according to the schema configuration.
+		 *
+		 * @param subjectId - The subject ID to find consentWithdrawals for
+		 * @param limit - Optional maximum number of records to return
+		 * @returns Array of consentWithdrawal records associated with the subject
+		 */
+		findConsentWithdrawalsBySubjectId: async (
+			subjectId: string,
+			limit?: number
+		) => {
+			const consentWithdrawals = await adapter.findMany({
+				model: 'consentWithdrawal',
+				where: [
+					{
+						field: 'subjectId',
+						value: subjectId,
+					},
+				],
+				sortBy: {
+					field: 'createdAt',
+					direction: 'desc',
+				},
+				limit,
+			});
+			return consentWithdrawals.map((consentWithdrawal) =>
+				validateEntityOutput(
+					'consentWithdrawal',
+					consentWithdrawal,
+					ctx.options
+				)
+			);
+		},
+
+		/**
+		 * Finds a consentWithdrawal record for a specific consent.
+		 * Returns the consentWithdrawal with processed output fields according to the schema configuration.
+		 * This is useful when you need to know if and why a specific consent was withdrawn.
+		 *
+		 * @param consentId - The consent ID to find consentWithdrawal for
+		 * @returns The consentWithdrawal record if found, null otherwise
+		 */
+		findConsentWithdrawalByConsentId: async (consentId: string) => {
+			const consentWithdrawal = await adapter.findOne({
+				model: 'consentWithdrawal',
+				where: [
+					{
+						field: 'consentId',
+						value: consentId,
+					},
+				],
+				sortBy: {
+					field: 'createdAt',
+					direction: 'desc',
+				},
+			});
+			return consentWithdrawal
+				? validateEntityOutput(
+						'consentWithdrawal',
+						consentWithdrawal,
+						ctx.options
+					)
+				: null;
+		},
+	};
+}

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

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+
+/**
+ * Zod schema for validating consent withdrawal entities.
+ *
+ * This defines the structure and validation rules for consentWithdrawal records:
+ * - Required fields: consentId, subjectId
+ * - Optional fields: withdrawalReason, withdrawalMethod, ipAddress, metadata
+ * - Default current date/time for creation and update timestamps
+ *
+ * @example
+ * ```typescript
+ * const withdrawalData = {
+ *   id: 'wdr_w5qufx2a66m7xkn3ty',
+ *   consentId: 'cns_hadt8w7nngm7xmx2bn',
+ *   subjectId: 'sub_x1pftyoufsm7xgo1kv',
+ *   withdrawalReason: 'No longer wish to receive marketing emails',
+ *   withdrawalMethod: 'subject-initiated',
+ *   ipAddress: '192.168.1.1'
+ * };
+ *
+ * // Validate and parse the consentWithdrawal data
+ * const validWithdrawal = consentWithdrawalSchema.parse(withdrawalData);
+ * ```
+ */
+export const consentWithdrawalSchema = z.object({
+	id: z.string(),
+	consentId: z.string(),
+	subjectId: z.string(),
+	withdrawalReason: z.string().optional(),
+	withdrawalMethod: z
+		.enum(['subject-initiated', 'automatic-expiry', 'admin', 'api', 'other'])
+		.default('subject-initiated'),
+	ipAddress: z.string().optional(),
+	userAgent: z.string().optional(),
+	metadata: z.record(z.unknown()).optional(),
+	createdAt: z.date().default(() => new Date()),
+	updatedAt: z.date().default(() => new Date()),
+});
+
+/**
+ * Type definition for Withdrawal
+ *
+ * This type represents the structure of a consent withdrawal record
+ * as defined by the consentWithdrawalSchema. It includes all fields
+ * that are part of the consentWithdrawal entity.
+ */
+export type Withdrawal = z.infer<typeof consentWithdrawalSchema>;

package/src/db/schema/consent-withdrawal/table.ts

@@ -0,0 +1,181 @@
+import type { Field } from '~/db/core/fields';
+import type { C15TOptions } from '~/types';
+import { consentWithdrawalSchema } from './schema';
+
+/**
+ * Generates the database table configuration for the consent withdrawal entity.
+ *
+ * This function creates a schema definition that includes all standard consentWithdrawal 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 consentWithdrawal table customizations
+ * @param withdrawalFields - Additional fields from plugins to include in the consentWithdrawal table
+ * @returns A complete table schema definition with fields, model name, and metadata
+ *
+ * @example
+ * ```typescript
+ * const withdrawalTableSchema = getConsentWithdrawalTable(c15tOptions);
+ * // Use the schema for migrations or data access
+ * const migrationPlans = generateMigrations(withdrawalTableSchema);
+ * ```
+ */
+export function getConsentWithdrawalTable(
+	options: C15TOptions,
+	withdrawalFields?: Record<string, Field>
+) {
+	const consentWithdrawalConfig = options.tables?.consentWithdrawal;
+	const consentConfig = options.tables?.consent;
+	const subjectConfig = options.tables?.subject;
+
+	return {
+		/**
+		 * The name of the consentWithdrawal table in the database, configurable through options
+		 */
+		entityName: consentWithdrawalConfig?.entityName || 'consentWithdrawal',
+
+		/**
+		 * The ID prefix for the consentWithdrawal table
+		 * Used to generate unique prefixed IDs for consentWithdrawals
+		 */
+		entityPrefix: consentWithdrawalConfig?.entityPrefix || 'wdr',
+
+		/**
+		 * The schema for the consent withdrawal table
+		 */
+		schema: consentWithdrawalSchema,
+
+		/**
+		 * Field definitions for the consent withdrawal table
+		 */
+		fields: {
+			/**
+			 * Reference to the consent that was withdrawn
+			 */
+			consentId: {
+				type: 'string',
+				required: true,
+				fieldName: consentWithdrawalConfig?.fields?.consentId || 'consentId',
+				references: {
+					model: consentConfig?.entityName || 'consent',
+					field: 'id',
+				},
+			},
+
+			/**
+			 * Reference to the subject who withdrew consent
+			 */
+			subjectId: {
+				type: 'string',
+				required: true,
+				fieldName: consentWithdrawalConfig?.fields?.subjectId || 'subjectId',
+				references: {
+					model: subjectConfig?.entityName || 'subject',
+					field: 'id',
+				},
+			},
+
+			/**
+			 * Reason provided for withdrawing consent
+			 */
+			withdrawalReason: {
+				type: 'string',
+				required: false,
+				fieldName:
+					consentWithdrawalConfig?.fields?.withdrawalReason ||
+					'withdrawalReason',
+			},
+
+			/**
+			 * Method by which consent was withdrawn
+			 * Common values: 'subject-initiated', 'automatic-expiry', 'admin'
+			 */
+			withdrawalMethod: {
+				type: 'string',
+				defaultValue: () => 'subject-initiated',
+				required: true,
+				fieldName:
+					consentWithdrawalConfig?.fields?.withdrawalMethod ||
+					'withdrawalMethod',
+			},
+
+			/**
+			 * IP address from which the consentWithdrawal was initiated
+			 */
+			ipAddress: {
+				type: 'string',
+				required: false,
+				fieldName: consentWithdrawalConfig?.fields?.ipAddress || 'ipAddress',
+			},
+
+			/**
+			 * Subject agent (browser/device) from which the consentWithdrawal was initiated
+			 */
+			userAgent: {
+				type: 'string',
+				required: false,
+				fieldName: consentWithdrawalConfig?.fields?.userAgent || 'userAgent',
+			},
+
+			/**
+			 * Additional metadata about the consentWithdrawal
+			 */
+			metadata: {
+				type: 'json',
+				required: false,
+				fieldName: consentWithdrawalConfig?.fields?.metadata || 'metadata',
+			},
+
+			/**
+			 * When the consentWithdrawal record was created
+			 * Automatically set to current time by default
+			 */
+			createdAt: {
+				type: 'date',
+				defaultValue: () => new Date(),
+				required: true,
+				fieldName: consentWithdrawalConfig?.fields?.createdAt || 'createdAt',
+			},
+
+			// Include additional fields from plugins
+			...(withdrawalFields || {}),
+
+			// Include additional fields from configuration
+			...(consentWithdrawalConfig?.additionalFields || {}),
+		},
+
+		/**
+		 * Add unique constraint to ensure a consent can only be withdrawn once
+		 * (If this constraint is not desired, it can be disabled in options)
+		 */
+		uniqueConstraints:
+			consentWithdrawalConfig?.preventMultipleWithdrawals !== false
+				? [
+						{
+							name: 'unique_consent_withdrawal',
+							fields: ['consentId'],
+						},
+					]
+				: [],
+
+		/**
+		 * Add indexes for better query performance
+		 */
+		indexes: [
+			{
+				name: 'subject_id_index',
+				fields: ['subjectId'],
+			},
+			{
+				name: 'created_at_index',
+				fields: ['createdAt'],
+			},
+		],
+
+		/**
+		 * Execution order during migrations (lower numbers run first)
+		 * Withdrawal table needs to be created after the consent and subject tables it references
+		 */
+		order: 4,
+	};
+}

package/src/db/schema/consent-withdrawal/types.ts

@@ -0,0 +1,29 @@
+import type { BaseEntityConfig } from '../types';
+
+/**
+ * Withdrawal entity configuration
+ * @default entityName: "consentWithdrawal", entityPrefix: "wdr"
+ */
+export interface ConsentWithdrawalEntityConfig extends BaseEntityConfig {
+	fields?: Record<string, string> & {
+		id?: string;
+		consentId?: string;
+		revokedAt?: string;
+		revocationReason?: string;
+		method?: string;
+		actor?: string;
+		metadata?: string;
+		createdAt?: string;
+	};
+
+	/**
+	 * Prevent multiple consentWithdrawals for the same consent
+	 *
+	 * If true, a subject can only have one consentWithdrawal record per consent,
+	 * preventing multiple revocation records for the same consent.
+	 * This helps maintain data integrity and clearer consent history.
+	 *
+	 * @default false
+	 */
+	preventMultipleWithdrawals?: boolean;
+}

package/src/db/schema/definition.ts

@@ -0,0 +1,196 @@
+import type { C15TOptions } from '~/types';
+import type { PluginSchema } from '../core/types';
+import {
+	getAuditLogTable,
+	getConsentGeoLocationTable,
+	getConsentPolicyTable,
+	// getGeoLocationTable,
+	getConsentRecordTable,
+	getConsentTable,
+	getConsentWithdrawalTable,
+	getDomainTable,
+	getGeoLocationTable,
+	getPurposeJunctionTable,
+	getPurposeTable,
+	getSubjectTable,
+} from './index';
+import type { InferTableShape } from './schemas';
+
+/**
+ * Retrieves all consent-related database table definitions
+ *
+ * This function combines the core tables with any additional tables
+ * defined by plugins. It handles merging plugin-defined fields with
+ * the standard tables and ensures all table definitions are properly
+ * structured for use by database adapters.
+ *
+ * @param options - The c15t configuration options
+ * @returns A complete schema mapping containing all table definitions
+ *
+ * @remarks
+ * Each table definition includes both field definitions and the physical
+ * entity name used in the database. Plugins can extend core tables by
+ * defining additional fields, which will be merged with the standard fields.
+ *
+ * @example
+ * ```typescript
+ * // Get all tables with default configuration
+ * const tables = getConsentTables(options);
+ *
+ * // Access fields for the consent table
+ * const consentFields = tables.consent.fields;
+ * ```
+ */
+export const getConsentTables = (options: C15TOptions) => {
+	const pluginSchema = options.plugins?.reduce((acc, plugin) => {
+		const schema = plugin.schema;
+		if (!schema) {
+			return acc;
+		}
+		for (const [key, value] of Object.entries(schema)) {
+			acc[key] = {
+				fields: {
+					...acc[key]?.fields,
+					...value.fields,
+				},
+				entityName: value.entityName || key,
+			};
+		}
+		return acc;
+	}, {} as PluginSchema);
+
+	const {
+		subject,
+		consentPurpose,
+		consentPolicy,
+		domain,
+		geoLocation,
+		consent,
+		consentPurposeJunction,
+		record,
+		consentGeoLocation,
+		consentWithdrawal,
+		auditLog,
+		...pluginTables
+	} = pluginSchema || {};
+
+	return {
+		subject: getSubjectTable(options, subject?.fields),
+		consentPurpose: getPurposeTable(options, consentPurpose?.fields),
+		consentPolicy: getConsentPolicyTable(options, consentPolicy?.fields),
+		domain: getDomainTable(options, domain?.fields),
+		consent: getConsentTable(options, consent?.fields),
+		consentPurposeJunction: getPurposeJunctionTable(
+			options,
+			consentPurposeJunction?.fields
+		),
+		consentRecord: getConsentRecordTable(options, record?.fields),
+		consentGeoLocation: getConsentGeoLocationTable(
+			options,
+			consentGeoLocation?.fields
+		),
+		consentWithdrawal: getConsentWithdrawalTable(
+			options,
+			consentWithdrawal?.fields
+		),
+		auditLog: getAuditLogTable(options, auditLog?.fields),
+		geoLocation: getGeoLocationTable(options, geoLocation?.fields),
+		...pluginTables,
+	};
+};
+
+/**
+ * Type representing the complete database schema for c15t
+ *
+ * This type captures the full structure of all tables in the database,
+ * including core tables and any plugin-defined tables. It's derived from
+ * the return type of `getConsentTables()`.
+ *
+ * @remarks
+ * This is a key type for type-safety throughout the codebase, as it
+ * ensures that table names and field references are validated at compile time.
+ * It's used as a basis for many other type definitions in the database layer.
+ *
+ * @example
+ * ```typescript
+ * // Type-safe reference to a specific table
+ * function processTable<TableName extends keyof C15TDBSchema>(
+ *   tableName: TableName,
+ *   data: Record<string, unknown>
+ * ) {
+ *   const tableFields = getConsentTables(options)[tableName].fields;
+ *   // Process with type safety...
+ * }
+ * ```
+ */
+export type C15TDBSchema = ReturnType<typeof getConsentTables>;
+
+/**
+ * Type to get all output fields of a table by its name
+ * This type extracts only the fields that are included in output operations,
+ * automatically excluding fields marked with { returned: false }.
+ * It also resolves relationships between tables.
+ */
+export type EntityOutputFields<TableName extends keyof C15TDBSchema> =
+	InferTableShape<TableName>;
+
+/**
+ * Type to get all input fields of a table by its name
+ * This type extracts only the fields that are allowed for input operations,
+ * automatically excluding fields marked with { input: false }.
+ */
+export type EntityInputFields<TableName extends keyof C15TDBSchema> = Omit<
+	InferTableShape<TableName>,
+	'id' | 'createdAt' | 'updatedAt'
+>;
+
+/**
+ * Validates output data against table schema using Zod
+ *
+ * This function validates and transforms output data according to the
+ * schema definition for a specific table. It ensures that all values match
+ * their expected types and excludes fields marked as not to be returned.
+ *
+ * @typeParam TableName - The table name from C15TDBSchema
+ * @param tableName - The name of the table to validate against
+ * @param data - The data to validate
+ * @param options - The C15TOptions instance
+ * @returns Validated and typed data
+ * @throws {Error} If the table is not found or validation fails
+ *
+ * @remarks
+ * This function is particularly useful for validating data received from
+ * external sources or database adapters before processing it in application logic.
+ *
+ * @example
+ * ```typescript
+ * // Validate data retrieved from an external API
+ * try {
+ *   const validSubjectOutput = validateEntityOutput(
+ *     'subject',
+ *     fetchedSubjectData,
+ *     options
+ *   );
+ *
+ *   // validSubjectOutput is now typed as EntityOutputFields<'subject'>
+ *   displaySubjectProfile(validSubjectOutput);
+ * } catch (error) {
+ *   console.error('Output validation failed:', error.message);
+ * }
+ * ```
+ */
+export function validateEntityOutput<TableName extends keyof C15TDBSchema>(
+	tableName: TableName,
+	data: Record<string, unknown>,
+	options: C15TOptions
+): EntityOutputFields<TableName> {
+	const tables = getConsentTables(options);
+	const table = tables[tableName];
+
+	if (!table) {
+		throw new Error(`Table ${tableName} not found`);
+	}
+
+	// Validate and return data using Zod schema
+	return table.schema.parse(data) as EntityOutputFields<TableName>;
+}

package/src/db/schema/domain/index.ts

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