waapi 0.1.0__py3-none-any.whl

waapi/_http.py

@@ -0,0 +1,97 @@
+"""HTTP transport and error mapping.
+
+Both the sync and the async client route every call through :func:`interpret`,
+so the two cannot drift apart on what counts as a failure.
+"""
+
+from __future__ import annotations
+
+import json as _json
+from collections.abc import Mapping
+from typing import Any
+
+import httpx
+
+from .exceptions import (
+    AuthenticationError,
+    FailedActionError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+    WaAPIError,
+)
+
+DEFAULT_BASE_URL = "https://waapi.app/api/v1"
+DEFAULT_TIMEOUT = 30.0
+
+
+def build_headers(token: str, user_agent: str) -> dict[str, str]:
+    return {
+        "authorization": f"Bearer {token}",
+        "accept": "application/json",
+        "content-type": "application/json",
+        "user-agent": user_agent,
+    }
+
+
+def _decode(response: httpx.Response) -> Any:
+    try:
+        return response.json()
+    except (ValueError, _json.JSONDecodeError):
+        return response.text
+
+
+def interpret(response: httpx.Response, *, check_body_status: bool = True) -> Any:
+    """Turn a response into a payload, or raise the matching exception.
+
+    ``check_body_status`` exists because a few endpoints answer without the
+    envelope. Leave it on unless you know the endpoint is one of them: turning
+    it off is what makes a failed send look like a successful one.
+    """
+    body = _decode(response)
+    status = response.status_code
+
+    if status == 401 or status == 403:
+        raise AuthenticationError(
+            f"WaAPI rejected the API token (HTTP {status}): {_brief(body)}"
+        )
+    if status == 404:
+        raise NotFoundError()
+    if status == 422:
+        raise ValidationError(body)
+    if status == 429:
+        retry_after = response.headers.get("retry-after")
+        raise RateLimitError(
+            f"Rate limited by WaAPI (HTTP 429): {_brief(body)}",
+            retry_after=float(retry_after) if retry_after else None,
+        )
+    if status == 400:
+        raise FailedActionError(f"WaAPI rejected the request: {_brief(body)}", body)
+    if 500 <= status < 600:
+        raise ServerError(f"WaAPI returned HTTP {status}: {_brief(body)}")
+    if not 200 <= status < 300:
+        raise WaAPIError(f"WaAPI returned HTTP {status}: {_brief(body)}")
+
+    # A 2xx is not proof the action happened. The API answers 200 with
+    # {"status": "error"} when, for example, the instance is not connected.
+    if check_body_status and isinstance(body, Mapping):
+        envelope = body.get("status")
+        if envelope is not None and envelope != "success":
+            raise FailedActionError(
+                "WaAPI accepted the request but did not carry the action out: "
+                + _brief(body),
+                body,
+            )
+
+    return body
+
+
+def _brief(body: Any, limit: int = 400) -> str:
+    text = body if isinstance(body, str) else _json.dumps(body, ensure_ascii=False)
+    return text if len(text) <= limit else text[:limit] + "..."
+
+
+def prune(payload: Mapping[str, Any]) -> dict[str, Any]:
+    """Drop keys whose value is None so optional parameters stay optional."""
+    return {k: v for k, v in payload.items() if v is not None}

waapi/client.py

@@ -0,0 +1,118 @@
+"""Synchronous and asynchronous WaAPI clients."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from . import __version__
+from ._actions import ActionsMixin, AsyncActionsMixin
+from ._http import DEFAULT_BASE_URL, DEFAULT_TIMEOUT, build_headers, interpret
+
+_USER_AGENT = f"waapi-python-sdk/{__version__}"
+
+
+class _Base:
+    def __init__(
+        self,
+        token: str,
+        *,
+        instance_id: int | str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ) -> None:
+        if not token:
+            raise ValueError("an API token is required — create one at https://waapi.app/user/api-tokens")
+        self.token = token
+        self.instance_id = instance_id
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def _resolve_instance(self, instance_id: int | str | None) -> int | str:
+        """Fall back to the client-wide instance so single-instance code stays short."""
+        resolved = instance_id if instance_id is not None else self.instance_id
+        if resolved is None:
+            raise ValueError(
+                "no instance id given and none configured on the client — "
+                "pass instance_id=... to the call or to WaAPI(...)"
+            )
+        return resolved
+
+
+class WaAPI(_Base, ActionsMixin):
+    """Blocking client.
+
+    >>> client = WaAPI(token="...", instance_id=123)
+    >>> client.send_message(chat_id="4915112345678@c.us", message="Hello")
+    """
+
+    def __init__(self, token: str, **kwargs: Any) -> None:
+        transport = kwargs.pop("transport", None)
+        super().__init__(token, **kwargs)
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            headers=build_headers(self.token, _USER_AGENT),
+            timeout=self.timeout,
+            transport=transport,
+        )
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: Any = None,
+        check_body_status: bool = True,
+    ) -> Any:
+        response = self._client.request(method, path, json=json, params=params)
+        return interpret(response, check_body_status=check_body_status)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> WaAPI:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+class AsyncWaAPI(_Base, AsyncActionsMixin):
+    """Non-blocking client with the same method names as :class:`WaAPI`.
+
+    >>> async with AsyncWaAPI(token="...", instance_id=123) as client:
+    ...     await client.send_message(chat_id="4915112345678@c.us", message="Hi")
+    """
+
+    def __init__(self, token: str, **kwargs: Any) -> None:
+        transport = kwargs.pop("transport", None)
+        super().__init__(token, **kwargs)
+        self._client = httpx.AsyncClient(
+            base_url=self.base_url,
+            headers=build_headers(self.token, _USER_AGENT),
+            timeout=self.timeout,
+            transport=transport,
+        )
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: Any = None,
+        check_body_status: bool = True,
+    ) -> Any:
+        response = await self._client.request(method, path, json=json, params=params)
+        return interpret(response, check_body_status=check_body_status)
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncWaAPI:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()

waapi/exceptions.py

@@ -0,0 +1,60 @@
+"""Exceptions raised by the SDK.
+
+The hierarchy mirrors the PHP SDK so that the same API condition carries the
+same name in both: a 422 is a validation problem, a 404 is a missing resource,
+a 400 is a rejected action.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class WaAPIError(Exception):
+    """Base class for every error this SDK raises."""
+
+
+class ValidationError(WaAPIError):
+    """The request body failed the API's validation (HTTP 422)."""
+
+    def __init__(self, errors: Any) -> None:
+        super().__init__("The given data failed to pass validation.")
+        self.errors = errors
+
+
+class NotFoundError(WaAPIError):
+    """The addressed resource does not exist (HTTP 404)."""
+
+    def __init__(self, message: str = "The resource you are looking for could not be found.") -> None:
+        super().__init__(message)
+
+
+class AuthenticationError(WaAPIError):
+    """The API token is missing, wrong or lacks the required scope (HTTP 401/403)."""
+
+
+class RateLimitError(WaAPIError):
+    """Too many requests (HTTP 429)."""
+
+    def __init__(self, message: str, retry_after: float | None = None) -> None:
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
+class FailedActionError(WaAPIError):
+    """The API accepted the request but did not carry the action out.
+
+    This covers two cases that look different on the wire but mean the same
+    thing to a caller: an HTTP 400, and an HTTP 200 whose body says
+    ``{"status": "error"}``. The second is the dangerous one — it is a
+    successful HTTP exchange, so code that only checks the status code treats
+    a message that was never sent as delivered.
+    """
+
+    def __init__(self, message: str, response: Any = None) -> None:
+        super().__init__(message)
+        self.response = response
+
+
+class ServerError(WaAPIError):
+    """The API returned a 5xx."""

waapi-0.1.0.dist-info/METADATA

@@ -0,0 +1,185 @@
+Metadata-Version: 2.5
+Name: waapi
+Version: 0.1.0
+Summary: Official Python SDK for the WaAPI REST API
+Project-URL: Homepage, https://waapi.app
+Project-URL: Documentation, https://waapi.app/docs
+Project-URL: Source, https://github.com/WaAPIapp/waapi-python-sdk
+Project-URL: Issues, https://github.com/WaAPIapp/waapi-python-sdk/issues
+Author-email: WaAPI <info@waapi.app>
+License: The MIT License (MIT)
+        
+        Copyright (c) WaAPI <info@waapi.app>
+        
+        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.
+License-File: LICENSE
+Keywords: api,automation,chatbot,messaging,sdk,waapi
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1.0,>=0.24
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# WaAPI Python SDK
+
+Official Python client for the [WaAPI](https://waapi.app) REST API — send and
+receive WhatsApp messages, manage chats, groups and channels from Python.
+
+[![PyPI](https://img.shields.io/pypi/v/waapi?style=for-the-badge)](https://pypi.org/project/waapi/)
+[![Python](https://img.shields.io/pypi/pyversions/waapi?style=for-the-badge)](https://pypi.org/project/waapi/)
+[![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
+
+```bash
+pip install waapi
+```
+
+## Quick start
+
+```python
+from waapi import WaAPI
+
+client = WaAPI(token="YOUR_API_TOKEN", instance_id=123)
+
+client.send_message(
+    chat_id="4915112345678@c.us",
+    message="Deployment finished.",
+)
+```
+
+Get a token at [waapi.app/user/api-tokens](https://waapi.app/user/api-tokens)
+and create an instance connected to your number.
+
+### The chat ID is the one thing to get right
+
+Its suffix decides where the message lands, and a wrong suffix is accepted and
+delivers nothing:
+
+| Target | Format |
+|---|---|
+| One person | `4915112345678@c.us` |
+| Group | `123456789-123456789@g.us` |
+| Channel | `123456789@newsletter` |
+
+## Async
+
+Same method names, awaited:
+
+```python
+from waapi import AsyncWaAPI
+
+async with AsyncWaAPI(token="YOUR_API_TOKEN", instance_id=123) as client:
+    await client.send_message(chat_id="4915112345678@c.us", message="Hi")
+```
+
+## Errors
+
+A successful HTTP exchange is not proof the message was sent. The API answers
+`200` with `{"status": "error"}` when, for example, the instance is not
+connected — so the SDK raises on that too, rather than handing back a body that
+looks like success.
+
+```python
+from waapi import WaAPI, FailedActionError, AuthenticationError, RateLimitError
+
+try:
+    client.send_message(chat_id="4915112345678@c.us", message="Hi")
+except AuthenticationError:
+    ...                      # token wrong, expired, or missing scopes
+except RateLimitError as e:
+    time.sleep(e.retry_after or 5)
+except FailedActionError as e:
+    ...                      # accepted but not carried out — e.response has the detail
+```
+
+| Exception | Raised on |
+|---|---|
+| `AuthenticationError` | HTTP 401, 403 |
+| `NotFoundError` | HTTP 404 |
+| `ValidationError` | HTTP 422 — `.errors` holds the field errors |
+| `RateLimitError` | HTTP 429 — `.retry_after` in seconds when the API sends it |
+| `FailedActionError` | HTTP 400, **and HTTP 200 with `status: error`** |
+| `ServerError` | HTTP 5xx |
+
+All inherit from `WaAPIError`.
+
+## Coverage
+
+All **122 client actions** are wrapped, typed, and available on both clients:
+
+```python
+client.create_group(group_name="Ops", group_participants=["4915112345678@c.us"])
+client.send_media(chat_id="4915112345678@c.us", media_url="https://example.com/report.pdf")
+client.get_contacts()
+```
+
+They are generated from the same OpenAPI specification the n8n node and the MCP
+tools come from, so they track the API instead of drifting behind it — see
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+An action added to the API since the last release is still reachable by name:
+
+```python
+client.action("some-new-action", {"chatId": "4915112345678@c.us"})
+```
+
+## Configuration
+
+```python
+WaAPI(
+    token="...",              # required
+    instance_id=123,          # optional; per-call instance_id overrides it
+    base_url="https://waapi.app/api/v1",
+    timeout=30.0,
+)
+```
+
+Passing `instance_id` to the client keeps single-instance code short. Any call
+can still override it, and a call with neither raises before a request is sent.
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+The suite runs entirely against `httpx.MockTransport` — no network, no token,
+no connected account.
+
+## License
+
+MIT. Not affiliated with, endorsed or sponsored by WhatsApp LLC or Meta.
+WhatsApp is a trademark of WhatsApp LLC.

waapi-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+waapi/__init__.py,sha256=ZwQguHWIZ4yj5vRQF3Nl8djc8Dtf7Eg8wymJ4Q-jrwE,659
+waapi/_actions.py,sha256=0WnfpKGaK1mPrQ_ldlhTR90ypccITpKCmNqd7z1qRpI,5446
+waapi/_generated.py,sha256=Ge0dFy50kSw9y6aiPjrd698kVQu80nPwn1P4XoZqEzs,105033
+waapi/_http.py,sha256=LHTmpV7Imv7LbtqQ0phMKp0R0q01tct4_qbE6N7SSEI,3156
+waapi/client.py,sha256=U9YsxmMNCwzHuOXcwgkLSlhA7hxDNKaP9EUyg2jsnrM,3628
+waapi/exceptions.py,sha256=H979M-QskB-FAQISVAj1HeaETDOkcjxPkAv7Jyy62ws,1870
+waapi/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+waapi-0.1.0.dist-info/METADATA,sha256=ogxwxcM-hVfMhRlZxVpEBRtg9SQX3jrrvkGv_wnzaHo,6468
+waapi-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+waapi-0.1.0.dist-info/licenses/LICENSE,sha256=I_-EKdTBwwmElru8k9Gje8LTfCO4lG6OUJqk5zvne-c,1084
+waapi-0.1.0.dist-info/RECORD,,

waapi-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

waapi-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) WaAPI <info@waapi.app>
+
+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.