feat(api): expose family exports (#1632)

* feat(api): expose family exports

* fix(api): harden family export review paths

* fix(api): tighten family export review paths

* fix(api): reject invalid family export params

* fix(api): address family export review

* fix(api): share uuid guard for exports

spec/requests/api/v1/family_exports_spec.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require "swagger_helper"
+
+RSpec.describe "Api::V1::FamilyExports", type: :request do
+  let(:user) { users(:family_admin) }
+  let(:api_key) do
+    key = ApiKey.generate_secure_key
+    ApiKey.create!(
+      user: user,
+      name: "API Docs Key",
+      key: key,
+      scopes: %w[read_write],
+      source: "web"
+    )
+  end
+  let(:'X-Api-Key') { api_key.plain_key }
+  let(:family_export) { user.family.family_exports.create!(status: "completed") }
+  let(:id) { family_export.id }
+
+  path "/api/v1/family_exports" do
+    get "Lists family exports" do
+      tags "Family Exports"
+      security [ apiKeyAuth: [] ]
+      produces "application/json"
+      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)"
+
+      response "200", "family exports listed" do
+        schema "$ref" => "#/components/schemas/FamilyExportCollection"
+        run_test!
+      end
+
+      response "401", "unauthorized" do
+        let(:'X-Api-Key') { nil }
+        schema "$ref" => "#/components/schemas/ErrorResponse"
+        run_test!
+      end
+
+      response "403", "forbidden" do
+        let(:user) { users(:family_member) }
+        schema "$ref" => "#/components/schemas/ErrorResponse"
+        run_test!
+      end
+    end
+
+    post "Queues a family export" do
+      tags "Family Exports"
+      security [ apiKeyAuth: [] ]
+      consumes "application/json"
+      produces "application/json"
+      parameter name: :body, in: :body, required: false, schema: {
+        type: :object,
+        additionalProperties: false,
+        description: "Family export creation does not accept request parameters."
+      }
+
+      let(:body) { {} }
+
+      response "202", "family export queued" do
+        schema "$ref" => "#/components/schemas/FamilyExportResponse"
+        run_test!
+      end
+
+      response "401", "unauthorized" do
+        let(:'X-Api-Key') { nil }
+        schema "$ref" => "#/components/schemas/ErrorResponse"
+        run_test!
+      end
+
+      response "403", "forbidden" do
+        let(:user) { users(:family_member) }
+        schema "$ref" => "#/components/schemas/ErrorResponse"
+        run_test!
+      end
+
+      response "422", "invalid params" do
+        let(:body) { { family_export: { status: "completed" } } }
+
+        schema "$ref" => "#/components/schemas/ErrorResponse"
+        run_test!
+      end
+    end
+  end
+
+  path "/api/v1/family_exports/{id}" do
+    parameter name: :id, in: :path, type: :string, format: :uuid, required: true
+
+    get "Shows a family export" do
+      tags "Family Exports"
+      security [ apiKeyAuth: [] ]
+      produces "application/json"
+
+      response "200", "family export shown" do
+        schema "$ref" => "#/components/schemas/FamilyExportResponse"
+        run_test!
+      end
+
+      response "401", "unauthorized" do
+        let(:'X-Api-Key') { nil }
+        schema "$ref" => "#/components/schemas/ErrorResponse"
+        run_test!
+      end
+
+      response "403", "forbidden" do
+        let(:user) { users(:family_member) }
+        schema "$ref" => "#/components/schemas/ErrorResponse"
+        run_test!
+      end
+
+      response "404", "not found" do
+        let(:id) { SecureRandom.uuid }
+        schema "$ref" => "#/components/schemas/ErrorResponse"
+        run_test!
+      end
+    end
+  end
+
+  path "/api/v1/family_exports/{id}/download" do
+    parameter name: :id, in: :path, type: :string, format: :uuid, required: true
+
+    get "Downloads a completed family export" do
+      tags "Family Exports"
+      security [ apiKeyAuth: [] ]
+      produces "application/json"
+
+      response "302", "family export download redirected" do
+        before do
+          family_export.export_file.attach(
+            io: StringIO.new("test zip content"),
+            filename: "test.zip",
+            content_type: "application/zip"
+          )
+        end
+
+        run_test!
+      end
+
+      response "401", "unauthorized" do
+        let(:'X-Api-Key') { nil }
+        schema "$ref" => "#/components/schemas/ErrorResponse"
+        run_test!
+      end
+
+      response "403", "forbidden" do
+        let(:user) { users(:family_member) }
+        schema "$ref" => "#/components/schemas/ErrorResponse"
+        run_test!
+      end
+
+      response "404", "not found" do
+        let(:id) { SecureRandom.uuid }
+        schema "$ref" => "#/components/schemas/ErrorResponse"
+        run_test!
+      end
+
+      response "409", "export not ready" do
+        let(:family_export) { user.family.family_exports.create!(status: "processing") }
+        schema "$ref" => "#/components/schemas/ErrorResponse"
+        run_test!
+      end
+    end
+  end
+end

spec/swagger_helper.rb

@@ -43,6 +43,48 @@ RSpec.configure do |config|
               total_pages: { type: :integer, minimum: 0 }
             }
           },
+          FamilyExportFile: {
+            type: :object,
+            required: %w[attached],
+            properties: {
+              attached: { type: :boolean },
+              byte_size: { type: :integer, nullable: true, minimum: 0 },
+              content_type: { type: :string, nullable: true }
+            }
+          },
+          FamilyExport: {
+            type: :object,
+            required: %w[id status filename downloadable file created_at updated_at],
+            properties: {
+              id: { type: :string, format: :uuid },
+              status: { type: :string, enum: %w[pending processing completed failed] },
+              filename: { type: :string },
+              downloadable: { type: :boolean },
+              download_path: { type: :string, nullable: true },
+              file: { '$ref' => '#/components/schemas/FamilyExportFile' },
+              created_at: { type: :string, format: :'date-time' },
+              updated_at: { type: :string, format: :'date-time' }
+            }
+          },
+          FamilyExportResponse: {
+            type: :object,
+            required: %w[data],
+            properties: {
+              data: { '$ref' => '#/components/schemas/FamilyExport' }
+            }
+          },
+          FamilyExportCollection: {
+            type: :object,
+            required: %w[data meta],
+            properties: {
+              data: {
+                type: :array,
+                maxItems: 100,
+                items: { '$ref' => '#/components/schemas/FamilyExport' }
+              },
+              meta: { '$ref' => '#/components/schemas/Pagination' }
+            }
+          },
           ErrorResponse: {
             type: :object,
             required: %w[error],