@20syldev/api 4.4.0 → 4.6.0

package/src/modules/v4/geo.ts

@@ -23,6 +23,16 @@ function parseCoord(value: string, name: string, min: number, max: number): numb
     return n;
 }
 
+/**
+ * Calculates the great-circle distance and bearing between two geographic coordinates.
+ *
+ * @param lat1 - Latitude of the first point (-90 to 90)
+ * @param lon1 - Longitude of the first point (-180 to 180)
+ * @param lat2 - Latitude of the second point (-90 to 90)
+ * @param lon2 - Longitude of the second point (-180 to 180)
+ * @returns Distance in km/miles/nautical miles, compass bearing, and both coordinates
+ * @throws Error if any coordinate is out of range or not a number
+ */
 export default function geo(lat1: string, lon1: string, lat2: string, lon2: string): GeoResult {
     const a = parseCoord(lat1, 'lat1', -90, 90);
     const b = parseCoord(lon1, 'lon1', -180, 180);

package/src/modules/v4/hash.ts

@@ -1,4 +1,4 @@
-import { getHashes, createHash } from 'crypto';
+import { createHash, getHashes } from 'crypto';
 
 export interface HashResult {
     method: string;
@@ -8,6 +8,15 @@ export interface HashResult {
 
 const ENCODINGS = new Set(['hex', 'base64']);
 
+/**
+ * Hashes a text string using the specified algorithm and encoding.
+ *
+ * @param text - The text to hash
+ * @param method - Hashing algorithm (e.g. "sha256", "md5")
+ * @param encoding - Output encoding: "hex" (default) or "base64"
+ * @returns Object containing the method, hash result, and encoding used
+ * @throws Error if text is missing, the method is unsupported, or the encoding is invalid
+ */
 export default function hash(text: string, method: string, encoding: string = 'hex'): HashResult {
     if (!text) throw new Error('Text is required');
 

package/src/modules/v4/hyperplanning.ts

@@ -1,6 +1,7 @@
-import { formatDate } from '../../utils/helpers.js';
 import ical from 'ical.js';
 
+import { formatDate } from '../../utils/helpers.js';
+
 interface CalendarEvent {
     summary: string[] | string;
     subject?: string;
@@ -11,8 +12,42 @@ interface CalendarEvent {
     end: string;
 }
 
+function blocked(hostname: string): boolean {
+    const list = ['localhost', '127.0.0.1', '0.0.0.0', '[::1]', 'metadata.google.internal'];
+    if (list.includes(hostname)) return true;
+
+    const parts = hostname.split('.').map(Number);
+    if (parts.length === 4 && parts.every((n) => !isNaN(n))) {
+        if (parts[0] === 10) return true;
+        if (parts[0] === 172 && parts[1]! >= 16 && parts[1]! <= 31) return true;
+        if (parts[0] === 192 && parts[1] === 168) return true;
+        if (parts[0] === 169 && parts[1] === 254) return true;
+        if (parts[0] === 0) return true;
+    }
+
+    return false;
+}
+
+/**
+ * Fetches and parses an ICS calendar from a Hyperplanning URL, filtering out past events.
+ *
+ * @param url - HTTPS URL to the ICS calendar
+ * @param detail - Level of detail: "full" (subject/teacher/classes), "list" (summary/times), or default (summary only)
+ * @returns Array of calendar events sorted by start time, excluding past events
+ * @throws Error if the URL is invalid, uses HTTP, points to a private host, or does not return a valid ICS file
+ */
 export default async function hyperplanning(url: string, detail?: string): Promise<CalendarEvent[]> {
-    const response = await fetch(url);
+    let parsed: URL;
+    try {
+        parsed = new URL(url);
+    } catch {
+        throw new Error('Invalid URL.');
+    }
+
+    if (parsed.protocol !== 'https:') throw new Error('Only HTTPS URLs are allowed.');
+    if (blocked(parsed.hostname)) throw new Error('Access to private/internal hosts is not allowed.');
+
+    const response = await fetch(url, { signal: AbortSignal.timeout(10_000) });
 
     if (!response.ok || !(response.headers.get('content-type') || '').includes('text/calendar')) {
         throw new Error('Invalid ICS file format.');

package/src/modules/v4/ip.ts

@@ -0,0 +1,134 @@
+import { MAX_STRING_LENGTH } from '../../constants.js';
+
+export interface IpResult {
+    ip: string;
+    version: 'IPv4' | 'IPv6';
+    type: 'public' | 'private' | 'loopback' | 'link-local' | 'multicast' | 'broadcast';
+    class?: 'A' | 'B' | 'C' | 'D' | 'E';
+    range?: string;
+    binary: string;
+    decimal?: number;
+    reverse: string;
+}
+
+/**
+ * Parses and analyzes an IPv4 address.
+ *
+ * @param raw - The IPv4 address string (e.g. "192.168.1.1")
+ * @returns Detailed information about the address
+ * @throws Error if the address is malformed
+ */
+function parseIPv4(raw: string): IpResult {
+    const parts = raw.split('.');
+    if (parts.length !== 4) throw new Error('Invalid IPv4 address');
+    const octets = parts.map(Number);
+    if (octets.some((o) => isNaN(o) || !Number.isInteger(o) || o < 0 || o > 255))
+        throw new Error('Invalid IPv4 address');
+
+    const [a, b, c, d] = octets as [number, number, number, number];
+
+    let cls: 'A' | 'B' | 'C' | 'D' | 'E';
+    if (a < 128) cls = 'A';
+    else if (a < 192) cls = 'B';
+    else if (a < 224) cls = 'C';
+    else if (a < 240) cls = 'D';
+    else cls = 'E';
+
+    let type: IpResult['type'] = 'public';
+    let range: string | undefined;
+
+    if (a === 127) {
+        type = 'loopback';
+        range = '127.0.0.0/8';
+    } else if (a === 10) {
+        type = 'private';
+        range = '10.0.0.0/8';
+    } else if (a === 172 && b >= 16 && b <= 31) {
+        type = 'private';
+        range = '172.16.0.0/12';
+    } else if (a === 192 && b === 168) {
+        type = 'private';
+        range = '192.168.0.0/16';
+    } else if (a === 169 && b === 254) {
+        type = 'link-local';
+        range = '169.254.0.0/16';
+    } else if (a >= 224 && a <= 239) {
+        type = 'multicast';
+        range = '224.0.0.0/4';
+    } else if (raw === '255.255.255.255') {
+        type = 'broadcast';
+    }
+
+    const binary = octets.map((o) => o.toString(2).padStart(8, '0')).join('.');
+    const decimal = ((a << 24) | (b << 16) | (c << 8) | d) >>> 0;
+    const reverse = [...octets].reverse().join('.') + '.in-addr.arpa';
+
+    const result: IpResult = { ip: raw, version: 'IPv4', type, class: cls, binary, decimal, reverse };
+    if (range) result.range = range;
+    return result;
+}
+
+/**
+ * Parses and analyzes an IPv6 address, expanding :: shorthand.
+ *
+ * @param raw - The IPv6 address string (e.g. "::1" or "fe80::1")
+ * @returns Detailed information about the address
+ * @throws Error if the address is malformed
+ */
+function parseIPv6(raw: string): IpResult {
+    let expanded = raw;
+    if (raw.includes('::')) {
+        const halves = raw.split('::');
+        const left = halves[0] ? halves[0].split(':') : [];
+        const right = halves[1] ? halves[1].split(':') : [];
+        const fill = Array(8 - left.length - right.length).fill('0');
+        expanded = [...left, ...fill, ...right].join(':');
+    }
+
+    const groups = expanded.split(':');
+    if (groups.length !== 8) throw new Error('Invalid IPv6 address');
+    const values = groups.map((g) => parseInt(g || '0', 16));
+    if (values.some((v) => isNaN(v) || v < 0 || v > 0xffff)) throw new Error('Invalid IPv6 address');
+
+    let type: IpResult['type'] = 'public';
+    let range: string | undefined;
+
+    if (raw === '::1' || values.every((v, i) => (i < 7 ? v === 0 : v === 1))) {
+        type = 'loopback';
+        range = '::1/128';
+    } else if ((values[0]! & 0xfe00) === 0xfc00) {
+        type = 'private';
+        range = 'fc00::/7';
+    } else if ((values[0]! & 0xffc0) === 0xfe80) {
+        type = 'link-local';
+        range = 'fe80::/10';
+    } else if ((values[0]! & 0xff00) === 0xff00) {
+        type = 'multicast';
+        range = 'ff00::/8';
+    }
+
+    const binary = values.map((v) => v.toString(2).padStart(16, '0')).join(':');
+    const hex = values.map((v) => v.toString(16).padStart(4, '0')).join('');
+    const reverse = hex.split('').reverse().join('.') + '.ip6.arpa';
+
+    const result: IpResult = { ip: expanded, version: 'IPv6', type, binary, reverse };
+    if (range) result.range = range;
+    return result;
+}
+
+/**
+ * Analyzes an IPv4 or IPv6 address and returns its type, class, binary
+ * representation, decimal value, and reverse DNS notation.
+ *
+ * @param address - The IP address to analyze
+ * @returns Detailed breakdown of the address
+ * @throws Error if the address is missing or invalid
+ */
+export default function ip(address: string): IpResult {
+    if (!address || typeof address !== 'string') throw new Error('An IP address is required');
+    if (address.length > MAX_STRING_LENGTH) throw new Error('Address is too long');
+
+    if (address.includes(':')) return parseIPv6(address);
+    if (address.includes('.')) return parseIPv4(address);
+    throw new Error('Invalid IP address format');
+}

package/src/modules/v4/levenshtein.ts

@@ -1,5 +1,13 @@
 import { MAX_LEVENSHTEIN_LENGTH } from '../../constants.js';
 
+/**
+ * Computes the Levenshtein edit distance between two strings.
+ *
+ * @param str1 - First string
+ * @param str2 - Second string
+ * @returns Object containing both strings and the minimum number of single-character edits to transform one into the other
+ * @throws Error if either string is missing, not a string, or exceeds the maximum length
+ */
 export default function levenshtein(str1: string, str2: string): { str1: string; str2: string; distance: number } {
     if (!str1 || typeof str1 !== 'string') {
         throw new Error('Please provide a valid first string');

package/src/modules/v4/palette.ts

@@ -1,4 +1,4 @@
-import { hexToRgb, rgbToHsl, hslToRgb, rgbToHex } from '../../utils/colors.js';
+import { hexToRgb, hslToRgb, rgbToHex, rgbToHsl } from '../../utils/colors.js';
 
 export interface PaletteColor {
     hex: string;
@@ -30,6 +30,14 @@ function fromHueShifts(base: [number, number, number], shifts: number[]): Palett
     });
 }
 
+/**
+ * Generates a color palette from a base hex color using a specified harmony type.
+ *
+ * @param color - Base hex color (e.g. "#ff5733")
+ * @param type - Palette type: "complementary", "triadic", "analogous", "tetradic", or "split-complementary"
+ * @returns Object containing the base color and the derived palette colors in hex, RGB, and HSL
+ * @throws Error if color or type is missing, or the type is not one of the accepted values
+ */
 export default function palette(color: string, type: string): PaletteResult {
     if (!color) throw new Error('A base color is required');
     if (!type) throw new Error('A palette type is required');

package/src/modules/v4/personal.ts

@@ -13,6 +13,11 @@ interface CountryInfo {
     lang: string;
 }
 
+/**
+ * Generates a fictional personal profile with realistic demographic and contact data.
+ *
+ * @returns Object containing name, email, phone, address, job, hobbies, and other personal attributes
+ */
 export default function personal(): Record<string, unknown> {
     const people: Person[] = [
         { name: 'John Doe', social: 'john_doe', email: 'john@example.com', country: 'US' },

package/src/modules/v4/placeholder.ts

@@ -157,6 +157,14 @@ function parseAnimate(value: string | undefined): AnimateMode {
     throw new Error('animate must be one of: shimmer, pulse, none');
 }
 
+/**
+ * Generates an SVG placeholder image or skeleton loader with configurable dimensions and style.
+ *
+ * @param type - Placeholder type: "image" or "skeleton"
+ * @param query - Query parameters including width, height, bg, color, text, rows, avatar, animate, speed, and radius
+ * @returns Object containing the SVG body, content type, and placeholder type
+ * @throws Error if any parameter is invalid or out of range
+ */
 export default function placeholder(type: string, query: Record<string, string | undefined>): PlaceholderResult {
     const speed = query.speed ? parseFloat(query.speed) : 1.5;
     if (isNaN(speed) || speed < 0.1 || speed > 10) throw new Error('speed must be between 0.1 and 10');

package/src/modules/v4/qrcode.ts

@@ -1,5 +1,6 @@
-import { toBuffer, toDataURL, toCanvas as qrToCanvas } from 'qrcode';
 import { createCanvas, loadImage } from 'canvas';
+import { toBuffer, toCanvas as qrToCanvas, toDataURL } from 'qrcode';
+
 import { normalizeColor } from '../../utils/colors.js';
 
 export interface QRCodeOptions {
@@ -48,6 +49,13 @@ async function fetchIcon(url: string): Promise<Buffer> {
     return buffer;
 }
 
+/**
+ * Generates a QR code image for a given URL, with optional icon overlay and color customization.
+ *
+ * @param options - QR code generation options including URL, size, margin, correction level, colors, and optional icon
+ * @returns Object containing the QR code as a PNG buffer or Base64 string, and the content type
+ * @throws Error if the URL is missing, any option is invalid, or the icon URL cannot be fetched
+ */
 export default async function qrcode(options: QRCodeOptions): Promise<QRCodeResult> {
     const { url } = options;
     if (!url || typeof url !== 'string') throw new Error('Please provide a valid URL');

package/src/modules/v4/statistics.ts

@@ -13,6 +13,13 @@ export interface StatisticsResult {
     stddev: number;
 }
 
+/**
+ * Computes descriptive statistics for a comma-separated list of numbers.
+ *
+ * @param values - Comma-separated numeric string (e.g. "1,2,3,4,5")
+ * @returns Object containing count, sum, min, max, range, mean, median, mode, variance, and standard deviation
+ * @throws Error if values is missing, contains non-numeric entries, or exceeds the maximum count
+ */
 export default function statistics(values: string): StatisticsResult {
     if (!values) throw new Error('A list of values is required');
     if (typeof values !== 'string') throw new Error('Values must be a comma-separated string');

package/src/modules/v4/text.ts

@@ -142,6 +142,13 @@ export interface TextStats {
     mostFrequentChar: string;
 }
 
+/**
+ * Analyzes a text string and returns character, word, sentence, and reading time statistics.
+ *
+ * @param value - The text to analyze
+ * @returns Object containing character counts, word/sentence/paragraph counts, reading time, and most frequent character
+ * @throws Error if value is missing, not a string, or too long
+ */
 export function stats(value: string): TextStats {
     checkText(value);
 
@@ -168,6 +175,13 @@ export function stats(value: string): TextStats {
     return { characters, charactersNoSpaces, words, sentences, paragraphs, readingTime, mostFrequentChar };
 }
 
+/**
+ * Converts a string to a URL-friendly slug.
+ *
+ * @param value - The string to slugify
+ * @returns Lowercase hyphenated slug with diacritics and special characters removed
+ * @throws Error if value is missing, not a string, or too long
+ */
 export function slug(value: string): string {
     checkText(value);
     return value
@@ -179,6 +193,14 @@ export function slug(value: string): string {
         .replace(/[\s-]+/g, '-');
 }
 
+/**
+ * Generates Lorem Ipsum placeholder text.
+ *
+ * @param type - Content type: "words", "sentences", or "paragraphs"
+ * @param count - Number of words, sentences, or paragraphs to generate
+ * @returns Generated Lorem Ipsum text
+ * @throws Error if count is out of range or type is not one of the accepted values
+ */
 export function lorem(type: string, count: string): string {
     const n = Number(count) || 5;
     if (n < 1 || n > 500) throw new Error('Count must be between 1 and 500');
@@ -283,6 +305,14 @@ function numberToEnglish(n: number): string {
     throw new Error('Number must be less than 1 billion');
 }
 
+/**
+ * Converts an integer to its written-out word form in French or English.
+ *
+ * @param value - The integer to convert (must be less than 1 billion)
+ * @param lang - Language: "fr" for French or "en" for English
+ * @returns The number written out in words
+ * @throws Error if value is not an integer, exceeds the maximum, or lang is not supported
+ */
 export function number(value: string, lang: string): string {
     const n = Number(value);
     if (isNaN(n)) throw new Error('Value must be a number');

package/src/modules/v4/tic_tac_toe.ts

@@ -1,6 +1,7 @@
 import { randomBytes } from 'crypto';
-import { SESSION_TTL, GAME_CLEANUP_TTL, RATE_LIMIT_WINDOW, RATE_LIMIT_MAX } from '../../constants.js';
-import type { TicTacToeStorage, TicTacToeMove, TicTacToeGame } from '../../types/storage.js';
+
+import { GAME_CLEANUP_TTL, RATE_LIMIT_MAX, RATE_LIMIT_WINDOW, SESSION_TTL } from '../../constants.js';
+import type { TicTacToeGame, TicTacToeMove, TicTacToeStorage } from '../../types/storage.js';
 
 interface TicTacToeParams {
     username?: string;
@@ -17,6 +18,14 @@ interface GameResult {
     tie?: boolean;
 }
 
+/**
+ * Handles Tic-Tac-Toe game actions including playing a move, fetching game state, listing games, and forfeiting.
+ *
+ * @param action - The action to perform: "play", "fetch", "list", or "forfeit"
+ * @param params - Game parameters including username, move, session, game ID, and shared storage
+ * @returns Game state or action result depending on the action
+ * @throws Error if a required parameter is missing, the action is invalid, or a rate limit is exceeded
+ */
 export default function tic_tac_toe(action: string, params: TicTacToeParams): Record<string, unknown> {
     const storage = params.storage;
 

package/src/modules/v4/time.ts

@@ -24,6 +24,17 @@ const validTimezones = ['UTC', 'America/New_York', 'Europe/Paris', 'Asia/Tokyo',
 type TimeFormat = (typeof validFormats)[number];
 type Timezone = (typeof validTimezones)[number];
 
+/**
+ * Returns the current or a random date/time in various formats and timezones.
+ *
+ * @param type - "live" for the current time or "random" for a random date within a range
+ * @param start - Optional start date for random mode (YYYY-MM-DD)
+ * @param end - Optional end date for random mode (YYYY-MM-DD)
+ * @param format - Optional specific format to return (e.g. "iso", "timestamp", "year")
+ * @param timezone - Optional timezone (e.g. "UTC", "Europe/Paris")
+ * @returns Object containing all time formats, or a single format if specified
+ * @throws Error if type, format, or timezone is invalid
+ */
 export default function time(
     type: string = 'live',
     start?: string,

package/src/modules/v4/token.ts

@@ -1,7 +1,16 @@
 import { randomBytes } from 'crypto';
 import { v4 } from 'uuid';
-import { MIN_TOKEN_LENGTH, MAX_TOKEN_LENGTH } from '../../constants.js';
 
+import { MAX_TOKEN_LENGTH, MIN_TOKEN_LENGTH } from '../../constants.js';
+
+/**
+ * Generates a cryptographically random token of the specified length and type.
+ *
+ * @param len - Token length (must be between 12 and 4096)
+ * @param type - Character set to use: "alpha", "alphanum", "base64", "hex", "num", "punct", "urlsafe", or "uuid"
+ * @returns The generated token string
+ * @throws Error if length is out of range or the type is not valid
+ */
 export default function token(len: number, type: string = 'alphanum'): string {
     if (isNaN(len) || len < MIN_TOKEN_LENGTH) {
         throw new Error('Length must be a number greater than or equal to 12');

package/src/modules/v4/username.ts

@@ -1,5 +1,10 @@
 import { random, randomNumber } from '../../utils/helpers.js';
 
+/**
+ * Generates a random username combining adjectives, animals, and job titles.
+ *
+ * @returns Object containing the generated username, the number used, and the components (adjective, animal, job)
+ */
 export default function username(): Record<string, unknown> {
     const adj = [
         'Happy',

package/src/modules/v4/validate.ts

@@ -7,6 +7,13 @@ function checkValue(value: string): void {
         throw new Error(`Value must be less than ${MAX_STRING_LENGTH} characters long`);
 }
 
+/**
+ * Validates a credit/debit card number using the Luhn algorithm.
+ *
+ * @param value - Card number string (digits, spaces, or dashes allowed)
+ * @returns Object containing the validity result and the sanitized digit string
+ * @throws Error if value is missing, contains non-digit characters, or has an invalid length
+ */
 export function luhn(value: string): { valid: boolean; value: string } {
     checkValue(value);
     const digits = value.replace(/\s|-/g, '');
@@ -28,6 +35,13 @@ export function luhn(value: string): { valid: boolean; value: string } {
     return { valid: sum % 10 === 0, value: digits };
 }
 
+/**
+ * Validates an IBAN using the mod-97 checksum algorithm.
+ *
+ * @param value - IBAN string (spaces allowed)
+ * @returns Object containing the validity result, sanitized IBAN, and country code
+ * @throws Error if value is missing, has an invalid format, or is out of length bounds
+ */
 export function iban(value: string): { valid: boolean; value: string; country?: string } {
     checkValue(value);
     const cleaned = value.replace(/\s/g, '').toUpperCase();
@@ -48,6 +62,13 @@ export function iban(value: string): { valid: boolean; value: string; country?:
     return { valid: remainder === 1, value: cleaned, country: cleaned.slice(0, 2) };
 }
 
+/**
+ * Validates an email address against a basic format check.
+ *
+ * @param value - The email address string to validate
+ * @returns Object containing the validity result and the original value
+ * @throws Error if value is missing, not a string, or too long
+ */
 export function email(value: string): { valid: boolean; value: string } {
     checkValue(value);
     const regex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;

package/src/modules/v4.ts

@@ -1,6 +1,7 @@
+export { default as agent } from './v4/agent.js';
 export * as algorithms from './v4/algorithms.js';
-export { default as chat } from './v4/chat.js';
 export { default as captcha } from './v4/captcha.js';
+export { default as chat } from './v4/chat.js';
 export { default as color } from './v4/color.js';
 export { default as convert } from './v4/convert.js';
 export { default as dice } from './v4/dice.js';
@@ -9,6 +10,7 @@ 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 ip } from './v4/ip.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';

package/src/routes/delete.ts

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

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();
 
@@ -61,7 +63,7 @@ router.get('/:version/algorithms', (req: Request, res: Response) => {
     const { version } = req.params;
 
     const algorithms = req.module.algorithms as Record<string, (v: string, v2?: string) => unknown>;
-    if (!algorithms || !algorithms[method as string]) {
+    if (!algorithms || !method || !Object.hasOwn(algorithms, method as string)) {
         error(res, 400, 'Please provide a valid algorithm (?method={algorithm})', `${version}/algorithms`);
         return;
     }
@@ -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 {
@@ -217,7 +267,7 @@ router.get('/:version/encode', (req: Request, res: Response) => {
         error(res, 404, `Endpoint not available in ${version}.`, `${version}/encode`);
         return;
     }
-    if (!method || !encode[method as string]) {
+    if (!method || !Object.hasOwn(encode, method as string)) {
         error(res, 400, 'Please provide a valid method (?method={method})', `${version}/encode`);
         return;
     }
@@ -434,7 +484,7 @@ router.get('/:version/text', (req: Request, res: Response) => {
         error(res, 404, `Endpoint not available in ${version}.`, `${version}/text`);
         return;
     }
-    if (!method || !textMod[method as string]) {
+    if (!method || !Object.hasOwn(textMod, method as string)) {
         error(res, 400, 'Please provide a valid method (?method={slug|stats|lorem|number})', `${version}/text`);
         return;
     }
@@ -471,7 +521,7 @@ router.get('/:version/validate', (req: Request, res: Response) => {
         error(res, 404, `Endpoint not available in ${version}.`, `${version}/validate`);
         return;
     }
-    if (!type || !validate[type as string]) {
+    if (!type || !Object.hasOwn(validate, type as string)) {
         error(res, 400, 'Please provide a valid type (?type={luhn|iban|email})', `${version}/validate`);
         return;
     }

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();