teko-chat-sdk 1.0.0

package/README.md

@@ -0,0 +1,462 @@
+# TekoChatSDK
+
+React component library giúp các ECOM app của Teko tích hợp AI chatbot với khả năng **bidirectional communication** — right panel có thể push context ngược lại cho AI.
+
+## Tính năng
+
+- **3 UI states**: `bubble` → `mini` popup → `fullscreen` split layout (35/65)
+- **Mobile mode**: `layoutMode="mobile"` — mini popup chuyển thành bottom sheet full-width; fullscreen chuyển thành single-column với floating toggle icon + right panel bottom sheet overlay
+- **Streaming responses**: AI response xuất hiện dần theo chunks (typewriter effect)
+- **Pluggable transport**: Auto-detect giao thức từ `chatBffUrl` scheme — WebSocket (`wss://`), HTTP Streaming (`https://`), hoặc mock built-in (không có URL)
+- **Bidirectional context**: Right-side app UI push context ngược về AI qua `ref.sendContext()`
+- **Intent-driven UI**: BFF trả về intent → SDK tự điều phối giao diện
+- **Quick reply**: Suggest options từ BFF hiển thị dưới dạng clickable buttons
+- **Mock handler**: Không cần backend thật, truyền `chatBffUrl=""` để dùng mock built-in với streaming giả lập
+- **Debug panel**: `onDebugEvent` callback theo dõi toàn bộ request/response/intent/context
+- **Customizable bubble**: Truyền `renderBubble` để dùng UI bubble tùy chỉnh
+
+## Cài đặt
+
+```bash
+yarn add teko-chat-sdk
+# hoặc
+npm install teko-chat-sdk
+```
+
+**Peer dependencies:**
+
+```bash
+yarn add react react-dom
+```
+
+## Quick Start
+
+```tsx
+import { useRef } from 'react';
+import { TekoChatWidget } from 'teko-chat-sdk';
+import type { TekoChatWidgetRef } from 'teko-chat-sdk';
+
+export default function App() {
+  const chatRef = useRef<TekoChatWidgetRef>(null);
+
+  return (
+    <>
+      <YourApp />
+
+      <TekoChatWidget
+        ref={chatRef}
+        appId="your-app-id"
+        chatBffUrl="https://your-bff.example.com/chat"
+        onIntent={(action, componentKey) => {
+          if (action === 'show_ui' && componentKey) {
+            chatRef.current?.openFullscreen(componentKey);
+          }
+        }}
+        renderRightPanel={(componentKey) => {
+          if (componentKey === 'cart') return <CartPage />;
+          return null;
+        }}
+      />
+    </>
+  );
+}
+```
+
+## API
+
+### `<TekoChatWidget>` Props
+
+**Core**
+
+| Prop         | Type     | Required | Mô tả                                                                     |
+| ------------ | -------- | -------- | ------------------------------------------------------------------------- |
+| `appId`      | `string` | ✅        | App identifier, gửi lên BFF để phân biệt context                          |
+| `chatBffUrl` | `string` | ✅        | BFF endpoint. `wss://` → WebSocket, `https://` → HTTP stream, `""` → mock |
+
+**Business logic**
+
+| Prop               | Type                                              | Mô tả                                                                   |
+| ------------------ | ------------------------------------------------- | ----------------------------------------------------------------------- |
+| `onIntent`         | `(action: string, componentKey?: string) => void` | Callback khi BFF trả về intent action                                   |
+| `renderRightPanel` | `(componentKey: string) => ReactNode`             | Render content cho right panel ở fullscreen state                       |
+| `getAppContext`    | `() => Record<string, unknown> \| Promise<...>`   | Inject app metadata vào mỗi BFF request, gọi tại send-time (luôn fresh) |
+
+**UI customization**
+
+| Prop           | Type                                                           | Default          | Mô tả                                                                        |
+| -------------- | -------------------------------------------------------------- | ---------------- | ---------------------------------------------------------------------------- |
+| `renderBubble` | `(onClick: () => void) => ReactNode`                           | —                | Custom bubble UI, thay thế bubble mặc định                                   |
+| `bubbleAnchor` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | `'bottom-right'` | Vị trí bubble, ảnh hưởng hướng animation fullscreen                          |
+| `layoutMode`   | `'desktop' \| 'mobile'`                                        | `'desktop'`      | Desktop: mini popup + split fullscreen. Mobile: bottom sheet + single column |
+| `primaryColor` | `string`                                                       | `'#1a73e8'`      | Primary color (hex) cho toàn bộ widget                                       |
+| `botAvatar`    | `string`                                                       | —                | Avatar URL cho AI bubble                                                     |
+| `locale`       | `'vi' \| 'en'`                                                 | `'vi'`           | Ngôn ngữ hiển thị                                                            |
+| `labels`       | `Partial<ChatLabels>`                                          | —                | Override từng label cụ thể, kết hợp được với `locale`                        |
+
+**Layout / spacing**
+
+| Prop           | Type     | Default | Mô tả                                              |
+| -------------- | -------- | ------- | -------------------------------------------------- |
+| `offsetTop`    | `number` | `0`     | Offset từ top (px) — tránh che fixed header        |
+| `offsetBottom` | `number` | `0`     | Offset từ bottom (px) — tránh che fixed bottom nav |
+| `miniWidth`    | `number` | `360`   | Chiều rộng mini popup (px)                         |
+| `miniHeight`   | `number` | `480`   | Chiều cao mini popup (px)                          |
+| `zIndex`       | `number` | `1031`  | CSS z-index. Fullscreen backdrop = zIndex + 9      |
+
+**Dev only**
+
+| Prop           | Type                          | Mô tả                       |
+| -------------- | ----------------------------- | --------------------------- |
+| `onDebugEvent` | `(event: DebugEvent) => void` | Nhận mọi SDK event để debug |
+
+### `TekoChatWidgetRef` Methods
+
+Truy cập qua `ref.current`:
+
+| Method            | Signature                                                   | Mô tả                                                                                                   |
+| ----------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `open`            | `() => void`                                                | Mở mini popup                                                                                           |
+| `close`           | `() => void`                                                | Đóng chat, về bubble state                                                                              |
+| `openFullscreen`  | `(componentKey: string) => void`                            | Mở fullscreen split với component key                                                                   |
+| `closeFullscreen` | `() => void`                                                | Thu nhỏ về mini popup                                                                                   |
+| `sendMessage`     | `(text: string, context?: Record<string, unknown>) => void` | Gửi message lên BFF programmatically; `context` được forward kèm request (dùng cho quick reply payload) |
+| `sendContext`     | `(data: Record<string, unknown>) => void`                   | Push context từ right panel ngược về AI                                                                 |
+
+## Customization
+
+```tsx
+<TekoChatWidget
+  appId="your-app-id"
+  chatBffUrl="https://your-bff.example.com/chat"
+  primaryColor="#e53e3e"   // thay màu chủ đạo
+  zIndex={2000}            // tăng z-index nếu app có overlay khác
+  offsetTop={64}           // chừa 64px cho fixed header
+  offsetBottom={56}        // chừa 56px cho bottom navigation bar
+  miniWidth={400}
+  miniHeight={520}
+/>
+```
+
+## Mobile Mode
+
+SDK không tự detect viewport — consumer app tự detect và truyền `layoutMode` vào:
+
+```tsx
+function App() {
+  const [layoutMode, setLayoutMode] = useState<'desktop' | 'mobile'>(
+    () => (window.innerWidth < 768 ? 'mobile' : 'desktop'),
+  );
+
+  useEffect(() => {
+    const handler = () =>
+      setLayoutMode(window.innerWidth < 768 ? 'mobile' : 'desktop');
+    window.addEventListener('resize', handler);
+    return () => window.removeEventListener('resize', handler);
+  }, []);
+
+  return (
+    <TekoChatWidget
+      layoutMode={layoutMode}
+      renderRightPanel={(key) =>
+        layoutMode === 'mobile' ? <MobileCartPage /> : <DesktopCartPage />
+      }
+      // ...
+    />
+  );
+}
+```
+
+**Mobile behavior:**
+- `mini` state: full-width bottom sheet slide up từ đáy (thay vì popup 360px); click vùng tối bên ngoài để đóng
+- `fullscreen` state: chat luôn hiển thị full-screen; khi BFF trigger `show_ui`, right panel slide up dạng bottom sheet overlay phía trên chat; click vùng tối để đóng overlay về chat; tap floating toggle icon để mở lại right panel
+
+## Bidirectional Communication
+
+Điểm khác biệt chính của SDK: right panel có thể push context ngược về AI để cải thiện intent detection.
+
+```tsx
+// App.tsx
+<TekoChatWidget
+  ref={chatRef}
+  renderRightPanel={(componentKey) => (
+    <CartPage
+      onContextUpdate={(data) => chatRef.current?.sendContext(data)}
+    />
+  )}
+/>
+
+// CartPage.tsx
+function CartPage({ onContextUpdate }) {
+  const handleQtyChange = (qty: number) => {
+    updateCart(qty);
+    onContextUpdate({
+      type: 'cart_updated',
+      items: cartItems,
+      totalAmount: calculateTotal(),
+    });
+  };
+}
+```
+
+## BFF Protocol
+
+SDK tự chọn giao thức dựa vào scheme của `chatBffUrl`:
+
+| `chatBffUrl`                    | Giao thức      | Ghi chú                                                               |
+| ------------------------------- | -------------- | --------------------------------------------------------------------- |
+| `wss://...` hoặc `ws://...`     | WebSocket      | Persistent connection, BFF push `TransportFrame` JSON qua `ws.send()` |
+| `https://...` hoặc `http://...` | HTTP Streaming | POST request, BFF trả newline-delimited JSON (`application/x-ndjson`) |
+| `""` hoặc không truyền          | Mock handler   | Built-in, không cần backend — simulate streaming word-by-word         |
+
+### TransportFrame (BFF → SDK streaming format)
+
+BFF cần gửi các frames theo format sau (mỗi frame là một JSON object):
+
+```typescript
+type TransportFrame =
+  | { type: 'chunk'; text: string }        // một đoạn text AI đang generate
+  | { type: 'done'; data: BFFResponseData } // kết thúc, kèm full response data
+  | { type: 'error'; message: string }      // lỗi
+```
+
+**WebSocket:** Mỗi `ws.send()` là một frame JSON.
+
+**HTTP Streaming:** Mỗi dòng (`\n`-delimited) là một frame JSON.
+
+---
+
+## BFF JSON Contract
+
+### BFF → SDK (Response)
+
+```json
+{
+  "code": 200,
+  "message": "ok",
+  "data": {
+    "conversationId": "conv-abc123",
+    "message": "Bạn muốn thêm loại nào?",
+    "intent": "addToCart",
+    "action": "show_ui",
+    "componentKey": "cart",
+    "suggest": {
+      "options": [
+        { "key": "suon-non", "label": "Sườn non", "payload": { "sku": "SN-001" } },
+        { "key": "ga-dong-tao", "label": "Gà đông tảo", "payload": { "sku": "GA-001" } }
+      ]
+    },
+    "timestamp": 1742208605000
+  }
+}
+```
+
+**`action` values SDK xử lý:**
+- `show_ui` — SDK gọi `renderRightPanel(componentKey)` và chuyển sang fullscreen
+- Các value khác — SDK forward sang `onIntent` callback để app tự xử lý
+
+### SDK → BFF (Request)
+
+```json
+// Nhắn tin thường
+{ "conversationId": "conv-abc123", "message": "tôi muốn mua gà", "timestamp": 1742208600000 }
+
+// Click quick reply (có context từ option payload)
+{ "conversationId": "conv-abc123", "message": "Sườn non", "context": { "sku": "SN-001" }, "timestamp": 1742208600000 }
+
+// Push context từ right panel (không có message)
+{ "conversationId": "conv-abc123", "context": { "type": "cart_updated", "items": [...] }, "timestamp": 1742208600000 }
+
+// Với getAppContext (appContext được inject vào mọi request nếu có giá trị)
+{ "conversationId": "conv-abc123", "message": "tôi muốn mua gà", "appContext": { "terminalId": "T001", "terminalCode": "freshmart-hanoi" }, "timestamp": 1742208600000 }
+```
+
+## Release
+
+Quy trình release lên NPM qua `release-it` + GitLab CI.
+
+### Setup Gitlab project
+
+Vào **Settings > CI/CD > Variables**, thêm:
+
+| Variable    | Value              | Protected | Masked |
+| ----------- | ------------------ | --------- | ------ |
+| `NPM_TOKEN` | token từ npmjs.org | x         | x      |
+
+### Quy trình release
+
+```bash
+# 1. Merge tất cả feature branches vào main, đảm bảo pass CI
+
+# 2. Run các command local
+yarn install
+yarn release
+```
+
+`yarn release` sẽ:
+
+1. Phân tích commit history (Conventional Commits) để gợi ý version bump
+2. Cập nhật `version` trong `package.json`
+3. Tạo entry mới trong `CHANGELOG.md`
+4. Tạo commit `chore(release): vX.Y.Z`
+5. Tạo git tag `vX.Y.Z`
+6. Push commit + tag lên GitLab
+
+GitLab CI detect tag `v*.*.*` → tự động chạy job `publish:npm`:
+
+```
+yarn lint → yarn build → npm publish --access public
+```
+
+### Version bump theo Conventional Commits
+
+| Commit prefix               | Version bump  |
+| --------------------------- | ------------- |
+| `fix:`, `perf:`             | patch (0.0.x) |
+| `feat:`                     | minor (0.x.0) |
+| `BREAKING CHANGE` in footer | major (x.0.0) |
+
+### Pre-release (alpha / beta / rc)
+
+```bash
+yarn release --preRelease=alpha   # → v1.0.0-alpha.1, npm tag: alpha
+yarn release --preRelease=beta    # → v1.0.0-beta.1,  npm tag: beta
+yarn release --preRelease=rc      # → v1.0.0-rc.1,    npm tag: rc
+```
+
+Consumer cài pre-release bằng cách chỉ định dist-tag:
+
+```bash
+npm install teko-chat-sdk@beta
+npm install teko-chat-sdk@alpha
+```
+
+Package `latest` (stable) không bị ảnh hưởng bởi các lần publish pre-release.
+
+### Manual version override
+
+```bash
+yarn release --release-version 1.0.0    # chỉ định version cụ thể
+yarn release minor                      # ép bump minor
+yarn release patch --dry-run            # preview không commit thật
+```
+
+### Checklist trước khi release
+
+- [ ] `main` branch CI pass
+- [ ] `yarn lint` và `yarn build` pass local
+- [ ] Working directory sạch (không có uncommitted changes)
+- [ ] `NPM_TOKEN` CI variable đã được set trong GitLab project
+
+---
+
+## Development
+
+```bash
+# Clone repo
+git clone <repo-url>
+cd teko-chat-sdk
+
+# Cài dependencies
+yarn install
+
+# Chạy demo app (localhost:5173)
+yarn dev
+
+# Build SDK
+yarn build
+
+# Lint
+yarn lint
+```
+
+### Storybook
+
+```bash
+# Dev server — localhost:6006
+yarn storybook
+
+# Build static output
+yarn build-storybook
+```
+
+**Stories có sẵn:**
+
+| Story                | Mô tả                                                                                             |
+| -------------------- | ------------------------------------------------------------------------------------------------- |
+| `SDK/TekoChatWidget` | Full integration — BubbleState, WithCustomColor, WithOffsets, MiniPopup, MobileMode               |
+| `SDK/ChatBubble`     | Default, CustomColor, GreenColor, WithOffset                                                      |
+| `SDK/ChatMiniPopup`  | Empty, WithMessages, WithLoading, CustomColor, CustomSize, MobileBottomSheet                      |
+| `SDK/ChatFullscreen` | SplitLayout, WithoutRightPanel, CustomColor, WithHeaderOffset, MobileLayout, MobileLayoutChatView |
+| `SDK/DataFlow`       | DataFlowInspector — inline event log dùng `onDebugEvent`                                          |
+| `SDK/MessageBubble`  | UserMessage, AIMessage, AIMessageWithOptions, CustomColor                                         |
+
+### Cấu trúc
+
+```
+teko-chat-sdk/
+├── src/
+│   ├── locales/
+│   │   └── index.ts            # ChatLabels interface, BUILT_IN_LABELS (vi/en), resolveLabels()
+│   ├── components/
+│   │   ├── TekoChatWidget.tsx   # Root component, state machine
+│   │   ├── ChatBubble.tsx       # State 1: floating button
+│   │   ├── ChatMiniPopup.tsx    # State 2: mini popup
+│   │   ├── ChatFullscreen.tsx   # State 3: fullscreen split layout
+│   │   ├── MessageList.tsx
+│   │   ├── MessageBubble.tsx    # Message + quick reply options
+│   │   └── MessageInput.tsx
+│   ├── hooks/
+│   │   └── useChatSession.ts   # Session management, orchestrates transport
+│   ├── transports/
+│   │   ├── ITransport.ts       # ITransport interface + TransportFrame type
+│   │   ├── WebSocketTransport.ts   # wss:// — persistent WS, auto-retry
+│   │   ├── HttpStreamTransport.ts  # https:// — fetch ndjson streaming
+│   │   ├── MockTransport.ts    # dev fallback — wraps mockHandler, simulates chunks
+│   │   └── createTransport.ts  # factory: auto-detect từ bffUrl scheme
+│   ├── utils/
+│   │   ├── mockHandler.ts      # Mock BFF logic (dùng bởi MockTransport)
+│   │   └── chatTheme.ts        # ChatThemeContext, useChatTheme, hexToRgba
+│   ├── stories/                # Storybook stories
+│   │   ├── TekoChatWidget.stories.tsx
+│   │   ├── ChatBubble.stories.tsx
+│   │   ├── ChatMiniPopup.stories.tsx
+│   │   ├── ChatFullscreen.stories.tsx
+│   │   ├── DataFlow.stories.tsx
+│   │   └── MessageBubble.stories.tsx
+│   ├── types.ts                # Full type definitions
+│   └── index.ts                # Public exports
+├── .storybook/                 # Storybook config
+│   ├── main.ts
+│   └── preview.ts
+└── demo/                       # Demo app (FreshMart ECOM)
+```
+
+## Architecture
+
+```
+ECOM App
+ │
+ └── <TekoChatWidget ref={chatRef} chatBffUrl="..." onIntent={...} renderRightPanel={...} />
+      │
+      │  createTransport(chatBffUrl) — auto-detect từ scheme:
+      │    wss://   → WebSocketTransport  (persistent, streaming chunks)
+      │    https:// → HttpStreamTransport (fetch ndjson)
+      │    ""       → MockTransport       (dev, simulate streaming)
+      ▼
+     BFF → LLM Core → Business Services
+          (push TransportFrame chunks: {type:'chunk'} → {type:'done'})
+```
+
+**UI States:**
+
+```
+bubble ──click──► mini ──intent: show_ui──► fullscreen (split 35/65)
+  ▲                │                              │
+  └──────close─────┘◄─────────close───────────────┘
+```
+
+## Scope POC
+
+**In scope:** 3 UI states, pluggable transport (WS/HTTP streaming/mock), streaming responses, demo app, bidirectional communication, quick reply, mobile mode layout
+
+**Out of scope:** BFF thật, authentication, message persistence