@ragbits/api-client 0.0.2 → 1.3.0

package/README.md

@@ -1,38 +1,54 @@
-# Ragbits API Client
+# @ragbits/api-client
 
-A TypeScript client for communicating with the Ragbits API. This client provides methods for both regular HTTP requests and server-sent events (streaming) functionality.
+A TypeScript client for communicating with the Ragbits API. This client provides type-safe methods for both regular HTTP requests and server-sent events (streaming) functionality.
+
+## Features
+
+- **Type-safe API calls** - Full TypeScript support with predefined endpoints
+- **Streaming support** - Real-time server-sent events with proper error handling
+- **Modern JavaScript** - ES modules and CommonJS support
+- **Abortable requests** - Cancel ongoing requests and streams
+- **Error handling** - Comprehensive error handling with detailed error messages
+- **Zero dependencies** - Lightweight with no runtime dependencies
 
 ## Installation
 
 ```bash
-npm install ragbits-api-client
+npm install @ragbits/api-client
 ```
 
-## Usage
+## Quick Start
 
 ```typescript
-import { RagbitsClient, type ChatResponse } from 'ragbits-api-client'
+import { RagbitsClient } from '@ragbits/api-client'
 
 // Initialize the client
 const client = new RagbitsClient({
     baseUrl: 'http://127.0.0.1:8000', // Optional, defaults to http://127.0.0.1:8000
+    auth: {
+        getToken: () => 'token',
+        onUnauthorized: () => {
+            console.warn('⚠️ Unauthorized')
+        },
+    }, // Optional, used to provide auth details
 })
 
 // Get API configuration
-const config = await client.getConfig()
+const config = await client.makeRequest('/api/config')
 
 // Send a chat message with streaming response
-const cleanup = client.sendChatMessage(
+const cleanup = client.makeStreamRequest(
+    '/api/chat',
     {
         message: 'Hello!',
         history: [],
         context: {}, // Optional
     },
     {
-        onMessage: (data: ChatResponse) => {
+        onMessage: (data) => {
             console.log('Received message:', data)
         },
-        onError: (error: string) => {
+        onError: (error) => {
             console.error('Error:', error)
         },
         onClose: () => {
@@ -45,10 +61,13 @@ const cleanup = client.sendChatMessage(
 cleanup()
 
 // Send feedback
-await client.sendFeedback({
-    message_id: 'message-123',
-    feedback: 'like',
-    payload: { reason: 'helpful' },
+await client.makeRequest('/api/feedback', {
+    method: 'POST',
+    body: {
+        message_id: 'message-123',
+        feedback: 'like',
+        payload: { reason: 'helpful' },
+    },
 })
 ```
 
@@ -61,86 +80,211 @@ The main client class for interacting with the Ragbits API.
 #### Constructor
 
 ```typescript
-new RagbitsClient(config?: { baseUrl?: string })
+new RagbitsClient(config?: ClientConfig)
 ```
 
+**Parameters:**
+
 - `config.baseUrl` (optional): Base URL for the API. Defaults to 'http://127.0.0.1:8000'
+- `config.auth` (optional): An object containing authentication details. Provide `getToken` to automatically attach `Authorization: Bearer <token>` to every request. `onUnauthorized` is called if the library encounters a 401 status code.
+
+**Throws:** `Error` if the base URL is invalid
 
 #### Methods
 
-##### `getConfig()`
+##### `getBaseUrl(): string`
 
-Get the API configuration.
+Get the base URL used by this client.
 
-- Returns: `Promise<Record<string, unknown>>` - API configuration object
+**Returns:** The configured base URL
 
-##### `sendChatMessage(chatRequest, callbacks)`
+##### `async makeRequest<Endpoints, URL>(endpoint, options?): Promise<Result>`
 
-Send a chat message and receive streaming responses.
+Make a type-safe API request to any endpoint. `endpoint` must be one of the key of `Endpoints` type
+that define schema of the available endpoints. All default Ragbits routes are supported out of the box.
 
-- Parameters:
-    - `chatRequest`: ChatRequest
-        - `message`: string - User message
-        - `history`: Array<{ role: string; content: string; id?: string }> - Chat history
-        - `context`: Record<string, unknown> (optional) - Additional context
-    - `callbacks`: StreamCallbacks
-        - `onMessage`: (data: ChatResponse) => void | Promise<void> - Called when a message chunk is received
-        - `onError`: (error: string) => void | Promise<void> - Called when an error occurs
-        - `onClose`: () => void | Promise<void> (optional) - Called when the stream closes
-- Returns: `() => void` - Cleanup function to cancel the stream
+**Parameters:**
 
-##### `sendFeedback(feedbackData)`
+- `endpoint`: API endpoint path (e.g., '/api/config', '/api/feedback')
+- `options` (optional): Request options
+    - `method`: HTTP method (defaults to endpoint's predefined method)
+    - `body`: Request body (typed based on endpoint)
+    - `headers`: Additional headers
+    - `signal`: AbortSignal for cancelling the request
 
-Send feedback for a message.
+**Returns:** Promise with the typed response
 
-- Parameters:
-    - `feedbackData`: FeedbackRequest
-        - `message_id`: string - ID of the message to provide feedback for
-        - `feedback`: string - Type of feedback
-        - `payload`: Record<string, unknown> | null - Additional feedback data
-- Returns: `Promise<Record<string, unknown>>` - Feedback submission response
+**Example:**
 
-## Types
+```typescript
+// GET request
+const config = await client.makeRequest('/api/config')
+
+// POST request
+const feedback = await client.makeRequest('/api/feedback', {
+    method: 'POST',
+    body: {
+        message_id: 'msg-123',
+        feedback: 'like',
+        payload: { rating: 5 },
+    },
+})
 
-### ChatResponse
+// Custom endpoints
+type MyEndpoints = {
+    '/api/my-endpoint': {
+        method: 'GET'
+        request: never
+        response: string
+    }
+}
 
-```typescript
-{
-    type: 'message' | 'reference' | 'state_update' | 'text' | 'message_id'
-    content: any
+// or
+type ExtendedEndpoints = BaseApiEndpoints & {
+    '/api/my-endpoint': {
+        method: 'GET'
+        request: never
+        response: string
+    }
 }
+
+// In case of usage of custom Endpoints, we have to specify the URL as generic parameter
+const myResponse = await client.makeRequest<MyEndpoints, '/api/my-endpoint'>(
+    '/api/my-endpoint'
+)
 ```
 
-### ChatRequest
+##### `makeStreamRequest<Endpoints, URL>(endpoint, data, callbacks, signal?): () => void`
+
+Make a type-safe streaming request to any streaming endpoints. `endpoint` must be one of the key of `Endpoints` type
+that define schema of the available endpoints. All default Ragbits routes are supported out of the box.
+
+**Parameters:**
+
+- `endpoint`: Streaming endpoint path (e.g., '/api/chat')
+- `data`: Request data (typed based on endpoint)
+- `callbacks`: Stream callbacks
+    - `onMessage`: Called when a message chunk is received
+    - `onError`: Called when an error occurs
+    - `onClose`: Called when the stream closes (optional)
+- `signal` (optional): AbortSignal for cancelling the stream
+
+**Returns:** Cleanup function to cancel the stream
+
+**Example:**
 
 ```typescript
-{
-  message: string;
-  history: Array<{
-    role: string;
-    content: string;
-    id?: string;
-  }>;
-  context?: Record<string, unknown>;
+const cleanup = client.makeStreamRequest(
+    '/api/chat',
+    {
+        message: 'Tell me about AI',
+        history: [
+            { role: 'user', content: 'Hello' },
+            { role: 'assistant', content: 'Hi there!' },
+        ],
+        context: { user_id: 'user-123' },
+    },
+    {
+        onMessage: (data) => {
+            switch (data.type) {
+                case 'text':
+                    console.log('Text:', data.content)
+                    break
+                case 'reference':
+                    console.log('Reference:', data.content.title)
+                    break
+                case 'message_id':
+                    console.log('Message ID:', data.content)
+                    break
+            }
+        },
+        onError: (error) => {
+            console.error('Stream error:', error)
+        },
+        onClose: () => {
+            console.log('Stream completed')
+        },
+    }
+)
+
+// Cancel stream
+cleanup()
+
+// Custom endpoints
+type MyEndpoints = {
+    '/api/my-endpoint': {
+        method: 'GET'
+        request: never
+        response: string
+    }
 }
+
+// In case of usage of custom Endpoints, we have to specify the URL as generic parameter
+const cleanup = client.makeStreamRequest<MyEndpoints, '/api/my-endpoint'>(
+    '/api/my-endpoint',
+    ...
+)
 ```
 
-### FeedbackRequest
+## Error Handling
+
+The client provides comprehensive error handling:
 
 ```typescript
-{
-    message_id: string
-    feedback: string
-    payload: Record<string, unknown> | null
+try {
+    const config = await client.makeRequest('/api/config')
+} catch (error) {
+    if (error instanceof Error) {
+        console.error('API Error:', error.message)
+    }
 }
 ```
 
-### StreamCallbacks
+Common error scenarios:
+
+- **Network errors** - Connection failures, timeouts
+- **HTTP errors** - 4xx/5xx status codes
+- **Invalid URLs** - Malformed base URL
+- **Stream errors** - Connection drops, parsing errors
+
+## Aborting Requests
+
+Both regular requests and streams can be aborted:
 
 ```typescript
-{
-  onMessage: (data: ChatResponse) => void | Promise<void>;
-  onError: (error: string) => void | Promise<void>;
-  onClose?: () => void | Promise<void>;
-}
+// Abort regular request
+const controller = new AbortController()
+const request = client.makeRequest('/api/config', {
+    signal: controller.signal,
+})
+controller.abort() // Cancels the request
+
+// Abort stream
+const cleanup = client.makeStreamRequest(
+    '/api/chat',
+    data,
+    callbacks,
+    controller.signal
+)
+controller.abort() // Cancels the stream
+cleanup() // Also cancels the stream
 ```
+
+## Browser Support
+
+This package supports all modern browsers with fetch API support:
+
+- Chrome 42+
+- Firefox 39+
+- Safari 10.1+
+- Edge 14+
+
+## Node.js Support
+
+For Node.js environments, you'll need:
+
+- Node.js 18+
+
+## License
+
+MIT

package/{src/test → __tests__}/utils.ts

@@ -1,4 +1,4 @@
-import type { ConfigResponse } from '../types'
+import type { ConfigResponse } from '../src'
 
 // Shared config response for tests
 export const defaultConfigResponse: ConfigResponse = {
@@ -25,4 +25,21 @@ export const defaultConfigResponse: ConfigResponse = {
         },
     },
     customization: null,
+    user_settings: {
+        form: {
+            title: 'Chat Form',
+            type: 'object',
+            required: ['language'],
+            properties: {
+                language: {
+                    title: 'Language',
+                    description: 'Please select the language',
+                    type: 'string',
+                    enum: ['English', 'Polish'],
+                },
+            },
+        },
+    },
+    debug_mode: false,
+    conversation_history: false,
 }