@monostate/browsernative-client NPM

@monostate/browsernative-client

Official JavaScript/TypeScript client for Browser Native API

A lightweight, fast, and reliable client for the Browser Native web scraping and content extraction API. Works in browsers, Node.js, Deno, and edge environments.

🚀 Quick Start

Installation

npm install @monostate/browsernative-client
# or
yarn add @monostate/browsernative-client
# or  
pnpm add @monostate/browsernative-client

Get Your API Key

Sign up at bnca.monostate.ai
Get your API key from the dashboard
Start scraping!

Basic Usage

import { BrowserNativeClient } from '@monostate/browsernative-client';

const client = new BrowserNativeClient('your-api-key');

// Scrape any website
const result = await client.scrape('https://example.com');
console.log(result.data.title);
console.log(result.data.content);

// Quick screenshot capture (optimized for speed)
const screenshot = await client.quickshot('https://example.com');
console.log(screenshot.screenshot); // Base64 image

Quick Functions

import { quickScrape, quickScreenshot, quickShot, quickAnalyze } from '@monostate/browsernative-client';

// One-line scraping
const content = await quickScrape('https://example.com', 'your-api-key');

// Take a screenshot (with content extraction)
const screenshot = await quickScreenshot('https://example.com', 'your-api-key');

// Quick screenshot only (fastest option)
const quickScreenshot = await quickShot('https://example.com', 'your-api-key');

// AI-powered analysis
const analysis = await quickAnalyze(
  'https://news.ycombinator.com', 
  'What are the top 3 trending topics?',
  'your-api-key'
);

📋 API Reference

Client Initialization

const client = new BrowserNativeClient(apiKey, options);

Options:

baseUrl (string): API base URL (default: https://bnca-api.fly.dev)
timeout (number): Request timeout in ms (default: 30000)
retries (number): Number of retry attempts (default: 2)
verbose (boolean): Enable logging (default: false)

Methods

`client.scrape(url, options)`

Extract structured content from any webpage.

const result = await client.scrape('https://example.com', {
  includeScreenshot: true,
  waitForSelector: '.main-content',
  extractMetadata: true,
  userAgent: 'Custom Bot 1.0'
});

console.log(result.data.title);      // Page title
console.log(result.data.content);   // Main content
console.log(result.data.metadata);  // Meta tags, etc.
console.log(result.screenshot);     // Base64 image (if requested)
console.log(result.method);         // Scraping method used

Options:

includeScreenshot (boolean): Include page screenshot
waitForSelector (string): CSS selector to wait for
userAgent (string): Custom user agent
viewport (object): { width: number, height: number }
extractMetadata (boolean): Extract meta tags and structured data

`client.screenshot(url, options)`

Take high-quality screenshots of webpages with content extraction.

const result = await client.screenshot('https://example.com', {
  fullPage: true,
  format: 'png',
  viewport: { width: 1920, height: 1080 }
});

// Use the base64 image
const img = `data:image/png;base64,${result.screenshot}`;

Options:

fullPage (boolean): Capture full page scroll
format (string): 'png', 'jpeg', or 'webp'
quality (number): JPEG quality (1-100)
All scrape options are also available

`client.quickshot(url, options)`

Optimized screenshot capture for maximum speed (no content extraction).

const result = await client.quickshot('https://example.com');

// Returns screenshot immediately
if (result.success && result.screenshot) {
  const img = result.screenshot; // Already includes data:image/png;base64,
}

Benefits:

2-3x faster than regular screenshot
Optimized for visual capture only
Perfect for thumbnails and previews

`client.analyze(url, question, options)`

AI-powered content analysis and question answering.

const result = await client.analyze(
  'https://techcrunch.com',
  'What are the latest AI developments mentioned?',
  {
    language: 'en',
    style: 'detailed'
  }
);

console.log(result.analysis.answer);     // AI response
console.log(result.analysis.confidence); // Confidence score

Options:

language (string): Response language ('en', 'pt', 'es', 'fr', 'de', 'auto')
style (string): Response style ('concise', 'detailed', 'technical')
All scrape options are also available

`client.getUsage(days)`

Get your account usage statistics.

const usage = await client.getUsage(30); // Last 30 days

console.log(usage.data.monthlyTotal.totalRequests);
console.log(usage.data.currentUsage);
console.log(usage.data.usageLimit);

`client.healthCheck()`

Check API status and your account health.

const health = await client.healthCheck();

console.log(health.data.status);   // 'healthy', 'degraded', or 'unhealthy'
console.log(health.data.services); // Service status breakdown

🌐 Framework Integration

React Hook

// hooks/useBrowserNative.js
import { useState } from 'react';
import { BrowserNativeClient } from '@monostate/browsernative-client';

export function useBrowserNative(apiKey) {
  const [loading, setLoading] = useState(false);
  const [data, setData] = useState(null);
  const [error, setError] = useState(null);

  const client = new BrowserNativeClient(apiKey);

  const scrape = async (url, options = {}) => {
    setLoading(true);
    setError(null);
    
    try {
      const result = await client.scrape(url, options);
      if (result.success) {
        setData(result.data);
      } else {
        setError(result.error);
      }
    } catch (err) {
      setError(err.message);
    } finally {
      setLoading(false);
    }
  };

  return { scrape, loading, data, error };
}

Vue Composable

// composables/useBrowserNative.js
import { ref } from 'vue';
import { BrowserNativeClient } from '@monostate/browsernative-client';

export function useBrowserNative(apiKey) {
  const loading = ref(false);
  const data = ref(null);
  const error = ref(null);

  const client = new BrowserNativeClient(apiKey);

  const scrape = async (url, options = {}) => {
    loading.value = true;
    error.value = null;
    
    try {
      const result = await client.scrape(url, options);
      if (result.success) {
        data.value = result.data;
      } else {
        error.value = result.error;
      }
    } catch (err) {
      error.value = err.message;
    } finally {
      loading.value = false;
    }
  };

  return { scrape, loading, data, error };
}

Next.js API Route

// pages/api/scrape.js
import { BrowserNativeClient } from '@monostate/browsernative-client';

const client = new BrowserNativeClient(process.env.BROWSER_NATIVE_API_KEY);

export default async function handler(req, res) {
  if (req.method !== 'POST') {
    return res.status(405).json({ error: 'Method not allowed' });
  }

  try {
    const { url, question } = req.body;
    
    let result;
    if (question) {
      result = await client.analyze(url, question);
    } else {
      result = await client.scrape(url);
    }
    
    res.status(200).json(result);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
}

Express.js

import express from 'express';
import { BrowserNativeClient } from '@monostate/browsernative-client';

const app = express();
const client = new BrowserNativeClient(process.env.BROWSER_NATIVE_API_KEY);

app.post('/scrape', async (req, res) => {
  try {
    const { url } = req.body;
    const result = await client.scrape(url);
    res.json(result);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

🔒 Environment Variables

Create a .env file:

BROWSER_NATIVE_API_KEY=your_api_key_here

Then use in your code:

const client = new BrowserNativeClient(process.env.BROWSER_NATIVE_API_KEY);

📱 Browser Usage

You can use this client directly in browsers, but be careful with API keys:

<!DOCTYPE html>
<html>
<head>
    <title>Browser Native Demo</title>
</head>
<body>
    <script type="module">
        import { BrowserNativeClient } from 'https://cdn.skypack.dev/@monostate/browsernative-client';
        
        // ⚠️ Never expose your API key in client-side code!
        // Use a proxy server or environment variables
        const client = new BrowserNativeClient(await getApiKeyFromServer());
        
        const result = await client.scrape('https://example.com');
        console.log(result);
    </script>
</body>
</html>

Security Note: Never expose your API key in client-side code. Use a backend proxy or server-side rendering.

⚡ Performance Tips

Reuse Client Instances: Create one client instance and reuse it
Enable Retries: The client automatically retries failed requests
Use Appropriate Timeouts: Adjust timeout based on your use case
Batch Requests: Process multiple URLs concurrently

const client = new BrowserNativeClient(apiKey, {
  timeout: 45000,  // Longer timeout for complex sites
  retries: 3,      // More retries for reliability
  verbose: true    // Enable logging for debugging
});

// Concurrent scraping
const urls = ['https://site1.com', 'https://site2.com', 'https://site3.com'];
const results = await Promise.all(
  urls.map(url => client.scrape(url))
);

🔧 Error Handling

try {
  const result = await client.scrape(url);
  
  if (result.success) {
    console.log('Success:', result.data);
  } else {
    console.error('Scraping failed:', result.error);
  }
} catch (error) {
  console.error('Request failed:', error.message);
}

Common error scenarios:

Invalid API Key: Check your API key and account status
Rate Limited: Upgrade your plan or reduce request frequency
Timeout: Increase timeout or try a simpler extraction method
Invalid URL: Ensure the URL is accessible and properly formatted

🚀 TypeScript Support

Full TypeScript support with comprehensive type definitions:

import { BrowserNativeClient, ScrapeResult, AnalyzeResult } from '@monostate/browsernative-client';

const client: BrowserNativeClient = new BrowserNativeClient('your-api-key');

const result: ScrapeResult = await client.scrape('https://example.com');
const analysis: AnalyzeResult = await client.analyze(url, question);