📦

Package

ubfb es el cliente oficial en TypeScript: une la API REST y el WebSocket de presencia en una sola interfaz, con una caché local para no repetir llamadas de red.

Instalación

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)) {
    // ...
}

Conexión (WebSocket)

Ninguno de los dos requiere red para responder — solo abren/cierran el socket.

SYNCconnect(): void

Abre la conexión de presencia (o reconecta). Si la conexión se cae de forma inesperada, reconecta sola trasreconnectDelayMs (5000ms por defecto) — no hace falta llamar a connect() otra vez.

SYNCclose(): void

Cierra la conexión y desactiva la reconexión automática. Para volver a conectar hace falta llamar aconnect() explícitamente.

Eventos

UBFB extiende EventEmitter de Node — ubfb.on(evento, callback). Solo llegan tras connect().

EVENTO"open" → ()

El socket se abrió (o reabrió tras una reconexión).

EVENTO"close" → ()

El socket se cerró — por close() o por una caída de conexión. Si fue una caída inesperada, justo después empieza el temporizador de reconexión.

EVENTO"error" → (error: Error)

Error de la conexión WebSocket subyacente.

EVENTO"sync" → (ids: string[])

Se emite justo al conectar: todos los IDs actualmente activos. Solo IDs, no filas completas — ver Caché local.

EVENTO"add" → (entry: BlacklistEntry)

Un usuario fue añadido a la blacklist (staff aprobó un reporte). Trae la fila completa.

EVENTO"remove" → (userId: string)

Un usuario dejó de estar activo (staff aprobó su apelación).

Caché local

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

SYNCisBlacklisted(userId: string): boolean

Si este ID está activo ahora mismo, según lo último que se sepa (por REST o por WS) — sin llamada de red.

SYNCgetCachedEntry(userId: string): BlacklistEntry | undefined

Detalles completos de un usuario, si alguna vez se recibieron. Puede ser undefined aunqueisBlacklisted() devuelva true — un sync por WS solo trae IDs, no filas completas.

SYNCgetCachedEntries(): BlacklistEntry[]

Todas las filas completas cacheadas ahora mismo — puede ser un subconjunto de todos los IDs activos (ver arriba).

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

API REST

Cada método funciona sin connect() — son llamadas independientes, y cada una que devuelve datos del blacklist también rellena la caché. Todos lanzanUBFBApiError (con .status y .body) si la API responde con un error.

ASYNCgetBlacklistIds(): Promise<string[]>

GET /blacklist/ids — todos los IDs de Discord actualmente activos.

ASYNCgetAllBlacklist(): Promise<BlacklistEntry[]>

GET /blacklist/all — todas las entradas activas, filas completas.

ASYNCgetBlacklistEntry(userId: string): Promise<BlacklistEntry | null>

GET /blacklist/:userId — la entrada de un usuario, o null si no está en la blacklist.

ASYNCgetReports(): Promise<Report[]>

GET /reports — la cola completa de reportes pendientes, de solo lectura. No es dato de blacklist — no toca la caché.

ASYNCfileReport(input: ReportInput): Promise<Report>

POST /reports — archiva un nuevo reporte. proofs debe traer al menos una URL de imagen. No toca la caché: archivar un reporte no blacklistea a nadie por sí solo, eso solo pasa cuando staff lo aprueba.

Lanza UBFBApiError: 400 si el input es inválido, 409 si el usuario ya tiene un reporte pendiente.

ASYNCexportBlacklist(format: ExportFormat): Promise<string>

GET /export?format=... — la blacklist activa como texto plano, en el formato indicado ("json" | "csv" | "sql").

ASYNCgetActiveBots(): Promise<{ count: number; bots: ActiveBot[] }>

GET /bots/active — quién está conectado ahora mismo al WebSocket de presencia.

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. Para un subconjunto propio:new BlacklistReasonList([BlacklistReason.Dox, BlacklistReason.Estafa]).toMarkdown().

Opciones y tipos

Opciones del constructor

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

También exportado

UBFB	La clase principal — event emitter + REST + caché, todo en uno.
UBFBPresence	Solo el WebSocket de presencia, sin caché ni REST — para quien quiera manejarlo por separado.
UBFBRest	Solo las llamadas REST, sin WebSocket ni caché.
UBFBCache	La caché en memoria por sí sola.
UBFBApiError	Error lanzado por los métodos REST — trae .status y .body.
BlacklistReason	Enum con las 21 razones válidas — el mismo que usa la API.
BlacklistStatus	Enum del estado de una entrada: Activo, Inactivo, En votación.
BlacklistEntry	Una fila del blacklist activo.
Report	Un reporte pendiente, tal como lo devuelve fileReport()/getReports().
ReportInput	El body que espera fileReport().
ActiveBot	Un cliente conectado ahora mismo al WebSocket de presencia.
ExportFormat	"json" \| "csv" \| "sql" — el tipo del argumento de exportBlacklist().