Metadata-Version: 2.4
Name: seb-auth
Version: 0.1.0
Summary: Official Python SDK for SebAuth — a Backend-as-a-Service for email, auth, and database.
Author: SebAuth
License: MIT
Project-URL: Homepage, https://seb-auth.lovable.app
Project-URL: Documentation, https://seb-auth.lovable.app
Project-URL: Source, https://github.com/sebauth/seb-auth-python
Project-URL: Issues, https://github.com/sebauth/seb-auth-python/issues
Keywords: sebauth,baas,email,auth,sdk,seb-auth
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Communications :: Email
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-mock>=3.10; extra == "dev"
Requires-Dist: responses>=0.23; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Dynamic: license-file

# seb-auth

**Official Python SDK for [SebAuth](https://seb-auth.lovable.app)** — a Backend-as-a-Service for email, authentication and database.

[![PyPI](https://img.shields.io/pypi/v/seb-auth.svg)](https://pypi.org/project/seb-auth/)
[![Python](https://img.shields.io/pypi/pyversions/seb-auth.svg)](https://pypi.org/project/seb-auth/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## Install

```bash
pip install seb-auth
```

## Quick start

```python
from seb_auth import SebAuth

# Reads SEBAUTH_API_KEY from the environment.
seb = SebAuth()

result = seb.email.send(
    to="user@example.com",
    subject="Hello",
    body="Hello from SebAuth!",
)

print(result.id, result.status)
```

Set your API key once and forget about it:

```bash
export SEBAUTH_API_KEY="sk_live_..."
```

Or pass it explicitly (never hard-code it in your source):

```python
import os
from seb_auth import SebAuth

seb = SebAuth(api_key=os.environ["MY_SEBAUTH_KEY"])
```

## Features

- 📨 **Email** — send transactional email via `seb.email.send(...)`.
- 🔐 **Auth** — namespace reserved for upcoming SebAuth auth endpoints.
- 🗄️ **Database** — namespace reserved for upcoming SebAuth database endpoints.
- ⏱️ Sensible request **timeouts** (30 s default, per-call overridable).
- 🧯 Typed **exception hierarchy** for easy error handling.
- 🕵️ Never prints or logs your full API key.

## Sending email

`seb.email.send(...)` makes a real HTTP request to
`POST https://seb-auth.lovable.app/api/public/v1/mail/send` and returns a
result object exposing everything SebAuth tells you about the message.

```python
from seb_auth import SebAuth

seb = SebAuth()

result = seb.email.send(
    to="jane@example.com",
    subject="Welcome to Acme",
    body="<h1>Hi Jane 👋</h1><p>Thanks for signing up!</p>",
)

print(result.id)          # -> "e5e7eea2-..."
print(result.status)      # -> "sent"
print(result.message_id)  # -> "<...@gmail.com>"
print(result.sent_at)     # -> ISO-8601 timestamp
```

`SendEmailResult` is a normal `dict`, so `result["id"]` works too.

## Error handling

Every exception raised by the SDK inherits from `SebAuthError`, so you can
catch everything with one clause or drill down as needed:

```python
from seb_auth import (
    SebAuth,
    SebAuthError,
    AuthenticationError,
    BadRequestError,
    RateLimitError,
    TimeoutError,
    ConnectionError,
)

seb = SebAuth()

try:
    seb.email.send(to="user@example.com", subject="Hi", body="Hello!")
except AuthenticationError:
    print("Your API key is invalid.")
except BadRequestError as e:
    print("Bad request:", e.message)
except RateLimitError:
    print("Slow down — you're being rate limited.")
except TimeoutError:
    print("SebAuth took too long to respond.")
except ConnectionError:
    print("Could not reach SebAuth.")
except SebAuthError as e:
    print("Something else went wrong:", e)
```

Every `APIError` exposes `status_code`, `message` and `response_body` for
easy debugging.

## Configuration

| Argument     | Env var             | Default                              |
| ------------ | ------------------- | ------------------------------------ |
| `api_key`    | `SEBAUTH_API_KEY`   | — *(required)*                       |
| `base_url`   | `SEBAUTH_BASE_URL`  | `https://seb-auth.lovable.app`       |
| `timeout`    | —                   | `30` seconds                         |

You can also pass a custom `requests.Session` via `session=...` if you
need to configure retries, proxies, or connection pooling.

## Context manager

`SebAuth` can be used as a context manager to guarantee that the
underlying HTTP session is closed:

```python
with SebAuth() as seb:
    seb.email.send(to="user@example.com", subject="Hi", body="Hello!")
```

## Roadmap

The SebAuth public API currently exposes the email endpoint. The
`seb.auth` and `seb.database` namespaces are reserved for upcoming
endpoints and will raise `NotImplementedError` until they ship.

## Development

```bash
git clone https://github.com/sebauth/seb-auth-python
cd seb-auth-python
pip install -e ".[dev]"
pytest
```

## License

MIT © SebAuth
