@sinoia/hubdoc-tools 1.0.4 → 1.2.1

package/EXPORT-DOCUMENTATION.md

@@ -1,333 +0,0 @@
-# 📤 HubDoc Export Documentation
-
-## Vue d'Ensemble
-
-L'outil **HubDoc Export** permet d'extraire des documents depuis HubDoc vers le système de fichiers local, avec reconstitution automatique de l'arborescence des dossiers.
-
-### 🎯 Fonctionnalités Clés
-
-- **Mode Scan** : Génère un fichier de mapping des documents HubDoc
-- **Mode Export** : Télécharge les documents selon le mapping personnalisé
-- **Filtres** : Par projet, domaine, ou critères personnalisés
-- **Arborescence** : Recréation automatique de la structure des dossiers
-- **Personnalisation** : Chemins de destination modifiables
-
----
-
-## 🚀 Utilisation
-
-### 1. Mode Scan - Génération du Mapping
-
-```bash
-# Scan complet de tous les documents
-hubdoc-tool export --scan
-
-# Scan filtré par projet
-hubdoc-tool export --scan --project "Les Jardins de Meudon"
-
-# Scan filtré par domaine
-hubdoc-tool export --scan --domain "BTP & Construction"
-
-# Scan avec fichier de sortie personnalisé
-hubdoc-tool export --scan --mapping my-export.csv
-```
-
-**Résultat :**
-```
-🔍 Scanning HubDoc for documents...
-   📁 Project filter: Les Jardins de Meudon
-✅ Generated export mapping for 1,847 documents
-
-📊 Scan Summary
-📄 Total documents found: 1,847
-
-📁 Documents by project:
-   • Les Jardins de Meudon: 1,847 documents
-
-✅ Export mapping generated successfully
-   📝 Edit the CSV file to customize target paths
-   🚀 Run with --mode export to download documents
-```
-
-### 2. Mode Export - Téléchargement
-
-```bash
-# Export avec mapping par défaut
-hubdoc-tool export
-
-# Export avec mapping personnalisé
-hubdoc-tool export --mapping my-export.csv
-
-# Export vers un dossier spécifique
-hubdoc-tool export --output ./mes-documents
-
-# Mode interactif
-hubdoc-tool export --interactive
-```
-
-**Résultat :**
-```
-📄 Loading export mapping from: export-mapping.csv
-📦 Found 1,847 documents to export
-📦 Starting export of 1,847 documents to ./export
-
-(1847/1847) Exporting: plan_facade_nord_v3.pdf
-✅ Exported: plan_facade_nord_v3.pdf → Les Jardins de Meudon/Technique/Plans Architecture
-
-📊 Export Summary
-✅ Successfully exported: 1,847 documents
-📁 Export directory: /Users/olivier/export
-
-📁 Directory structure created:
-   📂 Les Jardins de Meudon/Administrative/Permis & Autorisations
-   📂 Les Jardins de Meudon/Technique/Plans Architecture
-   📂 Les Jardins de Meudon/Financier/Devis
-   📂 Les Jardins de Meudon/Suivi/PV Chantier
-```
-
----
-
-## 📋 Format du Mapping CSV
-
-### Structure Générée (Scan)
-
-```csv
-Document ID,Document Name,Projects (project:folder|project:folder),Download URL,Target Path (editable),Metadata (JSON)
-doc_001,plan_facade_sud.pdf,Les Jardins de Meudon:Technique/Plans Architecture,https://hubdoc.../download/doc_001,Les Jardins de Meudon/Technique/Plans Architecture,"{\"type\":\"plan\",\"version\":\"2.1\"}"
-doc_002,permis_construire.pdf,Les Jardins de Meudon:Administrative/Permis & Autorisations,https://hubdoc.../download/doc_002,Les Jardins de Meudon/Administrative/Permis & Autorisations,"{\"numero\":\"PC-2024-001\"}"
-doc_003,devis_gros_oeuvre.pdf,Les Jardins de Meudon:Financier/Devis,https://hubdoc.../download/doc_003,Les Jardins de Meudon/Financier/Devis,"{\"montant\":285000}"
-```
-
-### Colonnes Expliquées
-
-| Colonne | Description | Modifiable |
-|---------|-------------|------------|
-| **Document ID** | Identifiant unique HubDoc | ❌ Non |
-| **Document Name** | Nom du fichier | ❌ Non |
-| **Projects** | Projets/dossiers dans HubDoc | ❌ Non |
-| **Download URL** | URL de téléchargement | ❌ Non |
-| **Target Path (editable)** | Chemin de destination | ✅ **Oui** |
-| **Metadata** | Métadonnées du document | ❌ Non |
-
-### 🎛️ Personnalisation des Chemins
-
-**Exemples de modification de la colonne "Target Path" :**
-
-```csv
-# AVANT (généré automatiquement)
-Target Path (editable)
-Les Jardins de Meudon/Technique/Plans Architecture
-Les Jardins de Meudon/Administrative/Permis & Autorisations
-
-# APRÈS (personnalisé par l'utilisateur)
-Target Path (editable)
-Projets 2024/Meudon/Plans
-Archives/Administratif/Meudon
-Mes Documents/Projets/Plans Architecture
-Export Complet/Documents Techniques
-```
-
----
-
-## 🗂️ Exemples d'Arborescence Créée
-
-### Arborescence par Défaut (HubDoc)
-```
-./export/
-├── Les Jardins de Meudon/
-│   ├── Administrative/
-│   │   ├── Permis & Autorisations/
-│   │   │   ├── permis_construire_001.pdf
-│   │   │   └── autorisation_voirie.pdf
-│   │   └── Contrats & Marchés/
-│   │       └── marche_gros_oeuvre.pdf
-│   ├── Technique/
-│   │   ├── Plans Architecture/
-│   │   │   ├── plan_facade_nord.pdf
-│   │   │   └── plan_facade_sud.pdf
-│   │   └── Plans Structure/
-│   │       └── plan_fondations.pdf
-│   └── Financier/
-│       └── Devis/
-│           ├── devis_gros_oeuvre.pdf
-│           └── devis_second_oeuvre.pdf
-└── Résidence Harmony Levallois/
-    ├── Administrative/
-    └── Technique/
-```
-
-### Arborescence Personnalisée
-```
-./export/
-├── Archives 2024/
-│   ├── Projets BTP/
-│   │   ├── Meudon - Plans/
-│   │   └── Levallois - Plans/
-│   └── Documents Admin/
-├── Projets Actifs/
-│   ├── Meudon/
-│   └── Levallois/
-└── Exports Spéciaux/
-    └── Plans Architecte/
-```
-
----
-
-## ⚙️ Options de Ligne de Commande
-
-### Command Export
-
-```bash
-hubdoc-tool export [OPTIONS]
-```
-
-**Options :**
-
-| Option | Description | Exemple |
-|--------|-------------|---------|
-| `-s, --scan` | Mode scan - génère le mapping | `--scan` |
-| *(défaut)* | Mode export - télécharge les documents | *(aucune option)* |
-| `-p, --project <name>` | Filtre par nom de projet | `--project "Les Jardins de Meudon"` |
-| `-d, --domain <name>` | Filtre par domaine | `--domain "BTP & Construction"` |
-| `-m, --mapping <file>` | Fichier de mapping personnalisé | `--mapping my-export.csv` |
-| `-o, --output <dir>` | Répertoire de sortie | `--output ./mes-exports` |
-| `-i, --interactive` | Mode interactif | `--interactive` |
-
-### Exemples Complets
-
-```bash
-# Workflow complet : Scan -> Edit -> Export
-hubdoc-tool export --scan --project "Les Jardins de Meudon"
-# Éditer export-mapping.csv pour personnaliser les chemins
-hubdoc-tool export --output ./projet-meudon
-
-# Export filtré avec mapping personnalisé
-hubdoc-tool export --scan --domain "BTP & Construction" --mapping btp-docs.csv
-hubdoc-tool export --mapping btp-docs.csv --output ./documents-btp
-
-# Mode interactif complet
-hubdoc-tool export --interactive
-```
-
----
-
-## 🔍 Filtres Disponibles
-
-### Filtre par Projet
-```bash
-# Projets spécifiques
---project "Les Jardins de Meudon"
---project "Résidence Harmony Levallois" 
---project "BAUTECH Corporate"
-```
-
-### Filtre par Domaine
-```bash
-# Domaines métier
---domain "BTP & Construction"
---domain "Administration"
---domain "Technique & Maintenance"
---domain "Légal & Conformité"
-```
-
-### Combinaison de Filtres
-```bash
-# Export des documents BTP du projet Meudon
-hubdoc-tool export --scan \
-  --project "Les Jardins de Meudon" \
-  --domain "BTP & Construction"
-```
-
----
-
-## 🛠️ Workflow Recommandé
-
-### 1. **Analyse Préliminaire**
-```bash
-# Scan global pour voir le volume
-hubdoc-tool export --scan --mapping analyse-complete.csv
-```
-
-### 2. **Export Ciblé**
-```bash
-# Export par projet
-hubdoc-tool export --scan --project "Les Jardins de Meudon" --mapping meudon.csv
-hubdoc-tool export --scan --project "Résidence Harmony Levallois" --mapping levallois.csv
-```
-
-### 3. **Personnalisation**
-- Ouvrir les fichiers CSV dans Excel/LibreOffice
-- Modifier la colonne "Target Path (editable)"
-- Adapter l'arborescence aux besoins
-
-### 4. **Export Final**
-```bash
-hubdoc-tool export --export --mapping meudon.csv --output ./exports/meudon
-hubdoc-tool export --export --mapping levallois.csv --output ./exports/levallois
-```
-
----
-
-## 📊 Gestion des Erreurs
-
-### Erreurs Courantes
-
-**Document non accessible :**
-```
-❌ Failed to export plan_facade_nord.pdf: Document not found or access denied
-```
-
-**Chemin invalide :**
-```
-⚠️  Invalid target path for document.pdf: ../../../system/file
-⚠️  Skipping 1 documents with invalid paths
-```
-
-**Espace disque :**
-```
-❌ Failed to export large_plan.pdf: ENOSPC: no space left on device
-```
-
-### Validation Automatique
-
-L'outil vérifie automatiquement :
-- ✅ Validité des chemins de destination
-- ✅ Permissions d'écriture
-- ✅ Caractères interdits dans les noms de fichiers
-- ✅ Disponibilité des documents sur HubDoc
-
----
-
-## 🔧 Configuration Avancée
-
-### Variables d'Environnement
-
-```bash
-# Timeout de téléchargement (ms)
-export HUBDOC_DOWNLOAD_TIMEOUT=300000
-
-# Nombre de téléchargements simultanés
-export HUBDOC_CONCURRENT_DOWNLOADS=5
-
-# Taille max des fichiers (bytes)
-export HUBDOC_MAX_FILE_SIZE=104857600  # 100MB
-```
-
-### Fichier de Configuration
-
-```json
-{
-  "apiUrl": "https://demo.hubdoc.sinoia.cloud/api/v1",
-  "token": "your-api-token",
-  "export": {
-    "defaultOutputDir": "./exports",
-    "createDateFolders": true,
-    "preserveMetadata": true,
-    "skipExisting": true
-  }
-}
-```
-
----
-
-*Documentation Export - HubDoc Tools v1.1.0*

package/HUBDOC-API-V2.md

@@ -1,248 +0,0 @@
-# 🚀 HubDoc API v2 Integration
-
-Cette documentation explique les améliorations apportées à l'intégration HubDoc basées sur la documentation Swagger officielle.
-
-## 📋 Améliorations Apportées
-
-### ✅ Services API Mis à Jour
-
-1. **HubDocApiServiceV2** (`/src/services/hubdoc-api-v2.ts`)
-   - Utilise les vrais endpoints de l'API HubDoc
-   - Authentification JWT via `/auth/login`
-   - Gestion des workspaces avec `/workspaces`
-   - Upload de fichiers avec `/files`
-   - Gestion des permissions intégrée
-
-2. **HubDocExportServiceV2** (`/src/services/hubdoc-export-v2.ts`)
-   - Export basé sur les vrais endpoints
-   - Scan des workspaces et folders
-   - Téléchargement via `/files/{id}/download`
-   - Statistiques d'export
-
-### ✅ Commandes Améliorées
-
-1. **ImportCommandV2** (`/src/commands/import-v2.ts`)
-   - Validation des mappings avant import
-   - Mode interactif amélioré
-   - Rapport détaillé des résultats
-   - Gestion d'erreurs robuste
-
-2. **ExportCommandV2** (`/src/commands/export-v2.ts`)
-   - Preview avant export
-   - Export basé sur recherche
-   - Configuration interactive
-   - Statistiques détaillées
-
-## 🔗 Endpoints API Utilisés
-
-### Authentification
-```http
-POST /auth/login
-GET  /auth/me
-```
-
-### Workspaces
-```http
-GET  /workspaces
-POST /workspaces
-```
-
-### Folders
-```http
-GET  /folders
-POST /folders
-GET  /folders/{id}/contents
-```
-
-### Files
-```http
-GET  /files
-POST /files
-GET  /files/{id}/download
-```
-
-### Search
-```http
-GET  /search?q={query}&type={file|folder|workspace}
-```
-
-## 🧪 Tests d'Intégration
-
-### Test Manuel
-```bash
-# Tester la connexion API
-npm run test-api
-
-# Avec tests d'écriture (optionnel)
-HUBDOC_TEST_WRITE=true npm run test-api
-```
-
-### Tests Couverts
-- ✅ Connexion API et authentification
-- ✅ Récupération des workspaces
-- ✅ Récupération des folders
-- ✅ Fonctionnalité de recherche
-- ✅ Statistiques d'export
-- ✅ Opérations d'écriture (optionnel)
-
-## 📊 Comparaison v1 vs v2
-
-| Fonctionnalité | API v1 | API v2 |
-|----------------|--------|--------|
-| **Authentification** | Bearer token statique | JWT avec `/auth/login` |
-| **Test de connexion** | `/ping` | `/auth/me` |
-| **Workspaces** | `/workspaces` (supposé) | `/workspaces` (validé) |
-| **Folders** | `/folders` (basique) | `/folders` + hiérarchie |
-| **Upload** | `/documents` (supposé) | `/files` (validé) |
-| **Permissions** | Post-upload | Intégrées à l'upload |
-| **Metadata** | Form fields | JSON intégré |
-| **Download** | URL supposée | `/files/{id}/download` |
-| **Search** | Non disponible | `/search` avec filtres |
-
-## 🔄 Migration depuis v1
-
-### 1. Configuration
-La configuration reste identique :
-```json
-{
-  "apiUrl": "https://demo.hubdoc.sinoia.cloud/api/v1",
-  "token": "your-jwt-token"
-}
-```
-
-### 2. Commandes CLI
-Les commandes restent compatibles :
-```bash
-# Import (identique)
-hubdoc-tool import --mapping mapping.csv
-
-# Export (identique)
-hubdoc-tool export --scan
-hubdoc-tool export --mapping export-mapping.csv
-```
-
-### 3. Services
-Pour utiliser les nouveaux services dans votre code :
-```typescript
-// Ancien
-import { HubDocApiService } from './services/hubdoc-api';
-
-// Nouveau
-import { HubDocApiServiceV2 } from './services/hubdoc-api-v2';
-```
-
-## 🎯 Nouvelles Fonctionnalités
-
-### 1. Validation Pré-Import
-```bash
-# Les mappings sont maintenant validés automatiquement
-hubdoc-tool import --mapping mapping.csv
-```
-
-### 2. Export Basé sur Recherche
-```bash
-# Export interactif avec recherche
-hubdoc-tool export --scan --interactive
-```
-
-### 3. Statistiques Détaillées
-```bash
-# Les statistiques HubDoc sont affichées pendant le scan
-hubdoc-tool export --scan
-```
-
-### 4. Gestion d'Erreurs Améliorée
-- Messages d'erreur plus détaillés
-- Retry automatique pour les erreurs réseau
-- Rapport de taux de succès
-
-### 5. Mode Interactif Enrichi
-- Configuration assistée
-- Preview avant opération
-- Confirmation utilisateur
-
-## 🔧 Configuration Avancée
-
-### Variables d'Environnement
-```bash
-# Debug API calls
-DEBUG=hubdoc-tool:* npm run dev
-
-# Test avec opérations d'écriture
-HUBDOC_TEST_WRITE=true npm run test-api
-
-# Timeout personnalisé (ms)
-HUBDOC_API_TIMEOUT=60000
-```
-
-### Headers Personnalisés
-```typescript
-const apiService = new HubDocApiServiceV2({
-  apiUrl: 'https://your.hubdoc.instance/api/v1',
-  token: 'your-token',
-  // Headers additionnels si nécessaire
-  customHeaders: {
-    'X-Custom-Header': 'value'
-  }
-});
-```
-
-## 🐛 Dépannage
-
-### Erreurs Courantes
-
-**❌ Connection failed**
-```bash
-# Vérifiez la configuration
-hubdoc-tool config
-
-# Testez la connexion
-npm run test-api
-```
-
-**❌ No workspaces found**
-- Vérifiez que votre compte a accès aux workspaces
-- Vérifiez les permissions du token
-
-**❌ Upload failed**
-- Vérifiez la taille du fichier (limite serveur)
-- Vérifiez les permissions d'écriture
-- Vérifiez le format du fichier
-
-### Logs de Debug
-```bash
-# Activer les logs détaillés
-DEBUG=hubdoc-tool:api npm run dev -- import --mapping test.csv
-```
-
-## 📈 Performance
-
-### Optimisations v2
-- **Batch processing** : Uploads par lots de 5
-- **Rate limiting** : Délais automatiques entre requêtes
-- **Connection pooling** : Réutilisation des connexions
-- **Error recovery** : Retry automatique
-
-### Recommandations
-- Utilisez des lots de 5-10 documents pour l'import
-- Évitez les fichiers > 50MB
-- Surveillez les rate limits de votre instance HubDoc
-
-## 🚀 Prochaines Étapes
-
-### Roadmap v2.1
-- [ ] Support des métadonnées étendues
-- [ ] Import incrémental
-- [ ] Synchronisation bidirectionnelle
-- [ ] API de monitoring
-- [ ] Webhooks pour les notifications
-
-### Migration Complète
-1. Tester avec `npm run test-api`
-2. Valider avec un petit import test
-3. Migrer progressivement les scripts existants
-4. Surveiller les performances
-
----
-
-*HubDoc API v2 Integration - Compatible avec l'API Swagger officielle*