@volley/recognition-client-sdk 0.1.384 → 0.1.417

package/dist/index.js

@@ -1,4 +1,4 @@
-// ../../node_modules/.pnpm/zod@3.22.5/node_modules/zod/lib/index.mjs
+// ../../node_modules/.pnpm/zod@3.22.4/node_modules/zod/lib/index.mjs
 var util;
 (function(util2) {
   util2.assertEqual = (val) => val;
@@ -3797,6 +3797,7 @@ var RecognitionResultTypeV1;
   RecognitionResultTypeV12["METADATA"] = "Metadata";
   RecognitionResultTypeV12["ERROR"] = "Error";
   RecognitionResultTypeV12["CLIENT_CONTROL_MESSAGE"] = "ClientControlMessage";
+  RecognitionResultTypeV12["AUDIO_METRICS"] = "AudioMetrics";
 })(RecognitionResultTypeV1 || (RecognitionResultTypeV1 = {}));
 var TranscriptionResultSchemaV1 = z.object({
   type: z.literal(RecognitionResultTypeV1.TRANSCRIPTION),
@@ -3821,6 +3822,12 @@ var FunctionCallResultSchemaV1 = z.object({
   functionName: z.string(),
   functionArgJson: z.string()
 });
+var TranscriptOutcomeType;
+(function(TranscriptOutcomeType2) {
+  TranscriptOutcomeType2["WITH_CONTENT"] = "with_content";
+  TranscriptOutcomeType2["EMPTY"] = "empty";
+  TranscriptOutcomeType2["NEVER_SENT"] = "never_sent";
+})(TranscriptOutcomeType || (TranscriptOutcomeType = {}));
 var MetadataResultSchemaV1 = z.object({
   type: z.literal(RecognitionResultTypeV1.METADATA),
   audioUtteranceId: z.string(),
@@ -3840,7 +3847,9 @@ var MetadataResultSchemaV1 = z.object({
   // ASR configuration as JSON string (no type validation)
   asrConfig: z.string().optional(),
   // Raw ASR metadata payload as provided by the provider (stringified if needed)
-  rawAsrMetadata: z.string().optional()
+  rawAsrMetadata: z.string().optional(),
+  // Transcript outcome - categorizes the final transcript state
+  transcriptOutcome: z.nativeEnum(TranscriptOutcomeType).optional()
 });
 var ErrorTypeV1;
 (function(ErrorTypeV12) {
@@ -3873,6 +3882,22 @@ var ClientControlMessageSchemaV1 = z.object({
   action: ClientControlActionsV1
   // The control action to perform
 });
+var AudioMetricsResultSchemaV1 = z.object({
+  type: z.literal(RecognitionResultTypeV1.AUDIO_METRICS),
+  valid: z.boolean(),
+  audioBeginMs: z.number(),
+  audioEndMs: z.number(),
+  maxVolume: z.number(),
+  minVolume: z.number(),
+  avgVolume: z.number(),
+  silenceRatio: z.number(),
+  clippingRatio: z.number(),
+  snrEstimate: z.number().nullable(),
+  lastNonSilenceMs: z.number(),
+  timestamp: z.string(),
+  isFinal: z.boolean().optional()
+  // true if this is the final metrics (STOP_RECORDING signal), false for streaming
+});
 var RecognitionResultSchemaV1 = z.discriminatedUnion("type", [
   // P0
   TranscriptionResultSchemaV1,
@@ -4541,6 +4566,7 @@ var PlumbingType;
   PlumbingType2["PROVIDER_VAD_SIGNAL"] = "provider_vad_signal";
   PlumbingType2["PROVIDER_TIMER_SIGNAL"] = "provider_timer_signal";
   PlumbingType2["PROVIDER_RAW_MESSAGE"] = "provider_raw_message";
+  PlumbingType2["AUDIO_METRICS"] = "audio_metrics";
 })(PlumbingType || (PlumbingType = {}));
 
 // ../../libs/types/dist/game-id.types.js
@@ -4565,6 +4591,21 @@ var STRING_TO_GAME_ID_MAP = {
   "twenty-questions": GameId.TWENTY_QUESTIONS,
   "emoji": GameId.GUESS_THE_EMOJI
 };
+var GAME_ID_ALIAS_MAP = {
+  // Song Quiz aliases
+  "songquiz": GameId.SONG_QUIZ,
+  "sq": GameId.SONG_QUIZ,
+  // Wheel of Fortune aliases
+  "wof": GameId.WHEEL_OF_FORTUNE,
+  "wheeloffortune": GameId.WHEEL_OF_FORTUNE,
+  // Twenty Questions aliases
+  "20q": GameId.TWENTY_QUESTIONS,
+  "twentyquestions": GameId.TWENTY_QUESTIONS,
+  "20questions": GameId.TWENTY_QUESTIONS,
+  // Guess the Emoji aliases
+  "guesstheemoji": GameId.GUESS_THE_EMOJI,
+  "gte": GameId.GUESS_THE_EMOJI
+};
 
 // ../../libs/types/dist/gemini-types.js
 var GeminiModel;
@@ -4770,7 +4811,7 @@ var WebSocketAudioClient = class {
 // ../../libs/websocket/dist/core/audio-upload-websocket-server.js
 import { WebSocketServer, WebSocket as WebSocket2 } from "ws";
 
-// ../../node_modules/.pnpm/uuid@11.1.0/node_modules/uuid/dist/esm-browser/stringify.js
+// ../../node_modules/.pnpm/uuid@11.0.0/node_modules/uuid/dist/esm-browser/stringify.js
 var byteToHex = [];
 for (let i = 0; i < 256; ++i) {
   byteToHex.push((i + 256).toString(16).slice(1));
@@ -4779,7 +4820,7 @@ function unsafeStringify(arr, offset = 0) {
   return (byteToHex[arr[offset + 0]] + byteToHex[arr[offset + 1]] + byteToHex[arr[offset + 2]] + byteToHex[arr[offset + 3]] + "-" + byteToHex[arr[offset + 4]] + byteToHex[arr[offset + 5]] + "-" + byteToHex[arr[offset + 6]] + byteToHex[arr[offset + 7]] + "-" + byteToHex[arr[offset + 8]] + byteToHex[arr[offset + 9]] + "-" + byteToHex[arr[offset + 10]] + byteToHex[arr[offset + 11]] + byteToHex[arr[offset + 12]] + byteToHex[arr[offset + 13]] + byteToHex[arr[offset + 14]] + byteToHex[arr[offset + 15]]).toLowerCase();
 }
 
-// ../../node_modules/.pnpm/uuid@11.1.0/node_modules/uuid/dist/esm-browser/rng.js
+// ../../node_modules/.pnpm/uuid@11.0.0/node_modules/uuid/dist/esm-browser/rng.js
 var getRandomValues;
 var rnds8 = new Uint8Array(16);
 function rng() {
@@ -4792,27 +4833,21 @@ function rng() {
   return getRandomValues(rnds8);
 }
 
-// ../../node_modules/.pnpm/uuid@11.1.0/node_modules/uuid/dist/esm-browser/native.js
+// ../../node_modules/.pnpm/uuid@11.0.0/node_modules/uuid/dist/esm-browser/native.js
 var randomUUID = typeof crypto !== "undefined" && crypto.randomUUID && crypto.randomUUID.bind(crypto);
 var native_default = { randomUUID };
 
-// ../../node_modules/.pnpm/uuid@11.1.0/node_modules/uuid/dist/esm-browser/v4.js
+// ../../node_modules/.pnpm/uuid@11.0.0/node_modules/uuid/dist/esm-browser/v4.js
 function v4(options, buf, offset) {
   if (native_default.randomUUID && !buf && !options) {
     return native_default.randomUUID();
   }
   options = options || {};
-  const rnds = options.random ?? options.rng?.() ?? rng();
-  if (rnds.length < 16) {
-    throw new Error("Random bytes length must be >= 16");
-  }
+  const rnds = options.random || (options.rng || rng)();
   rnds[6] = rnds[6] & 15 | 64;
   rnds[8] = rnds[8] & 63 | 128;
   if (buf) {
     offset = offset || 0;
-    if (offset < 0 || offset + 16 > buf.length) {
-      throw new RangeError(`UUID byte range ${offset}:${offset + 15} is out of buffer bounds`);
-    }
     for (let i = 0; i < 16; ++i) {
       buf[offset + i] = rnds[i];
     }
@@ -4941,8 +4976,11 @@ function buildWebSocketUrl(config) {
   if (config.platform) {
     url.searchParams.set("platform", config.platform);
   }
-  if (config.gameContext) {
-    url.searchParams.set("gameId", config.gameContext.gameId);
+  const gameId = config.gameId ?? config.gameContext?.gameId;
+  if (gameId) {
+    url.searchParams.set("gameId", gameId);
+  }
+  if (config.gameContext?.gamePhase) {
     url.searchParams.set("gamePhase", config.gameContext.gamePhase);
   }
   return url.toString();
@@ -4978,7 +5016,7 @@ var AudioRingBuffer = class {
       this.hasWrapped = true;
       this.overflowCount++;
       if (this.logger) {
-        this.logger("debug", "Buffer overflow detected", {
+        this.logger("debug", "[RecogSDK] Buffer overflow detected", {
           bufferSize: this.bufferSize,
           totalOverflows: this.overflowCount,
           droppedChunk: this.buffer[this.readIndex]?.timestamp
@@ -5059,7 +5097,7 @@ var AudioRingBuffer = class {
     this.chunksBuffered = 0;
     this.totalBufferedBytes = 0;
     if (this.logger) {
-      this.logger("debug", "Audio buffer cleared");
+      this.logger("debug", "[RecogSDK] Audio buffer cleared");
     }
   }
   /**
@@ -5094,7 +5132,7 @@ var MessageHandler = class {
    */
   handleMessage(msg) {
     if (this.callbacks.logger) {
-      this.callbacks.logger("debug", "Received WebSocket message", {
+      this.callbacks.logger("debug", "[RecogSDK] Received WebSocket message", {
         msgType: msg.type,
         msgDataType: msg.data && typeof msg.data === "object" && "type" in msg.data ? msg.data.type : "N/A",
         fullMessage: msg
@@ -5102,7 +5140,7 @@ var MessageHandler = class {
     }
     if (msg.data && typeof msg.data !== "object") {
       if (this.callbacks.logger) {
-        this.callbacks.logger("error", "Received primitive msg.data from server", {
+        this.callbacks.logger("error", "[RecogSDK] Received primitive msg.data from server", {
           dataType: typeof msg.data,
           data: msg.data,
           fullMessage: msg
@@ -5129,7 +5167,7 @@ var MessageHandler = class {
         break;
       default:
         if (this.callbacks.logger) {
-          this.callbacks.logger("debug", "Unknown message type", { type: msgType });
+          this.callbacks.logger("debug", "[RecogSDK] Unknown message type", { type: msgType });
         }
     }
   }
@@ -5142,7 +5180,7 @@ var MessageHandler = class {
       this.firstTranscriptTime = Date.now();
       const timeToFirstTranscript = this.firstTranscriptTime - this.sessionStartTime;
       if (this.callbacks.logger) {
-        this.callbacks.logger("debug", "First transcript received", {
+        this.callbacks.logger("debug", "[RecogSDK] First transcript received", {
           timeToFirstTranscriptMs: timeToFirstTranscript
         });
       }
@@ -5237,7 +5275,8 @@ var RealTimeTwoWayWebSocketRecognitionClient = class _RealTimeTwoWayWebSocketRec
       ...config.accountId && { accountId: config.accountId },
       ...config.questionAnswerId && { questionAnswerId: config.questionAnswerId },
       ...config.platform && { platform: config.platform },
-      ...config.gameContext && { gameContext: config.gameContext }
+      ...config.gameContext && { gameContext: config.gameContext },
+      ...config.gameId && { gameId: config.gameId }
     });
     super({
       url,
@@ -5315,7 +5354,7 @@ var RealTimeTwoWayWebSocketRecognitionClient = class _RealTimeTwoWayWebSocketRec
       return;
     }
     if (this.config.logger) {
-      this.config.logger(level, `[SDK] ${message}`, data);
+      this.config.logger(level, `[RecogSDK] ${message}`, data);
     }
   }
   /**
@@ -5757,6 +5796,14 @@ var ConfigBuilder = class {
     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) {
+    this.config.gameId = id;
+    return this;
+  }
   /**
    * Set audio utterance ID
    */
@@ -6013,14 +6060,6 @@ function mapTranscriptionResultToState(currentState, result, isRecording) {
   }
   return newState;
 }
-function mapMetadataToState(currentState, metadata) {
-  const newState = { ...currentState };
-  if (!newState.finalRecordingTimestamp) {
-    newState.finalRecordingTimestamp = (/* @__PURE__ */ new Date()).toISOString();
-  }
-  newState.startRecordingStatus = RecordingStatus.FINISHED;
-  return newState;
-}
 function mapErrorToState(currentState, error) {
   return {
     ...currentState,
@@ -6056,6 +6095,7 @@ function generateUUID() {
 var SimplifiedVGFRecognitionClient = class {
   constructor(config) {
     this.isRecordingAudio = false;
+    this.lastSentTerminalUuid = null;
     const { onStateChange, initialState, ...clientConfig } = config;
     this.stateChangeCallback = onStateChange;
     this.logger = clientConfig.logger;
@@ -6076,6 +6116,7 @@ var SimplifiedVGFRecognitionClient = class {
           finalTranscript: void 0
         };
         clientConfig.audioUtteranceId = newUUID;
+        this.lastSentTerminalUuid = null;
         if (onStateChange) {
           onStateChange(this.state);
         }
@@ -6110,11 +6151,17 @@ var SimplifiedVGFRecognitionClient = class {
           if (this.logger) {
             this.logger(
               "warn",
-              `[VGF] Skipping transcript update: UUID mismatch (expected: ${this.expectedUuid}, got: ${result.audioUtteranceId})`
+              `[RecogSDK:VGF] Skipping transcript update: UUID mismatch (expected: ${this.expectedUuid}, got: ${result.audioUtteranceId})`
             );
           }
-          if (clientConfig.onTranscript) {
-            clientConfig.onTranscript(result);
+          return;
+        }
+        if (this.lastSentTerminalUuid === this.expectedUuid) {
+          if (this.logger) {
+            this.logger(
+              "info",
+              `[RecogSDK:VGF] Duplicate terminal status suppressed (lastSentTerminalUuid: ${this.lastSentTerminalUuid})`
+            );
           }
           return;
         }
@@ -6129,16 +6176,11 @@ var SimplifiedVGFRecognitionClient = class {
           if (this.logger) {
             this.logger(
               "warn",
-              `[VGF] Skipping metadata update: UUID mismatch (expected: ${this.expectedUuid}, got: ${metadata.audioUtteranceId})`
+              `[RecogSDK:VGF] Skipping metadata update: UUID mismatch (expected: ${this.expectedUuid}, got: ${metadata.audioUtteranceId})`
             );
           }
-          if (clientConfig.onMetadata) {
-            clientConfig.onMetadata(metadata);
-          }
           return;
         }
-        this.state = mapMetadataToState(this.state, metadata);
-        this.notifyStateChange();
         if (clientConfig.onMetadata) {
           clientConfig.onMetadata(metadata);
         }
@@ -6153,12 +6195,12 @@ var SimplifiedVGFRecognitionClient = class {
           if (this.logger) {
             this.logger(
               "warn",
-              `[VGF] Skipping error update: UUID mismatch (expected: ${this.expectedUuid}, got: ${error.audioUtteranceId})`
+              `[RecogSDK:VGF] Skipping error update: UUID mismatch (expected: ${this.expectedUuid}, got: ${error.audioUtteranceId})`
             );
           }
-          if (clientConfig.onError) {
-            clientConfig.onError(error);
-          }
+          return;
+        }
+        if (this.lastSentTerminalUuid === this.expectedUuid) {
           return;
         }
         this.isRecordingAudio = false;
@@ -6202,6 +6244,24 @@ var SimplifiedVGFRecognitionClient = class {
     this.isRecordingAudio = false;
     this.state = updateStateOnStop(this.state);
     this.notifyStateChange();
+    if (this.state.transcriptionStatus === TranscriptionStatus.NOT_STARTED) {
+      if (this.logger) {
+        this.logger(
+          "info",
+          `[RecogSDK:VGF] Early termination detected (transcriptionStatus: NOT_STARTED) - emitting synthetic finalization`
+        );
+      }
+      this.state = {
+        ...this.state,
+        transcriptionStatus: TranscriptionStatus.FINALIZED,
+        finalTranscript: "",
+        finalConfidence: 0,
+        pendingTranscript: "",
+        pendingConfidence: void 0,
+        finalTranscriptionTimestamp: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      this.notifyStateChange();
+    }
     await this.client.stopRecording();
   }
   stopAbnormally() {
@@ -6251,10 +6311,26 @@ var SimplifiedVGFRecognitionClient = class {
   getVGFState() {
     return { ...this.state };
   }
+  isTerminalStatus(status) {
+    return status === TranscriptionStatus.FINALIZED || status === TranscriptionStatus.ABORTED || status === TranscriptionStatus.ERROR;
+  }
   notifyStateChange() {
-    if (this.stateChangeCallback) {
-      this.stateChangeCallback({ ...this.state });
+    if (this.isTerminalStatus(this.state.transcriptionStatus)) {
+      if (this.lastSentTerminalUuid === this.expectedUuid) {
+        if (this.logger) {
+          this.logger(
+            "info",
+            `[RecogSDK:VGF] Duplicate terminal status suppressed (lastSentTerminalUuid: ${this.lastSentTerminalUuid})`
+          );
+        }
+        return;
+      }
+      this.lastSentTerminalUuid = this.expectedUuid;
+    }
+    if (!this.stateChangeCallback) {
+      return;
     }
+    this.stateChangeCallback({ ...this.state });
   }
 };
 function createSimplifiedVGFClient(config) {