@volley/recognition-client-sdk-node22 0.1.424

package/dist/recognition-client.d.ts

@@ -0,0 +1,128 @@
+/**
+ * RealTimeTwoWayWebSocketRecognitionClient - Clean, compact SDK for real-time speech recognition
+ *
+ * Features:
+ * - Ring buffer-based audio storage with fixed memory footprint
+ * - Automatic buffering when disconnected, immediate send when connected
+ * - Buffer persists after flush (for future retry/reconnection scenarios)
+ * - Built on WebSocketAudioClient for robust protocol handling
+ * - Simple API: connect() → sendAudio() → stopRecording()
+ * - Type-safe message handling with callbacks
+ * - Automatic backpressure management
+ * - Overflow detection with buffer state tracking
+ *
+ * Example:
+ * ```typescript
+ * const client = new RealTimeTwoWayWebSocketRecognitionClient({
+ *   url: 'ws://localhost:3101/ws/v1/recognize',
+ *   onTranscript: (result) => console.log(result.finalTranscript),
+ *   onError: (error) => console.error(error),
+ *   maxBufferDurationSec: 60  // Ring buffer for 60 seconds
+ * });
+ *
+ * await client.connect();
+ *
+ * // Send audio chunks - always stored in ring buffer, sent if connected
+ * micStream.on('data', (chunk) => client.sendAudio(chunk));
+ *
+ * // Signal end of audio and wait for final results
+ * await client.stopRecording();
+ *
+ * // Server will close connection after sending finals
+ * // No manual cleanup needed - browser handles it
+ * ```
+ */
+import { WebSocketAudioClient } from '@recog/websocket';
+import { type TranscriptionResultV1 } from '@recog/shared-types';
+import { ClientState } from './recognition-client.types.js';
+import type { IRecognitionClient, IRecognitionClientStats, RealTimeTwoWayWebSocketRecognitionClientConfig } from './recognition-client.types.js';
+/**
+ * Check if a WebSocket close code indicates normal closure
+ * @param code - WebSocket close code
+ * @returns true if the disconnection was normal/expected, false if it was an error
+ */
+export declare function isNormalDisconnection(code: number): boolean;
+/**
+ * Re-export TranscriptionResultV1 as TranscriptionResult for backward compatibility
+ */
+export type TranscriptionResult = TranscriptionResultV1;
+export type { RealTimeTwoWayWebSocketRecognitionClientConfig } from './recognition-client.types.js';
+/**
+ * RealTimeTwoWayWebSocketRecognitionClient - SDK-level client for real-time speech recognition
+ *
+ * Implements IRecognitionClient interface for dependency injection and testing.
+ * Extends WebSocketAudioClient with local audio buffering and simple callback-based API.
+ */
+export declare class RealTimeTwoWayWebSocketRecognitionClient extends WebSocketAudioClient<number, any, any> implements IRecognitionClient {
+    private static readonly PROTOCOL_VERSION;
+    private config;
+    private audioBuffer;
+    private messageHandler;
+    private state;
+    private connectionPromise;
+    private isDebugLogEnabled;
+    private audioBytesSent;
+    private audioChunksSent;
+    private audioStatsLogInterval;
+    private lastAudioStatsLog;
+    constructor(config: RealTimeTwoWayWebSocketRecognitionClientConfig);
+    /**
+     * Internal logging helper - only logs if a logger was provided in config
+     * Debug logs are additionally gated by isDebugLogEnabled flag
+     * @param level - Log level: debug, info, warn, or error
+     * @param message - Message to log
+     * @param data - Optional additional data to log
+     */
+    private log;
+    /**
+     * Clean up internal resources to free memory
+     * Called when connection closes (normally or abnormally)
+     */
+    private cleanup;
+    connect(): Promise<void>;
+    /**
+     * Attempt to connect with retry logic
+     * Only retries on initial connection establishment, not mid-stream interruptions
+     */
+    private connectWithRetry;
+    sendAudio(audioData: ArrayBuffer | ArrayBufferView | Blob): void;
+    private sendAudioInternal;
+    /**
+     * Only active ehwne client is in READY state. otherwise it will return immediately.
+     * @returns Promise that resolves when the recording is stopped
+     */
+    stopRecording(): Promise<void>;
+    stopAbnormally(): void;
+    getAudioUtteranceId(): string;
+    getUrl(): string;
+    getState(): ClientState;
+    isConnected(): boolean;
+    isConnecting(): boolean;
+    isStopping(): boolean;
+    isTranscriptionFinished(): boolean;
+    isBufferOverflowing(): boolean;
+    getStats(): IRecognitionClientStats;
+    protected onConnected(): void;
+    protected onDisconnected(code: number, reason: string): void;
+    /**
+     * Get human-readable description for WebSocket close code
+     */
+    private getCloseCodeDescription;
+    protected onError(error: Event): void;
+    protected onMessage(msg: {
+        v: number;
+        type: string;
+        data: any;
+    }): void;
+    /**
+     * Handle control messages from server
+     * @param msg - Control message containing server actions
+     */
+    private handleControlMessage;
+    /**
+     * Send audio immediately to the server (without buffering)
+     * @param audioData - Audio data to send
+     */
+    private sendAudioNow;
+}
+//# sourceMappingURL=recognition-client.d.ts.map

package/dist/recognition-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recognition-client.d.ts","sourceRoot":"","sources":["../src/recognition-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EAML,KAAK,qBAAqB,EAS3B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAC5D,OAAO,KAAK,EACV,kBAAkB,EAClB,uBAAuB,EACvB,8CAA8C,EAE/C,MAAM,+BAA+B,CAAC;AAUvC;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE3D;AAgCD;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,qBAAqB,CAAC;AAGxD,YAAY,EAAE,8CAA8C,EAAE,MAAM,+BAA+B,CAAC;AAgCpG;;;;;GAKG;AACH,qBAAa,wCACX,SAAQ,oBAAoB,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,CAC7C,YAAW,kBAAkB;IAE7B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAK;IAE7C,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,WAAW,CAAkB;IACrC,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,KAAK,CAAoC;IACjD,OAAO,CAAC,iBAAiB,CAA4B;IAGrD,OAAO,CAAC,iBAAiB,CAAS;IAGlC,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,qBAAqB,CAAO;IACpC,OAAO,CAAC,iBAAiB,CAAK;gBAElB,MAAM,EAAE,8CAA8C;IA+ElE;;;;;;OAMG;IACH,OAAO,CAAC,GAAG;IAWX;;;OAGG;IACH,OAAO,CAAC,OAAO;IAmBA,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA6BvC;;;OAGG;YACW,gBAAgB;IAkIrB,SAAS,CAAC,SAAS,EAAE,WAAW,GAAG,eAAe,GAAG,IAAI,GAAG,IAAI;IAiBzE,OAAO,CAAC,iBAAiB;IAsCzB;;;OAGG;IAEG,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAoCpC,cAAc,IAAI,IAAI;IAwBtB,mBAAmB,IAAI,MAAM;IAI7B,MAAM,IAAI,MAAM;IAIhB,QAAQ,IAAI,WAAW;IAIvB,WAAW,IAAI,OAAO;IAItB,YAAY,IAAI,OAAO;IAIvB,UAAU,IAAI,OAAO;IAIrB,uBAAuB,IAAI,OAAO;IAIlC,mBAAmB,IAAI,OAAO;IAI9B,QAAQ,IAAI,uBAAuB;IAgBnC,SAAS,CAAC,WAAW,IAAI,IAAI;IAsE7B,SAAS,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IA8C5D;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAwB/B,SAAS,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;cAYlB,SAAS,CAAC,GAAG,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,GAAG,CAAA;KAAE,GAAG,IAAI;IAQ/E;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAyB5B;;;OAGG;IACH,OAAO,CAAC,YAAY;CAuBrB"}

package/dist/recognition-client.types.d.ts

@@ -0,0 +1,271 @@
+/**
+ * Recognition Client Types
+ *
+ * Type definitions and interfaces for the recognition client SDK.
+ * These interfaces enable dependency injection, testing, and alternative implementations.
+ */
+import { TranscriptionResultV1, FunctionCallResultV1, MetadataResultV1, ErrorResultV1, ASRRequestConfig, GameContextV1, Stage } from '@recog/shared-types';
+/**
+ * Client connection state enum
+ * Represents the various states a recognition client can be in during its lifecycle
+ */
+export declare enum ClientState {
+    /** Initial state, no connection established */
+    INITIAL = "initial",
+    /** Actively establishing WebSocket connection */
+    CONNECTING = "connecting",
+    /** WebSocket connected but waiting for server ready signal */
+    CONNECTED = "connected",
+    /** Server ready, can send audio */
+    READY = "ready",
+    /** Sent stop signal, waiting for final transcript */
+    STOPPING = "stopping",
+    /** Connection closed normally after stop */
+    STOPPED = "stopped",
+    /** Connection failed or lost unexpectedly */
+    FAILED = "failed"
+}
+/**
+ * Callback URL configuration with message type filtering
+ */
+export interface RecognitionCallbackUrl {
+    /** The callback URL endpoint */
+    url: string;
+    /** Array of message types to send to this URL. If empty/undefined, all types are sent */
+    messageTypes?: Array<string | number>;
+}
+export type IRecognitionCallbackUrl = RecognitionCallbackUrl;
+export interface IRecognitionClientConfig {
+    /**
+     * WebSocket endpoint URL (optional)
+     * Either `url` or `stage` must be provided.
+     * If both are provided, `url` takes precedence.
+     *
+     * Example with explicit URL:
+     * ```typescript
+     * { url: 'wss://custom-endpoint.example.com/ws/v1/recognize' }
+     * ```
+     */
+    url?: string;
+    /**
+     * Stage for recognition service (recommended)
+     * Either `url` or `stage` must be provided.
+     * If both are provided, `url` takes precedence.
+     * Defaults to production if neither is provided.
+     *
+     * Example with STAGES enum (recommended):
+     * ```typescript
+     * import { STAGES } from '@recog/shared-types';
+     * { stage: STAGES.STAGING }
+     * ```
+     *
+     * String values also accepted:
+     * ```typescript
+     * { stage: 'staging' }  // STAGES.LOCAL | STAGES.DEV | STAGES.STAGING | STAGES.PRODUCTION
+     * ```
+     */
+    stage?: Stage | string;
+    /** ASR configuration (provider, model, language, etc.) - optional */
+    asrRequestConfig?: ASRRequestConfig;
+    /** Game context for improved recognition accuracy */
+    gameContext?: GameContextV1;
+    /**
+     * Game ID for tracking and routing purposes (optional)
+     * If provided, this is added to the WebSocket URL as a query parameter.
+     * If gameContext is also provided, this takes precedence over gameContext.gameId.
+     */
+    gameId?: string;
+    /** Audio utterance ID (optional) - if not provided, a UUID v4 will be generated */
+    audioUtteranceId?: string;
+    /** Callback URLs for server-side notifications with optional message type filtering (optional)
+     *  Game side only need to use it if another service need to be notified about the transcription results.
+     */
+    callbackUrls?: RecognitionCallbackUrl[];
+    /** User identification (optional) */
+    userId?: string;
+    /** Game session identification (optional). called 'sessionId' in Platform and most games. */
+    gameSessionId?: string;
+    /** Device identification (optional) */
+    deviceId?: string;
+    /** Account identification (optional) */
+    accountId?: string;
+    /** Question answer identifier for tracking Q&A sessions (optional and tracking purpose only) */
+    questionAnswerId?: string;
+    /** Platform for audio recording device (optional, e.g., 'ios', 'android', 'web', 'unity') */
+    platform?: string;
+    /** Callback when transcript is received */
+    onTranscript?: (result: TranscriptionResultV1) => void;
+    /**
+     * Callback when function call is received
+     * Note: Not supported in 2025. P2 feature for future speech-to-function-call capability.
+     */
+    onFunctionCall?: (result: FunctionCallResultV1) => void;
+    /** Callback when metadata is received. Only once after transcription is complete.*/
+    onMetadata?: (metadata: MetadataResultV1) => void;
+    /** Callback when error occurs */
+    onError?: (error: ErrorResultV1) => void;
+    /** Callback when connected to WebSocket */
+    onConnected?: () => void;
+    /**
+     * Callback when WebSocket disconnects
+     * @param code - WebSocket close code (1000 = normal, 1006 = abnormal, etc.)
+     * @param reason - Close reason string
+     */
+    onDisconnected?: (code: number, reason: string) => void;
+    /** High water mark for backpressure control (bytes) */
+    highWaterMark?: number;
+    /** Low water mark for backpressure control (bytes) */
+    lowWaterMark?: number;
+    /** Maximum buffer duration in seconds (default: 60s) */
+    maxBufferDurationSec?: number;
+    /** Expected chunks per second for ring buffer sizing (default: 100) */
+    chunksPerSecond?: number;
+    /**
+     * Connection retry configuration (optional)
+     * Only applies to initial connection establishment, not mid-stream interruptions.
+     *
+     * Default: { maxAttempts: 4, delayMs: 200 } (try once, retry 3 times = 4 total attempts)
+     *
+     * Timing: Attempt 1 → FAIL → wait 200ms → Attempt 2 → FAIL → wait 200ms → Attempt 3 → FAIL → wait 200ms → Attempt 4
+     *
+     * Example:
+     * ```typescript
+     * {
+     *   connectionRetry: {
+     *     maxAttempts: 2,  // Try connecting up to 2 times (1 retry)
+     *     delayMs: 500     // Wait 500ms between attempts
+     *   }
+     * }
+     * ```
+     */
+    connectionRetry?: {
+        /** Maximum number of connection attempts (default: 4, min: 1, max: 5) */
+        maxAttempts?: number;
+        /** Delay in milliseconds between retry attempts (default: 200ms) */
+        delayMs?: number;
+    };
+    /**
+     * Optional logger function for debugging
+     * If not provided, no logging will occur
+     * @param level - Log level: 'debug', 'info', 'warn', 'error'
+     * @param message - Log message
+     * @param data - Optional additional data
+     */
+    logger?: (level: 'debug' | 'info' | 'warn' | 'error', message: string, data?: any) => void;
+}
+/**
+ * Recognition Client Interface
+ *
+ * Main interface for real-time speech recognition clients.
+ * Provides methods for connection management, audio streaming, and session control.
+ */
+export interface IRecognitionClient {
+    /**
+     * Connect to the WebSocket endpoint
+     * @returns Promise that resolves when connected
+     * @throws Error if connection fails or times out
+     */
+    connect(): Promise<void>;
+    /**
+     * Send audio data to the recognition service
+     * Audio is buffered locally and sent when connection is ready.
+     * @param audioData - PCM audio data as ArrayBuffer, typed array view, or Blob
+     */
+    sendAudio(audioData: ArrayBuffer | ArrayBufferView | Blob): void;
+    /**
+     * Stop recording and wait for final transcript
+     * The server will close the connection after sending the final transcript.
+     * @returns Promise that resolves when final transcript is received
+     */
+    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
+     * - Immediately closes WebSocket connection
+     * - Cleans up resources (buffers, listeners)
+     *
+     * Use Cases:
+     * - User explicitly cancels/abandons 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;
+    /**
+     * Get the audio utterance ID for this session
+     * Available immediately after client construction.
+     * @returns UUID v4 string identifying this recognition session
+     */
+    getAudioUtteranceId(): string;
+    /**
+     * Get the current state of the client
+     * @returns Current ClientState value
+     */
+    getState(): ClientState;
+    /**
+     * Check if WebSocket connection is open
+     * @returns true if connected and ready to communicate
+     */
+    isConnected(): boolean;
+    /**
+     * Check if client is currently connecting
+     * @returns true if connection is in progress
+     */
+    isConnecting(): boolean;
+    /**
+     * Check if client is currently stopping
+     * @returns true if stopRecording() is in progress
+     */
+    isStopping(): boolean;
+    /**
+     * Check if transcription has finished
+     * @returns true if the transcription is complete
+     */
+    isTranscriptionFinished(): boolean;
+    /**
+     * Check if the audio buffer has overflowed
+     * @returns true if the ring buffer has wrapped around
+     */
+    isBufferOverflowing(): boolean;
+    /**
+     * Get client statistics
+     * @returns Statistics about audio transmission and buffering
+     */
+    getStats(): IRecognitionClientStats;
+    /**
+     * Get the WebSocket URL being used by this client
+     * Available immediately after client construction.
+     * @returns WebSocket URL string
+     */
+    getUrl(): string;
+}
+/**
+ * Client statistics interface
+ */
+export interface IRecognitionClientStats {
+    /** Total audio bytes sent to server */
+    audioBytesSent: number;
+    /** Total number of audio chunks sent */
+    audioChunksSent: number;
+    /** Total number of audio chunks buffered */
+    audioChunksBuffered: number;
+    /** Number of times the ring buffer overflowed */
+    bufferOverflowCount: number;
+    /** Current number of chunks in buffer */
+    currentBufferedChunks: number;
+    /** Whether the ring buffer has wrapped (overwritten old data) */
+    hasWrapped: boolean;
+}
+/**
+ * Configuration for RealTimeTwoWayWebSocketRecognitionClient
+ * This extends IRecognitionClientConfig and is the main configuration interface
+ * for creating a new RealTimeTwoWayWebSocketRecognitionClient instance.
+ */
+export interface RealTimeTwoWayWebSocketRecognitionClientConfig extends IRecognitionClientConfig {
+}
+//# sourceMappingURL=recognition-client.types.d.ts.map

package/dist/recognition-client.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recognition-client.types.d.ts","sourceRoot":"","sources":["../src/recognition-client.types.ts"],"names":[],"mappings":"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"}

package/dist/simplified-vgf-recognition-client.d.ts

@@ -0,0 +1,178 @@
+/**
+ * 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 } from './vgf-recognition-state.js';
+import { IRecognitionClientConfig, ClientState } from './recognition-client.types.js';
+/**
+ * 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 {
+    /**
+     * 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;
+    /**
+     * Get the current VGF recognition state
+     * @returns Current RecognitionState with all transcription data
+     */
+    getVGFState(): RecognitionState;
+    /**
+     * 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;
+    /**
+     * 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 declare class SimplifiedVGFRecognitionClient implements ISimplifiedVGFRecognitionClient {
+    private client;
+    private state;
+    private isRecordingAudio;
+    private stateChangeCallback;
+    private expectedUuid;
+    private logger;
+    private lastSentTerminalUuid;
+    constructor(config: SimplifiedVGFClientConfig);
+    connect(): Promise<void>;
+    sendAudio(audioData: ArrayBuffer | ArrayBufferView | Blob): void;
+    stopRecording(): Promise<void>;
+    stopAbnormally(): void;
+    getAudioUtteranceId(): string;
+    getUrl(): string;
+    getState(): ClientState;
+    isConnected(): boolean;
+    isConnecting(): boolean;
+    isStopping(): boolean;
+    isTranscriptionFinished(): boolean;
+    isBufferOverflowing(): boolean;
+    getVGFState(): RecognitionState;
+    private isTerminalStatus;
+    private notifyStateChange;
+}
+/**
+ * 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 declare function createSimplifiedVGFClient(config: SimplifiedVGFClientConfig): ISimplifiedVGFRecognitionClient;
+//# sourceMappingURL=simplified-vgf-recognition-client.d.ts.map

package/dist/simplified-vgf-recognition-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"simplified-vgf-recognition-client.d.ts","sourceRoot":"","sources":["../src/simplified-vgf-recognition-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACH,gBAAgB,EAInB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAEH,wBAAwB,EACxB,WAAW,EACd,MAAM,+BAA+B,CAAC;AAWvC;;GAEG;AACH,MAAM,WAAW,yBAA0B,SAAQ,wBAAwB;IACvE;;;OAGG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAElD;;;OAGG;IACH,YAAY,CAAC,EAAE,gBAAgB,CAAC;CACnC;AAED;;;;;GAKG;AACH,MAAM,WAAW,+BAA+B;IAE5C;;;OAGG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzB;;;OAGG;IACH,SAAS,CAAC,SAAS,EAAE,WAAW,GAAG,eAAe,GAAG,IAAI,GAAG,IAAI,CAAC;IAEjE;;;OAGG;IACH,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/B;;;;;;;;;;;;;;;;OAgBG;IACH,cAAc,IAAI,IAAI,CAAC;IAGvB;;;OAGG;IACH,WAAW,IAAI,gBAAgB,CAAC;IAGhC;;OAEG;IACH,WAAW,IAAI,OAAO,CAAC;IAEvB;;OAEG;IACH,YAAY,IAAI,OAAO,CAAC;IAExB;;OAEG;IACH,UAAU,IAAI,OAAO,CAAC;IAEtB;;OAEG;IACH,uBAAuB,IAAI,OAAO,CAAC;IAEnC;;OAEG;IACH,mBAAmB,IAAI,OAAO,CAAC;IAG/B;;OAEG;IACH,mBAAmB,IAAI,MAAM,CAAC;IAE9B;;OAEG;IACH,MAAM,IAAI,MAAM,CAAC;IAEjB;;OAEG;IACH,QAAQ,IAAI,WAAW,CAAC;CAE3B;AAED;;;GAGG;AACH,qBAAa,8BAA+B,YAAW,+BAA+B;IAClF,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,KAAK,CAAmB;IAChC,OAAO,CAAC,gBAAgB,CAAkB;IAC1C,OAAO,CAAC,mBAAmB,CAAkD;IAC7E,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,MAAM,CAAqC;IACnD,OAAO,CAAC,oBAAoB,CAAuB;gBAEvC,MAAM,EAAE,yBAAyB;IAqKvC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAK9B,SAAS,CAAC,SAAS,EAAE,WAAW,GAAG,eAAe,GAAG,IAAI,GAAG,IAAI;IAc1D,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IA4BpC,cAAc,IAAI,IAAI;IAiCtB,mBAAmB,IAAI,MAAM;IAI7B,MAAM,IAAI,MAAM;IAIhB,QAAQ,IAAI,WAAW;IAIvB,WAAW,IAAI,OAAO;IAItB,YAAY,IAAI,OAAO;IAIvB,UAAU,IAAI,OAAO;IAIrB,uBAAuB,IAAI,OAAO;IAIlC,mBAAmB,IAAI,OAAO;IAM9B,WAAW,IAAI,gBAAgB;IAI/B,OAAO,CAAC,gBAAgB;IAMxB,OAAO,CAAC,iBAAiB;CA8B5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,yBAAyB,GAAG,+BAA+B,CAE5G"}

package/dist/utils/audio-ring-buffer.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Audio Ring Buffer
+ * Manages circular buffer for audio data with overflow detection
+ */
+export interface BufferedAudio {
+    data: ArrayBuffer | ArrayBufferView;
+    timestamp: number;
+}
+export interface AudioRingBufferConfig {
+    maxBufferDurationSec: number;
+    chunksPerSecond: number;
+    logger?: (level: 'debug' | 'info' | 'warn' | 'error', message: string, data?: any) => void;
+}
+export declare class AudioRingBuffer {
+    private buffer;
+    private bufferSize;
+    private writeIndex;
+    private readIndex;
+    private hasWrapped;
+    private totalBufferedBytes;
+    private overflowCount;
+    private chunksBuffered;
+    private logger?;
+    constructor(config: AudioRingBufferConfig);
+    /**
+     * Write audio chunk to ring buffer with overflow detection
+     */
+    write(audioData: ArrayBuffer | ArrayBufferView): void;
+    /**
+     * Read next chunk from buffer
+     */
+    read(): BufferedAudio | null;
+    /**
+     * Read all buffered chunks without removing them
+     */
+    readAll(): BufferedAudio[];
+    /**
+     * Flush all buffered data and advance read pointer
+     */
+    flush(): BufferedAudio[];
+    /**
+     * Get count of buffered chunks
+     */
+    getBufferedCount(): number;
+    /**
+     * Check if buffer is empty
+     */
+    isEmpty(): boolean;
+    /**
+     * Check if buffer has overflowed
+     */
+    isOverflowing(): boolean;
+    /**
+     * Clear the buffer and reset all counters
+     * Frees memory by releasing all stored audio chunks
+     */
+    clear(): void;
+    /**
+     * Get buffer statistics
+     */
+    getStats(): {
+        chunksBuffered: number;
+        currentBufferedChunks: number;
+        overflowCount: number;
+        hasWrapped: boolean;
+        totalBufferedBytes: number;
+    };
+}
+//# sourceMappingURL=audio-ring-buffer.d.ts.map

package/dist/utils/audio-ring-buffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio-ring-buffer.d.ts","sourceRoot":"","sources":["../../src/utils/audio-ring-buffer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,WAAW,GAAG,eAAe,CAAC;IACpC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,oBAAoB,EAAE,MAAM,CAAC;IAC7B,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,KAAK,IAAI,CAAC;CAC5F;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,kBAAkB,CAAK;IAC/B,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,MAAM,CAAC,CAAoF;gBAEvF,MAAM,EAAE,qBAAqB;IAQzC;;OAEG;IACH,KAAK,CAAC,SAAS,EAAE,WAAW,GAAG,eAAe,GAAG,IAAI;IAmCrD;;OAEG;IACH,IAAI,IAAI,aAAa,GAAG,IAAI;IAU5B;;OAEG;IACH,OAAO,IAAI,aAAa,EAAE;IAe1B;;OAEG;IACH,KAAK,IAAI,aAAa,EAAE;IAMxB;;OAEG;IACH,gBAAgB,IAAI,MAAM;IAS1B;;OAEG;IACH,OAAO,IAAI,OAAO;IAIlB;;OAEG;IACH,aAAa,IAAI,OAAO;IAIxB;;;OAGG;IACH,KAAK,IAAI,IAAI;IAcb;;OAEG;IACH,QAAQ;;;;;;;CAST"}