phonic 0.4.0 → 0.5.0

package/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2024 Phonic, Inc.
+Copyright (c) 2025 Phonic, Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

package/README.md

@@ -8,6 +8,7 @@ Node.js library for the Phonic API.
   - [Get voices](#get-voices)
   - [Get voice by id](#get-voice-by-id)
   - [Text-to-speech via WebSocket](#text-to-speech-via-websocket)
+  - [Speech-to-speech via WebSocket](#speech-to-speech-via-websocket)
 
 ## Installation
 
@@ -19,7 +20,7 @@ npm i phonic
 
 Grab an API key from [Phonic settings](https://phonic.co/settings) and pass it to the Phonic constructor.
 
-```js
+```ts
 import { Phonic } from "phonic";
 
 const phonic = new Phonic("ph_...");
@@ -29,7 +30,7 @@ const phonic = new Phonic("ph_...");
 
 ### Get voices
 
-```js
+```ts
 const { data, error } = await phonic.voices.list({ model: "shasta" });
 
 if (error === null) {
@@ -40,7 +41,7 @@ if (error === null) {
 
 ### Get voice by id
 
-```js
+```ts
 const { data, error } = await phonic.voices.get("meredith");
 
 if (error === null) {
@@ -48,11 +49,95 @@ if (error === null) {
 }
 ```
 
+### Speesh-to-speech via WebSocket
+
+Open a WebSocket connection:
+
+```ts
+const { data, error } = await phonic.sts.websocket();
+
+if (error !== null) {
+  throw new Error(error.message);
+}
+
+// Here we know that the WebSocket connection is open.
+const { phonicWebSocket } = data;
+```
+
+Send config params for the conversation:
+
+```ts
+phonicWebSocket.config({
+  input_format: "mulaw_8000",
+
+  // Optional fields
+  system_prompt: "You are a helpful assistant.",
+  welcome_message: "Hello, how can I help you?",
+  voice_id: "meredith",
+  output_format: "mulaw_8000"
+});
+```
+
+Stream input (user) audio chunks:
+
+```ts
+phonicWebSocket.audioChunk({
+  audio: "...", // base64 encoded audio chunk
+});
+```
+
+Process messages that Phonic sends back to you:
+
+```ts
+phonicWebSocket.onMessage((message) => {
+  switch (message.type) {
+    case "input_text": {
+      console.log(`User: ${message.text}`);
+      break;
+    }
+
+    case "audio_chunk": {
+      // Send the audio chunk to Twilio, for example:
+      ws.send(
+        JSON.stringify({
+          event: "media",
+          streamSid: "...",
+          media: {
+            payload: message.audio,
+          },
+        }),
+      );
+      break;
+    }
+  }
+});
+```
+
+To end the conversation, close the WebSocket:
+
+```ts
+phonicWebSocket.close();
+```
+
+You can also listen for close and error events:
+
+```ts
+phonicWebSocket.onClose((event) => {
+  console.log(
+    `Phonic WebSocket closed with code ${event.code} and reason "${event.reason}"`,
+  );
+});
+
+phonicWebSocket.onError((event) => {
+  console.log(`Error from Phonic WebSocket: ${event.message}`);
+});
+```
+
 ### Text-to-speech via WebSocket
 
 Open a WebSocket connection:
 
-```js
+```ts
 const { data, error } = await phonic.tts.websocket({
   model: "shasta",
   output_format: "mulaw_8000",
@@ -69,7 +154,7 @@ const { phonicWebSocket } = data;
 
 Process audio chunks that Phonic sends back to you, by sending them to Twilio, for example:
 
-```js
+```ts
 phonicWebSocket.onMessage((message) => {
   if (message.type === "audio_chunk") {
     ws.send(
@@ -87,7 +172,7 @@ phonicWebSocket.onMessage((message) => {
 
 Send text chunks to Phonic for audio generation as you receive them from LLM:
 
-```js
+```ts
 const stream = await openai.chat.completions.create(...);
 
 for await (const chunk of stream) {
@@ -101,25 +186,25 @@ for await (const chunk of stream) {
 
 Tell Phonic to finish generating audio for all text chunks you've sent:
 
-```js
+```ts
 phonicWebSocket.flush();
 ```
 
 You can also tell Phonic to stop sending audio chunks back, e.g. if the user interrupts the conversation:
 
-```js
+```ts
 phonicWebSocket.stop();
 ```
 
 To close the WebSocket connection:
 
-```js
+```ts
 phonicWebSocket.close();
 ```
 
 To know when the last audio chunk has been received:
 
-```js
+```ts
 phonicWebSocket.onMessage((message) => {
   if (message.type === "flushed") {
     console.log("Last audio chunk received");
@@ -129,7 +214,7 @@ phonicWebSocket.onMessage((message) => {
 
 You can also listen for close and error events:
 
-```js
+```ts
 phonicWebSocket.onClose((event) => {
   console.log(
     `Phonic WebSocket closed with code ${event.code} and reason "${event.reason}"`,

package/dist/index.d.mts

@@ -18,12 +18,12 @@ type DataOrError<T> = Promise<{
     error: ErrorResponse;
 }>;
 
-type PhonicWebSocketParams = {
+type PhonicTTSWebSocketParams = {
     model?: string;
     output_format?: string;
     voice_id?: string;
 };
-type PhonicWebSocketResponseMessage = {
+type PhonicTTSWebSocketResponseMessage = {
     type: "config";
     model: string;
     output_format: string;
@@ -50,19 +50,19 @@ type PhonicWebSocketResponseMessage = {
         speed?: string;
     };
 };
-type OnMessageCallback = (message: PhonicWebSocketResponseMessage) => void;
-type OnCloseCallback = (event: WebSocket.CloseEvent) => void;
-type OnErrorCallback = (event: WebSocket.ErrorEvent) => void;
+type OnMessageCallback$1 = (message: PhonicTTSWebSocketResponseMessage) => void;
+type OnCloseCallback$1 = (event: WebSocket.CloseEvent) => void;
+type OnErrorCallback$1 = (event: WebSocket.ErrorEvent) => void;
 
-declare class PhonicWebSocket {
+declare class PhonicTTSWebSocket {
     private readonly ws;
     private onMessageCallback;
     private onCloseCallback;
     private onErrorCallback;
     constructor(ws: WebSocket);
-    onMessage(callback: OnMessageCallback): void;
-    onClose(callback: OnCloseCallback): void;
-    onError(callback: OnErrorCallback): void;
+    onMessage(callback: OnMessageCallback$1): void;
+    onClose(callback: OnCloseCallback$1): void;
+    onError(callback: OnErrorCallback$1): void;
     generate(message: {
         text: string;
         speed?: number;
@@ -75,8 +75,8 @@ declare class PhonicWebSocket {
 declare class TextToSpeech {
     private readonly phonic;
     constructor(phonic: Phonic);
-    websocket(params?: PhonicWebSocketParams): DataOrError<{
-        phonicWebSocket: PhonicWebSocket;
+    websocket(params?: PhonicTTSWebSocketParams): DataOrError<{
+        phonicWebSocket: PhonicTTSWebSocket;
     }>;
 }
 
@@ -117,4 +117,51 @@ declare class Phonic {
     }>;
 }
 
-export { Phonic, PhonicWebSocket };
+type PhonicSTSWebSocketResponseMessage = {
+    type: "input_text";
+    text: string;
+} | {
+    type: "audio_chunk";
+    text: string;
+    audio: string;
+} | {
+    type: "error";
+    error: {
+        message: string;
+        code?: string;
+    };
+    paramErrors?: {
+        system_prompt?: string;
+        welcome_message?: string;
+        voice_id?: string;
+        input_format?: string;
+        output_format?: string;
+    };
+};
+type OnMessageCallback = (message: PhonicSTSWebSocketResponseMessage) => void;
+type OnCloseCallback = (event: WebSocket.CloseEvent) => void;
+type OnErrorCallback = (event: WebSocket.ErrorEvent) => void;
+
+declare class PhonicSTSWebSocket {
+    private readonly ws;
+    private onMessageCallback;
+    private onCloseCallback;
+    private onErrorCallback;
+    constructor(ws: WebSocket);
+    onMessage(callback: OnMessageCallback): void;
+    onClose(callback: OnCloseCallback): void;
+    onError(callback: OnErrorCallback): void;
+    config(message: {
+        system_prompt?: string;
+        welcome_message?: string;
+        voice_id?: string;
+        input_format?: "pcm_44100" | "mulaw_8000";
+        output_format?: "pcm_44100" | "mulaw_8000";
+    }): void;
+    audioChunk(message: {
+        audio: string;
+    }): void;
+    close(): void;
+}
+
+export { Phonic, PhonicSTSWebSocket, PhonicTTSWebSocket };

package/dist/index.d.ts

@@ -18,12 +18,12 @@ type DataOrError<T> = Promise<{
     error: ErrorResponse;
 }>;
 
-type PhonicWebSocketParams = {
+type PhonicTTSWebSocketParams = {
     model?: string;
     output_format?: string;
     voice_id?: string;
 };
-type PhonicWebSocketResponseMessage = {
+type PhonicTTSWebSocketResponseMessage = {
     type: "config";
     model: string;
     output_format: string;
@@ -50,19 +50,19 @@ type PhonicWebSocketResponseMessage = {
         speed?: string;
     };
 };
-type OnMessageCallback = (message: PhonicWebSocketResponseMessage) => void;
-type OnCloseCallback = (event: WebSocket.CloseEvent) => void;
-type OnErrorCallback = (event: WebSocket.ErrorEvent) => void;
+type OnMessageCallback$1 = (message: PhonicTTSWebSocketResponseMessage) => void;
+type OnCloseCallback$1 = (event: WebSocket.CloseEvent) => void;
+type OnErrorCallback$1 = (event: WebSocket.ErrorEvent) => void;
 
-declare class PhonicWebSocket {
+declare class PhonicTTSWebSocket {
     private readonly ws;
     private onMessageCallback;
     private onCloseCallback;
     private onErrorCallback;
     constructor(ws: WebSocket);
-    onMessage(callback: OnMessageCallback): void;
-    onClose(callback: OnCloseCallback): void;
-    onError(callback: OnErrorCallback): void;
+    onMessage(callback: OnMessageCallback$1): void;
+    onClose(callback: OnCloseCallback$1): void;
+    onError(callback: OnErrorCallback$1): void;
     generate(message: {
         text: string;
         speed?: number;
@@ -75,8 +75,8 @@ declare class PhonicWebSocket {
 declare class TextToSpeech {
     private readonly phonic;
     constructor(phonic: Phonic);
-    websocket(params?: PhonicWebSocketParams): DataOrError<{
-        phonicWebSocket: PhonicWebSocket;
+    websocket(params?: PhonicTTSWebSocketParams): DataOrError<{
+        phonicWebSocket: PhonicTTSWebSocket;
     }>;
 }
 
@@ -117,4 +117,51 @@ declare class Phonic {
     }>;
 }
 
-export { Phonic, PhonicWebSocket };
+type PhonicSTSWebSocketResponseMessage = {
+    type: "input_text";
+    text: string;
+} | {
+    type: "audio_chunk";
+    text: string;
+    audio: string;
+} | {
+    type: "error";
+    error: {
+        message: string;
+        code?: string;
+    };
+    paramErrors?: {
+        system_prompt?: string;
+        welcome_message?: string;
+        voice_id?: string;
+        input_format?: string;
+        output_format?: string;
+    };
+};
+type OnMessageCallback = (message: PhonicSTSWebSocketResponseMessage) => void;
+type OnCloseCallback = (event: WebSocket.CloseEvent) => void;
+type OnErrorCallback = (event: WebSocket.ErrorEvent) => void;
+
+declare class PhonicSTSWebSocket {
+    private readonly ws;
+    private onMessageCallback;
+    private onCloseCallback;
+    private onErrorCallback;
+    constructor(ws: WebSocket);
+    onMessage(callback: OnMessageCallback): void;
+    onClose(callback: OnCloseCallback): void;
+    onError(callback: OnErrorCallback): void;
+    config(message: {
+        system_prompt?: string;
+        welcome_message?: string;
+        voice_id?: string;
+        input_format?: "pcm_44100" | "mulaw_8000";
+        output_format?: "pcm_44100" | "mulaw_8000";
+    }): void;
+    audioChunk(message: {
+        audio: string;
+    }): void;
+    close(): void;
+}
+
+export { Phonic, PhonicSTSWebSocket, PhonicTTSWebSocket };

package/dist/index.js

@@ -35,13 +35,13 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // package.json
-var version = "0.4.0";
+var version = "0.5.0";
 
 // src/tts/index.ts
 var import_ws = __toESM(require("ws"));
 
 // src/tts/websocket.ts
-var PhonicWebSocket = class {
+var PhonicTTSWebSocket = class {
   constructor(ws) {
     this.ws = ws;
     this.ws.onmessage = (event) => {
@@ -51,7 +51,9 @@ var PhonicWebSocket = class {
       if (typeof event.data !== "string") {
         throw new Error("Received non-string message");
       }
-      const dataObj = JSON.parse(event.data);
+      const dataObj = JSON.parse(
+        event.data
+      );
       this.onMessageCallback(dataObj);
     };
     this.ws.onclose = (event) => {
@@ -67,6 +69,8 @@ var PhonicWebSocket = class {
       this.onErrorCallback(event);
     };
     this.onMessage = this.onMessage.bind(this);
+    this.onClose = this.onClose.bind(this);
+    this.onError = this.onError.bind(this);
     this.generate = this.generate.bind(this);
     this.flush = this.flush.bind(this);
     this.stop = this.stop.bind(this);
@@ -118,7 +122,7 @@ var TextToSpeech = class {
         }
       });
       ws.onopen = () => {
-        const phonicWebSocket = new PhonicWebSocket(ws);
+        const phonicWebSocket = new PhonicTTSWebSocket(ws);
         resolve({ data: { phonicWebSocket }, error: null });
       };
       ws.onerror = (error) => {

package/dist/index.mjs

@@ -1,11 +1,11 @@
 // package.json
-var version = "0.4.0";
+var version = "0.5.0";
 
 // src/tts/index.ts
 import WebSocket from "ws";
 
 // src/tts/websocket.ts
-var PhonicWebSocket = class {
+var PhonicTTSWebSocket = class {
   constructor(ws) {
     this.ws = ws;
     this.ws.onmessage = (event) => {
@@ -15,7 +15,9 @@ var PhonicWebSocket = class {
       if (typeof event.data !== "string") {
         throw new Error("Received non-string message");
       }
-      const dataObj = JSON.parse(event.data);
+      const dataObj = JSON.parse(
+        event.data
+      );
       this.onMessageCallback(dataObj);
     };
     this.ws.onclose = (event) => {
@@ -31,6 +33,8 @@ var PhonicWebSocket = class {
       this.onErrorCallback(event);
     };
     this.onMessage = this.onMessage.bind(this);
+    this.onClose = this.onClose.bind(this);
+    this.onError = this.onError.bind(this);
     this.generate = this.generate.bind(this);
     this.flush = this.flush.bind(this);
     this.stop = this.stop.bind(this);
@@ -82,7 +86,7 @@ var TextToSpeech = class {
         }
       });
       ws.onopen = () => {
-        const phonicWebSocket = new PhonicWebSocket(ws);
+        const phonicWebSocket = new PhonicTTSWebSocket(ws);
         resolve({ data: { phonicWebSocket }, error: null });
       };
       ws.onerror = (error) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phonic",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Phonic Node.js SDK",
   "scripts": {
     "build": "tsup",
@@ -33,13 +33,13 @@
     "url": "https://github.com/Phonic-Co/phonic-node/issues"
   },
   "dependencies": {
-    "ws": "8.18.0"
+    "ws": "8.18.1"
   },
   "devDependencies": {
     "@biomejs/biome": "1.9.4",
-    "@changesets/changelog-github": "0.5.0",
-    "@changesets/cli": "2.27.12",
-    "@types/bun": "1.2.2",
+    "@changesets/changelog-github": "0.5.1",
+    "@changesets/cli": "2.28.1",
+    "@types/bun": "1.2.3",
     "tsup": "8.3.6",
     "typescript": "5.7.3",
     "zod": "3.24.2"