@thinkai/tai-api-contract 2.5.16 → 2.6.0

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.5.16
+  version: 2.6.0
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -50,6 +50,8 @@ tags:
     description: Org chart import via storage path (§14)
   - name: AgenticFoundation
     description: Agentic Foundation pillars (epic #278); reads stored repository readiness snapshots
+  - name: YourAiJourney
+    description: Your AI Journey dashboard aggregators (epic #267); composes readiness, metrics, and AI-spend data for the /dashboard page
 
 paths:
   /me:
@@ -138,6 +140,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 +153,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 +189,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 +199,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 +240,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 +285,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:
@@ -2986,6 +3064,272 @@ paths:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
 
+  # ── Your AI Journey (/dashboard) — epic #267 ─────────────────────────────
+
+  /workspaces/{workspaceId}/your-ai-journey/analytics:
+    get:
+      tags: [YourAiJourney]
+      summary: Combined analytics summary for the /dashboard page
+      description: >
+        Returns a single aggregated payload combining journey step progress, readiness summary,
+        and PR-signal headline metrics. Covers issue #268. Results are cached for 60 seconds.
+      operationId: getYourAiJourneyAnalytics
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Analytics summary
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/YourAiJourneyAnalyticsDto"
+        "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}/your-ai-journey/pr-signals:
+    get:
+      tags: [YourAiJourney]
+      summary: Weekly PR velocity and change-failure-rate time series
+      description: >
+        Returns a per-week time series of PR throughput and DORA change-failure-rate metrics,
+        sourced from stored dashboard metrics. Covers issue #269. Results are cached for 60 seconds.
+      operationId: getYourAiJourneyPrSignals
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 52
+            default: 8
+          description: Number of weekly buckets to return (1–52; default 8).
+      responses:
+        "200":
+          description: Weekly PR signals
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/YourAiJourneyPrSignalsDto"
+        "400":
+          description: Invalid query parameter (limit out of range)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "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}/your-ai-journey/readiness/aggregate:
+    get:
+      tags: [YourAiJourney]
+      summary: Per-dimension readiness aggregate across all repos
+      description: >
+        Aggregates stored readiness scores across all workspace repos by dimension.
+        Covers issue #270. Results are cached for 60 seconds.
+      operationId: getYourAiJourneyReadinessAggregate
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Readiness aggregate
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/YourAiJourneyReadinessAggregateDto"
+        "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}/your-ai-journey/journey/progress:
+    get:
+      tags: [YourAiJourney]
+      summary: Workspace journey step completion
+      description: >
+        Returns the workspace-scoped journey progress state. Returns an empty `completedSteps`
+        list with a synthetic `updatedAt` if no row exists yet. Covers issue #271.
+      operationId: getYourAiJourneyProgress
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Journey progress
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/JourneyProgressDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+    put:
+      tags: [YourAiJourney]
+      summary: Replace workspace journey completed steps
+      description: >
+        Idempotent replace-all of completed route strings for the workspace journey.
+        Requires editor role. Covers issue #271.
+      operationId: putYourAiJourneyProgress
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/JourneyProgressUpdateDto"
+      responses:
+        "200":
+          description: Saved progress
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/JourneyProgressDto"
+        "400":
+          description: Body fails validation (non-array, invalid entries, too many steps)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "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}/your-ai-journey/agentic-foundation:
+    get:
+      tags: [YourAiJourney]
+      summary: Agentic foundation dashboard slice for /dashboard
+      description: >
+        Returns the same `AgenticFoundationDashboardDto` payload as
+        `GET /agentic-foundation/dashboard`, scoped to the /dashboard page context.
+        Covers issue #272. Results are cached for 60 seconds.
+      operationId: getYourAiJourneyAgenticFoundation
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Agentic foundation dashboard
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AgenticFoundationDashboardDto"
+        "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}/your-ai-journey/productivity:
+    get:
+      tags: [YourAiJourney]
+      summary: Workspace productivity metrics for /dashboard
+      description: >
+        Returns the most recent stored dashboard productivity metrics snapshot that overlaps the
+        requested window (defaults to the trailing 7 days). Same schema as
+        `GET /dashboard/productivity`. Covers issue #273. Results are cached for 60 seconds.
+      operationId: getYourAiJourneyProductivity
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: windowEnd
+          in: query
+          schema:
+            type: string
+            format: date-time
+          description: Upper bound of the requested window (ISO 8601; defaults to now).
+      responses:
+        "200":
+          description: Productivity metrics snapshot
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DashboardProductivityDto"
+        "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}/your-ai-journey/ai-spend:
+    get:
+      tags: [YourAiJourney]
+      summary: AI tool spend and usage aggregated by week and provider
+      description: >
+        Returns token usage and spend aggregated from connected AI tool sources (e.g. Cursor)
+        over the requested range, broken down by week and provider. Covers issue #274.
+        Results are cached for 60 seconds.
+      operationId: getYourAiJourneyAiSpend
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: rangeId
+          in: query
+          schema:
+            type: string
+            enum: [4w, 8w, q]
+            default: 4w
+          description: Time range — `4w` (4 weeks), `8w` (8 weeks), or `q` (quarter, 12 weeks).
+      responses:
+        "200":
+          description: AI spend aggregation
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/YourAiJourneyAiSpendDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
 components:
   securitySchemes:
     bearerAuth:
@@ -3020,6 +3364,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 +3413,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 +3423,7 @@ components:
       properties:
         id:
           type: string
+          format: uuid
         name:
           type: string
         email:
@@ -3536,6 +3892,12 @@ components:
           type: string
         teamName:
           type: string
+        notInOrgChart:
+          type: boolean
+          description: True when the contributor GitHub login is not mapped in the org chart.
+        githubLogin:
+          type: string
+          description: GitHub login for unattributed contributors (when notInOrgChart is true).
         weeks:
           type: array
           items:
@@ -3559,7 +3921,7 @@ components:
           format: date-time
         weeks:
           type: array
-          description: Portfolio aggregate merged PR counts (sum of filtered contributors per week).
+          description: Portfolio aggregate merged PR counts from org-scope metrics (all merged PRs in window).
           items:
             $ref: "#/components/schemas/ProductivityInsightsMergedPrTrendWeekDto"
         contributors:
@@ -5525,3 +5887,219 @@ components:
         storagePath:
           type: string
           description: Path in `org-charts` bucket after Supabase upload
+
+    # ── Your AI Journey schemas ─────────────────────────────────────────────
+
+    YourAiJourneyPrSignalsWeekDto:
+      type: object
+      required: [bucketStart, bucketEnd, weekLabel, prsPerDeveloperPerWeek, changeFailureRatePercent]
+      properties:
+        bucketStart:
+          type: string
+          format: date-time
+        bucketEnd:
+          type: string
+          format: date-time
+        weekLabel:
+          type: string
+          description: Display label in MM/DD format.
+        prsPerDeveloperPerWeek:
+          type: number
+        changeFailureRatePercent:
+          type: number
+
+    YourAiJourneyPrSignalsDto:
+      type: object
+      required: [workspaceId, generatedAt, windowStart, windowEnd, weeks, summary]
+      properties:
+        workspaceId:
+          type: string
+          format: uuid
+        generatedAt:
+          type: string
+          format: date-time
+        windowStart:
+          type: string
+          format: date-time
+        windowEnd:
+          type: string
+          format: date-time
+        weeks:
+          type: array
+          items:
+            $ref: "#/components/schemas/YourAiJourneyPrSignalsWeekDto"
+        summary:
+          type: object
+          required: [avgPrsPerDeveloperPerWeek, avgFailureRatePercent, prVelocityDeltaPercent]
+          properties:
+            avgPrsPerDeveloperPerWeek:
+              type: number
+            avgFailureRatePercent:
+              type: number
+            prVelocityDeltaPercent:
+              type: number
+
+    YourAiJourneyReadinessDimensionDto:
+      type: object
+      required: [dimensionId, name, totalScore, maxScore, percent]
+      properties:
+        dimensionId:
+          type: string
+        name:
+          type: string
+        totalScore:
+          type: number
+        maxScore:
+          type: number
+        percent:
+          type: number
+          description: Rounded percentage 0–100.
+
+    YourAiJourneyReadinessAggregateDto:
+      type: object
+      required: [workspaceId, generatedAt, dimensions, summary]
+      properties:
+        workspaceId:
+          type: string
+          format: uuid
+        generatedAt:
+          type: string
+          format: date-time
+        dimensions:
+          type: array
+          items:
+            $ref: "#/components/schemas/YourAiJourneyReadinessDimensionDto"
+        summary:
+          type: object
+          required: [avgScore, repoCount, fixRate, totalOpenIssues, totalFixedIssues]
+          properties:
+            avgScore:
+              type: number
+            repoCount:
+              type: integer
+            fixRate:
+              type: number
+            totalOpenIssues:
+              type: integer
+            totalFixedIssues:
+              type: integer
+
+    YourAiJourneyAnalyticsDto:
+      type: object
+      required: [workspaceId, generatedAt, windowStart, windowEnd, journey, readiness, prSignals]
+      properties:
+        workspaceId:
+          type: string
+          format: uuid
+        generatedAt:
+          type: string
+          format: date-time
+        windowStart:
+          type: string
+          format: date-time
+        windowEnd:
+          type: string
+          format: date-time
+        journey:
+          type: object
+          required: [completedSteps, updatedAt]
+          properties:
+            completedSteps:
+              type: array
+              items:
+                type: string
+            updatedAt:
+              type: string
+              format: date-time
+              nullable: true
+        readiness:
+          type: object
+          required: [avgScore, repoCount, fixRate, totalOpenIssues, totalFixedIssues]
+          properties:
+            avgScore:
+              type: number
+            repoCount:
+              type: integer
+            fixRate:
+              type: number
+            totalOpenIssues:
+              type: integer
+            totalFixedIssues:
+              type: integer
+        prSignals:
+          type: object
+          required: [avgPrsPerDeveloperPerWeek, prVelocityDeltaPercent, avgFailureRatePercent]
+          properties:
+            avgPrsPerDeveloperPerWeek:
+              type: number
+            prVelocityDeltaPercent:
+              type: number
+            avgFailureRatePercent:
+              type: number
+
+    YourAiJourneyAiSpendWeekDto:
+      type: object
+      required: [bucketStart, bucketEnd, weekLabel, mergedPrCount, tokenCount]
+      properties:
+        bucketStart:
+          type: string
+          format: date-time
+        bucketEnd:
+          type: string
+          format: date-time
+        weekLabel:
+          type: string
+        mergedPrCount:
+          type: integer
+        tokenCount:
+          type: integer
+
+    YourAiJourneyAiSpendDto:
+      type: object
+      required: [workspaceId, generatedAt, windowStart, windowEnd, totalSpendCents, totalTokenCount, activeUsers, aiAssistedPrRatio, prThroughputDeltaPercent, usageDeltaPercent, weeks, providers]
+      properties:
+        workspaceId:
+          type: string
+          format: uuid
+        generatedAt:
+          type: string
+          format: date-time
+        windowStart:
+          type: string
+          format: date-time
+        windowEnd:
+          type: string
+          format: date-time
+        totalSpendCents:
+          type: integer
+        totalTokenCount:
+          type: integer
+        activeUsers:
+          type: integer
+        aiAssistedPrRatio:
+          type: number
+          description: Fraction 0–1 of PRs that are AI-assisted.
+        prThroughputDeltaPercent:
+          type: number
+        usageDeltaPercent:
+          type: number
+        weeks:
+          type: array
+          items:
+            $ref: "#/components/schemas/YourAiJourneyAiSpendWeekDto"
+        providers:
+          type: array
+          items:
+            type: object
+            required: [providerId, providerName, tokenCount, spendCents, activeUsers]
+            properties:
+              providerId:
+                type: string
+              providerName:
+                type: string
+              tokenCount:
+                type: integer
+              spendCents:
+                type: integer
+              activeUsers:
+                type: integer