@c15t/backend 1.8.0 → 2.0.0-rc.1

package/src/pkgs/types/plugins.ts

@@ -1,191 +0,0 @@
-import type { Migration } from 'kysely';
-import type { Field } from '~/pkgs/data-model';
-import type { DoubleTieContext, HookEndpointContext } from './context';
-import type { Endpoint, EndpointMiddleware } from './endpoints';
-import type { DeepPartial, LiteralString } from './helper';
-import type { DoubleTieMiddleware, DoubleTieOptions } from './options';
-
-/**
- * Context object provided to plugin hooks
- *
- * This extends the standard endpoint context with additional properties
- * specific to plugin hooks, such as the request path and geolocation data.
- */
-export interface PluginHookContext {
-	/**
-	 * The path of the current request
-	 */
-	path: string;
-}
-
-/**
- * Core DoubleTie plugin interface
- *
- * Defines the structure that all DoubleTie plugins must conform to,
- * including lifecycle methods, hooks, endpoints, and type information.
- */
-export interface DoubleTiePlugin {
-	/**
-	 * Unique identifier for the plugin
-	 * Must be a string literal for type safety
-	 */
-	id: LiteralString;
-
-	/**
-	 * Name of the plugin
-	 */
-	name: string;
-
-	/**
-	 * Type of plugin for classification and type guards
-	 */
-	type: string;
-
-	/**
-	 * The init function is called when the plugin is initialized.
-	 * You can return a new context or modify the existing context.
-	 *
-	 * @param ctx - The DoubleTie context
-	 * @returns An object with context or options modifications, or undefined
-	 */
-	init?: (ctx: DoubleTieContext) =>
-		| {
-				context?: DeepPartial<Omit<DoubleTieContext, 'options'>>;
-				options?: Partial<DoubleTieOptions>;
-		  }
-		| undefined;
-
-	/**
-	 * Custom API endpoints provided by this plugin
-	 * Each key is the endpoint name, and the value is the endpoint handler
-	 */
-	endpoints?: {
-		[key: string]: Endpoint;
-	};
-
-	/**
-	 * Middleware functions to process requests for specific paths
-	 */
-	middlewares?: {
-		path: string;
-		middleware: EndpointMiddleware;
-	}[];
-
-	/**
-	 * Handler for intercepting and potentially modifying incoming requests
-	 */
-	onRequest?: (request: Request, ctx: DoubleTieContext) => Promise<unknown>;
-
-	/**
-	 * Handler for intercepting and potentially modifying outgoing responses
-	 */
-	onResponse?: (response: Response, ctx: DoubleTieContext) => Promise<unknown>;
-
-	/**
-	 * Request lifecycle hooks for executing code before or after endpoint handling
-	 */
-	hooks?: {
-		/**
-		 * Hooks that run before the endpoint handler
-		 * Each hook has a matcher to determine when it should run
-		 */
-		before?: {
-			matcher: (context: HookEndpointContext) => boolean;
-			handler: DoubleTieMiddleware;
-		}[];
-
-		/**
-		 * Hooks that run after the endpoint handler has completed
-		 * Each hook has a matcher to determine when it should run
-		 */
-		after?: {
-			matcher: (context: HookEndpointContext) => boolean;
-			handler: DoubleTieMiddleware;
-		}[];
-	};
-
-	/**
-	 * Schema the plugin needs
-	 *
-	 * This will also be used to migrate the database. If the fields are dynamic from the plugins
-	 * configuration each time the configuration is changed a new migration will be created.
-	 *
-	 * NOTE: If you want to create migrations manually using
-	 * migrations option or any other way you
-	 * can disable migration per table basis.
-	 *
-	 * @example
-	 * ```ts
-	 * schema: {
-	 * 	subject: {
-	 * 		fields: {
-	 * 			email: {
-	 * 				 type: "string",
-	 * 			},
-	 * 			emailVerified: {
-	 * 				type: "boolean",
-	 * 				defaultValue: false,
-	 * 			},
-	 * 		},
-	 * 	}
-	 * } as AuthPluginSchema
-	 * ```
-	 */
-	schema?: DoubleTiePluginSchema;
-
-	/**
-	 * The migrations of the plugin. If you define schema that will automatically create
-	 * migrations for you.
-	 *
-	 * ⚠️ Only uses this if you dont't want to use the schema option and you disabled migrations for
-	 * the tables.
-	 */
-	migrations?: Record<string, Migration>;
-
-	/**
-	 * The options of the plugin
-	 */
-	options?: Record<string, unknown>;
-
-	/**
-	 * Types to be inferred by the type system
-	 * Used for type information in the plugin system
-	 */
-	$Infer?: Record<string, unknown>;
-
-	/**
-	 * The error codes returned by the plugin
-	 * Used for consistent error handling across the system
-	 */
-	$ERROR_CODES?: Record<string, string>;
-
-	/**
-	 * Type information for context extensions provided by this plugin
-	 * This will be used to properly type the context in hooks and methods
-	 */
-	$InferContext?: Record<string, unknown>;
-}
-
-/**
- * Plugin schema definition
- *
- * Defines the database schema extensions that a plugin may require.
- */
-export interface DoubleTiePluginSchema {
-	[tableName: string]: {
-		/**
-		 * Should migrations be created for this table when using auto migrations
-		 *
-		 * If you want to create migrations manually using the migrations
-		 * option or any other way you can disable migration per table.
-		 *
-		 * @default true
-		 */
-		createMigrations?: boolean;
-
-		/**
-		 * Fields to add to the table
-		 */
-		fields: Record<string, Field>;
-	};
-}

package/src/pkgs/utils/index.ts

@@ -1,3 +0,0 @@
-export { env, isProduction, isTest } from './env';
-export * from './logger';
-export { getBaseURL } from './url';

package/src/pkgs/utils/logger.ts

@@ -1,35 +0,0 @@
-import { createLogger, type LoggerOptions } from '@c15t/logger';
-
-let globalLogger: ReturnType<typeof createLogger>;
-
-/**
- * Gets or creates a global logger instance
- *
- * @param options - Optional logger configuration options
- * @returns The global logger instance
- */
-export function getLogger(
-	options?: LoggerOptions
-): ReturnType<typeof createLogger> {
-	if (!globalLogger) {
-		globalLogger = createLogger({
-			level: 'info',
-			appName: 'c15t',
-			...options,
-		});
-	}
-	return globalLogger;
-}
-
-/**
- * Initializes the global logger with specific options
- *
- * @param options - Logger configuration options
- * @returns The initialized global logger instance
- */
-export function initLogger(
-	options: LoggerOptions
-): ReturnType<typeof createLogger> {
-	globalLogger = createLogger(options);
-	return globalLogger;
-}

package/src/pkgs/utils/url.ts

@@ -1,105 +0,0 @@
-import { DoubleTieError, ERROR_CODES } from '~/pkgs/results';
-import { env } from './env';
-
-/**
- * Regular expression to match trailing slashes in URLs
- *
- * @internal
- */
-const TRAILING_SLASHES_REGEX = /\/+$/;
-
-/**
- * Checks if a URL contains a path component other than root
- *
- * @param url - The URL to check for path components
- * @returns Boolean indicating whether the URL has a non-root path
- *
- * @throws {DoubleTieError} When the provided URL is invalid
- *
- * @internal
- */
-function checkHasPath(url: string): boolean {
-	try {
-		const parsedUrl = new URL(url);
-		return parsedUrl.pathname !== '/';
-	} catch {
-		throw new DoubleTieError(
-			`Invalid base URL: ${url}. Please provide a valid base URL.`,
-			{
-				code: ERROR_CODES.BAD_REQUEST,
-				status: 400,
-				meta: {
-					url,
-				},
-			}
-		);
-	}
-}
-
-/**
- * Appends a path to a URL if it doesn't already have one
- *
- * This function ensures a URL has a path component by adding the
- * specified path if the URL only has a root path.
- *
- * @param url - The base URL to potentially add a path to
- * @param path - The path to append if needed (defaults to '/api/auth')
- * @returns The URL with the path component
- *
- * @throws {DoubleTieError} When the provided URL is invalid
- *
- * @internal
- */
-function withPath(url: string, path = '/api/auth') {
-	const hasPath = checkHasPath(url);
-	if (hasPath) {
-		return url;
-	}
-	const pathWithSlash = path.startsWith('/') ? path : `/${path}`;
-	return `${url.replace(TRAILING_SLASHES_REGEX, '')}${pathWithSlash}`;
-}
-
-/**
- * Determines the base URL for API requests
- *
- * Attempts to derive a base URL from multiple sources in the following order:
- * 1. The provided URL parameter
- * 2. Various environment variables
- * 3. Current window location (if in browser)
- *
- * @param url - Optional explicit URL to use
- * @param path - Optional path to append to the URL if it doesn't have one
- * @returns The determined base URL or undefined if unable to determine
- *
- * @throws {DoubleTieError} When the provided URL is invalid
- *
- * @example
- * ```ts
- * // Get the base URL with default path ('/api/auth')
- * const baseUrl = getBaseURL();
- *
- * // Get the base URL with custom path
- * const apiUrl = getBaseURL(undefined, '/api/v2');
- *
- * // Use an explicit URL
- * const customUrl = getBaseURL('https://example.com');
- * ```
- */
-export function getBaseURL(url?: string, path?: string) {
-	if (url) {
-		return withPath(url, path);
-	}
-	const fromEnv =
-		env.C15T_URL ||
-		env.NEXT_PUBLIC_C15T_URL ||
-		env.PUBLIC_C15T_URL ||
-		env.NUXT_PUBLIC_C15T_URL ||
-		env.NUXT_PUBLIC_AUTH_URL ||
-		(env.BASE_URL !== '/' ? env.BASE_URL : undefined);
-
-	if (fromEnv) {
-		return withPath(fromEnv, path);
-	}
-
-	return undefined;
-}

package/src/schema/audit-log/index.ts

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

package/src/schema/audit-log/registry.ts

@@ -1,117 +0,0 @@
-import { getWithHooks } from '~/pkgs/data-model';
-import { DoubleTieError, ERROR_CODES } from '~/pkgs/results';
-import type { GenericEndpointContext, RegistryContext } from '~/pkgs/types';
-
-import type { AuditLog } from './schema';
-
-/**
- * Creates and returns a set of audit log adapter methods to interact with the database.
- * These methods provide a consistent interface for creating and querying audit logs
- * while applying hooks and enforcing data validation rules.
- *
- * The audit log system tracks changes to entities in the system, providing a historical
- * record of modifications for compliance, debugging, and auditing purposes.
- *
- * @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 audit log operations
- *
- * @example
- * ```ts
- * const registry = auditLogRegistry({
- *   adapter: databaseAdapter,
- *   hooks: customHooks,
- *   options: validationOptions
- * });
- *
- * // Use the registry to create an audit log entry
- * const logEntry = await registry.createAuditLog({
- *   entityType: 'consent',
- *   entityId: 'cns_hadt8w7nngm7xmx2bn',
- *   actionType: 'update',
- *   subjectId: 'sub_x1pftyoufsm7xgo1kv',
- *   changes: { status: { from: 'active', to: 'withdrawn' } }
- * });
- * ```
- *
- * @see {@link RegistryContext} For details on the context parameters
- * @see {@link AuditLog} For the structure of audit log objects
- */
-export function auditLogRegistry({ adapter, ...ctx }: RegistryContext) {
-	const { createWithHooks } = getWithHooks(adapter, ctx);
-
-	return {
-		/**
-		 * Creates a new audit log entry in the database.
-		 *
-		 * This method records an action performed on an entity in the system,
-		 * capturing details such as what changed, who made the change, and when it occurred.
-		 * Automatically sets creation timestamp and applies any configured hooks during creation.
-		 *
-		 * @param auditLog - Audit log data to create (without id and timestamp)
-		 * @param auditLog.entityType - The type of entity being audited (e.g., 'consent', 'user')
-		 * @param auditLog.entityId - The unique identifier of the entity being audited
-		 * @param auditLog.actionType - The type of action performed (e.g., 'create', 'update', 'delete')
-		 * @param auditLog.subjectId - Identifier of the user/system that performed the action
-		 * @param auditLog.changes - Object describing the changes made to the entity
-		 * @param context - Optional endpoint context for hooks execution
-		 * @returns Promise resolving to the created audit log entry 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
-		 * // Record a consent being withdrawn
-		 * const withdrawalLog = await registry.createAuditLog({
-		 *   entityType: 'consent',
-		 *   entityId: 'cns_abc123',
-		 *   actionType: 'update',
-		 *   subjectId: 'user_xyz789',
-		 *   changes: {
-		 *     status: { from: 'active', to: 'withdrawn' },
-		 *     withdrawalReason: { from: null, to: 'Changed mind' }
-		 *   }
-		 * });
-		 *
-		 * // Record a new policy being created
-		 * const policyCreationLog = await registry.createAuditLog({
-		 *   entityType: 'policy',
-		 *   entityId: 'pol_def456',
-		 *   actionType: 'create',
-		 *   subjectId: 'admin_uvw321',
-		 *   changes: null // No previous state for creation
-		 * });
-		 * ```
-		 *
-		 * @see {@link AuditLog} For the complete structure of the audit log object
-		 * @see {@link GenericEndpointContext} For details on the context object
-		 */
-		createAuditLog: async (
-			auditLog: Omit<AuditLog, 'id' | 'createdAt'> & Partial<AuditLog>,
-			context?: GenericEndpointContext
-		) => {
-			const createdLog = await createWithHooks({
-				data: {
-					createdAt: new Date(),
-					...auditLog,
-				},
-				model: 'auditLog',
-				customFn: undefined,
-				context,
-			});
-
-			if (!createdLog) {
-				throw new DoubleTieError(
-					'Failed to create audit log - operation returned null',
-					{
-						code: ERROR_CODES.INTERNAL_SERVER_ERROR,
-						status: 500,
-					}
-				);
-			}
-
-			return createdLog as AuditLog;
-		},
-	};
-}

package/src/schema/audit-log/schema.ts

@@ -1,46 +0,0 @@
-import { z } from 'zod';
-
-/**
- * Zod schema for validating consent audit log entities.
- *
- * This defines the structure and validation rules for audit log entries:
- * - Required fields: entityType, entityId, actionType
- * - Optional fields: subjectId, ipAddress, changes, metadata
- * - Default current date/time for creation timestamp
- *
- * @example
- * ```typescript
- * const auditLogData = {
- *   id: 'log_w5qufx2a66m7xkn3ty',
- *   entityType: 'consent',
- *   entityId: 'cns_hadt8w7nngm7xmx2bn',
- *   actionType: 'update',
- *   subjectId: 'sub_x1pftyoufsm7xgo1kv',
- *   changes: { status: { from: 'active', to: 'withdrawn' } }
- * };
- *
- * // Validate and parse the audit log data
- * const validAuditLog = auditLogSchema.parse(auditLogData);
- * ```
- */
-export const auditLogSchema = z.object({
-	id: z.string(),
-	entityType: z.string(),
-	entityId: z.string(),
-	actionType: z.string(),
-	subjectId: z.string().optional(),
-	ipAddress: z.string().optional(),
-	userAgent: z.string().optional(),
-	changes: z.record(z.string(), z.unknown()).optional(),
-	metadata: z.record(z.string(), z.unknown()).optional(),
-	createdAt: z.date().prefault(() => new Date()),
-});
-
-/**
- * Type definition for AuditLog
- *
- * This type represents the structure of a consent audit log entry
- * as defined by the auditLogSchema. It includes all fields
- * that are part of the audit log entity.
- */
-export type AuditLog = z.infer<typeof auditLogSchema>;

package/src/schema/audit-log/table.ts

@@ -1,185 +0,0 @@
-import { COMMON_TIMEZONES, type Field } from '~/pkgs/data-model';
-import type { C15TOptions } from '~/types';
-import { auditLogSchema } from './schema';
-
-/**
- * Generates the database table configuration for the consent audit log entity.
- *
- * This function creates a schema definition that includes all standard audit log 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 audit log table customizations
- * @param auditLogFields - Additional fields from plugins to include in the audit log table
- * @returns A complete table schema definition with fields, model name, and metadata
- *
- * @example
- * ```typescript
- * const auditLogTableSchema = getAuditLogTable(c15tOptions);
- * // Use the schema for migrations or data access
- * const migrationPlans = generateMigrations(auditLogTableSchema);
- * ```
- */
-export function getAuditLogTable(
-	options: C15TOptions,
-	auditLogFields?: Record<string, Field>
-) {
-	const auditLogConfig = options.tables?.auditLog;
-	const subjectConfig = options.tables?.subject;
-
-	return {
-		/**
-		 * The name of the audit log table in the database, configurable through options
-		 */
-		entityName: auditLogConfig?.entityName || 'auditLog',
-
-		/**
-		 * The ID prefix for the audit log table
-		 * Used to generate unique prefixed IDs
-		 */
-		entityPrefix: auditLogConfig?.entityPrefix || 'log',
-
-		/**
-		 * The schema for the audit log table
-		 */
-		schema: auditLogSchema,
-
-		/**
-		 * Field definitions for the consent audit log table
-		 */
-		fields: {
-			/**
-			 * Type of entity this audit log entry is about (e.g., 'consent', 'subject', 'consentPurpose')
-			 */
-			entityType: {
-				type: 'string',
-				required: true,
-				fieldName: auditLogConfig?.fields?.entityType || 'entityType',
-			},
-
-			/**
-			 * ID of the entity this audit log entry is about
-			 */
-			entityId: {
-				type: 'string',
-				required: true,
-				fieldName: auditLogConfig?.fields?.entityId || 'entityId',
-			},
-
-			/**
-			 * Type of action that was performed on the entity
-			 * Common values: 'create', 'update', 'delete', 'view'
-			 */
-			actionType: {
-				type: 'string',
-				required: true,
-				fieldName: auditLogConfig?.fields?.actionType || 'actionType',
-			},
-
-			/**
-			 * Optional ID of the subject who performed the action
-			 */
-			subjectId: {
-				type: 'string',
-				required: false,
-				fieldName: auditLogConfig?.fields?.subjectId || 'subjectId',
-				references: {
-					model: subjectConfig?.entityName || 'subject',
-					field: 'id',
-				},
-			},
-
-			/**
-			 * IP address from which the action was performed
-			 */
-			ipAddress: {
-				type: 'string',
-				required: false,
-				fieldName: auditLogConfig?.fields?.ipAddress || 'ipAddress',
-			},
-
-			/**
-			 * Subject agent (browser/device) from which the action was performed
-			 */
-			userAgent: {
-				type: 'string',
-				required: false,
-				fieldName: auditLogConfig?.fields?.userAgent || 'userAgent',
-			},
-
-			/**
-			 * Detailed changes made to the entity
-			 * For updates, this typically contains before/after values
-			 */
-			changes: {
-				type: 'json',
-				required: false,
-				fieldName: auditLogConfig?.fields?.changes || 'changes',
-			},
-
-			/**
-			 * Additional metadata about the action
-			 */
-			metadata: {
-				type: 'json',
-				required: false,
-				fieldName: auditLogConfig?.fields?.metadata || 'metadata',
-			},
-
-			/**
-			 * When the audit log entry was created
-			 * Automatically set to current time by default
-			 */
-			createdAt: {
-				type: 'date',
-				defaultValue: () => new Date(),
-				required: true,
-				fieldName: auditLogConfig?.fields?.createdAt || 'createdAt',
-			},
-
-			/**
-			 * Timezone where the audit event occurred
-			 */
-			eventTimezone: {
-				type: 'timezone',
-				required: true,
-				defaultValue: COMMON_TIMEZONES.UTC,
-				fieldName: auditLogConfig?.fields?.eventTimezone || 'eventTimezone',
-			},
-
-			// Include additional fields from plugins
-			...(auditLogFields || {}),
-
-			// Include additional fields from configuration
-			...(auditLogConfig?.additionalFields || {}),
-		},
-
-		/**
-		 * Add indexes for better query performance
-		 */
-		indexes: [
-			{
-				name: 'entity_index',
-				fields: ['entityType', 'entityId'],
-			},
-			{
-				name: 'action_type_index',
-				fields: ['actionType'],
-			},
-			{
-				name: 'subject_id_index',
-				fields: ['subjectId'],
-			},
-			{
-				name: 'created_at_index',
-				fields: ['createdAt'],
-			},
-		],
-
-		/**
-		 * Execution order during migrations (lower numbers run first)
-		 * Audit log table needs to be created after the subject table it references
-		 */
-		order: 5,
-	};
-}