@ragbits/api-client 0.0.2 → 0.0.3

package/README.md

@@ -1,17 +1,26 @@
-# 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({
@@ -19,20 +28,21 @@ const client = new RagbitsClient({
 })
 
 // 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 +55,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 +74,267 @@ 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'
 
+**Throws:** `Error` if the base URL is invalid
+
 #### Methods
 
-##### `getConfig()`
+##### `getBaseUrl(): string`
+
+Get the base URL used by this client.
+
+**Returns:** The configured base URL
+
+##### `makeRequest<T>(endpoint, options?): Promise<T>`
+
+Make a type-safe API request to predefined endpoints.
+
+**Parameters:**
 
-Get the API configuration.
+- `endpoint`: Predefined 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
 
-- Returns: `Promise<Record<string, unknown>>` - API configuration object
+**Returns:** Promise with the typed response
 
-##### `sendChatMessage(chatRequest, callbacks)`
+**Example:**
 
-Send a chat message and receive streaming responses.
+```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 },
+    },
+})
+```
+
+##### `makeStreamRequest<T>(endpoint, data, callbacks, signal?): () => void`
 
-- 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
+Make a type-safe streaming request to predefined streaming endpoints.
 
-##### `sendFeedback(feedbackData)`
+**Parameters:**
 
-Send feedback for a message.
+- `endpoint`: Predefined 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
 
-- 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
+**Returns:** Cleanup function to cancel the stream
+
+**Example:**
+
+```typescript
+const cleanup = client.makeStreamRequest(
+    '/api/chat',
+    {
+        message: 'Tell me about AI',
+        history: [
+            { role: 'user', content: 'Hello', id: 'msg-1' },
+            { role: 'assistant', content: 'Hi there!', id: 'msg-2' },
+        ],
+        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()
+```
 
 ## Types
 
-### ChatResponse
+### Core Types
+
+#### `ClientConfig`
 
 ```typescript
-{
-    type: 'message' | 'reference' | 'state_update' | 'text' | 'message_id'
-    content: any
+interface ClientConfig {
+    baseUrl?: string
 }
 ```
 
-### ChatRequest
+#### `Message`
 
 ```typescript
-{
-  message: string;
-  history: Array<{
-    role: string;
-    content: string;
-    id?: string;
-  }>;
-  context?: Record<string, unknown>;
+interface Message {
+    role: MessageRole
+    content: string
+    id?: string
+}
+
+enum MessageRole {
+    USER = 'user',
+    ASSISTANT = 'assistant',
+    SYSTEM = 'system',
 }
 ```
 
-### FeedbackRequest
+#### `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: 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 }
+    }
+    customization: UICustomization | null
+}
 ```
 
-### StreamCallbacks
+#### `StreamCallbacks<T, E>`
 
 ```typescript
-{
-  onMessage: (data: ChatResponse) => void | Promise<void>;
-  onError: (error: string) => void | Promise<void>;
-  onClose?: () => void | Promise<void>;
+interface StreamCallbacks<T, E = Error> {
+    onMessage: (data: T) => void | Promise<void>
+    onError: (error: E) => void | Promise<void>
+    onClose?: () => void | Promise<void>
 }
 ```
+
+### 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:
+
+```typescript
+try {
+    const config = await client.makeRequest('/api/config')
+} catch (error) {
+    if (error instanceof Error) {
+        console.error('API Error:', error.message)
+    }
+}
+```
+
+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
+// 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/dist/index.cjs

@@ -22,6 +22,7 @@ var index_exports = {};
 __export(index_exports, {
   ChatResponseType: () => ChatResponseType,
   FeedbackType: () => FeedbackType,
+  LiveUpdateType: () => LiveUpdateType,
   MessageRole: () => MessageRole,
   RagbitsClient: () => RagbitsClient
 });
@@ -41,6 +42,8 @@ var ChatResponseType = /* @__PURE__ */ ((ChatResponseType2) => {
   ChatResponseType2["TEXT"] = "text";
   ChatResponseType2["MESSAGE_ID"] = "message_id";
   ChatResponseType2["CONVERSATION_ID"] = "conversation_id";
+  ChatResponseType2["LIVE_UPDATE"] = "live_update";
+  ChatResponseType2["FOLLOWUP_MESSAGES"] = "followup_messages";
   return ChatResponseType2;
 })(ChatResponseType || {});
 var FeedbackType = /* @__PURE__ */ ((FeedbackType2) => {
@@ -48,6 +51,11 @@ var FeedbackType = /* @__PURE__ */ ((FeedbackType2) => {
   FeedbackType2["DISLIKE"] = "dislike";
   return FeedbackType2;
 })(FeedbackType || {});
+var LiveUpdateType = /* @__PURE__ */ ((LiveUpdateType2) => {
+  LiveUpdateType2["START"] = "START";
+  LiveUpdateType2["FINISH"] = "FINISH";
+  return LiveUpdateType2;
+})(LiveUpdateType || {});
 
 // src/index.ts
 var RagbitsClient = class {
@@ -206,6 +214,7 @@ var RagbitsClient = class {
 0 && (module.exports = {
   ChatResponseType,
   FeedbackType,
+  LiveUpdateType,
   MessageRole,
   RagbitsClient
 });

package/dist/index.d.ts

@@ -1,224 +1,8 @@
-import { RJSFSchema } from '@rjsf/utils';
-
-/**
- * Message roles for chat conversations
- */
-declare enum MessageRole {
-    USER = "user",
-    ASSISTANT = "assistant",
-    SYSTEM = "system"
-}
-/**
- * Message structure for chat conversations
- */
-interface Message {
-    role: MessageRole;
-    content: string;
-    id?: string;
-}
-/**
- * Reference structure for document references
- */
-interface Reference {
-    title: string;
-    content: string;
-    url?: string;
-}
-/**
- * Response types from the API
- */
-declare enum ChatResponseType {
-    MESSAGE = "message",
-    REFERENCE = "reference",
-    STATE_UPDATE = "state_update",
-    TEXT = "text",
-    MESSAGE_ID = "message_id",
-    CONVERSATION_ID = "conversation_id"
-}
-/**
- * Feedback types for user feedback
- */
-declare enum FeedbackType {
-    LIKE = "like",
-    DISLIKE = "dislike"
-}
-/**
- * Server state interface for state updates
- */
-interface ServerState {
-    state: Record<string, unknown>;
-    signature: string;
-}
-/**
- * Specific chat response types
- */
-interface MessageIdChatResponse {
-    type: ChatResponseType.MESSAGE_ID;
-    content: string;
-}
-interface TextChatResponse {
-    type: ChatResponseType.TEXT;
-    content: string;
-}
-interface ReferenceChatResponse {
-    type: ChatResponseType.REFERENCE;
-    content: Reference;
-}
-interface ConversationIdChatResponse {
-    type: ChatResponseType.CONVERSATION_ID;
-    content: string;
-}
-interface StateUpdateChatResponse {
-    type: ChatResponseType.STATE_UPDATE;
-    content: ServerState;
-}
-/**
- * Typed chat response union
- */
-type TypedChatResponse = TextChatResponse | ReferenceChatResponse | MessageIdChatResponse | ConversationIdChatResponse | StateUpdateChatResponse;
-/**
- * Base chat request to the API
- */
-interface ChatRequest {
-    message: string;
-    history: Message[];
-    context?: Record<string, unknown>;
-}
-/**
- * Feedback request to the API
- */
-interface FeedbackRequest {
-    message_id: string;
-    feedback: FeedbackType;
-    payload: Record<string, unknown> | null;
-}
-/**
- * Feedback response from the API
- */
-interface FeedbackResponse {
-    status: string;
-}
-/**
- * UI customization configuration
- */
-interface UICustomization {
-    header: {
-        title?: string;
-        subtitle?: string;
-        logo?: string;
-    };
-    welcome_message?: string;
-}
-/**
- * Configuration response from the API
- */
-interface ConfigResponse {
-    feedback: {
-        like: {
-            enabled: boolean;
-            form: RJSFSchema | null;
-        };
-        dislike: {
-            enabled: boolean;
-            form: RJSFSchema | null;
-        };
-    };
-    customization: UICustomization | null;
-}
-/**
- * Configuration for the client
- */
-interface ClientConfig {
-    baseUrl?: string;
-}
-/**
- * Callbacks for handling streaming responses
- */
-interface StreamCallbacks<T, E = Error> {
-    onMessage: (data: T) => void | Promise<void>;
-    onError: (error: E) => void | Promise<void>;
-    onClose?: () => void | Promise<void>;
-}
-/**
- * Regular API endpoint definitions with their request/response types
- */
-interface ApiEndpoints {
-    '/api/config': {
-        method: 'GET';
-        request: never;
-        response: ConfigResponse;
-    };
-    '/api/feedback': {
-        method: 'POST';
-        request: FeedbackRequest;
-        response: FeedbackResponse;
-    };
-}
-/**
- * Streaming API endpoint definitions with their request/stream response types
- */
-interface StreamingEndpoints {
-    '/api/chat': {
-        method: 'POST';
-        request: ChatRequest;
-        stream: TypedChatResponse;
-    };
-}
-/**
- * Extract endpoint paths as a union type
- */
-type ApiEndpointPath = keyof ApiEndpoints;
-/**
- * Extract streaming endpoint paths as a union type
- */
-type StreamingEndpointPath = keyof StreamingEndpoints;
-/**
- * Extract request type for a specific API endpoint
- */
-type ApiEndpointRequest<T extends ApiEndpointPath> = ApiEndpoints[T]['request'];
-/**
- * Extract response type for a specific API endpoint
- */
-type ApiEndpointResponse<T extends ApiEndpointPath> = ApiEndpoints[T]['response'];
-/**
- * Extract HTTP method for a specific API endpoint
- */
-type ApiEndpointMethod<T extends ApiEndpointPath> = ApiEndpoints[T]['method'];
-/**
- * Extract request type for a specific streaming endpoint
- */
-type StreamingEndpointRequest<T extends StreamingEndpointPath> = StreamingEndpoints[T]['request'];
-/**
- * Extract stream response type for a specific streaming endpoint
- */
-type StreamingEndpointStream<T extends StreamingEndpointPath> = StreamingEndpoints[T]['stream'];
-/**
- * Extract HTTP method for a specific streaming endpoint
- */
-type StreamingEndpointMethod<T extends StreamingEndpointPath> = StreamingEndpoints[T]['method'];
-/**
- * Generic request options for API endpoints with typed methods and body
- */
-interface TypedApiRequestOptions<T extends ApiEndpointPath> {
-    method?: ApiEndpointMethod<T>;
-    body?: ApiEndpointRequest<T> extends never ? undefined : ApiEndpointRequest<T>;
-    headers?: Record<string, string>;
-    signal?: AbortSignal;
-}
-/**
- * Typed request options for specific streaming endpoints
- */
-interface TypedStreamRequestOptions<T extends StreamingEndpointPath> {
-    method?: StreamingEndpointMethod<T>;
-    body?: StreamingEndpointRequest<T>;
-    headers?: Record<string, string>;
-    signal?: AbortSignal;
-}
-
+import type { ClientConfig, StreamCallbacks, ApiEndpointPath, ApiEndpointResponse, TypedApiRequestOptions, StreamingEndpointPath, StreamingEndpointRequest, StreamingEndpointStream } from './types';
 /**
  * Client for communicating with the Ragbits API
  */
-declare class RagbitsClient {
+export declare class RagbitsClient {
     private readonly baseUrl;
     /**
      * @param config - Configuration object
@@ -253,5 +37,4 @@ declare class RagbitsClient {
      */
     makeStreamRequest<T extends StreamingEndpointPath>(endpoint: T, data: StreamingEndpointRequest<T>, callbacks: StreamCallbacks<StreamingEndpointStream<T>>, signal?: AbortSignal): () => void;
 }
-
-export { type ApiEndpointMethod, type ApiEndpointPath, type ApiEndpointRequest, type ApiEndpointResponse, type ApiEndpoints, type ChatRequest, ChatResponseType, type ClientConfig, type ConfigResponse, type FeedbackRequest, type FeedbackResponse, FeedbackType, type Message, MessageRole, RagbitsClient, type Reference, type ServerState, type StreamCallbacks, type StreamingEndpointMethod, type StreamingEndpointPath, type StreamingEndpointRequest, type StreamingEndpointStream, type StreamingEndpoints, type TypedApiRequestOptions, type TypedChatResponse, type TypedStreamRequestOptions, type UICustomization };
+export * from './types';

package/dist/index.js

@@ -12,6 +12,8 @@ var ChatResponseType = /* @__PURE__ */ ((ChatResponseType2) => {
   ChatResponseType2["TEXT"] = "text";
   ChatResponseType2["MESSAGE_ID"] = "message_id";
   ChatResponseType2["CONVERSATION_ID"] = "conversation_id";
+  ChatResponseType2["LIVE_UPDATE"] = "live_update";
+  ChatResponseType2["FOLLOWUP_MESSAGES"] = "followup_messages";
   return ChatResponseType2;
 })(ChatResponseType || {});
 var FeedbackType = /* @__PURE__ */ ((FeedbackType2) => {
@@ -19,6 +21,11 @@ var FeedbackType = /* @__PURE__ */ ((FeedbackType2) => {
   FeedbackType2["DISLIKE"] = "dislike";
   return FeedbackType2;
 })(FeedbackType || {});
+var LiveUpdateType = /* @__PURE__ */ ((LiveUpdateType2) => {
+  LiveUpdateType2["START"] = "START";
+  LiveUpdateType2["FINISH"] = "FINISH";
+  return LiveUpdateType2;
+})(LiveUpdateType || {});
 
 // src/index.ts
 var RagbitsClient = class {
@@ -176,6 +183,7 @@ var RagbitsClient = class {
 export {
   ChatResponseType,
   FeedbackType,
+  LiveUpdateType,
   MessageRole,
   RagbitsClient
 };