@ragbits/api-client 0.0.3 → 1.3.0

package/README.md

@@ -25,6 +25,12 @@ 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
@@ -80,6 +86,7 @@ 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
 
@@ -91,13 +98,14 @@ Get the base URL used by this client.
 
 **Returns:** The configured base URL
 
-##### `makeRequest<T>(endpoint, options?): Promise<T>`
+##### `async makeRequest<Endpoints, URL>(endpoint, options?): Promise<Result>`
 
-Make a type-safe API request to predefined endpoints.
+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:**
 
-- `endpoint`: Predefined API endpoint path (e.g., '/api/config', '/api/feedback')
+- `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)
@@ -121,15 +129,39 @@ const feedback = await client.makeRequest('/api/feedback', {
         payload: { rating: 5 },
     },
 })
+
+// Custom endpoints
+type MyEndpoints = {
+    '/api/my-endpoint': {
+        method: 'GET'
+        request: never
+        response: string
+    }
+}
+
+// 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'
+)
 ```
 
-##### `makeStreamRequest<T>(endpoint, data, callbacks, signal?): () => void`
+##### `makeStreamRequest<Endpoints, URL>(endpoint, data, callbacks, signal?): () => void`
 
-Make a type-safe streaming request to predefined streaming endpoints.
+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`: Predefined streaming endpoint path (e.g., '/api/chat')
+- `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
@@ -147,8 +179,8 @@ const cleanup = client.makeStreamRequest(
     {
         message: 'Tell me about AI',
         history: [
-            { role: 'user', content: 'Hello', id: 'msg-1' },
-            { role: 'assistant', content: 'Hi there!', id: 'msg-2' },
+            { role: 'user', content: 'Hello' },
+            { role: 'assistant', content: 'Hi there!' },
         ],
         context: { user_id: 'user-123' },
     },
@@ -177,105 +209,23 @@ const cleanup = client.makeStreamRequest(
 
 // Cancel stream
 cleanup()
-```
-
-## Types
-
-### Core Types
-
-#### `ClientConfig`
 
-```typescript
-interface ClientConfig {
-    baseUrl?: string
-}
-```
-
-#### `Message`
-
-```typescript
-interface Message {
-    role: MessageRole
-    content: string
-    id?: string
-}
-
-enum MessageRole {
-    USER = 'user',
-    ASSISTANT = 'assistant',
-    SYSTEM = 'system',
-}
-```
-
-#### `ChatRequest`
-
-```typescript
-interface ChatRequest {
-    message: string
-    history: Message[]
-    context?: Record<string, unknown>
-}
-```
-
-#### `TypedChatResponse`
-
-Union type for all possible chat response types:
-
-```typescript
-type TypedChatResponse =
-    | { type: 'text'; content: string }
-    | { type: 'reference'; content: Reference }
-    | { type: 'message_id'; content: string }
-    | { type: 'conversation_id'; content: string }
-    | { type: 'state_update'; content: ServerState }
-```
-
-#### `FeedbackRequest`
-
-```typescript
-interface FeedbackRequest {
-    message_id: string
-    feedback: FeedbackType
-    payload: Record<string, unknown> | null
-}
-
-enum FeedbackType {
-    LIKE = 'like',
-    DISLIKE = 'dislike',
-}
-```
-
-#### `ConfigResponse`
-
-```typescript
-interface ConfigResponse {
-    feedback: {
-        like: { enabled: boolean; form: RJSFSchema | null }
-        dislike: { enabled: boolean; form: RJSFSchema | null }
+// Custom endpoints
+type MyEndpoints = {
+    '/api/my-endpoint': {
+        method: 'GET'
+        request: never
+        response: string
     }
-    customization: UICustomization | null
 }
-```
-
-#### `StreamCallbacks<T, E>`
 
-```typescript
-interface StreamCallbacks<T, E = Error> {
-    onMessage: (data: T) => void | Promise<void>
-    onError: (error: E) => void | Promise<void>
-    onClose?: () => void | Promise<void>
-}
+// 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',
+    ...
+)
 ```
 
-### Advanced Types
-
-The package provides extensive TypeScript support with predefined endpoint types:
-
-- `ApiEndpointPath` - Union of all available API endpoints
-- `StreamingEndpointPath` - Union of all available streaming endpoints
-- `ApiEndpointResponse<T>` - Response type for a specific endpoint
-- `StreamingEndpointStream<T>` - Stream response type for a specific endpoint
-
 ## Error Handling
 
 The client provides comprehensive error handling:

package/__tests__/mocks/handlers.ts

@@ -0,0 +1,98 @@
+import { http, HttpResponse } from 'msw'
+import { defaultConfigResponse } from '../utils'
+
+export const handlers = [
+    // Config endpoint with conditional error handling
+    http.get('http://127.0.0.1:8000/api/config', ({ request }) => {
+        const url = new URL(request.url)
+        if (url.searchParams.get('error') === 'true') {
+            return new HttpResponse(null, { status: 500 })
+        }
+
+        return HttpResponse.json(defaultConfigResponse)
+    }),
+
+    // Feedback endpoint
+    http.post('http://127.0.0.1:8000/api/feedback', async ({ request }) => {
+        const _body = await request.json()
+        return HttpResponse.json({
+            status: 'success',
+        })
+    }),
+
+    // Chat streaming endpoint
+    http.post('http://127.0.0.1:8000/api/chat', ({ request }) => {
+        const url = new URL(request.url)
+
+        // Handle different test scenarios
+        if (url.searchParams.get('error') === 'true') {
+            return new HttpResponse(null, { status: 500 })
+        }
+
+        if (url.searchParams.get('malformed') === 'true') {
+            const encoder = new TextEncoder()
+            const stream = new ReadableStream({
+                start(controller) {
+                    controller.enqueue(encoder.encode('data: invalid-json\n\n'))
+                    controller.close()
+                },
+            })
+            return new HttpResponse(stream, {
+                headers: { 'Content-Type': 'text/event-stream' },
+            })
+        }
+
+        if (url.searchParams.get('empty') === 'true') {
+            return new HttpResponse(null, {
+                headers: { 'Content-Type': 'text/event-stream' },
+            })
+        }
+
+        if (url.searchParams.get('slow') === 'true') {
+            return new Promise((resolve) => {
+                setTimeout(() => {
+                    resolve(
+                        HttpResponse.json({
+                            type: 'text',
+                            content: 'Slow response',
+                        })
+                    )
+                }, 1000)
+            })
+        }
+
+        const encoder = new TextEncoder()
+
+        const stream = new ReadableStream({
+            start(controller) {
+                const messages = [
+                    { type: 'text', content: 'Hello there!' },
+                    { type: 'text', content: 'How can I help you?' },
+                    { type: 'message_id', content: 'msg-123' },
+                    { type: 'conversation_id', content: 'conv-456' },
+                ]
+
+                messages.forEach((message, index) => {
+                    setTimeout(() => {
+                        controller.enqueue(
+                            encoder.encode(
+                                `data: ${JSON.stringify(message)}\n\n`
+                            )
+                        )
+                        if (index === messages.length - 1) {
+                            controller.close()
+                        }
+                    }, index * 10)
+                })
+            },
+        })
+
+        return new HttpResponse(stream, {
+            headers: {
+                'Content-Type': 'text/event-stream',
+                'Cache-Control': 'no-cache',
+                Connection: 'keep-alive',
+            },
+        })
+    }),
+]

package/__tests__/setup.ts

@@ -0,0 +1,23 @@
+import '@testing-library/jest-dom'
+import { beforeAll, afterEach, afterAll } from 'vitest'
+import { setupServer } from 'msw/node'
+import { handlers } from './mocks/handlers'
+
+// Setup MSW server
+export const server = setupServer(...handlers)
+
+beforeAll(() => {
+    // Start the interception on the client side before all tests run.
+    server.listen({ onUnhandledRequest: 'error' })
+})
+
+afterEach(() => {
+    // Reset any request handlers that we may add during the tests,
+    // so they don't affect other tests.
+    server.resetHandlers()
+})
+
+afterAll(() => {
+    // Clean up after the tests are finished.
+    server.close()
+})

package/__tests__/utils.ts

@@ -0,0 +1,45 @@
+import type { ConfigResponse } from '../src'
+
+// Shared config response for tests
+export const defaultConfigResponse: ConfigResponse = {
+    feedback: {
+        like: {
+            enabled: true,
+            form: {
+                title: 'Like Form',
+                type: 'object',
+                required: ['like_reason'],
+                properties: {
+                    like_reason: {
+                        title: 'Like Reason',
+                        description: 'Why do you like this?',
+                        type: 'string',
+                        minLength: 1,
+                    },
+                },
+            },
+        },
+        dislike: {
+            enabled: true,
+            form: null,
+        },
+    },
+    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,
+}