neekuro 2.1.0 → 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

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "neekuro",
-  "version": "2.1.0",
+  "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,10 +20,11 @@
   "directories": {
     "test": "test"
   },
-  "files": [
-    "sources",
-    "README.md"
-  ],
+  "files": [
+    "sources",
+    "README.md",
+    "CHANGELOG.md"
+  ],
   "contributors": [
     "cacao0027 <kmzkuro@gmail.com>"
   ],

package/sources/classes/SFW.js

@@ -1,47 +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');
-
-        const token = getToken();
-        if (!token) throw new NekoError('NoToken', 'Debes establecer un token antes de solicitar un GIF');
-        let solicitud = new APIClient(base, { token }), 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/user/BaseUser.js

@@ -1,6 +1,7 @@
 'use strict';
 
-let tokenGlobal = null;
+let tokenGlobal = null;
+let tokenVersion = 0;
 
 /**
  * Clase BaseUser
@@ -15,16 +16,26 @@ class BaseUser {
         if (typeof token !== 'string' || !token.trim()) {
             throw new TypeError('El token debe ser una cadena no vacía');
         }
-        tokenGlobal = token;
+        const normalizedToken = token.trim();
+        if (tokenGlobal !== normalizedToken) tokenVersion += 1;
+        tokenGlobal = normalizedToken;
     }
 
     /**
      * Obten el token del usuario si este ya se estableció
      * @returns {string} Token de usuario
      */
-    static getToken() {
-        return tokenGlobal;
-    }
-}
+    static getToken() {
+        return tokenGlobal;
+    }
+
+    /**
+     * Identificador interno que cambia cada vez que se establece otro token.
+     * @returns {number}
+     */
+    static getTokenVersion() {
+        return tokenVersion;
+    }
+}
 
 module.exports = BaseUser;

package/sources/rest/APIClient.js

@@ -51,7 +51,8 @@ class APIClient {
     /**
      * Obtiene el objeto compartido por la api a traves de la ruta y con autorizacion por token
      * @param {string} endpoint establece la ruta a la que se quiere comunicar
-     * @returns {Promise<GifResponse>}
+     * @template {import('../typings').ApiResponse} [T=GifResponse]
+     * @returns {Promise<T>}
      * @throws {APIError} solo si sucede un error entre solicitudes
      */
     async get(endpoint, options = {}) {
@@ -80,7 +81,7 @@ class APIClient {
                 throw new APIError(endpoint, response, data);
             }
 
-            return data
+            return /** @type {T} */ (data)
         } catch (error) {
             if (error instanceof APIError) {
                 throw error;

package/sources/typings/index.d.ts

@@ -7,7 +7,7 @@
  * // obtiene el objeto SFW
  * const SFW = require('neekuro').SFW
  */
-export const SFW: {
+export const SFW: {
     /**
      * Funcion principal para obtener gifs de cierta categoria
      * @param category category: corresponde a la subcategoria de SFW 
@@ -23,8 +23,18 @@ export const SFW: {
      * // obtener anime
      * cuddle.getAnime(); 
      */
-    getGif<T extends SfwCategories>(category: T, gif: GifMap[T]): Promise<NekoGif>
-}
+    getGif<T extends SfwCategories>(category: T, gif: GifMap[T]): Promise<NekoGif>
+    /** Obtiene todos los GIF disponibles y utiliza la caché interna. */
+    getGifs<T extends SfwCategories>(category: T, gif: GifMap[T]): Promise<NekoGif[]>
+    /** Limpia toda la caché de imágenes. */
+    clearCache(): void
+    /** Limpia la caché de una categoría completa o de una subcategoría. */
+    clearCache<T extends SfwCategories>(category: T, gif?: GifMap[T]): void
+    /** Cambia la URL HTTPS utilizada para consultar SFW. */
+    setBaseURL(url: string): void
+    /** Configura el TTL en milisegundos. El valor cero desactiva la caché. */
+    setCacheTTL(milliseconds: number): void
+}
 
 //#endregion
 
@@ -136,10 +146,15 @@ export interface WelcomeData {
     };
 }
 
-export interface NekoGifInterface {
-    url: string | null
-    anime?: string | null
-}
+export interface NekoGifInterface {
+    url: string | null
+    anime?: string | null
+}
+
+export interface GifData {
+    url: string
+    anime: string
+}
 
 export declare interface GifMap {
     action: ActionGifs
@@ -147,11 +162,12 @@ export declare interface GifMap {
 }
 
 export interface GifResponse extends ApiResponse {
-    data: {
-        url: string;
-        anime: string;
-    }
-}
+    data: GifData
+}
+
+export interface GifListResponse extends ApiResponse {
+    data: GifData[]
+}
 
 export interface ApiResponse {
     message?: string,
@@ -303,7 +319,10 @@ export class BaseUser {
      * Obten el token del usuario si este ya se estableció
      * @returns {string} Token de usuario
      */
-    public static getToken(): string
+    public static getToken(): string | null
+
+    /** Versión interna que cambia cuando se establece un token diferente. */
+    public static getTokenVersion(): number
 
     /**
      * Establece el token "global" para todo el paquete
@@ -330,8 +349,8 @@ export class APIClient {
      * @param endpoint establece la ruta a la que se quiere comunicar en la api
      * @throws {APIError} solo si sucede un error entre solicitudes
      */
-    public get(endpoint: string, options?: { timeout?: number }): Promise<GifResponse>
-}
+    public get<T extends ApiResponse = GifResponse>(endpoint: string, options?: { timeout?: number }): Promise<T>
+}
 
 /**
  * Clase APIError