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

package/README.md

@@ -10,7 +10,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
    ```
@@ -99,6 +99,45 @@ 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)
 
 ---
@@ -165,10 +204,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"
        />
      );
    }
@@ -186,20 +224,13 @@ For responses with buttons:
 |------|------|-------------|
 | `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 (falls back to env vars if not provided) |
 
 #### 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) |
+| `data` | `string` | - | Custom variables and auth URL in format `key1=value1~key2=value2~authUrl=https://...` |
 | `width` | `string` | `"25vw"` | Widget width (CSS value) |
 | `height` | `string` | `"90vh"` | Widget height (CSS value) |
 | `right` | `string` | `"1.25rem"` | Distance from right edge |
@@ -225,29 +256,22 @@ function App() {
     <ChatWidget 
       userId="user123" 
       sourceId="691e1b5952068ff7aaeccffc9"
+      webhookUrl="https://api.example.com/webhook"
     />
   );
 }
 ```
 
-#### With Backend URL
-
-```jsx
-<ChatWidget 
-  userId="user123" 
-  sourceId="691e1b5952068ff7aaeccffc9"
-  botServerUrl="https://api.example.com"
-  type="prime"
-/>
-```
-
-#### With Custom Variables (NEW!)
+#### With Custom Variables
 
 Pass custom user data like username, phone number, etc. to the backend:
 
 ```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"
+  data="username=John Doe~telephone_number=+628123456789~email=john@example.com"
 />
 ```
 
@@ -267,13 +291,58 @@ Pass custom user data like username, phone number, etc. to the backend:
 }
 ```
 
-**Reserved keys** (won't go into `variables`):
-- `url` - Backend URL
-- `user_id` - User identifier  
-- `source_id` - Source identifier
-- `type` - Agent type
+#### With Authentication (NEW!)
+
+The widget supports automatic authentication with token refresh on expiry:
+
+```jsx
+<ChatWidget 
+  userId="user123"
+  sourceId="691e1b5952068ff7aaeccffc9"
+  webhookUrl="https://api.example.com/webhook"
+  data="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:
+   ```
+   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": "...",
+     "user_id": "user123",
+     "message": "Hello",
+     "variables": {
+       "authToken": "eyJ...",
+       "username": "John Doe"
+     }
+   }
+   ```
 
-**Any other key** you add will be included in the `variables` object automatically!
+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
+   - 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"
+  data="authUrl=https://api.example.com/login/chatwidget~username=John~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.
 
 #### Custom Styling
 
@@ -342,92 +411,170 @@ 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 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.
 
-**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
+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
+```
+
+**Special keys:**
+- `authUrl`: Authentication endpoint URL (see "With Authentication" section above)
+- All other keys: Custom variables passed to webhook in `variables` object
+
 #### 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.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"
+ * buildChatWidgetData({
+ *   authUrl: "https://api.com",
+ *   username: "John",
+ *   email: "john@example.com"
+ * });
+ */
+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)}`);
+  }
+  
+  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: "authUrl=...~username=John~email=john@example.com~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
+  const customData = buildChatWidgetData({
+    authUrl: "https://api.example.com/login/chatwidget",
+    username: user.name,
+    email: user.email,
+    phone: user.phone,
+    customFields: {
+      department: "Engineering",
+      role: "Developer",
+      company: "Acme Corp"
+    }
   });
+  
+  // 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"
 
-  return <ChatWidget data={chatData} />;
+  return (
+    <ChatWidget 
+      userId={user.id}
+      sourceId="691e1b5952068ff7aaeccffc9"
+      webhookUrl="https://api.example.com/webhook"
+      data={customData} // Pass the STRING to data prop
+    />
+  );
 }
 ```
 
-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:
+**With conditional authentication:**
 
 ```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`:
-
-```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({
+    authUrl: authUrl, // Only included if authentication is enabled
+    username: getCurrentUser().name,
+    email: getCurrentUser().email
+  });
+
+  return (
+    <ChatWidget 
+      userId={getCurrentUser().id}
+      sourceId="691e1b5952068ff7aaeccffc9"
+      webhookUrl={import.meta.env.VITE_WEBHOOK_URL}
+      data={customData}
+    />
+  );
+}
 ```
 
----
+**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)