SDK et CLI

Frihet offre un SDK TypeScript officiel et une CLI pour gérer votre activité depuis le code ou le terminal. Les deux packages sont publiés sur npm.

Package	npm	Utilisation
@frihet/sdk		SDK pour Node.js / TypeScript
frihet		CLI pour terminal

---

Installation

SDK

npm install @frihet/sdk

CLI

npm install -g frihet

---

Authentification

Vous avez besoin d'une clé API. Générez-la dans Configuration > Sécurité sur app.frihet.io. Les clés commencent par fri_.

SDK

import Frihet from '@frihet/sdk';

const frihet = new Frihet({
  apiKey: 'fri_live_...',
});

Options supplémentaires :

Option	Type	Par défaut	Description
apiKey	string	--	Votre clé API (obligatoire)
baseUrl	string	https://api.frihet.io/v1	URL de base de l'API
timeout	number	30000	Timeout en millisecondes

CLI

frihet login
# Entrez votre clé API interactivement

# Ou directement :
frihet login --key fri_live_...

La clé est enregistrée dans ~/.frihet/config.json avec les permissions 0600. Vous pouvez également utiliser la variable d'environnement FRIHET_API_KEY.

---

SDK — Démarrage rapide

Lister les factures

import Frihet from '@frihet/sdk';

const frihet = new Frihet({ apiKey: 'fri_live_...' });

const page = await frihet.invoices.list({ limit: 10, status: 'paid' });
console.log(`${page.total} factures payées`);

for (const inv of page.data) {
  console.log(`${inv.documentNumber} — ${inv.clientName} — ${inv.total}`);
}

Créer une facture

const invoice = await frihet.invoices.create({
  clientName: 'Acme S.L.',
  items: [
    { description: 'Conseil', quantity: 10, unitPrice: 150 },
    { description: 'Développement web', quantity: 1, unitPrice: 3000 },
  ],
  taxRate: 21,
  dueDate: '2026-04-15',
});

console.log(`Facture ${invoice.documentNumber} créée (${invoice.total} EUR)`);

Rechercher et mettre à jour

// Recherche par texte
const results = await frihet.clients.search('Acme');

// Mettre à jour un client
await frihet.clients.update(results.data[0].id, {
  email: 'nouveau@acme.com',
  fiscalZone: 'peninsula',
});

Marquer une facture comme payée et l'envoyer par e-mail

await frihet.invoices.markPaid('inv_abc123');

await frihet.invoices.send('inv_abc123', {
  recipientEmail: 'cliente@acme.com',
  locale: 'es',
});

---

CLI — Démarrage rapide

Voir l'état de l'activité

frihet status
# Revenu:   EUR 12.500,00
# Dépenses:  EUR 3.200,00
# Net:       EUR 9.300,00

frihet status --month 2026-02

Gérer les factures

# Lister les factures
frihet invoices list --status paid --limit 5

# Rechercher
frihet invoices list -q "Acme"

# Voir le détail
frihet invoices get inv_abc123

# Créer une facture
frihet invoices create --client "Acme S.L." --item "Conseil,10,150" --tax 21

# Marquer comme payée
frihet invoices paid inv_abc123

# Envoyer par e-mail
frihet invoices send inv_abc123 --to cliente@acme.com

Gérer les dépenses

# Lister les dépenses
frihet expenses list --from 2026-01-01 --to 2026-03-31

# Créer une dépense
frihet expenses create --desc "Hébergement mensuel" --amount 49.99 --category software --vendor "Hetzner"

Gérer les clients

# Lister les clients
frihet clients list

# Rechercher
frihet clients list -q "Acme"

# Créer un client
frihet clients create --name "Acme S.L." --email info@acme.com --tax-id B12345678 --zone peninsula

---

Ressources disponibles

Le SDK expose les ressources suivantes en tant que propriétés de l'instance Frihet :

Ressource	Propriété	Méthodes
Factures	frihet.invoices	list, retrieve, create, update, del, search, markPaid, send, pdf, createBatch
Dépenses	frihet.expenses	list, retrieve, create, update, del, search, createBatch
Clients	frihet.clients	list, retrieve, create, update, del, search
Fournisseurs	frihet.vendors	list, retrieve, create, update, del, search
Produits	frihet.products	list, retrieve, create, update, del, search
Devis	frihet.quotes	list, retrieve, create, update, del, search, pdf, send
Webhooks	frihet.webhooks	list, retrieve, create, update, del + verifySignature (statique)
Intelligence	frihet.intelligence	context, summary, monthly, quarterly

Toutes les méthodes list et search renvoient un objet Page<T> :

interface Page<T> {
  data: T[];
  total: number;
  limit: number;
  offset: number;
}

---

Gestion des erreurs

Le SDK lève des erreurs typées pour chaque type d'échec :

import Frihet, { AuthenticationError, NotFoundError, ValidationError, RateLimitError, TimeoutError } from '@frihet/sdk';

try {
  await frihet.invoices.retrieve('no-existe');
} catch (err) {
  if (err instanceof NotFoundError) {
    console.log('Facture introuvable');
  } else if (err instanceof AuthenticationError) {
    console.log('Clé API invalide');
  } else if (err instanceof ValidationError) {
    console.log('Données invalides :', err.message, err.details);
  } else if (err instanceof RateLimitError) {
    console.log(`Limite de taux. Réessayer dans ${err.retryAfter}s`);
  } else if (err instanceof TimeoutError) {
    console.log('Délai d\'attente dépassé');
  }
}

Classe	Code HTTP	Quand
AuthenticationError	401	Clé API invalide ou absente
NotFoundError	404	Ressource introuvable
ValidationError	400 / 422	Données d'entrée invalides
RateLimitError	429	Limite de requêtes dépassée
TimeoutError	--	Pas de réponse dans le délai d'attente configuré
APIError	Autres	Erreur générique du serveur

Réessais automatiques

Le SDK réessaie automatiquement les requêtes qui reçoivent les codes 429 (limite de taux) ou 5xx (erreur de serveur), jusqu'à 3 fois avec un backoff exponentiel. Vous n'avez pas besoin d'implémenter de logique de réessai.

---

Idempotence

Pour les opérations de création, vous pouvez envoyer une idempotencyKey pour éviter les doublons en cas de réessais :

await frihet.invoices.create(
  { clientName: 'Acme S.L.', items: [{ description: 'Service', quantity: 1, unitPrice: 500 }] },
  { idempotencyKey: 'mi-clave-unica-123' }
);

---

Vérifier les webhooks

Le SDK inclut une méthode statique pour vérifier la signature HMAC-SHA256 des webhooks :

import { Webhooks } from '@frihet/sdk';

const isValid = Webhooks.verifySignature(
  rawBody,              // string ou Buffer du corps
  req.headers['x-frihet-signature'],  // en-tête de signature
  'whsec_tu_secreto',   // secret du webhook
);

---

Variables d'environnement

Variable	Description
FRIHET_API_KEY	Clé API (alternative à frihet login en CLI ou au constructeur du SDK)
FRIHET_API_URL	URL de base personnalisée

---

Plus d'informations

• API REST — référence complète des endpoints
• Webhooks — événements et vérification de signature
• Dépôt sur GitHub — code source, issues, contributions
• npm @frihet/sdk | npm frihet