allstargg-sdk

Cliente TypeScript/JavaScript no oficial para la Allstar Partner API. Pensado para generar highlights de CS2 (y también League of Legends y Fortnite) a partir de las demos de partida, en la nube.

⚠️ Proyecto no oficial. Basado en el ejemplo oficial "Make Your First Request" y en la referencia de la API. Algunos endpoints secundarios usan tipos "abiertos" (aceptan campos adicionales). Confirma los detalles en la referencia autenticada de tu cuenta: https://developer.allstar.gg/dashboard/api-reference/

Requisitos

• Node.js >= 18 (usa el fetch nativo).
• Una API key de partner de Allstar.

Instalación

npm install allstargg-sdk

Uso rápido (CS2)

import { AllstarClient } from "allstargg-sdk";

const allstar = new AllstarClient({
  apiKey: process.env.ALLSTAR_API_KEY!,
  // baseUrl: "https://prt.allstar.gg", // por defecto
  // apiKeyHeader: "X-API-Key",         // cabecera donde va la key
  // useBearerAuth: false,              // o Authorization: Bearer <key>
});

// Endpoint oficial "Make Your First Request": POST /api/clip_request
const res = await allstar.createClipRequest({
  steamId: "76561198000000000",
  demoUrl: "https://tu-cdn.com/partidas/match.dem",
  webhookUrl: "https://miapp.com/webhooks/allstar",
  rounds: [1],
  username: "s1mple",
  useCase: "POTG",
});

console.log("Clip en proceso:", res.requestId);

O usando las convenience methods (fijan el useCase por ti):

const res = await allstar.cs.createPotgClip({
  steamId: "76561198000000000",
  demoUrl: "https://tu-cdn.com/partidas/match.dem",
  webhookUrl: "https://miapp.com/webhooks/allstar",
  rounds: [1],
  username: "s1mple",
});

La generación es asíncrona: la API responde con un requestId y luego notifica el resultado por webhook. También puedes hacer polling:

const status = await allstar.cs.getClipStatus({ requestId: res.requestId! });
console.log(status.status); // "submitted" | "processed" | "error"

Use cases de Counter-Strike disponibles

Todas usan POST /api/clip_request fijando useCase:

| Método | useCase | Descripción | | --- | --- | --- | | cs.createPotgClip(body) | POTG | Play of the Game | | cs.createMhClip(body) | MH | Multi Highlight | | cs.createShClip(body) | SH | Single Highlight | | cs.createBpClip(body) | BP | Best Play | | cs.createPbClip(body) | PB | PB | | cs.createPmhClip(body) | PMH | Player Match Highlights | | cs.createClip(useCase, body) | (el que indiques) | Genérico |

Consulta / listado:

await allstar.cs.getClip({ clipId: "..." });
await allstar.cs.getClipStatus({ requestId: "..." });
await allstar.cs.listClips({ steam64Id: "7656...", page: 1, limit: 20 });
await allstar.cs.searchClips({ username: "s1mple" });
await allstar.cs.createMatchPlaylist({ /* filtros del match */ });
await allstar.cs.reprocessClip({ clipId: "..." });

Webhooks

Allstar envía tres eventos: clipSubmitted, clipProcessed y clipErrored. Ejemplo con Express:

import express from "express";
import {
  parseWebhookEvent,
  isClipProcessedEvent,
  isClipErroredEvent,
} from "allstargg-sdk";

const app = express();
app.use(express.json());

app.post("/webhooks/allstar", (req, res) => {
  const event = parseWebhookEvent(req.body);

  if (isClipProcessedEvent(event)) {
    console.log("Highlight listo:", event.clipUrl);
  } else if (isClipErroredEvent(event)) {
    console.error("Error al clipear:", event.message);
  }

  res.sendStatus(200);
});

Otros juegos

allstar.league.createPotgClip({ /* ... */ });
allstar.fortnite.createPotgClip({ /* ... */ });

Manejo de errores

import { AllstarApiError, AllstarConnectionError } from "allstargg-sdk";

try {
  await allstar.cs.createPotgClip({ /* ... */ });
} catch (err) {
  if (err instanceof AllstarApiError) {
    console.error(err.status, err.body, err.requestId);
  } else if (err instanceof AllstarConnectionError) {
    console.error("Fallo de red:", err.message);
  }
}

El cliente reintenta automáticamente ante errores de red y respuestas 429/5xx (configurable con maxRetries y timeoutMs).

Configuración

| Opción | Tipo | Default | Descripción | | --- | --- | --- | --- | | apiKey | string | — | Requerido. Clave de partner. | | baseUrl | string | https://prt.allstar.gg | Servidor de la API. | | apiKeyHeader | string | X-API-Key | Cabecera donde viaja la key. | | useBearerAuth | boolean | false | Envía Authorization: Bearer <key>. | | headers | object | {} | Cabeceras extra. | | timeoutMs | number | 30000 | Timeout por petición. | | maxRetries | number | 2 | Reintentos en red/429/5xx. | | fetch | typeof fetch | global | fetch personalizado. |

Si tu portal usa otra cabecera o esquema de autenticación (por ejemplo Authorization: Bearer), ajústalo con apiKeyHeader o useBearerAuth.

Publicar en npm

npm run build      # genera dist/ (ESM + CJS + tipos)
npm publish --access public

Recuerda cambiar name, author y version en package.json antes de publicar.

Licencia

MIT