feat(api): expose balance history (#1641)

* feat(api): expose balance history

* fix(api): address balance history review

* fix(api): address balance history review

* fix(api): tighten balance history docs

* fix(exports): preserve balance chronology

* fix(api): guard nullable balance account type

* test(api): align balances api key helper

* fix(api): use shared pagination clamp

* test(export): set explicit balance flows factor

app/controllers/api/v1/balances_controller.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+class Api::V1::BalancesController < Api::V1::BaseController
+  include Pagy::Backend
+
+  before_action :ensure_read_scope
+  before_action :set_balance, only: :show
+  helper_method :format_money, :money_to_minor_units
+
+  def index
+    balances_query = apply_filters(balances_scope).order(date: :desc, created_at: :desc)
+    @per_page = safe_per_page_param
+
+    @pagy, @balances = pagy(
+      balances_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
+  end
+
+  def show
+    render :show
+  end
+
+  private
+
+    def set_balance
+      raise ActiveRecord::RecordNotFound unless valid_uuid?(params[:id])
+
+      @balance = balances_scope.find(params[:id])
+    end
+
+    def ensure_read_scope
+      authorize_scope!(:read)
+    end
+
+    def balances_scope
+      Balance
+        .joins(:account)
+        .where(accounts: { id: accessible_account_ids })
+        .includes(:account)
+    end
+
+    def accessible_account_ids
+      @accessible_account_ids ||= current_resource_owner.family.accounts.accessible_by(current_resource_owner).select(:id)
+    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(currency: params[:currency].to_s.upcase) if params[:currency].present?
+      query = query.where("balances.date >= ?", parse_date_param(:start_date)) if params[:start_date].present?
+      query = query.where("balances.date <= ?", parse_date_param(:end_date)) if params[:end_date].present?
+      query
+    end
+
+    def format_money(money)
+      money&.format
+    end
+
+    def money_to_minor_units(money)
+      (money.amount * money.currency.minor_unit_conversion).round(0).to_i if money
+    end
+end

app/controllers/api/v1/base_controller.rb

@@ -6,6 +6,8 @@ class Api::V1::BaseController < ApplicationController
   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
 
+  InvalidFilterError = Class.new(StandardError)
+
   # Skip regular session-based authentication for API
   skip_authentication
 
@@ -254,6 +256,12 @@ class Api::V1::BaseController < ApplicationController
       render_json({ error: "bad_request", message: "Required parameters are missing or invalid" }, status: :bad_request)
     end
 
+    def parse_date_param(key)
+      Date.iso8601(params[key].to_s)
+    rescue ArgumentError
+      raise InvalidFilterError, "#{key} must be an ISO 8601 date"
+    end
+
     # Log API access for monitoring and debugging
     def log_api_access
       return unless current_resource_owner