@data-netmonk/mona-chat-widget 2.1.37 → 2.3.0

package/README.md

@@ -2,6 +2,83 @@
 
 Chat widget package developed by Netmonk data & solution team to be imported in Netmonk products
 
+---
+
+### Recent Updates & Breaking Changes
+
+---
+
+**Latest Version Changes:**
+
+⚠️ **Breaking Changes:**
+1. **Removed `type` and `agentType` props** - These parameters are no longer used and have been removed from all components
+2. **Renamed `botServerUrl` to `webhookUrl`** - For better clarity and consistency
+3. **`webhookUrl` is now required** - Must be provided as a prop
+4. **`authUrl` and `username` are now direct props** - No longer part of `data` prop for better clarity and type safety
+5. **`userId` is now optional** - Widget automatically generates visitor ID for guest users via browser fingerprinting when `userId` is not provided
+
+✨ **New Features:**
+1. **Guest user support** - Users can chat without logging in
+   - Automatic visitor ID generation using browser fingerprinting (FingerprintJS + SHA256)
+   - `auth: false` flag automatically added to API requests for guest users
+   - Persistent sessions across page reloads for anonymous visitors
+2. **Authentication support** - Automatic token management with refresh on 401 errors
+   - Pass `authUrl` as a direct prop
+   - Widget handles token lifecycle automatically
+3. **Enhanced user authentication handling** - Smart detection of authenticated vs guest users
+   - Compares `userId` with visitor ID to determine authentication status
+   - Automatic `auth` flag management in all API requests
+4. **Enhanced data prop** - Support for custom variables passed to backend via `data` prop
+5. **Improved error handling** - Better fallback mechanisms and error messages
+6. **Direct `username` prop** - Pass username as a top-level prop instead of in data string
+
+📝 **Migration Guide:**
+```jsx
+// Old usage (deprecated)
+<ChatWidget 
+  userId="user123"
+  sourceId="source456"
+  type="prime"
+  botServerUrl="https://api.example.com"
+/>
+
+// Previous version (with data prop)
+<ChatWidget 
+  userId="user123"
+  sourceId="source456"
+  webhookUrl="https://api.example.com/webhook"
+  data="authUrl=https://api.example.com/login/chatwidget~username=John"
+/>
+
+// New usage - Authenticated user (current - recommended)
+<ChatWidget 
+  userId="user123"
+  sourceId="source456"
+  webhookUrl="https://api.example.com/webhook"
+  authUrl="https://api.example.com/login/chatwidget"
+  username="John"
+  data="email=john@example.com~phone=+1234567890"
+/>
+
+// New usage - Guest user (without login)
+<ChatWidget 
+  sourceId="source456"
+  webhookUrl="https://api.example.com/webhook"
+  username="Guest"
+/>
+// Widget automatically generates visitor ID and adds auth: false flag
+
+// New usage - Conditional (handles both logged-in and guest users)
+<ChatWidget 
+  userId={currentUser?.id}  // undefined for guests
+  sourceId="source456"
+  webhookUrl="https://api.example.com/webhook"
+  username={currentUser?.name || "Guest"}
+/>
+```
+
+---
+
 ## 🚅 Quick start
 
 ### Prerequisites
@@ -10,7 +87,7 @@ Chat widget package developed by Netmonk data & solution team to be imported in
 
 1. Install dependencies
    ```
-   npm install
+   npm install --legacy-peer-deps
    ```
 2. Copy .env.example
    ```
@@ -79,7 +156,7 @@ For responses with buttons:
 
 ---
 
-1. **How to run Storybook locally** (access at http://localhost:6006)
+1. **How to run Storybook locally** (access at http://localhost:5177)
 
    ```
    npm run storybook
@@ -165,10 +242,9 @@ For responses with buttons:
    function App() {
      return (
        <ChatWidget 
-         type="prime"
          userId="user123" 
          sourceId="691e1b5952068ff7aaeccffc9"
-         botServerUrl="https://your-backend-url.com"
+         webhookUrl="https://your-backend-url.com"
        />
      );
    }
@@ -184,22 +260,17 @@ For responses with buttons:
 
 | Prop | Type | Description |
 |------|------|-------------|
-| `userId` | `string` | **Required.** Unique identifier for the user |
 | `sourceId` | `string` | **Required.** Source/channel identifier for the chat |
-
-#### Dynamic Data Prop (NEW!)
-| Prop | Type | Description |
-|------|------|-------------|
-| `data` | `string` | URL-encoded config string (see advanced usage below) |
-
+| `webhookUrl` | `string` | **Required.** Backend webhook URL |
 
 #### Optional Props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `type` | `"prime" \| "hi"` | `"hi"` | Agent type for multi-agent system |
-| `botServerUrl` | `string` | - | Backend API URL (falls back to env vars if not provided) |
-| `data` | `string` | - | URL-encoded config string (see advanced usage below) |
+| `userId` | `string` | Generated visitor ID | Unique identifier for the user. **Optional** - if not provided, a unique visitor ID is automatically generated using browser fingerprinting for guest users |
+| `authUrl` | `string` | - | Authentication endpoint URL for token-based authentication |
+| `username` | `string` | - | Username for the session (sent to backend in variables) |
+| `data` | `string` | - | Additional custom variables in format `key1=value1~key2=value2` |
 | `width` | `string` | `"25vw"` | Widget width (CSS value) |
 | `height` | `string` | `"90vh"` | Widget height (CSS value) |
 | `right` | `string` | `"1.25rem"` | Distance from right edge |
@@ -210,11 +281,45 @@ For responses with buttons:
 
 ---
 
+### Guest User Support
+
+---
+
+The widget now supports **guest users** (users who haven't logged in or before logging in). When `userId` is not provided, the widget automatically generates a unique visitor ID using browser fingerprinting.
+
+**How it works:**
+
+1. **Browser Fingerprinting**: Uses FingerprintJS to generate a unique identifier based on:
+   - Browser characteristics (user agent, screen resolution, timezone, etc.)
+   - Incognito/private browsing detection
+   - Combined into a SHA256 hash for consistency
+
+2. **Automatic Guest Detection**: The widget automatically detects guest users and:
+   - Generates a visitor ID if `userId` is not provided
+   - Adds `auth: false` flag to all API requests for guest users
+   - Uses the visitor ID as the effective user ID throughout the session
+
+3. **Persistent Sessions**: The visitor ID remains consistent across page reloads (unless browser fingerprint changes or user clears data)
+
+**When to use guest mode:**
+- Public-facing websites where users can chat without logging in
+- Support widgets for anonymous visitors
+- Pre-login customer service interactions
+- Any scenario where user authentication is optional
+
+**When to provide userId:**
+- Users who are logged into your application
+- When you need to track chat history across devices
+- When authentication is required for personalized responses
+- Enterprise or internal applications
+
+---
+
 ### Usage Examples
 
 ---
 
-#### Basic Usage
+#### Basic Usage (Authenticated User)
 
 ```jsx
 import { ChatWidget } from "@data-netmonk/mona-chat-widget";
@@ -225,33 +330,167 @@ function App() {
     <ChatWidget 
       userId="user123" 
       sourceId="691e1b5952068ff7aaeccffc9"
+      webhookUrl="https://api.example.com/webhook"
+    />
+  );
+}
+```
+
+#### Guest User (Without Login)
+
+For anonymous visitors or users who haven't logged in:
+
+```jsx
+import { ChatWidget } from "@data-netmonk/mona-chat-widget";
+import "@data-netmonk/mona-chat-widget/dist/style.css";
+
+function App() {
+  return (
+    <ChatWidget 
+      sourceId="691e1b5952068ff7aaeccffc9"
+      webhookUrl="https://api.example.com/webhook"
     />
   );
 }
 ```
 
-#### With Backend URL
+**What happens:**
+- Widget automatically generates a visitor ID using browser fingerprinting
+- All API requests include `auth: false` in variables to indicate guest user
+- No login required - users can start chatting immediately
+
+#### Conditional userId (Logged in or Guest)
+
+Handle both logged-in users and guests dynamically:
+
+```jsx
+import { ChatWidget } from "@data-netmonk/mona-chat-widget";
+import "@data-netmonk/mona-chat-widget/dist/style.css";
+
+function App() {
+  const currentUser = getCurrentUser(); // Your auth function
+  
+  return (
+    <ChatWidget 
+      userId={currentUser?.id}  // Provide userId if logged in, undefined if not
+      sourceId="691e1b5952068ff7aaeccffc9"
+      webhookUrl="https://api.example.com/webhook"
+      username={currentUser?.name}
+    />
+  );
+}
+```
+
+**Behavior:**
+- If `currentUser.id` exists → Uses provided userId (authenticated user)
+- If `currentUser.id` is `null`/`undefined` → Generates visitor ID (guest user)
+- Backend receives `auth: false` flag only for guest users
+
+#### With Custom Variables
+
+Pass custom user data like email, phone number, etc. to the backend:
 
 ```jsx
 <ChatWidget 
-  userId="user123" 
+  userId="user123"
   sourceId="691e1b5952068ff7aaeccffc9"
-  botServerUrl="https://api.example.com"
-  type="prime"
+  webhookUrl="https://api.example.com/webhook"
+  username="John Doe"
+  data="telephone_number=+628123456789~email=john@example.com"
 />
 ```
 
-#### With Custom Variables (NEW!)
+**Variables sent to backend:**
+```json
+{
+  "chat_id": "...",
+  "session_id": "...",
+  "user_id": "user123",
+  "message": "Hello",
+  "type": "text",
+  "variables": {
+    "username": "John Doe",
+    "telephone_number": "+628123456789",
+    "email": "john@example.com"
+  }
+}
+```
+}
+```
+#### With Authentication (NEW!)
 
-Pass custom user data like username, phone number, etc. to the backend:
+The widget supports automatic authentication with token refresh on expiry:
 
 ```jsx
 <ChatWidget 
-  data="url:https://api.example.com~user_id=user123~source_id=691e1b5952068ff7aaeccffc9~username=John Doe~telephone_number=+628123456789~email=john@example.com"
+  userId="user123"
+  sourceId="691e1b5952068ff7aaeccffc9"
+  webhookUrl="https://api.example.com/webhook"
+  authUrl="https://api.example.com/login/chatwidget"
+  username="John Doe"
 />
 ```
 
-**Variables sent to backend:**
+**How authentication works:**
+
+1. **Initial Authentication**: When the widget loads (on Launcher mount), if `authUrl` is provided as a prop, it automatically calls the auth API:
+   ```
+   POST {authUrl}
+   Body: { "user_id": "user123" }
+   Response: { "token": "eyJ..." }
+   ```
+
+2. **Session Initialization**: After getting the token, the widget calls the init endpoint to establish the session:
+   ```
+   POST {webhookUrl}/{sourceId}/init
+   Body: {
+     "session_id": "...",
+     "user_id": "user123",
+     "token": "eyJ...",
+     "username": "John Doe"
+   }
+   ```
+
+3. **Automatic Token Refresh**: If the webhook returns **401 Unauthorized** (token expired/revoked), the widget automatically:
+   - Calls the `authUrl` again to get a fresh token
+   - Re-initializes the session with the new token
+   - Updates the `authToken` in variables
+   - Retries the failed request with the new token
+   - This happens transparently without user interaction
+
+**Combined example with auth and custom variables:**
+```jsx
+<ChatWidget 
+  userId="user123"
+  sourceId="691e1b5952068ff7aaeccffc9"
+  webhookUrl="https://api.example.com/webhook"
+  authUrl="https://api.example.com/login/chatwidget"
+  username="John"
+  data="email=john@example.com~phone=+628123456789"
+/>
+```
+
+**Auth Flag (`auth` variable):**
+The widget automatically adds an `auth: false` flag to the `variables` object when the user is a guest (not authenticated):
+- When `userId === visitorId` (browser fingerprint), the widget adds `auth: false` to variables
+- When `userId !== visitorId` (authenticated user), no `auth` flag is added to variables
+
+**Guest user example** (userId equals browser fingerprint):
+```json
+{
+  "chat_id": "...",
+  "session_id": "...",
+  "user_id": "visitor_abc123",
+  "message": "Hello",
+  "type": "text",
+  "variables": {
+    "username": "Guest",
+    "auth": false
+  }
+}
+```
+
+**Authenticated user example** (userId is different from browser fingerprint):
 ```json
 {
   "chat_id": "...",
@@ -261,26 +500,25 @@ Pass custom user data like username, phone number, etc. to the backend:
   "type": "text",
   "variables": {
     "username": "John Doe",
-    "telephone_number": "+628123456789",
     "email": "john@example.com"
   }
 }
 ```
 
-**Reserved keys** (won't go into `variables`):
-- `url` - Backend URL
-- `user_id` - User identifier  
-- `source_id` - Source identifier
-- `type` - Agent type
+This `auth: false` flag is automatically added in:
+- Session initialization payload (when guest)
+- All message requests (when guest)
+- Button postback requests (when guest)
 
-**Any other key** you add will be included in the `variables` object automatically!
+**Note:** The `data` prop is for additional custom variables only. Required parameters (`userId`, `sourceId`, `webhookUrl`) and common optional parameters (`authUrl`, `username`) should be passed as direct props for better type safety and clarity.
 
 #### Custom Styling
 
 ```jsx
 <ChatWidget 
-  userId="user123"
+  userId="user123"  // Optional
   sourceId="691e1b5952068ff7aaeccffc9"
+  webhookUrl="https://api.example.com/webhook"
   width="400px"
   height="600px"
   right="20px"
@@ -295,8 +533,9 @@ Pass custom user data like username, phone number, etc. to the backend:
 <div style={{ display: 'grid', gridTemplateColumns: '1fr 400px' }}>
   <div>Main content</div>
   <ChatWidget 
-    userId="user123"
+    userId="user123"  // Optional
     sourceId="691e1b5952068ff7aaeccffc9"
+    webhookUrl="https://api.example.com/webhook"
     position="relative"
     width="100%"
     height="100vh"
@@ -315,8 +554,9 @@ function App() {
 
   return (
     <ChatWidget 
-      userId="user123"
+      userId="user123"  // Optional
       sourceId="691e1b5952068ff7aaeccffc9"
+      webhookUrl="https://api.example.com/webhook"
       onToggle={handleToggle}
     />
   );
@@ -327,8 +567,9 @@ function App() {
 
 ```jsx
 <ChatWidget 
-  userId="user123"
+  userId="user123"  // Optional - supports guest users
   sourceId="691e1b5952068ff7aaeccffc9"
+  webhookUrl="https://api.example.com/webhook"
   width="100vw"
   height="100vh"
   right="0"
@@ -342,92 +583,153 @@ function App() {
 
 ---
 
-The `data` prop allows you to pass configuration via a single string. This is especially useful when you need to dynamically build the configuration or pass it through URL parameters.
+The `data` prop allows you to pass additional custom variables via a single string. This is especially useful when you need to dynamically pass user-specific data or pass it through URL parameters.
 
-**Format:** `key:value` pairs separated by `~`
+**Format:** `key=value` pairs separated by `~`
 
 **Example data string:**
 ```
-url:https://api.example.com~user_id=user123~source_id=abc~username=John~phone=+1234567890
+email=john@example.com~phone=+1234567890~department=Engineering
 ```
 
+**Note:** `authUrl` and `username` are now **direct props** and should not be included in the `data` string.
+
 #### Building Data String Programmatically
 
-Instead of manually constructing the data string, you can create a helper function to build it dynamically:
+Instead of manually constructing the data string, you can create a helper function to build it dynamically. This approach is recommended for production applications as it:
+- Prevents syntax errors in the data string format
+- Makes the code more maintainable and readable
+- Allows for conditional inclusion of parameters
+- Handles URL encoding automatically if needed
+
+**Create a helper function** (`src/helpers/chatWidget.js` or similar):
+
+```jsx
+/**
+ * Builds the data string for ChatWidget component
+ * @param {Object} params - Object containing all parameters
+ * @param {string} params.email - Optional: User's email address
+ * @param {string} params.phone - Optional: User's phone number
+ * @param {Object} params.customFields - Optional: Any additional custom fields as key-value pairs
+ * @returns {string} Formatted data string for ChatWidget (always returns a string)
+ * 
+ * @example
+ * // Returns: "email=john@example.com~phone=+1234567890~department=Engineering"
+ * buildChatWidgetData({
+ *   email: "john@example.com",
+ *   phone: "+1234567890",
+ *   customFields: { department: "Engineering" }
+ * });
+ */
+export const buildChatWidgetData = ({ 
+  email, 
+  phone,
+  customFields = {} 
+}) => {
+  const parts = [];
+  
+  // Add standard fields
+  if (email) {
+    parts.push(`email=${encodeURIComponent(email)}`);
+  }
+  
+  if (phone) {
+    parts.push(`phone=${encodeURIComponent(phone)}`);
+  }
+  
+  // Add any custom fields dynamically
+  // Note: customFields is just a convenience parameter for the helper function
+  // Each field will be flattened into the string format: key=value~key2=value2
+  Object.entries(customFields).forEach(([key, value]) => {
+    if (value) {
+      parts.push(`${key}=${encodeURIComponent(String(value))}`);
+    }
+  });
+  
+  // Returns a string like: "email=john@example.com~phone=+1234567890~department=Engineering"
+  return parts.join("~");
+};
+```
+
+**Important:** The `customFields` parameter is **NOT** passed as an object to the widget. It's just a convenient way to pass multiple additional fields to the helper function. The function flattens everything into a single string format.
+
+**Usage in your application:**
 
-**Usage:**
 ```jsx
 import { ChatWidget } from "@data-netmonk/mona-chat-widget";
+import "@data-netmonk/mona-chat-widget/dist/style.css";
 import { buildChatWidgetData } from "./helpers/chatWidget";
 
 function App() {
-  const chatData = buildChatWidgetData({
-    userId: "user123",
-    sourceId: "691e1b5952068ff7aaeccffc9",
-    botServerUrl: "https://api.example.com",
-    username: "John Doe",
+  // Get user data from your auth system, state, or props
+  const user = {
+    id: "user123",
+    name: "John Doe",
     email: "john@example.com",
     phone: "+628123456789"
+  };
+  
+  // Build the data string with custom variables only
+  const customData = buildChatWidgetData({
+    email: user.email,
+    phone: user.phone,
+    customFields: {
+      department: "Engineering",
+      role: "Developer",
+      company: "Acme Corp"
+    }
   });
+  
+  // customData is now a STRING like:
+  // "email=john@example.com~phone=%2B628123456789~department=Engineering~role=Developer~company=Acme%20Corp"
 
-  return <ChatWidget data={chatData} />;
+  return (
+    <ChatWidget 
+      userId={user.id}
+      sourceId="691e1b5952068ff7aaeccffc9"
+      webhookUrl="https://api.example.com/webhook"
+      authUrl="https://api.example.com/login/chatwidget"  // Direct prop
+      username={user.name}  // Direct prop
+      data={customData}  // Only additional variables
+    />
+  );
 }
 ```
 
-The helper function should:
-- Accept configuration parameters (userId, sourceId, botServerUrl, and any custom variables)
-- Build the data string in format: `key=value` pairs separated by `~`
-- Use `url:` prefix (not `url=`) for the backend URL
-- Return the formatted string
-
-#### Using with URL Parameters (Optional)
-
-If you need to pass the data through URL parameters:
-
-```jsx
-// Parse from URL
-const urlParams = new URLSearchParams(window.location.search);
-const dataParam = urlParams.get('data');
-
-<ChatWidget data={dataParam} />
-```
-
-**URL example:**
-```
-https://yourapp.com/chat?data=url:https://api.example.com~user_id=user123~source_id=abc~username=John~phone=%2B628123456789
-```
-
-#### Real-World Example from ui-mona-web
-
-See the complete helper implementation in `ui-mona-web/src/helpers/chatWidget.js`:
+**With conditional authentication:**
 
 ```jsx
-import { getUserId } from './cookie';
-
-export const buildChatWidgetData = ({ loginType, sourceId, userId, botServerUrl }) => {
-  // Get userId from cookies if not provided
-  const finalUserId = userId || getUserId();
-  
-  // Get sourceId based on loginType
-  const finalSourceId = sourceId || getSourceIdByLoginType(loginType);
-  
-  // Get bot server URL from env
-  const finalBotServerUrl = import.meta.env.VITE_CHAT_WIDGET_WEBHOOK_URL || botServerUrl;
-  
-  const parts = [
-    `user_id=${String(finalUserId)}`,
-    `source_id=${finalSourceId}`,
-  ];
-  
-  if (finalBotServerUrl) {
-    parts.unshift(`url:${finalBotServerUrl}`);
-  }
+function App() {
+  const authUrl = import.meta.env.VITE_CHAT_AUTH_ENABLED === "true" 
+    ? import.meta.env.VITE_CHAT_AUTH_URL 
+    : null;
   
-  return parts.join("~");
-};
+  const customData = buildChatWidgetData({
+    email: getCurrentUser().email,
+    customFields: {
+      department: "Sales"
+    }
+  });
+
+  return (
+    <ChatWidget 
+      userId={getCurrentUser().id}
+      sourceId="691e1b5952068ff7aaeccffc9"
+      webhookUrl={import.meta.env.VITE_WEBHOOK_URL}
+      authUrl={authUrl}  // Direct prop (conditionally set)
+      username={getCurrentUser().name}  // Direct prop
+      data={customData}  // Only additional variables
+    />
+  );
+}
 ```
 
----
+**The helper function handles:**
+- ✅ Proper formatting with `~` separators
+- ✅ URL encoding for special characters
+- ✅ Conditional parameter inclusion (only adds if value exists)
+- ✅ Support for dynamic custom fields
+- ✅ Type safety and documentation via JSDoc comments
 
 ### Standalone app (for demonstration)