@standardagents/react 0.8.1

package/dist/index.d.ts

@@ -0,0 +1,457 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+interface Message {
+    id: string;
+    role: "system" | "user" | "assistant" | "tool";
+    content: string | null;
+    name?: string | null;
+    tool_calls?: string | null;
+    tool_call_id?: string | null;
+    log_id?: string | null;
+    created_at: number;
+    request_sent_at?: number | null;
+    response_completed_at?: number | null;
+    status?: "pending" | "completed" | "failed";
+    silent?: boolean;
+    tool_status?: "success" | "error" | null;
+    reasoning_content?: string | null;
+    reasoning_details?: string | null;
+    parent_id?: string | null;
+    depth?: number;
+}
+interface WorkItem {
+    id: string;
+    type: "tool_call" | "tool_result";
+    name?: string;
+    content: string | null;
+    status?: "pending" | "success" | "error" | null;
+    tool_call_id?: string;
+}
+interface WorkMessage {
+    id: string;
+    type: "workblock";
+    content: string | null;
+    reasoning_content?: string | null;
+    workItems: WorkItem[];
+    status: "pending" | "completed" | "failed";
+    created_at: number;
+    depth?: number;
+}
+type ThreadMessage = Message | WorkMessage;
+interface AgentBuilderConfig {
+    endpoint: string;
+}
+interface UseThreadOptions {
+    preload?: boolean;
+    live?: boolean;
+    endpoint?: string;
+    stream?: boolean;
+    useWorkblocks?: boolean;
+    depth?: number;
+}
+interface GetMessagesOptions {
+    limit?: number;
+    offset?: number;
+    depth?: number;
+    includeSilent?: boolean;
+}
+interface MessageDataEvent {
+    type: "message_data";
+    message_id: string;
+    depth: number;
+    data: Message;
+}
+interface MessageChunkEvent {
+    type: "message_chunk";
+    message_id: string;
+    depth: number;
+    chunk: string;
+}
+interface ErrorEvent {
+    type: "error";
+    error: string;
+}
+/**
+ * Custom thread event emitted via emitThreadEvent on the backend
+ */
+interface ThreadEvent<T = unknown> {
+    type: "event";
+    eventType: string;
+    data: T;
+    timestamp: number;
+}
+type MessageStreamEvent = MessageDataEvent | MessageChunkEvent | ErrorEvent | ThreadEvent;
+interface LogDataEvent {
+    type: "log_data";
+    log_id: string;
+    data: any;
+}
+interface CustomEvent {
+    type: "custom";
+    customType: string;
+    value: any;
+    timestamp: number;
+}
+interface StoppedByUserEvent {
+    type: "stopped_by_user";
+    timestamp: number;
+}
+type LogStreamEvent = LogDataEvent | CustomEvent | StoppedByUserEvent;
+interface SendMessagePayload {
+    role: "user" | "assistant" | "system";
+    content: string;
+    silent?: boolean;
+}
+interface Thread {
+    id: string;
+    agent_id: string;
+    metadata?: Record<string, any>;
+    created_at: number;
+}
+interface MessageWebSocketCallbacks {
+    onMessage?: (event: MessageDataEvent) => void;
+    onChunk?: (event: MessageChunkEvent) => void;
+    onEvent?: (event: ThreadEvent) => void;
+    onError?: (event: ErrorEvent) => void;
+    onOpen?: () => void;
+    onClose?: () => void;
+}
+interface LogWebSocketCallbacks {
+    onLog?: (event: LogDataEvent) => void;
+    onCustom?: (event: CustomEvent) => void;
+    onStopped?: (event: StoppedByUserEvent) => void;
+    onOpen?: () => void;
+    onClose?: () => void;
+}
+interface ThreadProviderOptions {
+    /** Maximum message depth to fetch/stream */
+    depth?: number;
+    /** Whether to include silent messages */
+    includeSilent?: boolean;
+}
+
+interface AgentBuilderProviderProps {
+    config: AgentBuilderConfig;
+    children: ReactNode;
+}
+/**
+ * AgentBuilderProvider provides the AgentBuilder client instance to all child components.
+ * This should wrap the part of your app where you want to use AgentBuilder functionality.
+ *
+ * @example
+ * ```tsx
+ * <AgentBuilderProvider config={{ endpoint: 'https://api.example.com' }}>
+ *   <YourApp />
+ * </AgentBuilderProvider>
+ * ```
+ */
+declare function AgentBuilderProvider({ config, children }: AgentBuilderProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Event listener callback type
+ */
+type EventListener<T = unknown> = (data: T) => void;
+/**
+ * Thread context value
+ */
+interface ThreadContextValue {
+    /** The thread ID */
+    threadId: string;
+    /** Current messages in the thread */
+    messages: Message[];
+    /** Whether messages are currently loading */
+    loading: boolean;
+    /** Any error that occurred */
+    error: Error | null;
+    /** Subscribe to a specific event type */
+    subscribeToEvent: <T = unknown>(eventType: string, listener: EventListener<T>) => () => void;
+    /** Options passed to the provider */
+    options: ThreadProviderOptions;
+}
+interface ThreadProviderProps {
+    /** The thread ID to connect to */
+    threadId: string;
+    /** Provider options */
+    options?: ThreadProviderOptions;
+    /** Whether to preload messages on mount (default: true) */
+    preload?: boolean;
+    /** Whether to enable live updates via WebSocket (default: true) */
+    live?: boolean;
+    /** Maximum message depth to fetch/stream (default: 0 for top-level only) */
+    depth?: number;
+    /** Whether to include silent messages (default: false) */
+    includeSilent?: boolean;
+    /** Optional endpoint override */
+    endpoint?: string;
+    children: ReactNode;
+}
+/**
+ * ThreadProvider establishes a WebSocket connection to a thread and provides
+ * context for child components to access messages and events.
+ *
+ * Must be nested inside AgentBuilderProvider.
+ *
+ * @example
+ * ```tsx
+ * <AgentBuilderProvider config={{ endpoint: 'https://api.example.com' }}>
+ *   <ThreadProvider threadId="thread-123">
+ *     <ChatMessages />
+ *   </ThreadProvider>
+ * </AgentBuilderProvider>
+ * ```
+ */
+declare function ThreadProvider({ threadId, options, preload, live, depth, includeSilent, endpoint: endpointOverride, children, }: ThreadProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access the thread context.
+ * Must be used within a ThreadProvider.
+ *
+ * @throws Error if used outside of ThreadProvider
+ */
+declare function useThreadContext(): ThreadContextValue;
+/**
+ * Hook to get the current thread ID from context.
+ * Must be used within a ThreadProvider.
+ */
+declare function useThreadId(): string;
+
+/**
+ * Hook to get messages from a thread.
+ *
+ * Must be used within a ThreadProvider. The thread ID and WebSocket connection
+ * are managed by the ThreadProvider, so this hook simply returns the messages.
+ *
+ * @param options - Configuration options
+ * @returns Array of messages (raw or transformed to workblocks)
+ *
+ * @example
+ * ```tsx
+ * function ChatMessages() {
+ *   // Basic usage - returns messages from context
+ *   const messages = useThread()
+ *
+ *   return (
+ *     <div>
+ *       {messages.map(msg => <Message key={msg.id} message={msg} />)}
+ *     </div>
+ *   )
+ * }
+ *
+ * // Wrap with ThreadProvider
+ * <ThreadProvider threadId="thread-123">
+ *   <ChatMessages />
+ * </ThreadProvider>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Disable workblocks transformation
+ * const messages = useThread({ useWorkblocks: false })
+ * ```
+ */
+declare function useThread(options?: UseThreadOptions): ThreadMessage[];
+
+/**
+ * Hook to listen for custom events emitted from a thread via the stream WebSocket.
+ * Calls the provided callback whenever an event of the specified type is received.
+ *
+ * Must be used within a ThreadProvider. Events are emitted from the backend
+ * using `emitThreadEvent(flow, 'event-type', data)`.
+ *
+ * @param type - The custom event type to filter for
+ * @param callback - Function to call when an event of this type is received
+ *
+ * @example
+ * ```tsx
+ * function GamePreview() {
+ *   const [gameHtml, setGameHtml] = useState<string | null>(null)
+ *
+ *   onThreadEvent('game_built', (data: { success: boolean }) => {
+ *     if (data.success) {
+ *       fetchGameHtml()
+ *     }
+ *   })
+ *
+ *   return <iframe srcDoc={gameHtml} />
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function ProgressIndicator() {
+ *   const [progress, setProgress] = useState(0)
+ *
+ *   onThreadEvent('progress', (data: { step: number; total: number }) => {
+ *     setProgress(data.step / data.total * 100)
+ *   })
+ *
+ *   return <ProgressBar value={progress} />
+ * }
+ * ```
+ */
+declare function onThreadEvent<T = unknown>(type: string, callback: (data: T) => void): void;
+/**
+ * Hook to get the latest event data for a specific event type as React state.
+ * Returns the most recent event data, or null if no event has been received.
+ *
+ * Must be used within a ThreadProvider. Events are emitted from the backend
+ * using `emitThreadEvent(flow, 'event-type', data)`.
+ *
+ * @param type - The custom event type to filter for
+ * @returns The latest event data matching the specified type, or null if none received
+ *
+ * @example
+ * ```tsx
+ * function ProgressIndicator() {
+ *   const progress = useThreadEvent<{ step: number; total: number }>('progress')
+ *
+ *   if (!progress) return null
+ *
+ *   return (
+ *     <div>
+ *       Step {progress.step} of {progress.total}
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * function StatusDisplay() {
+ *   const status = useThreadEvent<{ message: string }>('status')
+ *
+ *   useEffect(() => {
+ *     if (status) {
+ *       console.log('Status updated:', status.message)
+ *     }
+ *   }, [status])
+ *
+ *   return <div>{status?.message ?? 'No status'}</div>
+ * }
+ * ```
+ */
+declare function useThreadEvent<T = unknown>(type: string): T | null;
+
+/**
+ * Hook that returns a function to send messages to the current thread.
+ * Must be used within a ThreadProvider.
+ *
+ * This hook automatically uses the thread ID from the ThreadProvider context,
+ * so you don't need to pass it manually.
+ *
+ * @returns A function that sends a message to the current thread
+ *
+ * @throws Error if used outside of ThreadProvider
+ *
+ * @example
+ * ```tsx
+ * function ChatInput() {
+ *   const sendMessage = useSendMessage()
+ *
+ *   const handleSubmit = async (content: string) => {
+ *     await sendMessage({
+ *       role: 'user',
+ *       content,
+ *     })
+ *   }
+ *
+ *   return <input onSubmit={handleSubmit} />
+ * }
+ * ```
+ */
+declare function useSendMessage(): (payload: SendMessagePayload) => Promise<Message>;
+
+/**
+ * Hook that returns a function to stop the current thread's execution.
+ * Must be used within a ThreadProvider.
+ *
+ * This hook automatically uses the thread ID from the ThreadProvider context,
+ * so you don't need to pass it manually.
+ *
+ * @returns A function that stops the current thread's execution
+ *
+ * @throws Error if used outside of ThreadProvider
+ *
+ * @example
+ * ```tsx
+ * function StopButton() {
+ *   const stopThread = useStopThread()
+ *
+ *   return (
+ *     <button onClick={() => stopThread()}>
+ *       Stop
+ *     </button>
+ *   )
+ * }
+ * ```
+ */
+declare function useStopThread(): () => Promise<void>;
+
+/**
+ * Send a message to a specific thread.
+ *
+ * This is a standalone function that sends messages to threads.
+ * It requires that an AgentBuilderProvider is mounted somewhere in your app
+ * to set the global endpoint configuration.
+ *
+ * @param id - The thread ID to send the message to
+ * @param payload - The message payload containing role, content, and optional silent flag
+ * @returns Promise resolving to the created message
+ *
+ * @throws Error if called before AgentBuilderProvider is mounted
+ *
+ * @example
+ * ```tsx
+ * import { sendMessage } from '@standardagents/react'
+ *
+ * await sendMessage('thread-123', {
+ *   role: 'user',
+ *   content: 'Hello, agent!',
+ * })
+ *
+ * // Send a silent message
+ * await sendMessage('thread-123', {
+ *   role: 'user',
+ *   content: 'Silent message',
+ *   silent: true,
+ * })
+ * ```
+ */
+declare function sendMessage(id: string, payload: SendMessagePayload): Promise<Message>;
+
+interface StopThreadOptions {
+    /**
+     * Override the endpoint URL for this request.
+     * If not provided, uses the endpoint from AgentBuilderProvider.
+     */
+    endpoint?: string;
+}
+/**
+ * Stop execution of a thread.
+ *
+ * This is a standalone function that stops a running thread execution.
+ * It requires that an AgentBuilderProvider is mounted somewhere in your app
+ * to set the global endpoint configuration, or you can provide a custom endpoint.
+ *
+ * @param id - The thread ID to stop
+ * @param options - Optional configuration including custom endpoint
+ * @returns Promise that resolves when the thread is stopped
+ *
+ * @throws Error if called before AgentBuilderProvider is mounted and no endpoint is provided
+ *
+ * @example
+ * ```tsx
+ * import { stopThread } from '@standardagents/react'
+ *
+ * // Using global endpoint from AgentBuilderProvider
+ * await stopThread('thread-123')
+ *
+ * // Using custom endpoint
+ * await stopThread('thread-123', {
+ *   endpoint: 'https://custom.example.com/api'
+ * })
+ * ```
+ */
+declare function stopThread(id: string, options?: StopThreadOptions): Promise<void>;
+
+export { type AgentBuilderConfig, AgentBuilderProvider, type CustomEvent, type ErrorEvent, type GetMessagesOptions, type LogDataEvent, type LogStreamEvent, type LogWebSocketCallbacks, type Message, type MessageChunkEvent, type MessageDataEvent, type MessageStreamEvent, type MessageWebSocketCallbacks, type SendMessagePayload, type StoppedByUserEvent, type Thread, type ThreadEvent, type ThreadMessage, ThreadProvider, type ThreadProviderOptions, type UseThreadOptions, type WorkItem, type WorkMessage, onThreadEvent, sendMessage, stopThread, useSendMessage, useStopThread, useThread, useThreadContext, useThreadEvent, useThreadId };