@stack-spot/ai-chat-widget 0.11.0 → 1.1.0

package/src/state/ChatEntry.ts

@@ -3,10 +3,16 @@ import { pull } from 'lodash'
 import { LabeledWithImage } from './types'
 
 export interface SerializableAction {
+  /**
+   * The text for the button or anchor.
+   */
   title: string,
+  /**
+   * Links open new tabs with urls, while commands send text commands in the chat as if they were written by the user.
+   */
   type: 'link' | 'command',
   /**
-   * The URL if the action is a link or a chat command otherwise (/command).
+   * The URL if the action is a link. The content of the user message otherwise.
    */
   exec: string,
 }
@@ -26,23 +32,61 @@ export interface KnowledgeSource {
 }
 
 export interface TextChatEntry {
+  /**
+   * "text" for simple unformatted paragraphs. "md" for markdown.
+   */
   type: 'text' | 'md',
+  /**
+   * If the message was typed by the AI agent (bot), the user or the system (not currently in use).
+   */
   agentType: 'bot' | 'user' | 'system',
+  /**
+   * A set of buttons to go after the message.
+   */
   actions?: ChatAction[],
+  /**
+   * The content of the message.
+   */
   content: string,
+  /**
+   * The knowledge sources used to create the message.
+   */
   knowledgeSources?: KnowledgeSource[],
+  /**
+   * The date and time of the message. ISO string.
+   */
   updated?: string,
+  /**
+   * The agent who wrote the message. Undefined for the default agent or if the agentType is "user".
+   */
   agent?: LabeledWithImage,
+  /**
+   * The unique identifier of the message.
+   */
   messageId?: string,
+  /**
+   * If this is set, only an error message is rendered.
+   */
   error?: string,
+  /**
+   * A series of badges to display before the content.
+   */
   badges?: { color?: ColorPaletteName, label: string }[],
+  /**
+   * Whether or not to show this chat entry as a card.
+   */
   card?: boolean,
 }
 
 type ChatEntryListener = (value: TextChatEntry) => void
 
+// this id is unique for each message and used for rendering. The `messageId`, which comes from the backend, is not always available and, 
+// therefore, can't be used for this purpose.
 let nextId = 0
 
+/**
+ * A message (entry) in the chat.
+ */
 export class ChatEntry {
   readonly id: number
   private value: TextChatEntry
@@ -50,13 +94,18 @@ export class ChatEntry {
 
   /**
    * @param value the value of the entry.
-   * @param isStreamed whether or not this entry is streamed. Defaults to false.
    */
   constructor(value: TextChatEntry) {
     this.id = nextId++
     this.value = value
   }
 
+  /**
+   * Utility function to create a user entry.
+   * @param content the message's content.
+   * @param isMd whether or not this should be rendered as markdown.
+   * @returns a new ChatEntry.
+   */
   static createUserEntry(content: string, isMd = false) {
     return new ChatEntry({
       agentType: 'user',
@@ -66,6 +115,10 @@ export class ChatEntry {
     })
   }
 
+  /**
+   * Utility function to create a streamed entry from the AI agent.
+   * @returns a new ChatEntry.
+   */
   static createStreamedBotEntry() {
     return new ChatEntry({ agentType: 'bot', type: 'md', content: '' })
   }
@@ -79,6 +132,11 @@ export class ChatEntry {
     return this.value
   }
 
+  /**
+   * Watches the value of this ChatEntry.
+   * @param listener a function to call whenever the value changes.
+   * @returns a function that removes the listener.
+   */
   onChange(listener: ChatEntryListener) {
     this.listeners.push(listener)
     return () => {

package/src/state/ChatState.ts

@@ -6,12 +6,33 @@ import { ObservableState } from './ObservableState'
 import { Labeled, LabeledWithImage } from './types'
 
 export interface ChatProperties {
+  /**
+   * The name of the chat.
+   */
   label: string,
+  /**
+   * The current AI agent.
+   */
   agent?: LabeledWithImage & { builtIn: boolean },
+  /**
+   * The current workspace.
+   */
   workspace?: Labeled,
+  /**
+   * The current stack.
+   */
   stack?: Labeled,
+  /**
+   * The current knowledge sources.
+   */
   knowledgeSources?: Labeled[],
+  /**
+   * Whether or not the chat is in a loading state.
+   */
   isLoading?: boolean,
+  /**
+   * The value of the next message. This is the value of the text typed in the textarea below the chat.
+   */
   nextMessage?: string,
   /**
    * The current code in the editor.
@@ -22,7 +43,7 @@ export interface ChatProperties {
    */
   codeLanguage?: string,
   /**
-   * The current selection in the editor
+   * The current selection in the editor.
    */
   codeSelection?: string,
 }
@@ -34,28 +55,56 @@ export type MessageInterceptor = (
 ) => boolean | undefined | void | Promise<boolean | undefined | void>
 
 interface Options {
+  /**
+   * The unique identifier for this chat (conversationId).
+   */
   id: string,
+  /**
+   * The initial value for the state of this chat.
+   */
   initial: ChatProperties,
+  /**
+   * The interceptors to use for the messages pushed to this chat.
+   * 
+   * The interceptors are run whenever a new message (chat entry) is added to the chat. They're always run in the order of the array and if
+   * any returns a promise, the promise is awaited before running the next.
+   * 
+   * If an interceptor returns false or resolves to false (if a promise), the execution is interrupted, i.e. the next interceptors are not
+   * run.
+   * 
+   * An interceptor receives three parameters:
+   * 1. the chat entry added;
+   * 2. the chat state;
+   * 3. an AbortSignal that can be aborted by calling `abort()` on the ChatState. Once the signal is aborted, the interceptor must abort all
+   * of its operations.
+   * 
+   * Attention: when multiple messages are added at once, only the last goes through the interceptors. Furthermore, messages created by the
+   * constructor don't go through the interceptors, only messages added via `pushMessage` do.
+   */
   interceptors?: MessageInterceptor[],
+  /**
+   * The content of this chat, i.e. its messages.
+   */
   entries?: ChatEntry[],
 }
 
+/**
+ * A chat. Each chat tab is a different ChatState.
+ */
 export class ChatState extends ObservableState<ChatProperties> {
   readonly id: string
   private entries: ChatEntry[]
   private messagesListeners: ChatMessagesListener[] = []
   private readonly interceptors: MessageInterceptor[]
+  /**
+   * A memory space (map) to be used by interceptors.
+   */
   interceptorMemory = new Map<string, any>()
-  private abortions: AbortController[] = []
-
   /**
-   * @param id the id of the chat.
-   * @param initial the initial state.
-   * @param interceptors a list of interceptors to run whenever a new message (entry) is added to the chat. If an interception function
-   * returns false, the next interceptors are not run. Attention: when multiple messages are added at once, only the last goes through the
-   * interceptors. Furthermore, messages created by the constructor don't go through the interceptors, only messages added via `pushMessage`
-   * do.
+   * Abort signals currently active.
    */
+  private abortions: AbortController[] = []
+
   constructor({ id, initial, entries = [], interceptors = [] }: Options) {
     super(initial)
     this.id = id
@@ -82,6 +131,10 @@ export class ChatState extends ObservableState<ChatProperties> {
     pull(this.abortions, abort)
   }
 
+  /**
+   * Adds one or more messages to the chat. Messages are appended to the end of the chat.
+   * @param entries the messages to add.
+   */
   pushMessage(...entries: ChatEntry[]) {
     if (!entries.length) return
     this.entries = [...this.entries, ...entries]
@@ -89,15 +142,27 @@ export class ChatState extends ObservableState<ChatProperties> {
     this.runInterceptors(last(entries)!)
   }
 
+  /**
+   * Removes one or more messages from the end of the chat.
+   * @param quantity the number of messages to remove. Defaults to 1.
+   */
   popMessage(quantity = 1) {
     this.entries = dropRight(this.entries, quantity)
     this.runMessagesListeners()
   }
 
+  /**
+   * @returns the current list of messages.
+   */
   getMessages() {
     return this.entries
   }
 
+  /**
+   * Watches this chat for changes in the list of messages.
+   * @param listener the function to call whenever the list of messages changes.
+   * @returns a function that removes the listener.
+   */
   onChangeMessages(listener: ChatMessagesListener) {
     this.messagesListeners.push(listener)
     return () => {

package/src/state/ChatTabsController.ts

@@ -3,6 +3,9 @@ import { ChatState } from './ChatState'
 
 type TabChangeListener = (chats: ChatState[], activeId: string) => void
 
+/**
+ * Controls the chat tabs.
+ */
 export class ChatTabsController {
   private chats: ChatState[] = []
   private activeChatId = ''
@@ -12,12 +15,20 @@ export class ChatTabsController {
     this.listeners.forEach(l => l(this.chats, this.activeChatId))
   }
 
+  /**
+   * Adds new chats to the tab view.
+   * @param chats the chats to add.
+   */
   add(...chats: ChatState[]) {
     if (!chats.length) return
     this.chats = [...this.chats, ...chats]
     this.runListeners()
   }
 
+  /**
+   * Removes chats from the tab view.
+   * @param ids the ids of the chats to remove.
+   */
   remove(...ids: string[]) {
     if (this.chats.length <= 1 || !ids.length) return
     const currentActiveIndex = this.chats.findIndex(c => c.id === this.activeChatId)
@@ -29,18 +40,34 @@ export class ChatTabsController {
     this.runListeners()
   }
 
+  /**
+   * @param id the id of the chat to retrieve.
+   * @returns a ChatState corresponding to the id.
+   */
   get(id: string) {
     return this.chats.find(c => c.id === id)
   }
 
+  /**
+   * @returns the if of the chat corresponding to the tab that is currently active.
+   */
   getActiveChatId() {
     return this.activeChatId
   }
 
+  /**
+   * @returns all chats in tab view.
+   */
   getAll() {
     return this.chats
   }
 
+  /**
+   * Watches for changes in the tab view.
+   * @param listener a function called whenever a tab is added, removed or selected. This function receives the list of chats as the first
+   * parameter and the id of the active chat as the second parameter.
+   * @returns a function to remove the listener.
+   */
   onChange(listener: TabChangeListener) {
     this.listeners.push(listener)
     return () => {
@@ -48,6 +75,10 @@ export class ChatTabsController {
     }
   }
 
+  /**
+   * Changes the chat (tab) that is currently active.
+   * @param id the id of the chat to select.
+   */
   select(id: string) {
     this.activeChatId = id
     this.runListeners()

package/src/state/ObservableState.ts

@@ -6,6 +6,14 @@ type Listeners<T> = {
   [K in keyof T]?: ((value: T[K]) => void)[]
 }
 
+/**
+ * A generic representation of a state that can be observed for changes.
+ * 
+ * Building our own state instead of using React is important because:
+ * 1. We need to be able to control it even outside the react context.
+ * 2. We need performance, we can't have everything re-rendering because something changes. We need to be careful to watch only the
+ * properties we need in a component.
+ */
 export class ObservableState<T> {
   protected state: T
   private listeners: Listeners<T> = {}
@@ -25,6 +33,12 @@ export class ObservableState<T> {
     return this.state[key]
   }
 
+  /**
+   * Watches for changes in the state referred by the provided key.
+   * @param key the key of the state to watch.
+   * @param listener a function called whenever the value of the state referred by `key` changes.
+   * @returns a function to remove the listener.
+   */
   onChange<K extends keyof T>(key: K, listener: (value: T[K]) => void) {
     this.listeners[key] ??= []
     this.listeners[key]!.push(listener)

package/src/state/WidgetState.ts

@@ -16,6 +16,11 @@ export interface WidgetProperties {
   isMinimized?: boolean,
 }
 
+/**
+ * Holds the full state of the AI Chat Widget.
+ * 
+ * This can be used to fully control the chat widget. This is the model of what gets rendered to the screen.
+ */
 export class WidgetState extends ObservableState<WidgetProperties> {
   readonly chatTabs: ChatTabsController
 

package/src/types.ts

@@ -14,7 +14,17 @@ export interface ButtonAction extends WithStyle {
 }
 
 export interface MinimizedActions {
+  /**
+   * When the chat is minimized, a button to collapse the window is rendered. This function is called whenever this button is clicked.
+   */
   onCollapse?: () => void,
+  /**
+   * If `onCollapse` is clicked, the button to collapse is replaced by a button to expand. This function is called whenever the expand
+   * button is clicked. 
+   */
   onExpand?: () => void,
+  /**
+   * When the chat is minimized, a button to close the window is rendered. This function is called whenever this button is clicked.
+   */
   onClose?: () => void,
 }

package/src/utils/chat.ts

@@ -4,8 +4,14 @@ import { ChatState, MessageInterceptor } from '../state/ChatState'
 import { WidgetState } from '../state/WidgetState'
 import { defaultLanguage } from './programming-languages'
 
+// helps with naming new chats
 let next = 1
 
+/**
+ * Utility for creating a new chat in the chat tabs.
+ * @param widget the widget state.
+ * @param interceptors the interceptors to add the chat.
+ */
 export function createNewChat(widget: WidgetState, interceptors: MessageInterceptor[]) {
   const id = ulid()
   widget.chatTabs.add(new ChatState({ id, initial: { label: `Chat ${next}` }, interceptors }))
@@ -13,6 +19,14 @@ export function createNewChat(widget: WidgetState, interceptors: MessageIntercep
   next++
 }
 
+/**
+ * Builds a conversation context from a ChatState.
+ * 
+ * The conversation context is needed by most backend services.
+ * 
+ * @param state the ChatState to build the context from.
+ * @returns the conversation context ready to be sent to the backend.
+ */
 export function buildConversationContext(state: ChatState): FixedChatRequest['context'] {
   return {
     workspace: state.get('workspace')?.id,
@@ -25,6 +39,6 @@ export function buildConversationContext(state: ChatState): FixedChatRequest['co
     os: navigator.userAgent,
     platform: 'web-widget',
     platform_version: navigator.userAgent,
-    stackspot_ai_version: 'alpha',
+    stackspot_ai_version: '1.0.0',
   }
 }

package/src/utils/date.ts

@@ -8,7 +8,17 @@ const fullFormatOptions: Intl.DateTimeFormatOptions = {
   month: 'long',
 }
 
-
+/**
+ * Formats a date to show at the footer of a chat message.
+ * 
+ * @example
+ * - Today, 14:11
+ * - Yesterday, 09:00
+ * - October 26 at 10:53
+ * @param date the Date to format.
+ * @param language the language to use.
+ * @returns the formatted date.
+ */
 export function formatDateForChatMessage(date: Date, language: Language = getLanguage()) {
   const formatted: string[] = []
   const now = new Date()
@@ -21,13 +31,27 @@ export function formatDateForChatMessage(date: Date, language: Language = getLan
   return formatted.join(', ')
 }
 
+/**
+ * Uses the current language to format dates.
+ * @returns an object containing functions for formatting dates.
+ */
 export function useDateFormatter() {
   const language = useLanguage()
   return {
+    /**
+     * @param date the date to format using {@link formatDateForChatMessage}.
+     * @returns the formatted date according to the current language. If the language changes, this result also changes.
+     */
     formatForChatMessage: (date: Date) => formatDateForChatMessage(date, language),
   }
 }
 
+/**
+ * Subtracts `numberOfDays` from `date`.
+ * @param date 
+ * @param numberOfDays 
+ * @returns the resulting Date object.
+ */
 export function subtractDays(date: Date, numberOfDays: number) {
   return new Date(date.getTime() - 24 * numberOfDays * 60 * 60000)
 }

package/src/utils/download.ts

@@ -1,3 +1,8 @@
+/**
+ * Downloads `text` as a file named `filename`.
+ * @param filename the name of the file.
+ * @param text the content of the file.
+ */
 export function download(filename: string, text: string) {
   const element = document.createElement('a')
   element.setAttribute('href', 'data:text/plain;charset=utf-8,' + encodeURIComponent(text))

package/src/utils/knowledge-source.ts

@@ -1,6 +1,12 @@
 import { DocumentResponse, SourceKnowledgeSource, SourceProjectFile4, SourceStackAi } from '@stack-spot/portal-network/api/ai'
 import { KnowledgeSource } from '../state/ChatEntry'
 
+/**
+ * A document can come from the backend as something that resembles a JSON, but it is not. This function attempts to solve some issues and
+ * still interpret as a JSON.
+ * @param str the malformed JSON.
+ * @returns the object corresponding to parsed JSON or undefined if it wasn't possible to fix it.
+ */
 function attemptToParseMalFormedJson(str: string) {
   try {
     return JSON.parse(str)
@@ -21,6 +27,11 @@ function attemptToParseMalFormedJson(str: string) {
   }
 }
 
+/**
+ * Extracts the important part of a KS document to show for the user.
+ * @param document the document to parse.
+ * @returns an object containing the programming language of the KS, its code snippet and a textual description.
+ */
 export function extractCodeFromKSDocument(document: DocumentResponse): { language?: string, snippet: string, text?: string } {
   const language = (document?.metadata as any)?.language
   if (language) {
@@ -43,6 +54,11 @@ export function extractCodeFromKSDocument(document: DocumentResponse): { languag
   return typeof document === 'object' ? { language: 'json', snippet: JSON.stringify(document, null, 2) } : { snippet: String(document) }
 }
 
+/**
+ * Extracts all knowledge sources from a mix of sources that can be used to shape an AI agent's answer.
+ * @param sources a list with sources of any kind.
+ * @returns a list of knowledge sources in the format expected by the chat.
+ */
 export function genericSourcesToKnowledgeSources(
   sources: (SourceStackAi | SourceKnowledgeSource | SourceProjectFile4)[] | undefined,
 ): KnowledgeSource[] | undefined {

package/src/utils/string.ts

@@ -1,4 +1,8 @@
-// gets the size of a string removing control characters and spaces
+/**
+ * Gets the size of a string removing control characters and spaces
+ * @param str the string to count.
+ * @returns the count value.
+ */
 export function getSizeOfString(str: string): number {
   // eslint-disable-next-line no-control-regex
   const withoutSpacesAndControls = str.replace(/[\u0000-\u001F\u007F-\u009F\u061C\u200E\u200F\u202A-\u202E\u2066-\u2069\s]/g, '')

package/src/utils/url.ts

@@ -0,0 +1,8 @@
+const stkAIDomain = /^https:\/\/ai(\.\w+)?\.stackspot\.com$/
+const localhostDomain = /^http:\/\/localhost:\d+$/
+const aiPrd = 'https://ai.stackspot.com'
+
+export function getUrlToStackSpotAI() {
+  const current = location.origin
+  return stkAIDomain.test(current) || localhostDomain.test(current) ? current : aiPrd
+}

package/src/views/Agents.tsx

@@ -82,6 +82,9 @@ export const Agents = () => {
   return null
 }
 
+/**
+ * Renders the Agent selection form in the Right Panel if this is the panel that is currently opened.
+ */
 const AgentsPanel = () => {
   const t = useTranslate(dictionary)
   const chat = useCurrentChat()

package/src/views/Chat/AgentInfo.tsx

@@ -6,6 +6,9 @@ interface Props {
   agent?: LabeledWithImage,
 }
 
+/**
+ * Renders the avatar of an agent in a message.
+ */
 export const AgentInfo = ({ agent }: Props) => (
   <>
     {agent?.image

package/src/views/Chat/ChatMessage.tsx

@@ -1,7 +1,6 @@
 import { Button, IconBox, Text } from '@citric/core'
 import { Copy, Dislike, DislikeFill, Like, LikeFill, TimesCircle } from '@citric/icons'
 import { Avatar, Badge, IconButton } from '@citric/ui'
-import { aiClient } from '@stack-spot/portal-network'
 import { listToClass } from '@stack-spot/portal-theme'
 import { Dictionary, useTranslate } from '@stack-spot/portal-translate'
 import { useCallback, useMemo, useRef, useState } from 'react'
@@ -11,15 +10,35 @@ import { ChatEntry, SerializableAction, TextChatEntry } from '../../state/ChatEn
 import { useDateFormatter } from '../../utils/date'
 import { AgentInfo } from './AgentInfo'
 import { useChatScrollToBottomEffect } from './chat-scroll'
+import { onCopyAll, onCopyCode, onLikeOrDislike } from './events'
 
-export const ChatMessage = ({ message, username, isLast }: { message: ChatEntry, username: string, isLast: boolean }) => {
+interface Props {
+  /**
+   * The ChatEntry to render.
+   */
+  message: ChatEntry,
+  /**
+   * The name of the user currently logged in (will be used if the agent type of the message is "user").
+   */
+  username: string,
+  /**
+   * Whether or not this is the last message in the chat. This is important for disabling action buttons in messages that are no longer
+   * relevant.
+   */
+  isLast: boolean,
+}
+
+/**
+ * Renders a message (ChatEntry) in the chat.
+ */
+export const ChatMessage = ({ message, username, isLast }: Props) => {
   const t = useTranslate(dictionary)
   const [liked, setLiked] = useState<boolean | undefined>()
   const entry = useChatEntry(message)
   const dateFormatter = useDateFormatter()
   const userInfo = entry.agentType === 'user' ? <Avatar size="xs">{username}</Avatar> : <AgentInfo agent={entry.agent} />
   const date = new Date(entry.updated ?? '')
-  const shouldShowDate = entry.updated && !isNaN(date.getTime())
+  const shouldShowFooter = entry.updated && !isNaN(date.getTime())
   const ref = useRef<HTMLLIElement>(null)
   const widget = useWidget()
   const chat = useCurrentChat()
@@ -43,16 +62,7 @@ export const ChatMessage = ({ message, username, isLast }: { message: ChatEntry,
       if (!entry.messageId || like === liked) return
       setLiked(like)
       try {
-        await aiClient.createEvent.mutate({
-          body: [{
-            feedback: like ? 'LIKE' : 'DISLIKE',
-            message_id: entry.messageId,
-            type: 'user_feedback_provided',
-            code: '',
-            generated_at: Math.floor(new Date().getTime() / 1000),
-            size: 0,
-          }],
-        })
+        await onLikeOrDislike(entry.messageId, like)
       } catch {
         setLiked(liked)
       }
@@ -72,7 +82,10 @@ export const ChatMessage = ({ message, username, isLast }: { message: ChatEntry,
           {entry.badges?.length && <div className="badges">
             {entry.badges.map((b, index) => <Badge key={index} palette={b.color ?? 'cyan'} appearance="square">{b.label}</Badge>)}
           </div>}
-          {entry.type === 'md' ? <Markdown>{entry.content}</Markdown> : <p className="plain-text">{entry.content}</p>}
+          {entry.type === 'md'
+            ? <Markdown onCopyCode={(code) => onCopyCode(code, entry.messageId ?? '', chat)}>{entry.content}</Markdown>
+            : <p className="plain-text">{entry.content}</p>
+          }
           {entry.actions?.length && <div className="actions">
             {entry.actions.map(
               (a, index) => (
@@ -104,10 +117,10 @@ export const ChatMessage = ({ message, username, isLast }: { message: ChatEntry,
           </li>
         ))}</ul>
       </div>}
-      <div className="message-footer">
+      {shouldShowFooter && <div className="message-footer">
         {entry.agentType === 'bot' && !entry.error && <div className="message-actions">
           {entry.type === 'md' && (
-            <IconButton title={t.copy} aria-label={t.copy} onClick={() => navigator.clipboard.writeText(entry.content)}>
+            <IconButton title={t.copy} aria-label={t.copy} onClick={() => onCopyAll(entry, chat)}>
               <Copy />
             </IconButton>
           )}
@@ -122,8 +135,8 @@ export const ChatMessage = ({ message, username, isLast }: { message: ChatEntry,
             </>
           )}
         </div>}
-        {shouldShowDate && <Text appearance="microtext1" className="chat-date">{dateFormatter.formatForChatMessage(date)}</Text>}
-      </div>
+        <Text appearance="microtext1" className="chat-date">{dateFormatter.formatForChatMessage(date)}</Text>
+      </div>}
     </li>
   )
 }

package/src/views/Chat/ChatMessages.tsx

@@ -8,6 +8,9 @@ interface Props {
   chatId: string,
 }
 
+/**
+ * Renders all messages of a chat.
+ */
 export const ChatMessages = ({ chatId, username }: Props) => {
   const messages = useChatMessages(chatId)
   const items = useMemo(