@thinkai/tai-api-contract 2.12.0 → 2.14.0

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.12.0
+  version: 2.14.0
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -1703,6 +1703,153 @@ paths:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
 
+  /workspaces/{workspaceId}/integrations/github/user-authorize-url:
+    post:
+      tags: [Integrations]
+      summary: Create GitHub user OAuth authorize URL
+      operationId: postGithubUserAuthorizeUrl
+      description: >
+        Starts GitHub user OAuth for org/account picker. Workspace admin only.
+        After callback, SPA opens account picker with `?gh=account_picker&session=…`.
+      security:
+        - bearerAuth: []
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/GithubUserAuthorizeUrlRequestDto"
+      responses:
+        "200":
+          description: User OAuth authorize URL + signed state
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GithubUserAuthorizeUrlResponseDto"
+        "400":
+          description: Request validation failed
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "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"
+        "500":
+          description: GitHub user OAuth not configured
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/integrations/github/connectable-accounts:
+    get:
+      tags: [Integrations]
+      summary: List connectable GitHub accounts from user OAuth session
+      operationId: getGithubConnectableAccounts
+      description: >
+        Returns org/user accounts from a completed user OAuth picker session.
+        Session must belong to the caller and workspace.
+      security:
+        - bearerAuth: []
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: session
+          in: query
+          required: true
+          schema:
+            type: string
+            minLength: 16
+            maxLength: 128
+      responses:
+        "200":
+          description: Connectable accounts snapshot
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GithubConnectableAccountsResponseDto"
+        "400":
+          description: Missing or invalid session
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace or session not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/integrations/github/connect-by-org:
+    post:
+      tags: [Integrations]
+      summary: Link GitHub App installation by org or user account
+      operationId: postGithubConnectByOrg
+      description: >
+        Server-side link when the ThinkAI GitHub App is already installed on the selected account.
+        Returns `needs_oauth` when install redirect is required. Workspace admin only.
+      security:
+        - bearerAuth: []
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/GithubConnectByOrgRequestDto"
+      responses:
+        "200":
+          description: Connect result
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GithubConnectByOrgResponseDto"
+        "400":
+          description: Invalid session or account
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace or session not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "409":
+          description: GitHub installation already linked to another workspace
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: installation_already_linked
+        "503":
+          description: GitHub API error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
   /workspaces/{workspaceId}/integrations/ai-tool/{provider}/refresh:
     post:
       tags: [Integrations]
@@ -2007,6 +2154,52 @@ paths:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
 
+  /integrations/github/user-oauth/callback:
+    get:
+      tags: [Integrations]
+      summary: GitHub user OAuth callback
+      operationId: getGithubUserOauthCallback
+      description: >
+        Public callback for GitHub user OAuth (org/account picker flow).
+        Exchanges code, builds connectable-accounts snapshot, redirects SPA with
+        `?gh=account_picker&session=…`.
+      parameters:
+        - name: state
+          in: query
+          required: true
+          schema:
+            type: string
+        - name: code
+          in: query
+          required: false
+          schema:
+            type: string
+        - name: error
+          in: query
+          required: false
+          schema:
+            type: string
+        - name: error_description
+          in: query
+          required: false
+          schema:
+            type: string
+      responses:
+        "302":
+          description: Redirect to ThinkAI SPA with account picker session or error
+        "501":
+          description: Workspace store not configured
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "503":
+          description: SPA origin or GitHub OAuth configuration missing
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
   /integrations/github/webhook:
     post:
       tags: [Integrations]
@@ -4038,6 +4231,123 @@ paths:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
 
+  /workspaces/{workspaceId}/absences:
+    get:
+      tags: [HRIS]
+      summary: List absence records
+      operationId: listWorkspaceAbsences
+      description: >
+        Returns time-off/absence records sourced from connected HRIS providers (e.g. Personio)
+        for the given date window. Requires workspace membership.
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: from
+          in: query
+          description: Start of date window (ISO YYYY-MM-DD). Defaults to today.
+          schema: { type: string, format: date }
+        - name: to
+          in: query
+          description: End of date window (ISO YYYY-MM-DD). Defaults to 90 days from today.
+          schema: { type: string, format: date }
+      responses:
+        "200":
+          description: Absence list with last sync timestamp
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WorkspaceAbsenceListDto"
+              example:
+                absences:
+                  - source: personio
+                    employeeEmail: alice@example.com
+                    absenceType: Vacation
+                    startDate: "2025-07-01"
+                    endDate: "2025-07-05"
+                    halfDayStart: false
+                    halfDayEnd: false
+                    status: approved
+                syncedAt: "2025-06-30T08:00:00.000Z"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+
+  /workspaces/{workspaceId}/hris/status:
+    get:
+      tags: [HRIS]
+      summary: HRIS sync status
+      operationId: getHrisSyncStatus
+      description: >
+        Returns the last sync status for every HRIS provider connected to the workspace.
+        Returns an empty `statuses` array when no HRIS source has been synced yet.
+        Requires workspace membership.
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Sync status list
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HrisSyncStatusListDto"
+              example:
+                statuses:
+                  - provider: personio
+                    lastSyncAt: "2025-06-30T08:00:00.000Z"
+                    status: ok
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+
+  /workspaces/{workspaceId}/hris/sync:
+    post:
+      tags: [HRIS]
+      summary: Trigger manual HRIS sync
+      operationId: triggerHrisSync
+      description: >
+        Manually triggers an HRIS sync for the workspace. Runs synchronously and returns
+        the result. Requires editor role (same permission level as org-chart writes).
+        Returns 422 when no HRIS source is configured.
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Sync completed successfully
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HrisTriggerSyncResultDto"
+              example:
+                status: ok
+                employeeCount: 42
+                absenceCount: 7
+                durationMs: 1234
+        "422":
+          description: No HRIS source configured for this workspace
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HrisTriggerSyncResultDto"
+              example:
+                status: skipped
+                code: no_personio_source
+                reason: no_personio_source
+        "500":
+          description: Sync failed (Personio API error, decryption failure, etc.)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/HrisTriggerSyncResultDto"
+              example:
+                status: error
+                code: hris_sync_failed
+                error: "Personio employees API 401"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+
 components:
   securitySchemes:
     bearerAuth:
@@ -5985,6 +6295,104 @@ components:
           minLength: 16
           maxLength: 128
 
+    GithubUserAuthorizeUrlRequestDto:
+      type: object
+      additionalProperties: false
+      properties:
+        returnPath:
+          type: string
+          pattern: '^/[A-Za-z0-9/_\-\?\=&]*$'
+          maxLength: 256
+
+    GithubUserAuthorizeUrlResponseDto:
+      type: object
+      additionalProperties: false
+      required: [url, state]
+      properties:
+        url:
+          type: string
+          format: uri
+          maxLength: 2048
+        state:
+          type: string
+          minLength: 16
+          maxLength: 128
+
+    GithubConnectableAccountDto:
+      type: object
+      additionalProperties: false
+      required: [login, type, appInstalled]
+      properties:
+        login:
+          type: string
+        type:
+          type: string
+          enum: [Organization, User]
+        avatarUrl:
+          type: string
+          format: uri
+          nullable: true
+        appInstalled:
+          type: boolean
+          description: Whether the ThinkAI GitHub App is already installed on this account.
+
+    GithubConnectableAccountsResponseDto:
+      type: object
+      additionalProperties: false
+      required: [accounts]
+      properties:
+        accounts:
+          type: array
+          items:
+            $ref: "#/components/schemas/GithubConnectableAccountDto"
+
+    GithubConnectByOrgRequestDto:
+      type: object
+      additionalProperties: false
+      required: [accountLogin, accountType, session]
+      properties:
+        accountLogin:
+          type: string
+          minLength: 1
+          maxLength: 39
+        accountType:
+          type: string
+          enum: [Organization, User]
+        session:
+          type: string
+          minLength: 16
+          maxLength: 128
+
+    GithubConnectByOrgConnectedDto:
+      type: object
+      additionalProperties: false
+      required: [outcome, status]
+      properties:
+        outcome:
+          type: string
+          enum: [connected]
+        status:
+          $ref: "#/components/schemas/GithubInstallationStatusDto"
+
+    GithubConnectByOrgNeedsOAuthDto:
+      type: object
+      additionalProperties: false
+      required: [outcome]
+      properties:
+        outcome:
+          type: string
+          enum: [needs_oauth]
+
+    GithubConnectByOrgResponseDto:
+      oneOf:
+        - $ref: "#/components/schemas/GithubConnectByOrgConnectedDto"
+        - $ref: "#/components/schemas/GithubConnectByOrgNeedsOAuthDto"
+      discriminator:
+        propertyName: outcome
+        mapping:
+          connected: "#/components/schemas/GithubConnectByOrgConnectedDto"
+          needs_oauth: "#/components/schemas/GithubConnectByOrgNeedsOAuthDto"
+
     AIReadinessDto:
       type: object
       required:
@@ -7639,6 +8047,99 @@ components:
           nullable: true
           description: Event-specific supplementary data (before/after state, installation IDs, etc.).
 
+    WorkspaceAbsenceDto:
+      type: object
+      required: [source, employeeEmail, absenceType, startDate, endDate, halfDayStart, halfDayEnd, status]
+      properties:
+        source:
+          type: string
+          description: HRIS provider that sourced this record (e.g. 'personio', 'zenhr').
+        employeeEmail:
+          type: string
+          format: email
+        absenceType:
+          type: string
+        startDate:
+          type: string
+          format: date
+        endDate:
+          type: string
+          format: date
+        halfDayStart:
+          type: boolean
+        halfDayEnd:
+          type: boolean
+        status:
+          type: string
+          enum: [approved, pending, rejected]
+
+    WorkspaceAbsenceListDto:
+      type: object
+      required: [absences, syncedAt]
+      properties:
+        absences:
+          type: array
+          items:
+            $ref: "#/components/schemas/WorkspaceAbsenceDto"
+        syncedAt:
+          type: string
+          format: date-time
+          nullable: true
+          description: ISO timestamp of the most recent successful HRIS sync, or null if never synced.
+
+    HrisSyncStatusDto:
+      type: object
+      required: [provider, lastSyncAt, status]
+      properties:
+        provider:
+          type: string
+          description: Provider identifier (e.g. 'personio', 'zenhr').
+        lastSyncAt:
+          type: string
+          format: date-time
+          nullable: true
+        status:
+          type: string
+          enum: [ok, error, never]
+        lastError:
+          type: string
+          nullable: true
+
+    HrisSyncStatusListDto:
+      type: object
+      required: [statuses]
+      properties:
+        statuses:
+          type: array
+          items:
+            $ref: "#/components/schemas/HrisSyncStatusDto"
+
+    HrisTriggerSyncResultDto:
+      type: object
+      required: [status]
+      properties:
+        status:
+          type: string
+          enum: [ok, skipped, error]
+        code:
+          type: string
+          description: Stable machine-readable code (e.g. 'no_personio_source', 'hris_sync_failed').
+        employeeCount:
+          type: integer
+          description: Number of employees synced (present when status = 'ok').
+        absenceCount:
+          type: integer
+          description: Number of absence records synced (present when status = 'ok').
+        durationMs:
+          type: integer
+          description: Wall-clock duration of the sync in milliseconds (present when status = 'ok').
+        reason:
+          type: string
+          description: Machine-readable reason for a skipped sync (e.g. 'no_personio_source').
+        error:
+          type: string
+          description: Error message when status = 'error'.
+
     ActivityLogPageDto:
       allOf:
         - $ref: "#/components/schemas/PageMetaDto"

package/package.json

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