@monitoro/herd/README.md

Automate your browser, build AI web tools and MCP servers with Monitoro Herd

# Herd SDK

<img src="https://herd.garden/logo.png" alt="Herd" width="200"/>

A powerful SDK for controlling your own browser and other devices through the [Herd](https://herd.garden) 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](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

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

## Quick Start

```typescript
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](https://herd.garden/docs/reference-mcp-server).

```typescript
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](https://herd.garden/docs).

### HerdClient

The main client for interacting with the Herd platform.

```typescript
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).

```typescript
// 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.

```typescript
// 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 options: FindOptions = {
    timeout: 5000,
    visible: true
};
const element = await page.find('.selector', options);

// 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:

```typescript
// 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:

```typescript
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:

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

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

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

## Trails

Trails are packaged automations that can be shared, reused, and published to the Herd registry.

### Using Trails

Search and discover available trails using the CLI:

```bash
# Search for trails in the registry
herd trail search --query "login"

# Get detailed information about a specific trail
herd trail info @organization/trail-name

# View a trail's manifest
herd trail manifest @organization/trail-name

# Run a trail
herd trail run @organization/trail-name -a login

# Run a specific version of a trail
herd trail run @organization/trail-name -v 1.2.0 -a login
```

### Creating Trails

Create and publish your own trails:

```bash
# Initialize a new trail in the current directory
herd trail init

# Build the trail
herd trail build

# Test the trail
herd trail test

# Publish the trail to the registry
herd trail publish --organization your-org-id
```

### Trail API

You can also use trails programmatically:

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

async function useTrail() {
    const client = new HerdClient();
    await client.initialize();
    
    // Get the trail engine
    const trailEngine = client.trails();
    
    // Load a trail from the registry
    const { actions, resources } = await trailEngine.loadTrail('@organization/trail-name');
    
    // Run an action from the trail
    const result = await trailEngine.runTrail('@organization/trail-name', {
        actionName: 'login',
        params: {
            username: 'user',
            password: 'pass'
        }
    });
    
    console.log('Action result:', result);
}
```

## License

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

## Copyright

Copyright (c) 2025 Monitoro, Omneity Labs.