@inkeep/agents-ui 0.14.20 → 0.14.21

package/dist/types/config/ai.d.ts

@@ -0,0 +1,243 @@
+import { AIChatFormSettings } from './settings/form';
+import { GetHelpOption } from './settings/actions';
+import { SearchAndChatFilters } from './filters';
+import { ComponentsConfig } from './components';
+export interface InkeepAIChatSettings {
+    /**
+     * Headers for requests
+     */
+    headers?: Record<string, string>;
+    /**
+     * API key for requests
+     */
+    apiKey?: string;
+    /**
+     * Agent URL for chatstream API.
+     */
+    agentUrl?: string;
+    /**
+     * Context to be passed to the chatstream API.
+     */
+    context?: Record<string, unknown>;
+    /**
+     * The placeholder text to display in the chat input field when empty.
+     * Use this to provide guidance on what kind of questions users can ask.
+     * @example "Ask me anything about our API documentation..."
+     */
+    placeholder?: string;
+    /**
+     * A welcome message shown at the start of a new chat session.
+     * Supports markdown formatting for rich text styling.
+     * Use this to introduce the AI assistant's capabilities and set expectations.
+     * @example "👋 Hi! I'm here to help you with technical questions about our API..."
+     */
+    introMessage?: string;
+    /**
+     * The name of the product/service/topic that the chat assistant specializes in.
+     * This helps contextualize the chat experience for users.
+     * If not provided, defaults to the organization name from base settings.
+     * @example "MongoDB Atlas" or "React Router"
+     */
+    chatSubjectName?: string;
+    /**
+     * The display name for the AI assistant in the chat interface.
+     * Choose a name that reflects the assistant's role and your brand.
+     * @example "Atlas Assistant" or "DevBot"
+     */
+    aiAssistantName?: string;
+    /**
+     * URL to the AI assistant's avatar image.
+     * Should be a square image, recommended size 40x40px.
+     * Supports common image formats (PNG, JPG, SVG).
+     *
+     * You can pass a string or an object to configure for different color modes.
+     *
+     * @example
+     * {
+     *   light: 'https://example.com/avatar-light.png',
+     *   dark: 'https://example.com/avatar-dark.png',
+     * }
+     */
+    aiAssistantAvatar?: string | {
+        light: string;
+        dark: string;
+    };
+    /**
+     * URL to the user's avatar image in the chat interface.
+     * Should be a square image, recommended size 40x40px.
+     * Falls back to a default user icon if not provided.
+     */
+    userAvatar?: string;
+    /**
+     * Controls whether links in chat messages open in new browser tabs.
+     * Enable this to help users maintain their chat context when following links.
+     * @default true
+     */
+    shouldOpenLinksInNewTab?: boolean;
+    /**
+     * Custom heading text for the example questions section.
+     * Use this to better describe your suggested queries.
+     * @example "Common Questions" or "Try asking about..."
+     */
+    exampleQuestionsLabel?: string;
+    /**
+     * A list of pre-written questions users can click to quickly start a conversation.
+     * These should reflect common use cases and help users understand the AI assistant's capabilities.
+     * @example ["How do I reset my password?", "What are the API rate limits?"]
+     */
+    exampleQuestions?: string[];
+    /**
+     * Whether to visually emphasize the first example question.
+     * Use this to draw attention to the most important or common query.
+     */
+    isFirstExampleQuestionHighlighted?: boolean;
+    /**
+     * Enables the ability to share chat conversations via URL.
+     * Useful for allowing users to share helpful conversations with teammates.
+     */
+    isShareButtonVisible?: boolean;
+    /**
+     * The base URL path used when generating shareable chat links.
+     * Should match your application's routing structure.
+     * @example "/shared-chats/" or "/support/conversations/"
+     */
+    shareChatUrlBasePath?: string;
+    /**
+     * Controls the visibility of the copy chat button.
+     * Allows users to copy the entire chat transcript to their clipboard.
+     */
+    isCopyChatButtonVisible?: boolean;
+    /**
+     * Unique identifier for loading a specific conversation.
+     * Use this to restore a previous conversation state.
+     */
+    conversationId?: string;
+    /**
+     * When enabled, prevents users from sending new messages.
+     * Useful for displaying archived or shared chat sessions.
+     * @default false
+     */
+    isViewOnly?: boolean;
+    /**
+     * Whether to make conversations public by default.
+     * @default undefined (private)
+     */
+    conversationVisibility?: 'public' | 'private';
+    /**
+     * Configuration for the chat's disclaimer message.
+     * Use this to display important notices about AI limitations or data usage.
+     */
+    disclaimerSettings?: AIChatDisclaimerSettings;
+    /**
+     * Callback function triggered whenever the user modifies their input message.
+     * @param message The current content of the input field
+     */
+    onInputMessageChange?: (message: string) => void;
+    /**
+     * React ref for accessing the chat component's methods.
+     * Enables programmatic control of chat functions from parent components.
+     */
+    chatFunctionsRef?: React.Ref<AIChatFunctions>;
+    /**
+     * Array of actions available in the "Get Help" menu.
+     * Use this to provide alternative support options like contact forms or documentation links.
+     */
+    getHelpOptions?: GetHelpOption[];
+    /**
+     * Custom heading text for the workflows section.
+     * Use this to describe available automated processes or guided flows.
+     */
+    workflowsHeader?: string;
+    /**
+     * Collection of interactive workflows that can be triggered during chat.
+     * These can guide users through complex processes or data collection.
+     */
+    /**
+     * Custom labels for the chat interface's action buttons.
+     * Use this for internationalization or to better match your application's terminology.
+     */
+    toolbarButtonLabels?: AIChatToolbarButtonLabels;
+    /**
+     * Filters to apply to the chat results.
+     */
+    filters?: SearchAndChatFilters;
+    /**
+     * Components to be rendered in the chat interface.
+     */
+    components?: ComponentsConfig<any>;
+    artifacts?: ComponentsConfig<any>;
+}
+export interface AIChatDisclaimerSettings {
+    /**
+     * Controls whether the disclaimer message is shown.
+     * Enable this when you need to display important notices or legal disclaimers.
+     * @default false
+     */
+    isEnabled?: boolean;
+    /**
+     * The main text content of the disclaimer message.
+     * Should clearly communicate important information about AI usage or limitations.
+     * @example "AI responses are generated automatically and may require verification."
+     */
+    label?: string;
+    /**
+     * Additional information shown when hovering over the disclaimer.
+     * Use this to provide more detailed explanations or context.
+     */
+    tooltip?: string;
+}
+export interface AIChatFunctions {
+    /**
+     * Programmatically sends a message in the chat.
+     * @param message Optional message text. If omitted, sends the current input value.
+     */
+    submitMessage: (message?: string) => void;
+    /**
+     * Programmatically updates the text in the chat input field.
+     * @param message The new message text to set
+     */
+    updateInputMessage: (message: string) => void;
+    /**
+     * Resets the chat to its initial state.
+     * Removes all messages and resets any active workflows.
+     */
+    clearChat: () => void;
+    /**
+     * Displays a form overlay in the chat interface.
+     * @param formSettings Configuration object defining the form's fields and behavior
+     * @param getHelpOption Optional getHelpOption that triggered the form (for analytics)
+     */
+    openForm: (formSettings: AIChatFormSettings, getHelpOption?: GetHelpOption) => void;
+    /**
+     * Programmatically sets focus to the chat input field.
+     * Useful after programmatic updates or when showing the chat interface.
+     */
+    focusInput: () => void;
+}
+export interface AIChatToolbarButtonLabels {
+    /**
+     * Text shown on the button that clears the chat history.
+     * @example "Clear Chat" or "Start Over"
+     */
+    clear?: string;
+    /**
+     * Text shown on the button that generates a shareable chat link.
+     * @example "Share Chat" or "Get Link"
+     */
+    share?: string;
+    /**
+     * Text shown on the button that opens the help options menu.
+     * @example "Get Help" or "Support Options"
+     */
+    getHelp?: string;
+    /**
+     * Text shown on the button that stops the AI from generating a response.
+     * @example "Stop" or "Cancel Response"
+     */
+    stop?: string;
+    /**
+     * Text shown on the button that copies the chat transcript.
+     * @example "Copy Chat" or "Copy Transcript"
+     */
+    copyChat?: string;
+}

package/dist/types/config/base.d.ts

@@ -0,0 +1,344 @@
+import { CustomIconMap } from '../icons';
+import { InkeepCallbackEvent, InkeepFeedback } from '../events';
+import { UrlQueryParam } from '../widget';
+import { UserProvidedColorScheme, IkpTheme } from '../theme';
+import { TransformSource } from '../sources';
+import { ColorModeProviderProps } from '../color-mode';
+import { SearchAndChatFilters } from './filters';
+export interface InkeepBaseSettings {
+    /**
+     * The display name of your organization that will be shown in various UI elements.
+     * For example, this may appear in chat messages or headers.
+     */
+    organizationDisplayName?: string;
+    /**
+     * The primary brand color used throughout the widget UI.
+     * This color will be used to generate a cohesive color scheme.
+     * Should be provided as a valid CSS color value (hex, rgb, etc).
+     */
+    primaryBrandColor: string;
+    /**
+     * Settings to control the color mode (light/dark) behavior.
+     * Can be used to sync with your application's theme or set a forced color mode.
+     * @see ColorModeConfig type for detailed configuration options
+     */
+    colorMode?: ColorModeConfig;
+    /**
+     * Theme customization settings for the widget.
+     * Allows customizing colors, typography, component styles, and more.
+     */
+    theme?: UserTheme;
+    /**
+     * Custom icon overrides for the default icon set.
+     * Allows replacing any of the built-in icons with your own components.
+     */
+    customIcons?: CustomIconMap;
+    /**
+     * Properties to identify and provide context about the current user.
+     * Used for personalization and analytics tracking.
+     * @see UserProperties interface for available fields
+     */
+    userProperties?: UserProperties;
+    /**
+     * Authentication token for the current user.
+     * Used for authenticated API requests if required.
+     */
+    userAuthToken?: string;
+    /**
+     * Additional properties to be sent with analytics events.
+     * These properties will be merged with the event properties.
+     */
+    analyticsProperties?: Record<string, unknown>;
+    /**
+     * Handler for analytics events from the widget.
+     * @param event The analytics event object
+     */
+    onEvent?: (event: InkeepCallbackEvent) => Promise<void>;
+    /**
+     * Handler for feedback events from the widget.
+     * @param feedback The feedback object
+     */
+    onFeedback?: (feedback: InkeepFeedback & {
+        properties?: Record<string, unknown>;
+    }) => Promise<InkeepFeedback>;
+    /**
+     * Whether to bypass the captcha challenge. Only enable this flag if using a server side API type api key, otherwise the api requests will fail without the challenge solution.
+     * @default false
+     */
+    shouldBypassCaptcha?: boolean;
+    /**
+     * Function to transform source data before display.
+     * Allows customizing how source information is presented in the widget.
+     * @param source The original source data
+     * @returns The transformed source data
+     */
+    transformSource?: TransformSource;
+    /**
+     * Reference to the shadow DOM host element if using custom Shadow DOM.
+     * Required when embedding the widget within a Shadow DOM.
+     */
+    shadowHost?: HTMLElement | null;
+    /**
+     * Reference to the root element where the widget is mounted.
+     * Used for positioning and event handling.
+     */
+    rootElement?: HTMLElement | null;
+    /**
+     * Custom tags for widget identification.
+     * Used in analytics to segment and filter widget instances.
+     * Array of string identifiers.
+     */
+    tags?: string[];
+    /**
+     * Instance of the Prism syntax highlighting library.
+     * Required for code block syntax highlighting functionality.
+     */
+    prism?: any;
+    /**
+     * Query parameters to automatically append to URLs in the widget.
+     * Useful for tracking or maintaining context in navigation.
+     * Object mapping parameter names to values.
+     */
+    urlQueryParamsToAppend?: UrlQueryParam;
+    /**
+     * Base-level filters to apply to all search and chat operations.
+     * These are typically organization or user-level filters.
+     */
+    filters?: SearchAndChatFilters;
+}
+export type UserProperties = {
+    /**
+     * The user ID.
+     */
+    id?: string;
+    /**
+     * The user email.
+     */
+    email?: string;
+    /**
+     * The user name.
+     */
+    name?: string;
+    /**
+     * The user cohorts.
+     */
+    cohorts?: string[];
+} & Record<string, unknown>;
+export interface UserTheme extends Partial<IkpTheme> {
+    /**
+     * Whether to disable loading the default font.
+     * @default false
+     */
+    disableLoadingDefaultFont?: boolean;
+    /**
+     * The syntax highlighter theme configuration for code blocks.
+     * Allows setting different themes for light and dark modes.
+     *
+     * @example
+     * ```ts
+     * syntaxHighlighter: {
+     *   lightTheme: themes.github,
+     *   darkTheme: themes.dracula
+     * }
+     * ```
+     */
+    syntaxHighlighter?: SyntaxHighlighterTheme;
+    /**
+     * The primary colors used to generate the color scheme.
+     * These colors will be used to create variations for different UI states.
+     *
+     * @example
+     * ```ts
+     * primaryColors: {
+     *   primary: '#26D6FF',
+     *   secondary: '#6366F1'
+     * }
+     * ```
+     */
+    primaryColors?: UserProvidedColorScheme;
+    /**
+     * The class name for the container that holds CSS variables.
+     * This class will be added to a wrapper div that provides theming context.
+     *
+     * @default 'ikp-variables'
+     */
+    varsClassName?: string;
+    /**
+     * Custom styles to be injected into the widget.
+     * Supports both inline styles and external stylesheets/resources.
+     * Styles are uniquely identified by their key to prevent duplicates.
+     *
+     * @example
+     * ```ts
+     * styles: [
+     *   // External stylesheet or font
+     *   {
+     *     key: 'google-fonts',
+     *     type: 'link',
+     *     value: 'https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap'
+     *   },
+     *   // Custom CSS rules
+     *   {
+     *     key: 'custom-theme',
+     *     type: 'style',
+     *     value: `
+     *       .ikp-ai-chat-message {
+     *         border-radius: 8px;
+     *         padding: 12px;
+     *       }
+     *       [data-theme='dark'] .ikp-ai-chat-message {
+     *         background: #2D3748;
+     *       }
+     *     `
+     *   }
+     * ]
+     * ```
+     */
+    styles?: Style[];
+}
+export interface SyntaxHighlighterTheme {
+    lightTheme?: any;
+    darkTheme?: any;
+}
+export interface Style {
+    /**
+     * A unique identifier for the style.
+     * This is used to prevent duplicate styles and allow for style updates.
+     *
+     * @example
+     * key: 'custom-button-styles'
+     */
+    key?: string;
+    /**
+     * The type of style to apply.
+     * - 'link': Adds a <link> tag to load external resources like fonts or stylesheets
+     * - 'style': Injects CSS directly into a <style> tag
+     *
+     * @example
+     * type: 'link' // For loading external resources
+     * type: 'style' // For inline CSS
+     */
+    type: 'link' | 'style';
+    /**
+     * The content of the style.
+     * For type='link', this should be a valid URL to an external resource.
+     * For type='style', this should be valid CSS code.
+     *
+     * @example
+     * // For type='link':
+     * value: 'https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap'
+     *
+     * // For type='style':
+     * value: `.custom-button {
+     *   background: blue;
+     *   color: white;
+     * }`
+     */
+    value: string;
+}
+export interface ColorModeConfig extends Omit<ColorModeProviderProps, 'children' | 'rootId' | 'shadowHostId'> {
+    /**
+     * Configuration for syncing the widget's color mode with an external element.
+     *
+     * This allows the widget to automatically match its color mode (light/dark) with your application's theme.
+     * The widget will observe changes to specified attributes on a target element and update its appearance accordingly.
+     *
+     * @example
+     * ```ts
+     * colorMode: {
+     *   sync: {
+     *     // Watch the document root for theme changes
+     *     target: document.documentElement,
+     *     // Monitor the data-theme attribute
+     *     attributes: ['data-theme'],
+     *     // Determine dark mode based on attribute value
+     *     isDarkMode: (attrs) => attrs['data-theme'] === 'dark',
+     *     // Optional callback when color mode changes
+     *     onChange: (mode) => console.log('Color mode changed to:', mode)
+     *   }
+     * }
+     * ```
+     */
+    sync?: SyncColorMode;
+}
+export interface SyncColorMode {
+    /**
+     * The HTML element to watch for color mode changes.
+     * This element's attributes will be monitored for changes to determine the color mode.
+     *
+     * Common use cases include watching the document root or a specific app container.
+     *
+     * @example
+     * ```ts
+     * // Watch the document root element
+     * target: document.documentElement
+     *
+     * // Watch a specific container element
+     * target: document.querySelector('#app')
+     *
+     * // Watch a specific element by ID
+     * target: '#app'
+     * ```
+     */
+    target: HTMLElement | null | string;
+    /**
+     * The specific attributes to monitor for color mode changes.
+     * The observer will only trigger when these attributes change on the target element.
+     *
+     * Common attributes used for theming include:
+     * - data-theme: Custom theme attribute
+     * - color-scheme: Standard CSS color scheme
+     * - class: Class-based theming
+     *
+     * @example
+     * ```ts
+     * // Watch data-theme attribute
+     * attributes: ['data-theme']
+     *
+     * // Watch color-scheme attribute
+     * attributes: ['color-scheme']
+     *
+     * // Watch class changes
+     * attributes: ['class']
+     * ```
+     */
+    attributes: string[];
+    /**
+     * A function that determines if dark mode is active based on the target element's attributes.
+     *
+     * The function receives an object containing the current values of all monitored attributes,
+     * where the keys are attribute names and values are the attribute values.
+     *
+     * @param attributes - Object containing the current values of monitored attributes
+     * @returns boolean - True if dark mode is detected, false otherwise
+     *
+     * @example
+     * ```ts
+     * // Check data-theme attribute
+     * isDarkMode: (attributes) => attributes['data-theme'] === 'dark'
+     *
+     * // Check class for dark mode
+     * isDarkMode: (attributes) => /\bdark\b/.test(attributes['class'])
+     *
+     * // Check color-scheme
+     * isDarkMode: (attributes) => attributes['color-scheme'] === 'dark'
+     * ```
+     */
+    isDarkMode?: (attributes: Record<string, string | null>) => boolean;
+    /**
+     * Optional callback function that is invoked whenever the color mode changes.
+     *
+     * This can be used to perform side effects or sync the color mode with other parts of your application.
+     *
+     * @param colorMode - The new color mode value ('light' | 'dark')
+     *
+     * @example
+     * ```ts
+     * onChange: (colorMode) => {
+     *   console.log(`Color mode changed to: ${colorMode}`);
+     *   // Update other UI elements
+     * }
+     * ```
+     */
+    onChange?: (colorMode: string) => void;
+}

package/dist/types/config/components.d.ts

@@ -0,0 +1,10 @@
+import { Message } from '../message';
+export type ComponentsConfig<A extends Record<string, unknown>> = {
+    [K in keyof A]: (props: A[K], target: HTMLElement, context: null) => void | React.ReactNode;
+} & {
+    IkpMessage?(props: {
+        message: Message;
+        renderComponent: (name: string, props: Record<string, unknown>) => React.ReactNode;
+        renderMarkdown: (text: string) => React.ReactNode;
+    }, target: HTMLElement, context: null): void | React.ReactNode;
+};

package/dist/types/config/filters.d.ts

@@ -0,0 +1,17 @@
+export interface SearchAndChatFilters {
+    attributes?: {
+        [key: string]: any;
+    };
+}
+type QueryValue = boolean | number | string;
+type QueryCondition = {
+    $eq: QueryValue;
+} | {
+    $in: (number | string)[];
+};
+export type FilterQuery = Record<string, QueryCondition | QueryValue | QueryValue[]> | {
+    $and: FilterQuery[];
+} | {
+    $or: FilterQuery[];
+};
+export {};

package/dist/types/config/index.d.ts

@@ -0,0 +1,36 @@
+import { InkeepAIChatSettings } from './ai';
+import { InkeepBaseSettings } from './base';
+import { InkeepSearchSettings } from './search';
+export interface InkeepConfig {
+    /**
+     * The prefix to use for the widget.
+     * @default 'ikp'
+     */
+    prefix?: string;
+    /**
+     * Identifies how the widget is being used/displayed. Used for analytics tracking
+     * and internal behavior configuration.
+     *
+     * This is automatically set by the widget components and typically
+     * should not be manually configured.
+     *
+     * @internal
+     */
+    componentType: any;
+    /**
+     * Configuration for the chat.
+     */
+    aiChatSettings: InkeepAIChatSettings & {
+        shouldAutoFocusInput?: boolean;
+    };
+    /**
+     * Configuration for the base settings.
+     */
+    baseSettings: InkeepBaseSettings;
+    /**
+     * Configuration for the search settings.
+     */
+    searchSettings: InkeepSearchSettings & {
+        shouldAutoFocusInput?: boolean;
+    };
+}

package/dist/types/config/modal.d.ts

@@ -0,0 +1,33 @@
+export interface InkeepModalSettings {
+    /**
+     * Controls whether the modal is open.
+     */
+    isOpen?: boolean;
+    /**
+     * Handler called when the modal opens or closes.
+     */
+    onOpenChange?: (isOpen: boolean) => void;
+    /**
+     * Whether the modal is open by default.
+     * @default false
+     */
+    defaultOpen?: boolean;
+    /**
+     * The shortcut key.
+     *
+     * The key to trigger the modal when pressed with Cmd (Mac) / Ctrl (Windows).
+     *
+     * Set to `null` to disable the shortcut.
+     *
+     * @default 'k'
+     */
+    shortcutKey?: string | null;
+    /**
+     * The trigger selector.
+     *
+     * The selector to trigger the modal when clicked.
+     *
+     * @default '[data-inkeep-modal-trigger]'
+     */
+    triggerSelector?: string;
+}