@thinkai/tai-api-contract 2.4.3 → 2.4.5

package/openapi/openapi.yaml

@@ -1,13 +1,13 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.4.3
+  version: 2.4.5
   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:
@@ -2140,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"
@@ -2151,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:
@@ -2258,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]
@@ -2284,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]
@@ -2337,7 +2445,7 @@ components:
         orgChart:
           nullable: true
           allOf:
-            - $ref: "#/components/schemas/OrgChartDto"
+            - $ref: "#/components/schemas/ScoringOrgChartDto"
         region:
           type: string
           nullable: true
@@ -3022,6 +3130,29 @@ components:
           format: date-time
           nullable: true
 
+    ReadinessCriteriaSummaryDto:
+      type: object
+      required: [total, met, partial, gap, na, blocked]
+      properties:
+        total:
+          type: integer
+          minimum: 0
+        met:
+          type: integer
+          minimum: 0
+        partial:
+          type: integer
+          minimum: 0
+        gap:
+          type: integer
+          minimum: 0
+        na:
+          type: integer
+          minimum: 0
+        blocked:
+          type: integer
+          minimum: 0
+
     ReadinessIssueDto:
       type: object
       required: [id, dimensionId, severity, title, description, fixStatus]
@@ -3037,9 +3168,16 @@ components:
         title:
           type: string
           maxLength: 256
+          description: Human-readable rubric label (e.g. Agent instructions)
         description:
           type: string
           maxLength: 2048
+          description: Scan notes, remediation, and optional detection gist for tooltips
+        rubricId:
+          type: string
+          maxLength: 16
+          nullable: true
+          description: Rubric criterion id (e.g. A1, B3)
         filePath:
           type: string
           maxLength: 512
@@ -3057,9 +3195,22 @@ components:
         score:
           type: integer
           minimum: 0
+          description: Dimension points earned (weighted rubric average × maxScore, rounded)
         maxScore:
           type: integer
           minimum: 0
+          description: Maximum points for this dimension pillar
+        scorePercent:
+          type: integer
+          minimum: 0
+          maximum: 100
+          description: score / maxScore as 0–100 when maxScore > 0
+        criteriaSummary:
+          type: object
+          nullable: true
+          allOf:
+            - $ref: "#/components/schemas/ReadinessCriteriaSummaryDto"
+          description: Per-criterion status counts from the latest successful scan
         issues:
           type: array
           items:
@@ -3157,6 +3308,10 @@ components:
         description:
           type: string
           maxLength: 2048
+        rubricId:
+          type: string
+          maxLength: 16
+          nullable: true
         filePath:
           type: string
           maxLength: 512
@@ -3564,6 +3719,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.3",
+  "version": "2.4.5",
   "private": false,
   "type": "module",
   "main": "dist/index.js",

package/src/generated/openapi.ts

@@ -1032,7 +1032,10 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /** Import org chart from Supabase storage path */
+        /**
+         * 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`.
+         */
         post: operations["postOrgChartImport"];
         delete?: never;
         options?: never;
@@ -1066,6 +1069,16 @@ export interface components {
             /** @enum {string} */
             role: "admin" | "editor" | "viewer";
         };
+        OrgChartNodeDto: {
+            id: string;
+            name: string;
+            /** @enum {string} */
+            type: "org" | "department" | "team" | "person";
+            external_ids?: {
+                [key: string]: string;
+            };
+            children?: components["schemas"]["OrgChartNodeDto"][];
+        };
         OrgChartTreeNodeDto: {
             id: string;
             name?: string;
@@ -1079,9 +1092,31 @@ export interface components {
             };
             children?: components["schemas"]["OrgChartTreeNodeDto"][];
         };
-        OrgChartDto: {
+        ScoringOrgChartDto: {
             root: components["schemas"]["OrgChartTreeNodeDto"];
         };
+        OrgChartDto: {
+            root: components["schemas"]["OrgChartNodeDto"];
+        };
+        OrgChartPersonDto: {
+            employeeId: string;
+            name: string;
+            email: string;
+            title: string;
+            department: string;
+            team: string;
+            managerId: string;
+            location: string;
+        };
+        OrgChartImportResultDto: {
+            persons: components["schemas"]["OrgChartPersonDto"][];
+            errors: string[];
+        };
+        OrgChartSaveResultDto: {
+            ok: boolean;
+            /** Format: uuid */
+            tenantId: string;
+        };
         TenantSourceEntryDto: {
             type: string;
         } & {
@@ -1102,7 +1137,7 @@ export interface components {
         };
         WorkspaceConfigDto: {
             sources: components["schemas"]["TenantSourceEntryDto"][];
-            orgChart?: components["schemas"]["OrgChartDto"] | null;
+            orgChart?: components["schemas"]["ScoringOrgChartDto"] | null;
             /** @enum {string|null} */
             region?: "us" | "eu" | "me" | null;
         };
@@ -1420,22 +1455,40 @@ export interface components {
             /** Format: date-time */
             finishedAt: string | null;
         };
+        ReadinessCriteriaSummaryDto: {
+            total: number;
+            met: number;
+            partial: number;
+            gap: number;
+            na: number;
+            blocked: number;
+        };
         ReadinessIssueDto: {
             /** Format: uuid */
             id: string;
             dimensionId: components["schemas"]["ReadinessDimensionId"];
             /** @enum {string} */
             severity: "critical" | "high" | "medium" | "low";
+            /** @description Human-readable rubric label (e.g. Agent instructions) */
             title: string;
+            /** @description Scan notes, remediation, and optional detection gist for tooltips */
             description: string;
+            /** @description Rubric criterion id (e.g. A1, B3) */
+            rubricId?: string | null;
             filePath?: string | null;
             /** @enum {string} */
             fixStatus: "open" | "pr-pending" | "fixed";
         };
         DimensionScoreDto: {
             dimensionId: components["schemas"]["ReadinessDimensionId"];
+            /** @description Dimension points earned (weighted rubric average × maxScore, rounded) */
             score: number;
+            /** @description Maximum points for this dimension pillar */
             maxScore: number;
+            /** @description score / maxScore as 0–100 when maxScore > 0 */
+            scorePercent?: number;
+            /** @description Per-criterion status counts from the latest successful scan */
+            criteriaSummary?: components["schemas"]["ReadinessCriteriaSummaryDto"] | null;
             issues: components["schemas"]["ReadinessIssueDto"][];
         };
         RepoReadinessScoreDto: {
@@ -1476,6 +1529,7 @@ export interface components {
             severity: "critical" | "high" | "medium" | "low";
             title: string;
             description: string;
+            rubricId?: string | null;
             filePath: string | null;
             /** @enum {string} */
             fixStatus: "open" | "pr-pending" | "fixed";
@@ -1702,8 +1756,13 @@ export type TeamMemberDto = components['schemas']['TeamMemberDto'];
 export type TeamMemberListDto = components['schemas']['TeamMemberListDto'];
 export type InviteTeamMemberBodyDto = components['schemas']['InviteTeamMemberBodyDto'];
 export type UpdateTeamMemberRoleBodyDto = components['schemas']['UpdateTeamMemberRoleBodyDto'];
+export type OrgChartNodeDto = components['schemas']['OrgChartNodeDto'];
 export type OrgChartTreeNodeDto = components['schemas']['OrgChartTreeNodeDto'];
+export type ScoringOrgChartDto = components['schemas']['ScoringOrgChartDto'];
 export type OrgChartDto = components['schemas']['OrgChartDto'];
+export type OrgChartPersonDto = components['schemas']['OrgChartPersonDto'];
+export type OrgChartImportResultDto = components['schemas']['OrgChartImportResultDto'];
+export type OrgChartSaveResultDto = components['schemas']['OrgChartSaveResultDto'];
 export type TenantSourceEntryDto = components['schemas']['TenantSourceEntryDto'];
 export type CursorSourceDto = components['schemas']['CursorSourceDto'];
 export type WorkspaceConfigDto = components['schemas']['WorkspaceConfigDto'];
@@ -1747,6 +1806,7 @@ export type ReadinessAnalyzeResponseDto = components['schemas']['ReadinessAnalyz
 export type ReadinessRunStatusDto = components['schemas']['ReadinessRunStatusDto'];
 export type ReadinessRepoAnalysisStatusDto = components['schemas']['ReadinessRepoAnalysisStatusDto'];
 export type ReadinessRunSummaryDto = components['schemas']['ReadinessRunSummaryDto'];
+export type ReadinessCriteriaSummaryDto = components['schemas']['ReadinessCriteriaSummaryDto'];
 export type ReadinessIssueDto = components['schemas']['ReadinessIssueDto'];
 export type DimensionScoreDto = components['schemas']['DimensionScoreDto'];
 export type RepoReadinessScoreDto = components['schemas']['RepoReadinessScoreDto'];
@@ -2015,9 +2075,7 @@ export interface operations {
     };
     getTenantOrgChart: {
         parameters: {
-            query?: {
-                withScores?: boolean;
-            };
+            query?: never;
             header?: never;
             path: {
                 workspaceId: components["parameters"]["WorkspaceId"];
@@ -2026,7 +2084,7 @@ export interface operations {
         };
         requestBody?: never;
         responses: {
-            /** @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) */
             200: {
                 headers: {
                     [name: string]: unknown;
@@ -2036,6 +2094,7 @@ export interface operations {
                 };
             };
             401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
             /** @description Workspace not found */
             404: {
                 headers: {
@@ -2066,13 +2125,20 @@ export interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": {
-                        ok: boolean;
-                        workspaceId: string;
-                    };
+                    "application/json": components["schemas"]["OrgChartSaveResultDto"];
+                };
+            };
+            /** @description Invalid request body or chart limits exceeded */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorMessageDto"];
                 };
             };
             401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
         };
     };
     getWorkspaceConfig: {
@@ -4035,18 +4101,53 @@ export interface operations {
             };
         };
         responses: {
-            /** @description Parsed persons (shape TBD; align with backend) */
+            /** @description Parsed persons from uploaded CSV (not persisted server-side) */
             200: {
                 headers: {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": {
-                        [key: string]: unknown;
-                    };
+                    "application/json": components["schemas"]["OrgChartImportResultDto"];
+                };
+            };
+            /** @description Invalid body or storage path */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorMessageDto"];
                 };
             };
             401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            /** @description Storage object not found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
+            /** @description Failed to download file from storage */
+            502: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
+            /** @description Storage import not configured or service unavailable */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
         };
     };
 }

package/src/index.ts

@@ -179,18 +179,23 @@ export interface OrgChartTreeNodeDto {
   external_ids?: Record<string, string>;
 }
 
-/** Org chart tree node with computed scores (Option B, α=0.2). Used when ?withScores=true. */
+/** Org chart tree node with computed scores (Option B, α=0.2). Reserved for a future scored-tree API. */
 export interface OrgChartTreeNodeWithScoreDto extends OrgChartTreeNodeDto {
   score?: number | null;
   individualUpi?: number | null;
   children?: OrgChartTreeNodeWithScoreDto[];
 }
 
-/** M7: Org chart response (tree only). */
+/** M7: Org chart response (tree only). Legacy hand-written shape; prefer generated `OrgChartDto` for SPA routes. */
 export interface OrgChartDto {
   root: OrgChartTreeNodeDto;
 }
 
+/** Batch scoring person tree returned by GET /workspaces/{workspaceId}/config (`org_chart` column). */
+export interface ScoringOrgChartDto {
+  root: OrgChartTreeNodeDto;
+}
+
 /** Summary of a person derived from the tenant's org chart. */
 export interface PersonSummaryDto {
   /** Canonical person identifier (e.g. work email). */
@@ -222,7 +227,7 @@ export interface TestConnectionResponseDto {
 /** Workspace integration config (sources; optionally org chart for Home; optionally region for data residency). */
 export interface WorkspaceConfigDto {
   sources: TenantSourceEntryDto[];
-  orgChart?: OrgChartDto | null;
+  orgChart?: ScoringOrgChartDto | null;
   /** Region for data residency (us, eu, me). Null or absent = legacy/single-region. */
   region?: string | null;
 }