@johpaz/hive-sdk 0.0.16 → 0.0.18

package/packages/core/src/tools/web/api-request.ts

@@ -0,0 +1,239 @@
+/**
+ * api_request - Make generic HTTP requests to connect REST APIs
+ *
+ * @category web
+ * @seedId api_request
+ * @spanish conectar api, peticion http, llamada api, rest api, endpoint
+ */
+
+import type { Tool } from "../types.ts";
+import { logger } from "../../utils/logger.ts";
+
+const log = logger.child("api-request");
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_RESPONSE_CHARS = 100_000;
+
+export type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS";
+export type ResponseFormat = "auto" | "json" | "text" | "binary";
+
+export interface ApiAuthBearer {
+  type: "bearer";
+  token: string;
+}
+
+export interface ApiAuthBasic {
+  type: "basic";
+  username: string;
+  password: string;
+}
+
+export interface ApiAuthApiKey {
+  type: "api_key";
+  in: "header" | "query";
+  name: string;
+  value: string;
+}
+
+export type ApiAuth = ApiAuthBearer | ApiAuthBasic | ApiAuthApiKey;
+
+function applyAuth(
+  url: string,
+  init: RequestInit,
+  auth?: ApiAuth
+): { url: string; init: RequestInit } {
+  if (!auth) return { url, init };
+
+  const headers = new Headers(init.headers);
+
+  switch (auth.type) {
+    case "bearer":
+      headers.set("Authorization", `Bearer ${auth.token}`);
+      break;
+    case "basic": {
+      const credentials = btoa(`${auth.username}:${auth.password}`);
+      headers.set("Authorization", `Basic ${credentials}`);
+      break;
+    }
+    case "api_key":
+      if (auth.in === "query") {
+        const parsed = new URL(url);
+        parsed.searchParams.set(auth.name, auth.value);
+        url = parsed.toString();
+      } else {
+        headers.set(auth.name, auth.value);
+      }
+      break;
+  }
+
+  return { url, init: { ...init, headers } };
+}
+
+function isValidHttpUrl(url: string): boolean {
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === "http:" || parsed.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+async function parseResponse(
+  response: Response,
+  format: ResponseFormat
+): Promise<{ data: unknown; contentType: string }> {
+  const contentType = response.headers.get("content-type") || "";
+
+  if (format === "json" || (format === "auto" && contentType.includes("application/json"))) {
+    const json = await response.json();
+    return { data: json, contentType };
+  }
+
+  if (format === "text" || (format === "auto" && contentType.includes("text/"))) {
+    const text = await response.text();
+    return { data: text.slice(0, MAX_RESPONSE_CHARS), contentType };
+  }
+
+  if (format === "binary") {
+    const arrayBuffer = await response.arrayBuffer();
+    const base64 = Buffer.from(arrayBuffer).toString("base64");
+    return { data: base64, contentType };
+  }
+
+  // Fallback: try text, then JSON
+  const text = await response.text();
+  if (text.trim().startsWith("{") || text.trim().startsWith("[")) {
+    try {
+      return { data: JSON.parse(text), contentType };
+    } catch {
+      /* fallthrough */
+    }
+  }
+  return { data: text.slice(0, MAX_RESPONSE_CHARS), contentType };
+}
+
+export const apiRequestTool: Tool = {
+  name: "api_request",
+  description:
+    "Connect to REST APIs: make HTTP requests with methods, headers, body and authentication. Spanish: conectar api, peticion http, llamada api, rest api, endpoint, bearer, api key",
+  parameters: {
+    type: "object",
+    properties: {
+      url: {
+        type: "string",
+        description: "The API endpoint URL (http:// or https://)",
+      },
+      method: {
+        type: "string",
+        enum: ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"],
+        description: "HTTP method (default: GET)",
+      },
+      headers: {
+        type: "object",
+        additionalProperties: { type: "string" },
+        description: "Optional HTTP headers as key-value pairs",
+      },
+      body: {
+        type: "string",
+        description: "Request body. Objects should be passed as JSON strings; strings are sent as-is",
+      },
+      auth: {
+        type: "object",
+        description: "Optional authentication configuration",
+        properties: {
+          type: {
+            type: "string",
+            enum: ["bearer", "basic", "api_key"],
+          },
+          token: { type: "string" },
+          username: { type: "string" },
+          password: { type: "string" },
+          in: { type: "string", enum: ["header", "query"] },
+          name: { type: "string" },
+          value: { type: "string" },
+        },
+        required: ["type"],
+      },
+      timeoutMs: {
+        type: "number",
+        description: "Request timeout in milliseconds (default: 30000)",
+      },
+      responseFormat: {
+        type: "string",
+        enum: ["auto", "json", "text", "binary"],
+        description: "How to parse the response (default: auto)",
+      },
+    },
+    required: ["url"],
+  },
+  execute: async (params: Record<string, unknown>) => {
+    const url = params.url as string;
+    const method = (params.method as HttpMethod) ?? "GET";
+    const headers = (params.headers as Record<string, string>) ?? {};
+    const bodyParam = params.body;
+    const auth = params.auth as ApiAuth | undefined;
+    const timeoutMs = (params.timeoutMs as number) ?? DEFAULT_TIMEOUT_MS;
+    const responseFormat = (params.responseFormat as ResponseFormat) ?? "auto";
+
+    if (!isValidHttpUrl(url)) {
+      return { ok: false, error: "Invalid URL. Only http:// and https:// are allowed." };
+    }
+
+    log.info(`API request: ${method} ${url}`);
+
+    let body: BodyInit | undefined;
+    const finalHeaders: Record<string, string> = { ...headers };
+
+    if (bodyParam !== undefined) {
+      if (typeof bodyParam === "string") {
+        body = bodyParam;
+      } else {
+        body = JSON.stringify(bodyParam);
+        if (!finalHeaders["content-type"] && !finalHeaders["Content-Type"]) {
+          finalHeaders["content-type"] = "application/json";
+        }
+      }
+    }
+
+    let init: RequestInit = {
+      method,
+      headers: finalHeaders,
+      body,
+      signal: AbortSignal.timeout(timeoutMs),
+    };
+
+    const final = applyAuth(url, init, auth);
+
+    try {
+      const response = await fetch(final.url, final.init);
+      const { data, contentType } = await parseResponse(response, responseFormat);
+
+      const responseHeaders: Record<string, string> = {};
+      response.headers.forEach((value, key) => {
+        responseHeaders[key] = value;
+      });
+
+      const result = {
+        ok: response.ok,
+        status: response.status,
+        statusText: response.statusText,
+        url: final.url,
+        contentType,
+        headers: responseHeaders,
+        data,
+      };
+
+      if (!response.ok) {
+        log.warn(`API request returned ${response.status} for ${final.url}`);
+        return { ok: false, error: `HTTP ${response.status}: ${response.statusText}`, ...result };
+      }
+
+      log.info(`API request successful: ${response.status} ${final.url}`);
+      return result;
+    } catch (error) {
+      const message = (error as Error).message;
+      log.error(`API request failed: ${message}`);
+      return { ok: false, error: `API request failed: ${message}` };
+    }
+  },
+};

package/packages/core/src/tools/web/browser-click.ts

@@ -43,7 +43,7 @@ export const browserClickTool: Tool = {
       log.warn("Browser not available");
       return {
         ok: false,
-        error: "Browser automation not available. Install Chrome/Chromium.",
+        error: "Browser automation not available. Install agent-browser.",
       };
     }
 
@@ -51,7 +51,7 @@ export const browserClickTool: Tool = {
 
     try {
       const view = await browserService.getView();
-      if (!view) return { ok: false, error: "Browser automation not available. Install Chrome/Chromium." };
+      if (!view) return { ok: false, error: "Browser automation not available. Install agent-browser." };
 
       if (url) {
         await view.navigate(url);

package/packages/core/src/tools/web/browser-extract.ts

@@ -14,7 +14,7 @@ const log = logger.child("browser-extract");
 
 export const browserExtractTool: Tool = {
   name: "browser_extract",
-  description: "Extract text, links, or structured data from page using CSS selectors or XPath. Spanish: extraer datos, obtener información, scraping, selectores",
+  description: "Extract text, links, or structured data from page using CSS selectors or XPath. For general page overview without specific selectors, returns compact accessibility snapshot. Spanish: extraer datos, obtener información, scraping, selectores",
   parameters: {
     type: "object",
     properties: {
@@ -24,7 +24,7 @@ export const browserExtractTool: Tool = {
       },
       selector: {
         type: "string",
-        description: "CSS selector or XPath (prefix with 'xpath:') to match elements",
+        description: "CSS selector or XPath (prefix with 'xpath:') to match elements. Use 'body' or omit for compact accessibility snapshot.",
       },
       attribute: {
         type: "string",
@@ -43,7 +43,7 @@ export const browserExtractTool: Tool = {
   },
   execute: async (params: Record<string, unknown>) => {
     const url = params.url as string | undefined;
-    const selector = params.selector as string;
+    const selector = (params.selector as string) || "body";
     const attribute = (params.attribute as string) ?? "text";
     const all = (params.all as boolean) ?? true;
     const timeout = (params.timeout as number) ?? 30000;
@@ -53,7 +53,7 @@ export const browserExtractTool: Tool = {
       log.warn("Browser not available");
       return {
         ok: false,
-        error: "Browser automation not available. Install Chrome/Chromium.",
+        error: "Browser automation not available. Install agent-browser.",
       };
     }
 
@@ -61,13 +61,30 @@ export const browserExtractTool: Tool = {
 
     try {
       const view = await browserService.getView();
-      if (!view) return { ok: false, error: "Browser automation not available. Install Chrome/Chromium." };
+      if (!view) return { ok: false, error: "Browser automation not available. Install agent-browser." };
 
       if (url) {
         await view.navigate(url);
         await Bun.sleep(500);
       }
 
+      const currentUrl = view.url;
+
+      // If selector is broad (body, html, *, :root) and attribute is text, return compact snapshot
+      const isBroadSelector = ["body", "html", "*", ":root", "document"].includes(selector.toLowerCase());
+      if (isBroadSelector && attribute === "text") {
+        const snapshot = await view.snapshot({ compact: true, depth: 3 });
+        log.info(`Snapshot extracted from ${currentUrl} (${snapshot.length} chars)`);
+        return {
+          ok: true,
+          url: currentUrl,
+          selector,
+          attribute: "snapshot",
+          count: 1,
+          data: [snapshot],
+        };
+      }
+
       const isXPath = selector.startsWith("xpath:");
       const actualSelector = isXPath ? selector.slice(6) : selector;
 
@@ -117,7 +134,6 @@ export const browserExtractTool: Tool = {
         })()
       `) as string[];
 
-      const currentUrl = view.url;
       log.info(`Extracted ${extracted.length} element(s) from ${currentUrl}`);
 
       return {

package/packages/core/src/tools/web/browser-navigate.ts

@@ -14,7 +14,7 @@ const log = logger.child("browser-navigate");
 
 export const browserNavigateTool: Tool = {
   name: "browser_navigate",
-  description: "Navigate browser to URL, get rendered page content (supports JS). Spanish: navegar a url, abrir página, sitio web",
+  description: "Navigate browser to URL, get rendered page content (supports JS). Returns compact accessibility tree with element refs (@e1, @e2) for interaction. Spanish: navegar a url, abrir página, sitio web",
   parameters: {
     type: "object",
     properties: {
@@ -30,6 +30,11 @@ export const browserNavigateTool: Tool = {
         type: "number",
         description: "Timeout in milliseconds (default: 30000)",
       },
+      mode: {
+        type: "string",
+        enum: ["snapshot", "text"],
+        description: "Content mode: 'snapshot' (compact accessibility tree with refs, default) or 'text' (full innerText). Use 'text' only if you need all readable text.",
+      },
     },
     required: ["url"],
   },
@@ -37,21 +42,22 @@ export const browserNavigateTool: Tool = {
     const url = params.url as string;
     const waitFor = params.waitFor as string | undefined;
     const timeout = (params.timeout as number) ?? 30000;
+    const mode = (params.mode as string) ?? "snapshot";
 
     const browserService = getBrowserService();
     if (!browserService?.isAvailable()) {
       log.warn("Browser not available");
       return {
         ok: false,
-        error: "Browser automation not available. Install Chrome/Chromium.",
+        error: "Browser automation not available. Install agent-browser.",
       };
     }
 
-    log.info(`Navigating: ${url}${waitFor ? ` (waiting for: ${waitFor})` : ""}`);
+    log.info(`Navigating: ${url}${waitFor ? ` (waiting for: ${waitFor})` : ""} [mode=${mode}]`);
 
     try {
       const view = await browserService.getView();
-      if (!view) return { ok: false, error: "Browser automation not available. Install Chrome/Chromium." };
+      if (!view) return { ok: false, error: "Browser automation not available. Install agent-browser." };
 
       await view.navigate(url);
 
@@ -67,28 +73,38 @@ export const browserNavigateTool: Tool = {
       }
 
       const finalUrl = view.url;
+      let content: string;
+      let contentType: string;
 
-      // Extraer texto limpio del DOM
-      const content = await view.evaluate(`
-        (() => {
-          try {
-            document.querySelectorAll("script, style, noscript, meta, link, iframe").forEach(el => el.remove());
-            let text = document.body?.innerText || document.documentElement?.innerText || "";
-            text = text.replace(/\\s+/g, " ").trim();
-            return text.slice(0, 50000);
-          } catch (e) {
-            return "Error extracting content: " + e.message;
-          }
-        })()
-      `) as string;
+      if (mode === "text") {
+        // Full innerText (legacy mode, heavy)
+        content = await view.evaluate(`
+          (() => {
+            try {
+              document.querySelectorAll("script, style, noscript, meta, link, iframe").forEach(el => el.remove());
+              let text = document.body?.innerText || document.documentElement?.innerText || "";
+              text = text.replace(/\\s+/g, " ").trim();
+              return text.slice(0, 50000);
+            } catch (e) {
+              return "Error extracting content: " + e.message;
+            }
+          })()
+        `) as string;
+        contentType = "text";
+      } else {
+        // Default: compact accessibility snapshot with refs
+        content = await view.snapshot({ compact: true, depth: 3 });
+        contentType = "snapshot";
+      }
 
-      log.info(`Navigation successful: ${finalUrl} (${content.length} chars)`);
+      log.info(`Navigation successful: ${finalUrl} (${content.length} chars, ${contentType})`);
 
       return {
         ok: true,
         url,
         finalUrl,
         content,
+        contentType,
         length: content.length,
       };
     } catch (error) {

package/packages/core/src/tools/web/browser-screenshot.ts

@@ -12,9 +12,12 @@ import { getBrowserService, screenshotElement } from "./browser-service.ts";
 
 const log = logger.child("browser-screenshot");
 
+// Default viewport for screenshots — keeps base64 small (~30-60KB vs ~300KB)
+const DEFAULT_VIEWPORT = { width: 1280, height: 720 };
+
 export const browserScreenshotTool: Tool = {
   name: "browser_screenshot",
-  description: "Take screenshot of current browser page. Spanish: captura de pantalla, screenshot, imagen de página",
+  description: "Take screenshot of current browser page. Returns JPEG by default for smaller size. Spanish: captura de pantalla, screenshot, imagen de página",
   parameters: {
     type: "object",
     properties: {
@@ -30,6 +33,23 @@ export const browserScreenshotTool: Tool = {
         type: "string",
         description: "CSS selector of specific element to screenshot (optional)",
       },
+      format: {
+        type: "string",
+        enum: ["jpeg", "png"],
+        description: "Image format: jpeg (default, smaller) or png (lossless, larger)",
+      },
+      quality: {
+        type: "number",
+        description: "JPEG quality 0-100 (default: 80). Ignored for PNG.",
+      },
+      width: {
+        type: "number",
+        description: "Viewport width in pixels (default: 1280). Smaller = smaller file.",
+      },
+      height: {
+        type: "number",
+        description: "Viewport height in pixels (default: 720). Smaller = smaller file.",
+      },
     },
     required: [],
   },
@@ -37,47 +57,59 @@ export const browserScreenshotTool: Tool = {
     const url = params.url as string | undefined;
     const fullPage = (params.fullPage as boolean) ?? false;
     const selector = params.selector as string | undefined;
+    const format = (params.format as string) ?? "jpeg";
+    const quality = (params.quality as number) ?? 80;
+    const width = (params.width as number) ?? DEFAULT_VIEWPORT.width;
+    const height = (params.height as number) ?? DEFAULT_VIEWPORT.height;
 
     const browserService = getBrowserService();
     if (!browserService?.isAvailable()) {
       log.warn("Browser not available");
       return {
         ok: false,
-        error: "Browser automation not available. Install Chrome/Chromium.",
+        error: "Browser automation not available. Install agent-browser.",
       };
     }
 
-    log.info(`Taking screenshot${url ? ` of: ${url}` : ""}${selector ? ` (element: ${selector})` : ""}`);
+    log.info(`Taking screenshot${url ? ` of: ${url}` : ""}${selector ? ` (element: ${selector})` : ""} [${format} ${width}x${height}]`);
 
     try {
       const view = await browserService.getView();
-      if (!view) return { ok: false, error: "Browser automation not available. Install Chrome/Chromium." };
+      if (!view) return { ok: false, error: "Browser automation not available. Install agent-browser." };
 
       if (url) {
         await view.navigate(url);
         await Bun.sleep(500);
       }
 
+      // Resize viewport before screenshot to keep image small
+      await view.resize(width, height);
+      await Bun.sleep(200);
+
       let screenshot: string;
 
       if (selector) {
         screenshot = await screenshotElement(view, selector);
       } else {
-        screenshot = await view.screenshot({ encoding: "base64", format: "png" });
+        screenshot = await view.screenshot({
+          encoding: "base64",
+          format: format as "jpeg" | "png" | "webp",
+          quality: format === "jpeg" ? quality : undefined,
+        });
       }
 
       const currentUrl = view.url;
-      log.info(`Screenshot captured: ${currentUrl} (${screenshot.length} base64 chars)`);
+      log.info(`Screenshot captured: ${currentUrl} (${screenshot.length} base64 chars, ${format})`);
 
       return {
         ok: true,
         url: currentUrl,
         screenshot,
-        format: "png",
+        format,
         encoding: "base64",
         fullPage,
         selector,
-        viewport: { width: 1280, height: 800 },
+        viewport: { width, height },
       };
     } catch (error) {
       log.error(`Screenshot failed: ${(error as Error).message}`);

package/packages/core/src/tools/web/browser-script.ts

@@ -43,7 +43,7 @@ export const browserScriptTool: Tool = {
       log.warn("Browser not available");
       return {
         ok: false,
-        error: "Browser automation not available. Install Chrome/Chromium.",
+        error: "Browser automation not available. Install agent-browser.",
       };
     }
 
@@ -51,7 +51,7 @@ export const browserScriptTool: Tool = {
 
     try {
       const view = await browserService.getView();
-      if (!view) return { ok: false, error: "Browser automation not available. Install Chrome/Chromium." };
+      if (!view) return { ok: false, error: "Browser automation not available. Install agent-browser." };
 
       if (url) {
         await view.navigate(url);

package/packages/core/src/tools/web/browser-service.test.ts

@@ -0,0 +1,83 @@
+import { describe, it, expect } from "bun:test";
+import {
+  AgentBrowserView,
+  BrowserService,
+  initializeBrowserService,
+  getBrowserService,
+  waitForSelector,
+  waitForCondition,
+} from "./browser-service.ts";
+import type { Config } from "../../config/loader.ts";
+
+describe("AgentBrowserView", () => {
+  it("has the expected API surface", () => {
+    const view = new AgentBrowserView("test-session");
+    expect(view.url).toBe("");
+    expect(typeof view.navigate).toBe("function");
+    expect(typeof view.evaluate).toBe("function");
+    expect(typeof view.click).toBe("function");
+    expect(typeof view.type).toBe("function");
+    expect(typeof view.typeIn).toBe("function");
+    expect(typeof view.fill).toBe("function");
+    expect(typeof view.press).toBe("function");
+    expect(typeof view.scroll).toBe("function");
+    expect(typeof view.scrollTo).toBe("function");
+    expect(typeof view.back).toBe("function");
+    expect(typeof view.forward).toBe("function");
+    expect(typeof view.reload).toBe("function");
+    expect(typeof view.resize).toBe("function");
+    expect(typeof view.screenshot).toBe("function");
+    expect(typeof view.snapshot).toBe("function");
+    expect(typeof view.cdp).toBe("function");
+    expect(typeof view.close).toBe("function");
+  });
+});
+
+describe("BrowserService singleton", () => {
+  it("initializes and returns the same instance", () => {
+    const config = { tools: { browser: { enabled: true, sessionName: "test" } } } as Config;
+    const service = initializeBrowserService(config);
+    expect(service).toBeInstanceOf(BrowserService);
+    expect(getBrowserService()).toBe(service);
+  });
+
+  it("exposes expected service methods", () => {
+    const config = { tools: { browser: { enabled: true, sessionName: "test" } } } as Config;
+    const service = BrowserService.getInstance(config);
+    expect(typeof service.start).toBe("function");
+    expect(typeof service.getView).toBe("function");
+    expect(typeof service.isAvailable).toBe("function");
+    expect(typeof service.stop).toBe("function");
+  });
+});
+
+describe("wait helpers", () => {
+  it("waitForSelector resolves when element appears", async () => {
+    let found = false;
+    const view = {
+      evaluate: async (script: string) => {
+        if (script.includes("document.querySelector")) {
+          found = true;
+          return true;
+        }
+        return false;
+      },
+    } as unknown as AgentBrowserView;
+
+    await waitForSelector(view, "#test", 1000);
+    expect(found).toBe(true);
+  });
+
+  it("waitForCondition resolves when expression is truthy", async () => {
+    let calls = 0;
+    const view = {
+      evaluate: async () => {
+        calls++;
+        return calls >= 2;
+      },
+    } as unknown as AgentBrowserView;
+
+    await waitForCondition(view, "window.ready", 1000);
+    expect(calls).toBeGreaterThanOrEqual(2);
+  });
+});