feat: Add Identify hooks to Client SDK (#234)

**Requirements**

Adds BeforeIdentify / AfterIdentify hook stages to the existing hooks
infrastructure, mirroring the evaluation series pattern. Hooks execute
in forward order for BeforeIdentify and reverse (LIFO) order for
AfterIdentify.
Wraps LdClient.IdentifyAsync with the identify hook series so that
configured hooks receive callbacks before and after each identify
operation, with IdentifySeriesResult.Completed on success and
IdentifySeriesResult.Error on failure.
Threads maxWaitTime from Identify / IdentifyAsync into
IdentifySeriesContext.Timeout so hooks have visibility into the caller's
timeout configuration.

- [x] I have added test coverage for new or changed functionality
- [x] I have followed the repository's [pull request submission
guidelines](../blob/main/CONTRIBUTING.md#submitting-pull-requests)
- [x] I have validated my changes against all supported platform
versions
<img width="593" height="801" alt="image"
src="https://github.com/user-attachments/assets/97cc5062-8e50-4eb5-8c2c-ec75e874d6b6"
/>


<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Changes `LdClient` initialization and `Identify`/`IdentifyAsync` flow
to run new hook callbacks and to always emit an identify series result,
which could affect timing/ordering and error propagation around context
changes.
> 
> **Overview**
> Adds an **identify hook series** to the SDK hook infrastructure,
introducing `Hook.BeforeIdentify`/`Hook.AfterIdentify` plus new
`IdentifySeriesContext` (includes timeout) and `IdentifySeriesResult`
(Completed/Error).
> 
> Extends the internal hook executor (`IHookExecutor`, `Executor`,
`NoopExecutor`) with an async `IdentifySeries` pipeline that runs hooks
in forward order before identify and reverse order after, logging and
isolating hook-stage failures while still propagating identify
exceptions.
> 
> Updates `LdClient` to route both startup identify event recording and
`Identify`/`IdentifyAsync` through the new identify series (including
threading `maxWaitTime` into hook context) and adds unit tests covering
ordering, data passing, logging on hook errors, result status, and
activation during init.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
b881e20. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: abelonogov-ld

pkgs/sdk/client/src/Hooks/Hook.cs

@@ -74,6 +74,35 @@ public virtual SeriesData BeforeEvaluation(EvaluationSeriesContext context, Seri
         public virtual SeriesData AfterEvaluation(EvaluationSeriesContext context, SeriesData data,
             EvaluationDetail<LdValue> detail) => data;
 
+
+        /// <summary>
+        /// BeforeIdentify is executed by the SDK before an identify operation.
+        ///
+        /// The modified data is not shared with any other hook. It will be passed to subsequent stages in the identify
+        /// series, including <see cref="AfterIdentify"/>.
+        ///
+        /// </summary>
+        /// <param name="context">parameters associated with this identify operation</param>
+        /// <param name="data">user-configurable data, currently empty</param>
+        /// <returns>user-configurable data, which will be forwarded to <see cref="AfterIdentify"/></returns>
+        public virtual SeriesData BeforeIdentify(IdentifySeriesContext context, SeriesData data) =>
+            data;
+
+
+        /// <summary>
+        /// AfterIdentify is executed by the SDK after an identify operation.
+        ///
+        /// The function should return the given <see cref="SeriesData"/> unmodified, for forward compatibility with subsequent
+        /// stages that may be added.
+        ///
+        /// </summary>
+        /// <param name="context">parameters associated with this identify operation</param>
+        /// <param name="data">user-configurable data from the <see cref="BeforeIdentify"/> stage</param>
+        /// <param name="result">the result of the identify operation</param>
+        /// <returns>user-configurable data, which is currently unused but may be forwarded to subsequent stages in future versions of the SDK</returns>
+        public virtual SeriesData AfterIdentify(IdentifySeriesContext context, SeriesData data,
+            IdentifySeriesResult result) => data;
+
         /// <summary>
         /// Constructs a new Hook with the given name. The name may be used in log messages.
         /// </summary>

pkgs/sdk/client/src/Hooks/IdentifySeriesContext.cs

@@ -0,0 +1,33 @@
+using System;
+
+namespace LaunchDarkly.Sdk.Client.Hooks
+{
+    /// <summary>
+    /// IdentifySeriesContext represents parameters associated with an identify operation. It is
+    /// made available in <see cref="Hook"/> stage callbacks.
+    /// </summary>
+    public sealed class IdentifySeriesContext
+    {
+        /// <summary>
+        /// The Context being identified.
+        /// </summary>
+        public Context Context { get; }
+
+        /// <summary>
+        /// The timeout for the identify operation. A value of <see cref="TimeSpan.Zero"/> indicates
+        /// that no timeout was specified.
+        /// </summary>
+        public TimeSpan Timeout { get; }
+
+        /// <summary>
+        /// Constructs a new IdentifySeriesContext.
+        /// </summary>
+        /// <param name="context">the context being identified</param>
+        /// <param name="timeout">the timeout for the identify operation</param>
+        public IdentifySeriesContext(Context context, TimeSpan timeout)
+        {
+            Context = context;
+            Timeout = timeout;
+        }
+    }
+}

pkgs/sdk/client/src/Hooks/IdentifySeriesResult.cs

@@ -0,0 +1,38 @@
+namespace LaunchDarkly.Sdk.Client.Hooks
+{
+    /// <summary>
+    /// IdentifySeriesResult contains the outcome of an identify operation.
+    /// </summary>
+    public sealed class IdentifySeriesResult
+    {
+        /// <summary>
+        /// Represents the possible statuses of an identify operation.
+        /// </summary>
+        public enum IdentifySeriesStatus
+        {
+            /// <summary>
+            /// The identify operation completed successfully.
+            /// </summary>
+            Completed,
+
+            /// <summary>
+            /// The identify operation encountered an error.
+            /// </summary>
+            Error
+        }
+
+        /// <summary>
+        /// The status of the identify operation.
+        /// </summary>
+        public IdentifySeriesStatus Status { get; }
+
+        /// <summary>
+        /// Constructs a new IdentifySeriesResult.
+        /// </summary>
+        /// <param name="status">the status of the identify operation</param>
+        public IdentifySeriesResult(IdentifySeriesStatus status)
+        {
+            Status = status;
+        }
+    }
+}

pkgs/sdk/client/src/ILdClientExtensions.cs

@@ -1,4 +1,4 @@
-using System;
+using System;
 using System.Threading.Tasks;
 using LaunchDarkly.Sdk.Client.Interfaces;
 

pkgs/sdk/client/src/Interfaces/IFlagTracker.cs

@@ -1,4 +1,4 @@
-using System;
+using System;
 
 namespace LaunchDarkly.Sdk.Client.Interfaces
 {

pkgs/sdk/client/src/Interfaces/ILdClient.cs

@@ -1,4 +1,4 @@
-using System;
+using System;
 using System.Collections.Generic;
 using System.Threading.Tasks;
 using LaunchDarkly.Sdk.Client.Integrations;

pkgs/sdk/client/src/Internal/Hooks/Executor/Executor.cs

@@ -1,6 +1,7 @@
 using System;
 using System.Collections.Generic;
 using System.Linq;
+using System.Threading.Tasks;
 using LaunchDarkly.Logging;
 using LaunchDarkly.Sdk.Client.Hooks;
 using LaunchDarkly.Sdk.Client.Internal.Hooks.Interfaces;
@@ -16,12 +17,17 @@ internal sealed class Executor : IHookExecutor
         private readonly IStageExecutor<EvaluationSeriesContext> _beforeEvaluation;
         private readonly IStageExecutor<EvaluationSeriesContext, EvaluationDetail<LdValue>> _afterEvaluation;
 
+        private readonly IStageExecutor<IdentifySeriesContext> _beforeIdentify;
+        private readonly IStageExecutor<IdentifySeriesContext, IdentifySeriesResult> _afterIdentify;
+
         public Executor(Logger logger, IEnumerable<Hook> hooks)
         {
             _logger = logger;
             _hooks = hooks.ToList();
             _beforeEvaluation = new BeforeEvaluation(logger, _hooks, EvaluationStage.Order.Forward);
             _afterEvaluation = new AfterEvaluation(logger, _hooks, EvaluationStage.Order.Reverse);
+            _beforeIdentify = new BeforeIdentify(logger, _hooks, EvaluationStage.Order.Forward);
+            _afterIdentify = new AfterIdentify(logger, _hooks, EvaluationStage.Order.Reverse);
         }
 
         public EvaluationDetail<T> EvaluationSeries<T>(EvaluationSeriesContext context,
@@ -38,6 +44,31 @@ public EvaluationDetail<T> EvaluationSeries<T>(EvaluationSeriesContext context,
             return detail;
         }
 
+        public async Task<bool> IdentifySeries(Context context, TimeSpan maxWaitTime, Func<Task<bool>> identify)
+        {
+            var identifyContext = new IdentifySeriesContext(context, maxWaitTime);
+            var seriesData = _beforeIdentify.Execute(identifyContext, default);
+
+            try
+            {
+                var result = await identify();
+
+                _afterIdentify.Execute(identifyContext,
+                    new IdentifySeriesResult(IdentifySeriesResult.IdentifySeriesStatus.Completed),
+                    seriesData);
+
+                return result;
+            }
+            catch (Exception)
+            {
+                _afterIdentify.Execute(identifyContext,
+                    new IdentifySeriesResult(IdentifySeriesResult.IdentifySeriesStatus.Error),
+                    seriesData);
+
+                throw;
+            }
+        }
+
         public void Dispose()
         {
             foreach (var hook in _hooks)

pkgs/sdk/client/src/Internal/Hooks/Executor/NoopExecutor.cs

@@ -1,4 +1,5 @@
 using System;
+using System.Threading.Tasks;
 using LaunchDarkly.Sdk.Client.Hooks;
 using LaunchDarkly.Sdk.Client.Internal.Hooks.Interfaces;
 
@@ -13,6 +14,9 @@ internal sealed class NoopExecutor : IHookExecutor
         public EvaluationDetail<T> EvaluationSeries<T>(EvaluationSeriesContext context,
             LdValue.Converter<T> converter, Func<EvaluationDetail<T>> evaluate) => evaluate();
 
+        public Task<bool> IdentifySeries(Context context, TimeSpan maxWaitTime, Func<Task<bool>> identify) =>
+            identify();
+
         public void Dispose()
         {
         }

pkgs/sdk/client/src/Internal/Hooks/Interfaces/IHookExecutor.cs

@@ -1,4 +1,5 @@
 using System;
+using System.Threading.Tasks;
 using LaunchDarkly.Sdk.Client.Hooks;
 
 namespace LaunchDarkly.Sdk.Client.Internal.Hooks.Interfaces
@@ -12,7 +13,8 @@ namespace LaunchDarkly.Sdk.Client.Internal.Hooks.Interfaces
     internal interface IHookExecutor : IDisposable
     {
         /// <summary>
-        /// EvaluationSeries should run the evaluation series for each configured hook.
+        /// Runs the evaluation series for each configured hook, invoking the <paramref name="evaluate"/>
+        /// delegate to obtain the flag value. Exceptions thrown by the delegate are propagated to the caller.
         /// </summary>
         /// <param name="context">context for the evaluation series</param>
         /// <param name="converter">used to convert the primitive evaluation value into a wrapped <see cref="LdValue"/> suitable for use in hooks</param>
@@ -21,5 +23,16 @@ internal interface IHookExecutor : IDisposable
         /// <returns>the EvaluationDetail returned from the evaluator</returns>
         EvaluationDetail<T> EvaluationSeries<T>(EvaluationSeriesContext context,
             LdValue.Converter<T> converter, Func<EvaluationDetail<T>> evaluate);
+
+        /// <summary>
+        /// Runs the identify series for each configured hook, invoking the <paramref name="identify"/>
+        /// delegate to perform the identify operation. Exceptions thrown by the delegate are propagated
+        /// to the caller.
+        /// </summary>
+        /// <param name="context">the evaluation context being identified</param>
+        /// <param name="maxWaitTime">the timeout for the identify operation</param>
+        /// <param name="identify">async function that performs the identify operation</param>
+        /// <returns>the result of the identify operation</returns>
+        Task<bool> IdentifySeries(Context context, TimeSpan maxWaitTime, Func<Task<bool>> identify);
     }
 }

pkgs/sdk/client/src/Internal/Hooks/Series/IdentifySeries.cs

@@ -0,0 +1,89 @@
+using System;
+using System.Collections.Generic;
+using System.Collections.Immutable;
+using System.Linq;
+using LaunchDarkly.Logging;
+using LaunchDarkly.Sdk.Client.Hooks;
+using LaunchDarkly.Sdk.Client.Internal.Hooks.Interfaces;
+
+namespace LaunchDarkly.Sdk.Client.Internal.Hooks.Series
+{
+    using SeriesData = ImmutableDictionary<string, object>;
+
+    internal class IdentifyStage
+    {
+        protected enum Stage
+        {
+            BeforeIdentify,
+            AfterIdentify
+        }
+
+        protected readonly EvaluationStage.Order _order;
+        private readonly Logger _logger;
+
+        protected IdentifyStage(Logger logger, EvaluationStage.Order order)
+        {
+            _logger = logger;
+            _order = order;
+        }
+
+        protected void LogFailure(IdentifySeriesContext context, Hook h, Stage stage, Exception e)
+        {
+            _logger.Error("During identify of context \"{0}\", stage \"{1}\" of hook \"{2}\" reported error: {3}",
+                context.Context.Key, stage.ToString(), h.Metadata.Name, e.Message);
+        }
+    }
+
+    internal sealed class BeforeIdentify : IdentifyStage, IStageExecutor<IdentifySeriesContext>
+    {
+        private readonly IEnumerable<Hook> _hooks;
+
+        public BeforeIdentify(Logger logger, IEnumerable<Hook> hooks, EvaluationStage.Order order) : base(logger, order)
+        {
+            _hooks = (order == EvaluationStage.Order.Forward) ? hooks : hooks.Reverse();
+        }
+
+        public IEnumerable<SeriesData> Execute(IdentifySeriesContext context, IEnumerable<SeriesData> _)
+        {
+            return _hooks.Select(hook =>
+            {
+                try
+                {
+                    return hook.BeforeIdentify(context, SeriesData.Empty);
+                }
+                catch (Exception e)
+                {
+                    LogFailure(context, hook, Stage.BeforeIdentify, e);
+                    return SeriesData.Empty;
+                }
+            }).ToList();
+        }
+    }
+
+    internal sealed class AfterIdentify : IdentifyStage, IStageExecutor<IdentifySeriesContext, IdentifySeriesResult>
+    {
+        private readonly IEnumerable<Hook> _hooks;
+
+        public AfterIdentify(Logger logger, IEnumerable<Hook> hooks, EvaluationStage.Order order) : base(logger, order)
+        {
+            _hooks = (order == EvaluationStage.Order.Forward) ? hooks : hooks.Reverse();
+        }
+
+        public IEnumerable<SeriesData> Execute(IdentifySeriesContext context, IdentifySeriesResult result,
+            IEnumerable<SeriesData> seriesData)
+        {
+            return _hooks.Zip((_order == EvaluationStage.Order.Reverse ? seriesData.Reverse() : seriesData), (hook, data) =>
+            {
+                try
+                {
+                    return hook.AfterIdentify(context, data, result);
+                }
+                catch (Exception e)
+                {
+                    LogFailure(context, hook, Stage.AfterIdentify, e);
+                    return SeriesData.Empty;
+                }
+            }).ToList();
+        }
+    }
+}