syntax = "proto3";

package ttab.newswire;

option go_package = "./rpc/newswire";

// Entity service for looking up named entities.
service Entity {
  // Autocomplete is a method that can be used to provide autocomplete
  // suggestions in a UI.
  rpc Autocomplete(AutocompleteRequest) returns (AutocompleteResponse);
}

enum EntityType {
  ENTITY_UNSPECIFIED  = 0;
  ENTITY_PERSON       = 1;
  ENTITY_ORGANISATION = 2;
  ENTITY_PLACE        = 3;
  ENTITY_TOPIC        = 4;
  ENTITY_STORY        = 5;
}

message AutocompleteRequest {
  // Type of entities to match against.
  EntityType type = 1;
  // Text to seach for.
  string text     = 2;
}

message AutocompleteResponse {
  // Items that matched the text.
  repeated AutocompleteEntity items = 1;
}

message AutocompleteEntity {
  // Code that uniquely identifies the entity.
  string code                   = 1;
  // Name of the entity.
  string name                   = 2;
  // Coordinates of the entity (if any) in WGS84/GPS projection.
  EntityCoordinates coordinates = 3;  
}

message EntityCoordinates {
  // Lat is the latitude.
  double lat = 1;
  // Lng is the longitude.
  double lng = 2;
}

service Delivery {
  // ListDestinations lists the destinations for your organisation. This is a
  // paginated method.
  rpc ListDestinations(ListDestinationsRequest) returns (ListDestinationsResponse);
  // SetDestination creates or updates a destination.
  rpc SetDestination(SetDestinationRequest) returns (SetDestinationResponse);
  // GetDestination returns details about a destination, this never includes any
  // sensitive credentials.
  rpc GetDestination(GetDestinationRequest) returns (GetDestinationResponse);
  rpc DeleteDestination(DeleteDestinationRequest) returns (DeleteDestinationResponse);
  // ListDestinationDeploys lists the deploys of a destination.
  rpc ListDestinationDeploys(ListDestinationDeploysRequest) returns (ListDestinationDeploysResponse);
  // ListRules lists the rulesets for a given destination.
  rpc ListRules(ListRulesRequest) returns (ListRulesResponse);
  // SetRules creates or updates a named ruleset for a destination.
  rpc SetRules(SetRulesRequest) returns (SetRulesResponse);
  // GetRules returns a named ruleset for a destination.
  rpc GetRules(GetRulesRequest) returns (GetRulesResponse);
  rpc DeployRules(DeployRulesRequest) returns (DeployRulesResponse);
  // DeleteRules permanently deletes a ruleset.
  rpc DeleteRules(DeleteRulesRequest) returns (DeleteRulesResponse);
  // TestRules is used by TT Studio to perform a test run of a ruleset.
  rpc TestRules(TestRulesRequest) returns (TestRulesResponse);
  // GetEvent is used to get detailed information about an event, it's used for
  // debugging or interactive applications.
  rpc GetEvent(GetEventRequest) returns (GetEventResponse);
  // GetDeliveries is used to fetch deliveries to the destination. Returned
  // items are in ascending ID order, starting from the first item for the
  // destination if no cursor is provided. This method can be used regardless of
  // the destination type.
  rpc GetDeliveries(GetDeliveriesRequest) returns (GetDeliveriesResponse);
  // GetPreviousDeliveries is used to access individual deliveries, for example
  // for use in a retry mechanism.
  rpc GetPreviousDeliveries(GetPreviousDeliveriesRequest) returns (GetPreviousDeliveriesResponse);
}

message GetPreviousDeliveriesRequest {
  // Destination to get deliveries for.
  string destination      = 1;
  // Cursors of the deliveries to get. Use the document-specific cursors from
  // previous calls to GetDeliveries. At most 100 cursors can be provided.
  repeated string cursors = 2;
  // BodyFormat can be used to specify the desired body format. Will default to
  // "BODY_FORMAT_RICH_HTML5" if omitted.
  BodyFormat body_format  = 3;
}

message GetPreviousDeliveriesResponse {
  // Items included in this batch of delivery items.
  repeated DeliveryItem items = 1;
}

message DeleteDestinationRequest {
    string destination = 1;
}

message DeleteDestinationResponse {}

message ListDestinationDeploysRequest {
  string destination = 1;
  int64 cursor       = 2;
}

message ListDestinationDeploysResponse {
  repeated DestinationDeploy deploys = 1;
  int64 next_page                    = 2;
}

message DestinationDeploy {
  // Version of the destination that was deployed.
  int64 version            = 1;
  // Rules is a set of the names and versions of the deployed rulesets.
  map<string, int64> rules = 2;
  // Reason for the deploy, one of "config_update" or "rule_update".
  string reason            = 3;
  // Created timestamp as an RFC3339 string.
  string created           = 4;
  // CreatedBy is the URI of the subject that caused the deploy.
  string created_by        = 5;
  // CreatorName is the human readable name of the subject, not guaranteed to be
  // present, and must not be treated as an identifier.
  string creator_name      = 6;
}

message ListDestinationsRequest {
  // Cursor is the pagination cursor.
  int64 cursor = 1;
}

message ListDestinationsResponse {
  // Destinations included in the page.
  repeated DestinationListItem destinations = 1;
  // NextPage is the cursor that should be used to get the next page, if any.
  int64 next_page                           = 2;
}

message DestinationListItem {
  // Name that identifies the destination.
  string name          = 1;
  // Title that describes the destination.
  string title         = 2;
  // Type of the destination.
  DestinationType type = 3;
  // Enabled - whether the destination is active or paused.
  bool enabled         = 4;
  // Created timestamp as an RFC3339 string.
  string created       = 5;
  // Updated timestamp as an RFC3339 string.
  string updated       = 6;
}

enum BodyFormat {
  BODY_FORMAT_UNSPECIFIED = 0;
  BODY_FORMAT_ALL         = 1;
  BODY_FORMAT_TEXT        = 2;
  BODY_FORMAT_HTML5       = 3;
  BODY_FORMAT_RICH_HTML5  = 4;
}

message GetDeliveriesRequest {
  // Destination to get deliveries for.
  string destination     = 1;
  // Cursor used to paginate through deliveries.
  string cursor          = 2;
  // MaxWaitSec can be specified to activate long-poll behaviour when tailing
  // the end of the deliveries.
  int64 max_wait_sec     = 3;
  // BodyFormat can be used to specify the desired body format. Will default to
  // "BODY_FORMAT_RICH_HTML5" if omitted.
  BodyFormat body_format = 4;
}

message GetDeliveriesResponse {
  // Next is the cursor to use for the next request to GetDeliveries.
  string next                 = 1;
  // Items included in this batch of delivery items.
  repeated DeliveryItem items = 2;
}

message DeliveryItem {
  // Cursor to use to start a GetDeliveries request at this position.
  string cursor                   = 1;
  // Doc is the TTNINJS document as a JSON string.
  string doc                      = 2;
  // Annotations for this item. Annotations are not part of the original
  // document, but applied by delivery rules for the destination.
  DeliveryAnnotations annotations = 3;
  // Type is the delivery type of the document.
  ContentType type                = 4;
}

message DeliveryAnnotations {
  // DeliveryTags for an item.
  repeated string delivery_tags = 1;
}

enum DestinationType {
  DESTINATION_UNSPECIFIED = 0;
  DESTINATION_API         = 1;
  DESTINATION_SFTP        = 2;
  DESTINATION_S3          = 3;
}

enum DestinationFormat {
  FORMAT_UNSPECIFIED = 0;
  FORMAT_TTNINJS     = 1;
  FORMAT_NEWSML      = 2;
}

enum ContentType {
  reserved 3;

  CONTENT_UNSPECIFIED    = 0;
  CONTENT_NEWS           = 1;
  CONTENT_EDITORIAL_INFO = 2;
  CONTENT_PRESS_RELEASES = 4;
  // TODO: Planning
  // TODO: Calendar
}

message GetEventRequest {
  // ID is the ID of an event to get.
  int64 id = 1;
}

message GetEventResponse {
  // URI of the document that this event represents.
  string uri       = 1;
  // Type of the content.
  ContentType type = 2;
  // Added timestamp (the time newswire got the event) as an RFC3339 string.
  string added     = 3;
  // Document payload for the event.
  string document  = 4;
}

message ListRulesRequest {
  // Name of the destination to list rules for.
  string name = 1;
}

message ListRulesResponse {
  // Items included in the ruleset listing.
  repeated ListRulesItem items = 1;
}

message ListRulesItem {
  // Name of the ruleset.
  string name            = 1;
  // Version of the ruleset.
  int64 version          = 2;
  // Created is the time that this version of the ruleset was created.
  string created         = 3;
  // DeployedVersion is the version number of the currently deployed version.
  int64 deployed_version = 4;
}

message DestinationSpecification {
  // Sftp is the specification to use for SFTP destinations.
  SftpSpec sftp = 1;
  // S3 is the specification to use for S3 destinations.
  S3Spec s3     = 2;
}

message S3Spec {
  // Endpoint (host) to use with the S3 client. Usually if the format
  // "s3.[region].amazonaws.com", should match the region of the S3 bucket when
  // using AWS.
  string endpoint           = 1;
  // Bucket to put the item in.
  string bucket             = 2;
  // Prefix to use when storing items in the bucket.
  string prefix             = 3;
  // Insecure is set to true to use http instead of https when communicating
  // with the S3 API. Should only be used for testing purposes.
  bool insecure             = 4;
  // Credentials to use with S3. Omit if you don't want to update the
  // credentials for the destination. Will not be returned when fetching
  // destination details.
  S3Credentials credentials = 5;
}

message S3Credentials {
  // ID is the access key id.
  string id     = 1;
  // Secret is the access key secret.
  string secret = 2;
}

message SftpSpec {
  // User to connect as.
  string user                 = 1;
  // Host of the server to connect to.
  string host                 = 2;
  // Path to the diectory to upload deliveries to.
  string path                 = 3;
  // HostKey in SSH format: `ecdsa-sha2-nistp256 AAAAE2Vj...IHfsd/jD11tEvr8 =`.
  // Optional, will be validated against (or default to) the public key supplied
  // by the server.
  string host_key             = 4;
  // IdleTimeoutSec is the time to allow a connection to the server to stay idle
  // before closing it. Defaults to two minutes.
  int32 idle_timout_sec       = 5;
  // PublicKey is the public key of the keypair used to connect to the
  // server. Generated automatically from private key, if any, and doesn't need
  // to be provided when updating the destination.
  string public_key           = 6;
  // Credentials to use when connecting to the server. Omit if you don't want to
  // update the credentials for the destination. Will not be returned when
  // fetching destination details.
  SshCredentials credentials  = 7;
  // StrictHostValidation will halt delivery if the host key on file doesn't
  // match the one returned by the server.
  bool strict_host_validation = 8;
}

enum KeyType {
  KEY_NONE    = 0;
  KEY_RSA     = 1;
  KEY_ED25519 = 2;
}

message SshCredentials {
  // Password to use when connecting to the server.
  string password    = 1;
  // PrivateKey to use when connecting to the server. Must be PEM encoded,
  // supports RSA, DSA, ECDSA, and Ed25519 private keys in PKCS#1, PKCS#8,
  // OpenSSL, and OpenSSH formats.
  string private_key = 2;
  // Generate a key of the given key type. Generated RSA keys will be 4096 bits.
  KeyType generate   = 3;
}

message SetDestinationRequest {
  // Name identifying the destination.
  string name                   = 1;
  // Type of the destination.
  DestinationType type          = 2;
  // Title describing the destination.
  string title                  = 3;
  // Enabled - whether the destination should be active or paused.
  bool enabled                  = 4;
  // Format is the delivery format that should be used for the destination. For
  // now only FORMAT_TTNINJS is supported.
  DestinationFormat format      = 5;
  // Spec for the destination - used to set configure the destination.
  DestinationSpecification spec = 6;
}

message SetDestinationResponse {
  // PublicKey of the keypair that will be used to connect to the server.
  string public_key = 1;
}

message GetDestinationRequest {
  // Name of the destination to get.
  string name = 1;
}

message GetDestinationResponse {
  // Name identifying the destination.
  string name                   = 1;
  // Type of the destination.
  DestinationType type          = 2;
  // Enabled - whether the destination is active or paused.
  bool enabled                  = 3;
  // Spec for the destination.
  DestinationSpecification spec = 4;
  // Version of the destination.
  int64 version                 = 5;
}

message SetRulesRequest {
  // Destination is the name of the destination to set the ruleset for.
  string destination = 1;
  // Name of the ruleset to create or update.
  string name        = 2;
  // Deploy will immediately activate the ruleset if set to true.
  bool deploy        = 3;
  // Rules is the blockly state describing the rules.
  string rules       = 4;
}

message SetRulesResponse {
  // Version of the new or updated ruleset.
  int64 version = 1;
}

message GetRulesRequest {
  // Destination is the name of the destination to get the ruleset from.
  string destination = 1;
  // Name of the ruleset.
  string name        = 2;
}

message GetRulesResponse {
  // Version of the ruleset.
  int64 version  = 1;
  // Rules is the blockly state describing the rules.
  string rules   = 2;
  // Created timestamp Created timestamp as an RFC3339 string.
  string created = 3;
}

message DeployRulesRequest {
  // Destination to deploy rulesets for.
  string destination           = 1;
  // Sets of rulesets to deploy. 
  repeated DeployRulesSet sets = 2;
}

message DeployRulesSet {
  // Name of the ruleset.
  string name   = 1;
  // Version that should be deployed.
  int64 version = 2;  
}

message DeployRulesResponse {}

message DeleteRulesRequest {
  // Destination to delete the ruleset from.
  string destination = 1;
  // Name of the ruleset to delete.
  string name        = 2;
}

message DeleteRulesResponse {}

message TestRulesRequest {
  // Date in the format YYYY-MM-DD get events from for testing.
  string date     = 1;
  // Timezone to calculate the date start and end timestamps.
  string timezone = 2;
  // Rules is the blockly state that should be tested.
  string rules    = 3;
}

message TestRulesResponse {
  // Docs that matched the rules.
  repeated TestDocument docs = 1;
}

message TestDocument {
  // Id of the event that represents the document.
  int64 id        = 1;
  // Uri of the document.
  string uri      = 2;
  // Headline of the document.
  string headline = 3;
  // Webprio is the web priority of the document.
  int32 webprio   = 4;
  // Time is the timestamp for the event as an RFC3339 string.
  string time     = 5;
  // FirstPublished is the time of the first publication as an RFC3339 string.
  string firstPublished         = 6;
  // Delivery tags set by the ruleset.
  repeated string delivery_tags = 7;
  // Genre of the document.
  repeated string genre         = 8;
  // MatchedBy is the IDs of the rules that matched the document.
  repeated string matched_by    = 9;
  // Newsvalue of the document.
  int32 newsvalue = 10;
}