reachflow 0.1.0__tar.gz

reachflow-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+node_modules/
+dist/
+*.tsbuildinfo
+.coverage
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+.venv/
+venv/
+reachflow-python/.venv/
+.env
+.env.*
+!.env.example
+scripts/.env.sandbox
+reachflow-node/.npmrc.publish

reachflow-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ReachFlow
+
+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.

reachflow-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: reachflow
+Version: 0.1.0
+Summary: Client officiel Python pour l'API publique ReachFlow
+Project-URL: Homepage, https://docs.reachflow.me/developpeurs
+Project-URL: Documentation, https://docs.reachflow.me/developpeurs
+Project-URL: Repository, https://github.com/reachflow/reachflow-python
+Project-URL: Issues, https://github.com/reachflow/reachflow-python/issues
+Author-email: ReachFlow <contact@reachflow.me>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,otp,reachflow,sdk,whatsapp
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13.0; 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'
+Description-Content-Type: text/markdown
+
+# reachflow
+
+Client officiel **Python** pour l’[API publique ReachFlow](https://docs.reachflow.me/developpeurs) (REST v1).
+
+## Installation
+
+```bash
+pip install reachflow
+```
+
+**Prérequis :** Python ≥ 3.10.
+
+## Configuration
+
+```python
+from reachflow import ReachFlow
+
+client = ReachFlow(
+    api_key="rfl_live_…",  # ou rfl_test_…
+    base_url="https://sandbox-api.reachflow.me",  # optionnel
+    timeout_ms=30_000,  # optionnel
+    max_retries=2,  # optionnel — 429 / 5xx
+)
+```
+
+Utilisez le client comme context manager pour fermer la connexion HTTP :
+
+```python
+with ReachFlow(api_key="rfl_live_…") as client:
+    ...
+```
+
+## Exemples
+
+### Envoyer un message
+
+```python
+with ReachFlow(api_key="rfl_live_…") as client:
+    result = client.messages.send(
+        provider_id="uuid-du-provider",
+        to="22996123456",
+        message="Votre commande est confirmée.",
+    )
+    status = client.messages.wait_for_terminal(result["messageId"])
+    print(status["status"])
+```
+
+### OTP
+
+```python
+with ReachFlow(api_key="rfl_live_…") as client:
+    sent = client.otp.send(
+        provider_id="uuid-du-provider",
+        phone_number="22996123456",
+        brand_name="Mon App",
+    )
+    # Le code arrive sur WhatsApp — jamais dans la réponse JSON.
+    verified = client.otp.verify(otp_id=sent["otpId"], code="482910")
+    print(verified["valid"])
+```
+
+### Client asynchrone
+
+```python
+from reachflow import AsyncReachFlow
+
+async with AsyncReachFlow(api_key="rfl_live_…") as client:
+    providers = await client.providers.list()
+```
+
+## Gestion des erreurs
+
+```python
+from reachflow import ReachFlow, ReachFlowError
+
+try:
+    client.messages.send(...)
+except ReachFlowError as err:
+    print(err.status_code, err.code, err.message)
+    if err.retryable:
+        ...
+```
+
+## Idempotence
+
+```python
+client.messages.send(
+    provider_id=provider_id,
+    to=to,
+    message=message,
+    idempotency_key="order-12345",
+)
+```
+
+## Développement
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Licence
+
+MIT

reachflow-0.1.0/README.md

@@ -0,0 +1,104 @@
+# reachflow
+
+Client officiel **Python** pour l’[API publique ReachFlow](https://docs.reachflow.me/developpeurs) (REST v1).
+
+## Installation
+
+```bash
+pip install reachflow
+```
+
+**Prérequis :** Python ≥ 3.10.
+
+## Configuration
+
+```python
+from reachflow import ReachFlow
+
+client = ReachFlow(
+    api_key="rfl_live_…",  # ou rfl_test_…
+    base_url="https://sandbox-api.reachflow.me",  # optionnel
+    timeout_ms=30_000,  # optionnel
+    max_retries=2,  # optionnel — 429 / 5xx
+)
+```
+
+Utilisez le client comme context manager pour fermer la connexion HTTP :
+
+```python
+with ReachFlow(api_key="rfl_live_…") as client:
+    ...
+```
+
+## Exemples
+
+### Envoyer un message
+
+```python
+with ReachFlow(api_key="rfl_live_…") as client:
+    result = client.messages.send(
+        provider_id="uuid-du-provider",
+        to="22996123456",
+        message="Votre commande est confirmée.",
+    )
+    status = client.messages.wait_for_terminal(result["messageId"])
+    print(status["status"])
+```
+
+### OTP
+
+```python
+with ReachFlow(api_key="rfl_live_…") as client:
+    sent = client.otp.send(
+        provider_id="uuid-du-provider",
+        phone_number="22996123456",
+        brand_name="Mon App",
+    )
+    # Le code arrive sur WhatsApp — jamais dans la réponse JSON.
+    verified = client.otp.verify(otp_id=sent["otpId"], code="482910")
+    print(verified["valid"])
+```
+
+### Client asynchrone
+
+```python
+from reachflow import AsyncReachFlow
+
+async with AsyncReachFlow(api_key="rfl_live_…") as client:
+    providers = await client.providers.list()
+```
+
+## Gestion des erreurs
+
+```python
+from reachflow import ReachFlow, ReachFlowError
+
+try:
+    client.messages.send(...)
+except ReachFlowError as err:
+    print(err.status_code, err.code, err.message)
+    if err.retryable:
+        ...
+```
+
+## Idempotence
+
+```python
+client.messages.send(
+    provider_id=provider_id,
+    to=to,
+    message=message,
+    idempotency_key="order-12345",
+)
+```
+
+## Développement
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Licence
+
+MIT

reachflow-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling>=1.24.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "reachflow"
+version = "0.1.0"
+description = "Client officiel Python pour l'API publique ReachFlow"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "ReachFlow", email = "contact@reachflow.me" }]
+keywords = ["reachflow", "whatsapp", "api", "sdk", "otp"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.27.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0.0",
+  "pytest-asyncio>=0.24.0",
+  "respx>=0.21.0",
+  "mypy>=1.13.0",
+]
+
+[project.urls]
+Homepage = "https://docs.reachflow.me/developpeurs"
+Documentation = "https://docs.reachflow.me/developpeurs"
+Repository = "https://github.com/reachflow/reachflow-python"
+Issues = "https://github.com/reachflow/reachflow-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/reachflow"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+packages = ["reachflow"]
+mypy_path = ["src"]

reachflow-0.1.0/src/reachflow/__init__.py

@@ -0,0 +1,22 @@
+"""Client officiel Python pour l'API publique ReachFlow."""
+
+from reachflow.client import ReachFlow, AsyncReachFlow
+from reachflow.errors import ReachFlowError
+from reachflow.types import (
+    DEFAULT_BASE_URL,
+    TERMINAL_MESSAGE_STATUSES,
+    MessageStatus,
+    MediaType,
+)
+
+__all__ = [
+    "ReachFlow",
+    "AsyncReachFlow",
+    "ReachFlowError",
+    "DEFAULT_BASE_URL",
+    "TERMINAL_MESSAGE_STATUSES",
+    "MessageStatus",
+    "MediaType",
+]
+
+__version__ = "0.1.0"

reachflow-0.1.0/src/reachflow/client.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+from types import TracebackType
+
+import httpx
+
+from reachflow.http import (
+    AsyncHttpClient,
+    ClientConfig,
+    HttpClient,
+    resolve_config,
+)
+from reachflow.resources.messages import AsyncMessagesResource, MessagesResource
+from reachflow.resources.otp import AsyncOtpResource, OtpResource
+from reachflow.resources.providers import AsyncProvidersResource, ProvidersResource
+
+
+class ReachFlow:
+    """Client synchrone pour l'API publique ReachFlow (REST v1)."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str | None = None,
+        timeout_ms: int = 30_000,
+        max_retries: int = 2,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        if not api_key or not api_key.strip():
+            raise ValueError("ReachFlow: api_key is required")
+
+        self._config: ClientConfig = resolve_config(
+            api_key=api_key,
+            base_url=base_url,
+            timeout_ms=timeout_ms,
+            max_retries=max_retries,
+        )
+        self._owns_client = http_client is None
+        self._httpx = http_client or httpx.Client()
+        self._http = HttpClient(self._config, self._httpx)
+
+        self.messages = MessagesResource(self._http)
+        self.providers = ProvidersResource(self._http)
+        self.otp = OtpResource(self._http)
+
+    @property
+    def base_url(self) -> str:
+        return self._config.base_url
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._httpx.close()
+
+    def __enter__(self) -> ReachFlow:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+
+class AsyncReachFlow:
+    """Client asynchrone pour l'API publique ReachFlow (REST v1)."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str,
+        base_url: str | None = None,
+        timeout_ms: int = 30_000,
+        max_retries: int = 2,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        if not api_key or not api_key.strip():
+            raise ValueError("ReachFlow: api_key is required")
+
+        self._config: ClientConfig = resolve_config(
+            api_key=api_key,
+            base_url=base_url,
+            timeout_ms=timeout_ms,
+            max_retries=max_retries,
+        )
+        self._owns_client = http_client is None
+        self._httpx = http_client or httpx.AsyncClient()
+        self._http = AsyncHttpClient(self._config, self._httpx)
+
+        self.messages = AsyncMessagesResource(self._http)
+        self.providers = AsyncProvidersResource(self._http)
+        self.otp = AsyncOtpResource(self._http)
+
+    @property
+    def base_url(self) -> str:
+        return self._config.base_url
+
+    async def close(self) -> None:
+        if self._owns_client:
+            await self._httpx.aclose()
+
+    async def __aenter__(self) -> AsyncReachFlow:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        await self.close()

reachflow-0.1.0/src/reachflow/errors.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+from email.utils import parsedate_to_datetime
+from typing import Any, Literal
+
+ReachFlowErrorCode = Literal[
+    "unauthorized",
+    "plan_required",
+    "insufficient_scope",
+    "rate_limit_exceeded",
+    "too_many_auth_failures",
+    "validation_error",
+    "not_found",
+    "api_error",
+    "network_error",
+    "timeout",
+]
+
+
+class ReachFlowError(Exception):
+    """Erreur levée par le client ReachFlow."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        code: ReachFlowErrorCode,
+        retryable: bool = False,
+        retry_after_ms: int | None = None,
+        body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.code = code
+        self.retryable = retryable
+        self.retry_after_ms = retry_after_ms
+        self.body = body
+
+    @classmethod
+    def from_response(cls, status: int, body: Any, fallback: str | None = None) -> ReachFlowError:
+        parsed = body if isinstance(body, dict) else {}
+        api_error = parsed.get("error")
+        message = parsed.get("message") or fallback or f"ReachFlow API error (HTTP {status})"
+        code = _map_api_error_to_code(status, api_error)
+        retryable = status == 429 or status == 408 or 500 <= status < 600
+        return cls(
+            message,
+            status_code=status,
+            code=code,
+            retryable=retryable,
+            body=body,
+        )
+
+    @classmethod
+    def network(cls, cause: BaseException) -> ReachFlowError:
+        return cls(
+            "Network error while calling ReachFlow API",
+            status_code=0,
+            code="network_error",
+            retryable=True,
+        )
+
+    @classmethod
+    def timeout(cls, timeout_ms: int) -> ReachFlowError:
+        return cls(
+            f"Request timed out after {timeout_ms}ms",
+            status_code=408,
+            code="timeout",
+            retryable=True,
+        )
+
+
+def parse_retry_after_ms(header: str | None) -> int | None:
+    if not header:
+        return None
+    try:
+        return max(0, int(float(header.strip())) * 1000)
+    except ValueError:
+        pass
+    try:
+        dt = parsedate_to_datetime(header)
+        from datetime import datetime, timezone
+
+        now = datetime.now(timezone.utc)
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        return max(0, int((dt - now).total_seconds() * 1000))
+    except (TypeError, ValueError, OverflowError):
+        return None
+
+
+def _map_api_error_to_code(status: int, api_error: str | None) -> ReachFlowErrorCode:
+    mapping: dict[str, ReachFlowErrorCode] = {
+        "unauthorized": "unauthorized",
+        "plan_required": "plan_required",
+        "insufficient_scope": "insufficient_scope",
+        "rate_limit_exceeded": "rate_limit_exceeded",
+        "too_many_auth_failures": "too_many_auth_failures",
+    }
+    if api_error in mapping:
+        return mapping[api_error]
+    if status == 401:
+        return "unauthorized"
+    if status == 403:
+        return "insufficient_scope"
+    if status == 404:
+        return "not_found"
+    if status in (400, 422):
+        return "validation_error"
+    if status == 429:
+        return "rate_limit_exceeded"
+    return "api_error"