Add support for ingesting conversation in Slack integration

.changeset/tall-bikes-unite.md

@@ -0,0 +1,5 @@
+---
+'@gitbook/integration-slack': minor
+---
+
+Add support for ingesting conversation to Docs Agents in Slack integration

integrations/slack/gitbook-manifest.yaml

@@ -19,6 +19,7 @@ script: ./src/index.ts
 scopes:
     - space:content:read
     - space:metadata:read
+    - conversations:ingest
 summary: |
     # Overview
     With the GitBook Slack integration, your teams have instant access to your documentation, and can get AI-summarized answers about your content.

integrations/slack/src/actions/index.ts

@@ -1 +1,3 @@
 export * from './queryAskAI';
+export * from './ingestConversation';
+export * from './types';

integrations/slack/src/actions/ingestConversation.ts

@@ -0,0 +1,237 @@
+import { ConversationInput, ConversationPart, IntegrationInstallation } from '@gitbook/api';
+import { SlackInstallationConfiguration, SlackRuntimeContext } from '../configuration';
+import {
+    getSlackThread,
+    parseSlackConversationPermalink,
+    slackAPI,
+    SlackConversationThread,
+} from '../slack';
+import { getInstallationApiClient, getIntegrationInstallationForTeam } from '../utils';
+import { IngestSlackConversationActionParams, IntegrationTaskIngestConversation } from './types';
+import { Logger } from '@gitbook/runtime';
+
+const logger = Logger('slack:actions:ingestConversation');
+
+/**
+ * Ingest the slack conversation to GitBook aiming at improving the organization docs.
+ */
+export async function ingestSlackConversation(params: IngestSlackConversationActionParams) {
+    const { responseUrl, channelId, channelName, userId, threadId, context, teamId } = params;
+
+    const installation = await getIntegrationInstallationForTeam(context, teamId);
+    if (!installation) {
+        throw new Error('Installation not found');
+    }
+
+    const accessToken = (installation.configuration as SlackInstallationConfiguration)
+        .oauth_credentials?.access_token;
+
+    const permalink = params.text;
+    const isIngestedFromLink = !!permalink;
+
+    const conversationToIngest: IngestSlackConversationActionParams['conversationToIngest'] =
+        (() => {
+            if (permalink) {
+                try {
+                    return parseSlackConversationPermalink(permalink);
+                } catch (error) {
+                    logger.debug(
+                        `⚠️ We couldn’t understand that link. Please check it and try again.`,
+                        error,
+                    );
+                }
+            }
+
+            return params.conversationToIngest;
+        })();
+
+    if (!conversationToIngest) {
+        await slackAPI(
+            context,
+            {
+                method: 'POST',
+                path: 'chat.postMessage',
+                payload: {
+                    channel: channelId,
+                    text: `⚠️ We couldn’t get the conversation details. Please try again.`,
+                },
+            },
+            {
+                accessToken,
+            },
+        );
+
+        return;
+    }
+
+    await Promise.all([
+        slackAPI(
+            context,
+            {
+                method: 'POST',
+                path: 'chat.postMessage',
+                payload: {
+                    channel: channelId,
+                    ...(isIngestedFromLink
+                        ? {
+                              markdown_text: `🚀 Sharing [this conversation](${permalink}) with Docs Agent to improve your docs...`,
+                          }
+                        : {
+                              text: `🚀 Sharing this conversation with Docs Agent to improve your docs...`,
+                          }),
+                    thread_ts: threadId,
+                    unfurl_links: isIngestedFromLink,
+                },
+            },
+            {
+                accessToken,
+            },
+        ),
+        queueIngestSlackConversationTask({
+            channelId,
+            channelName,
+            teamId,
+            responseUrl,
+            userId,
+            threadId,
+            context,
+            accessToken,
+            installation,
+            conversationToIngest,
+        }),
+    ]);
+}
+
+/**
+ * Queues an integration task to ingest the Slack conversation asynchronously.
+ */
+async function queueIngestSlackConversationTask(
+    params: IngestSlackConversationActionParams & {
+        installation: IntegrationInstallation;
+        accessToken: string | undefined;
+        conversationToIngest: {
+            channelId: string;
+            messageTs: string;
+        };
+    },
+) {
+    const { accessToken, installation, context, conversationToIngest } = params;
+
+    const task: IntegrationTaskIngestConversation = {
+        type: 'ingest:conversation',
+        payload: {
+            channelId: params.channelId,
+            teamId: params.teamId,
+            channelName: params.channelName,
+            responseUrl: params.responseUrl,
+            threadId: params.threadId,
+            userId: params.userId,
+            organizationId: installation.target.organization,
+            installationId: installation.id,
+            accessToken,
+            conversationToIngest,
+        },
+    };
+
+    await context.api.integrations.queueIntegrationTask(context.environment.integration.name, {
+        task,
+    });
+
+    logger.info(`Queue task ${task.type} for installation: ${task.payload.installationId})`);
+}
+
+/**
+ * Handle the integration task to ingest a slack conversation.
+ */
+export async function handleIngestSlackConversationTask(
+    task: IntegrationTaskIngestConversation,
+    context: SlackRuntimeContext,
+) {
+    const {
+        payload: {
+            channelId,
+            userId,
+            responseUrl,
+            threadId,
+            organizationId,
+            installationId,
+            accessToken,
+            conversationToIngest,
+        },
+    } = task;
+
+    const [client, conversation] = await Promise.all([
+        getInstallationApiClient(context, installationId),
+        (async () => {
+            const slackThread = await getSlackThread(context, conversationToIngest, {
+                accessToken,
+            });
+            return parseSlackThreadAsGitBookConversation(slackThread);
+        })(),
+    ]);
+
+    try {
+        await client.orgs.ingestConversation(organizationId, conversation);
+        await slackAPI(
+            context,
+            {
+                method: 'POST',
+                path: 'chat.postMessage',
+                payload: {
+                    channel: channelId,
+                    text: `🤖 Got it! Docs Agent is on it. We'll analyze this and suggest changes if needed.`,
+                    thread_ts: threadId,
+                },
+            },
+            {
+                accessToken,
+            },
+        );
+    } catch {
+        await slackAPI(
+            context,
+            {
+                method: 'POST',
+                path: 'chat.postMessage',
+                payload: {
+                    channel: channelId,
+                    text: `⚠️ Something went wrong while sending this conversation to Docs Agent.`,
+                    thread_ts: threadId,
+                },
+            },
+            {
+                accessToken,
+            },
+        );
+    }
+}
+
+/**
+ * Parse a Slack threaded conversation into a GitBook conversation.
+ */
+function parseSlackThreadAsGitBookConversation(
+    slackThread: SlackConversationThread,
+): ConversationInput {
+    return {
+        id: `${slackThread.channelId}-${slackThread.messageTs}`,
+        metadata: {
+            url: slackThread.link,
+            attributes: {
+                channelId: slackThread.channelId,
+                messageTs: slackThread.messageTs,
+            },
+            createdAt: new Date(slackThread.createdAt).toISOString(),
+        },
+        parts: slackThread.messages
+            .map((message) =>
+                message.text
+                    ? ({
+                          type: 'message',
+                          role: 'user',
+                          body: message.text,
+                      } as ConversationPart)
+                    : null,
+            )
+            .filter((part) => part !== null),
+    };
+}

integrations/slack/src/actions/queryAskAI.ts

@@ -8,11 +8,7 @@ import {
     IntegrationInstallation,
 } from '@gitbook/api';
 
-import {
-    SlackInstallationConfiguration,
-    SlackRuntimeEnvironment,
-    SlackRuntimeContext,
-} from '../configuration';
+import { SlackInstallationConfiguration, SlackRuntimeContext } from '../configuration';
 import { slackAPI } from '../slack';
 import { QueryDisplayBlock, ShareTools, decodeSlackEscapeChars, Spacer, SourcesBlock } from '../ui';
 import {
@@ -22,36 +18,16 @@ import {
     stripMarkdown,
 } from '../utils';
 import { Logger } from '@gitbook/runtime';
-import { IntegrationTaskAskAI } from '../types';
+import { AskAIActionParams, IntegrationTaskAskAI } from './types';
 
-const logger = Logger('slack:queryAskAI');
+const logger = Logger('slack:actions:askAI');
 
 export type RelatedSource = {
     id: string;
     sourceUrl: string;
     page: { path?: string; title: string };
 };
 
-export interface IQueryAskAI {
-    channelId: string;
-    channelName?: string;
-    responseUrl?: string;
-    teamId: string;
-    text: string;
-    context: SlackRuntimeContext;
-
-    /* postEphemeral vs postMessage */
-    messageType: 'ephemeral' | 'permanent';
-
-    /* needed for postEphemeral */
-    userId?: string;
-
-    /* Get AskAI reply in thread */
-    threadId?: string;
-
-    authorization?: string;
-}
-
 // Recursively extracts all pages from a collection of RevisionPages
 function extractAllPages(rootPages: Array<RevisionPage>) {
     const result: Array<RevisionPage> = [];
@@ -154,13 +130,13 @@ async function getRelatedSources(params: {
 /*
  * Queries GitBook AskAI via the GitBook API and posts the answer in the form of Slack UI Blocks back to the original channel/conversation/thread.
  */
-export async function queryAskAI(params: IQueryAskAI) {
+export async function queryAskAI(params: AskAIActionParams) {
     const {
         channelId,
         teamId,
         threadId,
         userId,
-        text,
+        queryText: text,
         messageType,
         context,
         authorization,
@@ -217,7 +193,7 @@ export async function queryAskAI(params: IQueryAskAI) {
  * Queues an integration task to process the AskAI query asynchronously.
  */
 async function queueQueryAskAI(
-    params: IQueryAskAI & {
+    params: AskAIActionParams & {
         query: string;
         installation: IntegrationInstallation;
         accessToken: string | undefined;
@@ -252,7 +228,7 @@ export async function handleAskAITask(task: IntegrationTaskAskAI, context: Slack
             channelName,
             channelId,
             userId,
-            text,
+            queryText: text,
             messageType,
             responseUrl,
             threadId,