feat(api): expose reset status polling (#1598)

* feat(api): expose reset status polling

* fix(api): hide reset enqueue exception details

* fix(api): use stable reset authorization message

* fix(api): narrow reset enqueue error handling

* fix(api): document reset enqueue failures

* docs(api): regenerate reset status OpenAPI

* fix(api): address reset polling review feedback

docs/api/openapi.yaml

@@ -1259,6 +1259,85 @@ components:
       properties:
         message:
           type: string
+    ResetInitiatedResponse:
+      type: object
+      required:
+      - message
+      - status
+      - job_id
+      - family_id
+      - status_url
+      properties:
+        message:
+          type: string
+        status:
+          type: string
+          enum:
+          - queued
+        job_id:
+          type: string
+          description: Informational Active Job identifier returned by the queue adapter;
+            reset status is family-scoped, not job-scoped.
+        family_id:
+          type: string
+          format: uuid
+          description: UUID of the family being reset.
+        status_url:
+          type: string
+    ResetStatusResponse:
+      type: object
+      required:
+      - status
+      - family_id
+      - reset_complete
+      - counts
+      properties:
+        status:
+          type: string
+          enum:
+          - complete
+          - data_remaining
+          description: Counts-based family reset status at response time.
+        family_id:
+          type: string
+          format: uuid
+          description: UUID of the family whose reset target counts were checked.
+        reset_complete:
+          type: boolean
+          description: True when all reset target counts are zero at response time.
+            This is a family data snapshot, not a durable per-job completion record.
+        counts:
+          type: object
+          required:
+          - accounts
+          - categories
+          - tags
+          - merchants
+          - plaid_items
+          - imports
+          - budgets
+          properties:
+            accounts:
+              type: integer
+              minimum: 0
+            categories:
+              type: integer
+              minimum: 0
+            tags:
+              type: integer
+              minimum: 0
+            merchants:
+              type: integer
+              minimum: 0
+            plaid_items:
+              type: integer
+              minimum: 0
+            imports:
+              type: integer
+              minimum: 0
+            budgets:
+              type: integer
+              minimum: 0
 paths:
   "/api/v1/accounts":
     get:
@@ -3752,7 +3831,8 @@ paths:
       - Users
       description: Resets all financial data (accounts, categories, merchants, tags,
         etc.) for the current user's family while keeping the user account intact.
-        The reset runs asynchronously in the background. Requires admin role.
+        The reset runs asynchronously in the background. The returned job_id is informational
+        only; reset status is family-scoped, not job-scoped. Requires admin role.
       security:
       - apiKeyAuth: []
       responses:
@@ -3761,11 +3841,55 @@ paths:
           content:
             application/json:
               schema:
-                "$ref": "#/components/schemas/SuccessMessage"
+                "$ref": "#/components/schemas/ResetInitiatedResponse"
         '401':
           description: unauthorized
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/ErrorResponse"
         '403':
           description: forbidden - requires read_write scope and admin role
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/ErrorResponse"
+        '500':
+          description: reset enqueue failed
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/ErrorResponse"
+  "/api/v1/users/reset/status":
+    get:
+      summary: Retrieve reset status
+      tags:
+      - Users
+      description: Returns counts of family-owned data targeted by account reset.
+        Use this after DELETE /api/v1/users/reset to decide whether reset materialization
+        has completed. Completion is a counts-based family snapshot and may change
+        if new data is created after reset.
+      security:
+      - apiKeyAuth: []
+      responses:
+        '200':
+          description: reset status returned
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/ResetStatusResponse"
+        '401':
+          description: unauthorized
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/ErrorResponse"
+        '403':
+          description: forbidden - requires admin role
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/ErrorResponse"
   "/api/v1/users/me":
     delete:
       summary: Delete account