Mac SDK

An SDK for automating macOS applications and system functions using JavaScript/TypeScript.

A modern, type-safe alternative to AppleScript for automating macOS applications and system functions using JavaScript/TypeScript.

Features

• 🚀 Modern JavaScript API - Write automation scripts using modern async/await syntax
• 🛠 TypeScript Support - Full type definitions for better development experience
• 🔌 Extensible Architecture - Easy to add support for new applications
• ⚡ Fast & Lightweight - No heavy dependencies or runtime overhead
• 🔒 Secure - Runs with user permissions, no kernel extensions required

Installation

npm install @mac-sdk/automation

Quick Start

import { Mac } from "@mac-sdk/automation";

async function main() {
  const mac = new Mac();

  // Open an application
  await mac.openApp("Safari");

  // Create a new note
  await mac.notes.create("Shopping List", "Milk\nEggs\nBread");

  // Take a screenshot
  await mac.screenshot("~/Desktop/screenshot.png");

  // Show a notification
  await mac.notification(
    "Task Complete",
    "Your automation finished successfully!"
  );
}

main().catch(console.error);

Core Concepts

1. Explorer

Comprehensive file system operations and system controls:

• File Management: Create, read, write, copy, move, and delete files
• Directory Operations: Create directories, list contents, find files by pattern
• System Controls: Clipboard, screenshots, notifications, text-to-speech
• Application Management: Launch applications by name

2. Built-in Apps

Pre-configured support for common applications:

• Notes
• VS Code

3. Extensibility

Easily add support for additional applications by extending the base classes.

API Reference

Mac Class

Main entry point for all automation tasks.

Methods

• app(name: string): Get an application instance by name
• copyToClipboard(text: string): Copy text to clipboard
• getClipboard(): Get current clipboard content
• screenshot(path?: string): Take a screenshot
• notification(title: string, message: string, sound?: string): Show a notification
• speak(text: string, voice?: string): Convert text to speech
• openApp(appName: string): Launch an application

Examples

File System Operations

const mac = new Mac();

// Create a project structure
await mac.system.createDirectory("my-project/src");
await mac.system.createFile(
  "my-project/package.json",
  JSON.stringify(
    {
      name: "my-project",
      version: "1.0.0",
    },
    null,
    2
  )
);

// Find all JavaScript files
const jsFiles = await mac.system.findFiles("**/*.js", "my-project");
console.log("Found JS files:", jsFiles);

// Copy project to backup
await mac.system.copy("my-project", "my-project-backup");

// Read and modify a file
const content = await mac.system.readFile("my-project/package.json");
const pkg = JSON.parse(content);
pkg.version = "1.0.1";
await mac.system.writeFile(
  "my-project/package.json",
  JSON.stringify(pkg, null, 2)
);

Open VS Code and create a new file

const mac = new Mac();
await mac.vscode.openFile("~/projects/new-project/hello.js");
await mac.vscode.type('console.log("Hello, Mac SDK!");');
await mac.vscode.save();

Create a note with formatted content

await mac.notes.create(
  "Meeting Notes",
  `# Team Sync

  ## Attendees
  - Alice
  - Bob
  - Charlie

  ## Action Items
  - [ ] Prepare presentation
  - [ ] Review PRs`
);

System Automation Workflow

const mac = new Mac();

// Take a screenshot
const screenshotPath = await mac.system.screenshot();

// Create a log file
await mac.system.writeFile(
  "automation.log",
  `Screenshot taken at ${new Date()}\n`
);

// Show notification
await mac.system.notification(
  "Automation Complete",
  "Screenshot saved successfully!"
);

// Speak confirmation
await mac.system.speak("Automation workflow completed successfully");

Contributing

Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with ❤️ by the Mac SDK Team
• Inspired by the need for better macOS automation tools