feat: Add FDv2 payload handling to the data source event handler (#305)

## What this adds

`DataSourceEventHandler.handlePayload`: the entry point the FDv2 data
pipeline (a later PR) calls when a payload completes. Nothing produces
payloads for the event handler yet, so behavior is unchanged.

The method maps the payload's updates to item descriptors with the
flag-eval mapper, applies them through `FlagManager.applyChanges` (full
replaces, partial applies, none takes no action), and marks the data
source valid — a payload of any type, including none, confirms the
connection is delivering current data. Unparseable flag data is
classified as an `invalidData` error and reported through the status
manager, mirroring how the FDv1 message verbs handle bad payloads; the
in-progress payload is discarded.

## Testing

New tests cover all three transfer types end to end through the event
handler (full replaces the stored flags and applies the environment ID,
partial applies updates without per-item version comparison, none
changes no data), the valid status transition, and invalid flag data
producing an `invalidData` error with `MessageStatus.invalidMessage`.

SDK-2186

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Low Risk**
> Isolated new API path with no callers yet; behavior mirrors existing
FDv1 error handling and delegates storage semantics to existing
`applyChanges`.
> 
> **Overview**
> Adds **`DataSourceEventHandler.handlePayload`**, the FDv2 entry point
that maps payload updates through `mapUpdatesToItemDescriptors`, applies
them via **`FlagManager.applyChanges`** (full replace, partial merge
without per-flag version checks, **none** leaves flags unchanged),
optionally sets **environment ID** on full transfers, and always marks
the data source **valid** on success.
> 
> Invalid flag-eval data follows the same pattern as FDv1 verbs: log,
**`ErrorKind.invalidData`**, return **`MessageStatus.invalidMessage`**,
and discard the payload. Nothing in this PR wires FDv2 streaming into
the handler yet.
> 
> Tests exercise full/partial/none behavior, valid status, environment
ID on full payloads, and malformed flag-eval objects.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
c44bdeb. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: kinyoklion

packages/common_client/lib/src/data_sources/data_source_event_handler.dart

@@ -6,6 +6,8 @@ import '../flag_manager/flag_manager.dart';
 import '../item_descriptor.dart';
 import 'data_source_status.dart';
 import 'data_source_status_manager.dart';
+import 'fdv2/flag_eval_mapper.dart';
+import 'fdv2/payload.dart';
 
 enum MessageStatus { messageHandled, invalidMessage, unhandledVerb }
 
@@ -96,6 +98,28 @@ final class DataSourceEventHandler {
     }
   }
 
+  /// Applies an FDv2 payload to the flag store.
+  ///
+  /// Full payloads replace the stored flags, partial payloads apply each
+  /// update, and a payload of type none confirms the SDK is up to date
+  /// without changing data. All three mark the data source valid.
+  Future<MessageStatus> handlePayload(LDContext context, Payload payload,
+      {String? environmentId}) async {
+    try {
+      final updates = mapUpdatesToItemDescriptors(payload.updates);
+      await _flagManager.applyChanges(context, updates, payload.type,
+          environmentId: environmentId);
+      _statusManager.setValid();
+      return MessageStatus.messageHandled;
+    } catch (err) {
+      _logger.error('FDv2 payload contained invalid flag data: '
+          '${err.runtimeType}');
+      _statusManager.setErrorByKind(
+          ErrorKind.invalidData, 'FDv2 payload contained invalid data');
+      return MessageStatus.invalidMessage;
+    }
+  }
+
   Future<MessageStatus> _processPut(
       LDContext context, dynamic parsed, String? environmentId) async {
     try {

packages/common_client/test/data_sources/data_source_event_handler_test.dart

@@ -2,6 +2,7 @@ import 'package:launchdarkly_common_client/launchdarkly_common_client.dart';
 import 'package:launchdarkly_common_client/src/data_sources/data_source_event_handler.dart';
 import 'package:launchdarkly_common_client/src/data_sources/data_source_status.dart';
 import 'package:launchdarkly_common_client/src/data_sources/data_source_status_manager.dart';
+import 'package:launchdarkly_common_client/src/data_sources/fdv2/payload.dart';
 import 'package:launchdarkly_common_client/src/flag_manager/flag_manager.dart';
 import 'package:test/test.dart';
 
@@ -284,5 +285,101 @@ void main() {
         expect(updated.flag, isNull);
       });
     });
+
+    group('handlePayload', () {
+      Update flagEval(String key, int version, {Object? value = true}) =>
+          Update(
+            kind: 'flag-eval',
+            key: key,
+            version: version,
+            object: {
+              'flagVersion': 5,
+              'value': value,
+              'variation': 0,
+              'trackEvents': false,
+            },
+          );
+
+      test('a full payload replaces the stored flags and sets valid', () async {
+        expectLater(
+            statusManager!.changes,
+            emits(DataSourceStatus(
+                state: DataSourceState.valid, stateSince: DateTime(2))));
+
+        await eventHandler!.handlePayload(context,
+            Payload(type: PayloadType.full, updates: [flagEval('flagA', 1)]));
+
+        expect(
+            await eventHandler!.handlePayload(
+                context,
+                Payload(
+                    type: PayloadType.full, updates: [flagEval('flagB', 2)]),
+                environmentId: 'the-environment-id'),
+            MessageStatus.messageHandled);
+
+        expect(flagManager!.get('flagA'), isNull,
+            reason: 'a full transfer replaces everything');
+        expect(flagManager!.get('flagB')?.flag?.version, 2);
+        expect(flagManager!.environmentId, 'the-environment-id');
+      });
+
+      test(
+          'a partial payload applies updates without per-item version '
+          'comparison and sets valid', () async {
+        await eventHandler!.handlePayload(context,
+            Payload(type: PayloadType.full, updates: [flagEval('flagA', 7)]));
+
+        expect(
+            await eventHandler!.handlePayload(
+                context,
+                Payload(
+                    type: PayloadType.partial,
+                    updates: [flagEval('flagA', 3, value: false)])),
+            MessageStatus.messageHandled);
+
+        final updated = flagManager!.get('flagA')!.flag!;
+        expect(updated.version, 3,
+            reason: 'FDv2 orders data at the payload level, so a lower '
+                'envelope version still applies');
+        expect(updated.detail.value, LDValue.ofBool(false));
+      });
+
+      test('a payload of none changes no data and sets valid', () async {
+        await eventHandler!.handlePayload(context,
+            Payload(type: PayloadType.full, updates: [flagEval('flagA', 1)]));
+
+        expect(
+            await eventHandler!.handlePayload(
+                context, const Payload(type: PayloadType.none, updates: [])),
+            MessageStatus.messageHandled);
+
+        expect(flagManager!.get('flagA')?.flag?.version, 1);
+      });
+
+      test('invalid flag data sets an invalid data error', () async {
+        expectLater(
+            statusManager!.changes,
+            emits(DataSourceStatus(
+                lastError: DataSourceStatusErrorInfo(
+                    kind: ErrorKind.invalidData,
+                    message: 'FDv2 payload contained invalid data',
+                    statusCode: null,
+                    time: DateTime(2)),
+                state: DataSourceState.initializing,
+                stateSince: DateTime(1))));
+
+        expect(
+            await eventHandler!.handlePayload(
+                context,
+                Payload(type: PayloadType.full, updates: [
+                  const Update(
+                      kind: 'flag-eval',
+                      key: 'bad',
+                      version: 1,
+                      object: {'trackEvents': 'not-a-bool'})
+                ])),
+            MessageStatus.invalidMessage);
+      });
+    });
   });
 }