Add categories endpoint in API (#460)

* Add categories endpoint in API

* FIX eager load parent and subcategories associations

* FIX update specs to match

* Add rswag spec

* FIX openapi spec

* FIX final warns

spec/requests/api/v1/categories_spec.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'API V1 Categories', type: :request do
+  let(:family) do
+    Family.create!(
+      name: 'API Family',
+      currency: 'USD',
+      locale: 'en',
+      date_format: '%m-%d-%Y'
+    )
+  end
+
+  let(:user) do
+    family.users.create!(
+      email: 'api-user@example.com',
+      password: 'password123',
+      password_confirmation: 'password123'
+    )
+  end
+
+  let(:oauth_application) do
+    Doorkeeper::Application.create!(
+      name: 'API Docs',
+      redirect_uri: 'https://example.com/callback',
+      scopes: 'read read_write'
+    )
+  end
+
+  let(:access_token) do
+    Doorkeeper::AccessToken.create!(
+      application: oauth_application,
+      resource_owner_id: user.id,
+      scopes: 'read_write',
+      expires_in: 2.hours,
+      token: SecureRandom.hex(32)
+    )
+  end
+
+  let(:Authorization) { "Bearer #{access_token.token}" }
+
+  let!(:parent_category) do
+    family.categories.create!(
+      name: 'Food & Drink',
+      classification: 'expense',
+      color: '#f97316',
+      lucide_icon: 'utensils'
+    )
+  end
+
+  let!(:subcategory) do
+    family.categories.create!(
+      name: 'Restaurants',
+      classification: 'expense',
+      color: '#f97316',
+      lucide_icon: 'utensils',
+      parent: parent_category
+    )
+  end
+
+  let!(:income_category) do
+    family.categories.create!(
+      name: 'Salary',
+      classification: 'income',
+      color: '#22c55e',
+      lucide_icon: 'circle-dollar-sign'
+    )
+  end
+
+  path '/api/v1/categories' do
+    get 'List categories' do
+      tags 'Categories'
+      security [ { bearerAuth: [] } ]
+      produces 'application/json'
+      parameter name: :Authorization, in: :header, required: true, schema: { type: :string },
+                description: 'Bearer token with read scope'
+      parameter name: :page, in: :query, type: :integer, required: false,
+                description: 'Page number (default: 1)'
+      parameter name: :per_page, in: :query, type: :integer, required: false,
+                description: 'Items per page (default: 25, max: 100)'
+      parameter name: :classification, in: :query, required: false,
+                description: 'Filter by classification (income or expense)',
+                schema: { type: :string, enum: %w[income expense] }
+      parameter name: :roots_only, in: :query, required: false,
+                description: 'Return only root categories (no parent)',
+                schema: { type: :boolean }
+      parameter name: :parent_id, in: :query, required: false,
+                description: 'Filter by parent category ID',
+                schema: { type: :string, format: :uuid }
+
+      response '200', 'categories listed' do
+        schema '$ref' => '#/components/schemas/CategoryCollection'
+
+        run_test! do |response|
+          payload = JSON.parse(response.body)
+          expect(payload.fetch('categories')).to be_present
+          expect(payload.fetch('pagination')).to include('page', 'per_page', 'total_count', 'total_pages')
+        end
+      end
+
+      response '200', 'categories filtered by classification' do
+        schema '$ref' => '#/components/schemas/CategoryCollection'
+
+        let(:classification) { 'expense' }
+
+        run_test! do |response|
+          payload = JSON.parse(response.body)
+          payload.fetch('categories').each do |category|
+            expect(category.fetch('classification')).to eq('expense')
+          end
+        end
+      end
+
+      response '200', 'root categories only' do
+        schema '$ref' => '#/components/schemas/CategoryCollection'
+
+        let(:roots_only) { true }
+
+        run_test! do |response|
+          payload = JSON.parse(response.body)
+          payload.fetch('categories').each do |category|
+            expect(category.fetch('parent')).to be_nil
+          end
+        end
+      end
+
+      response '200', 'categories filtered by parent' do
+        schema '$ref' => '#/components/schemas/CategoryCollection'
+
+        let(:parent_id) { parent_category.id }
+
+        run_test! do |response|
+          payload = JSON.parse(response.body)
+          payload.fetch('categories').each do |category|
+            expect(category.dig('parent', 'id')).to eq(parent_category.id)
+          end
+        end
+      end
+    end
+  end
+
+  path '/api/v1/categories/{id}' do
+    parameter name: :Authorization, in: :header, required: true, schema: { type: :string },
+              description: 'Bearer token with read scope'
+    parameter name: :id, in: :path, type: :string, required: true, description: 'Category ID'
+
+    get 'Retrieve a category' do
+      tags 'Categories'
+      security [ { bearerAuth: [] } ]
+      produces 'application/json'
+
+      let(:id) { parent_category.id }
+
+      response '200', 'category retrieved' do
+        schema '$ref' => '#/components/schemas/CategoryDetail'
+
+        run_test! do |response|
+          payload = JSON.parse(response.body)
+          expect(payload.fetch('id')).to eq(parent_category.id)
+          expect(payload.fetch('name')).to eq('Food & Drink')
+          expect(payload.fetch('classification')).to eq('expense')
+          expect(payload.fetch('subcategories_count')).to eq(1)
+        end
+      end
+
+      response '200', 'subcategory retrieved with parent' do
+        schema '$ref' => '#/components/schemas/CategoryDetail'
+
+        let(:id) { subcategory.id }
+
+        run_test! do |response|
+          payload = JSON.parse(response.body)
+          expect(payload.fetch('id')).to eq(subcategory.id)
+          expect(payload.fetch('name')).to eq('Restaurants')
+          expect(payload.dig('parent', 'id')).to eq(parent_category.id)
+          expect(payload.dig('parent', 'name')).to eq('Food & Drink')
+        end
+      end
+
+      response '404', 'category not found' do
+        schema '$ref' => '#/components/schemas/ErrorResponse'
+
+        let(:id) { SecureRandom.uuid }
+
+        run_test!
+      end
+    end
+  end
+end

spec/requests/api/v1/chats_spec.rb

@@ -126,10 +126,10 @@ RSpec.describe 'API V1 Chats', type: :request do
         type: :object,
         properties: {
           title: { type: :string, example: 'Monthly budget review' },
-          message: { type: :string, description: 'Initial message in the chat' },
+          message: { type: :string, description: 'Optional initial message in the chat' },
           model: { type: :string, description: 'Optional OpenAI model identifier' }
         },
-        required: %w[title message]
+        required: %w[title]
       }
 
       let(:chat_params) do

spec/requests/api/v1/transactions_spec.rb

@@ -110,18 +110,33 @@ RSpec.describe 'API V1 Transactions', type: :request do
                 description: 'Filter by category ID'
       parameter name: :merchant_id, in: :query, type: :string, required: false,
                 description: 'Filter by merchant ID'
-      parameter name: :start_date, in: :query, type: :string, format: :date, required: false,
-                description: 'Filter transactions from this date'
-      parameter name: :end_date, in: :query, type: :string, format: :date, required: false,
-                description: 'Filter transactions until this date'
+      parameter name: :start_date, in: :query, required: false,
+                description: 'Filter transactions from this date',
+                schema: { type: :string, format: :date }
+      parameter name: :end_date, in: :query, required: false,
+                description: 'Filter transactions until this date',
+                schema: { type: :string, format: :date }
       parameter name: :min_amount, in: :query, type: :number, required: false,
                 description: 'Filter by minimum amount'
       parameter name: :max_amount, in: :query, type: :number, required: false,
                 description: 'Filter by maximum amount'
-      parameter name: :type, in: :query, type: :string, enum: %w[income expense], required: false,
-                description: 'Filter by transaction type'
+      parameter name: :type, in: :query, required: false,
+                description: 'Filter by transaction type',
+                schema: { type: :string, enum: %w[income expense] }
       parameter name: :search, in: :query, type: :string, required: false,
                 description: 'Search by name, notes, or merchant name'
+      parameter name: :account_ids, in: :query, required: false,
+                description: 'Filter by multiple account IDs',
+                schema: { type: :array, items: { type: :string } }
+      parameter name: :category_ids, in: :query, required: false,
+                description: 'Filter by multiple category IDs',
+                schema: { type: :array, items: { type: :string } }
+      parameter name: :merchant_ids, in: :query, required: false,
+                description: 'Filter by multiple merchant IDs',
+                schema: { type: :array, items: { type: :string } }
+      parameter name: :tag_ids, in: :query, required: false,
+                description: 'Filter by tag IDs',
+                schema: { type: :array, items: { type: :string } }
 
       response '200', 'transactions listed' do
         schema '$ref' => '#/components/schemas/TransactionCollection'
@@ -174,6 +189,7 @@ RSpec.describe 'API V1 Transactions', type: :request do
               date: { type: :string, format: :date, description: 'Transaction date' },
               amount: { type: :number, description: 'Transaction amount' },
               name: { type: :string, description: 'Transaction name/description' },
+              description: { type: :string, description: 'Alternative to name field' },
               notes: { type: :string, description: 'Additional notes' },
               currency: { type: :string, description: 'Currency code (defaults to family currency)' },
               category_id: { type: :string, format: :uuid, description: 'Category ID' },
@@ -294,7 +310,9 @@ RSpec.describe 'API V1 Transactions', type: :request do
               date: { type: :string, format: :date },
               amount: { type: :number },
               name: { type: :string },
+              description: { type: :string, description: 'Alternative to name field' },
               notes: { type: :string },
+              currency: { type: :string, description: 'Currency code' },
               category_id: { type: :string, format: :uuid },
               merchant_id: { type: :string, format: :uuid },
               nature: { type: :string, enum: %w[income expense inflow outflow] },