SlackController.java

package edu.ucsb.cs156.frontiers.controllers;

import edu.ucsb.cs156.frontiers.entities.Course;
import edu.ucsb.cs156.frontiers.entities.CourseOption;
import edu.ucsb.cs156.frontiers.entities.CourseStaff;
import edu.ucsb.cs156.frontiers.entities.RosterStudent;
import edu.ucsb.cs156.frontiers.enums.CourseOptions;
import edu.ucsb.cs156.frontiers.enums.RosterStatus;
import edu.ucsb.cs156.frontiers.errors.EntityNotFoundException;
import edu.ucsb.cs156.frontiers.errors.SlackApiException;
import edu.ucsb.cs156.frontiers.jobs.SetupPrivateSlackChannelsJob;
import edu.ucsb.cs156.frontiers.jobs.SetupSectionSlackChannelsJob;
import edu.ucsb.cs156.frontiers.jobs.SetupTeamSlackChannelsJob;
import edu.ucsb.cs156.frontiers.models.SlackAuthTestResponse;
import edu.ucsb.cs156.frontiers.models.SlackUser;
import edu.ucsb.cs156.frontiers.repositories.CourseOptionRepository;
import edu.ucsb.cs156.frontiers.repositories.CourseRepository;
import edu.ucsb.cs156.frontiers.repositories.CourseStaffRepository;
import edu.ucsb.cs156.frontiers.repositories.RosterStudentRepository;
import edu.ucsb.cs156.frontiers.repositories.SectionRepository;
import edu.ucsb.cs156.frontiers.repositories.TeamRepository;
import edu.ucsb.cs156.frontiers.services.CanvasApiTokenSecurityService;
import edu.ucsb.cs156.frontiers.services.SlackService;
import edu.ucsb.cs156.frontiers.utilities.CanonicalFormConverter;
import edu.ucsb.cs156.jobs.entities.Job;
import edu.ucsb.cs156.jobs.services.JobService;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

/**
 * Endpoints for the Slack integration of a course.
 *
 * <p>The Slack bot token is a secret: it is encrypted at rest (using the same infrastructure as
 * Canvas API tokens), never logged, and only ever returned to the frontend in masked form.
 */
@RestController
@RequestMapping("/api/courses/slack")
@Tag(name = "Slack")
public class SlackController extends ApiController {

  private static final int VISIBLE_TOKEN_CHARS = 4;

  /** Error code used when a valid token could not be encrypted, and so was not stored. */
  public static final String ENCRYPTION_FAILED = "encryption_failed";

  /** Where a workspace can be opened when its own URL is not known. */
  public static final String SLACK_CLIENT_URL = "https://app.slack.com/client/";

  private final CourseRepository courseRepository;
  private final RosterStudentRepository rosterStudentRepository;
  private final CourseStaffRepository courseStaffRepository;
  private final SectionRepository sectionRepository;
  private final TeamRepository teamRepository;
  private final CourseOptionRepository courseOptionRepository;
  private final SlackService slackService;
  private final CanvasApiTokenSecurityService tokenSecurityService;
  private final JobService jobService;

  public SlackController(
      CourseRepository courseRepository,
      RosterStudentRepository rosterStudentRepository,
      CourseStaffRepository courseStaffRepository,
      SectionRepository sectionRepository,
      TeamRepository teamRepository,
      CourseOptionRepository courseOptionRepository,
      SlackService slackService,
      CanvasApiTokenSecurityService tokenSecurityService,
      JobService jobService) {
    this.courseRepository = courseRepository;
    this.rosterStudentRepository = rosterStudentRepository;
    this.courseStaffRepository = courseStaffRepository;
    this.sectionRepository = sectionRepository;
    this.teamRepository = teamRepository;
    this.courseOptionRepository = courseOptionRepository;
    this.slackService = slackService;
    this.tokenSecurityService = tokenSecurityService;
    this.jobService = jobService;
  }

  /** A person with an active account in the Slack workspace, and their role in the course. */
  public static record SlackUserView(
      String slackUserId,
      String name,
      String realName,
      String displayName,
      String email,
      String courseRole) {}

  /** A roster student or staff member who does not have an active account in the workspace. */
  public static record SlackMissingMemberView(
      String courseRole, String firstName, String lastName, String email, String slackStatus) {}

  public static final String ROLE_INSTRUCTOR = "INSTRUCTOR";
  public static final String ROLE_STAFF = "STAFF";
  public static final String ROLE_STUDENT = "STUDENT";
  public static final String ROLE_NONE = "NONE";

  /** Invited to the workspace, but has not yet signed in. */
  public static final String STATUS_INVITED = "INVITED";

  /** Has an account in the workspace, but it has been deactivated. */
  public static final String STATUS_DEACTIVATED = "DEACTIVATED";

  /** Slack has no record of this email address in the workspace. */
  public static final String STATUS_NOT_IN_SLACK = "NOT_IN_SLACK";

  private static final String STATUS_ACTIVE = "ACTIVE";

  /**
   * Returns the Slack workspace (team) associated with the course, along with a masked version of
   * the Slack bot token.
   *
   * @param courseId the id of the course
   * @return a map with courseId, slackBotToken (masked), slackTeamId, slackTeamName and
   *     slackTeamUrl; values are empty strings when no token has been stored
   */
  @Operation(summary = "Get Slack workspace info and Slack bot token (masked) for a course")
  @PreAuthorize("@CourseSecurity.hasManagePermissions(#root, #courseId)")
  @GetMapping("/info")
  public Map<String, String> getSlackInfo(
      @Parameter(name = "courseId") @RequestParam Long courseId) {
    Course course =
        courseRepository
            .findById(courseId)
            .orElseThrow(() -> new EntityNotFoundException(Course.class, courseId));
    course = backfillSlackTeamUrl(course);
    return slackInfo(course);
  }

  /**
   * Tokens saved before the workspace URL was recorded (see {@link Course#getSlackTeamUrl()}) have
   * no way to show a real "Admin" link; this calls Slack's <code>auth.test</code> again, using the
   * already-stored (and validated) token, to fetch and save the workspace's own URL. Any failure to
   * reach Slack is ignored here: the rest of the page still works from the cached data, and the
   * <code>app.slack.com</code> fallback URL is used instead.
   *
   * @param course the course
   * @return the course, with slackTeamUrl backfilled and saved if it was missing and could be
   *     determined
   */
  private Course backfillSlackTeamUrl(Course course) {
    boolean hasUrl = course.getSlackTeamUrl() != null && !course.getSlackTeamUrl().isEmpty();
    boolean hasToken = course.getSlackBotToken() != null && !course.getSlackBotToken().isEmpty();
    if (hasUrl || !hasToken) {
      return course;
    }
    String token = tokenSecurityService.decrypt(course.getSlackBotToken());
    SlackAuthTestResponse authTest = slackService.authTest(token);
    if (!authTest.getOk() || authTest.getUrl() == null || authTest.getUrl().isEmpty()) {
      return course;
    }
    course.setSlackTeamUrl(authTest.getUrl());
    return courseRepository.save(course);
  }

  /**
   * Validates a Slack bot token by calling the Slack <code>auth.test</code> method. If the token is
   * valid, it is encrypted and stored, along with the id and name of the workspace (team) it
   * belongs to. If it is invalid, nothing is stored, and a 400 response describes the problem.
   *
   * <p>The token should be sent in the (form encoded) body of the request rather than in the query
   * string, so that it does not end up in access logs.
   *
   * @param courseId the id of the course
   * @param slackBotToken the Slack bot token (<code>xoxb-...</code>)
   * @return on success, a map with ok=true, courseId, slackBotToken (masked), slackTeamId and
   *     slackTeamName; on failure, a map with ok=false, error (Slack error code) and message. If
   *     the token is valid but cannot be encrypted (e.g. the encryption key is not configured), it
   *     is not stored, and a 500 response with error {@link #ENCRYPTION_FAILED} is returned.
   */
  @Operation(summary = "Validate (via Slack auth.test) and store the Slack bot token for a course")
  @PreAuthorize("@CourseSecurity.hasManagePermissions(#root, #courseId)")
  @PostMapping("/token")
  public ResponseEntity<Map<String, Object>> updateSlackToken(
      @Parameter(name = "courseId") @RequestParam Long courseId,
      @Parameter(name = "slackBotToken") @RequestParam String slackBotToken) {
    Course course =
        courseRepository
            .findById(courseId)
            .orElseThrow(() -> new EntityNotFoundException(Course.class, courseId));

    String token = slackBotToken.strip();
    SlackAuthTestResponse authTest = slackService.authTest(token);

    if (!authTest.getOk()) {
      Map<String, Object> body = new LinkedHashMap<>();
      body.put("ok", false);
      body.put("error", String.valueOf(authTest.getError()));
      body.put("message", errorMessage(authTest.getError()));
      return ResponseEntity.badRequest().body(body);
    }

    String encryptedToken;
    try {
      encryptedToken = tokenSecurityService.encrypt(token);
    } catch (IllegalStateException e) {
      // Typically a missing or malformed encryption key. The exception message describes the key
      // problem and never contains the token.
      Map<String, Object> body = new LinkedHashMap<>();
      body.put("ok", false);
      body.put("error", ENCRYPTION_FAILED);
      body.put("message", encryptionFailedMessage(e.getMessage()));
      return ResponseEntity.internalServerError().body(body);
    }

    course.setSlackBotToken(encryptedToken);
    course.setSlackTeamId(authTest.getTeamId());
    course.setSlackTeamName(authTest.getTeam());
    course.setSlackTeamUrl(authTest.getUrl());
    Course savedCourse = courseRepository.save(course);

    Map<String, Object> body = new LinkedHashMap<>();
    body.put("ok", true);
    body.putAll(slackInfo(savedCourse));
    return ResponseEntity.ok(body);
  }

  private Map<String, String> slackInfo(Course course) {
    Map<String, String> info = new LinkedHashMap<>();
    info.put("courseId", course.getId().toString());
    info.put("slackBotToken", maskToken(tokenSecurityService.decrypt(course.getSlackBotToken())));
    info.put("slackTeamId", course.getSlackTeamId() != null ? course.getSlackTeamId() : "");
    info.put("slackTeamName", course.getSlackTeamName() != null ? course.getSlackTeamName() : "");
    info.put("slackTeamUrl", slackTeamUrl(course));
    return info;
  }

  /**
   * The URL of the course's Slack workspace, e.g. <code>https://ucsb-cs156-f26.slack.com/</code>.
   * Tokens stored before the URL was being recorded fall back to a URL based on the team id.
   *
   * @param course the course
   * @return the URL, or an empty string if the course is not connected to a workspace
   */
  public static String slackTeamUrl(Course course) {
    if (course.getSlackTeamUrl() != null && !course.getSlackTeamUrl().isEmpty()) {
      return course.getSlackTeamUrl();
    }
    if (course.getSlackTeamId() != null && !course.getSlackTeamId().isEmpty()) {
      return SLACK_CLIENT_URL + course.getSlackTeamId();
    }
    return "";
  }

  /**
   * Lists the people with active accounts in the course's Slack workspace (no bots, no deactivated
   * accounts, no invitations that have not been accepted yet). Each is matched by email against the
   * course to determine whether they are the instructor, a staff member, a roster student (only
   * those with status ROSTER or MANUAL; not dropped students), or none of these.
   *
   * @param courseId the id of the course
   * @return the active users of the workspace
   */
  @Operation(summary = "List active users of the course's Slack workspace, with their course role")
  @PreAuthorize("@CourseSecurity.hasManagePermissions(#root, #courseId)")
  @GetMapping("/users")
  public List<SlackUserView> getSlackUsers(
      @Parameter(name = "courseId") @RequestParam Long courseId) {
    Course course =
        courseRepository
            .findById(courseId)
            .orElseThrow(() -> new EntityNotFoundException(Course.class, courseId));
    List<SlackUser> slackUsers = listSlackUsers(course);

    Map<String, String> roleByEmail = new HashMap<>();
    for (RosterStudent student : enrolledStudents(courseId)) {
      if (student.getEmail() != null) {
        roleByEmail.put(canonical(student.getEmail()), ROLE_STUDENT);
      }
    }
    for (CourseStaff staff : courseStaffRepository.findByCourseId(courseId)) {
      if (staff.getEmail() != null) {
        roleByEmail.put(canonical(staff.getEmail()), ROLE_STAFF);
      }
    }
    if (course.getInstructorEmail() != null) {
      roleByEmail.put(canonical(course.getInstructorEmail()), ROLE_INSTRUCTOR);
    }

    List<SlackUserView> result = new ArrayList<>();
    for (SlackUser user : slackUsers) {
      if (user.isActivePerson()) {
        String role =
            user.email() == null
                ? ROLE_NONE
                : roleByEmail.getOrDefault(canonical(user.email()), ROLE_NONE);
        result.add(
            new SlackUserView(
                user.getId(),
                user.getName(),
                user.getRealName(),
                user.displayName(),
                user.email(),
                role));
      }
    }
    return result;
  }

  /**
   * Lists the roster students (only those with status ROSTER or MANUAL; not dropped students) and
   * the staff of the course that do not have an active account in the course's Slack workspace,
   * matching by email. For each, slackStatus indicates whether they have been invited but have not
   * signed in yet, have a deactivated account, or are unknown to the workspace.
   *
   * @param courseId the id of the course
   * @return staff first, then students
   */
  @Operation(summary = "List roster students and staff that are not active in the Slack workspace")
  @PreAuthorize("@CourseSecurity.hasManagePermissions(#root, #courseId)")
  @GetMapping("/missing")
  public List<SlackMissingMemberView> getMissingMembers(
      @Parameter(name = "courseId") @RequestParam Long courseId) {
    Course course =
        courseRepository
            .findById(courseId)
            .orElseThrow(() -> new EntityNotFoundException(Course.class, courseId));
    List<SlackUser> slackUsers = listSlackUsers(course);

    // An active account wins over an invitation, which wins over a deactivated account
    Map<String, String> statusByEmail = new HashMap<>();
    for (String status : List.of(STATUS_DEACTIVATED, STATUS_INVITED, STATUS_ACTIVE)) {
      for (SlackUser user : slackUsers) {
        if (user.isPerson() && user.email() != null && status.equals(slackStatus(user))) {
          statusByEmail.put(canonical(user.email()), status);
        }
      }
    }

    List<SlackMissingMemberView> result = new ArrayList<>();
    for (CourseStaff staff : courseStaffRepository.findByCourseId(courseId)) {
      String status = missingStatus(statusByEmail, staff.getEmail());
      if (status != null) {
        result.add(
            new SlackMissingMemberView(
                ROLE_STAFF, staff.getFirstName(), staff.getLastName(), staff.getEmail(), status));
      }
    }
    for (RosterStudent student : enrolledStudents(courseId)) {
      String status = missingStatus(statusByEmail, student.getEmail());
      if (status != null) {
        result.add(
            new SlackMissingMemberView(
                ROLE_STUDENT,
                student.getFirstName(),
                student.getLastName(),
                student.getEmail(),
                status));
      }
    }
    return result;
  }

  /**
   * Launches a job that creates the public Slack channels named in the sections table of the
   * course, adds the roster students of each section to its channel, and removes from those
   * channels anybody who is neither a student of the section, nor staff, nor the instructor. See
   * {@link SetupSectionSlackChannelsJob}.
   *
   * @param courseId the id of the course
   * @return the job that was launched; its log can be seen on the Jobs tab of the course
   */
  @Operation(summary = "Launch job that sets up the Slack channels of the sections of a course")
  @PreAuthorize("@CourseSecurity.hasInstructorPermissions(#root, #courseId)")
  @PostMapping("/sectionChannels")
  public Job setupSectionChannels(@Parameter(name = "courseId") @RequestParam Long courseId) {
    Course course =
        courseRepository
            .findById(courseId)
            .orElseThrow(() -> new EntityNotFoundException(Course.class, courseId));
    for (CourseOptions option :
        List.of(CourseOptions.SLACK_INTEGRATION, CourseOptions.TRANSLATE_SECTIONS)) {
      boolean enabled =
          courseOptionRepository
              .findByCourseIdAndOption(courseId, option.name())
              .map(CourseOption::getEnabled)
              .orElse(false);
      if (!enabled) {
        throw new IllegalArgumentException(
            "The course option %s must be enabled to set up section Slack channels."
                .formatted(option.name()));
      }
    }
    String token = tokenSecurityService.decrypt(course.getSlackBotToken());
    if (token == null || token.isEmpty()) {
      throw new IllegalArgumentException(NO_TOKEN_MESSAGE);
    }

    SetupSectionSlackChannelsJob job =
        SetupSectionSlackChannelsJob.builder()
            .course(course)
            .courseRepository(courseRepository)
            .sectionRepository(sectionRepository)
            .rosterStudentRepository(rosterStudentRepository)
            .courseStaffRepository(courseStaffRepository)
            .slackService(slackService)
            .tokenSecurityService(tokenSecurityService)
            .build();
    return jobService.runAsJob(job);
  }

  /**
   * Launches a job that creates a public Slack channel for each team of the course (named "team-"
   * followed by the team name in Slack's form), adds the members of each team and the instructor to
   * the team's channel, and removes from those channels anybody who is neither on the team, nor the
   * instructor, nor staff. See {@link SetupTeamSlackChannelsJob}.
   *
   * @param courseId the id of the course
   * @return the job that was launched; its log can be seen on the Jobs tab of the course
   */
  @Operation(summary = "Launch job that sets up the Slack channels of the teams of a course")
  @PreAuthorize("@CourseSecurity.hasInstructorPermissions(#root, #courseId)")
  @PostMapping("/teamChannels")
  public Job setupTeamChannels(@Parameter(name = "courseId") @RequestParam Long courseId) {
    Course course =
        courseRepository
            .findById(courseId)
            .orElseThrow(() -> new EntityNotFoundException(Course.class, courseId));
    boolean enabled =
        courseOptionRepository
            .findByCourseIdAndOption(courseId, CourseOptions.SLACK_INTEGRATION.name())
            .map(CourseOption::getEnabled)
            .orElse(false);
    if (!enabled) {
      throw new IllegalArgumentException(
          "The course option SLACK_INTEGRATION must be enabled to set up team Slack channels.");
    }
    String token = tokenSecurityService.decrypt(course.getSlackBotToken());
    if (token == null || token.isEmpty()) {
      throw new IllegalArgumentException(NO_TOKEN_MESSAGE);
    }

    SetupTeamSlackChannelsJob job =
        SetupTeamSlackChannelsJob.builder()
            .course(course)
            .courseRepository(courseRepository)
            .teamRepository(teamRepository)
            .courseStaffRepository(courseStaffRepository)
            .slackService(slackService)
            .tokenSecurityService(tokenSecurityService)
            .build();
    return jobService.runAsJob(job);
  }

  /**
   * Launches a job that gives each roster student of the course who has a Slack account a private
   * Slack channel (named "private-" followed by the first and last name of the student), and adds
   * the student, the instructor and the staff of the course to it. A student's channel is
   * recognized by its members rather than by its name, so running the job again creates no
   * duplicates; it does remove from the existing channels anybody who is neither the student, nor
   * the instructor, nor staff. See {@link SetupPrivateSlackChannelsJob}.
   *
   * @param courseId the id of the course
   * @return the job that was launched; its log can be seen on the Jobs tab of the course
   */
  @Operation(
      summary = "Launch job that sets up a private Slack channel for each student plus the staff")
  @PreAuthorize("@CourseSecurity.hasInstructorPermissions(#root, #courseId)")
  @PostMapping("/privateChannels")
  public Job setupPrivateChannels(@Parameter(name = "courseId") @RequestParam Long courseId) {
    Course course =
        courseRepository
            .findById(courseId)
            .orElseThrow(() -> new EntityNotFoundException(Course.class, courseId));
    boolean enabled =
        courseOptionRepository
            .findByCourseIdAndOption(courseId, CourseOptions.SLACK_INTEGRATION.name())
            .map(CourseOption::getEnabled)
            .orElse(false);
    if (!enabled) {
      throw new IllegalArgumentException(
          "The course option SLACK_INTEGRATION must be enabled to set up private Slack channels.");
    }
    String token = tokenSecurityService.decrypt(course.getSlackBotToken());
    if (token == null || token.isEmpty()) {
      throw new IllegalArgumentException(NO_TOKEN_MESSAGE);
    }

    SetupPrivateSlackChannelsJob job =
        SetupPrivateSlackChannelsJob.builder()
            .course(course)
            .courseRepository(courseRepository)
            .rosterStudentRepository(rosterStudentRepository)
            .courseStaffRepository(courseStaffRepository)
            .slackService(slackService)
            .tokenSecurityService(tokenSecurityService)
            .build();
    return jobService.runAsJob(job);
  }

  public static final String NO_TOKEN_MESSAGE =
      "No Slack token has been set for this course; enter one on the Settings tab.";

  /** Only these roster students are considered: in particular, not dropped students. */
  public static final List<RosterStatus> ENROLLED_STATUSES =
      List.of(RosterStatus.ROSTER, RosterStatus.MANUAL);

  private List<RosterStudent> enrolledStudents(Long courseId) {
    return rosterStudentRepository
        .findByCourseIdAndRosterStatusInOrderByFirstNameAscLastNameAscIgnoreCase(
            courseId, ENROLLED_STATUSES);
  }

  private static String slackStatus(SlackUser user) {
    if (user.isActivePerson()) {
      return STATUS_ACTIVE;
    }
    return user.getDeleted() ? STATUS_DEACTIVATED : STATUS_INVITED;
  }

  /**
   * @return null if the email belongs to an active Slack user; otherwise the status to report
   */
  private static String missingStatus(Map<String, String> statusByEmail, String email) {
    if (email == null) {
      return STATUS_NOT_IN_SLACK;
    }
    String status = statusByEmail.getOrDefault(canonical(email), STATUS_NOT_IN_SLACK);
    return status.equals(STATUS_ACTIVE) ? null : status;
  }

  private static String canonical(String email) {
    return CanonicalFormConverter.convertToValidEmail(email.strip());
  }

  private List<SlackUser> listSlackUsers(Course course) {
    String token = tokenSecurityService.decrypt(course.getSlackBotToken());
    if (token == null || token.isEmpty()) {
      throw new IllegalArgumentException(NO_TOKEN_MESSAGE);
    }
    return slackService.listUsers(token);
  }

  /**
   * A failed call to Slack maps to a 502/Bad Gateway, with the Slack error code and a message.
   *
   * @param e the exception; its message is the Slack error code
   * @return a map with ok=false, error (Slack error code) and message
   */
  @ExceptionHandler({SlackApiException.class})
  public ResponseEntity<Map<String, Object>> handleSlackApiException(SlackApiException e) {
    Map<String, Object> body = new LinkedHashMap<>();
    body.put("ok", false);
    body.put("error", e.getMessage());
    body.put("message", describeError(e.getMessage()));
    return ResponseEntity.status(HttpStatus.BAD_GATEWAY).body(body);
  }

  /**
   * Masks a token so that only the first four and last four characters are visible. Tokens too
   * short to mask meaningfully (eight characters or fewer) are masked entirely; Slack does not
   * issue tokens that short.
   *
   * @param token the plaintext token
   * @return the masked token, or an empty string if there is no token
   */
  public static String maskToken(String token) {
    if (token == null || token.isEmpty()) {
      return "";
    }
    if (token.length() <= 2 * VISIBLE_TOKEN_CHARS) {
      return "*".repeat(token.length());
    }
    return token.substring(0, VISIBLE_TOKEN_CHARS)
        + "*".repeat(token.length() - 2 * VISIBLE_TOKEN_CHARS)
        + token.substring(token.length() - VISIBLE_TOKEN_CHARS);
  }

  /**
   * Message shown when a valid token could not be encrypted.
   *
   * @param details message from the encryption service, describing the problem with the key
   * @return a human readable message
   */
  public static String encryptionFailedMessage(String details) {
    return "Slack accepted this token, but the server could not encrypt it, so the token was not saved. Ask an administrator to check the TOKEN_ENCRYPTION_KEY environment variable (see docs/slack.md). Details: %s"
        .formatted(details);
  }

  /**
   * Translates a Slack error code into a message suitable for showing to an instructor who has just
   * tried to save a token.
   *
   * @param error error code from Slack, e.g. <code>invalid_auth</code>
   * @return a human readable message
   */
  public static String errorMessage(String error) {
    return describeError(error) + " The token was not saved.";
  }

  /**
   * Translates a Slack error code into a message suitable for showing to an instructor.
   *
   * @param error error code from Slack, e.g. <code>invalid_auth</code>
   * @return a human readable message
   */
  public static String describeError(String error) {
    return switch (String.valueOf(error)) {
      case "invalid_auth", "not_authed" ->
          "Slack rejected this token as invalid. Copy the Bot User OAuth Token (xoxb-...) from your Slack app's OAuth & Permissions page and try again.";
      case "token_revoked", "token_expired", "account_inactive" ->
          "This Slack token has been revoked or is no longer active. Reinstall the Slack app to the workspace to get a new token.";
      case "missing_scope" ->
          "This Slack token is missing a required scope. Add the scope under OAuth & Permissions, reinstall the Slack app to the workspace, and enter the new token.";
      case "ratelimited" ->
          "Slack is limiting requests from this app. Please try again in a minute.";
      case SlackService.SLACK_UNREACHABLE -> "Could not reach Slack. Please try again later.";
      default -> "Slack reported an error (%s).".formatted(error);
    };
  }
}