Fix normalize depth of 3 for contexts.flags, improve docstrings

Author: aliu39

packages/core/src/utils/prepareEvent.ts

@@ -339,6 +339,14 @@ function normalizeEvent(event: Event | null, depth: number, maxBreadth: number):
     });
   }
 
+  // event.contexts.flags (FeatureFlagContext) stores context for our feature
+  // flag integrations. It has a greater nesting depth than our other typed
+  // Contexts, so we re-normalize with a fixed depth of 3 here. We do not want
+  // to skip this in case of conflicting, user-provided context.
+  if (event.contexts && event.contexts.flags && normalized.contexts) {
+    normalized.contexts.flags = normalize(event.contexts.flags, 3, maxBreadth);
+  }
+
   return normalized;
 }
 

packages/launchdarkly/src/core/integration.ts

@@ -1,5 +1,3 @@
-/* eslint-disable @sentry-internal/sdk/no-class-field-initializers */
-
 import * as Sentry from '@sentry/browser';
 import type { Client as SentryClient, Event, EventHint, IntegrationFn } from '@sentry/types';
 import type { LDContext, LDEvaluationDetail, LDInspectionFlagUsedHandler } from 'launchdarkly-js-client-sdk';
@@ -9,15 +7,15 @@ import { insertToFlagBuffer } from '@sentry/utils';
 /**
  * Sentry integration for capturing feature flags from LaunchDarkly.
  *
- * See the [feature flag documentation](TODO:) for more information.
+ * See the [feature flag documentation](https://develop.sentry.dev/sdk/expected-features/#feature-flags) for more information.
  *
  * @example
  * ```
- * import {SentryInspector, launchDarklyIntegration} from '@sentry/launchdarkly';
+ * import {buildSentryFlagUsedInspector, buildLaunchDarklyIntegration} from '@sentry/launchdarkly';
  * import {LDClient} from 'launchdarkly-js-client-sdk';
  *
- * Sentry.init(..., integrations: [launchDarklyIntegration()])
- * const ldClient = LDClient.initialize(..., inspectors: [SentryInspector]);
+ * Sentry.init(..., integrations: [buildLaunchDarklyIntegration()])
+ * const ldClient = LDClient.initialize(..., {inspectors: [buildSentryFlagUsedInspector()]});
  * ```
  */
 export const buildLaunchDarklyIntegration = ((_options?: LaunchDarklyOptions) => {

packages/types/src/context.ts

@@ -127,7 +127,11 @@ export interface MissingInstrumentationContext extends Record<string, unknown> {
   ['javascript.is_cjs']?: boolean;
 }
 
+/**
+ * Used to buffer flag evaluation data on the current scope and attach it to
+ * error events. `values` should be initialized as empty ([]), and it should
+ * only be modified by @sentry/util "FlagBuffer" methods.
+ */
 export interface FeatureFlagContext extends Record<string, unknown> {
-  // This should only be modified by @sentry/util methods (insertToFlagBuffer).
-  readonly values: FeatureFlag[];
+  values: FeatureFlag[];
 }