SDK JavaScript / Node.js

Le SDK JavaScript / Node.js est aujourd'hui le seul SDK officiel de Coffrify réellement disponible. Il enveloppe l'API REST v1 dans une interface idiomatique, gère pour vous l'authentification, les nouvelles tentatives automatiques, la pagination et l'idempotence, et expose des types TypeScript complets. Vous l'utilisez pour créer des transferts de fichiers chiffrés, recevoir des fichiers de tiers via la Réception et piloter vos webhooks, sans avoir à composer manuellement chaque requête HTTP. Cette page couvre l'installation, l'initialisation et les principaux scénarios, avec du code exact et exécutable.

Installation

Le SDK est publié sur npm sous le nom coffrify. Il fonctionne avec Node.js 18 ou supérieur, ainsi que dans les runtimes compatibles fetch (Deno, Bun, environnements edge). Aucune dépendance native n'est requise.

$ npm install @coffrify/sdk

Initialisation

Importez le client par défaut et instanciez-le avec votre clé API. Utilisez une clé cof_test_… pendant le développement, une clé cof_live_… en production, ou une clé cof_sandbox_… pour un environnement de bac à sable isolé qui se purge automatiquement au bout de 24 heures. Ne committez jamais votre clé : chargez-la depuis une variable d'environnement.

import { Coffrify } from '@coffrify/sdk';
 
const coffrify = new Coffrify({
  apiKey: process.env.COFFRIFY_API_KEY, // cof_live_… / cof_test_… / cof_sandbox_…
});

Créer un transfert et téléverser

Un transfert se crée en deux temps. Vous appelez d'abord transfers.create en décrivant les fichiers (nom, taille, type MIME) et les options de partage. Coffrify renvoie l'objet transfer ainsi qu'un tableau upload_urls : une URL signée par fichier. Vous téléversez ensuite chaque contenu avec une requête PUT vers ces URLs, en reprenant les en-têtes fournis. Une fois les fichiers en place, vous partagez le share_url.

import { readFile } from 'node:fs/promises';
 
const file = await readFile('./contrat.pdf');
 
// 1. Créer le transfert
const { transfer, upload_urls, share_url } = await coffrify.transfers.create({
  files: [
    { name: 'contrat.pdf', size: file.byteLength, mime_type: 'application/pdf' },
  ],
  expires_in_hours: 72,
  max_downloads: 3,
  password: 'un-secret-partage',
  recipient: 'client@exemple.fr',
  transfer_title: 'Contrat à signer',
});
 
// 2. Téléverser chaque fichier vers son URL signée (PUT)
for (const slot of upload_urls) {
  await fetch(slot.url, {
    method: 'PUT',
    headers: slot.headers,
    body: file,
  });
}
 
console.log('Lien de partage :', share_url);
// → https://files.coffrify.com/AbC123

L'objet transfer contient notamment id, short_code, status et expires_at. Le champ password est facultatif : s'il est fourni, le destinataire devra le saisir pour accéder au transfert. De même, recipient permet à Coffrify d'envoyer une notification, et max_downloads plafonne le nombre de téléchargements.

Lister, récupérer et supprimer

Le SDK expose les opérations de lecture et de suppression sur vos transferts. list accepte un limit (100 maximum) et un cursor pour la pagination ; get renvoie le détail d'un transfert, fichiers compris ; delete le supprime définitivement.

// Lister (page courante)
const page = await coffrify.transfers.list({ limit: 20 });
console.log(page.data, page.next_cursor, page.has_more);
 
// Récupérer un transfert précis
const one = await coffrify.transfers.get('trf_123');
 
// Supprimer
await coffrify.transfers.delete('trf_123');

Pagination automatique

Plutôt que de gérer le next_cursor à la main, vous pouvez itérer page après page. Tant que has_more vaut true, repassez next_cursor comme cursor à l'appel suivant. Le SDK conserve l'ordre stable des résultats, même si de nouveaux transferts sont créés entre deux pages.

let cursor = undefined;
do {
  const page = await coffrify.transfers.list({ limit: 100, cursor });
  for (const transfer of page.data) {
    console.log(transfer.id, transfer.status);
  }
  cursor = page.has_more ? page.next_cursor : undefined;
} while (cursor);

Idempotence et nouvelles tentatives

Le SDK réessaie automatiquement les erreurs réseau transitoires et les réponses 429 (limite de débit), en respectant l'en-tête Retry-After. Pour que ces reprises restent sûres sur les écritures, fournissez une clé d'idempotence (8 à 255 caractères) : Coffrify garantit alors qu'un même create ne produira jamais deux transferts. Un rejeu renvoie la réponse d'origine, signalée par l'en-tête X-Coffrify-Idempotent-Replay: true.

const transfer = await coffrify.transfers.create(
  {
    files: [{ name: 'rapport.pdf', size: 240_512, mime_type: 'application/pdf' }],
    expires_in_hours: 48,
  },
  { idempotencyKey: 'rapport-2026-06-10-001' },
);

Créer un webhook et vérifier sa signature

Les webhooks notifient votre serveur des événements de transfert. À la création, fournissez une url HTTPS et la liste des events ; sans liste, Coffrify s'abonne par défaut à transfer.downloaded. Le secret de signature (préfixe whsec_) n'est renvoyé qu'une seule fois : stockez-le immédiatement.

const hook = await coffrify.webhooks.create({
  name: 'Notifications production',
  url: 'https://exemple.fr/coffrify/webhooks',
  events: ['transfer.downloaded', 'transfer.expired'],
});
 
console.log(hook.secret); // whsec_…  - affiché une seule fois

À la réception, vérifiez toujours la signature avant de traiter la charge utile. Coffrify signe chaque livraison selon la spécification Standard Webhooks (en-têtes webhook-id, webhook-timestamp et webhook-signature) et fournit en parallèle une signature historique dans l'en-tête X-Coffrify-Signature (format t=<horodatage>,v1=<HMAC-SHA256 hexadécimal>). Dans les deux cas, la tolérance d'horodatage est de 5 minutes. Le SDK encapsule cette vérification :

import express from 'express';
import { Coffrify } from '@coffrify/sdk';
 
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY });
const app = express();
 
// Important : conservez le corps brut pour la vérification
app.post('/coffrify/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  let event;
  try {
    event = coffrify.webhooks.verify({
      payload: req.body,            // Buffer / string brut
      headers: req.headers,         // en-têtes de la requête
      secret: process.env.COFFRIFY_WEBHOOK_SECRET, // whsec_…
    });
  } catch (err) {
    return res.status(400).send('Signature invalide');
  }
 
  if (event.type === 'transfer.downloaded') {
    console.log('Transfert téléchargé :', event.data.transfer_id);
  }
  res.status(200).send('ok');
});

Utiliser une clé de réception (Réception)

La Réception (intake) vous permet de recevoir des fichiers de tiers de façon sécurisée. Vous créez d'abord un point de réception avec intakes.create. La réponse contient une clé publiable (préfixe cip_), sûre côté navigateur et renvoyée une seule fois ; votre clé secrète reste votre propre clé cof_ disposant du scope intake:write. La clé publiable s'utilise dans le navigateur pour déposer des fichiers ; côté serveur, vous listez ensuite les documents reçus.

// 1. Créer un point de réception (côté serveur, clé cof_ avec scope intake:write)
const intake = await coffrify.intakes.create({
  name: 'Pièces dossier client',
  reference_required: true,
  allowed_origins: ['https://portail.exemple.fr'],
});
 
console.log(intake.publishable_key); // cip_live_…  - à transmettre au navigateur, affiché une seule fois
 
// 2. Lister les documents reçus, filtrés par référence métier opaque
const docs = await coffrify.intakes.documents.list(intake.id, {
  reference: 'dossier-4821',
  limit: 50,
});
 
for (const doc of docs.data) {
  console.log(doc.document_id, doc.reference, doc.status);
}

Côté déposant, le dépôt s'effectue depuis le navigateur avec la clé publiable. Le SDK chiffre chaque fichier avant l'envoi, et la clé reste chez vous : ni vos serveurs ni Coffrify ne voient le contenu en clair. Vous ne manipulez côté serveur que des métadonnées (identifiant du document, référence opaque, statut), jamais le contenu déchiffré.

Chiffrement côté client

Par défaut, Coffrify chiffre les contenus au repos côté serveur. Vous pouvez aussi activer un mode de chiffrement de bout en bout : dans ce cas, le SDK chiffre les fichiers avant l'envoi et la clé reste chez vous, le serveur ne lit jamais le clair. Vous n'avez pas à implémenter de cryptographie vous-même : il s'agit d'un réglage d'usage. Lorsque ce mode est activé, certaines fonctions qui nécessiteraient de lire le contenu côté serveur (comme l'analyse antivirus) ne s'appliquent pas, par conception.

Types TypeScript

Le paquet coffrify est écrit en TypeScript et embarque ses propres déclarations : aucun paquet @types séparé n'est nécessaire. Les paramètres d'entrée et les objets de réponse (Transfer, Webhook, Intake, résultats paginés) sont typés, et votre éditeur propose l'autocomplétion ainsi que la vérification au moment de la compilation.

import Coffrify, { type Transfer } from '@coffrify/sdk';
 
const coffrify = new Coffrify({ apiKey: process.env.COFFRIFY_API_KEY! });
 
async function dernierTransfert(): Promise<Transfer | null> {
  const page = await coffrify.transfers.list({ limit: 1 });
  return page.data[0] ?? null;
}

Gestion des erreurs

En cas d'échec, le SDK lève une erreur typée qui reprend la réponse de l'API : un code lisible, un message et un request_id à fournir au support pour tracer l'appel. Encadrez vos écritures et inspectez le code pour réagir précisément (par exemple sur rate_limited ou validation_error).

try {
  await coffrify.transfers.create({ files: [] }); // files[] vide → erreur
} catch (err) {
  console.error(err.code);       // 'validation_error'
  console.error(err.message);    // 'files[] required'
  console.error(err.requestId);  // identifiant à transmettre au support
}