@ykurilov/agent-chat-voice 0.0.0-stage → 0.55.0

package/README.md

@@ -1,3 +1,299 @@
-# Temporary Holding Version
+# @ykurilov/agent-chat-voice
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Голосовой ввод для чата с агентом через Soniox: человек нажимает микрофон в поле ввода, слова появляются в поле
+по ходу речи, он правит и отправляет сам. Отдельное расширение: приложению без голоса пакет не нужен, а чат без него
+кнопки микрофона не рисует.
+
+Пакет про **диктовку в поле**. Голосовой разговор с агентом (говорит человек, отвечает голос) сюда не входит:
+для него будет отдельный пакет, а серверную часть связи с Soniox он возьмёт отсюда (см. «Сессия Soniox»).
+
+Два режима, оба держат главный ключ на сервере:
+
+- **Через сервер** (`mode: "relay"`) — **основной и рекомендуемый путь**. Браузер шлёт звук на ваш сервер по WebSocket,
+  сервер пересылает его в Soniox и возвращает текст. Ключ Soniox не покидает сервер даже в виде временного, работает
+  из России (сервер ходит через прокси), и только в этом режиме есть чистка текста моделью. Цена: серверу нужен WebSocket.
+- **Напрямую** (по умолчанию, **не рекомендуется**): сервер выдаёт браузеру временный ключ Soniox, браузер соединяется
+  с Soniox сам. Оставлен для приложений, которые уже так работают. Временный ключ всё же уходит в браузер, чистки
+  текста нет, а из России браузер до Soniox не достаёт.
+
+## Через сервер (рекомендуется)
+
+```ts
+import { createVoiceRelay } from "@ykurilov/agent-chat-voice/server";
+import { mountVoiceRelay } from "@ykurilov/agent-chat-voice/hono";
+import { createNodeWebSocket } from "@hono/node-ws";
+import { serve } from "@hono/node-server";
+
+const { upgradeWebSocket, injectWebSocket } = createNodeWebSocket({ app });
+const relay = createVoiceRelay({
+  resolveUser: async (request) => currentUser(request), // допуск проверяется до подъёма WebSocket; нет пользователя → 401
+  // ключ: SONIOX_API_KEY из окружения (или apiKey: "…")
+  websocketUrl: process.env.SONIOX_WEBSOCKET_URL,       // из России — адрес маршрута прокси до stt-rt.soniox.com
+  upstreamHeaders: { "X-Proxy-Token": process.env.PROXY_TOKEN! }, // сервер может добавить заголовок
+  polish: { provider: "together" },                     // чистка текста моделью, по желанию (ниже)
+  allowedOrigins: ["https://school.getcourse.ru"],      // по желанию: чужие страницы, которым можно; свой сайт проходит всегда
+});
+mountVoiceRelay(app, "/api/voice/stream", relay, upgradeWebSocket);
+injectWebSocket(serve({ fetch: app.fetch, port: 8787 }));
+```
+
+```tsx
+const voice = createVoiceInput({ api: "/api/voice", mode: "relay" }); // адрес — {api}/stream на том же сайте
+// другой адрес: relayUrl: "wss://voice.example.com/stream" или "/voice/stream" (от адреса страницы)
+```
+
+Настройки: `model` (по умолчанию `stt-rt-v5`, последняя real-time модель Soniox), `languageHints` (по умолчанию `["ru"]`),
+`allowedLanguageHints`, `context` (тема и термины для точности), `maxSessionSeconds` (по умолчанию 300), `rateLimit`,
+`polishRateLimit`, `maxConnectionsPerUser`, `logError`, `websocketUrl`, `upstreamHeaders`, `polish`, `spending`.
+
+Определение конца фразы Soniox (`enable_endpoint_detection`) включено: слова закрепляются быстрее.
+
+**Стоп и финал.** По «стоп» клиент шлёт серверу `finalize`, сервер передаёт его Soniox, и тот закрепляет всё сказанное
+и присылает метку `<fin>`. Только после неё текст считается готовым. Если Soniox не ответил за `stopTimeoutMs`
+(3 секунды по умолчанию), остаётся то, что уже пришло, без ошибки.
+
+**Частота.** Один человек может начать не больше 10 диктовок в минуту (`rateLimit: { maxSessions, perSeconds }`,
+`rateLimit: false` — выключить). Сверх этого — 429 и «слишком часто» у человека. Отдельно: не больше 2 соединений
+одновременно на человека (`maxConnectionsPerUser`, `false` — без предела); лишнее — 429 или код закрытия 4429. Счётчики живут
+в памяти одного процесса; общие лимиты (на всё приложение, на несколько процессов, на расходы Soniox) — задача приложения.
+
+**Почему отказали.** Браузер не видит HTTP-ответ на подъём WebSocket: для него любой такой отказ — «нет связи».
+Поэтому сервер поднимает соединение и сразу закрывает его кодом причины, а браузер показывает свою подпись:
+
+| Причина | Код закрытия | Ошибка в браузере | Подпись по умолчанию |
+|---|---|---|---|
+| не вошёл (`resolveUser` → `null`) | 4401 | `forbidden` | «Нет доступа к диктовке» |
+| приложение отказало (`{ refused: { code } }`) | по `code`, ниже | | |
+| — `code: "limit"` или `"spending_limit_reached"` | 4402 | `limit` | «Лимит расходов исчерпан, диктовка недоступна» |
+| — `code: "too_long"` | 4413 | `too_long` | «Запись слишком длинная» |
+| — `code: "rate_limited"` | 4429 | `rate_limited` | «Слишком много диктовок подряд…» |
+| — `code: "service_unavailable"` | 4502 | `service_unavailable` | «Сервис распознавания речи недоступен» |
+| — любой другой `code` | 4403 | `forbidden` | «Нет доступа к диктовке» |
+| лимит расходов (`spending`) | 4402 | `limit` | как у `limit` |
+| слишком часто | 4429 | `rate_limited` | |
+| нет ключа Soniox, Soniox недоступен | 4502 | `service_unavailable` | |
+| кусок звука больше предела сервера (`maxFrameBytes`) | 1009 | `too_long` | |
+| нет приветствия 10 с после подъёма (`helloTimeoutMs`) | 4400 | `other` | |
+| чужая страница (Origin) | HTTP 403, соединения нет | `network` | |
+
+Коды — `RELAY_CLOSE` из `@ykurilov/agent-chat-voice/server` (и из корня пакета для браузера). В режиме «напрямую» те же
+причины приходят статусом ответа: 401/403 → `forbidden`, 402 → `limit`, 429 → `rate_limited`.
+
+### Next.js: свой сервер (custom server)
+
+Route handlers Next.js не держат WebSocket. Голос встаёт на тот же HTTP-сервер, что и Next.js, обработчиком `upgrade`.
+Проверки те же, что у Hono: своя страница (Origin), вход, частота, лимит расходов, причина отказа кодом закрытия.
+Нужен пакет `ws` (`pnpm add ws`).
+
+```ts
+// server.ts — запуск: node server.ts (Node 22.18+) или node --import tsx server.ts (вместо next start)
+import { createServer } from "node:http";
+import next from "next";
+import { createVoiceUpgrade, sharedVoiceRelay } from "@ykurilov/agent-chat-voice/node";
+
+// Свой обработчик upgrade Next.js вешает на `httpServer` (без него — на сервер первого запроса) и закрывает
+// соединения, которые совпали с его маршрутом. Отдельный сервер, который не слушает порт, держит этот обработчик
+// в стороне: голос Next.js не видит, а свои соединения (горячая перезагрузка) получает через `emit` ниже.
+const nextUpgrades = createServer();
+const app = next({ dev: process.env.NODE_ENV !== "production", httpServer: nextUpgrades });
+const handle = app.getRequestHandler();
+await app.prepare();
+
+const voiceUpgrade = createVoiceUpgrade({ path: "/api/voice/stream", relay: sharedVoiceRelay });
+const server = createServer((request, response) => handle(request, response));
+server.on("upgrade", (request, socket, head) => {
+  if (!voiceUpgrade(request, socket, head)) nextUpgrades.emit("upgrade", request, socket, head);
+});
+server.listen(Number(process.env.PORT ?? 3000));
+```
+
+```ts
+// instrumentation.ts (или любой модуль, который Next.js грузит при старте): ретранслятор живёт рядом с кодом приложения
+import { shareVoiceRelay } from "@ykurilov/agent-chat-voice/node";
+import { createVoiceRelay } from "@ykurilov/agent-chat-voice/server";
+
+export async function register() {
+  if (process.env.NEXT_RUNTIME !== "nodejs") return;
+  shareVoiceRelay(createVoiceRelay({ resolveUser: currentUser, spending: { service: chatService, recognitionUsdPerHour: 0.12 } }));
+}
+```
+
+- `createVoiceUpgrade({ path, relay, maxFrameBytes, authorizeTimeoutMs })` возвращает обработчик `upgrade`: `true` — соединение голоса,
+  `false` — адрес чужой, отдайте его Next.js. `relay` — ретранслятор или функция, которая его отдаёт.
+- **Не вешайте Next.js на тот же сервер**, что и голос (`httpServer: nextUpgrades` обязателен). Иначе после первой
+  страницы Next.js сам подпишется на `upgrade` настоящего сервера и при маршруте, который ловит любой адрес
+  (`app/[...slug]`), закроет соединение голоса: диктовка оборвётся с «нет связи». `app.getUpgradeHandler()` вместо
+  `emit` не подходит: горячую перезагрузку он не обслуживает. Проверено вживую на Next.js 16.3 (`next build` и `next dev`).
+- `shareVoiceRelay` / `sharedVoiceRelay` — мостик внутри процесса. Next.js собирает свой код отдельно от `server.ts`,
+  и общий модуль у них — разные копии; мостик держит ретранслятор на `globalThis`. Пока его нет — ответ 503.
+- Ретранслятор можно создать и прямо в `server.ts` и передать `relay: relay`, если всё нужное (`resolveUser`, служба
+  чата) доступно оттуда.
+- `maxFrameBytes` — предел одного куска звука, по умолчанию 1 МиБ; больше — закрытие 1009 и «Запись слишком длинная».
+  Тот же предел есть у ретранслятора (`createVoiceRelay({ maxFrameBytes })`, он действует и для Hono); здесь кусок
+  отрезается ещё на входе, не попадая в память целиком.
+- `authorizeTimeoutMs` — сколько ждать проверки входа (`resolveUser`, лимит), по умолчанию 10 с; дольше — HTTP 503.
+- Сеть не роняет процесс: путь, который не разбирается (`GET //`), получает HTTP 400, обрыв во время проверки входа
+  просто закрывает сокет.
+- Тот же обработчик подходит для Express и голого `node:http`.
+
+Другой путь — маленький Node-сервер на Hono рядом (код выше, отдельный порт или поддомен, `relayUrl` указывает на него;
+вход `resolveUser` читает тот же cookie, поэтому нужен общий домен).
+
+### Учёт расходов и лимиты
+
+```ts
+const relay = createVoiceRelay({
+  resolveUser,
+  spending: { service: chatService, recognitionUsdPerHour: 0.12 }, // chatService = createChatService(...)
+  polish: { askModel: chatService.askModel, model: { providerId: "together", modelId: "deepseek-ai/DeepSeek-V4.1-Flash" } },
+});
+```
+
+- До диктовки сервер проверяет лимит расходов (`service.assertWithinLimit`): исчерпан — соединение закрывается кодом 4402,
+  человек видит «Лимит расходов исчерпан, диктовка недоступна». Soniox не зовётся.
+- Секунды звука пишутся в журнал расхода видом `voice_input` один раз в конце диктовки: от первого куска звука до конца
+  соединения, начатая секунда — целая, не больше предела записи. Цена — `секунды × recognitionUsdPerHour / 3600`,
+  `inputTokens` — секунды. Так голос попадает в общие лимиты (`@ykurilov/agent-chat-limits`) и отчёты.
+- Чат расхода — `?chat=` адреса соединения (его ставит `createVoiceInput`, `AgentChat` передаёт текущий чат), если это
+  чат вошедшего: сервер проверяет его `service.assertOwnChat`. Нет его, чужой или странный — метка `"voice"`, так чужой
+  адрес не тратит лимит чужого чата. Свой выбор — `spending.chatId(request, user)`. Расход всегда на вошедшем человеке.
+- Чистка текста пишется видом `voice_polish` (ниже).
+- Только режим «через сервер»: «напрямую» звук идёт мимо сервера, и секунд он не видит.
+
+### Язык записи
+
+Браузер может назвать язык каждой записи: `AgentChat` передаёт язык словаря подписей (`labels.locale`), своё приложение —
+`createVoiceInput({ languageHints: () => ["ru", "en"] })` или `voice.start(listener, { language: "en" })`.
+Сервер не верит браузеру на слово: берёт только коды языков из двух-трёх букв (`en-US` → `en`), без повторов, не больше
+трёх. `allowedLanguageHints: ["ru", "en"]` сужает выбор. Ничего годного — подсказка сервера (`languageHints`). Старый
+сервер поле `language_hints` в приветствии просто не читает.
+
+**Из России** нужен маршрут прокси и для WebSocket: обычного маршрута на `api.soniox.com` мало, нужен ещё
+`stt-rt.soniox.com` с проверкой токена и заголовками `Upgrade`/`Connection`.
+
+### Чистка текста моделью
+
+После «стоп» сервер может прогнать надиктованное через модель: убрать «э-э», повторы и оговорки, расставить знаки и заглавные.
+Модель не пересказывает, не отвечает на вопрос из текста, не меняет смысл и язык.
+
+```ts
+polish: { provider: "together" }                                  // ключ TOGETHER_API_KEY из окружения сервера
+polish: { provider: "together", model: "…", apiKey: "…", timeoutMs: 5000 }
+polish: { provider: "together", baseUrl: "https://fr-api-route.yeycourses.com/together/v1", headers: { "X-Proxy-Token": process.env.PROXY_TOKEN! } } // через прокси
+polish: { clean: async (text) => myModel(text) }                  // своя чистка: вернуть исправленный текст
+polish: { askModel: chatService.askModel, model: { providerId, modelId } } // модель службы чата: учёт и лимиты сами
+```
+
+- По умолчанию модель `deepseek-ai/DeepSeek-V4.1-Flash` у Together (без рассуждений, температура 0). Запрос устроен под кэш модели:
+  постоянная инструкция первой, надиктованный текст последним.
+- **Куда уходит текст.** Надиктованный текст отправляется в модель чистки (Together или ваша функция `clean`): это ещё один
+  сторонний сервис рядом с Soniox. Упомяните его в политике приватности. Ключ Together остаётся на сервере и в браузер не попадает.
+- Текст на чистку берёт сам сервер из ответов Soniox, клиент его не присылает: это не открытая дверь к модели.
+- В поле заменяется только надиктованный кусок. Набранное до и после остаётся; дописанное руками во время чистки сохраняется;
+  если человек поправил само надиктованное, чистка не применяется и его правка остаётся. Пока идёт чистка, у кнопки микрофона
+  тихий признак (`VoiceInputView.polishing`, подпись `voicePolishing`).
+- Сбой, ошибка HTTP, пустой, «раздутый» или слишком короткий ответ, ответ другими словами (меньше 70% слов из исходника: так
+  выглядит «ответил на вопрос» или отказ), тишина дольше 5 секунд — остаётся текст Soniox, без ошибки на экране.
+  Клиент ждёт чистку не дольше `polishTimeoutMs` (7 секунд по умолчанию).
+- Нет ключа Together — чистка выключена, диктовка работает, причина в `logError`.
+- **Расходы.** Чистка пишется в журнал расхода видом `voice_polish` и попадает в лимиты:
+  - `askModel` службы чата — всегда: служба сама проверяет лимит и пишет расход (вариант по умолчанию для приложений
+    с `createChatService`);
+  - Together — вместе с `spending` и ценой модели `pricing: { inputPerMillion, outputPerMillion }` (доллары за миллион
+    токенов); без цены при `spending` ретранслятор не создастся: расход прошёл бы мимо лимитов;
+  - своя чистка — вместе с `spending`, если `clean` вернёт `{ text, usage: { inputTokens, outputTokens, costUsd, modelId } }`.
+    Вернула просто текст (без `usage`) — её расход не учитывается: в журнал он не попадает, лимит его не видит. Лимит перед
+    чисткой проверяется и в этом случае.
+  Лимит исчерпан — чистки нет, текст остаётся как сказал Soniox. Расход пишется, как только модель ответила, даже если
+  ответ отброшен проверками. Отдельно у чистки свой лимит частоты: 6 чисток в минуту на человека
+  (`polishRateLimit: { maxSessions, perSeconds }`, `polishRateLimit: false` — выключить). Он работает и при `rateLimit: false`.
+
+### Как устроено
+
+`createVoiceRelay` даёт `authorize(request)` → `{ user, chatId }` или `{ refusal, closeCode? }`, и `accept(socket, user, chatId)`.
+Клиент шлёт `{"audio_format":"auto","language_hints":["ru"]}` (`language_hints` необязательно), сервер
+соединяется с Soniox и отвечает `{"ready":true,"max_session_seconds":300,"polish":true}` (`polish` только если чистка включена),
+после этого клиент шлёт куски звука, команду `{"type":"finalize"}` по «стоп» и, если нужно, пустое сообщение (конец звука).
+Ответы Soniox сервер пересылает как есть, после `<fin>` присылает `{"polished":{"text":"…"}}` (`null` — оставить как есть).
+Приветствие нужно прислать за 10 с (`helloTimeoutMs`), сообщение — не больше 1 МиБ (`maxFrameBytes`).
+Коды закрытия: 4400 нарушен протокол или нет приветствия, 4401 не вошёл, 4402 лимит расходов, 4403 нет доступа, 4408 вышло время, 4413 слишком
+длинно, 4429 слишком часто, 4502 Soniox недоступен, 1009 кусок больше предела.
+Полностью — `specs/009-voice-input/contracts/voice.md` и `specs/013-voice-realtime/contracts/relay.md`.
+
+### Сессия Soniox (для повторного использования)
+
+Связь сервера с Soniox вынесена в отдельный модуль без поля ввода и без WebSocket браузера:
+
+```ts
+import { createSonioxSession } from "@ykurilov/agent-chat-voice/server";
+
+const session = createSonioxSession(
+  { apiKey, model: "stt-rt-v5", languageHints: ["ru"], websocketUrl, logError },
+  { onReady() {}, onMessage(raw, event) {}, onClosed(reason) {} },
+);
+session.begin({ audio_format: "auto" }); // потом sendAudio(chunk), finalize(), endAudio(), text(), close()
+```
+
+Она сама открывает соединение, шлёт первое сообщение, копит закреплённый и предварительный текст, ловит `<fin>`,
+следит за пределом записи и не выдаёт ключ в ответах. На ней стоит `createVoiceRelay`; на ней же сможет стоять голосовой режим.
+
+## Напрямую (не рекомендуется)
+
+Сервер выдаёт браузеру временный ключ Soniox (живёт минуту, один раз, диктовка до пяти минут), браузер соединяется с Soniox сам.
+Чистки текста в этом режиме нет.
+
+```ts
+import { createVoiceHandler } from "@ykurilov/agent-chat-voice/server";
+import { mountChat } from "@ykurilov/agent-chat-server/hono"; // или createNextRouteHandlers из …/next
+
+const voice = createVoiceHandler({
+  basePath: "/api/voice",
+  resolveUser: async (request) => currentUser(request), // тот же вход, что у чата; null → 401
+});
+mountChat(app, voice);
+```
+
+Один адрес: `POST /api/voice/session` → `{ apiKey, websocketUrl, model, languageHints, context? }`. Тело запроса
+`{ languageHints }` (необязательно) — язык этой записи, сервер проверяет его так же, как в режиме «через сервер».
+Нет ключа на сервере или Soniox не ответил — 503/502: чат работает, человек видит «Сервис распознавания речи недоступен».
+Настройки: `model`, `languageHints`, `allowedLanguageHints`, `context`, `tokenLifetimeSeconds`, `maxSessionSeconds`,
+`rateLimit`, `logError`. Учёта расходов в этом режиме нет.
+Ответ с ключом идёт с `Cache-Control: no-store`. Российский сервер: `apiBaseUrl`, `apiHeaders`, `websocketUrl`, но браузер
+подключается к `websocketUrl` сам и заголовок добавить не может, поэтому прокси для WebSocket должен пускать без него.
+
+## Браузер
+
+```tsx
+import { createVoiceInput } from "@ykurilov/agent-chat-voice";
+
+const voice = createVoiceInput({ api: "/api/voice", mode: "relay" }); // один на приложение
+<AgentChat api="/api/chat" chatId={chatId} skin={tandemSkin} voice={voice} />;
+```
+
+- Нажатие: запрос разрешения на микрофон → соединение с сервером → запись потоком. Повторное нажатие — стоп: остаток речи
+  закрепляется (`finalize`), микрофон отпускается. Нажатие во время подключения отменяет запуск.
+- Слова дописываются к тому, что уже набрано. Ручная правка во время диктовки остаётся, сказанное раньше не дублируется.
+  Голос сам ничего не отправляет.
+- Нет доступа к микрофону, нет микрофона, нет связи, сервис недоступен, лимит, нет доступа, слишком длинно — понятная
+  надпись из словаря чата (`voiceErrors`), чат работает дальше.
+- Подписи — `voiceStart`, `voiceStop`, `voiceConnecting`, `voicePolishing`, `voiceErrors` в словаре `russianLabels`.
+  Подписи `limit`, `forbidden`, `too_long` в своём словаре можно не задавать: возьмутся подписи по умолчанию на языке
+  словаря. `time_limit` — строка или функция от предела записи в секундах.
+- `voice.start(listener, { chatId, language })`: чат расхода (режим «через сервер») и язык записи. `AgentChat` передаёт их
+  сам. `onError(kind, details)`: у `time_limit` в `details.maxSessionSeconds` предел, названный сервером.
+- Формат записи выбирается явно: webm/opus (Chrome, Firefox), затем ogg/opus, затем mp4 (Safari). Soniox сам
+  определяет контейнер. Нужен `https` или `localhost`.
+- Предел диктовки — `maxSessionSeconds` сервера (5 минут по умолчанию). За две секунды до него запись останавливается,
+  слова сохраняются, человек видит «Запись остановлена: предел 5 минут» — с числом из настройки сервера. Отправка сообщения во время диктовки останавливает диктовку.
+
+Договор скина версии 5: `Composer` получает необязательное свойство `voice` (`VoiceInputView`); нет его — кнопку не рисовать.
+Необязательное `voice.polishing` — признак «идёт чистка»; скин, который его не знает, работает как раньше.
+Подробнее — `specs/009-voice-input/contracts/voice.md`.
+
+## Проверка вживую
+
+`pnpm secrets:load` кладёт ключ из `~/.config/soniox/.env` в `.env.local`; `pnpm test:live soniox` озвучивает
+русскую фразу (`say -v Milena`), отправляет в Soniox тем же путём, что браузер, и ждёт текст. Из России добавьте
+`SONIOX_API_BASE_URL` и `PROXY_TOKEN`. `soniox-formats` проверяет куски webm/opus, ogg/opus и mp4/AAC,
+`soniox-relay` — весь путь «клиент → сервер Hono → Soniox» (для России ещё `SONIOX_WEBSOCKET_URL`), с замером, когда пришли предварительные слова и финал
+после `finalize`, и одним вызовом чистки, если есть `TOGETHER_API_KEY`.

package/dist/chunk-CAERXPTX.js

@@ -0,0 +1,103 @@
+// src/relay-close.ts
+var RELAY_CLOSE = {
+  normal: 1e3,
+  /** Кусок звука больше предела сервера (стандартный код WebSocket). */
+  messageTooBig: 1009,
+  protocol: 4400,
+  /** Не вошёл. */
+  unauthorized: 4401,
+  /** Лимит расходов исчерпан. */
+  limit: 4402,
+  /** Нет доступа: приложение отказало. */
+  forbidden: 4403,
+  timeLimit: 4408,
+  /** Слишком длинно: приложение отказало по длине. */
+  tooLong: 4413,
+  rateLimited: 4429,
+  upstream: 4502
+};
+
+// src/soniox-messages.ts
+function buildStartMessage({ apiKey, model, languageHints, context, endpointLatencyLevel, maxEndpointDelayMs }) {
+  return {
+    api_key: apiKey,
+    model,
+    audio_format: "auto",
+    language_hints: languageHints,
+    ...context && { context },
+    enable_endpoint_detection: true,
+    ...endpointLatencyLevel !== void 0 && { endpoint_latency_adjustment_level: endpointLatencyLevel },
+    ...maxEndpointDelayMs !== void 0 && { max_endpoint_delay_ms: maxEndpointDelayMs }
+  };
+}
+function buildFinalizeMessage() {
+  return { type: "finalize" };
+}
+var FINALIZED_MARK = "<fin>";
+var PHRASE_END_MARK = "<end>";
+var serviceTokens = /* @__PURE__ */ new Set([FINALIZED_MARK, PHRASE_END_MARK]);
+function createTranscript({ phraseEnds = false } = {}) {
+  let finalText = "";
+  let phraseText = "";
+  let interimText = "";
+  const snapshot = () => ({ finalText, interimText });
+  return {
+    accept(raw) {
+      let message;
+      try {
+        message = JSON.parse(raw);
+      } catch {
+        return { type: "ignored" };
+      }
+      if (typeof message !== "object" || message === null) return { type: "ignored" };
+      if (message.error_code !== void 0 || message.error_message !== void 0) {
+        return {
+          type: "error",
+          code: typeof message.error_code === "number" ? message.error_code : 0,
+          message: typeof message.error_message === "string" ? message.error_message : ""
+        };
+      }
+      const hasTokens = Array.isArray(message.tokens);
+      let finalized = false;
+      const endedPhrases = [];
+      if (hasTokens) {
+        let interim = "";
+        for (const token of message.tokens) {
+          if (typeof token.text !== "string") continue;
+          if (token.text === FINALIZED_MARK) finalized = true;
+          if (token.text === PHRASE_END_MARK && phraseEnds) {
+            endedPhrases.push(phraseText.trim());
+            phraseText = "";
+          }
+          if (serviceTokens.has(token.text)) continue;
+          if (token.is_final === true) {
+            finalText += token.text;
+            phraseText += token.text;
+          } else interim += token.text;
+        }
+        interimText = interim;
+      }
+      const phrases = endedPhrases.length > 0 ? { endedPhrases } : {};
+      if (message.finished === true) {
+        return hasTokens && message.tokens.length > 0 ? { type: "finished", text: snapshot(), ...phrases } : { type: "finished" };
+      }
+      if (!hasTokens) return { type: "ignored" };
+      return { type: "text", text: snapshot(), ...finalized && { finalized: true }, ...phrases };
+    },
+    /** Диктовка закончилась: что Soniox не успел закрепить, остаётся как есть. */
+    settle() {
+      finalText += interimText;
+      interimText = "";
+      return snapshot();
+    },
+    current: snapshot
+  };
+}
+
+export {
+  buildStartMessage,
+  buildFinalizeMessage,
+  createTranscript,
+  RELAY_CLOSE
+};
+//# sourceMappingURL=chunk-CAERXPTX.js.map

package/dist/chunk-CAERXPTX.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/relay-close.ts","../src/soniox-messages.ts"],"sourcesContent":["/**\n * Коды закрытия соединения браузера с сервером приложения (режим `relay`): по ним браузер понимает, что случилось,\n * и показывает свою подпись. Общие для сервера и браузера.\n */\nexport const RELAY_CLOSE = {\n  normal: 1000,\n  /** Кусок звука больше предела сервера (стандартный код WebSocket). */\n  messageTooBig: 1009,\n  protocol: 4400,\n  /** Не вошёл. */\n  unauthorized: 4401,\n  /** Лимит расходов исчерпан. */\n  limit: 4402,\n  /** Нет доступа: приложение отказало. */\n  forbidden: 4403,\n  timeLimit: 4408,\n  /** Слишком длинно: приложение отказало по длине. */\n  tooLong: 4413,\n  rateLimited: 4429,\n  upstream: 4502,\n} as const;\n","/** Всё, что человек уже сказал: закреплённое распознавание и то, что Soniox ещё может поправить. */\nexport interface DictatedText {\n  finalText: string;\n  interimText: string;\n}\n\n/** Подсказка Soniox: тема и термины, чтобы точнее распознавать узкие слова. */\nexport interface SonioxContext {\n  general?: Array<{ key: string; value: string }>;\n  text?: string;\n  terms?: string[];\n}\n\nexport interface StartMessageOptions {\n  apiKey: string;\n  model: string;\n  languageHints: string[];\n  context?: SonioxContext | undefined;\n  /** Как быстро Soniox объявляет конец фразы: чем меньше число, тем раньше (и тем чаще ошибается на паузах). Не задан — по умолчанию Soniox. */\n  endpointLatencyLevel?: number | undefined;\n  /** Самая долгая пауза до конца фразы, мс. Не задан — по умолчанию Soniox. */\n  maxEndpointDelayMs?: number | undefined;\n}\n\n/**\n * Первое сообщение в WebSocket Soniox: ключ и настройки распознавания. Формат звука Soniox определяет сам.\n * Границы фраз (`enable_endpoint_detection`): на паузе Soniox закрепляет сказанное, не дожидаясь конца диктовки.\n */\nexport function buildStartMessage({ apiKey, model, languageHints, context, endpointLatencyLevel, maxEndpointDelayMs }: StartMessageOptions) {\n  return {\n    api_key: apiKey,\n    model,\n    audio_format: \"auto\",\n    language_hints: languageHints,\n    ...(context && { context }),\n    enable_endpoint_detection: true,\n    ...(endpointLatencyLevel !== undefined && { endpoint_latency_adjustment_level: endpointLatencyLevel }),\n    ...(maxEndpointDelayMs !== undefined && { max_endpoint_delay_ms: maxEndpointDelayMs }),\n  };\n}\n\n/** Команда Soniox «закрепи всё сказанное»: в ответ приходят закреплённые слова и метка `<fin>`; соединение остаётся открытым. */\nexport function buildFinalizeMessage() {\n  return { type: \"finalize\" } as const;\n}\n\nexport type SonioxEvent =\n  /** `finalized`: в ответе метка `<fin>`, то есть Soniox выполнил команду «закрепи всё» и всё сказанное закреплено. */\n  | { type: \"text\"; text: DictatedText; finalized?: true; endedPhrases?: string[] }\n  | { type: \"finished\"; text?: DictatedText; endedPhrases?: string[] }\n  | { type: \"error\"; code: number; message: string }\n  | { type: \"ignored\" };\n\n/** Служебные метки Soniox между словами: в текст не попадают. `<fin>` — конец закрепления по команде, `<end>` — конец фразы. */\nconst FINALIZED_MARK = \"<fin>\";\nconst PHRASE_END_MARK = \"<end>\";\nconst serviceTokens = new Set([FINALIZED_MARK, PHRASE_END_MARK]);\n\ninterface SonioxMessage {\n  tokens?: Array<{ text?: unknown; is_final?: unknown }>;\n  finished?: unknown;\n  error_code?: unknown;\n  error_message?: unknown;\n}\n\nexport interface TranscriptOptions {\n  /**\n   * Выдавать конец фразы: по метке `<end>` событие несёт `endedPhrases` — закреплённый текст каждой закончившейся фразы.\n   * Нужно голосовому диалогу; диктовке поле не нужно, и без опции события прежние.\n   */\n  phraseEnds?: boolean | undefined;\n}\n\n/** Копит ответы Soniox: закреплённые слова только добавляются, незакреплённые каждый раз приходят заново целиком. */\nexport function createTranscript({ phraseEnds = false }: TranscriptOptions = {}) {\n  let finalText = \"\";\n  let phraseText = \"\";\n  let interimText = \"\";\n  const snapshot = (): DictatedText => ({ finalText, interimText });\n\n  return {\n    accept(raw: string): SonioxEvent {\n      let message: SonioxMessage;\n      try {\n        message = JSON.parse(raw) as SonioxMessage;\n      } catch {\n        return { type: \"ignored\" };\n      }\n      if (typeof message !== \"object\" || message === null) return { type: \"ignored\" };\n\n      if (message.error_code !== undefined || message.error_message !== undefined) {\n        return {\n          type: \"error\",\n          code: typeof message.error_code === \"number\" ? message.error_code : 0,\n          message: typeof message.error_message === \"string\" ? message.error_message : \"\",\n        };\n      }\n\n      const hasTokens = Array.isArray(message.tokens);\n      let finalized = false;\n      const endedPhrases: string[] = [];\n      if (hasTokens) {\n        let interim = \"\";\n        for (const token of message.tokens!) {\n          if (typeof token.text !== \"string\") continue;\n          if (token.text === FINALIZED_MARK) finalized = true;\n          if (token.text === PHRASE_END_MARK && phraseEnds) {\n            endedPhrases.push(phraseText.trim());\n            phraseText = \"\";\n          }\n          if (serviceTokens.has(token.text)) continue;\n          if (token.is_final === true) {\n            finalText += token.text;\n            phraseText += token.text;\n          } else interim += token.text;\n        }\n        interimText = interim;\n      }\n\n      const phrases = endedPhrases.length > 0 ? { endedPhrases } : {};\n      if (message.finished === true) {\n        return hasTokens && message.tokens!.length > 0 ? { type: \"finished\", text: snapshot(), ...phrases } : { type: \"finished\" };\n      }\n      if (!hasTokens) return { type: \"ignored\" };\n      return { type: \"text\", text: snapshot(), ...(finalized && { finalized: true as const }), ...phrases };\n    },\n\n    /** Диктовка закончилась: что Soniox не успел закрепить, остаётся как есть. */\n    settle(): DictatedText {\n      finalText += interimText;\n      interimText = \"\";\n      return snapshot();\n    },\n\n    current: snapshot,\n  };\n}\n"],"mappings":";AAIO,IAAM,cAAc;AAAA,EACzB,QAAQ;AAAA;AAAA,EAER,eAAe;AAAA,EACf,UAAU;AAAA;AAAA,EAEV,cAAc;AAAA;AAAA,EAEd,OAAO;AAAA;AAAA,EAEP,WAAW;AAAA,EACX,WAAW;AAAA;AAAA,EAEX,SAAS;AAAA,EACT,aAAa;AAAA,EACb,UAAU;AACZ;;;ACQO,SAAS,kBAAkB,EAAE,QAAQ,OAAO,eAAe,SAAS,sBAAsB,mBAAmB,GAAwB;AAC1I,SAAO;AAAA,IACL,SAAS;AAAA,IACT;AAAA,IACA,cAAc;AAAA,IACd,gBAAgB;AAAA,IAChB,GAAI,WAAW,EAAE,QAAQ;AAAA,IACzB,2BAA2B;AAAA,IAC3B,GAAI,yBAAyB,UAAa,EAAE,mCAAmC,qBAAqB;AAAA,IACpG,GAAI,uBAAuB,UAAa,EAAE,uBAAuB,mBAAmB;AAAA,EACtF;AACF;AAGO,SAAS,uBAAuB;AACrC,SAAO,EAAE,MAAM,WAAW;AAC5B;AAUA,IAAM,iBAAiB;AACvB,IAAM,kBAAkB;AACxB,IAAM,gBAAgB,oBAAI,IAAI,CAAC,gBAAgB,eAAe,CAAC;AAkBxD,SAAS,iBAAiB,EAAE,aAAa,MAAM,IAAuB,CAAC,GAAG;AAC/E,MAAI,YAAY;AAChB,MAAI,aAAa;AACjB,MAAI,cAAc;AAClB,QAAM,WAAW,OAAqB,EAAE,WAAW,YAAY;AAE/D,SAAO;AAAA,IACL,OAAO,KAA0B;AAC/B,UAAI;AACJ,UAAI;AACF,kBAAU,KAAK,MAAM,GAAG;AAAA,MAC1B,QAAQ;AACN,eAAO,EAAE,MAAM,UAAU;AAAA,MAC3B;AACA,UAAI,OAAO,YAAY,YAAY,YAAY,KAAM,QAAO,EAAE,MAAM,UAAU;AAE9E,UAAI,QAAQ,eAAe,UAAa,QAAQ,kBAAkB,QAAW;AAC3E,eAAO;AAAA,UACL,MAAM;AAAA,UACN,MAAM,OAAO,QAAQ,eAAe,WAAW,QAAQ,aAAa;AAAA,UACpE,SAAS,OAAO,QAAQ,kBAAkB,WAAW,QAAQ,gBAAgB;AAAA,QAC/E;AAAA,MACF;AAEA,YAAM,YAAY,MAAM,QAAQ,QAAQ,MAAM;AAC9C,UAAI,YAAY;AAChB,YAAM,eAAyB,CAAC;AAChC,UAAI,WAAW;AACb,YAAI,UAAU;AACd,mBAAW,SAAS,QAAQ,QAAS;AACnC,cAAI,OAAO,MAAM,SAAS,SAAU;AACpC,cAAI,MAAM,SAAS,eAAgB,aAAY;AAC/C,cAAI,MAAM,SAAS,mBAAmB,YAAY;AAChD,yBAAa,KAAK,WAAW,KAAK,CAAC;AACnC,yBAAa;AAAA,UACf;AACA,cAAI,cAAc,IAAI,MAAM,IAAI,EAAG;AACnC,cAAI,MAAM,aAAa,MAAM;AAC3B,yBAAa,MAAM;AACnB,0BAAc,MAAM;AAAA,UACtB,MAAO,YAAW,MAAM;AAAA,QAC1B;AACA,sBAAc;AAAA,MAChB;AAEA,YAAM,UAAU,aAAa,SAAS,IAAI,EAAE,aAAa,IAAI,CAAC;AAC9D,UAAI,QAAQ,aAAa,MAAM;AAC7B,eAAO,aAAa,QAAQ,OAAQ,SAAS,IAAI,EAAE,MAAM,YAAY,MAAM,SAAS,GAAG,GAAG,QAAQ,IAAI,EAAE,MAAM,WAAW;AAAA,MAC3H;AACA,UAAI,CAAC,UAAW,QAAO,EAAE,MAAM,UAAU;AACzC,aAAO,EAAE,MAAM,QAAQ,MAAM,SAAS,GAAG,GAAI,aAAa,EAAE,WAAW,KAAc,GAAI,GAAG,QAAQ;AAAA,IACtG;AAAA;AAAA,IAGA,SAAuB;AACrB,mBAAa;AACb,oBAAc;AACd,aAAO,SAAS;AAAA,IAClB;AAAA,IAEA,SAAS;AAAA,EACX;AACF;","names":[]}

package/dist/hono.js

@@ -0,0 +1,45 @@
+// src/hono.ts
+function mountVoiceRelay(app, path, relay, upgradeWebSocket) {
+  app.get(
+    path,
+    async (context, next) => {
+      const access = await relay.authorize(context.req.raw);
+      if ("refusal" in access) {
+        if (access.closeCode === void 0) return access.refusal;
+        context.set("voiceCloseCode", access.closeCode);
+      } else {
+        context.set("voiceUser", access.user);
+        context.set("voiceChatId", access.chatId);
+      }
+      await next();
+    },
+    upgradeWebSocket((context) => {
+      const user = context.get("voiceUser");
+      const chatId = context.get("voiceChatId");
+      const closeCode = context.get("voiceCloseCode");
+      let connection;
+      let queue = Promise.resolve();
+      return {
+        onOpen(_event, socket) {
+          if (closeCode !== void 0) return socket.close(closeCode);
+          connection = relay.accept({ send: (data) => socket.send(data), close: (code, reason) => socket.close(code, reason) }, user, chatId);
+        },
+        onMessage(event) {
+          const data = event.data;
+          queue = queue.then(async () => {
+            if (typeof data === "string") connection?.receive(data);
+            else if (data instanceof Blob) connection?.receive(new Uint8Array(await data.arrayBuffer()));
+            else if (ArrayBuffer.isView(data)) connection?.receive(new Uint8Array(data.buffer, data.byteOffset, data.byteLength));
+            else if (data instanceof ArrayBuffer) connection?.receive(data);
+          });
+        },
+        onClose: () => connection?.closed(),
+        onError: () => connection?.closed()
+      };
+    })
+  );
+}
+export {
+  mountVoiceRelay
+};
+//# sourceMappingURL=hono.js.map

package/dist/hono.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/hono.ts"],"sourcesContent":["import type { Context, Hono } from \"hono\";\nimport type { UpgradeWebSocket } from \"hono/ws\";\nimport type { RelayConnection, VoiceRelay } from \"./server/voice-relay\";\n\ntype VoiceRelayEnv = { Variables: { voiceUser: { id: string }; voiceChatId: string; voiceCloseCode: number | undefined } };\n\n/**\n * Подключает ретранслятор голоса к Hono: `GET {path}` поднимается до WebSocket.\n * `upgradeWebSocket` даёт адаптер вашего сервера, например `createNodeWebSocket` из `@hono/node-ws`.\n * Допуск решается до подъёма. Отказ с причиной (не вошёл, лимит, частота, сервис недоступен) браузер видит только кодом\n * закрытия: соединение поднимается и сразу закрывается этим кодом. Чужая страница — обычный HTTP-ответ 403.\n */\nexport function mountVoiceRelay(app: Hono, path: string, relay: VoiceRelay, upgradeWebSocket: UpgradeWebSocket): void {\n  (app as unknown as Hono<VoiceRelayEnv>).get(\n    path,\n    async (context, next) => {\n      const access = await relay.authorize(context.req.raw);\n      if (\"refusal\" in access) {\n        if (access.closeCode === undefined) return access.refusal;\n        context.set(\"voiceCloseCode\", access.closeCode);\n      } else {\n        context.set(\"voiceUser\", access.user);\n        context.set(\"voiceChatId\", access.chatId);\n      }\n      await next();\n    },\n    upgradeWebSocket((context: Context<VoiceRelayEnv>) => {\n      const user = context.get(\"voiceUser\");\n      const chatId = context.get(\"voiceChatId\");\n      const closeCode = context.get(\"voiceCloseCode\");\n      let connection: RelayConnection | undefined;\n      // Куски звука и «конец звука» должны дойти по порядку, даже если платформа отдаёт их вразнобой (Blob).\n      let queue: Promise<void> = Promise.resolve();\n      return {\n        onOpen(_event, socket) {\n          if (closeCode !== undefined) return socket.close(closeCode);\n          connection = relay.accept({ send: (data) => socket.send(data), close: (code, reason) => socket.close(code, reason) }, user, chatId);\n        },\n        onMessage(event) {\n          const data = event.data as unknown;\n          queue = queue.then(async () => {\n            if (typeof data === \"string\") connection?.receive(data);\n            else if (data instanceof Blob) connection?.receive(new Uint8Array(await data.arrayBuffer()));\n            else if (ArrayBuffer.isView(data)) connection?.receive(new Uint8Array(data.buffer, data.byteOffset, data.byteLength));\n            else if (data instanceof ArrayBuffer) connection?.receive(data);\n          });\n        },\n        onClose: () => connection?.closed(),\n        onError: () => connection?.closed(),\n      };\n    }),\n  );\n}\n"],"mappings":";AAYO,SAAS,gBAAgB,KAAW,MAAc,OAAmB,kBAA0C;AACpH,EAAC,IAAuC;AAAA,IACtC;AAAA,IACA,OAAO,SAAS,SAAS;AACvB,YAAM,SAAS,MAAM,MAAM,UAAU,QAAQ,IAAI,GAAG;AACpD,UAAI,aAAa,QAAQ;AACvB,YAAI,OAAO,cAAc,OAAW,QAAO,OAAO;AAClD,gBAAQ,IAAI,kBAAkB,OAAO,SAAS;AAAA,MAChD,OAAO;AACL,gBAAQ,IAAI,aAAa,OAAO,IAAI;AACpC,gBAAQ,IAAI,eAAe,OAAO,MAAM;AAAA,MAC1C;AACA,YAAM,KAAK;AAAA,IACb;AAAA,IACA,iBAAiB,CAAC,YAAoC;AACpD,YAAM,OAAO,QAAQ,IAAI,WAAW;AACpC,YAAM,SAAS,QAAQ,IAAI,aAAa;AACxC,YAAM,YAAY,QAAQ,IAAI,gBAAgB;AAC9C,UAAI;AAEJ,UAAI,QAAuB,QAAQ,QAAQ;AAC3C,aAAO;AAAA,QACL,OAAO,QAAQ,QAAQ;AACrB,cAAI,cAAc,OAAW,QAAO,OAAO,MAAM,SAAS;AAC1D,uBAAa,MAAM,OAAO,EAAE,MAAM,CAAC,SAAS,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,MAAM,WAAW,OAAO,MAAM,MAAM,MAAM,EAAE,GAAG,MAAM,MAAM;AAAA,QACpI;AAAA,QACA,UAAU,OAAO;AACf,gBAAM,OAAO,MAAM;AACnB,kBAAQ,MAAM,KAAK,YAAY;AAC7B,gBAAI,OAAO,SAAS,SAAU,aAAY,QAAQ,IAAI;AAAA,qBAC7C,gBAAgB,KAAM,aAAY,QAAQ,IAAI,WAAW,MAAM,KAAK,YAAY,CAAC,CAAC;AAAA,qBAClF,YAAY,OAAO,IAAI,EAAG,aAAY,QAAQ,IAAI,WAAW,KAAK,QAAQ,KAAK,YAAY,KAAK,UAAU,CAAC;AAAA,qBAC3G,gBAAgB,YAAa,aAAY,QAAQ,IAAI;AAAA,UAChE,CAAC;AAAA,QACH;AAAA,QACA,SAAS,MAAM,YAAY,OAAO;AAAA,QAClC,SAAS,MAAM,YAAY,OAAO;AAAA,MACpC;AAAA,IACF,CAAC;AAAA,EACH;AACF;","names":[]}