Metadata-Version: 2.4
Name: esauti
Version: 1.0.1
Summary: Production-ready Python SDK for eSauti — REST API + Event Injection
Author-email: eSauti <plugin@esauti.com>
License: MIT License
        
        Copyright (c) 2026 eSauti
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
        
Project-URL: Homepage, https://esauti.com
Project-URL: Repository, https://github.com/esauti/esauti-python
Project-URL: Documentation, https://docs.esauti.com/sdk/python
Keywords: esauti,sdk,events,marketing,automation
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.20.0
Requires-Dist: PyYAML>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: responses>=0.24; extra == "dev"
Requires-Dist: freezegun>=1.4; extra == "dev"
Dynamic: license-file

# eSauti Python SDK

Production-ready Python SDK for eSauti. Supports both the REST API and the Event Injection API.

## Requirements

- Python 3.10+
- `requests >= 2.25`

## Installation

```bash
pip install esauti
```

Or from source:

```bash
git clone https://github.com/esauti/pyesauti
cd pyesauti
pip install -e ".[dev]"
```

## Quick Start

### REST API

```python
from esauti import EsautiClient

client = EsautiClient(
    base_url="https://your-instance.esauti.com/api",
    token="YOUR_BEARER_TOKEN",
)

# List contacts
contacts = client.api.contacts.list(limit=10)
print(contacts)

# Create a contact
contact = client.api.contacts.create({"firstname": "Jane", "email": "jane@esauti.com"})
print(contact)
```

### Event Injection

```python
from esauti import EsautiClient
from esauti.events import EventType

client = EsautiClient(
    base_url="https://your-instance.esauti.com",
    token="YOUR_BEARER_TOKEN",
)

receipt = client.events.send(
    EventType.CUSTOMER_CREATED,
    identity={"id": "cus_123", "email": "jane@esauti.com"},
    data={"status": "active"},
    source="my-app",
)
print(receipt)
```

### HMAC Signing

```python
from esauti import EsautiClient

client = EsautiClient(
    base_url="https://your-instance.esauti.com",
    token="YOUR_BEARER_TOKEN",
    hmac_secret="your-hmac-secret",
)

receipt = client.events.send(
    "order.created",
    identity={"id": "cus_456"},
    data={"value": 99.99, "currency": "USD"},
    source="shopify",
)
```

## Configuration

```python
client = EsautiClient(
    base_url="https://...",
    token="...",
    hmac_secret=None,           # optional HMAC secret for event signing
    timeout=30.0,               # request timeout in seconds
    max_retries=3,              # max retry attempts
    debug=False,                # enable debug logging
    redact_pii=False,           # redact email/phone in logs
    events_endpoint="/api/integrations/events",  # override events URL
    source="sdk",               # X-eSauti-Source header value
)
```

## Running Tests

```bash
pip install -e ".[dev]"
pytest
```

## Project Structure

```
src/esauti/
├── __init__.py         # Public API
├── client.py           # EsautiClient entrypoint
├── auth.py             # BearerAuth, HmacAuth, CompositeAuth
├── transport.py        # HttpTransport abstraction + requests impl
├── retry.py            # RetryPolicy with exponential backoff + jitter
├── exceptions.py       # ApiError, EventValidationError
├── _logging.py         # Redacting structured logger
├── deadletter.py       # DeadLetter sink (JSONL file or custom hook)
├── api/
│   ├── __init__.py
│   └── client.py       # OpenAPI module (contacts, campaigns, etc.)
└── events/
    ├── __init__.py
    ├── registry.py     # EventType enum + registry loader
    ├── builder.py      # Event envelope builder + validator
    └── client.py       # EventsClient (build / send)
```

## Documentation

| Document                                             | Description                                         |
|------------------------------------------------------|-----------------------------------------------------|
| [01 – Installation & Setup](docs/01-installation.md) | Requirements, pip install, environment variables    |
| [02 – Getting Started](docs/02-getting-started.md)   | Your first API call and first event in 5 minutes    |
| [03 – Authentication](docs/03-authentication.md)     | Bearer tokens, API keys, HMAC signing               |
| [04 – REST API Module](docs/04-api-module.md)        | Contacts, campaigns, forms and all resource methods |
| [05 – Events Module](docs/05-events-module.md)       | Building, validating and sending canonical events   |
| [06 – Event Types Reference](docs/06-event-types.md) | All 225 canonical event type constants              |
| [07 – Error Handling](docs/07-error-handling.md)     | ApiError, TransportError, EventValidationError      |
| [08 – Reliability](docs/08-reliability.md)           | Retry policy, dead-letter sink, idempotency         |
| [09 – Logging](docs/09-logging.md)                   | Debug logging, PII redaction                        |
| [10 – Advanced](docs/10-advanced.md)                 | Custom transport, testing, multi-tenant usage       |

## Changelog

See [CHANGELOG.md](CHANGELOG.md).

