@ix-xs/metamob.api 1.0.9 → 2.0.0

package/README.md

@@ -1,10 +1,6 @@
-<div align=center>
-<span style="font-size:30px;">@ix-xs/metamob.api</span><br>
-<br>
-</div>
-
 <img align=right src="https://metamob.fr/img/otomai.png">
 <h1><img src="https://metamob.fr/img/logo.png">Metamob</h1>
+<h3>Gérez vos monstres de l'Eternelle Moisson sur Dofus !</h3>
 <a href="https://metamob.fr/connexion">Connectez-vous</a> ou <a href="https://metamob.fr/inscription">Inscrivez-vous</a> pour profiter des avantages du site :
     <ul>
         <li>Suivez votre avancement dans la quête</li>
@@ -15,106 +11,262 @@
       </ul>
 <br>
 <br>
-<h1>🌐API</h1>
-Une clé API sert à interroger les données de Metamob pour pouvoir les utiliser ailleurs: dans une feuille Google Sheets, sur une application web, dans un bot Discord...
-<br><br>
-Vous trouverez plus d'informations dans <a href="https://metamob.fr/aide/api">la page d'aide</a>.
-<br><br>
-<span style="background-color: DarkRed;">Utiliser une clé API requiert des connaissances en développement. Si vous ne savez pas ce qu'est une API ni comment l'utiliser, ce n'est pas la peine de créer une clé.<br>
-Les clés API sont automatiquement supprimées au bout de 90 jours sans utilisation.</span>
-<br>
-<br>
-<h3> 🗝️Récupérer une clé </h3>
-Pour créer votre clé, rendez-vous dans <a href="https://metamob.fr/utilisateur/mon_profil">votre espace</a> et cliquez sur l'onglet "API".
-Vous devrez saisir un nom. Gardez à l'esprit que vous ne pouvez créer qu'une seule clé API pour l'instant.<br>
-<b>Votre clé sera immédiatement utilisable.</b>
-<br>
-<h2>✨Installation</h2>
 
-`npm install @ix-xs/metamob.api`
-<br>
-<h2>👀Utilisation</h2>
-<h3>1. Créez un nouveau client en fournissant votre clé API Metamob :</h3>
+# 🔥 @ix-xs/metamob.api
+
+<div align="center">
+
+![Node.js](https://img.shields.io/badge/node.js-6DA55F?style=for-the-badge&logo=node.js&logoColor=white)
+![JavaScript](https://img.shields.io/badge/javascript-%23323330.svg?style=for-the-badge&logo=javascript&logoColor=%23F7DF1E)
+![NPM](https://img.shields.io/badge/NPM-%23CB3837.svg?style=for-the-badge&logo=npm&logoColor=white)
+![GitHub](https://img.shields.io/badge/github-%23121011.svg?style=for-the-badge&logo=github&logoColor=white)
+
+**🚀 SDK JavaScript officieux pour l'API Metamob - Dofus 🐉**
+
+*Une librairie performante pour interagir avec l'écosystème Dofus via Metamob*
+
+[![npm version](https://badge.fury.io/js/%40ix-xs%2Fmetamob.api.svg)](https://www.npmjs.com/package/@ix-xs/metamob.api)
+[![Downloads](https://img.shields.io/npm/dm/@ix-xs/metamob.api.svg)](https://www.npmjs.com/package/@ix-xs/metamob.api)
+[![License](https://img.shields.io/npm/l/@ix-xs/metamob.api.svg)](https://github.com/ix-xs/metamob.api/blob/main/LICENSE)
+
+</div>
+
+---
+
+## 🌟 Aperçu
+
+**@ix-xs/metamob.api** est un SDK JavaScript moderne et puissant conçu spécialement pour l'API Metamob, permettant aux développeurs de créer facilement des applications Dofus avec une intégration fluide et performante.
+
+### ✨ Fonctionnalités principales
+
+- 🔥 **Cache intelligent** avec synchronisation automatique disque/mémoire
+- ⚡ **Performances optimales** grâce à un système de cache avancé
+- 🛡️ **Sécurité renforcée** avec écriture atomique des fichiers
+- 🎯 **API moderne** avec support complet TypeScript (jsdoc)
+- 📖 **Documentation complète** avec exemples pratiques
+- 🔄 **Rate limiting** automatique avec retry intelligent
+- 🌐 **Support complet** de toutes les endpoints Metamob
+
+---
+
+## 🚀 Installation rapide
+
+```bash
+# NPM
+npm install @ix-xs/metamob.api
 
-```js
-const MetamobAPI = require("@ix-xs/metamob.api");
+# Yarn
+yarn add @ix-xs/metamob.api
 
-const client = new MetamobAPI({ apiKey:"votre_clé_api" });
+# PNPM
+pnpm add @ix-xs/metamob.api
 ```
 
-<img src="https://user-images.githubusercontent.com/114710533/234149976-268042b8-9300-4fda-92f8-fa781541abad.png">
+### 📋 Prérequis
 
-<br>
-<h3>2. Liste des appels possibles</h3>
-<br>
+- **Node.js** >= 18.0.0
+- **NPM** >= 8.0.0
+- Une clé API Metamob valide
 
-Méthode | options | Description |
-| --- | --- | --- |
-| `getUser()` | `username`:string; | Récupère les informations d'un utilisateur. Non sensible à la casse. |
-| `getUserMonsters()` | `username`:string;<br>{<br>`type?`:string;<br>`monstre?`:string;<br>`etape?`:string;<br>`quantite?`:string;<br>`etat?`:string;<br>} | Récupère les monstres d'un utilisateur. Le nom d'utilisateur n'est pas sensible à la casse. |
-| `getMonsters()` | {<br>`monstre?`:string;<br>`etape?`:string;<br>`type?`:string;<br>} | Récupère les monstres. |
-| `getServers()` | `server?`:string; | Récupère les serveurs. |
-| `getKralamoures()` | {<br>`serveur?`:string;<br>`date_debut?`:string;<br>`date_fin?`:string;<br>} | Récupère les kralamoures. |
-| `getZones()` | `zone?`:string; | Récupère les zones. |
-| `getSouszones()` | `souszone?`:string; | Récupère les sous-zones. |
-| `putUserMonsters()` | `username`:string<br>`uniqueId`:string<br>`body`:Array<{<br>`monstre`:string;<br>`quantite?`:string;<br>`etat?`:string;<br>}> | Met à jour les informations de monstre d'un compte utilisateur.<br>Le champ quantite indique l'opération à effectuer sur la quantité:<br>• Si la quantité renseigner commence par "===", la quantité du monstre sera forcée à cette valeur.<br>• Si la quantité renseigner commence par "+", la quantité du monstre sera incrémenter de cette valeur<br>• Si la quantité renseigner commence par "-", la quantité du monstre sera décrémenter de cette valeur  |
-| `resetUserMonsters()` | `username`:string;<br>`uniqueId`:string; | Réinitialise les monstres sur le compte. Cela signifie que toutes les informations relatives aux monstres seront supprimées !<br>Les monstres seront mis à l'état aucun (ni recherché ni proposé), avec une quantité nulle (0). |
+---
 
-<br>
-<h3>3. Exemples</h3>
-<br>
+## 💡 Utilisation de base
+
+```javascript
+const metamobAPI = require("@ix-xs/metamob.api");
+const client = new metamobAPI("VOTRE_CLÉ_API_METAMOB");
 
+// Utilisation du cache (recommandé)
+console.log(client.cache.servers);   // Serveurs en cache
+console.log(client.cache.monsters);  // Monstres en cache
+console.log(client.cache.areas);     // Zones en cache
 
-```js
-const MetamobAPI = require("@ix-xs/metamob.api");
+// Ou récupération via API
+const servers = await client.getServers();
+const user = await client.getUser("Ix-xs");
+const monsters = await client.getUserMonsters("Ix-xs");
+```
 
-const client = new MetamobAPI({ apiKey:"votre_clé_api" });
+---
 
-// Renvoie les informations de l'utilisateur
-client.getUser("popop").then(console.log);
+## 🏗️ Architecture du cache
 
-// Renvoie les monstres "proposés" dont l'utilisateur possède en + de 1 exemplaire
-client.getUserMonsters("popop", { etat:"propose", quantite:">1" }).then(console.log);
- // Renvoie les monstres de l'utilisateur à l'étape 20
-client.getUserMonsters("popop", { etape:"20" }).then(console.log);
+### 🧠 Cache intelligent multicouche
+
+Notre système de cache combine :
+
+- **📁 Cache disque** : Persistance des données via JSON
+- **💾 Cache mémoire** : Accès ultra-rapide via `require()`
+- **🔄 Synchronisation automatique** : Mise à jour seamless
+- **🛡️ Écriture atomique** : Prévention de la corruption des données
+
+```javascript
+// Le cache est automatiquement synchronisé
+await client.getServers(); // Met à jour le cache si nécessaire
+
+// Accès instantané depuis le cache mémoire
+const servers = client.cache.servers;
+```
 
-// Renvoie la liste de tous les monstres
-client.getMonsters().then(console.log);
-// Renvoie la liste de tous les archimonstres
-client.getMonsters({ type:"archimonstre" }).then(console.log);
+### 📊 Types de cache disponibles
 
-// Renvoie la liste de tous les serveurs
-client.getServers().then(console.log);
-// Renvoie les informations sur le serveur "Tylezia"
-client.getServers("Tylezia").then(console.log);
+| Type | Description | Endpoint |
+|------|-------------|----------|
+| `servers` | Serveurs Dofus | `/serveurs` |
+| `monsters` | Base de données des monstres | `/monstres` |
+| `areas` | Zones de jeu | `/zones` |
+| `subareas` | Sous-zones détaillées | `/sous-zones` |
 
-// Renvoie la liste des ouvertures prévues entre la date du jour et 1 mois plus tard
-client.getKralamoures().then(console.log);
- // Renvoie la liste des ouvertures prévues entre la date du jour et le 01 juin 2024 sur le serveur Tylezia
-client.getKralamoures({ serveur:"Tylezia", date_fin:"2023-06-01" }).then(console.log);
+---
 
-// Renvoie la liste de toutes les zones
-client.getZones().then(console.log); 
-// Renvoie les informations sur la zone Amakna
-client.getZones("Amakna").then(console.log);
+## 🔧 API complète
 
-// Renvoie la liste de toutes les sous-zones.
-client.getSouszones().then(console.log);
-// Renvoie les informations sur la sous-zones Aerdala
-client.getSouszones("Aerdala").then(console.log);
+### 👤 Gestion des utilisateurs
 
-// La quantité du monstre Arakne sera incrémenter de 5 et passera à l'état proposé
-// La quantité du monstre Larchimaide la Poussée passera à 3
-// La quantité du monstre Bouftou Royal sera décrémenter de 2
-client.putUserMonsters("nom_utilisateur", "id_unique_utilisateur", [
-	{ monstre:"Arakne", quantite:"+5", etat:"propose" },
-	{ monstre:"Larchimaide la Poussée", quantite:"===3" },
-	{ monstre:"Bouftou Royal", quantite:"-2" },
-]).then(console.log);
+```javascript
+// Informations utilisateur
+const user = await client.getUser("pseudo");
 
-// Tous les monstres de l'utilisateur seront réinitialiser (quantite à 0 et aucun état)
-client.resestUserMonsters("pseudo_utilisateur", "id_unique_utilisateur").then(console.log);
+// Monstres d'un utilisateur
+const userMonsters = await client.getUserMonsters("pseudo");
+
+// Mise à jour des monstres
+await client.setUserMonsters("pseudo", "unique_id", [
+    { monstre: "Arakne", etat: "recherche", quantite: 5 },
+    { monstre: "Boufton Blanc", etat: "propose", quantite: 2 }
+]);
+
+// Réinitialisation des monstres
+await client.resetUserMonsters("pseudo", "unique_id");
 ```
-<br>
-<br>
-Contactez moi sur Discord si vous rencontrez des difficultés : ix_xs
+
+### 🎮 Données de jeu
+
+```javascript
+// Cache instantané (recommandé)
+const servers = client.cache.servers;
+const monsters = client.cache.monsters;
+const areas = client.cache.areas;
+const subareas = client.cache.subareas;
+
+// Ou via API avec mise à jour du cache
+const freshServers = await client.getServers();
+const freshMonsters = await client.getMonsters();
+const freshAreas = await client.getAreas();
+const freshSubareas = await client.getSubareas();
+```
+
+### 🐙 Kralamoures
+
+```javascript
+// Toutes les ouvertures kralamoures
+const kralamoures = await client.getKralamoures();
+
+// Avec filtres
+const filtered = await client.getKralamoures({
+    server: "Salar",
+    start_date: "2025-01-01",
+    end_date: "2025-12-31"
+});
+```
+
+---
+
+### 📊 Structure de réponse
+
+Toutes les méthodes retournent un objet standardisé :
+
+```javascript
+{
+    ok: boolean,           // Succès de la requête
+    status: number,        // Code de statut HTTP
+    statusText: string,    // Message de statut
+    retryAfter?: number,   // Délai avant retry (si 429)
+    errors?: string[],     // Erreurs éventuelles
+    data?: any            // Données de réponse
+}
+```
+
+---
+
+## ⚡ Optimisations avancées
+
+### 🚀 Cache Strategy
+
+```javascript
+// Préférez toujours le cache pour les données statiques
+const servers = client.cache.servers;  // ✅ Instantané
+const servers = await client.getServers(); // ❌ Plus lent
+
+// Le cache se met à jour automatiquement si nécessaire
+```
+
+### 🔄 Rate Limiting
+
+Le SDK gère automatiquement :
+- **Détection du rate limiting** (429)
+- **Retry automatique** avec backoff
+- **Headers de retry** respectés
+
+---
+
+## 🛠️ Configuration avancée
+
+### 📁 Structure des fichiers cache
+
+```
+.cache/
+├── $.js          # Index des caches
+├── servers.json  # Serveurs
+├── monsters.json # Monstres
+├── areas.json    # Zones
+└── subareas.json # Sous-zones
+```
+
+### 🔧 Personnalisation
+
+Le cache utilise :
+- **write-file-atomic** pour l'écriture sécurisée
+- **Formatage JSON** avec indentation (4 espaces)
+- **Rechargement automatique** du cache Node.js
+
+---
+
+## 🏆 Contributeurs & Support
+
+<div align="center">
+
+### 👨‍💻 Créateur
+
+<img src="https://cdn.discordapp.com/avatars/782307250751406091/a_3f71f1ac5e1664038fdf33c2c408482e.gif" style="border-radius:0.5rem; width:5rem; height:auto">
+
+**Ix-xs**  
+*Développeur auto-didacte & Passionné Dofus*
+
+[![Discord](https://img.shields.io/badge/Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/user/ix-xs)
+[![GitHub](https://img.shields.io/badge/GitHub-181717?style=for-the-badge&logo=github&logoColor=white)](https://github.com/ix-xs)
+
+---
+
+### 💬 Besoin d'aide ?
+
+- 🐛 **Issues** : [GitHub Issues](https://github.com/ix-xs/metamob.api/issues)
+- 💬 **Discord** : `Ix-xs` - Contact direct
+
+</div>
+
+---
+
+<div align="center">
+
+**🌟 Si ce projet vous aide, n'hésitez pas à lui donner une étoile !**
+
+[![Star on GitHub](https://img.shields.io/github/stars/ix-xs/metamob.api.svg?style=social)](https://github.com/ix-xs/metamob.api/stargazers)
+
+*Développé avec ❤️ pour la communauté Dofus*
+
+---
+
+**⚡ Propulsé par l'API Metamob | Optimisé pour la performance | Conçu pour les développeurs**
+
+</div>