funnelchat 0.4.0__py3-none-any.whl

funnelchat/__init__.py

@@ -0,0 +1,86 @@
+"""The official Python SDK of the Funnelchat API.
+
+    from funnelchat import Funnelchat
+
+    client = Funnelchat()  # reads FUNNELCHAT_API_KEY
+    result = client.messages.send_direct(device_id=3, phone="5491100000000", text="Hi Ana!")
+    print(result["message"]["id"], result["message"]["status"])  # 1002 queued
+
+The types of the responses and of the webhook events are in `funnelchat.types`.
+"""
+
+from . import webhooks
+from ._client import BASE_URLS, DEFAULT_MAX_RETRIES, DEFAULT_TIMEOUT, Funnelchat, ResponseInfo
+from ._error_codes import (
+    ACCESS_ERROR_CODES,
+    GROUP_ACTION_ERROR_CODES,
+    IDEMPOTENCY_ERROR_CODES,
+    NOT_RETRYABLE_CODES,
+    NUMBER_ERROR_CODES,
+    SEND_ERROR_CODES,
+    TEMPLATE_SYNC_ERROR_CODES,
+    is_number_quota_error,
+    is_send_rule_error,
+)
+from ._errors import (
+    APIConnectionError,
+    APIConnectionTimeoutError,
+    APIError,
+    AuthenticationError,
+    BadRequestError,
+    ConflictError,
+    FunnelchatError,
+    InternalServerError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    UnprocessableEntityError,
+    UnsupportedMediaTypeError,
+    WebhookVerificationError,
+)
+from ._pagination import Page
+from ._resource import NOT_GIVEN, NotGiven
+from ._routes import ROUTE_GROUPS, ROUTES, WEBHOOK_EVENTS, Route, RouteGroup, WebhookEventInfo
+from ._version import __version__
+
+__all__ = [
+    "Funnelchat",
+    "ResponseInfo",
+    "BASE_URLS",
+    "DEFAULT_TIMEOUT",
+    "DEFAULT_MAX_RETRIES",
+    "Page",
+    "NOT_GIVEN",
+    "NotGiven",
+    "webhooks",
+    "ROUTES",
+    "ROUTE_GROUPS",
+    "WEBHOOK_EVENTS",
+    "Route",
+    "RouteGroup",
+    "WebhookEventInfo",
+    "FunnelchatError",
+    "APIError",
+    "BadRequestError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ConflictError",
+    "UnsupportedMediaTypeError",
+    "UnprocessableEntityError",
+    "RateLimitError",
+    "InternalServerError",
+    "APIConnectionError",
+    "APIConnectionTimeoutError",
+    "WebhookVerificationError",
+    "ACCESS_ERROR_CODES",
+    "SEND_ERROR_CODES",
+    "NUMBER_ERROR_CODES",
+    "GROUP_ACTION_ERROR_CODES",
+    "IDEMPOTENCY_ERROR_CODES",
+    "TEMPLATE_SYNC_ERROR_CODES",
+    "NOT_RETRYABLE_CODES",
+    "is_send_rule_error",
+    "is_number_quota_error",
+    "__version__",
+]

funnelchat/_client.py

@@ -0,0 +1,266 @@
+"""The client of the Funnelchat public API."""
+
+from __future__ import annotations
+
+import json
+import os
+import platform
+import time
+from typing import Any, Callable, Dict, Mapping, Optional, Tuple
+
+import httpx
+
+from ._error_codes import NOT_RETRYABLE_CODES
+from ._errors import APIConnectionError, APIConnectionTimeoutError, APIError, FunnelchatError, request_id_of
+from ._pagination import Page
+from ._query import interpolate_path, serialize_query
+from ._retry import is_retryable, is_send_request, retry_delay
+from ._version import __version__
+from .resources import ClientResources
+
+__all__ = ["Funnelchat", "ResponseInfo", "BASE_URLS", "DEFAULT_TIMEOUT", "DEFAULT_MAX_RETRIES"]
+
+#: The base URL of each environment: one URL for the whole public API.
+BASE_URLS: Dict[str, str] = {
+    "production": "https://api.funnelchat.com",
+    "staging": "https://api-staging.funnelchat.com",
+}
+#: Maximum seconds of each attempt.
+DEFAULT_TIMEOUT = 30.0
+#: Automatic retries (see the README, Retries).
+DEFAULT_MAX_RETRIES = 2
+
+
+class ResponseInfo:
+    """What the API answered to one request, besides the body: `status`, `request_id` (the
+    `X-Request-Id`, quote it when you report a problem), `headers`, `method` and `url`."""
+
+    def __init__(self, status: int, headers: httpx.Headers, method: str, url: str) -> None:
+        self.status = status
+        self.headers = headers
+        self.method = method
+        self.url = url
+        self.request_id = request_id_of(headers)
+
+    def __repr__(self) -> str:
+        return f"<ResponseInfo {self.method} {self.url} {self.status} request_id={self.request_id}>"
+
+
+class Funnelchat(ClientResources):
+    """Client of the Funnelchat public API.
+
+        from funnelchat import Funnelchat
+
+        client = Funnelchat()  # reads FUNNELCHAT_API_KEY
+        for device in client.devices.list():
+            print(device["id"], device["alias"])
+
+    Responses are plain dicts (the decoded JSON), typed with the TypedDicts of `funnelchat.types`.
+    The key never shows up in `repr(client)` or in an error.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: Optional[str] = None,
+        environment: str = "production",
+        base_url: Optional[str] = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        default_headers: Optional[Mapping[str, str]] = None,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        """
+        - `api_key`: `<id>|fc_live_...`. Default: the `FUNNELCHAT_API_KEY` environment variable.
+        - `environment`: `production` (`https://api.funnelchat.com`) or `staging`.
+        - `base_url`: another base URL (for example the sandbox's); it wins over `environment`.
+        - `timeout`: maximum seconds of each attempt. Default 30.
+        - `max_retries`: automatic retries on `429`, `5xx` and network errors. Default 2; 0 turns them off.
+        - `default_headers`: headers sent with every request.
+        - `http_client`: your own `httpx.Client` (proxies, transports…). You close it.
+        """
+        key = api_key if api_key is not None else os.environ.get("FUNNELCHAT_API_KEY", "")
+        key = key.strip()
+        if not key:
+            raise FunnelchatError(
+                "Missing API key: pass it as `api_key` or in the FUNNELCHAT_API_KEY environment variable."
+            )
+        if environment not in BASE_URLS:
+            raise FunnelchatError(f'Unknown environment: {environment!r}. Use "production" or "staging".')
+        self._api_key = key
+        self.base_url = (base_url or BASE_URLS[environment]).rstrip("/")
+        self.timeout = float(timeout)
+        self.max_retries = int(max_retries)
+        self._default_headers = dict(default_headers or {})
+        self._owns_http = http_client is None
+        self._http = http_client if http_client is not None else httpx.Client()
+        self._sleep: Callable[[float], None] = time.sleep
+        #: The status, headers and `X-Request-Id` of the last response this client got.
+        self.last_response: Optional[ResponseInfo] = None
+        self._init_resources()
+
+    def __repr__(self) -> str:
+        return f"Funnelchat(base_url={self.base_url!r}, timeout={self.timeout:g}, max_retries={self.max_retries})"
+
+    def close(self) -> None:
+        """Closes the HTTP connections (only those of the httpx.Client the SDK built)."""
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self) -> "Funnelchat":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    # -- any route ------------------------------------------------------------------------------
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        path_params: Optional[Mapping[str, Any]] = None,
+        query: Optional[Mapping[str, Any]] = None,
+        body: Any = None,
+        headers: Optional[Mapping[str, str]] = None,
+        timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+        retry_send: bool = False,
+        idempotency_key: Optional[str] = None,
+    ) -> Any:
+        """Calls any route and returns the decoded body (None for an empty answer).
+
+            contact = client.request("GET", "/api/v1/contacts/{contact}", path_params={"contact": 2001})
+        """
+        body_out, _ = self._send(
+            method,
+            path,
+            path_params=path_params,
+            query=query,
+            body=body,
+            headers=headers,
+            timeout=timeout,
+            max_retries=max_retries,
+            retry_send=retry_send,
+            idempotency_key=idempotency_key,
+        )
+        return body_out
+
+    def paginate(
+        self,
+        path: str,
+        *,
+        path_params: Optional[Mapping[str, Any]] = None,
+        query: Optional[Mapping[str, Any]] = None,
+        headers: Optional[Mapping[str, str]] = None,
+        timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+    ) -> Page[Any]:
+        """Fetches the first page of any list route; iterate it for every item of every page."""
+        first_query = dict(query or {})
+
+        def fetch(page_query: Dict[str, Any]) -> Tuple[Any, Optional[str]]:
+            return self._send(
+                "GET",
+                path,
+                path_params=path_params,
+                query=page_query,
+                headers=headers,
+                timeout=timeout,
+                max_retries=max_retries,
+            )
+
+        body, request_id = fetch(first_query)
+        return Page(fetch, first_query, body, request_id)
+
+    # -- transport --------------------------------------------------------------------------------
+
+    def _send(
+        self,
+        method: str,
+        template: str,
+        *,
+        path_params: Optional[Mapping[str, Any]] = None,
+        query: Optional[Mapping[str, Any]] = None,
+        body: Any = None,
+        headers: Optional[Mapping[str, str]] = None,
+        timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+        retry_send: bool = False,
+        idempotency_key: Optional[str] = None,
+    ) -> Tuple[Any, Optional[str]]:
+        verb = method.upper()
+        pathname = interpolate_path(template, path_params)
+        url = self.base_url + (pathname if pathname.startswith("/") else f"/{pathname}")
+        attempts = max(0, self.max_retries if max_retries is None else int(max_retries))
+        attempt_timeout = self.timeout if timeout is None else float(timeout)
+        is_send = is_send_request(verb, pathname.split("?")[0])
+        # A send is never repeated unless the caller asks; then it follows the rule of every write.
+        retries_allowed = retry_send or not is_send
+        # With an idempotency key the API answers the same resource to a repeated create, so it is
+        # retried like a PUT (as in funnelchat-php). A send is not, key or no key.
+        retry_as = "PUT" if idempotency_key is not None and not is_send else verb
+
+        request_headers: Dict[str, str] = {
+            "Accept": "application/json",
+            "User-Agent": f"funnelchat-python/{__version__} python/{platform.python_version()}",
+        }
+        content: Optional[bytes] = None
+        if body is not None:
+            content = body if isinstance(body, bytes) else json.dumps(body, ensure_ascii=False).encode("utf-8")
+            request_headers["Content-Type"] = "application/json"
+        request_headers.update(self._default_headers)
+        request_headers.update(headers or {})
+        if idempotency_key is not None:
+            if not 1 <= len(idempotency_key) <= 255:
+                raise FunnelchatError("`idempotency_key` must have between 1 and 255 characters.")
+            request_headers["Idempotency-Key"] = idempotency_key
+        request_headers["Authorization"] = f"Bearer {self._api_key}"
+        params = tuple(serialize_query(query))
+
+        attempt = 0
+        while True:
+            can_retry = retries_allowed and attempt < attempts
+            try:
+                response = self._http.request(
+                    verb, url, params=params, content=content, headers=request_headers, timeout=attempt_timeout
+                )
+            except httpx.TimeoutException:
+                failure: APIConnectionError = APIConnectionTimeoutError(attempt_timeout)
+            except httpx.RequestError as error:
+                failure = APIConnectionError(f"Could not connect to the Funnelchat API: {type(error).__name__}.")
+            else:
+                self.last_response = ResponseInfo(response.status_code, response.headers, verb, url)
+                decoded = _decode(response)
+                if response.is_success:
+                    return decoded, self.last_response.request_id
+                api_error = APIError.from_response(
+                    status=response.status_code, body=decoded, headers=response.headers, method=verb, url=url
+                )
+                if can_retry and is_retryable(retry_as, response.status_code) and api_error.code not in NOT_RETRYABLE_CODES:
+                    delay = retry_delay(attempt, api_error.retry_after)
+                    if delay is not None:
+                        self._sleep(delay)
+                        attempt += 1
+                        continue
+                raise api_error
+            if can_retry and is_retryable(retry_as, None):
+                self._sleep(retry_delay(attempt, None) or 0.0)
+                attempt += 1
+                continue
+            raise failure
+
+
+def _decode(response: httpx.Response) -> Any:
+    """The body: JSON when it parses, the text otherwise, None when there is none (a `204`)."""
+    text = response.text
+    if text == "":
+        return None
+    content_type = response.headers.get("content-type", "")
+    if "json" in content_type or text.lstrip()[:1] in ("{", "["):
+        try:
+            return json.loads(text)
+        except ValueError:
+            return text
+    return text

funnelchat/_error_codes.py

@@ -0,0 +1,142 @@
+"""The stable `error` codes of the API (`APIError.code`), with their HTTP status.
+
+Decide by `status` and `code`, never by `message`: its text and language change by area. The same
+tables as funnelchat-node 0.4.0 (src/core/error-codes.ts). Sources, all in production on
+04-11-2026: the key gate as accounts v1.5.97 runs it; the API entry as deployed to production on
+25-10-2026; conversations v1.19.7 (the send rules and the checks before sending a form); accounts
+v1.5.97 (creating and connecting numbers); communities v2.35.5 and v2.35.7 (the rejections of a
+group action). The spec the portal publishes (portal v0.6.13) documents some of these codes in the
+operations that answer them, but not those of the API entry and the key gate. When it documents all
+of them, these tables can be generated.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, FrozenSet, Optional
+
+__all__ = [
+    "ACCESS_ERROR_CODES",
+    "SEND_ERROR_CODES",
+    "NUMBER_ERROR_CODES",
+    "GROUP_ACTION_ERROR_CODES",
+    "IDEMPOTENCY_ERROR_CODES",
+    "TEMPLATE_SYNC_ERROR_CODES",
+    "NOT_RETRYABLE_CODES",
+    "is_send_rule_error",
+    "is_number_quota_error",
+]
+
+#: Errors of the API entry and of the key gate, on any route.
+ACCESS_ERROR_CODES: Dict[str, int] = {
+    "unauthenticated": 401,  # missing or invalid API key
+    "permission_denied": 403,  # the key lacks the permission the route needs (`message` names it)
+    "route_not_available": 403,  # the route is not open to API keys (or is turned off)
+    "route_not_found": 404,  # the path does not exist in the public API
+    "daily_cap_exceeded": 429,  # with Retry-After: the daily call cap of the key in that area
+    "edge_misconfigured": 500,  # our problem: report it with the request id
+    "origin_unreachable": 502,  # no guarantee the area did not get the call: read the state after a write
+    "gate_unavailable": 503,  # with Retry-After: nothing ran; safe to retry
+}
+
+#: Rejections of a send with an API key: nothing was sent and nothing was stored.
+SEND_ERROR_CODES: Dict[str, int] = {
+    "rate_limited": 429,  # with Retry-After: the number's pace
+    "mac_lockout_24h": 429,  # 24-hour lockout after using up the monthly active contacts; not worth retrying
+    "mac_limit_reached": 429,  # the monthly active contacts are used up; not worth retrying
+    "window_closed": 422,  # free text outside the 24-hour window on an official number: send a template
+    "antiblock_duplicate_content": 422,  # the same content again to a contact that did not answer
+    "antiblock_unanswered_limit": 422,  # too many messages in a row to a contact that did not answer
+    "recipient_mismatch": 422,  # the `phone` / `whatsapp_id` is not the contact of the route
+    "recipient_unsupported": 422,  # the contact is a group, a broadcast list or a channel
+    "provider_unsupported": 422,  # the number cannot send this (see its `capabilities`)
+    "device_unavailable": 422,  # the number is not connected or cannot send now
+    "not_sent": 422,  # the message could not be registered for sending
+    "recipient_unreachable": 422,  # the contact cannot be reached on WhatsApp (forms)
+    "contact_blocked": 422,  # the contact is blocked on that number (forms)
+    "template_unresolved_placeholder": 422,  # a template variable points to a field that does not exist
+    "template_not_found": 404,  # the template is not one this account can send
+    "form_not_found": 404,  # the form does not exist
+    "form_not_published": 422,  # the form is not published
+    "form_not_on_number": 422,  # the form is not published on that number
+    "number_not_eligible": 422,  # the number cannot send forms
+}
+
+#: Rejections of creating a number, asking for its QR or creating, reading or revoking a connect
+#: link: nothing was created. A code with two statuses has the one of the create here.
+NUMBER_ERROR_CODES: Dict[str, int] = {
+    "numbers_not_included": 403,  # the plan does not include numbers
+    "number_limit_reached": 403,  # every number of the plan is in use (`limit`, `used`, `pending_device_ids`)
+    "connect_not_allowed": 403,  # the account cannot connect numbers now
+    "payment_required": 403,  # `devices.qr()` of a number whose payment is due
+    "pending_number_exists": 409,  # a QR number is already waiting to be scanned; the body brings its `device_id`
+    "qr_requires_coexistence": 422,  # (409 on `devices.qr()`) QR only on an official number in coexistence
+    "method_already_present": 422,  # the number already has that method; the body brings its `device_id`
+    "invalid_reference_device": 422,  # `same_number_as` or `device_id` is not a number that can take it
+    "connection_type_mismatch": 422,  # a link with `device_id` of a number that connects another way
+    "number_suspended_by_plan": 422,  # (409 on `devices.qr()`) suspended: the plan has fewer numbers
+    "invalid_request": 422,  # the body is not valid; `errors` says which fields
+    "trial_number_blocked": 409,  # `devices.qr()` of a trial number that is blocked
+    "device_inactive": 409,  # `devices.qr()` of a number that is turned off
+    "provisioning_quota_exceeded": 409,  # `devices.qr()` when no more QR sessions can start now
+    "link_not_pending": 409,  # revoking a connect link that already ended
+    "too_many_open_links": 429,  # 20 connect links open: revoke some; not worth retrying
+    "provider_error": 500,  # (502 on `devices.qr()`) the WhatsApp provider failed
+    "meta_connect_disabled": 503,  # official numbers cannot be connected by link yet; QR links work
+    "credentials_not_allowed": 403,  # the connect page was opened with a key or a session
+}
+
+#: Rejections of a message to a group, of following a group and of reading a group action: nothing
+#: was queued or imported. A number or group of another workspace is answered as missing.
+GROUP_ACTION_ERROR_CODES: Dict[str, int] = {
+    "device_not_found": 404,  # `device_id` is not a number of the key's workspace
+    "group_not_found": 404,  # the group is not one of the key's workspace
+    "action_not_found": 404,  # `groups.retrieve_action()` of an action that does not exist
+    "unsupported_group_type": 422,  # the uid is a community or a channel, not a group
+    "device_not_connected": 422,  # the number is not connected
+    "device_not_group_admin": 422,  # a QR number that is not admin of the group
+    "device_not_group_number": 422,  # an official group that belongs to another number
+    "provider_unsupported": 422,  # the number cannot do it (`provider`, maybe `requires`, in the body)
+    "window_closed": 422,  # an official number outside the 24-hour window of the group
+    "number_restricted": 422,  # Meta restricted the official number
+    "unsupported_type": 422,  # that `type` cannot be sent to this group by this number
+    "too_many_pending_actions": 429,  # 50 group actions open on the number; not worth retrying
+    "import_permission_required": 403,  # following a group needs Groups and campaigns → Manage groups
+    "import_rate_limited": 429,  # with Retry-After: the number already followed 5 groups this minute
+    "import_in_progress": 409,  # another call is following the same group right now
+}
+
+#: Rejections of a create sent with `idempotency_key`.
+IDEMPOTENCY_ERROR_CODES: Dict[str, int] = {
+    "idempotency_key_mismatch": 422,  # the key was already used with another body
+    "invalid_idempotency_key": 422,  # the key is not 1 to 255 characters
+    "operation_in_progress": 409,  # the first call with that key is still running
+}
+
+#: Rejections of bringing a number's templates from Meta (`templates.sync()`), as the spec the portal
+#: publishes (portal v0.6.13) enumerates them for `POST /api/v1/devices/{device}/templates`. A number
+#: that does not exist, or is of another workspace, is a `404` without a code.
+TEMPLATE_SYNC_ERROR_CODES: Dict[str, int] = {
+    "template_sync_in_progress": 409,  # one is already running for that number: do not start another
+    "number_not_connected_to_meta": 422,  # a QR number, or one without a WhatsApp Business account or credentials
+    "meta_rejected": 422,  # Meta refused and nothing was brought; its code in `meta_code`
+    "meta_unavailable": 502,  # Meta did not answer
+}
+
+#: Codes a retry would only repeat: never retried automatically.
+NOT_RETRYABLE_CODES: FrozenSet[str] = frozenset(
+    {"mac_lockout_24h", "mac_limit_reached", "too_many_open_links", "too_many_pending_actions", "meta_connect_disabled"}
+)
+
+_QUOTA_CODES = frozenset(
+    {"numbers_not_included", "number_limit_reached", "pending_number_exists", "qr_requires_coexistence", "method_already_present"}
+)
+
+
+def is_send_rule_error(code: Optional[str]) -> bool:
+    """Whether an `APIError.code` is a rejection of a send: nothing was sent and nothing was stored."""
+    return code is not None and code in SEND_ERROR_CODES
+
+
+def is_number_quota_error(code: Optional[str]) -> bool:
+    """Whether an `APIError.code` is a rejection by the number quota of the plan (the same as the panel's)."""
+    return code is not None and code in _QUOTA_CODES