@thinkai/tai-api-contract 2.2.8 → 2.3.0

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.2.8
+  version: 2.3.0
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -307,7 +307,9 @@ paths:
       description: >
         Replace the workspace's `sources` array. Cursor entries are validated
         strictly (`token` 1-256 chars, no whitespace, no `env:` prefix;
-        optional `https:` `baseUrl`); other types pass through with only a
+        optional deprecated `baseUrl` is accepted for backwards compatibility and
+        ignored at runtime; verification and future refresh use the fixed Cursor Admin API host.
+        Other types pass through with only a
         non-empty `type` requirement so existing
         github / jira / sonarqube / bitbucket callers are not regressed.
 
@@ -405,8 +407,9 @@ 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 (calls
-        `GET ${baseUrl}/v0/me`); other types report
+        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
         `{ success: false, error: "unsupported_type" }`. Documented `error`
         codes for cursor: `invalid_token`, `rate_limited`, `network_error`.
 
@@ -749,6 +752,211 @@ paths:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
 
+  /workspaces/{workspaceId}/integrations/ai-tool/{provider}/refresh:
+    post:
+      tags: [Integrations]
+      summary: Refresh AI tool integration snapshots
+      operationId: refreshWorkspaceAiTool
+      description: >
+        Provider-agnostic refresh. Returns 409 when an advisory-lock refresh is already in progress.
+        On upstream auth/rate/network failures, returns `200` with `{ ok:false, error }` so the SPA can render inline error.
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: provider
+          in: path
+          required: true
+          schema:
+            type: string
+            enum: [cursor]
+      responses:
+        "200":
+          description: Refresh result
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AiToolRefreshResponseDto"
+              examples:
+                ok:
+                  value: { ok: true }
+                invalid_token:
+                  value: { ok: false, error: invalid_token }
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Provider source missing for this workspace
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AiToolRefreshResponseDto"
+              example:
+                ok: false
+                error: no_source
+        "409":
+          description: Refresh already in progress
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AiToolRefreshResponseDto"
+              example:
+                ok: false
+                error: already_in_progress
+
+  /workspaces/{workspaceId}/integrations/ai-tool/{provider}/seats:
+    get:
+      tags: [Integrations]
+      summary: List latest AI-tool seats
+      operationId: getWorkspaceAiToolSeats
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: provider
+          in: path
+          required: true
+          schema:
+            type: string
+            enum: [cursor]
+      responses:
+        "200":
+          description: Seats
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [seats]
+                properties:
+                  seats:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/AiToolSeatDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+
+  /workspaces/{workspaceId}/integrations/ai-tool/{provider}/daily-usage:
+    get:
+      tags: [Integrations]
+      summary: List AI-tool daily usage
+      operationId: getWorkspaceAiToolDailyUsage
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: provider
+          in: path
+          required: true
+          schema:
+            type: string
+            enum: [cursor]
+        - 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: Usage rows
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [rows]
+                properties:
+                  rows:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/AiToolDailyUsageRowDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+
+  /workspaces/{workspaceId}/integrations/ai-tool/{provider}/spend:
+    get:
+      tags: [Integrations]
+      summary: List AI-tool spend
+      operationId: getWorkspaceAiToolSpend
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: provider
+          in: path
+          required: true
+          schema:
+            type: string
+            enum: [cursor]
+        - name: cycleStartMs
+          in: query
+          required: false
+          schema:
+            type: integer
+            format: int64
+      responses:
+        "200":
+          description: Spend rows
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [rows]
+                properties:
+                  rows:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/AiToolSpendRowDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+
+  /workspaces/{workspaceId}/integrations/ai-tool/{provider}/status:
+    get:
+      tags: [Integrations]
+      summary: Get last refresh status
+      operationId: getWorkspaceAiToolRefreshStatus
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: provider
+          in: path
+          required: true
+          schema:
+            type: string
+            enum: [cursor]
+      responses:
+        "200":
+          description: Refresh status
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [status]
+                properties:
+                  status:
+                    $ref: "#/components/schemas/AiToolRefreshStatusDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: No refresh status yet (or provider source missing)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AiToolRefreshResponseDto"
+              example:
+                ok: false
+                error: no_source
+
   /integrations/github/callback:
     get:
       tags: [Integrations]
@@ -1613,6 +1821,7 @@ components:
         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`.
       required: [type, token]
       additionalProperties: false
       properties:
@@ -1626,8 +1835,10 @@ components:
           description: Cursor API key (literal). Whitespace and `env:` prefix are rejected.
         baseUrl:
           type: string
-          format: uri
-          description: Override Cursor API base URL. Must use `https:`.
+          deprecated: true
+          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.
           default: "https://api.cursor.com"
 
     WorkspaceConfigDto:
@@ -1656,6 +1867,101 @@ components:
         error:
           type: string
 
+    AiToolSeatDto:
+      type: object
+      required: [externalId, email, isRemoved]
+      properties:
+        externalId:
+          type: string
+        email:
+          type: string
+        displayName:
+          type: string
+          nullable: true
+        role:
+          type: string
+          nullable: true
+        isRemoved:
+          type: boolean
+        payload:
+          type: object
+          additionalProperties: true
+
+    AiToolDailyUsageRowDto:
+      type: object
+      required: [day, externalId, isActive]
+      properties:
+        day:
+          type: string
+          format: date
+        externalId:
+          type: string
+        email:
+          type: string
+          nullable: true
+        isActive:
+          type: boolean
+        mostUsedModel:
+          type: string
+          nullable: true
+        payload:
+          type: object
+          additionalProperties: true
+
+    AiToolSpendRowDto:
+      type: object
+      required: [billingCycleStartMs, externalId, spendCents]
+      properties:
+        billingCycleStartMs:
+          type: integer
+          format: int64
+        externalId:
+          type: string
+        email:
+          type: string
+          nullable: true
+        spendCents:
+          type: integer
+          format: int64
+        payload:
+          type: object
+          additionalProperties: true
+
+    AiToolRefreshStatusDto:
+      type: object
+      required: [lastAttemptAt, counts]
+      properties:
+        lastAttemptAt:
+          type: string
+          format: date-time
+        lastSuccessAt:
+          type: string
+          format: date-time
+          nullable: true
+        lastErrorKind:
+          type: string
+          nullable: true
+        lastErrorMessage:
+          type: string
+          nullable: true
+        durationMs:
+          type: integer
+          format: int64
+          nullable: true
+        counts:
+          type: object
+          additionalProperties: true
+
+    AiToolRefreshResponseDto:
+      type: object
+      required: [ok]
+      properties:
+        ok:
+          type: boolean
+        error:
+          type: string
+          nullable: true
+
     DashboardProductivityMetricsDto:
       type: object
       description: Nested metric groups; see TypeScript `DashboardProductivityMetricsDto` in @thinkai/tai-api-contract.

package/package.json

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