feat: Add browser-telemetry API types.

Author: kinyoklion

packages/telemetry/browser-telemetry/src/api/Breadcrumb.ts

@@ -0,0 +1,127 @@
+export type BreadcrumbClass =
+  | 'custom'
+  | 'log'
+  | 'navigation'
+  | 'feature-management'
+  | 'ui'
+  | 'http';
+
+export type BreadcrumbLevel = 'error' | 'warning' | 'info' | 'debug';
+
+export type BreadcrumbDataValue = boolean | number | string;
+
+export type BreadcrumbData = Record<string, BreadcrumbDataValue>;
+
+export 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;
+}
+
+type ImplementsCrumb<U extends Breadcrumb> = U;
+
+export type CustomBreadcrumb = ImplementsCrumb<{
+  class: 'custom';
+  timestamp: number;
+  level: BreadcrumbLevel;
+  type?: string;
+  message?: string;
+  data?: BreadcrumbData;
+}>;
+
+export type LogBreadcrumb = ImplementsCrumb<{
+  class: 'log';
+  timestamp: number;
+  level: BreadcrumbLevel;
+  message: string;
+  data?: BreadcrumbData;
+}>;
+
+export 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;
+  };
+}>;
+
+export type FeatureManagementBreadcrumb = ImplementsCrumb<{
+  class: 'feature-management';
+  timestamp: number;
+  level: 'info';
+  type: 'flag-evaluated' | 'flag-detail-changed';
+  data?: {
+    /**
+     * The flag key.
+     */
+    key?: string;
+    // Not supporting JSON flags in breadcrumbs. As noted in design we may want to eventually support none of the
+    // values in the breadcrumb.
+    /**
+     * The evaluated value for simple types.
+     */
+    value?: boolean | string | number;
+  };
+}>;
+
+export type UiBreadcrumb = ImplementsCrumb<{
+  class: 'ui';
+  timestamp: number;
+  level: 'info';
+  type: 'click' | 'input';
+  message: string;
+}>;
+
+export type HttpBreadcrumb = ImplementsCrumb<{
+  class: 'http';
+  timestamp: number;
+  level: 'error' | 'info'; // Error if an error status code?
+  type: 'xhr' | 'fetch';
+  data?: {
+    url?: string;
+    method?: string;
+    statusCode: number;
+    statusText: string;
+  };
+}>;

packages/telemetry/browser-telemetry/src/api/BrowserTelemetry.ts

@@ -0,0 +1,22 @@
+import { LDClient, LDInspection } from 'launchdarkly-js-client-sdk';
+
+import { Breadcrumb } from './Breadcrumb';
+import { EventData } from './EventData';
+
+// TODO: Make a core client-side telemetry package.
+// TODO: Put all the interfaces in the core package and only browser auto telemetry in the
+// browser package.
+
+export interface BrowserTelemetry {
+  inspectors(): LDInspection[];
+
+  captureError(exception: Error): void;
+  captureErrorEvent(errorEvent: ErrorEvent): void;
+  captureSession(sessionEvent: EventData): void;
+
+  addBreadcrumb(breadcrumb: Breadcrumb): void;
+
+  register(client: LDClient): void;
+
+  close(): void;
+}

packages/telemetry/browser-telemetry/src/api/Collector.ts

@@ -0,0 +1,13 @@
+import { type LDContext, type LDEvaluationDetail } from 'launchdarkly-js-client-sdk';
+
+import { BrowserTelemetry } from './BrowserTelemetry';
+
+export interface Collector {
+  register(telemetry: BrowserTelemetry, sessionId: string): void;
+  unregister(): void;
+
+  handleFlagUsed?(flagKey: string, flagDetail: LDEvaluationDetail, _context: LDContext): void;
+  handleFlagDetailChanged?(flagKey: string, detail: LDEvaluationDetail): void;
+  // TODO: Should have an ID to correlate to.
+  handleErrorEvent?(name: string, message: string): void;
+}

packages/telemetry/browser-telemetry/src/api/ErrorData.ts

@@ -0,0 +1,10 @@
+import StackTrace from '../stack/StackTrace';
+import { Breadcrumb } from './Breadcrumb';
+
+export interface ErrorData {
+  type: string;
+  message: string;
+  stack: StackTrace;
+  breadcrumbs: Breadcrumb[];
+  sessionId: string;
+}

packages/telemetry/browser-telemetry/src/api/EventData.ts

@@ -0,0 +1,4 @@
+export interface EventData {
+  // TODO: Change this to be a union of the different data types.
+  [key: string]: any;
+}

packages/telemetry/browser-telemetry/src/api/Options.ts

@@ -0,0 +1,146 @@
+import { Collector } from './Collector';
+
+/**
+ * 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;
+ * }
+ */
+export interface UrlFilter {
+  (url: string): string;
+}
+
+export 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;
+}
+
+export 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.
+ */
+export 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;
+  };
+
+  /**
+   * Additional, or custom, collectors.
+   */
+  collectors?: Collector[];
+
+  /**
+   * Configuration that controls the capture of the stack trace.
+   */
+  stack?: StackOptions;
+}