@sinoia/hubdoc-tools 1.0.4 → 1.2.1

package/PRESENTATION-CLIENT.md

@@ -1,100 +0,0 @@
-# 🔄 HubDoc Tool - Migration Documentaire Simplifiée
-
-## 📋 Le Défi de la Migration Documentaire
-
-Vous avez **des milliers de documents** éparpillés sur vos serveurs de fichiers, dans des arborescences complexes, avec des permissions variées ? HubDoc Tool résout ce défi en **3 étapes simples**.
-
-## 🚀 Principe Import : De Vos Serveurs vers HubDoc
-
-### 🎯 **Objectif** : Centraliser vos documents dans HubDoc avec l'organisation que VOUS décidez
-
-**Comment ça marche :**
-
-1. **📊 Scan Intelligent**
-   - Notre outil scanne vos répertoires existants
-   - Génère un fichier Excel/CSV avec TOUS vos documents listés
-
-2. **✏️ Personnalisation Métier**
-   - Vous éditez le fichier pour définir OÙ va chaque document
-   - Vous assignez les projets, domaines, permissions selon VOS règles métier
-   - Vous prévisualisez l'organisation avant le transfert
-
-3. **⚡ Import Automatique**
-   - L'outil transfère vos documents selon votre mapping
-   - Création automatique des projets et dossiers HubDoc
-   - Application des permissions utilisateurs/groupes
-
-**📈 Résultat :** 15 000 documents organisés et sécurisés en quelques heures au lieu de semaines
-
----
-
-## 📤 Principe Export : De HubDoc vers Vos Archives
-
-### 🎯 **Objectif** : Récupérer vos documents HubDoc avec l'arborescence de VOTRE choix
-
-**Comment ça marche :**
-
-1. **🔍 Scan HubDoc**
-   - L'outil liste tous vos documents disponibles
-   - Génère un fichier Excel/CSV avec leur localisation actuelle
-
-2. **🗂️ Réorganisation**
-   - Vous définissez la nouvelle structure de dossiers souhaitée
-   - Vous personnalisez les chemins selon vos besoins d'archivage
-   - Exemple : "Projets 2024/Meudon/Plans" au lieu de "Les Jardins de Meudon/Technique"
-
-3. **💾 Export Structuré**
-   - Téléchargement automatique avec création de l'arborescence
-   - Conservation des métadonnées et informations projets
-   - Prêt pour archivage ou migration vers autre système
-
-**🎯 Résultat :** Vos documents récupérés dans l'organisation exacte que vous souhaitez
-
----
-
-## ⚙️ La Force du Mapping CSV : Votre Contrôle Total
-
-**Le fichier de mapping est votre tableau de bord :**
-- ✅ **Transparence** : Vous voyez exactement où va chaque document
-- ✅ **Contrôle** : Vous décidez de l'organisation finale
-- ✅ **Flexibilité** : Modification facile avant exécution
-- ✅ **Traçabilité** : Historique complet des opérations
-
-**Métadonnées automatiques :**
-- Type de document, projet associé, entreprise
-- Permissions par utilisateur/groupe
-- Informations techniques (montants, dates, références)
-
----
-
-## 🏆 Avantages Business
-
-### Pour l'Import :
-- **⏱️ Gain de temps** : 15 000 docs en 3h au lieu de 3 semaines manuelles
-- **🎯 Zéro erreur** : Organisation automatisée selon vos règles
-- **🔒 Sécurité** : Permissions appliquées dès l'import
-- **📊 Traçabilité** : Suivi complet des opérations
-
-### Pour l'Export :
-- **📁 Arborescence personnalisée** : Structure adaptée à vos besoins
-- **💾 Archivage facilité** : Format standard pour conservation légale
-- **🔄 Migration simplifiée** : Passage vers autres systèmes documentaires
-- **🎯 Extraction ciblée** : Par projet, domaine ou période
-
----
-
-## 🔧 Mise en Œuvre
-
-**Prérequis techniques :**
-- Accès aux serveurs de fichiers existants
-- Configuration API HubDoc (nous nous en chargeons)
-- Définition des règles métier d'organisation
-
-**Accompagnement inclus :**
-- Formation à l'utilisation de l'outil
-- Support technique pendant la migration
-- Validation des mappings avant exécution
-
----
-
-*HubDoc Tool : La solution technique qui respecte VOS choix d'organisation métier*

package/README-hubdoc-tool.md

@@ -1,369 +0,0 @@
-# @sinoia/hubdoc-tools
-
-A professional Node.js command-line tool for bulk document import/export with HubDoc solution. This tool allows you to import documents either directly from a directory structure or using a CSV mapping file with custom metadata, permissions, domain classification, and project assignments.
-
-**🚀 Latest Updates (v1.1):**
-- **Flexible Source Directories**: Import from any directory without changing working directory
-- **New `--source` option**: Alternative to `--direct` for better workflow integration
-- **Enhanced mapping generation**: Support for both positional arguments and options
-- **Improved validation**: Better error handling for conflicting options
-
-## Features
-
-- **Direct Import Mode**: Import all files from a directory, preserving folder structure
-- **Flexible Source Directories**: Import from any directory without changing working directory
-- **Mapping Import Mode**: Use CSV mapping file for precise control over document placement
-- **Interactive & CLI Modes**: Both interactive wizard and command-line interface
-- **Configuration Wizard**: First-time setup for API credentials
-- **Folder Management**: Automatic folder creation in HubDoc
-- **Project Support**: Assign documents to specific projects with classification plans
-- **Permissions Management**: Set user and group permissions on imported documents
-- **Progress Tracking**: Real-time import progress with detailed feedback
-
-## Installation
-
-```bash
-# Global installation (recommended)
-npm install -g @sinoia/hubdoc-tools
-
-# Verify installation
-hubdoc-tool --version
-```
-
-## Configuration
-
-First, configure your HubDoc API credentials:
-
-```bash
-# Quick OAuth setup (recommended)
-hubdoc-tool get-token rec.hubdoc.sinoia.cloud --save
-
-# Interactive configuration wizard
-hubdoc-tool config
-
-# Or run any command and it will prompt for configuration
-hubdoc-tool import --interactive
-```
-
-### OAuth Token Retrieval (Recommended)
-
-The easiest way to get started is using the OAuth token retrieval:
-
-```bash
-# Get token automatically and save to .hubdoc-config.json
-hubdoc-tool get-token rec.hubdoc.sinoia.cloud --save
-
-# Custom port and timeout
-hubdoc-tool get-token rec.hubdoc.sinoia.cloud --port 8889 --timeout 600 --save
-```
-
-This will:
-1. Start a local server on port 8888 (or specified port)
-2. Open your browser to the HubDoc authentication page
-3. Automatically retrieve the OAuth token after login
-4. Save the token to `.hubdoc-config.json` file if `--save` is used
-
-### Manual Configuration
-
-The wizard will ask for:
-- **API URL**: Your HubDoc API endpoint (e.g., `https://demo.hubdoc.sinoia.cloud/api/v1`)
-- **API Token**: Your authentication token
-- **Storage Format**: Choose between JSON config file or environment file
-
-## Usage
-
-### 1. Generate Mapping File
-
-Create a CSV mapping file from a directory:
-
-```bash
-# Generate mapping.csv from documents directory (relative path)
-hubdoc-tool generate-mapping ./documents
-
-# Generate from absolute path
-hubdoc-tool generate-mapping --source /path/to/documents
-
-# Custom output file
-hubdoc-tool gen ./documents -o my-mapping.csv
-
-# Generate from any directory with custom output
-hubdoc-tool gen --source /home/user/invoices --output invoices-mapping.csv
-
-# Use current directory if no path specified
-hubdoc-tool generate-mapping
-```
-
-This creates a CSV file with columns:
-- **File Path**: Path to the source file
-- **Target Folder**: Destination folder in HubDoc (will be created if doesn't exist)
-- **Projet**: Project name (optional)
-- **Domain**: Business domain for transverse classification
-- **Metadata (JSON)**: Additional metadata as JSON object
-- **Read Permissions**: Users and groups who can read the document (format: `users:user1,user2|groups:group1,group2`)
-- **Write Permissions**: Users and groups who can edit the document (format: `users:user1,user2|groups:group1,group2`)
-
-### 2. Edit Mapping File
-
-Edit the generated CSV to specify:
-
-```csv
-File Path,Target Folder,Workspace,Domain,Plan Classement,Metadata (JSON),Read Permissions,Write Permissions
-# === DÉFINITION DES PROJETS ===
-./docs/projets/finance/,CREATE_PROJECT,Projet Finance 2024,Administration,ADMINISTRATION_GENERALE,"{\"type\":\"projet\",\"budget\":500000}",groups:direction,comptabilite,groups:direction
-
-# === DOCUMENTS ===
-./docs/invoice.pdf,Financier/Factures,Projet Finance 2024,Administration,,"{\"department\":\"accounting\"}",users:john,jane|groups:finance,groups:finance
-./docs/contract.pdf,Juridique/Contrats,Projet Finance 2024,Légal & Conformité,,"{\"type\":\"legal\"}",groups:legal,management,groups:legal
-```
-
-### 3. Import Documents
-
-#### Direct Import Mode
-Import all files from a directory:
-
-```bash
-# Import all files from documents directory (relative path)
-hubdoc-tool import --direct ./documents
-
-# Import from any directory (absolute path)
-hubdoc-tool import --source /path/to/documents
-
-# Alternative syntax (same as --source)
-hubdoc-tool import --direct /home/user/invoices
-
-# Interactive mode (allows choosing any directory)
-hubdoc-tool import --interactive
-```
-
-#### Mapping Import Mode  
-Import using CSV mapping file:
-
-```bash
-# Import using mapping file
-hubdoc-tool import --mapping mapping.csv
-
-# Interactive mode
-hubdoc-tool import --interactive
-```
-
-## Command Reference
-
-### Global Options
-- `--help`: Show help information
-- `--version`: Show version number
-
-### Commands
-
-#### `generate-mapping [source-dir]`
-Generate a CSV mapping file from directory structure.
-
-**Options:**
-- `-s, --source <dir>`: Source directory to scan (if not provided as argument)
-- `-o, --output <file>`: Output CSV file (default: mapping.csv)
-
-**Examples:**
-```bash
-# Using argument
-hubdoc-tool generate-mapping ./documents
-hubdoc-tool gen ./documents -o invoices-mapping.csv
-
-# Using --source option (flexible path)
-hubdoc-tool generate-mapping --source /path/to/documents
-hubdoc-tool gen --source /home/user/invoices --output invoices.csv
-
-# Use current directory
-hubdoc-tool generate-mapping
-```
-
-#### `import`
-Import documents to HubDoc.
-
-**Options:**
-- `-d, --direct <dir>`: Direct import mode - import all files from directory
-- `-s, --source <dir>`: Source directory for direct import (alternative to --direct)
-- `-m, --mapping <file>`: Mapping mode - use CSV mapping file  
-- `-i, --interactive`: Interactive mode (prompts for options)
-
-**Examples:**
-```bash
-# Direct import (relative path)
-hubdoc-tool import --direct ./documents
-
-# Direct import from any directory
-hubdoc-tool import --source /path/to/documents
-hubdoc-tool import --direct /home/user/invoices
-
-# Mapping import
-hubdoc-tool import --mapping mapping.csv
-
-# Interactive mode
-hubdoc-tool import --interactive
-hubdoc-tool import  # defaults to interactive if no options
-```
-
-**Note:** You cannot use both `--direct` and `--source` options together, as they serve the same purpose. Choose the one that fits your workflow better.
-
-## Workflow Examples
-
-### Scenario 1: Import from Remote/Network Directory
-```bash
-# Working from your project directory, import documents from network share
-cd /workspace/hubdoc-project
-hubdoc-tool generate-mapping --source /mnt/shared/corporate-docs --output corporate-mapping.csv
-# Edit corporate-mapping.csv to configure folders and permissions
-hubdoc-tool import --mapping corporate-mapping.csv
-```
-
-### Scenario 2: Batch Processing Multiple Directories
-```bash
-# Process invoices from different locations
-hubdoc-tool generate-mapping --source /data/invoices/2024 --output invoices-2024.csv
-hubdoc-tool generate-mapping --source /backup/invoices/2023 --output invoices-2023.csv
-# Configure each mapping file separately
-hubdoc-tool import --mapping invoices-2024.csv
-hubdoc-tool import --mapping invoices-2023.csv
-```
-
-### Scenario 3: Direct Import for Simple Cases
-```bash
-# Quick import without mapping customization
-hubdoc-tool import --source /home/user/scanned-docs
-```
-
-#### `config`
-Configure HubDoc API settings.
-
-**Examples:**
-```bash
-hubdoc-tool config
-```
-
-#### `get-token`
-Get OAuth token for CLI usage with automatic browser authentication.
-
-**Options:**
-- `--save`: Save token to .hubdoc-config.json file automatically
-- `--port <number>`: Local server port for OAuth callback (default: 8888)
-- `--timeout <seconds>`: OAuth flow timeout in seconds (default: 300)
-
-**Examples:**
-```bash
-# Get token and display it
-hubdoc-tool get-token rec.hubdoc.sinoia.cloud
-
-# Get token and save to .hubdoc-config.json automatically
-hubdoc-tool get-token rec.hubdoc.sinoia.cloud --save
-
-# Use custom port and timeout
-hubdoc-tool get-token demo.hubdoc.sinoia.cloud --port 8889 --timeout 600 --save
-```
-
-#### `revoke-token`
-Revoke an OAuth token.
-
-**Examples:**
-```bash
-hubdoc-tool revoke-token rec.hubdoc.sinoia.cloud token-id-here
-```
-
-## Configuration Files
-
-The tool supports two configuration formats:
-
-### JSON Configuration (`.hubdoc-config.json`)
-
-#### Manual Configuration
-```json
-{
-  "apiUrl": "https://demo.hubdoc.sinoia.cloud/api/v1",
-  "token": "your-api-token"
-}
-```
-
-#### OAuth Generated Configuration
-When using `hubdoc-tool get-token --save`, the configuration includes additional metadata:
-
-```json
-{
-  "apiUrl": "https://rec.hubdoc.sinoia.cloud",
-  "token": "xxx-oauth-token-xxx",
-  "tokenGenerated": "2024-09-23T15:30:00.000Z",
-  "tokenExpires": "2025-09-23T15:30:00.000Z",
-  "tokenScopes": ["read", "write", "admin"]
-}
-```
-
-### Environment File (`.env`)
-```env
-HUBDOC_API_URL=https://demo.hubdoc.sinoia.cloud/api/v1
-HUBDOC_TOKEN=your-api-token
-```
-
-## CSV Mapping Format
-
-The CSV mapping file supports the following columns:
-
-| Column | Description | Required | Example |
-|--------|-------------|----------|---------|
-| File Path | Path to source file | Yes | `./docs/invoice.pdf` |
-| Target Folder | Destination folder name | No | `Invoices` |
-| Workspace | Project name (technical field) | No | `Projet Finance 2024` |
-| Domain | Business domain | No | `Administration` |
-| Plan Classement | Classification plan template | No | `ADMINISTRATION_GENERALE` |
-| Metadata (JSON) | Additional metadata | No | `{"type":"invoice","amount":1000}` |
-| Read Permissions | Users/groups with read access | No | `users:john,jane\|groups:finance` |
-| Write Permissions | Users/groups with write access | No | `groups:finance` |
-
-### Permission Format
-Both Read and Write permissions use the format: `users:user1,user2|groups:group1,group2`
-
-- **users**: Comma-separated list of usernames
-- **groups**: Comma-separated list of group names  
-- **separator**: Use `|` to separate users and groups
-
-**Examples:**
-- Read only for specific users: `users:john,jane`
-- Write access for a group: `groups:editors`
-- Mixed permissions: `users:admin|groups:finance,legal`
-
-## Error Handling
-
-The tool provides detailed error reporting:
-- Connection failures to HubDoc API
-- File not found errors
-- Permission errors
-- API response errors
-- Invalid CSV format errors
-
-Failed imports are logged with specific error messages for troubleshooting.
-
-## Development
-
-```bash
-# Install dependencies
-npm install
-
-# Development mode (for contributors)
-npm install
-npm run build
-npm run dev -- import --interactive
-
-# Build
-npm run build
-
-# Test
-npm test
-```
-
-## API Integration
-
-This tool integrates with the HubDoc API and supports:
-- Document upload with multipart form data
-- Folder creation and management  
-- Project integration with classification plans
-- Permission management
-- Metadata assignment
-
-## License
-
-MIT License

package/README-npm.md

@@ -1,238 +0,0 @@
-# @sinoia/hubdoc-tools
-
-🚀 **Professional document import/export tool for HubDoc solution**
-
-[![npm version](https://badge.fury.io/js/%40sinoia%2Fhubdoc-tools.svg)](https://www.npmjs.com/package/@sinoia/hubdoc-tools)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-## 📋 Overview
-
-`@sinoia/hubdoc-tools` is a powerful command-line tool for bulk document management with HubDoc. Import documents from local filesystem or cloud sources, export with folder structure preservation, and manage workspaces, folders, and permissions.
-
-## 🚀 Quick Start
-
-### Installation
-
-```bash
-# Global installation (recommended)
-npm install -g @sinoia/hubdoc-tools
-
-# Local installation
-npm install @sinoia/hubdoc-tools
-```
-
-### Configuration
-
-```bash
-# First-time setup
-hubdoc-tool config
-
-# Or create config file manually
-echo '{
-  "apiUrl": "https://your.hubdoc.instance/api/v1",
-  "token": "your-jwt-token"
-}' > .hubdoc-config.json
-```
-
-## 📥 Import Documents
-
-### Direct Import
-```bash
-# Import all files from a directory
-hubdoc-tool import --source /path/to/documents
-
-# With workspace assignment
-hubdoc-tool import --source /path/to/documents --workspace "Project ABC"
-```
-
-### CSV Mapping Import
-```bash
-# Generate mapping file
-hubdoc-tool generate-mapping /path/to/documents
-
-# Edit mapping.csv to specify folders, workspaces, permissions
-# Then import
-hubdoc-tool import --mapping mapping.csv
-```
-
-## 📤 Export Documents
-
-### Scan Mode
-```bash
-# Generate export mapping
-hubdoc-tool export --scan
-
-# Export with custom filters
-hubdoc-tool export --scan --project "Client Project" --domain "legal"
-```
-
-### Export Mode
-```bash
-# Export documents using mapping
-hubdoc-tool export --mapping export-mapping.csv
-
-# Export with XML metadata
-hubdoc-tool export --generate-xml-metadata
-```
-
-## 🔌 Plugin Architecture
-
-Support for multiple document sources:
-
-```bash
-# Microsoft OneDrive/SharePoint
-hubdoc-tool --engine onedrive
-
-# Google Drive
-hubdoc-tool --engine googledrive
-
-# AWS S3
-hubdoc-tool --engine s3
-
-# Local filesystem with XML metadata
-hubdoc-tool --engine filesystem --source /path/to/docs
-```
-
-## 📋 CSV Mapping Format
-
-| Column | Description | Example |
-|--------|-------------|---------|
-| File Path | Source file path | `/docs/contract.pdf` |
-| Target Folder | Destination in HubDoc | `Legal/Contracts` |
-| Workspace | Workspace name | `Client Project` |
-| Domain | Business domain | `legal` |
-| Metadata (JSON) | Custom metadata | `{"author": "John", "type": "contract"}` |
-| Permissions | Access control | `users:john,jane\|groups:legal,admin` |
-
-## ⚙️ Configuration Options
-
-### JSON Config (.hubdoc-config.json)
-```json
-{
-  "apiUrl": "https://your.hubdoc.instance/api/v1",
-  "token": "your-jwt-token",
-  "defaultWorkspace": "Main Project",
-  "defaultDomain": "general"
-}
-```
-
-### Environment Variables (.env)
-```bash
-HUBDOC_API_URL=https://your.hubdoc.instance/api/v1
-HUBDOC_TOKEN=your-jwt-token
-```
-
-## 🛠️ Advanced Usage
-
-### Concurrent Processing
-```bash
-# Import with 5 concurrent jobs
-hubdoc-tool import --mapping mapping.csv --concurrent 5
-
-# Export with parallel downloads
-hubdoc-tool export --mapping export.csv --concurrent 3
-```
-
-### Interactive Mode
-```bash
-# Interactive configuration and processing
-hubdoc-tool --interactive
-
-# Interactive engine selection
-hubdoc-tool --interactive --engine
-```
-
-### Permission Management
-```bash
-# Set read permissions
-hubdoc-tool import --source /docs --read-users "john,jane" --read-groups "team"
-
-# Set write permissions
-hubdoc-tool import --source /docs --write-users "admin" --write-groups "managers"
-```
-
-## 🏢 Enterprise Features
-
-- **Workspace Management**: Create and organize workspaces
-- **Folder Hierarchy**: Automatic folder structure creation
-- **Permission Control**: User and group-based access control
-- **Metadata Support**: Rich metadata with JSON format
-- **Domain Classification**: Cross-workspace business domains
-- **Bulk Operations**: Process thousands of documents efficiently
-- **Error Recovery**: Detailed error reporting and retry mechanisms
-- **XML Metadata Export**: Full metadata preservation
-
-## 🔧 API Integration
-
-### HubDoc API Support
-- OAuth2 authentication
-- RESTful API endpoints
-- Pagination handling
-- Rate limiting compliance
-- Error handling and retry logic
-
-### Supported Operations
-- ✅ Workspace CRUD operations
-- ✅ Folder hierarchy management
-- ✅ Document upload/download
-- ✅ Permission management
-- ✅ Metadata operations
-- ✅ Search and filtering
-
-## 📊 Performance
-
-- **Concurrent Processing**: Up to 10 parallel operations
-- **Large Files**: Support for files up to 100MB
-- **Bulk Operations**: Process 1000+ documents efficiently
-- **Memory Optimization**: Streaming for large datasets
-- **Progress Tracking**: Real-time progress indicators
-
-## 🐛 Troubleshooting
-
-### Common Issues
-
-**Connection Failed**
-```bash
-# Test API connection
-hubdoc-tool config --test
-
-# Check configuration
-hubdoc-tool config --show
-```
-
-**Permission Denied**
-```bash
-# Verify token permissions
-hubdoc-tool --debug import --mapping test.csv
-```
-
-**Large File Upload**
-```bash
-# Check file size limits
-hubdoc-tool import --source /docs --skip-large-files
-```
-
-## 📚 Documentation
-
-- [Full Documentation](https://gitlab.com/sinoia/hubdoc-tools/-/blob/main/README.md)
-- [API Reference](https://gitlab.com/sinoia/hubdoc-tools/-/blob/main/docs/)
-- [Plugin Development](https://gitlab.com/sinoia/hubdoc-tools/-/blob/main/docs/plugins.md)
-- [Examples](https://gitlab.com/sinoia/hubdoc-tools/-/tree/main/examples)
-
-## 🤝 Contributing
-
-We welcome contributions! Please see our [Contributing Guide](https://gitlab.com/sinoia/hubdoc-tools/-/blob/main/CONTRIBUTING.md).
-
-## 📄 License
-
-MIT License - see [LICENSE](https://gitlab.com/sinoia/hubdoc-tools/-/blob/main/LICENSE) file for details.
-
-## 🆘 Support
-
-- 🐛 [Report Issues](https://gitlab.com/sinoia/hubdoc-tools/-/issues)
-- 💬 [Discussions](https://gitlab.com/sinoia/hubdoc-tools/-/discussions)
-- 📧 [Email Support](mailto:support@sinoia.com)
-
----
-
-**Made with ❤️ by [Sinoia](https://sinoia.com) - Professional Document Management Solutions**