SDK

SDK JavaScript / Node.js

Installation, configuration, TypeScript types et exemples complets.

Version

Package `@coffrify/sdk` - npm, ESM + CJS, TypeScript natif. Node.js ≥ 18 requis. Deno et Bun supportés.

Installation

terminal

$ npm install @coffrify/sdk
added 1 package in 0.9s

Initialisation

lib/coffrify.tstypescript

import Coffrify from '@coffrify/sdk';

export const coffrify = new Coffrify({
  apiKey: process.env.COFFRIFY_API_KEY!, // requis
  // Optionnel :
  baseURL: 'https://api.coffrify.com',   // par défaut
  timeout: 30_000,                       // ms, défaut 30s
  maxRetries: 2,                         // retries auto sur 429/5xx
  defaultExpiresIn: '7d',                // durée par défaut des transferts
});

Créer un transfert

create-transfer.tstypescript

const { transfer } = await coffrify.transfers.create({
  files: [
    { name: 'rapport-q2.pdf', size: 1_048_576 },
    { name: 'annexes.zip',    size: 4_194_304 },
  ],
  expires_in:  '30d',           // '1h' | '1d' | '7d' | '30d' | '90d'
  password:    'MonMotDePasse', // optionnel
  max_downloads: 10,            // optionnel
  notify_email: 'alice@acme.com', // notification à l'expiration
});

console.log(transfer.id);         // "tr_01JXXXXXXXXXXXXXXXX"
console.log(transfer.short_code); // "X9aB2c"
console.log(transfer.share_url);  // "https://r.coffrify.com/X9aB2c"

Uploader & finaliser

upload.tstypescript

import fs from 'node:fs';

// upload_urls est indexé dans le même ordre que files[]
for (const [i, url] of transfer.upload_urls.entries()) {
  const buffer = fs.readFileSync(filePaths[i]);
  await fetch(url, {
    method: 'PUT',
    body: buffer,
    headers: { 'Content-Type': mimeTypes[i] },
  });
}

// Obligatoire - active le transfert
const finalized = await coffrify.transfers.finalize(transfer.id);
console.log(finalized.status); // "active"

Lister les transferts

const { transfers, has_more, next_cursor } = await coffrify.transfers.list({
  limit:  20,
  cursor: undefined, // pagination cursor-based
  status: 'active',  // 'active' | 'expired' | 'deleted'
});

// Itérateur auto-paginator
for await (const t of coffrify.transfers.listAll()) {
  console.log(t.id, t.status);
}

Supprimer un transfert

await coffrify.transfers.delete('tr_01JXXXXXXXXXXXXXXXX');
// Réponse 204 - le fichier est effacé du stockage sous 60 s.

Gestion des erreurs

error-handling.tstypescript

import { CoffrifyAPIError, CoffrifyRateLimitError } from '@coffrify/sdk';

try {
  await coffrify.transfers.create({ files: [] });
} catch (err) {
  if (err instanceof CoffrifyRateLimitError) {
    console.log('Retry after', err.retryAfter, 's');
  } else if (err instanceof CoffrifyAPIError) {
    console.log(err.status, err.code, err.message);
  } else {
    throw err; // erreur réseau, timeout, etc.
  }
}

Types TypeScript

import type {
  Transfer,
  TransferFile,
  CreateTransferParams,
  TransferStatus,
  WebhookEvent,
} from '@coffrify/sdk';

function handleTransfer(t: Transfer): void {
  console.log(t.id, t.status, t.expires_at);
}