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
2026-05-09 21:54:58 +00:00 · 2026-05-03 03:29:29 -06:00
parent 6c84fc760e
commit 50936000e7
11 changed files with 803 additions and 6 deletions
--- a/docs/api/openapi.yaml
+++ b/docs/api/openapi.yaml
@@ -37,6 +37,76 @@ components:
        total_pages:
          type: integer
          minimum: 0
+    FamilyExportFile:
+      type: object
+      required:
+      - attached
+      properties:
+        attached:
+          type: boolean
+        byte_size:
+          type: integer
+          nullable: true
+          minimum: 0
+        content_type:
+          type: string
+          nullable: true
+    FamilyExport:
+      type: object
+      required:
+      - id
+      - status
+      - filename
+      - downloadable
+      - file
+      - created_at
+      - updated_at
+      properties:
+        id:
+          type: string
+          format: uuid
+        status:
+          type: string
+          enum:
+          - 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:
+      - data
+      properties:
+        data:
+          "$ref": "#/components/schemas/FamilyExport"
+    FamilyExportCollection:
+      type: object
+      required:
+      - data
+      - meta
+      properties:
+        data:
+          type: array
+          maxItems: 100
+          items:
+            "$ref": "#/components/schemas/FamilyExport"
+        meta:
+          "$ref": "#/components/schemas/Pagination"
    ErrorResponse:
      type: object
      required:
@@ -2260,6 +2330,164 @@ paths:
            application/json:
              schema:
                "$ref": "#/components/schemas/ErrorResponse"
+  "/api/v1/family_exports":
+    get:
+      summary: Lists family exports
+      tags:
+      - Family Exports
+      security:
+      - apiKeyAuth: []
+      parameters:
+      - name: page
+        in: query
+        required: false
+        description: 'Page number (default: 1)'
+        schema:
+          type: integer
+      - name: per_page
+        in: query
+        required: false
+        description: 'Items per page (default: 25, max: 100)'
+        schema:
+          type: integer
+      responses:
+        '200':
+          description: family exports listed
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/FamilyExportCollection"
+        '401':
+          description: unauthorized
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/ErrorResponse"
+        '403':
+          description: forbidden
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/ErrorResponse"
+    post:
+      summary: Queues a family export
+      tags:
+      - Family Exports
+      security:
+      - apiKeyAuth: []
+      parameters: []
+      responses:
+        '202':
+          description: family export queued
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/FamilyExportResponse"
+        '401':
+          description: unauthorized
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/ErrorResponse"
+        '403':
+          description: forbidden
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/ErrorResponse"
+        '422':
+          description: invalid params
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/ErrorResponse"
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: false
+              description: Family export creation does not accept request parameters.
+  "/api/v1/family_exports/{id}":
+    parameters:
+    - name: id
+      in: path
+      format: uuid
+      required: true
+      schema:
+        type: string
+    get:
+      summary: Shows a family export
+      tags:
+      - Family Exports
+      security:
+      - apiKeyAuth: []
+      responses:
+        '200':
+          description: family export shown
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/FamilyExportResponse"
+        '401':
+          description: unauthorized
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/ErrorResponse"
+        '403':
+          description: forbidden
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/ErrorResponse"
+        '404':
+          description: not found
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/ErrorResponse"
+  "/api/v1/family_exports/{id}/download":
+    parameters:
+    - name: id
+      in: path
+      format: uuid
+      required: true
+      schema:
+        type: string
+    get:
+      summary: Downloads a completed family export
+      tags:
+      - Family Exports
+      security:
+      - apiKeyAuth: []
+      responses:
+        '302':
+          description: family export download redirected
+        '401':
+          description: unauthorized
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/ErrorResponse"
+        '403':
+          description: forbidden
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/ErrorResponse"
+        '404':
+          description: not found
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/ErrorResponse"
+        '409':
+          description: export not ready
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/ErrorResponse"
  "/api/v1/holdings":
    get:
      summary: List holdings