zindua-sdk 1.0.0__tar.gz

zindua_sdk-1.0.0/.gitignore

@@ -0,0 +1,63 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+examples/**/node_modules/
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# local build artifacts in examples
+examples/**/.next/
+examples/**/dist/
+examples/**/build/
+examples/**/package-lock.json
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# WhatsApp Baileys auth (per project)
+.wa-sessions/
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+!.env.example
+
+# npm publish token (local only)
+packages/zindua-js/.npmrc
+
+# OAuth client downloads (never commit secrets)
+config/google-oauth.client.json
+config/microsoft-oauth.client.json
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+# local support uploads (replace with object storage in production)
+/public/support-uploads/*
+!/public/support-uploads/.gitkeep

zindua_sdk-1.0.0/LICENSE

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

zindua_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: zindua-sdk
+Version: 1.0.0
+Summary: Official Zindua SDK for Python — transactional email and WhatsApp via POST /api/v1/send.
+Project-URL: Homepage, https://zindua.run/fastapi
+Project-URL: Documentation, https://zindua.run/developers
+Project-URL: Repository, https://github.com/bbasabana/zindua
+Author-email: Zindua <hello@zindua.run>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: email,fastapi,otp,sdk,transactional,whatsapp,zindua
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.110.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: uvicorn>=0.29.0; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.110.0; extra == 'fastapi'
+Description-Content-Type: text/markdown
+
+# zindua-sdk
+
+Official **server-side** Python SDK for [Zindua](https://zindua.run): send transactional **email** and **WhatsApp** messages.
+
+| | |
+|---|---|
+| FastAPI guide | [zindua.run/fastapi](https://zindua.run/fastapi) |
+| Full API reference | [zindua.run/developers](https://zindua.run/developers) |
+| Dashboard | [zindua.run/login](https://zindua.run/login) |
+
+```bash
+pip install zindua-sdk
+```
+
+**Requirements:** Python 3.10+, run only on your **backend** (never ship `ZINDUA_API_KEY` to browsers).
+
+## Quick start
+
+```python
+import asyncio
+from zindua import Zindua
+
+async def main():
+    client = Zindua(api_key="znd_test_xxxxxxxxxxxxxxxxxxxxxxxx")
+    result = await client.send(
+        to="user@example.com",
+        template="otp-verification",
+        lang="fr",
+        variables={"code": "482910", "appName": "MyApp"},
+    )
+    print(result.log_id, result.status)
+
+asyncio.run(main())
+```
+
+## FastAPI
+
+```python
+from zindua.integrations.fastapi import get_zindua
+
+@app.post("/send-otp")
+async def send_otp(body: SendOtpRequest, zindua: Zindua = Depends(get_zindua)):
+    return await zindua.send(to=body.to, template="otp-verification", variables={"code": body.code})
+```
+
+## CLI
+
+```bash
+export ZINDUA_API_KEY=znd_test_...
+python -m zindua doctor
+python -m zindua send --to user@example.com --template otp-verification --var code=482910
+```
+
+## Publish (maintainers)
+
+```bash
+cd packages/zindua-python
+python -m pip install build twine
+python -m build
+twine upload dist/*
+```
+
+Bump `version` in `pyproject.toml` and `PYTHON_SDK_VERSION` in the app before each release.
+
+## License
+
+MIT © [Zindua](https://zindua.run)

zindua_sdk-1.0.0/README.md

@@ -0,0 +1,67 @@
+# zindua-sdk
+
+Official **server-side** Python SDK for [Zindua](https://zindua.run): send transactional **email** and **WhatsApp** messages.
+
+| | |
+|---|---|
+| FastAPI guide | [zindua.run/fastapi](https://zindua.run/fastapi) |
+| Full API reference | [zindua.run/developers](https://zindua.run/developers) |
+| Dashboard | [zindua.run/login](https://zindua.run/login) |
+
+```bash
+pip install zindua-sdk
+```
+
+**Requirements:** Python 3.10+, run only on your **backend** (never ship `ZINDUA_API_KEY` to browsers).
+
+## Quick start
+
+```python
+import asyncio
+from zindua import Zindua
+
+async def main():
+    client = Zindua(api_key="znd_test_xxxxxxxxxxxxxxxxxxxxxxxx")
+    result = await client.send(
+        to="user@example.com",
+        template="otp-verification",
+        lang="fr",
+        variables={"code": "482910", "appName": "MyApp"},
+    )
+    print(result.log_id, result.status)
+
+asyncio.run(main())
+```
+
+## FastAPI
+
+```python
+from zindua.integrations.fastapi import get_zindua
+
+@app.post("/send-otp")
+async def send_otp(body: SendOtpRequest, zindua: Zindua = Depends(get_zindua)):
+    return await zindua.send(to=body.to, template="otp-verification", variables={"code": body.code})
+```
+
+## CLI
+
+```bash
+export ZINDUA_API_KEY=znd_test_...
+python -m zindua doctor
+python -m zindua send --to user@example.com --template otp-verification --var code=482910
+```
+
+## Publish (maintainers)
+
+```bash
+cd packages/zindua-python
+python -m pip install build twine
+python -m build
+twine upload dist/*
+```
+
+Bump `version` in `pyproject.toml` and `PYTHON_SDK_VERSION` in the app before each release.
+
+## License
+
+MIT © [Zindua](https://zindua.run)

zindua_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "zindua-sdk"
+version = "1.0.0"
+description = "Official Zindua SDK for Python — transactional email and WhatsApp via POST /api/v1/send."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Zindua", email = "hello@zindua.run" }]
+keywords = ["zindua", "email", "whatsapp", "otp", "transactional", "sdk", "fastapi"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.27.0",
+]
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.110.0"]
+dev = ["pytest>=8.0.0", "pytest-asyncio>=0.23.0", "fastapi>=0.110.0", "uvicorn>=0.29.0"]
+
+[project.urls]
+Homepage = "https://zindua.run/fastapi"
+Documentation = "https://zindua.run/developers"
+Repository = "https://github.com/bbasabana/zindua"
+
+[project.scripts]
+zindua = "zindua.__main__:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/zindua"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

zindua_sdk-1.0.0/src/zindua/__init__.py

@@ -0,0 +1,15 @@
+from zindua.client import Zindua
+from zindua.errors import ZinduaError
+from zindua.types import LogStatus, SendResult, TemplateInfo
+from zindua.validate import DEFAULT_API_BASE
+
+__all__ = [
+    "Zindua",
+    "ZinduaError",
+    "SendResult",
+    "LogStatus",
+    "TemplateInfo",
+    "DEFAULT_API_BASE",
+]
+
+__version__ = "1.0.0"

zindua_sdk-1.0.0/src/zindua/__main__.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+import re
+import sys
+
+from zindua import Zindua
+from zindua.errors import ZinduaError
+
+API_KEY_RE = re.compile(r"^znd_(live|test)_[a-z0-9]{24}$")
+
+
+def _load_dotenv() -> None:
+    for name in (".env", ".env.local"):
+        if not os.path.isfile(name):
+            continue
+        with open(name, encoding="utf-8") as fh:
+            for line in fh:
+                line = line.strip()
+                if not line or line.startswith("#") or "=" not in line:
+                    continue
+                key, value = line.split("=", 1)
+                key = key.strip()
+                value = value.strip().strip('"').strip("'")
+                os.environ.setdefault(key, value)
+
+
+def _resolve_api_key(flag: str | None) -> str:
+    _load_dotenv()
+    key = (flag or os.environ.get("ZINDUA_API_KEY") or "").strip()
+    if not key:
+        print("ZINDUA_API_KEY is not set.", file=sys.stderr)
+        sys.exit(1)
+    return key
+
+
+async def _doctor(api_key: str) -> int:
+    print("Zindua doctor")
+    ok_format = bool(API_KEY_RE.match(api_key))
+    print(f"  API key format: {'ok' if ok_format else 'invalid'}")
+    if not ok_format:
+        return 1
+    client = Zindua(api_key=api_key)
+    try:
+        project = await client.get_project()
+    except ZinduaError as exc:
+        print(f"  GET /project: failed ({exc.code}) {exc}")
+        return 1
+    name = project.get("project", {}).get("name") if isinstance(project.get("project"), dict) else project.get("name")
+    channels = project.get("channels") if isinstance(project.get("channels"), dict) else {}
+    email_ready = bool((channels.get("email") or {}).get("ready") if isinstance(channels.get("email"), dict) else channels.get("email"))
+    wa_ready = bool((channels.get("whatsapp") or {}).get("ready") if isinstance(channels.get("whatsapp"), dict) else channels.get("whatsapp"))
+    print(f"  GET /project: ok ({name or 'unknown'})")
+    print(f"  Email channel: {'ready' if email_ready else 'not connected'}")
+    print(f"  WhatsApp channel: {'ready' if wa_ready else 'not connected'}")
+    return 0
+
+
+async def _send(api_key: str, args: argparse.Namespace) -> int:
+    variables: dict[str, str] = {}
+    for item in args.var or []:
+        if "=" not in item:
+            print(f"Invalid --var {item!r}, expected key=value", file=sys.stderr)
+            return 1
+        key, value = item.split("=", 1)
+        variables[key.strip()] = value
+
+    client = Zindua(api_key=api_key)
+    try:
+        result = await client.send(
+            to=args.to,
+            template=args.template,
+            channel=args.channel,
+            lang=args.lang,
+            variables=variables or None,
+        )
+    except ZinduaError as exc:
+        print(f"send failed ({exc.code}): {exc}", file=sys.stderr)
+        return 1
+
+    print(f"ok logId={result.log_id} status={result.status} langUsed={result.lang_used}")
+    return 0
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="zindua", description="Zindua Python SDK CLI")
+    parser.add_argument("--api-key", dest="api_key", help="Override ZINDUA_API_KEY")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("doctor", help="Verify API key and project connectivity")
+
+    send_p = sub.add_parser("send", help="Send a test message")
+    send_p.add_argument("--to", required=True)
+    send_p.add_argument("--template", required=True)
+    send_p.add_argument("--channel", choices=["email", "whatsapp"], default="email")
+    send_p.add_argument("--lang")
+    send_p.add_argument("--var", action="append", help="Template variable key=value")
+
+    args = parser.parse_args()
+    api_key = _resolve_api_key(args.api_key)
+
+    if args.command == "doctor":
+        raise SystemExit(asyncio.run(_doctor(api_key)))
+    if args.command == "send":
+        raise SystemExit(asyncio.run(_send(api_key, args)))
+
+    parser.print_help()
+    raise SystemExit(1)
+
+
+if __name__ == "__main__":
+    main()

zindua_sdk-1.0.0/src/zindua/client.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+from typing import Any
+
+from zindua.errors import ZinduaError
+from zindua.http import HttpClient
+from zindua.types import LogStatus, SendResult, TemplateInfo
+from zindua.validate import (
+    build_send_payload,
+    resolve_base_url,
+    validate_api_key,
+    validate_site_url,
+    validate_timeout,
+)
+
+
+class Zindua:
+    """Async Zindua API client (server-side only)."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str | None = None,
+        timeout: float | None = None,
+        site_url: str | None = None,
+    ) -> None:
+        self._api_key = validate_api_key(api_key)
+        self._base_url = resolve_base_url(base_url)
+        self._timeout = validate_timeout(timeout)
+        self._site_url = validate_site_url(site_url)
+        self._http = HttpClient(self._api_key, self._base_url, self._timeout, self._site_url)
+
+    def is_test_mode(self) -> bool:
+        return self._api_key.startswith("znd_test_")
+
+    async def send(
+        self,
+        *,
+        to: str,
+        template: str,
+        channel: str | None = None,
+        lang: str | None = None,
+        variables: dict[str, str] | None = None,
+        cc: str | None = None,
+        bcc: str | None = None,
+        reply_to: str | None = None,
+        attachments: list[dict[str, str]] | None = None,
+    ) -> SendResult:
+        payload = build_send_payload(
+            to=to,
+            template=template,
+            channel=channel,
+            lang=lang,
+            variables=variables,
+            cc=cc,
+            bcc=bcc,
+            reply_to=reply_to,
+            attachments=attachments,
+        )
+        data = await self._http.request("POST", "send", payload)
+        if data.get("success") is not True or not isinstance(data.get("logId"), str):
+            raise ZinduaError("API response missing success or logId.", status=200, code="INVALID_RESPONSE")
+        return SendResult.from_api(data)
+
+    async def get_project(self) -> dict[str, Any]:
+        return await self._http.request("GET", "project")
+
+    async def get_templates(self) -> dict[str, Any]:
+        data = await self._http.request("GET", "templates")
+        templates_raw = data.get("templates") if isinstance(data.get("templates"), list) else []
+        return {
+            "templates": [
+                TemplateInfo.from_api(item) for item in templates_raw if isinstance(item, dict)
+            ],
+            "limits": data.get("limits") if isinstance(data.get("limits"), dict) else None,
+        }
+
+    async def get_log(self, log_id: str) -> LogStatus:
+        trimmed = log_id.strip()
+        if not trimmed:
+            raise ZinduaError("log_id is required.", status=0, code="MISSING_FIELDS")
+        data = await self._http.request("GET", f"logs/{trimmed}")
+        return LogStatus.from_api(data)
+
+    async def connect(self, site_url: str | None = None) -> dict[str, Any]:
+        url = validate_site_url(site_url) or self._site_url
+        if not url:
+            raise ZinduaError("siteUrl is required for connect().", status=0, code="INVALID_OPTIONS")
+        data = await self._http.request("POST", "connect", {"siteUrl": url})
+        if data.get("ok") is not True:
+            raise ZinduaError("API response missing connect payload.", status=200, code="INVALID_RESPONSE")
+        return data
+
+    def send_sync(self, **kwargs: Any) -> SendResult:
+        import asyncio
+
+        return asyncio.run(self.send(**kwargs))
+
+    def get_project_sync(self) -> dict[str, Any]:
+        import asyncio
+
+        return asyncio.run(self.get_project())
+
+    def get_templates_sync(self) -> dict[str, Any]:
+        import asyncio
+
+        return asyncio.run(self.get_templates())
+
+    def get_log_sync(self, log_id: str) -> LogStatus:
+        import asyncio
+
+        return asyncio.run(self.get_log(log_id))
+
+    def connect_sync(self, site_url: str | None = None) -> dict[str, Any]:
+        import asyncio
+
+        return asyncio.run(self.connect(site_url=site_url))

zindua_sdk-1.0.0/src/zindua/errors.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ZinduaError(Exception):
+    message: str
+    status: int = 0
+    code: str = "API_ERROR"
+    details: dict[str, Any] | None = None
+
+    def __str__(self) -> str:
+        return self.message

zindua_sdk-1.0.0/src/zindua/http.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from zindua.errors import ZinduaError
+
+SDK_VERSION = "1.0.0"
+USER_AGENT = f"Zindua-Python/{SDK_VERSION}"
+
+
+class HttpClient:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str,
+        timeout_s: float,
+        site_url: str | None = None,
+    ) -> None:
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout_s = timeout_s
+        self.site_url = site_url
+
+    def _headers(self) -> dict[str, str]:
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "User-Agent": USER_AGENT,
+            "Accept": "application/json",
+        }
+        if self.site_url:
+            headers["X-Zindua-Site-Url"] = self.site_url
+        return headers
+
+    def _parse_error(self, status: int, body: dict[str, Any]) -> ZinduaError:
+        message = body.get("error") if isinstance(body.get("error"), str) else None
+        if not message and isinstance(body.get("message"), str):
+            message = body["message"]
+        if not message:
+            message = f"Request failed with HTTP {status}"
+
+        details: dict[str, Any] = {}
+        if isinstance(body.get("code"), str):
+            details["code"] = body["code"]
+        if isinstance(body.get("hint"), str):
+            details["hint"] = body["hint"]
+        if isinstance(body.get("retryAfterSec"), (int, float)):
+            details["retryAfterSec"] = body["retryAfterSec"]
+        if isinstance(body.get("boundSite"), str):
+            details["boundSite"] = body["boundSite"]
+
+        hint = body.get("hint")
+        full = f"{message} {hint}" if isinstance(hint, str) and hint else message
+        code = body.get("code") if isinstance(body.get("code"), str) else "API_ERROR"
+        return ZinduaError(full, status=status, code=code, details=details or None)
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        json_body: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        url = f"{self.base_url}/{path.lstrip('/')}"
+        headers = self._headers()
+        if json_body is not None:
+            headers["Content-Type"] = "application/json"
+
+        try:
+            async with httpx.AsyncClient(timeout=self.timeout_s, follow_redirects=False) as client:
+                response = await client.request(method.upper(), url, headers=headers, json=json_body)
+        except httpx.TimeoutException as exc:
+            raise ZinduaError(
+                f"Request timed out after {self.timeout_s}s.",
+                status=0,
+                code="REQUEST_TIMEOUT",
+            ) from exc
+        except httpx.HTTPError as exc:
+            raise ZinduaError("Network request failed.", status=0, code="API_ERROR") from exc
+
+        try:
+            data = response.json() if response.content else {}
+        except ValueError as exc:
+            raise ZinduaError("API returned non-JSON response.", status=response.status_code, code="INVALID_RESPONSE") from exc
+
+        if not isinstance(data, dict):
+            raise ZinduaError("API returned invalid JSON object.", status=response.status_code, code="INVALID_RESPONSE")
+
+        if response.status_code < 200 or response.status_code >= 300:
+            raise self._parse_error(response.status_code, data)
+        return data
+
+    def request_sync(
+        self,
+        method: str,
+        path: str,
+        json_body: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        url = f"{self.base_url}/{path.lstrip('/')}"
+        headers = self._headers()
+        if json_body is not None:
+            headers["Content-Type"] = "application/json"
+
+        try:
+            with httpx.Client(timeout=self.timeout_s, follow_redirects=False) as client:
+                response = client.request(method.upper(), url, headers=headers, json=json_body)
+        except httpx.TimeoutException as exc:
+            raise ZinduaError(
+                f"Request timed out after {self.timeout_s}s.",
+                status=0,
+                code="REQUEST_TIMEOUT",
+            ) from exc
+        except httpx.HTTPError as exc:
+            raise ZinduaError("Network request failed.", status=0, code="API_ERROR") from exc
+
+        try:
+            data = response.json() if response.content else {}
+        except ValueError as exc:
+            raise ZinduaError("API returned non-JSON response.", status=response.status_code, code="INVALID_RESPONSE") from exc
+
+        if not isinstance(data, dict):
+            raise ZinduaError("API returned invalid JSON object.", status=response.status_code, code="INVALID_RESPONSE")
+
+        if response.status_code < 200 or response.status_code >= 300:
+            raise self._parse_error(response.status_code, data)
+        return data

zindua_sdk-1.0.0/src/zindua/integrations/fastapi.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import os
+from functools import lru_cache
+from typing import Annotated
+
+from zindua import Zindua
+
+try:
+    from fastapi import Depends
+except ImportError:  # pragma: no cover
+    Depends = None  # type: ignore[misc, assignment]
+
+
+@lru_cache
+def get_zindua() -> Zindua:
+    api_key = os.environ.get("ZINDUA_API_KEY", "").strip()
+    if not api_key:
+        raise RuntimeError("ZINDUA_API_KEY is not set.")
+    return Zindua(
+        api_key=api_key,
+        base_url=os.environ.get("ZINDUA_API_BASE_URL") or None,
+        site_url=os.environ.get("ZINDUA_SITE_URL") or None,
+    )
+
+
+if Depends is not None:
+    ZinduaDep = Annotated[Zindua, Depends(get_zindua)]
+else:
+    ZinduaDep = Zindua  # type: ignore[misc, assignment]
+
+__all__ = ["get_zindua", "ZinduaDep"]

zindua_sdk-1.0.0/src/zindua/types.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal
+
+SendChannel = Literal["email", "whatsapp"]
+
+
+@dataclass
+class AttachmentInput:
+    url: str
+    filename: str | None = None
+
+
+@dataclass
+class SendResult:
+    success: bool
+    channel: SendChannel
+    status: str
+    log_id: str
+    lang_used: str | None = None
+    lang_fallback: bool | None = None
+    test_mode: bool | None = None
+    project: str | None = None
+    context: dict[str, Any] | None = None
+
+    @classmethod
+    def from_api(cls, data: dict[str, Any]) -> "SendResult":
+        return cls(
+            success=bool(data.get("success")),
+            channel="whatsapp" if data.get("channel") == "whatsapp" else "email",
+            status=str(data.get("status") or "queued"),
+            log_id=str(data["logId"]),
+            lang_used=data.get("langUsed") if isinstance(data.get("langUsed"), str) else None,
+            lang_fallback=data.get("langFallback") if isinstance(data.get("langFallback"), bool) else None,
+            test_mode=data.get("testMode") if isinstance(data.get("testMode"), bool) else None,
+            project=data.get("project") if isinstance(data.get("project"), str) else None,
+            context=data.get("context") if isinstance(data.get("context"), dict) else None,
+        )
+
+
+@dataclass
+class LogStatus:
+    log_id: str
+    channel: str
+    recipient: str
+    status: str
+    template_slug: str | None
+    lang_used: str | None
+    message_id: str | None
+    error: str | None
+    lang_fallback: bool
+    is_test_mode: bool
+    has_attachments: bool
+    created_at: str | None
+    opened_at: str | None
+    clicked_at: str | None
+
+    @classmethod
+    def from_api(cls, data: dict[str, Any]) -> "LogStatus":
+        log = data.get("log") if isinstance(data.get("log"), dict) else data
+        return cls(
+            log_id=str(log.get("logId") or log.get("id") or ""),
+            channel=str(log.get("channel") or "email"),
+            recipient=str(log.get("recipient") or ""),
+            status=str(log.get("status") or "queued"),
+            template_slug=log.get("templateSlug") if isinstance(log.get("templateSlug"), str) else None,
+            lang_used=log.get("langUsed") if isinstance(log.get("langUsed"), str) else None,
+            message_id=log.get("messageId") if isinstance(log.get("messageId"), str) else None,
+            error=log.get("error") if isinstance(log.get("error"), str) else None,
+            lang_fallback=bool(log.get("langFallback")),
+            is_test_mode=bool(log.get("isTestMode")),
+            has_attachments=bool(log.get("hasAttachments")),
+            created_at=str(log.get("createdAt")) if log.get("createdAt") else None,
+            opened_at=str(log.get("openedAt")) if log.get("openedAt") else None,
+            clicked_at=str(log.get("clickedAt")) if log.get("clickedAt") else None,
+        )
+
+
+@dataclass
+class TemplateInfo:
+    slug: str
+    langs: list[str]
+    default_lang: str
+    variables: list[str]
+
+    @classmethod
+    def from_api(cls, data: dict[str, Any]) -> "TemplateInfo":
+        langs = data.get("langs") if isinstance(data.get("langs"), list) else []
+        variables = data.get("variables") if isinstance(data.get("variables"), list) else []
+        return cls(
+            slug=str(data.get("slug") or ""),
+            langs=[str(x) for x in langs],
+            default_lang=str(data.get("defaultLang") or ""),
+            variables=[str(x) for x in variables],
+        )

zindua_sdk-1.0.0/src/zindua/validate.py

@@ -0,0 +1,244 @@
+from __future__ import annotations
+
+import os
+import re
+from typing import Any, Literal
+from urllib.parse import urlparse
+
+from zindua.errors import ZinduaError
+
+SendChannel = Literal["email", "whatsapp"]
+
+E164_RE = re.compile(r"^\+[1-9]\d{6,14}$")
+EMAIL_RE = re.compile(r"^[^\s@]+@[^\s@]+\.[^\s@]+$")
+TEMPLATE_SLUG_RE = re.compile(r"^[a-z0-9][a-z0-9_-]{0,62}$", re.I)
+LANG_RE = re.compile(r"^[a-z]{2}(-[a-z]{2})?$", re.I)
+API_KEY_RE = re.compile(r"^znd_(live|test)_[a-z0-9]{24}$")
+
+DEFAULT_API_BASE = "https://zindua.run/api/v1"
+DEFAULT_TIMEOUT_S = 30.0
+MAX_TIMEOUT_S = 120.0
+MAX_TO_LENGTH = 320
+MAX_TEMPLATE_LENGTH = 64
+MAX_VARIABLES = 50
+MAX_VAR_KEY_LENGTH = 64
+MAX_VAR_VALUE_LENGTH = 4096
+MAX_ATTACHMENTS = 5
+
+BLOCKED_VAR_KEYS = {"__proto__", "constructor", "prototype"}
+
+
+def validate_api_key(api_key: str) -> str:
+    key = api_key.strip()
+    if not key:
+        raise ZinduaError("apiKey is required.", status=0, code="INVALID_API_KEY")
+    if not API_KEY_RE.match(key):
+        raise ZinduaError(
+            "apiKey must be znd_live_… or znd_test_… (project key from Dashboard → Projects).",
+            status=0,
+            code="INVALID_API_KEY",
+        )
+    return key
+
+
+def validate_base_url(raw: str) -> str:
+    trimmed = raw.strip().rstrip("/")
+    parsed = urlparse(trimmed)
+    if not parsed.scheme or not parsed.netloc:
+        raise ZinduaError("baseUrl is not a valid URL.", status=0, code="INVALID_BASE_URL")
+    if parsed.username or parsed.password:
+        raise ZinduaError("baseUrl must not contain credentials.", status=0, code="INVALID_BASE_URL")
+
+    host = (parsed.hostname or "").lower()
+    is_local = host in {"localhost", "127.0.0.1", "[::1]"} or host.endswith(".localhost")
+    if parsed.scheme != "https" and not (is_local and parsed.scheme == "http"):
+        raise ZinduaError(
+            "baseUrl must use HTTPS (HTTP is only allowed for localhost).",
+            status=0,
+            code="INVALID_BASE_URL",
+        )
+    return trimmed
+
+
+def resolve_base_url(explicit: str | None = None) -> str:
+    if explicit and explicit.strip():
+        return validate_base_url(explicit)
+    from_env = os.environ.get("ZINDUA_API_BASE_URL", "").strip()
+    if from_env:
+        return validate_base_url(from_env)
+    return DEFAULT_API_BASE
+
+
+def validate_timeout(timeout_s: float | None) -> float:
+    if timeout_s is None:
+        return DEFAULT_TIMEOUT_S
+    if timeout_s < 1.0 or timeout_s > MAX_TIMEOUT_S:
+        raise ZinduaError(
+            f"timeout must be between 1 and {MAX_TIMEOUT_S} seconds.",
+            status=0,
+            code="INVALID_OPTIONS",
+        )
+    return float(timeout_s)
+
+
+def validate_channel(channel: str | None) -> SendChannel:
+    if channel is None or channel == "" or channel == "email":
+        return "email"
+    if channel == "whatsapp":
+        return "whatsapp"
+    raise ZinduaError('channel must be "email" or "whatsapp".', status=0, code="INVALID_CHANNEL")
+
+
+def validate_template_slug(template: str) -> str:
+    slug = template.strip()
+    if not slug or len(slug) > MAX_TEMPLATE_LENGTH:
+        raise ZinduaError("template slug is required (max 64 characters).", status=0, code="INVALID_TEMPLATE")
+    if not TEMPLATE_SLUG_RE.match(slug):
+        raise ZinduaError(
+            "template slug may only contain letters, numbers, hyphens, and underscores.",
+            status=0,
+            code="INVALID_TEMPLATE",
+        )
+    return slug
+
+
+def validate_recipient(to: str, channel: SendChannel) -> str:
+    recipient = to.strip()
+    if not recipient or len(recipient) > MAX_TO_LENGTH:
+        raise ZinduaError("to is required.", status=0, code="MISSING_FIELDS")
+    if channel == "email":
+        if not EMAIL_RE.match(recipient):
+            raise ZinduaError(
+                "Invalid email address, or phone used with channel email.",
+                status=0,
+                code="INVALID_EMAIL",
+            )
+        return recipient
+    if not E164_RE.match(recipient):
+        raise ZinduaError(
+            "Invalid WhatsApp phone (E.164 with +), or email used with channel whatsapp.",
+            status=0,
+            code="INVALID_PHONE",
+        )
+    return recipient
+
+
+def validate_lang(lang: str | None) -> str | None:
+    if lang is None or lang == "":
+        return None
+    value = lang.strip()
+    if len(value) > 10 or not LANG_RE.match(value):
+        raise ZinduaError("lang must be ISO 639-1 (e.g. fr, en, en-us).", status=0, code="INVALID_LANG")
+    return value
+
+
+def sanitize_variables(variables: dict[str, str] | None) -> dict[str, str] | None:
+    if not variables:
+        return None
+    out: dict[str, str] = {}
+    count = 0
+    for key, value in variables.items():
+        if count >= MAX_VARIABLES:
+            break
+        if key in BLOCKED_VAR_KEYS:
+            continue
+        if not isinstance(value, str):
+            value = str(value)
+        safe_key = key.strip()[:MAX_VAR_KEY_LENGTH]
+        if not safe_key:
+            continue
+        out[safe_key] = value[:MAX_VAR_VALUE_LENGTH]
+        count += 1
+    return out or None
+
+
+def validate_optional_email_field(field: str, value: str | None) -> str | None:
+    if value is None or value == "":
+        return None
+    trimmed = value.strip()
+    if not EMAIL_RE.match(trimmed):
+        raise ZinduaError(f"Invalid {field} email address.", status=0, code="INVALID_OPTIONS")
+    return trimmed
+
+
+def validate_attachments(attachments: list[dict[str, str]] | None) -> list[dict[str, str]] | None:
+    if not attachments:
+        return None
+    if len(attachments) > MAX_ATTACHMENTS:
+        raise ZinduaError(f"At most {MAX_ATTACHMENTS} attachments allowed.", status=0, code="INVALID_OPTIONS")
+    out: list[dict[str, str]] = []
+    for item in attachments:
+        if not isinstance(item, dict):
+            raise ZinduaError("Each attachment must be an object with url.", status=0, code="INVALID_OPTIONS")
+        url = item.get("url")
+        if not isinstance(url, str) or not url.strip():
+            raise ZinduaError("Attachment url is required.", status=0, code="INVALID_OPTIONS")
+        parsed = urlparse(url.strip())
+        if parsed.scheme != "https":
+            raise ZinduaError("Attachment urls must use HTTPS.", status=0, code="INVALID_OPTIONS")
+        entry: dict[str, str] = {"url": url.strip()}
+        filename = item.get("filename")
+        if isinstance(filename, str) and filename.strip():
+            entry["filename"] = filename.strip()
+        out.append(entry)
+    return out
+
+
+def validate_site_url(site_url: str | None) -> str | None:
+    if site_url is None or site_url == "":
+        return None
+    trimmed = site_url.strip()
+    if not trimmed:
+        return None
+    candidate = trimmed if "://" in trimmed else f"https://{trimmed}"
+    parsed = urlparse(candidate)
+    if not parsed.scheme or not parsed.netloc:
+        raise ZinduaError("siteUrl must be a valid URL (e.g. https://example.com).", status=0, code="INVALID_OPTIONS")
+    return f"{parsed.scheme}://{parsed.netloc}"
+
+
+def build_send_payload(
+    *,
+    to: str,
+    template: str,
+    channel: SendChannel | None = None,
+    lang: str | None = None,
+    variables: dict[str, str] | None = None,
+    cc: str | None = None,
+    bcc: str | None = None,
+    reply_to: str | None = None,
+    attachments: list[dict[str, str]] | None = None,
+) -> dict[str, Any]:
+    resolved_channel = validate_channel(channel)
+    payload: dict[str, Any] = {
+        "to": validate_recipient(to, resolved_channel),
+        "template": validate_template_slug(template),
+    }
+    if resolved_channel == "whatsapp":
+        payload["channel"] = "whatsapp"
+    elif channel == "email":
+        payload["channel"] = "email"
+
+    validated_lang = validate_lang(lang)
+    if validated_lang:
+        payload["lang"] = validated_lang
+
+    vars_out = sanitize_variables(variables)
+    if vars_out:
+        payload["variables"] = vars_out
+
+    if resolved_channel == "email":
+        cc_v = validate_optional_email_field("cc", cc)
+        bcc_v = validate_optional_email_field("bcc", bcc)
+        reply_v = validate_optional_email_field("replyTo", reply_to)
+        att_v = validate_attachments(attachments)
+        if cc_v:
+            payload["cc"] = cc_v
+        if bcc_v:
+            payload["bcc"] = bcc_v
+        if reply_v:
+            payload["replyTo"] = reply_v
+        if att_v:
+            payload["attachments"] = att_v
+
+    return payload

zindua_sdk-1.0.0/tests/test_validate.py

@@ -0,0 +1,47 @@
+import pytest
+
+from zindua.errors import ZinduaError
+from zindua.validate import (
+    build_send_payload,
+    validate_api_key,
+    validate_recipient,
+)
+
+
+def test_validate_api_key_accepts_test_key():
+    key = "znd_test_" + "a" * 24
+    assert validate_api_key(key) == key
+
+
+def test_validate_api_key_rejects_bad_prefix():
+    with pytest.raises(ZinduaError) as exc:
+        validate_api_key("sk_live_bad")
+    assert exc.value.code == "INVALID_API_KEY"
+
+
+def test_channel_to_mismatch_email():
+    with pytest.raises(ZinduaError) as exc:
+        validate_recipient("+243812345678", "email")
+    assert exc.value.code == "INVALID_EMAIL"
+
+
+def test_build_send_payload_with_lang_and_attachments():
+    payload = build_send_payload(
+        to="user@example.com",
+        template="invoice-ready",
+        lang="fr",
+        variables={"code": "1"},
+        attachments=[{"url": "https://cdn.example.com/file.pdf", "filename": "invoice.pdf"}],
+    )
+    assert payload["lang"] == "fr"
+    assert payload["attachments"][0]["url"].startswith("https://")
+
+
+def test_attachments_require_https():
+    with pytest.raises(ZinduaError) as exc:
+        build_send_payload(
+            to="user@example.com",
+            template="t",
+            attachments=[{"url": "http://insecure.example.com/a.pdf"}],
+        )
+    assert exc.value.code == "INVALID_OPTIONS"