Metadata-Version: 2.4
Name: notificator
Version: 0.4.1
Summary: Notificator SDK with AdminClient and Sender Notificator
Home-page: https://github.com/Jyonn/notificator
Author: Jyonn Liu
Author-email: i@6-79.cn
License: MIT Licence
Keywords: notice,notificator,bark,sms,mail,webhook
Platform: any
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests
Dynamic: author
Dynamic: author-email
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: platform
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# notificator

Python SDK for [Notificator](https://github.com/Jyonn/notificator), focused on:

- sending notifications through one unified API
- preparing multi-channel deliveries in one request
- managing admin login and account CRUD
- managing mail sender configuration

## Installation

```bash
pip install notificator
```

## Quick Start

```python
from notificator import Notificator

client = Notificator(
    name="demo_account",
    token="account_token",
    host="http://127.0.0.1:8000",
)

result = client.mail(
    mail="user@example.com",
    subject="Build finished",
    body="The nightly build is green.",
    recipient_name="Operator",
    action_url="https://example.com/jobs/42",
    action_text="Open job",
)

print(result)
```

## Unified Multi-Channel Sending

You can prepare multiple deliveries and send them together:

```python
from notificator import Notificator

client = Notificator(
    name="demo_account",
    token="account_token",
    host="http://127.0.0.1:8000",
)

result = (
    client
    .clean()
    .prepare_sms(
        "+8613800000000",
        template_param={"scene": "incident"},
    )
    .prepare_mail(
        "user@example.com",
        recipient_name="Operator",
        action_url="https://example.com/incidents/7",
        action_text="View incident",
    )
    .prepare_webhook(
        "https://example.com/hooks/notificator",
        headers={"Authorization": "Bearer your-secret"},
        body={"source": "notificator-sdk"},
    )
    .send(
        format="verification",
        body={"code": "482901", "time": 10},
        title="Incident opened",
    )
)

print(result)
```

## Shortcut Methods

### Mail

```python
client.mail(
    "user@example.com",
    subject="Welcome",
    body="Your account is ready.",
    recipient_name="Tom",
    footer_note="Sent by Notificator",
)
```

### SMS

```python
client.sms(
    "+8613800000000",
    code="123456",
    time=5,
)
```

### Bark

```python
client.bark(
    "https://api.day.app/your-device-key",
    title="Deploy finished",
    body="Production is healthy.",
)
```

### Webhook

```python
client.webhook(
    "https://example.com/hooks/notificator",
    headers={"Authorization": "Bearer your-secret"},
    body={"message": "Production is healthy."},
)
```

## AdminClient

`AdminClient` wraps administrator APIs such as login, account CRUD, and mail sender management.

```python
from notificator import AdminClient

admin = AdminClient(
    email="admin@example.com",
    password="your-password",
    host="http://127.0.0.1:8000",
)

accounts = admin.get_accounts()
print(accounts)

account = admin.create_account(
    name="ops_bot",
    nick="Ops Bot",
)
print(account)

sender_client = admin.get_notificator("ops_bot")
sender_client.webhook(
    "https://example.com/hooks/notificator",
    body={"message": "Hello from Notificator"},
)
```

Mail sender management:

```python
admin.create_mail_sender(
    sender_id="PRIMARY",
    email="noreply@example.com",
    password="app-password",
    smtp_server="smtp.example.com",
    smtp_port=465,
    enabled=True,
    weight=3,
)
```

## Defaults

- default host: `https://notice.6-79.cn`
- default locale: `zh-CN`
- default timeout: `15` seconds

## Errors

The SDK raises:

- `NotificatorError` for client-side validation or request failures
- `NotificatorAPIError` for structured API errors returned by the server

Example:

```python
from notificator import NotificatorAPIError

try:
    client.sms("+8613800000000", code="123456", time=5)
except NotificatorAPIError as err:
    print(err.identifier)
    print(err.message)
    print(err.details)
```

## Testing

Run unit tests:

```bash
python -m unittest tests/test_sdk_unit.py
```

Run integration tests with environment variables:

```bash
export NOTIFICATOR_TEST_HOST=http://127.0.0.1:8000
export NOTIFICATOR_TEST_ADMIN_EMAIL=admin@example.com
export NOTIFICATOR_TEST_ADMIN_PASSWORD=your-password
python -m unittest tests/test_integration.py
```

