feat(api): expose complete account export state (#1597)

* feat(api): expose complete account export state

* fix(api): handle malformed account identifiers

* fix(api): tighten account export contracts

* fix(api): correct account id OpenAPI format

* fix(api): tighten account docs auth contracts

* docs(api): document balance sheet auth errors

* docs(api): clarify account scope fixture

spec/requests/api/v1/accounts_spec.rb

@@ -31,6 +31,19 @@ RSpec.describe 'API V1 Accounts', type: :request do
     )
   end
 
+  let(:api_key_without_read_scope) do
+    key = ApiKey.generate_secure_key
+    # Valid persisted API keys can only be read/read_write; this intentionally
+    # bypasses validations to document the runtime insufficient-scope response.
+    ApiKey.new(
+      user: user,
+      name: 'No Read Docs Key',
+      key: key,
+      scopes: %w[write],
+      source: 'web'
+    ).tap { |api_key| api_key.save!(validate: false) }
+  end
+
   let(:'X-Api-Key') { api_key.plain_key }
 
   let!(:checking_account) do
@@ -72,6 +85,8 @@ RSpec.describe 'API V1 Accounts', type: :request do
                 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: :include_disabled, in: :query, type: :boolean, required: false,
+                description: 'Include disabled accounts in the response. Defaults to false.'
 
       response '200', 'accounts listed' do
         schema '$ref' => '#/components/schemas/AccountCollection'
@@ -89,4 +104,51 @@ RSpec.describe 'API V1 Accounts', type: :request do
       end
     end
   end
+
+  path '/api/v1/accounts/{id}' do
+    parameter name: :id, in: :path, required: true, description: 'Account ID',
+              schema: { type: :string, format: :uuid }
+
+    get 'Retrieve an account' do
+      tags 'Accounts'
+      security [ { apiKeyAuth: [] } ]
+      produces 'application/json'
+      parameter name: :include_disabled, in: :query, type: :boolean, required: false,
+                description: 'Allow retrieving a disabled account. Defaults to false.'
+
+      let(:id) { checking_account.id }
+
+      response '200', 'account retrieved' do
+        schema '$ref' => '#/components/schemas/AccountDetail'
+
+        run_test!
+      end
+
+      response '401', 'unauthorized' do
+        schema '$ref' => '#/components/schemas/ErrorResponse'
+
+        let(:id) { checking_account.id }
+        let(:'X-Api-Key') { nil }
+
+        run_test!
+      end
+
+      response '403', 'insufficient scope' do
+        schema '$ref' => '#/components/schemas/ErrorResponse'
+
+        let(:id) { checking_account.id }
+        let(:'X-Api-Key') { api_key_without_read_scope.plain_key }
+
+        run_test!
+      end
+
+      response '404', 'account not found' do
+        schema '$ref' => '#/components/schemas/ErrorResponse'
+
+        let(:id) { SecureRandom.uuid }
+
+        run_test!
+      end
+    end
+  end
 end

spec/requests/api/v1/auth_spec.rb

@@ -261,7 +261,10 @@ RSpec.describe 'API V1 Auth', type: :request do
       end
 
       response '401', 'invalid credentials or expired linking code' do
-        schema '$ref' => '#/components/schemas/ErrorResponse'
+        schema oneOf: [
+          { '$ref' => '#/components/schemas/ErrorResponse' },
+          { '$ref' => '#/components/schemas/MfaRequiredResponse' }
+        ]
         run_test!
       end
     end

spec/requests/api/v1/balance_sheet_spec.rb

@@ -48,6 +48,8 @@ RSpec.describe 'API V1 Balance Sheet', type: :request do
       end
 
       response '401', 'unauthorized' do
+        schema '$ref' => '#/components/schemas/ErrorResponse'
+
         let(:'X-Api-Key') { 'invalid-key' }
 
         run_test!