@20syldev/api 4.0.0 → 4.1.0

package/src/modules/v4/text.ts

@@ -0,0 +1,300 @@
+import { MAX_STRING_LENGTH } from '../../constants.js';
+
+const LOREM_WORDS = [
+    'lorem',
+    'ipsum',
+    'dolor',
+    'sit',
+    'amet',
+    'consectetur',
+    'adipiscing',
+    'elit',
+    'sed',
+    'do',
+    'eiusmod',
+    'tempor',
+    'incididunt',
+    'ut',
+    'labore',
+    'et',
+    'dolore',
+    'magna',
+    'aliqua',
+    'enim',
+    'ad',
+    'minim',
+    'veniam',
+    'quis',
+    'nostrud',
+    'exercitation',
+    'ullamco',
+    'laboris',
+    'nisi',
+    'aliquip',
+    'ex',
+    'ea',
+    'commodo',
+    'consequat',
+    'duis',
+    'aute',
+    'irure',
+    'in',
+    'reprehenderit',
+    'voluptate',
+    'velit',
+    'esse',
+    'cillum',
+    'eu',
+    'fugiat',
+    'nulla',
+    'pariatur',
+    'excepteur',
+    'sint',
+    'occaecat',
+    'cupidatat',
+    'non',
+    'proident',
+    'sunt',
+    'culpa',
+    'qui',
+    'officia',
+    'deserunt',
+    'mollit',
+    'anim',
+    'id',
+    'est',
+    'laborum',
+];
+
+const FR_UNITS = [
+    'zéro',
+    'un',
+    'deux',
+    'trois',
+    'quatre',
+    'cinq',
+    'six',
+    'sept',
+    'huit',
+    'neuf',
+    'dix',
+    'onze',
+    'douze',
+    'treize',
+    'quatorze',
+    'quinze',
+    'seize',
+    'dix-sept',
+    'dix-huit',
+    'dix-neuf',
+];
+const FR_TENS = [
+    '',
+    '',
+    'vingt',
+    'trente',
+    'quarante',
+    'cinquante',
+    'soixante',
+    'soixante',
+    'quatre-vingt',
+    'quatre-vingt',
+];
+
+const EN_UNITS = [
+    'zero',
+    'one',
+    'two',
+    'three',
+    'four',
+    'five',
+    'six',
+    'seven',
+    'eight',
+    'nine',
+    'ten',
+    'eleven',
+    'twelve',
+    'thirteen',
+    'fourteen',
+    'fifteen',
+    'sixteen',
+    'seventeen',
+    'eighteen',
+    'nineteen',
+];
+const EN_TENS = ['', '', 'twenty', 'thirty', 'forty', 'fifty', 'sixty', 'seventy', 'eighty', 'ninety'];
+
+function checkText(value: string): void {
+    if (!value) throw new Error('A value is required');
+    if (typeof value !== 'string') throw new Error('Value must be a string');
+    if (value.length > MAX_STRING_LENGTH)
+        throw new Error(`Value must be less than ${MAX_STRING_LENGTH} characters long`);
+}
+
+export interface TextStats {
+    characters: number;
+    charactersNoSpaces: number;
+    words: number;
+    sentences: number;
+    paragraphs: number;
+    readingTime: string;
+    mostFrequentChar: string;
+}
+
+export function stats(value: string): TextStats {
+    checkText(value);
+
+    const characters = value.length;
+    const charactersNoSpaces = value.replace(/\s/g, '').length;
+    const words = value.trim().split(/\s+/).filter(Boolean).length;
+    const sentences = value.split(/[.!?]+/).filter((s) => s.trim().length > 0).length;
+    const paragraphs = value.split(/\n\s*\n/).filter((p) => p.trim().length > 0).length || 1;
+
+    const minutes = words / 200;
+    const readingTime = minutes < 1 ? `${Math.ceil(minutes * 60)}s` : `${Math.round(minutes)}min`;
+
+    const counts = new Map<string, number>();
+    for (const c of value.replace(/\s/g, '').toLowerCase()) counts.set(c, (counts.get(c) ?? 0) + 1);
+    let mostFrequentChar = '';
+    let maxCount = 0;
+    for (const [char, count] of counts) {
+        if (count > maxCount) {
+            mostFrequentChar = char;
+            maxCount = count;
+        }
+    }
+
+    return { characters, charactersNoSpaces, words, sentences, paragraphs, readingTime, mostFrequentChar };
+}
+
+export function slug(value: string): string {
+    checkText(value);
+    return value
+        .normalize('NFD')
+        .replace(/[\u0300-\u036f]/g, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, '')
+        .trim()
+        .replace(/[\s-]+/g, '-');
+}
+
+export function lorem(type: string, count: string): string {
+    const n = Number(count) || 5;
+    if (n < 1 || n > 500) throw new Error('Count must be between 1 and 500');
+
+    const randomWord = (): string => LOREM_WORDS[Math.floor(Math.random() * LOREM_WORDS.length)]!;
+    const randomSentence = (): string => {
+        const length = 5 + Math.floor(Math.random() * 10);
+        const words = Array.from({ length }, randomWord);
+        words[0] = words[0]!.charAt(0).toUpperCase() + words[0]!.slice(1);
+        return words.join(' ') + '.';
+    };
+    const randomParagraph = (): string => {
+        const length = 3 + Math.floor(Math.random() * 5);
+        return Array.from({ length }, randomSentence).join(' ');
+    };
+
+    switch (type) {
+        case 'words':
+            return Array.from({ length: n }, randomWord).join(' ');
+        case 'sentences':
+            return Array.from({ length: n }, randomSentence).join(' ');
+        case 'paragraphs':
+            return Array.from({ length: n }, randomParagraph).join('\n\n');
+        default:
+            throw new Error('Type must be one of: words, sentences, paragraphs');
+    }
+}
+
+function frBelowHundred(n: number): string {
+    if (n < 20) return FR_UNITS[n]!;
+    const t = Math.floor(n / 10);
+    const u = n % 10;
+    if (t === 7 || t === 9) {
+        const base = FR_TENS[t]!;
+        const sub = 10 + u;
+        return base + (base.endsWith('-') ? '' : '-') + FR_UNITS[sub];
+    }
+    if (t === 8 && u === 0) return 'quatre-vingts';
+    if (u === 0) return FR_TENS[t]!;
+    if (u === 1 && t < 8) return FR_TENS[t] + ' et un';
+    return FR_TENS[t] + '-' + FR_UNITS[u];
+}
+
+function frBelowThousand(n: number): string {
+    if (n < 100) return frBelowHundred(n);
+    const h = Math.floor(n / 100);
+    const r = n % 100;
+    let result = '';
+    if (h === 1) result = 'cent';
+    else result = FR_UNITS[h] + ' cent' + (r === 0 ? 's' : '');
+    if (r > 0) result += ' ' + frBelowHundred(r);
+    return result;
+}
+
+function numberToFrench(n: number): string {
+    if (n === 0) return 'zéro';
+    if (n < 0) return 'moins ' + numberToFrench(-n);
+    if (n < 1000) return frBelowThousand(n);
+    if (n < 1_000_000) {
+        const t = Math.floor(n / 1000);
+        const r = n % 1000;
+        const thousands = t === 1 ? 'mille' : frBelowThousand(t) + ' mille';
+        return r === 0 ? thousands : thousands + ' ' + frBelowThousand(r);
+    }
+    if (n < 1_000_000_000) {
+        const m = Math.floor(n / 1_000_000);
+        const r = n % 1_000_000;
+        const millions = m === 1 ? 'un million' : frBelowThousand(m) + ' millions';
+        return r === 0 ? millions : millions + ' ' + numberToFrench(r);
+    }
+    throw new Error('Number must be less than 1 billion');
+}
+
+function enBelowHundred(n: number): string {
+    if (n < 20) return EN_UNITS[n]!;
+    const t = Math.floor(n / 10);
+    const u = n % 10;
+    return u === 0 ? EN_TENS[t]! : EN_TENS[t] + '-' + EN_UNITS[u];
+}
+
+function enBelowThousand(n: number): string {
+    if (n < 100) return enBelowHundred(n);
+    const h = Math.floor(n / 100);
+    const r = n % 100;
+    return r === 0 ? EN_UNITS[h] + ' hundred' : EN_UNITS[h] + ' hundred ' + enBelowHundred(r);
+}
+
+function numberToEnglish(n: number): string {
+    if (n === 0) return 'zero';
+    if (n < 0) return 'minus ' + numberToEnglish(-n);
+    if (n < 1000) return enBelowThousand(n);
+    if (n < 1_000_000) {
+        const t = Math.floor(n / 1000);
+        const r = n % 1000;
+        return r === 0 ? enBelowThousand(t) + ' thousand' : enBelowThousand(t) + ' thousand ' + enBelowThousand(r);
+    }
+    if (n < 1_000_000_000) {
+        const m = Math.floor(n / 1_000_000);
+        const r = n % 1_000_000;
+        return r === 0 ? enBelowThousand(m) + ' million' : enBelowThousand(m) + ' million ' + numberToEnglish(r);
+    }
+    throw new Error('Number must be less than 1 billion');
+}
+
+export function number(value: string, lang: string): string {
+    const n = Number(value);
+    if (isNaN(n)) throw new Error('Value must be a number');
+    if (!Number.isInteger(n)) throw new Error('Value must be an integer');
+    if (Math.abs(n) >= 1_000_000_000) throw new Error('Number must be less than 1 billion');
+
+    switch (lang) {
+        case 'fr':
+            return numberToFrench(n);
+        case 'en':
+            return numberToEnglish(n);
+        default:
+            throw new Error('Lang must be one of: fr, en');
+    }
+}

package/src/modules/v4/tic_tac_toe.ts

@@ -44,11 +44,43 @@ export default function tic_tac_toe(action: string, params: TicTacToeParams): Re
         return playMove(params, games, sessions, u, now);
     } else if (action === 'fetch') {
         return fetchGame(params, games, u);
+    } else if (action === 'forfeit') {
+        return forfeitGame(params, games, sessions);
     } else {
-        throw new Error('Invalid action. Use "play", "fetch", or "list"');
+        throw new Error('Invalid action. Use "play", "fetch", "list", or "forfeit"');
     }
 }
 
+function forfeitGame(
+    params: TicTacToeParams,
+    games: Record<string, TicTacToeGame>,
+    sessions: Record<string, { user: string; last: number }>,
+): Record<string, unknown> {
+    const { game, session } = params;
+
+    if (!game) throw new Error('Please provide a valid game ID');
+    if (!session) throw new Error('Please provide a valid session ID');
+    if (!games[game]) throw new Error('Game not found');
+
+    const u = params.username!.toLowerCase();
+    if (sessions[u] && sessions[u].user !== session) {
+        throw new Error('Session ID mismatch');
+    }
+
+    const players = games[game]!.players;
+    if (!players.includes(u)) throw new Error('You are not a player in this game');
+
+    const winner = players.find((p) => p !== u) ?? null;
+    delete games[game];
+    delete sessions[u];
+
+    return {
+        message: `${params.username} forfeited the game.${winner ? ` ${winner} wins.` : ''}`,
+        winner,
+        loser: params.username,
+    };
+}
+
 function playMove(
     params: TicTacToeParams,
     games: Record<string, TicTacToeGame>,

package/src/modules/v4/validate.ts

@@ -0,0 +1,55 @@
+import { MAX_STRING_LENGTH } from '../../constants.js';
+
+function checkValue(value: string): void {
+    if (!value) throw new Error('A value is required');
+    if (typeof value !== 'string') throw new Error('Value must be a string');
+    if (value.length > MAX_STRING_LENGTH)
+        throw new Error(`Value must be less than ${MAX_STRING_LENGTH} characters long`);
+}
+
+export function luhn(value: string): { valid: boolean; value: string } {
+    checkValue(value);
+    const digits = value.replace(/\s|-/g, '');
+    if (!/^\d+$/.test(digits)) throw new Error('Value must contain only digits, spaces or dashes');
+    if (digits.length < 12 || digits.length > 19) throw new Error('Card number must have between 12 and 19 digits');
+
+    let sum = 0;
+    let alt = false;
+    for (let i = digits.length - 1; i >= 0; i--) {
+        let n = parseInt(digits[i]!, 10);
+        if (alt) {
+            n *= 2;
+            if (n > 9) n -= 9;
+        }
+        sum += n;
+        alt = !alt;
+    }
+
+    return { valid: sum % 10 === 0, value: digits };
+}
+
+export function iban(value: string): { valid: boolean; value: string; country?: string } {
+    checkValue(value);
+    const cleaned = value.replace(/\s/g, '').toUpperCase();
+    if (!/^[A-Z]{2}\d{2}[A-Z0-9]+$/.test(cleaned)) throw new Error('Invalid IBAN format');
+    if (cleaned.length < 15 || cleaned.length > 34) throw new Error('IBAN length must be between 15 and 34 characters');
+
+    const rearranged = cleaned.slice(4) + cleaned.slice(0, 4);
+    const numeric = rearranged
+        .split('')
+        .map((c) => (c >= 'A' && c <= 'Z' ? (c.charCodeAt(0) - 55).toString() : c))
+        .join('');
+
+    let remainder = 0;
+    for (const char of numeric) {
+        remainder = (remainder * 10 + parseInt(char, 10)) % 97;
+    }
+
+    return { valid: remainder === 1, value: cleaned, country: cleaned.slice(0, 2) };
+}
+
+export function email(value: string): { valid: boolean; value: string } {
+    checkValue(value);
+    const regex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    return { valid: regex.test(value), value };
+}

package/src/modules/v4.ts

@@ -3,12 +3,14 @@ export { default as chat } from './v4/chat.js';
 export { default as captcha } from './v4/captcha.js';
 export { default as color } from './v4/color.js';
 export { default as convert } from './v4/convert.js';
+export { default as dice } from './v4/dice.js';
 export { default as domain } from './v4/domain.js';
 export { default as hash } from './v4/hash.js';
 export { default as hyperplanning } from './v4/hyperplanning.js';
 export { default as levenshtein } from './v4/levenshtein.js';
 export { default as personal } from './v4/personal.js';
 export { default as qrcode } from './v4/qrcode.js';
+export { default as statistics } from './v4/statistics.js';
 export { default as tic_tac_toe } from './v4/tic_tac_toe.js';
 export { default as time } from './v4/time.js';
 export { default as token } from './v4/token.js';

package/src/routes/delete.ts

@@ -0,0 +1,72 @@
+import { Router, type Request, type Response } from 'express';
+import { chatStorage, ticTacToeStorage } from '../storage/index.js';
+import { error } from '../utils/response.js';
+import { supportsRest } from '../utils/version.js';
+
+const router = Router();
+
+// Forfeit a tic-tac-toe game (REST: DELETE /tic-tac-toe/:game)
+router.delete('/:version/tic-tac-toe/:game', (req: Request, res: Response) => {
+    if (!supportsRest(req)) {
+        error(res, 405, 'DELETE is only supported in v4+.', `${req.version}/tic-tac-toe`);
+        return;
+    }
+
+    const game = req.params.game as string;
+    const { username, session } = (req.body as Record<string, string>) || {};
+
+    if (!username) {
+        error(res, 400, 'Please provide a username (?username={username})');
+        return;
+    }
+    if (!session) {
+        error(res, 400, 'Please provide a valid session ID (&session={ID})');
+        return;
+    }
+
+    try {
+        const result = req.module.tic_tac_toe('forfeit', {
+            username,
+            session,
+            game,
+            storage: ticTacToeStorage,
+        });
+        res.jsonResponse(result);
+    } catch (err) {
+        error(res, 400, (err as Error).message);
+    }
+});
+
+// Clear a private chat (REST: DELETE /chat/:token)
+router.delete('/:version/chat/:token', (req: Request, res: Response) => {
+    if (!supportsRest(req)) {
+        error(res, 405, 'DELETE is only supported in v4+.', `${req.version}/chat`);
+        return;
+    }
+
+    const token = req.params.token as string;
+    const { username, session } = (req.body as Record<string, string>) || {};
+
+    if (!username) {
+        error(res, 400, 'Please provide a username (?username={username})');
+        return;
+    }
+    if (!session) {
+        error(res, 400, 'Please provide a valid session ID (&session={ID})');
+        return;
+    }
+
+    try {
+        const result = req.module.chat('clear', {
+            username,
+            token,
+            session,
+            storage: chatStorage,
+        });
+        res.jsonResponse(result);
+    } catch (err) {
+        error(res, 400, (err as Error).message);
+    }
+});
+
+export default router;

package/src/routes/get.ts

@@ -18,6 +18,7 @@ router.get('/:version', (req: Request, res: Response) => {
 
     const endpoints = Object.keys(versionConfig.endpoints).reduce<Record<string, unknown>>((acc, method) => {
         const endpointList = versionConfig.endpoints[method as keyof typeof versionConfig.endpoints];
+        if (!endpointList) return acc;
         acc[method] = endpointList
             .filter(({ name }: { name: string }) => name !== 'website')
             .sort((a: { name: string }, b: { name: string }) => a.name.localeCompare(b.name))
@@ -149,6 +150,29 @@ router.get('/:version/domain', (req: Request, res: Response) => {
     }
 });
 
+// RPG Dice roller
+router.get('/:version/dice', (req: Request, res: Response) => {
+    const { roll } = req.query;
+    const { version } = req.params;
+
+    const dice = (req.module as { dice?: (r: string) => unknown }).dice;
+    if (!dice) {
+        error(res, 404, `Endpoint not available in ${version}.`, `${version}/dice`);
+        return;
+    }
+    if (!roll) {
+        error(res, 400, 'Please provide a roll notation (?roll=2d6+3)', `${version}/dice`);
+        return;
+    }
+
+    try {
+        const result = dice(roll as string);
+        res.jsonResponse(result);
+    } catch (err) {
+        error(res, 400, (err as Error).message, `${req.version}/dice`);
+    }
+});
+
 // GET planning error
 router.get('/:version/hyperplanning', (_req: Request, res: Response) => {
     error(res, 405, 'This endpoint only supports POST requests.');
@@ -222,6 +246,29 @@ router.get('/:version/qrcode', async (req: Request, res: Response) => {
     }
 });
 
+// Statistics on a list of numbers
+router.get('/:version/statistics', (req: Request, res: Response) => {
+    const { values } = req.query;
+    const { version } = req.params;
+
+    const statistics = (req.module as { statistics?: (v: string) => unknown }).statistics;
+    if (!statistics) {
+        error(res, 404, `Endpoint not available in ${version}.`, `${version}/statistics`);
+        return;
+    }
+    if (!values) {
+        error(res, 400, 'Please provide a list of values (?values=1,2,3)', `${version}/statistics`);
+        return;
+    }
+
+    try {
+        const result = statistics(values as string);
+        res.jsonResponse(result);
+    } catch (err) {
+        error(res, 400, (err as Error).message, `${req.version}/statistics`);
+    }
+});
+
 // GET tic-tac-toe errors
 router.get('/:version/tic-tac-toe', (_req: Request, res: Response) => {
     error(res, 405, 'This endpoint only supports POST requests.');

package/src/routes/index.ts

@@ -2,7 +2,7 @@ import { Router, type Request, type Response } from 'express';
 import { versions } from '../config/versions.js';
 import { ipLimits } from '../storage/index.js';
 import { logger } from '../middleware/logger.js';
-import { DOCS_URL, START_TIME } from '../constants.js';
+import { APP_VERSION, DOCS_URL, START_TIME } from '../constants.js';
 
 const router = Router();
 
@@ -28,7 +28,7 @@ router.get('/health', (_req: Request, res: Response) => {
     res.jsonResponse({
         status: 'ok',
         uptime: Math.floor((Date.now() - START_TIME) / 1000),
-        version: '4.0.0',
+        version: APP_VERSION,
         node: process.version,
         memory: {
             rss: `${(mem.rss / 1024 / 1024).toFixed(1)} MB`,

package/src/routes/patch.ts

@@ -0,0 +1,45 @@
+import { Router, type Request, type Response } from 'express';
+import { ticTacToeStorage } from '../storage/index.js';
+import { error } from '../utils/response.js';
+import { supportsRest } from '../utils/version.js';
+
+const router = Router();
+
+// Play a tic-tac-toe move (REST: PATCH /tic-tac-toe/:game)
+router.patch('/:version/tic-tac-toe/:game', (req: Request, res: Response) => {
+    if (!supportsRest(req)) {
+        error(res, 405, 'PATCH is only supported in v4+.', `${req.version}/tic-tac-toe`);
+        return;
+    }
+
+    const game = req.params.game as string;
+    const { username, move, session } = (req.body as Record<string, string>) || {};
+
+    if (!username) {
+        error(res, 400, 'Please provide a username (?username={username})');
+        return;
+    }
+    if (!move) {
+        error(res, 400, 'Please provide a valid move (&move={move})');
+        return;
+    }
+    if (!session) {
+        error(res, 400, 'Please provide a valid session ID (&session={ID})');
+        return;
+    }
+
+    try {
+        const result = req.module.tic_tac_toe('play', {
+            username,
+            move,
+            session,
+            game,
+            storage: ticTacToeStorage,
+        });
+        res.jsonResponse(result);
+    } catch (err) {
+        error(res, 400, (err as Error).message);
+    }
+});
+
+export default router;

package/src/utils/version.ts

@@ -0,0 +1,5 @@
+import type { Request } from 'express';
+
+const REST_VERSIONS = new Set(['v4']);
+
+export const supportsRest = (req: Request): boolean => REST_VERSIONS.has(req.version);