@thinkai/tai-api-contract 2.148.0 → 2.150.0

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.148.0
+  version: 2.150.0
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -9200,6 +9200,295 @@ paths:
         "409":
           description: Corpus not ready
 
+  /notifications/email/unsubscribe:
+    get:
+      tags: [Notifications]
+      summary: Confirm a Message Center email unsubscribe (public)
+      description: >
+        **Unauthenticated.** Mail scanners prefetch GET, so this page does not change
+        preferences. Status email cannot be turned off; the page says so. Other categories
+        show a button that POSTs the same token. An unknown or expired token is `400` HTML.
+      operationId: getNotificationEmailUnsubscribe
+      security: []
+      parameters:
+        - name: token
+          in: query
+          required: true
+          description: Opaque unsubscribe token from the email. Only its SHA-256 hash is stored.
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Confirm page. Preferences are unchanged.
+          content:
+            text/html:
+              schema:
+                type: string
+        "400":
+          description: Unknown or expired token
+          content:
+            text/html:
+              schema:
+                type: string
+    post:
+      tags: [Notifications]
+      summary: Apply a Message Center email unsubscribe (public)
+      description: >
+        **Unauthenticated.** Sets that category's email cell to `off` when the category
+        allows off. A status token leaves status email unchanged. Redirects `303` to
+        `{spa}/settings?tab=preferences`. An unknown or expired token is `400` HTML and
+        does not change preferences.
+      operationId: postNotificationEmailUnsubscribe
+      security: []
+      parameters:
+        - name: token
+          in: query
+          required: true
+          description: Opaque unsubscribe token from the email. Only its SHA-256 hash is stored.
+          schema:
+            type: string
+      responses:
+        "303":
+          description: Preference updated, or left unchanged for status email.
+          headers:
+            Location:
+              description: "`{spa}/settings?tab=preferences`"
+              schema:
+                type: string
+        "400":
+          description: Unknown or expired token
+          content:
+            text/html:
+              schema:
+                type: string
+        "200":
+          description: Preference updated when no SPA origin is configured.
+          content:
+            text/html:
+              schema:
+                type: string
+
+  /workspaces/{workspaceId}/integrations/slack/install-url:
+    get:
+      tags: [Integrations]
+      summary: Slack install URL for Message Center
+      operationId: getSlackInstallUrl
+      description: >
+        Workspace admin only. Returns the Slack OAuth authorize URL. State is stored
+        server-side and names this workspace and the signed-in admin. Editor or viewer
+        is `403` with `code` `workspace_admin_required`. Missing Slack app settings are
+        `503` with `code` `slack_not_configured`.
+      security:
+        - bearerAuth: []
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Slack authorize URL
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SlackInstallUrlDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Caller is not a workspace admin
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Forbidden
+                code: workspace_admin_required
+        "404":
+          description: Workspace does not exist or malformed workspaceId
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "503":
+          description: Slack app client id, secret, API origin, or SPA origin is unset
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Slack is not configured
+                code: slack_not_configured
+
+  /integrations/slack/callback:
+    get:
+      tags: [Integrations]
+      summary: Slack OAuth callback
+      operationId: getSlackOauthCallback
+      description: >
+        Browser return from Slack. The provider redirect does not include the API
+        bearer token. `state` was issued by `getSlackInstallUrl` to a signed-in admin
+        and is single-use. The bot token is stored encrypted only when that user is
+        still a workspace admin. Success redirects to
+        `{spa}/settings?tab=preferences&chat=slack`. Failures redirect to the same
+        page with `slack=error`. The token is never in the redirect.
+      parameters:
+        - name: code
+          in: query
+          schema:
+            type: string
+        - name: state
+          in: query
+          required: true
+          schema:
+            type: string
+        - name: error
+          in: query
+          schema:
+            type: string
+      responses:
+        "302":
+          description: Redirect to Settings → Preferences
+          headers:
+            Location:
+              schema:
+                type: string
+        "503":
+          description: Slack app settings are unset and no SPA origin is available
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/integrations/slack:
+    get:
+      tags: [Integrations]
+      summary: Slack connection status
+      operationId: getSlackIntegration
+      description: >
+        Any workspace member. `{ connected, channelName }`. `channelName` is null
+        until an admin saves a channel. The bot token is never returned.
+      security:
+        - bearerAuth: []
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Slack connection status
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SlackIntegrationStatusDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist or malformed workspaceId
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+    delete:
+      tags: [Integrations]
+      summary: Disconnect Slack
+      operationId: deleteSlackIntegration
+      description: >
+        Workspace admin only. Removes the bot token and saved channel. Later
+        Message Center delivery does not post to Slack.
+      security:
+        - bearerAuth: []
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "204":
+          description: Slack disconnected
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Caller is not a workspace admin
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Forbidden
+                code: workspace_admin_required
+        "404":
+          description: Workspace does not exist or malformed workspaceId
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/integrations/slack/channel:
+    put:
+      tags: [Integrations]
+      summary: Save the Slack channel for Message Center
+      operationId: putSlackChannel
+      description: >
+        Workspace admin only. Body `{ channelId }`. Slack must already be connected.
+        The response is the same status object as `getSlackIntegration`, with the
+        channel name Slack returned. Unknown or malformed `channelId` is `400`
+        `invalid_slack_channel`. Not connected is `409` `slack_not_connected`.
+      security:
+        - bearerAuth: []
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/SlackChannelBodyDto"
+      responses:
+        "200":
+          description: Channel saved
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SlackIntegrationStatusDto"
+        "400":
+          description: channelId is missing, malformed, or unknown to Slack
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Slack channel was not found
+                code: invalid_slack_channel
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Caller is not a workspace admin
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Forbidden
+                code: workspace_admin_required
+        "404":
+          description: Workspace does not exist or malformed workspaceId
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "409":
+          description: Slack is not connected
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Slack is not connected
+                code: slack_not_connected
+        "502":
+          description: Slack rejected the lookup
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Slack did not accept the channel
+                code: slack_request_failed
+
   /workspaces/{workspaceId}/notifications:
     get:
       tags: [Notifications]
@@ -9400,6 +9689,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":
@@ -9413,13 +9705,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
@@ -9428,11 +9727,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"
 
@@ -9487,7 +9790,8 @@ 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 (`count` and `hasUnreadCritical`), journey progress, and connectors
         snapshot. Invalid, unknown, or non-member `workspaceId` values do not produce 403/404 —
@@ -18753,9 +19057,187 @@ 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"
+
+    SlackInstallUrlDto:
+      type: object
+      additionalProperties: false
+      required: [url]
+      properties:
+        url:
+          type: string
+          description: Slack OAuth authorize URL. The bot token is not included.
+
+    SlackIntegrationStatusDto:
+      type: object
+      additionalProperties: false
+      required: [connected, channelName]
+      properties:
+        connected:
+          type: boolean
+        channelName:
+          type: string
+          nullable: true
+          description: Saved channel name. Null until an admin saves a channel, and when disconnected.
+
+    SlackChannelBodyDto:
+      type: object
+      additionalProperties: false
+      required: [channelId]
+      properties:
+        channelId:
+          type: string
+          minLength: 1
+          maxLength: 32
+
+    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:
@@ -18776,6 +19258,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.148.0",
+  "version": "2.150.0",
   "private": false,
   "type": "module",
   "main": "dist/index.js",