@thinkai/tai-api-contract 2.56.0 → 2.58.0-pr.901.2e63dee8

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.56.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]
@@ -10122,7 +10216,14 @@ components:
 
     GithubInstallationSummaryDto:
       type: object
-      required: [installationId, account, repos, permissionsUpgradeRequired]
+      required:
+        - installationId
+        - account
+        - repos
+        - permissionsUpgradeRequired
+        - corePermissionsOk
+        - writePermissionsOk
+        - writePermissionsUpgradeRequired
       properties:
         installationId:
           type: string
@@ -10144,16 +10245,38 @@ 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 installation grants write permissions required for automated 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.
 
     GithubPendingApprovalDto:
       type: object
@@ -10267,7 +10390,13 @@ components:
 
     GithubInstallationStatusDto:
       type: object
-      required: [installed, installations, permissionsUpgradeRequired]
+      required:
+        - installed
+        - installations
+        - permissionsUpgradeRequired
+        - corePermissionsOk
+        - writePermissionsOk
+        - writePermissionsUpgradeRequired
       properties:
         installed:
           type: boolean
@@ -10277,7 +10406,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:
@@ -11930,6 +12077,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]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinkai/tai-api-contract",
-  "version": "2.56.0",
+  "version": "2.58.0-pr.901.2e63dee8",
   "private": false,
   "type": "module",
   "main": "dist/index.js",

package/src/generated/openapi.ts

@@ -217,6 +217,50 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/platform/banner": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Global platform banner
+         * @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.
+         */
+        get: operations["getPlatformBanner"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/admin/platform/banner": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Read stored and effective global platform banner
+         * @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`.
+         */
+        get: operations["adminGetPlatformBanner"];
+        /**
+         * Set or clear global platform banner
+         * @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`.
+         */
+        put: operations["adminUpsertPlatformBanner"];
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/me": {
         parameters: {
             query?: never;
@@ -4196,11 +4240,22 @@ export interface components {
             manageUrl?: string | null;
             /** Format: date-time */
             lastSyncedAt?: string | null;
-            /** @description True when this installation's granted permissions are below what the ThinkAI GitHub App currently requests. */
+            /** @description True when this installation lacks core read permissions required for connect and analysis. Alias for `!corePermissionsOk`. */
             permissionsUpgradeRequired: boolean;
+            /** @description True when installation grants read permissions for repository analysis (contents, metadata, pull requests, and members for org installs). */
+            corePermissionsOk: boolean;
+            /** @description True when installation grants write permissions required for automated fix PRs. */
+            writePermissionsOk: boolean;
+            /** @description Alias for `!writePermissionsOk`. */
+            writePermissionsUpgradeRequired: boolean;
+            /** @description Core read permissions still needed for connect and analysis. */
             missingPermissions?: components["schemas"]["GithubMissingPermissionDto"][];
-            /** @description Human-readable summary for UI when permissionsUpgradeRequired is true. */
+            /** @description Write permissions still needed for automated fix PRs. */
+            missingWritePermissions?: components["schemas"]["GithubMissingPermissionDto"][];
+            /** @description Human-readable summary for UI when core permissions are missing. */
             upgradeMessage?: string | null;
+            /** @description Human-readable summary for UI when write permissions are missing. */
+            writeUpgradeMessage?: string | null;
         };
         GithubPendingApprovalDto: {
             /**
@@ -4268,8 +4323,18 @@ export interface components {
         GithubInstallationStatusDto: {
             installed: boolean;
             installations: components["schemas"]["GithubInstallationSummaryDto"][];
-            /** @description True if any connected installation is under-permissioned. */
+            /** @description True if any connected installation lacks core read permissions. Alias for `!corePermissionsOk`. */
             permissionsUpgradeRequired: boolean;
+            /** @description True when every connected installation grants core read permissions. */
+            corePermissionsOk: boolean;
+            /** @description True when every connected installation grants write permissions for automated fixes. */
+            writePermissionsOk: boolean;
+            /** @description True when any connected installation lacks write permissions for automated fixes. */
+            writePermissionsUpgradeRequired: boolean;
+            /** @description Aggregated write permissions missing on installations that lack write access. */
+            missingWritePermissions?: components["schemas"]["GithubMissingPermissionDto"][];
+            /** @description Human-readable summary when write permissions are missing. */
+            writeUpgradeMessage?: string | null;
             /** @description Present when an org admin must approve the GitHub App install request. */
             pendingApproval?: components["schemas"]["GithubPendingApprovalDto"] | null;
             /** @description Present when GitHub connect was started but not completed (install OAuth state or account-picker session still active). Omitted when pendingApproval is set. */
@@ -4996,6 +5061,40 @@ export interface components {
             /** Format: date-time */
             createdAt?: string;
         };
+        PlatformBannerDto: {
+            /** @description Stable identifier used for dismiss persistence in the SPA. */
+            id: string;
+            /** @enum {string} */
+            kind: "maintenance" | "outage" | "info";
+            title: string;
+            message: string;
+            dismissible: boolean;
+            /** @description Optional link to the public status page (status.aidrivensdlc.com). */
+            statusPageUrl?: string;
+            /**
+             * Format: date-time
+             * @description When set, the banner is hidden before this instant (UTC).
+             */
+            startsAt?: string;
+            /**
+             * Format: date-time
+             * @description When set, the banner is hidden after this instant (UTC).
+             */
+            endsAt?: string;
+        };
+        PlatformBannerViewDto: {
+            banner: components["schemas"]["PlatformBannerDto"] | null;
+        };
+        PlatformBannerUpsertDto: {
+            /** @description Pass null to clear the active database-managed banner. */
+            banner: components["schemas"]["PlatformBannerDto"] | null;
+        };
+        PlatformAdminBannerDto: {
+            /** @description Banner persisted in the database (editable via PUT). */
+            stored: components["schemas"]["PlatformBannerDto"] | null;
+            /** @description Merged banner shown in the SPA (stored wins over runtime-config fallback). */
+            effective: components["schemas"]["PlatformBannerViewDto"];
+        };
         NotificationDto: {
             id: string;
             /** @enum {string} */
@@ -5833,6 +5932,10 @@ export type SquadDto = components['schemas']['SquadDto'];
 export type WorkflowDto = components['schemas']['WorkflowDto'];
 export type ProjectDto = components['schemas']['ProjectDto'];
 export type ProjectPatchDto = components['schemas']['ProjectPatchDto'];
+export type PlatformBannerDto = components['schemas']['PlatformBannerDto'];
+export type PlatformBannerViewDto = components['schemas']['PlatformBannerViewDto'];
+export type PlatformBannerUpsertDto = components['schemas']['PlatformBannerUpsertDto'];
+export type PlatformAdminBannerDto = components['schemas']['PlatformAdminBannerDto'];
 export type NotificationDto = components['schemas']['NotificationDto'];
 export type NotificationListDto = components['schemas']['NotificationListDto'];
 export type NotificationUnreadCountDto = components['schemas']['NotificationUnreadCountDto'];
@@ -6579,6 +6682,123 @@ export interface operations {
             };
         };
     };
+    getPlatformBanner: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Active platform banner (if any) */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["PlatformBannerViewDto"];
+                };
+            };
+        };
+    };
+    adminGetPlatformBanner: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Admin platform banner view */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["PlatformAdminBannerDto"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            /** @description Caller is not a platform admin. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
+            /** @description Platform banner persistence unavailable. */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
+        };
+    };
+    adminUpsertPlatformBanner: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["PlatformBannerUpsertDto"];
+            };
+        };
+        responses: {
+            /** @description Updated platform banner */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["PlatformBannerViewDto"];
+                };
+            };
+            /** @description Invalid banner payload */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            /** @description Caller is not a platform admin. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    /**
+                     * @example {
+                     *       "error": "Forbidden",
+                     *       "code": "forbidden"
+                     *     }
+                     */
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
+            /** @description Platform banner persistence unavailable. */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
+        };
+    };
     getMe: {
         parameters: {
             query?: never;