@data-netmonk/mona-chat-widget 2.2.0 → 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
@@ -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
@@ -99,45 +176,6 @@ For responses with buttons:
 
 ---
 
-### 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 (falls back to env vars if not provided)
-
-✨ **New Features:**
-1. **Authentication support** - Automatic token management with refresh on 401 errors
-   - Pass `authUrl` in the `data` prop
-   - Widget handles token lifecycle automatically
-2. **Enhanced data prop** - Support for custom variables passed to backend via `data` prop
-3. **Improved error handling** - Better fallback mechanisms and error messages
-
-📝 **Migration Guide:**
-```jsx
-// Old usage (deprecated)
-<ChatWidget 
-  userId="user123"
-  sourceId="source456"
-  type="prime"
-  botServerUrl="https://api.example.com"
-/>
-
-// New usage (current)
-<ChatWidget 
-  userId="user123"
-  sourceId="source456"
-  webhookUrl="https://api.example.com/webhook"
-  data="authUrl=https://api.example.com/login/chatwidget~username=John"
-/>
-```
-
----
-
 ### Library (how to update and publish)
 
 ---
@@ -222,15 +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 |
-| `webhookUrl` | `string` | **Required.** Backend webhook URL (falls back to env vars if not provided) |
+| `webhookUrl` | `string` | **Required.** Backend webhook URL |
 
 #### Optional Props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `data` | `string` | - | Custom variables and auth URL in format `key1=value1~key2=value2~authUrl=https://...` |
+| `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 |
@@ -241,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";
@@ -262,16 +336,67 @@ function App() {
 }
 ```
 
+#### 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"
+    />
+  );
+}
+```
+
+**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 username, phone number, etc. to the backend:
+Pass custom user data like email, phone number, etc. to the backend:
 
 ```jsx
 <ChatWidget 
   userId="user123"
   sourceId="691e1b5952068ff7aaeccffc9"
   webhookUrl="https://api.example.com/webhook"
-  data="username=John Doe~telephone_number=+628123456789~email=john@example.com"
+  username="John Doe"
+  data="telephone_number=+628123456789~email=john@example.com"
 />
 ```
 
@@ -290,7 +415,8 @@ Pass custom user data like username, phone number, etc. to the backend:
   }
 }
 ```
-
+}
+```
 #### With Authentication (NEW!)
 
 The widget supports automatic authentication with token refresh on expiry:
@@ -300,34 +426,34 @@ The widget supports automatic authentication with token refresh on expiry:
   userId="user123"
   sourceId="691e1b5952068ff7aaeccffc9"
   webhookUrl="https://api.example.com/webhook"
-  data="authUrl=https://api.example.com/login/chatwidget~username=John Doe"
+  authUrl="https://api.example.com/login/chatwidget"
+  username="John Doe"
 />
 ```
 
 **How authentication works:**
 
-1. **Initial Authentication**: When the widget loads (on Launcher mount), if `authUrl` is provided in the `data` prop, it automatically calls the auth API:
+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. **Token Usage**: The received token is automatically included in all webhook API calls as `authToken` in the `variables` object:
-   ```json
-   {
-     "chat_id": "...",
+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",
-     "message": "Hello",
-     "variables": {
-       "authToken": "eyJ...",
-       "username": "John Doe"
-     }
+     "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
@@ -338,18 +464,61 @@ The widget supports automatic authentication with token refresh on expiry:
   userId="user123"
   sourceId="691e1b5952068ff7aaeccffc9"
   webhookUrl="https://api.example.com/webhook"
-  data="authUrl=https://api.example.com/login/chatwidget~username=John~email=john@example.com~phone=+628123456789"
+  authUrl="https://api.example.com/login/chatwidget"
+  username="John"
+  data="email=john@example.com~phone=+628123456789"
 />
 ```
 
-**Note:** The `data` prop is for optional parameters only (custom variables and `authUrl`). Required parameters (`userId`, `sourceId`, `webhookUrl`) must be passed as direct props.
+**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": "...",
+  "session_id": "...",
+  "user_id": "user123",
+  "message": "Hello",
+  "type": "text",
+  "variables": {
+    "username": "John Doe",
+    "email": "john@example.com"
+  }
+}
+```
+
+This `auth: false` flag is automatically added in:
+- Session initialization payload (when guest)
+- All message requests (when guest)
+- Button postback requests (when guest)
+
+**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"
@@ -364,8 +533,9 @@ The widget supports automatic authentication with token refresh on expiry:
 <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"
@@ -384,8 +554,9 @@ function App() {
 
   return (
     <ChatWidget 
-      userId="user123"
+      userId="user123"  // Optional
       sourceId="691e1b5952068ff7aaeccffc9"
+      webhookUrl="https://api.example.com/webhook"
       onToggle={handleToggle}
     />
   );
@@ -396,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"
@@ -411,23 +583,16 @@ function App() {
 
 ---
 
-The `data` prop allows you to pass custom variables and authentication URL via a single string. This is especially useful when you need to dynamically pass user-specific data 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 `~`
 
 **Example data string:**
 ```
-username=John Doe~phone=+1234567890~email=john@example.com
-```
-
-**With authentication:**
-```
-authUrl=https://api.example.com/login/chatwidget~username=John Doe~email=john@example.com
+email=john@example.com~phone=+1234567890~department=Engineering
 ```
 
-**Special keys:**
-- `authUrl`: Authentication endpoint URL (see "With Authentication" section above)
-- All other keys: Custom variables passed to webhook in `variables` object
+**Note:** `authUrl` and `username` are now **direct props** and should not be included in the `data` string.
 
 #### Building Data String Programmatically
 
@@ -443,40 +608,27 @@ Instead of manually constructing the data string, you can create a helper functi
 /**
  * Builds the data string for ChatWidget component
  * @param {Object} params - Object containing all parameters
- * @param {string} params.authUrl - Optional: Authentication endpoint URL
- * @param {string} params.username - Optional: User's display name
  * @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: "authUrl=https://api.com~username=John~email=john@example.com"
+ * // Returns: "email=john@example.com~phone=+1234567890~department=Engineering"
  * buildChatWidgetData({
- *   authUrl: "https://api.com",
- *   username: "John",
- *   email: "john@example.com"
+ *   email: "john@example.com",
+ *   phone: "+1234567890",
+ *   customFields: { department: "Engineering" }
  * });
  */
 export const buildChatWidgetData = ({ 
-  authUrl, 
-  username, 
   email, 
   phone,
   customFields = {} 
 }) => {
   const parts = [];
   
-  // Add authUrl first if provided (for authentication)
-  if (authUrl) {
-    parts.push(`authUrl=${authUrl}`);
-  }
-  
   // Add standard fields
-  if (username) {
-    parts.push(`username=${encodeURIComponent(username)}`);
-  }
-  
   if (email) {
     parts.push(`email=${encodeURIComponent(email)}`);
   }
@@ -494,7 +646,7 @@ export const buildChatWidgetData = ({
     }
   });
   
-  // Returns a string like: "authUrl=...~username=John~email=john@example.com~department=Engineering"
+  // Returns a string like: "email=john@example.com~phone=+1234567890~department=Engineering"
   return parts.join("~");
 };
 ```
@@ -517,10 +669,8 @@ function App() {
     phone: "+628123456789"
   };
   
-  // Build the data string
+  // Build the data string with custom variables only
   const customData = buildChatWidgetData({
-    authUrl: "https://api.example.com/login/chatwidget",
-    username: user.name,
     email: user.email,
     phone: user.phone,
     customFields: {
@@ -531,14 +681,16 @@ function App() {
   });
   
   // customData is now a STRING like:
-  // "authUrl=https://api.example.com/login/chatwidget~username=John%20Doe~email=john@example.com~phone=%2B628123456789~department=Engineering~role=Developer~company=Acme%20Corp"
+  // "email=john@example.com~phone=%2B628123456789~department=Engineering~role=Developer~company=Acme%20Corp"
 
   return (
     <ChatWidget 
       userId={user.id}
       sourceId="691e1b5952068ff7aaeccffc9"
       webhookUrl="https://api.example.com/webhook"
-      data={customData} // Pass the STRING to data prop
+      authUrl="https://api.example.com/login/chatwidget"  // Direct prop
+      username={user.name}  // Direct prop
+      data={customData}  // Only additional variables
     />
   );
 }
@@ -553,9 +705,10 @@ function App() {
     : null;
   
   const customData = buildChatWidgetData({
-    authUrl: authUrl, // Only included if authentication is enabled
-    username: getCurrentUser().name,
-    email: getCurrentUser().email
+    email: getCurrentUser().email,
+    customFields: {
+      department: "Sales"
+    }
   });
 
   return (
@@ -563,7 +716,9 @@ function App() {
       userId={getCurrentUser().id}
       sourceId="691e1b5952068ff7aaeccffc9"
       webhookUrl={import.meta.env.VITE_WEBHOOK_URL}
-      data={customData}
+      authUrl={authUrl}  // Direct prop (conditionally set)
+      username={getCurrentUser().name}  // Direct prop
+      data={customData}  // Only additional variables
     />
   );
 }