chattolib/proto/chatto/api/v1/notification_preferences.proto

syntax = "proto3";

package chatto.api.v1;

import "buf/validate/validate.proto";

// Notification delivery level for a room.
enum NotificationLevel {
  // The level was not specified.
  NOTIFICATION_LEVEL_UNSPECIFIED = 0;
  // Use the inherited default for the room.
  NOTIFICATION_LEVEL_DEFAULT = 1;
  // Do not notify for this room.
  NOTIFICATION_LEVEL_MUTED = 2;
  // Notify according to the normal room rules.
  NOTIFICATION_LEVEL_NORMAL = 3;
  // Notify for every message in the room.
  NOTIFICATION_LEVEL_ALL_MESSAGES = 4;
}

// Stored and effective notification preference.
message NotificationPreference {
  // Explicit level stored for the current user.
  NotificationLevel level = 1;
  // Level after applying defaults and inheritance.
  NotificationLevel effective_level = 2;
}

// Current notification preference.
message GetNotificationPreferenceResponse {
  // Field 1 was `level` and field 2 was `effective_level` before the shared
  // NotificationPreference shape.
  reserved 1, 2;
  reserved "level", "effective_level";

  // Current stored and effective notification preference.
  NotificationPreference preference = 3;
}

// Updated notification preference.
message UpdateNotificationPreferenceResponse {
  // Field 1 was `level` and field 2 was `effective_level` before the shared
  // NotificationPreference shape.
  reserved 1, 2;
  reserved "level", "effective_level";

  // Stored and effective notification preference after the update.
  NotificationPreference preference = 3;
}

// Request for the current user's server-level notification preference.
message GetServerNotificationPreferenceRequest {}

// Request to update the current user's server-level notification level.
message UpdateServerNotificationPreferenceRequest {
  // Required. New explicit notification level. Use NOTIFICATION_LEVEL_DEFAULT
  // to return the server to default behavior.
  NotificationLevel level = 1 [(buf.validate.field).enum = {
    defined_only: true
    not_in: [0]
  }];
}

// Request for the current user's notification preference in one room.
message GetRoomNotificationPreferenceRequest {
  // Required. Room whose notification preference should be loaded for the current user.
  string room_id = 1 [(buf.validate.field).string.min_len = 1];
}

// Request to update the current user's notification level in one room.
message UpdateRoomNotificationPreferenceRequest {
  // Required. Room whose notification level should be changed for the current user.
  string room_id = 1 [(buf.validate.field).string.min_len = 1];
  // Required. New explicit notification level. Use NOTIFICATION_LEVEL_DEFAULT
  // to return the room to inherited/default behavior.
  NotificationLevel level = 2 [(buf.validate.field).enum = {
    defined_only: true
    not_in: [0]
  }];
}

// Reads and updates per-room notification preferences for the current user.
service NotificationPreferencesService {
  // Returns the current user's explicit and effective server notification level.
  rpc GetServerNotificationPreference(GetServerNotificationPreferenceRequest) returns (GetNotificationPreferenceResponse);
  // Updates the current user's explicit server notification level and returns the
  // resulting stored and effective levels.
  rpc UpdateServerNotificationPreference(UpdateServerNotificationPreferenceRequest) returns (UpdateNotificationPreferenceResponse);
  // Returns the current user's explicit and effective notification level for a
  // room. Use this before rendering room notification controls so the UI can
  // distinguish inherited defaults from an explicit room override. Returns
  // NOT_FOUND when the room does not exist and PERMISSION_DENIED when the room
  // exists but is inaccessible to the caller.
  rpc GetRoomNotificationPreference(GetRoomNotificationPreferenceRequest) returns (GetNotificationPreferenceResponse);
  // Updates the current user's explicit notification level for a room and returns
  // the resulting stored and effective levels.
  rpc UpdateRoomNotificationPreference(UpdateRoomNotificationPreferenceRequest) returns (UpdateNotificationPreferenceResponse);
}