@communecter/cocolight-api-client 1.0.0

package/README.md

@@ -0,0 +1,194 @@
+# Cocolight API Client
+
+Ce module fournit un client JavaScript prêt à l'emploi pour interagir avec l'API Cocolight. Il encapsule la gestion des appels HTTP, l'authentification, la validation des schémas, la gestion des erreurs, ainsi qu'un ensemble de normalisations des données pour simplifier l'intégration côté client.
+
+## 📦 Installation
+
+```bash
+npm install @communecter/cocolight-api-client
+```
+
+## 🧭 Objectif
+
+Ce client facilite l'intégration avec l'API Cocolight en offrant :
+
+- Des appels simplifiés avec `axios`
+- Un système de validation des entrées/sorties avec AJV
+- La gestion automatique du token d'accès et du token de rafraîchissement
+- Un circuit breaker configurable
+- Un logger intégré avec Pino
+- Des outils de transformation de données compatibles MongoDB/EJSON
+- La gestion des appels API à partir de métadonnées JSON (endpoints)
+
+## 🧱 Architecture
+
+Le projet est structuré autour des fichiers suivants :
+
+```
+src/
+  ApiClient.js         # Client principal : logique d'appel, authentification, validation, transformation
+  EJSONType.js         # Support pour les ObjectID MongoDB avec EJSON
+  endpoints.module.js  # Fichier généré avec les définitions d'endpoints (voir ci-dessous)
+  error.js             # Erreurs personnalisées (ApiClientError, CircuitBreakerError)
+package.json           # Dépendances, scripts, métadonnées
+```
+
+## imports
+
+### ESM
+
+```js
+import ApiClient from "@communecter/cocolight-api-client";
+```
+### CommonJS
+
+```js
+const { default: ApiClient } = require("@communecter/cocolight-api-client");
+```
+
+
+## 🔧 Utilisation de base
+
+```js
+import ApiClient from "@communecter/cocolight-api-client";
+
+const client = new ApiClient({
+  baseURL: "https://mon-api.com",
+  accessToken: "token-jwt",
+  refreshToken: "token-refresh"
+});
+
+client.on("refreshSuccess", (tokens) => {
+  console.log("Token rafraîchi", tokens);
+});
+
+const res = await client.callEndpoint("GET_USER_INFO", {
+  pathParams: { userId: "@userId" }
+});
+
+console.log(res.data);
+```
+
+## 📜 API détaillée
+
+### `new ApiClient(options)`
+
+| Option                     | Type       | Description |
+|---------------------------|------------|-------------|
+| `baseURL` (requis)        | `string`   | URL de base de l'API |
+| `accessToken`             | `string`   | Token d'accès initial |
+| `refreshToken`            | `string`   | Token de rafraîchissement |
+| `refreshUrl`              | `string`   | URL pour rafraîchir le token (défaut : `/api/cocolight/refreshtoken`) |
+| `endpoints`               | `Array`    | Liste des endpoints (par défaut : `endpoints.module.js`) |
+| `timeout`                 | `number`   | Timeout en ms (défaut : `30000`) |
+| `debug`                   | `boolean`  | Active le logger debug (défaut : `false`) |
+| `maxRetries`              | `number`   | Nombre de tentatives max (défaut : `0`) |
+| `circuitBreakerThreshold` | `number`   | Seuil d'erreurs avant blocage (défaut : `5`) |
+| `circuitBreakerResetTime` | `number`   | Délai de réactivation (en ms, défaut : `60000`) |
+| `fromJSONValue`           | `boolean`  | Applique `EJSON.fromJSONValue` sur les réponses (défaut : `true`) |
+
+### Méthodes principales
+
+#### `callEndpoint(constant, data, transform, validate)`
+Effectue un appel à un endpoint défini via `endpoints.module.js`.
+
+- `constant`: nom unique du endpoint
+- `data`: objet avec `pathParams` et données du corps
+- `transform`: `true` (par défaut), `false`, ou fonction de transformation
+- `validate`: `true` (par défaut), permet de valider la réponse via AJV
+
+#### `setToken(token)` / `getToken()`
+Gère le token d'accès.
+
+#### `setRefreshToken(rt)` / `getRefreshToken()`
+Gère le token de rafraîchissement.
+
+#### `resetSession()`
+Réinitialise la session utilisateur.
+
+### Événements
+
+- `refreshSuccess` — déclenché après un rafraîchissement réussi
+- `validationError` — déclenché si AJV détecte des erreurs
+- `sessionReset` — déclenché par `resetSession()`
+
+## 🛠️ Scripts disponibles
+
+Depuis `package.json` :
+
+- `npm run test` — Lance les tests via Jest
+- `npm run exemple` — Lance un exemple
+- `npm run lint` / `lint:fix` — Vérifie et corrige le code avec ESLint
+- `npm run build` — Génère les builds navigateur + Node via Webpack
+- `npm run generate:*` — Génère les modules, documentation ou données de test depuis les fichiers JSON d’API
+
+## 🧩 Dépendances principales
+
+- `axios` & `axios-retry` — pour les appels HTTP robustes
+- `ajv` & `ajv-formats` — pour la validation JSON Schema
+- `ejson` — pour la compatibilité MongoDB (ObjectID, dates...)
+- `pino` — logger performant, compatible navigateur
+- `events` — pour la gestion des événements custom côté client
+
+## 🗃️ Format des endpoints
+
+Chaque endpoint dans `endpoints.module.js` suit le schéma :
+```js
+{
+  constant: "GET_USER_INFO",
+  method: "GET",
+  path: "/api/users/{userId}",
+  auth: "bearer",
+  pathParams: { type: "object", properties: { userId: { type: "string" } }, required: ["userId"] },
+  request: { ...schemaAjv },
+  responses: { "200": { ...schemaAjv } },
+  postActions: [
+    { type: "setToken", path: "accessToken" },
+    { type: "setUserId", path: "user._id" }
+  ]
+}
+```
+
+## 🔒 Sécurité et circuit breaker
+
+Un circuit breaker est intégré :
+- Blocage temporaire après trop d’échecs (`circuitBreakerThreshold`)
+- Réactivation après un délai (`circuitBreakerResetTime`)
+- Journalisation complète avec `pino`
+
+## 🧪 Validation AJV
+
+Chaque appel est validé avant (requête) et après (réponse) via AJV. En cas d’erreur, l’événement `validationError` est déclenché avec les détails.
+
+## 🔄 Rafraîchissement automatique
+
+Si une réponse retourne 401, le client tente automatiquement un appel POST vers `refreshUrl` avec le `refreshToken`, et réessaie l’appel initial si réussi.
+
+## 🧼 Transformation des données
+
+Les réponses sont normalisées :
+- Champs dates, images, IDs MongoDB
+- Structures communes comme `results`, `news`, `notif`, `replies`, etc.
+- Conversion EJSON via `EJSON.fromJSONValue()`
+
+## 🧙 Valeurs dynamiques
+
+Dans les données `pathParams`, il est possible d’utiliser des alias dynamiques :
+
+```js
+pathParams: {
+  userId: "@userId",
+  accessToken: "@accessToken"
+}
+```
+
+Ces valeurs seront automatiquement résolues à partir du contexte du client.
+
+## Licence
+
+MIT
+
+## 👤 Auteur
+
+Thomas Craipeau
+