Package Exports

@monitoro/herd
@monitoro/herd/dist/src/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@monitoro/herd) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Herd SDK

A powerful SDK for controlling your own browser and other devices through the Herd platform, whether it's one browser or a fleet of millions. Similar to Puppeteer but with support for multiple devices and real-time events, and no infrastructure to setup.

Learn more at https://herd.garden.

Features

🌐 Control multiple browsers and devices from a single client
⛏️ Extract data from web pages
🔍 Run automations and interact with webpages
🤖 Build AI web tools and MCP servers
🚀 Familiar automation API similar to Puppeteer
🧩 TypeScript support with full type definitions

Installation

npm install @monitoro/herd
# or
yarn add @monitoro/herd

Quick Start

import { HerdClient } from '@monitoro/herd';

async function example() {
    // Create a client
    const client = new HerdClient({
        token: 'your-auth-token'
    });

    // List available devices
    const devices = await client.devices();
    console.log('Available devices:', devices);

    // Get a specific device
    const device = await client.device('device-id');

    // Create a new page
    const page = await device.newPage();

    // Navigate to a URL
    await page.goto('https://example.com');

    // Wait for element and click
    await page.waitForElement('#login-button');
    await page.click('#login-button');

    // Fill a form
    await page.fill('#username', 'testuser');
    await page.fill('#password', 'password');
    await page.click('#submit');

    // Extract data
    const data = await page.extract({
        title: 'h1',
        description: '.description',
        items: {
            price: '.item-price',
            name: '.item-name'
        }
    });

    console.log('Extracted data:', data);

    // Cleanup
    await page.close();
    await device.close();
}

MCP Server

Herd can be used build MCP servers for the website of your choice, using your web accounts without setting up any infrastructure nor sharing your credentials with anyone.

Learn more at https://herd.garden/docs/reference-mcp-server.

import { HerdMcpServer } from '@monitoro/herd';

const server = new HerdMcpServer({
    info: {
        name: "social-assistant",
        version: "1.0.0",
        description: "Social media automation tools for LLMs"
    },
    transport: {
        type: "sse",
        port: 3000
    },
    herd: {
        token: "your-herd-token"  // Get from herd.garden
    }
});

// Start the server
await server.start();

API Reference

Docs available at https://herd.garden/docs.

HerdClient

The main client for interacting with the Herd platform.

const client = new HerdClient({
    token: 'your-auth-token'
});

// List devices
const devices = await client.devices();

// Get specific device
const device = await client.device('device-id');

// Register new device and get a registration url
const result = await client.registerDevice({
    deviceId: 'my-device',
    name: 'Laptop Browser',
    type: 'browser'
});

Device

Represents a connected device (browser or headless).

// Create new page
const page = await device.newPage();

// List all pages
const pages = await device.pages();

// Subscribe to device events
device.onEvent((event) => {
    console.log('Device event:', event);
});

// Close device
await device.close();

Page

Provides browser automation functionality similar to Puppeteer's Page class.

// Navigation
await page.goto('https://example.com');
await page.back();
await page.forward();
await page.reload();

// Element interaction
await page.click('#button', { button: 'left', clickCount: 1 });
await page.fill('#input', 'text', { clearFirst: true });

// Finding elements
const element = await page.find('.selector', { visible: true });

// Waiting
await page.waitForElement('.selector', { state: 'visible' });
await page.waitForNavigation('networkidle0');

// JavaScript evaluation
const result = await page.evaluate(() => document.title);

// Data extraction
const data = await page.extract({
    title: 'h1',
    items: '.item'
});

// Event subscription
const unsubscribe = page.onEvent((event) => {
    console.log('Page event:', event);
});

// Cleanup
unsubscribe();
await page.close();

Events

The SDK provides real-time events for various actions:

Device status changes
Page navigation
DOM mutations
Network activity
Console messages
JavaScript errors

Subscribe to events using the onEvent method:

// Device events
device.onEvent((event) => {
    console.log('Device event:', event);
});

// Page events
page.onEvent((event) => {
    console.log('Page event:', event);
});

// Specific event
device.on('status', (event) => {
    console.log('Status changed:', event);
});

Error Handling

The SDK uses standard error handling patterns:

try {
    await page.click('#non-existent');
} catch (error) {
    if (error.code === 'ELEMENT_NOT_FOUND') {
        console.error('Element not found');
    } else {
        console.error('Other error:', error);
    }
}

TypeScript Support

The SDK is written in TypeScript and provides full type definitions:

import { HerdClient, Device, Page, FindOptions } from '@herd/sdk';

const options: FindOptions = {
    timeout: 5000,
    visible: true
};

const element = await page.find('.selector', options);

License

This project is licensed under a EULA - see the LICENSE file for details.

@monitoro/herd