@bck-inc/nsl-core
Version:
SDK officiel pour l'API NSL (Néon Spinellia LuckyScale) - 100 % fetch natif
142 lines (141 loc) • 6.26 kB
TypeScript
import { NSLCoreEvents, NSLData, NSLFetchBody, NSLInsertBody, NSLSetModuleStateParams, NSLSetModuleStateReturn, NSLState, NSLUpdateBody } from './types';
import { EventEmitter } from 'node:events';
/**
* Options de configuration passées au constructeur de `NSLCore`.
*/
export interface NSLCoreOptions {
/** Jeton JWT ou API‑key délivré par l’API NSL – obligatoire pour la plupart des fonctions. */
token?: string | undefined;
/** ID du bot Discord (envoyé dans le header `nsl-bot-id`) – obligatoire pour la pupart des fonctions. */
botId?: string | undefined;
/** URL racine de l’API NSL. Par défaut : prod. */
baseURL?: string | undefined;
/** Active un log console.debug pour chaque requête HTTP sortante. */
debug?: boolean | undefined;
}
/***************************************************************************
* Classe : NSLCore
* -------------------------------------------------------------------------
* Expose un SDK minimaliste pour consommer l’API NSL depuis n’importe quel
* bot ou service Node.js. Toutes les méthodes retournent une Promesse et
* propagent les erreurs réseau/HTTP sous forme d’`Error` JavaScript.
*
* ⚠️ Comprend un cache mémoire TTL ; aucun back‑off ni suivi de quota
* n’est implémenté. Gérez ces aspects en amont si nécessaire.
***************************************************************************/
export declare class NSLCore extends EventEmitter {
/** Jeton d’auth Bearer utilisé dans le header `Authorization`. */
private readonly token;
/** ID du bot Discord courant – injecté dans `nsl-bot-id`. */
private readonly botId;
/** URL de base (sans `/` final) : ex. `http://…/api/nsl` */
private readonly baseURL;
/** Mode debug ? → log `co` pour chaque requête. */
private readonly debug;
private cache;
/** Durée du cache mémoire (ms) pour les requêtes GET). */
private defaultTTL;
constructor({ token, botId, baseURL, debug }: NSLCoreOptions);
on<E extends keyof NSLCoreEvents>(event: E, listener: (...args: NSLCoreEvents[E]) => void): this;
once<E extends keyof NSLCoreEvents>(event: E, listener: (...args: NSLCoreEvents[E]) => void): this;
emit<E extends keyof NSLCoreEvents>(event: E, ...args: NSLCoreEvents[E]): boolean;
private timeout;
/**
* Mesure la latence RTT de l’API NSL puis émet l’évènement {@link NSLCoreEvents.ping ping}.
*
* @param timeout Timeout max (ms) avant de renvoyer ‑1. 2000 par défaut.
* @returns RTT en millisecondes ou ‑1 si timeout/erreur.
*/
protected getPing(timeout?: number): Promise<number>;
/**
* GET `/modules/get`.
* Les réponses sont automatiquement mises en cache pendant `defaultTTL`.
*
* @param query Filtres bot_id / server_id / module_name …
* @return Objet {@link NSLData} typé ou erreur si la validation échoue
* (évènement `validationError` émis).
*/
fetchModules(query: NSLFetchBody): Promise<NSLData<{
module_name: string;
state: NSLState;
}[]>>;
/**
* Insère un nouveau module : POST `/modules/insert`.
* @returns Promesse d’un objet **{@link NSLData<T\>}**.
*/
insertModule<T = unknown>(body: NSLInsertBody): Promise<NSLData<T>>;
/**
* Met à jour un module existant : PATCH `/modules/update`.
* @returns Promesse d’un objet **{@link NSLData<T\>}**.
*/
updateModule<T = unknown>(body: NSLUpdateBody): Promise<NSLData<T>>;
/**
* Active ou désactive un module.
* Émet toujours `moduleStateChanged` quand l’opération est validée (INSERT/UPDATE).
* @param params Objet métier décrivant le module ciblé.
* @param more { debug?:0\|1, log?:function } – contrôle du verbosité/log.
* @returns Promesse d’un objet **{@link NSLSetModuleStateReturn}**.
*/
setModuleState(params: NSLSetModuleStateParams, more?: {
debug?: 0 | 1;
log?: (msg: string) => void;
}): Promise<NSLSetModuleStateReturn>;
/**
* Vérifie si un module est « standardisé » côté NSL.
* Retourne **true** uniquement quand :
* • l’endpoint répond 200 (code VALID) et
* • la propriété `data.isStandard` vaut `true`.
*/
isStandardized(module_name: string): Promise<boolean>;
/**
* Active un module NSL ― simple sucrage syntaxique autour de
* {@link setModuleState setModuleState()} avec `newState = NSLState.enabled`.
*
* @param p - Identifiants du module à modifier (bot_id, server_id, module_name…).
* Tous les champs de {@link NSLSetModuleStateParams} sauf `newState`.
* @returns La même structure de réponse que {@link setModuleState}.
*
* @example
* ```ts
* await core.enableModule({
* bot_id: client.user!.id,
* server_id: guild.id,
* module_name:"welcome"
* });
* ```
*/
enableModule(p: Omit<NSLSetModuleStateParams, 'newState'>): Promise<NSLSetModuleStateReturn>;
/**
* Désactive un module NSL — équivalent de
* {@link setModuleState setModuleState()} avec `newState = NSLState.disabled`.
*
* @param p - Mêmes paramètres que {@link enableModule} (sans `newState`).
* @returns L’objet renvoyé par {@link setModuleState}.
*
* @example
* ```ts
* await core.disableModule({
* bot_id: client.user!.id,
* server_id: guild.id,
* module_name:"music"
* });
* ```
*/
disableModule(p: Omit<NSLSetModuleStateParams, 'newState'>): Promise<NSLSetModuleStateReturn>;
/**
* Point d’entrée unique pour toutes les requêtes HTTP NSL.
*
* Workflow :
* 1. Vérifie cache mémoire → émet `cacheHit` si trouvé.
* 2. Fait le fetch et émet :
* • `request` juste avant,
* • `response` à la réception des headers.
* 3. Valide le JSON : si échec → `validationError`.
* 4. Stocke dans le cache, retourne la donnée typée.
*
* Toute exception est relayée via `error`.
*
* @internal
*/
private request;
}