@20syldev/api 3.5.0 → 4.1.0

package/src/modules/v4/tic_tac_toe.ts

@@ -0,0 +1,255 @@
+import { randomBytes } from 'crypto';
+import { SESSION_TTL, GAME_CLEANUP_TTL, RATE_LIMIT_WINDOW, RATE_LIMIT_MAX } from '../../constants.js';
+import type { TicTacToeStorage, TicTacToeMove, TicTacToeGame } from '../../types/storage.js';
+
+interface TicTacToeParams {
+    username?: string;
+    move?: string;
+    session?: string;
+    game?: string;
+    private?: boolean;
+    storage: TicTacToeStorage;
+}
+
+interface GameResult {
+    winner?: string | null;
+    loser?: string | null;
+    tie?: boolean;
+}
+
+export default function tic_tac_toe(action: string, params: TicTacToeParams): Record<string, unknown> {
+    const storage = params.storage;
+
+    storage.games ??= {};
+    storage.sessions ??= {};
+    storage.rateLimits ??= {};
+
+    const { games, sessions, rateLimits } = storage;
+
+    if (action === 'list') return listGames(games);
+
+    if (!params.username) throw new Error('Please provide a username');
+
+    const u = params.username.toLowerCase();
+    const now = Date.now();
+
+    rateLimits[u] = (rateLimits[u] ?? []).filter((ts) => now - ts < RATE_LIMIT_WINDOW);
+    if (rateLimits[u]!.length > RATE_LIMIT_MAX) {
+        const remainingTime = Math.ceil((rateLimits[u]![0]! + RATE_LIMIT_WINDOW - now) / 1000);
+        throw new Error(`Rate limit exceeded. Try again in ${remainingTime} seconds.`);
+    }
+    rateLimits[u]!.push(now);
+
+    if (action === 'play') {
+        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", "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>,
+    sessions: Record<string, { user: string; last: number }>,
+    u: string,
+    now: number,
+): Record<string, unknown> {
+    const { move, session, game } = params;
+    const validMoves = ['1-1', '1-2', '1-3', '2-1', '2-2', '2-3', '3-1', '3-2', '3-3'];
+
+    if (!move) throw new Error('Please provide a valid move');
+    if (!session) throw new Error('Please provide a valid session ID');
+    if (!game) throw new Error('Please provide a valid game ID');
+    if (!validMoves.includes(move)) throw new Error('Invalid move. Please provide a valid move (e.g., 1-1, 2-2, 3-3).');
+
+    if (sessions[u] && sessions[u].user !== session) {
+        throw new Error('Session ID mismatch');
+    }
+
+    games[game] = games[game] ?? {
+        moves: [],
+        players: [],
+        private: params.private || false,
+        creation: Date.now(),
+    };
+    const moves = games[game]!.moves;
+
+    const players = [...new Set(moves.map((play) => play.username))];
+    if (players.length >= 2 && !players.includes(params.username!)) {
+        throw new Error('Game is full, you can only watch.');
+    }
+
+    if (moves.length > 0 && moves[moves.length - 1]!.username === params.username) {
+        throw new Error('Please wait for the other player to make a move.');
+    }
+
+    if (moves.some((play) => play.move === move)) {
+        throw new Error('Move already made. Please choose a different move.');
+    }
+
+    const play: TicTacToeMove = { username: params.username!, move, session };
+    moves.push(play);
+
+    const result = checkGame(moves);
+    if (result.winner || result.tie) {
+        setTimeout(() => delete games[game!], GAME_CLEANUP_TTL);
+        return {
+            message: `Move sent successfully. ${result.winner ? result.winner + ' wins. ' + result.loser + ' loses.' : "It's a tie."}`,
+            ...result,
+        };
+    }
+
+    setTimeout(() => delete games[game!], SESSION_TTL);
+
+    sessions[u] = sessions[u] ?? { user: session, last: now };
+    sessions[u]!.last = now;
+    setTimeout(() => {
+        if (sessions[u] && now - sessions[u].last >= SESSION_TTL) delete sessions[u];
+    }, SESSION_TTL);
+
+    return { message: 'Move sent successfully' };
+}
+
+function fetchGame(params: TicTacToeParams, games: Record<string, TicTacToeGame>, u: string): Record<string, unknown> {
+    const id = params.game || generateGameId();
+    if (!games[id]) {
+        games[id] = {
+            moves: [],
+            players: [],
+            private: params.private || false,
+            creation: Date.now(),
+        };
+    }
+    if (!games[id]!.players.includes(u)) {
+        games[id]!.players.push(u);
+    }
+
+    const moves = games[id]!.moves;
+    const players = games[id]!.players;
+    const privateGame = games[id]!.private;
+    const lastPlayer = moves.length ? moves[moves.length - 1]!.username : null;
+    const turn = players.find((p) => p !== lastPlayer) || players[0];
+    const status = players.length >= 2 ? 'ready' : 'waiting';
+    const result = moves.length ? checkGame(moves) : {};
+
+    return {
+        id,
+        moves,
+        players,
+        turn,
+        status,
+        private: privateGame,
+        ...result,
+    };
+}
+
+function listGames(games: Record<string, TicTacToeGame>): Record<string, unknown> {
+    const publicGames: Record<string, unknown>[] = [];
+    const now = Date.now();
+
+    for (const [gameId, game] of Object.entries(games)) {
+        if (!game.private) {
+            const result = game.moves.length ? checkGame(game.moves) : {};
+            const isFinished = result.winner || result.tie;
+
+            if (!isFinished) {
+                const lastPlayer = game.moves.length ? game.moves[game.moves.length - 1]!.username : null;
+                const turn = game.players.find((p) => p !== lastPlayer) || game.players[0];
+                const status = game.players.length >= 2 ? 'ready' : 'waiting';
+
+                publicGames.push({
+                    id: gameId,
+                    players: game.players,
+                    playersCount: game.players.length,
+                    moves: game.moves.length,
+                    turn,
+                    status,
+                    creation: game.creation || now,
+                });
+            }
+        }
+    }
+
+    publicGames.sort((a, b) => (b.creation as number) - (a.creation as number));
+
+    return {
+        message: 'Public games available',
+        count: publicGames.length,
+        games: publicGames,
+    };
+}
+
+function generateGameId(): string {
+    const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+    return Array.from(randomBytes(5))
+        .map((b) => chars[b % chars.length])
+        .join('');
+}
+
+function checkGame(moves: TicTacToeMove[]): GameResult {
+    const board: (string | null)[][] = Array(3)
+        .fill(null)
+        .map(() => Array(3).fill(null) as (string | null)[]);
+    const playerSymbols: Record<string, string> = {};
+    const playersOrder: string[] = [];
+
+    moves.forEach(({ username, move }) => {
+        if (!playerSymbols[username]) {
+            playersOrder.push(username);
+            playerSymbols[username] = playersOrder.length === 1 ? 'X' : 'O';
+        }
+        const [row, col] = move.split('-').map(Number) as [number, number];
+        board[row - 1]![col - 1] = playerSymbols[username]!;
+    });
+
+    const checkWinner = (symbol: string): boolean => {
+        for (let i = 0; i < 3; i++) {
+            if (board[i]![0] === symbol && board[i]![1] === symbol && board[i]![2] === symbol) return true;
+            if (board[0]![i] === symbol && board[1]![i] === symbol && board[2]![i] === symbol) return true;
+        }
+        if (board[0]![0] === symbol && board[1]![1] === symbol && board[2]![2] === symbol) return true;
+        if (board[0]![2] === symbol && board[1]![1] === symbol && board[2]![0] === symbol) return true;
+        return false;
+    };
+
+    const winner = Object.keys(playerSymbols).find((player) => checkWinner(playerSymbols[player]!)) ?? null;
+    const isTie = !winner && moves.length === 9;
+    const loser =
+        winner && playersOrder.length === 2 ? (playersOrder.find((player) => player !== winner) ?? null) : null;
+
+    return { winner, loser, tie: isTie };
+}

package/src/modules/v4/time.ts

@@ -0,0 +1,92 @@
+const validFormats = [
+    'iso',
+    'utc',
+    'timestamp',
+    'locale',
+    'date',
+    'time',
+    'year',
+    'month',
+    'day',
+    'hour',
+    'minute',
+    'second',
+    'ms',
+    'dayOfWeek',
+    'dayOfYear',
+    'weekNumber',
+    'timezone',
+    'timezoneOffset',
+] as const;
+
+const validTimezones = ['UTC', 'America/New_York', 'Europe/Paris', 'Asia/Tokyo', 'Australia/Sydney'] as const;
+
+type TimeFormat = (typeof validFormats)[number];
+type Timezone = (typeof validTimezones)[number];
+
+export default function time(
+    type: string = 'live',
+    start?: string,
+    end?: string,
+    format?: string,
+    timezone?: string,
+): Record<string, unknown> {
+    if (type !== 'live' && type !== 'random') {
+        throw new Error('Please provide a valid type (live or random)');
+    }
+
+    if (start && !Date.parse(start)) {
+        throw new Error('Please provide a valid start date (YYYY-MM-DD)');
+    }
+
+    if (end && !Date.parse(end)) {
+        throw new Error('Please provide a valid end date (YYYY-MM-DD)');
+    }
+
+    if (format && !validFormats.includes(format as TimeFormat)) {
+        throw new Error(`Please provide a valid format. Options: ${validFormats.join(', ')}`);
+    }
+
+    if (timezone && !validTimezones.includes(timezone as Timezone)) {
+        throw new Error(`Please provide a valid timezone. Options: ${validTimezones.join(', ')}`);
+    }
+
+    const getTimeFormats = (date: Date, tz: string): Record<string, unknown> => {
+        return {
+            iso: date.toISOString(),
+            utc: date.toUTCString(),
+            timestamp: date.getTime(),
+            locale: date.toLocaleString('en-US', { timeZone: tz, timeZoneName: 'long' }),
+            date: date.toLocaleDateString('en-US', { timeZone: tz }),
+            time: date.toLocaleTimeString('en-US', { timeZone: tz }),
+            year: date.getFullYear(),
+            month: date.getMonth() + 1,
+            day: date.getDate(),
+            hour: date.getHours(),
+            minute: date.getMinutes(),
+            second: date.getSeconds(),
+            ms: date.getMilliseconds(),
+            dayOfWeek: date.getDay(),
+            dayOfYear: Math.floor((date.getTime() - new Date(date.getFullYear(), 0, 0).getTime()) / 86400000),
+            weekNumber: Math.ceil(((date.getTime() - new Date(date.getFullYear(), 0, 0).getTime()) / 86400000 + 1) / 7),
+            timezone: tz,
+            timezoneOffset: date.getTimezoneOffset(),
+        };
+    };
+
+    if (type === 'random') {
+        const startDate = start ? new Date(start).getTime() : new Date('1900-01-01').getTime();
+        const endDate = end ? new Date(end).getTime() : new Date('2100-12-31').getTime();
+        const randomDate = new Date(startDate + Math.random() * (endDate - startDate));
+        const tz = timezone || validTimezones[Math.floor(Math.random() * validTimezones.length)]!;
+        const formats = getTimeFormats(randomDate, tz);
+
+        return format ? { date: formats[format] } : formats;
+    }
+
+    const now = new Date();
+    const tz = timezone || 'UTC';
+    const formats = getTimeFormats(now, tz);
+
+    return format ? { date: formats[format] } : formats;
+}

package/src/modules/v4/token.ts

@@ -0,0 +1,43 @@
+import { randomBytes } from 'crypto';
+import { v4 } from 'uuid';
+import { MIN_TOKEN_LENGTH, MAX_TOKEN_LENGTH } from '../../constants.js';
+
+export default function token(len: number, type: string = 'alphanum'): string {
+    if (isNaN(len) || len < MIN_TOKEN_LENGTH) {
+        throw new Error('Length must be a number greater than or equal to 12');
+    }
+
+    if (len > MAX_TOKEN_LENGTH) {
+        throw new Error('Length cannot exceed 4096');
+    }
+
+    const genToken = (chars: string, length: number): string => {
+        return Array.from({ length }, () => {
+            return chars[Math.floor(Math.random() * chars.length)];
+        }).join('');
+    };
+
+    const tokenTypes: Record<string, () => string> = {
+        alpha: () => genToken('abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ', len),
+        alphanum: () => genToken('abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789', len),
+        base64: () =>
+            randomBytes(Math.ceil(len * 0.75))
+                .toString('base64')
+                .slice(0, len),
+        hex: () =>
+            randomBytes(Math.ceil(len * 0.5))
+                .toString('hex')
+                .slice(0, len),
+        num: () => genToken('0123456789', len),
+        punct: () => genToken('!"#$%&\'()*+,-./:;<=>?@[\\]^_`{|}~', len),
+        urlsafe: () => genToken('abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_', len),
+        uuid: () => v4().replace(/-/g, '').slice(0, len),
+    };
+
+    const lowerType = type.toLowerCase();
+    if (!tokenTypes[lowerType]) {
+        throw new Error(`Invalid token type. Valid types: ${Object.keys(tokenTypes).join(', ')}`);
+    }
+
+    return tokenTypes[lowerType]!();
+}

package/src/modules/v4/username.ts

@@ -0,0 +1,89 @@
+import { random, randomNumber } from './utils.js';
+
+export default function username(): Record<string, unknown> {
+    const adj = [
+        'Happy',
+        'Silly',
+        'Clever',
+        'Creative',
+        'Brave',
+        'Gentle',
+        'Kind',
+        'Funny',
+        'Wise',
+        'Charming',
+        'Sincere',
+        'Resourceful',
+        'Patient',
+        'Energetic',
+        'Adventurous',
+        'Ambitious',
+        'Courageous',
+        'Courteous',
+        'Determined',
+    ];
+    const ani = [
+        'Cat',
+        'Dog',
+        'Tiger',
+        'Elephant',
+        'Monkey',
+        'Penguin',
+        'Dolphin',
+        'Lion',
+        'Bear',
+        'Fox',
+        'Owl',
+        'Giraffe',
+        'Zebra',
+        'Koala',
+        'Rabbit',
+        'Squirrel',
+        'Panda',
+        'Horse',
+        'Wolf',
+        'Eagle',
+    ];
+    const job = [
+        'Writer',
+        'Artist',
+        'Musician',
+        'Explorer',
+        'Scientist',
+        'Engineer',
+        'Athlete',
+        'Chef',
+        'Doctor',
+        'Teacher',
+        'Lawyer',
+        'Entrepreneur',
+        'Actor',
+        'Dancer',
+        'Photographer',
+        'Architect',
+        'Pilot',
+        'Designer',
+        'Journalist',
+        'Veterinarian',
+    ];
+
+    const nombre = randomNumber(0, 99);
+    const choix: Record<string, () => string> = {
+        adj_num: () => random(adj) + nombre,
+        ani_num: () => random(ani) + nombre,
+        pro_num: () => random(job) + nombre,
+        adj_ani: () => random(adj) + random(ani),
+        adj_ani_num: () => random(adj) + random(ani) + nombre,
+        adj_pro: () => random(adj) + random(job),
+        pro_ani: () => random(job) + random(ani),
+        pro_ani_num: () => random(job) + random(ani) + nombre,
+    };
+
+    return {
+        username: choix[random(Object.keys(choix))]!(),
+        number: nombre,
+        adjective: random(adj),
+        animal: random(ani),
+        job: random(job),
+    };
+}

package/src/modules/v4/utils.ts

@@ -0,0 +1,38 @@
+export function random<T>(arr: T[]): T {
+    return arr[Math.floor(Math.random() * arr.length)]!;
+}
+
+export function randomNumber(min: number, max: number): number {
+    return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+
+export function genIP(): string {
+    return `${randomNumber(0, 255)}.${randomNumber(0, 255)}.${randomNumber(0, 255)}.${randomNumber(0, 255)}`;
+}
+
+export function formatDate(date: Date): string {
+    return new Date(date.getTime() - date.getTimezoneOffset() * 60000).toISOString().replace('Z', '');
+}
+
+export function envList(key: string): string[] | null {
+    const v = process.env[key];
+    return v && v !== 'undefined' ? v.split(' ') : null;
+}
+
+export function checkRateLimit(
+    rateLimits: Record<string, number[]>,
+    userId: string,
+    timestamp: number,
+    window = 10000,
+    limit = 50,
+): boolean {
+    rateLimits[userId] = (rateLimits[userId] ?? []).filter((ts) => timestamp - ts < window);
+
+    if (rateLimits[userId]!.length > limit) {
+        const remainingTime = Math.ceil((rateLimits[userId]![0]! + window - timestamp) / 1000);
+        throw new Error(`Rate limit exceeded. Try again in ${remainingTime} seconds.`);
+    }
+
+    rateLimits[userId]!.push(timestamp);
+    return false;
+}

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

@@ -0,0 +1,17 @@
+export * as algorithms from './v4/algorithms.js';
+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';
+export { default as username } from './v4/username.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;