@octavus/react 0.0.9 → 0.0.10

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { OctavusChatOptions, UIMessage, ChatStatus, UserMessageInput } from '@octavus/client-sdk';
+import { OctavusChatOptions, UIMessage, ChatStatus, ConnectionState, UserMessageInput } from '@octavus/client-sdk';
 export * from '@octavus/client-sdk';
 export { ChatStatus, OctavusChatOptions, UserMessageInput } from '@octavus/client-sdk';
 
@@ -9,6 +9,20 @@ interface UseOctavusChatReturn {
     status: ChatStatus;
     /** Error if status is 'error' */
     error: Error | null;
+    /**
+     * Socket connection state (socket transport only).
+     * For HTTP transport, this is always `undefined`.
+     *
+     * - `disconnected`: Not connected (initial state before first send)
+     * - `connecting`: Connection attempt in progress
+     * - `connected`: Successfully connected
+     * - `error`: Connection failed (check `connectionError`)
+     */
+    connectionState: ConnectionState | undefined;
+    /**
+     * Connection error if `connectionState` is 'error'.
+     */
+    connectionError: Error | undefined;
     /**
      * Trigger the agent and optionally add a user message to the chat.
      *
@@ -21,6 +35,21 @@ interface UseOctavusChatReturn {
     }) => Promise<void>;
     /** Stop the current streaming and finalize any partial message */
     stop: () => void;
+    /**
+     * Eagerly connect to the socket (socket transport only).
+     * Returns a promise that resolves when connected or rejects on error.
+     * Safe to call multiple times - subsequent calls resolve immediately if already connected.
+     *
+     * For HTTP transport, this is `undefined`.
+     */
+    connect: (() => Promise<void>) | undefined;
+    /**
+     * Disconnect the socket (socket transport only).
+     * The transport will reconnect automatically on next send().
+     *
+     * For HTTP transport, this is `undefined`.
+     */
+    disconnect: (() => void) | undefined;
 }
 /**
  * React hook for interacting with Octavus agents.
@@ -30,7 +59,7 @@ interface UseOctavusChatReturn {
  * reinitializes with a fresh chat instance. Use `initialMessages` if you need
  * to preserve messages across transport changes.
  *
- * @example
+ * @example Basic usage with HTTP transport
  * ```tsx
  * import { useOctavusChat, createHttpTransport } from '@octavus/react';
  *
@@ -61,6 +90,40 @@ interface UseOctavusChatReturn {
  *   );
  * }
  * ```
+ *
+ * @example Socket transport with eager connection
+ * ```tsx
+ * import { useOctavusChat, createSocketTransport } from '@octavus/react';
+ *
+ * function Chat() {
+ *   const transport = useMemo(
+ *     () => createSocketTransport({
+ *       connect: () => new Promise((resolve, reject) => {
+ *         const sock = new SockJS('/octavus');
+ *         sock.onopen = () => resolve(sock);
+ *         sock.onerror = () => reject(new Error('Connection failed'));
+ *       }),
+ *     }),
+ *     [],
+ *   );
+ *
+ *   const { messages, status, send, connectionState, connect, disconnect } =
+ *     useOctavusChat({ transport });
+ *
+ *   // Eager connection on mount
+ *   useEffect(() => {
+ *     connect?.();
+ *     return () => disconnect?.();
+ *   }, [connect, disconnect]);
+ *
+ *   return (
+ *     <div>
+ *       <StatusIndicator state={connectionState} />
+ *       {messages.map((msg) => <Message key={msg.id} message={msg} />)}
+ *     </div>
+ *   );
+ * }
+ * ```
  */
 declare function useOctavusChat(options: OctavusChatOptions): UseOctavusChatReturn;
 

package/dist/index.js

@@ -1,7 +1,8 @@
 // src/hooks/use-octavus-chat.ts
-import { useRef, useCallback, useSyncExternalStore } from "react";
+import { useRef, useCallback, useSyncExternalStore, useState, useEffect } from "react";
 import {
-  OctavusChat
+  OctavusChat,
+  isSocketTransport
 } from "@octavus/client-sdk";
 function useOctavusChat(options) {
   const chatRef = useRef(null);
@@ -12,6 +13,7 @@ function useOctavusChat(options) {
     transportRef.current = options.transport;
   }
   const chat = chatRef.current;
+  const transport = options.transport;
   const subscribe = useCallback((callback) => chat.subscribe(callback), [chat]);
   const getMessagesSnapshot = useCallback(() => chat.messages, [chat]);
   const getStatusSnapshot = useCallback(() => chat.status, [chat]);
@@ -19,17 +21,43 @@ function useOctavusChat(options) {
   const messages = useSyncExternalStore(subscribe, getMessagesSnapshot, getMessagesSnapshot);
   const status = useSyncExternalStore(subscribe, getStatusSnapshot, getStatusSnapshot);
   const error = useSyncExternalStore(subscribe, getErrorSnapshot, getErrorSnapshot);
+  const socketTransport = isSocketTransport(transport) ? transport : null;
+  const [connectionState, setConnectionState] = useState(
+    socketTransport?.connectionState
+  );
+  const [connectionError, setConnectionError] = useState(void 0);
+  useEffect(() => {
+    if (!socketTransport) {
+      setConnectionState(void 0);
+      setConnectionError(void 0);
+      return;
+    }
+    const unsubscribe = socketTransport.onConnectionStateChange((state, err) => {
+      setConnectionState(state);
+      setConnectionError(err);
+    });
+    return unsubscribe;
+  }, [socketTransport]);
   const send = useCallback(
     (triggerName, input, sendOptions) => chat.send(triggerName, input, sendOptions),
     [chat]
   );
   const stop = useCallback(() => chat.stop(), [chat]);
+  const connect = useCallback(
+    () => socketTransport?.connect() ?? Promise.resolve(),
+    [socketTransport]
+  );
+  const disconnect = useCallback(() => socketTransport?.disconnect(), [socketTransport]);
   return {
     messages,
     status,
     error,
+    connectionState,
+    connectionError,
     send,
-    stop
+    stop,
+    connect: socketTransport ? connect : void 0,
+    disconnect: socketTransport ? disconnect : void 0
   };
 }
 

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 } from 'react';\nimport {\n  OctavusChat,\n  type OctavusChatOptions,\n  type ChatStatus,\n  type UserMessageInput,\n  type UIMessage,\n  type Transport,\n} from '@octavus/client-sdk';\n\nexport type { OctavusChatOptions, ChatStatus, UserMessageInput };\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   * 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\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\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 */\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\n  // Subscribe to all state changes using useSyncExternalStore\n  // This provides automatic re-renders when state changes and proper SSR support\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  // Use useSyncExternalStore for each piece of state\n  // This hook is available in React 18+ and handles:\n  // - Subscription management\n  // - Proper re-rendering on state changes\n  // - SSR hydration (server snapshot)\n  const messages = useSyncExternalStore(subscribe, getMessagesSnapshot, getMessagesSnapshot);\n  const status = useSyncExternalStore(subscribe, getStatusSnapshot, getStatusSnapshot);\n  const error = useSyncExternalStore(subscribe, getErrorSnapshot, getErrorSnapshot);\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  return {\n    messages,\n    status,\n    error,\n    send,\n    stop,\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,4BAA4B;AAC1D;AAAA,EACE;AAAA,OAMK;AAmEA,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;AAIrB,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;AAO7D,QAAM,WAAW,qBAAqB,WAAW,qBAAqB,mBAAmB;AACzF,QAAM,SAAS,qBAAqB,WAAW,mBAAmB,iBAAiB;AACnF,QAAM,QAAQ,qBAAqB,WAAW,kBAAkB,gBAAgB;AAEhF,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,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;;;AClHA,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  isSocketTransport,\n  type OctavusChatOptions,\n  type ChatStatus,\n  type UserMessageInput,\n  type UIMessage,\n  type Transport,\n  type ConnectionState,\n} from '@octavus/client-sdk';\n\nexport type { OctavusChatOptions, ChatStatus, UserMessageInput };\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\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  // 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  };\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,OAOK;AAkIA,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;AAGlD,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,EAC7C;AACF;;;AC7MA,cAAc;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octavus/react",
-  "version": "0.0.9",
+  "version": "0.0.10",
   "description": "React bindings for Octavus agents",
   "license": "MIT",
   "author": "Octavus AI <dev@octavus.ai>",
@@ -29,7 +29,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@octavus/client-sdk": "^0.0.9"
+    "@octavus/client-sdk": "^0.0.10"
   },
   "peerDependencies": {
     "react": ">=18.0.0"