esauti 1.0.1

Production-ready Python SDK for eSauti — REST API + Event Injection

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

pip install esauti

Or from source:

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

Quick Start

REST API

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": "[e-mail]"})
print(contact)

Event Injection

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": "[e-mail]"},
    data={"status": "active"},
    source="my-app",
)
print(receipt)

HMAC Signing

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

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

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	Requirements, pip install, environment variables
02 – Getting Started	Your first API call and first event in 5 minutes
03 – Authentication	Bearer tokens, API keys, HMAC signing
04 – REST API Module	Contacts, campaigns, forms and all resource methods
05 – Events Module	Building, validating and sending canonical events
06 – Event Types Reference	All 225 canonical event type constants
07 – Error Handling	ApiError, TransportError, EventValidationError
08 – Reliability	Retry policy, dead-letter sink, idempotency
09 – Logging	Debug logging, PII redaction
10 – Advanced	Custom transport, testing, multi-tenant usage

Changelog

See CHANGELOG.md.