wazzapi 0.1.0__py3-none-any.whl

wazzapi/webhooks.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+from collections.abc import Mapping
+from typing import Any
+
+from .models.webhooks import PublicDeviceWebhook, PublicMessageWebhook, WebhookPayload
+
+SIGNATURE_HEADER = "X-Wazzapi-Signature"
+EVENT_HEADER = "X-Wazzapi-Event"
+EVENT_ID_HEADER = "X-Wazzapi-Event-ID"
+_SIGNATURE_PREFIX = "sha256="
+
+
+class WazzapiWebhookError(Exception):
+    """Base exception for webhook helpers."""
+
+
+class WazzapiWebhookVerificationError(WazzapiWebhookError):
+    """Raised when webhook signature verification fails."""
+
+
+class WazzapiWebhookParseError(WazzapiWebhookError):
+    """Raised when a webhook payload cannot be parsed."""
+
+
+def generate_webhook_signature(payload: bytes | str, secret: str) -> str:
+    payload_bytes = _to_bytes(payload)
+    digest = hmac.new(secret.encode("utf-8"), payload_bytes, hashlib.sha256).hexdigest()
+    return f"{_SIGNATURE_PREFIX}{digest}"
+
+
+def verify_webhook_signature(payload: bytes | str, signature: str, secret: str) -> bool:
+    normalized_signature = signature.strip()
+    expected = generate_webhook_signature(payload, secret)
+    return hmac.compare_digest(expected, normalized_signature)
+
+
+class WebhookHandler:
+    """Verify and parse incoming WazzAPI webhook deliveries."""
+
+    def __init__(self, secret: str) -> None:
+        self.secret = secret
+
+    def generate_signature(self, payload: bytes | str) -> str:
+        return generate_webhook_signature(payload, self.secret)
+
+    def verify_signature(self, payload: bytes | str, signature: str) -> bool:
+        return verify_webhook_signature(payload, signature, self.secret)
+
+    def verify_headers(self, payload: bytes | str, headers: Mapping[str, str]) -> None:
+        signature = _get_header(headers, SIGNATURE_HEADER)
+        if not signature:
+            raise WazzapiWebhookVerificationError(
+                f"Missing required webhook header: {SIGNATURE_HEADER}"
+            )
+        if not self.verify_signature(payload, signature):
+            raise WazzapiWebhookVerificationError("Invalid webhook signature")
+
+        if not _get_header(headers, EVENT_HEADER):
+            raise WazzapiWebhookVerificationError(
+                f"Missing required webhook header: {EVENT_HEADER}"
+            )
+        if not _get_header(headers, EVENT_ID_HEADER):
+            raise WazzapiWebhookVerificationError(
+                f"Missing required webhook header: {EVENT_ID_HEADER}"
+            )
+
+    def parse(self, payload: bytes | str) -> WebhookPayload:
+        payload_bytes = _to_bytes(payload)
+        try:
+            raw_payload = json.loads(payload_bytes.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+            raise WazzapiWebhookParseError("Webhook payload is not valid JSON") from exc
+
+        if not isinstance(raw_payload, dict):
+            raise WazzapiWebhookParseError("Webhook payload must be a JSON object")
+
+        event_type = raw_payload.get("event_type")
+        if not isinstance(event_type, str):
+            raise WazzapiWebhookParseError("Webhook payload is missing event_type")
+
+        if event_type.startswith("message."):
+            return PublicMessageWebhook.model_validate(raw_payload)
+        if event_type.startswith("device."):
+            return PublicDeviceWebhook.model_validate(raw_payload)
+        raise WazzapiWebhookParseError(f"Unsupported webhook event type: {event_type}")
+
+    def verify_and_parse(self, payload: bytes | str, headers: Mapping[str, str]) -> WebhookPayload:
+        self.verify_headers(payload, headers)
+        parsed = self.parse(payload)
+        header_event = _get_header(headers, EVENT_HEADER)
+        if header_event and header_event != parsed.event_type:
+            raise WazzapiWebhookVerificationError(
+                "Webhook event header does not match payload event_type"
+            )
+        return parsed
+
+
+def parse_webhook(payload: bytes | str, headers: Mapping[str, str], secret: str) -> WebhookPayload:
+    return WebhookHandler(secret).verify_and_parse(payload, headers)
+
+
+def _to_bytes(payload: bytes | str) -> bytes:
+    if isinstance(payload, bytes):
+        return payload
+    return payload.encode("utf-8")
+
+
+def _get_header(headers: Mapping[str, str], name: str) -> str | None:
+    expected = name.lower()
+    for key, value in headers.items():
+        if key.lower() == expected:
+            return value
+    return None
+
+
+__all__ = [
+    "EVENT_HEADER",
+    "EVENT_ID_HEADER",
+    "SIGNATURE_HEADER",
+    "WebhookHandler",
+    "WazzapiWebhookError",
+    "WazzapiWebhookParseError",
+    "WazzapiWebhookVerificationError",
+    "generate_webhook_signature",
+    "parse_webhook",
+    "verify_webhook_signature",
+]

wazzapi-0.1.0.dist-info/METADATA

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: wazzapi
+Version: 0.1.0
+Summary: Typed Python SDK for WazzAPI
+Project-URL: API, https://api.wazzapi.com
+Keywords: api,sdk,wazzapi,webhook,whatsapp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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 :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1.0,>=0.28
+Requires-Dist: pydantic<3.0,>=2.11
+Description-Content-Type: text/markdown
+
+# WazzAPI Python SDK
+
+Official Python SDK for WazzAPI.
+
+Use it to send messages, manage contacts and templates, and verify incoming webhooks with a simple typed client.
+
+## What you can do with this SDK
+
+- send direct WhatsApp messages
+- list, create, update, and delete contacts
+- manage message templates and preview rendered content
+- verify and parse incoming WazzAPI webhooks
+- work with typed request and response models
+
+## Requirements
+
+- Python 3.10+
+- a WazzAPI account
+- a WazzAPI API key
+
+## Install
+
+From PyPI:
+
+```bash
+pip install wazzapi-py
+```
+
+With uv:
+
+```bash
+uv add wazzapi-py
+```
+
+Need a WazzAPI account first?
+
+Sign up at `https://app.wazzapi.com` using your Google organization account. On first sign-in, WazzAPI creates a new workspace for you automatically.
+
+## Configuration
+
+For most integrations, you only need your API key:
+
+- `WAZZAPI_API_KEY`
+
+If you plan to receive webhooks, also configure:
+
+- `WAZZAPI_WEBHOOK_SECRET`
+
+The SDK uses `https://api.wazzapi.com` by default, so you do not need to set a base URL.
+
+## Quick start
+
+### Send a message
+
+```python
+from wazzapi import SendMessageRequest, WazzapiClient
+
+with WazzapiClient(api_key="your-api-key") as client:
+    response = client.messages.send(
+        SendMessageRequest(
+            phone_number="+6281234567890",
+            whatsapp_account_id="your-whatsapp-account-id",
+            content="Hello from WazzAPI!",
+        )
+    )
+
+print(response.model_dump())
+```
+
+## Error handling
+
+When the API returns a non-success response, the SDK raises `WazzapiAPIError`.
+
+```python
+from wazzapi import WazzapiAPIError, WazzapiClient
+
+try:
+    with WazzapiClient(api_key="your-api-key") as client:
+        client.messages.get("missing-message-id")
+except WazzapiAPIError as exc:
+    print(exc.status_code)
+    print(exc.message)
+```
+
+## More usage examples
+
+### List contacts
+
+```python
+from wazzapi import WazzapiClient
+
+with WazzapiClient(api_key="your-api-key") as client:
+    response = client.contacts.list(limit=20, search="alice")
+
+for contact in response.contacts:
+    print(contact.model_dump())
+```
+
+### Create a template
+
+```python
+from wazzapi import TemplateCreateRequest, WazzapiClient
+
+with WazzapiClient(api_key="your-api-key") as client:
+    template = client.templates.create(
+        TemplateCreateRequest(
+            name="welcome-message",
+            category="marketing",
+            content="Hi {{name}}, welcome to WazzAPI!",
+        )
+    )
+
+print(template.model_dump())
+```
+
+### Preview a template
+
+```python
+from wazzapi import TemplatePreviewRequest, WazzapiClient
+
+with WazzapiClient(api_key="your-api-key") as client:
+    preview = client.templates.preview(
+        TemplatePreviewRequest(
+            content="Hi {{name}}, your code is {{code}}.",
+            custom_variables={"name": "Alice", "code": "WZ-1234"},
+        )
+    )
+
+print(preview.model_dump())
+```
+
+## Webhook verification
+
+Use `WebhookHandler` to verify the raw request body against `X-Wazzapi-Signature` before parsing JSON.
+
+```python
+from wazzapi import WebhookHandler
+
+handler = WebhookHandler("your-webhook-secret")
+webhook = handler.verify_and_parse(raw_body, request.headers)
+
+print(webhook.event_type)
+print(webhook.data.model_dump())
+```
+
+WazzAPI webhook headers:
+
+- `X-Wazzapi-Signature`
+- `X-Wazzapi-Event`
+- `X-Wazzapi-Event-ID`
+
+Supported webhook event families:
+
+- message events: `message.received`, `message.sent`, `message.delivered`, `message.read`, `message.failed`
+- device events: `device.connected`, `device.disconnected`
+
+## Examples
+
+Ready-to-run examples live in `examples/`:
+
+- `examples/list_contacts.py`
+- `examples/send_message.py`
+- `examples/create_template.py`
+- `examples/preview_template.py`
+- `examples/verify_webhook.py`
+
+Run them with:
+
+```bash
+uv run python examples/list_contacts.py
+uv run python examples/send_message.py
+uv run python examples/create_template.py
+uv run python examples/preview_template.py
+uv run python examples/verify_webhook.py
+```
+
+## Release automation
+
+This repository includes a GitHub Actions workflow that publishes to PyPI automatically when a tag matching `v*` is pushed.

wazzapi-0.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+wazzapi/__init__.py,sha256=nChxmuPk-41f1CswitT1IDLTqq_2VUrBGYpaYK6tS_k,833
+wazzapi/client.py,sha256=Ps-rPR2oWGaH_R2-7KrjjNOWvBUlYRXQckShx_q-8M8,3468
+wazzapi/errors.py,sha256=RodZNLatVsw2JP5YR15TwQXlpSnkXEv4-wxqGGDosdM,1746
+wazzapi/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+wazzapi/webhooks.py,sha256=U824l0_HJsRVdXyuG5CIrtlYb_HiHHdSzQkVce7Jsig,4704
+wazzapi/models/__init__.py,sha256=vfQ970RjkqgG8Ph2YsIaLQb4EkWCabXU9-7kyTzGfS4,402
+wazzapi/models/base.py,sha256=A8o-YUNz9wYrOQMAqyMIAcpYr5y-Tc0mZ_szY1nziB8,234
+wazzapi/models/contacts.py,sha256=byhUrOiVW7NalQE7Y4Y9WVsRhZCInZV2VSv9ZCVUOAA,4516
+wazzapi/models/messages.py,sha256=1oaAAJQ36fasktbmLje4uHVwMm5YYuO4VvwFxbv2ukI,4100
+wazzapi/models/templates.py,sha256=VGZRYpYuM6fak0eYPn0fTuOS-6U80ayhcsSbaLC7YSU,2532
+wazzapi/models/webhooks.py,sha256=qCVeNtuUNbkC--bAJEmbxHNv36MvVZ6q3SA_Yt3WWfM,2159
+wazzapi/resources/__init__.py,sha256=Hagf7dJiXKFl08L0tphibKSFmxL50F0xHAjIzSf93qU,191
+wazzapi/resources/base.py,sha256=4gNtuTUz5dQo3HsEbplw27F1miVaUSlV8Zqvc6minLA,265
+wazzapi/resources/contacts.py,sha256=Oot002UJDcLiFPGd5h5EouR_76QikYnTGyj_uuEYz30,6564
+wazzapi/resources/messages.py,sha256=Ry4djOfPKWwiZQeNUOnWlHT6HiQhrWixDJSrRT5xl_4,5332
+wazzapi/resources/templates.py,sha256=Rlgpg9gPc1K0TbTBGzDJWdXL8uCKC1ZsBU_dfFStqTg,2518
+wazzapi-0.1.0.dist-info/METADATA,sha256=Xha6PPptDYYtDI0JlLviD5nrXixWSqxsifxty6_8S4I,4974
+wazzapi-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+wazzapi-0.1.0.dist-info/RECORD,,

wazzapi-0.1.0.dist-info/WHEEL

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