reachflow 0.1.0__py3-none-any.whl

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/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/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"

reachflow/http.py

@@ -0,0 +1,238 @@
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Any, Literal
+
+import httpx
+
+from reachflow.errors import ReachFlowError, parse_retry_after_ms
+from reachflow.types import DEFAULT_BASE_URL
+
+HttpMethod = Literal["GET", "POST"]
+
+
+@dataclass(frozen=True)
+class ClientConfig:
+    api_key: str
+    base_url: str
+    api_prefix: str
+    timeout_ms: int
+    max_retries: int
+
+
+def resolve_config(
+    *,
+    api_key: str,
+    base_url: str | None = None,
+    timeout_ms: int = 30_000,
+    max_retries: int = 2,
+) -> ClientConfig:
+    normalized_base = (base_url or DEFAULT_BASE_URL).rstrip("/")
+    return ClientConfig(
+        api_key=api_key.strip(),
+        base_url=normalized_base,
+        api_prefix=f"{normalized_base}/api/v1",
+        timeout_ms=timeout_ms,
+        max_retries=max_retries,
+    )
+
+
+class HttpClient:
+    def __init__(self, config: ClientConfig, client: httpx.Client) -> None:
+        self._config = config
+        self._client = client
+
+    def request(
+        self,
+        method: HttpMethod,
+        path: str,
+        *,
+        body: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+    ) -> Any:
+        attempt = 0
+        last_error: ReachFlowError | None = None
+
+        while attempt <= self._config.max_retries:
+            try:
+                return self._request_once(
+                    method, path, body=body, idempotency_key=idempotency_key
+                )
+            except ReachFlowError as err:
+                last_error = err
+                if not err.retryable or attempt >= self._config.max_retries:
+                    raise
+                delay_ms = (
+                    err.retry_after_ms
+                    if err.retry_after_ms is not None
+                    else _backoff_ms(attempt)
+                )
+                time.sleep(delay_ms / 1000)
+                attempt += 1
+
+        if last_error is not None:
+            raise last_error
+        raise ReachFlowError("Request failed", status_code=0, code="api_error")
+
+    def _request_once(
+        self,
+        method: HttpMethod,
+        path: str,
+        *,
+        body: dict[str, Any] | None,
+        idempotency_key: str | None,
+    ) -> Any:
+        headers = {
+            "Accept": "application/json",
+            "X-API-Key": self._config.api_key,
+        }
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+
+        url = f"{self._config.api_prefix}{path}"
+        timeout = httpx.Timeout(self._config.timeout_ms / 1000)
+
+        try:
+            response = self._client.request(
+                method,
+                url,
+                headers=headers,
+                json=body,
+                timeout=timeout,
+            )
+        except httpx.TimeoutException as exc:
+            raise ReachFlowError.timeout(self._config.timeout_ms) from exc
+        except httpx.HTTPError as exc:
+            raise ReachFlowError.network(exc) from exc
+
+        data: Any
+        text = response.text
+        if text:
+            try:
+                data = response.json()
+            except ValueError:
+                data = {"raw": text[:500]}
+        else:
+            data = None
+
+        if response.is_error:
+            err = ReachFlowError.from_response(response.status_code, data)
+            retry_after_ms = parse_retry_after_ms(response.headers.get("Retry-After"))
+            if retry_after_ms is not None:
+                raise ReachFlowError(
+                    err.message,
+                    status_code=err.status_code,
+                    code=err.code,
+                    retryable=err.retryable,
+                    retry_after_ms=retry_after_ms,
+                    body=err.body,
+                )
+            raise err
+
+        return data
+
+
+class AsyncHttpClient:
+    def __init__(self, config: ClientConfig, client: httpx.AsyncClient) -> None:
+        self._config = config
+        self._client = client
+
+    async def request(
+        self,
+        method: HttpMethod,
+        path: str,
+        *,
+        body: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+    ) -> Any:
+        attempt = 0
+        last_error: ReachFlowError | None = None
+
+        while attempt <= self._config.max_retries:
+            try:
+                return await self._request_once(
+                    method, path, body=body, idempotency_key=idempotency_key
+                )
+            except ReachFlowError as err:
+                last_error = err
+                if not err.retryable or attempt >= self._config.max_retries:
+                    raise
+                delay_ms = (
+                    err.retry_after_ms
+                    if err.retry_after_ms is not None
+                    else _backoff_ms(attempt)
+                )
+                import asyncio
+
+                await asyncio.sleep(delay_ms / 1000)
+                attempt += 1
+
+        if last_error is not None:
+            raise last_error
+        raise ReachFlowError("Request failed", status_code=0, code="api_error")
+
+    async def _request_once(
+        self,
+        method: HttpMethod,
+        path: str,
+        *,
+        body: dict[str, Any] | None,
+        idempotency_key: str | None,
+    ) -> Any:
+        headers = {
+            "Accept": "application/json",
+            "X-API-Key": self._config.api_key,
+        }
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+
+        url = f"{self._config.api_prefix}{path}"
+        timeout = httpx.Timeout(self._config.timeout_ms / 1000)
+
+        try:
+            response = await self._client.request(
+                method,
+                url,
+                headers=headers,
+                json=body,
+                timeout=timeout,
+            )
+        except httpx.TimeoutException as exc:
+            raise ReachFlowError.timeout(self._config.timeout_ms) from exc
+        except httpx.HTTPError as exc:
+            raise ReachFlowError.network(exc) from exc
+
+        data: Any
+        text = response.text
+        if text:
+            try:
+                data = response.json()
+            except ValueError:
+                data = {"raw": text[:500]}
+        else:
+            data = None
+
+        if response.is_error:
+            err = ReachFlowError.from_response(response.status_code, data)
+            retry_after_ms = parse_retry_after_ms(response.headers.get("Retry-After"))
+            if retry_after_ms is not None:
+                raise ReachFlowError(
+                    err.message,
+                    status_code=err.status_code,
+                    code=err.code,
+                    retryable=err.retryable,
+                    retry_after_ms=retry_after_ms,
+                    body=err.body,
+                )
+            raise err
+
+        return data
+
+
+def _backoff_ms(attempt: int) -> int:
+    return int(min(1000 * (2**attempt), 10_000))

reachflow/resources/__init__.py

@@ -0,0 +1 @@
+"""Ressources API ReachFlow."""

reachflow/resources/messages.py

@@ -0,0 +1,220 @@
+from __future__ import annotations
+
+import time
+from typing import Any, cast
+
+from reachflow.errors import ReachFlowError
+from reachflow.http import AsyncHttpClient, HttpClient
+from reachflow.types import (
+    MessageStatusResponse,
+    SendAcceptedResponse,
+    SendBulkResponse,
+    TERMINAL_MESSAGE_STATUSES,
+)
+
+
+class MessagesResource:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def send(
+        self,
+        *,
+        provider_id: str,
+        to: str,
+        message: str,
+        variables: dict[str, str] | None = None,
+        schedule_at: str | None = None,
+        save_contact: bool | None = None,
+        idempotency_key: str | None = None,
+    ) -> SendAcceptedResponse:
+        body = _send_body(
+            provider_id=provider_id,
+            to=to,
+            message=message,
+            variables=variables,
+            schedule_at=schedule_at,
+            save_contact=save_contact,
+        )
+        return cast(
+            SendAcceptedResponse,
+            self._http.request(
+                "POST",
+                "/messages/send",
+                body=body,
+                idempotency_key=idempotency_key,
+            ),
+        )
+
+    def send_media(
+        self,
+        *,
+        provider_id: str,
+        to: str,
+        media_url: str,
+        media_type: str,
+        caption: str | None = None,
+        save_contact: bool | None = None,
+        idempotency_key: str | None = None,
+    ) -> SendAcceptedResponse:
+        body: dict[str, Any] = {
+            "providerId": provider_id,
+            "to": to,
+            "mediaUrl": media_url,
+            "mediaType": media_type,
+        }
+        if caption is not None:
+            body["caption"] = caption
+        if save_contact is not None:
+            body["saveContact"] = save_contact
+        return cast(
+            SendAcceptedResponse,
+            self._http.request(
+                "POST",
+                "/messages/send-media",
+                body=body,
+                idempotency_key=idempotency_key,
+            ),
+        )
+
+    def send_bulk(
+        self,
+        *,
+        provider_id: str,
+        message_template: str,
+        recipients: list[dict[str, Any]],
+        schedule_at: str | None = None,
+        save_contact: bool | None = None,
+        idempotency_key: str | None = None,
+    ) -> SendBulkResponse:
+        body: dict[str, Any] = {
+            "providerId": provider_id,
+            "messageTemplate": message_template,
+            "recipients": recipients,
+        }
+        if schedule_at is not None:
+            body["scheduleAt"] = schedule_at
+        if save_contact is not None:
+            body["saveContact"] = save_contact
+        return cast(
+            SendBulkResponse,
+            self._http.request(
+                "POST",
+                "/messages/send-bulk",
+                body=body,
+                idempotency_key=idempotency_key,
+            ),
+        )
+
+    def get_status(self, message_id: str) -> MessageStatusResponse:
+        return cast(
+            MessageStatusResponse,
+            self._http.request("GET", f"/messages/{message_id}"),
+        )
+
+    def wait_for_terminal(
+        self,
+        message_id: str,
+        *,
+        poll_interval_ms: int = 2_000,
+        timeout_ms: int = 120_000,
+    ) -> MessageStatusResponse:
+        started = time.monotonic()
+        while (time.monotonic() - started) * 1000 < timeout_ms:
+            status = self.get_status(message_id)
+            if status.get("status") in TERMINAL_MESSAGE_STATUSES:
+                return status
+            time.sleep(poll_interval_ms / 1000)
+
+        raise ReachFlowError(
+            f"Message {message_id} did not reach a terminal status within {timeout_ms}ms",
+            status_code=408,
+            code="timeout",
+            retryable=False,
+        )
+
+
+class AsyncMessagesResource:
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def send(
+        self,
+        *,
+        provider_id: str,
+        to: str,
+        message: str,
+        variables: dict[str, str] | None = None,
+        schedule_at: str | None = None,
+        save_contact: bool | None = None,
+        idempotency_key: str | None = None,
+    ) -> SendAcceptedResponse:
+        body = _send_body(
+            provider_id=provider_id,
+            to=to,
+            message=message,
+            variables=variables,
+            schedule_at=schedule_at,
+            save_contact=save_contact,
+        )
+        return cast(
+            SendAcceptedResponse,
+            await self._http.request(
+                "POST",
+                "/messages/send",
+                body=body,
+                idempotency_key=idempotency_key,
+            ),
+        )
+
+    async def get_status(self, message_id: str) -> MessageStatusResponse:
+        return cast(
+            MessageStatusResponse,
+            await self._http.request("GET", f"/messages/{message_id}"),
+        )
+
+    async def wait_for_terminal(
+        self,
+        message_id: str,
+        *,
+        poll_interval_ms: int = 2_000,
+        timeout_ms: int = 120_000,
+    ) -> MessageStatusResponse:
+        import asyncio
+
+        started = time.monotonic()
+        while (time.monotonic() - started) * 1000 < timeout_ms:
+            status = await self.get_status(message_id)
+            if status.get("status") in TERMINAL_MESSAGE_STATUSES:
+                return status
+            await asyncio.sleep(poll_interval_ms / 1000)
+
+        raise ReachFlowError(
+            f"Message {message_id} did not reach a terminal status within {timeout_ms}ms",
+            status_code=408,
+            code="timeout",
+            retryable=False,
+        )
+
+
+def _send_body(
+    *,
+    provider_id: str,
+    to: str,
+    message: str,
+    variables: dict[str, str] | None,
+    schedule_at: str | None,
+    save_contact: bool | None,
+) -> dict[str, Any]:
+    body: dict[str, Any] = {
+        "providerId": provider_id,
+        "to": to,
+        "message": message,
+    }
+    if variables is not None:
+        body["variables"] = variables
+    if schedule_at is not None:
+        body["scheduleAt"] = schedule_at
+    if save_contact is not None:
+        body["saveContact"] = save_contact
+    return body

reachflow/resources/otp.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+from typing import Any, cast
+
+from reachflow.http import AsyncHttpClient, HttpClient
+from reachflow.types import OtpSendResponse, OtpVerifyResponse
+
+
+class OtpResource:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def send(
+        self,
+        *,
+        provider_id: str,
+        phone_number: str,
+        code_length: int | None = None,
+        expires_in: int | None = None,
+        brand_name: str | None = None,
+        template: str | None = None,
+        save_contact: bool | None = None,
+    ) -> OtpSendResponse:
+        body = _otp_send_body(
+            provider_id=provider_id,
+            phone_number=phone_number,
+            code_length=code_length,
+            expires_in=expires_in,
+            brand_name=brand_name,
+            template=template,
+            save_contact=save_contact,
+        )
+        return cast(OtpSendResponse, self._http.request("POST", "/otp/send", body=body))
+
+    def verify(self, *, otp_id: str, code: str) -> OtpVerifyResponse:
+        return cast(
+            OtpVerifyResponse,
+            self._http.request(
+                "POST",
+                "/otp/verify",
+                body={"otpId": otp_id, "code": code},
+            ),
+        )
+
+
+class AsyncOtpResource:
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def send(
+        self,
+        *,
+        provider_id: str,
+        phone_number: str,
+        code_length: int | None = None,
+        expires_in: int | None = None,
+        brand_name: str | None = None,
+        template: str | None = None,
+        save_contact: bool | None = None,
+    ) -> OtpSendResponse:
+        body = _otp_send_body(
+            provider_id=provider_id,
+            phone_number=phone_number,
+            code_length=code_length,
+            expires_in=expires_in,
+            brand_name=brand_name,
+            template=template,
+            save_contact=save_contact,
+        )
+        return cast(
+            OtpSendResponse,
+            await self._http.request("POST", "/otp/send", body=body),
+        )
+
+    async def verify(self, *, otp_id: str, code: str) -> OtpVerifyResponse:
+        return cast(
+            OtpVerifyResponse,
+            await self._http.request(
+                "POST",
+                "/otp/verify",
+                body={"otpId": otp_id, "code": code},
+            ),
+        )
+
+
+def _otp_send_body(
+    *,
+    provider_id: str,
+    phone_number: str,
+    code_length: int | None,
+    expires_in: int | None,
+    brand_name: str | None,
+    template: str | None,
+    save_contact: bool | None,
+) -> dict[str, Any]:
+    body: dict[str, Any] = {
+        "providerId": provider_id,
+        "phoneNumber": phone_number,
+    }
+    if code_length is not None:
+        body["codeLength"] = code_length
+    if expires_in is not None:
+        body["expiresIn"] = expires_in
+    if brand_name is not None:
+        body["brandName"] = brand_name
+    if template is not None:
+        body["template"] = template
+    if save_contact is not None:
+        body["saveContact"] = save_contact
+    return body

reachflow/resources/providers.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from typing import cast
+
+from reachflow.http import AsyncHttpClient, HttpClient
+from reachflow.types import ProviderDetail, ProviderListResponse, ProviderSummary
+
+
+class ProvidersResource:
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def list(self) -> ProviderListResponse:
+        return cast(ProviderListResponse, self._http.request("GET", "/providers"))
+
+    def get(self, provider_id: str) -> ProviderDetail:
+        return cast(
+            ProviderDetail,
+            self._http.request("GET", f"/providers/{provider_id}"),
+        )
+
+    def find_connected(self) -> ProviderSummary | None:
+        data = self.list()
+        providers = data.get("providers", [])
+        if not providers:
+            return None
+        for provider in providers:
+            if str(provider.get("status", "")).lower() == "connected":
+                return provider
+        return providers[0]
+
+
+class AsyncProvidersResource:
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def list(self) -> ProviderListResponse:
+        return cast(
+            ProviderListResponse,
+            await self._http.request("GET", "/providers"),
+        )
+
+    async def get(self, provider_id: str) -> ProviderDetail:
+        return cast(
+            ProviderDetail,
+            await self._http.request("GET", f"/providers/{provider_id}"),
+        )

reachflow/types.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+from typing import Literal, TypedDict
+
+DEFAULT_BASE_URL = "https://sandbox-api.reachflow.me"
+
+MessageStatus = Literal[
+    "queued",
+    "processing",
+    "sent",
+    "delivered",
+    "failed",
+    "cancelled",
+]
+
+MediaType = Literal["image", "document", "audio", "video"]
+
+FailureCode = Literal[
+    "warmup_daily_limit",
+    "risk_circuit_open",
+    "provider_disconnected",
+    "provider_banned",
+    "send_not_allowed",
+    "instance_busy",
+    "delivery_timeout",
+    "delivery_failed",
+    "send_error",
+    "provider_not_found",
+]
+
+OtpVerifyReason = Literal[
+    "invalidated",
+    "already_used",
+    "expired",
+    "max_attempts_reached",
+    "invalid_code",
+    "not_found",
+]
+
+TERMINAL_MESSAGE_STATUSES: frozenset[MessageStatus] = frozenset(
+    {"sent", "delivered", "failed", "cancelled"}
+)
+
+
+class SendAcceptedResponse(TypedDict):
+    messageId: str
+    status: Literal["queued"]
+    queuedAt: str
+
+
+class BulkRejection(TypedDict):
+    to: str
+    reason: str
+
+
+class SendBulkResponse(TypedDict):
+    bulkId: str
+    accepted: int
+    rejected: int
+    rejections: list[BulkRejection]
+    messageIds: list[str]
+
+
+class MessageStatusResponse(TypedDict, total=False):
+    messageId: str
+    status: MessageStatus
+    to: str
+    providerId: str
+    queuedAt: str
+    sentAt: str | None
+    deliveredAt: str | None
+    failedAt: str | None
+    failureCode: FailureCode | None
+    failureReason: str | None
+
+
+class ProviderSummary(TypedDict):
+    id: str
+    name: str
+    phoneNumber: str | None
+    status: str
+    warmupDay: int
+    riskScore: int
+
+
+class ProviderDailyStats(TypedDict):
+    sent: int
+    delivered: int
+    failed: int
+    messagesLimit: int | None
+    newContactsLimit: int | None
+
+
+class ProviderDetail(ProviderSummary, total=False):
+    dailyStats: ProviderDailyStats
+
+
+class ProviderListResponse(TypedDict):
+    providers: list[ProviderSummary]
+
+
+class OtpSendResponse(TypedDict):
+    otpId: str
+    messageId: str
+    expiresAt: str
+
+
+class OtpVerifyResponse(TypedDict, total=False):
+    valid: bool
+    reason: OtpVerifyReason
+    attemptsLeft: int

reachflow-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,14 @@
+reachflow/__init__.py,sha256=VJsKAJSzloPpqR9Ob6DwHr8w8tFIVix1OX0Q63G584s,473
+reachflow/client.py,sha256=keUt4Slo4UrRtsfQ0H39Muj1CDC8s0Zh5f8LMBQ3-KA,3200
+reachflow/errors.py,sha256=N2zhwOBIfyv1SJQFdVSLzFg-s8pi6UBQYaeT0WuJaHo,3340
+reachflow/http.py,sha256=jQvaWBwev4e_EoHkGkFtcDdfJB9JFwt9vGztJibdAJo,7085
+reachflow/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+reachflow/types.py,sha256=71sT8LY7cJILBZJAcQYNziP4TssYNe_EkRyUiThhil8,2121
+reachflow/resources/__init__.py,sha256=uoEG8Y9o6wd1_n6R1P24MLdJXhjLwUQZ1NCw5nLxO7I,32
+reachflow/resources/messages.py,sha256=FjKFqpts3VdOmPESqoGzqIE60KabwgkoA6WS_-Ykiew,6261
+reachflow/resources/otp.py,sha256=6tIQ0vS6RtdF0yWav4nkm2QttUrRmSaEMsntfIFzgog,3137
+reachflow/resources/providers.py,sha256=1oVm_2R5TQKzg7vo7Y6S0td4JUCMRcwdwCseLp_Mlz0,1441
+reachflow-0.1.0.dist-info/METADATA,sha256=-r_QssP-wWgRIJ1HiMoZe0oLSNG1sBt2YNbJTrNbLPY,3268
+reachflow-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+reachflow-0.1.0.dist-info/licenses/LICENSE,sha256=0DNSEXAHyOVVF3BLEQelnrEyWKAlvHaFbu8hQAEPDo8,1066
+reachflow-0.1.0.dist-info/RECORD,,

reachflow-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

reachflow-0.1.0.dist-info/licenses/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.