@servicetitan/titan-chatbot-api 7.1.2 → 9.0.0

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

@@ -1,5 +1,6 @@
 import { inject, injectable } from '@servicetitan/react-ioc';
 import { Models } from '..';
+import { AgentStreamHandlers, runAgentStream } from '../../streaming';
 import {
     CHATBOT_CLIENT_SETTINGS,
     FirstParameterType,
@@ -10,6 +11,9 @@ import {
 // eslint-disable-next-line no-restricted-imports
 import { Client } from './native-client';
 
+/** Streaming endpoint template, mirroring the generated client's `/api/v{version}/message`. */
+const AGENT_STREAM_PATH_TEMPLATE = '/api/v{version}/message/stream';
+
 /**
  * Settings for the chatbot client, which includes a factory for constructor parameters, and additional settings
  * like version and clientId which are used in the API calls.
@@ -21,6 +25,11 @@ export interface IChatbotClientSettingsTitanChat extends IChatbotClientSettings
     };
     version: string;
     clientId: string;
+    /**
+     * Extra headers for the SSE streaming request. `X-Client-ID` is always sent (from `clientId`);
+     * use this for anything the fetch http client would otherwise add (e.g. Authorization). Optional.
+     */
+    streamHeadersFactory?: () => Record<string, string>;
 }
 
 /**
@@ -30,6 +39,10 @@ export interface IChatbotClientSettingsTitanChat extends IChatbotClientSettings
 @injectable()
 export class ChatbotApiClient implements IChatbotApiClient {
     private readonly client: Client;
+    /** Same base URL the generated `Client` uses, so streaming URLs are built identically. */
+    private readonly baseUrl: string;
+    /** Same `fetch` the generated `Client` uses, so the SSE request gets identical auth/headers. */
+    private readonly httpFetch?: typeof fetch;
 
     get version(): string {
         return this.chatbotApiClientSettings.version;
@@ -46,6 +59,13 @@ export class ChatbotApiClient implements IChatbotApiClient {
         const { baseUrl, httpClient } =
             this.chatbotApiClientSettings.constructorParametersFactory();
         this.client = new Client(baseUrl, httpClient);
+        // Mirror the generated client's `this.baseUrl = baseUrl ?? ""`.
+        this.baseUrl = baseUrl ?? '';
+        /*
+         * Reuse the same fetch the generated client uses, so the SSE request goes through the
+         * consumer's request configuration (auth token, X-HC-Instance, credentials, …).
+         */
+        this.httpFetch = httpClient?.fetch as typeof fetch | undefined;
     }
 
     postFeedback(body: Models.Feedback, abortSignal?: AbortSignal) {
@@ -56,6 +76,32 @@ export class ChatbotApiClient implements IChatbotApiClient {
         return this.client.message(this.version, this.clientId, body, abortSignal);
     }
 
+    streamMessage(
+        body: Models.IUserMessage,
+        handlers: AgentStreamHandlers,
+        abortSignal?: AbortSignal
+    ): Promise<Models.BotMessage> {
+        /*
+         * Build the URL exactly as the generated Client does for `/api/v{version}/message`:
+         * substitute {version}, then strip a dangling query separator.
+         */
+        const url = (this.baseUrl + AGENT_STREAM_PATH_TEMPLATE)
+            .replace('{version}', encodeURIComponent('' + this.version))
+            .replace(/[?&]$/, '');
+
+        return runAgentStream({
+            url,
+            fetch: this.httpFetch,
+            headers: {
+                'X-Client-ID': this.clientId,
+                ...(this.chatbotApiClientSettings.streamHeadersFactory?.() ?? {}),
+            },
+            body,
+            handlers,
+            abortSignal,
+        });
+    }
+
     postFollowUpEmail(body: Models.UserMessage, abortSignal?: AbortSignal) {
         return this.client.followUpEmail(this.version, this.clientId, body, abortSignal);
     }

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

@@ -1 +1,2 @@
-export { ChatbotApiClient, IChatbotClientSettingsTitanChat } from './chatbot-api-client';
+export type { IChatbotClientSettingsTitanChat } from './chatbot-api-client';
+export { ChatbotApiClient } from './chatbot-api-client';

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

@@ -11,11 +11,9 @@ export function createSelectionsModel(
     const process = (filters: Models.IOption[]): Models.Selections | undefined => {
         let result: Models.Selections | undefined;
         const ensureResult = () => {
-            if (!result) {
-                result = new Models.Selections({
-                    subOptions: {},
-                });
-            }
+            result ??= new Models.Selections({
+                subOptions: {},
+            });
             return result.subOptions!;
         };
 
@@ -74,9 +72,7 @@ export function createSelectionsModel(
                         subFilterSelection = new Models.Selections({});
                         subOptions[filter.key] = subFilterSelection;
                     }
-                    if (!subFilterSelection.subOptions) {
-                        subFilterSelection.subOptions = {};
-                    }
+                    subFilterSelection.subOptions ??= {};
                     subFilterSelection.subOptions![key] = value;
                 }
             }

package/src/index.ts

@@ -1,7 +1,12 @@
 /* eslint-disable no-restricted-imports */
 export * from './api-client';
 export * from './stores';
-export * from './models';
+export * from './streaming';
+export type * from './models';
+// Runtime helpers from models (the `export type *` above is type-only).
+export {
+    isChatbotStreamingEnabled,
+    DEFAULT_STREAMING_INACTIVITY_TIMEOUT_MS,
+} from './models/chatbot-customizations';
 export * from './hooks/use-customization-chatbot';
-export * as NativeClientHC from './api-client/help-center/native-client';
 export * as NativeClientTC from './api-client/titan-chat/native-client';

package/src/models/__tests__/chatbot-customizations.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, test } from '@jest/globals';
+import { ChatbotCustomizations, isChatbotStreamingEnabled } from '../chatbot-customizations';
+
+describe('ChatbotCustomizations streaming setting', () => {
+    test('streaming is disabled when customizations are undefined', () => {
+        expect(isChatbotStreamingEnabled(undefined)).toBe(false);
+    });
+
+    test('streaming is disabled when the streaming setting is absent', () => {
+        const c: ChatbotCustomizations = { feedback: { title: 'x' } };
+        expect(isChatbotStreamingEnabled(c)).toBe(false);
+    });
+
+    test('streaming is disabled when explicitly false', () => {
+        const c: ChatbotCustomizations = { streaming: { enabled: false } };
+        expect(isChatbotStreamingEnabled(c)).toBe(false);
+    });
+
+    test('streaming is enabled only when explicitly true', () => {
+        const c: ChatbotCustomizations = {
+            streaming: { enabled: true, inactivityTimeoutMs: 16_000 },
+        };
+        expect(isChatbotStreamingEnabled(c)).toBe(true);
+        expect(c.streaming?.inactivityTimeoutMs).toBe(16_000);
+    });
+});

package/src/models/chatbot-customizations.ts

@@ -10,6 +10,19 @@ export type FilterDefaultSelectionFn = (filterKey: string, optionKey: string) =>
 
 export type ChatbotCustomizations = ChatCustomizations &
     Partial<{
+        /**
+         * Agent-progress SSE streaming. Disabled by default; when disabled (or when the streaming
+         * endpoint is unreachable at connect time) the widget falls back to the non-streaming path.
+         */
+        streaming?: {
+            /** Opt in to the SSE streaming send-path. Defaults to false. */
+            enabled?: boolean;
+            /**
+             * Inactivity threshold (ms) before the "Still working on it…" keepalive is shown.
+             * Defaults to 16000 (matching the legacy hard timeout).
+             */
+            inactivityTimeoutMs?: number;
+        };
         timeouts?: {
             chatbotRequestTimeoutMs?: number;
         };
@@ -31,3 +44,10 @@ export type ChatbotCustomizations = ChatCustomizations &
             isDefaultSelected?: FilterDefaultSelectionFn;
         };
     }>;
+
+/** Default inactivity threshold before the keepalive message is shown (ms). */
+export const DEFAULT_STREAMING_INACTIVITY_TIMEOUT_MS = 16_000;
+
+/** Whether the SSE streaming send-path is enabled. Defaults to off. */
+export const isChatbotStreamingEnabled = (customizations?: ChatbotCustomizations): boolean =>
+    customizations?.streaming?.enabled ?? false;

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

@@ -0,0 +1,105 @@
+import { expect } from '@jest/globals';
+import { ILog, Log, LogError, LogInfo, LogWarning } from '@servicetitan/log-service';
+import { Container } from '@servicetitan/react-ioc';
+import { ChatMessageModelText, 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 { AgentStreamHandlers } from '../../streaming';
+import { initTestContainer } from '../../utils/test-utils';
+import { ChatbotUiBackendStore } from '../chatbot-ui-backend.store';
+import { CHATBOT_UI_STORE_TOKEN, ChatbotUiStore } from '../chatbot-ui.store';
+
+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] streaming observability', () => {
+    let container: Container;
+    let store: ChatbotUiBackendStore;
+    let chatbotApi: ChatbotApiClientMock;
+    let chatUiStore: ChatbotUiStore;
+    let log: ILog;
+
+    const runListener = async (listener: ChatUiEventListener, args: unknown[]) =>
+        new Promise<void>((resolve, reject) => listener.apply(store, [resolve, reject, ...args]));
+
+    const sendStreamed = async () => {
+        chatUiStore.setCustomizationContext({ streaming: { enabled: true } });
+        await chatUiStore.sendMessageText('q');
+        const message = chatUiStore.messages.at(-1)! as ChatMessageModelText;
+        await runListener(store.handleMessageSend, [message]);
+    };
+
+    const codesLogged = () =>
+        (log.info as jest.Mock).mock.calls.map(c => (c[0] as { code: string }).code);
+
+    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);
+        chatbotApi.getOptions.mockResolvedValue(ModelsMocks.mockFrontendModel());
+        chatbotApi.postSession.mockResolvedValue(ModelsMocks.mockSession());
+    });
+
+    test('logs the connection lifecycle (connected → completed)', async () => {
+        chatbotApi.streamMessage.mockImplementation(
+            (_m: Models.IUserMessage, h: AgentStreamHandlers) => {
+                h.onConnected?.();
+                h.onCompleted?.();
+                return ModelsMocks.mockBotMessage({ answer: 'done' });
+            }
+        );
+
+        await sendStreamed();
+
+        const codes = codesLogged();
+        expect(codes).toContain('TitanChatbot_Streaming_connected');
+        expect(codes).toContain('TitanChatbot_Streaming_completed');
+    });
+
+    test('logs disconnected and timed_out lifecycle phases', async () => {
+        chatbotApi.streamMessage.mockImplementation(
+            (_m: Models.IUserMessage, h: AgentStreamHandlers) => {
+                h.onConnected?.();
+                h.onDisconnected?.();
+                h.onTimeout?.();
+                return ModelsMocks.mockBotMessage({ answer: 'done' });
+            }
+        );
+
+        await sendStreamed();
+
+        const codes = codesLogged();
+        expect(codes).toContain('TitanChatbot_Streaming_disconnected');
+        expect(codes).toContain('TitanChatbot_Streaming_timed_out');
+    });
+
+    test('tracks fallback separately and does not log a completed streaming run', async () => {
+        chatbotApi.streamMessage.mockRejectedValue(new Error('unreachable'));
+        chatbotApi.postMessage.mockResolvedValue(
+            ModelsMocks.mockBotMessage({ answer: 'fallback' })
+        );
+
+        await sendStreamed();
+
+        expect(store.streamingFallbackCount).toBe(1);
+        const codes = codesLogged();
+        expect(codes).toContain('TitanChatbot_Streaming_fallback');
+        expect(codes).not.toContain('TitanChatbot_Streaming_completed');
+    });
+});

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

@@ -0,0 +1,261 @@
+import { expect } from '@jest/globals';
+import { ILog, Log, LogError, LogInfo, LogWarning } from '@servicetitan/log-service';
+import { Container } from '@servicetitan/react-ioc';
+import { ChatMessageModelText, 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 { AgentStreamError, AgentStreamHandlers } from '../../streaming';
+import { initTestContainer } from '../../utils/test-utils';
+import { ChatbotUiBackendStore } from '../chatbot-ui-backend.store';
+import { CHATBOT_UI_STORE_TOKEN, ChatbotUiStore } from '../chatbot-ui.store';
+
+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] streaming', () => {
+    let container: Container;
+    let store: ChatbotUiBackendStore;
+    let chatbotApi: ChatbotApiClientMock;
+    let chatUiStore: ChatbotUiStore;
+
+    const runListener = async <T = void>(listener: ChatUiEventListener<T>, args: unknown[]) =>
+        new Promise<T>((resolve, reject) => listener.apply(store, [resolve, reject, ...args]));
+
+    const mockSession = () => {
+        chatbotApi.getOptions.mockResolvedValue(ModelsMocks.mockFrontendModel());
+        chatbotApi.postSession.mockResolvedValue(ModelsMocks.mockSession());
+    };
+
+    const enableStreaming = () =>
+        chatUiStore.setCustomizationContext({ streaming: { enabled: true } });
+
+    const sendQuestion = async (text = 'user question') => {
+        await chatUiStore.sendMessageText(text);
+        return chatUiStore.messages.at(-1)! as ChatMessageModelText;
+    };
+
+    beforeEach(() => {
+        container = initContainer();
+        store = container.get(ChatbotUiBackendStore);
+        chatbotApi = container.get<IChatbotApiClient>(CHATBOT_API_CLIENT) as ChatbotApiClientMock;
+        chatUiStore = container.get<ChatbotUiStore>(CHATBOT_UI_STORE_TOKEN);
+        mockSession();
+    });
+
+    test('uses the streaming path when enabled, not postMessage', async () => {
+        enableStreaming();
+        chatbotApi.streamMessage.mockResolvedValue(
+            ModelsMocks.mockBotMessage({ answer: 'streamed' })
+        );
+
+        const message = await sendQuestion();
+        await runListener(store.handleMessageSend, [message]);
+
+        expect(chatbotApi.streamMessage).toHaveBeenCalledTimes(1);
+        expect(chatbotApi.postMessage).not.toHaveBeenCalled();
+        expect((chatUiStore.messages.at(-1) as ChatMessageModelText).message).toBe('streamed');
+        expect(chatUiStore.isAgentTyping).toBe(false);
+    });
+
+    test('uses the non-streaming path when disabled', async () => {
+        chatbotApi.postMessage.mockResolvedValue(ModelsMocks.mockBotMessage({ answer: 'regular' }));
+
+        const message = await sendQuestion();
+        await runListener(store.handleMessageSend, [message]);
+
+        expect(chatbotApi.postMessage).toHaveBeenCalledTimes(1);
+        expect(chatbotApi.streamMessage).not.toHaveBeenCalled();
+        expect((chatUiStore.messages.at(-1) as ChatMessageModelText).message).toBe('regular');
+    });
+
+    test('maps progress events onto the observable progress model', async () => {
+        enableStreaming();
+        chatbotApi.streamMessage.mockImplementation(
+            (_m: Models.IUserMessage, h: AgentStreamHandlers) => {
+                h.onStatus?.('Thinking…');
+                h.onText?.('✓ searched');
+                h.onPlan?.([{ id: '1', title: 'Plan' }]);
+                return ModelsMocks.mockBotMessage({ answer: 'done' });
+            }
+        );
+
+        const message = await sendQuestion();
+        await runListener(store.handleMessageSend, [message]);
+
+        expect(store.streamingProgress.logLines).toContain('✓ searched');
+        expect(store.streamingProgress.steps.map(s => s.id)).toEqual(['1']);
+    });
+
+    test('scrolls the chat after each streaming progress update', async () => {
+        enableStreaming();
+        const triggerScroll = jest.spyOn(chatUiStore, 'triggerScroll');
+        chatbotApi.streamMessage.mockImplementation(
+            (_m: Models.IUserMessage, h: AgentStreamHandlers) => {
+                /*
+                 * Each progress event must scroll exactly once (isolated from the scrolls that
+                 * delivering the final answer also performs).
+                 */
+                const scrollsFor = (fn: () => void) => {
+                    triggerScroll.mockClear();
+                    fn();
+                    return triggerScroll.mock.calls.length;
+                };
+                expect(scrollsFor(() => h.onStatus?.('Thinking…'))).toBe(1);
+                expect(scrollsFor(() => h.onText?.('✓ searched'))).toBe(1);
+                expect(scrollsFor(() => h.onPlan?.([{ id: '1', title: 'Plan' }]))).toBe(1);
+                expect(scrollsFor(() => h.onStepActive?.('1'))).toBe(1);
+                expect(scrollsFor(() => h.onInactivity?.())).toBe(1);
+                return ModelsMocks.mockBotMessage({ answer: 'done' });
+            }
+        );
+
+        const message = await sendQuestion();
+        await runListener(store.handleMessageSend, [message]);
+        expect(triggerScroll).toHaveBeenCalled();
+    });
+
+    test('onStepActive marks the active plan step (earlier done, later pending)', async () => {
+        enableStreaming();
+        chatbotApi.streamMessage.mockImplementation(
+            (_m: Models.IUserMessage, h: AgentStreamHandlers) => {
+                h.onPlan?.([
+                    { id: '1', title: 'Look up' },
+                    { id: '2', title: 'Search' },
+                    { id: '3', title: 'Answer' },
+                ]);
+                h.onStepActive?.('2');
+                // Capture mid-run state before run.finished completes all steps.
+                expect(store.streamingProgress.steps.map(s => s.status)).toEqual([
+                    'done',
+                    'active',
+                    'pending',
+                ]);
+                return ModelsMocks.mockBotMessage({ answer: 'done' });
+            }
+        );
+
+        const message = await sendQuestion();
+        await runListener(store.handleMessageSend, [message]);
+    });
+
+    test('marks all plan steps done once the run finishes', async () => {
+        enableStreaming();
+        chatbotApi.streamMessage.mockImplementation(
+            (_m: Models.IUserMessage, h: AgentStreamHandlers) => {
+                h.onPlan?.([
+                    { id: '1', title: 'Look up' },
+                    { id: '2', title: 'Answer' },
+                ]);
+                h.onStepActive?.('1');
+                return ModelsMocks.mockBotMessage({ answer: 'done' });
+            }
+        );
+
+        const message = await sendQuestion();
+        await runListener(store.handleMessageSend, [message]);
+
+        expect(store.streamingProgress.steps.map(s => s.status)).toEqual(['done', 'done']);
+    });
+
+    test('shows the "Still working on it…" keepalive on inactivity', async () => {
+        enableStreaming();
+        chatbotApi.streamMessage.mockImplementation(
+            (_m: Models.IUserMessage, h: AgentStreamHandlers) => {
+                h.onInactivity?.();
+                expect(store.streamingProgress.keepaliveText).toBe('Still working on it…');
+                return ModelsMocks.mockBotMessage({ answer: 'done' });
+            }
+        );
+
+        const message = await sendQuestion();
+        await runListener(store.handleMessageSend, [message]);
+    });
+
+    test('passes the configured inactivity timeout (defaulting to 16000)', async () => {
+        enableStreaming();
+        chatbotApi.streamMessage.mockResolvedValue(ModelsMocks.mockBotMessage({ answer: 'done' }));
+
+        const message = await sendQuestion();
+        await runListener(store.handleMessageSend, [message]);
+
+        const handlers = chatbotApi.streamMessage.mock.calls[0][1] as AgentStreamHandlers;
+        expect(handlers.inactivityTimeoutMs).toBe(16_000);
+    });
+
+    test('falls back to non-streaming silently when the stream is unreachable at connect time', async () => {
+        enableStreaming();
+        // Rejects WITHOUT ever calling onConnected → connect-time failure.
+        chatbotApi.streamMessage.mockRejectedValue(new Error('connect failed'));
+        chatbotApi.postMessage.mockResolvedValue(
+            ModelsMocks.mockBotMessage({ answer: 'fallback answer' })
+        );
+
+        const message = await sendQuestion();
+        await runListener(store.handleMessageSend, [message]);
+
+        expect(chatbotApi.postMessage).toHaveBeenCalledTimes(1);
+        expect((chatUiStore.messages.at(-1) as ChatMessageModelText).message).toBe(
+            'fallback answer'
+        );
+        expect(chatUiStore.isError).toBe(false);
+        expect(store.streamingFallbackCount).toBe(1);
+    });
+
+    test('shows the drop error when the connection fails after connecting', async () => {
+        enableStreaming();
+        chatbotApi.streamMessage.mockImplementation(
+            (_m: Models.IUserMessage, h: AgentStreamHandlers) => {
+                h.onConnected?.();
+                throw new Error('socket dropped');
+            }
+        );
+
+        const message = await sendQuestion();
+        await runListener(store.handleMessageSend, [message]);
+
+        expect(chatbotApi.postMessage).not.toHaveBeenCalled();
+        expect(chatUiStore.isError).toBe(true);
+        expect(chatUiStore.error?.message).toContain('Something went wrong during this step');
+    });
+
+    test('surfaces the agent step error message from run.error', async () => {
+        enableStreaming();
+        chatbotApi.streamMessage.mockImplementation(
+            (_m: Models.IUserMessage, h: AgentStreamHandlers) => {
+                h.onConnected?.();
+                throw new AgentStreamError('Search step failed');
+            }
+        );
+
+        const message = await sendQuestion();
+        await runListener(store.handleMessageSend, [message]);
+
+        expect(chatUiStore.isError).toBe(true);
+        expect(chatUiStore.error?.message).toContain('Search step failed');
+    });
+
+    test('sends the active session id with the streamed message (session isolation)', async () => {
+        enableStreaming();
+        chatbotApi.streamMessage.mockResolvedValue(ModelsMocks.mockBotMessage({ answer: 'done' }));
+
+        const message = await sendQuestion();
+        await runListener(store.handleMessageSend, [message]);
+
+        const sentBody = chatbotApi.streamMessage.mock.calls[0][0] as Models.IUserMessage;
+        expect(sentBody.sessionId).toBe(store.session?.id);
+    });
+});