@sinoia/hubdoc-tools

🚀 Professional command-line tool for HubDoc document management

Outil CLI puissant pour l'import/export en masse de documents avec HubDoc. Importez depuis le système de fichiers local ou des sources cloud, exportez avec structures personnalisées et metadata XML.

📦 Installation

# Installation globale (recommandé)
npm install -g @sinoia/hubdoc-tools

# Vérifier l'installation
hubdoc-tool --version

⚡ Quick Start

1. Configuration (30 secondes)

# Définir les credentials OAuth2
export HUBDOC_API_URL=https://rec.hubdoc.sinoia.cloud
export HUBDOC_OAUTH_CLIENT_ID=your-client-id
export HUBDOC_OAUTH_CLIENT_SECRET=your-client-secret
export HUBDOC_OAUTH_SCOPES="read write"

L'authentification est ensuite 100% automatique ! ✨

2. Import Basique

# Import direct (préserve la structure)
hubdoc-tool import --direct ./invoices

# Ou avec mapping CSV
hubdoc-tool generate-mapping ./documents
hubdoc-tool import --mapping mapping.csv

3. Export

# Générer mapping depuis HubDoc
hubdoc-tool export --scan

# Exporter avec metadata XML
hubdoc-tool export --mapping export-mapping.csv --generate-xml-metadata

🎯 Fonctionnalités Clés

Import

• ✅ Import direct : Structure de dossiers préservée automatiquement
• ✅ Import avec mapping : Contrôle précis via CSV
• ✅ Permissions : Gestion read/write par utilisateur/groupe
• ✅ Metadata : Format simplifié key: value, parent.child: value
• ✅ Sources multiples : Local, OneDrive, Google Drive, AWS S3

Export

• ✅ Scan automatique : Génération du mapping depuis HubDoc
• ✅ Structure personnalisée : Recréation de l'arborescence
• ✅ Metadata XML : Fichiers *_metadata.xml générés automatiquement
• ✅ Filtrage : Par projet, domaine, workspace

Général

• ✅ OAuth2 automatique : Zéro config manuelle, refresh automatique
• ✅ Mode interactif : Assistant guidé étape par étape
• ✅ Validation : Pré-validation des fichiers avant import
• ✅ Concurrent : Import/export parallèle configurable
• ✅ Plugins : Architecture extensible pour sources externes

📚 Documentation

| Sujet | Description | |-------|-------------| | Configuration | OAuth2, variables d'environnement, fichiers config | | Permissions | Format naturel : users:r:email users:w:email | groups:Name | | Metadata | Format simplifié : key: value, parent.child: value | | Exemples | Cas d'usage, scripts, automatisation |

🚀 Commandes Principales

Import

# Import direct (structure préservée)
hubdoc-tool import --direct ./documents

# Import avec mapping CSV
hubdoc-tool import --mapping mapping.csv

# Import depuis source externe
hubdoc-tool --engine onedrive import --source "/Shared Documents"
hubdoc-tool --engine googledrive import --source "My Drive/Invoices"
hubdoc-tool --engine s3 import --source "s3://bucket/docs"

# Options
--concurrent 5          # 5 jobs parallèles
--skip-existing         # Skip documents déjà importés
--dry-run              # Test sans importer
--validate-all         # Validation stricte avant import

Export

# Générer mapping depuis HubDoc
hubdoc-tool export --scan

# Exporter selon mapping
hubdoc-tool export --mapping export-mapping.csv

# Export avec XML metadata
hubdoc-tool export --generate-xml-metadata

# Options
--target ./output      # Dossier de destination
--concurrent 5         # 5 downloads parallèles

Mapping

# Générer mapping depuis dossier local
hubdoc-tool generate-mapping ./documents

# Générer avec sortie spécifique
hubdoc-tool generate-mapping ./docs --output custom-mapping.csv

Mode Interactif

# Lancer l'assistant guidé
hubdoc-tool --interactive
hubdoc-tool -i

📋 Format CSV Mapping

Structure Basique

File Path;Target Folder;Workspace;Metadata (key: value, parent.child: value);Permissions (users:r:email users:w:email | groups:Name);Auto Classify;Status;Error;Document ID;Bulk Upload ID

Exemple Simple

File Path;Target Folder;Workspace;Metadata (key: value, parent.child: value);Permissions (users:r:email users:w:email | groups:Name);Auto Classify;Status;Error;Document ID;Bulk Upload ID
/invoices/inv-001.pdf;Factures/2024;Comptabilité;invoice_number: INV-001, amount: 1500;;true;pending;;;
/contracts/c-a.pdf;Contrats;Juridique;type: service, duration: 24;users:r:[email protected] users:w:[email protected];false;pending;;;

Voir Exemples pour plus de cas d'usage

🔐 Permissions (Format Naturel)

Format

users:email1,email2 | users:w:[email protected] | groups:Group Name | groups:w:Admin Group

Règles

• Sans suffixe = READ par défaut : users:[email protected] | groups:Finance
• :r = READ explicite : users:r:[email protected]
• :w = WRITE : users:w:[email protected] | groups:w:Admins
• Espaces supportés dans les noms de groupes : groups:Senior Management

Exemples

# Lecture seule
users:[email protected],[email protected] | groups:All Staff

# Mixte READ + WRITE
users:[email protected] | users:w:[email protected] | groups:Finance | groups:w:Direction

# Groupes avec espaces et accents
groups:Comptabilité France | groups:w:Présidence Direction

Voir Documentation Permissions pour détails complets

📝 Metadata (Format Simplifié)

Format

key: value, parent.child: value

Exemples

# Simple
invoice_number: INV-001, amount: 1500, paid: true

# Objets imbriqués (notation point)
supplier.name: Acme Corp, supplier.vat: FR123, amount: 2500

# Types auto-détectés
year: 2024, amount: 1500.50, active: true, optional: null

Voir Documentation Metadata pour détails complets

🔌 Plugins / Sources Externes

OneDrive/SharePoint

export ONEDRIVE_CLIENT_ID=your-client-id
export ONEDRIVE_CLIENT_SECRET=your-client-secret
export ONEDRIVE_TENANT_ID=your-tenant-id

hubdoc-tool --engine onedrive import --source "/Shared Documents/Invoices"

Google Drive

export GOOGLE_DRIVE_CLIENT_ID=your-client-id
export GOOGLE_DRIVE_CLIENT_SECRET=your-client-secret
export GOOGLE_DRIVE_CREDENTIALS_PATH=./credentials.json

hubdoc-tool --engine googledrive import --source "My Drive/Documents"

AWS S3

export AWS_ACCESS_KEY_ID=your-key
export AWS_SECRET_ACCESS_KEY=your-secret
export AWS_REGION=us-east-1

hubdoc-tool --engine s3 import --source "s3://my-bucket/documents/"

Voir Exemples pour configuration détaillée

🛠️ Développement

Installation pour Développement

git clone https://github.com/your-org/hubdoc-tools.git
cd hubdoc-tools
npm install
npm run build

Tests

# Tous les tests
npm test

# Tests spécifiques
npm test -- permissions
npm test -- metadata

# Coverage
npm run test:coverage

Build

# Build TypeScript
npm run build

# Watch mode
npm run dev

📖 Documentation Complète

• Configuration Détaillée : OAuth2, env vars, troubleshooting
• Système de Permissions : Format, exemples, cas d'usage
• Gestion des Metadata : Format simplifié, objets imbriqués
• Exemples Pratiques : Scripts, automatisation, cron jobs

🤝 Support & Contributions

Signaler un Bug

Ouvrir une issue

Proposer une Fonctionnalité

Créer une Feature Request

Contribuer

1. Fork le repo
2. Créer une branche : git checkout -b feature/amazing-feature
3. Commit : git commit -m 'Add amazing feature'
4. Push : git push origin feature/amazing-feature
5. Ouvrir une Pull Request

📄 Licence

MIT © [Sinoia]

🎯 Roadmap

• [ ] Support Azure Blob Storage
• [ ] Support Dropbox
• [ ] Interface Web (dashboard)
• [ ] Webhooks pour import temps-réel
• [ ] API REST pour intégrations
• [ ] Support multi-tenant

Made with ❤️ by Sinoia