Error and Event Capture

/**
 * Capture an exception and send it to Sentry
 * @param exception - The exception to capture (Error object, string, or any value)
 * @param captureContext - Optional context to attach to the event
 * @returns Event ID of the captured exception
 */
function captureException(exception: any, captureContext?: CaptureContext): string;

import * as Sentry from "@sentry/node";

// Capture a basic exception
try {
  throw new Error("Something went wrong!");
} catch (error) {
  Sentry.captureException(error);
}

// Capture with additional context
try {
  processUserData(userData);
} catch (error) {
  Sentry.captureException(error, {
    tags: {
      section: "user-processing",
    },
    extra: {
      userData: userData,
      timestamp: Date.now(),
    },
    user: {
      id: userId,
      email: userEmail,
    },
    level: "error",
  });
}

// Capture with scope callback
try {
  performCriticalOperation();
} catch (error) {
  Sentry.captureException(error, (scope) => {
    scope.setTag("operation", "critical");
    scope.setLevel("fatal");
    scope.setContext("operation_details", {
      startTime: operationStartTime,
      parameters: operationParams,
    });
    return scope;
  });
}

/**
 * Capture a message and send it to Sentry
 * @param message - The message to capture
 * @param level - Severity level of the message (optional, defaults to 'info')
 * @param captureContext - Optional context to attach to the event
 * @returns Event ID of the captured message
 */
function captureMessage(
  message: string, 
  level?: SeverityLevel, 
  captureContext?: CaptureContext
): string;

import * as Sentry from "@sentry/node";

// Basic message capture
Sentry.captureMessage("User performed important action");

// Message with severity level
Sentry.captureMessage("Database connection slow", "warning");

// Message with context
Sentry.captureMessage("Payment processed successfully", "info", {
  tags: {
    component: "payment",
    method: "stripe",
  },
  extra: {
    amount: paymentAmount,
    currency: "USD",
    transactionId: txnId,
  },
});

/**
 * Capture a custom event and send it to Sentry
 * @param event - The event object to capture
 * @param hint - Optional hint for event processing
 * @returns Event ID of the captured event
 */
function captureEvent(event: Event, hint?: EventHint): string;

import * as Sentry from "@sentry/node";

// Capture custom event
Sentry.captureEvent({
  message: "Custom business logic event",
  level: "info",
  tags: {
    component: "business-logic",
    feature: "user-onboarding",
  },
  extra: {
    step: "email-verification",
    userId: user.id,
    timestamp: Date.now(),
  },
});

// Capture with fingerprint for grouping
Sentry.captureEvent({
  message: "Rate limit exceeded",
  level: "warning",
  fingerprint: ["rate-limit", "{{ default }}"],
  tags: {
    endpoint: "/api/users",
    method: "POST",
  },
  extra: {
    rateLimitKey: rateLimitKey,
    requestCount: currentRequestCount,
    timeWindow: timeWindow,
  },
});

/**
 * Capture user feedback for an event
 * @param feedback - User feedback object
 * @returns Event ID of the captured feedback
 */
function captureFeedback(feedback: UserFeedback): string;

import * as Sentry from "@sentry/node";

// Capture user feedback for the last event
const eventId = Sentry.captureException(error);
Sentry.captureFeedback({
  event_id: eventId,
  email: "user@example.com",
  name: "John Doe",
  comments: "The application crashed when I tried to upload a file",
});

// Capture feedback with all optional fields
Sentry.captureFeedback({
  event_id: lastEventId,
  email: user.email,
  name: user.name,
  comments: feedbackText,
  associatedEventId: eventId, // Alternative to event_id
});

/**
 * Get the ID of the last event that was sent to Sentry
 * @returns Event ID string or undefined if no events have been sent
 */
function lastEventId(): string | undefined;

import * as Sentry from "@sentry/node";

// Capture an exception and get its ID
Sentry.captureException(new Error("Something failed"));
const eventId = Sentry.lastEventId();

if (eventId) {
  console.log(`Error reported with ID: ${eventId}`);
  // You could store this ID for user support tickets
}

/**
 * Add a breadcrumb to the current scope
 * @param breadcrumb - Breadcrumb object with message, category, and other data
 * @param hint - Optional hint for breadcrumb processing
 */
function addBreadcrumb(breadcrumb: Breadcrumb, hint?: BreadcrumbHint): void;

import * as Sentry from "@sentry/node";

// Add basic breadcrumb
Sentry.addBreadcrumb({
  message: "User clicked login button",
  category: "ui.click",
  level: "info",
});

// Add breadcrumb with data
Sentry.addBreadcrumb({
  message: "Database query executed",
  category: "query",
  level: "info",
  data: {
    query: "SELECT * FROM users WHERE id = ?",
    duration: 145,
    rowCount: 1,
  },
});

// Add navigation breadcrumb
Sentry.addBreadcrumb({
  message: "Navigation to /dashboard",
  category: "navigation",
  level: "info",
  data: {
    from: "/login",
    to: "/dashboard",
    method: "GET",
  },
});

// Add HTTP request breadcrumb
Sentry.addBreadcrumb({
  message: "HTTP request",
  category: "http",
  level: "info",
  data: {
    url: "https://api.example.com/users",
    method: "POST",
    status_code: 201,
    response_time: 234,
  },
});

type CaptureContext = 
  | Partial<ScopeContext> 
  | ((scope: Scope) => Scope);

interface ScopeContext {
  /** Tags to attach to the event */
  tags?: { [key: string]: Primitive };
  /** Extra data to attach to the event */
  extra?: { [key: string]: any };
  /** Contexts to attach to the event */
  contexts?: { [key: string]: Context };
  /** User information */
  user?: User;
  /** Severity level */
  level?: SeverityLevel;
  /** Event fingerprint for grouping */
  fingerprint?: string[];
}

interface Event {
  /** Event ID */
  event_id?: string;
  /** Event message */
  message?: string;
  /** Event timestamp */
  timestamp?: number;
  /** Event level */
  level?: SeverityLevel;
  /** Event platform */
  platform?: string;
  /** Event logger name */
  logger?: string;
  /** Event server name */
  server_name?: string;
  /** Event release */
  release?: string;
  /** Event environment */
  environment?: string;
  /** Event tags */
  tags?: { [key: string]: Primitive };
  /** Event extra data */
  extra?: { [key: string]: any };
  /** Event contexts */
  contexts?: { [key: string]: Context };
  /** Event user */
  user?: User;
  /** Event breadcrumbs */
  breadcrumbs?: Breadcrumb[];
  /** Event fingerprint */
  fingerprint?: string[];
  /** Event exception */
  exception?: {
    values?: Exception[];
  };
  /** Event stacktrace */
  stacktrace?: Stacktrace;
}

interface EventHint {
  /** Original exception object */
  originalException?: any;
  /** Synthetic exception created for the event */
  syntheticException?: Error;
  /** Event ID */
  event_id?: string;
  /** Additional context data */
  data?: any;
}

interface UserFeedback {
  /** Event ID that the feedback is associated with */
  event_id: string;
  /** User's email address */
  email: string;  
  /** User's name */
  name: string;
  /** User's feedback comments */
  comments: string;
}

interface Breadcrumb {
  /** Breadcrumb message */
  message?: string;
  /** Breadcrumb category */
  category?: string;
  /** Breadcrumb severity level */
  level?: SeverityLevel;
  /** Breadcrumb timestamp */
  timestamp?: number;
  /** Breadcrumb type */
  type?: string;
  /** Additional breadcrumb data */
  data?: { [key: string]: any };
}

interface BreadcrumbHint {
  /** Input data for the breadcrumb */
  input?: any;
  /** DOM event that triggered the breadcrumb */
  event?: Event;
  /** XMLHttpRequest object */
  xhr?: XMLHttpRequest;
}

type SeverityLevel = "fatal" | "error" | "warning" | "log" | "info" | "debug";