neekuro 2.0.4 → 2.2.0

package/sources/typings/index.d.ts

@@ -1,6 +1,4 @@
-import { Response } from "node-fetch";
-
-//#region constants
+//#region constants
 
 /**
  * Categoria SFW
@@ -9,7 +7,7 @@ import { Response } from "node-fetch";
  * // 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 
@@ -25,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
 
@@ -109,8 +117,9 @@ export interface WelcomeTextData {
     text_color?: string
 }
 
-export interface WelcomeData {
-    font: FontNames;
+export interface WelcomeData {
+    font: FontNames;
+    layout: 'center' | 'manual';
     width: number;
     height: number;
     background: WelcomeBackgroundData;
@@ -137,22 +146,28 @@ 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
     reaction: ReactionGifs
 }
 
-export interface GifResponse extends ApiResponse {
-    data?: {
-        url: string;
-        anime: string;
-    }
-}
+export interface GifResponse extends ApiResponse {
+    data: GifData
+}
+
+export interface GifListResponse extends ApiResponse {
+    data: GifData[]
+}
 
 export interface ApiResponse {
     message?: string,
@@ -187,7 +202,10 @@ export class Welcome {
      * @param height Alto en píxeles o 'default' para 450px
      * @throws {NekoError} Si los parámetros son inválidos
      */
-    setResolution(width: number | 'default', height: number | 'default'): this;
+    setResolution(width: number | 'default', height: number | 'default'): this;
+
+    /** Selecciona distribución automática centrada o coordenadas manuales. */
+    setLayout(layout: 'center' | 'manual'): this;
 
     /**
      * Configura la tipografía para el texto de la imagen
@@ -253,7 +271,7 @@ export class User {
      * puedes establecer el token a partir de aqui, pero recomiendo usar el metodo dedicado
      * @param token Token de la api
      */
-    constructor(token: string);
+    constructor(token?: string);
     /**
      * establece el token para usar la api
      * @example 
@@ -301,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
@@ -314,7 +335,7 @@ export class BaseUser {
  * Clase APIClient
  * Se encarga de hacer las solicitudes al servidor
  */
-export class APIClient {
+export class APIClient {
     /**
      * Instanciamiento de la clase
      * @param baseUrl baseUrl: link principal de la api
@@ -328,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): Promise<GifResponse>
-}
+    public get<T extends ApiResponse = GifResponse>(endpoint: string, options?: { timeout?: number }): Promise<T>
+}
 
 /**
  * Clase APIError
@@ -362,23 +383,26 @@ export class APIError extends Error {
     /**
      * Instanciamiento de un error de api 
      * @param endpoint endpoint: ruta solicitada
-     * @param response response: respuesta por node-fetch
+     * @param response respuesta HTTP o representación de un error de red
      * @param data data: objeto dado por la api
      */
-    constructor(endpoint: string, response: Awaited<Response>, data: ApiResponse);
+    constructor(endpoint: string, response: { url?: string; status?: number }, data: ApiResponse);
 }
 
 /**
  * Clase NekoError
  * Errores personalizados respecto al paquete
  */
-export class NekoError extends Error {
+export class NekoError extends Error {
     /**
      * Instanciamiento de un error del paquete
      * @param name name: nombre del error
      * @param message message: mensaje del error
      */
     constructor(name: string, message: string);
-}
+}
+
+/** Alias heredado de versiones 2.0.x. Prefiere NekoError. */
+export { NekoError as Error };
 
-//#endregion
+//#endregion

package/sources/utils/imageLoader.js

@@ -0,0 +1,146 @@
+'use strict';
+
+const dns = require('node:dns').promises;
+const net = require('node:net');
+const Canvas = require('canvas');
+const NekoError = require('../classes/errors/Error.js');
+
+const MAX_IMAGE_BYTES = 10 * 1024 * 1024;
+const IMAGE_TIMEOUT_MS = 10_000;
+const MAX_REDIRECTS = 3;
+const IMAGE_CONTENT_TYPES = new Set(['image/jpeg', 'image/png', 'image/gif', 'image/webp']);
+
+async function loadImageSource(source, label = 'imagen') {
+    if (Buffer.isBuffer(source)) {
+        validateImageBuffer(source, label);
+        return Canvas.loadImage(source);
+    }
+    return Canvas.loadImage(await downloadImage(source, label));
+}
+
+async function downloadImage(source, label = 'imagen') {
+    let currentURL = parseRemoteURL(source, label);
+
+    for (let redirects = 0; redirects <= MAX_REDIRECTS; redirects += 1) {
+        await assertPublicHostname(currentURL.hostname, label);
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), IMAGE_TIMEOUT_MS);
+        let response;
+        try {
+            response = await fetch(currentURL, {
+                redirect: 'manual',
+                signal: controller.signal,
+                headers: { 'User-Agent': 'neekuro/2.1 image-loader' }
+            });
+        } catch (error) {
+            const message = error?.name === 'AbortError'
+                ? `La descarga de ${label} excedió ${IMAGE_TIMEOUT_MS} ms`
+                : `No se pudo descargar ${label}: ${error?.message ?? 'error desconocido'}`;
+            throw new NekoError('ImageDownloadError', message);
+        } finally {
+            clearTimeout(timeoutId);
+        }
+
+        if (response.status >= 300 && response.status < 400) {
+            const location = response.headers.get('location');
+            if (!location || redirects === MAX_REDIRECTS) {
+                throw new NekoError('ImageDownloadError', `Demasiadas redirecciones al descargar ${label}`);
+            }
+            currentURL = parseRemoteURL(new URL(location, currentURL).href, label);
+            continue;
+        }
+        if (!response.ok) {
+            throw new NekoError('ImageDownloadError', `No se pudo descargar ${label}: HTTP ${response.status}`);
+        }
+
+        const contentType = response.headers.get('content-type')?.split(';', 1)[0].toLowerCase();
+        if (!contentType || !IMAGE_CONTENT_TYPES.has(contentType)) {
+            throw new NekoError('ImageFormatError', `${label} no tiene un formato de imagen compatible`);
+        }
+        const declaredLength = Number(response.headers.get('content-length'));
+        if (Number.isFinite(declaredLength) && declaredLength > MAX_IMAGE_BYTES) {
+            throw new NekoError('ImageSizeError', `${label} supera el límite de 10 MB`);
+        }
+        return readLimitedBody(response, label);
+    }
+    throw new NekoError('ImageDownloadError', `No se pudo descargar ${label}`);
+}
+
+function parseRemoteURL(source, label) {
+    if (typeof source !== 'string') {
+        throw new NekoError('ImageURLerror', `${label} debe ser una URL HTTPS o un Buffer`);
+    }
+    let url;
+    try {
+        url = new URL(source);
+    } catch {
+        throw new NekoError('ImageURLerror', `La URL de ${label} no es válida`);
+    }
+    if (url.protocol !== 'https:' || url.username || url.password) {
+        throw new NekoError('ImageURLerror', `La URL de ${label} debe utilizar HTTPS y no incluir credenciales`);
+    }
+    return url;
+}
+
+async function assertPublicHostname(hostname, label) {
+    const normalized = hostname.toLowerCase().replace(/\.$/, '');
+    if (normalized === 'localhost' || normalized.endsWith('.localhost') || normalized.endsWith('.local')) {
+        throw new NekoError('ImageURLerror', `La URL de ${label} apunta a una red local`);
+    }
+    const addresses = net.isIP(normalized)
+        ? [{ address: normalized }]
+        : await dns.lookup(normalized, { all: true, verbatim: true }).catch(() => []);
+    if (!addresses.length || addresses.some(({ address }) => isPrivateAddress(address))) {
+        throw new NekoError('ImageURLerror', `La URL de ${label} no apunta a una dirección pública`);
+    }
+}
+
+function isPrivateAddress(address) {
+    if (net.isIPv4(address)) {
+        const [a, b] = address.split('.').map(Number);
+        return a === 0 || a === 10 || a === 127 ||
+            (a === 100 && b >= 64 && b <= 127) || (a === 169 && b === 254) ||
+            (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) ||
+            (a === 198 && (b === 18 || b === 19)) || a >= 224;
+    }
+    if (net.isIPv6(address)) {
+        const value = address.toLowerCase();
+        return value === '::' || value === '::1' || value.startsWith('fc') || value.startsWith('fd') ||
+            /^fe[89ab]/.test(value) || value.startsWith('ff') || value.startsWith('2001:db8:') ||
+            (value.startsWith('::ffff:') && isPrivateAddress(value.slice(7)));
+    }
+    return true;
+}
+
+async function readLimitedBody(response, label) {
+    if (!response.body) throw new NekoError('ImageDownloadError', `${label} no contiene datos`);
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of response.body) {
+        const buffer = Buffer.from(chunk);
+        size += buffer.length;
+        if (size > MAX_IMAGE_BYTES) {
+            await response.body.cancel().catch(() => undefined);
+            throw new NekoError('ImageSizeError', `${label} supera el límite de 10 MB`);
+        }
+        chunks.push(buffer);
+    }
+    const result = Buffer.concat(chunks);
+    validateImageBuffer(result, label);
+    return result;
+}
+
+function validateImageBuffer(buffer, label = 'imagen') {
+    if (!Buffer.isBuffer(buffer) || buffer.length < 12) {
+        throw new NekoError('ImageFormatError', `${label} no contiene una imagen válida`);
+    }
+    if (buffer.length > MAX_IMAGE_BYTES) {
+        throw new NekoError('ImageSizeError', `${label} supera el límite de 10 MB`);
+    }
+    const header = buffer.subarray(0, 12).toString('hex');
+    const valid = header.startsWith('ffd8ff') || header.startsWith('89504e470d0a1a0a') ||
+        header.startsWith('47494638') || (header.slice(0, 8) === '52494646' && header.slice(16, 24) === '57454250');
+    if (!valid) throw new NekoError('ImageFormatError', `${label} debe ser JPEG, PNG, GIF o WebP`);
+}
+
+module.exports = { IMAGE_TIMEOUT_MS, MAX_IMAGE_BYTES, isPrivateAddress, loadImageSource, parseRemoteURL, validateImageBuffer };