@20syldev/api 4.5.0 → 4.6.0

package/src/routes/get.ts

@@ -1,14 +1,16 @@
-import { Router, type Request, type Response } from 'express';
-import { versions } from '../config/versions.js';
+import { type Request, type Response, Router } from 'express';
+
 import { env } from '../config/env.js';
-import { ipLimits } from '../storage/index.js';
-import { chatStorage } from '../storage/index.js';
+import { versions } from '../config/versions.js';
 import { DOCS_URL, GITHUB_CACHE_TTL } from '../constants.js';
-import { error } from '../utils/response.js';
-import { since } from '../utils/helpers.js';
-import type { QRCodeOptions, QRCodeResult } from '../modules/v4/qrcode.js';
+import type { UserAgentResult } from '../modules/v4/agent.js';
 import type { CaptchaOptions, CaptchaResult } from '../modules/v4/captcha.js';
 import type { ColorResult } from '../modules/v4/color.js';
+import type { IpResult } from '../modules/v4/ip.js';
+import type { QRCodeOptions, QRCodeResult } from '../modules/v4/qrcode.js';
+import { chatStorage, ipLimits } from '../storage/index.js';
+import { since } from '../utils/helpers.js';
+import { error } from '../utils/response.js';
 
 const router = Router();
 
@@ -174,6 +176,54 @@ router.get('/:version/convert', (req: Request, res: Response) => {
     }
 });
 
+// Echo request headers
+router.get('/:version/headers', (req: Request, res: Response) => {
+    const redacted = new Set(['authorization', 'cookie', 'set-cookie', 'proxy-authorization']);
+    let headers: Record<string, unknown> = {};
+
+    for (const [k, v] of Object.entries(req.headers)) {
+        headers[k] = redacted.has(k) ? '[redacted]' : v;
+    }
+
+    const filter = req.query.filter as string | undefined;
+    if (filter) {
+        const keys = new Set(filter.split(',').map((k) => k.trim().toLowerCase()));
+        headers = Object.fromEntries(Object.entries(headers).filter(([k]) => keys.has(k)));
+    }
+
+    res.jsonResponse({
+        count: Object.keys(headers).length,
+        headers,
+        ip: req.ip,
+        method: req.method,
+        url: req.originalUrl,
+    });
+});
+
+// Analyze an IP address
+router.get('/:version/ip', (req: Request, res: Response) => {
+    const address = (req.query.address as string | undefined) ?? req.ip ?? '';
+    try {
+        const ipFn = (req.module as Record<string, unknown>).ip as (a: string) => IpResult;
+        const result = ipFn(address);
+        res.jsonResponse(result);
+    } catch (err) {
+        error(res, 400, (err as Error).message, `${req.version}/ip`);
+    }
+});
+
+// Parse a User-Agent string
+router.get('/:version/agent', (req: Request, res: Response) => {
+    const ua = (req.query.ua as string | undefined) ?? (req.headers['user-agent'] as string) ?? '';
+    try {
+        const agentFn = (req.module as Record<string, unknown>).agent as (ua: string) => UserAgentResult;
+        const result = agentFn(ua);
+        res.jsonResponse(result);
+    } catch (err) {
+        error(res, 400, (err as Error).message, `${req.version}/agent`);
+    }
+});
+
 // Generate domain informations
 router.get('/:version/domain', (req: Request, res: Response) => {
     try {

package/src/routes/index.ts

@@ -1,8 +1,9 @@
-import { Router, type Request, type Response } from 'express';
+import { type Request, type Response, Router } from 'express';
+
 import { versions } from '../config/versions.js';
-import { ipLimits } from '../storage/index.js';
-import { logger } from '../middleware/logger.js';
 import { APP_VERSION, DOCS_URL, START_TIME } from '../constants.js';
+import { logger } from '../middleware/logger.js';
+import { ipLimits } from '../storage/index.js';
 
 const router = Router();
 

package/src/routes/patch.ts

@@ -1,4 +1,5 @@
-import { Router, type Request, type Response } from 'express';
+import { type Request, type Response, Router } from 'express';
+
 import { ticTacToeStorage } from '../storage/index.js';
 import { error } from '../utils/response.js';
 

package/src/routes/post.ts

@@ -1,9 +1,10 @@
-import { Router, type Request, type Response } from 'express';
+import { type Request, type Response, Router } from 'express';
+
+import { MAX_TOKEN_LENGTH, MIN_TOKEN_LENGTH } from '../constants.js';
+import type { HashResult } from '../modules/v4/hash.js';
 import { chatStorage, ticTacToeStorage } from '../storage/index.js';
-import { MIN_TOKEN_LENGTH, MAX_TOKEN_LENGTH } from '../constants.js';
-import { error } from '../utils/response.js';
 import { since } from '../utils/helpers.js';
-import type { HashResult } from '../modules/v4/hash.js';
+import { error } from '../utils/response.js';
 
 const router = Router();
 

package/src/storage/index.ts

@@ -1,4 +1,4 @@
-import type { ChatStorage, TicTacToeStorage, IpLimits } from '../types/storage.js';
+import type { ChatStorage, IpLimits, TicTacToeStorage } from '../types/storage.js';
 
 export const ipLimits: IpLimits = {};
 

package/src/utils/response.ts

@@ -1,4 +1,5 @@
 import type { Response } from 'express';
+
 import { DOCS_URL, STATUS_MESSAGES } from '../constants.js';
 
 /**

package/tests/integration/api.test.ts

@@ -1,7 +1,8 @@
-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 type { AddressInfo } from 'node:net';
+import { after, before, describe, test } from 'node:test';
+
 import app from '../../src/app.js';
 
 let server: Server;
@@ -558,6 +559,90 @@ describe('Payload size limit', () => {
     });
 });
 
+describe('GET /v4/headers', () => {
+    test('returns headers object with count, ip, method, url', async () => {
+        const { status, body } = await getJson('/v4/headers');
+        assert.equal(status, 200);
+        assert.ok(typeof body.count === 'number');
+        assert.ok(typeof body.headers === 'object');
+        assert.ok('method' in body);
+        assert.equal(body.method, 'GET');
+        assert.ok((body.url as string).includes('/v4/headers'));
+    });
+
+    test('filter param returns only matching headers', async () => {
+        const { body } = await getJson('/v4/headers?filter=host');
+        const headers = body.headers as Record<string, unknown>;
+        assert.ok('host' in headers);
+        assert.equal(body.count, 1);
+    });
+
+    test('cookie header is redacted', async () => {
+        const res = await fetch(`${baseUrl}/v4/headers`, {
+            headers: { Cookie: 'session=secret123' },
+        });
+        const body = (await res.json()) as Record<string, unknown>;
+        const headers = body.headers as Record<string, unknown>;
+        assert.equal(headers['cookie'], '[redacted]');
+    });
+});
+
+describe('GET /v4/ip', () => {
+    test('returns valid ip result with no address param', async () => {
+        const { status, body } = await getJson('/v4/ip');
+        assert.equal(status, 200);
+        assert.ok(['IPv4', 'IPv6'].includes(body.version as string));
+        assert.ok(typeof body.binary === 'string');
+        assert.ok(typeof body.reverse === 'string');
+    });
+
+    test('loopback 127.0.0.1', async () => {
+        const { status, body } = await getJson('/v4/ip?address=127.0.0.1');
+        assert.equal(status, 200);
+        assert.equal(body.type, 'loopback');
+        assert.equal(body.version, 'IPv4');
+    });
+
+    test('private 192.168.1.1', async () => {
+        const { body } = await getJson('/v4/ip?address=192.168.1.1');
+        assert.equal(body.type, 'private');
+        assert.equal(body.decimal, 3232235777);
+    });
+
+    test('invalid address returns 400', async () => {
+        const { status } = await getJson('/v4/ip?address=notanip');
+        assert.equal(status, 400);
+    });
+});
+
+describe('GET /v4/agent', () => {
+    test('returns parsed result with browser, os, device, engine, bot', async () => {
+        const { status, body } = await getJson('/v4/agent');
+        assert.equal(status, 200);
+        assert.ok(typeof body.browser === 'object');
+        assert.ok(typeof body.os === 'object');
+        assert.ok(typeof body.device === 'object');
+        assert.ok(typeof body.engine === 'object');
+        assert.ok(typeof body.bot === 'boolean');
+    });
+
+    test('custom ua param is parsed', async () => {
+        const ua = encodeURIComponent(
+            'Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:121.0) Gecko/20100101 Firefox/121.0',
+        );
+        const { body } = await getJson(`/v4/agent?ua=${ua}`);
+        const browser = body.browser as Record<string, string>;
+        assert.equal(browser.name, 'Firefox');
+        assert.equal(browser.major, '121');
+    });
+
+    test('bot ua detected', async () => {
+        const ua = encodeURIComponent('Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)');
+        const { body } = await getJson(`/v4/agent?ua=${ua}`);
+        assert.equal(body.bot, true);
+    });
+});
+
 describe('Prototype access on dynamic endpoints', () => {
     test('algorithms?method=toString returns 400', async () => {
         const { status } = await getJson('/v4/algorithms?method=toString');

package/tests/unit/agent.test.ts

@@ -0,0 +1,113 @@
+import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
+import agent from '../../src/modules/v4/agent.js';
+
+const CHROME_MAC =
+    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36';
+const FIREFOX_WIN = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:121.0) Gecko/20100101 Firefox/121.0';
+const SAFARI_IPHONE =
+    'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1';
+const EDGE_WIN =
+    'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36 Edg/120.0.0.0';
+const GOOGLEBOT = 'Mozilla/5.0 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)';
+const IPAD =
+    'Mozilla/5.0 (iPad; CPU OS 16_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/16.0 Mobile/15E148 Safari/604.1';
+
+describe('agent', () => {
+    describe('browser detection', () => {
+        test('Chrome on macOS', () => {
+            const r = agent(CHROME_MAC);
+            assert.equal(r.browser.name, 'Chrome');
+            assert.equal(r.browser.major, '120');
+        });
+
+        test('Firefox on Windows', () => {
+            const r = agent(FIREFOX_WIN);
+            assert.equal(r.browser.name, 'Firefox');
+            assert.equal(r.browser.major, '121');
+        });
+
+        test('Safari on iPhone', () => {
+            const r = agent(SAFARI_IPHONE);
+            assert.equal(r.browser.name, 'Safari');
+        });
+
+        test('Edge detected before Chrome (both present in UA)', () => {
+            const r = agent(EDGE_WIN);
+            assert.equal(r.browser.name, 'Edge');
+        });
+
+        test('unknown browser returns unknown', () => {
+            const r = agent('UnknownBrowser/1.0');
+            assert.equal(r.browser.name, 'unknown');
+        });
+    });
+
+    describe('OS detection', () => {
+        test('macOS from Chrome UA', () => {
+            const r = agent(CHROME_MAC);
+            assert.equal(r.os.name, 'macOS');
+            assert.equal(r.os.version, '10.15.7');
+        });
+
+        test('Windows 10/11 from Firefox UA', () => {
+            const r = agent(FIREFOX_WIN);
+            assert.equal(r.os.name, 'Windows 10/11');
+        });
+
+        test('iOS from iPhone UA', () => {
+            const r = agent(SAFARI_IPHONE);
+            assert.equal(r.os.name, 'iOS');
+            assert.equal(r.os.version, '17.0');
+        });
+    });
+
+    describe('device detection', () => {
+        test('desktop from Chrome macOS', () => {
+            assert.equal(agent(CHROME_MAC).device.type, 'desktop');
+        });
+
+        test('mobile from iPhone UA', () => {
+            assert.equal(agent(SAFARI_IPHONE).device.type, 'mobile');
+        });
+
+        test('tablet from iPad UA', () => {
+            assert.equal(agent(IPAD).device.type, 'tablet');
+        });
+
+        test('Apple vendor from iPhone', () => {
+            assert.equal(agent(SAFARI_IPHONE).device.vendor, 'Apple');
+        });
+    });
+
+    describe('engine detection', () => {
+        test('Chrome uses Blink', () => {
+            assert.equal(agent(CHROME_MAC).engine.name, 'Blink');
+        });
+
+        test('Firefox uses Gecko', () => {
+            assert.equal(agent(FIREFOX_WIN).engine.name, 'Gecko');
+        });
+
+        test('Edge uses Blink', () => {
+            assert.equal(agent(EDGE_WIN).engine.name, 'Blink');
+        });
+    });
+
+    describe('bot detection', () => {
+        test('Googlebot is a bot', () => {
+            assert.equal(agent(GOOGLEBOT).bot, true);
+        });
+
+        test('Chrome is not a bot', () => {
+            assert.equal(agent(CHROME_MAC).bot, false);
+        });
+    });
+
+    describe('errors', () => {
+        test('throws on empty string', () => {
+            assert.throws(() => agent(''), /required/);
+        });
+    });
+});

package/tests/unit/algorithms.test.ts

@@ -1,5 +1,6 @@
-import { test, describe } from 'node:test';
 import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
 import {
     anagram,
     factorial,

package/tests/unit/captcha.test.ts

@@ -1,5 +1,6 @@
-import { test, describe } from 'node:test';
 import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
 import captcha from '../../src/modules/v4/captcha.js';
 
 const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47]);

package/tests/unit/chat.test.ts

@@ -1,5 +1,6 @@
-import { test, describe } from 'node:test';
 import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
 import chat from '../../src/modules/v4/chat.js';
 import type { ChatStorage } from '../../src/types/storage.js';
 

package/tests/unit/color.test.ts

@@ -1,5 +1,6 @@
-import { test, describe } from 'node:test';
 import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
 import color from '../../src/modules/v4/color.js';
 
 describe('color', () => {

package/tests/unit/convert.test.ts

@@ -1,5 +1,6 @@
-import { test, describe } from 'node:test';
 import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
 import convert from '../../src/modules/v4/convert.js';
 
 describe('convert', () => {

package/tests/unit/dice.test.ts

@@ -1,5 +1,6 @@
-import { test, describe } from 'node:test';
 import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
 import dice from '../../src/modules/v4/dice.js';
 
 describe('dice', () => {

package/tests/unit/domain.test.ts

@@ -1,5 +1,6 @@
-import { test, describe } from 'node:test';
 import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
 import domain from '../../src/modules/v4/domain.js';
 
 describe('domain', () => {

package/tests/unit/encode.test.ts

@@ -1,16 +1,17 @@
-import { test, describe } from 'node:test';
 import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
 import {
-    base64encode,
     base64decode,
-    urlencode,
-    urldecode,
+    base64encode,
+    binary,
+    caesar,
     morse,
-    unmorse,
     rot13,
-    caesar,
-    binary,
     unbinary,
+    unmorse,
+    urldecode,
+    urlencode,
 } from '../../src/modules/v4/encode.js';
 
 describe('encode', () => {

package/tests/unit/geo.test.ts

@@ -1,5 +1,6 @@
-import { test, describe } from 'node:test';
 import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
 import geo from '../../src/modules/v4/geo.js';
 
 describe('geo', () => {

package/tests/unit/hash.test.ts

@@ -1,5 +1,6 @@
-import { test, describe } from 'node:test';
 import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
 import hash from '../../src/modules/v4/hash.js';
 
 describe('hash', () => {

package/tests/unit/hyperplanning.test.ts

@@ -1,5 +1,6 @@
-import { test, describe, before, after } from 'node:test';
 import { strict as assert } from 'node:assert';
+import { after, before, describe, test } from 'node:test';
+
 import hyperplanning from '../../src/modules/v4/hyperplanning.js';
 
 const ORIGINAL_FETCH = globalThis.fetch;

package/tests/unit/ip.test.ts

@@ -0,0 +1,140 @@
+import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
+import ip from '../../src/modules/v4/ip.js';
+
+describe('ip', () => {
+    describe('IPv4 — type detection', () => {
+        test('public IP returns public type and class A', () => {
+            const result = ip('8.8.8.8');
+            assert.equal(result.version, 'IPv4');
+            assert.equal(result.type, 'public');
+            assert.equal(result.class, 'A');
+        });
+
+        test('private 10.x.x.x', () => {
+            const result = ip('10.0.0.1');
+            assert.equal(result.type, 'private');
+            assert.equal(result.range, '10.0.0.0/8');
+        });
+
+        test('private 172.16-31.x.x', () => {
+            const result = ip('172.16.0.1');
+            assert.equal(result.type, 'private');
+            assert.equal(result.range, '172.16.0.0/12');
+        });
+
+        test('private 192.168.x.x', () => {
+            const result = ip('192.168.1.1');
+            assert.equal(result.type, 'private');
+            assert.equal(result.class, 'C');
+            assert.equal(result.range, '192.168.0.0/16');
+        });
+
+        test('loopback 127.0.0.1', () => {
+            const result = ip('127.0.0.1');
+            assert.equal(result.type, 'loopback');
+            assert.equal(result.range, '127.0.0.0/8');
+        });
+
+        test('link-local 169.254.x.x', () => {
+            const result = ip('169.254.1.1');
+            assert.equal(result.type, 'link-local');
+        });
+
+        test('multicast 224.x.x.x', () => {
+            const result = ip('224.0.0.1');
+            assert.equal(result.type, 'multicast');
+        });
+
+        test('broadcast 255.255.255.255', () => {
+            const result = ip('255.255.255.255');
+            assert.equal(result.type, 'broadcast');
+            assert.equal(result.class, 'E');
+        });
+    });
+
+    describe('IPv4 — representations', () => {
+        test('binary of 192.168.1.1', () => {
+            const result = ip('192.168.1.1');
+            assert.equal(result.binary, '11000000.10101000.00000001.00000001');
+        });
+
+        test('decimal of 192.168.1.1', () => {
+            const result = ip('192.168.1.1');
+            assert.equal(result.decimal, 3232235777);
+        });
+
+        test('decimal of 8.8.8.8', () => {
+            const result = ip('8.8.8.8');
+            assert.equal(result.decimal, 134744072);
+        });
+
+        test('reverse DNS of 192.168.1.1', () => {
+            const result = ip('192.168.1.1');
+            assert.equal(result.reverse, '1.1.168.192.in-addr.arpa');
+        });
+
+        test('class B for 128.x', () => {
+            assert.equal(ip('128.0.0.1').class, 'B');
+        });
+
+        test('class C for 192.x (non-private)', () => {
+            assert.equal(ip('200.0.0.1').class, 'C');
+        });
+    });
+
+    describe('IPv6', () => {
+        test('loopback ::1', () => {
+            const result = ip('::1');
+            assert.equal(result.version, 'IPv6');
+            assert.equal(result.type, 'loopback');
+            assert.equal(result.range, '::1/128');
+        });
+
+        test('link-local fe80::1', () => {
+            const result = ip('fe80::1');
+            assert.equal(result.type, 'link-local');
+            assert.equal(result.range, 'fe80::/10');
+        });
+
+        test('unique-local fc00::1', () => {
+            const result = ip('fc00::1');
+            assert.equal(result.type, 'private');
+            assert.equal(result.range, 'fc00::/7');
+        });
+
+        test('multicast ff02::1', () => {
+            const result = ip('ff02::1');
+            assert.equal(result.type, 'multicast');
+        });
+
+        test(':: expansion produces 8 groups', () => {
+            const result = ip('::1');
+            assert.equal(result.ip.split(':').length, 8);
+        });
+
+        test('reverse DNS ends in .ip6.arpa', () => {
+            const result = ip('::1');
+            assert.ok(result.reverse.endsWith('.ip6.arpa'));
+        });
+    });
+
+    describe('errors', () => {
+        test('throws on empty string', () => {
+            assert.throws(() => ip(''), /required/);
+        });
+
+        test('throws on invalid IPv4 octet > 255', () => {
+            assert.throws(() => ip('256.0.0.1'), /Invalid IPv4/);
+        });
+
+        test('throws on incomplete IPv4', () => {
+            assert.throws(() => ip('192.168.1'), /Invalid IPv4/);
+        });
+
+        test('throws on plain string', () => {
+            assert.throws(() => ip('notanip'), /Invalid IP address format/);
+        });
+    });
+});

package/tests/unit/levenshtein.test.ts

@@ -1,5 +1,6 @@
-import { test, describe } from 'node:test';
 import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
 import levenshtein from '../../src/modules/v4/levenshtein.js';
 
 describe('levenshtein', () => {

package/tests/unit/palette.test.ts

@@ -1,5 +1,6 @@
-import { test, describe } from 'node:test';
 import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
 import palette from '../../src/modules/v4/palette.js';
 
 describe('palette', () => {

package/tests/unit/personal.test.ts

@@ -1,5 +1,6 @@
-import { test, describe } from 'node:test';
 import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
 import personal from '../../src/modules/v4/personal.js';
 
 describe('personal', () => {

package/tests/unit/placeholder.test.ts

@@ -1,5 +1,6 @@
-import { test, describe } from 'node:test';
 import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
 import placeholder from '../../src/modules/v4/placeholder.js';
 
 describe('placeholder', () => {

package/tests/unit/qrcode.test.ts

@@ -1,5 +1,6 @@
-import { test, describe } from 'node:test';
 import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
 import qrcode from '../../src/modules/v4/qrcode.js';
 
 const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47]);

package/tests/unit/statistics.test.ts

@@ -1,5 +1,6 @@
-import { test, describe } from 'node:test';
 import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
 import statistics from '../../src/modules/v4/statistics.js';
 
 describe('statistics', () => {

package/tests/unit/text.test.ts

@@ -1,6 +1,7 @@
-import { test, describe } from 'node:test';
 import { strict as assert } from 'node:assert';
-import { slug, stats, lorem, number } from '../../src/modules/v4/text.js';
+import { describe, test } from 'node:test';
+
+import { lorem, number, slug, stats } from '../../src/modules/v4/text.js';
 
 describe('text', () => {
     describe('slug', () => {