@thinkai/tai-api-contract 2.60.0 → 2.61.0

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:
@@ -6604,7 +6608,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 +6647,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 +7078,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 +7863,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
@@ -13519,6 +13636,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",
   "private": false,
   "type": "module",
   "main": "dist/index.js",

package/src/generated/openapi.ts

@@ -2641,7 +2641,7 @@ export interface paths {
         put?: never;
         /**
          * Attempt silent ZenHR reconnect
-         * @description Attempts a silent token refresh and branch ping using stored ZenHR OAuth credentials. Returns `{ ok: true }` when the connection is restored without user interaction. 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`).
+         * @description Attempts a silent token refresh and branch ping using stored ZenHR OAuth credentials. Returns `{ ok: true }` when the connection is restored without user interaction. 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`). Returns `503` with `zenhr_sync_in_progress` when an HRIS sync or OAuth refresh is already in progress for this workspace (retry shortly).
          */
         post: operations["reconnectWorkspaceZenHr"];
         delete?: never;
@@ -2650,6 +2650,46 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/workspaces/{workspaceId}/integrations/zenhr/branches": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * List ZenHR branches
+         * @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).
+         */
+        get: operations["listWorkspaceZenHrBranches"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/workspaces/{workspaceId}/integrations/zenhr/branch": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        /**
+         * Save selected ZenHR branch
+         * @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).
+         */
+        patch: operations["patchWorkspaceZenHrBranch"];
+        trace?: never;
+    };
     "/workspaces/{workspaceId}/hris/status": {
         parameters: {
             query?: never;
@@ -3058,6 +3098,7 @@ export interface components {
         };
         TestConnectionResponseDto: {
             success: boolean;
+            /** @description Machine-readable failure code when success=false (e.g. invalid_token, zenhr_sync_in_progress when ZenHR OAuth refresh is contended). */
             error?: string;
             /** @description Present when `executionToken` was included in the test request. `true` = key passed save-time validation (format + not-admin-key check). `false` = key failed validation (see `executionKeyError` for detail). `null` = `executionToken` was not provided. */
             executionKeyValid?: boolean | null;
@@ -5782,6 +5823,19 @@ export interface components {
              */
             error?: "zenhr_oauth_required";
         };
+        ZenHrBranchDto: {
+            id: string;
+            name: string;
+        };
+        ZenHrBranchesListDto: {
+            branches: components["schemas"]["ZenHrBranchDto"][];
+        };
+        ZenHrBranchSelectionDto: {
+            branchId: string;
+        };
+        ZenHrBranchSelectionResultDto: {
+            branchId: string;
+        };
         HrisTriggerSyncResultDto: {
             /** @enum {string} */
             status: "ok" | "skipped" | "error" | "partial";
@@ -5945,6 +5999,20 @@ export interface components {
                 "application/json": components["schemas"]["ErrorMessageDto"];
             };
         };
+        /** @description HRIS sync or ZenHR OAuth refresh already in progress for this workspace */
+        ZenHrSyncInProgress: {
+            headers: {
+                [name: string]: unknown;
+            };
+            content: {
+                /**
+                 * @example {
+                 *       "error": "zenhr_sync_in_progress"
+                 *     }
+                 */
+                "application/json": components["schemas"]["ErrorMessageDto"];
+            };
+        };
     };
     parameters: {
         WorkspaceId: string;
@@ -6277,6 +6345,10 @@ export type WorkspaceAbsenceListDto = components['schemas']['WorkspaceAbsenceLis
 export type HrisSyncStatusDto = components['schemas']['HrisSyncStatusDto'];
 export type HrisSyncStatusListDto = components['schemas']['HrisSyncStatusListDto'];
 export type ZenHrReconnectResultDto = components['schemas']['ZenHrReconnectResultDto'];
+export type ZenHrBranchDto = components['schemas']['ZenHrBranchDto'];
+export type ZenHrBranchesListDto = components['schemas']['ZenHrBranchesListDto'];
+export type ZenHrBranchSelectionDto = components['schemas']['ZenHrBranchSelectionDto'];
+export type ZenHrBranchSelectionResultDto = components['schemas']['ZenHrBranchSelectionResultDto'];
 export type HrisTriggerSyncResultDto = components['schemas']['HrisTriggerSyncResultDto'];
 export type HrisProviderSyncResultDto = components['schemas']['HrisProviderSyncResultDto'];
 export type ActivityLogPageDto = components['schemas']['ActivityLogPageDto'];
@@ -6284,6 +6356,7 @@ export type ReadinessTokenUsageRowDto = components['schemas']['ReadinessTokenUsa
 export type ReadinessTokenUsageByDimensionRowDto = components['schemas']['ReadinessTokenUsageByDimensionRowDto'];
 export type ResponseUnauthorized = components['responses']['Unauthorized'];
 export type ResponseForbidden = components['responses']['Forbidden'];
+export type ResponseZenHrSyncInProgress = components['responses']['ZenHrSyncInProgress'];
 export type ParameterWorkspaceId = components['parameters']['WorkspaceId'];
 export type ParameterRepoId = components['parameters']['RepoId'];
 export type ParameterProviderSlug = components['parameters']['ProviderSlug'];
@@ -13092,6 +13165,126 @@ export interface operations {
                     "application/json": components["schemas"]["ErrorMessageDto"];
                 };
             };
+            503: components["responses"]["ZenHrSyncInProgress"];
+        };
+    };
+    listWorkspaceZenHrBranches: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspaceId: components["parameters"]["WorkspaceId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Branch list */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ZenHrBranchesListDto"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            /** @description ZenHR is not connected for this workspace */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "error": "zenhr_not_connected"
+                     *     }
+                     */
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
+            /** @description ZenHR branch list unavailable */
+            502: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "error": "zenhr_branches_unavailable"
+                     *     }
+                     */
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
+            503: components["responses"]["ZenHrSyncInProgress"];
+        };
+    };
+    patchWorkspaceZenHrBranch: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspaceId: components["parameters"]["WorkspaceId"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ZenHrBranchSelectionDto"];
+            };
+        };
+        responses: {
+            /** @description Branch saved */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ZenHrBranchSelectionResultDto"];
+                };
+            };
+            /** @description Invalid body or unknown branch id */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            /** @description ZenHR is not connected for this workspace */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "error": "zenhr_not_connected"
+                     *     }
+                     */
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
+            /** @description ZenHR branch validation unavailable */
+            502: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "error": "zenhr_branches_unavailable"
+                     *     }
+                     */
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
+            503: components["responses"]["ZenHrSyncInProgress"];
         };
     };
     getHrisSyncStatus: {