@servicetitan/titan-chatbot-api 3.0.0

package/src/api-client/utils/model-utils.ts

@@ -0,0 +1,68 @@
+import { Models } from '..';
+
+export function createNewSessionModel(): Models.Session {
+    return new Models.Session();
+}
+
+export function createSelectionsModel(
+    filters: Models.IOption[],
+    selected: Record<string, string[]>
+): Models.Selections | undefined {
+    const process = (filters: Models.IOption[]): Models.Selections | undefined => {
+        let result: Models.Selections | undefined;
+        const ensureResult = () => {
+            if (!result) {
+                result = new Models.Selections({
+                    subOptions: {},
+                });
+            }
+        };
+
+        const filterList = filters.filter(
+            x => x.type === Models.OptionType.Group && Boolean(x.subOptions?.length)
+        );
+        for (const filter of filterList) {
+            const hasSubFilters = Boolean(
+                filter.subOptions?.some(x => Boolean(x.subOptions?.length))
+            );
+            if (!hasSubFilters) {
+                // Leaf filter: just collect selected values
+                const values = filter.subOptions
+                    ?.map(o => o.key)
+                    .filter(o => selected[filter.key]?.includes(o));
+                if (values?.length) {
+                    ensureResult();
+                    result!.subOptions![filter.key] = new Models.Selections({ values });
+                }
+            } else {
+                // Non-leaf filter: add selected options as selectables and process sub-filters
+                const filterSelectables = filter.subOptions!.filter(
+                    x =>
+                        x.type === Models.OptionType.Selectable &&
+                        Boolean(x.subOptions?.length) &&
+                        selected[filter.key]?.includes(x.key!)
+                );
+                if (!filterSelectables.length) {
+                    continue;
+                }
+                ensureResult();
+                const filterResult = new Models.Selections({
+                    subOptions: {},
+                });
+                result!.subOptions![filter.key] = filterResult;
+                for (const filterSelectable of filterSelectables) {
+                    // Process sub-filters: if any sub-filters selected, add them to the result
+                    const subFilters = filterSelectable.subOptions!;
+                    const resultSubFilters = process(subFilters);
+                    filterResult.subOptions![filterSelectable.key] =
+                        resultSubFilters ??
+                        new Models.Selections({
+                            subOptions: {},
+                        });
+                }
+            }
+        }
+        return result;
+    };
+    return process(filters);
+}

package/src/cypress.d.ts

@@ -0,0 +1,10 @@
+// eslint-disable-next-line spaced-comment
+/// <reference types="cypress" />
+declare namespace Cypress {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    interface Chainable<Subject = any> {
+        getCy<E extends Node = HTMLElement>(value: string): Chainable<JQuery<E>>;
+        getCy2<E extends Node = HTMLElement>(value: string): Chainable<JQuery<E>>;
+        getAnvil<E extends Node = HTMLElement>(value: string, extra?: string): Chainable<JQuery<E>>;
+    }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+/* eslint-disable no-restricted-imports */
+export * from './api-client';
+export * from './stores';
+export * from './models';
+export * as NativeClientHC from './api-client/help-center/native-client';
+export * as NativeClientTC from './api-client/titan-chat/native-client';

package/src/models/chatbot-customizations.ts

@@ -0,0 +1,16 @@
+import { ChatCustomizations, ChatError } from '@servicetitan/titan-chat-ui-common';
+
+export type ChatbotCustomizations = ChatCustomizations &
+    Partial<{
+        error?: {
+            recover: (error?: ChatError) => Promise<void>;
+        };
+        feedback?: {
+            title?: string;
+            showGuardrailFeedback?: boolean;
+            isCommentAlwaysRequired?: boolean;
+        };
+        filters?: {
+            enabled?: boolean;
+        };
+    }>;

package/src/models/index.ts

@@ -0,0 +1 @@
+export * from './chatbot-customizations';

package/src/stores/__tests__/chatbot-ui-backend.store.test.ts

@@ -0,0 +1,426 @@
+import { expect } from '@jest/globals';
+import { ILog, Log, LogError, LogInfo, LogWarning } from '@servicetitan/log-service';
+import { Container } from '@servicetitan/react-ioc';
+import {
+    ChatError,
+    ChatMessageModelText,
+    ChatMessageModelWelcome,
+    ChatRunState,
+    ChatUiEventListener,
+} from '@servicetitan/titan-chat-ui-common';
+import { CHATBOT_API_CLIENT, IChatbotApiClient, Models, ModelsMocks } from '../../api-client';
+import { ChatbotApiClientMock } from '../../api-client/__mocks__/chatbot-api-client.mock';
+import { initTestContainer } from '../../utils/test-utils';
+import { ChatbotUiBackendStore } from '../chatbot-ui-backend.store';
+import { CHATBOT_UI_STORE_TOKEN, ChatbotUiStore } from '../chatbot-ui.store';
+
+const WELCOME_MESSAGE =
+    'Hi there! I’m Titan, an AI chatbot powered by Titan Intelligence. I’m here to answer your questions about using ServiceTitan. You can ask me things like "How to merge duplicate customers?". Do you have a question for me?';
+
+const initContainer = initTestContainer(ChatbotUiBackendStore, container => {
+    container
+        .bind<ILog>(Log)
+        .to(
+            class implements ILog {
+                error: (entry: LogError) => void = jest.fn();
+                info: (entry: LogInfo) => void = jest.fn();
+                warning: (entry: LogWarning) => void = jest.fn();
+            }
+        )
+        .inSingletonScope();
+    container
+        .bind<IChatbotApiClient>(CHATBOT_API_CLIENT)
+        .toConstantValue(new ChatbotApiClientMock());
+    container.bind(CHATBOT_UI_STORE_TOKEN).to(ChatbotUiStore).inSingletonScope();
+});
+
+describe('[ChatbotUiBackendStore]', () => {
+    let container: Container;
+    let store: ChatbotUiBackendStore;
+    let chatbotApi: ChatbotApiClientMock;
+    let chatUiStore: ChatbotUiStore;
+    let log: ILog;
+
+    beforeEach(() => {
+        container = initContainer();
+        store = container.get(ChatbotUiBackendStore);
+        chatbotApi = container.get<IChatbotApiClient>(CHATBOT_API_CLIENT) as ChatbotApiClientMock;
+        chatUiStore = container.get<ChatbotUiStore>(CHATBOT_UI_STORE_TOKEN);
+        log = container.get<ILog>(Log);
+        jest.useFakeTimers();
+        jest.setSystemTime(new Date('2000-01-01T00:00:00.000Z'));
+    });
+
+    afterEach(() => {
+        jest.useRealTimers();
+        jest.clearAllMocks();
+    });
+
+    describe('with subscription', () => {
+        let spyOn: jest.SpyInstance;
+        let spyOff: jest.SpyInstance;
+
+        beforeEach(() => {
+            spyOn = jest.spyOn(chatUiStore, 'on');
+            spyOff = jest.spyOn(chatUiStore, 'off');
+        });
+
+        test('should subscribe on external events', () => {
+            store.subscribe();
+            expect(spyOn).toHaveBeenCalledTimes(7);
+            expect(spyOff).toHaveBeenCalledTimes(7);
+        });
+
+        test('should unsubscribe from external events', () => {
+            store.unsubscribe();
+            expect(chatUiStore.on).toHaveBeenCalledTimes(0);
+            expect(chatUiStore.off).toHaveBeenCalledTimes(7);
+        });
+    });
+
+    describe('with run', () => {
+        const runChatUiEventListener = async <T = void>(
+            listener: ChatUiEventListener<T>,
+            args: unknown[]
+        ) => {
+            return new Promise<T>((resolve, reject) => {
+                listener.apply(store, [resolve, reject, ...args]);
+            });
+        };
+
+        const runStore = async () => {
+            await runChatUiEventListener(store.handleRun, []);
+            await jest.advanceTimersToNextTimerAsync(); // Wait for the timer to be set
+        };
+
+        const mockChatbotSession = () => {
+            chatbotApi.getOptions.mockResolvedValue(ModelsMocks.mockFrontendModel());
+            chatbotApi.postSession.mockResolvedValue(ModelsMocks.mockSession());
+            chatbotApi.deleteSession.mockResolvedValue(ModelsMocks.mockSession());
+        };
+
+        const mockChatbotAnswer = (answer: string) => {
+            chatbotApi.postMessage.mockResolvedValue(
+                ModelsMocks.mockBotMessage({
+                    answer,
+                })
+            );
+        };
+
+        const ensureChatStarted = () => {
+            expect(chatUiStore.isAgentTyping).toBe(false);
+            expect(chatUiStore.isFilePickerEnabled).toBe(false);
+            expect(chatUiStore.file).toBe(undefined);
+            expect(chatUiStore.currentFileMessage).toBe(undefined);
+            expect(chatUiStore.error).toBe(undefined);
+            expect(chatUiStore.endReason).toBe(undefined);
+            expect(chatUiStore.timer).toBe(undefined);
+            expect(chatUiStore.scrollCounter > 1).toBe(true);
+            expect(chatUiStore.status).toBe(ChatRunState.Started);
+        };
+
+        test('should run chatbot without stored session', async () => {
+            store.subscribe();
+            mockChatbotSession();
+
+            await runStore();
+
+            ensureChatStarted();
+            expect(chatUiStore.messages.length).toBe(1);
+            expect(chatUiStore.messages[0].type).toBe('welcome');
+            expect((chatUiStore.messages[0] as ChatMessageModelText).message).toBe(WELCOME_MESSAGE);
+
+            /*
+             * We don't have session yet because we've just initialized the chat with welcome message
+             * and we don't do any chatbotApi.postSession call
+             */
+            expect(store.session).toBeUndefined();
+            expect(chatbotApi.postSession).toHaveBeenCalledTimes(0);
+
+            mockChatbotAnswer('bot answer');
+            await chatUiStore.sendMessageText('user question');
+            expect(chatUiStore.messages.length).toBe(3);
+            expect(chatUiStore.messages[0].type).toBe('welcome');
+            expect(chatUiStore.messages[1].type).toBe('message');
+            expect(chatUiStore.messages[2].type).toBe('message');
+            expect(chatUiStore.messages[1].participant.isAgent).toBe(false);
+            expect(chatUiStore.messages[2].participant.isAgent).toBe(true);
+            expect((chatUiStore.messages[1] as ChatMessageModelText).message).toBe('user question');
+            expect((chatUiStore.messages[2] as ChatMessageModelText).message).toBe('bot answer');
+            expect(log.error).toHaveBeenCalledTimes(0);
+        });
+
+        test('should run chatbot with stored session with expiration', async () => {
+            mockChatbotSession();
+
+            await jest.advanceTimersByTimeAsync(1000 * 60 * 60 * 16);
+            await runStore();
+            ensureChatStarted();
+            expect(store.session).not.toBeDefined();
+            expect(chatUiStore.messages.length).toBe(1);
+            expect(chatbotApi.postSession).toHaveBeenCalledTimes(0);
+            expect(log.error).toHaveBeenCalledTimes(0);
+        });
+
+        test('should destroy', async () => {
+            mockChatbotSession();
+
+            await runStore();
+            store.session = ModelsMocks.mockSession();
+            await runChatUiEventListener(store.handleDestroy, []);
+
+            expect(chatbotApi.postSession).toHaveBeenCalledTimes(0);
+            expect(chatbotApi.deleteSession).toHaveBeenCalledTimes(1);
+            expect(chatUiStore.status).toBe(ChatRunState.Offline);
+            expect(store.session).toBeUndefined();
+            expect(log.error).toHaveBeenCalledTimes(0);
+        });
+
+        test('should restart', async () => {
+            mockChatbotSession();
+
+            await runStore();
+            store.session = ModelsMocks.mockSession();
+            await runChatUiEventListener(store.handleRestart, []);
+
+            expect(chatbotApi.postSession).toHaveBeenCalledTimes(0);
+            expect(chatbotApi.deleteSession).toHaveBeenCalledTimes(1);
+            expect(chatUiStore.status).toBe(ChatRunState.Started);
+            expect(log.error).toHaveBeenCalledTimes(0);
+        });
+
+        describe('with messages', () => {
+            test('should send message', async () => {
+                mockChatbotSession();
+                mockChatbotAnswer('bot answer');
+
+                await runStore();
+
+                await chatUiStore.sendMessageText('user question');
+                const message = chatUiStore.messages.at(-1)! as ChatMessageModelText;
+                await runChatUiEventListener(store.handleMessageSend, [message]);
+
+                expect(chatUiStore.messages.length).toBe(3);
+                expect((chatUiStore.messages[0] as ChatMessageModelText).message).toBe(
+                    WELCOME_MESSAGE
+                );
+                expect((chatUiStore.messages[1] as ChatMessageModelText).message).toBe(
+                    'user question'
+                );
+                expect((chatUiStore.messages[2] as ChatMessageModelText).message).toBe(
+                    'bot answer'
+                );
+                expect(log.error).toHaveBeenCalledTimes(0);
+            });
+
+            test('should send message with error', async () => {
+                mockChatbotSession();
+                chatbotApi.postMessage.mockRejectedValue(new Error('error'));
+
+                await chatUiStore.sendMessageText('user question');
+                const message = chatUiStore.messages.at(-1)! as ChatMessageModelText;
+                await runChatUiEventListener(store.handleMessageSend, [message]);
+
+                expect(chatbotApi.postSession).toHaveBeenCalled();
+                expect(chatbotApi.postMessage).toHaveBeenCalled();
+                expect(chatUiStore.isError).toBe(true);
+                expect(log.error).toHaveBeenCalledWith({
+                    category: 'TitanChatbot',
+                    code: 'TitanChatbot_FailedToSendMessage',
+                    error: new Error('error'),
+                    message: 'Failed to send message',
+                });
+            });
+
+            test('should send message retry', async () => {
+                mockChatbotSession();
+                const spyMessage = jest.spyOn(chatbotApi, 'postMessage');
+
+                // Retry with non-text message should not call "message"
+                const messageNonText = ModelsMocks.mockChatMessageModel<ChatMessageModelWelcome>({
+                    type: 'welcome',
+                });
+                await runChatUiEventListener(store.handleMessageSendRetry, [messageNonText]);
+                expect(spyMessage).not.toHaveBeenCalled();
+
+                // Retry with text message should call "message"
+                const message = ModelsMocks.mockChatMessageModel<ChatMessageModelText>({
+                    message: 'message',
+                });
+                await runChatUiEventListener(store.handleMessageSendRetry, [message]);
+                expect(spyMessage).toHaveBeenCalledWith(
+                    ModelsMocks.mockUserMessage({
+                        context: undefined,
+                        selections: undefined,
+                        question: 'message',
+                    }),
+                    expect.any(AbortSignal)
+                );
+            });
+        });
+
+        describe('with session feedback', () => {
+            const createSessionFeedback = () =>
+                ModelsMocks.mockFeedback({
+                    sessionId: 1,
+                    messageId: undefined,
+                    rating: Models.FeedbackRatings.ThumbsUp,
+                    description: 'description',
+                });
+
+            test('should send feedback', async () => {
+                mockChatbotSession();
+
+                chatbotApi.postFeedback.mockResolvedValueOnce(createSessionFeedback());
+
+                const { feedback, state } = await runChatUiEventListener(
+                    store.handleSessionFeedback,
+                    [createSessionFeedback()]
+                );
+
+                expect(state).toBe(Models.ChatbotFeedbackState.Success);
+                expect(feedback).toEqual(createSessionFeedback());
+                expect(chatbotApi.postSession).toHaveBeenCalled();
+                expect(chatbotApi.postFeedback).toHaveBeenCalledWith(
+                    createSessionFeedback(),
+                    expect.any(AbortSignal)
+                );
+            });
+
+            test('should send feedback with session error', async () => {
+                chatbotApi.postSession.mockRejectedValueOnce('session error');
+                chatbotApi.postFeedback.mockResolvedValueOnce(createSessionFeedback());
+
+                const { feedback, state } = await runChatUiEventListener(
+                    store.handleSessionFeedback,
+                    [createSessionFeedback()]
+                );
+
+                expect(state).toBe(Models.ChatbotFeedbackState.Failure);
+                expect(feedback).toEqual(createSessionFeedback());
+                expect(chatbotApi.postSession).toHaveBeenCalled();
+                expect(chatbotApi.postFeedback).not.toHaveBeenCalled();
+                expect(chatUiStore.isError).toBe(true);
+                expect(log.error).toHaveBeenCalledWith({
+                    category: 'TitanChatbot',
+                    code: 'TitanChatbot_FailedToSendFeedback',
+                    error: 'session error',
+                    message: 'Failed to send feedback',
+                });
+            });
+
+            test('should send feedback with error', async () => {
+                mockChatbotSession();
+                chatbotApi.postSession.mockReset().mockRejectedValue(new Error('session error'));
+                chatbotApi.postFeedback.mockResolvedValueOnce(createSessionFeedback());
+
+                const { feedback, state } = await runChatUiEventListener(
+                    store.handleSessionFeedback,
+                    [createSessionFeedback()]
+                );
+
+                expect(state).toBe(Models.ChatbotFeedbackState.Failure);
+                expect(feedback).toEqual(createSessionFeedback());
+                expect(chatbotApi.postSession).toHaveBeenCalled();
+                expect(chatbotApi.postFeedback).not.toHaveBeenCalled();
+                expect(chatUiStore.isError).toBe(true);
+                expect(log.error).toHaveBeenCalledWith({
+                    category: 'TitanChatbot',
+                    code: 'TitanChatbot_FailedToSendFeedback',
+                    error: new Error('session error'),
+                    message: 'Failed to send feedback',
+                });
+            });
+        });
+
+        describe('with message feedback', () => {
+            const createMessageFeedback = () =>
+                ModelsMocks.mockFeedback({
+                    sessionId: 1,
+                    messageId: 1,
+                    description: 'description',
+                    linkUrl: 'linkUrl',
+                    options: [Models.FeedbackOptions.Unclear, Models.FeedbackOptions.Incorrect],
+                    rating: Models.FeedbackRatings.ThumbsUp,
+                });
+            const createLogError = (errorMessage: string) => ({
+                category: 'TitanChatbot',
+                code: 'TitanChatbot_FailedToSendMessageFeedback',
+                error: errorMessage,
+                message: 'Failed to send message feedback',
+            });
+
+            test('should assert message feedback 1', async () => {
+                const { feedback, state } = await runChatUiEventListener(
+                    store.handleMessageFeedback,
+                    []
+                );
+                expect(feedback).toBeUndefined();
+                expect(state).toBe(Models.ChatbotFeedbackState.Failure);
+                expect(chatUiStore.isError).toBe(true);
+                expect(chatUiStore.error?.message).toBe('Failed to send message feedback');
+                expect(log.error).toHaveBeenCalledWith({
+                    category: 'TitanChatbot',
+                    code: 'TitanChatbot_FailedToSendMessageFeedback',
+                    error: new ChatError('Message feedback is missing.'),
+                    message: 'Failed to send message feedback',
+                });
+                expect(chatbotApi.postFeedback).not.toHaveBeenCalled();
+            });
+
+            test('should assert message feedback 3', async () => {
+                chatbotApi.postSession.mockRejectedValueOnce('session error');
+                const { feedback, state } = await runChatUiEventListener(
+                    store.handleMessageFeedback,
+                    [createMessageFeedback()]
+                );
+                expect(state).toBe(Models.ChatbotFeedbackState.Failure);
+                expect(feedback).toEqual(createMessageFeedback());
+                expect(chatUiStore.isError).toBe(true);
+                expect(chatUiStore.error?.message).toBe('Failed to send message feedback');
+                expect(log.error).toHaveBeenCalledWith({
+                    category: 'TitanChatbot',
+                    code: 'TitanChatbot_FailedToSendMessageFeedback',
+                    error: 'session error',
+                    message: 'Failed to send message feedback',
+                });
+                expect(chatbotApi.postFeedback).not.toHaveBeenCalled();
+            });
+
+            test('should send message feedback', async () => {
+                mockChatbotSession();
+                chatbotApi.postFeedback.mockResolvedValueOnce(createMessageFeedback());
+
+                const feedback = createMessageFeedback();
+                await runChatUiEventListener(store.handleMessageFeedback, [feedback]);
+
+                expect(chatbotApi.postFeedback).toHaveBeenCalledWith(
+                    {
+                        ...feedback,
+                    },
+                    expect.any(AbortSignal)
+                );
+            });
+
+            test('should send message feedback with session error', async () => {
+                chatbotApi.postSession.mockRejectedValueOnce('session error');
+                chatbotApi.postFeedback.mockResolvedValueOnce(createMessageFeedback());
+                const feedback = createMessageFeedback();
+                await runChatUiEventListener(store.handleMessageFeedback, [feedback]);
+
+                expect(chatbotApi.postFeedback).not.toHaveBeenCalled();
+                expect(log.error).toHaveBeenCalledWith(createLogError('session error'));
+            });
+
+            test('should send message feedback with feedback error', async () => {
+                mockChatbotSession();
+                chatbotApi.postFeedback.mockRejectedValueOnce('feedback error');
+                const feedback = createMessageFeedback();
+                await runChatUiEventListener(store.handleMessageFeedback, [feedback]);
+
+                expect(chatbotApi.postFeedback).toHaveBeenCalledTimes(1);
+                expect(log.error).toHaveBeenCalledWith(createLogError('feedback error'));
+            });
+        });
+    });
+});