Mac API Call Bot

A macOS menu-bar utility that periodically calls a user-specified API endpoint. The app lives in the menu bar only, prompts for configuration on first launch, and relies on launchd to schedule unattended checks. A small helper tool performs the actual requests so the schedule continues even when the UI is idle.

Features

• Menu-bar only interface with a discrete status icon and "Preferences…" / "Quit" actions.
• First-run setup flow requesting the API endpoint and polling frequency (in minutes).
• Persists configuration to ~/Library/Application Support/MacApiCallBot/config.json and reuses it across launches.
• Manages a launchd LaunchAgent that executes a bundled helper binary at the configured interval.
• Optional login item toggle (via SMLoginItemSetEnabled) so the app starts automatically at login.
• Helper tool validates network reachability before making the API call and logs basic response information.
• Sample LaunchAgent plist and build script for automation.

Requirements

• macOS 12.0 or later
• Xcode 15 (or compatible command-line tools)

Building and Packaging

A convenience script packages the .app bundle for distribution:

./build.sh         # Uses Release configuration by default

The script builds the MacApiCallBot scheme, embeds the helper executables, and copies the resulting .app to dist/MacApiCallBot.app.

You can also build manually with Xcode or the command line:

xcodebuild -scheme MacApiCallBot -configuration Release build

Running the App

1. Launch MacApiCallBot.app. The app appears as a small waveform icon in the menu bar.
2. On first run, the Preferences window prompts for:
   • API Endpoint URL – must be HTTP or HTTPS.
   • Frequency (minutes) – how often the helper should call the endpoint (minimum 1 minute).
   • Launch at login – whether to install the bundled login helper via Service Management.
3. Clicking Save writes the configuration, schedules the LaunchAgent, and (optionally) registers the login item. You can reopen the window from the menu bar icon at any time.

The helper logs stdout/stderr to files under ~/Library/Logs/MacApiCallBot/. This is useful for troubleshooting API responses.

Logging

• Runtime diagnostics are written to both the unified macOS log (subsystem com.alireza.MacApiCallBot) and to ~/Library/Logs/MacApiCallBot/app.log.
• Tail the file with tail -f ~/Library/Logs/MacApiCallBot/app.log to confirm the app launched and whether the preferences window was presented.

LaunchAgent Details

• Label: com.alireza.mac-api-call-bot.agent
• Plist location: ~/Library/LaunchAgents/com.alireza.mac-api-call-bot.agent.plist
• Program: the embedded APICallHelper binary (MacApiCallBot.app/Contents/MacOS/APICallHelper)
• Environment: MAC_API_CALL_BOT_CONFIG is set so the helper can read the shared JSON configuration.

A sample LaunchAgent configuration is provided at LaunchAgents/com.example.mac-api-call-bot.agent.plist. Update the paths and label if you wish to create a manual installation or deploy via device management.

If you need to inspect or reload the LaunchAgent manually:

launchctl bootout gui/"$(id -u)" com.alireza.mac-api-call-bot.agent
launchctl bootstrap gui/"$(id -u)" ~/Library/LaunchAgents/com.alireza.mac-api-call-bot.agent.plist

Login Item Helper

The login helper target (MacApiCallBotLauncher) is packaged inside MacApiCallBot.app/Contents/Library/LoginItems/. The main app toggles it through SMLoginItemSetEnabled. The helper ensures the menu-bar app launches at user login and then quits immediately.

Unit Tests

Run the included unit tests from the command line:

xcodebuild test -scheme MacApiCallBot -destination 'platform=macOS'

Tests cover preference persistence and basic URL validation logic.

Assumptions & Limitations

• The helper makes HTTP GET requests. If your API needs other verbs or authentication, additional work is required.
• Network checks rely on NWPathMonitor. Very brief outages may still result in failed requests; retry behaviour is delegated to LaunchAgent scheduling.
• The app does not inspect API usage policies. Ensure the configured endpoint allows automated polling and that you comply with the provider's Terms of Service.
• The build script does not sign or notarize the app. Distribute responsibly and sign with your own certificate when shipping.

Respecting API Terms of Service

Automating API calls can violate provider rules if done excessively. Configure conservative polling intervals, monitor response codes, and review the target API's Terms of Service before enabling automated checks in production environments.

Repository Layout

mac-api-call-bot.xcodeproj/   # Xcode project and shared scheme
MacApiCallBot/                # Menu-bar app sources and resources
MacApiCallBotLauncher/        # Login helper app target
APICallHelper/                # Command-line helper invoked by launchd
Shared/                       # Shared data models and persistence helpers
MacApiCallBotTests/           # Unit tests
LaunchAgents/                 # Example LaunchAgent plist
build.sh                      # Build and packaging helper script
README.md                     # This document