@thinkai/tai-api-contract 2.8.6 → 2.9.1

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.8.4
+  version: 2.9.1
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -1868,6 +1868,54 @@ paths:
         "403":
           $ref: "#/components/responses/Forbidden"
 
+  /workspaces/{workspaceId}/integrations/ai-tool/{provider}/spend-daily:
+    get:
+      tags: [Integrations]
+      summary: List AI-tool daily spend (historic Cursor filtered-usage rollup)
+      operationId: getWorkspaceAiToolSpendDaily
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: provider
+          in: path
+          required: true
+          schema:
+            type: string
+            enum: [cursor, claude]
+        - name: from
+          in: query
+          required: false
+          schema:
+            type: string
+            format: date
+        - name: to
+          in: query
+          required: false
+          schema:
+            type: string
+            format: date
+        - name: externalId
+          in: query
+          required: false
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Daily spend rows
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [rows]
+                properties:
+                  rows:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/AiToolSpendDailyRowDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+
   /workspaces/{workspaceId}/integrations/ai-tool/{provider}/status:
     get:
       tags: [Integrations]
@@ -3142,6 +3190,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 +4241,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 +4258,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 +4278,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 +4339,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 +4354,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
@@ -4258,6 +4444,27 @@ components:
           type: object
           additionalProperties: true
 
+    AiToolSpendDailyRowDto:
+      type: object
+      required: [day, externalId, spendCents, eventCount]
+      properties:
+        day:
+          type: string
+          format: date
+        externalId:
+          type: string
+        email:
+          type: string
+          nullable: true
+        spendCents:
+          type: integer
+          format: int64
+        eventCount:
+          type: integer
+        payload:
+          type: object
+          additionalProperties: true
+
     AiToolRefreshStatusDto:
       type: object
       required: [lastAttemptAt, counts]
@@ -4282,6 +4489,9 @@ components:
         counts:
           type: object
           additionalProperties: true
+        refreshInProgress:
+          type: boolean
+          description: True while a workspace/provider refresh holds the Postgres advisory lock.
 
     AiToolRefreshResponseDto:
       type: object
@@ -5897,6 +6107,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

package/package.json

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

package/src/generated/openapi.ts

@@ -657,6 +657,23 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/workspaces/{workspaceId}/integrations/ai-tool/{provider}/spend-daily": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** List AI-tool daily spend (historic Cursor filtered-usage rollup) */
+        get: operations["getWorkspaceAiToolSpendDaily"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/workspaces/{workspaceId}/integrations/ai-tool/{provider}/status": {
         parameters: {
             query?: never;
@@ -1239,6 +1256,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 +1710,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 +1725,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 +1746,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;
@@ -1715,6 +1797,18 @@ export interface components {
                 [key: string]: unknown;
             };
         };
+        AiToolSpendDailyRowDto: {
+            /** Format: date */
+            day: string;
+            externalId: string;
+            email?: string | null;
+            /** Format: int64 */
+            spendCents: number;
+            eventCount: number;
+            payload?: {
+                [key: string]: unknown;
+            };
+        };
         AiToolRefreshStatusDto: {
             /** Format: date-time */
             lastAttemptAt: string;
@@ -1727,6 +1821,8 @@ export interface components {
             counts: {
                 [key: string]: unknown;
             };
+            /** @description True while a workspace/provider refresh holds the Postgres advisory lock. */
+            refreshInProgress?: boolean;
         };
         AiToolRefreshResponseDto: {
             ok: boolean;
@@ -2449,6 +2545,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;
@@ -3038,12 +3139,15 @@ 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'];
+export type AiToolSpendDailyRowDto = components['schemas']['AiToolSpendDailyRowDto'];
 export type AiToolRefreshStatusDto = components['schemas']['AiToolRefreshStatusDto'];
 export type AiToolRefreshResponseDto = components['schemas']['AiToolRefreshResponseDto'];
 export type DashboardProductivityMetricsDto = components['schemas']['DashboardProductivityMetricsDto'];
@@ -4919,6 +5023,37 @@ export interface operations {
             403: components["responses"]["Forbidden"];
         };
     };
+    getWorkspaceAiToolSpendDaily: {
+        parameters: {
+            query?: {
+                from?: string;
+                to?: string;
+                externalId?: string;
+            };
+            header?: never;
+            path: {
+                workspaceId: components["parameters"]["WorkspaceId"];
+                provider: "cursor" | "claude";
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Daily spend rows */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        rows: components["schemas"]["AiToolSpendDailyRowDto"][];
+                    };
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+        };
+    };
     getWorkspaceAiToolRefreshStatus: {
         parameters: {
             query?: never;
@@ -6370,6 +6505,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;