@sptiming/rr-webapi

TypeScript/Node.js client library for the RaceResult Web API.

Features

• 🚀 Full TypeScript support with comprehensive type definitions
• 🔄 Promise-based API using async/await
• 📦 Modular design with organized endpoints
• 🛡️ Type-safe request and response handling
• 🔧 Configurable HTTP client with custom options

Development Timeline

First Release: 2025 - Initial TypeScript/Node.js client implementation
Key Innovations:

• Modular endpoint architecture for RaceResult API integration
• Type-safe request/response handling with comprehensive TypeScript definitions
• Promise-based async/await pattern for timing data access
• Configurable HTTP client with custom authentication flows

This software represents original work by SPTiming team, first publicly released in 2025.

Installation

npm install @sptiming/rr-webapi
# or
yarn add @sptiming/rr-webapi

Quick Start

Environment Setup

Create a .env file with your credentials:

RACERESULT_API_KEY=your_api_key_here
RACERESULT_API_URL=events.raceresult.com

Basic Usage

import { RaceResultApi } from '@sptiming/rr-webapi';

async function example() {
  // Create API client
  const api = new RaceResultApi({
    server: 'events.raceresult.com',
    https: true,
    userAgent: 'my-app/1.0'
  });

  try {
    // Login with API key
    await api.public().login({ apiKey: 'your-api-key' });

    // Get your events
    const events = await api.public().eventList();
    console.log(`You have ${events.length} events`);

    // Open an event
    if (events.length > 0) {
      const eventApi = api.eventApi(events[0].id);
      
      // Get participants
      const count = await eventApi.data().count();
      console.log(`Event has ${count} participants`);

      // Get participant by bib number
      const participant = await eventApi.data().getParticipantByBib(1);
      if (participant) {
        const [pid, bib, firstName, lastName, contest] = participant;
        console.log(`Found: ${firstName} ${lastName} (Bib: ${bib})`);

        // Get raw timing data
        const rawData = await eventApi.rawData().getByPid(pid);
        console.log(`Participant has ${rawData.length} timing entries`);
      }
    }

  } finally {
    // Always logout
    await api.public().logout();
  }
}

API Reference

Main Classes

RaceResultApi

Main API client class.

const api = new RaceResultApi({
  server: 'events.raceresult.com',
  https: true,
  userAgent: 'my-app/1.0',
  timeout: 30000
});

PublicApi

Authentication and account operations.

const publicApi = api.public();

// Login methods
await publicApi.login({ apiKey: 'key' });
await publicApi.login({ username: 'user', password: 'pass' });

// Get user info
const userInfo = await publicApi.userInfo();

// Get events
const events = await publicApi.eventList();

// Logout
await publicApi.logout();

EventApi

Event-specific operations.

const eventApi = api.eventApi('event-id');

// Data operations
const dataApi = eventApi.data();
const count = await dataApi.count();
const participants = await dataApi.getParticipants();

// Raw data operations
const rawDataApi = eventApi.rawData();
const rawData = await rawDataApi.getByPid(participantId);

Type Definitions

interface ApiConfig {
  server: string;
  https?: boolean;
  userAgent?: string;
  timeout?: number;
}

interface LoginCredentials {
  apiKey?: string;
  username?: string;
  password?: string;
}

interface EventListItem {
  id: string;
  event_name: string;
  event_date: Date | null;
  participants?: number;
}

interface RawDataEntry {
  Time: string;
  TimingPoint: string;
}

Development

Setup

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run linting
npm run lint

# Format code
npm run format

Scripts

• npm run build - Compile TypeScript to JavaScript
• npm run build:watch - Watch mode compilation
• npm run test - Run Jest tests
• `