@thinkai/tai-api-contract 2.70.0 → 2.71.0

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.70.0
+  version: 2.71.0
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -968,11 +968,15 @@ paths:
       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).
+        Workspace admin only. Creates or refreshes a **pending**
+        `tai_workspace_invitations` row and emails an accept link; it does **not** create
+        `tai_workspace_members`. Membership is granted only by
+        `POST /invitations/{token}/accept`. Applies to new and existing platform users
+        alike. Idempotent when the email is already an active member: returns **201** with
+        `outcome: "already_member"` and the existing row, **does not change** their role if
+        the request body role differs, and sends no email. Re-inviting a pending email
+        refreshes the token and 7-day expiry (the previous link stops working). When SMTP
+        is not configured the invitation is still created and a warning is logged.
       operationId: inviteTenantMember
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
@@ -987,11 +991,33 @@ paths:
               role: editor
       responses:
         "201":
-          description: Invited member row
+          description: Pending invitation, or the existing member row when already a member
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/TeamMemberDto"
+                $ref: "#/components/schemas/InviteTeamMemberResultDto"
+              examples:
+                invited:
+                  value:
+                    outcome: invited
+                    invitation:
+                      id: 6f1d9c0e-4d0b-4a0f-9a3e-2c1b8f4a7d55
+                      workspaceId: 9a2b7c1d-3e4f-4a5b-8c9d-0e1f2a3b4c5d
+                      workspaceName: Acme Engineering
+                      email: new.member@example.com
+                      role: editor
+                      status: pending
+                      invitedByName: Dana Admin
+                      expiresAt: "2026-08-01T12:00:00.000Z"
+                      createdAt: "2026-07-25T12:00:00.000Z"
+                alreadyMember:
+                  value:
+                    outcome: already_member
+                    member:
+                      id: 1b2c3d4e-5f60-4718-8293-a4b5c6d7e8f9
+                      name: Existing Member
+                      email: new.member@example.com
+                      role: admin
         "400":
           description: Invalid email or role
           content:
@@ -1099,6 +1125,175 @@ paths:
                     error: Cannot remove the workspace owner
                     code: workspace_owner
 
+  /workspaces/{workspaceId}/invitations:
+    get:
+      tags: [Workspace]
+      summary: List pending workspace invitations
+      description: >
+        Workspace admin only. Returns invitations still awaiting a decision so the team
+        settings page can show "pending" alongside active members. Rows whose `expiresAt`
+        has passed are flipped to `expired` on read and omitted.
+      operationId: listWorkspaceInvitations
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Pending invitations
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WorkspaceInvitationListDto"
+        "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"
+
+  /invitations/{token}:
+    get:
+      tags: [Workspace]
+      summary: Preview a workspace invitation (public)
+      description: >
+        **Unauthenticated.** Lets the SPA render the invite landing page before the invitee
+        has signed in. The invited email is **masked** (`j••••e@example.com`) so a leaked
+        link does not disclose an address. Returns `404` with a generic message for unknown,
+        revoked, or rejected tokens; a past-due `pending` invitation is flipped to `expired`
+        and returned with that status so the SPA can show a stable message.
+      operationId: getWorkspaceInvitationPreview
+      security: []
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceInvitationToken"
+      responses:
+        "200":
+          description: Invitation preview
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WorkspaceInvitationPreviewDto"
+        "404":
+          description: Unknown or no longer available invitation
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              examples:
+                notFound:
+                  value:
+                    error: This invitation link is not valid.
+                    code: invitation_not_found
+
+  /invitations/{token}/accept:
+    post:
+      tags: [Workspace]
+      summary: Accept a workspace invitation
+      description: >
+        Requires a Supabase JWT whose email matches the invited email. Creates the
+        `tai_workspace_members` row with the invited role and closes the invitation as
+        `accepted`. This is the **only** path that grants workspace membership — signing up
+        alone never does. Idempotent: re-accepting your own accepted invitation returns
+        `200` unchanged.
+      operationId: acceptWorkspaceInvitation
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceInvitationToken"
+      responses:
+        "200":
+          description: Invitation accepted; caller is now a workspace member
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WorkspaceInvitationDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Signed-in email does not match the invited email
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              examples:
+                emailMismatch:
+                  value:
+                    error: This invitation was sent to a different email address.
+                    code: invitation_email_mismatch
+        "404":
+          description: Unknown invitation token
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "409":
+          description: Invitation is no longer actionable
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              examples:
+                notPending:
+                  value:
+                    error: This invitation is no longer available.
+                    code: invitation_not_pending
+        "410":
+          description: Invitation expired
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              examples:
+                expired:
+                  value:
+                    error: This invitation has expired. Ask an admin to send a new one.
+                    code: invitation_expired
+
+  /invitations/{token}/reject:
+    post:
+      tags: [Workspace]
+      summary: Decline a workspace invitation
+      description: >
+        Requires a Supabase JWT whose email matches the invited email — anonymous decline
+        with only the token is not allowed. Closes the invitation as `rejected` and creates
+        no member row. Idempotent for an already-rejected invitation.
+      operationId: rejectWorkspaceInvitation
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceInvitationToken"
+      responses:
+        "200":
+          description: Invitation declined
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WorkspaceInvitationDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Signed-in email does not match the invited email
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "404":
+          description: Unknown invitation token
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "409":
+          description: Invitation was already accepted
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "410":
+          description: Invitation expired
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
   /workspaces/{workspaceId}/org-chart/status:
     get:
       tags: [Workspace]
@@ -7700,6 +7895,16 @@ components:
         type: string
         format: uuid
       description: Workspace member user id (`tai_users.id`).
+    WorkspaceInvitationToken:
+      name: token
+      in: path
+      required: true
+      schema:
+        type: string
+        minLength: 32
+      description: >
+        Opaque workspace invitation token from the emailed accept link. Only its SHA-256
+        hash is stored server-side; the plaintext is shown exactly once, in the email.
     PrivacyRequestId:
       name: requestId
       in: path
@@ -8029,6 +8234,100 @@ components:
           type: string
           enum: [admin, editor, viewer]
 
+    WorkspaceInvitationStatusDto:
+      type: string
+      description: >
+        `revoked` is an admin cancelling the invitation; `rejected` is the invitee
+        declining it. Both leave the invitee outside the workspace.
+      enum: [pending, accepted, expired, revoked, rejected]
+
+    WorkspaceInvitationDto:
+      type: object
+      description: Workspace invitation as seen by an authenticated admin or invitee.
+      required:
+        [id, workspaceId, workspaceName, email, role, status, expiresAt, createdAt]
+      properties:
+        id:
+          type: string
+          format: uuid
+        workspaceId:
+          type: string
+          format: uuid
+        workspaceName:
+          type: string
+        email:
+          type: string
+          description: Invited email address.
+        role:
+          type: string
+          enum: [admin, editor, viewer]
+        status:
+          $ref: "#/components/schemas/WorkspaceInvitationStatusDto"
+        invitedByName:
+          type: string
+          nullable: true
+        invitedByEmail:
+          type: string
+          nullable: true
+        expiresAt:
+          type: string
+          format: date-time
+        createdAt:
+          type: string
+          format: date-time
+        acceptedAt:
+          type: string
+          format: date-time
+          nullable: true
+
+    WorkspaceInvitationPreviewDto:
+      type: object
+      description: >
+        Unauthenticated invitation preview. `maskedEmail` is the only view of the invited
+        address; compare it to the signed-in account client-side before calling accept.
+      required: [workspaceName, role, status, maskedEmail, expiresAt]
+      properties:
+        workspaceName:
+          type: string
+        role:
+          type: string
+          enum: [admin, editor, viewer]
+        status:
+          $ref: "#/components/schemas/WorkspaceInvitationStatusDto"
+        maskedEmail:
+          type: string
+          example: j••••e@example.com
+        invitedByName:
+          type: string
+          nullable: true
+        expiresAt:
+          type: string
+          format: date-time
+
+    WorkspaceInvitationListDto:
+      type: object
+      required: [invitations]
+      properties:
+        invitations:
+          type: array
+          items:
+            $ref: "#/components/schemas/WorkspaceInvitationDto"
+
+    InviteTeamMemberResultDto:
+      type: object
+      description: >
+        Discriminated on `outcome`. `invited` carries the new pending invitation;
+        `already_member` carries the existing membership row unchanged.
+      required: [outcome]
+      properties:
+        outcome:
+          type: string
+          enum: [invited, already_member]
+        invitation:
+          $ref: "#/components/schemas/WorkspaceInvitationDto"
+        member:
+          $ref: "#/components/schemas/TeamMemberDto"
+
     EraseInsightsPersonBodyDto:
       type: object
       description: >
@@ -14644,6 +14943,8 @@ components:
         - integrations.cursor.platform_key_enabled
         - integrations.cursor.platform_key_disabled
         - member.invited
+        - member.invite_accepted
+        - member.invite_rejected
         - member.role_changed
         - member.removed
         - hris.personio.sync_started

package/package.json

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