@20syldev/api 4.0.0 → 4.1.0

package/README.md

@@ -2,7 +2,7 @@
   <a href="https://api.sylvain.sh"><img src="https://api.sylvain.sh/favicon.ico" alt="Logo" width="25%" height="auto"/></a>
 
   # API Personnelle
-  [![Version](https://custom-icon-badges.demolab.com/badge/Version%20:-v4.0.0-6479ee?logo=api.sylvain.sh&labelColor=23272A)](https://github.com/20syldev/api/releases/latest)
+  [![Version](https://custom-icon-badges.demolab.com/badge/Version%20:-v4.1.0-6479ee?logo=api.sylvain.sh&labelColor=23272A)](https://github.com/20syldev/api/releases/latest)
 </div>
 
 ---
@@ -32,10 +32,10 @@ Pour démarrer un serveur local avec tous les endpoints :
 $ npm run build && npm start
 ```
 ```console
-> @20syldev/api@4.0.0 build
+> @20syldev/api@4.1.0 build
 > tsc
 
-> @20syldev/api@4.0.0 start
+> @20syldev/api@4.1.0 start
 > node dist/app.js
 
 API is running on

package/docs/changelog.md

@@ -0,0 +1,333 @@
+# Changelog
+
+## Exemples curl
+
+```bash
+# dice
+curl -X GET "http://127.0.0.1:3000/v4/dice?roll=2d6%2B3"
+
+# encode
+curl -X GET "http://127.0.0.1:3000/v4/encode?method=base64encode&text=hello"
+curl -X GET "http://127.0.0.1:3000/v4/encode?method=morse&text=SOS"
+curl -X GET "http://127.0.0.1:3000/v4/encode?method=caesar&text=hello&shift=3"
+
+# geo
+curl -X GET "http://127.0.0.1:3000/v4/geo?lat1=48.8566&lon1=2.3522&lat2=43.2965&lon2=5.3698"
+
+# palette
+curl -X GET "http://127.0.0.1:3000/v4/palette?color=%23ff6600&type=triadic"
+
+# statistics
+curl -X GET "http://127.0.0.1:3000/v4/statistics?values=1,2,3,4,5"
+
+# text - stats
+curl -X GET "http://127.0.0.1:3000/v4/text?method=stats&value=Hello+world"
+
+# text - slug
+curl -X GET "http://127.0.0.1:3000/v4/text?method=slug&value=Héllo+Wörld%21"
+
+# text - lorem
+curl -X GET "http://127.0.0.1:3000/v4/text?method=lorem&type=sentences&count=3"
+
+# text - number
+curl -X GET "http://127.0.0.1:3000/v4/text?method=number&value=42&lang=fr"
+
+# validate - luhn
+curl -X GET "http://127.0.0.1:3000/v4/validate?type=luhn&value=4532015112830366"
+
+# validate - iban
+curl -X GET "http://127.0.0.1:3000/v4/validate?type=iban&value=FR7630006000011234567890189"
+
+# validate - email
+curl -X GET "http://127.0.0.1:3000/v4/validate?type=email&value=user%40example.com"
+
+# algorithms - roman
+curl -X GET "http://127.0.0.1:3000/v4/algorithms?method=roman&value=42"
+curl -X GET "http://127.0.0.1:3000/v4/algorithms?method=roman&value=XLII"
+
+# REST v4.2 - jouer un coup (PATCH)
+curl -X PATCH "http://127.0.0.1:3000/v4/tic-tac-toe/{gameId}" \
+  -H "Content-Type: application/json" \
+  -d '{"username":"alice","move":"A1","session":"abc123"}'
+
+# REST v4.2 - forfait (DELETE tic-tac-toe)
+curl -X DELETE "http://127.0.0.1:3000/v4/tic-tac-toe/{gameId}" \
+  -H "Content-Type: application/json" \
+  -d '{"username":"alice","session":"abc123"}'
+
+# REST v4.2 - vider un chat (DELETE chat)
+curl -X DELETE "http://127.0.0.1:3000/v4/chat/{token}" \
+  -H "Content-Type: application/json" \
+  -d '{"username":"alice","session":"abc123"}'
+```
+
+
+
+## v4.2.0
+
+### REST endpoints pour tic-tac-toe et chat
+
+Les endpoints existants ont été étendus avec des méthodes HTTP REST. Uniquement disponible en `v4+`.
+
+#### PATCH `/v4/tic-tac-toe/:game`
+
+Jouer un coup dans une partie.
+
+**Body (JSON) :**
+| Param | Type | Description |
+|-------|------|-------------|
+| `username` | string | Nom du joueur |
+| `move` | string | Case jouée (ex: `A1`) |
+| `session` | string | ID de session |
+
+---
+
+#### DELETE `/v4/tic-tac-toe/:game`
+
+Abandonner une partie (forfeit).
+
+**Body (JSON) :**
+| Param | Type | Description |
+|-------|------|-------------|
+| `username` | string | Nom du joueur |
+| `session` | string | ID de session |
+
+---
+
+#### DELETE `/v4/chat/:token`
+
+Effacer tous les messages d'un chat privé (clear).
+
+**Body (JSON) :**
+| Param | Type | Description |
+|-------|------|-------------|
+| `username` | string | Nom de l'utilisateur |
+| `session` | string | ID de session |
+
+---
+
+### Autres changements v4.2.0
+
+- CORS : ajout de `PATCH`, `DELETE`, `OPTIONS` dans les headers autorisés
+- Nouveau helper `supportsRest()` dans `src/utils/version.ts`
+
+---
+
+## v4.1.0
+
+### Nouveaux endpoints
+
+#### GET `/v4/dice`
+
+Lance des dés en notation RPG.
+
+**Query params :**
+| Param | Requis | Description | Exemple |
+|-------|--------|-------------|---------|
+| `roll` | oui | Notation NdX ou NdX+M | `2d6+3` |
+
+**Note :** le `+` dans l'URL peut être encodé en espace (`2d6 3`) — les deux sont acceptés.
+
+**Réponse :**
+```json
+{
+  "roll": "2d6+3",
+  "count": 2,
+  "sides": 6,
+  "modifier": 3,
+  "results": [4, 2],
+  "total": 9
+}
+```
+
+Limites : 1–100 dés, 2–1000 faces.
+
+---
+
+#### GET `/v4/encode`
+
+Encode ou décode du texte dans différents formats.
+
+**Query params :**
+| Param | Requis | Description |
+|-------|--------|-------------|
+| `method` | oui | Voir liste ci-dessous |
+| `value` | oui | Texte à traiter |
+| `shift` | non | Décalage pour Caesar (défaut : 13) |
+
+**Méthodes disponibles :**
+| `method` | Description |
+|----------|-------------|
+| `base64encode` | Encode en Base64 |
+| `base64decode` | Décode du Base64 |
+| `urlencode` | Encode pour URL |
+| `urldecode` | Décode une URL |
+| `morse` | Texte → Morse |
+| `unmorse` | Morse → Texte |
+| `rot13` | ROT-13 |
+| `caesar` | Chiffre de César (nécessite `shift`) |
+| `binary` | Texte → binaire 8 bits |
+| `unbinary` | Binaire → texte |
+
+---
+
+#### GET `/v4/geo`
+
+Calcule la distance et le cap entre deux coordonnées GPS (Haversine).
+
+**Query params :**
+| Param | Requis | Description |
+|-------|--------|-------------|
+| `lat1` | oui | Latitude point A (-90/+90) |
+| `lon1` | oui | Longitude point A (-180/+180) |
+| `lat2` | oui | Latitude point B |
+| `lon2` | oui | Longitude point B |
+
+**Réponse :**
+```json
+{
+  "distance": { "km": 1214.652, "miles": 754.801, "nauticalMiles": 655.879 },
+  "bearing": { "degrees": 157.34, "cardinal": "SSE" },
+  "from": { "lat": 48.8566, "lon": 2.3522 },
+  "to": { "lat": 43.2965, "lon": 5.3698 }
+}
+```
+
+---
+
+#### GET `/v4/palette`
+
+Génère une palette de couleurs harmonieuse à partir d'une couleur HEX.
+
+**Query params :**
+| Param | Requis | Description |
+|-------|--------|-------------|
+| `color` | oui | Couleur base en HEX (`#RRGGBB`) |
+| `type` | oui | Type de palette |
+
+**Types disponibles :**
+| `type` | Couleurs générées |
+|--------|------------------|
+| `complementary` | 2 couleurs (opposées) |
+| `triadic` | 3 couleurs (120°) |
+| `analogous` | 5 couleurs (-60° à +60°) |
+| `tetradic` | 4 couleurs (90°) |
+| `split-complementary` | 3 couleurs |
+
+Chaque couleur retournée a `hex`, `rgb`, `hsl`.
+
+---
+
+#### GET `/v4/statistics`
+
+Calcule des statistiques descriptives sur une liste de nombres.
+
+**Query params :**
+| Param | Requis | Description |
+|-------|--------|-------------|
+| `values` | oui | Nombres séparés par des virgules |
+
+**Réponse :**
+```json
+{
+  "count": 5,
+  "sum": 15,
+  "min": 1,
+  "max": 5,
+  "range": 4,
+  "mean": 3,
+  "median": 3,
+  "mode": [],
+  "variance": 2,
+  "stddev": 1.414214
+}
+```
+
+---
+
+#### GET `/v4/text`
+
+Manipulation et génération de texte.
+
+**Query params :**
+| Param | Requis | Description |
+|-------|--------|-------------|
+| `action` | oui | Voir liste ci-dessous |
+| `value` | non | Texte source (selon action) |
+| `type` | non | `words`, `sentences`, `paragraphs` (pour `lorem`) |
+| `count` | non | Nombre d'éléments (pour `lorem`, défaut 5) |
+| `lang` | non | `fr` ou `en` (pour `number`) |
+
+**Actions disponibles :**
+| `action` | Description | Params requis |
+|----------|-------------|---------------|
+| `stats` | Statistiques du texte | `value` |
+| `slug` | Convertit en slug URL | `value` |
+| `lorem` | Génère du Lorem Ipsum | `type`, `count` |
+| `number` | Nombre en lettres | `value`, `lang` |
+
+**Réponse `stats` :**
+```json
+{
+  "characters": 42,
+  "charactersNoSpaces": 35,
+  "words": 8,
+  "sentences": 2,
+  "paragraphs": 1,
+  "readingTime": "3s",
+  "mostFrequentChar": "e"
+}
+```
+
+---
+
+#### GET `/v4/validate`
+
+Valide différents formats de données.
+
+**Query params :**
+| Param | Requis | Description |
+|-------|--------|-------------|
+| `type` | oui | `luhn`, `iban`, `email` |
+| `value` | oui | Valeur à valider |
+
+**Réponse `luhn` (numéro de carte) :**
+```json
+{ "valid": true, "value": "4532015112830366" }
+```
+
+**Réponse `iban` :**
+```json
+{ "valid": true, "value": "FR7630006000011234567890189", "country": "FR" }
+```
+
+**Réponse `email` :**
+```json
+{ "valid": true, "value": "user@example.com" }
+```
+
+---
+
+### Ajout à un endpoint existant
+
+#### GET `/v4/algorithms` — conversion de chiffres romains
+
+Nouvelle action `roman` sur l'endpoint algorithms.
+
+**Query params :**
+| Param | Requis | Description |
+|-------|--------|-------------|
+| `method` | oui | `roman` |
+| `value` | oui | Nombre entier (1–3999) ou chiffre romain |
+
+Bidirectionnel : `42` → `XLII`, `XLII` → `42`.
+
+---
+
+### Infrastructure v4.1.0
+
+- **`src/app.ts`** : `export default app` + guard `NODE_ENV !== 'test'` pour les tests d'intégration
+- **`src/config/versions.ts`** : helper `merge()` pour dédoublonner les endpoints par `name`
+- **`tsconfig.test.json`** : étend le tsconfig principal, inclut `src/` et `tests/`
+- **`tests/tsconfig.json`** : pointe vers `tsconfig.test.json` pour la résolution IDE
+- **`package.json`** : script `npm test` avec `--test-force-exit` (requis car `setTimeout` dans chat/tic-tac-toe)

package/package.json

@@ -1,5 +1,5 @@
 {
-    "version": "4.0.0",
+    "version": "4.1.0",
     "name": "@20syldev/api",
     "description": "Node.js API with multiple features. Check the documentation at https://docs.sylvain.sh",
     "main": "dist/app.js",
@@ -8,8 +8,9 @@
         "dev": "tsx watch src/app.ts",
         "start": "node dist/app.js",
         "build": "tsc",
-        "check": "tsc --noEmit && eslint src/",
-        "format": "prettier --write src/ && eslint --fix src/",
+        "check": "tsc --noEmit -p tsconfig.test.json && eslint src/ tests/",
+        "format": "prettier --write src/ tests/ && eslint --fix src/ tests/",
+        "test": "NODE_ENV=test node --import tsx --test --test-force-exit tests/unit/*.test.ts tests/integration/*.test.ts",
         "upgrade:minor": "npm upgrade",
         "upgrade:major": "npx npm-check-updates -u && npm install"
     },
@@ -37,7 +38,7 @@
         "@eslint/js": "^9.24.0",
         "@types/cors": "^2.8.17",
         "@types/express": "^5.0.0",
-        "@types/node": "^22.0.0",
+        "@types/node": "^22.19.17",
         "@types/qrcode": "^1.5.6",
         "@types/uuid": "^10.0.0",
         "eslint": "^9.24.0",

package/src/app.ts

@@ -39,6 +39,10 @@ app.use(getRoutes);
 app.use(postRoutes);
 
 // Start server
-app.listen(env.PORT, () =>
-    console.log(`API is running on\n    - http://127.0.0.1:${env.PORT}\n    - http://localhost:${env.PORT}`),
-);
+if (process.env.NODE_ENV !== 'test') {
+    app.listen(env.PORT, () =>
+        console.log(`API is running on\n    - http://127.0.0.1:${env.PORT}\n    - http://localhost:${env.PORT}`),
+    );
+}
+
+export default app;

package/src/config/versions.ts

@@ -11,10 +11,22 @@ export interface VersionConfig {
     endpoints: {
         get: Endpoint[];
         post: Endpoint[];
+        patch?: Endpoint[];
+        delete?: Endpoint[];
     };
     modules: typeof apiv3 | typeof apiv4;
 }
 
+/**
+ * Merges a base list of endpoints with additions, deduplicating by `name`.
+ * If an addition has the same name as a base entry, it overrides it.
+ */
+const merge = (base: Endpoint[], additions: Endpoint[]): Endpoint[] => {
+    const map = new Map(base.map((e) => [e.name, e]));
+    for (const e of additions) map.set(e.name, e);
+    return [...map.values()];
+};
+
 const v1 = {
     get: [
         { name: 'algorithms', path: '/algorithms?method={algorithm}&value={value}(&value2={value2})' },
@@ -32,9 +44,8 @@ const v1 = {
 };
 
 const v2 = {
-    get: [...v1.get, { name: 'chat', path: '/chat' }],
-    post: [
-        ...v1.post,
+    get: merge(v1.get, [{ name: 'chat', path: '/chat' }]),
+    post: merge(v1.post, [
         {
             name: 'chat',
             children: {
@@ -51,24 +62,25 @@ const v2 = {
                 list: '/tic-tac-toe/list',
             } as Record<string, string>,
         },
-        { name: 'token', path: '/token' },
-    ],
+    ]),
 };
 
 const v3 = {
-    get: [
-        ...v2.get,
+    get: merge(v2.get, [
         { name: 'levenshtein', path: '/levenshtein?str1={string}&str2={string}' },
         {
             name: 'time',
             path: '/time(?type={type}&start={timestamp}&end={timestamp}&format={format}&timezone={timezone})',
         },
-    ],
-    post: [...v2.post, { name: 'hyperplanning', path: '/hyperplanning' }],
+    ]),
+    post: merge(v2.post, [{ name: 'hyperplanning', path: '/hyperplanning' }]),
 };
 
 const v4 = {
-    get: [...v3.get],
+    get: merge(v3.get, [
+        { name: 'dice', path: '/dice?roll={NdX+M}' },
+        { name: 'statistics', path: '/statistics?values={n1,n2,n3,...}' },
+    ]),
     post: [...v3.post],
 };
 

package/src/constants.ts

@@ -1,3 +1,6 @@
+import pkg from '../package.json' with { type: 'json' };
+
+export const APP_VERSION = pkg.version;
 export const MAX_LOG_ENTRIES = 1000;
 export const RATE_LIMIT_WINDOW = 10_000;
 export const RATE_LIMIT_MAX = 50;
@@ -26,3 +29,19 @@ export const STATUS_MESSAGES: Record<number, string> = {
 };
 
 export const START_TIME = Date.now();
+
+export const ROMAN_VALUES: [number, string][] = [
+    [1000, 'M'],
+    [900, 'CM'],
+    [500, 'D'],
+    [400, 'CD'],
+    [100, 'C'],
+    [90, 'XC'],
+    [50, 'L'],
+    [40, 'XL'],
+    [10, 'X'],
+    [9, 'IX'],
+    [5, 'V'],
+    [4, 'IV'],
+    [1, 'I'],
+];

package/src/middleware/cors.ts

@@ -8,7 +8,7 @@ const __dirname = dirname(__filename);
 
 export function setupCors(app: Express): void {
     app.set('trust proxy', 1);
-    app.use(cors({ methods: ['GET', 'POST'] }));
+    app.use(cors({ methods: ['GET', 'POST', 'PATCH', 'DELETE', 'OPTIONS'] }));
     app.use(express.urlencoded({ extended: true }));
     app.use(express.json());
 

package/src/modules/v4/algorithms.ts

@@ -1,4 +1,4 @@
-import { MAX_FACTORIAL, MAX_GCD_VALUE, MAX_PRIME_LIST, MAX_STRING_LENGTH } from '../../constants.js';
+import { MAX_FACTORIAL, MAX_GCD_VALUE, MAX_PRIME_LIST, MAX_STRING_LENGTH, ROMAN_VALUES } from '../../constants.js';
 
 export function anagram(value: string, value2: string): boolean {
     if (!value) throw new Error('First value is required');
@@ -153,3 +153,45 @@ export function reverse(value: string): string {
 
     return value.split('').reverse().join('');
 }
+
+export function roman(value: string): number | string {
+    if (!value) throw new Error('A value is required');
+
+    const num = Number(value);
+    if (!isNaN(num)) {
+        if (!Number.isInteger(num)) throw new Error('Value must be an integer');
+        if (num < 1 || num > 3999) throw new Error('Number must be between 1 and 3999');
+
+        let result = '';
+        let n = num;
+        for (const [val, sym] of ROMAN_VALUES) {
+            while (n >= val) {
+                result += sym;
+                n -= val;
+            }
+        }
+        return result;
+    }
+
+    if (typeof value !== 'string') throw new Error('Value must be a number or a Roman numeral');
+    const upper = value.toUpperCase();
+    if (!/^[MDCLXVI]+$/.test(upper)) throw new Error('Invalid Roman numeral');
+
+    let result = 0;
+    let i = 0;
+    while (i < upper.length) {
+        const two = upper.slice(i, i + 2);
+        const match = ROMAN_VALUES.find(([, sym]) => sym === two);
+        if (match) {
+            result += match[0];
+            i += 2;
+        } else {
+            const one = ROMAN_VALUES.find(([, sym]) => sym === upper[i]);
+            if (!one) throw new Error('Invalid Roman numeral');
+            result += one[0];
+            i += 1;
+        }
+    }
+
+    return result;
+}

package/src/modules/v4/chat.ts

@@ -34,8 +34,10 @@ export default function chat(action: string, params: ChatParams): ChatMessage[]
         return getPrivateChat(params, privateChats);
     } else if (action === 'fetch') {
         return fetchMessages(messages);
+    } else if (action === 'clear') {
+        return clearPrivateChat(params, privateChats, sessions, u);
     } else {
-        throw new Error('Invalid action. Use "message", "private", or "fetch"');
+        throw new Error('Invalid action. Use "message", "private", "fetch", or "clear"');
     }
 }
 
@@ -97,3 +99,24 @@ function fetchMessages(messages: ChatMessage[]): ChatMessage[] {
     if (messages.length > 0) return messages;
     throw new Error('No messages stored.');
 }
+
+function clearPrivateChat(
+    params: ChatParams,
+    privateChats: Record<string, ChatMessage[]>,
+    sessions: Record<string, { user: string; last: number }>,
+    u: string,
+): { message: string } {
+    const { token, session } = params;
+
+    if (!token) throw new Error('Please provide a valid token');
+    if (!session) throw new Error('Please provide a valid session ID');
+    if (sessions[u] && sessions[u].user !== session) {
+        throw new Error('Session ID mismatch');
+    }
+    if (!privateChats[token]) throw new Error('Invalid or expired token.');
+
+    delete privateChats[token];
+    delete sessions[u];
+
+    return { message: 'Private chat cleared successfully' };
+}

package/src/modules/v4/dice.ts

@@ -0,0 +1,39 @@
+export interface DiceResult {
+    roll: string;
+    count: number;
+    sides: number;
+    modifier: number;
+    results: number[];
+    total: number;
+}
+
+export default function dice(roll: string): DiceResult {
+    if (!roll) throw new Error('A roll notation is required (e.g. 2d6+3)');
+    if (typeof roll !== 'string') throw new Error('Roll must be a string');
+
+    const match = /^(\d*)d(\d+)([+-]\d+)?$/i.exec(roll.trim().replace(/\s+/g, '+'));
+    if (!match) throw new Error('Invalid notation. Use NdX or NdX+M (e.g. 2d6+3)');
+
+    const count = match[1] ? parseInt(match[1], 10) : 1;
+    const sides = parseInt(match[2]!, 10);
+    const modifier = match[3] ? parseInt(match[3], 10) : 0;
+
+    if (count < 1 || count > 100) throw new Error('Number of dice must be between 1 and 100');
+    if (sides < 2 || sides > 1000) throw new Error('Number of sides must be between 2 and 1000');
+
+    const results: number[] = [];
+    for (let i = 0; i < count; i++) {
+        results.push(1 + Math.floor(Math.random() * sides));
+    }
+
+    const total = results.reduce((a, b) => a + b, 0) + modifier;
+
+    return {
+        roll: `${count}d${sides}${modifier ? (modifier > 0 ? `+${modifier}` : modifier) : ''}`,
+        count,
+        sides,
+        modifier,
+        results,
+        total,
+    };
+}