feat(multi-provider): add track method support with strategy customization

Signed-off-by: Jonathan Norris <[email protected]>

Author: jonathannorris

libs/providers/multi-provider/README.md

@@ -6,21 +6,23 @@ the final result. Different evaluation strategies can be defined to control whic
 
 The Multi-Provider is a powerful tool for performing migrations between flag providers, or combining multiple providers into a single
 feature flagging interface. For example:
+
 - *Migration*: When migrating between two providers, you can run both in parallel under a unified flagging interface. As flags are added to the
 new provider, the Multi-Provider will automatically find and return them, falling back to the old provider if the new provider does not have
-- *Multiple Data Sources*: The Multi-Provider allows you to seamlessly combine many sources of flagging data, such as environment variables, 
+- *Multiple Data Sources*: The Multi-Provider allows you to seamlessly combine many sources of flagging data, such as environment variables,
 local files, database values and SaaS hosted feature management systems.
 
 ## Installation
 
-```
+```bash
 $ npm install @openfeature/multi-provider
 ```
 
 > [!TIP]
 > This provider is designed to be used with the [Node.js SDK](https://openfeature.dev/docs/reference/technologies/server/javascript/).
 
 ## Usage
+
 The Multi-Provider is initialized with an array of providers it should evaluate:
 
 ```typescript
@@ -66,8 +68,10 @@ const multiProvider = new MultiProvider(
     new FirstSuccessfulStrategy()
 )
 ```
+
 The Multi-Provider comes with three strategies out of the box:
-`FirstMatchStrategy` (default): Evaluates all providers in order and returns the first successful result. Providers that indicate FLAG_NOT_FOUND error will be skipped and the next provider will be evaluated. Any other error will cause the operation to fail and the set of errors to be thrown. 
+
+- `FirstMatchStrategy` (default): Evaluates all providers in order and returns the first successful result. Providers that indicate FLAG_NOT_FOUND error will be skipped and the next provider will be evaluated. Any other error will cause the operation to fail and the set of errors to be thrown.
 - `FirstSuccessfulStrategy`: Evaluates all providers in order and returns the first successful result. Any error will cause that provider to be skipped.
 If no successful result is returned, the set of errors will be thrown.
 - `ComparisonStrategy`: Evaluates all providers in parallel. If every provider returns a successful result with the same value, then that result is returned.
@@ -97,8 +101,59 @@ const multiProvider = new MultiProvider(
 ```
 The first argument is the "fallback provider" whose value to use in the event that providers do not agree. It should be the same object reference as one of the providers in the list. The second argument is a callback function that will be executed when a mismatch is detected. The callback will be passed an object containing the details of each provider's resolution, including the flag key, the value returned, and any errors that were thrown.
 
+## Tracking Support
+
+The Multi-Provider supports tracking events across multiple providers. When you call the `track` method, it will by default send the tracking event to all underlying providers that implement the `track` method.
+
+```typescript
+import { OpenFeature } from '@openfeature/server-sdk'
+
+const client = OpenFeature.getClient()
+
+// Track an event - this will be sent to all providers
+client.track('purchase', { targetingKey: 'user123' }, { value: 99.99, currency: 'USD' })
+```
+
+### Tracking Behavior
+
+- **Default**: All providers receive tracking calls
+- **Error Handling**: If one provider fails to track, others continue normally and errors are logged
+- **Provider Status**: Providers in `NOT_READY` or `FATAL` status are automatically skipped
+- **Optional Method**: Providers without a `track` method are gracefully skipped
+
+### Customizing Tracking with Strategies
+
+You can customize which providers receive tracking calls by overriding the `shouldTrackWithThisProvider` method in your custom strategy:
+
+```typescript
+import { BaseEvaluationStrategy, StrategyPerProviderContext } from '@openfeature/multi-provider'
+
+class CustomTrackingStrategy extends BaseEvaluationStrategy {
+  shouldTrackWithThisProvider(
+    strategyContext: StrategyPerProviderContext,
+    context: EvaluationContext,
+    trackingEventName: string,
+    trackingEventDetails: TrackingEventDetails,
+  ): boolean {
+    // Only track with the primary provider
+    if (strategyContext.providerName === 'primary-provider') {
+      return true;
+    }
+    
+    // Skip tracking for analytics events on backup providers
+    if (trackingEventName.startsWith('analytics.')) {
+      return false;
+    }
+    
+    return super.shouldTrackWithThisProvider(strategyContext, context, trackingEventName, trackingEventDetails);
+  }
+}
+```
+
 ## Custom Strategies
+
 It is also possible to implement your own strategy if the above options do not fit your use case. To do so, create a class which implements the "BaseEvaluationStrategy":
+
 ```typescript
 export abstract class BaseEvaluationStrategy {
     public runMode: 'parallel' | 'sequential' = 'sequential';
@@ -111,13 +166,21 @@ export abstract class BaseEvaluationStrategy {
         result: ProviderResolutionResult<T>,
     ): boolean;
 
+    abstract shouldTrackWithThisProvider(
+        strategyContext: StrategyPerProviderContext,
+        context: EvaluationContext,
+        trackingEventName: string,
+        trackingEventDetails: TrackingEventDetails,
+    ): boolean;
+
     abstract determineFinalResult<T extends FlagValue>(
         strategyContext: StrategyEvaluationContext,
         context: EvaluationContext,
         resolutions: ProviderResolutionResult<T>[],
     ): FinalResult<T>;
 }
 ```
+
 The `runMode` property determines whether the list of providers will be evaluated sequentially or in parallel.
 
 The `shouldEvaluateThisProvider` method is called just before a provider is evaluated by the Multi-Provider. If the function returns `false`, then
@@ -127,6 +190,8 @@ Check the type definitions for the full list.
 The `shouldEvaluateNextProvider` function is called after a provider is evaluated. If it returns `true`, the next provider in the sequence will be called,
 otherwise no more providers will be evaluated. It is called with the same data as `shouldEvaluateThisProvider` as well as the details about the evaluation result. This function is not called when the `runMode` is `parallel`.
 
+The `shouldTrackWithThisProvider` method is called before sending a tracking event to each provider. Return `false` to skip tracking with that provider. By default, it only tracks with providers that are in a ready state (not `NOT_READY` or `FATAL`). Override this method to implement custom tracking logic based on the tracking event name, details, or provider characteristics.
+
 The `determineFinalResult` function is called after all providers have been called, or the `shouldEvaluateNextProvider` function returned false. It is called
 with a list of results from all the individual providers' evaluations. It returns the final decision for evaluation result, or throws an error if needed.
 

libs/providers/multi-provider/src/lib/multi-provider.spec.ts

@@ -7,6 +7,7 @@ import type {
   Logger,
   Provider,
   ProviderMetadata,
+  TrackingEventDetails,
 } from '@openfeature/server-sdk';
 import {
   DefaultLogger,
@@ -26,6 +27,8 @@ class TestProvider implements Provider {
   };
   public events = new OpenFeatureEventEmitter();
   public hooks: Hook[] = [];
+  public track = jest.fn();
+
   constructor(
     public resolveBooleanEvaluation = jest.fn().mockResolvedValue({ value: false }),
     public resolveStringEvaluation = jest.fn().mockResolvedValue({ value: 'default' }),
@@ -769,4 +772,161 @@ describe('MultiProvider', () => {
       });
     });
   });
+
+  describe('tracking', () => {
+    const context: EvaluationContext = { targetingKey: 'user123' };
+    const trackingEventDetails: TrackingEventDetails = { value: 100, currency: 'USD' };
+
+    it('calls track on all providers by default', () => {
+      const provider1 = new TestProvider();
+      const provider2 = new TestProvider();
+      const provider3 = new TestProvider();
+
+      const multiProvider = new MultiProvider([
+        { provider: provider1 },
+        { provider: provider2 },
+        { provider: provider3 },
+      ]);
+
+      multiProvider.track('purchase', context, trackingEventDetails);
+
+      expect(provider1.track).toHaveBeenCalledWith('purchase', context, trackingEventDetails);
+      expect(provider2.track).toHaveBeenCalledWith('purchase', context, trackingEventDetails);
+      expect(provider3.track).toHaveBeenCalledWith('purchase', context, trackingEventDetails);
+    });
+
+    it('skips providers without track method', () => {
+      const provider1 = new TestProvider();
+      const provider2 = new InMemoryProvider(); // Doesn't have track method
+      const provider3 = new TestProvider();
+
+      const multiProvider = new MultiProvider([
+        { provider: provider1 },
+        { provider: provider2 },
+        { provider: provider3 },
+      ]);
+
+      expect(() => multiProvider.track('purchase', context, trackingEventDetails)).not.toThrow();
+      expect(provider1.track).toHaveBeenCalledWith('purchase', context, trackingEventDetails);
+      expect(provider3.track).toHaveBeenCalledWith('purchase', context, trackingEventDetails);
+    });
+
+    it('continues tracking with other providers when one throws an error', () => {
+      const provider1 = new TestProvider();
+      const provider2 = new TestProvider();
+      const provider3 = new TestProvider();
+
+      provider2.track.mockImplementation(() => {
+        throw new Error('Tracking failed');
+      });
+
+      const mockLogger = { error: jest.fn(), warn: jest.fn(), info: jest.fn(), debug: jest.fn() };
+      const multiProvider = new MultiProvider(
+        [{ provider: provider1 }, { provider: provider2 }, { provider: provider3 }],
+        undefined,
+        mockLogger,
+      );
+
+      expect(() => multiProvider.track('purchase', context, trackingEventDetails)).not.toThrow();
+
+      expect(provider1.track).toHaveBeenCalledWith('purchase', context, trackingEventDetails);
+      expect(provider2.track).toHaveBeenCalledWith('purchase', context, trackingEventDetails);
+      expect(provider3.track).toHaveBeenCalledWith('purchase', context, trackingEventDetails);
+      expect(mockLogger.error).toHaveBeenCalledWith(
+        'Error tracking event "purchase" with provider "TestProvider-2":',
+        expect.any(Error),
+      );
+    });
+
+    it('respects strategy shouldTrackWithThisProvider decision', () => {
+      const provider1 = new TestProvider();
+      const provider2 = new TestProvider();
+      const provider3 = new TestProvider();
+
+      const mockStrategy = new FirstMatchStrategy();
+      mockStrategy.shouldTrackWithThisProvider = jest
+        .fn()
+        .mockReturnValueOnce(true) // provider1: should track
+        .mockReturnValueOnce(false) // provider2: should not track
+        .mockReturnValueOnce(true); // provider3: should track
+
+      const multiProvider = new MultiProvider(
+        [{ provider: provider1 }, { provider: provider2 }, { provider: provider3 }],
+        mockStrategy,
+      );
+
+      multiProvider.track('purchase', context, trackingEventDetails);
+
+      expect(provider1.track).toHaveBeenCalledWith('purchase', context, trackingEventDetails);
+      expect(provider2.track).not.toHaveBeenCalled();
+      expect(provider3.track).toHaveBeenCalledWith('purchase', context, trackingEventDetails);
+
+      expect(mockStrategy.shouldTrackWithThisProvider).toHaveBeenCalledTimes(3);
+      expect(mockStrategy.shouldTrackWithThisProvider).toHaveBeenCalledWith(
+        expect.objectContaining({
+          provider: provider1,
+          providerName: 'TestProvider-1',
+        }),
+        context,
+        'purchase',
+        trackingEventDetails,
+      );
+    });
+
+    it('does not track with providers in NOT_READY or FATAL status by default', () => {
+      const provider1 = new TestProvider();
+      const provider2 = new TestProvider();
+      const provider3 = new TestProvider();
+
+      const multiProvider = new MultiProvider([
+        { provider: provider1 },
+        { provider: provider2 },
+        { provider: provider3 },
+      ]);
+
+      // Simulate providers with different statuses
+      const mockStatusTracker = {
+        providerStatus: jest
+          .fn()
+          .mockReturnValueOnce('READY') // provider1: ready
+          .mockReturnValueOnce('NOT_READY') // provider2: not ready
+          .mockReturnValueOnce('FATAL'), // provider3: fatal
+      };
+      (multiProvider as any).statusTracker = mockStatusTracker;
+
+      multiProvider.track('purchase', context, trackingEventDetails);
+
+      expect(provider1.track).toHaveBeenCalledWith('purchase', context, trackingEventDetails);
+      expect(provider2.track).not.toHaveBeenCalled();
+      expect(provider3.track).not.toHaveBeenCalled();
+    });
+
+    it('passes correct strategy context to shouldTrackWithThisProvider', () => {
+      const provider1 = new TestProvider();
+
+      const mockStrategy = new FirstMatchStrategy();
+      mockStrategy.shouldTrackWithThisProvider = jest.fn().mockReturnValue(true);
+
+      const multiProvider = new MultiProvider([{ provider: provider1, name: 'custom-name' }], mockStrategy);
+
+      // Mock the status tracker to return a proper status
+      const mockStatusTracker = {
+        providerStatus: jest.fn().mockReturnValue('READY'),
+      };
+      (multiProvider as any).statusTracker = mockStatusTracker;
+
+      multiProvider.track('purchase', context, trackingEventDetails);
+
+      expect(mockStrategy.shouldTrackWithThisProvider).toHaveBeenCalledWith(
+        expect.objectContaining({
+          provider: provider1,
+          providerName: 'custom-name',
+          providerStatus: 'READY',
+        }),
+        context,
+        'purchase',
+        trackingEventDetails,
+      );
+    });
+  });
 });

libs/providers/multi-provider/src/lib/multi-provider.ts

@@ -14,6 +14,7 @@ import type {
   Provider,
   ProviderMetadata,
   ResolutionDetails,
+  TrackingEventDetails,
 } from '@openfeature/server-sdk';
 import {
   DefaultLogger,
@@ -311,6 +312,40 @@ export class MultiProvider implements Provider {
     ];
   }
 
+  track(trackingEventName: string, context: EvaluationContext, trackingEventDetails: TrackingEventDetails): void {
+    for (const providerEntry of this.providerEntries) {
+      if (!providerEntry.provider.track) {
+        continue;
+      }
+
+      const strategyContext = {
+        provider: providerEntry.provider,
+        providerName: providerEntry.name,
+        providerStatus: this.statusTracker.providerStatus(providerEntry.name),
+      };
+
+      if (
+        this.evaluationStrategy.shouldTrackWithThisProvider(
+          strategyContext,
+          context,
+          trackingEventName,
+          trackingEventDetails,
+        )
+      ) {
+        try {
+          providerEntry.provider.track?.(trackingEventName, context, trackingEventDetails);
+        } catch (error) {
+          // TODO: how should we handle errors?
+          // Log error but don't throw - tracking shouldn't break application flow
+          this.logger.error(
+            `Error tracking event "${trackingEventName}" with provider "${providerEntry.name}":`,
+            error,
+          );
+        }
+      }
+    }
+  }
+
   private getErrorEvaluationDetails<T extends FlagValue>(
     flagKey: string,
     defaultValue: T,