@launchdarkly/browser-telemetry 0.0.9 → 0.1.1

package/dist/index.d.cts

@@ -0,0 +1,746 @@
+/**
+ * Defines the 'class' of the breadcrumb.
+ */
+type BreadcrumbClass = 'custom' | 'log' | 'navigation' | 'feature-management' | 'ui' | 'http';
+/**
+ * Indicates the severity of the breadcrumb.
+ */
+type BreadcrumbLevel = 'error' | 'warning' | 'info' | 'debug';
+/**
+ * Types of data support with breadcrumbs.
+ */
+type BreadcrumbDataValue = boolean | number | string;
+/**
+ * Defines arbitrary data that may be associated with a breadcrumb.
+ */
+type BreadcrumbData = Record<string, BreadcrumbDataValue>;
+/**
+ * Interface which defines a breadcrumb.
+ */
+interface Breadcrumb {
+    /**
+     * The class of the breadcrumb. This is the top level categorization of breadcrumbs.
+     */
+    class: BreadcrumbClass;
+    /**
+     * When the event associated with the breadcrumb happened. The timestamp is in milliseconds since January 1, 1970
+     * Universal Coordinated Time (UTC)
+     *
+     * For most breadcrumbs this will not be different than the time of breadcrumb creation, but if there is a delay
+     * between the event and breadcrumb capture, then the time of the event should be used instead.
+     */
+    timestamp: number;
+    /**
+     * The level of severity of the breadcrumb. The default choice of level should be `info` if there isn't a clear
+     * reason to use a different level.
+     */
+    level: BreadcrumbLevel;
+    /**
+     * The type of the breadcrumb. Each class may be split into multiple types with the type more specifically
+     * categorizing the type of event.
+     */
+    type?: string;
+    /**
+     * A message associated with the breadcrumb.
+     */
+    message?: string;
+    /**
+     * Any data associated with the breadcrumb.
+     */
+    data?: BreadcrumbData;
+}
+/**
+ * Utility type which allows for easy extension of base breadcrumb type.
+ */
+type ImplementsCrumb<U extends Breadcrumb> = U;
+/**
+ * Type for custom breadcrumbs.
+ */
+type CustomBreadcrumb = ImplementsCrumb<{
+    class: 'custom';
+    timestamp: number;
+    level: BreadcrumbLevel;
+    type?: string;
+    message?: string;
+    data?: BreadcrumbData;
+}>;
+/**
+ * Type for log breadcrumbs.
+ */
+type LogBreadcrumb = ImplementsCrumb<{
+    class: 'log';
+    timestamp: number;
+    level: BreadcrumbLevel;
+    message: string;
+    data?: BreadcrumbData;
+}>;
+/**
+ * Type for navigation breadcrumbs.
+ */
+type NavigationBreadcrumb = ImplementsCrumb<{
+    class: 'navigation';
+    timestamp: number;
+    level: 'info';
+    type?: string;
+    data?: {
+        /**
+         * The location being navigated from. In a web application this would typically be a URL.
+         */
+        from?: string;
+        /**
+         * The location being navigated to. In a web application this would typically be a URL.
+         */
+        to?: string;
+    };
+}>;
+/**
+ * Type for feature management breadcrumbs.
+ */
+type FeatureManagementBreadcrumb = ImplementsCrumb<{
+    class: 'feature-management';
+    timestamp: number;
+    level: 'info';
+    type: 'flag-evaluated' | 'flag-detail-changed';
+    data?: {
+        /**
+         * The flag key.
+         */
+        key?: string;
+        /**
+         * The evaluated value for simple types.
+         */
+        value?: boolean | string | number;
+    };
+}>;
+/**
+ * Type for UI breadcrumbs.
+ */
+type UiBreadcrumb = ImplementsCrumb<{
+    class: 'ui';
+    timestamp: number;
+    level: 'info';
+    type: 'click' | 'input';
+    message: string;
+}>;
+/**
+ * Type for HTTP breadcrumbs.
+ */
+type HttpBreadcrumb = ImplementsCrumb<{
+    class: 'http';
+    timestamp: number;
+    level: 'error' | 'info';
+    type: 'xhr' | 'fetch';
+    data?: {
+        url?: string;
+        method?: string;
+        statusCode: number;
+        statusText: string;
+    };
+}>;
+
+/**
+ * A less constrained version of the LDInspection interface in order to allow for greater compatibility between
+ * SDK versions.
+ *
+ * This interface is not intended for use by application developers and is instead intended as a compatibility bridge
+ * to support multiple SDK versions.
+ */
+interface BrowserTelemetryInspector {
+    /**
+     * The telemetry package only requires flag-detail-changed inspectors and flag-used inspectors.
+     */
+    type: 'flag-used' | 'flag-detail-changed';
+    /**
+     * The name of the inspector, used for debugging purposes.
+     */
+    name: string;
+    /**
+     * Whether the inspector is synchronous.
+     */
+    synchronous: boolean;
+    /**
+     * The method to call when the inspector is triggered.
+     *
+     * The typing here is intentionally loose to allow for greater compatibility between SDK versions.
+     * This function should ONLY be called by an SDK instance and not by an application developer.
+     */
+    method: (...args: any[]) => void;
+}
+
+/**
+ * Minimal client interface which allows for tracking. Should work with all client-side
+ * JavaScript packages.
+ */
+interface LDClientTracking {
+    track(key: string, data?: any, metricValue?: number): void;
+}
+
+/**
+ * Interface for browser-based telemetry collection in LaunchDarkly SDKs.
+ *
+ * This interface provides methods for collecting diagnostic information, error
+ * tracking, and SDK usage data in browser environments. It is designed to work
+ * with LaunchDarkly's JavaScript client-side SDKs for browser environments.
+ */
+interface BrowserTelemetry {
+    /**
+     * Returns an array of active SDK inspectors to use with SDK versions that do
+     * not support hooks.
+     *
+     * @returns An array of {@link BrowserTelemetryInspector} objects.
+     */
+    inspectors(): BrowserTelemetryInspector[];
+    /**
+     * Captures an Error object for telemetry purposes.
+     *
+     * Use this method to manually capture errors during application operation.
+     * Unhandled errors are automatically captured, but this method can be used
+     * to capture errors which were handled, but are still useful for telemetry.
+     *
+     * @param exception The Error object to capture
+     */
+    captureError(exception: Error): void;
+    /**
+     * Captures a browser ErrorEvent for telemetry purposes.
+     *
+     * This method can be used to capture a manually created error event. Use this
+     * function to represent application specific errors which cannot be captured
+     * automatically or are not `Error` types.
+     *
+     * For most errors {@link captureError} should be used.
+     *
+     * @param errorEvent The ErrorEvent to capture
+     */
+    captureErrorEvent(errorEvent: ErrorEvent): void;
+    /**
+     * Add a breadcrumb which will be included with telemetry events.
+     *
+     * Many breadcrumbs can be automatically captured, but this method can be
+     * used for capturing manual breadcrumbs. For application specific breadcrumbs
+     * the {@link CustomBreadcrumb} type can be used.
+     *
+     * @param breadcrumb The breadcrumb to add.
+     */
+    addBreadcrumb(breadcrumb: Breadcrumb): void;
+    /**
+     * Registers a LaunchDarkly client instance for telemetry tracking.
+     *
+     * This method connects the telemetry system to the specific LaunchDarkly
+     * client instance. The client instance will be used to report telemetry
+     * to LaunchDarkly and also for collecting flag and context data.
+     *
+     * @param client The {@link LDClientTracking} instance to register for
+     * telemetry
+     */
+    register(client: LDClientTracking): void;
+    /**
+     * Closes the telemetry system and stops data collection.
+     *
+     * In general usage this method is not required, but it can be used in cases
+     * where collection needs to be stopped independent of application
+     * lifecycle.
+     */
+    close(): void;
+}
+
+/**
+ * Interface for capturing telemetry data.
+ */
+interface Recorder {
+    /**
+     * Capture an error.
+     *
+     * @param exception The exception to capture.
+     */
+    captureError(exception: Error): void;
+    /**
+     * Capture an error event.
+     *
+     * @param errorEvent The error event to capture.
+     */
+    captureErrorEvent(errorEvent: ErrorEvent): void;
+    /**
+     * Add a breadcrumb. When a capture is performed breadcrumb data can be
+     * included with it.
+     *
+     * @param breadcrumb The breadcrumb to add.
+     */
+    addBreadcrumb(breadcrumb: Breadcrumb): void;
+}
+
+/**
+ * Interface to be implemented by collectors.
+ *
+ * Collectors collect data and inform the client of events.
+ *
+ * For instance a collector may notify the telemetry instance of HTTP navigation
+ * or of UI events. A collector can be created independently of a {@link Recorder}
+ * and can begin collecting immediately. It may queue information until it can
+ * be registered with a recorder.
+ */
+interface Collector {
+    /**
+     * Register the collector with a recorder.
+     * @param recorder Recorder to report events or breadcrumbs to.
+     * @param sessionId The current session ID.
+     */
+    register(recorder: Recorder, sessionId: string): void;
+    /**
+     * Unregister the collector. It will stop sending events to the recorder.
+     */
+    unregister(): void;
+}
+
+/**
+ * Represents a frame in a stack.
+ */
+interface StackFrame {
+    /**
+     * The fileName, relative to the project root, of the stack frame.
+     */
+    fileName?: string;
+    /**
+     * The name of the function the frame occurs in.
+     */
+    function?: string;
+    /**
+     * The line number in the file where the frame originates.
+     */
+    line?: number;
+    /**
+     * The column in the file where the frame originates.
+     */
+    col?: number;
+    /**
+     * A number of source code lines before the line the frame originates from.
+     *
+     * The number of lines is configurable.
+     */
+    srcBefore?: string[];
+    /**
+     * The line of source code the frame originates from.
+     *
+     * This line may be partial if the line is too large.
+     */
+    srcLine?: string;
+    /**
+     * A number of source code lines after the line the frame originates from.
+     *
+     * The number of lines is configurable.
+     */
+    srcAfter?: string[];
+}
+
+/**
+ * Represents a stack trace.
+ */
+interface StackTrace {
+    /**
+     * Frames associated with the stack. If no frames can be collected, then this
+     * will be an empty array.
+     */
+    frames: StackFrame[];
+}
+
+/**
+ * Interface representing error data.
+ */
+interface ErrorData {
+    /**
+     * The type of the error.
+     */
+    type: string;
+    /**
+     * A message associated with the error.
+     */
+    message: string;
+    /**
+     * The stack trace for the error.
+     */
+    stack: StackTrace;
+    /**
+     * Breadcrumbs leading up to the error.
+     */
+    breadcrumbs: Breadcrumb[];
+    /**
+     * The ID of the session during which the error occurred.
+     */
+    sessionId: string;
+}
+
+/**
+ * Minimal logging implementation. Compatible with an LDLogger.
+ *
+ * implementation node: Does not use a logging implementation exported by the SDK.
+ * This allows usage with multiple SDK versions.
+ */
+interface MinLogger {
+    /**
+     * The warning logger.
+     *
+     * @param args
+     *   A sequence of any JavaScript values.
+     */
+    warn(...args: any[]): void;
+}
+
+/**
+ * Interface for URL filters.
+ *
+ * Given a URL the filter may return a different string to represent that URL.
+ * This string will be included in the telemetry events instead of the original.
+ *
+ * The URL will be filtered by SDK internal filters before this function is called.
+ *
+ * To redact a URL entirely return an empty string.
+ *
+ * Example:
+ * customUrlFilter: (url) => {
+ *  if (url.includes('secret')) {
+ *    return ''
+ *  }
+ *  return url;
+ * }
+ */
+interface UrlFilter {
+    (url: string): string;
+}
+/**
+ * Interface for breadcrumb filters.
+ *
+ * Given a breadcrumb the filter may return a modified breadcrumb or undefined to exclude the breadcrumb.
+ */
+interface BreadcrumbFilter {
+    (breadcrumb: Breadcrumb): Breadcrumb | undefined;
+}
+/**
+ * Interface for filtering error data before it is sent to LaunchDarkly.
+ *
+ * Given {@link ErrorData} the filter may return modified data or undefined to exclude the breadcrumb.
+ */
+interface ErrorDataFilter {
+    (event: ErrorData): ErrorData | undefined;
+}
+interface HttpBreadcrumbOptions {
+    /**
+     * If fetch should be instrumented and breadcrumbs included for fetch requests.
+     *
+     * Defaults to true.
+     */
+    instrumentFetch?: boolean;
+    /**
+     * If XMLHttpRequests should be instrumented and breadcrumbs included for XMLHttpRequests.
+     *
+     * Defaults to true.
+     */
+    instrumentXhr?: boolean;
+    /**
+     * Customize URL filtering. This will be applied in addition to some baseline filtering included
+     * which redacts components of LaunchDarkly URLs.
+     */
+    customUrlFilter?: UrlFilter;
+}
+interface StackOptions {
+    /**
+     * Configuration that controls how source is captured.
+     */
+    source?: {
+        /**
+         * The number of lines captured before the originating line.
+         *
+         * Defaults to 3.
+         */
+        beforeLines?: number;
+        /**
+         * The number of lines captured after the originating line.
+         *
+         * Defaults to 3.
+         */
+        afterLines?: number;
+        /**
+         * The maximum length of source line to include. Lines longer than this will be
+         * trimmed.
+         *
+         * Defaults to 280.
+         */
+        maxLineLength?: number;
+    };
+}
+/**
+ * Options for configuring browser telemetry.
+ */
+interface Options {
+    /**
+     * The maximum number of pending events. Events may be captured before the LaunchDarkly
+     * SDK is initialized and these are stored until they can be sent. This only affects the
+     * events captured during initialization.
+     */
+    maxPendingEvents?: number;
+    /**
+     * Properties related to automatic breadcrumb collection.
+     */
+    breadcrumbs?: {
+        /**
+         * Set the maximum number of breadcrumbs. Defaults to 50.
+         */
+        maxBreadcrumbs?: number;
+        /**
+         * True to enable automatic evaluation breadcrumbs. Defaults to true.
+         */
+        evaluations?: boolean;
+        /**
+         * True to enable flag change breadcrumbs. Defaults to true.
+         */
+        flagChange?: boolean;
+        /**
+         * True to enable click breadcrumbs. Defaults to true.
+         */
+        click?: boolean;
+        /**
+         * True to enable input breadcrumbs for keypresses. Defaults to true.
+         *
+         * Input breadcrumbs do not include entered text, just that text was entered.
+         */
+        keyboardInput?: boolean;
+        /**
+         * Controls instrumentation and breadcrumbs for HTTP requests.
+         * The default is to instrument XMLHttpRequests and fetch requests.
+         *
+         * `false` to disable all HTTP breadcrumbs and instrumentation.
+         *
+         * Example:
+         * ```
+         * // This would instrument only XmlHttpRequests
+         * http: {
+         *  instrumentFetch: false
+         *  instrumentXhr: true
+         * }
+         *
+         * // Disable all HTTP instrumentation:
+         * http: false
+         * ```
+         */
+        http?: HttpBreadcrumbOptions | false;
+        /**
+         * Custom breadcrumb filters.
+         *
+         * Can be used to redact or modify breadcrumbs.
+         *
+         * Example:
+         * ```
+         * // We want to redact any click events that include the message 'sneaky-button'
+         * filters: [
+         *   (breadcrumb) => {
+         *     if(
+         *       breadcrumb.class === 'ui' &&
+         *       breadcrumb.type === 'click' &&
+         *       breadcrumb.message?.includes('sneaky-button')
+         *     ) {
+         *       return;
+         *     }
+         *    return breadcrumb;
+         *   }
+         * ]
+         * ```
+         *
+         * If you want to redact or modify URLs in breadcrumbs, then a urlFilter should be used.
+         *
+         * If any breadcrumb filters throw an exception while processing a breadcrumb, then that breadcrumb will be excluded.
+         *
+         * If any breadcrumbFilter cannot be executed, for example because it is not a function, then all breadcrumbs will
+         * be excluded.
+         */
+        filters?: BreadcrumbFilter[];
+    };
+    /**
+     * Additional, or custom, collectors.
+     */
+    collectors?: Collector[];
+    /**
+     * Configuration that controls the capture of the stack trace.
+     */
+    stack?: StackOptions;
+    /**
+     * Logger to use for warnings.
+     *
+     * This option is compatible with the `LDLogger` interface used by the LaunchDarkly SDK.
+     *
+     * If this option is not provided, the logs will be written to console.log unless the LaunchDarkly SDK is registered,
+     * and the registered SDK instance exposes its logger. In which case, the logs will be written to the registered SDK's
+     * logger. The 3.x SDKs do not expose their logger.
+     */
+    logger?: MinLogger;
+    /**
+     * Custom error data filters.
+     *
+     * Can be used to redact or modify error data.
+     *
+     * If any filter throws an exception, then the error data will be discarded.
+     *
+     * For filtering breadcrumbs or URLs in error data, refer to the `breadcrumbs.filters` option in {@link breadcrumbs} and
+     * `breadcrumbs.http.customUrlFilter` - {@link HttpBreadcrumbOptions.customUrlFilter}.
+     */
+    errorFilters?: ErrorDataFilter[];
+}
+
+/**
+ * Minimal client interface which allows for loggng. Works with 4.x and higher versions of the javascript client.
+ */
+interface LDClientLogging {
+    readonly logger: MinLogger;
+}
+
+/**
+ * Minimal client interface which allows waiting for initialization.
+ */
+interface LDClientInitialization {
+    waitForInitialization(timeout?: number): Promise<void>;
+}
+
+/**
+ * Initialize the LaunchDarkly telemetry client
+ *
+ * This method should be called one time as early as possible in the application lifecycle.
+ *
+ * @example
+ * ```
+ * import { initTelemetry } from '@launchdarkly/browser-telemetry';
+ *
+ * initTelemetry();
+ * ```
+ *
+ * After initialization the telemetry client must be registered with the LaunchDarkly SDK client.
+ *
+ * @example
+ * ```
+ * import { initTelemetry, register } from '@launchdarkly/browser-telemetry';
+ *
+ * initTelemetry();
+ *
+ * // Create your LaunchDarkly client following the LaunchDarkly SDK documentation.
+ *
+ * register(ldClient);
+ * ```
+ *
+ * If using the 3.x version of the LaunchDarkly SDK, then you must also add inspectors when initializing your LaunchDarkly client.
+ * This allows for integration with feature flag data.
+ *
+ * @example
+ * ```
+ * import { initTelemetry, register, inspectors } from '@launchdarkly/browser-telemetry';
+ * import { init } from 'launchdarkly-js-client-sdk';
+ *
+ * initTelemetry();
+ *
+ * const ldClient = init('YOUR_CLIENT_SIDE_ID', {
+ *   inspectors: inspectors()
+ * });
+ *
+ * register(ldClient);
+ * ```
+ *
+ * @param options The options to use for the telemetry instance. Refer to {@link Options} for more information.
+ */
+declare function initTelemetry(options?: Options): void;
+/**
+ * Get the telemetry instance.
+ *
+ * In typical operation this method doesn't need to be called. Instead the functions exported by this package directly
+ * use the telemetry instance.
+ *
+ * This function can be used when the telemetry instance needs to be injected into code instead of accessed globally.
+ *
+ * @returns The telemetry instance, or undefined if it has not been initialized.
+ */
+declare function getTelemetryInstance(): BrowserTelemetry | undefined;
+
+/**
+ * Returns an array of active SDK inspectors to use with SDK versions that do
+ * not support hooks.
+ *
+ * Telemetry must be initialized, using {@link initTelemetry} before calling this method.
+ * If telemetry is not initialized, this method will return an empty array.
+ *
+ * @returns An array of {@link BrowserTelemetryInspector} objects.
+ */
+declare function inspectors(): BrowserTelemetryInspector[];
+/**
+ * Captures an Error object for telemetry purposes.
+ *
+ * Use this method to manually capture errors during application operation.
+ * Unhandled errors are automatically captured, but this method can be used
+ * to capture errors which were handled, but are still useful for telemetry.
+ *
+ * Telemetry must be initialized, using {@link initTelemetry} before calling this method.
+ * If telemetry is not initialized, then the exception will be discarded.
+ *
+ * @param exception The Error object to capture
+ */
+declare function captureError(exception: Error): void;
+/**
+ * Captures a browser ErrorEvent for telemetry purposes.
+ *
+ * This method can be used to capture a manually created error event. Use this
+ * function to represent application specific errors which cannot be captured
+ * automatically or are not `Error` types.
+ *
+ * For most errors {@link captureError} should be used.
+ *
+ * Telemetry must be initialized, using {@link initTelemetry} before calling this method.
+ * If telemetry is not initialized, then the error event will be discarded.
+ *
+ * @param errorEvent The ErrorEvent to capture
+ */
+declare function captureErrorEvent(errorEvent: ErrorEvent): void;
+/**
+ * Add a breadcrumb which will be included with telemetry events.
+ *
+ * Many breadcrumbs can be automatically captured, but this method can be
+ * used for capturing manual breadcrumbs. For application specific breadcrumbs
+ * the {@link CustomBreadcrumb} type can be used.
+ *
+ * Telemetry must be initialized, using {@link initTelemetry} before calling this method.
+ * If telemetry is not initialized, then the breadcrumb will be discarded.
+ *
+ * @param breadcrumb The breadcrumb to add.
+ */
+declare function addBreadcrumb(breadcrumb: Breadcrumb): void;
+/**
+ * Registers a LaunchDarkly client instance for telemetry tracking.
+ *
+ * This method connects the telemetry system to the specific LaunchDarkly
+ * client instance. The client instance will be used to report telemetry
+ * to LaunchDarkly and also for collecting flag and context data.
+ *
+ * Telemetry must be initialized, using {@link initTelemetry} before calling this method.
+ * If telemetry is not initialized, then the client will not be registered, and no events will be sent to LaunchDarkly.
+ *
+ * @param client The {@link LDClientTracking} instance to register for
+ * telemetry.
+ */
+declare function register(client: LDClientTracking): void;
+/**
+ * Closes the telemetry system and stops data collection.
+ *
+ * In general usage this method is not required, but it can be used in cases
+ * where collection needs to be stopped independent of application
+ * lifecycle.
+ *
+ * If telemetry is not initialized, using {@link initTelemetry}, then this method will do nothing.
+ */
+declare function close(): void;
+
+/**
+ * Initialize a new telemetry instance.
+ *
+ * This instance is not global. Generally developers should use {@link initTelemetry} instead.
+ *
+ * If for some reason multiple telemetry instances are needed, this method can be used to create a new instance.
+ * Instances are not aware of each other and may send duplicate data from automatically captured events.
+ *
+ * @param options The options to use for the telemetry instance.
+ * @returns A telemetry instance.
+ */
+declare function initTelemetryInstance(options?: Options): BrowserTelemetry;
+
+export { type Breadcrumb, type BreadcrumbClass, type BreadcrumbData, type BreadcrumbDataValue, type BreadcrumbFilter, type BreadcrumbLevel, type BrowserTelemetry, type BrowserTelemetryInspector, type Collector, type CustomBreadcrumb, type ErrorData, type ErrorDataFilter, type FeatureManagementBreadcrumb, type HttpBreadcrumb, type HttpBreadcrumbOptions, type ImplementsCrumb, type LDClientInitialization, type LDClientLogging, type LDClientTracking, type LogBreadcrumb, type MinLogger, type NavigationBreadcrumb, type Options, type Recorder, type StackFrame, type StackOptions, type StackTrace, type UiBreadcrumb, type UrlFilter, addBreadcrumb, captureError, captureErrorEvent, close, getTelemetryInstance, initTelemetry, initTelemetryInstance, inspectors, register };