Metadata-Version: 2.4
Name: notifsh
Version: 0.2.1
Summary: Python SDK for notif.sh event hub
Project-URL: Homepage, https://notif.sh
Project-URL: Documentation, https://docs.notif.sh
Project-URL: Repository, https://github.com/filipexyz/notif
Author-email: "notif.sh" <hello@notif.sh>
License-Expression: MIT
Keywords: async,events,notif,notifsh,pubsub,webhooks,websocket
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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 :: Internet :: WWW/HTTP
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: websockets>=12.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# notifsh

Python SDK for [notif.sh](https://notif.sh) event hub.

## Installation

```bash
pip install notifsh
```

## Quick Start

```python
import asyncio
from notifsh import Notif

async def main():
    # Uses NOTIF_API_KEY env var by default
    async with Notif() as n:
        # Emit an event
        await n.emit('leads.new', {'name': 'John', 'email': 'john@example.com'})

        # Subscribe to events (auto-ack by default)
        async for event in n.subscribe('leads.*'):
            print(f"Received: {event.topic} - {event.data}")

asyncio.run(main())
```

## Configuration

```python
from notifsh import Notif

# Using environment variable (recommended)
# Set NOTIF_API_KEY=nsh_your_api_key
client = Notif()

# Or pass API key directly
client = Notif(api_key='nsh_your_api_key')

# With custom server
client = Notif(server='http://localhost:8080')
```

## Emitting Events

```python
async with Notif() as n:
    result = await n.emit('orders.created', {
        'order_id': '12345',
        'amount': 99.99,
    })
    print(f"Event ID: {result.id}")
```

## Subscribing to Events

```python
async with Notif() as n:
    # Subscribe to multiple topics
    async for event in n.subscribe('orders.*', 'payments.*'):
        print(f"{event.topic}: {event.data}")

    # Manual acknowledgment
    async for event in n.subscribe('orders.*', auto_ack=False):
        try:
            process(event.data)
            await event.ack()
        except Exception:
            await event.nack('5m')  # Retry in 5 minutes

    # Consumer groups (load-balanced)
    async for event in n.subscribe('jobs.*', group='worker-pool'):
        await process_job(event.data)

    # Start from beginning
    async for event in n.subscribe('orders.*', from_='beginning'):
        print(event.data)
```

## Error Handling

```python
from notifsh import Notif, AuthError, APIError, ConnectionError

try:
    async with Notif() as n:
        await n.emit('test', {'data': 'value'})
except AuthError:
    print("Invalid API key")
except APIError as e:
    print(f"API error ({e.status_code}): {e}")
except ConnectionError as e:
    print(f"Connection failed: {e}")
```

## Requirements

- Python 3.11+
- httpx
- websockets

## License

MIT
