trackofferz 0.1.0__tar.gz

trackofferz-0.1.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.4
+Name: trackofferz
+Version: 0.1.0
+Summary: Official Python SDK for the TrackOfferz reporting API.
+Project-URL: Homepage, https://trackofferz.com
+Project-URL: Documentation, https://trackofferz.com/docs
+Project-URL: Source, https://github.com/trackofferz/trackofferz-python
+Author-email: SPTSPL <support@trackofferz.com>
+License: MIT
+Keywords: affiliate,reporting,sdk,tracking,trackofferz
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# TrackOfferz Python SDK
+
+Official, zero-dependency Python client for the [TrackOfferz](https://trackofferz.com) reporting API.
+
+- **Typed** — dataclass results, ships with `py.typed`.
+- **Zero dependencies** — standard library only.
+- **Resilient** — automatic retries on 429 (honours `Retry-After`) and transient 5xx.
+- **Network-scoped** — every call is limited to your network by the API key.
+
+## Install
+
+```bash
+pip install trackofferz
+```
+
+## Authenticate
+
+Create a key in the panel under **Settings → API keys** (format `tofz_sk_…`).
+
+```python
+from trackofferz import TrackOfferz
+
+client = TrackOfferz(api_key="tofz_sk_...")
+```
+
+## Reporting
+
+```python
+# Summary (defaults to the last 30 days)
+s = client.reports.summary(from_="2026-06-01", to="2026-06-30")
+print(s.clicks, s.conversions, s.revenue_cents)
+
+# Breakdown by publisher
+for row in client.reports.breakdown(by="publisher"):
+    print(row.label, row.conversions, row.payout_cents)
+
+# One page of conversions for a campaign
+page = client.reports.conversions(campaign_id=5, page=1, page_size=100)
+print(page.total, page.has_next)
+for c in page.rows:
+    print(c.transaction_id, c.payout_cents, c.status)
+
+# Stream EVERY click across all pages (auto-pagination)
+for click in client.reports.iter_clicks(from_="2026-06-01", to="2026-06-30"):
+    print(click.transaction_id, click.country_code, click.is_unique)
+```
+
+> Money fields are integers in **cents** (`payout_cents=1250` → `$12.50`).
+> Date params are `YYYY-MM-DD`. `from_` has a trailing underscore (`from` is a Python keyword) and maps to the `from` query parameter.
+
+## Errors
+
+```python
+from trackofferz import (
+    AuthenticationError, ValidationError, RateLimitError, APIError, TrackOfferzError,
+)
+
+try:
+    client.reports.summary(from_="not-a-date")
+except ValidationError as e:
+    print("bad input:", e.message)
+except RateLimitError as e:
+    print("slow down; retry after", e.retry_after, "s")
+except TrackOfferzError as e:        # base class — catches all of the above
+    print(e.status, e.code, e.message)
+```
+
+## Configuration
+
+```python
+TrackOfferz(
+    api_key="tofz_sk_...",
+    base_url="https://trackofferz.com/api/v1",  # override for self-hosted
+    timeout=30.0,
+    max_retries=2,
+)
+```
+
+Full API reference: <https://trackofferz.com/docs>
+
+---
+
+TrackOfferz is a product by [SPTSPL (S. P. Techno Solution Private Limited)](https://www.sptspl.com).

trackofferz-0.1.0/README.md

@@ -0,0 +1,83 @@
+# TrackOfferz Python SDK
+
+Official, zero-dependency Python client for the [TrackOfferz](https://trackofferz.com) reporting API.
+
+- **Typed** — dataclass results, ships with `py.typed`.
+- **Zero dependencies** — standard library only.
+- **Resilient** — automatic retries on 429 (honours `Retry-After`) and transient 5xx.
+- **Network-scoped** — every call is limited to your network by the API key.
+
+## Install
+
+```bash
+pip install trackofferz
+```
+
+## Authenticate
+
+Create a key in the panel under **Settings → API keys** (format `tofz_sk_…`).
+
+```python
+from trackofferz import TrackOfferz
+
+client = TrackOfferz(api_key="tofz_sk_...")
+```
+
+## Reporting
+
+```python
+# Summary (defaults to the last 30 days)
+s = client.reports.summary(from_="2026-06-01", to="2026-06-30")
+print(s.clicks, s.conversions, s.revenue_cents)
+
+# Breakdown by publisher
+for row in client.reports.breakdown(by="publisher"):
+    print(row.label, row.conversions, row.payout_cents)
+
+# One page of conversions for a campaign
+page = client.reports.conversions(campaign_id=5, page=1, page_size=100)
+print(page.total, page.has_next)
+for c in page.rows:
+    print(c.transaction_id, c.payout_cents, c.status)
+
+# Stream EVERY click across all pages (auto-pagination)
+for click in client.reports.iter_clicks(from_="2026-06-01", to="2026-06-30"):
+    print(click.transaction_id, click.country_code, click.is_unique)
+```
+
+> Money fields are integers in **cents** (`payout_cents=1250` → `$12.50`).
+> Date params are `YYYY-MM-DD`. `from_` has a trailing underscore (`from` is a Python keyword) and maps to the `from` query parameter.
+
+## Errors
+
+```python
+from trackofferz import (
+    AuthenticationError, ValidationError, RateLimitError, APIError, TrackOfferzError,
+)
+
+try:
+    client.reports.summary(from_="not-a-date")
+except ValidationError as e:
+    print("bad input:", e.message)
+except RateLimitError as e:
+    print("slow down; retry after", e.retry_after, "s")
+except TrackOfferzError as e:        # base class — catches all of the above
+    print(e.status, e.code, e.message)
+```
+
+## Configuration
+
+```python
+TrackOfferz(
+    api_key="tofz_sk_...",
+    base_url="https://trackofferz.com/api/v1",  # override for self-hosted
+    timeout=30.0,
+    max_retries=2,
+)
+```
+
+Full API reference: <https://trackofferz.com/docs>
+
+---
+
+TrackOfferz is a product by [SPTSPL (S. P. Techno Solution Private Limited)](https://www.sptspl.com).

trackofferz-0.1.0/examples/quickstart.py

@@ -0,0 +1,35 @@
+"""Quickstart for the TrackOfferz Python SDK.
+
+    export TOFZ_API_KEY=tofz_sk_...
+    python examples/quickstart.py
+"""
+import os
+
+from trackofferz import TrackOfferz, TrackOfferzError
+
+API_KEY = os.environ.get("TOFZ_API_KEY", "")
+# Point at a non-production host if needed:
+BASE_URL = os.environ.get("TOFZ_BASE_URL", "https://trackofferz.com/api/v1")
+
+
+def main() -> None:
+    if not API_KEY:
+        raise SystemExit("Set TOFZ_API_KEY (Settings → API keys in the panel).")
+
+    client = TrackOfferz(api_key=API_KEY, base_url=BASE_URL)
+
+    try:
+        s = client.reports.summary()
+        print(f"Last 30 days: {s.clicks} clicks, {s.unique_clicks} unique, "
+              f"{s.conversions} conversions (CR {s.conversion_rate:.2%})")
+        print(f"Revenue: {s.revenue_cents/100:.2f}  Payout: {s.payout_cents/100:.2f}")
+
+        print("\nTop campaigns:")
+        for row in client.reports.breakdown(by="campaign")[:10]:
+            print(f"  {row.label or row.key:<24} {row.clicks:>6} clicks  {row.conversions:>4} conv")
+    except TrackOfferzError as e:
+        raise SystemExit(f"API error [{e.code}]: {e.message}")
+
+
+if __name__ == "__main__":
+    main()

trackofferz-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "trackofferz"
+version = "0.1.0"
+description = "Official Python SDK for the TrackOfferz reporting API."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "SPTSPL", email = "support@trackofferz.com" }]
+keywords = ["trackofferz", "affiliate", "tracking", "reporting", "sdk"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Typing :: Typed",
+]
+# Zero runtime dependencies — built on the Python standard library only.
+dependencies = []
+
+[project.urls]
+Homepage = "https://trackofferz.com"
+Documentation = "https://trackofferz.com/docs"
+Source = "https://github.com/trackofferz/trackofferz-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["trackofferz"]

trackofferz-0.1.0/trackofferz/__init__.py

@@ -0,0 +1,71 @@
+"""TrackOfferz — official Python SDK for the reporting API.
+
+    from trackofferz import TrackOfferz
+
+    client = TrackOfferz(api_key="tofz_sk_…")
+    print(client.reports.summary(from_="2026-06-01", to="2026-06-30"))
+
+Create a key in the panel under Settings → API keys. Every call is scoped to
+your network. Docs: https://trackofferz.com/docs
+"""
+from __future__ import annotations
+
+from ._client import DEFAULT_BASE_URL, HTTPClient, __version__
+from .errors import (
+    APIError,
+    AuthenticationError,
+    RateLimitError,
+    TrackOfferzError,
+    ValidationError,
+)
+from .reports import Reports
+from .types import (
+    BreakdownRow,
+    ClickRow,
+    ConversionRow,
+    DateRange,
+    Page,
+    Summary,
+)
+
+__all__ = [
+    "TrackOfferz",
+    "Reports",
+    "TrackOfferzError",
+    "AuthenticationError",
+    "ValidationError",
+    "RateLimitError",
+    "APIError",
+    "Summary",
+    "ClickRow",
+    "ConversionRow",
+    "BreakdownRow",
+    "DateRange",
+    "Page",
+    "__version__",
+]
+
+
+class TrackOfferz:
+    """Top-level client. Holds the API key + transport; exposes namespaces.
+
+    Args:
+        api_key: Network API key (``tofz_sk_…``) from Settings → API keys.
+        base_url: Override the API base (default production).
+        timeout: Per-request timeout in seconds.
+        max_retries: Retries for 429 / transient 5xx (exp backoff, honours
+            Retry-After).
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+    ):
+        self._http = HTTPClient(
+            api_key, base_url=base_url, timeout=timeout, max_retries=max_retries
+        )
+        self.reports = Reports(self._http)

trackofferz-0.1.0/trackofferz/_client.py

@@ -0,0 +1,120 @@
+"""Low-level HTTP transport. Standard library only (urllib) — no third-party
+deps so the SDK adds nothing to your dependency tree.
+"""
+from __future__ import annotations
+
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, Optional
+
+from .errors import (
+    APIError,
+    AuthenticationError,
+    RateLimitError,
+    TrackOfferzError,
+    ValidationError,
+)
+
+__version__ = "0.1.0"
+DEFAULT_BASE_URL = "https://trackofferz.com/api/v1"
+
+
+class HTTPClient:
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+    ):
+        if not api_key or not api_key.startswith("tofz_"):
+            raise ValueError("api_key must be a TrackOfferz key (starts with 'tofz_').")
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._max_retries = max_retries
+
+    def get(self, path: str, params: Optional[Dict[str, Any]] = None) -> Any:
+        """GET a path, returning the full parsed envelope ({data, meta}).
+        Retries 429 (honouring Retry-After) and transient 5xx with backoff."""
+        query = _encode_params(params or {})
+        url = f"{self._base_url}{path}"
+        if query:
+            url = f"{url}?{query}"
+
+        attempt = 0
+        while True:
+            try:
+                return self._request(url)
+            except RateLimitError as e:
+                if attempt >= self._max_retries:
+                    raise
+                _sleep(e.retry_after or _backoff(attempt))
+            except APIError as e:
+                # Retry transient 5xx only.
+                if (e.status or 0) < 500 or attempt >= self._max_retries:
+                    raise
+                _sleep(_backoff(attempt))
+            attempt += 1
+
+    # ── internals ──────────────────────────────────────────────────────────
+
+    def _request(self, url: str) -> Any:
+        req = urllib.request.Request(url, method="GET")
+        req.add_header("Authorization", f"Bearer {self._api_key}")
+        req.add_header("Accept", "application/json")
+        req.add_header("User-Agent", f"trackofferz-python/{__version__}")
+        try:
+            with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+                body = resp.read().decode("utf-8")
+                return json.loads(body) if body else {}
+        except urllib.error.HTTPError as e:
+            self._raise_for_status(e)
+        except urllib.error.URLError as e:
+            raise TrackOfferzError(f"Network error: {e.reason}") from e
+
+    def _raise_for_status(self, e: "urllib.error.HTTPError") -> None:
+        status = e.code
+        code = "http_error"
+        message = e.reason or "request failed"
+        try:
+            err = json.loads(e.read().decode("utf-8")).get("error", {})
+            code = err.get("code", code)
+            message = err.get("message", message)
+        except Exception:
+            pass
+
+        if status == 401:
+            raise AuthenticationError(message, status=status, code=code)
+        if status == 422:
+            raise ValidationError(message, status=status, code=code)
+        if status == 429:
+            ra = e.headers.get("Retry-After") if e.headers else None
+            raise RateLimitError(
+                message,
+                status=status,
+                code=code,
+                retry_after=int(ra) if ra and ra.isdigit() else None,
+            )
+        raise APIError(message, status=status, code=code)
+
+
+def _encode_params(params: Dict[str, Any]) -> str:
+    clean = {k: v for k, v in params.items() if v is not None}
+    # bools → lowercase strings the API expects ("true"/"false")
+    for k, v in list(clean.items()):
+        if isinstance(v, bool):
+            clean[k] = "true" if v else "false"
+    return urllib.parse.urlencode(clean)
+
+
+def _backoff(attempt: int) -> float:
+    return min(8.0, 0.5 * (2 ** attempt))
+
+
+def _sleep(seconds: float) -> None:
+    time.sleep(max(0.0, seconds))

trackofferz-0.1.0/trackofferz/errors.py

@@ -0,0 +1,38 @@
+"""Typed exceptions raised by the TrackOfferz client.
+
+Catch :class:`TrackOfferzError` to handle any SDK error, or the specific
+subclasses for finer control.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+
+class TrackOfferzError(Exception):
+    """Base class for every error the SDK raises."""
+
+    def __init__(self, message: str, *, status: Optional[int] = None, code: Optional[str] = None):
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+
+
+class AuthenticationError(TrackOfferzError):
+    """401 — missing, invalid, or revoked API key."""
+
+
+class ValidationError(TrackOfferzError):
+    """422 — invalid request parameters (bad dates, ids, etc.)."""
+
+
+class RateLimitError(TrackOfferzError):
+    """429 — too many requests. ``retry_after`` is seconds to wait."""
+
+    def __init__(self, message: str, *, retry_after: Optional[int] = None, **kw):
+        super().__init__(message, **kw)
+        self.retry_after = retry_after
+
+
+class APIError(TrackOfferzError):
+    """Any other non-2xx response (incl. 5xx)."""

trackofferz-0.1.0/trackofferz/reports.py

@@ -0,0 +1,118 @@
+"""The ``reports`` namespace: client.reports.summary(), .clicks(), etc."""
+from __future__ import annotations
+
+from typing import Iterator, Optional
+
+from ._client import HTTPClient
+from .types import BreakdownRow, ClickRow, ConversionRow, Page, Summary
+
+
+class Reports:
+    def __init__(self, http: HTTPClient):
+        self._http = http
+
+    def summary(
+        self,
+        *,
+        from_: Optional[str] = None,
+        to: Optional[str] = None,
+        campaign_id: Optional[int] = None,
+        publisher_id: Optional[int] = None,
+    ) -> Summary:
+        """Aggregate totals over a date range (default: last 30 days)."""
+        payload = self._http.get(
+            "/reports/summary",
+            {"from": from_, "to": to, "campaign_id": campaign_id, "publisher_id": publisher_id},
+        )
+        return Summary._parse(payload.get("data", {}))
+
+    def clicks(
+        self,
+        *,
+        from_: Optional[str] = None,
+        to: Optional[str] = None,
+        campaign_id: Optional[int] = None,
+        publisher_id: Optional[int] = None,
+        page: int = 1,
+        page_size: int = 100,
+        include_rejected: bool = False,
+    ) -> Page:
+        """One page of click detail (newest first)."""
+        payload = self._http.get(
+            "/reports/clicks",
+            {
+                "from": from_, "to": to,
+                "campaign_id": campaign_id, "publisher_id": publisher_id,
+                "page": page, "page_size": page_size,
+                "include_rejected": include_rejected,
+            },
+        )
+        return _to_page(payload, ClickRow)
+
+    def conversions(
+        self,
+        *,
+        from_: Optional[str] = None,
+        to: Optional[str] = None,
+        campaign_id: Optional[int] = None,
+        publisher_id: Optional[int] = None,
+        page: int = 1,
+        page_size: int = 100,
+    ) -> Page:
+        """One page of conversion detail (newest first, refunds excluded)."""
+        payload = self._http.get(
+            "/reports/conversions",
+            {
+                "from": from_, "to": to,
+                "campaign_id": campaign_id, "publisher_id": publisher_id,
+                "page": page, "page_size": page_size,
+            },
+        )
+        return _to_page(payload, ConversionRow)
+
+    def breakdown(
+        self,
+        *,
+        by: str = "campaign",
+        from_: Optional[str] = None,
+        to: Optional[str] = None,
+    ) -> list:
+        """Performance grouped by 'campaign' | 'publisher' | 'country' | 'sub_id'."""
+        payload = self._http.get("/reports/breakdown", {"by": by, "from": from_, "to": to})
+        return [BreakdownRow._parse(r) for r in payload.get("data", [])]
+
+    # ── auto-paginating iterators ────────────────────────────────────────────
+
+    def iter_clicks(self, *, page_size: int = 1000, **kw) -> Iterator[ClickRow]:
+        """Yield every click across all pages (handles pagination for you)."""
+        page = 1
+        while True:
+            p = self.clicks(page=page, page_size=page_size, **kw)
+            for row in p.rows:
+                yield row
+            if not p.has_next:
+                break
+            page += 1
+
+    def iter_conversions(self, *, page_size: int = 1000, **kw) -> Iterator[ConversionRow]:
+        """Yield every conversion across all pages."""
+        page = 1
+        while True:
+            p = self.conversions(page=page, page_size=page_size, **kw)
+            for row in p.rows:
+                yield row
+            if not p.has_next:
+                break
+            page += 1
+
+
+def _to_page(payload: dict, row_cls) -> Page:
+    rows = [row_cls._parse(r) for r in payload.get("data", [])]
+    meta = payload.get("meta", {}) or {}
+    return Page(
+        rows=rows,
+        page=int(meta.get("page", 1)),
+        page_size=int(meta.get("page_size", len(rows))),
+        total=int(meta.get("total", len(rows))),
+        total_pages=int(meta.get("total_pages", 1)),
+    )

trackofferz-0.1.0/trackofferz/types.py

@@ -0,0 +1,160 @@
+"""Typed result objects. Each parses straight from the API JSON.
+
+Money fields are integers in CENTS (e.g. payout_cents=1250 → $12.50), matching
+the API. Convert to your display currency at the edge.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class DateRange:
+    from_: str
+    to: str
+
+    @classmethod
+    def _parse(cls, d: Dict[str, Any]) -> "DateRange":
+        return cls(from_=d.get("from", ""), to=d.get("to", ""))
+
+
+@dataclass
+class Summary:
+    range: DateRange
+    clicks: int
+    unique_clicks: int
+    conversions: int
+    conversion_rate: float
+    payout_cents: int
+    revenue_cents: int
+    sale_amount_cents: int
+
+    @classmethod
+    def _parse(cls, d: Dict[str, Any]) -> "Summary":
+        return cls(
+            range=DateRange._parse(d.get("range", {})),
+            clicks=int(d.get("clicks", 0)),
+            unique_clicks=int(d.get("unique_clicks", 0)),
+            conversions=int(d.get("conversions", 0)),
+            conversion_rate=float(d.get("conversion_rate", 0.0)),
+            payout_cents=int(d.get("payout_cents", 0)),
+            revenue_cents=int(d.get("revenue_cents", 0)),
+            sale_amount_cents=int(d.get("sale_amount_cents", 0)),
+        )
+
+
+@dataclass
+class ClickRow:
+    event_time: str
+    transaction_id: str
+    campaign_id: int
+    publisher_id: int
+    country_code: str
+    region: str
+    city: str
+    os: str
+    browser: str
+    device_type: str
+    ip_address: str
+    asn: int
+    isp: str
+    sub_ids: List[str] = field(default_factory=list)
+    is_unique: bool = True
+    fraud_score: int = 0
+    rejected: bool = False
+    rejection_code: str = ""
+
+    @classmethod
+    def _parse(cls, d: Dict[str, Any]) -> "ClickRow":
+        return cls(
+            event_time=str(d.get("event_time", "")),
+            transaction_id=str(d.get("transaction_id", "")),
+            campaign_id=int(d.get("campaign_id", 0)),
+            publisher_id=int(d.get("publisher_id", 0)),
+            country_code=str(d.get("country_code", "")),
+            region=str(d.get("region", "")),
+            city=str(d.get("city", "")),
+            os=str(d.get("os", "")),
+            browser=str(d.get("browser", "")),
+            device_type=str(d.get("device_type", "")),
+            ip_address=str(d.get("ip_address", "")),
+            asn=int(d.get("asn", 0)),
+            isp=str(d.get("isp", "")),
+            sub_ids=list(d.get("sub_ids", []) or []),
+            is_unique=bool(d.get("is_unique", True)),
+            fraud_score=int(d.get("fraud_score", 0)),
+            rejected=bool(d.get("rejected", False)),
+            rejection_code=str(d.get("rejection_code", "")),
+        )
+
+
+@dataclass
+class ConversionRow:
+    event_time: str
+    transaction_id: str
+    campaign_id: int
+    publisher_id: int
+    event_type: str
+    status: str
+    payout_cents: int
+    sale_amount_cents: int
+    advertiser_cost_cents: int
+    currency: str
+    country_code: str
+    ctit_seconds: int
+
+    @classmethod
+    def _parse(cls, d: Dict[str, Any]) -> "ConversionRow":
+        return cls(
+            event_time=str(d.get("event_time", "")),
+            transaction_id=str(d.get("transaction_id", "")),
+            campaign_id=int(d.get("campaign_id", 0)),
+            publisher_id=int(d.get("publisher_id", 0)),
+            event_type=str(d.get("event_type", "")),
+            status=str(d.get("status", "")),
+            payout_cents=int(d.get("payout_cents", 0)),
+            sale_amount_cents=int(d.get("sale_amount_cents", 0)),
+            advertiser_cost_cents=int(d.get("advertiser_cost_cents", 0)),
+            currency=str(d.get("currency", "")),
+            country_code=str(d.get("country_code", "")),
+            ctit_seconds=int(d.get("ctit_seconds", 0)),
+        )
+
+
+@dataclass
+class BreakdownRow:
+    key: str
+    label: Optional[str]
+    clicks: int
+    unique_clicks: int
+    conversions: int
+    payout_cents: int
+    revenue_cents: int
+
+    @classmethod
+    def _parse(cls, d: Dict[str, Any]) -> "BreakdownRow":
+        return cls(
+            key=str(d.get("key", "")),
+            label=d.get("label"),
+            clicks=int(d.get("clicks", 0)),
+            unique_clicks=int(d.get("unique_clicks", 0)),
+            conversions=int(d.get("conversions", 0)),
+            payout_cents=int(d.get("payout_cents", 0)),
+            revenue_cents=int(d.get("revenue_cents", 0)),
+        )
+
+
+@dataclass
+class Page:
+    """One page of detail rows + pagination cursor."""
+
+    rows: List[Any]
+    page: int
+    page_size: int
+    total: int
+    total_pages: int
+
+    @property
+    def has_next(self) -> bool:
+        return self.page < self.total_pages