@volley/recognition-client-sdk 0.1.200

package/src/recognition-client.types.ts

@@ -0,0 +1,260 @@
+/**
+ * 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
+} from '@recog/shared-types';
+
+/**
+ * Client connection state enum
+ * Represents the various states a recognition client can be in during its lifecycle
+ */
+export 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>;
+}
+
+// Legacy alias for backward compatibility
+export type IRecognitionCallbackUrl = RecognitionCallbackUrl;
+
+export interface IRecognitionClientConfig {
+  /**
+   * WebSocket endpoint URL (optional - defaults to production)
+   *
+   * For different stages, use the helper function:
+   * ```typescript
+   * import { getRecognitionServiceBase } from '@recog/client-sdk-ts';
+   * const base = getRecognitionServiceBase('staging'); // or 'dev', 'production'
+   * const url = `${base.wsBase}/ws/v1/recognize`;
+   * ```
+   */
+  url?: string;
+
+  /** ASR configuration (provider, model, language, etc.) - optional */
+  asrRequestConfig?: ASRRequestConfig;
+
+  /** Game context for improved recognition accuracy */
+  gameContext?: GameContextV1;
+
+  /** 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;
+
+  /**
+   * 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 or typed array view
+   */
+  sendAudio(audioData: ArrayBuffer | ArrayBufferView): 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>;
+
+  /**
+   * 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;
+}
+
+/**
+ * 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 {
+  // All fields are inherited from IRecognitionClientConfig
+  // This interface exists for backward compatibility and clarity
+}
+