chattolib/proto/chatto/api/v1/viewer.proto

syntax = "proto3";

package chatto.api.v1;

import "chatto/api/v1/permissions.proto";
import "chatto/api/v1/users.proto";
import "google/protobuf/timestamp.proto";

// User preference for rendering times in clients.
enum TimeFormat {
  // No explicit preference was stored.
  TIME_FORMAT_UNSPECIFIED = 0;
  // Let the client choose based on locale and browser settings.
  TIME_FORMAT_AUTO = 1;
  // Render times using a 12-hour clock.
  TIME_FORMAT_12_HOUR = 2;
  // Render times using a 24-hour clock.
  TIME_FORMAT_24_HOUR = 3;
}

// Server-level display settings for the authenticated user.
message UserSettings {
  // Optional IANA timezone override. Absent means no choice has been recorded.
  // Empty means the user explicitly chose the browser's local timezone.
  // Both use browser-local time; only absence permits automatic device reporting.
  optional string timezone = 1;
  // Preferred time format.
  TimeFormat time_format = 2;
  // Whether the stored time zone may appear on the user's public profile.
  // New servers always set this field. Its absence means the server does not
  // support private time zones and may publish any stored time zone.
  optional bool share_timezone = 3;
}

// Current authenticated user's public profile plus self-only settings.
message ViewerUser {
  reserved 1 to 6;
  reserved "id", "login", "display_name", "avatar_url", "custom_status", "presence_status";

  // Whether the account has at least one verified email address.
  bool has_verified_email = 7;
  // Current user's display settings.
  UserSettings settings = 8;
  // Whether the authenticated user may delete this account.
  bool viewer_can_delete_account = 9;
  // Last time a login credential changed, when known.
  google.protobuf.Timestamp last_login_change = 10;
  // Public user fields for the authenticated user.
  User profile = 11;
  // Whether this account currently has a password sign-in credential.
  bool has_password = 12;
}

// Permission-derived capabilities for the authenticated user.
message ViewerCapabilities {
  // Keyed capability decisions for the authenticated user.
  repeated CapabilityGrant grants = 1;
  // Whether the user has unread followed threads.
  bool has_unread_followed_threads = 2;
}

// Effective server/channel permission decisions for the authenticated user.
message ServerViewerPermissions {
  // One row per permission known to the server.
  repeated PermissionGrant permissions = 1;
}

// Non-permission server state for the authenticated user.
message ServerViewerState {
  // Whether any joined channel room has neutral Badge attention.
  bool has_unread_rooms = 1;
}

// State of explicit privileged-mode activation for this authenticated session.
message PrivilegedModeState {
  // Whether the user has an elevation-required permission entitlement. This
  // includes owner entitlement and explicit allows at any supported scope.
  bool available = 1;
  // Whether elevated permissions are effective for this session now.
  bool active = 2;
  // Absolute activation deadline. Present only while privileged mode is active.
  google.protobuf.Timestamp expires_at = 3;
}

// Request for the authenticated viewer snapshot.
message GetViewerRequest {}

// Authenticated viewer snapshot needed by application shells.
message GetViewerResponse {
  reserved 3, 4;
  reserved "server_notification_preference", "room_notification_preferences";

  // Current authenticated user.
  ViewerUser user = 1;
  // Permission-derived capabilities.
  ViewerCapabilities capabilities = 2;
  // Effective server/channel permission decisions for the authenticated user.
  ServerViewerPermissions viewer_permissions = 5;
  // Non-permission server state for the authenticated user.
  ServerViewerState viewer_state = 6;
  // Explicit privilege activation state for this authenticated session.
  PrivilegedModeState privileged_mode = 7;
}

// Request to activate all currently entitled elevation-required permissions.
message ActivatePrivilegedModeRequest {}

// Result of activating privileged mode for the current session.
message ActivatePrivilegedModeResponse {
  // Current privileged-mode state after activation.
  PrivilegedModeState privileged_mode = 1;
  // Permission-derived capabilities that are effective after activation.
  ViewerCapabilities capabilities = 2;
  // Effective server permission decisions after activation.
  ServerViewerPermissions viewer_permissions = 3;
}

// Request to deactivate all elevation-required permissions for this session.
message DeactivatePrivilegedModeRequest {}

// Result of deactivating privileged mode for the current session.
message DeactivatePrivilegedModeResponse {
  // Current privileged-mode state after deactivation.
  PrivilegedModeState privileged_mode = 1;
  // Permission-derived capabilities that are effective after deactivation.
  ViewerCapabilities capabilities = 2;
  // Effective server permission decisions after deactivation.
  ServerViewerPermissions viewer_permissions = 3;
}

// Provides authenticated user profile, preferences, and capability state.
service ViewerService {
  // Returns the current authenticated viewer. This RPC requires a logged-in
  // user; unauthenticated callers receive an UNAUTHENTICATED error.
  rpc GetViewer(GetViewerRequest) returns (GetViewerResponse);
  // Activates elevation-required permissions for a fixed, non-sliding window.
  // Returns FAILED_PRECONDITION when the caller is a bot or has no eligible
  // permission entitlement.
  rpc ActivatePrivilegedMode(ActivatePrivilegedModeRequest) returns (ActivatePrivilegedModeResponse);
  // Deactivates elevation-required permissions immediately. Returns
  // FAILED_PRECONDITION when the caller is a bot.
  rpc DeactivatePrivilegedMode(DeactivatePrivilegedModeRequest) returns (DeactivatePrivilegedModeResponse);
}