Metadata-Version: 2.4
Name: esauti
Version: 1.1.0
Summary: eSauti SDK for Marketing events, tenant APIs, Verify, WhatsApp, and Wallet
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: pydantic<3,>=2.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 Marketing SDK for Python

Send customer and business events to an eSauti marketing tenant to drive
marketing workflows. This SDK also retains its marketing REST API support
for contacts, campaigns, and other tenant resources.


## Customer API: Verify, WhatsApp, and Wallet

One `esauti` installation includes both Marketing and the Customer API:

```python
import os
from esauti.api import ESauti

api = ESauti(os.environ["ESAUTI_API_KEY"])
balance = api.wallet.balance()
verification = api.verify.create(
    {"recipient": "+14165551234", "channel": "whatsapp", "language": "en"},
    idempotency_key="signup-123-send-otp-1",
)
```

The Customer API defaults to `https://api.esauti.com` and has its own API key.
It exposes `verify`, `whatsapp`, and `wallet`, with typed dictionaries in
`esauti.api.models` and errors in `esauti.api.errors`. It makes one request
attempt, rejects redirects, and requires explicit idempotency keys where specified.
Existing `from esauti import EsautiClient` usage, `client.api` tenant resources,
and Marketing events remain available with their existing configuration.

Migrating from `esauti-api`: replace `from esauti_api import ESauti` with
`from esauti.api import ESauti`. Update model and error imports in the same way,
install this repository's `esauti` package, then remove the old `esauti-api`
dependency. Method calls and response dictionaries are unchanged.

See [Customer API documentation](docs/11-customer-api.md) for all operations,
error handling, and retry guidance.

## Which SDK should I use?

| Your integration | SDK | Python import |
|---|---|---|
| Track events for marketing workflows; manage marketing tenant resources | eSauti Marketing SDK (`esauti`) | `from esauti import EsautiClient` |
| Send messages, verify users, manage WhatsApp accounts/templates, or retrieve wallet balances | [eSauti API SDK](../esauti-python/README.md) (`esauti-api`) | `from esauti_api import ESauti` |

The Marketing SDK keeps the existing `esauti` package, imports, and public
methods. Both SDKs can coexist and release independently. Configure each
client with the credentials and endpoint for its own product.

## Requirements

- Python 3.10+
- `requests >= 2.20`

## Installation

```bash
pip install esauti
```

Or from source:

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

## Quick Start

### 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,
    customer={"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",
    customer={"id": "cus_456"},
    data={"value": 99.99, "currency": "USD"},
    source="shopify",
)
```

### Marketing 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)
```

## 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 marketing event and tenant API call    |
| [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).

