@c15t/backend 1.8.0 → 2.0.0-rc.0

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

@@ -1,352 +0,0 @@
-import { getWithHooks } from '~/pkgs/data-model';
-import type { Where } from '~/pkgs/db-adapters';
-import { DoubleTieError, ERROR_CODES } from '~/pkgs/results';
-import type { GenericEndpointContext, RegistryContext } from '~/pkgs/types';
-import { validateEntityOutput } from '../definition';
-import type { ConsentPolicy, PolicyType } from './schema';
-
-/**
- * Generates placeholder content for a policy with its hash.
- *
- * Creates standardized temporary content for a consent policy, which includes a warning
- * that it should be replaced with actual policy terms. Also generates a SHA-256 hash
- * of this content for integrity verification.
- *
- * @param name - Policy name to include in the placeholder text
- * @param date - Generation date to include in the placeholder text
- * @returns Object containing the generated placeholder content and its SHA-256 hash
- * @returns {Object} result - Result object
- * @returns {string} result.content - Generated placeholder content
- * @returns {string} result.contentHash - SHA-256 hash of the generated content
- *
- * @example
- * ```ts
- * const { content, contentHash } = generatePolicyPlaceholder('Privacy Policy', new Date());
- * console.log(content); // "[PLACEHOLDER] This is an automatically generated version..."
- * console.log(contentHash); // "a1b2c3d4..." (SHA-256 hash)
- * ```
- *
- * @internal Used by findOrCreatePolicy to initialize placeholder content
- */
-async 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()}`;
-
-	let contentHash: string;
-	try {
-		// Use Web Crypto API which is available in both browsers and edge environments
-		const encoder = new TextEncoder();
-		const data = encoder.encode(content);
-		const hashBuffer = await crypto.subtle.digest('SHA-256', data);
-		contentHash = Array.from(new Uint8Array(hashBuffer))
-			.map((b) => b.toString(16).padStart(2, '0'))
-			.join('');
-	} catch (error) {
-		throw new DoubleTieError('Failed to generate policy content hash', {
-			code: ERROR_CODES.INTERNAL_SERVER_ERROR,
-			status: 500,
-			cause: error instanceof Error ? error : new Error(String(error)),
-		});
-	}
-
-	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.
- *
- * The returned registry object contains methods for common operations on consent policies,
- * including creation, retrieval, and conditional creation. All methods validate their
- * inputs and outputs according to the schema configuration.
- *
- * @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 policy operations
- *
- * @example
- * ```typescript
- * const registry = policyRegistry({
- *   adapter: databaseAdapter,
- *   hooks: customHooks,
- *   options: validationOptions
- * });
- *
- * // Use the registry methods
- * const policy = await registry.findOrCreatePolicy('privacy');
- * ```
- *
- * @see {@link RegistryContext} For details on the context parameters
- * @see {@link ConsentPolicy} For the structure of policy objects
- */
-export function policyRegistry({ adapter, ...ctx }: RegistryContext) {
-	const { createWithHooks } = 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.
-		 *
-		 * This method validates the provided policy data, assigns a creation timestamp,
-		 * and stores it in the database. It uses the configured hooks system to allow
-		 * for customization of the creation process.
-		 *
-		 * @param policy - Policy data to create (without id and timestamp)
-		 * @param context - Optional endpoint context for hooks execution
-		 * @returns Promise resolving to the created policy 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 database operations fail
-		 *
-		 * @example
-		 * ```ts
-		 * const newPolicy = await policyRegistry.createConsentPolicy({
-		 *   version: '1.0.0',
-		 *   type: 'privacy',
-		 *   name: 'Privacy Policy',
-		 *   effectiveDate: new Date(),
-		 *   content: 'Full policy text...',
-		 *   contentHash: 'sha256-hash-of-content',
-		 *   isActive: true,
-		 *   updatedAt: new Date(),
-		 *   expirationDate: null
-		 * });
-		 * ```
-		 *
-		 * @see {@link ConsentPolicy} For the structure of the policy object
-		 * @see {@link GenericEndpointContext} For details on the context object
-		 */
-		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 DoubleTieError(
-					'Failed to create consent policy - operation returned null',
-					{
-						code: ERROR_CODES.INTERNAL_SERVER_ERROR,
-						status: 500,
-					}
-				);
-			}
-
-			return createdPolicy as ConsentPolicy;
-		},
-
-		/**
-		 * Retrieves consent policies from the database based on provided filter parameters.
-		 *
-		 * This method queries the database for consent policies matching the specified criteria.
-		 * By default, only active policies are returned unless specifically requested otherwise.
-		 * Results are sorted by effective date in descending order (newest first).
-		 *
-		 * @param params - Optional parameters to filter the policies
-		 * @param params.domainId - Optional domain identifier to filter policies by domain
-		 * @param params.version - Optional version string to filter policies by specific version
-		 * @param params.includeInactive - When true, includes inactive policies in the results
-		 * @returns Promise resolving to an array of validated consent policy objects
-		 *
-		 * @example
-		 * ```ts
-		 * // Get all active policies
-		 * const activePolicies = await policyRegistry.findPolicies();
-		 *
-		 * // Get all policies including inactive ones
-		 * const allPolicies = await policyRegistry.findPolicies({ includeInactive: true });
-		 *
-		 * // Get active policies for a specific version
-		 * const specificVersionPolicies = await policyRegistry.findPolicies({
-		 *   version: '2.0.0'
-		 * });
-		 * ```
-		 *
-		 * @see {@link ConsentPolicy} For the structure of returned policy objects
-		 */
-		findPolicies: async (
-			params: {
-				domainId?: string;
-				version?: string;
-				includeInactive?: boolean;
-			} = {}
-		) => {
-			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)
-			);
-		},
-
-		/**
-		 * Finds a consent policy by its unique ID.
-		 * Returns the policy with processed output fields according to the schema configuration.
-		 *
-		 * This method queries the database for a single consent policy that matches the provided ID.
-		 * The resulting policy is validated against the schema before being returned.
-		 *
-		 * @param policyId - The unique identifier of the policy to find
-		 * @returns Promise resolving to the validated policy object if found, null otherwise
-		 *
-		 * @example
-		 * ```ts
-		 * // Find a policy by ID
-		 * const policy = await policyRegistry.findConsentPolicyById('policy-123');
-		 * if (policy) {
-		 *   console.log(`Found policy: ${policy.name}, version ${policy.version}`);
-		 * } else {
-		 *   console.log('Policy not found');
-		 * }
-		 * ```
-		 *
-		 * @see {@link ConsentPolicy} For the structure of the returned policy object
-		 */
-		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 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 type 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 type - The type of the policy to find/create (e.g., 'privacy', 'terms')
-		 * @returns Promise resolving to the found or newly created policy object
-		 * @throws {Error} If the database transaction fails to complete
-		 *
-		 * @example
-		 * ```ts
-		 * // Find or create a privacy policy
-		 * const privacyPolicy = await policyRegistry.findOrCreatePolicy('privacy');
-		 *
-		 * // Find or create a terms of service policy
-		 * const termsPolicy = await policyRegistry.findOrCreatePolicy('terms');
-		 * ```
-		 *
-		 * @see {@link PolicyType} For the available policy types
-		 * @see {@link ConsentPolicy} For the structure of the returned policy object
-		 * @see {@link generatePolicyPlaceholder} For details on how placeholder content is generated
-		 */
-		findOrCreatePolicy: async (type: PolicyType) => {
-			// Use a transaction to prevent race conditions
-			return await adapter.transaction({
-				callback: async (txAdapter) => {
-					try {
-						const now = new Date();
-						const txRegistry = policyRegistry({
-							adapter: txAdapter,
-							...ctx,
-						});
-
-						// Find latest policy with exact name match directly from database
-						const rawLatestPolicy = await txAdapter.findOne({
-							model: 'consentPolicy',
-							where: [
-								{ field: 'isActive', value: true },
-								{
-									field: 'type',
-									value: type,
-								},
-							],
-							sortBy: {
-								field: 'effectiveDate',
-								direction: 'desc',
-							},
-						});
-
-						const latestPolicy = rawLatestPolicy
-							? validateEntityOutput(
-									'consentPolicy',
-									rawLatestPolicy,
-									ctx.options
-								)
-							: null;
-
-						if (latestPolicy) {
-							return latestPolicy;
-						}
-
-						// Generate policy content and hash
-						const { content: defaultContent, contentHash } =
-							await generatePolicyPlaceholder(type, now);
-
-						return txRegistry.createConsentPolicy({
-							version: '1.0.0',
-							type,
-							name: type,
-							effectiveDate: now,
-							content: defaultContent,
-							contentHash,
-							isActive: true,
-							updatedAt: now,
-							expirationDate: null,
-						});
-					} catch (error) {
-						// Log the error for debugging purposes
-						ctx.logger.error('Error in findOrCreatePolicy transaction:', error);
-
-						// Rethrow as a DoubleTieError with appropriate context
-						throw new DoubleTieError('Failed to find or create policy', {
-							code: ERROR_CODES.INTERNAL_SERVER_ERROR,
-							status: 500,
-							cause: error instanceof Error ? error : new Error(String(error)),
-						});
-					}
-				},
-			});
-		},
-	};
-
-	return registry;
-}

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

@@ -1,60 +0,0 @@
-import { z } from 'zod';
-
-export const PolicyTypeSchema = z.enum([
-	'cookie_banner',
-	'privacy_policy',
-	'dpa',
-	'terms_and_conditions',
-	'marketing_communications',
-	'age_verification',
-	'other',
-]);
-
-export type PolicyType = z.infer<typeof PolicyTypeSchema>;
-
-/**
- * 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(),
-	type: PolicyTypeSchema,
-	name: z.string(),
-	effectiveDate: z.date(),
-	expirationDate: z.date().nullable().optional(),
-	content: z.string(),
-	contentHash: z.string(),
-	isActive: z.boolean().prefault(true),
-	createdAt: z.date().prefault(() => new Date()),
-	updatedAt: z.date().prefault(() => 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/schema/consent-policy/table.ts

@@ -1,150 +0,0 @@
-import type { Field } from '~/pkgs/data-model';
-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',
-			},
-
-			/**
-			 * Type of the policy
-			 */
-			type: {
-				type: 'string',
-				required: true,
-				fieldName: consentPolicyConfig?.fields?.type || 'type',
-			},
-
-			/**
-			 * 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/schema/consent-policy/types.ts

@@ -1,29 +0,0 @@
-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;
-		type?: string;
-		/**
-		 * ISO format date string (e.g., "2024-04-15T00:00:00Z")
-		 */
-		effectiveDate?: Date;
-		/**
-		 * ISO format date string (e.g., "2024-04-15T00:00:00Z")
-		 */
-		expirationDate?: Date;
-		content?: string;
-		contentHash?: string;
-		isActive?: string;
-		/**
-		 * ISO format date string (e.g., "2024-04-15T00:00:00Z")
-		 */
-		createdAt?: string;
-	};
-}

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

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