syntax = "proto3";

package nominal.settings.coachmarks.v1;

import "buf/validate/validate.proto";
import "google/api/annotations.proto";
import "google/protobuf/timestamp.proto";
import "nominal/protos/gen/v1/alias.proto";

// A record of a coachmark dismissal, including when it was dismissed and on which app version.
message CoachmarkDismissal {
  string user_rid = 1 [
    (nominal.gen.v1.alias) = {java_name: "io.nominal.scout.rids.api.UserRid"},
    (buf.validate.field) = {required: true},
    (buf.validate.field).string.pattern = "^ri\\.authn\\.([a-z0-9][a-z0-9\\-]*)?\\.user\\.[a-fA-F0-9\\-\\._]+$"
  ];
  // The coachmark identifier (typically the feature flag name)
  string coachmark_id = 2 [(buf.validate.field) = {required: true}];

  // The apps-scout version (semver) when the coachmark was dismissed
  string app_version = 3 [(buf.validate.field) = {required: true}];

  google.protobuf.Timestamp dismissed_at = 4 [(buf.validate.field) = {required: true}];

  // The step index when dismissed (for multi-step coachmarks).
  // If not present, the coachmark was dismissed via the X button.
  optional int32 step_index = 5;
}

// Request to dismiss a coachmark for the current user.
message DismissCoachmarkRequest {
  // The coachmark identifier (typically the feature flag name)
  string coachmark_id = 1 [(buf.validate.field) = {required: true}];

  // The apps-scout version (semver) when the coachmark was dismissed
  string app_version = 2 [(buf.validate.field) = {required: true}];

  // The step index when dismissed (for multi-step coachmarks).
  // If not present, the coachmark was dismissed via the X button.
  optional int32 step_index = 3;
}

message DismissCoachmarkResponse {
  CoachmarkDismissal dismissal = 1;
}

// Request to list coachmark dismissals for the current user.
message ListCoachmarkDismissalsRequest {
  // Optional list of coachmark IDs to filter by.
  // If empty, returns all dismissals for the user.
  repeated string coachmark_ids = 1;
}

// Response containing coachmark dismissals.
message ListCoachmarkDismissalsResponse {
  // Map of coachmark ID to dismissal record.
  map<string, CoachmarkDismissal> dismissals = 1;
}

// Request to get a singular coachmark dismissal for the current user.
message GetCoachmarkDismissalRequest {
  string coachmark_id = 1 [(buf.validate.field) = {required: true}];
}

message GetCoachmarkDismissalResponse {
  // The dismissal record, if the coachmark has been dismissed. Absent otherwise.
  optional CoachmarkDismissal dismissal = 1;
}

// Request to delete a coachmark dismissal for the current user.
message DeleteCoachmarkDismissalRequest {
  string coachmark_id = 1 [(buf.validate.field) = {required: true}];
}

message DeleteCoachmarkDismissalResponse {}

// Service for managing coachmark dismissals for the authenticated user.
service CoachmarksService {
  // Lists coachmark dismissals for the authenticated user.
  // Optionally filter by specific coachmark IDs.
  rpc ListCoachmarkDismissals(ListCoachmarkDismissalsRequest) returns (ListCoachmarkDismissalsResponse) {
    option (google.api.http) = {
      post: "/settings/v1/coachmarks/dismissals"
      response_body: "dismissals"
    };
  }

  // Dismisses a coachmark for the authenticated user.
  // Records the dismissal timestamp and app version.
  rpc DismissCoachmark(DismissCoachmarkRequest) returns (DismissCoachmarkResponse) {
    option (google.api.http) = {
      put: "/settings/v1/coachmarks/dismissals/{coachmark_id}"
      response_body: "dismissal"
    };
  }

  // Gets a specific coachmark dismissal for the authenticated user.
  rpc GetCoachmarkDismissal(GetCoachmarkDismissalRequest) returns (GetCoachmarkDismissalResponse) {
    option (google.api.http) = {get: "/settings/v1/coachmarks/dismissals/{coachmark_id}"};
  }

  // Deletes a coachmark dismissal for the authenticated user.
  // This allows the coachmark to be shown again. Primarily intended for testing and debugging.
  rpc DeleteCoachmarkDismissal(DeleteCoachmarkDismissalRequest) returns (DeleteCoachmarkDismissalResponse) {
    option (google.api.http) = {delete: "/settings/v1/coachmarks/dismissals/{coachmark_id}"};
  }
}
