@sayna-ai/node-sdk 0.0.19 → 0.0.20

package/README.md

@@ -240,14 +240,24 @@ Registers a callback for error messages.
 
 Registers a callback for participant messages.
 
+### `client.registerOnParticipantConnected(callback)`
+
+Registers a callback for participant connection events.
+
 ### `client.registerOnParticipantDisconnected(callback)`
 
 Registers a callback for participant disconnection events.
 
+### `client.registerOnTrackSubscribed(callback)`
+
+Registers a callback for track subscription events.
+
 ### `client.registerOnTtsPlaybackComplete(callback)`
 
 Registers a callback for TTS playback completion events.
 
+Unknown or malformed websocket control messages are logged and ignored so protocol drift does not break the client receive loop. Actual server `error` messages still reach `client.registerOnError(callback)`.
+
 ### `await client.speak(text, flush?, allowInterruption?)`
 
 Sends text to be synthesized as speech.

package/dist/index.cjs

@@ -128,7 +128,9 @@ class SaynaClient {
   ttsCallback;
   errorCallback;
   messageCallback;
+  participantConnectedCallback;
   participantDisconnectedCallback;
+  trackSubscribedCallback;
   ttsPlaybackCompleteCallback;
   sipTransferErrorCallback;
   readyPromiseResolve;
@@ -157,7 +159,7 @@ class SaynaClient {
     if (this.isConnected) {
       return;
     }
-    const wsUrl = this.url.replace(/^https:\/\//, "wss://").replace(/^http:\/\//, "ws://") + (this.url.endsWith("/") ? "ws" : "/ws");
+    const wsUrl = this.getWebSocketUrl();
     return new Promise((resolve, reject) => {
       this.readyPromiseResolve = resolve;
       this.readyPromiseReject = reject;
@@ -212,27 +214,30 @@ class SaynaClient {
     try {
       if (event.data instanceof Blob || event.data instanceof ArrayBuffer) {
         const buffer = event.data instanceof Blob ? await event.data.arrayBuffer() : event.data;
-        if (this.ttsCallback) {
-          await this.ttsCallback(buffer);
-        }
+        await this.invokeCallback(this.ttsCallback, buffer, "TTS audio");
       } else {
         if (typeof event.data !== "string") {
-          throw new Error("Expected string data for JSON messages");
+          this.logProtocolWarning("Ignoring websocket message with unsupported non-binary payload type", event.data);
+          return;
+        }
+        let data;
+        try {
+          data = JSON.parse(event.data);
+        } catch (error) {
+          this.logProtocolWarning(`Ignoring invalid websocket JSON: ${this.describeError(error)}`, event.data);
+          return;
         }
-        const data = JSON.parse(event.data);
         await this.handleJsonMessage(data);
       }
     } catch (error) {
-      if (this.errorCallback) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        await this.errorCallback({
-          type: "error",
-          message: `Failed to process message: ${errorMessage}`
-        });
-      }
+      await this.reportHandlerError("WebSocket message", error);
     }
   }
-  async handleJsonMessage(data) {
+  async handleJsonMessage(raw) {
+    const data = this.parseIncomingMessage(raw);
+    if (!data) {
+      return;
+    }
     const messageType = data.type;
     try {
       switch (messageType) {
@@ -250,72 +255,246 @@ class SaynaClient {
           break;
         }
         case "stt_result": {
-          const sttResult = data;
-          if (this.sttCallback) {
-            await this.sttCallback(sttResult);
-          }
+          await this.invokeCallback(this.sttCallback, data, "STT result");
           break;
         }
         case "error": {
-          const errorMsg = data;
-          if (this.errorCallback) {
-            await this.errorCallback(errorMsg);
-          }
+          await this.invokeCallback(this.errorCallback, data, "error");
           if (this.readyPromiseReject && !this.isReady) {
-            this.readyPromiseReject(new SaynaServerError(errorMsg.message));
+            this.readyPromiseReject(new SaynaServerError(data.message));
           }
           break;
         }
         case "sip_transfer_error": {
-          const sipTransferError = data;
           if (this.sipTransferErrorCallback) {
-            await this.sipTransferErrorCallback(sipTransferError);
+            await this.invokeCallback(this.sipTransferErrorCallback, data, "SIP transfer error");
           } else if (this.errorCallback) {
             await this.errorCallback({
               type: "error",
-              message: sipTransferError.message
+              message: data.message
             });
           }
           break;
         }
         case "message": {
-          const messageData = data;
-          if (this.messageCallback) {
-            await this.messageCallback(messageData.message);
-          }
+          await this.invokeCallback(this.messageCallback, data.message, "message");
+          break;
+        }
+        case "participant_connected": {
+          await this.invokeCallback(this.participantConnectedCallback, data.participant, "participant connected");
           break;
         }
         case "participant_disconnected": {
-          const participantMsg = data;
-          if (this.participantDisconnectedCallback) {
-            await this.participantDisconnectedCallback(participantMsg.participant);
-          }
+          await this.invokeCallback(this.participantDisconnectedCallback, data.participant, "participant disconnected");
           break;
         }
-        case "tts_playback_complete": {
-          const ttsPlaybackCompleteMsg = data;
-          if (this.ttsPlaybackCompleteCallback) {
-            await this.ttsPlaybackCompleteCallback(ttsPlaybackCompleteMsg.timestamp);
-          }
+        case "track_subscribed": {
+          await this.invokeCallback(this.trackSubscribedCallback, data.track, "track subscribed");
           break;
         }
-        default: {
-          const unknownMessage = data;
-          const errorMessage = `Unknown message type received: ${unknownMessage.type}`;
-          if (this.errorCallback) {
-            await this.errorCallback({ type: "error", message: errorMessage });
-          } else {
-            console.warn(errorMessage);
-          }
+        case "tts_playback_complete": {
+          await this.invokeCallback(this.ttsPlaybackCompleteCallback, data.timestamp, "TTS playback complete");
+          break;
         }
       }
     } catch (error) {
-      if (this.errorCallback) {
-        await this.errorCallback({
-          type: "error",
-          message: `Handler error: ${error instanceof Error ? error.message : String(error)}`
-        });
+      await this.reportHandlerError(`"${messageType}"`, error);
+    }
+  }
+  getWebSocketUrl() {
+    const wsUrl = this.url.replace(/^https:\/\//, "wss://").replace(/^http:\/\//, "ws://");
+    const parsedUrl = new URL(wsUrl);
+    if (!parsedUrl.pathname.endsWith("/ws")) {
+      parsedUrl.pathname = parsedUrl.pathname.endsWith("/") ? `${parsedUrl.pathname}ws` : `${parsedUrl.pathname}/ws`;
+    }
+    return parsedUrl.toString();
+  }
+  parseIncomingMessage(raw) {
+    if (!this.isJsonObject(raw)) {
+      this.logProtocolWarning("Ignoring websocket payload because it is not a JSON object", raw);
+      return;
+    }
+    const messageType = raw.type;
+    if (typeof messageType !== "string") {
+      this.logProtocolWarning('Ignoring websocket payload without a string "type" field', raw);
+      return;
+    }
+    try {
+      switch (messageType) {
+        case "ready":
+          return {
+            type: "ready",
+            stream_id: this.getOptionalString(raw, "stream_id"),
+            livekit_room_name: this.getOptionalString(raw, "livekit_room_name"),
+            livekit_url: this.getOptionalString(raw, "livekit_url"),
+            sayna_participant_identity: this.getOptionalString(raw, "sayna_participant_identity"),
+            sayna_participant_name: this.getOptionalString(raw, "sayna_participant_name")
+          };
+        case "stt_result":
+          return {
+            type: "stt_result",
+            transcript: this.getRequiredString(raw, "transcript"),
+            is_final: this.getRequiredBoolean(raw, "is_final"),
+            is_speech_final: this.getRequiredBoolean(raw, "is_speech_final"),
+            confidence: this.getRequiredNumber(raw, "confidence")
+          };
+        case "error":
+          return {
+            type: "error",
+            message: this.getRequiredString(raw, "message")
+          };
+        case "sip_transfer_error":
+          return {
+            type: "sip_transfer_error",
+            message: this.getRequiredString(raw, "message")
+          };
+        case "message":
+          return {
+            type: "message",
+            message: this.parseSaynaMessage(raw, "message")
+          };
+        case "participant_connected":
+          return {
+            type: "participant_connected",
+            participant: this.parseParticipant(raw, "participant")
+          };
+        case "participant_disconnected":
+          return {
+            type: "participant_disconnected",
+            participant: this.parseParticipant(raw, "participant")
+          };
+        case "track_subscribed":
+          return {
+            type: "track_subscribed",
+            track: this.parseTrack(raw, "track")
+          };
+        case "tts_playback_complete":
+          return {
+            type: "tts_playback_complete",
+            timestamp: this.getRequiredNumber(raw, "timestamp")
+          };
+        default:
+          this.logProtocolWarning(`Ignoring unknown websocket message type "${messageType}"`, raw);
+          return;
       }
+    } catch (error) {
+      this.logProtocolWarning(`Ignoring malformed websocket message "${messageType}": ${this.describeError(error)}`, raw);
+      return;
+    }
+  }
+  parseSaynaMessage(container, fieldName) {
+    const message = this.getRequiredObject(container, fieldName);
+    return {
+      message: this.getOptionalString(message, "message"),
+      data: this.getOptionalString(message, "data"),
+      identity: this.getRequiredString(message, "identity"),
+      topic: this.getRequiredString(message, "topic"),
+      room: this.getRequiredString(message, "room"),
+      timestamp: this.getRequiredNumber(message, "timestamp")
+    };
+  }
+  parseParticipant(container, fieldName) {
+    const participant = this.getRequiredObject(container, fieldName);
+    return {
+      identity: this.getRequiredString(participant, "identity"),
+      name: this.getOptionalString(participant, "name"),
+      room: this.getRequiredString(participant, "room"),
+      timestamp: this.getRequiredNumber(participant, "timestamp")
+    };
+  }
+  parseTrack(container, fieldName) {
+    const track = this.getRequiredObject(container, fieldName);
+    const trackKind = this.getRequiredString(track, "track_kind");
+    if (trackKind !== "audio" && trackKind !== "video") {
+      throw new Error('Field "track_kind" must be either "audio" or "video"');
+    }
+    return {
+      identity: this.getRequiredString(track, "identity"),
+      name: this.getOptionalString(track, "name"),
+      track_kind: trackKind,
+      track_sid: this.getRequiredString(track, "track_sid"),
+      room: this.getRequiredString(track, "room"),
+      timestamp: this.getRequiredNumber(track, "timestamp")
+    };
+  }
+  getRequiredObject(container, fieldName) {
+    const value = container[fieldName];
+    if (!this.isJsonObject(value)) {
+      throw new Error(`Field "${fieldName}" must be an object`);
+    }
+    return value;
+  }
+  getRequiredString(container, fieldName) {
+    const value = container[fieldName];
+    if (typeof value !== "string") {
+      throw new Error(`Field "${fieldName}" must be a string`);
+    }
+    return value;
+  }
+  getOptionalString(container, fieldName) {
+    const value = container[fieldName];
+    if (typeof value === "undefined" || value === null) {
+      return;
+    }
+    if (typeof value !== "string") {
+      throw new Error(`Field "${fieldName}" must be a string when present`);
+    }
+    return value;
+  }
+  getRequiredBoolean(container, fieldName) {
+    const value = container[fieldName];
+    if (typeof value !== "boolean") {
+      throw new Error(`Field "${fieldName}" must be a boolean`);
+    }
+    return value;
+  }
+  getRequiredNumber(container, fieldName) {
+    const value = container[fieldName];
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+      throw new Error(`Field "${fieldName}" must be a finite number`);
+    }
+    return value;
+  }
+  isJsonObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+  }
+  logProtocolWarning(message, payload) {
+    console.warn(`${message}; payload=${this.safeStringify(payload)}`);
+  }
+  safeStringify(payload) {
+    try {
+      return JSON.stringify(payload);
+    } catch {
+      return String(payload);
+    }
+  }
+  describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+  async invokeCallback(callback, payload, label) {
+    if (!callback) {
+      return;
+    }
+    try {
+      await callback(payload);
+    } catch (error) {
+      await this.reportHandlerError(`${label} callback`, error);
+    }
+  }
+  async reportHandlerError(label, error) {
+    const message = `${label} failed: ${this.describeError(error)}`;
+    if (!this.errorCallback) {
+      console.error(message);
+      return;
+    }
+    try {
+      await this.errorCallback({
+        type: "error",
+        message
+      });
+    } catch (callbackError) {
+      console.error(message);
+      console.error(`error callback failed: ${this.describeError(callbackError)}`);
     }
   }
   createWebSocket(url) {
@@ -435,9 +614,15 @@ class SaynaClient {
   registerOnMessage(callback) {
     this.messageCallback = callback;
   }
+  registerOnParticipantConnected(callback) {
+    this.participantConnectedCallback = callback;
+  }
   registerOnParticipantDisconnected(callback) {
     this.participantDisconnectedCallback = callback;
   }
+  registerOnTrackSubscribed(callback) {
+    this.trackSubscribedCallback = callback;
+  }
   registerOnTtsPlaybackComplete(callback) {
     this.ttsPlaybackCompleteCallback = callback;
   }
@@ -879,4 +1064,4 @@ async function saynaConnect(url, sttConfig, ttsConfig, livekitConfig, withoutAud
   return client;
 }
 
-//# debugId=83EF29EA6526F17D64756E2164756E21
+//# debugId=5E4C5FDAA012925764756E2164756E21