goomzo 0.1.0__tar.gz

goomzo-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+.venv
+__pycache__
+.pytest_cache
+.ruff_cache
+dist

goomzo-0.1.0/LICENSE

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

goomzo-0.1.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.5
+Name: goomzo
+Version: 0.1.0
+Summary: The Goomzo API for Python: messages, templates, customers and webhooks.
+Project-URL: Homepage, https://goomzo.africa
+Project-URL: Documentation, https://docs.goomzo.africa/docs/developers/python-sdk
+Author-email: Goomzo <hello@goomzo.africa>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,customers,goomzo,sms,tanzania,whatsapp
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: typing-extensions>=4.10
+Description-Content-Type: text/markdown
+
+# goomzo
+
+The [Goomzo API](https://docs.goomzo.africa/docs/developers/python-sdk) for Python: send SMS and WhatsApp messages,
+send saved templates, keep customers in step, and check webhooks. Sync and asyncio, fully typed.
+
+```bash
+pip install goomzo
+```
+
+```python
+from goomzo import Goomzo
+
+goomzo = Goomzo()  # reads GOOMZO_API_KEY
+
+# One message.
+goomzo.messages.send_one({'to': '+255712345678', 'channel': 'sms', 'content': {'text': 'Your order is ready.'}})
+
+# A saved template. {{secret.code}} is delivered, but kept as ••••••.
+goomzo.messages.send_one({'to': '+255712345678', 'template': 'auth_1', 'variables': {'code': '482913'}})
+
+# Add or update a customer, with their segments and activity.
+goomzo.customers.create(
+    [{'name': 'Amina Juma', 'phone': '+255712345678', 'segments': [{'name': 'Shoppers'}]}],
+    if_exists='update',
+)
+
+# Every customer in a segment, a page at a time behind the scenes.
+for customer in goomzo.segments.customers.list('seg_4hq2v9n1c8x0t6pk'):
+    print(customer['name'])
+```
+
+With asyncio:
+
+```python
+from goomzo import AsyncGoomzo
+
+goomzo = AsyncGoomzo()
+await goomzo.messages.send_one({'to': '+255712345678', 'template': 'auth_1', 'variables': {'code': '482913'}})
+```
+
+## What it does for you
+
+- **Typed:** every request and answer is a typed dict, with the API's own keys.
+- **A fixed version:** it pins the API version it was written for.
+- **Safe retries:** network errors, 429 and 5xx are tried again, twice by default. Every POST carries an
+  `Idempotency-Key`, the same on each try, so nothing is done twice.
+- **Lists page themselves:** loop over a list for every item.
+- **Errors you can act on:** a `GoomzoError` has the `status`, the `code`, the `fields` that were wrong and the
+  `request_id`.
+
+## Webhooks
+
+```python
+from goomzo import verify_webhook
+
+event = verify_webhook(request.body, request.headers, os.environ['GOOMZO_WEBHOOK_SECRET'])
+if event['type'] == 'message.delivered':
+    ...
+```

goomzo-0.1.0/README.md

@@ -0,0 +1,59 @@
+# goomzo
+
+The [Goomzo API](https://docs.goomzo.africa/docs/developers/python-sdk) for Python: send SMS and WhatsApp messages,
+send saved templates, keep customers in step, and check webhooks. Sync and asyncio, fully typed.
+
+```bash
+pip install goomzo
+```
+
+```python
+from goomzo import Goomzo
+
+goomzo = Goomzo()  # reads GOOMZO_API_KEY
+
+# One message.
+goomzo.messages.send_one({'to': '+255712345678', 'channel': 'sms', 'content': {'text': 'Your order is ready.'}})
+
+# A saved template. {{secret.code}} is delivered, but kept as ••••••.
+goomzo.messages.send_one({'to': '+255712345678', 'template': 'auth_1', 'variables': {'code': '482913'}})
+
+# Add or update a customer, with their segments and activity.
+goomzo.customers.create(
+    [{'name': 'Amina Juma', 'phone': '+255712345678', 'segments': [{'name': 'Shoppers'}]}],
+    if_exists='update',
+)
+
+# Every customer in a segment, a page at a time behind the scenes.
+for customer in goomzo.segments.customers.list('seg_4hq2v9n1c8x0t6pk'):
+    print(customer['name'])
+```
+
+With asyncio:
+
+```python
+from goomzo import AsyncGoomzo
+
+goomzo = AsyncGoomzo()
+await goomzo.messages.send_one({'to': '+255712345678', 'template': 'auth_1', 'variables': {'code': '482913'}})
+```
+
+## What it does for you
+
+- **Typed:** every request and answer is a typed dict, with the API's own keys.
+- **A fixed version:** it pins the API version it was written for.
+- **Safe retries:** network errors, 429 and 5xx are tried again, twice by default. Every POST carries an
+  `Idempotency-Key`, the same on each try, so nothing is done twice.
+- **Lists page themselves:** loop over a list for every item.
+- **Errors you can act on:** a `GoomzoError` has the `status`, the `code`, the `fields` that were wrong and the
+  `request_id`.
+
+## Webhooks
+
+```python
+from goomzo import verify_webhook
+
+event = verify_webhook(request.body, request.headers, os.environ['GOOMZO_WEBHOOK_SECRET'])
+if event['type'] == 'message.delivered':
+    ...
+```

goomzo-0.1.0/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@goomzo/sdk-python",
+  "version": "0.1.0",
+  "private": true,
+  "description": "The goomzo Python package, run by turbo through uv.",
+  "scripts": {
+    "lint": "uv run --frozen ruff check && uv run --frozen ruff format --check",
+    "check-types": "uv run --frozen pyright && uv run --frozen ty check src tests",
+    "test": "uv run --frozen pytest -q",
+    "build": "uv build"
+  }
+}

goomzo-0.1.0/pyproject.toml

@@ -0,0 +1,65 @@
+[project]
+name = "goomzo"
+dynamic = ["version"]
+description = "The Goomzo API for Python: messages, templates, customers and webhooks."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Goomzo", email = "hello@goomzo.africa" }]
+requires-python = ">=3.10"
+dependencies = ["httpx>=0.27,<1", "typing-extensions>=4.10"]
+keywords = ["goomzo", "sms", "whatsapp", "customers", "tanzania", "api"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Typing :: Typed",
+  "Intended Audience :: Developers",
+]
+
+[project.urls]
+Homepage = "https://goomzo.africa"
+Documentation = "https://docs.goomzo.africa/docs/developers/python-sdk"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.24",
+    "pyright>=1.1.390",
+    "ruff>=0.8",
+    "pyyaml>=6",
+    "ty>=0.0.101",
+]
+
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "package.json"
+pattern = '"version": "(?P<version>[^"]+)"'
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/goomzo"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/goomzo", "README.md", "LICENSE", "package.json"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.ruff.format]
+quote-style = "single"
+
+[tool.pyright]
+include = ["src", "tests"]
+pythonVersion = "3.10"
+typeCheckingMode = "strict"
+executionEnvironments = [{ root = "tests", reportPrivateUsage = false }]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

goomzo-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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