lulichat 1.0.15 → 1.0.17

package/README.md

@@ -1,32 +1,20 @@
 # LuliChat Support Chat
 
-Lulichat Support Chat is a React library that provides a chat interface for web applications. It includes a chat icon that opens a contact form for users to submit their contact information, and it establishes a socket connection for real-time chat functionality.
+LuliChat Support Chat is a library that provides a real-time live support chat widget for web applications. It can be integrated into React applications or loaded directly via UMD/script tags in standard HTML pages.
 
-## Features
+---
 
-- Chat icon positioned at the bottom right corner of the screen.
-- Contact information collection form with validation.
-- Real-time chat interface using WebSocket.
-- Easy integration into any React application.
+## 1. React Installation & Usage
 
-## Installation
-
-To install the LuliChat Support Chat library, run the following command:
+### Installation
 
 ```bash
 npm install lulichat
 ```
 
-## Usage
+### Usage
 
-To use the Lulichat Support Chat in your application, import the components as follows:
-
-```tsx
-import LuliChat from "lulichat";
-import "lulichat/dist/style.css";
-```
-
-### Example
+Import the component and stylesheet:
 
 ```tsx
 import React from "react";
@@ -35,49 +23,34 @@ import "lulichat/dist/style.css";
 
 const App = () => {
   return (
-    <div>
-      <h1>Welcome to My Application</h1>
-      <LuliChat
-        apiKey="LU...."
-        companyName="LuliChat Demo"
-        welcomeMessage="How can we help you today?"
-        primaryColor="#4f46e5"
-        allowAnonymous={true}
-        requireContactInfo={true}
-        position="bottom-right"
-      />
-    </div>
+    <LuliChat
+      apiKey="YOUR_API_KEY"
+      companyName="LuliChat Demo"
+      welcomeMessage="How can we help you today?"
+      primaryColor="#4f46e5"
+      allowAnonymous={true}
+      requireContactInfo={true}
+      position="bottom-right"
+    />
   );
 };
 
 export default App;
 ```
 
-## Script tag (no React)
-
-You have two ways to embed the widget:
-
-1. Externalized (smaller) build – you provide React, ReactDOM and socket.io-client (as globals) OR you are on a React page already.
-2. Standalone (larger) build – everything bundled, just one script tag.
+---
 
-### 1. Externalized build (recommended if you already use React)
+## 2. Vanilla Script Integration (No React)
 
-Add React, ReactDOM and socket.io-client globals if they are not already present. If you are not using the standalone bundle, also add marked and DOMPurify (or rely on our graceful fallbacks):
+You can load the widget on any website using the unpkg CDN.
 
-```html
-<script src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
-<script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
-<script src="https://unpkg.com/socket.io-client@4/dist/socket.io.min.js"></script>
-<script src="https://unpkg.com/marked/marked.min.js"></script>
-<script src="https://unpkg.com/dompurify/dist/purify.min.js"></script>
-```
+### Option A: Standalone Bundle (Recommended for non-React websites)
 
-Then include the library UMD bundle. You can pass configuration using `data-*` attributes, or initialize programmatically.
+This bundle includes React, ReactDOM, Socket.io, marked, and DOMPurify internally, making it a zero-dependency drop-in.
 
 ```html
-<link rel="stylesheet" href="https://unpkg.com/lulichat/dist/style.css" />
 <script
-  src="https://unpkg.com/lulichat/dist/lulichat-support.umd.js"
+  src="https://unpkg.com/lulichat/dist/lulichat-widget-standalone.umd.js"
   data-api-key="YOUR_API_KEY"
   data-company-name="Your Company"
   data-position="bottom-right"
@@ -87,35 +60,14 @@ Then include the library UMD bundle. You can pass configuration using `data-*` a
 ></script>
 ```
 
-Or programmatically:
-
-```html
-<script src="https://unpkg.com/lulichat/dist/lulichat-support.umd.js"></script>
-<script>
-  window.LuliChatSupport.mount({
-    apiKey: "YOUR_API_KEY",
-    baseUrl: "https://api.example.com",
-    position: "bottom-right",
-    primaryColor: "#4f46e5",
-  });
-  // Later
-  // window.LuliChatSupport.unmountAll();
-  // or window.LuliChatSupport.unmount(id)
-</script>
-```
-
-Notes:
+### Option B: Externalized Bundle
 
-- When using programmatic mount, the stylesheet will be auto‑injected. If your CSS file isn’t next to the script, set a custom URL via `data-style-href` on the script tag.
-- If `marked` or `DOMPurify` are not present, the widget will still render. Markdown will fall back to plain text/HTML passthrough and a console warning is logged. For best security and formatting, include both scripts above or use the standalone bundle.
-
-### 2. Standalone build (no other scripts needed)
-
-If you prefer a zero‑dependency drop‑in (larger file size), use the standalone bundle produced as `lulichat-support-standalone.umd.js`:
+If your page already loads React, ReactDOM, and socket.io-client, use the smaller externalized bundle:
 
 ```html
+<link rel="stylesheet" href="https://unpkg.com/lulichat/dist/style.css" />
 <script
-  src="https://unpkg.com/lulichat/dist/lulichat-support-standalone.umd.js"
+  src="https://unpkg.com/lulichat/dist/lulichat-widget.umd.js"
   data-api-key="YOUR_API_KEY"
   data-company-name="Your Company"
   data-position="bottom-right"
@@ -125,185 +77,32 @@ If you prefer a zero‑dependency drop‑in (larger file size), use the standalo
 ></script>
 ```
 
-No React/socket.io-client tags required. Choose this for non‑React sites wanting the simplest integration. Trade‑off: bigger download (~300kB UMD vs ~61kB + peer scripts).
+## 3. Configuration Options
 
-### Isolated iframe mode (optional)
+Set these options via React component props, `data-*` script tag attributes, or URL query parameters:
 
-If you want to isolate the widget’s DOM and CSS from your page, you can mount it inside a fixed-position iframe. Enable it from the script tag via `data-isolated="iframe"`:
+| Parameter / Attribute                              | Description                                                               | Default                    |
+| :------------------------------------------------- | :------------------------------------------------------------------------ | :------------------------- |
+| `apiKey` / `data-api-key`                          | Your LuliChat public API key (Required)                                   | -                          |
+| `companyName` / `data-company-name`                | Header title of the widget                                                | `LuliChat`                 |
+| `welcomeMessage` / `data-welcome-message`          | Initial greeting message                                                  | -                          |
+| `primaryColor` / `data-primary-color`              | Hex theme color code (e.g. `#4f46e5`)                                     | `#4f46e5`                  |
+| `position` / `data-position`                       | Widget placement (`bottom-right`, `bottom-left`, `top-right`, `top-left`) | `bottom-right`             |
+| `allowAnonymous` / `data-allow-anonymous`          | Allow users to chat without entering contact info                         | `false`                    |
+| `requireContactInfo` / `data-require-contact-info` | Ask for contact info before initiating a session                          | `true`                     |
+| `baseUrl` / `data-base-url`                        | Base endpoint URL for the chat backend API                                | `https://api.lulichat.com` |
 
-```html
-<script
-  src="https://unpkg.com/lulichat/dist/lulichat-support.umd.js"
-  data-api-key="YOUR_API_KEY"
-  data-isolated="iframe"
-  data-iframe-width="360px"
-  data-iframe-height="560px"
-  defer
-  onload="window.LuliChatSupport && window.LuliChatSupport.initFromScript()"
-></script>
-```
-
-Options you can set as `data-*` attributes for iframe mode:
-
-- `data-iframe-width` – width of the iframe (e.g. `360px`)
-- `data-iframe-height` – height of the iframe (e.g. `560px`)
-- `data-iframe-auto-resize` – when `true`, the iframe will resize to fit its content height
-- `data-iframe-min-height` / `data-iframe-max-height` – optional min/max height bounds for auto-resize
-
-You can also mount the iframe programmatically:
-
-```html
-<script>
-    const { mountIframe } = window.LuliChatSupport;
-    const { id, iframe, unmount } = mountIframe(
-      {
-        apiKey: "YOUR_API_KEY",
-        position: "bottom-right",
-        primaryColor: "#4f46e5",
-      },
-      {
-        width: "360px",
-        height: "auto", // optional; if omitted, set autoResize: true to fit content
-        autoResize: true,
-        minHeight: 300, // optional
-        maxHeight: 700, // optional
-      }
-    );
-    // later: unmount()
-    // or: window.LuliChatSupport.unmountIframe(id)
-    // or: window.LuliChatSupport.unmountAll()
-    // You can also set a custom stylesheet URL inside the iframe via styleHref:
-    // mountIframe(config, { styleHref: 'https://cdn.example.com/lulichat.css' })
-  }
-</script>
-```
-
-Notes:
-
-- Stylesheet injection is automatic for both normal and iframe modes. If your `style.css` is not next to the UMD script, set `data-style-href` on the script or pass `styleHref` to `mountIframe`.
-- In auto-resize mode, the iframe height tracks the content using `ResizeObserver` (with a polling fallback). Min/max heights are respected if provided.
-
-### Zero-JS iframe embedding (static frame)
-
-If you want to embed the chat without placing any script tags on the parent page (just an `<iframe>`), you can use the provided `frame.html` (or host a copy of it).
+---
 
-Example:
+## 4. JavaScript / Programmatic API
 
-```html
-<iframe
-  src="/path/to/frame.html?apiKey=YOUR_API_KEY&baseUrl=https://api.example.com&position=bottom-right&primaryColor=%234f46e5"
-  width="380"
-  height="600"
-  style="border:0;background:transparent"
-  loading="lazy"
-></iframe>
-```
-
-Supported query parameters (same semantics as data-\*):
+When loaded via a script tag, the widget registers a global `window.LuliChatSupport` object:
 
-| Param              | Description                                                |
-| ------------------ | ---------------------------------------------------------- | ----------- | --------- | -------- |
-| apiKey             | Required API key                                           |
-| baseUrl            | API base override                                          |
-| position           | bottom-right                                               | bottom-left | top-right | top-left |
-| primaryColor       | Hex/CSS color                                              |
-| companyName        | Display name                                               |
-| welcomeMessage     | Initial auto-response message                              |
-| requireContactInfo | `true` or `false`                                          |
-| allowAnonymous     | `true` or `false`                                          |
-| configUrl          | URL returning JSON config to merge (query params override) |
-
-Config JSON shape (example returned by `configUrl`):
-
-```json
-{
-  "apiKey": "YOUR_API_KEY",
-  "companyName": "My Company",
-  "welcomeMessage": "Hello! How can we help?",
-  "primaryColor": "#4f46e5",
-  "requireContactInfo": true,
-  "allowAnonymous": false
-}
-```
-
-Precedence: query parameters override fields returned by `configUrl`.
-
-To host your own: copy `frame.html` and ensure the path to the standalone bundle script is correct (or swap to externalized bundle + peer scripts). The frame loads, then waits for `window.LuliChatSupport` and mounts internally; styles are auto-injected.
-
-## Hosted widget (production)
-
-We recommend hosting a small, versioned bundle set under:
-
-https://app.lulichat.com/widget/<version>/
-
-Each version folder contains:
-
-- `lulichat-widget.js` – loader clients include in their pages
-- `lulichat-widget.html` – the frame loaded by the loader
-- `dist/style.css` – stylesheet
-- `lulichat-widget-standalone.umd.js` – the standalone bundle (copied/renamed from the build)
-
-There is also a convenience alias:
-
-https://app.lulichat.com/widget/latest/
-
-Use `latest` if you want automatic upgrades; pin a specific `<version>` for stability.
-
-### Client usage (loader)
-
-```html
-<script
-  src="https://app.lulichat.com/widget/latest/lulichat-widget.js"
-  data-api-key="YOUR_API_KEY"
-  data-base-url="https://api.lulichat.com"
-  data-position="bottom-right"
-  data-primary-color="#4f46e5"
-  defer
-></script>
-```
-
-The loader computes its base URL from its own `src` and injects an iframe pointing to `.../lulichat-widget.html` with your `data-*` passed as query params. It also auto-resizes the iframe based on messages from the frame.
-
-#
-
-### Passing options via data attributes
-
-Supported attributes (all optional except api-key):
-
-| Attribute          | Purpose                                                 |
-| ------------------ | ------------------------------------------------------- |
-| data-api-key       | Your public API key for auth/identification             |
-| data-company-name  | Display name in header                                  |
-| data-position      | one of: bottom-right, bottom-left, top-right, top-left  |
-| data-primary-color | Hex or CSS color used as primary accent                 |
-| data-container     | CSS selector for a custom mount node (defaults to body) |
-| data-style-href    | Optional absolute URL to the CSS file if not colocated  |
-
-Programmatic mount accepts the same properties plus `baseUrl` and feature flags like `allowAnonymous`.
-
-```
-
-## API
-
-### Global Embed API
-
-`window.LuliChatSupport.mount(options)` – mounts the widget, returns an id.
-
-`window.LuliChatSupport.unmount(id)` – unmounts a specific instance.
-
-`window.LuliChatSupport.unmountAll()` – removes all mounted instances.
-
-`window.LuliChatSupport.initFromScript()` – reads the current script tag's `data-*` attributes and auto‑mounts.
-
-### React Usage
-
-Import the default export `LuliChat` for React integration; styling is in `dist/style.css`.
-
-## Contributing
-
-Contributions are welcome! Please open an issue or submit a pull request for any improvements or bug fixes.
+- `window.LuliChatSupport.mount(config, targetSelector?)`: Mounts the widget programmatically.
+- `window.LuliChatSupport.unmount(id)`: Unmounts a specific widget instance by ID.
+- `window.LuliChatSupport.unmountAll()`: Removes all mounted widget instances.
+- `window.LuliChatSupport.initFromScript()`: Reads properties from the current `<script>` tag and initializes the widget.
 
 ## License
 
-This project is licensed under the MIT License. See the LICENSE file for more details.
-```
+This project is licensed under the MIT License.