API Reference

Complete reference for all apple-js methods, parameters, and usage examples.

Complete Example

Here's a comprehensive example showcasing most apple-js features:

javascript

const { Osascript } = require("apple-js-stable");
const script = new Osascript();

async function startTest() {
    await script.executeScript([
        script.appleCommands.display("Welcome to apple.js, Glad to see you, shall we open chrome?"),
        script.appleCommands.speak("Welcome to apple js, shall we open chrome?"),
    ]);
    await script.executeSingleCommand(script.appleCommands.systemControl.screenshotToDesktop());
    await script.executeSingleCommand(script.appleCommands.fun.playSosumi()); 
    await script.executeScript([
        script.appleCommands.notifications.alertWithSound("Opsii Dubsii","Looks like Siri wants to tell joke.","Blow"),
        script.appleCommands.delay(3),
        script.appleCommands.ai.tellJoke(),
        script.appleCommands.notifications.alertWithSound("Apple-js version 1.0.4","Enjoy the new methods of apple-js","Glass"),
        script.appleCommands.delay(3),
        script.appleCommands.fun.dramaticAnnouncement("Holy Moly ! i am alive "),
        script.appleCommands.demoTypeHelloWorld(),
        script.appleCommands.speak("Are you impressed with apple js ?","Zarvox"),
        script.appleCommands.ui.typeText("Apple-js",0.5),
        script.appleCommands.notifications.alertWithSound("Apple-js version 1.0.4","Enjoy the latest version")
    ]);
}
startTest();

Core Methods

script.executeSingleCommand(command)

Executes a single AppleScript command and returns a Promise.

Parameters:

command - The AppleScript command to execute

Returns: Promise that resolves when the command completes

script.executeScript(commands)

Executes multiple AppleScript commands in sequence.

Parameters:

commands - Array of AppleScript commands to execute

Returns: Promise that resolves when all commands complete

Apple Commands

script.appleCommands.speak(text, voice?)

Makes your Mac speak the given text using text-to-speech.

Parameters:

text - The text to speak (required)
voice - Voice to use (optional, e.g., "Zarvox", "Alex")

javascript

// Basic speech
await script.executeSingleCommand(
    script.appleCommands.speak("Hello, world!")
);

// With custom voice
await script.executeSingleCommand(
    script.appleCommands.speak("Hello, world!", "Zarvox")
);

script.appleCommands.display(message, title?)

Shows a native macOS alert dialog.

Parameters:

message - The message to display (required)
title - The dialog title (optional)

javascript

// Simple alert
await script.executeSingleCommand(
    script.appleCommands.display("Hello from apple-js!")
);

// Alert with title and message
await script.executeSingleCommand(
    script.appleCommands.display("Welcome", "Hello from apple-js!")
);

script.appleCommands.delay(seconds)

Pauses execution for the specified number of seconds.

Parameters:

seconds - Number of seconds to delay (required)

javascript

// Delay execution
await script.executeSingleCommand(
    script.appleCommands.delay(3) // 3 seconds
);

Browser Commands

script.appleCommands.browser.openChrome(url?)

Opens Google Chrome browser, optionally navigating to a specific URL.

Parameters:

url - URL to open in Chrome (optional)

javascript

// Open Chrome
await script.executeSingleCommand(
    script.appleCommands.browser.openChrome()
);

// Open URL in Chrome
await script.executeSingleCommand(
    script.appleCommands.browser.openChrome("https://github.com")
);

System Control

script.appleCommands.systemControl.screenshotToDesktop()

Takes a screenshot and saves it to the desktop.

javascript

// Take screenshot
await script.executeSingleCommand(
    script.appleCommands.systemControl.screenshotToDesktop()
);

// Play system sound
await script.executeSingleCommand(
    script.appleCommands.fun.playSosumi()
);

Notifications

script.appleCommands.notifications.alertWithSound(title, message, sound)

Shows a notification alert with a custom sound.

Parameters:

title - Alert title (required)
message - Alert message (required)
sound - Sound name (required)

javascript

// Simple alert with sound
await script.executeSingleCommand(
    script.appleCommands.notifications.alertWithSound("Title", "Message", "Glass")
);

// Available sounds: Glass, Basso, Blow, Bottle, Frog, Funk, Hero, Morse, Ping, Pop, Purr, Sosumi, Submarine, Tink

AI Commands

script.appleCommands.ai.tellJoke()

Makes Siri tell a random joke.

javascript

// Tell a joke
await script.executeSingleCommand(
    script.appleCommands.ai.tellJoke()
);

UI Commands

script.appleCommands.ui.typeText(text, delay?)

Types text into the currently focused application.

Parameters:

text - Text to type (required)
delay - Delay between keystrokes in seconds (optional)

javascript

// Type text with delay
await script.executeSingleCommand(
    script.appleCommands.ui.typeText("Hello, World!", 0.5)
);

// Demo typing
await script.executeSingleCommand(
    script.appleCommands.demoTypeHelloWorld()
);

Fun Commands

script.appleCommands.fun.playSosumi()

Plays the classic Mac "Sosumi" sound.

script.appleCommands.fun.dramaticAnnouncement(text)

Makes a dramatic announcement with special effects.

Parameters:

text - Text for the announcement (required)

script.appleCommands.demoTypeHelloWorld()

Demonstrates typing "Hello, World!" with a delay effect.

javascript

// Play Sosumi sound
await script.executeSingleCommand(
    script.appleCommands.fun.playSosumi()
);

// Dramatic announcement
await script.executeSingleCommand(
    script.appleCommands.fun.dramaticAnnouncement("Holy Moly! I am alive!")
);

Execution Examples

javascript

// Execute single command
await script.executeSingleCommand(
    script.appleCommands.speak("Hello!")
);

// Execute multiple commands
await script.executeScript([
    script.appleCommands.display("Welcome!"),
    script.appleCommands.speak("Hello!"),
    script.appleCommands.delay(2)
]);