phonic 0.3.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,8 +30,8 @@ const phonic = new Phonic("ph_...");
 
 ### Get voices
 
-```js
-const { data, error } = await phonic.voices.list();
+```ts
+const { data, error } = await phonic.voices.list({ model: "shasta" });
 
 if (error === null) {
   console.log(data.voices);
@@ -40,23 +41,107 @@ if (error === null) {
 
 ### Get voice by id
 
-```js
-const { data, error } = await phonic.voices.get("australian-man");
+```ts
+const { data, error } = await phonic.voices.get("meredith");
 
 if (error === null) {
   console.log(data.voice);
 }
 ```
 
+### 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",
-  voice_id: "australian-man",
+  voice_id: "meredith",
 });
 
 if (error !== null) {
@@ -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}"`,
@@ -141,15 +226,15 @@ phonicWebSocket.onError((event) => {
 });
 ```
 
-## Release a new version to npm
+## Publish a new version on npm
 
 1. `bunx changeset`
 2. `git add .`
 3. `git commit -m "Add changeset"`
 4. `git push`
 
-Git action will run and create a PR.
-Once this PR is merged, the new version will be released to npm.
+This should trigger the `publish` github workflow that will create a Pull Request named "Version Packages". 
+Once this Pull Request is merged, the new version will be published on npm.
 
 ## License
 

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;
     }>;
 }
 
@@ -94,7 +94,9 @@ type VoiceSuccessResponse = {
 declare class Voices {
     private readonly phonic;
     constructor(phonic: Phonic);
-    list(): DataOrError<VoicesSuccessResponse>;
+    list({ model }: {
+        model: string;
+    }): DataOrError<VoicesSuccessResponse>;
     get(id: string): DataOrError<VoiceSuccessResponse>;
 }
 
@@ -115,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;
     }>;
 }
 
@@ -94,7 +94,9 @@ type VoiceSuccessResponse = {
 declare class Voices {
     private readonly phonic;
     constructor(phonic: Phonic);
-    list(): DataOrError<VoicesSuccessResponse>;
+    list({ model }: {
+        model: string;
+    }): DataOrError<VoicesSuccessResponse>;
     get(id: string): DataOrError<VoiceSuccessResponse>;
 }
 
@@ -115,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

@@ -28,20 +28,20 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
-var src_exports = {};
-__export(src_exports, {
+var index_exports = {};
+__export(index_exports, {
   Phonic: () => Phonic
 });
-module.exports = __toCommonJS(src_exports);
+module.exports = __toCommonJS(index_exports);
 
 // package.json
-var version = "0.3.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) => {
@@ -138,8 +142,10 @@ var Voices = class {
   constructor(phonic) {
     this.phonic = phonic;
   }
-  async list() {
-    const response = await this.phonic.get("/voices");
+  async list({ model }) {
+    const response = await this.phonic.get(
+      `/voices?model=${encodeURIComponent(model)}`
+    );
     return response;
   }
   async get(id) {

package/dist/index.mjs

@@ -1,11 +1,11 @@
 // package.json
-var version = "0.3.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) => {
@@ -102,8 +106,10 @@ var Voices = class {
   constructor(phonic) {
     this.phonic = phonic;
   }
-  async list() {
-    const response = await this.phonic.get("/voices");
+  async list({ model }) {
+    const response = await this.phonic.get(
+      `/voices?model=${encodeURIComponent(model)}`
+    );
     return response;
   }
   async get(id) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phonic",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Phonic Node.js SDK",
   "scripts": {
     "build": "tsup",
@@ -33,16 +33,16 @@
     "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.11",
-    "@types/bun": "1.1.14",
-    "tsup": "8.3.5",
-    "typescript": "5.7.2",
-    "zod": "3.24.1"
+    "@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"
   },
   "files": ["dist/**"],
   "author": {