npm package: @plumsign/sdk
Description: SDK TypeScript officiel pour l'API PlumSign
Author: PlumSign
Latest version: 1.0.0-beta.1

# SDK TypeScript PlumSign

[![npm version](https://badge.fury.io/js/%40plumsign%2Fsdk.svg)](https://badge.fury.io/js/%40plumsign%2Fsdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

SDK TypeScript officiel pour l'API PlumSign V1. Permet l'intégration facile des fonctionnalités de signature de documents dans vos applications.

## 🚀 Installation

```bash
npm install @plumsign/sdk
```

## 📋 Prérequis

- Node.js 16+
- TypeScript 4.5+ (optionnel mais recommandé)
- Une clé API PlumSign (obtenez-la sur [votre tableau de bord](https://app.plumsign.com/api-keys))

## 🔧 Configuration rapide

```typescript
import { PlumSignClient } from '@plumsign/sdk';

// Environnement de production
const client = PlumSignClient.production('psk_live_votre_cle_api');

// Environnement sandbox pour les tests
const client = PlumSignClient.sandbox('sandbox_votre_cle_api');

// Ou utilisation directe
import { createClient } from '@plumsign/sdk';
const client = createClient('votre_cle_api', 'sandbox');
```

## 📚 Guide d'utilisation

### 1. Test de connexion

```typescript
const connectionTest = await client.testConnection();

if (connectionTest.success) {
  console.log(`Connecté en ${connectionTest.responseTime}ms`);
  console.log(`Environnement: ${connectionTest.environment}`);
} else {
  console.error('Erreur:', connectionTest.error);
}
```

### 2. Gestion des documents

#### Créer un document

```typescript
import * as fs from 'fs';

// Depuis un fichier
const fileBuffer = fs.readFileSync('contrat.pdf');
const document = await client.documents.create({
  file: fileBuffer,
  name: 'Contrat de service 2025'
});

// Depuis un File (navigateur)
const document = await client.documents.create({
  file: fileInput.files[0],
  name: 'Contrat client'
});
```

#### Lister les documents

```typescript
// Liste basique
const documents = await client.documents.list();

// Avec filtres et pagination
const documents = await client.documents.list({
  status: 'draft',
  page: 1,
  per_page: 20,
  sort: 'created_at',
  order: 'desc'
});

// Recherche
const documents = await client.documents.search('contrat 2025');

// Récupérer TOUS les documents (pagination automatique)
for await (const document of client.documents.listAll()) {
  console.log(`Document: ${document.name}`);
}
```

#### Opérations sur un document

```typescript
// Récupérer un document
const document = await client.documents.get('doc_123456789');

// Modifier un document
const updated = await client.documents.update('doc_123456789', {
  file_name: 'Nouveau nom.pdf',
  status: 'active'
});

// Supprimer un document
await client.documents.delete('doc_123456789');
```

### 3. Signature de documents

#### Signer avec position automatique

```typescript
const signatureBuffer = fs.readFileSync('signature.png');

const signature = await client.signatures.signDocument('doc_123456789', {
  file: signatureBuffer,
  pageNumber: 1  // Page optionnelle
});
```

#### Signer avec position précise

```typescript
const signature = await client.signatures.signDocumentWithPosition(
  'doc_123456789',
  signatureBuffer,
  {
    pageNumber: 1,
    x: 100,
    y: 200,
    width: 150,
    height: 50
  }
);
```

### 4. Workflow complet : Créer et signer

```typescript
const result = await client.createAndSignDocument(
  pdfFileBuffer,
  signatureFileBuffer,
  {
    documentName: 'Contrat commercial.pdf',
    signaturePosition: {
      pageNumber: 1,
      x: 100,
      y: 650,
      width: 200,
      height: 60
    }
  }
);

console.log('Document:', result.document.id);
console.log('Signature:', result.signature.id);
```

### 5. Gestion des webhooks

#### Créer un webhook

```typescript
const webhook = await client.webhooks.create({
  event: 'document.completed',
  callbackUrl: 'https://mon-app.com/webhooks/documents',
  secret: 'mon-secret-securise',
  active: true
});
```

#### Vérifier la signature d'un webhook

```typescript
import { WebhookUtils } from '@plumsign/sdk';

// Dans votre gestionnaire Express
app.post('/webhooks/plumsign', (req, res) => {
  const signature = req.headers['x-plumsign-signature'];
  const payload = JSON.stringify(req.body);
  const secret = 'mon-secret-securise';

  const isValid = WebhookUtils.verifyWebhookSignature(payload, signature, secret);

  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Traiter le webhook
  const webhookData = WebhookUtils.parseWebhookPayload(payload);
  console.log('Événement reçu:', webhookData.event);

  res.status(200).json({ received: true });
});
```

#### Gestionnaire de webhook automatique

```typescript
const webhookHandler = WebhookUtils.createExpressHandler(
  'mon-secret-securise',
  // Gestionnaire pour document.completed
  async (data) => {
    console.log(`Document ${data.documentId} terminé !`);
    // Votre logique métier ici
  },
  // Gestionnaire pour signature.viewed
  async (data) => {
    console.log(`Signature ${data.signatureId} visualisée`);
  }
);

app.post('/webhooks/plumsign', webhookHandler);
```

### 6. Gestion des clés API

```typescript
// Lister les clés API (nécessite authentification par session)
const apiKeys = await client.apiKeys.list();

// Créer une nouvelle clé API
const newKey = await client.apiKeys.create({
  name: 'Clé pour Mon App',
  validForDays: 90
});

// Révoquer une clé
await client.apiKeys.revoke('key_123456789');
```

### 7. Monitoring et santé

```typescript
// Vérification simple
const isHealthy = await client.health.ping();

// Statut détaillé
const status = await client.health.getDetailedStatus();
console.log(`API healthy: ${status.isHealthy}`);
console.log(`Response time: ${status.responseTime}ms`);

// Monitoring en continu
for await (const healthCheck of client.health.monitorHealth(30000)) {
  console.log(`${healthCheck.timestamp}: ${healthCheck.isHealthy ? '✅' : '❌'}`);
}
```

## 🛠️ Utilitaires

Le SDK inclut de nombreux utilitaires pour faciliter l'utilisation :

```typescript
import { PlumSignHelpers } from '@plumsign/sdk';

// Formatage
PlumSignHelpers.formatFileSize(2457600); // "2.3 MB"
PlumSignHelpers.formatRelativeTime('2025-01-15T10:30:00.000Z'); // "Il y a 2 heures"

// Validation
PlumSignHelpers.getStatusLabel('signed'); // "Signé"
PlumSignHelpers.canSignDocument(document); // true/false

// Retry avec backoff
const result = await PlumSignHelpers.retryWithBackoff(
  () => client.documents.list(),
  3, // tentatives
  1000 // délai initial en ms
);
```

## 🧪 Tests

```bash
npm test
npm run test:watch
```

## 🏗️ Build

```bash
npm run build
```

## 📋 Gestion d'erreurs

Le SDK utilise des classes d'erreur typées pour une gestion précise :

```typescript
import {
  PlumSignError,
  PlumSignAuthenticationError,
  PlumSignRateLimitError
} from '@plumsign/sdk';

try {
  await client.documents.list();
} catch (error) {
  if (error instanceof PlumSignAuthenticationError) {
    console.log('Erreur d\'authentification - vérifiez votre clé API');
  } else if (error instanceof PlumSignRateLimitError) {
    console.log(`Rate limit - retry dans ${error.retryAfter}s`);
  } else if (error instanceof PlumSignError) {
    console.log(`Erreur API: ${error.message} (${error.code})`);
  } else {
    console.log('Erreur inattendue:', error);
  }
}
```

## 🔗 Upload en lot

```typescript
const files = [
  { file: buffer1, name: 'Doc1.pdf' },
  { file: buffer2, name: 'Doc2.pdf' },
  { file: buffer3, name: 'Doc3.pdf' }
];

const results = await client.uploadMultipleDocuments(files);

results.forEach((result, index) => {
  if (result.success) {
    console.log(`✅ ${files[index].name}: ${result.document.id}`);
  } else {
    console.log(`❌ ${files[index].name}: ${result.error}`);
  }
});
```

## 🌍 Environnements

### Production
- URL: `https://api.plumsign.com`
- Clés API: Préfixe `psk_`

### Sandbox
- URL: `https://sandbox-api.plumsign.com`
- Clés API: Préfixe `sandbox_`
- Données de test isolées
- Rate limiting plus flexible

```typescript
// Reset des données sandbox
await client.health.resetSandbox();
```

## 📖 Documentation complète

- [Documentation API](https://docs.plumsign.com/api)
- [Guide d'intégration](https://docs.plumsign.com/integration)
- [Exemples avancés](./examples/)

## 🤝 Support

- 📧 Email: support@plumsign.com
- 📖 Documentation: https://docs.plumsign.com
- 🐛 Issues: https://github.com/plumsign/sdk-typescript/issues

## 📄 Licence

MIT © PlumSign

## 🔄 Changelog

### v1.0.0
- ✨ Version initiale
- 🚀 Support complet de l'API V1
- 📁 Gestion des documents
- ✍️ Signature de documents
- 🔗 Webhooks
- 🔐 Gestion des clés API
- 🏥 Monitoring de santé
- 🛠️ Utilitaires complets
- 🧪 Tests unitaires
- 📚 Documentation complète