@volley/recognition-client-sdk 0.1.384 → 0.1.417

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

@@ -5,7 +5,7 @@
 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 { AudioEncoding, RecognitionContextTypeV1, RecognitionResultTypeV1 } from '@recog/shared-types';
 import {
   RecordingStatus,
   TranscriptionStatus,
@@ -287,21 +287,43 @@ describe('SimplifiedVGFRecognitionClient', () => {
       expect(updatedState.finalTranscriptionTimestamp).toBeDefined();
     });
 
-    it('should handle metadata and mark recording as finished', () => {
+    it('should pass metadata to callback without updating VGF state', () => {
       // Get the actual UUID from the client
       const actualUuid = simplifiedClient.getVGFState().audioUtteranceId;
+      const originalOnMetadata = jest.fn();
 
+      // Create new client with onMetadata callback
+      const clientWithMetadata = new SimplifiedVGFRecognitionClient({
+        asrRequestConfig: {
+          provider: 'deepgram',
+          language: 'en',
+          sampleRate: 16000,
+          encoding: AudioEncoding.LINEAR16
+        },
+        onStateChange: stateChangeCallback,
+        onMetadata: originalOnMetadata
+      });
+
+      const constructorCalls = (RealTimeTwoWayWebSocketRecognitionClient as jest.MockedClass<typeof RealTimeTwoWayWebSocketRecognitionClient>).mock.calls;
+      const latestConfig = constructorCalls[constructorCalls.length - 1]?.[0];
+      const metadataCallback = latestConfig?.onMetadata;
+
+      const clientUuid = clientWithMetadata.getVGFState().audioUtteranceId;
       const metadata = {
-        audioUtteranceId: actualUuid,
-        duration: 5000
+        type: RecognitionResultTypeV1.METADATA as const,
+        audioUtteranceId: clientUuid
       };
 
-      onMetadataCallback(metadata);
+      // Clear previous state changes from client creation
+      stateChangeCallback.mockClear();
 
-      expect(stateChangeCallback).toHaveBeenCalled();
-      const updatedState = stateChangeCallback.mock.calls[0][0];
-      expect(updatedState.startRecordingStatus).toBe(RecordingStatus.FINISHED);
-      expect(updatedState.finalRecordingTimestamp).toBeDefined();
+      metadataCallback?.(metadata);
+
+      // Metadata should NOT trigger state change (state management simplified)
+      expect(stateChangeCallback).not.toHaveBeenCalled();
+
+      // But original callback should still be called
+      expect(originalOnMetadata).toHaveBeenCalledWith(metadata);
     });
 
     it('should handle errors and update state', () => {
@@ -325,13 +347,18 @@ describe('SimplifiedVGFRecognitionClient', () => {
       // Then error occurs
       onErrorCallback({ message: 'Error' });
 
-      // Send audio again should restart recording
+      // After terminal status (ERROR), no more state changes should be emitted
+      // The session is considered over, so sendAudio should not trigger callbacks
       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();
+      // No callback should be triggered since we're in terminal state
+      expect(stateChangeCallback).not.toHaveBeenCalled();
+
+      // However, the internal isRecordingAudio flag should still be reset
+      // (verified by the fact that the flag was set during the first sendAudio)
+      const state = simplifiedClient.getVGFState();
+      expect(state.transcriptionStatus).toBe(TranscriptionStatus.ERROR);
     });
   });
 
@@ -1331,4 +1358,163 @@ describe('SimplifiedVGFRecognitionClient', () => {
       expect(stateChangeCallback).not.toHaveBeenCalled();
     });
   });
+
+  describe('Terminal Status Protection', () => {
+    let stateChangeCallback: jest.Mock;
+    let onTranscriptCallback: (result: any) => void;
+    let onErrorCallback: (error: any) => void;
+    let simplifiedClient: SimplifiedVGFRecognitionClient;
+    let clientUuid: string;
+
+    beforeEach(() => {
+      stateChangeCallback = jest.fn();
+      simplifiedClient = new SimplifiedVGFRecognitionClient({
+        asrRequestConfig: {
+          provider: 'deepgram',
+          language: 'en',
+          sampleRate: 16000,
+          encoding: AudioEncoding.LINEAR16
+        },
+        onStateChange: stateChangeCallback
+      });
+
+      const constructorCalls = (RealTimeTwoWayWebSocketRecognitionClient as jest.MockedClass<typeof RealTimeTwoWayWebSocketRecognitionClient>).mock.calls;
+      const latestConfig = constructorCalls[constructorCalls.length - 1]?.[0];
+      onTranscriptCallback = latestConfig?.onTranscript ?? jest.fn();
+      onErrorCallback = latestConfig?.onError ?? jest.fn();
+      clientUuid = simplifiedClient.getVGFState().audioUtteranceId;
+    });
+
+    it('should allow first terminal transcript callback', () => {
+      onTranscriptCallback({
+        type: 'Transcription',
+        audioUtteranceId: clientUuid,
+        finalTranscript: 'hello',
+        finalTranscriptConfidence: 0.9,
+        is_finished: true
+      });
+
+      expect(stateChangeCallback).toHaveBeenCalledTimes(1);
+      expect(stateChangeCallback.mock.calls[0][0].transcriptionStatus).toBe(TranscriptionStatus.FINALIZED);
+    });
+
+    it('should block second terminal transcript callback with same UUID', () => {
+      // First terminal
+      onTranscriptCallback({
+        type: 'Transcription',
+        audioUtteranceId: clientUuid,
+        finalTranscript: 'first',
+        finalTranscriptConfidence: 0.9,
+        is_finished: true
+      });
+
+      stateChangeCallback.mockClear();
+
+      // Second terminal - should be blocked
+      onTranscriptCallback({
+        type: 'Transcription',
+        audioUtteranceId: clientUuid,
+        finalTranscript: 'second',
+        finalTranscriptConfidence: 0.95,
+        is_finished: true
+      });
+
+      expect(stateChangeCallback).not.toHaveBeenCalled();
+    });
+
+    it('should allow first error callback', () => {
+      onErrorCallback({
+        audioUtteranceId: clientUuid,
+        message: 'Error occurred'
+      });
+
+      expect(stateChangeCallback).toHaveBeenCalledTimes(1);
+      expect(stateChangeCallback.mock.calls[0][0].transcriptionStatus).toBe(TranscriptionStatus.ERROR);
+    });
+
+    it('should block second error callback with same UUID', () => {
+      // First error
+      onErrorCallback({
+        audioUtteranceId: clientUuid,
+        message: 'First error'
+      });
+
+      stateChangeCallback.mockClear();
+
+      // Second error - should be blocked
+      onErrorCallback({
+        audioUtteranceId: clientUuid,
+        message: 'Second error'
+      });
+
+      expect(stateChangeCallback).not.toHaveBeenCalled();
+    });
+
+    it('should block transcript after error', () => {
+      // Error first
+      onErrorCallback({
+        audioUtteranceId: clientUuid,
+        message: 'Error'
+      });
+
+      stateChangeCallback.mockClear();
+
+      // Transcript after error - should be blocked
+      onTranscriptCallback({
+        type: 'Transcription',
+        audioUtteranceId: clientUuid,
+        finalTranscript: 'late',
+        finalTranscriptConfidence: 0.9,
+        is_finished: true
+      });
+
+      expect(stateChangeCallback).not.toHaveBeenCalled();
+    });
+
+    it('should block error after terminal transcript', () => {
+      // Terminal transcript first
+      onTranscriptCallback({
+        type: 'Transcription',
+        audioUtteranceId: clientUuid,
+        finalTranscript: 'done',
+        finalTranscriptConfidence: 0.9,
+        is_finished: true
+      });
+
+      stateChangeCallback.mockClear();
+
+      // Error after terminal - should be blocked
+      onErrorCallback({
+        audioUtteranceId: clientUuid,
+        message: 'Late error'
+      });
+
+      expect(stateChangeCallback).not.toHaveBeenCalled();
+    });
+
+    it('should preserve original state after blocking duplicate', () => {
+      // First terminal with specific transcript
+      onTranscriptCallback({
+        type: 'Transcription',
+        audioUtteranceId: clientUuid,
+        finalTranscript: 'original',
+        finalTranscriptConfidence: 0.85,
+        is_finished: true
+      });
+
+      // Attempt second terminal with different transcript
+      onTranscriptCallback({
+        type: 'Transcription',
+        audioUtteranceId: clientUuid,
+        finalTranscript: 'different',
+        finalTranscriptConfidence: 0.99,
+        is_finished: true
+      });
+
+      // State should still have original values
+      const state = simplifiedClient.getVGFState();
+      expect(state.finalTranscript).toBe('original');
+      expect(state.finalConfidence).toBe(0.85);
+    });
+  });
 });

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

@@ -23,7 +23,6 @@ import { RealTimeTwoWayWebSocketRecognitionClient } from './recognition-client.j
 import {
     createVGFStateFromConfig,
     mapTranscriptionResultToState,
-    mapMetadataToState,
     mapErrorToState,
     updateStateOnStop
 } from './vgf-recognition-mapper.js';
@@ -154,6 +153,7 @@ export class SimplifiedVGFRecognitionClient implements ISimplifiedVGFRecognition
     private stateChangeCallback: ((state: RecognitionState) => void) | undefined;
     private expectedUuid: string;
     private logger: IRecognitionClientConfig['logger'];
+    private lastSentTerminalUuid: string | null = null;
 
     constructor(config: SimplifiedVGFClientConfig) {
         const { onStateChange, initialState, ...clientConfig } = config;
@@ -193,6 +193,9 @@ export class SimplifiedVGFRecognitionClient implements ISimplifiedVGFRecognition
                 // Use new UUID in client config
                 clientConfig.audioUtteranceId = newUUID;
 
+                // Reset terminal status tracking for new session
+                this.lastSentTerminalUuid = null;
+
                 // Notify state change immediately so app can update
                 if (onStateChange) {
                     onStateChange(this.state);
@@ -246,12 +249,19 @@ export class SimplifiedVGFRecognitionClient implements ISimplifiedVGFRecognition
                 if (result.audioUtteranceId && result.audioUtteranceId !== this.expectedUuid) {
                     if (this.logger) {
                         this.logger('warn',
-                            `[VGF] Skipping transcript update: UUID mismatch (expected: ${this.expectedUuid}, got: ${result.audioUtteranceId})`
+                            `[RecogSDK:VGF] Skipping transcript update: UUID mismatch (expected: ${this.expectedUuid}, got: ${result.audioUtteranceId})`
                         );
                     }
-                    // Still call original callback if provided
-                    if (clientConfig.onTranscript) {
-                        clientConfig.onTranscript(result);
+                    return;
+                }
+
+                // Skip if terminal status already sent for THIS session
+                // (If lastSentTerminalUuid exists but doesn't match expectedUuid, treat as new session)
+                if (this.lastSentTerminalUuid === this.expectedUuid) {
+                    if (this.logger) {
+                        this.logger('info',
+                            `[RecogSDK:VGF] Duplicate terminal status suppressed (lastSentTerminalUuid: ${this.lastSentTerminalUuid})`
+                        );
                     }
                     return;
                 }
@@ -271,19 +281,12 @@ export class SimplifiedVGFRecognitionClient implements ISimplifiedVGFRecognition
                 if (metadata.audioUtteranceId && metadata.audioUtteranceId !== this.expectedUuid) {
                     if (this.logger) {
                         this.logger('warn',
-                            `[VGF] Skipping metadata update: UUID mismatch (expected: ${this.expectedUuid}, got: ${metadata.audioUtteranceId})`
+                            `[RecogSDK:VGF] Skipping metadata update: UUID mismatch (expected: ${this.expectedUuid}, got: ${metadata.audioUtteranceId})`
                         );
                     }
-                    // Still call original callback if provided
-                    if (clientConfig.onMetadata) {
-                        clientConfig.onMetadata(metadata);
-                    }
                     return;
                 }
 
-                this.state = mapMetadataToState(this.state, metadata);
-                this.notifyStateChange();
-
                 if (clientConfig.onMetadata) {
                     clientConfig.onMetadata(metadata);
                 }
@@ -301,13 +304,14 @@ export class SimplifiedVGFRecognitionClient implements ISimplifiedVGFRecognition
                 if (error.audioUtteranceId && error.audioUtteranceId !== this.expectedUuid) {
                     if (this.logger) {
                         this.logger('warn',
-                            `[VGF] Skipping error update: UUID mismatch (expected: ${this.expectedUuid}, got: ${error.audioUtteranceId})`
+                            `[RecogSDK:VGF] Skipping error update: UUID mismatch (expected: ${this.expectedUuid}, got: ${error.audioUtteranceId})`
                         );
                     }
-                    // Still call original callback if provided
-                    if (clientConfig.onError) {
-                        clientConfig.onError(error);
-                    }
+                    return;
+                }
+
+                // Skip if terminal status already sent for THIS session
+                if (this.lastSentTerminalUuid === this.expectedUuid) {
                     return;
                 }
 
@@ -362,6 +366,27 @@ export class SimplifiedVGFRecognitionClient implements ISimplifiedVGFRecognition
         this.isRecordingAudio = false;
         this.state = updateStateOnStop(this.state);
         this.notifyStateChange();
+
+        // Early termination: If transcription never started (NOT_STARTED), emit synthetic finalization immediately
+        // This prevents games from getting stuck waiting for a server response that may never come
+        if (this.state.transcriptionStatus === TranscriptionStatus.NOT_STARTED) {
+            if (this.logger) {
+                this.logger('info',
+                    `[RecogSDK:VGF] Early termination detected (transcriptionStatus: NOT_STARTED) - emitting synthetic finalization`
+                );
+            }
+            this.state = {
+                ...this.state,
+                transcriptionStatus: TranscriptionStatus.FINALIZED,
+                finalTranscript: '',
+                finalConfidence: 0,
+                pendingTranscript: '',
+                pendingConfidence: undefined,
+                finalTranscriptionTimestamp: new Date().toISOString()
+            };
+            this.notifyStateChange();
+        }
+
         await this.client.stopRecording();
     }
 
@@ -436,11 +461,34 @@ export class SimplifiedVGFRecognitionClient implements ISimplifiedVGFRecognition
         return { ...this.state };
     }
 
+    private isTerminalStatus(status: string | undefined): boolean {
+        return status === TranscriptionStatus.FINALIZED ||
+               status === TranscriptionStatus.ABORTED ||
+               status === TranscriptionStatus.ERROR;
+    }
+
     private notifyStateChange(): void {
-        // State has already been validated for correct UUID before this is called
-        if (this.stateChangeCallback) {
-            this.stateChangeCallback({ ...this.state });
+
+        // Block duplicate terminal status emissions for THIS session
+        if (this.isTerminalStatus(this.state.transcriptionStatus)) {
+            if (this.lastSentTerminalUuid === this.expectedUuid) {
+                // Already sent a terminal status for this session - suppress duplicate
+                if (this.logger) {
+                    this.logger('info',
+                        `[RecogSDK:VGF] Duplicate terminal status suppressed (lastSentTerminalUuid: ${this.lastSentTerminalUuid})`
+                    );
+                }
+                return;
+            }
+            // First terminal status for this session - record it
+            this.lastSentTerminalUuid = this.expectedUuid;
         }
+        
+        if (!this.stateChangeCallback) {
+            return;
+        }        
+
+        this.stateChangeCallback({ ...this.state });
     }
 }
 
@@ -489,4 +537,4 @@ export class SimplifiedVGFRecognitionClient implements ISimplifiedVGFRecognition
  */
 export function createSimplifiedVGFClient(config: SimplifiedVGFClientConfig): ISimplifiedVGFRecognitionClient {
     return new SimplifiedVGFRecognitionClient(config);
-}
+}

package/src/utils/audio-ring-buffer.ts

@@ -55,7 +55,7 @@ export class AudioRingBuffer {
 
       // Log buffer overflow event
       if (this.logger) {
-        this.logger('debug', 'Buffer overflow detected', {
+        this.logger('debug', '[RecogSDK] Buffer overflow detected', {
           bufferSize: this.bufferSize,
           totalOverflows: this.overflowCount,
           droppedChunk: this.buffer[this.readIndex]?.timestamp
@@ -151,7 +151,7 @@ export class AudioRingBuffer {
     this.totalBufferedBytes = 0;
 
     if (this.logger) {
-      this.logger('debug', 'Audio buffer cleared');
+      this.logger('debug', '[RecogSDK] Audio buffer cleared');
     }
   }
 

package/src/utils/message-handler.ts

@@ -44,7 +44,7 @@ export class MessageHandler {
   handleMessage(msg: { v: number; type: string; data: any }): void {
     // Log ALL incoming messages for debugging
     if (this.callbacks.logger) {
-      this.callbacks.logger('debug', 'Received WebSocket message', {
+      this.callbacks.logger('debug', '[RecogSDK] Received WebSocket message', {
         msgType: msg.type,
         msgDataType: msg.data && typeof msg.data === 'object' && 'type' in msg.data ? msg.data.type : 'N/A',
         fullMessage: msg
@@ -55,7 +55,7 @@ export class MessageHandler {
     // Log error if we receive primitive data (indicates server issue)
     if (msg.data && typeof msg.data !== 'object') {
       if (this.callbacks.logger) {
-        this.callbacks.logger('error', 'Received primitive msg.data from server', {
+        this.callbacks.logger('error', '[RecogSDK] Received primitive msg.data from server', {
           dataType: typeof msg.data,
           data: msg.data,
           fullMessage: msg
@@ -90,7 +90,7 @@ export class MessageHandler {
       default:
         // Unknown message type - log if logger available
         if (this.callbacks.logger) {
-          this.callbacks.logger('debug', 'Unknown message type', { type: msgType });
+          this.callbacks.logger('debug', '[RecogSDK] Unknown message type', { type: msgType });
         }
     }
   }
@@ -106,7 +106,7 @@ export class MessageHandler {
       const timeToFirstTranscript = this.firstTranscriptTime - this.sessionStartTime;
 
       if (this.callbacks.logger) {
-        this.callbacks.logger('debug', 'First transcript received', {
+        this.callbacks.logger('debug', '[RecogSDK] First transcript received', {
           timeToFirstTranscriptMs: timeToFirstTranscript
         });
       }

package/src/utils/url-builder.ts

@@ -19,6 +19,8 @@ export interface UrlBuilderConfig {
   questionAnswerId?: string;
   platform?: string;
   gameContext?: GameContextV1;
+  /** Standalone gameId - takes precedence over gameContext.gameId if both provided */
+  gameId?: string;
 }
 
 /**
@@ -75,9 +77,14 @@ export function buildWebSocketUrl(config: UrlBuilderConfig): string {
     url.searchParams.set('platform', config.platform);
   }
 
-  // Add gameId and gamePhase if provided from gameContext
-  if (config.gameContext) {
-    url.searchParams.set('gameId', config.gameContext.gameId);
+  // Add gameId - standalone gameId takes precedence over gameContext.gameId
+  const gameId = config.gameId ?? config.gameContext?.gameId;
+  if (gameId) {
+    url.searchParams.set('gameId', gameId);
+  }
+
+  // Add gamePhase from gameContext if provided
+  if (config.gameContext?.gamePhase) {
     url.searchParams.set('gamePhase', config.gameContext.gamePhase);
   }
 

package/src/vgf-recognition-mapper.ts

@@ -17,9 +17,7 @@ import {
 } from './recognition-client.types.js';
 import {
     TranscriptionResultV1,
-    MetadataResultV1,
-    ErrorResultV1,
-    ASRRequestConfig
+    ErrorResultV1
 } from '@recog/shared-types';
 
 /**
@@ -103,26 +101,6 @@ export function mapTranscriptionResultToState(
     return newState;
 }
 
-/**
- * Maps metadata result to update state timestamps
- */
-export function mapMetadataToState(
-    currentState: RecognitionState,
-    metadata: MetadataResultV1
-): RecognitionState {
-    const newState = { ...currentState };
-
-    // Update final recording timestamp when metadata arrives
-    if (!newState.finalRecordingTimestamp) {
-        newState.finalRecordingTimestamp = new Date().toISOString();
-    }
-
-    // Recording is finished when metadata arrives
-    newState.startRecordingStatus = RecordingStatus.FINISHED;
-
-    return newState;
-}
-
 /**
  * Maps error to state
  */