@data-netmonk/mona-chat-widget 2.6.6 → 2.6.8

package/README.md

@@ -18,7 +18,7 @@ Chat widget package developed by Netmonk data & solution team to be imported in
 
 ✅ **Previous Non-breaking Changes (`v2.6.1`):**
 1. **Built-in voice mode button** - Chat widget now includes a microphone button to toggle voice mode directly from the input area
-2. **Speech-to-text flow for voice mode** - Recorded user audio is sent to the configured `VITE_STT_ENDPOINT`, then the transcription is forwarded as a normal chat message
+2. **Speech-to-text flow for voice mode** - Recorded user audio is sent to the configured STT endpoint, then the transcription is forwarded as a normal chat message
 3. **Phoneme-driven avatar animation** - The widget can animate Mona's avatar during TTS playback based on phoneme/viseme IDs returned by the backend
 4. **Supported phoneme IDs** - `A`, `BP`, `ChJ`, `E`, `FV`, `I`, `KG`, `L`, `M`, `O`, `SZ`, `U`
 
@@ -93,83 +93,97 @@ Chat widget package developed by Netmonk data & solution team to be imported in
 
 ## 🚅 Quick start
 
-### Prerequisites
-
 ---
 
-1. Install dependencies
-   ```
-   npm install --legacy-peer-deps
-   ```
-2. Copy .env.example
-   ```
-   cp .env.example .env
-   ```
-3. Populate .env
-4. Optional speech endpoints
-
-  To enable voice mode and phoneme-based avatar animation, set these environment variables in your `.env` file:
-  ```
-  VITE_STT_ENDPOINT=https://voice.netmonk-ai.tech/stt
-  VITE_STT_API_KEY=
-  VITE_STT_API_KEY_HEADER=x-api-key
-  VITE_STT_API_KEY_PREFIX=
-  VITE_TTS_ENDPOINT=https://your-tts-service.example.com/synthesize
-  VITE_TTS_API_KEY=
-  VITE_TTS_API_KEY_HEADER=Authorization
-  VITE_TTS_API_KEY_PREFIX=Bearer
-  VITE_PREFER_WEBHOOK_TTS=true
-  VITE_TTS_MINIO_OBJECT_ENDPOINT=http://localhost:8000/minio/object
-  VITE_TTS_MINIO_API_KEY=
-  VITE_TTS_MINIO_API_KEY_HEADER=X-API-Key
-  VITE_TTS_MINIO_API_KEY_PREFIX=
-  VITE_TTS_MINIO_BUCKET=chatbot-tts
-  VITE_TTS_MINIO_DOWNLOAD=false
-  ```
-
-  `VITE_STT_ENDPOINT` is used by the built-in mic button to transcribe recorded audio.
-  For the Netmonk STT service, set `VITE_STT_API_KEY_HEADER=x-api-key` and leave `VITE_STT_API_KEY_PREFIX` empty so the widget sends the raw key value without `Bearer`.
-  `VITE_PREFER_WEBHOOK_TTS=true` makes the widget prioritize TTS assets from webhook response (for example `tts_assets.items[].audio_object_key`) and use `VITE_TTS_ENDPOINT` only as fallback.
-  Widget tidak lagi konek langsung ke MinIO. Object diambil lewat endpoint voice-engine:
-  `GET /minio/object?object_key=<key>&bucket=<bucket>&download=<true|false>`.
-  `VITE_TTS_MINIO_API_KEY` opsional. Jika diisi, widget mengirim header `X-API-Key` (atau header custom via `VITE_TTS_MINIO_API_KEY_HEADER`).
-  `VITE_TTS_MINIO_BUCKET` dipakai sebagai default bucket bila payload webhook tidak mengirim bucket.
-  Set `VITE_TTS_MINIO_DOWNLOAD=true` jika ingin force download mode saat fetch object.
-  `VITE_TTS_ENDPOINT` is used for fallback TTS playback.
-  The widget expects the TTS response body to contain raw audio binary such as `audio/wav`, and reads lip-sync metadata from `x-tts-visemes-b64`, `x-tts-phonemes-b64`, and `x-tts-phoneme-timeline-b64` response headers.
-  If your TTS endpoint is called cross-origin, the server must expose those headers with `Access-Control-Expose-Headers`.
-  If your TTS service uses a different header such as `x-api-key`, set `VITE_TTS_API_KEY_HEADER=x-api-key` and leave the prefix empty.
-  If you are consuming the published package inside another project, prefer passing these values via the `voiceConfig` or `widgetConfig` props because the host app `.env` is not injected into an already-built library bundle.
-  You can also set runtime defaults on the host page before mounting the widget via `window.__MONA_WIDGET_RUNTIME_CONFIG__`.
-  Example:
-  ```jsx
-  <ChatWidget
-    sourceId="source456"
-    webhookUrl="https://api.example.com/webhook"
-    voiceConfig={{
-      sttEndpoint: "https://voice.netmonk-ai.tech/stt",
-      sttApiKey: "your-key",
-      sttApiKeyHeader: "x-api-key",
-      sttApiKeyPrefix: "",
-      ttsEndpoint: "https://voice.example.com/tts",
-      ttsApiKey: "your-key",
-      ttsApiKeyHeader: "Authorization",
-      ttsApiKeyPrefix: "Bearer",
-    }}
-  />
-  ```
-5. Optional TTS debug logging
-   
-  To inspect TTS queue and playback lifecycle in browser console, set `VITE_DEBUG_TTS=true` in your `.env` file.
-  Keep this disabled in production to avoid noisy logs.
-6. Enable mock mode (optional)
-   
-   To test the chat widget without a backend server, set `VITE_USE_MOCK_RESPONSES=true` in your `.env` file. The widget will respond to messages like:
-   - "start", "hello", "hi", "halo" - Greeting messages
-   - "help", "bantuan" - Help information
-   - "terima kasih", "thank you" - Acknowledgments
-   - "bye", "goodbye" - Farewell messages
-   - And more! Check `src/components/ChatWidget/utils/helpers.js` for full list
+1. Install the package
+   ```bash
+   npm install @data-netmonk/mona-chat-widget
+   ```
+2. Render the widget with the minimum required props
+   ```jsx
+   import { ChatWidget } from "@data-netmonk/mona-chat-widget";
+
+   export default function App() {
+     return (
+       <ChatWidget
+         sourceId="source-123"
+         webhookUrl="https://api.example.com/webhook"
+       />
+     );
+   }
+   ```
+3. Choose the usage mode you need
+
+**1. Basic mode**
+
+```jsx
+<ChatWidget
+  sourceId="source-123"
+  webhookUrl="https://api.example.com/webhook"
+/>
+```
+
+**2. With auth mode**
+
+```jsx
+<ChatWidget
+  sourceId="source-123"
+  webhookUrl="https://api.example.com/webhook"
+  userId="user-123"
+  username="John"
+  authUrl="https://api.example.com/login/chatwidget"
+/>
+```
+
+**3. With voice mode**
+
+```jsx
+<ChatWidget
+  sourceId="source-123"
+  webhookUrl="https://api.example.com/webhook"
+  voiceConfig={{
+    sttEndpoint: "https://voice.example.com/stt",
+    sttApiKey: "your-stt-key",
+    ttsEndpoint: "https://voice.example.com/tts",
+    ttsApiKey: "your-tts-key",
+    ttsMinioObjectEndpoint: "https://voice.example.com/minio/object",
+    ttsMinioApiKey: "your-minio-key",
+    ttsMinioBucket: "chatbot-tts",
+  }}
+/>
+```
+
+**4. Full props example**
+
+```jsx
+<ChatWidget
+  sourceId="source-123"
+  webhookUrl="https://api.example.com/webhook"
+  userId="user-123"
+  authUrl="https://api.example.com/login/chatwidget"
+  username="John Doe"
+  voiceConfig={{
+    sttEndpoint: "https://voice.example.com/stt",
+    sttApiKey: "your-stt-key",
+    ttsEndpoint: "https://voice.example.com/tts",
+    ttsApiKey: "your-tts-key",
+    ttsMinioObjectEndpoint: "https://voice.example.com/minio/object",
+    ttsMinioApiKey: "your-minio-key",
+    ttsMinioBucket: "chatbot-tts",
+  }}
+/>
+```
+
+**Common optional props**
+
+- `userId`: ID user login. Jika tidak diisi, widget akan memakai guest visitor ID.
+- `username`: nama yang dikirim bersama session chat.
+- `authUrl`: endpoint auth/refresh khusus chat widget.
+- `data`: custom payload tambahan untuk backend.
+- `voiceConfig`: aktifkan voice mode, STT, TTS, dan phoneme avatar bila dibutuhkan.
+- `showLauncher`, `autoOpen`, `enabled`, `position`, `width`, `height`: untuk perilaku dan layout widget.
+
+By default, STT and TTS requests send the API key using `x-api-key` without any prefix. MinIO object fetch uses `X-API-Key`. If your provider needs a different auth format, override it through `voiceConfig`.
 
 ---
 
@@ -180,8 +194,8 @@ Chat widget package developed by Netmonk data & solution team to be imported in
 The chat widget includes a built-in mock mode for testing and demonstrations without requiring a backend server.
 
 **To enable mock mode:**
-1. Set `VITE_USE_MOCK_RESPONSES=true` in your `.env` file
-2. Run the app normally with `npm run dev`
+1. Pass `widgetConfig={{ useMockResponses: true }}`
+2. Render the widget normally
 
 **Mock responses include:**
 - Greetings (hello, hi, halo, start) - with interactive buttons
@@ -353,9 +367,9 @@ For responses with buttons:
 
 ---
 
-The widget now includes a built-in microphone button in the input area. Clicking the button toggles voice mode, requests microphone access, records speech, sends the recorded audio to `VITE_STT_ENDPOINT`, and forwards the returned transcription as a regular user message.
+The widget now includes a built-in microphone button in the input area. Clicking the button toggles voice mode, requests microphone access, records speech, sends the recorded audio to `voiceConfig.sttEndpoint`, and forwards the returned transcription as a regular user message.
 
-If `VITE_STT_API_KEY` is set, the STT request also includes the configured auth header. For `https://voice.netmonk-ai.tech/stt`, use `x-api-key` without any prefix. Other providers can still use `Authorization: Bearer <key>` or any custom header via `.env`.
+If `voiceConfig.sttApiKey` is set, the STT request includes `x-api-key: <key>` by default. If another provider needs a different auth format, override it through `voiceConfig`.
 
 **Expected STT request/response shape:**
 
@@ -407,45 +421,46 @@ Phoneme IDs are normalized case-insensitively in the widget, so values such as `
 }
 ```
 
-When this payload is available, the widget resolves MinIO object keys first for audio and timeline metadata. If no usable asset is found, it falls back to `VITE_TTS_ENDPOINT`.
+When this payload is available, the widget resolves MinIO object keys first for audio and timeline metadata. If no usable asset is found, it falls back to `voiceConfig.ttsEndpoint`.
 
 **Expected TTS response shape:**
 
 ```text
 body: <raw WAV or other audio binary>
 content-type: audio/wav
-x-tts-visemes-b64: W3siaWQiOiJNIiwic3RhcnRNcyI6MCwiZW5kTXMiOjEyMH1d
-x-tts-phonemes-b64: TSBBCg==
-x-tts-phoneme-timeline-b64: W3sicGhvbmVtZSI6Ik0iLCJzdGFydE1zIjowLCJlbmRNcyI6MTIwfV0=
+x-tts-metadata-id: 7d8f6a0f0f684e97b7b8d8db67f4f3a1
+x-tts-metadata-path: /tts/metadata/7d8f6a0f0f684e97b7b8d8db67f4f3a1
+x-tts-duration-ms: 120
 ```
 
-`x-tts-phonemes-b64` is the legacy phoneme string, while `x-tts-phoneme-timeline-b64` is the timed phoneme timeline. The base64 headers should decode as:
-
-Decoded `x-tts-phonemes-b64`:
-
-```text
-M A
-```
-
-Decoded `x-tts-phoneme-timeline-b64`:
+Metadata lengkap diambil dari endpoint metadata yang ditunjuk header tadi:
 
 ```json
-[
-  { "phoneme": "M", "startMs": 0, "endMs": 120 }
-]
+GET /tts/metadata/7d8f6a0f0f684e97b7b8d8db67f4f3a1
+{
+  "id": "7d8f6a0f0f684e97b7b8d8db67f4f3a1",
+  "phonemes": "M A",
+  "phoneme_timeline": [
+    { "phoneme": "M", "startMs": 0, "endMs": 120 }
+  ],
+  "visemes": [
+    { "id": "M", "startMs": 0, "endMs": 120 },
+    { "id": "A", "startMs": 121, "endMs": 260 },
+    { "id": "SZ", "startMs": 261, "endMs": 420 }
+  ],
+  "duration_ms": 420
+}
 ```
 
-Decoded `x-tts-visemes-b64`:
+Widget ini masih mendukung header base64 lama sebagai fallback:
 
-```json
-[
-  { "id": "M", "startMs": 0, "endMs": 120 },
-  { "id": "A", "startMs": 121, "endMs": 260 },
-  { "id": "SZ", "startMs": 261, "endMs": 420 }
-]
+```text
+x-tts-visemes-b64
+x-tts-phonemes-b64
+x-tts-phoneme-timeline-b64
 ```
 
-The widget still supports the older JSON body format as a fallback, but header-based metadata is now the preferred format for binary audio responses.
+Widget juga masih mendukung format JSON body lama sebagai fallback, tetapi untuk audio binary format metadata endpoint di atas sekarang jadi jalur utama yang direkomendasikan.
 
 ---