An open-source TypeScript library to interact with the FIRST APIs.
- Fully typed API client for FIRST Tech Challenge (FTC) API
- Support for all FTC API endpoints
- Easy authentication with token generation
- Season selection with enum support
- Comprehensive error handling and input validation
import { FirstFTCAPI, createToken, Season } from 'first';
// Create an authentication token
const token = createToken('your_username', 'your_key');
// Create a client for the current season
const client = new FirstFTCAPI(token);
// Or specify a different season
const client2023 = new FirstFTCAPI(token, Season.CenterStage);async function getApiInfo() {
try {
const info = await client.getIndex();
console.log(`API Version: ${info.apiVersion}`);
console.log(`Current Season: ${info.currentSeason}`);
} catch (error) {
console.error('Error:', error.message);
}
}// Get all teams
const allTeams = await client.getTeams();
// Get a specific team
const team = await client.getTeams({ teamNumber: 12345 });
// Get teams from a specific state
const stateTeams = await client.getTeams({ state: 'CA' });
// Get teams attending a specific event
const eventTeams = await client.getTeams({ eventCode: 'USACMP' });// Get all events
const allEvents = await client.getEvents();
// Get a specific event
const event = await client.getEvents({ eventCode: 'USACMP' });
// Get events for a specific team
const teamEvents = await client.getEvents({ teamNumber: 12345 });// Get all matches for an event
const matches = await client.getMatches('USACMP');
// Get matches with specific filters
const qualificationMatches = await client.getMatches('USACMP', {
tournamentLevel: 'qual'
});
// Get matches for a specific team
const teamMatches = await client.getMatches('USACMP', {
teamNumber: 12345
});The library currently supports the following FTC API endpoints:
getIndex()- Get API informationgetTeams(options?)- Get team listingsgetEvents(options?)- Get event listingsgetMatches(eventCode, options?)- Get match resultsgetRankings(eventCode, options?)- Get rankingsgetSeasonSummary()- Get season summarygetAwardListings()- Get award listingsgetAwards(options)- Get awards for events or teamsgetAlliances(eventCode)- Get alliance informationgetAllianceSelections(eventCode)- Get alliance selection detailsgetScores(eventCode, tournamentLevel, options?)- Get score detailsgetSchedule(eventCode, options)- Get event schedulegetHybridSchedule(eventCode, tournamentLevel, options?)- Get hybrid schedule
The library includes an enum for easy season selection:
enum Season {
SkyStone = 2019,
UltimateGoal = 2020,
FreightFrenzy = 2021,
PowerPlay = 2022,
CenterStage = 2023,
IntoTheDeep = 2024
}To use this library, you need to have valid FIRST API credentials. You can create a token using:
import { createToken } from 'first';
const token = createToken('username', 'key');For testing, create a .env file in your test directory with:
TOKEN=username:key
- FRC (FIRST Robotics Competition) API support coming soon
- Extended documentation and examples
- Additional utility functions for common operations
Contributions are welcome! Please feel free to submit a Pull Request.
This project is licensed under the ISC License - see the LICENSE.md file for details.