genieos 0.1.0__tar.gz

genieos-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+.env
+.env.*
+.DS_Store

genieos-0.1.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# genieos (Python SDK)
+
+## 0.1.0
+
+Initial release.
+
+- `GenieOS` (sync) and `AsyncGenieOS` (async) clients on top of `httpx`.
+- Pydantic v2 models for typed responses.
+- Auto idempotency keys; retry-on-429/5xx with exponential back-off.
+- Resources: `workspace`, `templates`, `events`, `webhooks`, `audit`, `keys`.
+- Webhook signature helpers: `verify_webhook`, `sign_webhook`, `WebhookSignatureError`.
+- Typed errors inheriting from `GenieOSError`: auth / not-found / validation / conflict / rate-limit / server / network.

genieos-0.1.0/LICENSE

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

genieos-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: genieos
+Version: 0.1.0
+Summary: Official Python SDK for GenieOS — sync + async clients, typed responses, idempotency-aware retries, webhook verification.
+Project-URL: Homepage, https://docs.genieos.pro/sdks/python
+Project-URL: Documentation, https://docs.genieos.pro/sdks/python
+Project-URL: Repository, https://github.com/GenieOS-0/sdk-python
+Project-URL: Issues, https://github.com/GenieOS-0/sdk-python/issues
+Project-URL: Changelog, https://github.com/GenieOS-0/sdk-python/blob/main/CHANGELOG.md
+Author-email: GenieOS <developers@genieos.pro>
+License: MIT
+License-File: LICENSE
+Keywords: drip,email,genieos,mcp,sequences,transactional
+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.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.6
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: posthog>=3.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: python-dotenv>=1.0.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: telemetry
+Requires-Dist: posthog>=3.0.0; extra == 'telemetry'
+Description-Content-Type: text/markdown
+
+# genieos — Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/genieos.svg)](https://pypi.org/project/genieos)
+
+The official Python SDK for [GenieOS](https://genieos.pro). Sync and
+async clients, typed responses (Pydantic), automatic idempotency,
+retry-on-429/5xx with exponential back-off, and webhook signature
+verification.
+
+## Install
+
+```bash
+pip install genieos
+```
+
+Requires Python 3.9+ and `httpx>=0.27`, `pydantic>=2.6`.
+
+## Quickstart (sync)
+
+```python
+from genieos import GenieOS
+
+with GenieOS(api_key="gos_live_...") as mg:
+    ws = mg.workspace.get()
+    print(ws.name, "on", ws.plan)
+
+    send = mg.templates.send(
+        "welcome",
+        to="aki@example.com",
+        variables={"firstName": "Aki"},
+    )
+    print("queued:", send.id)
+```
+
+The API key is also picked up from the `GENIEOS_API_KEY` env var,
+matching the Node SDK and CLI.
+
+## Quickstart (async)
+
+```python
+import asyncio
+from genieos import AsyncGenieOS
+
+async def main():
+    async with AsyncGenieOS() as mg:  # MAILGENIUS_API_KEY env var
+        await mg.events.emit(
+            "subscription.cancelled",
+            email="aki@example.com",
+            traits={"tier": "pro", "reason": "moving to weekly"},
+        )
+
+asyncio.run(main())
+```
+
+## Webhook verification (Flask)
+
+```python
+from flask import Flask, request, abort
+from genieos import verify_webhook, WebhookSignatureError
+
+app = Flask(__name__)
+
+@app.post("/genieos/webhook")
+def webhook():
+    try:
+        delivery = verify_webhook(
+            request.get_data(as_text=True),
+            request.headers,
+            secret=os.environ["MAILGENIUS_WEBHOOK_SECRET"],
+        )
+    except WebhookSignatureError as e:
+        abort(400, str(e))
+
+    if delivery.type == "send.delivered":
+        ... # handle it
+    return "", 204
+```
+
+`verify_webhook` rejects out-of-window timestamps (default ±5 min) and
+performs constant-time signature comparison. The same module exposes
+`sign_webhook` for local testing.
+
+## Error handling
+
+```python
+from genieos import (
+    GenieOSRateLimitError,
+    GenieOSValidationError,
+    GenieOSAuthError,
+)
+
+try:
+    mg.events.emit("checkout.completed", email="aki@example.com")
+except GenieOSRateLimitError as e:
+    time.sleep(e.retry_after_seconds)
+except GenieOSValidationError as e:
+    log.warning("422: %s", e.body)
+except GenieOSAuthError:
+    rotate_my_key()
+```
+
+All SDK errors inherit from `GenieOSError` and expose `.code`,
+`.status`, `.request_id`, `.body`.
+
+## License
+
+MIT

genieos-0.1.0/README.md

@@ -0,0 +1,107 @@
+# genieos — Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/genieos.svg)](https://pypi.org/project/genieos)
+
+The official Python SDK for [GenieOS](https://genieos.pro). Sync and
+async clients, typed responses (Pydantic), automatic idempotency,
+retry-on-429/5xx with exponential back-off, and webhook signature
+verification.
+
+## Install
+
+```bash
+pip install genieos
+```
+
+Requires Python 3.9+ and `httpx>=0.27`, `pydantic>=2.6`.
+
+## Quickstart (sync)
+
+```python
+from genieos import GenieOS
+
+with GenieOS(api_key="gos_live_...") as mg:
+    ws = mg.workspace.get()
+    print(ws.name, "on", ws.plan)
+
+    send = mg.templates.send(
+        "welcome",
+        to="aki@example.com",
+        variables={"firstName": "Aki"},
+    )
+    print("queued:", send.id)
+```
+
+The API key is also picked up from the `GENIEOS_API_KEY` env var,
+matching the Node SDK and CLI.
+
+## Quickstart (async)
+
+```python
+import asyncio
+from genieos import AsyncGenieOS
+
+async def main():
+    async with AsyncGenieOS() as mg:  # MAILGENIUS_API_KEY env var
+        await mg.events.emit(
+            "subscription.cancelled",
+            email="aki@example.com",
+            traits={"tier": "pro", "reason": "moving to weekly"},
+        )
+
+asyncio.run(main())
+```
+
+## Webhook verification (Flask)
+
+```python
+from flask import Flask, request, abort
+from genieos import verify_webhook, WebhookSignatureError
+
+app = Flask(__name__)
+
+@app.post("/genieos/webhook")
+def webhook():
+    try:
+        delivery = verify_webhook(
+            request.get_data(as_text=True),
+            request.headers,
+            secret=os.environ["MAILGENIUS_WEBHOOK_SECRET"],
+        )
+    except WebhookSignatureError as e:
+        abort(400, str(e))
+
+    if delivery.type == "send.delivered":
+        ... # handle it
+    return "", 204
+```
+
+`verify_webhook` rejects out-of-window timestamps (default ±5 min) and
+performs constant-time signature comparison. The same module exposes
+`sign_webhook` for local testing.
+
+## Error handling
+
+```python
+from genieos import (
+    GenieOSRateLimitError,
+    GenieOSValidationError,
+    GenieOSAuthError,
+)
+
+try:
+    mg.events.emit("checkout.completed", email="aki@example.com")
+except GenieOSRateLimitError as e:
+    time.sleep(e.retry_after_seconds)
+except GenieOSValidationError as e:
+    log.warning("422: %s", e.body)
+except GenieOSAuthError:
+    rotate_my_key()
+```
+
+All SDK errors inherit from `GenieOSError` and expose `.code`,
+`.status`, `.request_id`, `.body`.
+
+## License
+
+MIT

genieos-0.1.0/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["hatchling>=1.21"]
+build-backend = "hatchling.build"
+
+[project]
+name = "genieos"
+version = "0.1.0"
+description = "Official Python SDK for GenieOS — sync + async clients, typed responses, idempotency-aware retries, webhook verification."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "GenieOS", email = "developers@genieos.pro" }]
+requires-python = ">=3.9"
+keywords = ["genieos", "email", "transactional", "drip", "sequences", "mcp"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Communications :: Email",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27",
+    "pydantic>=2.6",
+]
+
+[project.urls]
+Homepage = "https://docs.genieos.pro/sdks/python"
+Documentation = "https://docs.genieos.pro/sdks/python"
+Repository = "https://github.com/GenieOS-0/sdk-python"
+Issues = "https://github.com/GenieOS-0/sdk-python/issues"
+Changelog = "https://github.com/GenieOS-0/sdk-python/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+telemetry = [
+    "posthog>=3.0.0",
+]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "respx>=0.21",
+    "mypy>=1.10",
+    "ruff>=0.6",
+    "posthog>=3.0.0",
+    "python-dotenv>=1.0.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/genieos"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/genieos", "README.md", "LICENSE", "CHANGELOG.md", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "B", "UP", "ASYNC"]
+
+[tool.mypy]
+strict = true
+python_version = "3.9"

genieos-0.1.0/src/genieos/__init__.py

@@ -0,0 +1,56 @@
+"""
+GenieOS — official Python SDK.
+
+Quickstart::
+
+    from genieos import GenieOS
+
+    with GenieOS(api_key="gos_live_...") as mg:
+        ws = mg.workspace.get()
+        print(ws.name, ws.plan)
+
+        send = mg.templates.send(
+            "welcome",
+            to="aki@example.com",
+            variables={"firstName": "Aki"},
+        )
+        print("send id:", send.id)
+
+For asynchronous code, use ``AsyncGenieOS`` which exposes the same
+resource surface with awaitable methods.
+"""
+from ._errors import (
+    GenieOSAuthError,
+    GenieOSConflictError,
+    GenieOSError,
+    GenieOSNetworkError,
+    GenieOSNotFoundError,
+    GenieOSRateLimitError,
+    GenieOSServerError,
+    GenieOSValidationError,
+)
+from ._transport import DEFAULT_BASE_URL
+from .async_client import AsyncGenieOS
+from .client import GenieOS
+from .webhooks import VerifiedDelivery, WebhookSignatureError, sign_webhook, verify_webhook
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "DEFAULT_BASE_URL",
+    "GenieOS",
+    "AsyncGenieOS",
+    "GenieOSError",
+    "GenieOSAuthError",
+    "GenieOSNotFoundError",
+    "GenieOSValidationError",
+    "GenieOSConflictError",
+    "GenieOSRateLimitError",
+    "GenieOSServerError",
+    "GenieOSNetworkError",
+    "VerifiedDelivery",
+    "WebhookSignatureError",
+    "verify_webhook",
+    "sign_webhook",
+]

genieos-0.1.0/src/genieos/_errors.py

@@ -0,0 +1,124 @@
+"""
+Typed error hierarchy for the GenieOS SDK — mirrors the catalogue
+in ``packages/sdk-node/src/errors.ts`` so the same docs cover both
+SDKs.
+
+The base class is :class:`GenieOSError`. Every subclass corresponds
+to a documented API error code so callers can
+``except GenieOSRateLimitError`` instead of matching on string codes.
+"""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class GenieOSError(Exception):
+    """Base class for every error raised by the GenieOS SDK."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str = "genieos_error",
+        status: Optional[int] = None,
+        request_id: Optional[str] = None,
+        body: Optional[Any] = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.status = status
+        self.request_id = request_id
+        self.body = body
+
+    def __repr__(self) -> str:  # pragma: no cover - cosmetic
+        parts = [f"{self.__class__.__name__}({self.args[0]!r}", f"code={self.code!r}"]
+        if self.status is not None:
+            parts.append(f"status={self.status}")
+        if self.request_id is not None:
+            parts.append(f"request_id={self.request_id!r}")
+        return ", ".join(parts) + ")"
+
+
+class GenieOSAuthError(GenieOSError):
+    """401/403 — bearer token missing, invalid, revoked, or out-of-scope."""
+
+
+class GenieOSNotFoundError(GenieOSError):
+    """404 — addressed resource does not exist (or is in another workspace)."""
+
+
+class GenieOSValidationError(GenieOSError):
+    """422 — request body / query failed schema validation."""
+
+
+class GenieOSConflictError(GenieOSError):
+    """409 — idempotency conflict, optimistic-concurrency mismatch, etc."""
+
+
+class GenieOSRateLimitError(GenieOSError):
+    """429 — per-key or per-workspace rate limit exceeded.
+
+    ``retry_after_seconds`` mirrors the ``Retry-After`` header on the
+    response and is the recommended back-off duration before the next
+    attempt.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        retry_after_seconds: float,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(message, **kwargs)
+        self.retry_after_seconds = retry_after_seconds
+
+
+class GenieOSServerError(GenieOSError):
+    """5xx — transient server-side fault. Retried automatically by the SDK."""
+
+
+class GenieOSNetworkError(GenieOSError):
+    """Local network / DNS / TLS failure."""
+
+
+def from_response(
+    *,
+    status: int,
+    body: Any,
+    request_id: Optional[str],
+    retry_after_seconds: Optional[float] = None,
+) -> GenieOSError:
+    """Convert an HTTP error response into the appropriate typed error."""
+    err_obj = (body or {}).get("error", {}) if isinstance(body, dict) else {}
+    code = err_obj.get("code") or f"http_{status}"
+    message = err_obj.get("message") or f"HTTP {status}"
+    common = {"code": code, "status": status, "request_id": request_id, "body": body}
+    if status in (401, 403):
+        return GenieOSAuthError(message, **common)
+    if status == 404:
+        return GenieOSNotFoundError(message, **common)
+    if status == 409:
+        return GenieOSConflictError(message, **common)
+    if status == 422:
+        return GenieOSValidationError(message, **common)
+    if status == 429:
+        # `or` would coerce a legitimate 0 ("retry now") into 1s, so check None.
+        ra = retry_after_seconds if retry_after_seconds is not None else 1.0
+        return GenieOSRateLimitError(message, retry_after_seconds=ra, **common)
+    if status >= 500:
+        return GenieOSServerError(message, **common)
+    return GenieOSError(message, **common)
+
+
+__all__ = [
+    "GenieOSError",
+    "GenieOSAuthError",
+    "GenieOSNotFoundError",
+    "GenieOSValidationError",
+    "GenieOSConflictError",
+    "GenieOSRateLimitError",
+    "GenieOSServerError",
+    "GenieOSNetworkError",
+    "from_response",
+]

genieos-0.1.0/src/genieos/_telemetry.py

@@ -0,0 +1,82 @@
+"""
+Optional PostHog telemetry for the GenieOS Python SDK.
+
+Telemetry is enabled only when POSTHOG_PROJECT_TOKEN is set.  It tracks
+SDK-usage signals (which operations are called, error rates by code,
+webhook verification outcomes) to help the GenieOS team understand
+how the SDK is used and where developers hit problems.
+
+No PII is ever sent — the distinct_id is a SHA-256 hash of the API key
+prefix, so it is workspace-scoped but cannot be reverse-engineered.
+"""
+from __future__ import annotations
+
+import hashlib
+import os
+from typing import Any
+
+_client: Any = None
+_initialized = False
+
+# Used for calls (e.g. webhook verification) where no API key is available.
+ANONYMOUS_DISTINCT_ID = "sdk-py-webhook-verifier"
+
+
+def _distinct_id(api_key: str) -> str:
+    """Return a non-reversible, workspace-scoped identifier."""
+    return "sdk-py-" + hashlib.sha256(api_key.encode()).hexdigest()[:16]
+
+
+def get_client() -> Any | None:
+    """Return the (lazily-initialized) PostHog client, or None if disabled."""
+    global _client, _initialized
+    if _initialized:
+        return _client
+
+    _initialized = True
+    token = os.environ.get("POSTHOG_PROJECT_TOKEN", "").strip()
+    if not token:
+        return None
+
+    try:
+        from posthog import Posthog  # type: ignore[import]
+
+        kwargs: dict[str, Any] = {"enable_exception_autocapture": True}
+        host = os.environ.get("POSTHOG_HOST", "").strip()
+        if host:
+            kwargs["host"] = host
+        _client = Posthog(token, **kwargs)
+    except Exception:
+        # Never let PostHog errors surface to SDK consumers.
+        _client = None
+
+    return _client
+
+
+def capture(
+    api_key: str,
+    event: str,
+    properties: dict[str, Any] | None = None,
+    *,
+    distinct_id: str | None = None,
+) -> None:
+    """Fire a PostHog event; silently no-ops if telemetry is disabled.
+
+    If ``distinct_id`` is provided it is used directly; otherwise it is
+    derived from ``api_key`` via SHA-256 so no raw key is transmitted.
+    """
+    client = get_client()
+    if client is None:
+        return
+    try:
+        did = distinct_id if distinct_id is not None else _distinct_id(api_key)
+        client.capture(
+            distinct_id=did,
+            event=event,
+            properties=properties or {},
+        )
+    except Exception:
+        pass
+
+
+__all__ = ["capture", "get_client", "ANONYMOUS_DISTINCT_ID"]