Realtime: подключение и подписка

Статусы заказов приходят по WebSocket в Pusher-совместимом протоколе: подходят pusher-js и Laravel Echo, своего SDK у Lumean нет. Подписка бесплатна и окна ключа не расходует — их тратит только REST.

Подключение

App key публичный: он идентифицирует приложение, а не вас, и лежит открытым в спеке. Секрет здесь один — X-API-KEY, и он уходит только на auth-эндпоинт, в кадры WebSocket не попадая.

import Pusher from 'pusher-js'

const pusher = new Pusher('7c4dd881d8116ac76fe89aff71d8c2ff', {
  wsHost: 'ws.lumean.app', wsPort: 443, wssPort: 443,
  forceTLS: true, enabledTransports: ['ws', 'wss'], cluster: '',
  channelAuthorization: {
    endpoint: 'https://api.lumean.app/api/public/broadcasting/auth',
    headers: { 'X-API-KEY': process.env.LUMEAN_API_KEY },
  },
})

const ch = pusher.subscribe('private-orders.42')      // 42 = user_id владельца ключа
ch.bind('status.changed', (e) => console.log(e.previous_status, '→', e.new_status))

У Laravel Echo те же параметры (authEndpoint + auth.headers), но префикс private- он ставит сам: echo.private('orders.42').

Авторизация подписки

Приватный канал требует подписи, и библиотека получает её сама: socket_id из кадра pusher:connection_established уходит вместе с channel_name (с префиксом private-) на POST /broadcasting/auth под заголовком X-API-KEY, ответная строка auth кладётся в кадр pusher:subscribe. Право зависит от канала: orders.read у заказных и канала превью, voices.read у каналов клонов голоса, reseller.read у канала кодов. Ответ идёт вне общего конверта API: ни success, ни data в нём нет, только auth.

Каналы

Канал аккаунта (14): created, status.changed, item.status.changed, progress, bulk_retry.completed, paragraph_regenerate.completed, voice_search.queue.updated, renamed, stitch.changed, policy_cooldown.applied/.cleared, archive.progress/.ready/.failed. Канал заказа (8): те же, кроме created, archive.* и policy_cooldown.*. Канал превью (1): ready (status, preview_id, summary, page) — чанков в нём нет, их берут через GET /orders/chunks/preview/{previewId}?page=1. Каналы клонов (по 1): voice_clone.updated на каждую смену статуса клона (pending → cloning → ready или failed); без WebSocket статус опрашивают списком клонов. Канал кодов (4): issued, status.changed, reseller.status.changed, reseller.application.status.changed. Значений кодов в событиях нет — только маски; полный код отдают GET /reseller/codes и GET /reseller/codes/{uuid}.

Готовность ловите по status.changed (previous_status → new_status), а не по счётчикам прогресса: последний чанк и терминальный статус — разные моменты.

Ловушка: два разных progress

Событие progress есть на обоих заказных каналах, но payload у них разный, а различить их можно только по каналу: имя одинаковое, и общий обработчик читает несуществующие поля.

Оба progress считают только исходные чанки: повторы и перегенерации в них не входят, поэтому у переделанного заказа доля до 100 может не дойти вовсе.

Ловушка: ведущая точка в имени события

Чего в payload нет

• created и status.changed несут снимок заказа без списка чанков — вместо него items_summary: { total, by_status }; чанки берите из GET /orders/{order}.
• Файлы приходят метаданными: ссылка на скачивание — всегда POST /storage/url.
• renamed и archive.* по ключу инициировать нечем — они живут только в веб-кабинете; событие прилетит, если владелец сделал это руками.
• policy_cooldown.applied предупреждает о кулдауне до того, как вы упрётесь в 429: ограничение накладывается при финализации провалившейся задачи, а не в ответ на запрос. Считайте по retry_at (ISO-8601): событие идёт через очередь, и retry_after стареет в пути.

Когда WebSocket не нужен

Одиночный короткий заказ дешевле дождаться поллингом GET /orders/{order}: соединение и разбор событий окупаются на потоке заказов или там, где прогресс видит пользователь. И даже с подпиской источник истины остаётся у REST — событие может не дойти. Ожидание без WS — в гайде Асинхронная модель.