gitbook/packages/embed/src/client/createGitBook.ts

import { type GitBookFrameClient, createGitBookFrame } from './createGitBookFrame';

export type CreateGitBookOptions = {
    /**
     * URL of the GitBook site to embed.
     */
    siteURL: string;
};

export type GetFrameURLOptions = {
    /**
     * Override the color scheme used by the embedded docs.
     * When omitted, the standalone widget follows the page it is embedded in, and only falls back
     * to the visitor's OS preference when that page supports both schemes. Building the iframe
     * yourself, the embed follows the visitor's OS preference unless you pass this.
     */
    colorScheme?: 'light' | 'dark';

    /**
     * Authentication to use for the frame.
     */
    visitor?: {
        /**
         * Signed JWT token for Adaptive Content or Visitor Authentication to use.
         */
        token?: string;

        /**
         * Unsigned claims to pass to the frame.
         * You can use these claims in dynamic expressions using `visitor.claims.unsigned.<claim-name>`.
         */
        unsignedClaims?: Record<string, unknown>;
    };
};

export type GitBookClient = {
    /**
     * Get the URL for a GitBook frame.
     */
    getFrameURL: (options: GetFrameURLOptions) => string;
    /**
     * Create a new GitBook frame.
     */
    createFrame: (iframe: HTMLIFrameElement) => GitBookFrameClient;
};

export function createGitBook(options: CreateGitBookOptions) {
    const client: GitBookClient = {
        getFrameURL: (frameOptions) => {
            const url = new URL(options.siteURL);
            url.pathname = `${url.pathname.endsWith('/') ? url.pathname : `${url.pathname}/`}~gitbook/embed`;

            if (frameOptions.colorScheme) {
                url.searchParams.set('theme', frameOptions.colorScheme);
            }

            if (frameOptions.visitor?.token) {
                url.searchParams.set('jwt_token', frameOptions.visitor.token);
            }

            if (frameOptions.visitor?.unsignedClaims) {
                Object.entries(frameOptions.visitor.unsignedClaims).forEach(([key, value]) => {
                    url.searchParams.set(`visitor.${key}`, String(value));
                });
            }

            return url.toString();
        },
        createFrame: (iframe) => createGitBookFrame(iframe),
    };

    return client;
}