ombala 0.1.0__py3-none-any.whl

ombala/__init__.py

@@ -0,0 +1,3 @@
+from ombala.client import Ombala, AsyncOmbala
+
+__all__ = ["Ombala", "AsyncOmbala"]

ombala/client.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from ombala.exceptions import (
+    AuthenticationError,
+    OmbalaError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from ombala.resources.credits import CreditsResource
+from ombala.resources.messages import MessagesResource
+from ombala.resources.senders import SendersResource
+
+BASE_URL = "https://api.useombala.ao"
+
+
+def error(status_code: int, response_data: dict[str, Any] | None) -> OmbalaError:
+    message = str(response_data) if response_data else f"HTTP {status_code}"
+    if status_code == 401:
+        return AuthenticationError(message, status_code, response_data)
+    if status_code == 429:
+        return RateLimitError(message, status_code, response_data)
+    if 400 <= status_code < 500:
+        return ValidationError(message, status_code, response_data)
+    if 500 <= status_code < 600:
+        return ServerError(message, status_code, response_data)
+    return OmbalaError(message, status_code, response_data)
+
+
+class Ombala:
+    def __init__(self, token: str, base_url: str = BASE_URL, timeout: int = 30) -> None:
+        self._client = httpx.Client(
+            base_url=base_url,
+            headers={
+                "Authorization": f"Token {token}",
+                "Content-Type": "application/json",
+            },
+            timeout=timeout,
+        )
+        self.messages = MessagesResource(self)
+        self.senders = SendersResource(self)
+        self.credits = CreditsResource(self)
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
+        try:
+            response = self._client.request(method, path, **kwargs)
+        except httpx.HTTPError as exc:
+            raise OmbalaError(f"Request failed: {exc}") from exc
+
+        if response.is_error:
+            try:
+                data = response.json()
+            except Exception:
+                data = None
+            raise error(response.status_code, data)
+
+        return response
+
+    def get(self, path: str, **kwargs: Any) -> httpx.Response:
+        return self._request("GET", path, **kwargs)
+
+    def post(self, path: str, **kwargs: Any) -> httpx.Response:
+        return self._request("POST", path, **kwargs)
+
+    def delete(self, path: str, **kwargs: Any) -> httpx.Response:
+        return self._request("DELETE", path, **kwargs)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> Ombala:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()

ombala/exceptions.py

@@ -0,0 +1,20 @@
+from typing import Any
+
+
+class OmbalaError(Exception):
+    def __init__(self, message: str, status_code: int | None = None,response_data: dict[str, Any] | None = None) -> None:
+        self.status_code = status_code
+        self.response_data = response_data
+        super().__init__(message)
+
+
+class AuthenticationError(OmbalaError): ...
+
+
+class ValidationError(OmbalaError): ...
+
+
+class RateLimitError(OmbalaError): ...
+
+
+class ServerError(OmbalaError): ...

ombala/models.py

@@ -0,0 +1,48 @@
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class SendSMSRequest(BaseModel):
+    message: str
+    from_: str = Field(alias="from", serialization_alias="from")
+    to: str
+    schedule: str | None = None
+
+
+class Message(BaseModel):
+    id: str
+    message: str
+    from_: str | None = Field(None, alias="from")
+    to: str | None = None
+    status: str | None = None
+    created_at: datetime | None = Field(None, alias="createdAt")
+
+
+class SenderCreate(BaseModel):
+    name: str
+
+
+class Sender(BaseModel):
+    id: str
+    name: str
+    status: str | None = None
+
+
+class CreditBalance(BaseModel):
+    balance: float | None = None
+    currency: str | None = None
+
+
+class Recharge(BaseModel):
+    id: str | None = None
+    amount: float | None = None
+    date: str | None = None
+
+
+class PaginatedResponse(BaseModel):
+    data: list[Any]
+    page: int | None = None
+    total: int | None = None
+    total_pages: int | None = None

ombala/resources/credits.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ombala.client import Ombala, AsyncOmbala
+
+
+class CreditsResource:
+    def __init__(self, client: Ombala | AsyncOmbala) -> None:
+        self._client = client
+
+    def balance(self) -> dict[str, Any]:
+        resp = self._client.get("/v1/credits")
+        return resp.json()
+
+    def recharges(self) -> dict[str, Any]:
+        resp = self._client.get("/v1/recharges")
+        return resp.json()

ombala/resources/messages.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from ombala.models import SendSMSRequest
+
+if TYPE_CHECKING:
+    from ombala.client import Ombala, AsyncOmbala
+
+
+class MessagesResource:
+    def __init__(self, client: Ombala | AsyncOmbala) -> None:
+        self._client = client
+
+    def send(self, message: str, from_: str,to: str, schedule: str | None = None) -> dict[str, Any]:
+        body = SendSMSRequest(message=message, from_=from_, to=to, schedule=schedule)
+        resp = self._client.post(
+            "/v1/messages",
+            content=body.model_dump_json(by_alias=True),
+        )
+        return resp.json()
+
+    def list(self, page: int | None = None) -> dict[str, Any]:
+        params: dict[str, Any] = {}
+        if page is not None:
+            params["page"] = page
+        resp = self._client.get("/v1/messages", params=params)
+        return resp.json()
+
+    def get(self, message_id: str, id: str | None = None) -> dict[str, Any]:
+        params: dict[str, Any] = {"message_id": message_id}
+        if id is not None:
+            params["id"] = id
+        resp = self._client.get("/v1/messages/one", params=params)
+        return resp.json()
+
+    def delete(self, message_id: str) -> None:
+        self._client.delete(f"/v1/messages/{message_id}")
+
+    def list_recipients(
+        self,
+        page: int | None = None,
+    ) -> dict[str, Any]:
+        params: dict[str, Any] = {}
+        if page is not None:
+            params["page"] = page
+        resp = self._client.get("/v1/messages/recipients", params=params)
+        return resp.json()
+
+    def list_by_date_range(
+        self,
+        start: str,
+        end: str,
+        page: int | None = None,
+    ) -> dict[str, Any]:
+        params: dict[str, Any] = {"start": start, "end": end}
+        if page is not None:
+            params["page"] = page
+        resp = self._client.get("/v1/messages/date", params=params)
+        return resp.json()
+
+    def list_by_recipient(
+        self,
+        phone_number: str | None = None,
+        page: int | None = None,
+    ) -> dict[str, Any]:
+        params: dict[str, Any] = {}
+        if phone_number is not None:
+            params["phone_number"] = phone_number
+        if page is not None:
+            params["page"] = page
+        resp = self._client.get("/v1/messages/recipient", params=params)
+        return resp.json()

ombala/resources/senders.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ombala.client import Ombala, AsyncOmbala
+
+
+class SendersResource:
+    def __init__(self, client: Ombala | AsyncOmbala) -> None:
+        self._client = client
+
+    def create(self, name: str) -> dict[str, Any]:
+        resp = self._client.post("/v1/senders/", json={"name": name})
+        return resp.json()
+
+    def list(self) -> dict[str, Any]:
+        resp = self._client.get("/v1/senders")
+        return resp.json()
+
+    def list_approved(self) -> dict[str, Any]:
+        resp = self._client.get("/v1/senders/approved")
+        return resp.json()
+
+    def list_pending(self) -> dict[str, Any]:
+        resp = self._client.get("/v1/senders/pending")
+        return resp.json()
+
+    def delete(self, sender_id: str) -> None:
+        self._client.delete(f"/v1/senders/{sender_id}")

ombala-0.1.0.dist-info/METADATA

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: ombala
+Version: 0.1.0
+Summary: SDK em Python para a API de envios de SMS em Angola
+Project-URL: Homepage, https://www.useombala.ao/
+Project-URL: Repository, https://github.com/omarscode/ombala
+Project-URL: Documentation, https://github.com/omarscode/ombala#README
+Project-URL: Tracker, https://github.com/omarscode/ombala/issues
+Author-email: Omar Rodrigues <omarscode007@gmail.com>
+License: MIT
+Keywords: angola,api,ombala,sdk,sms
+Classifier: Development Status :: 3 - Alpha
+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 :: Telephony
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: respx>=0.21.0; extra == 'dev'
+Requires-Dist: ruff>=0.5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Ombala SDK Python
+
+SDK Python para a [API Ombala](https://api.useombala.ao) — envio de SMS em Angola.
+
+## Instalação
+
+```bash
+pip install ombala
+```
+
+## Uso
+
+```python
+from ombala import Ombala
+
+client = Ombala("Token a9eb6ea6-5777-4848-a9ed-8cbffc74a503")
+
+# Enviar SMS
+client.messages.send(
+    message="Olá, tudo bem?",
+    from_="MINHALOJA",
+    to="921939411",
+)
+
+# Listar mensagens
+client.messages.list(page=1)
+
+# Ver saldo
+client.credits.balance()
+```
+
+### Modo assíncrono
+
+```python
+import asyncio
+from ombala import AsyncOmbala
+
+async def main():
+    async with AsyncOmbala("Token ...") as client:
+        resp = await client.messages.send(
+            message="Olá, tudo bem?",
+            from_="MINHALOJA",
+            to="921939411",
+        )
+        print(resp)
+
+asyncio.run(main())
+```
+
+## API
+
+### Mensagens
+
+| Método | Descrição |
+|---|---|
+| `messages.send(message, from_, to, schedule?)` | Enviar SMS |
+| `messages.list(page?)` | Listar mensagens |
+| `messages.get(message_id, id?)` | Obter mensagem por ID |
+| `messages.delete(message_id)` | Apagar registo de envio |
+| `messages.list_recipients(page?)` | Listar destinatários |
+| `messages.list_by_date_range(start, end, page?)` | Listar mensagens por intervalo de datas |
+| `messages.list_by_recipient(phone_number?, page?)` | Listar mensagens de um número |
+
+### Remetentes
+
+| Método | Descrição |
+|---|---|
+| `senders.create(name)` | Criar remetente |
+| `senders.list()` | Listar remetentes |
+| `senders.list_approved()` | Listar remetentes aprovados |
+| `senders.list_pending()` | Listar remetentes pendentes |
+| `senders.delete(sender_id)` | Apagar remetente |
+
+### Créditos
+
+| Método | Descrição |
+|---|---|
+| `credits.balance()` | Mostrar saldo |
+| `credits.recharges()` | Histórico de carregamentos |

ombala-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+ombala/__init__.py,sha256=evXj8g4BMZtK2C3M56vMO9JtQQNFFBMj0p1bJUwjUqU,83
+ombala/client.py,sha256=JBzFsVBuy8v1NT4WMNOuJZveJx0UEQ_oRIjaF-69hPU,2535
+ombala/exceptions.py,sha256=YSfzUChw7omqQuEtk3-US6rlQyIqDpyJlhnSWJGyJyA,460
+ombala/models.py,sha256=TcHeXoKsV-2yq2As-HacTx7IllNe_chz-pBg2Ar7opU,975
+ombala/resources/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ombala/resources/credits.py,sha256=sXpg08mMIu1EPL97R3SgZtDThERGgKY7EVT21nll6GU,496
+ombala/resources/messages.py,sha256=QTxPY16w7Q2zYA-TYvOUAYs0U30jTPm3iRsrgr8Ee18,2379
+ombala/resources/senders.py,sha256=IEwA4qpaO-4Ei2cHwshMpe923LpbspyImklAmuvvPog,885
+ombala-0.1.0.dist-info/METADATA,sha256=p1dZQY2kqaBIhihI4kxvvW8zD6mXiGoBlDW6xPnSeiI,3212
+ombala-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+ombala-0.1.0.dist-info/RECORD,,

ombala-0.1.0.dist-info/WHEEL

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