omnix-chat 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Changed
+
+- npm package renamed from `agent-chat` to **`omnix-chat`**; build artifacts are
+  now `dist/omnix-chat.es.js` and `dist/omnix-chat.umd.js`.
+
+## [0.1.0] - Initial public beta
+
+### Added
+
+- Imperative SDK entry: `AgentChat` singleton + `createAgentChat()` factory
+  (`init`, `destroy`, `open`, `close`, `toggle`, `isOpen`, `identify`,
+  `sendMessage`, `prefetch`, `getState`, `on`, `off`).
+- React adapter exposed as the `omnix-chat/react` sub-path:
+  - `<AgentChat />`, `<AgentChatProvider>`, `AgentChatEmbedded`, `useAgentChat()`.
+- DSN parsing (`normalizeDsn`) with `INVALID_DSN` errors for malformed input.
+- Session list, message history, SSE streaming, agent/skill picker, message
+  feedback (like/dislike), table Excel export, chart PNG export.
+- Shadow DOM widget with antd + `@ant-design/x`; `theme: 'light' | 'dark' | 'auto'`.
+- Vite library build producing ESM + UMD for `omnix-chat` and `omnix-chat/react`,
+  plus `vite-plugin-dts`-generated `.d.ts`.
+- UMD attaches `window.AgentChat`.
+- Playground at `demo/`; CDN and React examples under `examples/`.
+
+[Unreleased]: https://github.com/your-org/omnix-chat/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/your-org/omnix-chat/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 omnix-chat contributors
+
+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/README.md

@@ -0,0 +1,360 @@
+# omnix-chat
+
+Embeddable Agent chat SDK for the browser. Configure with a **DSN**, drop a
+chat widget into any web page, and let your end users talk to your agent
+backend.
+
+- 🪶 **Tiny core** — the SDK weighs only a few KB once `react`, `antd`, and
+  `@ant-design/x` are externalized.
+- 🔌 **Two integrations** — vanilla JS (`AgentChat.init({...})`) and React
+  (`<AgentChat />` from `omnix-chat/react`, or `<AgentChatProvider>` +
+  `useAgentChat()` for custom layouts).
+- 🎨 **Ant Design X UI** — the chat surface is built on
+  [@ant-design/x](https://x.ant.design/) (Bubble, Sender, Welcome) with full
+  antd theming (`light`/`dark`/`auto` + token overrides).
+- 🛡 **Style isolation** — rendered inside a Shadow DOM with antd's
+  `StyleProvider` redirected to the shadow root, so the host page's CSS is
+  never touched.
+
+> **Status:** v0.1 public beta. The public API surface is stable but the
+> backend HTTP contract is still being refined.
+
+## Quick start
+
+### CDN drop-in (`<script>` tag)
+
+```html
+<!-- Peer dependencies (load order matters) -->
+<script crossorigin src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
+<script crossorigin src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
+<script crossorigin src="https://unpkg.com/dayjs@1/dayjs.min.js"></script>
+<script crossorigin src="https://unpkg.com/@ant-design/cssinjs/dist/cssinjs.min.js"></script>
+<script crossorigin src="https://unpkg.com/@ant-design/icons/dist/index.umd.min.js"></script>
+<script crossorigin src="https://unpkg.com/antd@5/dist/antd.min.js"></script>
+<script crossorigin src="https://unpkg.com/@ant-design/x@1/dist/index.min.js"></script>
+
+<!-- The SDK -->
+<script src="https://unpkg.com/omnix-chat@latest/dist/omnix-chat.umd.js"></script>
+<script>
+  AgentChat.init({
+    dsn: 'https://YOUR_PUBLIC_KEY@api.example.com/YOUR_PROJECT_ID',
+    locale: 'zh-CN',
+    theme: 'auto',
+  });
+</script>
+```
+
+### npm + vanilla JavaScript
+
+```bash
+pnpm add omnix-chat react react-dom antd @ant-design/x @ant-design/cssinjs @ant-design/icons dayjs
+```
+
+```ts
+import { AgentChat } from 'omnix-chat';
+
+AgentChat.init({
+  dsn: 'https://YOUR_PUBLIC_KEY@api.example.com/YOUR_PROJECT_ID',
+  user: { id: 'u-123', email: 'alice@example.com' },
+  locale: 'zh-CN',
+  theme: 'auto',
+});
+```
+
+### React (recommended)
+
+```tsx
+import { AgentChat } from 'omnix-chat/react';
+
+export function App() {
+  return (
+    <AgentChat
+      dsn="your-app-dsn"
+      baseUrl="https://api.example.com"
+      accountToken="optional-host-token"
+      project={{ name: 'My Assistant', logo: '/logo.png' }}
+      locale="zh-CN"
+    />
+  );
+}
+```
+
+### React (custom launcher with Provider)
+
+```tsx
+import { AgentChatProvider, AgentChatEmbedded, useAgentChat } from 'omnix-chat/react';
+
+export function App() {
+  return (
+    <AgentChatProvider dsn="your-app-dsn" baseUrl="https://api.example.com">
+      <YourApp />
+      <ChatShell />
+    </AgentChatProvider>
+  );
+}
+
+function ChatShell() {
+  const { instance, isOpen, open, close } = useAgentChat();
+  return (
+    <>
+      <button type="button" onClick={isOpen ? close : open}>
+        {isOpen ? 'Hide chat' : 'Need help?'}
+      </button>
+      <AgentChatEmbedded client={instance} />
+    </>
+  );
+}
+```
+
+## DSN format
+
+A DSN is a URL-shaped string that encodes everything the SDK needs to talk to
+your backend:
+
+```
+https://<publicKey>@<host>[:<port>][/<basePath>]/<projectId>
+```
+
+- `publicKey` — the project's **public** key. Visible on the client; never
+  use it to sign sensitive operations.
+- `host`/`port`/`basePath` — origin and base path of your agent API. The SDK
+  computes `apiBase = ${host}:${port}${basePath}/v1`.
+- `projectId` — string or numeric project identifier.
+
+Examples:
+
+```
+https://pk_live_abc@api.example.com/42
+https://pk_test@example.com:8443/api/edge/proj-7
+agent://pk_x@api.example.com/9       # alias, normalized to https://
+```
+
+Parsing / normalization:
+
+```ts
+import { normalizeDsn, DEFAULT_BASE_URL } from 'omnix-chat';
+
+const dsn = normalizeDsn('your-app-dsn');
+await AgentChat.init({ dsn, baseUrl: DEFAULT_BASE_URL });
+```
+
+## Configuration reference
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `dsn` | `string` | — | **Required.** See [DSN format](#dsn-format). |
+| `user` | `UserContext` | — | End-user identity. Forwarded to the backend at handshake time. |
+| `locale` | `string` | `navigator.language` | BCP-47 locale (`en`, `zh-CN`, …). Drives both SDK and antd copy. |
+| `theme` | `'light' \| 'dark' \| 'auto'` | `'auto'` | Visual theme. `auto` follows `prefers-color-scheme`. |
+| `themeToken` | `Record<string, unknown>` | — | antd theme token overrides (e.g. `{ colorPrimary: '#7c3aed' }`). |
+| `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | `'bottom-right'` | Where the floating launcher anchors. |
+| `container` | `HTMLElement \| string` | `document.body` | Where the Shadow DOM host is appended. |
+| `autoOpen` | `boolean` | `false` | Open the panel as soon as the widget mounts. |
+| `debug` | `boolean` | `false` | Verbose console logs and unhandled-error warnings. |
+| `headers` | `Record<string, string>` | — | Extra HTTP headers added to every backend call. |
+| `onReady` | `() => void` | — | Convenience alias for `instance.on('ready', ...)`. |
+
+## Events
+
+```ts
+const off = AgentChat.on('message', ({ message, source }) => {
+  console.log(source, message.content.text);
+});
+off(); // unsubscribe
+```
+
+| Event | Payload | Notes |
+| --- | --- | --- |
+| `ready` | `void` | Fired after `init()` settles. |
+| `error` | `{ code, message, cause? }` | Any SDK-level error. Subscribe in production to forward into Sentry/Datadog. |
+| `open` / `close` | `void` | The chat panel opened/closed. |
+| `session` | `{ sessionId, conversationId }` | Active chat session changed. |
+| `sessions` | `{ sessions: ChatSessionSummary[] }` | Sidebar session list refreshed (`GET /chat`). |
+| `message` | `{ message, source }` | A user, agent, or system message hit the timeline (agent may stream incrementally). |
+| `destroyed` | `void` | The instance was torn down. |
+
+## Lifecycle
+
+```ts
+AgentChat.init({ dsn });
+AgentChat.open();
+AgentChat.identify({ id: 'u-99' });
+// Resolves with the **user** message once POST succeeds.
+// Assistant replies arrive via `message` events (SSE stream per sessionId).
+const userMsg = await AgentChat.sendMessage('Hello!');
+
+AgentChat.selectSession('existing-session-id'); // switch sidebar session
+
+AgentChat.destroy();    // clean up DOM, abort in-flight requests
+AgentChat.init({ dsn }); // safe to re-init after destroy
+```
+
+For multi-tenant pages use `createAgentChat()` to obtain independent instances.
+
+### React Strict Mode
+
+If you call the imperative `AgentChat.init()` from inside a React `useEffect`
+under `<StrictMode>`, dev-mode will run `setup → cleanup → setup`, which
+otherwise causes the launcher to flash on screen. Prefer `<AgentChat dsn="..." />`
+from `omnix-chat/react`, which handles init/teardown for you. If you still call
+the imperative API from an effect, guard with a deferred destroy:
+
+```tsx
+const ref = useRef<{ key: string | null; timer: number | null }>({ key: null, timer: null });
+
+useEffect(() => {
+  if (ref.current.timer != null) {
+    clearTimeout(ref.current.timer);
+    ref.current.timer = null;
+  }
+  if (ref.current.key !== dsn) {
+    if (ref.current.key) AgentChat.destroy();
+    AgentChat.init({ dsn });
+    ref.current.key = dsn;
+  }
+  return () => {
+    ref.current.timer = window.setTimeout(() => {
+      AgentChat.destroy();
+      ref.current.key = null;
+      ref.current.timer = null;
+    }, 0);
+  };
+}, [dsn]);
+```
+
+## Multi-session chat & streaming
+
+The widget shows a **left sidebar** of conversations (`GET /chat`). Selecting one
+loads `GET /chat/{sessionId}` into the message pane.
+
+### `sendMessage()` pipeline (SDK)
+
+```text
+User hits Send
+  → optimistic user bubble (pending) + notifyStateChange     ← UI shows immediately
+  → ensure sessionId
+  → GET /chat/{sessionId}/stream (SSE connected)
+  → POST user message (existing session only)
+  → SSE events → agent bubble updates + notifyStateChange    ← UI streams assistant
+```
+
+**Existing session** (has `activeSessionId`):
+
+| Order | HTTP | Purpose |
+| --- | --- | --- |
+| 1 | `GET /chat/{sessionId}/stream` | Listen before agent runs |
+| 2 | `POST /chat/{sessionId}/messages` | `{ role: "user", content }` triggers agent |
+| 3 | same SSE | `think` / `result` / `complete` / `error` |
+
+**First message** (no session yet):
+
+| Order | HTTP | Purpose |
+| --- | --- | --- |
+| 1 | `POST /chat` | `{ role, content }` → `{ sessionId }` + starts agent (backend contract) |
+| 2 | `GET /chat/{sessionId}/stream` | Subscribe (ReplaySubject replays recent events) |
+| — | skip `POST .../messages` | User text already persisted in step 1 |
+
+**Other APIs**
+
+| Step | HTTP | Notes |
+| --- | --- | --- |
+| List sessions | `GET /chat` | Sidebar |
+| Load session | `GET /chat/{sessionId}` | `selectSession()` / `prefetch()` |
+
+SSE → UI mapping lives in `src/core/chat-sse.ts`. React reads `getState().messages`
+via `useClientState` in `ChatBody` (`useSyncExternalStore` + `notifyStateChange`).
+
+`sendMessage()` resolves when the user bubble is `sent` or `failed`. Assistant
+content streams through repeated `message` events and state updates.
+
+## Backend HTTP contract (legacy v1 sketch)
+
+The SDK historically documented two endpoints:
+
+### `POST {apiBase}/sessions`
+
+Headers: `X-Agent-Public-Key`, `X-Agent-Project-Id`, `X-Agent-Sdk-Version`,
+`Content-Type: application/json`.
+
+Body:
+
+```json
+{
+  "locale": "zh-CN",
+  "sdkVersion": "0.1.0",
+  "origin": "https://app.example.com",
+  "user": { "id": "u-123", "email": "a@b.c" },
+  "existingConversationId": "conv_abc"
+}
+```
+
+Response (200):
+
+```json
+{
+  "sessionId": "sess_...",
+  "sessionToken": "tok_...",
+  "expiresAt": 1731567890000,
+  "conversation": { "id": "conv_...", "messages": [] }
+}
+```
+
+### `POST {apiBase}/messages`
+
+Headers: `Authorization: Bearer <sessionToken>`, plus the same
+`X-Agent-*` headers.
+
+Body:
+
+```json
+{
+  "conversationId": "conv_abc",
+  "content": { "type": "text", "text": "Hello!" }
+}
+```
+
+Response (200):
+
+```json
+{
+  "message": {
+    "id": "msg_...",
+    "role": "agent",
+    "content": { "type": "text", "text": "Hi there!" },
+    "createdAt": 1731567890000,
+    "status": "sent"
+  }
+}
+```
+
+Errors should follow the shape `{ "error": { "code": "STRING_CODE", "message": "Human readable" } }`
+so the SDK can surface them as typed `AgentChatError` instances.
+
+## Security
+
+- The DSN's `publicKey` is **public**. Any rate-limiting or origin allow-list
+  must be enforced **server-side** (the SDK forwards `Origin` in the handshake
+  body so you can check it).
+- For trusted user identification pass an HMAC of the user id as
+  `user.signature` (validate it on the backend with a shared secret).
+- The SDK never executes `eval` or `new Function` and never injects styles
+  outside its Shadow DOM, so it works under strict CSP modulo
+  `style-src 'unsafe-inline'` (required by antd's css-in-js).
+
+## Local development
+
+```bash
+pnpm install
+pnpm dev          # runs the demo playground at http://localhost:5173
+pnpm build        # produces dist/omnix-chat.es.js + .umd.js + react.es.js + .umd.js + types
+pnpm typecheck
+pnpm size         # asserts gzipped budgets
+```
+
+The playground intercepts `/api/edge/*/v1/sessions` and
+`/api/edge/*/v1/messages` via a built-in Vite middleware, so you can develop
+without a real backend.
+
+## License
+
+MIT