@volley/recognition-client-sdk-node22 0.1.424

package/src/utils/url-builder.ts

@@ -0,0 +1,92 @@
+/**
+ * URL Builder for Recognition Client
+ * Handles WebSocket URL construction with query parameters
+ */
+
+import { getRecognitionServiceBase } from '@recog/shared-config';
+import type { GameContextV1, Stage } from '@recog/shared-types';
+import type { RecognitionCallbackUrl } from '../recognition-client.types.js';
+
+export interface UrlBuilderConfig {
+  url?: string;
+  stage?: Stage | string;
+  audioUtteranceId: string;
+  callbackUrls?: RecognitionCallbackUrl[];
+  userId?: string;
+  gameSessionId?: string;
+  deviceId?: string;
+  accountId?: string;
+  questionAnswerId?: string;
+  platform?: string;
+  gameContext?: GameContextV1;
+  /** Standalone gameId - takes precedence over gameContext.gameId if both provided */
+  gameId?: string;
+}
+
+/**
+ * Build WebSocket URL with all query parameters
+ * Either `url` or `stage` must be provided (or defaults to production if neither provided)
+ * If both are provided, `url` takes precedence over `stage`
+ */
+export function buildWebSocketUrl(config: UrlBuilderConfig): string {
+  // Determine base URL based on precedence: url > stage > default production
+  let baseUrl: string;
+
+  if (config.url) {
+    // Explicit URL takes precedence
+    baseUrl = config.url;
+  } else if (config.stage) {
+    // Use stage to build URL
+    const stageBase = getRecognitionServiceBase(config.stage);
+    baseUrl = `${stageBase.wsBase}/ws/v1/recognize`;
+  } else {
+    // Default to production if neither provided
+    const defaultBase = getRecognitionServiceBase('production');
+    baseUrl = `${defaultBase.wsBase}/ws/v1/recognize`;
+  }
+
+  // Build URL - add all optional identification parameters
+  const url = new URL(baseUrl);
+
+  // Add audioUtteranceId as query parameter (required for server to recognize it)
+  url.searchParams.set('audioUtteranceId', config.audioUtteranceId);
+
+  // Add callback URLs if provided (for server-side notifications)
+  if (config.callbackUrls && config.callbackUrls.length > 0) {
+    // Serialize as JSON for complex structure
+    url.searchParams.set('callbackUrls', JSON.stringify(config.callbackUrls));
+  }
+
+  // Add user/session/device/account identification if provided
+  if (config.userId) {
+    url.searchParams.set('userId', config.userId);
+  }
+  if (config.gameSessionId) {
+    url.searchParams.set('gameSessionId', config.gameSessionId);
+  }
+  if (config.deviceId) {
+    url.searchParams.set('deviceId', config.deviceId);
+  }
+  if (config.accountId) {
+    url.searchParams.set('accountId', config.accountId);
+  }
+  if (config.questionAnswerId) {
+    url.searchParams.set('questionAnswerId', config.questionAnswerId);
+  }
+  if (config.platform) {
+    url.searchParams.set('platform', config.platform);
+  }
+
+  // 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);
+  }
+
+  return url.toString();
+}

package/src/vgf-recognition-mapper.spec.ts

@@ -0,0 +1,78 @@
+/**
+ * Unit tests for VGF Recognition Mapper functions
+ */
+
+import {
+    resetRecognitionVGFState
+} from './vgf-recognition-mapper.js';
+import {
+    RecognitionState,
+    RecordingStatus,
+    TranscriptionStatus,
+    RecognitionActionProcessingState
+} from './vgf-recognition-state.js';
+
+describe('resetRecognitionVGFState', () => {
+    it('should generate a new UUID', () => {
+        const originalState: RecognitionState = {
+            audioUtteranceId: 'old-uuid-123',
+            pendingTranscript: '',
+            transcriptionStatus: TranscriptionStatus.FINALIZED,
+            startRecordingStatus: RecordingStatus.FINISHED,
+            recognitionActionProcessingState: RecognitionActionProcessingState.COMPLETED,
+            finalTranscript: 'hello world'
+        };
+
+        const newState = resetRecognitionVGFState(originalState);
+
+        expect(newState.audioUtteranceId).not.toBe('old-uuid-123');
+        expect(newState.audioUtteranceId).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i);
+    });
+
+    it('should reset session-specific fields', () => {
+        const originalState: RecognitionState = {
+            audioUtteranceId: 'old-uuid-123',
+            pendingTranscript: 'partial',
+            transcriptionStatus: TranscriptionStatus.FINALIZED,
+            startRecordingStatus: RecordingStatus.FINISHED,
+            recognitionActionProcessingState: RecognitionActionProcessingState.COMPLETED,
+            finalTranscript: 'hello world'
+        };
+
+        const newState = resetRecognitionVGFState(originalState);
+
+        expect(newState.transcriptionStatus).toBe(TranscriptionStatus.NOT_STARTED);
+        expect(newState.startRecordingStatus).toBe(RecordingStatus.READY);
+        expect(newState.recognitionActionProcessingState).toBe(RecognitionActionProcessingState.NOT_STARTED);
+        expect(newState.finalTranscript).toBeUndefined();
+    });
+
+    it('should preserve non-session fields like promptSlotMap', () => {
+        const originalState: RecognitionState = {
+            audioUtteranceId: 'old-uuid-123',
+            pendingTranscript: '',
+            transcriptionStatus: TranscriptionStatus.FINALIZED,
+            promptSlotMap: { artist: ['taylor swift'], song: ['shake it off'] },
+            asrConfig: '{"provider":"deepgram"}'
+        };
+
+        const newState = resetRecognitionVGFState(originalState);
+
+        expect(newState.promptSlotMap).toEqual({ artist: ['taylor swift'], song: ['shake it off'] });
+        expect(newState.asrConfig).toBe('{"provider":"deepgram"}');
+    });
+
+    it('should work with minimal state', () => {
+        const originalState: RecognitionState = {
+            audioUtteranceId: 'old-uuid',
+            pendingTranscript: ''
+        };
+
+        const newState = resetRecognitionVGFState(originalState);
+
+        expect(newState.audioUtteranceId).not.toBe('old-uuid');
+        expect(newState.transcriptionStatus).toBe(TranscriptionStatus.NOT_STARTED);
+        expect(newState.startRecordingStatus).toBe(RecordingStatus.READY);
+        expect(newState.recognitionActionProcessingState).toBe(RecognitionActionProcessingState.NOT_STARTED);
+    });
+});

package/src/vgf-recognition-mapper.ts

@@ -0,0 +1,232 @@
+/**
+ * VGF Recognition Mapper
+ *
+ * Maps between the existing recognition client types and the simplified VGF state.
+ * This provides a clean abstraction layer for game developers.
+ */
+
+import {
+    RecognitionState,
+    RecordingStatus,
+    TranscriptionStatus,
+    RecognitionActionProcessingState,
+    createInitialRecognitionState
+} from './vgf-recognition-state.js';
+import { v4 as uuidv4 } from 'uuid';
+import {
+    ClientState,
+    IRecognitionClientConfig
+} from './recognition-client.types.js';
+import {
+    TranscriptionResultV1,
+    ErrorResultV1
+} from '@recog/shared-types';
+
+/**
+ * Maps ClientState to RecordingStatus for VGF state
+ */
+export function mapClientStateToRecordingStatus(clientState: ClientState): string {
+    switch (clientState) {
+        case ClientState.INITIAL:
+        case ClientState.CONNECTING:
+        case ClientState.CONNECTED:
+            return RecordingStatus.NOT_READY;
+
+        case ClientState.READY:
+            // Ready to record, but not recording yet
+            return RecordingStatus.READY;
+
+        case ClientState.STOPPING:
+        case ClientState.STOPPED:
+        case ClientState.FAILED:
+            return RecordingStatus.FINISHED;
+
+        default:
+            return RecordingStatus.NOT_READY;
+    }
+}
+
+/**
+ * Creates a VGF state from transcription result
+ */
+export function mapTranscriptionResultToState(
+    currentState: RecognitionState,
+    result: TranscriptionResultV1,
+    isRecording: boolean
+): RecognitionState {
+    const newState = { ...currentState };
+
+    // Update recording status if actively recording
+    if (isRecording && currentState.startRecordingStatus !== RecordingStatus.FINISHED) {
+        newState.startRecordingStatus = RecordingStatus.RECORDING;
+
+        // Set start timestamp on first audio
+        if (!newState.startRecordingTimestamp) {
+            newState.startRecordingTimestamp = new Date().toISOString();
+        }
+    }
+
+    // Update transcription status
+    if (!result.is_finished) {
+        // Has pending transcript - STEP 2 support
+        newState.transcriptionStatus = TranscriptionStatus.IN_PROGRESS;
+
+        // Direct copy of pending transcript without any combination
+        newState.pendingTranscript = result.pendingTranscript || "";
+
+        // Direct copy of pending confidence
+        if (result.pendingTranscriptConfidence !== undefined) {
+            newState.pendingConfidence = result.pendingTranscriptConfidence;
+        }
+
+        // Also update final transcript if we have it (even if not finished)
+        if (result.finalTranscript) {
+            newState.finalTranscript = result.finalTranscript;
+            if (result.finalTranscriptConfidence !== undefined) {
+                newState.finalConfidence = result.finalTranscriptConfidence;
+            }
+        }
+    } else {
+        // Transcription is finished
+        newState.transcriptionStatus = TranscriptionStatus.FINALIZED;
+        newState.finalTranscript = result.finalTranscript || "";
+        if (result.finalTranscriptConfidence !== undefined) {
+            newState.finalConfidence = result.finalTranscriptConfidence;
+        }
+        newState.finalTranscriptionTimestamp = new Date().toISOString();
+
+        // Clear pending when we have final
+        newState.pendingTranscript = "";
+        newState.pendingConfidence = undefined;
+    }
+
+    return newState;
+}
+
+/**
+ * Maps error to state
+ */
+export function mapErrorToState(
+    currentState: RecognitionState,
+    error: ErrorResultV1
+): RecognitionState {
+    return {
+        ...currentState,
+        transcriptionStatus: TranscriptionStatus.ERROR,
+        startRecordingStatus: RecordingStatus.FINISHED,
+        finalRecordingTimestamp: new Date().toISOString()
+    };
+}
+
+/**
+ * Creates initial VGF state from client config
+ */
+export function createVGFStateFromConfig(config: IRecognitionClientConfig): RecognitionState {
+    const audioUtteranceId = config.audioUtteranceId || generateUUID();
+    const state = createInitialRecognitionState(audioUtteranceId);
+
+    // Store ASR config as JSON if provided
+    if (config.asrRequestConfig) {
+        state.asrConfig = JSON.stringify(config.asrRequestConfig);
+    }
+
+    return state;
+}
+
+/**
+ * Updates state when recording stops
+ */
+export function updateStateOnStop(currentState: RecognitionState): RecognitionState {
+    return {
+        ...currentState,
+        startRecordingStatus: RecordingStatus.FINISHED,
+        finalRecordingTimestamp: new Date().toISOString()
+    };
+}
+
+/**
+ * Resets session state with a new UUID.
+ * 
+ * This creates a fresh session state while preserving non-session fields
+ * (like promptSlotMap, asrConfig, etc.)
+ * 
+ * Resets:
+ * - audioUtteranceId → new UUID
+ * - transcriptionStatus → NOT_STARTED
+ * - startRecordingStatus → READY
+ * - recognitionActionProcessingState → NOT_STARTED
+ * - finalTranscript → undefined
+ * 
+ * @param currentState - The current recognition state
+ * @returns A new state with reset session fields and a new UUID
+ */
+export function resetRecognitionVGFState(currentState: RecognitionState): RecognitionState {
+    return {
+        ...currentState,
+        audioUtteranceId: uuidv4(),
+        transcriptionStatus: TranscriptionStatus.NOT_STARTED,
+        startRecordingStatus: RecordingStatus.READY,
+        recognitionActionProcessingState: RecognitionActionProcessingState.NOT_STARTED,
+        finalTranscript: undefined
+    };
+}
+
+/**
+ * Updates state when client becomes ready
+ */
+export function updateStateOnReady(currentState: RecognitionState): RecognitionState {
+    return {
+        ...currentState,
+        startRecordingStatus: RecordingStatus.READY
+    };
+}
+
+/**
+ * Parses function call from transcript (STEP 3 support)
+ * This is a placeholder - actual implementation would use NLP/LLM
+ */
+export function extractFunctionCallFromTranscript(
+    transcript: string,
+    gameContext?: any
+): { metadata?: string; confidence?: number } | null {
+    // This would be replaced with actual function call extraction logic
+    // For example, using an LLM to parse intent from the transcript
+    // and map it to game actions
+
+    // Example stub implementation:
+    const lowerTranscript = transcript.toLowerCase();
+
+    // Simple pattern matching for demo
+    if (lowerTranscript.includes("play") && lowerTranscript.includes("artist")) {
+        return {
+            metadata: JSON.stringify({ action: "play", target: "artist" }),
+            confidence: 0.8
+        };
+    }
+
+    return null;
+}
+
+/**
+ * Updates state with function call results (STEP 3)
+ */
+export function updateStateWithFunctionCall(
+    currentState: RecognitionState,
+    functionCall: { metadata?: string; confidence?: number }
+): RecognitionState {
+    return {
+        ...currentState,
+        functionCallMetadata: functionCall.metadata,
+        functionCallConfidence: functionCall.confidence,
+        finalFunctionCallTimestamp: new Date().toISOString()
+    };
+}
+
+// Helper function to generate UUID (simplified version)
+function generateUUID(): string {
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
+        const r = Math.random() * 16 | 0;
+        const v = c === 'x' ? r : (r & 0x3 | 0x8);
+        return v.toString(16);
+    });
+}

package/src/vgf-recognition-state.ts

@@ -0,0 +1,102 @@
+import { z } from "zod"
+
+/**
+ * VGF-style state schema for game-side recognition state/results management.
+ *
+ * This schema provides a standardized way for game developers to manage
+ * voice recognition state and results in their applications. It supports:
+ *
+ * STEP 1: Basic transcription flow
+ * STEP 2: Mic auto-stop upon correct answer (using partial transcripts)
+ * STEP 3: Semantic/function-call outcomes for game actions
+ *
+ * Ideally this should be part of a more centralized shared type library to free
+ * game developers and provide helper functions (VGF? Platform SDK?).
+ */
+export const RecognitionVGFStateSchema = z.object({
+    // Core STT state
+    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", "ABORTED", "ERROR"
+    finalTranscript: z.string().optional(), // Full finalized transcript for the utterance. Will not change.
+    finalConfidence: z.number().optional(),
+
+    // Tracking-only metadata
+    asrConfig: z.string().optional(), // Json format of the ASR config
+    startRecordingTimestamp: z.string().optional(), // Start of recording. Immutable after set.
+    finalRecordingTimestamp: z.string().optional(), // End of recording. Immutable after set. Transcription may still be in progress.
+    finalTranscriptionTimestamp: z.string().optional(), // When the final transcript was produced. Immutable after set.
+
+    // STEP 2: Support for mic auto-stop upon correct answer
+    pendingTranscript: z.string().optional().default(""), // Non-final transcript that may change (matches existing naming)
+    pendingConfidence: z.number().optional(),
+
+    // STEP 3: Support for semantic/function-call outcomes
+    functionCallMetadata: z.string().optional(), // Function call metadata in JSON, e.g. "{artist: true, title: true}"
+    functionCallConfidence: z.number().optional(), // Confidence score for the function call.
+    finalFunctionCallTimestamp: z.string().optional(), // When the final action after interpreting the transcript was taken. Immutable.
+
+    // Support for prompt slot mapping - passed to recognition context when present
+    promptSlotMap: z.record(z.string(), z.array(z.string())).optional(), // Optional map of slot names to prompt values for recognition context
+
+    // Recognition action processing state - managed externally, SDK preserves but never modifies
+    recognitionActionProcessingState: z.string().optional(), // "NOT_STARTED", "IN_PROGRESS", "COMPLETED"
+})
+
+export type RecognitionState = z.infer<typeof RecognitionVGFStateSchema>
+
+// Status constants for better type safety and consistency
+export const RecordingStatus = {
+    NOT_READY: "NOT_READY",
+    READY: "READY",
+    RECORDING: "RECORDING",
+    FINISHED: "FINISHED",
+} as const
+
+export type RecordingStatusType = typeof RecordingStatus[keyof typeof RecordingStatus]
+
+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
+
+export type TranscriptionStatusType = typeof TranscriptionStatus[keyof typeof TranscriptionStatus]
+
+export const RecognitionActionProcessingState = {
+    NOT_STARTED: "NOT_STARTED",
+    IN_PROGRESS: "IN_PROGRESS",
+    COMPLETED: "COMPLETED",
+} as const
+
+export type RecognitionActionProcessingStateType = typeof RecognitionActionProcessingState[keyof typeof RecognitionActionProcessingState]
+
+// Helper function to create initial state
+export function createInitialRecognitionState(audioUtteranceId: string): RecognitionState {
+    return {
+        audioUtteranceId,
+        startRecordingStatus: RecordingStatus.NOT_READY,
+        transcriptionStatus: TranscriptionStatus.NOT_STARTED,
+        pendingTranscript: "",
+        recognitionActionProcessingState: RecognitionActionProcessingState.NOT_STARTED,
+    }
+}
+
+// Helper function to validate state transitions
+export function isValidRecordingStatusTransition(from: string | undefined, to: string): boolean {
+    const statusOrder = [
+        RecordingStatus.NOT_READY,
+        RecordingStatus.READY,
+        RecordingStatus.RECORDING,
+        RecordingStatus.FINISHED,
+    ]
+
+    const fromIndex = from ? statusOrder.indexOf(from as RecordingStatusType) : -1
+    const toIndex = statusOrder.indexOf(to as RecordingStatusType)
+
+    // Can only move forward in the status order
+    return toIndex > fromIndex && toIndex !== -1
+}