@blockspark/chat-widget 1.0.0 → 1.0.2

package/README.md

@@ -1,57 +1,88 @@
 # 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
+### React
+
+Import the component and the default styles, then render with your config.
 
 ```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 (
+    <ChatWidget
+      dfProjectId="your-project-id"
+      dfLocation="us-central1"
+      dfAgentId="your-agent-id"
+      serviceAccountKey={serviceAccountKey}
+      languageCode="en"
+      title="💬 My Chat"
+      subtitle="We're here to help"
+    />
+  );
+}
+```
+
+### Next.js
+
+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
+'use client';
+
+import dynamic from 'next/dynamic';
+import '@blockspark/chat-widget/dist/styles.css';
+
+const ChatWidget = dynamic(
+  () => import('@blockspark/chat-widget').then((mod) => mod.default),
+  { ssr: false }
+);
+
+export default function Page() {
+  const serviceAccountKey = {
+    /* your key object, or load from env/server */
+  };
+
   return (
     <div>
+      <h1>My Page</h1>
       <ChatWidget
         dfProjectId="your-project-id"
         dfLocation="us-central1"
@@ -64,71 +95,166 @@ function App() {
 }
 ```
 
-### Using Access Token (Alternative)
-
-If you prefer to manage authentication yourself:
+**Pages Router:**
 
 ```tsx
-import ChatWidget from '@blockspark/chat-widget';
+import dynamic from 'next/dynamic';
 import '@blockspark/chat-widget/dist/styles.css';
 
-function App() {
-  const [accessToken, setAccessToken] = useState<string>('');
-
-  // Get access token from your backend or OAuth flow
-  useEffect(() => {
-    // Your token fetching logic here
-    fetchAccessToken().then(setAccessToken);
-  }, []);
+const ChatWidget = dynamic(
+  () => import('@blockspark/chat-widget').then((mod) => mod.default),
+  { ssr: false }
+);
 
+export default function ChatPage() {
   return (
     <ChatWidget
       dfProjectId="your-project-id"
       dfLocation="us-central1"
       dfAgentId="your-agent-id"
-      accessToken={accessToken}
+      serviceAccountKey={process.env.NEXT_PUBLIC_SERVICE_ACCOUNT_KEY_JSON ? JSON.parse(process.env.NEXT_PUBLIC_SERVICE_ACCOUNT_KEY_JSON) : undefined}
       languageCode="en"
     />
   );
 }
 ```
 
-### With Custom Configuration
+**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.
 
-```tsx
-import ChatWidget from '@blockspark/chat-widget';
+### Vue 3
+
+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';
-import serviceAccountKey from './service-account-key.json';
 
-function App() {
-  return (
-    <ChatWidget
-      dfProjectId="your-project-id"
-      dfLocation="us-central1"
-      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"
-      showWelcomePopup={true}
-      welcomePopupDelay={2000}
-      inputPlaceholder="Type your message..."
-      emptyStateMessage="Hi! How can I help you today?"
-      debug={false}
-    />
-  );
-}
+const app = createApp(App);
+app.use(BlockSparkChatWidget); // registers <BlockSparkChatWidget>
+app.mount('#app');
 ```
 
-### Import Types (TypeScript)
+Then in any template:
+
+```vue
+<template>
+  <BlockSparkChatWidget
+    df-project-id="your-project-id"
+    df-location="us-central1"
+    df-agent-id="your-agent-id"
+    :service-account-key="serviceAccountKey"
+    language-code="en"
+  />
+</template>
+```
 
-```tsx
-import ChatWidget, { ChatWidgetProps, DialogflowConfig } from '@blockspark/chat-widget';
+**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
+    df-project-id="your-project-id"
+    df-location="us-central1"
+    df-agent-id="your-agent-id"
+    :service-account-key="serviceAccountKey"
+    language-code="en"
+  />
+</template>
+```
+
+Use **kebab-case** for props in templates (e.g. `df-project-id`, `service-account-key`). All props from the Props table below are supported.
+
+### 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 */ },
+        languageCode: 'en',
+        title: '💬 BlockSpark AI Assistant',
+        subtitle: "We're here to help"
+      };
+
+      if (ReactDOM.createRoot) {
+        ReactDOM.createRoot(container).render(React.createElement(ChatWidget, config));
+      } else {
+        ReactDOM.render(React.createElement(ChatWidget, config), container);
+      }
+    })();
+  </script>
+</body>
+</html>
 ```
 
+**Using jsDelivr:**
+
+Use the same structure and swap the CDN base URL:
+
+- 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`
+
+**Notes for CDN:**
+
+- 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.
+
+---
+
+## 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
 
 | Prop | Type | Required | Default | Description |
@@ -150,60 +276,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 | 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

package/dist/components/ChatWidget.d.ts

@@ -34,6 +34,10 @@ export interface ChatWidgetProps {
     accessToken?: string;
     /** Language code for Dialogflow */
     languageCode?: string;
+    /** Backend API base URL (default: http://localhost:8012) */
+    backendBaseUrl?: string;
+    /** WebSocket URL (default: ws://localhost:8012) */
+    backendWsUrl?: string;
 }
-export default function ChatWidget({ title, subtitle, welcomeTitle, welcomeMessage, welcomeCta, showWelcomePopup: enableWelcomePopup, welcomePopupDelay, fallbackWelcomeMessage, inputPlaceholder, emptyStateMessage, debug, dfProjectId, dfLocation, dfAgentId, serviceAccountKey, accessToken, languageCode, }: ChatWidgetProps): import("react/jsx-runtime").JSX.Element;
+export default function ChatWidget({ title, subtitle, welcomeTitle, welcomeMessage, welcomeCta, showWelcomePopup: enableWelcomePopup, welcomePopupDelay, fallbackWelcomeMessage, inputPlaceholder, emptyStateMessage, debug, dfProjectId, dfLocation, dfAgentId, serviceAccountKey, accessToken, languageCode, backendBaseUrl, backendWsUrl, }: ChatWidgetProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=ChatWidget.d.ts.map

package/dist/components/ChatWidget.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ChatWidget.d.ts","sourceRoot":"","sources":["../../src/components/ChatWidget.tsx"],"names":[],"mappings":"AAQA,OAAO,0BAA0B,CAAC;AAsBlC,MAAM,WAAW,eAAe;IAC9B,uCAAuC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0BAA0B;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4BAA4B;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,6BAA6B;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wCAAwC;IACxC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,yDAAyD;IACzD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,4CAA4C;IAC5C,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,uCAAuC;IACvC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iCAAiC;IACjC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mCAAmC;IACnC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,4BAA4B;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0BAA0B;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,iBAAiB,CAAC,EAAE,GAAG,CAAC;IACxB,sDAAsD;IACtD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mCAAmC;IACnC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,CAAC,OAAO,UAAU,UAAU,CAAC,EACjC,KAAoC,EACpC,QAA+B,EAC/B,YAAyC,EACzC,cAAyE,EACzE,UAA+C,EAC/C,gBAAgB,EAAE,kBAAyB,EAC3C,iBAAwB,EACxB,sBAAwF,EACxF,gBAAyC,EACzC,iBAAgF,EAChF,KAAa,EACb,WAAW,EACX,UAA0B,EAC1B,SAAS,EACT,iBAAiB,EACjB,WAAW,EACX,YAAmB,GACpB,EAAE,eAAe,2CA6bjB"}
+{"version":3,"file":"ChatWidget.d.ts","sourceRoot":"","sources":["../../src/components/ChatWidget.tsx"],"names":[],"mappings":"AAWA,OAAO,0BAA0B,CAAC;AAsBlC,MAAM,WAAW,eAAe;IAC9B,uCAAuC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0BAA0B;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4BAA4B;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,6BAA6B;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wCAAwC;IACxC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,yDAAyD;IACzD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,4CAA4C;IAC5C,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,uCAAuC;IACvC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iCAAiC;IACjC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mCAAmC;IACnC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,4BAA4B;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gDAAgD;IAChD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0BAA0B;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,iBAAiB,CAAC,EAAE,GAAG,CAAC;IACxB,sDAAsD;IACtD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mCAAmC;IACnC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mDAAmD;IACnD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,CAAC,OAAO,UAAU,UAAU,CAAC,EACjC,KAAoC,EACpC,QAA+B,EAC/B,YAAyC,EACzC,cAAyE,EACzE,UAA+C,EAC/C,gBAAgB,EAAE,kBAAyB,EAC3C,iBAAwB,EACxB,sBAAwF,EACxF,gBAAyC,EACzC,iBAAgF,EAChF,KAAa,EACb,WAAW,EACX,UAA0B,EAC1B,SAAS,EACT,iBAAiB,EACjB,WAAW,EACX,YAAmB,EACnB,cAAc,EACd,YAAY,GACb,EAAE,eAAe,2CA03CjB"}

package/dist/hooks/useChatMode.d.ts

@@ -0,0 +1,17 @@
+import type { ChatResponse } from "../services/dialogflowClient";
+export type ChatMode = "BOT" | "HUMAN";
+export interface UseChatModeReturn {
+    currentMode: ChatMode;
+    switchToHumanMode: () => void;
+    switchToBotMode: () => void;
+    isHandoffTriggered: (dialogflowResponse: ChatResponse) => boolean;
+    chatId: string | null;
+    sessionId: string | null;
+    setChatId: (id: string | null) => void;
+    setSessionId: (id: string | null) => void;
+}
+/**
+ * Hook to manage chat mode (BOT or HUMAN)
+ */
+export declare function useChatMode(): UseChatModeReturn;
+//# sourceMappingURL=useChatMode.d.ts.map

package/dist/hooks/useChatMode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useChatMode.d.ts","sourceRoot":"","sources":["../../src/hooks/useChatMode.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAEjE,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,OAAO,CAAC;AAMvC,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,QAAQ,CAAC;IACtB,iBAAiB,EAAE,MAAM,IAAI,CAAC;IAC9B,eAAe,EAAE,MAAM,IAAI,CAAC;IAC5B,kBAAkB,EAAE,CAAC,kBAAkB,EAAE,YAAY,KAAK,OAAO,CAAC;IAClE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,SAAS,EAAE,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IACvC,YAAY,EAAE,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;CAC3C;AAED;;GAEG;AACH,wBAAgB,WAAW,IAAI,iBAAiB,CAmF/C"}