add request_changes endpoint

- submitter is found by slug and authorized

app/controllers/api/submitters_request_changes_controller.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Api
+  class SubmittersRequestChangesController < ApiBaseController
+    before_action :load_submitter
+
+    def request_changes
+      @submitter.update!(changes_requested_at: Time.current, completed_at: nil) unless @submitter.changes_requested_at?
+
+      render json: Submitters::SerializeForApi.call(@submitter), status: :ok
+    end
+
+    private
+
+    def load_submitter
+      @submitter = Submitter.find_by!(slug: params[:slug])
+      authorize! :read, @submitter
+    end
+  end
+end

config/routes.rb

@@ -34,6 +34,11 @@ Rails.application.routes.draw do
     resources :submitter_email_clicks, only: %i[create]
     resources :submitter_form_views, only: %i[create]
     resources :submitters, only: %i[index show update]
+    resources :submitters, only: %i[], param: 'slug' do
+      member do
+        post :request_changes, controller: 'submitters_request_changes'
+      end
+    end
     resources :submissions, only: %i[index show create destroy] do
       resources :documents, only: %i[index], controller: 'submission_documents'
       resource :signed_document_url, only: %i[show]

spec/requests/api_submitters_request_changes_spec.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+describe 'API Submitters Request Changes' do
+  let(:account) { create(:account) }
+  let(:user) { create(:user, account:) }
+  let(:template) { create(:template, account:, author: user) }
+  let(:submission) { create(:submission, template:, account:, created_by_user: user) }
+  let(:submitter) do
+    create(
+      :submitter,
+      submission:,
+      account:,
+      completed_at: 1.hour.ago,
+      uuid: template.submitters.first['uuid']
+    )
+  end
+
+  describe 'POST /api/submitters/:slug/request_changes' do
+    context 'when authenticated with a valid token' do
+      it 'clears completed_at and sets changes_requested_at' do
+        expect do
+          post "/api/submitters/#{submitter.slug}/request_changes",
+               headers: { 'x-auth-token': user.access_token.token }
+        end.to change { submitter.reload.changes_requested_at }.from(nil)
+           .and change { submitter.reload.completed_at }.to(nil)
+
+        expect(response).to have_http_status(:ok)
+      end
+
+      it 'is idempotent when changes already requested' do
+        submitter.update!(changes_requested_at: 1.hour.ago)
+
+        expect do
+          post "/api/submitters/#{submitter.slug}/request_changes",
+               headers: { 'x-auth-token': user.access_token.token }
+        end.not_to(change { submitter.reload.changes_requested_at })
+
+        expect(response).to have_http_status(:ok)
+      end
+    end
+
+    context 'when authenticated with a different account token' do
+      let(:other_user) { create(:user, account: create(:account)) }
+
+      it 'returns forbidden' do
+        post "/api/submitters/#{submitter.slug}/request_changes",
+             headers: { 'x-auth-token': other_user.access_token.token }
+
+        expect(response).to have_http_status(:forbidden)
+      end
+    end
+
+    context 'when unauthenticated' do
+      it 'returns unauthorized' do
+        post "/api/submitters/#{submitter.slug}/request_changes"
+
+        expect(response).to have_http_status(:unauthorized)
+      end
+    end
+  end
+end