@thinkai/tai-api-contract 2.4.1 → 2.4.4

package/openapi/openapi.yaml

@@ -1,13 +1,13 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.4.1
+  version: 2.4.4
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
     Legacy tenant-scoped routes (`/tenants/{tenantId}/...`, `/me/tenants`) were removed from runtime.
     Legacy HTTP routes that exist on the server but are not listed here (for example
-    `PUT /workspaces/{workspaceId}/dashboard-settings`) remain supported for existing PIP clients;
+    `PUT /workspaces/{workspaceId}/dashboard-settings`) remain supported for existing API clients;
     prefer OpenAPI-documented equivalents where available. Removal will be coordinated with ThinkAI releases.
 
     **Acceptance intent:** Per-operation behavior (happy paths, validation, and representative errors)
@@ -235,18 +235,17 @@ paths:
       operationId: getTenantOrgChart
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-        - name: withScores
-          in: query
-          schema: { type: boolean }
       responses:
         "200":
-          description: Org chart (optionally with per-node scores)
+          description: SPA org structure chart (`spa_org_chart`; per-node scores not included — use GET /config for scoring tree)
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/OrgChartDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
         "404":
           description: Workspace not found
     post:
@@ -267,13 +266,17 @@ paths:
           content:
             application/json:
               schema:
-                type: object
-                required: [ok, workspaceId]
-                properties:
-                  ok: { type: boolean }
-                  workspaceId: { type: string }
+                $ref: "#/components/schemas/OrgChartSaveResultDto"
+        "400":
+          description: Invalid request body or chart limits exceeded
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
 
   /workspaces/{workspaceId}/config:
     get:
@@ -1514,6 +1517,8 @@ paths:
                         defaultBranch: main
                         externalId: null
                         hostBaseUrl: null
+                      analysisStatus: idle
+                      activeRunId: null
         "401":
           $ref: "#/components/responses/Unauthorized"
         "403":
@@ -1755,6 +1760,9 @@ paths:
     get:
       tags: [RepositoryReadiness]
       summary: Readiness dimensions catalog
+      description: >
+        Returns static rubric metadata (id, name, description, maxScore) aligned with the readiness
+        scanner dimensions. Does not run scoring on the request path.
       operationId: listReadinessDimensions
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
@@ -1769,11 +1777,21 @@ paths:
                   $ref: "#/components/schemas/ReadinessDimensionDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
 
   /workspaces/{workspaceId}/readiness/fixes:
     get:
       tags: [RepositoryReadiness]
       summary: List fix requests
+      description: >
+        Returns persisted fix-queue rows for the workspace (newest first). Empty array when none exist.
       operationId: listReadinessFixes
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
@@ -1788,9 +1806,21 @@ paths:
                   $ref: "#/components/schemas/FixRequestDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
     post:
       tags: [RepositoryReadiness]
       summary: Enqueue fix for an issue
+      description: >
+        Creates a fix request with `status: queued` when `issueId` belongs to `repoId` in this workspace.
+        Requires workspace editor or admin. Re-posting the same `issueId` and `repoId` returns the
+        existing row (idempotent).
       operationId: postReadinessFix
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
@@ -1800,15 +1830,34 @@ paths:
           application/json:
             schema:
               $ref: "#/components/schemas/CreateFixRequestBodyDto"
+            examples:
+              enqueue:
+                value:
+                  issueId: "22222222-2222-2222-2222-222222222222"
+                  repoId: "11111111-1111-4111-8111-111111111111"
       responses:
         "200":
-          description: Fix request created
+          description: Fix request created or existing row returned
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/FixRequestDto"
+        "400":
+          description: Invalid body or malformed `repoId` (not a UUID)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace not found, or issue/repo pair not in workspace
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
 
   /workspaces/{workspaceId}/squad:
     get:
@@ -2094,6 +2143,10 @@ paths:
     post:
       tags: [OrgChartImport]
       summary: Import org chart from Supabase storage path
+      description: >
+        Parse-only. Downloads the CSV at `storagePath` from the `org-charts` bucket and returns
+        `persons` and `errors`. Does not persist to `spa_org_chart` or `org_chart`. The SPA
+        derives teams client-side and saves the org structure via `POST /workspaces/{workspaceId}/org-chart`.
       operationId: postOrgChartImport
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
@@ -2105,14 +2158,39 @@ paths:
               $ref: "#/components/schemas/OrgChartImportBodyDto"
       responses:
         "200":
-          description: Parsed persons (shape TBD; align with backend)
+          description: Parsed persons from uploaded CSV (not persisted server-side)
           content:
             application/json:
               schema:
-                type: object
-                additionalProperties: true
+                $ref: "#/components/schemas/OrgChartImportResultDto"
+        "400":
+          description: Invalid body or storage path
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Storage object not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "502":
+          description: Failed to download file from storage
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "503":
+          description: Storage import not configured or service unavailable
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
 
 components:
   securitySchemes:
@@ -2212,6 +2290,26 @@ components:
           type: string
           enum: [admin, editor, viewer]
 
+    OrgChartNodeDto:
+      type: object
+      additionalProperties: false
+      required: [id, name, type]
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        type:
+          type: string
+          enum: [org, department, team, person]
+        external_ids:
+          type: object
+          additionalProperties: { type: string }
+        children:
+          type: array
+          items:
+            $ref: "#/components/schemas/OrgChartNodeDto"
+
     OrgChartTreeNodeDto:
       type: object
       required: [id]
@@ -2238,13 +2336,69 @@ components:
           items:
             $ref: "#/components/schemas/OrgChartTreeNodeDto"
 
-    OrgChartDto:
+    ScoringOrgChartDto:
       type: object
+      additionalProperties: false
       required: [root]
       properties:
         root:
           $ref: "#/components/schemas/OrgChartTreeNodeDto"
 
+    OrgChartDto:
+      type: object
+      additionalProperties: false
+      required: [root]
+      properties:
+        root:
+          $ref: "#/components/schemas/OrgChartNodeDto"
+
+    OrgChartPersonDto:
+      type: object
+      additionalProperties: false
+      required: [employeeId, name, email, title, department, team, managerId, location]
+      properties:
+        employeeId:
+          type: string
+        name:
+          type: string
+        email:
+          type: string
+        title:
+          type: string
+        department:
+          type: string
+        team:
+          type: string
+        managerId:
+          type: string
+        location:
+          type: string
+
+    OrgChartImportResultDto:
+      type: object
+      additionalProperties: false
+      required: [persons, errors]
+      properties:
+        persons:
+          type: array
+          items:
+            $ref: "#/components/schemas/OrgChartPersonDto"
+        errors:
+          type: array
+          items:
+            type: string
+
+    OrgChartSaveResultDto:
+      type: object
+      additionalProperties: false
+      required: [ok, tenantId]
+      properties:
+        ok:
+          type: boolean
+        tenantId:
+          type: string
+          format: uuid
+
     TenantSourceEntryDto:
       type: object
       required: [type]
@@ -2291,7 +2445,7 @@ components:
         orgChart:
           nullable: true
           allOf:
-            - $ref: "#/components/schemas/OrgChartDto"
+            - $ref: "#/components/schemas/ScoringOrgChartDto"
         region:
           type: string
           nullable: true
@@ -2939,6 +3093,13 @@ components:
       type: string
       enum: [queued, running, succeeded, failed, partial_failed]
 
+    ReadinessRepoAnalysisStatusDto:
+      type: string
+      enum: [idle, queued, running]
+      description: >
+        Whether an AI readiness analysis run is queued or in progress for this repository slug.
+        `idle` means no `queued`/`running` row exists in `tai_workspace_readiness_runs`.
+
     ReadinessRunSummaryDto:
       type: object
       required: [runId, status, providerSlug, errorCode, errorDetail, repoId, createdAt, finishedAt]
@@ -3014,7 +3175,15 @@ components:
 
     RepoReadinessScoreDto:
       type: object
-      required: [repoId, repoName, language, overallScore, dimensions, lastAnalyzed, provider]
+      required:
+        - repoId
+        - repoName
+        - language
+        - overallScore
+        - dimensions
+        - lastAnalyzed
+        - provider
+        - analysisStatus
       properties:
         repoId:
           type: string
@@ -3043,6 +3212,13 @@ components:
           nullable: true
         provider:
           $ref: "#/components/schemas/RepoProviderDto"
+        analysisStatus:
+          $ref: "#/components/schemas/ReadinessRepoAnalysisStatusDto"
+        activeRunId:
+          type: string
+          format: uuid
+          nullable: true
+          description: Present when `analysisStatus` is `queued` or `running`; use with `GET .../readiness/runs/{runId}`.
 
     AgenticFoundationDashboardSummaryDto:
       type: object
@@ -3152,8 +3328,12 @@ components:
       properties:
         issueId:
           type: string
+          format: uuid
+          description: Readiness issue id from stored scorecard data
         repoId:
           type: string
+          format: uuid
+          description: Workspace repository id that owns the issue
 
     PhaseRoleDto:
       type: object
@@ -3492,6 +3672,7 @@ components:
 
     OrgChartImportBodyDto:
       type: object
+      additionalProperties: false
       required: [storagePath]
       properties:
         storagePath:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinkai/tai-api-contract",
-  "version": "2.4.1",
+  "version": "2.4.4",
   "private": false,
   "type": "module",
   "main": "dist/index.js",