@volley/recognition-client-sdk 0.1.200

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

@@ -0,0 +1,671 @@
+/**
+ * Unit tests for SimplifiedVGFRecognitionClient
+ */
+
+import { SimplifiedVGFRecognitionClient, createSimplifiedVGFClient } from './simplified-vgf-recognition-client.js';
+import { RealTimeTwoWayWebSocketRecognitionClient } from './recognition-client.js';
+import { ClientState } from './recognition-client.types.js';
+import { AudioEncoding, RecognitionContextTypeV1 } from '@recog/shared-types';
+import {
+  RecordingStatus,
+  TranscriptionStatus,
+  type RecognitionState
+} from './vgf-recognition-state.js';
+
+// Mock the underlying client
+jest.mock('./recognition-client');
+
+describe('SimplifiedVGFRecognitionClient', () => {
+  let mockClient: jest.Mocked<RealTimeTwoWayWebSocketRecognitionClient>;
+  let simplifiedClient: SimplifiedVGFRecognitionClient;
+  let stateChangeCallback: jest.Mock;
+
+  beforeEach(() => {
+    // Reset mocks
+    jest.clearAllMocks();
+
+    // Create mock for underlying client
+    mockClient = {
+      connect: jest.fn().mockResolvedValue(undefined),
+      sendAudio: jest.fn(),
+      stopRecording: jest.fn().mockResolvedValue(undefined),
+      getAudioUtteranceId: jest.fn().mockReturnValue('test-uuid'),
+      getState: jest.fn().mockReturnValue(ClientState.INITIAL),
+      isConnected: jest.fn().mockReturnValue(false),
+      isConnecting: jest.fn().mockReturnValue(false),
+      isStopping: jest.fn().mockReturnValue(false),
+      isTranscriptionFinished: jest.fn().mockReturnValue(false),
+      isBufferOverflowing: jest.fn().mockReturnValue(false),
+    } as any;
+
+    // Mock the constructor
+    (RealTimeTwoWayWebSocketRecognitionClient as jest.MockedClass<typeof RealTimeTwoWayWebSocketRecognitionClient>)
+      .mockImplementation(() => mockClient as any);
+
+    stateChangeCallback = jest.fn();
+  });
+
+  describe('Constructor', () => {
+    it('should initialize with correct default VGF state', () => {
+      simplifiedClient = new SimplifiedVGFRecognitionClient({
+        asrRequestConfig: {
+          provider: 'deepgram',
+          language: 'en',
+          sampleRate: 16000,
+          encoding: AudioEncoding.LINEAR16
+        },
+        onStateChange: stateChangeCallback
+      });
+
+      const state = simplifiedClient.getVGFState();
+      expect(state.audioUtteranceId).toBeDefined();
+      expect(state.startRecordingStatus).toBe(RecordingStatus.READY);
+      expect(state.transcriptionStatus).toBe(TranscriptionStatus.NOT_STARTED);
+      expect(state.pendingTranscript).toBe('');
+    });
+
+    it('should accept initial state and use its audioUtteranceId', () => {
+      const initialState: RecognitionState = {
+        audioUtteranceId: 'existing-session-id',
+        startRecordingStatus: RecordingStatus.FINISHED,
+        finalTranscript: 'Previous transcript',
+        pendingTranscript: '', // Required field
+        transcriptionStatus: TranscriptionStatus.FINALIZED
+      };
+
+      simplifiedClient = new SimplifiedVGFRecognitionClient({
+        initialState,
+        onStateChange: stateChangeCallback
+      });
+
+      const state = simplifiedClient.getVGFState();
+      expect(state.audioUtteranceId).toBe('existing-session-id');
+      expect(state.finalTranscript).toBe('Previous transcript');
+
+      // Verify audioUtteranceId was passed to underlying client
+      const constructorCalls = (RealTimeTwoWayWebSocketRecognitionClient as jest.MockedClass<typeof RealTimeTwoWayWebSocketRecognitionClient>).mock.calls;
+      expect(constructorCalls[0]?.[0]?.audioUtteranceId).toBe('existing-session-id');
+    });
+
+    it('should store ASR config as JSON string', () => {
+      const asrConfig = {
+        provider: 'deepgram' as const,
+        language: 'en',
+        model: 'nova-2',
+        sampleRate: 16000,
+        encoding: AudioEncoding.LINEAR16
+      };
+
+      simplifiedClient = new SimplifiedVGFRecognitionClient({
+        asrRequestConfig: asrConfig,
+        onStateChange: stateChangeCallback
+      });
+
+      const state = simplifiedClient.getVGFState();
+      expect(state.asrConfig).toBe(JSON.stringify(asrConfig));
+    });
+  });
+
+  describe('State Management', () => {
+    beforeEach(() => {
+      simplifiedClient = new SimplifiedVGFRecognitionClient({
+        asrRequestConfig: {
+          provider: 'deepgram',
+          language: 'en',
+          sampleRate: 16000,
+          encoding: AudioEncoding.LINEAR16
+        },
+        onStateChange: stateChangeCallback
+      });
+    });
+
+    it('should update state to RECORDING when sendAudio is called', () => {
+      const audioData = Buffer.from([1, 2, 3, 4]);
+      simplifiedClient.sendAudio(audioData);
+
+      expect(stateChangeCallback).toHaveBeenCalled();
+      const updatedState = stateChangeCallback.mock.calls[0][0];
+      expect(updatedState.startRecordingStatus).toBe(RecordingStatus.RECORDING);
+      expect(updatedState.startRecordingTimestamp).toBeDefined();
+    });
+
+    it('should only set recording timestamp once', () => {
+      const audioData = Buffer.from([1, 2, 3, 4]);
+
+      simplifiedClient.sendAudio(audioData);
+      const firstTimestamp = stateChangeCallback.mock.calls[0][0].startRecordingTimestamp;
+
+      // Clear mock to verify no additional state changes
+      stateChangeCallback.mockClear();
+
+      // Second sendAudio should not trigger state change since already recording
+      simplifiedClient.sendAudio(audioData);
+      expect(stateChangeCallback).not.toHaveBeenCalled();
+
+      // Verify timestamp hasn't changed in internal state
+      const currentState = simplifiedClient.getVGFState();
+      expect(currentState.startRecordingTimestamp).toBe(firstTimestamp);
+    });
+
+    it('should update state to FINISHED when stopRecording is called', async () => {
+      await simplifiedClient.stopRecording();
+
+      expect(stateChangeCallback).toHaveBeenCalled();
+      const updatedState = stateChangeCallback.mock.calls[0][0];
+      expect(updatedState.startRecordingStatus).toBe(RecordingStatus.FINISHED);
+      expect(updatedState.finalRecordingTimestamp).toBeDefined();
+    });
+  });
+
+  describe('Transcript Callbacks', () => {
+    let onTranscriptCallback: (result: any) => void;
+    let onMetadataCallback: (metadata: any) => void;
+    let onErrorCallback: (error: any) => void;
+
+    beforeEach(() => {
+      // Capture the callbacks passed to underlying client
+      simplifiedClient = new SimplifiedVGFRecognitionClient({
+        asrRequestConfig: {
+          provider: 'deepgram',
+          language: 'en',
+          sampleRate: 16000,
+          encoding: AudioEncoding.LINEAR16
+        },
+        onStateChange: stateChangeCallback
+      });
+
+      const constructorCall = (RealTimeTwoWayWebSocketRecognitionClient as jest.MockedClass<typeof RealTimeTwoWayWebSocketRecognitionClient>).mock.calls[0]?.[0];
+      onTranscriptCallback = constructorCall?.onTranscript ?? jest.fn();
+      onMetadataCallback = constructorCall?.onMetadata ?? jest.fn();
+      onErrorCallback = constructorCall?.onError ?? jest.fn();
+    });
+
+    it('should directly copy pending transcript without combining', () => {
+      const transcriptResult = {
+        finalTranscript: 'Hello',
+        pendingTranscript: ' world',
+        pendingTranscriptConfidence: 0.85,
+        finalTranscriptConfidence: 0.95,
+        is_finished: false
+      };
+
+      onTranscriptCallback(transcriptResult);
+
+      expect(stateChangeCallback).toHaveBeenCalled();
+      const updatedState = stateChangeCallback.mock.calls[0][0];
+      expect(updatedState.transcriptionStatus).toBe(TranscriptionStatus.IN_PROGRESS);
+      // Should be direct copy, NOT combined
+      expect(updatedState.pendingTranscript).toBe(' world');
+      expect(updatedState.pendingConfidence).toBe(0.85);
+      // Final should also be copied when present
+      expect(updatedState.finalTranscript).toBe('Hello');
+      expect(updatedState.finalConfidence).toBe(0.95);
+    });
+
+    it('should update VGF state with final transcript', () => {
+      const transcriptResult = {
+        finalTranscript: 'Hello world',
+        finalTranscriptConfidence: 0.98,
+        is_finished: true
+      };
+
+      onTranscriptCallback(transcriptResult);
+
+      expect(stateChangeCallback).toHaveBeenCalled();
+      const updatedState = stateChangeCallback.mock.calls[0][0];
+      expect(updatedState.transcriptionStatus).toBe(TranscriptionStatus.FINALIZED);
+      expect(updatedState.finalTranscript).toBe('Hello world');
+      expect(updatedState.finalConfidence).toBe(0.98);
+      expect(updatedState.pendingTranscript).toBe('');
+      expect(updatedState.finalTranscriptionTimestamp).toBeDefined();
+    });
+
+    it('should handle metadata and mark recording as finished', () => {
+      const metadata = {
+        audioUtteranceId: 'test-uuid',
+        duration: 5000
+      };
+
+      onMetadataCallback(metadata);
+
+      expect(stateChangeCallback).toHaveBeenCalled();
+      const updatedState = stateChangeCallback.mock.calls[0][0];
+      expect(updatedState.startRecordingStatus).toBe(RecordingStatus.FINISHED);
+      expect(updatedState.finalRecordingTimestamp).toBeDefined();
+    });
+
+    it('should handle errors and update state', () => {
+      const error = {
+        message: 'Recognition failed',
+        code: 'RECOGNITION_ERROR'
+      };
+
+      onErrorCallback(error);
+
+      expect(stateChangeCallback).toHaveBeenCalled();
+      const updatedState = stateChangeCallback.mock.calls[0][0];
+      expect(updatedState.transcriptionStatus).toBe(TranscriptionStatus.ERROR);
+      expect(updatedState.startRecordingStatus).toBe(RecordingStatus.FINISHED);
+    });
+
+    it('should reset isRecordingAudio on error', () => {
+      // First start recording
+      simplifiedClient.sendAudio(Buffer.from([1, 2, 3]));
+
+      // Then error occurs
+      onErrorCallback({ message: 'Error' });
+
+      // Send audio again should restart recording
+      stateChangeCallback.mockClear();
+      simplifiedClient.sendAudio(Buffer.from([4, 5, 6]));
+
+      const updatedState = stateChangeCallback.mock.calls[0][0];
+      expect(updatedState.startRecordingStatus).toBe(RecordingStatus.RECORDING);
+      expect(updatedState.startRecordingTimestamp).toBeDefined();
+    });
+  });
+
+  describe('Method Delegation', () => {
+    beforeEach(() => {
+      simplifiedClient = new SimplifiedVGFRecognitionClient({
+        asrRequestConfig: {
+          provider: 'deepgram',
+          language: 'en',
+          sampleRate: 16000,
+          encoding: AudioEncoding.LINEAR16
+        }
+      });
+    });
+
+    it('should delegate connect() to underlying client', async () => {
+      await simplifiedClient.connect();
+      expect(mockClient.connect).toHaveBeenCalled();
+    });
+
+    it('should delegate sendAudio() to underlying client', () => {
+      const audioData = Buffer.from([1, 2, 3, 4]);
+      simplifiedClient.sendAudio(audioData);
+      expect(mockClient.sendAudio).toHaveBeenCalledWith(audioData);
+    });
+
+    it('should delegate stopRecording() to underlying client', async () => {
+      await simplifiedClient.stopRecording();
+      expect(mockClient.stopRecording).toHaveBeenCalled();
+    });
+
+    it('should delegate status check methods', () => {
+      simplifiedClient.isConnected();
+      expect(mockClient.isConnected).toHaveBeenCalled();
+
+      simplifiedClient.isConnecting();
+      expect(mockClient.isConnecting).toHaveBeenCalled();
+
+      simplifiedClient.isStopping();
+      expect(mockClient.isStopping).toHaveBeenCalled();
+
+      simplifiedClient.isTranscriptionFinished();
+      expect(mockClient.isTranscriptionFinished).toHaveBeenCalled();
+
+      simplifiedClient.isBufferOverflowing();
+      expect(mockClient.isBufferOverflowing).toHaveBeenCalled();
+    });
+
+    it('should delegate getAudioUtteranceId()', () => {
+      const id = simplifiedClient.getAudioUtteranceId();
+      expect(mockClient.getAudioUtteranceId).toHaveBeenCalled();
+      expect(id).toBe('test-uuid');
+    });
+
+    it('should delegate getState()', () => {
+      const state = simplifiedClient.getState();
+      expect(mockClient.getState).toHaveBeenCalled();
+      expect(state).toBe(ClientState.INITIAL);
+    });
+  });
+
+  describe('Original Callbacks', () => {
+    it('should call original onTranscript callback if provided', () => {
+      const originalOnTranscript = jest.fn();
+
+      simplifiedClient = new SimplifiedVGFRecognitionClient({
+        asrRequestConfig: {
+          provider: 'deepgram',
+          language: 'en',
+          sampleRate: 16000,
+          encoding: AudioEncoding.LINEAR16
+        },
+        onTranscript: originalOnTranscript
+      });
+
+      const constructorCall = (RealTimeTwoWayWebSocketRecognitionClient as jest.MockedClass<typeof RealTimeTwoWayWebSocketRecognitionClient>).mock.calls[0]?.[0];
+      const wrappedCallback = constructorCall?.onTranscript;
+      if (!wrappedCallback) throw new Error('onTranscript callback not found');
+
+      const result = { finalTranscript: 'test', is_finished: false };
+      wrappedCallback(result as any);
+
+      expect(originalOnTranscript).toHaveBeenCalledWith(result);
+    });
+
+    it('should call original onError callback if provided', () => {
+      const originalOnError = jest.fn();
+
+      simplifiedClient = new SimplifiedVGFRecognitionClient({
+        asrRequestConfig: {
+          provider: 'deepgram',
+          language: 'en',
+          sampleRate: 16000,
+          encoding: AudioEncoding.LINEAR16
+        },
+        onError: originalOnError
+      });
+
+      const constructorCall = (RealTimeTwoWayWebSocketRecognitionClient as jest.MockedClass<typeof RealTimeTwoWayWebSocketRecognitionClient>).mock.calls[0]?.[0];
+      const wrappedCallback = constructorCall?.onError;
+      if (!wrappedCallback) throw new Error('onError callback not found');
+
+      const error = { message: 'test error' };
+      wrappedCallback(error as any);
+
+      expect(originalOnError).toHaveBeenCalledWith(error);
+    });
+  });
+
+  describe('Thin Layer Verification', () => {
+    it('should pass transcript result directly to mapper without modification', () => {
+      const transcriptResult = {
+        type: 'Transcription',
+        audioUtteranceId: 'test-123',
+        finalTranscript: 'Final text',
+        pendingTranscript: 'Pending text',
+        finalTranscriptConfidence: 0.99,
+        pendingTranscriptConfidence: 0.88,
+        is_finished: false,
+        voiceStart: 100,
+        voiceDuration: 500,
+        voiceEnd: 600,
+        extraField: 'should be ignored by VGF state'
+      };
+
+      simplifiedClient = new SimplifiedVGFRecognitionClient({
+        asrRequestConfig: {
+          provider: 'deepgram',
+          language: 'en',
+          sampleRate: 16000,
+          encoding: AudioEncoding.LINEAR16
+        },
+        onStateChange: stateChangeCallback
+      });
+
+      const constructorCall = (RealTimeTwoWayWebSocketRecognitionClient as jest.MockedClass<typeof RealTimeTwoWayWebSocketRecognitionClient>).mock.calls[0]?.[0];
+      const wrappedCallback = constructorCall?.onTranscript;
+      if (!wrappedCallback) throw new Error('onTranscript callback not found');
+
+      wrappedCallback(transcriptResult as any);
+
+      const updatedState = stateChangeCallback.mock.calls[0][0];
+      // Verify direct copy without modification
+      expect(updatedState.pendingTranscript).toBe('Pending text');
+      expect(updatedState.finalTranscript).toBe('Final text');
+      expect(updatedState.pendingConfidence).toBe(0.88);
+      expect(updatedState.finalConfidence).toBe(0.99);
+    });
+
+    it('should handle only pending transcript correctly', () => {
+      const transcriptResult = {
+        pendingTranscript: 'Just pending',
+        pendingTranscriptConfidence: 0.75,
+        is_finished: false
+      };
+
+      simplifiedClient = new SimplifiedVGFRecognitionClient({
+        asrRequestConfig: {
+          provider: 'deepgram',
+          language: 'en',
+          sampleRate: 16000,
+          encoding: AudioEncoding.LINEAR16
+        },
+        onStateChange: stateChangeCallback
+      });
+
+      const constructorCall = (RealTimeTwoWayWebSocketRecognitionClient as jest.MockedClass<typeof RealTimeTwoWayWebSocketRecognitionClient>).mock.calls[0]?.[0];
+      const wrappedCallback = constructorCall?.onTranscript;
+      if (!wrappedCallback) throw new Error('onTranscript callback not found');
+
+      wrappedCallback(transcriptResult as any);
+
+      const updatedState = stateChangeCallback.mock.calls[0][0];
+      expect(updatedState.pendingTranscript).toBe('Just pending');
+      expect(updatedState.pendingConfidence).toBe(0.75);
+      expect(updatedState.finalTranscript).toBeUndefined();
+      expect(updatedState.finalConfidence).toBeUndefined();
+    });
+
+    it('should handle only final transcript correctly', () => {
+      const transcriptResult = {
+        finalTranscript: 'Just final',
+        finalTranscriptConfidence: 0.92,
+        is_finished: false
+      };
+
+      simplifiedClient = new SimplifiedVGFRecognitionClient({
+        asrRequestConfig: {
+          provider: 'deepgram',
+          language: 'en',
+          sampleRate: 16000,
+          encoding: AudioEncoding.LINEAR16
+        },
+        onStateChange: stateChangeCallback
+      });
+
+      const constructorCall = (RealTimeTwoWayWebSocketRecognitionClient as jest.MockedClass<typeof RealTimeTwoWayWebSocketRecognitionClient>).mock.calls[0]?.[0];
+      const wrappedCallback = constructorCall?.onTranscript;
+      if (!wrappedCallback) throw new Error('onTranscript callback not found');
+
+      wrappedCallback(transcriptResult as any);
+
+      const updatedState = stateChangeCallback.mock.calls[0][0];
+      expect(updatedState.pendingTranscript).toBe(''); // Empty string when undefined
+      expect(updatedState.pendingConfidence).toBeUndefined();
+      expect(updatedState.finalTranscript).toBe('Just final');
+      expect(updatedState.finalConfidence).toBe(0.92);
+    });
+
+    it('should clear pending when is_finished is true', () => {
+      const transcriptResult = {
+        finalTranscript: 'Complete transcript',
+        pendingTranscript: 'Should be ignored',
+        finalTranscriptConfidence: 0.98,
+        pendingTranscriptConfidence: 0.77,
+        is_finished: true
+      };
+
+      simplifiedClient = new SimplifiedVGFRecognitionClient({
+        asrRequestConfig: {
+          provider: 'deepgram',
+          language: 'en',
+          sampleRate: 16000,
+          encoding: AudioEncoding.LINEAR16
+        },
+        onStateChange: stateChangeCallback
+      });
+
+      const constructorCall = (RealTimeTwoWayWebSocketRecognitionClient as jest.MockedClass<typeof RealTimeTwoWayWebSocketRecognitionClient>).mock.calls[0]?.[0];
+      const wrappedCallback = constructorCall?.onTranscript;
+      if (!wrappedCallback) throw new Error('onTranscript callback not found');
+
+      wrappedCallback(transcriptResult as any);
+
+      const updatedState = stateChangeCallback.mock.calls[0][0];
+      expect(updatedState.finalTranscript).toBe('Complete transcript');
+      expect(updatedState.finalConfidence).toBe(0.98);
+      // Pending should be cleared when finished
+      expect(updatedState.pendingTranscript).toBe('');
+      expect(updatedState.pendingConfidence).toBeUndefined();
+      expect(updatedState.transcriptionStatus).toBe(TranscriptionStatus.FINALIZED);
+    });
+  });
+
+  describe('Factory Function', () => {
+    it('should create SimplifiedVGFRecognitionClient instance', () => {
+      const client = createSimplifiedVGFClient({
+        asrRequestConfig: {
+          provider: 'deepgram',
+          language: 'en',
+          sampleRate: 16000,
+          encoding: AudioEncoding.LINEAR16
+        }
+      });
+
+      expect(client).toBeInstanceOf(SimplifiedVGFRecognitionClient);
+      expect(client.getVGFState).toBeDefined();
+      expect(client.connect).toBeDefined();
+    });
+  });
+
+  describe('PromptSlotMap Integration', () => {
+    it('should pass promptSlotMap from initial state to gameContext', () => {
+      const initialState: RecognitionState = {
+        audioUtteranceId: 'test-123',
+        pendingTranscript: '', // Required field
+        promptSlotMap: {
+          'entity1': ['value1', 'value2'],
+          'entity2': ['value3']
+        }
+      };
+
+      const gameContext = {
+        type: RecognitionContextTypeV1.GAME_CONTEXT,
+        gameId: 'test-game',
+        gamePhase: 'test-phase'
+      } as const;
+
+      simplifiedClient = new SimplifiedVGFRecognitionClient({
+        asrRequestConfig: {
+          provider: 'deepgram',
+          language: 'en',
+          sampleRate: 16000,
+          encoding: AudioEncoding.LINEAR16
+        },
+        gameContext,
+        initialState
+      });
+
+      const constructorCall = (RealTimeTwoWayWebSocketRecognitionClient as jest.MockedClass<typeof RealTimeTwoWayWebSocketRecognitionClient>).mock.calls[0]?.[0];
+
+      // Verify useContext was set to true
+      expect(constructorCall?.asrRequestConfig?.useContext).toBe(true);
+
+      // Verify slotMap was added to gameContext
+      expect(constructorCall?.gameContext?.slotMap).toEqual({
+        'entity1': ['value1', 'value2'],
+        'entity2': ['value3']
+      });
+    });
+
+    it('should warn if promptSlotMap exists but no gameContext provided', () => {
+      const logger = jest.fn();
+      const initialState: RecognitionState = {
+        audioUtteranceId: 'test-123',
+        pendingTranscript: '', // Required field
+        promptSlotMap: {
+          'entity1': ['value1']
+        }
+      };
+
+      simplifiedClient = new SimplifiedVGFRecognitionClient({
+        asrRequestConfig: {
+          provider: 'deepgram',
+          language: 'en',
+          sampleRate: 16000,
+          encoding: AudioEncoding.LINEAR16
+        },
+        initialState,
+        logger
+      });
+
+      expect(logger).toHaveBeenCalledWith(
+        'warn',
+        '[VGF] promptSlotMap found but no gameContext provided. SlotMap will not be sent.'
+      );
+    });
+
+    it('should preserve promptSlotMap throughout state changes', () => {
+      const initialState: RecognitionState = {
+        audioUtteranceId: 'test-123',
+        pendingTranscript: '', // Required field
+        promptSlotMap: {
+          'slots': ['test']
+        }
+      };
+
+      simplifiedClient = new SimplifiedVGFRecognitionClient({
+        asrRequestConfig: {
+          provider: 'deepgram',
+          language: 'en',
+          sampleRate: 16000,
+          encoding: AudioEncoding.LINEAR16
+        },
+        initialState,
+        onStateChange: stateChangeCallback
+      });
+
+      // Send audio and verify promptSlotMap is preserved
+      simplifiedClient.sendAudio(Buffer.from([1, 2, 3]));
+
+      let state = stateChangeCallback.mock.calls[0][0];
+      expect(state.promptSlotMap).toEqual({ 'slots': ['test'] });
+
+      // Simulate transcript and verify preservation
+      const constructorCall = (RealTimeTwoWayWebSocketRecognitionClient as jest.MockedClass<typeof RealTimeTwoWayWebSocketRecognitionClient>).mock.calls[0]?.[0];
+      const onTranscriptCallback = constructorCall?.onTranscript;
+      if (!onTranscriptCallback) throw new Error('onTranscript callback not found');
+
+      onTranscriptCallback({
+        finalTranscript: 'test',
+        is_finished: false
+      } as any);
+
+      state = stateChangeCallback.mock.calls[1][0];
+      expect(state.promptSlotMap).toEqual({ 'slots': ['test'] });
+    });
+  });
+
+  describe('State Immutability', () => {
+    it('should return a copy of VGF state, not a reference', () => {
+      simplifiedClient = new SimplifiedVGFRecognitionClient({
+        asrRequestConfig: {
+          provider: 'deepgram',
+          language: 'en',
+          sampleRate: 16000,
+          encoding: AudioEncoding.LINEAR16
+        }
+      });
+
+      const state1 = simplifiedClient.getVGFState();
+      const state2 = simplifiedClient.getVGFState();
+
+      expect(state1).not.toBe(state2); // Different object references
+      expect(state1).toEqual(state2);  // But same content
+    });
+
+    it('should pass a copy of state to onStateChange callback', () => {
+      simplifiedClient = new SimplifiedVGFRecognitionClient({
+        asrRequestConfig: {
+          provider: 'deepgram',
+          language: 'en',
+          sampleRate: 16000,
+          encoding: AudioEncoding.LINEAR16
+        },
+        onStateChange: stateChangeCallback
+      });
+
+      simplifiedClient.sendAudio(Buffer.from([1, 2, 3]));
+
+      const callbackState = stateChangeCallback.mock.calls[0][0];
+      const currentState = simplifiedClient.getVGFState();
+
+      expect(callbackState).not.toBe(currentState); // Different references
+    });
+  });
+});