@sinoia/hubdoc-tools 1.0.4 → 1.2.1

package/docs/connectors/aws-s3.md

@@ -1,187 +0,0 @@
-# AWS S3 Connector
-
-Plugin pour importer/exporter des documents depuis/vers Amazon S3 et services compatibles.
-
-## Configuration
-
-### Paramètres requis
-- `accessKeyId` : AWS Access Key ID
-- `secretAccessKey` : AWS Secret Access Key  
-- `region` : Région AWS (ex: us-east-1, eu-west-1)
-- `bucketName` : Nom du bucket S3
-
-### Paramètres optionnels
-- `prefix` : Préfixe des clés S3 pour filtrer les objets
-- `endpoint` : URL personnalisée pour services S3-compatibles
-- `limit` : Nombre maximum de documents à scanner
-
-## Configuration AWS
-
-### Option 1: Utilisateur IAM (Recommandé)
-1. Créer un utilisateur IAM dans la [Console AWS](https://console.aws.amazon.com/iam/)
-2. Attacher une politique avec les permissions S3 nécessaires
-3. Générer une Access Key et Secret Key
-4. Noter la région de votre bucket S3
-
-### Exemple de politique IAM minimale
-```json
-{
-    "Version": "2012-10-17",
-    "Statement": [
-        {
-            "Effect": "Allow",
-            "Action": [
-                "s3:GetObject",
-                "s3:ListBucket"
-            ],
-            "Resource": [
-                "arn:aws:s3:::your-bucket-name",
-                "arn:aws:s3:::your-bucket-name/*"
-            ]
-        }
-    ]
-}
-```
-
-### Pour l'export, ajouter les permissions d'écriture :
-```json
-{
-    "Action": [
-        "s3:GetObject",
-        "s3:ListBucket", 
-        "s3:PutObject",
-        "s3:DeleteObject"
-    ]
-}
-```
-
-### Option 2: Rôle IAM (Pour EC2)
-Si vous exécutez sur EC2, vous pouvez utiliser un rôle IAM attaché à l'instance.
-
-## Services S3-compatibles
-
-Le connecteur supporte aussi les services compatibles S3 :
-
-### MinIO
-```json
-{
-  "accessKeyId": "minio_access_key",
-  "secretAccessKey": "minio_secret_key", 
-  "region": "us-east-1",
-  "bucketName": "documents",
-  "endpoint": "http://localhost:9000"
-}
-```
-
-### DigitalOcean Spaces
-```json
-{
-  "accessKeyId": "do_spaces_key",
-  "secretAccessKey": "do_spaces_secret",
-  "region": "nyc3", 
-  "bucketName": "my-space",
-  "endpoint": "https://nyc3.digitaloceanspaces.com"
-}
-```
-
-## Utilisation
-
-```bash
-# Mode interactif
-hubdoc-tool --engine s3
-
-# Avec limite de documents
-hubdoc-tool --engine s3 --limit 100
-```
-
-## Fichier de configuration
-
-Créer `s3-config.json` :
-
-```json
-{
-  "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
-  "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
-  "region": "eu-west-1",
-  "bucketName": "my-documents",
-  "prefix": "documents/",
-  "limit": 1000
-}
-```
-
-## Fonctionnalités supportées
-
-### Scan (✅)
-- Parcours de tous les objets dans le bucket
-- Support des préfixes pour filtrer
-- Métadonnées S3 (tags, storage class, ETag)
-- Filtrage par taille, date, type MIME
-
-### Import (✅)
-- Téléchargement avec streaming
-- Support des gros fichiers
-- Préservation de la structure de "dossiers" (préfixes S3)
-- Téléchargement par lots avec contrôle de débit
-
-### Export (✅)
-- Upload multipart automatique pour gros fichiers
-- Création de structure de préfixes
-- Métadonnées personnalisées
-- Détection automatique du Content-Type
-
-## Gestion des "dossiers"
-
-S3 n'a pas de vraie notion de dossiers, mais utilise des préfixes :
-- `documents/2023/invoice.pdf` 
-- `documents/2023/reports/monthly.xlsx`
-
-Le connecteur simule une structure de dossiers en utilisant `/` comme séparateur.
-
-## Limitations
-
-- Taille maximale par objet : 5TB
-- Pas de limite sur le nombre d'objets
-- Les métadonnées S3 sont limitées à 2KB par objet
-- Le listing d'objets est paginé (1000 objets max par requête)
-
-## Performances
-
-- **Upload** : Multipart automatique pour fichiers > 5MB
-- **Download** : Streaming pour économiser la mémoire  
-- **Listing** : Pagination automatique
-- **Parallélisme** : Configurable via `batchSize`
-
-## Troubleshooting
-
-### Erreur d'accès 403
-- Vérifier les permissions IAM
-- Vérifier que le bucket existe et est accessible
-- Vérifier la région configurée
-
-### Erreur de credentials
-- Vérifier `accessKeyId` et `secretAccessKey`
-- S'assurer que les credentials ne sont pas expirés
-- Pour les rôles IAM, vérifier que l'instance EC2 a le bon rôle
-
-### Problèmes de réseau
-- Vérifier la connectivité internet
-- Pour les VPC, vérifier les routes et security groups
-- Considérer utiliser un VPC Endpoint S3 pour rester en réseau privé
-
-## Bonnes pratiques
-
-### Sécurité
-- Utiliser des rôles IAM plutôt que des access keys quand possible
-- Appliquer le principe du moindre privilège
-- Chiffrer les objets sensibles avec SSE-S3 ou SSE-KMS
-- Activer les logs d'accès S3
-
-### Performance  
-- Utiliser des préfixes distribués pour éviter les hot spots
-- Configurer des règles de cycle de vie pour les anciens objets
-- Utiliser S3 Transfer Acceleration pour les uploads depuis l'international
-
-### Coûts
-- Choisir la classe de stockage appropriée (Standard, IA, Glacier)
-- Utiliser des règles de cycle de vie pour archiver automatiquement
-- Surveiller les coûts de requêtes (GET, PUT, LIST)

package/docs/connectors/azure-blob.md

@@ -1,195 +0,0 @@
-# Azure Blob Storage Connector
-
-Plugin pour importer/exporter des documents depuis/vers Azure Blob Storage.
-
-## Configuration
-
-### Paramètres requis
-- `accountName` : Nom du compte de stockage Azure
-- `containerName` : Nom du conteneur blob
-
-### Authentification (une des options requises)
-- **Option 1** : `accountKey` - Clé d'accès du compte de stockage
-- **Option 2** : `sasToken` - Token SAS (Shared Access Signature)  
-- **Option 3** : `connectionString` - Chaîne de connexion complète
-
-### Paramètres optionnels
-- `prefix` : Préfixe des blobs pour filtrer
-- `limit` : Nombre maximum de documents à scanner
-
-## Configuration Azure
-
-### Option 1: Clé de compte (Recommandé pour dev/test)
-1. Aller dans le [Portail Azure](https://portal.azure.com)
-2. Naviguer vers votre compte de stockage
-3. Aller dans "Clés d'accès" dans le menu de gauche
-4. Copier le nom du compte et une des clés
-
-### Option 2: Token SAS (Recommandé pour production)
-1. Dans votre compte de stockage, aller dans "Signature d'accès partagé"
-2. Sélectionner les permissions nécessaires :
-   - **Lecture** : Read, List (pour import)
-   - **Écriture** : Read, Write, List, Create (pour import + export)
-3. Définir la période de validité
-4. Générer le token SAS
-5. Copier le token généré
-
-### Option 3: Chaîne de connexion
-1. Dans "Clés d'accès", copier une des chaînes de connexion complètes
-2. Format : `DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...`
-
-## Types d'authentification supportés
-
-### 1. Account Key
-```json
-{
-  "accountName": "mystorageaccount",
-  "accountKey": "base64encodedkey==",
-  "containerName": "documents"
-}
-```
-
-### 2. SAS Token
-```json
-{
-  "accountName": "mystorageaccount", 
-  "sasToken": "sv=2020-08-04&ss=b&srt=sco&sp=rwlacupx&se=2023-12-31T23:59:59Z&st=2023-01-01T00:00:00Z&spr=https&sig=...",
-  "containerName": "documents"
-}
-```
-
-### 3. Connection String
-```json
-{
-  "connectionString": "DefaultEndpointsProtocol=https;AccountName=mystorageaccount;AccountKey=base64key==;EndpointSuffix=core.windows.net",
-  "containerName": "documents"
-}
-```
-
-## Utilisation
-
-```bash
-# Mode interactif
-hubdoc-tool --engine azure-blob
-
-# Avec limite de documents  
-hubdoc-tool --engine azure-blob --limit 50
-```
-
-## Fichier de configuration
-
-Créer `azure-blob-config.json` :
-
-```json
-{
-  "accountName": "mystorageaccount",
-  "accountKey": "your-account-key-here",
-  "containerName": "documents",
-  "prefix": "invoices/",
-  "limit": 100
-}
-```
-
-## Fonctionnalités supportées
-
-### Scan (✅)
-- Parcours de tous les blobs dans le conteneur
-- Support des préfixes pour filtrer (dossiers virtuels)
-- Métadonnées Azure (tags, properties, metadata)
-- Filtrage par taille, date, type MIME
-
-### Import (✅)
-- Téléchargement direct vers fichier
-- Support des gros fichiers
-- Préservation de la structure de "dossiers"
-- Téléchargement par lots
-
-### Export (✅)
-- Upload avec détection automatique du type de contenu
-- Métadonnées personnalisées
-- Création de structure de préfixes
-- Support des gros fichiers
-
-## Structure des dossiers
-
-Azure Blob Storage utilise des noms de blobs avec `/` pour simuler des dossiers :
-- `documents/2023/invoice.pdf`
-- `documents/2023/reports/monthly.xlsx`
-
-Le connecteur traite ces préfixes comme une hiérarchie de dossiers.
-
-## Types de stockage Azure
-
-### Hot Tier (Chaud)
-- Accès fréquent
-- Coût de stockage élevé, coût d'accès faible
-- Par défaut pour nouveaux blobs
-
-### Cool Tier (Froid)  
-- Accès moins fréquent
-- Coût de stockage faible, coût d'accès élevé
-- Stockage minimum 30 jours
-
-### Archive Tier
-- Accès rare
-- Coût de stockage très faible
-- Réhydratation nécessaire avant accès (plusieurs heures)
-
-## Limitations
-
-- Taille maximale par blob : 5TB (Block Blob)
-- Nom de blob max : 1024 caractères
-- Métadonnées custom max : 8KB par blob
-- 50 000 blobs max par requête de listing
-
-## Permissions SAS
-
-### Permissions minimales pour Import
-- **Read** (r) : Lire le contenu des blobs
-- **List** (l) : Lister les blobs du conteneur
-
-### Permissions pour Export
-- **Read** (r) : Lire les blobs existants
-- **Write** (w) : Écrire/modifier des blobs
-- **List** (l) : Lister les blobs
-- **Create** (c) : Créer de nouveaux blobs
-
-## Troubleshooting
-
-### Erreur 403: Forbidden
-- Vérifier les permissions SAS ou account key
-- S'assurer que le conteneur existe
-- Vérifier la période de validité du token SAS
-
-### Erreur 404: Container not found
-- Vérifier que le nom du conteneur est correct
-- S'assurer que le conteneur existe dans le bon compte de stockage
-
-### Erreur de réseau/timeout
-- Vérifier la connectivité internet
-- Augmenter la valeur de timeout si nécessaire
-- Vérifier les règles de firewall du compte de stockage
-
-### Problèmes de performances
-- Utiliser des préfixes distribués pour éviter les goulots d'étranglement
-- Réduire la taille des lots si trop de requêtes simultanées
-- Considérer l'utilisation d'Azure CDN pour les accès en lecture
-
-## Bonnes pratiques
-
-### Sécurité
-- Utiliser des tokens SAS avec permissions minimales et expiration courte
-- Activer HTTPS uniquement
-- Configurer les règles de firewall du compte de stockage
-- Utiliser Azure Private Endpoints pour le trafic privé
-
-### Performance
-- Utiliser des noms de blobs distribués pour éviter les partitions chaudes
-- Activer les logs de diagnostic pour surveiller les performances
-- Utiliser des CDN pour la distribution mondiale
-
-### Coûts
-- Choisir le bon niveau d'accès (Hot/Cool/Archive)
-- Utiliser les règles de gestion du cycle de vie
-- Surveiller les coûts de transfert de données sortantes
-- Activer la compression pour réduire les coûts de stockage

package/docs/connectors/box.md

@@ -1,115 +0,0 @@
-# Box Cloud Storage Connector
-
-Plugin pour importer/exporter des documents depuis/vers Box Cloud Storage.
-
-## Configuration
-
-### Paramètres requis
-- `accessToken` : Token d'accès Box (Bearer token)
-
-### Paramètres optionnels
-- `clientId` : ID client Box (pour OAuth flow)
-- `clientSecret` : Secret client Box (pour OAuth flow)  
-- `rootFolderId` : ID du dossier racine à scanner (défaut: '0' pour root)
-- `limit` : Nombre maximum de documents à scanner
-
-## Obtention du token Box
-
-### Option 1: Box Developer Console (Recommandé)
-1. Aller sur [Box Developer Console](https://developer.box.com/)
-2. Créer une nouvelle app ou sélectionner une app existante
-3. Choisir le type d'authentification :
-   - **Custom App** avec "Server Authentication (with JWT)" pour les apps serveur
-   - **Custom App** avec "User Authentication (OAuth 2.0)" pour les apps utilisateur
-4. Dans les paramètres de l'app, générer un "Developer Token"
-5. Copier le token généré (valide 1 heure, renouvelable)
-
-### Option 2: OAuth 2.0 Flow (Pour production)
-1. Configurer les paramètres OAuth dans la Box Developer Console
-2. Implémenter le flow OAuth 2.0 pour obtenir un access token
-3. Utiliser le refresh token pour renouveler l'access token
-
-## Utilisation
-
-```bash
-# Mode interactif
-hubdoc-tool --engine box
-
-# Avec limite de documents
-hubdoc-tool --engine box --limit 10
-
-# Avec dossier racine spécifique
-hubdoc-tool --engine box
-# Puis configurer rootFolderId lors de la configuration
-```
-
-## Fichier de configuration
-
-Créer `box-config.json` :
-
-```json
-{
-  "accessToken": "votre_token_box",
-  "rootFolderId": "123456789",
-  "limit": 50
-}
-```
-
-## Fonctionnalités supportées
-
-### Scan (✅)
-- Parcours récursif de tous les dossiers
-- Support des métadonnées Box (tags, description, partage)
-- Filtrage par taille, date, type MIME
-
-### Import (✅)
-- Téléchargement avec streaming pour les gros fichiers
-- Préservation de la structure de dossiers
-- Gestion des redirections Box
-- Support du téléchargement par lots avec rate limiting
-
-### Export (✅)
-- Upload multipart pour les gros fichiers
-- Création automatique de l'arborescence de dossiers
-- Support des métadonnées lors de l'upload
-- Gestion de la résolution de conflits
-
-## Permissions requises
-
-Le token doit avoir les permissions suivantes :
-- `read_all_files_and_folders` : Pour scanner et télécharger
-- `write_all_files_and_folders` : Pour uploader (export uniquement)
-
-## Limitations
-
-- Les Developer Tokens expirent après 1 heure
-- Rate limiting : 10 requêtes par seconde par défaut
-- Taille maximale d'upload : 5GB par fichier
-- Les fichiers partagés publiquement peuvent avoir des restrictions d'accès
-
-## Troubleshooting
-
-### Erreur 401: Token invalide
-- Vérifier que le token n'a pas expiré (1h pour Developer Token)
-- Régénérer un nouveau Developer Token
-- Vérifier les permissions de l'app Box
-
-### Erreur 403: Accès refusé  
-- Vérifier les permissions de l'app sur les dossiers/fichiers
-- S'assurer que l'utilisateur a accès au contenu demandé
-
-### Erreur 429: Rate limit
-- Le plugin gère automatiquement le rate limiting avec des délais
-- Réduire la taille des lots avec `batchSize`
-
-## API Box utilisée
-
-- **API Version** : Box API v2.0
-- **Base URL** : `https://api.box.com/2.0`
-- **Documentation** : [Box API Docs](https://developer.box.com/reference/)
-
-### Endpoints utilisés
-- `GET /folders/{id}/items` : Liste le contenu d'un dossier
-- `GET /files/{id}/content` : Télécharge le contenu d'un fichier  
-- `POST /files/content` : Upload un nouveau fichier
-- `POST /folders` : Crée un nouveau dossier

package/docs/connectors/nuxeo.md

@@ -1,214 +0,0 @@
-# Nuxeo ECM Connector
-
-Plugin pour importer/exporter des documents depuis/vers Nuxeo Platform.
-
-## Configuration
-
-### Paramètres requis
-- `baseUrl` : URL de base Nuxeo (ex: http://localhost:8080/nuxeo)
-- `username` : Nom d'utilisateur Nuxeo
-- `password` : Mot de passe Nuxeo
-
-### Paramètres optionnels
-- `repository` : Nom du repository (défaut: 'default')
-- `rootPath` : Chemin de départ (défaut: '/default-domain/workspaces')
-- `limit` : Nombre maximum de documents à scanner
-
-## Configuration Nuxeo
-
-### Prérequis
-- Nuxeo Platform 10.10+ ou Nuxeo Cloud
-- API REST Nuxeo activée
-- Utilisateur avec permissions appropriées
-
-### Vérification de l'API
-1. Tester l'accès : `http://your-nuxeo/nuxeo/api/v1/user/Administrator`
-2. Vérifier l'authentification
-3. Contrôler l'accès aux workspaces
-
-## Structure Nuxeo
-
-### Hiérarchie standard
-```
-/default-domain/
-├── workspaces/           # Documents de travail
-│   ├── project-a/
-│   └── project-b/
-├── sections/             # Publications
-└── templates/           # Modèles
-```
-
-### Types de documents Nuxeo
-- **File** : Document avec contenu binaire
-- **Folder** : Dossier conteneur
-- **Workspace** : Espace de travail collaboratif
-- **Note** : Document texte simple
-- Types personnalisés selon votre configuration
-
-## Utilisation
-
-```bash
-# Mode interactif
-hubdoc-tool --engine nuxeo
-
-# Avec chemin spécifique
-hubdoc-tool --engine nuxeo
-# Configurer rootPath: /default-domain/workspaces/my-project
-```
-
-## Fichier de configuration
-
-Créer `nuxeo-config.json` :
-
-```json
-{
-  "baseUrl": "https://nuxeo.example.com/nuxeo",
-  "username": "Administrator",
-  "password": "Administrator",
-  "repository": "default",
-  "rootPath": "/default-domain/workspaces",
-  "limit": 100
-}
-```
-
-### Configuration avancée
-```json
-{
-  "baseUrl": "https://cloud.nuxeocloud.com/nuxeo",
-  "username": "user@example.com",
-  "password": "secure-password",
-  "repository": "default", 
-  "rootPath": "/default-domain/workspaces/project-documents",
-  "limit": 500
-}
-```
-
-## Fonctionnalités supportées
-
-### Scan (✅)
-- Requêtes NXQL pour parcours efficace
-- Support de tous les types de documents
-- Métadonnées complètes Nuxeo (schemas, facets)
-- États du cycle de vie
-- Filtrage par taille, date, type MIME
-
-### Import (✅)
-- Téléchargement via endpoint blob
-- Préservation de la structure de dossiers
-- Conservation des métadonnées Dublin Core
-- Support des versions de documents
-
-### Export (✅)
-- Upload multipart pour gros fichiers
-- Création automatique de l'arborescence
-- Assignment du type `File`
-- Métadonnées Dublin Core de base
-
-## Métadonnées Nuxeo
-
-### Schemas standard extraités
-- **Dublin Core** : title, description, creator, created, modified
-- **File Schema** : filename, content, mime-type, length
-- **Common Schema** : icon, size
-- **UID Schema** : uid, major_version, minor_version
-
-### États et cycle de vie
-- **project** : Brouillon de travail
-- **approved** : Document approuvé
-- **obsolete** : Document obsolète
-- États personnalisés selon configuration
-
-## API Nuxeo utilisée
-
-### Version API
-- **API REST** : Nuxeo REST API v1
-- **Base Path** : `/api/v1/repo/{repository}`
-- **Documentation** : [Nuxeo REST API](https://doc.nuxeo.com/nxdoc/rest-api/)
-
-### Endpoints utilisés
-- `GET /search/lang/NXQL/execute` : Requêtes NXQL
-- `GET /id/{docId}/@blob/file:content` : Télécharge le contenu
-- `POST /path/{path}` : Crée un nouveau document
-- `GET /path/{path}` : Accède à un document par chemin
-
-### Requêtes NXQL
-```sql
--- Tous les documents sous un chemin
-SELECT * FROM Document 
-WHERE ecm:path STARTSWITH '/default-domain/workspaces' 
-  AND ecm:isVersion = 0 
-  AND ecm:isTrashed = 0
-
--- Documents avec contenu binaire uniquement
-SELECT * FROM File 
-WHERE file:content IS NOT NULL
-```
-
-## Limitations
-
-### Nuxeo Platform
-- Pagination max : 1000 documents par défaut
-- Timeout par défaut : 30 secondes
-- Pas de support transactionnel via REST
-
-### Types de contenu
-- Le connecteur crée uniquement des documents de type `File`
-- Les métadonnées complexes ne sont pas préservées à l'export
-- Les relations entre documents ne sont pas maintenues
-
-### Performance
-- Les requêtes NXQL peuvent être lentes sur de gros volumes
-- L'indexation Elasticsearch peut créer des délais
-
-## Troubleshooting
-
-### Erreur 401: Authentication failed
-- Vérifier username/password
-- Contrôler que l'utilisateur est actif
-- Tester la connexion via interface web
-
-### Erreur 403: Access denied
-- Vérifier les permissions sur le workspace/dossier
-- Contrôler les groupes d'appartenance de l'utilisateur
-- Vérifier les ACL Nuxeo
-
-### Erreur 404: Path not found
-- Vérifier que le rootPath existe
-- Contrôler l'orthographe du chemin
-- S'assurer que l'utilisateur a accès au chemin
-
-### Performance lente
-- Réduire la portée du scan avec rootPath
-- Utiliser des filtres appropriés
-- Vérifier les performances de la base de données
-- Contrôler l'état de l'indexation Elasticsearch
-
-## Bonnes pratiques
-
-### Organisation des contenus
-- Organiser les documents en workspaces thématiques
-- Utiliser des structures de dossiers logiques
-- Implémenter des conventions de nommage
-
-### Métadonnées
-- Définir des schémas de métadonnées appropriés
-- Utiliser des vocabulaires contrôlés
-- Configurer des champs obligatoires
-
-### Sécurité
-- Utiliser HTTPS pour les connexions
-- Créer des utilisateurs techniques avec permissions minimales
-- Auditer les accès aux contenus sensibles
-- Configurer l'authentification LDAP/AD si approprié
-
-### Performance
-- Optimiser les index de base de données
-- Configurer Elasticsearch correctement
-- Utiliser des quotas d'espace disque appropriés
-- Planifier les opérations lourdes en dehors des heures de pointe
-
-### Maintenance
-- Surveiller les logs Nuxeo (server.log)
-- Effectuer des sauvegardes régulières du repository
-- Nettoyer les versions et documents supprimés
-- Maintenir les index Elasticsearch à jour