pawpado 0.1.0__tar.gz

pawpado-0.1.0/.gitignore

@@ -0,0 +1,66 @@
+# Dependencies
+node_modules/
+.pnp
+.pnp.js
+
+# Testing
+/coverage
+test-results/
+playwright-report/
+
+# Next.js
+.next/
+out/
+
+# Production builds
+build/
+# ...but NOT the "Build your machine" app route, which lives at
+# src/app/(dashboard)/dashboard/build/ and is real source, not an artifact.
+!frontend/src/app/**/build/
+dist/
+*.tsbuildinfo
+next-env.d.ts
+
+# Python (control plane)
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Environment + secrets — NEVER commit
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+secrets.ini
+config/secrets.ini
+config/secrets.*.ini
+!config/secrets.example.ini
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Misc
+.cache/
+*.pid
+
+# DB
+frontend/data/

pawpado-0.1.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: pawpado
+Version: 0.1.0
+Summary: Official Python SDK for Pawpado — single-user AWS GPU gaming portal. Sessions (start/stop/poll/pair/connect), credits, billing, settings, admin. Bearer auth via Huudis OIDC device flow.
+Project-URL: Homepage, https://pawpado.com
+Project-URL: Source, https://github.com/hachimi-cat/saas-pawpado/tree/main/sdk/python
+Project-URL: Issues, https://github.com/hachimi-cat/saas-pawpado/issues
+Author-email: Forjio <hello@pawpado.com>
+License: MIT
+Keywords: aws,forjio,gaming,gpu,huudis,pawpado
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pyjwt[crypto]>=2.9.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pawpado (Python)
+
+Official Python SDK for [Pawpado](https://pawpado.com) — the single-user AWS
+GPU gaming portal. Mirrors the Node SDK (`@forjio/pawpado-node`) 1:1.
+
+## Install
+
+```bash
+pip install pawpado
+```
+
+## Quickstart
+
+### Static API key (simplest)
+
+```python
+from pawpado import PawpadoClient
+
+with PawpadoClient(api_key="...") as client:
+    print(client.health())               # public, no auth
+    print(client.sessions.poll())        # GET /api/v1/sessions/poll
+    print(client.sessions.start())       # POST /api/v1/sessions/start
+    print(client.credits.me())
+    client.sessions.stop({"force": True})
+```
+
+### Huudis OIDC device flow (CLI-style)
+
+```python
+from pawpado import PawpadoClient, Session
+
+session = Session(brand="pawpado", profile="default")
+session.load()  # reads ~/.pawpado/credentials
+
+with PawpadoClient(session=session) as client:
+    print(client.account.session())
+```
+
+The ``Session`` refresh path is single-flight — concurrent callers share the
+same refresh and avoid burning the Huudis refresh-token family (Huudis revokes
+the entire family on reuse).
+
+## Surface
+
+| Namespace | Methods |
+|---|---|
+| ``sessions`` | ``start`` / ``stop`` / ``poll`` / ``pair`` / ``connect`` / ``tailscale_key`` |
+| ``credits`` | ``me`` / ``topup`` |
+| ``billing`` | ``storage`` |
+| ``settings`` | ``get`` / ``update`` |
+| ``account`` | ``session`` / ``delete`` |
+| ``admin`` | ``reconcile`` / ``orphans`` |
+| ``health()`` | top-level, no auth |
+
+Every method takes an optional ``auth_token=`` to override the client-level
+bearer for one call.
+
+## Errors
+
+- ``PawpadoError`` (alias: ``ApiError``) — enveloped API errors, carries
+  ``.code``, ``.message``, ``.status``, ``.request_id``, ``.details``.
+- ``PawpadoAuthError`` — credentials / session lookup failures.
+- ``RefreshError`` — OIDC refresh failure.
+- ``NetworkError`` — transport failure (DNS, TLS, etc.).
+
+## License
+
+MIT

pawpado-0.1.0/README.md

@@ -0,0 +1,68 @@
+# pawpado (Python)
+
+Official Python SDK for [Pawpado](https://pawpado.com) — the single-user AWS
+GPU gaming portal. Mirrors the Node SDK (`@forjio/pawpado-node`) 1:1.
+
+## Install
+
+```bash
+pip install pawpado
+```
+
+## Quickstart
+
+### Static API key (simplest)
+
+```python
+from pawpado import PawpadoClient
+
+with PawpadoClient(api_key="...") as client:
+    print(client.health())               # public, no auth
+    print(client.sessions.poll())        # GET /api/v1/sessions/poll
+    print(client.sessions.start())       # POST /api/v1/sessions/start
+    print(client.credits.me())
+    client.sessions.stop({"force": True})
+```
+
+### Huudis OIDC device flow (CLI-style)
+
+```python
+from pawpado import PawpadoClient, Session
+
+session = Session(brand="pawpado", profile="default")
+session.load()  # reads ~/.pawpado/credentials
+
+with PawpadoClient(session=session) as client:
+    print(client.account.session())
+```
+
+The ``Session`` refresh path is single-flight — concurrent callers share the
+same refresh and avoid burning the Huudis refresh-token family (Huudis revokes
+the entire family on reuse).
+
+## Surface
+
+| Namespace | Methods |
+|---|---|
+| ``sessions`` | ``start`` / ``stop`` / ``poll`` / ``pair`` / ``connect`` / ``tailscale_key`` |
+| ``credits`` | ``me`` / ``topup`` |
+| ``billing`` | ``storage`` |
+| ``settings`` | ``get`` / ``update`` |
+| ``account`` | ``session`` / ``delete`` |
+| ``admin`` | ``reconcile`` / ``orphans`` |
+| ``health()`` | top-level, no auth |
+
+Every method takes an optional ``auth_token=`` to override the client-level
+bearer for one call.
+
+## Errors
+
+- ``PawpadoError`` (alias: ``ApiError``) — enveloped API errors, carries
+  ``.code``, ``.message``, ``.status``, ``.request_id``, ``.details``.
+- ``PawpadoAuthError`` — credentials / session lookup failures.
+- ``RefreshError`` — OIDC refresh failure.
+- ``NetworkError`` — transport failure (DNS, TLS, etc.).
+
+## License
+
+MIT

pawpado-0.1.0/pawpado/__init__.py

@@ -0,0 +1,57 @@
+"""Official Python SDK for Pawpado.
+
+Mirrors the Node SDK (`@forjio/pawpado-node`):
+
+- :class:`PawpadoClient` — sessions / credits / billing / settings / account /
+  admin / health, with Bearer auth via either a :class:`Session` (Huudis OIDC
+  device flow + refresh) or a static ``api_key``.
+- :class:`Session` — multi-profile credentials store with single-flight refresh,
+  the Python parity of ``@forjio/sdk``'s Session.
+- :class:`ApiClient` — typed HTTP client with envelope unwrap, proactive +
+  reactive token refresh, and auto-pagination.
+"""
+
+from .client import PawpadoClient
+from .errors import (
+    ApiError,
+    NetworkError,
+    PawpadoAuthError,
+    PawpadoError,
+    RefreshError,
+)
+from .resources import (
+    AccountResources,
+    AdminResources,
+    ApiClient,
+    BillingResources,
+    CreditsResources,
+    SessionsResources,
+    SettingsResources,
+    build_resources,
+)
+from .session import ProfileData, Session
+
+__all__ = [
+    # client
+    "PawpadoClient",
+    # errors
+    "ApiError",
+    "NetworkError",
+    "PawpadoAuthError",
+    "PawpadoError",
+    "RefreshError",
+    # resources
+    "ApiClient",
+    "AccountResources",
+    "AdminResources",
+    "BillingResources",
+    "CreditsResources",
+    "SessionsResources",
+    "SettingsResources",
+    "build_resources",
+    # session
+    "ProfileData",
+    "Session",
+]
+
+__version__ = "0.1.0"

pawpado-0.1.0/pawpado/client.py

@@ -0,0 +1,95 @@
+"""High-level Pawpado client mirroring the Node SDK's PawpadoClient surface."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import httpx
+
+from .resources import (
+    AccountResources,
+    AdminResources,
+    ApiClient,
+    BillingResources,
+    CreditsResources,
+    SessionsResources,
+    SettingsResources,
+    build_resources,
+)
+from .session import Session
+
+
+class _ApiKeyApiClient(ApiClient):
+    """ApiClient variant that injects a static API key as the default Bearer.
+
+    Mirrors the Node SDK's ``a(token)`` helper: when no per-call ``auth_token``
+    is given, fall back to the configured static api_key.
+    """
+
+    def __init__(self, *, api_key: str, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self._api_key = api_key
+
+    def _request(self, method, path, body, *, query, headers, auth_token):  # type: ignore[override]
+        if auth_token is None:
+            auth_token = self._api_key
+        return super()._request(
+            method, path, body, query=query, headers=headers, auth_token=auth_token,
+        )
+
+
+class PawpadoClient:
+    """Talk to Pawpado.
+
+    Auth options (pick one):
+      - ``session=Session(...)`` — Bearer via Huudis device flow w/ refresh.
+      - ``api_key="..."`` — static access token (mirrors Node ``apiKey``).
+      - neither — only ``health()`` is usable; per-call ``auth_token=`` works.
+    """
+
+    # IDE hints — populated in __init__.
+    sessions: SessionsResources
+    credits: CreditsResources
+    billing: BillingResources
+    settings: SettingsResources
+    account: AccountResources
+    admin: AdminResources
+
+    def __init__(
+        self,
+        *,
+        base_url: str = "https://pawpado.com",
+        session: Optional[Session] = None,
+        api_key: Optional[str] = None,
+        http: Optional[httpx.Client] = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self._http = http or httpx.Client(timeout=10.0)
+        self._owns_http = http is None
+        if api_key is not None and session is None:
+            self.api: ApiClient = _ApiKeyApiClient(
+                api_key=api_key, base_url=self.base_url, http=self._http,
+            )
+        else:
+            self.api = ApiClient(base_url=self.base_url, session=session, http=self._http)
+        resources = build_resources(self.api)
+        self.sessions = resources["sessions"]  # type: ignore[assignment]
+        self.credits = resources["credits"]  # type: ignore[assignment]
+        self.billing = resources["billing"]  # type: ignore[assignment]
+        self.settings = resources["settings"]  # type: ignore[assignment]
+        self.account = resources["account"]  # type: ignore[assignment]
+        self.admin = resources["admin"]  # type: ignore[assignment]
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self) -> "PawpadoClient":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+    # ─── Health (no auth) ───────────────────────────────────────────────
+    def health(self) -> Any:
+        return self.api.get("/api/v1/health")

pawpado-0.1.0/pawpado/errors.py

@@ -0,0 +1,69 @@
+"""Typed error classes for the Pawpado SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+
+class PawpadoAuthError(Exception):
+    """Raised on Pawpado auth / OIDC failures."""
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+
+    def __repr__(self) -> str:
+        return f"PawpadoAuthError({self.code!r}, {self.message!r})"
+
+
+class RefreshError(Exception):
+    """Raised when refreshing an OIDC access token fails."""
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+
+    def __repr__(self) -> str:
+        return f"RefreshError({self.code!r}, {self.message!r})"
+
+
+class NetworkError(Exception):
+    """Raised on transport failures (DNS, connect refused, TLS, etc.)."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+        self.message = message
+
+
+class PawpadoError(Exception):
+    """Raised on enveloped errors (data=null, error.code/message)
+    or non-2xx HTTP responses from Pawpado APIs.
+
+    Aliased as ``ApiError`` for parity with the Node SDK's
+    ``ApiError as PawpadoError`` re-export.
+    """
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        status: int,
+        *,
+        request_id: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.status = status
+        self.request_id = request_id
+        self.details = details
+
+    def __repr__(self) -> str:
+        return f"PawpadoError({self.code!r}, {self.message!r}, status={self.status})"
+
+
+# Alias to match Node SDK naming.
+ApiError = PawpadoError

pawpado-0.1.0/pawpado/resources.py

@@ -0,0 +1,303 @@
+"""Typed ApiClient + resource namespaces for PawpadoClient.
+
+Bundled into one module because pawpado's surface is small enough that splitting
+``http_client.py`` + ``resources.py`` (the huudis layout) is overkill — but the
+class shapes match huudis 1:1 so they can be teased apart later.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Iterator, Optional
+from urllib.parse import urlparse
+
+import httpx
+
+from .errors import ApiError, NetworkError
+from .session import Session
+
+
+class ApiClient:
+    """Bearer-auth HTTP client with envelope unwrap + proactive/reactive
+    refresh. Mirrors @forjio/sdk's ApiClient."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        session: Optional[Session] = None,
+        http: Optional[httpx.Client] = None,
+        refresh_buffer_sec: int = 300,
+        retry_on_5xx: int = 1,
+        default_headers: Optional[Dict[str, str]] = None,
+        default_query: Optional[Dict[str, str]] = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.session = session
+        self._http = http or httpx.Client(timeout=10.0)
+        self._owns_http = http is None
+        self.refresh_buffer_sec = refresh_buffer_sec
+        self.retry_on_5xx = retry_on_5xx
+        self.default_headers = default_headers or {}
+        self.default_query = default_query or {}
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+    def __enter__(self) -> "ApiClient":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+    # ---- public methods -------------------------------------------------
+
+    def get(self, path: str, *, query: Optional[Dict[str, Any]] = None, headers: Optional[Dict[str, str]] = None, auth_token: Optional[str] = None) -> Any:
+        return self._request("GET", path, None, query=query, headers=headers, auth_token=auth_token)
+
+    def post(self, path: str, body: Any = None, *, query: Optional[Dict[str, Any]] = None, headers: Optional[Dict[str, str]] = None, auth_token: Optional[str] = None) -> Any:
+        return self._request("POST", path, body, query=query, headers=headers, auth_token=auth_token)
+
+    def patch(self, path: str, body: Any = None, *, query: Optional[Dict[str, Any]] = None, headers: Optional[Dict[str, str]] = None, auth_token: Optional[str] = None) -> Any:
+        return self._request("PATCH", path, body, query=query, headers=headers, auth_token=auth_token)
+
+    def put(self, path: str, body: Any = None, *, query: Optional[Dict[str, Any]] = None, headers: Optional[Dict[str, str]] = None, auth_token: Optional[str] = None) -> Any:
+        return self._request("PUT", path, body, query=query, headers=headers, auth_token=auth_token)
+
+    def delete(self, path: str, *, query: Optional[Dict[str, Any]] = None, headers: Optional[Dict[str, str]] = None, auth_token: Optional[str] = None) -> Any:
+        return self._request("DELETE", path, None, query=query, headers=headers, auth_token=auth_token)
+
+    def paginate(
+        self,
+        path: str,
+        *,
+        query: Optional[Dict[str, Any]] = None,
+        cursor_param: str = "cursor",
+        auth_token: Optional[str] = None,
+    ) -> Iterator[Any]:
+        cursor: Optional[str] = None
+        while True:
+            q = dict(query or {})
+            if cursor:
+                q[cursor_param] = cursor
+            page = self.get(path, query=q, auth_token=auth_token)
+            for item in _extract_items(page):
+                yield item
+            cursor = _extract_cursor(page)
+            if not cursor:
+                return
+
+    # ---- internals ------------------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: Any,
+        *,
+        query: Optional[Dict[str, Any]],
+        headers: Optional[Dict[str, str]],
+        auth_token: Optional[str],
+    ) -> Any:
+        # Proactive refresh (only when we own the bearer via session)
+        if (
+            self.session is not None
+            and auth_token is None
+            and self.session.will_expire_soon(self.refresh_buffer_sec)
+        ):
+            try:
+                self.session.refresh()
+            except Exception:
+                pass
+        res = self._send(method, path, body, query=query, headers=headers, auth_token=auth_token)
+        # Reactive single 401 retry
+        if res.status_code == 401 and self.session is not None and auth_token is None:
+            try:
+                self.session.refresh()
+                res = self._send(method, path, body, query=query, headers=headers, auth_token=auth_token)
+            except Exception:
+                pass
+        # 5xx retry
+        retries_left = self.retry_on_5xx
+        while res.status_code >= 500 and retries_left > 0:
+            retries_left -= 1
+            res = self._send(method, path, body, query=query, headers=headers, auth_token=auth_token)
+        return self._unwrap(res)
+
+    def _send(
+        self,
+        method: str,
+        path: str,
+        body: Any,
+        *,
+        query: Optional[Dict[str, Any]],
+        headers: Optional[Dict[str, str]],
+        auth_token: Optional[str],
+    ) -> httpx.Response:
+        if urlparse(path).scheme:
+            url = path
+        else:
+            url = f"{self.base_url}{path if path.startswith('/') else '/' + path}"
+        merged_q: Dict[str, Any] = dict(self.default_query)
+        if query:
+            merged_q.update({k: v for k, v in query.items() if v is not None})
+        h: Dict[str, str] = dict(self.default_headers)
+        h["accept"] = h.get("accept", "application/json")
+        if headers:
+            h.update(headers)
+        token = auth_token or (
+            self.session.data.access_token if (self.session and self.session.data) else None
+        )
+        if token:
+            h["authorization"] = f"Bearer {token}"
+        kwargs: Dict[str, Any] = {"params": merged_q or None, "headers": h}
+        if body is not None:
+            h.setdefault("content-type", "application/json")
+            kwargs["json"] = body
+        try:
+            return self._http.request(method, url, **kwargs)
+        except httpx.HTTPError as e:
+            raise NetworkError(str(e)) from e
+
+    def _unwrap(self, res: httpx.Response) -> Any:
+        text = res.text or ""
+        parsed: Any = None
+        if text:
+            try:
+                parsed = res.json()
+            except Exception:
+                if res.status_code >= 400:
+                    raise ApiError("NON_JSON_ERROR", text or res.reason_phrase, res.status_code)
+                raise ApiError("INVALID_RESPONSE", "non-JSON response", res.status_code)
+        if isinstance(parsed, dict) and "data" in parsed and "error" in parsed and "meta" in parsed:
+            if parsed.get("error"):
+                error = parsed["error"]
+                raise ApiError(
+                    error.get("code", "UNKNOWN"),
+                    error.get("message", ""),
+                    res.status_code,
+                    request_id=(parsed.get("meta") or {}).get("requestId"),
+                    details=error.get("details"),
+                )
+            return parsed.get("data")
+        if res.status_code >= 400:
+            err_obj = parsed.get("error") if isinstance(parsed, dict) else parsed
+            code = (err_obj or {}).get("code", "HTTP_ERROR") if isinstance(err_obj, dict) else "HTTP_ERROR"
+            message = (
+                (err_obj or {}).get("message", res.reason_phrase)
+                if isinstance(err_obj, dict)
+                else res.reason_phrase
+            )
+            raise ApiError(
+                code,
+                message,
+                res.status_code,
+                details=parsed if isinstance(parsed, dict) else None,
+            )
+        return parsed
+
+
+def _extract_items(page: Any) -> Iterator[Any]:
+    if isinstance(page, list):
+        yield from page
+        return
+    if isinstance(page, dict):
+        for key in ("items", "data", "results"):
+            v = page.get(key)
+            if isinstance(v, list):
+                yield from v
+                return
+
+
+def _extract_cursor(page: Any) -> Optional[str]:
+    if not isinstance(page, dict):
+        return None
+    nc = page.get("nextCursor")
+    if isinstance(nc, str) and nc:
+        return nc
+    meta = page.get("meta")
+    if isinstance(meta, dict):
+        mc = meta.get("nextCursor")
+        if isinstance(mc, str) and mc:
+            return mc
+    return None
+
+
+# ─── Resource namespaces ────────────────────────────────────────────────
+
+
+class _Namespace:
+    def __init__(self, api: ApiClient) -> None:
+        self.api = api
+
+
+def _opts(auth_token: Optional[str]) -> Dict[str, Any]:
+    return {"auth_token": auth_token} if auth_token else {}
+
+
+class SessionsResources(_Namespace):
+    def start(self, *, auth_token: Optional[str] = None):
+        return self.api.post("/api/v1/sessions/start", None, **_opts(auth_token))
+
+    def stop(self, body: Optional[Dict[str, Any]] = None, *, auth_token: Optional[str] = None):
+        return self.api.post("/api/v1/sessions/stop", body or {}, **_opts(auth_token))
+
+    def poll(self, *, auth_token: Optional[str] = None):
+        return self.api.get("/api/v1/sessions/poll", **_opts(auth_token))
+
+    def pair(self, *, auth_token: Optional[str] = None):
+        return self.api.post("/api/v1/sessions/pair", None, **_opts(auth_token))
+
+    def connect(self, *, auth_token: Optional[str] = None):
+        return self.api.get("/api/v1/sessions/connect", **_opts(auth_token))
+
+    def tailscale_key(self, *, auth_token: Optional[str] = None):
+        return self.api.post("/api/v1/sessions/tailscale-key", None, **_opts(auth_token))
+
+
+class CreditsResources(_Namespace):
+    def me(self, *, auth_token: Optional[str] = None):
+        return self.api.get("/api/v1/credits/me", **_opts(auth_token))
+
+    def topup(self, body: Dict[str, Any], *, auth_token: Optional[str] = None):
+        return self.api.post("/api/v1/credits/topup", body, **_opts(auth_token))
+
+
+class BillingResources(_Namespace):
+    def storage(self, *, auth_token: Optional[str] = None):
+        return self.api.get("/api/v1/billing/storage", **_opts(auth_token))
+
+
+class SettingsResources(_Namespace):
+    def get(self, *, auth_token: Optional[str] = None):
+        return self.api.get("/api/v1/settings", **_opts(auth_token))
+
+    def update(self, patch: Dict[str, Any], *, auth_token: Optional[str] = None):
+        return self.api.patch("/api/v1/settings", patch, **_opts(auth_token))
+
+
+class AccountResources(_Namespace):
+    def session(self, *, auth_token: Optional[str] = None):
+        return self.api.get("/api/v1/session", **_opts(auth_token))
+
+    def delete(self, *, auth_token: Optional[str] = None):
+        return self.api.delete("/api/v1/account/delete", **_opts(auth_token))
+
+
+class AdminResources(_Namespace):
+    def reconcile(self, *, auth_token: Optional[str] = None):
+        return self.api.post("/api/v1/admin/reconcile", None, **_opts(auth_token))
+
+    def orphans(self, *, auth_token: Optional[str] = None):
+        return self.api.get("/api/v1/admin/orphans", **_opts(auth_token))
+
+
+def build_resources(api: ApiClient) -> Dict[str, _Namespace]:
+    return {
+        "sessions": SessionsResources(api),
+        "credits": CreditsResources(api),
+        "billing": BillingResources(api),
+        "settings": SettingsResources(api),
+        "account": AccountResources(api),
+        "admin": AdminResources(api),
+    }

pawpado-0.1.0/pawpado/session.py

@@ -0,0 +1,262 @@
+"""Multi-profile credentials store mirroring @forjio/sdk's Session.
+
+INI-format ``~/.pawpado/credentials``, one section per profile. Single-flight
+refresh guard prevents concurrent calls from burning the Huudis refresh-token
+family (Huudis revokes the entire family on reuse — see the
+``feedback_huudis_refresh_singleflight`` rule).
+
+This is the Python parity of the Node ``Session`` from ``@forjio/sdk``. If a
+central ``forjio-sdk-py`` is later extracted, this module moves there
+unchanged.
+"""
+
+from __future__ import annotations
+
+import configparser
+import os
+import stat
+import tempfile
+import threading
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable, Dict, Optional
+from urllib.parse import urlencode
+
+import httpx
+
+from .errors import PawpadoAuthError, RefreshError
+
+
+@dataclass
+class ProfileData:
+    access_token: str
+    expires_at: int
+    issuer: str
+    client_id: str
+    refresh_token: Optional[str] = None
+    scope: Optional[str] = None
+    account_id: Optional[str] = None
+
+
+# Default refresh implementation — hits the OIDC token endpoint at
+# ``{issuer}/api/v1/oidc/token``. Tests inject their own via the
+# ``refresh_impl`` constructor arg.
+def _default_refresh(
+    *,
+    issuer: str,
+    client_id: str,
+    refresh_token: str,
+    scope: Optional[str] = None,
+    http: Optional[httpx.Client] = None,
+) -> Dict[str, Any]:
+    body = {
+        "grant_type": "refresh_token",
+        "refresh_token": refresh_token,
+        "client_id": client_id,
+    }
+    if scope:
+        body["scope"] = scope
+    client = http or httpx.Client(timeout=10.0)
+    owns = http is None
+    try:
+        res = client.post(
+            f"{issuer.rstrip('/')}/api/v1/oidc/token",
+            headers={"content-type": "application/x-www-form-urlencoded"},
+            content=urlencode(body),
+        )
+    except httpx.HTTPError as e:
+        raise RefreshError("NETWORK_ERROR", str(e)) from e
+    finally:
+        if owns:
+            client.close()
+    try:
+        payload = res.json()
+    except Exception:
+        payload = {}
+    if res.status_code >= 400:
+        code = (payload.get("error") if isinstance(payload, dict) else None) or "refresh_failed"
+        desc = (payload.get("error_description") if isinstance(payload, dict) else None) or "refresh failed"
+        raise RefreshError(str(code).upper(), str(desc))
+    return payload
+
+
+class Session:
+    def __init__(
+        self,
+        *,
+        brand: str = "pawpado",
+        profile: Optional[str] = None,
+        credentials_path: Optional[str] = None,
+        http: Optional[httpx.Client] = None,
+        refresh_impl: Optional[Callable[..., Dict[str, Any]]] = None,
+    ) -> None:
+        self.brand = brand
+        env_key = f"{brand.upper()}_PROFILE"
+        self.profile = profile or os.environ.get(env_key, "default")
+        self.credentials_path = Path(
+            credentials_path or os.path.expanduser(f"~/.{brand}/credentials")
+        )
+        self.http = http
+        self._refresh_impl = refresh_impl or _default_refresh
+        self._data: Optional[ProfileData] = None
+        self._refresh_lock = threading.Lock()
+        self._refresh_in_flight: Optional[threading.Event] = None
+        self._refresh_error: Optional[BaseException] = None
+
+    @property
+    def data(self) -> Optional[ProfileData]:
+        return self._data
+
+    def set_data(self, data: ProfileData) -> None:
+        """In-memory only — useful for tests and ad-hoc use."""
+        self._data = data
+
+    def load(self) -> ProfileData:
+        if not self.credentials_path.exists():
+            raise PawpadoAuthError(
+                "SESSION_NOT_FOUND",
+                f"credentials file not found at {self.credentials_path}",
+            )
+        parser = configparser.ConfigParser()
+        parser.read(self.credentials_path)
+        if not parser.has_section(self.profile):
+            raise PawpadoAuthError(
+                "PROFILE_NOT_FOUND",
+                f"profile [{self.profile}] not in {self.credentials_path}",
+            )
+        section = parser[self.profile]
+        for required in ("access_token", "issuer", "client_id"):
+            if required not in section:
+                raise PawpadoAuthError(
+                    "SESSION_INCOMPLETE",
+                    f"profile [{self.profile}] missing {required}",
+                )
+        self._data = ProfileData(
+            access_token=section["access_token"],
+            expires_at=int(section.get("expires_at", "0") or "0"),
+            issuer=section["issuer"],
+            client_id=section["client_id"],
+            refresh_token=section.get("refresh_token") or None,
+            scope=section.get("scope") or None,
+            account_id=section.get("account_id") or None,
+        )
+        return self._data
+
+    def save(self, data: Optional[ProfileData] = None) -> None:
+        if data is not None:
+            self._data = data
+        if self._data is None:
+            raise RuntimeError("Session.save called with no data")
+        parser = configparser.ConfigParser()
+        if self.credentials_path.exists():
+            parser.read(self.credentials_path)
+        parser[self.profile] = {
+            "access_token": self._data.access_token,
+            "expires_at": str(self._data.expires_at),
+            "issuer": self._data.issuer,
+            "client_id": self._data.client_id,
+        }
+        if self._data.refresh_token:
+            parser[self.profile]["refresh_token"] = self._data.refresh_token
+        if self._data.scope:
+            parser[self.profile]["scope"] = self._data.scope
+        if self._data.account_id:
+            parser[self.profile]["account_id"] = self._data.account_id
+        self.credentials_path.parent.mkdir(parents=True, exist_ok=True)
+        fd, tmp = tempfile.mkstemp(prefix=".credentials.", dir=str(self.credentials_path.parent))
+        try:
+            with os.fdopen(fd, "w") as f:
+                parser.write(f)
+            os.chmod(tmp, stat.S_IRUSR | stat.S_IWUSR)
+            os.replace(tmp, self.credentials_path)
+        except Exception:
+            if os.path.exists(tmp):
+                os.unlink(tmp)
+            raise
+
+    def clear(self) -> None:
+        if not self.credentials_path.exists():
+            self._data = None
+            return
+        parser = configparser.ConfigParser()
+        parser.read(self.credentials_path)
+        if parser.has_section(self.profile):
+            parser.remove_section(self.profile)
+        self._data = None
+        if not parser.sections():
+            self.credentials_path.unlink(missing_ok=True)
+            return
+        fd, tmp = tempfile.mkstemp(prefix=".credentials.", dir=str(self.credentials_path.parent))
+        try:
+            with os.fdopen(fd, "w") as f:
+                parser.write(f)
+            os.chmod(tmp, stat.S_IRUSR | stat.S_IWUSR)
+            os.replace(tmp, self.credentials_path)
+        except Exception:
+            if os.path.exists(tmp):
+                os.unlink(tmp)
+            raise
+
+    def is_expired(self) -> bool:
+        if self._data is None:
+            return True
+        return time.time() >= self._data.expires_at
+
+    def will_expire_soon(self, buffer_sec: int = 300) -> bool:
+        if self._data is None:
+            return True
+        return time.time() + buffer_sec >= self._data.expires_at
+
+    def refresh(self) -> None:
+        """Single-flight refresh. Concurrent callers share the same refresh."""
+        with self._refresh_lock:
+            if self._refresh_in_flight is not None:
+                event = self._refresh_in_flight
+            else:
+                self._refresh_in_flight = threading.Event()
+                self._refresh_error = None
+                event = self._refresh_in_flight
+                self._spawn_refresh()
+        event.wait()
+        if self._refresh_error is not None:
+            raise self._refresh_error
+
+    def _spawn_refresh(self) -> None:
+        try:
+            self._do_refresh()
+        except BaseException as e:  # noqa: BLE001
+            self._refresh_error = e
+        finally:
+            event = self._refresh_in_flight
+            with self._refresh_lock:
+                self._refresh_in_flight = None
+            if event is not None:
+                event.set()
+
+    def _do_refresh(self) -> None:
+        if self._data is None:
+            raise RefreshError("NO_SESSION", "load() or set_data() before refresh()")
+        if not self._data.refresh_token:
+            raise RefreshError("NO_REFRESH_TOKEN", "session has no refresh_token")
+        payload = self._refresh_impl(
+            issuer=self._data.issuer,
+            client_id=self._data.client_id,
+            refresh_token=self._data.refresh_token,
+            scope=self._data.scope,
+            http=self.http,
+        )
+        expires_in = int(payload.get("expires_in", 3600))
+        self._data = ProfileData(
+            access_token=payload["access_token"],
+            expires_at=int(time.time()) + expires_in,
+            issuer=self._data.issuer,
+            client_id=self._data.client_id,
+            refresh_token=payload.get("refresh_token") or self._data.refresh_token,
+            scope=payload.get("scope") or self._data.scope,
+            account_id=self._data.account_id,
+        )
+        # Only persist if we have a credentials file already on disk; in-memory
+        # sessions stay in memory.
+        if self.credentials_path.exists():
+            self.save()

pawpado-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pawpado"
+version = "0.1.0"
+description = "Official Python SDK for Pawpado — single-user AWS GPU gaming portal. Sessions (start/stop/poll/pair/connect), credits, billing, settings, admin. Bearer auth via Huudis OIDC device flow."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+keywords = ["pawpado", "forjio", "aws", "gpu", "gaming", "huudis"]
+authors = [{ name = "Forjio", email = "hello@pawpado.com" }]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Internet :: WWW/HTTP",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.27.0",
+  "PyJWT[crypto]>=2.9.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "respx>=0.21",
+]
+
+[project.urls]
+Homepage = "https://pawpado.com"
+Source = "https://github.com/hachimi-cat/saas-pawpado/tree/main/sdk/python"
+Issues = "https://github.com/hachimi-cat/saas-pawpado/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["pawpado"]

pawpado-0.1.0/tests/test_client.py

@@ -0,0 +1,230 @@
+"""Smoke tests for PawpadoClient — uses respx to intercept httpx.
+
+Same testing strategy as the Node SDK's ``test/resources.test.ts``: spin up
+a fake transport, fire each method once, assert path + method + body +
+Bearer header.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from typing import Any
+
+import httpx
+import pytest
+import respx
+
+from pawpado import (
+    ApiError,
+    PawpadoClient,
+    PawpadoError,
+    ProfileData,
+    Session,
+)
+
+BASE = "https://pawpado.test"
+
+
+def _envelope(data: Any) -> dict:
+    return {
+        "data": data,
+        "error": None,
+        "meta": {"requestId": "req_test", "timestamp": "now"},
+    }
+
+
+@pytest.fixture
+def mock():
+    with respx.mock(base_url=BASE, assert_all_called=False) as m:
+        yield m
+
+
+def _ok_route(mock, method: str, path: str):
+    return getattr(mock, method.lower())(path).mock(
+        return_value=httpx.Response(200, json=_envelope({"ok": True}))
+    )
+
+
+# ─── Construction ────────────────────────────────────────────────────────
+
+
+def test_client_construction_defaults():
+    c = PawpadoClient()
+    assert c.base_url == "https://pawpado.com"
+    # All resource namespaces exist
+    assert c.sessions and c.credits and c.billing
+    assert c.settings and c.account and c.admin
+
+
+# ─── Bearer auth via api_key ─────────────────────────────────────────────
+
+
+def test_api_key_attaches_bearer(mock):
+    route = _ok_route(mock, "GET", "/api/v1/sessions/poll")
+    client = PawpadoClient(base_url=BASE, api_key="tok")
+    client.sessions.poll()
+    assert route.calls.last.request.headers["authorization"] == "Bearer tok"
+
+
+def test_per_call_token_overrides_api_key(mock):
+    route = _ok_route(mock, "GET", "/api/v1/sessions/poll")
+    client = PawpadoClient(base_url=BASE, api_key="tok")
+    client.sessions.poll(auth_token="override")
+    assert route.calls.last.request.headers["authorization"] == "Bearer override"
+
+
+def test_no_auth_header_when_no_token(mock):
+    route = _ok_route(mock, "GET", "/api/v1/sessions/poll")
+    client = PawpadoClient(base_url=BASE)
+    client.sessions.poll()
+    assert "authorization" not in route.calls.last.request.headers
+
+
+# ─── Every route ─────────────────────────────────────────────────────────
+
+
+def test_sessions_start_post(mock):
+    route = _ok_route(mock, "POST", "/api/v1/sessions/start")
+    PawpadoClient(base_url=BASE, api_key="t").sessions.start()
+    assert route.called
+    assert route.calls.last.request.method == "POST"
+
+
+def test_sessions_stop_post_with_body(mock):
+    route = _ok_route(mock, "POST", "/api/v1/sessions/stop")
+    PawpadoClient(base_url=BASE, api_key="t").sessions.stop({"force": True})
+    assert json.loads(route.calls.last.request.content) == {"force": True}
+
+
+def test_sessions_pair_post(mock):
+    route = _ok_route(mock, "POST", "/api/v1/sessions/pair")
+    PawpadoClient(base_url=BASE, api_key="t").sessions.pair()
+    assert route.called
+
+
+def test_sessions_connect_get(mock):
+    route = _ok_route(mock, "GET", "/api/v1/sessions/connect")
+    PawpadoClient(base_url=BASE, api_key="t").sessions.connect()
+    assert route.called
+
+
+def test_sessions_tailscale_key_post(mock):
+    route = _ok_route(mock, "POST", "/api/v1/sessions/tailscale-key")
+    PawpadoClient(base_url=BASE, api_key="t").sessions.tailscale_key()
+    assert route.called
+
+
+def test_credits_me_get(mock):
+    route = _ok_route(mock, "GET", "/api/v1/credits/me")
+    PawpadoClient(base_url=BASE, api_key="t").credits.me()
+    assert route.called
+
+
+def test_credits_topup_post(mock):
+    route = _ok_route(mock, "POST", "/api/v1/credits/topup")
+    PawpadoClient(base_url=BASE, api_key="t").credits.topup(
+        {"amountCents": 50000, "currency": "IDR"},
+    )
+    body = json.loads(route.calls.last.request.content)
+    assert body == {"amountCents": 50000, "currency": "IDR"}
+
+
+def test_billing_storage_get(mock):
+    route = _ok_route(mock, "GET", "/api/v1/billing/storage")
+    PawpadoClient(base_url=BASE, api_key="t").billing.storage()
+    assert route.called
+
+
+def test_settings_get(mock):
+    route = _ok_route(mock, "GET", "/api/v1/settings")
+    PawpadoClient(base_url=BASE, api_key="t").settings.get()
+    assert route.called
+
+
+def test_settings_update_patches(mock):
+    route = _ok_route(mock, "PATCH", "/api/v1/settings")
+    PawpadoClient(base_url=BASE, api_key="t").settings.update({"autoStopMinutes": 30})
+    assert route.calls.last.request.method == "PATCH"
+    assert json.loads(route.calls.last.request.content) == {"autoStopMinutes": 30}
+
+
+def test_account_session_get(mock):
+    route = _ok_route(mock, "GET", "/api/v1/session")
+    PawpadoClient(base_url=BASE, api_key="t").account.session()
+    assert route.called
+
+
+def test_account_delete(mock):
+    route = _ok_route(mock, "DELETE", "/api/v1/account/delete")
+    PawpadoClient(base_url=BASE, api_key="t").account.delete()
+    assert route.calls.last.request.method == "DELETE"
+
+
+def test_admin_reconcile_post(mock):
+    route = _ok_route(mock, "POST", "/api/v1/admin/reconcile")
+    PawpadoClient(base_url=BASE, api_key="t").admin.reconcile()
+    assert route.called
+
+
+def test_admin_orphans_get(mock):
+    route = _ok_route(mock, "GET", "/api/v1/admin/orphans")
+    PawpadoClient(base_url=BASE, api_key="t").admin.orphans()
+    assert route.called
+
+
+def test_health_no_auth(mock):
+    route = _ok_route(mock, "GET", "/api/v1/health")
+    PawpadoClient(base_url=BASE).health()
+    assert "authorization" not in route.calls.last.request.headers
+
+
+# ─── Errors ──────────────────────────────────────────────────────────────
+
+
+def test_enveloped_error_raises_pawpado_error(mock):
+    mock.get("/api/v1/sessions/poll").mock(
+        return_value=httpx.Response(
+            400,
+            json={
+                "data": None,
+                "error": {"code": "BAD_STATE", "message": "session not running"},
+                "meta": {"requestId": "req_x", "timestamp": "now"},
+            },
+        ),
+    )
+    with pytest.raises(PawpadoError) as exc:
+        PawpadoClient(base_url=BASE, api_key="t").sessions.poll()
+    assert exc.value.code == "BAD_STATE"
+    assert exc.value.status == 400
+    assert exc.value.request_id == "req_x"
+    # Alias still works.
+    assert isinstance(exc.value, ApiError)
+
+
+def test_non_enveloped_4xx_raises(mock):
+    mock.get("/api/v1/sessions/poll").mock(
+        return_value=httpx.Response(404, text="not found"),
+    )
+    with pytest.raises(PawpadoError) as exc:
+        PawpadoClient(base_url=BASE, api_key="t").sessions.poll()
+    assert exc.value.status == 404
+
+
+# ─── Session-based auth (Bearer via Session) ─────────────────────────────
+
+
+def test_session_bearer_used(mock):
+    route = _ok_route(mock, "GET", "/api/v1/credits/me")
+    session = Session(brand="pawpado", credentials_path="/tmp/__never_exists__")
+    session.set_data(
+        ProfileData(
+            access_token="sess_tok",
+            expires_at=int(time.time()) + 3600,
+            issuer="https://huudis.test",
+            client_id="oc_pawpado",
+        )
+    )
+    client = PawpadoClient(base_url=BASE, session=session)
+    client.credits.me()
+    assert route.calls.last.request.headers["authorization"] == "Bearer sess_tok"