b4n1-web 0.3.0

package/README.md

@@ -0,0 +1,146 @@
+# B4n1Web JavaScript/TypeScript SDK
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/b4n1-web"><img src="https://img.shields.io/npm/v/b4n1-web.svg" alt="NPM version"></a>
+  <a href="https://www.npmjs.com/package/b4n1-web"><img src="https://img.shields.io/npm/dt/b4n1-web.svg" alt="NPM downloads"></a>
+  <a href="https://github.com/B4N1-com/b4n1-web"><img src="https://img.shields.io/github/stars/B4N1-com/b4n1web?style=flat" alt="GitHub stars"></a>
+</p>
+
+TypeScript/JavaScript bindings for B4n1Web: The Agentic Browser Engine.
+
+## Installation
+
+### 1. Install the B4n1Web Binary
+
+```bash
+curl -sL https://web.b4n1.com/install | bash
+```
+
+### 2. Install the JavaScript SDK
+
+```bash
+npm install b4n1-web
+```
+
+Or with yarn:
+
+```bash
+yarn add b4n1-web
+```
+
+Or with pnpm:
+
+```bash
+pnpm add b4n1-web
+```
+
+## Quick Start
+
+```typescript
+import { AgentBrowser, BrowserMode, Page } from 'b4n1-web';
+
+// Create a browser instance
+const browser = new AgentBrowser({ mode: BrowserMode.LIGHT });
+
+// Navigate to a page
+const page = await browser.goto('https://example.com');
+
+// Access structured data
+console.log('Page content:', page.markdown);
+console.log('Found', page.links.length, 'links');
+
+// Extract main content
+const mainContent = page.getMainContent();
+console.log('Main content:', mainContent.substring(0, 200) + '...');
+
+// Find specific links
+const githubLinks = page.findLinksByText('github');
+console.log('GitHub links:', githubLinks);
+
+// Close browser when done
+browser.close();
+```
+
+## Browser Modes
+
+### Light Mode (Default)
+
+- **Use case**: Reading articles, scraping static content, extracting links
+- **Performance**: < 15MB RAM, instant startup
+- **Capabilities**: HTML parsing, markdown conversion, link extraction
+- **Limitations**: No JavaScript execution
+
+```typescript
+const browser = new AgentBrowser({ mode: BrowserMode.LIGHT });
+```
+
+### JS Mode
+
+- **Use case**: Extracting JavaScript from pages, SPA analysis
+- **Performance**: Same as Light, instant startup
+- **Capabilities**: HTML parsing + JavaScript tag extraction
+
+```typescript
+const browser = new AgentBrowser({ mode: BrowserMode.JS });
+```
+
+### Render Mode (Coming Soon)
+
+- **Use case**: SPAs, form filling, visual verification, E2E testing
+- **Status**: Coming in v0.3.0
+
+## API Reference
+
+### AgentBrowser
+
+Main browser class for web automation.
+
+#### Constructor Options
+
+- `mode`: BrowserMode.LIGHT, BrowserMode.JS, or BrowserMode.RENDER
+- `timeout`: Request timeout in seconds (default: 30)
+- `userAgent`: Custom user agent string
+
+#### Methods
+
+- `goto(url: string)`: Navigate to URL and return structured page data
+- `close()`: Close the browser session
+
+### Page
+
+Structured data from a web page.
+
+#### Properties
+
+- `url: string`: The page URL
+- `markdown: string`: Clean markdown content
+- `links: string[]`: Extracted links
+- `screenshot?: string`: Base64-encoded screenshot (render mode only)
+
+#### Methods
+
+- `getMainContent()`: Extract main content, skipping headers/footers
+- `findLinksByText(text: string)`: Find links containing specific text
+
+## SecurityShield
+
+Optional security validation with caching:
+
+```typescript
+import { SecurityShield, navigate } from 'b4n1-web';
+
+// With security check
+const result = await navigate('https://example.com');
+
+// With custom shield
+const shield = new SecurityShield({ cacheDays: 30 });
+const { isSafe, needsApiCheck } = shield.isUrlSafe('https://example.com');
+```
+
+## TypeScript
+
+This package includes TypeScript type definitions. No additional installation needed.
+
+## License
+
+MIT

package/dist/browser.d.ts

@@ -0,0 +1,70 @@
+/**
+ * B4n1Web Browser - JavaScript/TypeScript Implementation
+ */
+import { type BrowserOptions, type PageData } from './types';
+/**
+ * Get B4n1Web binary version
+ */
+export declare function getB4n1webVersion(): string;
+/**
+ * Page data returned by B4n1Web
+ */
+export declare class Page implements PageData {
+    url: string;
+    markdown: string;
+    links: string[];
+    screenshot?: string;
+    constructor(data: PageData);
+    /**
+     * Extract main content from markdown, skipping headers
+     */
+    getMainContent(): string;
+    /**
+     * Find links containing specific text
+     */
+    findLinksByText(text: string): string[];
+}
+/**
+ * B4n1Web Agent Browser
+ *
+ * A browser instance optimized for AI agent workflows.
+ * Requires B4n1Web binary to be installed.
+ *
+ * @example
+ * ```typescript
+ * import { AgentBrowser, BrowserMode } from 'b4n1-web';
+ *
+ * const browser = new AgentBrowser({ mode: BrowserMode.LIGHT });
+ * const page = await browser.goto('https://example.com');
+ * console.log(page.markdown);
+ * browser.close();
+ * ```
+ */
+export declare class AgentBrowser {
+    private mode;
+    private timeout;
+    private userAgent;
+    private binaryPath;
+    constructor(options?: BrowserOptions);
+    /**
+     * Navigate to a URL and extract structured content
+     */
+    goto(url: string): Promise<Page>;
+    /**
+     * Parse text output from the binary
+     */
+    private parseOutput;
+    /**
+     * Close the browser session
+     */
+    close(): void;
+    /**
+     * Use as async context manager
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+}
+/**
+ * Create a browser and navigate in one go
+ */
+export declare function createBrowserAndGoto(url: string, options?: BrowserOptions): Promise<Page>;
+//# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAe,KAAK,cAAc,EAAE,KAAK,QAAQ,EAAuB,MAAM,SAAS,CAAC;AA0B/F;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAW1C;AAED;;GAEG;AACH,qBAAa,IAAK,YAAW,QAAQ;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;gBAER,IAAI,EAAE,QAAQ;IAO1B;;OAEG;IACH,cAAc,IAAI,MAAM;IAMxB;;OAEG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE;CAIxC;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,IAAI,CAAc;IAC1B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,UAAU,CAAU;gBAEhB,OAAO,GAAE,cAAmB;IAYxC;;OAEG;IACG,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBtC;;OAEG;IACH,OAAO,CAAC,WAAW;IA2BnB;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACG,CAAC,MAAM,CAAC,YAAY,CAAC;CAG5B;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,IAAI,CAAC,CAOf"}

package/dist/browser.js

@@ -0,0 +1,174 @@
+/**
+ * B4n1Web Browser - JavaScript/TypeScript Implementation
+ */
+import { execSync } from 'child_process';
+import { BrowserMode, BinaryNotFoundError } from './types';
+/**
+ * Find the b4n1web binary in common locations
+ */
+function getB4n1webBinary() {
+    const possiblePaths = [
+        '/usr/local/bin/b4n1web',
+        '/usr/bin/b4n1web',
+        process.env.HOME + '/.local/bin/b4n1web',
+        process.env.HOME + '/.b4n1web/bin/b4n1web',
+    ];
+    for (const path of possiblePaths) {
+        try {
+            const fs = require('fs');
+            if (fs.existsSync(path) && fs.accessSync(path, fs.constants.X_OK)) {
+                return path;
+            }
+        }
+        catch {
+            // Path doesn't exist or not executable
+        }
+    }
+    return null;
+}
+/**
+ * Get B4n1Web binary version
+ */
+export function getB4n1webVersion() {
+    const binaryPath = getB4n1webBinary();
+    if (!binaryPath) {
+        return 'unknown';
+    }
+    try {
+        const version = execSync(`${binaryPath} --version`, { timeout: 5000 }).toString().trim();
+        return version || 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/**
+ * Page data returned by B4n1Web
+ */
+export class Page {
+    constructor(data) {
+        this.url = data.url;
+        this.markdown = data.markdown;
+        this.links = data.links;
+        this.screenshot = data.screenshot;
+    }
+    /**
+     * Extract main content from markdown, skipping headers
+     */
+    getMainContent() {
+        const lines = this.markdown.split('\n');
+        const contentLines = lines.length > 2 ? lines.slice(2) : lines;
+        return contentLines.join('\n').trim();
+    }
+    /**
+     * Find links containing specific text
+     */
+    findLinksByText(text) {
+        const lowerText = text.toLowerCase();
+        return this.links.filter(link => link.toLowerCase().includes(lowerText));
+    }
+}
+/**
+ * B4n1Web Agent Browser
+ *
+ * A browser instance optimized for AI agent workflows.
+ * Requires B4n1Web binary to be installed.
+ *
+ * @example
+ * ```typescript
+ * import { AgentBrowser, BrowserMode } from 'b4n1-web';
+ *
+ * const browser = new AgentBrowser({ mode: BrowserMode.LIGHT });
+ * const page = await browser.goto('https://example.com');
+ * console.log(page.markdown);
+ * browser.close();
+ * ```
+ */
+export class AgentBrowser {
+    constructor(options = {}) {
+        this.mode = options.mode ?? BrowserMode.LIGHT;
+        this.timeout = options.timeout ?? 30;
+        this.userAgent = options.userAgent ?? 'B4n1Web-Agent/1.0';
+        const binary = getB4n1webBinary();
+        if (!binary) {
+            throw new BinaryNotFoundError('b4n1web binary not found. Run: curl -sL https://web.b4n1.com/install | bash');
+        }
+        this.binaryPath = binary;
+    }
+    /**
+     * Navigate to a URL and extract structured content
+     */
+    async goto(url) {
+        return new Promise((resolve, reject) => {
+            try {
+                const output = execSync(`${this.binaryPath} goto ${url} --mode ${this.mode}`, { timeout: this.timeout * 1000 }).toString();
+                const page = this.parseOutput(url, output);
+                resolve(page);
+            }
+            catch (error) {
+                if (error.message?.includes('timed out')) {
+                    reject(new Error(`Binary timed out after ${this.timeout}s`));
+                }
+                else {
+                    reject(new Error(`Binary error: ${error.message}`));
+                }
+            }
+        });
+    }
+    /**
+     * Parse text output from the binary
+     */
+    parseOutput(url, output) {
+        let markdown = '';
+        let links = [];
+        for (const line of output.split('\n')) {
+            if (line.startsWith('URL:')) {
+                continue;
+            }
+            else if (line.startsWith('Markdown:')) {
+                continue;
+            }
+            else if (line.startsWith('Links:')) {
+                try {
+                    links = eval(line.slice(6).trim()); // Safe: we control the output format
+                }
+                catch {
+                    links = [];
+                }
+            }
+            else {
+                markdown += line + '\n';
+            }
+        }
+        return new Page({
+            url,
+            markdown: markdown.trim(),
+            links,
+        });
+    }
+    /**
+     * Close the browser session
+     */
+    close() {
+        // No persistent session to close in current implementation
+    }
+    /**
+     * Use as async context manager
+     */
+    async [Symbol.asyncDispose]() {
+        this.close();
+    }
+}
+/**
+ * Create a browser and navigate in one go
+ */
+export async function createBrowserAndGoto(url, options = {}) {
+    const browser = new AgentBrowser(options);
+    try {
+        return await browser.goto(url);
+    }
+    finally {
+        browser.close();
+    }
+}
+//# sourceMappingURL=browser.js.map

package/dist/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,24 @@
+/**
+ * B4n1Web Errors
+ */
+/**
+ * Error thrown when B4n1Web binary is not found
+ */
+export declare class BinaryNotFoundError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Error thrown when navigation fails
+ */
+export declare class NavigationError extends Error {
+    readonly url: string;
+    constructor(message: string, url: string);
+}
+/**
+ * Error thrown when binary execution fails
+ */
+export declare class BinaryError extends Error {
+    readonly stderr: string;
+    constructor(message: string, stderr: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,SAAuG;CAK3H;AAED;;GAEG;AACH,qBAAa,eAAgB,SAAQ,KAAK;aACK,GAAG,EAAE,MAAM;gBAA5C,OAAO,EAAE,MAAM,EAAkB,GAAG,EAAE,MAAM;CAKzD;AAED;;GAEG;AACH,qBAAa,WAAY,SAAQ,KAAK;aACS,MAAM,EAAE,MAAM;gBAA/C,OAAO,EAAE,MAAM,EAAkB,MAAM,EAAE,MAAM;CAK5D"}

package/dist/errors.js

@@ -0,0 +1,36 @@
+/**
+ * B4n1Web Errors
+ */
+/**
+ * Error thrown when B4n1Web binary is not found
+ */
+export class BinaryNotFoundError extends Error {
+    constructor(message = 'B4n1Web binary not found. Please install it first:\n  curl -sL https://web.b4n1.com/install | bash') {
+        super(message);
+        this.name = 'BinaryNotFoundError';
+        Error.captureStackTrace(this, BinaryNotFoundError);
+    }
+}
+/**
+ * Error thrown when navigation fails
+ */
+export class NavigationError extends Error {
+    constructor(message, url) {
+        super(message);
+        this.url = url;
+        this.name = 'NavigationError';
+        Error.captureStackTrace(this, NavigationError);
+    }
+}
+/**
+ * Error thrown when binary execution fails
+ */
+export class BinaryError extends Error {
+    constructor(message, stderr) {
+        super(message);
+        this.stderr = stderr;
+        this.name = 'BinaryError';
+        Error.captureStackTrace(this, BinaryError);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAC5C,YAAY,OAAO,GAAG,oGAAoG;QACxH,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,mBAAmB,CAAC,CAAC;IACrD,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACxC,YAAY,OAAe,EAAkB,GAAW;QACtD,KAAK,CAAC,OAAO,CAAC,CAAC;QAD4B,QAAG,GAAH,GAAG,CAAQ;QAEtD,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC;IACjD,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IACpC,YAAY,OAAe,EAAkB,MAAc;QACzD,KAAK,CAAC,OAAO,CAAC,CAAC;QAD4B,WAAM,GAAN,MAAM,CAAQ;QAEzD,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;IAC7C,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * B4n1Web SDK for JavaScript/TypeScript
+ * Zero-overhead, high-speed web execution for sovereign AI agents.
+ *
+ * @module b4n1web
+ */
+export { AgentBrowser, Page } from './browser';
+export { BrowserMode } from './types';
+export { BinaryNotFoundError } from './errors';
+export { SecurityShield, navigate } from './security';
+export type { BrowserOptions, PageData, NavigateResult, SecurityShieldOptions } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACtC,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtD,YAAY,EAAE,cAAc,EAAE,QAAQ,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * B4n1Web SDK for JavaScript/TypeScript
+ * Zero-overhead, high-speed web execution for sovereign AI agents.
+ *
+ * @module b4n1web
+ */
+export { AgentBrowser, Page } from './browser';
+export { BrowserMode } from './types';
+export { BinaryNotFoundError } from './errors';
+export { SecurityShield, navigate } from './security';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACtC,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC"}

package/dist/security.d.ts

@@ -0,0 +1,65 @@
+/**
+ * B4n1Web SecurityShield - URL Security Validation
+ *
+ * Provides URL security validation with caching.
+ * Fall-safe: returns safe=true if any error occurs.
+ */
+import type { SecurityShieldOptions, SecurityCheckResult } from './types';
+/**
+ * SecurityShield - Domain safety validation with caching
+ *
+ * @example
+ * ```typescript
+ * import { SecurityShield, navigate } from 'b4n1-web';
+ *
+ * // Simple usage
+ * const result = await navigate('https://example.com');
+ *
+ * // With custom shield
+ * const shield = new SecurityShield({ cacheDays: 30 });
+ * const { isSafe, needsApiCheck } = shield.isUrlSafe('https://example.com');
+ * ```
+ */
+export declare class SecurityShield {
+    private dbPath;
+    private cacheDays;
+    private cache;
+    constructor(options?: SecurityShieldOptions);
+    /**
+     * Extract domain from URL
+     */
+    private extractDomain;
+    /**
+     * Check if URL is safe to navigate
+     */
+    isUrlSafe(url: string): SecurityCheckResult;
+    /**
+     * Mark a domain as safe or unsafe
+     */
+    markDomain(domain: string, isSafe: boolean): void;
+    /**
+     * Clear all cached domains
+     */
+    clearCache(): void;
+}
+/**
+ * Navigate to URL with optional security check
+ *
+ * @example
+ * ```typescript
+ * import { navigate } from 'b4n1-web';
+ *
+ * const result = await navigate('https://example.com');
+ * if (result.success) {
+ *   console.log(result.markdown);
+ * }
+ * ```
+ */
+export declare function navigate(url: string, ignoreSecurity?: boolean, securityShield?: SecurityShield): Promise<{
+    url: string;
+    success: boolean;
+    markdown?: string;
+    links?: string[];
+    error?: string;
+}>;
+//# sourceMappingURL=security.d.ts.map

package/dist/security.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"security.d.ts","sourceRoot":"","sources":["../src/security.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAE1E;;;;;;;;;;;;;;GAcG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,KAAK,CAAoD;gBAErD,OAAO,GAAE,qBAA0B;IAM/C;;OAEG;IACH,OAAO,CAAC,aAAa;IASrB;;OAEG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB;IAkB3C;;OAEG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI;IAMjD;;OAEG;IACH,UAAU,IAAI,IAAI;CAGnB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,QAAQ,CAC5B,GAAG,EAAE,MAAM,EACX,cAAc,GAAE,OAAe,EAC/B,cAAc,CAAC,EAAE,cAAc,GAC9B,OAAO,CAAC;IACT,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC,CAkCD"}

package/dist/security.js

@@ -0,0 +1,121 @@
+/**
+ * B4n1Web SecurityShield - URL Security Validation
+ *
+ * Provides URL security validation with caching.
+ * Fall-safe: returns safe=true if any error occurs.
+ */
+import { AgentBrowser } from './browser';
+import { BrowserMode } from './types';
+/**
+ * SecurityShield - Domain safety validation with caching
+ *
+ * @example
+ * ```typescript
+ * import { SecurityShield, navigate } from 'b4n1-web';
+ *
+ * // Simple usage
+ * const result = await navigate('https://example.com');
+ *
+ * // With custom shield
+ * const shield = new SecurityShield({ cacheDays: 30 });
+ * const { isSafe, needsApiCheck } = shield.isUrlSafe('https://example.com');
+ * ```
+ */
+export class SecurityShield {
+    constructor(options = {}) {
+        this.dbPath = options.dbPath ?? `${process.env.HOME}/.b4n1web/security.db`;
+        this.cacheDays = options.cacheDays ?? 7;
+        this.cache = new Map();
+    }
+    /**
+     * Extract domain from URL
+     */
+    extractDomain(url) {
+        try {
+            const parsed = new URL(url);
+            return parsed.hostname.toLowerCase();
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Check if URL is safe to navigate
+     */
+    isUrlSafe(url) {
+        const domain = this.extractDomain(url);
+        if (!domain) {
+            return { isSafe: true, needsApiCheck: false };
+        }
+        const cached = this.cache.get(domain);
+        if (cached) {
+            if (Date.now() > cached.expires) {
+                this.cache.delete(domain);
+                return { isSafe: true, needsApiCheck: true };
+            }
+            return { isSafe: cached.isSafe, needsApiCheck: false };
+        }
+        return { isSafe: true, needsApiCheck: true };
+    }
+    /**
+     * Mark a domain as safe or unsafe
+     */
+    markDomain(domain, isSafe) {
+        const normalizedDomain = domain.toLowerCase();
+        const expires = Date.now() + this.cacheDays * 24 * 60 * 60 * 1000;
+        this.cache.set(normalizedDomain, { isSafe, expires });
+    }
+    /**
+     * Clear all cached domains
+     */
+    clearCache() {
+        this.cache.clear();
+    }
+}
+/**
+ * Navigate to URL with optional security check
+ *
+ * @example
+ * ```typescript
+ * import { navigate } from 'b4n1-web';
+ *
+ * const result = await navigate('https://example.com');
+ * if (result.success) {
+ *   console.log(result.markdown);
+ * }
+ * ```
+ */
+export async function navigate(url, ignoreSecurity = false, securityShield) {
+    if (!securityShield) {
+        securityShield = new SecurityShield();
+    }
+    if (!ignoreSecurity) {
+        const { isSafe } = securityShield.isUrlSafe(url);
+        if (!isSafe) {
+            return {
+                url,
+                success: false,
+                error: 'URL flagged as unsafe by security check',
+            };
+        }
+    }
+    try {
+        const browser = new AgentBrowser({ mode: BrowserMode.LIGHT });
+        const page = await browser.goto(url);
+        browser.close();
+        return {
+            url: page.url,
+            success: true,
+            markdown: page.markdown,
+            links: page.links,
+        };
+    }
+    catch (error) {
+        return {
+            url,
+            success: false,
+            error: error.message,
+        };
+    }
+}
+//# sourceMappingURL=security.js.map

package/dist/security.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"security.js","sourceRoot":"","sources":["../src/security.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAa,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAGtC;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,cAAc;IAKzB,YAAY,UAAiC,EAAE;QAC7C,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,uBAAuB,CAAC;QAC3E,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,CAAC,CAAC;QACxC,IAAI,CAAC,KAAK,GAAG,IAAI,GAAG,EAAE,CAAC;IACzB,CAAC;IAED;;OAEG;IACK,aAAa,CAAC,GAAW;QAC/B,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;YAC5B,OAAO,MAAM,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;QACvC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED;;OAEG;IACH,SAAS,CAAC,GAAW;QACnB,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;QACvC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC;QAChD,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACtC,IAAI,MAAM,EAAE,CAAC;YACX,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;gBAChC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;gBAC1B,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC;YAC/C,CAAC;YACD,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC;QACzD,CAAC;QAED,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC;IAC/C,CAAC;IAED;;OAEG;IACH,UAAU,CAAC,MAAc,EAAE,MAAe;QACxC,MAAM,gBAAgB,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC;QAC9C,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,SAAS,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;QAClE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,gBAAgB,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;IACxD,CAAC;IAED;;OAEG;IACH,UAAU;QACR,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;CACF;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,GAAW,EACX,iBAA0B,KAAK,EAC/B,cAA+B;IAQ/B,IAAI,CAAC,cAAc,EAAE,CAAC;QACpB,cAAc,GAAG,IAAI,cAAc,EAAE,CAAC;IACxC,CAAC;IAED,IAAI,CAAC,cAAc,EAAE,CAAC;QACpB,MAAM,EAAE,MAAM,EAAE,GAAG,cAAc,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QACjD,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO;gBACL,GAAG;gBACH,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,yCAAyC;aACjD,CAAC;QACJ,CAAC;IACH,CAAC;IAED,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,IAAI,YAAY,CAAC,EAAE,IAAI,EAAE,WAAW,CAAC,KAAK,EAAE,CAAC,CAAC;QAC9D,MAAM,IAAI,GAAS,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC3C,OAAO,CAAC,KAAK,EAAE,CAAC;QAEhB,OAAO;YACL,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,OAAO,EAAE,IAAI;YACb,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,KAAK,EAAE,IAAI,CAAC,KAAK;SAClB,CAAC;IACJ,CAAC;IAAC,OAAO,KAAU,EAAE,CAAC;QACpB,OAAO;YACL,GAAG;YACH,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,KAAK,CAAC,OAAO;SACrB,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,38 @@
+/**
+ * B4n1Web TypeScript Types
+ */
+export declare enum BrowserMode {
+    LIGHT = "light",
+    JS = "js",
+    RENDER = "render"
+}
+export interface BrowserOptions {
+    mode?: BrowserMode;
+    timeout?: number;
+    userAgent?: string;
+}
+export interface PageData {
+    url: string;
+    markdown: string;
+    links: string[];
+    screenshot?: string;
+}
+export interface NavigateResult {
+    url: string;
+    success: boolean;
+    markdown?: string;
+    links?: string[];
+    error?: string;
+}
+export interface SecurityShieldOptions {
+    dbPath?: string;
+    cacheDays?: number;
+}
+export interface SecurityCheckResult {
+    isSafe: boolean;
+    needsApiCheck: boolean;
+}
+export declare class BinaryNotFoundError extends Error {
+    constructor(message?: string);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,oBAAY,WAAW;IACrB,KAAK,UAAU;IACf,EAAE,OAAO;IACT,MAAM,WAAW;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,OAAO,CAAC;IAChB,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,SAAuG;CAI3H"}

package/dist/types.js

@@ -0,0 +1,16 @@
+/**
+ * B4n1Web TypeScript Types
+ */
+export var BrowserMode;
+(function (BrowserMode) {
+    BrowserMode["LIGHT"] = "light";
+    BrowserMode["JS"] = "js";
+    BrowserMode["RENDER"] = "render";
+})(BrowserMode || (BrowserMode = {}));
+export class BinaryNotFoundError extends Error {
+    constructor(message = 'B4n1Web binary not found. Please install it first:\n  curl -sL https://web.b4n1.com/install | bash') {
+        super(message);
+        this.name = 'BinaryNotFoundError';
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,CAAN,IAAY,WAIX;AAJD,WAAY,WAAW;IACrB,8BAAe,CAAA;IACf,wBAAS,CAAA;IACT,gCAAiB,CAAA;AACnB,CAAC,EAJW,WAAW,KAAX,WAAW,QAItB;AAiCD,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAC5C,YAAY,OAAO,GAAG,oGAAoG;QACxH,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "b4n1-web",
+  "version": "0.3.0",
+  "description": "B4n1Web SDK for JavaScript/TypeScript - Agentic Browser Engine",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "browser",
+    "agent",
+    "automation",
+    "web-scraping",
+    "headless"
+  ],
+  "author": "Bani Montoya <banimontoya@gmail.com>",
+  "license": "MIT",
+  "homepage": "https://web.b4n1.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/B4N1-com/b4n1-web.git"
+  },
+  "dependencies": {
+    "undici": "^6.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "jest": "^29.7.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.1.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}