teko-chat-sdk 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,175 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+interface ChatLabels {
+    agentName: string;
+    agentStatus: string;
+    close: string;
+    minimize: string;
+    backToChat: string;
+    viewContent: string;
+    loadingContent: string;
+    inputPlaceholder: string;
+    send: string;
+    emptyState: string;
+}
+
+type ChatState = 'bubble' | 'mini' | 'fullscreen';
+interface SuggestOption {
+    key: string;
+    label: string;
+    payload?: Record<string, unknown>;
+}
+interface BFFResponseData {
+    conversationId: string;
+    message: string;
+    intent: string;
+    /** Any string — SDK only handles 'show_ui' internally, rest forwarded to onIntent */
+    action: string;
+    componentKey?: string;
+    path?: string;
+    suggest?: {
+        options: SuggestOption[];
+    };
+    timestamp: number;
+}
+interface BFFResponse {
+    code: number;
+    message: string;
+    data: BFFResponseData;
+}
+interface SDKRequest {
+    conversationId?: string;
+    userId?: string;
+    message?: string;
+    context?: Record<string, unknown>;
+    appContext?: Record<string, unknown>;
+    timestamp: number;
+}
+interface ChatMessage {
+    id: string;
+    role: 'user' | 'ai';
+    content: string;
+    options?: SuggestOption[];
+    timestamp: number;
+    isStreaming?: boolean;
+}
+interface DebugEvent {
+    /** Loại event:
+     * - `request`: SDK gửi message/context lên BFF
+     * - `response`: BFF trả về response
+     * - `intent`: onIntent được trigger (action + componentKey)
+     * - `context`: sendContext được gọi từ host app
+     */
+    type: 'request' | 'response' | 'intent' | 'context';
+    timestamp: number;
+    payload: unknown;
+}
+/** Frame protocol cho BFF → SDK streaming communication */
+type TransportFrame = {
+    type: 'chunk';
+    text: string;
+} | {
+    type: 'done';
+    data: BFFResponseData;
+} | {
+    type: 'error';
+    message: string;
+};
+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)
+     */
+    chatBffUrl: string;
+    /** Callback khi BFF trả về intent action (show_ui, navigate, ...) */
+    onIntent?: (action: string, componentKey?: string) => void;
+    /** Render content cho right panel ở fullscreen state */
+    renderRightPanel?: (componentKey: string) => ReactNode;
+    /**
+     * Inject app-level metadata vào mỗi BFF request.
+     * Được gọi tại send-time — luôn resolve giá trị mới nhất.
+     * Support sync và async. Field `appContext` bị omit nếu trả về `{}`.
+     *
+     * @example
+     * getAppContext={() => ({ terminalId: '123', sessionKey: store.getKey() })}
+     * getAppContext={async () => await myApp.getSessionMeta()}
+     */
+    getAppContext?: () => Record<string, unknown> | Promise<Record<string, unknown>>;
+    /**
+     * Custom bubble — SDK inject onClick để open chat.
+     * Nếu không truyền, SDK dùng bubble mặc định (bottom-right).
+     */
+    renderBubble?: (onClick: () => void) => ReactNode;
+    /**
+     * Vị trí bubble, ảnh hưởng hướng animation fullscreen.
+     * @default 'bottom-right'
+     */
+    bubbleAnchor?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    /**
+     * Layout mode:
+     * - `'desktop'` (default): mini popup góc dưới phải, fullscreen split 35/65
+     * - `'mobile'`: bottom sheet + single column fullscreen
+     *
+     * SDK không tự detect viewport — host app tự detect và truyền vào.
+     * @default 'desktop'
+     */
+    layoutMode?: 'desktop' | 'mobile';
+    /** Primary color (hex) cho toàn bộ widget. @default '#1a73e8' */
+    primaryColor?: string;
+    /** Avatar URL cho AI bubble. Mặc định dùng icon robot. */
+    botAvatar?: string;
+    /** @default 'vi' */
+    locale?: 'vi' | 'en';
+    /** Override từng label cụ thể thay vì đổi toàn bộ locale */
+    labels?: Partial<ChatLabels>;
+    /**
+     * Offset từ top (px) — dùng khi host app có fixed header.
+     * Fullscreen bắt đầu từ offsetTop thay vì top: 0.
+     * @default 0
+     */
+    offsetTop?: number;
+    /**
+     * Offset từ bottom (px) — dùng khi host app có fixed bottom nav.
+     * @default 0
+     */
+    offsetBottom?: number;
+    /** Chiều rộng mini popup (px). @default 360 */
+    miniWidth?: number;
+    /** Chiều cao mini popup (px). @default 480 */
+    miniHeight?: number;
+    /**
+     * CSS z-index cho bubble và mini popup. Fullscreen backdrop = zIndex + 9.
+     * @default 1031
+     */
+    zIndex?: number;
+    /**
+     * @internal
+     * Nhận mọi SDK event (request/response/intent/context) để debug.
+     * Dùng cho DebugPanel hoặc Storybook. Không dùng trong production.
+     */
+    onDebugEvent?: (event: DebugEvent) => void;
+}
+interface TekoChatWidgetRef {
+    sendContext: (data: Record<string, unknown>) => void;
+    sendMessage: (text: string) => void;
+    open: () => void;
+    close: () => void;
+    openFullscreen: (componentKey: string) => void;
+    closeFullscreen: () => void;
+}
+
+declare const TekoChatWidget: react.ForwardRefExoticComponent<TekoChatWidgetProps & react.RefAttributes<TekoChatWidgetRef>>;
+
+interface ITransport {
+    send(request: SDKRequest): void;
+    onChunk(callback: (text: string) => void): void;
+    onDone(callback: (data: BFFResponseData) => void): void;
+    onError(callback: (error: Error) => void): void;
+    connect(): Promise<void>;
+    disconnect(): void;
+}
+
+export { type BFFResponse, type BFFResponseData, type ChatLabels, type ChatMessage, type ChatState, type DebugEvent, type ITransport, type SDKRequest, type SuggestOption, TekoChatWidget, type TekoChatWidgetProps, type TekoChatWidgetRef, type TransportFrame };

package/dist/index.d.ts

@@ -0,0 +1,175 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+interface ChatLabels {
+    agentName: string;
+    agentStatus: string;
+    close: string;
+    minimize: string;
+    backToChat: string;
+    viewContent: string;
+    loadingContent: string;
+    inputPlaceholder: string;
+    send: string;
+    emptyState: string;
+}
+
+type ChatState = 'bubble' | 'mini' | 'fullscreen';
+interface SuggestOption {
+    key: string;
+    label: string;
+    payload?: Record<string, unknown>;
+}
+interface BFFResponseData {
+    conversationId: string;
+    message: string;
+    intent: string;
+    /** Any string — SDK only handles 'show_ui' internally, rest forwarded to onIntent */
+    action: string;
+    componentKey?: string;
+    path?: string;
+    suggest?: {
+        options: SuggestOption[];
+    };
+    timestamp: number;
+}
+interface BFFResponse {
+    code: number;
+    message: string;
+    data: BFFResponseData;
+}
+interface SDKRequest {
+    conversationId?: string;
+    userId?: string;
+    message?: string;
+    context?: Record<string, unknown>;
+    appContext?: Record<string, unknown>;
+    timestamp: number;
+}
+interface ChatMessage {
+    id: string;
+    role: 'user' | 'ai';
+    content: string;
+    options?: SuggestOption[];
+    timestamp: number;
+    isStreaming?: boolean;
+}
+interface DebugEvent {
+    /** Loại event:
+     * - `request`: SDK gửi message/context lên BFF
+     * - `response`: BFF trả về response
+     * - `intent`: onIntent được trigger (action + componentKey)
+     * - `context`: sendContext được gọi từ host app
+     */
+    type: 'request' | 'response' | 'intent' | 'context';
+    timestamp: number;
+    payload: unknown;
+}
+/** Frame protocol cho BFF → SDK streaming communication */
+type TransportFrame = {
+    type: 'chunk';
+    text: string;
+} | {
+    type: 'done';
+    data: BFFResponseData;
+} | {
+    type: 'error';
+    message: string;
+};
+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)
+     */
+    chatBffUrl: string;
+    /** Callback khi BFF trả về intent action (show_ui, navigate, ...) */
+    onIntent?: (action: string, componentKey?: string) => void;
+    /** Render content cho right panel ở fullscreen state */
+    renderRightPanel?: (componentKey: string) => ReactNode;
+    /**
+     * Inject app-level metadata vào mỗi BFF request.
+     * Được gọi tại send-time — luôn resolve giá trị mới nhất.
+     * Support sync và async. Field `appContext` bị omit nếu trả về `{}`.
+     *
+     * @example
+     * getAppContext={() => ({ terminalId: '123', sessionKey: store.getKey() })}
+     * getAppContext={async () => await myApp.getSessionMeta()}
+     */
+    getAppContext?: () => Record<string, unknown> | Promise<Record<string, unknown>>;
+    /**
+     * Custom bubble — SDK inject onClick để open chat.
+     * Nếu không truyền, SDK dùng bubble mặc định (bottom-right).
+     */
+    renderBubble?: (onClick: () => void) => ReactNode;
+    /**
+     * Vị trí bubble, ảnh hưởng hướng animation fullscreen.
+     * @default 'bottom-right'
+     */
+    bubbleAnchor?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    /**
+     * Layout mode:
+     * - `'desktop'` (default): mini popup góc dưới phải, fullscreen split 35/65
+     * - `'mobile'`: bottom sheet + single column fullscreen
+     *
+     * SDK không tự detect viewport — host app tự detect và truyền vào.
+     * @default 'desktop'
+     */
+    layoutMode?: 'desktop' | 'mobile';
+    /** Primary color (hex) cho toàn bộ widget. @default '#1a73e8' */
+    primaryColor?: string;
+    /** Avatar URL cho AI bubble. Mặc định dùng icon robot. */
+    botAvatar?: string;
+    /** @default 'vi' */
+    locale?: 'vi' | 'en';
+    /** Override từng label cụ thể thay vì đổi toàn bộ locale */
+    labels?: Partial<ChatLabels>;
+    /**
+     * Offset từ top (px) — dùng khi host app có fixed header.
+     * Fullscreen bắt đầu từ offsetTop thay vì top: 0.
+     * @default 0
+     */
+    offsetTop?: number;
+    /**
+     * Offset từ bottom (px) — dùng khi host app có fixed bottom nav.
+     * @default 0
+     */
+    offsetBottom?: number;
+    /** Chiều rộng mini popup (px). @default 360 */
+    miniWidth?: number;
+    /** Chiều cao mini popup (px). @default 480 */
+    miniHeight?: number;
+    /**
+     * CSS z-index cho bubble và mini popup. Fullscreen backdrop = zIndex + 9.
+     * @default 1031
+     */
+    zIndex?: number;
+    /**
+     * @internal
+     * Nhận mọi SDK event (request/response/intent/context) để debug.
+     * Dùng cho DebugPanel hoặc Storybook. Không dùng trong production.
+     */
+    onDebugEvent?: (event: DebugEvent) => void;
+}
+interface TekoChatWidgetRef {
+    sendContext: (data: Record<string, unknown>) => void;
+    sendMessage: (text: string) => void;
+    open: () => void;
+    close: () => void;
+    openFullscreen: (componentKey: string) => void;
+    closeFullscreen: () => void;
+}
+
+declare const TekoChatWidget: react.ForwardRefExoticComponent<TekoChatWidgetProps & react.RefAttributes<TekoChatWidgetRef>>;
+
+interface ITransport {
+    send(request: SDKRequest): void;
+    onChunk(callback: (text: string) => void): void;
+    onDone(callback: (data: BFFResponseData) => void): void;
+    onError(callback: (error: Error) => void): void;
+    connect(): Promise<void>;
+    disconnect(): void;
+}
+
+export { type BFFResponse, type BFFResponseData, type ChatLabels, type ChatMessage, type ChatState, type DebugEvent, type ITransport, type SDKRequest, type SuggestOption, TekoChatWidget, type TekoChatWidgetProps, type TekoChatWidgetRef, type TransportFrame };