@ragbits/api-client-react 0.0.3

package/README.md

@@ -0,0 +1,253 @@
+# @ragbits/api-client-react
+
+React hooks for the Ragbits API client. This package provides React-friendly hooks built on top of the core `@ragbits/api-client` package with full TypeScript support and automatic state management.
+
+## Features
+
+- **React hooks** - Type-safe hooks for API calls and streaming
+- **Automatic state management** - Loading states, error handling, and data caching
+- **Request cancellation** - Built-in abort functionality for ongoing requests
+- **Streaming support** - Real-time streaming with React state integration
+- **TypeScript support** - Full type safety with predefined endpoints
+- **Context provider** - Easy setup with React Context
+
+## Installation
+
+```bash
+npm install @ragbits/api-client-react
+```
+
+**Note:** This package depends on `@ragbits/api-client` which will be installed automatically.
+
+## Quick Start
+
+### 1. Setup Provider
+
+First, wrap your app with the `RagbitsProvider`:
+
+```tsx
+import { RagbitsProvider } from '@ragbits/api-client-react'
+
+function App() {
+    return (
+        <RagbitsProvider baseUrl="http://localhost:8000">
+            <YourApp />
+        </RagbitsProvider>
+    )
+}
+```
+
+### 2. Hooks Usage Examples
+
+#### API Call Example
+
+```tsx
+import { useRagbitsCall } from '@ragbits/api-client-react'
+
+function ConfigComponent() {
+    const config = useRagbitsCall('/api/config')
+
+    const handleLoadConfig = async () => {
+        try {
+            await config.call()
+            console.log('Config loaded:', config.data)
+        } catch (error) {
+            console.error('Failed to load config:', error)
+        }
+    }
+
+    return (
+        <div>
+            <button onClick={handleLoadConfig} disabled={config.isLoading}>
+                {config.isLoading
+                    ? 'Loading...'
+                    : config.data
+                      ? 'Reload Config'
+                      : 'Load Config'}
+            </button>
+
+            {config.data && (
+                <div>
+                    <h3>Config loaded successfully</h3>
+                </div>
+            )}
+
+            {config.error && <p>Error: {config.error.message}</p>}
+        </div>
+    )
+}
+```
+
+#### Streaming Example
+
+```tsx
+import { useRagbitsStream } from '@ragbits/api-client-react'
+
+function ChatComponent() {
+    const chatStream = useRagbitsStream('/api/chat')
+
+    const handleSendMessage = () => {
+        const chatRequest = {
+            message: 'Hello!',
+            history: [],
+            context: {},
+        }
+
+        chatStream.stream(chatRequest, {
+            onMessage: (chunk) => {
+                console.log('chunk:', chunk)
+            },
+            onError: (error) => {
+                console.error('Stream error:', error)
+            },
+            onClose: () => {
+                console.log('Stream completed')
+            },
+        })
+    }
+
+    return (
+        <div>
+            <button
+                onClick={handleSendMessage}
+                disabled={chatStream.isStreaming}
+            >
+                {chatStream.isStreaming ? 'Streaming...' : 'Send Message'}
+            </button>
+
+            <button
+                onClick={chatStream.cancel}
+                disabled={!chatStream.isStreaming}
+            >
+                Cancel
+            </button>
+
+            {chatStream.error && <p>Error: {chatStream.error.message}</p>}
+        </div>
+    )
+}
+```
+
+## API Reference
+
+### `RagbitsProvider`
+
+Provider component that sets up the `RagbitsClient` instance and provides it to the React context.
+
+**Props:**
+
+```typescript
+interface RagbitsProviderProps {
+    baseUrl?: string // Base URL for the API (default: "http://127.0.0.1:8000")
+    children: ReactNode
+}
+```
+
+### `useRagbitsCall<T>(endpoint, defaultOptions?)`
+
+React hook for making type-safe API calls with automatic state management.
+
+**Parameters:**
+
+- `endpoint`: Predefined API endpoint path (e.g., '/api/config', '/api/feedback')
+- `defaultOptions` (optional): Default request options
+
+**Returns:**
+
+```typescript
+interface RagbitsCallResult<T, E = Error> {
+    data: T | null // Response data
+    error: E | null // Error if request failed
+    isLoading: boolean // Loading state
+    call: (options?) => Promise<T> // Function to make the API call
+    reset: () => void // Reset state to initial values
+    abort: () => void // Abort current request
+}
+```
+
+### `useRagbitsStream<T>(endpoint)`
+
+React hook for handling streaming responses with automatic state management.
+
+**Parameters:**
+
+- `endpoint`: Predefined streaming endpoint path (e.g., '/api/chat')
+
+**Returns:**
+
+```typescript
+interface RagbitsStreamResult<E = Error> {
+    isStreaming: boolean // Whether a stream is active
+    error: E | null // Stream error
+    stream: (data, callbacks) => () => void // Start streaming
+    cancel: () => void // Cancel current stream
+}
+```
+
+### `useRagbitsContext()`
+
+Access the underlying `RagbitsClient` instance directly.
+
+**Returns:**
+
+```typescript
+interface RagbitsContextValue {
+    client: RagbitsClient
+}
+```
+
+## 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):
+
+- 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/RagbitsProvider.d.ts

@@ -0,0 +1,7 @@
+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;

package/dist/hooks.d.ts

@@ -0,0 +1,17 @@
+import type { ApiEndpointPath, ApiEndpointResponse, TypedApiRequestOptions, StreamingEndpointPath } 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
+ * @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>;
+/**
+ * Hook for handling streaming responses from Ragbits endpoints
+ * - Only predefined streaming routes are allowed
+ * - Response type can be overridden with explicit type parameter
+ * @param endpoint - The predefined streaming endpoint
+ */
+export declare function useRagbitsStream<TEndpoint extends StreamingEndpointPath>(endpoint: TEndpoint): RagbitsStreamResult<Error, TEndpoint>;

package/dist/index.cjs

@@ -0,0 +1,203 @@
+"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 __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  RagbitsProvider: () => RagbitsProvider,
+  useRagbitsCall: () => useRagbitsCall,
+  useRagbitsContext: () => useRagbitsContext,
+  useRagbitsStream: () => useRagbitsStream
+});
+module.exports = __toCommonJS(index_exports);
+__reExport(index_exports, require("@ragbits/api-client"), module.exports);
+
+// src/hooks.ts
+var import_react2 = require("react");
+
+// src/RagbitsProvider.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 }) {
+  const client = (0, import_react.useMemo)(() => new import_api_client.RagbitsClient(config), [config]);
+  const contextValue = (0, import_react.useMemo)(
+    () => ({
+      client
+    }),
+    [client]
+  );
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(RagbitsContext.Provider, { value: contextValue, children });
+}
+function useRagbitsContext() {
+  const context = (0, import_react.useContext)(RagbitsContext);
+  if (!context) {
+    throw new Error(
+      "useRagbitsContext must be used within a RagbitsProvider"
+    );
+  }
+  return context;
+}
+
+// src/hooks.ts
+function useRagbitsCall(endpoint, defaultOptions) {
+  const { client } = useRagbitsContext();
+  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);
+  const abort = (0, import_react2.useCallback)(() => {
+    if (!abortControllerRef.current) {
+      return null;
+    }
+    abortControllerRef.current.abort();
+    abortControllerRef.current = null;
+    setIsLoading(false);
+  }, []);
+  const call = (0, import_react2.useCallback)(
+    async (options = {}) => {
+      if (abortControllerRef.current && isLoading) {
+        abortControllerRef.current.abort();
+      }
+      const abortController = new AbortController();
+      abortControllerRef.current = abortController;
+      setIsLoading(true);
+      setError(null);
+      try {
+        const mergedOptions = {
+          ...defaultOptions,
+          ...options,
+          headers: {
+            ...defaultOptions?.headers,
+            ...options.headers
+          }
+        };
+        const requestOptions = {
+          ...mergedOptions,
+          signal: abortController.signal
+        };
+        const result = await client.makeRequest(
+          endpoint,
+          requestOptions
+        );
+        if (!abortController.signal.aborted) {
+          setData(result);
+          abortControllerRef.current = null;
+        }
+        return result;
+      } catch (err) {
+        if (!abortController.signal.aborted) {
+          const error2 = err instanceof Error ? err : new Error("API call failed");
+          setError(error2);
+          abortControllerRef.current = null;
+          throw error2;
+        }
+        throw err;
+      } finally {
+        if (!abortController.signal.aborted) {
+          setIsLoading(false);
+        }
+      }
+    },
+    [client, endpoint, defaultOptions, isLoading]
+  );
+  const reset = (0, import_react2.useCallback)(() => {
+    abort();
+    setData(null);
+    setError(null);
+    setIsLoading(false);
+  }, [abort]);
+  return {
+    data,
+    error,
+    isLoading,
+    call,
+    reset,
+    abort
+  };
+}
+function useRagbitsStream(endpoint) {
+  const { client } = useRagbitsContext();
+  const [isStreaming, setIsStreaming] = (0, import_react2.useState)(false);
+  const [error, setError] = (0, import_react2.useState)(null);
+  const abortControllerRef = (0, import_react2.useRef)(null);
+  const cancel = (0, import_react2.useCallback)(() => {
+    if (!abortControllerRef.current) {
+      return null;
+    }
+    abortControllerRef.current.abort();
+    abortControllerRef.current = null;
+    setIsStreaming(false);
+  }, []);
+  const stream = (0, import_react2.useCallback)(
+    (data, callbacks) => {
+      if (abortControllerRef.current && isStreaming) {
+        abortControllerRef.current.abort();
+      }
+      const abortController = new AbortController();
+      abortControllerRef.current = abortController;
+      setError(null);
+      setIsStreaming(true);
+      const cancelFn = client.makeStreamRequest(
+        endpoint,
+        data,
+        {
+          onMessage: callbacks.onMessage,
+          onError: (err) => {
+            if (!abortController.signal.aborted) {
+              setError(err);
+              setIsStreaming(false);
+              callbacks.onError(err.message);
+            }
+          },
+          onClose: () => {
+            if (!abortController.signal.aborted) {
+              setIsStreaming(false);
+              if (callbacks.onClose) {
+                callbacks.onClose();
+              }
+            }
+          }
+        },
+        abortController.signal
+      );
+      return () => {
+        cancel();
+        cancelFn();
+      };
+    },
+    [client, cancel, endpoint, isStreaming]
+  );
+  return {
+    isStreaming,
+    error,
+    stream,
+    cancel
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  RagbitsProvider,
+  useRagbitsCall,
+  useRagbitsContext,
+  useRagbitsStream,
+  ...require("@ragbits/api-client")
+});

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,173 @@
+// src/index.ts
+export * from "@ragbits/api-client";
+
+// src/hooks.ts
+import { useState, useCallback, useRef } from "react";
+
+// src/RagbitsProvider.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 }) {
+  const client = useMemo(() => new RagbitsClient(config), [config]);
+  const contextValue = useMemo(
+    () => ({
+      client
+    }),
+    [client]
+  );
+  return /* @__PURE__ */ jsx(RagbitsContext.Provider, { value: contextValue, children });
+}
+function useRagbitsContext() {
+  const context = useContext(RagbitsContext);
+  if (!context) {
+    throw new Error(
+      "useRagbitsContext must be used within a RagbitsProvider"
+    );
+  }
+  return context;
+}
+
+// src/hooks.ts
+function useRagbitsCall(endpoint, defaultOptions) {
+  const { client } = useRagbitsContext();
+  const [data, setData] = useState(null);
+  const [error, setError] = useState(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const abortControllerRef = useRef(null);
+  const abort = useCallback(() => {
+    if (!abortControllerRef.current) {
+      return null;
+    }
+    abortControllerRef.current.abort();
+    abortControllerRef.current = null;
+    setIsLoading(false);
+  }, []);
+  const call = useCallback(
+    async (options = {}) => {
+      if (abortControllerRef.current && isLoading) {
+        abortControllerRef.current.abort();
+      }
+      const abortController = new AbortController();
+      abortControllerRef.current = abortController;
+      setIsLoading(true);
+      setError(null);
+      try {
+        const mergedOptions = {
+          ...defaultOptions,
+          ...options,
+          headers: {
+            ...defaultOptions?.headers,
+            ...options.headers
+          }
+        };
+        const requestOptions = {
+          ...mergedOptions,
+          signal: abortController.signal
+        };
+        const result = await client.makeRequest(
+          endpoint,
+          requestOptions
+        );
+        if (!abortController.signal.aborted) {
+          setData(result);
+          abortControllerRef.current = null;
+        }
+        return result;
+      } catch (err) {
+        if (!abortController.signal.aborted) {
+          const error2 = err instanceof Error ? err : new Error("API call failed");
+          setError(error2);
+          abortControllerRef.current = null;
+          throw error2;
+        }
+        throw err;
+      } finally {
+        if (!abortController.signal.aborted) {
+          setIsLoading(false);
+        }
+      }
+    },
+    [client, endpoint, defaultOptions, isLoading]
+  );
+  const reset = useCallback(() => {
+    abort();
+    setData(null);
+    setError(null);
+    setIsLoading(false);
+  }, [abort]);
+  return {
+    data,
+    error,
+    isLoading,
+    call,
+    reset,
+    abort
+  };
+}
+function useRagbitsStream(endpoint) {
+  const { client } = useRagbitsContext();
+  const [isStreaming, setIsStreaming] = useState(false);
+  const [error, setError] = useState(null);
+  const abortControllerRef = useRef(null);
+  const cancel = useCallback(() => {
+    if (!abortControllerRef.current) {
+      return null;
+    }
+    abortControllerRef.current.abort();
+    abortControllerRef.current = null;
+    setIsStreaming(false);
+  }, []);
+  const stream = useCallback(
+    (data, callbacks) => {
+      if (abortControllerRef.current && isStreaming) {
+        abortControllerRef.current.abort();
+      }
+      const abortController = new AbortController();
+      abortControllerRef.current = abortController;
+      setError(null);
+      setIsStreaming(true);
+      const cancelFn = client.makeStreamRequest(
+        endpoint,
+        data,
+        {
+          onMessage: callbacks.onMessage,
+          onError: (err) => {
+            if (!abortController.signal.aborted) {
+              setError(err);
+              setIsStreaming(false);
+              callbacks.onError(err.message);
+            }
+          },
+          onClose: () => {
+            if (!abortController.signal.aborted) {
+              setIsStreaming(false);
+              if (callbacks.onClose) {
+                callbacks.onClose();
+              }
+            }
+          }
+        },
+        abortController.signal
+      );
+      return () => {
+        cancel();
+        cancelFn();
+      };
+    },
+    [client, cancel, endpoint, isStreaming]
+  );
+  return {
+    isStreaming,
+    error,
+    stream,
+    cancel
+  };
+}
+export {
+  RagbitsProvider,
+  useRagbitsCall,
+  useRagbitsContext,
+  useRagbitsStream
+};

package/dist/types.d.ts

@@ -0,0 +1,18 @@
+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;
+    isLoading: boolean;
+    call: (options?: TypedApiRequestOptions<TEndpoint>) => Promise<T>;
+    reset: () => void;
+    abort: () => void;
+}
+export interface RagbitsStreamResult<E = Error, TEndpoint extends StreamingEndpointPath = StreamingEndpointPath> {
+    isStreaming: boolean;
+    error: E | null;
+    stream: (data: StreamingEndpointRequest<TEndpoint>, callbacks: StreamCallbacks<StreamingEndpointStream<TEndpoint>, string>) => () => void;
+    cancel: () => void;
+}
+export interface RagbitsContextValue {
+    client: RagbitsClient;
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+    "name": "@ragbits/api-client-react",
+    "version": "0.0.3",
+    "description": "React hooks for the Ragbits API client",
+    "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": "npm run clean && tsup src/index.ts --format cjs,esm && tsc --emitDeclarationOnly --declaration --declarationDir dist --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"
+    },
+    "peerDependencies": {
+        "react": ">=16.8.0",
+        "react-dom": ">=16.8.0"
+    },
+    "dependencies": {
+        "@ragbits/api-client": "*"
+    },
+    "devDependencies": {
+        "@eslint/js": "^9.17.0",
+        "@testing-library/jest-dom": "^6.4.0",
+        "@testing-library/react": "^14.0.0",
+        "@testing-library/user-event": "^14.5.0",
+        "@types/react": "^18.2.0",
+        "@types/react-dom": "^18.2.0",
+        "@vitest/coverage-v8": "^1.6.0",
+        "eslint": "^9.17.0",
+        "eslint-plugin-react-hooks": "^5.0.0",
+        "eslint-plugin-react-refresh": "^0.4.16",
+        "globals": "^15.14.0",
+        "jsdom": "^23.0.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"
+    },
+    "keywords": [
+        "ragbits",
+        "api",
+        "client",
+        "react"
+    ],
+    "author": "deepsense.ai",
+    "license": "MIT"
+}