Metadata-Version: 2.4
Name: sendfn
Version: 0.0.1
Summary: Self-hosted communications platform SDK for email, push notifications, and SMS
Project-URL: Documentation, https://docs.superfunctions.dev/sendfn
Project-URL: Repository, https://github.com/21nCo/super-functions
Project-URL: Issues, https://github.com/21nCo/super-functions/issues
Author: 21n
License-Expression: MIT
Keywords: communications,email,notifications,push,sms,superfunctions
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Email
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: pydantic>=2.5.0
Requires-Dist: superfunctions>=0.1.0
Provides-Extra: all
Requires-Dist: aioapns>=3.1.0; extra == 'all'
Requires-Dist: boto3>=1.34.0; extra == 'all'
Requires-Dist: firebase-admin>=6.5.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: black>=23.11.0; extra == 'dev'
Requires-Dist: mypy>=1.7.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.1.6; extra == 'dev'
Requires-Dist: types-boto3>=1.0.0; extra == 'dev'
Provides-Extra: email
Requires-Dist: boto3>=1.34.0; extra == 'email'
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.104.0; extra == 'fastapi'
Requires-Dist: superfunctions-fastapi>=0.1.0; extra == 'fastapi'
Provides-Extra: flask
Requires-Dist: flask>=3.0.0; extra == 'flask'
Requires-Dist: superfunctions-flask>=0.1.0; extra == 'flask'
Provides-Extra: push
Requires-Dist: aioapns>=3.1.0; extra == 'push'
Requires-Dist: firebase-admin>=6.5.0; extra == 'push'
Provides-Extra: sms
Description-Content-Type: text/markdown

# SendFn Python SDK

Self-hosted communications platform SDK for email, push notifications, and SMS.

## Installation

```bash
pip install sendfn
```

For email support (AWS SES):

```bash
pip install sendfn[email]
```

For push notification support:

```bash
pip install sendfn[push]
```

For all features:

```bash
pip install sendfn[all]
```

## Quick Start

### Email Sending

```python
from sendfn import create_sendfn, SendfnConfig
from sendfn.models import EmailConfig, AwsSesConfig, SendEmailParams
from sendfn.database import MemoryAdapter

# Create configuration
config = SendfnConfig(
    database=MemoryAdapter(),
    email=EmailConfig(
        from_email="noreply@example.com",
        from_name="My App",
        aws_ses=AwsSesConfig(
            access_key_id="YOUR_ACCESS_KEY",
            secret_access_key="YOUR_SECRET_KEY",
            region="us-east-1",
        ),
    ),
)

# Create client
sendfn = create_sendfn(config)

# Send an email
transaction = await sendfn.send_email(
    SendEmailParams(
        user_id="user-123",
        to="user@example.com",
        subject="Welcome!",
        html="<h1>Welcome to our app!</h1>",
        text="Welcome to our app!",
    )
)

print(f"Email sent! Transaction ID: {transaction.id}")
```

### Using Templates

```python
from sendfn.models import EmailTemplate

# Register a custom template
template = EmailTemplate(
    id="welcome",
    name="Welcome Email",
    subject="Welcome to {{appName}}!",
    html="<h1>Hi {{userName}}!</h1><p>Welcome to {{appName}}.</p>",
    variables=["userName", "appName"],
)

await sendfn.register_template(template)

# Send email using template
transaction = await sendfn.send_email(
    SendEmailParams(
        user_id="user-123",
        to="user@example.com",
        template_id="welcome",
        template_data={
            "userName": "John",
            "appName": "My App",
        },
    )
)
```

### Suppression List

```python
# Check if email is suppressed
result = await sendfn.check_suppression_list("user@example.com")
if result["suppressed"]:
    print(f"Email is suppressed: {result['entry'].reason}")

# Add to suppression list
await sendfn.add_to_suppression_list(
    email="spam@example.com",
    reason="manual",
    source="admin-action",
)

# Remove from suppression list
await sendfn.remove_from_suppression_list("user@example.com")
```

### Event Tracking

```python
# Get events for an email transaction
events = await sendfn.get_email_events(transaction_id="...")

for event in events:
    print(f"{event.event_type} at {event.event_timestamp}")
```

## Features

- ✅ **Email Sending** - AWS SES support with attachments
- ✅ **Template Engine** - Variable interpolation, conditionals, loops
- ✅ **Suppression Lists** - Automatic bounce and complaint handling
- ✅ **Event Tracking** - Track delivery, bounces, opens, clicks
- ✅ **Database Agnostic** - Works with any database via adapters
- ⏳ **Push Notifications** - FCM and APNS support (coming soon)
- ⏳ **SMS** - SMS sending support (coming soon)

## Configuration

### Email Configuration

```python
EmailConfig(
    from_email="noreply@example.com",  # Required
    from_name="My App",  # Optional
    reply_to="support@example.com",  # Optional
    aws_ses=AwsSesConfig(
        access_key_id="...",
        secret_access_key="...",
        region="us-east-1",
        configuration_set_name="my-config-set",  # Optional
    ),
)
```

### Options

```python
SendfnOptions(
    suppression_enabled=True,  # Enable suppression list checking
    retry_attempts=3,  # Number of retry attempts
    retry_delay=1000,  # Delay between retries (ms)
    event_tracking=True,  # Enable event tracking
)
```

## Database Adapters

### Memory Adapter (for testing)

```python
from sendfn.database import MemoryAdapter

adapter = MemoryAdapter()
```

### With Superfunctions DB

```python
from superfunctions.db import create_adapter

adapter = create_adapter({
    "type": "postgres",
    "connection_string": "postgresql://...",
})
```

## Development

```bash
# Install dependencies
make install

# Run tests
make test

# Lint code
make lint

# Format code
make format
```

## License

MIT License - see LICENSE file for details.

## Links

- [Documentation](https://docs.superfunctions.dev/sendfn)
- [GitHub](https://github.com/21nCo/super-functions)
- [Issues](https://github.com/21nCo/super-functions/issues)
