sahges-sdk 0.1.4

SDK Python officiel de l'écosystème SAHGES

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.

📋 Prérequis

• Python 3.10 ou supérieur
• pip pour l'installation des dépendances

🚀 Installation

pip install sahges-sdk

Ou depuis les sources :

git clone https://gitlab.com/florianogomez/sahges-sdk.git
cd sahges-sdk
pip install -e .

🎯 Getting Started (Démarrage rapide)

Installation et premier test

# 1. Installer le SDK
pip install sahges-sdk

# 2. Créer un fichier test.py

Exemple minimum : Authentification

# 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": "[e-mail]",
    "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

# 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)

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": "[e-mail]",
    "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 :

# 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

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 : [e-mail]
• 🌐 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

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": "[e-mail]",
    "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

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": "[e-mail]",
    "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

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": "[e-mail]"
})
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

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

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

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

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 :

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 :

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": "[e-mail]",
    "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

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 :

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": "[e-mail]",
        "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

pytest tests/ -v

Tests avec couverture

pytest --cov=src tests/
pytest --cov=src --cov-report=html tests/

Tests spécifiques

# 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 :

# 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 :

SAHGES_CLIENT_ID=test_client_id
SAHGES_CLIENT_SECRET=test_client_secret
SAHGES_TEST_EMAIL=[e-mail]
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

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 :

# 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é

# 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 pour plus de détails.

📧 Contact

SAHGES - [e-mail]

Lien du projet : https://gitlab.com/florianogomez/sahges-sdk

🔗 Liens utiles

• Documentation Auth complète - Guide détaillé du module Auth
• Documentation Docs complète - Guide détaillé du module Docs
• Documentation API Backend
• Support
• GitLab Repository

📚 Documentation des modules

Module Auth

Consultez 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 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

# 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": "[e-mail]",
    "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 :

# 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

from sahges_sdk.auth import SahgesAuthClient

client = SahgesAuthClient(client_id="xxx", client_secret="yyy")

# Connexion
login = client.login(payload={"credential": "[e-mail]", "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

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

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 à [e-mail] 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 ci-dessous.