@blockspark/chat-widget 1.0.3 → 1.0.5

package/README.md

@@ -1,346 +1,201 @@
 # BlockSpark Chat Widget
 
-A reusable chat widget for **React**, **Next.js**, **Vue 3**, and **vanilla HTML (CDN)** that connects directly with Dialogflow CX — no backend API required.
+A reusable React chat widget component that connects directly with Dialogflow CX - no backend API required!
 
 ## Installation
 
-Install from npm (for React, Next.js, or Vue projects):
+### Option 1: Install from Local Path (Recommended for Development)
 
 ```bash
-npm install @blockspark/chat-widget
+# In your website project directory
+npm install /path/to/blockspark-chat-widget
+# or
+npm install ../blockspark-chat-widget
 ```
 
-- **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.
+### Option 2: Use npm link (For Development)
 
 ```bash
-# React or Next.js
-npm install @blockspark/chat-widget react react-dom
+# In the blockspark-chat-widget directory
+npm link
 
-# Vue 3 only
-npm install @blockspark/chat-widget vue
+# In your website project directory
+npm link @blockspark/chat-widget
 ```
 
-**Development / local testing:**
+### Option 3: Publish to npm (For Production)
 
 ```bash
-# 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
+# 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 @blockspark/chat-widget
+```
 
 ## Usage
 
-Use **camelCase** for all props in every environment (React, Next.js, Vue, and CDN). Examples: `dfProjectId`, `serviceAccountKey`, `languageCode`.
-
----
+### Vue.js Usage (Quick Start)
 
-### React
+```bash
+# Install
+npm install @blockspark/chat-widget
+```
 
-Import the component and the default styles, then render with your config. Copy the props below and replace the placeholder values with yours.
+```vue
+<template>
+  <ChatWidget
+    :df-project-id="'your-project-id'"
+    :df-agent-id="'your-agent-id'"
+    :service-account-key="serviceAccountKey"
+  />
+</template>
 
-```tsx
-import ChatWidget from '@blockspark/chat-widget';
+<script setup>
+import ChatWidget from '@blockspark/chat-widget/vue';
 import '@blockspark/chat-widget/dist/styles.css';
-
-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}
-      // 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"
-    />
-  );
-}
+import serviceAccountKey from './service-account-key.json';
+</script>
 ```
 
-### Next.js
+**📚 For detailed Vue.js setup guide, see [VUE_INSTALLATION_GUIDE.md](./VUE_INSTALLATION_GUIDE.md)**
 
-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+):**
+### React/Next.js Usage
 
-```tsx
-'use client';
+### Basic Usage
 
-import dynamic from 'next/dynamic';
+```tsx
+import ChatWidget from '@blockspark/chat-widget';
 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 */
-  };
+// Load your Google Cloud service account key
+import serviceAccountKey from './path/to/service-account-key.json';
 
+function App() {
   return (
     <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>
   );
 }
 ```
 
-**Pages Router:**
+### Using Access Token (Alternative)
+
+If you prefer to manage authentication yourself:
 
 ```tsx
-import dynamic from 'next/dynamic';
+import ChatWidget from '@blockspark/chat-widget';
 import '@blockspark/chat-widget/dist/styles.css';
 
-const ChatWidget = dynamic(
-  () => import('@blockspark/chat-widget').then((mod) => mod.default),
-  { ssr: false }
-);
+function App() {
+  const [accessToken, setAccessToken] = useState<string>('');
 
-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;
+  // 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"
-      serviceAccountKey={serviceAccountKey}
+      accessToken={accessToken}
       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"
     />
   );
 }
 ```
 
-**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.
-
-### Vue 3
-
-Use either the global plugin or the component directly.
+### With Custom Configuration
 
-**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';
+```tsx
+import ChatWidget from '@blockspark/chat-widget';
 import '@blockspark/chat-widget/dist/styles.css';
+import serviceAccountKey from './service-account-key.json';
 
-const app = createApp(App);
-app.use(BlockSparkChatWidget); // registers <BlockSparkChatWidget>
-app.mount('#app');
-```
-
-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>
+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}
+    />
+  );
+}
 ```
 
-**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>
+### Using Environment Variables
 
-<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>
-```
+You can configure the backend API URLs for Human Support Mode using environment variables. Create a `.env` file in the project root:
 
-### 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>
+```bash
+# .env file
+REACT_APP_BACKEND_BASE_URL=http://localhost:8012
+REACT_APP_BACKEND_WS_URL=ws://localhost:8012
 ```
 
-**Using jsDelivr:**
+Or pass them as props:
 
-Use the same structure and swap the CDN base URL:
+```tsx
+<ChatWidget
+  dfProjectId="your-project-id"
+  dfAgentId="your-agent-id"
+  serviceAccountKey={serviceAccountKey}
+  backendBaseUrl="http://your-backend-url:8012"
+  backendWsUrl="ws://your-backend-url:8012"
+/>
+```
 
-- 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`
+**Note**: Props take precedence over environment variables.
 
-**Notes for CDN:**
+### Human Support Mode
 
-- 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.
+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
 
-## Human Support Mode
+The widget displays mode indicators and connection status in the chat header.
 
-The widget supports automatic handoff from bot to human agents. When Dialogflow returns `{"handoff": true}`, the widget will:
+### Import Types (TypeScript)
 
-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.
+```tsx
+import ChatWidget, { ChatWidgetProps, DialogflowConfig } from '@blockspark/chat-widget';
+```
 
 ## Props
 
-All props use **camelCase** in every framework (React, Next.js, Vue, CDN).
-
 | Prop | Type | Required | Default | Description |
 |------|------|----------|---------|-------------|
 | `dfProjectId` | `string` | Yes | - | Dialogflow project ID |
@@ -360,57 +215,62 @@ All props use **camelCase** in every framework (React, Next.js, Vue, CDN).
 | `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 |
+| `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 |
 
 \* Either `serviceAccountKey` or `accessToken` must be provided.
 
-## TypeScript
-
-```tsx
-import ChatWidget, { ChatWidgetProps, DialogflowConfig } from '@blockspark/chat-widget';
-```
-
 ## How It Works
 
-The widget talks **directly** to Dialogflow CX via the REST API (no custom backend required for basic use):
+The widget connects **directly** to Dialogflow CX using the REST API - no backend required! 
 
-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.)
+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.)
 
 ## Requirements
 
-- **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  
+- React 16.8.0 or higher
+- React DOM 16.8.0 or higher
+- Google Cloud service account with Dialogflow API enabled
+- Dialogflow CX agent
 
 ## Getting Your Service Account Key
 
-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  
+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
+## Security Warning ⚠️
 
-- **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  
+**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
-npm run build    # production build
-npm run dev      # watch mode
+
+# Build for production
+npm run build
+
+# Watch mode for development
+npm run dev
 ```
 
 ## License
 
 MIT
+export NPM_TOKEN=your_token_here

package/dist/adapters/vue/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Vue Adapter Entry Point
+ * Supports Vue 2.7+ and Vue 3.x
+ */
+export { default } from './ChatWidget.vue';
+export { default as ChatWidget } from './ChatWidget.vue';
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/vue/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adapters/vue/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC3C,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/adapters/vue/useChatMode.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Vue Composable for Chat Mode Management
+ * Equivalent to React's useChatMode hook
+ */
+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;
+}
+/**
+ * Vue composable to manage chat mode (BOT or HUMAN)
+ */
+export declare function useChatMode(): UseChatModeReturn;
+//# sourceMappingURL=useChatMode.d.ts.map

package/dist/adapters/vue/useChatMode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useChatMode.d.ts","sourceRoot":"","sources":["../../../src/adapters/vue/useChatMode.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAEpE,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,CAqF/C"}