@ragbits/api-client 0.0.1 → 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

@@ -0,0 +1,220 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ChatResponseType: () => ChatResponseType,
+  FeedbackType: () => FeedbackType,
+  LiveUpdateType: () => LiveUpdateType,
+  MessageRole: () => MessageRole,
+  RagbitsClient: () => RagbitsClient
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/types.ts
+var MessageRole = /* @__PURE__ */ ((MessageRole2) => {
+  MessageRole2["USER"] = "user";
+  MessageRole2["ASSISTANT"] = "assistant";
+  MessageRole2["SYSTEM"] = "system";
+  return MessageRole2;
+})(MessageRole || {});
+var ChatResponseType = /* @__PURE__ */ ((ChatResponseType2) => {
+  ChatResponseType2["MESSAGE"] = "message";
+  ChatResponseType2["REFERENCE"] = "reference";
+  ChatResponseType2["STATE_UPDATE"] = "state_update";
+  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) => {
+  FeedbackType2["LIKE"] = "like";
+  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 {
+  /**
+   * @param config - Configuration object
+   */
+  constructor(config = {}) {
+    this.baseUrl = config.baseUrl || "http://127.0.0.1:8000";
+    try {
+      new URL(this.baseUrl);
+    } catch {
+      throw new Error(
+        `Invalid base URL: ${this.baseUrl}. Please provide a valid URL.`
+      );
+    }
+    if (this.baseUrl.endsWith("/")) {
+      this.baseUrl = this.baseUrl.slice(0, -1);
+    }
+  }
+  /**
+   * Get the base URL used by this client
+   */
+  getBaseUrl() {
+    return this.baseUrl;
+  }
+  /**
+   * Build full API URL from path
+   * @private
+   */
+  _buildApiUrl(path) {
+    return `${this.baseUrl}${path}`;
+  }
+  /**
+   * Make a request to the API
+   * @private
+   */
+  async _makeRequest(url, options = {}) {
+    const defaultOptions = {
+      headers: {
+        "Content-Type": "application/json"
+      }
+    };
+    const response = await fetch(url, { ...defaultOptions, ...options });
+    if (!response.ok) {
+      throw new Error(`HTTP error! status: ${response.status}`);
+    }
+    return response;
+  }
+  /**
+   * Method to make API requests to known endpoints only
+   * @param endpoint - API endpoint path (must be predefined)
+   * @param options - Typed request options for the specific endpoint
+   */
+  async makeRequest(endpoint, options) {
+    const {
+      method = "GET",
+      body,
+      headers = {},
+      ...restOptions
+    } = options || {};
+    const requestOptions = {
+      method,
+      headers,
+      ...restOptions
+      // This will include signal and other fetch options
+    };
+    if (body && method !== "GET") {
+      requestOptions.body = typeof body === "string" ? body : JSON.stringify(body);
+    }
+    const response = await this._makeRequest(
+      this._buildApiUrl(endpoint),
+      requestOptions
+    );
+    return response.json();
+  }
+  /**
+   * Method for streaming requests to known endpoints only
+   * @param endpoint - Streaming endpoint path (must be predefined)
+   * @param data - Request data
+   * @param callbacks - Stream callbacks
+   * @param signal - Optional AbortSignal for cancelling the request
+   */
+  makeStreamRequest(endpoint, data, callbacks, signal) {
+    let isCancelled = false;
+    const processStream = async (response) => {
+      const reader = response.body?.pipeThrough(new TextDecoderStream()).getReader();
+      if (!reader) {
+        throw new Error("Response body is null");
+      }
+      while (!isCancelled && !signal?.aborted) {
+        try {
+          const { value, done } = await reader.read();
+          if (done) {
+            callbacks.onClose?.();
+            break;
+          }
+          const lines = value.split("\n");
+          for (const line of lines) {
+            if (!line.startsWith("data: ")) continue;
+            try {
+              const jsonString = line.replace("data: ", "").trim();
+              const parsedData = JSON.parse(
+                jsonString
+              );
+              await callbacks.onMessage(parsedData);
+            } catch (parseError) {
+              console.error("Error parsing JSON:", parseError);
+              await callbacks.onError(
+                new Error("Error processing server response")
+              );
+            }
+          }
+        } catch (streamError) {
+          console.error("Stream error:", streamError);
+          await callbacks.onError(new Error("Error reading stream"));
+          break;
+        }
+      }
+    };
+    const startStream = async () => {
+      try {
+        const response = await fetch(this._buildApiUrl(endpoint), {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            Accept: "text/event-stream"
+          },
+          body: JSON.stringify(data),
+          signal
+        });
+        if (!response.ok) {
+          throw new Error(`HTTP error! status: ${response.status}`);
+        }
+        await processStream(response);
+      } catch (error) {
+        if (signal?.aborted) {
+          return;
+        }
+        console.error("Request error:", error);
+        const errorMessage = error instanceof Error ? error.message : "Error connecting to server";
+        await callbacks.onError(new Error(errorMessage));
+      }
+    };
+    try {
+      startStream();
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : "Failed to start stream";
+      callbacks.onError(new Error(errorMessage));
+    }
+    return () => {
+      isCancelled = true;
+    };
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ChatResponseType,
+  FeedbackType,
+  LiveUpdateType,
+  MessageRole,
+  RagbitsClient
+});

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+import type { ClientConfig, StreamCallbacks, ApiEndpointPath, ApiEndpointResponse, TypedApiRequestOptions, StreamingEndpointPath, StreamingEndpointRequest, StreamingEndpointStream } from './types';
+/**
+ * Client for communicating with the Ragbits API
+ */
+export declare class RagbitsClient {
+    private readonly baseUrl;
+    /**
+     * @param config - Configuration object
+     */
+    constructor(config?: ClientConfig);
+    /**
+     * Get the base URL used by this client
+     */
+    getBaseUrl(): string;
+    /**
+     * Build full API URL from path
+     * @private
+     */
+    private _buildApiUrl;
+    /**
+     * Make a request to the API
+     * @private
+     */
+    private _makeRequest;
+    /**
+     * Method to make API requests to known endpoints only
+     * @param endpoint - API endpoint path (must be predefined)
+     * @param options - Typed request options for the specific endpoint
+     */
+    makeRequest<T extends ApiEndpointPath>(endpoint: T, options?: TypedApiRequestOptions<T>): Promise<ApiEndpointResponse<T>>;
+    /**
+     * Method for streaming requests to known endpoints only
+     * @param endpoint - Streaming endpoint path (must be predefined)
+     * @param data - Request data
+     * @param callbacks - Stream callbacks
+     * @param signal - Optional AbortSignal for cancelling the request
+     */
+    makeStreamRequest<T extends StreamingEndpointPath>(endpoint: T, data: StreamingEndpointRequest<T>, callbacks: StreamCallbacks<StreamingEndpointStream<T>>, signal?: AbortSignal): () => void;
+}
+export * from './types';