@sinoia/hubdoc-tools 1.4.0 → 1.6.0

package/README.md

@@ -1,289 +1,245 @@
-# @sinoia/hubdoc-tools
+# HubDoc Tools CLI
 
-🚀 **Professional command-line tool for HubDoc document management**
+Command-line tool for HubDoc document import/export with multi-source support and OAuth2 authentication.
 
-[![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)
+Two binaries are installed: `hubdoc-tool` (full name) and `hubdoc` (short
+alias). Use `hubdoc` for one-shot CRUD operations and headless / agent
+usage; `hubdoc-tool` keeps the legacy bulk import/export workflows.
 
-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.
+## LLM / Headless usage
 
----
+Single-operation CRUD commands (`hubdoc workspaces|folders|files ...`) are
+designed to be driven by LLMs and CI scripts: every subcommand accepts
+`--json` (structured stdout, structured stderr errors, non-zero exit on
+failure) and refuses to prompt when `--yes` is omitted in `--json` mode.
 
-## 📦 Installation
+See [`docs/llm-usage.md`](./docs/llm-usage.md) for the contract, a full
+command reference, and a worked agent session example.
 
 ```bash
-# Installation globale (recommandé)
-npm install -g @sinoia/hubdoc-tools
-
-# Vérifier l'installation
-hubdoc-tool --version
+hubdoc whoami --json
+hubdoc workspaces ls --json | jq '.[].label'
+hubdoc files upload ./report.pdf --folder=$FOLDER_ID --json
 ```
 
----
-
-## ⚡ Quick Start
+## Installation
 
-### 1. Configuration (30 secondes)
+### Global (NPM)
 
 ```bash
-# 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"
+npm install -g @sinoia/hubdoc-tools
+hubdoc --version
 ```
 
-**L'authentification est ensuite 100% automatique !** ✨
-
-### 2. Import Basique
+### Development
 
 ```bash
-# 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
+# From monorepo root
+npm install
+npm run build:cli
+npm run dev:cli -- --help
 ```
 
-### 3. Export
+## Configuration
 
-```bash
-# Générer mapping depuis HubDoc
-hubdoc-tool export --scan
+### OAuth2 (Automatic)
 
-# Exporter avec metadata XML
-hubdoc-tool export --mapping export-mapping.csv --generate-xml-metadata
+```bash
+export HUBDOC_API_URL=https://your-instance.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"
 ```
 
----
-
-## 🎯 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
+Or create `.env` file with the same variables.
 
-| Sujet | Description |
-|-------|-------------|
-| **[Configuration](./docs/configuration.md)** | OAuth2, variables d'environnement, fichiers config |
-| **[Permissions](./docs/permissions.md)** | Format naturel : `users:r:email users:w:email | groups:Name` |
-| **[Metadata](./docs/metadata.md)** | Format simplifié : `key: value, parent.child: value` |
-| **[Exemples](./docs/examples.md)** | Cas d'usage, scripts, automatisation |
+Authentication is automatic:
+- First run opens browser for authorization
+- Token saved to `.hubdoc-config.json`
+- Auto-refresh before expiration
+- No manual token management required
 
----
+See [OAUTH_SETUP.md](./OAUTH_SETUP.md) for details.
 
-## 🚀 Commandes Principales
+## Commands
 
 ### Import
 
+#### Direct Import
 ```bash
-# Import direct (structure préservée)
+# Preserves folder structure
 hubdoc-tool import --direct ./documents
+```
+
+#### CSV Mapping Import
+```bash
+# Generate mapping
+hubdoc-tool generate-mapping ./documents
 
-# Import avec mapping CSV
+# Edit mapping.csv, then import
 hubdoc-tool import --mapping mapping.csv
+```
 
-# Import depuis source externe
+#### Plugin Import
+```bash
+# From external source (OneDrive, S3, etc.)
 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
+hubdoc-tool --engine googledrive import --source "My Drive/Docs"
+hubdoc-tool --engine s3 import --source "s3://bucket/path"
 ```
 
+Options:
+- `--concurrent N` - Parallel jobs (default: 3)
+- `--skip-existing` - Skip already imported documents
+- `--dry-run` - Validate without importing
+- `--validate-all` - Strict validation
+
 ### Export
 
 ```bash
-# Générer mapping depuis HubDoc
+# Scan HubDoc and generate mapping
 hubdoc-tool export --scan
 
-# Exporter selon mapping
+# Export using mapping
 hubdoc-tool export --mapping export-mapping.csv
 
-# Export avec XML metadata
+# Export with XML metadata
 hubdoc-tool export --generate-xml-metadata
 
-# Options
---target ./output      # Dossier de destination
---concurrent 5         # 5 downloads parallèles
+# Filters
+hubdoc-tool export --scan --project "Project Name"
+hubdoc-tool export --scan --domain "Domain Name"
 ```
 
-### Mapping
+See [EXPORT-DOCUMENTATION.md](./EXPORT-DOCUMENTATION.md) for details.
 
-```bash
-# 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
+### Interactive Mode
 
 ```bash
-# Lancer l'assistant guidé
 hubdoc-tool --interactive
 hubdoc-tool -i
 ```
 
----
+## CSV Mapping Format
 
-## 📋 Format CSV Mapping
-
-### Structure Basique
+### Import Mapping
 
 ```csv
 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
-
+Example:
 ```csv
-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:legal@ex.com users:w:ceo@ex.com;false;pending;;;
+/docs/invoice.pdf;Finance/Invoices;Accounting;invoice_number: INV-001, amount: 1500;users:john@ex.com | groups:Finance;true;pending;;;
 ```
 
-**Voir [Exemples](./docs/examples.md) pour plus de cas d'usage**
+### Export Mapping
 
----
-
-## 🔐 Permissions (Format Naturel)
+```csv
+Document ID,Document Name,Projects (project:folder|project:folder),Download URL,Target Path (editable),Metadata (JSON)
+```
 
-### Format
+## Metadata Format
 
+Simplified key-value format:
 ```
-users:email1,email2 | users:w:admin@ex.com | groups:Group Name | groups:w:Admin Group
+key: value, parent.child: value
 ```
 
-### Règles
-
-- **Sans suffixe** = READ par défaut : `users:john@ex.com | groups:Finance`
-- **:r** = READ explicite : `users:r:viewer@ex.com`
-- **:w** = WRITE : `users:w:editor@ex.com | groups:w:Admins`
-- **Espaces supportés** dans les noms de groupes : `groups:Senior Management`
-
-### Exemples
-
-```csv
-# Lecture seule
-users:john@ex.com,jane@ex.com | groups:All Staff
-
-# Mixte READ + WRITE
-users:viewer@ex.com | users:w:admin@ex.com | groups:Finance | groups:w:Direction
-
-# Groupes avec espaces et accents
-groups:Comptabilité France | groups:w:Présidence Direction
+Examples:
+```
+invoice_number: INV-001, amount: 1500
+supplier.name: Acme, supplier.vat: FR123, amount: 2500
 ```
 
-**Voir [Documentation Permissions](./docs/permissions.md) pour détails complets**
-
----
-
-## 📝 Metadata (Format Simplifié)
+Types auto-detected: numbers, booleans, null.
 
-### Format
+## Permissions Format
 
+Natural format:
 ```
-key: value, parent.child: value
+users:email1,email2 | users:w:admin@ex.com | groups:Group Name | groups:w:Admins
 ```
 
-### Exemples
-
-```csv
-# Simple
-invoice_number: INV-001, amount: 1500, paid: true
-
-# Objets imbriqués (notation point)
-supplier.name: Acme Corp, supplier.vat: FR123, amount: 2500
+- No suffix = READ
+- `:r` = READ explicit
+- `:w` = WRITE
+- Supports spaces in group names
 
-# Types auto-détectés
-year: 2024, amount: 1500.50, active: true, optional: null
+Examples:
+```
+users:viewer@ex.com | users:w:editor@ex.com | groups:Finance
+groups:All Staff | groups:w:Management
 ```
 
-**Voir [Documentation Metadata](./docs/metadata.md) pour détails complets**
+## Plugins
 
----
+Available plugins:
+- **core** - Core DMS integration
+- **o365-mail** - Office 365 Mail via Graph API
+- **filesystem** - Local filesystem
+- **onedrive** - Microsoft OneDrive
+- **googledrive** - Google Drive
+- **dropbox** - Dropbox
+- **aws-s3** - Amazon S3
+- **azure-blob** - Azure Blob Storage
+- **sharepoint** - SharePoint
+- **alfresco** - Alfresco ECM
+- **nuxeo** - Nuxeo DMS
+- **opentext** - OpenText
+- **box** - Box.com
 
-## 🔌 Plugins / Sources Externes
+See [PLUGINS.md](./PLUGINS.md) for plugin development.
 
-### OneDrive/SharePoint
+## Features
 
-```bash
-export ONEDRIVE_CLIENT_ID=your-client-id
-export ONEDRIVE_CLIENT_SECRET=your-client-secret
-export ONEDRIVE_TENANT_ID=your-tenant-id
+### Import
+- Direct import with folder structure preservation
+- CSV mapping for precise control
+- Multi-source support via plugins
+- Permissions (read/write by user/group)
+- Simplified metadata format
+- Concurrent processing
+- Dry-run validation
+- Skip existing documents
+- OAuth2 automatic authentication
 
-hubdoc-tool --engine onedrive import --source "/Shared Documents/Invoices"
-```
+### Export
+- Scan HubDoc to generate mapping
+- Custom folder structure
+- XML metadata generation
+- Filters by project/domain
+- Concurrent downloads
 
-### Google Drive
+## Examples
 
+### Import from Local Filesystem
 ```bash
-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"
+hubdoc-tool import --direct ./invoices --concurrent 5
 ```
 
-### AWS S3
-
+### Import from OneDrive
 ```bash
-export AWS_ACCESS_KEY_ID=your-key
-export AWS_SECRET_ACCESS_KEY=your-secret
-export AWS_REGION=us-east-1
+export ONEDRIVE_CLIENT_ID=your-id
+export ONEDRIVE_CLIENT_SECRET=your-secret
+export ONEDRIVE_TENANT_ID=your-tenant
 
-hubdoc-tool --engine s3 import --source "s3://my-bucket/documents/"
+hubdoc-tool --engine onedrive import --source "/Shared Documents"
 ```
 
-**Voir [Exemples](./docs/examples.md) pour configuration détaillée**
-
----
-
-## 🛠️ Développement
-
-### Installation pour Développement
-
+### Export with Filters
 ```bash
-git clone https://github.com/your-org/hubdoc-tools.git
-cd hubdoc-tools
-npm install
-npm run build
+hubdoc-tool export --scan --project "My Project" --domain "Finance"
+hubdoc-tool export --mapping export.csv --output ./exports
 ```
 
-### Tests
+## Testing
 
 ```bash
-# Tous les tests
-npm test
+# From monorepo root
+npm run test:cli
 
-# Tests spécifiques
+# Specific tests
 npm test -- permissions
 npm test -- metadata
 
@@ -291,62 +247,10 @@ npm test -- metadata
 npm run test:coverage
 ```
 
-### Build
-
-```bash
-# Build TypeScript
-npm run build
-
-# Watch mode
-npm run dev
-```
-
----
-
-## 📖 Documentation Complète
-
-- **[Configuration Détaillée](./docs/configuration.md)** : OAuth2, env vars, troubleshooting
-- **[Système de Permissions](./docs/permissions.md)** : Format, exemples, cas d'usage
-- **[Gestion des Metadata](./docs/metadata.md)** : Format simplifié, objets imbriqués
-- **[Exemples Pratiques](./docs/examples.md)** : Scripts, automatisation, cron jobs
-
----
-
-## 🤝 Support & Contributions
-
-### Signaler un Bug
-
-[Ouvrir une issue](https://github.com/your-org/hubdoc-tools/issues)
-
-### Proposer une Fonctionnalité
-
-[Créer une Feature Request](https://github.com/your-org/hubdoc-tools/issues/new?template=feature_request.md)
-
-### 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
+## Version
 
-- [ ] Support Azure Blob Storage
-- [ ] Support Dropbox
-- [ ] Interface Web (dashboard)
-- [ ] Webhooks pour import temps-réel
-- [ ] API REST pour intégrations
-- [ ] Support multi-tenant
+1.4.0
 
----
+## License
 
-**Made with ❤️ by Sinoia**
+MIT