neekuro 2.3.1 → 2.3.2

package/CHANGELOG.md

@@ -1,76 +1,84 @@
-# Changelog
-
-## [2.3.1] - 07-10-2026
-
-### Fixed
-- La URL por defecto del API pasa a `https://maplebot.fyi/api/sfw`. El dominio anterior dejo de resolver, asi que las versiones previas no podian obtener ninguna imagen.
-
-### Compatibility
-- No cambia ninguna firma. Quien ya fijaba su endpoint con `SFW.setBaseURL()` no se ve afectado.
-
-## [2.3.0] - 15-09-2026
-
-### Added
-- Nuevas subcategorías de `action`: `handhold`, `highfive`, `read` y `wave`.
-- Nuevas subcategorías de `reaction`: `disgust`, `facepalm`, `happy`, `love`, `nervous`, `shrug` y `surprised`.
-
-### Fixed
-- El timeout de 10 segundos de las imágenes remotas ahora también cubre la lectura del cuerpo, no solo las cabeceras.
-- Las respuestas descartadas (redirecciones, errores HTTP o formatos inválidos) liberan su conexión.
-- El User-Agent de descarga de imágenes refleja la versión real del paquete.
-- Declaraciones TypeScript: `APIError.determineMessage` es estático, se añade `APIError.fromNetworkError` y se corrige la resolución por defecto documentada (1140 × 520) y el ejemplo de `User.token()`.
-- `SFW` muestra `Desconocido` cuando el anime llega como `Unknown`, no solo cuando viene vacío.
-- `SFW` descarta las URL repetidas de una subcategoría: pesaban doble en el sorteo y podían salir dos veces seguidas.
-
-### Compatibility
-- Solo se añaden subcategorías; las existentes no cambian.
-
-## [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)
+# Changelog
+
+## [2.3.2] - 25-10-2026
+
+### Changed
+- La URL por defecto del API pasa a `https://api.maplebot.fyi/api/sfw`. El API se separa de la web y deja de responder en `maplebot.fyi/api/sfw`, asi que las versiones 2.3.1 y anteriores no pueden obtener imagenes sin fijar el endpoint.
+
+### Compatibility
+- No cambia ninguna firma. Quien no pueda actualizar puede seguir con su version llamando a `SFW.setBaseURL('https://api.maplebot.fyi/api/sfw')`.
+
+## [2.3.1] - 07-10-2026
+
+### Fixed
+- La URL por defecto del API pasa a `https://maplebot.fyi/api/sfw`. El dominio anterior dejo de resolver, asi que las versiones previas no podian obtener ninguna imagen.
+
+### Compatibility
+- No cambia ninguna firma. Quien ya fijaba su endpoint con `SFW.setBaseURL()` no se ve afectado.
+
+## [2.3.0] - 15-09-2026
+
+### Added
+- Nuevas subcategorías de `action`: `handhold`, `highfive`, `read` y `wave`.
+- Nuevas subcategorías de `reaction`: `disgust`, `facepalm`, `happy`, `love`, `nervous`, `shrug` y `surprised`.
+
+### Fixed
+- El timeout de 10 segundos de las imágenes remotas ahora también cubre la lectura del cuerpo, no solo las cabeceras.
+- Las respuestas descartadas (redirecciones, errores HTTP o formatos inválidos) liberan su conexión.
+- El User-Agent de descarga de imágenes refleja la versión real del paquete.
+- Declaraciones TypeScript: `APIError.determineMessage` es estático, se añade `APIError.fromNetworkError` y se corrige la resolución por defecto documentada (1140 × 520) y el ejemplo de `User.token()`.
+- `SFW` muestra `Desconocido` cuando el anime llega como `Unknown`, no solo cuando viene vacío.
+- `SFW` descarta las URL repetidas de una subcategoría: pesaban doble en el sorteo y podían salir dos veces seguidas.
+
+### Compatibility
+- Solo se añaden subcategorías; las existentes no cambian.
+
+## [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

@@ -166,12 +166,11 @@ declaraciones TypeScript. Ninguna de estas pruebas consulta la API remota.
 
 ## Contenido
 
-Lo siguente es lo que contiene (o contendra) el paquete
+Lo siguente es lo que contiene el paquete
 
 | Categoria | Descripción | |
 |-|-|-|
 | Sfw | Contenido de roleplay no nsfw | en desarrollo
-| Nsfw | Contenido +18 general y roleplay | no comenzada
 
 ## Finalmente....
 

package/package.json

@@ -1,69 +1,68 @@
-{
-  "$schema": "https://json.schemastore.org/package.json",
-  "name": "neekuro",
-  "version": "2.3.1",
-  "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",
-  "exports": {
-    ".": {
-      "import": {
-        "types": "./sources/typings/index.d.ts",
-        "default": "./sources/main/index.js"
-      },
-      "require": {
-        "types": "./sources/typings/index.d.ts",
-        "default": "./sources/main/index.js"
-      }
-    }
-  },
-  "directories": {
-    "test": "test"
-  },
-  "files": [
-    "sources",
-    "README.md",
-    "CHANGELOG.md"
-  ],
-  "contributors": [
-    "cacao0027 <kmzkuro@gmail.com>"
-  ],
-  "author": "cacao0027 <kmzkuro@gmail.com>",
-  "keywords": [
-    "anime",
-    "acción",
-    "gifs",
-    "imagenes",
-    "nsfw",
-    "sfw",
-    "discord",
-    "action",
-    "images"
-  ],
-  "license": "ISC",
-  "packageManager": "pnpm@11.23.0",
-  "scripts": {
-    "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"
-  },
-  "devDependencies": {
-    "@types/node": "^24.0.0",
-    "typescript": "^5.9.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/CacaoNk0027/neekuro_package.git"
-  },
-  "bugs": {
-    "url": "https://github.com/CacaoNk0027/neekuro_package/issues"
-  },
-  "homepage": "https://github.com/CacaoNk0027/neekuro_package#readme"
-}
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "neekuro",
+  "version": "2.3.2",
+  "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",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./sources/typings/index.d.ts",
+        "default": "./sources/main/index.js"
+      },
+      "require": {
+        "types": "./sources/typings/index.d.ts",
+        "default": "./sources/main/index.js"
+      }
+    }
+  },
+  "directories": {
+    "test": "test"
+  },
+  "files": [
+    "sources",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "contributors": [
+    "cacao0027 <kmzkuro@gmail.com>"
+  ],
+  "author": "cacao0027 <kmzkuro@gmail.com>",
+  "keywords": [
+    "anime",
+    "acción",
+    "gifs",
+    "imagenes",
+    "sfw",
+    "discord",
+    "action",
+    "images"
+  ],
+  "license": "ISC",
+  "packageManager": "pnpm@11.23.0",
+  "scripts": {
+    "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"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CacaoNk0027/neekuro_package.git"
+  },
+  "bugs": {
+    "url": "https://github.com/CacaoNk0027/neekuro_package/issues"
+  },
+  "homepage": "https://github.com/CacaoNk0027/neekuro_package#readme"
+}

package/sources/classes/SFW.js

@@ -1,313 +1,313 @@
-'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://maplebot.fyi/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}`);
-    }
-
-    const items = response.data.map((item, index) => normalizeGif(item, category, gif, index));
-    return removeDuplicateURLs(items);
-}
-
-const UNKNOWN_ANIME = 'Desconocido';
-// Valores que la base de datos usa para "sin dato". Se tratan igual que un
-// campo vacío para no mostrar, por ejemplo, "Unknown" en un embed en español.
-const PLACEHOLDER_ANIME = new Set(['unknown', 'desconocido']);
-
-/**
- * @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`);
-    }
-
-    const anime = typeof item.anime === 'string' ? item.anime.trim() : '';
-    return Object.freeze({
-        url: item.url.trim(),
-        anime: anime && !PLACEHOLDER_ANIME.has(anime.toLowerCase()) ? anime : UNKNOWN_ANIME
-    });
-}
-
-/**
- * Conserva la primera aparición de cada URL. Una URL repetida pesa doble en el
- * sorteo y puede salir dos veces seguidas, porque la selección evita repetir
- * posiciones, no URLs.
- * @param {GifData[]} items
- * @returns {GifData[]}
- */
-function removeDuplicateURLs(items) {
-    const seen = new Set();
-    return items.filter(item => {
-        if (seen.has(item.url)) return false;
-        seen.add(item.url);
-        return true;
-    });
-}
-
-/** @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;
+'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://api.maplebot.fyi/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}`);
+    }
+
+    const items = response.data.map((item, index) => normalizeGif(item, category, gif, index));
+    return removeDuplicateURLs(items);
+}
+
+const UNKNOWN_ANIME = 'Desconocido';
+// Valores que la base de datos usa para "sin dato". Se tratan igual que un
+// campo vacío para no mostrar, por ejemplo, "Unknown" en un embed en español.
+const PLACEHOLDER_ANIME = new Set(['unknown', 'desconocido']);
+
+/**
+ * @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`);
+    }
+
+    const anime = typeof item.anime === 'string' ? item.anime.trim() : '';
+    return Object.freeze({
+        url: item.url.trim(),
+        anime: anime && !PLACEHOLDER_ANIME.has(anime.toLowerCase()) ? anime : UNKNOWN_ANIME
+    });
+}
+
+/**
+ * Conserva la primera aparición de cada URL. Una URL repetida pesa doble en el
+ * sorteo y puede salir dos veces seguidas, porque la selección evita repetir
+ * posiciones, no URLs.
+ * @param {GifData[]} items
+ * @returns {GifData[]}
+ */
+function removeDuplicateURLs(items) {
+    const seen = new Set();
+    return items.filter(item => {
+        if (seen.has(item.url)) return false;
+        seen.add(item.url);
+        return true;
+    });
+}
+
+/** @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;