@thinkai/tai-api-contract 2.50.0-pr.877.6ff333f6 → 2.51.0-pr.877.bf4a3821

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.50.0
+  version: 2.51.0
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -1933,13 +1933,9 @@ paths:
       operationId: getAiUsageSpendAggregatedTeams
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-        - name: rangeId
-          in: query
-          description: Measure time range (maps to weekly bucket count).
-          schema:
-            type: string
-            enum: [4w, 8w, q]
-            default: 4w
+        - $ref: "#/components/parameters/InsightsProductivityRangeId"
+        - $ref: "#/components/parameters/InsightsProductivityFrom"
+        - $ref: "#/components/parameters/InsightsProductivityTo"
         - $ref: "#/components/parameters/InsightsDepartmentFilter"
         - name: team
           in: query
@@ -1988,13 +1984,9 @@ paths:
       operationId: getAiUsageSpendAggregatedContributors
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-        - name: rangeId
-          in: query
-          description: Measure time range (maps to weekly bucket count).
-          schema:
-            type: string
-            enum: [4w, 8w, q]
-            default: 4w
+        - $ref: "#/components/parameters/InsightsProductivityRangeId"
+        - $ref: "#/components/parameters/InsightsProductivityFrom"
+        - $ref: "#/components/parameters/InsightsProductivityTo"
         - $ref: "#/components/parameters/InsightsDepartmentFilter"
         - name: team
           in: query
@@ -2042,13 +2034,9 @@ paths:
       operationId: getAiUsageSpendContributorToolHeatmap
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-        - name: rangeId
-          in: query
-          description: Measure time range (maps to weekly bucket count).
-          schema:
-            type: string
-            enum: [4w, 8w, q]
-            default: 4w
+        - $ref: "#/components/parameters/InsightsProductivityRangeId"
+        - $ref: "#/components/parameters/InsightsProductivityFrom"
+        - $ref: "#/components/parameters/InsightsProductivityTo"
         - $ref: "#/components/parameters/InsightsDepartmentFilter"
         - name: team
           in: query
@@ -2096,13 +2084,9 @@ paths:
       operationId: getAiUsageSpendKeyInsights
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-        - name: rangeId
-          in: query
-          description: Measure time range (maps to weekly bucket count).
-          schema:
-            type: string
-            enum: [4w, 8w, q]
-            default: 4w
+        - $ref: "#/components/parameters/InsightsProductivityRangeId"
+        - $ref: "#/components/parameters/InsightsProductivityFrom"
+        - $ref: "#/components/parameters/InsightsProductivityTo"
         - $ref: "#/components/parameters/InsightsDepartmentFilter"
         - name: team
           in: query
@@ -2153,13 +2137,9 @@ paths:
       operationId: getAiUsageSpendAiAssistedCodePercentage
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-        - name: rangeId
-          in: query
-          description: Measure time range (maps to weekly bucket count).
-          schema:
-            type: string
-            enum: [4w, 8w, q]
-            default: 4w
+        - $ref: "#/components/parameters/InsightsProductivityRangeId"
+        - $ref: "#/components/parameters/InsightsProductivityFrom"
+        - $ref: "#/components/parameters/InsightsProductivityTo"
         - $ref: "#/components/parameters/InsightsDepartmentFilter"
         - name: team
           in: query
@@ -2209,13 +2189,9 @@ paths:
       operationId: getAiUsageSpendProviderEngagementInsights
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-        - name: rangeId
-          in: query
-          description: Measure time range (maps to weekly bucket count).
-          schema:
-            type: string
-            enum: [4w, 8w, q]
-            default: 4w
+        - $ref: "#/components/parameters/InsightsProductivityRangeId"
+        - $ref: "#/components/parameters/InsightsProductivityFrom"
+        - $ref: "#/components/parameters/InsightsProductivityTo"
         - $ref: "#/components/parameters/InsightsDepartmentFilter"
         - name: team
           in: query
@@ -2229,6 +2205,26 @@ paths:
           schema:
             type: string
             format: date-time
+        - name: memberExternalId
+          in: query
+          description: >
+            When set, aggregate engagement metrics for a single AI-tool member
+            (user detail pages). Mutually exclusive with `scopeTeamId`.
+          schema:
+            type: string
+        - name: scopeTeamId
+          in: query
+          description: >
+            Org-chart team id — aggregate engagement for members mapped to that team
+            (team detail pages). Mutually exclusive with `memberExternalId`.
+          schema:
+            type: string
+        - name: provider
+          in: query
+          description: Optional provider id filter (`cursor`, `claude`) for detail pages.
+          schema:
+            type: string
+            enum: [cursor, claude]
       responses:
         "200":
           description: Provider engagement insight cards
@@ -2266,13 +2262,9 @@ paths:
       operationId: getAiUsageSpendAiToolUsageSpend
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-        - name: rangeId
-          in: query
-          description: Measure time range (maps to weekly bucket count).
-          schema:
-            type: string
-            enum: [4w, 8w, q]
-            default: 4w
+        - $ref: "#/components/parameters/InsightsProductivityRangeId"
+        - $ref: "#/components/parameters/InsightsProductivityFrom"
+        - $ref: "#/components/parameters/InsightsProductivityTo"
         - $ref: "#/components/parameters/InsightsDepartmentFilter"
         - name: team
           in: query
@@ -2321,13 +2313,9 @@ paths:
       operationId: getAiUsageSpendTeamToolHeatmap
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-        - name: rangeId
-          in: query
-          description: Measure time range (maps to weekly bucket count).
-          schema:
-            type: string
-            enum: [4w, 8w, q]
-            default: 4w
+        - $ref: "#/components/parameters/InsightsProductivityRangeId"
+        - $ref: "#/components/parameters/InsightsProductivityFrom"
+        - $ref: "#/components/parameters/InsightsProductivityTo"
         - $ref: "#/components/parameters/InsightsDepartmentFilter"
         - name: team
           in: query
@@ -2376,13 +2364,9 @@ paths:
       operationId: getAiUsageSpendRoiProductivitySignal
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-        - name: rangeId
-          in: query
-          description: Measure time range (maps to weekly bucket count).
-          schema:
-            type: string
-            enum: [4w, 8w, q]
-            default: 4w
+        - $ref: "#/components/parameters/InsightsProductivityRangeId"
+        - $ref: "#/components/parameters/InsightsProductivityFrom"
+        - $ref: "#/components/parameters/InsightsProductivityTo"
         - $ref: "#/components/parameters/InsightsDepartmentFilter"
         - name: team
           in: query
@@ -2432,13 +2416,9 @@ paths:
       operationId: getAiUsageSpendUsageTrends
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-        - name: rangeId
-          in: query
-          description: Measure time range (maps to weekly bucket count).
-          schema:
-            type: string
-            enum: [4w, 8w, q]
-            default: 4w
+        - $ref: "#/components/parameters/InsightsProductivityRangeId"
+        - $ref: "#/components/parameters/InsightsProductivityFrom"
+        - $ref: "#/components/parameters/InsightsProductivityTo"
         - $ref: "#/components/parameters/InsightsDepartmentFilter"
         - name: team
           in: query
@@ -7824,6 +7804,41 @@ components:
           items:
             $ref: "#/components/schemas/ProductivityInsightsNeedsAttentionItemDto"
 
+    AiUsageSpendGranularity:
+      type: string
+      enum: [day, week]
+      description: >
+        Echo of the resolved time bucket for this response. `day` when the request used an
+        `Nd`/`cr:`/`from`+`to` window; `week` for legacy weekly rangeIds.
+
+    AiUsageSpendRangeId:
+      type: string
+      description: >
+        Daily windows: `7d`, `30d`, `90d`, `180d`, or custom `cr:YYYY-MM-DD:YYYY-MM-DD`.
+        Weekly legacy: `4w`, `8w`, `q` (12 weeks), `12w`, `16w`.
+
+    AiUsageSpendDailyBucketDto:
+      type: object
+      additionalProperties: false
+      required: [date, tokenCount, spendCents, activeUsers]
+      properties:
+        date:
+          type: string
+          format: date
+          description: UTC calendar day (`YYYY-MM-DD`).
+        dayLabel:
+          type: string
+          description: Short label for table headers (e.g. MM/DD).
+        tokenCount:
+          type: integer
+          minimum: 0
+        spendCents:
+          type: integer
+          minimum: 0
+        activeUsers:
+          type: integer
+          minimum: 0
+
     AiUsageSpendAggregatedTeamWeekDto:
       type: object
       additionalProperties: false
@@ -7854,7 +7869,7 @@ components:
     AiUsageSpendAggregatedTeamRowDto:
       type: object
       additionalProperties: false
-      required: [teamId, teamName, headcount, weeks]
+      required: [teamId, teamName, headcount]
       properties:
         teamId:
           type: string
@@ -7865,6 +7880,11 @@ components:
           minimum: 0
         managerLabel:
           type: string
+        days:
+          type: array
+          description: Present in day-mode responses — daily token, spend, and active-user counts.
+          items:
+            $ref: "#/components/schemas/AiUsageSpendDailyBucketDto"
         weeks:
           type: array
           items:
@@ -7904,8 +7924,17 @@ components:
           type: string
           format: uuid
         range:
+          $ref: "#/components/schemas/AiUsageSpendRangeId"
+        granularity:
+          $ref: "#/components/schemas/AiUsageSpendGranularity"
+        from:
+          type: string
+          format: date
+          description: Inclusive start day when `granularity` is `day`.
+        to:
           type: string
-          enum: [4w, 8w, q]
+          format: date
+          description: Inclusive end day when `granularity` is `day`.
         scope:
           $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamsScopeDto"
         generatedAt:
@@ -7921,7 +7950,7 @@ components:
     AiUsageSpendAggregatedContributorRowDto:
       type: object
       additionalProperties: false
-      required: [contributorId, contributorName, weeks]
+      required: [contributorId, contributorName]
       properties:
         contributorId:
           type: string
@@ -7934,6 +7963,11 @@ components:
           type: string
         department:
           type: string
+        days:
+          type: array
+          description: Present in day-mode responses — daily token, spend, and active-user counts.
+          items:
+            $ref: "#/components/schemas/AiUsageSpendDailyBucketDto"
         weeks:
           type: array
           items:
@@ -7948,8 +7982,17 @@ components:
           type: string
           format: uuid
         range:
+          $ref: "#/components/schemas/AiUsageSpendRangeId"
+        granularity:
+          $ref: "#/components/schemas/AiUsageSpendGranularity"
+        from:
+          type: string
+          format: date
+          description: Inclusive start day when `granularity` is `day`.
+        to:
           type: string
-          enum: [4w, 8w, q]
+          format: date
+          description: Inclusive end day when `granularity` is `day`.
         scope:
           $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamsScopeDto"
         generatedAt:
@@ -7976,8 +8019,17 @@ components:
           type: string
           format: uuid
         range:
+          $ref: "#/components/schemas/AiUsageSpendRangeId"
+        granularity:
+          $ref: "#/components/schemas/AiUsageSpendGranularity"
+        from:
           type: string
-          enum: [4w, 8w, q]
+          format: date
+          description: Inclusive start day when `granularity` is `day`.
+        to:
+          type: string
+          format: date
+          description: Inclusive end day when `granularity` is `day`.
         scope:
           $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamsScopeDto"
         generatedAt:
@@ -8012,8 +8064,17 @@ components:
           type: string
           format: uuid
         range:
+          $ref: "#/components/schemas/AiUsageSpendRangeId"
+        granularity:
+          $ref: "#/components/schemas/AiUsageSpendGranularity"
+        from:
           type: string
-          enum: [4w, 8w, q]
+          format: date
+          description: Inclusive start day when `granularity` is `day`.
+        to:
+          type: string
+          format: date
+          description: Inclusive end day when `granularity` is `day`.
         scope:
           $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamsScopeDto"
         generatedAt:
@@ -8041,6 +8102,33 @@ components:
         to proxy tokens when usage rows omit counts; **adoption** — active AI-tool users vs org
         headcount; **unavailable** — no usable signal for the selected scope.
 
+    AiUsageSpendAiAssistedCodeDayDto:
+      type: object
+      additionalProperties: false
+      required:
+        [date, aiAssistedCodePercent, totalLoc, aiLoc, humanLoc, dataQuality]
+      properties:
+        date:
+          type: string
+          format: date
+        dayLabel:
+          type: string
+        aiAssistedCodePercent:
+          type: number
+          minimum: 0
+          maximum: 100
+        totalLoc:
+          type: integer
+          minimum: 0
+        aiLoc:
+          type: integer
+          minimum: 0
+        humanLoc:
+          type: integer
+          minimum: 0
+        dataQuality:
+          $ref: "#/components/schemas/AiAssistedCodeDataQuality"
+
     AiUsageSpendAiAssistedCodeWeekDto:
       type: object
       additionalProperties: false
@@ -8093,14 +8181,22 @@ components:
         - aiLoc
         - humanLoc
         - dataQuality
-        - weeks
       properties:
         workspaceId:
           type: string
           format: uuid
         range:
+          $ref: "#/components/schemas/AiUsageSpendRangeId"
+        granularity:
+          $ref: "#/components/schemas/AiUsageSpendGranularity"
+        from:
           type: string
-          enum: [4w, 8w, q]
+          format: date
+          description: Inclusive start day when `granularity` is `day`.
+        to:
+          type: string
+          format: date
+          description: Inclusive end day when `granularity` is `day`.
         scope:
           $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamsScopeDto"
         generatedAt:
@@ -8145,6 +8241,11 @@ components:
           type: integer
           minimum: 0
           description: Scoped AI-tool spend in cents for the selected period.
+        days:
+          type: array
+          description: Present in day-mode responses — daily AI-assisted code share series.
+          items:
+            $ref: "#/components/schemas/AiUsageSpendAiAssistedCodeDayDto"
         weeks:
           type: array
           items:
@@ -8198,8 +8299,17 @@ components:
           type: string
           format: uuid
         range:
+          $ref: "#/components/schemas/AiUsageSpendRangeId"
+        granularity:
+          $ref: "#/components/schemas/AiUsageSpendGranularity"
+        from:
           type: string
-          enum: [4w, 8w, q]
+          format: date
+          description: Inclusive start day when `granularity` is `day`.
+        to:
+          type: string
+          format: date
+          description: Inclusive end day when `granularity` is `day`.
         scope:
           $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamsScopeDto"
         generatedAt:
@@ -8263,8 +8373,17 @@ components:
           type: string
           format: uuid
         range:
+          $ref: "#/components/schemas/AiUsageSpendRangeId"
+        granularity:
+          $ref: "#/components/schemas/AiUsageSpendGranularity"
+        from:
           type: string
-          enum: [4w, 8w, q]
+          format: date
+          description: Inclusive start day when `granularity` is `day`.
+        to:
+          type: string
+          format: date
+          description: Inclusive end day when `granularity` is `day`.
         scope:
           $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamsScopeDto"
         generatedAt:
@@ -8296,8 +8415,17 @@ components:
           type: string
           format: uuid
         range:
+          $ref: "#/components/schemas/AiUsageSpendRangeId"
+        granularity:
+          $ref: "#/components/schemas/AiUsageSpendGranularity"
+        from:
+          type: string
+          format: date
+          description: Inclusive start day when `granularity` is `day`.
+        to:
           type: string
-          enum: [4w, 8w, q]
+          format: date
+          description: Inclusive end day when `granularity` is `day`.
         scope:
           $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamsScopeDto"
         generatedAt:
@@ -8308,6 +8436,23 @@ components:
           items:
             $ref: "#/components/schemas/AiUsageSpendAggregatedTeamRowDto"
 
+    AiUsageSpendRoiProductivitySignalDayDto:
+      type: object
+      additionalProperties: false
+      required: [date, mergedPrCount, tokenCount]
+      properties:
+        date:
+          type: string
+          format: date
+        dayLabel:
+          type: string
+        mergedPrCount:
+          type: integer
+          minimum: 0
+        tokenCount:
+          type: integer
+          minimum: 0
+
     AiUsageSpendRoiProductivitySignalWeekDto:
       type: object
       additionalProperties: false
@@ -8345,14 +8490,22 @@ components:
         - aiAssistedPrRatio
         - prThroughputDeltaPercent
         - usageDeltaPercent
-        - weeks
       properties:
         workspaceId:
           type: string
           format: uuid
         range:
+          $ref: "#/components/schemas/AiUsageSpendRangeId"
+        granularity:
+          $ref: "#/components/schemas/AiUsageSpendGranularity"
+        from:
+          type: string
+          format: date
+          description: Inclusive start day when `granularity` is `day`.
+        to:
           type: string
-          enum: [4w, 8w, q]
+          format: date
+          description: Inclusive end day when `granularity` is `day`.
         scope:
           $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamsScopeDto"
         generatedAt:
@@ -8381,11 +8534,35 @@ components:
         usageDeltaPercent:
           type: number
           description: Percent change in token usage (recent half vs prior half of range).
+        days:
+          type: array
+          description: Present in day-mode responses — daily merged PR and token counts.
+          items:
+            $ref: "#/components/schemas/AiUsageSpendRoiProductivitySignalDayDto"
         weeks:
           type: array
           items:
             $ref: "#/components/schemas/AiUsageSpendRoiProductivitySignalWeekDto"
 
+    AiUsageSpendUsageTrendsProviderDayDto:
+      type: object
+      additionalProperties: false
+      required: [providerId, providerName, spendCents, tokenCount, activeUsers]
+      properties:
+        providerId:
+          type: string
+        providerName:
+          type: string
+        spendCents:
+          type: integer
+          minimum: 0
+        tokenCount:
+          type: integer
+          minimum: 0
+        activeUsers:
+          type: integer
+          minimum: 0
+
     AiUsageSpendUsageTrendsProviderWeekDto:
       type: object
       additionalProperties: false
@@ -8405,6 +8582,21 @@ components:
           type: integer
           minimum: 0
 
+    AiUsageSpendUsageTrendsDayDto:
+      type: object
+      additionalProperties: false
+      required: [date, providers]
+      properties:
+        date:
+          type: string
+          format: date
+        dayLabel:
+          type: string
+        providers:
+          type: array
+          items:
+            $ref: "#/components/schemas/AiUsageSpendUsageTrendsProviderDayDto"
+
     AiUsageSpendUsageTrendsWeekDto:
       type: object
       additionalProperties: false
@@ -8426,19 +8618,33 @@ components:
     AiUsageSpendUsageTrendsDto:
       type: object
       additionalProperties: false
-      required: [workspaceId, range, scope, generatedAt, weeks]
+      required: [workspaceId, range, scope, generatedAt]
       properties:
         workspaceId:
           type: string
           format: uuid
         range:
+          $ref: "#/components/schemas/AiUsageSpendRangeId"
+        granularity:
+          $ref: "#/components/schemas/AiUsageSpendGranularity"
+        from:
           type: string
-          enum: [4w, 8w, q]
+          format: date
+          description: Inclusive start day when `granularity` is `day`.
+        to:
+          type: string
+          format: date
+          description: Inclusive end day when `granularity` is `day`.
         scope:
           $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamsScopeDto"
         generatedAt:
           type: string
           format: date-time
+        days:
+          type: array
+          description: Present in day-mode responses — per-provider spend and usage by day.
+          items:
+            $ref: "#/components/schemas/AiUsageSpendUsageTrendsDayDto"
         weeks:
           type: array
           items:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinkai/tai-api-contract",
-  "version": "2.50.0-pr.877.6ff333f6",
+  "version": "2.51.0-pr.877.bf4a3821",
   "private": false,
   "type": "module",
   "main": "dist/index.js",