@volley/recognition-client-sdk/src/utils/url-builder.ts

Recognition Service TypeScript/Node.js Client SDK

/**
 * URL Builder for Recognition Client
 * Handles WebSocket URL construction with query parameters
 */

import { getRecognitionServiceBase } from '@recog/shared-config';
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 function buildWebSocketUrl(config: UrlBuilderConfig): string {
  // Determine base URL based on precedence: url > stage > default production
  let baseUrl: string;

  if (config.url) {
    // Explicit URL takes precedence
    baseUrl = config.url;
  } else if (config.stage) {
    // Use stage to build URL
    const stageBase = getRecognitionServiceBase(config.stage);
    baseUrl = `${stageBase.wsBase}/ws/v1/recognize`;
  } else {
    // Default to production if neither provided
    const defaultBase = getRecognitionServiceBase('production');
    baseUrl = `${defaultBase.wsBase}/ws/v1/recognize`;
  }

  // Build URL - add all optional identification parameters
  const url = new URL(baseUrl);

  // Add audioUtteranceId as query parameter (required for server to recognize it)
  url.searchParams.set('audioUtteranceId', config.audioUtteranceId);

  // Add callback URLs if provided (for server-side notifications)
  if (config.callbackUrls && config.callbackUrls.length > 0) {
    // Serialize as JSON for complex structure
    url.searchParams.set('callbackUrls', JSON.stringify(config.callbackUrls));
  }

  // Add user/session/device/account identification if provided
  if (config.userId) {
    url.searchParams.set('userId', config.userId);
  }
  if (config.gameSessionId) {
    url.searchParams.set('gameSessionId', config.gameSessionId);
  }
  if (config.deviceId) {
    url.searchParams.set('deviceId', config.deviceId);
  }
  if (config.accountId) {
    url.searchParams.set('accountId', config.accountId);
  }
  if (config.questionAnswerId) {
    url.searchParams.set('questionAnswerId', config.questionAnswerId);
  }
  if (config.platform) {
    url.searchParams.set('platform', config.platform);
  }

  // Add gameId and gamePhase if provided from gameContext
  if (config.gameContext) {
    url.searchParams.set('gameId', config.gameContext.gameId);
    url.searchParams.set('gamePhase', config.gameContext.gamePhase);
  }

  return url.toString();
}