npm package: @florynxlabs/farmlink-sdk
Description: The official Farmlink SDK for interacting with the Farmlink API
Author: Florynx Labs
Latest version: 2.2.0

# @florynxlabs/farmlink-sdk

> Le SDK officiel pour interagir avec l'API FarmLink — la plateforme de gestion agricole intelligente pour l'Afrique.

[![npm](https://img.shields.io/npm/v/@florynxlabs/farmlink-sdk)](https://www.npmjs.com/package/@florynxlabs/farmlink-sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)

---

## Installation

```bash
npm install @florynxlabs/farmlink-sdk
# ou
pnpm add @florynxlabs/farmlink-sdk
# ou
yarn add @florynxlabs/farmlink-sdk
```

---

## Démarrage rapide

### Authentification par API Key

```typescript
import { FarmlinkClient } from "@florynxlabs/farmlink-sdk";

const client = new FarmlinkClient({
  apiKey: "fl_xxxxx_xxxxxxxxxxxxxxxx",
});

// Récupérer le profil utilisateur
const user = await client.me();
console.log(user.name, user.email);
```

### Authentification par Token OAuth

```typescript
const client = new FarmlinkClient({
  accessToken: "votre-access-token-oauth",
});

// Vous pouvez aussi définir le token après la création
client.setAccessToken("nouveau-token");
```

### Configuration personnalisée

```typescript
const client = new FarmlinkClient({
  baseUrl: "https://www.farmlinkmali.com/api/v1", // URL de base (optionnel)
  apiKey: "fl_xxxxx_xxxxxxxxxxxxxxxx",             // OU accessToken
});
```

---

## Modules disponibles

Le SDK est organisé en **3 modules** :

### 🌾 `client.agriculture` — Gestion agricole

```typescript
// Lister toutes les fermes
const fermes = await client.agriculture.getFermes();
// => Ferme[] { id, nom, description, localisation, superficie, typeCulture }

// Lister les parcelles
const parcelles = await client.agriculture.getParcelles();
// => Parcelle[] { id, nom, superficie, localisation, typeSol, statut }

// Lister les cultures
const cultures = await client.agriculture.getCultures();
// => Cultive[] { id, nom, variete, dateSemis, dateRecolte, statut, rendementEstime }
```

### 🛒 `client.marketplace` — Marketplace

```typescript
// Tous les produits du marketplace
const produits = await client.marketplace.getProducts();
// => Product[] { id, title, description, price, unit, quantity, category }

// Vos propres produits
const mesProduits = await client.marketplace.getMyProducts();
```

### 📊 `client.analytics` — Statistiques

```typescript
// Statistiques du tableau de bord
const stats = await client.analytics.getStats();
// => DashboardStats { parcelles, cultures, budget, inventaire, santeGlobale }

console.log(`Total parcelles : ${stats.parcelles.total}`);
console.log(`Superficie totale : ${stats.parcelles.superficieTotale} ha`);
console.log(`Santé globale : ${stats.santeGlobale}%`);
console.log(`Budget du mois : ${stats.budget.mois.solde} F CFA`);
```

---

## Types exportés

Le SDK exporte tous les types TypeScript pour un typage complet :

```typescript
import type {
  User,
  Session,
  Ferme,
  Parcelle,
  Cultive,
  Product,
  DashboardStats,
} from "@florynxlabs/farmlink-sdk";
```

| Type | Description |
|------|-------------|
| `User` | Profil utilisateur (id, name, email, role) |
| `Session` | Session d'authentification complète |
| `Ferme` | Exploitation agricole |
| `Parcelle` | Parcelle de terrain |
| `Cultive` | Culture en cours |
| `Product` | Produit du marketplace |
| `DashboardStats` | Statistiques agrégées du dashboard |

---

## Intégration OAuth avec Better Auth

Le SDK inclut un plugin **Better Auth** prêt à l'emploi pour l'authentification OAuth 2.0 :

```typescript
import { betterAuth } from "better-auth";
import { farmlinkProvider } from "@florynxlabs/farmlink-sdk";

export const auth = betterAuth({
  plugins: [
    farmlinkProvider({
      clientId: process.env.FARMLINK_CLIENT_ID!,
      clientSecret: process.env.FARMLINK_CLIENT_SECRET!,
      // baseUrl: "https://www.farmlinkmali.com" (optionnel, c'est le défaut)
    }),
  ],
});
```

Le plugin configure automatiquement les endpoints OAuth :
- **Authorization** : `/api/oauth/authorize`
- **Token** : `/api/oauth/token`
- **UserInfo** : `/api/oauth/userinfo`
- **Scopes** : `openid`, `profile`, `email`, `read:cultures`

---

## Gestion des erreurs

Le SDK utilise la classe `FarmlinkError` pour les erreurs d'API :

```typescript
import { FarmlinkError } from "@florynxlabs/farmlink-sdk";

try {
  const fermes = await client.agriculture.getFermes();
} catch (error) {
  if (error instanceof FarmlinkError) {
    console.error(`Erreur ${error.status}: ${error.message}`);
    // error.status  → code HTTP (401, 403, 404, 500...)
    // error.message → description de l'erreur
    // error.data    → données supplémentaires (optionnel)
  }
}
```

### Retry automatique

Le SDK gère automatiquement les **rate limits** (HTTP 429) avec un backoff exponentiel :
- 3 tentatives par défaut
- Délai initial de 1 seconde, doublé à chaque retry
- Les erreurs réseau sont aussi retentées automatiquement

---

## Exemple complet

```typescript
import { FarmlinkClient, FarmlinkError } from "@florynxlabs/farmlink-sdk";

async function main() {
  const client = new FarmlinkClient({
    apiKey: "fl_xxxxx_xxxxxxxxxxxxxxxx",
  });

  try {
    // 1. Profil
    const me = await client.me();
    console.log(`Connecté en tant que ${me.name} (${me.role})`);

    // 2. Fermes et parcelles
    const fermes = await client.agriculture.getFermes();
    const parcelles = await client.agriculture.getParcelles();
    console.log(`${fermes.length} ferme(s), ${parcelles.length} parcelle(s)`);

    // 3. Cultures en cours
    const cultures = await client.agriculture.getCultures();
    const enCroissance = cultures.filter((c) => c.statut === "CROISSANCE");
    console.log(`${enCroissance.length} culture(s) en croissance`);

    // 4. Stats
    const stats = await client.analytics.getStats();
    console.log(`Santé globale : ${stats.santeGlobale}%`);

    // 5. Marketplace
    const produits = await client.marketplace.getProducts();
    console.log(`${produits.length} produit(s) disponibles`);
  } catch (error) {
    if (error instanceof FarmlinkError) {
      console.error(`API Error [${error.status}]: ${error.message}`);
    } else {
      console.error("Erreur inattendue:", error);
    }
  }
}

main();
```

---

## Obtenir une API Key

1. Connectez-vous sur [www.farmlinkmali.com](https://www.farmlinkmali.com)
2. Allez dans **Paramètres > Développeur > API Keys**
3. Cliquez sur **Générer une nouvelle clé**
4. Copiez la clé (format `fl_xxxxx_xxxxxxxxxxxxxxxx`)

### Rate Limits

| Type | Limite |
|------|--------|
| API Key standard | 1 000 req/heure |
| API Key premium | 10 000 req/heure |
| OAuth token | 100 req/minute |

---

## Licence

MIT © [Florynx Labs](https://florynxlabs.com)