@monostate/browsernative-client 1.0.1

package/README.md

@@ -0,0 +1,419 @@
+# @browsernative/client
+
+> **Official JavaScript/TypeScript client for Browser Native API**
+
+[![npm version](https://badge.fury.io/js/%40browsernative%2Fclient.svg)](https://badge.fury.io/js/%40browsernative%2Fclient)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](../../LICENSE)
+
+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
+
+```bash
+npm install @browsernative/client
+# or
+yarn add @browsernative/client
+# or  
+pnpm add @browsernative/client
+```
+
+### Get Your API Key
+
+1. Sign up at [browsernative.monostate.ai](https://browsernative.monostate.ai)
+2. Get your API key from the dashboard
+3. Start scraping!
+
+### Basic Usage
+
+```javascript
+import { BrowserNativeClient } from '@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 Functions
+
+```javascript
+import { quickScrape, quickScreenshot, quickAnalyze } from '@browsernative/client';
+
+// One-line scraping
+const content = await quickScrape('https://example.com', 'your-api-key');
+
+// Take a screenshot
+const screenshot = await quickScreenshot('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
+
+```javascript
+const client = new BrowserNativeClient(apiKey, options);
+```
+
+**Options:**
+- `baseUrl` (string): API base URL (default: `https://browsernative.monostate.ai`)
+- `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.
+
+```javascript
+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.
+
+```javascript
+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.analyze(url, question, options)`
+
+AI-powered content analysis and question answering.
+
+```javascript
+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.
+
+```javascript
+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.
+
+```javascript
+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
+
+```javascript
+// hooks/useBrowserNative.js
+import { useState } from 'react';
+import { BrowserNativeClient } from '@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
+
+```javascript
+// composables/useBrowserNative.js
+import { ref } from 'vue';
+import { BrowserNativeClient } from '@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
+
+```javascript
+// pages/api/scrape.js
+import { BrowserNativeClient } from '@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
+
+```javascript
+import express from 'express';
+import { BrowserNativeClient } from '@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:
+
+```bash
+BROWSER_NATIVE_API_KEY=your_api_key_here
+```
+
+Then use in your code:
+
+```javascript
+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:
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <title>Browser Native Demo</title>
+</head>
+<body>
+    <script type="module">
+        import { BrowserNativeClient } from 'https://cdn.skypack.dev/@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
+
+1. **Reuse Client Instances**: Create one client instance and reuse it
+2. **Enable Retries**: The client automatically retries failed requests
+3. **Use Appropriate Timeouts**: Adjust timeout based on your use case
+4. **Batch Requests**: Process multiple URLs concurrently
+
+```javascript
+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
+
+```javascript
+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:
+
+```typescript
+import { BrowserNativeClient, ScrapeResult, AnalyzeResult } from '@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);
+```
+
+## 📊 Rate Limits
+
+| Plan | Requests/Month | Rate Limit |
+|------|----------------|------------|
+| **Free** | 1,000 | 10/minute |
+| **Starter** | 10,000 | 60/minute |
+| **Pro** | 100,000 | 300/minute |
+| **Enterprise** | Unlimited | Custom |
+
+## 🤝 Support
+
+- 📧 **Email**: [support@browsernative.monostate.ai](mailto:support@browsernative.monostate.ai)
+- 📖 **Documentation**: [browsernative.monostate.ai/docs](https://browsernative.monostate.ai/docs)
+- 🐛 **Issues**: [GitHub Issues](https://github.com/browsernative/client-sdk/issues)
+- 💬 **Discord**: [Join our community](https://discord.gg/browsernative)
+
+## 📄 License
+
+MIT License - see [LICENSE](../../LICENSE) file for details.
+
+---
+
+<div align="center">
+
+**Built with ❤️ for developers who value speed and reliability**
+
+[🌐 Website](https://browsernative.monostate.ai) | [📖 Docs](https://browsernative.monostate.ai/docs) | [🚀 Get API Key](https://browsernative.monostate.ai/signup)
+
+</div>

package/index.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Browser Native Client SDK TypeScript Definitions
+ */
+
+export interface ClientOptions {
+  /** Base URL for the API (default: https://browsernative.monostate.ai) */
+  baseUrl?: string;
+  /** Request timeout in milliseconds (default: 30000) */
+  timeout?: number;
+  /** Number of retry attempts (default: 2) */
+  retries?: number;
+  /** Enable verbose logging (default: false) */
+  verbose?: boolean;
+}
+
+export interface ScrapeOptions {
+  /** Include screenshot in the response */
+  includeScreenshot?: boolean;
+  /** Wait for specific selector before extracting content */
+  waitForSelector?: string;
+  /** Custom user agent string */
+  userAgent?: string;
+  /** Viewport size for rendering */
+  viewport?: {
+    width: number;
+    height: number;
+  };
+  /** Additional metadata to extract */
+  extractMetadata?: boolean;
+}
+
+export interface ScreenshotOptions extends ScrapeOptions {
+  /** Force full page screenshot */
+  fullPage?: boolean;
+  /** Image format (default: png) */
+  format?: 'png' | 'jpeg' | 'webp';
+  /** Image quality for JPEG (1-100) */
+  quality?: number;
+}
+
+export interface AnalyzeOptions extends ScrapeOptions {
+  /** Language for the AI response */
+  language?: 'en' | 'pt' | 'es' | 'fr' | 'de' | 'auto';
+  /** Response style */
+  style?: 'concise' | 'detailed' | 'technical';
+}
+
+export interface ScrapeResult {
+  /** Whether the request was successful */
+  success: boolean;
+  /** Extracted content data */
+  data?: {
+    title?: string;
+    description?: string;
+    content?: string;
+    metadata?: Record<string, any>;
+    links?: string[];
+    images?: string[];
+  };
+  /** Scraping method used */
+  method?: 'direct' | 'lightpanda' | 'puppeteer';
+  /** Performance information */
+  performance?: {
+    totalTime: number;
+    method: string;
+  };
+  /** Base64 encoded screenshot (if requested) */
+  screenshot?: string;
+  /** Error message (if failed) */
+  error?: string;
+  /** Response time in milliseconds */
+  responseTime: number;
+  /** Attempt number that succeeded */
+  attempt?: number;
+}
+
+export interface AnalyzeResult extends ScrapeResult {
+  /** AI analysis response */
+  analysis?: {
+    answer: string;
+    confidence: number;
+    processingTime: number;
+    language: string;
+  };
+}
+
+export interface UsageResult {
+  success: boolean;
+  data?: {
+    /** Daily usage breakdown */
+    dailyUsage: Array<{
+      date: string;
+      requests: number;
+      scrapeRequests: number;
+      analyzeRequests: number;
+    }>;
+    /** Monthly totals */
+    monthlyTotal: {
+      totalRequests: number;
+      scrapeTotal: number;
+      analyzeTotal: number;
+    };
+    /** Current plan information */
+    currentUsage: number;
+    usageLimit: number;
+    planType: string;
+    subscriptionStatus: string;
+    currentPeriodEnd: string;
+  };
+  error?: string;
+  responseTime: number;
+}
+
+export interface HealthResult {
+  success: boolean;
+  data?: {
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    version: string;
+    uptime: number;
+    services: {
+      scraping: boolean;
+      ai: boolean;
+      database: boolean;
+    };
+  };
+  error?: string;
+  responseTime: number;
+}
+
+/**
+ * Browser Native API Client
+ */
+export declare class BrowserNativeClient {
+  constructor(apiKey: string, options?: ClientOptions);
+
+  /**
+   * Scrape a webpage and extract structured content
+   */
+  scrape(url: string, options?: ScrapeOptions): Promise<ScrapeResult>;
+
+  /**
+   * Scrape a webpage and take a screenshot
+   */
+  screenshot(url: string, options?: ScreenshotOptions): Promise<ScrapeResult>;
+
+  /**
+   * Extract content and answer questions using AI
+   */
+  analyze(url: string, question: string, options?: AnalyzeOptions): Promise<AnalyzeResult>;
+
+  /**
+   * Get account usage statistics
+   */
+  getUsage(days?: number): Promise<UsageResult>;
+
+  /**
+   * Check API health and your account status
+   */
+  healthCheck(): Promise<HealthResult>;
+}
+
+/**
+ * Convenience function for quick scraping without instantiating a client
+ */
+export declare function quickScrape(
+  url: string, 
+  apiKey: string, 
+  options?: ScrapeOptions
+): Promise<ScrapeResult>;
+
+/**
+ * Convenience function for taking screenshots
+ */
+export declare function quickScreenshot(
+  url: string, 
+  apiKey: string, 
+  options?: ScreenshotOptions
+): Promise<ScrapeResult>;
+
+/**
+ * Convenience function for AI analysis
+ */
+export declare function quickAnalyze(
+  url: string, 
+  question: string, 
+  apiKey: string, 
+  options?: AnalyzeOptions
+): Promise<AnalyzeResult>;
+
+export default BrowserNativeClient;

package/index.js

@@ -0,0 +1,208 @@
+/**
+ * Browser Native Client SDK
+ * 
+ * A lightweight JavaScript client for the Browser Native web scraping API.
+ * Works in browsers, Node.js, and edge environments.
+ */
+
+export class BrowserNativeClient {
+  constructor(apiKey, options = {}) {
+    if (!apiKey) {
+      throw new Error('API key is required. Get one at https://browsernative.monostate.ai');
+    }
+    
+    this.apiKey = apiKey;
+    this.baseUrl = options.baseUrl || 'https://bnca-api.fly.dev';
+    this.timeout = options.timeout || 30000;
+    this.retries = options.retries || 2;
+    this.verbose = options.verbose || false;
+  }
+
+  /**
+   * Scrape a webpage and extract structured content
+   * @param {string} url - The URL to scrape
+   * @param {object} options - Scraping options
+   * @returns {Promise<object>} Scraping result
+   */
+  async scrape(url, options = {}) {
+    const payload = {
+      url,
+      screenshot: options.includeScreenshot || false,
+      ...options
+    };
+
+    return this._makeRequest('/scrapeurl', payload);
+  }
+
+  /**
+   * Scrape a webpage and take a screenshot
+   * @param {string} url - The URL to scrape
+   * @param {object} options - Screenshot options
+   * @returns {Promise<object>} Screenshot result with base64 image
+   */
+  async screenshot(url, options = {}) {
+    const payload = {
+      url,
+      screenshot: true,
+      ...options
+    };
+
+    return this._makeRequest('/scrapeurl', payload);
+  }
+
+  /**
+   * Extract content and answer questions using AI
+   * @param {string} url - The URL to analyze
+   * @param {string} question - The question to answer
+   * @param {object} options - Analysis options
+   * @returns {Promise<object>} AI analysis result
+   */
+  async analyze(url, question, options = {}) {
+    const payload = {
+      url,
+      question,
+      screenshot: options.includeScreenshot || false,
+      ...options
+    };
+
+    return this._makeRequest('/aireply', payload);
+  }
+
+  /**
+   * Get account usage statistics
+   * @param {number} days - Number of days to fetch (max 30)
+   * @returns {Promise<object>} Usage statistics
+   */
+  async getUsage(days = 30) {
+    return this._makeRequest('/stats', {}, 'GET');
+  }
+
+  /**
+   * Check API health and your account status
+   * @returns {Promise<object>} Health check result
+   */
+  async healthCheck() {
+    return this._makeRequest('/health', {}, 'GET');
+  }
+
+  /**
+   * Make an authenticated request to the API
+   * @private
+   */
+  async _makeRequest(endpoint, payload = {}, method = 'POST', queryParams = '') {
+    const url = `${this.baseUrl}${endpoint}${queryParams}`;
+    const startTime = Date.now();
+
+    let lastError;
+    
+    for (let attempt = 1; attempt <= this.retries + 1; attempt++) {
+      try {
+        if (this.verbose) {
+          console.log(`Browser Native: ${method} ${url} (attempt ${attempt})`);
+        }
+
+        const options = {
+          method,
+          headers: {
+            'Authorization': `Bearer ${this.apiKey}`,
+            'Content-Type': 'application/json',
+            'User-Agent': 'Browser Native Client SDK/1.0.0'
+          }
+        };
+
+        if (method !== 'GET') {
+          options.body = JSON.stringify(payload);
+        }
+
+        // Set up timeout
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        options.signal = controller.signal;
+
+        const response = await fetch(url, options);
+        clearTimeout(timeoutId);
+
+        const responseTime = Date.now() - startTime;
+
+        if (!response.ok) {
+          const errorData = await response.json().catch(() => ({ error: 'Unknown error' }));
+          throw new Error(`API Error (${response.status}): ${errorData.error || response.statusText}`);
+        }
+
+        const data = await response.json();
+        
+        if (this.verbose) {
+          console.log(`Browser Native: Request completed in ${responseTime}ms`);
+        }
+
+        return {
+          success: true,
+          data,
+          responseTime,
+          attempt
+        };
+
+      } catch (error) {
+        lastError = error;
+        
+        if (attempt <= this.retries && !error.name === 'AbortError') {
+          const delay = Math.pow(2, attempt - 1) * 1000; // Exponential backoff
+          if (this.verbose) {
+            console.log(`Browser Native: Attempt ${attempt} failed, retrying in ${delay}ms...`);
+          }
+          await new Promise(resolve => setTimeout(resolve, delay));
+          continue;
+        }
+        
+        break;
+      }
+    }
+
+    // All retries failed
+    return {
+      success: false,
+      error: lastError.message || 'Request failed',
+      responseTime: Date.now() - startTime
+    };
+  }
+}
+
+/**
+ * Convenience function for quick scraping without instantiating a client
+ * @param {string} url - The URL to scrape
+ * @param {string} apiKey - Your API key
+ * @param {object} options - Additional options
+ * @returns {Promise<object>} Scraping result
+ */
+export async function quickScrape(url, apiKey, options = {}) {
+  const client = new BrowserNativeClient(apiKey, options);
+  return client.scrape(url, options);
+}
+
+/**
+ * Convenience function for taking screenshots
+ * @param {string} url - The URL to capture
+ * @param {string} apiKey - Your API key
+ * @param {object} options - Additional options
+ * @returns {Promise<object>} Screenshot result
+ */
+export async function quickScreenshot(url, apiKey, options = {}) {
+  const client = new BrowserNativeClient(apiKey, options);
+  return client.screenshot(url, options);
+}
+
+/**
+ * Convenience function for AI analysis
+ * @param {string} url - The URL to analyze
+ * @param {string} question - The question to answer
+ * @param {string} apiKey - Your API key
+ * @param {object} options - Additional options
+ * @returns {Promise<object>} Analysis result
+ */
+export async function quickAnalyze(url, question, apiKey, options = {}) {
+  const client = new BrowserNativeClient(apiKey, options);
+  return client.analyze(url, question, options);
+}
+
+// Default export for CommonJS compatibility
+export default BrowserNativeClient;

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@monostate/browsernative-client",
+  "version": "1.0.1",
+  "description": "Browser Native client SDK for web scraping and content extraction API",
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./index.js",
+      "types": "./index.d.ts"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md",
+    "package.json"
+  ],
+  "keywords": [
+    "web-scraping",
+    "api-client",
+    "browser-native",
+    "content-extraction",
+    "web-automation",
+    "data-extraction",
+    "javascript",
+    "typescript",
+    "browser",
+    "client-sdk"
+  ],
+  "author": "Browser Native Team",
+  "license": "MIT",
+  "dependencies": {},
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/browsernative/client-sdk.git"
+  },
+  "bugs": {
+    "url": "https://github.com/browsernative/client-sdk/issues"
+  },
+  "homepage": "https://browsernative.monostate.ai",
+  "publishConfig": {
+    "access": "public"
+  }
+}