@20syldev/api 4.8.0 → 5.0.0

package/src/modules/v4/encode.ts

@@ -1,241 +0,0 @@
-import { MAX_STRING_LENGTH } from '../../constants.js';
-
-const MORSE_TABLE: Record<string, string> = {
-    A: '.-',
-    B: '-...',
-    C: '-.-.',
-    D: '-..',
-    E: '.',
-    F: '..-.',
-    G: '--.',
-    H: '....',
-    I: '..',
-    J: '.---',
-    K: '-.-',
-    L: '.-..',
-    M: '--',
-    N: '-.',
-    O: '---',
-    P: '.--.',
-    Q: '--.-',
-    R: '.-.',
-    S: '...',
-    T: '-',
-    U: '..-',
-    V: '...-',
-    W: '.--',
-    X: '-..-',
-    Y: '-.--',
-    Z: '--..',
-    '0': '-----',
-    '1': '.----',
-    '2': '..---',
-    '3': '...--',
-    '4': '....-',
-    '5': '.....',
-    '6': '-....',
-    '7': '--...',
-    '8': '---..',
-    '9': '----.',
-    '.': '.-.-.-',
-    ',': '--..--',
-    '?': '..--..',
-    "'": '.----.',
-    '!': '-.-.--',
-    '/': '-..-.',
-    '(': '-.--.',
-    ')': '-.--.-',
-    '&': '.-...',
-    ':': '---...',
-    ';': '-.-.-.',
-    '=': '-...-',
-    '+': '.-.-.',
-    '-': '-....-',
-    _: '..--.-',
-    '"': '.-..-.',
-    $: '...-..-',
-    '@': '.--.-.',
-};
-
-const MORSE_REVERSE: Record<string, string> = Object.fromEntries(Object.entries(MORSE_TABLE).map(([k, v]) => [v, k]));
-
-function checkText(value: string): void {
-    if (!value) throw new Error('A value is required');
-    if (typeof value !== 'string') throw new Error('Value must be a string');
-    if (value.length > MAX_STRING_LENGTH)
-        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 {
-        return decodeURIComponent(value);
-    } catch {
-        throw new Error('Invalid URL-encoded 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
-        .toUpperCase()
-        .split(' ')
-        .map((word) =>
-            word
-                .split('')
-                .map((c) => {
-                    if (c === '\n' || c === '\t') return '';
-                    const code = MORSE_TABLE[c];
-                    if (!code) throw new Error(`Unsupported character in Morse code: '${c}'`);
-                    return code;
-                })
-                .filter(Boolean)
-                .join(' '),
-        )
-        .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
-        .split(' / ')
-        .map((word) =>
-            word
-                .split(' ')
-                .map((code) => {
-                    if (!code) return '';
-                    const char = MORSE_REVERSE[code];
-                    if (!char) throw new Error(`Unsupported Morse sequence: '${code}'`);
-                    return char;
-                })
-                .join(''),
-        )
-        .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) => {
-        const base = c <= 'Z' ? 65 : 97;
-        return String.fromCharCode(((c.charCodeAt(0) - base + 13) % 26) + base);
-    });
-}
-
-/**
- * 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);
-    if (isNaN(n)) throw new Error('Shift must be a number');
-    const s = ((n % 26) + 26) % 26;
-    return value.replace(/[a-zA-Z]/g, (c) => {
-        const base = c <= 'Z' ? 65 : 97;
-        return String.fromCharCode(((c.charCodeAt(0) - base + s) % 26) + base);
-    });
-}
-
-/**
- * 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
-        .split('')
-        .map((c) => c.charCodeAt(0).toString(2).padStart(8, '0'))
-        .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');
-    return value
-        .trim()
-        .split(/\s+/)
-        .map((b) => {
-            if (b.length !== 8) throw new Error('Each binary group must contain 8 bits');
-            return String.fromCharCode(parseInt(b, 2));
-        })
-        .join('');
-}

package/src/modules/v4/geo.ts

@@ -1,64 +0,0 @@
-export interface GeoResult {
-    distance: { km: number; miles: number; nauticalMiles: number };
-    bearing: { degrees: number; cardinal: string };
-    from: { lat: number; lon: number };
-    to: { lat: number; lon: number };
-}
-
-import { EARTH_RADIUS_KM } from '../../constants.js';
-
-const CARDINALS = ['N', 'NNE', 'NE', 'ENE', 'E', 'ESE', 'SE', 'SSE', 'S', 'SSW', 'SW', 'WSW', 'W', 'WNW', 'NW', 'NNW'];
-
-function toRad(deg: number): number {
-    return (deg * Math.PI) / 180;
-}
-
-function toDeg(rad: number): number {
-    return (rad * 180) / Math.PI;
-}
-
-function parseCoord(value: string, name: string, min: number, max: number): number {
-    const n = Number(value);
-    if (isNaN(n)) throw new Error(`${name} must be a number`);
-    if (n < min || n > max) throw new Error(`${name} must be between ${min} and ${max}`);
-    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);
-    const c = parseCoord(lat2, 'lat2', -90, 90);
-    const d = parseCoord(lon2, 'lon2', -180, 180);
-
-    const dLat = toRad(c - a);
-    const dLon = toRad(d - b);
-    const sa = Math.sin(dLat / 2) ** 2 + Math.cos(toRad(a)) * Math.cos(toRad(c)) * Math.sin(dLon / 2) ** 2;
-    const distance = 2 * EARTH_RADIUS_KM * Math.asin(Math.sqrt(sa));
-
-    const y = Math.sin(toRad(d - b)) * Math.cos(toRad(c));
-    const x =
-        Math.cos(toRad(a)) * Math.sin(toRad(c)) - Math.sin(toRad(a)) * Math.cos(toRad(c)) * Math.cos(toRad(d - b));
-    const bearing = (toDeg(Math.atan2(y, x)) + 360) % 360;
-    const cardinal = CARDINALS[Math.round(bearing / 22.5) % 16]!;
-
-    return {
-        distance: {
-            km: +distance.toFixed(3),
-            miles: +(distance * 0.621371).toFixed(3),
-            nauticalMiles: +(distance * 0.539957).toFixed(3),
-        },
-        bearing: { degrees: +bearing.toFixed(2), cardinal },
-        from: { lat: a, lon: b },
-        to: { lat: c, lon: d },
-    };
-}

package/src/modules/v4/hash.ts

@@ -1,32 +0,0 @@
-import { createHash, getHashes } from 'crypto';
-
-export interface HashResult {
-    method: string;
-    hash: string;
-    encoding: string;
-}
-
-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');
-
-    const methods = getHashes();
-    if (!methods.includes(method)) throw new Error(`Unsupported method. Use one of: ${methods.join(', ')}`);
-
-    if (!ENCODINGS.has(encoding)) throw new Error('Encoding must be one of: hex, base64');
-
-    const result = createHash(method)
-        .update(text)
-        .digest(encoding as 'hex' | 'base64');
-    return { method, hash: result, encoding };
-}

package/src/modules/v4/hyperplanning.ts

@@ -1,93 +0,0 @@
-import ical from 'ical.js';
-
-import { formatDate } from '../../utils/helpers.js';
-
-interface CalendarEvent {
-    summary: string[] | string;
-    subject?: string;
-    teacher?: string;
-    classes?: string[];
-    type?: string;
-    start: string;
-    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[]> {
-    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.');
-    }
-
-    const events: CalendarEvent[] = new ical.Component(ical.parse(await response.text()))
-        .getAllSubcomponents('vevent')
-        .map((e: ical.Component) => {
-            const evt = new ical.Event(e);
-            const summary = (evt.summary || '').split(' ').filter((part: string) => part !== '-');
-            const start = formatDate(evt.startDate.toJSDate());
-            const end = formatDate(evt.endDate.toJSDate());
-
-            if (detail === 'full') {
-                const desc = (evt.description || '').split('\n').map((l: string) => l.trim());
-                const extract = (p: string) => (desc.find((l: string) => l.startsWith(p)) || '').replace(p, '').trim();
-
-                return {
-                    summary,
-                    subject: extract('Matière :'),
-                    teacher: extract('Enseignant :'),
-                    classes: extract('Promotions :')
-                        .split(', ')
-                        .map((c: string) => c.trim()),
-                    type: extract('Salle :') || undefined,
-                    start,
-                    end,
-                };
-            }
-
-            if (detail === 'list') return { summary, start, end };
-
-            return {
-                summary: evt.summary || '',
-                start,
-                end,
-            };
-        })
-        .sort((a: CalendarEvent, b: CalendarEvent) => new Date(a.start).getTime() - new Date(b.start).getTime())
-        .filter((e: CalendarEvent) => new Date(e.end) >= new Date());
-
-    return events;
-}

package/src/modules/v4/ip.ts

@@ -1,134 +0,0 @@
-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,46 +0,0 @@
-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');
-    }
-
-    if (!str2 || typeof str2 !== 'string') {
-        throw new Error('Please provide a valid second string');
-    }
-
-    if (str1.length > MAX_LEVENSHTEIN_LENGTH) {
-        throw new Error('First string exceeds 1000 characters');
-    }
-
-    if (str2.length > MAX_LEVENSHTEIN_LENGTH) {
-        throw new Error('Second string exceeds 1000 characters');
-    }
-
-    const m: number[][] = Array.from({ length: str1.length + 1 }, (_, i) => [i]);
-    for (let j = 0; j <= str2.length; j++) m[0]![j] = j;
-
-    for (let i = 1; i <= str1.length; i++) {
-        for (let j = 1; j <= str2.length; j++) {
-            m[i]![j] = Math.min(
-                m[i - 1]![j]! + 1,
-                m[i]![j - 1]! + 1,
-                m[i - 1]![j - 1]! + (str1[i - 1] !== str2[j - 1] ? 1 : 0),
-            );
-        }
-    }
-
-    return {
-        str1,
-        str2,
-        distance: m[str1.length]![str2.length]!,
-    };
-}

package/src/modules/v4/palette.ts

@@ -1,71 +0,0 @@
-import { hexToRgb, hslToRgb, rgbToHex, rgbToHsl } from '../../utils/colors.js';
-
-export interface PaletteColor {
-    hex: string;
-    rgb: string;
-    hsl: string;
-}
-
-export interface PaletteResult {
-    base: PaletteColor;
-    type: string;
-    colors: PaletteColor[];
-}
-
-function format(r: number, g: number, b: number): PaletteColor {
-    const [h, s, l] = rgbToHsl(r, g, b);
-    return {
-        hex: rgbToHex(r, g, b),
-        rgb: `rgb(${r}, ${g}, ${b})`,
-        hsl: `hsl(${h.toFixed(1)}, ${(s * 100).toFixed(1)}%, ${(l * 100).toFixed(1)}%)`,
-    };
-}
-
-function fromHueShifts(base: [number, number, number], shifts: number[]): PaletteColor[] {
-    const [h, s, l] = base;
-    return shifts.map((shift) => {
-        const newH = (h + shift + 360) % 360;
-        const [r, g, b] = hslToRgb(newH, s, l);
-        return format(r, g, b);
-    });
-}
-
-/**
- * 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');
-
-    const [r, g, b] = hexToRgb(color);
-    const base = format(r, g, b);
-    const hsl = rgbToHsl(r, g, b);
-
-    let colors: PaletteColor[];
-    switch (type) {
-        case 'complementary':
-            colors = fromHueShifts(hsl, [0, 180]);
-            break;
-        case 'triadic':
-            colors = fromHueShifts(hsl, [0, 120, 240]);
-            break;
-        case 'analogous':
-            colors = fromHueShifts(hsl, [-60, -30, 0, 30, 60]);
-            break;
-        case 'tetradic':
-            colors = fromHueShifts(hsl, [0, 90, 180, 270]);
-            break;
-        case 'split-complementary':
-            colors = fromHueShifts(hsl, [0, 150, 210]);
-            break;
-        default:
-            throw new Error('Type must be one of: complementary, triadic, analogous, tetradic, split-complementary');
-    }
-
-    return { base, type, colors };
-}