@lantos1618/better-ui 0.2.3 → 0.3.1

package/dist/index.d.mts

@@ -0,0 +1,314 @@
+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.
+ */
+
+/**
+ * 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, any>;
+    /** 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?: any;
+    /** Session data - NEVER available on client */
+    session?: any;
+    /** 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;
+}
+type ServerHandler<TInput, TOutput> = (input: TInput, ctx: ToolContext) => Promise<TOutput> | TOutput;
+type ClientHandler<TInput, TOutput> = (input: TInput, ctx: ToolContext) => Promise<TOutput> | TOutput;
+type ViewState<TInput = any> = {
+    loading?: boolean;
+    error?: Error | null;
+    onAction?: (input: TInput) => void | Promise<void>;
+};
+type ViewComponent<TOutput, TInput = any> = (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;
+    private _server?;
+    private _client?;
+    private _view?;
+    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>): 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>;
+    /**
+     * 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;
+        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;
+    /**
+     * 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;
+        hasCache: boolean;
+    };
+    /**
+     * Convert to AI SDK format (Vercel AI SDK v5 compatible)
+     */
+    toAITool(): {
+        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 _serverHandler?;
+    private _clientHandler?;
+    private _viewComponent?;
+    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;
+    server(handler: ServerHandler<TInput, TOutput>): this;
+    client(handler: ClientHandler<TInput, TOutput>): this;
+    view(component: ViewComponent<TOutput>): this;
+    /**
+     * Build the final Tool instance
+     */
+    build(): Tool<TInput, TOutput>;
+    /**
+     * Auto-build when accessing Tool methods
+     */
+    run(input: TInput, ctx?: Partial<ToolContext>): Promise<TOutput>;
+    get View(): React.NamedExoticComponent<{
+        data: TOutput | null;
+        loading?: 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;
+        hasCache: boolean;
+    };
+    toAITool(): {
+        description: string;
+        inputSchema: z.ZodType<TInput, z.ZodTypeDef, TInput>;
+        execute: (input: TInput) => Promise<TOutput>;
+    };
+}
+
+interface UseToolOptions {
+    /** Auto-execute on mount or when input changes */
+    auto?: boolean;
+    /** Custom context overrides */
+    context?: Partial<ToolContext>;
+    /** Callback on success */
+    onSuccess?: (data: any) => void;
+    /** Callback on error */
+    onError?: (error: Error) => void;
+}
+interface UseToolResult<TInput, TOutput> {
+    /** The result data */
+    data: TOutput | null;
+    /** Loading state */
+    loading: boolean;
+    /** Error if any */
+    error: Error | null;
+    /** Execute the tool manually */
+    execute: (input?: TInput) => Promise<TOutput | null>;
+    /** Reset state */
+    reset: () => void;
+    /** Whether the tool has been executed at least once */
+    executed: boolean;
+}
+/**
+ * React hook for executing tools
+ *
+ * @example
+ * // Manual execution
+ * const { data, loading, execute } = useTool(weather);
+ * <button onClick={() => execute({ city: 'London' })}>Get Weather</button>
+ *
+ * @example
+ * // Auto execution when input changes
+ * const { data, loading } = useTool(weather, { city }, { auto: true });
+ *
+ * @example
+ * // With callbacks
+ * const { execute } = useTool(weather, undefined, {
+ *   onSuccess: (data) => console.log('Got weather:', data),
+ *   onError: (error) => console.error('Failed:', error),
+ * });
+ */
+declare function useTool<TInput, TOutput>(tool: Tool<TInput, TOutput>, initialInput?: TInput, options?: UseToolOptions): UseToolResult<TInput, TOutput>;
+/**
+ * React hook for executing multiple tools
+ *
+ * This hook properly manages state for multiple tools using a single useState,
+ * avoiding the hooks-in-loop anti-pattern.
+ *
+ * @example
+ * // Define tools outside component or memoize with useMemo
+ * const myTools = { weather, search };
+ *
+ * function MyComponent() {
+ *   const tools = useTools(myTools);
+ *   await tools.weather.execute({ city: 'London' });
+ *   await tools.search.execute({ query: 'restaurants' });
+ * }
+ */
+declare function useTools<T extends Record<string, Tool>>(tools: T, options?: UseToolOptions): {
+    [K in keyof T]: UseToolResult<T[K] extends Tool<infer I, any> ? I : never, T[K] extends Tool<any, infer O> ? O : never>;
+};
+
+export { type CacheConfig, type ClientFetchConfig, type ClientHandler, type ServerHandler, Tool, ToolBuilder, type ToolConfig, type ToolContext, type UseToolOptions, type UseToolResult, type ViewComponent, tool, useTool, useTools };

package/dist/index.d.ts

@@ -0,0 +1,314 @@
+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.
+ */
+
+/**
+ * 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, any>;
+    /** 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?: any;
+    /** Session data - NEVER available on client */
+    session?: any;
+    /** 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;
+}
+type ServerHandler<TInput, TOutput> = (input: TInput, ctx: ToolContext) => Promise<TOutput> | TOutput;
+type ClientHandler<TInput, TOutput> = (input: TInput, ctx: ToolContext) => Promise<TOutput> | TOutput;
+type ViewState<TInput = any> = {
+    loading?: boolean;
+    error?: Error | null;
+    onAction?: (input: TInput) => void | Promise<void>;
+};
+type ViewComponent<TOutput, TInput = any> = (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;
+    private _server?;
+    private _client?;
+    private _view?;
+    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>): 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>;
+    /**
+     * 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;
+        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;
+    /**
+     * 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;
+        hasCache: boolean;
+    };
+    /**
+     * Convert to AI SDK format (Vercel AI SDK v5 compatible)
+     */
+    toAITool(): {
+        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 _serverHandler?;
+    private _clientHandler?;
+    private _viewComponent?;
+    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;
+    server(handler: ServerHandler<TInput, TOutput>): this;
+    client(handler: ClientHandler<TInput, TOutput>): this;
+    view(component: ViewComponent<TOutput>): this;
+    /**
+     * Build the final Tool instance
+     */
+    build(): Tool<TInput, TOutput>;
+    /**
+     * Auto-build when accessing Tool methods
+     */
+    run(input: TInput, ctx?: Partial<ToolContext>): Promise<TOutput>;
+    get View(): React.NamedExoticComponent<{
+        data: TOutput | null;
+        loading?: 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;
+        hasCache: boolean;
+    };
+    toAITool(): {
+        description: string;
+        inputSchema: z.ZodType<TInput, z.ZodTypeDef, TInput>;
+        execute: (input: TInput) => Promise<TOutput>;
+    };
+}
+
+interface UseToolOptions {
+    /** Auto-execute on mount or when input changes */
+    auto?: boolean;
+    /** Custom context overrides */
+    context?: Partial<ToolContext>;
+    /** Callback on success */
+    onSuccess?: (data: any) => void;
+    /** Callback on error */
+    onError?: (error: Error) => void;
+}
+interface UseToolResult<TInput, TOutput> {
+    /** The result data */
+    data: TOutput | null;
+    /** Loading state */
+    loading: boolean;
+    /** Error if any */
+    error: Error | null;
+    /** Execute the tool manually */
+    execute: (input?: TInput) => Promise<TOutput | null>;
+    /** Reset state */
+    reset: () => void;
+    /** Whether the tool has been executed at least once */
+    executed: boolean;
+}
+/**
+ * React hook for executing tools
+ *
+ * @example
+ * // Manual execution
+ * const { data, loading, execute } = useTool(weather);
+ * <button onClick={() => execute({ city: 'London' })}>Get Weather</button>
+ *
+ * @example
+ * // Auto execution when input changes
+ * const { data, loading } = useTool(weather, { city }, { auto: true });
+ *
+ * @example
+ * // With callbacks
+ * const { execute } = useTool(weather, undefined, {
+ *   onSuccess: (data) => console.log('Got weather:', data),
+ *   onError: (error) => console.error('Failed:', error),
+ * });
+ */
+declare function useTool<TInput, TOutput>(tool: Tool<TInput, TOutput>, initialInput?: TInput, options?: UseToolOptions): UseToolResult<TInput, TOutput>;
+/**
+ * React hook for executing multiple tools
+ *
+ * This hook properly manages state for multiple tools using a single useState,
+ * avoiding the hooks-in-loop anti-pattern.
+ *
+ * @example
+ * // Define tools outside component or memoize with useMemo
+ * const myTools = { weather, search };
+ *
+ * function MyComponent() {
+ *   const tools = useTools(myTools);
+ *   await tools.weather.execute({ city: 'London' });
+ *   await tools.search.execute({ query: 'restaurants' });
+ * }
+ */
+declare function useTools<T extends Record<string, Tool>>(tools: T, options?: UseToolOptions): {
+    [K in keyof T]: UseToolResult<T[K] extends Tool<infer I, any> ? I : never, T[K] extends Tool<any, infer O> ? O : never>;
+};
+
+export { type CacheConfig, type ClientFetchConfig, type ClientHandler, type ServerHandler, Tool, ToolBuilder, type ToolConfig, type ToolContext, type UseToolOptions, type UseToolResult, type ViewComponent, tool, useTool, useTools };