@ibti-tech/chatbot 0.2.0 → 0.5.7

package/README.md

@@ -1,36 +1,478 @@
-# IBTI Chatbot
+# @ibti-tech/chatbot
 
-IBTI Chatbot is an assistent designed to provide intelligent responses and assist users effectively according to ibti available data from website and blog.
+A modern and customizable React chatbot component developed by IBTI Soluções em TI. This package provides an intelligent conversational interface that can be easily integrated into any React application.
 
-## How to use on your project
+## 📋 Features
 
-1. Install using yarn or npm
+- 🎨 **Customizable themes**: Support for light and dark themes
+- 🌍 **Internationalization**: Support for Brazilian Portuguese (pt-BR) and English (en)
+- 💬 **Modern interface**: Responsive and intuitive design
+- ⚡ **Optimized performance**: Built with ESBuild for maximum performance
+- 🔌 **Easy integration**: Simple React component to use
+- 📱 **Responsive**: Works perfectly on desktop and mobile
 
-```sh
-  yarn add @ibti-tech/chatbot | npm install @ibti-tech/chatbot
+## 📦 Installation
+
+Install the package using yarn or npm:
+
+```bash
+# Using yarn
+yarn add @ibti-tech/chatbot
+
+# Using npm
+npm install @ibti-tech/chatbot
+```
+
+## 🚀 Basic Usage
+
+### Import
+
+```jsx
+import { ChatbotProvider, ChatbotBar } from '@ibti-tech/chatbot'
+```
+
+### Minimal Example
+
+```jsx
+import React from 'react'
+import { ChatbotProvider, ChatbotBar } from '@ibti-tech/chatbot'
+
+function App() {
+  return (
+    <ChatbotProvider
+      locale="pt-BR"
+      apiURL="https://api.example.com"
+      theme="dark"
+    >
+      <ChatbotBar />
+    </ChatbotProvider>
+  )
+}
+
+export default App
+```
+
+## 📚 Available Components
+
+### `ChatbotProvider`
+
+Context component that provides chatbot configuration and state to child components.
+
+#### Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `locale` | `'pt-BR' \| 'en'` | ✅ | Chatbot interface language |
+| `apiURL` | `string` | ✅ | Chatbot backend API URL |
+| `theme` | `'light' \| 'dark'` | ✅ | Chatbot visual theme |
+| `isOpen` | `boolean` | ❌ | Controls if the chatbot is initially open. Default: `false` |
+| `texts` | `ChatbotTypes.Texts` | ❌ | Custom texts to override default translations. See [Custom Texts](#custom-texts) section |
+| `children` | `ReactNode` | ❌ | Child components to be rendered |
+
+### `ChatbotBar`
+
+Main component that displays the chatbot bar with toggle button and conversation interface.
+
+#### Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `verticalPosition` | `'top' \| 'bottom'` | ❌ | Vertical position of the chatbot. Default: `'bottom'` |
+| `horizontalPosition` | `'left' \| 'right'` | ❌ | Horizontal position of the chatbot. Default: `'right'` |
+
+### `ChatbotDevice`
+
+Alternative component that can be used to display the chatbot on different devices or layouts.
+
+#### Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `verticalPosition` | `'top' \| 'bottom'` | ❌ | Vertical position of the chatbot. Default: `'bottom'` |
+
+## 🎨 Themes
+
+The chatbot supports two themes:
+
+- **`light`**: Light theme with bright colors
+- **`dark`**: Dark theme with dark colors
+
+```jsx
+<ChatbotProvider theme="dark" ...>
+  <ChatbotBar />
+</ChatbotProvider>
+```
+
+## 🌍 Localization
+
+The chatbot supports the following languages:
+
+- **`pt-BR`**: Brazilian Portuguese
+- **`en`**: English
+
+```jsx
+<ChatbotProvider locale="pt-BR" ...>
+  <ChatbotBar />
+</ChatbotProvider>
 ```
 
-2. Import Chatbot component into your react application and use it as a component
+### Custom Texts
+
+You can customize all texts in the chatbot interface by passing a `texts` prop to `ChatbotProvider`. This allows you to override default translations for any locale.
 
 ```jsx
-import { Chatbot } from '@ibti-tech/chatbot'
+<ChatbotProvider
+  locale="pt-BR"
+  apiURL="https://api.example.com"
+  theme="dark"
+  texts={{
+    'pt-BR': {
+      CHATBOT_NAME: 'Meu Assistente',
+      INPUT_PLACEHOLDER: 'Digite sua mensagem...',
+      CHATBOT_BAR: {
+        OPEN: 'Abrir chat',
+        CLOSE: 'Fechar chat',
+      },
+      CHAT_FEEDBACK: {
+        TITLE: 'Avalie esta resposta',
+        DESCRIPTION: 'Sua opinião nos ajuda a melhorar',
+        MESSAGE_FIELD: 'Mensagem (opcional)',
+        SUBMIT_BUTTON: 'Enviar',
+        CLOSE_BUTTON: 'Fechar',
+        RATE: 'Avaliar',
+      },
+      SUGGESTED_QUESTIONS: {
+        TITLE: 'Perguntas sugeridas',
+        LOADING: 'Carregando...',
+      },
+      STATUS: {
+        ONLINE: 'Online',
+        LOADING: 'Carregando',
+        WRITING: 'Digitando...',
+        UNAVAILABLE: 'Indisponível',
+        INACTIVE: 'Inativo',
+      },
+      ERRORS: {
+        UNKNOWN: 'Erro desconhecido',
+      },
+      MESSAGE_ACTIONS: {
+        COPY: 'Copiar',
+        SHARE: 'Compartilhar',
+        RESEND: 'Reenviar',
+      },
+      USER_LABEL: 'Você',
+      WRITING_MESSAGE: 'Digitando...',
+    },
+    'en': {
+      CHATBOT_NAME: 'My Assistant',
+      // ... other custom texts
+    },
+  }}
+>
+  <ChatbotBar />
+</ChatbotProvider>
 ```
 
-3. Use the component
+**Available text keys:**
+- `CHATBOT_NAME`: Name displayed in the chatbot header
+- `INPUT_PLACEHOLDER`: Placeholder text for the input field
+- `CHATBOT_BAR.OPEN`: Text for opening the chatbot
+- `CHATBOT_BAR.CLOSE`: Text for closing the chatbot
+- `CHAT_FEEDBACK.*`: All feedback form texts
+- `SUGGESTED_QUESTIONS.*`: Suggested questions section texts
+- `STATUS.*`: Status indicator texts
+- `ERRORS.*`: Error message texts
+- `MESSAGE_ACTIONS.*`: Message action button texts
+- `USER_LABEL`: Label for user messages
+- `WRITING_MESSAGE`: Text shown when the bot is typing
+
+## 📝 Complete Example
 
 ```jsx
-// {...}
-const MyFunctionalComponent = () => {
+import React from 'react'
+import { ChatbotProvider, ChatbotBar } from '@ibti-tech/chatbot'
+
+function MyApp() {
   return (
-    <div>
+    <div className="app">
+      <h1>My Application</h1>
+      
+      {/* Other components of your application */}
+      
       <ChatbotProvider
         locale="pt-BR"
-        apiURL="http://localhost:6061"
+        apiURL={process.env.REACT_APP_CHATBOT_API_URL || "http://localhost:6061"}
         theme="dark"
+        isOpen={false}
       >
-        <ChatbotBar />
+        <ChatbotBar 
+          verticalPosition="bottom"
+          horizontalPosition="right"
+        />
       </ChatbotProvider>
     </div>
   )
 }
+
+export default MyApp
 ```
+
+## 🎛️ Advanced Configuration
+
+### Positioning the Chatbot
+
+You can control the position of the chatbot using the `ChatbotBar` component props:
+
+```jsx
+// Bottom right (default)
+<ChatbotBar />
+
+// Top right
+<ChatbotBar verticalPosition="top" />
+
+// Bottom left
+<ChatbotBar horizontalPosition="left" />
+
+// Top left
+<ChatbotBar 
+  verticalPosition="top" 
+  horizontalPosition="left" 
+/>
+```
+
+### Controlling Initial State
+
+Use the `isOpen` prop to control whether the chatbot starts open or closed:
+
+```jsx
+<ChatbotProvider
+  locale="pt-BR"
+  apiURL="https://api.example.com"
+  theme="dark"
+  isOpen={true}  // Chatbot starts open
+>
+  <ChatbotBar />
+</ChatbotProvider>
+```
+
+## 🔧 Requirements
+
+### Peer Dependencies
+
+This package requires the following dependencies that must be installed in your project:
+
+- `react`: `^18.2.0`
+- `react-dom`: `^18.2.0`
+- `lodash`: `^4.17.21`
+- `nookies`: `^2.5.2`
+
+Make sure these dependencies are installed:
+
+```bash
+yarn add react react-dom lodash nookies
+# or
+npm install react react-dom lodash nookies
+```
+
+## 📡 Backend API
+
+The chatbot expects the backend API to be configured and accessible at the provided URL. The API must implement the following endpoints:
+
+### Required Endpoints
+
+#### 1. `GET /chat/welcome?locale={locale}`
+
+**Purpose**: Retrieves the welcome message and checks API health/availability.
+
+**Query Parameters**:
+- `locale` (required): The locale code (`'pt-BR'` or `'en'`)
+
+**Response**:
+```json
+{
+  "welcomeMessage": "Hello! How can I help you today?"
+}
+```
+
+**Status Codes**:
+- `200 OK`: API is available and welcome message is returned
+- `4xx/5xx`: API is considered unavailable
+
+**Notes**:
+- This endpoint is used for health checks (via `HEAD` or `GET` requests)
+- The chatbot uses this to determine connection status
+- Should return a welcome message appropriate for the specified locale
+
+---
+
+#### 2. `POST /chat/completion?locale={locale}`
+
+**Purpose**: Sends a chat message and receives a streaming response from the AI assistant.
+
+**Query Parameters**:
+- `locale` (required): The locale code (`'pt-BR'` or `'en'`)
+
+**Request Body**:
+```json
+{
+  "context": [
+    {
+      "role": "user",
+      "content": "What is artificial intelligence?"
+    },
+    {
+      "role": "assistant",
+      "content": "Artificial intelligence (AI) is..."
+    },
+    {
+      "role": "user",
+      "content": "Tell me more about machine learning"
+    }
+  ]
+}
+```
+
+**Request Body Schema**:
+- `context` (required, array): Array of chat messages representing the conversation history
+  - Each item must have:
+    - `role` (required, string): Either `"user"` or `"assistant"`
+    - `content` (required, string): The message content
+  - The array must not be empty
+  - The last message should typically be from the `"user"` role
+
+**Response**:
+- **Content-Type**: `text/event-stream`
+- **Format**: Server-Sent Events (SSE) stream
+- **Body**: Plain text chunks that are concatenated to form the complete response
+
+**Response Headers**:
+```
+Content-Type: text/event-stream
+Cache-Control: no-cache
+Connection: keep-alive
+```
+
+**Status Codes**:
+- `200 OK`: Stream started successfully
+- `429 Too Many Requests`: Rate limit exceeded (should send error message via stream before closing)
+- `4xx/5xx`: Error occurred
+
+**Streaming Behavior**:
+- The response is sent as a continuous stream of text chunks
+- Each chunk is immediately displayed to the user as it arrives
+- The stream ends when the complete response is sent
+- The chatbot accumulates all chunks to form the final message
+
+**Error Handling**:
+- For `429` errors, the API should send a friendly error message via the stream before closing:
+  ```json
+  {"error": "Sorry, too many requests were made. Please try again in a few moments. 😊"}
+  ```
+- For other errors, the stream should be closed and an appropriate HTTP status code returned
+
+**Example Flow**:
+1. Frontend sends POST request with conversation context
+2. Backend starts streaming response chunks
+3. Frontend receives chunks and displays them incrementally
+4. Stream completes when response is finished
+5. Frontend saves the complete message to conversation history
+
+---
+
+#### 3. `POST /chat/feedback`
+
+**Purpose**: Submits user feedback about a chatbot response (rating and optional message).
+
+**Request Body**:
+```json
+{
+  "rating_score": 5,
+  "chat_context": [
+    {
+      "role": "user",
+      "content": "What is AI?"
+    },
+    {
+      "role": "assistant",
+      "content": "Artificial intelligence is..."
+    }
+  ],
+  "locale": "pt-BR",
+  "message": "Very helpful response!"
+}
+```
+
+**Request Body Schema**:
+- `rating_score` (required, number): Rating from 1 to 5 (inclusive)
+  - Valid values: `1`, `2`, `3`, `4`, `5`
+- `chat_context` (required, array): The conversation context that was rated
+  - Same structure as in `/chat/completion` endpoint
+  - Must not be empty
+- `locale` (required, string): The locale code (`'pt-BR'` or `'en'`)
+- `message` (optional, string): Optional feedback message from the user
+
+**Response**:
+- **Status Code**: `200 OK` or `201 Created` (implementation dependent)
+- **Body**: Typically empty or a success confirmation
+
+**Status Codes**:
+- `200 OK` / `201 Created`: Feedback submitted successfully
+- `400 Bad Request`: Invalid request body (invalid rating, missing fields, etc.)
+- `4xx/5xx`: Other errors
+
+**Notes**:
+- This endpoint is called when a user rates a chatbot response
+- The feedback is typically stored for analytics and improvement purposes
+- The endpoint should handle the request asynchronously if possible to avoid blocking the UI
+
+---
+
+### API Requirements Summary
+
+| Endpoint | Method | Purpose | Streaming | Required |
+|----------|--------|---------|-----------|----------|
+| `/chat/welcome` | `GET` | Health check & welcome message | ❌ | ✅ |
+| `/chat/completion` | `POST` | Send message & receive response | ✅ | ✅ |
+| `/chat/feedback` | `POST` | Submit user feedback | ❌ | ✅ |
+
+### Implementation Notes
+
+1. **CORS**: The API must allow cross-origin requests from the frontend domain
+2. **Locale Support**: All endpoints should respect the `locale` parameter and return appropriate content
+3. **Error Handling**: Provide clear error messages in the appropriate locale
+4. **Streaming**: The `/chat/completion` endpoint must support Server-Sent Events (SSE) for real-time response streaming
+5. **Rate Limiting**: Consider implementing rate limiting and return `429` status when exceeded
+6. **Content-Type**: 
+   - Use `application/json` for JSON endpoints
+   - Use `text/event-stream` for streaming endpoints
+
+### Example API Base URL
+
+```jsx
+<ChatbotProvider
+  apiURL="https://api.example.com"  // Base URL without trailing slash
+  // ...
+/>
+```
+
+The chatbot will automatically append the endpoint paths (e.g., `/chat/welcome`, `/chat/completion`, `/chat/feedback`) to this base URL.
+
+## 🐛 Issues and Support
+
+If you encounter any issues or have questions:
+
+1. Check the [complete documentation](https://github.com/ibti-solutions/ibti-chatbot)
+2. Open an [issue on GitHub](https://github.com/ibti-solutions/ibti-chatbot/issues)
+3. Contact the IBTI team
+
+## 📄 License
+
+ISC
+
+## 👥 Author
+
+IBTI Soluções em TI
+
+---
+
+For more information about development and contribution, see the [DEV_NOTES.md](./DEV_NOTES.md) file.