imessage-monitor 0.1.0__tar.gz

imessage_monitor-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish to PyPI
+
+on:
+  push:
+    branches: [main]
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+      with:
+        enable-cache: true
+
+    - name: Set up Python
+      run: uv python install
+
+    - name: Build package
+      run: uv build
+
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        repository-url: https://upload.pypi.org/legacy/

imessage_monitor-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

imessage_monitor-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

imessage_monitor-0.1.0/CLAUDE.md

@@ -0,0 +1,6 @@
+The package manager you use is uv -- python and packages will be run using uv run, dependencies will be managed using uv add/rm.
+
+Reference documentation is found in respources.  
+
+The ultimate goal of this project is to query an existing imessage database (w/in some daterange and optionally limited to a list of numbers/contacts) and store the messages in the imessage-db database and poll for new messages while running (and ingest all messages that have been received during downtime on startup w/o introducing duplicates into the database)
+

imessage_monitor-0.1.0/PKG-INFO

@@ -0,0 +1,224 @@
+Metadata-Version: 2.4
+Name: imessage-monitor
+Version: 0.1.0
+Summary: A Python library for monitoring and extracting iMessage data with real-time capabilities
+Author-email: Christian Hale <bhschristian@gmail.com>
+Maintainer-email: Christian Hale <bhschristian@gmail.com>
+License: MIT
+Keywords: ascii-art,chat,imessage,macos,messages,monitoring,real-time,sms
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: ascii-magic>=2.3.0
+Requires-Dist: pillow-heif>=1.0.0
+Requires-Dist: tomli-w>=1.2.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.4.1; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=1.0.0; extra == 'test'
+Requires-Dist: pytest>=8.4.1; extra == 'test'
+Description-Content-Type: text/markdown
+
+# iMessage Monitor
+
+A Python library for monitoring and extracting iMessage data with real-time capabilities and beautiful terminal display.
+
+## Features
+
+- = **Real-time monitoring** of incoming iMessages
+- =� **Pretty-printed chat bubbles** with proper left/right alignment
+- <� **Sticker and reaction support** with emoji display
+- =� **ASCII art generation** for image attachments (optional)
+- =� **Attachment handling** including HEIC conversion
+- =� **Outbound messaging** via AppleScript or Shortcuts
+- =� **Safe database access** with read-only mode
+
+## Requirements
+
+- **macOS only** (requires access to Messages database)
+- **Python 3.11+**
+- **Full Disk Access** permission for terminal/IDE
+
+## Installation
+
+```bash
+pip install imessage-monitor
+
+or
+
+uv add imessage-monitor
+```
+
+
+## Quick Start
+
+### Real-time Monitoring
+
+```python
+from imessage_monitor import iMessageMonitor
+from imessage_monitor.display import pretty_print_bubble
+
+def handle_message(message):
+    """Handle new messages with pretty printing."""
+    print(pretty_print_bubble(message, show_ascii_art=True))
+
+# Start monitoring
+monitor = iMessageMonitor()
+monitor.start(message_callback=handle_message)
+
+# Keep running (in practice, you'd run this in an async loop)
+input("Press Enter to stop...")
+monitor.stop()
+```
+
+### Message Retrieval
+
+```python
+from imessage_monitor import iMessageMonitor, to_json
+
+# Get recent messages
+monitor = iMessageMonitor()
+messages = monitor.get_recent_messages(limit=50)
+
+# Convert to JSON
+json_data = to_json(messages)
+print(json_data)
+```
+
+### Sending Messages
+
+```python
+from imessage_monitor import ImessageOutbound
+
+# Send via AppleScript
+outbound = ImessageOutbound()
+success = outbound.send_message_applescript("+1234567890", "Hello!")
+
+# Send attachment
+success = outbound.send_attachment_applescript("+1234567890", "/path/to/file.jpg")
+```
+
+## Display Options
+
+The library provides three pretty-print formats:
+
+### Chat Bubbles
+```python
+from imessage_monitor.display import pretty_print_bubble
+
+# Basic bubble (no ASCII art)
+print(pretty_print_bubble(message))
+
+# With ASCII art for images
+print(pretty_print_bubble(message, show_ascii_art=True))
+```
+
+### Reactions
+```python
+from imessage_monitor.display import pretty_print_reaction
+
+print(pretty_print_reaction(message))  # Shows d, =M, =, etc.
+```
+
+### Stickers
+```python
+from imessage_monitor.display import pretty_print_sticker
+
+print(pretty_print_sticker(message, show_ascii_art=True))
+```
+
+## Data Conversion
+
+```python
+from imessage_monitor import to_json, to_toml
+
+# Convert messages to different formats
+json_str = to_json(messages)
+toml_str = to_toml(messages)
+
+# Save to files
+to_json(messages, "messages.json")
+to_toml(messages, "messages.toml")
+```
+
+## Configuration
+
+The library uses sensible defaults but can be configured:
+
+```python
+from imessage_monitor.config import Config
+
+# Create custom config
+config = Config.default()
+config.monitoring.poll_interval_seconds = 1  # Faster polling
+
+monitor = iMessageMonitor(config_path="path/to/config.toml")
+```
+
+## Permissions
+
+### Required: Full Disk Access
+
+1. Open **System Preferences** � **Security & Privacy** � **Privacy**
+2. Select **Full Disk Access** 
+3. Add your terminal application (Terminal.app, iTerm2, etc.)
+4. Add your IDE if running from there (VS Code, PyCharm, etc.)
+
+### Optional: Shortcuts (for outbound messaging)
+
+For Shortcuts-based messaging, create these shortcuts in the Shortcuts app:
+- "Send Message" - Not Yet Implemented
+- "Send Attachment" - Not Yet Implemented
+
+## Platform Support
+
+- **macOS**: Supported
+- **Windows/Linux**: Not supported L (requires macOS Messages database)
+
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run tests: `pytest`
+5. Submit a pull request
+
+
+## Troubleshooting
+
+### "Database not found" error
+- Ensure you're running on macOS
+- Check Full Disk Access permissions
+- Verify Messages app has been used at least once
+
+### "Permission denied" error  
+- Add Full Disk Access for your terminal/IDE
+- Restart terminal after adding permissions
+
+### ASCII art not showing
+- Ensure `ascii-magic` is installed
+- Enable with `show_ascii_art=True` parameter
+- Check image file accessibility
+
+## Examples
+
+See `example_usage.py` for a complete real-time monitoring application.
+
+## Security Note
+
+This library accesses your Messages database in read-only mode for monitoring. It does not modify or delete any messages. Outbound messaging requires explicit function calls and uses standard macOS APIs.

imessage_monitor-0.1.0/README.md

@@ -0,0 +1,189 @@
+# iMessage Monitor
+
+A Python library for monitoring and extracting iMessage data with real-time capabilities and beautiful terminal display.
+
+## Features
+
+- = **Real-time monitoring** of incoming iMessages
+- =� **Pretty-printed chat bubbles** with proper left/right alignment
+- <� **Sticker and reaction support** with emoji display
+- =� **ASCII art generation** for image attachments (optional)
+- =� **Attachment handling** including HEIC conversion
+- =� **Outbound messaging** via AppleScript or Shortcuts
+- =� **Safe database access** with read-only mode
+
+## Requirements
+
+- **macOS only** (requires access to Messages database)
+- **Python 3.11+**
+- **Full Disk Access** permission for terminal/IDE
+
+## Installation
+
+```bash
+pip install imessage-monitor
+
+or
+
+uv add imessage-monitor
+```
+
+
+## Quick Start
+
+### Real-time Monitoring
+
+```python
+from imessage_monitor import iMessageMonitor
+from imessage_monitor.display import pretty_print_bubble
+
+def handle_message(message):
+    """Handle new messages with pretty printing."""
+    print(pretty_print_bubble(message, show_ascii_art=True))
+
+# Start monitoring
+monitor = iMessageMonitor()
+monitor.start(message_callback=handle_message)
+
+# Keep running (in practice, you'd run this in an async loop)
+input("Press Enter to stop...")
+monitor.stop()
+```
+
+### Message Retrieval
+
+```python
+from imessage_monitor import iMessageMonitor, to_json
+
+# Get recent messages
+monitor = iMessageMonitor()
+messages = monitor.get_recent_messages(limit=50)
+
+# Convert to JSON
+json_data = to_json(messages)
+print(json_data)
+```
+
+### Sending Messages
+
+```python
+from imessage_monitor import ImessageOutbound
+
+# Send via AppleScript
+outbound = ImessageOutbound()
+success = outbound.send_message_applescript("+1234567890", "Hello!")
+
+# Send attachment
+success = outbound.send_attachment_applescript("+1234567890", "/path/to/file.jpg")
+```
+
+## Display Options
+
+The library provides three pretty-print formats:
+
+### Chat Bubbles
+```python
+from imessage_monitor.display import pretty_print_bubble
+
+# Basic bubble (no ASCII art)
+print(pretty_print_bubble(message))
+
+# With ASCII art for images
+print(pretty_print_bubble(message, show_ascii_art=True))
+```
+
+### Reactions
+```python
+from imessage_monitor.display import pretty_print_reaction
+
+print(pretty_print_reaction(message))  # Shows d, =M, =, etc.
+```
+
+### Stickers
+```python
+from imessage_monitor.display import pretty_print_sticker
+
+print(pretty_print_sticker(message, show_ascii_art=True))
+```
+
+## Data Conversion
+
+```python
+from imessage_monitor import to_json, to_toml
+
+# Convert messages to different formats
+json_str = to_json(messages)
+toml_str = to_toml(messages)
+
+# Save to files
+to_json(messages, "messages.json")
+to_toml(messages, "messages.toml")
+```
+
+## Configuration
+
+The library uses sensible defaults but can be configured:
+
+```python
+from imessage_monitor.config import Config
+
+# Create custom config
+config = Config.default()
+config.monitoring.poll_interval_seconds = 1  # Faster polling
+
+monitor = iMessageMonitor(config_path="path/to/config.toml")
+```
+
+## Permissions
+
+### Required: Full Disk Access
+
+1. Open **System Preferences** � **Security & Privacy** � **Privacy**
+2. Select **Full Disk Access** 
+3. Add your terminal application (Terminal.app, iTerm2, etc.)
+4. Add your IDE if running from there (VS Code, PyCharm, etc.)
+
+### Optional: Shortcuts (for outbound messaging)
+
+For Shortcuts-based messaging, create these shortcuts in the Shortcuts app:
+- "Send Message" - Not Yet Implemented
+- "Send Attachment" - Not Yet Implemented
+
+## Platform Support
+
+- **macOS**: Supported
+- **Windows/Linux**: Not supported L (requires macOS Messages database)
+
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run tests: `pytest`
+5. Submit a pull request
+
+
+## Troubleshooting
+
+### "Database not found" error
+- Ensure you're running on macOS
+- Check Full Disk Access permissions
+- Verify Messages app has been used at least once
+
+### "Permission denied" error  
+- Add Full Disk Access for your terminal/IDE
+- Restart terminal after adding permissions
+
+### ASCII art not showing
+- Ensure `ascii-magic` is installed
+- Enable with `show_ascii_art=True` parameter
+- Check image file accessibility
+
+## Examples
+
+See `example_usage.py` for a complete real-time monitoring application.
+
+## Security Note
+
+This library accesses your Messages database in read-only mode for monitoring. It does not modify or delete any messages. Outbound messaging requires explicit function calls and uses standard macOS APIs.

imessage_monitor-0.1.0/config.toml

@@ -0,0 +1,33 @@
+[database]
+# Databasing not yet supported
+url = "postgresql://user:pass@localhost/imessage_db"
+pool_size = 10
+max_overflow = 20
+pool_timeout = 30
+enable_storage = false
+
+[apple]
+chat_db_path = "~/Library/Messages/chat.db"
+attachments_path = "~/Library/Messages/Attachments"
+permissions_check = true
+
+[monitoring]
+poll_interval_seconds = 3
+startup_lookback_hours = 24
+max_batch_size = 100
+enable_real_time = true
+
+[contacts]
+phone_numbers = []
+include_unknown = true
+group_chats = false
+
+[date_range]
+# start_date = "2024-01-01T00:00:00"
+# end_date = "2024-12-31T23:59:59"
+
+[outbound]
+method = "applescript"
+rate_limit_per_minute = 30
+enable_auto_reply = false
+auto_reply_triggers = []

imessage_monitor-0.1.0/example_usage.py

@@ -0,0 +1,162 @@
+"""Real-time iMessage monitoring example."""
+import asyncio
+import signal
+import sys
+from imessage_monitor import iMessageMonitor
+from imessage_monitor.display import pretty_print_bubble, pretty_print_reaction, pretty_print_sticker
+
+
+class RealTimeMonitor:
+    """Real-time iMessage monitor with graceful shutdown."""
+    
+    def __init__(self, enable_ascii_art: bool = False):
+        self.monitor = iMessageMonitor()
+        self.enable_ascii_art = enable_ascii_art
+        self.running = False
+        self.message_count = 0
+        
+    def handle_new_message(self, message):
+        """Handle incoming messages with pretty printing."""
+        self.message_count += 1
+        
+        print(f"\n{'='*80}")
+        print(f"📱 NEW MESSAGE #{self.message_count}")
+        print(f"{'='*80}")
+        
+        # Determine message type and use appropriate pretty print
+        associated_type = message.get('associated_message_type', 0)
+        balloon_bundle_id = message.get('balloon_bundle_id', '')
+        attachments = message.get('parsed_attachments', [])
+        
+        # Check if it's a sticker
+        is_sticker = any(attachment.get('is_sticker', False) for attachment in attachments)
+        
+        if associated_type in range(2000, 4000):  # Reaction
+            print("🔄 REACTION:")
+            print(pretty_print_reaction(message))
+        elif is_sticker:
+            print("🎭 STICKER:")
+            print(pretty_print_sticker(message, show_ascii_art=self.enable_ascii_art))
+        else:
+            print("💬 MESSAGE:")
+            print(pretty_print_bubble(message, show_ascii_art=self.enable_ascii_art))
+        
+        # Show additional info
+        sender = "You" if message.get('is_from_me') else message.get('handle_id_str', 'Unknown')
+        service = message.get('service', 'Unknown')
+        print(f"\n📊 From: {sender} | Service: {service}")
+        
+        if attachments:
+            print(f"📎 Attachments: {len(attachments)}")
+            for i, attachment in enumerate(attachments[:3]):  # Show first 3
+                filename = attachment.get('filename', 'Unknown')
+                size = attachment.get('size', 0)
+                if size:
+                    size_mb = size / (1024 * 1024)
+                    print(f"   {i+1}. {filename} ({size_mb:.1f}MB)")
+                else:
+                    print(f"   {i+1}. {filename}")
+    
+    def setup_signal_handlers(self):
+        """Setup graceful shutdown on Ctrl+C."""
+        def signal_handler(signum, frame):
+            print(f"\n\n⚠️  Received signal {signum}. Shutting down gracefully...")
+            self.running = False
+        
+        signal.signal(signal.SIGINT, signal_handler)
+        signal.signal(signal.SIGTERM, signal_handler)
+    
+    async def start_monitoring(self):
+        """Start real-time monitoring."""
+        self.setup_signal_handlers()
+        self.running = True
+        
+        print("🚀 Starting iMessage Real-Time Monitor")
+        print("=" * 60)
+        print(f"ASCII Art: {'Enabled' if self.enable_ascii_art else 'Disabled'}")
+        print("=" * 60)
+        
+        try:
+            # Start monitoring without showing initial messages
+            print("📱 Initializing monitor...")
+            initial_messages = self.monitor.start(message_callback=self.handle_new_message)
+            print("✅ Monitor initialized")
+            
+            print("\n🎯 MONITORING ACTIVE - Waiting for new messages...")
+            print("📞 Send yourself a message to test!")
+            print("🛑 Press Ctrl+C to stop monitoring")
+            print("=" * 60)
+            
+            # Keep the monitor running
+            while self.running and self.monitor.is_running():
+                await asyncio.sleep(0.5)  # Check every 0.5 seconds
+                
+        except KeyboardInterrupt:
+            print("\n⚠️  Keyboard interrupt received")
+        except Exception as e:
+            print(f"\n❌ Error during monitoring: {e}")
+        finally:
+            await self.cleanup()
+    
+    async def cleanup(self):
+        """Clean shutdown of the monitor."""
+        print("\n🛑 Stopping monitor...")
+        
+        if self.monitor.is_running():
+            self.monitor.stop()
+            
+        print(f"📊 Session Summary:")
+        print(f"   • Messages processed: {self.message_count}")
+        print(f"   • Monitor status: {'Stopped' if not self.monitor.is_running() else 'Running'}")
+        print("✅ Monitor stopped successfully")
+
+
+def show_help():
+    """Show usage instructions."""
+    print("iMessage Real-Time Monitor")
+    print("=" * 40)
+    print("Usage:")
+    print("  python example_usage.py [--ascii-art]")
+    print("")
+    print("Options:")
+    print("  --ascii-art    Enable ASCII art for images (default: disabled)")
+    print("  --help         Show this help message")
+    print("")
+    print("Controls:")
+    print("  Ctrl+C         Stop monitoring")
+    print("")
+    print("Features:")
+    print("  • Real-time message monitoring")
+    print("  • Pretty-printed chat bubbles") 
+    print("  • Reaction and sticker support")
+    print("  • Attachment information")
+    print("  • Graceful shutdown")
+
+
+async def main():
+    """Main entry point for real-time monitoring."""
+    
+    # Parse command line arguments
+    enable_ascii_art = '--ascii-art' in sys.argv
+    show_help_flag = '--help' in sys.argv or '-h' in sys.argv
+    
+    if show_help_flag:
+        show_help()
+        return
+    
+    # Create and start the monitor
+    monitor = RealTimeMonitor(enable_ascii_art=enable_ascii_art)
+    await monitor.start_monitoring()
+
+
+if __name__ == "__main__":
+    print("iMessage Monitor - Real-Time Monitoring")
+    print("=" * 60)
+    
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        print("\n👋 Goodbye!")
+    except Exception as e:
+        print(f"\n❌ Fatal error: {e}")
+        sys.exit(1)