@vinaverse/client 0.0.0-stage → 0.1.0-alpha.1

package/README.md

@@ -1,3 +1,93 @@
-# Temporary Holding Version
+# @vinaverse/client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The realtime session for apps: a conversation with an agent over the WebSocket, with SSE as the fallback, that
+reconnects and resumes, resends what was never acknowledged, and gives typed events and cards. Headless: it holds
+the conversation's state, and your app draws it. Runs in React Native, browsers and Node 18+, with no runtime
+dependencies.
+
+```sh
+npm install @vinaverse/client
+```
+
+## Use
+
+Your backend creates the session with its service key (`@vinaverse/server`) and hands the app the session's `id`,
+`realtime_url`, `turns_url` and `client_secret`. The app never holds a service key: the client refuses one.
+
+```ts
+import { VinaverseSession, isKnownCard } from '@vinaverse/client';
+
+const session = new VinaverseSession({
+  session, // from your backend
+  // On 4401, a fresh secret for the session in use: after resume() that is the newer one.
+  refreshSecret: (sessionId) => api.refreshClientSecret(sessionId),
+  // React Native and Node 22+: their WebSocket takes headers
+  // auth: 'header',
+});
+
+session.on('state', (state) => render(state)); // messages, cards, the open question, what is not sent
+session.on('event', (event) => {
+  if (event.type === 'message.delta') appendStreaming(event.text);
+});
+session.on('status', (status) => {
+  if (status !== 'ended') return;
+  // Ended idle, expired or at its limit: on the next action, a new session for the conversation, then resume().
+  if (session.state.reconnect === 'new_session_on_next_action') resumeOnNextAction();
+  else showContinuedElsewhere(); // replaced or revoked: resume only on the user's action
+});
+session.connect(); // now: a client secret opens its first connection within two minutes of issue
+
+session.sendText('Find me a silk press stylist near Midtown');
+session.answer(card.id, card.question.question_id, { values: ['opt_repair'] });
+session.reportOutcome(proposalCard.id, 'confirmed'); // after your backend applied it
+
+for (const card of session.state.cards) if (isKnownCard(card.card)) draw(card);
+```
+
+- **Connect early.** The gateway accepts a client secret's first connection within two minutes of issue
+  (`client_secret.expires_at`). Call `connect()` when the conversation opens, or pass `refreshSecret`: otherwise a
+  person who types after that window gets an `unauthorized` session.
+- **Resume** a conversation on a new session your backend created (by `conversation_key` or `conversation_id`):
+  `session.resume(newSession)`. The client resends what the old one never acknowledged.
+- **Idle.** After 10 minutes without input (pings do not count) the gateway ends the session: the status is `ended`
+  with `state.reconnect` `new_session_on_next_action`. On the person's next action, have your backend create a new
+  session for the same conversation (`conversation_id` or `conversation_key`) and call `session.resume(newSession)`.
+  Anything sent in between is held and resent there (`state.heldForNextSession` lists it, to draw as "sends when
+  you continue"); `connect()` would only spend a dead secret, so it throws `needs_new_session`.
+- **Turn limit.** When a session has no turns left, the text sent is held, not refused: the status is `ended` with
+  `state.reconnect` `new_session_on_next_action`, as after an idle close. Create the next session from your backend and
+  `resume()`; the held text is sent there.
+- **The end of the session.** `session.expiring` arrives about a minute before it (WebSocket only), and
+  `state.expiring` holds its seconds left: a good moment to have your backend create the next session.
+- **Background**: `session.setForeground(false)` stops the pings.
+- **Drawing the conversation.** Sort `state.messages` and `state.cards` together by `seq`, and key each by its `key`
+  (messages) or `id` (cards). `state.streaming` is the reply so far; a reply cut off stays, with `partial`. When a
+  person from the business takes over, `state.takeover` names their role: draw `role: 'staff'` messages as that
+  person, never as the agent. Always show `state.disclosure`.
+- **Without a WebSocket** (after two failed first connections, or none in the runtime) the session runs turns over
+  SSE (`status === 'sse'`) and `connect()` tries the WebSocket again. Answers to question cards need the WebSocket:
+  one that cannot be sent is shown as not sent (its question unlocks) and reported on the `error` listener.
+- **`auth: 'header'`** works where the WebSocket takes headers: React Native, and Node 22+ with the default factory.
+  A browser's cannot: keep the default (`subprotocol`).
+
+## A UI on top: the conversation store
+
+`@vinaverse/client/conversation` holds a whole conversation for a UI, with no framework: an immutable, structurally
+shared view (`getSnapshot`, `subscribe`), the streaming reply once per frame, resume on the person's next action,
+pending and held texts, proposals decided through your handler. The UI kits bind to it.
+
+```ts
+import { createConversation } from '@vinaverse/client/conversation';
+
+const conversation = createConversation({ getSession: (req) => api.vinaverseSession(req) });
+conversation.start();
+conversation.subscribe(() => draw(conversation.getSnapshot()));
+```
+
+[docs/architecture/conversation.md](../../docs/architecture/conversation.md).
+
+How it works, and what it guarantees: [docs/architecture/client.md](../../docs/architecture/client.md).
+
+## License
+
+Apache-2.0