@thinkai/tai-api-contract 2.184.0 → 2.186.0

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.184.0
+  version: 2.186.0
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -1069,6 +1069,269 @@ paths:
                 error: Forbidden
                 code: forbidden
 
+  /admin/automation-cost/summary:
+    get:
+      tags: [PlatformAdmin]
+      summary: Estimated Agent automation spend by workspace and operation
+      operationId: adminGetAutomationCostSummary
+      description: >
+        Rolls up `tai_readiness_token_usage` for the given UTC range (defaults to the current
+        UTC calendar month when `from`/`to` are omitted). Each row is one
+        `(workspaceId, operation)` with token totals, invocation count, and
+        `estimatedSpendCents` from `workers.automationCost.pricing` (Cursor Auto pool list-rate
+        defaults when keys are missing). Portfolio `totals` are sums of the returned rows.
+
+        **Authorization:** Bearer JWT required. Caller email must appear in `PLATFORM_ADMIN_EMAILS`.
+        Separate from customer Insights AI Usage & Spend / `ai_cost_budget`.
+      parameters:
+        - name: workspaceId
+          in: query
+          required: false
+          schema:
+            type: string
+            format: uuid
+          description: Filter by workspace UUID.
+        - name: from
+          in: query
+          required: false
+          schema:
+            type: string
+            format: date-time
+          description: Inclusive start (ISO-8601). Defaults to start of current UTC month.
+        - name: to
+          in: query
+          required: false
+          schema:
+            type: string
+            format: date-time
+          description: Inclusive end (ISO-8601). Defaults to end of current UTC month.
+      responses:
+        "200":
+          description: Summary rows and portfolio totals (empty rows / zero totals when no usage).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AutomationCostSummaryDto"
+        "401":
+          description: Missing or invalid JWT.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "403":
+          description: Caller is not a platform admin.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Forbidden
+                code: forbidden
+
+  /admin/workspaces/{workspaceId}/automation-cost/budget:
+    get:
+      tags: [PlatformAdmin]
+      summary: Get automation-cost budget and month status for a workspace
+      operationId: adminGetAutomationCostBudget
+      description: >
+        Returns budget rows for `readiness_analysis` and/or `readiness_fix` with
+        `monthSpendCents` (estimated from token rows in the current UTC month) and
+        `status` (`ok` | `warn` | `hard_stopped` | `paused`). When no budget is configured,
+        `monthlyBudgetCents` is null and status is `ok` (unlimited) unless paused.
+
+        **Authorization:** Bearer JWT + `PLATFORM_ADMIN_EMAILS`.
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: operation
+          in: query
+          required: false
+          schema:
+            type: string
+            enum: [readiness_analysis, readiness_fix]
+          description: Limit to one operation; omit for both.
+      responses:
+        "200":
+          description: Budget views for the requested operations.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AutomationCostBudgetListDto"
+        "401":
+          description: Missing or invalid JWT.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "403":
+          description: Caller is not a platform admin.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Forbidden
+                code: forbidden
+        "404":
+          description: Workspace not found.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Workspace not found
+                code: workspace_not_found
+    put:
+      tags: [PlatformAdmin]
+      summary: Upsert automation-cost budget for one operation
+      operationId: adminPutAutomationCostBudget
+      description: >
+        Upserts `{ operation, monthlyBudgetCents, warnThresholdPct, hardEnabled }` into
+        workspace `automation_cost_budget` (not `ai_cost_budget`). Default `warnThresholdPct`
+        is 80. `monthlyBudgetCents: 0` with `hardEnabled: true` is an immediate hard stop.
+        Returns the refreshed budget view for that operation.
+
+        **Authorization:** Bearer JWT + `PLATFORM_ADMIN_EMAILS`.
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AutomationCostBudgetUpsertDto"
+      responses:
+        "200":
+          description: Updated budget view(s).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AutomationCostBudgetListDto"
+        "400":
+          description: Invalid body.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          description: Missing or invalid JWT.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "403":
+          description: Caller is not a platform admin.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Forbidden
+                code: forbidden
+        "404":
+          description: Workspace not found.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Workspace not found
+                code: workspace_not_found
+
+  /admin/workspaces/{workspaceId}/automation-cost/pause:
+    post:
+      tags: [PlatformAdmin]
+      summary: Pause Agent automation for selected operations
+      operationId: adminPostAutomationCostPause
+      description: >
+        Sets a per-workspace pause kill-switch for the listed operations. Workers honor pause
+        the same as a hard budget stop (enforcement is a follow-up slice). Empty `operations`
+        → `400`.
+
+        **Authorization:** Bearer JWT + `PLATFORM_ADMIN_EMAILS`.
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AutomationCostPauseBodyDto"
+      responses:
+        "200":
+          description: Pause state stored.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AutomationCostPauseResponseDto"
+        "400":
+          description: Empty or invalid operations list.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          description: Missing or invalid JWT.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "403":
+          description: Caller is not a platform admin.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Forbidden
+                code: forbidden
+        "404":
+          description: Workspace not found.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Workspace not found
+                code: workspace_not_found
+    delete:
+      tags: [PlatformAdmin]
+      summary: Clear automation-cost pause for a workspace
+      operationId: adminDeleteAutomationCostPause
+      description: >
+        Clears `automation_cost_pause` for the workspace so workers may resume when under hard
+        cap.
+
+        **Authorization:** Bearer JWT + `PLATFORM_ADMIN_EMAILS`.
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "204":
+          description: Pause cleared.
+        "401":
+          description: Missing or invalid JWT.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "403":
+          description: Caller is not a platform admin.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Forbidden
+                code: forbidden
+        "404":
+          description: Workspace not found.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Workspace not found
+                code: workspace_not_found
+
   /privacy-requests:
     post:
       tags: [PrivacyRequests]
@@ -6371,6 +6634,76 @@ paths:
               schema:
                 $ref: "#/components/schemas/GrafanaTriggerSyncResultDto"
 
+  /workspaces/{workspaceId}/integrations/datadog:
+    get:
+      tags: [Integrations]
+      summary: Datadog monitoring integration status
+      operationId: getWorkspaceDatadogIntegrationStatus
+      description: >
+        Returns whether Datadog is connected for the workspace (site + dual keys) and the last
+        monitoring ingest sync outcome (incidents/deployments pulled into Quality and DORA metrics).
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Datadog integration status
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DatadogIntegrationStatusDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist or malformed workspaceId
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/integrations/datadog/sync:
+    post:
+      tags: [Integrations]
+      summary: Trigger Datadog monitoring ingest now
+      operationId: postWorkspaceDatadogIntegrationSync
+      description: >
+        Manually polls Datadog for incidents and deployment-tagged events, persists canonical
+        monitoring events, and refreshes org-level Quality/DORA dashboard buckets. Requires editor role.
+      security:
+        - bearerAuth: []
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Sync completed
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DatadogTriggerSyncResultDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist or malformed workspaceId
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "422":
+          description: Datadog is not connected on this workspace
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DatadogTriggerSyncResultDto"
+        "503":
+          description: Sync failed (Datadog API or persistence error)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DatadogTriggerSyncResultDto"
+
   /integrations/github/webhook:
     post:
       tags: [Integrations]
@@ -19374,6 +19707,80 @@ components:
         error:
           type: string
 
+    DatadogIntegrationStatusDto:
+      type: object
+      additionalProperties: false
+      required: [connected, status]
+      properties:
+        connected:
+          type: boolean
+          description: "True when a type:datadog workspace source is configured."
+        site:
+          type: string
+          enum:
+            - datadoghq.com
+            - us3.datadoghq.com
+            - us5.datadoghq.com
+            - datadoghq.eu
+            - ap1.datadoghq.com
+          description: Configured Datadog site when connected.
+        orgName:
+          type: string
+          description: Org display name when known from the last successful verify.
+        lastSyncAt:
+          type: string
+          format: date-time
+          nullable: true
+          description: Timestamp of the last monitoring ingest attempt (success or failure).
+        status:
+          type: string
+          enum: [ok, error, never]
+          description: Outcome of the most recent sync (`never` when not yet synced).
+        lastError:
+          type: string
+          nullable: true
+        issueCount:
+          type: integer
+          nullable: true
+          description: Incidents fetched on the last successful sync (30d lookback).
+        deploymentCount:
+          type: integer
+          nullable: true
+          description: Deployment-tagged events fetched on the last successful sync (30d lookback).
+        eventCount:
+          type: integer
+          nullable: true
+          description: Canonical monitoring events upserted on the last successful sync.
+
+    DatadogTriggerSyncResultDto:
+      type: object
+      additionalProperties: false
+      required: [status]
+      properties:
+        status:
+          type: string
+          enum: [ok, skipped, error]
+        code:
+          type: string
+          description: Stable machine-readable code (e.g. `datadog_not_connected`).
+        reason:
+          type: string
+          description: Human-readable skip reason when status is skipped.
+        issueCount:
+          type: integer
+        deploymentCount:
+          type: integer
+        eventCount:
+          type: integer
+        bucketsWritten:
+          type: integer
+          description: Weekly dashboard metric buckets updated from monitoring events.
+        durationMs:
+          type: integer
+        error:
+          type: string
+          description: Error message when status is error.
+
     GithubActionsEnableResponseDto:
       type: object
       additionalProperties: false
@@ -23329,6 +23736,10 @@ components:
         - integrations.grafana.removed
         - integrations.grafana.sync_completed
         - integrations.grafana.sync_failed
+        - integrations.datadog.added
+        - integrations.datadog.removed
+        - integrations.datadog.sync_completed
+        - integrations.datadog.sync_failed
         - integrations.zelt.added
         - integrations.zelt.removed
         - report.exported
@@ -23739,7 +24150,7 @@ components:
       properties:
         version:
           type: string
-          enum: ["2026-10-24.1"]
+          enum: ["2026-10-25.1"]
         periodDays:
           type: integer
           enum: [90]
@@ -23825,12 +24236,12 @@ components:
                 enum: [jira]
             incident:
               type: array
-              minItems: 6
-              maxItems: 6
+              minItems: 7
+              maxItems: 7
               uniqueItems: true
               items:
                 type: string
-                enum: [pagerduty, opsgenie, goalert, newrelic, prometheus, grafana]
+                enum: [pagerduty, opsgenie, goalert, newrelic, prometheus, grafana, datadog]
         selfManagedGit:
           type: object
           additionalProperties: false
@@ -25252,6 +25663,186 @@ components:
               items:
                 $ref: "#/components/schemas/ActivityLogEntryDto"
 
+    AutomationCostOperationDto:
+      type: string
+      enum: [readiness_analysis, readiness_fix]
+      description: Platform Agent job type in the readiness token ledger.
+
+    AutomationCostSummaryRowDto:
+      type: object
+      required:
+        - workspaceId
+        - operation
+        - inputTokens
+        - outputTokens
+        - cacheReadTokens
+        - cacheWriteTokens
+        - estimatedSpendCents
+        - invocationCount
+      properties:
+        workspaceId:
+          type: string
+          format: uuid
+        operation:
+          $ref: "#/components/schemas/AutomationCostOperationDto"
+        inputTokens:
+          type: integer
+          format: int64
+        outputTokens:
+          type: integer
+          format: int64
+        cacheReadTokens:
+          type: integer
+          format: int64
+        cacheWriteTokens:
+          type: integer
+          format: int64
+        estimatedSpendCents:
+          type: integer
+          description: Ops estimate from token totals × runtime-config pricing (integer cents).
+        invocationCount:
+          type: integer
+
+    AutomationCostSummaryTotalsDto:
+      type: object
+      required:
+        - inputTokens
+        - outputTokens
+        - cacheReadTokens
+        - cacheWriteTokens
+        - estimatedSpendCents
+        - invocationCount
+      properties:
+        inputTokens:
+          type: integer
+          format: int64
+        outputTokens:
+          type: integer
+          format: int64
+        cacheReadTokens:
+          type: integer
+          format: int64
+        cacheWriteTokens:
+          type: integer
+          format: int64
+        estimatedSpendCents:
+          type: integer
+        invocationCount:
+          type: integer
+
+    AutomationCostSummaryDto:
+      type: object
+      required: [rows, totals]
+      properties:
+        rows:
+          type: array
+          items:
+            $ref: "#/components/schemas/AutomationCostSummaryRowDto"
+        totals:
+          $ref: "#/components/schemas/AutomationCostSummaryTotalsDto"
+
+    AutomationCostBudgetStatusDto:
+      type: string
+      enum: [ok, warn, hard_stopped, paused]
+
+    AutomationCostBudgetViewDto:
+      type: object
+      required:
+        - operation
+        - monthlyBudgetCents
+        - warnThresholdPct
+        - hardEnabled
+        - monthSpendCents
+        - status
+        - paused
+      properties:
+        operation:
+          $ref: "#/components/schemas/AutomationCostOperationDto"
+        monthlyBudgetCents:
+          type: integer
+          nullable: true
+          description: Null when no budget is configured (unlimited).
+        warnThresholdPct:
+          type: integer
+          minimum: 0
+          maximum: 100
+        hardEnabled:
+          type: boolean
+        monthSpendCents:
+          type: integer
+          description: Estimated spend for this operation in the current UTC calendar month.
+        status:
+          $ref: "#/components/schemas/AutomationCostBudgetStatusDto"
+        paused:
+          type: boolean
+        pauseReason:
+          type: string
+          nullable: true
+
+    AutomationCostBudgetListDto:
+      type: object
+      required: [budgets]
+      properties:
+        budgets:
+          type: array
+          items:
+            $ref: "#/components/schemas/AutomationCostBudgetViewDto"
+
+    AutomationCostBudgetUpsertDto:
+      type: object
+      required: [operation, monthlyBudgetCents]
+      properties:
+        operation:
+          $ref: "#/components/schemas/AutomationCostOperationDto"
+        monthlyBudgetCents:
+          type: integer
+          minimum: 0
+        warnThresholdPct:
+          type: integer
+          minimum: 0
+          maximum: 100
+          default: 80
+        hardEnabled:
+          type: boolean
+          default: false
+
+    AutomationCostPauseBodyDto:
+      type: object
+      required: [operations, reason]
+      properties:
+        operations:
+          type: array
+          minItems: 1
+          items:
+            $ref: "#/components/schemas/AutomationCostOperationDto"
+        reason:
+          type: string
+
+    AutomationCostPauseStateDto:
+      type: object
+      required: [operations, reason, pausedAt]
+      properties:
+        operations:
+          type: array
+          items:
+            $ref: "#/components/schemas/AutomationCostOperationDto"
+        reason:
+          type: string
+        pausedAt:
+          type: string
+          format: date-time
+        pausedBy:
+          type: string
+          nullable: true
+          description: Platform admin email that set the pause, when known.
+
+    AutomationCostPauseResponseDto:
+      type: object
+      required: [pause]
+      properties:
+        pause:
+          $ref: "#/components/schemas/AutomationCostPauseStateDto"
+
     ReadinessTokenUsageRowDto:
       type: object
       required:

package/package.json

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