@cilow/sdk 0.2.0 → 0.2.1

package/dist/react/hooks.d.ts

@@ -0,0 +1,327 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { CilowClient } from '../client.js';
+import { CilowWebSocket } from '../websocket.js';
+import { CilowConfig, WebSocketConfig, CreateMemoryOptions, Memory, SearchResult, CilowEvent, MemoryStats } from '../types.js';
+
+/**
+ * Cilow context value
+ */
+interface CilowContextValue {
+    /** Cilow client instance */
+    client: CilowClient;
+    /** WebSocket connection (if enabled) */
+    ws: CilowWebSocket | null;
+    /** Current user ID */
+    userId?: string;
+    /** Current session ID */
+    sessionId?: string;
+    /** Set user ID */
+    setUserId: (userId: string) => void;
+    /** Set session ID */
+    setSessionId: (sessionId: string) => void;
+    /** Whether WebSocket is connected */
+    isConnected: boolean;
+}
+/**
+ * Props for CilowProvider
+ */
+interface CilowProviderProps extends CilowConfig, Partial<WebSocketConfig> {
+    /** React children */
+    children: ReactNode;
+    /** Initial user ID */
+    userId?: string;
+    /** Initial session ID */
+    sessionId?: string;
+    /** Enable WebSocket connection */
+    enableWebSocket?: boolean;
+}
+/**
+ * CilowProvider - Context provider for Cilow SDK
+ *
+ * @example
+ * ```typescript
+ * function App() {
+ *   return (
+ *     <CilowProvider
+ *       apiUrl="https://api.cilow.ai"
+ *       apiKey="your-key"
+ *       userId="user-123"
+ *       enableWebSocket={true}
+ *     >
+ *       <YourApp />
+ *     </CilowProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function CilowProvider({ children, userId: initialUserId, sessionId: initialSessionId, enableWebSocket, ...config }: CilowProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access Cilow context
+ */
+declare function useCilow(): CilowContextValue;
+/**
+ * State for useMemory hook
+ */
+interface UseMemoryState {
+    /** Store a new memory */
+    remember: (content: string, options?: CreateMemoryOptions) => Promise<string>;
+    /** Delete memories */
+    forget: (filter: {
+        memoryId?: string;
+        tags?: string[];
+    }) => Promise<number>;
+    /** Get a memory by ID */
+    getMemory: (memoryId: string) => Promise<Memory>;
+    /** Loading state */
+    isLoading: boolean;
+    /** Error state */
+    error: Error | null;
+}
+/**
+ * useMemory - Hook for memory CRUD operations
+ *
+ * @example
+ * ```typescript
+ * function MyComponent() {
+ *   const { remember, forget, isLoading, error } = useMemory();
+ *
+ *   const handleSave = async () => {
+ *     await remember("Important information", { tags: ["important"] });
+ *   };
+ *
+ *   const handleDelete = async (memoryId: string) => {
+ *     await forget({ memoryId });
+ *   };
+ *
+ *   return <div>...</div>;
+ * }
+ * ```
+ */
+declare function useMemory(): UseMemoryState;
+/**
+ * State for useRecall hook
+ */
+interface UseRecallState {
+    /** Search results */
+    data: SearchResult[];
+    /** Execute search */
+    search: (query: string, options?: {
+        limit?: number;
+        tags?: string[];
+    }) => Promise<void>;
+    /** Clear results */
+    clear: () => void;
+    /** Loading state */
+    isLoading: boolean;
+    /** Error state */
+    error: Error | null;
+}
+/**
+ * useRecall - Hook for searching memories
+ *
+ * @example
+ * ```typescript
+ * function SearchComponent() {
+ *   const { data, search, isLoading, error } = useRecall();
+ *   const [query, setQuery] = useState('');
+ *
+ *   const handleSearch = () => {
+ *     search(query, { limit: 10 });
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <input value={query} onChange={e => setQuery(e.target.value)} />
+ *       <button onClick={handleSearch} disabled={isLoading}>Search</button>
+ *       {data.map(result => (
+ *         <div key={result.memory.id}>
+ *           <p>{result.memory.content}</p>
+ *           <span>Score: {result.score}</span>
+ *         </div>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useRecall(): UseRecallState;
+/**
+ * Options for useMemorySubscription
+ */
+interface UseMemorySubscriptionOptions {
+    /** Filter by user ID */
+    userId?: string;
+    /** Filter by session ID */
+    sessionId?: string;
+    /** Filter by tags */
+    tags?: string[];
+    /** Event types to subscribe to */
+    eventTypes?: ('memory.created' | 'memory.updated' | 'memory.deleted')[];
+}
+/**
+ * State for useMemorySubscription hook
+ */
+interface UseMemorySubscriptionState {
+    /** Latest event */
+    latestEvent: CilowEvent | null;
+    /** All events received */
+    events: CilowEvent[];
+    /** Whether connected */
+    isConnected: boolean;
+    /** Clear events */
+    clearEvents: () => void;
+}
+/**
+ * useMemorySubscription - Hook for real-time memory updates
+ *
+ * @example
+ * ```typescript
+ * function LiveMemories() {
+ *   const { latestEvent, events, isConnected } = useMemorySubscription({
+ *     userId: 'user-123'
+ *   });
+ *
+ *   useEffect(() => {
+ *     if (latestEvent?.type === 'memory.created') {
+ *       console.log('New memory:', latestEvent.memory);
+ *     }
+ *   }, [latestEvent]);
+ *
+ *   return (
+ *     <div>
+ *       <p>Status: {isConnected ? 'Connected' : 'Disconnected'}</p>
+ *       <p>Events received: {events.length}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useMemorySubscription(options?: UseMemorySubscriptionOptions): UseMemorySubscriptionState;
+/**
+ * useMemoryContext - Hook for getting AI context from memories
+ *
+ * @example
+ * ```typescript
+ * function ChatInput() {
+ *   const { getContext, context, isLoading } = useMemoryContext();
+ *
+ *   const handleSend = async (message: string) => {
+ *     const ctx = await getContext(message);
+ *
+ *     // Use ctx.context as system message or context
+ *     await sendToAI(message, ctx.context);
+ *   };
+ *
+ *   return <input onSubmit={handleSend} />;
+ * }
+ * ```
+ */
+declare function useMemoryContext(): {
+    getContext: (query: string, options?: {
+        maxTokens?: number;
+        tags?: string[];
+    }) => Promise<{
+        context: string;
+        memoriesUsed: number;
+    }>;
+    context: string;
+    memoriesUsed: number;
+    clearContext: () => void;
+    isLoading: boolean;
+    error: Error | null;
+};
+/**
+ * useMemoryStats - Hook for memory statistics
+ *
+ * @example
+ * ```typescript
+ * function StatsPanel() {
+ *   const { stats, refresh, isLoading } = useMemoryStats();
+ *
+ *   return (
+ *     <div>
+ *       <p>Total memories: {stats?.totalMemories ?? 0}</p>
+ *       <p>Hot: {stats?.hotMemories ?? 0}</p>
+ *       <p>Warm: {stats?.warmMemories ?? 0}</p>
+ *       <p>Cold: {stats?.coldMemories ?? 0}</p>
+ *       <button onClick={refresh} disabled={isLoading}>Refresh</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useMemoryStats(): {
+    stats: MemoryStats | null;
+    refresh: () => Promise<void>;
+    isLoading: boolean;
+    error: Error | null;
+};
+/**
+ * useConversation - Hook for storing conversation turns
+ *
+ * @example
+ * ```typescript
+ * function Chat() {
+ *   const { storeConversation, isLoading } = useConversation();
+ *
+ *   const handleMessage = async (userMsg: string, aiResponse: string) => {
+ *     // Store after getting AI response
+ *     await storeConversation(userMsg, aiResponse);
+ *   };
+ *
+ *   return <ChatUI onMessage={handleMessage} />;
+ * }
+ * ```
+ */
+declare function useConversation(): {
+    storeConversation: (userMessage: string, assistantResponse: string, metadata?: Record<string, unknown>) => Promise<string>;
+    storedCount: number;
+    isLoading: boolean;
+    error: Error | null;
+};
+/**
+ * useDebounce - Debounce a value
+ */
+declare function useDebounce<T>(value: T, delay: number): T;
+/**
+ * useDebouncedSearch - Hook for debounced memory search
+ *
+ * @example
+ * ```typescript
+ * function SearchWithDebounce() {
+ *   const { query, setQuery, results, isLoading } = useDebouncedSearch({
+ *     delay: 300
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <input
+ *         value={query}
+ *         onChange={e => setQuery(e.target.value)}
+ *         placeholder="Search memories..."
+ *       />
+ *       {isLoading && <p>Searching...</p>}
+ *       {results.map(r => (
+ *         <div key={r.memory.id}>{r.memory.content}</div>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useDebouncedSearch(options?: {
+    delay?: number;
+    minLength?: number;
+    limit?: number;
+}): {
+    query: string;
+    setQuery: react.Dispatch<react.SetStateAction<string>>;
+    results: SearchResult[];
+    clear: () => void;
+    isLoading: boolean;
+    error: Error | null;
+};
+
+export { type CilowContextValue, CilowProvider, type CilowProviderProps, type UseMemoryState, type UseMemorySubscriptionOptions, type UseMemorySubscriptionState, type UseRecallState, useCilow, useConversation, useDebounce, useDebouncedSearch, useMemory, useMemoryContext, useMemoryStats, useMemorySubscription, useRecall };