@20syldev/api 4.2.0 → 4.3.0

package/src/routes/delete.ts

@@ -0,0 +1,71 @@
+import { Router, type Request, type Response } from 'express';
+import { chatStorage, ticTacToeStorage } from '../storage/index.js';
+import { error } from '../utils/response.js';
+
+const router = Router();
+
+// Clear a private chat
+router.delete('/:version/chat/:token', (req: Request, res: Response) => {
+    if (req.version !== 'v4') {
+        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);
+    }
+});
+
+// Forfeit a tic-tac-toe game
+router.delete('/:version/tic-tac-toe/:game', (req: Request, res: Response) => {
+    if (req.version !== 'v4') {
+        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);
+    }
+});
+
+export default router;

package/src/routes/get.ts

@@ -196,6 +196,29 @@ router.get('/:version/encode', (req: Request, res: Response) => {
     }
 });
 
+// Geographic distance and bearing between two coordinates
+router.get('/:version/geo', (req: Request, res: Response) => {
+    const { lat1, lon1, lat2, lon2 } = req.query;
+    const { version } = req.params;
+
+    const geo = (req.module as { geo?: (a: string, b: string, c: string, d: string) => unknown }).geo;
+    if (!geo) {
+        error(res, 404, `Endpoint not available in ${version}.`, `${version}/geo`);
+        return;
+    }
+    if (lat1 === undefined || lon1 === undefined || lat2 === undefined || lon2 === undefined) {
+        error(res, 400, 'Please provide lat1, lon1, lat2 and lon2', `${version}/geo`);
+        return;
+    }
+
+    try {
+        const result = geo(lat1 as string, lon1 as string, lat2 as string, lon2 as string);
+        res.jsonResponse(result);
+    } catch (err) {
+        error(res, 400, (err as Error).message, `${req.version}/geo`);
+    }
+});
+
 // GET planning error
 router.get('/:version/hyperplanning', (_req: Request, res: Response) => {
     error(res, 405, 'This endpoint only supports POST requests.');
@@ -242,6 +265,33 @@ router.get('/:version/levenshtein', (req: Request, res: Response) => {
     }
 });
 
+// Generate a color palette from a base color
+router.get('/:version/palette', (req: Request, res: Response) => {
+    const { color, type } = req.query;
+    const { version } = req.params;
+
+    const palette = (req.module as { palette?: (c: string, t: string) => unknown }).palette;
+    if (!palette) {
+        error(res, 404, `Endpoint not available in ${version}.`, `${version}/palette`);
+        return;
+    }
+    if (!color) {
+        error(res, 400, 'Please provide a base color (?color=#ff6600)', `${version}/palette`);
+        return;
+    }
+    if (!type) {
+        error(res, 400, 'Please provide a palette type (&type=complementary)', `${version}/palette`);
+        return;
+    }
+
+    try {
+        const result = palette(color as string, type as string);
+        res.jsonResponse(result);
+    } catch (err) {
+        error(res, 400, (err as Error).message, `${req.version}/palette`);
+    }
+});
+
 // Generate personal data
 router.get('/:version/personal', (req: Request, res: Response) => {
     try {
@@ -252,6 +302,32 @@ router.get('/:version/personal', (req: Request, res: Response) => {
     }
 });
 
+// Generate a placeholder image or skeleton
+router.get('/:version/placeholder', (req: Request, res: Response) => {
+    const { type = 'image' } = req.query;
+    const { version } = req.params;
+
+    const placeholder = (
+        req.module as {
+            placeholder?: (
+                t: string,
+                q: Record<string, string | undefined>,
+            ) => { type: string; contentType: string; body: Buffer | string };
+        }
+    ).placeholder;
+    if (!placeholder) {
+        error(res, 404, `Endpoint not available in ${version}.`, `${version}/placeholder`);
+        return;
+    }
+
+    try {
+        const result = placeholder(type as string, req.query as Record<string, string | undefined>);
+        res.type(result.contentType).send(result.body);
+    } catch (err) {
+        error(res, 400, (err as Error).message, `${req.version}/placeholder`);
+    }
+});
+
 // Generate QR Code
 router.get('/:version/qrcode', async (req: Request, res: Response) => {
     const { url } = req.query;

package/src/routes/patch.ts

@@ -0,0 +1,44 @@
+import { Router, type Request, type Response } from 'express';
+import { ticTacToeStorage } from '../storage/index.js';
+import { error } from '../utils/response.js';
+
+const router = Router();
+
+// Play a tic-tac-toe move
+router.patch('/:version/tic-tac-toe/:game', (req: Request, res: Response) => {
+    if (req.version !== 'v4') {
+        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/tests/integration/api.test.ts

@@ -52,6 +52,9 @@ describe('GET / (version listing)', () => {
         const endpoints = body.endpoints as Record<string, Record<string, string>>;
         assert.ok('dice' in endpoints.get!);
         assert.ok('encode' in endpoints.get!);
+        assert.ok('geo' in endpoints.get!);
+        assert.ok('palette' in endpoints.get!);
+        assert.ok('placeholder' in endpoints.get!);
         assert.ok('statistics' in endpoints.get!);
         assert.ok('text' in endpoints.get!);
         assert.ok('validate' in endpoints.get!);
@@ -151,6 +154,14 @@ describe('GET /v4/dice', () => {
     });
 });
 
+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/encode', () => {
     test('base64 encode', async () => {
         const { status, body } = await getJson('/v4/encode?method=base64encode&text=hello');
@@ -169,11 +180,16 @@ describe('GET /v4/encode', () => {
     });
 });
 
-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/geo', () => {
+    test('Paris-NYC distance', async () => {
+        const { body } = await getJson('/v4/geo?lat1=48.8566&lon1=2.3522&lat2=40.7128&lon2=-74.006');
+        const distance = body.distance as { km: number };
+        assert.ok(Math.abs(distance.km - 5837) < 50);
+    });
+
+    test('missing param returns 400', async () => {
+        const { status } = await getJson('/v4/geo?lat1=0&lon1=0');
+        assert.equal(status, 400);
     });
 });
 
@@ -194,6 +210,18 @@ describe('GET /v4/levenshtein', () => {
     });
 });
 
+describe('GET /v4/palette', () => {
+    test('triadic returns 3 colors', async () => {
+        const { body } = await getJson('/v4/palette?color=%23ff6600&type=triadic');
+        assert.equal((body.colors as unknown[]).length, 3);
+    });
+
+    test('invalid type returns 400', async () => {
+        const { status } = await getJson('/v4/palette?color=%23ff6600&type=rainbow');
+        assert.equal(status, 400);
+    });
+});
+
 describe('GET /v4/personal', () => {
     test('returns generated identity', async () => {
         const { status, body } = await getJson('/v4/personal');
@@ -204,6 +232,22 @@ describe('GET /v4/personal', () => {
     });
 });
 
+describe('GET /v4/placeholder', () => {
+    test('image returns SVG', async () => {
+        const res = await fetch(`${baseUrl}/v4/placeholder?type=image&width=100&height=50`);
+        assert.equal(res.status, 200);
+        assert.match(res.headers.get('content-type') ?? '', /image\/svg\+xml/);
+    });
+
+    test('skeleton returns SVG', async () => {
+        const res = await fetch(`${baseUrl}/v4/placeholder?type=skeleton&width=200&height=100`);
+        assert.equal(res.status, 200);
+        assert.match(res.headers.get('content-type') ?? '', /image\/svg\+xml/);
+        const body = await res.text();
+        assert.match(body, /<svg/);
+    });
+});
+
 describe('GET /v4/qrcode', () => {
     test('returns data URL', async () => {
         const { status, body } = await getJson('/v4/qrcode?url=https%3A%2F%2Fexample.com');
@@ -260,6 +304,16 @@ describe('GET /v4/time', () => {
     });
 });
 
+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/validate', () => {
     test('valid luhn', async () => {
         const { body } = await getJson('/v4/validate?type=luhn&value=4111111111111111');
@@ -277,16 +331,6 @@ describe('GET /v4/validate', () => {
     });
 });
 
-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;
 
@@ -327,10 +371,10 @@ describe('GET /v4/website', () => {
         assert.ok('stats' in body);
     });
 
-    test('?key=stats.5 returns sub-key', async () => {
-        const { status, body } = await getJson('/v4/website?key=stats.5');
+    test('?key=active returns sub-key', async () => {
+        const { status, body } = await getJson('/v4/website?key=active');
         assert.equal(status, 200);
-        assert.ok('stats.5' in body);
+        assert.ok('active' in body);
     });
 
     test('?key=invalid.path returns 404', async () => {

package/tests/unit/captcha.test.ts

@@ -0,0 +1,23 @@
+import { test, describe } from 'node:test';
+import { strict as assert } from 'node:assert';
+import captcha from '../../src/modules/v4/captcha.js';
+
+describe('captcha', () => {
+    test('returns a Buffer for valid text', () => {
+        const result = captcha('hello');
+        assert.ok(Buffer.isBuffer(result));
+        assert.ok(result.length > 0);
+    });
+
+    test('PNG starts with correct magic bytes', () => {
+        const result = captcha('test');
+        assert.equal(result[0], 0x89);
+        assert.equal(result[1], 0x50); // P
+        assert.equal(result[2], 0x4e); // N
+        assert.equal(result[3], 0x47); // G
+    });
+
+    test('throws on missing text', () => {
+        assert.throws(() => captcha(''));
+    });
+});

package/tests/unit/chat.test.ts

@@ -0,0 +1,50 @@
+import { test, describe } from 'node:test';
+import { strict as assert } from 'node:assert';
+import chat from '../../src/modules/v4/chat.js';
+import type { ChatStorage } from '../../src/types/storage.js';
+
+function makeStorage(): ChatStorage {
+    return { messages: [], privateChats: {}, sessions: {}, rateLimits: {} };
+}
+
+describe('chat', () => {
+    test('sends a public message', () => {
+        const storage = makeStorage();
+        const result = chat('message', { username: 'alice', message: 'hello', session: 'a1', storage });
+        assert.ok((result as { message: string }).message.includes('sent'));
+    });
+
+    test('fetches public messages', () => {
+        const storage = makeStorage();
+        chat('message', { username: 'alice', message: 'test', session: 'a1', storage });
+        const result = chat('fetch', { username: 'bob', storage });
+        assert.ok(Array.isArray(result));
+        assert.equal((result as { message: string }[])[0]!.message, 'test');
+    });
+
+    test('sends and retrieves private messages', () => {
+        const storage = makeStorage();
+        chat('message', { username: 'alice', message: 'secret', session: 'a1', token: 'tok1', storage });
+        const result = chat('private', { username: 'bob', token: 'tok1', storage });
+        assert.ok(Array.isArray(result));
+    });
+
+    test('clears a private chat', () => {
+        const storage = makeStorage();
+        chat('message', { username: 'alice', message: 'secret', session: 'a1', token: 'tok2', storage });
+        const result = chat('clear', { username: 'alice', session: 'a1', token: 'tok2', storage });
+        assert.ok((result as { message: string }).message.includes('cleared'));
+    });
+
+    test('throws on missing username', () => {
+        assert.throws(() => chat('message', { username: '', message: 'hi', session: 's', storage: makeStorage() }), /username/);
+    });
+
+    test('throws on invalid action', () => {
+        assert.throws(() => chat('delete', { username: 'alice', storage: makeStorage() }), /Invalid action/);
+    });
+
+    test('throws on fetch with no messages', () => {
+        assert.throws(() => chat('fetch', { username: 'alice', storage: makeStorage() }), /No messages/);
+    });
+});

package/tests/unit/geo.test.ts

@@ -0,0 +1,45 @@
+import { test, describe } from 'node:test';
+import { strict as assert } from 'node:assert';
+import geo from '../../src/modules/v4/geo.js';
+
+describe('geo', () => {
+    test('Paris to NYC distance ~5837 km', () => {
+        const result = geo('48.8566', '2.3522', '40.7128', '-74.006');
+        assert.ok(Math.abs(result.distance.km - 5837) < 50, `expected ~5837, got ${result.distance.km}`);
+    });
+
+    test('same point returns 0 km', () => {
+        const result = geo('48.8566', '2.3522', '48.8566', '2.3522');
+        assert.equal(result.distance.km, 0);
+    });
+
+    test('miles and nautical miles match km conversion', () => {
+        const result = geo('0', '0', '0', '90');
+        assert.ok(Math.abs(result.distance.miles - result.distance.km * 0.621371) < 0.01);
+        assert.ok(Math.abs(result.distance.nauticalMiles - result.distance.km * 0.539957) < 0.01);
+    });
+
+    test('bearing N for due north', () => {
+        const result = geo('0', '0', '10', '0');
+        assert.equal(result.bearing.degrees, 0);
+        assert.equal(result.bearing.cardinal, 'N');
+    });
+
+    test('bearing E for due east', () => {
+        const result = geo('0', '0', '0', '10');
+        assert.equal(result.bearing.degrees, 90);
+        assert.equal(result.bearing.cardinal, 'E');
+    });
+
+    test('throws on invalid latitude', () => {
+        assert.throws(() => geo('100', '0', '0', '0'), /lat1 must be between/);
+    });
+
+    test('throws on invalid longitude', () => {
+        assert.throws(() => geo('0', '200', '0', '0'), /lon1 must be between/);
+    });
+
+    test('throws on non-numeric coords', () => {
+        assert.throws(() => geo('abc', '0', '0', '0'), /must be a number/);
+    });
+});

package/tests/unit/palette.test.ts

@@ -0,0 +1,53 @@
+import { test, describe } from 'node:test';
+import { strict as assert } from 'node:assert';
+import palette from '../../src/modules/v4/palette.js';
+
+describe('palette', () => {
+    test('complementary returns 2 colors', () => {
+        const result = palette('#ff6600', 'complementary');
+        assert.equal(result.colors.length, 2);
+        assert.equal(result.type, 'complementary');
+    });
+
+    test('triadic returns 3 colors', () => {
+        const result = palette('#ff6600', 'triadic');
+        assert.equal(result.colors.length, 3);
+    });
+
+    test('analogous returns 5 colors', () => {
+        const result = palette('#ff6600', 'analogous');
+        assert.equal(result.colors.length, 5);
+    });
+
+    test('tetradic returns 4 colors', () => {
+        const result = palette('#0066ff', 'tetradic');
+        assert.equal(result.colors.length, 4);
+    });
+
+    test('split-complementary returns 3 colors', () => {
+        const result = palette('#0066ff', 'split-complementary');
+        assert.equal(result.colors.length, 3);
+    });
+
+    test('each color has hex/rgb/hsl', () => {
+        const result = palette('#ff6600', 'triadic');
+        for (const c of result.colors) {
+            assert.match(c.hex, /^#[0-9a-f]{6}$/);
+            assert.match(c.rgb, /^rgb\(/);
+            assert.match(c.hsl, /^hsl\(/);
+        }
+    });
+
+    test('base color is included', () => {
+        const result = palette('#ff6600', 'complementary');
+        assert.equal(result.base.hex, '#ff6600');
+    });
+
+    test('throws on invalid hex', () => {
+        assert.throws(() => palette('#zzz', 'triadic'), /Invalid HEX/);
+    });
+
+    test('throws on unknown type', () => {
+        assert.throws(() => palette('#ff6600', 'rainbow'), /must be one of/);
+    });
+});

package/tests/unit/placeholder.test.ts

@@ -0,0 +1,57 @@
+import { test, describe } from 'node:test';
+import { strict as assert } from 'node:assert';
+import placeholder from '../../src/modules/v4/placeholder.js';
+
+describe('placeholder', () => {
+    test('image returns SVG with text', () => {
+        const result = placeholder('image', { width: '200', height: '100', text: 'Hello' });
+        assert.equal(result.type, 'image');
+        assert.equal(result.contentType, 'image/svg+xml');
+        assert.match(result.body, /<svg/);
+        assert.match(result.body, /Hello/);
+    });
+
+    test('skeleton returns SVG with animation', () => {
+        const result = placeholder('skeleton', { width: '300', height: '200' });
+        assert.equal(result.type, 'skeleton');
+        assert.equal(result.contentType, 'image/svg+xml');
+        assert.match(result.body, /<svg/);
+    });
+
+    test('default dimensions 800x600', () => {
+        const result = placeholder('image', {});
+        assert.match(result.body, /width="800"/);
+        assert.match(result.body, /height="600"/);
+    });
+
+    test('skeleton with avatar', () => {
+        const result = placeholder('skeleton', { avatar: 'circle' });
+        assert.match(result.body, /<circle/);
+    });
+
+    test('skeleton with rows', () => {
+        const result = placeholder('skeleton', { rows: '5' });
+        assert.match(result.body, /<rect/);
+    });
+
+    test('animate none removes animation', () => {
+        const result = placeholder('skeleton', { animate: 'none' });
+        assert.ok(!result.body.includes('<animate'));
+    });
+
+    test('throws on invalid type', () => {
+        assert.throws(() => placeholder('video', {}), /Type must be one of/);
+    });
+
+    test('throws on invalid width', () => {
+        assert.throws(() => placeholder('image', { width: '5000' }), /width/);
+    });
+
+    test('throws on invalid avatar shape', () => {
+        assert.throws(() => placeholder('skeleton', { avatar: 'hexagon' }), /avatar/);
+    });
+
+    test('throws on invalid speed', () => {
+        assert.throws(() => placeholder('skeleton', { speed: '99' }), /speed/);
+    });
+});

package/tests/unit/qrcode.test.ts

@@ -0,0 +1,14 @@
+import { test, describe } from 'node:test';
+import { strict as assert } from 'node:assert';
+import qrcode from '../../src/modules/v4/qrcode.js';
+
+describe('qrcode', () => {
+    test('returns data URL for valid url', async () => {
+        const result = await qrcode('https://example.com');
+        assert.match(result, /^data:image\/png;base64,/);
+    });
+
+    test('throws on missing url', async () => {
+        await assert.rejects(() => qrcode(''));
+    });
+});

package/tests/unit/tic_tac_toe.test.ts

@@ -0,0 +1,52 @@
+import { test, describe } from 'node:test';
+import { strict as assert } from 'node:assert';
+import tic_tac_toe from '../../src/modules/v4/tic_tac_toe.js';
+import type { TicTacToeStorage } from '../../src/types/storage.js';
+
+function makeStorage(): TicTacToeStorage {
+    return { games: {}, sessions: {}, rateLimits: {} };
+}
+
+describe('tic_tac_toe', () => {
+    test('list returns empty games array', () => {
+        const result = tic_tac_toe('list', { storage: makeStorage() });
+        assert.ok(Array.isArray(result.games));
+    });
+
+    test('play creates a game and makes a move', () => {
+        const storage = makeStorage();
+        const result = tic_tac_toe('play', { username: 'alice', move: '1-1', session: 'a1', game: 'TEST1', storage });
+        assert.ok((result.message as string).includes('Move sent'));
+    });
+
+    test('fetch returns game state', () => {
+        const storage = makeStorage();
+        tic_tac_toe('play', { username: 'alice', move: '1-1', session: 'a1', game: 'TEST2', storage });
+        const result = tic_tac_toe('fetch', { username: 'alice', game: 'TEST2', storage });
+        assert.equal(result.id, 'TEST2');
+    });
+
+    test('forfeit throws on non-player', () => {
+        const storage = makeStorage();
+        tic_tac_toe('play', { username: 'alice', move: '1-1', session: 'a1', game: 'TEST3', storage });
+        assert.throws(
+            () => tic_tac_toe('forfeit', { username: 'charlie', session: 'c1', game: 'TEST3', storage }),
+            /not a player/,
+        );
+    });
+
+    test('throws on missing username', () => {
+        assert.throws(() => tic_tac_toe('play', { move: '1-1', session: 's', game: 'G', storage: makeStorage() }), /username/);
+    });
+
+    test('throws on missing move', () => {
+        assert.throws(
+            () => tic_tac_toe('play', { username: 'alice', session: 's', game: 'G', storage: makeStorage() }),
+            /move/i,
+        );
+    });
+
+    test('throws on invalid action', () => {
+        assert.throws(() => tic_tac_toe('reset', { username: 'alice', storage: makeStorage() }), /Invalid action/);
+    });
+});