@20syldev/api 4.6.0 → 4.8.0

package/src/routes/get.ts

@@ -3,10 +3,12 @@ import { type Request, type Response, Router } from 'express';
 import { env } from '../config/env.js';
 import { versions } from '../config/versions.js';
 import { DOCS_URL, GITHUB_CACHE_TTL } from '../constants.js';
+import type { AddressResult } from '../modules/v4/address.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 { PasswordResult } from '../modules/v4/password.js';
 import type { QRCodeOptions, QRCodeResult } from '../modules/v4/qrcode.js';
 import { chatStorage, ipLimits } from '../storage/index.js';
 import { since } from '../utils/helpers.js';
@@ -176,6 +178,27 @@ router.get('/:version/convert', (req: Request, res: Response) => {
     }
 });
 
+// Generate a fictional postal address
+router.get('/:version/address', (req: Request, res: Response) => {
+    const { country, count } = req.query;
+    const { version } = req.params;
+
+    const addressFn = (req.module as { address?: (c?: string, n?: number) => AddressResult }).address;
+    if (!addressFn) {
+        error(res, 404, `Endpoint not available in ${version}.`, `${version}/address`);
+        return;
+    }
+
+    const parsedCount = count !== undefined ? parseInt(count as string, 10) : 1;
+
+    try {
+        const result = addressFn(country as string | undefined, parsedCount);
+        res.jsonResponse(result);
+    } catch (err) {
+        error(res, 400, (err as Error).message, `${req.version}/address`);
+    }
+});
+
 // Echo request headers
 router.get('/:version/headers', (req: Request, res: Response) => {
     const redacted = new Set(['authorization', 'cookie', 'set-cookie', 'proxy-authorization']);
@@ -234,6 +257,34 @@ router.get('/:version/domain', (req: Request, res: Response) => {
     }
 });
 
+// Parse a cron expression and compute next execution dates
+router.get('/:version/cron', (req: Request, res: Response) => {
+    const { expr, count, from, timezone } = req.query;
+    const { version } = req.params;
+
+    const cronFn = (req.module as { cron?: (e: string, n?: number, f?: string, tz?: string) => unknown }).cron;
+    if (!cronFn) {
+        error(res, 404, `Endpoint not available in ${version}.`, `${version}/cron`);
+        return;
+    }
+    if (!expr) {
+        error(res, 400, 'Please provide a cron expression (?expr=* * * * *)', `${version}/cron`);
+        return;
+    }
+
+    try {
+        const result = cronFn(
+            expr as string,
+            count !== undefined ? parseInt(count as string, 10) : 5,
+            from as string | undefined,
+            (timezone as string) ?? 'UTC',
+        );
+        res.jsonResponse(result);
+    } catch (err) {
+        error(res, 400, (err as Error).message, `${req.version}/cron`);
+    }
+});
+
 // RPG Dice roller
 router.get('/:version/dice', (req: Request, res: Response) => {
     const { roll } = req.query;
@@ -376,6 +427,41 @@ router.get('/:version/palette', (req: Request, res: Response) => {
     }
 });
 
+// Generate a password or passphrase
+router.get('/:version/password', (req: Request, res: Response) => {
+    const { type, length, uppercase, lowercase, digits, symbols, exclude, count, separator } = req.query;
+    const { version } = req.params;
+
+    const passwordFn = (
+        req.module as { password?: (t: string, l: number, o: Record<string, unknown>) => PasswordResult }
+    ).password;
+    if (!passwordFn) {
+        error(res, 404, `Endpoint not available in ${version}.`, `${version}/password`);
+        return;
+    }
+
+    const parseBool = (v: unknown, def: boolean): boolean => (v === undefined ? def : v !== 'false');
+
+    try {
+        const result = passwordFn(
+            (type as string) ?? 'random',
+            length !== undefined ? parseInt(length as string, 10) : 16,
+            {
+                uppercase: parseBool(uppercase, true),
+                lowercase: parseBool(lowercase, true),
+                digits: parseBool(digits, true),
+                symbols: parseBool(symbols, false),
+                exclude: (exclude as string) ?? '',
+                count: count !== undefined ? parseInt(count as string, 10) : 1,
+                separator: (separator as string) ?? '-',
+            },
+        );
+        res.jsonResponse(result);
+    } catch (err) {
+        error(res, 400, (err as Error).message, `${req.version}/password`);
+    }
+});
+
 // Generate personal data
 router.get('/:version/personal', (req: Request, res: Response) => {
     try {
@@ -451,6 +537,33 @@ router.get('/:version/qrcode', async (req: Request, res: Response) => {
     }
 });
 
+// Test a regex pattern against a text
+router.get('/:version/regex', (req: Request, res: Response) => {
+    const { pattern, text, flags } = req.query;
+    const { version } = req.params;
+
+    const regexFn = (req.module as { regex?: (p: string, t: string, f?: string) => unknown }).regex;
+    if (!regexFn) {
+        error(res, 404, `Endpoint not available in ${version}.`, `${version}/regex`);
+        return;
+    }
+    if (!pattern) {
+        error(res, 400, 'Please provide a pattern (?pattern={regex})', `${version}/regex`);
+        return;
+    }
+    if (!text) {
+        error(res, 400, 'Please provide a text (&text={string})', `${version}/regex`);
+        return;
+    }
+
+    try {
+        const result = regexFn(pattern as string, text as string, flags as string | undefined);
+        res.jsonResponse(result);
+    } catch (err) {
+        error(res, 400, (err as Error).message, `${req.version}/regex`);
+    }
+});
+
 // Statistics on a list of numbers
 router.get('/:version/statistics', (req: Request, res: Response) => {
     const { values } = req.query;
@@ -551,60 +664,26 @@ router.get('/:version/tic-tac-toe/list', (_req: Request, res: Response) => {
     error(res, 405, 'This endpoint only supports POST requests.');
 });
 
-// Display or generate time informations
+// Display or generate time informations, or compute a countdown
 router.get('/:version/time', (req: Request, res: Response) => {
-    const { type = 'live', start, end, format, timezone } = req.query;
-
-    const validFormats = [
-        'iso',
-        'utc',
-        'timestamp',
-        'locale',
-        'date',
-        'time',
-        'year',
-        'month',
-        'day',
-        'hour',
-        'minute',
-        'second',
-        'ms',
-        'dayOfWeek',
-        'dayOfYear',
-        'weekNumber',
-        'timezone',
-        'timezoneOffset',
-    ];
-    const validTimezones = ['UTC', 'America/New_York', 'Europe/Paris', 'Asia/Tokyo', 'Australia/Sydney'];
-
-    if (type !== 'live' && type !== 'random') {
-        error(res, 400, 'Please provide a valid type (?type={type})', `${req.version}/time`);
-        return;
-    }
-    if (start && !Date.parse(start as string)) {
-        error(res, 400, 'Please provide a valid start date (?start={YYYY-MM-DD})', `${req.version}/time`);
-        return;
-    }
-    if (end && !Date.parse(end as string)) {
-        error(res, 400, 'Please provide a valid end date (?end={YYYY-MM-DD})', `${req.version}/time`);
-        return;
-    }
-    if (format && !validFormats.includes(format as string)) {
-        error(res, 400, 'Please provide a valid format (?format={format})', `${req.version}/time`);
-        return;
-    }
-    if (timezone && !validTimezones.includes(timezone as string)) {
-        error(res, 400, 'Please provide a valid timezone (?timezone={timezone})', `${req.version}/time`);
-        return;
-    }
+    const { type = 'live', start, end, format, timezone, target } = req.query;
 
     try {
-        const time = req.module.time(
+        const timeFn = req.module.time as (
+            t: string,
+            s?: string,
+            e?: string,
+            f?: string,
+            tz?: string,
+            target?: string,
+        ) => Record<string, unknown>;
+        const time = timeFn(
             type as string,
             start as string,
             end as string,
             format as string,
             timezone as string,
+            target as string,
         );
         res.jsonResponse(time);
     } catch (err) {

package/tests/integration/api.test.ts

@@ -331,6 +331,19 @@ describe('GET /v4/time', () => {
         assert.ok(ts >= new Date('2020-01-01').getTime());
         assert.ok(ts <= new Date('2020-12-31').getTime());
     });
+
+    test('countdown future returns direction and remaining', async () => {
+        const future = new Date(Date.now() + 10 * 24 * 3600 * 1000).toISOString();
+        const { status, body } = await getJson(`/v4/time?type=countdown&target=${encodeURIComponent(future)}`);
+        assert.equal(status, 200);
+        assert.equal(body.direction, 'future');
+        assert.ok(typeof body.human === 'string');
+    });
+
+    test('countdown missing target returns 400', async () => {
+        const { status } = await getJson('/v4/time?type=countdown');
+        assert.equal(status, 400);
+    });
 });
 
 describe('GET /v4/username', () => {
@@ -643,6 +656,104 @@ describe('GET /v4/agent', () => {
     });
 });
 
+describe('GET /v4/address', () => {
+    test('returns one address by default', async () => {
+        const { status, body } = await getJson('/v4/address');
+        assert.equal(status, 200);
+        assert.equal((body.addresses as unknown[]).length, 1);
+    });
+
+    test('country=fr returns a French address', async () => {
+        const { body } = await getJson('/v4/address?country=fr');
+        const a = (body.addresses as Record<string, string>[])[0]!;
+        assert.equal(a.countryCode, 'FR');
+    });
+
+    test('count=3 returns 3 addresses', async () => {
+        const { body } = await getJson('/v4/address?count=3');
+        assert.equal((body.addresses as unknown[]).length, 3);
+    });
+
+    test('unknown country returns 400', async () => {
+        const { status } = await getJson('/v4/address?country=xx');
+        assert.equal(status, 400);
+    });
+});
+
+describe('GET /v4/password', () => {
+    test('returns one password by default', async () => {
+        const { status, body } = await getJson('/v4/password');
+        assert.equal(status, 200);
+        assert.equal((body.passwords as string[]).length, 1);
+        assert.equal((body.passwords as string[])[0]!.length, 16);
+    });
+
+    test('length param is respected', async () => {
+        const { body } = await getJson('/v4/password?length=32');
+        assert.equal((body.passwords as string[])[0]!.length, 32);
+    });
+
+    test('passphrase mode returns words', async () => {
+        const { body } = await getJson('/v4/password?type=passphrase&length=4');
+        assert.equal(body.type, 'passphrase');
+        assert.equal((body.passwords as string[])[0]!.split('-').length, 4);
+    });
+
+    test('count=5 returns 5 passwords', async () => {
+        const { body } = await getJson('/v4/password?count=5');
+        assert.equal((body.passwords as string[]).length, 5);
+    });
+
+    test('no charset active returns 400', async () => {
+        const { status } = await getJson('/v4/password?uppercase=false&lowercase=false&digits=false&symbols=false');
+        assert.equal(status, 400);
+    });
+});
+
+describe('GET /v4/cron', () => {
+    test('returns next dates for * * * * *', async () => {
+        const { status, body } = await getJson('/v4/cron?expr=*%20*%20*%20*%20*');
+        assert.equal(status, 200);
+        assert.equal((body.next as string[]).length, 5);
+        assert.ok(typeof body.description === 'string');
+    });
+
+    test('count param is respected', async () => {
+        const { body } = await getJson('/v4/cron?expr=*%20*%20*%20*%20*&count=3');
+        assert.equal((body.next as string[]).length, 3);
+    });
+
+    test('invalid expression returns 400', async () => {
+        const { status } = await getJson('/v4/cron?expr=invalid');
+        assert.equal(status, 400);
+    });
+
+    test('missing expr returns 400', async () => {
+        const { status } = await getJson('/v4/cron');
+        assert.equal(status, 400);
+    });
+});
+
+describe('GET /v4/regex', () => {
+    test('basic match returns count and matches', async () => {
+        const { status, body } = await getJson('/v4/regex?pattern=hello&text=hello%20world');
+        assert.equal(status, 200);
+        assert.equal(body.valid, true);
+        assert.ok((body.count as number) >= 1);
+    });
+
+    test('invalid pattern returns valid: false with 200', async () => {
+        const { status, body } = await getJson('/v4/regex?pattern=%5Binvalid&text=hello');
+        assert.equal(status, 200);
+        assert.equal(body.valid, false);
+    });
+
+    test('missing pattern returns 400', async () => {
+        const { status } = await getJson('/v4/regex?text=hello');
+        assert.equal(status, 400);
+    });
+});
+
 describe('Prototype access on dynamic endpoints', () => {
     test('algorithms?method=toString returns 400', async () => {
         const { status } = await getJson('/v4/algorithms?method=toString');

package/tests/unit/address.test.ts

@@ -0,0 +1,84 @@
+import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
+import address from '../../src/modules/v4/address.js';
+
+describe('address', () => {
+    describe('default behavior', () => {
+        test('returns an addresses array with one entry by default', () => {
+            const r = address();
+            assert.equal(r.addresses.length, 1);
+        });
+
+        test('each address has required fields', () => {
+            const r = address();
+            const a = r.addresses[0]!;
+            assert.ok(a.street);
+            assert.ok(a.city);
+            assert.ok(a.zip);
+            assert.ok(a.state);
+            assert.ok(a.country);
+            assert.ok(a.countryCode);
+        });
+    });
+
+    describe('country filtering', () => {
+        test('fr returns a French address', () => {
+            const r = address('fr');
+            assert.equal(r.addresses[0]!.countryCode, 'FR');
+            assert.equal(r.addresses[0]!.country, 'France');
+        });
+
+        test('us returns a US address', () => {
+            const r = address('us');
+            assert.equal(r.addresses[0]!.countryCode, 'US');
+            assert.equal(r.addresses[0]!.country, 'United States');
+        });
+
+        test('uk returns a UK address', () => {
+            const r = address('uk');
+            assert.equal(r.addresses[0]!.countryCode, 'UK');
+        });
+
+        test('de returns a German address', () => {
+            const r = address('de');
+            assert.equal(r.addresses[0]!.countryCode, 'DE');
+        });
+
+        test('es returns a Spanish address', () => {
+            const r = address('es');
+            assert.equal(r.addresses[0]!.countryCode, 'ES');
+        });
+
+        test('country code is case-insensitive', () => {
+            const r = address('FR');
+            assert.equal(r.addresses[0]!.countryCode, 'FR');
+        });
+    });
+
+    describe('count', () => {
+        test('count=5 returns 5 addresses', () => {
+            const r = address('fr', 5);
+            assert.equal(r.addresses.length, 5);
+        });
+
+        test('count=10 returns 10 addresses', () => {
+            const r = address('us', 10);
+            assert.equal(r.addresses.length, 10);
+        });
+    });
+
+    describe('errors', () => {
+        test('unknown country throws', () => {
+            assert.throws(() => address('xx'), /Unknown country code/);
+        });
+
+        test('count=0 throws', () => {
+            assert.throws(() => address('fr', 0), /Count must be between/);
+        });
+
+        test('count=11 throws', () => {
+            assert.throws(() => address('fr', 11), /Count must be between/);
+        });
+    });
+});

package/tests/unit/cron.test.ts

@@ -0,0 +1,110 @@
+import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
+import cron from '../../src/modules/v4/cron.js';
+
+// Fixed reference point: a known Monday at 08:45 UTC
+const FROM = '2026-01-05T08:45:00Z'; // Monday
+
+describe('cron', () => {
+    describe('every minute', () => {
+        test('* * * * * returns 5 consecutive minutes', () => {
+            const r = cron('* * * * *', 5, FROM);
+            assert.equal(r.next.length, 5);
+            // First result should be the next minute after FROM
+            assert.ok(r.next[0]!.startsWith('2026-01-05T08:46'));
+        });
+
+        test('description is "Every minute"', () => {
+            const r = cron('* * * * *', 1, FROM);
+            assert.equal(r.description, 'Every minute');
+        });
+    });
+
+    describe('every N minutes', () => {
+        test('*/15 * * * * returns results 15 minutes apart', () => {
+            const r = cron('*/15 * * * *', 3, FROM);
+            assert.equal(r.next.length, 3);
+            assert.ok(r.next[0]!.includes('T09:00'));
+            assert.ok(r.next[1]!.includes('T09:15'));
+            assert.ok(r.next[2]!.includes('T09:30'));
+        });
+
+        test('description mentions every 15 minutes', () => {
+            const r = cron('*/15 * * * *', 1, FROM);
+            assert.match(r.description, /Every 15 minutes/);
+        });
+    });
+
+    describe('at fixed time', () => {
+        test('0 9 * * 1-5 fires at 09:00 on weekdays', () => {
+            const r = cron('0 9 * * 1-5', 3, FROM);
+            // Next Monday 09:00 is same day
+            assert.ok(r.next[0]!.includes('T09:00'));
+            // All results should be on weekdays (Mon–Fri)
+            for (const date of r.next) {
+                const d = new Date(date);
+                const dow = d.getUTCDay();
+                assert.ok(dow >= 1 && dow <= 5, `Expected weekday, got ${dow}`);
+            }
+        });
+
+        test('description includes Monday through Friday', () => {
+            const r = cron('0 9 * * 1-5', 1, FROM);
+            assert.match(r.description, /Monday through Friday/);
+        });
+    });
+
+    describe('plan example', () => {
+        test('*/15 9-17 * * 1-5 fires between 09:00 and 17:45 on weekdays', () => {
+            const r = cron('*/15 9-17 * * 1-5', 5, FROM);
+            assert.equal(r.next.length, 5);
+            for (const date of r.next) {
+                const d = new Date(date);
+                const hour = d.getUTCHours();
+                assert.ok(hour >= 9 && hour <= 17);
+                const dow = d.getUTCDay();
+                assert.ok(dow >= 1 && dow <= 5);
+            }
+        });
+
+        test('description includes "Every 15 minutes"', () => {
+            const r = cron('*/15 9-17 * * 1-5', 1, FROM);
+            assert.match(r.description, /Every 15 minutes/);
+        });
+    });
+
+    describe('count', () => {
+        test('count=10 returns 10 results', () => {
+            const r = cron('* * * * *', 10, FROM);
+            assert.equal(r.next.length, 10);
+        });
+
+        test('count=1 returns 1 result', () => {
+            const r = cron('*/30 * * * *', 1, FROM);
+            assert.equal(r.next.length, 1);
+        });
+    });
+
+    describe('errors', () => {
+        test('missing expr throws', () => {
+            assert.throws(() => cron(''), /expression/);
+        });
+
+        test('too few fields throws', () => {
+            assert.throws(() => cron('* * * *'), /5 fields/);
+        });
+
+        test('invalid range throws', () => {
+            assert.throws(() => cron('60-70 * * * *'), /valid: 0-59/);
+        });
+
+        test('invalid timezone throws', () => {
+            assert.throws(() => cron('* * * * *', 5, undefined, 'Mars/Olympus'), /timezone/);
+        });
+
+        test('count out of range throws', () => {
+            assert.throws(() => cron('* * * * *', 21), /Count/);
+        });
+    });
+});

package/tests/unit/password.test.ts

@@ -0,0 +1,86 @@
+import { strict as assert } from 'node:assert';
+import { describe, test } from 'node:test';
+
+import password from '../../src/modules/v4/password.js';
+
+describe('password', () => {
+    describe('random mode', () => {
+        test('default returns one password of length 16', () => {
+            const r = password();
+            assert.equal(r.passwords.length, 1);
+            assert.equal(r.passwords[0]!.length, 16);
+            assert.equal(r.type, 'random');
+            assert.equal(r.length, 16);
+        });
+
+        test('length is respected', () => {
+            const r = password('random', 32);
+            assert.equal(r.passwords[0]!.length, 32);
+        });
+
+        test('no symbols when symbols=false', () => {
+            const r = password('random', 64, { symbols: false });
+            assert.ok(!/[!@#$%^&*()\-_=+[\]{}|;:,.<>?]/.test(r.passwords[0]!));
+        });
+
+        test('only digits when only digits enabled', () => {
+            const r = password('random', 16, { uppercase: false, lowercase: false, digits: true, symbols: false });
+            assert.ok(/^\d+$/.test(r.passwords[0]!));
+        });
+
+        test('exclude chars are absent from password', () => {
+            const r = password('random', 64, { exclude: 'aeiou' });
+            assert.ok(!/[aeiou]/.test(r.passwords[0]!));
+        });
+
+        test('count=5 returns 5 passwords', () => {
+            const r = password('random', 16, { count: 5 });
+            assert.equal(r.passwords.length, 5);
+        });
+
+        test('entropy and strength are present', () => {
+            const r = password();
+            assert.ok(typeof r.entropy === 'number');
+            assert.ok(['weak', 'moderate', 'strong', 'very_strong'].includes(r.strength));
+        });
+    });
+
+    describe('passphrase mode', () => {
+        test('returns words joined by separator', () => {
+            const r = password('passphrase', 4, { separator: '-' });
+            assert.equal(r.type, 'passphrase');
+            const words = r.passwords[0]!.split('-');
+            assert.equal(words.length, 4);
+        });
+
+        test('custom separator is used', () => {
+            const r = password('passphrase', 3, { separator: '.' });
+            assert.ok(r.passwords[0]!.includes('.'));
+        });
+    });
+
+    describe('errors', () => {
+        test('length below 8 throws', () => {
+            assert.throws(() => password('random', 4), /Length must be between/);
+        });
+
+        test('length above 128 throws', () => {
+            assert.throws(() => password('random', 200), /Length must be between/);
+        });
+
+        test('no charset active throws', () => {
+            assert.throws(
+                () => password('random', 16, { uppercase: false, lowercase: false, digits: false, symbols: false }),
+                /At least one character set/,
+            );
+        });
+
+        test('count above 20 throws', () => {
+            assert.throws(() => password('random', 16, { count: 21 }), /Count must be between/);
+        });
+
+        test('invalid type throws', () => {
+            assert.throws(() => password('invalid'), /Type must be/);
+        });
+    });
+});