rmyndharis-openwa 0.1.0__tar.gz

rmyndharis_openwa-0.1.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: rmyndharis-openwa
+Version: 0.1.0
+Summary: Official Python SDK for OpenWA WhatsApp API Gateway
+Author: OpenWA Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/rmyndharis/OpenWA
+Project-URL: Repository, https://github.com/rmyndharis/OpenWA
+Keywords: whatsapp,api,sdk,openwa,gateway
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1.0,>=0.25.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+
+# rmyndharis-openwa
+
+Official Python SDK for the [OpenWA](https://github.com/rmyndharis/OpenWA) WhatsApp API Gateway.
+
+A synchronous client built on [httpx](https://www.python-httpx.org/), with bundled type hints (PEP 561).
+
+## Install
+
+> **Not yet published to PyPI.** Until the first release, install from a checkout
+> of the repo (`cd sdk/python && pip install -e .`) or from git.
+
+```bash
+pip install rmyndharis-openwa   # once published
+```
+
+Requires Python 3.9+. The importable module is `openwa`.
+
+## Usage
+
+```python
+from openwa import OpenWAClient
+
+client = OpenWAClient(
+    base_url="https://your-gateway.example.com",
+    api_key="owa_k1_…",
+)
+
+client.sessions.start("my-session")
+
+result = client.messages.send_text("my-session", {
+    "chatId": "628123456789@c.us",
+    "text": "Hello from the OpenWA Python SDK!",
+})
+print(result["messageId"])
+```
+
+The client is also a context manager (it closes the underlying connection pool on exit):
+
+```python
+with OpenWAClient(base_url="…", api_key="…") as client:
+    client.messages.send_text("my-session", {"chatId": "…@c.us", "text": "hi"})
+```
+
+For tests, pass an httpx transport — no global monkey-patching required:
+
+```python
+import httpx
+client = OpenWAClient(base_url="…", api_key="…", transport=httpx.MockTransport(handler))
+```
+
+## Errors
+
+A non-2xx response raises a typed `OpenWAApiError` subclass — `OpenWAAuthError` (401),
+`OpenWAForbiddenError` (403), `OpenWANotFoundError` (404), `OpenWAConflictError` (409),
+`OpenWARateLimitError` (429), `OpenWANotImplementedError` (501) — each carrying `.status`
+and the parsed `.body`. A timeout raises `OpenWATimeoutError`.
+
+```python
+from openwa import OpenWANotFoundError
+
+try:
+    client.sessions.get("missing")
+except OpenWANotFoundError as e:
+    print(e.status)  # 404
+```
+
+## Notes
+
+- **Use HTTPS in production** — the API key is sent as `X-API-Key` and is bearer-equivalent.
+- The SDK does **not** retry, and **never follows redirects** (so the key is never re-sent to
+  a redirect target). Path segments are percent-encoded; a base-URL path prefix (e.g. behind a
+  reverse proxy) is preserved.
+- Escape hatch for endpoints the SDK does not wrap:
+  `client.request(method, path, query=…, body=…)`.
+
+## License
+
+MIT

rmyndharis_openwa-0.1.0/README.md

@@ -0,0 +1,78 @@
+# rmyndharis-openwa
+
+Official Python SDK for the [OpenWA](https://github.com/rmyndharis/OpenWA) WhatsApp API Gateway.
+
+A synchronous client built on [httpx](https://www.python-httpx.org/), with bundled type hints (PEP 561).
+
+## Install
+
+> **Not yet published to PyPI.** Until the first release, install from a checkout
+> of the repo (`cd sdk/python && pip install -e .`) or from git.
+
+```bash
+pip install rmyndharis-openwa   # once published
+```
+
+Requires Python 3.9+. The importable module is `openwa`.
+
+## Usage
+
+```python
+from openwa import OpenWAClient
+
+client = OpenWAClient(
+    base_url="https://your-gateway.example.com",
+    api_key="owa_k1_…",
+)
+
+client.sessions.start("my-session")
+
+result = client.messages.send_text("my-session", {
+    "chatId": "628123456789@c.us",
+    "text": "Hello from the OpenWA Python SDK!",
+})
+print(result["messageId"])
+```
+
+The client is also a context manager (it closes the underlying connection pool on exit):
+
+```python
+with OpenWAClient(base_url="…", api_key="…") as client:
+    client.messages.send_text("my-session", {"chatId": "…@c.us", "text": "hi"})
+```
+
+For tests, pass an httpx transport — no global monkey-patching required:
+
+```python
+import httpx
+client = OpenWAClient(base_url="…", api_key="…", transport=httpx.MockTransport(handler))
+```
+
+## Errors
+
+A non-2xx response raises a typed `OpenWAApiError` subclass — `OpenWAAuthError` (401),
+`OpenWAForbiddenError` (403), `OpenWANotFoundError` (404), `OpenWAConflictError` (409),
+`OpenWARateLimitError` (429), `OpenWANotImplementedError` (501) — each carrying `.status`
+and the parsed `.body`. A timeout raises `OpenWATimeoutError`.
+
+```python
+from openwa import OpenWANotFoundError
+
+try:
+    client.sessions.get("missing")
+except OpenWANotFoundError as e:
+    print(e.status)  # 404
+```
+
+## Notes
+
+- **Use HTTPS in production** — the API key is sent as `X-API-Key` and is bearer-equivalent.
+- The SDK does **not** retry, and **never follows redirects** (so the key is never re-sent to
+  a redirect target). Path segments are percent-encoded; a base-URL path prefix (e.g. behind a
+  reverse proxy) is preserved.
+- Escape hatch for endpoints the SDK does not wrap:
+  `client.request(method, path, query=…, body=…)`.
+
+## License
+
+MIT

rmyndharis_openwa-0.1.0/openwa/__init__.py

@@ -0,0 +1,49 @@
+"""
+OpenWA Python SDK.
+
+Official client library for the OpenWA WhatsApp API Gateway.
+
+Example usage::
+
+    from openwa import OpenWAClient
+
+    client = OpenWAClient(
+        base_url="http://localhost:2785",
+        api_key="owa_k1_…",
+    )
+
+    client.sessions.start("my-session")
+    result = client.messages.send_text("my-session", {
+        "chatId": "628123456789@c.us",
+        "text": "Hello from the OpenWA Python SDK!",
+    })
+    print(result["messageId"])
+"""
+
+from __future__ import annotations
+
+from .client import OpenWAClient
+from .errors import (
+    OpenWAApiError,
+    OpenWAAuthError,
+    OpenWAConflictError,
+    OpenWAError,
+    OpenWAForbiddenError,
+    OpenWANotFoundError,
+    OpenWANotImplementedError,
+    OpenWARateLimitError,
+    OpenWATimeoutError,
+)
+
+__all__ = [
+    "OpenWAClient",
+    "OpenWAError",
+    "OpenWAApiError",
+    "OpenWAAuthError",
+    "OpenWAForbiddenError",
+    "OpenWANotFoundError",
+    "OpenWAConflictError",
+    "OpenWARateLimitError",
+    "OpenWANotImplementedError",
+    "OpenWATimeoutError",
+]

rmyndharis_openwa-0.1.0/openwa/_http.py

@@ -0,0 +1,115 @@
+"""HTTP transport wrapper for the OpenWA Python SDK.
+
+The client never builds a bare :class:`httpx.Client` with a hard-coded
+transport. Instead it accepts an optional ``transport`` (an ``httpx.BaseTransport``)
+that overrides the default. This makes the SDK trivially testable — a test
+passes ``httpx.MockTransport(handler)`` instead of monkey-patching — and lets
+consumers intercept/observability-wrap outbound calls.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+from urllib.parse import quote
+
+import httpx
+
+from .errors import OpenWAApiError, OpenWATimeoutError, classify
+
+HttpMethod = str  # "GET" | "POST" | "PUT" | "PATCH" | "DELETE"
+
+
+def quote_segment(segment: Any) -> str:
+    """Percent-encode a single path segment so a value containing ``/``, ``#`` or
+    ``?`` can't break out of its path position. WhatsApp-id characters that are
+    already path-safe (``@``, ``:``, ``+``) are kept readable.
+    """
+    return quote(str(segment), safe="@:+")
+
+
+def build_url(base_url: str, path: str, query: Mapping[str, Any] | None = None) -> str:
+    """Build a URL, serializing query params and skipping ``None`` values."""
+    url = f"{base_url.rstrip('/')}{path}"
+    if not query:
+        return url
+
+    def _serialize(v: Any) -> str:
+        # Booleans must be lowercase: the backend reads query flags as `=== 'true'`,
+        # so Python's default str(True) == 'True' would be silently ignored.
+        if v is True:
+            return "true"
+        if v is False:
+            return "false"
+        return str(v)
+
+    params = {k: _serialize(v) for k, v in query.items() if v is not None}
+    if not params:
+        return url
+    req = httpx.Request("GET", url, params=params)
+    # httpx.Request already encoded params into the URL string.
+    return str(req.url)
+
+
+class HttpExecutor:
+    """Owns the :class:`httpx.Client` and performs JSON requests.
+
+    Constructed once per :class:`OpenWAClient`; the transport is taken from
+    the client config so all requests share one connection pool.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        timeout: float = 30.0,
+        default_headers: Mapping[str, str] | None = None,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        # Caller-supplied default headers are applied FIRST so the auth/JSON
+        # headers below always win and can never be clobbered (mirrors the JS SDK).
+        headers: dict[str, str] = {}
+        if default_headers:
+            headers.update(default_headers)
+        headers["Content-Type"] = "application/json"
+        headers["X-API-Key"] = api_key
+        client_kwargs: dict[str, Any] = {
+            "base_url": base_url.rstrip("/"),
+            "headers": headers,
+            "timeout": timeout,
+            # Never auto-follow redirects: doing so would re-send the X-API-Key
+            # header to the redirect target (potentially a different origin).
+            # (This is also httpx's default; set explicitly so it can't regress.)
+            "follow_redirects": False,
+        }
+        if transport is not None:
+            client_kwargs["transport"] = transport
+        self._client = httpx.Client(**client_kwargs)
+        self._timeout = timeout
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "HttpExecutor":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def request(self, method: HttpMethod, path: str, *, query: Mapping[str, Any] | None = None, body: Any = None) -> Any:
+        """Perform one request and return the parsed JSON (or ``None`` for 204)."""
+        url = build_url("", path, query)
+        try:
+            res = self._client.request(method, url, json=body if body is not None else None)
+        except httpx.TimeoutException as e:
+            raise OpenWATimeoutError(self._timeout) from e
+        if res.status_code >= 400:
+            context = f"{method} {path}"
+            raise OpenWAApiError.from_response(res.status_code, res.text, context)
+        if res.status_code == 204 or not res.content:
+            return None
+        try:
+            return res.json()
+        except ValueError:
+            # A 2xx body that isn't JSON surfaces as text rather than a raw
+            # JSONDecodeError (mirrors the JS and PHP transports).
+            return res.text

rmyndharis_openwa-0.1.0/openwa/client.py

@@ -0,0 +1,148 @@
+"""OpenWA Python SDK — client core.
+
+The :class:`OpenWAClient` is the single entry point. It owns an
+:class:`HttpExecutor` (which wraps :class:`httpx.Client` with an injectable
+transport) and exposes domain resources as properties::
+
+    from openwa import OpenWAClient
+
+    client = OpenWAClient(
+        base_url="http://localhost:2785",
+        api_key="owa_k1_…",
+    )
+
+    client.sessions.start("my-session")
+    client.messages.send_text("my-session", {
+        "chatId": "628123456789@c.us",
+        "text": "Hello from the OpenWA SDK!",
+    })
+
+Pass ``transport=httpx.MockTransport(handler)`` for testability — no global
+monkey-patching required.
+"""
+
+from __future__ import annotations
+
+from types import TracebackType
+from typing import Any, Mapping
+
+import httpx
+
+from ._http import HttpExecutor, HttpMethod
+from .resources import (
+    CatalogResource,
+    ChannelsResource,
+    ChatsResource,
+    ContactsResource,
+    GroupsResource,
+    HealthResource,
+    LabelsResource,
+    MessagesResource,
+    SessionsResource,
+    StatusResource,
+    TemplatesResource,
+    WebhooksResource,
+)
+from .types import AuthValidateResponse
+
+
+class OpenWAClient:
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        *,
+        timeout: float = 30.0,
+        default_headers: Mapping[str, str] | None = None,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        if not base_url:
+            raise ValueError("OpenWAClient: base_url is required")
+        if not api_key:
+            raise ValueError("OpenWAClient: api_key is required")
+        self._http = HttpExecutor(
+            base_url=base_url,
+            api_key=api_key,
+            timeout=timeout,
+            default_headers=default_headers,
+            transport=transport,
+        )
+
+    # ── Resources ────────────────────────────────────────────────────
+
+    @property
+    def sessions(self) -> SessionsResource:
+        return SessionsResource(self._http)
+
+    @property
+    def messages(self) -> MessagesResource:
+        return MessagesResource(self._http)
+
+    @property
+    def contacts(self) -> ContactsResource:
+        return ContactsResource(self._http)
+
+    @property
+    def groups(self) -> GroupsResource:
+        return GroupsResource(self._http)
+
+    @property
+    def webhooks(self) -> WebhooksResource:
+        return WebhooksResource(self._http)
+
+    @property
+    def chats(self) -> ChatsResource:
+        return ChatsResource(self._http)
+
+    @property
+    def status(self) -> StatusResource:
+        return StatusResource(self._http)
+
+    @property
+    def health(self) -> HealthResource:
+        return HealthResource(self._http)
+
+    @property
+    def labels(self) -> LabelsResource:
+        return LabelsResource(self._http)
+
+    @property
+    def channels(self) -> ChannelsResource:
+        return ChannelsResource(self._http)
+
+    @property
+    def catalog(self) -> CatalogResource:
+        return CatalogResource(self._http)
+
+    @property
+    def templates(self) -> TemplatesResource:
+        return TemplatesResource(self._http)
+
+    # ── Auth ─────────────────────────────────────────────────────────
+
+    def auth(self) -> AuthValidateResponse:
+        return self._http.request("POST", "/api/auth/validate")
+
+    # ── Raw request escape hatch ─────────────────────────────────────
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        query: Mapping[str, Any] | None = None,
+        body: Any = None,
+    ) -> Any:
+        """Issue a raw request against the API (advanced use). ``path`` begins with ``/``."""
+        return self._http.request(method, path, query=query, body=body)
+
+    # ── Lifecycle ────────────────────────────────────────────────────
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "OpenWAClient":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()

rmyndharis_openwa-0.1.0/openwa/errors.py

@@ -0,0 +1,99 @@
+"""Typed error hierarchy for the OpenWA Python SDK.
+
+The OpenWA API returns NestJS-default errors of the shape::
+
+    {"statusCode": int, "message": str | list[str], "error": str}
+
+This module maps that to a typed, ergonomic error tree so callers can
+``isinstance``-check or branch on ``.status``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class OpenWAError(Exception):
+    """Base class for every error raised by the SDK."""
+
+
+class OpenWAApiError(OpenWAError):
+    """Raised when the API responds with a non-2xx status.
+
+    Attributes:
+        status: HTTP status code.
+        body: Parsed JSON body if available, otherwise the raw text.
+        error_kind: Value of the ``error`` field in the NestJS envelope.
+    """
+
+    def __init__(self, message: str, status: int, body: Any = None, error_kind: str | None = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.body = body
+        self.error_kind = error_kind
+
+    @classmethod
+    def from_response(cls, status_code: int, text: str, context: str) -> "OpenWAApiError":
+        import json
+
+        body: Any = None
+        if text:
+            try:
+                body = json.loads(text)
+            except ValueError:
+                body = text
+        envelope = body if isinstance(body, dict) and "statusCode" in body else None
+        raw_message = envelope.get("message") if envelope else body
+        if isinstance(raw_message, list):
+            message_text = ", ".join(str(m) for m in raw_message)
+        elif isinstance(raw_message, str):
+            message_text = raw_message
+        else:
+            message_text = str(raw_message)
+        message = f"OpenWA API {status_code} — {context}: {message_text}"
+        return classify(status_code, message, body, envelope.get("error") if envelope else None)
+
+
+class OpenWAAuthError(OpenWAApiError):
+    """401 Unauthorized — missing or invalid API key."""
+
+
+class OpenWAForbiddenError(OpenWAApiError):
+    """403 Forbidden — insufficient role."""
+
+
+class OpenWANotFoundError(OpenWAApiError):
+    """404 Not Found."""
+
+
+class OpenWAConflictError(OpenWAApiError):
+    """409 Conflict — typically an engine-not-ready condition."""
+
+
+class OpenWARateLimitError(OpenWAApiError):
+    """429 Too Many Requests."""
+
+
+class OpenWANotImplementedError(OpenWAApiError):
+    """501 Not Implemented — the active engine does not support this operation."""
+
+
+class OpenWATimeoutError(OpenWAError):
+    """Raised when a request exceeds the configured timeout."""
+
+    def __init__(self, timeout: float) -> None:
+        super().__init__(f"Request timed out after {timeout}s")
+        self.timeout = timeout
+
+
+def classify(status: int, message: str, body: Any, error_kind: str | None) -> OpenWAApiError:
+    """Pick the most specific :class:`OpenWAApiError` subclass for a status."""
+    cls = {
+        401: OpenWAAuthError,
+        403: OpenWAForbiddenError,
+        404: OpenWANotFoundError,
+        409: OpenWAConflictError,
+        429: OpenWARateLimitError,
+        501: OpenWANotImplementedError,
+    }.get(status, OpenWAApiError)
+    return cls(message, status, body, error_kind)

rmyndharis_openwa-0.1.0/openwa/resources/__init__.py

@@ -0,0 +1,35 @@
+"""Resource modules for the OpenWA Python SDK.
+
+Each module defines a small ``_*Resource`` class whose methods map 1:1 to an
+API path group. They are constructed by :class:`openwa.client.OpenWAClient`.
+"""
+
+from __future__ import annotations
+
+from .catalog import CatalogResource
+from .channels import ChannelsResource
+from .chats import ChatsResource
+from .contacts import ContactsResource
+from .groups import GroupsResource
+from .health import HealthResource
+from .labels import LabelsResource
+from .messages import MessagesResource
+from .sessions import SessionsResource
+from .status import StatusResource
+from .templates import TemplatesResource
+from .webhooks import WebhooksResource
+
+__all__ = [
+    "CatalogResource",
+    "ChannelsResource",
+    "ChatsResource",
+    "ContactsResource",
+    "GroupsResource",
+    "HealthResource",
+    "LabelsResource",
+    "MessagesResource",
+    "SessionsResource",
+    "StatusResource",
+    "TemplatesResource",
+    "WebhooksResource",
+]

rmyndharis_openwa-0.1.0/openwa/resources/catalog.py

@@ -0,0 +1,58 @@
+"""Catalog resource — WhatsApp Business catalog, products, and product/catalog sends.
+
+Backed by ``src/modules/catalog/catalog.controller.ts``
+(``@Controller('sessions/:sessionId')``). NOTE: the catalog controller is
+mounted under the session root, so catalog reads are ``/catalog...`` while
+product/catalog SENDS share the messages namespace
+(``/messages/send-product``, ``/messages/send-catalog``).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .._http import quote_segment
+from ..types import (
+    CatalogInfo,
+    CatalogProduct,
+    CatalogProductsQuery,
+    MessageResponse,
+    PaginatedProducts,
+    SendCatalogRequest,
+    SendProductRequest,
+)
+
+if TYPE_CHECKING:
+    from .._http import HttpExecutor
+
+
+class CatalogResource:
+    def __init__(self, http: "HttpExecutor") -> None:
+        self._http = http
+
+    def info(self, session_id: str) -> CatalogInfo:
+        return self._http.request("GET", f"/api/sessions/{quote_segment(session_id)}/catalog")
+
+    def products(
+        self, session_id: str, query: CatalogProductsQuery | None = None
+    ) -> PaginatedProducts:
+        return self._http.request(
+            "GET", f"/api/sessions/{quote_segment(session_id)}/catalog/products", query=query
+        )
+
+    def product(self, session_id: str, product_id: str) -> CatalogProduct:
+        return self._http.request(
+            "GET", f"/api/sessions/{quote_segment(session_id)}/catalog/products/{quote_segment(product_id)}"
+        )
+
+    def send_product(self, session_id: str, body: SendProductRequest) -> MessageResponse:
+        """Send a product message. Requires an OPERATOR-level key. Shares the messages path."""
+        return self._http.request(
+            "POST", f"/api/sessions/{quote_segment(session_id)}/messages/send-product", body=body
+        )
+
+    def send_catalog(self, session_id: str, body: SendCatalogRequest) -> MessageResponse:
+        """Send a catalog link message. Requires an OPERATOR-level key. Shares the messages path."""
+        return self._http.request(
+            "POST", f"/api/sessions/{quote_segment(session_id)}/messages/send-catalog", body=body
+        )