npm package: @sinoia/hubdoc-tools
Description: Professional command-line tool for HubDoc document management and bulk import/export
Latest version: 1.4.0

# @sinoia/hubdoc-tools

🚀 **Professional command-line tool for HubDoc document management**

[![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)

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

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

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

---

## ⚡ Quick Start

### 1. Configuration (30 secondes)

```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"
```

**L'authentification est ensuite 100% automatique !** ✨

### 2. Import Basique

```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
```

### 3. Export

```bash
# 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](./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 |

---

## 🚀 Commandes Principales

### Import

```bash
# 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

```bash
# 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

```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

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

---

## 📋 Format CSV Mapping

### Structure Basique

```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

```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;;;
```

**Voir [Exemples](./docs/examples.md) pour plus de cas d'usage**

---

## 🔐 Permissions (Format Naturel)

### Format

```
users:email1,email2 | users:w:admin@ex.com | groups:Group Name | groups:w:Admin Group
```

### 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
```

**Voir [Documentation Permissions](./docs/permissions.md) pour détails complets**

---

## 📝 Metadata (Format Simplifié)

### Format

```
key: value, parent.child: value
```

### 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

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

**Voir [Documentation Metadata](./docs/metadata.md) pour détails complets**

---

## 🔌 Plugins / Sources Externes

### OneDrive/SharePoint

```bash
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

```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"
```

### AWS S3

```bash
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](./docs/examples.md) pour configuration détaillée**

---

## 🛠️ Développement

### Installation pour Développement

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

### Tests

```bash
# Tous les tests
npm test

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

# Coverage
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

- [ ] 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**