@c15t/backend 1.8.0 → 2.0.0-rc.0

package/src/schema/index.ts

@@ -1,74 +0,0 @@
-/**
- * Schema Module for c15t Consent Management System
- *
- * This module serves as the central hub for database schema definitions, validation,
- * and transformation utilities used throughout the c15t system. It defines the structure
- * of all database tables and provides tools to work with schema-compliant data.
- *
- * @remarks
- * The Schema Module is organized into three main components:
- *
- * 1. Table Definitions - Individual table schemas (subject, consent, consentPurpose, etc.)
- * 2. Schema Utilities - Functions for retrieving and working with the complete schema
- * 3. Data Parsing - Validation and transformation of input/output data
- *
- * These components work together to provide a type-safe, consistent interface for
- * interacting with the database, regardless of which database adapter is used.
- *
- * @example
- * ```typescript
- * import {
- *   getConsentTables,
- *   parseInputData,
- *   type C15TDBSchema
- * } from '@c15t/backend/schema';
- *
- * // Get the complete schema
- * const tables = getConsentTables(options);
- *
- * // Validate input data against the subject table schema
- * const validSubjectData = parseInputData(
- *   inputData,
- *   { fields: tables.subject.fields }
- * );
- * ```
- */
-
-// Table Definition Exports
-/**
- * Table definitions for core c15t entities
- *
- * These exports provide the schema definitions for each table in the c15t database.
- * Each table definition includes field specifications, relationships, and metadata.
- */
-export * from './audit-log';
-export * from './consent';
-export * from './consent-policy';
-export * from './consent-purpose';
-export * from './consent-record';
-// Schema Utility Exports
-/**
- * Schema utilities for working with the complete database schema
- *
- * These exports provide functions for retrieving the complete schema and
- * working with table definitions at a higher level.
- *
- * @see {@link getConsentTables} - Main function to get the complete schema
- * @see {@link C15TDBSchema} - Type representing the complete database schema
- */
-export { type C15TDBSchema, getConsentTables } from './definition';
-export * from './domain';
-// Schemas export
-export * from './schemas';
-export * from './subject';
-// Schema Type Exports
-/**
- * Type definitions for database schema configuration
- *
- * These exports provide interfaces for configuring database entities
- * and are used throughout the application for type-safe schema definition.
- *
- * @see {@link BaseEntityConfig} - Base configuration for all entities
- * @see {@link TablesConfig} - Configuration for all database tables
- */
-export * from './types';

package/src/schema/schemas.ts

@@ -1,27 +0,0 @@
-import type { z } from 'zod';
-import {
-	auditLogSchema,
-	consentPolicySchema,
-	consentRecordSchema,
-	consentSchema,
-	domainSchema,
-	purposeSchema,
-	subjectSchema,
-} from './index';
-
-// Export all schemas
-export const schemas = {
-	auditLog: auditLogSchema,
-	consent: consentSchema,
-	consentPolicy: consentPolicySchema,
-	consentPurpose: purposeSchema,
-	consentRecord: consentRecordSchema,
-	domain: domainSchema,
-	subject: subjectSchema,
-} as const;
-
-// Type for all table names
-export type TableName = keyof typeof schemas;
-
-// Type for inferring the shape of any table
-export type InferTableShape<T extends TableName> = z.infer<(typeof schemas)[T]>;

package/src/schema/subject/index.ts

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

package/src/schema/subject/registry.ts

@@ -1,298 +0,0 @@
-import { getWithHooks } from '~/pkgs/data-model';
-import { DoubleTieError, ERROR_CODES } from '~/pkgs/results';
-import type { GenericEndpointContext, RegistryContext } from '~/pkgs/types';
-
-import { validateEntityOutput } from '../definition';
-import type { Subject } from './schema';
-
-/**
- * Creates and returns a set of subject-related adapter methods to interact with the database.
- *
- * These methods provide a consistent interface for creating and finding
- * subject 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 subject operations
- *
- * @example
- * ```typescript
- * const subjectAdapter = createSubjectAdapter(
- *   databaseAdapter,
- *   createWithHooks,
- *   c15tOptions
- * );
- *
- * // Create a new subject
- * const subject = await subjectAdapter.createSubject({
- *   externalId: 'external-123',
- *   identityProvider: 'auth0'
- * });
- * ```
- */
-export function subjectRegistry({ adapter, ...ctx }: RegistryContext) {
-	const { createWithHooks } = getWithHooks(adapter, ctx);
-
-	return {
-		/**
-		 * Creates a new subject record in the database.
-		 *
-		 * Automatically sets creation and update timestamps and applies any
-		 * configured hooks during the creation process.
-		 *
-		 * @param subject - Subject data to create (without id and timestamps)
-		 * @param context - Optional endpoint context for hooks
-		 * @returns The created subject with all fields populated
-		 *
-		 * @throws May throw an error if hooks prevent creation or if database operations fail
-		 */
-		createSubject: async (
-			subject: Omit<Subject, 'id' | 'createdAt' | 'updatedAt'> &
-				Partial<Subject>,
-			context?: GenericEndpointContext
-		) => {
-			const createdSubject = await createWithHooks({
-				data: {
-					createdAt: new Date(),
-					updatedAt: new Date(),
-					...subject,
-				},
-				model: 'subject',
-				customFn: undefined,
-				context,
-			});
-			return createdSubject
-				? validateEntityOutput('subject', createdSubject, ctx.options)
-				: null;
-		},
-
-		/**
-		 * Finds an existing subject or creates a new one if needed.
-		 * If both subjectId and externalSubjectId are provided, validates they match the same subject.
-		 * Creates a new anonymous subject only if no identifiers are provided.
-		 *
-		 * @param params - Parameters for finding or creating the subject
-		 * @returns The existing or newly created subject
-		 * @throws APIError if subject validation fails or creation fails
-		 */
-		findOrCreateSubject: async function ({
-			subjectId,
-			externalSubjectId,
-			identityProvider,
-			ipAddress = 'unknown',
-			context,
-		}: {
-			subjectId?: string;
-			externalSubjectId?: string;
-			identityProvider?: string;
-			ipAddress?: string;
-			context?: GenericEndpointContext;
-		}) {
-			// If both subjectId and externalSubjectId are provided, validate they match
-			if (subjectId && externalSubjectId) {
-				const [subjectById, subjectByExternalId] = await Promise.all([
-					this.findSubjectById(subjectId),
-					this.findSubjectByExternalId(externalSubjectId),
-				]);
-
-				if (!subjectById || !subjectByExternalId) {
-					ctx.logger?.error(
-						'Subject validation failed: One or both subjects not found',
-						{
-							providedSubjectId: subjectId,
-							providedExternalId: externalSubjectId,
-							subjectByIdFound: !!subjectById,
-							subjectByExternalIdFound: !!subjectByExternalId,
-						}
-					);
-					throw new DoubleTieError(
-						'The specified subject could not be found. Please verify the subject identifiers and try again.',
-						{
-							code: ERROR_CODES.NOT_FOUND,
-							status: 404,
-							meta: {
-								providedSubjectId: subjectId,
-								providedExternalId: externalSubjectId,
-							},
-						}
-					);
-				}
-
-				if (subjectById.id !== subjectByExternalId.id) {
-					ctx.logger?.warn(
-						'Subject validation failed: IDs do not match the same subject',
-						{
-							providedSubjectId: subjectId,
-							providedExternalId: externalSubjectId,
-							subjectByIdId: subjectById.id,
-							subjectByExternalIdId: subjectByExternalId.id,
-						}
-					);
-
-					throw new DoubleTieError(
-						'The provided subjectId and externalSubjectId do not match the same subject. Please ensure both identifiers refer to the same subject.',
-						{
-							code: ERROR_CODES.CONFLICT,
-							status: 409,
-							meta: {
-								providedSubjectId: subjectId,
-								providedExternalId: externalSubjectId,
-								subjectByIdId: subjectById.id,
-								subjectByExternalIdId: subjectByExternalId.id,
-							},
-						}
-					);
-				}
-
-				return subjectById;
-			}
-
-			// Try to find subject by subjectId if provided
-			if (subjectId) {
-				const subject = await this.findSubjectById(subjectId);
-				if (subject) {
-					return subject;
-				}
-				throw new DoubleTieError('Subject not found by subjectId', {
-					code: ERROR_CODES.NOT_FOUND,
-					status: 404,
-				});
-			}
-
-			// If externalSubjectId provided, try to find or create with upsert
-			if (externalSubjectId) {
-				try {
-					const subject = await this.findSubjectByExternalId(externalSubjectId);
-					if (subject) {
-						ctx.logger?.debug('Found existing subject by external ID', {
-							externalSubjectId,
-						});
-						return subject;
-					}
-
-					ctx.logger?.info('Creating new subject with external ID', {
-						externalSubjectId,
-					});
-					// Attempt to create with unique constraint on externalId
-					return await this.createSubject(
-						{
-							externalId: externalSubjectId,
-							identityProvider: identityProvider ?? 'external',
-							lastIpAddress: ipAddress,
-							isIdentified: true,
-						},
-						context
-					);
-				} catch (error) {
-					// If creation failed due to duplicate, try to find again
-					if (
-						error instanceof Error &&
-						error.message.includes('unique constraint')
-					) {
-						ctx.logger?.info(
-							'Handling duplicate key violation for external ID',
-							{ externalSubjectId }
-						);
-						const subject =
-							await this.findSubjectByExternalId(externalSubjectId);
-						if (subject) {
-							return subject;
-						}
-					}
-					ctx.logger?.error(
-						'Failed to create or find subject with external ID',
-						{
-							externalSubjectId,
-							error: error instanceof Error ? error.message : 'Unknown error',
-						}
-					);
-					throw new DoubleTieError(
-						'Failed to create or find subject with external ID',
-						{
-							code: ERROR_CODES.INTERNAL_SERVER_ERROR,
-							status: 500,
-							meta: {
-								error: error instanceof Error ? error.message : 'Unknown error',
-							},
-						}
-					);
-				}
-			}
-
-			// For anonymous subjects, use a transaction to prevent duplicates
-			try {
-				ctx.logger?.info('Creating new anonymous subject');
-				return await this.createSubject(
-					{
-						externalId: null,
-						identityProvider: 'anonymous',
-						lastIpAddress: ipAddress,
-						isIdentified: false,
-					},
-					context
-				);
-			} catch (error) {
-				ctx.logger?.error('Failed to create anonymous subject', {
-					ipAddress,
-					error: error instanceof Error ? error.message : 'Unknown error',
-				});
-				throw new DoubleTieError('Failed to create anonymous subject', {
-					code: ERROR_CODES.INTERNAL_SERVER_ERROR,
-					status: 500,
-					meta: {
-						error: error instanceof Error ? error.message : 'Unknown error',
-					},
-				});
-			}
-		},
-
-		/**
-		 * Finds a subject by their unique ID.
-		 *
-		 * Returns the subject with processed output fields according to the schema configuration.
-		 *
-		 * @param subjectId - The unique identifier of the subject
-		 * @returns The subject object if found, null otherwise
-		 */
-		findSubjectById: async (subjectId: string) => {
-			const subject = await adapter.findOne({
-				model: 'subject',
-				where: [
-					{
-						field: 'id',
-						value: subjectId,
-					},
-				],
-			});
-
-			return subject
-				? validateEntityOutput('subject', subject, ctx.options)
-				: null;
-		},
-
-		/**
-		 * Finds a subject by their external ID.
-		 *
-		 * This is useful when integrating with external authentication systems
-		 * where subjects are identified by a provider-specific ID.
-		 *
-		 * @param externalId - The external identifier of the subject
-		 * @returns The subject object if found, null otherwise
-		 */
-		findSubjectByExternalId: async (externalId: string) => {
-			const subject = await adapter.findOne({
-				model: 'subject',
-				where: [
-					{
-						field: 'externalId',
-						value: externalId,
-					},
-				],
-			});
-
-			return subject
-				? validateEntityOutput('subject', subject, ctx.options)
-				: null;
-		},
-	};
-}

package/src/schema/subject/schema.ts

@@ -1,41 +0,0 @@
-import { z } from 'zod';
-
-/**
- * Zod schema for validating subject entities.
- *
- * This defines the structure and validation rules for subject records:
- * - Requires a valid UUID for the ID field
- * - Default value of false for isIdentified
- * - Optional fields for externalId, identityProvider, and lastIpAddress
- * - Default current date/time for creation and update timestamps
- *
- * @example
- * ```typescript
- * const subjectData = {
- *   id: 'sub_x1pftyoufsm7xgo1kv',
- *   externalId: 'ext-123',
- *   isIdentified: true
- * };
- *
- * // Validate and parse the subject data
- * const validSubject = subjectSchema.parse(subjectData);
- * ```
- */
-export const subjectSchema = z.object({
-	id: z.string(),
-	isIdentified: z.boolean().prefault(false),
-	externalId: z.string().nullable().optional(),
-	identityProvider: z.string().optional(),
-	lastIpAddress: z.string().optional(),
-	createdAt: z.date().prefault(() => new Date()),
-	updatedAt: z.date().prefault(() => new Date()),
-});
-
-/**
- * Type definition for Subject
- *
- * This type represents the structure of a subject record
- * as defined by the subjectSchema. It includes all fields
- * that are part of the subject entity.
- */
-export type Subject = z.infer<typeof subjectSchema>;

package/src/schema/subject/table.ts

@@ -1,138 +0,0 @@
-import { COMMON_TIMEZONES, type Field } from '~/pkgs/data-model';
-import type { C15TOptions } from '~/types';
-import { subjectSchema } from './schema';
-
-/**
- * Generates the database table configuration for the subject entity.
- *
- * This function creates a schema definition that includes all standard subject 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 subject table customizations
- * @param subjectFields - Additional fields from plugins to include in the subject table
- * @returns A complete table schema definition with fields, model name, and metadata
- *
- * @example
- * ```typescript
- * const subjectTableSchema = getSubjectTable(c15tOptions);
- * // Use the schema for migrations or data access
- * const migrationPlans = generateMigrations(subjectTableSchema);
- * ```
- */
-export function getSubjectTable(
-	options: C15TOptions,
-	subjectFields?: Record<string, Field>
-) {
-	// Get subject config, supporting both the new tables.subject and legacy subject format
-	const subjectConfig = options.tables?.subject;
-
-	return {
-		/**
-		 * The name of the subject table in the database, configurable through options
-		 */
-		entityName: subjectConfig?.entityName || 'subject',
-
-		/**
-		 * The ID prefix for the subject table
-		 * Used to generate unique prefixed IDs for subjects
-		 */
-		entityPrefix: subjectConfig?.entityPrefix || 'sub',
-
-		/**
-		 * The Zod schema for the subject table
-		 */
-		schema: subjectSchema,
-
-		/**
-		 * Field definitions for the subject table
-		 */
-		fields: {
-			/**
-			 * Whether the subject has been identified/verified
-			 * Default: false
-			 */
-			isIdentified: {
-				type: 'boolean',
-				defaultValue: () => false,
-				required: true,
-				fieldName: subjectConfig?.fields?.isIdentified || 'isIdentified',
-			},
-
-			/**
-			 * External identifier for the subject (from auth providers)
-			 * Optional field
-			 */
-			externalId: {
-				type: 'string',
-				required: false,
-				fieldName: subjectConfig?.fields?.externalId || 'externalId',
-			},
-
-			/**
-			 * The provider that identified this subject (e.g., 'auth0', 'okta')
-			 * Optional field
-			 */
-			identityProvider: {
-				type: 'string',
-				required: false,
-				fieldName:
-					subjectConfig?.fields?.identityProvider || 'identityProvider',
-			},
-
-			/**
-			 * Last known IP address of the subject
-			 * Optional field, useful for security and audit purposes
-			 */
-			lastIpAddress: {
-				type: 'string',
-				required: false,
-				fieldName: subjectConfig?.fields?.lastIpAddress || 'lastIpAddress',
-			},
-
-			/**
-			 * When the subject was created
-			 * Automatically set to current time by default
-			 */
-			createdAt: {
-				type: 'date',
-				defaultValue: () => new Date(),
-				required: true,
-				fieldName: subjectConfig?.fields?.createdAt || 'createdAt',
-			},
-
-			/**
-			 * When the subject was last updated
-			 * Automatically set to current time on update
-			 */
-			updatedAt: {
-				type: 'date',
-				defaultValue: () => new Date(),
-				required: true,
-				fieldName: subjectConfig?.fields?.updatedAt || 'updatedAt',
-			},
-
-			/**
-			 * Subject's local timezone, stored as IANA timezone identifier
-			 */
-			subjectTimezone: {
-				type: 'timezone',
-				required: false,
-				defaultValue: COMMON_TIMEZONES.UTC,
-				fieldName: subjectConfig?.fields?.subjectTimezone || 'subjectTimezone',
-			},
-
-			// Include additional fields from plugins
-			...(subjectFields || {}),
-
-			// Include additional fields from configuration
-			...(subjectConfig?.additionalFields || {}),
-		},
-
-		/**
-		 * Execution order during migrations (lower numbers run first)
-		 * Subject table needs to be created early as other tables reference it
-		 */
-		order: 1,
-	};
-}

package/src/schema/subject/types.ts

@@ -1,22 +0,0 @@
-/**
- * Subject Entity Type Definitions
- *
- * This module contains type definitions specific to the subject entity.
- */
-import type { TimestampedEntityConfig } from '../types';
-
-/**
- * Subject entity configuration
- * @default entityName: "subject", entityPrefix: "sub"
- */
-export interface SubjectEntityConfig extends TimestampedEntityConfig {
-	fields?: Record<string, string> & {
-		id?: string;
-		isIdentified?: string;
-		externalId?: string;
-		identityProvider?: string;
-		lastIpAddress?: string;
-		createdAt?: string;
-		updatedAt?: string;
-	};
-}