@plumsign/sdk

v1.0.0-beta.1

Published

a year ago

SDK TypeScript officiel pour l'API PlumSign

0High
0Medium
0Low

plumsign

plumsign signature document pdf api sdk typescript

SDK TypeScript PlumSign

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

🚀 Installation

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)

🔧 Configuration rapide

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

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

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

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

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

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

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

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

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

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

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

// 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é

// 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 :

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

npm test
npm run test:watch

🏗️ Build

npm run build

📋 Gestion d'erreurs

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

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

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

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

📖 Documentation complète

🤝 Support

📧 Email: [email protected]
📖 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