saamfi-sdk 0.1.0__py3-none-any.whl

saamfi_sdk/services/base.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+import requests
+
+
+class SaamfiServiceBase:
+    """Common helpers for Saamfi service classes."""
+
+    def __init__(self, base_url: str, session: requests.Session):
+        self._base_url = base_url.rstrip("/")
+        self._session = session
+
+    def _build_url(self, path: str) -> str:
+        """Construct an absolute URL from a path."""
+        return f"{self._base_url}/{path.lstrip('/')}"
+
+    def _get(self, path: str, **kwargs: Any) -> requests.Response:
+        """Perform a GET request using the shared session."""
+        url = self._build_url(path)
+        return self._session.get(url, **kwargs)
+
+    def _post(self, path: str, **kwargs: Any) -> requests.Response:
+        """Perform a POST request using the shared session."""
+        url = self._build_url(path)
+        return self._session.post(url, **kwargs)
+
+    @staticmethod
+    def _is_success(status_code: int) -> bool:
+        """Check if an HTTP status code represents a successful response."""
+        return 200 <= status_code < 300
+
+    @staticmethod
+    def _authorization_header(token: str) -> Dict[str, str]:
+        """Create a bearer authorization header."""
+        return {"Authorization": f"Bearer {token}"}
+
+    @staticmethod
+    def _json_headers(token: str) -> Dict[str, str]:
+        """Create headers for JSON requests with bearer authorization."""
+        headers = SaamfiServiceBase._authorization_header(token)
+        headers["Content-Type"] = "application/json"
+        return headers
+

saamfi_sdk/services/institutions.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional
+
+from .base import SaamfiServiceBase
+
+logger = logging.getLogger(__name__)
+
+
+class InstitutionService(SaamfiServiceBase):
+    """Operations for retrieving institution metadata."""
+
+    def list_public_institutions(self) -> Optional[List[Dict[str, Any]]]:
+        """Retrieve the public list of institutions."""
+        try:
+            response = self._get("public/institutions", timeout=30)
+        except Exception as exc:
+            logger.warning("Error retrieving public institutions: %s", exc)
+            return None
+
+        if self._is_success(response.status_code):
+            try:
+                return response.json()
+            except Exception as exc:
+                logger.warning("Invalid response when listing public institutions: %s", exc)
+                return None
+
+        logger.warning(
+            "Failed to retrieve public institutions: status code %s", response.status_code
+        )
+        return None
+
+    def get_institution_by_nit(self, auth_token: str, nit: str) -> Optional[str]:
+        """Retrieve an institution by its NIT."""
+        headers = self._authorization_header(auth_token)
+        try:
+            response = self._get(f"public/institutions?nit={nit}", headers=headers, timeout=30)
+        except Exception as exc:
+            logger.warning("Error retrieving institution by NIT: %s", exc)
+            return None
+
+        if self._is_success(response.status_code):
+            logger.info("Retrieved institution by NIT '%s'", nit)
+            return response.text
+
+        logger.warning("Failed to retrieve institution by NIT '%s': %s", nit, response.status_code)
+        return None
+
+    def get_institutions_by_ids(self, auth_token: str, institution_ids: List[int]) -> Optional[str]:
+        """Retrieve multiple institutions by ID list."""
+        if not institution_ids:
+            logger.warning("No institution IDs provided")
+            return None
+
+        headers = self._authorization_header(auth_token)
+        params = {
+            "institutionIds": ",".join(str(institution_id) for institution_id in institution_ids)
+        }
+
+        try:
+            response = self._get(
+                "institutions",
+                headers=headers,
+                params=params,
+                timeout=30,
+            )
+        except Exception as exc:
+            logger.warning("Error retrieving institutions by IDs: %s", exc)
+            return None
+
+        if self._is_success(response.status_code):
+            logger.info("Retrieved institutions for IDs %s", institution_ids)
+            return response.text
+
+        logger.warning(
+            "Failed to retrieve institutions by IDs %s: %s",
+            institution_ids,
+            response.status_code,
+        )
+        return None
+
+    def get_institution_params(self, auth_token: str, institution_id: int) -> Optional[Dict[str, Any]]:
+        """Retrieve configuration parameters for a specific institution."""
+        headers = self._authorization_header(auth_token)
+        try:
+            response = self._get(
+                f"institutions/{institution_id}/params",
+                headers=headers,
+                timeout=30,
+            )
+        except Exception as exc:
+            logger.warning("Error retrieving params for institution %s: %s", institution_id, exc)
+            return None
+
+        if self._is_success(response.status_code):
+            try:
+                return response.json()
+            except Exception as exc:
+                logger.warning(
+                    "Invalid response while retrieving params for institution %s: %s",
+                    institution_id,
+                    exc,
+                )
+                return None
+
+        logger.warning(
+            "Failed to retrieve params for institution %s: %s",
+            institution_id,
+            response.status_code,
+        )
+        return None
+

saamfi_sdk/services/systems.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional
+
+from .base import SaamfiServiceBase
+
+logger = logging.getLogger(__name__)
+
+
+class SystemService(SaamfiServiceBase):
+    """Operations related to systems metadata and configuration."""
+
+    def list_public_systems(self) -> Optional[List[Dict[str, Any]]]:
+        """Retrieve public information about available systems."""
+        try:
+            response = self._get("public/systems", timeout=30)
+        except Exception as exc:
+            logger.warning("Error retrieving public systems: %s", exc)
+            return None
+
+        if self._is_success(response.status_code):
+            try:
+                return response.json()
+            except Exception as exc:
+                logger.warning("Invalid response when listing public systems: %s", exc)
+                return None
+
+        logger.warning("Failed to retrieve public systems: status code %s", response.status_code)
+        return None
+
+    def get_system_roles(self, auth_token: str, system_id: int) -> Optional[List[Dict[str, Any]]]:
+        """Retrieve roles for the given system."""
+        headers = self._authorization_header(auth_token)
+        try:
+            response = self._get(
+                f"systems/{system_id}/roles",
+                headers=headers,
+                timeout=30,
+            )
+        except Exception as exc:
+            logger.warning("Error retrieving roles for system %s: %s", system_id, exc)
+            return None
+
+        if self._is_success(response.status_code):
+            try:
+                return response.json()
+            except Exception as exc:
+                logger.warning(
+                    "Invalid response while retrieving roles for system %s: %s",
+                    system_id,
+                    exc,
+                )
+                return None
+
+        logger.warning(
+            "Failed to retrieve roles for system %s: %s",
+            system_id,
+            response.status_code,
+        )
+        return None
+

saamfi_sdk/services/token.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+import logging
+import base64
+from typing import List, Optional
+
+import jwt
+from cryptography.hazmat.backends import default_backend
+from cryptography.hazmat.primitives.asymmetric import rsa
+from cryptography.hazmat.primitives.serialization import load_der_public_key
+
+from saamfi_sdk.exceptions import SaamfiConnectionError, SaamfiTokenValidationError
+
+from .base import SaamfiServiceBase
+
+logger = logging.getLogger(__name__)
+
+
+class TokenService(SaamfiServiceBase):
+    """Handle public key retrieval and JWT token operations."""
+
+    ROLE_CLAIM = "role"
+    SYSTEM_CLAIM = "system"
+    USERNAME_CLAIM = "username"
+    ID_CLAIM = "persId"
+
+    def __init__(self, base_url: str, session):
+        super().__init__(base_url, session)
+        self._public_key_cache: Optional[bytes] = None
+
+    @property
+    def public_key_bytes(self) -> Optional[bytes]:
+        """Return cached public key bytes, if available."""
+        return self._public_key_cache
+
+    def fetch_public_key_bytes(self) -> bytes:
+        """Retrieve raw DER-encoded public key bytes from the Saamfi server."""
+        if self._public_key_cache is not None:
+            return self._public_key_cache
+
+        try:
+            response = self._get("public/publicKey", timeout=30)
+            response.raise_for_status()
+        except Exception as exc:
+            logger.error("Error retrieving public key: %s", exc)
+            raise SaamfiConnectionError(f"Error retrieving public key: {exc}") from exc
+
+        key_bytes: Optional[bytes] = None
+        payload = response.text.strip()
+
+        # Format 1: Legacy numeric list "[48, 130, ...]"
+        if payload.startswith("[") and payload.endswith("]"):
+            key_string = payload[1:-1]
+            byte_strings = key_string.split(",")
+
+            try:
+                byte_values = []
+                for item in byte_strings:
+                    stripped = item.strip()
+                    if not stripped:
+                        raise ValueError("Empty byte element in public key payload")
+                    value = int(stripped)
+                    if not -256 <= value <= 255:
+                        raise ValueError(f"Byte element out of range: {value}")
+                    byte_values.append(value & 0xFF)
+                key_bytes = bytes(byte_values)
+            except Exception as exc:
+                logger.error("Invalid public key payload: %s", payload)
+                raise SaamfiConnectionError(f"Error retrieving public key: {exc}") from exc
+
+        # Format 2: PEM with headers (-----BEGIN PUBLIC KEY-----)
+        if key_bytes is None and "BEGIN PUBLIC KEY" in payload:
+            try:
+                pem_lines = [
+                    line.strip()
+                    for line in payload.splitlines()
+                    if line and "BEGIN" not in line and "END" not in line
+                ]
+                key_bytes = base64.b64decode("".join(pem_lines), validate=True)
+            except Exception as exc:
+                logger.error("Invalid PEM-formatted public key payload")
+                raise SaamfiConnectionError(f"Error retrieving public key: {exc}") from exc
+
+        # Format 3: Plain base64 string
+        if key_bytes is None:
+            try:
+                key_bytes = base64.b64decode(payload, validate=True)
+            except Exception:
+                logger.error("Invalid public key payload: %s", payload[:64] + "...")
+                raise SaamfiConnectionError("Error retrieving public key: invalid payload format")
+
+        if not key_bytes:
+            logger.error("Public key payload is empty")
+            raise SaamfiConnectionError("Error retrieving public key: empty payload")
+
+        self._public_key_cache = key_bytes
+        logger.info("Public key successfully retrieved from Saamfi server")
+        return key_bytes
+
+    def get_rsa_public_key(self) -> rsa.RSAPublicKey:
+        """Return the RSA public key object used to validate JWT tokens."""
+        try:
+            key_bytes = self.fetch_public_key_bytes()
+            public_key = load_der_public_key(key_bytes, backend=default_backend())
+        except SaamfiConnectionError:
+            raise
+        except Exception as exc:
+            logger.error("Error getting public key: %s", exc)
+            raise SaamfiConnectionError(f"Error getting public key: {exc}") from exc
+
+        if not isinstance(public_key, rsa.RSAPublicKey):
+            raise SaamfiConnectionError("Retrieved key is not an RSA public key")
+        return public_key
+
+    def extract_roles(self, auth_token: str) -> List[str]:
+        """Extract roles from a JWT token."""
+        try:
+            decoded_token = jwt.decode(
+                auth_token,
+                self.get_rsa_public_key(),
+                algorithms=["RS256"],
+            )
+        except Exception as exc:
+            logger.warning("Error extracting roles from JWT: %s", exc)
+            return []
+
+        role_claim = decoded_token.get(self.ROLE_CLAIM, "")
+        if not role_claim:
+            return []
+        return [role.strip() for role in role_claim.split(",")]
+
+    def validate_token(self, auth_token: str) -> dict:
+        """Validate a JWT token and return decoded claims."""
+        try:
+            decoded_token = jwt.decode(
+                auth_token,
+                self.get_rsa_public_key(),
+                algorithms=["RS256"],
+            )
+        except jwt.ExpiredSignatureError as exc:
+            logger.error("Token has expired: %s", exc)
+            raise SaamfiTokenValidationError(f"Token has expired: {exc}") from exc
+        except jwt.InvalidTokenError as exc:
+            logger.error("Invalid token: %s", exc)
+            raise SaamfiTokenValidationError(f"Invalid token: {exc}") from exc
+        except Exception as exc:
+            logger.error("Error validating token: %s", exc)
+            raise SaamfiTokenValidationError(f"Error validating token: {exc}") from exc
+
+        return decoded_token
+
+    def reset_public_key_cache(self) -> None:
+        """Clear the cached public key. Intended for testing."""
+        self._public_key_cache = None
+

saamfi_sdk/services/users.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional
+
+from saamfi_sdk.exceptions import SaamfiAuthenticationError, SaamfiConnectionError
+from saamfi_sdk.models import UserInfo
+
+from .base import SaamfiServiceBase
+
+logger = logging.getLogger(__name__)
+
+
+class UserService(SaamfiServiceBase):
+    """Operations for querying user information."""
+
+    def get_user_info(self, auth_token: str, user_id: int) -> Optional[UserInfo]:
+        """Retrieve full user information by ID."""
+        headers = self._authorization_header(auth_token)
+        try:
+            response = self._get(f"users/{user_id}", headers=headers, timeout=30)
+        except Exception as exc:
+            logger.error("Error retrieving user info: %s", exc)
+            raise SaamfiConnectionError(f"Error retrieving user info: {exc}") from exc
+
+        if self._is_success(response.status_code):
+            try:
+                user = UserInfo(**response.json())
+            except Exception as exc:
+                logger.warning("Unexpected user info payload: %s", exc)
+                return None
+
+            logger.info("User info retrieved successfully for user ID %s", user_id)
+            return user
+
+        logger.warning("Failed to retrieve user info for ID %s: %s", user_id, response.status_code)
+        return None
+
+    def get_user_by_username(self, auth_token: str, username: str) -> Optional[Dict[str, Any]]:
+        """Retrieve a user by username."""
+        headers = self._json_headers(auth_token)
+        try:
+            response = self._post(
+                "users/user-from-username",
+                json=username,
+                headers=headers,
+                timeout=30,
+            )
+        except Exception as exc:
+            logger.error("Error searching user by username: %s", exc)
+            raise SaamfiConnectionError(f"Error searching user by username: {exc}") from exc
+
+        if response.status_code == 401:
+            logger.error("Authentication error when searching user by username")
+            raise SaamfiAuthenticationError("Error authenticating")
+
+        if response.status_code != 200:
+            logger.error(
+                "Error searching user by username '%s': %s", username, response.status_code
+            )
+            raise SaamfiConnectionError("Error")
+
+        try:
+            payload = response.json()
+        except ValueError:
+            logger.warning("Empty response when searching user by username '%s'", username)
+            return None
+
+        logger.info("User found by username '%s'", username)
+        return payload
+
+    def get_users_by_document(self, auth_token: str, user_documents: List[str]) -> List[Dict[str, Any]]:
+        """Retrieve users by document list."""
+        headers = self._json_headers(auth_token)
+        try:
+            response = self._post(
+                "users/users-from-document",
+                json=user_documents,
+                headers=headers,
+                timeout=30,
+            )
+        except Exception as exc:
+            logger.error("Error searching users by documents: %s", exc)
+            raise SaamfiConnectionError(f"Error searching users by documents: {exc}") from exc
+
+        if response.status_code == 401:
+            logger.error("Authentication error when searching users by documents")
+            raise SaamfiAuthenticationError("Error authenticating")
+
+        if response.status_code != 200:
+            logger.error(
+                "Error searching users by documents %s: %s",
+                user_documents,
+                response.status_code,
+            )
+            raise SaamfiConnectionError("Error")
+
+        users = response.json()
+        logger.info("Found %s users by documents", len(users))
+        return users
+
+    def get_users_from_list(self, auth_token: str, user_ids: List[int]) -> Optional[str]:
+        """Retrieve multiple users by ID list."""
+        headers = self._json_headers(auth_token)
+        try:
+            response = self._post(
+                "users/users-from-list",
+                json=user_ids,
+                headers=headers,
+                timeout=30,
+            )
+        except Exception as exc:
+            logger.warning("Error retrieving users from list: %s", exc)
+            return None
+
+        if self._is_success(response.status_code):
+            logger.info("Retrieved users from list of %s IDs", len(user_ids))
+            return response.text
+
+        logger.warning("Failed to retrieve users from list: %s", response.status_code)
+        return None
+
+    def get_users_by_param_and_value(self, auth_token: str, param: str, value: str) -> Optional[str]:
+        """Retrieve users using the generic param/value endpoint."""
+        headers = self._authorization_header(auth_token)
+        try:
+            response = self._get(
+                f"users?param={param}&value={value}",
+                headers=headers,
+                timeout=30,
+            )
+        except Exception as exc:
+            logger.warning("Error retrieving users by parameter: %s", exc)
+            return None
+
+        if self._is_success(response.status_code):
+            logger.info("Retrieved users by param '%s' and value '%s'", param, value)
+            return response.text
+
+        logger.warning(
+            "Failed to retrieve users by param '%s' and value '%s': %s",
+            param,
+            value,
+            response.status_code,
+        )
+        return None
+