@thinkai/tai-api-contract 2.97.0 → 2.99.0

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.97.0
+  version: 2.99.0
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -3539,6 +3539,53 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
+    post:
+      tags: [CodeInsights]
+      summary: Code Insights — enqueue Design risks analysis
+      operationId: postCodeInsightsDesignAnalyze
+      description: >
+        Enqueues an on-demand Design risks run (`run_kind=code_insights_design`) for the
+        repository. Reuses the readiness worker queue but never grades the readiness rubric.
+        Editor/admin only. Returns `409` when a design run is already queued or running for
+        the same provider slug (independent of readiness runs).
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: repoId
+          in: path
+          required: true
+          description: Internal repo UUID (`tai_workspace_repos.id`).
+          schema:
+            type: string
+            format: uuid
+      responses:
+        "202":
+          description: Design risks analysis enqueued
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CodeInsightsDesignAnalyzeResponseDto"
+        "400":
+          description: Malformed repoId, unsupported provider, or GitHub not connected
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace or repo does not exist
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "409":
+          description: An active Design risks run already exists for this repo slug
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
 
   /workspaces/{workspaceId}/integrations/ai-tool/{provider}/members:
     get:
@@ -7234,7 +7281,6 @@ paths:
         "401":
           $ref: "#/components/responses/Unauthorized"
 
-
   /workspaces/{workspaceId}/code-chat/indexes:
     get:
       tags: [CodeChat]
@@ -8886,7 +8932,7 @@ components:
         type: string
         minLength: 1
         maxLength: 512
-        pattern: '^[^/]+/[^/]+$'
+        pattern: "^[^/]+/[^/]+$"
         example: thinkai-llc/thinkai-platform-backend
     ProjectId:
       name: projectId
@@ -9281,8 +9327,7 @@ components:
     WorkspaceInvitationDto:
       type: object
       description: Workspace invitation as seen by an authenticated admin or invitee.
-      required:
-        [id, workspaceId, workspaceName, email, role, status, expiresAt, createdAt]
+      required: [id, workspaceId, workspaceName, email, role, status, expiresAt, createdAt]
       properties:
         id:
           type: string
@@ -10453,7 +10498,17 @@ components:
       properties:
         deliveryModel:
           type: string
-          enum: [auto, k8s_microservices, mobile_store, web_hosting, data_pipelines, monorepo, library, hybrid]
+          enum:
+            [
+              auto,
+              k8s_microservices,
+              mobile_store,
+              web_hosting,
+              data_pipelines,
+              monorepo,
+              library,
+              hybrid,
+            ]
         roles:
           type: object
           additionalProperties:
@@ -10468,7 +10523,17 @@ components:
       properties:
         deliveryModel:
           type: string
-          enum: [auto, k8s_microservices, mobile_store, web_hosting, data_pipelines, monorepo, library, hybrid]
+          enum:
+            [
+              auto,
+              k8s_microservices,
+              mobile_store,
+              web_hosting,
+              data_pipelines,
+              monorepo,
+              library,
+              hybrid,
+            ]
         ciProvider:
           type: string
           enum: [github_actions, jenkins, gitlab, bitbucket, hybrid, external_documented]
@@ -11026,8 +11091,7 @@ components:
     ProductivityInsightsTeamLeaderItemDto:
       type: object
       additionalProperties: false
-      required:
-        [rank, teamId, teamName, periodAvgMergedPrs]
+      required: [rank, teamId, teamName, periodAvgMergedPrs]
       properties:
         rank:
           type: integer
@@ -11205,8 +11269,7 @@ components:
     ProductivityInsightsContributorActivityDayDto:
       type: object
       additionalProperties: false
-      required:
-        [date, dayIndex, mergedPrCount, mergedPrs, absent, failureSignal, failures]
+      required: [date, dayIndex, mergedPrCount, mergedPrs, absent, failureSignal, failures]
       properties:
         date:
           type: string
@@ -11247,7 +11310,10 @@ components:
             $ref: "#/components/schemas/ProductivityInsightsContributorFailureItemDto"
         mergedPrItems:
           type: array
-          description: Optional PR rows with GitHub links when ingest stored URLs.
+          description: >
+            Optional merged PR rows for day drilldown (label, optional GitHub URL, optional
+            ship-weight score / pending flag). Includes label-only rows so unscored or
+            URL-less merges still surface ship-weight state.
           items:
             $ref: "#/components/schemas/ProductivityInsightsContributorMergedPrItemDto"
 
@@ -11261,6 +11327,12 @@ components:
         url:
           type: string
           format: uri
+        shipWeight:
+          type: number
+          description: v13 ship-weight score for this PR when scored (typically 0–10).
+        shipWeightPending:
+          type: boolean
+          description: True when this GitHub PR is still awaiting ship-weight scoring.
 
     ProductivityInsightsContributorFailureItemDto:
       type: object
@@ -11418,8 +11490,7 @@ components:
     ProductivityInsightsNeedsAttentionItemDto:
       type: object
       additionalProperties: false
-      required:
-        [rank, entityId, entityType, name, periodAvgMergedPrs]
+      required: [rank, entityId, entityType, name, periodAvgMergedPrs]
       properties:
         rank:
           type: integer
@@ -11575,8 +11646,7 @@ components:
     AiUsageSpendAggregatedTeamsSummaryDto:
       type: object
       additionalProperties: false
-      required:
-        [totalTokenCount, totalSpendCents, activeUsers, activeTools, totalEngineers]
+      required: [totalTokenCount, totalSpendCents, activeUsers, activeTools, totalEngineers]
       properties:
         totalTokenCount:
           type: integer
@@ -11787,8 +11857,7 @@ components:
     AiUsageSpendAiAssistedCodeDayDto:
       type: object
       additionalProperties: false
-      required:
-        [date, aiAssistedCodePercent, totalLoc, aiLoc, humanLoc, dataQuality]
+      required: [date, aiAssistedCodePercent, totalLoc, aiLoc, humanLoc, dataQuality]
       properties:
         date:
           type: string
@@ -11823,15 +11892,7 @@ components:
       type: object
       additionalProperties: false
       required:
-        [
-          bucketStart,
-          bucketEnd,
-          aiAssistedCodePercent,
-          totalLoc,
-          aiLoc,
-          humanLoc,
-          dataQuality,
-        ]
+        [bucketStart, bucketEnd, aiAssistedCodePercent, totalLoc, aiLoc, humanLoc, dataQuality]
       properties:
         bucketStart:
           type: string
@@ -12739,7 +12800,18 @@ components:
     AiToolMemberDetailDto:
       type: object
       additionalProperties: false
-      required: [externalId, email, isRemoved, spendCents, tokenCount, activeDays, modelBreakdown, productBreakdown, heatmap]
+      required:
+        [
+          externalId,
+          email,
+          isRemoved,
+          spendCents,
+          tokenCount,
+          activeDays,
+          modelBreakdown,
+          productBreakdown,
+          heatmap,
+        ]
       properties:
         externalId:
           type: string
@@ -12947,7 +13019,17 @@ components:
     PrivacyRequestDto:
       type: object
       required:
-        [id, referenceCode, requestType, status, intakeChannel, subjectEmail, createdAt, updatedAt, slaDueAt]
+        [
+          id,
+          referenceCode,
+          requestType,
+          status,
+          intakeChannel,
+          subjectEmail,
+          createdAt,
+          updatedAt,
+          slaDueAt,
+        ]
       properties:
         id:
           type: string
@@ -13027,7 +13109,15 @@ components:
         eventType:
           type: string
           enum:
-            [submitted, identity_verified, status_changed, assigned, export_generated, fulfillment_noted, duplicate_rejected]
+            [
+              submitted,
+              identity_verified,
+              status_changed,
+              assigned,
+              export_generated,
+              fulfillment_noted,
+              duplicate_rejected,
+            ]
         actorEmail:
           type: string
           nullable: true
@@ -13428,7 +13518,8 @@ components:
         of eligible repos. Lets the UI render per-repo "size / limit" (compare each repo's `size`
         in `GithubInstalledRepoDto` to `maxRepoSizeKb`) and workspace "N / cap" usage
         (`eligibleRepoCount` / `maxReposPerWorkspace`).
-      required: [maxRepoSizeKb, maxReposPerWorkspace, excludeArchived, excludeForks, eligibleRepoCount]
+      required:
+        [maxRepoSizeKb, maxReposPerWorkspace, excludeArchived, excludeForks, eligibleRepoCount]
       properties:
         maxRepoSizeKb:
           type: integer
@@ -14299,8 +14390,7 @@ components:
     TechStackDto:
       type: object
       additionalProperties: false
-      required:
-        [sourceControl, cicd, pm, monitoring, aiTools, security, knowledgeDocs, hrPeople]
+      required: [sourceControl, cicd, pm, monitoring, aiTools, security, knowledgeDocs, hrPeople]
       properties:
         sourceControl:
           $ref: "#/components/schemas/TechCategoryDto"
@@ -14944,7 +15034,14 @@ components:
         archivedReason:
           type: string
           nullable: true
-          enum: [github_removed, installation_disconnected, installation_replaced, superseded, user_removed]
+          enum:
+            [
+              github_removed,
+              installation_disconnected,
+              installation_replaced,
+              superseded,
+              user_removed,
+            ]
           description: Why the repo was archived. `user_removed` means excluded from Agentic Foundation scope only. Only present when `archivedAt` is set.
         eligibilityStatus:
           type: string
@@ -15140,7 +15237,14 @@ components:
         archivedReason:
           type: string
           nullable: true
-          enum: [github_removed, installation_disconnected, installation_replaced, superseded, user_removed]
+          enum:
+            [
+              github_removed,
+              installation_disconnected,
+              installation_replaced,
+              superseded,
+              user_removed,
+            ]
         eligibilityStatus:
           type: string
           enum: [eligible, ineligible]
@@ -15204,14 +15308,7 @@ components:
 
     AgenticFoundationDashboardSummaryDto:
       type: object
-      required:
-        [
-          repoCount,
-          averageOverallScore,
-          issueCount,
-          criticalIssueCount,
-          issuesByFixStatus,
-        ]
+      required: [repoCount, averageOverallScore, issueCount, criticalIssueCount, issuesByFixStatus]
       properties:
         repoCount:
           type: integer
@@ -15345,8 +15442,7 @@ components:
 
     ReadinessAuditEntryDto:
       type: object
-      required:
-        [id, occurredAt, eventType, actionLabel, actorName]
+      required: [id, occurredAt, eventType, actionLabel, actorName]
       properties:
         id:
           type: string
@@ -15575,8 +15671,7 @@ components:
 
     ReadinessFixGuideDto:
       type: object
-      required:
-        [issueId, repoId, rubricId, sourceRunId, status, markdown, criterionTitle]
+      required: [issueId, repoId, rubricId, sourceRunId, status, markdown, criterionTitle]
       properties:
         issueId:
           type: string
@@ -16182,7 +16277,8 @@ components:
 
     YourAiJourneyPrSignalsWeekDto:
       type: object
-      required: [bucketStart, bucketEnd, weekLabel, prsPerDeveloperPerWeek, changeFailureRatePercent]
+      required:
+        [bucketStart, bucketEnd, weekLabel, prsPerDeveloperPerWeek, changeFailureRatePercent]
       properties:
         bucketStart:
           type: string
@@ -16377,7 +16473,21 @@ components:
 
     YourAiJourneyAiSpendDto:
       type: object
-      required: [workspaceId, generatedAt, windowStart, windowEnd, totalSpendCents, totalTokenCount, activeUsers, aiAssistedPrRatio, prThroughputDeltaPercent, usageDeltaPercent, weeks, providers]
+      required:
+        [
+          workspaceId,
+          generatedAt,
+          windowStart,
+          windowEnd,
+          totalSpendCents,
+          totalTokenCount,
+          activeUsers,
+          aiAssistedPrRatio,
+          prThroughputDeltaPercent,
+          usageDeltaPercent,
+          weeks,
+          providers,
+        ]
       properties:
         workspaceId:
           type: string
@@ -16545,6 +16655,7 @@ components:
         - readiness.scan_completed
         - readiness.scan_failed
         - readiness.scan_partial
+        - code_insights.design_run_started
         - integrations.agent_execution.provider_changed
         - integrations.repo_eligibility.overrides_changed
         - integrations.repo_eligibility.languages_refresh_requested
@@ -16686,7 +16797,8 @@ components:
 
     WorkspaceAbsenceDto:
       type: object
-      required: [source, employeeEmail, absenceType, startDate, endDate, halfDayStart, halfDayEnd, status]
+      required:
+        [source, employeeEmail, absenceType, startDate, endDate, halfDayStart, halfDayEnd, status]
       properties:
         source:
           type: string
@@ -17354,8 +17466,15 @@ components:
       properties:
         weekStartIso: { type: string, format: date }
         mergedPrs: { type: number }
+        shipWeightSum:
+          type: number
+          description: Sum of ship-weight scores for merged PRs in this week bucket.
         ciFailRatePct: { type: number }
-        hasCiMetrics: { type: boolean, description: False when CI metrics were not available for this week bucket. }
+        hasCiMetrics:
+          {
+            type: boolean,
+            description: False when CI metrics were not available for this week bucket.,
+          }
 
     InsightsRecommendationsVelocityQuality:
       type: object
@@ -17367,6 +17486,9 @@ components:
             $ref: "#/components/schemas/InsightsVelocityQualityWeek"
         targetFailRatePct: { type: number }
         volumeGrowthPct: { type: number }
+        shipWeightVolumeGrowthPct:
+          type: number
+          description: Ship-weight volume growth vs the prior equal-length window.
 
     InsightsRecommendationsVelocityQualityResponse:
       allOf:
@@ -17655,7 +17777,19 @@ components:
 
     CodeChatIndexDto:
       type: object
-      required: [id, workspaceId, repoId, providerSlug, repoName, status, nodeCount, edgeCount, createdAt, updatedAt]
+      required:
+        [
+          id,
+          workspaceId,
+          repoId,
+          providerSlug,
+          repoName,
+          status,
+          nodeCount,
+          edgeCount,
+          createdAt,
+          updatedAt,
+        ]
       properties:
         id: { type: string, format: uuid }
         workspaceId: { type: string, format: uuid }
@@ -17882,7 +18016,19 @@ components:
 
     CodeChatWikiPageDto:
       type: object
-      required: [id, indexId, workspaceId, slug, title, bodyMd, sortOrder, sourcePaths, createdAt, updatedAt]
+      required:
+        [
+          id,
+          indexId,
+          workspaceId,
+          slug,
+          title,
+          bodyMd,
+          sortOrder,
+          sourcePaths,
+          createdAt,
+          updatedAt,
+        ]
       properties:
         id: { type: string, format: uuid }
         indexId: { type: string, format: uuid }
@@ -18281,7 +18427,19 @@ components:
 
     CodeInsightsFindingCategory:
       type: string
-      enum: [duplication, complexity, proliferation, coverage, anemic_domain, context_leak, tx_boundary, error_handling, config_cohesion, resilience_patterns]
+      enum:
+        [
+          duplication,
+          complexity,
+          proliferation,
+          coverage,
+          anemic_domain,
+          context_leak,
+          tx_boundary,
+          error_handling,
+          config_cohesion,
+          resilience_patterns,
+        ]
       description: >
         Deterministic categories (`duplication`, `complexity`, `proliferation`,
         `coverage`) plus LLM semantic detectors (`anemic_domain`, `context_leak`,
@@ -18439,7 +18597,8 @@ components:
 
     CodeInsightsRepoListItemDto:
       type: object
-      required: [repoId, repoName, language, providerSlug, webUrl, badges, findingsBySeverity, provenance]
+      required:
+        [repoId, repoName, language, providerSlug, webUrl, badges, findingsBySeverity, provenance]
       properties:
         repoId:
           type: string
@@ -18504,7 +18663,18 @@ components:
 
     CodeInsightsRepoDetailDto:
       type: object
-      required: [repoId, repoName, language, providerSlug, webUrl, metrics, hotspots, findings]
+      required:
+        [
+          repoId,
+          repoName,
+          language,
+          providerSlug,
+          webUrl,
+          metrics,
+          hotspots,
+          findings,
+          designAnalysis,
+        ]
       properties:
         repoId:
           type: string
@@ -18530,7 +18700,47 @@ components:
           type: array
           items:
             $ref: "#/components/schemas/CodeInsightsFindingDto"
-          description: Findings from the latest scan only (history is retention-bounded).
+          description: >
+            Deterministic findings from the latest metrics scan plus LLM findings from the
+            latest **succeeded** Design risks run only. Stale LLM rows from older design runs
+            are not returned.
+        designAnalysis:
+          allOf:
+            - $ref: "#/components/schemas/CodeInsightsDesignAnalysisDto"
+          nullable: true
+          description: >
+            Latest Design risks run of any status (for UI polling). Null when Design risks
+            has never been enqueued for this repo.
+
+    CodeInsightsDesignAnalysisDto:
+      type: object
+      required: [runId, status, finishedAt, errorCode, errorDetail]
+      properties:
+        runId:
+          type: string
+          format: uuid
+        status:
+          type: string
+          enum: [queued, running, succeeded, failed, partial_failed]
+        finishedAt:
+          type: string
+          format: date-time
+          nullable: true
+        errorCode:
+          type: string
+          nullable: true
+        errorDetail:
+          type: string
+          nullable: true
+
+    CodeInsightsDesignAnalyzeResponseDto:
+      type: object
+      required: [runId]
+      properties:
+        runId:
+          type: string
+          format: uuid
+          description: Enqueued Design risks run id (`tai_workspace_readiness_runs.id`).
 
     CodeInsightsOrgHotspotDto:
       allOf:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinkai/tai-api-contract",
-  "version": "2.97.0",
+  "version": "2.99.0",
   "private": false,
   "type": "module",
   "main": "dist/index.js",
@@ -20,8 +20,8 @@
   },
   "dependencies": {},
   "devDependencies": {
-    "@stoplight/spectral-cli": "^6.16.2",
-    "@types/node": "^26.1.2",
+    "@stoplight/spectral-cli": "^6.16.3",
+    "@types/node": "^26.2.0",
     "jsonpath-plus": "^10.3.0",
     "openapi-typescript": "^7.13.0",
     "typescript": "~6.0.3"