@c15t/backend 0.0.1-rc.10

package/src/utils/env.ts

@@ -0,0 +1,103 @@
+/**
+ * Environment variables object
+ *
+ * Provides access to environment variables in a way that works in both
+ * browser and Node.js environments. In Node.js, this will be process.env,
+ * and in browsers, it will be an empty object.
+ *
+ * @returns An object containing environment variables accessible in the current runtime
+ *
+ * @example
+ * ```ts
+ * // Access an environment variable
+ * const apiKey = env.API_KEY;
+ * ```
+ */
+export const env = typeof process !== 'undefined' ? process.env : {};
+
+/**
+ * Determines if the application is running in production mode
+ *
+ * Checks if NODE_ENV is set to 'production'. This is useful for
+ * conditionally enabling or disabling features based on the environment.
+ *
+ * @returns Boolean indicating whether the application is running in production mode
+ *
+ * @example
+ * ```ts
+ * // Conditionally execute code based on environment
+ * if (isProduction) {
+ *   // Production-only code
+ * }
+ * ```
+ */
+export const isProduction =
+	typeof process !== 'undefined' && process.env.NODE_ENV === 'production';
+
+/**
+ * Determines if the application is running in development mode
+ *
+ * Checks if NODE_ENV is set to 'development'. This is useful for
+ * conditionally enabling debugging features in development environments.
+ *
+ * @returns Boolean indicating whether the application is running in development mode
+ *
+ * @example
+ * ```ts
+ * // Enable development-only features
+ * if (isDevelopment) {
+ *   enableDebugTools();
+ * }
+ * ```
+ */
+export const isDevelopment =
+	typeof process !== 'undefined' && process.env.NODE_ENV === 'development';
+
+/**
+ * Converts a string or boolean value to a boolean
+ *
+ * @param val - The value to convert to boolean
+ * @returns `false` if the value is falsy or the string 'false', otherwise `true`
+ *
+ * @example
+ * ```ts
+ * toBoolean('true'); // true
+ * toBoolean('false'); // false
+ * toBoolean(undefined); // false
+ * toBoolean(true); // true
+ * ```
+ *
+ * @internal Used for environment variable parsing
+ */
+function toBoolean(val: boolean | string | undefined) {
+	return val ? val !== 'false' : false;
+}
+
+/**
+ * The current Node.js environment value
+ *
+ * Retrieves the NODE_ENV environment variable value if available,
+ * otherwise returns an empty string.
+ *
+ * @returns The current NODE_ENV value or empty string if not set
+ */
+export const nodeENV =
+	(typeof process !== 'undefined' && process.env && process.env.NODE_ENV) || '';
+
+/**
+ * Determines if the application is running in test mode
+ *
+ * Checks if NODE_ENV is set to 'test' or if the TEST environment
+ * variable is truthy and not 'false'.
+ *
+ * @returns Boolean indicating whether the application is running in test mode
+ *
+ * @example
+ * ```ts
+ * // Skip expensive operations in tests
+ * if (!isTest) {
+ *   runExpensiveOperation();
+ * }
+ * ```
+ */
+export const isTest = nodeENV === 'test' || toBoolean(env.TEST);

package/src/utils/hide-metadata.ts

@@ -0,0 +1,21 @@
+/**
+ * Constant metadata flag to identify non-action objects
+ *
+ * This constant provides metadata that can be attached to objects to indicate
+ * they should not be treated as actions by the system. The value is explicitly
+ * typed as a const assertion to ensure type safety.
+ *
+ * @see Used to differentiate between actionable and non-actionable objects in the system
+ *
+ * @example
+ * ```ts
+ * // Mark an object as not being an action
+ * const nonActionObject = {
+ *   ...HIDE_METADATA,
+ *   // other properties
+ * };
+ * ```
+ */
+export const HIDE_METADATA = {
+	isAction: false as const,
+};

package/src/utils/index.ts

@@ -0,0 +1,17 @@
+/**
+ * c15t Utility Functions
+ *
+ * This module serves as the main entry point for all utility functions used in the c15t
+ * consent management system. It re-exports utilities from specialized modules for easier access.
+ *
+ * Import utilities from this module for a cleaner import structure:
+ * @example
+ * ```typescript
+ * import { generateId, encrypt, formatDate } from '../utils';
+ * ```
+ */
+export * from './env';
+export * from './hide-metadata';
+export * from './logger';
+export * from './url';
+export * from './json';

package/src/utils/ip.ts

@@ -0,0 +1,45 @@
+import type { C15TOptions } from '~/types';
+import { isTest } from './env';
+
+/**
+ * Gets the client IP address from request headers
+ *
+ * @param req - The request object or headers
+ * @param options - C15T options containing IP address configuration
+ * @returns The client IP address or null if tracking is disabled
+ */
+export function getIp(
+	req: Request | Headers,
+	options: C15TOptions
+): string | null {
+	if (options.advanced?.ipAddress?.disableIpTracking) {
+		return null;
+	}
+	const testIP = '127.0.0.1';
+	if (isTest) {
+		return testIP;
+	}
+	const ipHeaders = options.advanced?.ipAddress?.ipAddressHeaders;
+	const keys = ipHeaders || [
+		'x-client-ip',
+		'x-forwarded-for',
+		'cf-connecting-ip',
+		'fastly-client-ip',
+		'x-real-ip',
+		'x-cluster-client-ip',
+		'x-forwarded',
+		'forwarded-for',
+		'forwarded',
+	];
+	const headers = req instanceof Request ? req.headers : req;
+	for (const key of keys) {
+		const value = headers.get(key);
+		if (value) {
+			const ip = value.split(',')[0]?.trim();
+			if (ip) {
+				return ip;
+			}
+		}
+	}
+	return null;
+}

package/src/utils/json.ts

@@ -0,0 +1,19 @@
+import type { SuperJSONValue } from 'node_modules/superjson/dist/types';
+import superjson from 'superjson';
+/**
+ * Parse a JSON string using SuperJSON
+ * @param json - The JSON string to parse
+ * @returns The parsed JSON value
+ */
+export function parseJson(json: SuperJSONValue) {
+	return superjson.parse(json);
+}
+
+/**
+ * Stringify a value using SuperJSON
+ * @param value - The value to stringify
+ * @returns The stringified value
+ */
+export function stringifyJson(value: SuperJSONValue) {
+	return superjson.stringify(value);
+}

package/src/utils/logger.ts

@@ -0,0 +1,252 @@
+/**
+ * Represents the available log severity levels
+ *
+ * These levels determine the priority and visibility of log messages.
+ * The order from highest to lowest severity is typically:
+ * error > warn > info > success > debug
+ */
+export type LogLevel = 'info' | 'success' | 'warn' | 'error' | 'debug';
+
+/**
+ * Array of all available log levels in order of importance
+ *
+ * This const array ensures type safety when working with log levels
+ * and provides a reference for level comparisons.
+ */
+export const levels = ['info', 'success', 'warn', 'error', 'debug'] as const;
+
+/**
+ * Determines if a log message should be published based on configured log level
+ *
+ * @param currentLogLevel - The configured log level threshold for the logger
+ * @param logLevel - The level of the message being evaluated
+ * @returns Boolean indicating whether the message should be published
+ *
+ * @example
+ * ```ts
+ * // Only publish if error level is at or above the current log level
+ * if (shouldPublishLog('warn', 'error')) {
+ *   // This will return true as error is more severe than warn
+ * }
+ * ```
+ */
+export function shouldPublishLog(
+	currentLogLevel: LogLevel,
+	logLevel: LogLevel
+): boolean {
+	return levels.indexOf(logLevel) <= levels.indexOf(currentLogLevel);
+}
+
+/**
+ * Configuration interface for logger instances
+ *
+ * Provides options to customize logger behavior including
+ * disabling logs, setting log levels, and custom log handlers.
+ */
+export interface Logger {
+	/**
+	 * Whether logging is disabled
+	 *
+	 * When true, no logs will be published regardless of log level
+	 */
+	disabled?: boolean;
+
+	/**
+	 * The minimum log level to publish
+	 *
+	 * Only logs with this level or higher severity will be published
+	 * Note that 'success' is excluded as it's typically handled as 'info'
+	 */
+	level?: Exclude<LogLevel, 'success'>;
+
+	/**
+	 * Custom log handler function
+	 *
+	 * When provided, this function will be called instead of console methods
+	 *
+	 * @param level - The severity level of the log message
+	 * @param message - The message to log
+	 * @param args - Additional data to include in the log
+	 */
+	log?: (
+		level: Exclude<LogLevel, 'success'>,
+		message: string,
+		...args: unknown[]
+	) => void;
+}
+
+/**
+ * Type representing the parameters for log handlers
+ *
+ * This utility type extracts parameter types from the Logger.log function,
+ * excluding the first parameter (log level).
+ */
+export type LogHandlerParams = Parameters<NonNullable<Logger['log']>> extends [
+	LogLevel,
+	...infer Rest,
+]
+	? Rest
+	: never;
+
+/**
+ * ANSI color codes for terminal output formatting
+ *
+ * Used to add color and styling to log messages in terminal environments
+ *
+ * @internal
+ */
+const colors = {
+	reset: '\x1b[0m',
+	bright: '\x1b[1m',
+	dim: '\x1b[2m',
+	underscore: '\x1b[4m',
+	blink: '\x1b[5m',
+	reverse: '\x1b[7m',
+	hidden: '\x1b[8m',
+	fg: {
+		black: '\x1b[30m',
+		red: '\x1b[31m',
+		green: '\x1b[32m',
+		yellow: '\x1b[33m',
+		blue: '\x1b[34m',
+		magenta: '\x1b[35m',
+		cyan: '\x1b[36m',
+		white: '\x1b[37m',
+	},
+	bg: {
+		black: '\x1b[40m',
+		red: '\x1b[41m',
+		green: '\x1b[42m',
+		yellow: '\x1b[43m',
+		blue: '\x1b[44m',
+		magenta: '\x1b[45m',
+		cyan: '\x1b[46m',
+		white: '\x1b[47m',
+	},
+};
+
+/**
+ * Mapping of log levels to their corresponding colors
+ *
+ * @internal
+ */
+const levelColors: Record<LogLevel, string> = {
+	info: colors.fg.blue,
+	success: colors.fg.green,
+	warn: colors.fg.yellow,
+	error: colors.fg.red,
+	debug: colors.fg.magenta,
+};
+
+/**
+ * Formats a log message with timestamp, level indicator, and styling
+ *
+ * @param level - The severity level of the message
+ * @param message - The message content to format
+ * @returns The formatted message string with ANSI color codes
+ *
+ * @internal
+ */
+const formatMessage = (level: LogLevel, message: string): string => {
+	const timestamp = new Date().toISOString();
+	return `${colors.dim}${timestamp}${colors.reset} ${
+		levelColors[level]
+	}${level.toUpperCase()}${colors.reset} ${colors.bright}[c15t]:${
+		colors.reset
+	} ${message}`;
+};
+
+/**
+ * Creates a configured logger instance with methods for each log level
+ *
+ * @param options - Configuration options for the logger
+ * @returns An object with methods for each log level
+ *
+ * @example
+ * ```ts
+ * // Create a logger that only shows warnings and errors
+ * const logger = createLogger({ level: 'warn' });
+ *
+ * // These will be output
+ * logger.error('This is an error');
+ * logger.warn('This is a warning');
+ *
+ * // These will be suppressed
+ * logger.info('This info won\'t be shown');
+ * logger.debug('This debug message won\'t be shown');
+ * ```
+ */
+export const createLogger = (
+	options?: Logger
+): Record<LogLevel, (...params: LogHandlerParams) => void> => {
+	const enabled = options?.disabled !== true;
+	const logLevel = options?.level ?? 'error';
+
+	/**
+	 * Internal function that handles the actual logging logic
+	 *
+	 * @param level - The severity level of the log
+	 * @param message - The message to log
+	 * @param args - Additional data to include in the log
+	 *
+	 * @internal
+	 */
+	const LogFunc = (
+		level: LogLevel,
+		message: string,
+		args: unknown[] = []
+	): void => {
+		if (!enabled || !shouldPublishLog(logLevel, level)) {
+			return;
+		}
+
+		const formattedMessage = formatMessage(level, message);
+
+		if (!options || typeof options.log !== 'function') {
+			if (level === 'error') {
+				// biome-ignore lint/suspicious/noConsole: Logger implementation
+				console.error(formattedMessage, ...args);
+			} else if (level === 'warn') {
+				// biome-ignore lint/suspicious/noConsole: Logger implementation
+				console.warn(formattedMessage, ...args);
+			} else if (level === 'info') {
+				// biome-ignore lint/suspicious/noConsole: Logger implementation
+				// biome-ignore lint/suspicious/noConsoleLog: Logger implementation
+				console.log(formattedMessage, ...args);
+			} else if (level === 'debug') {
+				// biome-ignore lint/suspicious/noConsole: Logger implementation
+				console.debug(formattedMessage, ...args);
+			} else if (level === 'success') {
+				// biome-ignore lint/suspicious/noConsole: Logger implementation
+				// biome-ignore lint/suspicious/noConsoleLog: Logger implementation
+				console.log(formattedMessage, ...args);
+			}
+			return;
+		}
+
+		options.log(level === 'success' ? 'info' : level, message, ...args);
+	};
+
+	return Object.fromEntries(
+		levels.map((level) => [
+			level,
+			(...[message, ...args]: LogHandlerParams) =>
+				LogFunc(level, message, args),
+		])
+	) as Record<LogLevel, (...params: LogHandlerParams) => void>;
+};
+
+/**
+ * Default logger instance with standard configuration
+ *
+ * Ready-to-use logger with default settings (logs errors only)
+ *
+ * @example
+ * ```ts
+ * import { logger } from './logger';
+ *
+ * logger.error('Something went wrong');
+ * logger.info('This won\'t be shown with default settings');
+ * ```
+ */
+export const logger = createLogger();

package/src/utils/url.ts

@@ -0,0 +1,194 @@
+import { BASE_ERROR_CODES, C15TError } from '~/error';
+import { env } from '../utils/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 {C15TError} When the provided URL is invalid
+ *
+ * @internal
+ */
+function checkHasPath(url: string): boolean {
+	try {
+		const parsedUrl = new URL(url);
+		return parsedUrl.pathname !== '/';
+	} catch {
+		throw new C15TError(
+			`Invalid base URL: ${url}. Please provide a valid base URL.`,
+			{
+				code: BASE_ERROR_CODES.BAD_REQUEST,
+				status: 400,
+				data: {
+					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 {C15TError} 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 {C15TError} 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);
+	}
+
+	if (typeof window !== 'undefined' && window.location) {
+		return withPath(window.location.origin, path);
+	}
+	return undefined;
+}
+
+/**
+ * Extracts the origin component from a URL
+ *
+ * @param url - The URL to extract the origin from
+ * @returns The origin of the URL or null if invalid
+ *
+ * @example
+ * ```ts
+ * getOrigin('https://example.com/path'); // 'https://example.com'
+ * getOrigin('invalid-url'); // null
+ * ```
+ */
+export function getOrigin(url: string) {
+	try {
+		const parsedUrl = new URL(url);
+		return parsedUrl.origin;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Extracts the protocol component from a URL
+ *
+ * @param url - The URL to extract the protocol from
+ * @returns The protocol of the URL (including colon) or null if invalid
+ *
+ * @example
+ * ```ts
+ * getProtocol('https://example.com'); // 'https:'
+ * getProtocol('http://example.com'); // 'http:'
+ * getProtocol('invalid-url'); // null
+ * ```
+ */
+export function getProtocol(url: string) {
+	try {
+		const parsedUrl = new URL(url);
+		return parsedUrl.protocol;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Checks if a string is a valid URL with a protocol
+ *
+ * Determines if the URL includes a protocol component (e.g., 'http://', 'https://'),
+ * which indicates it's a fully qualified URL rather than a relative path.
+ *
+ * @param url - The URL string to check
+ * @returns Boolean indicating whether the URL includes a protocol
+ *
+ * @example
+ * ```ts
+ * checkURLValidity('https://example.com'); // true
+ * checkURLValidity('example.com'); // false (no protocol)
+ * ```
+ */
+export const checkURLValidity = (url: string) => {
+	const urlPattern = url.includes('://');
+	return urlPattern;
+};
+
+/**
+ * Extracts the host component from a URL
+ *
+ * If the URL is a fully qualified URL with a protocol, it parses the host correctly.
+ * If not, it assumes the entire string is the host.
+ *
+ * @param url - The URL to extract the host from
+ * @returns The host component of the URL
+ *
+ * @example
+ * ```ts
+ * getHost('https://example.com/path'); // 'example.com'
+ * getHost('example.com'); // 'example.com'
+ * ```
+ */
+export function getHost(url: string) {
+	if (url.includes('://')) {
+		const parsedUrl = new URL(url);
+		return parsedUrl.host;
+	}
+	return url;
+}