@sippulse/niva-sdk 0.1.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -161,6 +161,31 @@ On an unrecognized runtime the `default` entry resolves and `.serve()` throws `N
161
161
 
162
162
  See the webhook receiver guide in the NIVA docs (`/sdk/webhooks`) for the event registry and payload shapes.
163
163
 
164
+ ## Chat
165
+
166
+ Build your own chat interface over the Chat API with `connectChat`, from the `@sippulse/niva-sdk/chat` subpath. It speaks the WebSocket protocol for you: starts the plan, pings, reconnects with backoff, resumes without losing or repeating messages, and holds the visitor's sends until the plan waits for them.
167
+
168
+ On your backend, create the session with the API key (`ws_url` comes back absolute, ready to hand to the browser):
169
+
170
+ ```ts
171
+ const { ws_url } = await niva.chat.createSession({ plan_id: "vp_..." });
172
+ ```
173
+
174
+ In the browser, `session` asks YOUR backend for it; the API key never reaches the page:
175
+
176
+ ```ts
177
+ import { connectChat } from "@sippulse/niva-sdk/chat";
178
+
179
+ const chat = connectChat({
180
+ session: async () => (await fetch("/chat/session", { method: "POST" }).then((r) => r.json())).ws_url,
181
+ });
182
+
183
+ chat.on("change", (state) => render(state)); // state.messages, connection, status, typing
184
+ chat.send("Hello");
185
+ ```
186
+
187
+ `chat.state` is a new frozen object on every change, so it plugs into React, Vue or Svelte as is. Events: `message`, `typing`, `status`, `connection`, `error` and `change`. Errors are `NivaChatError` with `code` and `fatal`. `persist` (`"tab"` by default, `"browser"` or `"none"`) keeps the conversation across a page reload.
188
+
164
189
  ## Compatibility
165
190
 
166
191
  The SDK is generated from, and handshakes against, the server `/api/v1` contract.
package/chat.d.ts ADDED
@@ -0,0 +1,2 @@
1
+ /** GENERATED by bun run build (NIVA-482): declarations of the `./chat` subpath. */
2
+ export * from "./dts/src/chat/index.js";