lightleaderboard 1.0.0

package/README.md

@@ -0,0 +1,258 @@
+# lightleaderboard
+
+Official JavaScript / TypeScript SDK for [LightLeaderboard](https://leaderboard.goproso.com) — leaderboard-as-a-service for game developers.
+
+Works in **Node.js 18+**, **browsers**, and any runtime with the Web Crypto API and native `fetch` (Deno, Bun, Cloudflare Workers, etc.).
+
+---
+
+## Installation
+
+```bash
+npm install lightleaderboard
+# or
+yarn add lightleaderboard
+# or
+pnpm add lightleaderboard
+```
+
+---
+
+## Quick start
+
+```ts
+import { LightLeaderboard } from 'lightleaderboard';
+
+const lb = new LightLeaderboard({
+  apiKey: 'YOUR_API_KEY',   // from the LightLeaderboard dashboard
+  gameId: 'YOUR_GAME_ID',   // your game's reference ID
+});
+
+// Submit a score and get back the player's rank immediately
+const result = await lb.submitScore({
+  score: 9500,
+  playerRefId: 'player-123',
+  playerName: 'Alice',
+});
+console.log(`Rank #${result.rank} of ${result.totalPlayers}!`);
+// → "Rank #4 of 1024!"
+
+// Fetch the top 10
+const { entries } = await lb.getLeaderboard({ limit: 10 });
+entries.forEach(e => {
+  console.log(`#${e.rank}  ${e.playerName}  ${e.score}`);
+});
+```
+
+---
+
+## API reference
+
+### `new LightLeaderboard(config)`
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `apiKey` | `string` | ✓ | Your game's API key from the dashboard |
+| `gameId` | `string` | ✓ | Your game's reference ID |
+| `baseUrl` | `string` | | Override the API base URL |
+| `scoreSecret` | `string` | | Auto-sign scores with HMAC-SHA256 (see [Score signing](#score-signing)) |
+
+---
+
+### `submitScore(options)`
+
+Submit a score. Returns rank, personal-best flag, and total player count in a single call.
+
+```ts
+const result = await lb.submitScore({
+  score: 9500,
+  playerRefId: 'player-123',  // your internal player ID
+  playerName: 'Alice',         // display name
+  playTimeMs: 120_000,         // run duration
+  seasonId: 'season-3',        // optional season bucket
+  teamId: 'team-red',          // optional team bucket
+  submissionId: crypto.randomUUID(), // idempotency key
+  metadata: { level: 5, combo: 12 }, // arbitrary JSON
+});
+
+console.log(result.rank);          // 4       (player's current rank)
+console.log(result.isPersonalBest); // true
+console.log(result.totalPlayers);  // 1024
+console.log(result.deduped);       // true if submissionId was already seen
+```
+
+**Response fields**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `number` | Database ID of the created entry |
+| `rank` | `number \| null` | Player's rank right after submission (`null` if no `playerRefId`) |
+| `isPersonalBest` | `boolean` | Whether this beats the player's previous best |
+| `totalPlayers` | `number \| null` | Total unique players on this leaderboard |
+| `deduped` | `boolean?` | `true` when `submissionId` was already seen |
+
+---
+
+### `getLeaderboard(options?)`
+
+Fetch the leaderboard. Returns **one entry per player** (their best score) by default.
+
+```ts
+const { entries } = await lb.getLeaderboard({
+  limit: 20,        // 1–100, default 20
+  offset: 0,        // pagination
+  period: 'weekly', // 'all' | 'weekly' | 'monthly'
+  season: 'season-3',
+  team: 'team-red',
+  allEntries: false, // true → return every raw submission
+});
+
+// Each entry has a `rank` field (1-based, offset-aware)
+entries.forEach(e => console.log(e.rank, e.playerName, e.score));
+```
+
+**Pagination example**
+
+```ts
+// Page 2 of a weekly board
+const page2 = await lb.getLeaderboard({ limit: 20, offset: 20, period: 'weekly' });
+```
+
+---
+
+### `getPlayerRank(playerRefId, options?)`
+
+Get a player's rank, score, and **percentile** in a single call.
+
+```ts
+const rank = await lb.getPlayerRank('player-123', { period: 'weekly' });
+
+console.log(rank.rank);       // 4
+console.log(rank.score);      // 9500
+console.log(rank.totalPlayers); // 1024
+console.log(rank.percentile); // 99.7  → top 0.3%
+```
+
+`percentile` is 0–100, higher is better. `rank 1 of 100` → `percentile 100`.
+
+---
+
+### `getCentricLeaderboard(playerRefId, options?)`
+
+Fetch the leaderboard centered on a specific player — the entries immediately above and below them. Great for in-game "you vs. your neighbors" screens.
+
+```ts
+const { entries, playerRank } = await lb.getCentricLeaderboard('player-123', {
+  limit: 11, // 5 above + player + 5 below
+});
+```
+
+---
+
+### `getPlayer(playerRefId)`
+
+Fetch a player's profile.
+
+```ts
+const profile = await lb.getPlayer('player-123');
+console.log(profile.playerName, profile.avatarUrl, profile.country);
+```
+
+---
+
+### `updatePlayer(playerRefId, options)`
+
+Create or update a player's profile. Fields are merged — omitted fields keep their current value.
+
+```ts
+await lb.updatePlayer('player-123', {
+  playerName: 'Alice',
+  avatarUrl: 'https://example.com/avatar.png',
+  country: 'US',
+  level: 42,
+  device: 'mobile',
+});
+```
+
+---
+
+### `getPlayerScores(playerRefId, options?)`
+
+Fetch all submissions a player has made, ordered **newest first**. Useful for progression graphs and run-history screens.
+
+```ts
+const { entries, bestScore, total } = await lb.getPlayerScores('player-123', {
+  limit: 50,   // 1–200, default 50
+  offset: 0,
+});
+
+console.log(`${total} total runs, best: ${bestScore}`);
+entries.forEach(e => console.log(e.score, e.createdAt));
+```
+
+---
+
+## Score signing
+
+If you enable "Require signed scores" on your game in the dashboard, every submission must include a valid HMAC-SHA256 signature. Pass `scoreSecret` to the constructor and the SDK handles signing automatically:
+
+```ts
+const lb = new LightLeaderboard({
+  apiKey: 'YOUR_API_KEY',
+  gameId: 'YOUR_GAME_ID',
+  scoreSecret: 'YOUR_SCORE_SECRET', // from the dashboard → Signature Secret
+});
+
+// Scores are now automatically signed — no extra code needed
+await lb.submitScore({ score: 9500, playerRefId: 'p1' });
+```
+
+Signing uses the **Web Crypto API** (`crypto.subtle`), available natively in Node 18+, modern browsers, Bun, Deno, and Cloudflare Workers.
+
+---
+
+## Error handling
+
+All methods throw `LightLeaderboardError` on failure.
+
+```ts
+import { LightLeaderboard, LightLeaderboardError } from 'lightleaderboard';
+
+try {
+  await lb.submitScore({ score: 9500 });
+} catch (err) {
+  if (err instanceof LightLeaderboardError) {
+    console.error(err.message);   // human-readable message from the API
+    console.error(err.status);    // HTTP status code
+    console.error(err.response);  // raw response body
+
+    if (err.isAuthError)        console.error('Check your API key');
+    if (err.isRateLimitError)   console.error('Slow down score submissions');
+    if (err.isBillingError)     console.error('Free tier limit reached');
+    if (err.isValidationError)  console.error('Invalid score data');
+  }
+}
+```
+
+---
+
+## TypeScript
+
+The SDK is written in TypeScript and ships full type declarations. All options and return types are exported:
+
+```ts
+import type {
+  SubmitScoreOptions,
+  SubmitScoreResult,
+  GetLeaderboardOptions,
+  GetLeaderboardResult,
+  PlayerRankResult,
+  LeaderboardEntry,
+} from 'lightleaderboard';
+```
+
+---
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,260 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  LightLeaderboard: () => LightLeaderboard,
+  LightLeaderboardError: () => LightLeaderboardError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/error.ts
+var LightLeaderboardError = class extends Error {
+  constructor(message, status, response) {
+    super(message);
+    this.name = "LightLeaderboardError";
+    this.status = status;
+    this.response = response;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+  get isAuthError() {
+    return this.status === 401 || this.status === 403;
+  }
+  get isRateLimitError() {
+    return this.status === 429;
+  }
+  get isBillingError() {
+    return this.status === 402;
+  }
+  get isValidationError() {
+    return this.status === 400;
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://leaderboard.goproso.com";
+async function hmacSha256(key, data) {
+  const enc = new TextEncoder();
+  const cryptoKey = await globalThis.crypto.subtle.importKey(
+    "raw",
+    enc.encode(key),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const sig = await globalThis.crypto.subtle.sign("HMAC", cryptoKey, enc.encode(data));
+  return Array.from(new Uint8Array(sig)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function buildUrl(base, path, params) {
+  const url = `${base}${path}`;
+  if (!params) return url;
+  const sp = new URLSearchParams();
+  for (const [k, v] of Object.entries(params)) {
+    if (v !== void 0 && v !== null) sp.set(k, String(v));
+  }
+  const qs = sp.toString();
+  return qs ? `${url}?${qs}` : url;
+}
+var LightLeaderboard = class {
+  constructor(config) {
+    if (!config.apiKey) throw new Error("LightLeaderboard: apiKey is required");
+    if (!config.gameId) throw new Error("LightLeaderboard: gameId is required");
+    this.apiKey = config.apiKey;
+    this.gameId = config.gameId;
+    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.scoreSecret = config.scoreSecret;
+  }
+  gameUrl(path, params) {
+    return buildUrl(this.baseUrl, `/api/v1/games/${encodeURIComponent(this.gameId)}${path}`, params);
+  }
+  async fetch(method, url, body, extraHeaders) {
+    const headers = {
+      Authorization: `Bearer ${this.apiKey}`,
+      "Content-Type": "application/json",
+      ...extraHeaders
+    };
+    const res = await globalThis.fetch(url, {
+      method,
+      headers,
+      body: body !== void 0 ? JSON.stringify(body) : void 0
+    });
+    let data;
+    try {
+      data = await res.json();
+    } catch {
+      throw new LightLeaderboardError(`HTTP ${res.status}: failed to parse response`, res.status, null);
+    }
+    if (!res.ok || data?.ok === false) {
+      throw new LightLeaderboardError(
+        data?.error ?? `HTTP ${res.status}`,
+        res.status,
+        data
+      );
+    }
+    return data;
+  }
+  // ─── Score submission ───────────────────────────────────────────────────────
+  /**
+   * Submit a score to the leaderboard.
+   *
+   * Returns the player's new rank immediately — no second API call needed.
+   *
+   * @example
+   * const result = await lb.submitScore({ score: 9500, playerRefId: 'p1', playerName: 'Alice' });
+   * console.log(`Rank #${result.rank} of ${result.totalPlayers}`);
+   */
+  async submitScore(options) {
+    const url = this.gameUrl("/scores");
+    const bodyStr = JSON.stringify(options);
+    const extraHeaders = {};
+    if (this.scoreSecret) {
+      const sig = await hmacSha256(this.scoreSecret, bodyStr);
+      extraHeaders["x-score-signature"] = `sha256=${sig}`;
+    }
+    const res = await globalThis.fetch(url, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json",
+        ...extraHeaders
+      },
+      body: bodyStr
+    });
+    let data;
+    try {
+      data = await res.json();
+    } catch {
+      throw new LightLeaderboardError(`HTTP ${res.status}: failed to parse response`, res.status, null);
+    }
+    if (!res.ok || data?.ok === false) {
+      throw new LightLeaderboardError(data?.error ?? `HTTP ${res.status}`, res.status, data);
+    }
+    return {
+      id: data.id,
+      rank: data.rank ?? null,
+      isPersonalBest: data.isPersonalBest ?? false,
+      totalPlayers: data.totalPlayers ?? null,
+      deduped: data.deduped
+    };
+  }
+  // ─── Leaderboard ───────────────────────────────────────────────────────────
+  /**
+   * Fetch the leaderboard. Returns one entry per player (their best score) by default.
+   *
+   * @example
+   * const { entries } = await lb.getLeaderboard({ limit: 10, period: 'weekly' });
+   * entries.forEach(e => console.log(`#${e.rank} ${e.playerName}: ${e.score}`));
+   */
+  async getLeaderboard(options) {
+    const { allEntries, ...rest } = options ?? {};
+    const data = await this.fetch(
+      "GET",
+      this.gameUrl("/leaderboard", {
+        ...rest,
+        allEntries: allEntries ? "true" : void 0
+      })
+    );
+    return {
+      entries: data.entries,
+      scoreOrder: data.scoreOrder,
+      period: data.period,
+      season: data.season ?? null,
+      team: data.team ?? null,
+      limit: data.limit,
+      offset: data.offset
+    };
+  }
+  // ─── Rank ───────────────────────────────────────────────────────────────────
+  /**
+   * Get a player's current rank, score, and percentile.
+   *
+   * @example
+   * const { rank, percentile } = await lb.getPlayerRank('player-123');
+   * console.log(`Rank #${rank} — top ${(100 - percentile).toFixed(1)}%`);
+   */
+  async getPlayerRank(playerRefId, options) {
+    return this.fetch(
+      "GET",
+      this.gameUrl(`/players/${encodeURIComponent(playerRefId)}/rank`, options)
+    );
+  }
+  // ─── Centric leaderboard ───────────────────────────────────────────────────
+  /**
+   * Fetch the leaderboard centered on a specific player, showing the players
+   * immediately above and below them.
+   *
+   * @example
+   * const { entries, playerRank } = await lb.getCentricLeaderboard('player-123', { limit: 11 });
+   */
+  async getCentricLeaderboard(playerRefId, options) {
+    const data = await this.fetch(
+      "GET",
+      this.gameUrl(`/players/${encodeURIComponent(playerRefId)}/centric`, options)
+    );
+    return {
+      entries: data.entries,
+      playerRank: data.playerRank ?? null,
+      period: data.period,
+      season: data.season ?? null,
+      team: data.team ?? null,
+      scoreOrder: data.scoreOrder
+    };
+  }
+  // ─── Player profile ─────────────────────────────────────────────────────────
+  /**
+   * Fetch a player's profile (name, avatar, country, level, etc.).
+   */
+  async getPlayer(playerRefId) {
+    const data = await this.fetch(
+      "GET",
+      this.gameUrl(`/players/${encodeURIComponent(playerRefId)}`)
+    );
+    return data.player;
+  }
+  /**
+   * Create or update a player's profile. Fields are merged — omitted fields
+   * keep their existing values.
+   *
+   * @example
+   * await lb.updatePlayer('player-123', { playerName: 'Alice', country: 'US', level: 5 });
+   */
+  async updatePlayer(playerRefId, options) {
+    await this.fetch(
+      "PUT",
+      this.gameUrl(`/players/${encodeURIComponent(playerRefId)}`),
+      options
+    );
+  }
+  // ─── Score history ──────────────────────────────────────────────────────────
+  /**
+   * Fetch all submissions a player has ever made, ordered newest first.
+   * Useful for progression charts and run history screens.
+   *
+   * @example
+   * const { entries, bestScore, total } = await lb.getPlayerScores('player-123');
+   */
+  async getPlayerScores(playerRefId, options) {
+    return this.fetch(
+      "GET",
+      this.gameUrl(`/players/${encodeURIComponent(playerRefId)}/scores`, options)
+    );
+  }
+};
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/error.ts","../src/client.ts"],"sourcesContent":["export { LightLeaderboard } from './client.js';\nexport { LightLeaderboardError } from './error.js';\nexport type {\n  LightLeaderboardConfig,\n  LeaderboardEntry,\n  GetLeaderboardOptions,\n  GetLeaderboardResult,\n  SubmitScoreOptions,\n  SubmitScoreResult,\n  GetRankOptions,\n  PlayerRankResult,\n  GetCentricOptions,\n  CentricLeaderboardResult,\n  PlayerProfile,\n  UpdatePlayerOptions,\n  PlayerScoreEntry,\n  GetPlayerScoresOptions,\n  GetPlayerScoresResult,\n} from './types.js';\n","export class LightLeaderboardError extends Error {\n  /** HTTP status code returned by the API */\n  readonly status: number;\n  /** Raw response body from the API */\n  readonly response: unknown;\n\n  constructor(message: string, status: number, response: unknown) {\n    super(message);\n    this.name = 'LightLeaderboardError';\n    this.status = status;\n    this.response = response;\n    // Restore prototype chain in environments that need it\n    Object.setPrototypeOf(this, new.target.prototype);\n  }\n\n  get isAuthError() {\n    return this.status === 401 || this.status === 403;\n  }\n\n  get isRateLimitError() {\n    return this.status === 429;\n  }\n\n  get isBillingError() {\n    return this.status === 402;\n  }\n\n  get isValidationError() {\n    return this.status === 400;\n  }\n}\n","import { LightLeaderboardError } from './error.js';\nimport type {\n  LightLeaderboardConfig,\n  SubmitScoreOptions,\n  SubmitScoreResult,\n  GetLeaderboardOptions,\n  GetLeaderboardResult,\n  GetRankOptions,\n  PlayerRankResult,\n  GetCentricOptions,\n  CentricLeaderboardResult,\n  PlayerProfile,\n  UpdatePlayerOptions,\n  GetPlayerScoresOptions,\n  GetPlayerScoresResult,\n} from './types.js';\n\nconst DEFAULT_BASE_URL = 'https://leaderboard.goproso.com';\n\nasync function hmacSha256(key: string, data: string): Promise<string> {\n  const enc = new TextEncoder();\n  const cryptoKey = await globalThis.crypto.subtle.importKey(\n    'raw',\n    enc.encode(key),\n    { name: 'HMAC', hash: 'SHA-256' },\n    false,\n    ['sign']\n  );\n  const sig = await globalThis.crypto.subtle.sign('HMAC', cryptoKey, enc.encode(data));\n  return Array.from(new Uint8Array(sig))\n    .map((b) => b.toString(16).padStart(2, '0'))\n    .join('');\n}\n\nfunction buildUrl(base: string, path: string, params?: object): string {\n  const url = `${base}${path}`;\n  if (!params) return url;\n  const sp = new URLSearchParams();\n  for (const [k, v] of Object.entries(params)) {\n    if (v !== undefined && v !== null) sp.set(k, String(v));\n  }\n  const qs = sp.toString();\n  return qs ? `${url}?${qs}` : url;\n}\n\nexport class LightLeaderboard {\n  private readonly apiKey: string;\n  private readonly gameId: string;\n  private readonly baseUrl: string;\n  private readonly scoreSecret?: string;\n\n  constructor(config: LightLeaderboardConfig) {\n    if (!config.apiKey) throw new Error('LightLeaderboard: apiKey is required');\n    if (!config.gameId) throw new Error('LightLeaderboard: gameId is required');\n    this.apiKey = config.apiKey;\n    this.gameId = config.gameId;\n    this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\\/$/, '');\n    this.scoreSecret = config.scoreSecret;\n  }\n\n  private gameUrl(path: string, params?: object): string {\n    return buildUrl(this.baseUrl, `/api/v1/games/${encodeURIComponent(this.gameId)}${path}`, params);\n  }\n\n  private async fetch<T>(\n    method: string,\n    url: string,\n    body?: unknown,\n    extraHeaders?: Record<string, string>\n  ): Promise<T> {\n    const headers: Record<string, string> = {\n      Authorization: `Bearer ${this.apiKey}`,\n      'Content-Type': 'application/json',\n      ...extraHeaders,\n    };\n\n    const res = await globalThis.fetch(url, {\n      method,\n      headers,\n      body: body !== undefined ? JSON.stringify(body) : undefined,\n    });\n\n    let data: any;\n    try {\n      data = await res.json();\n    } catch {\n      throw new LightLeaderboardError(`HTTP ${res.status}: failed to parse response`, res.status, null);\n    }\n\n    if (!res.ok || data?.ok === false) {\n      throw new LightLeaderboardError(\n        data?.error ?? `HTTP ${res.status}`,\n        res.status,\n        data\n      );\n    }\n\n    return data as T;\n  }\n\n  // ─── Score submission ───────────────────────────────────────────────────────\n\n  /**\n   * Submit a score to the leaderboard.\n   *\n   * Returns the player's new rank immediately — no second API call needed.\n   *\n   * @example\n   * const result = await lb.submitScore({ score: 9500, playerRefId: 'p1', playerName: 'Alice' });\n   * console.log(`Rank #${result.rank} of ${result.totalPlayers}`);\n   */\n  async submitScore(options: SubmitScoreOptions): Promise<SubmitScoreResult> {\n    const url = this.gameUrl('/scores');\n    const bodyStr = JSON.stringify(options);\n    const extraHeaders: Record<string, string> = {};\n\n    if (this.scoreSecret) {\n      const sig = await hmacSha256(this.scoreSecret, bodyStr);\n      extraHeaders['x-score-signature'] = `sha256=${sig}`;\n    }\n\n    const res = await globalThis.fetch(url, {\n      method: 'POST',\n      headers: {\n        Authorization: `Bearer ${this.apiKey}`,\n        'Content-Type': 'application/json',\n        ...extraHeaders,\n      },\n      body: bodyStr,\n    });\n\n    let data: any;\n    try {\n      data = await res.json();\n    } catch {\n      throw new LightLeaderboardError(`HTTP ${res.status}: failed to parse response`, res.status, null);\n    }\n\n    if (!res.ok || data?.ok === false) {\n      throw new LightLeaderboardError(data?.error ?? `HTTP ${res.status}`, res.status, data);\n    }\n\n    return {\n      id: data.id,\n      rank: data.rank ?? null,\n      isPersonalBest: data.isPersonalBest ?? false,\n      totalPlayers: data.totalPlayers ?? null,\n      deduped: data.deduped,\n    };\n  }\n\n  // ─── Leaderboard ───────────────────────────────────────────────────────────\n\n  /**\n   * Fetch the leaderboard. Returns one entry per player (their best score) by default.\n   *\n   * @example\n   * const { entries } = await lb.getLeaderboard({ limit: 10, period: 'weekly' });\n   * entries.forEach(e => console.log(`#${e.rank} ${e.playerName}: ${e.score}`));\n   */\n  async getLeaderboard(options?: GetLeaderboardOptions): Promise<GetLeaderboardResult> {\n    const { allEntries, ...rest } = options ?? {};\n    const data = await this.fetch<any>(\n      'GET',\n      this.gameUrl('/leaderboard', {\n        ...rest,\n        allEntries: allEntries ? 'true' : undefined,\n      })\n    );\n    return {\n      entries: data.entries,\n      scoreOrder: data.scoreOrder,\n      period: data.period,\n      season: data.season ?? null,\n      team: data.team ?? null,\n      limit: data.limit,\n      offset: data.offset,\n    };\n  }\n\n  // ─── Rank ───────────────────────────────────────────────────────────────────\n\n  /**\n   * Get a player's current rank, score, and percentile.\n   *\n   * @example\n   * const { rank, percentile } = await lb.getPlayerRank('player-123');\n   * console.log(`Rank #${rank} — top ${(100 - percentile).toFixed(1)}%`);\n   */\n  async getPlayerRank(playerRefId: string, options?: GetRankOptions): Promise<PlayerRankResult> {\n    return this.fetch<PlayerRankResult>(\n      'GET',\n      this.gameUrl(`/players/${encodeURIComponent(playerRefId)}/rank`, options)\n    );\n  }\n\n  // ─── Centric leaderboard ───────────────────────────────────────────────────\n\n  /**\n   * Fetch the leaderboard centered on a specific player, showing the players\n   * immediately above and below them.\n   *\n   * @example\n   * const { entries, playerRank } = await lb.getCentricLeaderboard('player-123', { limit: 11 });\n   */\n  async getCentricLeaderboard(\n    playerRefId: string,\n    options?: GetCentricOptions\n  ): Promise<CentricLeaderboardResult> {\n    const data = await this.fetch<any>(\n      'GET',\n      this.gameUrl(`/players/${encodeURIComponent(playerRefId)}/centric`, options)\n    );\n    return {\n      entries: data.entries,\n      playerRank: data.playerRank ?? null,\n      period: data.period,\n      season: data.season ?? null,\n      team: data.team ?? null,\n      scoreOrder: data.scoreOrder,\n    };\n  }\n\n  // ─── Player profile ─────────────────────────────────────────────────────────\n\n  /**\n   * Fetch a player's profile (name, avatar, country, level, etc.).\n   */\n  async getPlayer(playerRefId: string): Promise<PlayerProfile> {\n    const data = await this.fetch<any>(\n      'GET',\n      this.gameUrl(`/players/${encodeURIComponent(playerRefId)}`)\n    );\n    return data.player as PlayerProfile;\n  }\n\n  /**\n   * Create or update a player's profile. Fields are merged — omitted fields\n   * keep their existing values.\n   *\n   * @example\n   * await lb.updatePlayer('player-123', { playerName: 'Alice', country: 'US', level: 5 });\n   */\n  async updatePlayer(playerRefId: string, options: UpdatePlayerOptions): Promise<void> {\n    await this.fetch<any>(\n      'PUT',\n      this.gameUrl(`/players/${encodeURIComponent(playerRefId)}`),\n      options\n    );\n  }\n\n  // ─── Score history ──────────────────────────────────────────────────────────\n\n  /**\n   * Fetch all submissions a player has ever made, ordered newest first.\n   * Useful for progression charts and run history screens.\n   *\n   * @example\n   * const { entries, bestScore, total } = await lb.getPlayerScores('player-123');\n   */\n  async getPlayerScores(\n    playerRefId: string,\n    options?: GetPlayerScoresOptions\n  ): Promise<GetPlayerScoresResult> {\n    return this.fetch<GetPlayerScoresResult>(\n      'GET',\n      this.gameUrl(`/players/${encodeURIComponent(playerRefId)}/scores`, options)\n    );\n  }\n}\n"],"mappings":"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","names":[]}