sendara 0.2.0__tar.gz

sendara-0.2.0/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.pyc
+dist/
+*.egg-info/

sendara-0.2.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: sendara
+Version: 0.2.0
+Summary: Sendara — multi-channel messaging API (email, SMS, push, voice, webhooks) for Python.
+Project-URL: Homepage, https://sendara.dev
+Project-URL: Documentation, https://sendara.dev/docs
+Author: Sendara
+License: MIT
+Keywords: api,email,messaging,otp,sendara,sms,transactional
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.24
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Sendara — Python SDK
+
+The official Python client for the [Sendara](https://sendara.dev) messaging API:
+email, SMS, broadcasts, contacts, templates, webhooks, and more — with sync and
+async clients, typed models, a typed error hierarchy, automatic retries, and an
+auto-paginating message iterator.
+
+```bash
+pip install sendara
+```
+
+Requires Python 3.9+. Runtime dependency: `httpx`.
+
+## Quickstart
+
+```python
+import os
+from sendara import Sendara, SendaraError
+
+client = Sendara(os.environ["SENDARA_API_KEY"])  # sk_live_... or sk_test_...
+
+# Send an email
+result = client.emails.send(
+    from_="hello@acme.com",
+    to="user@example.com",
+    subject="Welcome to Acme",
+    html="<h1>Welcome 🎉</h1>",
+)
+print(result.id, result.status)
+
+# Send an SMS / OTP
+client.sms.send(to="+254712345678", body="Your Acme code is 481920")
+
+# Paginate every message (cursor handled for you)
+for message in client.messages.iter(channel="email", limit=100):
+    print(message.id, message.status)
+```
+
+### Async
+
+```python
+import asyncio
+from sendara import AsyncSendara
+
+async def main():
+    async with AsyncSendara("sk_live_...") as client:
+        await client.emails.send(to="user@example.com", subject="Hi", html="<p>Hi</p>")
+        async for message in client.messages.iter(limit=100):
+            print(message.id)
+
+asyncio.run(main())
+```
+
+Both clients are context managers (`with` / `async with`) and accept
+`base_url`, `timeout`, `max_retries`, and an optional `http_client`.
+
+```python
+client = Sendara(
+    "sk_live_...",
+    base_url="https://api.sendara.dev",
+    timeout=30.0,
+    max_retries=3,
+)
+```
+
+## Idempotency
+
+Every send accepts an `idempotency_key`. The SDK generates one (UUIDv4)
+automatically when you omit it, so retries are always safe. Pass your own to
+deduplicate across processes:
+
+```python
+client.emails.send(to="u@e.com", subject="s", text="t", idempotency_key="order-42")
+```
+
+## Retries
+
+Idempotent requests (all GET/PUT/DELETE and sends) are retried automatically on
+`429`, `409`, `5xx`, and network/timeout errors, using exponential backoff with
+jitter. A `Retry-After` header is honored when present. Attempts are bounded by
+`max_retries`.
+
+## Errors
+
+Every failure raises a subclass of `SendaraError` carrying `status`, `code`,
+`message`, and `request_id`:
+
+| HTTP        | Exception              |
+| ----------- | ---------------------- |
+| 400 / 422   | `ValidationError`      |
+| 401         | `AuthenticationError`  |
+| 403         | `PermissionError_`     |
+| 404         | `NotFoundError`        |
+| 409         | `ConflictError`        |
+| 429         | `RateLimitError` (`.retry_after`) |
+| 5xx         | `ServerError`          |
+| network     | `APIConnectionError` / `APITimeoutError` |
+
+```python
+from sendara import RateLimitError, SendaraError
+
+try:
+    client.emails.send(to="u@e.com", subject="s", html="<p>x</p>")
+except RateLimitError as e:
+    print("retry after", e.retry_after)
+except SendaraError as e:
+    print(e.status, e.code, e.message)
+```
+
+## Verifying webhooks
+
+`webhooks.verify` recomputes `HMAC-SHA256(secret, "<timestamp>.<raw_body>")`
+(hex) and checks it in constant time against the `Sendara-Signature` header.
+Pass the **raw** request body, never a re-serialized object.
+
+```python
+from sendara import webhooks
+
+# Flask example
+@app.post("/webhooks/sendara")
+def hook():
+    event = webhooks.verify(
+        os.environ["SENDARA_WEBHOOK_SECRET"],
+        request.get_data(),     # raw bytes
+        request.headers,        # case-insensitive mapping
+    )
+    print(event["event_type"], event["message_id"])
+    return "", 200
+```
+
+`verify` raises `WebhookVerificationError` on any mismatch (bad signature,
+missing headers, or a timestamp outside the `tolerance` window, default 300s).
+
+## Method reference
+
+```text
+client.emails.send(to, subject, html=, text=, from_=, message_type=,
+                   template_id=, template_vars=, idempotency_key=, metadata=, test_send=)
+client.emails.send_raw(request)            # POST /v1/send (escape hatch)
+client.emails.send_batch([req, ...])       # POST /v1/send/batch
+client.emails.send_bulk(request)           # POST /v1/send/bulk
+client.sms.send(to, body, sender_id=, message_type=, idempotency_key=)
+
+client.broadcasts.create(**params) / .list(limit=, offset=) / .get(id)
+                 .send(id) / .cancel(id) / .delete(id)
+
+client.messages.list(channel=, status=, from_=, to=, limit=, cursor=)
+client.messages.iter(channel=, status=, from_=, to=, limit=)   # auto-paginating
+client.messages.get(id)
+
+client.suppressions.list(channel=) / .create(channel, recipient, reason=)
+                    .delete(channel, recipient)
+
+client.domains.list() / .create(domain) / .get(domain) / .verify(domain)
+
+client.api_keys.list() / .create(scope=, test_mode=) / .rotate(id) / .revoke(id)
+
+client.usage.get(period=)
+client.usage.set_spend_cap(key_id=, soft_limit_micros=, hard_limit_micros=)
+
+client.billing.get() / .checkout(plan=) / .portal()
+
+client.templates.create(**params) / .list() / .get(id) / .update(id, **params)
+                .delete(id) / .render(id, vars=)
+
+client.contacts.create(**params) / .list(limit=, offset=) / .get(id)
+               .update(id, **params) / .delete(id) / .import_(s3_key=, format=)
+client.lists.create(name, list_type=, segment_rules=) / .list() / .get(id)
+            .update(id, **params) / .delete(id)
+            .add_member(id, contact_id) / .remove_member(id, contact_id) / .members(id)
+
+client.webhooks.create(endpoint_url, event_types=) / .list() / .get(id)
+               .update(id, **params) / .delete(id)
+               .deliveries(id, limit=) / .rotate_secret(id)
+
+client.uploads.create(file, filename=, content_type=)   # multipart image
+
+client.test_recipients.list() / .create(email) / .resend(id) / .delete(id)
+
+webhooks.verify(secret, payload, headers=, signature=, timestamp=, tolerance=300)
+```
+
+The async client (`AsyncSendara`) exposes every method above with `await`;
+`messages.iter` becomes an `async for`.
+
+## Development
+
+```bash
+cd sdk/python
+pip install -e '.[dev]'
+python -m pytest
+```
+
+MIT licensed.

sendara-0.2.0/README.md

@@ -0,0 +1,194 @@
+# Sendara — Python SDK
+
+The official Python client for the [Sendara](https://sendara.dev) messaging API:
+email, SMS, broadcasts, contacts, templates, webhooks, and more — with sync and
+async clients, typed models, a typed error hierarchy, automatic retries, and an
+auto-paginating message iterator.
+
+```bash
+pip install sendara
+```
+
+Requires Python 3.9+. Runtime dependency: `httpx`.
+
+## Quickstart
+
+```python
+import os
+from sendara import Sendara, SendaraError
+
+client = Sendara(os.environ["SENDARA_API_KEY"])  # sk_live_... or sk_test_...
+
+# Send an email
+result = client.emails.send(
+    from_="hello@acme.com",
+    to="user@example.com",
+    subject="Welcome to Acme",
+    html="<h1>Welcome 🎉</h1>",
+)
+print(result.id, result.status)
+
+# Send an SMS / OTP
+client.sms.send(to="+254712345678", body="Your Acme code is 481920")
+
+# Paginate every message (cursor handled for you)
+for message in client.messages.iter(channel="email", limit=100):
+    print(message.id, message.status)
+```
+
+### Async
+
+```python
+import asyncio
+from sendara import AsyncSendara
+
+async def main():
+    async with AsyncSendara("sk_live_...") as client:
+        await client.emails.send(to="user@example.com", subject="Hi", html="<p>Hi</p>")
+        async for message in client.messages.iter(limit=100):
+            print(message.id)
+
+asyncio.run(main())
+```
+
+Both clients are context managers (`with` / `async with`) and accept
+`base_url`, `timeout`, `max_retries`, and an optional `http_client`.
+
+```python
+client = Sendara(
+    "sk_live_...",
+    base_url="https://api.sendara.dev",
+    timeout=30.0,
+    max_retries=3,
+)
+```
+
+## Idempotency
+
+Every send accepts an `idempotency_key`. The SDK generates one (UUIDv4)
+automatically when you omit it, so retries are always safe. Pass your own to
+deduplicate across processes:
+
+```python
+client.emails.send(to="u@e.com", subject="s", text="t", idempotency_key="order-42")
+```
+
+## Retries
+
+Idempotent requests (all GET/PUT/DELETE and sends) are retried automatically on
+`429`, `409`, `5xx`, and network/timeout errors, using exponential backoff with
+jitter. A `Retry-After` header is honored when present. Attempts are bounded by
+`max_retries`.
+
+## Errors
+
+Every failure raises a subclass of `SendaraError` carrying `status`, `code`,
+`message`, and `request_id`:
+
+| HTTP        | Exception              |
+| ----------- | ---------------------- |
+| 400 / 422   | `ValidationError`      |
+| 401         | `AuthenticationError`  |
+| 403         | `PermissionError_`     |
+| 404         | `NotFoundError`        |
+| 409         | `ConflictError`        |
+| 429         | `RateLimitError` (`.retry_after`) |
+| 5xx         | `ServerError`          |
+| network     | `APIConnectionError` / `APITimeoutError` |
+
+```python
+from sendara import RateLimitError, SendaraError
+
+try:
+    client.emails.send(to="u@e.com", subject="s", html="<p>x</p>")
+except RateLimitError as e:
+    print("retry after", e.retry_after)
+except SendaraError as e:
+    print(e.status, e.code, e.message)
+```
+
+## Verifying webhooks
+
+`webhooks.verify` recomputes `HMAC-SHA256(secret, "<timestamp>.<raw_body>")`
+(hex) and checks it in constant time against the `Sendara-Signature` header.
+Pass the **raw** request body, never a re-serialized object.
+
+```python
+from sendara import webhooks
+
+# Flask example
+@app.post("/webhooks/sendara")
+def hook():
+    event = webhooks.verify(
+        os.environ["SENDARA_WEBHOOK_SECRET"],
+        request.get_data(),     # raw bytes
+        request.headers,        # case-insensitive mapping
+    )
+    print(event["event_type"], event["message_id"])
+    return "", 200
+```
+
+`verify` raises `WebhookVerificationError` on any mismatch (bad signature,
+missing headers, or a timestamp outside the `tolerance` window, default 300s).
+
+## Method reference
+
+```text
+client.emails.send(to, subject, html=, text=, from_=, message_type=,
+                   template_id=, template_vars=, idempotency_key=, metadata=, test_send=)
+client.emails.send_raw(request)            # POST /v1/send (escape hatch)
+client.emails.send_batch([req, ...])       # POST /v1/send/batch
+client.emails.send_bulk(request)           # POST /v1/send/bulk
+client.sms.send(to, body, sender_id=, message_type=, idempotency_key=)
+
+client.broadcasts.create(**params) / .list(limit=, offset=) / .get(id)
+                 .send(id) / .cancel(id) / .delete(id)
+
+client.messages.list(channel=, status=, from_=, to=, limit=, cursor=)
+client.messages.iter(channel=, status=, from_=, to=, limit=)   # auto-paginating
+client.messages.get(id)
+
+client.suppressions.list(channel=) / .create(channel, recipient, reason=)
+                    .delete(channel, recipient)
+
+client.domains.list() / .create(domain) / .get(domain) / .verify(domain)
+
+client.api_keys.list() / .create(scope=, test_mode=) / .rotate(id) / .revoke(id)
+
+client.usage.get(period=)
+client.usage.set_spend_cap(key_id=, soft_limit_micros=, hard_limit_micros=)
+
+client.billing.get() / .checkout(plan=) / .portal()
+
+client.templates.create(**params) / .list() / .get(id) / .update(id, **params)
+                .delete(id) / .render(id, vars=)
+
+client.contacts.create(**params) / .list(limit=, offset=) / .get(id)
+               .update(id, **params) / .delete(id) / .import_(s3_key=, format=)
+client.lists.create(name, list_type=, segment_rules=) / .list() / .get(id)
+            .update(id, **params) / .delete(id)
+            .add_member(id, contact_id) / .remove_member(id, contact_id) / .members(id)
+
+client.webhooks.create(endpoint_url, event_types=) / .list() / .get(id)
+               .update(id, **params) / .delete(id)
+               .deliveries(id, limit=) / .rotate_secret(id)
+
+client.uploads.create(file, filename=, content_type=)   # multipart image
+
+client.test_recipients.list() / .create(email) / .resend(id) / .delete(id)
+
+webhooks.verify(secret, payload, headers=, signature=, timestamp=, tolerance=300)
+```
+
+The async client (`AsyncSendara`) exposes every method above with `await`;
+`messages.iter` becomes an `async for`.
+
+## Development
+
+```bash
+cd sdk/python
+pip install -e '.[dev]'
+python -m pytest
+```
+
+MIT licensed.

sendara-0.2.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sendara"
+version = "0.2.0"
+description = "Sendara — multi-channel messaging API (email, SMS, push, voice, webhooks) for Python."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+keywords = ["sendara", "email", "sms", "messaging", "api", "transactional", "otp"]
+authors = [{ name = "Sendara" }]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.24,<1"]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7",
+    "pytest-asyncio>=0.21",
+]
+
+[project.urls]
+Homepage = "https://sendara.dev"
+Documentation = "https://sendara.dev/docs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["sendara"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

sendara-0.2.0/sendara/__init__.py

@@ -0,0 +1,79 @@
+from . import models, webhooks
+from .async_client import AsyncSendara
+from .client import Sendara
+from .errors import (
+    APIConnectionError,
+    APITimeoutError,
+    AuthenticationError,
+    ConflictError,
+    NotFoundError,
+    PermissionError_,
+    RateLimitError,
+    SendaraError,
+    ServerError,
+    ValidationError,
+)
+from .models import (
+    ApiKey,
+    BillingState,
+    BimiDmarc,
+    BimiRecord,
+    BimiStatus,
+    Broadcast,
+    Channel,
+    Contact,
+    ContactList,
+    Domain,
+    Message,
+    MessageType,
+    SendResult,
+    Suppression,
+    Template,
+    TestRecipient,
+    Upload,
+    UsageSummary,
+    WebhookDelivery,
+    WebhookSubscription,
+)
+from .webhooks_verify import WebhookVerificationError
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "Sendara",
+    "AsyncSendara",
+    "SendaraError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "AuthenticationError",
+    "PermissionError_",
+    "ValidationError",
+    "NotFoundError",
+    "ConflictError",
+    "RateLimitError",
+    "ServerError",
+    "WebhookVerificationError",
+    "models",
+    "webhooks",
+    "Channel",
+    "MessageType",
+    "SendResult",
+    "Message",
+    "Broadcast",
+    "Suppression",
+    "Domain",
+    "ApiKey",
+    "UsageSummary",
+    "BillingState",
+    "Template",
+    "Contact",
+    "ContactList",
+    "WebhookSubscription",
+    "WebhookDelivery",
+    "Upload",
+    "TestRecipient",
+    "BimiStatus",
+    "BimiRecord",
+    "BimiDmarc",
+    "__version__",
+]

sendara-0.2.0/sendara/_async_http.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Dict, Optional
+
+import httpx
+
+from ._config import ClientConfig
+from ._transport import JsonBody, PreparedRequest, RequestBuilder, connection_error
+
+
+class AsyncHTTP:
+    """Asynchronous transport over httpx.AsyncClient with retry/backoff."""
+
+    def __init__(
+        self,
+        config: ClientConfig,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        self._builder = RequestBuilder(config)
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.AsyncClient(
+            timeout=self._builder.config.timeout
+        )
+
+    @property
+    def config(self) -> ClientConfig:
+        return self._builder.config
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Optional[JsonBody] = None,
+        files: Optional[Dict[str, Any]] = None,
+        idempotent: Optional[bool] = None,
+    ) -> Any:
+        prepared = self._builder.prepare(
+            method, path, json_body=json_body, files=files, idempotent=idempotent
+        )
+        return await self._send(prepared)
+
+    async def _send(self, prepared: PreparedRequest) -> Any:
+        attempt = 0
+        while True:
+            try:
+                response = await self._client.request(
+                    prepared.method,
+                    prepared.url,
+                    headers=prepared.headers,
+                    json=prepared.json_body if prepared.files is None else None,
+                    files=prepared.files,
+                    timeout=self._builder.config.timeout,
+                )
+            except httpx.HTTPError as exc:
+                if prepared.idempotent and self._builder.should_retry(attempt, None):
+                    await asyncio.sleep(self._builder.backoff_delay(attempt, None))
+                    attempt += 1
+                    continue
+                raise connection_error(exc) from None
+
+            headers = dict(response.headers)
+            if prepared.idempotent and self._builder.should_retry(
+                attempt, response.status_code
+            ):
+                retry_after = self._builder.retry_after_from_headers(headers)
+                await asyncio.sleep(self._builder.backoff_delay(attempt, retry_after))
+                attempt += 1
+                continue
+
+            return self._builder.interpret(
+                response.status_code, response.content, headers
+            )
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncHTTP":
+        return self
+
+    async def __aexit__(self, *_exc: object) -> None:
+        await self.aclose()

sendara-0.2.0/sendara/_config.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+DEFAULT_BASE_URL = "https://api.sendara.dev"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 3
+DEFAULT_USER_AGENT = "sendara-python/0.2.0"
+
+RETRYABLE_STATUS = frozenset({408, 409, 429, 500, 502, 503, 504})
+
+
+@dataclass(frozen=True)
+class ClientConfig:
+    api_key: str
+    base_url: str = DEFAULT_BASE_URL
+    timeout: float = DEFAULT_TIMEOUT
+    max_retries: int = DEFAULT_MAX_RETRIES
+
+    def normalized(self) -> "ClientConfig":
+        return ClientConfig(
+            api_key=self.api_key,
+            base_url=self.base_url.rstrip("/"),
+            timeout=self.timeout,
+            max_retries=max(0, self.max_retries),
+        )