launchdarkly-js-sdk-common 4.2.0 → 4.3.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to the `launchdarkly-js-sdk-common` package will be documented in this file. Changes that affect the dependent SDKs such as `launchdarkly-js-client-sdk` should also be logged in those projects, in the next release that uses the updated version of this package. This project adheres to [Semantic Versioning](http://semver.org).
 
+## [4.2.0] - 2022-10-03
+### Removed:
+- Removed `seenRequests` cache. This cache was used to de-duplicate events, but it has been supplanted with summary events.
+
+### Deprecated:
+- The `allowFrequentDuplicateEvents` configuration has been deprecated because it controlled the behavior of the `seenRequests` cache.
+
 ## [4.1.1] - 2022-06-07
 ### Changed:
 - Enforce a 64 character limit for `application.id` and `application.version` configuration options.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "launchdarkly-js-sdk-common",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "description": "LaunchDarkly SDK for JavaScript - common code",
   "author": "LaunchDarkly <team@launchdarkly.com>",
   "license": "Apache-2.0",

package/src/InspectorManager.js

@@ -0,0 +1,120 @@
+const { messages } = require('.');
+const SafeInspector = require('./SafeInspector');
+const { onNextTick } = require('./utils');
+
+/**
+ * The types of supported inspectors.
+ */
+const InspectorTypes = {
+  flagUsed: 'flag-used',
+  flagDetailsChanged: 'flag-details-changed',
+  flagDetailChanged: 'flag-detail-changed',
+  clientIdentityChanged: 'client-identity-changed',
+};
+
+Object.freeze(InspectorTypes);
+
+/**
+ * Manages dispatching of inspection data to registered inspectors.
+ */
+function InspectorManager(inspectors, logger) {
+  const manager = {};
+
+  /**
+   * Collection of inspectors keyed by type.
+   * @type {{[type: string]: object[]}}
+   */
+  const inspectorsByType = {
+    [InspectorTypes.flagUsed]: [],
+    [InspectorTypes.flagDetailsChanged]: [],
+    [InspectorTypes.flagDetailChanged]: [],
+    [InspectorTypes.clientIdentityChanged]: [],
+  };
+
+  const safeInspectors = inspectors?.map(inspector => SafeInspector(inspector, logger));
+
+  safeInspectors.forEach(safeInspector => {
+    // Only add inspectors of supported types.
+    if (Object.prototype.hasOwnProperty.call(inspectorsByType, safeInspector.type)) {
+      inspectorsByType[safeInspector.type].push(safeInspector);
+    } else {
+      logger.warn(messages.invalidInspector(safeInspector.type, safeInspector.name));
+    }
+  });
+
+  /**
+   * Check if there is an inspector of a specific type registered.
+   *
+   * @param {string} type The type of the inspector to check.
+   * @returns True if there are any inspectors of that type registered.
+   */
+  manager.hasListeners = type => inspectorsByType[type]?.length;
+
+  /**
+   * Notify registered inspectors of a flag being used.
+   *
+   * The notification itself will be dispatched asynchronously.
+   *
+   * @param {string} flagKey The key for the flag.
+   * @param {Object} detail The LDEvaluationDetail for the flag.
+   * @param {Object} user The LDUser for the flag.
+   */
+  manager.onFlagUsed = (flagKey, detail, user) => {
+    if (inspectorsByType[InspectorTypes.flagUsed].length) {
+      onNextTick(() => {
+        inspectorsByType[InspectorTypes.flagUsed].forEach(inspector => inspector.method(flagKey, detail, user));
+      });
+    }
+  };
+
+  /**
+   * Notify registered inspectors that the flags have been replaced.
+   *
+   * The notification itself will be dispatched asynchronously.
+   *
+   * @param {Record<string, Object>} flags The current flags as a Record<string, LDEvaluationDetail>.
+   */
+  manager.onFlags = flags => {
+    if (inspectorsByType[InspectorTypes.flagDetailsChanged].length) {
+      onNextTick(() => {
+        inspectorsByType[InspectorTypes.flagDetailsChanged].forEach(inspector => inspector.method(flags));
+      });
+    }
+  };
+
+  /**
+   * Notify registered inspectors that a flag value has changed.
+   *
+   * The notification itself will be dispatched asynchronously.
+   *
+   * @param {string} flagKey The key for the flag that changed.
+   * @param {Object} flag An `LDEvaluationDetail` for the flag.
+   */
+  manager.onFlagChanged = (flagKey, flag) => {
+    if (inspectorsByType[InspectorTypes.flagDetailChanged].length) {
+      onNextTick(() => {
+        console.log('what?');
+        inspectorsByType[InspectorTypes.flagDetailChanged].forEach(inspector => inspector.method(flagKey, flag));
+      });
+    }
+  };
+
+  /**
+   * Notify the registered inspectors that the user identity has changed.
+   *
+   * The notification itself will be dispatched asynchronously.
+   *
+   * @param {Object} user The `LDUser` which is now identified.
+   */
+  manager.onIdentityChanged = user => {
+    if (inspectorsByType[InspectorTypes.clientIdentityChanged].length) {
+      onNextTick(() => {
+        inspectorsByType[InspectorTypes.clientIdentityChanged].forEach(inspector => inspector.method(user));
+      });
+    }
+  };
+
+  return manager;
+}
+
+module.exports = { InspectorTypes, InspectorManager };

package/src/SafeInspector.js

@@ -0,0 +1,34 @@
+const { messages } = require('.');
+
+/**
+ * Wrap an inspector ensuring that calling its methods are safe.
+ * @param {object} inspector Inspector to wrap.
+ */
+function SafeInspector(inspector, logger) {
+  let errorLogged = false;
+  const wrapper = {
+    type: inspector.type,
+    name: inspector.name,
+  };
+
+  wrapper.method = (...args) => {
+    try {
+      inspector.method(...args);
+    } catch {
+      // If something goes wrong in an inspector we want to log that something
+      // went wrong. We don't want to flood the logs, so we only log something
+      // the first time that something goes wrong.
+      // We do not include the exception in the log, because we do not know what
+      // kind of data it may contain.
+      if (!errorLogged) {
+        errorLogged = true;
+        logger.warn(messages.inspectorMethodError(wrapper.type, wrapper.name));
+      }
+      // Prevent errors.
+    }
+  };
+
+  return wrapper;
+}
+
+module.exports = SafeInspector;

package/src/__tests__/InspectorManager-test.js

@@ -0,0 +1,186 @@
+const { AsyncQueue } = require('launchdarkly-js-test-helpers');
+const { InspectorTypes, InspectorManager } = require('../InspectorManager');
+const stubPlatform = require('./stubPlatform');
+
+describe('given an inspector manager with no registered inspectors', () => {
+  const platform = stubPlatform.defaults();
+  const manager = InspectorManager([], platform.testing.logger);
+
+  it('does not cause errors', () => {
+    manager.onIdentityChanged({ key: 'key' });
+    manager.onFlagUsed(
+      'flag-key',
+      {
+        value: null,
+      },
+      { key: 'key' }
+    );
+    manager.onFlags({});
+    manager.onFlagChanged('flag-key', { value: null });
+  });
+
+  it('does not report any registered listeners', () => {
+    expect(manager.hasListeners(InspectorTypes.clientIdentityChanged)).toBeFalsy();
+    expect(manager.hasListeners(InspectorTypes.flagDetailChanged)).toBeFalsy();
+    expect(manager.hasListeners(InspectorTypes.flagDetailsChanged)).toBeFalsy();
+    expect(manager.hasListeners(InspectorTypes.flagUsed)).toBeFalsy();
+    expect(manager.hasListeners('potato')).toBeFalsy();
+  });
+});
+
+describe('given an inspector with callbacks of every type', () => {
+  /**
+   * @type {AsyncQueue}
+   */
+  const eventQueue = new AsyncQueue();
+  const platform = stubPlatform.defaults();
+  const manager = InspectorManager(
+    [
+      {
+        type: 'flag-used',
+        name: 'my-flag-used-inspector',
+        method: (flagKey, flagDetail, user) => {
+          eventQueue.add({ type: 'flag-used', flagKey, flagDetail, user });
+        },
+      },
+      // 'flag-used registered twice.
+      {
+        type: 'flag-used',
+        name: 'my-other-flag-used-inspector',
+        method: (flagKey, flagDetail, user) => {
+          eventQueue.add({ type: 'flag-used', flagKey, flagDetail, user });
+        },
+      },
+      {
+        type: 'flag-details-changed',
+        name: 'my-flag-details-inspector',
+        method: details => {
+          eventQueue.add({
+            type: 'flag-details-changed',
+            details,
+          });
+        },
+      },
+      {
+        type: 'flag-detail-changed',
+        name: 'my-flag-detail-inspector',
+        method: (flagKey, flagDetail) => {
+          eventQueue.add({
+            type: 'flag-detail-changed',
+            flagKey,
+            flagDetail,
+          });
+        },
+      },
+      {
+        type: 'client-identity-changed',
+        name: 'my-identity-inspector',
+        method: user => {
+          eventQueue.add({
+            type: 'client-identity-changed',
+            user,
+          });
+        },
+      },
+      // Invalid inspector shouldn't have an effect.
+      {
+        type: 'potato',
+        name: 'my-potato-inspector',
+        method: () => {},
+      },
+    ],
+    platform.testing.logger
+  );
+
+  afterEach(() => {
+    expect(eventQueue.length()).toEqual(0);
+  });
+
+  afterAll(() => {
+    eventQueue.close();
+  });
+
+  it('logged that there was a bad inspector', () => {
+    expect(platform.testing.logger.output.warn).toEqual([
+      'an inspector: "my-potato-inspector" of an invalid type (potato) was configured',
+    ]);
+  });
+
+  it('reports any registered listeners', () => {
+    expect(manager.hasListeners(InspectorTypes.clientIdentityChanged)).toBeTruthy();
+    expect(manager.hasListeners(InspectorTypes.flagDetailChanged)).toBeTruthy();
+    expect(manager.hasListeners(InspectorTypes.flagDetailsChanged)).toBeTruthy();
+    expect(manager.hasListeners(InspectorTypes.flagUsed)).toBeTruthy();
+    expect(manager.hasListeners('potato')).toBeFalsy();
+  });
+
+  it('executes `onFlagUsed` handlers', async () => {
+    manager.onFlagUsed(
+      'flag-key',
+      {
+        value: 'test',
+        variationIndex: 1,
+        reason: {
+          kind: 'OFF',
+        },
+      },
+      { key: 'test-key' }
+    );
+
+    const expectedEvent = {
+      type: 'flag-used',
+      flagKey: 'flag-key',
+      flagDetail: {
+        value: 'test',
+        variationIndex: 1,
+        reason: {
+          kind: 'OFF',
+        },
+      },
+      user: { key: 'test-key' },
+    };
+    const event1 = await eventQueue.take();
+    expect(event1).toMatchObject(expectedEvent);
+
+    // There are two handlers, so there should be another event.
+    const event2 = await eventQueue.take();
+    expect(event2).toMatchObject(expectedEvent);
+  });
+
+  it('executes `onFlags` handler', async () => {
+    manager.onFlags({
+      example: { value: 'a-value' },
+    });
+
+    const event = await eventQueue.take();
+    expect(event).toMatchObject({
+      type: 'flag-details-changed',
+      details: {
+        example: { value: 'a-value' },
+      },
+    });
+  });
+
+  it('executes `onFlagChanged` handler', async () => {
+    manager.onFlagChanged('the-flag', { value: 'a-value' });
+
+    const event = await eventQueue.take();
+    expect(event).toMatchObject({
+      type: 'flag-detail-changed',
+      flagKey: 'the-flag',
+      flagDetail: {
+        value: 'a-value',
+      },
+    });
+  });
+
+  it('executes `onIdentityChanged` handler', async () => {
+    manager.onIdentityChanged({ key: 'the-key' });
+
+    const event = await eventQueue.take();
+    expect(event).toMatchObject({
+      type: 'client-identity-changed',
+      user: { key: 'the-key' },
+    });
+  });
+});

package/src/__tests__/LDClient-inspectors-test.js

@@ -0,0 +1,127 @@
+const { AsyncQueue } = require('launchdarkly-js-test-helpers');
+const { respondJson } = require('./mockHttp');
+const stubPlatform = require('./stubPlatform');
+
+const envName = 'UNKNOWN_ENVIRONMENT_ID';
+const user = { key: 'user' };
+
+describe('given a streaming client with registered inspectors', () => {
+  const eventQueue = new AsyncQueue();
+
+  const inspectors = [
+    {
+      type: 'flag-used',
+      method: (flagKey, flagDetail, user) => {
+        eventQueue.add({ type: 'flag-used', flagKey, flagDetail, user });
+      },
+    },
+    // 'flag-used registered twice.
+    {
+      type: 'flag-used',
+      method: (flagKey, flagDetail, user) => {
+        eventQueue.add({ type: 'flag-used', flagKey, flagDetail, user });
+      },
+    },
+    {
+      type: 'flag-details-changed',
+      method: details => {
+        eventQueue.add({
+          type: 'flag-details-changed',
+          details,
+        });
+      },
+    },
+    {
+      type: 'flag-detail-changed',
+      method: (flagKey, flagDetail) => {
+        eventQueue.add({
+          type: 'flag-detail-changed',
+          flagKey,
+          flagDetail,
+        });
+      },
+    },
+    {
+      type: 'client-identity-changed',
+      method: user => {
+        eventQueue.add({
+          type: 'client-identity-changed',
+          user,
+        });
+      },
+    },
+  ];
+
+  let client;
+  let platform;
+
+  beforeEach(async () => {
+    platform = stubPlatform.defaults();
+    const server = platform.testing.http.newServer();
+    server.byDefault(respondJson({}));
+    const config = { streaming: true, baseUrl: server.url, inspectors };
+    client = platform.testing.makeClient(envName, user, config);
+    await client.waitUntilReady();
+  });
+
+  afterEach(() => {
+    expect(eventQueue.length()).toEqual(0);
+  });
+
+  afterAll(() => {
+    eventQueue.close();
+  });
+
+  afterEach(async () => {
+    await client.close();
+  });
+
+  it('has an initial identify event and flag payload', async () => {
+    // These events cover the initial identify and a polling response.
+    const ident = await eventQueue.take();
+    expect(ident).toMatchObject({
+      type: 'client-identity-changed',
+      user,
+    });
+    const flagsEvent = await eventQueue.take();
+    expect(flagsEvent).toMatchObject({
+      type: 'flag-details-changed',
+      details: {},
+    });
+  });
+
+  it('emits an event for the stream put replacing all flags', async () => {
+    // Take initial events.
+    eventQueue.take();
+    eventQueue.take();
+
+    const stream = await platform.testing.eventSourcesCreated.take();
+    stream.eventSource.mockEmit('put', {
+      data: '{"flagKey":{"value":true,"version":1}}',
+    });
+    const updateEvent = await eventQueue.take();
+    expect(updateEvent).toMatchObject({
+      type: 'flag-details-changed',
+      details: {
+        flagKey: { value: true },
+      },
+    });
+  });
+
+  it('emits an event for a stream patch changing a flag', async () => {
+    // Take initial events.
+    eventQueue.take();
+    eventQueue.take();
+
+    const stream = await platform.testing.eventSourcesCreated.take();
+    stream.eventSource.mockEmit('patch', {
+      data: '{"key": "flagKey", "value":false,"version":2}',
+    });
+    const updateEvent = await eventQueue.take();
+    expect(updateEvent).toMatchObject({
+      type: 'flag-detail-changed',
+      flagKey: 'flagKey',
+      flagDetail: { value: false },
+    });
+  });
+});

package/src/__tests__/SafeInspector-test.js

@@ -0,0 +1,61 @@
+const SafeInspector = require('../SafeInspector');
+const stubPlatform = require('./stubPlatform');
+
+describe('given a safe inspector', () => {
+  const platform = stubPlatform.defaults();
+  const mockInspector = {
+    type: 'the-inspector-type',
+    name: 'the-inspector-name',
+    method: () => {
+      throw new Error('evil inspector');
+    },
+  };
+  const safeInspector = SafeInspector(mockInspector, platform.testing.logger);
+
+  it('has the correct type', () => {
+    expect(safeInspector.type).toEqual('the-inspector-type');
+  });
+
+  it('does not allow exceptions to propagate', () => {
+    safeInspector.method();
+  });
+
+  it('only logs one error', () => {
+    safeInspector.method();
+    safeInspector.method();
+    expect(platform.testing.logger.output.warn).toEqual([
+      'an inspector: "the-inspector-name" of type: "the-inspector-type" generated an exception',
+    ]);
+  });
+});
+
+// Type and name are required by the schema, but it should operate fine if they are not specified.
+describe('given a safe inspector with no name or type', () => {
+  const platform = stubPlatform.defaults();
+  const mockInspector = {
+    method: () => {
+      throw new Error('evil inspector');
+    },
+  };
+  const safeInspector = SafeInspector(mockInspector, platform.testing.logger);
+
+  it('has undefined type', () => {
+    expect(safeInspector.type).toBeUndefined();
+  });
+
+  it('has undefined name', () => {
+    expect(safeInspector.name).toBeUndefined();
+  });
+
+  it('does not allow exceptions to propagate', () => {
+    safeInspector.method();
+  });
+
+  it('only logs one error', () => {
+    safeInspector.method();
+    safeInspector.method();
+    expect(platform.testing.logger.output.warn).toEqual([
+      'an inspector: "undefined" of type: "undefined" generated an exception',
+    ]);
+  });
+});

package/src/configuration.js

@@ -39,6 +39,7 @@ const baseOptionDefs = {
   stateProvider: { type: 'object' }, // not a public option, used internally
   autoAliasingOptOut: { default: false },
   application: { validator: applicationConfigValidator },
+  inspectors: { default: [] },
 };
 
 /**

package/src/index.js

@@ -14,6 +14,7 @@ const { commonBasicLogger } = require('./loggers');
 const utils = require('./utils');
 const errors = require('./errors');
 const messages = require('./messages');
+const { InspectorTypes, InspectorManager } = require('./InspectorManager');
 
 const changeEvent = 'change';
 const internalChangeEvent = 'internal-change';
@@ -32,6 +33,7 @@ function initialize(env, user, specifiedOptions, platform, extraOptionDefs) {
   const emitter = EventEmitter(logger);
   const initializationStateTracker = InitializationStateTracker(emitter);
   const options = configuration.validate(specifiedOptions, emitter, extraOptionDefs, logger);
+  const inspectorManager = InspectorManager(options.inspectors, logger);
   const sendEvents = options.sendEvents;
   let environment = env;
   let hash = options.hash;
@@ -154,11 +156,38 @@ function initialize(env, user, specifiedOptions, platform, extraOptionDefs) {
     }
   }
 
+  function notifyInspectionIdentityChanged() {
+    if (inspectorManager.hasListeners(InspectorTypes.clientIdentityChanged)) {
+      inspectorManager.onIdentityChanged(ident.getUser());
+    }
+  }
+
+  function notifyInspectionFlagChanged(data, newFlag) {
+    if (inspectorManager.hasListeners(InspectorTypes.flagDetailChanged)) {
+      inspectorManager.onFlagChanged(data.key, getFlagDetail(newFlag));
+    }
+  }
+
+  function notifyInspectionFlagsChanged() {
+    if (inspectorManager.hasListeners(InspectorTypes.flagDetailsChanged)) {
+      inspectorManager.onFlags(
+        Object.entries(flags)
+          .map(([key, value]) => ({ key, detail: getFlagDetail(value) }))
+          .reduce((acc, cur) => {
+            // eslint-disable-next-line no-param-reassign
+            acc[cur.key] = cur.detail;
+            return acc;
+          }, {})
+      );
+    }
+  }
+
   function onIdentifyChange(user, previousUser) {
     sendIdentifyEvent(user);
     if (!options.autoAliasingOptOut && previousUser && previousUser.anonymous && user && !user.anonymous) {
       alias(user, previousUser);
     }
+    notifyInspectionIdentityChanged();
   }
 
   function sendIdentifyEvent(user) {
@@ -257,14 +286,14 @@ function initialize(env, user, specifiedOptions, platform, extraOptionDefs) {
   }
 
   function variation(key, defaultValue) {
-    return variationDetailInternal(key, defaultValue, true, false).value;
+    return variationDetailInternal(key, defaultValue, true, false, false).value;
   }
 
   function variationDetail(key, defaultValue) {
-    return variationDetailInternal(key, defaultValue, true, true);
+    return variationDetailInternal(key, defaultValue, true, true, false);
   }
 
-  function variationDetailInternal(key, defaultValue, sendEvent, includeReasonInEvent) {
+  function variationDetailInternal(key, defaultValue, sendEvent, includeReasonInEvent, isAllFlags) {
     let detail;
 
     if (flags && utils.objectHasOwnProperty(flags, key) && flags[key] && !flags[key].deleted) {
@@ -281,6 +310,11 @@ function initialize(env, user, specifiedOptions, platform, extraOptionDefs) {
       sendFlagEvent(key, detail, defaultValue, includeReasonInEvent);
     }
 
+    // For the all flags case `onFlags` will be called instead.
+    if (!isAllFlags) {
+      notifyInspectionIdentityChanged();
+    }
+
     return detail;
   }
 
@@ -304,7 +338,7 @@ function initialize(env, user, specifiedOptions, platform, extraOptionDefs) {
 
     for (const key in flags) {
       if (utils.objectHasOwnProperty(flags, key) && !flags[key].deleted) {
-        results[key] = variationDetailInternal(key, null, !options.sendEventsOnlyForVariation).value;
+        results[key] = variationDetailInternal(key, null, !options.sendEventsOnlyForVariation, false, true).value;
       }
     }
 
@@ -433,6 +467,7 @@ function initialize(env, user, specifiedOptions, platform, extraOptionDefs) {
             mods[data.key] = { current: newDetail };
           }
           handleFlagChanges(mods); // don't wait for this Promise to be resolved
+          notifyInspectionFlagChanged(data, newFlag);
         } else {
           logger.debug(messages.debugStreamPatchIgnored(data.key));
         }
@@ -449,6 +484,7 @@ function initialize(env, user, specifiedOptions, platform, extraOptionDefs) {
             mods[data.key] = { previous: flags[data.key].value };
           }
           flags[data.key] = { version: data.version, deleted: true };
+          notifyInspectionFlagChanged(data, flags[data.key]);
           handleFlagChanges(mods); // don't wait for this Promise to be resolved
         } else {
           logger.debug(messages.debugStreamDeleteIgnored(data.key));
@@ -490,6 +526,9 @@ function initialize(env, user, specifiedOptions, platform, extraOptionDefs) {
     }
 
     flags = { ...newFlags };
+
+    notifyInspectionFlagsChanged();
+
     return handleFlagChanges(changes).catch(() => {}); // swallow any exceptions from this Promise
   }
 
@@ -663,6 +702,8 @@ function initialize(env, user, specifiedOptions, platform, extraOptionDefs) {
       .fetchFlagSettings(ident.getUser(), hash)
       .then(requestedFlags => {
         flags = requestedFlags || {};
+
+        notifyInspectionFlagsChanged();
         // Note, we don't need to call updateSettings here because local storage and change events are not relevant
         signalSuccessfulInit();
       })

package/src/messages.js

@@ -180,6 +180,10 @@ const debugPostingDiagnosticEvent = function(event) {
   return 'sending diagnostic event (' + event.kind + ')';
 };
 
+const invalidInspector = (type, name) => `an inspector: "${name}" of an invalid type (${type}) was configured`;
+
+const inspectorMethodError = (type, name) => `an inspector: "${name}" of type: "${type}" generated an exception`;
+
 const invalidTagValue = name => `Config option "${name}" must only contain letters, numbers, ., _ or -.`;
 
 const tagValueTooLong = name => `Value of "${name}" was longer than 64 characters and was discarded.`;
@@ -208,8 +212,10 @@ module.exports = {
   httpErrorMessage,
   httpUnavailable,
   identifyDisabled,
+  inspectorMethodError,
   invalidContentType,
   invalidData,
+  invalidInspector,
   invalidKey,
   invalidTagValue,
   invalidUser,

package/typings.d.ts

@@ -287,6 +287,11 @@ declare module 'launchdarkly-js-sdk-common' {
        */
       version?: string;
     }
+
+    /**
+     * Inspectors can be used for collecting information for monitoring, analytics, and debugging.
+     */
+    inspectors?: LDInspection[];
   }
 
   /**
@@ -821,4 +826,105 @@ declare module 'launchdarkly-js-sdk-common' {
    * You can also specify `'none'` instead to disable all logging.
    */
   export type LDLogLevel = 'debug' | 'info' | 'warn' | 'error' | 'none';
+
+  /**
+   * Callback interface for collecting information about the SDK at runtime.
+   * 
+   * This interface is used to collect information about flag usage.
+   * 
+   * This interface should not be used by the application to access flags for the purpose of controlling application
+   * flow. It is intended for monitoring, analytics, or debugging purposes.
+   */
+  interface LDInspectionFlagUsedHandler {
+    type: 'flag-used',
+
+    /**
+     * Name of the inspector. Will be used for logging issues with the inspector.
+     */
+    name: string,
+
+    /**
+     * This method is called when a flag is accessed via a variation method, or it can be called based on actions in
+     * wrapper SDKs which have different methods of tracking when a flag was accessed. It is not called when a call is made
+     * to allFlags.
+     */
+    method: (flagKey: string, flagDetail: LDEvaluationDetail, user: LDUser) => void;
+  }
+  
+  /**
+   * Callback interface for collecting information about the SDK at runtime.
+   * 
+   * This interface is used to collect information about flag data. In order to understand the
+   * current flag state it should be combined with {@link LDInspectionFlagValueChangedHandler}.
+   * This interface will get the initial flag information, and 
+   * {@link LDInspectionFlagValueChangedHandler} will provide changes to individual flags.
+   * 
+   * This interface should not be used by the application to access flags for the purpose of controlling application
+   * flow. It is intended for monitoring, analytics, or debugging purposes.
+   */
+  interface LDInspectionFlagDetailsChangedHandler {
+    type: 'flag-details-changed',
+
+    /**
+     * Name of the inspector. Will be used for logging issues with the inspector.
+     */
+    name: string,
+    
+    /**
+     * This method is called when the flags in the store are replaced with new flags. It will contain all flags
+     * regardless of if they have been evaluated.
+     */
+    method: (details: Record<string, LDEvaluationDetail>) => void;
+  }
+  
+    
+  /**
+   * Callback interface for collecting information about the SDK at runtime.
+   * 
+   * This interface is used to collect changes to flag data, but does not provide the initial
+   * data. It can be combined with {@link LDInspectionFlagValuesChangedHandler} to track the
+   * entire flag state.
+   * 
+   * This interface should not be used by the application to access flags for the purpose of controlling application
+   * flow. It is intended for monitoring, analytics, or debugging purposes.
+   */
+  interface LDInspectionFlagDetailChangedHandler {
+    type: 'flag-detail-changed',
+
+    /**
+     * Name of the inspector. Will be used for logging issues with the inspector.
+     */
+    name: string,
+  
+    /**
+     * This method is called when a flag is updated. It will not be called
+     * when all flags are updated.
+     */
+    method: (flagKey: string, detail: LDEvaluationDetail) => void;
+  }
+
+  /**
+   * Callback interface for collecting information about the SDK at runtime.
+   * 
+   * This interface is used to track current identity state of the SDK.
+   * 
+   * This interface should not be used by the application to access flags for the purpose of controlling application
+   * flow. It is intended for monitoring, analytics, or debugging purposes.
+   */
+  interface LDInspectionIdentifyHandler {
+    type: 'client-identity-changed',
+
+    /**
+     * Name of the inspector. Will be used for logging issues with the inspector.
+     */
+    name: string,
+  
+    /**
+     * This method will be called when an identify operation completes.
+     */
+    method: (user: LDUser) => void;
+  }
+
+  type LDInspection = LDInspectionFlagUsedHandler | LDInspectionFlagDetailsChangedHandler
+    | LDInspectionFlagDetailChangedHandler | LDInspectionIdentifyHandler;
 }