feat: Support for per-context summary events. (#243)

Adds support for per-context summary events.

<!-- CURSOR_SUMMARY -->
> [!NOTE]
> **Medium Risk**
> Changes analytics event shape and batching behavior (multiple summary
events, optional embedded context), which could affect downstream
ingestion and privacy expectations if misconfigured or if context
equality differs from expectations.
> 
> **Overview**
> Adds **per-context summary event** support by changing
`EventSummarizer` to maintain separate accumulators per unique
`LDContext` (with an option `summariesPerContext` to fall back to a
single global summary).
> 
> `DefaultEventProcessor` now flushes *multiple* summary events and
`SummaryEvent`/`SummaryEventSerialization` gain optional `context`
output, serialized with event-style privacy filtering. Contract-test
capabilities and common-client dependency are updated, and tests are
expanded/updated for the new multi-summary behavior and context
handling.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
d2eb218. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: kinyoklion

apps/flutter_client_contract_test_service/bin/contract_test_service.dart

@@ -25,6 +25,7 @@ class TestApiImpl extends SdkTestApi {
     'context-comparison',
     'inline-context-all',
     'anonymous-redaction',
+    'client-per-context-summaries',
     'client-prereq-events',
     'auto-env-attributes',
   ];

packages/common/lib/src/events/default_event_processor.dart

@@ -24,7 +24,7 @@ const _eventSchema = '4';
 // along with the corresponding context de-duplication.
 
 final class DefaultEventProcessor implements EventProcessor {
-  final _eventSummarizer = EventSummarizer();
+  final EventSummarizer _eventSummarizer;
   final LDLogger _logger;
   final int _eventCapacity;
   final Duration _flushInterval;
@@ -60,6 +60,7 @@ final class DefaultEventProcessor implements EventProcessor {
       required Duration diagnosticRecordingInterval,
       required bool allAttributesPrivate,
       required Set<AttributeReference> globalPrivateAttributes,
+      bool summariesPerContext = true,
       DiagnosticsManager? diagnosticsManager})
       : _logger = logger.subLogger('EventProcessor'),
         _eventCapacity = eventCapacity,
@@ -68,7 +69,9 @@ final class DefaultEventProcessor implements EventProcessor {
         _allAttributesPrivate = allAttributesPrivate,
         _globalPrivateAttributes = globalPrivateAttributes,
         _diagnosticsManager = diagnosticsManager,
-        _diagnosticRecordingInterval = diagnosticRecordingInterval {
+        _diagnosticRecordingInterval = diagnosticRecordingInterval,
+        _eventSummarizer =
+            EventSummarizer(summariesPerContext: summariesPerContext) {
     _eventsUri = Uri.parse(appendPath(endpoints.events, analyticsEventsPath));
 
     _diagnosticEventsUri =
@@ -160,11 +163,16 @@ final class DefaultEventProcessor implements EventProcessor {
     final eventsToFlush = _eventBuffer;
     _eventBuffer = [];
 
-    final summaryEvent = _eventSummarizer.createEventAndReset();
+    final summaryEvents = _eventSummarizer.createEventsAndReset();
 
-    if (summaryEvent != null) {
-      eventsToFlush.add(SummaryEventSerialization.toJson(summaryEvent));
+    for (final summaryEvent in summaryEvents) {
+      eventsToFlush.add(SummaryEventSerialization.toJson(
+        summaryEvent,
+        allAttributesPrivate: _allAttributesPrivate,
+        globalPrivateAttributes: _globalPrivateAttributes,
+      ));
     }
+
     if (eventsToFlush.isEmpty) {
       return;
     }

packages/common/lib/src/events/event_summarizer.dart

@@ -1,3 +1,4 @@
+import '../ld_context.dart';
 import '../ld_value.dart';
 import 'events.dart';
 
@@ -37,45 +38,39 @@ final class _SummaryCounter {
   }
 }
 
-/// Tracks evaluation events in order to generate summary events.
-final class EventSummarizer {
+/// Accumulates summary statistics.
+/// When [includeContextInSummary] is true, the context is included in the generated
+/// summary event. When false, statistics are aggregated without context information.
+final class _ContextAccumulator {
   int _startDate = 0;
   int _endDate = 0;
-
+  final LDContext context;
+  final bool includeContextInSummary;
   final Map<FlagKey, _SummaryCounter> _features = {};
 
-  void summarize(EvalEvent event) {
-    if (!_features.containsKey(event.flagKey)) {
-      _features[event.flagKey] = _SummaryCounter(event.defaultValue);
-    }
-    _features[event.flagKey]!.count(
-        event.evaluationDetail.variationIndex,
-        event.version,
-        event.evaluationDetail.value,
-        event.context.attributesByKind.keys.toSet());
-
-    if (event.creationDate.millisecondsSinceEpoch < _startDate ||
-        _startDate == 0) {
-      _startDate = event.creationDate.millisecondsSinceEpoch;
-    }
-    if (event.creationDate.millisecondsSinceEpoch > _endDate) {
-      _endDate = event.creationDate.millisecondsSinceEpoch;
+  _ContextAccumulator(this.context, {required this.includeContextInSummary});
+
+  void count(FlagKey flagKey, LDValue defaultValue, Variation variation,
+      Version version, LDValue value, Set<String> contextKinds) {
+    if (!_features.containsKey(flagKey)) {
+      _features[flagKey] = _SummaryCounter(defaultValue);
     }
+    _features[flagKey]!.count(variation, version, value, contextKinds);
   }
 
-  void _clear() {
-    _startDate = 0;
-    _endDate = 0;
-    _features.clear();
+  void updateDates(DateTime eventDate) {
+    final timestamp = eventDate.millisecondsSinceEpoch;
+    if (timestamp < _startDate || _startDate == 0) {
+      _startDate = timestamp;
+    }
+    if (timestamp > _endDate) {
+      _endDate = timestamp;
+    }
   }
 
-  SummaryEvent? createEventAndReset() {
+  SummaryEvent createSummary() {
     final features = <String, FlagSummary>{};
 
-    if (_features.isEmpty) {
-      return null;
-    }
-
     for (var feature in _features.entries) {
       final counters = <FlagCounter>[];
 
@@ -100,9 +95,65 @@ final class EventSummarizer {
     final startDate = DateTime.fromMillisecondsSinceEpoch(_startDate);
     final endDate = DateTime.fromMillisecondsSinceEpoch(_endDate);
 
-    _clear();
-
     return SummaryEvent(
-        startDate: startDate, endDate: endDate, features: features);
+      startDate: startDate,
+      endDate: endDate,
+      features: features,
+      context: includeContextInSummary ? context : null,
+    );
+  }
+}
+
+/// Tracks evaluation events in order to generate summary events.
+/// When [summariesPerContext] is true, generates one summary event per unique context.
+/// When false, generates a single global summary event without context information.
+final class EventSummarizer {
+  final bool summariesPerContext;
+  final Map<LDContext?, _ContextAccumulator> _accumulatorsByContext = {};
+
+  EventSummarizer({this.summariesPerContext = true});
+
+  void summarize(EvalEvent event) {
+    // Skip invalid contexts
+    if (!event.context.valid) {
+      return;
+    }
+
+    // When per-context summaries are disabled, use null as the key so all
+    // events go into a single accumulator. When enabled, use the actual context
+    // as the key so each unique context gets its own accumulator.
+    final contextKey = summariesPerContext ? event.context : null;
+
+    // Get or create accumulator for this context key
+    final accumulator = _accumulatorsByContext.putIfAbsent(
+      contextKey,
+      () => _ContextAccumulator(event.context,
+          includeContextInSummary: summariesPerContext),
+    );
+
+    // Update the accumulator
+    accumulator.count(
+      event.flagKey,
+      event.defaultValue,
+      event.evaluationDetail.variationIndex,
+      event.version,
+      event.evaluationDetail.value,
+      event.context.attributesByKind.keys.toSet(),
+    );
+    accumulator.updateDates(event.creationDate);
+  }
+
+  List<SummaryEvent> createEventsAndReset() {
+    if (_accumulatorsByContext.isEmpty) {
+      return [];
+    }
+
+    final events = _accumulatorsByContext.values
+        .map((accumulator) => accumulator.createSummary())
+        .toList();
+
+    _accumulatorsByContext.clear();
+
+    return events;
   }
 }

packages/common/lib/src/events/events.dart

@@ -144,12 +144,17 @@ final class SummaryEvent {
   final DateTime startDate;
   final DateTime endDate;
   final Map<String, FlagSummary> features;
+  final LDContext? context;
 
-  SummaryEvent(
-      {required this.startDate, required this.endDate, required this.features});
+  SummaryEvent({
+    required this.startDate,
+    required this.endDate,
+    required this.features,
+    this.context,
+  });
 
   @override
   String toString() {
-    return 'SummaryEvent{startDate: $startDate, endDate: $endDate, features: $features}';
+    return 'SummaryEvent{startDate: $startDate, endDate: $endDate, features: $features, context: $context}';
   }
 }

packages/common/lib/src/serialization/event_serialization.dart

@@ -110,7 +110,9 @@ final class _FlagSummarySerialization {
 }
 
 final class SummaryEventSerialization {
-  static Map<String, dynamic> toJson(SummaryEvent event) {
+  static Map<String, dynamic> toJson(SummaryEvent event,
+      {required bool allAttributesPrivate,
+      required Set<AttributeReference> globalPrivateAttributes}) {
     final json = <String, dynamic>{};
 
     json['kind'] = 'summary';
@@ -119,6 +121,19 @@ final class SummaryEventSerialization {
     json['features'] = event.features.map(
         (key, value) => MapEntry(key, _FlagSummarySerialization.toJson(value)));
 
+    // Serialize context with event-style privacy filtering (if present)
+    if (event.context != null) {
+      final contextJson = LDContextSerialization.toJson(
+        event.context!,
+        isEvent: true,
+        allAttributesPrivate: allAttributesPrivate,
+        globalPrivateAttributes: globalPrivateAttributes,
+      );
+      if (contextJson != null) {
+        json['context'] = contextJson;
+      }
+    }
+
     return json;
   }
 }