Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

0.1.0 - 2025-11-30

AppleScript Execution: Execute AppleScript code with timeout support and argument passing
JavaScript for Automation (JXA): Full JXA support with ObjC bridge access
Script File Execution: Execute .applescript, .scpt, .js, and .jxa files with automatic language detection
macOS Shortcuts: Run Shortcuts with input parameter support (strings, numbers, maps, lists)
Comprehensive Error Handling: Detailed error types and messages via ExMacOSControl.Error module

SystemEvents: Process management (list, launch, quit, check if running)
SystemEvents.UI: UI automation (menu clicks, keystrokes, window properties)
SystemEvents.FileOps: File operations (reveal in Finder, trash files, get selection)
Finder: Control Finder application (selection, navigation, view modes)
Safari: Browser automation (open URLs, execute JavaScript, manage tabs)
Mail: Email automation (send emails with CC/BCC, search mailboxes, unread counts)
Messages: iMessage/SMS automation (send messages, retrieve chats, unread counts)

Permissions Module: Check and manage macOS automation permissions (accessibility, automation, full disk access)
Script Building DSL: Minimal DSL for constructing AppleScript programmatically
Retry Logic: Automatic retry with exponential/linear backoff for timeout errors
Telemetry Integration: Observability via :telemetry events for monitoring and debugging
Performance Monitoring: Built-in telemetry events for script execution and retry operations

Platform Detection: Automatic macOS platform validation with helpful error messages
Test-Friendly Design: Adapter pattern with Mox support for comprehensive testing
Comprehensive Documentation: Module creation guide for extending with new app modules
Performance Guide: Best practices for timeout tuning, retry strategies, and telemetry setup

Test Coverage: 417 tests with 100% pass rate (408 unit tests, 9 doctests, 171 integration tests)
Code Quality: Zero Credo issues (strict mode), zero Dialyzer warnings
Dependencies: Minimal dependencies (telemetry for monitoring, mox for testing)
Elixir Version: Requires Elixir ~> 1.19

macOS Only: This library only works on macOS platforms (validated at runtime)
Permissions Required: Most features require macOS permissions (accessibility, automation, full disk access)
Application Availability: App modules (Safari, Mail, Messages, etc.) require the respective apps to be installed and properly configured
Script Timeout: Long-running scripts may timeout; use the :timeout option to adjust (default varies by operation)
Integration Tests: Many integration tests are skipped by default to prevent destructive operations (use mix test --include integration to run)

Message Sending: Messages.send_message/2 sends real messages immediately with no undo
Email Sending: Mail.send_email/1 sends real emails immediately with no undo
File Operations: SystemEvents.trash_file/1 moves files to trash (not permanent but use with caution)
Permission Prompts: macOS will prompt for permissions on first use; ensure users understand what permissions are needed and why

None (initial release)

Messages.list_chats/0: Fixed AppleScript syntax error with unread count property
- Changed from unread count of c to c's unread count (possessive form required for multi-word properties)
- Now properly retrieves chat names from participant full names instead of missing values
- Returns unread: 0 for all chats as Messages AppleScript API doesn't expose unread counts
Messages.get_unread_count/0: Updated to return {:ok, 0} as placeholder
- Documents that real unread counts require Full Disk Access and direct SQLite database queries
Messages.send_message/3: Simplified AppleScript to use send to buddy syntax
- Fixed issues with service type selection that caused execution errors
- Properly handles contact names with correct capitalization

Messages Group Chat Support: New :group_chat option for send_message/3
- Send messages to group chats by participant names (e.g., "John Doe & Jane Smith")
- Automatically finds matching group chat via list_chats() and uses chat ID
- Returns :not_found error if group chat doesn't exist
- Comprehensive test coverage for group chat functionality
Messages Documentation: Enhanced module documentation with group chat examples and limitations section

Messages AppleScript: Updated to use simpler and more reliable syntax patterns
- Individual messages use send to buddy syntax
- Group messages use send to chat id syntax

Telemetry Performance Warning: Fixed telemetry handler warnings in test suite
- Changed from anonymous functions to module function references using &Module.function/4 syntax
- Eliminates "local function" performance penalty warnings from :telemetry.attach_many/4
- Affected files: retry_test.exs and osascript_adapter_telemetry_test.exs
- Improves test suite performance and reduces noise in test output

Additional app modules (Music, Photos, Calendar, Contacts, Reminders, Notes, Notification Center)
Advanced error handling features
Real unread count support via SQLite database access (requires Full Disk Access)