# chirppy

A lightweight Python library for sending notifications to multiple platforms with a unified API. Send messages to Slack, Discord, Telegram, and generic webhooks with minimal configuration.

## Features

- **Unified API** - Send notifications to multiple platforms with a single function call.
- **Multiple Providers** - Supports Slack, Discord, Telegram, and arbitrary webhook endpoints.
- **Async Support** - Fully async-compatible API via `async_send`.
- **Easy Configuration** - Use environment variables or pass webhook URLs directly.
- **Lightweight** - Minimal dependencies.
- **Built-in Retries** - Automatic retry logic for failed requests.

## Installation

```bash
pip install chirppy
```

## Quick Start

### Basic Usage

Send a simple notification:

```python
from chirppy import send

# Send with explicit webhook URL
send("Hello world", slack="https://hooks.slack.com/services/...")
```

### Provider-Specific Usage

Send a notification to a specific provider.

```python
from chirppy.slack import send

# Send with an explicit webhook URL
send("Hello world", url="https://hooks.slack.com/services/...")

```

### Using Environment Variables

For convenience, configure your webhooks as environment variables:

```bash
export CHIRPPY_SLACK_WEBHOOK=https://hooks.slack.com/services/...
export CHIRPPY_DISCORD_WEBHOOK=https://discord.com/api/webhooks/...
export CHIRPPY_TELEGRAM_TOKEN=your-telegram-bot-token
export CHIRPPY_TELEGRAM_CHAT_ID=your-telegram-chat-id
export CHIRPPY_CUSTOM_WEBHOOK=https://example.com/webhook
```

Then send notifications without specifying URLs:

```python
from chirppy import send

# Automatically uses environment variables
send("Build completed", slack=True, discord=True)
```

## Supported Providers

| Provider   | Parameter  | Environment Variable       |
|------------|------------|----------------------------|
| Slack      | `slack`    | `CHIRPPY_SLACK_WEBHOOK`    |
| Discord    | `discord`  | `CHIRPPY_DISCORD_WEBHOOK`  |
| Telegram   | `telegram` | `CHIRPPY_TELEGRAM_TOKEN`, `CHIRPPY_TELEGRAM_CHAT_ID` |
| Custom     | `webhook`  | `CHIRPPY_CUSTOM_WEBHOOK`   |

## Async Usage
Chirppy is fully async-compatible. Use `async_send` instead of `send`.

### Basic Async Example

Send an asynchronous message.

```python
import asyncio
from chirppy import async_send

async def main():
    await async_send(
        "Hello async world",
        slack="https://hooks.slack.com/services/..."
    )

asyncio.run(main())
```

### Provider-Specific Usage

Send an asynchronous notification to a specific provider.

```python
import asyncio
from chirppy.slack import async_send

async def main():
    await async_send("Async processing complete")

asyncio.run(main())
```
## Configuration

### Environment Variables

Chirppy supports the following environment variables for configuration:

```bash
# Slack and Discord webhooks
CHIRPPY_SLACK_WEBHOOK=https://...
CHIRPPY_DISCORD_WEBHOOK=https://...

# Telegram token and chat ID
CHIRPPY_TELEGRAM_TOKEN=your-bot-token
CHIRPPY_TELEGRAM_CHAT_ID=your-chat-id

# Custom webhook endpoint
CHIRPPY_CUSTOM_WEBHOOK=https://...
```

## Examples

### Send to Multiple Platforms

```python
from chirppy import send

send(
    "Deployment complete",
    slack=True,
    telegram=True
    discord="https://...",
)
```

### Send to Multiple Platforms with overrides
```python
from chirppy import send

send(
    "Hello",
    slack=True,
    discord={"message": "Alternative message", "username": "different-user"},
    telegram={"token": "your-telegram-token", "chat_id": "your-chat-id"},
)
```

### Send with Custom Webhook

```python
from chirppy import send

send(
    "Custom alert",
    webhook="https://your-webhook-endpoint.com/notify"
)
```

## License

This project is licensed under the MIT License - see the LICENSE file for details.