@thinkai/tai-api-contract 2.147.1 → 2.149.0

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.147.1
+  version: 2.149.0
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -9204,15 +9204,42 @@ paths:
     get:
       tags: [Notifications]
       summary: Paginated notifications
+      description: >
+        Inbox for the current user in this workspace. Applies the same notification-type
+        preference filter and routine-title exclusion as the unread badge. `view` defaults to
+        `all` so a client that omits it still receives success rows. Severity is the stored
+        column and is not recomputed per request.
       operationId: listNotifications
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
         - name: limit
           in: query
-          schema: { type: integer, minimum: 1 }
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 50
         - name: offset
           in: query
-          schema: { type: integer, minimum: 0 }
+          schema:
+            type: integer
+            minimum: 0
+            default: 0
+        - name: view
+          in: query
+          description: >
+            `all` returns every severity. `needs_action` returns only `warning` and
+            `destructive`. Omitted is `all`.
+          schema:
+            type: string
+            enum: [all, needs_action]
+            default: all
+        - name: unread
+          in: query
+          description: >
+            Omit to include read and unread rows. `true` is unread only. `false` is read only.
+          schema:
+            type: boolean
       responses:
         "200":
           description: Page of notifications
@@ -9220,6 +9247,12 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/NotificationListDto"
+        "400":
+          description: Invalid `view` or `unread`
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
 
@@ -9227,6 +9260,10 @@ paths:
     get:
       tags: [Notifications]
       summary: Unread notification count
+      description: >
+        Unread rows for the current user in this workspace after the notification-type
+        preference filter and the routine-title exclusion. `count` is not capped.
+        `hasUnreadCritical` is true when at least one of those rows has severity `destructive`.
       operationId: getNotificationUnreadCount
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
@@ -9363,6 +9400,9 @@ paths:
     get:
       tags: [Preferences]
       summary: Get preferences for current user
+      description: >
+        Returns saved preferences, including `notificationChannels`. An empty or missing
+        profile returns defaults (`email.status` is `digest`; every other channel cell is `off`).
       operationId: getMyPreferences
       responses:
         "200":
@@ -9376,13 +9416,20 @@ paths:
     put:
       tags: [Preferences]
       summary: Upsert preferences
+      description: >
+        Replaces the saved preferences object. Omitting `notificationChannels` keeps the
+        stored cells, or the defaults when none are stored. A body that includes
+        `notificationChannels` replaces those cells; any missing key inside it uses the
+        default (`email.status` = `digest`, every other cell = `off`). Setting
+        `email.status` to `off` returns 400 `notification_channel_required`. In-app
+        `notifications` booleans are independent of these cells.
       operationId: putMyPreferences
       requestBody:
         required: true
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/PreferencesDto"
+              $ref: "#/components/schemas/PutPreferencesBodyDto"
       responses:
         "200":
           description: Saved preferences
@@ -9391,11 +9438,15 @@ paths:
               schema:
                 $ref: "#/components/schemas/PreferencesDto"
         "400":
-          description: Validation failed
+          description: >
+            Validation failed, or Status email was set to off
+            (`code` `notification_channel_required`).
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/PreferencesValidationErrorDto"
+                oneOf:
+                  - $ref: "#/components/schemas/PreferencesValidationErrorDto"
+                  - $ref: "#/components/schemas/NotificationChannelRequiredErrorDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
 
@@ -9450,9 +9501,10 @@ paths:
       tags: [Me]
       summary: App chrome bootstrap payload
       description: >
-        Returns the authenticated user's profile, workspace list, and preferences in one response.
+        Returns the authenticated user's profile, workspace list, and preferences
+        (including `notificationChannels`) in one response.
         When `workspaceId` is provided and resolves to a workspace the caller belongs to, also
-        returns platform banner, unread notification count, journey progress, and connectors
+        returns platform banner, unread notification count (`count` and `hasUnreadCritical`), journey progress, and connectors
         snapshot. Invalid, unknown, or non-member `workspaceId` values do not produce 403/404 —
         the response is still 200 with only `me`, `workspaces`, and `preferences` (workspace-scoped
         fields omitted).
@@ -18501,7 +18553,7 @@ components:
 
     NotificationDto:
       type: object
-      required: [id, type, title, message, read, createdAt]
+      required: [id, type, title, message, read, createdAt, severity]
       properties:
         id:
           type: string
@@ -18522,6 +18574,8 @@ components:
         severity:
           type: string
           enum: [success, warning, destructive, muted, neutral]
+          description: >
+            Stored on the notification row at fan-out. `destructive` is the only critical severity.
         triggeredBy:
           type: string
           nullable: true
@@ -18539,11 +18593,17 @@ components:
 
     NotificationUnreadCountDto:
       type: object
-      required: [count]
+      required: [count, hasUnreadCritical]
       properties:
         count:
           type: integer
           minimum: 0
+          description: >
+            Unread rows after the type-preference filter and routine-title exclusion. Not capped.
+        hasUnreadCritical:
+          type: boolean
+          description: >
+            True when at least one of those unread rows has severity `destructive`.
 
     EffectiveTaskRowDto:
       type: object
@@ -18708,9 +18768,156 @@ components:
           type: boolean
           description: System / platform announcements.
 
+    NotificationEmailStatusMode:
+      type: string
+      description: >
+        Status email delivery. `digest` (default) is the weekly mail. `immediate`
+        sends as events arrive. `off` is not allowed.
+      enum: [immediate, digest]
+
+    NotificationEmailDeliveryMode:
+      type: string
+      description: >
+        Email delivery for comment, activity, or system. Default `off`.
+        `immediate` sends as events arrive. `digest` is the weekly mail.
+      enum: [off, immediate, digest]
+
+    NotificationChatDeliveryMode:
+      type: string
+      description: >
+        Slack or Teams delivery for one category. Default `off` until that member
+        changes the cell. `dm` is a direct message. `channel` posts to the workspace
+        channel an admin saved. Connecting chat does not turn cells on.
+      enum: [off, dm, channel]
+
+    NotificationEmailChannelsDto:
+      type: object
+      additionalProperties: false
+      required: [status, comment, activity, system]
+      properties:
+        status:
+          $ref: "#/components/schemas/NotificationEmailStatusMode"
+        comment:
+          $ref: "#/components/schemas/NotificationEmailDeliveryMode"
+        activity:
+          $ref: "#/components/schemas/NotificationEmailDeliveryMode"
+        system:
+          $ref: "#/components/schemas/NotificationEmailDeliveryMode"
+
+    NotificationChatChannelsDto:
+      type: object
+      additionalProperties: false
+      required: [status, comment, activity, system]
+      properties:
+        status:
+          $ref: "#/components/schemas/NotificationChatDeliveryMode"
+        comment:
+          $ref: "#/components/schemas/NotificationChatDeliveryMode"
+        activity:
+          $ref: "#/components/schemas/NotificationChatDeliveryMode"
+        system:
+          $ref: "#/components/schemas/NotificationChatDeliveryMode"
+
+    NotificationChannelsDto:
+      type: object
+      additionalProperties: false
+      required: [email, slack, teams]
+      description: >
+        Delivery cells beside the in-app Message Center switches. Defaults:
+        `email.status` is `digest`; every other cell is `off`. Inbox rows whose
+        type is `integration` use the `status` cell.
+      properties:
+        email:
+          $ref: "#/components/schemas/NotificationEmailChannelsDto"
+        slack:
+          $ref: "#/components/schemas/NotificationChatChannelsDto"
+        teams:
+          $ref: "#/components/schemas/NotificationChatChannelsDto"
+
+    PutNotificationEmailChannelsDto:
+      type: object
+      additionalProperties: false
+      description: >
+        Partial email cells. Omitted keys are filled with defaults on save
+        (`status` = `digest`, other keys = `off`).
+      properties:
+        status:
+          $ref: "#/components/schemas/NotificationEmailStatusMode"
+        comment:
+          $ref: "#/components/schemas/NotificationEmailDeliveryMode"
+        activity:
+          $ref: "#/components/schemas/NotificationEmailDeliveryMode"
+        system:
+          $ref: "#/components/schemas/NotificationEmailDeliveryMode"
+
+    PutNotificationChatChannelsDto:
+      type: object
+      additionalProperties: false
+      description: Partial chat cells. Omitted keys default to `off` on save.
+      properties:
+        status:
+          $ref: "#/components/schemas/NotificationChatDeliveryMode"
+        comment:
+          $ref: "#/components/schemas/NotificationChatDeliveryMode"
+        activity:
+          $ref: "#/components/schemas/NotificationChatDeliveryMode"
+        system:
+          $ref: "#/components/schemas/NotificationChatDeliveryMode"
+
+    PutNotificationChannelsDto:
+      type: object
+      additionalProperties: false
+      description: >
+        Replaces stored channel cells when present on `PUT /me/preferences`.
+        Omitted `email`, `slack`, or `teams` objects are filled with defaults.
+      properties:
+        email:
+          $ref: "#/components/schemas/PutNotificationEmailChannelsDto"
+        slack:
+          $ref: "#/components/schemas/PutNotificationChatChannelsDto"
+        teams:
+          $ref: "#/components/schemas/PutNotificationChatChannelsDto"
+
     PreferencesDto:
       type: object
       additionalProperties: false
+      required:
+        [
+          theme,
+          sidebarCollapsed,
+          timezone,
+          dataRefreshInterval,
+          notifications,
+          buddyEnabled,
+          notificationChannels,
+        ]
+      properties:
+        theme:
+          $ref: "#/components/schemas/ThemePreference"
+        sidebarCollapsed:
+          type: boolean
+        timezone:
+          type: string
+          description: IANA timezone name
+        dataRefreshInterval:
+          $ref: "#/components/schemas/DataRefreshInterval"
+        notifications:
+          $ref: "#/components/schemas/NotificationPreferencesDto"
+        buddyEnabled:
+          type: boolean
+          default: false
+          description: >
+            When true, show the ThinkAI Buddy mascot. Default and missing stored
+            values are false (opt-in only).
+        notificationChannels:
+          $ref: "#/components/schemas/NotificationChannelsDto"
+
+    PutPreferencesBodyDto:
+      type: object
+      additionalProperties: false
+      description: >
+        Body for `PUT /me/preferences`. `notificationChannels` may be omitted to keep
+        stored cells.
       required:
         [theme, sidebarCollapsed, timezone, dataRefreshInterval, notifications, buddyEnabled]
       properties:
@@ -18731,6 +18938,20 @@ components:
           description: >
             When true, show the ThinkAI Buddy mascot. Default and missing stored
             values are false (opt-in only).
+        notificationChannels:
+          $ref: "#/components/schemas/PutNotificationChannelsDto"
+
+    NotificationChannelRequiredErrorDto:
+      type: object
+      additionalProperties: false
+      required: [error, code]
+      properties:
+        error:
+          type: string
+          description: Status email cannot be turned off.
+        code:
+          type: string
+          enum: [notification_channel_required]
 
     ValidationIssueDto:
       type: object

package/package.json

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

package/src/generated/openapi.ts

@@ -3708,7 +3708,10 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /** Paginated notifications */
+        /**
+         * Paginated notifications
+         * @description Inbox for the current user in this workspace. Applies the same notification-type preference filter and routine-title exclusion as the unread badge. `view` defaults to `all` so a client that omits it still receives success rows. Severity is the stored column and is not recomputed per request.
+         */
         get: operations["listNotifications"];
         put?: never;
         post?: never;
@@ -3725,7 +3728,10 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /** Unread notification count */
+        /**
+         * Unread notification count
+         * @description Unread rows for the current user in this workspace after the notification-type preference filter and the routine-title exclusion. `count` is not capped. `hasUnreadCritical` is true when at least one of those rows has severity `destructive`.
+         */
         get: operations["getNotificationUnreadCount"];
         put?: never;
         post?: never;
@@ -3814,9 +3820,15 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /** Get preferences for current user */
+        /**
+         * Get preferences for current user
+         * @description Returns saved preferences, including `notificationChannels`. An empty or missing profile returns defaults (`email.status` is `digest`; every other channel cell is `off`).
+         */
         get: operations["getMyPreferences"];
-        /** Upsert preferences */
+        /**
+         * Upsert preferences
+         * @description Replaces the saved preferences object. Omitting `notificationChannels` keeps the stored cells, or the defaults when none are stored. A body that includes `notificationChannels` replaces those cells; any missing key inside it uses the default (`email.status` = `digest`, every other cell = `off`). Setting `email.status` to `off` returns 400 `notification_channel_required`. In-app `notifications` booleans are independent of these cells.
+         */
         put: operations["putMyPreferences"];
         post?: never;
         delete?: never;
@@ -3852,7 +3864,7 @@ export interface paths {
         };
         /**
          * App chrome bootstrap payload
-         * @description Returns the authenticated user's profile, workspace list, and preferences in one response. When `workspaceId` is provided and resolves to a workspace the caller belongs to, also returns platform banner, unread notification count, journey progress, and connectors snapshot. Invalid, unknown, or non-member `workspaceId` values do not produce 403/404 — the response is still 200 with only `me`, `workspaces`, and `preferences` (workspace-scoped fields omitted).
+         * @description Returns the authenticated user's profile, workspace list, and preferences (including `notificationChannels`) in one response. When `workspaceId` is provided and resolves to a workspace the caller belongs to, also returns platform banner, unread notification count (`count` and `hasUnreadCritical`), journey progress, and connectors snapshot. Invalid, unknown, or non-member `workspaceId` values do not produce 403/404 — the response is still 200 with only `me`, `workspaces`, and `preferences` (workspace-scoped fields omitted).
          */
         get: operations["getAppShell"];
         put?: never;
@@ -7880,8 +7892,11 @@ export interface components {
             /** Format: date-time */
             createdAt: string;
             route?: string;
-            /** @enum {string} */
-            severity?: "success" | "warning" | "destructive" | "muted" | "neutral";
+            /**
+             * @description Stored on the notification row at fan-out. `destructive` is the only critical severity.
+             * @enum {string}
+             */
+            severity: "success" | "warning" | "destructive" | "muted" | "neutral";
             triggeredBy?: string | null;
         };
         NotificationListDto: {
@@ -7889,7 +7904,10 @@ export interface components {
             total: number;
         };
         NotificationUnreadCountDto: {
+            /** @description Unread rows after the type-preference filter and routine-title exclusion. Not capped. */
             count: number;
+            /** @description True when at least one of those unread rows has severity `destructive`. */
+            hasUnreadCritical: boolean;
         };
         EffectiveTaskRowDto: {
             id: string;
@@ -7967,6 +7985,59 @@ export interface components {
             /** @description System / platform announcements. */
             system: boolean;
         };
+        /**
+         * @description Status email delivery. `digest` (default) is the weekly mail. `immediate` sends as events arrive. `off` is not allowed.
+         * @enum {string}
+         */
+        NotificationEmailStatusMode: "immediate" | "digest";
+        /**
+         * @description Email delivery for comment, activity, or system. Default `off`. `immediate` sends as events arrive. `digest` is the weekly mail.
+         * @enum {string}
+         */
+        NotificationEmailDeliveryMode: "off" | "immediate" | "digest";
+        /**
+         * @description Slack or Teams delivery for one category. Default `off` until that member changes the cell. `dm` is a direct message. `channel` posts to the workspace channel an admin saved. Connecting chat does not turn cells on.
+         * @enum {string}
+         */
+        NotificationChatDeliveryMode: "off" | "dm" | "channel";
+        NotificationEmailChannelsDto: {
+            status: components["schemas"]["NotificationEmailStatusMode"];
+            comment: components["schemas"]["NotificationEmailDeliveryMode"];
+            activity: components["schemas"]["NotificationEmailDeliveryMode"];
+            system: components["schemas"]["NotificationEmailDeliveryMode"];
+        };
+        NotificationChatChannelsDto: {
+            status: components["schemas"]["NotificationChatDeliveryMode"];
+            comment: components["schemas"]["NotificationChatDeliveryMode"];
+            activity: components["schemas"]["NotificationChatDeliveryMode"];
+            system: components["schemas"]["NotificationChatDeliveryMode"];
+        };
+        /** @description Delivery cells beside the in-app Message Center switches. Defaults: `email.status` is `digest`; every other cell is `off`. Inbox rows whose type is `integration` use the `status` cell. */
+        NotificationChannelsDto: {
+            email: components["schemas"]["NotificationEmailChannelsDto"];
+            slack: components["schemas"]["NotificationChatChannelsDto"];
+            teams: components["schemas"]["NotificationChatChannelsDto"];
+        };
+        /** @description Partial email cells. Omitted keys are filled with defaults on save (`status` = `digest`, other keys = `off`). */
+        PutNotificationEmailChannelsDto: {
+            status?: components["schemas"]["NotificationEmailStatusMode"];
+            comment?: components["schemas"]["NotificationEmailDeliveryMode"];
+            activity?: components["schemas"]["NotificationEmailDeliveryMode"];
+            system?: components["schemas"]["NotificationEmailDeliveryMode"];
+        };
+        /** @description Partial chat cells. Omitted keys default to `off` on save. */
+        PutNotificationChatChannelsDto: {
+            status?: components["schemas"]["NotificationChatDeliveryMode"];
+            comment?: components["schemas"]["NotificationChatDeliveryMode"];
+            activity?: components["schemas"]["NotificationChatDeliveryMode"];
+            system?: components["schemas"]["NotificationChatDeliveryMode"];
+        };
+        /** @description Replaces stored channel cells when present on `PUT /me/preferences`. Omitted `email`, `slack`, or `teams` objects are filled with defaults. */
+        PutNotificationChannelsDto: {
+            email?: components["schemas"]["PutNotificationEmailChannelsDto"];
+            slack?: components["schemas"]["PutNotificationChatChannelsDto"];
+            teams?: components["schemas"]["PutNotificationChatChannelsDto"];
+        };
         PreferencesDto: {
             theme: components["schemas"]["ThemePreference"];
             sidebarCollapsed: boolean;
@@ -7979,6 +8050,28 @@ export interface components {
              * @default false
              */
             buddyEnabled: boolean;
+            notificationChannels: components["schemas"]["NotificationChannelsDto"];
+        };
+        /** @description Body for `PUT /me/preferences`. `notificationChannels` may be omitted to keep stored cells. */
+        PutPreferencesBodyDto: {
+            theme: components["schemas"]["ThemePreference"];
+            sidebarCollapsed: boolean;
+            /** @description IANA timezone name */
+            timezone: string;
+            dataRefreshInterval: components["schemas"]["DataRefreshInterval"];
+            notifications: components["schemas"]["NotificationPreferencesDto"];
+            /**
+             * @description When true, show the ThinkAI Buddy mascot. Default and missing stored values are false (opt-in only).
+             * @default false
+             */
+            buddyEnabled: boolean;
+            notificationChannels?: components["schemas"]["PutNotificationChannelsDto"];
+        };
+        NotificationChannelRequiredErrorDto: {
+            /** @description Status email cannot be turned off. */
+            error: string;
+            /** @enum {string} */
+            code: "notification_channel_required";
         };
         ValidationIssueDto: {
             path: (string | number)[];
@@ -10708,7 +10801,18 @@ export type JourneyProgressUpdateDto = components['schemas']['JourneyProgressUpd
 export type ThemePreference = components['schemas']['ThemePreference'];
 export type DataRefreshInterval = components['schemas']['DataRefreshInterval'];
 export type NotificationPreferencesDto = components['schemas']['NotificationPreferencesDto'];
+export type NotificationEmailStatusMode = components['schemas']['NotificationEmailStatusMode'];
+export type NotificationEmailDeliveryMode = components['schemas']['NotificationEmailDeliveryMode'];
+export type NotificationChatDeliveryMode = components['schemas']['NotificationChatDeliveryMode'];
+export type NotificationEmailChannelsDto = components['schemas']['NotificationEmailChannelsDto'];
+export type NotificationChatChannelsDto = components['schemas']['NotificationChatChannelsDto'];
+export type NotificationChannelsDto = components['schemas']['NotificationChannelsDto'];
+export type PutNotificationEmailChannelsDto = components['schemas']['PutNotificationEmailChannelsDto'];
+export type PutNotificationChatChannelsDto = components['schemas']['PutNotificationChatChannelsDto'];
+export type PutNotificationChannelsDto = components['schemas']['PutNotificationChannelsDto'];
 export type PreferencesDto = components['schemas']['PreferencesDto'];
+export type PutPreferencesBodyDto = components['schemas']['PutPreferencesBodyDto'];
+export type NotificationChannelRequiredErrorDto = components['schemas']['NotificationChannelRequiredErrorDto'];
 export type ValidationIssueDto = components['schemas']['ValidationIssueDto'];
 export type PreferencesValidationErrorDto = components['schemas']['PreferencesValidationErrorDto'];
 export type ConsentCategoriesDto = components['schemas']['ConsentCategoriesDto'];
@@ -20580,6 +20684,10 @@ export interface operations {
             query?: {
                 limit?: number;
                 offset?: number;
+                /** @description `all` returns every severity. `needs_action` returns only `warning` and `destructive`. Omitted is `all`. */
+                view?: "all" | "needs_action";
+                /** @description Omit to include read and unread rows. `true` is unread only. `false` is read only. */
+                unread?: boolean;
             };
             header?: never;
             path: {
@@ -20598,6 +20706,15 @@ export interface operations {
                     "application/json": components["schemas"]["NotificationListDto"];
                 };
             };
+            /** @description Invalid `view` or `unread` */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorMessageDto"];
+                };
+            };
             401: components["responses"]["Unauthorized"];
         };
     };
@@ -20812,7 +20929,7 @@ export interface operations {
         };
         requestBody: {
             content: {
-                "application/json": components["schemas"]["PreferencesDto"];
+                "application/json": components["schemas"]["PutPreferencesBodyDto"];
             };
         };
         responses: {
@@ -20825,13 +20942,13 @@ export interface operations {
                     "application/json": components["schemas"]["PreferencesDto"];
                 };
             };
-            /** @description Validation failed */
+            /** @description Validation failed, or Status email was set to off (`code` `notification_channel_required`). */
             400: {
                 headers: {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": components["schemas"]["PreferencesValidationErrorDto"];
+                    "application/json": components["schemas"]["PreferencesValidationErrorDto"] | components["schemas"]["NotificationChannelRequiredErrorDto"];
                 };
             };
             401: components["responses"]["Unauthorized"];