@bck-inc/nsl-core/README.md

SDK officiel pour l'API NSL (Néon Spinellia LuckyScale) - 100 % fetch natif

<div align="center">

# @bck-inc/nsl-core

*SDK TypeScript / Node.js pour l’API **NSL** (Néon Spinellia LuckyScale)*

<a href="https://www.npmjs.com/package/@bck-inc/nsl-core"><img alt="npm" src="https://img.shields.io/npm/v/@bck-inc/nsl-core?color=cb3837&logo=npm" /></a> <a href="https://www.npmjs.com/package/@bck-inc/nsl-core"><img alt="types" src="https://img.shields.io/npm/types/@bck-inc/nsl-core?label=TypeScript" /></a> <img alt="node" src="https://img.shields.io/node/v/@bck-inc/nsl-core?color=5fa04e&logo=node.js" /> <img alt="license" src="https://img.shields.io/npm/l/@bck-inc/nsl-core?color=blue" />

</div>

> **TL;DR :** `import { NSLCore } from '@bck-inc/nsl-core'` → appelez votre premier endpoint en 10 lignes.

---

## ✨ Caractéristiques principales

|                        |                                                                                              |
| :--------------------- | :------------------------------------------------------------------------------------------- |
| **Fetch natif**        | Aucun client HTTP externe — Node ≥ 18 requis (polyfill possible).                            |
| **ESM & CJS**          | Fonctionne avec `import` **et** `require`.                                                   |
| **Type safe**          | Déclarations `.d.ts` + type‑guards runtime.                                                  |
| **Cache TTL (1,5 s)**  | Réponses GET mises en cache pour amortir les floods.                                         |
| **Rate‑limit intégré** | Token‑bucket 200 ms entre requêtes.                                                          |
| **Errors typées**      | `NSLError`, `NSLHTTPError` pour des `catch` ciblés.                                          |
| **Évènements**         | `request`, `response`, `cacheHit`, `validationError`, `moduleStateChanged`, `ping`, `error`. |
| **Zéro config**        | Instanciez, appelez : headers et baseURL gérés pour vous.                                    |

---

## 🚀 Installation

```bash
npm i @bck-inc/nsl-core           # pnpm add @bck-inc/nsl-core / yarn add @bck-inc/nsl-core
```

> **Node ≥ 18** recommandé pour `fetch` et `URL` globaux.
> Sur Node 16 :
>
> ```ts
> import fetch from 'node-fetch';
> // @ts-ignore
> globalThis.fetch = fetch;
> ```

---

## ⚡ Exemple rapide (TS / ESM)

```ts
import { NSLCore, NSLCodes, NSLState } from '@bck-inc/nsl-core';

const core = new NSLCore({
  token: process.env.NSL_TOKEN!,
  botId:  process.env.BOT_ID!,
  debug:  true,
});

core.on('cacheHit', ({ url })  => console.log('⚡ cache', url))
    .on('ping',     ({ rtt })  => console.log('ping', rtt, 'ms'))
    .on('error',    console.error);

// Active le module "welcome" sur un serveur
const res = await core.setModuleState({
  bot_id:     core['botId']!,
  server_id:  '987654321098765432',
  module_name:'welcome',
  newState:   NSLState.enabled,
});

if (res.code === NSLCodes.VALID) console.log('Module OK');
```

---

## 📚 API en bref

### Constructeur

```ts
new NSLCore({ token, botId, baseURL?, debug? });
```

### Méthodes

| Méthode                                     | Effet                                             |
| ------------------------------------------- | ------------------------------------------------- |
| `fetchModules(query?)`                      | GET `/modules/get` + cache TTL                    |
| `insertModule(body)` / `updateModule(body)` | CRUD module                                       |
| `setModuleState(params)`                    | Insert ou update + événement `moduleStateChanged` |
| `enableModule()` / `disableModule()`        | Sucrage autour de `setModuleState`                |
| `isStandardized(name)`                      | Vérifie si « standard » côté API                  |
| `getPing()`                                 | Retourne la latence (ms) et émet `ping`           |

### Évènements (auto‑complétés dans VS Code)

| Event                | Payload                      |
| :------------------- | :--------------------------- |
| `request`            | `{ url, method }`            |
| `response`           | `{ url, status }`            |
| `cacheHit`           | `{ url, ttlLeft }`           |
| `validationError`    | `{ url, issues }`            |
| `moduleStateChanged` | `{ module, type, newState }` |
| `ping`               | `{ rtt }` (`‑1` si timeout)  |
| `error`              | `unknown`                    |

Types & enums détaillés dans [`src/types.ts`](./src/types.ts).

---

## 🧪 Tests

```bash
pnpm test        # Vitest en CI
pnpm test:watch  # watch mode
```

---

## 🤝 Contribuer

1. **Fork** puis `git checkout -b feat/ma-feature`
2. `pnpm i && pnpm test`
3. PR + description claire.

> Toute idée ou bug ? Ouvrez une *Issue* — on répond vite !

---

## 📜 Licence

MIT — © BCK Inc. 2025