options.ts

import type { Breadcrumb, BreadcrumbHint } from './breadcrumb';
import type { ErrorEvent, Event, EventHint, TransactionEvent } from './event';
import type { Instrumenter } from './instrumenter';
import type { Integration } from './integration';
import type { CaptureContext } from './scope';
import type { SdkMetadata } from './sdkmetadata';
import type { StackLineParser, StackParser } from './stacktrace';
import type { SamplingContext } from './transaction';
import type { BaseTransportOptions, Transport } from './transport';

export interface ClientOptions<TO extends BaseTransportOptions = BaseTransportOptions> {
  /**
   * Enable debug functionality in the SDK itself
   */
  debug?: boolean;

  /**
   * Specifies whether this SDK should send events to Sentry.
   * Defaults to true.
   */
  enabled?: boolean;

  /** Attaches stacktraces to pure capture message / log integrations */
  attachStacktrace?: boolean;

  /**
   * A flag enabling Sessions Tracking feature.
   * By default, Sessions Tracking is enabled.
   */
  autoSessionTracking?: boolean;

  /**
   * Send SDK Client Reports.
   * By default, Client Reports are enabled.
   */
  sendClientReports?: boolean;

  /**
   * The Dsn used to connect to Sentry and identify the project. If omitted, the
   * SDK will not send any data to Sentry.
   */
  dsn?: string;

  /**
   * The release identifier used when uploading respective source maps. Specify
   * this value to allow Sentry to resolve the correct source maps when
   * processing events.
   */
  release?: string;

  /** The current environment of your application (e.g. "production"). */
  environment?: string;

  /** Sets the distribution for all events */
  dist?: string;

  /**
   * List of integrations that should be installed after SDK was initialized.
   */
  integrations: Integration[];

  /**
   * The instrumenter to use. Defaults to `sentry`.
   * When not set to `sentry`, auto-instrumentation inside of Sentry will be disabled,
   * in favor of using external auto instrumentation.
   *
   * NOTE: Any option except for `sentry` is highly experimental and subject to change!
   */
  instrumenter?: Instrumenter;

  /**
   * A function that takes transport options and returns the Transport object which is used to send events to Sentry.
   * The function is invoked internally when the client is initialized.
   */
  transport: (transportOptions: TO) => Transport;

  /**
   * A stack parser implementation
   * By default, a stack parser is supplied for all supported platforms
   */
  stackParser: StackParser;

  /**
   * Options for the default transport that the SDK uses.
   */
  transportOptions?: Partial<TO>;

  /**
   * Sample rate to determine trace sampling.
   *
   * 0.0 = 0% chance of a given trace being sent (send no traces) 1.0 = 100% chance of a given trace being sent (send
   * all traces)
   *
   * Tracing is enabled if either this or `tracesSampler` is defined. If both are defined, `tracesSampleRate` is
   * ignored.
   */
  tracesSampleRate?: number;

  /**
   * If this is enabled, transactions and trace data will be generated and captured.
   * This will set the `tracesSampleRate` to the recommended default of `1.0` if `tracesSampleRate` is undefined.
   * Note that `tracesSampleRate` and `tracesSampler` take precedence over this option.
   */
  enableTracing?: boolean;

  /**
   * Initial data to populate scope.
   */
  initialScope?: CaptureContext;

  /**
   * The maximum number of breadcrumbs sent with events. Defaults to 100.
   * Sentry has a maximum payload size of 1MB and any events exceeding that payload size will be dropped.
   */
  maxBreadcrumbs?: number;

  /**
   * A global sample rate to apply to all events.
   *
   * 0.0 = 0% chance of a given event being sent (send no events) 1.0 = 100% chance of a given event being sent (send
   * all events)
   */
  sampleRate?: number;

  /** Maximum number of chars a single value can have before it will be truncated. */
  maxValueLength?: number;

  /**
   * Maximum number of levels that normalization algorithm will traverse in objects and arrays.
   * Used when normalizing an event before sending, on all of the listed attributes:
   * - `breadcrumbs.data`
   * - `user`
   * - `contexts`
   * - `extra`
   * Defaults to `3`. Set to `0` to disable.
   */
  normalizeDepth?: number;

  /**
   * Maximum number of properties or elements that the normalization algorithm will output in any single array or object included in the normalized event.
   * Used when normalizing an event before sending, on all of the listed attributes:
   * - `breadcrumbs.data`
   * - `user`
   * - `contexts`
   * - `extra`
   * Defaults to `1000`
   */
  normalizeMaxBreadth?: number;

  /**
   * Controls how many milliseconds to wait before shutting down. The default is
   * SDK-specific but typically around 2 seconds. Setting this too low can cause
   * problems for sending events from command line applications. Setting it too
   * high can cause the application to block for users with network connectivity
   * problems.
   */
  shutdownTimeout?: number;

  /**
   * A pattern for error messages which should not be sent to Sentry.
   * By default, all errors will be sent.
   */
  ignoreErrors?: Array<string | RegExp>;

  /**
   * A pattern for transaction names which should not be sent to Sentry.
   * By default, all transactions will be sent.
   */
  ignoreTransactions?: Array<string | RegExp>;

  /**
   * A URL to an envelope tunnel endpoint. An envelope tunnel is an HTTP endpoint
   * that accepts Sentry envelopes for forwarding. This can be used to force data
   * through a custom server independent of the type of data.
   */
  tunnel?: string;

  /**
   * Controls if potentially sensitive data should be sent to Sentry by default.
   * Note that this only applies to data that the SDK is sending by default
   * but not data that was explicitly set (e.g. by calling `Sentry.setUser()`).
   *
   * Defaults to `false`.
   *
   * NOTE: This option currently controls only a few data points in a selected
   * set of SDKs. The goal for this option is to eventually control all sensitive
   * data the SDK sets by default. However, this would be a breaking change so
   * until the next major update this option only controls data points which were
   * added in versions above `7.9.0`.
   */
  sendDefaultPii?: boolean;

  /**
   * Set of metadata about the SDK that can be internally used to enhance envelopes and events,
   * and provide additional data about every request.
   */
  _metadata?: SdkMetadata;

  /**
   * Options which are in beta, or otherwise not guaranteed to be stable.
   */
  _experiments?: {
    [key: string]: any;
  };

  /**
   * A pattern for error URLs which should exclusively be sent to Sentry.
   * This is the opposite of {@link Options.denyUrls}.
   * By default, all errors will be sent.
   *
   * Requires the use of the `InboundFilters` integration.
   */
  allowUrls?: Array<string | RegExp>;

  /**
   * A pattern for error URLs which should not be sent to Sentry.
   * To allow certain errors instead, use {@link Options.allowUrls}.
   * By default, all errors will be sent.
   *
   * Requires the use of the `InboundFilters` integration.
   */
  denyUrls?: Array<string | RegExp>;

  /**
   * Function to compute tracing sample rate dynamically and filter unwanted traces.
   *
   * Tracing is enabled if either this or `tracesSampleRate` is defined. If both are defined, `tracesSampleRate` is
   * ignored.
   *
   * Will automatically be passed a context object of default and optional custom data. See
   * {@link Transaction.samplingContext} and {@link Hub.startTransaction}.
   *
   * @returns A sample rate between 0 and 1 (0 drops the trace, 1 guarantees it will be sent). Returning `true` is
   * equivalent to returning 1 and returning `false` is equivalent to returning 0.
   */
  tracesSampler?: (samplingContext: SamplingContext) => number | boolean;

  // TODO (v8): Narrow the response type to `ErrorEvent` - this is technically a breaking change.
  /**
   * An event-processing callback for error and message events, guaranteed to be invoked after all other event
   * processors, which allows an event to be modified or dropped.
   *
   * Note that you must return a valid event from this callback. If you do not wish to modify the event, simply return
   * it at the end. Returning `null` will cause the event to be dropped.
   *
   * @param event The error or message event generated by the SDK.
   * @param hint Event metadata useful for processing.
   * @returns A new event that will be sent | null.
   */
  beforeSend?: (event: ErrorEvent, hint: EventHint) => PromiseLike<Event | null> | Event | null;

  // TODO (v8): Narrow the response type to `TransactionEvent` - this is technically a breaking change.
  /**
   * An event-processing callback for transaction events, guaranteed to be invoked after all other event
   * processors. This allows an event to be modified or dropped before it's sent.
   *
   * Note that you must return a valid event from this callback. If you do not wish to modify the event, simply return
   * it at the end. Returning `null` will cause the event to be dropped.
   *
   * @param event The error or message event generated by the SDK.
   * @param hint Event metadata useful for processing.
   * @returns A new event that will be sent | null.
   */
  beforeSendTransaction?: (event: TransactionEvent, hint: EventHint) => PromiseLike<Event | null> | Event | null;

  /**
   * A callback invoked when adding a breadcrumb, allowing to optionally modify
   * it before adding it to future events.
   *
   * Note that you must return a valid breadcrumb from this callback. If you do
   * not wish to modify the breadcrumb, simply return it at the end.
   * Returning null will cause the breadcrumb to be dropped.
   *
   * @param breadcrumb The breadcrumb as created by the SDK.
   * @returns The breadcrumb that will be added | null.
   */
  beforeBreadcrumb?: (breadcrumb: Breadcrumb, hint?: BreadcrumbHint) => Breadcrumb | null;
}

/** Base configuration options for every SDK. */
export interface Options<TO extends BaseTransportOptions = BaseTransportOptions>
  extends Omit<Partial<ClientOptions<TO>>, 'integrations' | 'transport' | 'stackParser'> {
  /**
   * If this is set to false, default integrations will not be added, otherwise this will internally be set to the
   * recommended default integrations.
   */
  defaultIntegrations?: false | Integration[];

  /**
   * List of integrations that should be installed after SDK was initialized.
   * Accepts either a list of integrations or a function that receives
   * default integrations and returns a new, updated list.
   */
  integrations?: Integration[] | ((integrations: Integration[]) => Integration[]);

  /**
   * A function that takes transport options and returns the Transport object which is used to send events to Sentry.
   * The function is invoked internally during SDK initialization.
   * By default, the SDK initializes its default transports.
   */
  transport?: (transportOptions: TO) => Transport;

  /**
   * A stack parser implementation or an array of stack line parsers
   * By default, a stack parser is supplied for all supported browsers
   */
  stackParser?: StackParser | StackLineParser[];
}