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

package/README.md

@@ -146,26 +146,289 @@ 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 
+         type="prime"
+         userId="user123" 
+         sourceId="691e1b5952068ff7aaeccffc9"
+         botServerUrl="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 |
+
+#### Dynamic Data Prop (NEW!)
+| Prop | Type | Description |
+|------|------|-------------|
+| `data` | `string` | URL-encoded config string (see advanced usage below) |
+
+
+#### 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) |
+| `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"
+    />
+  );
+}
+```
+
+#### With Backend URL
+
+```jsx
+<ChatWidget 
+  userId="user123" 
+  sourceId="691e1b5952068ff7aaeccffc9"
+  botServerUrl="https://api.example.com"
+  type="prime"
+/>
+```
+
+#### With Custom Variables (NEW!)
+
+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"
+/>
+```
+
+**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"
+  }
+}
+```
+
+**Reserved keys** (won't go into `variables`):
+- `url` - Backend URL
+- `user_id` - User identifier  
+- `source_id` - Source identifier
+- `type` - Agent type
+
+**Any other key** you add will be included in the `variables` object automatically!
+
+#### 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 configuration via a single string. This is especially useful when you need to dynamically build the configuration or pass it through URL parameters.
+
+**Format:** `key:value` pairs separated by `~`
+
+**Example data string:**
+```
+url:https://api.example.com~user_id=user123~source_id=abc~username=John~phone=+1234567890
+```
+
+#### Building Data String Programmatically
+
+Instead of manually constructing the data string, you can create a helper function to build it dynamically:
+
+**Usage:**
+```jsx
+import { ChatWidget } from "@data-netmonk/mona-chat-widget";
+import { buildChatWidgetData } from "./helpers/chatWidget";
+
+function App() {
+  const chatData = buildChatWidgetData({
+    userId: "user123",
+    sourceId: "691e1b5952068ff7aaeccffc9",
+    botServerUrl: "https://api.example.com",
+    username: "John Doe",
+    email: "john@example.com",
+    phone: "+628123456789"
+  });
+
+  return <ChatWidget data={chatData} />;
+}
+```
+
+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`:
+
+```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}`);
+  }
+  
+  return parts.join("~");
+};
+```
+
+---
+
 ### Standalone app (for demonstration)
 
 1. **How to run locally** (access at `http://localhost:${PORT}/${APP_PREFIX}`)