[AI-FSSDK] [FSSDK-12735] Add holdout event dispatch, local holdout guard, and null TD fallback

Author: esrakartalOpt

lib/core/decision_service/index.spec.ts

@@ -2252,7 +2252,7 @@ describe('DecisionService', () => {
           });
         });
 
-        it('should return delivery variation when excludeTargetedDeliveries is true and delivery matches', async () => {
+        it('should return delivery variation with holdout info when excludeTargetedDeliveries is true and delivery matches', async () => {
           const { decisionService } = getDecisionService();
           const datafile = getExcludeTDDatafile(true);
 
@@ -2281,10 +2281,14 @@ describe('DecisionService', () => {
             experiment: config.experimentKeyMap['delivery_1'],
             variation: config.variationIdMap['5004'],
             decisionSource: DECISION_SOURCES.ROLLOUT,
+            holdout: {
+              experiment: config.holdoutIdMap && config.holdoutIdMap['holdout_running_id'],
+              variation: config.variationIdMap['holdout_variation_running_id'],
+            },
           });
         });
 
-        it('should return holdout variation when excludeTargetedDeliveries is true but no delivery matches', async () => {
+        it('should return null decision with holdout info when excludeTargetedDeliveries is true but no delivery matches', async () => {
           const { decisionService } = getDecisionService();
           const datafile = getExcludeTDDatafile(true);
 
@@ -2307,9 +2311,13 @@ describe('DecisionService', () => {
           const variation = (await value)[0];
 
           expect(variation.result).toEqual({
-            experiment: config.holdoutIdMap && config.holdoutIdMap['holdout_running_id'],
-            variation: config.variationIdMap['holdout_variation_running_id'],
-            decisionSource: DECISION_SOURCES.HOLDOUT,
+            experiment: null,
+            variation: null,
+            decisionSource: DECISION_SOURCES.ROLLOUT,
+            holdout: {
+              experiment: config.holdoutIdMap && config.holdoutIdMap['holdout_running_id'],
+              variation: config.variationIdMap['holdout_variation_running_id'],
+            },
           });
         });
 
@@ -2338,12 +2346,14 @@ describe('DecisionService', () => {
           const value = decisionService.resolveVariationsForFeatureList('async', config, [feature], user, {}).get();
           const variation = (await value)[0];
 
-          // Should NOT get exp_1 — holdout blocks experiments even with excludeTargetedDeliveries
-          // Should get holdout since no delivery matched
           expect(variation.result).toEqual({
-            experiment: config.holdoutIdMap && config.holdoutIdMap['holdout_running_id'],
-            variation: config.variationIdMap['holdout_variation_running_id'],
-            decisionSource: DECISION_SOURCES.HOLDOUT,
+            experiment: null,
+            variation: null,
+            decisionSource: DECISION_SOURCES.ROLLOUT,
+            holdout: {
+              experiment: config.holdoutIdMap && config.holdoutIdMap['holdout_running_id'],
+              variation: config.variationIdMap['holdout_variation_running_id'],
+            },
           });
         });
       });
@@ -3252,6 +3262,34 @@ describe('DecisionService', () => {
       expect(value[0].result.decisionSource).toBe(DECISION_SOURCES.FEATURE_TEST);
       expect(value[0].result.variation?.key).toBe('variation_1');
     });
+
+    it('local holdout ignores excludeTargetedDeliveries and applies normally', async () => {
+      const datafile = makeLocalHoldoutDatafile('2001');
+      (datafile as any).localHoldouts[0].excludeTargetedDeliveries = true;
+      const config = createProjectConfig(JSON.stringify(datafile));
+      const { decisionService } = getDecisionService();
+
+      mockBucket.mockImplementation((params: BucketerParams) => {
+        if (params.experimentId === 'local_holdout_id') {
+          return { result: 'local_holdout_variation_id', reasons: [] };
+        }
+        return { result: null, reasons: [] };
+      });
+
+      const user = new OptimizelyUserContext({
+        optimizely: {} as any,
+        userId: 'user1',
+        attributes: { age: 15 },
+      });
+
+      const feature = config.featureKeyMap['flag_1'];
+      const value = await decisionService.resolveVariationsForFeatureList('async', config, [feature], user, {}).get();
+
+      // Local holdout applies normally even with excludeTargetedDeliveries set
+      expect(value[0].result.decisionSource).toBe(DECISION_SOURCES.HOLDOUT);
+      expect(value[0].result.experiment?.id).toBe('local_holdout_id');
+      expect(value[0].result.variation?.id).toBe('local_holdout_variation_id');
+    });
   });
 });
 

lib/core/decision_service/index.ts

@@ -126,6 +126,10 @@ export interface DecisionObj {
   variation: Variation | null;
   decisionSource: DecisionSource;
   cmabUuid?: string;
+  holdout?: {
+    experiment: Holdout;
+    variation: Variation;
+  };
 }
 
 interface DecisionServiceOptions {
@@ -1035,7 +1039,13 @@ export class DecisionService {
       this.logger?.debug(USER_IN_ROLLOUT, userId, feature.key);
       decideReasons.push([USER_IN_ROLLOUT, userId, feature.key]);
       return Value.of(op, {
-        result: rolloutDecisionResult,
+        result: {
+          ...rolloutDecisionResult,
+          holdout: {
+            experiment: activeHoldout!,
+            variation: activeHoldoutDecision!.variation!,
+          },
+        },
         reasons: decideReasons,
       });
     }
@@ -1044,7 +1054,15 @@ export class DecisionService {
     decideReasons.push([USER_NOT_IN_ROLLOUT, userId, feature.key]);
 
     return Value.of(op, {
-      result: activeHoldoutDecision,
+      result: {
+        experiment: null,
+        variation: null,
+        decisionSource: DECISION_SOURCES.ROLLOUT,
+        holdout: {
+          experiment: activeHoldout!,
+          variation: activeHoldoutDecision!.variation!,
+        },
+      },
       reasons: decideReasons,
     });
   }

lib/optimizely/index.spec.ts

@@ -872,6 +872,52 @@ describe('Optimizely', () => {
         }),
       });
     });
+
+    it('should dispatch separate holdout impression when decisionObj.holdout is populated', async () => {
+      const processSpy = vi.spyOn(eventProcessor, 'process');
+
+      const holdoutExperiment = projectConfig.holdouts[0];
+      const holdoutVariation = projectConfig.holdouts[0].variations[0];
+      const rolloutExperiment = projectConfig.experimentKeyMap['delivery_1'] || Object.values(projectConfig.experimentIdMap)[0];
+      const rolloutVariation = rolloutExperiment?.variations?.[0] || { id: 'test_var_id', key: 'test_var_key', variables: [] };
+
+      vi.spyOn(decisionService, 'resolveVariationsForFeatureList').mockImplementation(() => {
+        return Value.of('async', [{
+          error: false,
+          result: {
+            variation: rolloutVariation,
+            experiment: rolloutExperiment,
+            decisionSource: DECISION_SOURCES.ROLLOUT,
+            holdout: {
+              experiment: holdoutExperiment,
+              variation: holdoutVariation,
+            },
+          },
+          reasons: [],
+        }]);
+      });
+
+      const user = new OptimizelyUserContext({
+        optimizely,
+        userId: 'test_user',
+        attributes: {},
+      });
+
+      await optimizely.decideAsync(user, 'flag_1', []);
+
+      // The holdout impression is dispatched even when the main rollout impression is not
+      // (sendFlagDecisions not set). Verify at least one impression is a holdout event.
+      expect(processSpy).toHaveBeenCalled();
+
+      const holdoutEvent = processSpy.mock.calls.find(
+        (call: any) => (call[0] as ImpressionEvent).ruleType === 'holdout'
+      );
+      expect(holdoutEvent).toBeDefined();
+      const holdoutImpression = holdoutEvent![0] as ImpressionEvent;
+      expect(holdoutImpression.ruleKey).toBe('holdout_test_key');
+      expect(holdoutImpression.ruleType).toBe('holdout');
+      expect(holdoutImpression.enabled).toBe(false);
+    });
   });
 
   it('should flush eventProcessor and odpManager on flushImmediately()', async () => {

lib/optimizely/index.ts

@@ -1542,6 +1542,15 @@ export default class Optimizely extends BaseService implements Client {
         decisionEventDispatched = true;
       }
 
+      if (decisionObj.holdout && !options[OptimizelyDecideOption.DISABLE_DECISION_EVENT]) {
+        const holdoutDecisionObj: DecisionObj = {
+          experiment: decisionObj.holdout.experiment,
+          variation: decisionObj.holdout.variation,
+          decisionSource: DECISION_SOURCES.HOLDOUT,
+        };
+        this.sendImpressionEvent(holdoutDecisionObj, key, userId, false, attributes);
+      }
+
       const shouldIncludeReasons = options[OptimizelyDecideOption.INCLUDE_REASONS];
 
       let reportedReasons: string[] = [];