cosmoner-sdk 1.1.0__tar.gz

cosmoner_sdk-1.1.0/.gitignore

@@ -0,0 +1,26 @@
+# JavaScript
+node_modules/
+dist/
+
+# Python
+__pycache__/
+*.egg-info/
+dist/
+build/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+
+# PHP
+vendor/
+.phpunit.result.cache
+.phpcs-cache
+.phpstan.cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+.DS_Store

cosmoner_sdk-1.1.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: cosmoner-sdk
+Version: 1.1.0
+Summary: Cosmoner SDK for Python
+Project-URL: Homepage, https://cosmoner.com
+License-Expression: MIT
+Keywords: cosmoner,sdk
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Provides-Extra: lint
+Requires-Dist: mypy>=1.15; extra == 'lint'
+Requires-Dist: ruff>=0.9; extra == 'lint'
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest-httpx>=0.28; extra == 'test'
+Requires-Dist: pytest>=7.0; extra == 'test'

cosmoner_sdk-1.1.0/README.md

@@ -0,0 +1,136 @@
+# cosmoner-sdk
+
+Official Cosmoner SDK for Python.
+
+## Installation
+
+```bash
+pip install cosmoner-sdk
+```
+
+## Usage
+
+```python
+from cosmoner import Cosmoner
+
+client = Cosmoner(
+    api_key="your-api-key",
+    project_id="your-project-id",
+)
+
+# Send to a single recipient
+result = client.email.send(
+    credential_id="your-credential-id",
+    to="recipient@example.com",
+    subject="Hello from Cosmoner",
+    html="<h1>Hello!</h1><p>This is a test email.</p>",
+)
+print(result["data"]["messageId"])
+
+# Send to multiple recipients (up to 50)
+client.email.send(
+    credential_id="your-credential-id",
+    to=["alice@example.com", "bob@example.com"],
+    subject="Team Update",
+    text="Plain text email body",
+    reply_to="noreply@yourdomain.com",
+)
+```
+
+## Configuration
+
+| Parameter     | Required | Default                    | Description                                        |
+| ------------- | -------- | -------------------------- | -------------------------------------------------- |
+| `api_key`     | Yes      | —                          | Your Cosmoner API key                              |
+| `project_id`  | No       | —                          | Default project; can also be passed per call       |
+| `base_url`    | No       | `https://api.cosmoner.com` | API base URL override                              |
+| `timeout`     | No       | `30.0`                     | Per-request timeout in seconds                     |
+| `max_retries` | No       | `2`                        | Retries for transient failures (see [Retries](#retries)) |
+
+`project_id` is optional so one client can span projects. Pass it per call to
+override the default:
+
+```python
+client = Cosmoner(api_key="your-api-key")
+
+client.email.send(project_id="proj-2", credential_id="...", to="...", subject="...", text="...")
+```
+
+## Async
+
+`AsyncCosmoner` mirrors the sync client method for method:
+
+```python
+from cosmoner import AsyncCosmoner
+
+async with AsyncCosmoner(api_key="your-api-key", project_id="your-project-id") as client:
+    await client.email.send(
+        credential_id="your-credential-id",
+        to="recipient@example.com",
+        subject="Hello",
+        text="Hi there",
+    )
+```
+
+Both clients hold a connection pool. Use them as context managers, or call
+`client.close()` / `await client.aclose()` when you are done.
+
+## Retries
+
+Transient failures are retried automatically with exponential backoff and full
+jitter, honouring `Retry-After` when the API sends it.
+
+- **429** is always retried — the request was rejected before it was processed,
+  so replaying it cannot duplicate a side effect.
+- **Timeouts and 5xx** are retried only for idempotent methods. A write such as
+  `email.send` is *not* replayed, because the API may have completed the send
+  before failing to answer.
+
+Set `max_retries=0` to disable retries entirely.
+
+## Email
+
+### `client.email.send(...)`
+
+| Parameter       | Type                     | Required | Description                          |
+| --------------- | ------------------------ | -------- | ------------------------------------ |
+| `credential_id` | `str`                    | Yes      | SMTP credential ID                   |
+| `to`            | `str \| list[str]`       | Yes      | Recipient(s), max 50                 |
+| `subject`       | `str`                    | Yes      | Email subject line                   |
+| `html`          | `str`                    | No*      | HTML body                            |
+| `text`          | `str`                    | No*      | Plain text body                      |
+| `reply_to`      | `str \| list[str]`       | No       | Reply-to address(es), max 5          |
+| `project_id`    | `str`                    | No       | Overrides the client-level project   |
+
+\* At least one of `html` or `text` must be provided.
+
+## Error Handling
+
+Every failure raises a subclass of `CosmonerError`, so you can catch broadly or
+narrowly:
+
+```python
+from cosmoner import Cosmoner, CosmonerError, RateLimitError
+
+try:
+    client.email.send(...)
+except RateLimitError as e:
+    print(e.retry_after)  # seconds, when the API supplies it
+except CosmonerError as e:
+    print(e.code)     # e.g. "INSUFFICIENT_SCOPE"
+    print(e.status)   # e.g. 403
+    print(e.details)  # field-level validation errors, when present
+    print(str(e))     # Human-readable message
+```
+
+| Exception                  | Raised on                                     |
+| -------------------------- | --------------------------------------------- |
+| `ValidationError`          | 400, 422                                      |
+| `AuthenticationError`      | 401                                           |
+| `InsufficientScopeError`   | 403 — API key is missing a `resource:action`  |
+| `NotFoundError`            | 404                                           |
+| `ConflictError`            | 409                                           |
+| `RateLimitError`           | 429                                           |
+| `ServerError`              | 5xx                                           |
+| `CosmonerTimeoutError`     | Request exceeded `timeout`                    |
+| `CosmonerConnectionError`  | DNS, TCP, TLS or socket failure               |

cosmoner_sdk-1.1.0/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cosmoner-sdk"
+version = "1.1.0"
+description = "Cosmoner SDK for Python"
+requires-python = ">=3.9"
+license = "MIT"
+dependencies = [
+  "httpx>=0.24",
+]
+keywords = ["cosmoner", "sdk"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cosmoner"]
+
+[project.optional-dependencies]
+test = [
+  "pytest>=7.0",
+  "pytest-httpx>=0.28",
+  "pytest-asyncio>=0.23",
+]
+lint = [
+  "ruff>=0.9",
+  "mypy>=1.15",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 90
+target-version = "py39"
+src = ["src", "tests"]
+extend-exclude = ["*.md"]
+
+[tool.ruff.lint]
+select = [
+  "E",    # pycodestyle errors
+  "W",    # pycodestyle warnings
+  "F",    # pyflakes
+  "I",    # isort
+  "B",    # flake8-bugbear
+  "UP",   # pyupgrade
+  "SIM",  # flake8-simplify
+  "RUF",  # ruff-specific
+  "D",    # pydocstyle — every function/class needs a docstring
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+# Tests document themselves through their names; docstrings on every case are noise.
+"tests/*" = ["D"]
+
+[tool.mypy]
+files = ["src"]
+strict = true
+warn_unused_ignores = true
+
+[project.urls]
+Homepage = "https://cosmoner.com"

cosmoner_sdk-1.1.0/src/cosmoner/__init__.py

@@ -0,0 +1,52 @@
+"""Cosmoner SDK for Python."""
+
+from ._version import __version__
+from .client import AsyncCosmoner, Cosmoner
+from .errors import (
+    AuthenticationError,
+    ConflictError,
+    CosmonerConnectionError,
+    CosmonerError,
+    CosmonerTimeoutError,
+    InsufficientScopeError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+    WebhookSignatureError,
+)
+from .webhook_signature import (
+    DEFAULT_TOLERANCE_SECONDS,
+    DELIVERY_ID_HEADER,
+    EVENT_TYPE_HEADER,
+    SIGNATURE_HEADER,
+    construct_event,
+    verify_webhook_signature,
+)
+from .webhooks import WEBHOOK_EVENT_TYPES, AsyncWebhooksService, WebhooksService
+
+__all__ = [
+    "DEFAULT_TOLERANCE_SECONDS",
+    "DELIVERY_ID_HEADER",
+    "EVENT_TYPE_HEADER",
+    "SIGNATURE_HEADER",
+    "WEBHOOK_EVENT_TYPES",
+    "AsyncCosmoner",
+    "AsyncWebhooksService",
+    "AuthenticationError",
+    "ConflictError",
+    "Cosmoner",
+    "CosmonerConnectionError",
+    "CosmonerError",
+    "CosmonerTimeoutError",
+    "InsufficientScopeError",
+    "NotFoundError",
+    "RateLimitError",
+    "ServerError",
+    "ValidationError",
+    "WebhookSignatureError",
+    "WebhooksService",
+    "__version__",
+    "construct_event",
+    "verify_webhook_signature",
+]

cosmoner_sdk-1.1.0/src/cosmoner/_config.py

@@ -0,0 +1,61 @@
+"""Shared, validated configuration for the sync and async clients."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+DEFAULT_BASE_URL = "https://api.cosmoner.com"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RETRIES = 2
+
+
+@dataclass(frozen=True)
+class ClientConfig:
+    """Immutable connection settings shared by a client and its service namespaces."""
+
+    api_key: str
+    project_id: str | None
+    base_url: str
+    timeout: float
+    max_retries: int
+
+
+def build_config(
+    api_key: str,
+    project_id: str | None,
+    base_url: str = DEFAULT_BASE_URL,
+    timeout: float = DEFAULT_TIMEOUT,
+    max_retries: int = DEFAULT_MAX_RETRIES,
+) -> ClientConfig:
+    """Validates constructor arguments and normalizes them into a ``ClientConfig``.
+
+    ``project_id`` is optional so a single client can span projects, but an
+    explicitly empty string is rejected rather than silently treated as unset —
+    that almost always means an unresolved environment variable.
+    """
+    if not api_key:
+        raise ValueError("api_key is required")
+    if project_id is not None and not project_id:
+        raise ValueError("project_id is required")
+    if timeout <= 0:
+        raise ValueError("timeout must be greater than 0")
+    if max_retries < 0:
+        raise ValueError("max_retries cannot be negative")
+
+    return ClientConfig(
+        api_key=api_key,
+        project_id=project_id,
+        base_url=base_url.rstrip("/"),
+        timeout=timeout,
+        max_retries=max_retries,
+    )
+
+
+def resolve_project_id(config: ClientConfig, override: str | None = None) -> str:
+    """Returns the per-call project id, falling back to the client-level default."""
+    project_id = override or config.project_id
+    if not project_id:
+        raise ValueError(
+            "project_id is required — pass it to the Cosmoner client or to this method"
+        )
+    return project_id

cosmoner_sdk-1.1.0/src/cosmoner/_retry.py

@@ -0,0 +1,84 @@
+"""Retry policy governing which failed requests are safe to send again."""
+
+from __future__ import annotations
+
+import random
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+# Methods the HTTP spec defines as idempotent: replaying one cannot create a
+# second side effect, so they are safe to retry after a timeout or a 5xx.
+IDEMPOTENT_METHODS = frozenset({"GET", "HEAD", "OPTIONS", "PUT", "DELETE"})
+
+BACKOFF_BASE_SECONDS = 0.5
+BACKOFF_CAP_SECONDS = 8.0
+
+
+@dataclass(frozen=True)
+class RetryPolicy:
+    """Decides whether a given failure should be retried, and how long to wait."""
+
+    max_retries: int
+
+    def should_retry(
+        self,
+        *,
+        attempt: int,
+        method: str,
+        status: int | None,
+        retry_non_idempotent: bool = False,
+    ) -> bool:
+        """Returns whether another attempt is warranted.
+
+        A ``status`` of ``None`` means the request failed at the transport layer
+        and never reached the API.
+
+        429 is always retryable regardless of method: the request was rejected
+        before it was processed, so replaying it cannot duplicate a side effect.
+        Timeouts and 5xx are different — the API may well have completed the work
+        before failing to answer, so those are only retried for idempotent
+        methods, or when the caller opts in because the request carries an
+        idempotency key the server honours.
+        """
+        if attempt >= self.max_retries:
+            return False
+
+        if status == 429:
+            return True
+
+        is_retryable_failure = status is None or status >= 500
+        if not is_retryable_failure:
+            return False
+
+        return method.upper() in IDEMPOTENT_METHODS or retry_non_idempotent
+
+    def backoff_seconds(self, attempt: int, retry_after: float | None = None) -> float:
+        """Returns the delay before the next attempt.
+
+        A server-supplied ``Retry-After`` wins outright. Otherwise the delay is
+        exponential with full jitter, which spreads a thundering herd of clients
+        that all got rate limited in the same window.
+        """
+        if retry_after is not None and retry_after >= 0:
+            return min(retry_after, BACKOFF_CAP_SECONDS)
+
+        ceiling = min(BACKOFF_BASE_SECONDS * (2**attempt), BACKOFF_CAP_SECONDS)
+        return random.uniform(0, ceiling)
+
+
+def parse_retry_after(headers: Mapping[str, str]) -> float | None:
+    """Reads a ``Retry-After`` header expressed in seconds.
+
+    The API does not currently send this header; it is honoured so the SDK
+    starts respecting it the moment the platform adds it. The HTTP-date form is
+    ignored deliberately — it is rare in practice and jittered backoff is a
+    perfectly good fallback.
+    """
+    raw = headers.get("retry-after") or headers.get("Retry-After")
+    if raw is None:
+        return None
+
+    try:
+        return float(raw)
+    except (TypeError, ValueError):
+        return None

cosmoner_sdk-1.1.0/src/cosmoner/_transport.py

@@ -0,0 +1,209 @@
+"""HTTP transport: header assembly, retries, and response/error decoding."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+import uuid
+from collections.abc import Mapping
+from typing import Any
+
+import httpx
+
+from ._config import ClientConfig
+from ._retry import RetryPolicy, parse_retry_after
+from ._version import USER_AGENT
+from .errors import (
+    CosmonerConnectionError,
+    CosmonerError,
+    CosmonerTimeoutError,
+    error_from_response,
+)
+
+# Methods that mutate state and therefore carry an idempotency key.
+WRITE_METHODS = frozenset({"POST", "PUT", "PATCH", "DELETE"})
+
+
+class _BaseTransport:
+    """Shared request construction and response decoding for both transports."""
+
+    def __init__(self, config: ClientConfig) -> None:
+        self._config = config
+        self._policy = RetryPolicy(max_retries=config.max_retries)
+
+    def _url(self, path: str) -> str:
+        """Joins a route path onto the configured base URL."""
+        return f"{self._config.base_url}{path}"
+
+    def _headers(
+        self,
+        method: str,
+        has_body: bool,
+        idempotency_key: str | None,
+    ) -> dict[str, str]:
+        """Builds the header set for one request.
+
+        The idempotency key is generated once per logical request and reused
+        across retries, so a replayed write can be collapsed server-side. The
+        API does not consume this header yet — it is sent now so that retries
+        become safe for writes as soon as it does.
+        """
+        headers = {
+            "Authorization": f"Bearer {self._config.api_key}",
+            "Accept": "application/json",
+            "User-Agent": USER_AGENT,
+        }
+        if has_body:
+            headers["Content-Type"] = "application/json"
+        if method.upper() in WRITE_METHODS:
+            headers["Idempotency-Key"] = idempotency_key or str(uuid.uuid4())
+        return headers
+
+    def _decode(self, response: httpx.Response) -> Any:
+        """Parses a successful response body, or raises the mapped API error."""
+        try:
+            body: Any = response.json()
+        except ValueError:
+            body = None
+
+        if response.is_success:
+            if body is None:
+                raise CosmonerError(
+                    status=response.status_code,
+                    code="INVALID_RESPONSE",
+                    message="API returned a non-JSON response",
+                )
+            return body
+
+        raise error_from_response(
+            status=response.status_code,
+            body=body,
+            headers=response.headers,
+            retry_after=parse_retry_after(response.headers),
+        )
+
+
+class Transport(_BaseTransport):
+    """Synchronous HTTP transport backed by a pooled ``httpx.Client``."""
+
+    def __init__(self, config: ClientConfig) -> None:
+        super().__init__(config)
+        self._client = httpx.Client(timeout=config.timeout)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Mapping[str, Any] | None = None,
+        params: Mapping[str, Any] | None = None,
+        idempotency_key: str | None = None,
+        retry_non_idempotent: bool = False,
+    ) -> Any:
+        """Issues a request, retrying transient failures, and returns the parsed body."""
+        url = self._url(path)
+        headers = self._headers(method, json is not None, idempotency_key)
+        attempt = 0
+
+        while True:
+            status: int | None = None
+            retry_after: float | None = None
+            error: CosmonerConnectionError | None = None
+
+            try:
+                response = self._client.request(
+                    method, url, json=json, params=params, headers=headers
+                )
+                status = response.status_code
+                retry_after = parse_retry_after(response.headers)
+
+                if response.is_success:
+                    return self._decode(response)
+            except httpx.TimeoutException as err:
+                response, error = None, CosmonerTimeoutError(f"Request timed out: {err}")
+            except httpx.HTTPError as err:
+                response, error = None, CosmonerConnectionError(f"Request failed: {err}")
+            else:
+                error = None
+
+            if not self._policy.should_retry(
+                attempt=attempt,
+                method=method,
+                status=status,
+                retry_non_idempotent=retry_non_idempotent,
+            ):
+                if error is not None:
+                    raise error
+                # ``response`` is always set when no transport error was captured.
+                assert response is not None
+                return self._decode(response)  # raises the mapped API error
+
+            time.sleep(self._policy.backoff_seconds(attempt, retry_after))
+            attempt += 1
+
+    def close(self) -> None:
+        """Closes the underlying connection pool."""
+        self._client.close()
+
+
+class AsyncTransport(_BaseTransport):
+    """Asynchronous HTTP transport backed by a pooled ``httpx.AsyncClient``."""
+
+    def __init__(self, config: ClientConfig) -> None:
+        super().__init__(config)
+        self._client = httpx.AsyncClient(timeout=config.timeout)
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Mapping[str, Any] | None = None,
+        params: Mapping[str, Any] | None = None,
+        idempotency_key: str | None = None,
+        retry_non_idempotent: bool = False,
+    ) -> Any:
+        """Issues a request, retrying transient failures, and returns the parsed body."""
+        url = self._url(path)
+        headers = self._headers(method, json is not None, idempotency_key)
+        attempt = 0
+
+        while True:
+            status: int | None = None
+            retry_after: float | None = None
+            error: CosmonerConnectionError | None = None
+
+            try:
+                response = await self._client.request(
+                    method, url, json=json, params=params, headers=headers
+                )
+                status = response.status_code
+                retry_after = parse_retry_after(response.headers)
+
+                if response.is_success:
+                    return self._decode(response)
+            except httpx.TimeoutException as err:
+                response, error = None, CosmonerTimeoutError(f"Request timed out: {err}")
+            except httpx.HTTPError as err:
+                response, error = None, CosmonerConnectionError(f"Request failed: {err}")
+            else:
+                error = None
+
+            if not self._policy.should_retry(
+                attempt=attempt,
+                method=method,
+                status=status,
+                retry_non_idempotent=retry_non_idempotent,
+            ):
+                if error is not None:
+                    raise error
+                # ``response`` is always set when no transport error was captured.
+                assert response is not None
+                return self._decode(response)  # raises the mapped API error
+
+            await asyncio.sleep(self._policy.backoff_seconds(attempt, retry_after))
+            attempt += 1
+
+    async def aclose(self) -> None:
+        """Closes the underlying connection pool."""
+        await self._client.aclose()

cosmoner_sdk-1.1.0/src/cosmoner/_version.py

@@ -0,0 +1,12 @@
+"""Resolves the installed package version for the SDK's User-Agent header."""
+
+from __future__ import annotations
+
+from importlib import metadata
+
+try:
+    __version__ = metadata.version("cosmoner-sdk")
+except metadata.PackageNotFoundError:  # running from a source checkout
+    __version__ = "0.0.0"
+
+USER_AGENT = f"cosmoner-python/{__version__}"