feat(api): expose valuation history index (#1596)

* feat(api): expose valuation history index

* fix(api): hide valuation exception details

* fix(api): reuse eager-loaded valuation entries

* fix(api): tighten valuation index contracts

* fix(api): scope valuation filter errors

* docs(api): nest valuation account filter format

* Fix merge conflict mistakes

---------

Signed-off-by: Juan José Mata <juanjo.mata@gmail.com>
Co-authored-by: Juan José Mata <juanjo.mata@gmail.com>
Co-authored-by: Juan José Mata <jjmata@jjmata.com>

app/controllers/api/v1/valuations_controller.rb

@@ -1,10 +1,47 @@
 # frozen_string_literal: true
 
 class Api::V1::ValuationsController < Api::V1::BaseController
-  before_action :ensure_read_scope, only: [ :show ]
+  include Pagy::Backend
+
+  InvalidFilterError = Class.new(StandardError)
+
+  before_action :ensure_read_scope, only: [ :index, :show ]
   before_action :ensure_write_scope, only: [ :create, :update ]
   before_action :set_valuation, only: [ :show, :update ]
 
+  def index
+    family = current_resource_owner.family
+    accessible_account_ids = family.accounts.accessible_by(current_resource_owner).select(:id)
+    valuations_query = family.entries
+      .where(entryable_type: "Valuation", account_id: accessible_account_ids)
+      .includes(:account, :entryable)
+
+    valuations_query = apply_filters(valuations_query).reverse_chronological
+    @per_page = safe_per_page_param
+
+    @pagy, @entries = pagy(
+      valuations_query,
+      page: safe_page_param,
+      limit: @per_page
+    )
+
+    render :index
+  rescue InvalidFilterError => e
+    render json: {
+      error: "validation_failed",
+      message: e.message,
+      errors: [ e.message ]
+    }, status: :unprocessable_entity
+  rescue => e
+    Rails.logger.error "ValuationsController#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
   rescue => e
@@ -208,6 +245,43 @@ class Api::V1::ValuationsController < Api::V1::BaseController
       authorize_scope!(:write)
     end
 
+    def apply_filters(query)
+      if params[:account_id].present?
+        raise InvalidFilterError, "account_id must be a valid UUID" unless valid_uuid?(params[:account_id])
+
+        query = query.where(account_id: params[:account_id])
+      end
+      query = query.where("entries.date >= ?", parse_date_param(:start_date)) if params[:start_date].present?
+      query = query.where("entries.date <= ?", parse_date_param(:end_date)) if params[:end_date].present?
+      query
+    end
+
+    def parse_date_param(key)
+      Date.iso8601(params[key].to_s)
+    rescue ArgumentError
+      raise InvalidFilterError, "#{key} must be an ISO 8601 date"
+    end
+
+    def valid_uuid?(value)
+      value.to_s.match?(/\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i)
+    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
+
     def valuation_account_id
       params.dig(:valuation, :account_id)
     end