Error Handling & Processing

/**
 * Custom error class for Sentry-specific errors
 */
class SentryError extends Error {
  /** Log level for the error */
  logLevel?: string;
  
  /**
   * Creates a new SentryError
   * @param message - Error message
   * @param logLevel - Optional log level (default: 'error')
   */
  constructor(message: string, logLevel?: string);
}

import { SentryError } from "@sentry/core"; // ✅ Recommended (was @sentry/utils)

const error = new SentryError("Configuration is invalid", "warn");
throw error;

/**
 * Type guard for Error objects
 * @param wat - Value to check
 * @returns True if value is an Error
 */
function isError(wat: unknown): wat is Error;

/**
 * Type guard for ErrorEvent objects (browser events)
 * @param wat - Value to check  
 * @returns True if value is an ErrorEvent
 */
function isErrorEvent(wat: unknown): wat is ErrorEvent;

/**
 * Type guard for DOMError objects
 * @param wat - Value to check
 * @returns True if value is a DOMError
 */
function isDOMError(wat: unknown): wat is DOMError;

/**
 * Type guard for DOMException objects
 * @param wat - Value to check
 * @returns True if value is a DOMException  
 */
function isDOMException(wat: unknown): wat is DOMException;

import { isError, isErrorEvent, isDOMError } from "@sentry/core";

function handleUnknownError(error: unknown) {
  if (isError(error)) {
    console.log("Standard Error:", error.message);
  } else if (isErrorEvent(error)) {
    console.log("Error Event:", error.error?.message);
  } else if (isDOMError(error)) {
    console.log("DOM Error:", error.name);
  }
}

interface Exception {
  type?: string;
  value?: string;
  mechanism?: Mechanism;
  module?: string;
  thread_id?: number;
  stacktrace?: Stacktrace;
}

interface Mechanism {
  type: string;
  description?: string;
  help_link?: string;
  handled?: boolean;
  synthetic?: boolean;
  data?: { [key: string]: string | boolean };
}

interface Stacktrace {
  frames?: StackFrame[];
  frames_omitted?: [number, number];
}

/**
 * Converts an Error object into a Sentry Exception format
 * @param parser - Stack parser to use for parsing stack trace
 * @param ex - Error object to convert
 * @returns Exception object suitable for Sentry
 */
function exceptionFromError(parser: StackParser, ex: Error): Exception;

/**
 * Extracts exception keys for message generation
 * @param ex - Exception object
 * @returns String representation of exception keys
 */
function extractExceptionKeysForMessage(ex: Exception): string;

/**
 * Adds exception mechanism information to an event
 * @param event - Event to modify
 * @param mechanism - Mechanism data to add
 */
function addExceptionMechanism(
  event: Event,
  mechanism: Partial<Mechanism>
): void;

/**
 * Adds exception type and value to an event
 * @param event - Event to modify
 * @param value - Exception message/value
 * @param type - Exception type/name
 */
function addExceptionTypeValue(
  event: Event,
  value?: string,
  type?: string
): void;

/**
 * Checks or sets the already caught flag on an exception
 * @param exception - Exception to check/modify
 * @returns True if exception was already caught
 */
function checkOrSetAlreadyCaught(exception: Exception): boolean;

/**
 * Applies aggregate errors to an event, extracting nested errors
 * @param exceptionFromErrorImplementation - Function to convert errors to exceptions
 * @param parser - Stack parser instance
 * @param maxValueLimit - Maximum depth for value extraction
 * @param key - Key name for the aggregate error
 * @param limit - Maximum number of nested errors to process
 * @param event - Event to modify
 * @param hint - Optional event hint for additional context
 */
function applyAggregateErrorsToEvent(
  exceptionFromErrorImplementation: (stackParser: StackParser, ex: Error) => Exception,
  parser: StackParser,
  maxValueLimit: number,
  key: string,
  limit: number,
  event: Event,
  hint?: EventHint,
): void;

import { 
  exceptionFromError, 
  addExceptionMechanism, 
  createStackParser,
  nodeStackLineParser 
} from "@sentry/core";

const parser = createStackParser(nodeStackLineParser());

try {
  // Some operation that might fail
  throw new Error("Something went wrong");
} catch (error) {
  if (isError(error)) {
    const exception = exceptionFromError(parser, error);
    
    const event = {
      exception: {
        values: [exception]
      }
    };
    
    // Add mechanism information
    addExceptionMechanism(event, {
      type: "generic",
      handled: true
    });
  }
}