@data-netmonk/mona-chat-widget 2.1.36 → 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)
 
 ---
@@ -146,26 +185,397 @@ For responses with buttons:
 
 ---
 
-1. Install package
-   ```
-   npm install @aaiiccaa/mona-chat-widget
+1. **Install package**
+   ```bash
+   npm install @data-netmonk/mona-chat-widget
    ```
-2. Import styles on your `App.jsx` or `index.jsx`
+
+2. **Import styles on your `App.jsx` or `index.jsx`**
 
    ```jsx
-   import "@aaiiccaa/mona-chat-widget/dist/style.css";
+   import "@data-netmonk/mona-chat-widget/dist/style.css";
    ```
 
-3. Import & use component
+3. **Import & use component**
 
    ```jsx
-   import { ChatWidget } from "@aaiiccaa/mona-chat-widget";
+   import { ChatWidget } from "@data-netmonk/mona-chat-widget";
 
-   <ChatWidget type={"prime"} userId={"1234"} sourceId={"1"}/>;
+   function App() {
+     return (
+       <ChatWidget 
+         userId="user123" 
+         sourceId="691e1b5952068ff7aaeccffc9"
+         webhookUrl="https://your-backend-url.com"
+       />
+     );
+   }
    ```
 
 ---
 
+### Component Props
+
+---
+
+#### Required Props
+
+| 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) |
+
+#### Optional Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `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 |
+| `bottom` | `string` | `"1.25rem"` | Distance from bottom edge |
+| `zIndex` | `number` | `2000` | CSS z-index for widget positioning |
+| `position` | `string` | `"fixed"` | CSS position (`"fixed"` or `"relative"`) |
+| `onToggle` | `function` | - | Callback when widget opens/closes: `(isOpen: boolean) => void` |
+
+---
+
+### Usage Examples
+
+---
+
+#### Basic Usage
+
+```jsx
+import { ChatWidget } from "@data-netmonk/mona-chat-widget";
+import "@data-netmonk/mona-chat-widget/dist/style.css";
+
+function App() {
+  return (
+    <ChatWidget 
+      userId="user123" 
+      sourceId="691e1b5952068ff7aaeccffc9"
+      webhookUrl="https://api.example.com/webhook"
+    />
+  );
+}
+```
+
+#### With Custom Variables
+
+Pass custom user data like username, 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"
+/>
+```
+
+**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!)
+
+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"
+     }
+   }
+   ```
+
+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
+
+```jsx
+<ChatWidget 
+  userId="user123"
+  sourceId="691e1b5952068ff7aaeccffc9"
+  width="400px"
+  height="600px"
+  right="20px"
+  bottom="20px"
+  zIndex={9999}
+/>
+```
+
+#### Embedded in Layout (Relative Positioning)
+
+```jsx
+<div style={{ display: 'grid', gridTemplateColumns: '1fr 400px' }}>
+  <div>Main content</div>
+  <ChatWidget 
+    userId="user123"
+    sourceId="691e1b5952068ff7aaeccffc9"
+    position="relative"
+    width="100%"
+    height="100vh"
+  />
+</div>
+```
+
+#### With Toggle Callback
+
+```jsx
+function App() {
+  const handleToggle = (isOpen) => {
+    console.log('Chat widget is', isOpen ? 'open' : 'closed');
+    // Track analytics, update UI, etc.
+  };
+
+  return (
+    <ChatWidget 
+      userId="user123"
+      sourceId="691e1b5952068ff7aaeccffc9"
+      onToggle={handleToggle}
+    />
+  );
+}
+```
+
+#### Full-Screen Widget
+
+```jsx
+<ChatWidget 
+  userId="user123"
+  sourceId="691e1b5952068ff7aaeccffc9"
+  width="100vw"
+  height="100vh"
+  right="0"
+  bottom="0"
+/>
+```
+
+---
+
+### Data Prop Format & Helper Function
+
+---
+
+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 `~`
+
+**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
+```
+
+**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. 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:**
+
+```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() {
+  // 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 
+      userId={user.id}
+      sourceId="691e1b5952068ff7aaeccffc9"
+      webhookUrl="https://api.example.com/webhook"
+      data={customData} // Pass the STRING to data prop
+    />
+  );
+}
+```
+
+**With conditional authentication:**
+
+```jsx
+function App() {
+  const authUrl = import.meta.env.VITE_CHAT_AUTH_ENABLED === "true" 
+    ? import.meta.env.VITE_CHAT_AUTH_URL 
+    : null;
+  
+  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)
 
 1. **How to run locally** (access at `http://localhost:${PORT}/${APP_PREFIX}`)