@openmarket/rooms-client 0.6.0 → 0.7.0

package/src/social-client.ts

@@ -1,6 +1,9 @@
 import { resolveRoomsWsUrl } from "./client.js";
 import { envString, ROOM_CHAT_API_URL } from "./endpoints.js";
+import type { RoomTopicAttention } from "./shared/rooms-protocol.js";
 import type {
+  RoomBookmarkSaved,
+  RoomBookmarksResult,
   RoomDmConversation,
   RoomDmHistory,
   RoomDmSendResult,
@@ -19,18 +22,25 @@ import type {
   RoomFriend,
   RoomFriendRequests,
   RoomNotificationInboxResult,
+  RoomPollVotersResult,
   RoomPublicProfile,
   RoomRepliesReadResult,
   RoomRepliesResult,
+  RoomRestEvent,
   RoomSocialConfig,
   RoomSpaceRestorePlan,
   RoomSpaceRestoreReceipt,
   RoomSuggestion,
   RoomSuggestionRequest,
+  RoomUserBlock,
+  RoomUserBlocksResult,
 } from "./social-types.js";
 
 export type {
   RoomAttachment,
+  RoomBookmark,
+  RoomBookmarkSaved,
+  RoomBookmarksResult,
   RoomDmConversation,
   RoomDmHistory,
   RoomDmMessage,
@@ -51,11 +61,16 @@ export type {
   RoomNotificationInboxResult,
   RoomNotificationKind,
   RoomNotificationMessageData,
+  RoomNotifyQuietHours,
+  RoomPollOptionVoters,
+  RoomPollVotersResult,
   RoomPublicProfile,
   RoomRepliesReadResult,
   RoomRepliesResult,
   RoomReplyInboxItem,
+  RoomRestEvent,
   RoomSocialConfig,
+  RoomSpaceNotificationOverride,
   RoomSpaceRestoreAction,
   RoomSpaceRestoreActionKind,
   RoomSpaceRestorePlan,
@@ -65,6 +80,9 @@ export type {
   RoomSuggestionIntent,
   RoomSuggestionRequest,
   RoomSuggestionSource,
+  RoomsNotificationSettings,
+  RoomUserBlock,
+  RoomUserBlocksResult,
 } from "./social-types.js";
 
 /** Largest per-file size any tier accepts (plus tier). The server enforces
@@ -876,20 +894,54 @@ export interface RoomSpaceInvite {
   invitedBy?: string;
   role: "admin" | "member";
   createdAt?: string;
+  /** Expiry deadline (ISO date); null or absent means the invite stands
+   *  until accepted or declined. Additive (0.6.0 servers). */
+  expiresAt?: string | null;
 }
 
-/** Create (or refresh) a pending invitation. Membership needs their accept. */
+/** Create (or refresh) a pending invitation. Membership needs their accept.
+ *  `expiresAt` (ISO date, future, at most 30 days out) puts a deadline on
+ *  it; re-inviting without one clears any previous deadline. Fail-closed on
+ *  servers older than 0.6.0: they persist the invite but drop the deadline,
+ *  so a deadline the echo omits revokes the invite and throws. */
 export async function createSpaceInvite(
   config: RoomSocialConfig,
   spaceId: string,
-  input: { targetUserId?: string; targetUsername?: string; role?: "admin" | "member" },
+  input: {
+    targetUserId?: string;
+    targetUsername?: string;
+    role?: "admin" | "member";
+    expiresAt?: string;
+  },
 ): Promise<RoomSpaceInvite> {
   const result = await socialRequest<{ invite: RoomSpaceInvite }>(
     config,
     `/spaces/${encodeURIComponent(spaceId)}/invites`,
     { method: "POST", body: input },
   );
-  return result.invite;
+  const invite = result.invite;
+  // Presence check, not equality: servers may normalize the ISO string.
+  // declineSpaceInvite doubles as the manager-side revoke (the store
+  // deletes the row for invitee OR manager), so the inviter can retract
+  // the invite it just created.
+  if (input.expiresAt !== undefined && invite && typeof invite.expiresAt !== "string") {
+    const details = { spaceId, inviteId: invite.inviteId, requestedExpiresAt: input.expiresAt };
+    try {
+      await declineSpaceInvite(config, invite.inviteId);
+    } catch (revokeError) {
+      throw new RoomSocialError(
+        "Server does not support invite expiry, and revoking the invite failed: a standing (never-expiring) invite may be live",
+        502,
+        { ...details, revokeError: (revokeError as Error).message },
+      );
+    }
+    throw new RoomSocialError(
+      "Server does not support invite expiry; the standing invite was revoked",
+      502,
+      details,
+    );
+  }
+  return invite;
 }
 
 /** The caller's own pending invitations. */
@@ -929,14 +981,65 @@ export async function declineSpaceInvite(
   });
 }
 
-/** Mint (or rotate) the shareable join code; plaintext comes back once. */
+/** Mint (or rotate) the shareable join code; plaintext comes back once.
+ *  Optional caps: `expiresAt` (ISO date, future, at most 30 days out) and
+ *  `maxUses` (1..10000). Rotation is a fresh grant: the new code starts at
+ *  zero uses and takes exactly the caps given here (omitted caps clear the
+ *  previous ones). Servers older than 0.6.0 echo neither cap field; they
+ *  mint the code but drop the caps, so a requested cap the echo omits
+ *  fail-closes: the fresh code is revoked and the call throws rather than
+ *  hand back a live UNLIMITED code the caller believes capped. */
 export async function setSpaceJoinCode(
   config: RoomSocialConfig,
   spaceId: string,
-): Promise<{ spaceId: string; code: string }> {
-  return socialRequest(config, `/spaces/${encodeURIComponent(spaceId)}/join-code`, {
+  options: { expiresAt?: string | undefined; maxUses?: number | undefined } = {},
+): Promise<{
+  spaceId: string;
+  code: string;
+  expiresAt?: string | null;
+  maxUses?: number | null;
+}> {
+  const body: { expiresAt?: string; maxUses?: number } = {};
+  if (options.expiresAt !== undefined) body.expiresAt = options.expiresAt;
+  if (options.maxUses !== undefined) body.maxUses = options.maxUses;
+  const result = await socialRequest<{
+    spaceId: string;
+    code: string;
+    expiresAt?: string | null;
+    maxUses?: number | null;
+  }>(config, `/spaces/${encodeURIComponent(spaceId)}/join-code`, {
     method: "PUT",
+    // Capless mints keep the historical bodiless PUT on the wire.
+    ...(Object.keys(body).length > 0 ? { body } : {}),
   });
+  // Presence check for expiresAt (servers may normalize the ISO string),
+  // numeric equality for maxUses.
+  const droppedExpiry = body.expiresAt !== undefined && typeof result.expiresAt !== "string";
+  const droppedMaxUses = body.maxUses !== undefined && result.maxUses !== body.maxUses;
+  if (droppedExpiry || droppedMaxUses) {
+    // Details deliberately omit the plaintext code: RoomSocialError.details
+    // ends up in logs.
+    const details = {
+      spaceId,
+      requested: body,
+      echoed: { expiresAt: result.expiresAt ?? null, maxUses: result.maxUses ?? null },
+    };
+    try {
+      await clearSpaceJoinCode(config, spaceId);
+    } catch (revokeError) {
+      throw new RoomSocialError(
+        "Server does not support join-code caps, and revoking the code failed: an uncapped join code may be live",
+        502,
+        { ...details, revokeError: (revokeError as Error).message },
+      );
+    }
+    throw new RoomSocialError(
+      "Server does not support join-code caps; the uncapped code was revoked",
+      502,
+      details,
+    );
+  }
+  return result;
 }
 
 export async function clearSpaceJoinCode(
@@ -1325,6 +1428,464 @@ export async function listRoomNotifications(
   };
 }
 
+/**
+ * Mark a room unread from `seq` (Discord-style): the room-wide read cursor
+ * drops to seq - 1 (server-clamped at 0) so the unread divider and pill
+ * return. The one sanctioned cursor-regression path; mention rows an
+ * earlier ack swept stay swept, and nothing is re-notified.
+ */
+export async function markRoomUnread(
+  config: RoomSocialConfig,
+  room: string,
+  seq: number,
+): Promise<{ success: boolean }> {
+  const result = await socialRequest<{ success?: boolean }>(
+    config,
+    `/rooms/${encodeURIComponent(cleanRoomId(room))}/read/unread`,
+    { method: "POST", body: { seq } },
+  );
+  return { success: result.success === true };
+}
+
+/**
+ * Set the caller's room-level attention over REST, the path that carries
+ * mute-with-duration: `untilMs` (epoch ms, valid only with 'mute') stamps
+ * the expiry that read state later surfaces as `muteUntil`; the mute lapses
+ * server-side and reads as 'default' afterwards. Every write settles the
+ * expiry, so follow/default (and a plain permanent mute) clear a previous
+ * one. The pinned ROOM_SET_ATTENTION frame (setRoomAttentionOnClient)
+ * predates `untilMs` and stays the live-session path for permanent
+ * postures; servers older than mute-with-duration strip the field and land
+ * the mute permanent, so a requested `untilMs` the echo omits fail-closes:
+ * the attention is reset and the call throws rather than leave an
+ * unbounded mute the caller believes timed. Echoes the persisted
+ * attention; `muteUntil` is the ISO expiry, null when none stands.
+ */
+export async function setRoomAttentionRest(
+  config: RoomSocialConfig,
+  room: string,
+  attention: RoomTopicAttention,
+  options: { untilMs?: number | undefined } = {},
+): Promise<{ attention: RoomTopicAttention; muteUntil: string | null }> {
+  const body: { attention: RoomTopicAttention; untilMs?: number } = { attention };
+  if (options.untilMs !== undefined) body.untilMs = options.untilMs;
+  const result = await socialRequest<{
+    success?: boolean;
+    roomId?: string;
+    attention?: RoomTopicAttention;
+    muteUntil?: string;
+  }>(config, `/rooms/${encodeURIComponent(cleanRoomId(room))}/attention`, {
+    method: "POST",
+    body,
+  });
+  const muteUntil = typeof result.muteUntil === "string" ? result.muteUntil : null;
+  if (options.untilMs !== undefined && muteUntil === null) {
+    // The undo cannot know the caller's prior attention, so it deliberately
+    // lands 'default' (the same neutral a lapsed timed mute reads as, see
+    // resolveTopicAttention) rather than leave the unbounded mute standing.
+    try {
+      await setRoomAttentionRest(config, room, "default");
+    } catch (undoError) {
+      throw new RoomSocialError(
+        "Server does not support timed mutes, and undoing the mute failed: a permanent mute may be standing",
+        502,
+        { room, undoError: (undoError as Error).message },
+      );
+    }
+    throw new RoomSocialError(
+      "Server does not support timed mutes; the permanent mute was undone (attention is now 'default')",
+      502,
+      { room },
+    );
+  }
+  return { attention: result.attention ?? attention, muteUntil };
+}
+
+/**
+ * Save a message for later (personal, per-user; nothing broadcasts).
+ * Idempotent: re-saving an already bookmarked event echoes the standing
+ * row with its original createdAt.
+ */
+export async function addRoomBookmark(
+  config: RoomSocialConfig,
+  room: string,
+  seq: number,
+): Promise<RoomBookmarkSaved> {
+  const result = await socialRequest<{ success?: boolean; bookmark?: RoomBookmarkSaved }>(
+    config,
+    `/rooms/${encodeURIComponent(cleanRoomId(room))}/bookmarks`,
+    { method: "POST", body: { seq } },
+  );
+  if (!result.bookmark) {
+    throw new RoomSocialError("Bookmark save returned no row", 502, result);
+  }
+  return result.bookmark;
+}
+
+/** Remove a bookmark. Idempotent, and deliberately NOT gated on room
+ *  readability: cleanup keeps working after lost membership or a deleted
+ *  target (`removed` is false when no row stood). */
+/** Sequence numbers ride URL paths; a JavaScript caller can pass any value
+ *  despite the type annotation, and fetch normalizes dot segments, so a seq
+ *  of ".." would rewrite a bookmark DELETE onto the ROOM route (archive).
+ *  Runtime-require a nonnegative safe integer before interpolating. */
+function requireSeq(seq: number): number {
+  if (!Number.isSafeInteger(seq) || seq < 0) {
+    throw new RoomSocialError("Invalid sequence number", 400, { seq: String(seq) });
+  }
+  return seq;
+}
+
+export async function removeRoomBookmark(
+  config: RoomSocialConfig,
+  room: string,
+  seq: number,
+): Promise<{ removed: boolean }> {
+  const result = await socialRequest<{ success?: boolean; removed?: boolean }>(
+    config,
+    `/rooms/${encodeURIComponent(cleanRoomId(room))}/bookmarks/${requireSeq(seq)}`,
+    { method: "DELETE" },
+  );
+  return { removed: result.removed === true };
+}
+
+/**
+ * The caller's bookmarks across every room (GET /users/bookmarks), newest
+ * first with the notification inbox's composite cursor: pass a page's
+ * lastCursor and lastCursorId back TOGETHER for the next page. Rows in
+ * rooms the caller can no longer read are subtracted server-side.
+ */
+export async function listUserBookmarks(
+  config: RoomSocialConfig,
+  options: {
+    limit?: number | undefined;
+    /** Feed a page's lastCursor back here (explicit undefined reads as
+     *  "first page", so `page.lastCursor ?? undefined` composes under
+     *  exactOptionalPropertyTypes). */
+    cursor?: string | undefined;
+    cursorId?: string | undefined;
+    signal?: AbortSignal | undefined;
+  } = {},
+): Promise<RoomBookmarksResult> {
+  const params = new URLSearchParams();
+  if (options.limit !== undefined) params.set("limit", String(options.limit));
+  if (options.cursor !== undefined) params.set("cursor", options.cursor);
+  if (options.cursorId !== undefined) params.set("cursorId", options.cursorId);
+  const init: { signal?: AbortSignal } = {};
+  if (options.signal) init.signal = options.signal;
+  const result = await socialRequest<Partial<RoomBookmarksResult>>(
+    config,
+    `/users/bookmarks${params.size ? `?${params.toString()}` : ""}`,
+    init,
+  );
+  return {
+    bookmarks: result.bookmarks ?? [],
+    hasMore: result.hasMore ?? false,
+    lastCursor: result.lastCursor ?? null,
+    lastCursorId: result.lastCursorId ?? null,
+    total: result.total ?? 0,
+  };
+}
+
+/**
+ * The caller's user-block list (GET /users/blocks), newest first with the
+ * same composite-cursor paging as the notification inbox. Blocks are
+ * directional and the blocker is always the verified caller.
+ */
+export async function getUserBlocks(
+  config: RoomSocialConfig,
+  options: {
+    limit?: number | undefined;
+    cursor?: string | undefined;
+    cursorId?: string | undefined;
+    signal?: AbortSignal | undefined;
+  } = {},
+): Promise<RoomUserBlocksResult> {
+  const params = new URLSearchParams();
+  if (options.limit !== undefined) params.set("limit", String(options.limit));
+  if (options.cursor !== undefined) params.set("cursor", options.cursor);
+  if (options.cursorId !== undefined) params.set("cursorId", options.cursorId);
+  const init: { signal?: AbortSignal } = {};
+  if (options.signal) init.signal = options.signal;
+  const result = await socialRequest<Partial<RoomUserBlocksResult>>(
+    config,
+    `/users/blocks${params.size ? `?${params.toString()}` : ""}`,
+    init,
+  );
+  return {
+    blocks: result.blocks ?? [],
+    hasMore: result.hasMore ?? false,
+    lastCursor: result.lastCursor ?? null,
+    lastCursorId: result.lastCursorId ?? null,
+  };
+}
+
+/** Path-safety guard for block-target ids, NOT a format guard: the server
+ *  accepts any trimmed non-empty id up to 128 chars (legacy and agent
+ *  identities are not ObjectIds), so only the traversal class is refused
+ *  here: empty ids and pure dot segments, which encodeURIComponent leaves
+ *  alone and fetch would normalize onto /users/ itself. Everything else
+ *  rides percent-encoded. */
+function requireBlockUserId(userId: string): string {
+  const trimmed = String(userId).trim();
+  if (trimmed === "" || trimmed === "." || trimmed === ".." || trimmed.length > 128) {
+    throw new RoomSocialError("Invalid user id", 400, { userId: String(userId) });
+  }
+  return trimmed;
+}
+
+/** Block a user by userId (PUT, idempotent: re-blocking echoes the standing
+ *  row with its original createdAt). Server-enforced effects: DM doors shut
+ *  both directions, friend requests refuse, and the blocked sender produces
+ *  no notifications for the caller. Room visibility is unchanged. */
+export async function blockUser(config: RoomSocialConfig, userId: string): Promise<RoomUserBlock> {
+  const result = await socialRequest<{ success?: boolean; block?: RoomUserBlock }>(
+    config,
+    `/users/blocks/${encodeURIComponent(requireBlockUserId(userId))}`,
+    { method: "PUT" },
+  );
+  if (!result.block) {
+    throw new RoomSocialError("Block returned no row", 502, result);
+  }
+  return result.block;
+}
+
+/** Unblock a user (idempotent: unblocking a non-blocked user is a no-op). */
+export async function unblockUser(
+  config: RoomSocialConfig,
+  userId: string,
+): Promise<{ success: boolean }> {
+  const result = await socialRequest<{ success?: boolean }>(
+    config,
+    `/users/blocks/${encodeURIComponent(requireBlockUserId(userId))}`,
+    { method: "DELETE" },
+  );
+  return { success: result.success === true };
+}
+
+/**
+ * Post a poll message. There is no separate create route and no WS input
+ * path (the relay's post frame carries text only): a poll rides the normal
+ * REST append as the strict body's `poll` block. `options` are option TEXT
+ * (2..10 entries; ids are minted server-side) and `closesAt` is an ISO
+ * deadline that must sit in the future. `text` is the optional caption;
+ * absent is fine, the poll IS the content. Echoes the created store event
+ * row with its counts-only summary; the room hears the same message
+ * through the ordinary live echo. Additive (0.6.0 servers): older stores
+ * reject the unknown block.
+ */
+export async function createRoomPoll(
+  config: RoomSocialConfig,
+  room: string,
+  input: {
+    question: string;
+    options: string[];
+    multi?: boolean | undefined;
+    closesAt?: string | undefined;
+    text?: string | undefined;
+    /** Exact-case workspace id: lets a COLD relay replica materialize a
+     *  virtual workspace room without guessing the id's casing from the
+     *  lowercased room name (owners resolve server-side; non-owner first
+     *  writers need this). */
+    workspaceId?: string | undefined;
+    /** Route into a topic lane like any other append. */
+    topicId?: string | undefined;
+    /** Post the poll as a threaded reply. */
+    replyToSeq?: number | undefined;
+    /** Server-side idempotency: retries after an ambiguous failure reuse
+     *  the key instead of minting a duplicate poll. */
+    clientMsgId?: string | undefined;
+  },
+): Promise<RoomRestEvent> {
+  const poll: { question: string; options: string[]; multi?: boolean; closesAt?: string } = {
+    question: input.question,
+    options: input.options,
+  };
+  if (input.multi !== undefined) poll.multi = input.multi;
+  if (input.closesAt !== undefined) poll.closesAt = input.closesAt;
+  const body: {
+    roomId: string;
+    poll: typeof poll;
+    text?: string;
+    workspaceId?: string;
+    topicId?: string;
+    replyToSeq?: number;
+    clientMsgId?: string;
+  } = {
+    roomId: cleanRoomId(room),
+    poll,
+  };
+  if (input.text !== undefined) body.text = input.text;
+  if (input.workspaceId !== undefined) body.workspaceId = input.workspaceId;
+  if (input.topicId !== undefined) body.topicId = input.topicId;
+  if (input.replyToSeq !== undefined) body.replyToSeq = input.replyToSeq;
+  if (input.clientMsgId !== undefined) body.clientMsgId = input.clientMsgId;
+  const result = await socialRequest<{ success?: boolean; event?: RoomRestEvent }>(
+    config,
+    "/rooms/events",
+    { method: "POST", body },
+  );
+  if (!result.event) {
+    throw new RoomSocialError("Poll create returned no event", 502, result);
+  }
+  return result.event;
+}
+
+/**
+ * Vote on a poll (the poll is keyed by its carrying message's seq). Echoes
+ * the store's public event row (RoomRestEvent, not the relay's mapped
+ * ledger entry) with the refreshed counts-only summary; the room hears the
+ * same update over ENTRY_UPDATED. Single-choice polls replace the caller's
+ * previous ballot; multi-choice polls union into it.
+ */
+export async function voteRoomPoll(
+  config: RoomSocialConfig,
+  room: string,
+  seq: number,
+  optionIds: string[],
+): Promise<RoomRestEvent> {
+  const result = await socialRequest<{ success?: boolean; event?: RoomRestEvent }>(
+    config,
+    `/rooms/${encodeURIComponent(cleanRoomId(room))}/polls/${requireSeq(seq)}/vote`,
+    { method: "POST", body: { optionIds } },
+  );
+  if (!result.event) {
+    throw new RoomSocialError("Poll vote returned no event", 502, result);
+  }
+  return result.event;
+}
+
+/** Clear the caller's vote. Echoes the refreshed store event row. */
+export async function unvoteRoomPoll(
+  config: RoomSocialConfig,
+  room: string,
+  seq: number,
+): Promise<RoomRestEvent> {
+  const result = await socialRequest<{ success?: boolean; event?: RoomRestEvent }>(
+    config,
+    `/rooms/${encodeURIComponent(cleanRoomId(room))}/polls/${requireSeq(seq)}/vote`,
+    { method: "DELETE" },
+  );
+  if (!result.event) {
+    throw new RoomSocialError("Poll unvote returned no event", 502, result);
+  }
+  return result.event;
+}
+
+/** Close a poll (idempotent on an already-closed poll). Echoes the store
+ *  event row with `poll.closed` set. */
+export async function closeRoomPoll(
+  config: RoomSocialConfig,
+  room: string,
+  seq: number,
+): Promise<RoomRestEvent> {
+  const result = await socialRequest<{ success?: boolean; event?: RoomRestEvent }>(
+    config,
+    `/rooms/${encodeURIComponent(cleanRoomId(room))}/polls/${requireSeq(seq)}/close`,
+    { method: "POST" },
+  );
+  if (!result.event) {
+    throw new RoomSocialError("Poll close returned no event", 502, result);
+  }
+  return result.event;
+}
+
+/** Edit a poll's question/options (author-only, and locked once any vote
+ *  exists or the poll closes; at least one field required). Options are
+ *  full replacement TEXT, like creation. */
+/** Purge an event's frozen unfurl cards without editing or deleting the
+ *  message. Author or a delete-any moderation power; the store unsets the
+ *  cards, schedules thumbnail cleanup, and returns the mutated event for
+ *  ENTRY_UPDATED fan-out. An edit that removes a card's URL from the text
+ *  drops that card automatically; this route is the explicit purge for
+ *  everything else (a capability URL that must go without rewording the
+ *  message, a moderator acting on someone else's post). */
+export async function unsetRoomEventUnfurls(
+  config: RoomSocialConfig,
+  room: string,
+  seq: number,
+): Promise<void> {
+  await socialRequest(
+    config,
+    `/rooms/${encodeURIComponent(cleanRoomId(room))}/events/${requireSeq(seq)}/unfurls`,
+    { method: "DELETE" },
+  );
+}
+
+/** Edit an event's text over REST: the cold-replica-safe mirror of the WS
+ *  EDIT frame, and the ONE shape the WS path cannot express: an empty text
+ *  on a poll-bearing message legally clears the optional caption (the poll
+ *  stays the content; the store rejects empty edits on plain messages).
+ *  Viewers reconcile through the store's ENTRY_UPDATED fan-out exactly
+ *  like the REST poll verbs. */
+export async function editRoomEventRest(
+  config: RoomSocialConfig,
+  room: string,
+  seq: number,
+  text: string,
+): Promise<void> {
+  await socialRequest(
+    config,
+    `/rooms/${encodeURIComponent(cleanRoomId(room))}/events/${requireSeq(seq)}`,
+    { method: "PATCH", body: { text } },
+  );
+}
+
+export async function editRoomPoll(
+  config: RoomSocialConfig,
+  room: string,
+  seq: number,
+  patch: { question?: string | undefined; options?: string[] | undefined },
+): Promise<RoomRestEvent> {
+  const body: { question?: string; options?: string[] } = {};
+  if (patch.question !== undefined) body.question = patch.question;
+  if (patch.options !== undefined) body.options = patch.options;
+  const result = await socialRequest<{ success?: boolean; event?: RoomRestEvent }>(
+    config,
+    `/rooms/${encodeURIComponent(cleanRoomId(room))}/polls/${requireSeq(seq)}`,
+    { method: "PATCH", body },
+  );
+  if (!result.event) {
+    throw new RoomSocialError("Poll edit returned no event", 502, result);
+  }
+  return result.event;
+}
+
+/**
+ * Voter identities, on demand (the entry's summary carries counts only).
+ * Grouped per option; `optionId` narrows to one option and `limit` caps the
+ * identities per option (counts stay exact).
+ */
+export async function listRoomPollVoters(
+  config: RoomSocialConfig,
+  room: string,
+  seq: number,
+  options: {
+    optionId?: string | undefined;
+    limit?: number | undefined;
+    signal?: AbortSignal | undefined;
+  } = {},
+): Promise<RoomPollVotersResult> {
+  const params = new URLSearchParams();
+  if (options.optionId !== undefined) params.set("optionId", options.optionId);
+  if (options.limit !== undefined) params.set("limit", String(options.limit));
+  const init: { signal?: AbortSignal } = {};
+  if (options.signal) init.signal = options.signal;
+  const result = await socialRequest<Partial<RoomPollVotersResult>>(
+    config,
+    `/rooms/${encodeURIComponent(cleanRoomId(room))}/polls/${requireSeq(seq)}/voters${
+      params.size ? `?${params.toString()}` : ""
+    }`,
+    init,
+  );
+  return {
+    room: result.room ?? cleanRoomId(room),
+    seq: result.seq ?? seq,
+    voters: result.voters ?? [],
+    viewerOptionIds: result.viewerOptionIds ?? [],
+  };
+}
+
 export async function suggestRooms(
   config: RoomSocialConfig,
   request: RoomSuggestionRequest,