@c15t/backend 1.8.0 → 2.0.0-rc.0

package/src/pkgs/results/core/error-class.ts

@@ -1,297 +0,0 @@
-import { ORPCError } from '@orpc/server';
-import type { DoubleTieErrorOptions, ErrorMessageType } from '../types';
-import { ERROR_CATEGORIES, ERROR_CODES } from './error-codes';
-import { withSpan } from './tracing';
-
-/**
- * Custom error class for DoubleTie errors that extends ORPCError.
- *
- * This class directly extends ORPCError to provide seamless integration with oRPC
- * while adding application-specific error properties and context.
- *
- * @remarks
- * The DoubleTieError is designed to be compatible with HTTP responses and API error handling
- * while providing rich context for debugging and error reporting.
- *
- * @example
- * ```typescript
- * // Create and throw a DoubleTie error
- * throw new DoubleTieError('Failed to update subject preferences', {
- *   code: ERROR_CODES.FAILED_TO_UPDATE_CONSENT,
- *   status: 400,
- *   meta: { subjectId: 'sub_x1pftyoufsm7xgo1kv', preferences: { analytics: true } }
- * });
- *
- * // Catch and handle a DoubleTie error
- * try {
- *   // some operation
- * } catch (err) {
- *   if (DoubleTieError.isDoubleTieError(err)) {
- *     console.error(`${err.code}: ${err.message} (${err.category})`);
- *   }
- * }
- * ```
- */
-export class DoubleTieError extends ORPCError<string, Record<string, unknown>> {
-	/**
-	 * Error category that groups related errors.
-	 * Defaults to 'unexpected' if not specified.
-	 *
-	 * @see ERROR_CATEGORIES for predefined categories
-	 */
-	readonly category: string;
-
-	/**
-	 * Additional metadata about the error.
-	 * Can contain any contextual information that might help debugging.
-	 */
-	readonly meta: Record<string, unknown>;
-
-	/**
-	 * HTTP status code for the error
-	 */
-	readonly statusCode: number;
-
-	/**
-	 * Creates a new DoubleTieError instance.
-	 *
-	 * @param message - Human-readable error message
-	 * @param options - Configuration options for the error
-	 * @param options.code - Error code identifying the error type
-	 * @param options.status - HTTP status code (defaults to 500)
-	 * @param options.category - Error category (defaults to 'unexpected')
-	 * @param options.cause - Original error that caused this error
-	 * @param options.meta - Additional metadata about the error
-	 *
-	 * @example
-	 * ```typescript
-	 * const error = new DoubleTieError('Authentication failed', {
-	 *   code: ERROR_CODES.UNAUTHORIZED,
-	 *   status: 401,
-	 *   category: ERROR_CATEGORIES.AUTH,
-	 *   meta: { userId: 'usr_abc123' }
-	 * });
-	 * ```
-	 */
-	constructor(
-		message: string,
-		options: DoubleTieErrorOptions = {
-			code: ERROR_CODES.UNKNOWN_ERROR,
-			status: 500,
-			category: ERROR_CATEGORIES.UNEXPECTED,
-			cause: undefined,
-			meta: {},
-		}
-	) {
-		// Call ORPCError constructor with code and options
-		super(options.code ?? ERROR_CODES.UNKNOWN_ERROR, {
-			message,
-			cause: options.cause,
-			data: options.meta ?? {},
-		});
-
-		// Set name explicitly
-		this.name = 'DoubleTieError';
-
-		// Initialize additional properties
-		this.category = options.category ?? ERROR_CATEGORIES.UNEXPECTED;
-		this.meta = options.meta ?? {};
-		this.statusCode = options.status ?? 500;
-
-		// Add tracing after initialization
-		withSpan('create_doubletie_error', async (span) => {
-			span.setAttributes({
-				'error.name': this.constructor.name,
-				'error.message': message,
-				'error.code': this.code,
-				'error.status': this.statusCode,
-				'error.category': this.category,
-				'error.has_cause': !!this.cause,
-				'error.cause_type':
-					this.cause instanceof Error
-						? this.cause.constructor.name
-						: typeof this.cause,
-				'error.has_meta': !!this.meta,
-			});
-
-			if (this.cause instanceof Error) {
-				span.recordException(this.cause);
-			}
-		});
-
-		// Capture stack trace
-		if (Error.captureStackTrace) {
-			Error.captureStackTrace(this, this.constructor);
-		}
-	}
-
-	/**
-	 * Type guard to check if an unknown error is a DoubleTieError.
-	 *
-	 * @param error - The error to check
-	 * @returns True if the error is a DoubleTieError, false otherwise
-	 */
-	static isDoubleTieError(error: unknown): error is DoubleTieError {
-		return error instanceof DoubleTieError;
-	}
-
-	/**
-	 * Convert the error to a JSON-serializable object matching oRPC's error format.
-	 * Override of the parent ORPCError toJSON method.
-	 */
-	toJSON() {
-		// Extract validation error details if present
-		const validationErrorMessage = this.meta?.validationErrors
-			? String(this.meta.validationErrors)
-			: undefined;
-
-		// Parse stack trace into an array if available
-		const stackTrace = this.stack
-			? this.stack
-					.split('\n')
-					.map((line) => line.trim())
-					.filter((line) => line && !line.includes('Error: '))
-			: [];
-
-		// Create the result object with proper structure matching oRPC error format
-		return {
-			code: this.code,
-			message: validationErrorMessage || this.message,
-			// oRPC expects a status field rather than statusCode
-			status: this.statusCode,
-			// Required field in ORPCErrorJSON
-			defined: true,
-			data: {
-				category: this.category,
-				meta: this.meta,
-				...(process.env.NODE_ENV === 'production' ? {} : { stack: stackTrace }),
-				// Add originalMessage if we're showing validation error as main message
-				...(validationErrorMessage && this.message
-					? { originalMessage: this.message }
-					: {}),
-				// Add cause information if available
-				...(this.cause
-					? {
-							cause:
-								this.cause instanceof Error
-									? {
-											name: this.cause.name,
-											message: this.cause.message,
-											stack: this.cause.stack
-												? this.cause.stack
-														.split('\n')
-														.map((line) => line.trim())
-												: undefined,
-										}
-									: this.cause,
-						}
-					: {}),
-			},
-		};
-	}
-
-	/**
-	 * Creates a DoubleTieError from an HTTP response object.
-	 *
-	 * @param response - The HTTP Response object
-	 * @param data - Optional response data that was already parsed
-	 * @returns A new DoubleTieError instance with information from the response
-	 */
-	static fromResponse(response: Response, data?: unknown): DoubleTieError {
-		// Extract error message from response or data
-		let message = `HTTP error ${response.status}`;
-		let errorCode: ErrorMessageType = `HTTP ${response.status}`;
-		let errorMeta: Record<string, unknown> = {};
-
-		// 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') {
-				errorCode = errorObj.code;
-			}
-
-			// Include any additional error data
-			if (typeof errorObj.data === 'object' && errorObj.data !== null) {
-				errorMeta = errorObj.data as Record<string, unknown>;
-			}
-		}
-
-		return new DoubleTieError(message, {
-			code: errorCode,
-			status: response.status,
-			meta: errorMeta,
-		});
-	}
-
-	/**
-	 * Creates a new error instance with additional metadata merged with the original.
-	 * Does not modify the original error instance.
-	 *
-	 * @param additionalMeta - Additional metadata to add to the error
-	 * @returns A new DoubleTieError instance with the combined metadata
-	 */
-	withMeta(additionalMeta: Record<string, unknown>): DoubleTieError {
-		return new DoubleTieError(this.message, {
-			code: this.code,
-			status: this.statusCode,
-			category: this.category,
-			cause: this.cause instanceof Error ? this.cause : undefined,
-			meta: { ...this.meta, ...additionalMeta },
-		});
-	}
-
-	/**
-	 * Creates a subclass of DoubleTieError with a custom name.
-	 * Useful for creating domain-specific error classes.
-	 *
-	 * @param name - The name for the new error class
-	 * @returns A new error class extending DoubleTieError
-	 */
-	static createSubclass(name: string): typeof DoubleTieError {
-		const ErrorSubclass = class extends DoubleTieError {
-			constructor(message: string, options: DoubleTieErrorOptions) {
-				super(message, options);
-				Object.defineProperty(this, 'name', { value: name });
-			}
-		};
-
-		Object.defineProperty(ErrorSubclass, 'name', { value: name });
-		return ErrorSubclass;
-	}
-
-	/**
-	 * Format a validation error into a more user-friendly message.
-	 * Especially useful for displaying validation errors from the meta field.
-	 *
-	 * @param error - The DoubleTieError containing validation details
-	 * @returns A formatted string with validation error details
-	 */
-	static formatValidationError(error: DoubleTieError): string {
-		if (!error.meta) {
-			return error.message;
-		}
-
-		let formattedMessage = `${error.message} (${error.code})`;
-
-		// Extract validation errors from meta
-		if (error.meta.validationErrors) {
-			formattedMessage += `\nValidation Errors: ${JSON.stringify(error.meta.validationErrors, null, 2)}`;
-		}
-
-		// Create a new object without validationErrors instead of using delete
-		const otherMeta = Object.fromEntries(
-			Object.entries(error.meta).filter(([key]) => key !== 'validationErrors')
-		);
-
-		if (Object.keys(otherMeta).length > 0) {
-			formattedMessage += `\nAdditional Context: ${JSON.stringify(otherMeta, null, 2)}`;
-		}
-
-		return formattedMessage;
-	}
-}

package/src/pkgs/results/core/error-codes.ts

@@ -1,206 +0,0 @@
-/**
- * Core error codes for DoubleTie applications.
- *
- * 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 common type of error that can occur in any application.
- *
- * @example
- * ```typescript
- * import { CORE_ERROR_CODES, DoubleTieError } from '@doubletie/errors';
- *
- * // Handle a specific error
- * try {
- *   await dataManager.updateRecord(recordId, data);
- * } catch (error) {
- *   if (error instanceof DoubleTieError && error.code === CORE_ERROR_CODES.NOT_FOUND) {
- *     // Handle the specific case where record is not found
- *     console.error('Cannot update: record does not exist');
- *   } else {
- *     // Handle other errors
- *     console.error('Failed to update record:', error.message);
- *   }
- * }
- * ```
- */
-export const ERROR_CODES = Object.freeze({
-	/**
-	 * 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',
-
-	/**
-	 * 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',
-
-	/**
-	 * 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',
-
-	/**
-	 * The provided configuration is invalid or contains errors.
-	 * This may occur when initializing the system with incorrect settings.
-	 */
-	INVALID_CONFIGURATION: 'Invalid configuration',
-
-	/**
-	 * 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',
-
-	/**
-	 * 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',
-
-	/**
-	 * A network-related error occurred.
-	 * This may occur when network requests fail due to connectivity issues.
-	 */
-	NETWORK_ERROR: 'Network error',
-
-	/**
-	 * 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',
-
-	/**
-	 * 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',
-
-	/**
-	 * Validation of input data failed.
-	 * This may occur when input data does not meet schema requirements or other validation rules.
-	 */
-	VALIDATION_ERROR: 'Validation error',
-
-	/**
-	 * An unexpected error occurred.
-	 * This is a general error for unexpected exceptions that don't fit other categories.
-	 */
-	UNEXPECTED: 'Unexpected error',
-});
-
-/**
- * Error categories for organizing errors by domain
- */
-export const ERROR_CATEGORIES = Object.freeze({
-	VALIDATION: 'validation',
-	AUTHORIZATION: 'authorization',
-	STORAGE: 'storage',
-	NETWORK: 'network',
-	PLUGIN: 'plugin',
-	CONFIGURATION: 'configuration',
-	UNEXPECTED: 'unexpected',
-});
-
-/**
- * Utility function to create custom error categories
- *
- * @param categories - Record of category names and their string values
- * @returns The categories object with const assertion
- *
- * @example
- * ```typescript
- * const MY_ERROR_CATEGORIES = createErrorCategories({
- *   BILLING: 'billing',
- *   ANALYTICS: 'analytics',
- * });
- * ```
- */
-export function createErrorCategories<
-	TCategories extends Record<string, string>,
->(categories: TCategories): Readonly<TCategories> {
-	return Object.freeze(categories);
-}
-
-/**
- * Utility function to create custom error codes that can be used with DoubleTieError
- *
- * @param codes - Record of error code names and their string message values
- * @returns The error codes object with const assertion
- *
- * @example
- * ```typescript
- * const BILLING_ERROR_CODES = createErrorCodes({
- *   PAYMENT_FAILED: 'Payment processing failed',
- *   INVOICE_NOT_FOUND: 'Invoice not found',
- * });
- *
- * // Later in your code
- * throw new DoubleTieError('Could not charge credit card', {
- *   code: BILLING_ERROR_CODES.PAYMENT_FAILED,
- *   status: 400,
- * });
- * ```
- */
-export function createErrorCodes<TCodes extends Record<string, string>>(
-	codes: TCodes
-): Readonly<TCodes> {
-	return Object.freeze(codes);
-}

package/src/pkgs/results/core/tracing.ts

@@ -1,65 +0,0 @@
-import { type Span, SpanStatusCode, trace } from '@opentelemetry/api';
-import { DoubleTieError } from './error-class';
-
-const tracer = trace.getTracer('@doubletie/results');
-
-/**
- * Creates and manages a span for a function execution
- *
- * @param name - Name of the span
- * @param fn - Function to execute within the span
- * @param attributes - Optional attributes to add to the span
- * @returns The result of the function execution
- */
-export async function withSpan<T>(
-	name: string,
-	fn: (span: Span) => Promise<T> | T,
-	attributes: Record<string, string | number | boolean> = {}
-): Promise<T> {
-	return await tracer.startActiveSpan(name, async (span) => {
-		try {
-			// Add attributes
-			span.setAttributes(attributes);
-
-			// Execute the function
-			const result = await fn(span);
-
-			// End the span successfully
-			span.setStatus({ code: SpanStatusCode.OK });
-			span.end();
-
-			return result;
-		} catch (error) {
-			// Handle errors and add error details to the span
-			if (error instanceof DoubleTieError) {
-				span.setAttributes({
-					'error.type': 'DoubleTieError',
-					'error.code': error.code,
-					'error.statusCode': error.statusCode,
-					'error.message': error.message,
-				});
-
-				if (error.meta) {
-					span.setAttributes({
-						'error.meta': JSON.stringify(error.meta),
-					});
-				}
-			} else {
-				span.setAttributes({
-					'error.type':
-						error instanceof Error ? error.constructor.name : 'Unknown',
-					'error.message':
-						error instanceof Error ? error.message : String(error),
-				});
-			}
-
-			span.setStatus({
-				code: SpanStatusCode.ERROR,
-				message: error instanceof Error ? error.message : String(error),
-			});
-
-			span.end();
-			throw error;
-		}
-	});
-}

package/src/pkgs/results/create-telemetry-options.ts

@@ -1,62 +0,0 @@
-import type { Tracer } from '@opentelemetry/api';
-import type { DoubleTieOptions } from '../types';
-
-/**
- * Configuration options for the telemetry system
- */
-export interface TelemetryConfig {
-	/**
-	 * Custom OpenTelemetry tracer to use instead of the default
-	 */
-	tracer?: Tracer;
-
-	/**
-	 * Whether telemetry should be disabled
-	 */
-	disabled?: boolean;
-
-	/**
-	 * Default attributes to add to all telemetry spans
-	 */
-	defaultAttributes?: Record<string, string | number | boolean>;
-}
-
-/**
- * Creates telemetry configuration from provided options
- *
- * This function merges user-provided telemetry options with sensible defaults,
- * ensuring that service name and version are always properly set.
- *
- * @param appName - The application name to use for service.name attribute
- * @param telemetryConfig - Optional user-provided telemetry configuration
- * @returns Properly structured telemetry options for the OpenTelemetry SDK
- */
-export function createTelemetryOptions(
-	appName = 'c15t',
-	telemetryConfig?: TelemetryConfig
-): DoubleTieOptions['telemetry'] {
-	// Ensure we have a valid semver for OpenTelemetry (which requires valid SemVer)
-	const serviceVersion = process.env.npm_package_version || '1.0.0'; // Use 1.0.0 as fallback instead of 'unknown'
-
-	// Create the base configuration
-	const config: DoubleTieOptions['telemetry'] = {
-		// User can explicitly disable telemetry if needed
-		disabled: telemetryConfig?.disabled ?? false,
-
-		// Use provided tracer if available
-		tracer: telemetryConfig?.tracer,
-
-		// Merge default attributes with user-provided ones
-		defaultAttributes: {
-			// Start with user-provided attributes
-			...(telemetryConfig?.defaultAttributes || {}),
-
-			// Always ensure these core attributes are set
-			// (will override user values if they exist)
-			'service.name': String(appName),
-			'service.version': serviceVersion,
-		},
-	};
-
-	return config;
-}