Installer et configurer le SDK Node.js / TypeScript

Ce guide vous accompagne de l'installation du SDK jusqu'à votre premier transfert créé via l'API Coffrify. Vous configurerez votre clé API (cof_live_…, cof_test_… ou cof_sandbox_…), vérifierez votre contexte d'authentification avec GET /v1/me, puis créerez un transfert avec POST /v1/transfers. Tous les exemples reposent sur les champs et codes d'erreur réels de l'API (version 2026-05-14).

Prérequis et installation

Le SDK officiel cible Node.js 18 ou supérieur et fournit des types TypeScript de première classe. Installez-le avec votre gestionnaire de paquets habituel, puis exportez votre clé API dans une variable d'environnement (COFFRIFY_API_KEY) plutôt que de la coder en dur dans vos sources.

• Node.js 18 ou supérieur (LTS 20 et 22 recommandés).
• Une clé API active générée depuis app.coffrify.com/developer. Formats acceptés : cof_live_… (production), cof_test_… (test), cof_sandbox_… (éphémère 24 h), cof_rk_… (restreinte) ou cof_mcp_… (token MCP). Tout autre préfixe est rejeté avec 401 invalid_api_key.
• Installez le SDK via npm install @coffrify/sdk (ou pnpm add @coffrify/sdk / yarn add @coffrify/sdk), puis initialisez le client avec new CoffrifyClient({ apiKey: process.env.COFFRIFY_API_KEY }). Stockez votre clé en variable d'environnement, jamais dans le code source.

// client.ts
import { CoffrifyClient } from '@coffrify/sdk';
 
export const coffrify = new CoffrifyClient({
  apiKey: process.env.COFFRIFY_API_KEY!, // cof_live_… / cof_test_… / cof_sandbox_…
  // baseUrl par défaut : https://api.coffrify.com
});

Authentification : GET /v1/me

Avant tout appel métier, GET /v1/me est le moyen le plus simple de vérifier qu'une clé est valide : il renvoie l'identité du workspace, l'environnement de la clé (live, test ou sandbox) et la liste de ses scopes. Un 401 signifie une clé absente ou invalide, un 403 une clé valide mais sans le scope requis.

curl https://api.coffrify.com/v1/me \
  -H "Authorization: Bearer cof_live_VOTRE_CLE"
# Réponse :
# {
#   "workspace": { "id": "ws_01hx…", "name": "Acme Corp", "slug": "acme-corp", "plan": "pro", "is_personal": false },
#   "api_key":   { "id": "key_01hy…", "key_prefix": "cof_live_…",
#                  "scopes": ["transfers:read", "transfers:write"],
#                  "environment": "live", "last_used_at": "2026-06-06T09:12:34.000Z",
#                  "created_at": "2026-01-15T14:00:00.000Z" },
#   "scopes": ["transfers:read", "transfers:write"],
#   "environment": "live"
# }

Créer un transfert : POST /v1/transfers

Le scope transfers:write est obligatoire. Le seul champ requis est files[] (chaque élément : name, size en octets, optionnellement mime_type). Les champs facultatifs sont : expires_in_hours, max_downloads, password, transfer_title, notes, recipient, allow_download, auto_delete, custom_slug, notify_opens, require_totp, watermark_enabled, watermark_text, geo_allowlist, geo_blocklist, scheduled_for, encryption_mode et encryption_metadata. En environnement sandbox : 10 fichiers max, 10 Mo max/fichier, 5 téléchargements max, 25 transferts/24 h (au-delà : 429 rate_limited). La réponse inclut transfer (id, short_code, status, expires_at, scan_status, encryption_mode), upload_urls[] (file_id, url pré-signée, headers pour le PUT), share_url (https://files.coffrify.com/<short_code>) et totp_secret.

curl -X POST https://api.coffrify.com/v1/transfers \
  -H "Authorization: Bearer cof_live_VOTRE_CLE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "files": [
      { "name": "contrat.pdf", "size": 204800, "mime_type": "application/pdf" }
    ],
    "transfer_title": "Contrat Q2 2026",
    "expires_in_hours": 72,
    "max_downloads": 3,
    "recipient": "client@exemple.fr"
  }'

Erreurs

Le SDK lève une exception typée par catégorie d'erreur, ce qui vous permet de réagir précisément (clé invalide, scope manquant, quota atteint). Le tableau ci-dessous récapitule les cas les plus fréquents et leur résolution.

Voir aussi

• Référence GET /v1/me
• Référence POST /v1/transfers
• Référence GET /v1/transfers
• Guide : créer et gérer vos clés API
• Guide : webhooks et événements
• Guide : pagination par curseur
• Environnements : live, test, sandbox