browsy-ai 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,70 @@
+import type { BrowsyResponse } from "./types.js";
+/**
+ * HTTP client for the browsy REST API.
+ * Uses Node.js built-in fetch(). Passes and extracts X-Browsy-Session header.
+ */
+export declare class BrowsyClient {
+    private baseUrl;
+    constructor(port: number);
+    /** GET /health */
+    health(): Promise<BrowsyResponse>;
+    /** POST /api/browse */
+    browse(params: {
+        url: string;
+        format?: string;
+        scope?: string;
+    }, session?: string): Promise<BrowsyResponse>;
+    /** POST /api/click */
+    click(params: {
+        id: number;
+    }, session?: string): Promise<BrowsyResponse>;
+    /** POST /api/type */
+    typeText(params: {
+        id: number;
+        text: string;
+    }, session?: string): Promise<BrowsyResponse>;
+    /** POST /api/check */
+    check(params: {
+        id: number;
+    }, session?: string): Promise<BrowsyResponse>;
+    /** POST /api/uncheck */
+    uncheck(params: {
+        id: number;
+    }, session?: string): Promise<BrowsyResponse>;
+    /** POST /api/select */
+    select(params: {
+        id: number;
+        value: string;
+    }, session?: string): Promise<BrowsyResponse>;
+    /** POST /api/search */
+    search(params: {
+        query: string;
+        engine?: string;
+    }, session?: string): Promise<BrowsyResponse>;
+    /** POST /api/login */
+    login(params: {
+        username: string;
+        password: string;
+    }, session?: string): Promise<BrowsyResponse>;
+    /** POST /api/enter-code */
+    enterCode(params: {
+        code: string;
+    }, session?: string): Promise<BrowsyResponse>;
+    /** POST /api/find */
+    find(params: {
+        text?: string;
+        role?: string;
+    }, session?: string): Promise<BrowsyResponse>;
+    /** GET /api/page */
+    getPage(params?: {
+        format?: string;
+        scope?: string;
+    }, session?: string): Promise<BrowsyResponse>;
+    /** GET /api/page-info */
+    pageInfo(session?: string): Promise<BrowsyResponse>;
+    /** GET /api/tables */
+    tables(session?: string): Promise<BrowsyResponse>;
+    /** POST /api/back */
+    back(session?: string): Promise<BrowsyResponse>;
+    private request;
+}

package/dist/client.js

@@ -0,0 +1,109 @@
+/**
+ * HTTP client for the browsy REST API.
+ * Uses Node.js built-in fetch(). Passes and extracts X-Browsy-Session header.
+ */
+export class BrowsyClient {
+    baseUrl;
+    constructor(port) {
+        this.baseUrl = `http://127.0.0.1:${port}`;
+    }
+    /** GET /health */
+    async health() {
+        return this.request("GET", "/health");
+    }
+    /** POST /api/browse */
+    async browse(params, session) {
+        return this.request("POST", "/api/browse", params, session);
+    }
+    /** POST /api/click */
+    async click(params, session) {
+        return this.request("POST", "/api/click", params, session);
+    }
+    /** POST /api/type */
+    async typeText(params, session) {
+        return this.request("POST", "/api/type", params, session);
+    }
+    /** POST /api/check */
+    async check(params, session) {
+        return this.request("POST", "/api/check", params, session);
+    }
+    /** POST /api/uncheck */
+    async uncheck(params, session) {
+        return this.request("POST", "/api/uncheck", params, session);
+    }
+    /** POST /api/select */
+    async select(params, session) {
+        return this.request("POST", "/api/select", params, session);
+    }
+    /** POST /api/search */
+    async search(params, session) {
+        return this.request("POST", "/api/search", params, session);
+    }
+    /** POST /api/login */
+    async login(params, session) {
+        return this.request("POST", "/api/login", params, session);
+    }
+    /** POST /api/enter-code */
+    async enterCode(params, session) {
+        return this.request("POST", "/api/enter-code", params, session);
+    }
+    /** POST /api/find */
+    async find(params, session) {
+        return this.request("POST", "/api/find", params, session);
+    }
+    /** GET /api/page */
+    async getPage(params, session) {
+        const query = new URLSearchParams();
+        if (params?.format)
+            query.set("format", params.format);
+        if (params?.scope)
+            query.set("scope", params.scope);
+        const qs = query.toString();
+        return this.request("GET", `/api/page${qs ? `?${qs}` : ""}`, undefined, session);
+    }
+    /** GET /api/page-info */
+    async pageInfo(session) {
+        return this.request("GET", "/api/page-info", undefined, session);
+    }
+    /** GET /api/tables */
+    async tables(session) {
+        return this.request("GET", "/api/tables", undefined, session);
+    }
+    /** POST /api/back */
+    async back(session) {
+        return this.request("POST", "/api/back", undefined, session);
+    }
+    // ---------------------------------------------------------------------------
+    // Internal
+    // ---------------------------------------------------------------------------
+    async request(method, path, body, session) {
+        const headers = {};
+        if (session) {
+            headers["X-Browsy-Session"] = session;
+        }
+        if (body !== undefined) {
+            headers["Content-Type"] = "application/json";
+        }
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            method,
+            headers,
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        const responseSession = res.headers.get("X-Browsy-Session") ?? session ?? "";
+        const text = await res.text();
+        let json;
+        try {
+            json = JSON.parse(text);
+        }
+        catch {
+            // Response is plain text, not JSON
+        }
+        return {
+            ok: res.ok,
+            status: res.status,
+            session: responseSession,
+            body: text,
+            json,
+        };
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,6 @@
+import type { BrowsyConfig, BrowsyConfigInput } from "./types.js";
+export declare function defaultConfig(): BrowsyConfig;
+/**
+ * Merge partial user input onto defaults, producing a complete BrowsyConfig.
+ */
+export declare function parseConfig(input?: BrowsyConfigInput): BrowsyConfig;

package/dist/config.js

@@ -0,0 +1,28 @@
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+export function defaultConfig() {
+    return {
+        port: 3847,
+        autoStart: true,
+        allowPrivateNetwork: false,
+        serverTimeout: 10_000,
+    };
+}
+// ---------------------------------------------------------------------------
+// Config parsing
+// ---------------------------------------------------------------------------
+/**
+ * Merge partial user input onto defaults, producing a complete BrowsyConfig.
+ */
+export function parseConfig(input) {
+    const base = defaultConfig();
+    if (!input)
+        return base;
+    return {
+        port: input.port ?? base.port,
+        autoStart: input.autoStart ?? base.autoStart,
+        allowPrivateNetwork: input.allowPrivateNetwork ?? base.allowPrivateNetwork,
+        serverTimeout: input.serverTimeout ?? base.serverTimeout,
+    };
+}

package/dist/context.d.ts

@@ -0,0 +1,27 @@
+import type { BrowsyConfigInput, BrowsyServerInfo } from "./types.js";
+import { BrowsyClient } from "./client.js";
+import { ServerManager } from "./server-manager.js";
+import { SessionManager } from "./session-manager.js";
+import type { BrowsyConfig } from "./types.js";
+/**
+ * Central facade holding config, client, server manager, and session manager.
+ * One instance per SDK lifetime.
+ */
+export declare class BrowsyContext {
+    readonly config: BrowsyConfig;
+    readonly client: BrowsyClient;
+    readonly serverManager: ServerManager;
+    readonly sessionManager: SessionManager;
+    /** Agent ID to use when no agent context is available */
+    private defaultAgentId;
+    constructor(configInput?: BrowsyConfigInput);
+    /** Ensure the browsy server is running. */
+    ensureServer(): Promise<void>;
+    /** Get current server status. */
+    getStatus(): BrowsyServerInfo;
+    /**
+     * Execute a browsy tool call.
+     * Ensures server is running, manages sessions, calls the client, and returns results.
+     */
+    executeToolCall(method: string, params: Record<string, unknown>, agentId?: string): Promise<string>;
+}

package/dist/context.js

@@ -0,0 +1,100 @@
+import { parseConfig } from "./config.js";
+import { BrowsyClient } from "./client.js";
+import { ServerManager } from "./server-manager.js";
+import { SessionManager } from "./session-manager.js";
+/**
+ * Central facade holding config, client, server manager, and session manager.
+ * One instance per SDK lifetime.
+ */
+export class BrowsyContext {
+    config;
+    client;
+    serverManager;
+    sessionManager;
+    /** Agent ID to use when no agent context is available */
+    defaultAgentId = "__default__";
+    constructor(configInput) {
+        this.config = parseConfig(configInput);
+        this.client = new BrowsyClient(this.config.port);
+        this.serverManager = new ServerManager(this.config);
+        this.sessionManager = new SessionManager();
+    }
+    /** Ensure the browsy server is running. */
+    async ensureServer() {
+        if (!this.serverManager.isRunning()) {
+            await this.serverManager.start();
+        }
+    }
+    /** Get current server status. */
+    getStatus() {
+        return this.serverManager.getStatus();
+    }
+    /**
+     * Execute a browsy tool call.
+     * Ensures server is running, manages sessions, calls the client, and returns results.
+     */
+    async executeToolCall(method, params, agentId) {
+        await this.ensureServer();
+        const aid = agentId ?? this.defaultAgentId;
+        const session = this.sessionManager.getOrCreate(aid);
+        const token = session.token || undefined;
+        let response;
+        switch (method) {
+            case "browse":
+                response = await this.client.browse(params, token);
+                break;
+            case "click":
+                response = await this.client.click(params, token);
+                break;
+            case "typeText":
+                response = await this.client.typeText(params, token);
+                break;
+            case "check":
+                response = await this.client.check(params, token);
+                break;
+            case "uncheck":
+                response = await this.client.uncheck(params, token);
+                break;
+            case "select":
+                response = await this.client.select(params, token);
+                break;
+            case "search":
+                response = await this.client.search(params, token);
+                break;
+            case "login":
+                response = await this.client.login(params, token);
+                break;
+            case "enterCode":
+                response = await this.client.enterCode(params, token);
+                break;
+            case "find":
+                response = await this.client.find(params, token);
+                break;
+            case "pageInfo":
+                response = await this.client.pageInfo(token);
+                break;
+            case "tables":
+                response = await this.client.tables(token);
+                break;
+            case "getPage":
+                response = await this.client.getPage(params, token);
+                break;
+            case "back":
+                response = await this.client.back(token);
+                break;
+            default:
+                throw new Error(`Unknown browsy method: ${method}`);
+        }
+        // Update session token from response
+        if (response.session) {
+            this.sessionManager.update(aid, response.session);
+        }
+        // Return error message on failure, body on success
+        let result = response.body;
+        if (!response.ok) {
+            const errorJson = response.json;
+            result = errorJson?.error ?? response.body;
+        }
+        return result;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { BrowsyClient } from "./client.js";
+export { ServerManager } from "./server-manager.js";
+export { SessionManager } from "./session-manager.js";
+export { BrowsyContext } from "./context.js";
+export { defaultConfig, parseConfig } from "./config.js";
+export { isPortInUse, findBrowsyBinary } from "./process.js";
+export type { BrowsyConfig, BrowsyConfigInput, BrowsyResponse, BrowsyServerStatus, BrowsyServerInfo, BrowsySession, } from "./types.js";
+export { BrowseParams, ClickParams, TypeTextParams, CheckParams, UncheckParams, SelectParams, SearchParams, LoginParams, EnterCodeParams, FindParams, GetPageParams, PageInfoParams, TablesParams, BackParams, TOOL_DESCRIPTIONS, TOOL_SCHEMAS, } from "./schemas.js";

package/dist/index.js

@@ -0,0 +1,9 @@
+// Core SDK
+export { BrowsyClient } from "./client.js";
+export { ServerManager } from "./server-manager.js";
+export { SessionManager } from "./session-manager.js";
+export { BrowsyContext } from "./context.js";
+export { defaultConfig, parseConfig } from "./config.js";
+export { isPortInUse, findBrowsyBinary } from "./process.js";
+// Schemas
+export { BrowseParams, ClickParams, TypeTextParams, CheckParams, UncheckParams, SelectParams, SearchParams, LoginParams, EnterCodeParams, FindParams, GetPageParams, PageInfoParams, TablesParams, BackParams, TOOL_DESCRIPTIONS, TOOL_SCHEMAS, } from "./schemas.js";

package/dist/langchain.d.ts

@@ -0,0 +1,157 @@
+import { BrowsyContext } from "./context.js";
+import type { BrowsyConfigInput } from "./types.js";
+/**
+ * Returns an array of 14 LangChain tool instances for all browsy operations.
+ * Lazily initializes a default BrowsyContext if none is provided.
+ */
+export declare function getTools(ctx?: BrowsyContext | BrowsyConfigInput): import("@langchain/core/tools").DynamicStructuredTool<import("zod").ZodObject<{
+    url: import("zod").ZodString;
+    format: import("zod").ZodOptional<import("zod").ZodString>;
+    scope: import("zod").ZodOptional<import("zod").ZodString>;
+}, "strip", import("zod").ZodTypeAny, {
+    url: string;
+    format?: string | undefined;
+    scope?: string | undefined;
+}, {
+    url: string;
+    format?: string | undefined;
+    scope?: string | undefined;
+}> | import("zod").ZodObject<{
+    id: import("zod").ZodNumber;
+}, "strip", import("zod").ZodTypeAny, {
+    id: number;
+}, {
+    id: number;
+}> | import("zod").ZodObject<{
+    id: import("zod").ZodNumber;
+    text: import("zod").ZodString;
+}, "strip", import("zod").ZodTypeAny, {
+    id: number;
+    text: string;
+}, {
+    id: number;
+    text: string;
+}> | import("zod").ZodObject<{
+    id: import("zod").ZodNumber;
+}, "strip", import("zod").ZodTypeAny, {
+    id: number;
+}, {
+    id: number;
+}> | import("zod").ZodObject<{
+    id: import("zod").ZodNumber;
+}, "strip", import("zod").ZodTypeAny, {
+    id: number;
+}, {
+    id: number;
+}> | import("zod").ZodObject<{
+    id: import("zod").ZodNumber;
+    value: import("zod").ZodString;
+}, "strip", import("zod").ZodTypeAny, {
+    id: number;
+    value: string;
+}, {
+    id: number;
+    value: string;
+}> | import("zod").ZodObject<{
+    query: import("zod").ZodString;
+    engine: import("zod").ZodOptional<import("zod").ZodString>;
+}, "strip", import("zod").ZodTypeAny, {
+    query: string;
+    engine?: string | undefined;
+}, {
+    query: string;
+    engine?: string | undefined;
+}> | import("zod").ZodObject<{
+    username: import("zod").ZodString;
+    password: import("zod").ZodString;
+}, "strip", import("zod").ZodTypeAny, {
+    username: string;
+    password: string;
+}, {
+    username: string;
+    password: string;
+}> | import("zod").ZodObject<{
+    code: import("zod").ZodString;
+}, "strip", import("zod").ZodTypeAny, {
+    code: string;
+}, {
+    code: string;
+}> | import("zod").ZodObject<{
+    text: import("zod").ZodOptional<import("zod").ZodString>;
+    role: import("zod").ZodOptional<import("zod").ZodString>;
+}, "strip", import("zod").ZodTypeAny, {
+    text?: string | undefined;
+    role?: string | undefined;
+}, {
+    text?: string | undefined;
+    role?: string | undefined;
+}> | import("zod").ZodObject<{
+    format: import("zod").ZodOptional<import("zod").ZodString>;
+    scope: import("zod").ZodOptional<import("zod").ZodString>;
+}, "strip", import("zod").ZodTypeAny, {
+    format?: string | undefined;
+    scope?: string | undefined;
+}, {
+    format?: string | undefined;
+    scope?: string | undefined;
+}> | import("zod").ZodObject<{}, "strip", import("zod").ZodTypeAny, {}, {}> | import("zod").ZodObject<{}, "strip", import("zod").ZodTypeAny, {}, {}> | import("zod").ZodObject<{}, "strip", import("zod").ZodTypeAny, {}, {}>, {
+    url: string;
+    format?: string | undefined;
+    scope?: string | undefined;
+} | {
+    id: number;
+} | {
+    id: number;
+    text: string;
+} | {
+    id: number;
+} | {
+    id: number;
+} | {
+    id: number;
+    value: string;
+} | {
+    query: string;
+    engine?: string | undefined;
+} | {
+    username: string;
+    password: string;
+} | {
+    code: string;
+} | {
+    text?: string | undefined;
+    role?: string | undefined;
+} | {
+    format?: string | undefined;
+    scope?: string | undefined;
+} | {} | {} | {}, {
+    url: string;
+    format?: string | undefined;
+    scope?: string | undefined;
+} | {
+    id: number;
+} | {
+    id: number;
+    text: string;
+} | {
+    id: number;
+} | {
+    id: number;
+} | {
+    id: number;
+    value: string;
+} | {
+    query: string;
+    engine?: string | undefined;
+} | {
+    username: string;
+    password: string;
+} | {
+    code: string;
+} | {
+    text?: string | undefined;
+    role?: string | undefined;
+} | {
+    format?: string | undefined;
+    scope?: string | undefined;
+} | {} | {} | {}, string>[];

package/dist/langchain.js

@@ -0,0 +1,26 @@
+import { tool } from "@langchain/core/tools";
+import { BrowsyContext } from "./context.js";
+import { TOOL_SCHEMAS, TOOL_DESCRIPTIONS } from "./schemas.js";
+let defaultContext;
+function getDefaultContext() {
+    if (!defaultContext) {
+        defaultContext = new BrowsyContext();
+    }
+    return defaultContext;
+}
+/**
+ * Returns an array of 14 LangChain tool instances for all browsy operations.
+ * Lazily initializes a default BrowsyContext if none is provided.
+ */
+export function getTools(ctx) {
+    const context = ctx instanceof BrowsyContext
+        ? ctx
+        : ctx
+            ? new BrowsyContext(ctx)
+            : getDefaultContext();
+    return TOOL_SCHEMAS.map((entry) => tool(async (params) => context.executeToolCall(entry.method, params), {
+        name: entry.name,
+        description: TOOL_DESCRIPTIONS[entry.name],
+        schema: entry.schema,
+    }));
+}

package/dist/openai.d.ts

@@ -0,0 +1,23 @@
+import { BrowsyContext } from "./context.js";
+import type { BrowsyConfigInput } from "./types.js";
+export interface ChatCompletionTool {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+        strict?: boolean;
+    };
+}
+/**
+ * Returns OpenAI-format tool definitions for all 14 browsy tools.
+ */
+export declare function getToolDefinitions(): ChatCompletionTool[];
+/**
+ * Dispatches a tool call by name and returns the string result.
+ */
+export declare function handleToolCall(name: string, args: Record<string, unknown>, ctx?: BrowsyContext | BrowsyConfigInput): Promise<string>;
+/**
+ * Returns a bound handler function for dispatching tool calls.
+ */
+export declare function createToolCallHandler(ctx?: BrowsyContext | BrowsyConfigInput): (name: string, args: Record<string, unknown>) => Promise<string>;

package/dist/openai.js

@@ -0,0 +1,58 @@
+import { zodToJsonSchema } from "./zod-to-json-schema.js";
+import { BrowsyContext } from "./context.js";
+import { TOOL_SCHEMAS, TOOL_DESCRIPTIONS } from "./schemas.js";
+// ---------------------------------------------------------------------------
+// Default context
+// ---------------------------------------------------------------------------
+let defaultContext;
+function getDefaultContext() {
+    if (!defaultContext) {
+        defaultContext = new BrowsyContext();
+    }
+    return defaultContext;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Returns OpenAI-format tool definitions for all 14 browsy tools.
+ */
+export function getToolDefinitions() {
+    return TOOL_SCHEMAS.map((entry) => ({
+        type: "function",
+        function: {
+            name: entry.name,
+            description: TOOL_DESCRIPTIONS[entry.name],
+            parameters: zodToJsonSchema(entry.schema),
+            strict: true,
+        },
+    }));
+}
+/**
+ * Dispatches a tool call by name and returns the string result.
+ */
+export async function handleToolCall(name, args, ctx) {
+    const context = ctx instanceof BrowsyContext
+        ? ctx
+        : ctx
+            ? new BrowsyContext(ctx)
+            : getDefaultContext();
+    const entry = TOOL_SCHEMAS.find((t) => t.name === name);
+    if (!entry) {
+        throw new Error(`Unknown browsy tool: ${name}`);
+    }
+    return context.executeToolCall(entry.method, args);
+}
+/**
+ * Returns a bound handler function for dispatching tool calls.
+ */
+export function createToolCallHandler(ctx) {
+    const context = ctx instanceof BrowsyContext
+        ? ctx
+        : ctx
+            ? new BrowsyContext(ctx)
+            : getDefaultContext();
+    return async (name, args) => {
+        return handleToolCall(name, args, context);
+    };
+}

package/dist/process.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Check if a port is currently in use.
+ */
+export declare function isPortInUse(port: number): Promise<boolean>;
+/**
+ * Find the browsy binary in PATH or common locations.
+ * Returns the path to the binary, or null if not found.
+ *
+ * Checks in order:
+ *   1. BROWSY_BIN environment variable (explicit override)
+ *   2. "browsy" in system PATH
+ */
+export declare function findBrowsyBinary(): string | null;