proto/yoresee_doc/v1/yoresee_doc.proto

syntax = "proto3";

package yoresee_doc.v1;

option go_package = "github.com/XingfenD/yoresee_doc/pkg/gen/yoresee_doc/v1;yoreseedocpb";

message BaseResponse {
  int32 code = 1;
  string message = 2;
}

message HealthRequest {}

message HealthResponse {
  BaseResponse base = 1;
  string timestamp = 2;
  string status = 3;
  string version = 4;
}

message SystemInfoRequest {}

message SystemInfoResponse {
  BaseResponse base = 1;
  string system_name = 2;
  string system_register_mode = 3;
}

message UserGroupResponse {
  string external_id = 1;
  string name = 2;
  string description = 3;
  string creator_user_external_id = 4;
  int32 member_count = 5;
}

message OrgNodeResponse {
  string external_id = 1;
  string parent_external_id = 2;
  string name = 3;
  string path = 4;
  string description = 5;
  string creator_user_external_id = 6;
  int32 member_count = 7;
  repeated OrgNodeResponse children = 8;
}

message ListUserGroupsRequest {
  optional string keyword = 1;
  int32 page = 2;
  int32 page_size = 3;
}

message ListUserGroupsResponse {
  BaseResponse base = 1;
  repeated UserGroupResponse user_groups = 2;
  int64 total = 3;
}

message GetUserGroupRequest {
  string external_id = 1;
}

message GetUserGroupResponse {
  BaseResponse base = 1;
  UserGroupResponse user_group = 2;
}

message CreateUserGroupRequest {
  string name = 1;
  string description = 2;
  repeated string member_user_external_ids = 3;
}

message CreateUserGroupResponse {
  BaseResponse base = 1;
  string external_id = 2;
}

message UpdateUserGroupRequest {
  string external_id = 1;
  optional string name = 2;
  optional string description = 3;
  bool sync_members = 4;
  repeated string member_user_external_ids = 5;
}

message UpdateUserGroupResponse {
  BaseResponse base = 1;
}

message DeleteUserGroupRequest {
  string external_id = 1;
}

message DeleteUserGroupResponse {
  BaseResponse base = 1;
}

message ListUsersRequest {
  optional string keyword = 1;
  int32 page = 2;
  int32 page_size = 3;
}

message ListUsersResponse {
  BaseResponse base = 1;
  repeated UserResponse users = 2;
  int64 total = 3;
}

message ListUserGroupMembersRequest {
  string external_id = 1;
  optional string keyword = 2;
  int32 page = 3;
  int32 page_size = 4;
}

message ListUserGroupMembersResponse {
  BaseResponse base = 1;
  repeated UserResponse users = 2;
  int64 total = 3;
}

message ListOrgNodesRequest {
  string parent_external_id = 1;
  optional string keyword = 2;
  int32 page = 3;
  int32 page_size = 4;
  bool include_children = 5;
}

message ListOrgNodesResponse {
  BaseResponse base = 1;
  repeated OrgNodeResponse org_nodes = 2;
  int64 total = 3;
}

message GetOrgNodeRequest {
  string external_id = 1;
  bool include_children = 2;
}

message GetOrgNodeResponse {
  BaseResponse base = 1;
  OrgNodeResponse org_node = 2;
}

message CreateOrgNodeRequest {
  string name = 1;
  string description = 2;
  string parent_external_id = 3;
  repeated string member_user_external_ids = 4;
}

message CreateOrgNodeResponse {
  BaseResponse base = 1;
  string external_id = 2;
}

message UpdateOrgNodeRequest {
  string external_id = 1;
  optional string name = 2;
  optional string description = 3;
  bool sync_members = 4;
  repeated string member_user_external_ids = 5;
}

message UpdateOrgNodeResponse {
  BaseResponse base = 1;
}

message DeleteOrgNodeRequest {
  string external_id = 1;
}

message DeleteOrgNodeResponse {
  BaseResponse base = 1;
}

message MoveOrgNodeRequest {
  string external_id = 1;
  string new_parent_external_id = 2;
}

message MoveOrgNodeResponse {
  BaseResponse base = 1;
}

message ListOrgNodeMembersRequest {
  string external_id = 1;
  optional string keyword = 2;
  int32 page = 3;
  int32 page_size = 4;
}

message ListOrgNodeMembersResponse {
  BaseResponse base = 1;
  repeated UserResponse users = 2;
  int64 total = 3;
}

message SettingOption {
  string label = 1;
  string label_key = 2;
  string value = 3;
}

message SettingUI {
  string component = 1;
  repeated SettingOption options = 2;
  string placeholder = 3;
  string placeholder_key = 4;
}

message SettingItem {
  string key = 1;
  string label = 2;
  string label_key = 3;
  string description = 4;
  string description_key = 5;
  string type = 6;
  SettingUI ui = 7;
  string value = 8;
  string default_value = 9;
  bool required = 10;
  bool readonly = 11;
}

message SettingGroup {
  string key = 1;
  string title = 2;
  string title_key = 3;
  repeated SettingItem items = 4;
}

message GetSettingsRequest {
  string scene = 1;
}

message GetSettingsResponse {
  BaseResponse base = 1;
  repeated SettingGroup groups = 2;
}

message SettingUpdate {
  string key = 1;
  string value = 2;
}

message UpdateSettingsRequest {
  repeated SettingUpdate updates = 1;
}

message UpdateSettingsResponse {
  BaseResponse base = 1;
}

message UpdateUserRequest {
  string external_id = 1;
  optional string username = 2;
  optional string email = 3;
  optional string nickname = 4;
  optional int32 status = 5;
}

message UpdateUserResponse {
  BaseResponse base = 1;
}

message AuthLoginRequest {
  string email = 1;
  string password = 2;
}

message AuthLoginResponse {
  BaseResponse base = 1;
  string token = 2;
  UserResponse user = 3;
}

message AuthRegisterRequest {
  string username = 1;
  string password = 2;
  string email = 3;
  optional string invitation_code = 4;
}

message AuthRegisterResponse {
  BaseResponse base = 1;
}

message UpdateProfileRequest {
  optional string username = 1;
  optional string email = 2;
  optional string nickname = 3;
  optional string password = 4;
  optional string avatar = 5;
  optional bytes avatar_file = 6;
  optional string avatar_filename = 7;
  optional string avatar_content_type = 8;
}

message UpdateProfileResponse {
  BaseResponse base = 1;
  UserResponse user = 2;
}

message QuerySideBarDisplayRequest {
  // scene enum string: home | user_info | manage
  string scene = 1;
}

message QuerySideBarDisplayResponse {
  BaseResponse base = 1;
  // tab key enum strings defined by frontend and backend convention.
  repeated string display_tabs = 2;
}

message QueryTopNavDisplayRequest {}

message QueryTopNavDisplayResponse {
  BaseResponse base = 1;
  // menu key enum strings defined by frontend and backend convention.
  repeated string display_menus = 2;
}

enum DocumentType {
  DOCUMENT_TYPE_UNSPECIFIED = 0;
  DOCUMENT_TYPE_MARKDOWN = 1;
  DOCUMENT_TYPE_TABLE = 2;
  DOCUMENT_TYPE_MARKDOWN_SLIDE = 3;
  DOCUMENT_TYPE_YORESEE_RICH_TEXT = 4;
}

message DocumentResponse {
  string external_id = 1;
  string title = 2;
  DocumentType type = 3;
  string summary = 4;
  reserved 5;
  repeated string tags = 6;
  int32 view_count = 7;
  int32 edit_count = 8;
  string created_at = 9;
  string updated_at = 10;
  repeated DocumentResponse children = 11;
  bool has_children = 12;
  bool is_public = 13;
}

message GetDocumentContentRequest {
  string document_external_id = 1;
}

message GetDocumentContentResponse {
  BaseResponse base = 1;
  DocumentResponse document = 2;
  string content = 3;
}

message GetDocumentSettingsRequest {
  string document_external_id = 1;
}

message GetDocumentSettingsResponse {
  BaseResponse base = 1;
  optional bool is_public = 2;
}

message ListRecentDocumentsRequest {
  optional string start_time = 1;
  optional string end_time = 2;
  int32 page = 3;
  int32 page_size = 4;
}

message ListRecentDocumentsResponse {
  BaseResponse base = 1;
  repeated DocumentResponse documents = 2;
  int64 total = 3;
}

message RecordRecentDocumentRequest {
  string document_external_id = 1;
}

message RecordRecentDocumentResponse {
  BaseResponse base = 1;
}

message RecursiveOptions {
  bool include_children = 1;
  bool recursive = 2;
  int32 depth = 3;
}

message TimeRange {
  optional string start = 1;
  optional string end = 2;
}

message ListDocumentsRequest {
  optional string user_external_id = 1;
  optional string root_document_external_id = 2;
  optional string title_keyword = 3;
  optional string type = 4;
  reserved 5;
  repeated string tags = 6;
  optional TimeRange create_time_range = 7;
  optional TimeRange update_time_range = 8;
  optional string order_by = 9;
  optional bool order_desc = 10;
  int32 page = 11;
  int32 page_size = 12;
  optional RecursiveOptions options = 13;
  optional string knowledge_base_external_id = 14;
}

message ListDocumentsResponse {
  BaseResponse base = 1;
  repeated DocumentResponse documents = 2;
  int64 total_count = 3;
}

message GetOwnDocumentsRequest {
  int32 page = 1;
  int32 page_size = 2;
  bool directory_only = 3;
}

message GetOwnDocumentsResponse {
  BaseResponse base = 1;
  repeated DocumentResponse documents = 2;
  int64 total_count = 3;
}

enum CreateDocumentContainerType {
  CREATE_DOCUMENT_CONTAINER_TYPE_UNSPECIFIED = 0;
  CREATE_DOCUMENT_CONTAINER_TYPE_KNOWLEDGE_BASE = 1;
  CREATE_DOCUMENT_CONTAINER_TYPE_OWN = 2;
}

message CreateDocumentRequest {
  string title = 1;
  DocumentType type = 2;
  CreateDocumentContainerType container_type = 3;
  optional string knowledge_base_external_id = 4;
  optional string parent_external_id = 5;
  optional int64 template_id = 6;
  optional bool is_public = 7;
}

message CreateDocumentResponse {
  BaseResponse base = 1;
  string external_id = 2;
}

message KnowledgeBaseResponse {
  string external_id = 1;
  string name = 2;
  string description = 3;
  string cover = 4;
  bool is_public = 5;
  string created_at = 6;
  string updated_at = 7;
  string deleted_at = 8;
  string creator_user_external_id = 9;
  string creator_name = 10;
  int64 documents_count = 11;
}

message ListKnowledgeBasesRequest {
  bool only_mine = 1;
  optional string name_keyword = 2;
  optional bool is_public = 3;
  optional TimeRange create_time_range = 4;
  optional TimeRange update_time_range = 5;
  optional string order_by = 6;
  optional bool order_desc = 7;
  int32 page = 8;
  int32 page_size = 9;
}

message ListKnowledgeBasesResponse {
  BaseResponse base = 1;
  repeated KnowledgeBaseResponse knowledge_bases = 2;
  int64 total = 3;
}

message CreateKnowledgeBaseRequest {
  string name = 1;
  string description = 2;
  string cover = 3;
  bool is_public = 4;
}

message CreateKnowledgeBaseResponse {
  BaseResponse base = 1;
  string external_id = 2;
}

message GetKnowledgeBaseRequest {
  string knowledge_base_external_id = 1;
  bool record_recent_log = 2;
  int32 page = 3;
  int32 page_size = 4;
  bool directory_only = 5;
}

message GetKnowledgeBaseResponse {
  BaseResponse base = 1;
  KnowledgeBaseResponse knowledge_base = 2;
  repeated DocumentResponse documents = 3;
  int64 total_count = 4;
}

message UserResponse {
  string external_id = 1;
  string username = 2;
  string email = 3;
  string nickname = 4;
  string avatar = 5;
  int32 status = 6;
  string created_at = 7;
  string updated_at = 8;
  optional string invitation_code = 9;
}

message InvitationResponse {
  string code = 1;
  string created_by_external_id = 2;
  string created_by_name = 3;
  int64 used_cnt = 4;
  optional int64 max_used_cnt = 5;
  optional string expires_at = 6;
  string created_at = 7;
  bool disabled = 8;
  optional string note = 9;
}

message InvitationRecordResponse {
  string code = 1;
  string used_by = 2;
  optional string used_by_external_id = 3;
  string used_at = 4;
  string status = 5;
}

message ListInvitationsRequest {
  optional int64 max_used_cnt = 2;
  optional string expires_at_start = 3;
  optional string expires_at_end = 4;
  optional string created_at_start = 5;
  optional string created_at_end = 6;
  optional bool disabled = 7;
  optional string order_by = 8;
  optional bool order_desc = 9;
  int32 page = 10;
  int32 page_size = 11;
  optional bool only_mine = 12;
  optional string keyword = 13;
}

message ListInvitationsResponse {
  BaseResponse base = 1;
  repeated InvitationResponse invitations = 2;
  int64 total = 3;
}

message CreateInvitationRequest {
  optional int64 max_used_cnt = 1;
  optional string expires_at = 2;
  optional string note = 3;
}

message CreateInvitationResponse {
  BaseResponse base = 1;
  InvitationResponse invitation = 2;
}

message UpdateInvitationRequest {
  string code = 1;
  optional int64 max_used_cnt = 2;
  optional string expires_at = 3;
  optional bool disabled = 4;
  optional string note = 5;
}

message UpdateInvitationResponse {
  BaseResponse base = 1;
}

message DeleteInvitationRequest {
  string code = 1;
}

message DeleteInvitationResponse {
  BaseResponse base = 1;
}

message ListInvitationRecordsRequest {
  optional string code = 1;
  optional string status = 2;
  optional string used_at_start = 3;
  optional string used_at_end = 4;
  int32 page = 5;
  int32 page_size = 6;
  optional bool only_mine = 7;
  optional string keyword = 8;
}

message ListInvitationRecordsResponse {
  BaseResponse base = 1;
  repeated InvitationRecordResponse records = 2;
  int64 total = 3;
}

message Notification {
  string external_id = 1;
  string type = 2;
  string status = 3;
  string title = 4;
  string content = 5;
  string payload = 6;
  string created_at = 7;
}

message CreateNotificationRequest {
  repeated string receiver_external_ids = 1;
  string type = 2;
  string title = 3;
  string content = 4;
  string payload_json = 5;
}

message CreateNotificationResponse {
  BaseResponse base = 1;
}

message ListNotificationsRequest {
  int32 page = 1;
  int32 page_size = 2;
  optional string status = 3;
}

message ListNotificationsResponse {
  BaseResponse base = 1;
  repeated Notification notifications = 2;
  int64 total = 3;
}

message MarkNotificationsReadRequest {
  repeated string external_ids = 1;
}

message MarkNotificationsReadResponse {
  BaseResponse base = 1;
}

message MarkAllNotificationsReadRequest {}

message MarkAllNotificationsReadResponse {
  BaseResponse base = 1;
}

message UpdateDocumentRequest {
  string external_id = 1;
  optional string title = 2;
  optional string knowledge_base_external_id = 3;
  optional string parent_external_id = 4;
  optional string content = 5;
  optional CreateDocumentContainerType move_to_container = 6;
}

message DocumentComment {
  string external_id = 1;
  string document_external_id = 2;
  string parent_external_id = 3;
  string content = 4;
  string creator_user_external_id = 5;
  string creator_name = 6;
  string creator_avatar = 7;
  string created_at = 8;
  string anchor_id = 9;
  string quote = 10;
}

message CreateDocumentCommentRequest {
  string document_external_id = 1;
  string content = 2;
  optional string parent_external_id = 3;
  optional string anchor_id = 4;
  optional string quote = 5;
  repeated string mentioned_user_external_ids = 6;
}

message CreateDocumentCommentResponse {
  BaseResponse base = 1;
  DocumentComment comment = 2;
}

message ListDocumentCommentsRequest {
  string document_external_id = 1;
  int32 page = 2;
  int32 page_size = 3;
}

message ListDocumentCommentsResponse {
  BaseResponse base = 1;
  repeated DocumentComment comments = 2;
  int64 total = 3;
}

message DeleteDocumentCommentRequest {
  string external_id = 1;
}

message DeleteDocumentCommentResponse {
  BaseResponse base = 1;
}

message UpdateDocumentCommentRequest {
  string external_id = 1;
  string content = 2;
}

message UpdateDocumentCommentResponse {
  BaseResponse base = 1;
  DocumentComment comment = 2;
}

message UpdateDocumentResponse {
  BaseResponse base = 1;
}

message UpdateDocumentMetaRequest {
  string external_id = 1;
  optional string title = 2;
  optional string summary = 3;
  repeated string tags = 4;
  reserved 5, 6;
}

message UpdateDocumentMetaResponse {
  BaseResponse base = 1;
}

message UpdateDocumentSettingsRequest {
  string external_id = 1;
  optional bool is_public = 2;
}

message UpdateDocumentSettingsResponse {
  BaseResponse base = 1;
  optional bool is_public = 2;
}

message AttachmentResponse {
  string external_id = 1;
  string document_external_id = 2;
  string name = 3;
  int64 size = 4;
  string mime_type = 5;
  string path = 6;
  string url = 7;
  string created_at = 8;
  string updated_at = 9;
}

message UploadDocumentAttachmentRequest {
  string document_external_id = 1;
  bytes file_content = 2;
  string file_name = 3;
  optional string content_type = 4;
}

message UploadDocumentAttachmentResponse {
  BaseResponse base = 1;
  AttachmentResponse attachment = 2;
}

message ListDocumentAttachmentsRequest {
  string document_external_id = 1;
}

message ListDocumentAttachmentsResponse {
  BaseResponse base = 1;
  repeated AttachmentResponse attachments = 2;
}

message DeleteDocumentAttachmentRequest {
  string document_external_id = 1;
  string attachment_external_id = 2;
}

message DeleteDocumentAttachmentResponse {
  BaseResponse base = 1;
}

message DocumentVersionResponse {
  int32 version = 1;
  string title = 2;
  string content = 3;
  string change_summary = 4;
  string created_at = 5;
}

message ListDocumentVersionsRequest {
  string document_external_id = 1;
  int32 page = 2;
  int32 page_size = 3;
}

message ListDocumentVersionsResponse {
  BaseResponse base = 1;
  repeated DocumentVersionResponse versions = 2;
  int64 total = 3;
}

message GetDocumentVersionContentRequest {
  string document_external_id = 1;
  int32 version = 2;
}

message GetDocumentVersionContentResponse {
  BaseResponse base = 1;
  DocumentVersionResponse version = 2;
}

message GetDocumentYjsSnapshotRequest {
  string document_external_id = 1;
}

message GetDocumentYjsSnapshotResponse {
  BaseResponse base = 1;
  bytes state = 2;
}

message SaveDocumentYjsSnapshotRequest {
  string document_external_id = 1;
  bytes state = 2;
}

message SaveDocumentYjsSnapshotResponse {
  BaseResponse base = 1;
}

// listRecentKnowledgeBasesRequest requests the caller's recent knowledge bases.
// Note: This RPC does not accept any external user identifiers. The backend
// resolves the user from the authenticated context.
message ListRecentKnowledgeBasesRequest {
  // Optional inclusive start time (RFC3339). If omitted, no lower bound.
  optional string start_time = 1;
  // Optional inclusive end time (RFC3339). If omitted, no upper bound.
  optional string end_time = 2;
  // 1-based page index. Defaults to 1 when <= 0.
  int32 page = 3;
  // Page size. Defaults to 10 when <= 0, capped by server.
  int32 page_size = 4;
}

// listRecentKnowledgeBasesResponse contains the recent knowledge bases.
message ListRecentKnowledgeBasesResponse {
  BaseResponse base = 1;
  repeated KnowledgeBaseResponse knowledge_bases = 2;
  int64 total = 3;
}

enum CreateTemplateContainer {
  OWN_TEMPLATE = 0;
  KNOWLEDGEBASE_TEMPLATE = 1;
  PUBLIC_TEMPLATE = 2;
}

message CreateTemplateRequest {
  CreateTemplateContainer target_container = 1;
  string knowledge_base_id = 2;
  string template_content = 3;
  DocumentType type = 4;
}

message CreateTemplateResponse {
  BaseResponse base = 1;
}

message TemplateResponse {
  int64 id = 1;
  string name = 2;
  string description = 3;
  string content = 4;
  string scope = 5;
  string knowledge_base_external_id = 6;
  repeated string tags = 7;
  string created_at = 8;
  string updated_at = 9;
  DocumentType type = 10;
}

message ListTemplatesRequest {
  bool only_mine = 1;
  optional CreateTemplateContainer target_container = 2;
  optional string knowledge_base_id = 3;
  optional string name_keyword = 4;
  optional string order_by = 5;
  optional bool order_desc = 6;
  int32 page = 7;
  int32 page_size = 8;
  optional DocumentType type = 9;
}

message ListTemplatesResponse {
  BaseResponse base = 1;
  repeated TemplateResponse templates = 2;
  int64 total = 3;
}

message GetTemplateRequest {
  int64 template_id = 1;
  bool record_recent_log = 2;
}

message GetTemplateResponse {
  BaseResponse base = 1;
  TemplateResponse template = 2;
}

message UpdateTemplateSettingsRequest {
  int64 template_id = 1;
  optional string name = 2;
  optional string description = 3;
  optional bool is_public = 4;
}

message UpdateTemplateSettingsResponse {
  BaseResponse base = 1;
}

message DeleteDocumentRequest {
  string document_external_id = 1;
}

message DeleteDocumentResponse {
  BaseResponse base = 1;
}

message ListRecentTemplatesRequest {
  optional string start_time = 1;
  optional string end_time = 2;
  int32 page = 3;
  int32 page_size = 4;
}

message ListRecentTemplatesResponse {
  BaseResponse base = 1;
  repeated TemplateResponse templates = 2;
  int64 total = 3;
}

// authService provides authentication APIs.
service AuthService {
  // login authenticates a user and returns a token.
  rpc Login(AuthLoginRequest) returns (AuthLoginResponse);
  // register creates a new user account.
  rpc Register(AuthRegisterRequest) returns (AuthRegisterResponse);
  // update current user profile.
  rpc UpdateProfile(UpdateProfileRequest) returns (UpdateProfileResponse);
  // query side bar visible tabs for scene.
  rpc QuerySideBarDisplay(QuerySideBarDisplayRequest) returns (QuerySideBarDisplayResponse);
  // query top nav visible menus.
  rpc QueryTopNavDisplay(QueryTopNavDisplayRequest) returns (QueryTopNavDisplayResponse);
}

// documentService provides document APIs.
service DocumentService {
  // listDocuments lists documents with filters and pagination.
  rpc ListDocuments(ListDocumentsRequest) returns (ListDocumentsResponse);
  // getDocumentContent fetches a document with its content.
  rpc GetDocumentContent(GetDocumentContentRequest) returns (GetDocumentContentResponse);
  // getDocumentSettings fetches document metadata for settings page.
  rpc GetDocumentSettings(GetDocumentSettingsRequest) returns (GetDocumentSettingsResponse);
  // list recent documents for caller.
  rpc ListRecentDocuments(ListRecentDocumentsRequest) returns (ListRecentDocumentsResponse);
  // record recent document for caller.
  rpc RecordRecentDocument(RecordRecentDocumentRequest) returns (RecordRecentDocumentResponse);
  // getDocumentYjsSnapshot fetches yjs snapshot by document external id.
  rpc GetDocumentYjsSnapshot(GetDocumentYjsSnapshotRequest) returns (GetDocumentYjsSnapshotResponse);
  // saveDocumentYjsSnapshot saves yjs snapshot state.
  rpc SaveDocumentYjsSnapshot(SaveDocumentYjsSnapshotRequest) returns (SaveDocumentYjsSnapshotResponse);
  // getOwnDocuments lists documents owned by the caller.
  rpc GetOwnDocuments(GetOwnDocumentsRequest) returns (GetOwnDocumentsResponse);
  // createDocument creates a new document.
  rpc CreateDocument(CreateDocumentRequest) returns (CreateDocumentResponse);
  // updateDocument updates an existing document.
  rpc UpdateDocument(UpdateDocumentRequest) returns (UpdateDocumentResponse);
  // updateDocumentMeta updates document metadata without changing content.
  rpc UpdateDocumentMeta(UpdateDocumentMetaRequest) returns (UpdateDocumentMetaResponse);
  // updateDocumentSettings updates settings fields for document.
  rpc UpdateDocumentSettings(UpdateDocumentSettingsRequest) returns (UpdateDocumentSettingsResponse);
  // upload attachment and bind to document.
  rpc UploadDocumentAttachment(UploadDocumentAttachmentRequest) returns (UploadDocumentAttachmentResponse);
  // list attachments by document.
  rpc ListDocumentAttachments(ListDocumentAttachmentsRequest) returns (ListDocumentAttachmentsResponse);
  // delete an attachment from document.
  rpc DeleteDocumentAttachment(DeleteDocumentAttachmentRequest) returns (DeleteDocumentAttachmentResponse);
  // list document history versions.
  rpc ListDocumentVersions(ListDocumentVersionsRequest) returns (ListDocumentVersionsResponse);
  // get document history version content.
  rpc GetDocumentVersionContent(GetDocumentVersionContentRequest) returns (GetDocumentVersionContentResponse);
  // save document as template
  rpc CreateTemplate(CreateTemplateRequest) returns (CreateTemplateResponse);
  // list templates with filters and pagination.
  rpc ListTemplates(ListTemplatesRequest) returns (ListTemplatesResponse);
  // list recent templates for caller.
  rpc ListRecentTemplates(ListRecentTemplatesRequest) returns (ListRecentTemplatesResponse);
  // get template by id.
  rpc GetTemplate(GetTemplateRequest) returns (GetTemplateResponse);
  // update template settings.
  rpc UpdateTemplateSettings(UpdateTemplateSettingsRequest) returns (UpdateTemplateSettingsResponse);
  // delete a document.
  rpc DeleteDocument(DeleteDocumentRequest) returns (DeleteDocumentResponse);
}

// commentService provides document comment APIs.
service CommentService {
  // create a comment for document.
  rpc CreateDocumentComment(CreateDocumentCommentRequest) returns (CreateDocumentCommentResponse);
  // list comments for document.
  rpc ListDocumentComments(ListDocumentCommentsRequest) returns (ListDocumentCommentsResponse);
  // delete a comment.
  rpc DeleteDocumentComment(DeleteDocumentCommentRequest) returns (DeleteDocumentCommentResponse);
  // update a comment.
  rpc UpdateDocumentComment(UpdateDocumentCommentRequest) returns (UpdateDocumentCommentResponse);
}

// knowledgeBaseService provides knowledge base management and discovery APIs.
service KnowledgeBaseService {
  // list knowledge bases with filters and pagination.
  rpc ListKnowledgeBases(ListKnowledgeBasesRequest) returns (ListKnowledgeBasesResponse);
  // get a knowledge base by external ID, optionally recording a recent-access log.
  rpc GetKnowledgeBase(GetKnowledgeBaseRequest) returns (GetKnowledgeBaseResponse);
  // create a knowledge base for the caller.
  rpc CreateKnowledgeBase(CreateKnowledgeBaseRequest) returns (CreateKnowledgeBaseResponse);
  // list the caller's recent knowledge bases. User identity is derived from auth context.
  rpc ListRecentKnowledgeBases(ListRecentKnowledgeBasesRequest) returns (ListRecentKnowledgeBasesResponse);
}

// systemService provides system health and info APIs.
service SystemService {
  // health returns service health status.
  rpc Health(HealthRequest) returns (HealthResponse);
  // systemInfo returns system info and config.
  rpc SystemInfo(SystemInfoRequest) returns (SystemInfoResponse);
}

// settingService provides settings schema and update APIs.
service SettingService {
  // get settings schema with current values.
  rpc GetSettings(GetSettingsRequest) returns (GetSettingsResponse);
  // update settings values.
  rpc UpdateSettings(UpdateSettingsRequest) returns (UpdateSettingsResponse);
}

// membershipService provides user group and org structure management APIs.
service MembershipService {
  // list user groups with pagination.
  rpc ListUserGroups(ListUserGroupsRequest) returns (ListUserGroupsResponse);
  // get a user group by external id.
  rpc GetUserGroup(GetUserGroupRequest) returns (GetUserGroupResponse);
  // create user group and optional members.
  rpc CreateUserGroup(CreateUserGroupRequest) returns (CreateUserGroupResponse);
  // update user group metadata and optional member set.
  rpc UpdateUserGroup(UpdateUserGroupRequest) returns (UpdateUserGroupResponse);
  // delete a user group and its memberships.
  rpc DeleteUserGroup(DeleteUserGroupRequest) returns (DeleteUserGroupResponse);
  // list users for member management.
  rpc ListUsers(ListUsersRequest) returns (ListUsersResponse);
  // update user info or status.
  rpc UpdateUser(UpdateUserRequest) returns (UpdateUserResponse);
  // list user group members with pagination.
  rpc ListUserGroupMembers(ListUserGroupMembersRequest) returns (ListUserGroupMembersResponse);
  // list org nodes with pagination.
  rpc ListOrgNodes(ListOrgNodesRequest) returns (ListOrgNodesResponse);
  // get an org node by external id.
  rpc GetOrgNode(GetOrgNodeRequest) returns (GetOrgNodeResponse);
  // create org node and optional members.
  rpc CreateOrgNode(CreateOrgNodeRequest) returns (CreateOrgNodeResponse);
  // update org node metadata and optional member set.
  rpc UpdateOrgNode(UpdateOrgNodeRequest) returns (UpdateOrgNodeResponse);
  // delete an org node and its memberships.
  rpc DeleteOrgNode(DeleteOrgNodeRequest) returns (DeleteOrgNodeResponse);
  // move an org node to a new parent.
  rpc MoveOrgNode(MoveOrgNodeRequest) returns (MoveOrgNodeResponse);
  // list org node members with pagination.
  rpc ListOrgNodeMembers(ListOrgNodeMembersRequest) returns (ListOrgNodeMembersResponse);
}

// invitationService provides invitation management APIs.
service InvitationService {
  // create invitation code.
  rpc CreateInvitation(CreateInvitationRequest) returns (CreateInvitationResponse);
  // list invitations with filters and pagination.
  rpc ListInvitations(ListInvitationsRequest) returns (ListInvitationsResponse);
  // update invitation code.
  rpc UpdateInvitation(UpdateInvitationRequest) returns (UpdateInvitationResponse);
  // delete invitation code.
  rpc DeleteInvitation(DeleteInvitationRequest) returns (DeleteInvitationResponse);
  // list invitation usage records.
  rpc ListInvitationRecords(ListInvitationRecordsRequest) returns (ListInvitationRecordsResponse);
}

// notificationService provides notification APIs.
service NotificationService {
  // create notifications (single or batch).
  rpc CreateNotification(CreateNotificationRequest) returns (CreateNotificationResponse);
  // list notifications for current user.
  rpc ListNotifications(ListNotificationsRequest) returns (ListNotificationsResponse);
  // mark notifications as read.
  rpc MarkNotificationsRead(MarkNotificationsReadRequest) returns (MarkNotificationsReadResponse);
  // mark all notifications as read.
  rpc MarkAllNotificationsRead(MarkAllNotificationsReadRequest) returns (MarkAllNotificationsReadResponse);
}