@vibexnpm/talkx 4.0.1 → 5.2.0

package/src/talkflow/delegates.js

@@ -65,7 +65,16 @@ const CHAT_DELEGATE_METHODS = [
     'deactivateRoomPmPrompt',
     'getRoomPmPromptVersions',
     'activateRoomPmPromptVersion',
-    'previewRoomPmPrompt'
+    'previewRoomPmPrompt',
+    // 투표 — 투표 서버는 클러스터 내부에만 있어 클라이언트가 직접 부를 수 없다. 전부 채팅 서버 경유.
+    'createVote',
+    'getVotes',
+    'getVote',
+    'updateVote',
+    'deleteVote',
+    'closeVote',
+    'submitVote',
+    'uploadVoteImage'
 ];
 
 const WEBRTC_DELEGATE_METHODS = [

package/src/talkflow/eventForwarding.js

@@ -24,6 +24,7 @@ const CHAT_EVENT_MAP = [
     ['messageRead', 'messageRead'],
     ['typing', 'typing'],
     ['assistantProgress', 'assistantProgress'],
+    ['assistantRoomProgress', 'assistantRoomProgress'],
     ['summaryUpdate', 'summaryUpdate'],
     ['memberJoined', 'memberJoined'],
     ['memberLeft', 'memberLeft'],

package/src/talkflow/session.js

@@ -33,6 +33,7 @@ export function initializeSubClients(client) {
         apiClient: client.apiClient,
         userId: client._userId,
         syncOnReconnect: client.options.syncOnReconnect,
+        assistantStreamReplay: client.options.assistantStreamReplay,
         rewindMillis: client.options.rewindMillis,
         maxSyncPages: client.options.maxSyncPages,
         syncPageSize: client.options.syncPageSize,

package/src/utils/ApiClient.js

@@ -62,10 +62,12 @@ class ApiClient {
      * @param {Object} [options] - 옵션
      * @param {Object} [options.body] - 요청 본문
      * @param {Object} [options.params] - URL 파라미터
+     * @param {Object} [options.headers] - 이 요청에만 얹는 추가 헤더. 기본 헤더(Authorization 등)와 병합된다.
+     *   같은 이름이면 이 값이 이긴다 — 인증 헤더를 덮어쓰지 않도록 호출자가 주의한다.
      * @returns {Promise<Object>}
      */
     async request(method, path, options = {}) {
-        const { body, params } = options;
+        const { body, params, headers } = options;
 
         // URL 빌드
         let url = `${this.baseUrl}${path}`;
@@ -92,7 +94,7 @@ class ApiClient {
 
             response = await fetch(url, {
                 method,
-                headers: this._getHeaders(),
+                headers: headers ? { ...this._getHeaders(), ...headers } : this._getHeaders(),
                 body: body ? JSON.stringify(body) : undefined,
                 signal: controller.signal
             });
@@ -152,10 +154,12 @@ class ApiClient {
      * @param {string} path - API 경로
      * @param {Object} [body] - 요청 본문
      * @param {Object} [params] - URL 파라미터
+     * @param {Object} [headers] - 이 요청에만 얹는 추가 헤더 (예: {@code X-Idempotency-Key}).
+     *   기존 호출자는 인자를 넘기지 않으므로 동작이 바뀌지 않는다.
      * @returns {Promise<Object>}
      */
-    post(path, body, params) {
-        return this.request('POST', path, { body, params });
+    post(path, body, params, headers) {
+        return this.request('POST', path, { body, params, headers });
     }
 
     /**

package/types/index.d.ts

@@ -753,6 +753,177 @@ export interface ChatMessage {
     decisionRequest?: DecisionRequest | null;
     /** 사용자의 선택. 어느 카드인지는 {@code replyTo} 가 특정한다. */
     decisionResponse?: DecisionResponse | null;
+    /**
+     * 투표 카드 — 투표가 열리거나 마감·취소됐음을 알리는 메시지의 payload.
+     *
+     * <p><b>모르면 그냥 텍스트로 그려라 — 그게 정상 동작이다.</b> {@code content} 에 같은 내용이
+     * 사람이 읽는 형태로 들어 있다. 반대로 카드를 그린다면 {@code content} 를 다시 그리지 마라.</p>
+     *
+     * <p>카드에는 집계가 없다. 결과는 {@code voteId} 로 {@link ChatClient.getVote} 를 호출해 받는다 —
+     * 마스킹이 호출자마다 다르게 계산되기 때문이다.</p>
+     */
+    voteCard?: VoteCard | null;
+}
+
+/**
+ * 투표 카드 payload — 이벤트 하나당 메시지 하나다(개설·마감·취소).
+ *
+ * <p>이미 발행된 카드는 고쳐지지 않는다. 투표가 삭제돼도 개설 카드는 그대로 남고 조회가 404 가 되며,
+ * 「취소됨」 표시는 화면 몫이다(별도의 취소 카드도 함께 발행된다).</p>
+ */
+export interface VoteCard {
+    voteId: string;
+    /**
+     * {@code 'OPENED'} | {@code 'CLOSED'} | {@code 'CANCELED'}.
+     *
+     * <p>🔴 <b>모르는 값이 올 수 있다</b> — 서버가 나중에 종류를 늘려도 구버전이 깨지지 않도록 열린 문자열이다.
+     * switch 의 default 는 텍스트 폴백으로 둔다.</p>
+     */
+    kind: 'OPENED' | 'CLOSED' | 'CANCELED' | (string & {});
+    /**
+     * 발행 시점의 질문 <b>스냅샷</b>. 참여자가 0명인 동안 투표가 수정될 수 있으므로 최신값이 필요하면
+     * {@link ChatClient.getVote} 로 조회한다. 마감·취소 카드에서는 비어 있을 수 있다.
+     */
+    question?: string | null;
+    /** 마감 예정 시각 (epoch millis, UTC). 마감·취소 카드에서는 null 일 수 있다. */
+    closeAt?: number | null;
+}
+
+// ── 투표 (createVote / getVotes / getVote / submitVote ...) ──
+
+/** 투표 등록 폼 — 생성과 수정이 같은 타입이다({@code PATCH} 지만 부분 수정이 아니다). */
+export interface VoteForm {
+    /** 최대 500자. 공백만이면 거절. */
+    question: string;
+    type: 'SINGLE' | 'MULTIPLE';
+    /** 양수. {@code SINGLE} 이면 1. */
+    maxSelections: number;
+    /** {@code 'IMAGE'} 라는 값은 없다. */
+    optionType: 'TEXT' | 'TEXT_WITH_IMAGE';
+    /** 마감 시각 (epoch millis). 과거·현재 불가 · 최대 30일 뒤. 무기한 투표는 없다. */
+    closeAt: number;
+    /** 2~10개. */
+    options: VoteFormOption[];
+}
+
+export interface VoteFormOption {
+    /** {@code .} {@code $} NUL 사용 불가 · 최대 100자 · 중복 불가 (집계 필드명으로 쓰인다). */
+    id: string;
+    /** 최대 200자. */
+    content: string;
+    /** 표시 순서. */
+    order: number;
+    /**
+     * {@link ChatClient.uploadVoteImage} 가 돌려준 값을 <b>가공 없이</b> 넣는다 — 서버가 문자열로 비교한다.
+     * 채팅 첨부 URL 은 쓸 수 없다. {@code optionType: 'TEXT'} 면 넣으면 안 되고, 빈 문자열도 거절된다.
+     */
+    imageUrl?: string | null;
+}
+
+/** 투표 단건 + 집계 — 생성 · 수정 · 단건조회 · 접수 응답. */
+export interface Vote {
+    voteId: string;
+    roomId: string;
+    question: string;
+    type: 'SINGLE' | 'MULTIPLE';
+    optionType: 'TEXT' | 'TEXT_WITH_IMAGE';
+    maxSelections: number;
+    /**
+     * {@code 'OPEN'} | {@code 'CLOSED'}.
+     *
+     * <p>🔴 <b>이 값만으로 마감을 판정하면 안 된다</b> — 서버 자동 마감이 미구현이라 {@code closeAt} 이
+     * 지났는데도 {@code 'OPEN'} 인 투표가 있고, 그건 마감된 것으로 동작한다. 둘을 함께 본다.</p>
+     */
+    status: 'OPEN' | 'CLOSED' | (string & {});
+    /** epoch millis. */
+    closeAt: number;
+    /** 마감 전이면 null. epoch millis. */
+    closedAt?: number | null;
+    creatorId: string;
+    createdAt: number;
+    updatedAt: number;
+    /**
+     * 결과 공개 여부. 공개 조건은 「내가 응답했다」 또는 「마감됐다」.
+     *
+     * <p>🔴 {@code false} 일 때의 {@code count}/{@code ratio} 0 은 「참여자가 없다」가 아니라
+     * <b>서버가 가린 값</b>이다. 「아직 0표」로 표시하면 거짓말이 된다.</p>
+     */
+    revealed: boolean;
+    /** 응답자 수. <b>득표 합이 아니다</b> — 복수 선택에서 값이 다르다. */
+    totalResponses: number;
+    /** 호출자가 고른 선택지. 없으면 빈 배열. 비공개 상태에서도 채워진다(재투표 화면용). */
+    myOptionIds: string[];
+    options: VoteOptionResult[];
+}
+
+export interface VoteOptionResult {
+    optionId: string;
+    content: string;
+    order: number;
+    /** {@code optionType} 이 {@code 'TEXT'} 면 항상 null. */
+    imageUrl?: string | null;
+    /** 득표 수. 비공개면 0(가려진 값). */
+    count: number;
+    /**
+     * 응답자 대비 %, 소수 첫째 자리.
+     *
+     * <p>분모가 <b>응답자 수</b>이지 총 선택 수가 아니다 — 복수 선택 투표에서는 합이 100을 넘는 것이
+     * 정상이고, 화면이 「복수 응답」임을 표기해야 한다.</p>
+     */
+    ratio: number;
+}
+
+/** {@link ChatClient.getVotes} 옵션. */
+export interface GetVotesOptions {
+    /** 이전 응답의 {@code nextCursor} 를 <b>그대로</b>. 불투명 문자열이라 파싱하지 않는다. */
+    cursor?: string;
+    /** 기본 20, 최대 100. 초과분은 서버가 조용히 100 으로 보정한다(에러 아님). */
+    limit?: number;
+}
+
+/** {@link ChatClient.getVotes} 반환. */
+export interface VoteList {
+    /** 최신순. 비면 끝이다. */
+    items: VoteListItem[];
+    /** null 이면 끝. 마지막 페이지가 정확히 {@code limit} 개면 채워진 채 오고, 그 커서로 부르면 빈 목록이 온다. */
+    nextCursor?: string | null;
+}
+
+/** 목록 항목 — {@code optionType} · {@code options} · {@code myOptionIds} · {@code revealed} 가 <b>없다</b>. */
+export interface VoteListItem {
+    voteId: string;
+    question: string;
+    type: 'SINGLE' | 'MULTIPLE';
+    status: 'OPEN' | 'CLOSED' | (string & {});
+    closeAt: number;
+    creatorId: string;
+    createdAt: number;
+    /** 참여자 수. 선택지별 집계는 목록에 없다 — 마스킹이 사용자마다 다르기 때문이다. */
+    responseCount: number;
+}
+
+/** {@link ChatClient.createVote} 옵션. */
+export interface CreateVoteOptions {
+    /**
+     * 🔴 <b>필수.</b> SDK 가 대신 만들지 않는다 — 만들면 그 값이 호출자에게 남지 않아 응답만 유실된
+     * 타임아웃에서 복구가 불가능하다(다음 호출이 새 키를 만들어 투표가 두 개 생긴다).
+     *
+     * <p>한 투표당 한 번 만들어 보관하고, 같은 시도의 재시도에는 <b>같은 값</b>을 넘긴다 —
+     * 그러면 서버가 기존 투표를 돌려준다(201, 같은 voteId).</p>
+     */
+    idempotencyKey: string;
+}
+
+/** {@link ChatClient.uploadVoteImage} 옵션. */
+export interface UploadVoteImageOptions {
+    onProgress?: (progress: { loaded: number; total: number; percent: number }) => void;
+    signal?: AbortSignal;
+}
+
+/** {@link ChatClient.uploadVoteImage} 반환. */
+export interface VoteImage {
+    /** 생성·수정 본문의 {@code options[].imageUrl} 에 <b>가공 없이</b> 넣는다. */
+    imageUrl: string;
 }
 
 /**
@@ -990,35 +1161,103 @@ export interface TypingEvent {
  *
  * typing 과 별개의 가산 UX 레이어(설계 ASSISTANT_PROGRESS_STREAMING_DESIGN.md). 서버가 typing 도 이중발행하므로
  * 구버전 SDK 는 본 이벤트를 못 받아도 기존 typing 으로 정상 동작한다. UI 는 `active:true` 면 `label`(또는 `phase`)
- * 로 단계를 표시하고, `active:false`(DONE·어시 메시지 도착·TTL 만료) 면 해제한다.
+ * 로 단계를 표시하고, `active:false`(DONE·TTL 만료) 면 해제한다.
+ *
+ * ⚠️ **v5.0.0 breaking — 이 이벤트는 `streamId` 단위다.** 한 방에 동시 스트림이 실재하므로(PM 방에서 트리거가
+ * 겹치면 각각 streamId 를 받는다) `active:false` 는 **그 stream 하나**를 뜻한다. 방마다 버블 하나를 그리는
+ * 기존 코드에 그대로 물리면 **같은 방의 다른 살아 있는 버블까지 숨긴다**. 둘 중 하나를 택한다.
+ *
+ * - (권장) `roomId + streamId` 를 키로 버블을 관리한다 — 최종 목표 형태.
+ * - (이행용 다리) {@link AssistantRoomProgressEvent} 를 대신 구독한다. 리스너 이름만 바꾸면 기존 단일 버블
+ *   렌더가 그대로 동작한다.
  *
  * 현재는 PM_BACKSTAGE(방당 단일 PM) 만 phase 를 발행 — 멘션/버튼/14인 경로는 본 이벤트 없이 typing 만.
  */
 export interface AssistantProgressEvent {
     /** 채팅방 ID. */
     roomId: string;
-    /** 어시 응답 1회분 식별(멀티 응답/중복 dedup). 일부 종료 emit 에선 null. */
-    streamId: string | null;
+    /**
+     * 어시 응답 1회분 식별 — **v5.0.0 부터 항상 non-null**.
+     *
+     * UI 는 `roomId + streamId` 로 버블을 키잉한다. SDK 는 `streamId` 없는 서버 이벤트를 아예 버리므로
+     * 이 값이 비어 오는 emit 은 없다(v4.x 는 일부 종료 emit 에서 null 이 올 수 있었다).
+     */
+    streamId: string;
     /** 진행 주체 페르소나 ID. */
     personaId: string | null;
     /** 진행 단계 — `active:true` 일 때. 종료 시 null. */
     phase: 'THINKING' | 'SEARCHING' | 'PLANNING' | 'WRITING' | null;
     /** phase 의 기본 표시 라벨(예: "생각 중…"). SDK 매핑 — 커스텀하려면 `phase` 사용. 종료 시 null. */
     label: string | null;
-    /** true=진행중(PHASE/DELTA) / false=종료(DONE·메시지 도착·TTL). */
+    /** true=진행중(PHASE/DELTA) / false=종료(DONE·TTL). */
     active: boolean;
-    /** 토큰 스트림 누적 텍스트(B) — DELTA 수신 시 지금까지 모인 전체. 버블에 그대로 렌더. PHASE-only/종료 시 null. */
+    /**
+     * 토큰 스트림 누적 텍스트(B) — DELTA 수신 시 지금까지 모인 전체. 버블에 그대로 렌더.
+     * PHASE-only/종료 시 null. **`textAvailable:false` 면 항상 null** — 그 땐 `label` 을 그린다.
+     */
     text?: string | null;
-    /** 이번 토큰 청크(B) — append 렌더를 선호할 때. DELTA 수신 시만. */
+    /** 이번 토큰 청크(B) — append 렌더를 선호할 때. DELTA 수신 시만. `textAvailable:false` 면 null. */
     delta?: string | null;
     /** 토큰 청크 순서/누락 감지(B) — DELTA 수신 시만. */
     seq?: number | null;
+    /**
+     * 본문을 신뢰할 수 있는가 (v4.2.0 추가).
+     *
+     * `false` = 앞부분을 받은 적이 없다 — 스트리밍 도중 재입장/새로고침(late join)했거나 WS 순단으로 `seq` 에
+     * 구멍이 났다는 뜻. 이때 `text`/`delta` 는 null 로 오고 **이후 청크도 누적되지 않는다**.
+     * UI 는 본문 대신 `label`(예: "작성 중…")을 표시하고 최종 메시지를 기다리면 된다.
+     *
+     * 예전 동작은 이 경우에도 받은 조각을 누적본처럼 넘겨서 **잘린 답변**이 화면에 그려졌다.
+     */
+    textAvailable?: boolean;
     /** 종료(DONE) 결과 — DONE 수신 시만. */
     status?: 'SUCCEEDED' | 'FAILED' | 'CANCELLED' | 'TIMEOUT' | null;
     /** 종료(DONE, SUCCEEDED) 시 영속된 최종 메시지 ID. */
     messageId?: string | null;
-    /** 종료 사유 — 'message'(어시 메시지 도착) / 'timeout'(TTL). DONE 수신 해제엔 없음. */
-    reason?: 'message' | 'timeout' | null;
+    /**
+     * 종료 사유 — 'timeout'(TTL 만료). DONE 수신 해제엔 없음.
+     *
+     * v4.2.0 부터 `'message'` 는 emit 되지 않았고(어시 메시지 도착은 진행 표시를 끄지 않는다 —
+     * 종료 SSOT = DONE + TTL), **v5.0.0 에서 유니온에서도 제거**했다.
+     */
+    reason?: 'timeout' | null;
+    /** 이 stream 의 마지막 seq — 스냅샷 병합 커서(v5.0.0). DELTA 0건이면 -1. */
+    lastSeq?: number;
+    /**
+     * `true` = 서버 스냅샷으로 **복원된** 진행분(v5.1.0).
+     *
+     * 스트리밍 도중 재입장했거나 새로 들어와서, 구독 전에 이미 발행된 앞부분을 REST 스냅샷으로 받아온
+     * 경우다. UI 가 "이어보는 중" 같은 표시를 하고 싶을 때만 쓰면 되고, 렌더 로직은 평소와 같다.
+     */
+    resumed?: boolean;
+}
+
+/**
+ * 방 단위 AI 진행 표시 집계 (v5.0.0 신설).
+ *
+ * <p>{@link AssistantProgressEvent} 가 `streamId` 단위로 바뀌면서, **방마다 임시 버블 하나**를 그리는 기존
+ * UI 를 위한 이행용 다리로 제공한다. 리스너 이름만 `assistantProgress` → `assistantRoomProgress` 로 바꾸면
+ * 기존 렌더 코드가 그대로 동작한다.</p>
+ *
+ * <p>`active` 는 방에 살아 있는 stream 이 **하나라도** 있으면 true 다. 그래서 동시 응답 중 하나가 끝나도
+ * 버블이 사라지지 않는다. 표시 내용(`text`/`label`/`phase`)은 **가장 최근에 갱신된** stream 을 따른다.</p>
+ */
+export interface AssistantRoomProgressEvent {
+    /** 채팅방 ID. */
+    roomId: string;
+    /** 방에 살아 있는 stream 이 하나라도 있으면 true. */
+    active: boolean;
+    /** 살아 있는 stream 개수. 2 이상이면 동시 응답 중이다. */
+    streamCount: number;
+    /** 표시 기준이 된 stream (가장 최근 갱신). 없으면 null. */
+    streamId: string | null;
+    personaId: string | null;
+    phase: 'THINKING' | 'SEARCHING' | 'PLANNING' | 'WRITING' | null;
+    label: string | null;
+    /** 표시 기준 stream 의 누적 본문. `textAvailable:false` 거나 진행 중이 아니면 null. */
+    text?: string | null;
+    /** 표시 기준 stream 의 본문 신뢰 여부 — false 면 `label` 을 그린다. */
+    textAvailable?: boolean;
 }
 
 // ============================================================================
@@ -1061,6 +1300,13 @@ export interface TalkFlowClientOptions {
      * <p>복구된 메시지는 일반 `chatMessage` 이벤트로 재생되므로 수신 코드를 바꿀 필요가 없다.</p>
      */
     syncOnReconnect?: boolean;
+    /**
+     * 방 구독·재연결 시 진행 중 AI 스트림을 서버 스냅샷으로 이어받을지. 기본 true (v5.1.0).
+     *
+     * <p>스트림은 Pub/Sub 라 구독 시점 이후만 오므로, 스트리밍 도중 재입장하면 앞부분을 받을 방법이
+     * 스냅샷뿐이다. `syncOnReconnect`(메시지 갭 복구)와 <b>별개 경로</b>다 — 그쪽을 꺼도 이건 돈다.</p>
+     */
+    assistantStreamReplay?: boolean;
     /** 갭 복구 첫 페이지에만 적용되는 되감기 폭 (ms). 기본 3000. 서버가 상한 clamp 후 1회 차감. */
     rewindMillis?: number;
     /** 갭 복구 페이지 상한. 기본 5. 초과 시 최신 페이지 재로드로 전환하고 `gapTruncated` 를 발행. */
@@ -1438,6 +1684,7 @@ export interface TalkFlowClientEvents {
     messageRead: MessageReadEventPayload;
     typing: TypingEvent;
     assistantProgress: AssistantProgressEvent;
+    assistantRoomProgress: AssistantRoomProgressEvent;
     /** Rolling 누적 요약 완료/실패 통지 (transient) — refreshSummary 후. */
     summaryUpdate: SummaryUpdateEvent;
     memberJoined: MemberChangePayload;
@@ -1573,6 +1820,7 @@ export interface ChatClientEvents {
     messageRead: MessageReadEventPayload;
     typing: TypingEvent;
     assistantProgress: AssistantProgressEvent;
+    assistantRoomProgress: AssistantRoomProgressEvent;
     /** Rolling 누적 요약 완료/실패 통지 (transient) — refreshSummary 후. */
     summaryUpdate: SummaryUpdateEvent;
 }
@@ -1644,6 +1892,24 @@ export class ChatClient implements SdkEventEmitter<ChatClientEvents> {
     refreshSummary(roomId: string, options?: RefreshSummaryOptions): Promise<RefreshSummaryResult>;
     /** Rolling 누적 요약 조회 — rollup + segment 페이지. 저장된 요약의 단일 진실 소스. */
     getSummary(roomId: string, options?: GetSummaryOptions): Promise<RoomSummaryView>;
+
+    // ── 투표 ──
+    /** 투표 생성. {@code idempotencyKey} 필수 — 재시도에 같은 값을 넘겨야 투표가 두 개 안 생긴다. */
+    createVote(roomId: string, vote: VoteForm, options: CreateVoteOptions): Promise<Vote>;
+    /** 방의 투표 목록(최신순). 집계는 없고 참여자 수만 있다. */
+    getVotes(roomId: string, options?: GetVotesOptions): Promise<VoteList>;
+    /** 투표 단건 + 집계. 마스킹이 호출자마다 다르므로 공유 캐시에 넣지 않는다. */
+    getVote(roomId: string, voteId: string): Promise<Vote>;
+    /** 투표 수정 — 폼 전체를 보낸다. 개설자 + 참여자 0명일 때만. */
+    updateVote(roomId: string, voteId: string, vote: VoteForm): Promise<Vote>;
+    /** 투표 삭제(204). 이미 발행된 카드는 남고 조회가 404 가 된다. */
+    deleteVote(roomId: string, voteId: string): Promise<void>;
+    /** 수동 마감(204). 결과를 보려면 {@link getVote} 를 다시 호출한다. */
+    closeVote(roomId: string, voteId: string): Promise<void>;
+    /** 투표 접수 · 재투표 — 같은 메서드. 응답에 갱신된 집계가 함께 온다. */
+    submitVote(roomId: string, voteId: string, optionIds: string[]): Promise<Vote>;
+    /** 선택지 이미지 업로드. 반환 {@code imageUrl} 을 가공 없이 폼에 넣는다. */
+    uploadVoteImage(roomId: string, file: File | Blob, options?: UploadVoteImageOptions): Promise<VoteImage>;
     /** 방 PM 프롬프트 레이어 조회 — PM_BACKSTAGE 방 전용, 참여자 전체. 미등록 시 404. */
     getRoomPmPrompt(roomId: string): Promise<PmPromptLayerResponse>;
     /** 방 PM 프롬프트 레이어 등록/수정 (upsert, 새 버전 자동 기록) — 방 주인(OWNER) 전용. content 1~2,000자. */
@@ -2012,6 +2278,24 @@ export default class TalkFlowClient implements SdkEventEmitter<TalkFlowClientEve
     refreshSummary(roomId: string, options?: RefreshSummaryOptions): Promise<RefreshSummaryResult>;
     /** Rolling 누적 요약 조회 — rollup + segment 페이지. 저장된 요약의 단일 진실 소스. */
     getSummary(roomId: string, options?: GetSummaryOptions): Promise<RoomSummaryView>;
+
+    // ── 투표 ──
+    /** 투표 생성. {@code idempotencyKey} 필수 — 재시도에 같은 값을 넘겨야 투표가 두 개 안 생긴다. */
+    createVote(roomId: string, vote: VoteForm, options: CreateVoteOptions): Promise<Vote>;
+    /** 방의 투표 목록(최신순). 집계는 없고 참여자 수만 있다. */
+    getVotes(roomId: string, options?: GetVotesOptions): Promise<VoteList>;
+    /** 투표 단건 + 집계. 마스킹이 호출자마다 다르므로 공유 캐시에 넣지 않는다. */
+    getVote(roomId: string, voteId: string): Promise<Vote>;
+    /** 투표 수정 — 폼 전체를 보낸다. 개설자 + 참여자 0명일 때만. */
+    updateVote(roomId: string, voteId: string, vote: VoteForm): Promise<Vote>;
+    /** 투표 삭제(204). 이미 발행된 카드는 남고 조회가 404 가 된다. */
+    deleteVote(roomId: string, voteId: string): Promise<void>;
+    /** 수동 마감(204). 결과를 보려면 {@link getVote} 를 다시 호출한다. */
+    closeVote(roomId: string, voteId: string): Promise<void>;
+    /** 투표 접수 · 재투표 — 같은 메서드. 응답에 갱신된 집계가 함께 온다. */
+    submitVote(roomId: string, voteId: string, optionIds: string[]): Promise<Vote>;
+    /** 선택지 이미지 업로드. 반환 {@code imageUrl} 을 가공 없이 폼에 넣는다. */
+    uploadVoteImage(roomId: string, file: File | Blob, options?: UploadVoteImageOptions): Promise<VoteImage>;
     /** 방 PM 프롬프트 레이어 조회 — PM_BACKSTAGE 방 전용, 참여자 전체. 미등록 시 404. */
     getRoomPmPrompt(roomId: string): Promise<PmPromptLayerResponse>;
     /** 방 PM 프롬프트 레이어 등록/수정 (upsert, 새 버전 자동 기록) — 방 주인(OWNER) 전용. content 1~2,000자. */