erlc-api/README_ES.md

An ER:LC API wrapper for JS/TS

# 🚔 ER:LC API Wrapper

[![npm version](https://img.shields.io/npm/v/erlc-api?style=flat-square)](https://www.npmjs.com/package/erlc-api)
[![License](https://img.shields.io/npm/l/erlc-api?style=flat-square)](https://opensource.org/licenses/MIT)
[![Downloads](https://img.shields.io/npm/dt/erlc-api?style=flat-square)](https://www.npmjs.com/package/erlc-api)

[🇬🇧 English Version](README.md)

Una librería ligera, completa y **totalmente tipada** para interactuar con la API de _Emergency Response: Liberty County_ (ER:LC). Diseñada para ofrecer la mejor experiencia de desarrollo tanto en JavaScript como en TypeScript.

---

## ✨ Características

- 🎯 **Soporte API Actual**: Usa `https://api.erlc.gg/v2` donde está disponible.
- 🛡️ **Tipado TypeScript**: Definiciones de tipos incluidas nativamente.
- ⚡ **Ligero y Rápido**: Sin dependencias pesadas innecesarias.
- 🔒 **Seguro**: Validación de tokens y manejo de errores robusto.
- 🆕 **Actualizado**: Soporte para global API keys opcionales en apps grandes.

## 📦 Instalación

```bash
npm install erlc-api
# o
bun add erlc-api
```

## 🚀 Inicio Rápido

### Inicialización

Puedes iniciar el cliente con tu `Server Key` para reutilizarla automáticamente en todas las peticiones del servidor. El `Global Token` es opcional y solo se requiere para aplicaciones a gran escala.

**JavaScript**

```javascript
const erlc = require("erlc-api");

const client = new erlc.Client({
  serverToken: "tu-server-key-aqui",
  // globalToken: "tu-global-token-aqui", // Opcional, para apps grandes
});

await client.ready;

if (!client.connected) {
  console.error("No se pudo conectar:", client.connectionError.message);
}
```

**TypeScript**

```typescript
import { Client } from "erlc-api";

const client = new Client({
  serverToken: "tu-server-key-aqui",
});

await client.ready;
```

---

## 📖 Ejemplos de Uso

Asegúrate de tener tu `Server Key` a mano (obtenla en los ajustes de tu servidor privado en ER:LC). Cuando la key está configurada en `Client`, no necesitas volver a pasarla en cada petición.

### 🖥️ Información del Servidor

```javascript
// Obtener estado del servidor
const server = await client.getServer();
console.log(
  `Servidor: ${server.Name} | Jugadores: ${server.CurrentPlayers}/${server.MaxPlayers}`,
);

// Obtener jugadores conectados
const players = await client.getPlayers();
console.table(players); // Muestra nombre, ID, permisos y equipo

// Obtener vehículos en el mapa
const vehicles = await client.getVehicles();

// Obtener llamadas de emergencia
const emergencyCalls = await client.getEmergencyCalls();

// Obtener información del servidor con includes de v2 en una sola petición
const fullServer = await client.getServer({
  players: true,
  staff: true,
  emergencyCalls: true,
});
```

### 📜 Registros (Logs)

Accede a los historiales de actividad de tu servidor:

```javascript
// Logs de Entradas/Salidas
const joinLogs = await client.getJoinLogs();

// Logs de Muertes (Killfeed)
const killLogs = await client.getKillLogs();

// Logs de Comandos ejecutados
const commandLogs = await client.getCommandLogs();

// Logs de Llamadas a Moderadores
const modCalls = await client.getModcallLogs();
```

### 🛠️ Gestión y Administración

```javascript
// Ver lista de Baneos
const bans = await client.getBans();

// Obtener Staff del servidor
const staff = await client.getStaff();

// Obtener cola del servidor
const queue = await client.getQueue();
```

### 📢 Otros Comandos

```javascript
// Ejecutar comando remoto (Ej: Anuncio)
await client.runCommand(":h ¡Hola desde la API!");

// Resetear Global Key (Solo si tienes una configurada)
// await erlc.resetGlobalKey();
```

### Uso con Token Manual

También puedes seguir pasando la server key directamente si prefieres el estilo anterior:

```javascript
const server = await erlc.getServer("tu-server-key-aqui");
const players = await erlc.getPlayers("tu-server-key-aqui");
```

---

## 🚨 Manejo de Errores

La librería lanza errores descriptivos (`ErlcError`) que facilitan la depuración.

```javascript
try {
  const client = new erlc.Client({ serverToken: "token-invalido" });
  await client.connect();
} catch (error) {
  console.error(`Error ${error.code}: ${error.message}`);

  if (error.code === 4001)
    console.log("⏳ Rate limit alcanzado, espera un momento.");
  if (error.code === 2002)
    console.log("🔑 La Server Key es inválida o expiró.");
}
```

### Códigos Comunes

|  Código  | Significado      | Solución                                       |
| :------: | ---------------- | ---------------------------------------------- |
| **2002** | Key Inválida     | Verifica tu `Server-Key` en el juego.          |
| **3002** | Servidor Offline | El servidor no tiene jugadores o está apagado. |
| **4001** | Rate Limit       | Estás enviando muchas peticiones muy rápido.   |
| **403**  | No Autorizado    | Verifica tus permisos o tokens.                |

---

## 🔗 Enlaces Útiles

- [Documentación Oficial de ER:LC](https://apidocs.erlc.gg/)
- [Discord de Soporte PRC](https://discord.gg/prc)
- [NPM Package](https://www.npmjs.com/package/erlc-api)

---

<div align="center">
  <sub>Hecho con ❤️ para la comunidad de ER:LC</sub>
</div>