Improve slack notifications (#965)

valentin0h · web-flow · commit 42efb2abeea2 · 2025-09-01T11:37:26.000+03:00
* Improve slack notifications

* types

* types

* restore page links

* refactor: rename T-prefixed types to Slack-prefixed for better naming convention

As suggested in PR review, using 'Slack' prefix instead of 'T' for type names
provides better clarity and follows TypeScript naming conventions
diff --git a/.changeset/empty-eggs-matter.md b/.changeset/empty-eggs-matter.md
@@ -0,0 +1,5 @@
+---
+'@gitbook/integration-slack': minor
+---
+
+Improved slack notifications
diff --git a/bun.lock b/bun.lock
@@ -16,7 +16,7 @@
     },
     "integrations/ahrefs": {
       "name": "@gitbook/integration-ahrefs",
-      "version": "0.1.0",
+      "version": "0.1.1",
       "dependencies": {
         "@gitbook/api": "*",
         "@gitbook/runtime": "*",
@@ -383,7 +383,7 @@
     },
     "integrations/mermaid": {
       "name": "@gitbook/integration-mermaid",
-      "version": "0.4.0",
+      "version": "0.4.2",
       "dependencies": {
         "@gitbook/api": "*",
         "@gitbook/runtime": "*",
@@ -433,7 +433,7 @@
     },
     "integrations/plausible": {
       "name": "@gitbook/integration-plausible",
-      "version": "0.7.0",
+      "version": "0.9.0",
       "dependencies": {
         "@gitbook/api": "*",
         "@gitbook/runtime": "*",
@@ -507,7 +507,7 @@
     },
     "integrations/segment": {
       "name": "@gitbook/integration-segment",
-      "version": "2.1.3",
+      "version": "2.3.0",
       "dependencies": {
         "@gitbook/api": "*",
         "@gitbook/runtime": "*",
@@ -652,7 +652,7 @@
     },
     "packages/api": {
       "name": "@gitbook/api",
-      "version": "0.135.0",
+      "version": "0.137.0",
       "dependencies": {
         "event-iterator": "^2.0.0",
         "eventsource-parser": "^3.0.0",
diff --git a/integrations/slack/src/index.ts b/integrations/slack/src/index.ts
@@ -4,7 +4,7 @@ import { createIntegration, EventCallback } from '@gitbook/runtime';
 import { SlackRuntimeContext } from './configuration';
 import { handleFetchEvent } from './router';
 import { slackAPI } from './slack';
-import { Spacer } from './ui';
+import { SlackBlock, SlackButtonElement } from './types';
 
 /*
  * Handle content being updated: send a notification on Slack.
@@ -41,29 +41,6 @@ const handleSpaceContentUpdated: EventCallback<
         return;
     }
 
-    /*
-     * Build a notification that looks something like this:
-     *
-     *    Content of *Space* has been updated.
-     *
-     *    [Changes were merged from change request: #123 - My Change Request]
-     *
-     *    *New pages:*
-     *    • Page 7
-     *    • Page 8
-     *    • Page 9
-     *
-     *    *Modified pages:*
-     *    • Page 1
-     *    • Page 2
-     *
-     *    *New files:*
-     *    • File 1
-     *    • File 2
-     *
-     *    And another X changes not listed here.
-     */
-
     const createdPages: ChangedRevisionPage[] = [];
     const editedPages: ChangedRevisionPage[] = [];
     const deletedPages: ChangedRevisionPage[] = [];
@@ -100,75 +77,173 @@ const handleSpaceContentUpdated: EventCallback<
         }
     });
 
-    let notificationText = `Content of *<${space.urls.app}|${
-        space.title || 'Space'
-    }>* has been updated.\n\n`;
+    const MAX_ITEMS_TO_SHOW = 5;
 
-    if (semanticChanges.mergedFrom) {
-        const changeRequest = semanticChanges.mergedFrom;
-        notificationText += `_Changes were merged from change request: <${changeRequest.urls.app}|#${changeRequest.number} - ${changeRequest.subject}>_\n\n`;
-    }
+    const createChangeSection = (
+        title: string,
+        items: string[] | ChangedRevisionPage[],
+        emoji: string,
+    ): SlackBlock[] => {
+        if (items.length === 0) return [];
 
-    const renderList = (list: string[]) => {
-        return list.map((item) => `• ${item}\n`).join('');
-    };
+        const displayItems = items.slice(0, MAX_ITEMS_TO_SHOW);
+        const remainingCount = items.length - displayItems.length;
 
-    const renderPageList = (list: ChangedRevisionPage[]) => {
-        return list.map((item) => `• <${space.urls.app}${item.path}|${item.title}>\n`).join('');
-    };
+        let text = `${emoji} *${title}*\n`;
+        displayItems.forEach((item) => {
+            if (typeof item === 'string') {
+                text += `• ${item}\n`;
+            } else {
+                // Page object with URL
+                const pageUrl = `${space.urls.published || space.urls.app}${item.path || ''}`;
+                text += `• <${pageUrl}|${item.title}>\n`;
+            }
+        });
 
-    if (
-        createdPages.length > 0 ||
-        editedPages.length > 0 ||
-        deletedPages.length > 0 ||
-        movedPages.length > 0 ||
-        createdFiles.length > 0 ||
-        editedFiles.length > 0 ||
-        deletedFiles.length > 0
-    ) {
-        if (createdPages.length > 0) {
-            notificationText += `\n*New pages:*\n${renderPageList(createdPages)}\n\n`;
-        }
-        if (editedPages.length > 0) {
-            notificationText += `\n*Modified pages:*\n${renderPageList(editedPages)}\n\n`;
-        }
-        if (deletedPages.length > 0) {
-            notificationText += `\n*Deleted pages:*\n${renderPageList(deletedPages)}\n\n`;
-        }
-        if (movedPages.length > 0) {
-            notificationText += `\n*Moved pages:*\n${renderPageList(movedPages)}\n\n`;
-        }
-        if (createdFiles.length > 0) {
-            notificationText += `\n*New files:*\n${renderList(createdFiles)}\n\n`;
-        }
-        if (editedFiles.length > 0) {
-            notificationText += `\n*Modified files:*\n${renderList(editedFiles)}\n\n`;
-        }
-        if (deletedFiles.length > 0) {
-            notificationText += `\n*Deleted files:*\n${renderList(deletedFiles)}\n\n`;
+        if (remainingCount > 0) {
+            text += `_and ${remainingCount} more..._`;
         }
 
-        if (semanticChanges.more && semanticChanges.more > 0) {
-            notificationText += `\n\nAnd another ${semanticChanges.more} changes not listed here.\n`;
+        return [
+            {
+                type: 'section',
+                text: {
+                    type: 'mrkdwn',
+                    text: text.trim(),
+                },
+            },
+        ];
+    };
+
+    const getEmojiFromUnicode = (unicodeHex: string) => {
+        if (!unicodeHex) return '✨';
+        try {
+            // Convert hex string to actual emoji
+            const codePoint = parseInt(unicodeHex, 16);
+            return String.fromCodePoint(codePoint);
+        } catch {
+            return '✨';
         }
+    };
+
+    const spaceEmoji = space.emoji ? getEmojiFromUnicode(space.emoji) : '✨';
+
+    const blocks: SlackBlock[] = [
+        {
+            type: 'header',
+            text: {
+                type: 'plain_text',
+                text: `${spaceEmoji} ${space.title || 'Space'} Updated`,
+                emoji: true,
+            },
+        },
+    ];
+
+    let changeRequest;
+    if (semanticChanges.mergedFrom) {
+        changeRequest = semanticChanges.mergedFrom;
+        blocks.push({
+            type: 'context',
+            elements: [
+                {
+                    type: 'mrkdwn',
+                    text: `🔀 Changes were merged from change request: <${changeRequest.urls.app}|#${changeRequest.number}${changeRequest.subject ? ` - ${changeRequest.subject}` : ''}>`,
+                },
+            ],
+        });
     }
 
+    blocks.push({
+        type: 'section',
+        text: {
+            type: 'mrkdwn',
+            text: '*Summary of Changes:*',
+        },
+    });
+
+    blocks.push(...createChangeSection('New pages', createdPages, '🆕'));
+    blocks.push(...createChangeSection('Modified pages', editedPages, '📝'));
+    blocks.push(...createChangeSection('Deleted pages', deletedPages, '🗑️'));
+    blocks.push(...createChangeSection('Moved pages', movedPages, '📁'));
+    blocks.push(...createChangeSection('New files', createdFiles, '📄'));
+    blocks.push(...createChangeSection('Modified files', editedFiles, '📝'));
+    blocks.push(...createChangeSection('Deleted files', deletedFiles, '🗂️'));
+
+    if (semanticChanges.more && semanticChanges.more > 0) {
+        blocks.push({
+            type: 'context',
+            elements: [
+                {
+                    type: 'mrkdwn',
+                    text: `➕ _And ${semanticChanges.more} additional changes not listed here_`,
+                },
+            ],
+        });
+    }
+
+    const actionButtons: SlackButtonElement[] = [
+        {
+            type: 'button',
+            text: {
+                type: 'plain_text',
+                text: '🏠 View Main Space',
+                emoji: true,
+            },
+            url: space.urls.app,
+            action_id: 'view_main_space',
+            style: 'primary',
+        },
+    ];
+
+    if (space.urls.published) {
+        actionButtons.push({
+            type: 'button',
+            text: {
+                type: 'plain_text',
+                text: '🌐 View Docs Site',
+                emoji: true,
+            },
+            url: space.urls.published,
+            action_id: 'view_docs_site',
+        });
+    }
+
+    blocks.push({ type: 'divider' });
+
+    // Add a nice footer section
+    const totalChanges =
+        createdPages.length +
+        editedPages.length +
+        deletedPages.length +
+        movedPages.length +
+        createdFiles.length +
+        editedFiles.length +
+        deletedFiles.length +
+        (semanticChanges.more || 0);
+
+    blocks.push({
+        type: 'context',
+        elements: [
+            {
+                type: 'mrkdwn',
+                text: `📊 *${totalChanges} total changes* • Updated just now`,
+            },
+        ],
+    });
+
+    blocks.push({
+        type: 'actions',
+        elements: actionButtons,
+    });
+
     await slackAPI(context, {
         method: 'POST',
         path: 'chat.postMessage',
         payload: {
             channel,
-            blocks: [
-                Spacer,
-                {
-                    type: 'section',
-                    text: {
-                        type: 'mrkdwn',
-                        text: notificationText,
-                    },
-                },
-                Spacer,
-            ],
+            blocks,
+            unfurl_links: false,
+            unfurl_media: false,
         },
     });
 };
diff --git a/integrations/slack/src/types.ts b/integrations/slack/src/types.ts
@@ -0,0 +1,23 @@
+// Slack Block Kit Types
+export type SlackTextType = 'plain_text' | 'mrkdwn';
+
+export type SlackTextField = {
+    type: SlackTextType;
+    text: string;
+    emoji?: boolean;
+};
+
+export type SlackButtonElement = {
+    type: 'button';
+    text: SlackTextField;
+    url?: string;
+    action_id: string;
+    style?: 'primary' | 'danger';
+};
+
+export type SlackBlock =
+    | { type: 'section'; text?: SlackTextField; fields?: SlackTextField[]; accessory?: unknown }
+    | { type: 'header'; text: SlackTextField }
+    | { type: 'context'; elements: SlackTextField[] }
+    | { type: 'divider' }
+    | { type: 'actions'; elements: SlackButtonElement[] };

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@gitbook/integration-slack': minor
 +---
++
 +Improved slack notifications