feat(api): expose family exports (#1632)

* feat(api): expose family exports

* fix(api): harden family export review paths

* fix(api): tighten family export review paths

* fix(api): reject invalid family export params

* fix(api): address family export review

* fix(api): share uuid guard for exports

app/controllers/api/v1/base_controller.rb

@@ -3,6 +3,9 @@
 class Api::V1::BaseController < ApplicationController
   include Doorkeeper::Rails::Helpers
 
+  UUID_PATTERN = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i
+  private_constant :UUID_PATTERN
+
   # Skip regular session-based authentication for API
   skip_authentication
 
@@ -209,6 +212,10 @@ class Api::V1::BaseController < ApplicationController
       render json: data, status: status
     end
 
+    def valid_uuid?(value)
+      value.to_s.match?(UUID_PATTERN)
+    end
+
     # Error handlers
     def handle_not_found(exception)
       Rails.logger.warn "API Record Not Found: #{exception.message}"

app/controllers/api/v1/family_exports_controller.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+class Api::V1::FamilyExportsController < Api::V1::BaseController
+  include Pagy::Backend
+
+  before_action :ensure_read_scope, only: [ :index, :show, :download ]
+  before_action :ensure_write_scope, only: [ :create ]
+  before_action :ensure_admin
+  before_action :set_family_export, only: [ :show, :download ]
+
+  def index
+    family_exports_query = current_resource_owner.family
+      .family_exports
+      .with_attached_export_file
+      .ordered
+
+    @per_page = safe_per_page_param
+    @pagy, @family_exports = pagy(
+      family_exports_query,
+      page: safe_page_param,
+      limit: @per_page
+    )
+
+    render :index
+  rescue StandardError => e
+    Rails.logger.error "FamilyExportsController#index error: #{e.message}"
+    Rails.logger.error e.backtrace.join("\n")
+
+    render json: {
+      error: "internal_server_error",
+      message: "An unexpected error occurred"
+    }, status: :internal_server_error
+  end
+
+  def show
+    render :show
+  end
+
+  def create
+    if unsupported_create_params?
+      render json: {
+        error: "invalid_params",
+        message: "Family export creation does not accept request parameters"
+      }, status: :unprocessable_entity
+      return
+    end
+
+    @family_export = current_resource_owner.family.family_exports.create!
+    FamilyDataExportJob.perform_later(@family_export)
+
+    render :show, status: :accepted
+  rescue StandardError => e
+    Rails.logger.error "FamilyExportsController#create error: #{e.message}"
+    Rails.logger.error e.backtrace.join("\n")
+
+    render json: {
+      error: "internal_server_error",
+      message: "An unexpected error occurred"
+    }, status: :internal_server_error
+  end
+
+  def download
+    unless @family_export.downloadable?
+      render json: {
+        error: "export_not_ready",
+        message: "Export is not ready for download"
+      }, status: :conflict
+      return
+    end
+
+    redirect_to rails_blob_url(@family_export.export_file, disposition: "attachment"), allow_other_host: true
+  rescue StandardError => e
+    Rails.logger.error "FamilyExportsController#download error: #{e.message}"
+    Rails.logger.error e.backtrace.join("\n")
+
+    render json: {
+      error: "internal_server_error",
+      message: "An unexpected error occurred"
+    }, status: :internal_server_error
+  end
+
+  private
+
+    def set_family_export
+      raise ActiveRecord::RecordNotFound unless valid_uuid?(params[:id])
+
+      @family_export = current_resource_owner.family.family_exports.find(params[:id])
+    end
+
+    def ensure_read_scope
+      authorize_scope!(:read)
+    end
+
+    def ensure_write_scope
+      authorize_scope!(:write)
+    end
+
+    def ensure_admin
+      return if current_resource_owner.admin?
+
+      render json: {
+        error: "forbidden",
+        message: "Family exports require a family admin"
+      }, status: :forbidden
+    end
+
+    def unsupported_create_params?
+      params.except(:controller, :action, :format).present?
+    end
+
+    def safe_page_param
+      page = params[:page].to_i
+      page > 0 ? page : 1
+    end
+
+    def safe_per_page_param
+      per_page = params[:per_page].to_i
+
+      case per_page
+      when 1..100
+        per_page
+      else
+        25
+      end
+    end
+end

app/controllers/api/v1/recurring_transactions_controller.rb

@@ -3,8 +3,6 @@
 class Api::V1::RecurringTransactionsController < Api::V1::BaseController
   include Pagy::Backend
 
-  UUID_REGEX = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i
-
   before_action :ensure_read_scope, only: %i[index show]
   before_action :ensure_write_scope, only: %i[create update destroy]
   before_action :set_readable_recurring_transaction, only: :show
@@ -211,10 +209,6 @@ class Api::V1::RecurringTransactionsController < Api::V1::BaseController
         raise(ActiveRecord::RecordNotFound, "Merchant not found")
     end
 
-    def valid_uuid?(value)
-      value.to_s.match?(UUID_REGEX)
-    end
-
     def validate_create_write_params(recurring_transaction)
       input = recurring_transaction_input
       recurring_transaction.errors.add(:last_occurrence_date, :blank) if input[:last_occurrence_date].blank?