@volley/recognition-client-sdk 0.1.255 → 0.1.294

package/dist/utils/message-handler.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Message Handler for Recognition Client
+ * Routes incoming WebSocket messages to appropriate callbacks
+ */
+import { type TranscriptionResultV1, type FunctionCallResultV1, type MetadataResultV1, type ErrorResultV1, type ClientControlMessageV1 } from '@recog/shared-types';
+export interface MessageHandlerCallbacks {
+    onTranscript: (result: TranscriptionResultV1) => void;
+    onFunctionCall: (result: FunctionCallResultV1) => void;
+    onMetadata: (metadata: MetadataResultV1) => void;
+    onError: (error: ErrorResultV1) => void;
+    onControlMessage: (msg: ClientControlMessageV1) => void;
+    logger?: (level: 'debug' | 'info' | 'warn' | 'error', message: string, data?: any) => void;
+}
+export declare class MessageHandler {
+    private firstTranscriptTime;
+    private sessionStartTime;
+    private callbacks;
+    constructor(callbacks: MessageHandlerCallbacks);
+    /**
+     * Set session start time for performance tracking
+     */
+    setSessionStartTime(time: number): void;
+    /**
+     * Handle incoming WebSocket message
+     */
+    handleMessage(msg: {
+        v: number;
+        type: string;
+        data: any;
+    }): void;
+    /**
+     * Handle transcript message and track performance metrics
+     * @param result - The transcription result from the server
+     */
+    private handleTranscription;
+    /**
+     * Get performance metrics
+     */
+    getMetrics(): {
+        sessionStartTime: number | null;
+        firstTranscriptTime: number | null;
+        timeToFirstTranscript: number | null;
+    };
+}
+//# sourceMappingURL=message-handler.d.ts.map

package/dist/utils/message-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-handler.d.ts","sourceRoot":"","sources":["../../src/utils/message-handler.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAGL,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,sBAAsB,EAC5B,MAAM,qBAAqB,CAAC;AAE7B,MAAM,WAAW,uBAAuB;IACtC,YAAY,EAAE,CAAC,MAAM,EAAE,qBAAqB,KAAK,IAAI,CAAC;IACtD,cAAc,EAAE,CAAC,MAAM,EAAE,oBAAoB,KAAK,IAAI,CAAC;IACvD,UAAU,EAAE,CAAC,QAAQ,EAAE,gBAAgB,KAAK,IAAI,CAAC;IACjD,OAAO,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;IACxC,gBAAgB,EAAE,CAAC,GAAG,EAAE,sBAAsB,KAAK,IAAI,CAAC;IACxD,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,KAAK,IAAI,CAAC;CAC5F;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,mBAAmB,CAAuB;IAClD,OAAO,CAAC,gBAAgB,CAAuB;IAC/C,OAAO,CAAC,SAAS,CAA0B;gBAE/B,SAAS,EAAE,uBAAuB;IAI9C;;OAEG;IACH,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIvC;;OAEG;IACH,aAAa,CAAC,GAAG,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,GAAG,CAAA;KAAE,GAAG,IAAI;IAsDhE;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAgB3B;;OAEG;IACH,UAAU;;;;;CAUX"}

package/dist/utils/url-builder.d.ts

@@ -0,0 +1,26 @@
+/**
+ * URL Builder for Recognition Client
+ * Handles WebSocket URL construction with query parameters
+ */
+import type { GameContextV1, Stage } from '@recog/shared-types';
+import type { RecognitionCallbackUrl } from '../recognition-client.types.js';
+export interface UrlBuilderConfig {
+    url?: string;
+    stage?: Stage | string;
+    audioUtteranceId: string;
+    callbackUrls?: RecognitionCallbackUrl[];
+    userId?: string;
+    gameSessionId?: string;
+    deviceId?: string;
+    accountId?: string;
+    questionAnswerId?: string;
+    platform?: string;
+    gameContext?: GameContextV1;
+}
+/**
+ * Build WebSocket URL with all query parameters
+ * Either `url` or `stage` must be provided (or defaults to production if neither provided)
+ * If both are provided, `url` takes precedence over `stage`
+ */
+export declare function buildWebSocketUrl(config: UrlBuilderConfig): string;
+//# sourceMappingURL=url-builder.d.ts.map

package/dist/utils/url-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-builder.d.ts","sourceRoot":"","sources":["../../src/utils/url-builder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAE7E,MAAM,WAAW,gBAAgB;IAC/B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,sBAAsB,EAAE,CAAC;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,aAAa,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAwDlE"}

package/dist/vgf-recognition-mapper.d.ts

@@ -0,0 +1,53 @@
+/**
+ * VGF Recognition Mapper
+ *
+ * Maps between the existing recognition client types and the simplified VGF state.
+ * This provides a clean abstraction layer for game developers.
+ */
+import { RecognitionState } from './vgf-recognition-state.js';
+import { ClientState, IRecognitionClientConfig } from './recognition-client.types.js';
+import { TranscriptionResultV1, MetadataResultV1, ErrorResultV1 } from '@recog/shared-types';
+/**
+ * Maps ClientState to RecordingStatus for VGF state
+ */
+export declare function mapClientStateToRecordingStatus(clientState: ClientState): string;
+/**
+ * Creates a VGF state from transcription result
+ */
+export declare function mapTranscriptionResultToState(currentState: RecognitionState, result: TranscriptionResultV1, isRecording: boolean): RecognitionState;
+/**
+ * Maps metadata result to update state timestamps
+ */
+export declare function mapMetadataToState(currentState: RecognitionState, metadata: MetadataResultV1): RecognitionState;
+/**
+ * Maps error to state
+ */
+export declare function mapErrorToState(currentState: RecognitionState, error: ErrorResultV1): RecognitionState;
+/**
+ * Creates initial VGF state from client config
+ */
+export declare function createVGFStateFromConfig(config: IRecognitionClientConfig): RecognitionState;
+/**
+ * Updates state when recording stops
+ */
+export declare function updateStateOnStop(currentState: RecognitionState): RecognitionState;
+/**
+ * Updates state when client becomes ready
+ */
+export declare function updateStateOnReady(currentState: RecognitionState): RecognitionState;
+/**
+ * Parses function call from transcript (STEP 3 support)
+ * This is a placeholder - actual implementation would use NLP/LLM
+ */
+export declare function extractFunctionCallFromTranscript(transcript: string, gameContext?: any): {
+    metadata?: string;
+    confidence?: number;
+} | null;
+/**
+ * Updates state with function call results (STEP 3)
+ */
+export declare function updateStateWithFunctionCall(currentState: RecognitionState, functionCall: {
+    metadata?: string;
+    confidence?: number;
+}): RecognitionState;
+//# sourceMappingURL=vgf-recognition-mapper.d.ts.map

package/dist/vgf-recognition-mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vgf-recognition-mapper.d.ts","sourceRoot":"","sources":["../src/vgf-recognition-mapper.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACH,gBAAgB,EAInB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACH,WAAW,EACX,wBAAwB,EAC3B,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACH,qBAAqB,EACrB,gBAAgB,EAChB,aAAa,EAEhB,MAAM,qBAAqB,CAAC;AAE7B;;GAEG;AACH,wBAAgB,+BAA+B,CAAC,WAAW,EAAE,WAAW,GAAG,MAAM,CAmBhF;AAED;;GAEG;AACH,wBAAgB,6BAA6B,CACzC,YAAY,EAAE,gBAAgB,EAC9B,MAAM,EAAE,qBAAqB,EAC7B,WAAW,EAAE,OAAO,GACrB,gBAAgB,CAgDlB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAC9B,YAAY,EAAE,gBAAgB,EAC9B,QAAQ,EAAE,gBAAgB,GAC3B,gBAAgB,CAYlB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC3B,YAAY,EAAE,gBAAgB,EAC9B,KAAK,EAAE,aAAa,GACrB,gBAAgB,CAOlB;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,wBAAwB,GAAG,gBAAgB,CAU3F;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,gBAAgB,GAAG,gBAAgB,CAMlF;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,gBAAgB,GAAG,gBAAgB,CAKnF;AAED;;;GAGG;AACH,wBAAgB,iCAAiC,CAC7C,UAAU,EAAE,MAAM,EAClB,WAAW,CAAC,EAAE,GAAG,GAClB;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAiBnD;AAED;;GAEG;AACH,wBAAgB,2BAA2B,CACvC,YAAY,EAAE,gBAAgB,EAC9B,YAAY,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GACzD,gBAAgB,CAOlB"}

package/dist/vgf-recognition-state.d.ts

@@ -0,0 +1,82 @@
+import { z } from "zod";
+/**
+ * VGF-style state schema for game-side recognition state/results management.
+ *
+ * This schema provides a standardized way for game developers to manage
+ * voice recognition state and results in their applications. It supports:
+ *
+ * STEP 1: Basic transcription flow
+ * STEP 2: Mic auto-stop upon correct answer (using partial transcripts)
+ * STEP 3: Semantic/function-call outcomes for game actions
+ *
+ * Ideally this should be part of a more centralized shared type library to free
+ * game developers and provide helper functions (VGF? Platform SDK?).
+ */
+export declare const RecognitionVGFStateSchema: z.ZodObject<{
+    audioUtteranceId: z.ZodString;
+    startRecordingStatus: z.ZodOptional<z.ZodString>;
+    transcriptionStatus: z.ZodOptional<z.ZodString>;
+    finalTranscript: z.ZodOptional<z.ZodString>;
+    finalConfidence: z.ZodOptional<z.ZodNumber>;
+    asrConfig: z.ZodOptional<z.ZodString>;
+    startRecordingTimestamp: z.ZodOptional<z.ZodString>;
+    finalRecordingTimestamp: z.ZodOptional<z.ZodString>;
+    finalTranscriptionTimestamp: z.ZodOptional<z.ZodString>;
+    pendingTranscript: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    pendingConfidence: z.ZodOptional<z.ZodNumber>;
+    functionCallMetadata: z.ZodOptional<z.ZodString>;
+    functionCallConfidence: z.ZodOptional<z.ZodNumber>;
+    finalFunctionCallTimestamp: z.ZodOptional<z.ZodString>;
+    promptSlotMap: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString, "many">>>;
+}, "strip", z.ZodTypeAny, {
+    audioUtteranceId: string;
+    pendingTranscript: string;
+    startRecordingStatus?: string | undefined;
+    transcriptionStatus?: string | undefined;
+    finalTranscript?: string | undefined;
+    finalConfidence?: number | undefined;
+    asrConfig?: string | undefined;
+    startRecordingTimestamp?: string | undefined;
+    finalRecordingTimestamp?: string | undefined;
+    finalTranscriptionTimestamp?: string | undefined;
+    pendingConfidence?: number | undefined;
+    functionCallMetadata?: string | undefined;
+    functionCallConfidence?: number | undefined;
+    finalFunctionCallTimestamp?: string | undefined;
+    promptSlotMap?: Record<string, string[]> | undefined;
+}, {
+    audioUtteranceId: string;
+    startRecordingStatus?: string | undefined;
+    transcriptionStatus?: string | undefined;
+    finalTranscript?: string | undefined;
+    finalConfidence?: number | undefined;
+    asrConfig?: string | undefined;
+    startRecordingTimestamp?: string | undefined;
+    finalRecordingTimestamp?: string | undefined;
+    finalTranscriptionTimestamp?: string | undefined;
+    pendingTranscript?: string | undefined;
+    pendingConfidence?: number | undefined;
+    functionCallMetadata?: string | undefined;
+    functionCallConfidence?: number | undefined;
+    finalFunctionCallTimestamp?: string | undefined;
+    promptSlotMap?: Record<string, string[]> | undefined;
+}>;
+export type RecognitionState = z.infer<typeof RecognitionVGFStateSchema>;
+export declare const RecordingStatus: {
+    readonly NOT_READY: "NOT_READY";
+    readonly READY: "READY";
+    readonly RECORDING: "RECORDING";
+    readonly FINISHED: "FINISHED";
+};
+export type RecordingStatusType = typeof RecordingStatus[keyof typeof RecordingStatus];
+export declare const TranscriptionStatus: {
+    readonly NOT_STARTED: "NOT_STARTED";
+    readonly IN_PROGRESS: "IN_PROGRESS";
+    readonly FINALIZED: "FINALIZED";
+    readonly ABORTED: "ABORTED";
+    readonly ERROR: "ERROR";
+};
+export type TranscriptionStatusType = typeof TranscriptionStatus[keyof typeof TranscriptionStatus];
+export declare function createInitialRecognitionState(audioUtteranceId: string): RecognitionState;
+export declare function isValidRecordingStatusTransition(from: string | undefined, to: string): boolean;
+//# sourceMappingURL=vgf-recognition-state.d.ts.map

package/dist/vgf-recognition-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vgf-recognition-state.d.ts","sourceRoot":"","sources":["../src/vgf-recognition-state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0BpC,CAAA;AAEF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAA;AAGxE,eAAO,MAAM,eAAe;;;;;CAKlB,CAAA;AAEV,MAAM,MAAM,mBAAmB,GAAG,OAAO,eAAe,CAAC,MAAM,OAAO,eAAe,CAAC,CAAA;AAEtF,eAAO,MAAM,mBAAmB;;;;;;CAMtB,CAAA;AAEV,MAAM,MAAM,uBAAuB,GAAG,OAAO,mBAAmB,CAAC,MAAM,OAAO,mBAAmB,CAAC,CAAA;AAGlG,wBAAgB,6BAA6B,CAAC,gBAAgB,EAAE,MAAM,GAAG,gBAAgB,CAOxF;AAGD,wBAAgB,gCAAgC,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAa9F"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volley/recognition-client-sdk",
-  "version": "0.1.255",
+  "version": "0.1.294",
   "description": "Recognition Service TypeScript/Node.js Client SDK",
   "type": "module",
   "main": "dist/index.js",
@@ -32,8 +32,8 @@
   },
   "dependencies": {
     "uuid": "^11.0.0",
-    "ws": "^8.13.0",
-    "zod": "^3.22.4"
+    "ws": "8.18.3",
+    "zod": "~3.22.4"
   },
   "devDependencies": {
     "@semantic-release/changelog": "^6.0.3",
@@ -51,12 +51,11 @@
     "jest": "^29.6.1",
     "semantic-release": "^25.0.1",
     "ts-jest": "^29.4.5",
-    "tsup": "^8.5.0",
     "typescript": "^5.1.6",
     "@recog/shared-config": "1.0.0",
     "@recog/websocket": "1.0.0",
-    "@recog/shared-utils": "1.0.0",
-    "@recog/shared-types": "1.0.0"
+    "@recog/shared-types": "1.0.0",
+    "@recog/shared-utils": "1.0.0"
   },
   "keywords": [
     "recognition",
@@ -65,8 +64,8 @@
     "speech"
   ],
   "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
+    "build": "node build.mjs",
+    "dev": "node build.mjs --watch",
     "test": "jest --passWithNoTests",
     "lint": "eslint src --ext .ts"
   }

package/src/index.ts

@@ -76,6 +76,7 @@ export { AudioEncoding } from '@recog/websocket';
 export {
   // Recognition context types
   type GameContextV1,
+  type SlotMap,
   RecognitionContextTypeV1,
   ControlSignalTypeV1,
   ControlSignalTypeV1 as ControlSignal,  // Alias for backward compatibility
@@ -86,10 +87,13 @@ export {
   type MetadataResultV1,
   type ErrorResultV1,
   RecognitionResultTypeV1,
+  ClientControlActionV1,
 
   // ASR configuration types
   type ASRRequestConfig,
   type ASRRequestV1,
+  FinalTranscriptStability,
+  createDefaultASRConfig,
   RecognitionProvider,
   DeepgramModel,
   GoogleModel,

package/src/recognition-client.spec.ts

@@ -4,6 +4,7 @@
 
 import { RealTimeTwoWayWebSocketRecognitionClient } from './recognition-client';
 import { ClientState } from './recognition-client.types';
+import { RecognitionResultTypeV1 } from '@recog/shared-types';
 import { WebSocket as MockWebSocket } from 'ws';
 
 // Mock WebSocket
@@ -581,12 +582,14 @@ describe('RealTimeTwoWayWebSocketRecognitionClient', () => {
         logger: mockLogger
       });
 
-      // Create a mock Blob that throws on arrayBuffer()
-      const badBlob: any = {
-        arrayBuffer: jest.fn().mockRejectedValue(new Error('Conversion failed'))
-      };
+      // Create a real Blob but spy on arrayBuffer to make it fail
+      const audioData = new Uint8Array([1, 2, 3, 4]);
+      const badBlob = new Blob([audioData], { type: 'audio/raw' });
+
+      // Mock arrayBuffer to reject
+      jest.spyOn(badBlob, 'arrayBuffer').mockRejectedValue(new Error('Conversion failed'));
 
-      testClient.sendAudio(badBlob as Blob);
+      testClient.sendAudio(badBlob);
 
       // Wait for error handling
       await new Promise(resolve => setTimeout(resolve, 100));
@@ -623,14 +626,10 @@ describe('RealTimeTwoWayWebSocketRecognitionClient', () => {
     it('should use FileReader fallback when blob.arrayBuffer not available (Smart TV path)', async () => {
       const audioData = new Uint8Array([1, 2, 3, 4]);
 
-      // Create a mock Blob-like object without arrayBuffer (simulates old Smart TV)
-      const blobLike = {
-        size: audioData.length,
-        type: 'audio/raw',
-        // No arrayBuffer method - will trigger FileReader path
-      };
+      // Create a real Blob
+      const blob = new Blob([audioData], { type: 'audio/raw' });
 
-      // Mock FileReader
+      // Mock FileReader BEFORE removing arrayBuffer
       const mockReadAsArrayBuffer = jest.fn();
       const originalFileReader = (global as any).FileReader;
 
@@ -651,14 +650,21 @@ describe('RealTimeTwoWayWebSocketRecognitionClient', () => {
         }, 10);
       });
 
-      client.sendAudio(blobLike as Blob);
+      // Remove arrayBuffer method to simulate old Smart TV (must be done after blob creation)
+      Object.defineProperty(blob, 'arrayBuffer', {
+        value: undefined,
+        writable: true,
+        configurable: true
+      });
+
+      client.sendAudio(blob);
 
       // Wait for FileReader async conversion
       await new Promise(resolve => setTimeout(resolve, 150));
 
       // Should have used FileReader
       expect((global as any).FileReader).toHaveBeenCalled();
-      expect(mockReadAsArrayBuffer).toHaveBeenCalledWith(blobLike);
+      expect(mockReadAsArrayBuffer).toHaveBeenCalledWith(blob);
 
       // Should have buffered successfully
       const stats = client.getStats();
@@ -766,4 +772,131 @@ describe('RealTimeTwoWayWebSocketRecognitionClient', () => {
     });
     messageHandler(readyMessage);
   }
+
+  describe('stopAbnormally', () => {
+    beforeEach(() => {
+      // Recreate client with fresh mocks
+      jest.clearAllMocks();
+
+      client = new RealTimeTwoWayWebSocketRecognitionClient({
+        url: 'ws://localhost:3000',
+        onTranscript: jest.fn(),
+        onError: jest.fn(),
+        onConnected: jest.fn(),
+        onDisconnected: jest.fn()
+      });
+
+      // Access the mock WebSocket through the MockWebSocket constructor
+      const MockWsConstructor = MockWebSocket as jest.MockedClass<typeof MockWebSocket>;
+      mockWs = MockWsConstructor.mock.results[MockWsConstructor.mock.results.length - 1]?.value;
+
+      // Ensure mockWs has necessary methods
+      if (mockWs) {
+        mockWs.on = mockWs.on || jest.fn().mockReturnThis();
+        mockWs.send = mockWs.send || jest.fn();
+        mockWs.close = mockWs.close || jest.fn();
+        mockWs.readyState = MockWebSocket.CONNECTING;
+      }
+    });
+
+    it('should immediately close WebSocket connection', async () => {
+      await setupReadyClient();
+      expect(client.getState()).toBe(ClientState.READY);
+
+      client.stopAbnormally();
+
+      expect(mockWs.close).toHaveBeenCalledWith(1000, 'Client abnormal stop');
+    });
+
+    it('should update state to STOPPED', async () => {
+      await setupReadyClient();
+
+      client.stopAbnormally();
+
+      expect(client.getState()).toBe(ClientState.STOPPED);
+    });
+
+    it('should work from any state', () => {
+      // Test from INITIAL state
+      expect(client.getState()).toBe(ClientState.INITIAL);
+      client.stopAbnormally();
+      expect(client.getState()).toBe(ClientState.STOPPED);
+    });
+
+    it('should clean up resources', async () => {
+      await setupReadyClient();
+
+      // Send some audio to populate buffers
+      client.sendAudio(new ArrayBuffer(1000));
+
+      // Verify audio was sent
+      const statsBefore = client.getStats();
+      expect(statsBefore.audioBytesSent).toBeGreaterThan(0);
+
+      client.stopAbnormally();
+
+      // Cleanup resets stats
+      const statsAfter = client.getStats();
+      expect(statsAfter.audioBytesSent).toBe(0);
+      expect(statsAfter.audioChunksSent).toBe(0);
+    });
+
+    it('should not send stop signal to server (immediate disconnect)', async () => {
+      await setupReadyClient();
+      jest.clearAllMocks(); // Clear connection setup messages
+
+      client.stopAbnormally();
+
+      // Should NOT send stop recording signal (unlike stopRecording)
+      // Only closes the WebSocket
+      expect(mockWs.send).not.toHaveBeenCalled();
+      expect(mockWs.close).toHaveBeenCalled();
+    });
+
+    it('should differ from stopRecording behavior', async () => {
+      await setupReadyClient();
+
+      // stopRecording sends control signal and waits
+      jest.clearAllMocks();
+      const stopPromise = client.stopRecording();
+
+      // Verify control signal was sent
+      expect(mockWs.send).toHaveBeenCalled();
+      const sendCall = mockWs.send.mock.calls[0][0];
+      const message = JSON.parse(sendCall);
+      expect(message.data.signal).toBe('STOP_RECORDING');
+
+      // Complete the stop
+      const messageHandler = mockWs.on.mock.calls.find((call: any[]) => call[0] === 'message')[1];
+      messageHandler(JSON.stringify({
+        v: 1,
+        type: 'message',
+        data: {
+          type: RecognitionResultTypeV1.TRANSCRIPTION,
+          is_finished: true,
+          finalTranscript: 'test'
+        }
+      }));
+      await stopPromise;
+
+      // Now test stopAbnormally
+      await setupReadyClient();
+      jest.clearAllMocks();
+
+      client.stopAbnormally();
+
+      // stopAbnormally does NOT send messages, just closes
+      expect(mockWs.send).not.toHaveBeenCalled();
+      expect(mockWs.close).toHaveBeenCalled();
+    });
+
+    it('should be idempotent - safe to call multiple times', () => {
+      client.stopAbnormally();
+      expect(client.getState()).toBe(ClientState.STOPPED);
+
+      // Call again - should not throw
+      expect(() => client.stopAbnormally()).not.toThrow();
+      expect(client.getState()).toBe(ClientState.STOPPED);
+    });
+  });
 });

package/src/recognition-client.ts

@@ -544,6 +544,29 @@ export class RealTimeTwoWayWebSocketRecognitionClient
     });
   }
 
+  stopAbnormally(): void {
+    // Guard: If already in terminal state, do nothing
+    if (this.state === ClientState.STOPPED || this.state === ClientState.FAILED) {
+      this.log('debug', 'stopAbnormally called but already in terminal state', { state: this.state });
+      return;
+    }
+
+    this.log('warn', 'Abnormal stop requested - closing connection immediately', { state: this.state });
+
+    // Update state to STOPPED (skip STOPPING)
+    this.state = ClientState.STOPPED;
+
+    // Clean up resources
+    this.cleanup();
+
+    // Close WebSocket connection immediately
+    // Code 1000 = Normal Closure (even though abnormal for us, it's normal for WebSocket spec)
+    // Type assertion needed because closeConnection is a newly added protected method
+    (this as any).closeConnection(1000, 'Client abnormal stop');
+
+    // Note: onDisconnected will be called by WebSocket close event
+    // which will call cleanup again (idempotent) and trigger onDisconnected callback
+  }
 
   getAudioUtteranceId(): string {
     return this.config.audioUtteranceId;
@@ -627,6 +650,10 @@ export class RealTimeTwoWayWebSocketRecognitionClient
         interimResults: this.config.asrRequestConfig.interimResults ?? false,
         // Auto-enable useContext if gameContext is provided, or use explicit value if set
         useContext: this.config.asrRequestConfig.useContext ?? !!this.config.gameContext,
+        // Include finalTranscriptStability if provided (it's already a string enum)
+        ...(this.config.asrRequestConfig.finalTranscriptStability && {
+          finalTranscriptStability: this.config.asrRequestConfig.finalTranscriptStability
+        }),
         ...(debugCommand && { debugCommand })
       };
 

package/src/recognition-client.types.ts

@@ -220,6 +220,25 @@ export interface IRecognitionClient {
    */
   stopRecording(): Promise<void>;
 
+  /**
+   * Force stop and immediately close connection without waiting for server
+   *
+   * WARNING: This is an abnormal shutdown that bypasses the graceful stop flow:
+   * - Does NOT wait for server to process remaining audio
+   * - Does NOT receive final transcript from server
+   * - Immediately closes WebSocket connection
+   * - Cleans up resources (buffers, listeners)
+   *
+   * Use Cases:
+   * - User explicitly cancels/abandons session
+   * - Timeout scenarios where waiting is not acceptable
+   * - Need immediate cleanup and can't wait for server
+   *
+   * RECOMMENDED: Use stopRecording() for normal shutdown.
+   * Only use this when immediate disconnection is required.
+   */
+  stopAbnormally(): void;
+
   /**
    * Get the audio utterance ID for this session
    * Available immediately after client construction.