@johpaz/hive-sdk 0.0.12 → 0.0.15

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

@@ -0,0 +1,136 @@
+/**
+ * browser_wait - Wait for element or condition on page
+ *
+ * @category web
+ * @seedId browser_wait
+ * @spanish esperar, wait, condición, elemento, selector
+ */
+
+import type { Tool } from "../types.ts";
+import { logger } from "../../utils/logger.ts";
+import { getBrowserService, waitForSelector, waitForCondition } from "./browser-service.ts";
+
+const log = logger.child("browser-wait");
+
+export const browserWaitTool: Tool = {
+  name: "browser_wait",
+  description: "Wait for an element to appear or condition to be met on the page. Spanish: esperar, wait, condición, elemento, selector",
+  parameters: {
+    type: "object",
+    properties: {
+      url: {
+        type: "string",
+        description: "URL to navigate to before waiting (optional)",
+      },
+      selector: {
+        type: "string",
+        description: "CSS selector to wait for (optional if condition provided)",
+      },
+      condition: {
+        type: "string",
+        description: "JavaScript expression to evaluate (optional if selector provided)",
+      },
+      timeout: {
+        type: "number",
+        description: "Timeout in milliseconds (default: 30000)",
+      },
+      state: {
+        type: "string",
+        description: "Element state: visible, hidden, attached (default: visible)",
+        enum: ["visible", "hidden", "attached"],
+      },
+    },
+    required: [],
+  },
+  execute: async (params: Record<string, unknown>) => {
+    const url = params.url as string | undefined;
+    const selector = params.selector as string | undefined;
+    const condition = params.condition as string | undefined;
+    const timeout = (params.timeout as number) ?? 30000;
+    const state = (params.state as string) ?? "visible";
+
+    const browserService = getBrowserService();
+    if (!browserService?.isAvailable()) {
+      log.warn("Browser not available");
+      return {
+        ok: false,
+        error: "Browser automation not available. Install Chrome/Chromium.",
+      };
+    }
+
+    if (!selector && !condition) {
+      return {
+        ok: false,
+        error: "Either 'selector' or 'condition' must be provided",
+      };
+    }
+
+    log.info(`Waiting${selector ? ` for selector: ${selector}` : ""}${condition ? ` for condition: ${condition}` : ""}${url ? ` on ${url}` : ""}`);
+
+    try {
+      const view = await browserService.getView();
+      if (!view) return { ok: false, error: "Browser automation not available. Install Chrome/Chromium." };
+
+      if (url) {
+        await view.navigate(url);
+        await Bun.sleep(500);
+      }
+
+      const startTime = Date.now();
+      let found = false;
+
+      if (selector) {
+        const isXPath = selector.startsWith("xpath:");
+        const actualSelector = isXPath ? selector.slice(6) : selector;
+
+        try {
+          if (isXPath) {
+            const xpathExpr = `(() => {
+              const r = document.evaluate(
+                ${JSON.stringify(actualSelector)}, document, null,
+                XPathResult.FIRST_ORDERED_NODE_TYPE, null
+              );
+              return r.singleNodeValue !== null;
+            })()`;
+            await waitForCondition(view, xpathExpr, timeout);
+          } else {
+            await waitForSelector(view, actualSelector, timeout);
+          }
+          found = true;
+        } catch {
+          log.warn(`Selector "${actualSelector}" not found within ${timeout}ms`);
+        }
+      }
+
+      if (condition) {
+        try {
+          await waitForCondition(view, condition, timeout);
+          found = true;
+        } catch {
+          log.warn(`Condition not met within ${timeout}ms`);
+        }
+      }
+
+      const elapsed = Date.now() - startTime;
+      const currentUrl = view.url;
+
+      log.info(`Wait completed in ${elapsed}ms on ${currentUrl} (found=${found})`);
+
+      return {
+        ok: true,
+        found,
+        url: currentUrl,
+        selector,
+        condition,
+        state,
+        elapsedMs: elapsed,
+      };
+    } catch (error) {
+      log.error(`Wait failed: ${(error as Error).message}`);
+      return {
+        ok: false,
+        error: `Failed to wait: ${(error as Error).message}`,
+      };
+    }
+  },
+};

package/packages/core/src/tools/web/index.ts

@@ -0,0 +1,41 @@
+/**
+ * Web Tools - Browser automation + Web utilities
+ * 
+ * Browser tools use Puppeteer/Chromium (auto-managed).
+ */
+
+import type { Tool } from "../types.ts";
+import { webSearchTool } from "./web-search.ts";
+import { webFetchTool } from "./web-fetch.ts";
+import { browserNavigateTool } from "./browser-navigate.ts";
+import { browserScreenshotTool } from "./browser-screenshot.ts";
+import { browserClickTool } from "./browser-click.ts";
+import { browserTypeTool } from "./browser-type.ts";
+import { browserExtractTool } from "./browser-extract.ts";
+import { browserScriptTool } from "./browser-script.ts";
+import { browserWaitTool } from "./browser-wait.ts";
+
+export function createTools(): Tool[] {
+  return [
+    webSearchTool,
+    webFetchTool,
+    browserNavigateTool,
+    browserScreenshotTool,
+    browserClickTool,
+    browserTypeTool,
+    browserExtractTool,
+    browserScriptTool,
+    browserWaitTool,
+  ];
+}
+
+export * from "./web-search.ts";
+export * from "./web-fetch.ts";
+export * from "./browser-navigate.ts";
+export * from "./browser-screenshot.ts";
+export * from "./browser-click.ts";
+export * from "./browser-type.ts";
+export * from "./browser-extract.ts";
+export * from "./browser-script.ts";
+export * from "./browser-wait.ts";
+export * from "./browser-service.ts";

package/packages/core/src/tools/web/web-fetch.ts

@@ -0,0 +1,78 @@
+/**
+ * web_fetch - Fetch plain content from a URL
+ * 
+ * @category web
+ * @seedId web_fetch
+ * @spanish obtener página, descargar contenido, extraer texto de url
+ */
+
+import type { Tool } from "../types.ts";
+import { logger } from "../../utils/logger.ts";
+
+const log = logger.child("web-fetch");
+
+export const webFetchTool: Tool = {
+  name: "web_fetch",
+  description: "Fetch plain content from a URL (lightweight, no JS). Spanish: obtener página, descargar contenido, extraer texto de url",
+  parameters: {
+    type: "object",
+    properties: {
+      url: {
+        type: "string",
+        description: "The URL to fetch content from",
+      },
+    },
+    required: ["url"],
+  },
+  execute: async (params: Record<string, unknown>) => {
+    const url = params.url as string;
+
+    log.info(`Fetching: ${url}`);
+
+    try {
+      const response = await fetch(url, {
+        headers: {
+          "User-Agent": "Mozilla/5.0 (compatible; HiveBot/1.0)",
+        },
+      });
+
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+
+      const contentType = response.headers.get("content-type") || "";
+      let content: string;
+
+      if (contentType.includes("application/json")) {
+        const json = await response.json();
+        content = JSON.stringify(json, null, 2);
+      } else if (contentType.includes("text/html")) {
+        const html = await response.text();
+        // Strip HTML tags
+        content = html
+          .replace(/<script[^>]*>[\s\S]*?<\/script>/gi, "")
+          .replace(/<style[^>]*>[\s\S]*?<\/style>/gi, "")
+          .replace(/<[^>]+>/g, " ")
+          .replace(/\s+/g, " ")
+          .trim()
+          .slice(0, 50000);
+      } else {
+        content = await response.text();
+      }
+
+      return {
+        ok: true,
+        url,
+        content,
+        contentType,
+        length: content.length,
+      };
+    } catch (error) {
+      log.error(`Fetch failed: ${(error as Error).message}`);
+      return {
+        ok: false,
+        error: `Failed to fetch URL: ${(error as Error).message}`,
+      };
+    }
+  },
+};

package/packages/core/src/tools/web/web-search.ts

@@ -0,0 +1,123 @@
+/**
+ * web_search - Search the web for current information
+ *
+ * @category web
+ * @seedId web_search
+ * @spanish buscar en internet, búsqueda web, noticias, información
+ */
+
+import type { Tool } from "../types.ts";
+import { logger } from "../../utils/logger.ts";
+
+const log = logger.child("web-search");
+
+const TIMEOUT_MS = 10_000;
+
+interface SearchResult {
+  title: string;
+  url: string;
+  snippet: string;
+}
+
+function decodeUddg(href: string): string {
+  try {
+    const uddg = new URL("https:" + href).searchParams.get("uddg");
+    return uddg ? decodeURIComponent(uddg) : href;
+  } catch {
+    return href;
+  }
+}
+
+function isAdUrl(url: string): boolean {
+  return url.includes("duckduckgo.com/y.js") || url.includes("ad_provider") || url.includes("ad_domain");
+}
+
+async function searchDuckDuckGo(query: string, numResults: number): Promise<SearchResult[]> {
+  const searchUrl = `https://html.duckduckgo.com/html/?q=${encodeURIComponent(query)}`;
+
+  log.info(`Requesting DuckDuckGo HTML: ${searchUrl}`);
+
+  const response = await fetch(searchUrl, {
+    signal: AbortSignal.timeout(TIMEOUT_MS),
+    headers: {
+      "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
+    },
+  });
+
+  if (!response.ok) {
+    throw new Error(`DuckDuckGo request failed: ${response.status}`);
+  }
+
+  const html = await response.text();
+
+  // Extract links: href contains //duckduckgo.com/l/?uddg=ENCODED_URL
+  const hrefs = [...html.matchAll(/<a[^>]+class="result__a"[^>]*href="([^"]+)"/g)].map((m) => m[1]);
+  const titles = [...html.matchAll(/<a[^>]+class="result__a"[^>]*>([^<]+)<\/a>/g)].map((m) => m[1].trim());
+  const rawSnippets = [...html.matchAll(/class="result__snippet"[^>]*>([\s\S]{0,400}?)<\/a>/g)].map((m) =>
+    m[1].replace(/<[^>]+>/g, "").trim()
+  );
+
+  log.debug(`DDG parsed: ${hrefs.length} links, ${titles.length} titles, ${rawSnippets.length} snippets`);
+
+  const results: SearchResult[] = [];
+  let snippetIdx = 0;
+
+  for (let i = 0; i < hrefs.length && results.length < numResults; i++) {
+    const rawUrl = hrefs[i] ?? "";
+    const url = decodeUddg(rawUrl);
+
+    // Skip ads
+    if (isAdUrl(url) || isAdUrl(rawUrl)) {
+      snippetIdx++; // ads also consume a snippet slot
+      continue;
+    }
+
+    // Advance snippet index past ads
+    while (snippetIdx < rawSnippets.length && isAdUrl(rawSnippets[snippetIdx] ?? "")) {
+      snippetIdx++;
+    }
+
+    results.push({
+      title: titles[i] ?? url,
+      url,
+      snippet: rawSnippets[snippetIdx] ?? "",
+    });
+    snippetIdx++;
+  }
+
+  return results;
+}
+
+export const webSearchTool: Tool = {
+  name: "web_search",
+  description: "Search the web for current information and research. Spanish: buscar en internet, búsqueda web, noticias, información",
+  parameters: {
+    type: "object",
+    properties: {
+      query: {
+        type: "string",
+        description: "The search query - be specific and include relevant keywords",
+      },
+      numResults: {
+        type: "number",
+        description: "Number of results to return (default: 5, max: 10)",
+      },
+    },
+    required: ["query"],
+  },
+  execute: async (params: Record<string, unknown>) => {
+    const query = params.query as string;
+    const numResults = Math.min((params.numResults as number) ?? 5, 10);
+
+    log.info(`Web search: "${query}"`);
+
+    try {
+      const results = await searchDuckDuckGo(query, numResults);
+      log.info(`Web search returned ${results.length} results for "${query}"`);
+      return { ok: true, results, query, count: results.length };
+    } catch (error) {
+      log.error(`Search failed: ${(error as Error).message}`);
+      return { ok: false, error: `Web search failed: ${(error as Error).message}` };
+    }
+  },
+};

package/packages/core/src/utils/benchmark.ts

@@ -0,0 +1,80 @@
+/**
+ * Utility for measuring resource usage (time and memory).
+ */
+export class Benchmark {
+    private startTime: number = 0;
+    private startMem: NodeJS.MemoryUsage | null = null;
+    private name: string;
+
+    constructor(name: string = "Benchmark") {
+        this.name = name;
+    }
+
+    /**
+     * Starts the benchmark timer and records initial memory usage.
+     */
+    start() {
+        this.startTime = performance.now();
+        this.startMem = process.memoryUsage();
+        return this;
+    }
+
+    /**
+     * Stops the benchmark and returns the metrics.
+     */
+    stop() {
+        const endTime = performance.now();
+        const endMem = process.memoryUsage();
+        const duration = endTime - this.startTime;
+
+        const metrics = {
+            name: this.name,
+            durationMs: duration.toFixed(2),
+            heapUsed: this.formatMB(endMem.heapUsed),
+            heapTotal: this.formatMB(endMem.heapTotal),
+            rss: this.formatMB(endMem.rss),
+            external: this.formatMB(endMem.external),
+            heapDelta: this.startMem
+                ? this.formatMB(endMem.heapUsed - this.startMem.heapUsed)
+                : "0.00 MB",
+            raw: {
+                duration,
+                memory: endMem,
+                delta: this.startMem
+                    ? endMem.heapUsed - this.startMem.heapUsed
+                    : 0
+            }
+        };
+
+        return metrics;
+    }
+
+    /**
+     * Pretty-prints the benchmark results to the console.
+     */
+    print() {
+        const m = this.stop();
+        console.log(`\n📊 Benchmark: ${m.name}`);
+        console.table({
+            'Time': `${m.durationMs} ms`,
+            'Heap Used': m.heapUsed,
+            'Heap Total': m.heapTotal,
+            'RSS': m.rss,
+            'External': m.external,
+            'Memory Delta': m.heapDelta
+        });
+    }
+
+    private formatMB(bytes: number) {
+        return `${(bytes / 1024 / 1024).toFixed(2)} MB`;
+    }
+
+    /**
+     * static helper for quick one-off benchmarks.
+     */
+    static async run(name: string, fn: () => Promise<any> | any) {
+        const b = new Benchmark(name).start();
+        await fn();
+        b.print();
+    }
+}

package/packages/core/src/utils/crypto.ts

@@ -0,0 +1,73 @@
+import * as crypto from "node:crypto";
+
+export function generateId(): string {
+  return crypto.randomUUID();
+}
+
+export function generateShortId(length = 8): string {
+  const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
+  let result = "";
+  const randomBytes = crypto.randomBytes(length);
+  
+  for (let i = 0; i < length; i++) {
+    result += chars[randomBytes[i]! % chars.length];
+  }
+  
+  return result;
+}
+
+export function hashString(input: string): string {
+  return crypto.createHash("sha256").update(input).digest("hex");
+}
+
+export function hashObject(obj: unknown): string {
+  return hashString(JSON.stringify(obj));
+}
+
+export async function hmacSign(
+  key: string,
+  data: string,
+  algorithm: "sha256" | "sha512" = "sha256"
+): Promise<string> {
+  return crypto.createHmac(algorithm, key).update(data).digest("hex");
+}
+
+export async function hmacVerify(
+  key: string,
+  data: string,
+  signature: string,
+  algorithm: "sha256" | "sha512" = "sha256"
+): Promise<boolean> {
+  const expected = await hmacSign(key, data, algorithm);
+  return crypto.timingSafeEqual(
+    Buffer.from(expected),
+    Buffer.from(signature)
+  );
+}
+
+export function encrypt(text: string, key: string): string {
+  const iv = crypto.randomBytes(16);
+  const derivedKey = crypto.scryptSync(key, "salt", 32);
+  const cipher = crypto.createCipheriv("aes-256-cbc", derivedKey, iv);
+  
+  let encrypted = cipher.update(text, "utf8", "hex");
+  encrypted += cipher.final("hex");
+  
+  return iv.toString("hex") + ":" + encrypted;
+}
+
+export function decrypt(encryptedData: string, key: string): string {
+  const [ivHex, encrypted] = encryptedData.split(":");
+  if (!ivHex || !encrypted) {
+    throw new Error("Invalid encrypted data format");
+  }
+  
+  const iv = Buffer.from(ivHex, "hex");
+  const derivedKey = crypto.scryptSync(key, "salt", 32);
+  const decipher = crypto.createDecipheriv("aes-256-cbc", derivedKey, iv);
+  
+  let decrypted = decipher.update(encrypted, "hex", "utf8");
+  decrypted += decipher.final("utf8");
+  
+  return decrypted;
+}

package/packages/core/src/utils/date.ts

@@ -0,0 +1,42 @@
+/**
+ * Utility functions for user-specific date and time formatting.
+ */
+
+export function getUserDate(timezone: string = "UTC", date: Date = new Date()): string {
+    try {
+        const formatter = new Intl.DateTimeFormat("en-GB", {
+            timeZone: timezone,
+            year: "numeric",
+            month: "2-digit",
+            day: "2-digit",
+        });
+        const parts = formatter.formatToParts(date);
+        const year = parts.find(p => p.type === "year")?.value;
+        const month = parts.find(p => p.type === "month")?.value;
+        const day = parts.find(p => p.type === "day")?.value;
+        return `${year}-${month}-${day}`;
+    } catch (e) {
+        // Fallback to UTC if timezone is invalid
+        return date.toISOString().split("T")[0];
+    }
+}
+
+export function getUserTime(timezone: string = "UTC", date: Date = new Date()): string {
+    try {
+        const formatter = new Intl.DateTimeFormat("en-GB", {
+            timeZone: timezone,
+            hour: "2-digit",
+            minute: "2-digit",
+            second: "2-digit",
+            hour12: false,
+        });
+        const parts = formatter.formatToParts(date);
+        const hour = parts.find(p => p.type === "hour")?.value;
+        const minute = parts.find(p => p.type === "minute")?.value;
+        const second = parts.find(p => p.type === "second")?.value;
+        return `${hour}:${minute}:${second}`;
+    } catch (e) {
+        // Fallback if formatting fails
+        return date.toISOString().split("T")[1].split(".")[0];
+    }
+}

package/packages/core/src/utils/index.ts

@@ -0,0 +1,10 @@
+export type { LogLevel, LogEntry, LogEntryListener, LoggerConfig, LogMeta } from "./logger.ts";
+export { logger, onLogEntry, removeLogListener } from "./logger.ts";
+export type { RetryOptions } from "./retry.ts";
+export { sleep, retry, retryWithBackoff } from "./retry.ts";
+export { generateId, generateShortId, hashString, hashObject, hmacSign, hmacVerify } from "./crypto.ts";
+export { encrypt as utilsEncrypt, decrypt as utilsDecrypt } from "./crypto.ts";
+export { Benchmark } from "./benchmark.ts";
+export { getUserDate, getUserTime } from "./date.ts";
+export type { ToonStringifyResult } from "./toon.ts";
+export { estimateTokens, stringify, formatToolResult, formatMCPResponse, formatSkillOutput, formatContext, withToonFormat, reportCompression, getCompressionAnalysis } from "./toon.ts";