Are Leaderboard Endpoints (getLeaderboardEntries, getGameLeaderboards, getUserGameLeaderboards) Supported in @retroachievements/api@2.4.0?

[CatoPaus]

Hi all,

I’m working on a Node.js project using @retroachievements/api@2.4.0 with TypeScript (nodenext, Node.js 22) and noticed that the leaderboard endpoints (getLeaderboardEntries, getGameLeaderboards, getUserGameLeaderboards) are not implemented in the JavaScript library, despite being documented and available in the RAWeb API. I’d like to clarify if this is intentional, a known limitation, or an oversight, and share a workaround for others who might encounter this.

Context

The RAWeb API includes three leaderboard endpoints, added in RAWeb PR #2564 (merged July 31, 2024, release 6.10.0):

• API_GetLeaderboardEntries.php (docs)
• API_GetGameLeaderboards.php (docs)
• API_GetUserGameLeaderboards.php (docs)

The main page (https://api-docs.retroachievements.org/) states that @retroachievements/api aligns 1:1 with the RAWeb API, suggesting these endpoints should be supported. However:

• dist/game/index.d.ts omits getLeaderboardEntries and getGameLeaderboards.
• dist/user/index.d.ts omits getUserGameLeaderboards.
• dist/api.modern.js lacks exports and logic for these functions, unlike others (e.g., getGame, getGameRankAndScore, getUserRecentlyPlayedGames, getUserSummary).

Attempting to import these (e.g., import { getLeaderboardEntries } from '@retroachievements/api/game') fails at compile-time unless a custom .d.ts declares them, then causes TypeError: getLeaderboardEntries is not a function at runtime.

Workaround

I implemented direct API calls using node-fetch to access the RAWeb endpoints, which work reliably in a Firebase Cloud Functions project. Example:

`import { Request, Response } from 'express';
import fetch from 'node-fetch';

async function fetchGameLeaderboards(req: Request, res: Response): Promise {
try {
const { gameId } = req.query;
if (!gameId || isNaN(Number(gameId))) {
res.status(400).json({ error: 'Invalid or missing gameId' });
return;
}
const username = process.env.RA_USERNAME!;
const webApiKey = process.env.RA_API_KEY!;
const url = new URL('https://retroachievements.org/API/API_GetGameLeaderboards.php');
url.searchParams.append('z', username);
url.searchParams.append('y', webApiKey);
url.searchParams.append('i', gameId.toString());
const response = await fetch(url.toString());
if (!response.ok) {
throw new Error(HTTP error! status: ${response.status});
}
const data = await response.json();
res.status(200).json(data);
} catch (error) {
console.error('Error in fetchGameLeaderboards:', error);
res.status(500).json({ error: 'Internal server error' });
}
}`

Similar functions for fetchLeaderboardEntries and fetchUserGameLeaderboards work by calling API_GetLeaderboardEntries.php and API_GetUserGameLeaderboards.php.

Questions

1. Are getLeaderboardEntries, getGameLeaderboards, and getUserGameLeaderboards intentionally omitted from @retroachievements/api@2.4.0, or is this an oversight since PR #2564?
2. Are there plans to add these endpoints in a future release (e.g., 2.4.1)?
3. Is the Kotlin library (api-kotlin:1.0.2) the preferred way to access leaderboard endpoints, or should the JavaScript library cover them?
4. Are there recommended alternatives to direct API calls for these endpoints?

Additional Notes

• Other endpoints (e.g., getGame, getGameRankAndScore, getUserRecentlyPlayedGames, getUserSummary) work as expected via the library.
• I applied a patch-package fix for subpath exports (achievement, game, user, etc.) and TypeScript TS2834 errors (missing .d.ts extensions in index.d.ts), which I can share if helpful.
• My project uses Firebase Cloud Functions, and the direct API calls are stable in the emulator and ready for production.

I’d appreciate any clarification from maintainers (e.g., @wescopeland) or the community on the library’s scope and plans for these endpoints. Happy to provide more details or test future updates!

References

• RAWeb PR #2564
• RetroAchievements API Documentation
• api-js Repository
• npm Package

[ioslife]

From my understanding, the api-js library needs to be manually updated to reflect changes made in RAWeb API.
The following issues have been raised, so they are planned:
#104
#112
#111
#113
#115

Being open source, anyone is able to make a PR and solve the issues :) I can't speak for when they are planned to be added to api-js.