@volley/recognition-client-sdk/src/config-builder.ts

Recognition Service TypeScript/Node.js Client SDK

/**
 * 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 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;
  }
}