chattolib/proto/chatto/api/v1/presence.proto

syntax = "proto3";

package chatto.api.v1;

import "buf/validate/validate.proto";

// Saved choice visible only to the authenticated account itself.
message PresencePreference {
  // Saved choice, independent of liveness. OFFLINE means "Appear Offline";
  // DO_NOT_DISTURB suppresses alerts even while disconnected.
  PresenceStatus status = 1;
  // Opaque revision required when replacing this choice.
  string revision = 2;
}

// Read the authenticated account's own choice; accepts no other user ID.
message GetPresencePreferenceRequest {}
// Current private choice, or absence before first initialization.
message GetPresencePreferenceResponse {
  // Absent until the account first saves a choice.
  PresencePreference preference = 1;
}

// An explicit selection. Heartbeats must not call this operation.
message SetPresencePreferenceRequest {
  // Explicit new choice for every device on this server.
  PresenceStatus status = 1 [(buf.validate.field).enum = {defined_only: true, not_in: [0]}];
  // Revision from the last read; empty only when initializing an absent choice.
  string expected_revision = 2;
}
// Acknowledged current choice after the selection commits.
message SetPresencePreferenceResponse {
  PresencePreference preference = 1;
}

// Refresh the authenticated account's liveness without supplying a choice.
message RefreshPresenceRequest {}
// Current private choice after refreshing liveness.
message RefreshPresenceResponse {
  // Private saved choice; clients use this to recover missed device updates.
  PresencePreference preference = 1;
}

// Availability used for private choices and effective public presence.
//
// Public Offline reveals neither connection liveness nor whether the account
// selected "Appear Offline". A saved Online, Away, or Do Not Disturb choice
// becomes public Offline when no device refreshes liveness.
enum PresenceStatus {
  // No presence status was specified.
  PRESENCE_STATUS_UNSPECIFIED = 0;
  // Online while at least one device refreshes liveness.
  PRESENCE_STATUS_ONLINE = 1;
  // Away while at least one device refreshes liveness.
  PRESENCE_STATUS_AWAY = 2;
  // Do Not Disturb. A saved choice suppresses alerts even while disconnected.
  PRESENCE_STATUS_DO_NOT_DISTURB = 3;
  // No public live presence. As a saved choice, suppresses presence and typing.
  PRESENCE_STATUS_OFFLINE = 4;
}

// Legacy live report. A saved private choice takes precedence over this report.
message SetPresenceRequest {
  // Live status to store for the authenticated user. Offline is rejected.
  PresenceStatus status = 1 [(buf.validate.field).enum = {
    defined_only: true
    not_in: [0, 4]
  }];
  // Legacy manual-selection flag. It cannot replace a saved private choice.
  // New clients use SetPresencePreference for explicit selections.
  bool user_selected = 2;
}

// Result of updating live presence.
message SetPresenceResponse {
  // Reportable status accepted and stored by the server.
  PresenceStatus status = 1;
}