[FSSDK-12274] ucm update + test

Author: junaed-optimizely

src/utils/UserContextManager.spec.ts

@@ -50,6 +50,7 @@ function createMockClient(opts: MockClientOptions = {}) {
   const mockUserContext = {
     fetchQualifiedSegments: vi.fn().mockResolvedValue(fetchQualifiedSegmentsResult),
     getUserId: vi.fn().mockReturnValue('test-user'),
+    qualifiedSegments: null as string[] | null,
   } as unknown as OptimizelyUserContext;
 
   const onReadyDeferred = createDeferred();
@@ -338,6 +339,181 @@ describe('UserContextManager', () => {
     });
   });
 
+  // ============================================================
+  // Scenario 3: Pre-set Qualified Segments
+  // ============================================================
+  describe('pre-set qualified segments', () => {
+    describe('qualifiedSegments + skipSegments=true', () => {
+      it('should set ctx.qualifiedSegments, fire onUserContextReady once, no background fetch', async () => {
+        const { client, mockUserContext } = createMockClient({
+          hasOdpManager: true,
+          hasVuidManager: false,
+        });
+        const config = createManagerConfig(client, { skipSegments: true });
+        const manager = new UserContextManager(config);
+
+        manager.createUserContext({ id: 'user-1' }, ['seg-a', 'seg-b']);
+
+        expect(client.createUserContext).toHaveBeenCalledWith('user-1', undefined);
+        expect(mockUserContext.qualifiedSegments).toEqual(['seg-a', 'seg-b']);
+        expect(config.onUserContextReady).toHaveBeenCalledTimes(1);
+        expect(config.onUserContextReady).toHaveBeenCalledWith(mockUserContext);
+        expect(mockUserContext.fetchQualifiedSegments).not.toHaveBeenCalled();
+        expect(client.onReady).not.toHaveBeenCalled();
+
+        manager.dispose();
+      });
+    });
+
+    describe('qualifiedSegments + skipSegments=false + ODP + segments match', () => {
+      it('should callback with pre-set segments immediately than skip second callback when background fetch returns matching segments', async () => {
+        const { client, mockUserContext, onReadyDeferred } = createMockClient({
+          hasOdpManager: true,
+          hasVuidManager: false,
+          isOdpIntegrated: true,
+        });
+        // fetchQualifiedSegments will keep the same segments (simulate match)
+        (mockUserContext.fetchQualifiedSegments as ReturnType<typeof vi.fn>).mockImplementation(async () => {
+          mockUserContext.qualifiedSegments = ['seg-a', 'seg-b'];
+          return true;
+        });
+        const config = createManagerConfig(client, { skipSegments: false });
+        const manager = new UserContextManager(config);
+
+        manager.createUserContext({ id: 'user-1' }, ['seg-a', 'seg-b']);
+
+        // Immediate callback with pre-set segments
+        expect(mockUserContext.qualifiedSegments).toEqual(['seg-a', 'seg-b']);
+        expect(config.onUserContextReady).toHaveBeenCalledTimes(1);
+
+        // Background fetch waiting on onReady
+        expect(client.onReady).toHaveBeenCalled();
+
+        onReadyDeferred.resolve(undefined);
+        await flushPromises();
+
+        // Background fetch returned matching segments — no second callback
+        expect(mockUserContext.fetchQualifiedSegments).toHaveBeenCalled();
+        expect(config.onUserContextReady).toHaveBeenCalledTimes(1);
+
+        manager.dispose();
+      });
+    });
+
+    describe('qualifiedSegments + skipSegments=false + ODP + segments differ', () => {
+      it('should callback with pre-set segments immediately then callback again when background fetch returns different segments', async () => {
+        const { client, mockUserContext, onReadyDeferred } = createMockClient({
+          hasOdpManager: true,
+          hasVuidManager: false,
+          isOdpIntegrated: true,
+        });
+        // fetchQualifiedSegments returns different segments
+        (mockUserContext.fetchQualifiedSegments as ReturnType<typeof vi.fn>).mockImplementation(async () => {
+          mockUserContext.qualifiedSegments = ['seg-a', 'seg-c'];
+          return true;
+        });
+        const config = createManagerConfig(client, { skipSegments: false });
+        const manager = new UserContextManager(config);
+
+        manager.createUserContext({ id: 'user-1' }, ['seg-a', 'seg-b']);
+
+        // Immediate callback with pre-set segments
+        expect(config.onUserContextReady).toHaveBeenCalledTimes(1);
+
+        onReadyDeferred.resolve(undefined);
+        await flushPromises();
+
+        // Background fetch returned different segments — second callback fires
+        expect(mockUserContext.fetchQualifiedSegments).toHaveBeenCalled();
+        expect(config.onUserContextReady).toHaveBeenCalledTimes(2);
+
+        manager.dispose();
+      });
+    });
+
+    describe('qualifiedSegments + skipSegments=false + ODP not integrated', () => {
+      it('should callback with pre-set segments immediately and skip background fetch when ODP is not integrated', async () => {
+        const { client, mockUserContext, onReadyDeferred } = createMockClient({
+          hasOdpManager: true,
+          hasVuidManager: false,
+          isOdpIntegrated: false,
+        });
+        const config = createManagerConfig(client, { skipSegments: false });
+        const manager = new UserContextManager(config);
+
+        manager.createUserContext({ id: 'user-1' }, ['seg-a']);
+
+        // Immediate callback with pre-set segments
+        expect(mockUserContext.qualifiedSegments).toEqual(['seg-a']);
+        expect(config.onUserContextReady).toHaveBeenCalledTimes(1);
+
+        onReadyDeferred.resolve(undefined);
+        await flushPromises();
+
+        // ODP not integrated — no background fetch, no second callback
+        expect(client.isOdpIntegrated).toHaveBeenCalled();
+        expect(mockUserContext.fetchQualifiedSegments).not.toHaveBeenCalled();
+        expect(config.onUserContextReady).toHaveBeenCalledTimes(1);
+
+        manager.dispose();
+      });
+    });
+
+    describe('qualifiedSegments + skipSegments=false + no ODP manager', () => {
+      it('should callback with pre-set segments immediately and skip background fetch without ODP manager', async () => {
+        const { client, mockUserContext } = createMockClient({
+          hasOdpManager: false,
+          hasVuidManager: false,
+        });
+        const config = createManagerConfig(client, { skipSegments: false });
+        const manager = new UserContextManager(config);
+
+        manager.createUserContext({ id: 'user-1' }, ['seg-a', 'seg-b']);
+        await flushPromises();
+
+        // Immediate callback with pre-set segments only — no ODP manager, no background fetch
+        expect(mockUserContext.qualifiedSegments).toEqual(['seg-a', 'seg-b']);
+        expect(config.onUserContextReady).toHaveBeenCalledTimes(1);
+        expect(client.onReady).not.toHaveBeenCalled();
+        expect(mockUserContext.fetchQualifiedSegments).not.toHaveBeenCalled();
+
+        manager.dispose();
+      });
+    });
+
+    describe('qualifiedSegments=[] empty array', () => {
+      it('should treat empty array as explicit zero segments, callback immediately, then callback again after background fetch', async () => {
+        const { client, mockUserContext, onReadyDeferred } = createMockClient({
+          hasOdpManager: true,
+          hasVuidManager: false,
+          isOdpIntegrated: true,
+        });
+        // fetchQualifiedSegments returns segments (differ from empty)
+        (mockUserContext.fetchQualifiedSegments as ReturnType<typeof vi.fn>).mockImplementation(async () => {
+          mockUserContext.qualifiedSegments = ['seg-x'];
+          return true;
+        });
+        const config = createManagerConfig(client, { skipSegments: false });
+        const manager = new UserContextManager(config);
+
+        manager.createUserContext({ id: 'user-1' }, []); // empty array is truthy in JS
+
+        // Immediate callback with empty segments
+        expect(mockUserContext.qualifiedSegments).toEqual([]);
+        expect(config.onUserContextReady).toHaveBeenCalledTimes(1);
+
+        onReadyDeferred.resolve(undefined);
+        await flushPromises();
+
+        // Background fetch returned different segments — second callback fires
+        expect(mockUserContext.fetchQualifiedSegments).toHaveBeenCalled();
+        expect(config.onUserContextReady).toHaveBeenCalledTimes(2);
+
+        manager.dispose();
+      });
+    });
+  });
+
   // ============================================================
   // Race conditions
   // ============================================================
@@ -411,6 +587,54 @@ describe('UserContextManager', () => {
 
       manager.dispose();
     });
+
+    it('should suppress background fetch callback of stale request when user changes after pre-set segments callback', async () => {
+      const segmentDeferred = createDeferred<boolean>();
+      const { client, mockUserContext, onReadyDeferred } = createMockClient({
+        hasOdpManager: true,
+        hasVuidManager: false,
+        isOdpIntegrated: true,
+      });
+      (mockUserContext.fetchQualifiedSegments as ReturnType<typeof vi.fn>).mockReturnValue(segmentDeferred.promise);
+
+      const config = createManagerConfig(client, { skipSegments: false });
+      const manager = new UserContextManager(config);
+
+      // First call with qualifiedSegments — pre-set segments callback fires immediately
+      manager.createUserContext({ id: 'user-1' }, ['seg-a']);
+
+      // Pre-set segments callback of first request fired
+      expect(config.onUserContextReady).toHaveBeenCalledTimes(1);
+
+      // Resolve onReady so background fetch starts
+      onReadyDeferred.resolve(undefined);
+      await flushPromises();
+
+      expect(mockUserContext.fetchQualifiedSegments).toHaveBeenCalled();
+
+      // New user call invalidates the first request
+      const newCtx = {
+        getUserId: vi.fn().mockReturnValue('user-2'),
+        qualifiedSegments: null as string[] | null,
+        fetchQualifiedSegments: vi.fn().mockResolvedValue(true),
+      } as unknown as OptimizelyUserContext;
+      (client.createUserContext as ReturnType<typeof vi.fn>).mockReturnValue(newCtx);
+      manager.createUserContext({ id: 'user-2' });
+      await flushPromises();
+
+      expect(config.onUserContextReady).toHaveBeenCalledTimes(2);
+
+      // First request's background fetch completes — callback should be suppressed (stale)
+      (mockUserContext as unknown as { qualifiedSegments: string[] }).qualifiedSegments = ['seg-a', 'seg-new'];
+      segmentDeferred.resolve(true);
+
+      await flushPromises();
+
+      // Still only 2 calls — background fetch callback of stale request was suppressed
+      expect(config.onUserContextReady).toHaveBeenCalledTimes(2);
+
+      manager.dispose();
+    });
   });
 
   // ============================================================

src/utils/UserContextManager.ts

@@ -55,11 +55,14 @@ export class UserContextManager {
   /**
    * Creates a user context, optionally waiting for VUID resolution and
    * fetching ODP segments. Only the latest call's callbacks will fire.
+   *
+   * @param user - Optional user info (id and attributes)
+   * @param qualifiedSegments - Optional pre-fetched segments. When provided,
    */
-  createUserContext(user?: UserInfo): void {
+  createUserContext(user?: UserInfo, qualifiedSegments?: string[]): void {
     const requestId = ++this.requestId;
 
-    this.resolveUserContext(requestId, user).catch((error: unknown) => {
+    this.resolveUserContext(requestId, user, qualifiedSegments).catch((error: unknown) => {
       if (this.isStale(requestId)) return;
       this.onError(error instanceof Error ? error : new Error(String(error)));
     });
@@ -72,14 +75,44 @@ export class UserContextManager {
     this.disposed = true;
   }
 
-  private async resolveUserContext(requestId: number, user?: UserInfo): Promise<void> {
+  private async resolveUserContext(requestId: number, user?: UserInfo, qualifiedSegments?: string[]): Promise<void> {
     if (!user?.id && this.meta.hasVuidManager) {
       await this.client.onReady();
       if (this.isStale(requestId)) return;
     }
 
     const ctx = this.client.createUserContext(user?.id, user?.attributes);
 
+    if (qualifiedSegments) {
+      ctx.qualifiedSegments = qualifiedSegments;
+
+      this.onUserContextReady(ctx); // immediate callback for sync decision with pre-set segments
+
+      if (this.skipSegments) return;
+
+      // Background fetch — only when ODP manager exists
+      if (this.meta.hasOdpManager) {
+        await this.client.onReady();
+
+        if (this.isStale(requestId)) return;
+
+        if (this.client.isOdpIntegrated()) {
+          const snapshot = [...qualifiedSegments];
+
+          await ctx.fetchQualifiedSegments();
+
+          if (this.isStale(requestId)) return;
+
+          // update only if different
+          if (!this.segmentsEqual(snapshot, ctx.qualifiedSegments)) {
+            this.onUserContextReady(ctx);
+          }
+        }
+      }
+      return;
+    }
+
+    // Step 3: Original path (no qualifiedSegments)
     if (!this.skipSegments && this.meta.hasOdpManager) {
       await this.client.onReady();
       if (this.isStale(requestId)) return;
@@ -93,6 +126,15 @@ export class UserContextManager {
     this.onUserContextReady(ctx);
   }
 
+  private segmentsEqual(a: string[] | null, b: string[] | null): boolean {
+    if (a === b) return true;
+    if (!a || !b) return false;
+    if (a.length !== b.length) return false;
+    const sortedA = [...a].sort();
+    const sortedB = [...b].sort();
+    return sortedA.every((val, i) => val === sortedB[i]);
+  }
+
   private isStale(requestId: number): boolean {
     return this.disposed || requestId !== this.requestId;
   }