feat: Add experimental plugin support.

packages/common_client/lib/launchdarkly_common_client.dart

@@ -54,3 +54,17 @@ export 'src/hooks/hook.dart'
         EvaluationSeriesContext,
         IdentifySeriesContext,
         TrackSeriesContext;
+
+export 'src/hooks/operations.dart' show combineHooks;
+
+export 'src/plugins/plugin.dart'
+    show
+        PluginBase,
+        PluginCredentialInfo,
+        PluginEnvironmentMetadata,
+        PluginMetadata,
+        PluginSdkMetadata;
+
+export 'src/plugins/operations.dart' show safeGetHooks, safeRegisterPlugins;
+
+export 'src/config/defaults/credential_type.dart' show CredentialType;

packages/common_client/lib/src/config/defaults/credential_type.dart

@@ -1,4 +1,9 @@
+/// Represents the credential type used by the SDK. The credential type is
+/// determined by the platform the SDK is running on.
 enum CredentialType {
+  /// The SDK is using a mobile key credential.
   mobileKey,
+
+  /// The SDK is using a client-side ID.
   clientSideId,
 }

packages/common_client/lib/src/hooks/operations.dart

@@ -0,0 +1,14 @@
+import 'hook.dart';
+
+List<Hook>? combineHooks(List<Hook>? baseHooks, List<Hook>? extendedHooks) {
+  if (baseHooks == null) {
+    return extendedHooks;
+  }
+  if (extendedHooks == null) {
+    return baseHooks;
+  }
+  List<Hook> combined = [];
+  combined.addAll(baseHooks);
+  combined.addAll(extendedHooks);
+  return combined;
+}

packages/common_client/lib/src/ld_common_client.dart

@@ -850,4 +850,8 @@ final class LDCommonClient {
 
   /// Check if the initialization process is complete.
   bool get initialized => _startCompleter?.isCompleted ?? false;
+
+  /// Get the type of credential the SDK uses.
+  CredentialType get credentialType =>
+      DefaultConfig.credentialConfig.credentialType;
 }

packages/common_client/lib/src/ld_common_config.dart

@@ -1,3 +1,4 @@
+import 'dart:collection';
 import 'dart:math';
 
 import 'package:launchdarkly_dart_common/launchdarkly_dart_common.dart';
@@ -129,7 +130,7 @@ abstract class LDCommonConfig {
   final List<String> globalPrivateAttributes;
 
   /// An initial list of hooks.
-  final List<Hook>? hooks;
+  final UnmodifiableListView<Hook>? hooks;
 
   LDCommonConfig(this.sdkCredential, this.autoEnvAttributes,
       {this.applicationInfo,
@@ -142,7 +143,7 @@ abstract class LDCommonConfig {
       DataSourceConfig? dataSourceConfig,
       bool? allAttributesPrivate,
       List<String>? globalPrivateAttributes,
-      this.hooks})
+      List<Hook>? hooks})
       : httpProperties = httpProperties ?? HttpProperties(),
         serviceEndpoints =
             serviceEndpoints ?? client_endpoints.ServiceEndpoints(),
@@ -153,7 +154,8 @@ abstract class LDCommonConfig {
         dataSourceConfig = dataSourceConfig ?? DataSourceConfig(),
         allAttributesPrivate =
             allAttributesPrivate ?? DefaultConfig.allAttributesPrivate,
-        globalPrivateAttributes = globalPrivateAttributes ?? [];
+        globalPrivateAttributes = globalPrivateAttributes ?? [],
+        hooks = hooks != null ? UnmodifiableListView(List.from(hooks)) : null;
 }
 
 /// Enable / disable options for Auto Environment Attributes functionality.  When enabled, the SDK will automatically

packages/common_client/lib/src/plugins/operations.dart

@@ -0,0 +1,38 @@
+import 'package:launchdarkly_dart_common/launchdarkly_dart_common.dart'
+    show LDLogger;
+
+import 'plugin.dart';
+import '../hooks/hook.dart';
+
+List<Hook>? safeGetHooks<TClient>(
+    List<PluginBase<TClient>>? plugins, LDLogger logger) {
+  if (plugins == null) return null;
+
+  return plugins
+      .map<List<Hook>>((plugin) {
+        try {
+          return plugin.hooks;
+        } catch (err) {
+          logger.warn(
+              'Exception thrown getting hooks for plugin ${plugin.metadata.name}. Unable to get hooks for plugin.');
+        }
+        return [];
+      })
+      .expand<Hook>((hooks) => hooks)
+      .toList();
+}
+
+void safeRegisterPlugins<TClient>(
+    TClient client,
+    PluginEnvironmentMetadata metadata,
+    List<PluginBase<TClient>>? plugins,
+    LDLogger logger) {
+  plugins?.forEach((plugin) {
+    try {
+      plugin.register(client, metadata);
+    } catch (err) {
+      logger.warn(
+          'Exception thrown when registering plugin ${plugin.metadata.name}');
+    }
+  });
+}

packages/common_client/lib/src/plugins/plugin.dart

@@ -0,0 +1,135 @@
+import 'package:launchdarkly_dart_common/launchdarkly_dart_common.dart'
+    show ApplicationInfo;
+
+import '../config/defaults/credential_type.dart';
+import '../hooks/hook.dart' show Hook;
+
+/// Metadata about a plugin implementation.
+///
+/// May be used in logs and analytics to identify the plugin.
+final class PluginMetadata {
+  /// The name of the plugin.
+  final String name;
+
+  const PluginMetadata({required this.name});
+
+  @override
+  String toString() {
+    return 'PluginMetadata{name: $name}';
+  }
+}
+
+/// Metadata about the SDK that is running the plugin.
+final class PluginSdkMetadata {
+  /// The name of the SDK.
+  final String name;
+
+  /// The version of the SDK.
+  final String version;
+
+  /// If this is a wrapper SDK, then this is the name of the wrapper.
+  final String? wrapperName;
+
+  /// If this is a wrapper SDK, then this is the version of the wrapper.
+  final String? wrapperVersion;
+
+  PluginSdkMetadata(
+      {required this.name,
+      required this.version,
+      this.wrapperName,
+      this.wrapperVersion});
+
+  @override
+  String toString() {
+    return 'PluginSdkMetadata{name: $name, version: $version,'
+        ' wrapperName: $wrapperName, wrapperVersion: $wrapperVersion}';
+  }
+}
+
+/// Information about the credential used to initialize the SDK.
+final class PluginCredentialInfo {
+  /// The type of credential.
+  final CredentialType type;
+
+  /// The value of the credential.
+  final String value;
+
+  PluginCredentialInfo({required this.type, required this.value});
+
+  @override
+  String toString() {
+    return 'PluginCredentialInfo{type: $type, value: $value}';
+  }
+}
+
+/// Metadata about the environment where the plugin is running.
+final class PluginEnvironmentMetadata {
+  /// Metadata about the SDK that is running the plugin.
+  final PluginSdkMetadata sdk;
+
+  /// Metadata about the application where the LaunchDarkly SDK is running.
+  ///
+  /// Plugins only have access to application info collected during
+  /// configuration. Application information collected by environment reporting
+  /// is not available.
+  ///
+  /// If access to the environment reporting information is required, then it
+  /// is available via the [LDContext] by using hooks.
+  ///
+  /// Only present if any application information is available.
+  final ApplicationInfo? application;
+
+  /// Information about the credential used to initialize the SDK.
+  final PluginCredentialInfo credential;
+
+  PluginEnvironmentMetadata(
+      {required this.sdk, required this.credential, this.application});
+
+  @override
+  String toString() {
+    return 'PluginEnvironmentMetadata{sdk: $sdk, credential: $credential,'
+        ' application: $application}';
+  }
+}
+
+/// Base class from which all plugins must derive.
+///
+/// Implementation note: SDK packages must export a specialized version of this
+/// for their specific TClient type. This class cannot provide a type, because
+/// it would limit the API to methods available in the base client.
+abstract base class PluginBase<TClient> {
+  /// Metadata associated with this plugin.
+  ///
+  /// Plugin implementations must implement this property.
+  /// ```dart
+  /// final _metadata = PluginMetadata(name: 'MyPluginName');
+  ///
+  /// @override
+  /// PluginMetadata get metadata => _metadata;
+  /// ```
+  PluginMetadata get metadata;
+
+  /// Registers the plugin with the SDK. Called once during SDK initialization.
+  ///
+  /// The SDK initialization will typically not have been completed at this
+  /// point, so the plugin should take appropriate actions to ensure the SDK is
+  /// ready before sending track events or evaluating flags. For example the
+  /// plugin could wait for the [Hook.afterIdentify] stage to indicate success
+  /// before tracking any events.
+  ///
+  /// The [client] the plugin is registered with.
+  void register(
+      TClient client, PluginEnvironmentMetadata environmentMetadata) {}
+
+  /// Hooks which are bundled with this plugin.
+  ///
+  /// Implementations should override this method to return their bundled
+  /// hooks.
+  /// ```dart
+  /// @override
+  /// List<Hook> get hooks => [MyBundledHook()];
+  /// ```
+  List<Hook> get hooks => [];
+
+  PluginBase();
+}