@c15t/backend 0.0.1-rc.10

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

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

package/src/db/schema/subject/registry.ts

@@ -0,0 +1,371 @@
+import type { Adapter } from '~/db/adapters/types';
+import { getWithHooks } from '~/db/hooks';
+import { BASE_ERROR_CODES, C15TError } from '~/error';
+import type { GenericEndpointContext, RegistryContext } from '~/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, finding, updating, and deleting
+ * 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,
+ *   updateWithHooks,
+ *   c15tOptions
+ * );
+ *
+ * // Create a new subject
+ * const subject = await subjectAdapter.createSubject({
+ *   externalId: 'external-123',
+ *   identityProvider: 'auth0'
+ * });
+ * ```
+ */
+export function subjectRegistry({ adapter, ...ctx }: RegistryContext) {
+	const { createWithHooks, updateWithHooks } = 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,
+			ipAddress = 'unknown',
+			context,
+		}: {
+			subjectId?: string;
+			externalSubjectId?: 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?.info(
+						'Subject validation failed: One or both subjects not found',
+						{
+							providedSubjectId: subjectId,
+							providedExternalId: externalSubjectId,
+							subjectByIdFound: !!subjectById,
+							subjectByExternalIdFound: !!subjectByExternalId,
+						}
+					);
+					throw new C15TError(
+						'The specified subject could not be found. Please verify the subject identifiers and try again.',
+						{
+							code: BASE_ERROR_CODES.NOT_FOUND,
+							status: 404,
+							data: {
+								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 C15TError(
+						'The provided subjectId and externalSubjectId do not match the same subject. Please ensure both identifiers refer to the same subject.',
+						{
+							code: BASE_ERROR_CODES.CONFLICT,
+							status: 409,
+							data: {
+								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 C15TError('Subject not found', {
+					code: BASE_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: '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 C15TError(
+						'Failed to create or find subject with external ID',
+						{
+							code: BASE_ERROR_CODES.INTERNAL_SERVER_ERROR,
+							status: 500,
+							data: {
+								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 C15TError('Failed to create anonymous subject', {
+					code: BASE_ERROR_CODES.INTERNAL_SERVER_ERROR,
+					status: 500,
+					data: {
+						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;
+		},
+
+		/**
+		 * Updates an existing subject record by ID.
+		 *
+		 * Applies any configured hooks during the update process and
+		 * processes the output according to schema configuration.
+		 *
+		 * @param subjectId - The unique identifier of the subject to update
+		 * @param data - The fields to update on the subject record
+		 * @param context - Optional endpoint context for hooks
+		 * @returns The updated subject if successful, null if subject not found or hooks prevented update
+		 */
+		updateSubject: async (
+			subjectId: string,
+			data: Partial<Subject> & Record<string, unknown>,
+			context?: GenericEndpointContext
+		) => {
+			const subject = await updateWithHooks({
+				data: {
+					...data,
+					updatedAt: new Date(),
+				},
+				where: [
+					{
+						field: 'id',
+						value: subjectId,
+					},
+				],
+				model: 'subject',
+				customFn: undefined,
+				context,
+			});
+			return subject
+				? validateEntityOutput('subject', subject, ctx.options)
+				: null;
+		},
+
+		/**
+		 * Soft deletes a subject and all associated consents from the database.
+		 *
+		 * This is a cascading operation that marks the subject as deleted by setting
+		 * its status to 'deleted' and removes all associated consent records.
+		 * The subject record itself remains in the database but is inactive.
+		 *
+		 * @param subjectId - The unique identifier of the subject to soft delete
+		 * @returns A promise that resolves when the soft deletion is complete
+		 */
+		deleteSubject: async (subjectId: string) => {
+			await adapter.transaction({
+				callback: async (tx: Adapter) => {
+					// Update the subject record
+					await tx.update({
+						model: 'subject',
+						where: [
+							{
+								field: 'id',
+								value: subjectId,
+							},
+						],
+						update: {
+							status: 'deleted',
+							updatedAt: new Date(),
+						},
+					});
+
+					// Delete all related records
+					await tx.deleteMany({
+						model: 'consent',
+						where: [
+							{
+								field: 'subjectId',
+								value: subjectId,
+							},
+						],
+					});
+				},
+			});
+		},
+	};
+}

package/src/db/schema/subject/schema.ts

@@ -0,0 +1,41 @@
+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().default(false),
+	externalId: z.string().nullable().optional(),
+	identityProvider: z.string().optional(),
+	lastIpAddress: z.string().optional(),
+	createdAt: z.date().default(() => new Date()),
+	updatedAt: z.date().default(() => 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/db/schema/subject/table.ts

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

@@ -0,0 +1,22 @@
+/**
+ * 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;
+	};
+}