sendly-python 0.1.0__tar.gz

sendly_python-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,52 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  schedule:
+    # Mondays 06:00 UTC -- surface live OpenAPI drift even without a push.
+    - cron: "0 6 * * 1"
+
+# Public repo -> GitHub-hosted standard runners (free for public repos).
+# The org's self-hosted Warp runner group (warp-ubuntu-latest-*) is deliberately
+# NOT used here: it may not be authorized for this repository, and the standard
+# ubuntu-latest runners are sufficient for a pure-Python package.
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.13"]
+    steps:
+      - uses: actions/checkout@v6.0.3
+      - uses: actions/setup-python@v5.6.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package with dev dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Ruff lint
+        run: ruff check .
+      - name: Ruff format check
+        run: ruff format --check .
+      - name: Mypy (strict)
+        run: mypy src
+      - name: Contract tests (SDK surface vs vendored OpenAPI)
+        run: pytest tests/test_contract.py
+      - name: Pytest
+        run: pytest
+      # Non-blocking: diff the vendored spec against the live API so drift shows
+      # up as a warning annotation without failing the build. Runs once (on the
+      # newest interpreter) to avoid duplicate live fetches and annotations.
+      - name: Live OpenAPI drift check (non-blocking)
+        id: spec_drift
+        if: matrix.python-version == '3.13'
+        continue-on-error: true
+        run: python scripts/sync_spec.py --check
+      - name: Annotate OpenAPI drift
+        if: matrix.python-version == '3.13' && steps.spec_drift.outcome == 'failure'
+        run: |
+          echo "::warning title=OpenAPI spec drift::Vendored tests/fixtures/openapi.json differs from the live spec at https://api.sendly.now/api/openapi.json. Run 'python scripts/sync_spec.py' and commit the refreshed copy."

sendly_python-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,62 @@
+name: Release
+
+# Publishes sendly-python to PyPI when a version tag (vX.Y.Z) is pushed.
+# Disjoint from ci.yml (push/PR to main + weekly cron): this runs ONLY on tags,
+# re-runs the full gate, then publishes. A red SDK can never ship.
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Test, build & publish to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi # must match the environment on the PyPI trusted publisher
+    permissions:
+      id-token: write # OIDC for PyPI Trusted Publishing (no token stored)
+    steps:
+      - uses: actions/checkout@v6.0.3
+
+      - uses: actions/setup-python@v5.6.0
+        with:
+          python-version: "3.13"
+
+      - name: Install build + dev toolchain
+        run: |
+          python -m pip install --upgrade pip build
+          pip install -e ".[dev]"
+
+      # Version-consistency gate: the pushed tag must equal both the
+      # pyproject.toml version and the SDK_VERSION constant (User-Agent header).
+      - name: Assert tag matches pyproject + SDK_VERSION
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          VER=$(python -c "import tomllib;print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          SDK=$(python -c "from sendly import SDK_VERSION;print(SDK_VERSION)")
+          echo "tag=$TAG pyproject=$VER SDK_VERSION=$SDK"
+          test "$TAG" = "$VER" || { echo "::error::tag $TAG != pyproject $VER"; exit 1; }
+          test "$TAG" = "$SDK" || { echo "::error::tag $TAG != SDK_VERSION $SDK"; exit 1; }
+
+      - name: Ruff lint
+        run: ruff check .
+
+      - name: Ruff format check
+        run: ruff format --check .
+
+      - name: Mypy (strict)
+        run: mypy src
+
+      - name: Contract tests (SDK surface vs vendored OpenAPI)
+        run: pytest tests/test_contract.py
+
+      - name: Pytest
+        run: pytest
+
+      - name: Build sdist + wheel
+        run: python -m build
+
+      - name: Publish to PyPI (Trusted Publishing / OIDC)
+        uses: pypa/gh-action-pypi-publish@release/v1

sendly_python-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Python caches / build artifacts
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Tooling caches
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Editor / OS
+.idea/
+.vscode/
+.DS_Store
+
+# Local scratch logs
+*.log

sendly_python-0.1.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to `sendly-python` are documented here. This project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Changed
+
+- Re-synced the vendored OpenAPI spec (`tests/fixtures/openapi.json`) to the
+  committed monorepo contract. The client stays thin (opaque `Mapping` bodies),
+  so these are contract/behaviour clarifications rather than method-signature
+  changes:
+  - **Deletes now return HTTP `200` with the deleted resource's id** (was `204`
+    No Content) for `contacts.delete` and `templates.delete`. The SDK still
+    discards the body and returns `None` — no consumer change.
+  - **Invalid input now raises `SendlyValidationError` from HTTP `422`**
+    (`error_code == "VALIDATION_ERROR"`) with a per-field breakdown at
+    `err.body["error"]["details"]["errors"]`. Previously invalid input came back
+    as `400`. Both `400` and `422` map to `SendlyValidationError`, so
+    `except SendlyValidationError` continues to catch validation failures.
+  - **Contacts bulk ops (`bulk_create`, `bulk_delete`) against an unresolved
+    project now return `422 VALIDATION_ERROR`** (was a `NO_PROJECT` error).
+  - **`templates.list` is cursor-paginated** (`limit` / `cursor`) — the former
+    `page` / `pageSize` query params are gone. `contacts.list` was already
+    cursor-based and is unchanged.
+  - Error envelopes on migrated routes now include `success: false` alongside
+    `error.{message,code}`; error parsing reads `message`/`code` and is
+    unaffected by the additive fields.

sendly_python-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Devino Solutions
+
+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.

sendly_python-0.1.0/PKG-INFO

@@ -0,0 +1,311 @@
+Metadata-Version: 2.4
+Name: sendly-python
+Version: 0.1.0
+Summary: Official Sendly Python SDK
+Project-URL: Homepage, https://sendly.now
+Project-URL: Documentation, https://docs.sendly.now
+Project-URL: Repository, https://github.com/DevinoSolutions/sendly-python
+Author-email: Devino Solutions <dev@devino.ca>
+License: MIT
+License-File: LICENSE
+Keywords: api,email,sdk,sendly,transactional-email,webhooks
+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 :: Only
+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 :: Communications :: Email
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx==0.28.1
+Provides-Extra: dev
+Requires-Dist: mypy==1.15.0; extra == 'dev'
+Requires-Dist: pytest==8.3.4; extra == 'dev'
+Requires-Dist: ruff==0.9.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Sendly Python SDK
+
+Official Python SDK for the [Sendly](https://sendly.now) REST API — transactional
+email, contacts, events, domains, templates, email verification, webhooks, and
+suppression.
+
+[![CI](https://github.com/DevinoSolutions/sendly-python/actions/workflows/ci.yml/badge.svg)](https://github.com/DevinoSolutions/sendly-python/actions/workflows/ci.yml)
+
+- Full type hints (ships `py.typed`), `mypy --strict` clean.
+- One small runtime dependency: [`httpx`](https://www.python-httpx.org/).
+- Fail-loud by design: no silent fallbacks, no degraded mode.
+
+## Installation
+
+```bash
+pip install sendly-python
+```
+
+The distribution is published as `sendly-python`; the import name is unchanged:
+
+```python
+import sendly
+```
+
+Alternatively, install the latest `main` directly from GitHub:
+
+```bash
+pip install git+https://github.com/DevinoSolutions/sendly-python.git
+```
+
+Requires Python 3.10+.
+
+## Quickstart
+
+The client reads your API key from the `SENDLY_API_KEY` environment variable:
+
+```python
+from sendly import Sendly
+
+sendly = Sendly()  # reads SENDLY_API_KEY
+
+result = sendly.emails.send(
+    {
+        "from": "hello@yourdomain.com",
+        "to": "customer@example.com",
+        "subject": "Welcome aboard",
+        "body": "<h1>Thanks for signing up!</h1>",
+    }
+)
+print(result["id"])
+```
+
+Or pass the key explicitly:
+
+```python
+sendly = Sendly(api_key="sk_live_...")
+```
+
+If neither an explicit key nor `SENDLY_API_KEY` is set, the constructor raises a
+`SendlyError` immediately.
+
+### Options
+
+```python
+sendly = Sendly(
+    api_key="sk_live_...",
+    base_url="https://api.sendly.now",  # override for staging/self-hosted
+    timeout=30.0,                        # per-request seconds; 0 or None disables
+    default_headers={"X-Trace-Id": "..."},
+)
+```
+
+The client holds an internal connection pool. Reuse a single instance, and close
+it when done (or use it as a context manager):
+
+```python
+with Sendly() as sendly:
+    sendly.emails.send({...})
+```
+
+## Usage by resource
+
+### Emails
+
+```python
+# Single send (pass idempotency_key to dedupe replays for 24h)
+sendly.emails.send({"from": "a@you.com", "to": "b@them.com", "subject": "Hi", "body": "<p>Hi</p>"},
+                   idempotency_key="order-42-receipt")
+
+# Batch send (up to 100)
+sendly.emails.batch({"emails": [{"from": "a@you.com", "to": "b@them.com", "subject": "Hi", "body": "<p>Hi</p>"}]})
+
+# List, get, cancel a scheduled send
+sendly.emails.list({"limit": 20, "status": "DELIVERED"})
+sendly.emails.get("em_123")
+sendly.emails.cancel_schedule("em_123")
+```
+
+### Contacts
+
+```python
+sendly.contacts.create({"email": "user@example.com", "subscribed": True})
+sendly.contacts.upsert({"email": "user@example.com", "data": {"plan": "pro"}})
+sendly.contacts.list({"limit": 50, "search": "example.com"})
+sendly.contacts.get("c_123")
+sendly.contacts.update("c_123", {"data": {"plan": "enterprise"}})
+sendly.contacts.delete("c_123")
+sendly.contacts.bulk_create({"contacts": [{"email": "a@x.com"}, {"email": "b@x.com"}]})
+sendly.contacts.bulk_delete({"emails": ["a@x.com"]})
+```
+
+### Events
+
+```python
+# Track a custom event for a contact (accepts sk_* and pk_* keys)
+result = sendly.events.track({"event": "signup", "email": "user@example.com"})
+print(result["contact"], result["timestamp"])
+
+# Attach an arbitrary payload and set subscription state
+sendly.events.track({"event": "purchase", "email": "user@example.com",
+                     "subscribed": True, "data": {"plan": "pro", "amount": 42}})
+```
+
+### Domains
+
+```python
+sendly.domains.create({"domain": "mail.yourdomain.com", "region": "us-east-1"})
+sendly.domains.list()
+sendly.domains.get("d_123")
+sendly.domains.verify("d_123")
+sendly.domains.get_verification("d_123")
+sendly.domains.delete("d_123")
+```
+
+### Templates
+
+```python
+sendly.templates.create({"name": "Welcome", "subject": "Welcome", "body": "<p>Hi</p>",
+                         "from": "a@you.com", "type": "MARKETING"})
+sendly.templates.list({"limit": 25})  # cursor pagination: pass {"cursor": ...} for the next page
+sendly.templates.get("t_123")
+sendly.templates.update("t_123", {"name": "Welcome v2"})
+sendly.templates.delete("t_123")
+```
+
+### Verify
+
+```python
+# Validate an email address (syntax, MX, disposable domains, plus-addressing).
+# Open endpoint — the SDK still sends your API key, which the API ignores.
+result = sendly.verify.email({"email": "user@example.com"})
+if not result["valid"]:
+    print("Rejected:", result.get("reason"))
+```
+
+### Webhooks
+
+```python
+created = sendly.webhooks.create({"url": "https://you.com/hook", "eventTypes": ["email.delivered"]})
+# Store the signing secret now — it is only returned in full at creation/rotation.
+sendly.webhooks.list()
+sendly.webhooks.get("w_123")
+sendly.webhooks.update("w_123", {"status": "PAUSED"})
+sendly.webhooks.rotate_secret("w_123")
+sendly.webhooks.list_calls("w_123", {"limit": 20})
+sendly.webhooks.delete("w_123")
+```
+
+### Suppression
+
+```python
+sendly.suppression.add({"email": "bounce@example.com", "reason": "MANUAL"})
+sendly.suppression.list({"reason": "MANUAL", "limit": 100})
+sendly.suppression.get("bounce@example.com")
+sendly.suppression.remove("bounce@example.com")
+```
+
+## Error handling
+
+Every non-2xx response raises a `SendlyError` subclass carrying `status_code`,
+`error_code`, `message`, and the raw `body`:
+
+```python
+from sendly import Sendly, SendlyValidationError, SendlyRateLimitError, SendlyError
+
+sendly = Sendly()
+try:
+    sendly.emails.send({"from": "a@you.com", "to": "b@them.com", "subject": "Hi", "body": "<p>Hi</p>"})
+except SendlyValidationError as err:
+    print("Bad request:", err.error_code, err.message)
+except SendlyRateLimitError:
+    print("Slow down and retry with backoff")
+except SendlyError as err:
+    print("Sendly error", err.status_code, err.message)
+```
+
+| Exception | HTTP status |
+| --- | --- |
+| `SendlyValidationError` | 400, 422 |
+| `SendlyAuthenticationError` | 401 |
+| `SendlyPermissionError` | 403 |
+| `SendlyNotFoundError` | 404 |
+| `SendlyConflictError` | 409 |
+| `SendlyRateLimitError` | 429 |
+| `SendlyServerError` | 5xx |
+| `SendlyConnectionError` | transport failure (status `0`) |
+
+All inherit from `SendlyError`.
+
+Invalid input raises `SendlyValidationError`. Migrated routes report it as HTTP
+`422` with `error_code == "VALIDATION_ERROR"` and a per-field breakdown under
+`err.body["error"]["details"]["errors"]`; legacy/malformed requests still use
+`400`. Both surface as `SendlyValidationError`.
+
+## Verifying webhooks
+
+Every delivery is signed. Verify it against the **raw** request body — do not
+parse the JSON first. Two headers are sent:
+
+- `X-Sendly-Signature` — bare lowercase hex HMAC-SHA256 of `"{timestamp}.{body}"`
+  (no `sha256=` prefix).
+- `X-Sendly-Timestamp` — the signing time as a **millisecond** Unix epoch.
+
+`verify_signature` also enforces replay protection: a delivery whose timestamp is
+more than `DEFAULT_TOLERANCE_MS` (5 minutes) from now is rejected. Pass
+`tolerance_ms=math.inf` to disable that check.
+
+```python
+import os
+from flask import Flask, request
+from sendly import construct_event
+
+app = Flask(__name__)
+
+@app.post("/webhook")
+def webhook():
+    payload = request.get_data()  # raw bytes
+    signature = request.headers.get("X-Sendly-Signature", "")
+    timestamp = request.headers.get("X-Sendly-Timestamp", "")
+    secret = os.environ["SENDLY_WEBHOOK_SECRET"]
+    try:
+        event = construct_event(payload, signature, timestamp, secret)
+    except ValueError:
+        return "Invalid signature", 400
+    # handle event["event"], event["data"], ...
+    return "", 200
+```
+
+`verify_signature(payload, signature, timestamp, secret, *, tolerance_ms=...) -> bool`
+is also exported if you only need the boolean check. Both use a constant-time
+comparison and reject a stale or non-numeric timestamp.
+
+## Async
+
+Only a synchronous client ships in v0.1. An `httpx.AsyncClient`-backed async
+variant is planned.
+
+## Development
+
+```bash
+python -m venv .venv
+source .venv/bin/activate            # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+
+ruff check .
+ruff format --check .
+mypy src
+pytest
+```
+
+Tests are fully hermetic (httpx `MockTransport`) and hit no network.
+
+## Documentation
+
+Full API reference: <https://docs.sendly.now>
+
+## License
+
+MIT — see [LICENSE](LICENSE).