@volley/recognition-client-sdk-node22 0.1.424

package/src/utils/message-handler.spec.ts

@@ -0,0 +1,311 @@
+/**
+ * Unit tests for MessageHandler
+ */
+
+import { MessageHandler, MessageHandlerCallbacks } from './message-handler.js';
+import { RecognitionResultTypeV1, ClientControlActionV1 } from '@recog/shared-types';
+
+describe('MessageHandler', () => {
+  let callbacks: MessageHandlerCallbacks;
+  let handler: MessageHandler;
+  let mockLogger: jest.Mock;
+
+  beforeEach(() => {
+    mockLogger = jest.fn();
+    callbacks = {
+      onTranscript: jest.fn(),
+      onFunctionCall: jest.fn(),
+      onMetadata: jest.fn(),
+      onError: jest.fn(),
+      onControlMessage: jest.fn(),
+      logger: mockLogger
+    };
+    handler = new MessageHandler(callbacks);
+  });
+
+  describe('handleMessage', () => {
+    it('should handle transcription message', () => {
+      const msg = {
+        v: 1,
+        type: 'recognition_result',
+        data: {
+          type: RecognitionResultTypeV1.TRANSCRIPTION,
+          transcript: 'hello world',
+          isFinal: true
+        }
+      };
+
+      handler.handleMessage(msg);
+      expect(callbacks.onTranscript).toHaveBeenCalledWith(msg.data);
+    });
+
+    it('should handle function call message', () => {
+      const msg = {
+        v: 1,
+        type: 'recognition_result',
+        data: {
+          type: RecognitionResultTypeV1.FUNCTION_CALL,
+          functionName: 'testFunction',
+          arguments: { arg1: 'value1' }
+        }
+      };
+
+      handler.handleMessage(msg);
+      expect(callbacks.onFunctionCall).toHaveBeenCalledWith(msg.data);
+    });
+
+    it('should handle metadata message', () => {
+      const msg = {
+        v: 1,
+        type: 'recognition_result',
+        data: {
+          type: RecognitionResultTypeV1.METADATA,
+          metadata: { key: 'value' }
+        }
+      };
+
+      handler.handleMessage(msg);
+      expect(callbacks.onMetadata).toHaveBeenCalledWith(msg.data);
+    });
+
+    it('should handle error message', () => {
+      const msg = {
+        v: 1,
+        type: 'recognition_result',
+        data: {
+          type: RecognitionResultTypeV1.ERROR,
+          error: 'test error',
+          code: 'TEST_ERROR'
+        }
+      };
+
+      handler.handleMessage(msg);
+      expect(callbacks.onError).toHaveBeenCalledWith(msg.data);
+    });
+
+    it('should handle client control message', () => {
+      const msg = {
+        v: 1,
+        type: 'recognition_result',
+        data: {
+          type: RecognitionResultTypeV1.CLIENT_CONTROL_MESSAGE,
+          action: ClientControlActionV1.STOP_RECORDING,
+          audioUtteranceId: 'test-utterance'
+        }
+      };
+
+      handler.handleMessage(msg);
+      expect(callbacks.onControlMessage).toHaveBeenCalledWith(msg.data);
+    });
+
+    it('should handle unknown message type', () => {
+      const msg = {
+        v: 1,
+        type: 'unknown_type',
+        data: {
+          type: 'unknown',
+          content: 'test'
+        }
+      };
+
+      handler.handleMessage(msg);
+      expect(mockLogger).toHaveBeenCalledWith(
+        'debug',
+        '[RecogSDK] Unknown message type',
+        expect.objectContaining({ type: 'unknown' })
+      );
+    });
+
+    it('should log all incoming messages', () => {
+      const msg = {
+        v: 1,
+        type: 'recognition_result',
+        data: {
+          type: RecognitionResultTypeV1.TRANSCRIPTION,
+          transcript: 'test'
+        }
+      };
+
+      handler.handleMessage(msg);
+      expect(mockLogger).toHaveBeenCalledWith(
+        'debug',
+        '[RecogSDK] Received WebSocket message',
+        expect.objectContaining({
+          msgType: 'recognition_result',
+          msgDataType: RecognitionResultTypeV1.TRANSCRIPTION
+        })
+      );
+    });
+
+    it('should handle primitive msg.data', () => {
+      const msg = {
+        v: 1,
+        type: 'recognition_result',
+        data: 'primitive string'
+      };
+
+      handler.handleMessage(msg);
+      expect(mockLogger).toHaveBeenCalledWith(
+        'error',
+        '[RecogSDK] Received primitive msg.data from server',
+        expect.objectContaining({
+          dataType: 'string',
+          data: 'primitive string'
+        })
+      );
+    });
+
+    it('should handle message without data field', () => {
+      const msg = {
+        v: 1,
+        type: RecognitionResultTypeV1.METADATA,
+        data: {
+          type: RecognitionResultTypeV1.METADATA,
+          metadata: { key: 'value' }
+        }
+      };
+
+      handler.handleMessage(msg);
+      expect(callbacks.onMetadata).toHaveBeenCalled();
+    });
+
+    it('should work without logger', () => {
+      const callbacksNoLogger = {
+        onTranscript: jest.fn(),
+        onFunctionCall: jest.fn(),
+        onMetadata: jest.fn(),
+        onError: jest.fn(),
+        onControlMessage: jest.fn()
+      };
+      const handlerNoLogger = new MessageHandler(callbacksNoLogger);
+
+      const msg = {
+        v: 1,
+        type: 'recognition_result',
+        data: {
+          type: RecognitionResultTypeV1.TRANSCRIPTION,
+          transcript: 'test'
+        }
+      };
+
+      expect(() => handlerNoLogger.handleMessage(msg)).not.toThrow();
+      expect(callbacksNoLogger.onTranscript).toHaveBeenCalled();
+    });
+  });
+
+  describe('setSessionStartTime', () => {
+    it('should set session start time', () => {
+      const startTime = Date.now();
+      handler.setSessionStartTime(startTime);
+
+      const metrics = handler.getMetrics();
+      expect(metrics.sessionStartTime).toBe(startTime);
+    });
+  });
+
+  describe('getMetrics', () => {
+    it('should return initial metrics', () => {
+      const metrics = handler.getMetrics();
+      expect(metrics).toEqual({
+        sessionStartTime: null,
+        firstTranscriptTime: null,
+        timeToFirstTranscript: null
+      });
+    });
+
+    it('should track time to first transcript', () => {
+      const startTime = Date.now();
+      handler.setSessionStartTime(startTime);
+
+      // Simulate delay before first transcript
+      const transcriptMsg = {
+        v: 1,
+        type: 'recognition_result',
+        data: {
+          type: RecognitionResultTypeV1.TRANSCRIPTION,
+          transcript: 'first transcript',
+          isFinal: false
+        }
+      };
+
+      handler.handleMessage(transcriptMsg);
+
+      const metrics = handler.getMetrics();
+      expect(metrics.sessionStartTime).toBe(startTime);
+      expect(metrics.firstTranscriptTime).toBeGreaterThanOrEqual(startTime);
+      expect(metrics.timeToFirstTranscript).toBeGreaterThanOrEqual(0);
+    });
+
+    it('should log time to first transcript', () => {
+      const startTime = Date.now();
+      handler.setSessionStartTime(startTime);
+
+      const transcriptMsg = {
+        v: 1,
+        type: 'recognition_result',
+        data: {
+          type: RecognitionResultTypeV1.TRANSCRIPTION,
+          transcript: 'first transcript'
+        }
+      };
+
+      handler.handleMessage(transcriptMsg);
+
+      expect(mockLogger).toHaveBeenCalledWith(
+        'debug',
+        '[RecogSDK] First transcript received',
+        expect.objectContaining({
+          timeToFirstTranscriptMs: expect.any(Number)
+        })
+      );
+    });
+
+    it('should only track first transcript time once', () => {
+      const startTime = Date.now();
+      handler.setSessionStartTime(startTime);
+
+      // First transcript
+      handler.handleMessage({
+        v: 1,
+        type: 'recognition_result',
+        data: {
+          type: RecognitionResultTypeV1.TRANSCRIPTION,
+          transcript: 'first'
+        }
+      });
+
+      const firstMetrics = handler.getMetrics();
+      const firstTranscriptTime = firstMetrics.firstTranscriptTime;
+
+      // Second transcript
+      handler.handleMessage({
+        v: 1,
+        type: 'recognition_result',
+        data: {
+          type: RecognitionResultTypeV1.TRANSCRIPTION,
+          transcript: 'second'
+        }
+      });
+
+      const secondMetrics = handler.getMetrics();
+      expect(secondMetrics.firstTranscriptTime).toBe(firstTranscriptTime);
+    });
+
+    it('should not track transcript time without session start', () => {
+      const transcriptMsg = {
+        v: 1,
+        type: 'recognition_result',
+        data: {
+          type: RecognitionResultTypeV1.TRANSCRIPTION,
+          transcript: 'test'
+        }
+      };
+
+      handler.handleMessage(transcriptMsg);
+
+      const metrics = handler.getMetrics();
+      expect(metrics.firstTranscriptTime).toBeNull();
+      expect(metrics.timeToFirstTranscript).toBeNull();
+    });
+  });
+});

package/src/utils/message-handler.ts

@@ -0,0 +1,131 @@
+/**
+ * Message Handler for Recognition Client
+ * Routes incoming WebSocket messages to appropriate callbacks
+ */
+
+import {
+  RecognitionResultTypeV1,
+  ClientControlActionV1,
+  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 class MessageHandler {
+  private firstTranscriptTime: number | null = null;
+  private sessionStartTime: number | null = null;
+  private callbacks: MessageHandlerCallbacks;
+
+  constructor(callbacks: MessageHandlerCallbacks) {
+    this.callbacks = callbacks;
+  }
+
+  /**
+   * Set session start time for performance tracking
+   */
+  setSessionStartTime(time: number): void {
+    this.sessionStartTime = time;
+  }
+
+  /**
+   * Handle incoming WebSocket message
+   */
+  handleMessage(msg: { v: number; type: string; data: any }): void {
+    // Log ALL incoming messages for debugging
+    if (this.callbacks.logger) {
+      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
+      });
+    }
+
+    // Safely check for type in msg.data - guard against primitives
+    // Log error if we receive primitive data (indicates server issue)
+    if (msg.data && typeof msg.data !== 'object') {
+      if (this.callbacks.logger) {
+        this.callbacks.logger('error', '[RecogSDK] Received primitive msg.data from server', {
+          dataType: typeof msg.data,
+          data: msg.data,
+          fullMessage: msg
+        });
+      }
+    }
+
+    const msgType = (msg.data && typeof msg.data === 'object' && 'type' in msg.data ? msg.data.type : undefined) || msg.type;
+    const msgData = msg.data || msg;
+
+    switch (msgType) {
+      case RecognitionResultTypeV1.TRANSCRIPTION:
+        this.handleTranscription(msgData as TranscriptionResultV1);
+        break;
+
+      case RecognitionResultTypeV1.FUNCTION_CALL:
+        this.callbacks.onFunctionCall(msgData as FunctionCallResultV1);
+        break;
+
+      case RecognitionResultTypeV1.METADATA:
+        this.callbacks.onMetadata(msgData as MetadataResultV1);
+        break;
+
+      case RecognitionResultTypeV1.ERROR:
+        this.callbacks.onError(msgData as ErrorResultV1);
+        break;
+
+      case RecognitionResultTypeV1.CLIENT_CONTROL_MESSAGE:
+        this.callbacks.onControlMessage(msgData as ClientControlMessageV1);
+        break;
+
+      default:
+        // Unknown message type - log if logger available
+        if (this.callbacks.logger) {
+          this.callbacks.logger('debug', '[RecogSDK] Unknown message type', { type: msgType });
+        }
+    }
+  }
+
+  /**
+   * Handle transcript message and track performance metrics
+   * @param result - The transcription result from the server
+   */
+  private handleTranscription(result: TranscriptionResultV1): void {
+    // Track time to first transcript
+    if (!this.firstTranscriptTime && this.sessionStartTime) {
+      this.firstTranscriptTime = Date.now();
+      const timeToFirstTranscript = this.firstTranscriptTime - this.sessionStartTime;
+
+      if (this.callbacks.logger) {
+        this.callbacks.logger('debug', '[RecogSDK] First transcript received', {
+          timeToFirstTranscriptMs: timeToFirstTranscript
+        });
+      }
+    }
+
+    this.callbacks.onTranscript(result);
+  }
+
+  /**
+   * Get performance metrics
+   */
+  getMetrics() {
+    return {
+      sessionStartTime: this.sessionStartTime,
+      firstTranscriptTime: this.firstTranscriptTime,
+      timeToFirstTranscript:
+        this.firstTranscriptTime && this.sessionStartTime
+          ? this.firstTranscriptTime - this.sessionStartTime
+          : null
+    };
+  }
+}

package/src/utils/url-builder.spec.ts

@@ -0,0 +1,252 @@
+/**
+ * Unit tests for URL Builder
+ */
+
+import { RecognitionContextTypeV1, STAGES } from '@recog/shared-types';
+
+// Mock the shared-config module BEFORE importing the module under test
+const mockGetRecognitionServiceBase = jest.fn();
+jest.mock('@recog/shared-config', () => ({
+  getRecognitionServiceBase: mockGetRecognitionServiceBase
+}));
+
+import { buildWebSocketUrl, UrlBuilderConfig } from './url-builder.js';
+
+describe('buildWebSocketUrl', () => {
+  const baseConfig: UrlBuilderConfig = {
+    audioUtteranceId: 'test-utterance-123'
+  };
+
+  beforeEach(() => {
+    // Clear and reset mock before each test
+    mockGetRecognitionServiceBase.mockClear();
+    mockGetRecognitionServiceBase.mockReturnValue({
+      wsBase: 'wss://recognition.volley.com'
+    });
+  });
+
+  it('should build URL with only audioUtteranceId', () => {
+    const url = buildWebSocketUrl(baseConfig);
+    expect(url).toContain('audioUtteranceId=test-utterance-123');
+  });
+
+  it('should use default production URL if neither url nor stage provided', () => {
+    const url = buildWebSocketUrl(baseConfig);
+    expect(url).toContain('wss://recognition.volley.com/ws/v1/recognize');
+    expect(mockGetRecognitionServiceBase).toHaveBeenCalledWith('production');
+  });
+
+  it('should use stage parameter to build URL', () => {
+    mockGetRecognitionServiceBase.mockReturnValue({
+      wsBase: 'wss://recognition-staging.volley.com'
+    });
+    const config = {
+      ...baseConfig,
+      stage: 'staging'
+    };
+    const url = buildWebSocketUrl(config);
+    expect(url).toContain('wss://recognition-staging.volley.com/ws/v1/recognize');
+    expect(mockGetRecognitionServiceBase).toHaveBeenCalledWith('staging');
+  });
+
+  it('should accept Stage enum as stage parameter', () => {
+    mockGetRecognitionServiceBase.mockReturnValue({
+      wsBase: 'wss://recognition-dev.volley.com'
+    });
+    const config = {
+      ...baseConfig,
+      stage: STAGES.DEV
+    };
+    const url = buildWebSocketUrl(config);
+    expect(url).toContain('wss://recognition-dev.volley.com/ws/v1/recognize');
+    expect(mockGetRecognitionServiceBase).toHaveBeenCalledWith(STAGES.DEV);
+  });
+
+  it('should prioritize url over stage when both provided', () => {
+    const config = {
+      ...baseConfig,
+      url: 'ws://localhost:3101/ws/v1/recognize',
+      stage: 'staging'
+    };
+    const url = buildWebSocketUrl(config);
+    expect(url).toContain('ws://localhost:3101/ws/v1/recognize');
+    // Mock should not be called when explicit URL is provided
+    expect(mockGetRecognitionServiceBase).not.toHaveBeenCalled();
+  });
+
+  it('should use custom URL if provided (backward compatibility)', () => {
+    const config = {
+      ...baseConfig,
+      url: 'ws://localhost:3101/ws/v1/recognize'
+    };
+    const url = buildWebSocketUrl(config);
+    expect(url).toContain('ws://localhost:3101/ws/v1/recognize');
+    // Mock should not be called when explicit URL is provided
+    expect(mockGetRecognitionServiceBase).not.toHaveBeenCalled();
+  });
+
+  it('should add userId to query parameters', () => {
+    const config = {
+      ...baseConfig,
+      userId: 'user-123'
+    };
+    const url = buildWebSocketUrl(config);
+    expect(url).toContain('userId=user-123');
+  });
+
+  it('should add gameSessionId to query parameters', () => {
+    const config = {
+      ...baseConfig,
+      gameSessionId: 'session-456'
+    };
+    const url = buildWebSocketUrl(config);
+    expect(url).toContain('gameSessionId=session-456');
+  });
+
+  it('should add deviceId to query parameters', () => {
+    const config = {
+      ...baseConfig,
+      deviceId: 'device-789'
+    };
+    const url = buildWebSocketUrl(config);
+    expect(url).toContain('deviceId=device-789');
+  });
+
+  it('should add accountId to query parameters', () => {
+    const config = {
+      ...baseConfig,
+      accountId: 'account-abc'
+    };
+    const url = buildWebSocketUrl(config);
+    expect(url).toContain('accountId=account-abc');
+  });
+
+  it('should add questionAnswerId to query parameters', () => {
+    const config = {
+      ...baseConfig,
+      questionAnswerId: 'qa-xyz'
+    };
+    const url = buildWebSocketUrl(config);
+    expect(url).toContain('questionAnswerId=qa-xyz');
+  });
+
+  it('should add platform to query parameters', () => {
+    const config = {
+      ...baseConfig,
+      platform: 'ios'
+    };
+    const url = buildWebSocketUrl(config);
+    expect(url).toContain('platform=ios');
+  });
+
+  it('should add gameId and gamePhase from gameContext', () => {
+    const config = {
+      ...baseConfig,
+      gameContext: {
+        type: RecognitionContextTypeV1.GAME_CONTEXT as const,
+        gameId: 'test-game',
+        gamePhase: 'test-phase'
+      }
+    };
+    const url = buildWebSocketUrl(config);
+    expect(url).toContain('gameId=test-game');
+    expect(url).toContain('gamePhase=test-phase');
+  });
+
+  it('should serialize callbackUrls as JSON', () => {
+    const callbackUrls = [
+      { url: 'https://example.com/callback', messageTypes: ['transcript'] },
+      { url: 'https://example.com/metadata', messageTypes: ['metadata'] }
+    ];
+    const config = {
+      ...baseConfig,
+      callbackUrls
+    };
+    const url = buildWebSocketUrl(config);
+    expect(url).toContain('callbackUrls=');
+    // Decode and verify JSON structure
+    const urlObj = new URL(url);
+    const callbackUrlsParam = urlObj.searchParams.get('callbackUrls');
+    expect(callbackUrlsParam).toBeDefined();
+    expect(JSON.parse(callbackUrlsParam!)).toEqual(callbackUrls);
+  });
+
+  it('should not add callbackUrls if empty array', () => {
+    const config = {
+      ...baseConfig,
+      callbackUrls: []
+    };
+    const url = buildWebSocketUrl(config);
+    expect(url).not.toContain('callbackUrls=');
+  });
+
+  it('should not add optional parameters if not provided', () => {
+    const url = buildWebSocketUrl(baseConfig);
+    expect(url).not.toContain('userId=');
+    expect(url).not.toContain('gameSessionId=');
+    expect(url).not.toContain('deviceId=');
+    expect(url).not.toContain('accountId=');
+    expect(url).not.toContain('questionAnswerId=');
+    expect(url).not.toContain('platform=');
+    expect(url).not.toContain('gameId=');
+    expect(url).not.toContain('gamePhase=');
+  });
+
+  it('should handle all parameters together', () => {
+    const config: UrlBuilderConfig = {
+      url: 'ws://localhost:3101/ws/v1/recognize',
+      audioUtteranceId: 'test-utterance-123',
+      userId: 'user-123',
+      gameSessionId: 'session-456',
+      deviceId: 'device-789',
+      accountId: 'account-abc',
+      questionAnswerId: 'qa-xyz',
+      platform: 'ios',
+      gameContext: {
+        type: RecognitionContextTypeV1.GAME_CONTEXT as const,
+        gameId: 'test-game',
+        gamePhase: 'test-phase'
+      },
+      callbackUrls: [
+        { url: 'https://example.com/callback', messageTypes: ['transcript'] }
+      ]
+    };
+
+    const url = buildWebSocketUrl(config);
+    expect(url).toContain('ws://localhost:3101/ws/v1/recognize');
+    expect(url).toContain('audioUtteranceId=test-utterance-123');
+    expect(url).toContain('userId=user-123');
+    expect(url).toContain('gameSessionId=session-456');
+    expect(url).toContain('deviceId=device-789');
+    expect(url).toContain('accountId=account-abc');
+    expect(url).toContain('questionAnswerId=qa-xyz');
+    expect(url).toContain('platform=ios');
+    expect(url).toContain('gameId=test-game');
+    expect(url).toContain('gamePhase=test-phase');
+    expect(url).toContain('callbackUrls=');
+  });
+
+  it('should properly encode special characters in parameters', () => {
+    const config = {
+      ...baseConfig,
+      userId: 'user@example.com',
+      platform: 'iOS 17.0'
+    };
+    const url = buildWebSocketUrl(config);
+    // URL should be properly encoded
+    expect(url).toBeDefined();
+    const urlObj = new URL(url);
+    expect(urlObj.searchParams.get('userId')).toBe('user@example.com');
+    expect(urlObj.searchParams.get('platform')).toBe('iOS 17.0');
+  });
+
+  it('should create valid URL object', () => {
+    const config = {
+      ...baseConfig,
+      userId: 'user-123'
+    };
+    const url = buildWebSocketUrl(config);
+    // Should not throw
+    expect(() => new URL(url)).not.toThrow();
+  });
+});