syntax = "proto3";
package one.api.v1;

//// General Message Information

enum RequestStatus {
  UNKNOWN_ERROR = 0;
  SUCCESS = 1;

  // An invalid session means that your session_token is no longer valid, and
  // you must log in again.
  INVALID_SESSION = 2;

  // An invalid request means that your request had something wrong with it.
  // Repeating the same request will almost certainly not fix the error, the
  // problem is on the client side. This may be the response, for example, if
  // you request a profile for a user who does not exist, or try to delete
  // another user's image.
  INVALID_REQUEST = 3;

  // This means that the server is too busy, or that the client has been making
  // requests too frequently. In either case, the client should pause at least
  // two seconds before making additional requests.
  TOO_BUSY = 4;
}

message Location {
  float latitude = 1;
  float longitude = 2;
  string name = 3; // Rarely used, mostly for glances
}

message UserLocation {
  // As always, don't count on any of these to exist when reading.
  // In particular, ttl_ms will default to 0 if not present, so be careful.
  bytes user_id = 1;
  Location location = 2;
  string tagline = 3;
  uint32 ttl_ms = 4;
}

//// Authentication

message AuthenticationDetails {
  enum EnumAuthenticationType {
    AUTH_SOURCE_LOCAL = 0; // Authenticating with an email address and password
    AUTH_SOURCE_FACEBOOK = 1; // Authenticating by Facebook token
  }
  EnumAuthenticationType auth_type = 1;

  // Note: auth_type == LOCAL should use the "username" and "password" fields
  // auth_type == FACEBOOK should use only the "token" field
  string username = 2;
  string password = 3;
  string token = 4;
}

enum EnumAuthenticationResponse {
  // Note: Anything other than AUTH_SUCCESS is an error. You should catch any
  // unknown values and just say there was an unknown error, in case this list
  // gets expanded in the future.
  AUTH_UNKNOWN_ERROR = 0;
  AUTH_SUCCESS = 1;
  INVALID_CREDENTIALS = 2;
  EXPIRED_CREDENTIALS = 3;
  ACCOUNT_EXISTS = 4;
}

message LoginRequest {
  AuthenticationDetails auth = 1;
}

message LoginResponse {
  EnumAuthenticationResponse response_code = 1;

  // session_token will only be set if response_code == SUCCESS
  // Note that session_token is an opaque string of bytes:
  // * Do not assume it is a valid UTF-8 string.
  // * Do not assume it has a fixed length.
  // * Its length should not exceed 1024 bytes, but avoid using a fixed buffer
  //   to store it. If you do, double-check the length before storing it.
  // * It will last for a reasonably long period of time. You can save it to
  //   a keychain to avoid needing to have the user log in repeatedly.
  bytes session_token = 2;

  // This is the profile ID of the logged-in user. 16 bytes.
  // Note that you should almost always request your own profile after logging
  // in. This will allow you to sync the user information across multiple
  // devices, check to see if the user has paid, and so on.
  bytes profile_id = 3;
}

message LogoutRequest {
  // This just destroys a session.
  bytes session_token = 1; // The session_token from logging in
}

message LogoutResponse {
  RequestStatus status = 1;
}

message CreateProfileRequest {
  AuthenticationDetails auth = 1;
}

message CreateProfileResponse {
  EnumAuthenticationResponse response_code = 1;

  // profile_id will only be set if response_code == SUCCESS
  bytes profile_id = 2;
}

//// Profiles

message Profile {
  // NOTE: A profile is not guaranteed to contain ANY of these fields. You MUST
  // verify that a field has content before attempting to display it in a user
  // interface.

  // Obvious examples of this may include: you can't see the birthdate for
  // other users, but you can see your own, etc.

  // However, there may be conditions under which you can see, for example,
  // the username and images of someone, but not their bio.

  message Image {
    bytes id = 1; // An opaque identifier. 16 bytes.
    string uri = 2;
    // The ordering priority of this image. Note that lower numbers are given
    // higher priority, so it would be reasonable to start at 0 and go up as
    // images are added with less priority.
    int32 priority = 3;
    int32 size = 4; // The size of the file referred to by uri in bytes.

    // Note again that you can't count on the thumbnail to exist, but it might.
    string thumb_uri = 5; // A thumbnail that can be loaded more quickly.
    int32 thumb_size = 6; // The filesize for the thumbnail.

    // This is to be used when uploading an image, and almost never otherwise.
    // Note that images uploaded MUST be in JPEG format.
    bytes image_content = 16;
  }

  bytes id = 1; // An opaque identifier. 16 bytes.
  string name = 2;
  repeated Image images = 3;
  bool is_male = 4;
  string biography = 5;
  int64 profile_views = 6;

  // Less commonly exposed fields get tags > 15 to save space.
  // 20-39: What the user is looking for.
  bool looking_for_men = 20;
  bool looking_for_women = 21;
  int32 looking_for_min_age = 22;
  int32 looking_for_max_age = 23;

  // 40-59: Properties of the user.
  int32 birthday_year = 40;
  int32 birthday_month = 41;
  int32 birthday_day = 42;

  // 60-79: Internal recordkeeping
  bool configuration_completed = 60;
  bool is_paying_user = 61;
}

message GetProfileRequest {
  bytes session_token = 1; // The session_token from logging in
  bytes profile_id = 2; // The profile_id you're requesting
}

message GetProfileResponse {
  RequestStatus status = 1;

  // Only some fields will actually be set:
  // * name
  // * images
  // * is_male
  // * biography
  // * profile_views
  Profile profile = 2;
}

message UpdateProfileRequest {
  bytes session_token = 1; // The session_token from logging in

  // This is the profile update.
  // Notes:
  // * Images should not be updated this way.
  // * All user-editable fields MUST be set on the profile, or they will be
  //   reset to defaults, including potentially changing the user's gender.
  // * To clear the name or biography, set them to be blank.
  // * You cannot modify profile_views, nor can you clear most fields once
  //   set (you can override, but not clear, birthdays, etc.).
  Profile profile = 2;
}

message UpdateProfileResponse {
  RequestStatus status = 1;
}

//// Images

message UploadImageRequest {
  bytes session_token = 1; // The session_token from logging in
  Profile.Image image = 2; // The image to upload
}

message UploadImageResponse {
  RequestStatus status = 1;

  // The ID of the image that got uploaded if successful, 16 bytes.
  bytes image_id = 2;
}

message DeleteImageRequest {
  bytes session_token = 1; // The session_token from logging in
  bytes image_id = 2; // One image_id to delete
}

message DeleteImageResponse {
  RequestStatus status = 1;
}

message ReorderImagesRequest {
  bytes session_token = 1; // The session_token from logging in

  // This may be confusing at first: you're sending an array of Profile.Image
  // objects, where the id must be set to the image ID, and the priority must
  // be the new priority of the image. All other fields will be ignored, but
  // this allows for batching of updates to photo ordering.
  repeated Profile.Image images = 2;
}

message ReorderImagesResponse {
  RequestStatus status = 1;
}

//// Messages

// Note: This is a somewhat simplified message synchronizing system, and may be
// swapped out at a later date. The general theme:
// * Messages have one of several types, including TEXT, GLANCE, and DELETE.
// * Messages have an ID and a "order". The "order" is assigned by the
//   server, not the client.
// * Messages MUST be processed in "order" order.
// * A DELETE message instructs the client (and server) to delete the message
//   with the ID given by the DELETE message.
// * When a client processes a DELETE message, it should check to see if any
//   message has an ID matching that of the DELETE message.
//   * If there is one, delete it and don't store the DELETE message.
//   * If there isn't one, ignore the DELETE message.
// * When synchronizing messages, store the last "order", and only request
//   messages that were sent after that "order" in the future.
// * Marking a message as read is done by sending a READ message to the server
//   with an ID of the message that was read. Semantics for processing READ
//   messages on the client are similar to those of DELETE: if the message
//   exists, mark it read, otherwise, ignore the READ message.

// Additionally, a number of things will be enforced by the server:
// * You can mark only messages sent *to* you as read.
// * You can delete only messages sent *to* you.
// * Deleting a message deletes it for both users.

enum EnumSentMessageType {
  TEXT = 0;   // Contains only text
  GLANCE = 1; // Contains only a location
  DELETE = 2; // Deletes a previous message
  READ = 3;   // Marks a previous message as read
}

message SentMessage {
  bytes id = 1; // Opaque identifier, 16 bytes.
  EnumSentMessageType type = 2;
  bytes from_id = 3; // The sender of this message
  bytes to_id = 4; // The recipient of this message
  uint64 order = 5; // The order for this message, opaque, but sortable

  // A timestamp for this message in seconds from the Unix epoch (UTC)
  uint64 timestamp = 6;

  // Text for this message, if the type allows it.
  string content = 7;

  // A location for this message, if the type allows it.
  Location location = 8;
}

message SendMessageRequest {
  bytes session_token = 1; // The session_token from logging in
  SentMessage message = 2; // The message to send
}

message SendMessageResponse {
  RequestStatus status = 1;
  bytes message_id = 2; // The message ID sent, if successful
}

message UpdateMessagesRequest {
  bytes session_token = 1; // The session_token from logging in

  // The "order" number from which to start retrieving messages. Note that
  // if no "order" is known, this field can be omitted or set to 0.
  uint64 order = 2;
}

message UpdateMessagesResponse {
  // Note: this response is likely to be sent multiple times, when there are
  // multiple items to retrieve.
  RequestStatus status = 1;
  SentMessage message = 2;
}

message VoteMessageRequest {
  RequestStatus status = 1;
  bytes message_id = 2; // The message ID to vote on

  // The number of points to give/take from the message. Note that the server
  // MAY require that this number be one of {-1, 0, 1} or otherwise bounded.
  int32 vote = 3;
}

//// Map

message UpdateMapRequest {
  bytes session_token = 1; // The session_token from logging in
  Location location = 2; // Your current location
  string tagline = 3; // Text you want to have display with your location
  uint32 ttl_ms = 4; // Time to leave this on the map in milliseconds
  bool need_other_users = 5; // Set to true if you want other users' locations
}

message UpdateMapResponse {
  RequestStatus status = 1;

  // Zero or more users in the nearby area.
  repeated UserLocation locations = 2;
}

//// Service definition

service Apiv1 {
  // Authentication
  rpc Login(LoginRequest) returns (LoginResponse);
  rpc Logout(LogoutRequest) returns (LogoutResponse);
  rpc CreateProfile(CreateProfileRequest) returns (CreateProfileResponse);

  // Profiles
  rpc GetProfile(GetProfileRequest) returns (GetProfileResponse);
  rpc UpdateProfile(UpdateProfileRequest) returns (UpdateProfileResponse);

  // Images
  rpc UploadImage(UploadImageRequest) returns (UploadImageResponse);
  rpc DeleteImage(DeleteImageRequest) returns (DeleteImageResponse);
  rpc ReorderImages(ReorderImagesRequest) returns (ReorderImagesResponse);

  // Messages
  rpc SendMessage(SendMessageRequest) returns (SendMessageResponse);
  rpc UpdateMessages(UpdateMessagesRequest) returns (stream UpdateMessagesResponse);

  // Map
  rpc UpdateMap(UpdateMapRequest) returns (UpdateMapResponse);
}