Developer API/TypeScript SDK

TypeScript SDK

Use the typed Strave client and reconnecting realtime gateway.

The official SDK exposes every API v1 endpoint, adds the authorization header, and validates responses.

bun add @strave/sdk

Create a client

import { Strave } from "@strave/sdk";

const strave = new Strave({
	apiKey: process.env.STRAVE_API_KEY!,
});

The base URL defaults to https://api.strave.gg/v1.

Read event data

const { data: events } = await strave.events.list();
const event = events[0];

if (event) {
	const [{ data: matches }, { data: standings }] = await Promise.all([
		strave.events.matches(event.id),
		strave.events.standings(event.id),
	]);
}

Detail methods mirror the REST route names:

await strave.events.retrieve(eventId);
await strave.events.stage(eventId, stageId);
await strave.events.group(eventId, groupId);
await strave.events.round(eventId, roundId);
await strave.events.participant(eventId, participantId);
await strave.events.match(eventId, matchId);
await strave.events.invitation(eventId, invitationId);
await strave.events.playday(eventId, playdayId);

Failures reject with StraveApiError, including a stable code, an HTTP status, and a safe message.

import { StraveApiError } from "@strave/sdk";

try {
	const { data: event } = await strave.events.retrieve(eventId);
} catch (error) {
	if (error instanceof StraveApiError) {
		console.error(error.code, error.status, error.message);
	}
}

Subscribe to changes

const gateway = strave.gateway({
	topics: ["match.*", "event.*"],
});

gateway.on("match", async (match) => {
	const { data } = await match.retrieve();
	// Update your cache with the fresh match.
});

gateway.connect();

The SDK stores the latest sequence in memory, sends heartbeats, reconnects, and resumes after temporary disconnects. Call gateway.close() during shutdown.

gateway.on() narrows the resource and exposes its IDs plus a bound retrieve() method. Supported resources include event, stage, group, participant, match, invitation, user, and organisation. Use gateway.onEvent() when you need the raw invalidation envelope.