Metadata-Version: 2.4
Name: ulfblk-notifications
Version: 0.1.0
Summary: Notification orchestrator with pluggable providers (email, webhook, console) and template rendering.
Project-URL: Homepage, https://github.com/abeldiaz/web25-991-bloques-reciclables
Project-URL: Documentation, https://github.com/abeldiaz/web25-991-bloques-reciclables/tree/main/packages/python/ulfblk-notifications
Project-URL: Repository, https://github.com/abeldiaz/web25-991-bloques-reciclables
Project-URL: Issues, https://github.com/abeldiaz/web25-991-bloques-reciclables/issues
Author-email: Abelardo Diaz <abelardo@bloques.dev>
License-Expression: MIT
Keywords: async,bloque,composable,email,notifications,templates,webhook
Classifier: Development Status :: 3 - Alpha
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 :: Communications
Classifier: Topic :: Communications :: Email
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: ulfblk-core
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: templates
Requires-Dist: jinja2>=3.1; extra == 'templates'
Description-Content-Type: text/markdown

# bloque-notifications

Notification orchestrator with pluggable providers and template rendering.

## Features

- **Template rendering** - Jinja2 (optional) with `str.format_map()` fallback
- **Pluggable providers** - WebhookProvider, ConsoleProvider, or any duck-typed provider
- **Multi-channel routing** - Send one notification to multiple channels
- **Tenant-aware templates** - Automatic tenant prefix via ulfblk-multitenant context
- **Async by design** - All I/O operations are async

## Installation

```bash
uv add bloque-notifications

# With Jinja2 template support
uv add bloque-notifications[templates]
```

## Quick Start

```python
from bloque_notifications import NotificationService, ConsoleProvider, Notification, Channel

service = NotificationService(
    providers={Channel.CONSOLE: ConsoleProvider()},
)

await service.start()

# Simple notification (no template)
result = await service.notify_simple(
    recipient="admin@example.com",
    subject="Deploy complete",
    body="Version 2.1.0 deployed successfully.",
    channels=[Channel.CONSOLE],
)

# Template-based notification
service.template_engine.register(
    "welcome",
    subject="Welcome, {name}!",
    body="Hello {name}, your account on {app} is ready.",
)

result = await service.notify(Notification(
    recipient="user@example.com",
    template_name="welcome",
    context={"name": "Alice", "app": "MyApp"},
    channels=[Channel.CONSOLE],
))

await service.stop()
```

## Connecting ulfblk-channels as Email Provider

bloque-notifications does NOT depend on ulfblk-channels. You can connect
any object that satisfies the `NotificationProvider` protocol via duck-typing:

```python
from bloque_channels.email.client import EmailClient
from bloque_channels.models.settings import EmailSettings
from bloque_notifications import NotificationService, Channel
from bloque_notifications.protocol import NotificationProvider

class EmailAdapter:
    """Adapt EmailClient to NotificationProvider protocol."""

    def __init__(self, client: EmailClient) -> None:
        self._client = client

    async def send(self, recipient, subject, body, *, metadata=None):
        from bloque_channels.models.message import OutboundMessage
        msg = OutboundMessage(to=recipient, subject=subject, body=body)
        return await self._client.send_message(msg)

    async def health_check(self) -> bool:
        return await self._client.health_check()

# Usage
email = EmailClient(EmailSettings(host="smtp.example.com"))
service = NotificationService(
    providers={Channel.EMAIL: EmailAdapter(email)},
)
```

## Providers

| Provider | Channel | Description |
|----------|---------|-------------|
| `ConsoleProvider` | CONSOLE | Logs notifications via ulfblk-core logger |
| `WebhookProvider` | WEBHOOK | POSTs JSON payload to recipient URL |

## API

See source code docstrings for full API documentation.
