Events API

@v5x/events is a strictly typed TypeScript client for the VEX Events API v2. It works in browsers, Bun, and modern Node.js runtimes with fetch.

bun add @v5x/events

Create a personal access token in your VEX Events account, then initialize the client:

import { Robot } from "@v5x/events";

const robot = new Robot({
  token: process.env.VEX_EVENTS_TOKEN!,
});

Search complete collections

The client groups the complete API under events, teams, programs, and seasons. Every collection method automatically retrieves all matching pages and returns a plain array.

const events = await robot.events.search({
  seasons: [seasonId],
  eventTypes: ["tournament"],
});

const team = await robot.teams.getByNumber("123A", robot.programs.V5RC);

const matches = await robot.events.matches(eventId, divisionId, {
  rounds: [robot.rounds.qualification],
});

Collection methods start at page 1, request 250 items per page, and follow the API’s pagination metadata. Broad filters can make many requests and retain the complete result set in memory. Pass an AbortSignal separately from filters to cancel the current request, pagination, or a retry delay:

const controller = new AbortController();

const teams = await robot.teams.search(
  { registered: true },
  { signal: controller.signal },
);

Options use camelCase names and normal arrays. The client translates these to the API’s snake_case and repeated field[] parameters. Date filters accept an RFC 3339 string or a Date. The eventTypes option is handled by the API and is not rechecked by the client. To remove events whose names contain cancelled or canceled, pass includeCancelled: false; that legacy name-based filter runs after all pages have been collected.

Resources

const events = await robot.events.search();
const event = await robot.events.get(eventId);
const eventBySku = await robot.events.getBySku("RE-VRC-26-1234");
const eventTeams = await robot.events.teams(eventId);
const eventSkills = await robot.events.skills(eventId);
const eventAwards = await robot.events.awards(eventId);
const divisionMatches = await robot.events.matches(eventId, divisionId);
const divisionRankings = await robot.events.rankings(eventId, divisionId);

const teams = await robot.teams.search();
const teamById = await robot.teams.get(teamId);
const teamByNumber = await robot.teams.getByNumber("123A", robot.programs.V5RC);
const teamEvents = await robot.teams.events(teamId);
const teamMatches = await robot.teams.matches(teamId);

const programs = await robot.programs.all();
const seasons = await robot.seasons.all({ programs: [robot.programs.V5RC] });

Constants and match helpers

import {
  getEventUrl,
  getMatchShortName,
  getTeamOutcome,
  programs,
  rounds,
} from "@v5x/events";

const program = await robot.programs.get(programs.V5RC);
const matches = await robot.events.matches(eventId, divisionId, {
  rounds: [rounds.qualification],
});

for (const match of matches) {
  console.log(getMatchShortName(match), getTeamOutcome(match, "123A"));
}

console.log(getEventUrl(events[0]!));

getTeamUrl, getAlliance, getMatchOutcome, and getMatchTeams provide additional helpers without wrapping API responses in classes.

Errors and retries

HTTP errors throw VexEventsApiError; invalid successful responses throw VexEventsResponseError. When a later page fails, the collection rejects without returning partial data.

const robot = new Robot({
  token: process.env.VEX_EVENTS_TOKEN!,
  retry: { maxAttempts: 3, maxDelayMs: 30_000 },
});

The retry option handles 429 responses and honors the same abort signal on every attempt and every page.

Migrating from 0.1

Page-oriented methods have been replaced by complete arrays:

0.1	0.2
`robot.events.list()`	`robot.events.search()`
`robot.teams.list()`	`robot.teams.search()`
`robot.programs.list()`	`robot.programs.all()`
`robot.seasons.list()`	`robot.seasons.all()`
`PaginatedResponse<T>`	`T[]`
`listPages()` / `matchesPages()`	Automatic internal pagination

page and perPage are no longer public filter options.

​Search complete collections

​Resources

​Constants and match helpers

​Errors and retries

​Migrating from 0.1

Search complete collections

Resources

Constants and match helpers

Errors and retries

Migrating from 0.1