@volley/recognition-client-sdk 0.1.287 → 0.1.295

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,38 @@ export class SimplifiedVGFRecognitionClient implements ISimplifiedVGFRecognition
         await this.client.stopRecording();
     }
 
+    stopAbnormally(): void {
+        const clientState = this.client.getState();
+
+        // Guard: Block if graceful shutdown in progress or already in terminal state
+        // This prevents stopAbnormally from disrupting stopRecording's graceful finalization
+        if (clientState === ClientState.STOPPING ||
+            clientState === ClientState.STOPPED ||
+            clientState === ClientState.FAILED) {
+            // Already stopping/stopped - do nothing to avoid disrupting graceful shutdown
+            return;
+        }
+
+        this.isRecordingAudio = false;
+
+        // Set state to ABORTED - preserve any partial transcript received so far
+        // 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,
+                startRecordingStatus: RecordingStatus.FINISHED,
+                finalRecordingTimestamp: new Date().toISOString(),
+                finalTranscriptionTimestamp: new Date().toISOString()
+            };
+            this.notifyStateChange();
+        }
+
+        // Delegate to underlying client for actual WebSocket cleanup
+        this.client.stopAbnormally();
+    }
+
     // Pure delegation methods - no state logic
     getAudioUtteranceId(): string {
         return this.client.getAudioUtteranceId();

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