wazzapi 0.1.0__tar.gz

wazzapi-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

wazzapi-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,179 @@
+# 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/examples/create_template.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import os
+
+from wazzapi import TemplateCreateRequest, WazzapiClient
+
+api_key = os.environ["WAZZAPI_API_KEY"]
+
+with WazzapiClient(api_key=api_key) as client:
+    response = client.templates.create(
+        TemplateCreateRequest(
+            name="welcome-message",
+            category="marketing",
+            content="Hi {{name}}, welcome to WazzAPI!",
+        )
+    )
+
+print(response.model_dump())

wazzapi-0.1.0/examples/list_contacts.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+import os
+
+from wazzapi import WazzapiClient
+
+api_key = os.environ["WAZZAPI_API_KEY"]
+
+with WazzapiClient(api_key=api_key) as client:
+    response = client.contacts.list(limit=20, search="alice")
+
+for contact in response.contacts:
+    print(contact.model_dump())
+
+print({"total": response.total, "limit": response.limit, "offset": response.offset})

wazzapi-0.1.0/examples/preview_template.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+import os
+
+from wazzapi import TemplatePreviewRequest, WazzapiClient
+
+api_key = os.environ["WAZZAPI_API_KEY"]
+
+with WazzapiClient(api_key=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())

wazzapi-0.1.0/examples/send_message.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import os
+
+from wazzapi import SendMessageRequest, WazzapiClient
+
+api_key = os.environ["WAZZAPI_API_KEY"]
+
+with WazzapiClient(api_key=api_key) as client:
+    response = client.messages.send(
+        SendMessageRequest(
+            phone_number="+6281234567890",
+            whatsapp_account_id="your-whatsapp-account-id",
+            content="Hello from the WazzAPI Python SDK",
+        )
+    )
+
+print(response.model_dump())

wazzapi-0.1.0/examples/verify_webhook.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import json
+import os
+
+from wazzapi import WebhookHandler
+
+secret = os.environ["WAZZAPI_WEBHOOK_SECRET"]
+handler = WebhookHandler(secret)
+
+raw_body = json.dumps(
+    {
+        "id": "97e1d724-f38d-46f6-bc4c-d9e0f4cf9285",
+        "event_type": "message.received",
+        "timestamp": "2026-04-26T09:15:30Z",
+        "organization_id": "0f1d6e38-d6bc-49be-9c39-1fcf2f946d7e",
+        "webhook_id": "a17d6351-d8f6-4cd8-ae0e-fce090afdb8f",
+        "data": {
+            "message_id": "f4fd147d-e2a8-4d52-9eb5-98a72f5b90ab",
+            "whatsapp_message_id": "wamid.123",
+            "phone_number": "6281234567890",
+            "account_name": "Support Device",
+            "status": "delivered",
+            "direction": "inbound",
+            "message_type": "text",
+            "failure_reason": None,
+            "reason": None,
+            "sent_at": None,
+            "delivered_at": "2026-04-26T09:15:29Z",
+            "read_at": None,
+            "failed_at": None,
+            "whatsapp_account_id": "c053d8ef-6c19-4ecb-9cc5-a4a64be79d92",
+            "campaign_id": None,
+            "batch_id": None,
+        },
+    },
+    separators=(",", ":"),
+)
+
+headers = {
+    "X-Wazzapi-Signature": handler.generate_signature(raw_body),
+    "X-Wazzapi-Event": "message.received",
+    "X-Wazzapi-Event-ID": "2e0b76fe-f5b4-4e50-80cb-ec7cce2c8fd5",
+}
+
+webhook = handler.verify_and_parse(raw_body, headers)
+print(webhook.event_type)
+print(webhook.data.model_dump())

wazzapi-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[project]
+name = "wazzapi"
+version = "0.1.0"
+description = "Typed Python SDK for WazzAPI"
+readme = { file = "README.md", content-type = "text/markdown" }
+requires-python = ">=3.10"
+keywords = ["api", "sdk", "wazzapi", "webhook", "whatsapp"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.28,<1.0",
+  "pydantic>=2.11,<3.0",
+]
+
+[project.urls]
+API = "https://api.wazzapi.com"
+
+[dependency-groups]
+dev = [
+  "pytest>=8.3,<9.0",
+  "twine>=6.1,<7.0",
+]
+
+[build-system]
+requires = ["hatchling>=1.27.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["wazzapi"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/README.md",
+  "/examples",
+  "/pyproject.toml",
+  "/tests",
+  "/wazzapi",
+]
+
+[tool.pytest]
+python_files = ["test_*.py"]
+testpaths = ["tests"]

wazzapi-0.1.0/tests/smoke_test.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from wazzapi import (
+    SendMessageRequest,
+    WazzapiClient,
+    WebhookHandler,
+    __version__,
+    generate_webhook_signature,
+)
+
+
+def main() -> None:
+    assert __version__ == "0.1.0"
+
+    client = WazzapiClient(api_key="smoke-test-token")
+    try:
+        assert str(client.http.base_url) == "https://api.wazzapi.com"
+        assert client.http.headers["Authorization"] == "Bearer smoke-test-token"
+    finally:
+        client.close()
+
+    request = SendMessageRequest(
+        phone_number="+6281234567890",
+        whatsapp_account_id="wa_123",
+        content="smoke test",
+    )
+    assert request.phone_number == "+6281234567890"
+    assert request.content == "smoke test"
+
+    handler = WebhookHandler("secret")
+    signature = generate_webhook_signature(b"{}", "secret")
+    assert handler.verify_signature(b"{}", signature)
+
+    print("smoke-ok")
+
+
+if __name__ == "__main__":
+    main()

wazzapi-0.1.0/tests/test_client.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import json
+
+import httpx
+import pytest
+
+from wazzapi import WazzapiAPIError, WazzapiClient
+from wazzapi.models import ContactCreateRequest
+
+
+def test_client_formats_bearer_auth_header() -> None:
+    client = WazzapiClient(base_url="https://api.example.com", api_key="plain-token")
+    try:
+        assert client.http.headers["Authorization"] == "Bearer plain-token"
+        assert client.http.headers["Accept"] == "application/json"
+        assert client.http.headers["Content-Type"] == "application/json"
+    finally:
+        client.close()
+
+
+def test_client_uses_default_wazzapi_base_url() -> None:
+    client = WazzapiClient(api_key="plain-token")
+    try:
+        assert str(client.http.base_url) == "https://api.wazzapi.com"
+    finally:
+        client.close()
+
+
+def test_client_preserves_existing_bearer_prefix() -> None:
+    client = WazzapiClient(base_url="https://api.example.com", api_key="Bearer already-set")
+    try:
+        assert client.http.headers["Authorization"] == "Bearer already-set"
+    finally:
+        client.close()
+
+
+def test_client_serializes_models_and_filters_none_query_params() -> None:
+    seen: dict[str, object] = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["query"] = dict(request.url.params)
+        seen["body"] = json.loads(request.content.decode("utf-8"))
+        return httpx.Response(
+            201,
+            json={
+                "id": "contact_1",
+                "phone_number": "+6281234567890",
+                "source": "manual",
+                "is_opted_out": False,
+                "tags": [],
+                "created_at": "2026-05-01T00:00:00Z",
+                "updated_at": "2026-05-01T00:00:00Z",
+            },
+        )
+
+    transport = httpx.MockTransport(handler)
+    with WazzapiClient(base_url="https://api.example.com", transport=transport) as client:
+        response = client._request(
+            "POST",
+            "/api/v1/contacts",
+            params={"limit": 10, "search": None},
+            json_body=ContactCreateRequest(phone_number="+6281234567890", name=None),
+            response_model=None,
+        )
+
+    assert seen["query"] == {"limit": "10"}
+    assert seen["body"] == {"phone_number": "+6281234567890"}
+    assert response["id"] == "contact_1"
+
+
+@pytest.mark.parametrize(
+    ("payload", "expected_message"),
+    [
+        ({"detail": "Message not found"}, "Message not found"),
+        ({"detail": [{"msg": "Invalid input"}]}, "Invalid input"),
+        ({"message": "Rate limited"}, "Rate limited"),
+    ],
+)
+def test_client_raises_api_error_with_parsed_message(payload: dict[str, object], expected_message: str) -> None:
+    def handler(_: httpx.Request) -> httpx.Response:
+        return httpx.Response(400, json=payload)
+
+    transport = httpx.MockTransport(handler)
+    with WazzapiClient(base_url="https://api.example.com", transport=transport) as client:
+        with pytest.raises(WazzapiAPIError) as exc_info:
+            client._request("GET", "/api/v1/test")
+
+    assert exc_info.value.message == expected_message
+    assert exc_info.value.status_code == 400