Metadata-Version: 2.4
Name: sahges-sdk
Version: 0.1.4
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.

