feat: Make browser-telemetry specific inspector type. (#741)

This is a compatibility improvement PR intended to make the telemetry
package less dependent on a specific SDK package.

The inspector interface between 3.x and 4.x has some minor differences
and this provides a more broad interface that is compatible with both.

Author: kinyoklion

packages/telemetry/browser-telemetry/__tests__/singleton/singletonMethods.test.ts

@@ -1,7 +1,6 @@
-import { LDInspection } from '@launchdarkly/js-client-sdk';
-
 import { Breadcrumb, LDClientTracking } from '../../src/api';
 import { BrowserTelemetry } from '../../src/api/BrowserTelemetry';
+import { BrowserTelemetryInspector } from '../../src/api/client/BrowserTelemetryInspector';
 import { getTelemetryInstance } from '../../src/singleton/singletonInstance';
 import {
   addBreadcrumb,
@@ -36,8 +35,8 @@ it('returns empty array when telemetry is not initialized for inspectors', () =>
 });
 
 it('returns inspectors when telemetry is initialized', () => {
-  const mockInspectors: LDInspection[] = [
-    { name: 'test-inspector', type: 'flag-used', method: () => {} },
+  const mockInspectors: BrowserTelemetryInspector[] = [
+    { name: 'test-inspector', type: 'flag-used', synchronous: true, method: () => {} },
   ];
   mockGetTelemetryInstance.mockReturnValue(mockTelemetry);
   mockTelemetry.inspectors.mockReturnValue(mockInspectors);

packages/telemetry/browser-telemetry/src/BrowserTelemetryImpl.ts

@@ -3,11 +3,12 @@
  * This is only a type dependency and these types should be compatible between
  * SDKs.
  */
-import type { LDContext, LDEvaluationDetail, LDInspection } from '@launchdarkly/js-client-sdk';
+import type { LDContext, LDEvaluationDetail } from '@launchdarkly/js-client-sdk';
 
 import { BreadcrumbFilter, LDClientLogging, LDClientTracking, MinLogger } from './api';
 import { Breadcrumb, FeatureManagementBreadcrumb } from './api/Breadcrumb';
 import { BrowserTelemetry } from './api/BrowserTelemetry';
+import { BrowserTelemetryInspector } from './api/client/BrowserTelemetryInspector';
 import { Collector } from './api/Collector';
 import { ErrorData } from './api/ErrorData';
 import { EventData } from './api/EventData';
@@ -94,7 +95,7 @@ export default class BrowserTelemetryImpl implements BrowserTelemetry {
 
   private _breadcrumbs: Breadcrumb[] = [];
 
-  private _inspectorInstances: LDInspection[] = [];
+  private _inspectorInstances: BrowserTelemetryInspector[] = [];
   private _collectors: Collector[] = [];
   private _sessionId: string = randomUuidV4();
 
@@ -149,7 +150,7 @@ export default class BrowserTelemetryImpl implements BrowserTelemetry {
     );
 
     const impl = this;
-    const inspectors: LDInspection[] = [];
+    const inspectors: BrowserTelemetryInspector[] = [];
     makeInspectors(_options, inspectors, impl);
     this._inspectorInstances.push(...inspectors);
 
@@ -184,7 +185,7 @@ export default class BrowserTelemetryImpl implements BrowserTelemetry {
     }
   }
 
-  inspectors(): LDInspection[] {
+  inspectors(): BrowserTelemetryInspector[] {
     return this._inspectorInstances;
   }
 

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

@@ -1,6 +1,5 @@
-import type { LDInspection } from '@launchdarkly/js-client-sdk';
-
 import { Breadcrumb } from './Breadcrumb';
+import { BrowserTelemetryInspector } from './client/BrowserTelemetryInspector';
 import { LDClientTracking } from './client/LDClientTracking';
 
 /**
@@ -15,9 +14,9 @@ export interface BrowserTelemetry {
    * Returns an array of active SDK inspectors to use with SDK versions that do
    * not support hooks.
    *
-   * @returns An array of {@link LDInspection} objects.
+   * @returns An array of {@link BrowserTelemetryInspector} objects.
    */
-  inspectors(): LDInspection[];
+  inspectors(): BrowserTelemetryInspector[];
 
   /**
    * Captures an Error object for telemetry purposes.

packages/telemetry/browser-telemetry/src/api/client/BrowserTelemetryInspector.ts

@@ -0,0 +1,29 @@
+/**
+ * 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.
+ */
+export 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;
+}

packages/telemetry/browser-telemetry/src/inspectors.ts

@@ -1,5 +1,6 @@
-import type { LDContext, LDEvaluationDetail, LDInspection } from '@launchdarkly/js-client-sdk';
+import type { LDContext, LDEvaluationDetail } from '@launchdarkly/js-client-sdk';
 
+import { BrowserTelemetryInspector } from './api/client/BrowserTelemetryInspector.js';
 import BrowserTelemetryImpl from './BrowserTelemetryImpl.js';
 import { ParsedOptions } from './options.js';
 
@@ -12,7 +13,7 @@ import { ParsedOptions } from './options.js';
  */
 export default function makeInspectors(
   options: ParsedOptions,
-  inspectors: LDInspection[],
+  inspectors: BrowserTelemetryInspector[],
   telemetry: BrowserTelemetryImpl,
 ) {
   if (options.breadcrumbs.evaluations) {

packages/telemetry/browser-telemetry/src/singleton/singletonMethods.ts

@@ -1,7 +1,6 @@
-import type { LDInspection } from '@launchdarkly/js-client-sdk';
-
 import { LDClientTracking } from '../api';
 import { Breadcrumb } from '../api/Breadcrumb';
+import { BrowserTelemetryInspector } from '../api/client/BrowserTelemetryInspector';
 import { getTelemetryInstance } from './singletonInstance';
 
 /**
@@ -11,9 +10,9 @@ import { getTelemetryInstance } from './singletonInstance';
  * Telemetry must be initialized, using {@link initializeTelemetry} before calling this method.
  * If telemetry is not initialized, this method will return an empty array.
  *
- * @returns An array of {@link LDInspection} objects.
+ * @returns An array of {@link BrowserTelemetryInspector} objects.
  */
-export function inspectors(): LDInspection[] {
+export function inspectors(): BrowserTelemetryInspector[] {
   return getTelemetryInstance()?.inspectors() || [];
 }