@thinkai/tai-api-contract 2.60.0 → 2.61.0-pr.901.b553abc8

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.60.0
+  version: 2.61.0
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -1469,6 +1469,10 @@ paths:
                   value:
                     success: false
                     error: "invalid_token"
+                zenhr_sync_in_progress:
+                  value:
+                    success: false
+                    error: zenhr_sync_in_progress
         "400":
           description: Invalid body or missing env for token refs
           content:
@@ -3004,6 +3008,9 @@ paths:
       operationId: postGithubInstallUrl
       description: >
         Creates a GitHub App installation URL scoped to the workspace and caller.
+        Default intent `connect` installs ThinkAI Platform Insights (read).
+        Intent `enable_fixes` installs ThinkAI Platform Automations (write) for the Insights
+        installation identified by `installationId`.
         Body is optional; when omitted, defaults to `/onboarding/integrations` return path.
         Optional `pickerSession` (from user OAuth org picker) recovers `returnPath` from the server-side picker snapshot when the multi-hop authorize→install flow should return to the page where OAuth started.
       security:
@@ -3039,6 +3046,91 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
+        "503":
+          description: Requested GitHub App is not configured
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/integrations/github/installations/{installationId}/automated-fixes/enable:
+    post:
+      tags: [Integrations]
+      summary: Enable automated fixes for a GitHub installation
+      operationId: postGithubAutomatedFixesEnable
+      description: >
+        Workspace-level enable for automated fixes on an Insights (read) installation.
+        If an Automations (write) installation is already linked, flips `automatedFixesEnabled`
+        without reinstalling. Otherwise returns `outcome: needs_install` so the client can
+        call install-url with intent=enable_fixes.
+      security:
+        - bearerAuth: []
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: installationId
+          in: path
+          required: true
+          schema:
+            type: string
+            minLength: 1
+            maxLength: 64
+      responses:
+        "200":
+          description: Enable result
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GithubAutomatedFixesEnableResponseDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace or installation not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "503":
+          description: Automations GitHub App not configured
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/integrations/github/installations/{installationId}/automated-fixes:
+    delete:
+      tags: [Integrations]
+      summary: Disable automated fixes for a GitHub installation
+      operationId: deleteGithubAutomatedFixes
+      description: >
+        Workspace-level disable. Clears `automatedFixesEnabled` but keeps the linked Automations
+        write installation id so re-enable does not require reinstall. Does not uninstall the
+        Automations app from GitHub.
+      security:
+        - bearerAuth: []
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: installationId
+          in: path
+          required: true
+          schema:
+            type: string
+            minLength: 1
+            maxLength: 64
+      responses:
+        "204":
+          description: Automated fixes disabled (or already disabled)
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace or installation not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
 
   /workspaces/{workspaceId}/integrations/github/user-authorize-url:
     post:
@@ -5605,6 +5697,31 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
+        "422":
+          description: GitHub installation lacks write permissions required for automated fix PRs
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GithubWritePermissionsRequiredErrorDto"
+              examples:
+                write_required:
+                  value:
+                    error: github_write_permissions_required
+                    missingPermissions:
+                      - name: contents
+                        required: write
+                        granted: read
+                      - name: pull_requests
+                        required: write
+                        granted: read
+                    manageUrl: https://github.com/settings/installations/12345
+                    writeUpgradeMessage: "Automated fixes need write access to your repositories: Contents (Read and write) and Pull requests (Read and write). Fixes open pull requests you review — nothing is merged automatically. Approve the update on GitHub to enable fix PRs."
+        "503":
+          description: GitHub installation permissions could not be verified
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GithubPermissionsCheckFailedErrorDto"
 
   /workspaces/{workspaceId}/readiness/fixes/{fixId}/retrigger:
     post:
@@ -5648,6 +5765,18 @@ paths:
                   value:
                     error: Fix is currently generating and cannot be superseded
                     code: fix_generating
+        "422":
+          description: GitHub installation lacks write permissions required for automated fix PRs
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GithubWritePermissionsRequiredErrorDto"
+        "503":
+          description: GitHub installation permissions could not be verified
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GithubPermissionsCheckFailedErrorDto"
 
   /workspaces/{workspaceId}/cursor/platform-key-consent:
     put:
@@ -6604,7 +6733,8 @@ paths:
         Returns `{ ok: false, oauthRequired: true }` when stored credentials exist but refresh
         failed with an OAuth re-authorization error (e.g. `invalid_grant`); the SPA should
         start ZenHR OAuth next. Returns `502` for other upstream failures (same semantics as
-        `GET .../integrations/zenhr/branches`).
+        `GET .../integrations/zenhr/branches`). Returns `503` with `zenhr_sync_in_progress` when
+        an HRIS sync or OAuth refresh is already in progress for this workspace (retry shortly).
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
       responses:
@@ -6642,6 +6772,107 @@ paths:
                 $ref: "#/components/schemas/ErrorMessageDto"
               example:
                 error: zenhr_reconnect_failed
+        "503":
+          $ref: "#/components/responses/ZenHrSyncInProgress"
+
+  /workspaces/{workspaceId}/integrations/zenhr/branches:
+    get:
+      tags: [HRIS, Integrations]
+      summary: List ZenHR branches
+      operationId: listWorkspaceZenHrBranches
+      description: >
+        Lists ZenHR branches for the connected OAuth app so a workspace admin can pick one.
+        Requires workspace admin role. Returns `503` with `zenhr_sync_in_progress` when an HRIS
+        sync or OAuth refresh is already in progress (retry shortly).
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Branch list
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ZenHrBranchesListDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: ZenHR is not connected for this workspace
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: zenhr_not_connected
+        "502":
+          description: ZenHR branch list unavailable
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: zenhr_branches_unavailable
+        "503":
+          $ref: "#/components/responses/ZenHrSyncInProgress"
+
+  /workspaces/{workspaceId}/integrations/zenhr/branch:
+    patch:
+      tags: [HRIS, Integrations]
+      summary: Save selected ZenHR branch
+      operationId: patchWorkspaceZenHrBranch
+      description: >
+        Validates and persists the admin-selected ZenHR branch id on the workspace source.
+        Requires workspace admin role. Returns `503` with `zenhr_sync_in_progress` when an HRIS
+        sync or OAuth refresh is already in progress (retry shortly).
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ZenHrBranchSelectionDto"
+      responses:
+        "200":
+          description: Branch saved
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ZenHrBranchSelectionResultDto"
+        "400":
+          description: Invalid body or unknown branch id
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              examples:
+                invalid_request:
+                  value: { error: invalid_request }
+                invalid_branch_id:
+                  value: { error: invalid_branch_id }
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: ZenHR is not connected for this workspace
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: zenhr_not_connected
+        "502":
+          description: ZenHR branch validation unavailable
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: zenhr_branches_unavailable
+        "503":
+          $ref: "#/components/responses/ZenHrSyncInProgress"
 
   /workspaces/{workspaceId}/hris/status:
     get:
@@ -6972,6 +7203,14 @@ components:
         application/json:
           schema:
             $ref: "#/components/schemas/ErrorMessageDto"
+    ZenHrSyncInProgress:
+      description: HRIS sync or ZenHR OAuth refresh already in progress for this workspace
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorMessageDto"
+          example:
+            error: zenhr_sync_in_progress
 
   schemas:
     ErrorMessageDto:
@@ -7749,6 +7988,9 @@ components:
           type: boolean
         error:
           type: string
+          description: >
+            Machine-readable failure code when success=false (e.g. invalid_token,
+            zenhr_sync_in_progress when ZenHR OAuth refresh is contended).
         executionKeyValid:
           type: boolean
           nullable: true
@@ -10606,9 +10848,50 @@ components:
           nullable: true
           description: Null when the installation has not granted this permission.
 
+    GithubWritePermissionsRequiredErrorDto:
+      type: object
+      additionalProperties: false
+      required: [error, missingPermissions]
+      properties:
+        error:
+          type: string
+          enum: [github_write_permissions_required]
+        missingPermissions:
+          type: array
+          items:
+            $ref: "#/components/schemas/GithubMissingPermissionDto"
+        manageUrl:
+          type: string
+          nullable: true
+          description: GitHub installation settings URL to approve write permissions.
+        writeUpgradeMessage:
+          type: string
+          nullable: true
+          description: Human-readable summary of the write permission upgrade.
+
+    GithubPermissionsCheckFailedErrorDto:
+      type: object
+      additionalProperties: false
+      required: [error]
+      properties:
+        error:
+          type: string
+          enum: [github_permissions_check_failed]
+          description: GitHub installation permissions could not be verified (transient upstream failure).
+
     GithubInstallationSummaryDto:
       type: object
-      required: [installationId, account, repos, permissionsUpgradeRequired]
+      required:
+        - installationId
+        - account
+        - repos
+        - permissionsUpgradeRequired
+        - corePermissionsOk
+        - writePermissionsOk
+        - writePermissionsUpgradeRequired
+        - automatedFixesEnabled
+        - writeAppInstalled
+        - canEnableAutomatedFixes
       properties:
         installationId:
           type: string
@@ -10630,16 +10913,61 @@ components:
         permissionsUpgradeRequired:
           type: boolean
           description: >
-            True when this installation's granted permissions are below what the ThinkAI GitHub App
-            currently requests.
+            True when this installation lacks core read permissions required for connect and analysis.
+            Alias for `!corePermissionsOk`.
+        corePermissionsOk:
+          type: boolean
+          description: >
+            True when installation grants read permissions for repository analysis (contents, metadata,
+            pull requests, and members for org installs).
+        writePermissionsOk:
+          type: boolean
+          description: >
+            True when automated fixes are enabled and the linked Automations (write) installation
+            grants write permissions required for fix PRs.
+        writePermissionsUpgradeRequired:
+          type: boolean
+          description: Alias for `!writePermissionsOk`.
         missingPermissions:
           type: array
           items:
             $ref: "#/components/schemas/GithubMissingPermissionDto"
+          description: Core read permissions still needed for connect and analysis.
+        missingWritePermissions:
+          type: array
+          items:
+            $ref: "#/components/schemas/GithubMissingPermissionDto"
+          description: Write permissions still needed for automated fix PRs.
         upgradeMessage:
           type: string
           nullable: true
-          description: Human-readable summary for UI when permissionsUpgradeRequired is true.
+          description: Human-readable summary for UI when core permissions are missing.
+        writeUpgradeMessage:
+          type: string
+          nullable: true
+          description: Human-readable summary for UI when write permissions are missing.
+        automatedFixesEnabled:
+          type: boolean
+          description: >
+            True when this workspace has enabled automated fixes for this Insights (read)
+            installation and linked a ThinkAI Platform Automations (write) installation.
+        writeAppInstalled:
+          type: boolean
+          description: True when an Automations (write) GitHub App installation is linked.
+        writeInstallationId:
+          type: string
+          nullable: true
+          description: GitHub installation id for the Automations (write) app, when linked.
+        writeManageUrl:
+          type: string
+          format: uri
+          nullable: true
+          description: GitHub settings URL for the Automations (write) installation.
+        canEnableAutomatedFixes:
+          type: boolean
+          description: >
+            True when the Automations app is configured and automated fixes are not yet
+            enabled for this installation (UI may show Enable automated fixes).
 
     GithubPendingApprovalDto:
       type: object
@@ -10924,7 +11252,13 @@ components:
 
     GithubInstallationStatusDto:
       type: object
-      required: [installed, installations, permissionsUpgradeRequired]
+      required:
+        - installed
+        - installations
+        - permissionsUpgradeRequired
+        - corePermissionsOk
+        - writePermissionsOk
+        - writePermissionsUpgradeRequired
       properties:
         installed:
           type: boolean
@@ -10934,7 +11268,25 @@ components:
             $ref: "#/components/schemas/GithubInstallationSummaryDto"
         permissionsUpgradeRequired:
           type: boolean
-          description: True if any connected installation is under-permissioned.
+          description: True if any connected installation lacks core read permissions. Alias for `!corePermissionsOk`.
+        corePermissionsOk:
+          type: boolean
+          description: True when every connected installation grants core read permissions.
+        writePermissionsOk:
+          type: boolean
+          description: True when every connected installation grants write permissions for automated fixes.
+        writePermissionsUpgradeRequired:
+          type: boolean
+          description: True when any connected installation lacks write permissions for automated fixes.
+        missingWritePermissions:
+          type: array
+          items:
+            $ref: "#/components/schemas/GithubMissingPermissionDto"
+          description: Aggregated write permissions missing on installations that lack write access.
+        writeUpgradeMessage:
+          type: string
+          nullable: true
+          description: Human-readable summary when write permissions are missing.
         pendingApproval:
           nullable: true
           allOf:
@@ -11010,6 +11362,17 @@ components:
           format: uri
           maxLength: 256
           description: SPA origin to redirect back to after OAuth; must match server spaOrigins allowlist.
+        intent:
+          type: string
+          enum: [connect, enable_fixes]
+          description: >
+            connect installs ThinkAI Platform Insights (read). enable_fixes installs ThinkAI Platform
+            Automations (write) for the Insights installation identified by installationId.
+        installationId:
+          type: string
+          minLength: 1
+          maxLength: 64
+          description: Insights (read) installation id required when intent is enable_fixes.
 
     GithubInstallUrlResponseDto:
       type: object
@@ -11025,6 +11388,22 @@ components:
           minLength: 16
           maxLength: 128
 
+    GithubAutomatedFixesEnableResponseDto:
+      type: object
+      additionalProperties: false
+      required: [outcome]
+      properties:
+        outcome:
+          type: string
+          enum: [enabled, needs_install]
+          description: >
+            enabled — write app already linked and flag flipped; needs_install — client should
+            call install-url with intent=enable_fixes.
+        status:
+          allOf:
+            - $ref: "#/components/schemas/GithubInstallationStatusDto"
+          description: Present when outcome is enabled.
+
     GithubUserAuthorizeUrlRequestDto:
       type: object
       additionalProperties: false
@@ -13519,6 +13898,38 @@ components:
           enum: [zenhr_oauth_required]
           description: Machine-readable code when ok=false and oauthRequired=true.
 
+    ZenHrBranchDto:
+      type: object
+      required: [id, name]
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+
+    ZenHrBranchesListDto:
+      type: object
+      required: [branches]
+      properties:
+        branches:
+          type: array
+          items:
+            $ref: "#/components/schemas/ZenHrBranchDto"
+
+    ZenHrBranchSelectionDto:
+      type: object
+      required: [branchId]
+      properties:
+        branchId:
+          type: string
+
+    ZenHrBranchSelectionResultDto:
+      type: object
+      required: [branchId]
+      properties:
+        branchId:
+          type: string
+
     HrisTriggerSyncResultDto:
       type: object
       required: [status]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinkai/tai-api-contract",
-  "version": "2.60.0",
+  "version": "2.61.0-pr.901.b553abc8",
   "private": false,
   "type": "module",
   "main": "dist/index.js",