@thinkai/tai-api-contract 2.11.1 → 2.13.0

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.11.1
+  version: 2.13.0
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -52,6 +52,8 @@ tags:
     description: Agentic Foundation pillars (epic #278); reads stored repository readiness snapshots
   - name: YourAiJourney
     description: Your AI Journey dashboard aggregators (epic #267); composes readiness, metrics, and AI-spend data for the /dashboard page
+  - name: WorkspaceActivity
+    description: Workspace-wide lifecycle activity log — repo add/remove/re-add and integration lifecycle events (issue #515).
   - name: PlatformAdmin
     description: Platform-admin operations restricted to PLATFORM_ADMIN_EMAILS. Callers must present a valid JWT from an email on that allowlist; all other callers receive 403.
 
@@ -2282,6 +2284,12 @@ paths:
         - $ref: "#/components/parameters/PaginationOrder"
         - $ref: "#/components/parameters/ReadinessRepoSearch"
         - $ref: "#/components/parameters/ReadinessRepoLanguage"
+        - name: includeArchived
+          in: query
+          description: When `true`, includes Inactive (user-removed) repos alongside Active ones. Default is `false` (active only).
+          schema:
+            type: boolean
+            default: false
       responses:
         "200":
           description: Paginated repositories analyzed
@@ -2462,6 +2470,62 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
+    patch:
+      tags: [RepositoryReadiness]
+      summary: Archive (remove) or restore (re-add) a repository
+      description: >
+        Set `archived: true` to soft-remove the repo (Inactive). Set `archived: false` to re-add a
+        previously Inactive repo (Active). Re-add reuses the same `repo_id` row so historical scan
+        foreign keys remain intact, and automatically enqueues a fresh readiness scan.
+
+        Returns `409` with `code: repo_scan_in_progress` if a scan is queued or running when archiving.
+        Returns `409` with `code: repo_already_active` if re-adding a repo that is already Active.
+      operationId: patchReadinessRepo
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/RepoId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/PatchRepoArchiveBodyDto"
+            examples:
+              archive:
+                value:
+                  archived: true
+              restore:
+                value:
+                  archived: false
+      responses:
+        "200":
+          description: Repo status updated
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PatchRepoArchiveResponseDto"
+        "400":
+          description: Malformed request body or repoId
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace or repository not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "409":
+          description: Conflict — scan in progress or repo already in the requested state
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
 
   /workspaces/{workspaceId}/readiness/repos/{repoId}/runs:
     get:
@@ -2603,6 +2667,83 @@ paths:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
 
+  /workspaces/{workspaceId}/activity:
+    get:
+      tags: [WorkspaceActivity]
+      summary: Workspace activity log (paginated)
+      operationId: listWorkspaceActivity
+      description: >
+        Paginated, chronological feed of workspace-scoped lifecycle events: repository add/remove/re-add
+        and GitHub integration add/remove. Inactive repos remain visible in this log.
+        Filter by `eventType`, `actorUserId`, or date range (`since`/`until`).
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/PaginationLimit"
+        - $ref: "#/components/parameters/PaginationOffset"
+        - $ref: "#/components/parameters/PaginationOrder"
+        - name: eventType
+          in: query
+          description: Filter to a specific event type.
+          schema:
+            $ref: "#/components/schemas/ActivityLogEventTypeDto"
+        - name: actorUserId
+          in: query
+          description: Filter to events performed by a specific user (UUID).
+          schema:
+            type: string
+            format: uuid
+        - name: since
+          in: query
+          description: ISO-8601 lower bound on `occurredAt` (inclusive).
+          schema:
+            type: string
+            format: date-time
+        - name: until
+          in: query
+          description: ISO-8601 upper bound on `occurredAt` (inclusive).
+          schema:
+            type: string
+            format: date-time
+        - name: eventCategory
+          in: query
+          required: false
+          description: >
+            Filter by event namespace prefix (e.g. "fix", "repo", "integration", "readiness", "config", "member").
+          schema:
+            type: string
+        - name: search
+          in: query
+          required: false
+          description: >
+            Case-insensitive substring filter applied across repo name,
+            integration type, actor email, and actor display name.
+          schema:
+            type: string
+            maxLength: 200
+      responses:
+        "200":
+          description: Paginated activity log entries
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ActivityLogPageDto"
+        "400":
+          description: Invalid query parameters
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
   /workspaces/{workspaceId}/readiness/score-history:
     get:
       tags: [RepositoryReadiness]
@@ -3897,6 +4038,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:
@@ -7363,3 +7621,241 @@ components:
                 type: integer
               activeUsers:
                 type: integer
+
+    PatchRepoArchiveBodyDto:
+      type: object
+      required: [archived]
+      properties:
+        archived:
+          type: boolean
+          description: >
+            `true` to soft-remove (Inactive). `false` to restore a previously Inactive repo (Active),
+            which also enqueues a fresh readiness scan.
+
+    PatchRepoArchiveResponseDto:
+      type: object
+      required: [repoId, status]
+      properties:
+        repoId:
+          type: string
+          format: uuid
+        status:
+          type: string
+          enum: [Active, Inactive]
+          description: Current lifecycle status of the repository after the operation.
+        runId:
+          type: string
+          format: uuid
+          nullable: true
+          description: ID of the freshly enqueued readiness scan run (only present on re-add).
+
+    ActivityLogEventTypeDto:
+      type: string
+      description: Type of workspace lifecycle event.
+      enum:
+        - repo.added
+        - repo.removed
+        - repo.readded
+        - integration.github.added
+        - integration.github.updated
+        - integration.github.removed
+        - integration.github.permissions_changed
+        - integration.github.repo_added
+        - integration.github.repo_removed
+        - fix.requested
+        - fix.generating
+        - fix.pr_created
+        - fix.merged
+        - fix.failed
+        - readiness.scan_started
+        - readiness.scan_completed
+        - readiness.scan_failed
+        - readiness.scan_partial
+        - config.cursor.added
+        - config.cursor.updated
+        - config.cursor.removed
+        - config.cursor.platform_key_enabled
+        - config.cursor.platform_key_disabled
+        - config.claude.added
+        - config.claude.updated
+        - config.claude.removed
+        - member.invited
+        - member.role_changed
+        - member.removed
+
+    ActivityLogActorDto:
+      type: object
+      required: [userId]
+      properties:
+        userId:
+          type: string
+          format: uuid
+        email:
+          type: string
+          format: email
+          nullable: true
+        name:
+          type: string
+          nullable: true
+
+    ActivityLogEntryDto:
+      type: object
+      required: [id, eventType, eventCategory, occurredAt, actorType]
+      properties:
+        id:
+          type: string
+          format: uuid
+        eventType:
+          $ref: "#/components/schemas/ActivityLogEventTypeDto"
+        eventCategory:
+          type: string
+          description: Namespace prefix derived from event_type (e.g. "fix", "repo", "config").
+        occurredAt:
+          type: string
+          format: date-time
+        actorType:
+          type: string
+          enum: [user, system, webhook]
+          description: Whether the event was triggered by a human user, a batch/system process, or a webhook.
+        actor:
+          nullable: true
+          allOf:
+            - $ref: "#/components/schemas/ActivityLogActorDto"
+        repoId:
+          type: string
+          format: uuid
+          nullable: true
+        repoName:
+          type: string
+          nullable: true
+        integrationId:
+          type: string
+          format: uuid
+          nullable: true
+        integrationType:
+          type: string
+          nullable: true
+        fixRequestId:
+          type: string
+          format: uuid
+          nullable: true
+          description: ID of the related fix request (fix.* events).
+        issueId:
+          type: string
+          format: uuid
+          nullable: true
+          description: ID of the related readiness issue (fix.* events).
+        readinessRunId:
+          type: string
+          format: uuid
+          nullable: true
+          description: ID of the related readiness run (readiness.* events).
+        metadata:
+          type: object
+          additionalProperties: true
+          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"
+        - type: object
+          required: [items]
+          properties:
+            items:
+              type: array
+              items:
+                $ref: "#/components/schemas/ActivityLogEntryDto"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinkai/tai-api-contract",
-  "version": "2.11.1",
+  "version": "2.13.0",
   "private": false,
   "type": "module",
   "main": "dist/index.js",
@@ -21,6 +21,7 @@
   "dependencies": {},
   "devDependencies": {
     "@stoplight/spectral-cli": "^6.15.1",
+    "jsonpath-plus": "^10.3.0",
     "openapi-typescript": "^7.13.0",
     "typescript": "~5.3.0"
   },