@theonexai/chartsconnect-chat-widget 1.0.18

package/README.md

@@ -0,0 +1,270 @@
+# chartsconnect Chat Widget
+
+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
+
+### Option 1: Install from Local Path (Recommended for Development)
+
+```bash
+# In your website project directory
+npm install /path/to/chartsconnect-chat-widget
+# or
+npm install ../chartsconnect-chat-widget
+```
+
+### Option 2: Use npm link (For Development)
+
+```bash
+# In the chartsconnect-chat-widget directory
+npm link
+
+# In your website project directory
+npm link @chartsconnect/chat-widget
+```
+
+### Option 3: Publish to npm (For Production)
+
+```bash
+# Build the library first
+npm run build
+
+# Publish to npm (make sure you're logged in)
+npm publish
+```
+
+Then install in your project:
+```bash
+npm install @chartsconnect/chat-widget
+```
+
+## Usage
+
+### Vue.js 3
+
+```vue
+<template>
+  <ChatWidget
+    df-project-id="your-project-id"
+    df-agent-id="your-agent-id"
+    :service-account-key="serviceAccountKey"
+    backendBaseUrl="https://chartconnect.chartsconnect.in"
+    backendWsUrl="wss://chartconnect.chartsconnect.in"
+  />
+</template>
+
+<script setup>
+import ChatWidget from '@chartsconnect/chat-widget/vue';
+// ⚠️ REQUIRED: Import CSS separately
+import '@chartsconnect/chat-widget/styles';
+import serviceAccountKey from './credentials/dialogflow.json';
+</script>
+```
+
+**CSS Import Options:**
+- `import '@chartsconnect/chat-widget/styles'` (recommended)
+- `import '@chartsconnect/chat-widget/dist/styles.css'` (alternative)
+
+### Nuxt 3 / Vue.js 3 (Important: Use ClientOnly!)
+
+```vue
+<template>
+  <ClientOnly>
+    <ChatWidget
+      df-project-id="your-project-id"
+      df-agent-id="your-agent-id"
+      :service-account-key="serviceAccountKey"
+    />
+  </ClientOnly>
+</template>
+
+<script setup>
+import ChatWidget from '@chartsconnect/chat-widget/nuxt';
+import '@chartsconnect/chat-widget/styles';
+import serviceAccountKey from './credentials/dialogflow.json';
+</script>
+```
+
+**In `nuxt.config.ts`:**
+```typescript
+export default defineNuxtConfig({
+  css: ['@chartsconnect/chat-widget/dist/styles.css'],
+  
+  vite: {
+    optimizeDeps: {
+      exclude: ['@chartsconnect/chat-widget'],
+    },
+  },
+});
+```
+
+**⚠️ 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.
+
+**CSS Import Options:**
+- `import '@chartsconnect/chat-widget/styles'` (recommended - shorter path)
+- `import '@chartsconnect/chat-widget/dist/styles.css'` (alternative)
+
+### React/Next.js
+
+```tsx
+import ChatWidget from '@chartsconnect/chat-widget';
+import '@chartsconnect/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"
+    />
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `dfProjectId` | `string` | Yes | - | Dialogflow project ID |
+| `dfLocation` | `string` | No | `"us-central1"` | Dialogflow location |
+| `dfAgentId` | `string` | Yes | - | Dialogflow agent ID |
+| `serviceAccountKey` | `object` | Yes* | - | Google Cloud service account key JSON object |
+| `accessToken` | `string` | Yes* | - | Access token (alternative to serviceAccountKey) |
+| `languageCode` | `string` | No | `"en"` | Language code for Dialogflow |
+| `title` | `string` | No | `"💬 chartsconnect AI Assistant"` | Chat widget title |
+| `subtitle` | `string` | No | `"We're here to help"` | Chat widget subtitle |
+| `welcomeTitle` | `string` | No | `"👋 Welcome to chartsconnect"` | Welcome popup title |
+| `welcomeMessage` | `string` | No | `"My name is chartsconnect..."` | Welcome popup message |
+| `welcomeCta` | `string` | No | `"💬 Click here to start chatting!"` | Welcome popup CTA text |
+| `showWelcomePopup` | `boolean` | No | `true` | Whether to show welcome popup |
+| `welcomePopupDelay` | `number` | No | `1500` | Delay before showing welcome popup (ms) |
+| `fallbackWelcomeMessage` | `string` | No | `"Hello! I'm chartsconnect..."` | Fallback message if API fails |
+| `inputPlaceholder` | `string` | No | `"Type your message..."` | Input field placeholder |
+| `emptyStateMessage` | `string` | No | `"Hi! I'm chartsconnect..."` | Empty state message |
+| `debug` | `boolean` | No | `false` | Enable debug logging |
+| `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! 
+
+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.)
+5. **Human Handoff**: Automatically switches to human support mode when Dialogflow returns handoff signal
+
+## Requirements
+
+### 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
+
+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 ⚠️
+
+**Important**: Service account keys contain sensitive credentials. 
+
+- **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
+
+```bash
+# Install dependencies
+npm install
+
+# Build for production
+npm run build
+
+# Watch mode for development
+npm run dev
+```
+
+## Troubleshooting
+
+### Vue.js/Nuxt Issues
+
+**Widget not displaying?**
+- ✅ Make sure you imported the CSS: `import '@chartsconnect/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: ['@chartsconnect/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: ['@chartsconnect/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