Metadata-Version: 2.4
Name: hedwigbot
Version: 1.0.0
Summary: Official Python SDK for hedwig.bot
Project-URL: Documentation, https://docs.hedwig.bot
Project-URL: Source, https://github.com/gondar00/ai-mailbox
Project-URL: Issues, https://github.com/gondar00/ai-mailbox/issues
Author: hedwig.bot
License-Expression: MIT
Keywords: ai-agents,api,email,hedwig,hedwigbot,inbox,webhooks
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Requires-Dist: requests>=2.31.0
Requires-Dist: typing-extensions>=4.5.0; python_version < '3.10'
Provides-Extra: dev
Requires-Dist: black>=23.7.0; extra == 'dev'
Requires-Dist: mypy>=1.4.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: types-requests>=2.31.0; extra == 'dev'
Description-Content-Type: text/markdown

# hedwigbot

Official Python SDK for [hedwig.bot](https://hedwig.bot) — real inboxes for AI agents.

## Installation

```bash
pip install hedwigbot
```

## Quick Start

```python
from hedwigbot import Hedwig

client = Hedwig(api_key="your-api-key")

# Create an inbox
inbox = client.inboxes.create(
    email_address="support-agent",
    display_name="Support Agent"
)

print(f"Created inbox: {inbox['email_address']}")

# List messages
response = client.inboxes.messages(inbox["id"])
messages = response["messages"]

# Send a message
client.inboxes.send(
    inbox["id"],
    to="customer@example.com",
    subject="Re: Your question",
    body_text="Thanks for reaching out!"
)
```

## Configuration

```python
from hedwigbot import Hedwig

client = Hedwig(
    api_key="your-api-key",
    base_url="https://api.hedwig.bot"  # optional, defaults to production
)
```

## API Reference

### Inboxes

```python
# List all inboxes
response = client.inboxes.list(limit=50, page_token="optional-cursor")
inboxes = response["inboxes"]
next_page = response.get("next_page_token")

# Create an inbox
inbox = client.inboxes.create(
    email_address="agent-123",      # optional, auto-generated if omitted
    display_name="Agent Name",       # optional
    metadata={"team": "support"}     # optional
)

# Get an inbox
inbox = client.inboxes.get("inbox_id")

# Delete an inbox
client.inboxes.delete("inbox_id")

# List messages in an inbox
response = client.inboxes.messages("inbox_id", limit=25)
messages = response["messages"]

# Get a specific message
message = client.inboxes.get_message("inbox_id", "message_id")

# Send a message
sent = client.inboxes.send(
    "inbox_id",
    to="recipient@example.com",
    subject="Hello",
    body_text="Plain text body",
    body_html="<p>HTML body</p>",  # optional
    from_name="Custom Name",        # optional
    reply_to="other@example.com"   # optional
)

# List threads
response = client.inboxes.threads("inbox_id", limit=20)
threads = response["threads"]
```

### Webhooks

```python
# List all webhooks
response = client.webhooks.list()
webhooks = response["webhooks"]

# Create a webhook
webhook = client.webhooks.create(
    url="https://yourapp.com/webhook",
    event_types=["message.received", "message.sent"]
)

# Get a webhook
webhook = client.webhooks.get("webhook_id")

# Delete a webhook
client.webhooks.delete("webhook_id")
```

### API Keys

```python
# List all API keys
response = client.api_keys.list()
keys = response["api_keys"]

# Create an API key
result = client.api_keys.create(
    name="Production Key",
    inbox_id="inbox_123"  # optional, for inbox-scoped keys
)

# Save the key immediately - it won't be shown again!
print(f"New API Key: {result['key']}")

# Revoke an API key
client.api_keys.revoke("key_id")
```

## Error Handling

```python
from hedwigbot import Hedwig, HedwigApiError

try:
    inbox = client.inboxes.create()
except HedwigApiError as error:
    print(f"API Error ({error.status}): {error}")
    print(f"Details: {error.details}")
```

## Pagination

All list endpoints support cursor-based pagination:

```python
page_token = None

while True:
    response = client.inboxes.list(limit=50, page_token=page_token)
    
    # Process inboxes
    for inbox in response["inboxes"]:
        print(inbox["email_address"])
    
    # Check for more pages
    page_token = response.get("next_page_token")
    if not page_token:
        break
```

## Type Hints

The SDK includes complete type hints:

```python
from hedwigbot import Hedwig
from hedwigbot.types import Inbox, Message, Webhook

client = Hedwig(api_key="your-key")

inbox: Inbox = client.inboxes.get("inbox_id")
```

## Requirements

- Python 3.8+
- requests>=2.31.0

## License

MIT

## Support

- Documentation: https://docs.hedwig.bot
- Issues: https://github.com/gondar00/ai-mailbox/issues
- Email: support@hedwig.bot
