@volley/recognition-client-sdk-node22 0.1.424

package/src/simplified-vgf-recognition-client.integration.spec.ts

@@ -0,0 +1,718 @@
+/**
+ * Integration tests for SimplifiedVGFRecognitionClient state transitions.
+ *
+ * These tests verify complete recognition flows involving multiple method calls
+ * and state transitions, including:
+ * - Normal recognition flow (sendAudio → transcript → stopRecording → final)
+ * - Early termination with synthetic finalization
+ * - Abnormal stop (cancel/abandon)
+ * - Terminal status protection (duplicate suppression)
+ */
+
+import {
+  SimplifiedVGFRecognitionClient,
+  SimplifiedVGFClientConfig
+} from './simplified-vgf-recognition-client.js';
+import { RealTimeTwoWayWebSocketRecognitionClient } from './recognition-client.js';
+import {
+  RecognitionState,
+  TranscriptionStatus,
+  RecordingStatus
+} from './vgf-recognition-state.js';
+import { ClientState } from './recognition-client.types.js';
+import { AudioEncoding } from '@recog/shared-types';
+
+// Track the current mock state - can be changed per test
+let mockClientState: ClientState = ClientState.READY;
+
+// Mock the underlying client
+jest.mock('./recognition-client.js', () => {
+  const mockClient = {
+    connect: jest.fn().mockResolvedValue(undefined),
+    sendAudio: jest.fn(),
+    stopRecording: jest.fn().mockResolvedValue(undefined),
+    stopAbnormally: jest.fn(),
+    getAudioUtteranceId: jest.fn().mockReturnValue('mock-uuid'),
+    getUrl: jest.fn().mockReturnValue('wss://mock-url'),
+    getState: jest.fn().mockImplementation(() => mockClientState),
+    isConnected: jest.fn().mockReturnValue(true),
+    isConnecting: jest.fn().mockReturnValue(false),
+    isStopping: jest.fn().mockReturnValue(false),
+    isTranscriptionFinished: jest.fn().mockReturnValue(false),
+    isBufferOverflowing: jest.fn().mockReturnValue(false)
+  };
+
+  return {
+    RealTimeTwoWayWebSocketRecognitionClient: jest.fn().mockImplementation(() => mockClient)
+  };
+});
+
+describe('SimplifiedVGFRecognitionClient Integration - State Transitions', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    // Reset to default READY state
+    mockClientState = ClientState.READY;
+  });
+
+  describe('Normal Recognition Flow', () => {
+    it('should follow correct state transitions for complete normal flow', async () => {
+      let stateChangeCounter = 0;
+      const stateHistory: RecognitionState[] = [];
+
+      const trackingCallback = jest.fn((state: RecognitionState) => {
+        stateChangeCounter++;
+        stateHistory.push({ ...state });
+      });
+
+      const client = new SimplifiedVGFRecognitionClient({
+        asrRequestConfig: {
+          provider: 'deepgram',
+          language: 'en',
+          sampleRate: 16000,
+          encoding: AudioEncoding.LINEAR16
+        },
+        onStateChange: trackingCallback
+      });
+
+      // Capture the onTranscript callback
+      const constructorCalls = (RealTimeTwoWayWebSocketRecognitionClient as jest.MockedClass<typeof RealTimeTwoWayWebSocketRecognitionClient>).mock.calls;
+      const latestConfig = constructorCalls[constructorCalls.length - 1]?.[0];
+      const onTranscriptCallback = latestConfig?.onTranscript;
+      if (!onTranscriptCallback) throw new Error('onTranscript callback not found');
+
+      const clientUuid = client.getVGFState().audioUtteranceId;
+
+      // Step 1: Initial state - verify starting point
+      expect(stateChangeCounter).toBe(0);
+      let currentState = client.getVGFState();
+      expect(currentState.audioUtteranceId).toBe(clientUuid);
+      expect(currentState.startRecordingStatus).toBe(RecordingStatus.READY);
+      expect(currentState.transcriptionStatus).toBe(TranscriptionStatus.NOT_STARTED);
+      expect(currentState.pendingTranscript).toBe('');
+      expect(currentState.finalTranscript).toBeUndefined();
+
+      // Step 2: Send first audio chunk - triggers RECORDING state
+      client.sendAudio(Buffer.from([1, 2, 3, 4]));
+
+      expect(stateChangeCounter).toBe(1);
+      currentState = client.getVGFState();
+      expect(currentState.audioUtteranceId).toBe(clientUuid);
+      expect(currentState.startRecordingStatus).toBe(RecordingStatus.RECORDING);
+      expect(currentState.startRecordingTimestamp).toBeDefined();
+      expect(currentState.transcriptionStatus).toBe(TranscriptionStatus.NOT_STARTED);
+
+      // Step 3: Server sends pending transcript - triggers IN_PROGRESS
+      onTranscriptCallback({
+        type: 'Transcription',
+        audioUtteranceId: clientUuid,
+        pendingTranscript: 'hello',
+        pendingTranscriptConfidence: 0.7,
+        is_finished: false
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any);
+
+      expect(stateChangeCounter).toBe(2);
+      currentState = client.getVGFState();
+      expect(currentState.audioUtteranceId).toBe(clientUuid);
+      expect(currentState.startRecordingStatus).toBe(RecordingStatus.RECORDING);
+      expect(currentState.transcriptionStatus).toBe(TranscriptionStatus.IN_PROGRESS);
+      expect(currentState.pendingTranscript).toBe('hello');
+      expect(currentState.pendingConfidence).toBe(0.7);
+      expect(currentState.finalTranscript).toBeUndefined();
+
+      // Step 4: Server sends more pending transcript
+      onTranscriptCallback({
+        type: 'Transcription',
+        audioUtteranceId: clientUuid,
+        pendingTranscript: 'hello world',
+        pendingTranscriptConfidence: 0.8,
+        is_finished: false
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any);
+
+      expect(stateChangeCounter).toBe(3);
+      currentState = client.getVGFState();
+      expect(currentState.audioUtteranceId).toBe(clientUuid);
+      expect(currentState.transcriptionStatus).toBe(TranscriptionStatus.IN_PROGRESS);
+      expect(currentState.pendingTranscript).toBe('hello world');
+      expect(currentState.pendingConfidence).toBe(0.8);
+
+      // Step 5: User calls stopRecording - triggers FINISHED recording status
+      await client.stopRecording();
+
+      expect(stateChangeCounter).toBe(4);
+      currentState = client.getVGFState();
+      expect(currentState.audioUtteranceId).toBe(clientUuid);
+      expect(currentState.startRecordingStatus).toBe(RecordingStatus.FINISHED);
+      expect(currentState.finalRecordingTimestamp).toBeDefined();
+      // Transcription should still be IN_PROGRESS (waiting for server final)
+      expect(currentState.transcriptionStatus).toBe(TranscriptionStatus.IN_PROGRESS);
+
+      // Step 6: Server sends final transcript - triggers FINALIZED
+      onTranscriptCallback({
+        type: 'Transcription',
+        audioUtteranceId: clientUuid,
+        finalTranscript: 'hello world',
+        finalTranscriptConfidence: 0.95,
+        is_finished: true
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any);
+
+      expect(stateChangeCounter).toBe(5);
+      currentState = client.getVGFState();
+      expect(currentState.audioUtteranceId).toBe(clientUuid);
+      expect(currentState.startRecordingStatus).toBe(RecordingStatus.FINISHED);
+      expect(currentState.transcriptionStatus).toBe(TranscriptionStatus.FINALIZED);
+      expect(currentState.finalTranscript).toBe('hello world');
+      expect(currentState.finalConfidence).toBe(0.95);
+      expect(currentState.pendingTranscript).toBe('');
+      expect(currentState.pendingConfidence).toBeUndefined();
+      expect(currentState.finalTranscriptionTimestamp).toBeDefined();
+
+      // Verify total callback count
+      expect(trackingCallback).toHaveBeenCalledTimes(5);
+    });
+
+    it('should not emit synthetic finalization if transcript was received before stopRecording', async () => {
+      let stateChangeCounter = 0;
+
+      const trackingCallback = jest.fn((state: RecognitionState) => {
+        stateChangeCounter++;
+      });
+
+      const client = new SimplifiedVGFRecognitionClient({
+        asrRequestConfig: {
+          provider: 'deepgram',
+          language: 'en',
+          sampleRate: 16000,
+          encoding: AudioEncoding.LINEAR16
+        },
+        onStateChange: trackingCallback
+      });
+
+      // Capture the onTranscript callback
+      const constructorCalls = (RealTimeTwoWayWebSocketRecognitionClient as jest.MockedClass<typeof RealTimeTwoWayWebSocketRecognitionClient>).mock.calls;
+      const latestConfig = constructorCalls[constructorCalls.length - 1]?.[0];
+      const onTranscriptCallback = latestConfig?.onTranscript;
+      if (!onTranscriptCallback) throw new Error('onTranscript callback not found');
+
+      const clientUuid = client.getVGFState().audioUtteranceId;
+
+      // Step 1: Send audio
+      client.sendAudio(Buffer.from([1, 2, 3, 4]));
+      expect(stateChangeCounter).toBe(1);
+
+      // Step 2: Server sends a pending transcript (transcriptionStatus -> IN_PROGRESS)
+      onTranscriptCallback({
+        type: 'Transcription',
+        audioUtteranceId: clientUuid,
+        pendingTranscript: 'hello',
+        pendingTranscriptConfidence: 0.7,
+        is_finished: false
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any);
+      expect(stateChangeCounter).toBe(2);
+
+      // Step 3: User calls stopRecording - should NOT emit synthetic finalization
+      // because transcriptionStatus is IN_PROGRESS (not NOT_STARTED)
+      await client.stopRecording();
+
+      expect(stateChangeCounter).toBe(3); // Only stopRecording state change, no synthetic finalization
+      let currentState = client.getVGFState();
+      expect(currentState.startRecordingStatus).toBe(RecordingStatus.FINISHED);
+      expect(currentState.transcriptionStatus).toBe(TranscriptionStatus.IN_PROGRESS); // Still waiting for final
+
+      // Step 4: Server sends final transcript after stop
+      onTranscriptCallback({
+        type: 'Transcription',
+        audioUtteranceId: clientUuid,
+        finalTranscript: 'hello world',
+        finalTranscriptConfidence: 0.95,
+        is_finished: true
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any);
+
+      expect(stateChangeCounter).toBe(4);
+      currentState = client.getVGFState();
+      expect(currentState.transcriptionStatus).toBe(TranscriptionStatus.FINALIZED);
+      expect(currentState.finalTranscript).toBe('hello world');
+      expect(currentState.finalConfidence).toBe(0.95);
+
+      expect(trackingCallback).toHaveBeenCalledTimes(4);
+    });
+  });
+
+  describe('Early Termination with Synthetic Finalization', () => {
+    it('should handle stopRecording without ever sending audio', async () => {
+      // Mock client in CONNECTED state (not yet READY) - synthetic finalization should trigger
+      mockClientState = ClientState.CONNECTED;
+
+      let stateChangeCounter = 0;
+
+      const trackingCallback = jest.fn((state: RecognitionState) => {
+        stateChangeCounter++;
+      });
+
+      const client = new SimplifiedVGFRecognitionClient({
+        asrRequestConfig: {
+          provider: 'deepgram',
+          language: 'en',
+          sampleRate: 16000,
+          encoding: AudioEncoding.LINEAR16
+        },
+        onStateChange: trackingCallback
+      });
+
+      const clientUuid = client.getVGFState().audioUtteranceId;
+
+      // Step 1: Initial state
+      expect(stateChangeCounter).toBe(0);
+      let currentState = client.getVGFState();
+      expect(currentState.audioUtteranceId).toBe(clientUuid);
+      expect(currentState.startRecordingStatus).toBe(RecordingStatus.READY);
+      expect(currentState.transcriptionStatus).toBe(TranscriptionStatus.NOT_STARTED);
+
+      // Step 2: User calls stopRecording WITHOUT ever sending audio
+      // Since client is in CONNECTED state (not READY), SDK should emit synthetic finalization
+      await client.stopRecording();
+
+      // Should have 2 callbacks: stopRecording (FINISHED) + synthetic finalization (FINALIZED)
+      expect(stateChangeCounter).toBe(2);
+      currentState = client.getVGFState();
+      expect(currentState.audioUtteranceId).toBe(clientUuid);
+      expect(currentState.startRecordingStatus).toBe(RecordingStatus.FINISHED);
+      expect(currentState.finalRecordingTimestamp).toBeDefined();
+      expect(currentState.transcriptionStatus).toBe(TranscriptionStatus.FINALIZED);
+      expect(currentState.finalTranscript).toBe('');
+      expect(currentState.finalTranscriptionTimestamp).toBeDefined();
+
+      // Verify total callback count
+      expect(trackingCallback).toHaveBeenCalledTimes(2);
+    });
+
+    it('should emit synthetic finalization and suppress late server transcripts', async () => {
+      // Mock client in CONNECTED state (not yet READY) - synthetic finalization should trigger
+      mockClientState = ClientState.CONNECTED;
+
+      let stateChangeCounter = 0;
+      const stateHistory: RecognitionState[] = [];
+      const loggerCalls: Array<{ level: string; message: string }> = [];
+
+      const trackingCallback = jest.fn((state: RecognitionState) => {
+        stateChangeCounter++;
+        stateHistory.push({ ...state });
+      });
+
+      const logger = jest.fn((level: string, message: string) => {
+        loggerCalls.push({ level, message });
+      });
+
+      const client = new SimplifiedVGFRecognitionClient({
+        asrRequestConfig: {
+          provider: 'deepgram',
+          language: 'en',
+          sampleRate: 16000,
+          encoding: AudioEncoding.LINEAR16
+        },
+        onStateChange: trackingCallback,
+        logger
+      });
+
+      // Capture the onTranscript callback
+      const constructorCalls = (RealTimeTwoWayWebSocketRecognitionClient as jest.MockedClass<typeof RealTimeTwoWayWebSocketRecognitionClient>).mock.calls;
+      const latestConfig = constructorCalls[constructorCalls.length - 1]?.[0];
+      const onTranscriptCallback = latestConfig?.onTranscript;
+      if (!onTranscriptCallback) throw new Error('onTranscript callback not found');
+
+      const clientUuid = client.getVGFState().audioUtteranceId;
+
+      // Step 1: Send audio
+      client.sendAudio(Buffer.from([1, 2, 3, 4]));
+      expect(stateChangeCounter).toBe(1);
+
+      // Step 2: User calls stopRecording BEFORE any transcript received
+      // Since client is in CONNECTED state (not READY), SDK should emit synthetic finalization
+      await client.stopRecording();
+
+      // Should have 3 callbacks: sendAudio, stopRecording (FINISHED), synthetic finalization (FINALIZED)
+      expect(stateChangeCounter).toBe(3);
+      const currentState = client.getVGFState();
+      expect(currentState.audioUtteranceId).toBe(clientUuid);
+      expect(currentState.startRecordingStatus).toBe(RecordingStatus.FINISHED);
+      expect(currentState.transcriptionStatus).toBe(TranscriptionStatus.FINALIZED);
+      expect(currentState.finalTranscript).toBe('');
+      expect(currentState.finalTranscriptionTimestamp).toBeDefined();
+
+      // Verify state history: RECORDING -> FINISHED -> FINALIZED
+      expect(stateHistory[0]!.startRecordingStatus).toBe(RecordingStatus.RECORDING);
+      expect(stateHistory[1]!.startRecordingStatus).toBe(RecordingStatus.FINISHED);
+      expect(stateHistory[1]!.transcriptionStatus).toBe(TranscriptionStatus.NOT_STARTED);
+      expect(stateHistory[2]!.transcriptionStatus).toBe(TranscriptionStatus.FINALIZED);
+
+      // Game can now proceed - state is terminal (FINALIZED)
+      expect(trackingCallback).toHaveBeenCalledTimes(3);
+
+      // Step 3: Late server transcript arrives - should be SUPPRESSED
+      onTranscriptCallback({
+        type: 'Transcription',
+        audioUtteranceId: clientUuid,
+        finalTranscript: 'late server response',
+        finalTranscriptConfidence: 0.99,
+        is_finished: true
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any);
+
+      // Callback should NOT be called again
+      expect(stateChangeCounter).toBe(3);
+      expect(trackingCallback).toHaveBeenCalledTimes(3);
+
+      // Local state IS updated with late transcript, but callback was not called
+      const finalState = client.getVGFState();
+      expect(finalState.finalTranscript).toBe('late server response');
+
+      // Log should indicate suppression
+      const suppressionLog = loggerCalls.find(log =>
+        log.level === 'info' && log.message.includes('Duplicate terminal status suppressed')
+      );
+      expect(suppressionLog).toBeDefined();
+    });
+  });
+
+  describe('Abnormal Stop (Cancel/Abandon)', () => {
+    it('should emit only ONE ABORTED status and suppress late transcripts', () => {
+      let stateChangeCounter = 0;
+      const stateHistory: RecognitionState[] = [];
+      const loggerCalls: Array<{ level: string; message: string }> = [];
+
+      const trackingCallback = jest.fn((state: RecognitionState) => {
+        stateChangeCounter++;
+        stateHistory.push({ ...state });
+      });
+
+      const logger = jest.fn((level: string, message: string) => {
+        loggerCalls.push({ level, message });
+      });
+
+      const client = new SimplifiedVGFRecognitionClient({
+        asrRequestConfig: {
+          provider: 'deepgram',
+          language: 'en',
+          sampleRate: 16000,
+          encoding: AudioEncoding.LINEAR16
+        },
+        onStateChange: trackingCallback,
+        logger
+      });
+
+      // Capture the onTranscript callback
+      const constructorCalls = (RealTimeTwoWayWebSocketRecognitionClient as jest.MockedClass<typeof RealTimeTwoWayWebSocketRecognitionClient>).mock.calls;
+      const latestConfig = constructorCalls[constructorCalls.length - 1]?.[0];
+      const onTranscriptCallback = latestConfig?.onTranscript;
+      if (!onTranscriptCallback) throw new Error('onTranscript callback not found');
+
+      const clientUuid = client.getVGFState().audioUtteranceId;
+
+      // Step 1: Send audio
+      client.sendAudio(Buffer.from([1, 2, 3, 4]));
+      expect(stateChangeCounter).toBe(1);
+      expect(stateHistory[0]!.startRecordingStatus).toBe(RecordingStatus.RECORDING);
+
+      // Step 2: Receive a pending transcript
+      onTranscriptCallback({
+        type: 'Transcription',
+        audioUtteranceId: clientUuid,
+        pendingTranscript: 'partial text',
+        pendingTranscriptConfidence: 0.7,
+        is_finished: false
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any);
+
+      expect(stateChangeCounter).toBe(2);
+      expect(stateHistory[1]!.transcriptionStatus).toBe(TranscriptionStatus.IN_PROGRESS);
+      expect(stateHistory[1]!.pendingTranscript).toBe('partial text');
+
+      // Step 3: User calls stopAbnormally (cancel/abandon session)
+      client.stopAbnormally();
+
+      // Should have 3 callbacks: sendAudio, pending transcript, stopAbnormally (ABORTED)
+      expect(stateChangeCounter).toBe(3);
+      expect(stateHistory[2]!.transcriptionStatus).toBe(TranscriptionStatus.ABORTED);
+      expect(stateHistory[2]!.startRecordingStatus).toBe(RecordingStatus.FINISHED);
+
+      // Step 4: Late server transcript arrives - should be SUPPRESSED
+      onTranscriptCallback({
+        type: 'Transcription',
+        audioUtteranceId: clientUuid,
+        finalTranscript: 'late server response',
+        finalTranscriptConfidence: 0.99,
+        is_finished: true
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any);
+
+      // Callback should NOT be called again
+      expect(stateChangeCounter).toBe(3);
+      expect(trackingCallback).toHaveBeenCalledTimes(3);
+
+      // Local state IS updated (late transcript overwrites ABORTED), but callback was not called
+      const finalState = client.getVGFState();
+      expect(finalState.transcriptionStatus).toBe(TranscriptionStatus.FINALIZED);
+      expect(finalState.finalTranscript).toBe('late server response');
+
+      // Log should indicate suppression
+      const suppressionLog = loggerCalls.find(log =>
+        log.level === 'info' && log.message.includes('Duplicate terminal status suppressed')
+      );
+      expect(suppressionLog).toBeDefined();
+
+      // Step 5: Calling stopAbnormally again should not emit another callback
+      client.stopAbnormally();
+      expect(stateChangeCounter).toBe(3);
+      expect(trackingCallback).toHaveBeenCalledTimes(3);
+    });
+  });
+
+  describe('Error Status Protection', () => {
+    it('should emit only ONE ERROR status and suppress late errors and transcripts', () => {
+      let stateChangeCounter = 0;
+      const stateHistory: RecognitionState[] = [];
+      const loggerCalls: Array<{ level: string; message: string }> = [];
+
+      const trackingCallback = jest.fn((state: RecognitionState) => {
+        stateChangeCounter++;
+        stateHistory.push({ ...state });
+      });
+
+      const logger = jest.fn((level: string, message: string) => {
+        loggerCalls.push({ level, message });
+      });
+
+      const client = new SimplifiedVGFRecognitionClient({
+        asrRequestConfig: {
+          provider: 'deepgram',
+          language: 'en',
+          sampleRate: 16000,
+          encoding: AudioEncoding.LINEAR16
+        },
+        onStateChange: trackingCallback,
+        logger
+      });
+
+      // Capture the callbacks
+      const constructorCalls = (RealTimeTwoWayWebSocketRecognitionClient as jest.MockedClass<typeof RealTimeTwoWayWebSocketRecognitionClient>).mock.calls;
+      const latestConfig = constructorCalls[constructorCalls.length - 1]?.[0];
+      const onTranscriptCallback = latestConfig?.onTranscript;
+      const onErrorCallback = latestConfig?.onError;
+      if (!onTranscriptCallback) throw new Error('onTranscript callback not found');
+      if (!onErrorCallback) throw new Error('onError callback not found');
+
+      const clientUuid = client.getVGFState().audioUtteranceId;
+
+      // Step 1: Send audio
+      client.sendAudio(Buffer.from([1, 2, 3, 4]));
+      expect(stateChangeCounter).toBe(1);
+      expect(stateHistory[0]!.startRecordingStatus).toBe(RecordingStatus.RECORDING);
+
+      // Step 2: Receive a pending transcript
+      onTranscriptCallback({
+        type: 'Transcription',
+        audioUtteranceId: clientUuid,
+        pendingTranscript: 'partial text',
+        pendingTranscriptConfidence: 0.7,
+        is_finished: false
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any);
+
+      expect(stateChangeCounter).toBe(2);
+      expect(stateHistory[1]!.transcriptionStatus).toBe(TranscriptionStatus.IN_PROGRESS);
+
+      // Step 3: Error occurs (e.g., provider error, timeout)
+      onErrorCallback({
+        audioUtteranceId: clientUuid,
+        message: 'Provider connection failed'
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any);
+
+      // Should have 3 callbacks: sendAudio, pending transcript, error (ERROR)
+      expect(stateChangeCounter).toBe(3);
+      expect(stateHistory[2]!.transcriptionStatus).toBe(TranscriptionStatus.ERROR);
+      expect(stateHistory[2]!.startRecordingStatus).toBe(RecordingStatus.FINISHED);
+
+      // Step 4: Another error arrives - should be SUPPRESSED
+      onErrorCallback({
+        audioUtteranceId: clientUuid,
+        message: 'Second error message'
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any);
+
+      // Callback should NOT be called again
+      expect(stateChangeCounter).toBe(3);
+      expect(trackingCallback).toHaveBeenCalledTimes(3);
+
+      // Step 5: Late transcript arrives - should also be SUPPRESSED
+      onTranscriptCallback({
+        type: 'Transcription',
+        audioUtteranceId: clientUuid,
+        finalTranscript: 'late server response',
+        finalTranscriptConfidence: 0.99,
+        is_finished: true
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any);
+
+      // Callback should still NOT be called again
+      expect(stateChangeCounter).toBe(3);
+      expect(trackingCallback).toHaveBeenCalledTimes(3);
+
+      // Local state IS updated (late transcript overwrites), but callback was not called
+      const finalState = client.getVGFState();
+      expect(finalState.transcriptionStatus).toBe(TranscriptionStatus.FINALIZED);
+      expect(finalState.finalTranscript).toBe('late server response');
+
+      // Log should indicate suppression for the late transcript
+      const suppressionLog = loggerCalls.find(log =>
+        log.level === 'info' && log.message.includes('Duplicate terminal status suppressed')
+      );
+      expect(suppressionLog).toBeDefined();
+    });
+  });
+
+  describe('Terminal Status Protection (Duplicate Suppression)', () => {
+    it('should emit only ONE terminal status per session', async () => {
+      let stateChangeCounter = 0;
+      const stateHistory: RecognitionState[] = [];
+      const loggerCalls: Array<{ level: string; message: string }> = [];
+
+      const trackingCallback = jest.fn((state: RecognitionState) => {
+        stateChangeCounter++;
+        stateHistory.push({ ...state });
+      });
+
+      const logger = jest.fn((level: string, message: string) => {
+        loggerCalls.push({ level, message });
+      });
+
+      const client = new SimplifiedVGFRecognitionClient({
+        asrRequestConfig: {
+          provider: 'deepgram',
+          language: 'en',
+          sampleRate: 16000,
+          encoding: AudioEncoding.LINEAR16
+        },
+        onStateChange: trackingCallback,
+        logger
+      });
+
+      // Capture the onTranscript callback
+      const constructorCalls = (RealTimeTwoWayWebSocketRecognitionClient as jest.MockedClass<typeof RealTimeTwoWayWebSocketRecognitionClient>).mock.calls;
+      const latestConfig = constructorCalls[constructorCalls.length - 1]?.[0];
+      const onTranscriptCallback = latestConfig?.onTranscript;
+      if (!onTranscriptCallback) throw new Error('onTranscript callback not found');
+
+      const clientUuid = client.getVGFState().audioUtteranceId;
+
+      // Step 1: Send audio
+      client.sendAudio(Buffer.from([1, 2, 3, 4]));
+      expect(stateChangeCounter).toBe(1);
+
+      // Step 2: Receive a pending transcript (transcriptionStatus -> IN_PROGRESS, prevents synthetic finalization)
+      onTranscriptCallback({
+        type: 'Transcription',
+        audioUtteranceId: clientUuid,
+        pendingTranscript: 'hello',
+        pendingTranscriptConfidence: 0.7,
+        is_finished: false
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any);
+      expect(stateChangeCounter).toBe(2);
+
+      // Step 3: Receive first final transcript - should emit
+      onTranscriptCallback({
+        type: 'Transcription',
+        audioUtteranceId: clientUuid,
+        finalTranscript: 'hello world',
+        finalTranscriptConfidence: 0.95,
+        is_finished: true
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any);
+
+      expect(stateChangeCounter).toBe(3); // First terminal emitted
+      expect(stateHistory[2]!.transcriptionStatus).toBe(TranscriptionStatus.FINALIZED);
+
+      // Step 4: Duplicate final transcript - should be suppressed
+      onTranscriptCallback({
+        type: 'Transcription',
+        audioUtteranceId: clientUuid,
+        finalTranscript: 'different transcript',
+        finalTranscriptConfidence: 0.99,
+        is_finished: true
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any);
+
+      // Callback should NOT be called again
+      expect(stateChangeCounter).toBe(3);
+      expect(trackingCallback).toHaveBeenCalledTimes(3);
+
+      // Log should indicate suppression
+      const suppressionLog = loggerCalls.find(log =>
+        log.level === 'info' && log.message.includes('Duplicate terminal status suppressed')
+      );
+      expect(suppressionLog).toBeDefined();
+
+      // Local state IS updated with new transcript, but callback was not called
+      const finalState = client.getVGFState();
+      expect(finalState.finalTranscript).toBe('different transcript');
+    });
+
+    it('should reset terminal status flag when new UUID is generated', () => {
+      const stateChangeCallback1 = jest.fn();
+
+      // Create client with terminal state - forces new UUID generation
+      const terminalState: RecognitionState = {
+        audioUtteranceId: 'old-session-uuid',
+        transcriptionStatus: TranscriptionStatus.FINALIZED,
+        startRecordingStatus: RecordingStatus.FINISHED,
+        pendingTranscript: '',
+        finalTranscript: 'previous transcript'
+      };
+
+      const client = new SimplifiedVGFRecognitionClient({
+        initialState: terminalState,
+        asrRequestConfig: {
+          provider: 'deepgram',
+          language: 'en',
+          sampleRate: 16000,
+          encoding: AudioEncoding.LINEAR16
+        },
+        onStateChange: stateChangeCallback1
+      });
+
+      // UUID was regenerated
+      const newUuid = client.getVGFState().audioUtteranceId;
+      expect(newUuid).not.toBe('old-session-uuid');
+
+      // Initial state change callback was called (for UUID regeneration)
+      expect(stateChangeCallback1).toHaveBeenCalledTimes(1);
+
+      // Get the transcript callback
+      const constructorCalls = (RealTimeTwoWayWebSocketRecognitionClient as jest.MockedClass<typeof RealTimeTwoWayWebSocketRecognitionClient>).mock.calls;
+      const latestConfig = constructorCalls[constructorCalls.length - 1]?.[0];
+      const onTranscriptCallback = latestConfig?.onTranscript;
+      if (!onTranscriptCallback) throw new Error('onTranscript callback not found');
+
+      // Simulate new session transcript with new UUID
+      onTranscriptCallback({
+        type: 'Transcription',
+        audioUtteranceId: newUuid,
+        finalTranscript: 'new transcript',
+        finalTranscriptConfidence: 0.9,
+        is_finished: true
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      } as any);
+
+      // Should emit terminal status for new session (counter was reset)
+      expect(stateChangeCallback1).toHaveBeenCalledTimes(2);
+      const finalState = stateChangeCallback1.mock.calls[1][0];
+      expect(finalState.transcriptionStatus).toBe(TranscriptionStatus.FINALIZED);
+      expect(finalState.finalTranscript).toBe('new transcript');
+    });
+  });
+});