@20syldev/api 4.5.0 → 4.7.0

package/src/modules/v4/agent.ts

@@ -0,0 +1,104 @@
+import { MAX_STRING_LENGTH } from '../../constants.js';
+
+export interface UserAgentResult {
+    raw: string;
+    browser: { name: string; version: string; major: string };
+    os: { name: string; version: string };
+    device: { type: 'mobile' | 'tablet' | 'desktop'; vendor: string };
+    engine: { name: string; version: string };
+    bot: boolean;
+}
+
+const WINDOWS_MAP: Record<string, string> = {
+    '10.0': 'Windows 10/11',
+    '6.3': 'Windows 8.1',
+    '6.2': 'Windows 8',
+    '6.1': 'Windows 7',
+    '6.0': 'Windows Vista',
+    '5.1': 'Windows XP',
+};
+
+/**
+ * Parses a User-Agent string and extracts browser, OS, device, engine
+ * and bot information.
+ *
+ * @param ua - The User-Agent string to parse
+ * @returns Structured breakdown of the User-Agent
+ * @throws Error if the User-Agent string is missing or too long
+ */
+export default function agent(ua: string): UserAgentResult {
+    if (!ua || typeof ua !== 'string') throw new Error('A User-Agent string is required');
+    if (ua.length > MAX_STRING_LENGTH) throw new Error(`User-Agent must be less than ${MAX_STRING_LENGTH} characters`);
+
+    const unknown = { name: 'unknown', version: 'unknown', major: 'unknown' };
+
+    const bot = /bot|crawl|spider|lighthouse|headless|prerender|slurp|bingpreview/i.test(ua);
+
+    // Browser — order matters: Edge/Opera before Chrome
+    let browser = { ...unknown };
+    const browserRules: [RegExp, string][] = [
+        [/Edg\/(\d+[\d.]*)/i, 'Edge'],
+        [/OPR\/(\d+[\d.]*)/i, 'Opera'],
+        [/SamsungBrowser\/(\d+[\d.]*)/i, 'Samsung Internet'],
+        [/Chrome\/(\d+[\d.]*)/i, 'Chrome'],
+        [/Firefox\/(\d+[\d.]*)/i, 'Firefox'],
+        [/Version\/([\d.]+).*Safari/i, 'Safari'],
+        [/MSIE ([\d.]+)/i, 'Internet Explorer'],
+        [/Trident\/.*rv:([\d.]+)/i, 'Internet Explorer'],
+    ];
+    for (const [re, name] of browserRules) {
+        const m = ua.match(re);
+        if (m) {
+            browser = { name, version: m[1]!, major: m[1]!.split('.')[0]! };
+            break;
+        }
+    }
+
+    // OS
+    let os = { name: 'unknown', version: 'unknown' };
+    const osRules: [RegExp, (m: RegExpMatchArray) => typeof os][] = [
+        [/iPhone OS ([\d_]+)/i, (m) => ({ name: 'iOS', version: m[1]!.replace(/_/g, '.') })],
+        [/iPad.*OS ([\d_]+)/i, (m) => ({ name: 'iPadOS', version: m[1]!.replace(/_/g, '.') })],
+        [/Android ([\d.]+)/i, (m) => ({ name: 'Android', version: m[1]! })],
+        [/Windows NT ([\d.]+)/i, (m) => ({ name: WINDOWS_MAP[m[1]!] ?? 'Windows', version: m[1]! })],
+        [/Mac OS X ([\d_.]+)/i, (m) => ({ name: 'macOS', version: m[1]!.replace(/_/g, '.') })],
+        [/Linux/i, () => ({ name: 'Linux', version: 'unknown' })],
+    ];
+    for (const [re, build] of osRules) {
+        const m = ua.match(re);
+        if (m) {
+            os = build(m);
+            break;
+        }
+    }
+
+    // Device
+    const isMobile = /Mobi|Android|iPhone|iPod/i.test(ua) && !/iPad/i.test(ua);
+    const isTablet = /iPad/i.test(ua) || (/Android/i.test(ua) && !/Mobile/i.test(ua));
+    const deviceType: 'mobile' | 'tablet' | 'desktop' = isMobile ? 'mobile' : isTablet ? 'tablet' : 'desktop';
+
+    let vendor = 'unknown';
+    if (/iPhone|iPad|Macintosh/i.test(ua)) vendor = 'Apple';
+    else if (/Samsung/i.test(ua)) vendor = 'Samsung';
+    else if (/Pixel|Nexus/i.test(ua)) vendor = 'Google';
+    else if (/Huawei/i.test(ua)) vendor = 'Huawei';
+
+    // Engine
+    let engine = { name: 'unknown', version: 'unknown' };
+    const engineRules: [RegExp, string][] = [
+        [/AppleWebKit\/([\d.]+)/i, 'WebKit'],
+        [/Gecko\/([\d.]+)/i, 'Gecko'],
+        [/Trident\/([\d.]+)/i, 'Trident'],
+    ];
+    for (const [re, name] of engineRules) {
+        const m = ua.match(re);
+        if (m) {
+            // Chrome and Edge use Blink, a WebKit fork
+            const engineName = name === 'WebKit' && /Chrome|Edg/i.test(ua) ? 'Blink' : name;
+            engine = { name: engineName, version: m[1]! };
+            break;
+        }
+    }
+
+    return { raw: ua, browser, os, device: { type: deviceType, vendor }, engine, bot };
+}

package/src/modules/v4/algorithms.ts

@@ -1,5 +1,13 @@
 import { MAX_FACTORIAL, MAX_GCD_VALUE, MAX_PRIME_LIST, MAX_STRING_LENGTH, ROMAN_VALUES } from '../../constants.js';
 
+/**
+ * Checks whether two strings are anagrams of each other.
+ *
+ * @param value - First string
+ * @param value2 - Second string
+ * @returns True if the strings are anagrams, false otherwise
+ * @throws Error if either value is missing, not a string, or out of length bounds
+ */
 export function anagram(value: string, value2: string): boolean {
     if (!value) throw new Error('First value is required');
     if (!value2) throw new Error('Second value is required');
@@ -16,6 +24,13 @@ export function anagram(value: string, value2: string): boolean {
     return value.split('').sort().join('') === value2.split('').sort().join('');
 }
 
+/**
+ * Sorts a comma-separated list of numbers using the bubble sort algorithm.
+ *
+ * @param value - Comma-separated string of numbers (e.g. "3,1,2")
+ * @returns Array of numbers sorted in ascending order
+ * @throws Error if value is missing, non-numeric, or contains fewer than two elements
+ */
 export function bubblesort(value: string): number[] {
     if (!value) throw new Error('A value is required');
 
@@ -36,6 +51,13 @@ export function bubblesort(value: string): number[] {
     return arr;
 }
 
+/**
+ * Computes the factorial of a non-negative integer.
+ *
+ * @param value - The integer to compute the factorial of
+ * @returns The factorial of the given number
+ * @throws Error if value is not a number, is negative, or exceeds the maximum allowed
+ */
 export function factorial(value: string | number): number {
     const num = Number(value);
     if (isNaN(num)) throw new Error('Value must be a number');
@@ -45,6 +67,13 @@ export function factorial(value: string | number): number {
     return num <= 1 ? 1 : num * factorial(num - 1);
 }
 
+/**
+ * Returns the first n numbers of the Fibonacci sequence.
+ *
+ * @param value - How many Fibonacci numbers to generate
+ * @returns Array of Fibonacci numbers starting from 0
+ * @throws Error if value is not a number, is negative, or exceeds 1000
+ */
 export function fibonacci(value: string | number): number[] {
     const num = Number(value);
     if (isNaN(num)) throw new Error('Value must be a number');
@@ -60,6 +89,14 @@ export function fibonacci(value: string | number): number[] {
     return fib.slice(0, num);
 }
 
+/**
+ * Computes the greatest common divisor of two positive integers using the Euclidean algorithm.
+ *
+ * @param value - First positive integer
+ * @param value2 - Second positive integer
+ * @returns The greatest common divisor
+ * @throws Error if either value is not a positive number or exceeds the maximum allowed
+ */
 export function gcd(value: string | number, value2: string | number): number {
     let a = Number(value);
     let b = Number(value2);
@@ -80,6 +117,13 @@ export function gcd(value: string | number, value2: string | number): number {
     return a;
 }
 
+/**
+ * Determines whether a given number is prime.
+ *
+ * @param value - The number to test
+ * @returns True if the number is prime, false otherwise
+ * @throws Error if value is not a positive number or exceeds the maximum allowed
+ */
 export function isprime(value: string | number): boolean {
     const num = Number(value);
     if (isNaN(num)) throw new Error('Value must be a number');
@@ -93,6 +137,13 @@ export function isprime(value: string | number): boolean {
     return true;
 }
 
+/**
+ * Checks whether a string reads the same forwards and backwards.
+ *
+ * @param value - The string to test
+ * @returns True if the string is a palindrome, false otherwise
+ * @throws Error if value is missing, not a string, or out of length bounds
+ */
 export function palindrome(value: string): boolean {
     if (!value) throw new Error('A value is required');
 
@@ -104,6 +155,13 @@ export function palindrome(value: string): boolean {
     return value === value.split('').reverse().join('');
 }
 
+/**
+ * Returns the prime factorization of a given integer.
+ *
+ * @param value - An integer greater than 1
+ * @returns Array of prime factors in ascending order
+ * @throws Error if value is not a number, less than 2, or exceeds the maximum allowed
+ */
 export function primefactors(value: string | number): number[] {
     let num = Number(value);
     if (isNaN(num)) throw new Error('Value must be a number');
@@ -122,6 +180,13 @@ export function primefactors(value: string | number): number[] {
     return factors;
 }
 
+/**
+ * Returns all prime numbers up to and including the given limit.
+ *
+ * @param value - The upper bound (inclusive)
+ * @returns Array of prime numbers up to the given limit
+ * @throws Error if value is not a number, less than 2, or exceeds the maximum allowed
+ */
 export function primelist(value: string | number): number[] {
     const num = Number(value);
     if (isNaN(num)) throw new Error('Value must be a number');
@@ -146,6 +211,13 @@ export function primelist(value: string | number): number[] {
     return primes;
 }
 
+/**
+ * Reverses a string.
+ *
+ * @param value - The string to reverse
+ * @returns The reversed string
+ * @throws Error if value is missing or not a string
+ */
 export function reverse(value: string): string {
     if (!value) throw new Error('A value is required');
 
@@ -154,6 +226,13 @@ export function reverse(value: string): string {
     return value.split('').reverse().join('');
 }
 
+/**
+ * Converts an integer to its Roman numeral representation, or a Roman numeral to an integer.
+ *
+ * @param value - An integer (1–3999) or a Roman numeral string
+ * @returns The converted value — a Roman numeral string if input was numeric, or an integer if input was a Roman numeral
+ * @throws Error if value is missing, out of range, or not a valid Roman numeral
+ */
 export function roman(value: string): number | string {
     if (!value) throw new Error('A value is required');
 

package/src/modules/v4/captcha.ts

@@ -1,4 +1,5 @@
 import { createCanvas } from 'canvas';
+
 import { normalizeColor } from '../../utils/colors.js';
 
 export interface CaptchaOptions {
@@ -36,6 +37,13 @@ function clamp(value: number | undefined, name: string, def: number, min: number
     return Math.floor(value);
 }
 
+/**
+ * Generates a CAPTCHA image with random or custom text and configurable noise.
+ *
+ * @param options - Captcha configuration options
+ * @returns Object containing the PNG buffer, content type, and the challenge text
+ * @throws Error if any option is out of the accepted range
+ */
 export default function captcha(options: CaptchaOptions): CaptchaResult {
     const text = options.text || generateText(clamp(options.length, 'length', 6, 1, 20));
     const height = clamp(options.height, 'height', 120, 50, 400);

package/src/modules/v4/chat.ts

@@ -1,6 +1,6 @@
-import { checkRateLimit } from '../../utils/helpers.js';
 import { SESSION_TTL } from '../../constants.js';
-import type { ChatStorage, ChatMessage } from '../../types/storage.js';
+import type { ChatMessage, ChatStorage } from '../../types/storage.js';
+import { checkRateLimit } from '../../utils/helpers.js';
 
 interface ChatParams {
     username: string;
@@ -11,6 +11,14 @@ interface ChatParams {
     storage: ChatStorage;
 }
 
+/**
+ * Handles real-time chat actions including sending, fetching, and clearing messages.
+ *
+ * @param action - The action to perform: "message", "private", "fetch", or "clear"
+ * @param params - Chat parameters including username, message, session, and shared storage
+ * @returns The result of the action — a message list, a sent confirmation, or a status message
+ * @throws Error if a required parameter is missing or the action is invalid
+ */
 export default function chat(action: string, params: ChatParams): ChatMessage[] | ChatMessage | { message: string } {
     const storage = params.storage;
 

package/src/modules/v4/color.ts

@@ -1,4 +1,4 @@
-import { hexToRgb, rgbToHsl, rgbToHex } from '../../utils/colors.js';
+import { hexToRgb, rgbToHex, rgbToHsl } from '../../utils/colors.js';
 
 export interface ColorResult {
     hex: string;
@@ -41,6 +41,13 @@ function rgbToCmyk(r: number, g: number, b: number): [number, number, number, nu
     return [c * 100, m * 100, y * 100, k * 100];
 }
 
+/**
+ * Converts a hex color to all major color space representations, or generates a random color.
+ *
+ * @param hex - Optional hex color string (e.g. "#ff5733"); generates a random color if omitted
+ * @returns Color in hex, RGB, HSL, HSV, HWB, and CMYK formats
+ * @throws Error if the hex string is invalid
+ */
 export default function color(hex?: string): ColorResult {
     let r: number, g: number, b: number;
 

package/src/modules/v4/convert.ts

@@ -97,6 +97,15 @@ const conversions: Record<string, Record<string, ConversionFn>> = {
     knots: { 'km/h': (v) => v * 1.852, mph: (v) => v * 1.15078, 'm/s': (v) => v * 0.514444 },
 };
 
+/**
+ * Converts a numeric value from one unit to another.
+ *
+ * @param value - The numeric value to convert
+ * @param from - The source unit (e.g. "km", "celsius", "kg")
+ * @param to - The target unit (e.g. "mi", "fahrenheit", "lb")
+ * @returns Object with source unit, target unit, original value, and converted result
+ * @throws Error if the conversion pair is unsupported, the value is NaN, or the temperature is below absolute zero
+ */
 export default function convert(
     value: number,
     from: string,

package/src/modules/v4/dice.ts

@@ -7,6 +7,13 @@ export interface DiceResult {
     total: number;
 }
 
+/**
+ * Rolls dice using standard tabletop notation and returns individual results with a total.
+ *
+ * @param roll - Dice notation string (e.g. "2d6+3", "d20", "4d8-1")
+ * @returns Roll breakdown including count, sides, modifier, individual results, and total
+ * @throws Error if the notation is missing, invalid, or out of bounds
+ */
 export default function dice(roll: string): DiceResult {
     if (!roll) throw new Error('A roll notation is required (e.g. 2d6+3)');
     if (typeof roll !== 'string') throw new Error('Roll must be a string');

package/src/modules/v4/domain.ts

@@ -1,5 +1,10 @@
-import { random, genIP } from '../../utils/helpers.js';
+import { genIP, random } from '../../utils/helpers.js';
 
+/**
+ * Generates a randomized fictional domain profile with metadata.
+ *
+ * @returns Object containing domain name, IP addresses, DNS info, SEO score, and other domain attributes
+ */
 export default function domain(): Record<string, unknown> {
     const subdomains = [
         'fr.',

package/src/modules/v4/encode.ts

@@ -66,22 +66,50 @@ function checkText(value: string): void {
         throw new Error(`Value must be less than ${MAX_STRING_LENGTH} characters long`);
 }
 
+/**
+ * Encodes a UTF-8 string to Base64.
+ *
+ * @param value - The string to encode
+ * @returns Base64-encoded string
+ * @throws Error if value is missing, not a string, or too long
+ */
 export function base64encode(value: string): string {
     checkText(value);
     return Buffer.from(value, 'utf-8').toString('base64');
 }
 
+/**
+ * Decodes a Base64 string to UTF-8.
+ *
+ * @param value - The Base64 string to decode
+ * @returns Decoded UTF-8 string
+ * @throws Error if value is missing, not valid Base64, or too long
+ */
 export function base64decode(value: string): string {
     checkText(value);
     if (!/^[A-Za-z0-9+/]*={0,2}$/.test(value)) throw new Error('Invalid Base64 string');
     return Buffer.from(value, 'base64').toString('utf-8');
 }
 
+/**
+ * Percent-encodes a string for safe use in a URL.
+ *
+ * @param value - The string to encode
+ * @returns URL-encoded string
+ * @throws Error if value is missing, not a string, or too long
+ */
 export function urlencode(value: string): string {
     checkText(value);
     return encodeURIComponent(value);
 }
 
+/**
+ * Decodes a percent-encoded URL string.
+ *
+ * @param value - The URL-encoded string to decode
+ * @returns Decoded string
+ * @throws Error if value is missing, not a valid URL-encoded string, or too long
+ */
 export function urldecode(value: string): string {
     checkText(value);
     try {
@@ -91,6 +119,13 @@ export function urldecode(value: string): string {
     }
 }
 
+/**
+ * Converts a plain text string to Morse code.
+ *
+ * @param value - The text to encode in Morse code
+ * @returns Morse code string where letters are separated by spaces and words by " / "
+ * @throws Error if value contains unsupported characters or is too long
+ */
 export function morse(value: string): string {
     checkText(value);
     return value
@@ -111,6 +146,13 @@ export function morse(value: string): string {
         .join(' / ');
 }
 
+/**
+ * Converts a Morse code string back to plain text.
+ *
+ * @param value - Morse code string (letters separated by spaces, words by " / ")
+ * @returns Decoded plain text string
+ * @throws Error if the Morse code contains an unrecognized sequence or is too long
+ */
 export function unmorse(value: string): string {
     checkText(value);
     return value
@@ -129,6 +171,13 @@ export function unmorse(value: string): string {
         .join(' ');
 }
 
+/**
+ * Applies the ROT13 substitution cipher to a string.
+ *
+ * @param value - The string to encode
+ * @returns ROT13-encoded string (applying it twice restores the original)
+ * @throws Error if value is missing, not a string, or too long
+ */
 export function rot13(value: string): string {
     checkText(value);
     return value.replace(/[a-zA-Z]/g, (c) => {
@@ -137,6 +186,14 @@ export function rot13(value: string): string {
     });
 }
 
+/**
+ * Applies the Caesar cipher by shifting alphabetic characters by a given amount.
+ *
+ * @param value - The string to encode
+ * @param shift - Number of positions to shift (can be negative for left shift)
+ * @returns Caesar-shifted string
+ * @throws Error if value is missing or shift is not a number
+ */
 export function caesar(value: string, shift: string): string {
     checkText(value);
     const n = Number(shift);
@@ -148,6 +205,13 @@ export function caesar(value: string, shift: string): string {
     });
 }
 
+/**
+ * Converts a string to its binary representation, one byte per character.
+ *
+ * @param value - The string to convert
+ * @returns Space-separated 8-bit binary groups (one per character)
+ * @throws Error if value is missing, not a string, or too long
+ */
 export function binary(value: string): string {
     checkText(value);
     return value
@@ -156,6 +220,13 @@ export function binary(value: string): string {
         .join(' ');
 }
 
+/**
+ * Converts a binary string back to plain text.
+ *
+ * @param value - Space-separated 8-bit binary groups
+ * @returns Decoded string
+ * @throws Error if value contains non-binary characters or groups are not 8 bits wide
+ */
 export function unbinary(value: string): string {
     checkText(value);
     if (!/^[01\s]+$/.test(value)) throw new Error('Invalid binary string');

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;
@@ -27,6 +28,14 @@ function blocked(hostname: string): boolean {
     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[]> {
     let parsed: URL;
     try {