@servicetitan/titan-chatbot-api 3.0.0

package/package.json

@@ -0,0 +1,45 @@
+{
+    "name": "@servicetitan/titan-chatbot-api",
+    "version": "3.0.0",
+    "description": "Chatbot client API package",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/servicetitan/titan-chatbot-client",
+        "directory": "packages/titan-chatbot-api"
+    },
+    "main": "./dist/index.js",
+    "typings": "./dist/index.d.ts",
+    "exports": {
+        ".": "./dist/index.js"
+    },
+    "scripts": {
+        "publish:local": "yalc publish",
+        "push:local": "yalc push"
+    },
+    "dependencies": {
+        "@servicetitan/titan-chat-ui-common": "^3.0.0",
+        "lodash": "^4.17.21",
+        "nanoid": "^5.1.5"
+    },
+    "peerDependencies": {
+        "@servicetitan/log-service": ">=27",
+        "@servicetitan/react-ioc": ">=24",
+        "axios": ">=0.28.0",
+        "mobx": ">=6",
+        "mobx-react": ">=9",
+        "mobx-utils": ">=6",
+        "react": "^18",
+        "react-dom": "^18"
+    },
+    "keywords": [
+        "ServiceTitan"
+    ],
+    "author": "Alexander Yarmolchuk",
+    "publishConfig": {
+        "access": "public"
+    },
+    "cli": {
+        "webpack": false
+    },
+    "gitHead": "5c9c88b8b55c56cacefef6b8452e9367c31c9ad3"
+}

package/src/api-client/__mocks__/chatbot-api-client.mock.ts

@@ -0,0 +1,11 @@
+import { IChatbotApiClient } from '..';
+
+export class ChatbotApiClientMock implements IChatbotApiClient {
+    postFeedback = jest.fn();
+    postMessage = jest.fn();
+    getOptions = jest.fn();
+    postSession = jest.fn();
+    patchSession = jest.fn();
+    deleteSession = jest.fn();
+    postRefreshAuthCookies = jest.fn();
+}

package/src/api-client/base/chatbot-api-client.ts

@@ -0,0 +1,33 @@
+import { symbolToken } from '@servicetitan/react-ioc';
+import { Models } from '..';
+
+/**
+ * Token for injecting the chatbot client settings for proper initialization of the client.
+ */
+export const CHATBOT_CLIENT_SETTINGS =
+    symbolToken<IChatbotClientSettings>('CHATBOT_CLIENT_SETTINGS');
+
+/**
+ * Token for injecting the chatbot API client.
+ */
+export const CHATBOT_API_CLIENT = symbolToken<IChatbotApiClient>('CHATBOT_API_CLIENT');
+
+type Constructor = abstract new (...args: any) => any;
+type ConstructorParametersFactory<T extends Constructor> = () => Required<ConstructorParameters<T>>;
+type ParametersFromFactory<T extends Constructor> = ReturnType<ConstructorParametersFactory<T>>;
+export type FirstParameterType<T extends Constructor> =
+    ParametersFromFactory<T> extends [infer P1, ...any[]] ? Exclude<P1, undefined> : undefined;
+export type SecondParameterType<T extends Constructor> =
+    ParametersFromFactory<T> extends [any, infer P2, ...any[]] ? Exclude<P2, undefined> : undefined;
+
+export interface IChatbotClientSettings {}
+
+export interface IChatbotApiClient {
+    postFeedback(body: Models.IFeedback, abortSignal?: AbortSignal): Promise<Models.Feedback>;
+    postMessage(body: Models.IUserMessage, abortSignal?: AbortSignal): Promise<Models.BotMessage>;
+    getOptions(abortSignal?: AbortSignal): Promise<Models.FrontendModel>;
+    postSession(body: Models.ISession, abortSignal?: AbortSignal): Promise<Models.Session>;
+    patchSession(body: Models.ISession, abortSignal?: AbortSignal): Promise<Models.Session>;
+    deleteSession(body: Models.ISession, abortSignal?: AbortSignal): Promise<Models.Session>;
+    postRefreshAuthCookies(abortSignal?: AbortSignal): Promise<boolean>; // TODO: This is a temporary method which will be removed in the future (ticket is created) and implemented in the internal chatbot client
+}

package/src/api-client/help-center/__tests__/converter-from-models.test.ts

@@ -0,0 +1,41 @@
+import { expect } from '@jest/globals';
+import { Models } from '../..';
+import { ConverterFromModels } from '../converter-from-models';
+
+describe('ConverterFromModels', () => {
+    test('convertFilters', () => {
+        expect(ConverterFromModels.convertFilters()).toBeUndefined();
+        expect(ConverterFromModels.convertFilters({})).toBeUndefined();
+        expect(
+            ConverterFromModels.convertFilters({
+                subOptions: {
+                    ProductAreas: { values: [] },
+                },
+            } as unknown as Models.ISelections)
+        ).toEqual({
+            productAreas: [],
+        });
+        expect(
+            ConverterFromModels.convertFilters({
+                subOptions: {
+                    ProductAreas: { values: ['area1', 'area2'] },
+                },
+            } as unknown as Models.ISelections)
+        ).toEqual({
+            productAreas: ['area1', 'area2'],
+        });
+        expect(
+            ConverterFromModels.convertFilters({
+                subOptions: {
+                    Sources: { values: ['source1', 'source2'] },
+                    ContentTypes: { values: ['type1'] },
+                    ProductAreas: { values: ['area1', 'area2'] },
+                },
+            } as unknown as Models.ISelections)
+        ).toEqual({
+            sources: ['source1', 'source2'],
+            contentTypes: ['type1'],
+            productAreas: ['area1', 'area2'],
+        });
+    });
+});

package/src/api-client/help-center/__tests__/converter-to-models.test.ts

@@ -0,0 +1,89 @@
+import { expect } from '@jest/globals';
+import { Models } from '../..';
+import { ConverterToModels } from '../converter-to-models';
+// eslint-disable-next-line no-restricted-imports
+import * as HelpCenterClient from '../native-client';
+
+describe('ConverterToModels', () => {
+    test('convertFilterOptions', () => {
+        expect(ConverterToModels.convertFilterOptions({})).toEqual(
+            new Models.FrontendModel({
+                options: new Models.Option({
+                    key: 'help-center-filters-root',
+                    displayName: 'help-center-filters-root',
+                    type: Models.OptionType.Group,
+                    subOptions: [],
+                }),
+            })
+        );
+
+        expect(
+            ConverterToModels.convertFilterOptions({
+                sources: [
+                    new HelpCenterClient.FilterOption({
+                        id: 'source1',
+                        displayName: 'Source 1',
+                    }),
+                    new HelpCenterClient.FilterOption({
+                        id: 'source2',
+                        displayName: 'Source 2',
+                    }),
+                ],
+                productAreas: [
+                    new HelpCenterClient.FilterOption({
+                        id: 'area1',
+                        displayName: 'Area 1',
+                    }),
+                    new HelpCenterClient.FilterOption({
+                        id: 'area2',
+                        displayName: 'Area 2',
+                    }),
+                ],
+            })
+        ).toEqual(
+            new Models.FrontendModel({
+                options: new Models.Option({
+                    key: 'help-center-filters-root',
+                    displayName: 'help-center-filters-root',
+                    type: Models.OptionType.Group,
+                    subOptions: [
+                        new Models.Option({
+                            key: 'Sources',
+                            displayName: 'Sources',
+                            type: Models.OptionType.Group,
+                            subOptions: [
+                                new Models.Option({
+                                    key: 'source1',
+                                    displayName: 'Source 1',
+                                    type: Models.OptionType.Selectable,
+                                }),
+                                new Models.Option({
+                                    key: 'source2',
+                                    displayName: 'Source 2',
+                                    type: Models.OptionType.Selectable,
+                                }),
+                            ],
+                        }),
+                        new Models.Option({
+                            key: 'ProductAreas',
+                            displayName: 'Product Areas',
+                            type: Models.OptionType.Group,
+                            subOptions: [
+                                new Models.Option({
+                                    key: 'area1',
+                                    displayName: 'Area 1',
+                                    type: Models.OptionType.Selectable,
+                                }),
+                                new Models.Option({
+                                    key: 'area2',
+                                    displayName: 'Area 2',
+                                    type: Models.OptionType.Selectable,
+                                }),
+                            ],
+                        }),
+                    ],
+                }),
+            })
+        );
+    });
+});

package/src/api-client/help-center/chatbot-api-client.ts

@@ -0,0 +1,107 @@
+import { inject, injectable } from '@servicetitan/react-ioc';
+import { Models } from '..';
+import {
+    CHATBOT_CLIENT_SETTINGS,
+    FirstParameterType,
+    IChatbotApiClient,
+    IChatbotClientSettings,
+    SecondParameterType,
+} from '../base/chatbot-api-client';
+import { ConverterFromModels } from './converter-from-models';
+import { ConverterToModels } from './converter-to-models';
+// eslint-disable-next-line no-restricted-imports
+import { ChatClient } from './native-client';
+
+/**
+ * Settings for the chatbot client, which includes a factory for constructor parameters, and additional settings
+ * like instance and area which are used in the API calls.
+ */
+export interface IChatbotClientSettingsHelpCenter extends IChatbotClientSettings {
+    constructorParametersFactory: () => {
+        baseUrl?: FirstParameterType<typeof ChatClient>;
+        axiosInstance?: SecondParameterType<typeof ChatClient>;
+    };
+    instance: string;
+    area: string;
+}
+
+/**
+ * Client adapter adopts the generated titan chatbot client to the generic IChatbotApiClient interface.
+ */
+@injectable()
+export class ChatbotApiClient implements IChatbotApiClient {
+    private readonly client: ChatClient;
+
+    constructor(
+        @inject(CHATBOT_CLIENT_SETTINGS)
+        private readonly chatbotApiClientSettings: IChatbotClientSettingsHelpCenter
+    ) {
+        const { axiosInstance, baseUrl } =
+            this.chatbotApiClientSettings.constructorParametersFactory();
+        this.client = new ChatClient(baseUrl, axiosInstance);
+    }
+
+    async postRefreshAuthCookies(abortSignal?: AbortSignal) {
+        const result = await this.client.refreshAuthCookies(abortSignal);
+        return Boolean(result);
+    }
+
+    async postFeedback(body: Models.Feedback, abortSignal?: AbortSignal) {
+        if (body?.messageId) {
+            await this.client.sendBotMessageFeedback(
+                body.sessionId,
+                body.messageId,
+                ConverterFromModels.convertMessageFeedback(body),
+                abortSignal
+            );
+            return body;
+        } else if (body?.sessionId) {
+            await this.client.sendSessionFeedback(
+                body.sessionId,
+                ConverterFromModels.convertSessionFeedback(body),
+                abortSignal
+            );
+            return body;
+        }
+        throw new Error('Feedback must contain either messageId or sessionId');
+    }
+
+    async postMessage(body: Models.UserMessage, abortSignal?: AbortSignal) {
+        const hcMessage = ConverterFromModels.convertUserMessage(
+            body,
+            this.chatbotApiClientSettings.area
+        );
+        const botMessage = await this.client.sendUserMessage(hcMessage, abortSignal);
+        return ConverterToModels.convertBotMessage(botMessage);
+    }
+
+    async getOptions(abortSignal?: AbortSignal): Promise<Models.FrontendModel> {
+        const filterOptions = await this.client.getFilterOptions(abortSignal);
+        return ConverterToModels.convertFilterOptions(filterOptions);
+    }
+
+    async postSession(body: Models.Session, abortSignal?: AbortSignal) {
+        body.data = body.data ?? {};
+        body.data.instance ??= this.chatbotApiClientSettings.instance;
+        const hcSession = ConverterFromModels.convertSession(body);
+        const newSession = await this.client.createSession(hcSession.source!, abortSignal);
+        return ConverterToModels.convertSession(newSession);
+    }
+
+    async patchSession(body: Models.Session, abortSignal?: AbortSignal) {
+        const session = ConverterFromModels.convertSession(body);
+        await this.client.updateSessionCategory(
+            session.source?.category,
+            session.source?.subCategory,
+            session.id,
+            abortSignal
+        );
+        return body;
+    }
+
+    async deleteSession(body: Models.Session, abortSignal?: AbortSignal) {
+        const session = ConverterFromModels.convertSession(body);
+        await this.client.closeSession(session.id, abortSignal);
+        return body;
+    }
+}

package/src/api-client/help-center/converter-from-models.ts

@@ -0,0 +1,132 @@
+import { Models } from '..';
+// eslint-disable-next-line no-restricted-imports
+import * as HelpCenterModels from './native-client';
+
+export class ConverterFromModels {
+    static convertSession(session: Models.ISession): HelpCenterModels.ChatbotSession {
+        const data = session.data;
+        return new HelpCenterModels.ChatbotSession({
+            id: session.id,
+            createdUtc: data?.createdUtc ? new Date(data.createdUtc) : undefined,
+            closedUtc: data?.closedUtc ? new Date(data.closedUtc) : undefined,
+            botId: data?.botId,
+            source: new HelpCenterModels.SessionSource({
+                instance: data?.instance,
+                category: data?.category,
+                subCategory: data?.subCategory,
+            }),
+        });
+    }
+
+    static convertUserMessage(
+        userMessage: Models.IUserMessage,
+        area: string
+    ): HelpCenterModels.UserMessage {
+        const filters =
+            ConverterFromModels.convertFilters(userMessage.selections) ??
+            new HelpCenterModels.FilterSelections({});
+        const data: HelpCenterModels.IUserMessage = {
+            sessionId: userMessage.sessionId,
+            text: userMessage.question,
+            source: new HelpCenterModels.MessageSource({
+                area,
+            }),
+            ...(filters ? { filters } : undefined),
+        };
+        return HelpCenterModels.UserMessage.fromJS(data);
+    }
+
+    static convertFilters(
+        selections?: Models.ISelections
+    ): HelpCenterModels.FilterSelections | undefined {
+        if (!selections?.subOptions || !Object.keys(selections.subOptions).length) {
+            return;
+        }
+        const data: HelpCenterModels.IFilterSelections = {};
+        const sources = selections.subOptions.Sources;
+        const contentTypes = selections.subOptions.ContentTypes;
+        const productAreas = selections.subOptions.ProductAreas;
+        if (sources?.values) {
+            data.sources = sources.values;
+        }
+        if (contentTypes?.values) {
+            data.contentTypes = contentTypes.values;
+        }
+        if (productAreas?.values) {
+            data.productAreas = productAreas.values;
+        }
+        return new HelpCenterModels.FilterSelections(data);
+    }
+
+    static convertSessionFeedback(feedback: Models.IFeedback): HelpCenterModels.SessionFeedback {
+        return new HelpCenterModels.SessionFeedback({
+            description: feedback.description,
+            rating: ConverterFromModels.convertSessionFeedbackRating(feedback.rating),
+        });
+    }
+
+    static convertMessageFeedback(feedback: Models.IFeedback): HelpCenterModels.MessageFeedback {
+        return new HelpCenterModels.MessageFeedback({
+            linkUrl: feedback.linkUrl,
+            description: feedback.description,
+            rating: ConverterFromModels.convertMessageFeedbackRating(feedback.rating),
+            options: ConverterFromModels.convertFeedbackOptions(feedback.options),
+        });
+    }
+
+    static convertFeedbackOptions(
+        feedbackOptions?: Models.FeedbackOptions[]
+    ): HelpCenterModels.FeedbackOptions[] | undefined {
+        if (feedbackOptions === undefined) {
+            return;
+        }
+        return feedbackOptions.map(feedbackOption => {
+            switch (feedbackOption) {
+                case Models.FeedbackOptions.Incomplete:
+                    return HelpCenterModels.FeedbackOptions.Incomplete;
+                case Models.FeedbackOptions.Incorrect:
+                    return HelpCenterModels.FeedbackOptions.Incorrect;
+                case Models.FeedbackOptions.Other:
+                    return HelpCenterModels.FeedbackOptions.Other;
+                case Models.FeedbackOptions.Unclear:
+                    return HelpCenterModels.FeedbackOptions.Unclear;
+                case Models.FeedbackOptions.Unrelated:
+                    return HelpCenterModels.FeedbackOptions.Unrelated;
+                default:
+                    return HelpCenterModels.FeedbackOptions.Other;
+            }
+        });
+    }
+
+    static convertMessageFeedbackRating(
+        feedbackRatings?: Models.FeedbackRatings
+    ): HelpCenterModels.MessageFeedbackRatings | undefined {
+        if (feedbackRatings === undefined) {
+            return;
+        }
+        switch (feedbackRatings) {
+            case Models.FeedbackRatings.ThumbsDown:
+                return HelpCenterModels.MessageFeedbackRatings.ThumbsDown;
+            case Models.FeedbackRatings.GuardrailFeedback:
+                return HelpCenterModels.MessageFeedbackRatings.GuardrailFeedback;
+            case Models.FeedbackRatings.ThumbsUp:
+                return HelpCenterModels.MessageFeedbackRatings.ThumbsUp;
+        }
+    }
+
+    static convertSessionFeedbackRating(
+        feedbackRatings?: Models.FeedbackRatings
+    ): HelpCenterModels.SessionFeedbackRatings | undefined {
+        if (feedbackRatings === undefined) {
+            return;
+        }
+        switch (feedbackRatings) {
+            case Models.FeedbackRatings.ThumbsDown:
+                return HelpCenterModels.SessionFeedbackRatings.ThumbsDown;
+            case Models.FeedbackRatings.ThumbsUp:
+                return HelpCenterModels.SessionFeedbackRatings.ThumbsUp;
+            default:
+                return HelpCenterModels.SessionFeedbackRatings.ThumbsDown;
+        }
+    }
+}

package/src/api-client/help-center/converter-to-models.ts

@@ -0,0 +1,124 @@
+import { Models } from '..';
+// eslint-disable-next-line no-restricted-imports
+import * as HelpCenterClient from './native-client';
+
+export class ConverterToModels {
+    static convertSession(session: HelpCenterClient.IChatbotSession): Models.Session {
+        return new Models.Session({
+            id: session.id,
+            data: ConverterToModels.convertSessionData(session),
+        });
+    }
+
+    static convertSessionData(session: HelpCenterClient.IChatbotSession): Models.Session['data'] {
+        const data: Models.Session['data'] = {};
+        if (session.createdUtc) {
+            data.createdUtc = session.createdUtc.toISOString();
+        }
+        if (session.closedUtc) {
+            data.closedUtc = session.closedUtc.toISOString();
+        }
+        if (session.botId) {
+            data.botId = session.botId;
+        }
+        if (session.source) {
+            if (session.source.instance) {
+                data.instance = session.source.instance;
+            }
+            if (session.source.category) {
+                data.category = session.source.category;
+            }
+            if (session.source.subCategory) {
+                data.subCategory = session.source.subCategory;
+            }
+        }
+        return Object.keys(data).length > 0 ? data : undefined;
+    }
+
+    /**
+     * Convert HC filters into single-level frontend model.
+     */
+    static convertFilterOptions(options: HelpCenterClient.IFilterOptions): Models.FrontendModel {
+        const createFilterOption = (key: string, displayName?: string): Models.Option => {
+            return new Models.Option({
+                key,
+                displayName: displayName ?? key,
+                type: Models.OptionType.Selectable,
+            });
+        };
+        const createFilterOptions = (options?: HelpCenterClient.IFilterOption[]) =>
+            options?.map(x => createFilterOption(x.id ?? '', x.displayName));
+        const createFilter = (
+            key: string,
+            displayName?: string,
+            subOptions?: Models.Option[]
+        ): Models.Option => {
+            return new Models.Option({
+                key,
+                displayName: displayName ?? key,
+                type: Models.OptionType.Group,
+                subOptions,
+            });
+        };
+
+        const subOptions: Models.Option[] = [];
+        if (options.sources?.length) {
+            subOptions.push(
+                createFilter('Sources', 'Sources', createFilterOptions(options.sources))
+            );
+        }
+        if (options.contentTypes?.length) {
+            subOptions.push(
+                createFilter(
+                    'ContentTypes',
+                    'Content Types',
+                    createFilterOptions(options.contentTypes)
+                )
+            );
+        }
+        if (options.productAreas?.length) {
+            subOptions.push(
+                createFilter(
+                    'ProductAreas',
+                    'Product Areas',
+                    createFilterOptions(options.productAreas)
+                )
+            );
+        }
+        return new Models.FrontendModel({
+            options: new Models.Option({
+                key: 'help-center-filters-root',
+                displayName: 'help-center-filters-root',
+                type: Models.OptionType.Group,
+                subOptions,
+            }),
+        });
+    }
+
+    static convertBotMessage(botMessage: HelpCenterClient.IBotMessage): Models.BotMessage {
+        return new Models.BotMessage({
+            id: botMessage.id ?? 0,
+            answer: botMessage.text ?? '',
+            isGuardrailed: botMessage.isGuardrailed ?? false,
+            guardFlag: botMessage.guardFlag ?? 'N',
+            sessionId: botMessage.sessionId ?? 0,
+            scoredUrls: ConverterToModels.convertScoredUrls(botMessage.scoredUrls),
+        });
+    }
+
+    static convertScoredUrls(
+        scoredUrls?: HelpCenterClient.IScoredUrl[]
+    ): Models.ScoredUrl[] | undefined {
+        if (scoredUrls === undefined) {
+            return;
+        }
+        return scoredUrls.map(
+            url =>
+                new Models.ScoredUrl({
+                    url: url.url,
+                    score: url.score,
+                    title: url.title,
+                })
+        );
+    }
+}

package/src/api-client/help-center/index.ts

@@ -0,0 +1 @@
+export { ChatbotApiClient, IChatbotClientSettingsHelpCenter } from './chatbot-api-client';