@hubtalk-ai/web-sdk 0.2.0 → 0.3.1

package/README.ru.md

@@ -0,0 +1,338 @@
+# @hubtalk-ai/web-sdk
+
+*[English version — `README.md`](README.md).*
+
+Браузерный SDK: голосовой звонок с агентом HubTalk AI Conversation Flow
+прямо со страницы вашего сайта. Тонкая обёртка над
+[`livekit-client`](https://github.com/livekit/client-sdk-js); ключа Web API
+SDK не держит и в HTTP-API платформы не ходит.
+
+Интеграция состоит из трёх шагов:
+
+1. Ваш бэкенд зовёт `POST /v1/calls/web` ключом Web API воркспейса —
+   в теле `agent_id` и, если нужно, динамические переменные звонка.
+2. Платформа отвечает `201` и сессией: `{access_token, url, …}`.
+3. Страница отдаёт это тело в `startCall()` — дальше разговор идёт между
+   браузером и платформой, а состояние приходит событиями.
+
+Ключ Web API остаётся на вашем сервере и в браузер не попадает. Контракт
+эндпоинта — в схеме платформы: `{BASE_URL}/docs`.
+
+## Установка
+
+```bash
+npm install @hubtalk-ai/web-sdk
+```
+
+```ts
+import { VoiceClient } from '@hubtalk-ai/web-sdk';
+```
+
+Без сборщика — самодостаточный бандл со своей копией `livekit-client`:
+
+```html
+<script src="voice-client.bundle.js"></script>
+<script>
+  const client = new VoiceClient();
+</script>
+```
+
+## Быстрый старт
+
+```ts
+const client = new VoiceClient();
+
+startCallButton.addEventListener('click', async () => {
+  // session — то, что ваш бэкенд вернул из POST /v1/calls/web
+  const session = await fetch('/api/start-voice-call', { method: 'POST' }).then((r) => r.json());
+  await client.startCall(session);
+});
+
+client.on('transcript', ({ role, text, final, id }) => renderBubble(id, role, text, final));
+client.on('callEnded', ({ reason }) => console.log('call ended:', reason));
+
+endCallButton.addEventListener('click', () => client.stopCall());
+```
+
+**`startCall` вызывайте внутри обработчика клика или тапа** — жест
+посетителя нужен браузеру и для звука агента, и для доступа к микрофону.
+На iOS Safari сетевой запрос между кликом и `startCall()` может этот жест
+съесть: получайте сессию заранее.
+
+## API
+
+### `new VoiceClient(options?)`
+
+| Опция | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `audioContainer` | `HTMLElement` | скрытый `<div>` от SDK | Куда добавляются `<audio>`-элементы агента. |
+| `logger` | `{ error, debug }` | `console` | Свой приёмник логов; токены маскируются в любом случае. |
+| `logLevel` | `'silent' \| 'error' \| 'debug'` | `'error'` | Подробный лог включается явно. |
+| `connectTimeoutMs` | `number` | 15 с | Таймаут подключения. |
+
+### Методы
+
+| Метод | Поведение |
+|---|---|
+| `startCall(session, options?)` | Подключается и публикует микрофон. Принимает ответ `POST /v1/calls/web` как есть (лишние поля игнорируются) либо `{accessToken, url}`. Второй вызов при активном звонке — `ALREADY_IN_CALL`. `options.audio: false` — звонок только текстом. |
+| `stopCall()` | Завершает звонок. Без активного звонка ничего не делает и не даёт ошибки. |
+| `sendText(text)` | Отправляет текстовую реплику посетителя; агент прерывает речь и отвечает на неё как на сказанное вслух. Вне звонка — `NOT_IN_CALL`; длиннее 1000 символов обрезается. Своё сообщение SDK в чат не кладёт: оно вернётся событием `transcript` с `role: 'user'`. |
+| `getState()` | Состояние соединения: `idle \| connecting \| connected \| reconnecting \| disconnected \| error`. |
+| `getAgentState()` | Чем занят агент: `unknown \| initializing \| listening \| thinking \| speaking`. |
+| `getCallId()` | Идентификатор звонка (тот же, что в `GET /v1/calls/{call_id}`), или `null` до подключения. |
+| `on` / `off` / `once` | Подписка, отписка, подписка на один раз. |
+| `destroy()` | Останавливает звонок и освобождает ресурсы; экземпляр больше непригоден. |
+
+### События
+
+| Событие | Полезная нагрузка |
+|---|---|
+| `callStarted` | `{ callId }` |
+| `callEnded` | `{ callId, reason }` — `local` (`stopCall`), `remote` (завершил агент), `connection_lost`, `error` |
+| `connectionStateChanged` | `{ state, previous }` |
+| `agentStateChanged` | `{ state, previous }` |
+| `agentSpeakingStarted` / `agentSpeakingStopped` | `{}` |
+| `transcript` | `{ role, text, final, id }` — реплика разговора; `role`: `user` \| `agent`. Пока `final: false`, реплика растёт: рисуйте один пузырь на `id`. |
+| `error` | `VoiceError` |
+
+### Звонок только текстом
+
+`startCall(session, { audio: false })` — тот же звонок без микрофона и без
+звука: разрешение браузер не спрашивает, разговор идёт текстом (`sendText()`
+и `transcript`). Режим для посетителя, который не может или не хочет
+говорить. Агент при этом всё равно синтезирует речь, поэтому текст приходит
+в темпе речи, а звонок стоит столько же, сколько голосовой.
+
+```ts
+await client.startCall(session, { audio: false });
+```
+
+### Коды ошибок
+
+Любой отказ — `VoiceError`: `{ code, message, state, cause? }`. Разбирайте
+`code`; `message` — служебная строка, а текст для посетителя пишете вы.
+
+| Код | Когда |
+|---|---|
+| `INVALID_PARAMS` | В сессии нет `access_token` или `url` |
+| `WEBRTC_UNSUPPORTED` | Браузер не поддерживает WebRTC либо страница не на HTTPS |
+| `MICROPHONE_PERMISSION_DENIED` | Посетитель запретил микрофон |
+| `MICROPHONE_UNAVAILABLE` | Микрофона нет или он занят |
+| `TOKEN_EXPIRED` | Сессия протухла до начала звонка |
+| `TOKEN_INVALID` | Сервер отклонил токен сессии |
+| `CONNECTION_FAILED` | Не удалось подключиться |
+| `CONNECTION_LOST` | Связь пропала и не восстановилась |
+| `ALREADY_IN_CALL` | Звонок уже идёт |
+| `NOT_IN_CALL` | `sendText` вне звонка |
+| `SERVER_ERROR` | Прочий сбой сервиса |
+
+Токен сессии живёт 2 часа и не обновляется: минтите свежую сессию на каждый
+звонок, а не держите одну на открытой странице.
+
+## Ссылки-демо
+
+Свой бэкенд нужен не всегда. Кабинет платформы выдаёт временную ссылку на
+один опубликованный агент — со сроком, потолком числа звонков и отзывом в
+один клик. Страница за ссылкой минтит сессию сама и ведёт звонок этим же
+SDK, так что послушать агента можно без аккаунта, ключа и настройки.
+
+Ссылка-демо — когда человеку нужно просто поговорить с агентом. Свой
+бэкенд — когда звонок начинается с вашего сайта, на вашем домене, с
+переменными, которые знает ваша система.
+
+## Пример интеграции
+
+В `example/` лежит рабочая пара «бэкенд + страница», с которой удобно
+начинать: `server.py` держит ключ Web API и минтит сессию, а страницы
+показывают виджет звонка. `/` и `/avatar` используют готовый компонент SDK;
+остальные страницы остаются примерами на основе headless-клиента.
+
+```bash
+npm install && npm run build
+cp .env.example .env       # CFLOW_API_URL, CFLOW_API_KEY, CFLOW_AGENT_ID
+python3 example/server.py  # http://localhost:8000/
+```
+
+| Страница | Что показывает |
+|---|---|
+| `/` | сайт с виджетом звонка в углу |
+| `/avatar` | перетаскиваемый аватар: живой AI-аватар после соединения, клип ведущего из примера как failover |
+| `/call` | звонок во всю страницу с брендированной колонкой |
+| `/free` | то же без настроек: агент, переменные и ключ набираются в форме |
+| `/file` | `/free`, плюс mp3 или wav, который играет в звонок вместо микрофона |
+
+Что стоит унести из примера в свою интеграцию: ключ Web API живёт только на
+сервере, браузер называет лишь значения переменных, а сервер принимает
+значения только тех переменных, которые сам объявил. Компонент — `src/widget.ts`; `example/demo-widget.js` передаёт callback
+бэкенда и использует формы из `example/demo-call.js`.
+
+### Демо-стенд
+
+Сервер примера ставится под systemd unit'ом
+`example/hubtalk-webrtc-example.service` (перед установкой поправьте `User`
+и `WorkingDirectory`), за HTTPS-прокси — браузеру нужен защищённый контекст.
+Пример конфигурации прокси — `example/caller-widget.demo.cyberdev.kz.Caddyfile`.
+
+```bash
+npm run build   # обязательно: dist/ в gitignore, git pull бандл не обновляет
+sudo systemctl restart hubtalk-webrtc-example
+```
+
+## Готовый виджет (VPT-857)
+
+**Что работает сегодня.** Аватарный режим работает с любой текущей
+платформой HubTalk: круг играет встроенные клипы-failover (постер, петля
+«слушает», петля «говорит», Video.js), а звонок — обычный голосовой. Живой
+AI-аватар, описанный ниже, требует поддержки платформы, которая ещё не
+выкачена; до тех пор каждый звонок показывает клипы, и с её появлением в
+интеграции ничего не меняется — виджет сам переключится на живое видео.
+
+**Попробовать за пять минут.**
+
+1. `npm ci && npm run build` в этом репозитории.
+2. Скопируйте `.env.example` в `.env` в корне репозитория, впишите Web API key и
+   имя агента.
+3. `python3 example/server.py`, откройте `http://127.0.0.1:8000/avatar`.
+   `/` — тот же виджет в стандартном режиме, `/free` — рукописный пример.
+4. Нажмите круг — звонок, ещё раз — mute; Chat открывает транскрипт и End
+   call. Замените три файла в `example/` своим постером и беззвучными
+   клипами (см. `example/AVATAR-MEDIA.md`), чтобы увидеть своего ведущего.
+
+Опциональный экспорт — `@hubtalk-ai/web-sdk/widget`:
+`mountWidget(options: WidgetOptions): WidgetHandle`; типы `AvatarMedia`,
+`CreateSessionContext`, `WidgetOptions`, `WidgetHandle` экспортируются из
+того же пути.
+
+```ts
+import { mountWidget } from '@hubtalk-ai/web-sdk/widget';
+import '@hubtalk-ai/web-sdk/widget.css';
+const widget = mountWidget({
+  container: document.getElementById('support')!,
+  mode: 'avatar',
+  createSession: async ({ avatar }) => {
+    // avatar === true в аватарном режиме: бэкенд передаёт его как
+    // `avatar: true` в POST /v1/calls/web (см. «Живой аватар» ниже)
+    const response = await fetch('/api/session', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ avatar }),
+    });
+    if (!response.ok) throw new Error('Session unavailable');
+    return response.json();
+  },
+  // клипы-failover: показываются, пока живого видео аватара нет
+  avatar: {
+    posterUrl: '/presenter/poster.jpg',
+    listeningVideoUrl: '/presenter/listening.mp4',
+    speakingVideoUrl: '/presenter/speaking.mp4',
+    size: 140, // диаметр круга в px, необязательно; это значение по умолчанию
+  },
+});
+// При удалении страницы/компонента:
+widget.destroy();
+```
+
+Без сборщика подключите `/sdk/widget.css` и `/sdk/widget.bundle.js` обычными
+`link`/`script`; тот же метод доступен как `HubTalkWidget.mountWidget(options)`.
+`container` и `createSession` обязательны; `mode` по умолчанию `standard`.
+В режиме `avatar` обязательны все три URL (медиа failover); необязательный
+`avatar.size` задаёт диаметр круга в пикселях (по умолчанию 140, на
+телефонах 6/7 от него) — либо переменная `--ht-avatar-size` на `.ht-widget`
+в вашем CSS. `createSession`
+вызывается с `{ avatar: boolean }` — `true` в аватарном режиме, `false` в
+стандартном; колбэки без аргумента продолжают работать.
+`renderCallDetails(container)` опционально создаёт форму; callback сессии
+читает её текущие значения через замыкание. `destroy()` идемпотентно
+завершает звонок и удаляет свой DOM/медиа. Пример — `example/demo-widget.js`;
+`/` показывает стандартный режим, `/avatar` — аватар. Web API key остаётся
+на сервере.
+
+### Живой аватар
+
+В аватарном режиме круг показывает **живое видео AI-аватара** — воркер
+аватара LiveKit входит в звонок от имени агента и публикует видео с губами,
+синхронизированными с голосом агента (провайдер Anam; стоковое лицо «Layla»
+по умолчанию, настраивается на агенте). Аватар стартует, только когда верны
+все три условия, иначе звонок идёт только со звуком и виджет показывает
+клипы-failover:
+
+1. ваш бэкенд передаёт просьбу виджета как `"avatar": true` в теле
+   `POST /v1/calls/web` (для платформы это просьба, не гарантия; форма ответа
+   не меняется);
+2. у агента включена настройка **AI-аватар** в редакторе HubTalk
+   (Settings → Additional → AI-аватар; по умолчанию выключена, только
+   каскадный пайплайн);
+3. на контуре платформы настроен провайдер аватара.
+
+Приоритет медиа, от старшего: **живое видео** → **клипы-failover**
+(`listeningVideoUrl`/`speakingVideoUrl`) → **постер**. Откат на клипы —
+штатное состояние, не ошибка: до звонка, секунды, пока аватар входит, агент
+с выключенным аватаром, медленный или недоступный провайдер, пропавшее
+посреди звонка видео. Пока идёт живое видео, клип-плеер стоит на паузе и
+спрятан (а если клип ещё не понадобился — не загружается вовсе); когда видео
+пропадает, клипы возобновляются. Живой `<video>` — muted, inline, без
+controls: голос всегда идёт звуковым путём SDK, никогда из видеоэлемента,
+поэтому слышен ровно один раз.
+
+Headless-интеграции получают тот же сигнал от `VoiceClient`: событие
+`agentVideoChanged: { available }` при подписке/пропадании видеотрека
+воркера (сброс в `false` на конце звонка, при неудачном старте и
+`destroy()`), метод `attachAgentVideo(element)` вешает текущий и любой
+поздний трек на ваш `<video>` и возвращает функцию отсоединения (вне звонка —
+no-op). Воркер — удалённый участник kind `agent`, чей атрибут
+`lk.publish_on_behalf` равен identity агента; состояние агента остаётся на
+его собственном `lk.agent.state`.
+
+**Раскрытие.** Пока идёт живое видео, на круге видна подпись **AI avatar**,
+она же — доступное описание круга. Вшитого водяного знака нет. Сообщить
+посетителю, что он говорит с ИИ, там, где этого требует юрисдикция, —
+обязанность интегратора; подпись помогает, но не заменяет её.
+
+Живое видео приходит по уже установленному соединению LiveKit: новых
+CSP-источников сверх `connect-src` и `media-src blob:` не нужно. Голос агента
+и видео аватара проходят через облако провайдера — согласуйте это с
+ответственным за данные перед включением настройки на регулируемом контуре.
+
+Круг запускает голосовой звонок, затем включает/выключает только микрофон
+посетителя. Голос агента продолжает звучать. Отдельная кнопка Chat открывает
+панель; End call внутри завершает звонок. Кнопка Chat внутри панели начинает
+текстовый звонок. Enter/Space активируют кнопки, фокус видим. Перетаскивание
+не запускает звонок и не переключает микрофон; позиция не сохраняется.
+
+Медиа failover — постер и два беззвучных H.264 MP4 одного человека с
+разрешённым использованием образа как AI-презентера. Точной синхронизации
+губ у клипов нет: speaking-клип следует состоянию агента; кольцо и текст
+показывают listening/speaking/muted/idle/connecting. Thinking не называется
+listening. При ошибке/запрете клипа и reduced motion остаётся постер, живое
+видео при reduced motion сохраняется; управление звонком работает.
+В пример включён ведущий из клипа Pexels (лицензия Pexels, источник и
+скрипт регенерации — `example/AVATAR-MEDIA.md`); это медиа примера, а не
+очищенный образ для вашего сайта — замените своим.
+
+Video.js закреплён на 8.24.0. ESM загружает его только для аватара и только
+при первой потребности в клипе;
+самодостаточный IIFE содержит библиотеку целиком, но создаёт player только
+для аватара. Headless-экспорты не импортируют виджет или Video.js. CSS
+подключается явно и ограничен корнем виджета.
+
+Нужен HTTPS. CSP: хост SDK — `script-src`/`style-src`, постер — `img-src`,
+клипы — `media-src`, бэкенд и LiveKit HTTPS/WSS — `connect-src`;
+для WebRTC нужен `media-src blob:`, для позиционирования и Video.js —
+`style-src-attr 'unsafe-inline'`. CDN не требуется. Ограничения хоста на
+медиа могут оставить только постер.
+
+`isMicrophoneEnabled()` изначально false; `setMicrophoneEnabled(enabled)`
+меняет только микрофон подключённого аудиозвонка. Событие
+`microphoneStateChanged: { enabled }` отражает подтверждённый результат;
+завершение сбрасывает false. Ошибка переключения сохраняет звонок и состояние.
+Вне подключённого аудиозвонка — `NOT_IN_CALL`, включая reconnecting.
+
+На iOS исходный жест может потеряться за запросом сессии. Событие
+`audioPlaybackBlocked` сохраняет соединение и показывает Enable sound;
+нажатие вызывает `resumeAudio()`. Повторный запрет — `AUDIO_PLAYBACK_BLOCKED`,
+без перепубликации микрофона. Запрет микрофона по-прежнему срывает старт.
+`stopCall()` завершает звонок, mute — нет.
+
+Проверки: `npm test`, `npm run lint`, `npm run format:check`, `npm run build`;
+браузеры — `npx playwright install chromium webkit && npm run test:browser`.
+Размеры сборки и оставшиеся проверки — `VALIDATION.md`.

package/dist/errors.d.ts

@@ -16,3 +16,4 @@ export declare function connectErrorCode(error: unknown): VoiceErrorCode;
 /** MediaDeviceFailure.getFailure — классификатор ошибок getUserMedia из
  * самого livekit-client (не переизобретаем разбор DOMException.name). */
 export declare function microphoneErrorCode(error: unknown): VoiceErrorCode;
+export declare function microphoneToggleErrorCode(error: unknown): VoiceErrorCode;

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export { VoiceClient } from './voice-client';
 export { VoiceCallError } from './errors';
-export type { AgentState, AgentStateChangedEvent, CallEndedEvent, CallEndedReason, CallStartedEvent, ConnectionState, ConnectionStateChangedEvent, LogLevel, Logger, StartCallOptions, StartCallParams, TranscriptEvent, VoiceClientEventHandler, VoiceClientEventMap, VoiceClientEventName, VoiceClientOptions, VoiceError, VoiceErrorCode, } from './types';
+export type { AgentState, AgentVideoChangedEvent, AgentStateChangedEvent, CallEndedEvent, CallEndedReason, CallStartedEvent, ConnectionState, ConnectionStateChangedEvent, LogLevel, Logger, StartCallOptions, StartCallParams, TranscriptEvent, VoiceClientEventHandler, VoiceClientEventMap, VoiceClientEventName, VoiceClientOptions, VoiceError, VoiceErrorCode, } from './types';