Bluesky Notify

A cross-platform desktop notification system for Bluesky. Monitor and receive notifications from your favorite Bluesky accounts.

https://pypi.org/project/bluesky-notify/

Features

• Monitor multiple Bluesky accounts for new posts
• Real-time browser notifications in Docker environment
• Desktop notifications support across platforms (macOS, Linux, Windows)
• Daemon mode for continuous monitoring
• Web interface for easy account management
• Email notifications support (requires Mailgun configuration)
• XDG-compliant configuration storage
• SQLite database for reliable post tracking
• Cross-platform compatibility
• Consistent CLI interface with clear version and configuration information
• Comprehensive logging system with rotation and separate error logs
• WebSocket support for real-time updates in Docker environment

Installation

• From local / repo download

pip install bluesky-notify

• From PyPi

To verify the installation:
```bash
bluesky-notify --version

Example output:

Bluesky Notify v0.4.1
Config: /Users/username/.local/share/bluesky-notify

A cross-platform desktop notification system for Bluesky. Monitor and receive notifications from your favorite Bluesky accounts.

Usage: bluesky-notify [OPTIONS] COMMAND [ARGS]...

Run 'bluesky-notify start --daemon' to install and run as a system service.

Options:
  --version     Show version and exit
  --help        Show this message and exit

Commands:
  add          Add a Bluesky account to monitor.
  list         List all monitored Bluesky accounts and their notification...
  remove       Remove a Bluesky account from monitoring.
  settings     View or update application settings.
  start        Start the notification service.
  status       View the current status of the service.
  stop         Stop the notification service.
  toggle       Toggle monitoring status for a Bluesky account.
  update       Update notification preferences for a monitored account.

Configuration

The application uses the XDG Base Directory Specification for storing its data:

• Configuration: ~/.config/bluesky-notify/
• Data: ~/.local/share/bluesky-notify/
• Cache: ~/.cache/bluesky-notify/
• Logs:
  • macOS: ~/Library/Logs/bluesky-notify/
  • Linux: ~/.local/share/bluesky-notify/logs/

Port Configuration

The web interface runs on port 3000 by default. On macOS, port 5000 is avoided as it's reserved for AirPlay. You can change the port using:

bluesky-notify settings --port NUMBER

Email Notifications (Optional)

To enable email notifications, set the following environment variables:

export MAILGUN_API_KEY='your-api-key'
export MAILGUN_DOMAIN='your-domain'
export MAILGUN_FROM_EMAIL='[email protected]'
export MAILGUN_TO_EMAIL='[email protected]'

Usage

Starting the Service

Start the service with debug logging:

bluesky-notify start --log-level DEBUG

Start as a system service:

bluesky-notify start --daemon

Command Help

To see all available commands and options:

bluesky-notify --help

Adding an Account to Monitor

bluesky-notify add username.bsky.social

Note: The handle should be provided without the '@' symbol.

Options:

• --desktop/--no-desktop: Enable/disable desktop notifications (default: enabled)
• --email/--no-email: Enable/disable email notifications (default: disabled)

Listing Monitored Accounts

bluesky-notify list

Managing Accounts

Toggle monitoring for an account:

bluesky-notify toggle username.bsky.social

Remove an account:

bluesky-notify remove username.bsky.social

Update notification preferences:

bluesky-notify update username.bsky.social --desktop/--no-desktop --email/--no-email

Docker Support

When running in Docker, the application supports browser notifications through WebSocket connections. The web interface will automatically detect the Docker environment and enable real-time notifications.

Environment Variables

• DOCKER_CONTAINER: Set to 'true' to enable Docker-specific features
• PORT: Override the default port (default: 5001 in Docker)

Logging

The application uses a comprehensive logging system:

• Log files are stored in platform-specific locations:

  • macOS: ~/Library/Logs/bluesky-notify/
  • Linux: ~/.local/share/bluesky-notify/logs/

• Two log files are maintained:

  • bluesky-notify.log: General application logs (INFO level and above)
  • bluesky-notify.error.log: Error logs only (ERROR level)

• Log rotation is enabled:

  • Maximum file size: 1MB
  • Keeps up to 5 backup files
  • Rotated files are named with numerical suffixes (e.g., bluesky-notify.log.1)

• Debug logging can be enabled with:

  bluesky-notify start --log-level DEBUG

Development

Requirements

• Python 3.9 or higher
• Dependencies listed in pyproject.toml

Setting Up Development Environment

1. Clone the repository:

git clone https://github.com/jerdog/bluesky-notify.git
cd bluesky-notify

2. Install development dependencies:

pip install -e ".[dev]"

3. Run tests:

pytest

License

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

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

If you encounter any issues or have questions, please file an issue on the GitHub repository.

Version History

• 0.4.2: Enhance monitoring + logging
• 0.4.1: Validate Docker container image builds correctly, make CLI co-exist
• 0.4.0: Add web interface to daemon + terminal mode
• 0.3.0: Add daemon mode, web interface, and improved CLI help text
• 0.2.7: Fixed CLI output formatting and help text organization
• 0.2.6: Enhanced CLI interface with consistent version and config display
• 0.2.5: Improved help text formatting and command output
• 0.2.4: Added version and config information to all commands
• 0.2.3: Refined CLI presentation and version display
• 0.2.0: Initial public release

Troubleshooting

1. Version Check

   • Run bluesky-notify --version to verify the installed version
   • Make sure you have the latest version installed

2. No Notifications

   • Check if desktop notifications are enabled in your system
   • Verify the notification service is running
   • Check logs in ~/.local/share/bluesky-notify/logs/

3. API Errors

   • Verify Bluesky handles are entered correctly (without '@' symbol)
   • Check your internet connection
   • Ensure the Bluesky API is accessible