@volley/recognition-client-sdk-node22 0.1.424

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

@@ -0,0 +1,524 @@
+/**
+ * Simplified VGF Recognition Client
+ *
+ * A thin wrapper around RealTimeTwoWayWebSocketRecognitionClient that maintains
+ * a VGF RecognitionState as a pure sink/output of recognition events.
+ *
+ * The VGF state is updated based on events but never influences client behavior.
+ * All functionality is delegated to the underlying client.
+ */
+
+import {
+    RecognitionState,
+    TranscriptionStatus,
+    RecordingStatus,
+    RecognitionActionProcessingState
+} from './vgf-recognition-state.js';
+import {
+    IRecognitionClient,
+    IRecognitionClientConfig,
+    ClientState
+} from './recognition-client.types.js';
+import { RealTimeTwoWayWebSocketRecognitionClient } from './recognition-client.js';
+import {
+    createVGFStateFromConfig,
+    mapTranscriptionResultToState,
+    mapErrorToState,
+    updateStateOnStop,
+    resetRecognitionVGFState
+} from './vgf-recognition-mapper.js';
+import { RecognitionContextTypeV1 } from '@recog/shared-types';
+
+/**
+ * Configuration for SimplifiedVGFRecognitionClient
+ */
+export interface SimplifiedVGFClientConfig extends IRecognitionClientConfig {
+    /**
+     * Callback invoked whenever the VGF state changes
+     * Use this to update your UI or React state
+     */
+    onStateChange?: (state: RecognitionState) => void;
+
+    /**
+     * Optional initial state to restore from a previous session
+     * If provided, audioUtteranceId will be extracted and used
+     */
+    initialState?: RecognitionState;
+}
+
+/**
+ * Interface for SimplifiedVGFRecognitionClient
+ *
+ * A simplified client that maintains VGF state for game developers.
+ * All methods from the underlying client are available, plus VGF state management.
+ */
+export interface ISimplifiedVGFRecognitionClient {
+    // ============= Core Connection Methods =============
+    /**
+     * Connect to the recognition service WebSocket
+     * @returns Promise that resolves when connected and ready
+     */
+    connect(): Promise<void>;
+
+    /**
+     * Send audio data for transcription
+     * @param audioData - PCM audio data as ArrayBuffer, typed array, or Blob
+     */
+    sendAudio(audioData: ArrayBuffer | ArrayBufferView | Blob): void;
+
+    /**
+     * Stop recording and wait for final transcription
+     * @returns Promise that resolves when transcription is complete
+     */
+    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
+     * @returns Current RecognitionState with all transcription data
+     */
+    getVGFState(): RecognitionState;
+
+    // ============= Status Check Methods =============
+    /**
+     * Check if connected to the WebSocket
+     */
+    isConnected(): boolean;
+
+    /**
+     * Check if currently connecting
+     */
+    isConnecting(): boolean;
+
+    /**
+     * Check if currently stopping
+     */
+    isStopping(): boolean;
+
+    /**
+     * Check if transcription has finished
+     */
+    isTranscriptionFinished(): boolean;
+
+    /**
+     * Check if the audio buffer has overflowed
+     */
+    isBufferOverflowing(): boolean;
+
+    // ============= Utility Methods =============
+    /**
+     * Get the audio utterance ID for this session
+     */
+    getAudioUtteranceId(): string;
+
+    /**
+     * Get the WebSocket URL being used
+     */
+    getUrl(): string;
+
+    /**
+     * Get the underlying client state (for advanced usage)
+     */
+    getState(): ClientState;
+
+}
+
+/**
+ * This wrapper ONLY maintains VGF state as a sink.
+ * All actual functionality is delegated to the underlying client.
+ */
+export class SimplifiedVGFRecognitionClient implements ISimplifiedVGFRecognitionClient {
+    private client: IRecognitionClient;
+    private state: RecognitionState;
+    private isRecordingAudio: boolean = false;
+    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;
+        this.stateChangeCallback = onStateChange;
+        this.logger = clientConfig.logger;
+
+        // Use provided initial state or create from config
+        if (initialState) {
+            // Check if initial state has a valid UUID
+            const needsNewUuid = !initialState.audioUtteranceId ||
+                                initialState.audioUtteranceId === '' ||
+                                initialState.transcriptionStatus === TranscriptionStatus.ABORTED ||
+                                initialState.transcriptionStatus === TranscriptionStatus.FINALIZED ||
+                                initialState.transcriptionStatus === TranscriptionStatus.ERROR ||
+                                (initialState.recognitionActionProcessingState !== undefined && initialState.recognitionActionProcessingState !== RecognitionActionProcessingState.COMPLETED);
+            if (needsNewUuid) {
+                // Reset session state with new UUID
+                this.state = resetRecognitionVGFState(initialState);
+                const newUUID = this.state.audioUtteranceId;
+
+                if (clientConfig.logger) {
+                    const reason = !initialState.audioUtteranceId ? 'Missing UUID' :
+                                 initialState.audioUtteranceId === '' ? 'Empty UUID' :
+                                 `Terminal session (${initialState.transcriptionStatus})`;
+                    clientConfig.logger('info', `${reason} detected, generating new UUID: ${newUUID}`);
+                }
+
+                // 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);
+                }
+            } else {
+                // Non-terminal state with valid UUID - safe to reuse (e.g., reconnecting to IN_PROGRESS session)
+                this.state = initialState;
+                // Override audioUtteranceId in config if state has one
+                if (initialState.audioUtteranceId && !clientConfig.audioUtteranceId) {
+                    clientConfig.audioUtteranceId = initialState.audioUtteranceId;
+                }
+            }
+        } else {
+            // Initialize VGF state from config
+            this.state = createVGFStateFromConfig(clientConfig);
+            // Ensure clientConfig uses the same UUID as VGF state
+            clientConfig.audioUtteranceId = this.state.audioUtteranceId;
+        }
+
+        // Client is immediately ready to accept audio (will buffer if not connected)
+        this.state = { ...this.state, startRecordingStatus: 'READY' };
+
+        // Track the expected UUID for this session
+        this.expectedUuid = this.state.audioUtteranceId;
+
+        // If VGF state has promptSlotMap, configure gameContext to use it
+        if (this.state.promptSlotMap) {
+            // Set useContext=true in ASR config to enable context processing
+            if (clientConfig.asrRequestConfig) {
+                clientConfig.asrRequestConfig.useContext = true;
+            }
+
+            // Add promptSlotMap to gameContext
+            if (!clientConfig.gameContext) {
+                // Only create gameContext if we have gameId and gamePhase
+                // These should come from the game's configuration
+                if (clientConfig.logger) {
+                    clientConfig.logger('warn', '[VGF] promptSlotMap found but no gameContext provided. SlotMap will not be sent.');
+                }
+            } else {
+                // Merge promptSlotMap into existing gameContext
+                clientConfig.gameContext.slotMap = this.state.promptSlotMap;
+            }
+        }
+
+        // Create underlying client with callbacks that ONLY update VGF state
+        this.client = new RealTimeTwoWayWebSocketRecognitionClient({
+            ...clientConfig,
+
+            // These callbacks ONLY update the VGF state sink
+            onTranscript: (result) => {
+                // Skip update if UUID doesn't match (stale callback from previous session)
+                if (result.audioUtteranceId && result.audioUtteranceId !== this.expectedUuid) {
+                    if (this.logger) {
+                        this.logger('warn',
+                            `[RecogSDK:VGF] Skipping transcript update: UUID mismatch (expected: ${this.expectedUuid}, got: ${result.audioUtteranceId})`
+                        );
+                    }
+                    return;
+                }
+
+                // Update VGF state based on transcript (always update local state)
+                this.state = mapTranscriptionResultToState(this.state, result, this.isRecordingAudio);
+                this.notifyStateChange();
+
+                // Call original callback if provided
+                if (clientConfig.onTranscript) {
+                    clientConfig.onTranscript(result);
+                }
+            },
+
+            onMetadata: (metadata) => {
+                // Skip update if UUID doesn't match (stale callback from previous session)
+                if (metadata.audioUtteranceId && metadata.audioUtteranceId !== this.expectedUuid) {
+                    if (this.logger) {
+                        this.logger('warn',
+                            `[RecogSDK:VGF] Skipping metadata update: UUID mismatch (expected: ${this.expectedUuid}, got: ${metadata.audioUtteranceId})`
+                        );
+                    }
+                    return;
+                }
+
+                if (clientConfig.onMetadata) {
+                    clientConfig.onMetadata(metadata);
+                }
+            },
+
+            onFunctionCall: (result) => {
+                // Pass through function call - no VGF state changes needed for P2 feature
+                if (clientConfig.onFunctionCall) {
+                    clientConfig.onFunctionCall(result);
+                }
+            },
+
+            onError: (error) => {
+                // Skip update if UUID doesn't match (stale callback from previous session)
+                if (error.audioUtteranceId && error.audioUtteranceId !== this.expectedUuid) {
+                    if (this.logger) {
+                        this.logger('warn',
+                            `[RecogSDK:VGF] Skipping error update: UUID mismatch (expected: ${this.expectedUuid}, got: ${error.audioUtteranceId})`
+                        );
+                    }
+                    return;
+                }
+
+                this.isRecordingAudio = false; // Reset on error
+                this.state = mapErrorToState(this.state, error);
+                this.notifyStateChange();
+
+                if (clientConfig.onError) {
+                    clientConfig.onError(error);
+                }
+            },
+
+            onConnected: () => {
+                // Don't update READY here - client can accept audio before connection
+                if (clientConfig.onConnected) {
+                    clientConfig.onConnected();
+                }
+            },
+
+            onDisconnected: (code, reason) => {
+                this.isRecordingAudio = false; // Reset on disconnect
+                if (clientConfig.onDisconnected) {
+                    clientConfig.onDisconnected(code, reason);
+                }
+            }
+        });
+    }
+
+    // DELEGATE ALL METHODS TO UNDERLYING CLIENT
+    // The wrapper ONLY updates VGF state, doesn't use it for decisions
+
+    async connect(): Promise<void> {
+        await this.client.connect();
+        // State will be updated via onConnected callback
+    }
+
+    sendAudio(audioData: ArrayBuffer | ArrayBufferView | Blob): void {
+        // Track recording for state updates
+        if (!this.isRecordingAudio) {
+            this.isRecordingAudio = true;
+            this.state = {
+                ...this.state,
+                startRecordingStatus: 'RECORDING',
+                startRecordingTimestamp: new Date().toISOString()
+            };
+            this.notifyStateChange();
+        }
+        this.client.sendAudio(audioData);
+    }
+
+    async stopRecording(): Promise<void> {
+        this.isRecordingAudio = false;
+        this.state = updateStateOnStop(this.state);
+        this.notifyStateChange();
+
+        // Early termination: If connection is not yet established with server, emit synthetic finalization immediately
+        // This prevents games from getting stuck waiting for a server response that may never come
+        if (this.client.getState() === ClientState.CONNECTED || this.client.getState() === ClientState.CONNECTING) {
+            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();
+    }
+
+    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();
+    }
+
+    getUrl(): string {
+        return this.client.getUrl();
+    }
+
+    getState(): ClientState {
+        return this.client.getState();
+    }
+
+    isConnected(): boolean {
+        return this.client.isConnected();
+    }
+
+    isConnecting(): boolean {
+        return this.client.isConnecting();
+    }
+
+    isStopping(): boolean {
+        return this.client.isStopping();
+    }
+
+    isTranscriptionFinished(): boolean {
+        return this.client.isTranscriptionFinished();
+    }
+
+    isBufferOverflowing(): boolean {
+        return this.client.isBufferOverflowing();
+    }
+
+
+    // VGF State access (read-only for consumers)
+    getVGFState(): RecognitionState {
+        return { ...this.state };
+    }
+
+    private isTerminalStatus(status: string | undefined): boolean {
+        return status === TranscriptionStatus.FINALIZED ||
+               status === TranscriptionStatus.ABORTED ||
+               status === TranscriptionStatus.ERROR;
+    }
+
+    private notifyStateChange(): void {
+
+        // 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})`,
+                        { transcriptionStatus: this.state.transcriptionStatus, finalTranscript: this.state.finalTranscript }
+                    );
+                }
+                return;
+            }
+            // First terminal status for this session - record it
+            this.lastSentTerminalUuid = this.expectedUuid;
+            if (this.logger) {
+                this.logger('info',
+                    `[RecogSDK:VGF] Sending terminal status (uuid: ${this.expectedUuid})`,
+                    { transcriptionStatus: this.state.transcriptionStatus, finalTranscript: this.state.finalTranscript }
+                );
+            }
+        }
+        
+        if (!this.stateChangeCallback) {
+            return;
+        }        
+
+        this.stateChangeCallback({ ...this.state });
+    }
+}
+
+/**
+ * Factory function for creating simplified client
+ * Usage examples:
+ *
+ * // Basic usage
+ * const client = createSimplifiedVGFClient({
+ *   asrRequestConfig: { provider: 'deepgram', language: 'en' },
+ *   onStateChange: (state) => {
+ *     console.log('VGF State updated:', state);
+ *     // Update React state, game UI, etc.
+ *   }
+ * });
+ *
+ * // With initial state (e.g., restoring from previous session)
+ * const client = createSimplifiedVGFClient({
+ *   asrRequestConfig: { provider: 'deepgram', language: 'en' },
+ *   initialState: previousState, // Will use audioUtteranceId from state
+ *   onStateChange: (state) => setVGFState(state)
+ * });
+ *
+ * // With initial state containing promptSlotMap for enhanced recognition
+ * const stateWithSlots: RecognitionState = {
+ *   audioUtteranceId: 'session-123',
+ *   promptSlotMap: {
+ *     'song_title': ['one time', 'baby'],
+ *     'artists': ['justin bieber']
+ *   }
+ * };
+ * const client = createSimplifiedVGFClient({
+ *   asrRequestConfig: { provider: 'deepgram', language: 'en' },
+ *   gameContext: {
+ *     type: RecognitionContextTypeV1.GAME_CONTEXT,
+ *     gameId: 'music-quiz',  // Your game's ID
+ *     gamePhase: 'song-guessing'  // Current game phase
+ *   },
+ *   initialState: stateWithSlots, // promptSlotMap will be added to gameContext
+ *   onStateChange: (state) => setVGFState(state)
+ * });
+ *
+ * await client.connect();
+ * client.sendAudio(audioData);
+ * // VGF state automatically updates based on transcription results
+ */
+export function createSimplifiedVGFClient(config: SimplifiedVGFClientConfig): ISimplifiedVGFRecognitionClient {
+    return new SimplifiedVGFRecognitionClient(config);
+}