@volley/recognition-client-sdk 0.1.211 → 0.1.254

package/README.md

@@ -11,12 +11,17 @@ npm install @volley/recognition-client-sdk
 ## Quick Start
 
 ```typescript
-import { createClientWithBuilder, RecognitionProvider, DeepgramModel } from '@volley/recognition-client-sdk';
+import {
+  createClientWithBuilder,
+  RecognitionProvider,
+  DeepgramModel,
+  STAGES
+} from '@volley/recognition-client-sdk';
 
 // Create client with builder pattern (recommended)
 const client = createClientWithBuilder(builder =>
   builder
-    .url('ws://localhost:3101/ws/v1/recognize')
+    .stage(STAGES.STAGING)  // ✨ Simple environment selection using enum
     .provider(RecognitionProvider.DEEPGRAM)
     .model(DeepgramModel.NOVA_2)
     .onTranscript(result => {
@@ -30,6 +35,9 @@ const client = createClientWithBuilder(builder =>
 await client.connect();
 client.sendAudio(pcm16AudioChunk);  // Call repeatedly with audio chunks
 await client.stopRecording();       // Wait for final transcript
+
+// Check the actual URL being used
+console.log('Connected to:', client.getUrl());
 ```
 
 ### Alternative: Direct Client Creation
@@ -39,11 +47,12 @@ import {
   RealTimeTwoWayWebSocketRecognitionClient,
   RecognitionProvider,
   DeepgramModel,
-  Language
+  Language,
+  STAGES
 } from '@volley/recognition-client-sdk';
 
 const client = new RealTimeTwoWayWebSocketRecognitionClient({
-  url: 'ws://localhost:3101/ws/v1/recognize',
+  stage: STAGES.STAGING,  // ✨ Recommended: Use STAGES enum for type safety
   asrRequestConfig: {
     provider: RecognitionProvider.DEEPGRAM,
     model: DeepgramModel.NOVA_2,
@@ -52,23 +61,89 @@ const client = new RealTimeTwoWayWebSocketRecognitionClient({
   onTranscript: (result) => console.log(result),
   onError: (error) => console.error(error)
 });
+
+// Check the actual URL being used
+console.log('Connected to:', client.getUrl());
 ```
 
 ## Configuration
 
-### Basic Setup
+### Environment Selection
+
+**Recommended: Use `stage` parameter with STAGES enum** for automatic environment configuration:
 
 ```typescript
-import { RecognitionProvider, DeepgramModel, Language } from '@volley/recognition-client-sdk';
+import {
+  RecognitionProvider,
+  DeepgramModel,
+  Language,
+  STAGES
+} from '@volley/recognition-client-sdk';
 
 builder
-  .url('ws://localhost:3101/ws/v1/recognize')
+  .stage(STAGES.STAGING)  // STAGES.LOCAL | STAGES.DEV | STAGES.STAGING | STAGES.PRODUCTION
   .provider(RecognitionProvider.DEEPGRAM)  // DEEPGRAM, GOOGLE
   .model(DeepgramModel.NOVA_2)              // Provider-specific model enum
   .language(Language.ENGLISH_US)            // Language enum
   .interimResults(true)                     // Enable partial transcripts
 ```
 
+**Available Stages and URLs:**
+
+| Stage | Enum | WebSocket URL |
+|-------|------|---------------|
+| **Local** | `STAGES.LOCAL` | `ws://localhost:3101/ws/v1/recognize` |
+| **Development** | `STAGES.DEV` | `wss://recognition-service-dev.volley-services.net/ws/v1/recognize` |
+| **Staging** | `STAGES.STAGING` | `wss://recognition-service-staging.volley-services.net/ws/v1/recognize` |
+| **Production** | `STAGES.PRODUCTION` | `wss://recognition-service.volley-services.net/ws/v1/recognize` |
+
+> 💡 Using the `stage` parameter automatically constructs the correct URL for each environment.
+
+**Automatic Connection Retry:**
+
+The SDK **automatically retries failed connections** with sensible defaults - no configuration needed!
+
+**Default behavior (works out of the box):**
+- 4 connection attempts (try once, retry 3 times if failed)
+- 200ms delay between retries
+- Handles temporary service unavailability (503)
+- Fast failure (~600ms total on complete failure)
+- Timing: `Attempt 1 → FAIL → wait 200ms → Attempt 2 → FAIL → wait 200ms → Attempt 3 → FAIL → wait 200ms → Attempt 4`
+
+```typescript
+import { STAGES } from '@volley/recognition-client-sdk';
+
+// ✅ Automatic retry - no config needed!
+const client = new RealTimeTwoWayWebSocketRecognitionClient({
+  stage: STAGES.STAGING,
+  // connectionRetry works automatically with defaults
+});
+```
+
+**Optional: Customize retry behavior** (only if needed):
+```typescript
+const client = new RealTimeTwoWayWebSocketRecognitionClient({
+  stage: STAGES.STAGING,
+  connectionRetry: {
+    maxAttempts: 2,  // Fewer attempts (min: 1, max: 5)
+    delayMs: 500     // Longer delay between attempts
+  }
+});
+```
+
+> ⚠️ **Note**: Retry only applies to **initial connection establishment**. If the connection drops during audio streaming, the SDK will not auto-retry (caller must handle this).
+
+**Advanced: Custom URL** for non-standard endpoints:
+
+```typescript
+builder
+  .url('wss://custom-endpoint.example.com/ws/v1/recognize')  // Custom WebSocket URL
+  .provider(RecognitionProvider.DEEPGRAM)
+  // ... rest of config
+```
+
+> 💡 **Note**: If both `stage` and `url` are provided, `url` takes precedence.
+
 ### Event Handlers
 
 ```typescript
@@ -102,6 +177,7 @@ await client.connect();           // Establish connection
 client.sendAudio(chunk);          // Send PCM16 audio
 await client.stopRecording();     // End and get final transcript
 client.getAudioUtteranceId();     // Get session UUID
+client.getUrl();                  // Get actual WebSocket URL being used
 client.getState();                // Get current state
 client.isConnected();             // Check connection status
 ```

package/dist/{browser-C4ZssGoU.d.ts → browser-BZs4BL_w.d.ts}

@@ -14,6 +14,15 @@ declare enum RecognitionProvider {
     GEMINI_BATCH = "gemini-batch",
     OPENAI_BATCH = "openai-batch"
 }
+/**
+ * ASR API type - distinguishes between streaming and file-based transcription APIs
+ * - STREAMING: Real-time streaming APIs (Deepgram, AssemblyAI, Google)
+ * - FILE_BASED: File upload/batch APIs (OpenAI Batch, Gemini Batch)
+ */
+declare enum ASRApiType {
+    STREAMING = "streaming",
+    FILE_BASED = "file-based"
+}
 /**
  * Deepgram model names
  */
@@ -266,6 +275,7 @@ declare const MetadataResultSchemaV1: z.ZodObject<{
     volume: z.ZodOptional<z.ZodNumber>;
     accumulatedAudioTimeMs: z.ZodOptional<z.ZodNumber>;
     costInUSD: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+    apiType: z.ZodOptional<z.ZodNativeEnum<typeof ASRApiType>>;
     asrConfig: z.ZodOptional<z.ZodString>;
     rawAsrMetadata: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
@@ -279,6 +289,7 @@ declare const MetadataResultSchemaV1: z.ZodObject<{
     duration?: number | undefined;
     volume?: number | undefined;
     costInUSD?: number | undefined;
+    apiType?: ASRApiType | undefined;
     asrConfig?: string | undefined;
     rawAsrMetadata?: string | undefined;
 }, {
@@ -292,6 +303,7 @@ declare const MetadataResultSchemaV1: z.ZodObject<{
     duration?: number | undefined;
     volume?: number | undefined;
     costInUSD?: number | undefined;
+    apiType?: ASRApiType | undefined;
     asrConfig?: string | undefined;
     rawAsrMetadata?: string | undefined;
 }>;
@@ -305,6 +317,7 @@ declare enum ErrorTypeV1 {
     PROVIDER_ERROR = "provider_error",// Error from ASR provider (Deepgram, Google, etc.)  Unlikely to happen with fall
     TIMEOUT_ERROR = "timeout_error",// Request or operation timeout. Likely business logic did not handle timeout.
     QUOTA_EXCEEDED = "quota_exceeded",// Quota or rate limit exceeded. Unlikely to happen with fallbakcs
+    CONNECTION_ERROR = "connection_error",// Connection establishment or network error
     UNKNOWN_ERROR = "unknown_error"
 }
 /**
@@ -584,6 +597,17 @@ interface ASRRequestConfig {
     fallbackModels?: ASRRequestConfig[];
 }
 
+/**
+ * Standard stage/environment constants used across all services
+ */
+declare const STAGES: {
+    readonly LOCAL: "local";
+    readonly DEV: "dev";
+    readonly STAGING: "staging";
+    readonly PRODUCTION: "production";
+};
+type Stage = typeof STAGES[keyof typeof STAGES];
+
 /**
  * Generic WebSocket protocol types and utilities
  * Supports flexible versioning and message types
@@ -767,16 +791,34 @@ interface RecognitionCallbackUrl {
 }
 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;
     /** Game context for improved recognition accuracy */
@@ -826,6 +868,30 @@ interface IRecognitionClientConfig {
     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
@@ -901,6 +967,12 @@ 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;
 }
 /**
  * Client statistics interface
@@ -1006,10 +1078,16 @@ declare class RealTimeTwoWayWebSocketRecognitionClient extends WebSocketAudioCli
      */
     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;
     stopRecording(): Promise<void>;
     getAudioUtteranceId(): string;
+    getUrl(): string;
     getState(): ClientState;
     isConnected(): boolean;
     isConnecting(): boolean;
@@ -1037,4 +1115,4 @@ declare class RealTimeTwoWayWebSocketRecognitionClient extends WebSocketAudioCli
     private sendAudioNow;
 }
 
-export { type ASRRequestConfig as A, ClientState as C, DeepgramModel as D, type ErrorResultV1 as E, type FunctionCallResultV1 as F, type GameContextV1 as G, type IRecognitionClient as I, Language as L, type MetadataResultV1 as M, type RecognitionCallbackUrl as R, SampleRate as S, type TranscriptionResultV1 as T, type RealTimeTwoWayWebSocketRecognitionClientConfig as a, type IRecognitionClientConfig as b, RealTimeTwoWayWebSocketRecognitionClient as c, type TranscriptionResult as d, type IRecognitionClientStats as e, AudioEncoding as f, RecognitionContextTypeV1 as g, ControlSignalTypeV1 as h, isNormalDisconnection as i, RecognitionResultTypeV1 as j, type ASRRequestV1 as k, RecognitionProvider as l, GoogleModel as m };
+export { type ASRRequestConfig as A, ClientState as C, DeepgramModel as D, ErrorTypeV1 as E, type FunctionCallResultV1 as F, type GameContextV1 as G, type IRecognitionClient as I, Language as L, type MetadataResultV1 as M, RecognitionProvider as R, type Stage as S, type TranscriptionResultV1 as T, type RecognitionCallbackUrl as a, type ErrorResultV1 as b, type RealTimeTwoWayWebSocketRecognitionClientConfig as c, type IRecognitionClientConfig as d, RealTimeTwoWayWebSocketRecognitionClient as e, type TranscriptionResult as f, type IRecognitionClientStats as g, AudioEncoding as h, isNormalDisconnection as i, RecognitionContextTypeV1 as j, ControlSignalTypeV1 as k, RecognitionResultTypeV1 as l, type ASRRequestV1 as m, GoogleModel as n, SampleRate as o, STAGES as p };