@thinkai/tai-api-contract 2.7.3 → 2.8.1

package/openapi/openapi.yaml

@@ -471,8 +471,8 @@ paths:
 
         **Typical outcomes:** Valid typed sources → `200` with `{ ok: true, workspaceId }`. Missing required
         fields for a given `type` → `400` with `error` text.
-        Unknown `type` strings (non-cursor, non-github) currently pass through to storage (lenient compatibility); only `cursor`
-        entries get strict field validation. Cursor sources enforce strict token shape (no whitespace, no `env:` prefix).
+        Unknown `type` strings (non-AI-tool, non-github) currently pass through to storage (lenient compatibility).
+        Registered AI tools (`cursor`, `claude`) get strict field validation (no whitespace, no `env:` prefix on tokens).
       operationId: putTenantSources
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
@@ -489,6 +489,7 @@ paths:
                   items:
                     anyOf:
                       - $ref: "#/components/schemas/CursorSourceDto"
+                      - $ref: "#/components/schemas/ClaudeSourceDto"
                       - $ref: "#/components/schemas/TenantSourceEntryDto"
             examples:
               cursorAndJira:
@@ -564,15 +565,16 @@ paths:
         200 — upstream auth, rate-limit, and network failures surface as
         `{ success: false, error }` so the SPA can render an inline error.
 
-        Currently only `type: cursor` is verified end-to-end (Cursor Admin API,
-        HTTP Basic against `https://api.cursor.com`; optional `baseUrl` in the body is deprecated and ignored).
-        Other types report
+        Registered AI tools are verified end-to-end: `cursor` (Cursor Admin API at
+        `https://api.cursor.com`, HTTP Basic; optional `baseUrl` is deprecated and ignored) and
+        `claude` (Anthropic Admin API at `https://api.anthropic.com`, `X-Api-Key` with an
+        organization Admin API key `sk-ant-admin...`). Other types report
         `{ success: false, error: "unsupported_type" }`. Documented `error`
-        codes for cursor: `invalid_token`, `rate_limited`, `network_error`.
+        codes for AI tool verifiers: `invalid_token`, `rate_limited`, `network_error`.
 
         **Typical outcomes:** Malformed body, missing `type`, invalid `type`, or missing required fields for the
         declared type → `400` with `{ error: "..." }`. Well-formed body with bad credentials or unreachable
-        service → `200` with `{ success: false, error: "..." }` (Cursor verifier and non-cursor paths as documented above).
+        service → `200` with `{ success: false, error: "..." }`.
       operationId: postTenantSourceTest
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
@@ -583,6 +585,7 @@ paths:
             schema:
               anyOf:
                 - $ref: "#/components/schemas/CursorSourceDto"
+                - $ref: "#/components/schemas/ClaudeSourceDto"
                 - $ref: "#/components/schemas/TenantSourceEntryDto"
             examples:
               cursorValid:
@@ -590,8 +593,13 @@ paths:
                 value:
                   type: cursor
                   token: cursor_api_key_example
+              claudeValid:
+                summary: Claude (Anthropic Admin API) source for connection test
+                value:
+                  type: claude
+                  token: sk-ant-admin-example-key
               githubShape:
-                summary: GitHub-shaped body (non-cursor types return unsupported_type unless extended)
+                summary: GitHub-shaped body (non-AI-tool types return unsupported_type unless extended)
                 value:
                   type: github
                   owner: org
@@ -611,7 +619,7 @@ paths:
                 failure:
                   value:
                     success: false
-                    error: invalid_token
+                    error: "invalid_token"
         "400":
           description: Invalid body or missing env for token refs
           content:
@@ -1686,7 +1694,7 @@ paths:
           required: true
           schema:
             type: string
-            enum: [cursor]
+            enum: [cursor, claude]
       responses:
         "200":
           description: Refresh result
@@ -1698,7 +1706,7 @@ paths:
                 ok:
                   value: { ok: true }
                 invalid_token:
-                  value: { ok: false, error: invalid_token }
+                  value: { ok: false, error: "invalid_token" }
         "401":
           $ref: "#/components/responses/Unauthorized"
         "403":
@@ -1711,7 +1719,7 @@ paths:
                 $ref: "#/components/schemas/AiToolRefreshResponseDto"
               example:
                 ok: false
-                error: no_source
+                error: "no_source"
         "409":
           description: Refresh already in progress
           content:
@@ -1720,7 +1728,7 @@ paths:
                 $ref: "#/components/schemas/AiToolRefreshResponseDto"
               example:
                 ok: false
-                error: already_in_progress
+                error: "already_in_progress"
 
   /workspaces/{workspaceId}/integrations/ai-tool/{provider}/seats:
     get:
@@ -1734,7 +1742,7 @@ paths:
           required: true
           schema:
             type: string
-            enum: [cursor]
+            enum: [cursor, claude]
       responses:
         "200":
           description: Seats
@@ -1765,7 +1773,7 @@ paths:
           required: true
           schema:
             type: string
-            enum: [cursor]
+            enum: [cursor, claude]
         - name: from
           in: query
           required: false
@@ -1813,7 +1821,7 @@ paths:
           required: true
           schema:
             type: string
-            enum: [cursor]
+            enum: [cursor, claude]
         - name: cycleStartMs
           in: query
           required: false
@@ -1850,7 +1858,7 @@ paths:
           required: true
           schema:
             type: string
-            enum: [cursor]
+            enum: [cursor, claude]
       responses:
         "200":
           description: Refresh status
@@ -1874,7 +1882,7 @@ paths:
                 $ref: "#/components/schemas/AiToolRefreshResponseDto"
               example:
                 ok: false
-                error: no_source
+                error: "no_source"
 
   /integrations/github/callback:
     get:
@@ -2348,6 +2356,109 @@ paths:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
 
+  /workspaces/{workspaceId}/readiness/repos/{repoId}/runs:
+    get:
+      tags: [RepositoryReadiness]
+      summary: Paginated readiness run history for one repository
+      description: >
+        Append-only scan history for charts on repo detail. Ordered by scan finish time
+        (or `createdAt` when still in progress). Use `cursor` from the previous response for
+        the next page. Failed and `partial_failed` runs are included with nullable `overallScore`.
+      operationId: listReadinessRepoRuns
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/RepoId"
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 25
+        - name: order
+          in: query
+          schema:
+            type: string
+            enum: [asc, desc]
+            default: desc
+        - name: cursor
+          in: query
+          description: Opaque cursor from a prior response `nextCursor` field.
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Run history page
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ReadinessRepoRunListDto"
+        "400":
+          description: Invalid pagination query
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace or repository not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/readiness/score-history:
+    get:
+      tags: [RepositoryReadiness]
+      summary: Workspace score time-series for all repositories
+      description: >
+        Returns succeeded runs with stored `overallScore` per repo in one call (avoids N+1).
+        Points are ordered ascending by `finishedAt` within each repo. Omit failed and
+        `partial_failed` runs. Use `since` to bound the window; `limitPerRepo` caps points per repo
+        (most recent first, then returned oldest-to-newest within the cap).
+      operationId: getReadinessScoreHistory
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: since
+          in: query
+          description: ISO-8601 lower bound on `finishedAt` (inclusive).
+          schema:
+            type: string
+            format: date-time
+        - name: limitPerRepo
+          in: query
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 200
+            default: 50
+      responses:
+        "200":
+          description: Score history grouped by repository
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WorkspaceReadinessScoreHistoryDto"
+        "400":
+          description: Invalid query
+          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}/agentic-foundation/dashboard:
     get:
       tags: [AgenticFoundation]
@@ -2439,6 +2550,7 @@ paths:
                             maxScore: 3
                             issues: []
                         lastAnalyzed: "2026-05-12T12:00:00.000Z"
+                        connectedAt: "2026-05-01T10:00:00.000Z"
                         teamId: null
                         provider:
                           kind: github
@@ -3929,6 +4041,29 @@ components:
             and always uses the Cursor Admin API host. Kept so older clients can submit payloads unchanged.
           default: "https://api.cursor.com"
 
+    ClaudeSourceDto:
+      type: object
+      description: >
+        Claude (Anthropic) source entry for `PUT /workspaces/{workspaceId}/sources`
+        and `POST /workspaces/{workspaceId}/sources/test`. The `token` field
+        carries a literal Organization Admin API key on writes (`sk-ant-admin...`);
+        reads from `GET /workspaces/{workspaceId}/config` redact it to `***`.
+        Runtime calls use the Anthropic Admin API at `https://api.anthropic.com`.
+        Provision keys in Claude Console → Organization settings (admin role required).
+      required: [type, token]
+      additionalProperties: false
+      properties:
+        type:
+          type: string
+          enum: [claude]
+        token:
+          type: string
+          minLength: 1
+          maxLength: 512
+          description: >
+            Anthropic Organization Admin API key (literal, must start with sk-ant-admin).
+            Standard API keys (sk-ant-api...) are rejected. Whitespace and `env:` prefix are rejected.
+
     WorkspaceConfigDto:
       type: object
       required: [sources]
@@ -5658,6 +5793,92 @@ components:
           items:
             $ref: "#/components/schemas/ReadinessIssueDto"
 
+    ReadinessRepoRunHistoryItemDto:
+      type: object
+      required: [runId, status, overallScore, createdAt, finishedAt]
+      properties:
+        runId:
+          type: string
+          format: uuid
+        status:
+          $ref: "#/components/schemas/ReadinessRunStatusDto"
+        overallScore:
+          type: integer
+          minimum: 0
+          maximum: 100
+          nullable: true
+          description: Present for succeeded runs after migration 050; null otherwise.
+        createdAt:
+          type: string
+          format: date-time
+        finishedAt:
+          type: string
+          format: date-time
+          nullable: true
+
+    ReadinessRepoRunListDto:
+      type: object
+      required: [items, limit, nextCursor]
+      properties:
+        items:
+          type: array
+          items:
+            $ref: "#/components/schemas/ReadinessRepoRunHistoryItemDto"
+        limit:
+          type: integer
+          minimum: 1
+          maximum: 100
+        nextCursor:
+          type: string
+          nullable: true
+          description: Pass as `cursor` query param to fetch the next page; null when no more rows.
+
+    ReadinessScoreHistoryPointDto:
+      type: object
+      required: [finishedAt, overallScore]
+      properties:
+        finishedAt:
+          type: string
+          format: date-time
+        overallScore:
+          type: integer
+          minimum: 0
+          maximum: 100
+
+    ReadinessRepoScoreHistoryDto:
+      type: object
+      required: [repoId, repoName, connectedAt, points]
+      properties:
+        repoId:
+          type: string
+          format: uuid
+        repoName:
+          type: string
+          maxLength: 256
+        connectedAt:
+          type: string
+          format: date-time
+          description: When the repository was first materialized in the workspace (GitHub connect).
+        points:
+          type: array
+          items:
+            $ref: "#/components/schemas/ReadinessScoreHistoryPointDto"
+
+    WorkspaceReadinessScoreHistoryDto:
+      type: object
+      required: [workspaceId, generatedAt, repos]
+      properties:
+        workspaceId:
+          type: string
+          format: uuid
+        generatedAt:
+          type: string
+          format: date-time
+        repos:
+          type: array
+          items:
+            $ref: "#/components/schemas/ReadinessRepoScoreHistoryDto"
+
     RepoReadinessScoreDto:
       type: object
       required:
@@ -5667,6 +5888,7 @@ components:
         - overallScore
         - dimensions
         - lastAnalyzed
+        - connectedAt
         - provider
         - analysisStatus
       properties:
@@ -5691,6 +5913,10 @@ components:
         lastAnalyzed:
           type: string
           format: date-time
+        connectedAt:
+          type: string
+          format: date-time
+          description: First time this repository was materialized in the workspace (GitHub connect).
         teamId:
           type: string
           format: uuid

package/package.json

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