sadakio 0.1.0__tar.gz

sadakio-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.egg-info/
+dist/
+.pytest_cache/

sadakio-0.1.0/LICENSE

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

sadakio-0.1.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.5
+Name: sadakio
+Version: 0.1.0
+Summary: Sadakio API client — read a business's own guests, visits and retention
+Project-URL: Homepage, https://sadakio.com/gelistirici
+Project-URL: Examples, https://github.com/lio-maker/sadakio-examples
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,cafe,loyalty,retention,sadakio,sdk
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# sadakio
+
+Python client for the [Sadakio](https://sadakio.com) Public API. It reads
+**one business's own** guests, visits and retention numbers.
+
+Sadakio is the operating layer for small hospitality businesses in Türkiye:
+guest base, loyalty programme, return visits, QR menu, Apple Wallet cards. If
+you are building for cafés, salons or shops — your own product, a dashboard for
+a client, or an integration with a POS you already sell — this is the read side
+of that data without you having to build and run a loyalty engine.
+
+Read-only today, because the Public API v1 is read-only.
+
+```bash
+pip install sadakio
+```
+
+The same name works in both ecosystems: `npm install sadakio` and
+`pip install sadakio`.
+
+## Get a key
+
+A business owner creates the key in the Sadakio panel under **Ayarlar → API**.
+The raw key is shown once, at creation; only its fingerprint is stored.
+
+Each key belongs to exactly one business and carries the `read` scope. It can
+never name another business's row — a foreign id answers `404`, not `403`, so
+the API cannot be used to discover what exists elsewhere.
+
+## Use it
+
+```python
+import os
+from sadakio import Sadakio
+
+sadakio = Sadakio(api_key=os.environ["SADAKIO_API_KEY"])
+
+# one page
+page = sadakio.list_guests(limit=50)
+print(page["data"], page["next_cursor"])
+
+# or every guest, without writing the pagination yourself
+for guest in sadakio.iter_guests(updated_since=last_sync):
+    print(guest["name"], guest["visits_count"], guest["masked_phone"])
+
+# returned-guest numbers for the last month
+summary = sadakio.retention(period="month")["data"]
+```
+
+There is an async client with the same surface:
+
+```python
+from sadakio import AsyncSadakio
+
+async with AsyncSadakio(api_key=key) as sadakio:
+    async for guest in sadakio.iter_guests():
+        ...
+```
+
+| Call | What it answers |
+|---|---|
+| `list_guests(**params)` / `iter_guests(**params)` | The guest base. `updated_since` matches guests who visited **or** were created since that moment, so an incremental sync never misses a brand-new guest. |
+| `get_guest(id)` | One guest with their loyalty cards and balances. |
+| `list_visits(**params)` / `iter_visits(**params)` | The earn-event feed: stamps, points, cashback, redeems. |
+| `retention(**params)` | Returned-guest numbers over a window. |
+
+## Options
+
+```python
+Sadakio(
+    api_key=...,                               # required
+    base_url="https://api.sadakio.com/api/v1", # default
+    timeout_s=30.0,                            # default
+    max_retries=2,                             # 429 and 5xx only
+)
+```
+
+Retries happen only where waiting can actually help — a rate limit or a server
+error — and wait exactly as long as `Retry-After` says. A `404` is never
+retried, because waiting cannot make it true.
+
+## Four things worth knowing before you trust a number
+
+**Phones are always masked.** Last four digits only, and there is no unmasked
+path. This is a KVKK decision, not a scope you can request your way past.
+
+**Pagination is by cursor.** `iter_guests()` and `iter_visits()` walk it for you and stops on a null
+cursor — not on an empty page, which is the usual way a hand-written sync
+truncates itself.
+
+**A reversed earn keeps its row**, with `reversed_at` set. History is never
+deleted, so exclude reversed rows yourself when you count.
+
+**No money figure is invented.** `retention()` returns
+`estimated_returned_value` only when you supply a real `avg_ticket`.
+
+## Errors
+
+Every failure is a `SadakioError` carrying `status`, `code` and a message that
+includes the one step that fixes it. `err.is_retryable` tells you whether trying
+again could plausibly work.
+
+```python
+from sadakio import SadakioError
+
+try:
+    sadakio.get_guest(guest_id)
+except SadakioError as err:
+    if err.code == "not_found":
+        ...
+```
+
+## Contract
+
+The machine-readable contract is served publicly, without a key, at
+`https://api.sadakio.com/api/v1/openapi.yaml`. Response fields may be **added**
+over time, never renamed or removed — so parse leniently and a release will not
+break you.
+
+Working with an AI assistant? There is an MCP server too: `uvx sadakio-mcp`.
+
+Examples you can read and run: <https://github.com/lio-maker/sadakio-examples>
+
+Docs: <https://sadakio.com/gelistirici> · Questions: biz@sadakio.com
+
+Python 3.10 and up. MIT licensed. Built by the Sadakio team, and pull requests are welcome.

sadakio-0.1.0/README.md

@@ -0,0 +1,126 @@
+# sadakio
+
+Python client for the [Sadakio](https://sadakio.com) Public API. It reads
+**one business's own** guests, visits and retention numbers.
+
+Sadakio is the operating layer for small hospitality businesses in Türkiye:
+guest base, loyalty programme, return visits, QR menu, Apple Wallet cards. If
+you are building for cafés, salons or shops — your own product, a dashboard for
+a client, or an integration with a POS you already sell — this is the read side
+of that data without you having to build and run a loyalty engine.
+
+Read-only today, because the Public API v1 is read-only.
+
+```bash
+pip install sadakio
+```
+
+The same name works in both ecosystems: `npm install sadakio` and
+`pip install sadakio`.
+
+## Get a key
+
+A business owner creates the key in the Sadakio panel under **Ayarlar → API**.
+The raw key is shown once, at creation; only its fingerprint is stored.
+
+Each key belongs to exactly one business and carries the `read` scope. It can
+never name another business's row — a foreign id answers `404`, not `403`, so
+the API cannot be used to discover what exists elsewhere.
+
+## Use it
+
+```python
+import os
+from sadakio import Sadakio
+
+sadakio = Sadakio(api_key=os.environ["SADAKIO_API_KEY"])
+
+# one page
+page = sadakio.list_guests(limit=50)
+print(page["data"], page["next_cursor"])
+
+# or every guest, without writing the pagination yourself
+for guest in sadakio.iter_guests(updated_since=last_sync):
+    print(guest["name"], guest["visits_count"], guest["masked_phone"])
+
+# returned-guest numbers for the last month
+summary = sadakio.retention(period="month")["data"]
+```
+
+There is an async client with the same surface:
+
+```python
+from sadakio import AsyncSadakio
+
+async with AsyncSadakio(api_key=key) as sadakio:
+    async for guest in sadakio.iter_guests():
+        ...
+```
+
+| Call | What it answers |
+|---|---|
+| `list_guests(**params)` / `iter_guests(**params)` | The guest base. `updated_since` matches guests who visited **or** were created since that moment, so an incremental sync never misses a brand-new guest. |
+| `get_guest(id)` | One guest with their loyalty cards and balances. |
+| `list_visits(**params)` / `iter_visits(**params)` | The earn-event feed: stamps, points, cashback, redeems. |
+| `retention(**params)` | Returned-guest numbers over a window. |
+
+## Options
+
+```python
+Sadakio(
+    api_key=...,                               # required
+    base_url="https://api.sadakio.com/api/v1", # default
+    timeout_s=30.0,                            # default
+    max_retries=2,                             # 429 and 5xx only
+)
+```
+
+Retries happen only where waiting can actually help — a rate limit or a server
+error — and wait exactly as long as `Retry-After` says. A `404` is never
+retried, because waiting cannot make it true.
+
+## Four things worth knowing before you trust a number
+
+**Phones are always masked.** Last four digits only, and there is no unmasked
+path. This is a KVKK decision, not a scope you can request your way past.
+
+**Pagination is by cursor.** `iter_guests()` and `iter_visits()` walk it for you and stops on a null
+cursor — not on an empty page, which is the usual way a hand-written sync
+truncates itself.
+
+**A reversed earn keeps its row**, with `reversed_at` set. History is never
+deleted, so exclude reversed rows yourself when you count.
+
+**No money figure is invented.** `retention()` returns
+`estimated_returned_value` only when you supply a real `avg_ticket`.
+
+## Errors
+
+Every failure is a `SadakioError` carrying `status`, `code` and a message that
+includes the one step that fixes it. `err.is_retryable` tells you whether trying
+again could plausibly work.
+
+```python
+from sadakio import SadakioError
+
+try:
+    sadakio.get_guest(guest_id)
+except SadakioError as err:
+    if err.code == "not_found":
+        ...
+```
+
+## Contract
+
+The machine-readable contract is served publicly, without a key, at
+`https://api.sadakio.com/api/v1/openapi.yaml`. Response fields may be **added**
+over time, never renamed or removed — so parse leniently and a release will not
+break you.
+
+Working with an AI assistant? There is an MCP server too: `uvx sadakio-mcp`.
+
+Examples you can read and run: <https://github.com/lio-maker/sadakio-examples>
+
+Docs: <https://sadakio.com/gelistirici> · Questions: biz@sadakio.com
+
+Python 3.10 and up. MIT licensed. Built by the Sadakio team, and pull requests are welcome.

sadakio-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sadakio"
+version = "0.1.0"
+description = "Sadakio API client — read a business's own guests, visits and retention"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+keywords = ["sadakio", "loyalty", "api", "cafe", "retention", "sdk"]
+dependencies = ["httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://sadakio.com/gelistirici"
+Examples = "https://github.com/lio-maker/sadakio-examples"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sadakio"]

sadakio-0.1.0/src/sadakio/__init__.py

@@ -0,0 +1,22 @@
+"""Sadakio API client.
+
+    from sadakio import Sadakio
+
+    sadakio = Sadakio(api_key=os.environ["SADAKIO_API_KEY"])
+    summary = sadakio.retention(period="month")
+"""
+
+from ._client import AsyncSadakio, Sadakio
+from ._constants import DEFAULT_BASE_URL, PACKAGE_NAME, VERSION
+from ._errors import ERROR_CODES, SadakioError
+
+__all__ = [
+    "Sadakio",
+    "AsyncSadakio",
+    "SadakioError",
+    "ERROR_CODES",
+    "VERSION",
+    "PACKAGE_NAME",
+    "DEFAULT_BASE_URL",
+]
+__version__ = VERSION

sadakio-0.1.0/src/sadakio/_client.py

@@ -0,0 +1,212 @@
+"""The sync and async clients for the Sadakio Public API v1.
+
+Read-only, because v1 is read-only. Every call is scoped to the one business the
+key belongs to.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import time
+from collections.abc import AsyncIterator, Iterator
+from typing import Any, Literal
+
+import httpx
+
+from . import _core
+from ._constants import DEFAULT_BASE_URL
+from ._errors import SadakioError
+
+
+class _Base:
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout_s: float = 30.0,
+        max_retries: int = 2,
+    ) -> None:
+        # Environment fallbacks are read HERE rather than as default arguments,
+        # which are bound once at import and would ignore anything set later.
+        # The same two variables the MCP server reads, so one product does not
+        # honour a setting in half its surfaces and silently ignore it in the
+        # other. An explicit argument always wins.
+        api_key = api_key or os.environ.get("SADAKIO_API_KEY")
+        base_url = base_url or os.environ.get("SADAKIO_BASE_URL") or DEFAULT_BASE_URL
+        if not api_key:
+            raise SadakioError(
+                401, "unauthorized",
+                "No API key: pass api_key or set SADAKIO_API_KEY.",
+            )
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout_s = timeout_s
+        self.max_retries = max_retries
+
+    def _url(self, path: str) -> str:
+        return f"{self.base_url}{path}"
+
+
+class Sadakio(_Base):
+    """Synchronous client.
+
+    >>> sadakio = Sadakio(api_key=os.environ["SADAKIO_API_KEY"])
+    >>> for guest in sadakio.iter_guests(updated_since="2026-09-01T00:00:00Z"):
+    ...     print(guest["name"], guest["visits_count"])
+    """
+
+    def __init__(self, *args: Any, transport: httpx.BaseTransport | None = None, **kw: Any) -> None:
+        super().__init__(*args, **kw)
+        self._http = httpx.Client(timeout=self.timeout_s, transport=transport)
+
+    def __enter__(self) -> Sadakio:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def request(self, path: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        url = self._url(path)
+        attempt = 0
+        while True:
+            try:
+                res = self._http.get(
+                    url, params=_core.clean_params(params), headers=_core.headers(self.api_key)
+                )
+                return _core.interpret(res, url)
+            except SadakioError as err:
+                if not err.is_retryable or attempt >= self.max_retries:
+                    raise
+                time.sleep(_core.backoff_seconds(err, attempt))
+                attempt += 1
+            except httpx.HTTPError as err:
+                wrapped = _core.wrap_transport_error(err, self.base_url, url, self.timeout_s)
+                if attempt >= self.max_retries:
+                    raise wrapped from None
+                time.sleep(_core.backoff_seconds(wrapped, attempt))
+                attempt += 1
+
+    # --- the four shipped read endpoints -------------------------------------
+
+    def list_guests(self, **params: Any) -> dict[str, Any]:
+        return self.request("/guests", params)
+
+    def get_guest(self, guest_id: int) -> dict[str, Any]:
+        return self.request(f"/guests/{int(guest_id)}")
+
+    def list_visits(self, **params: Any) -> dict[str, Any]:
+        return self.request("/visits", params)
+
+    def retention(
+        self,
+        since: str | None = None,
+        until: str | None = None,
+        period: Literal["week", "month", "year"] | None = None,
+        avg_ticket: float | None = None,
+    ) -> dict[str, Any]:
+        return self.request(
+            "/stats/retention",
+            {"since": since, "until": until, "period": period, "avg_ticket": avg_ticket},
+        )
+
+    # --- pagination ----------------------------------------------------------
+
+    def _paginate(self, path: str, params: dict[str, Any]) -> Iterator[dict[str, Any]]:
+        """Walks every page and yields rows one at a time.
+
+        Pagination is the part every caller reimplements and half of them get
+        wrong — most often by stopping on an empty page instead of on a null
+        cursor, which silently truncates a sync.
+        """
+        cursor = params.get("cursor")
+        while True:
+            page = self.request(path, {**params, "cursor": cursor})
+            yield from page.get("data") or []
+            cursor = page.get("next_cursor")
+            if cursor is None:
+                return
+
+    def iter_guests(self, **params: Any) -> Iterator[dict[str, Any]]:
+        return self._paginate("/guests", params)
+
+    def iter_visits(self, **params: Any) -> Iterator[dict[str, Any]]:
+        return self._paginate("/visits", params)
+
+
+class AsyncSadakio(_Base):
+    """Asynchronous client, same surface as :class:`Sadakio`."""
+
+    def __init__(self, *args: Any, transport: httpx.AsyncBaseTransport | None = None, **kw: Any) -> None:
+        super().__init__(*args, **kw)
+        self._http = httpx.AsyncClient(timeout=self.timeout_s, transport=transport)
+
+    async def __aenter__(self) -> AsyncSadakio:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def request(self, path: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        url = self._url(path)
+        attempt = 0
+        while True:
+            try:
+                res = await self._http.get(
+                    url, params=_core.clean_params(params), headers=_core.headers(self.api_key)
+                )
+                return _core.interpret(res, url)
+            except SadakioError as err:
+                if not err.is_retryable or attempt >= self.max_retries:
+                    raise
+                await asyncio.sleep(_core.backoff_seconds(err, attempt))
+                attempt += 1
+            except httpx.HTTPError as err:
+                wrapped = _core.wrap_transport_error(err, self.base_url, url, self.timeout_s)
+                if attempt >= self.max_retries:
+                    raise wrapped from None
+                await asyncio.sleep(_core.backoff_seconds(wrapped, attempt))
+                attempt += 1
+
+    async def list_guests(self, **params: Any) -> dict[str, Any]:
+        return await self.request("/guests", params)
+
+    async def get_guest(self, guest_id: int) -> dict[str, Any]:
+        return await self.request(f"/guests/{int(guest_id)}")
+
+    async def list_visits(self, **params: Any) -> dict[str, Any]:
+        return await self.request("/visits", params)
+
+    async def retention(
+        self,
+        since: str | None = None,
+        until: str | None = None,
+        period: Literal["week", "month", "year"] | None = None,
+        avg_ticket: float | None = None,
+    ) -> dict[str, Any]:
+        return await self.request(
+            "/stats/retention",
+            {"since": since, "until": until, "period": period, "avg_ticket": avg_ticket},
+        )
+
+    async def _paginate(self, path: str, params: dict[str, Any]) -> AsyncIterator[dict[str, Any]]:
+        cursor = params.get("cursor")
+        while True:
+            page = await self.request(path, {**params, "cursor": cursor})
+            for row in page.get("data") or []:
+                yield row
+            cursor = page.get("next_cursor")
+            if cursor is None:
+                return
+
+    def iter_guests(self, **params: Any) -> AsyncIterator[dict[str, Any]]:
+        return self._paginate("/guests", params)
+
+    def iter_visits(self, **params: Any) -> AsyncIterator[dict[str, Any]]:
+        return self._paginate("/visits", params)

sadakio-0.1.0/src/sadakio/_constants.py

@@ -0,0 +1,10 @@
+"""The package's identity, in one place.
+
+Renaming a published package touches the manifest, the readme, every example
+and the user agent. Keeping it here means the next rename is one line.
+"""
+
+PACKAGE_NAME = "sadakio"
+VERSION = "0.1.0"
+DEFAULT_BASE_URL = "https://api.sadakio.com/api/v1"
+USER_AGENT = f"{PACKAGE_NAME}-py/{VERSION}"

sadakio-0.1.0/src/sadakio/_core.py

@@ -0,0 +1,93 @@
+"""The parts the sync and async clients must agree on.
+
+Request building and response interpretation live here exactly once, so the two
+clients cannot drift into sending different parameters or explaining the same
+failure two different ways.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from ._constants import USER_AGENT
+from ._errors import SadakioError
+
+
+def headers(api_key: str) -> dict[str, str]:
+    return {
+        "Authorization": f"Bearer {api_key}",
+        "Accept": "application/json",
+        "User-Agent": USER_AGENT,
+    }
+
+
+def clean_params(params: dict[str, Any] | None) -> dict[str, Any]:
+    """Only parameters the caller actually set are sent.
+
+    An unset value must not travel as the string "None": a correct server
+    answers 422, and the caller gets a validation error for a parameter they
+    never set.
+    """
+    if not params:
+        return {}
+    return {k: v for k, v in params.items() if v is not None and v != ""}
+
+
+def interpret(res: httpx.Response, url: str) -> dict[str, Any]:
+    """Turn a response into data, or into an error that says what to do."""
+    retry_after = res.headers.get("retry-after")
+    try:
+        body: Any = res.json()
+    except ValueError:
+        body = None
+
+    if res.status_code >= 400:
+        err = body.get("error") if isinstance(body, dict) else None
+        code = (err or {}).get("code") or f"http_{res.status_code}"
+        message = (err or {}).get("message") or (
+            f"Sadakio answered {res.status_code} with a body this client did not recognise."
+            if res.text
+            else f"Sadakio answered {res.status_code}."
+        )
+        raise SadakioError(
+            res.status_code,
+            code,
+            message,
+            retry_after=float(retry_after) if retry_after else None,
+            url=url,
+        )
+
+    if body is None:
+        raise SadakioError(
+            res.status_code, "invalid_response",
+            "Sadakio answered 200 with a body that is not JSON.", url=url,
+        )
+    if not isinstance(body, dict) or "data" not in body:
+        raise SadakioError(
+            res.status_code, "invalid_response",
+            'Sadakio answered 200 but the body is not a v1 response: no "data" envelope.',
+            url=url,
+        )
+    return body
+
+
+def backoff_seconds(err: SadakioError, attempt: int) -> float:
+    """Retry-After is the server saying exactly how long.
+
+    Guessing shorter is how a client turns one rate limit into several.
+    """
+    if err.retry_after is not None:
+        return err.retry_after
+    return 0.5 * (2**attempt)
+
+
+def wrap_transport_error(err: Exception, base_url: str, url: str, timeout_s: float) -> SadakioError:
+    if isinstance(err, httpx.TimeoutException):
+        return SadakioError(
+            0, "timeout", f"Sadakio did not answer within {timeout_s:g} seconds.", url=url
+        )
+    return SadakioError(
+        0, "network_error", f"Could not reach Sadakio at {base_url}: {err}", url=url
+    )

sadakio-0.1.0/src/sadakio/_errors.py

@@ -0,0 +1,65 @@
+"""The error taxonomy, shared by the sync and async clients."""
+
+from __future__ import annotations
+
+#: Documented error codes, so a caller can branch without parsing prose.
+ERROR_CODES = frozenset(
+    {
+        "unauthorized",
+        "forbidden",
+        "account_inactive",
+        "not_found",
+        "validation_failed",
+        "rate_limited",
+    }
+)
+
+_HINTS = {
+    "unauthorized": (
+        "Create a key in the Sadakio panel, Ayarlar → API. The raw key is shown "
+        "once, at creation."
+    ),
+    "forbidden": (
+        "This key does not carry the scope this call needs, or the business "
+        "account is not active."
+    ),
+    "account_inactive": (
+        "The business account behind this key is not active, so the API is "
+        "closed with the panel."
+    ),
+    "not_found": (
+        "No such row inside this key's own business. A key only ever sees its "
+        "own business, and a foreign id answers 404 rather than revealing that "
+        "it exists."
+    ),
+    "validation_failed": (
+        "Dates are ISO 8601, period is week, month or year, and limit is 1 to 200."
+    ),
+    "invalid_response": (
+        "Check base_url: it must end in /api/v1. A host that answers 200 with "
+        "something else is usually a base URL pointing one level too high, or a "
+        "proxy in front of the API."
+    ),
+}
+
+
+class SadakioError(Exception):
+    def __init__(
+        self,
+        status: int,
+        code: str,
+        message: str,
+        retry_after: float | None = None,
+        url: str | None = None,
+    ) -> None:
+        hint = _HINTS.get(code)
+        super().__init__(f"{message} {hint}" if hint else message)
+        self.status = status
+        self.code = code
+        self.retry_after = retry_after
+        self.url = url
+
+    @property
+    def is_retryable(self) -> bool:
+        """True when waiting and trying the same call again can plausibly work."""
+        return self.code == "rate_limited" or self.status >= 500 or self.status == 0

sadakio-0.1.0/tests/conftest.py

@@ -0,0 +1,31 @@
+import httpx
+import pytest
+
+
+@pytest.fixture(scope="session")
+def anyio_backend():
+    return "asyncio"
+
+
+@pytest.fixture
+def stub():
+    """A transport that answers from a route table and records every request."""
+
+    def make(routes, default=None):
+        calls: list[httpx.Request] = []
+
+        def handler(request: httpx.Request) -> httpx.Response:
+            calls.append(request)
+            entry = routes.get(request.url.path, default)
+            if entry is None:
+                raise AssertionError(f"no stub route for {request.url.path}")
+            if callable(entry):
+                entry = entry(request, len(calls))
+            status, body, headers = entry
+            if isinstance(body, str):
+                return httpx.Response(status, text=body, headers=headers)
+            return httpx.Response(status, json=body, headers=headers)
+
+        return handler, calls
+
+    return make

sadakio-0.1.0/tests/test_sdk.py

@@ -0,0 +1,166 @@
+"""The sync and async clients must behave identically."""
+
+import httpx
+import pytest
+
+from sadakio import AsyncSadakio, Sadakio, SadakioError
+
+
+def guest(i):
+    return {"id": i, "name": f"Guest {i}", "masked_phone": "+••••••••4579", "visits_count": i}
+
+
+def sync_client(handler, **kw):
+    return Sadakio(api_key="sk_test", transport=httpx.MockTransport(handler), **kw)
+
+
+def async_client(handler, **kw):
+    return AsyncSadakio(api_key="sk_test", transport=httpx.MockTransport(handler), **kw)
+
+
+def test_a_client_without_a_key_fails_at_construction(stub):
+    with pytest.raises(SadakioError) as e:
+        Sadakio(api_key=None)
+    assert e.value.code == "unauthorized"
+
+
+def test_the_key_travels_as_a_bearer_token(stub):
+    handler, calls = stub({"/api/v1/guests": (200, {"data": [], "next_cursor": None}, {})})
+    with sync_client(handler) as s:
+        s.list_guests()
+    assert calls[0].headers["authorization"] == "Bearer sk_test"
+    assert calls[0].headers["user-agent"].startswith("sadakio-py/")
+    assert str(calls[0].url.params) == "", "unset parameters must not be sent"
+
+
+def test_iterate_walks_every_page_and_stops_on_a_null_cursor(stub):
+    def pages(request, _n):
+        cursor = request.url.params.get("cursor")
+        if not cursor:
+            return (200, {"data": [guest(1), guest(2)], "next_cursor": 2}, {})
+        if cursor == "2":
+            return (200, {"data": [guest(3)], "next_cursor": 3}, {})
+        # a real tail: the last page can be empty while still ending the walk
+        return (200, {"data": [], "next_cursor": None}, {})
+
+    handler, _ = stub({"/api/v1/guests": pages})
+    with sync_client(handler) as s:
+        assert [g["id"] for g in s.iter_guests()] == [1, 2, 3]
+
+
+@pytest.mark.anyio
+async def test_the_async_client_iterates_the_same_way(stub):
+    def pages(request, _n):
+        cursor = request.url.params.get("cursor")
+        if not cursor:
+            return (200, {"data": [guest(1)], "next_cursor": 1}, {})
+        return (200, {"data": [guest(2)], "next_cursor": None}, {})
+
+    handler, _ = stub({"/api/v1/guests": pages})
+    async with async_client(handler) as s:
+        ids = [g["id"] async for g in s.iter_guests()]
+    assert ids == [1, 2]
+
+
+def test_iterate_honours_a_starting_cursor(stub):
+    def pages(request, _n):
+        if request.url.params.get("cursor") == "100":
+            return (200, {"data": [guest(101)], "next_cursor": None}, {})
+        return (200, {"data": [guest(1)], "next_cursor": None}, {})
+
+    handler, calls = stub({"/api/v1/guests": pages})
+    with sync_client(handler) as s:
+        assert [g["id"] for g in s.iter_guests(cursor=100)] == [101]
+    assert calls[0].url.params["cursor"] == "100"
+
+
+def test_a_rate_limit_is_retried_waiting_as_long_as_the_server_said(stub):
+    def flaky(_request, n):
+        if n == 1:
+            return (429, {"error": {"code": "rate_limited", "message": "Too many."}}, {"Retry-After": "0"})
+        return (200, {"data": [{"id": 7}], "next_cursor": None}, {})
+
+    handler, calls = stub({"/api/v1/visits": flaky})
+    with sync_client(handler) as s:
+        assert s.list_visits()["data"][0]["id"] == 7
+    assert len(calls) == 2, "should have retried exactly once"
+
+
+def test_retries_are_bounded_and_the_original_error_survives(stub):
+    handler, calls = stub({}, default=(429, {"error": {"code": "rate_limited", "message": "Too many."}}, {"Retry-After": "0"}))
+    with sync_client(handler, max_retries=2) as s, pytest.raises(SadakioError) as e:
+        s.list_guests()
+    assert e.value.code == "rate_limited"
+    assert len(calls) == 3, "one attempt plus two retries"
+
+
+def test_a_404_is_never_retried(stub):
+    handler, calls = stub({}, default=(404, {"error": {"code": "not_found", "message": "Guest not found."}}, {}))
+    with sync_client(handler) as s, pytest.raises(SadakioError) as e:
+        s.get_guest(999)
+    assert e.value.code == "not_found"
+    assert "own business" in str(e.value)
+    assert len(calls) == 1
+
+
+def test_a_200_that_is_not_a_v1_response_names_the_likely_cause(stub):
+    handler, _ = stub({}, default=(200, {"hello": "world"}, {}))
+    with sync_client(handler) as s, pytest.raises(SadakioError) as e:
+        s.list_guests()
+    assert e.value.code == "invalid_response"
+    assert "base_url" in str(e.value)
+
+
+def test_an_added_response_field_passes_through(stub):
+    handler, _ = stub({}, default=(200, {"data": [{"id": 1, "brand_new": "x"}], "next_cursor": None}, {}))
+    with sync_client(handler) as s:
+        assert s.list_guests()["data"][0]["brand_new"] == "x"
+
+
+def test_retention_forwards_the_window_and_invents_no_money(stub):
+    body = {"data": {"since": "a", "until": "b", "active_guests": 40, "returned_guests": 28}}
+    handler, calls = stub({"/api/v1/stats/retention": (200, body, {})})
+    with sync_client(handler) as s:
+        res = s.retention(period="month")
+    assert calls[0].url.params["period"] == "month"
+    assert "estimated_returned_value" not in res["data"]
+
+
+def test_a_trailing_slash_makes_no_double_slash(stub):
+    handler, calls = stub({}, default=(200, {"data": [], "next_cursor": None}, {}))
+    with Sadakio(api_key="sk", base_url="https://example.test/api/v1/", transport=httpx.MockTransport(handler)) as s:
+        s.list_guests()
+    assert "v1//" not in str(calls[0].url)
+
+
+def test_the_two_languages_agree_on_the_package_name():
+    """The npm and PyPI SDKs are one product under one name."""
+    import pathlib
+    import re
+
+    import sadakio
+
+    js = (pathlib.Path(__file__).parents[2] / "sdk-js" / "src" / "constants.js").read_text(encoding="utf-8")
+    js_name = re.search(r"PACKAGE_NAME = '([^']+)'", js).group(1)
+    js_base = re.search(r"DEFAULT_BASE_URL = '([^']+)'", js).group(1)
+    assert js_name == sadakio.PACKAGE_NAME
+    assert js_base == sadakio.DEFAULT_BASE_URL
+
+
+def test_the_key_and_base_url_fall_back_to_the_environment(stub, monkeypatch):
+    handler, calls = stub({}, default=(200, {"data": [], "next_cursor": None}, {}))
+    monkeypatch.setenv("SADAKIO_API_KEY", "sk_from_env")
+    monkeypatch.setenv("SADAKIO_BASE_URL", "https://from-env.test/api/v1")
+    with Sadakio(transport=httpx.MockTransport(handler)) as s:
+        s.list_guests()
+    assert calls[0].headers["authorization"] == "Bearer sk_from_env"
+    assert str(calls[0].url).startswith("https://from-env.test/api/v1")
+
+
+def test_an_explicit_argument_beats_the_environment(stub, monkeypatch):
+    handler, calls = stub({}, default=(200, {"data": [], "next_cursor": None}, {}))
+    monkeypatch.setenv("SADAKIO_BASE_URL", "https://from-env.test/api/v1")
+    with Sadakio(api_key="sk_explicit", base_url="https://explicit.test/api/v1",
+                 transport=httpx.MockTransport(handler)) as s:
+        s.list_guests()
+    assert str(calls[0].url).startswith("https://explicit.test/api/v1")