@ragbits/api-client-react 0.0.3 → 1.3.0

package/README.md

@@ -128,6 +128,56 @@ function ChatComponent() {
 }
 ```
 
+#### Custom Route Call Example
+
+```tsx
+import { useRagbitsCall } from '@ragbits/api-client-react'
+
+type MyEndpoints = {
+    '/api/my-endpoint': {
+        method: 'GET'
+        request: never
+        response: string
+    }
+}
+
+function MyComponent() {
+    // In case of usage of custom Endpoints, we have to specify the URL as generic parameter
+    const custom = useRagbitsCall<MyEndpoints, '/api/my-endpoint'>(
+        '/api/my-endpoint'
+    )
+
+    const handleLoadCustom = async () => {
+        try {
+            await custom.call()
+            console.log('Custom loaded:', custom.data)
+        } catch (error) {
+            console.error('Failed to load custom:', error)
+        }
+    }
+
+    return (
+        <div>
+            <button onClick={handleLoadCustom} disabled={custom.isLoading}>
+                {custom.isLoading
+                    ? 'Loading...'
+                    : custom.data
+                      ? 'Reload custom'
+                      : 'Load custom'}
+            </button>
+
+            {custom.data && (
+                <div>
+                    <h3>Custom loaded successfully</h3>
+                </div>
+            )}
+
+            {custom.error && <p>Error: {custom.error.message}</p>}
+        </div>
+    )
+}
+```
+
 ## API Reference
 
 ### `RagbitsProvider`
@@ -143,13 +193,14 @@ interface RagbitsProviderProps {
 }
 ```
 
-### `useRagbitsCall<T>(endpoint, defaultOptions?)`
+### `useRagbitsCall<Endpoints, URL>(endpoint, defaultOptions?)`
 
-React hook for making type-safe API calls with automatic state management.
+React hook for making type-safe API calls with automatic state management. `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')
 - `defaultOptions` (optional): Default request options
 
 **Returns:**
@@ -165,13 +216,14 @@ interface RagbitsCallResult<T, E = Error> {
 }
 ```
 
-### `useRagbitsStream<T>(endpoint)`
+### `useRagbitsStream<Endpoints, URL>(endpoint)`
 
-React hook for handling streaming responses with automatic state management.
+React hook for handling streaming responses with automatic state management. `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')
 
 **Returns:**
 
@@ -196,43 +248,6 @@ interface RagbitsContextValue {
 }
 ```
 
-## Types
-
-All types from `@ragbits/api-client` are re-exported:
-
-```typescript
-import type {
-    // Core types
-    RagbitsClient,
-    ClientConfig,
-
-    // Request/Response types
-    ChatRequest,
-    FeedbackRequest,
-    ConfigResponse,
-    FeedbackResponse,
-
-    // Message types
-    Message,
-    MessageRole,
-    TypedChatResponse,
-    ChatResponseType,
-
-    // Feedback types
-    FeedbackType,
-
-    // Stream types
-    StreamCallbacks,
-
-    // Endpoint types
-    ApiEndpointPath,
-    StreamingEndpointPath,
-    ApiEndpointResponse,
-    StreamingEndpointStream,
-    TypedApiRequestOptions,
-} from '@ragbits/api-client-react'
-```
-
 ## Browser Support
 
 This package supports all modern browsers with React 16.8+ (for hooks):

package/__tests__/mocks/handlers.ts

@@ -0,0 +1,58 @@
+import { http, HttpResponse } from 'msw'
+import type { FeedbackResponse, ChatResponse } from '@ragbits/api-client'
+import { ChatResponseType } from '@ragbits/api-client'
+import { defaultConfigResponse } from '../utils'
+
+export const handlers = [
+    // Mock /api/config endpoint (GET)
+    http.get('http://127.0.0.1:8000/api/config', () => {
+        return HttpResponse.json(defaultConfigResponse)
+    }),
+
+    // Mock /api/feedback endpoint (POST)
+    http.post('http://127.0.0.1:8000/api/feedback', async ({ request }) => {
+        const _body = await request.json()
+        const response: FeedbackResponse = {
+            status: 'success',
+        }
+        return HttpResponse.json(response)
+    }),
+
+    // Mock /api/chat endpoint for streaming
+    http.post('http://127.0.0.1:8000/api/chat', () => {
+        const encoder = new TextEncoder()
+
+        const stream = new ReadableStream({
+            start(controller) {
+                // Send multiple chunks to simulate streaming with proper TypedChatResponse format
+                const chunks: string[] = [
+                    `data: ${JSON.stringify({ type: ChatResponseType.Text, content: 'Hello' } as ChatResponse)}\n\n`,
+                    `data: ${JSON.stringify({ type: ChatResponseType.Text, content: ' there!' } as ChatResponse)}\n\n`,
+                    `data: ${JSON.stringify({ type: ChatResponseType.MessageId, content: 'msg-123' } as ChatResponse)}\n\n`,
+                    `data: ${JSON.stringify({ type: ChatResponseType.ConversationId, content: 'conv-456' } as ChatResponse)}\n\n`,
+                ]
+
+                let index = 0
+                const sendChunk = () => {
+                    if (index < chunks.length) {
+                        controller.enqueue(encoder.encode(chunks[index]))
+                        index++
+                        setTimeout(sendChunk, 10)
+                    } else {
+                        controller.close()
+                    }
+                }
+
+                sendChunk()
+            },
+        })
+
+        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.tsx

@@ -0,0 +1,120 @@
+import React from 'react'
+import {
+    render,
+    renderHook,
+    RenderOptions,
+    RenderHookOptions,
+    RenderResult,
+} from '@testing-library/react'
+import { RagbitsContextProvider } from '../src'
+import type { ConfigResponse } from '@ragbits/api-client'
+
+interface CustomRenderOptions extends Omit<RenderOptions, 'wrapper'> {
+    baseUrl?: string
+}
+
+interface CustomRenderHookOptions<TProps>
+    extends Omit<RenderHookOptions<TProps>, 'wrapper'> {
+    baseUrl?: string
+}
+
+function createWrapper(baseUrl?: string) {
+    return function Wrapper({ children }: { children: React.ReactNode }) {
+        return (
+            <RagbitsContextProvider baseUrl={baseUrl}>
+                {children}
+            </RagbitsContextProvider>
+        )
+    }
+}
+
+export function renderWithProvider(
+    ui: React.ReactElement,
+    options: CustomRenderOptions = {}
+): RenderResult {
+    const { baseUrl, ...renderOptions } = options
+
+    return render(ui, {
+        wrapper: createWrapper(baseUrl),
+        ...renderOptions,
+    })
+}
+
+export function renderHookWithProvider<TResult, TProps>(
+    hook: (props: TProps) => TResult,
+    options: CustomRenderHookOptions<TProps> = {}
+) {
+    const { baseUrl, ...renderOptions } = options
+
+    return renderHook(hook, {
+        wrapper: createWrapper(baseUrl),
+        ...renderOptions,
+    })
+}
+
+// Default config response used in most tests - matches Python classes
+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: {
+                title: 'Dislike Form',
+                type: 'object',
+                required: ['issue_type', 'feedback'],
+                properties: {
+                    issue_type: {
+                        title: 'Issue Type',
+                        description: 'What was the issue?',
+                        type: 'string',
+                        enum: [
+                            'Incorrect information',
+                            'Not helpful',
+                            'Unclear',
+                            'Other',
+                        ],
+                    },
+                    feedback: {
+                        title: 'Feedback',
+                        description: 'Please provide more details',
+                        type: 'string',
+                        minLength: 1,
+                    },
+                },
+            },
+        },
+    },
+    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,
+}

package/dist/RagbitsContextProvider.d.ts

@@ -0,0 +1,7 @@
+import { type ReactNode } from 'react';
+import type { ClientConfig, RagbitsContextValue } from './index';
+export interface RagbitsContextProviderProps extends ClientConfig {
+    children: ReactNode;
+}
+export declare function RagbitsContextProvider({ children, ...config }: RagbitsContextProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function useRagbitsContext(): RagbitsContextValue;

package/dist/hooks.d.ts

@@ -1,17 +1,19 @@
-import type { ApiEndpointPath, ApiEndpointResponse, TypedApiRequestOptions, StreamingEndpointPath } from '@ragbits/api-client';
+import type { RequestOptions, EndpointDefinition, BaseApiEndpoints, BaseStreamingEndpoints } from '@ragbits/api-client';
 import type { RagbitsCallResult, RagbitsStreamResult } from './types';
 /**
  * Hook for making API calls to Ragbits endpoints
- * - Only predefined routes are allowed
- * - Response type can be overridden with explicit type parameter
+ * - Supports any endpoints by providing `Endpoints` generic argument
  * @param endpoint - The predefined API endpoint
  * @param defaultOptions - Default options for the API call
  */
-export declare function useRagbitsCall<TEndpoint extends ApiEndpointPath, TResponse = ApiEndpointResponse<TEndpoint>>(endpoint: TEndpoint, defaultOptions?: TypedApiRequestOptions<TEndpoint>): RagbitsCallResult<TResponse, Error, TEndpoint>;
+export declare function useRagbitsCall<Endpoints extends {
+    [K in keyof Endpoints]: EndpointDefinition;
+} = BaseApiEndpoints, URL extends keyof Endpoints = keyof Endpoints>(endpoint: URL, defaultOptions?: RequestOptions<URL, Endpoints>): RagbitsCallResult<URL, Endpoints, Error>;
 /**
  * Hook for handling streaming responses from Ragbits endpoints
- * - Only predefined streaming routes are allowed
- * - Response type can be overridden with explicit type parameter
+ * - Supports any streaming endpoints by providing `Endpoints` generic argument
  * @param endpoint - The predefined streaming endpoint
  */
-export declare function useRagbitsStream<TEndpoint extends StreamingEndpointPath>(endpoint: TEndpoint): RagbitsStreamResult<Error, TEndpoint>;
+export declare function useRagbitsStream<Endpoints extends {
+    [K in keyof Endpoints]: EndpointDefinition;
+} = BaseStreamingEndpoints, URL extends keyof Endpoints = keyof Endpoints>(endpoint: URL, customHeaders?: Record<string, string>): RagbitsStreamResult<URL, Endpoints, Error>;

package/dist/index.cjs

@@ -21,7 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  RagbitsProvider: () => RagbitsProvider,
+  RagbitsContextProvider: () => RagbitsContextProvider,
   useRagbitsCall: () => useRagbitsCall,
   useRagbitsContext: () => useRagbitsContext,
   useRagbitsStream: () => useRagbitsStream
@@ -32,12 +32,15 @@ __reExport(index_exports, require("@ragbits/api-client"), module.exports);
 // src/hooks.ts
 var import_react2 = require("react");
 
-// src/RagbitsProvider.tsx
+// src/RagbitsContextProvider.tsx
 var import_react = require("react");
 var import_api_client = require("@ragbits/api-client");
 var import_jsx_runtime = require("react/jsx-runtime");
 var RagbitsContext = (0, import_react.createContext)(null);
-function RagbitsProvider({ children, ...config }) {
+function RagbitsContextProvider({
+  children,
+  ...config
+}) {
   const client = (0, import_react.useMemo)(() => new import_api_client.RagbitsClient(config), [config]);
   const contextValue = (0, import_react.useMemo)(
     () => ({
@@ -60,7 +63,9 @@ function useRagbitsContext() {
 // src/hooks.ts
 function useRagbitsCall(endpoint, defaultOptions) {
   const { client } = useRagbitsContext();
-  const [data, setData] = (0, import_react2.useState)(null);
+  const [data, setData] = (0, import_react2.useState)(
+    null
+  );
   const [error, setError] = (0, import_react2.useState)(null);
   const [isLoading, setIsLoading] = (0, import_react2.useState)(false);
   const abortControllerRef = (0, import_react2.useRef)(null);
@@ -134,7 +139,7 @@ function useRagbitsCall(endpoint, defaultOptions) {
     abort
   };
 }
-function useRagbitsStream(endpoint) {
+function useRagbitsStream(endpoint, customHeaders) {
   const { client } = useRagbitsContext();
   const [isStreaming, setIsStreaming] = (0, import_react2.useState)(false);
   const [error, setError] = (0, import_react2.useState)(null);
@@ -177,14 +182,15 @@ function useRagbitsStream(endpoint) {
             }
           }
         },
-        abortController.signal
+        abortController.signal,
+        customHeaders
       );
       return () => {
         cancel();
         cancelFn();
       };
     },
-    [client, cancel, endpoint, isStreaming]
+    [isStreaming, client, endpoint, customHeaders, cancel]
   );
   return {
     isStreaming,
@@ -195,7 +201,7 @@ function useRagbitsStream(endpoint) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  RagbitsProvider,
+  RagbitsContextProvider,
   useRagbitsCall,
   useRagbitsContext,
   useRagbitsStream,

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export * from '@ragbits/api-client';
 export * from './types';
 export * from './hooks';
-export * from './RagbitsProvider';
+export * from './RagbitsContextProvider';

package/dist/index.js

@@ -4,12 +4,15 @@ export * from "@ragbits/api-client";
 // src/hooks.ts
 import { useState, useCallback, useRef } from "react";
 
-// src/RagbitsProvider.tsx
+// src/RagbitsContextProvider.tsx
 import { createContext, useContext, useMemo } from "react";
 import { RagbitsClient } from "@ragbits/api-client";
 import { jsx } from "react/jsx-runtime";
 var RagbitsContext = createContext(null);
-function RagbitsProvider({ children, ...config }) {
+function RagbitsContextProvider({
+  children,
+  ...config
+}) {
   const client = useMemo(() => new RagbitsClient(config), [config]);
   const contextValue = useMemo(
     () => ({
@@ -32,7 +35,9 @@ function useRagbitsContext() {
 // src/hooks.ts
 function useRagbitsCall(endpoint, defaultOptions) {
   const { client } = useRagbitsContext();
-  const [data, setData] = useState(null);
+  const [data, setData] = useState(
+    null
+  );
   const [error, setError] = useState(null);
   const [isLoading, setIsLoading] = useState(false);
   const abortControllerRef = useRef(null);
@@ -106,7 +111,7 @@ function useRagbitsCall(endpoint, defaultOptions) {
     abort
   };
 }
-function useRagbitsStream(endpoint) {
+function useRagbitsStream(endpoint, customHeaders) {
   const { client } = useRagbitsContext();
   const [isStreaming, setIsStreaming] = useState(false);
   const [error, setError] = useState(null);
@@ -149,14 +154,15 @@ function useRagbitsStream(endpoint) {
             }
           }
         },
-        abortController.signal
+        abortController.signal,
+        customHeaders
       );
       return () => {
         cancel();
         cancelFn();
       };
     },
-    [client, cancel, endpoint, isStreaming]
+    [isStreaming, client, endpoint, customHeaders, cancel]
   );
   return {
     isStreaming,
@@ -166,7 +172,7 @@ function useRagbitsStream(endpoint) {
   };
 }
 export {
-  RagbitsProvider,
+  RagbitsContextProvider,
   useRagbitsCall,
   useRagbitsContext,
   useRagbitsStream

package/dist/types.d.ts

@@ -1,16 +1,20 @@
-import type { StreamCallbacks, RagbitsClient, StreamingEndpointPath, StreamingEndpointRequest, TypedApiRequestOptions, ApiEndpointPath, StreamingEndpointStream } from '@ragbits/api-client';
-export interface RagbitsCallResult<T, E = Error, TEndpoint extends ApiEndpointPath = ApiEndpointPath> {
-    data: T | null;
-    error: E | null;
+import type { StreamCallbacks, RagbitsClient, RequestOptions, EndpointDefinition, BaseApiEndpoints, EndpointRequest, EndpointResponse, BaseStreamingEndpoints } from '@ragbits/api-client';
+export interface RagbitsCallResult<URL extends keyof Endpoints, Endpoints extends {
+    [K in keyof Endpoints]: EndpointDefinition;
+} = BaseApiEndpoints, Err = Error> {
+    data: EndpointResponse<URL, Endpoints> | null;
+    error: Err | null;
     isLoading: boolean;
-    call: (options?: TypedApiRequestOptions<TEndpoint>) => Promise<T>;
+    call: (options?: RequestOptions<URL, Endpoints>) => Promise<EndpointResponse<URL, Endpoints>>;
     reset: () => void;
     abort: () => void;
 }
-export interface RagbitsStreamResult<E = Error, TEndpoint extends StreamingEndpointPath = StreamingEndpointPath> {
+export interface RagbitsStreamResult<URL extends keyof Endpoints, Endpoints extends {
+    [K in keyof Endpoints]: EndpointDefinition;
+} = BaseStreamingEndpoints, Err = Error> {
     isStreaming: boolean;
-    error: E | null;
-    stream: (data: StreamingEndpointRequest<TEndpoint>, callbacks: StreamCallbacks<StreamingEndpointStream<TEndpoint>, string>) => () => void;
+    error: Err | null;
+    stream: (data: EndpointRequest<URL, Endpoints>, callbacks: StreamCallbacks<EndpointResponse<URL, Endpoints>, string>) => () => void;
     cancel: () => void;
 }
 export interface RagbitsContextValue {

package/package.json

@@ -1,7 +1,11 @@
 {
     "name": "@ragbits/api-client-react",
-    "version": "0.0.3",
+    "version": "1.3.0",
     "description": "React hooks for the Ragbits API client",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/deepsense-ai/ragbits"
+    },
     "main": "dist/index.cjs",
     "module": "dist/index.js",
     "types": "dist/index.d.ts",
@@ -14,7 +18,7 @@
         }
     },
     "scripts": {
-        "build": "npm run clean && tsup src/index.ts --format cjs,esm && tsc --emitDeclarationOnly --declaration --declarationDir dist --project tsconfig.json",
+        "build": "npm run clean && tsup src/index.ts --format cjs,esm && tsc --emitDeclarationOnly --declaration --project tsconfig.json",
         "dev": "tsc -b . --watch",
         "test": "vitest",
         "test:run": "vitest run",
@@ -22,7 +26,7 @@
         "lint": "eslint .",
         "format": "prettier --write .",
         "format:check": "prettier --check .",
-        "clean": "rm -rf ./dist"
+        "clean": "rm -rf ./dist && rm -f ./tsconfig.tsbuildinfo"
     },
     "peerDependencies": {
         "react": ">=16.8.0",

package/dist/RagbitsProvider.d.ts

@@ -1,7 +0,0 @@
-import { type ReactNode } from 'react';
-import type { ClientConfig, RagbitsContextValue } from './index';
-export interface RagbitsProviderProps extends ClientConfig {
-    children: ReactNode;
-}
-export declare function RagbitsProvider({ children, ...config }: RagbitsProviderProps): import("react/jsx-runtime").JSX.Element;
-export declare function useRagbitsContext(): RagbitsContextValue;