raceresult-webapi

Typed Node.js client for the RACE RESULT 14 Web API. It covers the same endpoints as the official Go client raceresult/go-webapi: the account endpoints, the general endpoints, all 43 endpoint groups of an event, multiRequest and raw get/post.

• Native fetch, no HTTP library.
• Every JSON answer is validated with ArkType before it reaches your code.
• Models keep the JSON field names of the server (Name, ListName, AgeStart), so a read, change and save cycle sends back exactly what the server sent, including fields that this package does not know yet.

Use at your own risk. RACE RESULT offers the Web API without support (knowledge base). An API key grants access to all events of the account; keep it out of source control.

Installation

npm install raceresult-webapi

Node.js 24 or later. The package is ESM only.

Usage

import { RaceResultClient } from 'raceresult-webapi';

const client = new RaceResultClient();
await client.account.login({ apiKey: process.env.RACERESULT_API_KEY });
try {
  const events = await client.account.eventList();
  for (const event of events) {
    console.log(event.ID, event.EventName, event.EventDate);
  }

  const contests = await client.event('165435').contests.get();
  console.log(contests.map((contest) => contest.Name));
} finally {
  await client.account.logout();
}

client.event(eventId) returns the endpoint groups of one event (contests, participants, data, rawData, lists, …). All of them share the session of the client.

Options

| Option | Default | Meaning | |---|---|---| | server | events.raceresult.com | Host name, optionally with a port, for example a local RACE RESULT 14 server. | | isHttps | true | false for a local server without TLS. | | userAgent | raceresult-webapi | Value of the User-Agent header. | | timeoutMs | 30000 | Deadline of one request, including the body. | | fetch | globalThis.fetch | Another fetch implementation, for example for tests. | | sessionId | '0' | Resumes a stored session without a login. Read the current value from client.sessionId. |

Participants and identifiers

Endpoints that address one participant take an Identifier. Create it with bib() or pid():

import { bib, pid } from 'raceresult-webapi';

const api = client.event('165435');
await api.participants.saveFields({ identifier: bib(12000), values: { FirstName: 'Mark' } });
await api.rawData.copy({ from: pid(17), to: pid(18) });

Errors

| Class | When | |---|---| | RaceResultApiError | The server answered with a status other than 200. message is the error text of the server, status the HTTP status. | | RaceResultNetworkError | No complete answer arrived. isTimeout is true when the deadline expired. | | ValidationError (@datenknoten/kit) | An answer did not match its schema, or login got no credentials. | | NotFoundError (@datenknoten/kit) | exporters.getOne or teamScores.getOne found no item. |

Error details carry the method and the path of the request, never the query string, because queries can hold names and filters.

Differences to go-webapi

| go-webapi | raceresult-webapi | Reason | |---|---|---| | api.Public() | client.account | public is a TypeScript modifier. | | New(...) | add(...) | new reads like a constructor. | | Settings().GetValue(name) | settings.findValue(name) | Returns undefined when the setting is missing. | | Two or more parameters | One parameter object | contests.save({ item, oldId }); optional fields default to the Go zero value. | | Acronyms (PDF, PreviewJPG, SESVersion) | One word (pdf, previewJpg, sesVersion) | TypeScript naming. | | Logout() keeps the session ID | logout() resets it to '0' | client.sessionId names the real state. | | EmailTemplates().Save(*label.Label) | emailTemplates.save(EmailTemplate) | The Go signature is a bug. | | Empty slice answered as null | [] | Lists are always arrays. |

License

MIT