@octavus/react 0.2.0 → 2.0.0

package/README.md

@@ -0,0 +1,170 @@
+# @octavus/react
+
+React bindings for Octavus agents.
+
+## Installation
+
+```bash
+npm install @octavus/react
+```
+
+## Overview
+
+This package provides React hooks for interacting with Octavus agents. It wraps `@octavus/client-sdk` with React state management using `useSyncExternalStore` for proper React 18+ integration.
+
+## Quick Start
+
+```tsx
+import { useMemo } from 'react';
+import { useOctavusChat, createHttpTransport } from '@octavus/react';
+
+function Chat({ sessionId }: { sessionId: string }) {
+  const transport = useMemo(
+    () =>
+      createHttpTransport({
+        request: (payload, options) =>
+          fetch('/api/trigger', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ sessionId, ...payload }),
+            signal: options?.signal,
+          }),
+      }),
+    [sessionId],
+  );
+
+  const { messages, status, send } = useOctavusChat({ transport });
+
+  const handleSend = async (message: string) => {
+    await send('user-message', { USER_MESSAGE: message }, { userMessage: { content: message } });
+  };
+
+  return (
+    <div>
+      {messages.map((msg) => (
+        <Message key={msg.id} message={msg} />
+      ))}
+      <ChatInput onSend={handleSend} disabled={status === 'streaming'} />
+    </div>
+  );
+}
+```
+
+## useOctavusChat Hook
+
+### Options
+
+```typescript
+const { messages, status, error, send, stop } = useOctavusChat({
+  transport, // Required: HTTP or Socket transport
+  initialMessages: [], // Optional: restore messages from server
+  onError: (error) => {}, // Optional: error callback
+  onFinish: () => {}, // Optional: completion callback
+  onResourceUpdate: (name, value) => {}, // Optional: resource update callback
+});
+```
+
+### Return Values
+
+| Property      | Type                               | Description                                        |
+| ------------- | ---------------------------------- | -------------------------------------------------- |
+| `messages`    | `UIMessage[]`                      | All messages including the currently streaming one |
+| `status`      | `'idle' \| 'streaming' \| 'error'` | Current chat status                                |
+| `error`       | `OctavusError \| null`             | Structured error if status is 'error'              |
+| `send`        | `function`                         | Send a message to the agent                        |
+| `stop`        | `function`                         | Stop streaming and finalize partial content        |
+| `uploadFiles` | `function`                         | Upload files with progress tracking                |
+
+### Socket Transport Extensions
+
+When using `createSocketTransport`, additional properties are available:
+
+| Property          | Type                 | Description                                                |
+| ----------------- | -------------------- | ---------------------------------------------------------- |
+| `connectionState` | `ConnectionState`    | `'disconnected' \| 'connecting' \| 'connected' \| 'error'` |
+| `connectionError` | `Error \| undefined` | Connection error if state is 'error'                       |
+| `connect`         | `function`           | Eagerly establish connection                               |
+| `disconnect`      | `function`           | Close the connection                                       |
+
+## Transports
+
+### HTTP Transport
+
+```typescript
+import { createHttpTransport } from '@octavus/react';
+
+const transport = createHttpTransport({
+  request: (payload, options) =>
+    fetch('/api/trigger', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ sessionId, ...payload }),
+      signal: options?.signal,
+    }),
+});
+```
+
+### Socket Transport
+
+```typescript
+import { createSocketTransport } from '@octavus/react';
+
+const transport = createSocketTransport({
+  connect: () =>
+    new Promise((resolve, reject) => {
+      const ws = new WebSocket(`wss://api.example.com/stream?sessionId=${sessionId}`);
+      ws.onopen = () => resolve(ws);
+      ws.onerror = () => reject(new Error('Connection failed'));
+    }),
+});
+```
+
+## File Uploads
+
+```tsx
+const { send, uploadFiles } = useOctavusChat({ transport, requestUploadUrls });
+
+// Upload with progress tracking
+const handleFileSelect = async (files: FileList) => {
+  const fileRefs = await uploadFiles(files, (index, progress) => {
+    console.log(`File ${index}: ${progress}%`);
+  });
+
+  await send('user-message', { FILES: fileRefs }, { userMessage: { files: fileRefs } });
+};
+```
+
+## Error Handling
+
+```tsx
+import { useOctavusChat, isRateLimitError, isProviderError } from '@octavus/react';
+
+function Chat() {
+  const { error, status } = useOctavusChat({
+    transport,
+    onError: (error) => {
+      if (isRateLimitError(error)) {
+        toast(`Rate limited. Retry in ${error.retryAfter}s`);
+      } else if (isProviderError(error)) {
+        toast(`Provider error: ${error.provider?.name}`);
+      }
+    },
+  });
+
+  return status === 'error' && <ErrorBanner error={error} />;
+}
+```
+
+## Re-exports
+
+This package re-exports everything from `@octavus/client-sdk` and `@octavus/core`, so you don't need to install them separately.
+
+## Related Packages
+
+- [`@octavus/client-sdk`](https://www.npmjs.com/package/@octavus/client-sdk) - Framework-agnostic client SDK
+- [`@octavus/server-sdk`](https://www.npmjs.com/package/@octavus/server-sdk) - Server-side SDK
+- [`@octavus/core`](https://www.npmjs.com/package/@octavus/core) - Shared types
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -1,14 +1,18 @@
-import { OctavusChatOptions, UIMessage, ChatStatus, ConnectionState, UserMessageInput, FileReference } from '@octavus/client-sdk';
+import { OctavusChatOptions, UIMessage, ChatStatus, OctavusError, ConnectionState, InteractiveTool, UserMessageInput, FileReference } from '@octavus/client-sdk';
 export * from '@octavus/client-sdk';
-export { ChatStatus, OctavusChatOptions, UserMessageInput } from '@octavus/client-sdk';
+export { AppError, ChatStatus, ClientToolContext, ClientToolHandler, ConflictError, ForbiddenError, InteractiveTool, MAIN_THREAD, NotFoundError, OCTAVUS_SKILL_TOOLS, OctavusChat, OctavusChatOptions, OctavusError, UserMessageInput, ValidationError, createApiErrorEvent, createErrorEvent, createHttpTransport, createInternalErrorEvent, createSocketTransport, errorToStreamEvent, generateId, getSkillSlugFromToolCall, isAbortError, isAuthenticationError, isFileReference, isFileReferenceArray, isMainThread, isOctavusSkillTool, isOtherThread, isProviderError, isRateLimitError, isRetryableError, isSocketTransport, isToolError, isValidationError, parseSSEStream, resolveThread, safeParseStreamEvent, safeParseUIMessage, safeParseUIMessages, threadForPart, uploadFiles } from '@octavus/client-sdk';
 
 interface UseOctavusChatReturn {
     /** All messages including the currently streaming one */
     messages: UIMessage[];
     /** Current status of the chat */
     status: ChatStatus;
-    /** Error if status is 'error' */
-    error: Error | null;
+    /**
+     * Error if status is 'error'.
+     * Contains structured error information including type, source, and retryability.
+     * Use type guards like `isRateLimitError()` or `isProviderError()` to check specific error types.
+     */
+    error: OctavusError | null;
     /**
      * Socket connection state (socket transport only).
      * For HTTP transport, this is always `undefined`.
@@ -23,6 +27,25 @@ interface UseOctavusChatReturn {
      * Connection error if `connectionState` is 'error'.
      */
     connectionError: Error | undefined;
+    /**
+     * Pending interactive tool calls keyed by tool name.
+     * Each tool has bound `submit()` and `cancel()` methods.
+     *
+     * @example
+     * ```tsx
+     * const feedbackTools = pendingClientTools['request-feedback'] ?? [];
+     *
+     * {feedbackTools.map(tool => (
+     *   <FeedbackModal
+     *     key={tool.toolCallId}
+     *     {...tool.args}
+     *     onSubmit={(result) => tool.submit(result)}
+     *     onCancel={() => tool.cancel()}
+     *   />
+     * ))}
+     * ```
+     */
+    pendingClientTools: Record<string, InteractiveTool[]>;
     /**
      * Trigger the agent and optionally add a user message to the chat.
      *
@@ -84,11 +107,12 @@ interface UseOctavusChatReturn {
  * function Chat({ sessionId }) {
  *   const transport = useMemo(
  *     () => createHttpTransport({
- *       triggerRequest: (triggerName, input) =>
+ *       request: (payload, options) =>
  *         fetch('/api/trigger', {
  *           method: 'POST',
  *           headers: { 'Content-Type': 'application/json' },
- *           body: JSON.stringify({ sessionId, triggerName, input }),
+ *           body: JSON.stringify({ sessionId, ...payload }),
+ *           signal: options?.signal,
  *         }),
  *     }),
  *     [sessionId],

package/dist/index.js

@@ -18,9 +18,15 @@ function useOctavusChat(options) {
   const getMessagesSnapshot = useCallback(() => chat.messages, [chat]);
   const getStatusSnapshot = useCallback(() => chat.status, [chat]);
   const getErrorSnapshot = useCallback(() => chat.error, [chat]);
+  const getPendingClientToolsSnapshot = useCallback(() => chat.pendingClientTools, [chat]);
   const messages = useSyncExternalStore(subscribe, getMessagesSnapshot, getMessagesSnapshot);
   const status = useSyncExternalStore(subscribe, getStatusSnapshot, getStatusSnapshot);
   const error = useSyncExternalStore(subscribe, getErrorSnapshot, getErrorSnapshot);
+  const pendingClientTools = useSyncExternalStore(
+    subscribe,
+    getPendingClientToolsSnapshot,
+    getPendingClientToolsSnapshot
+  );
   const socketTransport = isSocketTransport(transport) ? transport : null;
   const [connectionState, setConnectionState] = useState(
     socketTransport?.connectionState
@@ -43,7 +49,7 @@ function useOctavusChat(options) {
     [chat]
   );
   const stop = useCallback(() => chat.stop(), [chat]);
-  const uploadFiles = useCallback(
+  const uploadFiles2 = useCallback(
     (files, onProgress) => chat.uploadFiles(files, onProgress),
     [chat]
   );
@@ -58,17 +64,93 @@ function useOctavusChat(options) {
     error,
     connectionState,
     connectionError,
+    pendingClientTools,
     send,
     stop,
     connect: socketTransport ? connect : void 0,
     disconnect: socketTransport ? disconnect : void 0,
-    uploadFiles
+    uploadFiles: uploadFiles2
   };
 }
 
 // src/index.ts
-export * from "@octavus/client-sdk";
+import {
+  OctavusChat as OctavusChat2,
+  uploadFiles,
+  parseSSEStream,
+  createHttpTransport,
+  createSocketTransport,
+  isSocketTransport as isSocketTransport2,
+  AppError,
+  NotFoundError,
+  ValidationError,
+  ConflictError,
+  ForbiddenError,
+  OctavusError,
+  isRateLimitError,
+  isAuthenticationError,
+  isProviderError,
+  isToolError,
+  isRetryableError,
+  isValidationError,
+  createErrorEvent,
+  errorToStreamEvent,
+  createInternalErrorEvent,
+  createApiErrorEvent,
+  generateId,
+  isAbortError,
+  MAIN_THREAD,
+  resolveThread,
+  isMainThread,
+  threadForPart,
+  isOtherThread,
+  isFileReference,
+  isFileReferenceArray,
+  safeParseStreamEvent,
+  safeParseUIMessage,
+  safeParseUIMessages,
+  OCTAVUS_SKILL_TOOLS,
+  isOctavusSkillTool,
+  getSkillSlugFromToolCall
+} from "@octavus/client-sdk";
 export {
+  AppError,
+  ConflictError,
+  ForbiddenError,
+  MAIN_THREAD,
+  NotFoundError,
+  OCTAVUS_SKILL_TOOLS,
+  OctavusChat2 as OctavusChat,
+  OctavusError,
+  ValidationError,
+  createApiErrorEvent,
+  createErrorEvent,
+  createHttpTransport,
+  createInternalErrorEvent,
+  createSocketTransport,
+  errorToStreamEvent,
+  generateId,
+  getSkillSlugFromToolCall,
+  isAbortError,
+  isAuthenticationError,
+  isFileReference,
+  isFileReferenceArray,
+  isMainThread,
+  isOctavusSkillTool,
+  isOtherThread,
+  isProviderError,
+  isRateLimitError,
+  isRetryableError,
+  isSocketTransport2 as isSocketTransport,
+  isToolError,
+  isValidationError,
+  parseSSEStream,
+  resolveThread,
+  safeParseStreamEvent,
+  safeParseUIMessage,
+  safeParseUIMessages,
+  threadForPart,
+  uploadFiles,
   useOctavusChat
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/hooks/use-octavus-chat.ts","../src/index.ts"],"sourcesContent":["'use client';\n\nimport { useRef, useCallback, useSyncExternalStore, useState, useEffect } from 'react';\nimport {\n  OctavusChat,\n  isSocketTransport,\n  type OctavusChatOptions,\n  type ChatStatus,\n  type UserMessageInput,\n  type UIMessage,\n  type Transport,\n  type ConnectionState,\n  type FileReference,\n  type UploadFilesOptions,\n  type UploadUrlsResponse,\n} from '@octavus/client-sdk';\n\nexport type {\n  OctavusChatOptions,\n  ChatStatus,\n  UserMessageInput,\n  FileReference,\n  UploadFilesOptions,\n  UploadUrlsResponse,\n};\n\nexport interface UseOctavusChatReturn {\n  /** All messages including the currently streaming one */\n  messages: UIMessage[];\n  /** Current status of the chat */\n  status: ChatStatus;\n  /** Error if status is 'error' */\n  error: Error | null;\n  /**\n   * Socket connection state (socket transport only).\n   * For HTTP transport, this is always `undefined`.\n   *\n   * - `disconnected`: Not connected (initial state before first send)\n   * - `connecting`: Connection attempt in progress\n   * - `connected`: Successfully connected\n   * - `error`: Connection failed (check `connectionError`)\n   */\n  connectionState: ConnectionState | undefined;\n  /**\n   * Connection error if `connectionState` is 'error'.\n   */\n  connectionError: Error | undefined;\n  /**\n   * Trigger the agent and optionally add a user message to the chat.\n   *\n   * @param triggerName - The trigger name defined in the agent's protocol.yaml\n   * @param input - Input parameters for the trigger (variable substitutions)\n   * @param options.userMessage - If provided, adds a user message to the chat before triggering\n   */\n  send: (\n    triggerName: string,\n    input?: Record<string, unknown>,\n    options?: { userMessage?: UserMessageInput },\n  ) => Promise<void>;\n  /** Stop the current streaming and finalize any partial message */\n  stop: () => void;\n  /**\n   * Eagerly connect to the socket (socket transport only).\n   * Returns a promise that resolves when connected or rejects on error.\n   * Safe to call multiple times - subsequent calls resolve immediately if already connected.\n   *\n   * For HTTP transport, this is `undefined`.\n   */\n  connect: (() => Promise<void>) | undefined;\n  /**\n   * Disconnect the socket (socket transport only).\n   * The transport will reconnect automatically on next send().\n   *\n   * For HTTP transport, this is `undefined`.\n   */\n  disconnect: (() => void) | undefined;\n  /**\n   * Upload files directly without sending a message.\n   * Useful for showing upload progress before sending.\n   *\n   * @param files - Files to upload\n   * @param onProgress - Optional progress callback\n   * @returns Array of file references\n   *\n   * @example\n   * ```typescript\n   * const fileRefs = await uploadFiles(fileInput.files, (i, progress) => {\n   *   console.log(`File ${i}: ${progress}%`);\n   * });\n   * // Later...\n   * await send('user-message', { FILES: fileRefs }, { userMessage: { files: fileRefs } });\n   * ```\n   */\n  uploadFiles: (\n    files: FileList | File[],\n    onProgress?: (fileIndex: number, progress: number) => void,\n  ) => Promise<FileReference[]>;\n}\n\n/**\n * React hook for interacting with Octavus agents.\n * Provides chat state management and streaming support.\n *\n * When the transport changes (e.g., sessionId changes), the hook automatically\n * reinitializes with a fresh chat instance. Use `initialMessages` if you need\n * to preserve messages across transport changes.\n *\n * @example Basic usage with HTTP transport\n * ```tsx\n * import { useOctavusChat, createHttpTransport } from '@octavus/react';\n *\n * function Chat({ sessionId }) {\n *   const transport = useMemo(\n *     () => createHttpTransport({\n *       triggerRequest: (triggerName, input) =>\n *         fetch('/api/trigger', {\n *           method: 'POST',\n *           headers: { 'Content-Type': 'application/json' },\n *           body: JSON.stringify({ sessionId, triggerName, input }),\n *         }),\n *     }),\n *     [sessionId],\n *   );\n *\n *   const { messages, status, send } = useOctavusChat({ transport });\n *\n *   return (\n *     <div>\n *       {messages.map((msg) => (\n *         <Message key={msg.id} message={msg} />\n *       ))}\n *       <button onClick={() => send('user-message', { USER_MESSAGE: 'Hello' })}>\n *         Send\n *       </button>\n *     </div>\n *   );\n * }\n * ```\n *\n * @example Socket transport with eager connection\n * ```tsx\n * import { useOctavusChat, createSocketTransport } from '@octavus/react';\n *\n * function Chat() {\n *   const transport = useMemo(\n *     () => createSocketTransport({\n *       connect: () => new Promise((resolve, reject) => {\n *         const sock = new SockJS('/octavus');\n *         sock.onopen = () => resolve(sock);\n *         sock.onerror = () => reject(new Error('Connection failed'));\n *       }),\n *     }),\n *     [],\n *   );\n *\n *   const { messages, status, send, connectionState, connect, disconnect } =\n *     useOctavusChat({ transport });\n *\n *   // Eager connection on mount\n *   useEffect(() => {\n *     connect?.();\n *     return () => disconnect?.();\n *   }, [connect, disconnect]);\n *\n *   return (\n *     <div>\n *       <StatusIndicator state={connectionState} />\n *       {messages.map((msg) => <Message key={msg.id} message={msg} />)}\n *     </div>\n *   );\n * }\n * ```\n */\nexport function useOctavusChat(options: OctavusChatOptions): UseOctavusChatReturn {\n  const chatRef = useRef<OctavusChat | null>(null);\n  const transportRef = useRef<Transport | null>(null);\n\n  if (transportRef.current !== options.transport) {\n    chatRef.current?.stop();\n    chatRef.current = new OctavusChat(options);\n    transportRef.current = options.transport;\n  }\n\n  const chat = chatRef.current!;\n  const transport = options.transport;\n\n  const subscribe = useCallback((callback: () => void) => chat.subscribe(callback), [chat]);\n  const getMessagesSnapshot = useCallback(() => chat.messages, [chat]);\n  const getStatusSnapshot = useCallback(() => chat.status, [chat]);\n  const getErrorSnapshot = useCallback(() => chat.error, [chat]);\n\n  const messages = useSyncExternalStore(subscribe, getMessagesSnapshot, getMessagesSnapshot);\n  const status = useSyncExternalStore(subscribe, getStatusSnapshot, getStatusSnapshot);\n  const error = useSyncExternalStore(subscribe, getErrorSnapshot, getErrorSnapshot);\n\n  const socketTransport = isSocketTransport(transport) ? transport : null;\n  const [connectionState, setConnectionState] = useState<ConnectionState | undefined>(\n    socketTransport?.connectionState,\n  );\n  const [connectionError, setConnectionError] = useState<Error | undefined>(undefined);\n\n  useEffect(() => {\n    if (!socketTransport) {\n      setConnectionState(undefined);\n      setConnectionError(undefined);\n      return;\n    }\n\n    const unsubscribe = socketTransport.onConnectionStateChange((state, err) => {\n      setConnectionState(state);\n      setConnectionError(err);\n    });\n\n    return unsubscribe;\n  }, [socketTransport]);\n\n  const send = useCallback(\n    (\n      triggerName: string,\n      input?: Record<string, unknown>,\n      sendOptions?: { userMessage?: UserMessageInput },\n    ) => chat.send(triggerName, input, sendOptions),\n    [chat],\n  );\n\n  const stop = useCallback(() => chat.stop(), [chat]);\n\n  const uploadFiles = useCallback(\n    (files: FileList | File[], onProgress?: (fileIndex: number, progress: number) => void) =>\n      chat.uploadFiles(files, onProgress),\n    [chat],\n  );\n\n  // Stable references for connect/disconnect (socket transport only)\n  const connect = useCallback(\n    () => socketTransport?.connect() ?? Promise.resolve(),\n    [socketTransport],\n  );\n  const disconnect = useCallback(() => socketTransport?.disconnect(), [socketTransport]);\n\n  return {\n    messages,\n    status,\n    error,\n    connectionState,\n    connectionError,\n    send,\n    stop,\n    connect: socketTransport ? connect : undefined,\n    disconnect: socketTransport ? disconnect : undefined,\n    uploadFiles,\n  };\n}\n","export {\n  useOctavusChat,\n  type UseOctavusChatReturn,\n  type OctavusChatOptions,\n  type ChatStatus,\n  type UserMessageInput,\n} from './hooks/use-octavus-chat';\n\n// Re-export everything from client-sdk so consumers only need @octavus/react\nexport * from '@octavus/client-sdk';\n"],"mappings":";AAEA,SAAS,QAAQ,aAAa,sBAAsB,UAAU,iBAAiB;AAC/E;AAAA,EACE;AAAA,EACA;AAAA,OAUK;AA8JA,SAAS,eAAe,SAAmD;AAChF,QAAM,UAAU,OAA2B,IAAI;AAC/C,QAAM,eAAe,OAAyB,IAAI;AAElD,MAAI,aAAa,YAAY,QAAQ,WAAW;AAC9C,YAAQ,SAAS,KAAK;AACtB,YAAQ,UAAU,IAAI,YAAY,OAAO;AACzC,iBAAa,UAAU,QAAQ;AAAA,EACjC;AAEA,QAAM,OAAO,QAAQ;AACrB,QAAM,YAAY,QAAQ;AAE1B,QAAM,YAAY,YAAY,CAAC,aAAyB,KAAK,UAAU,QAAQ,GAAG,CAAC,IAAI,CAAC;AACxF,QAAM,sBAAsB,YAAY,MAAM,KAAK,UAAU,CAAC,IAAI,CAAC;AACnE,QAAM,oBAAoB,YAAY,MAAM,KAAK,QAAQ,CAAC,IAAI,CAAC;AAC/D,QAAM,mBAAmB,YAAY,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC;AAE7D,QAAM,WAAW,qBAAqB,WAAW,qBAAqB,mBAAmB;AACzF,QAAM,SAAS,qBAAqB,WAAW,mBAAmB,iBAAiB;AACnF,QAAM,QAAQ,qBAAqB,WAAW,kBAAkB,gBAAgB;AAEhF,QAAM,kBAAkB,kBAAkB,SAAS,IAAI,YAAY;AACnE,QAAM,CAAC,iBAAiB,kBAAkB,IAAI;AAAA,IAC5C,iBAAiB;AAAA,EACnB;AACA,QAAM,CAAC,iBAAiB,kBAAkB,IAAI,SAA4B,MAAS;AAEnF,YAAU,MAAM;AACd,QAAI,CAAC,iBAAiB;AACpB,yBAAmB,MAAS;AAC5B,yBAAmB,MAAS;AAC5B;AAAA,IACF;AAEA,UAAM,cAAc,gBAAgB,wBAAwB,CAAC,OAAO,QAAQ;AAC1E,yBAAmB,KAAK;AACxB,yBAAmB,GAAG;AAAA,IACxB,CAAC;AAED,WAAO;AAAA,EACT,GAAG,CAAC,eAAe,CAAC;AAEpB,QAAM,OAAO;AAAA,IACX,CACE,aACA,OACA,gBACG,KAAK,KAAK,aAAa,OAAO,WAAW;AAAA,IAC9C,CAAC,IAAI;AAAA,EACP;AAEA,QAAM,OAAO,YAAY,MAAM,KAAK,KAAK,GAAG,CAAC,IAAI,CAAC;AAElD,QAAM,cAAc;AAAA,IAClB,CAAC,OAA0B,eACzB,KAAK,YAAY,OAAO,UAAU;AAAA,IACpC,CAAC,IAAI;AAAA,EACP;AAGA,QAAM,UAAU;AAAA,IACd,MAAM,iBAAiB,QAAQ,KAAK,QAAQ,QAAQ;AAAA,IACpD,CAAC,eAAe;AAAA,EAClB;AACA,QAAM,aAAa,YAAY,MAAM,iBAAiB,WAAW,GAAG,CAAC,eAAe,CAAC;AAErF,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA,SAAS,kBAAkB,UAAU;AAAA,IACrC,YAAY,kBAAkB,aAAa;AAAA,IAC3C;AAAA,EACF;AACF;;;ACnPA,cAAc;","names":[]}
+{"version":3,"sources":["../src/hooks/use-octavus-chat.ts","../src/index.ts"],"sourcesContent":["'use client';\n\nimport { useRef, useCallback, useSyncExternalStore, useState, useEffect } from 'react';\nimport {\n  OctavusChat,\n  type OctavusError,\n  isSocketTransport,\n  type OctavusChatOptions,\n  type ChatStatus,\n  type UserMessageInput,\n  type UIMessage,\n  type Transport,\n  type ConnectionState,\n  type FileReference,\n  type UploadFilesOptions,\n  type UploadUrlsResponse,\n  type ClientToolContext,\n  type ClientToolHandler,\n  type InteractiveTool,\n} from '@octavus/client-sdk';\n\nexport type {\n  OctavusChatOptions,\n  ChatStatus,\n  UserMessageInput,\n  FileReference,\n  UploadFilesOptions,\n  UploadUrlsResponse,\n  ClientToolContext,\n  ClientToolHandler,\n  InteractiveTool,\n};\n\nexport interface UseOctavusChatReturn {\n  /** All messages including the currently streaming one */\n  messages: UIMessage[];\n  /** Current status of the chat */\n  status: ChatStatus;\n  /**\n   * Error if status is 'error'.\n   * Contains structured error information including type, source, and retryability.\n   * Use type guards like `isRateLimitError()` or `isProviderError()` to check specific error types.\n   */\n  error: OctavusError | null;\n  /**\n   * Socket connection state (socket transport only).\n   * For HTTP transport, this is always `undefined`.\n   *\n   * - `disconnected`: Not connected (initial state before first send)\n   * - `connecting`: Connection attempt in progress\n   * - `connected`: Successfully connected\n   * - `error`: Connection failed (check `connectionError`)\n   */\n  connectionState: ConnectionState | undefined;\n  /**\n   * Connection error if `connectionState` is 'error'.\n   */\n  connectionError: Error | undefined;\n  /**\n   * Pending interactive tool calls keyed by tool name.\n   * Each tool has bound `submit()` and `cancel()` methods.\n   *\n   * @example\n   * ```tsx\n   * const feedbackTools = pendingClientTools['request-feedback'] ?? [];\n   *\n   * {feedbackTools.map(tool => (\n   *   <FeedbackModal\n   *     key={tool.toolCallId}\n   *     {...tool.args}\n   *     onSubmit={(result) => tool.submit(result)}\n   *     onCancel={() => tool.cancel()}\n   *   />\n   * ))}\n   * ```\n   */\n  pendingClientTools: Record<string, InteractiveTool[]>;\n  /**\n   * Trigger the agent and optionally add a user message to the chat.\n   *\n   * @param triggerName - The trigger name defined in the agent's protocol.yaml\n   * @param input - Input parameters for the trigger (variable substitutions)\n   * @param options.userMessage - If provided, adds a user message to the chat before triggering\n   */\n  send: (\n    triggerName: string,\n    input?: Record<string, unknown>,\n    options?: { userMessage?: UserMessageInput },\n  ) => Promise<void>;\n  /** Stop the current streaming and finalize any partial message */\n  stop: () => void;\n  /**\n   * Eagerly connect to the socket (socket transport only).\n   * Returns a promise that resolves when connected or rejects on error.\n   * Safe to call multiple times - subsequent calls resolve immediately if already connected.\n   *\n   * For HTTP transport, this is `undefined`.\n   */\n  connect: (() => Promise<void>) | undefined;\n  /**\n   * Disconnect the socket (socket transport only).\n   * The transport will reconnect automatically on next send().\n   *\n   * For HTTP transport, this is `undefined`.\n   */\n  disconnect: (() => void) | undefined;\n  /**\n   * Upload files directly without sending a message.\n   * Useful for showing upload progress before sending.\n   *\n   * @param files - Files to upload\n   * @param onProgress - Optional progress callback\n   * @returns Array of file references\n   *\n   * @example\n   * ```typescript\n   * const fileRefs = await uploadFiles(fileInput.files, (i, progress) => {\n   *   console.log(`File ${i}: ${progress}%`);\n   * });\n   * // Later...\n   * await send('user-message', { FILES: fileRefs }, { userMessage: { files: fileRefs } });\n   * ```\n   */\n  uploadFiles: (\n    files: FileList | File[],\n    onProgress?: (fileIndex: number, progress: number) => void,\n  ) => Promise<FileReference[]>;\n}\n\n/**\n * React hook for interacting with Octavus agents.\n * Provides chat state management and streaming support.\n *\n * When the transport changes (e.g., sessionId changes), the hook automatically\n * reinitializes with a fresh chat instance. Use `initialMessages` if you need\n * to preserve messages across transport changes.\n *\n * @example Basic usage with HTTP transport\n * ```tsx\n * import { useOctavusChat, createHttpTransport } from '@octavus/react';\n *\n * function Chat({ sessionId }) {\n *   const transport = useMemo(\n *     () => createHttpTransport({\n *       request: (payload, options) =>\n *         fetch('/api/trigger', {\n *           method: 'POST',\n *           headers: { 'Content-Type': 'application/json' },\n *           body: JSON.stringify({ sessionId, ...payload }),\n *           signal: options?.signal,\n *         }),\n *     }),\n *     [sessionId],\n *   );\n *\n *   const { messages, status, send } = useOctavusChat({ transport });\n *\n *   return (\n *     <div>\n *       {messages.map((msg) => (\n *         <Message key={msg.id} message={msg} />\n *       ))}\n *       <button onClick={() => send('user-message', { USER_MESSAGE: 'Hello' })}>\n *         Send\n *       </button>\n *     </div>\n *   );\n * }\n * ```\n *\n * @example Socket transport with eager connection\n * ```tsx\n * import { useOctavusChat, createSocketTransport } from '@octavus/react';\n *\n * function Chat() {\n *   const transport = useMemo(\n *     () => createSocketTransport({\n *       connect: () => new Promise((resolve, reject) => {\n *         const sock = new SockJS('/octavus');\n *         sock.onopen = () => resolve(sock);\n *         sock.onerror = () => reject(new Error('Connection failed'));\n *       }),\n *     }),\n *     [],\n *   );\n *\n *   const { messages, status, send, connectionState, connect, disconnect } =\n *     useOctavusChat({ transport });\n *\n *   // Eager connection on mount\n *   useEffect(() => {\n *     connect?.();\n *     return () => disconnect?.();\n *   }, [connect, disconnect]);\n *\n *   return (\n *     <div>\n *       <StatusIndicator state={connectionState} />\n *       {messages.map((msg) => <Message key={msg.id} message={msg} />)}\n *     </div>\n *   );\n * }\n * ```\n */\nexport function useOctavusChat(options: OctavusChatOptions): UseOctavusChatReturn {\n  const chatRef = useRef<OctavusChat | null>(null);\n  const transportRef = useRef<Transport | null>(null);\n\n  if (transportRef.current !== options.transport) {\n    chatRef.current?.stop();\n    chatRef.current = new OctavusChat(options);\n    transportRef.current = options.transport;\n  }\n\n  const chat = chatRef.current!;\n  const transport = options.transport;\n\n  const subscribe = useCallback((callback: () => void) => chat.subscribe(callback), [chat]);\n  const getMessagesSnapshot = useCallback(() => chat.messages, [chat]);\n  const getStatusSnapshot = useCallback(() => chat.status, [chat]);\n  const getErrorSnapshot = useCallback(() => chat.error, [chat]);\n  const getPendingClientToolsSnapshot = useCallback(() => chat.pendingClientTools, [chat]);\n\n  const messages = useSyncExternalStore(subscribe, getMessagesSnapshot, getMessagesSnapshot);\n  const status = useSyncExternalStore(subscribe, getStatusSnapshot, getStatusSnapshot);\n  const error = useSyncExternalStore(subscribe, getErrorSnapshot, getErrorSnapshot);\n  const pendingClientTools = useSyncExternalStore(\n    subscribe,\n    getPendingClientToolsSnapshot,\n    getPendingClientToolsSnapshot,\n  );\n\n  const socketTransport = isSocketTransport(transport) ? transport : null;\n  const [connectionState, setConnectionState] = useState<ConnectionState | undefined>(\n    socketTransport?.connectionState,\n  );\n  const [connectionError, setConnectionError] = useState<Error | undefined>(undefined);\n\n  useEffect(() => {\n    if (!socketTransport) {\n      setConnectionState(undefined);\n      setConnectionError(undefined);\n      return;\n    }\n\n    const unsubscribe = socketTransport.onConnectionStateChange((state, err) => {\n      setConnectionState(state);\n      setConnectionError(err);\n    });\n\n    return unsubscribe;\n  }, [socketTransport]);\n\n  const send = useCallback(\n    (\n      triggerName: string,\n      input?: Record<string, unknown>,\n      sendOptions?: { userMessage?: UserMessageInput },\n    ) => chat.send(triggerName, input, sendOptions),\n    [chat],\n  );\n\n  const stop = useCallback(() => chat.stop(), [chat]);\n\n  const uploadFiles = useCallback(\n    (files: FileList | File[], onProgress?: (fileIndex: number, progress: number) => void) =>\n      chat.uploadFiles(files, onProgress),\n    [chat],\n  );\n\n  // Stable references for connect/disconnect (socket transport only)\n  const connect = useCallback(\n    () => socketTransport?.connect() ?? Promise.resolve(),\n    [socketTransport],\n  );\n  const disconnect = useCallback(() => socketTransport?.disconnect(), [socketTransport]);\n\n  return {\n    messages,\n    status,\n    error,\n    connectionState,\n    connectionError,\n    pendingClientTools,\n    send,\n    stop,\n    connect: socketTransport ? connect : undefined,\n    disconnect: socketTransport ? disconnect : undefined,\n    uploadFiles,\n  };\n}\n","export {\n  useOctavusChat,\n  type UseOctavusChatReturn,\n  type OctavusChatOptions,\n  type ChatStatus,\n  type UserMessageInput,\n  type ClientToolContext,\n  type ClientToolHandler,\n  type InteractiveTool,\n} from './hooks/use-octavus-chat';\n\nexport type * from '@octavus/client-sdk';\nexport {\n  // Chat\n  OctavusChat,\n  // Files\n  uploadFiles,\n  // Stream\n  parseSSEStream,\n  // Transports\n  createHttpTransport,\n  createSocketTransport,\n  isSocketTransport,\n  // Error classes\n  AppError,\n  NotFoundError,\n  ValidationError,\n  ConflictError,\n  ForbiddenError,\n  OctavusError,\n  // Error type guards\n  isRateLimitError,\n  isAuthenticationError,\n  isProviderError,\n  isToolError,\n  isRetryableError,\n  isValidationError,\n  // Error event helpers\n  createErrorEvent,\n  errorToStreamEvent,\n  createInternalErrorEvent,\n  createApiErrorEvent,\n  // Utilities\n  generateId,\n  isAbortError,\n  // Thread helpers\n  MAIN_THREAD,\n  resolveThread,\n  isMainThread,\n  threadForPart,\n  isOtherThread,\n  // Type guards\n  isFileReference,\n  isFileReferenceArray,\n  // Safe parse helpers\n  safeParseStreamEvent,\n  safeParseUIMessage,\n  safeParseUIMessages,\n  // Skills\n  OCTAVUS_SKILL_TOOLS,\n  isOctavusSkillTool,\n  getSkillSlugFromToolCall,\n} from '@octavus/client-sdk';\n"],"mappings":"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","names":["uploadFiles","OctavusChat","isSocketTransport"]}

package/package.json

@@ -1,16 +1,27 @@
 {
   "name": "@octavus/react",
-  "version": "0.2.0",
+  "version": "2.0.0",
   "description": "React bindings for Octavus agents",
   "license": "MIT",
   "author": "Octavus AI <dev@octavus.ai>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/octavus-ai/js-sdk.git",
+    "directory": "packages/react"
+  },
+  "homepage": "https://octavus.ai",
+  "bugs": {
+    "url": "https://github.com/octavus-ai/js-sdk/issues"
+  },
   "keywords": [
     "octavus",
     "ai",
     "agents",
     "sdk",
     "react",
-    "streaming"
+    "hooks",
+    "streaming",
+    "chat"
   ],
   "type": "module",
   "sideEffects": false,
@@ -29,7 +40,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@octavus/client-sdk": "^0.2.0"
+    "@octavus/client-sdk": "^2.0.0"
   },
   "peerDependencies": {
     "react": ">=18.0.0"