feat(api): expose budget state (#1640)

* feat(api): expose budget state

* fix(api): guard malformed budget ids

* fix(api): address budget state review

* fix(api): address budget state review

* fix(api): document budget id formats

* fix(api): align budget category docs auth

* fix(api): lighten budget category index payload

* fix(api): use shared pagination clamp

* fix(api): centralize budget filter handling

app/controllers/api/v1/accounts_controller.rb

@@ -69,24 +69,4 @@ class Api::V1::AccountsController < Api::V1::BaseController
     def include_disabled_accounts?
       ActiveModel::Type::Boolean.new.cast(params[:include_disabled])
     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
 end

app/controllers/api/v1/base_controller.rb

@@ -35,6 +35,7 @@ class Api::V1::BaseController < ApplicationController
   rescue_from ActiveRecord::RecordNotFound, with: :handle_not_found
   rescue_from Doorkeeper::Errors::DoorkeeperError, with: :handle_unauthorized
   rescue_from ActionController::ParameterMissing, with: :handle_bad_request
+  rescue_from InvalidFilterError, with: :handle_invalid_filter
 
   private
 
@@ -256,6 +257,10 @@ class Api::V1::BaseController < ApplicationController
       render_json({ error: "bad_request", message: "Required parameters are missing or invalid" }, status: :bad_request)
     end
 
+    def handle_invalid_filter(exception)
+      render_validation_error(exception.message)
+    end
+
     def parse_date_param(key)
       Date.iso8601(params[key].to_s)
     rescue ArgumentError

app/controllers/api/v1/budget_categories_controller.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+class Api::V1::BudgetCategoriesController < Api::V1::BaseController
+  include Pagy::Backend
+
+  before_action :ensure_read_scope
+  before_action :set_budget_category, only: :show
+
+  def index
+    budget_categories_query = apply_filters(budget_categories_scope)
+      .order("budgets.start_date DESC", "categories.name ASC")
+    @per_page = safe_per_page_param
+
+    @pagy, @budget_categories = pagy(
+      budget_categories_query,
+      page: safe_page_param,
+      limit: @per_page
+    )
+
+    render :index
+  end
+
+  def show
+    render :show
+  end
+
+  private
+
+    def set_budget_category
+      raise ActiveRecord::RecordNotFound unless valid_uuid?(params[:id])
+
+      @budget_category = budget_categories_scope.find(params[:id])
+    end
+
+    def ensure_read_scope
+      authorize_scope!(:read)
+    end
+
+    def budget_categories_scope
+      BudgetCategory
+        .joins(:budget, :category)
+        .where(budgets: { family_id: current_resource_owner.family_id })
+        .includes({ budget: { budget_categories: { category: :parent } } }, category: :parent)
+    end
+
+    def apply_filters(query)
+      if params[:budget_id].present?
+        raise InvalidFilterError, "budget_id must be a valid UUID" unless valid_uuid?(params[:budget_id])
+
+        query = query.where(budget_id: params[:budget_id])
+      end
+
+      if params[:category_id].present?
+        raise InvalidFilterError, "category_id must be a valid UUID" unless valid_uuid?(params[:category_id])
+
+        query = query.where(category_id: params[:category_id])
+      end
+
+      query = query.where("budgets.start_date >= ?", parse_date_param(:start_date)) if params[:start_date].present?
+      query = query.where("budgets.end_date <= ?", parse_date_param(:end_date)) if params[:end_date].present?
+      query
+    end
+end

app/controllers/api/v1/budgets_controller.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+class Api::V1::BudgetsController < Api::V1::BaseController
+  include Pagy::Backend
+
+  before_action :ensure_read_scope
+  before_action :set_budget, only: :show
+
+  def index
+    budgets_query = apply_filters(budgets_scope).order(start_date: :desc)
+    @per_page = safe_per_page_param
+
+    @pagy, @budgets = pagy(
+      budgets_query,
+      page: safe_page_param,
+      limit: @per_page
+    )
+
+    render :index
+  end
+
+  def show
+    render :show
+  end
+
+  private
+
+    def set_budget
+      raise ActiveRecord::RecordNotFound unless valid_uuid?(params[:id])
+
+      @budget = budgets_scope.find(params[:id])
+    end
+
+    def ensure_read_scope
+      authorize_scope!(:read)
+    end
+
+    def apply_filters(query)
+      query = query.where("budgets.start_date >= ?", parse_date_param(:start_date)) if params[:start_date].present?
+      query = query.where("budgets.end_date <= ?", parse_date_param(:end_date)) if params[:end_date].present?
+      query
+    end
+
+    def budgets_scope
+      current_resource_owner.family.budgets.includes(budget_categories: :category)
+    end
+end