@20syldev/api 4.2.0 → 4.4.0

package/src/modules/v4.ts

@@ -6,10 +6,13 @@ export { default as convert } from './v4/convert.js';
 export { default as dice } from './v4/dice.js';
 export { default as domain } from './v4/domain.js';
 export * as encode from './v4/encode.js';
+export { default as geo } from './v4/geo.js';
 export { default as hash } from './v4/hash.js';
 export { default as hyperplanning } from './v4/hyperplanning.js';
 export { default as levenshtein } from './v4/levenshtein.js';
+export { default as palette } from './v4/palette.js';
 export { default as personal } from './v4/personal.js';
+export { default as placeholder } from './v4/placeholder.js';
 export { default as qrcode } from './v4/qrcode.js';
 export { default as statistics } from './v4/statistics.js';
 export * as text from './v4/text.js';

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

@@ -5,6 +5,10 @@ import { ipLimits } from '../storage/index.js';
 import { chatStorage } from '../storage/index.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 { CaptchaOptions, CaptchaResult } from '../modules/v4/captcha.js';
+import type { ColorResult } from '../modules/v4/color.js';
 
 const router = Router();
 
@@ -72,16 +76,29 @@ router.get('/:version/algorithms', (req: Request, res: Response) => {
 
 // Generate captcha
 router.get('/:version/captcha', (req: Request, res: Response) => {
-    const text = req.query.text as string;
-
-    if (!text) {
-        error(res, 400, 'Please provide a valid argument (?text={text})', `${req.version}/captcha`);
-        return;
-    }
-
     try {
-        const result = req.module.captcha(text);
-        res.type('png').send(result);
+        if (since(req.version, 4)) {
+            const captchaFn = req.module.captcha as (o: CaptchaOptions) => CaptchaResult;
+            const result = captchaFn({
+                text: req.query.text as string | undefined,
+                length: req.query.length ? Number(req.query.length) : undefined,
+                width: req.query.width ? Number(req.query.width) : undefined,
+                height: req.query.height ? Number(req.query.height) : undefined,
+                noise: req.query.noise as CaptchaOptions['noise'],
+                bg: req.query.bg as string | undefined,
+                color: req.query.color as string | undefined,
+            });
+            res.set('X-Captcha-Text', result.text);
+            res.type('png').send(result.body);
+        } else {
+            const text = req.query.text as string;
+            if (!text) {
+                error(res, 400, 'Please provide a valid argument (?text={text})', `${req.version}/captcha`);
+                return;
+            }
+            const result = (req.module.captcha as (t: string) => Buffer)(text);
+            res.type('png').send(result);
+        }
     } catch (err) {
         error(res, 400, (err as Error).message, `${req.version}/captcha`);
     }
@@ -108,8 +125,15 @@ router.get('/:version/chat/private', (_req: Request, res: Response) => {
 // Generate color
 router.get('/:version/color', (req: Request, res: Response) => {
     try {
-        const result = req.module.color();
-        res.jsonResponse(result);
+        if (since(req.version, 4)) {
+            const colorFn = req.module.color as (hex?: string) => ColorResult;
+            const hex = req.query.hex as string | undefined;
+            const result = colorFn(hex || undefined);
+            res.jsonResponse(result);
+        } else {
+            const result = (req.module.color as () => Record<string, string>)();
+            res.jsonResponse(result);
+        }
     } catch (err) {
         error(res, 400, (err as Error).message, `${req.version}/color`);
     }
@@ -133,8 +157,18 @@ router.get('/:version/convert', (req: Request, res: Response) => {
     }
 
     try {
-        const result = req.module.convert(value as string, from as string, to as string);
-        res.jsonResponse(result);
+        if (since(req.version, 4)) {
+            const convertFn = req.module.convert as (v: number, f: string, t: string) => Record<string, unknown>;
+            const result = convertFn(Number(value), from as string, to as string);
+            res.jsonResponse(result);
+        } else {
+            const result = (req.module.convert as (v: string, f: string, t: string) => Record<string, unknown>)(
+                value as string,
+                from as string,
+                to as string,
+            );
+            res.jsonResponse(result);
+        }
     } catch (err) {
         error(res, 400, (err as Error).message, `${req.version}/convert`);
     }
@@ -196,6 +230,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 +299,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 +336,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;
@@ -262,8 +372,30 @@ router.get('/:version/qrcode', async (req: Request, res: Response) => {
     }
 
     try {
-        const result = await req.module.qrcode(url as string);
-        res.jsonResponse(result);
+        if (since(req.version, 4)) {
+            const qrcodeFn = req.module.qrcode as (o: QRCodeOptions) => Promise<QRCodeResult>;
+            const result = await qrcodeFn({
+                url: url as string,
+                size: req.query.size ? Number(req.query.size) : undefined,
+                margin: req.query.margin ? Number(req.query.margin) : undefined,
+                correction: req.query.correction as QRCodeOptions['correction'],
+                dark: req.query.dark as string | undefined,
+                light: req.query.light as string | undefined,
+                icon: req.query.icon as string | undefined,
+                iconSize: req.query.iconSize ? Number(req.query.iconSize) : undefined,
+                iconPadding: req.query.iconPadding ? Number(req.query.iconPadding) : undefined,
+                iconRadius: req.query.iconRadius ? Number(req.query.iconRadius) : undefined,
+                format: req.query.format as QRCodeOptions['format'],
+            });
+            if (result.contentType === 'application/json') {
+                res.jsonResponse(result.body);
+            } else {
+                res.type(result.contentType).send(result.body);
+            }
+        } else {
+            const result = await (req.module.qrcode as (u: string) => Promise<string>)(url as string);
+            res.jsonResponse(result);
+        }
     } catch (err) {
         error(res, 400, (err as Error).message, `${req.version}/qrcode`);
     }

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/src/routes/post.ts

@@ -2,6 +2,8 @@ import { Router, type Request, type Response } from 'express';
 import { chatStorage, ticTacToeStorage } from '../storage/index.js';
 import { MIN_TOKEN_LENGTH, MAX_TOKEN_LENGTH } from '../constants.js';
 import { error } from '../utils/response.js';
+import { since } from '../utils/helpers.js';
+import type { HashResult } from '../modules/v4/hash.js';
 
 const router = Router();
 
@@ -64,7 +66,7 @@ router.post('/:version/chat/private', (req: Request, res: Response) => {
 
 // Generate hash
 router.post('/:version/hash', (req: Request, res: Response) => {
-    const { text, method } = (req.body as Record<string, string>) || {};
+    const { text, method, encoding } = (req.body as Record<string, string>) || {};
 
     if (!text) {
         error(res, 400, 'Please provide a text (?text={text})', `${req.version}/hash`);
@@ -76,8 +78,14 @@ router.post('/:version/hash', (req: Request, res: Response) => {
     }
 
     try {
-        const result = req.module.hash(text, method);
-        res.jsonResponse(result);
+        if (since(req.version, 4)) {
+            const hashFn = req.module.hash as (t: string, m: string, e?: string) => HashResult;
+            const result = hashFn(text, method, encoding);
+            res.jsonResponse(result);
+        } else {
+            const result = (req.module.hash as (t: string, m: string) => Record<string, string>)(text, method);
+            res.jsonResponse(result);
+        }
     } catch (err) {
         error(res, 400, (err as Error).message, `${req.version}/hash`);
     }

package/src/utils/colors.ts

@@ -0,0 +1,91 @@
+/**
+ * Parses a hex color string into an RGB tuple.
+ *
+ * @param hex - Hex color string (#RRGGBB or RRGGBB)
+ * @returns RGB tuple [r, g, b] with values 0-255
+ * @throws Error if the hex string is invalid
+ */
+export function hexToRgb(hex: string): [number, number, number] {
+    const clean = hex.replace('#', '');
+    if (!/^[0-9a-fA-F]{6}$/.test(clean)) throw new Error('Invalid HEX color (use #RRGGBB)');
+    return [parseInt(clean.slice(0, 2), 16), parseInt(clean.slice(2, 4), 16), parseInt(clean.slice(4, 6), 16)];
+}
+
+/**
+ * Converts HSL values to an RGB tuple.
+ *
+ * @param h - Hue in degrees (0-360)
+ * @param s - Saturation (0-1)
+ * @param l - Lightness (0-1)
+ * @returns RGB tuple [r, g, b] with values 0-255
+ */
+export function hslToRgb(h: number, s: number, l: number): [number, number, number] {
+    const c = (1 - Math.abs(2 * l - 1)) * s;
+    const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
+    const m = l - c / 2;
+    let r1 = 0,
+        g1 = 0,
+        b1 = 0;
+    if (h < 60) [r1, g1, b1] = [c, x, 0];
+    else if (h < 120) [r1, g1, b1] = [x, c, 0];
+    else if (h < 180) [r1, g1, b1] = [0, c, x];
+    else if (h < 240) [r1, g1, b1] = [0, x, c];
+    else if (h < 300) [r1, g1, b1] = [x, 0, c];
+    else [r1, g1, b1] = [c, 0, x];
+    return [Math.round((r1 + m) * 255), Math.round((g1 + m) * 255), Math.round((b1 + m) * 255)];
+}
+
+/**
+ * Validates and normalizes a hex color string, adding # if missing.
+ *
+ * @param value - Raw color value (with or without #)
+ * @param def - Default color if value is empty
+ * @returns Normalized hex color string with #
+ * @throws Error if the color format is invalid
+ */
+export function normalizeColor(value: string | undefined, def: string): string {
+    if (!value) return def;
+    const clean = value.startsWith('#') ? value : `#${value}`;
+    if (!/^#([0-9a-fA-F]{3}){1,2}$/.test(clean)) throw new Error('Invalid color (use hex like ff6600)');
+    return clean;
+}
+
+/**
+ * Formats an RGB tuple as a hex color string.
+ *
+ * @param r - Red channel (0-255)
+ * @param g - Green channel (0-255)
+ * @param b - Blue channel (0-255)
+ * @returns Hex color string (#rrggbb)
+ */
+export function rgbToHex(r: number, g: number, b: number): string {
+    return `#${[r, g, b].map((x) => x.toString(16).padStart(2, '0')).join('')}`;
+}
+
+/**
+ * Converts RGB values to an HSL tuple.
+ *
+ * @param r - Red channel (0-255)
+ * @param g - Green channel (0-255)
+ * @param b - Blue channel (0-255)
+ * @returns HSL tuple [h (0-360), s (0-1), l (0-1)]
+ */
+export function rgbToHsl(r: number, g: number, b: number): [number, number, number] {
+    const r1 = r / 255,
+        g1 = g / 255,
+        b1 = b / 255;
+    const max = Math.max(r1, g1, b1),
+        min = Math.min(r1, g1, b1);
+    const l = (max + min) / 2;
+
+    if (max === min) return [0, 0, l];
+
+    const d = max - min;
+    const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+    let h = 0;
+    if (max === r1) h = (g1 - b1) / d + (g1 < b1 ? 6 : 0);
+    else if (max === g1) h = (b1 - r1) / d + 2;
+    else h = (r1 - g1) / d + 4;
+
+    return [(h * 60 + 360) % 360, s, l];
+}

package/src/utils/helpers.ts

@@ -0,0 +1,90 @@
+/**
+ * Tracks requests per user and throws if the rate limit is exceeded.
+ *
+ * @param rateLimits - Store of timestamps per user
+ * @param userId - Identifier of the requesting user
+ * @param timestamp - Current timestamp in milliseconds
+ * @param window - Time window in milliseconds
+ * @param limit - Maximum requests allowed in the window
+ * @returns false if within limits
+ * @throws Error if rate limit is exceeded
+ */
+export function checkRateLimit(
+    rateLimits: Record<string, number[]>,
+    userId: string,
+    timestamp: number,
+    window = 10000,
+    limit = 50,
+): boolean {
+    rateLimits[userId] = (rateLimits[userId] ?? []).filter((ts) => timestamp - ts < window);
+
+    if (rateLimits[userId]!.length > limit) {
+        const remainingTime = Math.ceil((rateLimits[userId]![0]! + window - timestamp) / 1000);
+        throw new Error(`Rate limit exceeded. Try again in ${remainingTime} seconds.`);
+    }
+
+    rateLimits[userId]!.push(timestamp);
+    return false;
+}
+
+/**
+ * Parses a space-separated environment variable into an array.
+ *
+ * @param key - The environment variable name
+ * @returns The parsed array, or null if not set
+ */
+export function envList(key: string): string[] | null {
+    const v = process.env[key];
+    return v && v !== 'undefined' ? v.split(' ') : null;
+}
+
+/**
+ * Formats a Date to ISO string without timezone suffix.
+ *
+ * @param date - The date to format
+ * @returns ISO-formatted string without trailing Z
+ */
+export function formatDate(date: Date): string {
+    return new Date(date.getTime() - date.getTimezoneOffset() * 60000).toISOString().replace('Z', '');
+}
+
+/**
+ * Generates a random IPv4 address.
+ *
+ * @returns A string in the format "X.X.X.X"
+ */
+export function genIP(): string {
+    return `${randomNumber(0, 255)}.${randomNumber(0, 255)}.${randomNumber(0, 255)}.${randomNumber(0, 255)}`;
+}
+
+/**
+ * Returns a random element from an array.
+ *
+ * @param arr - The source array
+ * @returns A random element
+ */
+export function random<T>(arr: T[]): T {
+    return arr[Math.floor(Math.random() * arr.length)]!;
+}
+
+/**
+ * Returns a random integer between min and max (inclusive).
+ *
+ * @param min - Lower bound
+ * @param max - Upper bound
+ * @returns A random integer in [min, max]
+ */
+export function randomNumber(min: number, max: number): number {
+    return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+
+/**
+ * Checks if a version string is at least the given minimum.
+ *
+ * @param version - Version string (e.g. "v4")
+ * @param min - Minimum version number
+ * @returns true if the version is >= min
+ */
+export function since(version: string, min: number): boolean {
+    return parseInt(version.replace('v', '')) >= min;
+}

package/src/utils/response.ts

@@ -1,6 +1,14 @@
 import type { Response } from 'express';
 import { DOCS_URL, STATUS_MESSAGES } from '../constants.js';
 
+/**
+ * Sends a standardized JSON error response.
+ *
+ * @param res - Express response object
+ * @param status - HTTP status code
+ * @param message - Error description
+ * @param docPath - Optional documentation path appended to the base URL
+ */
 export function error(res: Response, status: number, message: string, docPath?: string): void {
     res.status(status).jsonResponse({
         message: STATUS_MESSAGES[status] ?? 'Error',