@20syldev/api 4.5.0 → 4.7.0

package/README.md

@@ -2,7 +2,7 @@
   <a href="https://api.sylvain.sh"><img src="https://api.sylvain.sh/favicon.ico" alt="Logo" width="25%" height="auto"/></a>
 
   # API Personnelle
-  [![Version](https://custom-icon-badges.demolab.com/badge/Version%20:-v4.5.0-6479ee?logo=api.sylvain.sh&labelColor=23272A)](https://github.com/20syldev/api/releases/latest)
+  [![Version](https://custom-icon-badges.demolab.com/badge/Version%20:-v4.7.0-6479ee?logo=api.sylvain.sh&labelColor=23272A)](https://github.com/20syldev/api/releases/latest)
 </div>
 
 ---
@@ -32,10 +32,10 @@ Pour démarrer un serveur local avec tous les endpoints :
 $ npm run build && npm start
 ```
 ```console
-> @20syldev/api@4.5.0 build
+> @20syldev/api@4.7.0 build
 > tsc
 
-> @20syldev/api@4.5.0 start
+> @20syldev/api@4.7.0 start
 > node dist/app.js
 
 API is running on
@@ -88,6 +88,8 @@ L'API v4 expose plusieurs modules que vous pouvez importer :
 
 ```js
 import {
+    address,           // Génération d'adresses postales aléatoires
+    agent,             // Analyse de User-Agent (navigateur, OS, appareil)
     algorithms,        // Fonctions algorithmiques diverses
     captcha,           // Génération d'images captcha
     chat,              // Système de chat temporaire
@@ -96,15 +98,20 @@ import {
     dice,              // Lanceur de dés RPG
     domain,            // Informations de domaine aléatoires
     encode,            // Encodage / décodage (base64, morse, rot13, caesar, binaire)
+    geo,               // Informations de géolocalisation
     hash,              // Hachage de texte
     hyperplanning,     // Analyse de calendriers
+    ip,                // Analyse d'adresses IPv4/IPv6
     levenshtein,       // Distance entre chaînes
+    palette,           // Génération de palettes de couleurs
+    password,          // Génération de mots de passe sécurisés
     personal,          // Informations personnelles aléatoires
+    placeholder,       // Génération d'images placeholder
     qrcode,            // Génération de QR codes
     statistics,        // Statistiques descriptives
+    text,              // Utilitaires texte (slug, stats, lorem, nombre en lettres)
     tic_tac_toe,       // Jeu de morpion
     time,              // Informations temporelles
-    text,              // Utilitaires texte (slug, stats, lorem, nombre en lettres)
     token,             // Génération de jetons sécurisés
     username,          // Génération de noms d'utilisateur
     validate           // Validation (Luhn, IBAN, email)

package/eslint.config.js

@@ -1,4 +1,5 @@
 import eslint from '@eslint/js';
+import simpleImportSort from 'eslint-plugin-simple-import-sort';
 import tseslint from 'typescript-eslint';
 import eslintConfigPrettier from 'eslint-config-prettier';
 
@@ -7,7 +8,10 @@ export default tseslint.config(
     ...tseslint.configs.strict,
     eslintConfigPrettier,
     {
+        plugins: { 'simple-import-sort': simpleImportSort },
         rules: {
+            'simple-import-sort/imports': 'error',
+            'simple-import-sort/exports': 'error',
             '@typescript-eslint/no-explicit-any': 'warn',
             '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
             '@typescript-eslint/no-non-null-assertion': 'off',

package/package.json

@@ -1,5 +1,5 @@
 {
-    "version": "4.5.0",
+    "version": "4.7.0",
     "name": "@20syldev/api",
     "description": "Node.js API with multiple features. Check the documentation at https://docs.sylvain.sh",
     "main": "dist/app.js",
@@ -32,7 +32,7 @@
         "ical.js": "^2.1.0",
         "qrcode": "^1.5.4",
         "random": "^5.3.0",
-        "uuid": "^11.1.0"
+        "uuid": "^14.0.0"
     },
     "devDependencies": {
         "@eslint/js": "^9.24.0",
@@ -43,6 +43,7 @@
         "@types/uuid": "^10.0.0",
         "eslint": "^9.24.0",
         "eslint-config-prettier": "^10.1.1",
+        "eslint-plugin-simple-import-sort": "^13.0.0",
         "npm-check-updates": "^18.0.1",
         "prettier": "^3.5.3",
         "tsx": "^4.19.0",

package/src/app.ts

@@ -1,16 +1,17 @@
 import express from 'express';
+
 import { env } from './config/env.js';
 import { setupCors } from './middleware/cors.js';
+import { errorHandler } from './middleware/error.js';
 import { jsonResponseMiddleware } from './middleware/json.js';
-import { rateLimitMiddleware } from './middleware/ratelimit.js';
 import { loggerMiddleware } from './middleware/logger.js';
-import { errorHandler } from './middleware/error.js';
-import { versionCheckMiddleware, endpointCheckMiddleware } from './middleware/version.js';
-import indexRoutes from './routes/index.js';
+import { rateLimitMiddleware } from './middleware/ratelimit.js';
+import { endpointCheckMiddleware, versionCheckMiddleware } from './middleware/version.js';
+import deleteRoutes from './routes/delete.js';
 import getRoutes from './routes/get.js';
-import postRoutes from './routes/post.js';
+import indexRoutes from './routes/index.js';
 import patchRoutes from './routes/patch.js';
-import deleteRoutes from './routes/delete.js';
+import postRoutes from './routes/post.js';
 
 const app = express();
 

package/src/config/env.ts

@@ -1,4 +1,5 @@
 import dotenv from 'dotenv';
+
 import { DEFAULT_PORT } from '../constants.js';
 
 dotenv.config();

package/src/config/versions.ts

@@ -78,6 +78,8 @@ const v3 = {
 
 const v4 = {
     get: merge(v3.get, [
+        { name: 'address', path: '/address(&country={code}&count={n})' },
+        { name: 'agent', path: '/agent(&ua={string})' },
         {
             name: 'captcha',
             path: '/captcha(&text={text}&length={n}&width={px}&height={px}&noise={low|medium|high}&bg={hex}&color={hex})',
@@ -87,15 +89,21 @@ const v4 = {
         { name: 'dice', path: '/dice?roll={NdX+M}' },
         { name: 'encode', path: '/encode?method={method}&text={text}(&shift={shift})' },
         { name: 'geo', path: '/geo?lat1={lat}&lon1={lon}&lat2={lat}&lon2={lon}' },
+        { name: 'headers', path: '/headers(&filter={header1,header2})' },
+        { name: 'ip', path: '/ip(&address={ip})' },
         { name: 'palette', path: '/palette?color={#hex}&type={type}' },
         {
-            name: 'qrcode',
-            path: '/qrcode?url={URL}(&size={px}&margin={n}&correction={L|M|Q|H}&dark={hex}&light={hex}&icon={URL}&iconSize={px}&iconPadding={px}&iconRadius={px}&format={png|base64})',
+            name: 'password',
+            path: '/password(&type={random|passphrase}&length={n}&uppercase={bool}&lowercase={bool}&digits={bool}&symbols={bool}&exclude={chars}&count={n}&separator={char})',
         },
         {
             name: 'placeholder',
             path: '/placeholder?type={image|skeleton}&width={w}&height={h}(&bg={hex}&color={hex}&text={text}&rows={n}&avatar={bool})',
         },
+        {
+            name: 'qrcode',
+            path: '/qrcode?url={URL}(&size={px}&margin={n}&correction={L|M|Q|H}&dark={hex}&light={hex}&icon={URL}&iconSize={px}&iconPadding={px}&iconRadius={px}&format={png|base64})',
+        },
         { name: 'statistics', path: '/statistics?values={n1,n2,n3,...}' },
         { name: 'text', path: '/text?method={method}(&value={value}&type={type}&count={count}&lang={lang})' },
         { name: 'validate', path: '/validate?type={type}&value={value}' },

package/src/middleware/error.ts

@@ -1,4 +1,5 @@
-import type { Request, Response, NextFunction } from 'express';
+import type { NextFunction, Request, Response } from 'express';
+
 import { error } from '../utils/response.js';
 
 export function errorHandler(

package/src/middleware/json.ts

@@ -1,4 +1,4 @@
-import type { Request, Response, NextFunction } from 'express';
+import type { NextFunction, Request, Response } from 'express';
 
 export function jsonResponseMiddleware(_req: Request, res: Response, next: NextFunction): void {
     res.setHeader('Content-Type', 'application/json');

package/src/middleware/logger.ts

@@ -1,5 +1,6 @@
 import { createLogger } from '@20syldev/logger.ts';
-import type { Request, Response, NextFunction } from 'express';
+import type { NextFunction, Request, Response } from 'express';
+
 import { MAX_LOG_ENTRIES } from '../constants.js';
 
 export const logger = createLogger({

package/src/middleware/ratelimit.ts

@@ -1,8 +1,9 @@
-import type { Request, Response, NextFunction } from 'express';
-import { ipLimits } from '../storage/index.js';
+import type { NextFunction, Request, Response } from 'express';
+
+import { getPlan, globalLimit } from '../config/plans.js';
 import { RATE_LIMIT_WINDOW, SESSION_TTL } from '../constants.js';
+import { ipLimits } from '../storage/index.js';
 import { error } from '../utils/response.js';
-import { getPlan, globalLimit } from '../config/plans.js';
 
 let requests = 0;
 let resetTime = Date.now() + SESSION_TTL;

package/src/middleware/version.ts

@@ -1,4 +1,5 @@
-import type { Request, Response, NextFunction } from 'express';
+import type { NextFunction, Request, Response } from 'express';
+
 import { versions } from '../config/versions.js';
 import { error } from '../utils/response.js';
 

package/src/modules/v3.js

@@ -1,6 +1,6 @@
 export * as algorithms from './v3/algorithms.js';
-export { default as chat } from './v3/chat.js';
 export { default as captcha } from './v3/captcha.js';
+export { default as chat } from './v3/chat.js';
 export { default as color } from './v3/color.js';
 export { default as convert } from './v3/convert.js';
 export { default as domain } from './v3/domain.js';

package/src/modules/v4/address.ts

@@ -0,0 +1,413 @@
+import { random, randomNumber } from '../../utils/helpers.js';
+
+const MAX_COUNT = 10;
+
+interface CountryData {
+    name: string;
+    streetTypes: string[];
+    streetNames: string[];
+    cities: string[];
+    regions: string[];
+    zipFormat: () => string;
+}
+
+function randomChar(chars: string): string {
+    return chars[Math.floor(Math.random() * chars.length)]!;
+}
+
+const ALPHA = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+
+const countries: Record<string, CountryData> = {
+    fr: {
+        name: 'France',
+        streetTypes: ['Rue', 'Avenue', 'Boulevard', 'Allée', 'Impasse', 'Place', 'Chemin', 'Route', 'Voie', 'Passage'],
+        streetNames: [
+            'de la Paix',
+            'Victor Hugo',
+            'Jean Jaurès',
+            'de la République',
+            'du Général de Gaulle',
+            'de la Liberté',
+            'des Fleurs',
+            'du Moulin',
+            'de la Forêt',
+            'des Lilas',
+            'du Château',
+            'de la Mairie',
+            'de la Gare',
+            'du Commerce',
+            'de la Fontaine',
+            'de la Croix',
+            'des Vignes',
+            'du Marché',
+            "de l'Église",
+            'des Acacias',
+        ],
+        cities: [
+            'Paris',
+            'Lyon',
+            'Marseille',
+            'Toulouse',
+            'Nice',
+            'Nantes',
+            'Strasbourg',
+            'Montpellier',
+            'Bordeaux',
+            'Lille',
+            'Rennes',
+            'Reims',
+            'Le Havre',
+            'Saint-Étienne',
+            'Toulon',
+            'Grenoble',
+            'Dijon',
+            'Angers',
+            'Nîmes',
+            'Villeurbanne',
+        ],
+        regions: [
+            'Île-de-France',
+            'Auvergne-Rhône-Alpes',
+            "Provence-Alpes-Côte d'Azur",
+            'Occitanie',
+            'Hauts-de-France',
+            'Nouvelle-Aquitaine',
+            'Grand Est',
+            'Pays de la Loire',
+            'Bretagne',
+            'Normandie',
+            'Bourgogne-Franche-Comté',
+            'Centre-Val de Loire',
+        ],
+        zipFormat: () => String(randomNumber(10000, 99999)).padStart(5, '0'),
+    },
+    us: {
+        name: 'United States',
+        streetTypes: ['Street', 'Avenue', 'Boulevard', 'Drive', 'Road', 'Lane', 'Court', 'Way', 'Place', 'Circle'],
+        streetNames: [
+            'Main',
+            'Oak',
+            'Maple',
+            'Cedar',
+            'Pine',
+            'Elm',
+            'Washington',
+            'Lincoln',
+            'Park',
+            'Lake',
+            'Hill',
+            'River',
+            'Sunset',
+            'Forest',
+            'Meadow',
+            'Valley',
+            'Highland',
+            'Willow',
+            'Spring',
+            'Church',
+        ],
+        cities: [
+            'New York',
+            'Los Angeles',
+            'Chicago',
+            'Houston',
+            'Phoenix',
+            'Philadelphia',
+            'San Antonio',
+            'San Diego',
+            'Dallas',
+            'San Jose',
+            'Austin',
+            'Jacksonville',
+            'Fort Worth',
+            'Columbus',
+            'Charlotte',
+            'Indianapolis',
+            'San Francisco',
+            'Seattle',
+            'Denver',
+            'Nashville',
+        ],
+        regions: [
+            'California',
+            'Texas',
+            'Florida',
+            'New York',
+            'Pennsylvania',
+            'Illinois',
+            'Ohio',
+            'Georgia',
+            'North Carolina',
+            'Michigan',
+            'New Jersey',
+            'Virginia',
+            'Washington',
+            'Arizona',
+            'Massachusetts',
+            'Tennessee',
+            'Indiana',
+            'Colorado',
+            'Missouri',
+            'Maryland',
+        ],
+        zipFormat: () => String(randomNumber(10000, 99999)).padStart(5, '0'),
+    },
+    uk: {
+        name: 'United Kingdom',
+        streetTypes: ['Street', 'Road', 'Avenue', 'Lane', 'Close', 'Drive', 'Way', 'Court', 'Grove', 'Place'],
+        streetNames: [
+            'High',
+            'Church',
+            'Station',
+            'Park',
+            'Manor',
+            'Mill',
+            'Victoria',
+            'King',
+            'Queen',
+            'Albert',
+            'George',
+            'York',
+            'Oxford',
+            'Cambridge',
+            'Windsor',
+            'Richmond',
+            'Elm',
+            'Oak',
+            'Ash',
+            'Rose',
+        ],
+        cities: [
+            'London',
+            'Birmingham',
+            'Manchester',
+            'Glasgow',
+            'Liverpool',
+            'Bristol',
+            'Sheffield',
+            'Leeds',
+            'Edinburgh',
+            'Leicester',
+            'Coventry',
+            'Bradford',
+            'Cardiff',
+            'Belfast',
+            'Nottingham',
+            'Kingston upon Hull',
+            'Newcastle',
+            'Stoke-on-Trent',
+            'Southampton',
+            'Derby',
+        ],
+        regions: [
+            'England',
+            'Scotland',
+            'Wales',
+            'Northern Ireland',
+            'Greater London',
+            'South East',
+            'North West',
+            'East of England',
+            'West Midlands',
+            'South West',
+            'Yorkshire',
+            'East Midlands',
+            'North East',
+        ],
+        zipFormat: () =>
+            `${randomChar(ALPHA)}${randomChar(ALPHA)}${randomNumber(1, 9)} ${randomNumber(1, 9)}${randomChar(ALPHA)}${randomChar(ALPHA)}`,
+    },
+    de: {
+        name: 'Germany',
+        streetTypes: ['Straße', 'Allee', 'Weg', 'Platz', 'Gasse', 'Ring', 'Damm', 'Ufer', 'Stieg', 'Pfad'],
+        streetNames: [
+            'Haupt',
+            'Bahnhof',
+            'Schul',
+            'Kirch',
+            'Garten',
+            'Berg',
+            'Wald',
+            'Wiesen',
+            'Tal',
+            'See',
+            'Bismarck',
+            'Goethe',
+            'Schiller',
+            'Kant',
+            'Hegel',
+            'Mozart',
+            'Beethoven',
+            'Bach',
+            'Brahms',
+            'Handel',
+        ],
+        cities: [
+            'Berlin',
+            'Hamburg',
+            'Munich',
+            'Cologne',
+            'Frankfurt',
+            'Stuttgart',
+            'Düsseldorf',
+            'Leipzig',
+            'Dortmund',
+            'Essen',
+            'Bremen',
+            'Dresden',
+            'Hanover',
+            'Nuremberg',
+            'Duisburg',
+            'Bochum',
+            'Wuppertal',
+            'Bielefeld',
+            'Bonn',
+            'Münster',
+        ],
+        regions: [
+            'Bayern',
+            'Nordrhein-Westfalen',
+            'Baden-Württemberg',
+            'Niedersachsen',
+            'Hessen',
+            'Sachsen',
+            'Rheinland-Pfalz',
+            'Berlin',
+            'Schleswig-Holstein',
+            'Brandenburg',
+            'Sachsen-Anhalt',
+            'Thüringen',
+            'Hamburg',
+            'Mecklenburg-Vorpommern',
+            'Bremen',
+            'Saarland',
+        ],
+        zipFormat: () => String(randomNumber(10000, 99999)).padStart(5, '0'),
+    },
+    es: {
+        name: 'Spain',
+        streetTypes: [
+            'Calle',
+            'Avenida',
+            'Plaza',
+            'Paseo',
+            'Rambla',
+            'Carretera',
+            'Camino',
+            'Vía',
+            'Travesía',
+            'Callejón',
+        ],
+        streetNames: [
+            'Mayor',
+            'Real',
+            'Nueva',
+            'del Sol',
+            'de la Luna',
+            'del Rey',
+            'de la Reina',
+            'del Mar',
+            'de la Paz',
+            'de la Victoria',
+            'Cervantes',
+            'Goya',
+            'Velázquez',
+            'Picasso',
+            'Dalí',
+            'de España',
+            'de Colón',
+            'de la Constitución',
+            'del Prado',
+            'de las Flores',
+        ],
+        cities: [
+            'Madrid',
+            'Barcelona',
+            'Valencia',
+            'Seville',
+            'Zaragoza',
+            'Málaga',
+            'Murcia',
+            'Palma',
+            'Las Palmas',
+            'Bilbao',
+            'Alicante',
+            'Córdoba',
+            'Valladolid',
+            'Vigo',
+            'Gijón',
+            'Hospitalet',
+            'A Coruña',
+            'Granada',
+            'Vitoria',
+            'Elche',
+        ],
+        regions: [
+            'Andalucía',
+            'Cataluña',
+            'Madrid',
+            'Comunidad Valenciana',
+            'Galicia',
+            'Castilla y León',
+            'País Vasco',
+            'Castilla-La Mancha',
+            'Canarias',
+            'Murcia',
+            'Aragón',
+            'Extremadura',
+            'Asturias',
+            'Navarra',
+            'Cantabria',
+            'La Rioja',
+            'Baleares',
+        ],
+        zipFormat: () => String(randomNumber(10000, 52999)).padStart(5, '0'),
+    },
+};
+
+const countryKeys = Object.keys(countries);
+
+export interface Address {
+    street: string;
+    city: string;
+    zip: string;
+    state: string;
+    country: string;
+    countryCode: string;
+}
+
+export interface AddressResult {
+    addresses: Address[];
+}
+
+/**
+ * Generates one or more fictional postal addresses for a given country.
+ *
+ * @param countryCode - Country code: "fr", "us", "uk", "de", or "es" (random if omitted)
+ * @param count - Number of addresses to generate (1–10)
+ * @returns Array of addresses with street, city, zip, state, country, and countryCode
+ * @throws Error if the country code is invalid or count is out of range
+ */
+export default function address(countryCode?: string, count: number = 1): AddressResult {
+    if (count < 1 || count > MAX_COUNT) {
+        throw new Error(`Count must be between 1 and ${MAX_COUNT}`);
+    }
+
+    const code = (countryCode ?? random(countryKeys)).toLowerCase();
+    if (!countries[code]) {
+        throw new Error(`Unknown country code "${code}". Supported: ${countryKeys.join(', ')}`);
+    }
+
+    const data = countries[code]!;
+
+    const addresses: Address[] = Array.from({ length: count }, () => ({
+        street: `${randomNumber(1, 200)} ${random(data.streetTypes)} ${random(data.streetNames)}`,
+        city: random(data.cities),
+        zip: data.zipFormat(),
+        state: random(data.regions),
+        country: data.name,
+        countryCode: code.toUpperCase(),
+    }));
+
+    return { addresses };
+}