feat(api): expose provider connection health (#1636)

* feat(api): expose provider connection health

* fix(api): harden provider health review paths

* fix(api): refine provider health responses

* test(api): align provider health docs key scope

* fix(api): clarify provider connection status

* fix(api): batch provider connection sync status

* fix(api): polish provider connection status review feedback

* fix(api): correct provider connection summaries

docs/api/openapi.yaml

@@ -1755,6 +1755,164 @@ components:
       properties:
         data:
           "$ref": "#/components/schemas/ImportDetail"
+    ProviderConnectionInstitution:
+      type: object
+      required:
+      - name
+      properties:
+        name:
+          type: string
+          nullable: true
+        domain:
+          type: string
+          nullable: true
+        url:
+          type: string
+          nullable: true
+    ProviderConnectionAccounts:
+      type: object
+      required:
+      - total_count
+      - linked_count
+      - unlinked_count
+      properties:
+        total_count:
+          type: integer
+          minimum: 0
+        linked_count:
+          type: integer
+          minimum: 0
+        unlinked_count:
+          type: integer
+          minimum: 0
+    ProviderConnectionSyncLatest:
+      type: object
+      required:
+      - id
+      - status
+      - created_at
+      properties:
+        id:
+          type: string
+          format: uuid
+        status:
+          type: string
+        created_at:
+          type: string
+          format: date-time
+        syncing_at:
+          type: string
+          format: date-time
+          nullable: true
+        completed_at:
+          type: string
+          format: date-time
+          nullable: true
+        failed_at:
+          type: string
+          format: date-time
+          nullable: true
+        error:
+          type: object
+          nullable: true
+          description: Sanitized latest sync error summary. Null when the latest sync
+            is not failed or stale.
+          required:
+          - present
+          properties:
+            present:
+              type: boolean
+              description: Always true when this object is present.
+            message:
+              type: string
+              nullable: true
+              description: Stable sanitized error category message; raw provider error
+                text is never exposed.
+    ProviderConnectionSync:
+      type: object
+      required:
+      - syncing
+      properties:
+        syncing:
+          type: boolean
+        status_summary:
+          type: string
+          nullable: true
+        last_synced_at:
+          type: string
+          format: date-time
+          nullable: true
+        latest:
+          allOf:
+          - "$ref": "#/components/schemas/ProviderConnectionSyncLatest"
+          nullable: true
+    ProviderConnection:
+      type: object
+      required:
+      - id
+      - provider
+      - provider_type
+      - name
+      - status
+      - requires_update
+      - credentials_configured
+      - scheduled_for_deletion
+      - pending_account_setup
+      - institution
+      - accounts
+      - sync
+      - created_at
+      - updated_at
+      properties:
+        id:
+          type: string
+          format: uuid
+        provider:
+          type: string
+        provider_type:
+          type: string
+        name:
+          type: string
+        status:
+          type: string
+          nullable: true
+        requires_update:
+          type: boolean
+          nullable: true
+          description: False when the provider item does not expose this status.
+        credentials_configured:
+          type: boolean
+          nullable: true
+          description: False when credential readiness is unknown.
+        scheduled_for_deletion:
+          type: boolean
+          nullable: true
+          description: False when the provider item does not expose this status.
+        pending_account_setup:
+          type: boolean
+          nullable: true
+          description: False when account setup state is unknown.
+        institution:
+          "$ref": "#/components/schemas/ProviderConnectionInstitution"
+        accounts:
+          "$ref": "#/components/schemas/ProviderConnectionAccounts"
+        sync:
+          "$ref": "#/components/schemas/ProviderConnectionSync"
+        created_at:
+          type: string
+          format: date-time
+        updated_at:
+          type: string
+          format: date-time
+    ProviderConnectionCollection:
+      type: object
+      required:
+      - data
+      properties:
+        data:
+          type: array
+          items:
+            "$ref": "#/components/schemas/ProviderConnection"
     ImportRowMapping:
       type: object
       required:
@@ -4448,6 +4606,35 @@ paths:
             application/json:
               schema:
                 "$ref": "#/components/schemas/ErrorResponse"
+  "/api/v1/provider_connections":
+    get:
+      summary: Lists provider connection status summaries
+      description: List safe provider connection status metadata for the authenticated
+        user's family without exposing credentials, raw provider payloads, or raw
+        sync errors.
+      tags:
+      - Provider Connections
+      security:
+      - apiKeyAuth: []
+      responses:
+        '200':
+          description: provider connection status summaries listed
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/ProviderConnectionCollection"
+        '401':
+          description: unauthorized
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/ErrorResponse"
+        '403':
+          description: insufficient scope
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/ErrorResponse"
   "/api/v1/recurring_transactions":
     get:
       summary: List recurring transactions