Embeddable GitBook API

.changeset/forty-trees-sniff.md

@@ -0,0 +1,5 @@
+---
+"@gitbook/embed": minor
+---
+
+Improve API to control the GitBook embed

.changeset/sixty-pumas-tell.md

@@ -0,0 +1,5 @@
+---
+"gitbook": minor
+---
+
+Support customization of buttons and tools through iframe API

biome.json

@@ -18,6 +18,7 @@
             "**/.vercel/**/*",
             "**/.cache/**/*",
             "**/.wrangler/**/*",
+            "packages/embed/standalone/**/*",
             "packages/openapi-parser/src/fixtures/**/*",
             "packages/emoji-codepoints/index.ts",
             "packages/icons/src/data/*.json",

packages/embed/src/client/createGitBookFrame.ts

@@ -1,8 +1,7 @@
 import { createChannel } from 'bidc';
 import type {
     FrameToParentMessage,
-    GitBookPlaceholderSettings,
-    GitBookToolDefinition,
+    GitBookEmbeddableConfiguration,
     ParentToFrameMessage,
 } from './protocol';
 
@@ -22,11 +21,6 @@ export type GitBookFrameClient = {
      */
     postUserMessage: (message: string) => void;
 
-    /**
-     * Register a custom tool.
-     */
-    registerTool: (tool: GitBookToolDefinition) => void;
-
     /**
      * Clear the chat.
      */
@@ -35,7 +29,7 @@ export type GitBookFrameClient = {
     /**
      * Set the placeholder settings.
      */
-    setPlaceholder: (placeholder: GitBookPlaceholderSettings) => void;
+    configure: (settings: Partial<GitBookEmbeddableConfiguration>) => void;
 
     /**
      * Register an event listener.
@@ -53,6 +47,7 @@ export function createGitBookFrame(iframe: HTMLIFrameElement): GitBookFrameClien
     const channel = createChannel(iframe.contentWindow);
 
     channel.receive((message: FrameToParentMessage) => {
+        console.log('[gitbook:embed] received message', message);
         if (message.type === 'close') {
             const listeners = events.get('close') || [];
             if (listeners) {
@@ -62,11 +57,19 @@ export function createGitBookFrame(iframe: HTMLIFrameElement): GitBookFrameClien
     });
 
     const sendToFrame = (message: ParentToFrameMessage) => {
+        console.log('[gitbook:embed] send message', message);
         channel.send(message);
     };
 
     const events = new Map<string, Array<(...args: any[]) => void>>();
 
+    const configuration: GitBookEmbeddableConfiguration = {
+        buttons: [],
+        welcomeMessage: '',
+        suggestions: [],
+        tools: [],
+    };
+
     return {
         navigateToPage: (pagePath) => {
             sendToFrame({ type: 'navigateToPage', pagePath });
@@ -75,9 +78,11 @@ export function createGitBookFrame(iframe: HTMLIFrameElement): GitBookFrameClien
             sendToFrame({ type: 'navigateToAssistant' });
         },
         postUserMessage: (message) => sendToFrame({ type: 'postUserMessage', message }),
-        registerTool: (tool) => sendToFrame({ type: 'registerTool', tool }),
+        configure: (settings) => {
+            Object.assign(configuration, settings);
+            sendToFrame({ type: 'configure', settings: configuration });
+        },
         clearChat: () => sendToFrame({ type: 'clearChat' }),
-        setPlaceholder: (settings) => sendToFrame({ type: 'setPlaceholder', settings }),
         on: (event, listener) => {
             const listeners = events.get(event) || [];
             listeners.push(listener);

packages/embed/src/client/protocol.ts

@@ -21,18 +21,42 @@ export type GitBookToolDefinition = AIToolDefinition & {
 };
 
 /**
- * Placeholder settings.
+ * Custom button definition to be passed to the embeddable GitBook.
  */
-export type GitBookPlaceholderSettings = {
+export type GitBookEmbeddableButtonDefinition = {
     /**
-     * Welcome message to be displayed in the placeholder.
+     * Icon to be displayed in the button.
      */
-    welcomeMessage: string;
+    icon: IconName;
+
+    /**
+     * Label to be displayed in the button.
+     */
+    label: string;
+
+    /**
+     * Callback when the button is clicked.
+     */
+    onClick: () => void | Promise<void>;
+};
 
+/**
+ * Overall configuration for the layout of the embeddable GitBook.
+ */
+export type GitBookEmbeddableConfiguration = {
     /**
-     * Suggestions to be displayed in the placeholder.
+     * Buttons to be displayed in the header of the embeddable GitBook.
      */
+    buttons: GitBookEmbeddableButtonDefinition[];
+
+    /** Message to be displayed in the welcome page. */
+    welcomeMessage: string;
+
+    /** Suggestions of questions to be displayed in the welcome page. */
     suggestions: string[];
+
+    /** Tools to be provided to the assistant. */
+    tools: GitBookToolDefinition[];
 };
 
 /**
@@ -43,16 +67,12 @@ export type ParentToFrameMessage =
           type: 'postUserMessage';
           message: string;
       }
-    | {
-          type: 'registerTool';
-          tool: GitBookToolDefinition;
-      }
     | {
           type: 'clearChat';
       }
     | {
-          type: 'setPlaceholder';
-          settings: GitBookPlaceholderSettings;
+          type: 'configure';
+          settings: GitBookEmbeddableConfiguration;
       }
     | {
           type: 'navigateToPage';

packages/embed/src/react/GitBookFrame.tsx

@@ -0,0 +1,51 @@
+import React from 'react';
+import type {
+    GetFrameURLOptions,
+    GitBookEmbeddableConfiguration,
+    GitBookFrameClient,
+} from '../client';
+import { useGitBook } from './GitBookProvider';
+
+export type GitBookFrameProps = {
+    className?: string;
+} & GetFrameURLOptions &
+    GitBookEmbeddableConfiguration;
+
+/**
+ * Render a frame with the GitBook Assistant in it.
+ */
+export function GitBookFrame(props: GitBookFrameProps) {
+    const { className, visitor, buttons, welcomeMessage, suggestions, tools } = props;
+
+    const frameRef = React.useRef<HTMLIFrameElement>(null);
+    const gitbook = useGitBook();
+    const [gitbookFrame, setGitbookFrame] = React.useState<GitBookFrameClient | null>(null);
+
+    const frameURL = React.useMemo(() => gitbook.getFrameURL({ visitor }), [gitbook, visitor]);
+
+    React.useEffect(() => {
+        if (frameRef.current) {
+            setGitbookFrame(gitbook.createFrame(frameRef.current));
+        }
+    }, [gitbook]);
+
+    React.useEffect(() => {
+        gitbookFrame?.configure({
+            buttons,
+            welcomeMessage,
+            suggestions,
+            tools,
+        });
+    }, [gitbookFrame, buttons, welcomeMessage, suggestions, tools]);
+
+    return (
+        <iframe
+            title="GitBook"
+            ref={frameRef}
+            src={frameURL}
+            width="100%"
+            height="100%"
+            className={className}
+        />
+    );
+}

packages/embed/src/react/index.ts

@@ -1 +1,2 @@
 export * from './GitBookProvider';
+export * from './GitBookFrame';

packages/embed/src/standalone/index.ts

@@ -4,9 +4,8 @@ import {
     type CreateGitBookOptions,
     type GetFrameURLOptions,
     type GitBookClient,
+    type GitBookEmbeddableConfiguration,
     type GitBookFrameClient,
-    type GitBookPlaceholderSettings,
-    type GitBookToolDefinition,
     createGitBook,
 } from '../client';
 
@@ -29,12 +28,10 @@ type StandaloneCalls =
     | ['toggle']
     // Post a user message
     | ['postUserMessage', string]
-    // Register a tool
-    | ['registerTool', GitBookToolDefinition]
     // Clear the chat
     | ['clearChat']
-    // Configure the placeholder
-    | ['setPlaceholder', GitBookPlaceholderSettings]
+    // Configure the embed
+    | ['configure', Partial<GitBookEmbeddableConfiguration>]
     // Navigate to a page
     | ['navigateToPage', string]
     // Navigate to the assistant
@@ -65,6 +62,12 @@ let widgetIframe: HTMLIFrameElement | undefined;
 let _client: GitBookClient | undefined;
 let _frame: GitBookFrameClient | undefined;
 let frameOptions: GetFrameURLOptions | undefined;
+let frameConfiguration: GitBookEmbeddableConfiguration = {
+    buttons: [],
+    welcomeMessage: '',
+    suggestions: [],
+    tools: [],
+};
 
 function getClient() {
     if (!_client) {
@@ -132,15 +135,30 @@ const GitBook = (...args: StandaloneCalls) => {
         case 'postUserMessage':
             getIframe().frame.postUserMessage(args[1]);
             break;
-        case 'registerTool':
-            getIframe().frame.registerTool(args[1]);
+        case 'configure':
+            frameConfiguration = {
+                ...frameConfiguration,
+                ...args[1],
+            };
+            getIframe().frame.configure({
+                ...frameConfiguration,
+                buttons: [
+                    ...frameConfiguration.buttons,
+
+                    // Always include a close button
+                    {
+                        icon: 'close',
+                        label: 'Close',
+                        onClick: () => {
+                            GitBook('close');
+                        },
+                    },
+                ],
+            });
             break;
         case 'clearChat':
             getIframe().frame.clearChat();
             break;
-        case 'setPlaceholder':
-            getIframe().frame.setPlaceholder(args[1]);
-            break;
         case 'navigateToPage':
             getIframe().frame.navigateToPage(args[1]);
             break;
@@ -156,3 +174,5 @@ const precalls = (window.GitBook as GitBookStandalone | undefined)?.q ?? [];
 // @ts-expect-error - GitBook is not defined in the global scope
 window.GitBook = GitBook;
 precalls.forEach((call) => GitBook(...call));
+
+GitBook('configure', {});

packages/gitbook/src/components/AI/useAIChat.tsx

@@ -346,7 +346,8 @@ export function AIChatProvider(props: {
                     loading: false,
                     error: false,
                 }));
-            } catch {
+            } catch (error) {
+                console.error('Error streaming AI response', error);
                 globalState.setState((state) => ({
                     ...state,
                     loading: false,
@@ -359,6 +360,7 @@ export function AIChatProvider(props: {
             renderMessageOptions?.withLinkPreviews,
             renderMessageOptions?.withToolCalls,
             renderMessageOptions?.asEmbeddable,
+            language,
         ]
     );