WebSocket 連線與認證

POST /api/v1/auth/ticket
X-API-Key: vas_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

{
  "ticket": "aBcDeFgHiJkLmNoPqRsTuVwXyZ012345",
  "expires_in": 60
}

// 瀏覽器原生支援
const ws = new WebSocket('wss://vas-poc.vurbo.ai/ws', [`ticket.${ticket}`]);

ws.onopen = () => {
  console.log('Connected! Protocol:', ws.protocol);
  // 開始使用 WebSocket...
};

ws.onerror = (error) => {
  console.error('Connection failed:', error);
};

const WebSocket = require('ws');

const ws = new WebSocket('wss://vas-poc.vurbo.ai/ws', [`ticket.${ticket}`]);

{
  "type": "服務類型",
  "data": { ... }
}

{
  "type": "error",
  "data": {
    "error_code": "auth_invalid_api_key",
    "severity": "fatal",
    "message": "API Key 無效",
    "context": "auth",
    "request_id": "req_abc123xyz789",
    "timestamp": "2026-01-15T10:30:45.123Z"
  }
}

{
  "type": "health",
  "data": {
    "action": "ping"
  }
}

{
  "type": "health",
  "data": {
    "action": "pong"
  }
}

1. start 成功 → session_started 內含 resume_token + resume_grace_seconds（請保存）
2. 連線中斷  → 在 grace 期間內：
   a. 重新向後端取得一張「新的」一次性 Ticket
   b. 以 Sec-WebSocket-Protocol: ["ticket.<新ticket>", "resume.<resume_token>"] 重連
3. 成功     → 伺服器回 resume_ok（含 server_last_sid）→ 像 start 後一樣「重開一段音訊流」
   失敗     → 伺服器回 resume_* 錯誤 → 重新取 Ticket 後 fallback 全新 start（使用者已結束錄音時除外）

{
  "type": "voice-translation",
  "data": {
    "action": "session_started",
    "session_id": "...",
    "task_id": "...",
    "resume_token": "<43 字元，請保存到本次會話結束>",
    "resume_grace_seconds": 45,
    "server_time": 1749550000000
  }
}

const ws = new WebSocket(url, [`ticket.${newTicket}`, `resume.${resumeToken}`]);

{
  "type": "voice-translation",
  "data": {
    "action": "resume_ok",
    "session_id": "...",
    "task_id": "...",
    "recording_type": "transcribe",
    "recognition_mode": "single",
    "server_last_sid": 42,
    "server_last_offset_ms": 125000,
    "server_recording_ms": 127500,
    "is_paused": false,
    "settings": {
      "speaking_speed": "normal",
      "profanity_handling": "mask",
      "audio_format": "pcm",
      "transcription_languages": ["zh-TW"],
      "translation_languages": ["en-US"],
      "realtime_translation": true,
      "auto_summary": true,
      "summary_plain_text": false,
      "summary_template": "meeting",
      "summary_language": "zh-TW",
      "summary_mode": "builtin",
      "name": "產品會議"
    },
    "message": "已續接原會話"
  }
}

class ResumableVASClient {
  // getTicket: async () => string（每次都向後端取「新的」一次性 Ticket）
  constructor({ wsUrl, getTicket, buildStartMessage }) {
    this.wsUrl = wsUrl;
    this.getTicket = getTicket;
    this.buildStartMessage = buildStartMessage; // () => start 訊息物件
    this.resumeToken = null;
    this.graceSeconds = 45;
    this.resumeDeadline = 0; // 寬限期截止（epoch ms）；0 = 未在續接中
    this.closedByUser = false;
  }

  async start() {
    this.closedByUser = false;
    await this._connect(false);
  }

  stop() {
    this.closedByUser = true;
    this.resumeToken = null;
    this.ws?.close(1000, 'client stop');
  }

  async _connect(isResume) {
    const ticket = await this.getTicket(); // 一次性，每次重連都要新的
    const protocols = isResume && this.resumeToken
      ? [`ticket.${ticket}`, `resume.${this.resumeToken}`]
      : [`ticket.${ticket}`];

    this.ws = new WebSocket(this.wsUrl, protocols);
    this.ws.onopen = () => {
      if (!isResume) this.ws.send(JSON.stringify(this.buildStartMessage())); // 全新 start
      // isResume：等伺服器回 resume_ok 再重開音訊流（見下方 onmessage）
    };
    // staleness guard：舊 socket 遲到的事件（e.target !== this.ws）一律忽略，避免 resume
    // fallback 後雙連線、或舊連線的 onclose 污染新狀態。
    this.ws.onmessage = (e) => { if (e.target === this.ws) this._onMessage(JSON.parse(e.data)); };
    this.ws.onclose = (e) => { if (e.target === this.ws) this._onClose(); };
    this.ws.onerror = () => {}; // onclose 會統一處理
  }

  _onMessage(msg) {
    const d = msg.data || {};
    switch (d.action) {
      case 'session_started':
        this.resumeToken = d.resume_token;            // 保存 token
        this.graceSeconds = d.resume_grace_seconds || 45;
        this.resumeDeadline = 0;                       // 連線正常，清掉續接狀態
        this.startAudioStream();                       // 開始送音訊
        break;
      case 'resume_ok':
        // 續接成功：像 start 後一樣重開音訊流（WebM 必送新容器）
        this.resumeDeadline = 0;
        this.restartAudioStream();
        break;
      default:
        if (msg.type === 'error' && String(d.error_code).startsWith('resume_')) {
          // 續接失敗 → 清 token、fallback 全新 start（_connect 會取新 ticket）
          this.resumeToken = null;
          this.resumeDeadline = 0;
          // 使用者已結束錄音（例如續接途中呼叫了 stop()）：不要再開始新的錄音
          if (this.closedByUser) return;
          this._connect(false).catch((err) => this.onFatal(err));
        }
        // 其餘事件（origin / translation 等）依 sid 更新 UI
    }
  }

  _onClose() {
    if (this.closedByUser || !this.resumeToken) return this.onFatal?.();
    // 第一次斷線：設定寬限期截止
    if (this.resumeDeadline === 0) {
      this.resumeDeadline = Date.now() + this.graceSeconds * 1000;
    }
    if (Date.now() < this.resumeDeadline) {
      // 寬限期內：嘗試續接（失敗則退避重試，仍在期限內）
      this._connect(true).catch(() => {
        if (Date.now() < this.resumeDeadline) setTimeout(() => this._onClose(), 1000);
        else this.onResumeExhausted?.();
      });
    } else {
      this.onResumeExhausted?.(); // 寬限期已過，放棄續接
    }
  }

  // 以下由你依音訊格式實作：
  startAudioStream() {}    // 開始擷取並送 audio frame
  restartAudioStream() {}  // 重開音訊流（WebM=新容器；PCM=續送）
  onResumeExhausted() {}   // 寬限期內未能續接（視為本場結束 / 提示使用者）
  onFatal() {}             // 不可恢復
}