@thinkai/tai-api-contract 2.53.0 → 2.54.0

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.53.0
+  version: 2.54.0
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -2216,7 +2216,16 @@ paths:
           in: query
           description: >
             Org-chart team id — aggregate engagement for members mapped to that team
-            (team detail pages). Mutually exclusive with `memberExternalId`.
+            (team detail pages). Mutually exclusive with `memberExternalId` and
+            `scopeExternalIds`.
+          schema:
+            type: string
+        - name: scopeExternalIds
+          in: query
+          description: >
+            Comma-separated AI-tool member external IDs — aggregate engagement for
+            exactly those seats (team detail when scoped via slim reads). Mutually
+            exclusive with `memberExternalId` and `scopeTeamId`.
           schema:
             type: string
         - name: provider
@@ -2479,6 +2488,20 @@ paths:
             type: string
             enum: [4w, 8w, q]
             default: 4w
+        - name: from
+          in: query
+          schema:
+            type: string
+            format: date
+          description: >
+            Inclusive start day (YYYY-MM-DD). When set with `to`, overrides `rangeId` calendar
+            buckets for the aggregation window.
+        - name: to
+          in: query
+          schema:
+            type: string
+            format: date
+          description: Inclusive end day (YYYY-MM-DD). Requires `from`.
         - name: windowEnd
           in: query
           schema:
@@ -2552,6 +2575,18 @@ paths:
             type: string
             enum: [4w, 8w, q]
             default: 4w
+        - name: from
+          in: query
+          schema:
+            type: string
+            format: date
+          description: Inclusive start day (YYYY-MM-DD). When set with `to`, overrides `rangeId`.
+        - name: to
+          in: query
+          schema:
+            type: string
+            format: date
+          description: Inclusive end day (YYYY-MM-DD). Requires `from`.
         - name: windowEnd
           in: query
           schema:
@@ -2608,6 +2643,18 @@ paths:
             type: string
             enum: [4w, 8w, q]
             default: 4w
+        - name: from
+          in: query
+          schema:
+            type: string
+            format: date
+          description: Inclusive start day (YYYY-MM-DD). When set with `to`, overrides `rangeId`.
+        - name: to
+          in: query
+          schema:
+            type: string
+            format: date
+          description: Inclusive end day (YYYY-MM-DD). Requires `from`.
         - name: windowEnd
           in: query
           schema:
@@ -3230,6 +3277,176 @@ paths:
         "403":
           $ref: "#/components/responses/Forbidden"
 
+  /workspaces/{workspaceId}/integrations/ai-tool/{provider}/summary:
+    get:
+      tags: [Integrations]
+      summary: AI-tool provider summary for a date window
+      description: >
+        Pre-aggregated spend, token, and active-user totals plus weekly buckets for the
+        AI Usage & Spend overview. Replaces downloading the full `/snapshot` payload for
+        KPI cards and sparklines.
+      operationId: getWorkspaceAiToolProviderSummary
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: provider
+          in: path
+          required: true
+          schema:
+            type: string
+            enum: [cursor, claude]
+        - name: from
+          in: query
+          required: true
+          schema:
+            type: string
+            format: date
+        - name: to
+          in: query
+          required: true
+          schema:
+            type: string
+            format: date
+      responses:
+        "200":
+          description: Provider summary
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AiToolProviderSummaryDto"
+        "400":
+          description: Invalid query
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [error]
+                properties:
+                  error: { type: string, example: invalid_query }
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+
+  /workspaces/{workspaceId}/integrations/ai-tool/{provider}/daily-series:
+    get:
+      tags: [Integrations]
+      summary: AI-tool daily spend and usage series for charts
+      description: >
+        Daily chart points (spend and tokens) with optional product/model breakdown.
+        Scoped to the requested date window; intended for the overview trend chart.
+      operationId: getWorkspaceAiToolProviderDailySeries
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: provider
+          in: path
+          required: true
+          schema:
+            type: string
+            enum: [cursor, claude]
+        - name: from
+          in: query
+          required: true
+          schema:
+            type: string
+            format: date
+        - name: to
+          in: query
+          required: true
+          schema:
+            type: string
+            format: date
+        - name: externalId
+          in: query
+          required: false
+          schema:
+            type: array
+            items:
+              type: string
+          style: form
+          explode: true
+          description: >
+            Optional member external IDs. When set, the series includes only those members
+            (team drill-down, user detail). Repeat the parameter or pass comma-separated values.
+      responses:
+        "200":
+          description: Daily series
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AiToolDailySeriesDto"
+        "400":
+          description: Invalid query
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [error]
+                properties:
+                  error: { type: string, example: invalid_query }
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+
+  /workspaces/{workspaceId}/integrations/ai-tool/{provider}/model-breakdown:
+    get:
+      tags: [Integrations]
+      summary: AI-tool model spend rollup for a date window
+      description: >
+        Aggregated spend and token totals per LLM model for the Costs by LLM Model page
+        and team drill-downs. Optionally scoped to specific member external IDs.
+      operationId: getWorkspaceAiToolProviderModelBreakdown
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: provider
+          in: path
+          required: true
+          schema:
+            type: string
+            enum: [cursor, claude]
+        - name: from
+          in: query
+          required: true
+          schema:
+            type: string
+            format: date
+        - name: to
+          in: query
+          required: true
+          schema:
+            type: string
+            format: date
+        - name: externalId
+          in: query
+          required: false
+          schema:
+            type: array
+            items:
+              type: string
+          style: form
+          explode: true
+          description: Optional member external IDs to scope the rollup (org/team filter).
+      responses:
+        "200":
+          description: Model breakdown
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AiToolModelBreakdownDto"
+        "400":
+          description: Invalid query
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [error]
+                properties:
+                  error: { type: string, example: invalid_query }
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+
   /workspaces/{workspaceId}/integrations/ai-tool/{provider}/status:
     get:
       tags: [Integrations]
@@ -8695,6 +8912,239 @@ components:
           items:
             $ref: "#/components/schemas/AiUsageSpendUsageTrendsWeekDto"
 
+    AiToolProviderSummaryWeekBucketDto:
+      type: object
+      additionalProperties: false
+      required: [weekLabel, spendCents, tokenCount, activeUsers]
+      properties:
+        weekLabel:
+          type: string
+        spendCents:
+          type: integer
+          minimum: 0
+        tokenCount:
+          type: integer
+          minimum: 0
+        activeUsers:
+          type: integer
+          minimum: 0
+
+    AiToolProviderSummaryTopMoverDto:
+      type: object
+      additionalProperties: false
+      required: [externalId, label, deltaSpendCents, currentSpendCents]
+      properties:
+        externalId:
+          type: string
+        label:
+          type: string
+        deltaSpendCents:
+          type: integer
+        currentSpendCents:
+          type: integer
+          minimum: 0
+
+    AiToolProviderSummaryDto:
+      type: object
+      additionalProperties: false
+      required:
+        - provider
+        - from
+        - to
+        - seatCounts
+        - totals
+        - weekBuckets
+        - generatedAt
+      properties:
+        provider:
+          type: string
+        from:
+          type: string
+          format: date
+        to:
+          type: string
+          format: date
+        status:
+          $ref: "#/components/schemas/AiToolRefreshStatusDto"
+        seatCounts:
+          type: object
+          additionalProperties: false
+          required: [total, active, removed]
+          properties:
+            total:
+              type: integer
+              minimum: 0
+            active:
+              type: integer
+              minimum: 0
+            removed:
+              type: integer
+              minimum: 0
+        totals:
+          type: object
+          additionalProperties: false
+          required: [spendCents, tokenCount, activeUsers, totalEngineers]
+          properties:
+            spendCents:
+              type: integer
+              minimum: 0
+            tokenCount:
+              type: integer
+              minimum: 0
+            activeUsers:
+              type: integer
+              minimum: 0
+            totalEngineers:
+              type: integer
+              minimum: 0
+        weekBuckets:
+          type: array
+          items:
+            $ref: "#/components/schemas/AiToolProviderSummaryWeekBucketDto"
+        topMovers:
+          type: array
+          items:
+            $ref: "#/components/schemas/AiToolProviderSummaryTopMoverDto"
+        hasTokenMetrics:
+          type: boolean
+        generatedAt:
+          type: string
+          format: date-time
+
+    AiToolDailySeriesPointDto:
+      type: object
+      additionalProperties: false
+      required: [day, label, spendCents, tokenCount, products, models]
+      properties:
+        day:
+          type: string
+          format: date
+        label:
+          type: string
+        spendCents:
+          type: integer
+          minimum: 0
+        tokenCount:
+          type: integer
+          minimum: 0
+        products:
+          type: object
+          additionalProperties:
+            type: integer
+            minimum: 0
+          description: Spend cents by product label.
+        models:
+          type: object
+          additionalProperties:
+            type: integer
+            minimum: 0
+          description: Spend cents by model name.
+
+    AiToolDailySeriesDto:
+      type: object
+      additionalProperties: false
+      required:
+        - provider
+        - from
+        - to
+        - points
+        - productKeys
+        - modelKeys
+        - totals
+        - generatedAt
+      properties:
+        provider:
+          type: string
+        from:
+          type: string
+          format: date
+        to:
+          type: string
+          format: date
+        points:
+          type: array
+          items:
+            $ref: "#/components/schemas/AiToolDailySeriesPointDto"
+        productKeys:
+          type: array
+          items:
+            type: string
+        modelKeys:
+          type: array
+          items:
+            type: string
+        totals:
+          type: object
+          additionalProperties: false
+          required: [spendCents, tokenCount]
+          properties:
+            spendCents:
+              type: integer
+              minimum: 0
+            tokenCount:
+              type: integer
+              minimum: 0
+        hasProductBreakdown:
+          type: boolean
+        hasModelBreakdown:
+          type: boolean
+        hasSpend:
+          type: boolean
+        hasTokens:
+          type: boolean
+        generatedAt:
+          type: string
+          format: date-time
+
+    AiToolModelBreakdownItemDto:
+      type: object
+      additionalProperties: false
+      required: [modelName, spendCents, tokenCount, activeUsers]
+      properties:
+        modelName:
+          type: string
+        spendCents:
+          type: integer
+          minimum: 0
+        tokenCount:
+          type: integer
+          minimum: 0
+        activeUsers:
+          type: integer
+          minimum: 0
+
+    AiToolModelBreakdownDto:
+      type: object
+      additionalProperties: false
+      required: [provider, from, to, models, totals, generatedAt]
+      properties:
+        provider:
+          type: string
+        from:
+          type: string
+          format: date
+        to:
+          type: string
+          format: date
+        models:
+          type: array
+          items:
+            $ref: "#/components/schemas/AiToolModelBreakdownItemDto"
+        totals:
+          type: object
+          additionalProperties: false
+          required: [spendCents, tokenCount]
+          properties:
+            spendCents:
+              type: integer
+              minimum: 0
+            tokenCount:
+              type: integer
+              minimum: 0
+        generatedAt:
+          type: string
+          format: date-time
+
     AiToolMemberSummaryDto:
       type: object
       additionalProperties: false
@@ -8719,6 +9169,14 @@ components:
           minimum: 0
         mostUsedModel:
           type: string
+        productBreakdownCents:
+          type: object
+          additionalProperties:
+            type: integer
+            minimum: 0
+          description: >
+            Per-product spend in cents for the requested window (Claude Enterprise).
+            Omitted when no product-level daily rows exist for the member.
 
     AiToolMembersListDto:
       type: object

package/package.json

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