wazzapi 0.1.1__tar.gz → 0.2.0__tar.gz

{wazzapi-0.1.1 → wazzapi-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wazzapi
-Version: 0.1.1
+Version: 0.2.0
 Summary: Typed Python SDK for WazzAPI
 Project-URL: Homepage, https://github.com/wazzapihq/wazzapi-py
 Project-URL: API, https://api.wazzapi.com
@@ -17,6 +17,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
+Requires-Dist: cryptography<45.0,>=44.0
 Requires-Dist: httpx<1.0,>=0.28
 Requires-Dist: pydantic<3.0,>=2.11
 Description-Content-Type: text/markdown

{wazzapi-0.1.1 → wazzapi-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "wazzapi"
-version = "0.1.1"
+version = "0.2.0"
 description = "Typed Python SDK for WazzAPI"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.10"
@@ -19,6 +19,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
+  "cryptography>=44.0,<45.0",
   "httpx>=0.28,<1.0",
   "pydantic>=2.11,<3.0",
 ]
@@ -30,6 +31,7 @@ API = "https://api.wazzapi.com"
 [dependency-groups]
 dev = [
   "pytest>=8.3,<9.0",
+  "pytest-asyncio>=0.25,<1.0",
   "twine>=6.1,<7.0",
 ]
 
@@ -52,3 +54,4 @@ include = [
 [tool.pytest]
 python_files = ["test_*.py"]
 testpaths = ["tests"]
+asyncio_mode = "auto"

{wazzapi-0.1.1 → wazzapi-0.2.0}/tests/smoke_test.py

@@ -10,7 +10,7 @@ from wazzapi import (
 
 
 def main() -> None:
-    assert __version__ == "0.1.1"
+    assert __version__ == "0.2.0"
 
     client = WazzapiClient(api_key="smoke-test-token")
     try:

wazzapi-0.2.0/tests/test_groups.py

@@ -0,0 +1,285 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+
+import httpx
+import pytest
+
+from wazzapi import WazzapiClient, models
+
+
+@pytest.mark.parametrize(
+    ("call_factory", "expected_method", "expected_path", "expected_response_type", "response_json"),
+    [
+        (
+            lambda client: client.groups.list(session_name="main", limit=25),
+            "GET",
+            "/api/v1/groups",
+            models.GroupListResponse,
+            {"groups": [], "total": 0},
+        ),
+        (
+            lambda client: client.groups.get("123@g.us", session_name="main"),
+            "GET",
+            "/api/v1/groups/123@g.us",
+            models.GroupDetailResponse,
+            {"id": "123@g.us", "name": "Test Group"},
+        ),
+        (
+            lambda client: client.groups.get_participants("123@g.us", session_name="main"),
+            "GET",
+            "/api/v1/groups/123@g.us/participants",
+            models.GroupParticipantsResponse,
+            {"participants": [{"id": "6281234567890@s.whatsapp.net", "is_admin": True}]},
+        ),
+        (
+            lambda client: client.groups.create({"session_name": "main", "name": "New Group", "participants": ["6281234567890"]}),
+            "POST",
+            "/api/v1/groups/create",
+            models.CreateGroupResponseModel,
+            {"success": True, "jid": "456@g.us", "name": "New Group"},
+        ),
+        (
+            lambda client: client.groups.send_text({"session_name": "main", "group_jid": "123@g.us", "text": "hello"}),
+            "POST",
+            "/api/v1/groups/send",
+            models.SendGroupResponse,
+            {"success": True, "message_id": "msg_1", "status": "queued"},
+        ),
+        (
+            lambda client: client.groups.send_media({
+                "session_name": "main",
+                "group_jid": "123@g.us",
+                "media_url": "https://example.com/img.jpg",
+                "media_type": "image",
+            }),
+            "POST",
+            "/api/v1/groups/send/media",
+            models.SendGroupResponse,
+            {"success": True, "message_id": "msg_2", "status": "queued"},
+        ),
+        (
+            lambda client: client.groups.update_participants({
+                "session_name": "main",
+                "group_jid": "123@g.us",
+                "action": "promote",
+                "participants": ["6281234567890@s.whatsapp.net"],
+            }),
+            "POST",
+            "/api/v1/groups/participants",
+            models.GroupOperationResponseModel,
+            {"success": True, "details": "done"},
+        ),
+        (
+            lambda client: client.groups.add_participant("123@g.us", session_name="main", participant_jid="6281234567890@s.whatsapp.net"),
+            "POST",
+            "/api/v1/groups/123@g.us/participants/add",
+            models.GroupOperationResponseModel,
+            {"success": True, "details": "added"},
+        ),
+        (
+            lambda client: client.groups.remove_participant("123@g.us", session_name="main", participant_jid="6281234567890@s.whatsapp.net"),
+            "POST",
+            "/api/v1/groups/123@g.us/participants/remove",
+            models.GroupOperationResponseModel,
+            {"success": True, "details": "removed"},
+        ),
+        (
+            lambda client: client.groups.get_invite_link("123@g.us", session_name="main"),
+            "POST",
+            "/api/v1/groups/123@g.us/invite-link",
+            models.GroupInviteLinkResponseModel,
+            {"success": True, "invite_link": "https://chat.whatsapp.com/abc"},
+        ),
+        (
+            lambda client: client.groups.get_invite_info({"session_name": "main", "invite_link": "https://chat.whatsapp.com/abc"}),
+            "POST",
+            "/api/v1/groups/invite-info",
+            models.GroupInviteInfoResponseModel,
+            {"success": True, "jid": "789@g.us", "name": "Invited Group"},
+        ),
+        (
+            lambda client: client.groups.join({"session_name": "main", "invite_link": "https://chat.whatsapp.com/abc"}),
+            "POST",
+            "/api/v1/groups/join",
+            models.GroupOperationResponseModel,
+            {"success": True, "details": "joined"},
+        ),
+        (
+            lambda client: client.groups.leave("123@g.us", session_name="main"),
+            "POST",
+            "/api/v1/groups/123@g.us/leave",
+            models.GroupOperationResponseModel,
+            {"success": True, "details": "left"},
+        ),
+        (
+            lambda client: client.groups.set_name("123@g.us", {"session_name": "main", "name": "Renamed"}),
+            "POST",
+            "/api/v1/groups/123@g.us/name",
+            models.GroupOperationResponseModel,
+            {"success": True, "details": "name updated"},
+        ),
+        (
+            lambda client: client.groups.set_topic("123@g.us", {"session_name": "main", "topic": "new topic"}),
+            "POST",
+            "/api/v1/groups/123@g.us/topic",
+            models.GroupOperationResponseModel,
+            {"success": True, "details": "topic updated"},
+        ),
+        (
+            lambda client: client.groups.set_photo("123@g.us", {"session_name": "main", "image_data_uri": "data:image/png;base64,abc"}),
+            "POST",
+            "/api/v1/groups/123@g.us/photo",
+            models.GroupOperationResponseModel,
+            {"success": True, "details": "photo updated"},
+        ),
+        (
+            lambda client: client.groups.set_announce("123@g.us", {"session_name": "main", "announce": True}),
+            "POST",
+            "/api/v1/groups/123@g.us/announce",
+            models.GroupOperationResponseModel,
+            {"success": True, "details": "announce set"},
+        ),
+        (
+            lambda client: client.groups.set_locked("123@g.us", {"session_name": "main", "locked": True}),
+            "POST",
+            "/api/v1/groups/123@g.us/locked",
+            models.GroupOperationResponseModel,
+            {"success": True, "details": "locked set"},
+        ),
+        (
+            lambda client: client.groups.set_ephemeral("123@g.us", {"session_name": "main", "duration": "24h"}),
+            "POST",
+            "/api/v1/groups/123@g.us/ephemeral",
+            models.GroupOperationResponseModel,
+            {"success": True, "details": "ephemeral set"},
+        ),
+    ],
+)
+def test_groups_methods_hit_expected_routes(
+    call_factory: Callable[[WazzapiClient], object],
+    expected_method: str,
+    expected_path: str,
+    expected_response_type: type[object],
+    response_json: dict[str, object],
+) -> None:
+    seen: dict[str, object] = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["method"] = request.method
+        seen["path"] = request.url.path
+        seen["query"] = dict(request.url.params)
+        seen["body"] = json.loads(request.content.decode("utf-8")) if request.content else None
+        status_code = 201 if request.method == "POST" else 200
+        return httpx.Response(status_code, json=response_json)
+
+    transport = httpx.MockTransport(handler)
+    with WazzapiClient(base_url="https://api.example.com", transport=transport) as client:
+        result = call_factory(client)
+
+    assert seen["method"] == expected_method
+    assert seen["path"] == expected_path
+    assert isinstance(result, expected_response_type)
+
+
+def test_groups_remove_photo_returns_operation_response() -> None:
+    seen: dict[str, object] = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["method"] = request.method
+        seen["path"] = request.url.path
+        seen["query"] = dict(request.url.params)
+        return httpx.Response(
+            200,
+            json={"success": True, "details": "photo removed"},
+        )
+
+    transport = httpx.MockTransport(handler)
+    with WazzapiClient(base_url="https://api.example.com", transport=transport) as client:
+        result = client.groups.remove_photo("123@g.us", session_name="main")
+
+    assert seen["method"] == "DELETE"
+    assert seen["path"] == "/api/v1/groups/123@g.us/photo"
+    assert seen["query"] == {"session_name": "main"}
+    assert isinstance(result, models.GroupOperationResponseModel)
+    assert result.success is True
+
+
+def test_groups_list_sends_query_params() -> None:
+    seen: dict[str, object] = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["query"] = dict(request.url.params)
+        return httpx.Response(200, json={"groups": [], "total": 0})
+
+    transport = httpx.MockTransport(handler)
+    with WazzapiClient(base_url="https://api.example.com", transport=transport) as client:
+        client.groups.list(session_name="main", limit=10, offset=5)
+
+    assert seen["query"] == {"session_name": "main", "limit": "10", "offset": "5"}
+
+
+def test_groups_get_sends_session_name_query() -> None:
+    seen: dict[str, object] = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["query"] = dict(request.url.params)
+        return httpx.Response(200, json={"id": "123@g.us", "name": "Test"})
+
+    transport = httpx.MockTransport(handler)
+    with WazzapiClient(base_url="https://api.example.com", transport=transport) as client:
+        client.groups.get("123@g.us", session_name="main")
+
+    assert seen["query"] == {"session_name": "main"}
+
+
+def test_groups_add_participant_sends_query_params() -> None:
+    seen: dict[str, object] = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["query"] = dict(request.url.params)
+        return httpx.Response(200, json={"success": True, "details": "added"})
+
+    transport = httpx.MockTransport(handler)
+    with WazzapiClient(base_url="https://api.example.com", transport=transport) as client:
+        client.groups.add_participant(
+            "123@g.us",
+            session_name="main",
+            participant_jid="6281234567890@s.whatsapp.net",
+        )
+
+    assert seen["query"] == {
+        "session_name": "main",
+        "participant_jid": "6281234567890@s.whatsapp.net",
+    }
+
+
+def test_groups_models_are_importable() -> None:
+    from wazzapi.models import (
+        CreateGroupRequest,
+        CreateGroupResponseModel,
+        GroupDetailResponse,
+        GroupInviteInfoResponseModel,
+        GroupInviteLinkResponseModel,
+        GroupListItem,
+        GroupListResponse,
+        GroupOperationResponseModel,
+        GroupParticipantItem,
+        GroupParticipantsResponse,
+        InviteInfoRequest,
+        JoinGroupRequest,
+        SendGroupMediaRequest,
+        SendGroupResponse,
+        SendGroupTextRequest,
+        SetGroupAnnounceRequest,
+        SetGroupEphemeralRequest,
+        SetGroupLockedRequest,
+        SetGroupNameRequest,
+        SetGroupPhotoRequest,
+        SetGroupTopicRequest,
+        UpdateParticipantsRequest,
+    )
+
+    assert GroupListItem is not None
+    assert CreateGroupResponseModel is not None

wazzapi-0.2.0/tests/test_media.py

@@ -0,0 +1,170 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+from unittest.mock import AsyncMock
+
+import httpx
+import pytest
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives import hmac as crypto_hmac
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
+from wazzapi.errors import WazzapiMediaError
+from wazzapi.media import _decrypt_wa_media, _media_info_bytes, download_media
+
+PLAINTEXT = b"hello world this is a test file"
+MIMETYPE = "application/pdf"
+_MEDIA_KEY_BYTES = b"\x00" * 32
+MEDIA_KEY = base64.b64encode(_MEDIA_KEY_BYTES).decode()
+
+
+def _encrypt_wa_media(plaintext: bytes, media_key: bytes, mimetype: str) -> bytes:
+    info = _media_info_bytes(mimetype)
+    hkdf = HKDF(algorithm=hashes.SHA256(), length=112, salt=None, info=info)
+    expanded = hkdf.derive(media_key)
+    iv = expanded[:16]
+    aes_key = expanded[16:48]
+    mac_key = expanded[48:80]
+
+    pad_len = 16 - (len(plaintext) % 16)
+    padded = plaintext + bytes([pad_len] * pad_len)
+
+    cipher = Cipher(algorithms.AES(aes_key), modes.CBC(iv))
+    encryptor = cipher.encryptor()
+    ciphertext = encryptor.update(padded) + encryptor.finalize()
+
+    h = crypto_hmac.HMAC(mac_key, hashes.SHA256())
+    h.update(iv + ciphertext)
+    mac = h.finalize()[:10]
+
+    return ciphertext + mac
+
+
+ENC_BLOB = _encrypt_wa_media(PLAINTEXT, _MEDIA_KEY_BYTES, MIMETYPE)
+FILE_SHA256 = base64.b64encode(hashlib.sha256(PLAINTEXT).digest()).decode()
+ENC_SHA256 = base64.b64encode(hashlib.sha256(ENC_BLOB).digest()).decode()
+
+
+def _mock_client(enc_data: bytes, status_code: int = 200) -> AsyncMock:
+    mock_client = AsyncMock(spec=httpx.AsyncClient)
+    request = httpx.Request("GET", "https://cdn.example.com/file")
+    mock_client.get.return_value = httpx.Response(status_code, content=enc_data, request=request)
+    mock_client.aclose = AsyncMock()
+    return mock_client
+
+
+def test_decrypt_wa_media_success() -> None:
+    result = _decrypt_wa_media(MEDIA_KEY, ENC_BLOB, MIMETYPE)
+    assert result == PLAINTEXT
+
+
+def test_decrypt_wa_media_mac_failure() -> None:
+    bad_blob = ENC_BLOB[:-10] + b"\x00" * 10
+    with pytest.raises(WazzapiMediaError, match="MAC verification failed"):
+        _decrypt_wa_media(MEDIA_KEY, bad_blob, MIMETYPE)
+
+
+def test_decrypt_wa_media_short_data() -> None:
+    with pytest.raises(WazzapiMediaError, match="Encrypted data too short"):
+        _decrypt_wa_media(MEDIA_KEY, b"123", MIMETYPE)
+
+
+def test_decrypt_wa_media_bad_base64_key() -> None:
+    with pytest.raises(WazzapiMediaError, match="Invalid media_key base64"):
+        _decrypt_wa_media("not-valid-b64!!!", ENC_BLOB, MIMETYPE)
+
+
+def test_media_info_bytes_mapping() -> None:
+    assert _media_info_bytes("image/jpeg") == b"WhatsApp Image Keys"
+    assert _media_info_bytes("video/mp4") == b"WhatsApp Video Keys"
+    assert _media_info_bytes("audio/ogg") == b"WhatsApp Audio Keys"
+    assert _media_info_bytes("application/pdf") == b"WhatsApp Document Keys"
+
+
+@pytest.mark.asyncio
+async def test_download_media_success() -> None:
+    mock_client = _mock_client(ENC_BLOB)
+    result = await download_media(
+        url="https://cdn.example.com/file",
+        media_key=MEDIA_KEY,
+        mimetype=MIMETYPE,
+        file_sha256=FILE_SHA256,
+        file_enc_sha256=ENC_SHA256,
+        file_name="test.pdf",
+        http_client=mock_client,
+    )
+    assert result.content == PLAINTEXT
+    assert result.mimetype == MIMETYPE
+    assert result.file_name == "test.pdf"
+    assert result.file_size == len(PLAINTEXT)
+    mock_client.get.assert_awaited_once_with("https://cdn.example.com/file")
+    mock_client.aclose.assert_not_awaited()
+
+
+@pytest.mark.asyncio
+async def test_download_media_http_error() -> None:
+    mock_client = _mock_client(b"not found", status_code=404)
+    with pytest.raises(WazzapiMediaError, match="CDN fetch failed: 404"):
+        await download_media(
+            url="https://cdn.example.com/file",
+            media_key=MEDIA_KEY,
+            mimetype=MIMETYPE,
+            http_client=mock_client,
+        )
+
+
+@pytest.mark.asyncio
+async def test_download_media_network_error() -> None:
+    mock_client = AsyncMock(spec=httpx.AsyncClient)
+    mock_client.get.side_effect = httpx.RequestError(
+        "connection refused", request=httpx.Request("GET", "https://cdn.example.com/file")
+    )
+    mock_client.aclose = AsyncMock()
+    with pytest.raises(WazzapiMediaError, match="CDN fetch error:"):
+        await download_media(
+            url="https://cdn.example.com/file",
+            media_key=MEDIA_KEY,
+            mimetype=MIMETYPE,
+            http_client=mock_client,
+        )
+
+
+@pytest.mark.asyncio
+async def test_download_media_enc_sha_mismatch() -> None:
+    mock_client = _mock_client(ENC_BLOB)
+    with pytest.raises(WazzapiMediaError, match="file_enc_sha256 mismatch"):
+        await download_media(
+            url="https://cdn.example.com/file",
+            media_key=MEDIA_KEY,
+            mimetype=MIMETYPE,
+            file_enc_sha256=base64.b64encode(hashlib.sha256(b"wrong").digest()).decode(),
+            http_client=mock_client,
+        )
+
+
+@pytest.mark.asyncio
+async def test_download_media_plain_sha_mismatch() -> None:
+    mock_client = _mock_client(ENC_BLOB)
+    with pytest.raises(WazzapiMediaError, match="file_sha256 mismatch after decryption"):
+        await download_media(
+            url="https://cdn.example.com/file",
+            media_key=MEDIA_KEY,
+            mimetype=MIMETYPE,
+            file_sha256=base64.b64encode(hashlib.sha256(b"wrong").digest()).decode(),
+            http_client=mock_client,
+        )
+
+
+@pytest.mark.asyncio
+async def test_download_media_no_checksums() -> None:
+    mock_client = _mock_client(ENC_BLOB)
+    result = await download_media(
+        url="https://cdn.example.com/file",
+        media_key=MEDIA_KEY,
+        mimetype=MIMETYPE,
+        http_client=mock_client,
+    )
+    assert result.content == PLAINTEXT
+    assert result.file_name == "media"

{wazzapi-0.1.1 → wazzapi-0.2.0}/wazzapi/__init__.py

@@ -1,6 +1,7 @@
 from . import models
 from .client import WazzapiClient
-from .errors import WazzapiAPIError, WazzapiError
+from .errors import WazzapiAPIError, WazzapiError, WazzapiMediaError
+from .media import MediaDownloadResult, download_media
 from .models import *
 from .webhooks import (
     EVENT_HEADER,
@@ -15,18 +16,21 @@ from .webhooks import (
     verify_webhook_signature,
 )
 
-__version__ = "0.1.1"
+__version__ = "0.2.0"
 
 __all__ = [
     "EVENT_HEADER",
     "EVENT_ID_HEADER",
     "SIGNATURE_HEADER",
     "__version__",
+    "download_media",
     "generate_webhook_signature",
     "parse_webhook",
+    "MediaDownloadResult",
     "WazzapiAPIError",
     "WazzapiClient",
     "WazzapiError",
+    "WazzapiMediaError",
     "WazzapiWebhookError",
     "WazzapiWebhookParseError",
     "WazzapiWebhookVerificationError",

{wazzapi-0.1.1 → wazzapi-0.2.0}/wazzapi/client.py

@@ -7,7 +7,7 @@ import httpx
 from pydantic import BaseModel, TypeAdapter
 
 from .errors import WazzapiAPIError
-from .resources import ContactsResource, MessagesResource, TemplatesResource
+from .resources import ContactsResource, GroupsResource, MessagesResource, TemplatesResource
 
 DEFAULT_BASE_URL = "https://api.wazzapi.com"
 
@@ -39,6 +39,7 @@ class WazzapiClient:
         )
 
         self.contacts = ContactsResource(self)
+        self.groups = GroupsResource(self)
         self.messages = MessagesResource(self)
         self.templates = TemplatesResource(self)
 

{wazzapi-0.1.1 → wazzapi-0.2.0}/wazzapi/errors.py

@@ -58,3 +58,7 @@ class WazzapiAPIError(WazzapiError):
             details=details,
             response_text=response.text,
         )
+
+
+class WazzapiMediaError(WazzapiError):
+    """Raised when media download or decryption fails."""

wazzapi-0.2.0/wazzapi/media.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import logging
+
+import httpx
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives import hmac as crypto_hmac
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
+from .errors import WazzapiMediaError
+from .models.media import MediaDownloadResult
+
+logger = logging.getLogger("wazzapi.media")
+
+# https://github.com/tgalal/python-axolotl/wiki/WhatsApp-media-encryption
+_WA_MEDIA_INFO: dict[str, bytes] = {
+    "image": b"WhatsApp Image Keys",
+    "video": b"WhatsApp Video Keys",
+    "audio": b"WhatsApp Audio Keys",
+    "ptt": b"WhatsApp Audio Keys",
+    "document": b"WhatsApp Document Keys",
+    "sticker": b"WhatsApp Image Keys",
+    "history": b"WhatsApp History Keys",
+}
+
+
+def _media_info_bytes(mimetype: str) -> bytes:
+    mt = mimetype.lower()
+    if mt.startswith("image/"):
+        return _WA_MEDIA_INFO["image"]
+    if mt.startswith("video/"):
+        return _WA_MEDIA_INFO["video"]
+    if mt.startswith("audio/"):
+        return _WA_MEDIA_INFO["audio"]
+    return _WA_MEDIA_INFO["document"]
+
+
+def _decrypt_wa_media(media_key_b64: str, enc_data: bytes, mimetype: str) -> bytes:
+    if len(enc_data) < 10:
+        raise WazzapiMediaError("Encrypted data too short")
+
+    try:
+        media_key = base64.b64decode(media_key_b64)
+    except Exception as exc:
+        raise WazzapiMediaError("Invalid media_key base64") from exc
+
+    info = _media_info_bytes(mimetype)
+
+    hkdf = HKDF(algorithm=hashes.SHA256(), length=112, salt=None, info=info)
+    expanded = hkdf.derive(media_key)
+
+    iv = expanded[:16]
+    aes_key = expanded[16:48]
+    mac_key = expanded[48:80]
+
+    ciphertext = enc_data[:-10]
+    mac = enc_data[-10:]
+
+    h = crypto_hmac.HMAC(mac_key, hashes.SHA256())
+    h.update(iv + ciphertext)
+    computed_mac = h.finalize()[:10]
+    if computed_mac != mac:
+        raise WazzapiMediaError(
+            "MAC verification failed — media may be corrupted or mediaKey is wrong"
+        )
+
+    cipher = Cipher(algorithms.AES(aes_key), modes.CBC(iv))
+    decryptor = cipher.decryptor()
+    plaintext_padded = decryptor.update(ciphertext) + decryptor.finalize()
+
+    if not plaintext_padded:
+        raise WazzapiMediaError("Decrypted plaintext is empty")
+
+    pad_len = plaintext_padded[-1]
+    if pad_len > 16 or pad_len == 0 or pad_len > len(plaintext_padded):
+        raise WazzapiMediaError("Invalid PKCS7 padding")
+    if any(b != pad_len for b in plaintext_padded[-pad_len:]):
+        raise WazzapiMediaError("Invalid PKCS7 padding")
+
+    return plaintext_padded[:-pad_len]
+
+
+async def download_media(
+    url: str,
+    media_key: str,
+    mimetype: str,
+    *,
+    file_sha256: str | None = None,
+    file_enc_sha256: str | None = None,
+    file_name: str | None = None,
+    http_client: httpx.AsyncClient | None = None,
+) -> MediaDownloadResult:
+    logger.info("Downloading media url=%s mimetype=%s", url, mimetype)
+
+    client = http_client or httpx.AsyncClient(follow_redirects=True, timeout=30)
+    owns_client = http_client is None
+
+    try:
+        resp = await client.get(url)
+        resp.raise_for_status()
+    except httpx.HTTPStatusError as exc:
+        logger.error("CDN fetch failed: %s", exc)
+        raise WazzapiMediaError(f"CDN fetch failed: {exc.response.status_code}") from exc
+    except httpx.RequestError as exc:
+        logger.error("CDN network error: %s", exc)
+        raise WazzapiMediaError(f"CDN fetch error: {exc}") from exc
+    finally:
+        if owns_client:
+            await client.aclose()
+
+    enc_data = resp.content
+
+    if file_enc_sha256:
+        expected_enc = base64.b64decode(file_enc_sha256)
+        actual_enc = hashlib.sha256(enc_data).digest()
+        if actual_enc != expected_enc:
+            raise WazzapiMediaError(
+                f"file_enc_sha256 mismatch: CDN returned wrong data (got {len(enc_data)} bytes)"
+            )
+
+    plaintext = _decrypt_wa_media(media_key, enc_data, mimetype)
+
+    if file_sha256:
+        expected = base64.b64decode(file_sha256)
+        actual = hashlib.sha256(plaintext).digest()
+        if actual != expected:
+            raise WazzapiMediaError("file_sha256 mismatch after decryption")
+
+    result = MediaDownloadResult(
+        content=plaintext,
+        mimetype=mimetype,
+        file_name=file_name or "media",
+        file_size=len(plaintext),
+    )
+    logger.info("Media download success url=%s size=%d", url, result.file_size)
+    return result
+
+
+__all__ = [
+    "MediaDownloadResult",
+    "_decrypt_wa_media",
+    "_media_info_bytes",
+    "download_media",
+]

{wazzapi-0.1.1 → wazzapi-0.2.0}/wazzapi/models/__init__.py

@@ -1,6 +1,10 @@
 from .base import WazzapiModel
 from .contacts import *
 from .contacts import __all__ as contacts_all
+from .groups import *
+from .groups import __all__ as groups_all
+from .media import *
+from .media import __all__ as media_all
 from .messages import *
 from .messages import __all__ as messages_all
 from .templates import *
@@ -8,4 +12,4 @@ from .templates import __all__ as templates_all
 from .webhooks import *
 from .webhooks import __all__ as webhooks_all
 
-__all__ = ["WazzapiModel", *contacts_all, *messages_all, *templates_all, *webhooks_all]
+__all__ = ["WazzapiModel", *contacts_all, *groups_all, *media_all, *messages_all, *templates_all, *webhooks_all]

wazzapi-0.2.0/wazzapi/models/groups.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from .base import WazzapiModel
+
+
+class GroupListItem(WazzapiModel):
+    id: str
+    name: str
+    description: str | None = None
+    owner: str | None = None
+    participants_count: int = 0
+
+
+class GroupListResponse(WazzapiModel):
+    groups: list[GroupListItem]
+    total: int
+
+
+class GroupDetailResponse(WazzapiModel):
+    id: str
+    name: str
+    description: str | None = None
+    owner: str | None = None
+    participants_count: int = 0
+
+
+class GroupParticipantItem(WazzapiModel):
+    id: str
+    is_admin: bool = False
+    is_super_admin: bool = False
+
+
+class GroupParticipantsResponse(WazzapiModel):
+    participants: list[GroupParticipantItem]
+
+
+class GroupOperationResponseModel(WazzapiModel):
+    success: bool
+    details: str
+
+
+class CreateGroupRequest(WazzapiModel):
+    session_name: str
+    name: str
+    participants: list[str]
+
+
+class CreateGroupResponseModel(WazzapiModel):
+    success: bool
+    jid: str
+    name: str
+    owner_jid: str | None = None
+    group_created: str | None = None
+
+
+class SendGroupTextRequest(WazzapiModel):
+    session_name: str
+    group_jid: str
+    text: str
+    message_id: str | None = None
+
+
+class SendGroupMediaRequest(WazzapiModel):
+    session_name: str
+    group_jid: str
+    media_url: str
+    media_type: str
+    caption: str | None = None
+    filename: str | None = None
+
+
+class SendGroupResponse(WazzapiModel):
+    success: bool
+    message_id: str
+    status: str
+    run_id: str | None = None
+
+
+class UpdateParticipantsRequest(WazzapiModel):
+    session_name: str
+    group_jid: str
+    action: str
+    participants: list[str]
+
+
+class GroupInviteLinkResponseModel(WazzapiModel):
+    success: bool
+    invite_link: str
+
+
+class GroupInviteInfoResponseModel(WazzapiModel):
+    success: bool
+    jid: str
+    name: str
+    participants: int = 0
+    owner_jid: str | None = None
+
+
+class InviteInfoRequest(WazzapiModel):
+    session_name: str
+    invite_link: str
+
+
+class JoinGroupRequest(WazzapiModel):
+    session_name: str
+    invite_link: str
+
+
+class SetGroupNameRequest(WazzapiModel):
+    session_name: str
+    name: str
+
+
+class SetGroupTopicRequest(WazzapiModel):
+    session_name: str
+    topic: str
+
+
+class SetGroupPhotoRequest(WazzapiModel):
+    session_name: str
+    image_data_uri: str
+
+
+class SetGroupAnnounceRequest(WazzapiModel):
+    session_name: str
+    announce: bool
+
+
+class SetGroupLockedRequest(WazzapiModel):
+    session_name: str
+    locked: bool
+
+
+class SetGroupEphemeralRequest(WazzapiModel):
+    session_name: str
+    duration: str
+
+
+__all__ = [
+    "CreateGroupRequest",
+    "CreateGroupResponseModel",
+    "GroupDetailResponse",
+    "GroupInviteInfoResponseModel",
+    "GroupInviteLinkResponseModel",
+    "GroupListItem",
+    "GroupListResponse",
+    "GroupOperationResponseModel",
+    "GroupParticipantItem",
+    "GroupParticipantsResponse",
+    "InviteInfoRequest",
+    "JoinGroupRequest",
+    "SendGroupMediaRequest",
+    "SendGroupResponse",
+    "SendGroupTextRequest",
+    "SetGroupAnnounceRequest",
+    "SetGroupEphemeralRequest",
+    "SetGroupLockedRequest",
+    "SetGroupNameRequest",
+    "SetGroupPhotoRequest",
+    "SetGroupTopicRequest",
+    "UpdateParticipantsRequest",
+]

wazzapi-0.2.0/wazzapi/models/media.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from .base import WazzapiModel
+
+
+class MediaDownloadResult(WazzapiModel):
+    content: bytes
+    mimetype: str
+    file_name: str
+    file_size: int
+
+
+__all__ = ["MediaDownloadResult"]

wazzapi-0.2.0/wazzapi/resources/__init__.py

@@ -0,0 +1,6 @@
+from .contacts import ContactsResource
+from .groups import GroupsResource
+from .messages import MessagesResource
+from .templates import TemplatesResource
+
+__all__ = ["ContactsResource", "GroupsResource", "MessagesResource", "TemplatesResource"]

wazzapi-0.2.0/wazzapi/resources/groups.py

@@ -0,0 +1,266 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .. import models
+from .base import BaseResource
+
+
+class GroupsResource(BaseResource):
+    def list(
+        self,
+        *,
+        session_name: str,
+        limit: int | None = None,
+        offset: int | None = None,
+    ) -> models.GroupListResponse:
+        return self._client._request(
+            "GET",
+            "/api/v1/groups",
+            params={
+                "session_name": session_name,
+                "limit": limit,
+                "offset": offset,
+            },
+            response_model=models.GroupListResponse,
+        )
+
+    def get(
+        self,
+        group_jid: str,
+        *,
+        session_name: str,
+    ) -> models.GroupDetailResponse:
+        return self._client._request(
+            "GET",
+            f"/api/v1/groups/{group_jid}",
+            params={"session_name": session_name},
+            response_model=models.GroupDetailResponse,
+        )
+
+    def get_participants(
+        self,
+        group_jid: str,
+        *,
+        session_name: str,
+    ) -> models.GroupParticipantsResponse:
+        return self._client._request(
+            "GET",
+            f"/api/v1/groups/{group_jid}/participants",
+            params={"session_name": session_name},
+            response_model=models.GroupParticipantsResponse,
+        )
+
+    def create(
+        self,
+        payload: models.CreateGroupRequest | dict[str, Any],
+    ) -> models.CreateGroupResponseModel:
+        return self._client._request(
+            "POST",
+            "/api/v1/groups/create",
+            json_body=payload,
+            response_model=models.CreateGroupResponseModel,
+        )
+
+    def send_text(
+        self,
+        payload: models.SendGroupTextRequest | dict[str, Any],
+    ) -> models.SendGroupResponse:
+        return self._client._request(
+            "POST",
+            "/api/v1/groups/send",
+            json_body=payload,
+            response_model=models.SendGroupResponse,
+        )
+
+    def send_media(
+        self,
+        payload: models.SendGroupMediaRequest | dict[str, Any],
+    ) -> models.SendGroupResponse:
+        return self._client._request(
+            "POST",
+            "/api/v1/groups/send/media",
+            json_body=payload,
+            response_model=models.SendGroupResponse,
+        )
+
+    def update_participants(
+        self,
+        payload: models.UpdateParticipantsRequest | dict[str, Any],
+    ) -> models.GroupOperationResponseModel:
+        return self._client._request(
+            "POST",
+            "/api/v1/groups/participants",
+            json_body=payload,
+            response_model=models.GroupOperationResponseModel,
+        )
+
+    def add_participant(
+        self,
+        group_jid: str,
+        *,
+        session_name: str,
+        participant_jid: str,
+    ) -> models.GroupOperationResponseModel:
+        return self._client._request(
+            "POST",
+            f"/api/v1/groups/{group_jid}/participants/add",
+            params={
+                "session_name": session_name,
+                "participant_jid": participant_jid,
+            },
+            response_model=models.GroupOperationResponseModel,
+        )
+
+    def remove_participant(
+        self,
+        group_jid: str,
+        *,
+        session_name: str,
+        participant_jid: str,
+    ) -> models.GroupOperationResponseModel:
+        return self._client._request(
+            "POST",
+            f"/api/v1/groups/{group_jid}/participants/remove",
+            params={
+                "session_name": session_name,
+                "participant_jid": participant_jid,
+            },
+            response_model=models.GroupOperationResponseModel,
+        )
+
+    def get_invite_link(
+        self,
+        group_jid: str,
+        *,
+        session_name: str,
+    ) -> models.GroupInviteLinkResponseModel:
+        return self._client._request(
+            "POST",
+            f"/api/v1/groups/{group_jid}/invite-link",
+            params={"session_name": session_name},
+            response_model=models.GroupInviteLinkResponseModel,
+        )
+
+    def get_invite_info(
+        self,
+        payload: models.InviteInfoRequest | dict[str, Any],
+    ) -> models.GroupInviteInfoResponseModel:
+        return self._client._request(
+            "POST",
+            "/api/v1/groups/invite-info",
+            json_body=payload,
+            response_model=models.GroupInviteInfoResponseModel,
+        )
+
+    def join(
+        self,
+        payload: models.JoinGroupRequest | dict[str, Any],
+    ) -> models.GroupOperationResponseModel:
+        return self._client._request(
+            "POST",
+            "/api/v1/groups/join",
+            json_body=payload,
+            response_model=models.GroupOperationResponseModel,
+        )
+
+    def leave(
+        self,
+        group_jid: str,
+        *,
+        session_name: str,
+    ) -> models.GroupOperationResponseModel:
+        return self._client._request(
+            "POST",
+            f"/api/v1/groups/{group_jid}/leave",
+            params={"session_name": session_name},
+            response_model=models.GroupOperationResponseModel,
+        )
+
+    def set_name(
+        self,
+        group_jid: str,
+        payload: models.SetGroupNameRequest | dict[str, Any],
+    ) -> models.GroupOperationResponseModel:
+        return self._client._request(
+            "POST",
+            f"/api/v1/groups/{group_jid}/name",
+            json_body=payload,
+            response_model=models.GroupOperationResponseModel,
+        )
+
+    def set_topic(
+        self,
+        group_jid: str,
+        payload: models.SetGroupTopicRequest | dict[str, Any],
+    ) -> models.GroupOperationResponseModel:
+        return self._client._request(
+            "POST",
+            f"/api/v1/groups/{group_jid}/topic",
+            json_body=payload,
+            response_model=models.GroupOperationResponseModel,
+        )
+
+    def set_photo(
+        self,
+        group_jid: str,
+        payload: models.SetGroupPhotoRequest | dict[str, Any],
+    ) -> models.GroupOperationResponseModel:
+        return self._client._request(
+            "POST",
+            f"/api/v1/groups/{group_jid}/photo",
+            json_body=payload,
+            response_model=models.GroupOperationResponseModel,
+        )
+
+    def remove_photo(
+        self,
+        group_jid: str,
+        *,
+        session_name: str,
+    ) -> models.GroupOperationResponseModel:
+        return self._client._request(
+            "DELETE",
+            f"/api/v1/groups/{group_jid}/photo",
+            params={"session_name": session_name},
+            response_model=models.GroupOperationResponseModel,
+        )
+
+    def set_announce(
+        self,
+        group_jid: str,
+        payload: models.SetGroupAnnounceRequest | dict[str, Any],
+    ) -> models.GroupOperationResponseModel:
+        return self._client._request(
+            "POST",
+            f"/api/v1/groups/{group_jid}/announce",
+            json_body=payload,
+            response_model=models.GroupOperationResponseModel,
+        )
+
+    def set_locked(
+        self,
+        group_jid: str,
+        payload: models.SetGroupLockedRequest | dict[str, Any],
+    ) -> models.GroupOperationResponseModel:
+        return self._client._request(
+            "POST",
+            f"/api/v1/groups/{group_jid}/locked",
+            json_body=payload,
+            response_model=models.GroupOperationResponseModel,
+        )
+
+    def set_ephemeral(
+        self,
+        group_jid: str,
+        payload: models.SetGroupEphemeralRequest | dict[str, Any],
+    ) -> models.GroupOperationResponseModel:
+        return self._client._request(
+            "POST",
+            f"/api/v1/groups/{group_jid}/ephemeral",
+            json_body=payload,
+            response_model=models.GroupOperationResponseModel,
+        )
+
+
+__all__ = ["GroupsResource"]

wazzapi-0.1.1/wazzapi/resources/__init__.py

@@ -1,5 +0,0 @@
-from .contacts import ContactsResource
-from .messages import MessagesResource
-from .templates import TemplatesResource
-
-__all__ = ["ContactsResource", "MessagesResource", "TemplatesResource"]