fix capture methods

Author: mydea

packages/node-experimental/src/sdk/api.ts

@@ -5,6 +5,7 @@ import { DEFAULT_ENVIRONMENT, closeSession, makeSession, updateSession } from '@
 import type {
   Breadcrumb,
   BreadcrumbHint,
+  CaptureContext,
   Client,
   Event,
   EventHint,
@@ -17,9 +18,10 @@ import type {
   SeverityLevel,
   User,
 } from '@sentry/types';
-import { GLOBAL_OBJ, consoleSandbox, dateTimestampInSeconds, logger } from '@sentry/utils';
+import { GLOBAL_OBJ, consoleSandbox, dateTimestampInSeconds } from '@sentry/utils';
 
 import { getScopesFromContext, setScopesOnContext } from '../utils/contextData';
+import { ExclusiveEventHintOrCaptureContext, parseEventHintOrCaptureContext } from '../utils/prepareEvent';
 import { getGlobalCarrier } from './globals';
 import { Scope } from './scope';
 import type { CurrentScopes, SentryCarrier } from './types';
@@ -118,18 +120,22 @@ export function configureScope(callback: (scope: Scope) => void): void {
 }
 
 /** Capture an exception to Sentry. */
-export function captureException(exception: unknown, hint?: EventHint): string {
-  return getCurrentScope().captureException(exception, hint);
+export function captureException(exception: unknown, hint?: ExclusiveEventHintOrCaptureContext): string {
+  return getCurrentScope().captureException(exception, parseEventHintOrCaptureContext(hint));
 }
 
 /** Capture a message to Sentry. */
 export function captureMessage(
   message: string,
   // eslint-disable-next-line deprecation/deprecation
-  level?: Severity | SeverityLevel,
-  hint?: EventHint,
+  captureContext?: CaptureContext | Severity | SeverityLevel,
 ): string {
-  return getCurrentScope().captureMessage(message, level, hint);
+  // This is necessary to provide explicit scopes upgrade, without changing the original
+  // arity of the `captureMessage(message, level)` method.
+  const level = typeof captureContext === 'string' ? captureContext : undefined;
+  const context = typeof captureContext !== 'string' ? { captureContext } : undefined;
+
+  return getCurrentScope().captureMessage(message, level, context);
 }
 
 /** Capture a generic event to Sentry. */

packages/node-experimental/src/sdk/hub.ts

@@ -1,10 +1,13 @@
 import type {
   Client,
   CustomSamplingContext,
+  EventHint,
   Hub,
   Integration,
   IntegrationClass,
   Session,
+  Severity,
+  SeverityLevel,
   TransactionContext,
 } from '@sentry/types';
 
@@ -64,8 +67,17 @@ export function getCurrentHub(): Hub {
     withScope,
     getClient,
     getScope: getCurrentScope,
-    captureException,
-    captureMessage,
+    captureException: (exception: unknown, hint?: EventHint) => {
+      return getCurrentScope().captureException(exception, hint);
+    },
+    captureMessage: (
+      message: string,
+      // eslint-disable-next-line deprecation/deprecation
+      level?: Severity | SeverityLevel,
+      hint?: EventHint,
+    ) => {
+      return getCurrentScope().captureMessage(message, level, hint);
+    },
     captureEvent,
     lastEventId,
     addBreadcrumb,

packages/node-experimental/src/utils/prepareEvent.ts

@@ -0,0 +1,58 @@
+import { Scope } from '@sentry/core';
+import { CaptureContext, EventHint, Scope as ScopeInterface, ScopeContext } from '@sentry/types';
+
+/**
+ * This type makes sure that we get either a CaptureContext, OR an EventHint.
+ * It does not allow mixing them, which could lead to unexpected outcomes, e.g. this is disallowed:
+ * { user: { id: '123' }, mechanism: { handled: false } }
+ */
+export type ExclusiveEventHintOrCaptureContext =
+  | (CaptureContext & Partial<{ [key in keyof EventHint]: never }>)
+  | (EventHint & Partial<{ [key in keyof ScopeContext]: never }>);
+
+/**
+ * Parse either an `EventHint` directly, or convert a `CaptureContext` to an `EventHint`.
+ * This is used to allow to update method signatures that used to accept a `CaptureContext` but should now accept an `EventHint`.
+ */
+export function parseEventHintOrCaptureContext(
+  hint: ExclusiveEventHintOrCaptureContext | undefined,
+): EventHint | undefined {
+  if (!hint) {
+    return undefined;
+  }
+
+  // If you pass a Scope or `() => Scope` as CaptureContext, we just return this as captureContext
+  if (hintIsScopeOrFunction(hint)) {
+    return { captureContext: hint };
+  }
+
+  if (hintIsScopeContext(hint)) {
+    return {
+      captureContext: hint,
+    };
+  }
+
+  return hint;
+}
+
+function hintIsScopeOrFunction(
+  hint: CaptureContext | EventHint,
+): hint is ScopeInterface | ((scope: ScopeInterface) => ScopeInterface) {
+  return hint instanceof Scope || typeof hint === 'function';
+}
+
+type ScopeContextProperty = keyof ScopeContext;
+const captureContextKeys: readonly ScopeContextProperty[] = [
+  'user',
+  'level',
+  'extra',
+  'contexts',
+  'tags',
+  'fingerprint',
+  'requestSession',
+  'propagationContext',
+] as const;
+
+function hintIsScopeContext(hint: Partial<ScopeContext> | EventHint): hint is Partial<ScopeContext> {
+  return Object.keys(hint).some(key => captureContextKeys.includes(key as ScopeContextProperty));
+}