@volley/recognition-client-sdk-node22 0.1.424

package/src/config-builder.ts

@@ -0,0 +1,240 @@
+/**
+ * Configuration Builder for Recognition Client
+ *
+ * Simple builder pattern for RealTimeTwoWayWebSocketRecognitionClientConfig
+ */
+
+import type {
+  RealTimeTwoWayWebSocketRecognitionClientConfig,
+  RecognitionCallbackUrl
+} from './recognition-client.types.js';
+import type {
+  ASRRequestConfig,
+  GameContextV1,
+  TranscriptionResultV1,
+  MetadataResultV1,
+  ErrorResultV1,
+  Stage
+} from '@recog/shared-types';
+
+/**
+ * Builder for RealTimeTwoWayWebSocketRecognitionClientConfig
+ *
+ * Provides a fluent API for building client configurations.
+ *
+ * Example:
+ * ```typescript
+ * import { STAGES } from '@recog/shared-types';
+ *
+ * const config = new ConfigBuilder()
+ *   .stage(STAGES.STAGING)  // Recommended: automatic environment selection
+ *   .asrRequestConfig({
+ *     provider: RecognitionProvider.DEEPGRAM,
+ *     model: 'nova-2-general'
+ *   })
+ *   .onTranscript((result) => console.log(result))
+ *   .build();
+ * ```
+ */
+export class ConfigBuilder {
+  private config: Partial<RealTimeTwoWayWebSocketRecognitionClientConfig> = {};
+
+  /**
+   * Set the WebSocket URL (advanced usage)
+   * For standard environments, use stage() instead
+   */
+  url(url: string): this {
+    this.config.url = url;
+    return this;
+  }
+
+  /**
+   * Set the stage for automatic environment selection (recommended)
+   * @param stage - STAGES.LOCAL | STAGES.DEV | STAGES.STAGING | STAGES.PRODUCTION
+   * @example
+   * ```typescript
+   * import { STAGES } from '@recog/shared-types';
+   * builder.stage(STAGES.STAGING)
+   * ```
+   */
+  stage(stage: Stage | string): this {
+    this.config.stage = stage;
+    return this;
+  }
+
+  /**
+   * Set ASR request configuration
+   */
+  asrRequestConfig(config: ASRRequestConfig): this {
+    this.config.asrRequestConfig = config;
+    return this;
+  }
+
+  /**
+   * Set game context
+   */
+  gameContext(context: GameContextV1): this {
+    this.config.gameContext = context;
+    return this;
+  }
+
+  /**
+   * Set game ID directly (takes precedence over gameContext.gameId)
+   * Use this when you only need to identify the game without full context.
+   */
+  gameId(id: string): this {
+    this.config.gameId = id;
+    return this;
+  }
+
+  /**
+   * Set audio utterance ID
+   */
+  audioUtteranceId(id: string): this {
+    this.config.audioUtteranceId = id;
+    return this;
+  }
+
+  /**
+   * Set callback URLs
+   */
+  callbackUrls(urls: RecognitionCallbackUrl[]): this {
+    this.config.callbackUrls = urls;
+    return this;
+  }
+
+  /**
+   * Set user ID
+   */
+  userId(id: string): this {
+    this.config.userId = id;
+    return this;
+  }
+
+  /**
+   * Set game session ID
+   */
+  gameSessionId(id: string): this {
+    this.config.gameSessionId = id;
+    return this;
+  }
+
+  /**
+   * Set device ID
+   */
+  deviceId(id: string): this {
+    this.config.deviceId = id;
+    return this;
+  }
+
+  /**
+   * Set account ID
+   */
+  accountId(id: string): this {
+    this.config.accountId = id;
+    return this;
+  }
+
+  /**
+   * Set question answer ID
+   */
+  questionAnswerId(id: string): this {
+    this.config.questionAnswerId = id;
+    return this;
+  }
+
+  /**
+   * Set platform
+   */
+  platform(platform: string): this {
+    this.config.platform = platform;
+    return this;
+  }
+
+  /**
+   * Set transcript callback
+   */
+  onTranscript(callback: (result: TranscriptionResultV1) => void): this {
+    this.config.onTranscript = callback;
+    return this;
+  }
+
+  /**
+   * Set metadata callback
+   */
+  onMetadata(callback: (metadata: MetadataResultV1) => void): this {
+    this.config.onMetadata = callback;
+    return this;
+  }
+
+  /**
+   * Set error callback
+   */
+  onError(callback: (error: ErrorResultV1) => void): this {
+    this.config.onError = callback;
+    return this;
+  }
+
+  /**
+   * Set connected callback
+   */
+  onConnected(callback: () => void): this {
+    this.config.onConnected = callback;
+    return this;
+  }
+
+  /**
+   * Set disconnected callback
+   */
+  onDisconnected(callback: (code: number, reason: string) => void): this {
+    this.config.onDisconnected = callback;
+    return this;
+  }
+
+  /**
+   * Set high water mark
+   */
+  highWaterMark(bytes: number): this {
+    this.config.highWaterMark = bytes;
+    return this;
+  }
+
+  /**
+   * Set low water mark
+   */
+  lowWaterMark(bytes: number): this {
+    this.config.lowWaterMark = bytes;
+    return this;
+  }
+
+  /**
+   * Set max buffer duration in seconds
+   */
+  maxBufferDurationSec(seconds: number): this {
+    this.config.maxBufferDurationSec = seconds;
+    return this;
+  }
+
+  /**
+   * Set chunks per second
+   */
+  chunksPerSecond(chunks: number): this {
+    this.config.chunksPerSecond = chunks;
+    return this;
+  }
+
+  /**
+   * Set logger function
+   */
+  logger(logger: (level: 'debug' | 'info' | 'warn' | 'error', message: string, data?: any) => void): this {
+    this.config.logger = logger;
+    return this;
+  }
+
+  /**
+   * Build the configuration
+   */
+  build(): RealTimeTwoWayWebSocketRecognitionClientConfig {
+    return this.config as RealTimeTwoWayWebSocketRecognitionClientConfig;
+  }
+}

package/src/errors.ts

@@ -0,0 +1,84 @@
+/**
+ * SDK Error Classes
+ *
+ * Typed error classes that extend native Error with recognition-specific metadata
+ */
+
+import { ErrorTypeV1 } from '@recog/shared-types';
+
+/**
+ * Base class for all recognition SDK errors
+ */
+export class RecognitionError extends Error {
+  public readonly errorType: ErrorTypeV1;
+  public readonly timestamp: number;
+
+  constructor(errorType: ErrorTypeV1, message: string) {
+    super(message);
+    this.name = 'RecognitionError';
+    this.errorType = errorType;
+    this.timestamp = Date.now();
+
+    // Maintains proper stack trace for where error was thrown (only available on V8)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+}
+
+/**
+ * Connection error - thrown when WebSocket connection fails after all retry attempts
+ */
+export class ConnectionError extends RecognitionError {
+  public readonly attempts: number;
+  public readonly url: string;
+  public readonly underlyingError?: Error;
+
+  constructor(message: string, attempts: number, url: string, underlyingError?: Error) {
+    super(ErrorTypeV1.CONNECTION_ERROR, message);
+    this.name = 'ConnectionError';
+    this.attempts = attempts;
+    this.url = url;
+    if (underlyingError !== undefined) {
+      this.underlyingError = underlyingError;
+    }
+  }
+}
+
+/**
+ * Timeout error - thrown when operations exceed timeout limits
+ */
+export class TimeoutError extends RecognitionError {
+  public readonly timeoutMs: number;
+  public readonly operation: string;
+
+  constructor(message: string, timeoutMs: number, operation: string) {
+    super(ErrorTypeV1.TIMEOUT_ERROR, message);
+    this.name = 'TimeoutError';
+    this.timeoutMs = timeoutMs;
+    this.operation = operation;
+  }
+}
+
+/**
+ * Validation error - thrown when invalid configuration or input is provided
+ */
+export class ValidationError extends RecognitionError {
+  public readonly field?: string;
+  public readonly expected?: string;
+  public readonly received?: string;
+
+  constructor(message: string, field?: string, expected?: string, received?: string) {
+    super(ErrorTypeV1.VALIDATION_ERROR, message);
+    this.name = 'ValidationError';
+    if (field !== undefined) {
+      this.field = field;
+    }
+    if (expected !== undefined) {
+      this.expected = expected;
+    }
+    if (received !== undefined) {
+      this.received = received;
+    }
+  }
+}

package/src/factory.spec.ts

@@ -0,0 +1,215 @@
+/**
+ * Unit tests for Factory functions
+ */
+
+import { createClient, createClientWithBuilder } from './factory.js';
+import { ConfigBuilder } from './config-builder.js';
+import { RecognitionProvider, RecognitionContextTypeV1 } from '@recog/shared-types';
+
+// Mock the RealTimeTwoWayWebSocketRecognitionClient
+jest.mock('./recognition-client.js', () => ({
+  RealTimeTwoWayWebSocketRecognitionClient: jest.fn().mockImplementation((config) => ({
+    config,
+    connect: jest.fn(),
+    disconnect: jest.fn(),
+    sendAudio: jest.fn(),
+    startRecognition: jest.fn(),
+    stopRecognition: jest.fn()
+  }))
+}));
+
+describe('Factory Functions', () => {
+  describe('createClient', () => {
+    it('should create client with config object', () => {
+      const config = {
+        url: 'ws://localhost:3101/ws/v1/recognize',
+        audioUtteranceId: 'test-id',
+        asrRequestConfig: {
+          provider: RecognitionProvider.DEEPGRAM,
+          model: 'nova-2-general',
+          language: 'en-US',
+          sampleRate: 16000,
+          encoding: 'linear16'
+        }
+      };
+
+      const client = createClient(config);
+      expect(client).toBeDefined();
+      expect(client.connect).toBeDefined();
+      expect(client.sendAudio).toBeDefined();
+    });
+
+    it('should create client with minimal config', () => {
+      const config = {
+        url: 'ws://localhost:3101/ws/v1/recognize',
+        audioUtteranceId: 'test-id'
+      };
+
+      const client = createClient(config);
+      expect(client).toBeDefined();
+    });
+
+    it('should create client with callbacks', () => {
+      const onTranscript = jest.fn();
+      const onError = jest.fn();
+      const onConnected = jest.fn();
+
+      const config = {
+        url: 'ws://localhost:3101/ws/v1/recognize',
+        audioUtteranceId: 'test-id',
+        onTranscript,
+        onError,
+        onConnected
+      };
+
+      const client = createClient(config);
+      expect(client).toBeDefined();
+    });
+  });
+
+  describe('createClientWithBuilder', () => {
+    it('should create client using builder pattern', () => {
+      const client = createClientWithBuilder((builder) =>
+        builder
+          .url('ws://localhost:3101/ws/v1/recognize')
+          .audioUtteranceId('test-id')
+      );
+
+      expect(client).toBeDefined();
+      expect(client.connect).toBeDefined();
+    });
+
+    it('should create client with multiple builder methods', () => {
+      const onTranscript = jest.fn();
+      const onError = jest.fn();
+
+      const client = createClientWithBuilder((builder) =>
+        builder
+          .url('ws://localhost:3101/ws/v1/recognize')
+          .audioUtteranceId('test-id')
+          .userId('user-123')
+          .gameSessionId('session-456')
+          .onTranscript(onTranscript)
+          .onError(onError)
+      );
+
+      expect(client).toBeDefined();
+    });
+
+    it('should create client with ASR config via builder', () => {
+      const client = createClientWithBuilder((builder) =>
+        builder
+          .url('ws://localhost:3101/ws/v1/recognize')
+          .audioUtteranceId('test-id')
+          .asrRequestConfig({
+            provider: RecognitionProvider.DEEPGRAM,
+            model: 'nova-2-general',
+            language: 'en-US',
+            sampleRate: 16000,
+            encoding: 'linear16'
+          })
+      );
+
+      expect(client).toBeDefined();
+    });
+
+    it('should create client with game context via builder', () => {
+      const client = createClientWithBuilder((builder) =>
+        builder
+          .url('ws://localhost:3101/ws/v1/recognize')
+          .audioUtteranceId('test-id')
+          .gameContext({
+            type: RecognitionContextTypeV1.GAME_CONTEXT as const,
+            gameId: 'test-game',
+            gamePhase: 'test-phase'
+          })
+      );
+
+      expect(client).toBeDefined();
+    });
+
+    it('should create client with all optional fields via builder', () => {
+      const onTranscript = jest.fn();
+      const onMetadata = jest.fn();
+      const onError = jest.fn();
+      const onConnected = jest.fn();
+      const onDisconnected = jest.fn();
+      const logger = jest.fn();
+
+      const client = createClientWithBuilder((builder) =>
+        builder
+          .url('ws://localhost:3101/ws/v1/recognize')
+          .audioUtteranceId('test-id')
+          .userId('user-123')
+          .gameSessionId('session-456')
+          .deviceId('device-789')
+          .accountId('account-abc')
+          .questionAnswerId('qa-xyz')
+          .platform('ios')
+          .asrRequestConfig({
+            provider: RecognitionProvider.DEEPGRAM,
+            model: 'nova-2-general',
+            language: 'en-US',
+            sampleRate: 16000,
+            encoding: 'linear16'
+          })
+          .gameContext({
+            type: RecognitionContextTypeV1.GAME_CONTEXT as const,
+            gameId: 'test-game',
+            gamePhase: 'test-phase'
+          })
+          .onTranscript(onTranscript)
+          .onMetadata(onMetadata)
+          .onError(onError)
+          .onConnected(onConnected)
+          .onDisconnected(onDisconnected)
+          .highWaterMark(1000)
+          .lowWaterMark(500)
+          .maxBufferDurationSec(10)
+          .chunksPerSecond(50)
+          .logger(logger)
+      );
+
+      expect(client).toBeDefined();
+    });
+
+    it('should accept builder as parameter', () => {
+      const builder = new ConfigBuilder();
+      const client = createClientWithBuilder((b) => b.url('ws://localhost:3101').audioUtteranceId('test-id'));
+      expect(client).toBeDefined();
+    });
+  });
+
+  describe('Factory Function Equivalence', () => {
+    it('should produce equivalent clients from config and builder', () => {
+      const config = {
+        url: 'ws://localhost:3101/ws/v1/recognize',
+        audioUtteranceId: 'test-id',
+        userId: 'user-123'
+      };
+
+      const clientFromConfig = createClient(config);
+      const clientFromBuilder = createClientWithBuilder((builder) =>
+        builder
+          .url('ws://localhost:3101/ws/v1/recognize')
+          .audioUtteranceId('test-id')
+          .userId('user-123')
+      );
+
+      expect(clientFromConfig).toBeDefined();
+      expect(clientFromBuilder).toBeDefined();
+    });
+
+    it('should handle empty config gracefully', () => {
+      const config = {
+        url: 'ws://localhost:3101/ws/v1/recognize',
+        audioUtteranceId: 'test-id'
+      };
+
+      const client = createClient(config);
+      expect(client).toBeDefined();
+      expect(typeof client.connect).toBe('function');
+    });
+
+  });
+});

package/src/factory.ts

@@ -0,0 +1,47 @@
+/**
+ * Factory function for creating Recognition Client instances
+ */
+
+import { RealTimeTwoWayWebSocketRecognitionClient } from './recognition-client.js';
+import { ConfigBuilder } from './config-builder.js';
+import type { IRecognitionClient, RealTimeTwoWayWebSocketRecognitionClientConfig } from './recognition-client.types.js';
+
+/**
+ * Create a recognition client from a configuration object
+ *
+ * Example:
+ * ```typescript
+ * const client = createClient({
+ *   url: 'ws://localhost:3101/ws/v1/recognize',
+ *   audioUtteranceId: 'unique-id',
+ *   onTranscript: (result) => console.log(result)
+ * });
+ * ```
+ *
+ * @param config - Client configuration
+ * @returns Configured recognition client instance
+ */
+export function createClient(config: RealTimeTwoWayWebSocketRecognitionClientConfig): IRecognitionClient {
+  return new RealTimeTwoWayWebSocketRecognitionClient(config);
+}
+
+/**
+ * Create a recognition client using the builder pattern
+ *
+ * Example:
+ * ```typescript
+ * const client = createClientWithBuilder((builder) =>
+ *   builder
+ *     .url('ws://localhost:3101/ws/v1/recognize')
+ *     .onTranscript((result) => console.log(result))
+ *     .onError((error) => console.error(error))
+ * );
+ * ```
+ */
+export function createClientWithBuilder(
+  configure: (builder: ConfigBuilder) => ConfigBuilder
+): IRecognitionClient {
+  const builder = new ConfigBuilder();
+  const config = configure(builder).build();
+  return new RealTimeTwoWayWebSocketRecognitionClient(config);
+}

package/src/index.ts

@@ -0,0 +1,127 @@
+// Export RealTimeTwoWayWebSocketRecognitionClient (primary SDK)
+export {
+  RealTimeTwoWayWebSocketRecognitionClient,
+  type RealTimeTwoWayWebSocketRecognitionClientConfig,
+  type TranscriptionResult,
+  isNormalDisconnection
+} from './recognition-client.js';
+
+// Export interfaces for dependency injection and testing
+export {
+  type IRecognitionClient,
+  type IRecognitionClientConfig,
+  type IRecognitionClientStats,
+  type RecognitionCallbackUrl,
+  ClientState
+} from './recognition-client.types.js';
+
+// Export configuration builder
+export { ConfigBuilder } from './config-builder.js';
+
+// Export factory functions
+export { createClient, createClientWithBuilder } from './factory.js';
+
+// Export error classes
+export {
+  RecognitionError,
+  ConnectionError,
+  TimeoutError,
+  ValidationError
+} from './errors.js';
+
+// Export error types from shared-types
+export { ErrorTypeV1 } from '@recog/shared-types';
+
+// Export error exception types for advanced error handling
+export type {
+  RecognitionException,
+  ConnectionException,
+  TimeoutException,
+  ValidationException,
+  AuthenticationException,
+  ProviderException,
+  QuotaExceededException,
+  UnknownException
+} from '@recog/shared-types';
+
+// Export error helper functions
+export {
+  isExceptionImmediatelyAvailable,
+  getUserFriendlyMessage
+} from '@recog/shared-types';
+
+// Export VGF state management (new simplified interface)
+export {
+  SimplifiedVGFRecognitionClient,
+  createSimplifiedVGFClient,
+  type ISimplifiedVGFRecognitionClient,
+  type SimplifiedVGFClientConfig
+} from './simplified-vgf-recognition-client.js';
+
+export {
+  type RecognitionState,
+  RecognitionVGFStateSchema,
+  RecordingStatus,
+  TranscriptionStatus,
+  type RecordingStatusType,
+  type TranscriptionStatusType,
+  createInitialRecognitionState,
+  isValidRecordingStatusTransition
+} from './vgf-recognition-state.js';
+
+export { resetRecognitionVGFState } from './vgf-recognition-mapper.js';
+
+// Re-export WebSocket protocol types for advanced usage
+export { AudioEncoding } from '@recog/websocket';
+
+// Re-export necessary types from shared-types
+export {
+  // Recognition context types
+  type GameContextV1,
+  type SlotMap,
+  RecognitionContextTypeV1,
+  ControlSignalTypeV1,
+  ControlSignalTypeV1 as ControlSignal,  // Alias for backward compatibility
+
+  // Result types
+  type TranscriptionResultV1,
+  type FunctionCallResultV1,
+  type MetadataResultV1,
+  type ErrorResultV1,
+  RecognitionResultTypeV1,
+  ClientControlActionV1,
+
+  // ASR configuration types
+  type ASRRequestConfig,
+  type ASRRequestV1,
+  FinalTranscriptStability,
+  createDefaultASRConfig,
+  RecognitionProvider,
+  DeepgramModel,
+  ElevenLabsModel,
+  FireworksModel,
+  GoogleModel,
+  GeminiModel,
+  OpenAIModel,
+  Language,
+  SampleRate,
+
+  // Stage/Environment types
+  STAGES,
+  type Stage
+} from '@recog/shared-types';
+
+// Re-export shared config helpers so consumers don't depend on internal package
+export {
+  getRecognitionServiceBase,
+  getRecognitionServiceHttpBase,
+  getRecognitionServiceWsBase,
+  getRecognitionServiceHost,
+  getRecognitionConductorBase,
+  getRecognitionConductorHttpBase,
+  getRecognitionConductorWsBase,
+  getRecognitionConductorHost,
+  normalizeStage,
+  RECOGNITION_SERVICE_BASES,
+  RECOGNITION_CONDUCTOR_BASES
+} from '@recog/shared-config';