whatsarab 0.1.0__tar.gz

whatsarab-0.1.0/.gitignore

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

whatsarab-0.1.0/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: whatsarab
+Version: 0.1.0
+Summary: Official Python client for the WhatsArab API — WhatsApp messages, media, templates, OTP, and signed webhooks on the official Meta Cloud API.
+Project-URL: Homepage, https://whatsarab.com/docs
+Project-URL: Documentation, https://whatsarab.com/docs
+Project-URL: Source, https://github.com/efayek/whatsapp-api/tree/main/sdks/python
+Project-URL: Support, https://whatsarab.com/support
+Author: WhatsArab
+License: MIT
+Keywords: arabic,mena,messaging,meta-cloud-api,otp,whatsapp,whatsapp-business-api
+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: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# whatsarab
+
+Official Python client for the [WhatsArab](https://whatsarab.com) API — send WhatsApp messages on the official Meta Cloud API, upload media, manage templates, send and verify one-time codes, and verify signed webhooks.
+
+```bash
+pip install whatsarab
+```
+
+Python 3.9+.
+
+## Quick start
+
+```python
+import os
+from whatsarab import WhatsArab
+
+wa = WhatsArab(api_key=os.environ["WHATSARAB_API_KEY"])
+
+# Free-form text — only inside the 24-hour customer-service window
+wa.messages.send(to="201234567890", text="أهلًا يا سارة! طلبك رقم ١٠٤٢٨ خرج للتوصيل.")
+
+# An approved template — works any time
+wa.messages.send(
+    to="201234567890",
+    template="order_shipped",
+    language="ar",
+    components=[{"type": "body", "parameters": [{"type": "text", "text": "10428"}]}],
+)
+```
+
+Get an API key from **/app/integrations → API keys**. Keys are shown once, at creation.
+
+## What this covers
+
+The API-key surface, which is the eleven operations under `/api` in the [OpenAPI document](https://whatsarab.com/public/openapi.json):
+
+| | |
+|---|---|
+| `wa.messages.send()` | text · template · interactive · media |
+| `wa.media.upload()` / `.download()` | multipart up, raw bytes back |
+| `wa.templates.list() / .create() / .edit() / .delete()` | Meta template management |
+| `wa.otp.send()` / `.verify()` | one-time codes over WhatsApp |
+| `wa.events.list()` | recent webhook events |
+| `verify_webhook_signature()` | HMAC check for deliveries to you |
+
+**Not covered, deliberately:** contacts, the inbox and broadcasts are session-authenticated — they belong to a signed-in dashboard user, not to a server-side key — so there is no endpoint for this client to call. If that changes, it changes in the OpenAPI document first.
+
+## Sending
+
+Exactly one of `template`, `text`, `interactive` or `media` per call — checked locally, so a mistake is a `ValueError` on your machine rather than a 400 from production.
+
+```python
+# Media: upload once, then send by id
+with open("invoice.pdf", "rb") as fh:
+    uploaded = wa.media.upload(fh, filename="invoice.pdf", content_type="application/pdf")
+
+wa.messages.send(
+    to="201234567890",
+    media={"id": uploaded["media_id"], "kind": "document", "filename": "invoice.pdf"},
+)
+
+# Interactive buttons
+wa.messages.send(
+    to="201234567890",
+    interactive={
+        "type": "button",
+        "body": {"text": "تحب نأكد الطلب؟"},
+        "action": {"buttons": [{"type": "reply", "reply": {"id": "yes", "title": "أكيد"}}]},
+    },
+)
+
+# Multi-number workspace: pick the sender explicitly
+wa.messages.send(to="201234567890", text="hi", from_phone_number_id="113456789012345")
+
+# Check the call without spending a message
+wa.messages.send(to="201234567890", template="order_shipped", dry_run=True)
+```
+
+`text`, `interactive` and `media` are free but only deliverable inside the recipient's 24-hour customer-service window. Outside it the call fails with `OUTSIDE_CSW` and you need an approved template.
+
+The response is a `202`: Meta accepted the message. Delivery arrives later on the webhook bus, matched by `message_id` (the wamid).
+
+## One-time codes
+
+```python
+sent = wa.otp.send(to="201234567890", template="otp_login", language="ar")
+result = wa.otp.verify(request_id=sent["request_id"], code="123456")
+
+if result["verified"]:
+    ...
+```
+
+The code is generated, hashed and checked on our side — it is never returned to you.
+
+## Errors
+
+Every failure — including a refused connection or a timeout — is a `WhatsArabError`, so one `except` covers the lot. Branch on `.code`, which is stable; the message is for humans and may be reworded.
+
+```python
+from whatsarab import WhatsArabError
+
+try:
+    wa.messages.send(to="201234567890", text="hi")
+except WhatsArabError as err:
+    if err.code == "OUTSIDE_CSW":
+        send_template_instead()
+    elif err.code == "OVER_QUOTA":
+        queue_for_next_month()
+    elif err.code in ("TIMEOUT", "NETWORK_ERROR"):
+        retry_later()
+    else:
+        raise
+```
+
+`err.request_id` is worth logging — quote it in a support ticket and we can find the exact request.
+
+## Verifying webhooks
+
+Deliveries to your endpoint carry `X-Whatsarab-Timestamp` and `X-Whatsarab-Signature: sha256=<hex>`, computed over `f"{timestamp}.{raw_body}"` with your subscription secret.
+
+```python
+from fastapi import FastAPI, HTTPException, Request
+from whatsarab import verify_webhook_signature
+
+app = FastAPI()
+
+@app.post("/webhooks/whatsarab")
+async def hook(request: Request):
+    body = await request.body()          # the raw bytes
+    ok = verify_webhook_signature(
+        secret=os.environ["WHATSARAB_WEBHOOK_SECRET"],
+        raw_body=body,
+        signature_header=request.headers.get("x-whatsarab-signature"),
+        timestamp_header=request.headers.get("x-whatsarab-timestamp"),
+    )
+    if not ok:
+        raise HTTPException(status_code=401)
+    ...
+```
+
+**Pass the raw body.** A body that has been parsed and re-serialized will not match — that is the single commonest way this check is got wrong. The comparison is constant-time, and deliveries more than five minutes old are rejected (`tolerance_seconds=0` turns that off).
+
+## Options
+
+```python
+WhatsArab(
+    api_key="…",                       # required
+    base_url="https://whatsarab.com",  # override for staging or self-hosted
+    timeout=30.0,                      # seconds; None disables
+)
+```
+
+The client holds an `httpx.Client`. Close it when you are done, or use it as a context manager:
+
+```python
+with WhatsArab(api_key="…") as wa:
+    wa.messages.send(to="201234567890", text="hi")
+```
+
+## Links
+
+- [Docs](https://whatsarab.com/docs) · [OpenAPI](https://whatsarab.com/public/openapi.json) · [Guides](https://whatsarab.com/how-to) · [Support](https://whatsarab.com/support)
+
+MIT.

whatsarab-0.1.0/README.md

@@ -0,0 +1,164 @@
+# whatsarab
+
+Official Python client for the [WhatsArab](https://whatsarab.com) API — send WhatsApp messages on the official Meta Cloud API, upload media, manage templates, send and verify one-time codes, and verify signed webhooks.
+
+```bash
+pip install whatsarab
+```
+
+Python 3.9+.
+
+## Quick start
+
+```python
+import os
+from whatsarab import WhatsArab
+
+wa = WhatsArab(api_key=os.environ["WHATSARAB_API_KEY"])
+
+# Free-form text — only inside the 24-hour customer-service window
+wa.messages.send(to="201234567890", text="أهلًا يا سارة! طلبك رقم ١٠٤٢٨ خرج للتوصيل.")
+
+# An approved template — works any time
+wa.messages.send(
+    to="201234567890",
+    template="order_shipped",
+    language="ar",
+    components=[{"type": "body", "parameters": [{"type": "text", "text": "10428"}]}],
+)
+```
+
+Get an API key from **/app/integrations → API keys**. Keys are shown once, at creation.
+
+## What this covers
+
+The API-key surface, which is the eleven operations under `/api` in the [OpenAPI document](https://whatsarab.com/public/openapi.json):
+
+| | |
+|---|---|
+| `wa.messages.send()` | text · template · interactive · media |
+| `wa.media.upload()` / `.download()` | multipart up, raw bytes back |
+| `wa.templates.list() / .create() / .edit() / .delete()` | Meta template management |
+| `wa.otp.send()` / `.verify()` | one-time codes over WhatsApp |
+| `wa.events.list()` | recent webhook events |
+| `verify_webhook_signature()` | HMAC check for deliveries to you |
+
+**Not covered, deliberately:** contacts, the inbox and broadcasts are session-authenticated — they belong to a signed-in dashboard user, not to a server-side key — so there is no endpoint for this client to call. If that changes, it changes in the OpenAPI document first.
+
+## Sending
+
+Exactly one of `template`, `text`, `interactive` or `media` per call — checked locally, so a mistake is a `ValueError` on your machine rather than a 400 from production.
+
+```python
+# Media: upload once, then send by id
+with open("invoice.pdf", "rb") as fh:
+    uploaded = wa.media.upload(fh, filename="invoice.pdf", content_type="application/pdf")
+
+wa.messages.send(
+    to="201234567890",
+    media={"id": uploaded["media_id"], "kind": "document", "filename": "invoice.pdf"},
+)
+
+# Interactive buttons
+wa.messages.send(
+    to="201234567890",
+    interactive={
+        "type": "button",
+        "body": {"text": "تحب نأكد الطلب؟"},
+        "action": {"buttons": [{"type": "reply", "reply": {"id": "yes", "title": "أكيد"}}]},
+    },
+)
+
+# Multi-number workspace: pick the sender explicitly
+wa.messages.send(to="201234567890", text="hi", from_phone_number_id="113456789012345")
+
+# Check the call without spending a message
+wa.messages.send(to="201234567890", template="order_shipped", dry_run=True)
+```
+
+`text`, `interactive` and `media` are free but only deliverable inside the recipient's 24-hour customer-service window. Outside it the call fails with `OUTSIDE_CSW` and you need an approved template.
+
+The response is a `202`: Meta accepted the message. Delivery arrives later on the webhook bus, matched by `message_id` (the wamid).
+
+## One-time codes
+
+```python
+sent = wa.otp.send(to="201234567890", template="otp_login", language="ar")
+result = wa.otp.verify(request_id=sent["request_id"], code="123456")
+
+if result["verified"]:
+    ...
+```
+
+The code is generated, hashed and checked on our side — it is never returned to you.
+
+## Errors
+
+Every failure — including a refused connection or a timeout — is a `WhatsArabError`, so one `except` covers the lot. Branch on `.code`, which is stable; the message is for humans and may be reworded.
+
+```python
+from whatsarab import WhatsArabError
+
+try:
+    wa.messages.send(to="201234567890", text="hi")
+except WhatsArabError as err:
+    if err.code == "OUTSIDE_CSW":
+        send_template_instead()
+    elif err.code == "OVER_QUOTA":
+        queue_for_next_month()
+    elif err.code in ("TIMEOUT", "NETWORK_ERROR"):
+        retry_later()
+    else:
+        raise
+```
+
+`err.request_id` is worth logging — quote it in a support ticket and we can find the exact request.
+
+## Verifying webhooks
+
+Deliveries to your endpoint carry `X-Whatsarab-Timestamp` and `X-Whatsarab-Signature: sha256=<hex>`, computed over `f"{timestamp}.{raw_body}"` with your subscription secret.
+
+```python
+from fastapi import FastAPI, HTTPException, Request
+from whatsarab import verify_webhook_signature
+
+app = FastAPI()
+
+@app.post("/webhooks/whatsarab")
+async def hook(request: Request):
+    body = await request.body()          # the raw bytes
+    ok = verify_webhook_signature(
+        secret=os.environ["WHATSARAB_WEBHOOK_SECRET"],
+        raw_body=body,
+        signature_header=request.headers.get("x-whatsarab-signature"),
+        timestamp_header=request.headers.get("x-whatsarab-timestamp"),
+    )
+    if not ok:
+        raise HTTPException(status_code=401)
+    ...
+```
+
+**Pass the raw body.** A body that has been parsed and re-serialized will not match — that is the single commonest way this check is got wrong. The comparison is constant-time, and deliveries more than five minutes old are rejected (`tolerance_seconds=0` turns that off).
+
+## Options
+
+```python
+WhatsArab(
+    api_key="…",                       # required
+    base_url="https://whatsarab.com",  # override for staging or self-hosted
+    timeout=30.0,                      # seconds; None disables
+)
+```
+
+The client holds an `httpx.Client`. Close it when you are done, or use it as a context manager:
+
+```python
+with WhatsArab(api_key="…") as wa:
+    wa.messages.send(to="201234567890", text="hi")
+```
+
+## Links
+
+- [Docs](https://whatsarab.com/docs) · [OpenAPI](https://whatsarab.com/public/openapi.json) · [Guides](https://whatsarab.com/how-to) · [Support](https://whatsarab.com/support)
+
+MIT.

whatsarab-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "whatsarab"
+version = "0.1.0"
+description = "Official Python client for the WhatsArab API — WhatsApp messages, media, templates, OTP, and signed webhooks on the official Meta Cloud API."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "WhatsArab" }]
+keywords = ["whatsapp", "whatsapp-business-api", "meta-cloud-api", "messaging", "otp", "mena", "arabic"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Communications :: Chat",
+  "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://whatsarab.com/docs"
+Documentation = "https://whatsarab.com/docs"
+Source = "https://github.com/efayek/whatsapp-api/tree/main/sdks/python"
+Support = "https://whatsarab.com/support"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/whatsarab"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

whatsarab-0.1.0/src/whatsarab/__init__.py

@@ -0,0 +1,32 @@
+"""whatsarab — the official Python client for the WhatsArab API.
+
+    from whatsarab import WhatsArab
+
+    wa = WhatsArab(api_key=os.environ["WHATSARAB_API_KEY"])
+    wa.messages.send(to="201234567890", text="أهلًا! طلبك في الطريق.")
+
+    sent = wa.otp.send(to="201234567890", template="otp_login")
+    wa.otp.verify(request_id=sent["request_id"], code="123456")
+
+SCOPE: this client covers the API-KEY surface and nothing else — the eleven
+operations under /api in the published OpenAPI document. Contacts, inbox and
+broadcasts are session-authenticated (they belong to the dashboard, not to a
+server-side key), so an SDK cannot offer them without inventing endpoints.
+"""
+
+from .client import (
+    DEFAULT_BASE_URL,
+    WhatsArab,
+    WhatsArabError,
+)
+from .webhooks import verify_webhook_signature
+
+__all__ = [
+    "WhatsArab",
+    "WhatsArabError",
+    "verify_webhook_signature",
+    "DEFAULT_BASE_URL",
+    "__version__",
+]
+
+__version__ = "0.1.0"

whatsarab-0.1.0/src/whatsarab/client.py

@@ -0,0 +1,310 @@
+"""HTTP client and resources.
+
+httpx rather than requests: it gives us HTTP/2, a real timeout object, and the
+same call shape for a future async client without a second implementation.
+"""
+
+from __future__ import annotations
+
+from typing import Any, BinaryIO, Dict, List, Mapping, Optional, Sequence, Union
+from urllib.parse import quote
+
+import httpx
+
+DEFAULT_BASE_URL = "https://whatsarab.com"
+DEFAULT_TIMEOUT = 30.0
+
+MediaKind = str  # "image" | "video" | "audio" | "document" | "sticker"
+TemplateCategory = str  # "AUTHENTICATION" | "MARKETING" | "UTILITY" | "SERVICE"
+
+
+class WhatsArabError(Exception):
+    """Every failure, transport included, so a caller writes one except clause.
+
+    Branch on ``code`` — it is the platform's stable error code
+    (``OUTSIDE_CSW``, ``OVER_QUOTA``, ``INVALID_PHONE``…). ``args[0]`` /
+    ``str(err)`` is the human message and may be reworded between releases.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int,
+        code: str,
+        request_id: Optional[str] = None,
+        meta_error: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.request_id = request_id
+        self.meta_error = meta_error
+
+    def __repr__(self) -> str:  # pragma: no cover - debugging aid
+        return f"WhatsArabError(code={self.code!r}, status={self.status}, message={str(self)!r})"
+
+
+class WhatsArab:
+    """Client for the WhatsArab API.
+
+    Args:
+        api_key: your key (``whap_<prefix>_<secret>``), from /app/integrations.
+        base_url: backend origin. Defaults to the hosted platform.
+        timeout: seconds before a request is abandoned. ``None`` disables.
+        transport: an ``httpx`` transport, for tests or a custom proxy.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: Optional[float] = DEFAULT_TIMEOUT,
+        transport: Optional[httpx.BaseTransport] = None,
+        client: Optional[httpx.Client] = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+
+        self.base_url = base_url.rstrip("/")
+        self._client = client or httpx.Client(
+            base_url=self.base_url,
+            timeout=timeout,
+            transport=transport,
+            headers={"X-API-Key": api_key},
+        )
+        # A caller-supplied client may not carry the key; set it either way so
+        # the header is never silently missing.
+        self._client.headers["X-API-Key"] = api_key
+
+        self.messages = _Messages(self)
+        self.media = _Media(self)
+        self.templates = _Templates(self)
+        self.otp = _Otp(self)
+        self.events = _Events(self)
+
+    # ── plumbing ────────────────────────────────────────────────────
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        files: Any = None,
+        params: Optional[Mapping[str, Any]] = None,
+        raw: bool = False,
+    ) -> Any:
+        try:
+            response = self._client.request(method, path, json=json, files=files, params=params)
+        except httpx.TimeoutException as exc:
+            raise WhatsArabError(
+                str(exc) or f"Timed out talking to {self.base_url}",
+                status=0,
+                code="TIMEOUT",
+            ) from exc
+        except httpx.HTTPError as exc:
+            raise WhatsArabError(
+                str(exc) or f"Could not reach {self.base_url}",
+                status=0,
+                code="NETWORK_ERROR",
+            ) from exc
+
+        if raw:
+            if response.status_code >= 400:
+                raise self._error_from(response)
+            return response.content
+
+        try:
+            envelope = response.json()
+        except ValueError:
+            envelope = None
+
+        # The envelope is the authority, not the status line: the platform can
+        # answer 200 with success=false, and a client that trusted the status
+        # would hand back None and call it a send.
+        if response.status_code >= 400 or not isinstance(envelope, dict) or not envelope.get("success"):
+            raise self._error_from(response, envelope)
+        return envelope.get("data")
+
+    @staticmethod
+    def _error_from(response: httpx.Response, envelope: Any = None) -> WhatsArabError:
+        if envelope is None:
+            try:
+                envelope = response.json()
+            except ValueError:
+                envelope = None
+        error = envelope.get("error") if isinstance(envelope, dict) else None
+        error = error if isinstance(error, dict) else {}
+        return WhatsArabError(
+            error.get("message") or response.reason_phrase or "Request failed",
+            status=response.status_code,
+            code=error.get("code") or f"HTTP_{response.status_code}",
+            request_id=envelope.get("request_id") if isinstance(envelope, dict) else None,
+            meta_error=error.get("meta_error"),
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "WhatsArab":
+        return self
+
+    def __exit__(self, *exc_info: Any) -> None:
+        self.close()
+
+
+class _Messages:
+    def __init__(self, client: WhatsArab) -> None:
+        self._client = client
+
+    def send(
+        self,
+        *,
+        to: str,
+        template: Optional[str] = None,
+        text: Optional[str] = None,
+        interactive: Optional[Mapping[str, Any]] = None,
+        media: Optional[Mapping[str, Any]] = None,
+        language: Optional[str] = None,
+        components: Optional[Sequence[Mapping[str, Any]]] = None,
+        from_phone_number_id: Optional[str] = None,
+        dry_run: Optional[bool] = None,
+    ) -> Dict[str, Any]:
+        """Send one message. Returns the 202 body, including the wamid.
+
+        Exactly one of ``template`` / ``text`` / ``interactive`` / ``media``.
+        Python cannot express that in the signature the way a TypeScript union
+        can, so it is checked here — a local ValueError beats a round trip that
+        comes back 400.
+
+        ``text``, ``interactive`` and ``media`` are free but deliverable only
+        inside the recipient's 24-hour customer-service window; outside it the
+        call fails with ``OUTSIDE_CSW``.
+        """
+        kinds = {
+            "template": template,
+            "text": text,
+            "interactive": interactive,
+            "media": media,
+        }
+        present = [name for name, value in kinds.items() if value is not None]
+        if len(present) != 1:
+            raise ValueError(
+                "exactly one of template / text / interactive / media is required, got: "
+                + (", ".join(present) if present else "none")
+            )
+
+        payload: Dict[str, Any] = {"to": to}
+        payload[present[0]] = kinds[present[0]]
+        if language is not None:
+            payload["language"] = language
+        if components is not None:
+            payload["components"] = list(components)
+        if from_phone_number_id is not None:
+            payload["from_phone_number_id"] = from_phone_number_id
+        if dry_run is not None:
+            payload["dry_run"] = dry_run
+        return self._client.request("POST", "/api/messages", json=payload)
+
+
+class _Media:
+    def __init__(self, client: WhatsArab) -> None:
+        self._client = client
+
+    def upload(
+        self,
+        file: Union[bytes, BinaryIO],
+        *,
+        filename: Optional[str] = None,
+        content_type: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Upload a file and get back a ``media_id`` for ``messages.send``."""
+        return self._client.request(
+            "POST",
+            "/api/media",
+            files={"file": (filename, file, content_type)},
+        )
+
+    def download(self, media_id: str) -> bytes:
+        """Download a media file by id. Returns the raw bytes."""
+        return self._client.request("GET", f"/api/media/{quote(str(media_id), safe='')}", raw=True)
+
+
+class _Templates:
+    def __init__(self, client: WhatsArab) -> None:
+        self._client = client
+
+    def list(self) -> List[Any]:
+        return self._client.request("GET", "/api/templates")
+
+    def create(
+        self,
+        *,
+        name: str,
+        language: str,
+        category: TemplateCategory,
+        components: Sequence[Mapping[str, Any]],
+    ) -> Any:
+        return self._client.request(
+            "POST",
+            "/api/templates",
+            json={
+                "name": name,
+                "language": language,
+                "category": category,
+                "components": list(components),
+            },
+        )
+
+    def edit(self, template_id: str, **fields: Any) -> Any:
+        """Edit by Meta template id — note that create/delete key off the NAME."""
+        return self._client.request(
+            "PATCH", f"/api/templates/{quote(str(template_id), safe='')}", json=fields
+        )
+
+    def delete(self, name: str) -> Any:
+        return self._client.request("DELETE", f"/api/templates/{quote(str(name), safe='')}")
+
+
+class _Otp:
+    def __init__(self, client: WhatsArab) -> None:
+        self._client = client
+
+    def send(
+        self,
+        *,
+        to: str,
+        template: str,
+        language: Optional[str] = None,
+        code_length: Optional[int] = None,
+        ttl_seconds: Optional[int] = None,
+        max_attempts: Optional[int] = None,
+        from_phone_number_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {"to": to, "template": template}
+        for key, value in (
+            ("language", language),
+            ("code_length", code_length),
+            ("ttl_seconds", ttl_seconds),
+            ("max_attempts", max_attempts),
+            ("from_phone_number_id", from_phone_number_id),
+        ):
+            if value is not None:
+                payload[key] = value
+        return self._client.request("POST", "/api/otp/send", json=payload)
+
+    def verify(self, *, request_id: str, code: str) -> Dict[str, Any]:
+        return self._client.request(
+            "POST", "/api/otp/verify", json={"request_id": request_id, "code": code}
+        )
+
+
+class _Events:
+    def __init__(self, client: WhatsArab) -> None:
+        self._client = client
+
+    def list(self, limit: int = 50) -> List[Dict[str, Any]]:
+        """Recent webhook events, newest first."""
+        return self._client.request("GET", "/api/events", params={"limit": limit})

whatsarab-0.1.0/src/whatsarab/webhooks.py

@@ -0,0 +1,66 @@
+"""Verification for outbound webhooks from WhatsArab."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import time
+from typing import Callable, Optional, Union
+
+
+def verify_webhook_signature(
+    *,
+    secret: str,
+    raw_body: Union[str, bytes],
+    signature_header: Optional[str],
+    timestamp_header: Optional[str],
+    tolerance_seconds: int = 300,
+    now: Optional[Callable[[], float]] = None,
+) -> bool:
+    """Return True if a delivery genuinely came from WhatsArab.
+
+    Deliveries carry ``X-Whatsarab-Timestamp`` and
+    ``X-Whatsarab-Signature: sha256=<hex>``, computed over
+    ``f"{timestamp}.{raw_body}"`` with the subscription's secret.
+
+    Pass the RAW body — the exact bytes received. A body that has been parsed
+    and re-serialized will not match, and that is the single commonest way this
+    check is got wrong::
+
+        @app.post("/webhooks/whatsarab")
+        async def hook(request: Request):
+            body = await request.body()
+            ok = verify_webhook_signature(
+                secret=os.environ["WHATSARAB_WEBHOOK_SECRET"],
+                raw_body=body,
+                signature_header=request.headers.get("x-whatsarab-signature"),
+                timestamp_header=request.headers.get("x-whatsarab-timestamp"),
+            )
+            if not ok:
+                raise HTTPException(401)
+
+    Set ``tolerance_seconds=0`` to skip the freshness check (replay protection
+    off). Returns False rather than raising on anything malformed, so a bad
+    header cannot turn into a 500 on your webhook route.
+    """
+    if not secret or not signature_header or not timestamp_header:
+        return False
+
+    if tolerance_seconds > 0:
+        try:
+            sent_at = float(timestamp_header)
+        except (TypeError, ValueError):
+            return False
+        current = now() if now is not None else time.time()
+        if abs(current - sent_at) > tolerance_seconds:
+            return False
+
+    provided = signature_header
+    if provided.startswith("sha256="):
+        provided = provided[len("sha256=") :]
+
+    body = raw_body.encode("utf-8") if isinstance(raw_body, str) else raw_body
+    signed = timestamp_header.encode("utf-8") + b"." + body
+    expected = hmac.new(secret.encode("utf-8"), signed, hashlib.sha256).hexdigest()
+
+    return hmac.compare_digest(expected, provided)

whatsarab-0.1.0/tests/test_client.py

@@ -0,0 +1,345 @@
+"""Behavioural tests for the Python client.
+
+Every test drives a real httpx.MockTransport, so what is asserted is the request
+the SDK actually built — the URL, the method, the key header, the body — plus
+how it turns a response into a value or an exception. No mocking of our own
+methods, which would only prove the test matches the test.
+"""
+
+import hashlib
+import hmac
+import json
+
+import httpx
+import pytest
+
+from whatsarab import DEFAULT_BASE_URL, WhatsArab, WhatsArabError, verify_webhook_signature
+
+
+def make_client(handler, **kwargs):
+    transport = httpx.MockTransport(handler)
+    return WhatsArab(api_key="whap_test_secret", transport=transport, **kwargs)
+
+
+def envelope(data, status=200):
+    return httpx.Response(status, json={"success": True, "data": data})
+
+
+# ── requests ────────────────────────────────────────────────────────
+
+
+def test_attaches_key_and_builds_url():
+    seen = {}
+
+    def handler(request):
+        seen["url"] = str(request.url)
+        seen["method"] = request.method
+        seen["key"] = request.headers.get("x-api-key")
+        seen["body"] = json.loads(request.content)
+        return envelope({"message_id": "wamid.X"})
+
+    client = make_client(handler)
+    client.messages.send(to="201234567890", text="مرحبا")
+
+    assert seen["url"] == f"{DEFAULT_BASE_URL}/api/messages"
+    assert seen["method"] == "POST"
+    assert seen["key"] == "whap_test_secret"
+    assert seen["body"] == {"to": "201234567890", "text": "مرحبا"}
+
+
+def test_strips_trailing_slashes_from_base_url():
+    seen = {}
+
+    def handler(request):
+        seen["url"] = str(request.url)
+        return envelope([])
+
+    client = make_client(handler, base_url="https://staging.example.com///")
+    client.templates.list()
+
+    assert seen["url"] == "https://staging.example.com/api/templates"
+
+
+def test_unwraps_the_envelope():
+    client = make_client(lambda r: envelope({"request_id": "req_1", "expires_in": 300}))
+    result = client.otp.send(to="201234567890", template="otp_login")
+    assert result["request_id"] == "req_1"
+    assert result["expires_in"] == 300
+
+
+def test_error_envelope_becomes_whatsaraberror():
+    def handler(request):
+        return httpx.Response(
+            400,
+            json={
+                "success": False,
+                "request_id": "req_err",
+                "error": {"code": "OUTSIDE_CSW", "message": "Outside the 24-hour window."},
+            },
+        )
+
+    client = make_client(handler)
+    with pytest.raises(WhatsArabError) as excinfo:
+        client.messages.send(to="201234567890", text="hi")
+
+    err = excinfo.value
+    assert err.code == "OUTSIDE_CSW"
+    assert err.status == 400
+    assert err.request_id == "req_err"
+    assert "24-hour" in str(err)
+
+
+def test_200_with_success_false_is_still_a_failure():
+    # The envelope is the authority, not the status line. A client that trusted
+    # the status would return None here and call it a send.
+    def handler(request):
+        return httpx.Response(200, json={"success": False, "error": {"code": "OVER_QUOTA"}})
+
+    client = make_client(handler)
+    with pytest.raises(WhatsArabError) as excinfo:
+        client.templates.list()
+    assert excinfo.value.code == "OVER_QUOTA"
+
+
+def test_transport_failure_is_the_same_error_type():
+    def handler(request):
+        raise httpx.ConnectError("connection refused")
+
+    client = make_client(handler)
+    with pytest.raises(WhatsArabError) as excinfo:
+        client.events.list()
+    assert excinfo.value.code == "NETWORK_ERROR"
+    assert excinfo.value.status == 0
+
+
+def test_timeout_is_reported_as_timeout():
+    def handler(request):
+        raise httpx.ReadTimeout("timed out")
+
+    client = make_client(handler)
+    with pytest.raises(WhatsArabError) as excinfo:
+        client.events.list()
+    assert excinfo.value.code == "TIMEOUT"
+
+
+def test_non_json_error_body_still_raises_with_a_code():
+    def handler(request):
+        return httpx.Response(502, text="<html>bad gateway</html>")
+
+    client = make_client(handler)
+    with pytest.raises(WhatsArabError) as excinfo:
+        client.templates.list()
+    assert excinfo.value.code == "HTTP_502"
+    assert excinfo.value.status == 502
+
+
+# ── resources ───────────────────────────────────────────────────────
+
+
+def test_send_requires_exactly_one_kind():
+    client = make_client(lambda r: envelope({}))
+
+    with pytest.raises(ValueError, match="exactly one"):
+        client.messages.send(to="201234567890")
+    with pytest.raises(ValueError, match="exactly one"):
+        client.messages.send(to="201234567890", text="hi", template="order_shipped")
+
+
+def test_send_passes_optional_fields_through_and_omits_the_rest():
+    seen = {}
+
+    def handler(request):
+        seen["body"] = json.loads(request.content)
+        return envelope({})
+
+    client = make_client(handler)
+    client.messages.send(
+        to="201234567890",
+        template="order_shipped",
+        language="ar",
+        components=[{"type": "body", "parameters": [{"type": "text", "text": "10428"}]}],
+        from_phone_number_id="113456789012345",
+    )
+
+    assert seen["body"]["template"] == "order_shipped"
+    assert seen["body"]["language"] == "ar"
+    assert seen["body"]["from_phone_number_id"] == "113456789012345"
+    # Unset options must not be sent as nulls — the API rejects a null dry_run.
+    assert "dry_run" not in seen["body"]
+    assert "text" not in seen["body"]
+
+
+def test_path_segments_are_url_encoded():
+    # The case that matters is a RESERVED character, not a space: httpx encodes
+    # spaces on its own, so asserting on one would pass with the encoding
+    # removed. A slash does not get encoded for you — it silently becomes a
+    # path separator and addresses a different resource.
+    calls = []
+
+    def handler(request):
+        calls.append(str(request.url))
+        return httpx.Response(200, content=b"x")
+
+    client = make_client(handler)
+    client.media.download("../../secrets")
+
+    assert "%2F" in calls[0]
+    assert calls[0].endswith("/api/media/..%2F..%2Fsecrets")
+
+
+def test_templates_edit_is_patch_on_id_and_delete_is_on_name():
+    calls = []
+
+    def handler(request):
+        calls.append((request.method, str(request.url)))
+        return envelope({})
+
+    client = make_client(handler)
+    client.templates.edit("12345", category="UTILITY")
+    client.templates.delete("order_confirmation")
+
+    assert calls[0][0] == "PATCH"
+    assert calls[0][1].endswith("/api/templates/12345")
+    assert calls[1][0] == "DELETE"
+    assert calls[1][1].endswith("/api/templates/order_confirmation")
+
+
+def test_media_download_returns_raw_bytes():
+    payload = b"\xff\xd8\xff\xe0jpeg-ish"
+
+    def handler(request):
+        return httpx.Response(200, content=payload)
+
+    client = make_client(handler)
+    assert client.media.download("media_1") == payload
+
+
+def test_media_download_raises_on_an_error_body():
+    def handler(request):
+        return httpx.Response(404, json={"success": False, "error": {"code": "NOT_FOUND"}})
+
+    client = make_client(handler)
+    with pytest.raises(WhatsArabError) as excinfo:
+        client.media.download("nope")
+    assert excinfo.value.code == "NOT_FOUND"
+
+
+def test_media_upload_is_multipart():
+    seen = {}
+
+    def handler(request):
+        seen["content_type"] = request.headers.get("content-type", "")
+        seen["body"] = request.content
+        return envelope({"media_id": "m_1"})
+
+    client = make_client(handler)
+    result = client.media.upload(b"%PDF-1.4", filename="invoice.pdf", content_type="application/pdf")
+
+    assert result["media_id"] == "m_1"
+    assert seen["content_type"].startswith("multipart/form-data")
+    assert b"invoice.pdf" in seen["body"]
+
+
+def test_events_list_sends_the_limit_as_a_query_param():
+    seen = {}
+
+    def handler(request):
+        seen["url"] = str(request.url)
+        return envelope([])
+
+    client = make_client(handler)
+    client.events.list(limit=5)
+
+    assert "limit=5" in seen["url"]
+
+
+def test_rejects_construction_without_a_key():
+    with pytest.raises(ValueError, match="api_key is required"):
+        WhatsArab(api_key="")
+
+
+def test_works_as_a_context_manager():
+    with make_client(lambda r: envelope([])) as client:
+        assert client.templates.list() == []
+
+
+# ── webhook signature ───────────────────────────────────────────────
+
+SECRET = "whsec_test"
+NOW = 1700000000.0
+
+
+def sign(body, timestamp, secret=SECRET):
+    body_bytes = body.encode("utf-8") if isinstance(body, str) else body
+    signed = str(timestamp).encode("utf-8") + b"." + body_bytes
+    digest = hmac.new(secret.encode("utf-8"), signed, hashlib.sha256).hexdigest()
+    return "sha256=" + digest
+
+
+def test_accepts_a_correctly_signed_delivery():
+    body = '{"event":"message.delivered"}'
+    assert verify_webhook_signature(
+        secret=SECRET,
+        raw_body=body,
+        signature_header=sign(body, "1700000000"),
+        timestamp_header="1700000000",
+        now=lambda: NOW,
+    )
+
+
+def test_rejects_a_body_that_changed_by_one_character():
+    assert not verify_webhook_signature(
+        secret=SECRET,
+        raw_body='{"amount":99}',
+        signature_header=sign('{"amount":10}', "1700000000"),
+        timestamp_header="1700000000",
+        now=lambda: NOW,
+    )
+
+
+def test_rejects_a_signature_from_a_different_secret():
+    body = '{"a":1}'
+    assert not verify_webhook_signature(
+        secret=SECRET,
+        raw_body=body,
+        signature_header=sign(body, "1700000000", secret="other_secret"),
+        timestamp_header="1700000000",
+        now=lambda: NOW,
+    )
+
+
+def test_rejects_a_replay_outside_the_tolerance_but_allows_it_when_disabled():
+    body = '{"a":1}'
+    args = dict(
+        secret=SECRET,
+        raw_body=body,
+        signature_header=sign(body, "1700000000"),
+        timestamp_header="1700000000",
+    )
+    # The bytes stay valid forever; only the clock moves.
+    assert not verify_webhook_signature(**args, now=lambda: NOW + 3600)
+    assert verify_webhook_signature(**args, tolerance_seconds=0, now=lambda: NOW + 3600)
+
+
+def test_rejects_missing_or_malformed_headers_without_raising():
+    base = dict(secret=SECRET, raw_body="{}", now=lambda: NOW)
+    assert not verify_webhook_signature(**base, signature_header=None, timestamp_header="1700000000")
+    assert not verify_webhook_signature(**base, signature_header="sha256=aa", timestamp_header=None)
+    assert not verify_webhook_signature(**base, signature_header="sha256=aa", timestamp_header="not-a-number")
+    assert not verify_webhook_signature(**base, signature_header="sha256=short", timestamp_header="1700000000")
+
+
+def test_accepts_the_signature_with_or_without_the_prefix():
+    body = '{"a":1}'
+    with_prefix = sign(body, "1700000000")
+    base = dict(secret=SECRET, raw_body=body, timestamp_header="1700000000", now=lambda: NOW)
+    assert verify_webhook_signature(**base, signature_header=with_prefix)
+    assert verify_webhook_signature(**base, signature_header=with_prefix[len("sha256=") :])
+
+
+def test_bytes_and_str_bodies_agree():
+    body = '{"ar":"أهلًا"}'
+    signature = sign(body, "1700000000")
+    base = dict(secret=SECRET, signature_header=signature, timestamp_header="1700000000", now=lambda: NOW)
+    assert verify_webhook_signature(**base, raw_body=body)
+    assert verify_webhook_signature(**base, raw_body=body.encode("utf-8"))