ubfb

Cliente oficial de UBFB (Universal Blacklist For Bots) — lista negra pública y compartida de usuarios maliciosos de Discord.

npm install ubfb

Uso básico

import { UBFB } from "ubfb";

const ubfb = new UBFB({ name: "MiBot" }); // name/avatarUrl son opcionales, públicos y sin verificar

ubfb.on("sync", (ids) => console.log(`${ids.length} usuarios activos`));
ubfb.on("add", (entry) => console.log("nuevo:", entry.id, entry.reason));
ubfb.on("remove", (userId) => console.log("rehabilitado:", userId));
ubfb.on("error", (err) => console.error(err));

ubfb.connect();

// en cualquier parte, sin llamada de red:
if (ubfb.isBlacklisted(userId)) {
    // ...
}

Caché local

isBlacklisted(), getCachedEntry() y getCachedEntries() leen de una caché en memoria que se mantiene al día desde dos fuentes: cada evento del WebSocket (sync/add/remove) y cada llamada REST que devuelve datos del blacklist (getBlacklistIds, getAllBlacklist, getBlacklistEntry) — no hace falta connect() para que la caché tenga algo, basta con haber pedido los datos por REST alguna vez.

await ubfb.getAllBlacklist();        // también rellena la caché
ubfb.isBlacklisted(userId);          // sin red
ubfb.getCachedEntry(userId);         // sin red — undefined si nunca vimos el detalle completo
ubfb.getCachedEntries();             // todo lo que hay en caché ahora mismo

Un matiz: sync (WS) y getBlacklistIds() (REST) solo traen IDs, no filas completas — así que isBlacklisted() puede ser true mientras getCachedEntry() devuelve undefined, hasta que llegue el detalle completo (por un evento add o por getAllBlacklist()/getBlacklistEntry()).

API REST (funciona sin connect())

import { UBFB, BlacklistReason } from "ubfb";

const ubfb = new UBFB();

await ubfb.getBlacklistIds();           // string[]
await ubfb.getAllBlacklist();           // BlacklistEntry[]
await ubfb.getBlacklistEntry(userId);   // BlacklistEntry | null

await ubfb.fileReport({
    userId,
    reason: BlacklistReason.Estafa,
    authorId, authorUsername,
    intermediaryId, intermediaryUsername,
    proofs: ["https://cdn.discordapp.com/attachments/.../screenshot.png"], // obligatorio, al menos una
});

await ubfb.exportBlacklist("json"); // "json" | "csv" | "sql", como texto plano
await ubfb.getActiveBots();         // { count, bots }

Los métodos REST lanzan UBFBApiError (con .status y .body) si la API responde con un error.

Lista de razones

import { BlacklistReasons } from "ubfb";

[...BlacklistReasons];          // BlacklistReason[], las 21 razones válidas
BlacklistReasons.length;        // 21
BlacklistReasons.toMarkdown();  // lista en markdown, una razón por línea ("- Raider\n- ...")

BlacklistReasons es una instancia de BlacklistReasonList ya poblada con todas las razones — es iterable directamente. Si necesitas un subconjunto, puedes construir la tuya: new BlacklistReasonList([BlacklistReason.Dox, BlacklistReason.Estafa]).toMarkdown().

Opciones del constructor

| Opción | Descripción | |---|---| | baseUrl | Base de la API REST. Por defecto https://ubfb-api.theindiebrand.es. | | wsUrl | URL del WebSocket de presencia. Por defecto, derivada de baseUrl. | | name | Nombre público mostrado en GET /bots/active. No autenticado. | | avatarUrl | Avatar público mostrado junto al nombre. No autenticado. | | reconnectDelayMs | Espera antes de reconectar tras una caída inesperada. Por defecto 5000. |

connect() reconecta automáticamente si la conexión se cae. close() la cierra y desactiva la reconexión.