fix: re-fire useExperiment exposure on identity change; tighten reserved event guard

Author: Zaimwa9

event-processor.ts

@@ -113,6 +113,8 @@ export class EventProcessor {
     };
 
     start() {
+        // stop() clears any existing timer and flushes; the flush is a no-op
+        // when the buffer is empty, which is the usual case on (re)start.
         this.stop();
         if (this.flushInterval > 0) {
             this.timer = setInterval(this.flush, this.flushInterval);
@@ -125,6 +127,9 @@ export class EventProcessor {
             clearInterval(this.timer);
             this.timer = null;
         }
+        // Best-effort, fire-and-forget: this flush is not awaited, so on rapid
+        // re-init buffered events may be lost. Callers needing a guarantee
+        // (SSR/teardown) should await flushEvents() instead.
         this.flush();
     }
 

flagsmith-core.ts

@@ -961,8 +961,8 @@ const Flagsmith = class {
         metadata?: Record<string, unknown>;
     }) => {
         const processor = this.requireEventProcessor();
-        if (event.startsWith('$') && event !== FLAG_EXPOSURE_EVENT) {
-            throw new Error(`Flagsmith: event name "${event}" uses the reserved "$" prefix but is not a known system event.`);
+        if (event.startsWith('$')) {
+            throw new Error(`Flagsmith: event names starting with "$" are reserved; use trackExposureEvent to record "${FLAG_EXPOSURE_EVENT}".`);
         }
         processor.trackEvent({
             event,

react.tsx

@@ -86,7 +86,10 @@ const getRenderKey = (flagsmith: IFlagsmith, flags: string[], traits: string[] =
 
 const getExperimentRenderKey = (flagsmith: IFlagsmith | null, key: string): string => {
     const flag = flagsmith?.getAllFlags()?.[key]
-    return `${flag?.value}${flag?.enabled}`
+    const identifier = flagsmith?.getContext().identity?.identifier ?? null
+    // Identity is part of the key so that switching identity re-renders (and
+    // re-fires the exposure) even when the resolved value is unchanged.
+    return `${identifier}|${flag?.value}|${flag?.enabled}`
 }
 
 export function useFlagsmithLoading() {
@@ -227,20 +230,20 @@ export function useExperiment(featureName: string): IFlagsmithFeature | null {
     }, [flagsmith, key])
 
     const flag = (flagsmith?.getAllFlags()?.[key] as IFlagsmithFeature | undefined) ?? null
+    const identifier = flagsmith?.getContext().identity?.identifier ?? null
 
     useEffect(() => {
         if (!flagsmith?.eventsEnabled || !flag) {
             return
         }
-        const identifier = flagsmith.getContext().identity?.identifier ?? null
         const exposureKey = `${key}:${identifier}:${flag.value}`
         if (lastExposureKey.current === exposureKey) {
             return
         }
         lastExposureKey.current = exposureKey
         flagsmith.getExperimentFlag(featureName)
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [flagsmith, featureName, key, flag?.value, flag?.enabled])
+    }, [flagsmith, featureName, key, identifier, flag?.value, flag?.enabled])
 
     return flag
 }

test/events.test.ts

@@ -43,6 +43,7 @@ describe('events gate', () => {
         });
         await flagsmith.init(initConfig);
         expect(() => flagsmith.trackEvent('$custom')).toThrow(/reserved/i);
+        expect(() => flagsmith.trackEvent('$flag_exposure')).toThrow(/reserved/i);
     });
 });
 

test/react-events.test.tsx

@@ -116,6 +116,34 @@ describe('useExperiment', () => {
         expect(values).toEqual(['16', '20'])
     })
 
+    test('fires a fresh exposure when identity changes even if the value is unchanged', async () => {
+        const { flagsmith, initConfig, mockFetch } = getFlagsmith(eventsConfig({ identity: testIdentity }))
+        render(
+            <FlagsmithProvider flagsmith={flagsmith} options={initConfig}>
+                <Probe feature="font_size" />
+            </FlagsmithProvider>
+        )
+
+        await waitFor(() => {
+            expect(JSON.parse(screen.getByTestId('exp').innerHTML)?.value).toBe(16)
+        })
+
+        // A different identity that resolves the SAME font_size value (16).
+        getMockFetchWithValue(mockFetch, {
+            flags: [
+                { enabled: true, feature_state_value: 16, feature: { id: 6149, name: 'font_size' } },
+            ],
+            traits: [],
+        })
+        await flagsmith.identify('other_identity')
+
+        await waitFor(async () => {
+            await flagsmith.flushEvents()
+            expect(exposures(mockFetch)).toHaveLength(2)
+        })
+        expect(exposures(mockFetch).map((e: any) => e.identifier)).toEqual([testIdentity, 'other_identity'])
+    })
+
     test('renders the flag but fires no exposure when events are disabled', async () => {
         const { flagsmith, initConfig, mockFetch } = getFlagsmith({ identity: testIdentity })
         render(