sahges-sdk 0.1.1__tar.gz

sahges_sdk-0.1.1/PKG-INFO

@@ -0,0 +1,1103 @@
+Metadata-Version: 2.4
+Name: sahges-sdk
+Version: 0.1.1
+Summary: SDK Python officiel de l'écosystème SAHGES
+Author-email: SAHGES <floriano.gomez@bj.sanlamallianz.com>
+Project-URL: Source, https://gitlab.com/florianogomez/sahges-sdk.git
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Requires-Dist: marshmallow>=3.20
+Requires-Dist: python-dotenv>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-cov>=4.1; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+Requires-Dist: mypy>=1.5; extra == "dev"
+
+# SAHGES SDK
+
+SDK Python officiel pour l'écosystème SAHGES. Facilite l'intégration avec les services SAHGES via une interface Python simple et robuste.
+
+[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+## 📋 Prérequis
+
+- Python 3.10 ou supérieur
+- pip pour l'installation des dépendances
+
+## 🚀 Installation
+
+```bash
+pip install sahges-sdk
+```
+
+Ou depuis les sources :
+
+```bash
+git clone https://gitlab.com/florianogomez/sahges-sdk.git
+cd sahges-sdk
+pip install -e .
+```
+
+## 🎯 Getting Started (Démarrage rapide)
+
+### Installation et premier test
+
+```bash
+# 1. Installer le SDK
+pip install sahges-sdk
+
+# 2. Créer un fichier test.py
+```
+
+### Exemple minimum : Authentification
+
+```python
+# test.py
+from sahges_sdk.auth import SahgesAuthClient
+
+# Initialiser le client
+client = SahgesAuthClient(
+    client_id="votre_client_id",
+    client_secret="votre_client_secret"
+)
+
+# Se connecter
+response = client.login(payload={
+    "credential": "user@example.com",
+    "password": "mot_de_passe"
+})
+
+# Afficher le token
+print(f"Token d'accès: {response['access_token']}")
+print(f"Utilisateur: {response['user']['email']}")
+```
+
+### Exemple minimum : Gestion documentaire
+
+```python
+# test_docs.py
+from sahges_sdk.docs import SahgesDocsClient
+from pathlib import Path
+
+# Initialiser le client
+client = SahgesDocsClient(
+    client_id="votre_client_id",
+    client_secret="votre_client_secret"
+)
+
+# Uploader un document
+document = client.create(
+    title="Mon premier document",
+    file_path=Path("document.pdf"),
+    visibility="ORGANIZATION"
+)
+
+print(f"Document créé: {document['id']}")
+print(f"Fichier: {document['file_name']}")
+```
+
+### Utilisation combinée (Auth + Docs)
+
+```python
+from sahges_sdk.auth import SahgesAuthClient
+from sahges_sdk.docs import SahgesDocsClient
+
+# 1. S'authentifier
+auth = SahgesAuthClient(
+    client_id="votre_client_id",
+    client_secret="votre_client_secret"
+)
+
+login = auth.login(payload={
+    "credential": "user@example.com",
+    "password": "password"
+})
+
+print(f"Connecté: {login['user']['email']}")
+
+# 2. Gérer des documents
+docs = SahgesDocsClient(
+    client_id="votre_client_id",
+    client_secret="votre_client_secret"
+)
+
+# Lister les documents
+documents = docs.list(payload={})
+print(f"Nombre de documents: {len(documents)}")
+```
+
+## ⚙️ Configuration
+
+### Variables d'environnement
+
+Créez un fichier `.env` à la racine de votre projet :
+
+```env
+# Credentials API (obligatoire)
+SAHGES_CLIENT_ID=votre_client_id
+SAHGES_CLIENT_SECRET=votre_client_secret
+
+# URLs des services (optionnel, valeurs par défaut)
+SAHGES_AUTHENTICATION_BASE_URL=https://api.sahges.com
+SAHGES_DOCS_BASE_URL=https://docs.sahges.com
+
+# Configuration optionnelle
+SAHGES_TIMEOUT=30
+SAHGES_LOG_LEVEL=INFO
+```
+
+### Utilisation avec variables d'environnement
+
+```python
+import os
+from dotenv import load_dotenv
+from sahges_sdk.auth import SahgesAuthClient
+
+# Charger les variables d'environnement
+load_dotenv()
+
+# Utiliser les variables
+client = SahgesAuthClient(
+    client_id=os.getenv('SAHGES_CLIENT_ID'),
+    client_secret=os.getenv('SAHGES_CLIENT_SECRET')
+)
+
+response = client.login(payload={
+    "credential": os.getenv('SAHGES_USER_EMAIL'),
+    "password": os.getenv('SAHGES_USER_PASSWORD')
+})
+```
+
+### Obtenir des credentials
+
+Pour obtenir vos `client_id` et `client_secret`, contactez l'équipe SAHGES :
+- 📧 Email : floriano.gomez@bj.sanlamallianz.com
+- 🌐 Documentation : https://docs.sahges.com
+
+## 📖 Utilisation
+
+Le SDK SAHGES est organisé en deux modules principaux :
+- **Auth** : Authentification et gestion des utilisateurs
+- **Docs** : Gestion documentaire avec upload, partage et traitement IA
+
+### Module Auth - Authentification
+
+#### Connexion simple
+
+```python
+from sahges_sdk.auth import SahgesAuthClient
+
+# Initialiser le client
+client = SahgesAuthClient(
+    client_id="votre_client_id",
+    client_secret="votre_client_secret"
+)
+
+# Connexion
+response = client.login(payload={
+    "credential": "user@example.com",
+    "password": "votre_mot_de_passe"
+})
+
+print(f"Token: {response['access_token']}")
+print(f"Utilisateur: {response['user']['first_name']} {response['user']['last_name']}")
+print(f"Email: {response['user']['email']}")
+print(f"Organisation: {response['user']['organization']['name']}")
+```
+
+#### Cycle de vie complet d'une session
+
+```python
+from sahges_sdk.auth import SahgesAuthClient
+
+client = SahgesAuthClient(
+    client_id="votre_client_id",
+    client_secret="votre_client_secret"
+)
+
+# 1. Connexion
+login_response = client.login(payload={
+    "credential": "user@example.com",
+    "password": "mot_de_passe"
+})
+
+access_token = login_response["access_token"]
+refresh_token = login_response["refresh_token"]
+
+# 2. Introspection - Vérifier les infos utilisateur
+user_info = client.introspect(access_token=access_token)
+print(f"Rôle: {user_info['role']}")
+print(f"Actif: {user_info['is_active']}")
+
+# 3. Rafraîchir le token
+new_tokens = client.refresh(payload={
+    "refresh_token": refresh_token
+})
+access_token = new_tokens["access_token"]
+refresh_token = new_tokens["refresh_token"]
+
+# 4. Déconnexion
+client.logout(access_token=access_token)
+print("Déconnexion réussie")
+```
+
+#### Réinitialisation de mot de passe
+
+```python
+from sahges_sdk.auth import SahgesAuthClient
+
+client = SahgesAuthClient(
+    client_id="votre_client_id",
+    client_secret="votre_client_secret"
+)
+
+# 1. Demander la réinitialisation (envoie un email)
+response = client.forgot_password(payload={
+    "credential": "user@example.com"
+})
+print(response["message"])
+
+# 2. Valider le token reçu par email
+token = "token_recu_par_email"
+challenge = client.reset_password_challenge(token=token)
+
+if challenge["valid"]:
+    # 3. Réinitialiser le mot de passe
+    result = client.reset_password(payload={
+        "token": token,
+        "new_password": "nouveau_mot_de_passe_securise",
+        "new_password_confirmation": "nouveau_mot_de_passe_securise"
+    })
+    print(result["message"])
+```
+
+### Module Docs - Gestion documentaire
+
+#### Upload et création de documents
+
+```python
+from sahges_sdk.docs import SahgesDocsClient
+from pathlib import Path
+
+client = SahgesDocsClient(
+    client_id="votre_client_id",
+    client_secret="votre_client_secret"
+)
+
+# Créer un document avec upload
+document = client.create(
+    title="Rapport annuel 2025",
+    file_path=Path("/path/to/rapport.pdf"),
+    description="Rapport financier complet de l'année 2025",
+    visibility="ORGANIZATION",  # PRIVATE, ORGANIZATION, PUBLIC
+    status="DRAFT",              # DRAFT, PENDING, VALIDATED, ARCHIVED
+    category="finance",
+    tags=["rapport", "2025", "finance"]
+)
+
+print(f"Document créé: {document['id']}")
+print(f"Fichier: {document['file_name']} ({document['file_size']} bytes)")
+print(f"Format: {document['file_format']}")
+
+# Vérifier les résultats du traitement IA
+if document.get('ocr_text'):
+    print(f"Texte extrait (OCR): {document['ocr_text'][:100]}...")
+
+if document.get('ai_summary'):
+    print(f"Résumé IA: {document['ai_summary']}")
+
+if document.get('ai_metadata'):
+    print(f"Métadonnées IA: {document['ai_metadata']}")
+```
+
+#### Recherche et filtrage de documents
+
+```python
+from sahges_sdk.docs import SahgesDocsClient
+
+client = SahgesDocsClient(
+    client_id="votre_client_id",
+    client_secret="votre_client_secret"
+)
+
+# Liste de tous les documents
+all_docs = client.list(payload={})
+print(f"Total de documents: {len(all_docs)}")
+
+# Recherche avec filtres
+documents = client.list(payload={
+    "page": 1,
+    "search": "rapport",           # Recherche textuelle
+    "visibility": "ORGANIZATION",   # Filtre par visibilité
+    "status": "VALIDATED",          # Filtre par statut
+    "category": "finance"           # Filtre par catégorie
+})
+
+for doc in documents:
+    print(f"- {doc['title']} (créé le {doc['created_at']})")
+
+# Mes documents uniquement
+my_docs = client.list(payload={"owner_only": True})
+
+# Documents partagés avec moi
+shared_docs = client.list(payload={"shared_with_me": True})
+```
+
+#### Gestion complète d'un document
+
+```python
+from sahges_sdk.docs import SahgesDocsClient
+from pathlib import Path
+
+client = SahgesDocsClient(
+    client_id="votre_client_id",
+    client_secret="votre_client_secret"
+)
+
+# 1. Créer
+document = client.create(
+    title="Contrat client XYZ",
+    file_path=Path("contrat.pdf"),
+    visibility="PRIVATE",
+    status="DRAFT"
+)
+doc_id = document['id']
+
+# 2. Récupérer les détails
+doc_details = client.find(payload={"document_id": doc_id})
+print(f"Propriétaire: {doc_details['owner_auth_user_id']}")
+
+# 3. Mettre à jour
+updated_doc = client.update(payload={
+    "document_id": doc_id,
+    "title": "Contrat client XYZ - Version finale",
+    "status": "VALIDATED",
+    "tags": ["contrat", "2025", "client-xyz"]
+})
+
+# 4. Changer la visibilité
+doc = client.update_visibility(payload={
+    "document_id": doc_id,
+    "visibility": "ORGANIZATION"
+})
+
+# 5. Télécharger le fichier
+client.download(
+    document_id=doc_id,
+    output_path="/path/to/save/contrat_downloaded.pdf"
+)
+
+# Ou obtenir le contenu en bytes
+file_bytes = client.download(document_id=doc_id)
+# Traiter les bytes...
+
+# 6. Supprimer (optionnel)
+# client.delete(document_id=doc_id)
+```
+
+#### Partage de documents
+
+```python
+from sahges_sdk.docs import SahgesDocsClient
+from datetime import datetime, timedelta
+
+client = SahgesDocsClient(
+    client_id="votre_client_id",
+    client_secret="votre_client_secret"
+)
+
+doc_id = "550e8400-e29b-41d4-a716-446655440000"
+
+# 1. Partager avec un utilisateur
+share = client.share_create(payload={
+    "document_id": doc_id,
+    "shared_with_auth_user_id": "user-uuid-ici",
+    "permission": "VIEW",  # VIEW, EDIT, ou MANAGE
+    "expires_at": datetime.now() + timedelta(days=30)
+})
+
+print(f"Document partagé avec ID: {share['id']}")
+print(f"Permission: {share['permission']}")
+print(f"Expire le: {share['expires_at']}")
+
+# 2. Lister tous les partages
+shares = client.share_list(payload={"document_id": doc_id})
+
+for s in shares:
+    print(f"Partagé avec: {s['shared_with_auth_user_id']}")
+    print(f"Permission: {s['permission']}")
+    print(f"Par: {s['shared_by_auth_user_id']}")
+
+# 3. Révoquer un partage
+if shares:
+    client.share_delete(payload={
+        "document_id": doc_id,
+        "share_id": shares[0]['id']
+    })
+    print("Partage révoqué")
+```
+
+#### Endpoints clients (accès restreint)
+
+Les endpoints clients sont pour les applications tierces avec permissions limitées :
+
+```python
+from sahges_sdk.docs import SahgesDocsClient
+
+client = SahgesDocsClient(
+    client_id="client_id_tiers",
+    client_secret="client_secret_tiers"
+)
+
+# Liste des documents accessibles (ORGANIZATION + PUBLIC)
+documents = client.clients_list(payload={
+    "page": 1,
+    "search": "facture",
+    "category": "comptabilite"
+})
+
+# Créer un document (visibilité forcée à ORGANIZATION)
+doc = client.clients_create(
+    title="Facture janvier 2025",
+    file_path="facture_janvier.pdf",
+    description="Facture du mois de janvier",
+    status="VALIDATED",
+    category="comptabilite"
+)
+
+# Récupérer un document
+document = client.clients_find(payload={
+    "document_id": doc['id']
+})
+
+# Télécharger
+client.clients_download(
+    document_id=doc['id'],
+    output_path="facture_downloaded.pdf"
+)
+```
+
+### Workflow complet : Auth + Docs
+
+Exemple d'utilisation combinée des deux modules :
+
+```python
+from sahges_sdk.auth import SahgesAuthClient
+from sahges_sdk.docs import SahgesDocsClient
+from pathlib import Path
+
+# 1. Authentification
+auth_client = SahgesAuthClient(
+    client_id="votre_client_id",
+    client_secret="votre_client_secret"
+)
+
+login_response = auth_client.login(payload={
+    "credential": "user@example.com",
+    "password": "mot_de_passe"
+})
+
+access_token = login_response["access_token"]
+user = login_response["user"]
+
+print(f"Connecté en tant que {user['first_name']} {user['last_name']}")
+print(f"Organisation: {user['organization']['name']}")
+
+# 2. Gestion documentaire
+docs_client = SahgesDocsClient(
+    client_id="votre_client_id",
+    client_secret="votre_client_secret"
+)
+
+# Créer un document
+document = docs_client.create(
+    title="Mon document",
+    file_path=Path("document.pdf"),
+    visibility="ORGANIZATION",
+    status="DRAFT"
+)
+
+print(f"Document créé: {document['id']}")
+
+# Lister mes documents
+my_docs = docs_client.list(payload={"owner_only": True})
+print(f"Vous avez {len(my_docs)} document(s)")
+
+# Partager avec un collègue
+if user.get('colleague_id'):
+    share = docs_client.share_create(payload={
+        "document_id": document['id'],
+        "shared_with_auth_user_id": user['colleague_id'],
+        "permission": "EDIT"
+    })
+    print(f"Document partagé avec permission {share['permission']}")
+
+# 3. Déconnexion
+auth_client.logout(access_token=access_token)
+print("Session terminée")
+```
+
+### Utilisation avec variables d'environnement
+
+```python
+import os
+from dotenv import load_dotenv
+from sahges_sdk.auth import SahgesAuthClient
+from sahges_sdk.docs import SahgesDocsClient
+
+load_dotenv()
+
+# Initialisation simplifiée
+auth_client = SahgesAuthClient(
+    client_id=os.getenv('SAHGES_CLIENT_ID'),
+    client_secret=os.getenv('SAHGES_CLIENT_SECRET')
+)
+
+docs_client = SahgesDocsClient(
+    client_id=os.getenv('SAHGES_CLIENT_ID'),
+    client_secret=os.getenv('SAHGES_CLIENT_SECRET')
+)
+
+# Utilisation...
+response = auth_client.login(payload={
+    "credential": os.getenv('SAHGES_USER_EMAIL'),
+    "password": os.getenv('SAHGES_USER_PASSWORD')
+})
+```
+
+## 🏗️ Architecture
+
+```
+src/
+├── auth/              # Module d'authentification
+│   ├── auth_client.py # Client SAHGES Auth
+│   ├── routes.py      # Routes API d'authentification
+│   ├── login/         # Connexion et refresh token
+│   ├── logout/        # Déconnexion
+│   ├── introspect/    # Informations utilisateur
+│   ├── reset_password/# Réinitialisation de mot de passe
+│   └── schemas/       # Schémas de validation (user, organization)
+├── docs/              # Module de gestion documentaire
+│   ├── docs_client.py # Client SAHGES Docs
+│   ├── routes.py      # Routes API des documents
+│   ├── enums.py       # Énumérations (visibilité, statut, permissions)
+│   ├── documents/     # CRUD documents avec filtres
+│   ├── shares/        # Gestion des partages
+│   ├── clients/       # Endpoints clients (accès restreint)
+│   └── schemas/       # Schémas de validation (document, share)
+├── base/              # Classes de base
+│   ├── client.py      # Client HTTP de base
+│   ├── endpoint.py    # Définition des endpoints
+│   ├── decorators.py  # Décorateurs de validation
+│   ├── enums.py       # Énumérations globales
+│   ├── error.py       # Exceptions personnalisées
+│   └── logger.py      # Configuration du logging
+├── config/            # Configuration centralisée
+├── plugins/           # Extensions
+│   └── marshmallow/   # Champs de validation personnalisés
+└── utils/             # Utilitaires
+    └── validators.py  # Validateurs
+```
+
+## 🎯 Fonctionnalités principales
+
+### Module Auth
+
+- ✅ **Connexion (login)** : Authentification avec email/identifiant et mot de passe
+- ✅ **Rafraîchissement (refresh)** : Renouvellement des tokens sans reconnexion
+- ✅ **Introspection** : Récupération des informations utilisateur et organisation
+- ✅ **Déconnexion (logout)** : Invalidation sécurisée des tokens
+- ✅ **Mot de passe oublié** : Demande de réinitialisation par email
+- ✅ **Validation de token** : Vérification du token de réinitialisation
+- ✅ **Réinitialisation** : Changement de mot de passe avec token
+
+### Module Docs
+
+- 📄 **Upload de documents** : Création avec fichier (tous formats)
+- 🔍 **Recherche avancée** : Filtres par titre, catégorie, statut, visibilité
+- 📝 **CRUD complet** : Création, lecture, mise à jour, suppression
+- 👁️ **Visibilité granulaire** : PRIVATE, ORGANIZATION, PUBLIC
+- 🤝 **Partage** : Permissions VIEW, EDIT, MANAGE avec expiration
+- 🤖 **Traitement IA** : OCR, transcription audio, résumés, métadonnées
+- 🖼️ **Prévisualisation** : Génération automatique de miniatures
+- 🔐 **Hash SHA-256** : Intégrité et détection de doublons
+- 📊 **Métadonnées** : Extraction automatique (taille, format, MIME type)
+- 🔗 **Liens publics** : Partage avec token pour documents PUBLIC
+- 📁 **Catégorisation** : Organisation par catégories et tags
+- 🎫 **Statuts** : Workflow DRAFT → PENDING → VALIDATED → ARCHIVED
+
+## 🔒 Gestion des erreurs
+
+Le SDK fournit des exceptions spécifiques pour une meilleure gestion des erreurs :
+
+```python
+from base.error import (
+    SahgesError,                    # Erreur de base
+    SahgesClientConfigError,        # Erreur de configuration
+    SahgesRequestError,             # Erreur de requête HTTP
+    SahgesAuthenticationError,      # Erreur d'authentification
+    SahgesValidationError           # Erreur de validation de données
+)
+
+# Exemple de gestion complète
+try:
+    response = client.login(payload={
+        "credential": "user@example.com",
+        "password": "mot_de_passe"
+    })
+    
+except SahgesAuthenticationError as e:
+    print(f"Échec de l'authentification: {e}")
+    print(f"Status HTTP: {e.status_code}")
+    print(f"Données de réponse: {e.response_data}")
+    
+except SahgesValidationError as e:
+    print(f"Erreur de validation: {e}")
+    # Les données fournies ne sont pas valides
+    
+except SahgesRequestError as e:
+    print(f"Erreur réseau ou serveur: {e}")
+    print(f"Status: {e.status_code}")
+    
+except SahgesClientConfigError as e:
+    print(f"Erreur de configuration du client: {e}")
+    # client_id ou client_secret manquant/invalide
+    
+except SahgesError as e:
+    print(f"Erreur SAHGES générale: {e}")
+
+# Pour les documents
+try:
+    document = client.create(
+        title="Document",
+        file_path="inexistant.pdf"
+    )
+except FileNotFoundError as e:
+    print(f"Fichier introuvable: {e}")
+```
+
+### Codes d'erreur HTTP communs
+
+- **400 Bad Request** : Données invalides → `SahgesValidationError`
+- **401 Unauthorized** : Authentification échouée → `SahgesAuthenticationError`
+- **403 Forbidden** : Permissions insuffisantes → `SahgesAuthenticationError`
+- **404 Not Found** : Ressource introuvable → `SahgesRequestError`
+- **429 Too Many Requests** : Rate limit dépassé → `SahgesRequestError`
+- **500 Server Error** : Erreur serveur → `SahgesRequestError`
+
+## 🧪 Tests
+
+Le SDK comprend une suite complète de tests unitaires et d'intégration.
+
+### Exécuter tous les tests
+
+```bash
+pytest tests/ -v
+```
+
+### Tests avec couverture
+
+```bash
+pytest --cov=src tests/
+pytest --cov=src --cov-report=html tests/
+```
+
+### Tests spécifiques
+
+```bash
+# Tests du module Auth
+pytest tests/test_auth_login.py -v
+pytest tests/test_auth_complete.py -v
+
+# Tests du module Docs
+pytest tests/test_docs_complete.py -v
+
+# Tests de configuration
+pytest tests/test_config.py -v
+
+# Tests des décorateurs
+pytest tests/test_decorators.py -v
+
+# Tests des erreurs
+pytest tests/test_errors.py -v
+```
+
+### Tests manuels
+
+Des scripts de tests manuels sont disponibles pour tester en conditions réelles :
+
+```bash
+# Test manuel de connexion
+python tests/test_manual_login.py
+
+# Test manuel de documents
+python tests/test_manual_docs.py
+```
+
+### Configuration pour les tests
+
+Créez un fichier `.env.test` :
+
+```env
+SAHGES_CLIENT_ID=test_client_id
+SAHGES_CLIENT_SECRET=test_client_secret
+SAHGES_TEST_EMAIL=test@example.com
+SAHGES_TEST_PASSWORD=test_password
+SAHGES_AUTHENTICATION_BASE_URL=https://api-test.sahges.com
+SAHGES_DOCS_BASE_URL=https://docs-test.sahges.com
+```
+
+## 📝 Développement
+
+### Installation pour le développement
+
+```bash
+git clone https://gitlab.com/florianogomez/sahges-sdk.git
+cd sahges-sdk
+pip install -e ".[dev]"
+```
+
+### Structure du projet
+
+```
+sahges-sdk/
+├── src/                    # Code source
+│   ├── auth/              # Module Auth
+│   ├── docs/              # Module Docs
+│   ├── base/              # Classes de base
+│   ├── config/            # Configuration
+│   ├── plugins/           # Extensions
+│   └── utils/             # Utilitaires
+├── tests/                 # Tests unitaires et d'intégration
+│   ├── conftest.py       # Configuration pytest
+│   ├── test_auth_*.py    # Tests Auth
+│   ├── test_docs_*.py    # Tests Docs
+│   └── test_*.py         # Tests divers
+├── context/               # Documentation de contexte (backend)
+├── pyproject.toml        # Configuration du projet
+├── pytest.ini            # Configuration pytest
+├── .env.example          # Exemple de configuration
+└── readme.md             # Ce fichier
+```
+
+### Scripts utiles
+
+Le fichier `manage.sh` fournit des commandes pratiques :
+
+```bash
+# Lancer les tests
+./manage.sh test
+
+# Vérifier le formatage
+./manage.sh lint
+
+# Générer la documentation
+./manage.sh docs
+```
+
+### Conventions de code
+
+- **Python 3.10+** : Utilisez les fonctionnalités modernes (type hints, match/case)
+- **Type hints** : Annotations de type obligatoires
+- **Docstrings** : Documentation Google style pour toutes les fonctions publiques
+- **Validation** : Marshmallow pour tous les schémas
+- **Logging** : Utilisez le logger configuré (`base.logger`)
+- **Erreurs** : Levez des exceptions spécifiques (`SahgesAuthenticationError`, etc.)
+
+### Ajouter une nouvelle fonctionnalité
+
+#### Pour le module Auth
+
+1. Créez la fonction dans le dossier approprié (`login/`, `logout/`, etc.)
+2. Définissez les schémas de validation (request/response)
+3. Ajoutez la route dans `routes.py`
+4. Attachez la méthode au client dans `auth_client.py`
+5. Écrivez les tests dans `tests/`
+
+#### Pour le module Docs
+
+1. Créez la fonction dans le dossier approprié (`documents/`, `shares/`, etc.)
+2. Définissez les schémas si nécessaire
+3. Ajoutez la route dans `routes.py`
+4. Attachez la méthode au client dans `docs_client.py`
+5. Écrivez les tests dans `tests/`
+
+### Exemple d'ajout de fonctionnalité
+
+```python
+# 1. Créer la fonction (src/auth/new_feature/feature.py)
+from base.decorators import sahges_endpoint
+from auth.routes import SahgesAuthenticationRoutes
+
+@sahges_endpoint(
+    request_schema=FeatureRequestSchema,
+    response_schema=FeatureResponseSchema
+)
+def sahges_auth_new_feature(self, payload: dict):
+    """Description de la nouvelle fonctionnalité."""
+    endpoint = SahgesAuthenticationRoutes.new_feature.value
+    response = self.request(
+        method=endpoint.method,
+        path=endpoint.path,
+        json=payload
+    )
+    return response
+
+# 2. Ajouter la route (src/auth/routes.py)
+class SahgesAuthenticationRoutes(Enum):
+    # ... routes existantes ...
+    new_feature = Endpoint(
+        path=f"/{BASE}/new-feature",
+        method=HTTPMethod.POST
+    )
+
+# 3. Attacher au client (src/auth/auth_client.py)
+class SahgesAuthClient(BaseSahgesApiClient):
+    def __init__(self, client_id, client_secret):
+        # ... init existant ...
+        from auth.new_feature.feature import sahges_auth_new_feature
+        self.new_feature = MethodType(sahges_auth_new_feature, self)
+```
+
+## 🤝 Contribution
+
+Les contributions sont les bienvenues ! Veuillez suivre ces étapes :
+
+1. Fork le projet
+2. Créez une branche pour votre fonctionnalité (`git checkout -b feature/AmazingFeature`)
+3. Committez vos changements (`git commit -m 'Add some AmazingFeature'`)
+4. Pushez vers la branche (`git push origin feature/AmazingFeature`)
+5. Ouvrez une Pull Request
+
+## 📄 Licence
+
+Ce projet est sous licence MIT. Voir le fichier [LICENSE](LICENSE) pour plus de détails.
+
+## 📧 Contact
+
+SAHGES - floriano.gomez@bj.sanlamallianz.com
+
+Lien du projet : [https://gitlab.com/florianogomez/sahges-sdk](https://gitlab.com/florianogomez/sahges-sdk)
+
+## 🔗 Liens utiles
+
+- [Documentation Auth complète](src/auth/readme.md) - Guide détaillé du module Auth
+- [Documentation Docs complète](src/docs/readme.md) - Guide détaillé du module Docs
+- [Documentation API Backend](https://api.sahges.com/docs)
+- [Support](https://support.sahges.com)
+- [GitLab Repository](https://gitlab.com/florianogomez/sahges-sdk)
+
+## 📚 Documentation des modules
+
+### Module Auth
+
+Consultez [src/auth/readme.md](src/auth/readme.md) pour :
+- Architecture détaillée du module Auth
+- Description complète de chaque fonctionnalité (login, refresh, introspect, logout, reset password)
+- Schémas de validation (AuthUserSchema, AuthOrganizationSchema)
+- Exemples avancés
+- Gestion des tokens JWT et refresh tokens
+- Sécurité et bonnes pratiques
+
+### Module Docs
+
+Consultez [src/docs/readme.md](src/docs/readme.md) pour :
+- Architecture détaillée du module Docs
+- CRUD complet des documents avec upload
+- Système de partage et permissions
+- Filtres et recherche avancée
+- Traitement IA (OCR, transcription, résumés)
+- Énumérations (visibilité, statut, permissions, formats)
+- Schéma DocumentSchema complet
+- Endpoints clients vs endpoints normaux
+- Exemples d'utilisation avancés
+
+## ⚡ Quick Start
+
+### Installation rapide
+
+```bash
+# Installer le SDK
+pip install sahges-sdk
+
+# Créer un fichier de test
+cat > test_sahges.py << 'EOF'
+from sahges_sdk.auth import SahgesAuthClient
+
+client = SahgesAuthClient(
+    client_id="votre_client_id",
+    client_secret="votre_client_secret"
+)
+
+response = client.login(payload={
+    "credential": "user@example.com",
+    "password": "password"
+})
+
+print(f"✅ Connecté: {response['user']['email']}")
+print(f"🔑 Token: {response['access_token'][:20]}...")
+EOF
+
+# Tester
+python test_sahges.py
+```
+
+### Modules disponibles
+
+Le SDK expose deux modules principaux :
+
+```python
+# Module d'authentification
+from sahges_sdk.auth import SahgesAuthClient
+
+# Module de gestion documentaire
+from sahges_sdk.docs import SahgesDocsClient
+
+# Schémas de validation (si besoin)
+from sahges_sdk.auth.schemas import AuthUserSchema
+from sahges_sdk.docs.schemas import DocumentSchema
+
+# Énumérations (si besoin)
+from sahges_sdk.docs.enums import (
+    DocumentVisibilityEnum,
+    DocumentStatusEnum,
+    DocumentSharePermissionEnum
+)
+```
+
+## 💡 Exemples d'utilisation courants
+
+### Authentification et gestion de session
+
+```python
+from sahges_sdk.auth import SahgesAuthClient
+
+client = SahgesAuthClient(client_id="xxx", client_secret="yyy")
+
+# Connexion
+login = client.login(payload={"credential": "user@example.com", "password": "pass"})
+token = login["access_token"]
+
+# Vérifier l'utilisateur
+user = client.introspect(access_token=token)
+print(f"Connecté: {user['email']}")
+
+# Rafraîchir la session
+new_tokens = client.refresh(payload={"refresh_token": login["refresh_token"]})
+```
+
+### Upload et partage de document
+
+```python
+from sahges_sdk.docs import SahgesDocsClient
+from datetime import datetime, timedelta
+
+client = SahgesDocsClient(client_id="xxx", client_secret="yyy")
+
+# Upload
+doc = client.create(
+    title="Contrat client",
+    file_path="contrat.pdf",
+    visibility="ORGANIZATION",
+    tags=["contrat", "2025"]
+)
+
+# Partager avec expiration
+share = client.share_create(payload={
+    "document_id": doc['id'],
+    "shared_with_auth_user_id": "colleague-uuid",
+    "permission": "VIEW",
+    "expires_at": datetime.now() + timedelta(days=7)
+})
+```
+
+### Recherche et téléchargement
+
+```python
+from sahges_sdk.docs import SahgesDocsClient
+
+client = SahgesDocsClient(client_id="xxx", client_secret="yyy")
+
+# Recherche
+docs = client.list(payload={
+    "search": "contrat",
+    "status": "VALIDATED",
+    "category": "legal"
+})
+
+# Télécharger le premier résultat
+if docs:
+    client.download(
+        document_id=docs[0]['id'],
+        output_path="contrat_downloaded.pdf"
+    )
+```
+
+## 🛡️ Sécurité
+
+- **Tokens JWT** : Authentification stateless sécurisée
+- **Refresh tokens** : Renouvellement sans redemander le mot de passe
+- **HTTPS obligatoire** : Toutes les communications sont chiffrées
+- **Hash SHA-256** : Intégrité des fichiers garantie
+- **Validation stricte** : Tous les inputs sont validés (Marshmallow)
+- **Credentials** : Ne jamais logger ou commiter les secrets
+- **Rate limiting** : Protection contre les abus
+- **Permissions granulaires** : Contrôle d'accès fin (PRIVATE/ORGANIZATION/PUBLIC)
+
+## 🚦 Statuts et visibilité
+
+### Statuts des documents (DocumentStatusEnum)
+
+- **DRAFT** : Brouillon, en cours de rédaction
+- **PENDING** : En attente de validation
+- **VALIDATED** : Validé et approuvé
+- **ARCHIVED** : Archivé (inactif)
+
+### Visibilité (DocumentVisibilityEnum)
+
+- **PRIVATE** : Visible uniquement par le propriétaire
+- **ORGANIZATION** : Visible par tous les membres de l'organisation
+- **PUBLIC** : Accessible publiquement via token
+
+### Permissions de partage (DocumentSharePermissionEnum)
+
+- **VIEW** : Lecture seule
+- **EDIT** : Lecture et modification
+- **MANAGE** : Lecture, modification et gestion des partages
+
+## ❓ FAQ
+
+### Comment obtenir des credentials API ?
+
+Contactez l'équipe SAHGES à floriano.gomez@bj.sanlamallianz.com pour obtenir vos `client_id` et `client_secret`.
+
+### Quelle est la durée de vie des tokens ?
+
+- **Access token** : 15 minutes (configurable)
+- **Refresh token** : 7 jours (configurable)
+
+### Quels formats de fichiers sont supportés ?
+
+Tous les formats sont acceptés. Traitement spécial pour :
+- PDF : OCR et extraction de texte
+- Images : OCR et analyse IA
+- Audio/Vidéo : Transcription automatique
+- Office : Conversion et prévisualisation
+
+### Comment gérer les fichiers volumineux ?
+
+Le système gère automatiquement les uploads en streaming. Vérifiez les limites de taille avec votre administrateur.
+
+### Puis-je utiliser le SDK en production ?
+
+Oui, le SDK est conçu pour la production avec gestion d'erreurs robuste, logging, et retry automatique.
+
+### Comment contribuer ?
+
+Voir la section [Contribution](#🤝-contribution) ci-dessous.
+