feat: typescript docs update (#681)

Author: dazy-ds

packages/ragbits-chat/CHANGELOG.md

@@ -11,7 +11,8 @@
 - Add support for live updates and followup messages (#654)
 - Fix invalid context structure in requests from FE (#663)
 - Arrow Up and Arrow Down now cycle through sent messages in a terminal-like style (#667)
-- Fix followup messages not sending (#670)
+- Fix followup messages not sending (#680)
+- Improve typing of TypeScript libraries (#681)
 
 ## 1.0.0 (2025-06-04)
 

packages/ragbits-chat/src/ragbits/chat/ui-build/assets/FeedbackForm-DGKRWbmP.js renamed to packages/ragbits-chat/src/ragbits/chat/ui-build/assets/FeedbackForm-DMnDoAZy.js

@@ -0,0 +1 @@
+import{aF as a,aG as e,aH as t}from"./index-cNuF2g19.js";const n={renderer:t,...e,...a};var o=n;export{o as default};

packages/ragbits-chat/src/ragbits/chat/ui-build/assets/index-2dLwwTR5.js

@@ -5,7 +5,7 @@
     <link rel="icon" type="image/svg+xml" href="/assets/ragbits-9U4hpuUb.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Ragbits</title>
-    <script type="module" crossorigin src="/assets/index-CHdih0Fl.js"></script>
+    <script type="module" crossorigin src="/assets/index-cNuF2g19.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-BPwdy74I.css">
   </head>
 

packages/ragbits-chat/src/ragbits/chat/ui-build/assets/index-BNuA3Pl6.js

@@ -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):

packages/ragbits-chat/src/ragbits/chat/ui-build/assets/index-CHdih0Fl.js renamed to packages/ragbits-chat/src/ragbits/chat/ui-build/assets/index-cNuF2g19.js

@@ -14,15 +14,15 @@
         }
     },
     "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",
         "test:coverage": "vitest run --coverage",
         "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",

packages/ragbits-chat/src/ragbits/chat/ui-build/index.html

@@ -1,32 +1,35 @@
 import { useState, useCallback, useRef } from 'react'
 import type {
     StreamCallbacks,
-    ApiEndpointPath,
-    ApiEndpointResponse,
-    TypedApiRequestOptions,
-    StreamingEndpointPath,
-    StreamingEndpointStream,
-    StreamingEndpointRequest,
+    EndpointResponse,
+    RequestOptions,
+    EndpointDefinition,
+    BaseApiEndpoints,
+    EndpointRequest,
+    BaseStreamingEndpoints,
 } from '@ragbits/api-client'
 import type { RagbitsCallResult, RagbitsStreamResult } from './types'
 import { useRagbitsContext } from './RagbitsProvider'
 
 /**
  * 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 function useRagbitsCall<
-    TEndpoint extends ApiEndpointPath,
-    TResponse = ApiEndpointResponse<TEndpoint>,
+    Endpoints extends {
+        [K in keyof Endpoints]: EndpointDefinition
+    } = BaseApiEndpoints,
+    URL extends keyof Endpoints = keyof Endpoints,
 >(
-    endpoint: TEndpoint,
-    defaultOptions?: TypedApiRequestOptions<TEndpoint>
-): RagbitsCallResult<TResponse, Error, TEndpoint> {
+    endpoint: URL,
+    defaultOptions?: RequestOptions<URL, Endpoints>
+): RagbitsCallResult<URL, Endpoints, Error> {
     const { client } = useRagbitsContext()
-    const [data, setData] = useState<TResponse | null>(null)
+    const [data, setData] = useState<EndpointResponse<URL, Endpoints> | null>(
+        null
+    )
     const [error, setError] = useState<Error | null>(null)
     const [isLoading, setIsLoading] = useState(false)
     const abortControllerRef = useRef<AbortController | null>(null)
@@ -43,8 +46,8 @@ export function useRagbitsCall<
 
     const call = useCallback(
         async (
-            options: TypedApiRequestOptions<TEndpoint> = {}
-        ): Promise<TResponse> => {
+            options: RequestOptions<URL, Endpoints> = {}
+        ): Promise<EndpointResponse<URL, Endpoints>> => {
             // Abort any existing request only if there's one in progress
             if (abortControllerRef.current && isLoading) {
                 abortControllerRef.current.abort()
@@ -73,18 +76,18 @@ export function useRagbitsCall<
                 }
 
                 // Now we can use the properly typed makeRequest without casting
-                const result = await client.makeRequest(
+                const result = await client.makeRequest<Endpoints>(
                     endpoint,
                     requestOptions
                 )
 
                 // Only update state if request wasn't aborted
                 if (!abortController.signal.aborted) {
-                    setData(result as TResponse)
+                    setData(result)
                     abortControllerRef.current = null
                 }
 
-                return result as TResponse
+                return result
             } catch (err) {
                 // Only update error state if request wasn't aborted
                 if (!abortController.signal.aborted) {
@@ -126,13 +129,15 @@ export function useRagbitsCall<
 
 /**
  * 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 function useRagbitsStream<TEndpoint extends StreamingEndpointPath>(
-    endpoint: TEndpoint
-): RagbitsStreamResult<Error, TEndpoint> {
+export function useRagbitsStream<
+    Endpoints extends {
+        [K in keyof Endpoints]: EndpointDefinition
+    } = BaseStreamingEndpoints,
+    URL extends keyof Endpoints = keyof Endpoints,
+>(endpoint: URL): RagbitsStreamResult<URL, Endpoints, Error> {
     const { client } = useRagbitsContext()
     const [isStreaming, setIsStreaming] = useState(false)
     const [error, setError] = useState<Error | null>(null)
@@ -150,11 +155,8 @@ export function useRagbitsStream<TEndpoint extends StreamingEndpointPath>(
 
     const stream = useCallback(
         (
-            data: StreamingEndpointRequest<TEndpoint>,
-            callbacks: StreamCallbacks<
-                StreamingEndpointStream<TEndpoint>,
-                string
-            >
+            data: EndpointRequest<URL, Endpoints>,
+            callbacks: StreamCallbacks<EndpointResponse<URL, Endpoints>, string>
         ): (() => void) => {
             // Abort any existing stream only if there's one in progress
             if (abortControllerRef.current && isStreaming) {

typescript/@ragbits/api-client-react/README.md

@@ -1,36 +1,44 @@
 import type {
     StreamCallbacks,
     RagbitsClient,
-    StreamingEndpointPath,
-    StreamingEndpointRequest,
-    TypedApiRequestOptions,
-    ApiEndpointPath,
-    StreamingEndpointStream,
+    RequestOptions,
+    EndpointDefinition,
+    BaseApiEndpoints,
+    EndpointRequest,
+    EndpointResponse,
+    BaseStreamingEndpoints,
 } from '@ragbits/api-client'
 
 // React-specific hook result types
 export interface RagbitsCallResult<
-    T,
-    E = Error,
-    TEndpoint extends ApiEndpointPath = ApiEndpointPath,
+    URL extends keyof Endpoints,
+    Endpoints extends {
+        [K in keyof Endpoints]: EndpointDefinition
+    } = BaseApiEndpoints,
+    Err = Error,
 > {
-    data: T | null
-    error: E | null
+    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,
+    URL extends keyof Endpoints,
+    Endpoints extends {
+        [K in keyof Endpoints]: EndpointDefinition
+    } = BaseStreamingEndpoints,
+    Err = Error,
 > {
     isStreaming: boolean
-    error: E | null
+    error: Err | null
     stream: (
-        data: StreamingEndpointRequest<TEndpoint>,
-        callbacks: StreamCallbacks<StreamingEndpointStream<TEndpoint>, string>
+        data: EndpointRequest<URL, Endpoints>,
+        callbacks: StreamCallbacks<EndpointResponse<URL, Endpoints>, string>
     ) => () => void
     cancel: () => void
 }