@hibira-io/chat-ui 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hibira
+
+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:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PROTOCOL.md

@@ -0,0 +1,71 @@
+# Chat protocol v1
+
+How the `@hibira-io/chat-ui` components talk to your backend and to a
+[Hibira](https://hibira.io) channel. Any backend can implement it; the
+`server` helpers do the channel side for Node.
+
+## Principles
+
+- **Your backend stores messages.** Pages read them over HTTPS from your
+  routes (the `load` and `send` functions you pass to `createConversation`).
+- **The channel carries hints only**: small events that say "something
+  changed". A page that misses one catches up on its next poll, so a lost
+  event never loses a message, and message text never crosses the socket.
+- One channel per conversation. Use a private channel (for example
+  `private-chat.{conversationId}`) and authorize only the people in it.
+
+## Message
+
+```json
+{
+  "id": "msg_01",
+  "seq": 7,
+  "sender": "agent",
+  "name": "Support",
+  "text": "Markdown text",
+  "created_at": "2026-10-31T12:00:00Z",
+  "metadata": { "assistant": true, "suggestions": ["Is there a free plan?"] }
+}
+```
+
+| Field | Meaning |
+| --- | --- |
+| `seq` | Position in the conversation, increasing by one. Pages ask for messages after the last `seq` they have. |
+| `sender` | `customer` for the person using the chat (the page's `me`), anything else for your side (`agent`, `operator`, ...). |
+| `text` | Markdown. Pages render it without HTML (see the README). |
+| `metadata.assistant` | `true` on a reply your agent wrote: shown as an automatic reply. |
+| `metadata.handoff` | `true` when the agent passed the conversation to a person. |
+| `metadata.suggestions` | Up to 3 follow-up questions; the customer sends one with a tap. Clean them with `cleanSuggestions()`. |
+
+## Routes (yours)
+
+- `load(after)`: return `{ messages: Message[] }` with the messages whose
+  `seq > after`, oldest first. Anything else you return (status, read
+  marks) shows up as `state.extra`.
+- `send(text)`: store the customer's message and return it (or
+  `{ message }`). Then send the `message` hint.
+
+## Events on the conversation's channel
+
+| Event | Data | Sent when |
+| --- | --- | --- |
+| `message` | `{ "seq": 7, "from": "agent" }` | A message was stored. Pages read what they have not seen. |
+| `typing` | `{ "from": "agent", "step": "writing" }` | Someone is writing. Repeat every ~4 s while it lasts; pages hide it after 8 s without one, or when that side's message arrives. |
+| anything else | your data | Passed to `onEvent` (status changes, read marks, ...). |
+
+### Agent steps
+
+While your agent writes a reply, send `typing` with a `step` each time it
+moves on. Pages show the steps so far with a check and the current one with
+a spinner. Send only steps your agent really takes:
+
+| Step | Shown as (en) |
+| --- | --- |
+| `reading` | Reading your question |
+| `account` | Looking at your account |
+| `searching` | Searching our docs |
+| `writing` | Writing a reply |
+| `checking` | Checking the reply |
+
+Other step names show as plain typing unless you add labels for them
+(`labels.steps`).

package/README.md

@@ -1,3 +1,157 @@
-# Temporary Holding Version
+# chat-ui
 
-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.
+A small, open-source chat interface for support conversations where an AI agent answers first and a person steps in when needed. It shows what the agent is doing while it writes, renders safe Markdown, offers follow-up questions, and marks when a conversation is handed to your team.
+
+![A support conversation with an automatic reply, a code block and suggested follow-up questions](art/thread-en-desktop-light.png)
+
+| Agent steps (zh-TW, mobile) | Handed to a person (ja, dark) |
+| --- | --- |
+| ![Agent steps while a reply is written](art/steps-zh-TW-mobile-light.png) | ![A reply marked as passed to the team](art/handoff-ja-mobile-dark.png) |
+
+- **Agent steps**: "Reading your question", "Looking at your account", "Writing a reply"… shown live, from hints your backend sends.
+- **Safe Markdown**: parsed into elements, never HTML. Only http(s), mailto and same-site links; images show inline only from origins you allow.
+- **Follow-up suggestions**: up to three short questions the customer can send with one tap.
+- **Handoff**: a reply can say it was passed to a person, and the badge shows it.
+- **Typewriter reveal**, copy buttons on replies and code blocks, a "Seen" marker.
+- **Seven languages** built in: en, zh-TW, zh-CN, ja, ko, th, vi.
+- **Small**: about 9 KB of JavaScript and 2 KB of CSS gzipped, no runtime dependencies. React is an optional peer.
+
+It works with any backend. Messages live in your database and are read over HTTPS; a realtime channel on [Hibira](https://hibira.io) (or any Pusher-compatible service) only carries hints, so a missed event costs a poll, never a message. See [PROTOCOL.md](PROTOCOL.md).
+
+## Install
+
+```sh
+npm install @hibira-io/chat-ui pusher-js
+```
+
+## React
+
+```jsx
+import { useEffect } from 'react';
+import Pusher from 'pusher-js';
+import { Chat, createConversation } from '@hibira-io/chat-ui/react';
+import '@hibira-io/chat-ui/styles.css';
+
+const pusher = new Pusher('YOUR_APP_KEY', { wsHost: 'ws.hibira.io', forceTLS: true, cluster: '' });
+
+const conversation = createConversation({
+  pusher,
+  channel: `private-conversation-${conversationId}`,
+  load: (after, signal) => fetch(`/api/conversations/${conversationId}/messages?after=${after}`, { signal }).then((r) => r.json()),
+  send: (text) =>
+    fetch(`/api/conversations/${conversationId}/messages`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ text }),
+    }).then((r) => r.json()),
+});
+
+export function SupportChat() {
+  useEffect(() => conversation.start(), []);
+  return <Chat conversation={conversation} locale="ja" />;
+}
+```
+
+`load(after)` returns `{ messages: [...] }` with every message whose `seq` is greater than `after`. A message looks like:
+
+```js
+{
+  seq: 12,
+  sender: 'agent',            // or 'customer'; `me` (default "customer") is the person on this page
+  text: 'Here is how to **rotate** a key…',
+  created_at: '2026-10-31T09:00:00Z',
+  metadata: { assistant: true, suggestions: ['How do I revoke the old key?'] },
+}
+```
+
+The pieces are exported on their own too: `ChatThread` (controlled: pass `messages`, `typing`, `step`, `onSend`), `Markdown`, `AgentSteps`, `Suggestions`, `CopyButton` and `useReveal`.
+
+## Without a framework
+
+```js
+import { createConversation, parseMarkdown } from '@hibira-io/chat-ui';
+
+const conversation = createConversation({ pusher, channel, load, send });
+conversation.subscribe((state) => render(state)); // { messages, loading, error, typing, step }
+conversation.start();
+```
+
+`parseMarkdown(text, { origin, imageOrigins })` returns a plain block tree you can render with anything.
+
+## Hibira Chat API
+
+With the [Hibira Chat API](https://hibira.io) Hibira stores the messages, so
+you write no `load` or `send` routes. Your server creates conversations and
+gives each signed-in user a **user token** (an HS256 JWT signed with the app
+secret, `{ sub, exp }`); the page talks to Hibira directly.
+
+```jsx
+import Pusher from 'pusher-js';
+import { createChatClient } from '@hibira-io/chat-ui/hibira';
+import { Chat, useChatConversation } from '@hibira-io/chat-ui/react';
+
+const client = createChatClient({ appId: 'your-app-id', tokenUrl: '/hibira/token' });
+const pusher = new Pusher('your-key', { wsHost: 'ws.hibira.io', userAuthentication: { endpoint: '/pusher/user-auth' } });
+pusher.signin(); // Chat API events arrive on the user's own channel
+
+function Trip({ userId }) {
+  const conversation = useChatConversation(client, 'trip-1', { pusher, me: userId });
+  return <Chat conversation={conversation} me={userId} locale="zh-TW" />;
+}
+```
+
+The client does the rest of the API as the token's user: `conversations()`
+(with `unread`), `messages()`, `search(id, q)`, `send(id, { text, attachments })`,
+`edit()`, `remove()`, `react(id, seq, emoji, on)`, `read()`, `typing()`,
+`report()` and `upload(id, file)` (presigned, up to 25 MB). Edits, deletes and
+reactions from other members update the thread live through `pusher.user`.
+
+## Server (Node)
+
+```js
+import Pusher from 'pusher';
+import { createChatServer, agentMetadata } from '@hibira-io/chat-ui/server';
+
+const pusher = new Pusher({ appId, key, secret, host: 'api.hibira.io', useTLS: true });
+const chat = createChatServer({ pusher });
+
+const typing = chat.agentTyping(channel);       // "Reading your question", repeated every 4 s
+typing.step('account');                         // "Looking at your account"
+const answer = await yourAgent(question);
+typing.step('writing');
+typing.step('checking');
+const msg = await db.saveMessage({
+  sender: 'agent',
+  text: answer.text,
+  metadata: agentMetadata({ handoff: answer.handoff, suggestions: answer.suggestions }),
+});
+typing.stop();
+await chat.message(channel, { seq: msg.seq, from: 'agent' });
+```
+
+`agentMetadata` keeps at most three short suggestions and drops any with links, line breaks or markup, since the customer sends them as their own words. Only send the steps your agent really goes through.
+
+## Styling
+
+Every color is a CSS variable on `.hb-chat`:
+
+```css
+.hb-chat {
+  --hb-chat-accent: #3e63dd;
+  --hb-chat-radius: 10px;
+  --hb-chat-max-height: 480px;
+}
+```
+
+Dark mode follows `prefers-color-scheme`, or set `data-theme="dark"` / `"light"` on any ancestor. Labels can be overridden one by one with `labels={{ handoff: 'With our support team' }}`.
+
+## Safety
+
+- Message text is never inserted as HTML.
+- Links open only for `http:`, `https:`, `mailto:` and same-site paths, with `rel="noopener noreferrer"`.
+- Images render inline only from `origin` and `imageOrigins`; any other image becomes a plain link, so a message cannot make the page load third-party content.
+- Treat replies from your agent as untrusted text, like any customer message.
+
+## License
+
+MIT © Hibira

package/conversation.js

@@ -0,0 +1,188 @@
+// A conversation kept up to date in the browser, without a UI framework.
+//
+// Messages are read from your backend (`load`), never from the socket:
+// events on the conversation's channel are hints (PROTOCOL.md). A `message`
+// hint makes it read what it has not seen; a `typing` hint shows that the
+// other side (a person or your agent) is writing, with the agent's `step`.
+// A missed event costs a poll, never a message: it polls slowly while the
+// socket is up and every few seconds without one.
+
+/** What an agent can be doing while it writes a reply, in order (PROTOCOL.md). */
+export const STEPS = Object.freeze(['reading', 'account', 'searching', 'writing', 'checking']);
+
+/** Polling intervals, with the socket connected (a safety net) and without. */
+export const POLL_LIVE_MS = 60_000;
+export const POLL_MS = 10_000;
+/** How long a typing hint shows without another one. */
+export const TYPING_SHOW_MS = 8_000;
+
+/** Merges a page of messages into a list ordered by seq, without repeats. */
+export function mergeMessages(list, page) {
+  if (!page?.length) return list;
+  const bySeq = new Map(list.map((m) => [m.seq, m]));
+  for (const m of page) bySeq.set(m.seq, m);
+  return [...bySeq.values()].sort((a, b) => a.seq - b.seq);
+}
+
+export const lastSeq = (list) => (list.length ? list[list.length - 1].seq : 0);
+
+/** An automatic reply (your agent marks it in metadata). */
+export const isAutomatic = (m) => !!m?.metadata?.assistant;
+
+/**
+ * @param {{
+ *   load: (after: number, signal: AbortSignal) => Promise<{ messages: any[] } & Record<string, any>>,
+ *   send?: (text: string) => Promise<any>,
+ *   pusher?: any,
+ *   channel?: string,
+ *   me?: string,
+ *   pollMs?: number,
+ *   livePollMs?: number,
+ *   onEvent?: (event: string, data: any) => void,
+ * }} options
+ */
+export function createConversation(options) {
+  if (typeof options?.load !== 'function') throw new TypeError('createConversation() needs a load(after, signal) function.');
+  const me = options.me ?? 'customer';
+  const pollMs = options.pollMs ?? POLL_MS;
+  const livePollMs = options.livePollMs ?? POLL_LIVE_MS;
+  let state = { messages: [], loading: true, error: null, typing: false, step: undefined, extra: {} };
+  const listeners = new Set();
+  let timer = null;
+  let typingTimer = null;
+  let abort = null;
+  let inflight = null;
+  let again = false;
+  let stopped = true;
+  let unbind = [];
+
+  const set = (patch) => {
+    state = { ...state, ...patch };
+    listeners.forEach((fn) => fn(state));
+  };
+
+  const connected = () => options.pusher?.connection?.state === 'connected';
+
+  function schedule() {
+    if (stopped) return;
+    clearTimeout(timer);
+    timer = setTimeout(() => void refresh(), connected() ? livePollMs : pollMs);
+  }
+
+  function setTyping(on, step) {
+    clearTimeout(typingTimer);
+    typingTimer = on ? setTimeout(() => setTyping(false), TYPING_SHOW_MS) : null;
+    const next = on ? step : undefined;
+    if (state.typing !== on || state.step !== next) set({ typing: on, step: next });
+  }
+
+  function onHint(event, data) {
+    const d = data && typeof data === 'object' ? data : {};
+    if (event === 'typing') {
+      if (d.from !== me) setTyping(true, typeof d.step === 'string' ? d.step : undefined);
+      return;
+    }
+    if (event === 'message') {
+      if (d.from !== me) setTyping(false);
+      if (typeof d.seq === 'number' && d.seq <= lastSeq(state.messages)) return;
+      void refresh();
+      return;
+    }
+    options.onEvent?.(event, d);
+  }
+
+  /** Reads what is new; calls made while one runs fold into one more. */
+  function refresh() {
+    if (stopped) return Promise.resolve();
+    if (inflight) {
+      again = true;
+      return inflight;
+    }
+    const run = async () => {
+      do {
+        again = false;
+        abort = new AbortController();
+        try {
+          const { messages = [], ...extra } = await options.load(lastSeq(state.messages), abort.signal);
+          if (stopped) return;
+          set({ messages: mergeMessages(state.messages, messages), extra: { ...state.extra, ...extra }, error: null, loading: false });
+        } catch (err) {
+          if (stopped || err?.name === 'AbortError') return;
+          set({ error: err, loading: false });
+        }
+      } while (again && !stopped);
+    };
+    inflight = run().finally(() => {
+      inflight = null;
+      schedule();
+    });
+    return inflight;
+  }
+
+  function start() {
+    if (!stopped) return stop;
+    stopped = false;
+    const { pusher, channel } = options;
+    if (pusher && channel) {
+      const ch = pusher.subscribe(channel);
+      const global = (event, data) => {
+        if (event.startsWith('pusher:') || event.startsWith('pusher_internal:')) return;
+        onHint(event, data);
+      };
+      const subscribed = () => void refresh();
+      ch.bind_global(global);
+      ch.bind('pusher:subscription_succeeded', subscribed);
+      const state = () => schedule();
+      pusher.connection?.bind?.('state_change', state);
+      unbind.push(() => {
+        ch.unbind_global(global);
+        ch.unbind('pusher:subscription_succeeded', subscribed);
+        pusher.connection?.unbind?.('state_change', state);
+      });
+    }
+    if (typeof document !== 'undefined') {
+      const vis = () => document.visibilityState === 'visible' && void refresh();
+      document.addEventListener('visibilitychange', vis);
+      unbind.push(() => document.removeEventListener('visibilitychange', vis));
+    }
+    void refresh();
+    return stop;
+  }
+
+  function stop() {
+    stopped = true;
+    clearTimeout(timer);
+    clearTimeout(typingTimer);
+    abort?.abort();
+    unbind.forEach((fn) => fn());
+    unbind = [];
+  }
+
+  /** Adds a message the page just sent (the server's copy). */
+  function added(message) {
+    if (message && typeof message.seq === 'number') set({ messages: mergeMessages(state.messages, [message]) });
+  }
+
+  /** Sends through options.send and adds the message it returns. */
+  async function send(text) {
+    if (!options.send) throw new Error('createConversation() has no send(text) function.');
+    const out = await options.send(text);
+    added(out?.message ?? out);
+    return out;
+  }
+
+  return {
+    get: () => state,
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    },
+    start,
+    stop,
+    refresh,
+    added,
+    send,
+    /** For tests and custom transports: deliver a hint as if from the channel. */
+    hint: onHint,
+  };
+}

package/hibira.d.ts

@@ -0,0 +1,107 @@
+import type { ChatMessage, Conversation } from './types.js';
+
+export const DEFAULT_HOST: string;
+export const CHAT_EVENTS: readonly string[];
+
+export interface ChatClientOptions {
+  /** The Hibira app ID. */
+  appId: string;
+  /** The user token, or a function returning one; called again before it expires and after a 401. */
+  token?: string | (() => string | Promise<string>);
+  /** Instead of token: a URL on your site that answers { token }. */
+  tokenUrl?: string;
+  /** The HTTP API host (default api.hibira.io); may include http://. */
+  host?: string;
+  fetch?: typeof fetch;
+}
+
+export interface Attachment {
+  id: string;
+  name: string;
+  content_type: string;
+  size: number;
+  /** A download link, valid for an hour. */
+  url?: string;
+}
+
+/** A message of the Hibira Chat API. */
+export interface ChatApiMessage extends ChatMessage {
+  id: string;
+  kind?: string;
+  created_at: string;
+  edited_at?: string;
+  deleted_at?: string;
+  /** Each emoji and the members who reacted, in order. */
+  reactions?: Record<string, string[]>;
+  attachments?: Attachment[];
+}
+
+export interface ChatApiConversation {
+  id: string;
+  name?: string;
+  metadata?: Record<string, unknown>;
+  members: { user_id: string; read_seq: number }[];
+  last_seq: number;
+  created_at: string;
+  updated_at: string;
+  /** In conversations(): last_seq minus the user's read_seq. */
+  unread?: number;
+}
+
+export interface SendInput {
+  text?: string;
+  name?: string;
+  metadata?: Record<string, unknown>;
+  attachments?: Attachment[] | { id: string }[];
+}
+
+export interface Report {
+  id: string;
+  conversation_id: string;
+  seq: number;
+  reported_by: string;
+  reason: string;
+  message: ChatApiMessage;
+}
+
+type Opts = { signal?: AbortSignal };
+
+export interface ChatClient {
+  /** The token's user (sub), once a token is known. */
+  user(): string;
+  conversations(options?: { limit?: number; before?: string } & Opts): Promise<{ conversations: ChatApiConversation[]; next: string }>;
+  conversation(id: string, options?: Opts): Promise<ChatApiConversation>;
+  messages(id: string, options?: { after?: number; last?: number; limit?: number } & Opts): Promise<{ messages: ChatApiMessage[]; last_seq: number }>;
+  search(id: string, q: string, options?: { before?: number | string; limit?: number } & Opts): Promise<{ messages: ChatApiMessage[]; next: string }>;
+  send(id: string, message: string | SendInput): Promise<{ message: ChatApiMessage; push?: { users: number; error?: string } }>;
+  edit(id: string, seq: number, change: string | { text?: string; metadata?: Record<string, unknown> }): Promise<ChatApiMessage>;
+  remove(id: string, seq: number): Promise<ChatApiMessage>;
+  react(id: string, seq: number, emoji: string, on?: boolean): Promise<ChatApiMessage>;
+  report(id: string, seq: number, reason?: string): Promise<Report>;
+  read(id: string, seq: number): Promise<{ read_seq: number }>;
+  typing(id: string, typing?: boolean): Promise<unknown>;
+  /** Uploads a File or Blob (up to 25 MB); send the result in a message's attachments. */
+  upload(id: string, file: Blob & { name?: string }, options?: { name?: string }): Promise<Attachment>;
+}
+
+export class ChatApiError extends Error {
+  status: number;
+  constructor(status: number, message?: string);
+}
+
+export function createChatClient(options: ChatClientOptions): ChatClient;
+export function tokenUser(token: string): string;
+export function onChatEvents(pusher: unknown, handler: (event: string, data: any) => void): () => void;
+
+export interface ChatConversationOptions {
+  /** A pusher-js instance signed in as the user (pusher.signin()). Without one it polls. */
+  pusher?: unknown;
+  /** The user ID (default: the token's sub). */
+  me?: string;
+  pollMs?: number;
+  livePollMs?: number;
+  /** chat.read, chat.conversation, chat.left and chat.deleted for this conversation. */
+  onEvent?: (event: string, data: any) => void;
+}
+
+export function chatConversation(client: ChatClient, id: string, options?: ChatConversationOptions): Conversation;