@lantos1618/better-ui 0.2.3 → 0.4.0

package/dist/index.js

@@ -0,0 +1,587 @@
+"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,
+  createAnthropicProvider: () => createAnthropicProvider,
+  createGoogleProvider: () => createGoogleProvider,
+  createOpenAIProvider: () => createOpenAIProvider,
+  createOpenRouterProvider: () => createOpenRouterProvider,
+  createProvider: () => createProvider,
+  tool: () => tool
+});
+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.confirm = config.confirm ?? false;
+    this.hints = config.hints ?? {};
+    this.groupKey = config.groupKey;
+    this.autoRespond = config.autoRespond ?? false;
+    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;
+  }
+  /**
+   * Define streaming implementation
+   * The handler receives a `stream` callback to push partial updates.
+   */
+  stream(handler) {
+    this._stream = handler;
+    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);
+  }
+  /**
+   * Execute with streaming - returns async generator of partial results.
+   * Falls back to run() if no stream handler is defined.
+   */
+  async *runStream(input, ctx) {
+    const validated = this.inputSchema.parse(input);
+    if (!this._stream) {
+      const result = await this.run(input, ctx);
+      yield { partial: result, done: true };
+      return;
+    }
+    const isServer = ctx?.isServer ?? typeof window === "undefined";
+    const context = {
+      cache: ctx?.cache || /* @__PURE__ */ new Map(),
+      fetch: ctx?.fetch || globalThis.fetch?.bind(globalThis),
+      isServer,
+      ...isServer ? {
+        env: ctx?.env,
+        headers: ctx?.headers,
+        cookies: ctx?.cookies,
+        user: ctx?.user,
+        session: ctx?.session
+      } : {
+        optimistic: ctx?.optimistic
+      }
+    };
+    const queue = [];
+    let waiter = null;
+    const notify = () => {
+      waiter?.();
+      waiter = null;
+    };
+    const wait = () => new Promise((r) => {
+      waiter = r;
+    });
+    const streamFn = (partial) => {
+      queue.push({ partial });
+      notify();
+    };
+    let error = null;
+    let isDone = false;
+    this._stream(validated, { ...context, stream: streamFn }).then((result) => {
+      queue.push({ done: true, result });
+      isDone = true;
+      notify();
+    }).catch((err) => {
+      error = err instanceof Error ? err : new Error(String(err));
+      isDone = true;
+      notify();
+    });
+    while (true) {
+      while (queue.length > 0) {
+        const item = queue.shift();
+        if ("done" in item) {
+          let finalResult = item.result;
+          if (this.outputSchema) finalResult = this.outputSchema.parse(finalResult);
+          yield { partial: finalResult, done: true };
+          return;
+        }
+        yield { partial: item.partial, done: false };
+      }
+      if (error) throw error;
+      if (isDone && queue.length === 0) return;
+      await wait();
+    }
+  }
+  /**
+   * 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,
+        streaming: props.streaming,
+        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.streaming !== nextProps.streaming) 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;
+  }
+  /**
+   * Check if tool has a streaming implementation
+   */
+  get hasStream() {
+    return !!this._stream;
+  }
+  /**
+   * 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() {
+    return !!this.confirm || this.hints.destructive === true;
+  }
+  /**
+   * 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) {
+    if (typeof this.confirm === "function") {
+      if (input == null) return false;
+      return this.confirm(input);
+    }
+    if (typeof this.confirm === "boolean") {
+      return this.confirm;
+    }
+    return this.hints.destructive === true;
+  }
+  /**
+   * Get the entity group key for a given input.
+   * Returns `"toolName:groupKey(input)"` if groupKey is defined, otherwise undefined.
+   */
+  getGroupKey(input) {
+    if (!this.groupKey || input == null) return void 0;
+    return `${this.name}:${this.groupKey(input)}`;
+  }
+  /**
+   * 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,
+      hasStream: this.hasStream,
+      hasCache: !!this.cacheConfig,
+      confirm: !!this.confirm,
+      hints: this.hints,
+      requiresConfirmation: this.requiresConfirmation
+      // Intentionally NOT included: handlers, schemas, clientFetchConfig
+    };
+  }
+  /**
+   * 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() {
+    if (this.requiresConfirmation) {
+      return {
+        description: this.description || this.name,
+        inputSchema: this.inputSchema
+      };
+    }
+    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;
+  }
+  /** Require human confirmation before executing (HITL) */
+  requireConfirm(value = true) {
+    this._confirm = value;
+    return this;
+  }
+  /** Set a groupKey function for collapsing related tool calls */
+  groupBy(fn) {
+    this._groupKey = fn;
+    return this;
+  }
+  /** Auto-send updated state to AI after user interacts with this tool's UI */
+  autoRespondAfterAction(value = true) {
+    this._autoRespond = value;
+    return this;
+  }
+  /** Set behavioral hints for the tool */
+  hints(hints) {
+    this._hints = hints;
+    return this;
+  }
+  server(handler) {
+    this._serverHandler = handler;
+    return this;
+  }
+  client(handler) {
+    this._clientHandler = handler;
+    return this;
+  }
+  stream(handler) {
+    this._streamHandler = 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,
+      confirm: this._confirm,
+      hints: this._hints,
+      groupKey: this._groupKey,
+      autoRespond: this._autoRespond
+    });
+    if (this._serverHandler) t.server(this._serverHandler);
+    if (this._clientHandler) t.client(this._clientHandler);
+    if (this._streamHandler) t.stream(this._streamHandler);
+    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);
+  }
+  async *runStream(input, ctx) {
+    yield* this.build().runStream(input, ctx);
+  }
+  get View() {
+    return this.build().View;
+  }
+  toJSON() {
+    return this.build().toJSON();
+  }
+  toAITool() {
+    return this.build().toAITool();
+  }
+};
+
+// src/providers/openai.ts
+function createOpenAIProvider(config) {
+  return {
+    type: "openai",
+    modelId: config.model,
+    model: () => {
+      const id = "@ai-sdk/openai";
+      const { openai } = require(id);
+      return openai(config.model);
+    }
+  };
+}
+
+// src/providers/anthropic.ts
+function createAnthropicProvider(config) {
+  return {
+    type: "anthropic",
+    modelId: config.model,
+    model: () => {
+      const id = "@ai-sdk/anthropic";
+      const { anthropic } = require(id);
+      return anthropic(config.model);
+    }
+  };
+}
+
+// src/providers/google.ts
+function createGoogleProvider(config) {
+  return {
+    type: "google",
+    modelId: config.model,
+    model: () => {
+      const id = "@ai-sdk/google";
+      const { google } = require(id);
+      return google(config.model);
+    }
+  };
+}
+
+// src/providers/openrouter.ts
+function createOpenRouterProvider(config) {
+  return {
+    type: "openrouter",
+    modelId: config.model,
+    model: () => {
+      const id = "@ai-sdk/openai";
+      const { createOpenAI } = require(id);
+      const openrouter = createOpenAI({
+        baseURL: config.baseURL || "https://openrouter.ai/api/v1",
+        apiKey: config.apiKey,
+        ...config.options
+      });
+      return openrouter(config.model);
+    }
+  };
+}
+
+// src/providers/index.ts
+function createProvider(config) {
+  switch (config.provider) {
+    case "openai":
+      return createOpenAIProvider(config);
+    case "anthropic":
+      return createAnthropicProvider(config);
+    case "google":
+      return createGoogleProvider(config);
+    case "openrouter":
+      return createOpenRouterProvider(config);
+    default: {
+      const exhaustiveCheck = config.provider;
+      throw new Error(`Unknown provider: ${exhaustiveCheck}`);
+    }
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Tool,
+  ToolBuilder,
+  createAnthropicProvider,
+  createGoogleProvider,
+  createOpenAIProvider,
+  createOpenRouterProvider,
+  createProvider,
+  tool
+});