ararahq-sdk 1.8.0__tar.gz

ararahq_sdk-1.8.0/.gitignore

@@ -0,0 +1,146 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+# .Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Used to bundle your script into a single file
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or even
+#   fail to install.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#poetry.lock
+
+# pdm
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+.idea/

ararahq_sdk-1.8.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Arara Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ararahq_sdk-1.8.0/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: ararahq-sdk
+Version: 1.8.0
+Summary: Official Python SDK for the Arara API
+Project-URL: Homepage, https://github.com/ararahq/arara-python-sdk
+Project-URL: Bug Tracker, https://github.com/ararahq/arara-python-sdk/issues
+Author-email: Arara <contact@arara.io>
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: pydantic[email]>=2.0.0
+Requires-Dist: tenacity>=8.0.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: lint
+Requires-Dist: mypy>=1.0.0; extra == 'lint'
+Requires-Dist: ruff>=0.1.0; extra == 'lint'
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'test'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'test'
+Requires-Dist: pytest>=7.0.0; extra == 'test'
+Requires-Dist: respx>=0.20.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Arara Python SDK
+
+O SDK oficial da Arara para Python. Esta biblioteca permite integrar facilmente as funcionalidades de mensageria (WhatsApp), gestão de templates, inteligência artificial (Brain), campanhas e pagamentos diretamente no seu aplicativo ou servidor.
+
+---
+
+## 🚀 Destaques (Features)
+
+- **Suporte Nativo a Async/Sync**: Escolha entre operações bloqueantes ou assíncronas (`httpx` baseado).
+- **Type Safety**: Utiliza **Pydantic V2** para validação rigorosa de dados e suporte total a autocompletar em IDEs.
+- **Resiliência**: Lógica de **Retries** automática com backoff exponencial integrada.
+- **Tratamento de Erros Profissional**: Hierarquia de exceções clara para cada status HTTP relevante.
+- **Arquitetura Modular**: Recursos organizados por domínio (Messages, Templates, Brain, etc).
+
+---
+
+## 📦 Instalação
+
+```bash
+pip install arara-api-sdk
+```
+
+> **Nota:** Requer Python 3.8 ou superior.
+
+---
+
+## 🔑 Autenticação
+
+A autenticação é feita via **Bear API Key**. Você pode obter sua chave no painel da Arara.
+
+O SDK busca automaticamente a variável de ambiente `ARARA_API_KEY` caso nenhuma chave seja passada no construtor.
+
+```bash
+export ARARA_API_KEY="ara_live_..."
+```
+
+---
+
+## 🛠️ Uso Rápido (Quick Start)
+
+### Modo Síncrono (Standard)
+Ideal para scripts simples ou servidores que não utilizam async/await.
+
+```python
+from arara_api_sdk import AraraClient
+from arara_api_sdk.models.message import SendMessageRequest
+
+# O uso de Context Manager garante que os recursos sejam fechados corretamente
+with AraraClient(api_key="your_api_key") as client:
+    request = SendMessageRequest(
+        receiver="5511999999999",
+        body="Hello World from Arara SDK!",
+        media_url="https://ararahq.com/l/FtFmja" # Opcional: Anexo
+    )
+    response = client.messages.send(request)
+    print(f"Message ID: {response.id} | Status: {response.status}")
+```
+
+### Modo Assíncrono (High Performance)
+Recomendado para aplicações FastAPI, aiohttp ou volumes massivos de dados.
+
+```python
+import asyncio
+from arara_api_sdk import AraraClient
+from arara_api_sdk.models.message import SendMessageRequest
+
+async def send_bulk():
+    async with AraraClient() as client:
+        request = SendMessageRequest(
+            receiver="5511999999999",
+            template_name="welcome_message",
+            variables=["Amos"],
+            scheduled_at="2024-12-25T10:00:00Z" # Opcional: Agendamento ISO8601
+        )
+        response = await client.messages.send_async(request)
+        print(f"Async Sent: {response.id}")
+
+asyncio.run(send_bulk())
+```
+
+---
+
+## 📂 Visão Geral dos Módulos
+
+### 💬 Mensagens (Messages)
+Envio de mensagens de texto simples ou baseadas em templates aprovados.
+```python
+client.messages.send(request)
+client.messages.get(message_id)
+```
+
+### 📝 Templates
+Gestão completa do ciclo de vida de modelos de mensagem do WhatsApp.
+```python
+client.templates.list()
+client.templates.create(create_request)
+client.templates.get_status(template_id)
+```
+
+### 🧠 AI Brain
+Interface direta com o motor de Inteligência Artificial da Arara.
+```python
+response = client.brain.prompt(BrainRequest(prompt="Como configurar meu webhook?"))
+print(response.answer)
+```
+
+### 🏢 Organizações & Webhooks
+Gestão de membros, números de telefone e configuração de webhooks de recebimento.
+```python
+webhook = client.organizations.get_webhook()
+members = client.organizations.list_members()
+```
+
+---
+
+## ⚙️ Configuração Avançada
+
+Você pode customizar o comportamento do HttpClient no momento da inicialização:
+
+```python
+client = AraraClient(
+    api_key="...",
+    timeout=60.0,       # Custom timeout in seconds
+    max_retries=5,      # Exponential backoff retries
+    base_url="https://..." # Custom API endpoint
+)
+```
+
+---
+
+## ⚠️ Tratamento de Erros (Error Handling)
+
+O SDK mapeia erros da API para exceções Python específicas:
+
+```python
+from arara_api_sdk.exceptions import (
+    AraraAuthError, 
+    AraraValidationError, 
+    AraraResourceNotFoundError
+)
+
+try:
+    client.messages.send(request)
+except AraraAuthError:
+    # Error 401
+    pass
+except AraraResourceNotFoundError:
+    # Error 404
+    pass
+except AraraValidationError as e:
+    # Error 400 - Validation details are in e.response_body
+    print(e.response_body)
+```
+
+---
+
+## 👩‍💻 Desenvolvimento e Testes
+
+Se você deseja contribuir ou rodar os testes localmente:
+
+1. Crie um ambiente virtual: `python -m venv .venv`
+2. Ative: `source .venv/bin/activate`
+3. Instale as dependências: `pip install -e ".[test]"`
+4. Rode os testes: `pytest tests/`
+
+---
+
+## 📄 Licença
+
+Distribuído sob a licença MIT. Veja `LICENSE` para mais informações.

ararahq_sdk-1.8.0/README.md

@@ -0,0 +1,170 @@
+# Arara Python SDK
+
+O SDK oficial da Arara para Python. Esta biblioteca permite integrar facilmente as funcionalidades de mensageria (WhatsApp), gestão de templates, inteligência artificial (Brain), campanhas e pagamentos diretamente no seu aplicativo ou servidor.
+
+---
+
+## 🚀 Destaques (Features)
+
+- **Suporte Nativo a Async/Sync**: Escolha entre operações bloqueantes ou assíncronas (`httpx` baseado).
+- **Type Safety**: Utiliza **Pydantic V2** para validação rigorosa de dados e suporte total a autocompletar em IDEs.
+- **Resiliência**: Lógica de **Retries** automática com backoff exponencial integrada.
+- **Tratamento de Erros Profissional**: Hierarquia de exceções clara para cada status HTTP relevante.
+- **Arquitetura Modular**: Recursos organizados por domínio (Messages, Templates, Brain, etc).
+
+---
+
+## 📦 Instalação
+
+```bash
+pip install arara-api-sdk
+```
+
+> **Nota:** Requer Python 3.8 ou superior.
+
+---
+
+## 🔑 Autenticação
+
+A autenticação é feita via **Bear API Key**. Você pode obter sua chave no painel da Arara.
+
+O SDK busca automaticamente a variável de ambiente `ARARA_API_KEY` caso nenhuma chave seja passada no construtor.
+
+```bash
+export ARARA_API_KEY="ara_live_..."
+```
+
+---
+
+## 🛠️ Uso Rápido (Quick Start)
+
+### Modo Síncrono (Standard)
+Ideal para scripts simples ou servidores que não utilizam async/await.
+
+```python
+from arara_api_sdk import AraraClient
+from arara_api_sdk.models.message import SendMessageRequest
+
+# O uso de Context Manager garante que os recursos sejam fechados corretamente
+with AraraClient(api_key="your_api_key") as client:
+    request = SendMessageRequest(
+        receiver="5511999999999",
+        body="Hello World from Arara SDK!",
+        media_url="https://ararahq.com/l/FtFmja" # Opcional: Anexo
+    )
+    response = client.messages.send(request)
+    print(f"Message ID: {response.id} | Status: {response.status}")
+```
+
+### Modo Assíncrono (High Performance)
+Recomendado para aplicações FastAPI, aiohttp ou volumes massivos de dados.
+
+```python
+import asyncio
+from arara_api_sdk import AraraClient
+from arara_api_sdk.models.message import SendMessageRequest
+
+async def send_bulk():
+    async with AraraClient() as client:
+        request = SendMessageRequest(
+            receiver="5511999999999",
+            template_name="welcome_message",
+            variables=["Amos"],
+            scheduled_at="2024-12-25T10:00:00Z" # Opcional: Agendamento ISO8601
+        )
+        response = await client.messages.send_async(request)
+        print(f"Async Sent: {response.id}")
+
+asyncio.run(send_bulk())
+```
+
+---
+
+## 📂 Visão Geral dos Módulos
+
+### 💬 Mensagens (Messages)
+Envio de mensagens de texto simples ou baseadas em templates aprovados.
+```python
+client.messages.send(request)
+client.messages.get(message_id)
+```
+
+### 📝 Templates
+Gestão completa do ciclo de vida de modelos de mensagem do WhatsApp.
+```python
+client.templates.list()
+client.templates.create(create_request)
+client.templates.get_status(template_id)
+```
+
+### 🧠 AI Brain
+Interface direta com o motor de Inteligência Artificial da Arara.
+```python
+response = client.brain.prompt(BrainRequest(prompt="Como configurar meu webhook?"))
+print(response.answer)
+```
+
+### 🏢 Organizações & Webhooks
+Gestão de membros, números de telefone e configuração de webhooks de recebimento.
+```python
+webhook = client.organizations.get_webhook()
+members = client.organizations.list_members()
+```
+
+---
+
+## ⚙️ Configuração Avançada
+
+Você pode customizar o comportamento do HttpClient no momento da inicialização:
+
+```python
+client = AraraClient(
+    api_key="...",
+    timeout=60.0,       # Custom timeout in seconds
+    max_retries=5,      # Exponential backoff retries
+    base_url="https://..." # Custom API endpoint
+)
+```
+
+---
+
+## ⚠️ Tratamento de Erros (Error Handling)
+
+O SDK mapeia erros da API para exceções Python específicas:
+
+```python
+from arara_api_sdk.exceptions import (
+    AraraAuthError, 
+    AraraValidationError, 
+    AraraResourceNotFoundError
+)
+
+try:
+    client.messages.send(request)
+except AraraAuthError:
+    # Error 401
+    pass
+except AraraResourceNotFoundError:
+    # Error 404
+    pass
+except AraraValidationError as e:
+    # Error 400 - Validation details are in e.response_body
+    print(e.response_body)
+```
+
+---
+
+## 👩‍💻 Desenvolvimento e Testes
+
+Se você deseja contribuir ou rodar os testes localmente:
+
+1. Crie um ambiente virtual: `python -m venv .venv`
+2. Ative: `source .venv/bin/activate`
+3. Instale as dependências: `pip install -e ".[test]"`
+4. Rode os testes: `pytest tests/`
+
+---
+
+## 📄 Licença
+
+Distribuído sob a licença MIT. Veja `LICENSE` para mais informações.

ararahq_sdk-1.8.0/arara_api_sdk/__init__.py

@@ -0,0 +1,23 @@
+from arara_api_sdk.client import AraraClient
+from arara_api_sdk.exceptions import (
+    AraraError,
+    AraraAuthError,
+    AraraValidationError,
+    AraraRateLimitError,
+    AraraResourceNotFoundError,
+    AraraServerError,
+    AraraConnectionError,
+    AraraTimeoutError,
+)
+
+__all__ = [
+    "AraraClient",
+    "AraraError",
+    "AraraAuthError",
+    "AraraValidationError",
+    "AraraRateLimitError",
+    "AraraResourceNotFoundError",
+    "AraraServerError",
+    "AraraConnectionError",
+    "AraraTimeoutError",
+]

ararahq_sdk-1.8.0/arara_api_sdk/client.py

@@ -0,0 +1,78 @@
+from typing import Optional
+from arara_api_sdk.config import SDKConfig
+from arara_api_sdk.http.client import HttpClient
+from arara_api_sdk.resources.message import MessageResource
+from arara_api_sdk.resources.template import TemplateResource
+from arara_api_sdk.resources.organization import OrganizationResource
+from arara_api_sdk.resources.user import UserResource
+from arara_api_sdk.resources.brain import BrainResource
+from arara_api_sdk.resources.campaign import CampaignResource
+from arara_api_sdk.resources.payment import PaymentResource
+
+class AraraClient:
+    """
+    Official Arara Python SDK Client.
+    
+    Provides access to messages, templates, organizations, users, and AI brain features.
+    Supports both synchronous and asynchronous operations.
+    """
+
+    def __init__(
+        self, 
+        api_key: Optional[str] = None, 
+        base_url: Optional[str] = None,
+        timeout: Optional[float] = None,
+        max_retries: Optional[int] = None
+    ) -> None:
+        """Initializes the Arara SDK Client.
+
+        Args:
+            api_key: The Arara API Key. If not provided, will look for the 
+                ARARA_API_KEY environment variable.
+            base_url: The base URL for the Arara API. Defaults to 
+                https://api.arara.io.
+            timeout: Request timeout in seconds. Defaults to 30.0.
+            max_retries: Maximum number of request retries. Defaults to 3.
+        """
+        # Allow passing config directly or via env/defaults
+        config_kwargs = {}
+        if api_key: config_kwargs["api_key"] = api_key
+        if base_url: config_kwargs["base_url"] = base_url
+        if timeout: config_kwargs["timeout"] = timeout
+        if max_retries: config_kwargs["max_retries"] = max_retries
+        
+        self.config = SDKConfig(**config_kwargs)
+        self._http = HttpClient(self.config)
+        
+        # Initialize resources
+        self.messages = MessageResource(self._http)
+        self.templates = TemplateResource(self._http)
+        self.organizations = OrganizationResource(self._http)
+        self.users = UserResource(self._http)
+        self.brain = BrainResource(self._http)
+        self.campaigns = CampaignResource(self._http)
+        self.payments = PaymentResource(self._http)
+
+    def close(self) -> None:
+        """Closes the internal synchronous HTTP client."""
+        self._http.close()
+
+    async def aclose(self) -> None:
+        """Closes the internal asynchronous HTTP client."""
+        await self._http.aclose()
+
+    def __enter__(self) -> "AraraClient":
+        """Context manager entry point for synchronous use."""
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Context manager exit point for synchronous use."""
+        self.close()
+
+    async def __aenter__(self) -> "AraraClient":
+        """Context manager entry point for asynchronous use."""
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Context manager exit point for asynchronous use."""
+        await self.aclose()

ararahq_sdk-1.8.0/arara_api_sdk/config.py

@@ -0,0 +1,14 @@
+from typing import Optional
+from pydantic_settings import BaseSettings
+from pydantic import Field
+
+class SDKConfig(BaseSettings):
+    """SDK Configuration settings."""
+    api_key: str = Field(..., env="ARARA_API_KEY")
+    base_url: str = Field("https://api.arara.io", env="ARARA_BASE_URL")
+    timeout: float = Field(30.0, env="ARARA_TIMEOUT")
+    max_retries: int = Field(3, env="ARARA_MAX_RETRIES")
+
+    class Config:
+        env_prefix = "ARARA_"
+        case_sensitive = False

ararahq_sdk-1.8.0/arara_api_sdk/exceptions.py

@@ -0,0 +1,41 @@
+from typing import Optional, Dict, Any
+
+class AraraError(Exception):
+    """Base exception for Arara SDK."""
+    def __init__(
+        self, 
+        message: str, 
+        status_code: Optional[int] = None, 
+        response_body: Optional[Dict[str, Any]] = None
+    ):
+        super().__init__(message)
+        self.status_code = status_code
+        self.response_body = response_body
+
+class AraraAuthError(AraraError):
+    """Raised when authentication fails."""
+    pass
+
+class AraraValidationError(AraraError):
+    """Raised when request validation fails (400)."""
+    pass
+
+class AraraRateLimitError(AraraError):
+    """Raised when rate limit is exceeded (429)."""
+    pass
+
+class AraraResourceNotFoundError(AraraError):
+    """Raised when a resource is not found (404)."""
+    pass
+
+class AraraServerError(AraraError):
+    """Raised when the server returns a 5xx error."""
+    pass
+
+class AraraConnectionError(AraraError):
+    """Raised when a connection error occurs."""
+    pass
+
+class AraraTimeoutError(AraraError):
+    """Raised when a request times out."""
+    pass