@ragbits/api-client 0.0.1

package/README.md

@@ -0,0 +1,146 @@
+# 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.
+
+## Installation
+
+```bash
+npm install ragbits-api-client
+```
+
+## Usage
+
+```typescript
+import { RagbitsClient, type ChatResponse } 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
+})
+
+// Get API configuration
+const config = await client.getConfig()
+
+// Send a chat message with streaming response
+const cleanup = client.sendChatMessage(
+    {
+        message: 'Hello!',
+        history: [],
+        context: {}, // Optional
+    },
+    {
+        onMessage: (data: ChatResponse) => {
+            console.log('Received message:', data)
+        },
+        onError: (error: string) => {
+            console.error('Error:', error)
+        },
+        onClose: () => {
+            console.log('Stream closed')
+        },
+    }
+)
+
+// Cancel the stream if needed
+cleanup()
+
+// Send feedback
+await client.sendFeedback({
+    message_id: 'message-123',
+    feedback: 'like',
+    payload: { reason: 'helpful' },
+})
+```
+
+## API Reference
+
+### `RagbitsClient`
+
+The main client class for interacting with the Ragbits API.
+
+#### Constructor
+
+```typescript
+new RagbitsClient(config?: { baseUrl?: string })
+```
+
+- `config.baseUrl` (optional): Base URL for the API. Defaults to 'http://127.0.0.1:8000'
+
+#### Methods
+
+##### `getConfig()`
+
+Get the API configuration.
+
+- Returns: `Promise<Record<string, unknown>>` - API configuration object
+
+##### `sendChatMessage(chatRequest, callbacks)`
+
+Send a chat message and receive streaming responses.
+
+- 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
+
+##### `sendFeedback(feedbackData)`
+
+Send feedback for a message.
+
+- 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
+
+## Types
+
+### ChatResponse
+
+```typescript
+{
+    type: 'message' | 'reference' | 'state_update' | 'text' | 'message_id'
+    content: any
+}
+```
+
+### ChatRequest
+
+```typescript
+{
+  message: string;
+  history: Array<{
+    role: string;
+    content: string;
+    id?: string;
+  }>;
+  context?: Record<string, unknown>;
+}
+```
+
+### FeedbackRequest
+
+```typescript
+{
+    message_id: string
+    feedback: string
+    payload: Record<string, unknown> | null
+}
+```
+
+### StreamCallbacks
+
+```typescript
+{
+  onMessage: (data: ChatResponse) => void | Promise<void>;
+  onError: (error: string) => void | Promise<void>;
+  onClose?: () => void | Promise<void>;
+}
+```

package/eslint.config.js

@@ -0,0 +1,21 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import tseslint from 'typescript-eslint'
+
+export default tseslint.config(
+    { ignores: ['dist', 'coverage'] },
+    {
+        extends: [js.configs.recommended, ...tseslint.configs.recommended],
+        files: ['**/*.{ts,tsx}'],
+        languageOptions: {
+            ecmaVersion: 2020,
+            globals: globals.node,
+        },
+        rules: {
+            '@typescript-eslint/no-unused-vars': [
+                'error',
+                { argsIgnorePattern: '^_', varsIgnorePattern: '^_' },
+            ],
+        },
+    }
+)

package/package.json

@@ -0,0 +1,48 @@
+{
+    "name": "@ragbits/api-client",
+    "version": "0.0.1",
+    "description": "JavaScript client for the Ragbits API",
+    "main": "dist/index.cjs",
+    "module": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "type": "module",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js",
+            "require": "./dist/index.cjs"
+        }
+    },
+    "scripts": {
+        "build": "tsup src/index.ts --format cjs,esm --dts",
+        "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+        "test": "vitest",
+        "test:run": "vitest run",
+        "test:coverage": "vitest run --coverage",
+        "lint": "eslint .",
+        "format": "prettier --write .",
+        "format:check": "prettier --check ."
+    },
+    "keywords": [
+        "ragbits",
+        "api",
+        "client"
+    ],
+    "author": "deepsense.ai",
+    "license": "MIT",
+    "devDependencies": {
+        "@eslint/js": "^9.17.0",
+        "@rjsf/utils": "^5.24.12",
+        "@testing-library/jest-dom": "^6.4.0",
+        "@types/node": "^20.0.0",
+        "@vitest/coverage-v8": "^1.6.0",
+        "eslint": "^9.17.0",
+        "globals": "^15.14.0",
+        "msw": "^2.0.0",
+        "prettier": "^3.4.2",
+        "tsup": "^8.0.0",
+        "typescript": "^5.0.0",
+        "typescript-eslint": "^8.18.2",
+        "vitest": "^1.6.0"
+    }
+}

package/prettier.config.js

@@ -0,0 +1,6 @@
+export default {
+    trailingComma: 'es5',
+    tabWidth: 4,
+    semi: false,
+    singleQuote: true,
+}

package/src/index.ts

@@ -0,0 +1,213 @@
+import type {
+    ClientConfig,
+    StreamCallbacks,
+    ApiEndpointPath,
+    ApiEndpointResponse,
+    TypedApiRequestOptions,
+    StreamingEndpointPath,
+    StreamingEndpointRequest,
+    StreamingEndpointStream,
+} from './types'
+
+/**
+ * Client for communicating with the Ragbits API
+ */
+export class RagbitsClient {
+    private readonly baseUrl: string
+
+    /**
+     * @param config - Configuration object
+     */
+    constructor(config: ClientConfig = {}) {
+        this.baseUrl = config.baseUrl || 'http://127.0.0.1:8000'
+
+        // Validate the base URL
+        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(): string {
+        return this.baseUrl
+    }
+
+    /**
+     * Build full API URL from path
+     * @private
+     */
+    private _buildApiUrl(path: string): string {
+        return `${this.baseUrl}${path}`
+    }
+
+    /**
+     * Make a request to the API
+     * @private
+     */
+    private async _makeRequest(
+        url: string,
+        options: RequestInit = {}
+    ): Promise<Response> {
+        const defaultOptions: RequestInit = {
+            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<T extends ApiEndpointPath>(
+        endpoint: T,
+        options?: TypedApiRequestOptions<T>
+    ): Promise<ApiEndpointResponse<T>> {
+        const {
+            method = 'GET',
+            body,
+            headers = {},
+            ...restOptions
+        } = options || {}
+
+        const requestOptions: RequestInit = {
+            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<T extends StreamingEndpointPath>(
+        endpoint: T,
+        data: StreamingEndpointRequest<T>,
+        callbacks: StreamCallbacks<StreamingEndpointStream<T>>,
+        signal?: AbortSignal
+    ): () => void {
+        let isCancelled = false
+
+        const processStream = async (response: Response): Promise<void> => {
+            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
+                            ) as StreamingEndpointStream<T>
+                            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 (): Promise<void> => {
+            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
+        }
+    }
+}
+
+// Re-export types
+export * from './types'