@hubtalk-ai/web-sdk 0.2.0

package/dist/index.js

@@ -0,0 +1,400 @@
+import { ConnectionError as A, ConnectionErrorReason as u, MediaDeviceFailure as m, Room as I, RoomEvent as a, ConnectionState as p, Track as C, DisconnectReason as S } from "livekit-client";
+class y {
+  constructor(t) {
+    if (t) {
+      this.element = t, this.owned = !1;
+      return;
+    }
+    this.element = document.createElement("div"), this.element.style.display = "none", document.body.appendChild(this.element), this.owned = !0;
+  }
+  attach(t) {
+    this.element.appendChild(t.attach());
+  }
+  detach(t) {
+    t.detach().forEach((e) => e.remove());
+  }
+  clear() {
+    this.element.replaceChildren();
+  }
+  destroy() {
+    this.clear(), this.owned && this.element.remove();
+  }
+}
+class w {
+  constructor() {
+    this.listeners = /* @__PURE__ */ new Map();
+  }
+  on(t, e) {
+    let n = this.listeners.get(t);
+    n || (n = /* @__PURE__ */ new Set(), this.listeners.set(t, n)), n.add(e);
+  }
+  off(t, e) {
+    var n;
+    (n = this.listeners.get(t)) == null || n.delete(e);
+  }
+  once(t, e) {
+    const n = (i) => {
+      this.off(t, n), e(i);
+    };
+    this.on(t, n);
+  }
+  emit(t, e) {
+    const n = this.listeners.get(t);
+    if (n)
+      for (const i of [...n])
+        i(e);
+  }
+  clear() {
+    this.listeners.clear();
+  }
+}
+const N = {
+  INVALID_PARAMS: "accessToken и url обязательны",
+  WEBRTC_UNSUPPORTED: "браузер/контекст не поддерживает WebRTC (нужен HTTPS)",
+  MICROPHONE_PERMISSION_DENIED: "доступ к микрофону запрещён пользователем",
+  MICROPHONE_UNAVAILABLE: "микрофон недоступен или занят другим приложением",
+  TOKEN_EXPIRED: "срок действия токена истёк",
+  TOKEN_INVALID: "сервер отклонил токен",
+  CONNECTION_FAILED: "не удалось установить соединение",
+  CONNECTION_LOST: "соединение потеряно, реконнект не восстановил его",
+  ALREADY_IN_CALL: "звонок уже активен",
+  NOT_IN_CALL: "нет активного звонка",
+  SERVER_ERROR: "внутренняя ошибка сервиса сигналинга"
+};
+class _ extends Error {
+  constructor(t, e, n) {
+    super(N[t]), this.name = "VoiceCallError", this.code = t, this.state = e, this.cause = n;
+  }
+}
+function b(o) {
+  if (o instanceof A)
+    switch (o.reason) {
+      case u.NotAllowed:
+        return "TOKEN_INVALID";
+      case u.ServerUnreachable:
+      case u.Timeout:
+      case u.WebSocket:
+        return "CONNECTION_FAILED";
+      default:
+        return "SERVER_ERROR";
+    }
+  return "SERVER_ERROR";
+}
+function O(o) {
+  return m.getFailure(o) === m.PermissionDenied ? "MICROPHONE_PERMISSION_DENIED" : "MICROPHONE_UNAVAILABLE";
+}
+const T = "[redacted]", k = /^[\w-]+\.[\w-]+\.[\w-]+$/, D = /token/i;
+function f(o) {
+  if (typeof o == "string")
+    return k.test(o) ? T : o;
+  if (Array.isArray(o))
+    return o.map(f);
+  if (o && typeof o == "object") {
+    const t = {};
+    for (const [e, n] of Object.entries(o))
+      t[e] = D.test(e) ? T : f(n);
+    return t;
+  }
+  return o;
+}
+function L(o, t) {
+  if (o === "silent")
+    return { error: () => {
+    }, debug: () => {
+    } };
+  const e = t ?? {
+    error: (n, ...i) => console.error(n, ...i),
+    debug: (n, ...i) => console.debug(n, ...i)
+  };
+  return {
+    error: (n, ...i) => e.error(n, ...i.map(f)),
+    debug: (n, ...i) => {
+      o === "debug" && e.debug(n, ...i.map(f));
+    }
+  };
+}
+function P(o = !0) {
+  var t;
+  return typeof window > "u" || !window.isSecureContext || typeof RTCPeerConnection > "u" ? !1 : o ? typeof navigator < "u" && !!((t = navigator.mediaDevices) != null && t.getUserMedia) : !0;
+}
+function M(o) {
+  const t = o.split(".")[1];
+  if (!t) return null;
+  try {
+    const e = t.replace(/-/g, "+").replace(/_/g, "/"), n = decodeURIComponent(
+      Array.from(atob(e)).map((r) => "%" + r.charCodeAt(0).toString(16).padStart(2, "0")).join("")
+    ), i = JSON.parse(n);
+    return typeof i.exp == "number" ? i.exp : null;
+  } catch {
+    return null;
+  }
+}
+const v = "lk.agent.state", V = /* @__PURE__ */ new Set(["initializing", "listening", "thinking", "speaking"]), U = /* @__PURE__ */ new Set([
+  S.ROOM_DELETED,
+  S.PARTICIPANT_REMOVED,
+  S.SERVER_SHUTDOWN,
+  S.ROOM_CLOSED
+]), E = /* @__PURE__ */ new Set(["connecting", "connected", "reconnecting"]), R = "lk.transcription", H = "lk.chat", F = "lk.segment_id", x = "lk.transcription_final", K = 1e3;
+class B {
+  constructor(t = {}) {
+    this.emitter = new w(), this.connectionState = "idle", this.agentState = "unknown", this.room = null, this.callId = null, this.playAudio = !0, this.stoppingLocally = !1, this.reconnectSeen = !1, this.destroyed = !1, this.roomCleanup = [], this.audio = new y(t.audioContainer), this.log = L(t.logLevel ?? "error", t.logger), this.connectTimeoutMs = t.connectTimeoutMs;
+  }
+  getState() {
+    return this.connectionState;
+  }
+  getAgentState() {
+    return this.agentState;
+  }
+  getCallId() {
+    return this.callId;
+  }
+  on(t, e) {
+    this.emitter.on(t, e);
+  }
+  off(t, e) {
+    this.emitter.off(t, e);
+  }
+  once(t, e) {
+    this.emitter.once(t, e);
+  }
+  /**
+   * `options.audio === false` — chat-only call: микрофон не публикуется,
+   * аудио агента не подписывается (см. connectRoom). Текст в обе стороны
+   * идёт как обычно — `sendText` и событие `transcript`.
+   *
+   * Аудио агента при этом ПОДПИСЫВАЕТСЯ и просто не проигрывается — это не
+   * расточительность, а единственный работающий вариант с livekit-agents
+   * 1.6.4: `_ParticipantAudioOutput.capture_frame` ждёт `_subscribed_fut`
+   * (room_io/_output.py:92), который закрывается только по
+   * `publication.wait_for_subscription()`. Без подписчика первый же кадр
+   * TTS блокируется навсегда, а вместе с ним умирает и текст: транскрипт
+   * агента идёт через TranscriptSynchronizer, привязанный к тому же
+   * аудио-выходу (room_io.py:163-166). Наблюдалось как «агент мигает
+   * thinking -> listening и молчит», при том что эхо реплик посетителя
+   * приходило — у него своя, несинхронизированная ветка вывода.
+   *
+   * ponytail: платит трафиком и TTS за то, что никто не слышит. Убирается
+   * только на стороне платформы — RoomOutputOptions(audio_enabled=False) по
+   * флагу звонка, тогда текст пойдёт сразу и синтеза не будет вовсе.
+   */
+  async startCall(t, e = {}) {
+    if (E.has(this.connectionState))
+      throw this.raiseError("ALREADY_IN_CALL", this.connectionState);
+    const n = e.audio !== !1;
+    this.playAudio = n;
+    const { accessToken: i, url: r } = this.validateStartParams(t, n);
+    this.stoppingLocally = !1, this.reconnectSeen = !1, this.setConnectionState("connecting");
+    const c = new I();
+    if (this.room = c, this.wireRoomEvents(c), await this.connectRoom(c, r, i), this.stoppingLocally) {
+      await this.abandonConnectingCall(c);
+      return;
+    }
+    n && await this.publishMicrophone(c), this.callId = c.name, this.setConnectionState("connected"), this.syncAgentState(c), this.emitter.emit("callStarted", { callId: this.callId });
+  }
+  validateStartParams(t, e) {
+    const n = t.accessToken ?? t.access_token, i = t.url;
+    if (!n || !i)
+      throw this.raiseError("INVALID_PARAMS", "error");
+    if (!P(e))
+      throw this.raiseError("WEBRTC_UNSUPPORTED", "error");
+    const r = M(n);
+    if (r !== null && r * 1e3 <= Date.now())
+      throw this.raiseError("TOKEN_EXPIRED", "error");
+    return { accessToken: n, url: i };
+  }
+  async connectRoom(t, e, n) {
+    try {
+      await t.connect(
+        e,
+        n,
+        this.connectTimeoutMs === void 0 ? void 0 : {
+          peerConnectionTimeout: this.connectTimeoutMs,
+          websocketTimeout: this.connectTimeoutMs
+        }
+      );
+    } catch (i) {
+      throw this.teardownRoom(), this.raiseError(b(i), "error", i);
+    }
+  }
+  // stopCall() пришёл во время connecting (AC4/§1.2) — сворачиваем попытку
+  // без callStarted/error вместо продолжения к публикации микрофона
+  async abandonConnectingCall(t) {
+    await t.disconnect().catch(() => {
+    }), this.teardownRoom(), this.setConnectionState("disconnected");
+  }
+  async publishMicrophone(t) {
+    try {
+      await t.localParticipant.setMicrophoneEnabled(!0), await t.startAudio();
+    } catch (e) {
+      const n = O(e);
+      throw await t.disconnect().catch(() => {
+      }), this.teardownRoom(), this.raiseError(n, "error", e);
+    }
+  }
+  /**
+   * Отправляет текстовую реплику посетителя в разговор (VPT-108 §2.1).
+   * Своё сообщение в чат SDK не кладёт — его вернёт агент событием
+   * `transcript` с role: 'user' (§2.4): один источник правды и один порядок.
+   */
+  async sendText(t) {
+    const e = this.room;
+    if (!e || !E.has(this.connectionState))
+      throw this.raiseError("NOT_IN_CALL", this.connectionState);
+    const n = t.trim().slice(0, K);
+    if (n)
+      try {
+        await e.localParticipant.sendText(n, { topic: H });
+      } catch (i) {
+        throw this.raiseError("SERVER_ERROR", this.connectionState, i);
+      }
+  }
+  async stopCall() {
+    this.stoppingLocally = !0;
+    const t = this.room;
+    !t || !E.has(this.connectionState) || this.connectionState !== "connecting" && await t.disconnect().catch((e) => this.log.debug("[voice-client] disconnect", e));
+  }
+  destroy() {
+    this.stopCall(), this.playAudio = !0, this.destroyed = !0, this.teardownRoom(), this.emitter.clear(), this.audio.destroy(), this.connectionState = "idle", this.agentState = "unknown", this.callId = null;
+  }
+  wireRoomEvents(t) {
+    const e = (s, d, h) => {
+      this.log.debug("[voice-client] remote track subscribed", {
+        participant: h.identity,
+        participantID: h.sid,
+        trackID: s.sid,
+        streamTrackID: s.mediaStreamTrack.id,
+        kind: s.kind,
+        source: d.source,
+        muted: d.isMuted
+      }), s.kind === C.Kind.Audio && this.playAudio && this.audio.attach(s);
+    }, n = (s, d, h) => {
+      this.log.debug("[voice-client] remote track unsubscribed", {
+        participant: h.identity,
+        participantID: h.sid,
+        trackID: s.sid,
+        kind: s.kind,
+        source: d.source
+      }), s.kind === C.Kind.Audio && this.audio.detach(s);
+    }, i = (s, d, h) => {
+      this.log.debug("[voice-client] remote track subscription failed", {
+        participant: d.identity,
+        participantID: d.sid,
+        trackID: s,
+        reason: h
+      });
+    }, r = (s) => {
+      this.log.debug("[voice-client] remote participant connected", {
+        room: t.name,
+        participant: s.identity,
+        participantID: s.sid
+      }), !this.destroyed && this.syncAgentState(t);
+    }, c = () => {
+      this.destroyed || this.syncAgentState(t);
+    }, l = (s) => {
+      this.destroyed || this.applyLkConnectionState(s);
+    }, g = (s) => {
+      this.log.debug("[voice-client] room disconnected", {
+        room: t.name,
+        reason: s,
+        stoppingLocally: this.stoppingLocally
+      }), !this.destroyed && this.handleDisconnected(s);
+    };
+    t.registerTextStreamHandler(R, (s, d) => {
+      if (this.destroyed) return;
+      const h = d.identity === t.localParticipant.identity ? "user" : "agent";
+      this.readTranscriptSegment(s, h);
+    }), t.on(a.TrackSubscribed, e), t.on(a.TrackUnsubscribed, n), t.on(a.TrackSubscriptionFailed, i), t.on(a.ParticipantAttributesChanged, c), t.on(a.ParticipantConnected, r), t.on(a.ParticipantDisconnected, c), t.on(a.ConnectionStateChanged, l), t.on(a.Disconnected, g), this.roomCleanup = [
+      () => t.unregisterTextStreamHandler(R),
+      () => t.off(a.TrackSubscribed, e),
+      () => t.off(a.TrackUnsubscribed, n),
+      () => t.off(a.TrackSubscriptionFailed, i),
+      () => t.off(a.ParticipantAttributesChanged, c),
+      () => t.off(a.ParticipantConnected, r),
+      () => t.off(a.ParticipantDisconnected, c),
+      () => t.off(a.ConnectionStateChanged, l),
+      () => t.off(a.Disconnected, g)
+    ];
+  }
+  /**
+   * Разбор одного сегмента транскрипта (VPT-108 §1.3). Роль определена
+   * вызывающим — сравнением identity потока с локальным участником.
+   *
+   * Одна реплика приходит несколькими потоками с общим `lk.segment_id`
+   * (тот же дефект-дубль, что закрывался в №50 §9), поэтому пузырь
+   * сшивается по нему, а не по потоку. Чанки копятся ВНУТРИ потока, а текст
+   * потока ЗАМЕНЯЕТ текст сегмента: у реплик посетителя каждый поток несёт
+   * полный текст на момент отправки, а не хвост (`_ParticipantTranscription
+   * Output(is_delta_stream=False)`), и дописывание удвоило бы реплику.
+   *
+   * `final` — из атрибута `lk.transcription_final`, а не из факта закрытия
+   * потока: дельта-поток закрывается штатно, будучи нефинальным. У потока
+   * агента `true` приходит в трейлере, и livekit-client домешивает атрибуты
+   * трейлера в `reader.info` перед закрытием — поэтому читаем атрибут ПОСЛЕ
+   * цикла чтения.
+   */
+  readTranscriptSegment(t, e) {
+    var i;
+    const n = ((i = t.info.attributes) == null ? void 0 : i[F]) || t.info.id;
+    (async () => {
+      var c;
+      let r = "";
+      try {
+        for await (const l of t)
+          r += l, this.emitter.emit("transcript", { role: e, text: r, final: !1, id: n });
+      } catch {
+        return;
+      }
+      ((c = t.info.attributes) == null ? void 0 : c[x]) === "true" && this.emitter.emit("transcript", { role: e, text: r, final: !0, id: n });
+    })();
+  }
+  applyLkConnectionState(t) {
+    t === p.Reconnecting || t === p.SignalReconnecting ? (this.reconnectSeen = !0, this.setConnectionState("reconnecting")) : t === p.Connected && this.connectionState === "reconnecting" && this.setConnectionState("connected");
+  }
+  handleDisconnected(t) {
+    const e = this.callId, n = this.reconnectSeen, i = this.stoppingLocally;
+    if (this.teardownRoom(), i) {
+      this.setConnectionState("disconnected"), this.emitter.emit("callEnded", { callId: e, reason: "local" });
+      return;
+    }
+    if (n) {
+      this.setConnectionState("disconnected"), this.raiseError("CONNECTION_LOST", "disconnected"), this.emitter.emit("callEnded", { callId: e, reason: "connection_lost" });
+      return;
+    }
+    const c = t !== void 0 && U.has(t) ? "remote" : "error";
+    this.setConnectionState("disconnected"), this.emitter.emit("callEnded", { callId: e, reason: c });
+  }
+  teardownRoom() {
+    this.roomCleanup.forEach((t) => t()), this.roomCleanup = [], this.audio.clear(), this.room = null, this.agentState = "unknown";
+  }
+  syncAgentState(t) {
+    var n;
+    let e = "unknown";
+    for (const i of t.remoteParticipants.values()) {
+      const r = (n = i.attributes) == null ? void 0 : n[v];
+      if (r && V.has(r)) {
+        e = r;
+        break;
+      }
+    }
+    this.setAgentState(e);
+  }
+  setConnectionState(t) {
+    const e = this.connectionState;
+    e !== t && (this.connectionState = t, this.emitter.emit("connectionStateChanged", { state: t, previous: e }));
+  }
+  setAgentState(t) {
+    const e = this.agentState;
+    e !== t && (this.agentState = t, this.emitter.emit("agentStateChanged", { state: t, previous: e }), t === "speaking" ? this.emitter.emit("agentSpeakingStarted", {}) : e === "speaking" && this.emitter.emit("agentSpeakingStopped", {}));
+  }
+  /** Переводит ось соединения (если нужно), логирует и эмитит error (§1.4);
+   * возвращает VoiceCallError — вызывающий сам решает throw или нет. */
+  raiseError(t, e, n) {
+    e !== this.connectionState && this.setConnectionState(e);
+    const i = new _(t, this.connectionState, n);
+    return this.log.error(`[voice-client] ${t}`, n), this.emitter.emit("error", i), i;
+  }
+}
+export {
+  _ as VoiceCallError,
+  B as VoiceClient
+};

package/dist/logger.d.ts

@@ -0,0 +1,6 @@
+import type { Logger, LogLevel } from './types';
+/**
+ * §8 ТЗ №132: accessToken и любые поля с «token» в имени маскируются в
+ * логах безусловно — даже если интегратор передал свой logger.
+ */
+export declare function createLogger(level: LogLevel, custom?: Logger): Logger;

package/dist/types.d.ts

@@ -0,0 +1,86 @@
+/** Ось соединения (D4 ТЗ №132 §1.1) — жизненный цикл звонка. */
+export type ConnectionState = 'idle' | 'connecting' | 'connected' | 'reconnecting' | 'disconnected' | 'error';
+/** Ось активности агента (D4 §1.1) — из атрибута участника lk.agent.state. */
+export type AgentState = 'unknown' | 'initializing' | 'listening' | 'thinking' | 'speaking';
+export type VoiceErrorCode = 'INVALID_PARAMS' | 'WEBRTC_UNSUPPORTED' | 'MICROPHONE_PERMISSION_DENIED' | 'MICROPHONE_UNAVAILABLE' | 'TOKEN_EXPIRED' | 'TOKEN_INVALID' | 'CONNECTION_FAILED' | 'CONNECTION_LOST' | 'ALREADY_IN_CALL' | 'NOT_IN_CALL' | 'SERVER_ERROR';
+export interface VoiceError {
+    code: VoiceErrorCode;
+    message: string;
+    state: ConnectionState;
+    /** Исходная ошибка браузера/livekit-client — для логов интегратора (§1.4). */
+    cause?: unknown;
+}
+export type CallEndedReason = 'local' | 'remote' | 'connection_lost' | 'error';
+/**
+ * startCall принимает и camelCase, и сырой ответ POST /v1/calls/web
+ * (access_token/url + лишние поля объекта call) — §1.2 ТЗ №132.
+ */
+export interface StartCallParams {
+    accessToken?: string;
+    access_token?: string;
+    url: string;
+    [key: string]: unknown;
+}
+/**
+ * Per-call options — the mode belongs to the call, not to the client: the
+ * same page offers a voice call and a chat-only one side by side.
+ */
+export interface StartCallOptions {
+    /**
+     * false — chat-only call: no microphone is published and the agent's audio
+     * track is not subscribed. Text keeps flowing both ways (`sendText` /
+     * `transcript`), and neither MICROPHONE_* code can occur.
+     */
+    audio?: boolean;
+}
+export type LogLevel = 'silent' | 'error' | 'debug';
+export interface Logger {
+    error(message: string, ...args: unknown[]): void;
+    debug(message: string, ...args: unknown[]): void;
+}
+export interface VoiceClientOptions {
+    /** Куда вешать <audio>; по умолчанию — скрытый контейнер, создаваемый SDK. */
+    audioContainer?: HTMLElement;
+    logger?: Logger;
+    /** По умолчанию 'error' (§8: тихий лог, подробный — только явной опцией). */
+    logLevel?: LogLevel;
+    connectTimeoutMs?: number;
+}
+export interface CallStartedEvent {
+    callId: string;
+}
+export interface CallEndedEvent {
+    callId: string | null;
+    reason: CallEndedReason;
+}
+export interface ConnectionStateChangedEvent {
+    state: ConnectionState;
+    previous: ConnectionState;
+}
+export interface AgentStateChangedEvent {
+    state: AgentState;
+    previous: AgentState;
+}
+/** Реплика разговора из топика lk.transcription (VPT-108 §1.1). */
+export interface TranscriptEvent {
+    /** 'user' — реплика посетителя, 'agent' — реплика агента (D1). */
+    role: 'user' | 'agent';
+    /** Накопленный текст реплики на момент события. */
+    text: string;
+    /** false — реплика ещё растёт, true — сегмент закрыт. */
+    final: boolean;
+    /** Идентификатор реплики: сшивает дельты одного сегмента в один пузырь. */
+    id: string;
+}
+export interface VoiceClientEventMap {
+    callStarted: CallStartedEvent;
+    callEnded: CallEndedEvent;
+    connectionStateChanged: ConnectionStateChangedEvent;
+    agentStateChanged: AgentStateChangedEvent;
+    agentSpeakingStarted: Record<string, never>;
+    agentSpeakingStopped: Record<string, never>;
+    transcript: TranscriptEvent;
+    error: VoiceError;
+}
+export type VoiceClientEventName = keyof VoiceClientEventMap;
+export type VoiceClientEventHandler<E extends VoiceClientEventName> = (payload: VoiceClientEventMap[E]) => void;

package/dist/utils.d.ts

@@ -0,0 +1,15 @@
+/**
+ * WebRTC/secure-context детект (§1.4 ТЗ №132: WEBRTC_UNSUPPORTED).
+ *
+ * Secure context и RTCPeerConnection нужны любому звонку — текст LiveKit
+ * тоже везёт по WebRTC-датаканалу. getUserMedia спрашиваем только у звонка,
+ * который публикует микрофон: chat-only ({ audio: false }) работает и там,
+ * где микрофона нет вовсе.
+ */
+export declare function isWebRtcSupported(requireMicrophone?: boolean): boolean;
+/**
+ * exp из payload JWT без проверки подписи — только для локального
+ * пред-чека TOKEN_EXPIRED до connect (§3.2/§1.4); сервер токен всё равно
+ * валидирует сам. atob — нативный, без зависимости на jwt-decode.
+ */
+export declare function decodeJwtExpiry(token: string): number | null;