@blockspark/chat-widget 1.0.1 → 1.0.3

package/README.md

@@ -1,106 +1,145 @@
 # BlockSpark Chat Widget
 
-A reusable React chat widget component that connects directly with Dialogflow CX - no backend API required!
+A reusable chat widget for **React**, **Next.js**, **Vue 3**, and **vanilla HTML (CDN)** that connects directly with Dialogflow CX — no backend API required.
 
 ## Installation
 
-### Option 1: Install from Local Path (Recommended for Development)
+Install from npm (for React, Next.js, or Vue projects):
 
 ```bash
-# In your website project directory
-npm install /path/to/blockspark-chat-widget
-# or
-npm install ../blockspark-chat-widget
+npm install @blockspark/chat-widget
 ```
 
-### Option 2: Use npm link (For Development)
+- **React / Next.js**: You also need `react` and `react-dom` (they are peer dependencies).
+- **Vue 3**: You also need `vue`. The widget bundles React internally for the Vue build, so you do **not** need to install React.
 
 ```bash
-# In the blockspark-chat-widget directory
-npm link
+# React or Next.js
+npm install @blockspark/chat-widget react react-dom
 
-# In your website project directory
-npm link @blockspark/chat-widget
+# Vue 3 only
+npm install @blockspark/chat-widget vue
 ```
 
-### Option 3: Publish to npm (For Production)
+**Development / local testing:**
 
 ```bash
-# Build the library first
-npm run build
-
-# Publish to npm (make sure you're logged in)
-npm publish
+# From your app directory
+npm install /path/to/blockspark-chat-widget
+# or use npm link in the widget repo, then npm link @blockspark/chat-widget in your app
 ```
 
-Then install in your project:
-```bash
-npm install @blockspark/chat-widget
-```
+---
 
 ## Usage
 
-### Basic Usage
+Use **camelCase** for all props in every environment (React, Next.js, Vue, and CDN). Examples: `dfProjectId`, `serviceAccountKey`, `languageCode`.
+
+---
+
+### React
+
+Import the component and the default styles, then render with your config. Copy the props below and replace the placeholder values with yours.
 
 ```tsx
 import ChatWidget from '@blockspark/chat-widget';
 import '@blockspark/chat-widget/dist/styles.css';
 
-// Load your Google Cloud service account key
 import serviceAccountKey from './path/to/service-account-key.json';
 
 function App() {
   return (
-    <div>
-      <ChatWidget
-        dfProjectId="your-project-id"
-        dfLocation="us-central1"
-        dfAgentId="your-agent-id"
-        serviceAccountKey={serviceAccountKey}
-        languageCode="en"
-      />
-    </div>
+    <ChatWidget
+      dfProjectId="your-project-id"
+      dfLocation="us-central1"
+      dfAgentId="your-agent-id"
+      serviceAccountKey={serviceAccountKey}
+      // accessToken="your-token"  // use instead of serviceAccountKey if you have a token
+      languageCode="en"
+      title="💬 BlockSpark AI Assistant"
+      subtitle="We're here to help"
+      welcomeTitle="👋 Welcome to Blockspark"
+      welcomeMessage="My name is BlockSpark AI Assistant and I'll guide you."
+      welcomeCta="💬 Click here to start chatting!"
+      showWelcomePopup={true}
+      welcomePopupDelay={1500}
+      fallbackWelcomeMessage="Hello! I'm BlockSpark AI Assistant. How can I help you today?"
+      inputPlaceholder="Type your message..."
+      emptyStateMessage="Hi! I'm BlockSpark AI Assistant. How can I help you today?"
+      debug={false}
+      backendBaseUrl="http://localhost:8012"
+      backendWsUrl="ws://localhost:8012"
+    />
   );
 }
 ```
 
-### Using Access Token (Alternative)
+### Next.js
 
-If you prefer to manage authentication yourself:
+The widget uses browser APIs (e.g. `localStorage`) and is intended to run on the client. Use **dynamic import with SSR disabled** so it only loads in the browser.
+
+**App Router (Next.js 13+):**
 
 ```tsx
-import ChatWidget from '@blockspark/chat-widget';
+'use client';
+
+import dynamic from 'next/dynamic';
 import '@blockspark/chat-widget/dist/styles.css';
 
-function App() {
-  const [accessToken, setAccessToken] = useState<string>('');
+const ChatWidget = dynamic(
+  () => import('@blockspark/chat-widget').then((mod) => mod.default),
+  { ssr: false }
+);
 
-  // Get access token from your backend or OAuth flow
-  useEffect(() => {
-    // Your token fetching logic here
-    fetchAccessToken().then(setAccessToken);
-  }, []);
+export default function Page() {
+  const serviceAccountKey = {
+    /* your key object, or load from env/server */
+  };
 
   return (
-    <ChatWidget
-      dfProjectId="your-project-id"
-      dfLocation="us-central1"
-      dfAgentId="your-agent-id"
-      accessToken={accessToken}
-      languageCode="en"
-    />
+    <div>
+      <h1>My Page</h1>
+      <ChatWidget
+        dfProjectId="your-project-id"
+        dfLocation="us-central1"
+        dfAgentId="your-agent-id"
+        serviceAccountKey={serviceAccountKey}
+        languageCode="en"
+        title="💬 BlockSpark AI Assistant"
+        subtitle="We're here to help"
+        welcomeTitle="👋 Welcome to Blockspark"
+        welcomeMessage="My name is BlockSpark AI Assistant and I'll guide you."
+        welcomeCta="💬 Click here to start chatting!"
+        showWelcomePopup={true}
+        welcomePopupDelay={1500}
+        fallbackWelcomeMessage="Hello! I'm BlockSpark AI Assistant. How can I help you today?"
+        inputPlaceholder="Type your message..."
+        emptyStateMessage="Hi! I'm BlockSpark AI Assistant. How can I help you today?"
+        debug={false}
+        backendBaseUrl="http://localhost:8012"
+        backendWsUrl="ws://localhost:8012"
+      />
+    </div>
   );
 }
 ```
 
-### With Custom Configuration
+**Pages Router:**
 
 ```tsx
-import ChatWidget from '@blockspark/chat-widget';
+import dynamic from 'next/dynamic';
 import '@blockspark/chat-widget/dist/styles.css';
-import serviceAccountKey from './service-account-key.json';
 
-function App() {
+const ChatWidget = dynamic(
+  () => import('@blockspark/chat-widget').then((mod) => mod.default),
+  { ssr: false }
+);
+
+export default function ChatPage() {
+  const serviceAccountKey = process.env.NEXT_PUBLIC_SERVICE_ACCOUNT_KEY_JSON
+    ? JSON.parse(process.env.NEXT_PUBLIC_SERVICE_ACCOUNT_KEY_JSON)
+    : undefined;
+
   return (
     <ChatWidget
       dfProjectId="your-project-id"
@@ -108,65 +147,200 @@ function App() {
       dfAgentId="your-agent-id"
       serviceAccountKey={serviceAccountKey}
       languageCode="en"
-      title="💬 My Chat Assistant"
-      subtitle="How can I help you?"
-      welcomeTitle="👋 Welcome!"
-      welcomeMessage="I'm here to help you with any questions."
-      welcomeCta="Start chatting"
+      title="💬 BlockSpark AI Assistant"
+      subtitle="We're here to help"
+      welcomeTitle="👋 Welcome to Blockspark"
+      welcomeMessage="My name is BlockSpark AI Assistant and I'll guide you."
+      welcomeCta="💬 Click here to start chatting!"
       showWelcomePopup={true}
-      welcomePopupDelay={2000}
+      welcomePopupDelay={1500}
+      fallbackWelcomeMessage="Hello! I'm BlockSpark AI Assistant. How can I help you today?"
       inputPlaceholder="Type your message..."
-      emptyStateMessage="Hi! How can I help you today?"
+      emptyStateMessage="Hi! I'm BlockSpark AI Assistant. How can I help you today?"
       debug={false}
+      backendBaseUrl="http://localhost:8012"
+      backendWsUrl="ws://localhost:8012"
     />
   );
 }
 ```
 
-### Using Environment Variables
+**Important:** Do not expose raw service account keys in client-side code in production. Prefer a backend that returns short-lived tokens or use a proxy.
 
-You can configure the backend API URLs for Human Support Mode using environment variables. Create a `.env` file in the project root:
+### Vue 3
 
-```bash
-# .env file
-REACT_APP_BACKEND_BASE_URL=http://localhost:8012
-REACT_APP_BACKEND_WS_URL=ws://localhost:8012
+Use either the global plugin or the component directly.
+
+**Option A — Global plugin (e.g. `main.js` / `main.ts`):**
+
+```js
+import { createApp } from 'vue';
+import App from './App.vue';
+import BlockSparkChatWidget from '@blockspark/chat-widget/vue';
+import '@blockspark/chat-widget/dist/styles.css';
+
+const app = createApp(App);
+app.use(BlockSparkChatWidget); // registers <BlockSparkChatWidget>
+app.mount('#app');
 ```
 
-Or pass them as props:
+Then in any template (copy and replace the placeholder values):
+
+```vue
+<template>
+  <BlockSparkChatWidget
+    dfProjectId="your-project-id"
+    dfLocation="us-central1"
+    dfAgentId="your-agent-id"
+    :serviceAccountKey="serviceAccountKey"
+    languageCode="en"
+    title="💬 BlockSpark AI Assistant"
+    subtitle="We're here to help"
+    welcomeTitle="👋 Welcome to Blockspark"
+    welcomeMessage="My name is BlockSpark AI Assistant and I'll guide you."
+    welcomeCta="💬 Click here to start chatting!"
+    :showWelcomePopup="true"
+    :welcomePopupDelay="1500"
+    fallbackWelcomeMessage="Hello! I'm BlockSpark AI Assistant. How can I help you today?"
+    inputPlaceholder="Type your message..."
+    emptyStateMessage="Hi! I'm BlockSpark AI Assistant. How can I help you today?"
+    :debug="false"
+    backendBaseUrl="http://localhost:8012"
+    backendWsUrl="ws://localhost:8012"
+  />
+</template>
+```
 
-```tsx
-<ChatWidget
-  dfProjectId="your-project-id"
-  dfAgentId="your-agent-id"
-  serviceAccountKey={serviceAccountKey}
-  backendBaseUrl="http://your-backend-url:8012"
-  backendWsUrl="ws://your-backend-url:8012"
-/>
+**Option B — Component only:**
+
+```vue
+<script setup>
+import { BlockSparkChatWidgetVue } from '@blockspark/chat-widget/vue';
+import '@blockspark/chat-widget/dist/styles.css';
+
+import serviceAccountKey from './path/to/service-account-key.json';
+</script>
+
+<template>
+  <BlockSparkChatWidgetVue
+    dfProjectId="your-project-id"
+    dfLocation="us-central1"
+    dfAgentId="your-agent-id"
+    :serviceAccountKey="serviceAccountKey"
+    languageCode="en"
+    title="💬 BlockSpark AI Assistant"
+    subtitle="We're here to help"
+    welcomeTitle="👋 Welcome to Blockspark"
+    welcomeMessage="My name is BlockSpark AI Assistant and I'll guide you."
+    welcomeCta="💬 Click here to start chatting!"
+    :showWelcomePopup="true"
+    :welcomePopupDelay="1500"
+    fallbackWelcomeMessage="Hello! I'm BlockSpark AI Assistant. How can I help you today?"
+    inputPlaceholder="Type your message..."
+    emptyStateMessage="Hi! I'm BlockSpark AI Assistant. How can I help you today?"
+    :debug="false"
+    backendBaseUrl="http://localhost:8012"
+    backendWsUrl="ws://localhost:8012"
+  />
+</template>
 ```
 
-**Note**: Props take precedence over environment variables.
+### CDN (script tag, no build step)
+
+You can load the widget from a CDN and mount it with React (the widget is a React component). Load React, ReactDOM, the widget CSS, and the widget script, then render into a container.
+
+Replace `1.0.1` with the version you want (or use `latest` for the latest release).
+
+**Using unpkg:**
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <title>BlockSpark Chat Widget</title>
+  <!-- 1. React (required by the widget) -->
+  <script crossorigin src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
+  <script crossorigin src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
+  <!-- 2. Widget CSS -->
+  <link rel="stylesheet" href="https://unpkg.com/@blockspark/chat-widget@1.0.1/dist/styles.css" />
+</head>
+<body>
+  <div id="chat-root"></div>
+
+  <!-- 3. Widget script (UMD: exposes BlockSparkChatWidget) -->
+  <script src="https://unpkg.com/@blockspark/chat-widget@1.0.1/dist/index.js"></script>
+
+  <script>
+    (function () {
+      var container = document.getElementById('chat-root');
+      var React = window.React;
+      var ReactDOM = window.ReactDOM;
+      var ChatWidget = window.BlockSparkChatWidget;
+
+      var config = {
+        dfProjectId: 'your-project-id',
+        dfLocation: 'us-central1',
+        dfAgentId: 'your-agent-id',
+        serviceAccountKey: { /* your service account key object */ },
+        // accessToken: 'your-token',  // use instead of serviceAccountKey if you have a token
+        languageCode: 'en',
+        title: '💬 BlockSpark AI Assistant',
+        subtitle: "We're here to help",
+        welcomeTitle: '👋 Welcome to Blockspark',
+        welcomeMessage: "My name is BlockSpark AI Assistant and I'll guide you.",
+        welcomeCta: '💬 Click here to start chatting!',
+        showWelcomePopup: true,
+        welcomePopupDelay: 1500,
+        fallbackWelcomeMessage: "Hello! I'm BlockSpark AI Assistant. How can I help you today?",
+        inputPlaceholder: 'Type your message...',
+        emptyStateMessage: "Hi! I'm BlockSpark AI Assistant. How can I help you today?",
+        debug: false,
+        backendBaseUrl: 'http://localhost:8012',
+        backendWsUrl: 'ws://localhost:8012'
+      };
+
+      if (ReactDOM.createRoot) {
+        ReactDOM.createRoot(container).render(React.createElement(ChatWidget, config));
+      } else {
+        ReactDOM.render(React.createElement(ChatWidget, config), container);
+      }
+    })();
+  </script>
+</body>
+</html>
+```
 
-### Human Support Mode
+**Using jsDelivr:**
 
-The widget supports automatic handoff from bot to human agents. When Dialogflow returns `{"handoff": true}`, the widget will:
+Use the same structure and swap the CDN base URL:
 
-1. Switch from Bot Mode to Human Support Mode
-2. Create a support chat session
-3. Connect via WebSocket for real-time messaging
-4. Load message history
-5. Route messages to the backend API instead of Dialogflow
+- CSS: `https://cdn.jsdelivr.net/npm/@blockspark/chat-widget@1.0.1/dist/styles.css`
+- JS: `https://cdn.jsdelivr.net/npm/@blockspark/chat-widget@1.0.1/dist/index.js`
 
-The widget displays mode indicators and connection status in the chat header.
+**Notes for CDN:**
 
-### Import Types (TypeScript)
+- You must provide `serviceAccountKey` (or `accessToken`) in the config object. Do not hardcode real keys in production; use a backend or token endpoint.
+- Pin the version in the URL (e.g. `@1.0.1`) instead of `@latest` for stable behavior.
 
-```tsx
-import ChatWidget, { ChatWidgetProps, DialogflowConfig } from '@blockspark/chat-widget';
-```
+---
+
+## Human Support Mode
+
+The widget supports automatic handoff from bot to human agents. When Dialogflow returns `{"handoff": true}`, the widget will:
+
+1. Switch from Bot Mode to Human Support Mode  
+2. Create a support chat session  
+3. Connect via WebSocket for real-time messaging  
+4. Load message history  
+5. Route messages to the backend API instead of Dialogflow  
+
+The widget shows mode and connection status in the chat header.
 
 ## Props
 
+All props use **camelCase** in every framework (React, Next.js, Vue, CDN).
+
 | Prop | Type | Required | Default | Description |
 |------|------|----------|---------|-------------|
 | `dfProjectId` | `string` | Yes | - | Dialogflow project ID |
@@ -186,62 +360,57 @@ import ChatWidget, { ChatWidgetProps, DialogflowConfig } from '@blockspark/chat-
 | `inputPlaceholder` | `string` | No | `"Type your message..."` | Input field placeholder |
 | `emptyStateMessage` | `string` | No | `"Hi! I'm BlockSpark..."` | Empty state message |
 | `debug` | `boolean` | No | `false` | Enable debug logging |
-| `backendBaseUrl` | `string` | No | `process.env.REACT_APP_BACKEND_BASE_URL` or `"http://localhost:8012"` | Backend REST API base URL for Human Support Mode |
-| `backendWsUrl` | `string` | No | `process.env.REACT_APP_BACKEND_WS_URL` or `"ws://localhost:8012"` | Backend WebSocket URL for Human Support Mode |
+| `backendBaseUrl` | `string` | No | env or `"http://localhost:8012"` | Backend REST API base URL for Human Support Mode |
+| `backendWsUrl` | `string` | No | env or `"ws://localhost:8012"` | Backend WebSocket URL for Human Support Mode |
 
 \* Either `serviceAccountKey` or `accessToken` must be provided.
 
+## TypeScript
+
+```tsx
+import ChatWidget, { ChatWidgetProps, DialogflowConfig } from '@blockspark/chat-widget';
+```
+
 ## How It Works
 
-The widget connects **directly** to Dialogflow CX using the REST API - no backend required! 
+The widget talks **directly** to Dialogflow CX via the REST API (no custom backend required for basic use):
 
-1. **Authentication**: Uses Google Cloud service account key to generate OAuth2 access tokens
-2. **Session Management**: Creates and manages Dialogflow sessions automatically
-3. **Message Handling**: Sends messages directly to Dialogflow and displays responses
-4. **Rich Content**: Supports Dialogflow rich content (chips, cards, etc.)
+1. **Authentication** — Uses a Google Cloud service account key to obtain OAuth2 access tokens  
+2. **Sessions** — Creates and manages Dialogflow sessions  
+3. **Messages** — Sends user messages to Dialogflow and displays responses  
+4. **Rich content** — Supports Dialogflow rich content (chips, cards, etc.)
 
 ## Requirements
 
-- React 16.8.0 or higher
-- React DOM 16.8.0 or higher
-- Google Cloud service account with Dialogflow API enabled
-- Dialogflow CX agent
+- **React / Next.js**: React 16.8+ and React DOM  
+- **Vue**: Vue 3.x  
+- **CDN**: React 17 or 18 and React DOM loaded via script tags  
+- Google Cloud project with Dialogflow API enabled and a Dialogflow CX agent  
 
 ## Getting Your Service Account Key
 
-1. Go to [Google Cloud Console](https://console.cloud.google.com/)
-2. Select your project
-3. Navigate to **IAM & Admin** > **Service Accounts**
-4. Create a new service account or select an existing one
-5. Create a JSON key and download it
-6. Enable **Dialogflow API** for your project
-7. Grant the service account **Dialogflow API User** role
-
-## Security Warning ⚠️
+1. Open [Google Cloud Console](https://console.cloud.google.com/) and select your project  
+2. Go to **IAM & Admin** → **Service Accounts**  
+3. Create or select a service account and create a JSON key  
+4. Enable **Dialogflow API** for the project  
+5. Grant the service account the **Dialogflow API User** role  
 
-**Important**: Service account keys contain sensitive credentials. 
+## Security
 
-- **For Development**: You can import the key directly (as shown in examples)
-- **For Production**: 
-  - **DO NOT** expose service account keys in client-side code
-  - Use a backend proxy to handle authentication
-  - Or use OAuth2 flow to get access tokens securely
-  - Consider using restricted service account keys with minimal permissions
+- **Development**: You can import or pass the service account key in code for local testing  
+- **Production**:  
+  - **Do not** ship service account keys in client-side code or public HTML  
+  - Prefer a backend that issues short-lived tokens or proxies Dialogflow calls  
+  - Use restricted keys and minimal permissions where possible  
 
 ## Development
 
 ```bash
-# Install dependencies
 npm install
-
-# Build for production
-npm run build
-
-# Watch mode for development
-npm run dev
+npm run build    # production build
+npm run dev      # watch mode
 ```
 
 ## License
 
 MIT
-export NPM_TOKEN=your_token_here