illuma-rpa

Cross-platform desktop automation for Node.js. Control mouse, keyboard, and capture screenshots programmatically.

Features

• 🖱️ Mouse control - move, click, double-click, drag, scroll
• ⌨️ Keyboard control - type text, press keys, key combinations
• 📸 Screen capture - full screen or region screenshots
• 🪟 Window management - get active window, list windows, focus, resize
• 🌐 Cross-platform - Windows, macOS, Linux (x64 & ARM64)
• ⚡ Pre-built binaries - no compilation required

Installation

npm install illuma-rpa

Quick Start

import { mouse, keyboard, screen, Key } from 'illuma-rpa';

// Move mouse to position
await mouse.moveTo(100, 200);

// Click
await mouse.click();
await mouse.click('right');
await mouse.doubleClick();

// Drag
await mouse.drag(100, 100, 300, 300);

// Scroll
await mouse.scroll('down', 3);

// Type text
await keyboard.type('Hello, World!');

// Press keys
await keyboard.press(Key.Enter);
await keyboard.press(Key.Ctrl, Key.C);  // Ctrl+C

// Take screenshot
const screenshot = await screen.capture();
console.log(`Screenshot: ${screenshot.width}x${screenshot.height}`);

// Capture region
const region = await screen.captureRegion(0, 0, 500, 500);

API Reference

Mouse

import { mouse } from 'illuma-rpa';

// Move
await mouse.moveTo(x, y);
await mouse.moveSmooth(x, y);  // Smooth movement

// Click
await mouse.click();                    // Left click
await mouse.click('right');             // Right click
await mouse.click('middle');            // Middle click
await mouse.doubleClick();

// Drag
await mouse.drag(startX, startY, endX, endY);

// Scroll
await mouse.scroll('up', 3);
await mouse.scroll('down', 3);

// Get position
const pos = mouse.getPosition();
console.log(pos.x, pos.y);

Keyboard

import { keyboard, Key } from 'illuma-rpa';

// Type text
await keyboard.type('Hello');
await keyboard.typeDelayed('Hello', 50);  // 50ms between chars

// Press single key
await keyboard.press(Key.Enter);
await keyboard.press(Key.Tab);

// Key combinations
await keyboard.press(Key.Ctrl, Key.C);     // Copy
await keyboard.press(Key.Ctrl, Key.V);     // Paste
await keyboard.press(Key.Alt, Key.Tab);    // Switch window

// Hold and release
await keyboard.hold(Key.Shift);
await keyboard.type('hello');  // Types "HELLO"
await keyboard.release(Key.Shift);

Screen

import { screen } from 'illuma-rpa';

// Full screenshot
const shot = await screen.capture();
console.log(shot.width, shot.height);
console.log(shot.image);  // Raw pixel buffer

// Region screenshot
const region = await screen.captureRegion(x, y, width, height);

// Get screen size
const size = screen.getSize();
console.log(size.width, size.height);

Window

import { window } from 'illuma-rpa';

// Get active window
const active = await window.getActive();
console.log(active.title);

// List all windows
const windows = await window.getAll();

// Focus window
await window.focus(windowHandle);

// Resize/move window
await window.resize(handle, { width: 800, height: 600 });
await window.move(handle, { x: 100, y: 100 });

Key Reference

import { Key } from 'illuma-rpa';

// Modifiers
Key.Ctrl, Key.Alt, Key.Shift, Key.Meta (Win/Cmd)

// Navigation
Key.Up, Key.Down, Key.Left, Key.Right
Key.Home, Key.End, Key.PageUp, Key.PageDown

// Editing
Key.Enter, Key.Tab, Key.Backspace, Key.Delete, Key.Escape, Key.Space

// Function keys
Key.F1, Key.F2, ... Key.F12

Use with Electron

// In Electron main process
import { mouse, keyboard, screen } from 'illuma-rpa';

ipcMain.handle('click', async (_, x, y) => {
  await mouse.moveTo(x, y);
  await mouse.click();
});

ipcMain.handle('screenshot', async () => {
  return await screen.capture();
});

Building from Source

If you need to build the native binaries yourself:

# Prerequisites:
# Windows: npm install -g windows-build-tools
# macOS: xcode-select --install
# Linux: sudo apt-get install cmake libxtst-dev libpng++-dev

cd libnut-core
npm install
npm run build:release

License

Apache-2.0

Based on libnut-core and nut.js.