goomzo 0.1.0__py3-none-any.whl

goomzo/__init__.py

@@ -0,0 +1,26 @@
+"""The Goomzo API for Python: messages, templates, customers and webhooks."""
+
+from ._client import AsyncGoomzo, Goomzo
+from ._errors import FieldProblem, GoomzoConnectionError, GoomzoError, WebhookVerificationError
+from ._pagination import AsyncPage, AsyncPager, Page
+from ._transport import API_VERSION, Media
+from ._version import VERSION
+from ._webhooks import verify_webhook
+
+__version__ = VERSION
+
+__all__ = [
+    'API_VERSION',
+    'AsyncGoomzo',
+    'AsyncPage',
+    'AsyncPager',
+    'FieldProblem',
+    'Goomzo',
+    'GoomzoConnectionError',
+    'GoomzoError',
+    'Media',
+    'Page',
+    'WebhookVerificationError',
+    '__version__',
+    'verify_webhook',
+]

goomzo/_client.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+from types import TracebackType
+
+import httpx
+from typing_extensions import Self
+
+from ._transport import AsyncTransport, SyncTransport, make_config
+from .resources.broadcasts import AsyncBroadcasts, Broadcasts
+from .resources.customers import ActivityRecorder, AsyncActivityRecorder, AsyncCustomers, Customers
+from .resources.messages import AsyncMessages, Messages
+from .resources.segments import AsyncSegments, Segments
+from .resources.templates import AsyncTemplates, AsyncWhatsApp, Templates, WhatsApp
+from .resources.webhook_endpoints import AsyncWebhookEndpoints, WebhookEndpoints
+
+
+class Goomzo:
+    """
+    The Goomzo API client. Make one and share it across your app.
+
+        from goomzo import Goomzo
+
+        goomzo = Goomzo()  # reads GOOMZO_API_KEY
+        goomzo.messages.send_one({'to': '+255712345678', 'channel': 'sms', 'content': {'text': 'Your order is ready.'}})
+
+    `api_key` is your API key's secret, `gzk_…`: keep it on your server. A failed request is tried again
+    `max_retries` times after a network error, a 429 or a 5xx, and each try waits up to `timeout` seconds.
+
+    Docs: https://docs.goomzo.africa/docs/developers/python-sdk
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        max_retries: int = 2,
+        timeout: float = 60.0,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._transport = SyncTransport(make_config(api_key, base_url, max_retries, timeout), http_client)
+        self.messages = Messages(self._transport)
+        """Send SMS and WhatsApp messages, each to one person."""
+        self.broadcasts = Broadcasts(self._transport)
+        """Send one message to many people."""
+        self.templates = Templates(self._transport)
+        """Saved templates, sent by name."""
+        self.whatsapp = WhatsApp(self._transport)
+        """The business's WhatsApp account and its templates."""
+        self.customers = Customers(self._transport)
+        """Add and update customers."""
+        self.activity = ActivityRecorder(self._transport)
+        """Record customer activity, by phone, email or id."""
+        self.segments = Segments(self._transport)
+        """Groups of customers."""
+        self.webhook_endpoints = WebhookEndpoints(self._transport)
+        """URLs that hear webhook events."""
+
+    def close(self) -> None:
+        """Closes the connections it opened. Not needed for an http_client you gave it."""
+        self._transport.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, kind: type[BaseException] | None, error: BaseException | None, tb: TracebackType | None) -> None:
+        self.close()
+
+
+class AsyncGoomzo:
+    """
+    The Goomzo API client, for asyncio. The same as `Goomzo`, with every call awaited.
+
+        from goomzo import AsyncGoomzo
+
+        goomzo = AsyncGoomzo()
+        await goomzo.messages.send_one({'to': '+255712345678', 'template': 'auth_1', 'variables': {'code': '482913'}})
+
+    Docs: https://docs.goomzo.africa/docs/developers/python-sdk
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        max_retries: int = 2,
+        timeout: float = 60.0,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._transport = AsyncTransport(make_config(api_key, base_url, max_retries, timeout), http_client)
+        self.messages = AsyncMessages(self._transport)
+        """Send SMS and WhatsApp messages, each to one person."""
+        self.broadcasts = AsyncBroadcasts(self._transport)
+        """Send one message to many people."""
+        self.templates = AsyncTemplates(self._transport)
+        """Saved templates, sent by name."""
+        self.whatsapp = AsyncWhatsApp(self._transport)
+        """The business's WhatsApp account and its templates."""
+        self.customers = AsyncCustomers(self._transport)
+        """Add and update customers."""
+        self.activity = AsyncActivityRecorder(self._transport)
+        """Record customer activity, by phone, email or id."""
+        self.segments = AsyncSegments(self._transport)
+        """Groups of customers."""
+        self.webhook_endpoints = AsyncWebhookEndpoints(self._transport)
+        """URLs that hear webhook events."""
+
+    async def close(self) -> None:
+        """Closes the connections it opened. Not needed for an http_client you gave it."""
+        await self._transport.close()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self, kind: type[BaseException] | None, error: BaseException | None, tb: TracebackType | None
+    ) -> None:
+        await self.close()

goomzo/_errors.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from typing_extensions import TypedDict
+
+
+class FieldProblem(TypedDict):
+    """A problem with one field of a request."""
+
+    code: str
+    message: str
+
+
+class GoomzoError(Exception):
+    """
+    The API answered with an error.
+
+    `code` says what went wrong, such as `invalid`, `not_found` or `insufficient_sms`. `fields` names the fields that
+    were wrong, such as `customers[1].phone`. Include `request_id` when you contact Goomzo.
+    """
+
+    def __init__(
+        self,
+        status: int,
+        code: str,
+        message: str,
+        fields: dict[str, FieldProblem] | None = None,
+        request_id: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.message = message
+        self.fields: dict[str, FieldProblem] = fields or {}
+        self.request_id = request_id
+
+    def __repr__(self) -> str:
+        return f'GoomzoError(status={self.status}, code={self.code!r}, message={self.message!r})'
+
+
+class GoomzoConnectionError(Exception):
+    """No answer came: the network failed, or the request took longer than the timeout."""
+
+    def __init__(self, message: str, *, timed_out: bool) -> None:
+        super().__init__(message)
+        self.timed_out = timed_out
+
+
+class WebhookVerificationError(Exception):
+    """A webhook's signature or timestamp didn't check out. Don't trust its body."""

goomzo/_pagination.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Awaitable, Callable, Generator, Iterator
+from typing import Any, Generic, TypeVar
+
+T = TypeVar('T')
+
+
+class Page(Generic[T]):
+    """
+    One page of a list. Loop over it for every item: the next pages are asked for as you go.
+
+        page = goomzo.customers.list(limit=200)
+        page.items, page.next_cursor, page.total
+
+        for customer in goomzo.customers.list():
+            print(customer['name'])
+    """
+
+    def __init__(self, data: Any, fetch: Callable[[str], Page[T]]) -> None:
+        self.items: list[T] = data['items']
+        self.next_cursor: str | None = data.get('nextCursor')
+        self.total: int | None = data.get('total')
+        """How many match, on every page. Only customers, messages and broadcasts have it."""
+        self._fetch = fetch
+
+    def next_page(self) -> Page[T] | None:
+        """The next page, or None on the last."""
+        return self._fetch(self.next_cursor) if self.next_cursor else None
+
+    def __iter__(self) -> Iterator[T]:
+        page: Page[T] | None = self
+        while page is not None:
+            yield from page.items
+            page = page.next_page()
+
+
+class AsyncPage(Generic[T]):
+    """One page of a list, for asyncio. `async for` over it for every item."""
+
+    def __init__(self, data: Any, fetch: Callable[[str], Awaitable[AsyncPage[T]]]) -> None:
+        self.items: list[T] = data['items']
+        self.next_cursor: str | None = data.get('nextCursor')
+        self.total: int | None = data.get('total')
+        self._fetch = fetch
+
+    async def next_page(self) -> AsyncPage[T] | None:
+        """The next page, or None on the last."""
+        return await self._fetch(self.next_cursor) if self.next_cursor else None
+
+    async def __aiter__(self) -> AsyncIterator[T]:
+        page: AsyncPage[T] | None = self
+        while page is not None:
+            for item in page.items:
+                yield item
+            page = await page.next_page()
+
+
+class AsyncPager(Generic[T]):
+    """
+    A list for asyncio. Await it for the first page, or `async for` over it for every item.
+
+        page = await goomzo.customers.list(limit=200)
+
+        async for customer in goomzo.customers.list():
+            print(customer['name'])
+    """
+
+    def __init__(self, first: Callable[[], Awaitable[AsyncPage[T]]]) -> None:
+        self._first = first
+
+    def __await__(self) -> Generator[Any, None, AsyncPage[T]]:
+        return self._first().__await__()
+
+    async def __aiter__(self) -> AsyncIterator[T]:
+        async for item in await self._first():
+            yield item

goomzo/_transport.py

@@ -0,0 +1,229 @@
+from __future__ import annotations
+
+import asyncio
+import os
+import random
+import time
+import uuid
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any, Literal, cast
+from urllib.parse import quote
+
+import httpx
+
+from ._errors import FieldProblem, GoomzoConnectionError, GoomzoError
+from ._version import VERSION
+
+API_VERSION = '2026-11-08'
+"""The API version this release is written for. Every request is sent with it, as `Goomzo-Version`."""
+
+DEFAULT_BASE_URL = 'https://api.goomzo.africa'
+
+Method = Literal['GET', 'POST', 'PUT', 'PATCH', 'DELETE']
+Query = Mapping[str, Any]
+
+_RETRY_STATUSES = frozenset({408, 429, 500, 502, 503, 504})
+
+
+@dataclass(frozen=True)
+class Media:
+    """A file a customer sent on WhatsApp."""
+
+    content: bytes
+    content_type: str
+
+
+@dataclass(frozen=True)
+class _Config:
+    api_key: str
+    base_url: str
+    max_retries: int
+    timeout: float
+
+
+def make_config(api_key: str | None, base_url: str | None, max_retries: int, timeout: float) -> _Config:
+    key = api_key or os.environ.get('GOOMZO_API_KEY')
+    if not key:
+        raise ValueError('Give an api_key, or set GOOMZO_API_KEY.')
+    return _Config(key, (base_url or DEFAULT_BASE_URL).rstrip('/'), max_retries, timeout)
+
+
+def path(template: str, **params: str) -> str:
+    """Fills a path's `{name}` parts, each encoded: `path('/v1/customers/{id}', id=...)`."""
+    for name, value in params.items():
+        if not value:
+            raise ValueError(f'Missing {name} for {template}')
+        template = template.replace('{' + name + '}', quote(value, safe=''))
+    return template
+
+
+def _headers(config: _Config, method: Method, idempotency_key: str | None, file: bool) -> dict[str, str]:
+    headers = {
+        'Authorization': f'Bearer {config.api_key}',
+        'Accept': '*/*' if file else 'application/json',
+        'Goomzo-Version': API_VERSION,
+        'User-Agent': f'goomzo-python/{VERSION}',
+    }
+    if method == 'POST':
+        headers['Idempotency-Key'] = idempotency_key or str(uuid.uuid4())
+    return headers
+
+
+def _params(query: Query | None) -> dict[str, str]:
+    out: dict[str, str] = {}
+    for name, value in (query or {}).items():
+        if value is None:
+            continue
+        out[name] = ('true' if value else 'false') if isinstance(value, bool) else str(value)
+    return out
+
+
+def _backoff(attempt: int) -> float:
+    """0.5 s, 1 s, 2 s… up to 8 s, with jitter so many clients don't retry together."""
+    return min(0.5 * 2**attempt, 8.0) * (0.75 + random.random() * 0.5)
+
+
+def _retry_after(response: httpx.Response) -> float | None:
+    try:
+        seconds = float(response.headers.get('retry-after', ''))
+    except ValueError:
+        return None
+    return seconds if 0 < seconds <= 60 else None
+
+
+def _to_error(response: httpx.Response) -> GoomzoError:
+    try:
+        raw: Any = response.json()
+    except ValueError:
+        raw = None
+    body: dict[str, Any] = cast(dict[str, Any], raw) if isinstance(raw, dict) else {}
+    fields: dict[str, FieldProblem] = body.get('fields') or {}
+    return GoomzoError(
+        response.status_code,
+        str(body.get('code') or f'http_{response.status_code}'),
+        str(body.get('message') or f'Goomzo answered {response.status_code} {response.reason_phrase}.'),
+        fields,
+        response.headers.get('x-request-id'),
+    )
+
+
+def _should_retry(error: GoomzoError) -> bool:
+    # A key still being answered is safe to wait on; any other 409 is about the request itself.
+    return error.status in _RETRY_STATUSES or error.code == 'idempotency_key_in_use'
+
+
+def _result(response: httpx.Response, file: bool) -> Any:
+    if response.status_code == 204:
+        return None
+    if file:
+        return Media(response.content, response.headers.get('content-type', 'application/octet-stream'))
+    return response.json()
+
+
+def _connection_error(error: httpx.TransportError, timeout: float) -> GoomzoConnectionError:
+    if isinstance(error, httpx.TimeoutException):
+        return GoomzoConnectionError(f'No answer within {timeout:g} s.', timed_out=True)
+    return GoomzoConnectionError(f"Couldn't reach Goomzo: {error}", timed_out=False)
+
+
+class SyncTransport:
+    """Makes requests: authenticates, pins the API version, retries what's safe to, and raises GoomzoError."""
+
+    def __init__(self, config: _Config, http: httpx.Client | None) -> None:
+        self._config = config
+        self._owns_http = http is None
+        self._http = http or httpx.Client()
+
+    def request(
+        self,
+        method: Method,
+        route: str,
+        *,
+        query: Query | None = None,
+        body: object = None,
+        idempotency_key: str | None = None,
+        file: bool = False,
+    ) -> Any:
+        config = self._config
+        headers = _headers(config, method, idempotency_key, file)
+        attempt = 0
+        while True:
+            try:
+                response = self._http.request(
+                    method,
+                    config.base_url + route,
+                    params=_params(query),
+                    json=body,
+                    headers=headers,
+                    timeout=config.timeout,
+                )
+            except httpx.TransportError as error:
+                if attempt < config.max_retries:
+                    time.sleep(_backoff(attempt))
+                    attempt += 1
+                    continue
+                raise _connection_error(error, config.timeout) from error
+            if response.is_success:
+                return _result(response, file)
+            error = _to_error(response)
+            if _should_retry(error) and attempt < config.max_retries:
+                time.sleep(_retry_after(response) or _backoff(attempt))
+                attempt += 1
+                continue
+            raise error
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+
+class AsyncTransport:
+    """The same as SyncTransport, for asyncio."""
+
+    def __init__(self, config: _Config, http: httpx.AsyncClient | None) -> None:
+        self._config = config
+        self._owns_http = http is None
+        self._http = http or httpx.AsyncClient()
+
+    async def request(
+        self,
+        method: Method,
+        route: str,
+        *,
+        query: Query | None = None,
+        body: object = None,
+        idempotency_key: str | None = None,
+        file: bool = False,
+    ) -> Any:
+        config = self._config
+        headers = _headers(config, method, idempotency_key, file)
+        attempt = 0
+        while True:
+            try:
+                response = await self._http.request(
+                    method,
+                    config.base_url + route,
+                    params=_params(query),
+                    json=body,
+                    headers=headers,
+                    timeout=config.timeout,
+                )
+            except httpx.TransportError as error:
+                if attempt < config.max_retries:
+                    await asyncio.sleep(_backoff(attempt))
+                    attempt += 1
+                    continue
+                raise _connection_error(error, config.timeout) from error
+            if response.is_success:
+                return _result(response, file)
+            error = _to_error(response)
+            if _should_retry(error) and attempt < config.max_retries:
+                await asyncio.sleep(_retry_after(response) or _backoff(attempt))
+                attempt += 1
+                continue
+            raise error
+
+    async def close(self) -> None:
+        if self._owns_http:
+            await self._http.aclose()

goomzo/_version.py

@@ -0,0 +1,3 @@
+from importlib.metadata import version
+
+VERSION = version('goomzo')

goomzo/_webhooks.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import base64
+import binascii
+import hashlib
+import hmac
+import json
+import time
+from collections.abc import Mapping
+from typing import cast
+
+from ._errors import WebhookVerificationError
+from .types import WebhookEvent
+
+_TOLERANCE = 5 * 60
+
+
+def _header(headers: Mapping[str, str], name: str) -> str | None:
+    value = headers.get(name)
+    if value is not None:
+        return value
+    return next((v for k, v in headers.items() if k.lower() == name), None)
+
+
+def _key(secret: str) -> bytes:
+    raw = secret.removeprefix('whsec_')
+    try:
+        return base64.b64decode(raw, validate=True)
+    except (binascii.Error, ValueError):
+        return raw.encode()
+
+
+def verify_webhook(
+    payload: str | bytes,
+    headers: Mapping[str, str],
+    secret: str,
+    *,
+    now: float | None = None,
+) -> WebhookEvent:
+    """
+    Checks that a webhook delivery came from Goomzo and is recent, then returns its event.
+
+    Pass the body exactly as it arrived, before parsing it: the signature is of those bytes. Pass the request's
+    headers, and the endpoint's signing secret, `whsec_…`.
+
+        event = verify_webhook(request.body, request.headers, os.environ['GOOMZO_WEBHOOK_SECRET'])
+        if event['type'] == 'message.delivered':
+            ...
+
+    Raises WebhookVerificationError when the signature doesn't match, or the delivery is more than 5 minutes old.
+    """
+    webhook_id = _header(headers, 'webhook-id')
+    timestamp = _header(headers, 'webhook-timestamp')
+    signatures = _header(headers, 'webhook-signature')
+    if not webhook_id or not timestamp or not signatures:
+        raise WebhookVerificationError('The webhook-id, webhook-timestamp and webhook-signature headers are needed.')
+
+    try:
+        sent = int(timestamp)
+    except ValueError:
+        raise WebhookVerificationError("The webhook-timestamp isn't a number.") from None
+    if abs((time.time() if now is None else now) - sent) > _TOLERANCE:
+        raise WebhookVerificationError('The delivery is too old, or from the future: check your clock.')
+
+    body = payload if isinstance(payload, bytes) else payload.encode()
+    signed = webhook_id.encode() + b'.' + timestamp.encode() + b'.' + body
+    expected = base64.b64encode(hmac.new(_key(secret), signed, hashlib.sha256).digest()).decode()
+
+    # While a secret is being rotated, a delivery carries a signature for each: any of them will do.
+    for part in signatures.split(' '):
+        version, _, signature = part.partition(',')
+        if version == 'v1' and hmac.compare_digest(signature, expected):
+            break
+    else:
+        raise WebhookVerificationError("The signature doesn't match: check the secret is this endpoint's.")
+
+    try:
+        return cast(WebhookEvent, json.loads(body))
+    except ValueError:
+        raise WebhookVerificationError("The body isn't JSON.") from None

goomzo/resources/broadcasts.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+from typing import cast
+
+from .._pagination import AsyncPage, AsyncPager, Page
+from .._transport import AsyncTransport, SyncTransport, path
+from ..types import Broadcast, BroadcastInput, BroadcastStatus, Channel
+
+
+class Broadcasts:
+    """
+    Broadcasts: one message to segments, a list of numbers, or every customer, filled in for each person.
+
+    Docs: https://docs.goomzo.africa/docs/developers/messages/broadcasts
+    """
+
+    def __init__(self, transport: SyncTransport) -> None:
+        self._t = transport
+
+    def create(self, broadcast: BroadcastInput, *, idempotency_key: str | None = None) -> Broadcast:
+        """
+        Sends a broadcast, now or at `sendAt`. `audience` is required: leaving it out is an error, never a send to
+        everyone.
+
+            goomzo.broadcasts.create({
+                'name': 'Black Friday',
+                'channel': 'sms',
+                'content': {'text': 'Hi {{name|there}}, 20% off today.'},
+                'audience': {'segments': [{'name': 'VIP'}]},
+            })
+        """
+        return cast(
+            Broadcast, self._t.request('POST', '/v1/broadcasts', body=broadcast, idempotency_key=idempotency_key)
+        )
+
+    def get(self, id: str) -> Broadcast:
+        """Gets a broadcast, with how its messages are doing."""
+        return cast(Broadcast, self._t.request('GET', path('/v1/broadcasts/{id}', id=id)))
+
+    def list(
+        self,
+        *,
+        q: str | None = None,
+        channel: Channel | None = None,
+        status: BroadcastStatus | None = None,
+        limit: int | None = None,
+    ) -> Page[Broadcast]:
+        """Lists broadcasts, newest first. Loop over the page for all of them."""
+        query = {'q': q, 'channel': channel, 'status': status, 'limit': limit}
+
+        def fetch(cursor: str | None = None) -> Page[Broadcast]:
+            return Page(self._t.request('GET', '/v1/broadcasts', query={**query, 'cursor': cursor}), fetch)
+
+        return fetch()
+
+    def cancel(self, id: str) -> Broadcast:
+        """Cancels a scheduled broadcast before it goes."""
+        return cast(Broadcast, self._t.request('POST', path('/v1/broadcasts/{id}/cancel', id=id)))
+
+
+class AsyncBroadcasts:
+    """Broadcasts, for asyncio. See `Broadcasts`."""
+
+    def __init__(self, transport: AsyncTransport) -> None:
+        self._t = transport
+
+    async def create(self, broadcast: BroadcastInput, *, idempotency_key: str | None = None) -> Broadcast:
+        """Sends a broadcast, now or at `sendAt`."""
+        return cast(
+            Broadcast, await self._t.request('POST', '/v1/broadcasts', body=broadcast, idempotency_key=idempotency_key)
+        )
+
+    async def get(self, id: str) -> Broadcast:
+        """Gets a broadcast, with how its messages are doing."""
+        return cast(Broadcast, await self._t.request('GET', path('/v1/broadcasts/{id}', id=id)))
+
+    def list(
+        self,
+        *,
+        q: str | None = None,
+        channel: Channel | None = None,
+        status: BroadcastStatus | None = None,
+        limit: int | None = None,
+    ) -> AsyncPager[Broadcast]:
+        """Lists broadcasts, newest first. Await it for one page, or `async for` over it for all of them."""
+        query = {'q': q, 'channel': channel, 'status': status, 'limit': limit}
+
+        async def fetch(cursor: str | None = None) -> AsyncPage[Broadcast]:
+            return AsyncPage(await self._t.request('GET', '/v1/broadcasts', query={**query, 'cursor': cursor}), fetch)
+
+        return AsyncPager(fetch)
+
+    async def cancel(self, id: str) -> Broadcast:
+        """Cancels a scheduled broadcast before it goes."""
+        return cast(Broadcast, await self._t.request('POST', path('/v1/broadcasts/{id}/cancel', id=id)))