@thinkai/tai-api-contract 2.8.5 → 2.9.0

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.8.4
+  version: 2.9.0
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -3142,6 +3142,74 @@ paths:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
 
+  /workspaces/{workspaceId}/cursor/platform-key-consent:
+    put:
+      tags: [Integrations]
+      summary: Enable or disable ThinkAI platform Cursor key opt-in
+      description: >
+        Explicitly enable or disable use of ThinkAI's platform Cursor execution key for readiness
+        scans. When enabled and the workspace has no `executionToken` configured, the platform key
+        is used and tracked for billing. Requires workspace editor or admin role.
+      operationId: putCursorPlatformKeyConsent
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [enabled]
+              properties:
+                enabled:
+                  type: boolean
+                  description: >
+                    true to opt in to ThinkAI platform Cursor key (additional cost applies);
+                    false to opt out.
+      responses:
+        "200":
+          description: Consent updated
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [ok]
+                properties:
+                  ok:
+                    type: boolean
+        "400":
+          description: Invalid request body
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+
+  /workspaces/{workspaceId}/readiness/cursor-key-usage:
+    get:
+      tags: [RepositoryReadiness]
+      summary: Get Cursor key usage stats for this workspace
+      description: >
+        Returns per-workspace counts of readiness runs that used the ThinkAI platform Cursor key
+        vs. the workspace's own execution key. Member-level access.
+      operationId: getCursorKeyUsage
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Cursor key usage stats
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CursorKeyUsageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+
   /workspaces/{workspaceId}/squad:
     get:
       tags: [SquadProjects]
@@ -4125,11 +4193,13 @@ components:
     CursorSourceDto:
       type: object
       description: >
-        Cursor (AI Tools) source entry for `PUT /workspaces/{workspaceId}/sources`
-        and `POST /workspaces/{workspaceId}/sources/test`. The `token` field
-        carries a literal Cursor API key on writes; reads from
-        `GET /workspaces/{workspaceId}/config` redact it to `***`.
-        Runtime calls use the Cursor Admin API at `https://api.cursor.com` (HTTP Basic); do not rely on `baseUrl`.
+        Cursor source entry for `PUT /workspaces/{workspaceId}/sources`
+        and `POST /workspaces/{workspaceId}/sources/test`.
+        Two distinct keys: Admin API key (`token`) for insights sync;
+        Execution key (`executionToken`) for readiness scanner and Agent CLI.
+        On writes both fields accept literal key values; reads from
+        `GET /workspaces/{workspaceId}/config` return a `CursorSourceConfigDto`
+        shape (`hasToken` / `hasExecutionToken` booleans) — raw values are never returned.
       required: [type, token]
       additionalProperties: false
       properties:
@@ -4140,7 +4210,18 @@ components:
           type: string
           minLength: 1
           maxLength: 256
-          description: Cursor API key (literal). Whitespace and `env:` prefix are rejected.
+          description: >
+            Cursor Admin API key (literal). Used for seats/spend/usage insights sync only.
+            Whitespace and `env:` prefix are rejected.
+        executionToken:
+          type: string
+          minLength: 1
+          maxLength: 256
+          description: >
+            Cursor execution key (literal). Used for the readiness scanner and Agent CLI.
+            This is a Cursor user API key or service account key — NOT the Admin API key.
+            Omit if using the ThinkAI platform key (requires `cursorPlatformKeyEnabled` on the workspace).
+            Whitespace and `env:` prefix are rejected.
         baseUrl:
           type: string
           deprecated: true
@@ -4149,6 +4230,28 @@ components:
             and always uses the Cursor Admin API host. Kept so older clients can submit payloads unchanged.
           default: "https://api.cursor.com"
 
+    CursorSourceConfigDto:
+      type: object
+      description: >
+        Redacted Cursor source returned by `GET /workspaces/{workspaceId}/config`.
+        `hasToken` and `hasExecutionToken` indicate which keys are stored.
+        Raw values are never returned.
+      required: [type, hasToken, hasExecutionToken]
+      additionalProperties: false
+      properties:
+        type:
+          type: string
+          enum: [cursor]
+        hasToken:
+          type: boolean
+          description: Whether the Admin API key (`token`) is stored for this workspace.
+        hasExecutionToken:
+          type: boolean
+          description: >
+            Whether the execution key is stored. If false and `cursorPlatformKeyEnabled` is true
+            in `WorkspaceConfigDto`, the platform key will be used for readiness runs
+            (additional cost applies).
+
     ClaudeSourceDto:
       type: object
       description: >
@@ -4188,6 +4291,12 @@ components:
           type: string
           nullable: true
           enum: [us, eu, me]
+        cursorPlatformKeyEnabled:
+          type: boolean
+          description: >
+            When true, readiness runs may use the ThinkAI platform Cursor key if this
+            workspace has no `executionToken` configured. Additional cost applies.
+            Requires explicit opt-in via `PUT /workspaces/{workspaceId}/cursor/platform-key-consent`.
 
     TestConnectionResponseDto:
       type: object
@@ -4197,6 +4306,35 @@ components:
           type: boolean
         error:
           type: string
+        executionKeyValid:
+          type: boolean
+          nullable: true
+          description: >
+            Present when `executionToken` was included in the test request.
+            `true` = key passed save-time validation (format + not-admin-key check).
+            `false` = key failed validation (see `executionKeyError` for detail).
+            `null` = `executionToken` was not provided.
+        executionKeyError:
+          type: string
+          nullable: true
+          description: Error detail when `executionKeyValid` is false.
+
+    CursorKeyUsageDto:
+      type: object
+      required: [platformKeyRunsThisMonth, platformKeyRunsTotal, workspaceKeyRunsTotal]
+      properties:
+        platformKeyRunsThisMonth:
+          type: integer
+          minimum: 0
+          description: Readiness runs this calendar month that used the ThinkAI platform Cursor key.
+        platformKeyRunsTotal:
+          type: integer
+          minimum: 0
+          description: All-time readiness runs that used the ThinkAI platform Cursor key.
+        workspaceKeyRunsTotal:
+          type: integer
+          minimum: 0
+          description: All-time readiness runs that used the workspace's own execution key.
 
     AiToolSeatDto:
       type: object
@@ -5897,6 +6035,15 @@ components:
           type: string
           format: date-time
           nullable: true
+        cursorKeySource:
+          type: string
+          nullable: true
+          enum: [workspace_execution_token, platform_env_key]
+          description: >
+            Which Cursor execution key was used for this run.
+            `workspace_execution_token`: workspace provided its own execution key.
+            `platform_env_key`: ThinkAI platform key was used (opt-in required; additional cost applies).
+            `null`: run did not reach the Cursor agent stage.
 
     ReadinessCriteriaSummaryDto:
       type: object
@@ -6030,6 +6177,18 @@ components:
           nullable: true
           description: Pass as `cursor` query param to fetch the next page; null when no more rows.
 
+    ReadinessScoreHistoryDimensionScoreDto:
+      type: object
+      required: [dimensionId, scorePercent]
+      properties:
+        dimensionId:
+          $ref: "#/components/schemas/ReadinessDimensionId"
+        scorePercent:
+          type: integer
+          minimum: 0
+          maximum: 100
+          description: Dimension score as a percentage (0–100) for this scan run.
+
     ReadinessScoreHistoryPointDto:
       type: object
       required: [finishedAt, overallScore]
@@ -6041,6 +6200,11 @@ components:
           type: integer
           minimum: 0
           maximum: 100
+        dimensionScores:
+          type: array
+          items:
+            $ref: "#/components/schemas/ReadinessScoreHistoryDimensionScoreDto"
+          description: Per-dimension percentages captured on this scan run.
 
     ReadinessRepoScoreHistoryDto:
       type: object

package/package.json

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

package/src/generated/openapi.ts

@@ -1239,6 +1239,46 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/workspaces/{workspaceId}/cursor/platform-key-consent": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        /**
+         * Enable or disable ThinkAI platform Cursor key opt-in
+         * @description Explicitly enable or disable use of ThinkAI's platform Cursor execution key for readiness scans. When enabled and the workspace has no `executionToken` configured, the platform key is used and tracked for billing. Requires workspace editor or admin role.
+         */
+        put: operations["putCursorPlatformKeyConsent"];
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/workspaces/{workspaceId}/readiness/cursor-key-usage": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get Cursor key usage stats for this workspace
+         * @description Returns per-workspace counts of readiness runs that used the ThinkAI platform Cursor key vs. the workspace's own execution key. Member-level access.
+         */
+        get: operations["getCursorKeyUsage"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/workspaces/{workspaceId}/squad": {
         parameters: {
             query?: never;
@@ -1653,12 +1693,14 @@ export interface components {
         } & {
             [key: string]: unknown;
         };
-        /** @description Cursor (AI Tools) source entry for `PUT /workspaces/{workspaceId}/sources` and `POST /workspaces/{workspaceId}/sources/test`. The `token` field carries a literal Cursor API key on writes; reads from `GET /workspaces/{workspaceId}/config` redact it to `***`. Runtime calls use the Cursor Admin API at `https://api.cursor.com` (HTTP Basic); do not rely on `baseUrl`. */
+        /** @description Cursor source entry for `PUT /workspaces/{workspaceId}/sources` and `POST /workspaces/{workspaceId}/sources/test`. Two distinct keys: Admin API key (`token`) for insights sync; Execution key (`executionToken`) for readiness scanner and Agent CLI. On writes both fields accept literal key values; reads from `GET /workspaces/{workspaceId}/config` return a `CursorSourceConfigDto` shape (`hasToken` / `hasExecutionToken` booleans) — raw values are never returned. */
         CursorSourceDto: {
             /** @enum {string} */
             type: "cursor";
-            /** @description Cursor API key (literal). Whitespace and `env:` prefix are rejected. */
+            /** @description Cursor Admin API key (literal). Used for seats/spend/usage insights sync only. Whitespace and `env:` prefix are rejected. */
             token: string;
+            /** @description Cursor execution key (literal). Used for the readiness scanner and Agent CLI. This is a Cursor user API key or service account key — NOT the Admin API key. Omit if using the ThinkAI platform key (requires `cursorPlatformKeyEnabled` on the workspace). Whitespace and `env:` prefix are rejected. */
+            executionToken?: string;
             /**
              * @deprecated
              * @description Deprecated. Historically suggested an API base URL; the server ignores this field and always uses the Cursor Admin API host. Kept so older clients can submit payloads unchanged.
@@ -1666,6 +1708,15 @@ export interface components {
              */
             baseUrl: string;
         };
+        /** @description Redacted Cursor source returned by `GET /workspaces/{workspaceId}/config`. `hasToken` and `hasExecutionToken` indicate which keys are stored. Raw values are never returned. */
+        CursorSourceConfigDto: {
+            /** @enum {string} */
+            type: "cursor";
+            /** @description Whether the Admin API key (`token`) is stored for this workspace. */
+            hasToken: boolean;
+            /** @description Whether the execution key is stored. If false and `cursorPlatformKeyEnabled` is true in `WorkspaceConfigDto`, the platform key will be used for readiness runs (additional cost applies). */
+            hasExecutionToken: boolean;
+        };
         /** @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). */
         ClaudeSourceDto: {
             /** @enum {string} */
@@ -1678,10 +1729,24 @@ export interface components {
             orgChart?: components["schemas"]["ScoringOrgChartDto"] | null;
             /** @enum {string|null} */
             region?: "us" | "eu" | "me" | null;
+            /** @description When true, readiness runs may use the ThinkAI platform Cursor key if this workspace has no `executionToken` configured. Additional cost applies. Requires explicit opt-in via `PUT /workspaces/{workspaceId}/cursor/platform-key-consent`. */
+            cursorPlatformKeyEnabled?: boolean;
         };
         TestConnectionResponseDto: {
             success: boolean;
             error?: string;
+            /** @description Present when `executionToken` was included in the test request. `true` = key passed save-time validation (format + not-admin-key check). `false` = key failed validation (see `executionKeyError` for detail). `null` = `executionToken` was not provided. */
+            executionKeyValid?: boolean | null;
+            /** @description Error detail when `executionKeyValid` is false. */
+            executionKeyError?: string | null;
+        };
+        CursorKeyUsageDto: {
+            /** @description Readiness runs this calendar month that used the ThinkAI platform Cursor key. */
+            platformKeyRunsThisMonth: number;
+            /** @description All-time readiness runs that used the ThinkAI platform Cursor key. */
+            platformKeyRunsTotal: number;
+            /** @description All-time readiness runs that used the workspace's own execution key. */
+            workspaceKeyRunsTotal: number;
         };
         AiToolSeatDto: {
             externalId: string;
@@ -2449,6 +2514,11 @@ export interface components {
             createdAt: string;
             /** Format: date-time */
             finishedAt: string | null;
+            /**
+             * @description Which Cursor execution key was used for this run. `workspace_execution_token`: workspace provided its own execution key. `platform_env_key`: ThinkAI platform key was used (opt-in required; additional cost applies). `null`: run did not reach the Cursor agent stage.
+             * @enum {string|null}
+             */
+            cursorKeySource?: "workspace_execution_token" | "platform_env_key" | null;
         };
         ReadinessCriteriaSummaryDto: {
             total: number;
@@ -2505,10 +2575,17 @@ export interface components {
             /** @description Pass as `cursor` query param to fetch the next page; null when no more rows. */
             nextCursor: string | null;
         };
+        ReadinessScoreHistoryDimensionScoreDto: {
+            dimensionId: components["schemas"]["ReadinessDimensionId"];
+            /** @description Dimension score as a percentage (0–100) for this scan run. */
+            scorePercent: number;
+        };
         ReadinessScoreHistoryPointDto: {
             /** Format: date-time */
             finishedAt: string;
             overallScore: number;
+            /** @description Per-dimension percentages captured on this scan run. */
+            dimensionScores?: components["schemas"]["ReadinessScoreHistoryDimensionScoreDto"][];
         };
         ReadinessRepoScoreHistoryDto: {
             /** Format: uuid */
@@ -3031,9 +3108,11 @@ export type OrgChartImportResultDto = components['schemas']['OrgChartImportResul
 export type OrgChartSaveResultDto = components['schemas']['OrgChartSaveResultDto'];
 export type TenantSourceEntryDto = components['schemas']['TenantSourceEntryDto'];
 export type CursorSourceDto = components['schemas']['CursorSourceDto'];
+export type CursorSourceConfigDto = components['schemas']['CursorSourceConfigDto'];
 export type ClaudeSourceDto = components['schemas']['ClaudeSourceDto'];
 export type WorkspaceConfigDto = components['schemas']['WorkspaceConfigDto'];
 export type TestConnectionResponseDto = components['schemas']['TestConnectionResponseDto'];
+export type CursorKeyUsageDto = components['schemas']['CursorKeyUsageDto'];
 export type AiToolSeatDto = components['schemas']['AiToolSeatDto'];
 export type AiToolDailyUsageRowDto = components['schemas']['AiToolDailyUsageRowDto'];
 export type AiToolSpendRowDto = components['schemas']['AiToolSpendRowDto'];
@@ -3118,6 +3197,7 @@ export type ReadinessIssueDto = components['schemas']['ReadinessIssueDto'];
 export type DimensionScoreDto = components['schemas']['DimensionScoreDto'];
 export type ReadinessRepoRunHistoryItemDto = components['schemas']['ReadinessRepoRunHistoryItemDto'];
 export type ReadinessRepoRunListDto = components['schemas']['ReadinessRepoRunListDto'];
+export type ReadinessScoreHistoryDimensionScoreDto = components['schemas']['ReadinessScoreHistoryDimensionScoreDto'];
 export type ReadinessScoreHistoryPointDto = components['schemas']['ReadinessScoreHistoryPointDto'];
 export type ReadinessRepoScoreHistoryDto = components['schemas']['ReadinessRepoScoreHistoryDto'];
 export type WorkspaceReadinessScoreHistoryDto = components['schemas']['WorkspaceReadinessScoreHistoryDto'];
@@ -6362,6 +6442,72 @@ export interface operations {
             };
         };
     };
+    putCursorPlatformKeyConsent: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspaceId: components["parameters"]["WorkspaceId"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    /** @description true to opt in to ThinkAI platform Cursor key (additional cost applies); false to opt out. */
+                    enabled: boolean;
+                };
+            };
+        };
+        responses: {
+            /** @description Consent updated */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        ok: boolean;
+                    };
+                };
+            };
+            /** @description Invalid request body */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+        };
+    };
+    getCursorKeyUsage: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspaceId: components["parameters"]["WorkspaceId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Cursor key usage stats */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["CursorKeyUsageDto"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+        };
+    };
     getSquad: {
         parameters: {
             query?: never;