@blockspark/chat-widget 1.0.8 → 1.0.9

package/README.md

@@ -1,6 +1,8 @@
 # BlockSpark Chat Widget
 
-A reusable React chat widget component that connects directly with Dialogflow CX - no backend API required!
+A universal JavaScript chat widget library that connects directly with Dialogflow CX - no backend API required!
+
+**Supports:** React, Next.js, Vue.js, Nuxt 3, Vite, and Vanilla JavaScript
 
 ## Installation
 
@@ -40,89 +42,71 @@ npm install @blockspark/chat-widget
 
 ## Usage
 
-### Vue.js Usage (Quick Start)
-
-```bash
-# Install
-npm install @blockspark/chat-widget
-```
+### Vue.js 3
 
 ```vue
 <template>
   <ChatWidget
-    :df-project-id="'your-project-id'"
-    :df-agent-id="'your-agent-id'"
+    df-project-id="your-project-id"
+    df-agent-id="your-agent-id"
     :service-account-key="serviceAccountKey"
+    backendBaseUrl="https://chartconnect.blockspark.in"
+    backendWsUrl="wss://chartconnect.blockspark.in"
   />
 </template>
 
 <script setup>
 import ChatWidget from '@blockspark/chat-widget/vue';
-import '@blockspark/chat-widget/dist/styles.css';
-import serviceAccountKey from './service-account-key.json';
+// ⚠️ REQUIRED: Import CSS separately
+import '@blockspark/chat-widget/styles';
+import serviceAccountKey from './credentials/dialogflow.json';
 </script>
 ```
 
-**📚 For detailed Vue.js setup guide, see [VUE_INSTALLATION_GUIDE.md](./VUE_INSTALLATION_GUIDE.md)**
-
----
-
-### React/Next.js Usage
+**CSS Import Options:**
+- `import '@blockspark/chat-widget/styles'` (recommended)
+- `import '@blockspark/chat-widget/dist/styles.css'` (alternative)
 
-### Basic Usage
+### Nuxt 3 / Vue.js 3 (Important: Use ClientOnly!)
 
-```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';
+```vue
+<template>
+  <ClientOnly>
+    <ChatWidget
+      df-project-id="your-project-id"
+      df-agent-id="your-agent-id"
+      :service-account-key="serviceAccountKey"
+    />
+  </ClientOnly>
+</template>
 
-function App() {
-  return (
-    <div>
-      <ChatWidget
-        dfProjectId="your-project-id"
-        dfLocation="us-central1"
-        dfAgentId="your-agent-id"
-        serviceAccountKey={serviceAccountKey}
-        languageCode="en"
-      />
-    </div>
-  );
-}
+<script setup>
+import ChatWidget from '@blockspark/chat-widget/nuxt';
+import '@blockspark/chat-widget/styles';
+import serviceAccountKey from './credentials/dialogflow.json';
+</script>
 ```
 
-### Using Access Token (Alternative)
-
-If you prefer to manage authentication yourself:
+**In `nuxt.config.ts`:**
+```typescript
+export default defineNuxtConfig({
+  css: ['@blockspark/chat-widget/dist/styles.css'],
+  
+  vite: {
+    optimizeDeps: {
+      exclude: ['@blockspark/chat-widget'],
+    },
+  },
+});
+```
 
-```tsx
-import ChatWidget from '@blockspark/chat-widget';
-import '@blockspark/chat-widget/dist/styles.css';
+**⚠️ CRITICAL for Nuxt:** The component MUST be wrapped in `<ClientOnly>` because it uses browser-only APIs (`localStorage`, `window`, `WebSocket`) that don't exist during SSR.
 
-function App() {
-  const [accessToken, setAccessToken] = useState<string>('');
+**CSS Import Options:**
+- `import '@blockspark/chat-widget/styles'` (recommended - shorter path)
+- `import '@blockspark/chat-widget/dist/styles.css'` (alternative)
 
-  // Get access token from your backend or OAuth flow
-  useEffect(() => {
-    // Your token fetching logic here
-    fetchAccessToken().then(setAccessToken);
-  }, []);
-
-  return (
-    <ChatWidget
-      dfProjectId="your-project-id"
-      dfLocation="us-central1"
-      dfAgentId="your-agent-id"
-      accessToken={accessToken}
-      languageCode="en"
-    />
-  );
-}
-```
-
-### With Custom Configuration
+### React/Next.js
 
 ```tsx
 import ChatWidget from '@blockspark/chat-widget';
@@ -137,63 +121,11 @@ 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"
-      showWelcomePopup={true}
-      welcomePopupDelay={2000}
-      inputPlaceholder="Type your message..."
-      emptyStateMessage="Hi! How can I help you today?"
-      debug={false}
     />
   );
 }
 ```
 
-### Using Environment Variables
-
-You can configure the backend API URLs for Human Support Mode using environment variables. Create a `.env` file in the project root:
-
-```bash
-# .env file
-REACT_APP_BACKEND_BASE_URL=http://localhost:8012
-REACT_APP_BACKEND_WS_URL=ws://localhost:8012
-```
-
-Or pass them as props:
-
-```tsx
-<ChatWidget
-  dfProjectId="your-project-id"
-  dfAgentId="your-agent-id"
-  serviceAccountKey={serviceAccountKey}
-  backendBaseUrl="http://your-backend-url:8012"
-  backendWsUrl="ws://your-backend-url:8012"
-/>
-```
-
-**Note**: Props take precedence over environment variables.
-
-### 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 displays mode indicators and connection status in the chat header.
-
-### Import Types (TypeScript)
-
-```tsx
-import ChatWidget, { ChatWidgetProps, DialogflowConfig } from '@blockspark/chat-widget';
-```
-
 ## Props
 
 | Prop | Type | Required | Default | Description |
@@ -215,11 +147,22 @@ 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 | `"http://localhost:8012"` | Backend REST API base URL for Human Support Mode |
+| `backendWsUrl` | `string` | No | `"ws://localhost:8012"` | Backend WebSocket URL for Human Support Mode |
 
 \* Either `serviceAccountKey` or `accessToken` must be provided.
 
+## Features
+
+- ✅ **Direct Dialogflow CX Integration** - No backend required
+- ✅ **Human Handoff Support** - Automatic transition from bot to human agents
+- ✅ **Rich Content** - Supports Dialogflow chips, cards, and more
+- ✅ **Real-time Messaging** - WebSocket support for human agents
+- ✅ **SSR Compatible** - Works with Next.js and Nuxt 3 (with ClientOnly wrapper)
+- ✅ **Framework Agnostic** - Same UI across React and Vue
+- ✅ **TypeScript Support** - Full type definitions included
+- ✅ **Tree-shakeable** - Only import what you need
+
 ## How It Works
 
 The widget connects **directly** to Dialogflow CX using the REST API - no backend required! 
@@ -228,13 +171,18 @@ The widget connects **directly** to Dialogflow CX using the REST API - no backen
 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.)
+5. **Human Handoff**: Automatically switches to human support mode when Dialogflow returns handoff signal
 
 ## 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
+### For React/Next.js
+- React 16.8.0 or higher (peer dependency)
+- React DOM 16.8.0 or higher (peer dependency)
+
+### For Vue.js/Nuxt
+- Vue 3.0.0 or higher (peer dependency)
+
+**Note:** Peer dependencies are optional - install only what you need for your framework.
 
 ## Getting Your Service Account Key
 
@@ -270,7 +218,53 @@ npm run build
 npm run dev
 ```
 
+## Troubleshooting
+
+### Vue.js/Nuxt Issues
+
+**Widget not displaying?**
+- ✅ Make sure you imported the CSS: `import '@blockspark/chat-widget/styles'`
+- ✅ For Nuxt: Wrap in `<ClientOnly>` component
+- ✅ For Nuxt: Add CSS to `nuxt.config.ts` and exclude from optimization
+
+**Vue warnings about attributes?**
+- ✅ This is fixed in the latest version
+- ✅ Ensure you're using the latest package version
+
+**Nuxt vite-node errors?**
+- ✅ Wrap component in `<ClientOnly>`
+- ✅ Add to `nuxt.config.ts`:
+  ```ts
+  vite: {
+    optimizeDeps: {
+      exclude: ['@blockspark/chat-widget'],
+    },
+  }
+  ```
+- ✅ Clear cache: `rm -rf .nuxt node_modules/.vite`
+
+**504 Outdated Optimize Dep error?**
+- ✅ Clear Vite cache: `rm -rf node_modules/.vite && npm run dev`
+- ✅ Or add to `vite.config.ts`:
+  ```ts
+  optimizeDeps: {
+    exclude: ['@blockspark/chat-widget'],
+  }
+  ```
+
+### General Issues
+
+**Chat not opening?**
+- ✅ Check CSS is imported
+- ✅ Verify Dialogflow config is provided
+- ✅ Enable debug mode: `:debug="true"` or `debug={true}` to see console logs
+
+**Dialogflow errors?**
+- ✅ Verify service account key is valid
+- ✅ Check Dialogflow API is enabled
+- ✅ Ensure service account has Dialogflow API User role
+- ✅ Verify project ID, location, and agent ID are correct
+
 ## License
 
-MIT
-export NPM_TOKEN=your_token_here
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@blockspark/chat-widget",
-    "version": "1.0.8",
+    "version": "1.0.9",
     "description": "BlockSpark AI Chat Widget - Universal JavaScript library supporting React, Next.js, Vue, Nuxt, and Vite",
     "main": "./dist/index.cjs.js",
     "module": "./dist/index.esm.js",