@thinkai/tai-api-contract 2.5.16 → 2.5.17

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.5.16
+  version: 2.5.17
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -138,6 +138,9 @@ paths:
     get:
       tags: [Workspace]
       summary: List workspace team members
+      description: >
+        Returns active workspace members (`tai_workspace_members` with `deleted_at` null).
+        Any workspace member may list; invite and role changes require admin.
       operationId: listTenantMembers
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
@@ -148,15 +151,33 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/TeamMemberListDto"
+              example:
+                members:
+                  - id: "11111111-1111-4111-8111-111111111111"
+                    name: "Alex Admin"
+                    email: "alex@example.com"
+                    role: admin
         "401":
           $ref: "#/components/responses/Unauthorized"
         "403":
           $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist or malformed workspaceId
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
 
   /workspaces/{workspaceId}/members/invite:
     post:
       tags: [Workspace]
       summary: Invite member to workspace
+      description: >
+        Workspace admin only. Upserts `tai_users` by email and adds or reactivates
+        `tai_workspace_members`. Idempotent when the email is already an active member:
+        returns **201** with the existing row and **does not change** their role if the
+        request body role differs. Does not send email; optional `tai_workspace_invitations`
+        row may be recorded (no accept/link flow yet).
       operationId: inviteTenantMember
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
@@ -166,6 +187,9 @@ paths:
           application/json:
             schema:
               $ref: "#/components/schemas/InviteTeamMemberBodyDto"
+            example:
+              email: new.member@example.com
+              role: editor
       responses:
         "201":
           description: Invited member row
@@ -173,28 +197,40 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/TeamMemberDto"
+        "400":
+          description: Invalid email or role
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "403":
           $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist or malformed workspaceId
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
 
   /workspaces/{workspaceId}/members/{memberId}:
     patch:
       tags: [Workspace]
       summary: Update workspace member role
+      description: Workspace admin only. `memberId` is `tai_users.id` (UUID), not the auth subject.
       operationId: updateTenantMemberRole
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-        - name: memberId
-          in: path
-          required: true
-          schema: { type: string }
+        - $ref: "#/components/parameters/WorkspaceMemberId"
       requestBody:
         required: true
         content:
           application/json:
             schema:
               $ref: "#/components/schemas/UpdateTeamMemberRoleBodyDto"
+            example:
+              role: viewer
       responses:
         "200":
           description: Updated member row
@@ -202,22 +238,43 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/TeamMemberDto"
+        "400":
+          description: Invalid role payload
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "403":
           $ref: "#/components/responses/Forbidden"
         "404":
-          description: Member not found
+          description: Member not found or invalid memberId
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "409":
+          description: Cannot demote the last workspace admin
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              examples:
+                lastAdmin:
+                  value:
+                    error: Cannot change role of the last workspace admin
+                    code: last_admin
     delete:
       tags: [Workspace]
       summary: Remove member from workspace
+      description: >
+        Workspace admin only. Soft-deletes the membership (`deleted_at` set).
+        Cannot remove the workspace owner or the last admin.
       operationId: removeTenantMember
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-        - name: memberId
-          in: path
-          required: true
-          schema: { type: string }
+        - $ref: "#/components/parameters/WorkspaceMemberId"
       responses:
         "204":
           description: Removed
@@ -226,7 +283,26 @@ paths:
         "403":
           $ref: "#/components/responses/Forbidden"
         "404":
-          description: Member not found
+          description: Member not found or invalid memberId
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "409":
+          description: Cannot remove workspace owner or last admin
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              examples:
+                lastAdmin:
+                  value:
+                    error: Cannot remove the last workspace admin
+                    code: last_admin
+                workspaceOwner:
+                  value:
+                    error: Cannot remove the workspace owner
+                    code: workspace_owner
 
   /workspaces/{workspaceId}/org-chart:
     get:
@@ -3020,6 +3096,14 @@ components:
       required: true
       schema:
         type: string
+    WorkspaceMemberId:
+      name: memberId
+      in: path
+      required: true
+      schema:
+        type: string
+        format: uuid
+      description: Workspace member user id (`tai_users.id`).
     FixId:
       name: fixId
       in: path
@@ -3061,6 +3145,9 @@ components:
       properties:
         error:
           type: string
+        code:
+          type: string
+          description: Machine-readable error code when present (for example `last_admin`).
 
     TeamMemberDto:
       type: object
@@ -3068,6 +3155,7 @@ components:
       properties:
         id:
           type: string
+          format: uuid
         name:
           type: string
         email:

package/package.json

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

package/src/generated/openapi.ts

@@ -69,7 +69,10 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /** List workspace team members */
+        /**
+         * List workspace team members
+         * @description Returns active workspace members (`tai_workspace_members` with `deleted_at` null). Any workspace member may list; invite and role changes require admin.
+         */
         get: operations["listTenantMembers"];
         put?: never;
         post?: never;
@@ -88,7 +91,10 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /** Invite member to workspace */
+        /**
+         * Invite member to workspace
+         * @description Workspace admin only. Upserts `tai_users` by email and adds or reactivates `tai_workspace_members`. Idempotent when the email is already an active member: returns **201** with the existing row and **does not change** their role if the request body role differs. Does not send email; optional `tai_workspace_invitations` row may be recorded (no accept/link flow yet).
+         */
         post: operations["inviteTenantMember"];
         delete?: never;
         options?: never;
@@ -106,11 +112,17 @@ export interface paths {
         get?: never;
         put?: never;
         post?: never;
-        /** Remove member from workspace */
+        /**
+         * Remove member from workspace
+         * @description Workspace admin only. Soft-deletes the membership (`deleted_at` set). Cannot remove the workspace owner or the last admin.
+         */
         delete: operations["removeTenantMember"];
         options?: never;
         head?: never;
-        /** Update workspace member role */
+        /**
+         * Update workspace member role
+         * @description Workspace admin only. `memberId` is `tai_users.id` (UUID), not the auth subject.
+         */
         patch: operations["updateTenantMemberRole"];
         trace?: never;
     };
@@ -1329,8 +1341,11 @@ export interface components {
     schemas: {
         ErrorMessageDto: {
             error: string;
+            /** @description Machine-readable error code when present (for example `last_admin`). */
+            code?: string;
         };
         TeamMemberDto: {
+            /** Format: uuid */
             id: string;
             name: string;
             email: string;
@@ -2449,6 +2464,8 @@ export interface components {
         RepoId: string;
         ProjectId: string;
         NotificationId: string;
+        /** @description Workspace member user id (`tai_users.id`). */
+        WorkspaceMemberId: string;
         FixId: string;
         /** @description Department filter; send `All departments` to include every department. Scoped using imported `thinkai_org_structure` members when present, otherwise SPA org chart `department` nodes and their descendant teams. When neither source defines the requested department, insights return no scoped teams or contributors (not org-wide data). */
         InsightsDepartmentFilter: string;
@@ -2589,6 +2606,7 @@ export type ParameterWorkspaceId = components['parameters']['WorkspaceId'];
 export type ParameterRepoId = components['parameters']['RepoId'];
 export type ParameterProjectId = components['parameters']['ProjectId'];
 export type ParameterNotificationId = components['parameters']['NotificationId'];
+export type ParameterWorkspaceMemberId = components['parameters']['WorkspaceMemberId'];
 export type ParameterFixId = components['parameters']['FixId'];
 export type ParameterInsightsDepartmentFilter = components['parameters']['InsightsDepartmentFilter'];
 export type $defs = Record<string, never>;
@@ -2718,11 +2736,32 @@ export interface operations {
                     [name: string]: unknown;
                 };
                 content: {
+                    /**
+                     * @example {
+                     *       "members": [
+                     *         {
+                     *           "id": "11111111-1111-4111-8111-111111111111",
+                     *           "name": "Alex Admin",
+                     *           "email": "alex@example.com",
+                     *           "role": "admin"
+                     *         }
+                     *       ]
+                     *     }
+                     */
                     "application/json": components["schemas"]["TeamMemberListDto"];
                 };
             };
             401: components["responses"]["Unauthorized"];
             403: components["responses"]["Forbidden"];
+            /** @description Workspace does not exist or malformed workspaceId */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
         };
     };
     inviteTenantMember: {
@@ -2736,6 +2775,12 @@ export interface operations {
         };
         requestBody: {
             content: {
+                /**
+                 * @example {
+                 *       "email": "new.member@example.com",
+                 *       "role": "editor"
+                 *     }
+                 */
                 "application/json": components["schemas"]["InviteTeamMemberBodyDto"];
             };
         };
@@ -2749,8 +2794,26 @@ export interface operations {
                     "application/json": components["schemas"]["TeamMemberDto"];
                 };
             };
+            /** @description Invalid email or role */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
             401: components["responses"]["Unauthorized"];
             403: components["responses"]["Forbidden"];
+            /** @description Workspace does not exist or malformed workspaceId */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
         };
     };
     removeTenantMember: {
@@ -2759,7 +2822,8 @@ export interface operations {
             header?: never;
             path: {
                 workspaceId: components["parameters"]["WorkspaceId"];
-                memberId: string;
+                /** @description Workspace member user id (`tai_users.id`). */
+                memberId: components["parameters"]["WorkspaceMemberId"];
             };
             cookie?: never;
         };
@@ -2774,12 +2838,23 @@ export interface operations {
             };
             401: components["responses"]["Unauthorized"];
             403: components["responses"]["Forbidden"];
-            /** @description Member not found */
+            /** @description Member not found or invalid memberId */
             404: {
                 headers: {
                     [name: string]: unknown;
                 };
-                content?: never;
+                content: {
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
+            /** @description Cannot remove workspace owner or last admin */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
             };
         };
     };
@@ -2789,12 +2864,18 @@ export interface operations {
             header?: never;
             path: {
                 workspaceId: components["parameters"]["WorkspaceId"];
-                memberId: string;
+                /** @description Workspace member user id (`tai_users.id`). */
+                memberId: components["parameters"]["WorkspaceMemberId"];
             };
             cookie?: never;
         };
         requestBody: {
             content: {
+                /**
+                 * @example {
+                 *       "role": "viewer"
+                 *     }
+                 */
                 "application/json": components["schemas"]["UpdateTeamMemberRoleBodyDto"];
             };
         };
@@ -2808,14 +2889,34 @@ export interface operations {
                     "application/json": components["schemas"]["TeamMemberDto"];
                 };
             };
+            /** @description Invalid role payload */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
             401: components["responses"]["Unauthorized"];
             403: components["responses"]["Forbidden"];
-            /** @description Member not found */
+            /** @description Member not found or invalid memberId */
             404: {
                 headers: {
                     [name: string]: unknown;
                 };
-                content?: never;
+                content: {
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
+            /** @description Cannot demote the last workspace admin */
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
             };
         };
     };