@tambo-ai/react 0.70.0 → 0.72.0

package/dist/v1/utils/tool-executor.js

@@ -0,0 +1,103 @@
+"use strict";
+/**
+ * Tool Executor for v1 API
+ *
+ * Handles automatic execution of client-side tools when the model
+ * requests them via `tambo.run.awaiting_input` events.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeClientTool = executeClientTool;
+exports.executeAllPendingTools = executeAllPendingTools;
+/**
+ * Execute a single client-side tool and return the result.
+ * @param tool - The tool definition from the registry
+ * @param toolCallId - The ID of the tool call to respond to
+ * @param args - The parsed arguments for the tool
+ * @returns ToolResultContent with the execution result or error
+ */
+async function executeClientTool(tool, toolCallId, args) {
+    try {
+        const result = await tool.tool(args);
+        // Transform result to content if transformer provided
+        let content;
+        if (tool.transformToContent) {
+            // transformToContent may return content parts in beta format
+            // Convert to v1 format (TextContent | ResourceContent)
+            const transformed = await tool.transformToContent(result);
+            content = transformed.map((part) => {
+                if (part.type === "text" && "text" in part && part.text) {
+                    return { type: "text", text: part.text };
+                }
+                // For other types, stringify as text
+                return {
+                    type: "text",
+                    text: JSON.stringify(part),
+                };
+            });
+        }
+        else {
+            // Default: stringify result as text
+            content = [
+                {
+                    type: "text",
+                    text: typeof result === "string" ? result : JSON.stringify(result),
+                },
+            ];
+        }
+        return {
+            type: "tool_result",
+            toolUseId: toolCallId,
+            content,
+        };
+    }
+    catch (error) {
+        return {
+            type: "tool_result",
+            toolUseId: toolCallId,
+            content: [
+                {
+                    type: "text",
+                    text: error instanceof Error ? error.message : "Tool execution failed",
+                },
+            ],
+        };
+    }
+}
+/**
+ * Execute all pending tool calls and return their results.
+ * Tools are executed sequentially to avoid race conditions when
+ * tools may have side effects that depend on each other.
+ * @param toolCalls - Map of tool call IDs to their call details
+ * @param registry - Registry of tool names to their definitions (Map or Record)
+ * @returns Array of ToolResultContent for all executed tools
+ */
+async function executeAllPendingTools(toolCalls, registry) {
+    const results = [];
+    // Normalize registry to allow lookup regardless of Map or Record
+    const getTool = (name) => {
+        if (registry instanceof Map) {
+            return registry.get(name);
+        }
+        return registry[name];
+    };
+    for (const [toolCallId, { name, input }] of toolCalls) {
+        const tool = getTool(name);
+        if (!tool) {
+            results.push({
+                type: "tool_result",
+                toolUseId: toolCallId,
+                content: [
+                    {
+                        type: "text",
+                        text: `Tool "${name}" not found in registry`,
+                    },
+                ],
+            });
+            continue;
+        }
+        const result = await executeClientTool(tool, toolCallId, input);
+        results.push(result);
+    }
+    return results;
+}
+//# sourceMappingURL=tool-executor.js.map

package/dist/v1/utils/tool-executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-executor.js","sourceRoot":"","sources":["../../../src/v1/utils/tool-executor.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Tool Executor for v1 API\n *\n * Handles automatic execution of client-side tools when the model\n * requests them via `tambo.run.awaiting_input` events.\n */\n\nimport type { TamboTool } from \"../../model/component-metadata\";\nimport type {\n  ToolResultContent,\n  TextContent,\n  ResourceContent,\n} from \"@tambo-ai/typescript-sdk/resources/threads/threads\";\n\n/**\n * Pending tool call from the stream accumulator\n */\nexport interface PendingToolCall {\n  name: string;\n  input: Record<string, unknown>;\n}\n\n/**\n * Execute a single client-side tool and return the result.\n * @param tool - The tool definition from the registry\n * @param toolCallId - The ID of the tool call to respond to\n * @param args - The parsed arguments for the tool\n * @returns ToolResultContent with the execution result or error\n */\nexport async function executeClientTool(\n  tool: TamboTool,\n  toolCallId: string,\n  args: Record<string, unknown>,\n): Promise<ToolResultContent> {\n  try {\n    const result = await tool.tool(args);\n\n    // Transform result to content if transformer provided\n    let content: (TextContent | ResourceContent)[];\n    if (tool.transformToContent) {\n      // transformToContent may return content parts in beta format\n      // Convert to v1 format (TextContent | ResourceContent)\n      const transformed = await tool.transformToContent(result);\n      content = transformed.map((part) => {\n        if (part.type === \"text\" && \"text\" in part && part.text) {\n          return { type: \"text\" as const, text: part.text };\n        }\n        // For other types, stringify as text\n        return {\n          type: \"text\" as const,\n          text: JSON.stringify(part),\n        };\n      });\n    } else {\n      // Default: stringify result as text\n      content = [\n        {\n          type: \"text\" as const,\n          text: typeof result === \"string\" ? result : JSON.stringify(result),\n        },\n      ];\n    }\n\n    return {\n      type: \"tool_result\",\n      toolUseId: toolCallId,\n      content,\n    };\n  } catch (error) {\n    return {\n      type: \"tool_result\",\n      toolUseId: toolCallId,\n      content: [\n        {\n          type: \"text\" as const,\n          text:\n            error instanceof Error ? error.message : \"Tool execution failed\",\n        },\n      ],\n    };\n  }\n}\n\n/**\n * Execute all pending tool calls and return their results.\n * Tools are executed sequentially to avoid race conditions when\n * tools may have side effects that depend on each other.\n * @param toolCalls - Map of tool call IDs to their call details\n * @param registry - Registry of tool names to their definitions (Map or Record)\n * @returns Array of ToolResultContent for all executed tools\n */\nexport async function executeAllPendingTools(\n  toolCalls: Map<string, PendingToolCall>,\n  registry: Map<string, TamboTool> | Record<string, TamboTool>,\n): Promise<ToolResultContent[]> {\n  const results: ToolResultContent[] = [];\n\n  // Normalize registry to allow lookup regardless of Map or Record\n  const getTool = (name: string): TamboTool | undefined => {\n    if (registry instanceof Map) {\n      return registry.get(name);\n    }\n    return registry[name];\n  };\n\n  for (const [toolCallId, { name, input }] of toolCalls) {\n    const tool = getTool(name);\n    if (!tool) {\n      results.push({\n        type: \"tool_result\",\n        toolUseId: toolCallId,\n        content: [\n          {\n            type: \"text\" as const,\n            text: `Tool \"${name}\" not found in registry`,\n          },\n        ],\n      });\n      continue;\n    }\n\n    const result = await executeClientTool(tool, toolCallId, input);\n    results.push(result);\n  }\n\n  return results;\n}\n"]}

package/dist/v1/utils/tool-executor.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tool-executor.test.d.ts.map

package/dist/v1/utils/tool-executor.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-executor.test.d.ts","sourceRoot":"","sources":["../../../src/v1/utils/tool-executor.test.ts"],"names":[],"mappings":""}

package/dist/v1/utils/tool-executor.test.js

@@ -0,0 +1,222 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const zod_1 = require("zod");
+const tool_executor_1 = require("./tool-executor");
+describe("tool-executor", () => {
+    describe("executeClientTool", () => {
+        it("executes a tool and returns text result", async () => {
+            const tool = {
+                name: "get_weather",
+                description: "Gets weather",
+                tool: async ({ city }) => `Weather in ${city} is sunny`,
+                inputSchema: zod_1.z.object({ city: zod_1.z.string() }),
+                outputSchema: zod_1.z.string(),
+            };
+            const result = await (0, tool_executor_1.executeClientTool)(tool, "call-1", {
+                city: "Seattle",
+            });
+            expect(result).toEqual({
+                type: "tool_result",
+                toolUseId: "call-1",
+                content: [{ type: "text", text: "Weather in Seattle is sunny" }],
+            });
+        });
+        it("stringifies non-string results", async () => {
+            const tool = {
+                name: "get_data",
+                description: "Gets data",
+                tool: async () => ({ value: 42 }),
+                inputSchema: zod_1.z.object({}),
+                outputSchema: zod_1.z.object({ value: zod_1.z.number() }),
+            };
+            const result = await (0, tool_executor_1.executeClientTool)(tool, "call-2", {});
+            expect(result).toEqual({
+                type: "tool_result",
+                toolUseId: "call-2",
+                content: [{ type: "text", text: '{"value":42}' }],
+            });
+        });
+        it("uses transformToContent when provided", async () => {
+            const tool = {
+                name: "custom_tool",
+                description: "Custom tool",
+                tool: async () => "custom result",
+                inputSchema: zod_1.z.object({}),
+                outputSchema: zod_1.z.string(),
+                transformToContent: (result) => [
+                    { type: "text", text: `Transformed: ${result}` },
+                ],
+            };
+            const result = await (0, tool_executor_1.executeClientTool)(tool, "call-3", {});
+            expect(result).toEqual({
+                type: "tool_result",
+                toolUseId: "call-3",
+                content: [{ type: "text", text: "Transformed: custom result" }],
+            });
+        });
+        it("handles transformToContent with non-text types by stringifying", async () => {
+            const tool = {
+                name: "image_tool",
+                description: "Image tool",
+                tool: async () => "image data",
+                inputSchema: zod_1.z.object({}),
+                outputSchema: zod_1.z.string(),
+                transformToContent: () => [
+                    {
+                        type: "image_url",
+                        image_url: { url: "https://example.com/image.png" },
+                    },
+                ],
+            };
+            const result = await (0, tool_executor_1.executeClientTool)(tool, "call-4", {});
+            expect(result).toEqual({
+                type: "tool_result",
+                toolUseId: "call-4",
+                content: [
+                    {
+                        type: "text",
+                        text: '{"type":"image_url","image_url":{"url":"https://example.com/image.png"}}',
+                    },
+                ],
+            });
+        });
+        it("handles tool execution errors gracefully", async () => {
+            const tool = {
+                name: "failing_tool",
+                description: "A tool that fails",
+                tool: async () => {
+                    throw new Error("Tool failed!");
+                },
+                inputSchema: zod_1.z.object({}),
+                outputSchema: zod_1.z.void(),
+            };
+            const result = await (0, tool_executor_1.executeClientTool)(tool, "call-5", {});
+            expect(result).toEqual({
+                type: "tool_result",
+                toolUseId: "call-5",
+                content: [{ type: "text", text: "Tool failed!" }],
+            });
+        });
+        it("handles non-Error throws gracefully", async () => {
+            const tool = {
+                name: "throwing_tool",
+                description: "A tool that throws a string",
+                tool: async () => {
+                    throw "string error";
+                },
+                inputSchema: zod_1.z.object({}),
+                outputSchema: zod_1.z.void(),
+            };
+            const result = await (0, tool_executor_1.executeClientTool)(tool, "call-6", {});
+            expect(result).toEqual({
+                type: "tool_result",
+                toolUseId: "call-6",
+                content: [{ type: "text", text: "Tool execution failed" }],
+            });
+        });
+    });
+    describe("executeAllPendingTools", () => {
+        it("executes multiple tools with Map registry", async () => {
+            const registry = new Map([
+                [
+                    "add",
+                    {
+                        name: "add",
+                        description: "Adds numbers",
+                        tool: async ({ a, b }) => a + b,
+                        inputSchema: zod_1.z.object({ a: zod_1.z.number(), b: zod_1.z.number() }),
+                        outputSchema: zod_1.z.number(),
+                    },
+                ],
+                [
+                    "multiply",
+                    {
+                        name: "multiply",
+                        description: "Multiplies numbers",
+                        tool: async ({ a, b }) => a * b,
+                        inputSchema: zod_1.z.object({ a: zod_1.z.number(), b: zod_1.z.number() }),
+                        outputSchema: zod_1.z.number(),
+                    },
+                ],
+            ]);
+            const toolCalls = new Map([
+                ["call-1", { name: "add", input: { a: 2, b: 3 } }],
+                ["call-2", { name: "multiply", input: { a: 4, b: 5 } }],
+            ]);
+            const results = await (0, tool_executor_1.executeAllPendingTools)(toolCalls, registry);
+            expect(results).toHaveLength(2);
+            expect(results[0]).toEqual({
+                type: "tool_result",
+                toolUseId: "call-1",
+                content: [{ type: "text", text: "5" }],
+            });
+            expect(results[1]).toEqual({
+                type: "tool_result",
+                toolUseId: "call-2",
+                content: [{ type: "text", text: "20" }],
+            });
+        });
+        it("executes tools with Record registry", async () => {
+            const registry = {
+                greet: {
+                    name: "greet",
+                    description: "Greets user",
+                    tool: async ({ name }) => `Hello, ${name}!`,
+                    inputSchema: zod_1.z.object({ name: zod_1.z.string() }),
+                    outputSchema: zod_1.z.string(),
+                },
+            };
+            const toolCalls = new Map([
+                ["call-1", { name: "greet", input: { name: "World" } }],
+            ]);
+            const results = await (0, tool_executor_1.executeAllPendingTools)(toolCalls, registry);
+            expect(results).toHaveLength(1);
+            expect(results[0]).toEqual({
+                type: "tool_result",
+                toolUseId: "call-1",
+                content: [{ type: "text", text: "Hello, World!" }],
+            });
+        });
+        it("returns error result for unknown tools", async () => {
+            const registry = new Map();
+            const toolCalls = new Map([
+                ["call-1", { name: "unknown_tool", input: {} }],
+            ]);
+            const results = await (0, tool_executor_1.executeAllPendingTools)(toolCalls, registry);
+            expect(results).toHaveLength(1);
+            expect(results[0]).toEqual({
+                type: "tool_result",
+                toolUseId: "call-1",
+                content: [
+                    { type: "text", text: 'Tool "unknown_tool" not found in registry' },
+                ],
+            });
+        });
+        it("handles mixed known and unknown tools", async () => {
+            const registry = new Map([
+                [
+                    "known",
+                    {
+                        name: "known",
+                        description: "Known tool",
+                        tool: async () => "success",
+                        inputSchema: zod_1.z.object({}),
+                        outputSchema: zod_1.z.string(),
+                    },
+                ],
+            ]);
+            const toolCalls = new Map([
+                ["call-1", { name: "known", input: {} }],
+                ["call-2", { name: "unknown", input: {} }],
+            ]);
+            const results = await (0, tool_executor_1.executeAllPendingTools)(toolCalls, registry);
+            expect(results).toHaveLength(2);
+            expect(results[0].content[0]).toEqual({ type: "text", text: "success" });
+            expect(results[1].content[0]).toEqual({
+                type: "text",
+                text: 'Tool "unknown" not found in registry',
+            });
+        });
+    });
+});
+//# sourceMappingURL=tool-executor.test.js.map

package/dist/v1/utils/tool-executor.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-executor.test.js","sourceRoot":"","sources":["../../../src/v1/utils/tool-executor.test.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from \"zod\";\nimport type { TamboTool } from \"../../model/component-metadata\";\nimport {\n  executeClientTool,\n  executeAllPendingTools,\n  type PendingToolCall,\n} from \"./tool-executor\";\n\ndescribe(\"tool-executor\", () => {\n  describe(\"executeClientTool\", () => {\n    it(\"executes a tool and returns text result\", async () => {\n      const tool: TamboTool = {\n        name: \"get_weather\",\n        description: \"Gets weather\",\n        tool: async ({ city }: { city: string }) =>\n          `Weather in ${city} is sunny`,\n        inputSchema: z.object({ city: z.string() }),\n        outputSchema: z.string(),\n      };\n\n      const result = await executeClientTool(tool, \"call-1\", {\n        city: \"Seattle\",\n      });\n\n      expect(result).toEqual({\n        type: \"tool_result\",\n        toolUseId: \"call-1\",\n        content: [{ type: \"text\", text: \"Weather in Seattle is sunny\" }],\n      });\n    });\n\n    it(\"stringifies non-string results\", async () => {\n      const tool: TamboTool = {\n        name: \"get_data\",\n        description: \"Gets data\",\n        tool: async () => ({ value: 42 }),\n        inputSchema: z.object({}),\n        outputSchema: z.object({ value: z.number() }),\n      };\n\n      const result = await executeClientTool(tool, \"call-2\", {});\n\n      expect(result).toEqual({\n        type: \"tool_result\",\n        toolUseId: \"call-2\",\n        content: [{ type: \"text\", text: '{\"value\":42}' }],\n      });\n    });\n\n    it(\"uses transformToContent when provided\", async () => {\n      const tool: TamboTool = {\n        name: \"custom_tool\",\n        description: \"Custom tool\",\n        tool: async () => \"custom result\",\n        inputSchema: z.object({}),\n        outputSchema: z.string(),\n        transformToContent: (result) => [\n          { type: \"text\", text: `Transformed: ${result}` },\n        ],\n      };\n\n      const result = await executeClientTool(tool, \"call-3\", {});\n\n      expect(result).toEqual({\n        type: \"tool_result\",\n        toolUseId: \"call-3\",\n        content: [{ type: \"text\", text: \"Transformed: custom result\" }],\n      });\n    });\n\n    it(\"handles transformToContent with non-text types by stringifying\", async () => {\n      const tool: TamboTool = {\n        name: \"image_tool\",\n        description: \"Image tool\",\n        tool: async () => \"image data\",\n        inputSchema: z.object({}),\n        outputSchema: z.string(),\n        transformToContent: () => [\n          {\n            type: \"image_url\",\n            image_url: { url: \"https://example.com/image.png\" },\n          },\n        ],\n      };\n\n      const result = await executeClientTool(tool, \"call-4\", {});\n\n      expect(result).toEqual({\n        type: \"tool_result\",\n        toolUseId: \"call-4\",\n        content: [\n          {\n            type: \"text\",\n            text: '{\"type\":\"image_url\",\"image_url\":{\"url\":\"https://example.com/image.png\"}}',\n          },\n        ],\n      });\n    });\n\n    it(\"handles tool execution errors gracefully\", async () => {\n      const tool: TamboTool = {\n        name: \"failing_tool\",\n        description: \"A tool that fails\",\n        tool: async () => {\n          throw new Error(\"Tool failed!\");\n        },\n        inputSchema: z.object({}),\n        outputSchema: z.void(),\n      };\n\n      const result = await executeClientTool(tool, \"call-5\", {});\n\n      expect(result).toEqual({\n        type: \"tool_result\",\n        toolUseId: \"call-5\",\n        content: [{ type: \"text\", text: \"Tool failed!\" }],\n      });\n    });\n\n    it(\"handles non-Error throws gracefully\", async () => {\n      const tool: TamboTool = {\n        name: \"throwing_tool\",\n        description: \"A tool that throws a string\",\n        tool: async () => {\n          throw \"string error\";\n        },\n        inputSchema: z.object({}),\n        outputSchema: z.void(),\n      };\n\n      const result = await executeClientTool(tool, \"call-6\", {});\n\n      expect(result).toEqual({\n        type: \"tool_result\",\n        toolUseId: \"call-6\",\n        content: [{ type: \"text\", text: \"Tool execution failed\" }],\n      });\n    });\n  });\n\n  describe(\"executeAllPendingTools\", () => {\n    it(\"executes multiple tools with Map registry\", async () => {\n      const registry = new Map<string, TamboTool>([\n        [\n          \"add\",\n          {\n            name: \"add\",\n            description: \"Adds numbers\",\n            tool: async ({ a, b }: { a: number; b: number }) => a + b,\n            inputSchema: z.object({ a: z.number(), b: z.number() }),\n            outputSchema: z.number(),\n          },\n        ],\n        [\n          \"multiply\",\n          {\n            name: \"multiply\",\n            description: \"Multiplies numbers\",\n            tool: async ({ a, b }: { a: number; b: number }) => a * b,\n            inputSchema: z.object({ a: z.number(), b: z.number() }),\n            outputSchema: z.number(),\n          },\n        ],\n      ]);\n\n      const toolCalls = new Map<string, PendingToolCall>([\n        [\"call-1\", { name: \"add\", input: { a: 2, b: 3 } }],\n        [\"call-2\", { name: \"multiply\", input: { a: 4, b: 5 } }],\n      ]);\n\n      const results = await executeAllPendingTools(toolCalls, registry);\n\n      expect(results).toHaveLength(2);\n      expect(results[0]).toEqual({\n        type: \"tool_result\",\n        toolUseId: \"call-1\",\n        content: [{ type: \"text\", text: \"5\" }],\n      });\n      expect(results[1]).toEqual({\n        type: \"tool_result\",\n        toolUseId: \"call-2\",\n        content: [{ type: \"text\", text: \"20\" }],\n      });\n    });\n\n    it(\"executes tools with Record registry\", async () => {\n      const registry: Record<string, TamboTool> = {\n        greet: {\n          name: \"greet\",\n          description: \"Greets user\",\n          tool: async ({ name }: { name: string }) => `Hello, ${name}!`,\n          inputSchema: z.object({ name: z.string() }),\n          outputSchema: z.string(),\n        },\n      };\n\n      const toolCalls = new Map<string, PendingToolCall>([\n        [\"call-1\", { name: \"greet\", input: { name: \"World\" } }],\n      ]);\n\n      const results = await executeAllPendingTools(toolCalls, registry);\n\n      expect(results).toHaveLength(1);\n      expect(results[0]).toEqual({\n        type: \"tool_result\",\n        toolUseId: \"call-1\",\n        content: [{ type: \"text\", text: \"Hello, World!\" }],\n      });\n    });\n\n    it(\"returns error result for unknown tools\", async () => {\n      const registry = new Map<string, TamboTool>();\n\n      const toolCalls = new Map<string, PendingToolCall>([\n        [\"call-1\", { name: \"unknown_tool\", input: {} }],\n      ]);\n\n      const results = await executeAllPendingTools(toolCalls, registry);\n\n      expect(results).toHaveLength(1);\n      expect(results[0]).toEqual({\n        type: \"tool_result\",\n        toolUseId: \"call-1\",\n        content: [\n          { type: \"text\", text: 'Tool \"unknown_tool\" not found in registry' },\n        ],\n      });\n    });\n\n    it(\"handles mixed known and unknown tools\", async () => {\n      const registry = new Map<string, TamboTool>([\n        [\n          \"known\",\n          {\n            name: \"known\",\n            description: \"Known tool\",\n            tool: async () => \"success\",\n            inputSchema: z.object({}),\n            outputSchema: z.string(),\n          },\n        ],\n      ]);\n\n      const toolCalls = new Map<string, PendingToolCall>([\n        [\"call-1\", { name: \"known\", input: {} }],\n        [\"call-2\", { name: \"unknown\", input: {} }],\n      ]);\n\n      const results = await executeAllPendingTools(toolCalls, registry);\n\n      expect(results).toHaveLength(2);\n      expect(results[0].content[0]).toEqual({ type: \"text\", text: \"success\" });\n      expect(results[1].content[0]).toEqual({\n        type: \"text\",\n        text: 'Tool \"unknown\" not found in registry',\n      });\n    });\n  });\n});\n"]}

package/esm/v1/hooks/use-tambo-v1-component-state.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Return type for useTamboV1ComponentState hook.
+ * Similar to useState but with additional metadata.
+ */
+export type UseTamboV1ComponentStateReturn<S> = [
+    currentState: S,
+    setState: (newState: S | ((prev: S) => S)) => void,
+    meta: {
+        isPending: boolean;
+        error: Error | null;
+        flush: () => void;
+    }
+];
+/**
+ * Hook for managing component state with bidirectional server sync.
+ *
+ * This hook acts like useState but automatically syncs state changes
+ * to the Tambo backend. Server-side state updates are also reflected
+ * in the component.
+ *
+ * Must be used within a component rendered via the component renderer.
+ * @param keyName - The unique key to identify this state value within the component's state
+ * @param initialValue - Initial value for the state (used if no server state exists)
+ * @param debounceTime - Debounce time in milliseconds (default: 500ms)
+ * @returns Tuple of [currentState, setState, meta]
+ * @example
+ * ```tsx
+ * function Counter() {
+ *   const [count, setCount, { isPending }] = useTamboV1ComponentState('count', 0);
+ *
+ *   return (
+ *     <div>
+ *       <span>{count}</span>
+ *       <button onClick={() => setCount(c => c + 1)} disabled={isPending}>
+ *         Increment
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useTamboV1ComponentState<S = undefined>(keyName: string, initialValue?: S, debounceTime?: number): UseTamboV1ComponentStateReturn<S | undefined>;
+export declare function useTamboV1ComponentState<S>(keyName: string, initialValue: S, debounceTime?: number): UseTamboV1ComponentStateReturn<S>;
+//# sourceMappingURL=use-tambo-v1-component-state.d.ts.map

package/esm/v1/hooks/use-tambo-v1-component-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-tambo-v1-component-state.d.ts","sourceRoot":"","sources":["../../../src/v1/hooks/use-tambo-v1-component-state.ts"],"names":[],"mappings":"AAoBA;;;GAGG;AACH,MAAM,MAAM,8BAA8B,CAAC,CAAC,IAAI;IAC9C,YAAY,EAAE,CAAC;IACf,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,IAAI;IAClD,IAAI,EAAE;QACJ,SAAS,EAAE,OAAO,CAAC;QACnB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;QACpB,KAAK,EAAE,MAAM,IAAI,CAAC;KACnB;CACF,CAAC;AAgCF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,GAAG,SAAS,EACpD,OAAO,EAAE,MAAM,EACf,YAAY,CAAC,EAAE,CAAC,EAChB,YAAY,CAAC,EAAE,MAAM,GACpB,8BAA8B,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;AACjD,wBAAgB,wBAAwB,CAAC,CAAC,EACxC,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,CAAC,EACf,YAAY,CAAC,EAAE,MAAM,GACpB,8BAA8B,CAAC,CAAC,CAAC,CAAC"}

package/esm/v1/hooks/use-tambo-v1-component-state.js

@@ -0,0 +1,131 @@
+"use client";
+/**
+ * useTamboV1ComponentState - Component State Hook for v1 API
+ *
+ * Provides bidirectional state synchronization between React components
+ * and the Tambo backend. State changes are debounced before syncing to
+ * the server, and server state updates are reflected in the component.
+ *
+ * Must be used within a component rendered via the component renderer.
+ */
+import { useCallback, useEffect, useState, useRef } from "react";
+import { useDebouncedCallback } from "use-debounce";
+import { deepEqual } from "fast-equals";
+import { useTamboClient } from "../../providers/tambo-client-provider";
+import { useV1ComponentContent } from "../utils/component-renderer";
+import { useStreamState } from "../providers/tambo-v1-stream-context";
+/**
+ * Find a component content block by ID in a specific thread.
+ * Only searches the specified thread to prevent cross-thread data access
+ * and improve performance (O(m*k) instead of O(n*m*k)).
+ * @param streamState - The current stream state
+ * @param threadId - The thread ID to search in
+ * @param componentId - The component ID to find
+ * @returns The component content block, or undefined if not found
+ */
+function findComponentContent(streamState, threadId, componentId) {
+    // Only search the specified thread (not all threads)
+    const threadState = streamState.threadMap[threadId];
+    if (!threadState) {
+        return undefined;
+    }
+    for (const message of threadState.thread.messages) {
+        for (const content of message.content) {
+            if (content.type === "component" && content.id === componentId) {
+                return content;
+            }
+        }
+    }
+    return undefined;
+}
+export function useTamboV1ComponentState(keyName, initialValue, debounceTime = 500) {
+    const client = useTamboClient();
+    const { componentId, threadId } = useV1ComponentContent();
+    const streamState = useStreamState();
+    // Find the component content to get server state (only search current thread)
+    const componentContent = findComponentContent(streamState, threadId, componentId);
+    const serverState = componentContent?.state;
+    const serverValue = serverState?.[keyName];
+    // Local state - initialized from server state or initial value
+    const [localState, setLocalState] = useState(() => serverValue ?? initialValue);
+    // Track pending state and errors
+    const [isPending, setIsPending] = useState(false);
+    const [error, setError] = useState(null);
+    // Track the last value we sent to avoid overwriting with stale server state
+    const lastSentValueRef = useRef(undefined);
+    // Track whether there's a pending local change that hasn't synced yet
+    const hasPendingLocalChangeRef = useRef(false);
+    // Track in-flight sync requests to avoid stale completions clearing pending state
+    const syncSeqRef = useRef(0);
+    // Debounced function to sync state to server
+    const syncToServer = useDebouncedCallback(async (newState) => {
+        const seq = ++syncSeqRef.current;
+        setIsPending(true);
+        setError(null);
+        lastSentValueRef.current = newState;
+        try {
+            await client.threads.state.updateState(componentId, {
+                threadId,
+                state: { [keyName]: newState },
+            });
+            // Clear pending flag after successful sync
+            hasPendingLocalChangeRef.current = false;
+        }
+        catch (err) {
+            // Clear pending flag on error to allow server reconciliation
+            hasPendingLocalChangeRef.current = false;
+            const syncError = err instanceof Error ? err : new Error(String(err));
+            setError(syncError);
+            console.error(`[useTamboV1ComponentState] Failed to sync state for ${componentId}:`, syncError);
+        }
+        finally {
+            // Only clear isPending if this is the most recent request
+            if (seq === syncSeqRef.current) {
+                setIsPending(false);
+            }
+        }
+    }, debounceTime);
+    // setState function that updates local state and triggers debounced sync
+    const setState = useCallback((newState) => {
+        setLocalState((prev) => {
+            const nextState = typeof newState === "function"
+                ? newState(prev)
+                : newState;
+            // Mark that we have a pending local change
+            hasPendingLocalChangeRef.current = true;
+            // Trigger debounced sync to server
+            void syncToServer(nextState);
+            return nextState;
+        });
+    }, [syncToServer]);
+    // Sync from server state when it changes (e.g., from streaming events)
+    useEffect(() => {
+        if (serverValue === undefined) {
+            return;
+        }
+        // Don't overwrite local changes that haven't synced yet
+        if (hasPendingLocalChangeRef.current) {
+            return;
+        }
+        // Only sync if the server value is different from what we last sent
+        // This prevents overwriting local state with stale server values
+        if (lastSentValueRef.current !== undefined &&
+            deepEqual(serverValue, lastSentValueRef.current)) {
+            return;
+        }
+        // Use functional update to avoid localState in deps
+        setLocalState((prev) => deepEqual(serverValue, prev) ? prev : serverValue);
+    }, [serverValue]);
+    // Flush pending updates on unmount
+    useEffect(() => {
+        return () => {
+            void syncToServer.flush();
+        };
+    }, [syncToServer]);
+    // Flush function for immediate sync
+    const flush = useCallback(() => {
+        void syncToServer.flush();
+    }, [syncToServer]);
+    return [localState, setState, { isPending, error, flush }];
+}
+//# sourceMappingURL=use-tambo-v1-component-state.js.map

package/esm/v1/hooks/use-tambo-v1-component-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-tambo-v1-component-state.js","sourceRoot":"","sources":["../../../src/v1/hooks/use-tambo-v1-component-state.ts"],"names":[],"mappings":"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","sourcesContent":["\"use client\";\n\n/**\n * useTamboV1ComponentState - Component State Hook for v1 API\n *\n * Provides bidirectional state synchronization between React components\n * and the Tambo backend. State changes are debounced before syncing to\n * the server, and server state updates are reflected in the component.\n *\n * Must be used within a component rendered via the component renderer.\n */\n\nimport { useCallback, useEffect, useState, useRef } from \"react\";\nimport { useDebouncedCallback } from \"use-debounce\";\nimport { deepEqual } from \"fast-equals\";\nimport { useTamboClient } from \"../../providers/tambo-client-provider\";\nimport { useV1ComponentContent } from \"../utils/component-renderer\";\nimport { useStreamState } from \"../providers/tambo-v1-stream-context\";\nimport type { V1ComponentContent } from \"../types/message\";\n\n/**\n * Return type for useTamboV1ComponentState hook.\n * Similar to useState but with additional metadata.\n */\nexport type UseTamboV1ComponentStateReturn<S> = [\n  currentState: S,\n  setState: (newState: S | ((prev: S) => S)) => void,\n  meta: {\n    isPending: boolean;\n    error: Error | null;\n    flush: () => void;\n  },\n];\n\n/**\n * Find a component content block by ID in a specific thread.\n * Only searches the specified thread to prevent cross-thread data access\n * and improve performance (O(m*k) instead of O(n*m*k)).\n * @param streamState - The current stream state\n * @param threadId - The thread ID to search in\n * @param componentId - The component ID to find\n * @returns The component content block, or undefined if not found\n */\nfunction findComponentContent(\n  streamState: ReturnType<typeof useStreamState>,\n  threadId: string,\n  componentId: string,\n): V1ComponentContent | undefined {\n  // Only search the specified thread (not all threads)\n  const threadState = streamState.threadMap[threadId];\n  if (!threadState) {\n    return undefined;\n  }\n\n  for (const message of threadState.thread.messages) {\n    for (const content of message.content) {\n      if (content.type === \"component\" && content.id === componentId) {\n        return content;\n      }\n    }\n  }\n  return undefined;\n}\n\n/**\n * Hook for managing component state with bidirectional server sync.\n *\n * This hook acts like useState but automatically syncs state changes\n * to the Tambo backend. Server-side state updates are also reflected\n * in the component.\n *\n * Must be used within a component rendered via the component renderer.\n * @param keyName - The unique key to identify this state value within the component's state\n * @param initialValue - Initial value for the state (used if no server state exists)\n * @param debounceTime - Debounce time in milliseconds (default: 500ms)\n * @returns Tuple of [currentState, setState, meta]\n * @example\n * ```tsx\n * function Counter() {\n *   const [count, setCount, { isPending }] = useTamboV1ComponentState('count', 0);\n *\n *   return (\n *     <div>\n *       <span>{count}</span>\n *       <button onClick={() => setCount(c => c + 1)} disabled={isPending}>\n *         Increment\n *       </button>\n *     </div>\n *   );\n * }\n * ```\n */\nexport function useTamboV1ComponentState<S = undefined>(\n  keyName: string,\n  initialValue?: S,\n  debounceTime?: number,\n): UseTamboV1ComponentStateReturn<S | undefined>;\nexport function useTamboV1ComponentState<S>(\n  keyName: string,\n  initialValue: S,\n  debounceTime?: number,\n): UseTamboV1ComponentStateReturn<S>;\nexport function useTamboV1ComponentState<S>(\n  keyName: string,\n  initialValue?: S,\n  debounceTime = 500,\n): UseTamboV1ComponentStateReturn<S> {\n  const client = useTamboClient();\n  const { componentId, threadId } = useV1ComponentContent();\n  const streamState = useStreamState();\n\n  // Find the component content to get server state (only search current thread)\n  const componentContent = findComponentContent(\n    streamState,\n    threadId,\n    componentId,\n  );\n  const serverState = componentContent?.state as\n    | Record<string, unknown>\n    | undefined;\n  const serverValue = serverState?.[keyName] as S | undefined;\n\n  // Local state - initialized from server state or initial value\n  const [localState, setLocalState] = useState<S>(\n    () => serverValue ?? (initialValue as S),\n  );\n\n  // Track pending state and errors\n  const [isPending, setIsPending] = useState(false);\n  const [error, setError] = useState<Error | null>(null);\n\n  // Track the last value we sent to avoid overwriting with stale server state\n  const lastSentValueRef = useRef<S | undefined>(undefined);\n\n  // Track whether there's a pending local change that hasn't synced yet\n  const hasPendingLocalChangeRef = useRef(false);\n\n  // Track in-flight sync requests to avoid stale completions clearing pending state\n  const syncSeqRef = useRef(0);\n\n  // Debounced function to sync state to server\n  const syncToServer = useDebouncedCallback(async (newState: S) => {\n    const seq = ++syncSeqRef.current;\n    setIsPending(true);\n    setError(null);\n    lastSentValueRef.current = newState;\n\n    try {\n      await client.threads.state.updateState(componentId, {\n        threadId,\n        state: { [keyName]: newState },\n      });\n      // Clear pending flag after successful sync\n      hasPendingLocalChangeRef.current = false;\n    } catch (err) {\n      // Clear pending flag on error to allow server reconciliation\n      hasPendingLocalChangeRef.current = false;\n      const syncError = err instanceof Error ? err : new Error(String(err));\n      setError(syncError);\n      console.error(\n        `[useTamboV1ComponentState] Failed to sync state for ${componentId}:`,\n        syncError,\n      );\n    } finally {\n      // Only clear isPending if this is the most recent request\n      if (seq === syncSeqRef.current) {\n        setIsPending(false);\n      }\n    }\n  }, debounceTime);\n\n  // setState function that updates local state and triggers debounced sync\n  const setState = useCallback(\n    (newState: S | ((prev: S) => S)) => {\n      setLocalState((prev) => {\n        const nextState =\n          typeof newState === \"function\"\n            ? (newState as (prev: S) => S)(prev)\n            : newState;\n\n        // Mark that we have a pending local change\n        hasPendingLocalChangeRef.current = true;\n\n        // Trigger debounced sync to server\n        void syncToServer(nextState);\n\n        return nextState;\n      });\n    },\n    [syncToServer],\n  );\n\n  // Sync from server state when it changes (e.g., from streaming events)\n  useEffect(() => {\n    if (serverValue === undefined) {\n      return;\n    }\n\n    // Don't overwrite local changes that haven't synced yet\n    if (hasPendingLocalChangeRef.current) {\n      return;\n    }\n\n    // Only sync if the server value is different from what we last sent\n    // This prevents overwriting local state with stale server values\n    if (\n      lastSentValueRef.current !== undefined &&\n      deepEqual(serverValue, lastSentValueRef.current)\n    ) {\n      return;\n    }\n\n    // Use functional update to avoid localState in deps\n    setLocalState((prev) =>\n      deepEqual(serverValue, prev) ? prev : serverValue,\n    );\n  }, [serverValue]);\n\n  // Flush pending updates on unmount\n  useEffect(() => {\n    return () => {\n      void syncToServer.flush();\n    };\n  }, [syncToServer]);\n\n  // Flush function for immediate sync\n  const flush = useCallback(() => {\n    void syncToServer.flush();\n  }, [syncToServer]);\n\n  return [localState, setState, { isPending, error, flush }];\n}\n"]}

package/esm/v1/hooks/use-tambo-v1-component-state.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=use-tambo-v1-component-state.test.d.ts.map

package/esm/v1/hooks/use-tambo-v1-component-state.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-tambo-v1-component-state.test.d.ts","sourceRoot":"","sources":["../../../src/v1/hooks/use-tambo-v1-component-state.test.tsx"],"names":[],"mappings":""}