@volley/recognition-client-sdk 0.1.211 → 0.1.255

package/dist/index.js

@@ -19,6 +19,11 @@ var RecognitionMode;
   RecognitionMode2["STREAMING"] = "streaming";
   RecognitionMode2["BATCH"] = "batch";
 })(RecognitionMode || (RecognitionMode = {}));
+var ASRApiType;
+(function(ASRApiType2) {
+  ASRApiType2["STREAMING"] = "streaming";
+  ASRApiType2["FILE_BASED"] = "file-based";
+})(ASRApiType || (ASRApiType = {}));
 var DeepgramModel;
 (function(DeepgramModel2) {
   DeepgramModel2["NOVA_2"] = "nova-2";
@@ -82,6 +87,8 @@ var MetadataResultSchemaV1 = z.object({
   accumulatedAudioTimeMs: z.number().optional(),
   // Cost Information
   costInUSD: z.number().default(0).optional(),
+  // ASR API Type
+  apiType: z.nativeEnum(ASRApiType).optional(),
   // ASR configuration as JSON string (no type validation)
   asrConfig: z.string().optional(),
   // Raw ASR metadata payload as provided by the provider (stringified if needed)
@@ -94,6 +101,7 @@ var ErrorTypeV1;
   ErrorTypeV12["PROVIDER_ERROR"] = "provider_error";
   ErrorTypeV12["TIMEOUT_ERROR"] = "timeout_error";
   ErrorTypeV12["QUOTA_EXCEEDED"] = "quota_exceeded";
+  ErrorTypeV12["CONNECTION_ERROR"] = "connection_error";
   ErrorTypeV12["UNKNOWN_ERROR"] = "unknown_error";
 })(ErrorTypeV1 || (ErrorTypeV1 = {}));
 var ErrorResultSchemaV1 = z.object({
@@ -214,7 +222,27 @@ var TranscriptMessageSchema = z.object({
    * Whether this transcript is finalized (won't change)
    * @example true
    */
-  is_final: z.boolean()
+  is_final: z.boolean(),
+  /**
+   * Accumulated confirmed transcript (all finalized text received so far)
+   * Contains only the completed/finalized portions
+   * @example "hello world how are you"
+   */
+  confirmedTranscript: z.string().optional(),
+  /**
+   * New pending transcript (current interim text since last confirmation)
+   * Contains only the unconfirmed interim text
+   * @example "I'm doing"
+   */
+  newPendingTranscript: z.string().optional(),
+  /**
+   * Whether this is a fallback transcript (forced due to timeout)
+   * True when provider didn't send is_final=true within expected timeframe
+   * Used for monitoring/debugging fallback scenarios
+   * @example true
+   * @default false
+   */
+  is_fallback: z.boolean().optional()
 });
 var VADEndSignalSchema = z.object({
   type: z.literal(ProviderMessageType.VAD_END_SIGNAL),
@@ -302,7 +330,20 @@ var TimerSchema = z.object({
    * Total duration of all audio chunks sent to this provider session
    * @example 2500 (2.5 seconds of audio has been sent)
    */
-  accumulatedAudioTimeMs: z.number().optional()
+  accumulatedAudioTimeMs: z.number().optional(),
+  /**
+   * Estimated cost in USD for this session
+   * Calculated by the job based on audio duration and provider pricing
+   * @example 0.0025 (quarter of a cent)
+   */
+  costInUSD: z.number().optional().default(0),
+  /**
+   * ASR API type from the job
+   * - STREAMING: Real-time streaming APIs (Deepgram, AssemblyAI, Google)
+   * - FILE_BASED: File upload/batch APIs (OpenAI Batch, Gemini Batch)
+   * @example ASRApiType.STREAMING
+   */
+  apiType: z.nativeEnum(ASRApiType).optional()
 });
 var RawMessageSchema = z.object({
   type: z.literal(ProviderMessageType.RAW),
@@ -391,6 +432,16 @@ var QuotaExceededExceptionSchema = BaseRecognitionExceptionSchema.extend({
   /** How long to wait in seconds before retry */
   retryAfterSeconds: z.number().optional()
 });
+var ConnectionExceptionSchema = BaseRecognitionExceptionSchema.extend({
+  errorType: z.literal(ErrorTypeV1.CONNECTION_ERROR),
+  isImmediatelyAvailable: z.literal(true),
+  /** Number of connection attempts made */
+  attempts: z.number().optional(),
+  /** URL that failed to connect */
+  url: z.string().optional(),
+  /** Underlying error message */
+  underlyingError: z.string().optional()
+});
 var UnknownExceptionSchema = BaseRecognitionExceptionSchema.extend({
   errorType: z.literal(ErrorTypeV1.UNKNOWN_ERROR),
   isImmediatelyAvailable: z.literal(false),
@@ -405,8 +456,32 @@ z.discriminatedUnion("errorType", [
   ProviderExceptionSchema,
   TimeoutExceptionSchema,
   QuotaExceededExceptionSchema,
+  ConnectionExceptionSchema,
   UnknownExceptionSchema
 ]);
+function isExceptionImmediatelyAvailable(exception) {
+  return exception.isImmediatelyAvailable;
+}
+__name(isExceptionImmediatelyAvailable, "isExceptionImmediatelyAvailable");
+function getUserFriendlyMessage(exception) {
+  if (!exception.isImmediatelyAvailable) {
+    return "An error occurred. Please try again or contact support.";
+  }
+  switch (exception.errorType) {
+    case ErrorTypeV1.VALIDATION_ERROR:
+      return exception.message || "Invalid input. Please check your request.";
+    case ErrorTypeV1.TIMEOUT_ERROR:
+      return exception.message || "Request timed out. Please try again.";
+    case ErrorTypeV1.QUOTA_EXCEEDED:
+      if (exception.retryAfterSeconds) {
+        return `Rate limit exceeded. Please try again in ${exception.retryAfterSeconds} seconds.`;
+      }
+      return exception.message || "Rate limit exceeded. Please try again later.";
+    case ErrorTypeV1.CONNECTION_ERROR:
+      return exception.message || "Connection failed. Please check your network and try again.";
+  }
+}
+__name(getUserFriendlyMessage, "getUserFriendlyMessage");
 var RecognitionContextTypeV1;
 (function(RecognitionContextTypeV12) {
   RecognitionContextTypeV12["GAME_CONTEXT"] = "GameContext";
@@ -948,6 +1023,11 @@ var STAGES = {
   STAGING: "staging",
   PRODUCTION: "production"
 };
+[
+  STAGES.LOCAL,
+  STAGES.DEV,
+  STAGES.STAGING
+];
 
 // ../../libs/websocket/dist/core/audio-upload-websocket-protocol.js
 var WebSocketCloseCode;
@@ -1209,8 +1289,16 @@ __name(getRecognitionConductorHost, "getRecognitionConductorHost");
 
 // src/utils/url-builder.ts
 function buildWebSocketUrl(config) {
-  const defaultBase = getRecognitionServiceBase("production");
-  const baseUrl = config.url || `${defaultBase.wsBase}/ws/v1/recognize`;
+  let baseUrl;
+  if (config.url) {
+    baseUrl = config.url;
+  } else if (config.stage) {
+    const stageBase = getRecognitionServiceBase(config.stage);
+    baseUrl = `${stageBase.wsBase}/ws/v1/recognize`;
+  } else {
+    const defaultBase = getRecognitionServiceBase("production");
+    baseUrl = `${defaultBase.wsBase}/ws/v1/recognize`;
+  }
   const url = new URL(baseUrl);
   url.searchParams.set("audioUtteranceId", config.audioUtteranceId);
   if (config.callbackUrls && config.callbackUrls.length > 0) {
@@ -1466,6 +1554,75 @@ var MessageHandler = class {
   }
 };
 
+// src/errors.ts
+var RecognitionError = class extends Error {
+  static {
+    __name(this, "RecognitionError");
+  }
+  errorType;
+  timestamp;
+  constructor(errorType, message) {
+    super(message);
+    this.name = "RecognitionError";
+    this.errorType = errorType;
+    this.timestamp = Date.now();
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+};
+var ConnectionError = class extends RecognitionError {
+  static {
+    __name(this, "ConnectionError");
+  }
+  attempts;
+  url;
+  underlyingError;
+  constructor(message, attempts, url, underlyingError) {
+    super(ErrorTypeV1.CONNECTION_ERROR, message);
+    this.name = "ConnectionError";
+    this.attempts = attempts;
+    this.url = url;
+    if (underlyingError !== void 0) {
+      this.underlyingError = underlyingError;
+    }
+  }
+};
+var TimeoutError = class extends RecognitionError {
+  static {
+    __name(this, "TimeoutError");
+  }
+  timeoutMs;
+  operation;
+  constructor(message, timeoutMs, operation) {
+    super(ErrorTypeV1.TIMEOUT_ERROR, message);
+    this.name = "TimeoutError";
+    this.timeoutMs = timeoutMs;
+    this.operation = operation;
+  }
+};
+var ValidationError = class extends RecognitionError {
+  static {
+    __name(this, "ValidationError");
+  }
+  field;
+  expected;
+  received;
+  constructor(message, field, expected, received) {
+    super(ErrorTypeV1.VALIDATION_ERROR, message);
+    this.name = "ValidationError";
+    if (field !== void 0) {
+      this.field = field;
+    }
+    if (expected !== void 0) {
+      this.expected = expected;
+    }
+    if (received !== void 0) {
+      this.received = received;
+    }
+  }
+};
+
 // src/recognition-client.ts
 function isNormalDisconnection(code) {
   return code === 1e3;
@@ -1507,6 +1664,9 @@ var RealTimeTwoWayWebSocketRecognitionClient = class _RealTimeTwoWayWebSocketRec
       ...config.url && {
         url: config.url
       },
+      ...config.stage && {
+        stage: config.stage
+      },
       ...config.callbackUrls && {
         callbackUrls: config.callbackUrls
       },
@@ -1537,6 +1697,9 @@ var RealTimeTwoWayWebSocketRecognitionClient = class _RealTimeTwoWayWebSocketRec
       highWM: config.highWaterMark ?? 512e3,
       lowWM: config.lowWaterMark ?? 128e3
     });
+    const retryConfig = config.connectionRetry || {};
+    const maxAttempts = Math.max(1, Math.min(5, retryConfig.maxAttempts ?? 4));
+    const delayMs = retryConfig.delayMs ?? 200;
     this.config = {
       url,
       audioUtteranceId,
@@ -1565,6 +1728,10 @@ var RealTimeTwoWayWebSocketRecognitionClient = class _RealTimeTwoWayWebSocketRec
       lowWaterMark: config.lowWaterMark ?? 128e3,
       maxBufferDurationSec: config.maxBufferDurationSec ?? 60,
       chunksPerSecond: config.chunksPerSecond ?? 100,
+      connectionRetry: {
+        maxAttempts,
+        delayMs
+      },
       ...config.logger && {
         logger: config.logger
       }
@@ -1622,9 +1789,8 @@ var RealTimeTwoWayWebSocketRecognitionClient = class _RealTimeTwoWayWebSocketRec
   // ==========================================================================
   async connect() {
     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;
     }
@@ -1634,43 +1800,97 @@ var RealTimeTwoWayWebSocketRecognitionClient = class _RealTimeTwoWayWebSocketRec
       });
       return Promise.resolve();
     }
-    this.log("debug", "Creating new connection to WebSocket", {
-      url: this.config.url
-    });
-    this.state = ClientState.CONNECTING;
-    const connectionStartTime = Date.now();
-    this.connectionPromise = new Promise((resolve, reject) => {
-      const timeout = setTimeout(() => {
-        this.log("warn", "Connection timeout", {
-          timeout: 1e4
-        });
-        this.state = ClientState.FAILED;
-        reject(new Error("Timeout"));
-      }, 1e4);
-      const originalOnConnected = this.onConnected.bind(this);
-      this.onConnected = () => {
-        clearTimeout(timeout);
-        const connectionTime = Date.now() - connectionStartTime;
-        this.log("debug", "Connection established successfully", {
-          connectionTimeMs: connectionTime,
-          url: this.config.url
-        });
-        this.state = ClientState.CONNECTED;
-        originalOnConnected();
-        resolve();
-      };
-      const originalOnError = this.onError.bind(this);
-      this.onError = (error) => {
-        clearTimeout(timeout);
-        this.log("warn", "Connection error", error);
-        this.state = ClientState.FAILED;
-        originalOnError(error);
-        reject(error);
-      };
-      super.connect();
-    });
+    this.connectionPromise = this.connectWithRetry();
     return this.connectionPromise;
   }
+  /**
+  * Attempt to connect with retry logic
+  * Only retries on initial connection establishment, not mid-stream interruptions
+  */
+  async connectWithRetry() {
+    const { maxAttempts, delayMs } = this.config.connectionRetry;
+    const connectionTimeout = 1e4;
+    let lastError;
+    const originalOnConnected = this.onConnected.bind(this);
+    const originalOnError = this.onError.bind(this);
+    try {
+      for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        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.CONNECTING;
+        const connectionStartTime = Date.now();
+        try {
+          await new Promise((resolve, reject) => {
+            let settled = false;
+            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);
+            this.onConnected = () => {
+              if (settled) return;
+              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;
+              originalOnConnected();
+              resolve();
+            };
+            this.onError = (error) => {
+              if (settled) return;
+              settled = true;
+              clearTimeout(timeout);
+              this.log("warn", "Connection error", {
+                error,
+                attempt
+              });
+              this.state = ClientState.FAILED;
+              reject(error);
+            };
+            super.connect();
+          });
+          const successLogLevel = attempt === 1 ? "debug" : "info";
+          this.log(successLogLevel, `Connection successful on attempt ${attempt}`, {
+            totalAttempts: attempt
+          });
+          return;
+        } catch (error) {
+          lastError = error;
+          if (attempt < maxAttempts) {
+            const logLevel = attempt < 3 ? "info" : "warn";
+            this.log(logLevel, `Connection attempt ${attempt} failed, retrying after ${delayMs}ms`, {
+              error: lastError.message,
+              nextAttempt: attempt + 1
+            });
+            this.state = ClientState.INITIAL;
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+          } else {
+            this.log("warn", `All ${maxAttempts} connection attempts failed`, {
+              error: lastError.message
+            });
+          }
+        }
+      }
+      throw new ConnectionError(`Failed to establish connection after ${maxAttempts} attempts`, maxAttempts, this.config.url, lastError);
+    } finally {
+      this.onConnected = originalOnConnected;
+      this.onError = originalOnError;
+      this.connectionPromise = void 0;
+    }
+  }
   sendAudio(audioData) {
     if (audioData instanceof Blob) {
       blobToArrayBuffer(audioData).then((arrayBuffer) => {
@@ -1745,6 +1965,9 @@ var RealTimeTwoWayWebSocketRecognitionClient = class _RealTimeTwoWayWebSocketRec
   getAudioUtteranceId() {
     return this.config.audioUtteranceId;
   }
+  getUrl() {
+    return this.config.url;
+  }
   getState() {
     return this.state;
   }
@@ -1897,13 +2120,27 @@ var ConfigBuilder = class {
   }
   config = {};
   /**
-  * Set the WebSocket URL
+  * Set the WebSocket URL (advanced usage)
+  * For standard environments, use stage() instead
   */
   url(url) {
     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) {
+    this.config.stage = stage;
+    return this;
+  }
+  /**
   * Set ASR request configuration
   */
   asrRequestConfig(config) {
@@ -2307,6 +2544,9 @@ var SimplifiedVGFRecognitionClient = class {
   getAudioUtteranceId() {
     return this.client.getAudioUtteranceId();
   }
+  getUrl() {
+    return this.client.getUrl();
+  }
   getState() {
     return this.client.getState();
   }
@@ -2344,6 +2584,6 @@ function createSimplifiedVGFClient(config) {
 }
 __name(createSimplifiedVGFClient, "createSimplifiedVGFClient");
 
-export { AudioEncoding, ClientState, ConfigBuilder, ControlSignalTypeV1 as ControlSignal, ControlSignalTypeV1, DeepgramModel, GeminiModel, GoogleModel, Language, OpenAIModel, RECOGNITION_CONDUCTOR_BASES, RECOGNITION_SERVICE_BASES, RealTimeTwoWayWebSocketRecognitionClient, RecognitionContextTypeV1, RecognitionProvider, RecognitionResultTypeV1, RecognitionVGFStateSchema, RecordingStatus, SampleRate, SimplifiedVGFRecognitionClient, TranscriptionStatus, createClient, createClientWithBuilder, createInitialRecognitionState, createSimplifiedVGFClient, getRecognitionConductorBase, getRecognitionConductorHost, getRecognitionConductorHttpBase, getRecognitionConductorWsBase, getRecognitionServiceBase, getRecognitionServiceHost, getRecognitionServiceHttpBase, getRecognitionServiceWsBase, isNormalDisconnection, isValidRecordingStatusTransition, normalizeStage };
+export { AudioEncoding, ClientState, ConfigBuilder, ConnectionError, ControlSignalTypeV1 as ControlSignal, ControlSignalTypeV1, DeepgramModel, ErrorTypeV1, GeminiModel, GoogleModel, Language, OpenAIModel, RECOGNITION_CONDUCTOR_BASES, RECOGNITION_SERVICE_BASES, RealTimeTwoWayWebSocketRecognitionClient, RecognitionContextTypeV1, RecognitionError, RecognitionProvider, RecognitionResultTypeV1, RecognitionVGFStateSchema, RecordingStatus, STAGES, SampleRate, SimplifiedVGFRecognitionClient, TimeoutError, TranscriptionStatus, ValidationError, createClient, createClientWithBuilder, createInitialRecognitionState, createSimplifiedVGFClient, getRecognitionConductorBase, getRecognitionConductorHost, getRecognitionConductorHttpBase, getRecognitionConductorWsBase, getRecognitionServiceBase, getRecognitionServiceHost, getRecognitionServiceHttpBase, getRecognitionServiceWsBase, getUserFriendlyMessage, isExceptionImmediatelyAvailable, isNormalDisconnection, isValidRecordingStatusTransition, normalizeStage };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map