dominusnode 1.0.0__py3-none-any.whl

dominusnode/teams.py

@@ -0,0 +1,339 @@
+"""Teams resource -- team management with members, invites, wallet, and API keys."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+from urllib.parse import quote
+
+from .http_client import AsyncHttpClient, SyncHttpClient
+from .wallet import _validate_amount_cents
+from .types import (
+    Team,
+    TeamMember,
+    TeamInvite,
+    TeamTransaction,
+    TeamKey,
+    TeamKeyCreateResponse,
+    TeamDeleteResponse,
+)
+
+
+def _parse_team(data: Dict[str, Any]) -> Team:
+    return Team(
+        id=data["id"],
+        name=data["name"],
+        owner_id=data["ownerId"],
+        max_members=data.get("maxMembers", 0),
+        status=data.get("status", "active"),
+        balance_cents=data.get("balanceCents", 0),
+        created_at=data.get("createdAt", ""),
+    )
+
+
+def _parse_member(data: Dict[str, Any]) -> TeamMember:
+    return TeamMember(
+        id=data.get("id", ""),
+        team_id=data.get("teamId", ""),
+        user_id=data["userId"],
+        email=data["email"],
+        role=data["role"],
+        joined_at=data.get("joinedAt", ""),
+    )
+
+
+def _parse_invite(data: Dict[str, Any]) -> TeamInvite:
+    return TeamInvite(
+        id=data["id"],
+        team_id=data["teamId"],
+        email=data["email"],
+        role=data["role"],
+        token=data.get("token", ""),
+        expires_at=data.get("expiresAt", ""),
+        created_at=data.get("createdAt", ""),
+    )
+
+
+def _parse_transaction(data: Dict[str, Any]) -> TeamTransaction:
+    return TeamTransaction(
+        id=data["id"],
+        team_id=data["teamId"],
+        type=data["type"],
+        amount_cents=data["amountCents"],
+        description=data["description"],
+        created_at=data.get("createdAt", ""),
+    )
+
+
+def _parse_key(data: Dict[str, Any]) -> TeamKey:
+    return TeamKey(
+        id=data["id"],
+        key_prefix=data["keyPrefix"],
+        label=data["label"],
+        created_at=data.get("createdAt", ""),
+    )
+
+
+class TeamsResource:
+    """Synchronous team operations."""
+
+    def __init__(self, http: SyncHttpClient) -> None:
+        self._http = http
+
+    def create(self, name: str, max_members: Optional[int] = None) -> Team:
+        """Create a new team."""
+        body: Dict[str, Any] = {"name": name}
+        if max_members is not None:
+            body["maxMembers"] = max_members
+        data = self._http.post("/api/teams", json=body)
+        return _parse_team(data)
+
+    def list(self) -> List[Team]:
+        """List all teams the user belongs to."""
+        data = self._http.get("/api/teams")
+        return [_parse_team(t) for t in data]
+
+    def get(self, team_id: str) -> Team:
+        """Get a single team by ID."""
+        data = self._http.get(f"/api/teams/{quote(team_id, safe='')}")
+        return _parse_team(data)
+
+    def update(self, team_id: str, name: Optional[str] = None, max_members: Optional[int] = None) -> Team:
+        """Update a team's settings."""
+        body: Dict[str, Any] = {}
+        if name is not None:
+            body["name"] = name
+        if max_members is not None:
+            body["maxMembers"] = max_members
+        data = self._http.patch(f"/api/teams/{quote(team_id, safe='')}", json=body)
+        return _parse_team(data)
+
+    def delete(self, team_id: str) -> TeamDeleteResponse:
+        """Delete a team and refund remaining wallet balance."""
+        data = self._http.delete(f"/api/teams/{quote(team_id, safe='')}")
+        return TeamDeleteResponse(refunded_cents=data["refundedCents"])
+
+    def fund_wallet(self, team_id: str, amount_cents: int) -> TeamTransaction:
+        """Fund the team wallet from the user's main wallet."""
+        _validate_amount_cents(amount_cents, "amount_cents")
+        data = self._http.post(
+            f"/api/teams/{quote(team_id, safe='')}/wallet/fund",
+            json={"amountCents": amount_cents},
+        )
+        return _parse_transaction(data["transaction"])
+
+    def get_transactions(self, team_id: str, limit: int = 50, offset: int = 0) -> List[TeamTransaction]:
+        """Get wallet transaction history for a team."""
+        data = self._http.get(
+            f"/api/teams/{quote(team_id, safe='')}/wallet/transactions?limit={limit}&offset={offset}"
+        )
+        return [_parse_transaction(tx) for tx in data["transactions"]]
+
+    def list_members(self, team_id: str) -> List[TeamMember]:
+        """List all members of a team."""
+        data = self._http.get(f"/api/teams/{quote(team_id, safe='')}/members")
+        return [_parse_member(m) for m in data["members"]]
+
+    def add_member(self, team_id: str, email: str, role: Optional[str] = None) -> TeamMember:
+        """Add a member to a team."""
+        body: Dict[str, Any] = {"email": email}
+        if role is not None:
+            body["role"] = role
+        data = self._http.post(f"/api/teams/{quote(team_id, safe='')}/members", json=body)
+        return _parse_member(data)
+
+    def update_member_role(self, team_id: str, user_id: str, role: str) -> TeamMember:
+        """Update a member's role within a team."""
+        data = self._http.patch(
+            f"/api/teams/{quote(team_id, safe='')}/members/{quote(user_id, safe='')}",
+            json={"role": role},
+        )
+        return _parse_member(data)
+
+    def remove_member(self, team_id: str, user_id: str) -> None:
+        """Remove a member from a team."""
+        self._http.delete(
+            f"/api/teams/{quote(team_id, safe='')}/members/{quote(user_id, safe='')}"
+        )
+
+    def create_invite(self, team_id: str, email: str, role: Optional[str] = None) -> TeamInvite:
+        """Create an invite for a team."""
+        body: Dict[str, Any] = {"email": email}
+        if role is not None:
+            body["role"] = role
+        data = self._http.post(f"/api/teams/{quote(team_id, safe='')}/invites", json=body)
+        return _parse_invite(data)
+
+    def list_invites(self, team_id: str) -> List[TeamInvite]:
+        """List pending invites for a team."""
+        data = self._http.get(f"/api/teams/{quote(team_id, safe='')}/invites")
+        return [_parse_invite(i) for i in data["invites"]]
+
+    def cancel_invite(self, team_id: str, invite_id: str) -> None:
+        """Cancel a pending invite."""
+        self._http.delete(
+            f"/api/teams/{quote(team_id, safe='')}/invites/{quote(invite_id, safe='')}"
+        )
+
+    def accept_invite(self, token: str) -> TeamMember:
+        """Accept a team invite using the invite token."""
+        data = self._http.post(
+            f"/api/teams/invites/{quote(token, safe='')}/accept", json={}
+        )
+        return _parse_member(data)
+
+    def create_key(self, team_id: str, label: str) -> TeamKeyCreateResponse:
+        """Create a new API key for the team."""
+        data = self._http.post(
+            f"/api/teams/{quote(team_id, safe='')}/keys",
+            json={"label": label},
+        )
+        return TeamKeyCreateResponse(
+            id=data["id"],
+            key=data["key"],
+            key_prefix=data["keyPrefix"],
+            label=data["label"],
+        )
+
+    def list_keys(self, team_id: str) -> List[TeamKey]:
+        """List API keys for a team."""
+        data = self._http.get(f"/api/teams/{quote(team_id, safe='')}/keys")
+        return [_parse_key(k) for k in data["keys"]]
+
+    def revoke_key(self, team_id: str, key_id: str) -> None:
+        """Revoke a team API key by its ID."""
+        self._http.delete(
+            f"/api/teams/{quote(team_id, safe='')}/keys/{quote(key_id, safe='')}"
+        )
+
+
+class AsyncTeamsResource:
+    """Asynchronous team operations."""
+
+    def __init__(self, http: AsyncHttpClient) -> None:
+        self._http = http
+
+    async def create(self, name: str, max_members: Optional[int] = None) -> Team:
+        """Create a new team."""
+        body: Dict[str, Any] = {"name": name}
+        if max_members is not None:
+            body["maxMembers"] = max_members
+        data = await self._http.post("/api/teams", json=body)
+        return _parse_team(data)
+
+    async def list(self) -> List[Team]:
+        """List all teams the user belongs to."""
+        data = await self._http.get("/api/teams")
+        return [_parse_team(t) for t in data]
+
+    async def get(self, team_id: str) -> Team:
+        """Get a single team by ID."""
+        data = await self._http.get(f"/api/teams/{quote(team_id, safe='')}")
+        return _parse_team(data)
+
+    async def update(self, team_id: str, name: Optional[str] = None, max_members: Optional[int] = None) -> Team:
+        """Update a team's settings."""
+        body: Dict[str, Any] = {}
+        if name is not None:
+            body["name"] = name
+        if max_members is not None:
+            body["maxMembers"] = max_members
+        data = await self._http.patch(f"/api/teams/{quote(team_id, safe='')}", json=body)
+        return _parse_team(data)
+
+    async def delete(self, team_id: str) -> TeamDeleteResponse:
+        """Delete a team and refund remaining wallet balance."""
+        data = await self._http.delete(f"/api/teams/{quote(team_id, safe='')}")
+        return TeamDeleteResponse(refunded_cents=data["refundedCents"])
+
+    async def fund_wallet(self, team_id: str, amount_cents: int) -> TeamTransaction:
+        """Fund the team wallet from the user's main wallet."""
+        _validate_amount_cents(amount_cents, "amount_cents")
+        data = await self._http.post(
+            f"/api/teams/{quote(team_id, safe='')}/wallet/fund",
+            json={"amountCents": amount_cents},
+        )
+        return _parse_transaction(data["transaction"])
+
+    async def get_transactions(self, team_id: str, limit: int = 50, offset: int = 0) -> List[TeamTransaction]:
+        """Get wallet transaction history for a team."""
+        data = await self._http.get(
+            f"/api/teams/{quote(team_id, safe='')}/wallet/transactions?limit={limit}&offset={offset}"
+        )
+        return [_parse_transaction(tx) for tx in data["transactions"]]
+
+    async def list_members(self, team_id: str) -> List[TeamMember]:
+        """List all members of a team."""
+        data = await self._http.get(f"/api/teams/{quote(team_id, safe='')}/members")
+        return [_parse_member(m) for m in data["members"]]
+
+    async def add_member(self, team_id: str, email: str, role: Optional[str] = None) -> TeamMember:
+        """Add a member to a team."""
+        body: Dict[str, Any] = {"email": email}
+        if role is not None:
+            body["role"] = role
+        data = await self._http.post(f"/api/teams/{quote(team_id, safe='')}/members", json=body)
+        return _parse_member(data)
+
+    async def update_member_role(self, team_id: str, user_id: str, role: str) -> TeamMember:
+        """Update a member's role within a team."""
+        data = await self._http.patch(
+            f"/api/teams/{quote(team_id, safe='')}/members/{quote(user_id, safe='')}",
+            json={"role": role},
+        )
+        return _parse_member(data)
+
+    async def remove_member(self, team_id: str, user_id: str) -> None:
+        """Remove a member from a team."""
+        await self._http.delete(
+            f"/api/teams/{quote(team_id, safe='')}/members/{quote(user_id, safe='')}"
+        )
+
+    async def create_invite(self, team_id: str, email: str, role: Optional[str] = None) -> TeamInvite:
+        """Create an invite for a team."""
+        body: Dict[str, Any] = {"email": email}
+        if role is not None:
+            body["role"] = role
+        data = await self._http.post(f"/api/teams/{quote(team_id, safe='')}/invites", json=body)
+        return _parse_invite(data)
+
+    async def list_invites(self, team_id: str) -> List[TeamInvite]:
+        """List pending invites for a team."""
+        data = await self._http.get(f"/api/teams/{quote(team_id, safe='')}/invites")
+        return [_parse_invite(i) for i in data["invites"]]
+
+    async def cancel_invite(self, team_id: str, invite_id: str) -> None:
+        """Cancel a pending invite."""
+        await self._http.delete(
+            f"/api/teams/{quote(team_id, safe='')}/invites/{quote(invite_id, safe='')}"
+        )
+
+    async def accept_invite(self, token: str) -> TeamMember:
+        """Accept a team invite using the invite token."""
+        data = await self._http.post(
+            f"/api/teams/invites/{quote(token, safe='')}/accept", json={}
+        )
+        return _parse_member(data)
+
+    async def create_key(self, team_id: str, label: str) -> TeamKeyCreateResponse:
+        """Create a new API key for the team."""
+        data = await self._http.post(
+            f"/api/teams/{quote(team_id, safe='')}/keys",
+            json={"label": label},
+        )
+        return TeamKeyCreateResponse(
+            id=data["id"],
+            key=data["key"],
+            key_prefix=data["keyPrefix"],
+            label=data["label"],
+        )
+
+    async def list_keys(self, team_id: str) -> List[TeamKey]:
+        """List API keys for a team."""
+        data = await self._http.get(f"/api/teams/{quote(team_id, safe='')}/keys")
+        return [_parse_key(k) for k in data["keys"]]
+
+    async def revoke_key(self, team_id: str, key_id: str) -> None:
+        """Revoke a team API key by its ID."""
+        await self._http.delete(
+            f"/api/teams/{quote(team_id, safe='')}/keys/{quote(key_id, safe='')}"
+        )

dominusnode/token_manager.py

@@ -0,0 +1,235 @@
+"""JWT token management with auto-refresh.
+
+Tokens are stored in memory only -- never written to disk.
+JWT expiry is decoded from the base64 payload without cryptographic
+verification (the server validates the signature).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+import threading
+import time
+from typing import TYPE_CHECKING, Callable, Optional
+
+from .constants import TOKEN_REFRESH_BUFFER_SECONDS
+
+if TYPE_CHECKING:
+    from typing import Awaitable
+
+
+class TokenManager:
+    """Sync token manager with threading.Lock for singleton refresh."""
+
+    def __init__(self) -> None:
+        self._access_token: Optional[str] = None
+        self._refresh_token: Optional[str] = None
+        self._refresh_lock = threading.Lock()
+        self._refresh_fn: Optional[Callable[[str], tuple[str, str]]] = None
+
+    def set_tokens(self, access_token: str, refresh_token: str) -> None:
+        """Store a new token pair."""
+        self._access_token = access_token
+        self._refresh_token = refresh_token
+
+    def set_refresh_fn(self, fn: Callable[[str], tuple[str, str]]) -> None:
+        """Register the sync function that performs token refresh.
+
+        The function receives the current refresh token and must return
+        a (new_access_token, new_refresh_token) tuple.
+        """
+        self._refresh_fn = fn
+
+    def clear(self) -> None:
+        """Remove stored tokens."""
+        self._access_token = None
+        self._refresh_token = None
+
+    @property
+    def access_token(self) -> Optional[str]:
+        return self._access_token
+
+    @property
+    def refresh_token(self) -> Optional[str]:
+        return self._refresh_token
+
+    @property
+    def has_tokens(self) -> bool:
+        return self._access_token is not None
+
+    @property
+    def has_refresh_token(self) -> bool:
+        return self._refresh_token is not None
+
+    def get_valid_token(self) -> Optional[str]:
+        """Return a valid access token, refreshing if needed.
+
+        Returns None if no tokens are available or refresh fails.
+        """
+        if self._access_token is None:
+            return None
+
+        if not is_expired(self._access_token):
+            return self._access_token
+
+        # Token expired or about to expire -- try refresh
+        return self._do_refresh()
+
+    def force_refresh(self) -> Optional[str]:
+        """Force a token refresh regardless of expiry (e.g., after 401).
+
+        Raises RuntimeError if refresh fails instead of returning None,
+        preventing "Bearer None" from being sent as an auth header.
+        """
+        return self._do_refresh(force=True)
+
+    def _do_refresh(self, force: bool = False) -> Optional[str]:
+        """Perform a singleton refresh under lock."""
+        if self._refresh_token is None or self._refresh_fn is None:
+            if force:
+                raise RuntimeError("No valid token and cannot refresh")
+            return None
+
+        with self._refresh_lock:
+            # Double-check: another thread may have refreshed while we waited
+            # Skip double-check on force_refresh — the whole point is to NOT reuse current token
+            if not force and self._access_token and not is_expired(self._access_token):
+                return self._access_token
+
+            try:
+                new_access, new_refresh = self._refresh_fn(self._refresh_token)
+                self._access_token = new_access
+                self._refresh_token = new_refresh
+                return self._access_token
+            except Exception:
+                self.clear()
+                if force:
+                    raise RuntimeError("Token refresh failed")
+                return None
+
+
+class AsyncTokenManager:
+    """Async token manager with asyncio.Lock for singleton refresh.
+
+    The lock is created lazily on first use to avoid binding to an event loop
+    at __init__ time, which would fail if the TokenManager is constructed
+    outside of an async context (e.g., in frameworks that manage their own
+    event loops like FastAPI/uvicorn or Django ASGI).
+    """
+
+    def __init__(self) -> None:
+        self._access_token: Optional[str] = None
+        self._refresh_token: Optional[str] = None
+        self._refresh_lock: Optional[asyncio.Lock] = None
+        self._refresh_fn: Optional[Callable[[str], Awaitable[tuple[str, str]]]] = None
+
+    def _get_lock(self) -> asyncio.Lock:
+        """Lazily create the asyncio.Lock on first use within an async context."""
+        if self._refresh_lock is None:
+            self._refresh_lock = asyncio.Lock()
+        return self._refresh_lock
+
+    def set_tokens(self, access_token: str, refresh_token: str) -> None:
+        """Store a new token pair."""
+        self._access_token = access_token
+        self._refresh_token = refresh_token
+
+    def set_refresh_fn(self, fn: Callable[[str], Awaitable[tuple[str, str]]]) -> None:
+        """Register the async function that performs token refresh."""
+        self._refresh_fn = fn
+
+    def clear(self) -> None:
+        """Remove stored tokens."""
+        self._access_token = None
+        self._refresh_token = None
+
+    @property
+    def access_token(self) -> Optional[str]:
+        return self._access_token
+
+    @property
+    def refresh_token(self) -> Optional[str]:
+        return self._refresh_token
+
+    @property
+    def has_tokens(self) -> bool:
+        return self._access_token is not None
+
+    @property
+    def has_refresh_token(self) -> bool:
+        return self._refresh_token is not None
+
+    async def get_valid_token(self) -> Optional[str]:
+        """Return a valid access token, refreshing if needed."""
+        if self._access_token is None:
+            return None
+
+        if not is_expired(self._access_token):
+            return self._access_token
+
+        return await self._do_refresh()
+
+    async def force_refresh(self) -> Optional[str]:
+        """Force a token refresh regardless of expiry (e.g., after 401).
+
+        Raises RuntimeError if refresh fails instead of returning None.
+        """
+        return await self._do_refresh(force=True)
+
+    async def _do_refresh(self, force: bool = False) -> Optional[str]:
+        """Perform a singleton refresh under async lock."""
+        if self._refresh_token is None or self._refresh_fn is None:
+            if force:
+                raise RuntimeError("No valid token and cannot refresh")
+            return None
+
+        async with self._get_lock():
+            # Skip double-check on force_refresh
+            if not force and self._access_token and not is_expired(self._access_token):
+                return self._access_token
+
+            try:
+                new_access, new_refresh = await self._refresh_fn(self._refresh_token)
+                self._access_token = new_access
+                self._refresh_token = new_refresh
+                return self._access_token
+            except Exception:
+                self.clear()
+                if force:
+                    raise RuntimeError("Token refresh failed")
+                return None
+
+
+def is_expired(token: str) -> bool:
+    """Check if a JWT is expired or will expire within the buffer window.
+
+    Decodes the base64 payload to read the ``exp`` claim. No signature
+    verification is performed -- that is the server's responsibility.
+
+    Returns True if the token is expired / about to expire, or if the
+    token cannot be decoded.
+    """
+    try:
+        parts = token.split(".")
+        if len(parts) != 3:
+            return True
+
+        # Base64url decode the payload (second segment)
+        payload_b64 = parts[1]
+        # Add padding
+        padding = 4 - len(payload_b64) % 4
+        if padding != 4:
+            payload_b64 += "=" * padding
+
+        payload_bytes = base64.urlsafe_b64decode(payload_b64)
+        payload = json.loads(payload_bytes)
+
+        exp = payload.get("exp")
+        if exp is None:
+            return True
+
+        return time.time() >= (exp - TOKEN_REFRESH_BUFFER_SECONDS)
+    except Exception:
+        return True