rushchatbot 1.6.7

package/INTEGRATION.md

@@ -0,0 +1,559 @@
+# RushChatbot
+
+**Version:** 1.5.1
+
+Embeddable hybrid chatbot plugin that combines a click-based FAQ tree with a free-text query engine backed by n8n. Ships as an npm package with a Node.js/Express server and a React widget.
+
+**Features:**
+- Click-based FAQ question tree with subquestions
+- Fuzzy + keyword matching against your config
+- n8n webhook fallback for unmatched queries
+- Markdown rendering (bold, lists, headings)
+- Multi-bubble paragraph responses
+- Draggable floating chat button
+- Tagalog (TL) language support
+- Input validation and profanity guardrails
+- Session-based analytics
+
+---
+
+## Table of Contents
+
+1. [Requirements](#1-requirements)
+2. [Installation](#2-installation)
+3. [Scaffold Config Files](#3-scaffold-config-files)
+4. [Configure the Chatbot](#4-configure-the-chatbot)
+5. [Build the FAQ Tree](#5-build-the-faq-tree)
+6. [Start the Server](#6-start-the-server)
+7. [Embed the Widget](#7-embed-the-widget)
+8. [Floating Button Behavior](#8-floating-button-behavior)
+9. [n8n Webhook Setup](#9-n8n-webhook-setup)
+10. [n8n Response Formats](#10-n8n-response-formats)
+11. [Environment Variables](#11-environment-variables)
+12. [API Reference](#12-api-reference)
+13. [Analytics](#13-analytics)
+14. [Troubleshooting](#14-troubleshooting)
+
+---
+
+## 1. Requirements
+
+| Requirement | Version |
+|---|---|
+| Node.js | >= 18.0.0 |
+| npm | >= 9.0.0 |
+| React (for widget) | >= 18.0.0 |
+| n8n instance | Any hosted or self-hosted |
+
+---
+
+## 2. Installation
+
+```bash
+npm install rushchatbot
+```
+
+---
+
+## 3. Scaffold Config Files
+
+Run the init command to generate the required config and questions files in a directory of your choice:
+
+```bash
+npx rushchatbot init ./chatbot
+```
+
+This creates three files:
+
+```
+chatbot/
+├── chatbot.config.json     ← branding, n8n, chat settings
+├── questions.json          ← English FAQ tree
+└── questions.tl.json       ← Tagalog FAQ tree (optional)
+```
+
+---
+
+## 4. Configure the Chatbot
+
+Edit `chatbot.config.json` with your settings:
+
+```json
+{
+  "branding": {
+    "title": "My Support Bot",
+    "subtitle": "How can we help you today?",
+    "theme": {
+      "primaryColor": "#4F46E5",
+      "backgroundColor": "#FFFFFF",
+      "userBubbleColor": "#4F46E5",
+      "botBubbleColor": "#F3F4F6",
+      "textColor": "#111827",
+      "fontFamily": "Inter, sans-serif"
+    }
+  },
+  "n8n": {
+    "webhookUrl": "https://your-n8n.com/webhook/your-webhook-id",
+    "timeoutMs": 55000
+  },
+  "chat": {
+    "welcomeMessage": "Hi! Choose a question below or type your own.",
+    "fallbackMessage": "Let me look that up for you...",
+    "matchThreshold": 0.4,
+    "showPreQuestionsOnStart": true,
+    "language": "en"
+  }
+}
+```
+
+### Config field reference
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `branding.title` | string | — | Chat header title |
+| `branding.subtitle` | string | — | Chat header subtitle |
+| `branding.theme.primaryColor` | string | `#4F46E5` | Header, buttons, user bubble color |
+| `branding.theme.backgroundColor` | string | `#FFFFFF` | Chat window background |
+| `branding.theme.userBubbleColor` | string | `#4F46E5` | User message bubble color |
+| `branding.theme.botBubbleColor` | string | `#F3F4F6` | Bot message bubble color |
+| `branding.theme.textColor` | string | `#111827` | Main text color |
+| `branding.theme.fontFamily` | string | `Inter, sans-serif` | Font stack |
+| `n8n.webhookUrl` | string | — | Your n8n POST webhook URL |
+| `n8n.timeoutMs` | number | `55000` | n8n request timeout in milliseconds |
+| `chat.welcomeMessage` | string | — | First message shown when chat opens |
+| `chat.fallbackMessage` | string | — | Shown when an error occurs |
+| `chat.matchThreshold` | number | `0.4` | Fuzzy match sensitivity (0–1). Lower = stricter |
+| `chat.showPreQuestionsOnStart` | boolean | `true` | Show FAQ buttons when chat opens |
+| `chat.language` | `"en"` \| `"tl"` | `"en"` | Language for displaying FAQ questions |
+
+---
+
+## 6. Build the FAQ Tree
+
+Edit `questions.json` to define your FAQ categories and answers. The structure supports two levels: main questions and subquestions.
+
+```json
+[
+  {
+    "id": "q1",
+    "question": "About Our Company",
+    "answer": "We are a company that...",
+    "subquestions": [
+      {
+        "id": "q1a",
+        "question": "When was the company founded?",
+        "answer": "We were founded in 2010.",
+        "subquestions": []
+      },
+      {
+        "id": "q1b",
+        "question": "What is your mission?",
+        "answer": "Our mission is to...",
+        "subquestions": []
+      }
+    ]
+  },
+  {
+    "id": "q2",
+    "question": "Contact Information",
+    "answer": "You can reach us at support@example.com.",
+    "subquestions": []
+  }
+]
+```
+
+### Rules
+
+- Every question must have a unique `id`
+- `subquestions` must be an array (use `[]` if none)
+- `answer` is shown when the question is clicked directly or matched via text search
+- For Tagalog support, mirror the same structure in `questions.tl.json` with translated text — keep the same `id` values
+
+---
+
+## 6. Start the Server
+
+Create a server entry file (e.g. `server.js` or `server.ts`):
+
+```ts
+import { createServer } from 'rushchatbot/server'
+import path from 'path'
+
+createServer({
+  configPath: path.resolve('./chatbot/chatbot.config.json'),
+  questionsPath: path.resolve('./chatbot/questions.json'),
+  questionsTagalogPath: path.resolve('./chatbot/questions.tl.json'), // optional
+  port: 3001,
+  corsOrigin: 'https://your-frontend-domain.com', // or '*' for development
+}).listen()
+```
+
+### Server options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `configPath` | string | — | **Required.** Absolute path to `chatbot.config.json` |
+| `questionsPath` | string | — | **Required.** Absolute path to `questions.json` |
+| `questionsTagalogPath` | string | — | Optional. Absolute path to `questions.tl.json` |
+| `port` | number | `3001` | Port to listen on |
+| `corsOrigin` | string \| string[] | `*` | Allowed CORS origin(s) |
+
+Start the server:
+
+```bash
+node server.js
+```
+
+On successful startup you will see:
+
+```
+[RushChatbot] Server running on http://localhost:3001
+```
+
+---
+
+## 7. Embed the Widget
+
+### React
+
+Install peer dependencies if not already present:
+
+```bash
+npm install react react-dom marked
+```
+
+Import and render the widget:
+
+```tsx
+import { ChatWidget } from 'rushchatbot/client'
+
+export default function App() {
+  return (
+    <div>
+      <ChatWidget apiBase="http://localhost:3001/api/chat" />
+    </div>
+  )
+}
+```
+
+The widget renders as a **floating draggable button** fixed to the bottom-right of the screen. Clicking it opens the chat box above the button.
+
+### Widget props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `apiBase` | string | `http://localhost:3001/api/chat` | Base URL of the RushChatbot server |
+| `width` | number | `380` | Chat box width in pixels |
+| `height` | number | `580` | Chat box height in pixels |
+
+### Plain HTML / non-React projects
+
+Build the client bundle and include it via a script tag:
+
+```html
+<script src="https://unpkg.com/react/umd/react.production.min.js"></script>
+<script src="https://unpkg.com/react-dom/umd/react-dom.production.min.js"></script>
+<script src="/path/to/rushchatbot/dist/client.es.js"></script>
+
+<div id="rushchatbot-root"></div>
+<script>
+  ReactDOM.createRoot(document.getElementById('rushchatbot-root')).render(
+    React.createElement(RushChatbotClient.ChatWidget, {
+      apiBase: 'http://localhost:3001/api/chat'
+    })
+  )
+</script>
+```
+
+---
+
+## 8. Floating Button Behavior
+
+The chat button is draggable across the entire screen:
+
+- **Drag** — click and hold, then move to reposition the button anywhere on screen
+- **Click** (no drag) — toggles the chat box open or closed
+- **Chat box position** — always appears directly above the button, clamped to the viewport so it never goes off-screen
+- **Close** — click the ✕ button inside the chat header, or click the floating button again
+- Works on both desktop (mouse) and mobile (touch)
+
+---
+
+## 9. n8n Webhook Setup
+
+When a user types a query that doesn't match any FAQ answer, RushChatbot forwards it to your n8n webhook.
+
+### What RushChatbot sends to n8n
+
+```json
+{
+  "query": "the user's message",
+  "sessionId": "sess_abc123"
+}
+```
+
+Headers sent:
+
+```
+Content-Type: application/json
+x-session-id: sess_abc123
+```
+
+### Setting up the webhook in n8n
+
+1. Create a new workflow in n8n
+2. Add a **Webhook** trigger node — set method to `POST`
+3. Copy the webhook URL into `chatbot.config.json` under `n8n.webhookUrl`
+4. Add your AI/logic nodes after the webhook trigger
+5. End with a **Respond to Webhook** node returning one of the supported response formats (see section 11)
+6. Activate the workflow
+
+### Session continuity
+
+The `sessionId` is generated per browser tab (`sess_` + timestamp + random suffix). Pass it through your n8n workflow to maintain conversation context with your AI agent.
+
+---
+
+## 10. n8n Response Formats
+
+RushChatbot automatically parses all of the following response shapes from n8n:
+
+### Single answer
+
+```json
+[{ "output": "Your answer text here" }]
+```
+
+```json
+[{ "answer": "Your answer text here" }]
+```
+
+```json
+[{ "text": "Your answer text here" }]
+```
+
+### Multiple bubbles (paragraphs)
+
+Return a `paragraphs` array to render each item as a **separate chat bubble** with a short delay between them:
+
+```json
+[{
+  "paragraphs": [
+    "First part of the response.",
+    "Second part with **bold** and lists.",
+    "Third bubble with a follow-up question."
+  ]
+}]
+```
+
+### Markdown support
+
+All responses are rendered as Markdown. Supported formatting:
+
+| Syntax | Renders as |
+|---|---|
+| `**bold**` | **bold** |
+| `# Heading` | Large heading |
+| `- item` | Bullet list |
+| `1. item` | Numbered list |
+| `[link](url)` | Hyperlink |
+| `\n` (newline) | Line break |
+
+---
+
+## 11. Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `PORT` | No | Override the server port (default: `3001`) |
+
+### Setting the port
+
+```bash
+PORT=4000 node server.js
+```
+
+---
+
+## 12. API Reference
+
+All endpoints are mounted under `/api/chat`.
+
+### `GET /api/chat/config`
+
+Returns branding and chat settings. Safe to call from the frontend — never exposes n8n credentials or license key.
+
+**Response:**
+```json
+{
+  "branding": { "title": "...", "subtitle": "...", "theme": { } },
+  "chat": { "welcomeMessage": "...", "language": "en" }
+}
+```
+
+---
+
+### `GET /api/chat/questions`
+
+Returns the FAQ question tree in the configured language.
+
+**Response:**
+```json
+[
+  {
+    "id": "q1",
+    "question": "About Our Company",
+    "answer": "...",
+    "subquestions": []
+  }
+]
+```
+
+---
+
+### `GET /api/chat/query?query=your+question&sessionId=sess_abc`
+
+Forwards the query **directly to n8n**, bypassing FAQ matching. Useful for testing your n8n workflow from the browser.
+
+**Query params:**
+
+| Param | Required | Description |
+|---|---|---|
+| `query` | Yes | The user's question |
+| `sessionId` | No | Session identifier |
+
+**Response:**
+```json
+{ "answer": "...", "source": "n8n" }
+```
+or
+```json
+{ "paragraphs": ["...", "..."], "source": "n8n" }
+```
+
+---
+
+### `POST /api/chat/query`
+
+Main query endpoint. Runs the full pipeline: input validation → guardrails → FAQ matching → n8n fallback.
+
+**Request body:**
+```json
+{
+  "query": "How do I apply for membership?",
+  "sessionId": "sess_abc123"
+}
+```
+
+**Response (FAQ match):**
+```json
+{
+  "answer": "You can apply by...",
+  "source": "config",
+  "matchedQuestion": "How do I apply for membership?",
+  "matchedKeywords": ["apply", "membership"],
+  "score": 87
+}
+```
+
+**Response (n8n fallback):**
+```json
+{ "answer": "...", "source": "n8n" }
+```
+
+**Response (validation/guardrail blocked):**
+```json
+{ "answer": "Please rephrase your question...", "source": "validation" }
+```
+
+---
+
+### `POST /api/chat/click`
+
+Tracks when a user clicks a pre-built FAQ question.
+
+**Request body:**
+```json
+{
+  "questionId": "q1a",
+  "sessionId": "sess_abc123"
+}
+```
+
+**Response:**
+```json
+{ "ok": true }
+```
+
+---
+
+### `GET /api/chat/analytics`
+
+Returns the full analytics log.
+
+**Response:**
+```json
+[
+  {
+    "sessionId": "sess_abc123",
+    "questionId": "q1a",
+    "timestamp": "2025-01-01T10:00:00.000Z",
+    "type": "click"
+  }
+]
+```
+
+**Analytics types:**
+
+| Type | Description |
+|---|---|
+| `click` | User clicked a pre-built FAQ question |
+| `match` | User query matched a FAQ answer |
+| `n8n` | Query was forwarded to n8n |
+| `error` | Validation, guardrail, or server error |
+
+---
+
+## 13. Analytics
+
+Analytics are written to `analytics.json` in the same directory as your `chatbot.config.json`. Each entry records:
+
+- `sessionId` — browser session (resets on new tab)
+- `questionId` — the matched question ID, or `n8n` / `error` / `guardrail`
+- `timestamp` — ISO 8601 UTC
+- `type` — `click`, `match`, `n8n`, or `error`
+
+You can query the log at any time via `GET /api/chat/analytics` or read the file directly.
+
+---
+
+## 14. Troubleshooting
+
+### `[RushChatbot] configPath not found`
+
+- Use `path.resolve()` to ensure the path is absolute
+- Verify the file exists at the specified location
+
+### Chat widget shows nothing / blank
+
+- Check the browser console for CORS errors
+- Ensure `corsOrigin` in `createServer()` includes your frontend's origin
+- Confirm the server is running and reachable at the `apiBase` URL
+
+### n8n not responding / timeout
+
+- Increase `n8n.timeoutMs` in `chatbot.config.json` (default is 55000ms)
+- Test the webhook directly: `GET http://localhost:3001/api/chat/query?query=hello`
+- Check your n8n workflow is activated (not just saved)
+
+### Port already in use
+
+```bash
+kill $(lsof -ti :3001)
+```
+
+### Queries always fall through to n8n (no FAQ matches)
+
+- Lower `chat.matchThreshold` in config (e.g. `0.3`)
+- Ensure your `questions.json` answers contain keywords that appear in user queries
+- Check that question `id` values are unique across the entire tree

package/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>frontend</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>