@20syldev/api 4.2.0 → 4.4.0

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!);
@@ -87,15 +90,23 @@ describe('GET /v4/algorithms', () => {
 });
 
 describe('GET /v4/captcha', () => {
-    test('returns PNG', async () => {
+    test('returns PNG with provided text', async () => {
         const res = await fetch(`${baseUrl}/v4/captcha?text=hello`);
         assert.equal(res.status, 200);
         assert.match(res.headers.get('content-type') ?? '', /image\/png/);
+        assert.equal(res.headers.get('x-captcha-text'), 'hello');
     });
 
-    test('without text returns 400', async () => {
-        const { status } = await getJson('/v4/captcha');
-        assert.equal(status, 400);
+    test('auto-generates text when none provided', async () => {
+        const res = await fetch(`${baseUrl}/v4/captcha`);
+        assert.equal(res.status, 200);
+        assert.match(res.headers.get('content-type') ?? '', /image\/png/);
+        assert.ok(res.headers.get('x-captcha-text')!.length > 0);
+    });
+
+    test('accepts noise and dimensions', async () => {
+        const res = await fetch(`${baseUrl}/v4/captcha?text=AB&noise=high&width=200&height=80`);
+        assert.equal(res.status, 200);
     });
 });
 
@@ -114,7 +125,7 @@ describe('GET /v4/chat', () => {
 });
 
 describe('GET /v4/color', () => {
-    test('returns color formats', async () => {
+    test('returns random color formats', async () => {
         const { status, body } = await getJson('/v4/color');
         assert.equal(status, 200);
         assert.match(body.hex as string, /^#[0-9a-f]{6}$/);
@@ -122,6 +133,12 @@ describe('GET /v4/color', () => {
         assert.ok('hsl' in body);
         assert.ok('cmyk' in body);
     });
+
+    test('accepts hex input', async () => {
+        const { status, body } = await getJson('/v4/color?hex=ff6600');
+        assert.equal(status, 200);
+        assert.equal(body.hex, '#ff6600');
+    });
 });
 
 describe('GET /v4/convert', () => {
@@ -131,6 +148,12 @@ describe('GET /v4/convert', () => {
         assert.equal(body.result, 212);
     });
 
+    test('km to mi', async () => {
+        const { status, body } = await getJson('/v4/convert?value=1&from=km&to=mi');
+        assert.equal(status, 200);
+        assert.ok(Math.abs((body.result as number) - 0.621371) < 0.001);
+    });
+
     test('missing value returns 400', async () => {
         const { status } = await getJson('/v4/convert?from=celsius&to=fahrenheit');
         assert.equal(status, 400);
@@ -151,6 +174,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 +200,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 +230,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,9 +252,33 @@ 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');
+    test('returns PNG image by default', async () => {
+        const res = await fetch(`${baseUrl}/v4/qrcode?url=https%3A%2F%2Fexample.com`);
+        assert.equal(res.status, 200);
+        assert.match(res.headers.get('content-type') ?? '', /image\/png/);
+        const buf = Buffer.from(await res.arrayBuffer());
+        assert.ok(buf.subarray(0, 4).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47])));
+    });
+
+    test('returns data URL with format=base64', async () => {
+        const { status, body } = await getJson('/v4/qrcode?url=https%3A%2F%2Fexample.com&format=base64');
         assert.equal(status, 200);
         assert.match(body as unknown as string, /^data:image\/png;base64,/);
     });
@@ -260,6 +332,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 +359,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 +399,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 () => {
@@ -381,6 +453,7 @@ describe('POST /v4/hash', () => {
         const { status, body } = await sendJson('POST', '/v4/hash', { text: 'hello', method: 'sha256' });
         assert.equal(status, 200);
         assert.equal(body.hash, '2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824');
+        assert.equal(body.encoding, 'hex');
     });
 
     test('md5', async () => {
@@ -388,6 +461,21 @@ describe('POST /v4/hash', () => {
         assert.equal(body.hash, '5d41402abc4b2a76b9719d911017c592');
     });
 
+    test('base64 encoding', async () => {
+        const { status, body } = await sendJson('POST', '/v4/hash', {
+            text: 'hello',
+            method: 'sha256',
+            encoding: 'base64',
+        });
+        assert.equal(status, 200);
+        assert.equal(body.encoding, 'base64');
+    });
+
+    test('unsupported method returns 400', async () => {
+        const { status } = await sendJson('POST', '/v4/hash', { text: 'hello', method: 'fakehash' });
+        assert.equal(status, 400);
+    });
+
     test('missing text returns 400', async () => {
         const { status } = await sendJson('POST', '/v4/hash', { method: 'sha256' });
         assert.equal(status, 400);

package/tests/unit/captcha.test.ts

@@ -0,0 +1,61 @@
+import { test, describe } from 'node:test';
+import { strict as assert } from 'node:assert';
+import captcha from '../../src/modules/v4/captcha.js';
+
+const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47]);
+
+describe('captcha', () => {
+    test('returns PNG buffer with provided text', () => {
+        const result = captcha({ text: 'hello' });
+        assert.equal(result.contentType, 'image/png');
+        assert.ok(Buffer.isBuffer(result.body));
+        assert.ok(result.body.subarray(0, 4).equals(PNG_MAGIC));
+        assert.equal(result.text, 'hello');
+    });
+
+    test('auto-generates text when none provided', () => {
+        const result = captcha({});
+        assert.equal(result.text.length, 6);
+        assert.ok(Buffer.isBuffer(result.body));
+    });
+
+    test('respects custom length', () => {
+        const result = captcha({ length: 10 });
+        assert.equal(result.text.length, 10);
+    });
+
+    test('throws on invalid length', () => {
+        assert.throws(() => captcha({ length: 0 }), /length/);
+        assert.throws(() => captcha({ length: 99 }), /length/);
+    });
+
+    test('accepts custom dimensions', () => {
+        const result = captcha({ text: 'AB', width: 200, height: 80 });
+        assert.ok(Buffer.isBuffer(result.body));
+    });
+
+    test('throws on invalid dimensions', () => {
+        assert.throws(() => captcha({ text: 'AB', width: 10 }), /width/);
+        assert.throws(() => captcha({ text: 'AB', height: 500 }), /height/);
+    });
+
+    test('accepts noise levels', () => {
+        for (const noise of ['low', 'medium', 'high'] as const) {
+            const result = captcha({ text: 'test', noise });
+            assert.ok(Buffer.isBuffer(result.body));
+        }
+    });
+
+    test('throws on invalid noise', () => {
+        assert.throws(() => captcha({ text: 'test', noise: 'extreme' as 'low' }), /noise/);
+    });
+
+    test('accepts custom colors', () => {
+        const result = captcha({ text: 'test', bg: 'f0f0f0', color: '333333' });
+        assert.ok(Buffer.isBuffer(result.body));
+    });
+
+    test('throws on invalid color', () => {
+        assert.throws(() => captcha({ text: 'test', bg: 'xyz' }), /color/i);
+    });
+});

package/tests/unit/chat.test.ts

@@ -0,0 +1,53 @@
+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/color.test.ts

@@ -15,19 +15,39 @@ describe('color', () => {
 
     test('hex matches #RRGGBB', () => {
         for (let i = 0; i < 20; i++) {
-            assert.match(color().hex!, /^#[0-9a-f]{6}$/);
+            assert.match(color().hex, /^#[0-9a-f]{6}$/);
         }
     });
 
     test('rgb format', () => {
-        assert.match(color().rgb!, /^rgb\(\d{1,3}, \d{1,3}, \d{1,3}\)$/);
+        assert.match(color().rgb, /^rgb\(\d{1,3}, \d{1,3}, \d{1,3}\)$/);
     });
 
     test('hsl format', () => {
-        assert.match(color().hsl!, /^hsl\(\d+(\.\d+)?, \d+(\.\d+)?%, \d+(\.\d+)?%\)$/);
+        assert.match(color().hsl, /^hsl\(\d+(\.\d+)?, \d+(\.\d+)?%, \d+(\.\d+)?%\)$/);
     });
 
     test('cmyk format with 4 channels', () => {
-        assert.match(color().cmyk!, /^cmyk\(/);
+        assert.match(color().cmyk, /^cmyk\(/);
+    });
+
+    test('accepts hex input', () => {
+        const result = color('#ff6600');
+        assert.equal(result.hex, '#ff6600');
+        assert.equal(result.rgb, 'rgb(255, 102, 0)');
+    });
+
+    test('accepts hex without #', () => {
+        const result = color('ff6600');
+        assert.equal(result.hex, '#ff6600');
+    });
+
+    test('throws on invalid hex', () => {
+        assert.throws(() => color('xyz'), /Invalid HEX/);
+    });
+
+    test('HSV correct for equal channels', () => {
+        const result = color('#808000');
+        assert.match(result.hsv, /^hsv\(60\.0,/);
     });
 });

package/tests/unit/convert.test.ts

@@ -36,7 +36,32 @@ describe('convert', () => {
         assert.throws(() => convert(-300, 'celsius', 'kelvin'), /absolute zero/);
     });
 
+    test('km to mi', () => {
+        const result = convert(1, 'km', 'mi');
+        assert.ok(Math.abs(result.result - 0.621371) < 0.001);
+    });
+
+    test('kg to lb', () => {
+        const result = convert(1, 'kg', 'lb');
+        assert.ok(Math.abs(result.result - 2.20462) < 0.001);
+    });
+
+    test('kb to mb', () => {
+        const result = convert(1024, 'kb', 'mb');
+        assert.equal(result.result, 1);
+    });
+
+    test('km/h to mph', () => {
+        const result = convert(100, 'km/h', 'mph');
+        assert.ok(Math.abs(result.result - 62.1371) < 0.01);
+    });
+
+    test('negative values allowed for non-temperature', () => {
+        const result = convert(-5, 'km', 'mi');
+        assert.ok(result.result < 0);
+    });
+
     test('throws on non-numeric value', () => {
-        assert.throws(() => convert('abc', 'celsius', 'kelvin'), /must be a number/);
+        assert.throws(() => convert(NaN, 'celsius', 'kelvin'), /must be a number/);
     });
 });

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/hash.test.ts

@@ -8,25 +8,32 @@ describe('hash', () => {
         assert.deepEqual(result, {
             method: 'sha256',
             hash: '2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824',
+            encoding: 'hex',
         });
     });
 
     test('md5 of "hello"', () => {
         const result = hash('hello', 'md5');
-        assert.deepEqual(result, {
-            method: 'md5',
-            hash: '5d41402abc4b2a76b9719d911017c592',
-        });
+        assert.equal(result.hash, '5d41402abc4b2a76b9719d911017c592');
+        assert.equal(result.encoding, 'hex');
+    });
+
+    test('base64 encoding', () => {
+        const result = hash('hello', 'sha256', 'base64');
+        assert.equal(result.encoding, 'base64');
+        assert.ok(result.hash.length > 0);
+    });
+
+    test('throws on empty text', () => {
+        assert.throws(() => hash('', 'sha256'), /Text is required/);
     });
 
-    test('sha1 of empty string', () => {
-        const result = hash('', 'sha1');
-        assert.equal((result as { hash: string }).hash, 'da39a3ee5e6b4b0d3255bfef95601890afd80709');
+    test('throws on unsupported method', () => {
+        assert.throws(() => hash('hello', 'fakehash'), /Unsupported method/);
     });
 
-    test('returns error object on unsupported method', () => {
-        const result = hash('hello', 'fakehash');
-        assert.ok('error' in result);
+    test('throws on invalid encoding', () => {
+        assert.throws(() => hash('hello', 'sha256', 'utf8'), /Encoding must be/);
     });
 
     test('same input + method = same hash (deterministic)', () => {

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/);
+    });
+});