illuma-rpa 1.0.0

package/libnut-core/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "libnut",
+  "version": "2.7.1",
+  "description": "libnut is an N-API module for desktop automation with node",
+  "main": "index.js",
+  "typings": "index.d.ts",
+  "scripts": {
+    "clean": "cmake-js clean",
+    "patch": "node ./patch-packagename.js",
+    "build:debug": "cmake-js rebuild --CDCMAKE_OSX_ARCHITECTURES=\"arm64;x86_64\" --debug",
+    "build:release": "cmake-js rebuild --CDCMAKE_OSX_ARCHITECTURES=\"arm64;x86_64\"",
+    "prepublishOnly": "npm run build:release",
+    "publish:next": "npm publish --tag next"
+  },
+  "homepage": "https://nutjs.dev",
+  "author": {
+    "name": "dry Software UG (haftungsbeschränkt)",
+    "email": "info@dry.software",
+    "url": "https://dry.software"
+  },
+  "bugs": {
+    "url": "https://github.com/nut-tree/nut.js/issues"
+  },
+  "keywords": [
+    "GUI",
+    "Automation",
+    "mouse",
+    "keyboard",
+    "screenshot",
+    "image",
+    "desktop",
+    "screen",
+    "recognition",
+    "autohotkey"
+  ],
+  "license": "Apache-2.0",
+  "dependencies": {
+    "bindings": "1.5.0"
+  },
+  "devDependencies": {
+    "cmake-js": "7.3.0",
+    "node-addon-api": "7.1.0"
+  },
+  "optionalDependencies": {
+    "@nut-tree/node-mac-permissions": "2.2.1"
+  },
+  "engines": {
+    "node": ">=10.15.3"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ]
+}

package/libnut-core/patch-packagename.js

@@ -0,0 +1,18 @@
+const fs = require("fs");
+const { join } = require("path");
+
+if (process.env.CI) {
+  const filename = join(__dirname, "package.json");
+  const packageJson = require(filename);
+
+  const plattformPackageName = `@nut-tree/libnut-${process.platform}`;
+  packageJson.name = plattformPackageName;
+
+  try {
+    fs.writeFileSync(filename, JSON.stringify(packageJson, null, 2));
+  } catch (err) {
+    console.log(err);
+    process.exit(-1);
+  }
+  console.log(`Patched package name to '${plattformPackageName}'`);
+}

package/libnut-core/permissionCheck.js

@@ -0,0 +1,82 @@
+let libnut = require("bindings")("libnut");
+
+let hasScreenRecordingPermission = false;
+let hasAccessibilityPermission = false;
+
+try {
+    const permissions = require("@nut-tree/node-mac-permissions");
+
+    const wrapWithWarning = (message, nativeFunction) => (...args) => {
+        console.warn(message);
+        return nativeFunction(...args);
+    };
+
+    const askForAccessibility = (nativeFunction, functionName) => {
+        if (process.platform !== 'darwin' || hasAccessibilityPermission) {
+            return nativeFunction;
+        }
+        const accessibilityStatus = permissions.getAuthStatus("accessibility");
+
+        if (accessibilityStatus === 'authorized') {
+            hasAccessibilityPermission = true;
+            return nativeFunction;
+        } else if (accessibilityStatus === 'not determined' || accessibilityStatus === 'denied') {
+            permissions.askForAccessibilityAccess();
+            return wrapWithWarning(`##### WARNING! The application running this script tries to access accessibility features to execute ${functionName}! Please grant requested access and visit https://github.com/nut-tree/nut.js#macos for further information. #####`, nativeFunction);
+        }
+    }
+    const askForScreenRecording = (nativeFunction, functionName) => {
+        if (process.platform !== 'darwin' || hasScreenRecordingPermission) {
+            return nativeFunction;
+        }
+        const screenCaptureStatus = permissions.getAuthStatus("screen");
+
+        if (screenCaptureStatus === 'authorized') {
+            hasScreenRecordingPermission = true;
+            return nativeFunction;
+        } else if (screenCaptureStatus === 'not determined' || screenCaptureStatus === 'denied') {
+            permissions.askForScreenCaptureAccess();
+            return wrapWithWarning(`##### WARNING! The application running this script tries to screen recording features to execute ${functionName}! Please grant the requested access and visit https://github.com/nut-tree/nut.js#macos for further information. #####`, nativeFunction);
+        }
+    }
+
+    const accessibilityAccess = [
+        "dragMouse",
+        "moveMouse",
+        "getMousePos",
+        "mouseClick",
+        "mouseToggle",
+        "scrollMouse",
+        "keyTap",
+        "keyToggle",
+        "typeString",
+        "getScreenSize",
+        "highlight",
+        "captureScreen",
+        "getWindows",
+        "getActiveWindow",
+        "getWindowRect",
+        "getWindowTitle",
+        "focusWindow",
+        "resizeWindow"
+    ];
+    const screenCaptureAccess = [
+        "getWindowTitle",
+        "captureScreen",
+    ];
+
+    for (const functionName of accessibilityAccess) {
+        const originalFunction = libnut[functionName];
+        libnut[functionName] = (...args) => askForAccessibility(originalFunction, functionName)(...args);
+    }
+    for (const functionName of screenCaptureAccess) {
+        const originalFunction = libnut[functionName];
+        libnut[functionName] = (...args) => askForScreenRecording(originalFunction, functionName)(...args);
+    }
+} catch (e) {
+    console.warn(`Encountered error establishing macOS permission checks:`, e.message);
+    console.warn(`Returning original module.`);
+    libnut = require("bindings")("libnut");
+} finally {
+    module.exports = libnut;
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "illuma-rpa",
+  "version": "1.0.0",
+  "description": "Cross-platform desktop automation for Node.js - mouse, keyboard, screen capture",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "license": "Apache-2.0",
+  "author": "Illuma",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/illuma-ai/illuma-rpa.git"
+  },
+  "homepage": "https://github.com/illuma-ai/illuma-rpa",
+  "bugs": {
+    "url": "https://github.com/illuma-ai/illuma-rpa/issues"
+  },
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "pnpm run clean && tsc -p .",
+    "build:native": "cd libnut-core && npm run build:release",
+    "test": "jest",
+    "prepublishOnly": "pnpm run build",
+    "publish:npm": "npm publish --access public"
+  },
+  "keywords": [
+    "automation",
+    "desktop",
+    "rpa",
+    "mouse",
+    "keyboard",
+    "screenshot",
+    "screen",
+    "ui-automation",
+    "robot",
+    "native",
+    "electron"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "os": [
+    "win32",
+    "darwin",
+    "linux"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "dependencies": {
+    "jimp": "0.22.10"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "rimraf": "^5.0.0",
+    "typescript": "^5.3.0",
+    "jest": "^29.7.0",
+    "@types/jest": "^29.5.0",
+    "ts-jest": "^29.1.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+/**
+ * illuma-rpa
+ * Cross-platform desktop automation for Node.js
+ */
+
+export { mouse, Mouse } from './mouse';
+export { keyboard, Keyboard, Key } from './keyboard';
+export { screen, Screen, Screenshot } from './screen';
+export { window, Window, WindowInfo } from './window';
+export { loadNativeBinding } from './native';

package/src/keyboard.ts

@@ -0,0 +1,125 @@
+/**
+ * Keyboard control module
+ */
+
+import { getNative } from './native';
+
+/**
+ * Key constants for keyboard input
+ */
+export const Key = {
+  // Modifiers
+  Ctrl: 'control',
+  Control: 'control',
+  Alt: 'alt',
+  Shift: 'shift',
+  Meta: 'command',  // Win key on Windows, Cmd on macOS
+  Win: 'command',
+  Cmd: 'command',
+
+  // Navigation
+  Up: 'up',
+  Down: 'down',
+  Left: 'left',
+  Right: 'right',
+  Home: 'home',
+  End: 'end',
+  PageUp: 'pageup',
+  PageDown: 'pagedown',
+
+  // Editing
+  Enter: 'enter',
+  Return: 'enter',
+  Tab: 'tab',
+  Backspace: 'backspace',
+  Delete: 'delete',
+  Escape: 'escape',
+  Esc: 'escape',
+  Space: 'space',
+  Insert: 'insert',
+
+  // Function keys
+  F1: 'f1', F2: 'f2', F3: 'f3', F4: 'f4',
+  F5: 'f5', F6: 'f6', F7: 'f7', F8: 'f8',
+  F9: 'f9', F10: 'f10', F11: 'f11', F12: 'f12',
+
+  // Other
+  PrintScreen: 'printscreen',
+  CapsLock: 'capslock',
+  NumLock: 'numlock',
+  ScrollLock: 'scrolllock',
+} as const;
+
+export type KeyType = typeof Key[keyof typeof Key] | string;
+
+export class Keyboard {
+  private delay = 0;
+
+  /**
+   * Set delay between key presses (ms)
+   */
+  setDelay(ms: number): void {
+    this.delay = ms;
+    getNative().setKeyboardDelay(ms);
+  }
+
+  /**
+   * Type a string of text
+   */
+  async type(text: string): Promise<void> {
+    getNative().typeString(text);
+  }
+
+  /**
+   * Type text with delay between characters
+   */
+  async typeDelayed(text: string, delayMs: number = 50): Promise<void> {
+    // Convert delay to characters per minute
+    const cpm = Math.round(60000 / delayMs);
+    getNative().typeStringDelayed(text, cpm);
+  }
+
+  /**
+   * Press and release a key or key combination
+   */
+  async press(...keys: KeyType[]): Promise<void> {
+    if (keys.length === 0) return;
+
+    if (keys.length === 1) {
+      getNative().keyTap(keys[0]);
+    } else {
+      // Last key is the main key, others are modifiers
+      const mainKey = keys[keys.length - 1];
+      const modifiers = keys.slice(0, -1);
+      getNative().keyTap(mainKey, modifiers);
+    }
+  }
+
+  /**
+   * Hold a key down
+   */
+  async hold(...keys: KeyType[]): Promise<void> {
+    for (const key of keys) {
+      getNative().keyToggle(key, 'down');
+    }
+  }
+
+  /**
+   * Release a held key
+   */
+  async release(...keys: KeyType[]): Promise<void> {
+    for (const key of keys) {
+      getNative().keyToggle(key, 'up');
+    }
+  }
+
+  /**
+   * Press a key combination (e.g., Ctrl+C)
+   */
+  async combo(...keys: KeyType[]): Promise<void> {
+    await this.press(...keys);
+  }
+}
+
+// Export singleton instance
+export const keyboard = new Keyboard();

package/src/mouse.ts

@@ -0,0 +1,114 @@
+/**
+ * Mouse control module
+ */
+
+import { getNative } from './native';
+
+export interface Point {
+  x: number;
+  y: number;
+}
+
+export type MouseButton = 'left' | 'right' | 'middle';
+
+export class Mouse {
+  private delay = 10;
+
+  /**
+   * Set delay between mouse actions (ms)
+   */
+  setDelay(ms: number): void {
+    this.delay = ms;
+    getNative().setMouseDelay(ms);
+  }
+
+  /**
+   * Move mouse to absolute position
+   */
+  async moveTo(x: number, y: number): Promise<void> {
+    getNative().moveMouse(x, y);
+  }
+
+  /**
+   * Move mouse smoothly to position
+   */
+  async moveSmooth(x: number, y: number): Promise<void> {
+    getNative().moveMouseSmooth(x, y);
+  }
+
+  /**
+   * Click mouse button
+   */
+  async click(button: MouseButton = 'left'): Promise<void> {
+    getNative().mouseClick(button, false);
+  }
+
+  /**
+   * Double click
+   */
+  async doubleClick(button: MouseButton = 'left'): Promise<void> {
+    getNative().mouseClick(button, true);
+  }
+
+  /**
+   * Right click (convenience method)
+   */
+  async rightClick(): Promise<void> {
+    await this.click('right');
+  }
+
+  /**
+   * Press mouse button down
+   */
+  async down(button: MouseButton = 'left'): Promise<void> {
+    getNative().mouseToggle('down', button);
+  }
+
+  /**
+   * Release mouse button
+   */
+  async up(button: MouseButton = 'left'): Promise<void> {
+    getNative().mouseToggle('up', button);
+  }
+
+  /**
+   * Drag from current position to target
+   */
+  async drag(startX: number, startY: number, endX: number, endY: number): Promise<void> {
+    await this.moveTo(startX, startY);
+    await this.down();
+    await this.moveTo(endX, endY);
+    await this.up();
+  }
+
+  /**
+   * Drag to target from current position
+   */
+  async dragTo(x: number, y: number): Promise<void> {
+    getNative().dragMouse(x, y);
+  }
+
+  /**
+   * Scroll mouse wheel
+   */
+  async scroll(direction: 'up' | 'down' | 'left' | 'right', amount: number = 3): Promise<void> {
+    let x = 0, y = 0;
+    switch (direction) {
+      case 'up': y = amount; break;
+      case 'down': y = -amount; break;
+      case 'left': x = -amount; break;
+      case 'right': x = amount; break;
+    }
+    getNative().scrollMouse(x, y);
+  }
+
+  /**
+   * Get current mouse position
+   */
+  getPosition(): Point {
+    return getNative().getMousePos();
+  }
+}
+
+// Export singleton instance
+export const mouse = new Mouse();

package/src/native.ts

@@ -0,0 +1,103 @@
+/**
+ * Native binding loader
+ * Automatically loads the correct platform-specific binary
+ */
+
+import * as path from 'path';
+
+export interface NativeBinding {
+  // Keyboard
+  setKeyboardDelay(ms: number): void;
+  keyTap(key: string, modifier?: string | string[]): void;
+  keyToggle(key: string, down: string, modifier?: string | string[]): void;
+  typeString(str: string): void;
+  typeStringDelayed(str: string, cpm: number): void;
+
+  // Mouse
+  setMouseDelay(delay: number): void;
+  moveMouse(x: number, y: number): void;
+  moveMouseSmooth(x: number, y: number): void;
+  mouseClick(button?: string, double?: boolean): void;
+  mouseToggle(down?: string, button?: string): void;
+  dragMouse(x: number, y: number): void;
+  scrollMouse(x: number, y: number): void;
+  getMousePos(): { x: number; y: number };
+
+  // Screen
+  getScreenSize(): { width: number; height: number };
+  screen: {
+    capture(x?: number, y?: number, width?: number, height?: number): {
+      width: number;
+      height: number;
+      image: Buffer;
+      byteWidth: number;
+      bitsPerPixel: number;
+      bytesPerPixel: number;
+    };
+  };
+
+  // Window
+  getWindows(): number[];
+  getActiveWindow(): number;
+  getWindowRect(handle: number): { x: number; y: number; width: number; height: number };
+  getWindowTitle(handle: number): string;
+  focusWindow(handle: number): void;
+  resizeWindow(handle: number, size: { width: number; height: number }): void;
+  moveWindow(handle: number, pos: { x: number; y: number }): void;
+}
+
+let native: NativeBinding | null = null;
+
+/**
+ * Load the native binding for the current platform
+ */
+export function loadNativeBinding(): NativeBinding {
+  if (native) {
+    return native;
+  }
+
+  const platform = process.platform;
+  const arch = process.arch;
+  const packageName = `illuma-rpa-${platform}-${arch}`;
+
+  // Try loading from optional dependency
+  try {
+    native = require(packageName);
+    return native!;
+  } catch {
+    // Fallback: try loading from local build
+  }
+
+  // Try loading from local libnut-core build
+  const localPaths = [
+    path.join(__dirname, '../libnut-core/build/Release/libnut.node'),
+    path.join(__dirname, '../../libnut-core/build/Release/libnut.node'),
+    path.join(process.cwd(), 'libnut-core/build/Release/libnut.node'),
+  ];
+
+  for (const localPath of localPaths) {
+    try {
+      native = require(localPath);
+      return native!;
+    } catch {
+      continue;
+    }
+  }
+
+  throw new Error(
+    `Failed to load native binding for ${platform}-${arch}.\n` +
+    `Please ensure one of the following:\n` +
+    `  1. Install the platform package: npm install ${packageName}\n` +
+    `  2. Build from source: cd libnut-core && npm run build:release`
+  );
+}
+
+/**
+ * Get the native binding (lazy load)
+ */
+export function getNative(): NativeBinding {
+  if (!native) {
+    loadNativeBinding();
+  }
+  return native!;
+}

package/src/screen.ts

@@ -0,0 +1,59 @@
+/**
+ * Screen capture module
+ */
+
+import { getNative } from './native';
+
+export interface Screenshot {
+  width: number;
+  height: number;
+  image: Buffer;
+  byteWidth: number;
+  bitsPerPixel: number;
+  bytesPerPixel: number;
+}
+
+export interface ScreenSize {
+  width: number;
+  height: number;
+}
+
+export class Screen {
+  /**
+   * Capture the entire screen
+   */
+  async capture(): Promise<Screenshot> {
+    return getNative().screen.capture();
+  }
+
+  /**
+   * Capture a region of the screen
+   */
+  async captureRegion(x: number, y: number, width: number, height: number): Promise<Screenshot> {
+    return getNative().screen.capture(x, y, width, height);
+  }
+
+  /**
+   * Get the screen size
+   */
+  getSize(): ScreenSize {
+    return getNative().getScreenSize();
+  }
+
+  /**
+   * Get screen width
+   */
+  getWidth(): number {
+    return this.getSize().width;
+  }
+
+  /**
+   * Get screen height
+   */
+  getHeight(): number {
+    return this.getSize().height;
+  }
+}
+
+// Export singleton instance
+export const screen = new Screen();