@thinkai/tai-api-contract 2.149.0 → 2.151.0

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.149.0
+  version: 2.151.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]
@@ -9960,6 +10249,239 @@ paths:
         "403":
           $ref: "#/components/responses/Forbidden"
 
+  /workspaces/{workspaceId}/integrations/teams/install-url:
+    get:
+      tags: [Integrations, Notifications]
+      summary: Microsoft sign-in URL for Teams notification delivery
+      operationId: getWorkspaceTeamsInstallUrl
+      description: >
+        Workspace **admin** only. Returns the Microsoft authorize URL. State carries the
+        workspace and the signed-in admin. Editor or viewer is `403` `workspace_admin_required`.
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Authorize URL
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TeamsInstallUrlDto"
+              example:
+                url: "https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=example&state=example-state"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Editor or viewer
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Forbidden
+                code: workspace_admin_required
+        "404":
+          description: Workspace not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Not found
+        "503":
+          description: Teams app credentials are not configured
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Teams sign-in is not configured
+                code: teams_not_configured
+
+  /integrations/teams/callback:
+    get:
+      tags: [Integrations, Notifications]
+      summary: Finish Teams Microsoft sign-in
+      operationId: getTeamsIntegrationCallback
+      description: >
+        Public redirect target. The one-time state was minted by a signed-in admin and
+        still requires that user to be a workspace admin. Stores the bot token encrypted
+        and redirects to `{spa}/settings?tab=preferences&chat=teams`.
+      security: []
+      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
+                example: "https://app.example.com/settings?tab=preferences&chat=teams"
+        "503":
+          description: SPA origin is not configured
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/integrations/teams:
+    get:
+      tags: [Integrations, Notifications]
+      summary: Teams connection status
+      operationId: getWorkspaceTeamsConnection
+      description: >
+        Any workspace member. `{ connected, channelName }`. Never returns the bot token.
+        `channelName` is null until an admin saves a channel.
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Connection status
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TeamsConnectionDto"
+              example:
+                connected: true
+                channelName: General
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Not found
+    delete:
+      tags: [Integrations, Notifications]
+      summary: Disconnect Teams
+      operationId: deleteWorkspaceTeamsConnection
+      description: >
+        Workspace **admin** only. Later Message Center posts do not go to Teams.
+        Member chat cells stay unchanged.
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "204":
+          description: Disconnected
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Editor or viewer
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Forbidden
+                code: workspace_admin_required
+        "404":
+          description: Workspace not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Not found
+
+  /workspaces/{workspaceId}/integrations/teams/channel:
+    put:
+      tags: [Integrations, Notifications]
+      summary: Save the Teams channel for notification posts
+      operationId: putWorkspaceTeamsChannel
+      description: >
+        Workspace **admin** only. Body `{ channelId }`. The channel must be visible to the
+        connected Microsoft account. Until a channel is saved, channel-mode delivery is
+        skipped with `chat_channel_unset`.
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/TeamsChannelBodyDto"
+            example:
+              channelId: "19:example@thread.tacv2"
+      responses:
+        "200":
+          description: Channel saved
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TeamsConnectionDto"
+              example:
+                connected: true
+                channelName: General
+        "400":
+          description: Missing channelId, or the channel was not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              examples:
+                invalid:
+                  value:
+                    error: channelId is required
+                    code: invalid_input
+                missing:
+                  value:
+                    error: Teams channel was not found
+                    code: teams_channel_not_found
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Editor or viewer
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Forbidden
+                code: workspace_admin_required
+        "404":
+          description: Workspace not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Not found
+        "409":
+          description: Teams is not connected
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Teams is not connected
+                code: teams_not_connected
+        "502":
+          description: Microsoft Graph rejected the channel lookup
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Teams channel lookup failed
+                code: teams_graph_failed
+
   /workspaces/{workspaceId}/integrations/zelt/authorize-url:
     post:
       tags: [HRIS, Integrations]
@@ -10972,6 +11494,35 @@ components:
             error: zenhr_sync_in_progress
 
   schemas:
+    TeamsInstallUrlDto:
+      type: object
+      required: [url]
+      properties:
+        url:
+          type: string
+          format: uri
+
+    TeamsConnectionDto:
+      type: object
+      required: [connected, channelName]
+      properties:
+        connected:
+          type: boolean
+          description: True after an admin completes Microsoft sign-in.
+        channelName:
+          type: string
+          nullable: true
+          description: Selected channel display name. Null until an admin saves a channel.
+
+    TeamsChannelBodyDto:
+      type: object
+      required: [channelId]
+      properties:
+        channelId:
+          type: string
+          minLength: 1
+          maxLength: 256
+
     ErrorMessageDto:
       type: object
       required: [error]
@@ -18834,6 +19385,37 @@ components:
         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

package/package.json

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