@blockspark/chat-widget 1.0.1 → 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,106 +95,165 @@ 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');
 ```
 
-### Using Environment Variables
+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>
+```
 
-You can configure the backend API URLs for Human Support Mode using environment variables. Create a `.env` file in the project root:
+**Option B — Component only:**
 
-```bash
-# .env file
-REACT_APP_BACKEND_BASE_URL=http://localhost:8012
-REACT_APP_BACKEND_WS_URL=ws://localhost:8012
-```
+```vue
+<script setup>
+import { BlockSparkChatWidgetVue } from '@blockspark/chat-widget/vue';
+import '@blockspark/chat-widget/dist/styles.css';
 
-Or pass them as props:
+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>
+```
 
-```tsx
-<ChatWidget
-  dfProjectId="your-project-id"
-  dfAgentId="your-agent-id"
-  serviceAccountKey={serviceAccountKey}
-  backendBaseUrl="http://your-backend-url:8012"
-  backendWsUrl="ws://your-backend-url:8012"
-/>
+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>
 ```
 
-**Note**: Props take precedence over environment variables.
+**Using jsDelivr:**
 
-### Human Support Mode
+Use the same structure and swap the CDN base URL:
 
-The widget supports automatic handoff from bot to human agents. When Dialogflow returns `{"handoff": true}`, the widget will:
+- 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`
 
-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
+**Notes for CDN:**
 
-The widget displays mode indicators and connection status in the chat header.
+- 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.
 
-### Import Types (TypeScript)
+---
 
-```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
 
@@ -186,62 +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 | `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

package/dist/vue/ChatWidgetWrapper.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Vue 3 wrapper for the BlockSpark React ChatWidget.
+ * Mounts and unmounts the React component and forwards all props.
+ */
+export declare const BlockSparkChatWidgetVue: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    title: {
+        type: StringConstructor;
+        default: string;
+    };
+    subtitle: {
+        type: StringConstructor;
+        default: string;
+    };
+    welcomeTitle: {
+        type: StringConstructor;
+        default: string;
+    };
+    welcomeMessage: {
+        type: StringConstructor;
+        default: string;
+    };
+    welcomeCta: {
+        type: StringConstructor;
+        default: string;
+    };
+    showWelcomePopup: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    welcomePopupDelay: {
+        type: NumberConstructor;
+        default: number;
+    };
+    fallbackWelcomeMessage: {
+        type: StringConstructor;
+        default: string;
+    };
+    inputPlaceholder: {
+        type: StringConstructor;
+        default: string;
+    };
+    emptyStateMessage: {
+        type: StringConstructor;
+        default: string;
+    };
+    debug: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    dfProjectId: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    dfLocation: {
+        type: StringConstructor;
+        default: string;
+    };
+    dfAgentId: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    serviceAccountKey: {
+        type: ObjectConstructor;
+        default: undefined;
+    };
+    accessToken: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    languageCode: {
+        type: StringConstructor;
+        default: string;
+    };
+    backendBaseUrl: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    backendWsUrl: {
+        type: StringConstructor;
+        default: undefined;
+    };
+}>, {
+    containerRef: import("vue").Ref<HTMLElement | null, HTMLElement | null>;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    title: {
+        type: StringConstructor;
+        default: string;
+    };
+    subtitle: {
+        type: StringConstructor;
+        default: string;
+    };
+    welcomeTitle: {
+        type: StringConstructor;
+        default: string;
+    };
+    welcomeMessage: {
+        type: StringConstructor;
+        default: string;
+    };
+    welcomeCta: {
+        type: StringConstructor;
+        default: string;
+    };
+    showWelcomePopup: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    welcomePopupDelay: {
+        type: NumberConstructor;
+        default: number;
+    };
+    fallbackWelcomeMessage: {
+        type: StringConstructor;
+        default: string;
+    };
+    inputPlaceholder: {
+        type: StringConstructor;
+        default: string;
+    };
+    emptyStateMessage: {
+        type: StringConstructor;
+        default: string;
+    };
+    debug: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    dfProjectId: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    dfLocation: {
+        type: StringConstructor;
+        default: string;
+    };
+    dfAgentId: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    serviceAccountKey: {
+        type: ObjectConstructor;
+        default: undefined;
+    };
+    accessToken: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    languageCode: {
+        type: StringConstructor;
+        default: string;
+    };
+    backendBaseUrl: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    backendWsUrl: {
+        type: StringConstructor;
+        default: undefined;
+    };
+}>> & Readonly<{}>, {
+    title: string;
+    subtitle: string;
+    welcomeTitle: string;
+    welcomeMessage: string;
+    welcomeCta: string;
+    showWelcomePopup: boolean;
+    welcomePopupDelay: number;
+    fallbackWelcomeMessage: string;
+    inputPlaceholder: string;
+    emptyStateMessage: string;
+    debug: boolean;
+    dfProjectId: string;
+    dfLocation: string;
+    dfAgentId: string;
+    serviceAccountKey: Record<string, any>;
+    accessToken: string;
+    languageCode: string;
+    backendBaseUrl: string;
+    backendWsUrl: string;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+//# sourceMappingURL=ChatWidgetWrapper.d.ts.map

package/dist/vue/ChatWidgetWrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChatWidgetWrapper.d.ts","sourceRoot":"","sources":["../../src/vue/ChatWidgetWrapper.ts"],"names":[],"mappings":"AAcA;;;GAGG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4EAyFlC,CAAC"}