teko-chat-sdk 1.0.1 → 1.1.0

package/README.md

@@ -7,7 +7,7 @@ React component library giúp các ECOM app của Teko tích hợp AI chatbot v
 - **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)
+- **Pluggable transport**: Truyền `transportMode` tường minh (`'websocket'` / `'stream'` / `'rest'`) — mock built-in khi `chatBffUrl` rỗng
 - **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
@@ -68,10 +68,11 @@ export default function App() {
 
 **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 |
+| Prop            | Type                                | Required | Mô tả                                                    |
+| --------------- | ----------------------------------- | -------- | -------------------------------------------------------- |
+| `appId`         | `string`                            | ✅        | App identifier, gửi lên BFF để phân biệt context         |
+| `chatBffUrl`    | `string`                            | ✅        | BFF endpoint. Để `""` → SDK dùng mock handler (dev only) |
+| `transportMode` | `'websocket' \| 'stream' \| 'rest'` | ✅        | Giao thức giao tiếp với BFF. Bắt buộc truyền tường minh. |
 
 **Business logic**
 
@@ -200,13 +201,15 @@ function CartPage({ onContextUpdate }) {
 
 ## BFF Protocol
 
-SDK tự chọn giao thức dựa vào scheme của `chatBffUrl`:
+App consumer truyền `transportMode` tường minh để chọn giao thức:
 
-| `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         |
+| `transportMode` | Giao thức      | Ghi chú                                                               |
+| --------------- | -------------- | --------------------------------------------------------------------- |
+| `'websocket'`   | WebSocket      | Persistent connection, BFF push `TransportFrame` JSON qua `ws.send()` |
+| `'stream'`      | HTTP Streaming | POST request, BFF trả newline-delimited JSON (`application/x-ndjson`) |
+| `'rest'`        | REST JSON      | POST request, BFF trả JSON một lần (không stream)                     |
+
+**Mock handler:** Khi `chatBffUrl=""` hoặc không truyền, SDK tự dùng mock handler tích hợp (bất kể `transportMode`). Không cần backend — simulate streaming word-by-word.
 
 ### TransportFrame (BFF → SDK streaming format)
 
@@ -412,7 +415,7 @@ teko-chat-sdk/
 │   │   ├── 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
+│   │   └── createTransport.ts  # factory: chọn transport theo transportMode
 │   ├── utils/
 │   │   ├── mockHandler.ts      # Mock BFF logic (dùng bởi MockTransport)
 │   │   └── chatTheme.ts        # ChatThemeContext, useChatTheme, hexToRgba
@@ -436,12 +439,13 @@ teko-chat-sdk/
 ```
 ECOM App
  │
- └── <TekoChatWidget ref={chatRef} chatBffUrl="..." onIntent={...} renderRightPanel={...} />
+ └── <TekoChatWidget ref={chatRef} chatBffUrl="..." transportMode="stream" onIntent={...} renderRightPanel={...} />
       │
-      │  createTransport(chatBffUrl) — auto-detect từ scheme:
-      │    wss://   → WebSocketTransport  (persistent, streaming chunks)
-      │    https:// → HttpStreamTransport (fetch ndjson)
-      │    ""       → MockTransport       (dev, simulate streaming)
+      │  createTransport(chatBffUrl, transportMode):
+      │    transportMode='websocket' → WebSocketTransport  (persistent, streaming chunks)
+      │    transportMode='stream'    → HttpStreamTransport (fetch ndjson)
+      │    transportMode='rest'      → RestTransport       (plain JSON, no stream)
+      │    chatBffUrl=""             → MockTransport       (dev, simulate streaming)
       ▼
      BFF → LLM Core → Business Services
           (push TransportFrame chunks: {type:'chunk'} → {type:'done'})

package/dist/index.cjs

@@ -1320,6 +1320,105 @@ var MockTransport = class {
   }
 };
 
+// src/transports/RestTransport.ts
+var TOOL_INTENT_MAP = {
+  INTENT_VIEW_CART: {
+    action: "show_ui",
+    componentKey: "cart",
+    intent: "viewCart"
+  },
+  INTENT_VIEW_ORDER: {
+    action: "show_ui",
+    componentKey: "order",
+    intent: "viewOrder"
+  }
+};
+var RestTransport = class {
+  // POC default: gpt-4.1-mini — override bằng cách truyền model vào constructor nếu cần
+  constructor(url, token, model = "gpt-4.1-mini") {
+    this.url = url;
+    this.token = token;
+    this.model = model;
+  }
+  onChunk() {
+  }
+  onDone(cb) {
+    this.doneCb = cb;
+  }
+  onError(cb) {
+    this.errorCb = cb;
+  }
+  connect() {
+    return Promise.resolve();
+  }
+  disconnect() {
+  }
+  async send(request) {
+    try {
+      const ctx = request.appContext ?? {};
+      const metadata = {
+        session_id: request.conversationId,
+        ...this.token && { authorization: this.token },
+        ...ctx
+      };
+      const body = {
+        model: this.model,
+        user: request.userId ?? "user",
+        messages: [{ role: "user", content: request.message ?? "" }],
+        metadata
+      };
+      const res = await fetch(this.url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Accept: "application/json"
+        },
+        body: JSON.stringify(body)
+      });
+      if (!res.ok) {
+        throw new Error(`[RestTransport] HTTP ${res.status}`);
+      }
+      const json = await res.json();
+      const choice = json.choices?.[0];
+      const content = choice?.message?.content ?? "";
+      const toolCall = choice?.message?.tool_calls?.[0];
+      let result;
+      if (toolCall?.type === "function") {
+        const mapped = TOOL_INTENT_MAP[toolCall.function.name] ?? {
+          action: "show_ui",
+          componentKey: toolCall.function.name.toLowerCase(),
+          intent: toolCall.function.name
+        };
+        let intentPayload;
+        try {
+          intentPayload = JSON.parse(toolCall.function.arguments);
+        } catch {
+        }
+        result = {
+          conversationId: request.conversationId ?? json.id ?? "",
+          message: content,
+          intent: mapped.intent,
+          action: mapped.action,
+          componentKey: mapped.componentKey,
+          intentPayload,
+          timestamp: Date.now()
+        };
+      } else {
+        result = {
+          conversationId: request.conversationId ?? json.id ?? "",
+          message: content,
+          intent: "none",
+          action: "none",
+          timestamp: Date.now()
+        };
+      }
+      this.doneCb?.(result);
+    } catch (err) {
+      this.errorCb?.(err);
+    }
+  }
+};
+
 // src/transports/WebSocketTransport.ts
 var MAX_RETRIES = 3;
 var BASE_RETRY_DELAY_MS = 1e3;
@@ -1392,11 +1491,14 @@ var WebSocketTransport = class {
 };
 
 // src/transports/createTransport.ts
-function createTransport(bffUrl, conversationId, token) {
+function createTransport(bffUrl, conversationId, token, transportMode) {
   if (!bffUrl) {
     return new MockTransport(conversationId);
   }
-  if (bffUrl.startsWith("wss://") || bffUrl.startsWith("ws://")) {
+  if (transportMode === "rest") {
+    return new RestTransport(bffUrl, token);
+  }
+  if (transportMode === "websocket") {
     return new WebSocketTransport(bffUrl, token);
   }
   return new HttpStreamTransport(bffUrl, token);
@@ -1419,6 +1521,7 @@ var generateId = () => Math.random().toString(36).slice(2, 10);
 var generateConversationId = () => `conv-${Date.now()}-${generateId()}`;
 var useChatSession = ({
   chatBffUrl,
+  transportMode,
   onIntent,
   onDebugEvent,
   getAppContext
@@ -1440,13 +1543,11 @@ var useChatSession = ({
       }
       setIsLoading(true);
       const { userId, token } = await getTekoAuth();
-      let appContext;
-      if (getAppContext) {
-        const resolved = await getAppContext();
-        if (Object.keys(resolved).length > 0) {
-          appContext = resolved;
-        }
-      }
+      const sdkContext = {};
+      if (token) sdkContext.authorization = token;
+      const userAppContext = getAppContext ? await getAppContext() : {};
+      const mergedContext = { ...sdkContext, ...userAppContext };
+      const appContext = Object.keys(mergedContext).length > 0 ? mergedContext : void 0;
       const req = {
         conversationId: conversationIdRef.current,
         timestamp: Date.now(),
@@ -1459,7 +1560,8 @@ var useChatSession = ({
       const transport = createTransport(
         chatBffUrl,
         conversationIdRef.current,
-        token
+        token,
+        transportMode
       );
       const streamingIdRef = { current: generateId() };
       let firstChunk = true;
@@ -1502,7 +1604,7 @@ var useChatSession = ({
             timestamp: Date.now(),
             payload: { action: data.action, componentKey }
           });
-          onIntent?.(data.action, componentKey);
+          onIntent?.(data.action, componentKey, data.intentPayload);
         }
         setMessages((prev) => {
           const last = prev[prev.length - 1];
@@ -1561,7 +1663,7 @@ var useChatSession = ({
         setIsLoading(false);
       }
     },
-    [chatBffUrl, onIntent, onDebugEvent, getAppContext]
+    [getAppContext, onDebugEvent, chatBffUrl, transportMode, onIntent]
   );
   const contextDebounceRef = (0, import_react6.useRef)(null);
   const sendMessage = (0, import_react6.useCallback)(
@@ -1635,6 +1737,7 @@ var TekoChatWidget = (0, import_react7.forwardRef)(
   ({
     appId,
     chatBffUrl,
+    transportMode,
     onIntent,
     renderRightPanel,
     renderBubble,
@@ -1674,6 +1777,7 @@ var TekoChatWidget = (0, import_react7.forwardRef)(
     const { messages, isLoading, sendMessage, sendContext } = useChatSession({
       appId,
       chatBffUrl,
+      transportMode,
       onIntent: handleIntent,
       onDebugEvent,
       getAppContext

package/dist/index.d.cts

@@ -32,6 +32,8 @@ interface BFFResponseData {
         options: SuggestOption[];
     };
     timestamp: number;
+    /** Payload từ tool_calls.arguments (parsed JSON). Populated bởi RestTransport khi BFF/LLM trả về tool_calls. */
+    intentPayload?: Record<string, unknown>;
 }
 interface BFFResponse {
     code: number;
@@ -78,14 +80,22 @@ type TransportFrame = {
 };
 interface TekoChatWidgetProps {
     appId: string;
-    /** BFF endpoint. Prefix xác định giao thức:
-     *  - wss:// hoặc ws:// → WebSocket streaming
-     *  - https:// hoặc http:// → HTTP streaming (ndjson)
-     *  - chuỗi rỗng hoặc không truyền → mock handler (dev only)
+    /**
+     * BFF endpoint.
+     * Để trống hoặc không truyền → SDK dùng mock handler (dev only).
      */
     chatBffUrl: string;
+    /**
+     * Giao thức giao tiếp với BFF. Required.
+     * - `'websocket'` : WebSocket (ws:// hoặc wss://)
+     * - `'stream'`    : HTTP ndjson streaming (http:// hoặc https://)
+     * - `'rest'`      : Plain REST JSON — POST + nhận JSON một lần, không stream
+     *
+     * Khi chatBffUrl rỗng (không truyền), SDK tự dùng mock handler (dev only).
+     */
+    transportMode: 'websocket' | 'stream' | 'rest';
     /** Callback khi BFF trả về intent action (show_ui, navigate, ...) */
-    onIntent?: (action: string, componentKey?: string) => void;
+    onIntent?: (action: string, componentKey?: string, payload?: Record<string, unknown>) => void;
     /** Render content cho right panel ở fullscreen state */
     renderRightPanel?: (componentKey: string) => ReactNode;
     /**

package/dist/index.d.ts

@@ -32,6 +32,8 @@ interface BFFResponseData {
         options: SuggestOption[];
     };
     timestamp: number;
+    /** Payload từ tool_calls.arguments (parsed JSON). Populated bởi RestTransport khi BFF/LLM trả về tool_calls. */
+    intentPayload?: Record<string, unknown>;
 }
 interface BFFResponse {
     code: number;
@@ -78,14 +80,22 @@ type TransportFrame = {
 };
 interface TekoChatWidgetProps {
     appId: string;
-    /** BFF endpoint. Prefix xác định giao thức:
-     *  - wss:// hoặc ws:// → WebSocket streaming
-     *  - https:// hoặc http:// → HTTP streaming (ndjson)
-     *  - chuỗi rỗng hoặc không truyền → mock handler (dev only)
+    /**
+     * BFF endpoint.
+     * Để trống hoặc không truyền → SDK dùng mock handler (dev only).
      */
     chatBffUrl: string;
+    /**
+     * Giao thức giao tiếp với BFF. Required.
+     * - `'websocket'` : WebSocket (ws:// hoặc wss://)
+     * - `'stream'`    : HTTP ndjson streaming (http:// hoặc https://)
+     * - `'rest'`      : Plain REST JSON — POST + nhận JSON một lần, không stream
+     *
+     * Khi chatBffUrl rỗng (không truyền), SDK tự dùng mock handler (dev only).
+     */
+    transportMode: 'websocket' | 'stream' | 'rest';
     /** Callback khi BFF trả về intent action (show_ui, navigate, ...) */
-    onIntent?: (action: string, componentKey?: string) => void;
+    onIntent?: (action: string, componentKey?: string, payload?: Record<string, unknown>) => void;
     /** Render content cho right panel ở fullscreen state */
     renderRightPanel?: (componentKey: string) => ReactNode;
     /**

package/dist/index.js

@@ -1284,6 +1284,105 @@ var MockTransport = class {
   }
 };
 
+// src/transports/RestTransport.ts
+var TOOL_INTENT_MAP = {
+  INTENT_VIEW_CART: {
+    action: "show_ui",
+    componentKey: "cart",
+    intent: "viewCart"
+  },
+  INTENT_VIEW_ORDER: {
+    action: "show_ui",
+    componentKey: "order",
+    intent: "viewOrder"
+  }
+};
+var RestTransport = class {
+  // POC default: gpt-4.1-mini — override bằng cách truyền model vào constructor nếu cần
+  constructor(url, token, model = "gpt-4.1-mini") {
+    this.url = url;
+    this.token = token;
+    this.model = model;
+  }
+  onChunk() {
+  }
+  onDone(cb) {
+    this.doneCb = cb;
+  }
+  onError(cb) {
+    this.errorCb = cb;
+  }
+  connect() {
+    return Promise.resolve();
+  }
+  disconnect() {
+  }
+  async send(request) {
+    try {
+      const ctx = request.appContext ?? {};
+      const metadata = {
+        session_id: request.conversationId,
+        ...this.token && { authorization: this.token },
+        ...ctx
+      };
+      const body = {
+        model: this.model,
+        user: request.userId ?? "user",
+        messages: [{ role: "user", content: request.message ?? "" }],
+        metadata
+      };
+      const res = await fetch(this.url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Accept: "application/json"
+        },
+        body: JSON.stringify(body)
+      });
+      if (!res.ok) {
+        throw new Error(`[RestTransport] HTTP ${res.status}`);
+      }
+      const json = await res.json();
+      const choice = json.choices?.[0];
+      const content = choice?.message?.content ?? "";
+      const toolCall = choice?.message?.tool_calls?.[0];
+      let result;
+      if (toolCall?.type === "function") {
+        const mapped = TOOL_INTENT_MAP[toolCall.function.name] ?? {
+          action: "show_ui",
+          componentKey: toolCall.function.name.toLowerCase(),
+          intent: toolCall.function.name
+        };
+        let intentPayload;
+        try {
+          intentPayload = JSON.parse(toolCall.function.arguments);
+        } catch {
+        }
+        result = {
+          conversationId: request.conversationId ?? json.id ?? "",
+          message: content,
+          intent: mapped.intent,
+          action: mapped.action,
+          componentKey: mapped.componentKey,
+          intentPayload,
+          timestamp: Date.now()
+        };
+      } else {
+        result = {
+          conversationId: request.conversationId ?? json.id ?? "",
+          message: content,
+          intent: "none",
+          action: "none",
+          timestamp: Date.now()
+        };
+      }
+      this.doneCb?.(result);
+    } catch (err) {
+      this.errorCb?.(err);
+    }
+  }
+};
+
 // src/transports/WebSocketTransport.ts
 var MAX_RETRIES = 3;
 var BASE_RETRY_DELAY_MS = 1e3;
@@ -1356,11 +1455,14 @@ var WebSocketTransport = class {
 };
 
 // src/transports/createTransport.ts
-function createTransport(bffUrl, conversationId, token) {
+function createTransport(bffUrl, conversationId, token, transportMode) {
   if (!bffUrl) {
     return new MockTransport(conversationId);
   }
-  if (bffUrl.startsWith("wss://") || bffUrl.startsWith("ws://")) {
+  if (transportMode === "rest") {
+    return new RestTransport(bffUrl, token);
+  }
+  if (transportMode === "websocket") {
     return new WebSocketTransport(bffUrl, token);
   }
   return new HttpStreamTransport(bffUrl, token);
@@ -1383,6 +1485,7 @@ var generateId = () => Math.random().toString(36).slice(2, 10);
 var generateConversationId = () => `conv-${Date.now()}-${generateId()}`;
 var useChatSession = ({
   chatBffUrl,
+  transportMode,
   onIntent,
   onDebugEvent,
   getAppContext
@@ -1404,13 +1507,11 @@ var useChatSession = ({
       }
       setIsLoading(true);
       const { userId, token } = await getTekoAuth();
-      let appContext;
-      if (getAppContext) {
-        const resolved = await getAppContext();
-        if (Object.keys(resolved).length > 0) {
-          appContext = resolved;
-        }
-      }
+      const sdkContext = {};
+      if (token) sdkContext.authorization = token;
+      const userAppContext = getAppContext ? await getAppContext() : {};
+      const mergedContext = { ...sdkContext, ...userAppContext };
+      const appContext = Object.keys(mergedContext).length > 0 ? mergedContext : void 0;
       const req = {
         conversationId: conversationIdRef.current,
         timestamp: Date.now(),
@@ -1423,7 +1524,8 @@ var useChatSession = ({
       const transport = createTransport(
         chatBffUrl,
         conversationIdRef.current,
-        token
+        token,
+        transportMode
       );
       const streamingIdRef = { current: generateId() };
       let firstChunk = true;
@@ -1466,7 +1568,7 @@ var useChatSession = ({
             timestamp: Date.now(),
             payload: { action: data.action, componentKey }
           });
-          onIntent?.(data.action, componentKey);
+          onIntent?.(data.action, componentKey, data.intentPayload);
         }
         setMessages((prev) => {
           const last = prev[prev.length - 1];
@@ -1525,7 +1627,7 @@ var useChatSession = ({
         setIsLoading(false);
       }
     },
-    [chatBffUrl, onIntent, onDebugEvent, getAppContext]
+    [getAppContext, onDebugEvent, chatBffUrl, transportMode, onIntent]
   );
   const contextDebounceRef = useRef4(null);
   const sendMessage = useCallback3(
@@ -1599,6 +1701,7 @@ var TekoChatWidget = forwardRef(
   ({
     appId,
     chatBffUrl,
+    transportMode,
     onIntent,
     renderRightPanel,
     renderBubble,
@@ -1638,6 +1741,7 @@ var TekoChatWidget = forwardRef(
     const { messages, isLoading, sendMessage, sendContext } = useChatSession({
       appId,
       chatBffUrl,
+      transportMode,
       onIntent: handleIntent,
       onDebugEvent,
       getAppContext

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "teko-chat-sdk",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "TekoChatSDK - AI chatbot SDK for Teko ECOM apps",
   "license": "UNLICENSED",
   "type": "module",