feat: adds support for speak fallback (#414)

* feat: adds support for speak fallback provider

* feat: simplifies speak provider approach

Author: jpvajda

src/lib/types/AgentLiveSchema.ts

@@ -1,7 +1,15 @@
 type Provider = { type: string } & Record<string, unknown>;
 
+type SpeakProvider = {
+  provider: Provider;
+  endpoint?: {
+    url: string;
+    headers?: Record<string, string>;
+  };
+};
+
 /**
- * @see https://developers.deepgram.com/reference/voicebot-api-phase-preview#settingsconfiguration
+ * @see https://developers.deepgram.com/docs/configure-voice-agent
  */
 interface AgentLiveSchema extends Record<string, unknown> {
   /**
@@ -42,15 +50,9 @@ interface AgentLiveSchema extends Record<string, unknown> {
     listen?: {
       provider: Provider;
     };
-    speak?: {
-      provider: Provider;
-      endpoint?: {
-        url: string;
-        headers?: Record<string, string>;
-      };
-    };
+    speak?: SpeakProvider | SpeakProvider[];
     /**
-     * @see https://developers.deepgram.com/reference/voicebot-api-phase-preview#supported-llm-providers-and-models
+     * @see https://developers.deepgram.com/docs/voice-agent-tts-models
      */
     think?: {
       provider: Provider;
@@ -81,4 +83,4 @@ interface AgentLiveSchema extends Record<string, unknown> {
   };
 }
 
-export type { AgentLiveSchema };
+export type { AgentLiveSchema, SpeakProvider };

tests/unit/live-client-message-handling.test.ts

@@ -537,32 +537,95 @@ describe("Unit Tests - Live Client Message Handling", () => {
       expect(mockConnection.send).toHaveBeenCalledWith(JSON.stringify({ type: "KeepAlive" }));
     });
 
-    it("should send injectUserMessage correctly", () => {
-      const content = "Hello! Can you hear me?";
-      client.injectUserMessage(content);
+    describe("speak provider configuration", () => {
+      it("should accept single provider", () => {
+        const config = {
+          audio: { input: { encoding: "linear16", sample_rate: 16000 } },
+          agent: {
+            speak: {
+              provider: { type: "deepgram", model: "aura-2-zeus-en" },
+            },
+          },
+        };
 
-      expect(mockConnection.send).toHaveBeenCalledWith(
-        JSON.stringify({ type: "InjectUserMessage", content })
-      );
+        client.configure(config);
+        expect(mockConnection.send).toHaveBeenCalledWith(
+          JSON.stringify({ type: "Settings", ...config })
+        );
+      });
+
+      it("should accept array of providers", () => {
+        const config = {
+          audio: { input: { encoding: "linear16", sample_rate: 16000 } },
+          agent: {
+            speak: [
+              { provider: { type: "deepgram", model: "aura-2-zeus-en" } },
+              {
+                provider: { type: "openai", model: "tts-1", voice: "shimmer" },
+                endpoint: { url: "https://api.openai.com/v1/audio/speech", headers: { auth: "key" } }
+              },
+            ],
+          },
+        };
+
+        client.configure(config);
+        expect(mockConnection.send).toHaveBeenCalledWith(
+          JSON.stringify({ type: "Settings", ...config })
+        );
+      });
     });
 
-    it("should send injectUserMessage with different content types", () => {
-      const testCases = [
-        "What's the weather like today?",
-        "Simple greeting",
-        "Multi-line\nmessage content",
-        "", // Edge case: empty string
-      ];
+    describe("updateSpeak method", () => {
+      it("should update with single provider", () => {
+        const provider = { provider: { type: "deepgram", model: "aura-2-zeus-en" } };
+
+        client.updateSpeak(provider);
+        expect(mockConnection.send).toHaveBeenCalledWith(
+          JSON.stringify({ type: "UpdateSpeak", speak: provider })
+        );
+      });
 
-      testCases.forEach((content) => {
-        jest.clearAllMocks(); // Reset mock between test cases
+      it("should update with array of providers", () => {
+        const providers = [
+          { provider: { type: "deepgram", model: "aura-2-zeus-en" } },
+          { provider: { type: "openai", model: "tts-1", voice: "shimmer" } },
+        ];
 
+        client.updateSpeak(providers);
+        expect(mockConnection.send).toHaveBeenCalledWith(
+          JSON.stringify({ type: "UpdateSpeak", speak: providers })
+        );
+      });
+    });
+
+    describe("injectUserMessage method", () => {
+      it("should send injectUserMessage correctly", () => {
+        const content = "Hello! Can you hear me?";
         client.injectUserMessage(content);
 
         expect(mockConnection.send).toHaveBeenCalledWith(
           JSON.stringify({ type: "InjectUserMessage", content })
         );
       });
+
+      it("should send injectUserMessage with different content types", () => {
+        const testCases = [
+          "What's the weather like today?",
+          "Simple greeting",
+          "Multi-line\nmessage content",
+          "", // Edge case: empty string
+        ];
+
+        testCases.forEach((content) => {
+          jest.clearAllMocks(); // Reset mock between test cases
+
+          client.injectUserMessage(content);
+
+          expect(mockConnection.send).toHaveBeenCalledWith(
+            JSON.stringify({ type: "InjectUserMessage", content })
+          );
+        });
+      });
     });
   });
 });