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