# ubfb

> Official client for UBFB (Universal Blacklist For Bots) — a shared, public blacklist of malicious Discord users.

Latest version **5.0.0** (published 2026-08-23) · ISC license · 0 weekly downloads

## Install

```sh
npm install ubfb
pnpm add ubfb
yarn add ubfb
bun add ubfb
```

## Health

**Score 60/100 (C)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 5.0.0 |
| Published | 2026-08-23 |
| First published | 2022-02-23 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18 |
| Dependencies | 1 |
| Unpacked size | 51.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Maintainers | devethan6737 |
| Keywords | discord, blacklist, moderation, ubfb |

## Links

- npm: https://www.npmjs.com/package/ubfb
- Repository: https://github.com/TheIndieBrand/UBFB
- Homepage: https://github.com/TheIndieBrand/UBFB#readme
- Issues: https://github.com/TheIndieBrand/UBFB/issues
- npm.io page: https://npm.io/package/ubfb

## Dependencies (1)

- [ws](https://npm.io/package/ws.md) ^8.21.3

## Recent versions

- 5.0.0 (latest) — 2026-08-23
- 4.2.4 — 2023-06-26
- 4.2.3 — 2023-06-20
- 4.2.2 — 2023-06-20
- 4.2.1 — 2023-05-31
- 4.2.0 — 2023-05-28
- 4.1.0 — 2023-05-14
- 4.0.1 — 2023-05-10
- 4.0.0 — 2023-03-20
- 3.0.2 — 2022-09-28
- 3.0.1 — 2022-09-01
- 3.0.0 — 2022-09-01
- 2.1.2 — 2022-08-24
- 2.1.1 — 2022-08-17
- 2.1.0 — 2022-08-17
- … 30 more at https://npm.io/package/ubfb/versions

## README

# ubfb

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

```bash
npm install ubfb
```

## Uso básico

```ts
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.

```ts
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()`)

```ts
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

```ts
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.

---
_Source: https://npm.io/package/ubfb · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._