@ragion/react-hooks 0.1.0-alpha.0

package/README.md

@@ -0,0 +1,40 @@
+# @ragion/react-hooks
+
+React hooks para o Ragion SDK.
+
+## Instalação
+
+```bash
+npm install @ragion/react-hooks @ragion/sdk react
+```
+
+## Uso Básico
+
+```typescript
+import { RagionProvider, useRagionChat } from '@ragion/react-hooks'
+
+function App() {
+  return (
+    <RagionProvider config={{ apiKey: 'sk_...' }}>
+      <ChatComponent />
+    </RagionProvider>
+  )
+}
+
+function ChatComponent() {
+  const { messages, sendMessage } = useRagionChat()
+  // ...
+}
+```
+
+## Hooks Disponíveis
+
+- `useRagionChat` - Chat com streaming
+
+Veja a [documentação completa](../../README.md) para detalhes.
+
+## Build
+
+```bash
+npm run build
+```

package/dist/cjs/hooks/useChat.js

@@ -0,0 +1,166 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useRagionChat = void 0;
+const react_1 = require("react");
+const RagionProvider_1 = require("../providers/RagionProvider");
+const generateMessageId = () => {
+    return `${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+};
+/**
+ * React hook for managing chat conversations with the Ragion API
+ * Handles message state, streaming responses, and conversation flow
+ * @param options - Configuration options for the chat
+ * @param options.sessionId - Session ID for conversation continuity (optional)
+ * @param options.onSessionIdChange - Callback when session ID changes (optional)
+ * @returns Object containing chat state and control methods
+ * @example
+ * ```tsx
+ * const {
+ *   messages,
+ *   sendMessage,
+ *   isStreaming,
+ *   error,
+ *   clearMessages,
+ *   abort
+ * } = useRagionChat();
+ *
+ * // Send a message
+ * sendMessage('Hello!');
+ *
+ * // Clear conversation
+ * clearMessages();
+ *
+ * // Cancel ongoing request
+ * abort();
+ * ```
+ */
+const useRagionChat = (options = {}) => {
+    const { sdk } = (0, RagionProvider_1.useRagionContext)();
+    const { sessionId: initialSessionId, onSessionIdChange } = options;
+    const [messages, setMessages] = (0, react_1.useState)([]);
+    const [isStreaming, setIsStreaming] = (0, react_1.useState)(false);
+    const [error, setError] = (0, react_1.useState)(null);
+    const [sessionId, setSessionId] = (0, react_1.useState)(initialSessionId);
+    const currentControllerRef = (0, react_1.useRef)(null);
+    const currentMessageRef = (0, react_1.useRef)("");
+    const isStreamingRef = (0, react_1.useRef)(false);
+    (0, react_1.useEffect)(() => {
+        if (initialSessionId !== undefined) {
+            setSessionId(initialSessionId);
+        }
+    }, [initialSessionId]);
+    (0, react_1.useEffect)(() => {
+        if (sessionId && onSessionIdChange) {
+            onSessionIdChange(sessionId);
+        }
+    }, [sessionId, onSessionIdChange]);
+    const updateAssistantMessage = (0, react_1.useCallback)((assistantMessageId, content) => {
+        setMessages(prev => {
+            const lastMessage = prev[prev.length - 1];
+            if (lastMessage && lastMessage.role === "assistant" && lastMessage.id === assistantMessageId) {
+                return [
+                    ...prev.slice(0, -1),
+                    Object.assign(Object.assign({}, lastMessage), { content }),
+                ];
+            }
+            return prev;
+        });
+    }, []);
+    const removeAssistantMessage = (0, react_1.useCallback)((assistantMessageId) => {
+        setMessages(prev => {
+            const lastMessage = prev[prev.length - 1];
+            if (lastMessage && lastMessage.id === assistantMessageId) {
+                return prev.slice(0, -1);
+            }
+            return prev;
+        });
+    }, []);
+    const finalizeAssistantMessage = (0, react_1.useCallback)((assistantMessageId) => {
+        setMessages(prev => {
+            const lastMessage = prev[prev.length - 1];
+            if (lastMessage && lastMessage.id === assistantMessageId) {
+                return [
+                    ...prev.slice(0, -1),
+                    Object.assign(Object.assign({}, lastMessage), { id: generateMessageId() }),
+                ];
+            }
+            return prev;
+        });
+    }, []);
+    const resetStreamingState = (0, react_1.useCallback)(() => {
+        currentMessageRef.current = "";
+        isStreamingRef.current = false;
+        setIsStreaming(false);
+        currentControllerRef.current = null;
+    }, []);
+    const sendMessage = (0, react_1.useCallback)((message) => {
+        if (!message.trim() || isStreamingRef.current)
+            return;
+        const userMessage = {
+            id: generateMessageId(),
+            role: "user",
+            content: message.trim(),
+            timestamp: new Date(),
+        };
+        setMessages(prev => [...prev, userMessage]);
+        setError(null);
+        currentMessageRef.current = "";
+        isStreamingRef.current = true;
+        setIsStreaming(true);
+        const assistantMessageId = `streaming-${Date.now()}`;
+        setMessages(prev => [
+            ...prev,
+            {
+                id: assistantMessageId,
+                role: "assistant",
+                content: "",
+                timestamp: new Date(),
+            },
+        ]);
+        const controller = sdk.chat.ask({
+            message: message.trim(),
+            sessionId,
+            onChunk: (chunk) => {
+                currentMessageRef.current += chunk;
+                isStreamingRef.current = true;
+                updateAssistantMessage(assistantMessageId, currentMessageRef.current);
+            },
+            onComplete: () => {
+                finalizeAssistantMessage(assistantMessageId);
+                resetStreamingState();
+            },
+            onError: (err) => {
+                setError(err);
+                removeAssistantMessage(assistantMessageId);
+                resetStreamingState();
+            },
+        });
+        currentControllerRef.current = controller;
+    }, [sdk, sessionId, updateAssistantMessage, finalizeAssistantMessage, removeAssistantMessage, resetStreamingState]);
+    const clearMessages = (0, react_1.useCallback)(() => {
+        if (currentControllerRef.current) {
+            currentControllerRef.current.abort();
+            currentControllerRef.current = null;
+        }
+        setMessages([]);
+        setError(null);
+        resetStreamingState();
+    }, [resetStreamingState]);
+    const abort = (0, react_1.useCallback)(() => {
+        if (currentControllerRef.current) {
+            currentControllerRef.current.abort();
+            currentControllerRef.current = null;
+            resetStreamingState();
+        }
+    }, [resetStreamingState]);
+    return {
+        messages,
+        sendMessage,
+        isStreaming,
+        error,
+        sessionId,
+        clearMessages,
+        abort,
+    };
+};
+exports.useRagionChat = useRagionChat;

package/dist/cjs/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useRagionChat = exports.useRagionContext = exports.RagionProvider = void 0;
+var RagionProvider_1 = require("./providers/RagionProvider");
+Object.defineProperty(exports, "RagionProvider", { enumerable: true, get: function () { return RagionProvider_1.RagionProvider; } });
+Object.defineProperty(exports, "useRagionContext", { enumerable: true, get: function () { return RagionProvider_1.useRagionContext; } });
+var useChat_1 = require("./hooks/useChat");
+Object.defineProperty(exports, "useRagionChat", { enumerable: true, get: function () { return useChat_1.useRagionChat; } });

package/dist/cjs/providers/RagionProvider.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useRagionContext = exports.RagionProvider = void 0;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const sdk_1 = require("@ragion/sdk");
+const react_1 = require("react");
+const RagionContext = (0, react_1.createContext)(null);
+/**
+ * Provider component that initializes and provides the Ragion SDK instance to child components
+ * @param props - Component props
+ * @param props.config - Ragion SDK configuration
+ * @param props.children - Child components that will have access to the SDK
+ * @example
+ * ```tsx
+ * <RagionProvider config={{ apiKey: 'your-api-key' }}>
+ *   <App />
+ * </RagionProvider>
+ * ```
+ */
+const RagionProvider = ({ config, children }) => {
+    const sdk = (0, react_1.useMemo)(() => new sdk_1.RagionSDK(config), [config.apiKey]);
+    const value = (0, react_1.useMemo)(() => ({ sdk }), [sdk]);
+    return (0, jsx_runtime_1.jsx)(RagionContext.Provider, { value: value, children: children });
+};
+exports.RagionProvider = RagionProvider;
+/**
+ * Hook to access the Ragion SDK instance from context
+ * @returns Object containing the SDK instance
+ * @throws {Error} If used outside of RagionProvider
+ * @example
+ * ```tsx
+ * const { sdk } = useRagionContext();
+ * ```
+ */
+const useRagionContext = () => {
+    const context = (0, react_1.useContext)(RagionContext);
+    if (!context) {
+        throw new Error("useRagionContext must be used within a RagionProvider");
+    }
+    return context;
+};
+exports.useRagionContext = useRagionContext;

package/dist/esm/hooks/useChat.js

@@ -0,0 +1,162 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useRagionContext } from "../providers/RagionProvider";
+const generateMessageId = () => {
+    return `${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+};
+/**
+ * React hook for managing chat conversations with the Ragion API
+ * Handles message state, streaming responses, and conversation flow
+ * @param options - Configuration options for the chat
+ * @param options.sessionId - Session ID for conversation continuity (optional)
+ * @param options.onSessionIdChange - Callback when session ID changes (optional)
+ * @returns Object containing chat state and control methods
+ * @example
+ * ```tsx
+ * const {
+ *   messages,
+ *   sendMessage,
+ *   isStreaming,
+ *   error,
+ *   clearMessages,
+ *   abort
+ * } = useRagionChat();
+ *
+ * // Send a message
+ * sendMessage('Hello!');
+ *
+ * // Clear conversation
+ * clearMessages();
+ *
+ * // Cancel ongoing request
+ * abort();
+ * ```
+ */
+export const useRagionChat = (options = {}) => {
+    const { sdk } = useRagionContext();
+    const { sessionId: initialSessionId, onSessionIdChange } = options;
+    const [messages, setMessages] = useState([]);
+    const [isStreaming, setIsStreaming] = useState(false);
+    const [error, setError] = useState(null);
+    const [sessionId, setSessionId] = useState(initialSessionId);
+    const currentControllerRef = useRef(null);
+    const currentMessageRef = useRef("");
+    const isStreamingRef = useRef(false);
+    useEffect(() => {
+        if (initialSessionId !== undefined) {
+            setSessionId(initialSessionId);
+        }
+    }, [initialSessionId]);
+    useEffect(() => {
+        if (sessionId && onSessionIdChange) {
+            onSessionIdChange(sessionId);
+        }
+    }, [sessionId, onSessionIdChange]);
+    const updateAssistantMessage = useCallback((assistantMessageId, content) => {
+        setMessages(prev => {
+            const lastMessage = prev[prev.length - 1];
+            if (lastMessage && lastMessage.role === "assistant" && lastMessage.id === assistantMessageId) {
+                return [
+                    ...prev.slice(0, -1),
+                    Object.assign(Object.assign({}, lastMessage), { content }),
+                ];
+            }
+            return prev;
+        });
+    }, []);
+    const removeAssistantMessage = useCallback((assistantMessageId) => {
+        setMessages(prev => {
+            const lastMessage = prev[prev.length - 1];
+            if (lastMessage && lastMessage.id === assistantMessageId) {
+                return prev.slice(0, -1);
+            }
+            return prev;
+        });
+    }, []);
+    const finalizeAssistantMessage = useCallback((assistantMessageId) => {
+        setMessages(prev => {
+            const lastMessage = prev[prev.length - 1];
+            if (lastMessage && lastMessage.id === assistantMessageId) {
+                return [
+                    ...prev.slice(0, -1),
+                    Object.assign(Object.assign({}, lastMessage), { id: generateMessageId() }),
+                ];
+            }
+            return prev;
+        });
+    }, []);
+    const resetStreamingState = useCallback(() => {
+        currentMessageRef.current = "";
+        isStreamingRef.current = false;
+        setIsStreaming(false);
+        currentControllerRef.current = null;
+    }, []);
+    const sendMessage = useCallback((message) => {
+        if (!message.trim() || isStreamingRef.current)
+            return;
+        const userMessage = {
+            id: generateMessageId(),
+            role: "user",
+            content: message.trim(),
+            timestamp: new Date(),
+        };
+        setMessages(prev => [...prev, userMessage]);
+        setError(null);
+        currentMessageRef.current = "";
+        isStreamingRef.current = true;
+        setIsStreaming(true);
+        const assistantMessageId = `streaming-${Date.now()}`;
+        setMessages(prev => [
+            ...prev,
+            {
+                id: assistantMessageId,
+                role: "assistant",
+                content: "",
+                timestamp: new Date(),
+            },
+        ]);
+        const controller = sdk.chat.ask({
+            message: message.trim(),
+            sessionId,
+            onChunk: (chunk) => {
+                currentMessageRef.current += chunk;
+                isStreamingRef.current = true;
+                updateAssistantMessage(assistantMessageId, currentMessageRef.current);
+            },
+            onComplete: () => {
+                finalizeAssistantMessage(assistantMessageId);
+                resetStreamingState();
+            },
+            onError: (err) => {
+                setError(err);
+                removeAssistantMessage(assistantMessageId);
+                resetStreamingState();
+            },
+        });
+        currentControllerRef.current = controller;
+    }, [sdk, sessionId, updateAssistantMessage, finalizeAssistantMessage, removeAssistantMessage, resetStreamingState]);
+    const clearMessages = useCallback(() => {
+        if (currentControllerRef.current) {
+            currentControllerRef.current.abort();
+            currentControllerRef.current = null;
+        }
+        setMessages([]);
+        setError(null);
+        resetStreamingState();
+    }, [resetStreamingState]);
+    const abort = useCallback(() => {
+        if (currentControllerRef.current) {
+            currentControllerRef.current.abort();
+            currentControllerRef.current = null;
+            resetStreamingState();
+        }
+    }, [resetStreamingState]);
+    return {
+        messages,
+        sendMessage,
+        isStreaming,
+        error,
+        sessionId,
+        clearMessages,
+        abort,
+    };
+};

package/dist/esm/index.js

@@ -0,0 +1,2 @@
+export { RagionProvider, useRagionContext } from "./providers/RagionProvider";
+export { useRagionChat } from "./hooks/useChat";

package/dist/esm/providers/RagionProvider.js

@@ -0,0 +1,37 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { RagionSDK } from "@ragion/sdk";
+import { createContext, useContext, useMemo } from "react";
+const RagionContext = createContext(null);
+/**
+ * Provider component that initializes and provides the Ragion SDK instance to child components
+ * @param props - Component props
+ * @param props.config - Ragion SDK configuration
+ * @param props.children - Child components that will have access to the SDK
+ * @example
+ * ```tsx
+ * <RagionProvider config={{ apiKey: 'your-api-key' }}>
+ *   <App />
+ * </RagionProvider>
+ * ```
+ */
+export const RagionProvider = ({ config, children }) => {
+    const sdk = useMemo(() => new RagionSDK(config), [config.apiKey]);
+    const value = useMemo(() => ({ sdk }), [sdk]);
+    return _jsx(RagionContext.Provider, { value: value, children: children });
+};
+/**
+ * Hook to access the Ragion SDK instance from context
+ * @returns Object containing the SDK instance
+ * @throws {Error} If used outside of RagionProvider
+ * @example
+ * ```tsx
+ * const { sdk } = useRagionContext();
+ * ```
+ */
+export const useRagionContext = () => {
+    const context = useContext(RagionContext);
+    if (!context) {
+        throw new Error("useRagionContext must be used within a RagionProvider");
+    }
+    return context;
+};

package/dist/hooks/useChat.d.ts

@@ -0,0 +1,43 @@
+import type { ChatMessage } from "@ragion/sdk";
+export interface UseRagionChatOptions {
+    sessionId?: string;
+    onSessionIdChange?: (sessionId: string) => void;
+}
+export interface UseRagionChatReturn {
+    messages: ChatMessage[];
+    sendMessage: (message: string) => void;
+    isStreaming: boolean;
+    error: Error | null;
+    sessionId: string | undefined;
+    clearMessages: () => void;
+    abort: () => void;
+}
+/**
+ * React hook for managing chat conversations with the Ragion API
+ * Handles message state, streaming responses, and conversation flow
+ * @param options - Configuration options for the chat
+ * @param options.sessionId - Session ID for conversation continuity (optional)
+ * @param options.onSessionIdChange - Callback when session ID changes (optional)
+ * @returns Object containing chat state and control methods
+ * @example
+ * ```tsx
+ * const {
+ *   messages,
+ *   sendMessage,
+ *   isStreaming,
+ *   error,
+ *   clearMessages,
+ *   abort
+ * } = useRagionChat();
+ *
+ * // Send a message
+ * sendMessage('Hello!');
+ *
+ * // Clear conversation
+ * clearMessages();
+ *
+ * // Cancel ongoing request
+ * abort();
+ * ```
+ */
+export declare const useRagionChat: (options?: UseRagionChatOptions) => UseRagionChatReturn;

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { RagionProvider, useRagionContext } from "./providers/RagionProvider";
+export type { RagionProviderProps } from "./providers/RagionProvider";
+export { useRagionChat } from "./hooks/useChat";
+export type { UseRagionChatOptions, UseRagionChatReturn } from "./hooks/useChat";

package/dist/providers/RagionProvider.d.ts

@@ -0,0 +1,33 @@
+import { RagionSDK, type RagionConfig } from "@ragion/sdk";
+import { type ReactNode } from "react";
+interface RagionContextType {
+    sdk: RagionSDK;
+}
+export interface RagionProviderProps {
+    config: RagionConfig;
+    children: ReactNode;
+}
+/**
+ * Provider component that initializes and provides the Ragion SDK instance to child components
+ * @param props - Component props
+ * @param props.config - Ragion SDK configuration
+ * @param props.children - Child components that will have access to the SDK
+ * @example
+ * ```tsx
+ * <RagionProvider config={{ apiKey: 'your-api-key' }}>
+ *   <App />
+ * </RagionProvider>
+ * ```
+ */
+export declare const RagionProvider: ({ config, children }: RagionProviderProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * Hook to access the Ragion SDK instance from context
+ * @returns Object containing the SDK instance
+ * @throws {Error} If used outside of RagionProvider
+ * @example
+ * ```tsx
+ * const { sdk } = useRagionContext();
+ * ```
+ */
+export declare const useRagionContext: () => RagionContextType;
+export {};

package/package.json

@@ -0,0 +1,56 @@
+{
+	"name": "@ragion/react-hooks",
+	"version": "0.1.0-alpha.0",
+	"description": "React hooks for Ragion SDK - External integrations with x-Api-Key",
+	"main": "./dist/cjs/index.js",
+	"module": "./dist/esm/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"import": "./dist/esm/index.js",
+			"require": "./dist/cjs/index.js",
+			"types": "./dist/index.d.ts"
+		}
+	},
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"build": "rimraf dist && tsc && tsc --project tsconfig.esm.json",
+		"dev": "tsc --watch",
+		"clean": "rimraf dist"
+	},
+	"peerDependencies": {
+		"@ragion/sdk": "^0.1.0-alpha.0",
+		"react": ">=18.0.0"
+	},
+	"keywords": [
+		"ragion",
+		"rag",
+		"ai",
+		"chat",
+		"react",
+		"hooks"
+	],
+	"author": "Ragion",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/ragion/ragion-app"
+	},
+	"engines": {
+		"node": ">=18.0.0"
+	},
+	"devDependencies": {
+		"@types/node": "^25.0.0",
+		"@types/react": "^19.2.13",
+		"eslint": "^9.18.0",
+		"eslint-config-prettier": "^10.0.1",
+		"eslint-plugin-prettier": "^5.2.2",
+		"prettier": "^3.4.2",
+		"rimraf": "^5.0.0",
+		"ts-node": "^10.9.2",
+		"typescript": "^5.6.3",
+		"typescript-eslint": "^8.20.0"
+	}
+}