duta-sdk 0.1.0__tar.gz

duta_sdk-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.pyc
+.venv/

duta_sdk-0.1.0/LICENSE

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

duta_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: duta-sdk
+Version: 0.1.0
+Summary: Official Python SDK for Duta — transactional email for developers.
+Project-URL: Homepage, https://duta.indra.sh
+Project-URL: Repository, https://github.com/Fawwazs17/duta-python
+Author: Duta
+License: MIT
+License-File: LICENSE
+Keywords: duta,email,resend-alternative,ses,transactional-email
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# Duta Python SDK
+
+Official Python client for [Duta](https://duta.indra.sh). Zero dependencies, standard library only.
+
+## Install
+
+```bash
+pip install duta-sdk
+```
+
+## Quickstart
+
+```python
+from duta import Duta
+
+duta = Duta("duta_live_xxx")
+
+result = duta.emails.send({
+    "from": "hello@yourdomain.com",
+    "to": "user@example.com",
+    "subject": "Welcome to Duta",
+    "html": "<p>Thanks for signing up!</p>",
+})
+print("Sent:", result["id"])
+```
+
+Get an API key from the [dashboard](https://app.duta.indra.sh). The sender domain must be verified first.
+
+## Error handling
+
+Methods raise `DutaError` on failure:
+
+```python
+from duta import Duta, DutaError
+
+duta = Duta("duta_live_xxx")
+try:
+    duta.emails.send({ "from": "...", "to": "...", "subject": "Hi", "text": "Hello" })
+except DutaError as e:
+    print(e.status_code, e.name, e.message)
+    # e.name: authentication_error | permission_denied | rate_limit_exceeded | ...
+```
+
+## API
+
+### `Duta(api_key, base_url=..., timeout=30.0)`
+
+### `duta.emails.send(params)`
+
+`params` keys: `from`, `to` (str or list), `subject`, `html`, `text`, `reply_to`, `tags` (dict). Returns a dict with `id` and `status`.
+
+### `duta.emails.get(email_id)`
+
+Retrieve one email. Requires a full-access API key.
+
+### `duta.emails.list(page=1, limit=20)`
+
+List emails, newest first. Requires a full-access API key.
+
+## License
+
+MIT

duta_sdk-0.1.0/README.md

@@ -0,0 +1,62 @@
+# Duta Python SDK
+
+Official Python client for [Duta](https://duta.indra.sh). Zero dependencies, standard library only.
+
+## Install
+
+```bash
+pip install duta-sdk
+```
+
+## Quickstart
+
+```python
+from duta import Duta
+
+duta = Duta("duta_live_xxx")
+
+result = duta.emails.send({
+    "from": "hello@yourdomain.com",
+    "to": "user@example.com",
+    "subject": "Welcome to Duta",
+    "html": "<p>Thanks for signing up!</p>",
+})
+print("Sent:", result["id"])
+```
+
+Get an API key from the [dashboard](https://app.duta.indra.sh). The sender domain must be verified first.
+
+## Error handling
+
+Methods raise `DutaError` on failure:
+
+```python
+from duta import Duta, DutaError
+
+duta = Duta("duta_live_xxx")
+try:
+    duta.emails.send({ "from": "...", "to": "...", "subject": "Hi", "text": "Hello" })
+except DutaError as e:
+    print(e.status_code, e.name, e.message)
+    # e.name: authentication_error | permission_denied | rate_limit_exceeded | ...
+```
+
+## API
+
+### `Duta(api_key, base_url=..., timeout=30.0)`
+
+### `duta.emails.send(params)`
+
+`params` keys: `from`, `to` (str or list), `subject`, `html`, `text`, `reply_to`, `tags` (dict). Returns a dict with `id` and `status`.
+
+### `duta.emails.get(email_id)`
+
+Retrieve one email. Requires a full-access API key.
+
+### `duta.emails.list(page=1, limit=20)`
+
+List emails, newest first. Requires a full-access API key.
+
+## License
+
+MIT

duta_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "duta-sdk"
+version = "0.1.0"
+description = "Official Python SDK for Duta — transactional email for developers."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Duta" }]
+keywords = ["duta", "email", "transactional-email", "ses", "resend-alternative"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://duta.indra.sh"
+Repository = "https://github.com/Fawwazs17/duta-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/duta"]

duta_sdk-0.1.0/src/duta/__init__.py

@@ -0,0 +1,7 @@
+"""Official Python SDK for Duta — transactional email for developers."""
+
+from .client import Duta, Emails
+from .errors import DutaError
+
+__all__ = ["Duta", "Emails", "DutaError"]
+__version__ = "0.1.0"

duta_sdk-0.1.0/src/duta/client.py

@@ -0,0 +1,108 @@
+"""The Duta client."""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Any, Dict, List, Optional, Union
+
+from .errors import DutaError
+
+DEFAULT_BASE_URL = "https://api.duta.indra.sh"
+
+
+class Emails:
+    """The ``emails`` resource: send, retrieve, and list emails."""
+
+    def __init__(self, client: "Duta") -> None:
+        self._client = client
+
+    def send(self, params: Dict[str, Any]) -> Dict[str, Any]:
+        """Send a transactional email.
+
+        Example::
+
+            duta.emails.send({
+                "from": "hello@yourdomain.com",
+                "to": "user@example.com",
+                "subject": "Welcome",
+                "html": "<p>Thanks for signing up!</p>",
+            })
+
+        Accepts ``from``, ``to``, ``subject``, ``html``, ``text``, ``reply_to``,
+        and ``tags``. Returns a dict with ``id`` and ``status``.
+        Raises :class:`DutaError` on failure.
+        """
+        body: Dict[str, Any] = {
+            "from": params["from"],
+            "to": params["to"],
+            "subject": params["subject"],
+        }
+        if params.get("html") is not None:
+            body["html"] = params["html"]
+        if params.get("text") is not None:
+            body["text"] = params["text"]
+        if params.get("reply_to") is not None:
+            body["replyTo"] = params["reply_to"]
+        if params.get("tags") is not None:
+            body["tags"] = params["tags"]
+        return self._client._request("POST", "/v1/email/send", body)
+
+    def get(self, email_id: str) -> Dict[str, Any]:
+        """Retrieve a single email by ID. Requires a full-access API key."""
+        return self._client._request("GET", f"/v1/email/{email_id}")
+
+    def list(self, page: int = 1, limit: int = 20) -> Dict[str, Any]:
+        """List emails, most recent first. Requires a full-access API key."""
+        return self._client._request("GET", f"/v1/email?page={page}&limit={limit}")
+
+
+class Duta:
+    """Duta API client.
+
+    Example::
+
+        from duta import Duta
+
+        duta = Duta("duta_live_xxx")
+        duta.emails.send({
+            "from": "hello@yourdomain.com",
+            "to": "user@example.com",
+            "subject": "Hello",
+            "text": "It works!",
+        })
+    """
+
+    def __init__(self, api_key: str, base_url: str = DEFAULT_BASE_URL, timeout: float = 30.0) -> None:
+        if not api_key:
+            raise ValueError("A Duta API key is required. Create one at https://app.duta.indra.sh.")
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self.emails = Emails(self)
+
+    def _request(self, method: str, path: str, body: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        data = json.dumps(body).encode("utf-8") if body is not None else None
+        req = urllib.request.Request(
+            f"{self._base_url}{path}",
+            data=data,
+            method=method,
+            headers={
+                "Authorization": f"Bearer {self._api_key}",
+                "Content-Type": "application/json",
+            },
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+                raw = resp.read().decode("utf-8")
+                return json.loads(raw) if raw else {}
+        except urllib.error.HTTPError as exc:
+            raw = exc.read().decode("utf-8")
+            try:
+                parsed = json.loads(raw) if raw else None
+            except json.JSONDecodeError:
+                parsed = None
+            raise DutaError.from_response(exc.code, parsed) from None
+        except urllib.error.URLError as exc:
+            raise DutaError("network_error", str(exc.reason), 0) from None

duta_sdk-0.1.0/src/duta/errors.py

@@ -0,0 +1,47 @@
+"""Error types for the Duta SDK."""
+
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+_NAME_BY_STATUS = {
+    400: "validation_error",
+    401: "authentication_error",
+    403: "permission_denied",
+    404: "not_found",
+    422: "unprocessable_entity",
+    429: "rate_limit_exceeded",
+    500: "internal_server_error",
+}
+
+
+class DutaError(Exception):
+    """Raised when the Duta API returns an error.
+
+    Attributes:
+        name: Machine-readable error name, e.g. ``rate_limit_exceeded``.
+        message: Human-readable description.
+        status_code: HTTP status code (0 for network errors).
+        blocked: Suppressed recipient addresses, present on some 422 errors.
+    """
+
+    def __init__(self, name: str, message: str, status_code: int, blocked: Optional[List[str]] = None) -> None:
+        super().__init__(message)
+        self.name = name
+        self.message = message
+        self.status_code = status_code
+        self.blocked = blocked
+
+    @classmethod
+    def from_response(cls, status_code: int, body: Any) -> "DutaError":
+        """Normalise either of Duta's error shapes into a DutaError."""
+        fallback = _NAME_BY_STATUS.get(status_code, "api_error")
+        if isinstance(body, dict):
+            blocked = body.get("blocked") if isinstance(body.get("blocked"), list) else None
+            # Rate-limit shape: { statusCode, name, message }
+            if isinstance(body.get("name"), str) and isinstance(body.get("message"), str):
+                return cls(body["name"], body["message"], status_code, blocked)
+            # Common shape: { error: str }
+            if isinstance(body.get("error"), str):
+                return cls(fallback, body["error"], status_code, blocked)
+        return cls(fallback, f"Request failed with status {status_code}", status_code)