chattolib/proto/chatto/api/v1/rooms.proto

syntax = "proto3";

package chatto.api.v1;

import "buf/validate/validate.proto";
import "chatto/api/v1/attachments.proto";
import "chatto/api/v1/common.proto";
import "chatto/api/v1/member_directory.proto";
import "chatto/api/v1/pagination.proto";
import "chatto/api/v1/read_state.proto";
import "chatto/api/v1/room_timeline.proto";
import "chatto/api/v1/message_types.proto";
import "chatto/api/v1/users.proto";
import "google/protobuf/timestamp.proto";

// Kind of room represented by the public API.
enum RoomKind {
  // The room kind was not specified.
  ROOM_KIND_UNSPECIFIED = 0;
  // A regular channel governed by server and room permissions.
  ROOM_KIND_CHANNEL = 1;
  // A direct-message conversation between members.
  ROOM_KIND_DM = 2;
}

// Public room metadata returned by room commands.
message Room {
  // Stable room ID.
  string id = 1;
  // Room kind.
  RoomKind kind = 2;
  // Room name. Direct-message rooms may have an empty name because clients
  // derive their display label from participants.
  string name = 3;
  // Optional room description.
  string description = 4;
  // True when the room is archived and hidden from active room lists.
  bool archived = 5;
  // Room group ID for channel rooms. Empty for direct-message rooms.
  string group_id = 6;
  // True when a channel grants effective membership to eligible server members.
  bool universal = 7;
  // Minimum number of seconds a non-exempt member must wait between message
  // posts. Channel rooms only; zero means slow mode is disabled.
  uint32 slow_mode_seconds = 8;
  // Threading policy for this channel room. Direct-message rooms report
  // UNSPECIFIED because they do not support threads.
  RoomThreadingMode threading_mode = 9;
}

// Lightweight room reference for cross-resource rows.
message RoomSummary {
  // Stable room ID.
  string id = 1;
  // Room kind.
  RoomKind kind = 2;
  // Room name. Direct-message rooms may have an empty name because clients
  // derive their display label from participants.
  string name = 3;
}

// Request to create a channel room.
message CreateRoomRequest {
  // Required. Visible 1–30-code-point Unicode name of the new channel room.
  // The server trims and stores it in NFC form. Control characters and Unicode
  // line or paragraph separators are rejected.
  string name = 1 [(buf.validate.field).string = {
    min_len: 1
    max_len: 30
  }];
  // Optional room description.
  string description = 2 [(buf.validate.field).string.max_len = 500];
  // Required. Room group that should contain the new channel.
  string group_id = 3 [(buf.validate.field).string.min_len = 1];
  // Whether the new channel should grant effective membership to eligible
  // server members.
  bool universal = 4;
  // Threading policy for the new channel. UNSPECIFIED selects ENABLED.
  RoomThreadingMode threading_mode = 5;
}

// Result of creating a room.
message CreateRoomResponse {
  // Created room.
  Room room = 1;
}

// Request to update a room's editable metadata.
message UpdateRoomRequest {
  // Required. Room to update.
  string room_id = 1 [(buf.validate.field).string.min_len = 1];
  // New visible 1–30-code-point Unicode room name, when changing it. The server
  // trims and stores it in NFC form. Control characters and Unicode line or
  // paragraph separators are rejected.
  optional string name = 2 [(buf.validate.field).string = {
    min_len: 1
    max_len: 30
  }];
  // New room description, when changing it. Empty clears the description.
  optional string description = 3 [(buf.validate.field).string.max_len = 500];
  // New universal membership state, when changing it. Direct-message rooms
  // cannot be universal.
  optional bool universal = 4;
  // New per-user posting interval in seconds. Zero disables slow mode. The
  // maximum supported interval is six hours. Direct-message rooms cannot use
  // slow mode.
  optional uint32 slow_mode_seconds = 5 [(buf.validate.field).uint32.lte = 21600];
  // New threading policy. Direct-message rooms cannot set this field, and an
  // explicitly supplied UNSPECIFIED or unknown value is rejected.
  optional RoomThreadingMode threading_mode = 6;
}

// Result of updating a room.
message UpdateRoomResponse {
  // Updated room.
  Room room = 1;
}

// Request to archive a room.
message ArchiveRoomRequest {
  // Required. Room to archive.
  string room_id = 1 [(buf.validate.field).string.min_len = 1];
}

// Result of archiving a room.
message ArchiveRoomResponse {
  // Archived room.
  Room room = 1;
}

// Request to unarchive a room.
message UnarchiveRoomRequest {
  // Required. Room to unarchive.
  string room_id = 1 [(buf.validate.field).string.min_len = 1];
}

// Result of unarchiving a room.
message UnarchiveRoomResponse {
  // Unarchived room.
  Room room = 1;
}

// Request to join a room as the current user.
message JoinRoomRequest {
  // Required. Room to join.
  string room_id = 1 [(buf.validate.field).string.min_len = 1];
}

// Result of joining a room.
message JoinRoomResponse {
  // Joined room.
  Room room = 1;
}

// Request to join all joinable rooms in one room group.
message JoinRoomGroupRequest {
  // Required. Room group whose rooms should be joined.
  string group_id = 1 [(buf.validate.field).string.min_len = 1];
}

// Result of joining all joinable rooms in one room group.
message JoinRoomGroupResponse {
  // Room IDs that transitioned from not joined to joined.
  repeated string joined_room_ids = 1;
}

// Request to start a direct-message room for a human caller, or fetch an
// existing one. A human caller can fetch an existing DM without message.post.
// A valid request from a bot receives PERMISSION_DENIED, including when the
// room already exists.
message StartDMRequest {
  // Other participants to include in the direct-message room. The current user
  // is always included by the server. An empty list creates or fetches the
  // caller's self-DM.
  repeated string participant_ids = 1 [(buf.validate.field).repeated = {
    max_items: 9
    items: {
      string: {min_len: 1}
    }
  }];
}

// Result of starting or fetching a direct-message room.
message StartDMResponse {
  // Direct-message room for the participant set.
  Room room = 1;
}

// Request to leave a room as the current user.
message LeaveRoomRequest {
  // Required. Room to leave.
  string room_id = 1 [(buf.validate.field).string.min_len = 1];
}

// Result of leaving a room.
message LeaveRoomResponse {
  // True when the current user is no longer an explicit member after the call.
  bool left = 1;
}

// Request to add a user to a channel room.
message AddMemberRequest {
  // Required. Channel room to add the user to.
  string room_id = 1 [(buf.validate.field).string.min_len = 1];
  // Required. User to add as an explicit room member.
  string user_id = 2 [(buf.validate.field).string.min_len = 1];
}

// Result of adding a user to a room.
message AddMemberResponse {
  // Added room member.
  DirectoryMember member = 1;
}

// Request to remove a user from a channel room.
message RemoveMemberRequest {
  // Required. Channel room to remove the user from.
  string room_id = 1 [(buf.validate.field).string.min_len = 1];
  // Required. User to remove from the room's explicit members.
  string user_id = 2 [(buf.validate.field).string.min_len = 1];
}

// Result of removing a user from a room.
message RemoveMemberResponse {
  // True when an explicit room membership was removed by this call.
  bool removed = 1;
}

// Request to ban a member from a channel room.
message BanMemberRequest {
  // Required. Channel room to ban the user from.
  string room_id = 1 [(buf.validate.field).string.min_len = 1];
  // Required. User to ban from the room.
  string user_id = 2 [(buf.validate.field).string.min_len = 1];
  // Required moderator-entered reason stored for audit.
  string reason = 3 [(buf.validate.field).string = {
    min_len: 1
    max_len: 1000
  }];
  // Optional future time when the ban expires.
  google.protobuf.Timestamp expires_at = 4;
}

// Result of banning a room member.
message BanMemberResponse {
  // True when the ban operation completed.
  bool banned = 1;
}

// Request to remove a channel room ban.
message UnbanMemberRequest {
  // Required. Channel room to unban the user from.
  string room_id = 1 [(buf.validate.field).string.min_len = 1];
  // Required. User to unban.
  string user_id = 2 [(buf.validate.field).string.min_len = 1];
  // Required moderator-entered reason stored for audit.
  string reason = 3 [(buf.validate.field).string = {
    min_len: 1
    max_len: 1000
  }];
}

// Result of removing a room ban.
message UnbanMemberResponse {
  // True when the unban operation completed.
  bool unbanned = 1;
}

// Active channel room ban with optional hydrated room and user references.
message RoomBan {
  // Stable ban event ID.
  string id = 1;
  // Channel room ID.
  string room_id = 2;
  // Channel room metadata, when the referenced room still exists.
  Room room = 3;
  // Banned user ID.
  string user_id = 4;
  // Banned user profile, when the referenced user still exists.
  DirectoryMember user = 5;
  // Moderator user ID that created the ban.
  string moderator_id = 6;
  // Moderator profile, when the referenced user still exists.
  DirectoryMember moderator = 7;
  // Moderator-entered ban reason.
  string reason = 8;
  // Time the ban was created.
  google.protobuf.Timestamp created_at = 9;
  // Optional future time when the ban expires.
  google.protobuf.Timestamp expires_at = 10;
}

// Request to list active room bans.
message ListBansRequest {
  // Optional channel room filter. Empty lists active bans across all rooms.
  string room_id = 1;
  // Page request. Defaults are applied when absent or limit is zero.
  PageRequest page = 2;
}

// Active room bans visible to the current moderator.
message ListBansResponse {
  // Active bans, newest first.
  repeated RoomBan bans = 1;
  // Page metadata.
  PageInfo page = 2;
}

// Request for room-scoped attachment list pages.
message ListRoomAttachmentsRequest {
  reserved 2, 3;
  reserved "limit", "offset";

  // Required room ID.
  string room_id = 1 [(buf.validate.field).string.min_len = 1];
  // Thumbnail URL options. Defaults are applied when absent.
  ImageTransformOptions thumbnail = 4;
  // Page request. Defaults are applied when absent or limit is zero.
  PageRequest page = 5;
}

// Room-scoped attachment list response.
message ListRoomAttachmentsResponse {
  reserved 2, 3;
  reserved "total_count", "has_more";

  // Current attachments in newest message order.
  repeated RoomAttachmentListItem attachments = 1;
  // Page metadata.
  PageInfo page = 4;
}

// One current pinned message in a channel room.
message PinnedMessage {
  // Current renderable message. Retracted messages are omitted from pin lists.
  Message message = 1;
}

// Request to list a channel room's current pinned messages.
message ListPinnedMessagesRequest {
  // Required channel room ID.
  string room_id = 1 [(buf.validate.field).string.min_len = 1];
  // Page request. Defaults are applied when absent or limit is zero.
  PageRequest page = 2;
}

// Current pinned messages in one channel room.
message ListPinnedMessagesResponse {
  // Pinned messages in newest-pin-first order.
  repeated PinnedMessage pinned_messages = 1;
  // Page metadata.
  PageInfo page = 2;
  // Opaque marker for the latest pin fact observed for this room. The value
  // remains stable when pins are removed so clients can detect new pins
  // without comparing wall-clock timestamps. Clients must not interpret it.
  string latest_pin_marker = 3;
}

// Request to pin a message in a channel room.
message CreatePinnedMessageRequest {
  // Required channel room ID.
  string room_id = 1 [(buf.validate.field).string.min_len = 1];
  // Required canonical message event ID. Thread replies are supported.
  string message_event_id = 2 [(buf.validate.field).string.min_len = 1];
}

// Result of pinning a message.
message CreatePinnedMessageResponse {
  // Current pinned-message resource. Repeating an existing pin returns it.
  PinnedMessage pinned_message = 1;
}

// Request to unpin a message from a channel room.
message DeletePinnedMessageRequest {
  // Required channel room ID.
  string room_id = 1 [(buf.validate.field).string.min_len = 1];
  // Required canonical message event ID.
  string message_event_id = 2 [(buf.validate.field).string.min_len = 1];
}

// Result of unpinning a message.
message DeletePinnedMessageResponse {
  // True when the message is not pinned after this call.
  bool deleted = 1;
}

// Request to refresh the current user's live-only typing indicator.
message UpdateTypingIndicatorRequest {
  // Required. Room where the current user is typing.
  string room_id = 1 [(buf.validate.field).string.min_len = 1];
  // Event ID of the thread root when typing inside a thread.
  string thread_root_event_id = 2;
}

// Result of refreshing a typing indicator.
message UpdateTypingIndicatorResponse {
  // True when the typing indicator was accepted for publish.
  bool updated = 1;
}

// Manages room-scoped operations for the current user.
//
// RoomService owns operations whose authorization and state are primarily scoped
// to one room, including lifecycle, membership, moderation, room timeline reads,
// room read state, attachments, and live typing. Resource-specific services
// should still be preferred when an operation is not naturally room-scoped or
// when the resource needs an independent CRUD/batch surface.
service RoomService {
  // Creates a new channel room in a room group. The caller must be allowed to
  // create rooms in the target group.
  rpc CreateRoom(CreateRoomRequest) returns (CreateRoomResponse);
  // Updates a room's editable metadata. The caller must be allowed to manage
  // rooms. Direct-message rooms cannot be universal.
  rpc UpdateRoom(UpdateRoomRequest) returns (UpdateRoomResponse);
  // Archives a room so it is hidden from active room lists. The caller must be
  // allowed to manage rooms.
  rpc ArchiveRoom(ArchiveRoomRequest) returns (ArchiveRoomResponse);
  // Restores an archived room to active room lists. The caller must be allowed
  // to manage rooms.
  rpc UnarchiveRoom(UnarchiveRoomRequest) returns (UnarchiveRoomResponse);
  // Joins the room as the current user when room permissions allow it.
  rpc JoinRoom(JoinRoomRequest) returns (JoinRoomResponse);
  // Joins every unarchived room in a group that the current user can join.
  // Already-joined and non-joinable rooms are skipped.
  rpc JoinRoomGroup(JoinRoomGroupRequest) returns (JoinRoomGroupResponse);
  // Starts a direct-message room for the current human user and the requested
  // participant set, or fetches its existing DM. message.post is required
  // only when the DM must be created. A valid request from a bot receives
  // PERMISSION_DENIED and cannot use this RPC to fetch an existing DM.
  rpc StartDM(StartDMRequest) returns (StartDMResponse);
  // Leaves the room as the current user. Direct-message and universal rooms
  // cannot be left.
  rpc LeaveRoom(LeaveRoomRequest) returns (LeaveRoomResponse);
  // Lists effective room members. Existing members and room.manage holders may
  // list a channel room; other nonmembers need both room.list and room.join.
  rpc ListMembers(ListRoomMembersRequest) returns (ListRoomMembersResponse);
  // Gets one explicit member of a room. Existing members and room.manage
  // holders may read channel-room members; DMs remain membership-only. Returns
  // NOT_FOUND when the target is unknown or not a room member.
  rpc GetMember(GetRoomMemberRequest) returns (GetRoomMemberResponse);
  // Gets explicit room member rows for multiple users. Existing members and
  // room.manage holders may read channel-room members; DMs remain
  // membership-only.
  rpc BatchGetMembers(BatchGetRoomMembersRequest) returns (BatchGetRoomMembersResponse);
  // Adds a user as an explicit member of a channel room. The caller must be
  // allowed to manage the room. Direct-message and universal rooms cannot be
  // managed this way.
  rpc AddMember(AddMemberRequest) returns (AddMemberResponse);
  // Removes a user from a channel room's explicit members. The caller must be
  // allowed to manage the room. Direct-message and universal rooms cannot be
  // managed this way.
  rpc RemoveMember(RemoveMemberRequest) returns (RemoveMemberResponse);
  // Lists active channel room bans. The caller must be allowed to moderate room
  // membership bans.
  rpc ListBans(ListBansRequest) returns (ListBansResponse);
  // Lists current message-owned room attachments. Authentication and room
  // membership are required. Channel-room attachments also require message.read
  // or a matching thread relationship with message.read-interactions. DM
  // membership authorizes DM attachments. The server omits attachments from
  // inaccessible threads. Returns PERMISSION_DENIED when the room is
  // inaccessible to the caller.
  rpc ListRoomAttachments(ListRoomAttachmentsRequest) returns (ListRoomAttachmentsResponse);
  // Lists current pinned messages in a channel room. Room membership plus
  // message.read or message.read-interactions are required. The server omits
  // pins from threads that the caller cannot read. Direct-message rooms do not
  // support pins.
  rpc ListPinnedMessages(ListPinnedMessagesRequest) returns (ListPinnedMessagesResponse);
  // Pins a current message. The caller must have room.manage and must be able
  // to read the message. Repeating an existing pin is idempotent. Direct-message
  // rooms are rejected.
  rpc CreatePinnedMessage(CreatePinnedMessageRequest) returns (CreatePinnedMessageResponse);
  // Removes a current pin. The caller must have room.manage. Removing a
  // missing pin is idempotent. Direct-message rooms are rejected.
  rpc DeletePinnedMessage(DeletePinnedMessageRequest) returns (DeletePinnedMessageResponse);
  // Refreshes the current user's live-only typing indicator for a room or
  // thread. Room membership is required; message posting permission is not.
  rpc UpdateTypingIndicator(UpdateTypingIndicatorRequest) returns (UpdateTypingIndicatorResponse);
  // Returns one page of room timeline events, including related user data
  // needed to render the page. Room membership is required. Channel-room reads
  // also require message.read or message.read-interactions. The server returns
  // only related thread roots for an interaction-scoped caller. DM membership
  // authorizes DM reads.
  rpc GetRoomEvents(GetRoomEventsRequest) returns (GetRoomEventsResponse);
  // Returns a room timeline window centered around a specific event. Use this to
  // open a permalink, search result, or notification target in context. Returns
  // NOT_FOUND when the anchor event is missing or not visible in the room
  // timeline. Returns PERMISSION_DENIED when room membership or both read modes
  // are missing, or when the anchor is in an unrelated thread. DM membership
  // authorizes DM reads.
  rpc GetRoomEventsAround(GetRoomEventsAroundRequest) returns (GetRoomEventsAroundResponse);
  // Marks a room timeline as read through the supplied event. Room membership
  // is required. Channel-room reads also require message.read or
  // message.read-interactions. DM membership authorizes DM reads. If no event
  // is supplied, the server marks through the latest root event that the caller
  // can read. Clients
  // usually call this after the user has viewed the latest visible event in the
  // room.
  rpc MarkRoomAsRead(MarkRoomAsReadRequest) returns (MarkRoomAsReadResponse);
  // Bans a member from a channel room. Direct-message rooms cannot be moderated
  // this way, and the target must currently be a room member.
  rpc BanMember(BanMemberRequest) returns (BanMemberResponse);
  // Removes an active channel room ban. Calling this when no active ban exists
  // is allowed and still returns success.
  rpc UnbanMember(UnbanMemberRequest) returns (UnbanMemberResponse);
}