chat-headless: implement agent handoff with support of ChatHttpClient…

… and ChatEventClient (#51) ChatHeadless now accepts a bot chat client and an agent chat client. A Chat client can be of type `ChatHttpClient` (e.g. process requests through Yext Chat API endpoints) or of type `ChatEventClient` (e.g. WebSocket connection for Amazon Connect integration). A chat client can initiate a handoff to the other client. J=CLIP-1286 TEST=manual&auto see that unit tests passed see that the behavior is as expected in test-site with chat-core-aws-connect as the agent client. upon user request, a chat session is created and successfully interact with agent. When agent closes the session, user can either reconnect by sending a new message, or after 15 minutes, resume conversation with the bot.
yext · Jul 5, 2024 · 92615d3 · 92615d3
1 parent f6c7220
commit 92615d3
Show file tree

Hide file tree

Showing 24 changed files with 617 additions and 67 deletions.
diff --git a/package-lock.json b/package-lock.json
diff --git a/packages/chat-headless/THIRD-PARTY-NOTICES b/packages/chat-headless/THIRD-PARTY-NOTICES
@@ -105,7 +105,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 The following npm package may be included in this product:
 
- - @yext/[email protected].0
+ - @yext/[email protected].2
 
 This package contains the following license and notice below:
 

diff --git a/packages/chat-headless/docs/chat-headless.chatclient.md b/packages/chat-headless/docs/chat-headless.chatclient.md
@@ -2,20 +2,14 @@
 
 [Home](./index.md) &gt; [@yext/chat-headless](./chat-headless.md) &gt; [ChatClient](./chat-headless.chatclient.md)
 
-## ChatClient interface
+## ChatClient type
 
-The client interface used to make requests to the Chat API.
+A client that can be used to process user messages and provide responses.
 
 **Signature:**
 
 ```typescript
-export interface ChatClient 
+export type ChatClient = ChatHttpClient | ChatEventClient;
 ```
-
-## Methods
-
-|  Method | Description |
-|  --- | --- |
-|  [getNextMessage(request)](./chat-headless.chatclient.getnextmessage.md) | Make a request to Chat API to generate the next message. |
-|  [streamNextMessage(request)](./chat-headless.chatclient.streamnextmessage.md) | Make a request to Chat streaming API to generate the next message and consume its tokens via server-sent events. |
+**References:** [ChatHttpClient](./chat-headless.chathttpclient.md)<!-- -->, [ChatEventClient](./chat-headless.chateventclient.md)
 
diff --git a/packages/chat-headless/docs/chat-headless.chateventclient.emit.md b/packages/chat-headless/docs/chat-headless.chateventclient.emit.md
@@ -0,0 +1,25 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/chat-headless](./chat-headless.md) &gt; [ChatEventClient](./chat-headless.chateventclient.md) &gt; [emit](./chat-headless.chateventclient.emit.md)
+
+## ChatEventClient.emit() method
+
+Emits an event with the specified name and data, triggering all registered listeners for that event.
+
+**Signature:**
+
+```typescript
+emit(eventName: string, data: any): void;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  eventName | string | The name of the event to emit. |
+|  data | any | The data to be passed to the event listeners. |
+
+**Returns:**
+
+void
+
diff --git a/packages/chat-headless/docs/chat-headless.chateventclient.getsession.md b/packages/chat-headless/docs/chat-headless.chateventclient.getsession.md
@@ -0,0 +1,17 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/chat-headless](./chat-headless.md) &gt; [ChatEventClient](./chat-headless.chateventclient.md) &gt; [getSession](./chat-headless.chateventclient.getsession.md)
+
+## ChatEventClient.getSession() method
+
+Provide the current chat session.
+
+**Signature:**
+
+```typescript
+getSession(): any;
+```
+**Returns:**
+
+any
+
diff --git a/packages/chat-headless/docs/chat-headless.chateventclient.init.md b/packages/chat-headless/docs/chat-headless.chateventclient.init.md
@@ -0,0 +1,24 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/chat-headless](./chat-headless.md) &gt; [ChatEventClient](./chat-headless.chateventclient.md) &gt; [init](./chat-headless.chateventclient.init.md)
+
+## ChatEventClient.init() method
+
+Initializes the client, using credentials and data in the provided message to setup a chat session.
+
+**Signature:**
+
+```typescript
+init(messageResponse: MessageResponse): Promise<void>;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  messageResponse | MessageResponse | The message response that initiated the handoff to the chat client. |
+
+**Returns:**
+
+Promise&lt;void&gt;
+
diff --git a/packages/chat-headless/docs/chat-headless.chateventclient.md b/packages/chat-headless/docs/chat-headless.chateventclient.md
@@ -0,0 +1,24 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/chat-headless](./chat-headless.md) &gt; [ChatEventClient](./chat-headless.chateventclient.md)
+
+## ChatEventClient interface
+
+An event-driven client for processing user message and provide responses by emitting and listening to events.
+
+**Signature:**
+
+```typescript
+export interface ChatEventClient 
+```
+
+## Methods
+
+|  Method | Description |
+|  --- | --- |
+|  [emit(eventName, data)](./chat-headless.chateventclient.emit.md) | Emits an event with the specified name and data, triggering all registered listeners for that event. |
+|  [getSession()](./chat-headless.chateventclient.getsession.md) | Provide the current chat session. |
+|  [init(messageResponse)](./chat-headless.chateventclient.init.md) | Initializes the client, using credentials and data in the provided message to setup a chat session. |
+|  [on(eventName, cb)](./chat-headless.chateventclient.on.md) | Registers an event listener for a specified event. Supported events are: - <code>message</code>: A new message has been received. - <code>typing</code>: The agent is typing. - <code>close</code>: The chat session has been closed. |
+|  [processMessage(request)](./chat-headless.chateventclient.processmessage.md) | Processes a message request. The response should be emitted as a message event. |
+
diff --git a/packages/chat-headless/docs/chat-headless.chateventclient.on.md b/packages/chat-headless/docs/chat-headless.chateventclient.on.md
@@ -0,0 +1,25 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/chat-headless](./chat-headless.md) &gt; [ChatEventClient](./chat-headless.chateventclient.md) &gt; [on](./chat-headless.chateventclient.on.md)
+
+## ChatEventClient.on() method
+
+Registers an event listener for a specified event. Supported events are: - `message`<!-- -->: A new message has been received. - `typing`<!-- -->: The agent is typing. - `close`<!-- -->: The chat session has been closed.
+
+**Signature:**
+
+```typescript
+on(eventName: "message" | "typing" | "close", cb: (data: any) => void): void;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  eventName | "message" \| "typing" \| "close" | The name of the event to listen to. |
+|  cb | (data: any) =&gt; void | The callback function to be executed when the event is triggered. |
+
+**Returns:**
+
+void
+
diff --git a/packages/chat-headless/docs/chat-headless.chateventclient.processmessage.md b/packages/chat-headless/docs/chat-headless.chateventclient.processmessage.md
@@ -0,0 +1,24 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/chat-headless](./chat-headless.md) &gt; [ChatEventClient](./chat-headless.chateventclient.md) &gt; [processMessage](./chat-headless.chateventclient.processmessage.md)
+
+## ChatEventClient.processMessage() method
+
+Processes a message request. The response should be emitted as a message event.
+
+**Signature:**
+
+```typescript
+processMessage(request: MessageRequest): Promise<void>;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  request | MessageRequest | The message request to process. |
+
+**Returns:**
+
+Promise&lt;void&gt;
+
diff --git a/...hat-headless.chatclient.getnextmessage.md → ...headless.chathttpclient.getnextmessage.md b/...hat-headless.chatclient.getnextmessage.md → ...headless.chathttpclient.getnextmessage.md
@@ -1,10 +1,10 @@
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
-[Home](./index.md) &gt; [@yext/chat-headless](./chat-headless.md) &gt; [ChatClient](./chat-headless.chatclient.md) &gt; [getNextMessage](./chat-headless.chatclient.getnextmessage.md)
+[Home](./index.md) &gt; [@yext/chat-headless](./chat-headless.md) &gt; [ChatHttpClient](./chat-headless.chathttpclient.md) &gt; [getNextMessage](./chat-headless.chathttpclient.getnextmessage.md)
 
-## ChatClient.getNextMessage() method
+## ChatHttpClient.getNextMessage() method
 
-Make a request to Chat API to generate the next message.
+Make a request to generate the next message.
 
 **Signature:**
 
@@ -16,7 +16,7 @@ getNextMessage(request: MessageRequest): Promise<MessageResponse>;
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  request | MessageRequest |  |
+|  request | MessageRequest | The message request to process. |
 
 **Returns:**
 

diff --git a/packages/chat-headless/docs/chat-headless.chathttpclient.md b/packages/chat-headless/docs/chat-headless.chathttpclient.md
@@ -0,0 +1,21 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@yext/chat-headless](./chat-headless.md) &gt; [ChatHttpClient](./chat-headless.chathttpclient.md)
+
+## ChatHttpClient interface
+
+An HTTP-based client for processing user messages and generating corresponding responses via a chat service API.
+
+**Signature:**
+
+```typescript
+export interface ChatHttpClient 
+```
+
+## Methods
+
+|  Method | Description |
+|  --- | --- |
+|  [getNextMessage(request)](./chat-headless.chathttpclient.getnextmessage.md) | Make a request to generate the next message. |
+|  [streamNextMessage(request)](./chat-headless.chathttpclient.streamnextmessage.md) | Make a request to generate the next message and stream its tokens via server-sent events. |
+
diff --git a/...-headless.chatclient.streamnextmessage.md → ...dless.chathttpclient.streamnextmessage.md b/...-headless.chatclient.streamnextmessage.md → ...dless.chathttpclient.streamnextmessage.md
@@ -1,10 +1,10 @@
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
-[Home](./index.md) &gt; [@yext/chat-headless](./chat-headless.md) &gt; [ChatClient](./chat-headless.chatclient.md) &gt; [streamNextMessage](./chat-headless.chatclient.streamnextmessage.md)
+[Home](./index.md) &gt; [@yext/chat-headless](./chat-headless.md) &gt; [ChatHttpClient](./chat-headless.chathttpclient.md) &gt; [streamNextMessage](./chat-headless.chathttpclient.streamnextmessage.md)
 
-## ChatClient.streamNextMessage() method
+## ChatHttpClient.streamNextMessage() method
 
-Make a request to Chat streaming API to generate the next message and consume its tokens via server-sent events.
+Make a request to generate the next message and stream its tokens via server-sent events.
 
 **Signature:**
 
@@ -16,7 +16,7 @@ streamNextMessage(request: MessageRequest): Promise<StreamResponse>;
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
-|  request | MessageRequest |  |
+|  request | MessageRequest | The message request to process. |
 
 **Returns:**
 

diff --git a/packages/chat-headless/docs/chat-headless.md b/packages/chat-headless/docs/chat-headless.md
@@ -8,17 +8,24 @@
 
 |  Function | Description |
 |  --- | --- |
-|  [provideChatHeadless(config)](./chat-headless.providechatheadless.md) | Provide an instance of [ChatHeadless](./chat-headless.chatheadless.md) with all functionality built in. |
+|  [provideChatHeadless(config, clients)](./chat-headless.providechatheadless.md) | Provide an instance of [ChatHeadless](./chat-headless.chatheadless.md) with all functionality built in. |
 
 ## Interfaces
 
 |  Interface | Description |
 |  --- | --- |
-|  [ChatClient](./chat-headless.chatclient.md) | The client interface used to make requests to the Chat API. |
+|  [ChatEventClient](./chat-headless.chateventclient.md) | An event-driven client for processing user message and provide responses by emitting and listening to events. |
 |  [ChatHeadless](./chat-headless.chatheadless.md) | Provides the functionality needed to interact with the Chat API in a stateful manner. |
+|  [ChatHttpClient](./chat-headless.chathttpclient.md) | An HTTP-based client for processing user messages and generating corresponding responses via a chat service API. |
 |  [ConversationState](./chat-headless.conversationstate.md) | Maintains the data for the current conversation. |
 |  [HeadlessConfig](./chat-headless.headlessconfig.md) | The configuration for a SearchHeadless instance. |
 |  [MetaState](./chat-headless.metastate.md) | Maintains the metadata for Chat Headless. |
 |  [State](./chat-headless.state.md) | The state representing a ChatHeadless instance. |
 |  [StateListener](./chat-headless.statelistener.md) | Represents a listener for a specific value of type T in the state. |
 
+## Type Aliases
+
+|  Type Alias | Description |
+|  --- | --- |
+|  [ChatClient](./chat-headless.chatclient.md) | A client that can be used to process user messages and provide responses. |
+
diff --git a/packages/chat-headless/docs/chat-headless.providechatheadless.md b/packages/chat-headless/docs/chat-headless.providechatheadless.md
@@ -9,14 +9,18 @@ Provide an instance of [ChatHeadless](./chat-headless.chatheadless.md) with all
 **Signature:**
 
 ```typescript
-export declare function provideChatHeadless(config: HeadlessConfig): ChatHeadless;
+export declare function provideChatHeadless(config: HeadlessConfig, clients?: {
+    bot?: ChatClient;
+    agent?: ChatClient;
+}): ChatHeadless;
 ```
 
 ## Parameters
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
 |  config | [HeadlessConfig](./chat-headless.headlessconfig.md) |  |
+|  clients | { bot?: [ChatClient](./chat-headless.chatclient.md)<!-- -->; agent?: [ChatClient](./chat-headless.chatclient.md)<!-- -->; } | _(Optional)_ |
 
 **Returns:**
 

diff --git a/packages/chat-headless/etc/chat-headless.api.md b/packages/chat-headless/etc/chat-headless.api.md
@@ -33,13 +33,19 @@ import { Unsubscribe } from '@reduxjs/toolkit';
 export { ApiError }
 
 // @public
-export interface ChatClient {
-    getNextMessage(request: MessageRequest): Promise<MessageResponse>;
-    streamNextMessage(request: MessageRequest): Promise<StreamResponse>;
-}
+export type ChatClient = ChatHttpClient | ChatEventClient;
 
 export { ChatConfig }
 
+// @public
+export interface ChatEventClient {
+    emit(eventName: string, data: any): void;
+    getSession(): any;
+    init(messageResponse: MessageResponse): Promise<void>;
+    on(eventName: "message" | "typing" | "close", cb: (data: any) => void): void;
+    processMessage(request: MessageRequest): Promise<void>;
+}
+
 // @public
 export interface ChatHeadless {
     // @internal
@@ -62,6 +68,12 @@ export interface ChatHeadless {
     streamNextMessage(text?: string, source?: MessageSource): Promise<MessageResponse | undefined>;
 }
 
+// @public
+export interface ChatHttpClient {
+    getNextMessage(request: MessageRequest): Promise<MessageResponse>;
+    streamNextMessage(request: MessageRequest): Promise<StreamResponse>;
+}
+
 export { ChatPrompt }
 
 // @public
@@ -105,7 +117,10 @@ export interface MetaState {
 }
 
 // @public
-export function provideChatHeadless(config: HeadlessConfig): ChatHeadless;
+export function provideChatHeadless(config: HeadlessConfig, clients?: {
+    bot?: ChatClient;
+    agent?: ChatClient;
+}): ChatHeadless;
 
 // Warning: (ae-internal-missing-underscore) The name "provideChatHeadlessInternal" should be prefixed with an underscore because the declaration is marked as @internal
 //