Device

You can obtain a Device instance either by calling client.listDevices() to get all available devices, or client.getDevice(deviceId) to get a specific device by its ID.

Properties

deviceId

The unique identifier for the device in the Herd platform. This is an internal ID that uniquely identifies the device in our system and is automatically generated when the device is registered.

type

The type of device, which indicates its capabilities and behavior. Currently supported types include:

• ‘browser’: A browser instance that can be automated
• ‘headless’: A headless browser instance running on docker or kubernetes

name

An optional display name for the device. This can be used to give the device a human-readable label for easier identification in your application or the Herd dashboard.

status

The current status of the device. Possible values include:

• ‘online’: The device is connected and ready to receive commands
• ‘offline’: The device is not currently connected
• ‘busy’: The device is processing a command
• ‘error’: The device encountered an error

lastActive

A timestamp indicating when the device was last active. This is automatically updated whenever the device performs an action or responds to a command. The value is a JavaScript Date object.

Methods

newPage()

Creates a new page (tab) in the device.

// Create a new page
const page = await device.newPage();
console.log('New page created:', page.id);

listPages()

Returns a list of all pages (tabs) currently open in the device.

// List all open pages
const pages = await device.listPages();
pages.forEach(page => {
    console.log(`Page ${page.id}: ${page.url}`);
});

getPage(pageId)

Gets a specific page by ID.

// Get a specific page
const page = await device.getPage(123);
console.log('Current URL:', page.url);

onEvent(callback)

Subscribes to all events from the device. Returns an unsubscribe function.

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

// Later: stop listening to events
unsubscribe();

on(eventName, callback)

Subscribes to a specific event from the device. Returns the device instance for chaining.

// Subscribe to specific events
device.on('navigation', (event) => {
    console.log('Navigation occurred:', event);
}).on('console', (event) => {
    console.log('Console message:', event);
});

close()

Closes the device and cleans up resources. This will close all pages and remove event listeners.

// Close the device and cleanup
await device.close();

Example Usage

Here’s a complete example showing how to use the Device class:

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

async function main() {
    const client = new HerdClient({
        token: 'your-auth-token'
    });
    
    await client.initialize();
    
    // Get a device
    const device = await client.getDevice('my-browser');
    
    // Create a new page and navigate
    const page = await device.newPage();
    await page.goto('https://example.com');
    
    // Listen for navigation events
    device.on('navigation', (event) => {
        console.log('Page navigated:', event.url);
    });
    
    // List all pages
    const pages = await device.listPages();
    console.log(`Device has ${pages.length} pages open`);
    
    // Cleanup when done
    await device.close();
    await client.close();
}

main().catch(console.error);