feat(api): expose family settings (#1645)

* feat(api): expose family settings

* test(api): assert family settings moniker

* test(api): align family settings api key helper

* fix(api): tighten family settings schema

spec/requests/api/v1/family_settings_spec.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'swagger_helper'
+
+RSpec.describe 'API V1 Family Settings', type: :request do
+  let(:family) do
+    Family.create!(
+      name: 'API Family',
+      currency: 'USD',
+      locale: 'en',
+      date_format: '%m-%d-%Y',
+      country: 'US',
+      timezone: 'America/New_York',
+      month_start_day: 1
+    )
+  end
+
+  let(:user) do
+    family.users.create!(
+      email: 'api-user@example.com',
+      password: 'password123',
+      password_confirmation: 'password123'
+    )
+  end
+
+  let(:api_key) do
+    key = ApiKey.generate_secure_key
+    ApiKey.create!(
+      user: user,
+      name: 'API Docs Key',
+      key: key,
+      display_key: key,
+      scopes: %w[read_write],
+      source: 'web'
+    )
+  end
+
+  let(:api_key_without_read_scope) do
+    key = ApiKey.generate_secure_key
+    # Empty scopes intentionally bypass validation so the 403 response can be documented.
+    ApiKey.new(
+      user: user,
+      name: 'No Read Docs Key',
+      key: key,
+      display_key: key,
+      scopes: [],
+      source: 'web'
+    ).tap { |api_key| api_key.save!(validate: false) }
+  end
+
+  let(:'X-Api-Key') { api_key.plain_key }
+
+  path '/api/v1/family_settings' do
+    get 'Retrieve family settings' do
+      description 'Retrieve a read-only snapshot of non-secret family configuration.'
+      tags 'Family Settings'
+      security [ { apiKeyAuth: [] } ]
+      produces 'application/json'
+
+      response '200', 'family settings retrieved' do
+        schema '$ref' => '#/components/schemas/FamilySettings'
+
+        run_test!
+      end
+
+      response '401', 'unauthorized' do
+        schema '$ref' => '#/components/schemas/ErrorResponse'
+
+        let(:'X-Api-Key') { nil }
+
+        run_test!
+      end
+
+      response '403', 'insufficient scope' do
+        schema '$ref' => '#/components/schemas/ErrorResponse'
+
+        let(:'X-Api-Key') { api_key_without_read_scope.plain_key }
+
+        run_test!
+      end
+    end
+  end
+end

spec/swagger_helper.rb

@@ -274,6 +274,29 @@ RSpec.configure do |config|
               pagination: { '$ref' => '#/components/schemas/Pagination' }
             }
           },
+          FamilySettings: {
+            type: :object,
+            required: %w[id currency locale date_format month_start_day moniker default_account_sharing custom_enabled_currencies enabled_currencies created_at updated_at],
+            properties: {
+              id: { type: :string, format: :uuid },
+              name: { type: :string, nullable: true },
+              currency: { type: :string },
+              locale: { type: :string },
+              date_format: { type: :string },
+              country: { type: :string, nullable: true },
+              timezone: { type: :string, nullable: true },
+              month_start_day: { type: :integer, minimum: 1, maximum: 28 },
+              moniker: { type: :string, enum: Family::MONIKERS },
+              default_account_sharing: { type: :string, enum: %w[shared private] },
+              custom_enabled_currencies: { type: :boolean },
+              enabled_currencies: {
+                type: :array,
+                items: { type: :string }
+              },
+              created_at: { type: :string, format: :'date-time' },
+              updated_at: { type: :string, format: :'date-time' }
+            }
+          },
           Category: {
             type: :object,
             required: %w[id name color icon],