@onedeskpro/chatbot-core 0.2.0 → 0.3.0

package/README.md

@@ -28,7 +28,23 @@ await chatbot.init({
 });
 ```
 
-`init` mounts the widget and connects to the Onedesk Pro API. Only `apiKey` is required — use the publishable workspace API key, never a server secret.
+`init` connects to the Onedesk Pro API and adds the widget to the page once the agent can reply. Only `apiKey` is required — use the publishable workspace API key, never a server secret.
+
+### When the widget appears
+
+Nothing is added to the page straight away. `init` first checks that the Onedesk Pro server is reachable and that the agent is ready to reply, and the launcher appears only once both hold and a returning visitor's identity has been checked:
+
+| Situation | `blockReason` | What happens |
+| --- | --- | --- |
+| Ready | `null` | The launcher appears (and the panel opens, with `autoOpen`). |
+| The server cannot be reached, times out, or answers with a 5xx | `server-unavailable` | Stays hidden and checks again after 5, 15, 30 and 60 seconds, then gives up until the next page load. |
+| The agent has no system prompt or no knowledge base | `no-prompt`, `no-collections` | Stays hidden. |
+| The platform's AI models are not configured | `ai-unavailable` | Stays hidden. |
+| The workspace has used its AI token budget | `no-credits` | Stays hidden. |
+| No agent is assigned to the Website channel | `no-agent` | Stays hidden. |
+| The API key is rejected or the site's origin is not allowed | `null`, with `error` set | Stays hidden. |
+
+`init` resolves after the first check, and the `ready` event fires once the outcome is settled: when the widget appears, when a configuration problem rules it out, or when the last retry fails. A custom UI built on the state can show `blockReason` to explain why chat is unavailable.
 
 ### Visitor identification
 
@@ -81,6 +97,8 @@ The IIFE build exposes a `window.OnedeskProChatbot` global:
 | `init(options)` | Mounts the widget and loads remote config. Returns a promise. |
 | `submitIdentify({ name, phone, email? })` | Identifies the visitor and unlocks the chat. Returns a promise. |
 | `sendMessage(text)` | Sends a message and, in `ai` mode, appends the reply. Returns a promise that rejects if the visitor has not identified. |
+| `sendAttachments(files, text?)` | Sends up to 10 files (10 MB each) as one media message, with `text` as the caption. Each file is uploaded through the API first; the message sits in `messages` with `pending: true` and local previews until then. Rejects if the visitor has not identified; a file over the limits sets `error` instead. |
+| `sendVoice(recording)` | Sends a voice note. `recording` is `{ blob, mimeType?, durationSeconds }`, as `VoiceRecorder` produces; it is re-encoded as mono WAV with a waveform where Web Audio allows, uploaded, and stored as a `voice` message. Rejects if the visitor has not identified. |
 | `requestHuman()` | Escalates the conversation to a human agent. Does nothing unless the mode is `ai` and a conversation has started. Returns a promise. |
 | `open()` / `close()` / `toggle()` | Control widget visibility. |
 | `resetSession()` | Clears a `closed` conversation so the visitor can start a new one. Does nothing in any other mode. |
@@ -111,10 +129,10 @@ The IIFE build exposes a `window.OnedeskProChatbot` global:
 | --- | --- | --- |
 | `isOpen` | `boolean` | The panel is showing. |
 | `isLoading` | `boolean` | A send, identify, or human request is in flight. |
-| `isReady` | `boolean` | Config loaded and the agent can answer. |
+| `isReady` | `boolean` | The server answered and the agent can reply; the widget is on the page. |
 | `needsIdentify` | `boolean` | The visitor has not identified yet. |
-| `blockReason` | `ChatbotBlockReason` | Why the agent cannot answer, or `null`. |
-| `messages` | `ChatMessage[]` | The conversation so far. `message.type` is `'human'`, `'ai'`, or `'agent'`. |
+| `blockReason` | `ChatbotBlockReason` | Why the agent cannot answer, or `null`. See [When the widget appears](#when-the-widget-appears). |
+| `messages` | `ChatMessage[]` | The conversation so far. `message.type` is `'human'`, `'ai'`, or `'agent'`. A media message carries `message.attachments` (`type`, `url`, `fileName`, `size`) and `pending: true` while its files upload. |
 | `visitorToken` | `string \| null` | The identified visitor's token. |
 | `visitorName` | `string \| null` | The identified visitor's name. |
 | `mode` | `ChatbotTicketMode` | `'ai'`, `'waiting'`, `'human'`, or `'closed'`. |
@@ -126,7 +144,7 @@ The IIFE build exposes a `window.OnedeskProChatbot` global:
 | --- | --- | --- |
 | `message` | `ChatMessage` | A message is added — visitor, AI, and human agent alike. |
 | `state-change` | `ChatbotState` | Any state changes, including `isLoading` while a reply is in flight. |
-| `ready` | — | Init finished and readiness has been checked. |
+| `ready` | — | The readiness check settled: the widget appeared, or it will not (see `blockReason` and `error`). |
 | `open` / `close` | — | The panel is shown or hidden. |
 | `ticket-status` | `TicketStatusData` | The mode changed — on restore, after a send, or pushed live. |
 | `human-requested` | — | `requestHuman()` succeeded. |
@@ -142,7 +160,9 @@ off(); // unsubscribe
 
 ## Also exported
 
-`ApiClient`, `SdkSocket`, `resolveSdkSocketUrl`, `EventEmitter`, `SessionManager`, `isChatbotRequestError`, `DEFAULT_API_BASE_URL`, `DEFAULT_REQUEST_TIMEOUT_MS`, the `ChatbotRequestError` and `SdkSocketConnectOptions` types, and every type from `@onedeskpro/chatbot-types`.
+`ApiClient`, `SdkSocket`, `resolveSdkSocketUrl`, `EventEmitter`, `SessionManager`, `VoiceRecorder`, `isChatbotRequestError`, `DEFAULT_API_BASE_URL`, `DEFAULT_REQUEST_TIMEOUT_MS`, `SDK_UPLOAD_MAX_BYTES`, `SDK_CHAT_MAX_ATTACHMENTS`, `VOICE_MAX_DURATION_SECONDS`, the `ChatbotRequestError`, `SdkSocketConnectOptions`, `VoiceRecorderSnapshot` and `VoiceRecorderState` types, and every type from `@onedeskpro/chatbot-types`.
+
+`VoiceRecorder` records with `MediaRecorder` for custom UIs: `new VoiceRecorder(onChange)`, then `start()`, `stop()` (resolves with the recording to pass to `sendVoice`), `cancel()`, and `destroy()`. `onChange` receives `{ state, elapsedSeconds, level, result }`. Recording stops on its own at `VOICE_MAX_DURATION_SECONDS` (5 minutes).
 
 `SessionManager` is deprecated. It is now the visitor token store and is kept only so existing imports keep resolving.