# Leaderboards — `client.leaderboards`

`LeaderboardsService` (source: `src/leaderboards/LeaderboardsService.ts`).
Plain call-and-response service, NOT observable — refetch explicitly.

## Surface

```ts
const board = client.leaderboards.findBySlug('weekly-kills'); // cached handle
await board.submit(score);
const entries = await board.list(limit?);
board.getEntries();
```

## `LeaderboardHandle`

```ts
class LeaderboardHandle {
  readonly slug: string;

  getEntries(): readonly RankEntry[];             // last fetched list, [] initially
  submit(score: number): Promise<void>;
  list(limit = 100): Promise<readonly RankEntry[]>; // fetches and caches
}
```

- `findBySlug(slug)` caches handles per slug — repeated calls return the same
  instance (and its cached entries).
- `list(limit)`: `limit <= 0` sends no limit to the server; default is 100.
- `submit` does not update the cached entries; call `list()` afterwards to see
  the effect.

## Types

```ts
interface RankEntry {
  playerId?: string;
  playerName?: string;
  rank?: number;
  score?: number;
}
```

## Notes

- No player-around-me or metadata endpoints are exposed by this SDK — submit
  and top-N list only.
- Scenario `leaderboard` nodes surface through
  `client.effects.onLeaderboard` (`end()`, `rewardClaimed()`) — see
  `reference/scenarios.md`.