neekuro 2.0.4 → 2.2.0

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+## [2.2.0] - 28-08-2026
+
+### Added
+- `SFW.getGifs()` permite obtener todas las imágenes de una subcategoría.
+- `SFW.clearCache()` permite invalidar toda la caché, una categoría o una subcategoría.
+- `SFW.setBaseURL()` permite configurar un endpoint HTTPS alternativo.
+- `SFW.setCacheTTL()` permite configurar o desactivar el tiempo de caché.
+
+### Changed
+- `SFW.getGif()` conserva listas en memoria durante cinco minutos y selecciona aleatoriamente en cada llamada.
+- Las solicitudes concurrentes para la misma subcategoría se agrupan en una sola petición HTTP.
+- Cuando existen varias imágenes se evita repetir inmediatamente la selección anterior.
+- Cambiar el token invalida automáticamente las listas obtenidas con el token previo.
+- El cliente REST admite respuestas tipadas distintas a un único GIF.
+
+### Compatibility
+- `SFW.getGif(category, gif)` mantiene la misma firma y continúa devolviendo `NekoGif`.
+- La caché solamente cambia la frecuencia de consulta; no fija una imagen durante el TTL.
+
+## [2.1.0] - 28-08-2026
+
+### Changed
+- Se corrigieron imports sensibles a mayúsculas para funcionar en Linux.
+- Se eliminó la dependencia circular del paquete hacia sí mismo y `node-fetch`.
+- `Welcome` valida resolución, coordenadas, radios, fuentes e imágenes con límites seguros.
+- Avatar, título y descripción utilizan una columna centrada automática con modo manual opcional.
+- Las imágenes remotas requieren HTTPS, tienen timeout, límite de 10 MB y bloqueo de redes privadas.
+- El cliente REST usa `fetch` nativo, timeout y conserva el error concreto de red.
+- Se alinearon los exports, la implementación y las declaraciones TypeScript.
+
+### Compatibility
+- Se conserva la API encadenable de `Welcome`.
+- `Error` continúa disponible como alias de `NekoError`.
+- Las URLs HTTP de imágenes dejan de aceptarse; deben utilizar HTTPS.
+
+## [2.0.3] - 07-04-2025
+
+### Fixed
+- **Error de Importaciones**
+  - Corregido el error de importaciones require('...')`
+  - Causaba que no se pudiera usar el paquete
+  - Se uso el mismo nombre para todas las importaciones respecto al archivo
+  - Afectaba a todos los usuarios que hacian uso de la api
+
+**Impacto**: 
+- La actualizacion prevee que resuelva el error
+- No requiere cambios en implementaciones existentes
+
+Commit: (1e7380a)

package/README.md

@@ -56,7 +56,7 @@ const neekuro = require('neekuro');
  */
 
 // es necesario escribir todo siempre dentro de una funcion asincrona
-async function ObtenerImagen() {
+async function ObtenerImagen() {
     // obtenemos un gif con el metodo getGif de SFW
     const cuddle = await neekuro.SFW.getGif('action', 'cuddle');
     
@@ -65,11 +65,45 @@ async function ObtenerImagen() {
 }
 
 // ejecutamos la funcion
-ObtenerImagen();
+ObtenerImagen();
 
 // nota: no te aguites por el gif y subcategoria, todo viene en documentado con typescript, solo tienes que completar los pasos :)
-```
-#### Ejemplo de imagenes de bienvenida
+```
+
+`getGif()` selecciona una imagen nuevamente en cada llamada. Internamente, NeeKuro
+conserva durante cinco minutos la lista de la subcategoría para reducir solicitudes
+HTTP; no conserva un único GIF durante ese tiempo. Cuando existen varias imágenes,
+evita mostrar la misma dos veces consecutivas.
+
+También puedes obtener la lista completa:
+
+```javascript
+const gifs = await neekuro.SFW.getGifs('action', 'cuddle');
+console.log(gifs.map(gif => gif.getUrl()));
+```
+
+Si actualizaste el catálogo y necesitas consultarlo inmediatamente, puedes limpiar
+una subcategoría, una categoría completa o toda la caché:
+
+```javascript
+neekuro.SFW.clearCache('action', 'cuddle');
+neekuro.SFW.clearCache('action');
+neekuro.SFW.clearCache();
+```
+
+El TTL se expresa en milisegundos y un valor de cero desactiva la caché:
+
+```javascript
+neekuro.SFW.setCacheTTL(5 * 60 * 1000);
+```
+
+Para pruebas o instalaciones propias de la API puede configurarse otra URL HTTPS:
+
+```javascript
+neekuro.SFW.setBaseURL('https://api.example.com/api/sfw');
+```
+
+#### Ejemplo de imagenes de bienvenida
 Las imagenes de bienvenida son otra de las alternativas que otorga NeeKuro, puedes hacer una imagen de la siguiente manera:
 ```javascript
 // obtenemos directamente la clase del paquete
@@ -83,13 +117,47 @@ const welcome = new Welcome()
   .setDescription('Al servidor de Discord');
 
 // Genera y guarda la imagen
-welcome.build()
+welcome.build()
   .then(image => fs.writeFileSync('bienvenida.png', image))
   .then(() => console.log('Imagen creada correctamente!'))
   .catch(err => console.error('Error:', err.message));
 
 // nota: como antes, todo viene bien documentado en el paquete, solo sigue los pasos y explora por ti ;3
-```
+```
+
+Las imágenes remotas deben usar HTTPS. El paquete limita cada descarga a 10 MB,
+aplica un tiempo máximo de 10 segundos, comprueba el formato y bloquea direcciones
+locales o privadas. También puedes proporcionar un `Buffer` JPEG, PNG, GIF o WebP.
+
+La resolución admite valores enteros entre 128 y 4096 píxeles. Para regresar al
+tamaño original de 1140 × 520 puedes usar:
+
+```javascript
+welcome.setResolution('default', 'default');
+```
+
+Por defecto, el avatar, el título y la descripción forman una columna centrada
+horizontal y verticalmente. El tamaño del avatar y de los textos se adapta cuando
+la resolución es pequeña. Si necesitas coordenadas personalizadas puedes activar
+el modo manual directamente o proporcionar `x`/`y` en cualquiera de los elementos:
+
+```javascript
+welcome.setLayout('manual');
+
+// Para regresar a la distribución automática:
+welcome.setLayout('center');
+```
+
+## Desarrollo
+
+```sh
+pnpm install
+pnpm run check
+pnpm run pack:check
+```
+
+`pnpm run check` ejecuta las pruebas funcionales locales y comprueba las
+declaraciones TypeScript. Ninguna de estas pruebas consulta la API remota.
 <hr>
 <center>
 <p>Resultado esperado</p>

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "neekuro",
-  "version": "2.0.4",
+  "version": "2.2.0",
   "description": "Una biblioteca de imágenes con temática de anime para bots de Discord.",
   "main": "sources/main/index.js",
   "types": "sources/typings/index.d.ts",
@@ -20,14 +20,15 @@
   "directories": {
     "test": "test"
   },
-  "files": [
-    "sources",
-    "README.md"
-  ],
+  "files": [
+    "sources",
+    "README.md",
+    "CHANGELOG.md"
+  ],
   "contributors": [
-    "cacao0027 <kzmkuro@gmail.com>"
+    "cacao0027 <kmzkuro@gmail.com>"
   ],
-  "author": "cacao0027 <kzmkuro@gmail.com>",
+  "author": "cacao0027 <kmzkuro@gmail.com>",
   "keywords": [
     "anime",
     "acción",
@@ -40,17 +41,22 @@
     "images"
   ],
   "license": "ISC",
+  "packageManager": "pnpm@11.23.0",
   "scripts": {
-    "test": "nodemon node ./test/main.test.js"
+    "test": "node --test test/*.test.js",
+    "check": "node --check sources/main/index.js && node --test test/*.test.js && tsc -p test/tsconfig.json",
+    "pack:check": "npm pack --dry-run"
   },
   "engines": {
     "node": ">=20.12.2"
   },
   "dependencies": {
     "canvas": "^3.1.0",
-    "hex-color-regex": "^1.1.0",
-    "neekuro": "file:",
-    "node-fetch": "^3.3.2"
+    "hex-color-regex": "^1.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0"
   },
   "repository": {
     "type": "git",

package/sources/classes/SFW.js

@@ -1,45 +1,292 @@
-/**
- * @typedef {import('../typings').SfwCategories} SfwCategories
- * @typedef {import('../typings').GifMap} GifMap
- */
-
-const APIClient = require('../rest/APIClient.js');
-const NekoError = require('./errors/Error.js');
-const NekoGif = require('./package/NekoGif.js');
-const { getToken } = require('./user/BaseUser.js');
-
-// url base de la api para SFW
-const base = 'https://www.nexatdc.work.gd/api/sfw'
-
-/**
- * Clase SFW
- * No se necesita instanciar para acceder a sus metodos
- */
-class SFW {
-    /**
-     * Funcion principal para obtener gifs de cierta categoria
-     * @template {SfwCategories} T
-     * @param {T} cat corresponde a la subcategoria de SFW 
-     * @param {GifMap[T]} gif corresponde al gif que quieras obtener por categoria
-     * @returns {Promise<NekoGif>}
-     */
-    static async getGif(cat, gif) {
-        if (!cat) throw new NekoError('NoInput', 'el parametro <cat> es requerido');
-        if (!gif) throw new NekoError('NoInput', 'el parametro <gif> es requerido');
-
-        let solicitud = new APIClient(base, { token: getToken() }), response = null;
-        switch (cat) {
-            case 'action':
-                response = solicitud.get('/action/' + gif + '?random=true')
-                break;
-            case 'reaction':
-                response = solicitud.get('/reaction/' + gif + '?random=true')
-                break;
-            default:
-                throw new NekoError('InvalidInput', 'la categoria que ingresas es invalida')
-        }
-        return new NekoGif(await response);
-    }
-}
-
-module.exports = SFW
+'use strict';
+
+/**
+ * @typedef {import('../typings').SfwCategories} SfwCategories
+ * @typedef {import('../typings').GifMap} GifMap
+ * @typedef {import('../typings').GifData} GifData
+ * @typedef {import('../typings').GifListResponse} GifListResponse
+ */
+
+const APIClient = require('../rest/APIClient.js');
+const NekoError = require('./errors/Error.js');
+const NekoGif = require('./package/NekoGif.js');
+const { getToken, getTokenVersion } = require('./user/BaseUser.js');
+
+const DEFAULT_BASE_URL = 'https://www.nexatdc.work.gd/api/sfw';
+const DEFAULT_CACHE_TTL = 5 * 60 * 1000;
+const MAX_CACHE_ENTRIES = 100;
+
+let baseURL = DEFAULT_BASE_URL;
+let cacheTTL = DEFAULT_CACHE_TTL;
+let globalCacheVersion = 0;
+
+/** @type {Map<string, {items: GifData[], expiresAt: number, tokenVersion: number}>} */
+const gifCache = new Map();
+/** @type {Map<string, {promise: Promise<GifData[]>, tokenVersion: number}>} */
+const gifRequests = new Map();
+/** @type {Map<string, number>} */
+const cacheVersions = new Map();
+/** @type {Map<string, number>} */
+const lastSelections = new Map();
+
+/** Cliente para obtener imágenes SFW. */
+class SFW {
+    /**
+     * Obtiene un GIF aleatorio. La lista puede provenir de caché, pero la
+     * selección se realiza nuevamente en cada llamada.
+     * @template {SfwCategories} T
+     * @param {T} category categoría principal
+     * @param {GifMap[T]} gif subcategoría solicitada
+     * @returns {Promise<NekoGif>}
+     */
+    static async getGif(category, gif) {
+        const key = getCacheKey(category, gif);
+        const items = await getGifData(category, gif, key);
+        const previousIndex = lastSelections.get(key);
+        const index = getRandomIndex(items.length, previousIndex);
+
+        lastSelections.set(key, index);
+        return createNekoGif(items[index]);
+    }
+
+    /**
+     * Obtiene todos los GIF disponibles para una subcategoría.
+     * Se devuelven instancias nuevas para impedir que el consumidor modifique
+     * accidentalmente los datos conservados en caché.
+     * @template {SfwCategories} T
+     * @param {T} category categoría principal
+     * @param {GifMap[T]} gif subcategoría solicitada
+     * @returns {Promise<NekoGif[]>}
+     */
+    static async getGifs(category, gif) {
+        const key = getCacheKey(category, gif);
+        const items = await getGifData(category, gif, key);
+        return items.map(createNekoGif);
+    }
+
+    /**
+     * Limpia toda la caché, una categoría principal o una subcategoría.
+     * @template {SfwCategories} T
+     * @param {T} [category]
+     * @param {GifMap[T]} [gif]
+     */
+    static clearCache(category, gif) {
+        if (category === undefined) {
+            globalCacheVersion += 1;
+            gifCache.clear();
+            gifRequests.clear();
+            cacheVersions.clear();
+            lastSelections.clear();
+            return;
+        }
+
+        validateCategory(category);
+        if (gif === undefined) {
+            const prefix = `${category}:`;
+            for (const key of collectKnownKeys(prefix)) clearCacheKey(key);
+            return;
+        }
+
+        clearCacheKey(getCacheKey(category, gif));
+    }
+
+    /**
+     * Cambia la URL base utilizada por SFW y vacía la caché anterior.
+     * @param {string} url
+     */
+    static setBaseURL(url) {
+        baseURL = validateBaseURL(url);
+        this.clearCache();
+    }
+
+    /**
+     * Configura la duración de la caché. Un valor de cero la desactiva.
+     * @param {number} milliseconds
+     */
+    static setCacheTTL(milliseconds) {
+        if (!Number.isFinite(milliseconds) || milliseconds < 0) {
+            throw new NekoError('InvalidCacheTTL', 'El tiempo de caché debe ser un número mayor o igual a cero');
+        }
+        cacheTTL = Math.floor(milliseconds);
+        this.clearCache();
+    }
+}
+
+/**
+ * @template {SfwCategories} T
+ * @param {T} category
+ * @param {GifMap[T]} gif
+ * @param {string} key
+ * @returns {Promise<GifData[]>}
+ */
+async function getGifData(category, gif, key) {
+    const token = getToken();
+    if (!token) throw new NekoError('NoToken', 'Debes establecer un token antes de solicitar un GIF');
+    const currentTokenVersion = getTokenVersion();
+
+    const cached = gifCache.get(key);
+    if (
+        cached
+        && cached.tokenVersion === currentTokenVersion
+        && cached.expiresAt > Date.now()
+    ) return cached.items;
+    if (cached) gifCache.delete(key);
+
+    const pending = gifRequests.get(key);
+    if (pending?.tokenVersion === currentTokenVersion) return pending.promise;
+
+    const requestGlobalVersion = globalCacheVersion;
+    const requestKeyVersion = cacheVersions.get(key) ?? 0;
+    const request = requestGifList(category, gif, token)
+        .then(items => {
+            if (
+                cacheTTL > 0
+                && requestGlobalVersion === globalCacheVersion
+                && requestKeyVersion === (cacheVersions.get(key) ?? 0)
+                && currentTokenVersion === getTokenVersion()
+            ) {
+                storeCacheEntry(key, items, currentTokenVersion);
+            }
+            return items;
+        })
+        .finally(() => {
+            if (gifRequests.get(key)?.promise === request) gifRequests.delete(key);
+        });
+
+    gifRequests.set(key, { promise: request, tokenVersion: currentTokenVersion });
+    return request;
+}
+
+/**
+ * @template {SfwCategories} T
+ * @param {T} category
+ * @param {GifMap[T]} gif
+ * @param {string} token
+ * @returns {Promise<GifData[]>}
+ */
+async function requestGifList(category, gif, token) {
+    const client = new APIClient(baseURL, { token });
+    const endpoint = `/${category}/${encodeURIComponent(String(gif))}`;
+    /** @type {GifListResponse} */
+    const response = await client.get(endpoint);
+
+    if (!Array.isArray(response?.data) || response.data.length === 0) {
+        throw new NekoError('EmptyResponse', `La API no devolvió GIF para ${category}/${gif}`);
+    }
+
+    return response.data.map((item, index) => normalizeGif(item, category, gif, index));
+}
+
+/**
+ * @param {unknown} item
+ * @param {string} category
+ * @param {string} gif
+ * @param {number} index
+ * @returns {GifData}
+ */
+function normalizeGif(item, category, gif, index) {
+    if (!item || typeof item !== 'object' || typeof item.url !== 'string' || !item.url.trim()) {
+        throw new NekoError('InvalidResponse', `El GIF ${index} de ${category}/${gif} no contiene una URL válida`);
+    }
+
+    return Object.freeze({
+        url: item.url.trim(),
+        anime: typeof item.anime === 'string' && item.anime.trim()
+            ? item.anime.trim()
+            : 'Desconocido'
+    });
+}
+
+/** @param {GifData} item @returns {NekoGif} */
+function createNekoGif(item) {
+    return new NekoGif({ code: 200, data: { ...item } });
+}
+
+/**
+ * Elige uniformemente entre todas las posiciones, excepto la selección
+ * anterior cuando existen al menos dos alternativas.
+ * @param {number} length
+ * @param {number|undefined} previousIndex
+ */
+function getRandomIndex(length, previousIndex) {
+    if (length === 1) return 0;
+    if (previousIndex === undefined || previousIndex < 0 || previousIndex >= length) {
+        return Math.floor(Math.random() * length);
+    }
+
+    const index = Math.floor(Math.random() * (length - 1));
+    return index >= previousIndex ? index + 1 : index;
+}
+
+/**
+ * @template {SfwCategories} T
+ * @param {T} category
+ * @param {GifMap[T]} gif
+ */
+function getCacheKey(category, gif) {
+    validateCategory(category);
+    if (typeof gif !== 'string' || !gif.trim()) {
+        throw new NekoError('NoInput', 'el parámetro <gif> es requerido');
+    }
+    return `${category}:${gif}`;
+}
+
+/** @param {unknown} category */
+function validateCategory(category) {
+    if (category === undefined || category === null || category === '') {
+        throw new NekoError('NoInput', 'el parámetro <category> es requerido');
+    }
+    if (category !== 'action' && category !== 'reaction') {
+        throw new NekoError('InvalidInput', 'la categoría que ingresas es inválida');
+    }
+}
+
+/** @param {string} url */
+function validateBaseURL(url) {
+    if (typeof url !== 'string' || !url.trim()) {
+        throw new NekoError('InvalidBaseURL', 'La URL base debe ser una cadena HTTPS válida');
+    }
+
+    let parsed;
+    try {
+        parsed = new URL(url);
+    } catch {
+        throw new NekoError('InvalidBaseURL', 'La URL base debe ser una cadena HTTPS válida');
+    }
+    if (parsed.protocol !== 'https:' || parsed.username || parsed.password) {
+        throw new NekoError('InvalidBaseURL', 'La URL base debe utilizar HTTPS y no incluir credenciales');
+    }
+    return url.trim().replace(/\/$/, '');
+}
+
+/** @param {string} key @param {GifData[]} items @param {number} tokenVersion */
+function storeCacheEntry(key, items, tokenVersion) {
+    if (!gifCache.has(key) && gifCache.size >= MAX_CACHE_ENTRIES) {
+        const oldest = gifCache.keys().next().value;
+        if (oldest) {
+            gifCache.delete(oldest);
+            lastSelections.delete(oldest);
+        }
+    }
+    gifCache.set(key, { items, expiresAt: Date.now() + cacheTTL, tokenVersion });
+}
+
+/** @param {string} key */
+function clearCacheKey(key) {
+    gifCache.delete(key);
+    gifRequests.delete(key);
+    lastSelections.delete(key);
+    cacheVersions.set(key, (cacheVersions.get(key) ?? 0) + 1);
+}
+
+/** @param {string} prefix */
+function collectKnownKeys(prefix) {
+    return new Set([
+        ...[...gifCache.keys()].filter(key => key.startsWith(prefix)),
+        ...[...gifRequests.keys()].filter(key => key.startsWith(prefix)),
+        ...[...lastSelections.keys()].filter(key => key.startsWith(prefix)),
+        ...[...cacheVersions.keys()].filter(key => key.startsWith(prefix))
+    ]);
+}
+
+module.exports = SFW;

package/sources/classes/errors/{APIerror.js → APIError.js}

@@ -2,7 +2,7 @@
 
 /**
  * @typedef {import('../../typings').ApiResponse} ApiResponse
- * @typedef {import('node-fetch').Response} Response
+ * @typedef {{url?: string, status?: number}} ResponseLike
  */
 
 /**
@@ -14,15 +14,13 @@ class APIError extends Error {
     /**
      * Crea la instancia del error
      * @param {string} endpoint la ruta a la que se realizo la peticion
-     * @param {Response} response respuesta de node-fetch
+     * @param {ResponseLike} response respuesta HTTP o representación de un error de red
      * @param {ApiResponse} data respuesta de la api
      */
-    constructor(endpoint, response, data) {
-        super();
+    constructor(endpoint, response, data) {
+        super(APIError.determineMessage(data));
         
         this.name = `NekoREST Error [${endpoint}]`
-        this.message = this.#determineMessage(data);
-
         /**
          * @type {string}
          */
@@ -31,7 +29,7 @@ class APIError extends Error {
         /**
          * @type {number}
          */
-        this.statusCode = parseInt(response?.status ?? 500);
+        this.statusCode = Number.parseInt(response?.status ?? 500, 10);
 
         /**
          * @type {ApiResponse}
@@ -45,7 +43,7 @@ class APIError extends Error {
      * @param {ApiResponse} response respuesta de la api
      * @returns {string} mensaje de error
      */
-    #determineMessage(response) {
+    static determineMessage(response = {}) {
         if(response.code === 403) {
             return 'TOKEN ERROR: el token que haz proporcionado es invalido'
         } else 
@@ -54,7 +52,11 @@ class APIError extends Error {
         } else {
             return response.message ?? 'descripcion no dada'
         }
-    }
-}
-
-module.exports = APIError
+    }
+
+    static fromNetworkError(endpoint, url, message) {
+        return new APIError(endpoint, { url, status: 503 }, { code: 503, message });
+    }
+}
+
+module.exports = APIError

package/sources/classes/errors/Error.js

@@ -10,16 +10,17 @@ class NekoError extends Error {
      * @param {string} name Corresponde al nombre del error
      * @param {string} message Mensaje de error
      */
-    constructor(name, message) {
-        super(message);
+    constructor(name, message) {
+        super(message);
         
         this.name = `NeeKuro Error [${name}]`
         
         /**
          * @type {string}
          */
-        this.message = message
+        this.message = message
+        Error.captureStackTrace?.(this, NekoError);
     }
 }
 
-module.exports = NekoError
+module.exports = NekoError

package/sources/classes/package/NekoGif.js

@@ -14,19 +14,22 @@ class NekoGif {
      * Recibe la respuesta de la api
      * @param {GifResponse} response respuesta de la api 
      */
-    constructor(response) {
+    constructor(response) {
+        if (!response || typeof response !== 'object' || !response.data) {
+            throw new TypeError('La respuesta no contiene datos de imagen');
+        }
         
         /**
          * URL del gif
          * @type {string|null}
          */
-        this.url = response.data.url || null
+        this.url = typeof response.data.url === 'string' ? response.data.url : null
         
         /**
          * Anime del gif
          * @type {string|null}
          */
-        this.anime = response.data.anime || null
+        this.anime = typeof response.data.anime === 'string' ? response.data.anime : null
     }
 
     /**
@@ -47,4 +50,4 @@ class NekoGif {
 
 }
 
-module.exports = NekoGif
+module.exports = NekoGif