@lantos1618/better-ui 0.2.2 → 0.3.1

package/dist/index.js

@@ -0,0 +1,522 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Tool: () => Tool,
+  ToolBuilder: () => ToolBuilder,
+  tool: () => tool,
+  useTool: () => useTool,
+  useTools: () => useTools
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/tool.tsx
+var import_react = require("react");
+var import_jsx_runtime = require("react/jsx-runtime");
+var Tool = class {
+  constructor(config) {
+    this.name = config.name;
+    this.description = config.description;
+    this.inputSchema = config.input;
+    this.outputSchema = config.output;
+    this.tags = config.tags || [];
+    this.cacheConfig = config.cache;
+    this.clientFetchConfig = config.clientFetch;
+    this._initView();
+  }
+  /**
+   * Define server-side implementation
+   * Runs on server (API routes, server components, etc.)
+   */
+  server(handler) {
+    this._server = handler;
+    return this;
+  }
+  /**
+   * Define client-side implementation
+   * Runs in browser. If not specified, auto-fetches to /api/tools/{name}
+   */
+  client(handler) {
+    this._client = handler;
+    return this;
+  }
+  /**
+   * Define view component for rendering results
+   * Our differentiator from TanStack AI
+   */
+  view(component) {
+    this._view = component;
+    this._initView();
+    return 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.
+   */
+  async run(input, ctx) {
+    const validated = this.inputSchema.parse(input);
+    const isServer = ctx?.isServer ?? typeof window === "undefined";
+    const context = {
+      cache: ctx?.cache || /* @__PURE__ */ new Map(),
+      fetch: ctx?.fetch || globalThis.fetch?.bind(globalThis),
+      isServer,
+      // Only include server-sensitive fields when actually on server
+      ...isServer ? {
+        env: ctx?.env,
+        headers: ctx?.headers,
+        cookies: ctx?.cookies,
+        user: ctx?.user,
+        session: ctx?.session
+      } : {
+        // Client-only fields
+        optimistic: ctx?.optimistic
+      }
+    };
+    if (this.cacheConfig && context.cache) {
+      const cacheKey = this.cacheConfig.key ? this.cacheConfig.key(validated) : `${this.name}:${JSON.stringify(validated)}`;
+      const cached = context.cache.get(cacheKey);
+      if (cached && cached.expiry > Date.now()) {
+        return cached.data;
+      }
+    }
+    let result;
+    if (context.isServer) {
+      if (!this._server) {
+        throw new Error(`Tool "${this.name}" has no server implementation`);
+      }
+      result = await this._server(validated, context);
+    } else {
+      if (this._client) {
+        result = await this._client(validated, context);
+      } else if (this._server) {
+        result = await this._defaultClientFetch(validated, context);
+      } else {
+        throw new Error(`Tool "${this.name}" has no implementation`);
+      }
+    }
+    if (this.outputSchema) {
+      try {
+        result = this.outputSchema.parse(result);
+      } catch (error) {
+        console.error(`Output validation failed for tool "${this.name}":`, error);
+        if (error instanceof Error && "errors" in error) {
+          console.error("Validation errors:", error.errors);
+        }
+        throw error;
+      }
+    }
+    if (this.cacheConfig && context.cache) {
+      const cacheKey = this.cacheConfig.key ? this.cacheConfig.key(validated) : `${this.name}:${JSON.stringify(validated)}`;
+      context.cache.set(cacheKey, {
+        data: result,
+        expiry: Date.now() + this.cacheConfig.ttl
+      });
+    }
+    return result;
+  }
+  /**
+   * Make the tool callable directly: await weather({ city: 'London' })
+   */
+  async call(input, ctx) {
+    return this.run(input, ctx);
+  }
+  /**
+   * 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.
+   */
+  async _defaultClientFetch(input, ctx) {
+    const endpoint = this.clientFetchConfig?.endpoint || "/api/tools/execute";
+    const response = await ctx.fetch(endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ tool: this.name, input })
+    });
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new Error(error.message || error.error || `Tool execution failed: ${response.statusText}`);
+    }
+    const data = await response.json();
+    return data.result ?? data.data ?? data;
+  }
+  _initView() {
+    const viewFn = this._view;
+    const name = this.name;
+    const ViewComponent = (props) => {
+      if (!viewFn) {
+        if (props.loading) return null;
+        if (props.error) return null;
+        if (!props.data) return null;
+        return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("pre", { children: JSON.stringify(props.data, null, 2) });
+      }
+      if (!props.data && !props.loading && !props.error) {
+        return null;
+      }
+      return viewFn(props.data, {
+        loading: props.loading,
+        error: props.error,
+        onAction: props.onAction
+      });
+    };
+    ViewComponent.displayName = `${name}View`;
+    this.View = (0, import_react.memo)(ViewComponent, (prevProps, nextProps) => {
+      if (prevProps.data !== nextProps.data) return false;
+      if (prevProps.loading !== nextProps.loading) return false;
+      if (prevProps.error !== nextProps.error) return false;
+      return true;
+    });
+  }
+  /**
+   * Check if tool has a view
+   */
+  get hasView() {
+    return !!this._view;
+  }
+  /**
+   * Check if tool has server implementation
+   */
+  get hasServer() {
+    return !!this._server;
+  }
+  /**
+   * Check if tool has custom client implementation
+   */
+  get hasClient() {
+    return !!this._client;
+  }
+  /**
+   * Convert to plain object (for serialization)
+   *
+   * SECURITY: This intentionally excludes handlers and schemas to prevent
+   * accidental exposure of server logic or validation details.
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      description: this.description,
+      tags: this.tags,
+      hasServer: this.hasServer,
+      hasClient: this.hasClient,
+      hasView: this.hasView,
+      hasCache: !!this.cacheConfig
+      // Intentionally NOT included: handlers, schemas, clientFetchConfig
+    };
+  }
+  /**
+   * Convert to AI SDK format (Vercel AI SDK v5 compatible)
+   */
+  toAITool() {
+    return {
+      description: this.description || this.name,
+      inputSchema: this.inputSchema,
+      execute: async (input) => {
+        return this.run(input, { isServer: true });
+      }
+    };
+  }
+};
+function tool(nameOrConfig) {
+  if (typeof nameOrConfig === "string") {
+    return new ToolBuilder(nameOrConfig);
+  }
+  return new Tool(nameOrConfig);
+}
+var ToolBuilder = class {
+  constructor(name) {
+    this._tags = [];
+    this._name = name;
+  }
+  description(desc) {
+    this._description = desc;
+    return 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(schema) {
+    this._input = schema;
+    return this;
+  }
+  /**
+   * Define output schema - enables type inference for results
+   */
+  output(schema) {
+    this._output = schema;
+    return this;
+  }
+  tags(...tags) {
+    this._tags.push(...tags);
+    return this;
+  }
+  cache(config) {
+    this._cache = config;
+    return this;
+  }
+  /** Configure auto-fetch endpoint for client-side execution */
+  clientFetch(config) {
+    this._clientFetch = config;
+    return this;
+  }
+  server(handler) {
+    this._serverHandler = handler;
+    return this;
+  }
+  client(handler) {
+    this._clientHandler = handler;
+    return this;
+  }
+  view(component) {
+    this._viewComponent = component;
+    return this;
+  }
+  /**
+   * Build the final Tool instance
+   */
+  build() {
+    if (!this._input) {
+      throw new Error(`Tool "${this._name}" requires an input schema`);
+    }
+    const t = new Tool({
+      name: this._name,
+      description: this._description,
+      input: this._input,
+      output: this._output,
+      tags: this._tags,
+      cache: this._cache,
+      clientFetch: this._clientFetch
+    });
+    if (this._serverHandler) t.server(this._serverHandler);
+    if (this._clientHandler) t.client(this._clientHandler);
+    if (this._viewComponent) t.view(this._viewComponent);
+    return t;
+  }
+  /**
+   * Auto-build when accessing Tool methods
+   */
+  async run(input, ctx) {
+    return this.build().run(input, ctx);
+  }
+  get View() {
+    return this.build().View;
+  }
+  toJSON() {
+    return this.build().toJSON();
+  }
+  toAITool() {
+    return this.build().toAITool();
+  }
+};
+
+// src/react/useTool.ts
+var import_react2 = require("react");
+function useTool(tool2, initialInput, options = {}) {
+  const [data, setData] = (0, import_react2.useState)(null);
+  const [loading, setLoading] = (0, import_react2.useState)(false);
+  const [error, setError] = (0, import_react2.useState)(null);
+  const [executed, setExecuted] = (0, import_react2.useState)(false);
+  const inputRef = (0, import_react2.useRef)(initialInput);
+  const optionsRef = (0, import_react2.useRef)(options);
+  optionsRef.current = options;
+  const executionIdRef = (0, import_react2.useRef)(0);
+  const pendingCountRef = (0, import_react2.useRef)(0);
+  const execute = (0, import_react2.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 tool2.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);
+        }
+      }
+    },
+    [tool2]
+  );
+  const reset = (0, import_react2.useCallback)(() => {
+    setData(null);
+    setError(null);
+    setLoading(false);
+    setExecuted(false);
+  }, []);
+  (0, import_react2.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 = (0, import_react2.useRef)(tools);
+  const optionsRef = (0, import_react2.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] = (0, import_react2.useState)(() => {
+    const initial = {};
+    for (const name of Object.keys(tools)) {
+      initial[name] = {
+        data: null,
+        loading: false,
+        error: null,
+        executed: false
+      };
+    }
+    return initial;
+  });
+  const createExecute = (0, import_react2.useCallback)(
+    (toolName, tool2) => {
+      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 tool2.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 = (0, import_react2.useCallback)((toolName) => {
+    return () => {
+      setState((prev) => ({
+        ...prev,
+        [toolName]: {
+          data: null,
+          loading: false,
+          error: null,
+          executed: false
+        }
+      }));
+    };
+  }, []);
+  const results = {};
+  for (const [name, tool2] 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, tool2),
+      reset: createReset(toolName)
+    };
+  }
+  return results;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Tool,
+  ToolBuilder,
+  tool,
+  useTool,
+  useTools
+});