@c15t/backend 0.0.1-rc.10

package/src/init.test.ts

@@ -0,0 +1,235 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { DatabaseConfiguration } from './db/adapters/kysely-adapter';
+import { memoryAdapter } from './db/adapters/memory-adapter';
+import { init } from './init';
+import type { C15TPlugin } from './types';
+
+describe('init', () => {
+	beforeEach(() => {
+		vi.unstubAllEnvs();
+	});
+
+	it('should initialize with basic config', async () => {
+		const result = await init({
+			baseURL: 'http://localhost:3000',
+			database: memoryAdapter({}),
+		});
+
+		expect(result.isOk()).toBe(true);
+		if (result.isOk()) {
+			const ctx = result.value;
+			expect(ctx.options.baseURL).toBe('http://localhost:3000');
+			expect(ctx.options.basePath).toBe('/api/c15t');
+			expect(ctx.appName).toBe('c15t Consent Manager');
+		}
+	});
+
+	it('should infer base URL from environment', async () => {
+		vi.stubEnv('C15T_URL', 'http://localhost:5147');
+
+		const result = await init({
+			database: memoryAdapter({}),
+		});
+
+		expect(result.isOk()).toBe(true);
+		if (result.isOk()) {
+			const ctx = result.value;
+			expect(ctx.options.baseURL).toBe('http://localhost:5147');
+		}
+
+		vi.unstubAllEnvs();
+	});
+
+	it('should respect custom base path', async () => {
+		const result = await init({
+			baseURL: 'http://localhost:3000',
+			basePath: '/custom-path',
+			database: memoryAdapter({}),
+		});
+
+		expect(result.isOk()).toBe(true);
+		if (result.isOk()) {
+			const ctx = result.value;
+			expect(ctx.options.basePath).toBe('/custom-path');
+		}
+	});
+
+	it('should initialize plugins', async () => {
+		const newBaseURL = 'http://test.test';
+		const result = await init({
+			baseURL: 'http://localhost:3000',
+			database: memoryAdapter({}),
+			plugins: [
+				{
+					id: 'test-plugin',
+					name: 'Test Plugin',
+					type: 'test',
+					init: () => ({
+						context: {
+							baseURL: newBaseURL,
+						},
+					}),
+				} as C15TPlugin,
+			],
+		});
+
+		expect(result.isOk()).toBe(true);
+		if (result.isOk()) {
+			const ctx = result.value;
+			expect(ctx.baseURL).toBe(newBaseURL);
+		}
+	});
+
+	it('should allow plugins to modify options', async () => {
+		const result = await init({
+			baseURL: 'http://localhost:3000',
+			database: memoryAdapter({}),
+			plugins: [
+				{
+					id: 'test-plugin',
+					name: 'Test Plugin',
+					type: 'test',
+					init: () => ({
+						options: {
+							baseURL: 'http://test.test',
+						},
+					}),
+				} as C15TPlugin,
+			],
+		});
+
+		expect(result.isOk()).toBe(true);
+		if (result.isOk()) {
+			const ctx = result.value;
+			expect(ctx.options.baseURL).toBe('http://test.test');
+		}
+	});
+
+	it('should handle plugin initialization errors', async () => {
+		const result = await init({
+			baseURL: 'http://localhost:3000',
+			database: memoryAdapter({}),
+			plugins: [
+				{
+					id: 'error-plugin',
+					name: 'Error Plugin',
+					type: 'test',
+					init: () => {
+						throw new Error('Plugin initialization failed');
+					},
+				} as C15TPlugin,
+			],
+		});
+
+		expect(result.isErr()).toBe(true);
+		if (result.isErr()) {
+			expect(result.error.message).toContain('Plugin initialization failed');
+		}
+	});
+
+	it('should handle storage adapter errors', async () => {
+		const result = await init({
+			baseURL: 'http://localhost:3000',
+			database: null as unknown as DatabaseConfiguration,
+		});
+
+		expect(result.isErr()).toBe(false);
+		if (result.isErr()) {
+			expect(result.error.message).toContain(
+				'Failed to initialize consent system'
+			);
+		}
+	});
+
+	it('should handle secret from environment', async () => {
+		vi.stubEnv('C15T_SECRET', 'test-secret');
+
+		const result = await init({
+			baseURL: 'http://localhost:3000',
+			database: memoryAdapter({}),
+		});
+
+		expect(result.isOk()).toBe(true);
+		if (result.isOk()) {
+			const ctx = result.value;
+			expect(ctx.secret).toBe('test-secret');
+		}
+
+		vi.unstubAllEnvs();
+	});
+
+	it('should handle multiple plugins in sequence', async () => {
+		const result = await init({
+			baseURL: 'http://localhost:3000',
+			database: memoryAdapter({}),
+			plugins: [
+				{
+					id: 'plugin-1',
+					name: 'Plugin 1',
+					type: 'test',
+					init: () => ({
+						options: {
+							baseURL: 'http://plugin1.test',
+						},
+					}),
+				} as C15TPlugin,
+				{
+					id: 'plugin-2',
+					name: 'Plugin 2',
+					type: 'test',
+					init: () => ({
+						options: {
+							baseURL: 'http://plugin2.test',
+						},
+					}),
+				} as C15TPlugin,
+			],
+		});
+
+		expect(result.isOk()).toBe(true);
+		if (result.isOk()) {
+			const ctx = result.value;
+			expect(ctx.options.baseURL).toBe('http://plugin2.test');
+		}
+	});
+
+	it('should configure trusted origins', async () => {
+		const result = await init({
+			baseURL: 'http://localhost:3000',
+			database: memoryAdapter({}),
+			trustedOrigins: ['http://trusted.test'],
+		});
+
+		expect(result.isOk()).toBe(true);
+		if (result.isOk()) {
+			const ctx = result.value;
+			expect(ctx.trustedOrigins).toContain('http://localhost:3000');
+			expect(ctx.trustedOrigins).toContain('http://trusted.test');
+		}
+	});
+
+	it('should handle plugin context modifications', async () => {
+		const result = await init({
+			baseURL: 'http://localhost:3000',
+			database: memoryAdapter({}),
+			plugins: [
+				{
+					id: 'context-plugin',
+					name: 'Context Plugin',
+					type: 'test',
+					init: () => ({
+						context: {
+							appName: 'Modified App Name',
+						},
+					}),
+				} as C15TPlugin,
+			],
+		});
+
+		expect(result.isOk()).toBe(true);
+		if (result.isOk()) {
+			const ctx = result.value;
+			expect(ctx.appName).toBe('Modified App Name');
+		}
+	});
+});

package/src/init.ts

@@ -0,0 +1,261 @@
+import { defu } from 'defu';
+import { getConsentTables } from './db';
+import { generateId } from './db/core/fields/id-generator';
+import type { EntityName } from './db/core/types';
+import { createRegistry } from './db/create-registry';
+import { getAdapter } from './db/utils';
+import {
+	BASE_ERROR_CODES,
+	type C15TError,
+	failAsync,
+	fromPromise,
+} from './error';
+import { type C15TResult, fail, ok } from './error/results';
+/**
+ * c15t Initialization Module
+ *
+ * This module handles the initialization of the c15t consent management system.
+ * It sets up the consent context, configures storage adapters, initializes plugins,
+ * and establishes security settings like secrets and trusted origins.
+ *
+ * The initialization process includes:
+ * - Setting up storage adapters for consent data
+ * - Configuring security credentials and trusted origins
+ * - Initializing core and custom plugins
+ * - Creating the consent context object that serves as the foundation for the system
+ *
+ * This is an internal module typically not used directly by consumers of the c15t library.
+ */
+import type {
+	C15TContext,
+	C15TOptions,
+	C15TPlugin,
+	RegistryContext,
+} from './types';
+import { createLogger, env, getBaseURL, isProduction } from './utils';
+
+/**
+ * Helper function to convert a Promise to a C15T-specific ResultAsync
+ *
+ * @param promise - The promise to convert to a ResultAsync
+ * @returns A ResultAsync that captures errors as C15TError objects
+ */
+const fromC15TPromise = <T>(promise: Promise<T>) => {
+	return fromPromise(
+		promise,
+		(error): C15TError => ({
+			message: error instanceof Error ? error.message : String(error),
+			code: BASE_ERROR_CODES.UNKNOWN_ERROR,
+			name: 'C15TError',
+			data: { error },
+		})
+	);
+};
+
+/**
+ * Default secret used when no secret is provided
+ * This should only be used in development environments
+ */
+const DEFAULT_SECRET = 'c15t-default-secret-please-change-in-production';
+
+/**
+ * Initializes the c15t consent management system using Result pattern
+ *
+ * This function creates and configures the consent context based on the provided options.
+ * It sets up storage adapters, initializes plugins, configures security settings,
+ * and establishes the foundation for the consent management system.
+ *
+ * This version uses the neverthrow Result pattern for error handling.
+ *
+ * @template P - The plugin types used in the configuration
+ * @param options - Configuration options for the c15t instance
+ * @returns A Promise resolving to a Result containing the initialized consent context
+ *
+ * @example
+ * ```typescript
+ * const contextResult = await init({
+ *   secret: process.env.CONSENT_SECRET,
+ *   storage: memoryAdapter(),
+ *   plugins: [geoPlugin()]
+ * });
+ *
+ * // Handle success and error cases explicitly
+ * contextResult.match(
+ *   (context) => {
+ *     // Use the successfully initialized context
+ *   },
+ *   (error) => {
+ *     // Handle the initialization error
+ *     console.error('Failed to initialize:', error.message);
+ *   }
+ * );
+ * ```
+ */
+export const init = async <P extends C15TPlugin[]>(
+	options: C15TOptions<P>
+): Promise<C15TResult<C15TContext>> => {
+	try {
+		// Initialize core components
+		const adapterResult = await fromC15TPromise(getAdapter(options));
+
+		return adapterResult.andThen((adapter) => {
+			const logger = createLogger(options.logger);
+			const baseURL = getBaseURL(options.baseURL, options.basePath);
+			const secret =
+				options.secret ||
+				env.C15T_SECRET ||
+				env.CONSENT_SECRET ||
+				DEFAULT_SECRET;
+
+			// Secret warning
+			if (secret === DEFAULT_SECRET && isProduction) {
+				logger.error(
+					'Using default secret in production. Set C15T_SECRET or pass secret in config.'
+				);
+			}
+
+			// Create normalized options
+			const finalOptions = {
+				...options,
+				secret,
+				baseURL: baseURL ? new URL(baseURL).origin : '',
+				basePath: options.basePath || '/api/c15t',
+				plugins: [...(options.plugins || []), ...getInternalPlugins(options)],
+			};
+
+			// Create ID generator
+			const generateIdFunc = ({
+				model,
+				size = 16,
+			}: { model: EntityName; size?: number }) => {
+				return (
+					finalOptions?.advanced?.generateId?.({ model, size }) ||
+					generateId(getConsentTables(finalOptions)[model].entityPrefix)
+				);
+			};
+
+			// Create registry context - just what registries need
+			const registryContext: RegistryContext = {
+				adapter,
+				options: finalOptions,
+				logger,
+				hooks: options.databaseHooks || [],
+				generateId: generateIdFunc,
+			};
+
+			// Create full application context
+			const ctx: C15TContext = {
+				appName: finalOptions.appName || 'c15t Consent Manager',
+				options: finalOptions,
+				trustedOrigins: getTrustedOrigins(finalOptions),
+				baseURL: baseURL || '',
+				secret,
+				logger,
+				generateId: generateIdFunc,
+				adapter,
+				registry: createRegistry(registryContext),
+				tables: getConsentTables(options),
+			};
+
+			// Initialize plugins and return
+			return runPluginInit(ctx);
+		});
+	} catch (error) {
+		return failAsync(
+			`Failed to initialize consent system: ${error instanceof Error ? error.message : String(error)}`,
+			{
+				code: BASE_ERROR_CODES.INITIALIZATION_FAILED,
+				data: { error },
+			}
+		);
+	}
+};
+
+/**
+ * Initializes all registered plugins using the Result pattern
+ *
+ * This function runs the init method of each plugin in sequence,
+ * collecting any context or options modifications they provide.
+ *
+ * @param ctx - The current consent context
+ * @returns A Result with the updated context after plugin initialization
+ */
+function runPluginInit(ctx: C15TContext): C15TResult<C15TContext> {
+	try {
+		let options = ctx.options;
+		const plugins = options.plugins || [];
+		let context: C15TContext = ctx;
+
+		for (const plugin of plugins) {
+			if (plugin.init) {
+				const result = plugin.init(ctx);
+				if (typeof result === 'object') {
+					if (result.options) {
+						options = defu(result.options, options);
+					}
+					if (result.context) {
+						context = {
+							...context,
+							...(result.context as Partial<C15TContext>),
+						};
+					}
+				}
+			}
+		}
+
+		context.options = options;
+		return ok(context);
+	} catch (error) {
+		return fail(
+			`Plugin initialization failed: ${error instanceof Error ? error.message : String(error)}`,
+			{
+				code: BASE_ERROR_CODES.PLUGIN_INITIALIZATION_FAILED,
+				data: { error },
+			}
+		);
+	}
+}
+
+/**
+ * Retrieves internal plugins based on configuration options
+ *
+ * This function determines which internal plugins should be automatically
+ * included based on the provided options.
+ *
+ * @param options - The c15t configuration options
+ * @returns An array of internal plugins to include
+ */
+function getInternalPlugins(_options: C15TOptions): C15TPlugin[] {
+	const plugins: C15TPlugin[] = [];
+
+	return plugins;
+}
+
+/**
+ * Builds a list of trusted origins for CORS
+ *
+ * This function determines which origins should be trusted for
+ * cross-origin requests based on configuration and environment.
+ *
+ * @param options - The c15t configuration options
+ * @returns An array of trusted origin URLs
+ */
+function getTrustedOrigins(options: C15TOptions): string[] {
+	const baseURL = getBaseURL(options.baseURL, options.basePath);
+	if (!baseURL) {
+		return [];
+	}
+
+	const trustedOrigins = [new URL(baseURL).origin];
+
+	if (options.trustedOrigins && Array.isArray(options.trustedOrigins)) {
+		trustedOrigins.push(...options.trustedOrigins);
+	}
+
+	const envTrustedOrigins = env.C15T_TRUSTED_ORIGINS;
+	if (envTrustedOrigins) {
+		trustedOrigins.push(...envTrustedOrigins.split(','));
+	}
+
+	return trustedOrigins;
+}

package/src/integrations/index.ts

@@ -0,0 +1,10 @@
+/**
+ * c15t Framework Integrations
+ * This module exports integrations with various frameworks and libraries
+ */
+
+// Export Next.js integration
+export * from './next';
+
+// Export React integration
+export * from './react';

package/src/integrations/next.ts

@@ -0,0 +1,136 @@
+import type { C15TInstance } from '~/core';
+import { BASE_ERROR_CODES } from '~/error/codes';
+import type { C15TContext } from '~/types';
+
+/**
+ * Convert a c15t handler to a Next.js API route handler.
+ *
+ * This function adapts a c15t instance to work with Next.js App Router API routes,
+ * providing GET and POST handler functions. It handles the conversion between
+ * c15t's Result types and Next.js Response objects.
+ *
+ * @example
+ * ```typescript
+ * // app/api/c15t/route.ts
+ * import { toNextJsHandler } from '@c15t/integrations/next';
+ * import { c15t } from '@/lib/c15t';
+ *
+ * // Pass the entire c15t instance, not just the handler
+ * export const { GET, POST } = toNextJsHandler(c15t);
+ *
+ * // ❌ Don't do this:
+ * // export const { GET, POST } = toNextJsHandler(c15t.handler);
+ * ```
+ *
+ * @param instance - The complete c15t instance (not just the handler)
+ * @returns Next.js API route handler functions for GET and POST
+ */
+export function toNextJsHandler(instance: C15TInstance) {
+	const handler = async (initialRequest: Request) => {
+		try {
+			const request = initialRequest;
+
+			// For POST requests, validate JSON body
+			if (request.method === 'POST') {
+				try {
+					const clonedRequest = request.clone();
+					await clonedRequest.json();
+				} catch (error) {
+					return new Response(
+						JSON.stringify({
+							error: true,
+							code: BASE_ERROR_CODES.REQUEST_HANDLER_ERROR,
+							message: 'Invalid JSON in request body',
+							details: error instanceof Error ? error.message : 'Unknown error',
+						}),
+						{
+							status: 400,
+							headers: {
+								'Content-Type': 'application/json',
+							},
+						}
+					);
+				}
+			}
+
+			// Ensure the baseURL is set correctly for the c15t instance
+			if (instance.$context) {
+				const contextPromise = instance.$context;
+				try {
+					const contextResult = await contextPromise;
+
+					// Extract context safely using match pattern
+					contextResult.match(
+						(context: C15TContext) => {
+							// If baseURL is not set, initialize it from the request URL
+							if (!context.baseURL || context.baseURL.trim() === '') {
+								const url = new URL(request.url);
+								const basePath = context.options?.basePath || '/api/c15t';
+								const baseURL = `${url.origin}${basePath}`;
+
+								context.baseURL = baseURL;
+								if (context.options) {
+									context.options.baseURL = baseURL;
+								}
+							}
+						},
+						() => {
+							// Handle context error silently - the handler will deal with it
+						}
+					);
+				} catch {
+					// Handle promise rejection silently - the handler will deal with it
+				}
+			}
+
+			// Handle the request and unwrap the Result
+			const result = await instance.handler(request);
+			return await result.match(
+				(response) => response,
+				(error) => {
+					// Convert c15t errors to Response objects
+					const status = error.status || 500;
+					const message =
+						error.message || BASE_ERROR_CODES.INTERNAL_SERVER_ERROR;
+					return new Response(
+						JSON.stringify({
+							error: true,
+							code: error.code || BASE_ERROR_CODES.INTERNAL_SERVER_ERROR,
+							message,
+							data: error.data,
+						}),
+						{
+							status,
+							headers: {
+								'Content-Type': 'application/json',
+							},
+						}
+					);
+				}
+			);
+		} catch (error) {
+			// Handle any unexpected errors
+			// biome-ignore lint/suspicious/noConsole: This is a logging error
+			console.error('Unexpected error in c15t handler:', error);
+			return new Response(
+				JSON.stringify({
+					error: true,
+					code: BASE_ERROR_CODES.INTERNAL_SERVER_ERROR,
+					message: 'An unexpected error occurred',
+					data: { error: String(error) },
+				}),
+				{
+					status: 500,
+					headers: {
+						'Content-Type': 'application/json',
+					},
+				}
+			);
+		}
+	};
+
+	return {
+		GET: handler,
+		POST: handler,
+	};
+}