@thinkai/tai-api-contract 2.55.0 → 2.57.0

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.55.0
+  version: 2.57.0
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -64,6 +64,8 @@ tags:
     description: >
       Data subject access / erasure / portability request intake and privacy-ops management (DSAR, issue #611).
       Public and authenticated submission; platform-admin queue, export, and fulfillment.
+  - name: Platform
+    description: Platform-wide banner surfaces (global outage/maintenance banner, issue #284).
 
 paths:
   /admin/users/{userId}:
@@ -694,6 +696,98 @@ paths:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
 
+  /platform/banner:
+    get:
+      tags: [Platform]
+      summary: Global platform banner
+      operationId: getPlatformBanner
+      security: []
+      description: >
+        Returns the active global outage or maintenance banner for the platform shell, if any.
+        No authentication required so signed-in users can see incident messaging during partial outages.
+        When both a database-managed banner and a runtime-config fallback exist, the database value wins.
+      responses:
+        "200":
+          description: Active platform banner (if any)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PlatformBannerViewDto"
+
+  /admin/platform/banner:
+    get:
+      tags: [PlatformAdmin]
+      summary: Read stored and effective global platform banner
+      operationId: adminGetPlatformBanner
+      description: >
+        Platform admins only. Returns the database-stored banner (`stored`) for editing and the
+        merged banner users see (`effective`, DB wins over runtime-config fallback). Requires Bearer
+        JWT from an email on `PLATFORM_ADMIN_EMAILS`.
+      responses:
+        "200":
+          description: Admin platform banner view
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PlatformAdminBannerDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Caller is not a platform admin.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "503":
+          description: Platform banner persistence unavailable.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+    put:
+      tags: [PlatformAdmin]
+      summary: Set or clear global platform banner
+      operationId: adminUpsertPlatformBanner
+      description: >
+        Platform admins may activate, update, or clear (`banner: null`) the global outage/maintenance banner
+        shown in the authenticated SPA shell. Requires Bearer JWT from an email on `PLATFORM_ADMIN_EMAILS`.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/PlatformBannerUpsertDto"
+      responses:
+        "200":
+          description: Updated platform banner
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PlatformBannerViewDto"
+        "400":
+          description: Invalid banner payload
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Caller is not a platform admin.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Forbidden
+                code: forbidden
+        "503":
+          description: Platform banner persistence unavailable.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
   /me:
     get:
       tags: [Me]
@@ -4666,6 +4760,53 @@ paths:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
 
+  /workspaces/{workspaceId}/agentic-foundation/repo-scope:
+    put:
+      tags: [AgenticFoundation]
+      summary: Update Agentic Foundation repository scope
+      description: >
+        Bulk include/exclude materialized repos from Agentic Foundation by toggling the existing
+        `user_removed` archive state. Excluded repos remain integrated for productivity metrics.
+        Only workspace admins may call this endpoint. Partial failures are reported per repo.
+      operationId: putAgenticFoundationRepoScope
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/PutAgenticFoundationRepoScopeBodyDto"
+            example:
+              changes:
+                - repoId: 00000000-0000-0000-0000-000000000101
+                  included: false
+                - repoId: 00000000-0000-0000-0000-000000000102
+                  included: true
+      responses:
+        "200":
+          description: Scope changes applied (possibly with per-repo failures)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PutAgenticFoundationRepoScopeResponseDto"
+        "400":
+          description: Invalid request body
+          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}/agentic-foundation/dashboard:
     get:
       tags: [AgenticFoundation]
@@ -11129,8 +11270,8 @@ components:
         archivedReason:
           type: string
           nullable: true
-          enum: [github_removed, installation_disconnected, installation_replaced, superseded]
-          description: Why the repo was archived. Only present when `archivedAt` is set.
+          enum: [github_removed, installation_disconnected, installation_replaced, superseded, user_removed]
+          description: Why the repo was archived. `user_removed` means excluded from Agentic Foundation scope only. Only present when `archivedAt` is set.
         eligibilityStatus:
           type: string
           enum: [eligible, ineligible]
@@ -11273,7 +11414,7 @@ components:
         archivedReason:
           type: string
           nullable: true
-          enum: [github_removed, installation_disconnected, installation_replaced, superseded]
+          enum: [github_removed, installation_disconnected, installation_replaced, superseded, user_removed]
         eligibilityStatus:
           type: string
           enum: [eligible, ineligible]
@@ -11883,6 +12024,67 @@ components:
           type: string
           format: date-time
 
+    PlatformBannerDto:
+      type: object
+      required: [id, kind, title, message, dismissible]
+      properties:
+        id:
+          type: string
+          description: Stable identifier used for dismiss persistence in the SPA.
+        kind:
+          type: string
+          enum: [maintenance, outage, info]
+        title:
+          type: string
+        message:
+          type: string
+        dismissible:
+          type: boolean
+        statusPageUrl:
+          type: string
+          description: Optional link to the public status page (status.aidrivensdlc.com).
+        startsAt:
+          type: string
+          format: date-time
+          description: When set, the banner is hidden before this instant (UTC).
+        endsAt:
+          type: string
+          format: date-time
+          description: When set, the banner is hidden after this instant (UTC).
+
+    PlatformBannerViewDto:
+      type: object
+      required: [banner]
+      properties:
+        banner:
+          allOf:
+            - $ref: "#/components/schemas/PlatformBannerDto"
+          nullable: true
+
+    PlatformBannerUpsertDto:
+      type: object
+      required: [banner]
+      properties:
+        banner:
+          allOf:
+            - $ref: "#/components/schemas/PlatformBannerDto"
+          nullable: true
+          description: Pass null to clear the active database-managed banner.
+
+    PlatformAdminBannerDto:
+      type: object
+      required: [stored, effective]
+      properties:
+        stored:
+          allOf:
+            - $ref: "#/components/schemas/PlatformBannerDto"
+          nullable: true
+          description: Banner persisted in the database (editable via PUT).
+        effective:
+          allOf:
+            - $ref: "#/components/schemas/PlatformBannerViewDto"
+          description: Merged banner shown in the SPA (stored wins over runtime-config fallback).
+
     NotificationDto:
       type: object
       required: [id, type, title, message, read, createdAt]
@@ -12453,6 +12655,77 @@ components:
           nullable: true
           description: ID of the freshly enqueued readiness scan run (only present on re-add).
 
+    PutAgenticFoundationRepoScopeChangeDto:
+      type: object
+      required: [repoId, included]
+      properties:
+        repoId:
+          type: string
+          format: uuid
+        included:
+          type: boolean
+          description: >
+            `true` to include in Agentic Foundation scope (unarchive user_removed).
+            `false` to exclude (soft-archive with archived_reason user_removed).
+
+    PutAgenticFoundationRepoScopeBodyDto:
+      type: object
+      required: [changes]
+      properties:
+        changes:
+          type: array
+          minItems: 1
+          maxItems: 200
+          items:
+            $ref: "#/components/schemas/PutAgenticFoundationRepoScopeChangeDto"
+
+    PutAgenticFoundationRepoScopeAppliedDto:
+      type: object
+      required: [repoId, status]
+      properties:
+        repoId:
+          type: string
+          format: uuid
+        status:
+          type: string
+          enum: [Active, Inactive]
+        runId:
+          type: string
+          format: uuid
+          nullable: true
+
+    PutAgenticFoundationRepoScopeFailureDto:
+      type: object
+      required: [repoId, code, message]
+      properties:
+        repoId:
+          type: string
+          format: uuid
+        code:
+          type: string
+          enum:
+            - not_found
+            - scan_in_progress
+            - not_archived
+            - already_active
+            - system_archived
+            - forbidden
+        message:
+          type: string
+
+    PutAgenticFoundationRepoScopeResponseDto:
+      type: object
+      required: [applied, failures]
+      properties:
+        applied:
+          type: array
+          items:
+            $ref: "#/components/schemas/PutAgenticFoundationRepoScopeAppliedDto"
+        failures:
+          type: array
+          items:
+            $ref: "#/components/schemas/PutAgenticFoundationRepoScopeFailureDto"
+
     ActivityLogEventTypeDto:
       type: string
       description: Type of workspace lifecycle event.

package/package.json

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