@nickle/chatbot-react 0.1.0

package/README.md

@@ -0,0 +1,191 @@
+# @nickle/chatbot-react
+
+Customizable chatbot bubble + chat panel for React apps.
+
+## Install (npm)
+
+```bash
+npm install @nickle/chatbot-react
+```
+
+Do not install from `github:schvffler/chatbot-react`. That installs monorepo source and internal playground files.
+
+## Quick Start
+
+```tsx
+import "@nickle/chatbot-react/styles.css";
+import { ChatbotProvider, ChatbotWidget } from "@nickle/chatbot-react";
+
+export function SiteChat() {
+  return (
+    <ChatbotProvider
+      webhookUrl={process.env.NEXT_PUBLIC_CHATBOT_WEBHOOK_URL || ""}
+      agentName="Assistant"
+      assistantNote="Here to help"
+    >
+      <ChatbotWidget />
+    </ChatbotProvider>
+  );
+}
+```
+
+## How It Works
+
+### Provider runtime
+
+`ChatbotProvider` manages:
+
+- session id and chat history in `sessionStorage`
+- locale fallback copy for agent/welcome/disclaimer text
+- delayed welcome message when opened with an empty conversation
+- merged global config + latest `ChatbotPageConfig` override
+
+### Send/receive flow
+
+When `sendMessage` is called, the widget:
+
+1. Appends the user message.
+2. Adds a streaming assistant placeholder.
+3. Builds the request via adapter (`buildRequest`).
+4. Sends webhook payload including metadata (`sessionId`, `pageUrl`, `locale`, `agentName`, history).
+5. Parses non-streaming or streaming response and updates assistant message state.
+
+### Streaming behavior
+
+`streamingMode` options:
+
+- `auto`: stream when response looks stream-compatible
+- `on`: force stream parsing
+- `off`: parse as non-streaming response
+
+Stream formats supported:
+
+- `text/event-stream` (SSE)
+- line-delimited JSON/text
+- `application/x-ndjson`
+
+## Webhook Contract
+
+### Request payload (JSON mode)
+
+```json
+{
+  "message": "User message text",
+  "sessionId": "uuid-or-generated-id",
+  "metadata": {
+    "sessionId": "...",
+    "pageUrl": "https://client-site/path",
+    "timestamp": "2026-03-02T18:00:00.000Z",
+    "agentName": "Assistant",
+    "locale": "en",
+    "history": [
+      {
+        "id": "msg_1",
+        "role": "assistant",
+        "content": "Hi, how can I help you?",
+        "createdAt": "2026-03-02T17:59:00.000Z"
+      }
+    ]
+  }
+}
+```
+
+When uploads are enabled and files are attached, the adapter sends `multipart/form-data` with:
+
+- `message`
+- `sessionId`
+- `metadata` (JSON string)
+- `files[]`
+
+### Accepted response shapes (default adapter)
+
+Non-streaming JSON can return any of these fields:
+
+- `message`
+- `text`
+- `output`
+- `response`
+- `answer`
+- `content`
+
+Streaming chunks can return:
+
+```json
+{ "delta": "partial text" }
+{ "delta": "partial text", "done": true }
+```
+
+SSE `[DONE]` is also supported.
+
+## API Highlights
+
+### Components
+
+- `ChatbotProvider`
+- `ChatbotWidget`
+- `ChatbotPageConfig`
+
+### Hooks
+
+- `useChatbot`
+- `useChatbotSession`
+
+### Common provider props
+
+- `webhookUrl: string`
+- `streamingMode?: "auto" | "on" | "off"`
+- `enableUploads?: boolean`
+- `agentName?: string`
+- `assistantNote?: string`
+- `headers?: Record<string, string>`
+- `theme?: Partial<ChatbotThemeTokens>`
+- `icons?: Partial<ChatbotIcons>`
+- `adapter?: ChatbotAdapter`
+- `events?: Partial<ChatbotEventHandlers>`
+
+### Per-page overrides (`ChatbotPageConfig`)
+
+- `enabled?: boolean`
+- `agentName?: string`
+- `assistantNote?: string`
+- `enableUploads?: boolean`
+- `theme?: Partial<ChatbotThemeTokens>`
+
+## Tailwind Notes
+
+The package ships compiled `styles.css` for the widget UI.
+
+If you want Tailwind to see package class strings (for custom overrides), add one of these globs:
+
+```js
+"./node_modules/@nickle/chatbot-react/src/**/*.{ts,tsx}",
+"./node_modules/@nickle/chatbot-react/dist/**/*.{js,cjs}"
+```
+
+## Build
+
+```bash
+npm run build --workspace @nickle/chatbot-react
+```
+
+## Troubleshooting
+
+### Install fails from npm
+
+- Confirm package name is exactly `@nickle/chatbot-react`
+- Check your npm auth only if your environment requires it
+- Ensure your npm client can access the latest published version
+
+### Webhook returns but UI shows empty assistant response
+
+- Confirm response body includes recognized text fields (`message`, `text`, `output`, `response`, `answer`, `content`)
+- If using custom format, provide an `adapter.parseJsonResponse`
+
+### Streaming response not updating incrementally
+
+- Set `streamingMode="on"` while debugging
+- Ensure server returns SSE/line-delimited chunks compatible with adapter parsing
+
+### Browser blocks webhook requests
+
+- Verify CORS policy on your webhook endpoint allows the client origin and headers

package/dist/index.d.mts

@@ -0,0 +1,169 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ComponentType, ReactNode } from 'react';
+
+type ChatRole = "user" | "assistant" | "system";
+type MessageStatus = "pending" | "streaming" | "complete" | "error";
+interface ChatAttachment {
+    id: string;
+    name: string;
+    size: number;
+    type: string;
+    file?: File;
+}
+interface ChatMessage {
+    id: string;
+    role: ChatRole;
+    content: string;
+    createdAt: string;
+    status?: MessageStatus;
+    attachments?: ChatAttachment[];
+}
+interface NormalizedAssistantChunk {
+    delta?: string;
+    done?: boolean;
+    message?: string;
+}
+interface ChatbotAdapterRequestInput {
+    webhookUrl: string;
+    message: string;
+    sessionId: string;
+    agentName: string;
+    files: File[];
+    metadata: Record<string, unknown>;
+    headers?: Record<string, string>;
+}
+interface ChatbotAdapter {
+    buildRequest?: (input: ChatbotAdapterRequestInput) => RequestInit & {
+        url?: string;
+    };
+    parseJsonResponse?: (raw: unknown) => NormalizedAssistantChunk;
+    parseStreamChunk?: (chunk: string) => NormalizedAssistantChunk;
+}
+interface ChatbotThemeTokens {
+    primary: string;
+    primaryForeground: string;
+    background: string;
+    surface: string;
+    surfaceForeground: string;
+    muted: string;
+    mutedForeground: string;
+    border: string;
+    ring: string;
+    userBubble: string;
+    userText: string;
+    assistantBubble: string;
+    assistantText: string;
+    radius: string;
+    fontFamily: string;
+    shadowBubble: string;
+    shadowPanel: string;
+}
+interface ChatbotIconProps {
+    size?: string | number;
+    className?: string;
+    strokeWidth?: string | number;
+}
+interface ChatbotIcons {
+    /**
+     * Legacy alias. If provided, it maps to launcherClosed when launcherClosed is not set.
+     */
+    launcher?: ComponentType<ChatbotIconProps>;
+    launcherClosed: ComponentType<ChatbotIconProps>;
+    launcherOpen: ComponentType<ChatbotIconProps>;
+    close: ComponentType<ChatbotIconProps>;
+    send: ComponentType<ChatbotIconProps>;
+    attach: ComponentType<ChatbotIconProps>;
+    bot: ComponentType<ChatbotIconProps>;
+    menu: ComponentType<ChatbotIconProps>;
+    expand: ComponentType<ChatbotIconProps>;
+    download: ComponentType<ChatbotIconProps>;
+}
+interface ChatbotEventHandlers {
+    onOpen: () => void;
+    onClose: () => void;
+    onMessageSent: (message: ChatMessage) => void;
+    onChunkReceived: (chunk: string) => void;
+    onResponseComplete: (message: ChatMessage) => void;
+    onError: (error: Error) => void;
+    onAttachmentAdded: (attachments: ChatAttachment[]) => void;
+}
+interface ChatbotClassNames {
+    root: string;
+    bubble: string;
+    panel: string;
+    header: string;
+    headerMeta: string;
+    menu: string;
+    menuItem: string;
+    body: string;
+    footer: string;
+    composer: string;
+    input: string;
+    sendButton: string;
+}
+interface PageConfigOverrides {
+    enabled?: boolean;
+    agentName?: string;
+    assistantNote?: string;
+    enableUploads?: boolean;
+    theme?: Partial<ChatbotThemeTokens>;
+}
+interface ChatbotProviderProps {
+    webhookUrl: string;
+    children: ReactNode;
+    locale?: string;
+    agentName?: string;
+    assistantNote?: string;
+    enableUploads?: boolean;
+    streamingMode?: "auto" | "on" | "off";
+    headers?: Record<string, string>;
+    theme?: Partial<ChatbotThemeTokens>;
+    icons?: Partial<ChatbotIcons>;
+    adapter?: ChatbotAdapter;
+    events?: Partial<ChatbotEventHandlers>;
+    initialOpen?: boolean;
+    position?: "bottom-right" | "bottom-left";
+    classNames?: Partial<ChatbotClassNames>;
+}
+interface SendMessageInput {
+    text: string;
+    files?: File[];
+}
+interface ChatbotContextValue {
+    isOpen: boolean;
+    isAwaiting: boolean;
+    messages: ChatMessage[];
+    sessionId: string;
+    uploadEnabled: boolean;
+    agentName: string;
+    assistantNote: string;
+    disclaimerText: string;
+    position: "bottom-right" | "bottom-left";
+    themeVars: Record<string, string>;
+    icons: ChatbotIcons;
+    classNames: Partial<ChatbotClassNames>;
+    open: () => void;
+    close: () => void;
+    toggle: () => void;
+    sendMessage: (input: SendMessageInput) => Promise<void>;
+    clearConversation: () => void;
+    registerPageConfig: (id: string, config: PageConfigOverrides) => void;
+    unregisterPageConfig: (id: string) => void;
+    widgetEnabled: boolean;
+    resetSession: () => void;
+}
+
+declare function ChatbotProvider({ children, webhookUrl, locale, agentName, assistantNote, enableUploads, streamingMode, headers, theme, icons, adapter, events, initialOpen, position, classNames, }: ChatbotProviderProps): react_jsx_runtime.JSX.Element;
+
+declare function ChatbotWidget(): react_jsx_runtime.JSX.Element | null;
+
+declare function ChatbotPageConfig(props: PageConfigOverrides): null;
+
+declare function useChatbot(): ChatbotContextValue;
+
+declare function useChatbotSession(): {
+    sessionId: string;
+    resetSession: () => void;
+};
+
+export { type ChatAttachment, type ChatMessage, type ChatbotAdapter, type ChatbotAdapterRequestInput, type ChatbotClassNames, type ChatbotContextValue, type ChatbotEventHandlers, type ChatbotIcons, ChatbotPageConfig, ChatbotProvider, type ChatbotProviderProps, type ChatbotThemeTokens, ChatbotWidget, type NormalizedAssistantChunk, type PageConfigOverrides, type SendMessageInput, useChatbot, useChatbotSession };

package/dist/index.d.ts

@@ -0,0 +1,169 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ComponentType, ReactNode } from 'react';
+
+type ChatRole = "user" | "assistant" | "system";
+type MessageStatus = "pending" | "streaming" | "complete" | "error";
+interface ChatAttachment {
+    id: string;
+    name: string;
+    size: number;
+    type: string;
+    file?: File;
+}
+interface ChatMessage {
+    id: string;
+    role: ChatRole;
+    content: string;
+    createdAt: string;
+    status?: MessageStatus;
+    attachments?: ChatAttachment[];
+}
+interface NormalizedAssistantChunk {
+    delta?: string;
+    done?: boolean;
+    message?: string;
+}
+interface ChatbotAdapterRequestInput {
+    webhookUrl: string;
+    message: string;
+    sessionId: string;
+    agentName: string;
+    files: File[];
+    metadata: Record<string, unknown>;
+    headers?: Record<string, string>;
+}
+interface ChatbotAdapter {
+    buildRequest?: (input: ChatbotAdapterRequestInput) => RequestInit & {
+        url?: string;
+    };
+    parseJsonResponse?: (raw: unknown) => NormalizedAssistantChunk;
+    parseStreamChunk?: (chunk: string) => NormalizedAssistantChunk;
+}
+interface ChatbotThemeTokens {
+    primary: string;
+    primaryForeground: string;
+    background: string;
+    surface: string;
+    surfaceForeground: string;
+    muted: string;
+    mutedForeground: string;
+    border: string;
+    ring: string;
+    userBubble: string;
+    userText: string;
+    assistantBubble: string;
+    assistantText: string;
+    radius: string;
+    fontFamily: string;
+    shadowBubble: string;
+    shadowPanel: string;
+}
+interface ChatbotIconProps {
+    size?: string | number;
+    className?: string;
+    strokeWidth?: string | number;
+}
+interface ChatbotIcons {
+    /**
+     * Legacy alias. If provided, it maps to launcherClosed when launcherClosed is not set.
+     */
+    launcher?: ComponentType<ChatbotIconProps>;
+    launcherClosed: ComponentType<ChatbotIconProps>;
+    launcherOpen: ComponentType<ChatbotIconProps>;
+    close: ComponentType<ChatbotIconProps>;
+    send: ComponentType<ChatbotIconProps>;
+    attach: ComponentType<ChatbotIconProps>;
+    bot: ComponentType<ChatbotIconProps>;
+    menu: ComponentType<ChatbotIconProps>;
+    expand: ComponentType<ChatbotIconProps>;
+    download: ComponentType<ChatbotIconProps>;
+}
+interface ChatbotEventHandlers {
+    onOpen: () => void;
+    onClose: () => void;
+    onMessageSent: (message: ChatMessage) => void;
+    onChunkReceived: (chunk: string) => void;
+    onResponseComplete: (message: ChatMessage) => void;
+    onError: (error: Error) => void;
+    onAttachmentAdded: (attachments: ChatAttachment[]) => void;
+}
+interface ChatbotClassNames {
+    root: string;
+    bubble: string;
+    panel: string;
+    header: string;
+    headerMeta: string;
+    menu: string;
+    menuItem: string;
+    body: string;
+    footer: string;
+    composer: string;
+    input: string;
+    sendButton: string;
+}
+interface PageConfigOverrides {
+    enabled?: boolean;
+    agentName?: string;
+    assistantNote?: string;
+    enableUploads?: boolean;
+    theme?: Partial<ChatbotThemeTokens>;
+}
+interface ChatbotProviderProps {
+    webhookUrl: string;
+    children: ReactNode;
+    locale?: string;
+    agentName?: string;
+    assistantNote?: string;
+    enableUploads?: boolean;
+    streamingMode?: "auto" | "on" | "off";
+    headers?: Record<string, string>;
+    theme?: Partial<ChatbotThemeTokens>;
+    icons?: Partial<ChatbotIcons>;
+    adapter?: ChatbotAdapter;
+    events?: Partial<ChatbotEventHandlers>;
+    initialOpen?: boolean;
+    position?: "bottom-right" | "bottom-left";
+    classNames?: Partial<ChatbotClassNames>;
+}
+interface SendMessageInput {
+    text: string;
+    files?: File[];
+}
+interface ChatbotContextValue {
+    isOpen: boolean;
+    isAwaiting: boolean;
+    messages: ChatMessage[];
+    sessionId: string;
+    uploadEnabled: boolean;
+    agentName: string;
+    assistantNote: string;
+    disclaimerText: string;
+    position: "bottom-right" | "bottom-left";
+    themeVars: Record<string, string>;
+    icons: ChatbotIcons;
+    classNames: Partial<ChatbotClassNames>;
+    open: () => void;
+    close: () => void;
+    toggle: () => void;
+    sendMessage: (input: SendMessageInput) => Promise<void>;
+    clearConversation: () => void;
+    registerPageConfig: (id: string, config: PageConfigOverrides) => void;
+    unregisterPageConfig: (id: string) => void;
+    widgetEnabled: boolean;
+    resetSession: () => void;
+}
+
+declare function ChatbotProvider({ children, webhookUrl, locale, agentName, assistantNote, enableUploads, streamingMode, headers, theme, icons, adapter, events, initialOpen, position, classNames, }: ChatbotProviderProps): react_jsx_runtime.JSX.Element;
+
+declare function ChatbotWidget(): react_jsx_runtime.JSX.Element | null;
+
+declare function ChatbotPageConfig(props: PageConfigOverrides): null;
+
+declare function useChatbot(): ChatbotContextValue;
+
+declare function useChatbotSession(): {
+    sessionId: string;
+    resetSession: () => void;
+};
+
+export { type ChatAttachment, type ChatMessage, type ChatbotAdapter, type ChatbotAdapterRequestInput, type ChatbotClassNames, type ChatbotContextValue, type ChatbotEventHandlers, type ChatbotIcons, ChatbotPageConfig, ChatbotProvider, type ChatbotProviderProps, type ChatbotThemeTokens, ChatbotWidget, type NormalizedAssistantChunk, type PageConfigOverrides, type SendMessageInput, useChatbot, useChatbotSession };