NSB Core

Bienvenue dans l’écosystème NSB (Néon Spinellia BCK-INC). Ce projet ambitieux vise à révolutionner la gestion des bots Discord en connectant plusieurs bots partenaires au sein d’un réseau commun et unifié.

📖 Comprendre le projet NSB

Le but de NSB est simple : centraliser et standardiser la configuration de vos bots favoris.

Grâce à NSB, un administrateur n’a plus besoin de jongler entre quinze dashboards. Il configure tous les bots membres du réseau depuis un seul endroit :

• soit via des commandes Discord communes, exécutées sur n’importe quel bot membre ;
• soit depuis le panel web NSB, accessible depuis la configuration serveur de n’importe quel bot partenaire.

ℹ️ La standardisation

Chaque bot a sa propre architecture. En interne, trois bots peuvent nommer leur module musical music_sys, audio ou musique_bot. Sur le réseau NSB, le nom est unique (par exemple music).

L’API NSB permet à tout le monde de parler la même langue. Chaque développeur « mappe » donc ses modules internes avec les modules standards de NSB. Cela permet de piloter globalement l’état d’un module, ses sous-modules et ses paramètres de manière unifiée.

📜 Politique de gestion

Pour garantir la cohérence et éviter les conflits entre les bots, une politique stricte s’applique aux modules.

• ✅ Modules standardisés : l’API fournit une liste officielle de fonctions communes (logs, tickets, annonces, music…). Cela évite les doublons et garantit la compatibilité entre bots.
• 🛠️ Modules personnalisés : vous êtes libre de développer des modules propres à votre bot, sans les inscrire sur NSB. Pour profiter de la synchronisation NSB, ils doivent être mappés à un module standard.
• 🔒 Sécurité de la table : pour garantir l’intégrité du système, la gestion globale de la table des modules standards est strictement réservée aux mainteneurs NSB.

🛡️ Informations générales et sécurité

🔐 Authentification

Toutes les requêtes, à l’exception de la route publique /ping, nécessitent obligatoirement ces deux en-têtes HTTP :

Codes d’erreur d’authentification possibles

• 400 ❌ ID du bot appelant manquant (nsb-bot-id).
• 401 ❌ Token d’authentification manquant ou invalide.
• 403 ❌ Bot appelant non autorisé, ou action refusée par le système.

🚦 Rate limit (limitation de requêtes)

Le routeur applique une limitation stricte, basée sur l’authentification, pour protéger l’infrastructure :

• 55 requêtes par seconde pour le trafic authentifié valide.
• 1 requête par seconde pour le trafic non authentifié.

Exemple de réponse en cas de dépassement (HTTP 429) :

{ "rep": { "message": "⛔ Trop de requêtes. Pour plus d'informations, nous vous invitons à lire la documentation : https://www.neon-inc.fr/documentation#table_of_content_heading_1_53.", "code": 429, "retryAfter": 60 } }

🛣️ Architecture de l’API REST

URL de base : https://api.neon-inc.fr/nsb

💻 Exemples d’intégration (Node.js)

🔍 A. Vérifier la standardisation et récupérer un module

require('dotenv').config();

const token = process.env.NSB_TOKEN // Variable d'environnement dans le fichier .env: NSB_TOKEN="TOKEN_RECU_PAR_NEON"

/**
 * Récupère les modules existants sur l'API NSB en fonction des critères donnés.
 * ℹ️ Si aucun module ne correspond, le code de retour sera 404.
 * 
 * @param {Object} client - Instance du client Discord contenant l'ID du bot
 * @param {Object} queryParams - Critères de recherche
 * @param {?string} [queryParams.bot_id] - ID du bot concerné
 * @param {?string} [queryParams.server_id] - ID du serveur Discord
 * @param {?string} [queryParams.module_name] - Nom unique du module
 * @param {?boolean|string} [queryParams.coexist] - Coexistence attendue (true, false, any)
 * @param {?string} [queryParams.color] - Couleur hexadécimale
 * @param {?string} [queryParams.description] - Description exacte
 * @returns {Promise<{ data: any, code: number, message: string }>}
 */
 
async function fetchModules(client, queryParams = {}) {
  const url = new URL('http://api.neon-inc.fr/api/nsb/modules/get');
  Object.entries(queryParams).forEach(([key, value]) => {
    if (value !== undefined && value !== null) url.searchParams.append(key, value);
  });

  const response = await fetch(url.toString(), {
    method: 'GET',
    headers: {
      Authorization: `Bearer ${token}`,
      'nsl-bot-id': client.user.id
    }
  });

  const result = await response.json();
  return { data: result.data, code: result.rep.code, message: result.rep.message };
}

✏️ B. La logique d’upsert (insertion ou mise à jour)

Ce script vérifie l’existence du module et met à jour son état, ou l’insère s’il n’existe pas encore. Idéal pour synchroniser le changement d’état (la fonctionnalité actuellement déployée sur NSB).

require('dotenv').config();

const token = process.env.NSB_TOKEN;

/**
 * Insère un nouveau module via l'API NSB.
 * ⚠️ Tous les champs obligatoires doivent être fournis sous peine de rejet.
 * 
 * @param {Object} client - Instance du client Discord contenant l'ID du bot
 * @param {Object} body - Données à insérer
 * @param {string} body.bot_id - ID du bot concerné - Obligatoire
 * @param {string} body.server_id - ID du serveur Discord - Obligatoire
 * @param {string} body.module_name - Nom unique du module - Obligatoire
 * @param {?boolean} [body.coexist] - Si le module peut coexister avec d'autres - TRUE par défaut
 * @param {?string} [body.description] - Description optionnelle - NULL par défaut
 * @param {?string} [body.color] - Couleur hexadécimale - '#FF7700' par défaut
 * @param {?string} [body.state] - État initial du module ('enabled' ou 'disabled')
 * @returns {Promise<{ data: any, code: number, message: string }>}
 */
 
async function insertModule(client, body) {
  const response = await fetch('http://api.neon-inc.fr/api/nsb/modules/insert', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${token}`,
      'nsl-bot-id': client.user.id,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(body)
  });

  if (!response.ok) return console.error('❌ Erreur POST : ', response.status);
  const result = await response.json();
  return { data: result.data, code: result.rep.code, message: result.rep.message };
}

✏️ C. Mettre à jour un module (PATCH)

Cette fonction modifie les données d’un module déjà existant sur le réseau NSB.

require('dotenv').config();

const token = process.env.NSB_TOKEN;

/**
 * Met à jour un module existant via l'API NSB.
 * ⚠️ Le module doit exister au préalable.
 * 
 * @param {Object} client - Instance du client Discord contenant l'ID du bot
 * @param {Object} body - Données à mettre à jour
 * @param {string} body.bot_id - ID du bot concerné - Obligatoire
 * @param {string} body.server_id - ID du serveur Discord - Obligatoire
 * @param {string} body.module_name - Nom unique du module - Obligatoire
 * @param {Object} body.fields - Champs à mettre à jour (exemple : coexist, description, color, state)
 * @returns {Promise<{ data: any, code: number, message: string }>}
 */
 
async function updateModule(client, body) {
  const response = await fetch('http://api.neon-inc.fr/api/nsb/modules/update', {
    method: 'PATCH',
    headers: {
      Authorization: `Bearer ${token}`,
      'nsb-bot-id': client.user.id,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(body)
  });

  if (!response.ok) return console.error('❌ Erreur PATCH : ', response.status);
  const result = await response.json();
  return { data: result.data, code: result.rep.code, message: result.rep.message };
}

🔌 Le tunnel WebSocket (temps réel)

L’architecture NSB ne fonctionne pas en peer-to-peer entre les bots : l’API agit comme un routeur central (middleman). Elle reçoit une requête HTTP de configuration, l’enregistre en base, puis utilise un tunnel WebSocket persistant pour pousser l’ordre de modification aux bots concernés, en temps réel.

1. Authentification et connexion

Pour ouvrir le tunnel d’écoute, votre bot se connecte à l’URL suivante, avec les en-têtes d’authentification requis.

• Endpoint : wss://api.neon-inc.fr/ws/nsl

2. Maintien de la connexion (heartbeat)

Pour éviter les déconnexions silencieuses (timeouts réseau), le serveur envoie automatiquement un signal ping toutes les 20 secondes.

Avec une bibliothèque standard (comme ws sous Node.js), vous n’avez rien à faire : votre client répond automatiquement par un pong et le tunnel reste ouvert.

3. Structure des données entrantes

Lorsque le routeur vous transmet un ordre, vous recevez un message JSON. Voici sa structure standard :

{
  "action": "ACTION_NAME",
  "module_name": "nom_du_module",
  "server_id": "123456789012345678",
  "reqId": "id_unique_de_la_requete"
}

(Note : reqId correspond à l’ID unique de la requête.)

Action TOGGLE

{
  "action": "TOGGLE",
  "module_name": "logs",
  "server_id": "123",
  "state": "enabled",
  "reqId": "550e8400-e29b-41d4-a716-446655440000"
}

Lorsqu’un utilisateur modifie la configuration depuis le panel NSB ou via un autre bot, le routeur vous pousse l’événement en temps réel. L’action principale est TOGGLE : elle indique à votre bot qu’il doit basculer l’état d’un module (enabled ↔ disabled).

4. L’accusé de réception (ACK)

C’est la mécanique vitale du réseau NSB. Dès que votre bot a fini d’exécuter l’action demandée en interne (par exemple mettre à jour sa base locale), il doit impérativement renvoyer un ACK au routeur via le tunnel WebSocket.

Cela permet au routeur de clôturer la promesse (Promise) en attente et de notifier l’utilisateur de la réussite de l’opération.

{
  "action": "ACK",
  "reqId": "id_unique_de_la_requete",
  "success": true
}

🤝 Adhésion et commandes internes

Les commandes de gestion globale NSB sont accessibles sur Discord, via le préfixe /nsb-core :

• /nsb-core module-listListe les modules standards approuvés par le réseau.
• /nsb-core module-suggestPermet à un développeur de proposer la standardisation d’un nouveau module.
• /nsb-core module-addAjoute un module (réservé aux mainteneurs NSB).
• /nsb-core module-removeSupprime un module (réservé aux mainteneurs NSB).

Pour adhérer officiellement au projet et recevoir vos identifiants d’API, exécutez la commande /register sur les bots coordinateurs et suivez les instructions.

L’équipe NSB