wazzapi 0.1.0__py3-none-any.whl

wazzapi/__init__.py

@@ -0,0 +1,36 @@
+from . import models
+from .client import WazzapiClient
+from .errors import WazzapiAPIError, WazzapiError
+from .models import *
+from .webhooks import (
+    EVENT_HEADER,
+    EVENT_ID_HEADER,
+    SIGNATURE_HEADER,
+    WebhookHandler,
+    WazzapiWebhookError,
+    WazzapiWebhookParseError,
+    WazzapiWebhookVerificationError,
+    generate_webhook_signature,
+    parse_webhook,
+    verify_webhook_signature,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "EVENT_HEADER",
+    "EVENT_ID_HEADER",
+    "SIGNATURE_HEADER",
+    "__version__",
+    "generate_webhook_signature",
+    "parse_webhook",
+    "WazzapiAPIError",
+    "WazzapiClient",
+    "WazzapiError",
+    "WazzapiWebhookError",
+    "WazzapiWebhookParseError",
+    "WazzapiWebhookVerificationError",
+    "verify_webhook_signature",
+    "WebhookHandler",
+    "models",
+] + models.__all__

wazzapi/client.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+import httpx
+from pydantic import BaseModel, TypeAdapter
+
+from .errors import WazzapiAPIError
+from .resources import ContactsResource, MessagesResource, TemplatesResource
+
+DEFAULT_BASE_URL = "https://api.wazzapi.com"
+
+
+class WazzapiClient:
+    """Synchronous client for the WazzAPI API."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        api_key: str | None = None,
+        timeout: float = 30.0,
+        headers: Mapping[str, str] | None = None,
+        client: httpx.Client | None = None,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        base_headers = self._build_headers(
+            api_key=api_key,
+            headers=headers,
+        )
+
+        self._owns_client = client is None
+        self._client = client or httpx.Client(
+            base_url=base_url.rstrip("/"),
+            timeout=timeout,
+            headers=base_headers,
+            transport=transport,
+        )
+
+        self.contacts = ContactsResource(self)
+        self.messages = MessagesResource(self)
+        self.templates = TemplatesResource(self)
+
+    @staticmethod
+    def _build_headers(
+        *,
+        api_key: str | None,
+        headers: Mapping[str, str] | None,
+    ) -> dict[str, str]:
+        merged_headers: dict[str, str] = {
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+        }
+
+        if headers:
+            merged_headers.update(dict(headers))
+
+        if api_key:
+            merged_headers["Authorization"] = (
+                api_key if api_key.lower().startswith("bearer ") else f"Bearer {api_key}"
+            )
+
+        return merged_headers
+
+    @property
+    def http(self) -> httpx.Client:
+        return self._client
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> "WazzapiClient":
+        return self
+
+    def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        self.close()
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json_body: BaseModel | Mapping[str, Any] | None = None,
+        response_model: Any | None = None,
+    ) -> Any:
+        response = self._client.request(
+            method,
+            path,
+            params=self._filter_none(params),
+            json=self._normalize_body(json_body),
+        )
+
+        if response.status_code >= 400:
+            raise WazzapiAPIError.from_response(response)
+
+        if response.status_code == 204 or not response.content:
+            return None
+
+        if response_model is None:
+            return response.json()
+
+        payload = response.json()
+        return TypeAdapter(response_model).validate_python(payload)
+
+    @staticmethod
+    def _filter_none(data: Mapping[str, Any] | None) -> dict[str, Any] | None:
+        if data is None:
+            return None
+        return {key: value for key, value in data.items() if value is not None}
+
+    @staticmethod
+    def _normalize_body(data: BaseModel | Mapping[str, Any] | None) -> dict[str, Any] | None:
+        if data is None:
+            return None
+        if isinstance(data, BaseModel):
+            return data.model_dump(mode="json", exclude_none=True)
+        return {key: value for key, value in data.items() if value is not None}

wazzapi/errors.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+class WazzapiError(Exception):
+    """Base exception for the WazzAPI SDK."""
+
+
+class WazzapiAPIError(WazzapiError):
+    """Raised when the WazzAPI API returns a non-success response."""
+
+    def __init__(
+        self,
+        status_code: int,
+        message: str,
+        *,
+        details: Any | None = None,
+        response_text: str | None = None,
+    ) -> None:
+        super().__init__(f"WazzAPI API error {status_code}: {message}")
+        self.status_code = status_code
+        self.message = message
+        self.details = details
+        self.response_text = response_text
+
+    @classmethod
+    def from_response(cls, response: httpx.Response) -> "WazzapiAPIError":
+        details: Any | None = None
+        message = response.reason_phrase or "Request failed"
+
+        try:
+            payload = response.json()
+        except ValueError:
+            payload = None
+
+        if isinstance(payload, dict):
+            details = payload.get("detail", payload)
+            if isinstance(details, str):
+                message = details
+            elif isinstance(details, list) and details:
+                first_item = details[0]
+                if isinstance(first_item, dict):
+                    message = first_item.get("msg") or message
+                else:
+                    message = str(first_item)
+            elif payload.get("message"):
+                message = str(payload["message"])
+        elif payload is not None:
+            details = payload
+            message = str(payload)
+
+        return cls(
+            response.status_code,
+            message,
+            details=details,
+            response_text=response.text,
+        )

wazzapi/models/__init__.py

@@ -0,0 +1,11 @@
+from .base import WazzapiModel
+from .contacts import *
+from .contacts import __all__ as contacts_all
+from .messages import *
+from .messages import __all__ as messages_all
+from .templates import *
+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]

wazzapi/models/base.py

@@ -0,0 +1,10 @@
+from pydantic import BaseModel, ConfigDict
+
+
+class WazzapiModel(BaseModel):
+    """Base model for SDK request and response payloads."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+
+__all__ = ["WazzapiModel"]

wazzapi/models/contacts.py

@@ -0,0 +1,204 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import Field
+
+from .base import WazzapiModel
+
+
+class AddToGroupRequest(WazzapiModel):
+    contact_ids: list[str]
+
+
+class AddToGroupResponse(WazzapiModel):
+    success: bool
+    added: int
+    member_count: int
+
+
+class BulkDeleteRequest(WazzapiModel):
+    contact_ids: list[str]
+
+
+class BulkDeleteResponse(WazzapiModel):
+    success: bool
+    deleted: int
+
+
+class CSVExportResponse(WazzapiModel):
+    csv_data: str
+    count: int
+    filename: str
+
+
+class CSVImportRequest(WazzapiModel):
+    csv_content: str
+    skip_duplicates: bool | None = None
+
+
+class CSVImportResponse(WazzapiModel):
+    success: bool
+    imported: int
+    updated: int
+    errors: list[str] = Field(default_factory=list)
+    rows_processed: int
+
+
+class ContactCreateRequest(WazzapiModel):
+    phone_number: str
+    name: str | None = None
+    email: str | None = None
+    tags: list[str] | None = None
+    custom_fields: dict[str, Any] | None = None
+
+
+class ContactGroupCreateRequest(WazzapiModel):
+    name: str
+    description: str | None = None
+
+
+class ContactGroupItem(WazzapiModel):
+    id: str
+    name: str
+    description: str | None = None
+    member_count: int
+    created_at: datetime
+
+
+class ContactGroupListResponse(WazzapiModel):
+    groups: list[ContactGroupItem]
+    total: int
+    limit: int
+    offset: int
+
+
+class ContactItem(WazzapiModel):
+    id: str
+    phone_number: str
+    name: str | None = None
+    email: str | None = None
+    whatsapp_name: str | None = None
+    profile_picture_url: str | None = None
+    source: str
+    source_details: dict[str, Any] | None = None
+    is_opted_out: bool
+    tags: list[str] = Field(default_factory=list)
+    last_message_at: datetime | None = None
+    created_at: datetime
+
+
+class ContactGroupMembersResponse(WazzapiModel):
+    group: ContactGroupItem
+    contacts: list[ContactItem]
+    total: int
+    limit: int
+    offset: int
+
+
+class ContactGroupUpdateRequest(WazzapiModel):
+    name: str | None = None
+    description: str | None = None
+
+
+class ContactListResponse(WazzapiModel):
+    contacts: list[ContactItem]
+    total: int
+    limit: int
+    offset: int
+
+
+class ContactResponse(WazzapiModel):
+    id: str
+    phone_number: str
+    name: str | None = None
+    email: str | None = None
+    whatsapp_name: str | None = None
+    profile_picture_url: str | None = None
+    custom_fields: dict[str, Any] | None = None
+    source: str
+    source_details: dict[str, Any] | None = None
+    is_opted_out: bool
+    opted_out_at: datetime | None = None
+    tags: list[str] = Field(default_factory=list)
+    last_message_at: datetime | None = None
+    created_at: datetime
+    updated_at: datetime
+
+
+class ContactSyncHistoryItem(WazzapiModel):
+    id: str
+    account_id: str
+    account_name: str
+    sync_type: str
+    status: str
+    contacts_count: int
+    started_at: datetime
+    completed_at: datetime | None = None
+    error_message: str | None = None
+
+
+class ContactSyncHistoryResponse(WazzapiModel):
+    history: list[ContactSyncHistoryItem]
+    total: int
+
+
+class ContactSyncRequest(WazzapiModel):
+    whatsapp_account_id: str
+    sync_type: str | None = None
+
+
+class ContactSyncResponse(WazzapiModel):
+    success: bool
+    job_id: str | None = None
+    message: str
+    status: str | None = None
+
+
+class ContactSyncStatusResponse(WazzapiModel):
+    account_id: str
+    account_name: str
+    last_sync_at: datetime | None = None
+    last_sync_status: str | None = None
+    contacts_synced_count: int
+    can_sync: bool
+
+
+class ContactUpdateRequest(WazzapiModel):
+    name: str | None = None
+    email: str | None = None
+    tags: list[str] | None = None
+    custom_fields: dict[str, Any] | None = None
+    is_opted_out: bool | None = None
+
+
+class RemoveFromGroupRequest(WazzapiModel):
+    contact_ids: list[str]
+
+
+__all__ = [
+    "AddToGroupRequest",
+    "AddToGroupResponse",
+    "BulkDeleteRequest",
+    "BulkDeleteResponse",
+    "CSVExportResponse",
+    "CSVImportRequest",
+    "CSVImportResponse",
+    "ContactCreateRequest",
+    "ContactGroupCreateRequest",
+    "ContactGroupItem",
+    "ContactGroupListResponse",
+    "ContactGroupMembersResponse",
+    "ContactGroupUpdateRequest",
+    "ContactItem",
+    "ContactListResponse",
+    "ContactResponse",
+    "ContactSyncHistoryItem",
+    "ContactSyncHistoryResponse",
+    "ContactSyncRequest",
+    "ContactSyncResponse",
+    "ContactSyncStatusResponse",
+    "ContactUpdateRequest",
+    "RemoveFromGroupRequest",
+]

wazzapi/models/messages.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from .base import WazzapiModel
+
+
+class InteractiveButton(WazzapiModel):
+    id: str
+    title: str
+
+
+class ButtonReplyRequest(WazzapiModel):
+    phone_number: str
+    body: str
+    buttons: list[InteractiveButton]
+    whatsapp_account_id: str
+    footer: str | None = None
+    contact_id: str | None = None
+
+
+class CancelMessageResponse(WazzapiModel):
+    success: bool
+    message_id: str
+    status: str
+
+
+class InteractiveMessageResponse(WazzapiModel):
+    success: bool
+    message_id: str
+    status: str
+    run_id: str | None = None
+
+
+class InteractiveRow(WazzapiModel):
+    id: str
+    title: str
+    description: str | None = None
+
+
+class InteractiveSection(WazzapiModel):
+    title: str
+    rows: list[InteractiveRow]
+
+
+class ListReplyRequest(WazzapiModel):
+    phone_number: str
+    body: str
+    button_text: str
+    sections: list[InteractiveSection]
+    whatsapp_account_id: str
+    footer: str | None = None
+    contact_id: str | None = None
+
+
+class MessageItem(WazzapiModel):
+    id: str
+    phone_number: str
+    content: str
+    message_type: str = "text"
+    media_type: str | None = None
+    media_url: str | None = None
+    status: str
+    direction: str
+    retry_count: int
+    contact_id: str | None = None
+    contact_name: str | None = None
+    whatsapp_account_id: str
+    campaign_id: str | None = None
+    batch_id: str | None = None
+    scheduled_for: datetime | None = None
+    created_at: datetime
+    sent_at: datetime | None = None
+    delivered_at: datetime | None = None
+    read_at: datetime | None = None
+
+
+class MessageListResponse(WazzapiModel):
+    messages: list[MessageItem]
+    total_count: int
+    has_more: bool
+    current_page: int
+    total_pages: int
+
+
+class MessageResponse(WazzapiModel):
+    id: str
+    phone_number: str
+    content: str
+    message_type: str = "text"
+    media_type: str | None = None
+    media_url: str | None = None
+    status: str
+    direction: str
+    failure_reason: str | None = None
+    retry_count: int
+    whatsapp_message_id: str | None = None
+    variable_values: dict[str, Any] | None = None
+    contact_id: str | None = None
+    contact_name: str | None = None
+    whatsapp_account_id: str
+    campaign_id: str | None = None
+    batch_id: str | None = None
+    scheduled_for: datetime | None = None
+    queued_at: datetime | None = None
+    sent_at: datetime | None = None
+    delivered_at: datetime | None = None
+    read_at: datetime | None = None
+    failed_at: datetime | None = None
+    created_at: datetime
+    updated_at: datetime
+
+
+class MessageStatsResponse(WazzapiModel):
+    total: int
+    by_status: dict[str, int]
+    by_direction: dict[str, int]
+    last_7_days: int
+    last_30_days: int
+
+
+class RetryMessageResponse(WazzapiModel):
+    success: bool
+    message_id: str
+    run_id: str | None = None
+    status: str
+
+
+class SendMessageRequest(WazzapiModel):
+    phone_number: str
+    whatsapp_account_id: str
+    content: str | None = None
+    template_id: str | None = None
+    custom_variables: dict[str, Any] | None = None
+    message_type: str = "text"
+    media_type: str | None = None
+    media_url: str | None = None
+    caption: str | None = None
+    latitude: float | None = None
+    longitude: float | None = None
+    location_title: str | None = None
+    location_address: str | None = None
+    contacts: list[dict[str, Any]] | None = None
+    contact_id: str | None = None
+    scheduled_for: datetime | None = None
+    validate_phone: bool = False
+    status_callback_url: str | None = None
+
+
+class SendMessageResponse(WazzapiModel):
+    success: bool
+    message_id: str
+    status: str
+    run_id: str | None = None
+
+
+__all__ = [
+    "ButtonReplyRequest",
+    "CancelMessageResponse",
+    "InteractiveButton",
+    "InteractiveMessageResponse",
+    "InteractiveRow",
+    "InteractiveSection",
+    "ListReplyRequest",
+    "MessageItem",
+    "MessageListResponse",
+    "MessageResponse",
+    "MessageStatsResponse",
+    "RetryMessageResponse",
+    "SendMessageRequest",
+    "SendMessageResponse",
+]

wazzapi/models/templates.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import Field
+
+from .base import WazzapiModel
+
+
+class BuiltinVariableInfo(WazzapiModel):
+    name: str
+    description: str
+    example: str
+
+
+class BuiltinVariablesResponse(WazzapiModel):
+    variables: list[BuiltinVariableInfo]
+
+
+class TemplateCreateRequest(WazzapiModel):
+    name: str
+    content: str
+    category: str = "marketing"
+    media_type: str | None = None
+    media_url: str | None = None
+
+
+class TemplateItem(WazzapiModel):
+    id: str
+    name: str
+    category: str
+    content: str
+    variables: list[str] = Field(default_factory=list)
+    builtin_variables: list[str] = Field(default_factory=list)
+    custom_variables: list[str] = Field(default_factory=list)
+    media_type: str | None = None
+    media_url: str | None = None
+    times_used: int
+    last_used_at: datetime | None = None
+    created_at: datetime
+
+
+class TemplateListResponse(WazzapiModel):
+    data: list[TemplateItem]
+    pagination: dict[str, Any]
+
+
+class TemplatePreviewRequest(WazzapiModel):
+    content: str | None = None
+    template_id: str | None = None
+    custom_variables: dict[str, Any] | None = None
+    contact_id: str | None = None
+
+
+class TemplatePreviewResponse(WazzapiModel):
+    preview: str
+    all_variables: list[str] = Field(default_factory=list)
+    builtin_variables: list[str] = Field(default_factory=list)
+    custom_variables: list[str] = Field(default_factory=list)
+    missing_variables: list[str] = Field(default_factory=list)
+
+
+class TemplateResponse(WazzapiModel):
+    id: str
+    name: str
+    category: str
+    content: str
+    variables: list[str] = Field(default_factory=list)
+    builtin_variables: list[str] = Field(default_factory=list)
+    custom_variables: list[str] = Field(default_factory=list)
+    media_type: str | None = None
+    media_url: str | None = None
+    is_active: bool
+    times_used: int
+    last_used_at: datetime | None = None
+    created_at: datetime
+    updated_at: datetime
+
+
+class TemplateUpdateRequest(WazzapiModel):
+    name: str | None = None
+    content: str | None = None
+    category: str | None = None
+    is_active: bool | None = None
+    media_type: str | None = None
+    media_url: str | None = None
+
+
+__all__ = [
+    "BuiltinVariableInfo",
+    "BuiltinVariablesResponse",
+    "TemplateCreateRequest",
+    "TemplateItem",
+    "TemplateListResponse",
+    "TemplatePreviewRequest",
+    "TemplatePreviewResponse",
+    "TemplateResponse",
+    "TemplateUpdateRequest",
+]