// M-Files Server gRPC API 26.11. Generated from the M-Files Server IDL; do not edit.
// Documentation: https://developer.m-files.com/APIs/gRPC-API/
syntax = "proto3";

package MFiles;

import "mfiles/api/annotations.proto";
import "mfiles/structs.proto";

option csharp_namespace = "MFiles.Grpc";
option go_package = "github.com/M-Files/mfiles-grpc-api/go/mfiles;mfiles";
option java_multiple_files = true;
option java_package = "com.mfiles.grpc";
option objc_class_prefix = "MF_";

// Stores conversations with Aino and their chat turns in the vault, per user.
//
// A per-user history store for chat-style features. A
// [Conversation](mfiles:MFiles.Conversation) has a title and a type; its
// [ChatTurn](mfiles:MFiles.ChatTurn)s hold the exchanged messages as text that the server stores
// without interpreting it. The vault does not run any agent here: the caller writes what it wants
// to keep.
//
// - **Create or rename a conversation**:
//   [AddOrUpdateConversation](mfiles:MFiles.IRPCConversationOperations.AddOrUpdateConversation).
// - **Add or change a chat turn**:
//   [AddOrUpdateChatTurn](mfiles:MFiles.IRPCConversationOperations.AddOrUpdateChatTurn).
// - **Read**: [GetConversations](mfiles:MFiles.IRPCConversationOperations.GetConversations),
//   [GetConversationById](mfiles:MFiles.IRPCConversationOperations.GetConversationById),
//   [GetChatTurns](mfiles:MFiles.IRPCConversationOperations.GetChatTurns).
// - **Delete** a conversation with its chat turns:
//   [DeleteConversationById](mfiles:MFiles.IRPCConversationOperations.DeleteConversationById).
//
// All methods need a vault session and no special vault rights. A conversation belongs to the user
// who created it; reading, renaming or deleting another user's conversation fails with "Access is
// denied.". Administrators get no exception.
//
// **Paging.** [GetConversations](mfiles:MFiles.IRPCConversationOperations.GetConversations) and
// [GetChatTurns](mfiles:MFiles.IRPCConversationOperations.GetChatTurns) return at most 100 items,
// newest first (descending `sort_key`). For the next page, send the smallest `sort_key` you
// received; the server returns the items whose `sort_key` is less than it. 0 starts from the
// newest. `more_results` is true while older items remain.
service IRPCConversationOperations {
	option (mfiles.api.service) = { book: "vault" level: LEVEL_STANDARD title: "Conversations" };

	// Gets one of the caller's conversations by ID.
	//
	// - A conversation of another user, or an ID that does not exist, fails with "Access is
	//   denied.". ID 0 fails with "The parameter is incorrect.".
	rpc GetConversationById( GetConversationByIdRequest ) returns ( GetConversationByIdResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets the caller's conversations, newest first, up to 100 per call.
	//
	// - Returns only the caller's own conversations. See the service overview for paging.
	rpc GetConversations( GetConversationsRequest ) returns ( GetConversationsResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Gets the chat turns of one of the caller's conversations, newest first, up to 100 per call.
	//
	// - The conversation must belong to the caller; otherwise the call fails with "Access is
	//   denied.". See the service overview for paging.
	rpc GetChatTurns( GetChatTurnsRequest ) returns ( GetChatTurnsResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Creates a conversation, or renames an existing one of the caller.
	//
	// - With `id` 0, or an ID that does not exist, the server creates a new conversation with a new
	//   ID and `sort_key`, owned by the caller. Read the new ID from the response.
	// - With the ID of an existing conversation of the caller, only `title` is changed and `modified`
	//   is updated; `type` cannot be changed. The conversation of another user fails with "Access is
	//   denied.".
	// - `user_id`, `sort_key`, `created` and `modified` in the request are ignored.
	rpc AddOrUpdateConversation( AddOrUpdateConversationRequest ) returns ( AddOrUpdateConversationResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Adds a chat turn to one of the caller's conversations, or replaces the content of an existing
	// chat turn.
	//
	// - `conv_id` must name an existing conversation; otherwise the call fails with "The parameter is
	//   incorrect.".
	// - With `id` 0, or an ID that does not exist, a new chat turn is added with a new ID and
	//   `sort_key`. With an existing ID, `chat_turn` replaces the stored content and `modified` is
	//   updated.
	// - The content is stored as given; the server does not parse it.
	rpc AddOrUpdateChatTurn( AddOrUpdateChatTurnRequest ) returns ( AddOrUpdateChatTurnResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}

	// Deletes one of the caller's conversations and all its chat turns.
	//
	// - A conversation of another user fails with "Access is denied."; an ID that does not exist
	//   fails with "The parameter is incorrect.".
	// - Deleted conversations are no longer returned. The server keeps an archived copy of them and
	//   of their chat turns.
	rpc DeleteConversationById( DeleteConversationByIdRequest ) returns ( DeleteConversationByIdResponse ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION };
	}
}

// The request of GetConversationById.
message GetConversationByIdRequest {

	// The ID of the conversation.
	uint32 id = 1;
}

// The response of GetConversationById.
message GetConversationByIdResponse {

	// The requested conversation of the caller.
	Conversation updated_conversation = 1;
}

// The request of GetConversations.
message GetConversationsRequest {

	// 0 for the first page; for the next page, the smallest `sort_key` of the previous page.
	uint32 sort_key = 1;
}

// The response of GetConversations.
message GetConversationsResponse {

	// Up to 100 conversations in descending `sort_key` order.
	repeated Conversation conversations = 1;

	// True if older conversations remain.
	bool more_results = 2;
}

// The request of GetChatTurns.
message GetChatTurnsRequest {

	// The ID of the conversation.
	uint32 conversation_id = 1;

	// 0 for the first page; for the next page, the smallest `sort_key` of the previous page.
	uint32 sort_key = 2;
}

// The response of GetChatTurns.
message GetChatTurnsResponse {

	// Up to 100 chat turns in descending `sort_key` order.
	repeated ChatTurn chat_turns = 1;

	// True if older chat turns remain.
	bool more_results = 2;
}

// The request of AddOrUpdateConversation.
message AddOrUpdateConversationRequest {

	// The conversation. Set `title` and, for a new one, `type`; set `id` to rename an existing one.
	Conversation conversation = 1;
}

// The response of AddOrUpdateConversation.
message AddOrUpdateConversationResponse {

	// The conversation as stored.
	Conversation updated_conversation = 1;
}

// The request of AddOrUpdateChatTurn.
message AddOrUpdateChatTurnRequest {

	// The chat turn. Set `conv_id` and `chat_turn` (the content); set `id` to replace an existing turn.
	ChatTurn chat_turn = 1;
}

// The response of AddOrUpdateChatTurn.
message AddOrUpdateChatTurnResponse {

	// The chat turn as stored, with its ID and `sort_key`.
	ChatTurn updated_chat_turn = 1;
}

// The request of DeleteConversationById.
message DeleteConversationByIdRequest {

	// The ID of the conversation.
	uint32 id = 1;
}

// The response of DeleteConversationById.
message DeleteConversationByIdResponse {
}