@c15t/backend 0.0.1-rc.10

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

@@ -0,0 +1,313 @@
+import { createHash } from 'node:crypto';
+import type { Where } from '~/db/adapters/types';
+import { getWithHooks } from '~/db/hooks';
+import type { GenericEndpointContext, RegistryContext } from '~/types';
+import { validateEntityOutput } from '../definition';
+import type { ConsentPolicy } from './schema';
+
+export interface FindPolicyParams {
+	domainId?: string;
+	version?: string;
+	includeInactive?: boolean;
+}
+
+/**
+ * Generates placeholder content for a policy with its hash.
+ *
+ * @param name - Policy name
+ * @param date - Generation date
+ * @returns Object containing content and contentHash
+ */
+function generatePolicyPlaceholder(name: string, date: Date) {
+	const content = `[PLACEHOLDER] This is an automatically generated version of the ${name} policy.\n\nThis placeholder content should be replaced with actual policy terms before being presented to users.\n\nGenerated on: ${date.toISOString()}`;
+	const contentHash = createHash('sha256').update(content).digest('hex');
+	return { content, contentHash };
+}
+
+/**
+ * Creates and returns a set of consent policy-related adapter methods to interact with the database.
+ * These methods provide a consistent interface for creating, finding, and updating
+ * consent policy 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 policy operations
+ *
+ * @example
+ * ```typescript
+ * const policyAdapter = createConsentPolicyAdapter(
+ *   databaseAdapter,
+ *   createWithHooks,
+ *   updateWithHooks,
+ *   c15tOptions
+ * );
+ *
+ * // Create a new consent policy
+ * const policy = await policyAdapter.createConsentPolicy({
+ *   version: '1.0.0',
+ *   name: 'Privacy Policy 2023',
+ *   effectiveDate: new Date(),
+ *   content: 'Full policy text...',
+ *   contentHash: 'sha256-hash-of-content'
+ * });
+ * ```
+ */
+export function policyRegistry({ adapter, ...ctx }: RegistryContext) {
+	const { createWithHooks, updateWithHooks } = getWithHooks(adapter, ctx);
+	const registry = {
+		/**
+		 * Creates a new consent policy record in the database.
+		 * Automatically sets creation timestamp and applies any
+		 * configured hooks during the creation process.
+		 *
+		 * @param policy - Policy data to create (without id and timestamp)
+		 * @param context - Optional endpoint context for hooks
+		 * @returns The created policy with all fields populated
+		 * @throws May throw an error if hooks prevent creation or if database operations fail
+		 */
+		createConsentPolicy: async (
+			policy: Omit<ConsentPolicy, 'id' | 'createdAt'> & Partial<ConsentPolicy>,
+			context?: GenericEndpointContext
+		) => {
+			const createdPolicy = await createWithHooks({
+				data: {
+					createdAt: new Date(),
+					...policy,
+				},
+				model: 'consentPolicy',
+				context,
+			});
+
+			if (!createdPolicy) {
+				throw new Error(
+					'Failed to create consent policy - operation returned null'
+				);
+			}
+
+			return createdPolicy as ConsentPolicy;
+		},
+
+		findPolicies: async (params: FindPolicyParams = {}) => {
+			const whereConditions: Where<'consentPolicy'> = [];
+
+			if (!params.includeInactive) {
+				whereConditions.push({
+					field: 'isActive',
+					value: true,
+				});
+			}
+
+			if (params.domainId) {
+				whereConditions.push({
+					field: 'id',
+					value: params.domainId,
+				});
+			}
+
+			if (params.version) {
+				whereConditions.push({
+					field: 'version',
+					value: params.version,
+				});
+			}
+
+			const policies = await adapter.findMany({
+				model: 'consentPolicy',
+				where: whereConditions,
+				sortBy: {
+					field: 'effectiveDate',
+					direction: 'desc',
+				},
+			});
+
+			return policies.map((policy) =>
+				validateEntityOutput('consentPolicy', policy, ctx.options)
+			);
+		},
+
+		findPolicy: async (domainId: string, version?: string) => {
+			const policies = await registry.findPolicies({ domainId, version });
+			return policies[0] || null;
+		},
+
+		/**
+		 * Finds all active consent policies.
+		 * Returns policies with processed output fields according to the schema configuration.
+		 *
+		 * @returns Array of active consent policies sorted by effective date
+		 */
+		findActiveConsentPolicies: async () => {
+			const policies = await adapter.findMany({
+				model: 'consentPolicy',
+				where: [
+					{
+						field: 'isActive',
+						value: true,
+					},
+				],
+				sortBy: {
+					field: 'effectiveDate',
+					direction: 'desc',
+				},
+			});
+
+			return policies.map((policy) =>
+				validateEntityOutput('consentPolicy', policy, ctx.options)
+			);
+		},
+
+		/**
+		 * Finds a consent policy by its unique ID.
+		 * Returns the policy with processed output fields according to the schema configuration.
+		 *
+		 * @param policyId - The unique identifier of the policy
+		 * @returns The policy object if found, null otherwise
+		 */
+		findConsentPolicyById: async (policyId: string) => {
+			const policy = await adapter.findOne({
+				model: 'consentPolicy',
+				where: [
+					{
+						field: 'id',
+						value: policyId,
+					},
+				],
+			});
+			return policy
+				? validateEntityOutput('consentPolicy', policy, ctx.options)
+				: null;
+		},
+
+		/**
+		 * Finds a consent policy by its version string.
+		 * Returns the policy with processed output fields according to the schema configuration.
+		 *
+		 * @param version - The version string of the policy
+		 * @returns The policy object if found, null otherwise
+		 */
+		findConsentPolicyByVersion: async (version: string) => {
+			const policy = await adapter.findOne({
+				model: 'consentPolicy',
+				where: [
+					{
+						field: 'version',
+						value: version,
+					},
+				],
+			});
+			return policy
+				? validateEntityOutput('consentPolicy', policy, ctx.options)
+				: null;
+		},
+
+		/**
+		 * Updates an existing consent policy record by ID.
+		 * Applies any configured hooks during the update process and
+		 * processes the output according to schema configuration.
+		 *
+		 * @param policyId - The unique identifier of the policy to update
+		 * @param data - The fields to update on the policy record
+		 * @param context - Optional endpoint context for hooks
+		 * @returns The updated policy if successful, null if not found or hooks prevented update
+		 */
+		updateConsentPolicy: async (
+			policyId: string,
+			data: Partial<ConsentPolicy>,
+			context?: GenericEndpointContext
+		) => {
+			const policy = await updateWithHooks<
+				Partial<ConsentPolicy>,
+				ConsentPolicy
+			>({
+				data,
+				where: [
+					{
+						field: 'id',
+						value: policyId,
+					},
+				],
+				model: 'consentPolicy',
+				customFn: undefined,
+				context,
+			});
+			return policy
+				? validateEntityOutput('consentPolicy', policy, ctx.options)
+				: null;
+		},
+
+		/**
+		 * Finds the latest active policy or creates a new one if none exists.
+		 * Uses a database transaction to prevent race conditions in multi-threaded environments.
+		 *
+		 * If multiple active policies with the same name exist, returns the most recent one
+		 * based on effectiveDate. When creating a new policy, it assigns version '1.0.0'
+		 * and generates placeholder content with a SHA-256 hash.
+		 *
+		 * @param name - The name of the policy to find/create
+		 * @returns The policy object
+		 * @throws {Error} If the transaction fails to complete
+		 */
+		findOrCreatePolicy: async (name: string) => {
+			// Normalize name for comparison
+			const normalizedSearchName = name.toLowerCase().trim();
+
+			// Use a transaction to prevent race conditions
+			return adapter.transaction({
+				callback: async (txAdapter) => {
+					const now = new Date();
+					const txRegistry = policyRegistry({
+						adapter: txAdapter,
+						...ctx,
+					});
+
+					// Find latest policy with exact name match directly from database
+					const matchingPolicies = await txAdapter.findMany({
+						model: 'consentPolicy',
+						where: [
+							{ field: 'isActive', value: true },
+							{
+								field: 'name',
+								value: normalizedSearchName,
+								operator: 'ilike',
+							},
+						],
+						sortBy: {
+							field: 'effectiveDate',
+							direction: 'desc',
+						},
+						limit: 1,
+					});
+
+					const latestPolicy = matchingPolicies[0]
+						? validateEntityOutput(
+								'consentPolicy',
+								matchingPolicies[0],
+								ctx.options
+							)
+						: null;
+
+					if (latestPolicy) {
+						return latestPolicy;
+					}
+
+					// Generate policy content and hash
+					const { content: defaultContent, contentHash } =
+						generatePolicyPlaceholder(name, now);
+
+					return txRegistry.createConsentPolicy({
+						version: '1.0.0',
+						name: normalizedSearchName,
+						effectiveDate: now,
+						content: defaultContent,
+						contentHash,
+						isActive: true,
+						updatedAt: now,
+						expirationDate: null,
+					});
+				},
+			});
+		},
+	};
+
+	return registry;
+}

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

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+
+/**
+ * Zod schema for validating consent policy entities.
+ *
+ * This defines the structure and validation rules for consent policy records:
+ * - Required fields: version, name, effectiveDate, content, contentHash
+ * - Optional fields: expirationDate
+ * - Default value of true for isActive
+ * - Default current date/time for creation and update timestamps
+ *
+ * @example
+ * ```typescript
+ * const policyData = {
+ *   id: 'pol_w5qufx2a66m7xkn3ty',
+ *   version: '1.0.0',
+ *   name: 'Privacy Policy 2023',
+ *   effectiveDate: new Date(),
+ *   content: 'Full policy text...',
+ *   contentHash: 'sha256-hash-of-content'
+ * };
+ *
+ * // Validate and parse the policy data
+ * const validPolicy = consentPolicySchema.parse(policyData);
+ * ```
+ */
+export const consentPolicySchema = z.object({
+	id: z.string(),
+	version: z.string(),
+	name: z.string(),
+	effectiveDate: z.date(),
+	expirationDate: z.date().nullable().optional(),
+	content: z.string(),
+	contentHash: z.string(),
+	isActive: z.boolean().default(true),
+	createdAt: z.date().default(() => new Date()),
+	updatedAt: z.date().default(() => new Date()),
+});
+
+/**
+ * Type definition for ConsentPolicy
+ *
+ * This type represents the structure of a consent policy record
+ * as defined by the consentPolicySchema. It includes all fields
+ * that are part of the consent policy entity.
+ */
+export type ConsentPolicy = z.infer<typeof consentPolicySchema>;

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

@@ -0,0 +1,141 @@
+import type { Field } from '~/db/core/fields';
+import type { C15TOptions } from '~/types';
+import { consentPolicySchema } from './schema';
+
+/**
+ * Generates the database table configuration for the consent policy entity.
+ *
+ * This function creates a schema definition that includes all standard consent policy 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 policy table customizations
+ * @param policyFields - Additional fields from plugins to include in the policy table
+ * @returns A complete table schema definition with fields, model name, and metadata
+ *
+ * @example
+ * ```typescript
+ * const policyTableSchema = getConsentPolicyTable(c15tOptions);
+ * // Use the schema for migrations or data access
+ * const migrationPlans = generateMigrations(policyTableSchema);
+ * ```
+ */
+export function getConsentPolicyTable(
+	options: C15TOptions,
+	policyFields?: Record<string, Field>
+) {
+	const consentPolicyConfig = options.tables?.consentPolicy;
+
+	return {
+		/**
+		 * The name of the policy table in the database, configurable through options
+		 */
+		entityName: consentPolicyConfig?.entityName || 'consentPolicy',
+
+		/**
+		 * The ID prefix for the consent policy table
+		 * Used to generate unique prefixed IDs for consent policies
+		 */
+		entityPrefix: consentPolicyConfig?.entityPrefix || 'pol',
+
+		/**
+		 * The schema for the consent policy table
+		 */
+		schema: consentPolicySchema,
+
+		/**
+		 * Field definitions for the consent policy table
+		 */
+		fields: {
+			/**
+			 * Version identifier for the policy (e.g., "1.0.0")
+			 */
+			version: {
+				type: 'string',
+				required: true,
+				fieldName: consentPolicyConfig?.fields?.version || 'version',
+			},
+
+			/**
+			 * Human-readable name of the policy
+			 */
+			name: {
+				type: 'string',
+				required: true,
+				fieldName: consentPolicyConfig?.fields?.name || 'name',
+			},
+
+			/**
+			 * Date when the policy becomes effective
+			 */
+			effectiveDate: {
+				type: 'date',
+				required: true,
+				fieldName:
+					consentPolicyConfig?.fields?.effectiveDate || 'effectiveDate',
+			},
+
+			/**
+			 * Optional date when the policy expires
+			 */
+			expirationDate: {
+				type: 'date',
+				required: false,
+				fieldName:
+					consentPolicyConfig?.fields?.expirationDate || 'expirationDate',
+			},
+
+			/**
+			 * Full content of the policy document
+			 */
+			content: {
+				type: 'string',
+				required: true,
+				fieldName: consentPolicyConfig?.fields?.content || 'content',
+			},
+
+			/**
+			 * Hash of the content for integrity validation
+			 */
+			contentHash: {
+				type: 'string',
+				required: true,
+				fieldName: consentPolicyConfig?.fields?.contentHash || 'contentHash',
+			},
+
+			/**
+			 * Whether this policy is currently active
+			 * Default: true
+			 */
+			isActive: {
+				type: 'boolean',
+				defaultValue: true,
+				required: true,
+				fieldName: consentPolicyConfig?.fields?.isActive || 'isActive',
+			},
+
+			/**
+			 * When the policy record was created
+			 * Automatically set to current time by default
+			 */
+			createdAt: {
+				type: 'date',
+				defaultValue: () => new Date(),
+				required: true,
+				fieldName: consentPolicyConfig?.fields?.createdAt || 'createdAt',
+			},
+
+			// Include additional fields from plugins
+			...(policyFields || {}),
+
+			// Include additional fields from configuration
+			...(consentPolicyConfig?.additionalFields || {}),
+		},
+
+		/**
+		 * Execution order during migrations (lower numbers run first)
+		 * Policy table needs to be created before tables that reference it (like consent)
+		 */
+		order: 2,
+	};
+}

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

@@ -0,0 +1,28 @@
+import type { BaseEntityConfig } from '../types';
+
+/**
+ * Consent policy entity configuration
+ * @default entityName: "consentPolicy", entityPrefix: "pol"
+ */
+export interface ConsentPolicyEntityConfig extends BaseEntityConfig {
+	fields?: Record<string, string> & {
+		id?: string;
+		version?: string;
+		name?: string;
+		/**
+		 * ISO format date string (e.g., "2024-04-15T00:00:00Z")
+		 */
+		effectiveDate?: string;
+		/**
+		 * ISO format date string (e.g., "2024-04-15T00:00:00Z")
+		 */
+		expirationDate?: string;
+		content?: string;
+		contentHash?: string;
+		isActive?: string;
+		/**
+		 * ISO format date string (e.g., "2024-04-15T00:00:00Z")
+		 */
+		createdAt?: string;
+	};
+}

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

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