Context and Scope Management

/**
 * Set user information for all subsequent events
 * @param user - User information object
 */
function setUser(user: User | null): void;

import { setUser } from "@sentry/browser";

// Basic user information
setUser({
  id: "12345",
  email: "user@example.com",
  username: "johndoe",
});

// Extended user information
setUser({
  id: "12345",
  email: "user@example.com",
  username: "johndoe",
  ip_address: "192.168.1.1",
  subscription: "premium",
  first_login: "2023-01-15",
});

// Clear user information
setUser(null);

/**
 * Set a single tag that will be attached to all subsequent events
 * @param key - Tag key
 * @param value - Tag value (must be primitive)
 */
function setTag(key: string, value: Primitive): void;

/**
 * Set multiple tags at once
 * @param tags - Object containing key-value pairs of tags
 */
function setTags(tags: { [key: string]: Primitive }): void;

import { setTag, setTags } from "@sentry/browser";

// Single tag
setTag("environment", "production");
setTag("feature_flag", "new_ui_enabled");

// Multiple tags
setTags({
  component: "checkout",
  user_type: "premium",
  ab_test: "variant_b",
  version: "1.2.3",
});

/**
 * Set extra data that will be attached to all subsequent events
 * @param key - Extra data key
 * @param extra - Extra data value (can be any type)
 */
function setExtra(key: string, extra: Extra): void;

/**
 * Set multiple extra data values at once
 * @param extras - Object containing key-value pairs of extra data
 */
function setExtras(extras: { [key: string]: Extra }): void;

import { setExtra, setExtras } from "@sentry/browser";

// Single extra data
setExtra("last_action", "clicked_checkout_button");
setExtra("cart_items", ["item1", "item2", "item3"]);

// Complex extra data
setExtras({
  user_preferences: {
    theme: "dark",
    language: "en",
    notifications: true,
  },
  session_info: {
    start_time: new Date().toISOString(),
    page_views: 5,
    time_spent: 1200000,
  },
  debug_info: {
    build_number: "1.2.3-456",
    feature_flags: ["flag1", "flag2"],
  },
});

/**
 * Set context data under a specific key
 * @param key - Context namespace key
 * @param context - Context data object
 */
function setContext(key: string, context: Context | null): void;

import { setContext } from "@sentry/browser";

// Device context
setContext("device", {
  name: "iPhone 12",
  family: "iOS",
  model: "iPhone13,1",
  memory_size: 6442450944,
  storage_size: 128000000000,
});

// Application context
setContext("app", {
  name: "My App",
  version: "1.2.3",
  build: "456",
  theme: "dark",
});

// Business context
setContext("business", {
  plan: "premium",
  account_type: "enterprise",
  region: "us-west-2",
});

// Clear context
setContext("device", null);

/**
 * Execute callback with a temporary scope containing isolated context
 * @param callback - Function to execute with the new scope
 */
function withScope(callback: (scope: Scope) => void): void;

/**
 * Execute callback with a temporary isolation scope
 * @param callback - Function to execute with the new isolation scope  
 */
function withIsolationScope(callback: (scope: Scope) => void): void;

import { withScope, captureException, captureMessage } from "@sentry/browser";

// Temporary context for specific operation
withScope((scope) => {
  scope.setTag("operation", "payment_processing");
  scope.setExtra("payment_method", "credit_card");
  scope.setLevel("warning");
  
  try {
    processPayment();
  } catch (error) {
    // This exception will include the temporary context
    captureException(error);
  }
});

// Context isolation for different features
function handleUserAction(action: string) {
  withScope((scope) => {
    scope.setTag("user_action", action);
    scope.setExtra("timestamp", Date.now());
    
    captureMessage(`User performed action: ${action}`, "info");
  });
}

/**
 * Get the current scope for the current context
 * @returns Current scope instance
 */
function getCurrentScope(): Scope;

/**
 * Get the isolation scope (shared across async operations)
 * @returns Isolation scope instance
 */
function getIsolationScope(): Scope;

/**
 * Get the global scope (shared across entire application)
 * @returns Global scope instance
 */
function getGlobalScope(): Scope;

import { getCurrentScope, getIsolationScope } from "@sentry/browser";

// Read current context
const currentScope = getCurrentScope();
const currentUser = currentScope.getUser();
const currentTags = currentScope.getTags();

// Modify current scope
const scope = getCurrentScope();
scope.setTag("modified_at", Date.now().toString());

// Access isolation scope
const isolationScope = getIsolationScope();
isolationScope.setContext("feature", { name: "new_feature", enabled: true });

/**
 * Add a breadcrumb to the current scope
 * @param breadcrumb - Breadcrumb information
 * @param hint - Additional hint information for processing
 */
function addBreadcrumb(breadcrumb: Breadcrumb, hint?: BreadcrumbHint): void;

import { addBreadcrumb } from "@sentry/browser";

// Navigation breadcrumb
addBreadcrumb({
  message: "User navigated to checkout page",
  category: "navigation",
  level: "info",
  data: {
    from: "/cart",
    to: "/checkout",
  },
});

// User interaction breadcrumb
addBreadcrumb({
  message: "Button clicked",
  category: "ui.click",
  level: "info",
  data: {
    button_id: "submit-order",
    component: "CheckoutForm",
  },
});

// HTTP request breadcrumb
addBreadcrumb({
  message: "API request",
  category: "http",
  level: "info",
  data: {
    url: "/api/orders",
    method: "POST",
    status_code: 201,
  },
});

// Custom breadcrumb with timestamp
addBreadcrumb({
  message: "Custom business event",
  category: "business",
  level: "debug",
  timestamp: Date.now() / 1000,
  data: {
    action: "discount_applied",
    discount_code: "SAVE20",
    original_price: 100,
    discounted_price: 80,
  },
});

interface User {
  /** Unique user identifier */
  id?: string;
  
  /** User's username */
  username?: string;
  
  /** User's email address */
  email?: string;
  
  /** User's IP address */
  ip_address?: string;
  
  /** User's subscription level */
  subscription?: string;
  
  /** Additional user properties */
  [key: string]: any;
}

interface Scope {
  /** Set user information */
  setUser(user: User | null): this;
  
  /** Get current user information */
  getUser(): User | undefined;
  
  /** Set a tag */
  setTag(key: string, value: Primitive): this;
  
  /** Set multiple tags */
  setTags(tags: { [key: string]: Primitive }): this;
  
  /** Get current tags */
  getTags(): { [key: string]: Primitive };
  
  /** Set extra data */
  setExtra(key: string, extra: Extra): this;
  
  /** Set multiple extra data values */
  setExtras(extras: { [key: string]: Extra }): this;
  
  /** Get current extra data */
  getExtras(): { [key: string]: Extra };
  
  /** Set context data */
  setContext(key: string, context: Context | null): this;
  
  /** Get context data */
  getContext(key: string): Context | undefined;
  
  /** Set severity level */
  setLevel(level: SeverityLevel): this;
  
  /** Get current severity level */
  getLevel(): SeverityLevel | undefined;
  
  /** Set fingerprint */
  setFingerprint(fingerprint: string[]): this;
  
  /** Get current fingerprint */
  getFingerprint(): string[] | undefined;
  
  /** Add breadcrumb */
  addBreadcrumb(breadcrumb: Breadcrumb, maxBreadcrumbs?: number): this;
  
  /** Get last breadcrumb */
  getLastBreadcrumb(): Breadcrumb | undefined;
  
  /** Clear the scope */
  clear(): this;
  
  /** Add event processor to this scope */
  addEventProcessor(callback: EventProcessor): this;
}

interface Breadcrumb {
  /** Breadcrumb type (e.g., "navigation", "http", "user") */
  type?: string;
  
  /** Severity level */
  level?: SeverityLevel;
  
  /** Associated event ID */
  event_id?: string;
  
  /** Breadcrumb category for grouping */
  category?: string;
  
  /** Human-readable message */
  message?: string;
  
  /** Additional data */
  data?: any;
  
  /** Timestamp when breadcrumb was created */
  timestamp?: number;
}

interface BreadcrumbHint {
  /** Input data that created this breadcrumb */
  input?: any;
  
  /** Additional hint data */
  [key: string]: any;
}

type Primitive = number | string | boolean | bigint | symbol | null | undefined;
type Context = Record<string, any>;
type Extra = any;

import { setUser, setTag, withScope, captureMessage } from "@sentry/browser";

// Global context - applies to all events
setUser({ id: "12345" });
setTag("app_version", "1.0.0");

withScope((scope) => {
  // This scope inherits global context but can override it
  scope.setTag("feature", "checkout"); // Adds to global tags
  scope.setUser({ id: "12345", email: "user@example.com" }); // Extends global user
  
  captureMessage("Checkout started"); // Includes both global and scope context
});

// Good: Isolated context for specific operation
withScope((scope) => {
  scope.setTag("operation", "file_upload");
  processFileUpload();
});

// Avoid: Global context that affects all subsequent events
setTag("operation", "file_upload"); // This affects ALL future events

// Good: Actionable breadcrumbs
addBreadcrumb({
  message: "User clicked submit button",
  category: "ui.click",
  data: { form_id: "payment-form", validation_errors: 0 },
});

// Less useful: Vague breadcrumbs
addBreadcrumb({
  message: "Something happened",
  category: "debug",
});