@hibira-io/chat-ui 0.1.0 → 0.2.0

package/README.md

@@ -78,6 +78,34 @@ 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

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;

package/hibira.js

@@ -0,0 +1,187 @@
+// A client for the Hibira Chat API's user routes (/apps/{appId}/chat/me),
+// and an adapter that turns one of its conversations into a
+// createConversation() for the components. The user token comes from your
+// server (an HS256 JWT signed with the app secret, { sub, exp }); messages
+// are stored by Hibira, so you write no load/send routes.
+
+import { createConversation } from './conversation.js';
+
+export const DEFAULT_HOST = 'api.hibira.io';
+
+/** A user token's claims, read without checking them ({} when unreadable). */
+function claims(token) {
+  try {
+    const part = String(token).split('.')[1].replace(/-/g, '+').replace(/_/g, '/');
+    const bin = atob(part.padEnd(part.length + ((4 - (part.length % 4)) % 4), '='));
+    return JSON.parse(new TextDecoder().decode(Uint8Array.from(bin, (c) => c.charCodeAt(0)))) ?? {};
+  } catch {
+    return {};
+  }
+}
+
+/** The user ID (sub) inside a user token, or '' when it cannot be read. */
+export const tokenUser = (token) => String(claims(token).sub ?? '');
+
+/** An error answered by the Chat API, with its HTTP status. */
+export class ChatApiError extends Error {
+  constructor(status, message) {
+    super(message || `Chat API request failed (${status})`);
+    this.name = 'ChatApiError';
+    this.status = status;
+  }
+}
+
+/**
+ * The Chat API as the signed-in user.
+ *
+ * options:
+ *   appId     the Hibira app ID (required)
+ *   token     the user token: a string, or a function returning one (or a
+ *             promise of one), called again before it expires and after a 401
+ *   tokenUrl  instead of token: a URL on your site that answers {token}
+ *   host      the HTTP API host (default api.hibira.io); may include http://
+ *   fetch     a fetch implementation (default globalThis.fetch)
+ */
+export function createChatClient(options = {}) {
+  if (!options.appId) throw new TypeError('createChatClient: appId is required');
+  if (!options.token && !options.tokenUrl) throw new TypeError('createChatClient: token or tokenUrl is required');
+  const doFetch = options.fetch ?? ((...a) => globalThis.fetch(...a));
+  let host = String(options.host ?? DEFAULT_HOST);
+  while (host.endsWith('/')) host = host.slice(0, -1);
+  const base = `${/^https?:\/\//.test(host) ? host : `https://${host}`}/apps/${encodeURIComponent(options.appId)}/chat/me`;
+  let token = typeof options.token === 'string' ? options.token : null;
+  let pending = null;
+
+  async function fetchToken() {
+    if (typeof options.token === 'string') return options.token;
+    if (typeof options.token === 'function') return options.token();
+    const res = await doFetch(options.tokenUrl, { credentials: 'include', headers: { Accept: 'application/json' } });
+    if (!res.ok) throw new ChatApiError(res.status, `token endpoint answered ${res.status}`);
+    return (await res.json()).token;
+  }
+
+  function currentToken(force) {
+    const exp = token ? claims(token).exp ?? 0 : 0;
+    if (!force && token && (exp === 0 || exp - Date.now() / 1000 > 30)) return Promise.resolve(token);
+    pending ??= Promise.resolve(fetchToken())
+      .then((t) => (token = t))
+      .finally(() => (pending = null));
+    return pending;
+  }
+
+  async function call(method, path, { body, query, signal } = {}) {
+    const params = Object.entries(query ?? {}).filter(([, v]) => v !== undefined && v !== null && v !== '');
+    const qs = new URLSearchParams(params.map(([k, v]) => [k, String(v)])).toString();
+    const url = base + path + (qs ? `?${qs}` : '');
+    for (let attempt = 0; ; attempt++) {
+      const t = await currentToken(attempt > 0);
+      const res = await doFetch(url, {
+        method,
+        signal,
+        headers: { Authorization: `Bearer ${t}`, ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}) },
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+      });
+      if (res.status === 401 && attempt === 0 && typeof options.token !== 'string') continue;
+      const data = await res.json().catch(() => ({}));
+      if (!res.ok) throw new ChatApiError(res.status, data?.error);
+      return data;
+    }
+  }
+
+  const conv = (id) => `/conversations/${encodeURIComponent(id)}`;
+
+  return {
+    /** The token's user, once a token is known. */
+    user: () => (token ? tokenUser(token) : ''),
+    conversations: ({ limit, before, signal } = {}) => call('GET', '/conversations', { query: { limit, before }, signal }),
+    conversation: (id, { signal } = {}) => call('GET', conv(id), { signal }).then((d) => d.conversation),
+    messages: (id, { after, last, limit, signal } = {}) => call('GET', `${conv(id)}/messages`, { query: { after, last, limit }, signal }),
+    search: (id, q, { before, limit, signal } = {}) => call('GET', `${conv(id)}/search`, { query: { q, before, limit }, signal }),
+    send: (id, message) => call('POST', `${conv(id)}/messages`, { body: typeof message === 'string' ? { text: message } : message }),
+    edit: (id, seq, change) => call('PUT', `${conv(id)}/messages/${seq}`, { body: typeof change === 'string' ? { text: change } : change }).then((d) => d.message),
+    remove: (id, seq) => call('DELETE', `${conv(id)}/messages/${seq}`).then((d) => d.message),
+    react: (id, seq, emoji, on = true) =>
+      (on
+        ? call('POST', `${conv(id)}/messages/${seq}/reactions`, { body: { emoji } })
+        : call('DELETE', `${conv(id)}/messages/${seq}/reactions`, { query: { emoji } })
+      ).then((d) => d.message),
+    report: (id, seq, reason) => call('POST', `${conv(id)}/messages/${seq}/reports`, { body: { reason } }).then((d) => d.report),
+    read: (id, seq) => call('POST', `${conv(id)}/read`, { body: { seq } }),
+    typing: (id, typing = true) => call('POST', `${conv(id)}/typing`, { body: { typing } }),
+    /** Uploads a File or Blob; send its result in a message's attachments. */
+    async upload(id, file, { name } = {}) {
+      const fileName = name ?? file?.name ?? 'file';
+      const { attachment, upload } = await call('POST', `${conv(id)}/attachments`, {
+        body: { name: fileName, content_type: file.type || 'application/octet-stream', size: file.size },
+      });
+      const res = await doFetch(upload.url, { method: upload.method ?? 'PUT', headers: upload.headers ?? {}, body: file });
+      if (!res.ok) throw new ChatApiError(res.status, 'Upload failed');
+      return attachment;
+    },
+  };
+}
+
+/** Chat API events, sent to each member's user channel (pusher.signin). */
+export const CHAT_EVENTS = Object.freeze(['chat.message', 'chat.message_updated', 'chat.typing', 'chat.read', 'chat.conversation', 'chat.left', 'chat.deleted']);
+
+/**
+ * Binds Chat API events on a signed-in pusher-js client; returns unbind.
+ * @param {any} pusher
+ * @param {(event: string, data: any) => void} handler
+ */
+export function onChatEvents(pusher, handler) {
+  const user = pusher?.user;
+  if (!user?.bind) return () => {};
+  const fns = CHAT_EVENTS.map((e) => {
+    const fn = (data) => handler(e, data);
+    user.bind(e, fn);
+    return [e, fn];
+  });
+  return () => fns.forEach(([e, fn]) => user.unbind?.(e, fn));
+}
+
+/**
+ * One Chat API conversation as a createConversation(), for <Chat> and
+ * useConversation(). Live events come from pusher (signed in with
+ * pusher.signin()); without it, it polls.
+ * @param {ReturnType<typeof createChatClient>} client
+ * @param {string} id
+ * @param {{ pusher?: any, me?: string, pollMs?: number, livePollMs?: number, onEvent?: (event: string, data: any) => void }} [options]
+ */
+export function chatConversation(client, id, options = {}) {
+  const conversation = createConversation({
+    me: options.me ?? client.user(),
+    pusher: options.pusher,
+    pollMs: options.pollMs,
+    livePollMs: options.livePollMs,
+    onEvent: options.onEvent,
+    load: (after, signal) => client.messages(id, after ? { after, signal } : { last: 50, signal }),
+    send: (text) => client.send(id, { text }),
+  });
+  const start = conversation.start;
+  let unbind = () => {};
+  conversation.start = () => {
+    start();
+    unbind();
+    unbind = onChatEvents(options.pusher, (event, data) => {
+      if (data?.conversation_id !== id) return;
+      const me = options.me ?? client.user();
+      if (event === 'chat.message' || event === 'chat.message_updated') {
+        conversation.added(data.message);
+        if (event === 'chat.message') conversation.hint('message', { from: data.message?.sender, seq: data.message?.seq });
+      } else if (event === 'chat.typing') {
+        if (data.user_id !== me && data.typing !== false) conversation.hint('typing', { from: data.user_id });
+      } else {
+        options.onEvent?.(event, data);
+      }
+    });
+    return () => conversation.stop();
+  };
+  const stop = conversation.stop;
+  conversation.stop = () => {
+    unbind();
+    unbind = () => {};
+    stop();
+  };
+  return conversation;
+}

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@hibira-io/chat-ui",
-  "version": "0.1.0",
-  "description": "Agentic chat UI for support and AI agents over Hibira realtime channels: Markdown messages, agent steps, typed replies, follow-up suggestions and human handoff, for React",
+  "version": "0.2.0",
+  "description": "Agentic chat UI for support and AI agents over Hibira realtime channels: Markdown messages, agent steps, typed replies, follow-up suggestions and human handoff, and a client for the Hibira Chat API, for React",
   "keywords": [
     "chat",
     "chat-ui",
+    "chat-api",
     "ai",
     "agent",
     "ai-chat",
@@ -41,6 +42,10 @@
       "types": "./react.d.ts",
       "default": "./react.js"
     },
+    "./hibira": {
+      "types": "./hibira.d.ts",
+      "default": "./hibira.js"
+    },
     "./server": {
       "types": "./server.d.ts",
       "default": "./server.js"
@@ -58,6 +63,8 @@
     "conversation.js",
     "locales.js",
     "types.d.ts",
+    "hibira.js",
+    "hibira.d.ts",
     "react.js",
     "react.d.ts",
     "server.js",

package/react.d.ts

@@ -1,5 +1,6 @@
 import type { ReactElement, ReactNode } from 'react';
 import type { AgentStep, ChatLabels, ChatMessage, Conversation, ConversationState, LabelOverrides } from './types.js';
+import type { ChatClient, ChatConversationOptions } from './hibira.js';
 
 export type * from './types.js';
 export { createConversation } from './index.js';
@@ -29,6 +30,7 @@ export interface ChatThreadProps {
 export function ChatThread(props: ChatThreadProps): ReactElement;
 export function Chat(props: Omit<ChatThreadProps, 'messages' | 'typing' | 'step' | 'onSend'> & { conversation: Conversation | null }): ReactElement;
 export function useConversation(conversation: Conversation | null): ConversationState;
+export function useChatConversation(client: ChatClient | null, id: string | null, options?: ChatConversationOptions): Conversation | null;
 export function Markdown(props: { text: string; locale?: string; labels?: LabelOverrides; origin?: string; imageOrigins?: string[] }): ReactElement;
 export function AgentSteps(props: { typing: boolean; step?: AgentStep; locale?: string; labels?: ChatLabels }): ReactElement | null;
 export function Suggestions(props: { items: string[]; onPick: (text: string) => void; disabled?: boolean; locale?: string; labels?: ChatLabels }): ReactElement | null;

package/react.js

@@ -3,10 +3,11 @@
 // buttons and a reply box. Import '@hibira-io/chat-ui/styles.css' for the
 // default look.
 
-import { createElement as h, Fragment, useEffect, useRef, useState, useSyncExternalStore } from 'react';
+import { createElement as h, Fragment, useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
 import { parseMarkdown } from './markdown.js';
 import { isAutomatic, STEPS } from './conversation.js';
 import { format, labelsFor } from './locales.js';
+import { chatConversation } from './hibira.js';
 
 export { createConversation } from './conversation.js';
 
@@ -377,3 +378,9 @@ export function Chat({ conversation, ...props }) {
   const state = useConversation(conversation);
   return h(ChatThread, { messages: state.messages, typing: state.typing, step: state.step, onSend: conversation ? (t) => conversation.send(t) : undefined, ...props });
 }
+
+/** A Hibira Chat API conversation (createChatClient) for <Chat>, made once per client, id and pusher. */
+export function useChatConversation(client, id, options = {}) {
+  const { pusher, me } = options;
+  return useMemo(() => (client && id ? chatConversation(client, id, options) : null), [client, id, pusher, me]); // eslint-disable-line react-hooks/exhaustive-deps
+}