Add /api/join endpoint for student class enrollment

Add the student-facing half of the join-code flow: a JSON API the
frontend can call to look up a class from its join code and enroll
the current user. Mirrors the teacher_invitations pattern — backend
is JSON-only, the frontend owns the public URL the user lands on.

GET /api/join/:join_code is unauthenticated and returns
{ status, school, school_class } where status is one of
unauthenticated, joinable, already_member, wrong_school, or
domain_mismatch. The frontend uses status to decide what to show.

POST /api/join/:join_code requires auth and performs enrollment.
On success or for already_member it returns
{ redirect_url } (a locale-less path so the frontend can prepend
the user's current locale); on a forbidden status it returns 403
with the status as the error. Membership creation is idempotent.

The endpoint normalises join codes by uppercasing and stripping
non-alphanumerics, so hyphenated forms like BAFA-1234 from
copy-and-pasted share links resolve to the canonical BAFA1234.

Author: fspeirs

app/controllers/api/join_controller.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Api
+  class JoinController < ApiController
+    before_action :authorize_user, only: :create
+    before_action :find_school_and_class
+
+    def show
+      render json: payload(status: show_status), status: :ok
+    end
+
+    def create
+      case action_status
+      when :wrong_school, :domain_mismatch, :not_a_student
+        render json: { error: action_status.to_s }, status: :forbidden
+      when :already_member
+        render json: { redirect_url: class_redirect_path }, status: :ok
+      else
+        add_user_to_school_and_class
+        render json: { redirect_url: class_redirect_path }, status: :ok
+      end
+    end
+
+    private
+
+    def find_school_and_class
+      normalized = params[:join_code].to_s.upcase.gsub(/[^A-Z0-9]/, '')
+      @school_class = SchoolClass.find_by!(join_code: normalized)
+      @school = @school_class.school
+    end
+
+    def show_status
+      return :unauthenticated unless current_user
+
+      action_status
+    end
+
+    def action_status
+      @action_status ||= compute_action_status
+    end
+
+    def compute_action_status
+      return :already_member if user_is_member_of_class?
+      return :joinable if user_is_student_of_school?
+      return :not_a_student if user_has_non_student_role?
+      return :wrong_school if user_in_different_school?
+      return :domain_mismatch unless @school.valid_email?(current_user.email)
+
+      :joinable
+    end
+
+    def payload(status:)
+      {
+        status: status.to_s,
+        school: { code: @school.code, name: @school.name },
+        school_class: { code: @school_class.code, name: @school_class.name }
+      }
+    end
+
+    def class_redirect_path
+      "/school/#{@school.code}/class/#{@school_class.code}"
+    end
+
+    def user_is_member_of_class?
+      ClassStudent.exists?(school_class: @school_class, student_id: current_user.id)
+    end
+
+    def user_is_student_of_school?
+      Role.exists?(school: @school, user_id: current_user.id, role: Role.roles[:student])
+    end
+
+    def user_has_non_student_role?
+      Role.where(user_id: current_user.id).where.not(role: Role.roles[:student]).exists?
+    end
+
+    def user_in_different_school?
+      Role.where(user_id: current_user.id).where.not(school_id: @school.id).exists?
+    end
+
+    def add_user_to_school_and_class
+      Role.create!(school: @school, user_id: current_user.id, role: :student) unless Role.exists?(school: @school, user_id: current_user.id)
+      ClassStudent.create!(school_class: @school_class, student_id: current_user.id)
+    end
+  end
+end

config/routes.rb

@@ -101,6 +101,9 @@
 
     resources :profile_auth_check, only: %i[index]
     resources :subscriptions, only: %i[create]
+
+    get  '/join/:join_code', to: 'join#show'
+    post '/join/:join_code', to: 'join#create'
   end
 
   resource :github_webhooks, only: :create, defaults: { formats: :json }

spec/requests/join_controller_spec.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+
+RSpec.describe 'Join endpoint' do
+  let(:school) { create(:school, code: '12-34-56') }
+  let(:school_class) { create(:school_class, school:, join_code: 'BAFA2345') }
+  let(:student) { create(:user, email: 'student@example.edu') }
+  let(:headers) { { Authorization: UserProfileMock::TOKEN } }
+
+  before do
+    SchoolEmailDomain.create!(school:, domain: 'example.edu')
+  end
+
+  describe 'GET /api/join/:join_code' do
+    it 'responds with 404 when the join code does not exist' do
+      get '/api/join/INVALID123'
+      expect(response).to have_http_status(:not_found)
+    end
+
+    it 'normalizes the join code by stripping non-alphanumerics' do
+      school_class # force creation before the request
+
+      get '/api/join/BAFA-2345'
+
+      expect(response).to have_http_status(:ok)
+      data = JSON.parse(response.body, symbolize_names: true)
+      expect(data[:school_class][:code]).to eq(school_class.code)
+    end
+
+    context 'when the user is not authenticated' do
+      it 'returns status: unauthenticated with school and class details' do
+        get "/api/join/#{school_class.join_code}"
+
+        expect(response).to have_http_status(:ok)
+        data = JSON.parse(response.body, symbolize_names: true)
+        expect(data[:status]).to eq('unauthenticated')
+        expect(data[:school]).to include(code: school.code, name: school.name)
+        expect(data[:school_class]).to include(code: school_class.code, name: school_class.name)
+      end
+    end
+
+    context 'when the user is authenticated' do
+      before { authenticated_in_hydra_as(student) }
+
+      it 'returns status: joinable when the user can join' do
+        get "/api/join/#{school_class.join_code}", headers: headers
+
+        data = JSON.parse(response.body, symbolize_names: true)
+        expect(data[:status]).to eq('joinable')
+      end
+
+      it 'returns status: already_member when the user is already in the class' do
+        create(:student_role, school:, user_id: student.id)
+        ClassStudent.create!(school_class:, student_id: student.id)
+
+        get "/api/join/#{school_class.join_code}", headers: headers
+
+        data = JSON.parse(response.body, symbolize_names: true)
+        expect(data[:status]).to eq('already_member')
+      end
+
+      it 'returns status: wrong_school when the user belongs to a different school' do
+        other_school = create(:school)
+        create(:student_role, school: other_school, user_id: student.id)
+
+        get "/api/join/#{school_class.join_code}", headers: headers
+
+        data = JSON.parse(response.body, symbolize_names: true)
+        expect(data[:status]).to eq('wrong_school')
+      end
+
+      it 'returns status: not_a_student when the user is a teacher of this school' do
+        create(:teacher_role, school:, user_id: student.id)
+
+        get "/api/join/#{school_class.join_code}", headers: headers
+
+        data = JSON.parse(response.body, symbolize_names: true)
+        expect(data[:status]).to eq('not_a_student')
+      end
+
+      it 'returns status: not_a_student when the user is an owner of this school' do
+        create(:owner_role, school:, user_id: student.id)
+
+        get "/api/join/#{school_class.join_code}", headers: headers
+
+        data = JSON.parse(response.body, symbolize_names: true)
+        expect(data[:status]).to eq('not_a_student')
+      end
+
+      it 'returns status: not_a_student for a teacher of a different school (not wrong_school)' do
+        other_school = create(:school)
+        create(:teacher_role, school: other_school, user_id: student.id)
+
+        get "/api/join/#{school_class.join_code}", headers: headers
+
+        data = JSON.parse(response.body, symbolize_names: true)
+        expect(data[:status]).to eq('not_a_student')
+      end
+
+      context 'when the email domain is not registered for the school' do
+        let(:student) { create(:user, email: 'student@other.edu') }
+
+        it 'returns status: domain_mismatch' do
+          get "/api/join/#{school_class.join_code}", headers: headers
+
+          data = JSON.parse(response.body, symbolize_names: true)
+          expect(data[:status]).to eq('domain_mismatch')
+        end
+
+        it 'returns status: joinable when the user is already a student of the school' do
+          create(:student_role, school:, user_id: student.id)
+
+          get "/api/join/#{school_class.join_code}", headers: headers
+
+          data = JSON.parse(response.body, symbolize_names: true)
+          expect(data[:status]).to eq('joinable')
+        end
+      end
+    end
+  end
+
+  describe 'POST /api/join/:join_code' do
+    context 'when the user is not authenticated' do
+      it 'responds with 401' do
+        post "/api/join/#{school_class.join_code}"
+        expect(response).to have_http_status(:unauthorized)
+      end
+    end
+
+    context 'when the user is authenticated' do
+      before { authenticated_in_hydra_as(student) }
+
+      it 'adds the user to the school and class and returns a redirect URL' do
+        expect do
+          post "/api/join/#{school_class.join_code}", headers: headers
+        end.to change(ClassStudent, :count).by(1).and change(Role, :count).by(1)
+
+        expect(response).to have_http_status(:ok)
+        data = JSON.parse(response.body, symbolize_names: true)
+        expect(data[:redirect_url]).to eq("/school/#{school.code}/class/#{school_class.code}")
+
+        created_role = Role.find_by(user_id: student.id, school:)
+        expect(created_role.role).to eq('student')
+      end
+
+      it 'is idempotent when the user is already in the class' do
+        create(:student_role, school:, user_id: student.id)
+        ClassStudent.create!(school_class:, student_id: student.id)
+
+        expect do
+          post "/api/join/#{school_class.join_code}", headers: headers
+        end.not_to change(ClassStudent, :count)
+
+        expect(response).to have_http_status(:ok)
+        data = JSON.parse(response.body, symbolize_names: true)
+        expect(data[:redirect_url]).to eq("/school/#{school.code}/class/#{school_class.code}")
+      end
+
+      it 'does not duplicate the school role if the user is already in the school' do
+        create(:student_role, school:, user_id: student.id)
+
+        expect do
+          post "/api/join/#{school_class.join_code}", headers: headers
+        end.to change(ClassStudent, :count).by(1)
+
+        expect(Role.where(user_id: student.id, school:).count).to eq(1)
+      end
+
+      it 'responds with 403 wrong_school when the user belongs to a different school' do
+        other_school = create(:school)
+        create(:student_role, school: other_school, user_id: student.id)
+
+        post "/api/join/#{school_class.join_code}", headers: headers
+
+        expect(response).to have_http_status(:forbidden)
+        data = JSON.parse(response.body, symbolize_names: true)
+        expect(data[:error]).to eq('wrong_school')
+      end
+
+      context 'when the email domain is not registered for the school' do
+        let(:student) { create(:user, email: 'student@other.edu') }
+
+        it 'responds with 403 domain_mismatch and does not enroll the user' do
+          expect do
+            post "/api/join/#{school_class.join_code}", headers: headers
+          end.not_to change(ClassStudent, :count)
+
+          expect(response).to have_http_status(:forbidden)
+          data = JSON.parse(response.body, symbolize_names: true)
+          expect(data[:error]).to eq('domain_mismatch')
+        end
+
+        it 'enrolls the user when they are already a student of the school' do
+          create(:student_role, school:, user_id: student.id)
+
+          expect do
+            post "/api/join/#{school_class.join_code}", headers: headers
+          end.to change(ClassStudent, :count).by(1)
+
+          expect(response).to have_http_status(:ok)
+          data = JSON.parse(response.body, symbolize_names: true)
+          expect(data[:redirect_url]).to eq("/school/#{school.code}/class/#{school_class.code}")
+        end
+      end
+
+      it 'responds with 403 not_a_student when the user is a teacher of the school' do
+        create(:teacher_role, school:, user_id: student.id)
+
+        expect do
+          post "/api/join/#{school_class.join_code}", headers: headers
+        end.not_to change(ClassStudent, :count)
+
+        expect(response).to have_http_status(:forbidden)
+        data = JSON.parse(response.body, symbolize_names: true)
+        expect(data[:error]).to eq('not_a_student')
+      end
+
+      it 'responds with 403 not_a_student when the user is an owner of the school' do
+        create(:owner_role, school:, user_id: student.id)
+
+        post "/api/join/#{school_class.join_code}", headers: headers
+
+        expect(response).to have_http_status(:forbidden)
+        data = JSON.parse(response.body, symbolize_names: true)
+        expect(data[:error]).to eq('not_a_student')
+      end
+
+      it 'responds with 404 when the join code does not exist' do
+        post '/api/join/INVALID123', headers: headers
+        expect(response).to have_http_status(:not_found)
+      end
+    end
+  end
+end