@servicetitan/titan-chatbot-api 3.0.0

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

@@ -0,0 +1,401 @@
+import { ILog, Log } from '@servicetitan/log-service';
+import { inject, injectable, symbolToken } from '@servicetitan/react-ioc';
+import {
+    ChatError,
+    ChatMessageModelBase,
+    ChatMessageModelText,
+    ChatMessageState,
+    ChatRunState,
+    ChatUiEvent,
+    ChatUiEventListener,
+    IChatUiBackendStore,
+} from '@servicetitan/titan-chat-ui-common';
+import axios from 'axios';
+import { makeObservable, runInAction } from 'mobx';
+import { CHATBOT_API_CLIENT, IChatbotApiClient, Models, ModelsUtils } from '../api-client';
+import { withTimeout } from '../utils/axios-utils';
+import { CHATBOT_UI_STORE_TOKEN, ChatbotUiEvent, IChatbotUiStore } from './chatbot-ui.store';
+import { InitializeStore } from './initialize.store';
+
+const CHATBOT_ASK_BOT_TIMEOUT = 31000; // 31 seconds
+
+export const CHATBOT_UI_BACKEND_STORE_TOKEN = symbolToken<IChatbotUiBackendStore>(
+    'CHATBOT_UI_BACKEND_STORE_TOKEN'
+);
+
+export interface IChatbotUiBackendStore extends IChatUiBackendStore {
+    session?: Models.ISession;
+    initialize: () => void;
+    saveCurrentState: () => void;
+    deleteFromSessionStorage: () => void;
+    restoreChatSession: () => void;
+    restartTimers: () => void;
+}
+
+@injectable()
+export class ChatbotUiBackendStore extends InitializeStore implements IChatbotUiBackendStore {
+    session?: Models.ISession;
+    abortController!: AbortController;
+    @inject(CHATBOT_API_CLIENT) protected readonly chatbotApiClient!: IChatbotApiClient;
+    @inject(CHATBOT_UI_STORE_TOKEN) protected readonly chatUiStore!: IChatbotUiStore;
+
+    @inject(Log) private log!: ILog;
+    private intervalId?: ReturnType<typeof setInterval>;
+    private sessionPromise?: Promise<Models.ISession>;
+
+    protected get logService(): ILog {
+        return this.log;
+    }
+
+    constructor() {
+        super();
+        makeObservable(this);
+        this.initializeAbortController();
+        this.startRefreshingAuth();
+    }
+
+    subscribe(): void {
+        this.unsubscribe();
+        this.chatUiStore.on(ChatUiEvent.eventRun, this.handleRun);
+        this.chatUiStore.on(ChatUiEvent.eventDestroy, this.handleDestroy);
+        this.chatUiStore.on(ChatUiEvent.eventRestart, this.handleRestart);
+        this.chatUiStore.on(ChatUiEvent.eventMessageSend, this.handleMessageSend);
+        this.chatUiStore.on(ChatUiEvent.eventMessageSendRetry, this.handleMessageSendRetry);
+        this.chatUiStore.on(ChatbotUiEvent.eventChatbotSessionFeedback, this.handleSessionFeedback);
+        this.chatUiStore.on(ChatbotUiEvent.eventChatbotMessageFeedback, this.handleMessageFeedback);
+    }
+    unsubscribe(): void {
+        this.chatUiStore.off(ChatUiEvent.eventRun, this.handleRun);
+        this.chatUiStore.off(ChatUiEvent.eventDestroy, this.handleDestroy);
+        this.chatUiStore.off(ChatUiEvent.eventRestart, this.handleRestart);
+        this.chatUiStore.off(ChatUiEvent.eventMessageSend, this.handleMessageSend);
+        this.chatUiStore.off(ChatUiEvent.eventMessageSendRetry, this.handleMessageSendRetry);
+        this.chatUiStore.off(
+            ChatbotUiEvent.eventChatbotSessionFeedback,
+            this.handleSessionFeedback
+        );
+        this.chatUiStore.off(
+            ChatbotUiEvent.eventChatbotMessageFeedback,
+            this.handleMessageFeedback
+        );
+    }
+
+    handleRun: ChatUiEventListener = async resolve => {
+        await this.run();
+        resolve();
+    };
+
+    handleDestroy: ChatUiEventListener = async resolve => {
+        await this.destroy();
+        resolve();
+    };
+
+    handleRestart: ChatUiEventListener = async resolve => {
+        await this.destroy();
+        this.deleteFromSessionStorage();
+        await this.run();
+        resolve();
+    };
+
+    handleMessageSend: ChatUiEventListener = async (
+        resolve,
+        _,
+        messageModel: ChatMessageModelText,
+        selections: Models.Selections | undefined
+    ) => {
+        await this.sendMessage(messageModel, selections);
+        resolve();
+    };
+
+    handleMessageSendRetry: ChatUiEventListener = async (
+        resolve,
+        _,
+        messageModel: ChatMessageModelBase
+    ) => {
+        if (messageModel.type !== 'message') {
+            resolve();
+            return;
+        }
+        const selections = messageModel.data?.selections as Models.Selections | undefined;
+        await this.sendMessage(messageModel as ChatMessageModelText, selections);
+        resolve();
+    };
+
+    handleSessionFeedback: ChatUiEventListener<{
+        state: Models.ChatbotFeedbackState;
+        feedback?: Models.Feedback;
+    }> = async (resolve, _, feedback?: Models.Feedback) => {
+        let feedbackState: Models.ChatbotFeedbackState;
+        let feedbackResult = feedback;
+        try {
+            if (!feedback) {
+                throw new ChatError('Session feedback is missing.', {
+                    recoverStrategy: false,
+                });
+            }
+            if (typeof feedback.messageId !== 'undefined') {
+                throw new ChatError('Session feedback should not contain messageId.', {
+                    recoverStrategy: false,
+                });
+            }
+            await this.ensureSession();
+            runInAction(() => {
+                feedback.sessionId = this.session!.id;
+            });
+            feedbackResult = await this.api('postFeedback', feedback, this.abortController.signal);
+            feedbackState = Models.ChatbotFeedbackState.Success;
+        } catch (error: unknown) {
+            this.setError(
+                'FailedToSendFeedback',
+                'Send session feedback',
+                'Failed to send feedback',
+                error
+            );
+            feedbackState = Models.ChatbotFeedbackState.Failure;
+        }
+        resolve({
+            state: feedbackState,
+            feedback: feedbackResult,
+        });
+    };
+
+    handleMessageFeedback: ChatUiEventListener<{
+        state: Models.ChatbotFeedbackState;
+        feedback?: Models.Feedback;
+    }> = async (resolve, _, feedback?: Models.Feedback) => {
+        let feedbackState: Models.ChatbotFeedbackState;
+        let feedbackResult = feedback;
+        try {
+            if (!feedback) {
+                throw new ChatError('Message feedback is missing.', {
+                    recoverStrategy: false,
+                });
+            }
+            if (!feedback.messageId) {
+                throw new ChatError('Message feedback is missing messageId.', {
+                    recoverStrategy: false,
+                });
+            }
+            await this.ensureSession();
+            runInAction(() => {
+                feedback.sessionId = this.session!.id;
+            });
+            feedbackResult = await this.api('postFeedback', feedback, this.abortController.signal);
+            feedbackState = Models.ChatbotFeedbackState.Success;
+        } catch (error: unknown) {
+            this.setError(
+                'FailedToSendMessageFeedback',
+                'Send message feedback',
+                'Failed to send message feedback',
+                error
+            );
+            feedbackState = Models.ChatbotFeedbackState.Failure;
+        }
+        resolve({
+            state: feedbackState,
+            feedback: feedbackResult,
+        });
+    };
+
+    restoreChatSession() {}
+
+    saveCurrentState() {}
+
+    deleteFromSessionStorage() {}
+
+    restartTimers() {
+        this.startRefreshingAuth();
+    }
+
+    protected ensureWelcomeMessage() {
+        if (this.chatUiStore.messages.length) {
+            return;
+        }
+        this.withSaveState(() => {
+            this.chatUiStore.addMessageWelcome(
+                '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?'
+            );
+        });
+    }
+
+    protected logError(code: string, message: string, error: any) {
+        if (axios.isCancel(error)) {
+            return;
+        }
+        this.logService.error({
+            error,
+            message,
+            category: 'TitanChatbot',
+            code: `TitanChatbot_${code}`,
+        });
+    }
+
+    protected override async initializeInternal() {
+        await super.initializeInternal();
+        const options = await this.chatbotApiClient.getOptions();
+        runInAction(() => {
+            this.chatUiStore.filterStore.initFilters(options);
+        });
+    }
+
+    protected async run() {
+        this.chatUiStore.setStatus(ChatRunState.Initializing);
+        await this.initialize();
+        this.restoreChatSession();
+        this.ensureWelcomeMessage();
+        this.restartTimers();
+        this.chatUiStore.setStatus(ChatRunState.Started);
+    }
+
+    protected reset() {
+        this.setSession(undefined);
+    }
+
+    protected async destroy() {
+        if (this.session) {
+            const session = await this.api('deleteSession', this.session);
+            this.setSession(session);
+        }
+        this.reset();
+        this.chatUiStore.reset();
+    }
+
+    protected processBotAnswer(answer: Models.IBotMessage) {
+        this.chatUiStore.addMessage(true, answer.answer, answer);
+    }
+
+    private async sendMessage(messageModel: ChatMessageModelText, selections?: Models.Selections) {
+        try {
+            await this.ensureSession();
+            this.chatUiStore.setAgentTyping(true);
+            const answer = await withTimeout(
+                this.api(
+                    'postMessage',
+                    new Models.UserMessage({
+                        sessionId: this.session!.id!,
+                        question: messageModel.message,
+                        experience: Models.Experience.MultiTurn,
+                        selections,
+                    }),
+                    this.abortController.signal
+                ),
+                CHATBOT_ASK_BOT_TIMEOUT,
+                this.abortController
+            );
+            this.withSaveState(() => {
+                this.chatUiStore.setMessageState(messageModel, ChatMessageState.Delivered, {
+                    id: messageModel.id,
+                    selections,
+                });
+                this.processBotAnswer(answer);
+                this.chatUiStore.resetError(ChatRunState.Started);
+            });
+        } catch (error: unknown) {
+            this.withSaveState(() => {
+                this.chatUiStore.setMessageState(messageModel, ChatMessageState.Failed, {
+                    selections,
+                });
+            });
+            if (error instanceof ChatError) {
+                this.setChatError('FailedToSendMessage', error);
+            } else {
+                this.setError(
+                    'FailedToSendMessage',
+                    'Send message',
+                    'Failed to send message',
+                    error
+                );
+            }
+        } finally {
+            this.chatUiStore.setAgentTyping(false);
+        }
+    }
+
+    private setSession(session?: Models.ISession) {
+        this.session = session;
+    }
+
+    private async ensureSession() {
+        if (this.session) {
+            return;
+        }
+        if (!this.sessionPromise) {
+            this.sessionPromise = this.api('postSession', ModelsUtils.createNewSessionModel());
+            const session = await this.sessionPromise;
+            this.setSession(session);
+            this.withSaveState(() => {
+                this.chatUiStore.resetError(ChatRunState.Started);
+            });
+        }
+        try {
+            await this.sessionPromise;
+        } finally {
+            this.sessionPromise = undefined;
+        }
+    }
+
+    private async api<
+        K extends keyof IChatbotApiClient,
+        Args extends Parameters<IChatbotApiClient[K]>,
+        Result extends ReturnType<IChatbotApiClient[K]>,
+    >(methodName: K, ...args: Args): Promise<Awaited<Result>> {
+        const method = this.chatbotApiClient[methodName];
+        if (method) {
+            try {
+                const result = (method as (...args: Args) => Result).call(
+                    this.chatbotApiClient,
+                    ...args
+                ) as Promise<Awaited<Result>>;
+                return result;
+            } finally {
+                this.restartTimers();
+            }
+        }
+        throw new Error(`Method '${methodName}' not found in the API.`);
+    }
+
+    private withSaveState<T>(action: () => T): T {
+        const result = action();
+        this.saveCurrentState();
+        return result;
+    }
+
+    private setChatError(code: string, error: ChatError) {
+        this.logError(code, error.message, error);
+        this.withSaveState(() => {
+            this.chatUiStore.setChatError(error);
+        });
+    }
+
+    private setError(code: string, title: string, message: string, error: any) {
+        if (axios.isCancel(error)) {
+            return;
+        }
+        this.logError(code, message, error);
+        this.withSaveState(() => {
+            this.chatUiStore.setError(message, error?.message ?? error);
+        });
+    }
+
+    private startRefreshingAuth() {
+        clearInterval(this.intervalId);
+        this.intervalId = setInterval(
+            () => {
+                this.chatbotApiClient
+                    .postRefreshAuthCookies()
+                    .then(res => res || clearInterval(this.intervalId));
+            },
+            60 * 60 * 1000
+        );
+    }
+
+    private initializeAbortController(): void {
+        this.abortController = new AbortController();
+        this.abortController.signal.addEventListener('abort', () => {
+            this.initializeAbortController();
+        });
+    }
+}

package/src/stores/chatbot-ui.store.ts

@@ -0,0 +1,82 @@
+import { injectable, symbolToken } from '@servicetitan/react-ioc';
+import { ChatUiEvent, ChatUiStore, IChatUiStore } from '@servicetitan/titan-chat-ui-common';
+import { action, makeObservable } from 'mobx';
+import { Models } from '../api-client';
+import { ChatbotCustomizations } from '../models';
+import { FilterStore } from './filter.store';
+
+export const CHATBOT_UI_STORE_TOKEN = symbolToken<IChatbotUiStore>('CHATBOT_UI_STORE_TOKEN');
+
+export enum ChatbotUiEvent {
+    eventChatbotSessionFeedback = 'eventChatbotSessionFeedback',
+    eventChatbotMessageFeedback = 'eventChatbotMessageFeedback',
+}
+
+export interface IChatbotUiStore extends IChatUiStore<ChatbotCustomizations> {
+    filterStore: FilterStore;
+    settings?: Models.IFrontendModel;
+    sendSessionFeedback: (
+        feedback: Models.IFeedback
+    ) => Promise<void | Models.ChatbotFeedbackState>;
+    sendMessageFeedback: (
+        message: Models.IBotMessageWithFeedback,
+        messageFeedback: Models.IFeedback
+    ) => Promise<void | Models.ChatbotFeedbackState>;
+}
+
+@injectable()
+export class ChatbotUiStore extends ChatUiStore<ChatbotCustomizations> implements IChatbotUiStore {
+    filterStore = new FilterStore();
+
+    constructor() {
+        super();
+        makeObservable(this);
+    }
+
+    override async recover() {
+        const errorCustomization = this.customizations.error;
+        if (errorCustomization?.recover) {
+            await errorCustomization.recover(this.error);
+        } else {
+            await super.recover();
+        }
+        this.triggerScroll();
+    }
+
+    override async sendMessageText(messageText: string) {
+        await this.restartTimers();
+        if (messageText.trim() === '') {
+            return;
+        }
+        const messageModel = this.addMessage(false, messageText);
+        await this.emitAsync(ChatUiEvent.eventMessageSend, messageModel, this.filterStore.export());
+    }
+
+    @action
+    setFilters(filterOptions: Models.IFrontendModel) {
+        this.filterStore.initFilters(filterOptions);
+    }
+
+    @action
+    async sendSessionFeedback(feedback: Models.Feedback) {
+        feedback.messageId = undefined; // Ensure messageId is not set for session feedback
+        const result = await this.emitAsync<Models.ChatbotFeedbackState>(
+            ChatbotUiEvent.eventChatbotSessionFeedback,
+            feedback
+        );
+        return result;
+    }
+
+    @action
+    async sendMessageFeedback(
+        message: Models.IBotMessageWithFeedback,
+        messageFeedback: Models.Feedback
+    ) {
+        messageFeedback.messageId = message.id;
+        const result = await this.emitAsync<Models.ChatbotFeedbackState>(
+            ChatbotUiEvent.eventChatbotMessageFeedback,
+            messageFeedback
+        );
+        return result;
+    }
+}