@thinkai/tai-api-contract 2.2.9 → 2.3.1

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.2.9
+  version: 2.3.0
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -311,7 +311,9 @@ paths:
         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.
+        jira / sonarqube / bitbucket callers are not regressed.
+        **`type: github` is rejected** with HTTP 400 and `code: github_sources_deprecated`; use the
+        GitHub App integration (`POST /workspaces/{workspaceId}/integrations/github/install-url` and callback) instead.
 
         Every secret-keyed top-level string field
         (`token`, `password`, `api_key`, `secret`, `private_key`,
@@ -324,8 +326,8 @@ paths:
         Requires editor or admin workspace role.
 
         **Typical outcomes:** Valid typed sources → `200` with `{ ok: true, workspaceId }`. Missing required
-        fields for a given `type` (e.g. GitHub without `repo` or `token`) → `400` with `error` text.
-        Unknown `type` strings (non-cursor) currently pass through to storage (lenient compatibility); only `cursor`
+        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).
       operationId: putTenantSources
       parameters:
@@ -345,14 +347,17 @@ paths:
                       - $ref: "#/components/schemas/CursorSourceDto"
                       - $ref: "#/components/schemas/TenantSourceEntryDto"
             examples:
-              githubValid:
-                summary: GitHub source with required fields
+              cursorAndJira:
+                summary: Cursor plus Jira (GitHub uses App integration, not sources)
                 value:
                   sources:
-                    - type: github
-                      owner: org
-                      repo: repo
-                      token: secret
+                    - type: cursor
+                      token: cursor_api_key_example
+                      baseUrl: https://api.cursor.com
+                    - type: jira
+                      baseUrl: https://jira.example.com
+                      email: u@example.com
+                      apiToken: token
               jiraValid:
                 summary: Jira Cloud source
                 value:
@@ -389,8 +394,16 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
-              example:
-                error: repo is required
+              examples:
+                generic:
+                  summary: Generic validation error
+                  value:
+                    error: repo is required
+                githubDeprecated:
+                  summary: Legacy GitHub PAT in sources (use GitHub App)
+                  value:
+                    error: 'sources[0]: type "github" is no longer supported in workspace sources; use the GitHub App integration (POST .../integrations/github/install-url).'
+                    code: github_sources_deprecated
         "401":
           $ref: "#/components/responses/Unauthorized"
         "403":
@@ -752,6 +765,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]
@@ -1662,6 +1880,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.9",
+  "version": "2.3.1",
   "private": false,
   "type": "module",
   "main": "dist/index.js",