applescript-node 1.0.1

package/dist/languages.d.ts

@@ -0,0 +1,61 @@
+export interface OsaLanguageInfo {
+    name: string;
+    subtype: string;
+    manufacturer: string;
+    capabilities: {
+        compiling: boolean;
+        sourceData: boolean;
+        coercion: boolean;
+        eventHandling: boolean;
+        recording: boolean;
+        convenience: boolean;
+        dialects: boolean;
+        appleEvents: boolean;
+    };
+    description?: string;
+}
+/**
+ * Get all installed OSA (Open Scripting Architecture) languages
+ *
+ * **IMPORTANT: Empty Output Handling**
+ *
+ * This function includes critical handling for edge cases:
+ *
+ * 1. **Empty Output**: When `osalang -L` returns empty output (e.g., on systems
+ *    with no languages installed, or in test environments), the function:
+ *    - Filters out empty lines to prevent parsing errors
+ *    - Returns an empty array instead of crashing
+ *
+ * 2. **Missing Flags**: When a language line doesn't have capability flags:
+ *    - Defaults to empty string for flags parameter
+ *    - parseCapabilityFlags() safely handles empty strings (all capabilities false)
+ *
+ * 3. **Why This Matters**: Without proper empty output handling:
+ *    - Empty stdout would cause split() to return [''], leading to parsing errors
+ *    - Missing flags would cause undefined access in parseCapabilityFlags()
+ *    - Tests and edge cases would fail unpredictably
+ *
+ * **Usage Example:**
+ * ```typescript
+ * const languages = await getInstalledLanguages();
+ * if (languages.length === 0) {
+ *   console.warn('No OSA languages found');
+ * } else {
+ *   languages.forEach(lang => console.log(`${lang.name}: ${lang.capabilities}`));
+ * }
+ * ```
+ *
+ * **Testing Considerations:**
+ * - Always test with empty output (simulates edge cases)
+ * - Test with malformed lines (missing flags, etc.)
+ * - Verify empty arrays are returned gracefully
+ * - Ensure parseCapabilityFlags handles empty strings safely
+ *
+ * @returns Promise resolving to array of language information objects
+ * @throws Never throws - always returns array (empty if no languages found)
+ *
+ * @see {@link OsaLanguageInfo} for the language information structure
+ * @see {@link parseCapabilityFlags} for capability flag parsing
+ */
+export declare function getInstalledLanguages(): Promise<OsaLanguageInfo[]>;
+export declare function getDefaultLanguage(): Promise<OsaLanguageInfo>;

package/dist/loader.d.ts

@@ -0,0 +1,24 @@
+import { AppleScriptBuilder } from './builder.js';
+/**
+ * Load an AppleScript file and return a builder instance that can be edited further.
+ * The script is parsed to maintain proper block structure (tell, if, repeat, etc.)
+ * so you can continue adding commands using the fluent builder API.
+ *
+ * @param filePath Absolute or relative path to the AppleScript (.applescript or .scpt) file
+ * @returns Promise that resolves to an AppleScriptBuilder instance with the loaded script
+ * @throws Error if the file cannot be read
+ *
+ * @example
+ * ```typescript
+ * // Load an existing script and append new commands
+ * const script = await loadScript('./my-script.applescript');
+ * script
+ *   .tell('Finder')
+ *   .displayDialog('Script loaded and extended!')
+ *   .endtell();
+ *
+ * const result = await runScript(script);
+ * console.log(result.output);
+ * ```
+ */
+export declare function loadScript(filePath: string): Promise<AppleScriptBuilder>;

package/dist/sdef.d.ts

@@ -0,0 +1,50 @@
+import type { ApplicationDictionary, Class, Command } from './types.js';
+/**
+ * Extract the scripting definition (sdef) XML for a macOS application
+ * @param appPath - Path to the application (e.g., '/System/Applications/Messages.app')
+ * @returns Promise resolving to the sdef XML string
+ */
+export declare function getSdef(appPath: string): Promise<string>;
+/**
+ * Parse sdef XML into a structured ApplicationDictionary
+ * @param xml - The sdef XML string to parse
+ * @returns Parsed ApplicationDictionary
+ */
+export declare function parseSdef(xml: string): ApplicationDictionary;
+/**
+ * Get and parse the application dictionary for a macOS application
+ * @param appPath - Path to the application (e.g., '/System/Applications/Messages.app')
+ * @param useCache - Whether to use cached results (default: true)
+ * @returns Promise resolving to the parsed ApplicationDictionary
+ */
+export declare function getApplicationDictionary(appPath: string, useCache?: boolean): Promise<ApplicationDictionary>;
+/**
+ * Clear the sdef cache
+ */
+export declare function clearSdefCache(): void;
+/**
+ * Get a list of all commands in an application dictionary
+ * @param dictionary - The application dictionary
+ * @returns Array of all commands from all suites
+ */
+export declare function getAllCommands(dictionary: ApplicationDictionary): Command[];
+/**
+ * Get a list of all classes in an application dictionary
+ * @param dictionary - The application dictionary
+ * @returns Array of all classes from all suites
+ */
+export declare function getAllClasses(dictionary: ApplicationDictionary): Class[];
+/**
+ * Find a command by name in an application dictionary
+ * @param dictionary - The application dictionary
+ * @param commandName - The name of the command to find
+ * @returns The command if found, undefined otherwise
+ */
+export declare function findCommand(dictionary: ApplicationDictionary, commandName: string): Command | undefined;
+/**
+ * Find a class by name in an application dictionary
+ * @param dictionary - The application dictionary
+ * @param className - The name of the class to find
+ * @returns The class if found, undefined otherwise
+ */
+export declare function findClass(dictionary: ApplicationDictionary, className: string): Class | undefined;

package/dist/sources/applications.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Application information returned from macOS
+ */
+export interface ApplicationInfo {
+    name: string;
+    bundleId: string;
+    pid: number;
+    visible: boolean;
+    frontmost: boolean;
+    windowCount: number;
+}
+/**
+ * Get all running applications
+ * @param includeBackgroundApps - Include background-only applications (default: false)
+ * @returns Array of running application information
+ *
+ * @example
+ * import { applications } from 'applescript-node/sources';
+ * const apps = await applications.getAll();
+ * console.log(`Found ${apps.length} running applications`);
+ */
+export declare function getAll(includeBackgroundApps?: boolean): Promise<ApplicationInfo[]>;
+/**
+ * Get the frontmost (focused) application
+ * @returns The currently focused application
+ *
+ * @example
+ * import { applications } from 'applescript-node/sources';
+ * const frontApp = await applications.getFrontmost();
+ * console.log(`Active application: ${frontApp.name}`);
+ */
+export declare function getFrontmost(): Promise<ApplicationInfo>;
+/**
+ * Check if an application is running
+ * @param appName - Name of the application to check
+ * @returns True if the application is running, false otherwise
+ *
+ * @example
+ * import { applications } from 'applescript-node/sources';
+ * if (await applications.isRunning('Safari')) {
+ *   console.log('Safari is running');
+ * }
+ */
+export declare function isRunning(appName: string): Promise<boolean>;
+/**
+ * Get application by name
+ * @param appName - Name of the application
+ * @returns Application information, or null if not running
+ *
+ * @example
+ * import { applications } from 'applescript-node/sources';
+ * const safari = await applications.getByName('Safari');
+ * if (safari) {
+ *   console.log(`Safari PID: ${safari.pid}`);
+ * }
+ */
+export declare function getByName(appName: string): Promise<ApplicationInfo | null>;
+/**
+ * Activate (bring to front) an application
+ * @param appName - Name of the application to activate
+ *
+ * @example
+ * import { applications } from 'applescript-node/sources';
+ * await applications.activate('Safari');
+ */
+export declare function activate(appName: string): Promise<void>;
+/**
+ * Launch an application without activating it
+ * @param appName - Name of the application to launch
+ *
+ * @example
+ * import { applications } from 'applescript-node/sources';
+ * await applications.launch('Calendar');
+ */
+export declare function launch(appName: string): Promise<void>;
+/**
+ * Quit an application
+ * @param appName - Name of the application to quit
+ *
+ * @example
+ * import { applications } from 'applescript-node/sources';
+ * await applications.quit('TextEdit');
+ */
+export declare function quit(appName: string): Promise<void>;
+/**
+ * Hide an application
+ * @param appName - Name of the application to hide
+ *
+ * @example
+ * import { applications } from 'applescript-node/sources';
+ * await applications.hide('Safari');
+ */
+export declare function hide(appName: string): Promise<void>;
+/**
+ * Show (unhide) an application
+ * @param appName - Name of the application to show
+ *
+ * @example
+ * import { applications } from 'applescript-node/sources';
+ * await applications.show('Safari');
+ */
+export declare function show(appName: string): Promise<void>;

package/dist/sources/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * High-level data source APIs for common macOS operations.
+ *
+ * These modules provide clean, succinct entry points for typical macOS data sourcing tasks.
+ * Each module wraps the low-level builder API to provide simple, async functions.
+ *
+ * @example
+ * // Get all open windows across all applications
+ * import { windows } from 'applescript-node/sources';
+ * const allWindows = await windows.getAll();
+ *
+ * @example
+ * // Get all running applications
+ * import { applications } from 'applescript-node/sources';
+ * const apps = await applications.getAll();
+ *
+ * @example
+ * // Get system information
+ * import { system } from 'applescript-node/sources';
+ * const info = await system.getInfo();
+ *
+ * @module sources
+ */
+export type { ApplicationInfo } from './applications.js';
+export * as applications from './applications.js';
+export type { DisplayInfo, SystemInfo, VolumeInfo } from './system.js';
+export * as system from './system.js';
+export type { WindowInfo } from './windows.js';
+export * as windows from './windows.js';

package/dist/sources/system.d.ts

@@ -0,0 +1,178 @@
+/**
+ * System information returned from macOS
+ */
+export interface SystemInfo {
+    computerName: string;
+    hostname: string;
+    osVersion: string;
+    systemVersion: string;
+    userName: string;
+    homeDirectory: string;
+    architecture: string;
+}
+/**
+ * Volume information for mounted drives
+ */
+export interface VolumeInfo {
+    name: string;
+    capacity: number;
+    freeSpace: number;
+    usedSpace: number;
+    format: string;
+    ejectable: boolean;
+}
+/**
+ * Display information
+ */
+export interface DisplayInfo {
+    id: number;
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+/**
+ * Get system information
+ * @returns System information including computer name, OS version, etc.
+ *
+ * @example
+ * import { system } from 'applescript-node/sources';
+ * const info = await system.getInfo();
+ * console.log(`Computer: ${info.computerName}`);
+ * console.log(`OS: ${info.osVersion}`);
+ */
+export declare function getInfo(): Promise<SystemInfo>;
+/**
+ * Get information about mounted volumes
+ * @returns Array of volume information for all mounted drives
+ *
+ * @example
+ * import { system } from 'applescript-node/sources';
+ * const volumes = await system.getVolumes();
+ * volumes.forEach(vol => {
+ *   console.log(`${vol.name}: ${vol.freeSpace}GB free of ${vol.capacity}GB`);
+ * });
+ */
+export declare function getVolumes(): Promise<VolumeInfo[]>;
+/**
+ * Get display information for all connected displays
+ * @returns Array of display information
+ *
+ * @example
+ * import { system } from 'applescript-node/sources';
+ * const displays = await system.getDisplays();
+ * console.log(`Found ${displays.length} display(s)`);
+ */
+export declare function getDisplays(): Promise<DisplayInfo[]>;
+/**
+ * Get the current clipboard contents
+ * @returns Clipboard text content
+ *
+ * @example
+ * import { system } from 'applescript-node/sources';
+ * const clipboardText = await system.getClipboard();
+ * console.log('Clipboard:', clipboardText);
+ */
+export declare function getClipboard(): Promise<string>;
+/**
+ * Set the clipboard contents
+ * @param text - Text to set in clipboard
+ *
+ * @example
+ * import { system } from 'applescript-node/sources';
+ * await system.setClipboard('Hello, World!');
+ */
+export declare function setClipboard(text: string): Promise<void>;
+/**
+ * Get path to common system folders
+ * @param folder - Folder identifier (e.g., 'home', 'desktop', 'documents', 'downloads', 'applications', 'library', 'temporary items')
+ * @returns POSIX path to the folder
+ *
+ * @example
+ * import { system } from 'applescript-node/sources';
+ * const desktop = await system.getPath('desktop');
+ * console.log('Desktop path:', desktop);
+ */
+export declare function getPath(folder: 'home' | 'desktop' | 'documents' | 'downloads' | 'applications' | 'library' | 'temporary items' | 'music' | 'pictures' | 'movies' | 'public'): Promise<string>;
+/**
+ * Check if the system is in dark mode
+ * @returns True if dark mode is enabled
+ *
+ * @example
+ * import { system } from 'applescript-node/sources';
+ * if (await system.isDarkMode()) {
+ *   console.log('Dark mode is enabled');
+ * }
+ */
+export declare function isDarkMode(): Promise<boolean>;
+/**
+ * Get system uptime in seconds
+ * @returns Number of seconds since last boot
+ *
+ * @example
+ * import { system } from 'applescript-node/sources';
+ * const uptime = await system.getUptime();
+ * console.log(`System uptime: ${Math.floor(uptime / 3600)} hours`);
+ */
+/**
+ * Get system uptime in seconds since last boot
+ *
+ * **IMPORTANT: Invalid Input Handling**
+ *
+ * This function includes critical error handling for edge cases:
+ *
+ * 1. **Invalid Boot Time**: When the shell script returns invalid output
+ *    (non-numeric, malformed, etc.):
+ *    - Number.parseInt() returns NaN
+ *    - NaN is detected and defaults to 0 (treats as current time)
+ *    - Result: uptime = current_time - 0 = large positive number
+ *
+ * 2. **Why Default to 0**: Defaulting invalid boot time to 0 ensures:
+ *    - Function always returns a valid number (never NaN)
+ *    - Result is always positive (current time is always > 0)
+ *    - Downstream code can safely use the result without NaN checks
+ *
+ * 3. **Why This Matters**: Without proper NaN handling:
+ *    - `now - NaN` = NaN, causing downstream errors
+ *    - Tests expecting positive numbers would fail
+ *    - Production code could crash on unexpected input
+ *
+ * **Usage Example:**
+ * ```typescript
+ * const uptime = await system.getUptime();
+ * console.log(`System has been up for ${uptime} seconds`);
+ * console.log(`That's ${Math.floor(uptime / 3600)} hours`);
+ * ```
+ *
+ * **Edge Cases Handled:**
+ * - Invalid/malformed boot time output → defaults to 0
+ * - Empty output → defaults to 0
+ * - Non-numeric output → defaults to 0
+ * - Script execution failure → throws error (expected behavior)
+ *
+ * **Testing Considerations:**
+ * - Test with valid boot time output
+ * - Test with invalid output (non-numeric, empty, etc.)
+ * - Verify NaN is properly handled and defaults to 0
+ * - Ensure result is always a positive number
+ *
+ * @returns Promise resolving to uptime in seconds (always positive, never NaN)
+ * @throws Error if script execution fails (different from invalid output)
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const uptime = await getUptime();
+ *   // uptime is always a valid positive number
+ *   if (uptime > 86400) {
+ *     console.log('System has been up for more than a day');
+ *   }
+ * } catch (error) {
+ *   // Only thrown if osascript execution fails
+ *   console.error('Failed to get uptime:', error);
+ * }
+ * ```
+ */
+export declare function getUptime(): Promise<number>;

package/dist/sources/windows.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Window information returned from macOS
+ */
+export interface WindowInfo {
+    name: string;
+    app: string;
+    id: number;
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    minimized: boolean;
+    zoomed: boolean;
+    visible: boolean;
+}
+/**
+ * Get all open windows across all applications
+ * @returns Array of window information for all visible windows
+ *
+ * @example
+ * import { windows } from 'applescript-node/sources';
+ * const allWindows = await windows.getAll();
+ * console.log(`Found ${allWindows.length} open windows`);
+ */
+export declare function getAll(): Promise<WindowInfo[]>;
+/**
+ * Get all windows for a specific application
+ * @param appName - Name of the application (e.g., 'Safari', 'Chrome', 'Finder')
+ * @returns Array of window information for the specified application
+ *
+ * @example
+ * import { windows } from 'applescript-node/sources';
+ * const safariWindows = await windows.getByApp('Safari');
+ * console.log(`Safari has ${safariWindows.length} windows open`);
+ */
+export declare function getByApp(appName: string): Promise<WindowInfo[]>;
+/**
+ * Get the frontmost (focused) window across all applications
+ * @returns The currently focused window, or null if no window is focused
+ *
+ * @example
+ * import { windows } from 'applescript-node/sources';
+ * const activeWindow = await windows.getFrontmost();
+ * if (activeWindow) {
+ *   console.log(`Active window: ${activeWindow.name} (${activeWindow.app})`);
+ * }
+ */
+export declare function getFrontmost(): Promise<WindowInfo | null>;
+/**
+ * Get window count by application
+ * @returns Map of application names to window counts
+ *
+ * @example
+ * import { windows } from 'applescript-node/sources';
+ * const counts = await windows.getCountByApp();
+ * console.log('Window counts:', counts);
+ * // { 'Safari': 3, 'Chrome': 2, 'Terminal': 1 }
+ */
+export declare function getCountByApp(): Promise<Record<string, number>>;