@servicetitan/titan-chatbot-api 4.1.1 → 4.2.0

package/src/api-client/titan-chat/native-client.ts

@@ -312,17 +312,142 @@ export class Client {
         }
         return Promise.resolve<Session>(null as any);
     }
+
+    /**
+     * @param start (optional)
+     * @param end (optional)
+     * @param x_Client_ID (optional)
+     * @return Success
+     */
+    transcripts(start: Date | undefined, end: Date | undefined, version: string, x_Client_ID: any | undefined, signal?: AbortSignal): Promise<ExportHistoryMessage[]> {
+        let url_ = this.baseUrl + "/api/v{version}/transcripts?";
+        if (version === undefined || version === null)
+            throw new Error("The parameter 'version' must be defined.");
+        url_ = url_.replace("{version}", encodeURIComponent("" + version));
+        if (start === null)
+            throw new Error("The parameter 'start' cannot be null.");
+        else if (start !== undefined)
+            url_ += "start=" + encodeURIComponent(start ? "" + start.toISOString() : "") + "&";
+        if (end === null)
+            throw new Error("The parameter 'end' cannot be null.");
+        else if (end !== undefined)
+            url_ += "end=" + encodeURIComponent(end ? "" + end.toISOString() : "") + "&";
+        url_ = url_.replace(/[?&]$/, "");
+
+        let options_: RequestInit = {
+            method: "GET",
+            signal,
+            headers: {
+                "X-Client-ID": x_Client_ID !== undefined && x_Client_ID !== null ? "" + x_Client_ID : "",
+                "Accept": "text/plain"
+            }
+        };
+
+        return this.http.fetch(url_, options_).then((_response: Response) => {
+            return this.processTranscripts(_response);
+        });
+    }
+
+    protected processTranscripts(response: Response): Promise<ExportHistoryMessage[]> {
+        const status = response.status;
+        let _headers: any = {}; if (response.headers && response.headers.forEach) { response.headers.forEach((v: any, k: any) => _headers[k] = v); };
+        if (status === 200) {
+            return response.text().then((_responseText) => {
+                let result200: any = null;
+                let resultData200 = _responseText === "" ? null : JSON.parse(_responseText, this.jsonParseReviver);
+                if (Array.isArray(resultData200)) {
+                    result200 = [] as any;
+                    for (let item of resultData200)
+                        result200!.push(ExportHistoryMessage.fromJS(item));
+                }
+                else {
+                    result200 = <any>null;
+                }
+                return result200;
+            });
+        } else if (status !== 200 && status !== 204) {
+            return response.text().then((_responseText) => {
+                return throwException("An unexpected server error occurred.", status, _responseText, _headers);
+            });
+        }
+        return Promise.resolve<ExportHistoryMessage[]>(null as any);
+    }
+
+    /**
+     * @param sessionId (optional)
+     * @param x_Client_ID (optional)
+     * @return Success
+     */
+    summary(sessionId: number | undefined, version: string, x_Client_ID: any | undefined, signal?: AbortSignal): Promise<string> {
+        let url_ = this.baseUrl + "/api/v{version}/transcripts/summary?";
+        if (version === undefined || version === null)
+            throw new Error("The parameter 'version' must be defined.");
+        url_ = url_.replace("{version}", encodeURIComponent("" + version));
+        if (sessionId === null)
+            throw new Error("The parameter 'sessionId' cannot be null.");
+        else if (sessionId !== undefined)
+            url_ += "sessionId=" + encodeURIComponent("" + sessionId) + "&";
+        url_ = url_.replace(/[?&]$/, "");
+
+        let options_: RequestInit = {
+            method: "GET",
+            signal,
+            headers: {
+                "X-Client-ID": x_Client_ID !== undefined && x_Client_ID !== null ? "" + x_Client_ID : "",
+                "Accept": "text/plain"
+            }
+        };
+
+        return this.http.fetch(url_, options_).then((_response: Response) => {
+            return this.processSummary(_response);
+        });
+    }
+
+    protected processSummary(response: Response): Promise<string> {
+        const status = response.status;
+        let _headers: any = {}; if (response.headers && response.headers.forEach) { response.headers.forEach((v: any, k: any) => _headers[k] = v); };
+        if (status === 200) {
+            return response.text().then((_responseText) => {
+                let result200: any = null;
+                let resultData200 = _responseText === "" ? null : JSON.parse(_responseText, this.jsonParseReviver);
+                result200 = resultData200 !== undefined ? resultData200 : <any>null;
+
+                return result200;
+            });
+        } else if (status !== 200 && status !== 204) {
+            return response.text().then((_responseText) => {
+                return throwException("An unexpected server error occurred.", status, _responseText, _headers);
+            });
+        }
+        return Promise.resolve<string>(null as any);
+    }
 }
 
+/** Chatbot response message. */
 export class BotMessage implements IBotMessage {
-    id!: number;
-    sessionId!: number;
+    /** Primary key. */
+    id?: number;
+    /** Session ID. Required in multi-turn conversations after the session is created. */
+    sessionId?: number | undefined;
+    timeStamp?: Date;
+    /** Chatbot answer. */
     answer!: string;
+    /** Ordered list of relevant Knowledge Base links. */
     scoredUrls?: ScoredUrl[] | undefined;
+    /** A value indicating one of the conditions:
+     - N - "none" or "normal", a successful response
+     - A - "agent", user wants to talk to a support agent
+     - C - "conversation", user attempted to continue a conversation in a single-turn message
+     - OI - "offensive input"
+     Client may handle these conditions in different ways. */
     guardFlag!: string;
+    /** Whether the answer is guardrailed, meaning TitanChatbot.Host.API.Models.BotMessage.GuardFlag is anything but "N". */
     isGuardrailed!: boolean;
+    /** Chatbot version number. */
     botVersion?: string | undefined;
+    /** AI model version. */
     modelVersion?: string | undefined;
+    /** Various metadata for diagnostics purposes. */
     meta?: any | undefined;
 
     constructor(data?: IBotMessage) {
@@ -338,6 +463,7 @@ export class BotMessage implements IBotMessage {
         if (_data) {
             this.id = _data["id"];
             this.sessionId = _data["sessionId"];
+            this.timeStamp = _data["timeStamp"] ? new Date(_data["timeStamp"].toString()) : <any>undefined;
             this.answer = _data["answer"];
             if (Array.isArray(_data["scoredUrls"])) {
                 this.scoredUrls = [] as any;
@@ -363,6 +489,7 @@ export class BotMessage implements IBotMessage {
         data = typeof data === 'object' ? data : {};
         data["id"] = this.id;
         data["sessionId"] = this.sessionId;
+        data["timeStamp"] = this.timeStamp ? this.timeStamp.toISOString() : <any>undefined;
         data["answer"] = this.answer;
         if (Array.isArray(this.scoredUrls)) {
             data["scoredUrls"] = [];
@@ -378,15 +505,31 @@ export class BotMessage implements IBotMessage {
     }
 }
 
+/** Chatbot response message. */
 export interface IBotMessage {
-    id: number;
-    sessionId: number;
+    /** Primary key. */
+    id?: number;
+    /** Session ID. Required in multi-turn conversations after the session is created. */
+    sessionId?: number | undefined;
+    timeStamp?: Date;
+    /** Chatbot answer. */
     answer: string;
+    /** Ordered list of relevant Knowledge Base links. */
     scoredUrls?: ScoredUrl[] | undefined;
+    /** A value indicating one of the conditions:
+     - N - "none" or "normal", a successful response
+     - A - "agent", user wants to talk to a support agent
+     - C - "conversation", user attempted to continue a conversation in a single-turn message
+     - OI - "offensive input"
+     Client may handle these conditions in different ways. */
     guardFlag: string;
+    /** Whether the answer is guardrailed, meaning TitanChatbot.Host.API.Models.BotMessage.GuardFlag is anything but "N". */
     isGuardrailed: boolean;
+    /** Chatbot version number. */
     botVersion?: string | undefined;
+    /** AI model version. */
     modelVersion?: string | undefined;
+    /** Various metadata for diagnostics purposes. */
     meta?: any | undefined;
 }
 
@@ -395,11 +538,125 @@ export enum Experience {
     MultiTurn = 2,
 }
 
+export class ExportHistoryMessage implements IExportHistoryMessage {
+    /** Primary key. */
+    id?: number;
+    /** Session ID. Required in multi-turn conversations after the session is created. */
+    sessionId?: number | undefined;
+    timeStamp?: Date;
+    userId?: number;
+    sessionStartTime?: Date;
+    sessionEndTime?: Date | undefined;
+    userName?: string | undefined;
+    userEmail?: string | undefined;
+    question?: string | undefined;
+    answer?: string | undefined;
+    messageType?: string | undefined;
+    salesforceCaseId?: string | undefined;
+    guardFlag?: string | undefined;
+    isGuardrailed?: boolean;
+    botVersion?: string | undefined;
+    metadata?: any | undefined;
+    feedback?: Feedback;
+    sessionFeedback?: Feedback;
+
+    constructor(data?: IExportHistoryMessage) {
+        if (data) {
+            for (var property in data) {
+                if (data.hasOwnProperty(property))
+                    (<any>this)[property] = (<any>data)[property];
+            }
+        }
+    }
+
+    init(_data?: any) {
+        if (_data) {
+            this.id = _data["id"];
+            this.sessionId = _data["sessionId"];
+            this.timeStamp = _data["timeStamp"] ? new Date(_data["timeStamp"].toString()) : <any>undefined;
+            this.userId = _data["userId"];
+            this.sessionStartTime = _data["sessionStartTime"] ? new Date(_data["sessionStartTime"].toString()) : <any>undefined;
+            this.sessionEndTime = _data["sessionEndTime"] ? new Date(_data["sessionEndTime"].toString()) : <any>undefined;
+            this.userName = _data["userName"];
+            this.userEmail = _data["userEmail"];
+            this.question = _data["question"];
+            this.answer = _data["answer"];
+            this.messageType = _data["messageType"];
+            this.salesforceCaseId = _data["salesforceCaseId"];
+            this.guardFlag = _data["guardFlag"];
+            this.isGuardrailed = _data["isGuardrailed"];
+            this.botVersion = _data["botVersion"];
+            this.metadata = _data["metadata"];
+            this.feedback = _data["feedback"] ? Feedback.fromJS(_data["feedback"]) : <any>undefined;
+            this.sessionFeedback = _data["sessionFeedback"] ? Feedback.fromJS(_data["sessionFeedback"]) : <any>undefined;
+        }
+    }
+
+    static fromJS(data: any): ExportHistoryMessage {
+        data = typeof data === 'object' ? data : {};
+        let result = new ExportHistoryMessage();
+        result.init(data);
+        return result;
+    }
+
+    toJSON(data?: any) {
+        data = typeof data === 'object' ? data : {};
+        data["id"] = this.id;
+        data["sessionId"] = this.sessionId;
+        data["timeStamp"] = this.timeStamp ? this.timeStamp.toISOString() : <any>undefined;
+        data["userId"] = this.userId;
+        data["sessionStartTime"] = this.sessionStartTime ? this.sessionStartTime.toISOString() : <any>undefined;
+        data["sessionEndTime"] = this.sessionEndTime ? this.sessionEndTime.toISOString() : <any>undefined;
+        data["userName"] = this.userName;
+        data["userEmail"] = this.userEmail;
+        data["question"] = this.question;
+        data["answer"] = this.answer;
+        data["messageType"] = this.messageType;
+        data["salesforceCaseId"] = this.salesforceCaseId;
+        data["guardFlag"] = this.guardFlag;
+        data["isGuardrailed"] = this.isGuardrailed;
+        data["botVersion"] = this.botVersion;
+        data["metadata"] = this.metadata;
+        data["feedback"] = this.feedback ? this.feedback.toJSON() : <any>undefined;
+        data["sessionFeedback"] = this.sessionFeedback ? this.sessionFeedback.toJSON() : <any>undefined;
+        return data;
+    }
+}
+
+export interface IExportHistoryMessage {
+    /** Primary key. */
+    id?: number;
+    /** Session ID. Required in multi-turn conversations after the session is created. */
+    sessionId?: number | undefined;
+    timeStamp?: Date;
+    userId?: number;
+    sessionStartTime?: Date;
+    sessionEndTime?: Date | undefined;
+    userName?: string | undefined;
+    userEmail?: string | undefined;
+    question?: string | undefined;
+    answer?: string | undefined;
+    messageType?: string | undefined;
+    salesforceCaseId?: string | undefined;
+    guardFlag?: string | undefined;
+    isGuardrailed?: boolean;
+    botVersion?: string | undefined;
+    metadata?: any | undefined;
+    feedback?: Feedback;
+    sessionFeedback?: Feedback;
+}
+
+/** User feedback for chatbot interaction. */
 export class Feedback implements IFeedback {
+    /** A link to correct information according to user. */
     linkUrl?: string | undefined;
+    /** User typed input. */
     description?: string | undefined;
+    /** Session ID for session feedback. */
     sessionId?: number | undefined;
+    /** Message ID for message feedback. */
     messageId?: number | undefined;
+    /** Selected options. */
     options?: FeedbackOptions[] | undefined;
     rating?: FeedbackRatings;
 
@@ -450,11 +707,17 @@ export class Feedback implements IFeedback {
     }
 }
 
+/** User feedback for chatbot interaction. */
 export interface IFeedback {
+    /** A link to correct information according to user. */
     linkUrl?: string | undefined;
+    /** User typed input. */
     description?: string | undefined;
+    /** Session ID for session feedback. */
     sessionId?: number | undefined;
+    /** Message ID for message feedback. */
     messageId?: number | undefined;
+    /** Selected options. */
     options?: FeedbackOptions[] | undefined;
     rating?: FeedbackRatings;
 }
@@ -512,10 +775,14 @@ export interface IFrontendModel {
     options: Option;
 }
 
+/** A meaningful selectable option or a parent node for other options. */
 export class Option implements IOption {
+    /** Identifier key. */
     key!: string;
+    /** Display name. */
     displayName?: string | undefined;
     type!: OptionType;
+    /** Child options down the hierarchy. */
     subOptions?: Option[] | undefined;
 
     constructor(data?: IOption) {
@@ -561,10 +828,14 @@ export class Option implements IOption {
     }
 }
 
+/** A meaningful selectable option or a parent node for other options. */
 export interface IOption {
+    /** Identifier key. */
     key: string;
+    /** Display name. */
     displayName?: string | undefined;
     type: OptionType;
+    /** Child options down the hierarchy. */
     subOptions?: Option[] | undefined;
 }
 
@@ -574,6 +845,7 @@ export enum OptionType {
     Selectable = 2,
 }
 
+/** A scored link to Knowledge Base article. */
 export class ScoredUrl implements IScoredUrl {
     url?: string | undefined;
     score?: number;
@@ -612,14 +884,18 @@ export class ScoredUrl implements IScoredUrl {
     }
 }
 
+/** A scored link to Knowledge Base article. */
 export interface IScoredUrl {
     url?: string | undefined;
     score?: number;
     title?: string | undefined;
 }
 
+/** User-selected values from available options. Hierarchy of TitanChatbot.Host.API.Models.Selections must match hierarchy of TitanChatbot.Host.API.Models.Option. */
 export class Selections implements ISelections {
+    /** Selected values. */
     values?: string[] | undefined;
+    /** Child selections down the hierarchy. */
     subOptions?: { [key: string]: Selections; } | undefined;
 
     constructor(data?: ISelections) {
@@ -673,13 +949,19 @@ export class Selections implements ISelections {
     }
 }
 
+/** User-selected values from available options. Hierarchy of TitanChatbot.Host.API.Models.Selections must match hierarchy of TitanChatbot.Host.API.Models.Option. */
 export interface ISelections {
+    /** Selected values. */
     values?: string[] | undefined;
+    /** Child selections down the hierarchy. */
     subOptions?: { [key: string]: Selections; } | undefined;
 }
 
+/** Series of chatbot exchanges making a conversation. */
 export class Session implements ISession {
+    /** Primary key. */
     id?: number;
+    /** Arbitrary data to be stored in session. */
     data?: { [key: string]: string; } | undefined;
 
     constructor(data?: ISession) {
@@ -725,16 +1007,26 @@ export class Session implements ISession {
     }
 }
 
+/** Series of chatbot exchanges making a conversation. */
 export interface ISession {
+    /** Primary key. */
     id?: number;
+    /** Arbitrary data to be stored in session. */
     data?: { [key: string]: string; } | undefined;
 }
 
+/** User request message. */
 export class UserMessage implements IUserMessage {
+    /** Primary key. */
+    id?: number;
+    /** Session ID. Required in multi-turn conversations after the session is created. */
     sessionId?: number | undefined;
+    timeStamp?: Date;
+    /** User question. */
     question!: string;
     experience!: Experience;
     selections?: Selections;
+    /** Additional context. */
     context?: { [key: string]: any; } | undefined;
 
     constructor(data?: IUserMessage) {
@@ -748,7 +1040,9 @@ export class UserMessage implements IUserMessage {
 
     init(_data?: any) {
         if (_data) {
+            this.id = _data["id"];
             this.sessionId = _data["sessionId"];
+            this.timeStamp = _data["timeStamp"] ? new Date(_data["timeStamp"].toString()) : <any>undefined;
             this.question = _data["question"];
             this.experience = _data["experience"];
             this.selections = _data["selections"] ? Selections.fromJS(_data["selections"]) : <any>undefined;
@@ -771,7 +1065,9 @@ export class UserMessage implements IUserMessage {
 
     toJSON(data?: any) {
         data = typeof data === 'object' ? data : {};
+        data["id"] = this.id;
         data["sessionId"] = this.sessionId;
+        data["timeStamp"] = this.timeStamp ? this.timeStamp.toISOString() : <any>undefined;
         data["question"] = this.question;
         data["experience"] = this.experience;
         data["selections"] = this.selections ? this.selections.toJSON() : <any>undefined;
@@ -786,11 +1082,18 @@ export class UserMessage implements IUserMessage {
     }
 }
 
+/** User request message. */
 export interface IUserMessage {
+    /** Primary key. */
+    id?: number;
+    /** Session ID. Required in multi-turn conversations after the session is created. */
     sessionId?: number | undefined;
+    timeStamp?: Date;
+    /** User question. */
     question: string;
     experience: Experience;
     selections?: Selections;
+    /** Additional context. */
     context?: { [key: string]: any; } | undefined;
 }
 

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

@@ -267,14 +267,20 @@ describe('[ChatbotUiBackendStore]', () => {
                 });
 
             test('should start session', async () => {
+                const spyGetData = jest.spyOn(store, 'getSessionData').mockResolvedValue({
+                    defaultData: 'defaultData',
+                });
                 chatbotApi.postSession.mockResolvedValue(createSession(1));
                 const { session } = await runChatUiEventListener(store.handleSessionStart, [
                     { custom: 'data' },
                 ]);
 
+                expect(spyGetData).toHaveBeenCalled();
                 expect(session).toEqual(createSession(1));
                 expect(chatbotApi.postSession).toHaveBeenCalledWith(
-                    { custom: 'data' },
+                    {
+                        data: { custom: 'data', defaultData: 'defaultData' },
+                    },
                     expect.any(AbortSignal)
                 );
             });
@@ -290,7 +296,9 @@ describe('[ChatbotUiBackendStore]', () => {
                 expect(r2.session).toEqual(createSession(1));
                 expect(chatbotApi.postSession).toHaveBeenCalledTimes(1);
                 expect(chatbotApi.postSession).toHaveBeenCalledWith(
-                    { custom: 'data' },
+                    {
+                        data: { custom: 'data' },
+                    },
                     expect.any(AbortSignal)
                 );
             });

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

@@ -65,7 +65,7 @@ describe('[ChatbotUiStore]', () => {
                     resolve(ModelsMocks.mockSession());
                 }
             );
-            const sessionData = ModelsMocks.mockSession({ id: 1 });
+            const sessionData = { customData: 'customData' };
             const session = await store.startSession(sessionData, true);
             expect(session).toBeDefined();
             expect(session?.id).toBe(1);

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

@@ -29,6 +29,7 @@ export interface IChatbotUiBackendStore extends IChatUiBackendStore {
     saveCurrentState: () => void;
     deleteFromSessionStorage: () => void;
     restoreChatSession: () => void;
+    getSessionData: () => Promise<Models.ISession['data'] | undefined>;
     restartTimers: () => void;
 }
 
@@ -123,7 +124,7 @@ export class ChatbotUiBackendStore extends InitializeStore implements IChatbotUi
 
     handleSessionStart: ChatUiEventListener<{
         session?: Models.ISession;
-    }> = async (resolve, _, sessionData?: Models.ISession, forceRecreate?: boolean) => {
+    }> = async (resolve, _, sessionData?: Models.ISession['data'], forceRecreate?: boolean) => {
         const session = await this.startSession(sessionData, forceRecreate);
         resolve({
             session,
@@ -206,6 +207,10 @@ export class ChatbotUiBackendStore extends InitializeStore implements IChatbotUi
         });
     };
 
+    async getSessionData(): Promise<Models.ISession['data'] | undefined> {
+        return Promise.resolve(undefined);
+    }
+
     restoreChatSession() {}
 
     saveCurrentState() {}
@@ -325,7 +330,7 @@ export class ChatbotUiBackendStore extends InitializeStore implements IChatbotUi
         this.session = session;
     }
 
-    private async startSession(sessionData?: Models.ISession, forceRecreate = false) {
+    private async startSession(sessionData?: Models.ISession['data'], forceRecreate = false) {
         if (forceRecreate) {
             this.reset();
             this.sessionPromise = undefined;
@@ -334,11 +339,17 @@ export class ChatbotUiBackendStore extends InitializeStore implements IChatbotUi
             return this.session;
         }
         if (!this.sessionPromise) {
-            this.sessionPromise = this.api(
-                'postSession',
-                ModelsUtils.createNewSessionModel(sessionData),
-                this.abortController.signal
-            );
+            this.sessionPromise = (async () => {
+                let data = await this.getSessionData();
+                if (sessionData) {
+                    data = { ...data, ...sessionData };
+                }
+                return this.api(
+                    'postSession',
+                    ModelsUtils.createNewSessionModel({ data }),
+                    this.abortController.signal
+                );
+            })();
             const session = await this.sessionPromise;
             this.setSession(session);
             this.withSaveState(() => {

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

@@ -18,7 +18,7 @@ export interface IChatbotUiStore extends IChatUiStore<ChatbotCustomizations> {
     settings?: Models.IFrontendModel;
     setFilters: (filterOptions: Models.IFrontendModel) => void;
     startSession: (
-        sessionData?: Models.ISession,
+        sessionData?: Models.ISession['data'],
         forceRecreate?: boolean
     ) => Promise<undefined | Models.Session>;
     sendSessionFeedback: (
@@ -64,7 +64,7 @@ export class ChatbotUiStore extends ChatUiStore<ChatbotCustomizations> implement
     }
 
     @action
-    async startSession(sessionData?: Models.ISession, forceRecreate?: boolean) {
+    async startSession(sessionData?: Models.ISession['data'], forceRecreate?: boolean) {
         const result = await this.emitAsync<Models.Session>(
             ChatbotUiEvent.eventChatbotSessionStart,
             sessionData,