Metadata-Version: 2.4
Name: webhookloggerx
Version: 2.0.0
Summary: A clean, user-friendly Python package for sending Discord webhook messages and rich embeds.
Author: Nur Mohammad Rafi
Author-email: 
Keywords: discord webhook embed notification bot
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Communications
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.20.0
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: keywords
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# webhooklogger-python-rafi

A clean, user-friendly Python package for sending Discord webhook messages and rich embeds.

## Installation

```bash
pip install webhookloggerx
```

## Quick Start

```python
from webhooklogger import WebhookClient, Embed

client = WebhookClient("https://discord.com/api/webhooks/YOUR_ID/YOUR_TOKEN")
client.send("Hello from webhooklogger!")
```

---

## Features

- ✅ Send plain text messages
- ✅ Send rich Discord embeds
- ✅ Send multiple embeds in one request
- ✅ Customise webhook display name & avatar
- ✅ Embed builder with fluent (chainable) API
- ✅ Built-in colour themes (`success`, `error`, `warning`, etc.)
- ✅ Set embed title, description, author, footer, images, timestamp, fields

---

## WebhookClient

### Create a Client

```python
from webhooklogger import WebhookClient

client = WebhookClient("https://discord.com/api/webhooks/...")
```

### Set Webhook Profile (name & avatar)

```python
client.set_profile(
    username="MyBot",
    avatar_url="https://example.com/avatar.png"
)
```

### Send a Plain Text Message

```python
client.send("This is a plain message.")
```

### Send an Embed

```python
from webhooklogger import Embed

embed = Embed().set_title("Hello!").set_description("Embed body here.")
client.send_embed(embed)
```

### Send Multiple Embeds

```python
embed1 = Embed().set_title("First").set_theme("success")
embed2 = Embed().set_title("Second").set_theme("error")
client.send_embeds([embed1, embed2])
```

### Send Text + Embed Together

```python
embed = Embed().set_title("Alert").set_description("Check this out!")
client.send_message(content="Hey team!", embed=embed)
```

---

## Embed Builder

All methods return `self`, so you can **chain** them fluently.

### Title & Description

```python
embed = (
    Embed()
    .set_title("My Title")
    .set_description("This is the body of the embed.")
    .set_url("https://example.com")   # makes title clickable
)
```

### Colour

```python
# Hex string
embed.set_color("#FF5733")

# Integer
embed.set_color(16711680)

# Named theme
embed.set_theme("success")
```

**Available themes:**

| Theme | Colour |
|---|---|
| `default` | Discord Blurple |
| `success` | Green |
| `warning` | Yellow |
| `error` | Red |
| `info` | Blue |
| `dark` | Dark Grey |
| `light` | White |
| `purple` | Purple |
| `orange` | Orange |
| `pink` | Pink |

### Author

```python
embed.set_author(
    name="Nur Mohammad Rafi",
    url="https://github.com/yourusername",
    icon_url="https://example.com/icon.png"
)
```

### Thumbnail & Image

```python
embed.set_thumbnail("https://example.com/thumb.png")  # top-right corner
embed.set_image("https://example.com/big-image.png")  # large bottom image
```

### Fields

```python
embed.add_field("Status", "Online", inline=True)
embed.add_field("Server", "Production", inline=True)
embed.add_field("Message", "All systems go.", inline=False)
```

- `inline=True` — fields sit side by side (up to 3 per row)
- `inline=False` — field takes the full width
- Max **25 fields** per embed

### Footer

```python
embed.set_footer("webhooklogger v1.0", icon_url="https://example.com/icon.png")
```

### Timestamp

```python
embed.set_timestamp()        # use current UTC time
```

```python
from datetime import datetime, timezone
embed.set_timestamp(datetime(2025, 1, 1, tzinfo=timezone.utc))  # custom time
```

---

## Full Example

```python
from webhooklogger import WebhookClient, Embed

# Create and configure client
client = WebhookClient("https://discord.com/api/webhooks/...")
client.set_profile(username="AlertBot", avatar_url="https://example.com/bot.png")

# Build embed
embed = (
    Embed()
    .set_title("🚨 System Alert")
    .set_description("A critical event has been detected on the server.")
    .set_theme("error")
    .set_author("Monitor System", icon_url="https://example.com/icon.png")
    .set_thumbnail("https://example.com/thumb.png")
    .add_field("Host", "prod-server-01", inline=True)
    .add_field("Status", "❌ Down", inline=True)
    .add_field("Region", "US-East", inline=True)
    .add_field("Details", "Connection timeout after 30s", inline=False)
    .set_image("https://example.com/graph.png")
    .set_footer("webhooklogger • Auto-alert system")
    .set_timestamp()
)

# Send it
client.send_embed(embed)
```

---

## Error Handling

```python
from webhooklogger import WebhookClient, WebhookError

client = WebhookClient("https://discord.com/api/webhooks/...")

try:
    client.send("Test message")
except WebhookError as e:
    print(f"Failed: HTTP {e.status_code} — {e.message}")
```

---

## API Reference

### `WebhookClient`

| Method | Description |
|---|---|
| `__init__(url)` | Create client with webhook URL |
| `set_profile(username, avatar_url)` | Override display name & avatar |
| `send(content)` | Send plain text message |
| `send_embed(embed)` | Send a single Embed |
| `send_embeds(embeds)` | Send a list of Embeds (max 10) |
| `send_message(content, embed)` | Send text + embed together |

### `Embed`

| Method | Description |
|---|---|
| `set_title(title)` | Embed title |
| `set_description(text)` | Embed body text |
| `set_url(url)` | Make title a hyperlink |
| `set_color(color)` | Hex string or int |
| `set_colour(color)` | Alias for `set_color` |
| `set_theme(theme)` | Named colour theme |
| `set_author(name, url, icon_url)` | Author block |
| `set_thumbnail(url)` | Small top-right image |
| `set_image(url)` | Large bottom image |
| `set_footer(text, icon_url)` | Footer text & icon |
| `set_timestamp(dt)` | Timestamp (default: now) |
| `add_field(name, value, inline)` | Add a field |
| `clear_fields()` | Remove all fields |
| `build()` | Return raw dict for API |

---

## License

MIT © Nur Mohammad Rafi
