@thinkai/tai-api-contract 2.56.0 → 2.57.0

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]
@@ -11930,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]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thinkai/tai-api-contract",
-  "version": "2.56.0",
+  "version": "2.57.0",
   "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;
@@ -4996,6 +5040,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 +5911,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 +6661,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;