@servicetitan/titan-chat-ui-common 3.0.0

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

@@ -0,0 +1,539 @@
+import { EventEmitter } from 'events';
+import { injectable, symbolToken } from '@servicetitan/react-ioc';
+import { action, computed, makeObservable, observable, runInAction } from 'mobx';
+import { nanoid } from 'nanoid';
+import {
+    ChatConfiguration,
+    ChatCustomizations,
+    ChatEndReason,
+    ChatError,
+    ChatErrorOptions,
+    ChatMessageModelBase,
+    ChatMessageModelFile,
+    ChatMessageModelText,
+    ChatMessageModelTimeout,
+    ChatMessageModelWelcome,
+    ChatMessageState,
+    ChatParticipantIcon,
+    ChatParticipantModel,
+    ChatRunState,
+    ChatTimer,
+} from '../models';
+import { FileDescriptor } from '../models/file-descriptor';
+
+export const symbolAgent = Symbol('SupportChatAgent');
+export const symbolUser = Symbol('SupportChatUser');
+
+export enum ChatUiEvent {
+    eventRun = 'eventRun',
+    eventDestroy = 'eventDestroy',
+    eventRestart = 'eventRestart',
+    eventCancel = 'eventCancel',
+    eventEndChat = 'eventEndChat',
+    eventRecover = 'eventRecover',
+    eventChasitorTyping = 'eventChasitorTyping',
+    eventTimerRestart = 'eventTimerRestart',
+    eventMessageSend = 'eventMessageSend',
+    eventMessageSendRetry = 'eventMessageSendRetry',
+    eventMessageSendFile = 'eventMessageSendFile',
+    eventMessageSendFileRetry = 'eventMessageSendFileRetry',
+}
+
+export type ChatUiEventListener<T = void> = (
+    resolve: (value: T | PromiseLike<T>) => void,
+    reject: (reason?: any) => void,
+    ...args: unknown[]
+) => void;
+
+export interface IChatUiStore<T extends ChatCustomizations = ChatCustomizations> {
+    scrollCounter: number;
+
+    status: ChatRunState;
+    get isStarting(): boolean;
+    get isStarted(): boolean;
+    get isError(): boolean;
+    get isEnded(): boolean;
+    get customizations(): T;
+    timer?: ChatTimer;
+    endReason?: ChatEndReason;
+
+    participants: { [key: symbol]: ChatParticipantModel };
+    messages: ChatMessageModelBase[];
+    isAgentTyping: boolean;
+    isFilePickerEnabled: boolean;
+    file?: FileDescriptor;
+    error?: ChatError;
+
+    get agent(): ChatParticipantModel;
+    get user(): ChatParticipantModel;
+
+    on<T>(event: string, listener: ChatUiEventListener<T>): void;
+    off<T>(event: string, listener: ChatUiEventListener<T>): void;
+
+    setCustomizationContext(customizationContext?: T): void;
+    setIncomingSound(soundUrl: string): void;
+    setTimer(timer?: ChatTimer): void;
+    setFile(file: FileDescriptor | undefined): void;
+    setFilePickerEnabled(isEnabled: boolean): void;
+    setAgentTyping(typing: boolean): void;
+    setMessageState(message: ChatMessageModelBase, state: ChatMessageState, data?: any): void;
+    setMessages(messages: ChatMessageModelBase[]): void;
+    setAgentName(name: string): void;
+    setAgentIcon(icon: ChatParticipantIcon): void;
+    setChatError(chatError: ChatError): void;
+    setError<T = any>(message: string, options?: ChatErrorOptions<T>): void;
+    setStatus(status: ChatRunState): void;
+    resetError(runState: ChatRunState): void;
+    reset(resetStatus?: boolean): void;
+    resetFile(): void;
+
+    triggerScroll(): void;
+    configure(configuration?: ChatConfiguration): void;
+    run(configuration?: ChatConfiguration, data?: unknown): Promise<void>;
+    recover(): Promise<void>;
+    destroy(): Promise<void>;
+    chasitorTyping(isTyping: boolean): Promise<void>;
+    restartTimers(): Promise<void>;
+    restart(): Promise<void>;
+    cancelChat(): Promise<void>;
+    endChat(endReason?: ChatEndReason): Promise<void>;
+    sendMessageText(messageText: string): Promise<void>;
+    sendMessageRetry(message: ChatMessageModelBase): Promise<void>;
+    addMessage(isAgent: boolean, message: string, data?: any): void;
+    addMessageWelcome(message: string): void;
+}
+export const CHAT_UI_STORE_TOKEN = symbolToken<IChatUiStore>('CHAT_UI_STORE_TOKEN');
+
+@injectable()
+export class ChatUiStore<T extends ChatCustomizations> implements IChatUiStore<T> {
+    @observable isAgentTyping = false;
+
+    @observable status = ChatRunState.Offline;
+
+    @observable isFilePickerEnabled = false;
+
+    file?: FileDescriptor;
+
+    @observable.ref error?: ChatError;
+
+    @observable endReason?: ChatEndReason;
+
+    @observable messages: ChatMessageModelBase[] = [];
+
+    @observable currentFileMessage?: ChatMessageModelFile;
+
+    @observable scrollCounter = 1;
+
+    @observable timer?: ChatTimer;
+
+    @observable participants: { [key: symbol]: ChatParticipantModel } = {
+        [symbolAgent]: {
+            isAgent: true,
+            name: 'Agent',
+            icon: ChatParticipantIcon.Initials,
+        },
+        [symbolUser]: {
+            isAgent: false,
+            name: 'User',
+            icon: ChatParticipantIcon.Initials,
+        },
+    };
+
+    @computed
+    get agent() {
+        return this.participants[symbolAgent];
+    }
+
+    @computed
+    get user() {
+        return this.participants[symbolUser];
+    }
+
+    @computed
+    get isStarted() {
+        return this.status === ChatRunState.Started;
+    }
+
+    @computed
+    get isError() {
+        return this.status === ChatRunState.Error;
+    }
+
+    @computed
+    get isEnded() {
+        return this.status === ChatRunState.Ended;
+    }
+
+    @computed
+    get isStarting() {
+        return this.status === ChatRunState.Initializing;
+    }
+
+    @computed
+    get customizations() {
+        return this.customizationContext;
+    }
+
+    @observable
+    protected customizationContext: T = {} as T;
+    private eventEmitter = new EventEmitter();
+    private incomingMessageSound?: HTMLAudioElement;
+    private incomingMessageSoundPromise?: Promise<void>;
+
+    constructor() {
+        makeObservable(this);
+    }
+
+    on = <T>(event: string, listener: ChatUiEventListener<T>) => {
+        this.eventEmitter.on(event, listener);
+    };
+
+    off = <T>(event: string, listener: ChatUiEventListener<T>) => {
+        this.eventEmitter.off(event, listener);
+    };
+
+    @action
+    setCustomizationContext(customizationContext?: T) {
+        this.customizationContext = customizationContext ?? ({} as T);
+        this.triggerScroll();
+    }
+
+    setIncomingSound(soundUrl: string) {
+        if (this.incomingMessageSound) {
+            return;
+        }
+        this.incomingMessageSound = new Audio(soundUrl);
+    }
+
+    setFile(file?: FileDescriptor) {
+        this.file = file;
+    }
+
+    @action
+    setFilePickerEnabled(isEnabled: boolean) {
+        this.isFilePickerEnabled = isEnabled;
+        this.setFile();
+        this.triggerScroll();
+    }
+
+    @action
+    setTimer(timer?: ChatTimer) {
+        this.timer = timer;
+    }
+
+    @action
+    resetError(runState: ChatRunState) {
+        this.error = undefined;
+        this.setStatus(runState);
+        this.triggerScroll();
+    }
+
+    @action
+    setChatError(chatError: ChatError) {
+        this.error = chatError;
+        this.setStatus(ChatRunState.Error);
+        this.triggerScroll();
+    }
+
+    @action
+    setError<T = any>(message: string, options?: ChatErrorOptions<T>) {
+        this.setChatError(new ChatError(message, options));
+    }
+
+    @action
+    setStatus(status: ChatRunState) {
+        this.status = status;
+    }
+
+    @action
+    setMessages(messages: ChatMessageModelBase[]) {
+        this.messages = messages;
+        this.triggerScroll();
+    }
+
+    @action
+    setAgentName(name: string) {
+        this.agent.name = name;
+    }
+
+    @action
+    setAgentIcon(icon: ChatParticipantIcon) {
+        this.agent.icon = icon;
+    }
+
+    @action
+    setAgentTyping(isAgentTyping: boolean) {
+        this.isAgentTyping = isAgentTyping;
+        this.triggerScroll();
+    }
+
+    @action
+    setEndReason(reason?: ChatEndReason) {
+        this.endReason = reason;
+        this.triggerScroll();
+    }
+
+    @action
+    setEndedChatState(endReason: ChatEndReason) {
+        this.setEndReason(endReason);
+        this.setStatus(ChatRunState.Ended);
+        this.setAgentTyping(false);
+        this.resetFile();
+        this.triggerScroll();
+    }
+
+    @action
+    configure(configuration?: ChatConfiguration) {
+        if (!configuration) {
+            return;
+        }
+        if (configuration.agentName) {
+            this.setAgentName(configuration.agentName);
+        }
+        if (configuration.agentIcon) {
+            this.setAgentIcon(configuration.agentIcon);
+        }
+    }
+
+    async run(configuration?: ChatConfiguration, data?: unknown) {
+        this.configure(configuration);
+        if (!this.eventEmitter.listeners(ChatUiEvent.eventRun).length) {
+            throw new Error("No listeners for ChatUiEvent.eventRun ('eventRun')");
+        }
+        await this.emitAsync(ChatUiEvent.eventRun, data);
+    }
+
+    async recover() {
+        await this.emitAsync(ChatUiEvent.eventRecover, this.error);
+    }
+
+    async destroy() {
+        this.reset();
+        await this.emitAsync(ChatUiEvent.eventDestroy);
+    }
+
+    async restart() {
+        this.reset();
+        await this.emitAsync(ChatUiEvent.eventRestart);
+    }
+
+    async cancelChat() {
+        await this.emitAsync(ChatUiEvent.eventCancel);
+    }
+
+    async endChat(endReason?: ChatEndReason) {
+        await this.emitAsync(ChatUiEvent.eventEndChat, endReason);
+    }
+
+    async chasitorTyping(isTyping: boolean) {
+        await this.emitAsync(ChatUiEvent.eventChasitorTyping, isTyping);
+    }
+
+    @action
+    async sendMessageText(message: string) {
+        if (this.isFilePickerEnabled && this.file) {
+            // Send text message with file
+            runInAction(() => {
+                this.isFilePickerEnabled = false;
+                this.currentFileMessage = this.addMessageFile(this.file!);
+            });
+            let messageModel: ChatMessageModelText | undefined;
+            if (message.trim() !== '') {
+                messageModel = this.addMessage(false, message);
+            }
+            await this.emitAsync(
+                ChatUiEvent.eventMessageSendFile,
+                this.currentFileMessage,
+                this.file,
+                messageModel
+            );
+        } else {
+            // Send plain text message
+            await this.sendMessageTextInternal(message);
+        }
+    }
+
+    @action
+    async sendMessageRetry(messageModel: ChatMessageModelBase) {
+        this.resetError(ChatRunState.Started);
+        this.setMessageState(messageModel, ChatMessageState.Delivering);
+        await this.emitAsync(ChatUiEvent.eventMessageSendRetry, messageModel);
+        await this.restartTimers();
+    }
+
+    @action
+    async sendMessageFileRetry(messageModel: ChatMessageModelFile) {
+        this.resetError(ChatRunState.Started);
+        this.setMessageState(messageModel, ChatMessageState.Delivering);
+        await this.emitAsync(ChatUiEvent.eventMessageSendFileRetry, messageModel);
+    }
+
+    getParticipant(participantKey: symbol): ChatParticipantModel {
+        const participant = this.participants[participantKey];
+        return { ...participant };
+    }
+
+    @action
+    addMessage(isAgent: boolean, message: string, data?: any) {
+        return this.addMessageInternal<ChatMessageModelText>({
+            type: 'message',
+            state: ChatMessageState.Delivering,
+            participant: this.getParticipant(isAgent ? symbolAgent : symbolUser),
+            data,
+            message,
+        });
+    }
+
+    @action
+    addMessageTimeout() {
+        const isNewChat =
+            this.messages.length === 0 || this.messages.every(m => m.type === 'welcome');
+        if (isNewChat) {
+            return;
+        }
+        return this.addMessageInternal<ChatMessageModelTimeout>({
+            type: 'timeout',
+            participant: this.agent,
+            state: ChatMessageState.Delivered,
+        });
+    }
+
+    @action
+    addMessageWelcome(message: string) {
+        return this.addMessageInternal<ChatMessageModelWelcome>({
+            type: 'welcome',
+            state: ChatMessageState.Delivered,
+            participant: this.getParticipant(symbolAgent),
+            message,
+        });
+    }
+
+    @action
+    addMessageFile(file: FileDescriptor) {
+        return this.addMessageInternal<ChatMessageModelFile>({
+            fileName: file.displayName ?? 'attachment',
+            type: 'file',
+            state: ChatMessageState.Delivering,
+            participant: this.user,
+        });
+    }
+
+    @action
+    async restartTimers() {
+        this.removeMessageByType('timeout');
+        await this.emitAsync(ChatUiEvent.eventTimerRestart);
+    }
+
+    @action
+    setMessageState(message: ChatMessageModelBase, state: ChatMessageState, data?: any) {
+        const foundMessage = this.messages.find(m => m.id === message.id);
+        if (foundMessage) {
+            foundMessage.state = state;
+            if (data) {
+                foundMessage.data = data;
+            }
+        }
+    }
+
+    @action
+    resetFile() {
+        this.currentFileMessage = undefined;
+        this.file = undefined;
+        this.isFilePickerEnabled = false;
+        this.triggerScroll();
+    }
+
+    @action
+    reset(resetStatus = true) {
+        this.setMessages([]);
+        if (resetStatus) {
+            this.status = ChatRunState.Offline;
+        }
+        this.error = undefined;
+        this.isAgentTyping = false;
+        this.endReason = undefined;
+        this.resetFile();
+    }
+
+    getLastFailedMessages() {
+        const result: ChatMessageModelText[] = [];
+        for (let i = this.messages.length - 1; i >= 0; i--) {
+            const message = this.messages[i];
+            if (message.type === 'message' && !message.participant.isAgent) {
+                if (message.state !== ChatMessageState.Failed) {
+                    break;
+                }
+                result.push(message as ChatMessageModelText);
+            }
+        }
+        return result;
+    }
+
+    triggerScroll() {
+        setTimeout(() => {
+            runInAction(() => {
+                this.scrollCounter++;
+            });
+        }, 0);
+    }
+
+    protected async emitAsync<T>(event: string, ...args: unknown[]) {
+        if (!this.eventEmitter.listenerCount(event)) {
+            return Promise.resolve();
+        }
+        return new Promise<T>((resolve, reject) => {
+            this.eventEmitter.emit(event, resolve, reject, ...args);
+        });
+    }
+
+    protected addMessageInternal<T extends ChatMessageModelBase>(
+        message: Omit<T, 'id' | 'timestamp'>
+    ): T {
+        if (message.type === 'timeout') {
+            this.removeMessageByType('timeout'); // Remove previous timeout messages
+        } else {
+            this.restartTimers().then(() => {});
+        }
+        this.setMessages([...this.messages, this.createMessage<T>(message)]);
+        if (message.participant.isAgent) {
+            this.beepIncoming().catch(() => {});
+        }
+        return this.messages.at(-1) as T;
+    }
+
+    protected removeMessageByType(type: string) {
+        if (this.messages.some(m => m.type === type)) {
+            this.setMessages(this.messages.filter(m => m.type !== type));
+        }
+    }
+
+    private async sendMessageTextInternal(message: string) {
+        if (message.trim() === '') {
+            return;
+        }
+        const messageModel = this.addMessage(false, message);
+        await this.emitAsync(ChatUiEvent.eventMessageSend, messageModel);
+    }
+
+    private createMessage<T extends ChatMessageModelBase>(rest: Omit<T, 'id' | 'timestamp'>) {
+        return {
+            id: nanoid(),
+            timestamp: new Date(),
+            ...rest,
+        } as T;
+    }
+
+    private async beepIncoming() {
+        if (!this.incomingMessageSound) {
+            return;
+        }
+        try {
+            if (!this.incomingMessageSoundPromise) {
+                this.incomingMessageSoundPromise = this.incomingMessageSound.play();
+            }
+            await this.incomingMessageSoundPromise;
+        } finally {
+            this.incomingMessageSoundPromise = undefined;
+        }
+    }
+}

package/src/stores/index.ts

@@ -0,0 +1,11 @@
+export {
+    CHAT_UI_STORE_TOKEN,
+    IChatUiStore,
+    ChatUiStore,
+    ChatUiEvent,
+    symbolUser,
+    symbolAgent,
+    ChatUiEventListener,
+} from './chat-ui.store';
+export { ChatUiBackendEchoStore } from './chat-ui-backend-echo.store';
+export { CHAT_UI_BACKEND_STORE_TOKEN, IChatUiBackendStore } from './chat-ui-backend.store';

package/src/utils/__tests__/text-utils.test.ts

@@ -0,0 +1,70 @@
+import { expect } from '@jest/globals';
+import {
+    extractFilenameAndExt,
+    formatChatMessageDate,
+    getFirstName,
+    getNameInitials,
+    getNameInitialsFirst,
+} from '../text-utils';
+
+describe('text-utils', () => {
+    test('should get initials from name', () => {
+        expect(getNameInitials('')).toEqual('');
+        expect(getNameInitials('A')).toEqual('A');
+        expect(getNameInitials('AB')).toEqual('A');
+        expect(getNameInitials('abcd')).toEqual('A');
+        expect(getNameInitials('  abcd   ')).toEqual('A');
+        expect(getNameInitials('   a b c   ')).toEqual('AB');
+        expect(getNameInitials('abcd ef')).toEqual('AE');
+        expect(getNameInitials('a b c d')).toEqual('AB');
+    });
+
+    test('should extract filename and ext', () => {
+        expect(extractFilenameAndExt('')).toEqual(['', '']);
+        expect(extractFilenameAndExt('a')).toEqual(['a', '']);
+        expect(extractFilenameAndExt('a.')).toEqual(['a.', '']);
+        expect(extractFilenameAndExt('a.b')).toEqual(['a.', 'b']);
+        expect(extractFilenameAndExt('a.b.c')).toEqual(['a.b.', 'c']);
+        expect(extractFilenameAndExt('aaaa.bbbb.cccc')).toEqual(['aaaa.bbbb.', 'cccc']);
+    });
+
+    test('should getFirstName', () => {
+        expect(getFirstName('')).toEqual('');
+        expect(getFirstName('A')).toEqual('A');
+        expect(getFirstName('AB')).toEqual('AB');
+        expect(getFirstName('abcd')).toEqual('abcd');
+        expect(getFirstName('  abcd   ')).toEqual('abcd');
+        expect(getFirstName('   a b c   ')).toEqual('a');
+        expect(getFirstName('abcd ef')).toEqual('abcd');
+        expect(getFirstName('a b c d')).toEqual('a');
+    });
+
+    test('should getNameInitialsFirst', () => {
+        expect(getNameInitials('')).toEqual('');
+        expect(getNameInitials('A')).toEqual('A');
+        expect(getNameInitials('AB')).toEqual('A');
+        expect(getNameInitials('abcd')).toEqual('A');
+        expect(getNameInitials('  abcd   ')).toEqual('A');
+        expect(getNameInitials('   a b c   ')).toEqual('AB');
+        expect(getNameInitials('abcd ef')).toEqual('AE');
+        expect(getNameInitials('a b c d')).toEqual('AB');
+    });
+
+    test('should formatChatMessageDate', () => {
+        const date = new Date('2023-10-01T12:00:00Z');
+        expect(formatChatMessageDate(date)).toEqual('12:00 PM');
+        expect(formatChatMessageDate(new Date('2023-10-01T00:00:00Z'))).toEqual('12:00 AM');
+        expect(formatChatMessageDate(new Date('2023-10-01T23:59:59Z'))).toEqual('11:59 PM');
+    });
+
+    test('should getNameInitialsFirst', () => {
+        expect(getNameInitialsFirst('')).toEqual('');
+        expect(getNameInitialsFirst('A')).toEqual('A');
+        expect(getNameInitialsFirst('AB')).toEqual('A');
+        expect(getNameInitialsFirst('abcd')).toEqual('A');
+        expect(getNameInitialsFirst('  abcd   ')).toEqual('A');
+        expect(getNameInitialsFirst('   a b c   ')).toEqual('A');
+        expect(getNameInitialsFirst('abcd ef')).toEqual('A');
+        expect(getNameInitialsFirst('a b c d')).toEqual('A');
+    });
+});

package/src/utils/test-utils.ts

@@ -0,0 +1,22 @@
+import { Container } from '@servicetitan/react-ioc';
+
+type Newable<T> = new (...args: never[]) => T;
+
+export const initTestContainer = (
+    serviceIdentifier: Newable<unknown> | Newable<unknown>[],
+    initDependenciesFn: (container: Container) => void
+) => {
+    const rootContainer = new Container();
+    if (Array.isArray(serviceIdentifier)) {
+        serviceIdentifier.forEach(identifier => rootContainer.bind(identifier).toSelf());
+    } else {
+        rootContainer.bind(serviceIdentifier).toSelf();
+    }
+
+    return () => {
+        const container = new Container();
+        container.parent = rootContainer;
+        initDependenciesFn(container);
+        return container;
+    };
+};

package/src/utils/text-utils.ts

@@ -0,0 +1,36 @@
+export function formatChatMessageDate(date: Date) {
+    return date.toLocaleTimeString('en-US', {
+        hour: '2-digit',
+        minute: '2-digit',
+    });
+}
+
+export const getFirstName = (name: string): string => {
+    const parts = name.trim().split(' ');
+    return parts[0];
+};
+
+export const getNameInitials = (name: string): string => {
+    const parts = name.trim().split(' ');
+    return parts
+        .filter(Boolean)
+        .splice(0, 2)
+        .map(p => p[0]!.toUpperCase())
+        .join('');
+};
+
+export const getNameInitialsFirst = (name: string): string => {
+    const initials = getNameInitials(name);
+    return initials.length > 0 ? initials[0] : '';
+};
+
+export const extractFilenameAndExt = (fileName: string): [string, string] => {
+    const lastIndex = fileName.lastIndexOf('.');
+    if (lastIndex === -1) {
+        return [fileName, ''];
+    }
+    return [
+        fileName.substring(0, lastIndex) + '.',
+        fileName.substring(lastIndex + 1, fileName.length),
+    ];
+};

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+    "extends": "@servicetitan/startup/tsconfig/base",
+    "compilerOptions": {
+        "composite": true,
+        "outDir": "dist",
+        "rootDir": "src",
+        "moduleResolution": "bundler"
+    },
+    "include": [
+        "src/**/*"
+    ],
+    "exclude": [
+        "node_modules"
+    ]
+}