keyrunes-python-sdk 0.2.0__tar.gz → 0.3.0__tar.gz

{keyrunes_python_sdk-0.2.0 → keyrunes_python_sdk-0.3.0}/CHANGELOG.md

@@ -5,6 +5,61 @@ Todas as mudanças notáveis neste projeto serão documentadas neste arquivo.
 O formato é baseado em [Keep a Changelog](https://keepachangelog.com/pt-BR/1.0.0/),
 e este projeto adere ao [Semantic Versioning](https://semver.org/lang/pt-BR/).
 
+## [0.3.0] - 2026-09-03
+
+### Added
+
+- `User.user_id`, carrying the internal identifier Keyrunes puts in the JWT
+  `sub` claim. It is a different value from `User.id` (the external UUID), and
+  a consumer that keys its own records off `sub` needs it; before this release
+  it was discarded during normalization and could only be recovered by
+  re-parsing the token.
+- `User.namespace`, `User.organization_id` and `User.first_login`, all of which
+  the server returns and normalization used to drop.
+- `Token.requires_password_change`, so a login that must be followed by a
+  password change can be detected without reading the raw response.
+- `KeyrunesClient.refresh_token()`, wrapping `POST /api/refresh-token`. It
+  accepts an explicit token or falls back to the client's current one, raises
+  `InvalidTokenError` when neither is available, and adopts the refreshed
+  token the way `login()` does.
+- `get_current_user(force_refresh=True)`, which always asks the server. The
+  claims shortcut reads a token the SDK never verified, so it cannot answer
+  "is this token still accepted"; a caller validating a token needs the round
+  trip.
+- `KeyrunesError.status_code`, carrying the HTTP status when the error came
+  from a response rather than from the transport. Without it a caller cannot
+  tell "the server refused this request" (4xx) from "the server or the network
+  failed" (5xx, or no response at all), and both are raised as `NetworkError`.
+- `register_user(group=...)`, sent as a top-level field.
+- A `py.typed` marker (PEP 561). The package was already fully typed, but
+  without the marker a consumer running mypy saw every SDK import as
+  untyped.
+
+### Fixed
+
+- `get_current_user()` asked for `/api/users/me`, which the Keyrunes router
+  does not expose — the real route is `/api/me`, so the call answered 404
+  against a live server whenever the claims shortcut did not cover it. The
+  endpoint is now a named constant, `ENDPOINT_ME`.
+- `register_user()` and `register_admin()` required the response to be
+  `{"user": {...}}`, but `POST /api/register` answers with the bare user
+  object. Every registration against a real server failed with "Unexpected
+  response format". Both shapes are now accepted.
+- Extra keyword arguments to `register_user()` were nested under `attributes`,
+  so a `group` never reached the server, which reads it as a top-level field.
+  `group` is now an explicit parameter placed at the top level; other keyword
+  attributes keep nesting under `attributes`.
+
+### Testing
+
+- Test count raised from 159 to 189.
+
+### Notes
+
+- Every added field is optional with a backwards-compatible default, and
+  `User.id` keeps its existing precedence (`id` → `user_id` → `external_id`).
+  Code written against 0.2.0 keeps working unchanged.
+
 ## [0.2.0] - 2026-09-03
 
 ### Added

{keyrunes_python_sdk-0.2.0 → keyrunes_python_sdk-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: keyrunes-python-sdk
-Version: 0.2.0
+Version: 0.3.0
 Summary: Python SDK for Keyrunes Authorization System
 License: AGPL
 License-File: LICENSE

{keyrunes_python_sdk-0.2.0 → keyrunes_python_sdk-0.3.0}/keyrunes_sdk/__init__.py

@@ -1,6 +1,6 @@
 """Keyrunes SDK - Python client for Keyrunes Authorization System."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 from keyrunes_sdk.client import KeyrunesClient
 from keyrunes_sdk.config import (

{keyrunes_python_sdk-0.2.0 → keyrunes_python_sdk-0.3.0}/keyrunes_sdk/client.py

@@ -11,6 +11,7 @@ from keyrunes_sdk.exceptions import (
     AuthenticationError,
     AuthorizationError,
     GroupNotFoundError,
+    InvalidTokenError,
     NetworkError,
     UserNotFoundError,
 )
@@ -23,6 +24,17 @@ from keyrunes_sdk.models import (
     UserRegistration,
 )
 
+#: Where the server answers "who is this token". The Keyrunes router exposes
+#: this as ``/api/me``; there is no ``/api/users/me``.
+#: Creates a user; answers with the bare user object.
+ENDPOINT_REGISTER = "/api/register"
+
+#: Where the server answers "who is this token".
+ENDPOINT_ME = "/api/me"
+
+#: Exchanges a still-valid token for a fresh one.
+ENDPOINT_REFRESH_TOKEN = "/api/refresh-token"
+
 
 class KeyrunesClient:
     """
@@ -135,7 +147,10 @@ class KeyrunesClient:
                     error_msg = (
                         response.text or f"HTTP {response.status_code} error"
                     )
-                raise NetworkError(f"Request failed: {error_msg}")
+                raise NetworkError(
+                    f"Request failed: {error_msg}",
+                    status_code=response.status_code,
+                )
 
             try:
                 result: Dict[str, Any] = response.json()
@@ -170,6 +185,15 @@ class KeyrunesClient:
         normalized["is_admin"] = (
             is_admin_flag or has_admin_group or has_admin_in_name
         )
+        # Carried through untouched so a caller can key its own records off the
+        # same identifier the JWT ``sub`` uses, rather than off ``id``.
+        raw_user_id = data.get("user_id")
+        normalized["user_id"] = (
+            str(raw_user_id) if raw_user_id is not None else None
+        )
+        normalized["namespace"] = data.get("namespace")
+        normalized["organization_id"] = data.get("organization_id")
+        normalized["first_login"] = bool(data.get("first_login", False))
         return User(**normalized)
 
     def _user_from_token_claims(self) -> User:
@@ -221,6 +245,9 @@ class KeyrunesClient:
             expires_in=payload.get("expires_in"),
             refresh_token=payload.get("refresh_token"),
             user=user_model,
+            requires_password_change=bool(
+                payload.get("requires_password_change", False)
+            ),
         )
 
     def login(
@@ -267,12 +294,36 @@ class KeyrunesClient:
             self._token_data = None
         return token
 
+    @staticmethod
+    def _registration_payload(response: Any) -> Dict[str, Any]:
+        """Pull the user object out of a registration response.
+
+        ``POST /api/register`` answers with the bare user object. Some
+        deployments wrap it as ``{"user": {...}}``, so both are accepted.
+        """
+        if not isinstance(response, dict):
+            raise NetworkError(
+                "Unexpected response format for user registration."
+            )
+
+        wrapped = response.get("user")
+        if isinstance(wrapped, dict) and wrapped:
+            return wrapped
+
+        # A bare user object is identified by carrying an identifier; anything
+        # else is a response shape this SDK does not understand.
+        if response.get("id") or response.get("user_id"):
+            return response
+
+        raise NetworkError("Unexpected response format for user registration.")
+
     def register_user(
         self,
         username: str,
         email: str,
         password: str,
         namespace: str = "public",
+        group: Optional[str] = None,
         **attributes: Any,
     ) -> User:
         """
@@ -283,6 +334,8 @@ class KeyrunesClient:
             email: User email address
             password: Password (minimum 8 characters)
             namespace: User namespace (default: "public")
+            group: Group to place the new user in. Sent as a top-level field,
+                which is where the server reads it from.
             **attributes: Additional user attributes
 
         Returns:
@@ -308,22 +361,18 @@ class KeyrunesClient:
             namespace=namespace,
             attributes=attributes,
         )
+        data = registration.model_dump()
+        if group is not None:
+            data["group"] = group
+
         response = self._make_request(
             "POST",
-            "/api/register",
-            data=registration.model_dump(),
+            ENDPOINT_REGISTER,
+            data=data,
             use_auth=False,
         )
 
-        user_payload = (
-            response.get("user") if isinstance(response, dict) else None
-        )
-        if not user_payload:
-            raise NetworkError(
-                "Unexpected response format for user registration."
-            )
-
-        return self._normalize_user(user_payload)
+        return self._normalize_user(self._registration_payload(response))
 
     def register_admin(
         self,
@@ -371,20 +420,12 @@ class KeyrunesClient:
         )
         response = self._make_request(
             "POST",
-            "/api/register",
+            ENDPOINT_REGISTER,
             data=registration.model_dump(),
             use_auth=False,
         )
 
-        user_payload = (
-            response.get("user") if isinstance(response, dict) else None
-        )
-        if not user_payload:
-            raise NetworkError(
-                "Unexpected response format for admin registration."
-            )
-
-        return self._normalize_user(user_payload)
+        return self._normalize_user(self._registration_payload(response))
 
     def has_group(self, user_id: str, group_id: str) -> bool:
         """
@@ -470,10 +511,18 @@ class KeyrunesClient:
         response = self._make_request("GET", f"/api/users/{user_id}")
         return self._normalize_user(response)
 
-    def get_current_user(self) -> User:
+    def get_current_user(self, force_refresh: bool = False) -> User:
         """
         Get currently authenticated user information.
 
+        Args:
+            force_refresh: Ask the server even when the token's own claims
+                could answer. Required whenever the answer is used to decide
+                whether the token is still good: the claims shortcut reads a
+                token the SDK never verified, so it says nothing about whether
+                the server still accepts it (revoked, expired, or signed with
+                another key).
+
         Returns:
             User object for authenticated user
 
@@ -489,12 +538,10 @@ class KeyrunesClient:
         if not self._token:
             raise AuthenticationError("Not authenticated. Please login first.")
 
-        if self._token_data:
+        if self._token_data and not force_refresh:
             return self._user_from_token_claims()
 
-        # The claims shortcut above already handled every case where the token
-        # could answer, so a 404 here is a genuine miss and is propagated.
-        response = self._make_request("GET", "/api/users/me")
+        response = self._make_request("GET", ENDPOINT_ME)
         return self._normalize_user(response)
 
     def get_user_groups(self, user_id: Optional[str] = None) -> List[str]:
@@ -542,6 +589,44 @@ class KeyrunesClient:
         except Exception:
             self._token_data = None
 
+    def refresh_token(self, token: Optional[str] = None) -> Token:
+        """
+        Exchange a still-valid token for a fresh one.
+
+        Args:
+            token: Token to exchange. Defaults to the client's current token.
+
+        Returns:
+            Token object carrying the new access token.
+
+        Raises:
+            InvalidTokenError: If no token is available to exchange
+            AuthenticationError: If the server rejects the token
+            NetworkError: If the request fails
+
+        Example:
+            >>> client = KeyrunesClient("https://keyrunes.example.com")
+            >>> client.set_token("eyJhbGciOiJIUzI1NiIs...")
+            >>> refreshed = client.refresh_token()
+            >>> client.set_token(refreshed.access_token)
+        """
+        current = token or self._token
+        if not current:
+            raise InvalidTokenError("No token available to refresh.")
+
+        response = self._make_request(
+            "POST",
+            ENDPOINT_REFRESH_TOKEN,
+            data={"token": current},
+            use_auth=False,
+        )
+
+        refreshed = self._parse_token_response(response)
+        # Refreshing is only ever useful if the client keeps using the result,
+        # so adopt it the way login() does.
+        self.set_token(refreshed.access_token)
+        return refreshed
+
     def clear_token(self) -> None:
         """
         Clear authentication token.

keyrunes_python_sdk-0.3.0/keyrunes_sdk/exceptions.py

@@ -0,0 +1,62 @@
+"""Custom exceptions for Keyrunes SDK."""
+
+from typing import Optional
+
+
+class KeyrunesError(Exception):
+    """Base exception for all Keyrunes SDK errors.
+
+    Args:
+        message: Human-readable description.
+        status_code: HTTP status the server answered with, when the error came
+            from a response rather than from the transport. Callers use it to
+            tell "the server refused this request" (4xx, the caller's problem)
+            from "the server or the network failed" (5xx or no response at
+            all), which otherwise look identical.
+    """
+
+    def __init__(
+        self, message: str = "", status_code: Optional[int] = None
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class AuthenticationError(KeyrunesError):
+    """Raised when authentication fails."""
+
+    pass
+
+
+class AuthorizationError(KeyrunesError):
+    """Raised when authorization fails."""
+
+    pass
+
+
+class GroupNotFoundError(KeyrunesError):
+    """Raised when a group is not found."""
+
+    pass
+
+
+class UserNotFoundError(KeyrunesError):
+    """Raised when a user is not found."""
+
+    pass
+
+
+class InvalidTokenError(KeyrunesError):
+    """Raised when token is invalid or expired."""
+
+    pass
+
+
+class NetworkError(KeyrunesError):
+    """Raised when a request fails.
+
+    ``status_code`` is set when the server answered and the response was an
+    error; it is ``None`` when the request never got a response.
+    """
+
+    pass

{keyrunes_python_sdk-0.2.0 → keyrunes_python_sdk-0.3.0}/keyrunes_sdk/models.py

@@ -28,6 +28,23 @@ class User(BaseModel):
     is_admin: bool = Field(
         False, description="Whether user has admin privileges"
     )
+    # Keyrunes answers with two identifiers: ``id`` is the external UUID and
+    # ``user_id`` is the internal integer the JWT carries as ``sub``. ``id``
+    # above keeps its historical precedence; this field is kept alongside it so
+    # a caller that keys its own records off ``sub`` can reach that value
+    # without re-parsing the token.
+    user_id: Optional[str] = Field(
+        None, description="Internal user identifier, as carried by the JWT sub"
+    )
+    namespace: Optional[str] = Field(
+        None, description="Namespace (tenant) the user belongs to"
+    )
+    organization_id: Optional[Any] = Field(
+        None, description="Organization the user belongs to"
+    )
+    first_login: bool = Field(
+        False, description="Whether the user has yet to complete a first login"
+    )
 
 
 class Group(BaseModel):
@@ -54,6 +71,10 @@ class Token(BaseModel):
     )
     refresh_token: Optional[str] = Field(None, description="Refresh token")
     user: Optional[User] = Field(None, description="User information")
+    requires_password_change: bool = Field(
+        False,
+        description="Whether the server wants the password changed before use",
+    )
 
 
 class UserRegistration(BaseModel):

{keyrunes_python_sdk-0.2.0 → keyrunes_python_sdk-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "keyrunes-python-sdk"
-version = "0.2.0"
+version = "0.3.0"
 description = "Python SDK for Keyrunes Authorization System"
 authors = ["keyrunes <contact@singularjourney.host>"]
 maintainers = ["jonatasoli <contact@jonatasoli.dev>"]
@@ -25,7 +25,9 @@ classifiers = [
     "Topic :: System :: Systems Administration :: Authentication/Directory",
 ]
 packages = [{include = "keyrunes_sdk"}]
-include = ["LICENSE", "README.md", "CHANGELOG.md"]
+# `py.typed` marks the package as typed (PEP 561); without it a consumer
+# running mypy sees every SDK import as untyped.
+include = ["LICENSE", "README.md", "CHANGELOG.md", "keyrunes_sdk/py.typed"]
 exclude = ["tests", "examples", "docs", "*.pyc", "__pycache__"]
 
 [tool.poetry.dependencies]

keyrunes_python_sdk-0.2.0/keyrunes_sdk/exceptions.py

@@ -1,43 +0,0 @@
-"""Custom exceptions for Keyrunes SDK."""
-
-
-class KeyrunesError(Exception):
-    """Base exception for all Keyrunes SDK errors."""
-
-    pass
-
-
-class AuthenticationError(KeyrunesError):
-    """Raised when authentication fails."""
-
-    pass
-
-
-class AuthorizationError(KeyrunesError):
-    """Raised when authorization fails."""
-
-    pass
-
-
-class GroupNotFoundError(KeyrunesError):
-    """Raised when a group is not found."""
-
-    pass
-
-
-class UserNotFoundError(KeyrunesError):
-    """Raised when a user is not found."""
-
-    pass
-
-
-class InvalidTokenError(KeyrunesError):
-    """Raised when token is invalid or expired."""
-
-    pass
-
-
-class NetworkError(KeyrunesError):
-    """Raised when network request fails."""
-
-    pass