seabird.proto

syntax = "proto3";

package seabird;

import "common.proto";

option java_package = "io.coded.seabird.seabird";
option go_package = ".;pb";

// Note that the IDs exposed by the Backend, User, and Channel are opaque IDs
// which seabird-core will handle and route to the correct backend.

message Event {
  oneof inner {
    // Events sent by chat backends.
    common.MessageEvent message = 1;
    common.PrivateMessageEvent private_message = 2;
    common.MentionEvent mention = 3;
    common.CommandEvent command = 4;
    common.ActionEvent action = 5;
    common.PrivateActionEvent private_action = 6;

    // Events sent by plugins and other clients. Generally, these are only
    // needed for special cases.
    SendMessageEvent send_message = 7;
    SendPrivateMessageEvent send_private_message = 8;
    PerformActionEvent perform_action = 9;
    PerformPrivateActionEvent perform_private_action = 10;
  }

  map<string, string> tags = 11;
}

// Request and response objects

message StreamEventsRequest {
  // A registry of commands this plugin responds to. A plugin MUST register all
  // commands it responds to in order to receive those events. The
  // CommandMetadata's name MUST match the map key, or an error will be
  // returned.
  //
  // NOTE: help is a reserved command and cannot be registered by plugins.
  map<string, CommandMetadata> commands = 1;
}

// CommandMetadata groups together a command's name along with short in-line
// help and the full private help.
//
// An example for the "help" command might be a name of "help", a short_help of
// "<command>" and an long help of "With no arguments, lists all available
// commands. With an argument, display the long help for an item."
message CommandMetadata {
  string name = 1;
  string short_help = 2;
  string full_help = 3;
}

// Requests a plugin can make. Each Request has a corresponding Event which has
// a sender field added and the tags removed (because they are lifted up to the
// higher level Event message). These message types must be kept in sync.

// Perform an action in a given channel.
message PerformActionRequest {
  string channel_id = 1;
  string text = 2;
  common.Block root_block = 4;

  map<string, string> tags = 3;
}

message PerformActionResponse {
}

// PerformActionEvent will be emitted whenever a plugin or other client calls
// PerformAction. Note that this will be emitted every time PerformAction is
// called, not when it succeeds. The additional sender param refers to the
// client sending the message.
message PerformActionEvent {
  string sender = 1;

  string channel_id = 2;
  string text = 3;
  common.Block root_block = 4;
}

// Perform an action in a private message.
message PerformPrivateActionRequest {
  string user_id = 1;
  string text = 2;
  common.Block root_block = 4;

  map<string, string> tags = 3;
}

message PerformPrivateActionResponse {
}

// PerformPrivateActionEvent will be emitted whenever a plugin or other client
// calls PerformPrivateAction. Note that this will be emitted every time
// PerformPrivateAction is called, not when it succeeds. The additional sender
// param refers to the client sending the message.
message PerformPrivateActionEvent {
  string sender = 1;

  string user_id = 2;
  string text = 3;
  common.Block root_block = 4;
}

// Send a message to a given a channel.
message SendMessageRequest {
  string channel_id = 1;
  string text = 2;
  common.Block root_block = 4;

  map<string, string> tags = 3;
}

message SendMessageResponse {
}

// SendMessageEvent will be emitted whenever a plugin or other client calls
// SendMessage. Note that this will be emitted every time SendMessage is
// called, not when it succeeds. The additional sender param refers to the
// client sending the message.
message SendMessageEvent {
  string sender = 1;

  string channel_id = 2;
  string text = 3;
  common.Block root_block = 4;
}

// Send a private message to a given user.
message SendPrivateMessageRequest {
  string user_id = 1;
  string text = 2;
  common.Block root_block = 4;

  map<string, string> tags = 3;
}

message SendPrivateMessageResponse {
}

// SendPrivateMessageEvent will be emitted whenever a plugin or other client
// calls SendPrivateMessage. Note that this will be emitted every time
// SendPrivateMessage is called, not when it succeeds.The additional sender
// param refers to the client sending the message.
message SendPrivateMessageEvent {
  string sender = 1;

  string user_id = 2;
  string text = 3;
  common.Block root_block = 4;
}

// Request to join a channel.
message JoinChannelRequest {
  string backend_id = 1;

  // NOTE: this channel_name is the only place name is used for an identifier -
  // all other times channels will be referred to by ID.
  string channel_name = 2;

  map<string, string> tags = 3;
}

message JoinChannelResponse {
}

// Request to leave a channel.
message LeaveChannelRequest {
  string channel_id = 1;
  string exit_message = 2;

  map<string, string> tags = 3;
}

message LeaveChannelResponse {
}

// Request to list all connected backends.
message ListBackendsRequest {
}

message ListBackendsResponse {
  repeated common.Backend backends = 1;
}

// Get info about a specific connected backend.
message BackendInfoRequest {
  string backend_id = 1;
}

message BackendInfoResponse {
  common.Backend backend = 1;
  map<string, string> metadata = 2;
}

message ListChannelsRequest {
  string backend_id = 1;
}

message ListChannelsResponse {
  repeated common.Channel channels = 1;
}

message ChannelInfoRequest {
  string channel_id = 1;
}

message ChannelInfoResponse {
  common.Channel channel = 1;
}

message UpdateChannelInfoRequest {
  string channel_id = 1;
  string topic = 2;

  map<string, string> tags = 3;
}

message UpdateChannelInfoResponse {
}

// A request for metadata about the running core instance.
message CoreInfoRequest {
}

// Metadata about the running core instance.
message CoreInfoResponse {
  uint64 startup_timestamp = 1;
  uint64 current_timestamp = 2;
}

message CommandsRequest {
}

message CommandsResponse {
  map<string, CommandMetadata> commands = 1;
}

service Seabird {
  rpc StreamEvents(StreamEventsRequest) returns (stream Event);

  // Chat actions
  rpc PerformAction(PerformActionRequest) returns (PerformActionResponse);
  rpc PerformPrivateAction(PerformPrivateActionRequest) returns (PerformPrivateActionResponse);
  rpc SendMessage(SendMessageRequest) returns (SendMessageResponse);
  rpc SendPrivateMessage(SendPrivateMessageRequest) returns (SendPrivateMessageResponse);
  rpc JoinChannel(JoinChannelRequest) returns (JoinChannelResponse);
  rpc LeaveChannel(LeaveChannelRequest) returns (LeaveChannelResponse);
  rpc UpdateChannelInfo(UpdateChannelInfoRequest) returns (UpdateChannelInfoResponse);

  // Chat backend introspection
  rpc ListBackends(ListBackendsRequest) returns (ListBackendsResponse);
  rpc GetBackendInfo(BackendInfoRequest) returns (BackendInfoResponse);

  // Chat connection introspection
  rpc ListChannels(ListChannelsRequest) returns (ListChannelsResponse);
  rpc GetChannelInfo(ChannelInfoRequest) returns (ChannelInfoResponse);

  // Seabird introspection
  rpc GetCoreInfo(CoreInfoRequest) returns (CoreInfoResponse);
  rpc RegisteredCommands(CommandsRequest) returns (CommandsResponse);
}