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

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/index.d.ts

@@ -0,0 +1,22 @@
+import type { Block, ChatLabels, ChatMessage, Conversation, ConversationOptions, InlineNode, LabelOverrides, MarkdownOptions } from './types.js';
+
+export type * from './types.js';
+
+export function parseMarkdown(text: string, options?: MarkdownOptions): Block[];
+export function parseInline(text: string, options?: MarkdownOptions): InlineNode[];
+export function plainText(text: string): string;
+export function safeHref(url: string): string | null;
+export function imageSrc(url: string, options?: MarkdownOptions): string | null;
+
+export function createConversation(options: ConversationOptions): Conversation;
+export function mergeMessages(list: ChatMessage[], page: ChatMessage[]): ChatMessage[];
+export function lastSeq(list: ChatMessage[]): number;
+export function isAutomatic(message: ChatMessage | undefined | null): boolean;
+export const STEPS: readonly string[];
+export const POLL_MS: number;
+export const POLL_LIVE_MS: number;
+export const TYPING_SHOW_MS: number;
+
+export const LOCALES: Record<'en' | 'zh-TW' | 'zh-CN' | 'ja' | 'ko' | 'th' | 'vi', ChatLabels>;
+export function labelsFor(locale?: string, overrides?: LabelOverrides): ChatLabels;
+export function format(text: string, vars?: Record<string, string | number>): string;

package/index.js

@@ -0,0 +1,7 @@
+// Framework-free core: Markdown as data, the conversation store, labels.
+// React components: '@hibira-io/chat-ui/react'. Server helpers:
+// '@hibira-io/chat-ui/server'.
+
+export { parseMarkdown, parseInline, plainText, safeHref, imageSrc } from './markdown.js';
+export { createConversation, mergeMessages, lastSeq, isAutomatic, STEPS, POLL_MS, POLL_LIVE_MS, TYPING_SHOW_MS } from './conversation.js';
+export { labelsFor, LOCALES, format } from './locales.js';

package/locales.js

@@ -0,0 +1,173 @@
+// Labels for the bundled components. Pass `locale` to pick one, or `labels`
+// to override single strings.
+
+const en = {
+  placeholder: 'Write a message…',
+  send: 'Send',
+  typing: 'Typing…',
+  automatic: 'Automatic reply',
+  handoff: 'Passed to our team',
+  suggestions: 'You might also ask',
+  copy: 'Copy',
+  copied: 'Copied',
+  copyCode: 'Copy code',
+  seen: 'Seen',
+  empty: 'Ask us anything.',
+  tooLong: 'Keep a message under {n} characters.',
+  steps: {
+    reading: 'Reading your question',
+    account: 'Looking at your account',
+    searching: 'Searching our docs',
+    writing: 'Writing a reply',
+    checking: 'Checking the reply',
+  },
+};
+
+const zhTW = {
+  placeholder: '輸入訊息…',
+  send: '送出',
+  typing: '正在輸入…',
+  automatic: '自動回覆',
+  handoff: '已轉交團隊',
+  suggestions: '你可能還想問',
+  copy: '複製',
+  copied: '已複製',
+  copyCode: '複製程式碼',
+  seen: '已讀',
+  empty: '有任何問題都可以問我們。',
+  tooLong: '每則訊息請少於 {n} 個字元。',
+  steps: {
+    reading: '正在閱讀你的問題',
+    account: '正在查看你的帳戶',
+    searching: '正在搜尋文件',
+    writing: '正在撰寫回覆',
+    checking: '正在檢查回覆',
+  },
+};
+
+const zhCN = {
+  placeholder: '输入消息…',
+  send: '发送',
+  typing: '正在输入…',
+  automatic: '自动回复',
+  handoff: '已转交团队',
+  suggestions: '你可能还想问',
+  copy: '复制',
+  copied: '已复制',
+  copyCode: '复制代码',
+  seen: '已读',
+  empty: '有任何问题都可以问我们。',
+  tooLong: '每条消息请少于 {n} 个字符。',
+  steps: {
+    reading: '正在阅读你的问题',
+    account: '正在查看你的账户',
+    searching: '正在搜索文档',
+    writing: '正在撰写回复',
+    checking: '正在检查回复',
+  },
+};
+
+const ja = {
+  placeholder: 'メッセージを入力…',
+  send: '送信',
+  typing: '入力中…',
+  automatic: '自動応答',
+  handoff: '担当チームに引き継ぎ済み',
+  suggestions: 'こちらもよく聞かれます',
+  copy: 'コピー',
+  copied: 'コピーしました',
+  copyCode: 'コードをコピー',
+  seen: '既読',
+  empty: 'お気軽にご質問ください。',
+  tooLong: 'メッセージは {n} 文字未満にしてください。',
+  steps: {
+    reading: 'ご質問を確認しています',
+    account: 'アカウントを確認しています',
+    searching: 'ドキュメントを検索しています',
+    writing: '回答を作成しています',
+    checking: '回答をチェックしています',
+  },
+};
+
+const ko = {
+  placeholder: '메시지를 입력하세요…',
+  send: '보내기',
+  typing: '입력 중…',
+  automatic: '자동 답변',
+  handoff: '담당 팀에 전달됨',
+  suggestions: '이런 질문도 있어요',
+  copy: '복사',
+  copied: '복사됨',
+  copyCode: '코드 복사',
+  seen: '읽음',
+  empty: '무엇이든 물어보세요.',
+  tooLong: '메시지는 {n}자 미만으로 써 주세요.',
+  steps: {
+    reading: '질문을 읽고 있어요',
+    account: '계정을 확인하고 있어요',
+    searching: '문서를 찾고 있어요',
+    writing: '답변을 작성하고 있어요',
+    checking: '답변을 확인하고 있어요',
+  },
+};
+
+const th = {
+  placeholder: 'พิมพ์ข้อความ…',
+  send: 'ส่ง',
+  typing: 'กำลังพิมพ์…',
+  automatic: 'ตอบกลับอัตโนมัติ',
+  handoff: 'ส่งต่อให้ทีมงานแล้ว',
+  suggestions: 'คุณอาจอยากถามต่อ',
+  copy: 'คัดลอก',
+  copied: 'คัดลอกแล้ว',
+  copyCode: 'คัดลอกโค้ด',
+  seen: 'อ่านแล้ว',
+  empty: 'ถามเราได้ทุกเรื่อง',
+  tooLong: 'โปรดเขียนข้อความไม่เกิน {n} ตัวอักษร',
+  steps: {
+    reading: 'กำลังอ่านคำถามของคุณ',
+    account: 'กำลังดูบัญชีของคุณ',
+    searching: 'กำลังค้นหาในเอกสาร',
+    writing: 'กำลังเขียนคำตอบ',
+    checking: 'กำลังตรวจสอบคำตอบ',
+  },
+};
+
+const vi = {
+  placeholder: 'Nhập tin nhắn…',
+  send: 'Gửi',
+  typing: 'Đang nhập…',
+  automatic: 'Trả lời tự động',
+  handoff: 'Đã chuyển cho đội ngũ',
+  suggestions: 'Bạn cũng có thể hỏi',
+  copy: 'Sao chép',
+  copied: 'Đã sao chép',
+  copyCode: 'Sao chép mã',
+  seen: 'Đã xem',
+  empty: 'Hãy hỏi chúng tôi bất cứ điều gì.',
+  tooLong: 'Tin nhắn cần ít hơn {n} ký tự.',
+  steps: {
+    reading: 'Đang đọc câu hỏi của bạn',
+    account: 'Đang xem tài khoản của bạn',
+    searching: 'Đang tìm trong tài liệu',
+    writing: 'Đang viết câu trả lời',
+    checking: 'Đang kiểm tra câu trả lời',
+  },
+};
+
+export const LOCALES = { en, 'zh-TW': zhTW, 'zh-CN': zhCN, ja, ko, th, vi };
+
+/** The labels for a locale ("ja", "zh-Hant-TW", "pt" falls back to English), with overrides. */
+export function labelsFor(locale, overrides) {
+  const tag = String(locale ?? 'en');
+  let base = LOCALES[tag];
+  if (!base) {
+    const lower = tag.toLowerCase();
+    if (lower.startsWith('zh')) base = /hant|tw|hk|mo/.test(lower) ? zhTW : zhCN;
+    else base = LOCALES[lower.split('-')[0]] ?? en;
+  }
+  return { ...base, ...overrides, steps: { ...base.steps, ...overrides?.steps } };
+}
+
+/** Fills {name} placeholders. */
+export const format = (s, vars = {}) => String(s).replace(/\{(\w+)\}/g, (m, k) => (k in vars ? String(vars[k]) : m));