@tambo-ai/react 0.68.0 → 0.69.0

package/esm/providers/tambo-client-provider.test.js

@@ -0,0 +1,203 @@
+import { renderHook } from "@testing-library/react";
+import React from "react";
+import { TamboClientProvider, useIsTamboTokenUpdating, useTamboClient, useTamboQueryClient, } from "./tambo-client-provider";
+// Mock the session token hook to control token fetching state
+jest.mock("./hooks/use-tambo-session-token", () => ({
+    useTamboSessionToken: jest.fn(),
+}));
+import { useTamboSessionToken } from "./hooks/use-tambo-session-token";
+// Add fetch polyfill for jsdom environment (TamboAI SDK requires it)
+const mockFetch = jest.fn();
+let previousFetch;
+beforeEach(() => {
+    mockFetch.mockReset();
+    previousFetch = global.fetch;
+    global.fetch = mockFetch;
+});
+afterEach(() => {
+    global.fetch = previousFetch;
+});
+describe("TamboClientProvider", () => {
+    beforeEach(() => {
+        jest.clearAllMocks();
+        // Default mock: not fetching
+        jest.mocked(useTamboSessionToken).mockReturnValue({
+            isFetching: false,
+            data: undefined,
+            error: null,
+            isLoading: false,
+            isError: false,
+            isSuccess: false,
+            status: "pending",
+            fetchStatus: "idle",
+        });
+    });
+    const createWrapper = (props) => {
+        const Wrapper = ({ children }) => (React.createElement(TamboClientProvider, { ...props }, children));
+        Wrapper.displayName = "TestWrapper";
+        return Wrapper;
+    };
+    describe("Client Configuration", () => {
+        it("should create client accessible via useTamboClient hook", () => {
+            const { result } = renderHook(() => useTamboClient(), {
+                wrapper: createWrapper({ apiKey: "test-api-key" }),
+            });
+            // Client should be a TamboAI instance with expected shape
+            expect(result.current).toBeDefined();
+            expect(result.current.beta).toBeDefined();
+        });
+        it("should provide the same client instance on re-renders", () => {
+            const { result, rerender } = renderHook(() => useTamboClient(), {
+                wrapper: createWrapper({ apiKey: "test-api-key" }),
+            });
+            const firstClient = result.current;
+            rerender();
+            const secondClient = result.current;
+            expect(firstClient).toBe(secondClient);
+        });
+        it("should configure client with provided tamboUrl", () => {
+            const { result } = renderHook(() => useTamboClient(), {
+                wrapper: createWrapper({
+                    apiKey: "test-api-key",
+                    tamboUrl: "https://custom.tambo.api",
+                }),
+            });
+            expect(result.current.baseURL).toBe("https://custom.tambo.api");
+        });
+        it("should configure client with provided environment", async () => {
+            const { result } = renderHook(() => useTamboClient(), {
+                wrapper: createWrapper({
+                    apiKey: "test-api-key",
+                    environment: "staging",
+                }),
+            });
+            const { url } = await result.current.buildRequest({
+                method: "get",
+                path: "/test-endpoint",
+            });
+            expect(url).toBe("https://hydra-api-dev.up.railway.app/test-endpoint");
+        });
+        it("should throw if both tamboUrl and environment are provided", () => {
+            const consoleSpy = jest.spyOn(console, "error").mockImplementation();
+            expect(() => {
+                renderHook(() => useTamboClient(), {
+                    wrapper: createWrapper({
+                        apiKey: "test-api-key",
+                        tamboUrl: "https://custom.tambo.api",
+                        environment: "staging",
+                    }),
+                });
+            }).toThrow("Ambiguous URL; The `baseURL` option (or TAMBO_AI_BASE_URL env var) and the `environment` option are given. If you want to use the environment you must pass baseURL: null");
+            consoleSpy.mockRestore();
+        });
+        it("should include additional headers in client configuration", async () => {
+            const { result } = renderHook(() => useTamboClient(), {
+                wrapper: createWrapper({
+                    apiKey: "test-api-key",
+                    additionalHeaders: {
+                        "X-Custom-Header": "custom-value",
+                        "X-Another-Header": "another-value",
+                    },
+                }),
+            });
+            const { req } = await result.current.buildRequest({
+                method: "get",
+                path: "/test-endpoint",
+            });
+            expect(req.headers.get("X-Tambo-React-Version")).toBeDefined();
+            expect(req.headers.get("X-Tambo-React-Version")).toMatch(/\d+\.\d+\.\d+/); // version format
+            expect(req.headers.get("X-Custom-Header")).toBe("custom-value");
+            expect(req.headers.get("X-Another-Header")).toBe("another-value");
+        });
+    });
+    describe("Token State", () => {
+        it("should expose isUpdatingToken=true when session token is fetching", () => {
+            jest.mocked(useTamboSessionToken).mockReturnValue({
+                isFetching: true,
+            });
+            const { result } = renderHook(() => useIsTamboTokenUpdating(), {
+                wrapper: createWrapper({
+                    apiKey: "test-api-key",
+                    userToken: "oauth-token",
+                }),
+            });
+            expect(result.current).toBe(true);
+        });
+        it("should expose isUpdatingToken=false when not fetching", () => {
+            jest.mocked(useTamboSessionToken).mockReturnValue({
+                isFetching: false,
+            });
+            const { result } = renderHook(() => useIsTamboTokenUpdating(), {
+                wrapper: createWrapper({ apiKey: "test-api-key" }),
+            });
+            expect(result.current).toBe(false);
+        });
+        it("should call useTamboSessionToken with userToken when provided", () => {
+            renderHook(() => useTamboClient(), {
+                wrapper: createWrapper({
+                    apiKey: "test-api-key",
+                    userToken: "my-oauth-token",
+                }),
+            });
+            expect(useTamboSessionToken).toHaveBeenCalledWith(expect.anything(), // client
+            expect.anything(), // queryClient
+            "my-oauth-token");
+        });
+    });
+});
+describe("Hook Contracts", () => {
+    beforeEach(() => {
+        jest.clearAllMocks();
+        jest.mocked(useTamboSessionToken).mockReturnValue({
+            isFetching: false,
+        });
+    });
+    const createWrapper = (props) => {
+        const Wrapper = ({ children }) => (React.createElement(TamboClientProvider, { ...props }, children));
+        Wrapper.displayName = "TestWrapper";
+        return Wrapper;
+    };
+    describe("useTamboClient", () => {
+        it("should return client instance inside provider", () => {
+            const { result } = renderHook(() => useTamboClient(), {
+                wrapper: createWrapper({ apiKey: "test-api-key" }),
+            });
+            expect(result.current).toBeDefined();
+            expect(result.current.beta).toBeDefined();
+        });
+        it("should throw descriptive error outside provider", () => {
+            // Suppress console.error for this test
+            const consoleSpy = jest.spyOn(console, "error").mockImplementation();
+            expect(() => {
+                renderHook(() => useTamboClient());
+            }).toThrow("useTamboClient must be used within a TamboClientProvider");
+            consoleSpy.mockRestore();
+        });
+    });
+    describe("useTamboQueryClient", () => {
+        it("should return QueryClient instance inside provider", () => {
+            const { result } = renderHook(() => useTamboQueryClient(), {
+                wrapper: createWrapper({ apiKey: "test-api-key" }),
+            });
+            expect(result.current).toBeDefined();
+            expect(typeof result.current.getQueryCache).toBe("function");
+        });
+        it("should throw descriptive error outside provider", () => {
+            const consoleSpy = jest.spyOn(console, "error").mockImplementation();
+            expect(() => {
+                renderHook(() => useTamboQueryClient());
+            }).toThrow("useTamboQueryClient must be used within a TamboClientProvider");
+            consoleSpy.mockRestore();
+        });
+    });
+    describe("useIsTamboTokenUpdating", () => {
+        it("should throw descriptive error outside provider", () => {
+            const consoleSpy = jest.spyOn(console, "error").mockImplementation();
+            expect(() => {
+                renderHook(() => useIsTamboTokenUpdating());
+            }).toThrow("useIsTamboTokenUpdating must be used within a TamboClientProvider");
+            consoleSpy.mockRestore();
+        });
+    });
+});
+//# sourceMappingURL=tambo-client-provider.test.js.map

package/esm/providers/tambo-client-provider.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tambo-client-provider.test.js","sourceRoot":"","sources":["../../src/providers/tambo-client-provider.test.tsx"],"names":[],"mappings":"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","sourcesContent":["import { renderHook } from \"@testing-library/react\";\nimport React from \"react\";\nimport {\n  TamboClientProvider,\n  TamboClientProviderProps,\n  useIsTamboTokenUpdating,\n  useTamboClient,\n  useTamboQueryClient,\n} from \"./tambo-client-provider\";\n\n// Mock the session token hook to control token fetching state\njest.mock(\"./hooks/use-tambo-session-token\", () => ({\n  useTamboSessionToken: jest.fn(),\n}));\n\nimport { useTamboSessionToken } from \"./hooks/use-tambo-session-token\";\n\n// Add fetch polyfill for jsdom environment (TamboAI SDK requires it)\nconst mockFetch = jest.fn();\nlet previousFetch: typeof fetch;\n\nbeforeEach(() => {\n  mockFetch.mockReset();\n  previousFetch = global.fetch;\n  global.fetch = mockFetch as unknown as typeof fetch;\n});\n\nafterEach(() => {\n  global.fetch = previousFetch;\n});\n\ndescribe(\"TamboClientProvider\", () => {\n  beforeEach(() => {\n    jest.clearAllMocks();\n\n    // Default mock: not fetching\n    jest.mocked(useTamboSessionToken).mockReturnValue({\n      isFetching: false,\n      data: undefined,\n      error: null,\n      isLoading: false,\n      isError: false,\n      isSuccess: false,\n      status: \"pending\",\n      fetchStatus: \"idle\",\n    } as any);\n  });\n\n  const createWrapper = (props: TamboClientProviderProps) => {\n    const Wrapper = ({ children }: { children: React.ReactNode }) => (\n      <TamboClientProvider {...props}>{children}</TamboClientProvider>\n    );\n    Wrapper.displayName = \"TestWrapper\";\n    return Wrapper;\n  };\n\n  describe(\"Client Configuration\", () => {\n    it(\"should create client accessible via useTamboClient hook\", () => {\n      const { result } = renderHook(() => useTamboClient(), {\n        wrapper: createWrapper({ apiKey: \"test-api-key\" }),\n      });\n\n      // Client should be a TamboAI instance with expected shape\n      expect(result.current).toBeDefined();\n      expect(result.current.beta).toBeDefined();\n    });\n\n    it(\"should provide the same client instance on re-renders\", () => {\n      const { result, rerender } = renderHook(() => useTamboClient(), {\n        wrapper: createWrapper({ apiKey: \"test-api-key\" }),\n      });\n\n      const firstClient = result.current;\n      rerender();\n      const secondClient = result.current;\n\n      expect(firstClient).toBe(secondClient);\n    });\n\n    it(\"should configure client with provided tamboUrl\", () => {\n      const { result } = renderHook(() => useTamboClient(), {\n        wrapper: createWrapper({\n          apiKey: \"test-api-key\",\n          tamboUrl: \"https://custom.tambo.api\",\n        }),\n      });\n\n      expect(result.current.baseURL).toBe(\"https://custom.tambo.api\");\n    });\n\n    it(\"should configure client with provided environment\", async () => {\n      const { result } = renderHook(() => useTamboClient(), {\n        wrapper: createWrapper({\n          apiKey: \"test-api-key\",\n          environment: \"staging\",\n        }),\n      });\n\n      const { url } = await result.current.buildRequest({\n        method: \"get\",\n        path: \"/test-endpoint\",\n      });\n\n      expect(url).toBe(\"https://hydra-api-dev.up.railway.app/test-endpoint\");\n    });\n\n    it(\"should throw if both tamboUrl and environment are provided\", () => {\n      const consoleSpy = jest.spyOn(console, \"error\").mockImplementation();\n\n      expect(() => {\n        renderHook(() => useTamboClient(), {\n          wrapper: createWrapper({\n            apiKey: \"test-api-key\",\n            tamboUrl: \"https://custom.tambo.api\",\n            environment: \"staging\",\n          }),\n        });\n      }).toThrow(\n        \"Ambiguous URL; The `baseURL` option (or TAMBO_AI_BASE_URL env var) and the `environment` option are given. If you want to use the environment you must pass baseURL: null\",\n      );\n\n      consoleSpy.mockRestore();\n    });\n\n    it(\"should include additional headers in client configuration\", async () => {\n      const { result } = renderHook(() => useTamboClient(), {\n        wrapper: createWrapper({\n          apiKey: \"test-api-key\",\n          additionalHeaders: {\n            \"X-Custom-Header\": \"custom-value\",\n            \"X-Another-Header\": \"another-value\",\n          },\n        }),\n      });\n\n      const { req } = await result.current.buildRequest({\n        method: \"get\",\n        path: \"/test-endpoint\",\n      });\n\n      expect(req.headers.get(\"X-Tambo-React-Version\")).toBeDefined();\n      expect(req.headers.get(\"X-Tambo-React-Version\")).toMatch(/\\d+\\.\\d+\\.\\d+/); // version format\n      expect(req.headers.get(\"X-Custom-Header\")).toBe(\"custom-value\");\n      expect(req.headers.get(\"X-Another-Header\")).toBe(\"another-value\");\n    });\n  });\n\n  describe(\"Token State\", () => {\n    it(\"should expose isUpdatingToken=true when session token is fetching\", () => {\n      jest.mocked(useTamboSessionToken).mockReturnValue({\n        isFetching: true,\n      } as any);\n\n      const { result } = renderHook(() => useIsTamboTokenUpdating(), {\n        wrapper: createWrapper({\n          apiKey: \"test-api-key\",\n          userToken: \"oauth-token\",\n        }),\n      });\n\n      expect(result.current).toBe(true);\n    });\n\n    it(\"should expose isUpdatingToken=false when not fetching\", () => {\n      jest.mocked(useTamboSessionToken).mockReturnValue({\n        isFetching: false,\n      } as any);\n\n      const { result } = renderHook(() => useIsTamboTokenUpdating(), {\n        wrapper: createWrapper({ apiKey: \"test-api-key\" }),\n      });\n\n      expect(result.current).toBe(false);\n    });\n\n    it(\"should call useTamboSessionToken with userToken when provided\", () => {\n      renderHook(() => useTamboClient(), {\n        wrapper: createWrapper({\n          apiKey: \"test-api-key\",\n          userToken: \"my-oauth-token\",\n        }),\n      });\n\n      expect(useTamboSessionToken).toHaveBeenCalledWith(\n        expect.anything(), // client\n        expect.anything(), // queryClient\n        \"my-oauth-token\",\n      );\n    });\n  });\n});\n\ndescribe(\"Hook Contracts\", () => {\n  beforeEach(() => {\n    jest.clearAllMocks();\n\n    jest.mocked(useTamboSessionToken).mockReturnValue({\n      isFetching: false,\n    } as any);\n  });\n\n  const createWrapper = (props: { apiKey: string }) => {\n    const Wrapper = ({ children }: { children: React.ReactNode }) => (\n      <TamboClientProvider {...props}>{children}</TamboClientProvider>\n    );\n    Wrapper.displayName = \"TestWrapper\";\n    return Wrapper;\n  };\n\n  describe(\"useTamboClient\", () => {\n    it(\"should return client instance inside provider\", () => {\n      const { result } = renderHook(() => useTamboClient(), {\n        wrapper: createWrapper({ apiKey: \"test-api-key\" }),\n      });\n\n      expect(result.current).toBeDefined();\n      expect(result.current.beta).toBeDefined();\n    });\n\n    it(\"should throw descriptive error outside provider\", () => {\n      // Suppress console.error for this test\n      const consoleSpy = jest.spyOn(console, \"error\").mockImplementation();\n\n      expect(() => {\n        renderHook(() => useTamboClient());\n      }).toThrow(\"useTamboClient must be used within a TamboClientProvider\");\n\n      consoleSpy.mockRestore();\n    });\n  });\n\n  describe(\"useTamboQueryClient\", () => {\n    it(\"should return QueryClient instance inside provider\", () => {\n      const { result } = renderHook(() => useTamboQueryClient(), {\n        wrapper: createWrapper({ apiKey: \"test-api-key\" }),\n      });\n\n      expect(result.current).toBeDefined();\n      expect(typeof result.current.getQueryCache).toBe(\"function\");\n    });\n\n    it(\"should throw descriptive error outside provider\", () => {\n      const consoleSpy = jest.spyOn(console, \"error\").mockImplementation();\n\n      expect(() => {\n        renderHook(() => useTamboQueryClient());\n      }).toThrow(\n        \"useTamboQueryClient must be used within a TamboClientProvider\",\n      );\n\n      consoleSpy.mockRestore();\n    });\n  });\n\n  describe(\"useIsTamboTokenUpdating\", () => {\n    it(\"should throw descriptive error outside provider\", () => {\n      const consoleSpy = jest.spyOn(console, \"error\").mockImplementation();\n\n      expect(() => {\n        renderHook(() => useIsTamboTokenUpdating());\n      }).toThrow(\n        \"useIsTamboTokenUpdating must be used within a TamboClientProvider\",\n      );\n\n      consoleSpy.mockRestore();\n    });\n  });\n});\n"]}

package/esm/providers/tambo-context-attachment-provider.d.ts

@@ -1,110 +1,52 @@
-import type { Suggestion } from "@tambo-ai/typescript-sdk/resources/beta/threads/suggestions";
 import React from "react";
 /**
- * Represents a context attachment that can be displayed in MessageInputContexts.
- * Context attachments appear as badges above the message input and provide additional
- * information to the AI about what to focus on.
- * @property {string} name - Display name shown in the badge
- * @property {React.ReactNode} [icon] - Optional icon to display in the badge
- * @property {Record<string, unknown>} [metadata] - Additional data passed to the AI
- * @example
- * ```tsx
- * const context: ContextAttachment = {
- *   name: "Button.tsx",
- *   icon: <FileIcon />,
- *   metadata: { filePath: "/src/components/Button.tsx" }
- * };
- * ```
+ * Represents a context attachment that will be sent with the next user message.
+ * These are automatically registered as context helpers and will be included in
+ * the additionalContext when the next message is sent.
+ * @property {string} id - Unique identifier for this context attachment
+ * @property {string} [displayName] - Optional display name for UI rendering
+ * @property {string} context - The context value that will be used in additionalContext
+ * @property {string} [type] - Optional type identifier for grouping/rendering multiple contexts of the same type
  */
 export interface ContextAttachment {
     id: string;
-    name: string;
-    icon?: React.ReactNode;
-    metadata?: Record<string, unknown>;
+    displayName?: string;
+    context: string;
+    type?: string;
 }
 /**
- * Represents the data structure returned by a context helper
- */
-export type ContextHelperData = Record<string, unknown>;
-/**
- * Context state interface for managing context attachments and custom suggestions.
- * @property {ContextAttachment[]} attachments - Array of active context attachments (badges above message input)
- * @property {(context: Omit<ContextAttachment, "id">) => void} addContextAttachment - Add a new context attachment
+ * Context state interface for managing context attachments.
+ * @property {ContextAttachment[]} attachments - Array of active context attachments
+ * @property {(contextAttachment: Omit<ContextAttachment, "id">) => ContextAttachment} addContextAttachment - Add a new context attachment, returns the attachment
  * @property {(id: string) => void} removeContextAttachment - Remove a context attachment by ID
- * @property {() => void} clearContextAttachments - Remove all context attachments - This is used to clear the context when the user submits a message
- * @property {Suggestion[] | null} customSuggestions - Custom suggestions to display instead of auto-generated ones
- * @property {(suggestions: Suggestion[] | null) => void} setCustomSuggestions - Set or clear custom suggestions
+ * @property {() => void} clearContextAttachments - Remove all context attachments
  */
 export interface ContextAttachmentState {
     attachments: ContextAttachment[];
-    addContextAttachment: (context: Omit<ContextAttachment, "id">) => void;
+    addContextAttachment: (contextAttachment: Omit<ContextAttachment, "id">) => ContextAttachment;
     removeContextAttachment: (id: string) => void;
     clearContextAttachments: () => void;
-    customSuggestions: Suggestion[] | null;
-    setCustomSuggestions: (suggestions: Suggestion[] | null) => void;
 }
-/**
- * Props for the TamboContextAttachmentProvider.
- * @property {(context: ContextAttachment) => Promise<ContextHelperData> | ContextHelperData} [getContextHelperData] - Optional function to customize the data sent to the AI for each context. If not provided, uses a default structure with the context name and instruction.
- * @example
- * ```tsx
- * <TamboContextAttachmentProvider
- *   getContextHelperData={(context) => ({
- *     selectedFile: {
- *       name: context.name,
- *       path: context.metadata?.filePath,
- *       instruction: "Focus on this file"
- *     }
- *   })}
- * >
- *   {children}
- * </TamboContextAttachmentProvider>
- * ```
- */
 export interface TamboContextAttachmentProviderProps {
     children?: React.ReactNode;
-    getContextHelperData?: (context: ContextAttachment) => Promise<ContextHelperData> | ContextHelperData;
 }
 /**
- * Provider that enables context attachment features and custom suggestions in MessageInput.
- * **When to use:**
+ * Provider that manages context attachments for the next user message.
  * - **Included by default** in TamboProvider - no need to wrap separately
  * - Use `useTamboContextAttachment()` hook to manage context attachments
  * **What it does:**
- * - Manages context items that appear as badges above MessageInput
- * - Syncs context data with Tambo's AI for better responses
- * - Manages custom suggestions that replace auto-generated suggestions
- * - Allows components to add/remove contexts via `useTamboContextAttachment()`
- * - Allows components to set custom suggestions via `setCustomSuggestions()`
+ * - Stores context attachments that will be sent with the next message
+ * - Automatically registers/deregisters context helpers for each attachment
+ * - Context helpers are automatically collected during message submission
+ * - Context attachments are cleared after message submission (one-time use)
+ *
+ * **Note:** Context attachments are automatically included in additionalContext when
+ * the next message is sent. They are cleared after submission.
  * @param props - The props for the TamboContextAttachmentProvider
  * @param props.children - The children to wrap
- * @param props.getContextHelperData - The function to get the context helper data
  * @returns The TamboContextAttachmentProvider component
- * @example
- * Basic usage - already included in TamboProvider
- * ```tsx
- * <TamboProvider apiKey="...">
- *   <App />
- * </TamboProvider>
- * ```
- * @example
- * Using TamboProvider with custom context data
- * ```tsx
- * <TamboProvider
- *   apiKey="..."
- *   getContextHelperData={(context) => ({
- *     selectedComponent: {
- *       name: context.name,
- *       filePath: context.metadata?.path,
- *       instruction: "Edit this component"
- *     }
- *   })}
- * >
- *   <App />
- * </TamboProvider>
- * ```
  */
-export declare function TamboContextAttachmentProvider({ children, getContextHelperData, }: TamboContextAttachmentProviderProps): React.JSX.Element;
+export declare function TamboContextAttachmentProvider({ children, }: TamboContextAttachmentProviderProps): React.JSX.Element;
 /**
  * Hook to access context attachment state and methods.
  * **Must be used within a `TamboProvider`** - throws an error otherwise.
@@ -112,20 +54,20 @@ export declare function TamboContextAttachmentProvider({ children, getContextHel
  * @returns The context attachment state and methods
  * @example
  * ```tsx
- * const contextAttachment = useTamboContextAttachment();
+ * const { addContextAttachment, attachments, clearContextAttachments } = useTamboContextAttachment();
  *
- * // Add a context
- * contextAttachment.addContextAttachment({
- *   name: "Button.tsx",
- *   icon: <FileIcon />,
- *   metadata: { path: "/src/Button.tsx" }
+ * // Add a context attachment for the next message
+ * const attachment = addContextAttachment({
+ *   context: "The contents of File.txt",
+ *   displayName: "File.txt", // optional
+ *   type: "file" // optional
  * });
  *
- * // Remove a context
- * contextAttachment.removeContextAttachment(contextId);
+ * // Remove a context attachment
+ * removeContextAttachment(attachment.id);
  *
- * // Set custom suggestions
- * contextAttachment.setCustomSuggestions([{ id: "1", title: "Add Feature" }]);
+ * // Clear all context attachments
+ * clearContextAttachments();
  * ```
  */
 export declare function useTamboContextAttachment(): ContextAttachmentState;

package/esm/providers/tambo-context-attachment-provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tambo-context-attachment-provider.d.ts","sourceRoot":"","sources":["../../src/providers/tambo-context-attachment-provider.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6DAA6D,CAAC;AAC9F,OAAO,KAQN,MAAM,OAAO,CAAC;AAGf;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAExD;;;;;;;;GAQG;AACH,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,iBAAiB,EAAE,CAAC;IACjC,oBAAoB,EAAE,CAAC,OAAO,EAAE,IAAI,CAAC,iBAAiB,EAAE,IAAI,CAAC,KAAK,IAAI,CAAC;IACvE,uBAAuB,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9C,uBAAuB,EAAE,MAAM,IAAI,CAAC;IACpC,iBAAiB,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC;IACvC,oBAAoB,EAAE,CAAC,WAAW,EAAE,UAAU,EAAE,GAAG,IAAI,KAAK,IAAI,CAAC;CAClE;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,mCAAmC;IAClD,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,oBAAoB,CAAC,EAAE,CACrB,OAAO,EAAE,iBAAiB,KACvB,OAAO,CAAC,iBAAiB,CAAC,GAAG,iBAAiB,CAAC;CACrD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,8BAA8B,CAAC,EAC7C,QAAQ,EACR,oBAAoB,GACrB,EAAE,mCAAmC,qBAsHrC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,yBAAyB,2BAQxC"}
+{"version":3,"file":"tambo-context-attachment-provider.d.ts","sourceRoot":"","sources":["../../src/providers/tambo-context-attachment-provider.tsx"],"names":[],"mappings":"AAEA,OAAO,KAON,MAAM,OAAO,CAAC;AAGf;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,iBAAiB,EAAE,CAAC;IACjC,oBAAoB,EAAE,CACpB,iBAAiB,EAAE,IAAI,CAAC,iBAAiB,EAAE,IAAI,CAAC,KAC7C,iBAAiB,CAAC;IACvB,uBAAuB,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9C,uBAAuB,EAAE,MAAM,IAAI,CAAC;CACrC;AAMD,MAAM,WAAW,mCAAmC;IAClD,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC5B;AAID;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,8BAA8B,CAAC,EAC7C,QAAQ,GACT,EAAE,mCAAmC,qBAuFrC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,yBAAyB,2BAQxC"}

package/esm/providers/tambo-context-attachment-provider.js

@@ -1,117 +1,77 @@
 "use client";
-import React, { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, } from "react";
+import React, { createContext, useCallback, useContext, useEffect, useMemo, useState, } from "react";
 import { useTamboContextHelpers } from "./tambo-context-helpers-provider";
 const ContextAttachmentContext = createContext(null);
+const CONTEXT_ATTACHMENTS_HELPER_KEY = "contextAttachments";
 /**
- * Provider that enables context attachment features and custom suggestions in MessageInput.
- * **When to use:**
+ * Provider that manages context attachments for the next user message.
  * - **Included by default** in TamboProvider - no need to wrap separately
  * - Use `useTamboContextAttachment()` hook to manage context attachments
  * **What it does:**
- * - Manages context items that appear as badges above MessageInput
- * - Syncs context data with Tambo's AI for better responses
- * - Manages custom suggestions that replace auto-generated suggestions
- * - Allows components to add/remove contexts via `useTamboContextAttachment()`
- * - Allows components to set custom suggestions via `setCustomSuggestions()`
+ * - Stores context attachments that will be sent with the next message
+ * - Automatically registers/deregisters context helpers for each attachment
+ * - Context helpers are automatically collected during message submission
+ * - Context attachments are cleared after message submission (one-time use)
+ *
+ * **Note:** Context attachments are automatically included in additionalContext when
+ * the next message is sent. They are cleared after submission.
  * @param props - The props for the TamboContextAttachmentProvider
  * @param props.children - The children to wrap
- * @param props.getContextHelperData - The function to get the context helper data
  * @returns The TamboContextAttachmentProvider component
- * @example
- * Basic usage - already included in TamboProvider
- * ```tsx
- * <TamboProvider apiKey="...">
- *   <App />
- * </TamboProvider>
- * ```
- * @example
- * Using TamboProvider with custom context data
- * ```tsx
- * <TamboProvider
- *   apiKey="..."
- *   getContextHelperData={(context) => ({
- *     selectedComponent: {
- *       name: context.name,
- *       filePath: context.metadata?.path,
- *       instruction: "Edit this component"
- *     }
- *   })}
- * >
- *   <App />
- * </TamboProvider>
- * ```
  */
-export function TamboContextAttachmentProvider({ children, getContextHelperData, }) {
-    const [attachments, setAttachments] = useState([]);
-    const [customSuggestions, setCustomSuggestions] = useState(null);
+export function TamboContextAttachmentProvider({ children, }) {
     const { addContextHelper, removeContextHelper } = useTamboContextHelpers();
-    // Track which context helpers have been registered to avoid duplicates
-    const registeredIdsRef = useRef(new Set());
-    const prevGetContextHelperDataRef = useRef();
-    // Sync context helpers with attachments using useEffect
+    const [attachments, setAttachments] = useState([]);
     useEffect(() => {
-        const currentIds = attachments.map((a) => a.id);
-        const registeredIds = registeredIdsRef.current;
-        // Remove context helpers that are no longer in attachments
-        registeredIds.forEach((id) => {
-            if (!currentIds.includes(id)) {
-                removeContextHelper(id);
-                registeredIds.delete(id);
+        addContextHelper(CONTEXT_ATTACHMENTS_HELPER_KEY, () => {
+            if (attachments.length === 0) {
+                return null;
             }
+            return attachments.map((attachment) => ({
+                id: attachment.id,
+                displayName: attachment.displayName,
+                context: attachment.context,
+                type: attachment.type,
+            }));
         });
-        const getDataChanged = prevGetContextHelperDataRef.current !== getContextHelperData;
-        // Add or replace context helpers for attachments
-        attachments.forEach((context) => {
-            if (getDataChanged || !registeredIds.has(context.id)) {
-                addContextHelper(context.id, async () => {
-                    if (getContextHelperData) {
-                        return await getContextHelperData(context);
-                    }
-                    return {
-                        selectedComponent: {
-                            name: context.name,
-                            instruction: "This is a Tambo interactable component that is currently selected and visible on the dashboard. You can read its current props and state, and update it by modifying its props. If multiple components are attached, you can interact with and modify any of them. Use the auto-registered interactable component tools (like get_interactable_component_by_id and update_interactable_component_<id>) to view and update the component's state.",
-                            ...(context.metadata ?? {}),
-                        },
-                    };
-                });
-                registeredIds.add(context.id);
-            }
-        });
-        prevGetContextHelperDataRef.current = getContextHelperData;
-    }, [
-        attachments,
-        addContextHelper,
-        removeContextHelper,
-        getContextHelperData,
-    ]);
-    // Cleanup: remove all context helpers on unmount
-    useEffect(() => {
-        const registeredIds = registeredIdsRef.current;
         return () => {
-            registeredIds.forEach((id) => {
-                removeContextHelper(id);
-            });
-            registeredIds.clear();
+            removeContextHelper(CONTEXT_ATTACHMENTS_HELPER_KEY);
         };
-    }, [removeContextHelper]);
-    const addContextAttachment = useCallback((context) => {
-        setAttachments((prev) => {
-            if (prev.some((c) => c.name === context.name))
-                return prev;
-            if (typeof crypto === "undefined" || !("randomUUID" in crypto)) {
-                throw new Error("crypto.randomUUID() is not available. This usually happens when using an IP address instead of 'localhost' in development. Use 'localhost' or a secure context (HTTPS) to enable crypto APIs.");
-            }
-            const newId = crypto.randomUUID();
-            const newContext = { ...context, id: newId };
-            return [...prev, newContext];
-        });
+    }, [attachments, addContextHelper, removeContextHelper]);
+    /**
+     * Adds a new context attachment that will be included with the next user message.
+     * The attachment is automatically registered as part of the merged context helper.
+     * @param contextAttachment - The context attachment input (context, optional displayName, optional type)
+     * @returns The created ContextAttachment object with a unique ID
+     * @example
+     * ```tsx
+     * const attachment = addContextAttachment({
+     *   context: "The contents of File.txt",
+     *   displayName: "File.txt",
+     *   type: "file"
+     * });
+     * ```
+     */
+    const addContextAttachment = useCallback((contextAttachment) => {
+        const id = crypto.randomUUID();
+        const attachment = {
+            id,
+            displayName: contextAttachment.displayName,
+            context: contextAttachment.context,
+            type: contextAttachment.type,
+        };
+        setAttachments((prev) => [...prev, attachment]);
+        return attachment;
     }, []);
-    // This is used to remove a context when the user clicks the remove button
+    /**
+     * Removes a context attachment by its ID.
+     */
     const removeContextAttachment = useCallback((id) => {
         setAttachments((prev) => prev.filter((c) => c.id !== id));
     }, []);
-    // This is used to clear the context when the user submits a message
+    /**
+     * Removes all context attachments at once.
+     */
     const clearContextAttachments = useCallback(() => {
         setAttachments([]);
     }, []);
@@ -120,14 +80,11 @@ export function TamboContextAttachmentProvider({ children, getContextHelperData,
         addContextAttachment,
         removeContextAttachment,
         clearContextAttachments,
-        customSuggestions,
-        setCustomSuggestions,
     }), [
         attachments,
         addContextAttachment,
         removeContextAttachment,
         clearContextAttachments,
-        customSuggestions,
     ]);
     return (React.createElement(ContextAttachmentContext.Provider, { value: value }, children));
 }
@@ -138,20 +95,20 @@ export function TamboContextAttachmentProvider({ children, getContextHelperData,
  * @returns The context attachment state and methods
  * @example
  * ```tsx
- * const contextAttachment = useTamboContextAttachment();
+ * const { addContextAttachment, attachments, clearContextAttachments } = useTamboContextAttachment();
  *
- * // Add a context
- * contextAttachment.addContextAttachment({
- *   name: "Button.tsx",
- *   icon: <FileIcon />,
- *   metadata: { path: "/src/Button.tsx" }
+ * // Add a context attachment for the next message
+ * const attachment = addContextAttachment({
+ *   context: "The contents of File.txt",
+ *   displayName: "File.txt", // optional
+ *   type: "file" // optional
  * });
  *
- * // Remove a context
- * contextAttachment.removeContextAttachment(contextId);
+ * // Remove a context attachment
+ * removeContextAttachment(attachment.id);
  *
- * // Set custom suggestions
- * contextAttachment.setCustomSuggestions([{ id: "1", title: "Add Feature" }]);
+ * // Clear all context attachments
+ * clearContextAttachments();
  * ```
  */
 export function useTamboContextAttachment() {