@ibti-tech/chatbot 0.5.6 → 0.5.7

package/README.md

@@ -276,12 +276,186 @@ 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 necessary endpoints for:
+The chatbot expects the backend API to be configured and accessible at the provided URL. The API must implement the following endpoints:
 
-- Sending messages
-- Receiving responses
-- Managing conversation history
-- Suggested questions
+### 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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ibti-tech/chatbot",
-  "version": "0.5.6",
+  "version": "0.5.7",
   "description": "Chatbot developed for IBTI products",
   "packageManager": "yarn@3.6.4",
   "main": "./dist/index.mjs",