@volley/recognition-client-sdk 0.1.255 → 0.1.294

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

@@ -29,6 +29,7 @@ describe('SimplifiedVGFRecognitionClient', () => {
       connect: jest.fn().mockResolvedValue(undefined),
       sendAudio: jest.fn(),
       stopRecording: jest.fn().mockResolvedValue(undefined),
+      stopAbnormally: jest.fn(),
       getAudioUtteranceId: jest.fn().mockReturnValue('test-uuid'),
       getState: jest.fn().mockReturnValue(ClientState.INITIAL),
       isConnected: jest.fn().mockReturnValue(false),
@@ -674,4 +675,249 @@ describe('SimplifiedVGFRecognitionClient', () => {
       expect(callbackState).not.toBe(currentState); // Different references
     });
   });
+
+  describe('stopAbnormally', () => {
+    beforeEach(() => {
+      simplifiedClient = new SimplifiedVGFRecognitionClient({
+        asrRequestConfig: {
+          provider: 'deepgram',
+          language: 'en',
+          sampleRate: 16000,
+          encoding: AudioEncoding.LINEAR16
+        },
+        onStateChange: stateChangeCallback
+      });
+    });
+
+    it('should immediately set state to ABORTED with empty transcript', () => {
+      // Start recording first
+      simplifiedClient.sendAudio(Buffer.from([1, 2, 3]));
+      jest.clearAllMocks();
+
+      // Call stopAbnormally
+      simplifiedClient.stopAbnormally();
+
+      // Verify state was updated to ABORTED (not FINALIZED)
+      expect(stateChangeCallback).toHaveBeenCalledTimes(1);
+      const finalState = stateChangeCallback.mock.calls[0][0];
+
+      expect(finalState.transcriptionStatus).toBe(TranscriptionStatus.ABORTED);
+      expect(finalState.finalTranscript).toBe('');
+      expect(finalState.startRecordingStatus).toBe(RecordingStatus.FINISHED);
+      expect(finalState.finalRecordingTimestamp).toBeDefined();
+      expect(finalState.finalTranscriptionTimestamp).toBeDefined();
+    });
+
+    it('should stop recording audio flag', () => {
+      // Start recording
+      simplifiedClient.sendAudio(Buffer.from([1, 2, 3]));
+
+      // Call stopAbnormally
+      simplifiedClient.stopAbnormally();
+
+      // Send more audio - should not update recording status again
+      jest.clearAllMocks();
+      simplifiedClient.sendAudio(Buffer.from([4, 5, 6]));
+
+      // Verify recording status was set in sendAudio
+      const state = simplifiedClient.getVGFState();
+      expect(state.startRecordingStatus).toBe(RecordingStatus.RECORDING);
+    });
+
+    it('should be idempotent - calling twice does not change state again', () => {
+      // Start recording
+      simplifiedClient.sendAudio(Buffer.from([1, 2, 3]));
+      jest.clearAllMocks();
+
+      // Call stopAbnormally first time
+      simplifiedClient.stopAbnormally();
+      expect(stateChangeCallback).toHaveBeenCalledTimes(1);
+
+      const firstCallState = stateChangeCallback.mock.calls[0][0];
+      jest.clearAllMocks();
+
+      // Call stopAbnormally second time
+      simplifiedClient.stopAbnormally();
+
+      // Should not trigger state change callback again (already aborted)
+      expect(stateChangeCallback).toHaveBeenCalledTimes(0);
+
+      const currentState = simplifiedClient.getVGFState();
+      expect(currentState.transcriptionStatus).toBe(TranscriptionStatus.ABORTED);
+      expect(currentState.finalTranscript).toBe('');
+    });
+
+    it('should work even if called before any recording', () => {
+      // Call stopAbnormally without ever recording
+      simplifiedClient.stopAbnormally();
+
+      const state = simplifiedClient.getVGFState();
+      expect(state.transcriptionStatus).toBe(TranscriptionStatus.ABORTED);
+      expect(state.finalTranscript).toBe('');
+      expect(state.startRecordingStatus).toBe(RecordingStatus.FINISHED);
+    });
+
+    it('should preserve existing state fields except for overridden ones', () => {
+      // Set up some initial state by sending audio
+      simplifiedClient.sendAudio(Buffer.from([1, 2, 3]));
+
+      const initialState = simplifiedClient.getVGFState();
+      const audioUtteranceId = initialState.audioUtteranceId;
+
+      // Call stopAbnormally
+      simplifiedClient.stopAbnormally();
+
+      const finalState = simplifiedClient.getVGFState();
+
+      // Should preserve audioUtteranceId and other non-overridden fields
+      expect(finalState.audioUtteranceId).toBe(audioUtteranceId);
+
+      // Should override these fields
+      expect(finalState.transcriptionStatus).toBe(TranscriptionStatus.ABORTED);
+      expect(finalState.finalTranscript).toBe('');
+      expect(finalState.startRecordingStatus).toBe(RecordingStatus.FINISHED);
+    });
+
+    it('should set both recording and transcription timestamps', () => {
+      const beforeTime = new Date().toISOString();
+
+      simplifiedClient.stopAbnormally();
+
+      const state = simplifiedClient.getVGFState();
+      const afterTime = new Date().toISOString();
+
+      // Timestamps should be set and within reasonable range
+      expect(state.finalRecordingTimestamp).toBeDefined();
+      expect(state.finalTranscriptionTimestamp).toBeDefined();
+
+      // Basic sanity check that timestamps are ISO strings
+      expect(state.finalRecordingTimestamp).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+      expect(state.finalTranscriptionTimestamp).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+
+      // Timestamps should be close to current time
+      if (state.finalRecordingTimestamp) {
+        expect(state.finalRecordingTimestamp >= beforeTime).toBe(true);
+        expect(state.finalRecordingTimestamp <= afterTime).toBe(true);
+      }
+    });
+
+    it('should call underlying client stopAbnormally for cleanup', () => {
+      simplifiedClient.stopAbnormally();
+
+      // stopAbnormally on underlying client SHOULD be called for WebSocket cleanup
+      expect(mockClient.stopAbnormally).toHaveBeenCalled();
+
+      // stopRecording on underlying client should NOT be called
+      expect(mockClient.stopRecording).not.toHaveBeenCalled();
+    });
+
+    it('should differ from stopRecording behavior', async () => {
+      // Test that stopAbnormally and stopRecording behave differently
+      jest.clearAllMocks();
+
+      // Use the existing simplifiedClient for testing
+      simplifiedClient.sendAudio(Buffer.from([1, 2, 3]));
+
+      // Test stopAbnormally - should NOT call underlying client
+      simplifiedClient.stopAbnormally();
+      expect(mockClient.stopRecording).not.toHaveBeenCalled();
+
+      // Create new client to test stopRecording
+      const client2 = new SimplifiedVGFRecognitionClient({
+        asrRequestConfig: {
+          provider: 'deepgram',
+          language: 'en',
+          sampleRate: 16000,
+          encoding: AudioEncoding.LINEAR16
+        },
+        onStateChange: jest.fn()
+      });
+
+      // Clear mocks to isolate client2's behavior
+      jest.clearAllMocks();
+
+      // Test stopRecording - SHOULD call underlying client
+      await client2.stopRecording();
+      expect(mockClient.stopRecording).toHaveBeenCalled();
+    });
+
+    it('should use ABORTED status to distinguish from normal completion', () => {
+      // Test that stopAbnormally uses ABORTED, not FINALIZED
+      simplifiedClient.sendAudio(Buffer.from([1, 2, 3]));
+
+      // Abnormal stop - should set to ABORTED
+      simplifiedClient.stopAbnormally();
+      const abortedState = simplifiedClient.getVGFState();
+
+      // Verify ABORTED is used (not FINALIZED)
+      expect(abortedState.transcriptionStatus).toBe(TranscriptionStatus.ABORTED);
+      expect(abortedState.transcriptionStatus).not.toBe(TranscriptionStatus.FINALIZED);
+      expect(abortedState.finalTranscript).toBe(''); // Empty because cancelled
+
+      // ABORTED clearly indicates user cancelled, vs FINALIZED which means completed normally
+    });
+
+    describe('state guards', () => {
+      it('should do nothing if already fully stopped', () => {
+        // Setup: finalize state and mark underlying client as stopped
+        mockClient.getState.mockReturnValue(ClientState.STOPPED);
+        simplifiedClient.stopAbnormally();
+
+        // Clear mocks to test second call
+        jest.clearAllMocks();
+
+        // Call again - should return early and not call anything
+        simplifiedClient.stopAbnormally();
+
+        expect(stateChangeCallback).not.toHaveBeenCalled();
+        expect(mockClient.stopAbnormally).not.toHaveBeenCalled();
+      });
+
+      it('should not call underlying client if already in STOPPED state', () => {
+        // Mock underlying client as already stopped
+        mockClient.getState.mockReturnValue(ClientState.STOPPED);
+
+        // But VGF state not finalized yet
+        simplifiedClient.sendAudio(Buffer.from([1, 2, 3]));
+        jest.clearAllMocks();
+
+        simplifiedClient.stopAbnormally();
+
+        // Should finalize VGF state
+        expect(stateChangeCallback).toHaveBeenCalled();
+        // But should NOT call underlying client
+        expect(mockClient.stopAbnormally).not.toHaveBeenCalled();
+      });
+
+      it('should not call underlying client if already in FAILED state', () => {
+        // Mock underlying client as failed
+        mockClient.getState.mockReturnValue(ClientState.FAILED);
+
+        simplifiedClient.stopAbnormally();
+
+        // Should handle VGF state update
+        expect(stateChangeCallback).toHaveBeenCalled();
+        // But should NOT call underlying client (already in terminal state)
+        expect(mockClient.stopAbnormally).not.toHaveBeenCalled();
+      });
+
+      it('should only update VGF state if already finalized but client not stopped', () => {
+        // First call - fully stop
+        simplifiedClient.stopAbnormally();
+        const firstCallCount = stateChangeCallback.mock.calls.length;
+
+        // Mock underlying client reconnects (edge case)
+        mockClient.getState.mockReturnValue(ClientState.READY);
+        jest.clearAllMocks();
+
+        // Second call - VGF already finalized but client not stopped
+        simplifiedClient.stopAbnormally();
+
+        // Should NOT update VGF state (already finalized)
+        expect(stateChangeCallback).not.toHaveBeenCalled();
+        // But SHOULD call underlying client (not stopped)
+        expect(mockClient.stopAbnormally).toHaveBeenCalled();
+      });
+    });
+  });
 });

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

@@ -8,7 +8,11 @@
  * All functionality is delegated to the underlying client.
  */
 
-import { RecognitionState } from './vgf-recognition-state.js';
+import {
+    RecognitionState,
+    TranscriptionStatus,
+    RecordingStatus
+} from './vgf-recognition-state.js';
 import {
     IRecognitionClient,
     IRecognitionClientConfig,
@@ -67,6 +71,25 @@ export interface ISimplifiedVGFRecognitionClient {
      */
     stopRecording(): Promise<void>;
 
+    /**
+     * Force stop and immediately close connection without waiting for server
+     *
+     * WARNING: This is an abnormal shutdown that bypasses the graceful stop flow:
+     * - Does NOT wait for server to process remaining audio
+     * - Does NOT receive final transcript from server (VGF state set to empty)
+     * - Immediately closes WebSocket connection
+     * - Cleans up resources (buffers, listeners)
+     *
+     * Use Cases:
+     * - User explicitly cancels/abandons the session
+     * - Timeout scenarios where waiting is not acceptable
+     * - Need immediate cleanup and can't wait for server
+     *
+     * RECOMMENDED: Use stopRecording() for normal shutdown.
+     * Only use this when immediate disconnection is required.
+     */
+    stopAbnormally(): void;
+
     // ============= VGF State Methods =============
     /**
      * Get the current VGF recognition state
@@ -254,6 +277,40 @@ export class SimplifiedVGFRecognitionClient implements ISimplifiedVGFRecognition
         await this.client.stopRecording();
     }
 
+    stopAbnormally(): void {
+        // Guard: If already aborted/finalized and stopped, do nothing
+        if ((this.state.transcriptionStatus === TranscriptionStatus.ABORTED ||
+             this.state.transcriptionStatus === TranscriptionStatus.FINALIZED) &&
+            this.client.getState() === ClientState.STOPPED) {
+            // Already fully stopped - nothing to do
+            return;
+        }
+
+        this.isRecordingAudio = false;
+
+        // Set state to ABORTED with empty transcript
+        // This clearly indicates the session was cancelled/abandoned by user
+        if (this.state.transcriptionStatus !== TranscriptionStatus.ABORTED &&
+            this.state.transcriptionStatus !== TranscriptionStatus.FINALIZED) {
+            this.state = {
+                ...this.state,
+                transcriptionStatus: TranscriptionStatus.ABORTED,
+                finalTranscript: '',
+                startRecordingStatus: RecordingStatus.FINISHED,
+                finalRecordingTimestamp: new Date().toISOString(),
+                finalTranscriptionTimestamp: new Date().toISOString()
+            };
+            this.notifyStateChange();
+        }
+
+        // Delegate to underlying client for actual WebSocket cleanup
+        // Only if client is not already in a terminal state
+        const clientState = this.client.getState();
+        if (clientState !== ClientState.STOPPED && clientState !== ClientState.FAILED) {
+            this.client.stopAbnormally();
+        }
+    }
+
     // Pure delegation methods - no state logic
     getAudioUtteranceId(): string {
         return this.client.getAudioUtteranceId();

package/src/utils/url-builder.spec.ts

@@ -2,22 +2,24 @@
  * Unit tests for URL Builder
  */
 
-import { buildWebSocketUrl, UrlBuilderConfig } from './url-builder.js';
 import { RecognitionContextTypeV1, STAGES } from '@recog/shared-types';
 
-// Mock the shared-config module
+// Mock the shared-config module BEFORE importing the module under test
 const mockGetRecognitionServiceBase = jest.fn();
 jest.mock('@recog/shared-config', () => ({
   getRecognitionServiceBase: mockGetRecognitionServiceBase
 }));
 
+import { buildWebSocketUrl, UrlBuilderConfig } from './url-builder.js';
+
 describe('buildWebSocketUrl', () => {
   const baseConfig: UrlBuilderConfig = {
     audioUtteranceId: 'test-utterance-123'
   };
 
   beforeEach(() => {
-    // Reset mock before each test
+    // Clear and reset mock before each test
+    mockGetRecognitionServiceBase.mockClear();
     mockGetRecognitionServiceBase.mockReturnValue({
       wsBase: 'wss://recognition.volley.com'
     });

package/src/vgf-recognition-state.ts

@@ -18,7 +18,7 @@ export const RecognitionVGFStateSchema = z.object({
     audioUtteranceId: z.string(),
     startRecordingStatus: z.string().optional(), // "NOT_READY", "READY", "RECORDING", "FINISHED". States follow this order.
     // Streaming should only start when "READY". Other states control mic UI and recording.
-    transcriptionStatus: z.string().optional(), // "NOT_STARTED", "IN_PROGRESS", "FINALIZED", "ERROR"
+    transcriptionStatus: z.string().optional(), // "NOT_STARTED", "IN_PROGRESS", "FINALIZED", "ABORTED", "ERROR"
     finalTranscript: z.string().optional(), // Full finalized transcript for the utterance. Will not change.
     finalConfidence: z.number().optional(),
 
@@ -57,6 +57,7 @@ export const TranscriptionStatus = {
     NOT_STARTED: "NOT_STARTED",
     IN_PROGRESS: "IN_PROGRESS",
     FINALIZED: "FINALIZED",
+    ABORTED: "ABORTED",  // Session was cancelled/abandoned by user
     ERROR: "ERROR",
 } as const