ironnotify-python/README.md

# IronNotify SDK for Python

Event notifications and alerts SDK for Python applications. Send notifications, receive real-time updates, and manage notification state.

[![PyPI](https://img.shields.io/pypi/v/ironnotify.svg)](https://pypi.org/project/ironnotify/)
[![Python](https://img.shields.io/pypi/pyversions/ironnotify.svg)](https://pypi.org/project/ironnotify/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Installation

```bash
pip install ironnotify
```

## Quick Start

### Send a Simple Notification

```python
import ironnotify

# Initialize
ironnotify.init("ak_live_xxxxx")

# Send a simple notification
ironnotify.notify(
    "order.created",
    "New Order Received",
    message="Order #1234 has been placed",
    severity="success",
    metadata={"order_id": "1234", "amount": 99.99},
)
```

### Fluent Event Builder

```python
import ironnotify

ironnotify.init("ak_live_xxxxx")

# Build complex notifications with the fluent API
result = ironnotify.event("payment.failed") \
    .with_title("Payment Failed") \
    .with_message("Payment could not be processed") \
    .with_severity("error") \
    .with_metadata({"order_id": "1234", "reason": "Card declined"}) \
    .with_action("Retry Payment", url="/orders/1234/retry", style="primary") \
    .with_action("Contact Support", action="open_support") \
    .for_user("user-123") \
    .with_deduplication_key("payment-failed-1234") \
    .expires_in(86400)  # 24 hours \
    .send()
```

### Async Support

```python
import asyncio
import ironnotify

async def main():
    ironnotify.init("ak_live_xxxxx")

    # Async notification
    result = await ironnotify.notify_async(
        "user.signup",
        "New User Registered",
        severity="success",
    )

    # Async event builder
    result = await ironnotify.event("order.shipped") \
        .with_title("Order Shipped") \
        .for_user("user-123") \
        .send_async()

    # Get notifications async
    notifications = await ironnotify.get_notifications_async(limit=10)

asyncio.run(main())
```

### Using the Client Directly

```python
from ironnotify import NotifyClient, NotifyOptions

client = NotifyClient(NotifyOptions(
    api_key="ak_live_xxxxx",
    debug=True,
))

# Send notification
result = client.notify("event.type", "Title")

# Use event builder
result = client.event("event.type") \
    .with_title("Title") \
    .send()

# Clean up
client.close()
```

## Configuration

```python
from ironnotify import NotifyOptions, NotifyClient

options = NotifyOptions(
    api_key="ak_live_xxxxx",
    api_base_url="https://api.ironnotify.com",
    ws_url="wss://ws.ironnotify.com",
    debug=False,
    enable_offline_queue=True,
    max_offline_queue_size=100,
    auto_reconnect=True,
    max_reconnect_attempts=5,
    reconnect_delay=1.0,
)

client = NotifyClient(options)
```

### Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `api_key` | str | required | Your API key (ak_live_xxx or ak_test_xxx) |
| `api_base_url` | str | 'https://api.ironnotify.com' | API base URL |
| `ws_url` | str | 'wss://ws.ironnotify.com' | WebSocket URL |
| `debug` | bool | False | Enable debug logging |
| `enable_offline_queue` | bool | True | Queue notifications when offline |
| `max_offline_queue_size` | int | 100 | Max offline queue size |
| `auto_reconnect` | bool | True | Auto-reconnect WebSocket |
| `max_reconnect_attempts` | int | 5 | Max reconnection attempts |
| `reconnect_delay` | float | 1.0 | Base reconnection delay (seconds) |

## Features

- **Simple Notifications**: Send notifications with one line of code
- **Fluent Builder**: Build complex notifications with an intuitive API
- **Async Support**: Full async/await support for all operations
- **Offline Queue**: Notifications are queued when offline
- **Type Hints**: Full type annotations for IDE support
- **Dataclasses**: Clean data models using Python dataclasses

## Notification Options

### Severity Levels

```python
from ironnotify import SeverityLevel

# Available levels: "info", "success", "warning", "error", "critical"
ironnotify.notify("alert", "System Alert", severity="critical")
```

### Actions

```python
ironnotify.event("order.shipped") \
    .with_title("Order Shipped") \
    .with_action("Track Package", url="https://tracking.example.com/123", style="primary") \
    .with_action("View Order", action="view_order") \
    .send()
```

### Deduplication

Prevent duplicate notifications:

```python
ironnotify.event("reminder") \
    .with_title("Daily Reminder") \
    .with_deduplication_key("daily-reminder-2024-01-15") \
    .send()
```

### Grouping

Group related notifications:

```python
ironnotify.event("comment.new") \
    .with_title("New Comment") \
    .with_group_key("post-123-comments") \
    .send()
```

### Expiration

```python
from datetime import datetime, timedelta

# Expires in 1 hour
ironnotify.event("flash_sale") \
    .with_title("Flash Sale!") \
    .expires_in(3600) \
    .send()

# Expires at specific time
ironnotify.event("event_reminder") \
    .with_title("Event Tomorrow") \
    .expires_on(datetime.utcnow() + timedelta(days=1)) \
    .send()
```

## Managing Notifications

### Get Notifications

```python
# Get all notifications
notifications = ironnotify.get_notifications()

# With options
unread = ironnotify.get_notifications(limit=10, offset=0, unread_only=True)

# Async
notifications = await ironnotify.get_notifications_async()
```

### Mark as Read

```python
# Mark single notification
client.mark_as_read("notification-id")

# Mark all as read
client.mark_all_as_read()
```

### Get Unread Count

```python
count = client.get_unread_count()
print(f"You have {count} unread notifications")
```

## Real-Time Notifications

```python
import ironnotify

ironnotify.init("ak_live_xxxxx")

def handle_notification(notification):
    print(f"New notification: {notification.title}")

ironnotify.on_notification(handle_notification)
ironnotify.connect()
ironnotify.subscribe_to_user("user-123")
ironnotify.subscribe_to_app()
```

## Offline Support

Notifications are automatically queued when offline:

```python
import ironnotify

ironnotify.init("ak_live_xxxxx")

# This will be queued if offline
ironnotify.notify("event", "Title")

# Manually flush the queue
ironnotify.flush()

# Or async
await ironnotify.flush_async()
```

## Requirements

- Python 3.8+
- httpx
- websockets (for real-time features)

## License

MIT License - see [LICENSE](LICENSE) for details.