@ai-me-chat/react 0.1.0 → 0.2.0

package/README.md

@@ -42,6 +42,165 @@ export function Providers({ children }: { children: React.ReactNode }) {
 - **`useAIMe()`** — full chat state (messages, input, submit) for custom UIs
 - **`useAIMeContext()`** — access provider context
 
+## Syncing Client State After Tool Execution
+
+When the AI executes a tool that mutates data (POST/PUT/DELETE), your client-side
+state may be stale. Use `onToolComplete` to trigger a refresh and `onMessageComplete`
+to know when the full response is done:
+
+```tsx
+"use client";
+
+import { useRouter } from "next/navigation";
+import { AIMeProvider, AIMeChat } from "@ai-me-chat/react";
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  const router = useRouter();
+
+  return (
+    <AIMeProvider endpoint="/api/ai-me">
+      {children}
+      <AIMeChat
+        onToolComplete={(tool) => {
+          // Refresh the page whenever the AI calls a mutating tool.
+          // You can narrow by tool.name or tool.httpMethod for finer control.
+          router.refresh();
+        }}
+        onMessageComplete={(message) => {
+          // The assistant finished its full response — all tool calls are done.
+          console.log("Assistant reply:", message.content);
+        }}
+      />
+    </AIMeProvider>
+  );
+}
+```
+
+`onToolComplete` fires once per tool execution, immediately after the result
+is available in the message stream. Fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `name` | `string` | Tool (function) name |
+| `httpMethod` | `string \| undefined` | HTTP method, if surfaced |
+| `path` | `string \| undefined` | API path called, if surfaced |
+| `result` | `unknown` | Raw tool result |
+| `requiresConfirmation` | `boolean \| undefined` | Whether confirmation was required |
+
+`onMessageComplete` fires once when the assistant finishes a full response
+(status transitions from `"streaming"` to `"ready"`). Fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `role` | `string` | Always `"assistant"` |
+| `content` | `string` | Concatenated text content |
+| `toolCalls` | `unknown[] \| undefined` | Tool-call parts, if any |
+
+## Custom Confirmation Rendering
+
+By default, AI-Me shows its built-in `<AIMeConfirm>` dialog before executing
+any tool that requires user confirmation (destructive actions, etc.).
+
+Use `renderConfirmation` on `<AIMeChat>` to replace the default dialog with
+your own UI — a branded modal, a slide-over panel, an inline card, whatever
+fits your design system:
+
+```tsx
+"use client";
+
+import { AIMeProvider, AIMeChat } from "@ai-me-chat/react";
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <AIMeProvider endpoint="/api/ai-me">
+      {children}
+      <AIMeChat
+        renderConfirmation={({ tool, params, onConfirm, onCancel }) => (
+          <MyConfirmModal
+            title={`Run "${tool.name}"?`}
+            description={tool.description}
+            details={`${tool.httpMethod} ${tool.path}`}
+            params={params}
+            onConfirm={onConfirm}
+            onCancel={onCancel}
+          />
+        )}
+      />
+    </AIMeProvider>
+  );
+}
+```
+
+The `renderConfirmation` callback receives:
+
+| Prop | Type | Description |
+|---|---|---|
+| `tool.name` | `string` | Tool (function) name |
+| `tool.httpMethod` | `string` | HTTP method, e.g. `"POST"` |
+| `tool.path` | `string` | API path, e.g. `"/api/projects"` |
+| `tool.description` | `string` | Human-readable description |
+| `params` | `Record<string, unknown>` | Resolved call parameters |
+| `onConfirm` | `() => void` | Call to proceed with execution |
+| `onCancel` | `() => void` | Call to abort |
+
+If `renderConfirmation` is omitted, the default dialog is used.
+
+## Navigation Intents (Action Callbacks)
+
+Sometimes the AI should guide the UI — navigate to a route, pre-fill a form,
+open a modal — rather than making an API call directly. Use the `onAction`
+prop on `<AIMeProvider>` to handle these client-side intents:
+
+```tsx
+"use client";
+
+import { useRouter } from "next/navigation";
+import { AIMeProvider, AIMeChat } from "@ai-me-chat/react";
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  const router = useRouter();
+
+  return (
+    <AIMeProvider
+      endpoint="/api/ai-me"
+      onAction={(action) => {
+        switch (action.type) {
+          case "navigate":
+            router.push(action.href as string);
+            break;
+          case "prefill":
+            // Broadcast to a form using a custom event, context, or state manager
+            window.dispatchEvent(
+              new CustomEvent("ai-me:prefill", { detail: action.fields }),
+            );
+            break;
+          case "open-modal":
+            // Open whichever modal the AI identified
+            openModal(action.modalId as string);
+            break;
+        }
+      }}
+    >
+      {children}
+      <AIMeChat />
+    </AIMeProvider>
+  );
+}
+```
+
+The `onAction` callback receives an object with at least a `type` field plus
+any additional payload the tool provides:
+
+| Field | Type | Description |
+|---|---|---|
+| `type` | `string` | Action kind — `"navigate"`, `"prefill"`, `"open-modal"`, etc. |
+| `...rest` | `unknown` | Flexible payload defined per action type |
+
+The `onAction` callback is stored in context and available to any component
+via `useAIMeContext().onAction`. The actual tool registrations that emit these
+actions live in your AI-Me handler (server-side), so client and server
+concerns stay separated.
+
 ## Theming
 
 ```tsx

package/dist/index.cjs

@@ -44,8 +44,8 @@ function useAIMeContext() {
 
 // src/provider.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
-function AIMeProvider({ endpoint, headers, children }) {
-  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(AIMeContext, { value: { endpoint, headers }, children });
+function AIMeProvider({ endpoint, headers, onAction, children }) {
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(AIMeContext, { value: { endpoint, headers, onAction }, children });
 }
 
 // src/chat.tsx
@@ -356,13 +356,17 @@ function AIMeChat({
   welcomeMessage = "Hi! I can help you navigate and use this app. What would you like to do?",
   suggestedPrompts,
   defaultOpen = false,
-  onToggle
+  onToggle,
+  onToolComplete,
+  onMessageComplete
 }) {
   const [open, setOpen] = (0, import_react4.useState)(defaultOpen);
   const messagesEndRef = (0, import_react4.useRef)(null);
   const inputRef = (0, import_react4.useRef)(null);
   const panelRef = (0, import_react4.useRef)(null);
   const triggerRef = (0, import_react4.useRef)(null);
+  const firedToolResults = (0, import_react4.useRef)(/* @__PURE__ */ new Set());
+  const prevStatus = (0, import_react4.useRef)(null);
   const {
     messages,
     input,
@@ -393,6 +397,44 @@ function AIMeChat({
   (0, import_react4.useEffect)(() => {
     messagesEndRef.current?.scrollIntoView({ behavior: "smooth" });
   }, [messages]);
+  (0, import_react4.useEffect)(() => {
+    if (!onToolComplete) return;
+    for (const message of messages) {
+      for (const part of message.parts) {
+        if (part.type !== "tool-result") continue;
+        const id = part.toolCallId;
+        const dedupeKey = id ?? `${message.id}:${part.type}`;
+        if (firedToolResults.current.has(dedupeKey)) continue;
+        firedToolResults.current.add(dedupeKey);
+        onToolComplete({
+          name: part.toolName ?? "",
+          result: part.result
+        });
+      }
+    }
+  }, [messages, onToolComplete]);
+  (0, import_react4.useEffect)(() => {
+    const prev = prevStatus.current;
+    prevStatus.current = status;
+    if (!onMessageComplete) return;
+    if (status !== "ready") return;
+    if (prev !== "streaming" && prev !== "submitted") return;
+    let lastAssistant;
+    for (let i = messages.length - 1; i >= 0; i--) {
+      if (messages[i].role === "assistant") {
+        lastAssistant = messages[i];
+        break;
+      }
+    }
+    if (!lastAssistant) return;
+    const textContent = lastAssistant.parts.filter((p) => p.type === "text").map((p) => p.text).join("");
+    const toolCalls = lastAssistant.parts.filter((p) => p.type === "tool-call");
+    onMessageComplete({
+      role: lastAssistant.role,
+      content: textContent,
+      toolCalls: toolCalls.length > 0 ? toolCalls : void 0
+    });
+  }, [status, messages, onMessageComplete]);
   (0, import_react4.useEffect)(() => {
     if (open) {
       panelRef.current?.focus();
@@ -455,7 +497,8 @@ function AIMeChat({
     bottom: 24,
     ...position === "bottom-right" ? { right: 24 } : { left: 24 },
     width: 380,
-    maxHeight: "70vh",
+    height: "70vh",
+    maxHeight: 600,
     display: open ? "flex" : "none",
     flexDirection: "column",
     fontFamily: "var(--ai-me-font)",