@volley/recognition-client-sdk 0.1.211 → 0.1.254

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volley/recognition-client-sdk",
-  "version": "0.1.211",
+  "version": "0.1.254",
   "description": "Recognition Service TypeScript/Node.js Client SDK",
   "type": "module",
   "main": "dist/index.js",
@@ -53,9 +53,9 @@
     "ts-jest": "^29.4.5",
     "tsup": "^8.5.0",
     "typescript": "^5.1.6",
+    "@recog/shared-types": "1.0.0",
     "@recog/shared-config": "1.0.0",
     "@recog/websocket": "1.0.0",
-    "@recog/shared-types": "1.0.0",
     "@recog/shared-utils": "1.0.0"
   },
   "keywords": [

package/src/config-builder.ts

@@ -13,7 +13,8 @@ import type {
   GameContextV1,
   TranscriptionResultV1,
   MetadataResultV1,
-  ErrorResultV1
+  ErrorResultV1,
+  Stage
 } from '@recog/shared-types';
 
 /**
@@ -23,8 +24,10 @@ import type {
  *
  * Example:
  * ```typescript
+ * import { STAGES } from '@recog/shared-types';
+ *
  * const config = new ConfigBuilder()
- *   .url('ws://localhost:3101/ws/v1/recognize')
+ *   .stage(STAGES.STAGING)  // Recommended: automatic environment selection
  *   .asrRequestConfig({
  *     provider: RecognitionProvider.DEEPGRAM,
  *     model: 'nova-2-general'
@@ -37,13 +40,28 @@ export class ConfigBuilder {
   private config: Partial<RealTimeTwoWayWebSocketRecognitionClientConfig> = {};
 
   /**
-   * Set the WebSocket URL
+   * 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
    */

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/index.ts

@@ -21,6 +21,35 @@ 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,
@@ -67,7 +96,11 @@ export {
   GeminiModel,
   OpenAIModel,
   Language,
-  SampleRate
+  SampleRate,
+
+  // Stage/Environment types
+  STAGES,
+  type Stage
 } from '@recog/shared-types';
 
 // Re-export shared config helpers so consumers don't depend on internal package

package/src/recognition-client.spec.ts

@@ -60,6 +60,45 @@ describe('RealTimeTwoWayWebSocketRecognitionClient', () => {
       expect(client.getAudioUtteranceId()).toBe(originalId);
     });
 
+    it('should expose the WebSocket URL via getUrl()', () => {
+      const url = client.getUrl();
+      expect(url).toBeDefined();
+      expect(typeof url).toBe('string');
+      expect(url).toContain('audioUtteranceId=');
+    });
+
+    it('should build URL from stage parameter', () => {
+      const stagingClient = new RealTimeTwoWayWebSocketRecognitionClient({
+        stage: 'staging',
+        asrRequestConfig: {
+          provider: 'deepgram',
+          language: 'en',
+          sampleRate: 16000,
+          encoding: 'linear16'
+        }
+      });
+      const url = stagingClient.getUrl();
+      expect(url).toBeDefined();
+      // URL should be built from stage (exact URL depends on mocked getRecognitionServiceBase)
+      expect(url).toContain('/ws/v1/recognize');
+    });
+
+    it('should prioritize url over stage when both provided', () => {
+      const explicitUrlClient = new RealTimeTwoWayWebSocketRecognitionClient({
+        url: 'ws://custom.example.com/ws/v1/recognize',
+        stage: 'staging',
+        asrRequestConfig: {
+          provider: 'deepgram',
+          language: 'en',
+          sampleRate: 16000,
+          encoding: 'linear16'
+        }
+      });
+      const url = explicitUrlClient.getUrl();
+      expect(url).toContain('ws://custom.example.com/ws/v1/recognize');
+      expect(url).not.toContain('staging');
+    });
+
     it('should initialize stats correctly', () => {
       const stats = client.getStats();
       expect(stats.audioBytesSent).toBe(0);

package/src/recognition-client.ts

@@ -61,6 +61,7 @@ import type {
 import { buildWebSocketUrl } from './utils/url-builder.js';
 import { AudioRingBuffer } from './utils/audio-ring-buffer.js';
 import { MessageHandler } from './utils/message-handler.js';
+import { ConnectionError } from './errors.js';
 
 // ============================================================================
 // UTILITIES
@@ -132,6 +133,10 @@ interface InternalConfig {
   lowWaterMark: number;
   maxBufferDurationSec: number;
   chunksPerSecond: number;
+  connectionRetry: {
+    maxAttempts: number;
+    delayMs: number;
+  };
   logger?: (level: 'debug' | 'info' | 'warn' | 'error', message: string, data?: any) => void;
 }
 
@@ -171,9 +176,11 @@ export class RealTimeTwoWayWebSocketRecognitionClient
     const audioUtteranceId = config.audioUtteranceId || uuidv4();
 
     // Build WebSocket URL with query parameters
+    // Precedence: url > stage > default production
     const url = buildWebSocketUrl({
       audioUtteranceId,
       ...(config.url && { url: config.url }),
+      ...(config.stage && { stage: config.stage }),
       ...(config.callbackUrls && { callbackUrls: config.callbackUrls }),
       ...(config.userId && { userId: config.userId }),
       ...(config.gameSessionId && { gameSessionId: config.gameSessionId }),
@@ -191,6 +198,11 @@ export class RealTimeTwoWayWebSocketRecognitionClient
       lowWM: config.lowWaterMark ?? 128_000
     });
 
+    // Process retry config with defaults and validation
+    const retryConfig = config.connectionRetry || {};
+    const maxAttempts = Math.max(1, Math.min(5, retryConfig.maxAttempts ?? 4)); // Default: 4 attempts (3 retries), clamp 1-5
+    const delayMs = retryConfig.delayMs ?? 200; // Fast retry for short audio sessions
+
     // Process config with defaults
     this.config = {
       url,
@@ -208,6 +220,10 @@ export class RealTimeTwoWayWebSocketRecognitionClient
       lowWaterMark: config.lowWaterMark ?? 128_000,
       maxBufferDurationSec: config.maxBufferDurationSec ?? 60,
       chunksPerSecond: config.chunksPerSecond ?? 100,
+      connectionRetry: {
+        maxAttempts,
+        delayMs
+      },
       ...(config.logger && { logger: config.logger })
     };
 
@@ -275,11 +291,10 @@ export class RealTimeTwoWayWebSocketRecognitionClient
   // ==========================================================================
 
   override async connect(): Promise<void> {
-    // FIRST: Check if we already have a connection promise (handles simultaneous calls)
+    // FIRST: Prevent concurrent connection attempts - return existing promise if connecting
     if (this.connectionPromise) {
-      this.log('debug', 'Returning existing connection promise', {
-        state: this.state,
-        hasPromise: true
+      this.log('debug', 'Returning existing connection promise (already connecting)', {
+        state: this.state
       });
       return this.connectionPromise;
     }
@@ -297,48 +312,142 @@ export class RealTimeTwoWayWebSocketRecognitionClient
       return Promise.resolve();
     }
 
-    // RETRY HINT: Wrap this method with exponential backoff (e.g., 1s, 2s, 4s) on FAILED state
-    // Ensure audioBuffer persists between retries - same audioUtteranceId = same audio session
+    // THIRD: Create connection promise with retry logic
+    // Store the promise IMMEDIATELY to prevent concurrent attempts
+    this.connectionPromise = this.connectWithRetry();
 
-    this.log('debug', 'Creating new connection to WebSocket', { url: this.config.url });
-    this.state = ClientState.CONNECTING;
-
-    const connectionStartTime = Date.now();
+    return this.connectionPromise;
+  }
 
-    // Store the promise IMMEDIATELY so simultaneous calls will get the same promise
-    this.connectionPromise = new Promise((resolve, reject) => {
-      const timeout = setTimeout(() => {
-        this.log('warn', 'Connection timeout', { timeout: 10000 });
-        this.state = ClientState.FAILED;
-        reject(new Error('Timeout'));
-      }, 10000);
-
-      const originalOnConnected = this.onConnected.bind(this);
-      this.onConnected = (): void => {
-        clearTimeout(timeout);
-        const connectionTime = Date.now() - connectionStartTime;
-        this.log('debug', 'Connection established successfully', {
-          connectionTimeMs: connectionTime,
-          url: this.config.url
+  /**
+   * Attempt to connect with retry logic
+   * Only retries on initial connection establishment, not mid-stream interruptions
+   */
+  private async connectWithRetry(): Promise<void> {
+    const { maxAttempts, delayMs } = this.config.connectionRetry;
+    const connectionTimeout = 10000; // 10 second timeout per attempt
+
+    // TODO: Consider implementing error-code-based retry strategy
+    // - Retry on 503 (Service Unavailable) with longer delays
+    // - Don't retry on 401 (Unauthorized) or 400 (Bad Request)
+    // - Requires extracting HTTP status from WebSocket connection error
+    // For now: Simple retry for all connection failures
+
+    let lastError: Error | undefined;
+
+    // Store original handlers once (not per-attempt to avoid nested wrappers)
+    const originalOnConnected = this.config.onConnected;
+    const originalOnError = this.config.onError;
+
+    try {
+      for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        // Use debug for first attempt (usually succeeds), info for retries
+        const attemptLogLevel = attempt === 1 ? 'debug' : 'info';
+        this.log(attemptLogLevel, `Connection attempt ${attempt}/${maxAttempts}`, {
+          url: this.config.url,
+          delayMs: attempt > 1 ? delayMs : 0
         });
-        this.state = ClientState.CONNECTED;
-        originalOnConnected();
-        resolve();
-      };
 
-      const originalOnError = this.onError.bind(this);
-      this.onError = (error): void => {
-        clearTimeout(timeout);
-        this.log('warn', 'Connection error', error);
-        this.state = ClientState.FAILED;
-        originalOnError(error);
-        reject(error);
-      };
+        this.state = ClientState.CONNECTING;
+        const connectionStartTime = Date.now();
+
+        try {
+          // Create promise for this single attempt with timeout
+          await new Promise<void>((resolve, reject) => {
+            let settled = false; // Guard against late callbacks for this attempt
+
+            const timeout = setTimeout(() => {
+              if (settled) return;
+              settled = true;
+              this.log('warn', 'Connection timeout', { timeout: connectionTimeout, attempt });
+              this.state = ClientState.FAILED;
+              reject(new Error(`Connection timeout after ${connectionTimeout}ms`));
+            }, connectionTimeout);
+
+            // One-shot handlers for this attempt
+            this.onConnected = (): void => {
+              if (settled) return; // Ignore late callback
+              settled = true;
+              clearTimeout(timeout);
+
+              const connectionTime = Date.now() - connectionStartTime;
+              this.log('debug', 'Connection established successfully', {
+                connectionTimeMs: connectionTime,
+                url: this.config.url,
+                attempt
+              });
+              this.state = ClientState.CONNECTED;
+
+              // Call original handler
+              originalOnConnected();
+              resolve();
+            };
+
+            this.onError = (error): void => {
+              if (settled) return; // Ignore late callback
+              settled = true;
+              clearTimeout(timeout);
+
+              this.log('warn', 'Connection error', { error, attempt });
+              this.state = ClientState.FAILED;
+
+              // Don't call originalOnError - it expects ErrorResultV1, not WebSocket Event
+              // Connection errors are handled by throwing ConnectionError after retry exhaustion
+              reject(error);
+            };
+
+            // Start the connection attempt
+            super.connect();
+          });
+
+          // Success! Connection established
+          const successLogLevel = attempt === 1 ? 'debug' : 'info';
+          this.log(successLogLevel, `Connection successful on attempt ${attempt}`, {
+            totalAttempts: attempt
+          });
+          return; // Success - exit retry loop
+
+        } catch (error) {
+          lastError = error as Error;
+
+          if (attempt < maxAttempts) {
+            // Not the last attempt - wait before retry
+            // Use info for first 2 retries (attempts 2-3), warn for 3rd retry (attempt 4)
+            const logLevel = attempt < 3 ? 'info' : 'warn';
+            this.log(logLevel, `Connection attempt ${attempt} failed, retrying after ${delayMs}ms`, {
+              error: lastError.message,
+              nextAttempt: attempt + 1
+            });
+
+            // Reset state to allow retry (but DON'T clear connectionPromise - maintains concurrency guard)
+            this.state = ClientState.INITIAL;
+
+            // Wait before next attempt
+            await new Promise(resolve => setTimeout(resolve, delayMs));
+          } else {
+            // Last attempt failed - all retries exhausted
+            this.log('warn', `All ${maxAttempts} connection attempts failed`, {
+              error: lastError.message
+            });
+          }
+        }
+      }
 
-      super.connect();
-    });
+      // All retries exhausted - throw typed ConnectionError
+      throw new ConnectionError(
+        `Failed to establish connection after ${maxAttempts} attempts`,
+        maxAttempts,
+        this.config.url,
+        lastError
+      );
+    } finally {
+      // Restore original handlers
+      this.config.onConnected = originalOnConnected;
+      this.config.onError = originalOnError;
 
-    return this.connectionPromise;
+      // Clear connectionPromise only after entire retry sequence completes (success or failure)
+      this.connectionPromise = undefined;
+    }
   }
 
   override sendAudio(audioData: ArrayBuffer | ArrayBufferView | Blob): void {
@@ -437,6 +546,10 @@ export class RealTimeTwoWayWebSocketRecognitionClient
     return this.config.audioUtteranceId;
   }
 
+  getUrl(): string {
+    return this.config.url;
+  }
+
   getState(): ClientState {
     return this.state;
   }

package/src/recognition-client.types.ts

@@ -11,7 +11,8 @@ import {
   MetadataResultV1,
   ErrorResultV1,
   ASRRequestConfig,
-  GameContextV1
+  GameContextV1,
+  Stage
 } from '@recog/shared-types';
 
 /**
@@ -57,17 +58,36 @@ export type IRecognitionCallbackUrl = RecognitionCallbackUrl;
 
 export interface IRecognitionClientConfig {
   /**
-   * WebSocket endpoint URL (optional - defaults to production)
+   * WebSocket endpoint URL (optional)
+   * Either `url` or `stage` must be provided.
+   * If both are provided, `url` takes precedence.
    *
-   * For different stages, use the helper function:
+   * Example with explicit URL:
    * ```typescript
-   * import { getRecognitionServiceBase } from '@recog/client-sdk-ts';
-   * const base = getRecognitionServiceBase('staging'); // or 'dev', 'production'
-   * const url = `${base.wsBase}/ws/v1/recognize`;
+   * { 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;
 
@@ -137,6 +157,31 @@ export interface IRecognitionClientConfig {
   /** 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
@@ -223,6 +268,13 @@ export interface IRecognitionClient {
    * @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;
 }
 
 /**

package/src/simplified-vgf-recognition-client.ts

@@ -106,6 +106,11 @@ export interface ISimplifiedVGFRecognitionClient {
      */
     getAudioUtteranceId(): string;
 
+    /**
+     * Get the WebSocket URL being used
+     */
+    getUrl(): string;
+
     /**
      * Get the underlying client state (for advanced usage)
      */
@@ -254,6 +259,10 @@ export class SimplifiedVGFRecognitionClient implements ISimplifiedVGFRecognition
         return this.client.getAudioUtteranceId();
     }
 
+    getUrl(): string {
+        return this.client.getUrl();
+    }
+
     getState(): ClientState {
         return this.client.getState();
     }