saamfi-sdk 0.1.0__py3-none-any.whl

saamfi_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,257 @@
+Metadata-Version: 2.4
+Name: saamfi-sdk
+Version: 0.1.0
+Summary: SDK de Python para conectarse a los servicios SAAMFI - Autenticacion y Autorizacion
+Author-email: Universidad ICESI <dev@icesi.edu.co>
+License: MIT
+Project-URL: Homepage, https://github.com/icesi-dev/saamfi-sdk-python
+Project-URL: Documentation, https://saamfi-sdk-python.readthedocs.io
+Project-URL: Repository, https://github.com/icesi-dev/saamfi-sdk-python.git
+Project-URL: Issues, https://github.com/icesi-dev/saamfi-sdk-python/issues
+Keywords: saamfi,authentication,authorization,jwt,security,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Security
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Requires-Dist: PyJWT>=2.8.0
+Requires-Dist: cryptography>=41.0.0
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: mypy>=1.5.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.104.0; extra == "fastapi"
+Dynamic: license-file
+
+## Saamfi SDK para Python
+
+Cliente oficial en Python para integrar sistemas con los servicios de autenticacion y autorizacion de Saamfi. Este SDK expone las mismas operaciones disponibles en la libreria Java (`SaamfiDelegate`) y simplifica la validacion de tokens JWT, la autenticacion de usuarios y la consulta de informacion institucional.
+
+---
+
+## Instalacion
+
+- **Desde PyPI**
+  ```bash
+  pip install saamfi-sdk
+  ```
+- **Desde el codigo fuente**
+  ```bash
+  git clone https://github.com/saamfi/saamfi-sdk-python.git
+  cd saamfi-sdk-python
+  pip install -e .
+  ```
+
+Configura las siguientes variables de entorno antes de usar el cliente (por ejemplo en un archivo `.env`):
+
+- `SAAMFI_BASE_URL`: URL base del servicio Saamfi (`https://api.saamfi.com`).
+- `SAAMFI_SYS_ID`: Identificador del sistema o tenant asignado por Saamfi.
+- `SAAMFI_TENANT_ID` *(opcional)*: Identificador de institución (para endpoints como `/institutions/{instid}/params`).
+- `SAAMFI_CLIENT_ID` y `SAAMFI_CLIENT_SECRET` *(opcionales)*: Credenciales del sistema si tu integración las requiere.
+- `SAAMFI_TEST_USERNAME` y `SAAMFI_TEST_PASSWORD` *(solo para pruebas locales)*: Usuario demo del sandbox.
+
+> El cliente mantiene compatibilidad con las variables antiguas `SAAMFI_URL`, `SAAMFI_SYSTEM_ID` y `SAAMFI_INST_ID`.
+
+---
+
+## Quickstart
+
+```python
+from saamfi_sdk import SaamfiClient
+
+client = SaamfiClient()  # Usa SAAMFI_BASE_URL y SAAMFI_SYS_ID desde el entorno
+
+response = client.login("usuario@example.com", "clave-segura")
+if response:
+    print(f"Token: {response.access_token}")
+    token_info = client.validate_token(response.access_token)
+    print(f"Roles: {token_info.roles}")
+else:
+    print("Credenciales invalidas")
+```
+
+---
+
+## Sandbox local con docker compose
+
+1. Levanta el entorno local de Saamfi con `docker compose` (puerto `9091` según la configuración compartida).
+2. Crea un archivo `.env` junto al proyecto del SDK con las variables:
+   ```
+   SAAMFI_BASE_URL=http://localhost:9091/iaslab/saamfiapi
+   SAAMFI_SYS_ID=8
+   SAAMFI_CLIENT_ID=8
+   SAAMFI_CLIENT_SECRET=qYr6-CxZP9t4vN2eFM1sR4gL
+   SAAMFI_TENANT_ID=1
+   SAAMFI_TEST_USERNAME=testuser
+   SAAMFI_TEST_PASSWORD=password123
+   ```
+3. Ejecuta el script de ejemplo:
+   ```bash
+   python examples/sandbox_demo.py
+   ```
+   Verás el flujo completo: descarga de clave pública, descubrimiento de sistemas/instituciones, autenticación del usuario demo, validación del JWT y consultas protegidas.
+
+> Consulta los logs del backend en `saamfi-rest/logs/saamfi.log` o mediante `GET /logs/` (requiere rol `Query-server-logs`) para corroborar las operaciones.
+
+---
+
+## Ejemplos por funcionalidad
+
+Cada metodo del cliente refleja una operacion del servicio Saamfi. Los siguientes fragmentos muestran el flujo completo con un token valido (`token`):
+
+- **Obtener llave publica**
+  ```python
+  public_key = client.get_public_key()
+  ```
+
+- **Autenticar usuario**
+  ```python
+  login = client.login("usuario@example.com", "clave")
+  ```
+
+- **Validar token y extraer datos**
+  ```python
+  token_info = client.validate_token(token)
+  print(token_info.username, token_info.roles)
+  ```
+
+- **Roles desde un JWT**
+  ```python
+  roles = client.get_roles_from_jwt(token)
+  ```
+
+- **Informacion detallada de usuario**
+  ```python
+  user = client.get_user_info(token, user_id=12345)
+  ```
+
+- **Buscar usuario por username**
+  ```python
+  user = client.get_user_by_username(token, "john.doe")
+  ```
+
+- **Buscar usuarios por documentos**
+  ```python
+  users = client.get_users_by_document(token, ["100200300", "999888777"])
+  ```
+
+- **Obtener usuarios por lista de IDs**
+  ```python
+  users_json = client.get_users_from_list(token, [1, 2, 3])
+  ```
+
+- **Busqueda generica por parametro y valor**
+  ```python
+  result_json = client.get_users_by_param_and_value(token, "email", "example.com")
+  ```
+
+- **Consultar institucion por NIT**
+  ```python
+  institution_json = client.get_institution_by_nit(token, "900123456-7")
+  ```
+
+- **Consultar instituciones por IDs**
+  ```python
+  institutions_json = client.get_institutions_by_ids(token, [10, 20, 30])
+  ```
+
+- **Listado público de sistemas e instituciones**
+  ```python
+  systems = client.list_public_systems()
+  institutions = client.list_public_institutions()
+  ```
+
+- **Parámetros de institución**
+  ```python
+  params = client.get_institution_params(token)  # Usa SAAMFI_TENANT_ID por defecto
+  ```
+
+- **Roles configurados para un sistema**
+  ```python
+  roles = client.get_system_roles(token)  # Usa SAAMFI_SYS_ID por defecto
+  ```
+
+---
+
+## Referencia de API
+
+### Clases principales
+
+| Clase | Descripcion |
+| ----- | ----------- |
+| `SaamfiClient` | Cliente principal; gestiona autenticacion, validacion y consultas. |
+| `LoginBody` | Modelo para solicitudes de login. |
+| `LoginResponse` | Respuesta de autenticacion exitosa. |
+| `UserInfo` | Informacion detallada de usuario. |
+| `UserDetailToken` | Datos extraidos de un JWT validado. |
+
+### Metodos clave de `SaamfiClient`
+
+| Metodo | Entrada | Salida | Nota |
+| ------ | ------- | ------ | ---- |
+| `get_public_key()` | - | `RSAPublicKey` | Obtiene y cachea la llave publica. |
+| `login(username, password)` | `str`, `str` | `LoginResponse | None` | Autentica usuario. |
+| `get_roles_from_jwt(auth_token)` | `str` | `List[str]` | Extrae claim `role`. |
+| `validate_token(auth_token)` | `str` | `UserDetailToken` | Valida firma y claims. |
+| `get_user_info(auth_token, user_id)` | `str`, `int` | `UserInfo | None` | Consulta usuario por ID. |
+| `get_user_by_username(auth_token, username)` | `str`, `str` | `dict | None` | Consulta POST por username. |
+| `get_users_by_document(auth_token, user_documents)` | `str`, `List[str]` | `List[dict]` | Busca por multiples documentos. |
+| `get_users_from_list(auth_token, user_ids)` | `str`, `List[int]` | `str | None` | JSON con usuarios por ID. |
+| `get_users_by_param_and_value(auth_token, param, value)` | `str`, `str`, `str` | `str | None` | Filtro generico usando query string. |
+| `get_institution_by_nit(auth_token, nit)` | `str`, `str` | `str | None` | Consulta institucion por NIT. |
+| `get_institutions_by_ids(auth_token, institution_ids)` | `str`, `List[int]` | `str | None` | Consulta masiva por IDs. |
+| `list_public_institutions()` | - | `List[dict] | None` | Descubrimiento de instituciones disponibles. |
+| `get_institution_params(auth_token, institution_id=None)` | `str`, `Optional[int]` | `dict | None` | Obtiene parámetros de configuración institucional. |
+| `list_public_systems()` | - | `List[dict] | None` | Descubrimiento de sistemas publicados. |
+| `get_system_roles(auth_token, system_id=None)` | `str`, `Optional[int]` | `List[dict] | None` | Roles disponibles para un sistema. |
+
+> Consulta los docstrings en `saamfi_sdk/client.py` para conocer detalles, equivalencias con la version Java y ejemplos adicionales.
+
+---
+
+## Manejo de errores
+
+Todas las excepciones del SDK heredan de `SaamfiException`:
+
+| Excepcion | Cuándo ocurre |
+| --------- | ------------- |
+| `SaamfiAuthenticationError` | Credenciales invalidas o token sin permisos. |
+| `SaamfiTokenValidationError` | Token expirado, mal formado o con claims faltantes. |
+| `SaamfiConnectionError` | Problemas de red o respuestas no exitosas del backend. |
+| `SaamfiInvalidSystemError` | El token pertenece a otro `system_id`. |
+| `SaamfiUnauthorizedError` | El usuario autenticado no tiene permisos para la operacion. |
+| `SaamfiNotFoundError` | El recurso solicitado no existe. |
+
+```python
+from saamfi_sdk import SaamfiClient
+from saamfi_sdk.exceptions import SaamfiConnectionError, SaamfiAuthenticationError
+
+client = SaamfiClient()
+
+try:
+    login = client.login("usuario@example.com", "clave")
+except SaamfiConnectionError as exc:
+    print(f"No es posible comunicar con Saamfi: {exc}")
+except SaamfiAuthenticationError:
+    print("Credenciales invalidas")
+```
+
+---
+

saamfi_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+saamfi_sdk/__init__.py,sha256=rC1tAAgJYOJAO1j3kGENyzqrtnXZH4GwyFyT_k4hmQA,1284
+saamfi_sdk/client.py,sha256=Nwhv0giWBCyhs0GEeQUgbk6CuYe5yTn2sIt2562yPy8,11766
+saamfi_sdk/exceptions.py,sha256=iVKCHbNlNEjw9foY0TV5PQMY0vrGDJY3KTLDw7oaCEo,2253
+saamfi_sdk/models.py,sha256=shsY_Z-0Kp6Lle5TZr-PWZ4daZpbPVRwYkx2DyhJZiI,4602
+saamfi_sdk/py.typed,sha256=daEdpEyAJIa8b2VkCqSKcw8PaExcB6Qro80XNes_sHA,2
+saamfi_sdk/services/__init__.py,sha256=7xm0b5RLP6GNFXNj2bX7Yd16otGmffF9y_30B9jDZ6g,431
+saamfi_sdk/services/auth.py,sha256=OLjRZOXiCh9L0yBaDioQ54s1yeFouG3_sRtyzvxeuUY,3171
+saamfi_sdk/services/base.py,sha256=I4xqcOYup3unI5b9JnWbXHDE11vJfOhS8shw6zMFMA0,1555
+saamfi_sdk/services/institutions.py,sha256=RmnhzrUkiO5Xc2hQ8Zkljaj472LuA-Bn8gvxlQBR9oY,3980
+saamfi_sdk/services/systems.py,sha256=FD53D4b9smk_qzStyQsMJZfqUCaaSoyCUGLqPcxUd30,2053
+saamfi_sdk/services/token.py,sha256=xE1pIdYb6voxI1pSeCap7ZBfj9T1kdKOFTSNM8pcvgE,6139
+saamfi_sdk/services/users.py,sha256=bYWPcGOExtz0b4IZ3Ljuha2mX58j67ZmXkfznsY1QC4,5490
+saamfi_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=6iltbovbpbh9UIcMAQ4YaIe_XuhmiQHACLKGL5dXm70,1074
+saamfi_sdk-0.1.0.dist-info/METADATA,sha256=-E-RGqe8R1nf81p2QrZfGkPMN1-ibIxRVWEGNWti4nE,9653
+saamfi_sdk-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+saamfi_sdk-0.1.0.dist-info/top_level.txt,sha256=jF4kal_I5anaAgY1b4vS35XgME_BgJIPJK30WYndg9Q,11
+saamfi_sdk-0.1.0.dist-info/RECORD,,

saamfi_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

saamfi_sdk-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Universidad ICESI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

saamfi_sdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+saamfi_sdk