@tambo-ai/react 0.16.1 → 0.17.0

package/dist/hooks/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./react-query-hooks";
+export { useTamboComponentState } from "./use-component-state";
+export { useTamboCurrentMessage, useTamboMessageContext, } from "./use-current-message";
+export { useTamboStreamingProps } from "./use-streaming-props";
+export * from "./use-suggestions";
+export { useTamboThreads } from "./use-tambo-threads";
+export { useTamboThreadInput } from "./use-thread-input";
+//# sourceMappingURL=index.d.ts.map

package/dist/hooks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AACA,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,EACL,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/hooks/index.js

@@ -0,0 +1,32 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useTamboThreadInput = exports.useTamboThreads = exports.useTamboStreamingProps = exports.useTamboMessageContext = exports.useTamboCurrentMessage = exports.useTamboComponentState = void 0;
+// Export all hooks from this directory
+__exportStar(require("./react-query-hooks"), exports);
+var use_component_state_1 = require("./use-component-state");
+Object.defineProperty(exports, "useTamboComponentState", { enumerable: true, get: function () { return use_component_state_1.useTamboComponentState; } });
+var use_current_message_1 = require("./use-current-message");
+Object.defineProperty(exports, "useTamboCurrentMessage", { enumerable: true, get: function () { return use_current_message_1.useTamboCurrentMessage; } });
+Object.defineProperty(exports, "useTamboMessageContext", { enumerable: true, get: function () { return use_current_message_1.useTamboMessageContext; } });
+var use_streaming_props_1 = require("./use-streaming-props");
+Object.defineProperty(exports, "useTamboStreamingProps", { enumerable: true, get: function () { return use_streaming_props_1.useTamboStreamingProps; } });
+__exportStar(require("./use-suggestions"), exports);
+var use_tambo_threads_1 = require("./use-tambo-threads");
+Object.defineProperty(exports, "useTamboThreads", { enumerable: true, get: function () { return use_tambo_threads_1.useTamboThreads; } });
+var use_thread_input_1 = require("./use-thread-input");
+Object.defineProperty(exports, "useTamboThreadInput", { enumerable: true, get: function () { return use_thread_input_1.useTamboThreadInput; } });
+//# sourceMappingURL=index.js.map

package/dist/hooks/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,uCAAuC;AACvC,sDAAoC;AACpC,6DAA+D;AAAtD,6HAAA,sBAAsB,OAAA;AAC/B,6DAG+B;AAF7B,6HAAA,sBAAsB,OAAA;AACtB,6HAAA,sBAAsB,OAAA;AAExB,6DAA+D;AAAtD,6HAAA,sBAAsB,OAAA;AAC/B,oDAAkC;AAClC,yDAAsD;AAA7C,oHAAA,eAAe,OAAA;AACxB,uDAAyD;AAAhD,uHAAA,mBAAmB,OAAA","sourcesContent":["// Export all hooks from this directory\nexport * from \"./react-query-hooks\";\nexport { useTamboComponentState } from \"./use-component-state\";\nexport {\n  useTamboCurrentMessage,\n  useTamboMessageContext,\n} from \"./use-current-message\";\nexport { useTamboStreamingProps } from \"./use-streaming-props\";\nexport * from \"./use-suggestions\";\nexport { useTamboThreads } from \"./use-tambo-threads\";\nexport { useTamboThreadInput } from \"./use-thread-input\";\n"]}

package/dist/hooks/use-component-state.d.ts

@@ -1,9 +1,44 @@
-type StateUpdateResult<T> = [currentState: T, setState: (newState: T) => void];
+interface ComponentStateMeta {
+    isPending: boolean;
+}
+type StateUpdateResult<T> = [
+    currentState: T,
+    setState: (newState: T) => void,
+    meta: ComponentStateMeta
+];
 /**
- * Behaves similarly to useState, but the value is stored in the thread
- * message, and the state is keyed by the keyName
+ * A React hook that provides state management and passes user updates to Tambo.
+ * Benefits: Passes user changes to AI, and when threads are returned, state is preserved.
+ *
+ * @param keyName - The unique key to identify this state within the message's componentState object
+ * @param initialValue - Optional initial value for the state, used if no value exists in the message
+ * @param debounceTime - Optional debounce time in milliseconds (default: 300ms) to limit API calls
+ *
+ * @returns A tuple containing:
+ *   - The current state value
+ *   - A setter function to update the state (updates UI immediately, debounces server sync)
+ *   - A metadata object with properties like isPending to track sync status
+ *
+ * @example
+ * // Basic usage
+ * const [count, setCount, { isPending }] = useTamboComponentState("counter", 0);
+ *
+ * // Usage with object state
+ * const [formState, setFormState] = useTamboComponentState("myForm", {
+ *   name: "",
+ *   email: "",
+ *   message: ""
+ * });
+ *
+ * // Handling form input
+ * const handleChange = (e) => {
+ *   setFormState({
+ *     ...formState,
+ *     [e.target.name]: e.target.value
+ *   });
+ * };
  */
-export declare function useTamboComponentState<S = undefined>(keyName: string): StateUpdateResult<S | undefined>;
-export declare function useTamboComponentState<S>(keyName: string, initialValue?: S): StateUpdateResult<S>;
+export declare function useTamboComponentState<S = undefined>(keyName: string, initialValue?: S, debounceTime?: number): StateUpdateResult<S | undefined>;
+export declare function useTamboComponentState<S>(keyName: string, initialValue: S, debounceTime?: number): StateUpdateResult<S>;
 export {};
 //# sourceMappingURL=use-component-state.d.ts.map

package/dist/hooks/use-component-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-component-state.d.ts","sourceRoot":"","sources":["../../src/hooks/use-component-state.tsx"],"names":[],"mappings":"AAOA,KAAK,iBAAiB,CAAC,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,IAAI,CAAC,CAAC;AAE/E;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,GAAG,SAAS,EAClD,OAAO,EAAE,MAAM,GACd,iBAAiB,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;AACpC,wBAAgB,sBAAsB,CAAC,CAAC,EACtC,OAAO,EAAE,MAAM,EACf,YAAY,CAAC,EAAE,CAAC,GACf,iBAAiB,CAAC,CAAC,CAAC,CAAC"}
+{"version":3,"file":"use-component-state.d.ts","sourceRoot":"","sources":["../../src/hooks/use-component-state.tsx"],"names":[],"mappings":"AASA,UAAU,kBAAkB;IAC1B,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,KAAK,iBAAiB,CAAC,CAAC,IAAI;IAC1B,YAAY,EAAE,CAAC;IACf,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,IAAI;IAC/B,IAAI,EAAE,kBAAkB;CACzB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,wBAAgB,sBAAsB,CAAC,CAAC,GAAG,SAAS,EAClD,OAAO,EAAE,MAAM,EACf,YAAY,CAAC,EAAE,CAAC,EAChB,YAAY,CAAC,EAAE,MAAM,GACpB,iBAAiB,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;AACpC,wBAAgB,sBAAsB,CAAC,CAAC,EACtC,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,CAAC,EACf,YAAY,CAAC,EAAE,MAAM,GACpB,iBAAiB,CAAC,CAAC,CAAC,CAAC"}

package/dist/hooks/use-component-state.js

@@ -2,42 +2,136 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.useTamboComponentState = useTamboComponentState;
 const react_1 = require("react");
+const use_debounce_1 = require("use-debounce");
 const providers_1 = require("../providers");
 const use_current_message_1 = require("./use-current-message");
-function useTamboComponentState(keyName, initialValue) {
+function useTamboComponentState(keyName, initialValue, debounceTime = 300) {
     const { threadId, messageId } = (0, use_current_message_1.useTamboMessageContext)();
     const { updateThreadMessage } = (0, providers_1.useTamboThread)();
     const client = (0, providers_1.useTamboClient)();
     const message = (0, use_current_message_1.useTamboCurrentMessage)();
+    // Initial value management
     const [cachedInitialValue] = (0, react_1.useState)(() => initialValue);
-    const value = (0, react_1.useMemo)(() => {
-        if (!message?.componentState)
-            return cachedInitialValue;
-        return keyName in message.componentState
-            ? message.componentState[keyName]
-            : cachedInitialValue;
-    }, [cachedInitialValue, keyName, message?.componentState]);
+    // UI state management
+    const [localState, setLocalState] = (0, react_1.useState)(cachedInitialValue);
+    // Synchronization state
+    const [isPending, setIsPending] = (0, react_1.useState)(false);
+    // Track the last user-initiated value instead of a simple boolean flag
+    const [lastUserValue, setLastUserValue] = (0, react_1.useState)(null);
+    const [haveInitialized, setHaveInitialized] = (0, react_1.useState)(false);
+    // Determine if we need to initialize state
+    const shouldInitialize = !haveInitialized &&
+        message &&
+        cachedInitialValue !== undefined &&
+        (!message.componentState || !(keyName in message.componentState));
+    // Helper function to check if two values are deeply equal
+    const isEqual = (a, b) => {
+        if (a === b)
+            return true;
+        // Handle primitive types
+        if (typeof a !== "object" ||
+            typeof b !== "object" ||
+            a === null ||
+            b === null)
+            return false;
+        // For objects and arrays, do a shallow comparison for simplicity
+        // This could be enhanced with a proper deep equality check if needed
+        if (Array.isArray(a) && Array.isArray(b)) {
+            if (a.length !== b.length)
+                return false;
+            return a.every((val, idx) => val === b[idx]);
+        }
+        const keysA = Object.keys(a);
+        const keysB = Object.keys(b);
+        if (keysA.length !== keysB.length)
+            return false;
+        return keysA.every((key) => a[key] === b[key]);
+    };
+    // Sync local state with message state on initial load and when message changes
+    (0, react_1.useEffect)(() => {
+        if (message?.componentState && keyName in message.componentState) {
+            const messageState = message.componentState[keyName];
+            // If this is a user-initiated state that matches what we're getting from server,
+            // we can clear the lastUserValue flag since it's been synchronized
+            if (lastUserValue !== null && isEqual(messageState, lastUserValue)) {
+                setLastUserValue(null);
+            }
+            // Update local state with server state unless user has specifically changed this value
+            // This allows streaming updates to continue while protecting user edits
+            if (lastUserValue === null || !isEqual(localState, lastUserValue)) {
+                setLocalState(messageState);
+            }
+        }
+        // Otherwise fall back to initial value if we have one
+        else if (cachedInitialValue !== undefined && !localState) {
+            setLocalState(cachedInitialValue);
+        }
+    }, [
+        keyName,
+        message?.componentState,
+        cachedInitialValue,
+        lastUserValue,
+        localState,
+    ]);
+    // Create debounced save function for efficient server synchronization
+    const debouncedSave = (0, use_debounce_1.useDebouncedCallback)(async (newValue) => {
+        if (!message) {
+            console.warn(`Cannot update missing message ${messageId} for state key "${keyName}"`);
+            setLastUserValue(null);
+            return;
+        }
+        setIsPending(true);
+        try {
+            const messageUpdate = {
+                ...message,
+                componentState: {
+                    ...message.componentState,
+                    [keyName]: newValue,
+                },
+            };
+            const componentStateUpdate = {
+                state: { [keyName]: newValue },
+            };
+            await Promise.all([
+                updateThreadMessage(messageId, messageUpdate, false),
+                client.beta.threads.messages.updateComponentState(threadId, messageId, componentStateUpdate),
+            ]);
+            // Only clear the lastUserValue when we've successfully synced this exact value
+            if (isEqual(newValue, lastUserValue)) {
+                setLastUserValue(null);
+            }
+        }
+        catch (err) {
+            console.error(`Failed to save component state for key "${keyName}":`, err);
+        }
+        finally {
+            setIsPending(false);
+        }
+    }, debounceTime);
+    // Initialize state on first render if needed
     const initializeState = (0, react_1.useCallback)(async () => {
         if (!message) {
-            console.warn(`Cannot initialize state for missing message ${messageId}`);
+            console.warn(`Cannot initialize state for missing message ${messageId} with key "${keyName}"`);
             return;
         }
         try {
+            const messageUpdate = {
+                ...message,
+                componentState: {
+                    ...message.componentState,
+                    [keyName]: cachedInitialValue,
+                },
+            };
+            const componentStateUpdate = {
+                state: { [keyName]: cachedInitialValue },
+            };
             await Promise.all([
-                updateThreadMessage(messageId, {
-                    ...message,
-                    componentState: {
-                        ...message.componentState,
-                        [keyName]: cachedInitialValue,
-                    },
-                }, false),
-                client.beta.threads.messages.updateComponentState(threadId, messageId, {
-                    state: { [keyName]: cachedInitialValue },
-                }),
+                updateThreadMessage(messageId, messageUpdate, false),
+                client.beta.threads.messages.updateComponentState(threadId, messageId, componentStateUpdate),
             ]);
         }
         catch (err) {
-            console.warn("Failed to initialize component state:", err);
+            console.warn(`Failed to initialize component state for key "${keyName}":`, err);
         }
     }, [
         cachedInitialValue,
@@ -48,39 +142,36 @@ function useTamboComponentState(keyName, initialValue) {
         threadId,
         updateThreadMessage,
     ]);
-    const [haveInitialized, setHaveInitialized] = (0, react_1.useState)(false);
-    const shouldInitialize = !haveInitialized &&
-        message &&
-        cachedInitialValue !== undefined &&
-        (!message.componentState || !(keyName in message.componentState));
-    // send initial state
+    // Send initial state when component mounts
     (0, react_1.useEffect)(() => {
         if (shouldInitialize) {
             initializeState();
             setHaveInitialized(true);
         }
     }, [initializeState, shouldInitialize]);
-    const setValue = (0, react_1.useCallback)(async (newValue) => {
-        if (!message) {
-            console.warn(`Cannot update missing message ${messageId}`);
-            return;
+    // setValue function for updating state
+    // Updates local state immediately and schedules debounced server sync
+    const setValue = (0, react_1.useCallback)((newValue) => {
+        // Track this as a user-initiated update
+        setLastUserValue(newValue);
+        setLocalState(newValue);
+        // Only trigger server updates if we have a message
+        if (message) {
+            debouncedSave(newValue);
         }
-        await updateThreadMessage(messageId, {
-            ...message,
-            componentState: {
-                ...message.componentState,
-                [keyName]: newValue,
-            },
-        }, false);
-        await client.beta.threads.messages.updateComponentState(threadId, messageId, { state: { [keyName]: newValue } });
-    }, [
-        client.beta.threads.messages,
-        keyName,
-        message,
-        messageId,
-        threadId,
-        updateThreadMessage,
-    ]);
-    return [value, setValue];
+        else {
+            console.warn(`Cannot update server for missing message ${messageId} with key "${keyName}"`);
+            setLastUserValue(null);
+        }
+    }, [debouncedSave, message, messageId, keyName]);
+    // Ensure pending changes are flushed on unmount
+    (0, react_1.useEffect)(() => {
+        return () => {
+            debouncedSave.flush();
+            setLastUserValue(null);
+        };
+    }, [debouncedSave]);
+    // Return the local state for immediate UI rendering
+    return [localState, setValue, { isPending }];
 }
 //# sourceMappingURL=use-component-state.js.map

package/dist/hooks/use-component-state.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-component-state.js","sourceRoot":"","sources":["../../src/hooks/use-component-state.tsx"],"names":[],"mappings":"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","sourcesContent":["import { useCallback, useEffect, useMemo, useState } from \"react\";\nimport { useTamboClient, useTamboThread } from \"../providers\";\nimport {\n  useTamboCurrentMessage,\n  useTamboMessageContext,\n} from \"./use-current-message\";\n\ntype StateUpdateResult<T> = [currentState: T, setState: (newState: T) => void];\n\n/**\n * Behaves similarly to useState, but the value is stored in the thread\n * message, and the state is keyed by the keyName\n */\nexport function useTamboComponentState<S = undefined>(\n  keyName: string,\n): StateUpdateResult<S | undefined>;\nexport function useTamboComponentState<S>(\n  keyName: string,\n  initialValue?: S,\n): StateUpdateResult<S>;\nexport function useTamboComponentState<S>(\n  keyName: string,\n  initialValue?: S,\n): StateUpdateResult<S> {\n  const { threadId, messageId } = useTamboMessageContext();\n  const { updateThreadMessage } = useTamboThread();\n  const client = useTamboClient();\n\n  const message = useTamboCurrentMessage();\n  const [cachedInitialValue] = useState(() => initialValue);\n\n  const value = useMemo(() => {\n    if (!message?.componentState) return cachedInitialValue;\n    return keyName in message.componentState\n      ? (message.componentState[keyName] as S)\n      : cachedInitialValue;\n  }, [cachedInitialValue, keyName, message?.componentState]);\n\n  const initializeState = useCallback(async () => {\n    if (!message) {\n      console.warn(`Cannot initialize state for missing message ${messageId}`);\n      return;\n    }\n    try {\n      await Promise.all([\n        updateThreadMessage(\n          messageId,\n          {\n            ...message,\n            componentState: {\n              ...message.componentState,\n              [keyName]: cachedInitialValue,\n            },\n          },\n          false,\n        ),\n        client.beta.threads.messages.updateComponentState(threadId, messageId, {\n          state: { [keyName]: cachedInitialValue },\n        }),\n      ]);\n    } catch (err) {\n      console.warn(\"Failed to initialize component state:\", err);\n    }\n  }, [\n    cachedInitialValue,\n    client.beta.threads.messages,\n    keyName,\n    message,\n    messageId,\n    threadId,\n    updateThreadMessage,\n  ]);\n  const [haveInitialized, setHaveInitialized] = useState(false);\n  const shouldInitialize =\n    !haveInitialized &&\n    message &&\n    cachedInitialValue !== undefined &&\n    (!message.componentState || !(keyName in message.componentState));\n\n  // send initial state\n  useEffect(() => {\n    if (shouldInitialize) {\n      initializeState();\n      setHaveInitialized(true);\n    }\n  }, [initializeState, shouldInitialize]);\n\n  const setValue = useCallback(\n    async (newValue: S) => {\n      if (!message) {\n        console.warn(`Cannot update missing message ${messageId}`);\n        return;\n      }\n      await updateThreadMessage(\n        messageId,\n        {\n          ...message,\n          componentState: {\n            ...message.componentState,\n            [keyName]: newValue,\n          },\n        },\n        false,\n      );\n      await client.beta.threads.messages.updateComponentState(\n        threadId,\n        messageId,\n        { state: { [keyName]: newValue } },\n      );\n    },\n    [\n      client.beta.threads.messages,\n      keyName,\n      message,\n      messageId,\n      threadId,\n      updateThreadMessage,\n    ],\n  );\n  return [value as S, setValue];\n}\n"]}
+{"version":3,"file":"use-component-state.js","sourceRoot":"","sources":["../../src/hooks/use-component-state.tsx"],"names":[],"mappings":"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","sourcesContent":["import { useCallback, useEffect, useState } from \"react\";\nimport { useDebouncedCallback } from \"use-debounce\";\nimport { useTamboClient, useTamboThread } from \"../providers\";\nimport {\n  useTamboCurrentMessage,\n  useTamboMessageContext,\n} from \"./use-current-message\";\n\n// Define metadata interface for better extensibility\ninterface ComponentStateMeta {\n  isPending: boolean;\n}\n\ntype StateUpdateResult<T> = [\n  currentState: T,\n  setState: (newState: T) => void,\n  meta: ComponentStateMeta,\n];\n\n/**\n * A React hook that provides state management and passes user updates to Tambo.\n * Benefits: Passes user changes to AI, and when threads are returned, state is preserved.\n *\n * @param keyName - The unique key to identify this state within the message's componentState object\n * @param initialValue - Optional initial value for the state, used if no value exists in the message\n * @param debounceTime - Optional debounce time in milliseconds (default: 300ms) to limit API calls\n *\n * @returns A tuple containing:\n *   - The current state value\n *   - A setter function to update the state (updates UI immediately, debounces server sync)\n *   - A metadata object with properties like isPending to track sync status\n *\n * @example\n * // Basic usage\n * const [count, setCount, { isPending }] = useTamboComponentState(\"counter\", 0);\n *\n * // Usage with object state\n * const [formState, setFormState] = useTamboComponentState(\"myForm\", {\n *   name: \"\",\n *   email: \"\",\n *   message: \"\"\n * });\n *\n * // Handling form input\n * const handleChange = (e) => {\n *   setFormState({\n *     ...formState,\n *     [e.target.name]: e.target.value\n *   });\n * };\n */\n\nexport function useTamboComponentState<S = undefined>(\n  keyName: string,\n  initialValue?: S,\n  debounceTime?: number,\n): StateUpdateResult<S | undefined>;\nexport function useTamboComponentState<S>(\n  keyName: string,\n  initialValue: S,\n  debounceTime?: number,\n): StateUpdateResult<S>;\nexport function useTamboComponentState<S>(\n  keyName: string,\n  initialValue?: S,\n  debounceTime = 300,\n): StateUpdateResult<S> {\n  const { threadId, messageId } = useTamboMessageContext();\n  const { updateThreadMessage } = useTamboThread();\n  const client = useTamboClient();\n  const message = useTamboCurrentMessage();\n\n  // Initial value management\n  const [cachedInitialValue] = useState(() => initialValue);\n  // UI state management\n  const [localState, setLocalState] = useState<S | undefined>(\n    cachedInitialValue,\n  );\n  // Synchronization state\n  const [isPending, setIsPending] = useState(false);\n  // Track the last user-initiated value instead of a simple boolean flag\n  const [lastUserValue, setLastUserValue] = useState<S | null>(null);\n  const [haveInitialized, setHaveInitialized] = useState(false);\n\n  // Determine if we need to initialize state\n  const shouldInitialize =\n    !haveInitialized &&\n    message &&\n    cachedInitialValue !== undefined &&\n    (!message.componentState || !(keyName in message.componentState));\n\n  // Helper function to check if two values are deeply equal\n  const isEqual = (a: any, b: any): boolean => {\n    if (a === b) return true;\n\n    // Handle primitive types\n    if (\n      typeof a !== \"object\" ||\n      typeof b !== \"object\" ||\n      a === null ||\n      b === null\n    )\n      return false;\n\n    // For objects and arrays, do a shallow comparison for simplicity\n    // This could be enhanced with a proper deep equality check if needed\n    if (Array.isArray(a) && Array.isArray(b)) {\n      if (a.length !== b.length) return false;\n      return a.every((val, idx) => val === b[idx]);\n    }\n\n    const keysA = Object.keys(a);\n    const keysB = Object.keys(b);\n\n    if (keysA.length !== keysB.length) return false;\n\n    return keysA.every((key) => a[key] === b[key]);\n  };\n\n  // Sync local state with message state on initial load and when message changes\n  useEffect(() => {\n    if (message?.componentState && keyName in message.componentState) {\n      const messageState = message.componentState[keyName] as S;\n\n      // If this is a user-initiated state that matches what we're getting from server,\n      // we can clear the lastUserValue flag since it's been synchronized\n      if (lastUserValue !== null && isEqual(messageState, lastUserValue)) {\n        setLastUserValue(null);\n      }\n\n      // Update local state with server state unless user has specifically changed this value\n      // This allows streaming updates to continue while protecting user edits\n      if (lastUserValue === null || !isEqual(localState, lastUserValue)) {\n        setLocalState(messageState);\n      }\n    }\n    // Otherwise fall back to initial value if we have one\n    else if (cachedInitialValue !== undefined && !localState) {\n      setLocalState(cachedInitialValue);\n    }\n  }, [\n    keyName,\n    message?.componentState,\n    cachedInitialValue,\n    lastUserValue,\n    localState,\n  ]);\n\n  // Create debounced save function for efficient server synchronization\n  const debouncedSave = useDebouncedCallback(async (newValue: S) => {\n    if (!message) {\n      console.warn(\n        `Cannot update missing message ${messageId} for state key \"${keyName}\"`,\n      );\n      setLastUserValue(null);\n      return;\n    }\n\n    setIsPending(true);\n    try {\n      const messageUpdate = {\n        ...message,\n        componentState: {\n          ...message.componentState,\n          [keyName]: newValue,\n        },\n      };\n\n      const componentStateUpdate = {\n        state: { [keyName]: newValue },\n      };\n\n      await Promise.all([\n        updateThreadMessage(messageId, messageUpdate, false),\n        client.beta.threads.messages.updateComponentState(\n          threadId,\n          messageId,\n          componentStateUpdate,\n        ),\n      ]);\n\n      // Only clear the lastUserValue when we've successfully synced this exact value\n      if (isEqual(newValue, lastUserValue)) {\n        setLastUserValue(null);\n      }\n    } catch (err) {\n      console.error(\n        `Failed to save component state for key \"${keyName}\":`,\n        err,\n      );\n    } finally {\n      setIsPending(false);\n    }\n  }, debounceTime);\n\n  // Initialize state on first render if needed\n  const initializeState = useCallback(async () => {\n    if (!message) {\n      console.warn(\n        `Cannot initialize state for missing message ${messageId} with key \"${keyName}\"`,\n      );\n      return;\n    }\n\n    try {\n      const messageUpdate = {\n        ...message,\n        componentState: {\n          ...message.componentState,\n          [keyName]: cachedInitialValue,\n        },\n      };\n\n      const componentStateUpdate = {\n        state: { [keyName]: cachedInitialValue },\n      };\n\n      await Promise.all([\n        updateThreadMessage(messageId, messageUpdate, false),\n        client.beta.threads.messages.updateComponentState(\n          threadId,\n          messageId,\n          componentStateUpdate,\n        ),\n      ]);\n    } catch (err) {\n      console.warn(\n        `Failed to initialize component state for key \"${keyName}\":`,\n        err,\n      );\n    }\n  }, [\n    cachedInitialValue,\n    client.beta.threads.messages,\n    keyName,\n    message,\n    messageId,\n    threadId,\n    updateThreadMessage,\n  ]);\n\n  // Send initial state when component mounts\n  useEffect(() => {\n    if (shouldInitialize) {\n      initializeState();\n      setHaveInitialized(true);\n    }\n  }, [initializeState, shouldInitialize]);\n\n  // setValue function for updating state\n  // Updates local state immediately and schedules debounced server sync\n  const setValue = useCallback(\n    (newValue: S) => {\n      // Track this as a user-initiated update\n      setLastUserValue(newValue);\n      setLocalState(newValue);\n\n      // Only trigger server updates if we have a message\n      if (message) {\n        debouncedSave(newValue);\n      } else {\n        console.warn(\n          `Cannot update server for missing message ${messageId} with key \"${keyName}\"`,\n        );\n        setLastUserValue(null);\n      }\n    },\n    [debouncedSave, message, messageId, keyName],\n  );\n\n  // Ensure pending changes are flushed on unmount\n  useEffect(() => {\n    return () => {\n      debouncedSave.flush();\n      setLastUserValue(null);\n    };\n  }, [debouncedSave]);\n\n  // Return the local state for immediate UI rendering\n  return [localState as S, setValue, { isPending }];\n}\n"]}

package/dist/hooks/use-streaming-props.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A helper hook that automatically updates Tambo component state when specified props change.
+ *
+ * This hook streamlines the common pattern of updating component state when receiving new
+ * streamed values from Tambo, eliminating the need to write repetitive useEffect code.
+ *
+ * @param currentState - The current state object from useTamboComponentState
+ * @param setState - The setState function from useTamboComponentState
+ * @param streamingProps - An object mapping state keys to prop values that should update the state
+ *
+ * @example
+ * ```tsx
+ * // Instead of writing a complex useEffect:
+ * const [emailState, setEmailState] = useTamboComponentState("email", initialState);
+ *
+ * // Simply use:
+ * useTamboStreamingProps(emailState, setEmailState, {
+ *   subject: aiGeneratedSubject,
+ *   body: aiGeneratedBody,
+ *   usersEmail: usersEmail
+ * });
+ * ```
+ */
+export declare function useTamboStreamingProps<T extends Record<string, any>>(currentState: T | undefined, setState: (state: T) => void, streamingProps: Partial<T>): void;
+//# sourceMappingURL=use-streaming-props.d.ts.map

package/dist/hooks/use-streaming-props.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-streaming-props.d.ts","sourceRoot":"","sources":["../../src/hooks/use-streaming-props.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAClE,YAAY,EAAE,CAAC,GAAG,SAAS,EAC3B,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,EAC5B,cAAc,EAAE,OAAO,CAAC,CAAC,CAAC,QAuB3B"}

package/dist/hooks/use-streaming-props.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useTamboStreamingProps = useTamboStreamingProps;
+const react_1 = require("react");
+/**
+ * A helper hook that automatically updates Tambo component state when specified props change.
+ *
+ * This hook streamlines the common pattern of updating component state when receiving new
+ * streamed values from Tambo, eliminating the need to write repetitive useEffect code.
+ *
+ * @param currentState - The current state object from useTamboComponentState
+ * @param setState - The setState function from useTamboComponentState
+ * @param streamingProps - An object mapping state keys to prop values that should update the state
+ *
+ * @example
+ * ```tsx
+ * // Instead of writing a complex useEffect:
+ * const [emailState, setEmailState] = useTamboComponentState("email", initialState);
+ *
+ * // Simply use:
+ * useTamboStreamingProps(emailState, setEmailState, {
+ *   subject: aiGeneratedSubject,
+ *   body: aiGeneratedBody,
+ *   usersEmail: usersEmail
+ * });
+ * ```
+ */
+function useTamboStreamingProps(currentState, setState, streamingProps) {
+    (0, react_1.useEffect)(() => {
+        if (currentState) {
+            let shouldUpdate = false;
+            const updates = {};
+            Object.entries(streamingProps).forEach(([key, value]) => {
+                if (value !== undefined && value !== currentState[key]) {
+                    shouldUpdate = true;
+                    updates[key] = value;
+                }
+            });
+            if (shouldUpdate) {
+                setState({
+                    ...currentState,
+                    ...updates,
+                });
+            }
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [currentState, setState, ...Object.values(streamingProps)]);
+}
+//# sourceMappingURL=use-streaming-props.js.map

package/dist/hooks/use-streaming-props.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-streaming-props.js","sourceRoot":"","sources":["../../src/hooks/use-streaming-props.tsx"],"names":[],"mappings":";;AAyBA,wDA0BC;AAnDD,iCAAkC;AAElC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,SAAgB,sBAAsB,CACpC,YAA2B,EAC3B,QAA4B,EAC5B,cAA0B;IAE1B,IAAA,iBAAS,EAAC,GAAG,EAAE;QACb,IAAI,YAAY,EAAE,CAAC;YACjB,IAAI,YAAY,GAAG,KAAK,CAAC;YACzB,MAAM,OAAO,GAAe,EAAE,CAAC;YAE/B,MAAM,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE;gBACtD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC;oBACvD,YAAY,GAAG,IAAI,CAAC;oBACpB,OAAO,CAAC,GAAc,CAAC,GAAG,KAAmB,CAAC;gBAChD,CAAC;YACH,CAAC,CAAC,CAAC;YAEH,IAAI,YAAY,EAAE,CAAC;gBACjB,QAAQ,CAAC;oBACP,GAAG,YAAY;oBACf,GAAG,OAAO;iBACX,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QACD,uDAAuD;IACzD,CAAC,EAAE,CAAC,YAAY,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;AACjE,CAAC","sourcesContent":["import { useEffect } from \"react\";\n\n/**\n * A helper hook that automatically updates Tambo component state when specified props change.\n *\n * This hook streamlines the common pattern of updating component state when receiving new\n * streamed values from Tambo, eliminating the need to write repetitive useEffect code.\n *\n * @param currentState - The current state object from useTamboComponentState\n * @param setState - The setState function from useTamboComponentState\n * @param streamingProps - An object mapping state keys to prop values that should update the state\n *\n * @example\n * ```tsx\n * // Instead of writing a complex useEffect:\n * const [emailState, setEmailState] = useTamboComponentState(\"email\", initialState);\n *\n * // Simply use:\n * useTamboStreamingProps(emailState, setEmailState, {\n *   subject: aiGeneratedSubject,\n *   body: aiGeneratedBody,\n *   usersEmail: usersEmail\n * });\n * ```\n */\nexport function useTamboStreamingProps<T extends Record<string, any>>(\n  currentState: T | undefined,\n  setState: (state: T) => void,\n  streamingProps: Partial<T>,\n) {\n  useEffect(() => {\n    if (currentState) {\n      let shouldUpdate = false;\n      const updates: Partial<T> = {};\n\n      Object.entries(streamingProps).forEach(([key, value]) => {\n        if (value !== undefined && value !== currentState[key]) {\n          shouldUpdate = true;\n          updates[key as keyof T] = value as T[keyof T];\n        }\n      });\n\n      if (shouldUpdate) {\n        setState({\n          ...currentState,\n          ...updates,\n        });\n      }\n    }\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [currentState, setState, ...Object.values(streamingProps)]);\n}\n"]}

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 /** Exports for the library. Only publically available exports are re-exported here. Anything not exported here is not supported and may change or break at any time. */
 export { useTamboComponentState } from "./hooks/use-component-state";
 export { TamboMessageProvider, useTamboCurrentMessage, useTamboMessageContext, } from "./hooks/use-current-message";
+export { useTamboStreamingProps } from "./hooks/use-streaming-props";
 export * from "./hooks/use-suggestions";
 export { useTamboThreadInput } from "./hooks/use-thread-input";
 export * from "./providers";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,wKAAwK;AACxK,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,6BAA6B,CAAC;AACrC,cAAc,yBAAyB,CAAC;AACxC,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAG/D,cAAc,aAAa,CAAC;AAG5B,YAAY,EACV,QAAQ,EACR,cAAc,EACd,YAAY,GACb,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,UAAU,EACV,wBAAwB,EACxB,0BAA0B,EAC1B,sBAAsB,GACvB,MAAM,6DAA6D,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EACL,KAAK,4BAA4B,EACjC,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,SAAS,GACf,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,eAAe,EACf,KAAK,kBAAkB,GACxB,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,wKAAwK;AACxK,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,cAAc,yBAAyB,CAAC;AACxC,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAG/D,cAAc,aAAa,CAAC;AAG5B,YAAY,EACV,QAAQ,EACR,cAAc,EACd,YAAY,GACb,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,UAAU,EACV,wBAAwB,EACxB,0BAA0B,EAC1B,sBAAsB,GACvB,MAAM,6DAA6D,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EACL,KAAK,4BAA4B,EACjC,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,SAAS,GACf,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,eAAe,EACf,KAAK,kBAAkB,GACxB,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GenerationStage = exports.useTamboThreads = exports.useTamboThreadInput = exports.useTamboMessageContext = exports.useTamboCurrentMessage = exports.TamboMessageProvider = exports.useTamboComponentState = void 0;
+exports.GenerationStage = exports.useTamboThreads = exports.useTamboThreadInput = exports.useTamboStreamingProps = exports.useTamboMessageContext = exports.useTamboCurrentMessage = exports.TamboMessageProvider = exports.useTamboComponentState = void 0;
 /** Exports for the library. Only publically available exports are re-exported here. Anything not exported here is not supported and may change or break at any time. */
 var use_component_state_1 = require("./hooks/use-component-state");
 Object.defineProperty(exports, "useTamboComponentState", { enumerable: true, get: function () { return use_component_state_1.useTamboComponentState; } });
@@ -22,6 +22,8 @@ var use_current_message_1 = require("./hooks/use-current-message");
 Object.defineProperty(exports, "TamboMessageProvider", { enumerable: true, get: function () { return use_current_message_1.TamboMessageProvider; } });
 Object.defineProperty(exports, "useTamboCurrentMessage", { enumerable: true, get: function () { return use_current_message_1.useTamboCurrentMessage; } });
 Object.defineProperty(exports, "useTamboMessageContext", { enumerable: true, get: function () { return use_current_message_1.useTamboMessageContext; } });
+var use_streaming_props_1 = require("./hooks/use-streaming-props");
+Object.defineProperty(exports, "useTamboStreamingProps", { enumerable: true, get: function () { return use_streaming_props_1.useTamboStreamingProps; } });
 __exportStar(require("./hooks/use-suggestions"), exports);
 var use_thread_input_1 = require("./hooks/use-thread-input");
 Object.defineProperty(exports, "useTamboThreadInput", { enumerable: true, get: function () { return use_thread_input_1.useTamboThreadInput; } });

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,wKAAwK;AACxK,mEAAqE;AAA5D,6HAAA,sBAAsB,OAAA;AAC/B,mEAIqC;AAHnC,2HAAA,oBAAoB,OAAA;AACpB,6HAAA,sBAAsB,OAAA;AACtB,6HAAA,sBAAsB,OAAA;AAExB,0DAAwC;AACxC,6DAA+D;AAAtD,uHAAA,mBAAmB,OAAA;AAE5B,gCAAgC;AAChC,8CAA4B;AAc5B,+DAA4D;AAAnD,oHAAA,eAAe,OAAA;AAQxB,mFAG6C;AAF3C,8HAAA,eAAe,OAAA","sourcesContent":["/** Exports for the library. Only publically available exports are re-exported here. Anything not exported here is not supported and may change or break at any time. */\nexport { useTamboComponentState } from \"./hooks/use-component-state\";\nexport {\n  TamboMessageProvider,\n  useTamboCurrentMessage,\n  useTamboMessageContext,\n} from \"./hooks/use-current-message\";\nexport * from \"./hooks/use-suggestions\";\nexport { useTamboThreadInput } from \"./hooks/use-thread-input\";\n\n// Re-export provider components\nexport * from \"./providers\";\n\n// Re-export types from Tambo Node SDK\nexport type {\n  APIError,\n  RateLimitError,\n  TamboAIError,\n} from \"@tambo-ai/typescript-sdk\";\nexport type {\n  Suggestion,\n  SuggestionGenerateParams,\n  SuggestionGenerateResponse,\n  SuggestionListResponse,\n} from \"@tambo-ai/typescript-sdk/resources/beta/threads/suggestions\";\nexport { useTamboThreads } from \"./hooks/use-tambo-threads\";\nexport {\n  type ComponentContextToolMetadata,\n  type ComponentRegistry,\n  type ParameterSpec,\n  type RegisteredComponent,\n  type TamboTool,\n} from \"./model/component-metadata\";\nexport {\n  GenerationStage,\n  type TamboThreadMessage,\n} from \"./model/generate-component-response\";\nexport { type TamboThread } from \"./model/tambo-thread\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,wKAAwK;AACxK,mEAAqE;AAA5D,6HAAA,sBAAsB,OAAA;AAC/B,mEAIqC;AAHnC,2HAAA,oBAAoB,OAAA;AACpB,6HAAA,sBAAsB,OAAA;AACtB,6HAAA,sBAAsB,OAAA;AAExB,mEAAqE;AAA5D,6HAAA,sBAAsB,OAAA;AAC/B,0DAAwC;AACxC,6DAA+D;AAAtD,uHAAA,mBAAmB,OAAA;AAE5B,gCAAgC;AAChC,8CAA4B;AAc5B,+DAA4D;AAAnD,oHAAA,eAAe,OAAA;AAQxB,mFAG6C;AAF3C,8HAAA,eAAe,OAAA","sourcesContent":["/** Exports for the library. Only publically available exports are re-exported here. Anything not exported here is not supported and may change or break at any time. */\nexport { useTamboComponentState } from \"./hooks/use-component-state\";\nexport {\n  TamboMessageProvider,\n  useTamboCurrentMessage,\n  useTamboMessageContext,\n} from \"./hooks/use-current-message\";\nexport { useTamboStreamingProps } from \"./hooks/use-streaming-props\";\nexport * from \"./hooks/use-suggestions\";\nexport { useTamboThreadInput } from \"./hooks/use-thread-input\";\n\n// Re-export provider components\nexport * from \"./providers\";\n\n// Re-export types from Tambo Node SDK\nexport type {\n  APIError,\n  RateLimitError,\n  TamboAIError,\n} from \"@tambo-ai/typescript-sdk\";\nexport type {\n  Suggestion,\n  SuggestionGenerateParams,\n  SuggestionGenerateResponse,\n  SuggestionListResponse,\n} from \"@tambo-ai/typescript-sdk/resources/beta/threads/suggestions\";\nexport { useTamboThreads } from \"./hooks/use-tambo-threads\";\nexport {\n  type ComponentContextToolMetadata,\n  type ComponentRegistry,\n  type ParameterSpec,\n  type RegisteredComponent,\n  type TamboTool,\n} from \"./model/component-metadata\";\nexport {\n  GenerationStage,\n  type TamboThreadMessage,\n} from \"./model/generate-component-response\";\nexport { type TamboThread } from \"./model/tambo-thread\";\n"]}

package/dist/providers/tambo-thread-provider.d.ts

@@ -4,7 +4,7 @@ import { GenerationStage, TamboThreadMessage } from "../model/generate-component
 import { TamboThread } from "../model/tambo-thread";
 export interface TamboThreadContextProps {
     thread: TamboThread;
-    switchCurrentThread: (threadId: string) => void;
+    switchCurrentThread: (threadId: string, fetch?: boolean) => void;
     addThreadMessage: (message: TamboThreadMessage, sendToServer: boolean) => Promise<TamboAI.Beta.Threads.ThreadMessage[]>;
     updateThreadMessage: (id: string, message: TamboThreadMessage, sendToServer: boolean) => Promise<void>;
     setLastThreadStatus: (status: GenerationStage) => void;

package/dist/providers/tambo-thread-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tambo-thread-provider.d.ts","sourceRoot":"","sources":["../../src/providers/tambo-thread-provider.tsx"],"names":[],"mappings":"AACA,OAAO,OAA0B,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,EAEZ,iBAAiB,EAMlB,MAAM,OAAO,CAAC;AACf,OAAO,EACL,eAAe,EAEf,kBAAkB,EACnB,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAOpD,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,WAAW,CAAC;IACpB,mBAAmB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAChD,gBAAgB,EAAE,CAChB,OAAO,EAAE,kBAAkB,EAC3B,YAAY,EAAE,OAAO,KAClB,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IACnD,mBAAmB,EAAE,CACnB,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,kBAAkB,EAC3B,YAAY,EAAE,OAAO,KAClB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,mBAAmB,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,CAAC;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,iBAAiB,EAAE,CACjB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,KACE,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACjC,eAAe,EAAE,eAAe,CAAC;IACjC,uBAAuB,EAAE,MAAM,CAAC;IAChC,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,EAAE,WAOhC,CAAC;AAEF,eAAO,MAAM,kBAAkB,wCAwB7B,CAAC;AAEH,eAAO,MAAM,mBAAmB,EAAE,KAAK,CAAC,EAAE,CAAC,iBAAiB,CA0e3D,CAAC;AAEF,eAAO,MAAM,cAAc,+BAM1B,CAAC"}
+{"version":3,"file":"tambo-thread-provider.d.ts","sourceRoot":"","sources":["../../src/providers/tambo-thread-provider.tsx"],"names":[],"mappings":"AACA,OAAO,OAA0B,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,EAEZ,iBAAiB,EAMlB,MAAM,OAAO,CAAC;AACf,OAAO,EACL,eAAe,EAEf,kBAAkB,EACnB,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAOpD,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,WAAW,CAAC;IACpB,mBAAmB,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IACjE,gBAAgB,EAAE,CAChB,OAAO,EAAE,kBAAkB,EAC3B,YAAY,EAAE,OAAO,KAClB,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IACnD,mBAAmB,EAAE,CACnB,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,kBAAkB,EAC3B,YAAY,EAAE,OAAO,KAClB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,mBAAmB,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,CAAC;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,iBAAiB,EAAE,CACjB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,KACE,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACjC,eAAe,EAAE,eAAe,CAAC;IACjC,uBAAuB,EAAE,MAAM,CAAC;IAChC,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,EAAE,WAOhC,CAAC;AAEF,eAAO,MAAM,kBAAkB,wCAwB7B,CAAC;AAEH,eAAO,MAAM,mBAAmB,EAAE,KAAK,CAAC,EAAE,CAAC,iBAAiB,CA0e3D,CAAC;AAEF,eAAO,MAAM,cAAc,+BAM1B,CAAC"}