@c15t/backend 0.0.1-rc.10

package/src/error/codes.ts

@@ -0,0 +1,201 @@
+/**
+ * Standardized error codes for the c15t consent management system.
+ *
+ * These error codes are used throughout the application to provide consistent
+ * error messages and enable proper error handling in client applications.
+ * Each error code represents a specific type of error that can occur during
+ * consent management operations.
+ *
+ * @example
+ * ```typescript
+ * import { BASE_ERROR_CODES, C15TError } from '@c15t/error';
+ *
+ * // Handle a specific error
+ * try {
+ *   await consentManager.updateConsent(consentId, preferences);
+ * } catch (error) {
+ *   if (error instanceof C15TError && error.code === BASE_ERROR_CODES.CONSENT_NOT_FOUND) {
+ *     // Handle the specific case where consent is not found
+ *     console.error('Cannot update: consent record does not exist');
+ *   } else {
+ *     // Handle other errors
+ *     console.error('Failed to update consent:', error.message);
+ *   }
+ * }
+ * ```
+ */
+export const BASE_ERROR_CODES = {
+	/**
+	 * The requested resource could not be found.
+	 * This is a general error for when a requested entity does not exist.
+	 */
+	NOT_FOUND: 'Resource not found',
+
+	/**
+	 * The request is invalid or malformed.
+	 * This is a general error for requests that do not meet the expected format.
+	 */
+	BAD_REQUEST: 'Bad request',
+
+	/**
+	 * The request conflicts with the current state of the server.
+	 * This may occur when trying to create a resource that already exists or
+	 * when attempting to modify a resource in a way that conflicts with its current state.
+	 */
+	CONFLICT: 'Conflict with current state',
+
+	/**
+	 * The requested consent record could not be found.
+	 * This may occur when attempting to retrieve, update, or delete a non-existent consent record.
+	 */
+	CONSENT_NOT_FOUND: 'Consent not found',
+
+	/**
+	 * The consent record has expired and is no longer valid.
+	 * This may occur when attempting to use a consent record after its expiration date.
+	 */
+	CONSENT_EXPIRED: 'Consent has expired',
+
+	/**
+	 * An error occurred while attempting to create a new consent record.
+	 * This may be due to validation errors, storage issues, or other internal errors.
+	 */
+	FAILED_TO_CREATE_CONSENT: 'Failed to create consent',
+
+	/**
+	 * An error occurred while attempting to update an existing consent record.
+	 * This may be due to validation errors, storage issues, or concurrent modifications.
+	 */
+	FAILED_TO_UPDATE_CONSENT: 'Failed to update consent',
+
+	/**
+	 * An error occurred while attempting to retrieve a consent record.
+	 * This may be due to storage issues, permissions, or other internal errors.
+	 */
+	FAILED_TO_GET_CONSENT: 'Failed to get consent',
+
+	/**
+	 * An error occurred while attempting to create a new consent consentPurpose.
+	 * This may be due to validation errors, duplicate consentPurpose IDs, or other internal errors.
+	 */
+	FAILED_TO_CREATE_PURPOSE: 'Failed to create consentPurpose',
+
+	/**
+	 * The requested consent consentPurpose could not be found.
+	 * This may occur when attempting to retrieve, update, or delete a non-existent consentPurpose.
+	 */
+	PURPOSE_NOT_FOUND: 'Consent Purpose not found',
+
+	/**
+	 * The provided configuration is invalid or contains errors.
+	 * This may occur when initializing the system with incorrect settings.
+	 */
+	INVALID_CONFIGURATION: 'Invalid configuration',
+
+	/**
+	 * A required parameter is missing from the request.
+	 * This may occur when API calls are made without all necessary data.
+	 */
+	MISSING_REQUIRED_PARAMETER: 'Missing required parameter',
+
+	/**
+	 * The request requires authentication that was not provided or is invalid.
+	 * This may occur when attempting to access protected resources without proper credentials.
+	 */
+	UNAUTHORIZED: 'Unauthorized',
+
+	/**
+	 * The requester does not have permission to perform the requested operation.
+	 * This may occur when authenticated subjects attempt operations beyond their permission level.
+	 */
+	FORBIDDEN: 'Forbidden',
+
+	/**
+	 * An unexpected internal error occurred on the server.
+	 * This is a general error for unexpected exceptions during request processing.
+	 */
+	INTERNAL_SERVER_ERROR: 'Internal server error',
+
+	/**
+	 * Initialization of the system failed.
+	 * This may occur when the system cannot be initialized due to configuration
+	 * errors, missing dependencies, or other setup issues.
+	 */
+	INITIALIZATION_FAILED: 'Initialization failed',
+
+	/**
+	 * Plugin initialization failed.
+	 * This may occur when a plugin cannot be initialized due to configuration
+	 * errors, missing dependencies, or other setup issues.
+	 */
+	PLUGIN_INITIALIZATION_FAILED: 'Plugin initialization failed',
+
+	/**
+	 * Database connection error.
+	 * This may occur when the system cannot connect to the database due to
+	 * connection issues, authentication failures, or other database-related problems.
+	 */
+	DATABASE_CONNECTION_ERROR: 'Database connection error',
+
+	/**
+	 * Database query error.
+	 * This may occur when a database query fails due to syntax errors,
+	 * constraint violations, or other database-related issues.
+	 */
+	DATABASE_QUERY_ERROR: 'Database query error',
+
+	/**
+	 * An error occurred while attempting to handle a request.
+	 * This may occur when a request cannot be processed due to invalid input,
+	 * internal errors, or other issues.
+	 */
+	REQUEST_HANDLER_ERROR: 'Request handler error',
+
+	/**
+	 * Error retrieving API endpoints.
+	 * This may occur when the system cannot retrieve API endpoints due to
+	 * configuration errors or other internal issues.
+	 */
+	API_RETRIEVAL_ERROR: 'API retrieval error',
+
+	/**
+	 * The request is invalid or malformed.
+	 * This is a specific error for requests that do not meet the expected format.
+	 */
+	INVALID_REQUEST: 'Invalid request',
+
+	/**
+	 * Unknown or unclassified error.
+	 * Used when an error occurs that doesn't match any other error code.
+	 */
+	UNKNOWN_ERROR: 'Unknown error',
+} as const;
+
+/**
+ * Error categories for organizing errors by domain
+ */
+export const ERROR_CATEGORIES = {
+	VALIDATION: 'validation',
+	AUTHORIZATION: 'authorization',
+	STORAGE: 'storage',
+	NETWORK: 'network',
+	PLUGIN: 'plugin',
+	CONFIGURATION: 'configuration',
+	UNEXPECTED: 'unexpected',
+} as const;
+
+/**
+ * Type for error categories
+ */
+export type ErrorCategory =
+	(typeof ERROR_CATEGORIES)[keyof typeof ERROR_CATEGORIES];
+
+/**
+ * Type containing all possible error codes from the BASE_ERROR_CODES object
+ */
+export type ErrorCode = keyof typeof BASE_ERROR_CODES;
+
+/**
+ * Type for the error message values in BASE_ERROR_CODES
+ */
+export type ErrorMessage = (typeof BASE_ERROR_CODES)[ErrorCode];

package/src/error/error.ts

@@ -0,0 +1,145 @@
+import {
+	BASE_ERROR_CODES,
+	type ErrorCategory,
+	type ErrorMessage,
+} from './codes';
+
+/**
+ * Custom error class for c15t consent management errors.
+ *
+ * This class extends the standard Error object with additional properties
+ * specific to the c15t consent management system, such as error codes,
+ * status codes, and contextual data.
+ *
+ * @example
+ * ```typescript
+ * // Create and throw a c15t error
+ * throw new C15TError('Failed to update subject preferences', {
+ *   code: BASE_ERROR_CODES.FAILED_TO_UPDATE_CONSENT,
+ *   status: 400,
+ *   data: { subjectId: 'sub_x1pftyoufsm7xgo1kv', preferences: { analytics: true } }
+ * });
+ *
+ * // Create an error from an HTTP response
+ * const error = C15TError.fromResponse(response, await response.json());
+ * ```
+ */
+export class C15TError extends Error {
+	/**
+	 * The error code identifying the type of error
+	 */
+	code?: ErrorMessage;
+
+	/**
+	 * HTTP status code associated with this error
+	 */
+	status?: number;
+
+	/**
+	 * Additional data providing context about the error
+	 */
+	data?: Record<string, unknown>;
+
+	/**
+	 * Category of the error for better organization
+	 */
+	category?: ErrorCategory;
+
+	/**
+	 * Creates a new C15TError instance.
+	 *
+	 * @param message - Human-readable error message
+	 * @param options - Additional error options including code, status, and data
+	 */
+	constructor(
+		message: string,
+		options?: {
+			/**
+			 * The error code identifying the type of error
+			 */
+			code?: ErrorMessage;
+
+			/**
+			 * HTTP status code associated with this error
+			 */
+			status?: number;
+
+			/**
+			 * Additional data providing context about the error
+			 */
+			data?: Record<string, unknown>;
+
+			/**
+			 * Category of the error for better organization
+			 */
+			category?: ErrorCategory;
+		}
+	) {
+		super(message);
+		this.name = 'C15TError';
+
+		if (options) {
+			this.code = options.code;
+			this.status = options.status;
+			this.data = options.data;
+			this.category = options.category;
+		}
+
+		// Ensure prototype chain works correctly
+		Object.setPrototypeOf(this, C15TError.prototype);
+	}
+
+	/**
+	 * Creates a C15TError from an HTTP response and optional response data.
+	 *
+	 * @param response - The HTTP Response object
+	 * @param data - Optional parsed response data
+	 * @returns A new C15TError instance with appropriate properties
+	 */
+	static fromResponse(response: Response, data?: unknown): C15TError {
+		// Extract error message from response or data
+		let message = `HTTP error ${response.status}`;
+		let code: ErrorMessage | undefined;
+		let errorData: Record<string, unknown> | undefined;
+
+		// Try to extract more specific error details from the response data
+		if (data && typeof data === 'object' && data !== null) {
+			const errorObj = data as Record<string, unknown>;
+
+			if (typeof errorObj.message === 'string') {
+				message = errorObj.message;
+			}
+
+			if (typeof errorObj.code === 'string') {
+				// Check if the code matches one of our known error codes
+				const isKnownCode = Object.values(BASE_ERROR_CODES).includes(
+					errorObj.code as ErrorMessage
+				);
+				if (isKnownCode) {
+					code = errorObj.code as ErrorMessage;
+				}
+			}
+
+			// Include any additional error data
+			if (typeof errorObj.data === 'object' && errorObj.data !== null) {
+				errorData = errorObj.data as Record<string, unknown>;
+			}
+		}
+
+		return new C15TError(message, {
+			code,
+			status: response.status,
+			data: errorData,
+		});
+	}
+
+	/**
+	 * Determines if an unknown error is a C15TError.
+	 *
+	 * @param error - The error to check
+	 * @returns True if the error is a C15TError instance
+	 */
+	static isC15TError(error: unknown): error is C15TError {
+		return error instanceof C15TError;
+	}
+}

package/src/error/index.ts

@@ -0,0 +1,23 @@
+export { BASE_ERROR_CODES } from './codes';
+export type { ErrorCategory, ErrorCode, ErrorMessage } from './codes';
+export { C15TError } from './error';
+export {
+	fail,
+	failAsync,
+	safeResult,
+	safeResultAsync,
+} from './results';
+export {
+	recoverFromCodes,
+	recoverFromCategory,
+} from './recovery';
+export {
+	logError,
+	logErrorAsync,
+} from './logging';
+export {
+	validationPipeline,
+	retrievalPipeline,
+} from './pipeline';
+
+export { fromPromise, okAsync, ok, Result } from 'neverthrow';

package/src/error/logging.ts

@@ -0,0 +1,52 @@
+import type { Result, ResultAsync } from 'neverthrow';
+import type { C15TError } from './error';
+
+/**
+ * Logs any errors in a Result without changing the Result
+ *
+ * @param result - The Result that may contain an error
+ * @param logger - Logger instance
+ * @param message - Optional message prefix
+ * @returns The original Result unchanged
+ */
+export const logError = <T>(
+	result: Result<T, C15TError>,
+	logger: { error: (message: string, ...args: unknown[]) => void },
+	message = 'Error occurred:'
+): Result<T, C15TError> => {
+	return result.mapErr((error) => {
+		logger.error(`${message} ${error.message}`, {
+			code: error.code,
+			status: error.status,
+			data: error.data,
+			category: error.category,
+			stack: error.stack,
+		});
+		return error;
+	});
+};
+
+/**
+ * Logs any errors in a ResultAsync without changing the ResultAsync
+ *
+ * @param resultAsync - The ResultAsync that may contain an error
+ * @param logger - Logger instance
+ * @param message - Optional message prefix
+ * @returns The original ResultAsync unchanged
+ */
+export const logErrorAsync = <T>(
+	resultAsync: ResultAsync<T, C15TError>,
+	logger: { error: (message: string, ...args: unknown[]) => void },
+	message = 'Error occurred:'
+): ResultAsync<T, C15TError> => {
+	return resultAsync.mapErr((error) => {
+		logger.error(`${message} ${error.message}`, {
+			code: error.code,
+			status: error.status,
+			data: error.data,
+			category: error.category,
+			stack: error.stack,
+		});
+		return error;
+	});
+};

package/src/error/pipeline.ts

@@ -0,0 +1,57 @@
+import type { Result, ResultAsync } from 'neverthrow';
+import { BASE_ERROR_CODES } from './codes';
+import type { C15TError } from './error';
+import { safeResult, safeResultAsync } from './results';
+
+/**
+ * Creates a standard validation pipeline
+ *
+ * @param validator - Function that validates input
+ * @param processor - Function that processes validated input
+ * @returns A function that validates and processes input in a Result chain
+ */
+export const validationPipeline = <Input, Output>(
+	validator: (input: Input) => boolean | string,
+	processor: (input: Input) => Output
+): ((input: Input) => Result<Output, C15TError>) => {
+	return (input: Input) => {
+		const validationResult = safeResult(() => {
+			const validationOutcome = validator(input);
+			if (validationOutcome === false) {
+				throw new Error('Validation failed');
+			}
+			if (typeof validationOutcome === 'string') {
+				throw new Error(validationOutcome);
+			}
+			return input;
+		}, BASE_ERROR_CODES.INVALID_REQUEST);
+
+		return validationResult.andThen((validInput) =>
+			safeResult(() => processor(validInput))
+		);
+	};
+};
+
+/**
+ * Creates a standard async data retrieval pipeline
+ *
+ * @param fetcher - Function that fetches data
+ * @param transformer - Function that transforms fetched data
+ * @returns A function that fetches and transforms data in a ResultAsync chain
+ */
+export const retrievalPipeline = <RawData, TransformedData>(
+	fetcher: () => Promise<RawData>,
+	transformer: (data: RawData) => TransformedData
+): (() => ResultAsync<TransformedData, C15TError>) => {
+	return () => {
+		return safeResultAsync(
+			fetcher(),
+			BASE_ERROR_CODES.FAILED_TO_GET_CONSENT
+		).andThen((data) =>
+			safeResult(
+				() => transformer(data),
+				BASE_ERROR_CODES.INVALID_CONFIGURATION
+			)
+		);
+	};
+};

package/src/error/recovery.ts

@@ -0,0 +1,45 @@
+import { type Result, err, ok } from 'neverthrow';
+import type { ErrorCategory, ErrorMessage } from './codes';
+import type { C15TError } from './error';
+
+/**
+ * Recovers from specific error codes by transforming to a default value
+ *
+ * @param result - The result that may contain an error
+ * @param errorCodes - Array of error codes to recover from
+ * @param defaultValue - Value to use if error matches specified codes
+ * @returns A new Result with the error recovered if it matches specified codes
+ */
+export const recoverFromCodes = <T>(
+	result: Result<T, C15TError>,
+	errorCodes: ErrorMessage[],
+	defaultValue: T
+): Result<T, C15TError> => {
+	return result.orElse((error) => {
+		if (error.code && errorCodes.includes(error.code)) {
+			return ok(defaultValue);
+		}
+		return err(error);
+	});
+};
+
+/**
+ * Recovers from errors of a specific category
+ *
+ * @param result - The result that may contain an error
+ * @param category - Error category to recover from
+ * @param defaultValue - Value to use if error matches specified category
+ * @returns A new Result with the error recovered if it matches the category
+ */
+export const recoverFromCategory = <T>(
+	result: Result<T, C15TError>,
+	category: ErrorCategory,
+	defaultValue: T
+): Result<T, C15TError> => {
+	return result.orElse((error) => {
+		if (error.category === category) {
+			return ok(defaultValue);
+		}
+		return err(error);
+	});
+};

package/src/error/results.ts

@@ -0,0 +1,100 @@
+import { type Result, ResultAsync, err, ok as neverOk } from 'neverthrow';
+import { BASE_ERROR_CODES, type ErrorMessage } from './codes';
+import { C15TError } from './error';
+
+/**
+ * Type for C15T results that can contain any error
+ */
+export type C15TResult<T> = Result<T, C15TError>;
+
+/**
+ * Type for C15T async results that can contain any error
+ */
+export type C15TResultAsync<T> = ResultAsync<T, C15TError>;
+
+/**
+ * Creates a successful result
+ */
+export const ok = <T>(value: T): C15TResult<T> => neverOk(value);
+
+/**
+ * Creates a standardized failure Result with a C15TError
+ *
+ * @param message - Error message
+ * @param options - Additional error options
+ * @returns A Result containing the error
+ */
+export const fail = <T>(
+	message: string,
+	options?: {
+		code?: ErrorMessage;
+		status?: number;
+		data?: Record<string, unknown>;
+	}
+): Result<T, C15TError> => {
+	return err(new C15TError(message, options));
+};
+
+/**
+ * Creates a standardized failure ResultAsync with a C15TError
+ *
+ * @param message - Error message
+ * @param options - Additional error options
+ * @returns A ResultAsync containing the error
+ */
+export const failAsync = <T>(
+	message: string,
+	options?: {
+		code?: ErrorMessage;
+		status?: number;
+		data?: Record<string, unknown>;
+	}
+): ResultAsync<T, C15TError> => {
+	return ResultAsync.fromSafePromise(
+		Promise.reject(new C15TError(message, options))
+	);
+};
+
+/**
+ * Wraps a potentially throwing function in a Result
+ *
+ * @param fn - Function that might throw
+ * @param errorCode - Optional error code to use if fn throws
+ * @returns A Result containing either the function result or a C15TError
+ */
+export const safeResult = <T>(
+	fn: () => T,
+	errorCode: ErrorMessage = BASE_ERROR_CODES.UNKNOWN_ERROR
+): Result<T, C15TError> => {
+	try {
+		return ok(fn());
+	} catch (error) {
+		return err(
+			new C15TError(error instanceof Error ? error.message : String(error), {
+				code: errorCode,
+				data: { originalError: error },
+			})
+		);
+	}
+};
+
+/**
+ * Wraps a Promise in a ResultAsync
+ *
+ * @param promise - Promise that might reject
+ * @param errorCode - Optional error code to use if promise rejects
+ * @returns A ResultAsync containing either the promise result or a C15TError
+ */
+export const safeResultAsync = <T>(
+	promise: Promise<T>,
+	errorCode: ErrorMessage = BASE_ERROR_CODES.UNKNOWN_ERROR
+): ResultAsync<T, C15TError> => {
+	return ResultAsync.fromPromise(
+		promise,
+		(error): C15TError =>
+			new C15TError(error instanceof Error ? error.message : String(error), {
+				code: errorCode,
+				data: { originalError: error },
+			})
+	);
+};

package/src/index.ts

@@ -0,0 +1,79 @@
+/**
+ * c15t Consent Management System
+ *
+ * This is the main entry point for the c15t library, exporting all public APIs,
+ * components, and types needed to implement consent management in your application.
+ */
+
+//------------------------------------------------------------------------------
+// Core API
+//------------------------------------------------------------------------------
+
+/**
+ * Core factory function and types for creating c15t instances
+ */
+export * from './core';
+
+/**
+ * Error codes used throughout the system for consistent error handling
+ */
+export * from './error/codes';
+
+//------------------------------------------------------------------------------
+// Utilities and Helpers
+//------------------------------------------------------------------------------
+
+/**
+ * General utility functions used throughout the library
+ */
+export * from './utils';
+
+//------------------------------------------------------------------------------
+// Client
+//------------------------------------------------------------------------------
+
+/**
+ * Client-side integration for implementing consent in browsers
+ */
+export * from './client';
+
+/**
+ * All client-related types bundled under a namespace to avoid conflicts
+ */
+export * as ClientTypes from './client/types';
+
+/**
+ * Selected client types needed for common use cases
+ */
+export type {
+	c15tClientOptions,
+	FetchOptions,
+	ResponseContext,
+} from './client/types';
+
+//------------------------------------------------------------------------------
+// Plugins
+//------------------------------------------------------------------------------
+
+/**
+ * Geo plugin for jurisdiction-based consent management
+ */
+export * from './plugins/geo';
+
+//------------------------------------------------------------------------------
+// Types
+//------------------------------------------------------------------------------
+
+/**
+ * All system types bundled under a namespace to avoid conflicts
+ */
+export * as Types from './types';
+
+/**
+ * Plugin type extension point for type augmentation
+ */
+declare module './types/plugins' {
+	interface PluginTypes {
+		// Plugin type interfaces will be added here
+	}
+}