@20syldev/api 3.5.0 → 4.1.0

package/src/routes/post.ts

@@ -0,0 +1,200 @@
+import { Router, type Request, type Response } from 'express';
+import { chatStorage, ticTacToeStorage } from '../storage/index.js';
+import { MIN_TOKEN_LENGTH, MAX_TOKEN_LENGTH } from '../constants.js';
+import { error } from '../utils/response.js';
+
+const router = Router();
+
+// Store chat messages
+router.post('/:version/chat', (req: Request, res: Response) => {
+    const { username, message, timestamp, session, token } = (req.body as Record<string, string>) || {};
+
+    if (!username) {
+        error(res, 400, 'Please provide a username (?username={username})');
+        return;
+    }
+    if (!message) {
+        error(res, 400, 'Please provide a message (&message={message})');
+        return;
+    }
+    if (!session) {
+        error(res, 400, 'Please provide a valid session ID (&session={ID})');
+        return;
+    }
+
+    try {
+        const result = req.module.chat('message', {
+            username,
+            message,
+            timestamp,
+            session,
+            token,
+            storage: chatStorage,
+        });
+        res.jsonResponse(result);
+    } catch (err) {
+        error(res, 400, (err as Error).message);
+    }
+});
+
+// Display a private chat with a token
+router.post('/:version/chat/private', (req: Request, res: Response) => {
+    const { username, token } = (req.body as Record<string, string>) || {};
+
+    if (!username) {
+        error(res, 400, 'Please provide a username (?username={username})');
+        return;
+    }
+    if (!token) {
+        error(res, 400, 'Please provide a valid token (&token={key}).');
+        return;
+    }
+
+    try {
+        const messages = req.module.chat('private', {
+            username,
+            token,
+            storage: chatStorage,
+        });
+        res.jsonResponse(messages);
+    } catch (err) {
+        error(res, 400, (err as Error).message);
+    }
+});
+
+// Generate hash
+router.post('/:version/hash', (req: Request, res: Response) => {
+    const { text, method } = (req.body as Record<string, string>) || {};
+
+    if (!text) {
+        error(res, 400, 'Please provide a text (?text={text})', `${req.version}/hash`);
+        return;
+    }
+    if (!method) {
+        error(res, 400, 'Please provide a valid hash algorithm (&method={algorithm})', `${req.version}/hash`);
+        return;
+    }
+
+    try {
+        const result = req.module.hash(text, method);
+        res.jsonResponse(result);
+    } catch (err) {
+        error(res, 400, (err as Error).message, `${req.version}/hash`);
+    }
+});
+
+// Display a planning from an ICS file
+router.post('/:version/hyperplanning', async (req: Request, res: Response) => {
+    const { url, detail } = (req.body as Record<string, string>) || {};
+
+    if (!url) {
+        error(res, 400, 'Please provide a valid ICS file URL (?url={URL})', `${req.version}/hyperplanning`);
+        return;
+    }
+
+    try {
+        const hyperplanning = await req.module.hyperplanning(url, detail);
+        res.jsonResponse(hyperplanning);
+    } catch (err) {
+        error(res, 400, (err as Error).message, `${req.version}/hyperplanning`);
+    }
+});
+
+// Store tic tac toe games
+router.post('/:version/tic-tac-toe', (req: Request, res: Response) => {
+    const { username, move, session, game } = (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;
+    }
+    if (!game) {
+        error(res, 400, 'Please provide a valid game ID (&game={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);
+    }
+});
+
+// Display a tic tac toe game with a token
+router.post('/:version/tic-tac-toe/fetch', (req: Request, res: Response) => {
+    const { username, game } = (req.body as Record<string, string>) || {};
+    const privateGame = ((req.body as Record<string, unknown>) || {}).private as boolean | undefined;
+
+    if (!username) {
+        error(res, 400, 'Please provide a username (?username={username})');
+        return;
+    }
+
+    try {
+        const result = req.module.tic_tac_toe('fetch', {
+            username,
+            game,
+            private: privateGame,
+            storage: ticTacToeStorage,
+        });
+        res.jsonResponse(result);
+    } catch (err) {
+        error(res, 400, (err as Error).message);
+    }
+});
+
+// List public tic tac toe games
+router.post('/:version/tic-tac-toe/list', (req: Request, res: Response) => {
+    try {
+        const result = req.module.tic_tac_toe('list', {
+            storage: ticTacToeStorage,
+        });
+        res.jsonResponse(result);
+    } catch (err) {
+        error(res, 400, (err as Error).message);
+    }
+});
+
+// Generate Token
+router.post('/:version/token', (req: Request, res: Response) => {
+    const body = (req.body as Record<string, unknown>) || {};
+    const len = parseInt(String(body.len || 24), 10);
+    const type = body.type ? String(body.type).toLowerCase() : 'alpha';
+
+    if (isNaN(len) || len < 0) {
+        error(res, 400, 'Invalid number.', `${req.version}/token`);
+        return;
+    }
+    if (len > MAX_TOKEN_LENGTH) {
+        error(res, 400, 'Length cannot exceed 4096.', `${req.version}/token`);
+        return;
+    }
+    if (len < MIN_TOKEN_LENGTH) {
+        error(res, 400, 'Length cannot be less than 12.', `${req.version}/token`);
+        return;
+    }
+
+    try {
+        const token = req.module.token(len, type);
+        res.jsonResponse({ token });
+    } catch (err) {
+        error(res, 400, (err as Error).message, `${req.version}/token`);
+    }
+});
+
+export default router;

package/src/storage/index.ts

@@ -0,0 +1,16 @@
+import type { ChatStorage, TicTacToeStorage, IpLimits } from '../types/storage.js';
+
+export const ipLimits: IpLimits = {};
+
+export const chatStorage: ChatStorage = {
+    messages: [],
+    privateChats: {},
+    sessions: {},
+    rateLimits: {},
+};
+
+export const ticTacToeStorage: TicTacToeStorage = {
+    games: {},
+    sessions: {},
+    rateLimits: {},
+};

package/src/types/express.d.ts

@@ -0,0 +1,17 @@
+import type * as apiv3 from '../modules/v3.js';
+import type * as apiv4 from '../modules/v4.js';
+
+declare global {
+    namespace Express {
+        interface Request {
+            version: string;
+            latest: string;
+            endpoint: string;
+            module: typeof apiv3 | typeof apiv4;
+        }
+
+        interface Response {
+            jsonResponse: (data: unknown) => void;
+        }
+    }
+}

package/src/types/storage.ts

@@ -0,0 +1,48 @@
+export interface LogEntry {
+    timestamp: string;
+    method: string;
+    url: string;
+    status: number;
+    duration: string;
+    platform: string | undefined;
+}
+
+export interface ChatMessage {
+    username: string;
+    message: string;
+    timestamp: string;
+}
+
+export interface ChatStorage {
+    messages: ChatMessage[];
+    privateChats: Record<string, ChatMessage[]>;
+    sessions: Record<string, { user: string; last: number }>;
+    rateLimits: Record<string, number[]>;
+}
+
+export interface TicTacToeMove {
+    username: string;
+    move: string;
+    session: string;
+}
+
+export interface TicTacToeGame {
+    moves: TicTacToeMove[];
+    players: string[];
+    private: boolean;
+    creation: number;
+}
+
+export interface TicTacToeStorage {
+    games: Record<string, TicTacToeGame>;
+    sessions: Record<string, { user: string; last: number }>;
+    rateLimits: Record<string, number[]>;
+}
+
+export interface IpLimits {
+    [ip: string]: {
+        [hour: string]: {
+            [minute: string]: number;
+        };
+    };
+}

package/src/utils/response.ts

@@ -0,0 +1,11 @@
+import type { Response } from 'express';
+import { DOCS_URL, STATUS_MESSAGES } from '../constants.js';
+
+export function error(res: Response, status: number, message: string, docPath?: string): void {
+    res.status(status).jsonResponse({
+        message: STATUS_MESSAGES[status] ?? 'Error',
+        error: message,
+        documentation: docPath ? `${DOCS_URL}/${docPath}` : DOCS_URL,
+        status: String(status),
+    });
+}

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);

package/tests/integration/api.test.ts

@@ -0,0 +1,395 @@
+import { test, describe, before, after } from 'node:test';
+import { strict as assert } from 'node:assert';
+import type { AddressInfo } from 'node:net';
+import type { Server } from 'node:http';
+import app from '../../src/app.js';
+
+let server: Server;
+let baseUrl: string;
+
+before(() => {
+    return new Promise<void>((resolve) => {
+        server = app.listen(0, () => {
+            const port = (server.address() as AddressInfo).port;
+            baseUrl = `http://127.0.0.1:${port}`;
+            resolve();
+        });
+    });
+});
+
+after(() => {
+    return new Promise<void>((resolve) => {
+        server.close(() => resolve());
+    });
+});
+
+async function getJson(path: string): Promise<{ status: number; body: Record<string, unknown> }> {
+    const res = await fetch(`${baseUrl}${path}`);
+    const body = (await res.json()) as Record<string, unknown>;
+    return { status: res.status, body };
+}
+
+async function sendJson(
+    method: string,
+    path: string,
+    body: Record<string, unknown>,
+): Promise<{ status: number; body: Record<string, unknown> }> {
+    const res = await fetch(`${baseUrl}${path}`, {
+        method,
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    const data = (await res.json()) as Record<string, unknown>;
+    return { status: res.status, body: data };
+}
+
+// --- GET endpoints ---
+
+describe('GET / (version listing)', () => {
+    test('v4 endpoints listed', async () => {
+        const { body } = await getJson('/v4');
+        assert.equal(body.version, 'v4');
+        const endpoints = body.endpoints as Record<string, Record<string, string>>;
+        assert.ok('dice' in endpoints.get!);
+        assert.ok('statistics' in endpoints.get!);
+    });
+
+    test('invalid version returns 404', async () => {
+        const { status } = await getJson('/v99');
+        assert.equal(status, 404);
+    });
+});
+
+describe('GET /v4/algorithms', () => {
+    test('fibonacci', async () => {
+        const { status, body } = await getJson('/v4/algorithms?method=fibonacci&value=10');
+        assert.equal(status, 200);
+        assert.deepEqual(body.answer, [0, 1, 1, 2, 3, 5, 8, 13, 21, 34]);
+    });
+
+    test('isprime', async () => {
+        const { body } = await getJson('/v4/algorithms?method=isprime&value=17');
+        assert.equal(body.answer, true);
+    });
+
+    test('roman 2024 to MMXXIV', async () => {
+        const { body } = await getJson('/v4/algorithms?method=roman&value=2024');
+        assert.equal(body.answer, 'MMXXIV');
+    });
+
+    test('roman MMXXIV to 2024', async () => {
+        const { body } = await getJson('/v4/algorithms?method=roman&value=MMXXIV');
+        assert.equal(body.answer, 2024);
+    });
+});
+
+describe('GET /v4/captcha', () => {
+    test('returns PNG', async () => {
+        const res = await fetch(`${baseUrl}/v4/captcha?text=hello`);
+        assert.equal(res.status, 200);
+        assert.match(res.headers.get('content-type') ?? '', /image\/png/);
+    });
+
+    test('without text returns 400', async () => {
+        const { status } = await getJson('/v4/captcha');
+        assert.equal(status, 400);
+    });
+});
+
+describe('GET /v4/chat', () => {
+    test('fetches public messages', async () => {
+        await sendJson('POST', '/v4/chat', {
+            username: 'get-chat-user',
+            message: 'ping',
+            session: `get-chat-${Date.now()}`,
+        });
+        const res = await fetch(`${baseUrl}/v4/chat`);
+        assert.equal(res.status, 200);
+        const body = (await res.json()) as { username: string; message: string }[];
+        assert.ok(Array.isArray(body));
+    });
+});
+
+describe('GET /v4/color', () => {
+    test('returns color formats', async () => {
+        const { status, body } = await getJson('/v4/color');
+        assert.equal(status, 200);
+        assert.match(body.hex as string, /^#[0-9a-f]{6}$/);
+        assert.ok('rgb' in body);
+        assert.ok('hsl' in body);
+        assert.ok('cmyk' in body);
+    });
+});
+
+describe('GET /v4/convert', () => {
+    test('celsius to fahrenheit', async () => {
+        const { status, body } = await getJson('/v4/convert?value=100&from=celsius&to=fahrenheit');
+        assert.equal(status, 200);
+        assert.equal(body.result, 212);
+    });
+
+    test('missing value returns 400', async () => {
+        const { status } = await getJson('/v4/convert?from=celsius&to=fahrenheit');
+        assert.equal(status, 400);
+    });
+});
+
+describe('GET /v4/dice', () => {
+    test('rolls 2d6+3', async () => {
+        const { body } = await getJson('/v4/dice?roll=2d6%2B3');
+        assert.equal(body.count, 2);
+        assert.equal(body.sides, 6);
+        assert.equal(body.modifier, 3);
+    });
+
+    test('rejects invalid notation', async () => {
+        const { status } = await getJson('/v4/dice?roll=foo');
+        assert.equal(status, 400);
+    });
+});
+
+describe('GET /v4/domain', () => {
+    test('has TLD', async () => {
+        const { status, body } = await getJson('/v4/domain');
+        assert.equal(status, 200);
+        assert.match(body.domain as string, /\./);
+    });
+});
+
+describe('GET /v4/infos', () => {
+    test('returns API infos', async () => {
+        const { status, body } = await getJson('/v4/infos');
+        assert.equal(status, 200);
+        assert.ok('endpoints' in body);
+        assert.ok('documentation' in body);
+    });
+});
+
+describe('GET /v4/levenshtein', () => {
+    test('computes distance', async () => {
+        const { status, body } = await getJson('/v4/levenshtein?str1=kitten&str2=sitting');
+        assert.equal(status, 200);
+        assert.equal(body.distance, 3);
+    });
+});
+
+describe('GET /v4/personal', () => {
+    test('returns generated identity', async () => {
+        const { status, body } = await getJson('/v4/personal');
+        assert.equal(status, 200);
+        assert.ok('name' in body);
+        assert.ok('email' in body);
+        assert.ok('card' in body);
+    });
+});
+
+describe('GET /v4/qrcode', () => {
+    test('returns data URL', async () => {
+        const { status, body } = await getJson('/v4/qrcode?url=https%3A%2F%2Fexample.com');
+        assert.equal(status, 200);
+        assert.match(body as unknown as string, /^data:image\/png;base64,/);
+    });
+});
+
+describe('GET /v4/statistics', () => {
+    test('basic stats', async () => {
+        const { body } = await getJson('/v4/statistics?values=1,2,3,4,5');
+        assert.equal(body.mean, 3);
+        assert.equal(body.median, 3);
+        assert.equal(body.count, 5);
+    });
+
+    test('missing values returns 400', async () => {
+        const { status } = await getJson('/v4/statistics');
+        assert.equal(status, 400);
+    });
+});
+
+describe('GET /v4/time', () => {
+    test('live', async () => {
+        const { status, body } = await getJson('/v4/time');
+        assert.equal(status, 200);
+        assert.ok('iso' in body);
+        assert.ok('timestamp' in body);
+    });
+
+    test('random in range', async () => {
+        const { status, body } = await getJson('/v4/time?type=random&start=2020-01-01&end=2020-12-31');
+        assert.equal(status, 200);
+        const ts = body.timestamp as number;
+        assert.ok(ts >= new Date('2020-01-01').getTime());
+        assert.ok(ts <= new Date('2020-12-31').getTime());
+    });
+});
+
+describe('GET /v4/username', () => {
+    test('has fields', async () => {
+        const { status, body } = await getJson('/v4/username');
+        assert.equal(status, 200);
+        assert.ok('username' in body);
+        assert.ok('adjective' in body);
+        assert.ok('animal' in body);
+    });
+});
+
+describe('GET /v4/website', () => {
+    const originalFetch = globalThis.fetch;
+
+    after(() => {
+        globalThis.fetch = originalFetch;
+    });
+
+    test('returns aggregated payload (with mocked GitHub API)', async () => {
+        globalThis.fetch = (async (input: string | URL | Request) => {
+            const url = typeof input === 'string' ? input : input.toString();
+            if (url.includes('api.github.com')) {
+                return new Response(
+                    JSON.stringify({
+                        data: {
+                            user: {
+                                contributionsCollection: {
+                                    contributionCalendar: {
+                                        weeks: [
+                                            {
+                                                firstDay: '2026-01-01',
+                                                contributionDays: [{ date: '2026-01-01', contributionCount: 5 }],
+                                            },
+                                        ],
+                                    },
+                                },
+                            },
+                        },
+                    }),
+                    { status: 200, headers: { 'content-type': 'application/json' } },
+                );
+            }
+            return originalFetch(input);
+        }) as typeof fetch;
+
+        const { status, body } = await getJson('/v4/website');
+        assert.equal(status, 200);
+        assert.ok('versions' in body);
+        assert.ok('stats' in body);
+    });
+
+    test('?key=stats.5 returns sub-key', async () => {
+        const { status, body } = await getJson('/v4/website?key=stats.5');
+        assert.equal(status, 200);
+        assert.ok('stats.5' in body);
+    });
+
+    test('?key=invalid.path returns 404', async () => {
+        const { status } = await getJson('/v4/website?key=does.not.exist');
+        assert.equal(status, 404);
+    });
+
+    test('rejects prototype pollution keys', async () => {
+        const { status } = await getJson('/v4/website?key=__proto__');
+        assert.equal(status, 400);
+    });
+});
+
+// --- POST endpoints ---
+
+describe('POST /v4/chat', () => {
+    const session = `chat-${Date.now()}`;
+
+    test('sends a public message', async () => {
+        const { status, body } = await sendJson('POST', '/v4/chat', {
+            username: 'alice',
+            message: 'public hello',
+            session,
+        });
+        assert.equal(status, 200);
+        assert.match(body.message as string, /sent/);
+    });
+
+    test('fetches private chat (legacy)', async () => {
+        const token = `tok-${Date.now()}`;
+        await sendJson('POST', '/v4/chat', {
+            username: 'bob',
+            message: 'secret',
+            session: `chat-bob-${Date.now()}`,
+            token,
+        });
+        const { status, body } = await sendJson('POST', '/v4/chat/private', {
+            username: 'bob',
+            token,
+        });
+        assert.equal(status, 200);
+        assert.ok(Array.isArray(body));
+    });
+});
+
+describe('POST /v4/hash', () => {
+    test('sha256', async () => {
+        const { status, body } = await sendJson('POST', '/v4/hash', { text: 'hello', method: 'sha256' });
+        assert.equal(status, 200);
+        assert.equal(body.hash, '2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824');
+    });
+
+    test('md5', async () => {
+        const { body } = await sendJson('POST', '/v4/hash', { text: 'hello', method: 'md5' });
+        assert.equal(body.hash, '5d41402abc4b2a76b9719d911017c592');
+    });
+
+    test('missing text returns 400', async () => {
+        const { status } = await sendJson('POST', '/v4/hash', { method: 'sha256' });
+        assert.equal(status, 400);
+    });
+});
+
+describe('POST /v4/tic-tac-toe', () => {
+    const game = 'TTT' + Date.now().toString(36).slice(-3).toUpperCase();
+    const session = `ttt-${Date.now()}`;
+
+    test('list returns games', async () => {
+        const { status, body } = await sendJson('POST', '/v4/tic-tac-toe/list', {});
+        assert.equal(status, 200);
+        assert.ok(Array.isArray(body.games));
+    });
+
+    test('plays a move', async () => {
+        const { status, body } = await sendJson('POST', '/v4/tic-tac-toe', {
+            username: 'alice',
+            move: '1-1',
+            session,
+            game,
+        });
+        assert.equal(status, 200);
+        assert.match(body.message as string, /Move sent/);
+    });
+
+    test('fetch returns game state', async () => {
+        const { status, body } = await sendJson('POST', '/v4/tic-tac-toe/fetch', {
+            username: 'alice',
+            game,
+        });
+        assert.equal(status, 200);
+        assert.equal(body.id, game);
+    });
+
+    test('missing move returns 400', async () => {
+        const { status } = await sendJson('POST', '/v4/tic-tac-toe', {
+            username: 'alice',
+            session,
+            game,
+        });
+        assert.equal(status, 400);
+    });
+});
+
+describe('POST /v4/token', () => {
+    test('alpha 24', async () => {
+        const { status, body } = await sendJson('POST', '/v4/token', { len: 24, type: 'alpha' });
+        assert.equal(status, 200);
+        assert.equal(typeof body.token, 'string');
+        assert.equal((body.token as string).length, 24);
+        assert.match(body.token as string, /^[a-zA-Z]+$/);
+    });
+
+    test('below min length returns 400', async () => {
+        const { status } = await sendJson('POST', '/v4/token', { len: 5, type: 'alpha' });
+        assert.equal(status, 400);
+    });
+});

package/tests/tsconfig.json

@@ -0,0 +1,3 @@
+{
+    "extends": "../tsconfig.test.json"
+}