@simfinity/constellation-client 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,125 @@
+# @simfinity/constellation-client
+
+## Installation
+
+```bash
+npm install @simfinity/constellation-client
+# or
+yarn add @simfinity/constellation-client
+```
+
+## Purpose & Usage
+This package is a code wrapper to integrate the Simfinity constellation server.
+The constellation server is a proxy managing streaming sessions with third party LLMs.
+This package provides the programmatic functions covering the complete lifecycle of a streaming session:
+- Open/start session
+- Callbacks to continuously send and receive streamed data over a persistent connection
+- Close/end session
+
+### Server implementation insight
+The Constellation server is chat-room & session manager: upon receiving a session-start request, 
+it creates a persistent chat-room, initiates the persistent connection with the LLM and configures it accordingly 
+(e.g. system instruction, temperature, audio, transcript subscription...).
+Clients may lose connection with Constellation, but the chat-room will remain opened on server side, 
+this allows the client to reconnect and resume the session. 
+Clients MUST notify the server that a session has ended, so that Constellation can release allocated resources.
+
+### Example
+Key steps in pseudo-code:
+```TypeScript
+const client = new WebClient({
+     sessionEndpoint: "https://simfinity.constellation.com", 
+     streamingEndpoint: "wss://simfinity.constellation.com:30003",
+     key: "my-key",
+     llm: "openai",
+     model: "gpt-4o-realtime-preview-2024-12-17",
+});
+
+try {
+    /* ... */
+    
+    // Start a chat session
+    await startSession("You are a useful assistant", true);
+    await connect(true, {
+        onStreamClosed: (reason: string) => {
+            console.log("Stream connection lost");
+        },
+        onAudioResponseStart: () => {
+            console.log("The model is talking");
+        },
+        onAudioResponseChunk: (audioChunk: string) => {
+            audioPlayer.enqueue(audioChunk);
+        },
+        onAudioResponseEnd: () => {
+            console.log("The model is done talking");
+        }
+    });
+
+    /* ... */
+    
+    sendAudioChunk("{PCM16 Base64-encoded data}");
+    commitAudioChunksSent();
+    
+    /* ... */
+}
+catch {
+    
+}
+finally {
+    await endSession();
+}
+```
+
+### Types
+
+**Configuration**
+
+Configuration required to initiate a connection with the server:
+In the client, values would typically be stored in secret stores & environment variables
+```TypeScript
+export interface WebClientConfig {
+     sessionEndpoint:    string;
+     streamingEndpoint:  string;
+     key:    string;
+     llm:    LlmType;
+     model:  string;
+}
+```
+
+**Event hooks**
+
+Callback functions to catch all the propagated server events. Except for the
+onStreamClosed event, assigning hooks is optional: 
+non-observed events will be silently ignored & lost.
+```TypeScript
+export interface EventHandlers {
+     onStreamClosed: (reason: string) => void;
+     onAudioResponseStart?: () => void;
+     onAudioResponseChunk?: (audioChunk: string) => void;
+     onAudioResponseEnd?: () => void;
+     onTranscriptInput?: (transcript: string) => void;
+     onTranscriptResponse?: (transcript: string) => void;
+     onTechnicalError?: (error: string) => void;
+}
+```
+
+### Audio
+
+* The server expect exclusively base64 encoded PCM16 format & sends responses of the same format in return
+* The server implements VAD - voice activation detection. Configured to detect 1s silences as a response trigger
+* Therefore, input audio data chunks can be streamed immediately without buffering 
+* Client should however implement voice detection as well to reduce network consumption
+  * 500ms ring buffer continuously filled with audio input
+  * Noise detection with minimum threshold
+  * 
+
+### Text & Transcript
+
+* The transcript inputs/responses callbacks carry both the text exchanges and transcription of audio exchanges
+* In an audio session, text and audio inputs will trigger:
+  * a mirrored transcript text through onTranscriptInput
+  * an audio response through onAudioResponseChunk
+  * a text transcript of the audio response through onTranscriptResponse
+* In a text-only session, a text input will trigger: 
+  * a mirrored transcript text through onTranscriptInput
+  * a text response through the onTranscriptResponse callback

package/dist/index.cjs

@@ -20,17 +20,273 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  Dummy: () => Dummy_default
+  WebClient: () => WebClient_default
 });
 module.exports = __toCommonJS(index_exports);
 
-// src/Dummy.tsx
-var import_jsx_runtime = require("react/jsx-runtime");
-function Dummy({ label }) {
-  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { children: label });
-}
-var Dummy_default = Dummy;
+// src/WebClient.ts
+var WebClient = class {
+  constructor(config) {
+    this.ws = null;
+    this.sessionId = null;
+    this.config = config;
+  }
+  /**
+   * Start a persistent chat room on the server, allowing for re-connection,
+   * when the streaming connection is lost. Once a session was started it must
+   * be closed to release the context on server side. See endSession().
+   *
+   * @remarks
+   * A session MUST exist to connect the stream.
+   *
+   * @param instructions to the model, added to its context. This is the "system" input instructions.
+   * @param audio whether to allow audio streaming or text-only
+   *
+   * @exception
+   * This method throws new Error(...) if unable to execute successfully for any reason.
+   *
+   * @example
+   * ```TypeScript
+   * await startSession("You are useful assistant", true)
+   * ```
+   */
+  async startSession(instructions = "", audio = false) {
+    const response = await fetch(`${this.config.sessionEndpoint}/prepare_session`, {
+      method: "POST",
+      headers: {
+        "Authorization": `Bearer ${this.config.key}`,
+        "Content-Type": "application/json",
+        "Accept": "application/json"
+      },
+      body: JSON.stringify({
+        llmProvider: this.config.llm,
+        systemPrompt: instructions,
+        audio
+      })
+    });
+    if (!response.ok) {
+      throw new Error(`Could not create a new chat session
+[${response.status}:${response.statusText}]`);
+    }
+    try {
+      const result = await response.json();
+      if (result) {
+        this.sessionId = result.sessionId;
+      }
+    } catch (error) {
+      throw `Failed to read session create response: ${error}`;
+    }
+  }
+  /**
+   * Close an opened, persistent chat room, effectively killing the streaming as well if still opened.
+   * If there is no active session, this method does nothing.
+   *
+   * @remarks
+   * Not closing an opened session will not prevent from starting a new one, however this could
+   * starve the server resources and affect service stability.
+   * Make sure to always close an opened session when finished.
+   *
+   * @exception
+   * This method throws new Error(...) if unable to execute successfully for any reason.
+   */
+  async endSession() {
+    if (!this.sessionId) {
+      return;
+    }
+    const response = await fetch(`${this.config.sessionEndpoint}/end_session`, {
+      method: "POST",
+      headers: {
+        "Authorization": `Bearer ${this.config.key}`,
+        "Content-Type": "application/json",
+        "Accept": "application/json"
+      },
+      body: JSON.stringify({ sessionId: this.sessionId })
+    });
+    if (!response.ok) {
+      throw new Error(`Could not close the chat session
+[${response.status}:${response.statusText}]`);
+    }
+    this.sessionId = "";
+  }
+  /**
+   * Following a successful startSession, open a streaming connection with the server.
+   * After a successful call to this connect() method, the client is ready to send & receive events.
+   *
+   * @remarks
+   * This method not only opens a websocket connection with the server but also initiates a
+   * handshake, where the server explicitly acknowledges and accepts the client connection.
+   *
+   * @param audio for a session that created with audio capabilities, allows this streaming to include audio
+   * @param handlers callback functions to handle every possible communication events coming from the server
+   *
+   * @exception
+   * This method throws new Error(...) if unable to execute successfully for any reason.
+   *
+   * @example
+   * ```TypeScript
+   * // Open an audio connection: in this example we choose to handle only audio data, and ignore text.
+   * await connect(true, {
+   *     onStreamClosed: (reason: string) => { console.log("Stream connection lost"); },
+   *     onAudioResponseStart: () => { console.log("The model is talking"); },
+   *     onAudioResponseChunk: (audioChunk: string) => { audioPlayer.enqueue(audioChunk); },
+   *     onAudioResponseEnd: () => { console.log("The model is done talking"); }
+   * })
+   * ```
+   */
+  async connect(audio = false, handlers) {
+    if (!this.sessionId) {
+      throw new Error("No open session");
+    }
+    const ws = new WebSocket(
+      `${this.config.streamingEndpoint}/web/${this.sessionId}`,
+      ["key", this.config.key]
+    );
+    if (!await this.serverHandShake(ws, audio)) {
+      ws.close();
+      throw new Error("Unable to establish the connection");
+    }
+    ws.onerror = (error) => {
+      handlers.onStreamClosed(`WebSocket error: ${error}`);
+    };
+    ws.onclose = (event) => {
+      handlers.onStreamClosed(`WebSocket closed by peer: ${event.reason}`);
+    };
+    ws.onmessage = async (event) => {
+      var _a, _b, _c, _d, _e, _f;
+      try {
+        const data = JSON.parse(event.data);
+        switch (data.type) {
+          case "audio.response.start":
+            (_a = handlers.onAudioResponseStart) == null ? void 0 : _a.call(handlers);
+            break;
+          case "audio.response.append":
+            (_b = handlers.onAudioResponseChunk) == null ? void 0 : _b.call(handlers, data.data.audioData);
+            break;
+          case "audio.response.done":
+            (_c = handlers.onAudioResponseEnd) == null ? void 0 : _c.call(handlers);
+            break;
+          case "transcript.input":
+            (_d = handlers.onTranscriptInput) == null ? void 0 : _d.call(handlers, data.data.transcript);
+            break;
+          case "transcript.response":
+            (_e = handlers.onTranscriptResponse) == null ? void 0 : _e.call(handlers, data.data.transcript);
+            break;
+          case "technical.error":
+            (_f = handlers.onTechnicalError) == null ? void 0 : _f.call(handlers, data.data.error);
+            break;
+          default:
+            break;
+        }
+      } catch (error) {
+        console.error("Error processing message:", error, event.data);
+      }
+    };
+    this.ws = ws;
+  }
+  /**
+   * With an opened streaming connection: send a text input message to the LLM. This will trigger a
+   * text response as well as an audio response if the session was opened with audio mode active.
+   *
+   * @remarks
+   * With openai for example, this triggers (pseudo-code):
+   * webSocket.send({ type: "conversation.item.create", item: { content: { type: "input_text": text: text }}})
+   * webSocket.send({ type: "response.create"})
+   *
+   * @param text input message
+   *
+   * @exception
+   * This method throws new Error(...) if unable to execute successfully for any reason.
+   */
+  sendText(text) {
+    this.send("text.input.message", { text });
+  }
+  /**
+   * With an opened streaming connection: send a chunk of raw audio data to the LLM.
+   * Audio data chunks do not systematically & immediately trigger a model response:
+   * They get accumulated by the model to form a single input message, until:
+   * - commitAudioChunksSent is called, which flushes the accumulated audio and triggers a response
+   * - silence is detected for more than 1 second, which flushes the accumulated audio and triggers a response
+   *
+   * @remarks
+   * With openai for example, this triggers (pseudo-code):
+   * webSocket.send({ type: "input_audio_buffer.append", audio: "...audio data chunk..." })
+   *
+   * @param chunk base64-encoded pcm16 audio data chunk
+   *
+   * @exception
+   * This method throws new Error(...) if unable to execute successfully for any reason.
+   */
+  sendAudioChunk(chunk) {
+    this.send("audio.input.append", { audioData: chunk });
+  }
+  /**
+   * With an opened streaming connection: triggers the processing of the accumulated audio data since
+   * the last model response. This effectively flushes the audio buffer and triggers a new model response.
+   *
+   * @remarks
+   * With openai for example, this triggers (pseudo-code):
+   * webSocket.send({ type: "input_audio_buffer.commit" })
+   *
+   * Calling commitAudioChunksSent is optional because the constellation server uses server_vad,
+   * configured to detect a ~1 second silence, before automatically triggering a model response.
+   *
+   * Calling commitAudioChunksSent will always trigger a model response, even if no audio
+   * data was sent since the last response.
+   *
+   * @exception
+   * This method throws new Error(...) if unable to execute successfully for any reason.
+   */
+  commitAudioChunksSent() {
+    this.send("audio.input.commit");
+  }
+  // ================= Inner utils ================= //
+  async serverHandShake(ws, audio) {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        cleanup();
+        reject(new Error("Handshake timeout"));
+      }, 5e3);
+      const cleanup = () => {
+        clearTimeout(timer);
+        ws.onopen = null;
+        ws.onerror = null;
+        ws.onmessage = null;
+      };
+      ws.onerror = (error) => {
+        cleanup();
+        reject(new Error(`WebSocket connection failed with ${error.type}`));
+      };
+      ws.onopen = () => {
+        const eventSubs = audio ? [0 /* Text */, 1 /* Audio */] : [0 /* Text */];
+        ws.send(JSON.stringify({
+          type: "connection.request",
+          data: { subscription: eventSubs }
+        }));
+      };
+      ws.onmessage = (event) => {
+        try {
+          const data = JSON.parse(event.data);
+          if (data.type === "connection.accepted")
+            resolve(true);
+          else
+            reject(new Error(`Received unexpected event: ${data.type}`));
+        } catch (e) {
+          reject(new Error(`An unexpected error occurred: ${e}`));
+        } finally {
+          cleanup();
+        }
+      };
+    });
+  }
+  send(type, data = null) {
+    if (!this.ws || this.ws.readyState != WebSocket.OPEN) {
+      throw new Error("Stream is not opened");
+    }
+    this.ws.send(JSON.stringify({ type, ...data && { data } }));
+  }
+};
+var WebClient_default = WebClient;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  Dummy
+  WebClient
 });

package/dist/index.d.cts

@@ -1,8 +1,186 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
+/**
+ * Available server-side LLM types
+ */
+type LlmType = "openai";
+/**
+ * Configuration required to initiate a connection with the stream server:
+ *
+ * @sessionEndpoint : REST base URL to the constellation API for managing sessions
+ * @streamingEndpoint : WebSocket endpoint to the constellation server
+ * @key : Simfinity API secret key granting access to the server API
+ * @llm : which LLM service to connect to
+ * @model : depends on the LLM service. This is the model name as define by the LLM service
+ *
+ * @example
+ * ```TypeScript
+ * {
+ *     sessionEndpoint: "https://simfinity.constellation.com",
+ *     streamingEndpoint: "wss://simfinity.constellation.com:30003",
+ *     key: "some-secret-key"
+ *     llm: "openai",
+ *     model: "gpt-4o-realtime-preview-2024-12-17"
+ * }
+ * ```
+ */
+interface WebClientConfig {
+    sessionEndpoint: string;
+    streamingEndpoint: string;
+    key: string;
+    llm: LlmType;
+    model: string;
+}
+/**
+ * Callback functions to catch all the propagated server events.
+ *
+ * @onStreamClosed the streaming session (web socket) shut down
+ * @onAudioResponseStart the LLM service is about to respond with streaming audio data
+ * @onAudioResponseChunk a new chunk of response audio data was received
+ * @onAudioResponseEnd the model has finished responding. Audio response has been entirely streamed
+ * @onTranscriptInput either a copy of a text input, or the transcript of an audio input sent by the client
+ * @onTranscriptResponse either a text response (to a text input) or the transcript of an audio response
+ * @onTechnicalError any technical issue encountered during the stream
+ *
+ * @remarks
+ * Un-assigned callbacks will not cause exceptions by this client when events are received from the server
+ * However the events and information attached will be lost.
+ *
+ * The transcript events have dual purpose:
+ *  - In an audio exchange, they hold the text transcripts of the audio conversation
+ *  - In a text exchange, they hold the actual text messages of the conversation
+ */
+interface EventHandlers {
+    onStreamClosed: (reason: string) => void;
+    onAudioResponseStart?: () => void;
+    onAudioResponseChunk?: (audioChunk: string) => void;
+    onAudioResponseEnd?: () => void;
+    onTranscriptInput?: (transcript: string) => void;
+    onTranscriptResponse?: (transcript: string) => void;
+    onTechnicalError?: (error: string) => void;
+}
+/**
+ * This class is a code wrapper to integrate the Simfinity constellation server.
+ * The constellation server is a proxy managing streaming sessions with third party LLMs.
+ * This class manages the complete lifecycle of a streaming session:
+ * - Open/start session
+ * - Continuously sending and receiving streamed data over persistent connection
+ * - Close/end session
+ */
+declare class WebClient {
+    private config;
+    private ws;
+    private sessionId;
+    constructor(config: WebClientConfig);
+    /**
+     * Start a persistent chat room on the server, allowing for re-connection,
+     * when the streaming connection is lost. Once a session was started it must
+     * be closed to release the context on server side. See endSession().
+     *
+     * @remarks
+     * A session MUST exist to connect the stream.
+     *
+     * @param instructions to the model, added to its context. This is the "system" input instructions.
+     * @param audio whether to allow audio streaming or text-only
+     *
+     * @exception
+     * This method throws new Error(...) if unable to execute successfully for any reason.
+     *
+     * @example
+     * ```TypeScript
+     * await startSession("You are useful assistant", true)
+     * ```
+     */
+    startSession(instructions?: string, audio?: boolean): Promise<void>;
+    /**
+     * Close an opened, persistent chat room, effectively killing the streaming as well if still opened.
+     * If there is no active session, this method does nothing.
+     *
+     * @remarks
+     * Not closing an opened session will not prevent from starting a new one, however this could
+     * starve the server resources and affect service stability.
+     * Make sure to always close an opened session when finished.
+     *
+     * @exception
+     * This method throws new Error(...) if unable to execute successfully for any reason.
+     */
+    endSession(): Promise<void>;
+    /**
+     * Following a successful startSession, open a streaming connection with the server.
+     * After a successful call to this connect() method, the client is ready to send & receive events.
+     *
+     * @remarks
+     * This method not only opens a websocket connection with the server but also initiates a
+     * handshake, where the server explicitly acknowledges and accepts the client connection.
+     *
+     * @param audio for a session that created with audio capabilities, allows this streaming to include audio
+     * @param handlers callback functions to handle every possible communication events coming from the server
+     *
+     * @exception
+     * This method throws new Error(...) if unable to execute successfully for any reason.
+     *
+     * @example
+     * ```TypeScript
+     * // Open an audio connection: in this example we choose to handle only audio data, and ignore text.
+     * await connect(true, {
+     *     onStreamClosed: (reason: string) => { console.log("Stream connection lost"); },
+     *     onAudioResponseStart: () => { console.log("The model is talking"); },
+     *     onAudioResponseChunk: (audioChunk: string) => { audioPlayer.enqueue(audioChunk); },
+     *     onAudioResponseEnd: () => { console.log("The model is done talking"); }
+     * })
+     * ```
+     */
+    connect(audio: boolean | undefined, handlers: EventHandlers): Promise<void>;
+    /**
+     * With an opened streaming connection: send a text input message to the LLM. This will trigger a
+     * text response as well as an audio response if the session was opened with audio mode active.
+     *
+     * @remarks
+     * With openai for example, this triggers (pseudo-code):
+     * webSocket.send({ type: "conversation.item.create", item: { content: { type: "input_text": text: text }}})
+     * webSocket.send({ type: "response.create"})
+     *
+     * @param text input message
+     *
+     * @exception
+     * This method throws new Error(...) if unable to execute successfully for any reason.
+     */
+    sendText(text: string): void;
+    /**
+     * With an opened streaming connection: send a chunk of raw audio data to the LLM.
+     * Audio data chunks do not systematically & immediately trigger a model response:
+     * They get accumulated by the model to form a single input message, until:
+     * - commitAudioChunksSent is called, which flushes the accumulated audio and triggers a response
+     * - silence is detected for more than 1 second, which flushes the accumulated audio and triggers a response
+     *
+     * @remarks
+     * With openai for example, this triggers (pseudo-code):
+     * webSocket.send({ type: "input_audio_buffer.append", audio: "...audio data chunk..." })
+     *
+     * @param chunk base64-encoded pcm16 audio data chunk
+     *
+     * @exception
+     * This method throws new Error(...) if unable to execute successfully for any reason.
+     */
+    sendAudioChunk(chunk: string): void;
+    /**
+     * With an opened streaming connection: triggers the processing of the accumulated audio data since
+     * the last model response. This effectively flushes the audio buffer and triggers a new model response.
+     *
+     * @remarks
+     * With openai for example, this triggers (pseudo-code):
+     * webSocket.send({ type: "input_audio_buffer.commit" })
+     *
+     * Calling commitAudioChunksSent is optional because the constellation server uses server_vad,
+     * configured to detect a ~1 second silence, before automatically triggering a model response.
+     *
+     * Calling commitAudioChunksSent will always trigger a model response, even if no audio
+     * data was sent since the last response.
+     *
+     * @exception
+     * This method throws new Error(...) if unable to execute successfully for any reason.
+     */
+    commitAudioChunksSent(): void;
+    private serverHandShake;
+    private send;
+}
 
-type DummyProps = {
-    label: string;
-};
-declare function Dummy({ label }: DummyProps): react_jsx_runtime.JSX.Element;
-
-export { Dummy, type DummyProps };
+export { type EventHandlers, type LlmType, WebClient, type WebClientConfig };

package/dist/index.d.ts

@@ -1,8 +1,186 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
+/**
+ * Available server-side LLM types
+ */
+type LlmType = "openai";
+/**
+ * Configuration required to initiate a connection with the stream server:
+ *
+ * @sessionEndpoint : REST base URL to the constellation API for managing sessions
+ * @streamingEndpoint : WebSocket endpoint to the constellation server
+ * @key : Simfinity API secret key granting access to the server API
+ * @llm : which LLM service to connect to
+ * @model : depends on the LLM service. This is the model name as define by the LLM service
+ *
+ * @example
+ * ```TypeScript
+ * {
+ *     sessionEndpoint: "https://simfinity.constellation.com",
+ *     streamingEndpoint: "wss://simfinity.constellation.com:30003",
+ *     key: "some-secret-key"
+ *     llm: "openai",
+ *     model: "gpt-4o-realtime-preview-2024-12-17"
+ * }
+ * ```
+ */
+interface WebClientConfig {
+    sessionEndpoint: string;
+    streamingEndpoint: string;
+    key: string;
+    llm: LlmType;
+    model: string;
+}
+/**
+ * Callback functions to catch all the propagated server events.
+ *
+ * @onStreamClosed the streaming session (web socket) shut down
+ * @onAudioResponseStart the LLM service is about to respond with streaming audio data
+ * @onAudioResponseChunk a new chunk of response audio data was received
+ * @onAudioResponseEnd the model has finished responding. Audio response has been entirely streamed
+ * @onTranscriptInput either a copy of a text input, or the transcript of an audio input sent by the client
+ * @onTranscriptResponse either a text response (to a text input) or the transcript of an audio response
+ * @onTechnicalError any technical issue encountered during the stream
+ *
+ * @remarks
+ * Un-assigned callbacks will not cause exceptions by this client when events are received from the server
+ * However the events and information attached will be lost.
+ *
+ * The transcript events have dual purpose:
+ *  - In an audio exchange, they hold the text transcripts of the audio conversation
+ *  - In a text exchange, they hold the actual text messages of the conversation
+ */
+interface EventHandlers {
+    onStreamClosed: (reason: string) => void;
+    onAudioResponseStart?: () => void;
+    onAudioResponseChunk?: (audioChunk: string) => void;
+    onAudioResponseEnd?: () => void;
+    onTranscriptInput?: (transcript: string) => void;
+    onTranscriptResponse?: (transcript: string) => void;
+    onTechnicalError?: (error: string) => void;
+}
+/**
+ * This class is a code wrapper to integrate the Simfinity constellation server.
+ * The constellation server is a proxy managing streaming sessions with third party LLMs.
+ * This class manages the complete lifecycle of a streaming session:
+ * - Open/start session
+ * - Continuously sending and receiving streamed data over persistent connection
+ * - Close/end session
+ */
+declare class WebClient {
+    private config;
+    private ws;
+    private sessionId;
+    constructor(config: WebClientConfig);
+    /**
+     * Start a persistent chat room on the server, allowing for re-connection,
+     * when the streaming connection is lost. Once a session was started it must
+     * be closed to release the context on server side. See endSession().
+     *
+     * @remarks
+     * A session MUST exist to connect the stream.
+     *
+     * @param instructions to the model, added to its context. This is the "system" input instructions.
+     * @param audio whether to allow audio streaming or text-only
+     *
+     * @exception
+     * This method throws new Error(...) if unable to execute successfully for any reason.
+     *
+     * @example
+     * ```TypeScript
+     * await startSession("You are useful assistant", true)
+     * ```
+     */
+    startSession(instructions?: string, audio?: boolean): Promise<void>;
+    /**
+     * Close an opened, persistent chat room, effectively killing the streaming as well if still opened.
+     * If there is no active session, this method does nothing.
+     *
+     * @remarks
+     * Not closing an opened session will not prevent from starting a new one, however this could
+     * starve the server resources and affect service stability.
+     * Make sure to always close an opened session when finished.
+     *
+     * @exception
+     * This method throws new Error(...) if unable to execute successfully for any reason.
+     */
+    endSession(): Promise<void>;
+    /**
+     * Following a successful startSession, open a streaming connection with the server.
+     * After a successful call to this connect() method, the client is ready to send & receive events.
+     *
+     * @remarks
+     * This method not only opens a websocket connection with the server but also initiates a
+     * handshake, where the server explicitly acknowledges and accepts the client connection.
+     *
+     * @param audio for a session that created with audio capabilities, allows this streaming to include audio
+     * @param handlers callback functions to handle every possible communication events coming from the server
+     *
+     * @exception
+     * This method throws new Error(...) if unable to execute successfully for any reason.
+     *
+     * @example
+     * ```TypeScript
+     * // Open an audio connection: in this example we choose to handle only audio data, and ignore text.
+     * await connect(true, {
+     *     onStreamClosed: (reason: string) => { console.log("Stream connection lost"); },
+     *     onAudioResponseStart: () => { console.log("The model is talking"); },
+     *     onAudioResponseChunk: (audioChunk: string) => { audioPlayer.enqueue(audioChunk); },
+     *     onAudioResponseEnd: () => { console.log("The model is done talking"); }
+     * })
+     * ```
+     */
+    connect(audio: boolean | undefined, handlers: EventHandlers): Promise<void>;
+    /**
+     * With an opened streaming connection: send a text input message to the LLM. This will trigger a
+     * text response as well as an audio response if the session was opened with audio mode active.
+     *
+     * @remarks
+     * With openai for example, this triggers (pseudo-code):
+     * webSocket.send({ type: "conversation.item.create", item: { content: { type: "input_text": text: text }}})
+     * webSocket.send({ type: "response.create"})
+     *
+     * @param text input message
+     *
+     * @exception
+     * This method throws new Error(...) if unable to execute successfully for any reason.
+     */
+    sendText(text: string): void;
+    /**
+     * With an opened streaming connection: send a chunk of raw audio data to the LLM.
+     * Audio data chunks do not systematically & immediately trigger a model response:
+     * They get accumulated by the model to form a single input message, until:
+     * - commitAudioChunksSent is called, which flushes the accumulated audio and triggers a response
+     * - silence is detected for more than 1 second, which flushes the accumulated audio and triggers a response
+     *
+     * @remarks
+     * With openai for example, this triggers (pseudo-code):
+     * webSocket.send({ type: "input_audio_buffer.append", audio: "...audio data chunk..." })
+     *
+     * @param chunk base64-encoded pcm16 audio data chunk
+     *
+     * @exception
+     * This method throws new Error(...) if unable to execute successfully for any reason.
+     */
+    sendAudioChunk(chunk: string): void;
+    /**
+     * With an opened streaming connection: triggers the processing of the accumulated audio data since
+     * the last model response. This effectively flushes the audio buffer and triggers a new model response.
+     *
+     * @remarks
+     * With openai for example, this triggers (pseudo-code):
+     * webSocket.send({ type: "input_audio_buffer.commit" })
+     *
+     * Calling commitAudioChunksSent is optional because the constellation server uses server_vad,
+     * configured to detect a ~1 second silence, before automatically triggering a model response.
+     *
+     * Calling commitAudioChunksSent will always trigger a model response, even if no audio
+     * data was sent since the last response.
+     *
+     * @exception
+     * This method throws new Error(...) if unable to execute successfully for any reason.
+     */
+    commitAudioChunksSent(): void;
+    private serverHandShake;
+    private send;
+}
 
-type DummyProps = {
-    label: string;
-};
-declare function Dummy({ label }: DummyProps): react_jsx_runtime.JSX.Element;
-
-export { Dummy, type DummyProps };
+export { type EventHandlers, type LlmType, WebClient, type WebClientConfig };

package/dist/index.js

@@ -1,9 +1,265 @@
-// src/Dummy.tsx
-import { jsx } from "react/jsx-runtime";
-function Dummy({ label }) {
-  return /* @__PURE__ */ jsx("div", { children: label });
-}
-var Dummy_default = Dummy;
+// src/WebClient.ts
+var WebClient = class {
+  constructor(config) {
+    this.ws = null;
+    this.sessionId = null;
+    this.config = config;
+  }
+  /**
+   * Start a persistent chat room on the server, allowing for re-connection,
+   * when the streaming connection is lost. Once a session was started it must
+   * be closed to release the context on server side. See endSession().
+   *
+   * @remarks
+   * A session MUST exist to connect the stream.
+   *
+   * @param instructions to the model, added to its context. This is the "system" input instructions.
+   * @param audio whether to allow audio streaming or text-only
+   *
+   * @exception
+   * This method throws new Error(...) if unable to execute successfully for any reason.
+   *
+   * @example
+   * ```TypeScript
+   * await startSession("You are useful assistant", true)
+   * ```
+   */
+  async startSession(instructions = "", audio = false) {
+    const response = await fetch(`${this.config.sessionEndpoint}/prepare_session`, {
+      method: "POST",
+      headers: {
+        "Authorization": `Bearer ${this.config.key}`,
+        "Content-Type": "application/json",
+        "Accept": "application/json"
+      },
+      body: JSON.stringify({
+        llmProvider: this.config.llm,
+        systemPrompt: instructions,
+        audio
+      })
+    });
+    if (!response.ok) {
+      throw new Error(`Could not create a new chat session
+[${response.status}:${response.statusText}]`);
+    }
+    try {
+      const result = await response.json();
+      if (result) {
+        this.sessionId = result.sessionId;
+      }
+    } catch (error) {
+      throw `Failed to read session create response: ${error}`;
+    }
+  }
+  /**
+   * Close an opened, persistent chat room, effectively killing the streaming as well if still opened.
+   * If there is no active session, this method does nothing.
+   *
+   * @remarks
+   * Not closing an opened session will not prevent from starting a new one, however this could
+   * starve the server resources and affect service stability.
+   * Make sure to always close an opened session when finished.
+   *
+   * @exception
+   * This method throws new Error(...) if unable to execute successfully for any reason.
+   */
+  async endSession() {
+    if (!this.sessionId) {
+      return;
+    }
+    const response = await fetch(`${this.config.sessionEndpoint}/end_session`, {
+      method: "POST",
+      headers: {
+        "Authorization": `Bearer ${this.config.key}`,
+        "Content-Type": "application/json",
+        "Accept": "application/json"
+      },
+      body: JSON.stringify({ sessionId: this.sessionId })
+    });
+    if (!response.ok) {
+      throw new Error(`Could not close the chat session
+[${response.status}:${response.statusText}]`);
+    }
+    this.sessionId = "";
+  }
+  /**
+   * Following a successful startSession, open a streaming connection with the server.
+   * After a successful call to this connect() method, the client is ready to send & receive events.
+   *
+   * @remarks
+   * This method not only opens a websocket connection with the server but also initiates a
+   * handshake, where the server explicitly acknowledges and accepts the client connection.
+   *
+   * @param audio for a session that created with audio capabilities, allows this streaming to include audio
+   * @param handlers callback functions to handle every possible communication events coming from the server
+   *
+   * @exception
+   * This method throws new Error(...) if unable to execute successfully for any reason.
+   *
+   * @example
+   * ```TypeScript
+   * // Open an audio connection: in this example we choose to handle only audio data, and ignore text.
+   * await connect(true, {
+   *     onStreamClosed: (reason: string) => { console.log("Stream connection lost"); },
+   *     onAudioResponseStart: () => { console.log("The model is talking"); },
+   *     onAudioResponseChunk: (audioChunk: string) => { audioPlayer.enqueue(audioChunk); },
+   *     onAudioResponseEnd: () => { console.log("The model is done talking"); }
+   * })
+   * ```
+   */
+  async connect(audio = false, handlers) {
+    if (!this.sessionId) {
+      throw new Error("No open session");
+    }
+    const ws = new WebSocket(
+      `${this.config.streamingEndpoint}/web/${this.sessionId}`,
+      ["key", this.config.key]
+    );
+    if (!await this.serverHandShake(ws, audio)) {
+      ws.close();
+      throw new Error("Unable to establish the connection");
+    }
+    ws.onerror = (error) => {
+      handlers.onStreamClosed(`WebSocket error: ${error}`);
+    };
+    ws.onclose = (event) => {
+      handlers.onStreamClosed(`WebSocket closed by peer: ${event.reason}`);
+    };
+    ws.onmessage = async (event) => {
+      var _a, _b, _c, _d, _e, _f;
+      try {
+        const data = JSON.parse(event.data);
+        switch (data.type) {
+          case "audio.response.start":
+            (_a = handlers.onAudioResponseStart) == null ? void 0 : _a.call(handlers);
+            break;
+          case "audio.response.append":
+            (_b = handlers.onAudioResponseChunk) == null ? void 0 : _b.call(handlers, data.data.audioData);
+            break;
+          case "audio.response.done":
+            (_c = handlers.onAudioResponseEnd) == null ? void 0 : _c.call(handlers);
+            break;
+          case "transcript.input":
+            (_d = handlers.onTranscriptInput) == null ? void 0 : _d.call(handlers, data.data.transcript);
+            break;
+          case "transcript.response":
+            (_e = handlers.onTranscriptResponse) == null ? void 0 : _e.call(handlers, data.data.transcript);
+            break;
+          case "technical.error":
+            (_f = handlers.onTechnicalError) == null ? void 0 : _f.call(handlers, data.data.error);
+            break;
+          default:
+            break;
+        }
+      } catch (error) {
+        console.error("Error processing message:", error, event.data);
+      }
+    };
+    this.ws = ws;
+  }
+  /**
+   * With an opened streaming connection: send a text input message to the LLM. This will trigger a
+   * text response as well as an audio response if the session was opened with audio mode active.
+   *
+   * @remarks
+   * With openai for example, this triggers (pseudo-code):
+   * webSocket.send({ type: "conversation.item.create", item: { content: { type: "input_text": text: text }}})
+   * webSocket.send({ type: "response.create"})
+   *
+   * @param text input message
+   *
+   * @exception
+   * This method throws new Error(...) if unable to execute successfully for any reason.
+   */
+  sendText(text) {
+    this.send("text.input.message", { text });
+  }
+  /**
+   * With an opened streaming connection: send a chunk of raw audio data to the LLM.
+   * Audio data chunks do not systematically & immediately trigger a model response:
+   * They get accumulated by the model to form a single input message, until:
+   * - commitAudioChunksSent is called, which flushes the accumulated audio and triggers a response
+   * - silence is detected for more than 1 second, which flushes the accumulated audio and triggers a response
+   *
+   * @remarks
+   * With openai for example, this triggers (pseudo-code):
+   * webSocket.send({ type: "input_audio_buffer.append", audio: "...audio data chunk..." })
+   *
+   * @param chunk base64-encoded pcm16 audio data chunk
+   *
+   * @exception
+   * This method throws new Error(...) if unable to execute successfully for any reason.
+   */
+  sendAudioChunk(chunk) {
+    this.send("audio.input.append", { audioData: chunk });
+  }
+  /**
+   * With an opened streaming connection: triggers the processing of the accumulated audio data since
+   * the last model response. This effectively flushes the audio buffer and triggers a new model response.
+   *
+   * @remarks
+   * With openai for example, this triggers (pseudo-code):
+   * webSocket.send({ type: "input_audio_buffer.commit" })
+   *
+   * Calling commitAudioChunksSent is optional because the constellation server uses server_vad,
+   * configured to detect a ~1 second silence, before automatically triggering a model response.
+   *
+   * Calling commitAudioChunksSent will always trigger a model response, even if no audio
+   * data was sent since the last response.
+   *
+   * @exception
+   * This method throws new Error(...) if unable to execute successfully for any reason.
+   */
+  commitAudioChunksSent() {
+    this.send("audio.input.commit");
+  }
+  // ================= Inner utils ================= //
+  async serverHandShake(ws, audio) {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        cleanup();
+        reject(new Error("Handshake timeout"));
+      }, 5e3);
+      const cleanup = () => {
+        clearTimeout(timer);
+        ws.onopen = null;
+        ws.onerror = null;
+        ws.onmessage = null;
+      };
+      ws.onerror = (error) => {
+        cleanup();
+        reject(new Error(`WebSocket connection failed with ${error.type}`));
+      };
+      ws.onopen = () => {
+        const eventSubs = audio ? [0 /* Text */, 1 /* Audio */] : [0 /* Text */];
+        ws.send(JSON.stringify({
+          type: "connection.request",
+          data: { subscription: eventSubs }
+        }));
+      };
+      ws.onmessage = (event) => {
+        try {
+          const data = JSON.parse(event.data);
+          if (data.type === "connection.accepted")
+            resolve(true);
+          else
+            reject(new Error(`Received unexpected event: ${data.type}`));
+        } catch (e) {
+          reject(new Error(`An unexpected error occurred: ${e}`));
+        } finally {
+          cleanup();
+        }
+      };
+    });
+  }
+  send(type, data = null) {
+    if (!this.ws || this.ws.readyState != WebSocket.OPEN) {
+      throw new Error("Stream is not opened");
+    }
+    this.ws.send(JSON.stringify({ type, ...data && { data } }));
+  }
+};
+var WebClient_default = WebClient;
 export {
-  Dummy_default as Dummy
+  WebClient_default as WebClient
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simfinity/constellation-client",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "type": "module",
   "exports": {
     ".": {
@@ -18,16 +18,12 @@
     "build": "tsup src/index.ts --format cjs,esm --dts"
   },
   "peerDependencies": {
-    "react": "^18.0.0 || ^19.0.0",
-    "react-dom": "^18.0.0 || ^19.0.0"
   },
   "author": "Simfinity",
   "license": "MIT",
   "dependencies": {
   },
   "devDependencies": {
-    "@types/react": "^19.2.11",
-    "@types/react-dom": "^19.2.3",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3"
   }