@lantos1618/better-ui 0.3.1 → 0.4.0

package/dist/react/index.mjs

@@ -0,0 +1,257 @@
+"use client";
+import "../chunk-Y6FXYEAI.mjs";
+
+// src/react/useTool.ts
+import { useState, useCallback, useEffect, useRef } from "react";
+function useTool(tool, initialInput, options = {}) {
+  const [data, setData] = useState(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState(null);
+  const [executed, setExecuted] = useState(false);
+  const inputRef = useRef(initialInput);
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  const executionIdRef = useRef(0);
+  const pendingCountRef = useRef(0);
+  const execute = useCallback(
+    async (input) => {
+      const finalInput = input ?? inputRef.current;
+      if (finalInput === void 0) {
+        const err = new Error("No input provided to tool");
+        setError(err);
+        optionsRef.current.onError?.(err);
+        return null;
+      }
+      const currentExecutionId = ++executionIdRef.current;
+      pendingCountRef.current++;
+      setLoading(true);
+      setError(null);
+      try {
+        const context = {
+          cache: /* @__PURE__ */ new Map(),
+          fetch: globalThis.fetch?.bind(globalThis),
+          isServer: false,
+          ...optionsRef.current.context
+        };
+        const result = await tool.run(finalInput, context);
+        if (currentExecutionId === executionIdRef.current) {
+          setData(result);
+          setExecuted(true);
+          optionsRef.current.onSuccess?.(result);
+        }
+        return result;
+      } catch (err) {
+        const error2 = err instanceof Error ? err : new Error(String(err));
+        if (currentExecutionId === executionIdRef.current) {
+          setError(error2);
+          optionsRef.current.onError?.(error2);
+        }
+        return null;
+      } finally {
+        pendingCountRef.current--;
+        if (pendingCountRef.current === 0) {
+          setLoading(false);
+        }
+      }
+    },
+    [tool]
+  );
+  const reset = useCallback(() => {
+    setData(null);
+    setError(null);
+    setLoading(false);
+    setExecuted(false);
+  }, []);
+  useEffect(() => {
+    if (options.auto && initialInput !== void 0) {
+      inputRef.current = initialInput;
+      execute(initialInput);
+    }
+  }, [options.auto, initialInput, execute]);
+  return {
+    data,
+    loading,
+    error,
+    execute,
+    reset,
+    executed
+  };
+}
+function useTools(tools, options = {}) {
+  const toolsRef = useRef(tools);
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  if (process.env.NODE_ENV !== "production") {
+    const prevKeys = Object.keys(toolsRef.current);
+    const currKeys = Object.keys(tools);
+    if (prevKeys.length !== currKeys.length || !currKeys.every((k) => prevKeys.includes(k))) {
+      console.warn(
+        "useTools: The tools object keys changed between renders. This may cause unexpected behavior. Define tools outside the component or memoize with useMemo."
+      );
+    }
+    toolsRef.current = tools;
+  }
+  const [state, setState] = useState(() => {
+    const initial = {};
+    for (const name of Object.keys(tools)) {
+      initial[name] = {
+        data: null,
+        loading: false,
+        error: null,
+        executed: false
+      };
+    }
+    return initial;
+  });
+  const createExecute = useCallback(
+    (toolName, tool) => {
+      return async (input) => {
+        if (input === void 0) {
+          const err = new Error("No input provided to tool");
+          setState((prev) => ({
+            ...prev,
+            [toolName]: { ...prev[toolName], error: err }
+          }));
+          optionsRef.current.onError?.(err);
+          return null;
+        }
+        setState((prev) => ({
+          ...prev,
+          [toolName]: { ...prev[toolName], loading: true, error: null }
+        }));
+        try {
+          const context = {
+            cache: /* @__PURE__ */ new Map(),
+            fetch: globalThis.fetch?.bind(globalThis),
+            isServer: false,
+            ...optionsRef.current.context
+          };
+          const result = await tool.run(input, context);
+          setState((prev) => ({
+            ...prev,
+            [toolName]: {
+              data: result,
+              loading: false,
+              error: null,
+              executed: true
+            }
+          }));
+          optionsRef.current.onSuccess?.(result);
+          return result;
+        } catch (err) {
+          const error = err instanceof Error ? err : new Error(String(err));
+          setState((prev) => ({
+            ...prev,
+            [toolName]: { ...prev[toolName], loading: false, error }
+          }));
+          optionsRef.current.onError?.(error);
+          return null;
+        }
+      };
+    },
+    []
+  );
+  const createReset = useCallback((toolName) => {
+    return () => {
+      setState((prev) => ({
+        ...prev,
+        [toolName]: {
+          data: null,
+          loading: false,
+          error: null,
+          executed: false
+        }
+      }));
+    };
+  }, []);
+  const results = {};
+  for (const [name, tool] of Object.entries(tools)) {
+    const toolName = name;
+    const toolState = state[toolName];
+    results[toolName] = {
+      data: toolState?.data ?? null,
+      loading: toolState?.loading ?? false,
+      error: toolState?.error ?? null,
+      executed: toolState?.executed ?? false,
+      execute: createExecute(toolName, tool),
+      reset: createReset(toolName)
+      // Per-key type safety is enforced by the function's return type annotation.
+    };
+  }
+  return results;
+}
+
+// src/react/useToolStream.ts
+import { useState as useState2, useCallback as useCallback2, useRef as useRef2 } from "react";
+function useToolStream(tool, options = {}) {
+  const [data, setData] = useState2(null);
+  const [finalData, setFinalData] = useState2(null);
+  const [streaming, setStreaming] = useState2(false);
+  const [loading, setLoading] = useState2(false);
+  const [error, setError] = useState2(null);
+  const executionIdRef = useRef2(0);
+  const optionsRef = useRef2(options);
+  optionsRef.current = options;
+  const execute = useCallback2(
+    async (input) => {
+      const currentId = ++executionIdRef.current;
+      setLoading(true);
+      setStreaming(false);
+      setError(null);
+      setData(null);
+      setFinalData(null);
+      try {
+        let accumulated = {};
+        let result = null;
+        let firstChunkReceived = false;
+        for await (const chunk of tool.runStream(input, {
+          isServer: false,
+          ...optionsRef.current.context
+        })) {
+          if (currentId !== executionIdRef.current) return null;
+          if (chunk.done) {
+            result = chunk.partial;
+            setFinalData(result);
+            setData(result);
+            setStreaming(false);
+            setLoading(false);
+            optionsRef.current.onSuccess?.(result);
+          } else {
+            if (!firstChunkReceived) {
+              firstChunkReceived = true;
+              setStreaming(true);
+              setLoading(false);
+            }
+            accumulated = { ...accumulated, ...chunk.partial };
+            setData({ ...accumulated });
+          }
+        }
+        setLoading(false);
+        setStreaming(false);
+        return result;
+      } catch (err) {
+        if (currentId !== executionIdRef.current) return null;
+        const e = err instanceof Error ? err : new Error(String(err));
+        setError(e);
+        setLoading(false);
+        setStreaming(false);
+        optionsRef.current.onError?.(e);
+        return null;
+      }
+    },
+    [tool]
+  );
+  const reset = useCallback2(() => {
+    setData(null);
+    setFinalData(null);
+    setStreaming(false);
+    setLoading(false);
+    setError(null);
+  }, []);
+  return { data, finalData, streaming, loading, error, execute, reset };
+}
+export {
+  useTool,
+  useToolStream,
+  useTools
+};

package/dist/tool-Ca2x-VNK.d.mts

@@ -0,0 +1,361 @@
+import { z } from 'zod';
+import React, { ReactElement } from 'react';
+
+/**
+ * Better UI v2 - Tool Definition
+ *
+ * Clean, type-safe tool definition inspired by TanStack AI,
+ * with Better UI's unique view integration.
+ */
+
+/** Behavioral hints for tools */
+interface ToolHints {
+    /** Tool performs destructive/irreversible actions (auto-implies requiresConfirmation) */
+    destructive?: boolean;
+    /** Tool only reads data, never modifies state */
+    readOnly?: boolean;
+    /** Tool can be safely retried without side effects */
+    idempotent?: boolean;
+}
+/** Entry stored in the tool context cache */
+interface CacheEntry {
+    data: unknown;
+    expiry: number;
+}
+/**
+ * Context passed to tool handlers
+ *
+ * SECURITY NOTE:
+ * - Server-only fields (env, headers, cookies, user, session) are automatically
+ *   stripped when running on the client to prevent accidental leakage.
+ * - Server handlers NEVER run on the client - they auto-fetch via API instead.
+ * - Never store secrets in tool output - it gets sent to the client.
+ */
+interface ToolContext {
+    /** Shared cache for deduplication */
+    cache: Map<string, CacheEntry>;
+    /** Fetch function (can be customized for auth headers, etc.) */
+    fetch: typeof fetch;
+    /** Whether running on server */
+    isServer: boolean;
+    /** Environment variables - NEVER available on client */
+    env?: Record<string, string>;
+    /** Request headers - NEVER available on client */
+    headers?: Headers;
+    /** Cookies - NEVER available on client */
+    cookies?: Record<string, string>;
+    /** Authenticated user - NEVER available on client */
+    user?: Record<string, unknown>;
+    /** Session data - NEVER available on client */
+    session?: Record<string, unknown>;
+    /** Optimistic update function */
+    optimistic?: <T>(data: Partial<T>) => void;
+}
+interface CacheConfig<TInput> {
+    ttl: number;
+    key?: (input: TInput) => string;
+}
+/** Configuration for auto-fetch behavior when no client handler is defined */
+interface ClientFetchConfig {
+    /** API endpoint for tool execution (default: '/api/tools/execute') */
+    endpoint?: string;
+}
+interface ToolConfig<TInput, TOutput> {
+    name: string;
+    description?: string;
+    input: z.ZodType<TInput>;
+    output?: z.ZodType<TOutput>;
+    tags?: string[];
+    cache?: CacheConfig<TInput>;
+    /** Configure auto-fetch behavior for client-side execution */
+    clientFetch?: ClientFetchConfig;
+    /** If true or returns true, tool requires human confirmation before executing (HITL).
+     *  When a function, it receives the input and can conditionally require confirmation. */
+    confirm?: boolean | ((input: TInput) => boolean);
+    /** Behavioral hints for the tool */
+    hints?: ToolHints;
+    /** Group related tool calls by a key derived from input.
+     *  Calls with the same groupKey are collapsed in the thread — only the latest renders fully. */
+    groupKey?: (input: TInput) => string;
+    /** When true, a user UI action on this tool automatically sends the updated state
+     *  to the AI so it can continue without the user typing a message. */
+    autoRespond?: boolean;
+}
+type ServerHandler<TInput, TOutput> = (input: TInput, ctx: ToolContext) => Promise<TOutput> | TOutput;
+type ClientHandler<TInput, TOutput> = (input: TInput, ctx: ToolContext) => Promise<TOutput> | TOutput;
+type StreamCallback<TOutput> = (partial: Partial<TOutput>) => void;
+type StreamHandler<TInput, TOutput> = (input: TInput, ctx: ToolContext & {
+    /** Send a partial update to the view */
+    stream: StreamCallback<TOutput>;
+}) => Promise<TOutput>;
+type ViewState<TInput = unknown> = {
+    loading?: boolean;
+    /** True while receiving partial streaming updates */
+    streaming?: boolean;
+    error?: Error | null;
+    onAction?: (input: TInput) => void | Promise<void>;
+};
+type ViewComponent<TOutput, TInput = unknown> = (data: TOutput, state?: ViewState<TInput>) => ReactElement | null;
+declare class Tool<TInput = any, TOutput = any> {
+    readonly name: string;
+    readonly description?: string;
+    readonly inputSchema: z.ZodType<TInput>;
+    readonly outputSchema?: z.ZodType<TOutput>;
+    readonly tags: string[];
+    readonly cacheConfig?: CacheConfig<TInput>;
+    readonly clientFetchConfig?: ClientFetchConfig;
+    readonly confirm: boolean | ((input: TInput) => boolean);
+    readonly hints: ToolHints;
+    readonly groupKey?: (input: TInput) => string;
+    readonly autoRespond: boolean;
+    private _server?;
+    private _client?;
+    private _view?;
+    private _stream?;
+    constructor(config: ToolConfig<TInput, TOutput>);
+    /**
+     * Define server-side implementation
+     * Runs on server (API routes, server components, etc.)
+     */
+    server(handler: ServerHandler<TInput, TOutput>): this;
+    /**
+     * Define client-side implementation
+     * Runs in browser. If not specified, auto-fetches to /api/tools/{name}
+     */
+    client(handler: ClientHandler<TInput, TOutput>): this;
+    /**
+     * Define view component for rendering results
+     * Our differentiator from TanStack AI
+     */
+    view(component: ViewComponent<TOutput, TInput>): this;
+    /**
+     * Define streaming implementation
+     * The handler receives a `stream` callback to push partial updates.
+     */
+    stream(handler: StreamHandler<TInput, TOutput>): this;
+    /**
+     * Execute the tool
+     * Automatically uses server or client handler based on environment
+     *
+     * SECURITY: Server handlers only run on server. Client automatically
+     * fetches from /api/tools/execute if no client handler is defined.
+     */
+    run(input: TInput, ctx?: Partial<ToolContext>): Promise<TOutput>;
+    /**
+     * Make the tool callable directly: await weather({ city: 'London' })
+     */
+    call(input: TInput, ctx?: Partial<ToolContext>): Promise<TOutput>;
+    /**
+     * Execute with streaming - returns async generator of partial results.
+     * Falls back to run() if no stream handler is defined.
+     */
+    runStream(input: TInput, ctx?: Partial<ToolContext>): AsyncGenerator<{
+        partial: Partial<TOutput>;
+        done: boolean;
+    }>;
+    /**
+     * Default client fetch when no .client() is defined
+     *
+     * SECURITY: This ensures server handlers never run on the client.
+     * The server-side /api/tools/execute endpoint handles execution safely.
+     */
+    private _defaultClientFetch;
+    /**
+     * Render the tool's view component
+     * Memoized to prevent unnecessary re-renders when parent state changes
+     */
+    View: React.NamedExoticComponent<{
+        data: TOutput | null;
+        loading?: boolean;
+        streaming?: boolean;
+        error?: Error | null;
+        onAction?: (input: TInput) => void | Promise<void>;
+    }>;
+    private _initView;
+    /**
+     * Check if tool has a view
+     */
+    get hasView(): boolean;
+    /**
+     * Check if tool has server implementation
+     */
+    get hasServer(): boolean;
+    /**
+     * Check if tool has custom client implementation
+     */
+    get hasClient(): boolean;
+    /**
+     * Check if tool has a streaming implementation
+     */
+    get hasStream(): boolean;
+    /**
+     * Check if tool requires human confirmation before executing (HITL)
+     * Returns true if `confirm` is truthy (boolean true or a function) OR `hints.destructive: true`
+     */
+    get requiresConfirmation(): boolean;
+    /**
+     * Determine if a specific input should trigger user confirmation.
+     * - If `confirm` is a function, calls it with input
+     * - If `confirm` is boolean, returns it
+     * - If `hints.destructive`, returns true
+     */
+    shouldConfirm(input: TInput): boolean;
+    /**
+     * Get the entity group key for a given input.
+     * Returns `"toolName:groupKey(input)"` if groupKey is defined, otherwise undefined.
+     */
+    getGroupKey(input: TInput): string | undefined;
+    /**
+     * Convert to plain object (for serialization)
+     *
+     * SECURITY: This intentionally excludes handlers and schemas to prevent
+     * accidental exposure of server logic or validation details.
+     */
+    toJSON(): {
+        name: string;
+        description: string | undefined;
+        tags: string[];
+        hasServer: boolean;
+        hasClient: boolean;
+        hasView: boolean;
+        hasStream: boolean;
+        hasCache: boolean;
+        confirm: boolean;
+        hints: ToolHints;
+        requiresConfirmation: boolean;
+    };
+    /**
+     * Convert to AI SDK format (Vercel AI SDK v5 compatible)
+     *
+     * If `confirm` is true, the execute function is omitted so the AI SDK
+     * leaves the tool call at `state: 'input-available'`, enabling HITL
+     * confirmation on the client before execution.
+     */
+    toAITool(): {
+        description: string;
+        inputSchema: z.ZodType<TInput, z.ZodTypeDef, TInput>;
+        execute?: undefined;
+    } | {
+        description: string;
+        inputSchema: z.ZodType<TInput, z.ZodTypeDef, TInput>;
+        execute: (input: TInput) => Promise<TOutput>;
+    };
+}
+/**
+ * Create a new tool with object config
+ *
+ * @example
+ * const weather = tool({
+ *   name: 'weather',
+ *   description: 'Get weather for a city',
+ *   input: z.object({ city: z.string() }),
+ *   output: z.object({ temp: z.number() }),
+ * });
+ *
+ * weather.server(async ({ city }) => {
+ *   return { temp: await getTemp(city) };
+ * });
+ */
+declare function tool<TInput, TOutput = any>(config: ToolConfig<TInput, TOutput>): Tool<TInput, TOutput>;
+/**
+ * Create a new tool with fluent builder
+ *
+ * @example
+ * const weather = tool('weather')
+ *   .description('Get weather for a city')
+ *   .input(z.object({ city: z.string() }))
+ *   .output(z.object({ temp: z.number() }))
+ *   .server(async ({ city }) => ({ temp: 72 }));
+ */
+declare function tool(name: string): ToolBuilder;
+declare class ToolBuilder<TInput = any, TOutput = any> {
+    private _name;
+    private _description?;
+    private _input?;
+    private _output?;
+    private _tags;
+    private _cache?;
+    private _clientFetch?;
+    private _confirm?;
+    private _hints?;
+    private _groupKey?;
+    private _autoRespond?;
+    private _serverHandler?;
+    private _clientHandler?;
+    private _viewComponent?;
+    private _streamHandler?;
+    constructor(name: string);
+    description(desc: string): this;
+    /**
+     * Define input schema - enables type inference for handlers
+     *
+     * NOTE: Uses type assertion internally. This is safe because:
+     * 1. The schema is stored and used correctly at runtime
+     * 2. The return type correctly reflects the new generic parameter
+     * 3. TypeScript doesn't support "this type mutation" in fluent builders
+     */
+    input<T>(schema: z.ZodType<T>): ToolBuilder<T, TOutput>;
+    /**
+     * Define output schema - enables type inference for results
+     */
+    output<O>(schema: z.ZodType<O>): ToolBuilder<TInput, O>;
+    tags(...tags: string[]): this;
+    cache(config: CacheConfig<TInput>): this;
+    /** Configure auto-fetch endpoint for client-side execution */
+    clientFetch(config: ClientFetchConfig): this;
+    /** Require human confirmation before executing (HITL) */
+    requireConfirm(value?: boolean | ((input: TInput) => boolean)): this;
+    /** Set a groupKey function for collapsing related tool calls */
+    groupBy(fn: (input: TInput) => string): this;
+    /** Auto-send updated state to AI after user interacts with this tool's UI */
+    autoRespondAfterAction(value?: boolean): this;
+    /** Set behavioral hints for the tool */
+    hints(hints: ToolHints): this;
+    server(handler: ServerHandler<TInput, TOutput>): this;
+    client(handler: ClientHandler<TInput, TOutput>): this;
+    stream(handler: StreamHandler<TInput, TOutput>): this;
+    view(component: ViewComponent<TOutput, TInput>): this;
+    /**
+     * Build the final Tool instance
+     */
+    build(): Tool<TInput, TOutput>;
+    /**
+     * Auto-build when accessing Tool methods
+     */
+    run(input: TInput, ctx?: Partial<ToolContext>): Promise<TOutput>;
+    runStream(input: TInput, ctx?: Partial<ToolContext>): AsyncGenerator<{
+        partial: Partial<TOutput>;
+        done: boolean;
+    }>;
+    get View(): React.NamedExoticComponent<{
+        data: TOutput | null;
+        loading?: boolean;
+        streaming?: boolean;
+        error?: Error | null;
+        onAction?: ((input: TInput) => void | Promise<void>) | undefined;
+    }>;
+    toJSON(): {
+        name: string;
+        description: string | undefined;
+        tags: string[];
+        hasServer: boolean;
+        hasClient: boolean;
+        hasView: boolean;
+        hasStream: boolean;
+        hasCache: boolean;
+        confirm: boolean;
+        hints: ToolHints;
+        requiresConfirmation: boolean;
+    };
+    toAITool(): {
+        description: string;
+        inputSchema: z.ZodType<TInput, z.ZodTypeDef, TInput>;
+        execute?: undefined;
+    } | {
+        description: string;
+        inputSchema: z.ZodType<TInput, z.ZodTypeDef, TInput>;
+        execute: (input: TInput) => Promise<TOutput>;
+    };
+}
+
+export { type ClientHandler as C, type ServerHandler as S, Tool as T, type ViewComponent as V, ToolBuilder as a, type ToolConfig as b, type ToolContext as c, type StreamCallback as d, type StreamHandler as e, type ViewState as f, type CacheConfig as g, type ClientFetchConfig as h, tool as t };