# EU-Utility New Features Documentation

This document describes the 5 major new features added to EU-Utility.

## Table of Contents

1. [Auto-Updater System](#1-auto-updater-system)
2. [Plugin Marketplace](#2-plugin-marketplace)
3. [Cloud Sync](#3-cloud-sync)
4. [Statistics Dashboard](#4-statistics-dashboard)
5. [Import/Export System](#5-importexport-system)

---

## 1. Auto-Updater System

**Plugin:** `auto_updater.py`

The Auto-Updater provides automatic update checking, downloading, and installation with rollback support.

### Features

- **Automatic Update Checks**: Configurable interval-based checking
- **Semantic Versioning**: Full support for version comparison (e.g., `1.2.3-beta+build123`)
- **Secure Downloads**: SHA256 checksum verification
- **Automatic Rollback**: Restores previous version if update fails
- **Update History**: Tracks all update attempts with success/failure status
- **Multiple Channels**: Support for stable, beta, and alpha release channels

### Configuration

```python
config = {
    "check_interval_hours": 24,      # How often to check for updates
    "auto_check": True,              # Enable automatic checking
    "auto_install": False,           # Auto-install updates (disabled by default)
    "update_server": "https://api.eu-utility.app/updates",
    "backup_dir": "data/backups",
    "channel": "stable",             # stable, beta, alpha
}
```

### Usage

```python
from plugins.auto_updater import AutoUpdaterPlugin

# Get the plugin
updater = plugin_api.get_plugin("auto_updater")

# Manual update check
update_info = updater.check_for_updates()
if update_info:
    print(f"Update available: {update_info.version}")
    print(f"Release notes: {update_info.release_notes}")

# Full update process (check, download, install)
success = updater.update()

# Or step by step
download_path = updater.download_update(update_info)
if download_path:
    success = updater.install_update(download_path, update_info)

# Get update history
history = updater.get_update_history()
```

### API Reference

| Method | Description |
|--------|-------------|
| `check_for_updates()` | Check for available updates |
| `download_update(info)` | Download an update package |
| `install_update(path, info)` | Install a downloaded update |
| `update()` | Full update process (check + download + install) |
| `get_update_history()` | Get history of update attempts |
| `set_channel(channel)` | Set update channel (stable/beta/alpha) |
| `add_listener(callback)` | Listen for status changes |

---

## 2. Plugin Marketplace

**Plugin:** `plugin_marketplace.py`

Browse, install, and manage community-contributed plugins from a centralized marketplace.

### Features

- **Plugin Discovery**: Browse by category, rating, or popularity
- **Search**: Find plugins by name, description, tags, or author
- **One-Click Install**: Simple installation with dependency resolution
- **Auto-Updates**: Check for and install plugin updates
- **Ratings & Reviews**: Community-driven quality indicators
- **Offline Cache**: Cached plugin list for offline browsing

### Configuration

```python
config = {
    "marketplace_url": "https://marketplace.eu-utility.app/api",
    "cache_duration_minutes": 60,
    "plugins_dir": "plugins",
    "auto_check_updates": True,
}
```

### Usage

```python
from plugins.plugin_marketplace import PluginMarketplacePlugin

# Get the plugin
marketplace = plugin_api.get_plugin("plugin_marketplace")

# Browse all plugins
plugins = marketplace.fetch_plugins()
for plugin in plugins:
    print(f"{plugin.name} by {plugin.author} - {plugin.rating}★")

# Search
results = marketplace.search_plugins("clipboard", category="utilities")

# Get featured plugins
featured = marketplace.get_featured_plugins(limit=10)

# Install a plugin
success = marketplace.install_plugin("plugin_id")

# Check for updates
updates = marketplace.check_installed_updates()
for update in updates:
    marketplace.update_plugin(update.id)

# Get installed plugins
installed = marketplace.get_installed_plugins()
```

### API Reference

| Method | Description |
|--------|-------------|
| `fetch_plugins()` | Get all available plugins |
| `search_plugins(query, category)` | Search for plugins |
| `get_plugin_by_id(id)` | Get specific plugin details |
| `get_featured_plugins(limit)` | Get popular plugins |
| `get_categories()` | List available categories |
| `install_plugin(id)` | Install a plugin |
| `uninstall_plugin(id)` | Remove a plugin |
| `update_plugin(id)` | Update a plugin |
| `check_installed_updates()` | Check for available updates |
| `submit_rating(id, rating, review)` | Rate a plugin |

---

## 3. Cloud Sync

**Plugin:** `cloud_sync.py`

Synchronize settings, configurations, and data across multiple devices.

### Features

- **Multi-Provider Support**: Dropbox, Google Drive, OneDrive, WebDAV, Custom
- **Automatic Sync**: Sync on changes or at intervals
- **Conflict Resolution**: Multiple strategies (ask, local, remote, newest)
- **Encryption**: Optional data encryption for privacy
- **Selective Sync**: Choose what to sync (settings, plugins, history)
- **Bidirectional Sync**: Merge local and remote changes

### Configuration

```python
config = {
    "enabled": False,
    "provider": "custom",
    "auto_sync": True,
    "sync_interval_minutes": 30,
    "sync_on_change": True,
    "conflict_resolution": "ask",  # ask, local, remote, newest
    "encrypt_data": True,
    "sync_plugins": True,
    "sync_settings": True,
    "sync_history": False,
}
```

### Usage

```python
from plugins.cloud_sync import CloudSyncPlugin, CloudProvider, SyncConfig

# Get the plugin
sync = plugin_api.get_plugin("cloud_sync")

# Configure
config = SyncConfig(
    enabled=True,
    provider="custom",
    auto_sync=True,
    encrypt_data=True,
)
sync.set_sync_config(config)

# Configure provider
sync.set_provider_config(CloudProvider.CUSTOM, {
    "upload_url": "https://my-server.com/sync/upload",
    "download_url": "https://my-server.com/sync/download",
    "api_key": "your-api-key",
})

# Manual sync operations
sync.sync_up()        # Upload to cloud
sync.sync_down()      # Download from cloud
sync.sync_bidirectional()  # Merge changes

# Get sync status
print(f"Status: {sync.get_status()}")
print(f"Last sync: {sync.get_last_sync()}")

# Get sync history
history = sync.get_sync_history()
```

### API Reference

| Method | Description |
|--------|-------------|
| `sync_up()` | Upload local data to cloud |
| `sync_down()` | Download cloud data to local |
| `sync_bidirectional()` | Two-way sync |
| `set_sync_config(config)` | Update sync settings |
| `set_provider_config(provider, config)` | Configure cloud provider |
| `get_status()` | Get current sync status |
| `get_last_sync()` | Get timestamp of last sync |
| `get_sync_history()` | Get sync operation history |

---

## 4. Statistics Dashboard

**Plugin:** `stats_dashboard.py`

Comprehensive analytics and monitoring for EU-Utility usage and performance.

### Features

- **Real-time Metrics**: CPU, memory, disk usage monitoring
- **Time-Series Data**: Historical tracking of all metrics
- **Event Logging**: Track application events and user actions
- **Performance Timing**: Measure operation durations
- **Custom Metrics**: Counters, gauges, and histograms
- **Health Monitoring**: System health status and alerts
- **Exportable Reports**: Generate and export statistics reports

### Configuration

```python
config = {
    "data_dir": "data/stats",
    "retention_days": 30,
    "collection_interval_seconds": 60,
    "enable_system_metrics": True,
    "enable_plugin_metrics": True,
    "enable_usage_metrics": True,
}
```

### Usage

```python
from plugins.stats_dashboard import StatsDashboardPlugin

# Get the plugin
stats = plugin_api.get_plugin("stats_dashboard")

# Record metrics
stats.record_counter("clipboard_copies", 1)
stats.record_gauge("active_connections", 5)
stats.record_histogram("response_time", 150.5)

# Time an operation
with stats.time_operation("database_query"):
    # Your code here
    pass

# Record events
stats.record_event("plugin", "plugin_loaded", {"plugin": "my_plugin"})

# Get metric statistics
cpu_stats = stats.get_metric("cpu_percent").get_stats(3600)  # Last hour
print(f"Average CPU: {cpu_stats['mean']:.1f}%")

# Get system health
health = stats.get_system_health()
print(f"Status: {health['status']}")

# Generate report
report = stats.generate_report()
filepath = stats.export_report(format="json")

# Dashboard summary
summary = stats.get_dashboard_summary()
```

### API Reference

| Method | Description |
|--------|-------------|
| `record_counter(name, value, labels)` | Increment a counter |
| `record_gauge(name, value, labels)` | Set a gauge value |
| `record_histogram(name, value, labels)` | Record to histogram |
| `record_timing(name, duration_ms)` | Record timing |
| `time_operation(name)` | Context manager for timing |
| `record_event(source, type, details)` | Log an event |
| `get_metric(name)` | Get a time series |
| `get_system_health()` | Get health status |
| `generate_report()` | Generate statistics report |
| `export_report(filepath, format)` | Export report to file |

---

## 5. Import/Export System

**Plugin:** `import_export.py`

Comprehensive data export and import functionality in multiple formats.

### Features

- **Multiple Formats**: JSON, CSV, XML, YAML, ZIP
- **Export Profiles**: Predefined profiles (full, settings_only, minimal, etc.)
- **Import Modes**: Merge, replace, or skip existing data
- **Backup Creation**: Full system backups
- **Validation**: Validate import files before importing
- **Progress Callbacks**: Track export/import progress
- **Automatic Backups**: Create backup before import

### Configuration

```python
config = {
    "export_dir": "data/exports",
    "import_dir": "data/imports",
    "default_format": "json",
    "backup_before_import": True,
}
```

### Usage

```python
from plugins.import_export import ImportExportPlugin, ExportFormat, ImportMode

# Get the plugin
ie = plugin_api.get_plugin("import_export")

# Export with profile
result = ie.export_data(
    profile="full",  # full, settings_only, plugins_only, minimal
    format=ExportFormat.JSON,
)
print(f"Exported to: {result.filepath}")

# Quick exports
ie.export_settings("my_settings.json")
ie.export_plugins("my_plugins.json")

# Create backup
backup = ie.create_backup("pre_update_backup")

# Import data
result = ie.import_data(
    filepath="export.json",
    mode=ImportMode.MERGE,  # merge, replace, skip
)
print(f"Imported: {result.items_imported}")

# Restore from backup
ie.restore_backup("backup_file.zip", mode=ImportMode.REPLACE)

# List backups
backups = ie.list_backups()

# Validate import file
validation = ie.validate_import_file("export.json")
print(f"Valid: {validation['valid']}")

# Custom export profile
from plugins.import_export import ExportProfile
profile = ie.create_custom_profile(
    name="my_profile",
    include_settings=True,
    include_plugins=True,
    include_history=False,
)
ie.export_data(profile, ExportFormat.ZIP)
```

### API Reference

| Method | Description |
|--------|-------------|
| `export_data(profile, format, filepath)` | Export data |
| `export_settings(filepath)` | Quick export settings |
| `export_plugins(filepath)` | Quick export plugins |
| `create_backup(name)` | Create full backup |
| `import_data(filepath, mode)` | Import data |
| `restore_backup(path, mode)` | Restore from backup |
| `list_backups()` | List available backups |
| `validate_import_file(filepath)` | Validate import file |
| `get_export_profiles()` | Get available profiles |
| `create_custom_profile(name, **kwargs)` | Create custom profile |

---

## Integration Examples

### Combining Features

```python
# Example: Auto-backup before update
updater = plugin_api.get_plugin("auto_updater")
ie = plugin_api.get_plugin("import_export")

# Add pre-update backup
updater.add_listener(lambda status, info: 
    ie.create_backup(f"pre_update_{info.version}") if status.value == "downloading" else None
)

# Example: Sync stats to cloud
stats = plugin_api.get_plugin("stats_dashboard")
sync = plugin_api.get_plugin("cloud_sync")

# Export stats and sync
report_path = stats.export_report()
# Add to sync config...

# Example: Marketplace with stats tracking
marketplace = plugin_api.get_plugin("plugin_marketplace")

# Track plugin installations
marketplace.add_listener(lambda event, plugin_id:
    stats.record_event("marketplace", event, {"plugin": plugin_id})
)
```

---

## Architecture Notes

All new plugins follow the EU-Utility plugin architecture:

1. **Inherit from BasePlugin**: All plugins extend `core.base_plugin.BasePlugin`
2. **Implement on_start/on_stop**: Lifecycle methods for initialization
3. **Use existing services**: Integrate with clipboard, plugin API
4. **Minimal dependencies**: Only use standard library where possible
5. **Configuration persistence**: Store config in `data/` directory
6. **Event-driven**: Support listeners/callbacks for extensibility

### File Structure

```
plugins/
├── auto_updater.py      # Auto-update system
├── plugin_marketplace.py # Plugin browser/installer
├── cloud_sync.py        # Cloud synchronization
├── stats_dashboard.py   # Analytics dashboard
├── import_export.py     # Data export/import
└── test_plugin.py       # Original test plugin
```

### Dependencies

All plugins use only Python standard library except:
- `psutil` (optional): For system metrics in stats_dashboard
- `pyyaml` (optional): For YAML export/import

Install optional dependencies:
```bash
pip install psutil pyyaml
```