keeperboard 1.0.2 → 1.0.3

package/README.md

@@ -1,6 +1,6 @@
 # KeeperBoard SDK
 
-TypeScript client SDK for [KeeperBoard](https://github.com/YOUR_USERNAME/keeperboard) — a free, open-source leaderboard-as-a-service for indie game developers.
+TypeScript client SDK for [KeeperBoard](https://github.com/clauderoy790/keeperboard) — a free, open-source leaderboard-as-a-service for indie game developers.
 
 Works with Phaser.js, vanilla JavaScript, and any TypeScript/JavaScript game running in the browser.
 
@@ -24,7 +24,8 @@ import { KeeperBoardClient, PlayerIdentity } from './keeperboard/index';
 
 1. Sign up at your KeeperBoard dashboard
 2. Create a game
-3. Generate an API key for your environment (dev/prod)
+3. Create an environment (dev/prod)
+4. Generate an API key for that environment
 
 ### 2. Initialize the client
 
@@ -32,23 +33,22 @@ import { KeeperBoardClient, PlayerIdentity } from './keeperboard/index';
 import { KeeperBoardClient, PlayerIdentity } from 'keeperboard-sdk';
 
 // Create the API client
-const keeperboard = new KeeperBoardClient({
+const client = new KeeperBoardClient({
   apiUrl: 'https://keeperboard.vercel.app',
-  apiKey: 'kb_dev_your_api_key_here',
+  apiKey: 'kb_prod_your_api_key_here',
 });
 
 // Helper for persistent player identity
-const playerIdentity = new PlayerIdentity();
+const identity = new PlayerIdentity();
 ```
 
 ### 3. Submit a score
 
 ```typescript
-// Get or create a persistent player GUID
-const playerGuid = playerIdentity.getOrCreatePlayerGuid();
+const playerGuid = identity.getOrCreatePlayerGuid();
 
-// Submit a score (only updates if higher than existing)
-const result = await keeperboard.submitScore(playerGuid, 'PlayerName', 1500);
+// Submit to default leaderboard
+const result = await client.submitScore(playerGuid, 'PlayerName', 1500);
 
 console.log(`Rank: #${result.rank}`);
 console.log(`New high score: ${result.is_new_high_score}`);
@@ -57,13 +57,24 @@ console.log(`New high score: ${result.is_new_high_score}`);
 ### 4. Display the leaderboard
 
 ```typescript
-const leaderboard = await keeperboard.getLeaderboard(10);
+// Get top 10
+const leaderboard = await client.getLeaderboard();
 
 leaderboard.entries.forEach((entry) => {
   console.log(`#${entry.rank} ${entry.player_name}: ${entry.score}`);
 });
 ```
 
+### 5. Show player's rank (even if not in top 10)
+
+```typescript
+const player = await client.getPlayerRank(playerGuid);
+
+if (player && player.rank > 10) {
+  console.log(`You are ranked #${player.rank} with ${player.score} points`);
+}
+```
+
 ## API Reference
 
 ### KeeperBoardClient
@@ -72,97 +83,159 @@ leaderboard.entries.forEach((entry) => {
 
 ```typescript
 const client = new KeeperBoardClient({
-  apiUrl: string, // Your KeeperBoard API URL
-  apiKey: string, // API key from dashboard (e.g., "kb_dev_...")
+  apiUrl: string,  // Your KeeperBoard API URL
+  apiKey: string,  // API key from dashboard
 });
 ```
 
-#### Methods
+> **Note:** The API key determines which game and environment you're accessing. You don't need to pass environment or game IDs — they're implicit in the key.
+
+---
 
-##### `submitScore(playerGuid, playerName, score, metadata?, leaderboardSlug?)`
+### Score Submission
 
-Submit a score. Only updates if the new score is higher than the existing one.
+#### `submitScore(playerGuid, playerName, score)`
+
+Submit a score to the default leaderboard. Only updates if higher than existing score.
 
 ```typescript
-const result = await client.submitScore(
-  'player-uuid-123',
+const result = await client.submitScore('player-uuid', 'PlayerName', 2500);
+// Returns: { id, player_guid, player_name, score, rank, is_new_high_score }
+```
+
+#### `submitScore(playerGuid, playerName, score, leaderboard)`
+
+Submit to a specific leaderboard by name.
+
+```typescript
+await client.submitScore('player-uuid', 'PlayerName', 2500, 'Weekly Best');
+```
+
+#### `submitScore(playerGuid, playerName, score, leaderboard, metadata)`
+
+Submit with optional metadata.
+
+```typescript
+await client.submitScore(
+  'player-uuid',
   'PlayerName',
   2500,
-  { level: 10, character: 'warrior' }, // optional metadata
-  'high-scores', // optional leaderboard slug
+  'Weekly Best',
+  { level: 10, character: 'warrior' }
 );
+```
 
-// Returns:
-// {
-//   id: string,
-//   player_guid: string,
-//   player_name: string,
-//   score: number,
-//   rank: number,
-//   is_new_high_score: boolean
-// }
+---
+
+### Leaderboard
+
+#### `getLeaderboard()`
+
+Get the default leaderboard (top 10 entries).
+
+```typescript
+const lb = await client.getLeaderboard();
+// Returns: { entries, total_count, reset_schedule }
 ```
 
-##### `getLeaderboard(limit?, offset?, leaderboardSlug?)`
+#### `getLeaderboard(name)`
 
-Get leaderboard entries with pagination.
+Get a specific leaderboard by name.
 
 ```typescript
-const result = await client.getLeaderboard(
-  25, // limit (max 100)
-  0, // offset
-  'high-scores', // optional leaderboard slug
-);
+const lb = await client.getLeaderboard('Weekly Best');
+```
+
+#### `getLeaderboard(name, limit)`
+
+Get with a custom limit (max 100).
+
+```typescript
+const lb = await client.getLeaderboard('Weekly Best', 50);
+```
+
+#### `getLeaderboard(name, limit, offset)`
+
+Get with pagination.
+
+```typescript
+// Page 2 (entries 11-20)
+const lb = await client.getLeaderboard('Weekly Best', 10, 10);
+```
+
+---
+
+### Leaderboard Versions (Time-Based)
 
-// Returns:
-// {
-//   entries: [{ rank, player_guid, player_name, score }],
-//   total_count: number
-// }
+For leaderboards with reset schedules (daily/weekly/monthly), you can query historical versions.
+
+#### `getLeaderboardVersion(name, version)`
+
+Get a specific version of a time-based leaderboard.
+
+```typescript
+// Get last week's scores (version 3)
+const lastWeek = await client.getLeaderboardVersion('Weekly Best', 3);
 ```
 
-##### `getPlayer(playerGuid, leaderboardSlug?)`
+#### `getLeaderboardVersion(name, version, limit, offset)`
 
-Get a player's score and rank. Returns `null` if not found.
+Get historical version with pagination.
 
 ```typescript
-const player = await client.getPlayer('player-uuid-123');
+const lb = await client.getLeaderboardVersion('Weekly Best', 3, 25, 0);
+```
+
+---
+
+### Player
+
+#### `getPlayerRank(playerGuid)`
+
+Get a player's rank and score. Returns `null` if player has no score.
+
+```typescript
+const player = await client.getPlayerRank('player-uuid');
 
 if (player) {
-  console.log(`Score: ${player.score}, Rank: #${player.rank}`);
+  console.log(`Rank: #${player.rank}, Score: ${player.score}`);
 }
 ```
 
-##### `updatePlayerName(playerGuid, newName, leaderboardSlug?)`
+#### `getPlayerRank(playerGuid, leaderboard)`
+
+Get player's rank on a specific leaderboard.
+
+```typescript
+const player = await client.getPlayerRank('player-uuid', 'Weekly Best');
+```
+
+#### `updatePlayerName(playerGuid, newName)`
 
 Update a player's display name.
 
 ```typescript
-const result = await client.updatePlayerName(
-  'player-uuid-123',
-  'NewPlayerName',
-);
+await client.updatePlayerName('player-uuid', 'NewPlayerName');
 ```
 
-##### `claimScore(playerGuid, playerName, leaderboardSlug?)`
+---
+
+### Claim (for migrated scores)
+
+#### `claimScore(playerGuid, playerName)`
 
 Claim a migrated score by matching player name. Used when scores were imported without player GUIDs.
 
 ```typescript
-try {
-  const result = await client.claimScore(
-    'new-player-guid',
-    'ImportedPlayerName',
-  );
-  console.log(`Claimed score: ${result.score}`);
-} catch (error) {
-  if (error.code === 'NOT_FOUND') {
-    console.log('No unclaimed score found');
-  }
-}
+const result = await client.claimScore('new-player-guid', 'ImportedPlayerName');
+console.log(`Claimed score: ${result.score}, Rank: #${result.rank}`);
 ```
 
-##### `healthCheck()`
+---
+
+### Health Check
+
+#### `healthCheck()`
 
 Check if the API is healthy. Does not require an API key.
 
@@ -171,6 +244,8 @@ const health = await client.healthCheck();
 console.log(`API Version: ${health.version}`);
 ```
 
+---
+
 ### PlayerIdentity
 
 Helper for managing persistent player identity in localStorage.
@@ -196,6 +271,8 @@ if (identity.hasIdentity()) {
 identity.clear();
 ```
 
+---
+
 ### Error Handling
 
 All methods throw `KeeperBoardError` on failure:
@@ -219,25 +296,41 @@ try {
       case 'INVALID_REQUEST':
         // Check request parameters
         break;
-      case 'ALREADY_CLAIMED':
-        // Player already has a score
-        break;
     }
   }
 }
 ```
 
+---
+
+## Multiple Leaderboards
+
+If your game has multiple leaderboards (e.g., per-level or per-mode):
+
+```typescript
+// Submit to different leaderboards
+await client.submitScore(guid, name, score, 'Level 1');
+await client.submitScore(guid, name, score, 'Endless Mode');
+await client.submitScore(guid, name, score, 'Weekly Challenge');
+
+// Get specific leaderboards
+const level1 = await client.getLeaderboard('Level 1');
+const endless = await client.getLeaderboard('Endless Mode', 50);
+```
+
+---
+
 ## Phaser.js Integration Example
 
 ```typescript
 import { KeeperBoardClient, PlayerIdentity } from 'keeperboard-sdk';
 
-const keeperboard = new KeeperBoardClient({
+const client = new KeeperBoardClient({
   apiUrl: 'https://keeperboard.vercel.app',
   apiKey: 'kb_prod_your_api_key',
 });
 
-const playerIdentity = new PlayerIdentity();
+const identity = new PlayerIdentity();
 
 class GameOverScene extends Phaser.Scene {
   private score: number = 0;
@@ -247,34 +340,25 @@ class GameOverScene extends Phaser.Scene {
   }
 
   async create() {
-    const playerGuid = playerIdentity.getOrCreatePlayerGuid();
-    const playerName = playerIdentity.getPlayerName() ?? 'Anonymous';
+    const playerGuid = identity.getOrCreatePlayerGuid();
+    const playerName = identity.getPlayerName() ?? 'Anonymous';
 
     // Submit score
-    const result = await keeperboard.submitScore(
-      playerGuid,
-      playerName,
-      this.score,
-    );
+    const result = await client.submitScore(playerGuid, playerName, this.score);
 
-    // Display result
+    // Display rank
     this.add
-      .text(400, 200, `Your Rank: #${result.rank}`, {
-        fontSize: '32px',
-      })
+      .text(400, 200, `Your Rank: #${result.rank}`, { fontSize: '32px' })
       .setOrigin(0.5);
 
     if (result.is_new_high_score) {
       this.add
-        .text(400, 250, 'NEW HIGH SCORE!', {
-          fontSize: '24px',
-          color: '#ffff00',
-        })
+        .text(400, 250, 'NEW HIGH SCORE!', { fontSize: '24px', color: '#ffff00' })
         .setOrigin(0.5);
     }
 
-    // Display leaderboard
-    const leaderboard = await keeperboard.getLeaderboard(10);
+    // Display top 10
+    const leaderboard = await client.getLeaderboard();
 
     leaderboard.entries.forEach((entry, index) => {
       const isMe = entry.player_guid === playerGuid;
@@ -285,44 +369,26 @@ class GameOverScene extends Phaser.Scene {
           400,
           350 + index * 30,
           `#${entry.rank} ${entry.player_name}: ${entry.score}`,
-          { fontSize: '18px', color },
+          { fontSize: '18px', color }
         )
         .setOrigin(0.5);
     });
+
+    // Show player's rank if not in top 10
+    const player = await client.getPlayerRank(playerGuid);
+    if (player && player.rank > 10) {
+      this.add
+        .text(400, 660, `... #${player.rank} ${playerName}: ${player.score}`, {
+          fontSize: '18px',
+          color: '#00ff00',
+        })
+        .setOrigin(0.5);
+    }
   }
 }
 ```
 
-## Multiple Leaderboards
-
-If your game has multiple leaderboards (e.g., per-level or per-mode), use the `leaderboardSlug` parameter:
-
-```typescript
-// Submit to a specific leaderboard
-await client.submitScore(guid, name, score, undefined, 'level-1-scores');
-await client.submitScore(guid, name, score, undefined, 'endless-mode');
-
-// Get a specific leaderboard
-const level1 = await client.getLeaderboard(10, 0, 'level-1-scores');
-const endless = await client.getLeaderboard(10, 0, 'endless-mode');
-```
-
-## TypeScript Types
-
-All types are exported for your convenience:
-
-```typescript
-import type {
-  KeeperBoardConfig,
-  ScoreSubmission,
-  ScoreResponse,
-  LeaderboardEntry,
-  LeaderboardResponse,
-  PlayerResponse,
-  ClaimResponse,
-  HealthResponse,
-} from 'keeperboard-sdk';
-```
+---
 
 ## Development
 
@@ -336,10 +402,29 @@ npm run typecheck
 # Build
 npm run build
 
+# Run tests (requires .env with Supabase credentials)
+npm test
+
 # Clean
 npm run clean
 ```
 
+### Running Tests
+
+Copy `.env.example` to `.env` and fill in your Supabase credentials:
+
+```bash
+cp .env.example .env
+```
+
+Then run:
+
+```bash
+npm test
+```
+
+---
+
 ## License
 
 MIT

package/dist/index.d.mts

@@ -18,16 +18,8 @@ interface ScoreSubmission {
     /** Optional metadata to attach to the score */
     metadata?: Record<string, unknown>;
 }
-interface PlayerNameUpdate {
-    /** New display name for the player */
-    player_name: string;
-}
-interface ClaimRequest {
-    /** Player GUID to assign to the migrated score */
-    player_guid: string;
-    /** Player name to match against migrated scores */
-    player_name: string;
-}
+/** Reset schedule options for leaderboards */
+type ResetSchedule = 'none' | 'daily' | 'weekly' | 'monthly';
 interface ScoreResponse {
     /** Score ID in the database */
     id: string;
@@ -55,8 +47,16 @@ interface LeaderboardEntry {
 interface LeaderboardResponse {
     /** Array of leaderboard entries */
     entries: LeaderboardEntry[];
-    /** Total number of scores on this leaderboard */
+    /** Total number of scores in this version/period */
     total_count: number;
+    /** The reset schedule of this leaderboard */
+    reset_schedule: ResetSchedule;
+    /** Current version number — only present when reset_schedule is not 'none' */
+    version?: number;
+    /** Oldest available version number — only present when reset_schedule is not 'none' */
+    oldest_version?: number;
+    /** ISO timestamp of when the next reset occurs — only present when reset_schedule is not 'none' */
+    next_reset?: string;
 }
 interface PlayerResponse {
     /** Score ID in the database */
@@ -88,16 +88,6 @@ interface HealthResponse {
     /** Server timestamp */
     timestamp: string;
 }
-interface ApiSuccessResponse<T> {
-    success: true;
-    data: T;
-}
-interface ApiErrorResponse {
-    success: false;
-    error: string;
-    code: string;
-}
-type ApiResponse<T> = ApiSuccessResponse<T> | ApiErrorResponse;
 declare class KeeperBoardError extends Error {
     readonly code: string;
     readonly statusCode: number;
@@ -114,63 +104,102 @@ declare class KeeperBoardClient {
     private readonly apiKey;
     constructor(config: KeeperBoardConfig);
     /**
-     * Submit a score to the leaderboard.
+     * Submit a score to the default leaderboard.
+     * Only updates if the new score is higher than the existing one.
+     */
+    submitScore(playerGuid: string, playerName: string, score: number): Promise<ScoreResponse>;
+    /**
+     * Submit a score to a specific leaderboard.
      * Only updates if the new score is higher than the existing one.
+     */
+    submitScore(playerGuid: string, playerName: string, score: number, leaderboard: string): Promise<ScoreResponse>;
+    /**
+     * Submit a score with metadata.
+     * Only updates if the new score is higher than the existing one.
+     */
+    submitScore(playerGuid: string, playerName: string, score: number, leaderboard: string, metadata: Record<string, unknown>): Promise<ScoreResponse>;
+    /**
+     * Get the default leaderboard (top 10 entries).
      *
-     * @param playerGuid - Unique player identifier
-     * @param playerName - Player display name
-     * @param score - Score value
-     * @param metadata - Optional metadata to attach
-     * @param leaderboardSlug - Optional leaderboard slug (uses default if not specified)
-     * @returns Score response with rank and whether it's a new high score
+     * @example
+     * const lb = await client.getLeaderboard();
      */
-    submitScore(playerGuid: string, playerName: string, score: number, metadata?: Record<string, unknown>, leaderboardSlug?: string): Promise<ScoreResponse>;
+    getLeaderboard(): Promise<LeaderboardResponse>;
     /**
-     * Get the leaderboard entries with pagination.
+     * Get a specific leaderboard by name (top 10 entries).
      *
-     * @param limit - Maximum number of entries to return (default: 10, max: 100)
-     * @param offset - Pagination offset (default: 0)
-     * @param leaderboardSlug - Optional leaderboard slug (uses default if not specified)
-     * @returns Leaderboard entries with total count
+     * @example
+     * const lb = await client.getLeaderboard('Weekly Best');
      */
-    getLeaderboard(limit?: number, offset?: number, leaderboardSlug?: string): Promise<LeaderboardResponse>;
+    getLeaderboard(name: string): Promise<LeaderboardResponse>;
     /**
-     * Get a specific player's score and rank.
+     * Get a leaderboard with custom limit.
      *
-     * @param playerGuid - Player's unique identifier
-     * @param leaderboardSlug - Optional leaderboard slug (uses default if not specified)
-     * @returns Player's score and rank, or null if not found
+     * @example
+     * const lb = await client.getLeaderboard('Weekly Best', 25);
      */
-    getPlayer(playerGuid: string, leaderboardSlug?: string): Promise<PlayerResponse | null>;
+    getLeaderboard(name: string, limit: number): Promise<LeaderboardResponse>;
     /**
-     * Update a player's display name.
+     * Get a leaderboard with pagination.
      *
-     * @param playerGuid - Player's unique identifier
-     * @param newName - New display name
-     * @param leaderboardSlug - Optional leaderboard slug (uses default if not specified)
-     * @returns Updated player info
+     * @example
+     * const page2 = await client.getLeaderboard('Weekly Best', 10, 10);
      */
-    updatePlayerName(playerGuid: string, newName: string, leaderboardSlug?: string): Promise<PlayerResponse>;
+    getLeaderboard(name: string, limit: number, offset: number): Promise<LeaderboardResponse>;
     /**
-     * Claim a migrated score by matching player name.
-     * Used when scores were imported (e.g., from CSV) without player GUIDs.
+     * Get a specific version of a time-based leaderboard.
      *
-     * @param playerGuid - Player GUID to assign to the claimed score
-     * @param playerName - Player name to match against migrated scores
-     * @param leaderboardSlug - Optional leaderboard slug (uses default if not specified)
-     * @returns Claim result with score and rank
+     * @example
+     * // Get last week's leaderboard (version 3)
+     * const lastWeek = await client.getLeaderboardVersion('Weekly Best', 3);
      */
-    claimScore(playerGuid: string, playerName: string, leaderboardSlug?: string): Promise<ClaimResponse>;
+    getLeaderboardVersion(name: string, version: number): Promise<LeaderboardResponse>;
     /**
-     * Check if the API is healthy.
-     * This endpoint does not require an API key.
+     * Get a specific version with custom limit.
+     */
+    getLeaderboardVersion(name: string, version: number, limit: number): Promise<LeaderboardResponse>;
+    /**
+     * Get a specific version with pagination.
+     */
+    getLeaderboardVersion(name: string, version: number, limit: number, offset: number): Promise<LeaderboardResponse>;
+    /**
+     * Get a player's rank and score on the default leaderboard.
+     * Returns null if the player has no score.
      *
-     * @returns Health status with version and timestamp
+     * @example
+     * const player = await client.getPlayerRank(playerGuid);
+     * if (player) {
+     *   console.log(`You are ranked #${player.rank}`);
+     * }
      */
-    healthCheck(): Promise<HealthResponse>;
+    getPlayerRank(playerGuid: string): Promise<PlayerResponse | null>;
+    /**
+     * Get a player's rank and score on a specific leaderboard.
+     * Returns null if the player has no score.
+     */
+    getPlayerRank(playerGuid: string, leaderboard: string): Promise<PlayerResponse | null>;
+    /**
+     * Update a player's display name on the default leaderboard.
+     */
+    updatePlayerName(playerGuid: string, newName: string): Promise<PlayerResponse>;
+    /**
+     * Update a player's display name on a specific leaderboard.
+     */
+    updatePlayerName(playerGuid: string, newName: string, leaderboard: string): Promise<PlayerResponse>;
     /**
-     * Internal request helper with auth and error handling.
+     * Claim a migrated score by matching player name.
+     * Used when scores were imported without player GUIDs.
      */
+    claimScore(playerGuid: string, playerName: string): Promise<ClaimResponse>;
+    /**
+     * Claim a migrated score on a specific leaderboard.
+     */
+    claimScore(playerGuid: string, playerName: string, leaderboard: string): Promise<ClaimResponse>;
+    /**
+     * Check if the API is healthy.
+     * This endpoint does not require an API key.
+     */
+    healthCheck(): Promise<HealthResponse>;
     private request;
 }
 
@@ -223,4 +252,4 @@ declare class PlayerIdentity {
     private generateUUID;
 }
 
-export { type ApiErrorResponse, type ApiResponse, type ApiSuccessResponse, type ClaimRequest, type ClaimResponse, type HealthResponse, KeeperBoardClient, type KeeperBoardConfig, KeeperBoardError, type LeaderboardEntry, type LeaderboardResponse, PlayerIdentity, type PlayerIdentityConfig, type PlayerNameUpdate, type PlayerResponse, type ScoreResponse, type ScoreSubmission };
+export { type ClaimResponse, type HealthResponse, KeeperBoardClient, type KeeperBoardConfig, KeeperBoardError, type LeaderboardEntry, type LeaderboardResponse, PlayerIdentity, type PlayerIdentityConfig, type PlayerResponse, type ResetSchedule, type ScoreResponse, type ScoreSubmission };

package/dist/index.d.ts

@@ -18,16 +18,8 @@ interface ScoreSubmission {
     /** Optional metadata to attach to the score */
     metadata?: Record<string, unknown>;
 }
-interface PlayerNameUpdate {
-    /** New display name for the player */
-    player_name: string;
-}
-interface ClaimRequest {
-    /** Player GUID to assign to the migrated score */
-    player_guid: string;
-    /** Player name to match against migrated scores */
-    player_name: string;
-}
+/** Reset schedule options for leaderboards */
+type ResetSchedule = 'none' | 'daily' | 'weekly' | 'monthly';
 interface ScoreResponse {
     /** Score ID in the database */
     id: string;
@@ -55,8 +47,16 @@ interface LeaderboardEntry {
 interface LeaderboardResponse {
     /** Array of leaderboard entries */
     entries: LeaderboardEntry[];
-    /** Total number of scores on this leaderboard */
+    /** Total number of scores in this version/period */
     total_count: number;
+    /** The reset schedule of this leaderboard */
+    reset_schedule: ResetSchedule;
+    /** Current version number — only present when reset_schedule is not 'none' */
+    version?: number;
+    /** Oldest available version number — only present when reset_schedule is not 'none' */
+    oldest_version?: number;
+    /** ISO timestamp of when the next reset occurs — only present when reset_schedule is not 'none' */
+    next_reset?: string;
 }
 interface PlayerResponse {
     /** Score ID in the database */
@@ -88,16 +88,6 @@ interface HealthResponse {
     /** Server timestamp */
     timestamp: string;
 }
-interface ApiSuccessResponse<T> {
-    success: true;
-    data: T;
-}
-interface ApiErrorResponse {
-    success: false;
-    error: string;
-    code: string;
-}
-type ApiResponse<T> = ApiSuccessResponse<T> | ApiErrorResponse;
 declare class KeeperBoardError extends Error {
     readonly code: string;
     readonly statusCode: number;
@@ -114,63 +104,102 @@ declare class KeeperBoardClient {
     private readonly apiKey;
     constructor(config: KeeperBoardConfig);
     /**
-     * Submit a score to the leaderboard.
+     * Submit a score to the default leaderboard.
+     * Only updates if the new score is higher than the existing one.
+     */
+    submitScore(playerGuid: string, playerName: string, score: number): Promise<ScoreResponse>;
+    /**
+     * Submit a score to a specific leaderboard.
      * Only updates if the new score is higher than the existing one.
+     */
+    submitScore(playerGuid: string, playerName: string, score: number, leaderboard: string): Promise<ScoreResponse>;
+    /**
+     * Submit a score with metadata.
+     * Only updates if the new score is higher than the existing one.
+     */
+    submitScore(playerGuid: string, playerName: string, score: number, leaderboard: string, metadata: Record<string, unknown>): Promise<ScoreResponse>;
+    /**
+     * Get the default leaderboard (top 10 entries).
      *
-     * @param playerGuid - Unique player identifier
-     * @param playerName - Player display name
-     * @param score - Score value
-     * @param metadata - Optional metadata to attach
-     * @param leaderboardSlug - Optional leaderboard slug (uses default if not specified)
-     * @returns Score response with rank and whether it's a new high score
+     * @example
+     * const lb = await client.getLeaderboard();
      */
-    submitScore(playerGuid: string, playerName: string, score: number, metadata?: Record<string, unknown>, leaderboardSlug?: string): Promise<ScoreResponse>;
+    getLeaderboard(): Promise<LeaderboardResponse>;
     /**
-     * Get the leaderboard entries with pagination.
+     * Get a specific leaderboard by name (top 10 entries).
      *
-     * @param limit - Maximum number of entries to return (default: 10, max: 100)
-     * @param offset - Pagination offset (default: 0)
-     * @param leaderboardSlug - Optional leaderboard slug (uses default if not specified)
-     * @returns Leaderboard entries with total count
+     * @example
+     * const lb = await client.getLeaderboard('Weekly Best');
      */
-    getLeaderboard(limit?: number, offset?: number, leaderboardSlug?: string): Promise<LeaderboardResponse>;
+    getLeaderboard(name: string): Promise<LeaderboardResponse>;
     /**
-     * Get a specific player's score and rank.
+     * Get a leaderboard with custom limit.
      *
-     * @param playerGuid - Player's unique identifier
-     * @param leaderboardSlug - Optional leaderboard slug (uses default if not specified)
-     * @returns Player's score and rank, or null if not found
+     * @example
+     * const lb = await client.getLeaderboard('Weekly Best', 25);
      */
-    getPlayer(playerGuid: string, leaderboardSlug?: string): Promise<PlayerResponse | null>;
+    getLeaderboard(name: string, limit: number): Promise<LeaderboardResponse>;
     /**
-     * Update a player's display name.
+     * Get a leaderboard with pagination.
      *
-     * @param playerGuid - Player's unique identifier
-     * @param newName - New display name
-     * @param leaderboardSlug - Optional leaderboard slug (uses default if not specified)
-     * @returns Updated player info
+     * @example
+     * const page2 = await client.getLeaderboard('Weekly Best', 10, 10);
      */
-    updatePlayerName(playerGuid: string, newName: string, leaderboardSlug?: string): Promise<PlayerResponse>;
+    getLeaderboard(name: string, limit: number, offset: number): Promise<LeaderboardResponse>;
     /**
-     * Claim a migrated score by matching player name.
-     * Used when scores were imported (e.g., from CSV) without player GUIDs.
+     * Get a specific version of a time-based leaderboard.
      *
-     * @param playerGuid - Player GUID to assign to the claimed score
-     * @param playerName - Player name to match against migrated scores
-     * @param leaderboardSlug - Optional leaderboard slug (uses default if not specified)
-     * @returns Claim result with score and rank
+     * @example
+     * // Get last week's leaderboard (version 3)
+     * const lastWeek = await client.getLeaderboardVersion('Weekly Best', 3);
      */
-    claimScore(playerGuid: string, playerName: string, leaderboardSlug?: string): Promise<ClaimResponse>;
+    getLeaderboardVersion(name: string, version: number): Promise<LeaderboardResponse>;
     /**
-     * Check if the API is healthy.
-     * This endpoint does not require an API key.
+     * Get a specific version with custom limit.
+     */
+    getLeaderboardVersion(name: string, version: number, limit: number): Promise<LeaderboardResponse>;
+    /**
+     * Get a specific version with pagination.
+     */
+    getLeaderboardVersion(name: string, version: number, limit: number, offset: number): Promise<LeaderboardResponse>;
+    /**
+     * Get a player's rank and score on the default leaderboard.
+     * Returns null if the player has no score.
      *
-     * @returns Health status with version and timestamp
+     * @example
+     * const player = await client.getPlayerRank(playerGuid);
+     * if (player) {
+     *   console.log(`You are ranked #${player.rank}`);
+     * }
      */
-    healthCheck(): Promise<HealthResponse>;
+    getPlayerRank(playerGuid: string): Promise<PlayerResponse | null>;
+    /**
+     * Get a player's rank and score on a specific leaderboard.
+     * Returns null if the player has no score.
+     */
+    getPlayerRank(playerGuid: string, leaderboard: string): Promise<PlayerResponse | null>;
+    /**
+     * Update a player's display name on the default leaderboard.
+     */
+    updatePlayerName(playerGuid: string, newName: string): Promise<PlayerResponse>;
+    /**
+     * Update a player's display name on a specific leaderboard.
+     */
+    updatePlayerName(playerGuid: string, newName: string, leaderboard: string): Promise<PlayerResponse>;
     /**
-     * Internal request helper with auth and error handling.
+     * Claim a migrated score by matching player name.
+     * Used when scores were imported without player GUIDs.
      */
+    claimScore(playerGuid: string, playerName: string): Promise<ClaimResponse>;
+    /**
+     * Claim a migrated score on a specific leaderboard.
+     */
+    claimScore(playerGuid: string, playerName: string, leaderboard: string): Promise<ClaimResponse>;
+    /**
+     * Check if the API is healthy.
+     * This endpoint does not require an API key.
+     */
+    healthCheck(): Promise<HealthResponse>;
     private request;
 }
 
@@ -223,4 +252,4 @@ declare class PlayerIdentity {
     private generateUUID;
 }
 
-export { type ApiErrorResponse, type ApiResponse, type ApiSuccessResponse, type ClaimRequest, type ClaimResponse, type HealthResponse, KeeperBoardClient, type KeeperBoardConfig, KeeperBoardError, type LeaderboardEntry, type LeaderboardResponse, PlayerIdentity, type PlayerIdentityConfig, type PlayerNameUpdate, type PlayerResponse, type ScoreResponse, type ScoreSubmission };
+export { type ClaimResponse, type HealthResponse, KeeperBoardClient, type KeeperBoardConfig, KeeperBoardError, type LeaderboardEntry, type LeaderboardResponse, PlayerIdentity, type PlayerIdentityConfig, type PlayerResponse, type ResetSchedule, type ScoreResponse, type ScoreSubmission };

package/dist/index.js

@@ -42,21 +42,10 @@ var KeeperBoardClient = class {
     this.apiUrl = config.apiUrl.replace(/\/$/, "");
     this.apiKey = config.apiKey;
   }
-  /**
-   * Submit a score to the leaderboard.
-   * Only updates if the new score is higher than the existing one.
-   *
-   * @param playerGuid - Unique player identifier
-   * @param playerName - Player display name
-   * @param score - Score value
-   * @param metadata - Optional metadata to attach
-   * @param leaderboardSlug - Optional leaderboard slug (uses default if not specified)
-   * @returns Score response with rank and whether it's a new high score
-   */
-  async submitScore(playerGuid, playerName, score, metadata, leaderboardSlug) {
+  async submitScore(playerGuid, playerName, score, leaderboard, metadata) {
     const params = new URLSearchParams();
-    if (leaderboardSlug) {
-      params.set("leaderboard", leaderboardSlug);
+    if (leaderboard) {
+      params.set("leaderboard", leaderboard);
     }
     const url = `${this.apiUrl}/api/v1/scores${params.toString() ? "?" + params.toString() : ""}`;
     const body = {
@@ -65,49 +54,38 @@ var KeeperBoardClient = class {
       score,
       ...metadata && { metadata }
     };
-    const response = await this.request(url, {
+    return this.request(url, {
       method: "POST",
       body: JSON.stringify(body)
     });
-    return response;
   }
-  /**
-   * Get the leaderboard entries with pagination.
-   *
-   * @param limit - Maximum number of entries to return (default: 10, max: 100)
-   * @param offset - Pagination offset (default: 0)
-   * @param leaderboardSlug - Optional leaderboard slug (uses default if not specified)
-   * @returns Leaderboard entries with total count
-   */
-  async getLeaderboard(limit = 10, offset = 0, leaderboardSlug) {
+  async getLeaderboard(name, limit = 10, offset = 0) {
     const params = new URLSearchParams();
     params.set("limit", String(Math.min(limit, 100)));
     params.set("offset", String(offset));
-    if (leaderboardSlug) {
-      params.set("leaderboard", leaderboardSlug);
+    if (name) {
+      params.set("leaderboard", name);
     }
     const url = `${this.apiUrl}/api/v1/leaderboard?${params.toString()}`;
-    return this.request(url, {
-      method: "GET"
-    });
+    return this.request(url, { method: "GET" });
   }
-  /**
-   * Get a specific player's score and rank.
-   *
-   * @param playerGuid - Player's unique identifier
-   * @param leaderboardSlug - Optional leaderboard slug (uses default if not specified)
-   * @returns Player's score and rank, or null if not found
-   */
-  async getPlayer(playerGuid, leaderboardSlug) {
+  async getLeaderboardVersion(name, version, limit = 10, offset = 0) {
+    const params = new URLSearchParams();
+    params.set("leaderboard", name);
+    params.set("version", String(version));
+    params.set("limit", String(Math.min(limit, 100)));
+    params.set("offset", String(offset));
+    const url = `${this.apiUrl}/api/v1/leaderboard?${params.toString()}`;
+    return this.request(url, { method: "GET" });
+  }
+  async getPlayerRank(playerGuid, leaderboard) {
     const params = new URLSearchParams();
-    if (leaderboardSlug) {
-      params.set("leaderboard", leaderboardSlug);
+    if (leaderboard) {
+      params.set("leaderboard", leaderboard);
     }
     const url = `${this.apiUrl}/api/v1/player/${encodeURIComponent(playerGuid)}${params.toString() ? "?" + params.toString() : ""}`;
     try {
-      return await this.request(url, {
-        method: "GET"
-      });
+      return await this.request(url, { method: "GET" });
     } catch (error) {
       if (error instanceof KeeperBoardError && error.code === "NOT_FOUND") {
         return null;
@@ -115,18 +93,10 @@ var KeeperBoardClient = class {
       throw error;
     }
   }
-  /**
-   * Update a player's display name.
-   *
-   * @param playerGuid - Player's unique identifier
-   * @param newName - New display name
-   * @param leaderboardSlug - Optional leaderboard slug (uses default if not specified)
-   * @returns Updated player info
-   */
-  async updatePlayerName(playerGuid, newName, leaderboardSlug) {
+  async updatePlayerName(playerGuid, newName, leaderboard) {
     const params = new URLSearchParams();
-    if (leaderboardSlug) {
-      params.set("leaderboard", leaderboardSlug);
+    if (leaderboard) {
+      params.set("leaderboard", leaderboard);
     }
     const url = `${this.apiUrl}/api/v1/player/${encodeURIComponent(playerGuid)}${params.toString() ? "?" + params.toString() : ""}`;
     return this.request(url, {
@@ -134,19 +104,10 @@ var KeeperBoardClient = class {
       body: JSON.stringify({ player_name: newName })
     });
   }
-  /**
-   * Claim a migrated score by matching player name.
-   * Used when scores were imported (e.g., from CSV) without player GUIDs.
-   *
-   * @param playerGuid - Player GUID to assign to the claimed score
-   * @param playerName - Player name to match against migrated scores
-   * @param leaderboardSlug - Optional leaderboard slug (uses default if not specified)
-   * @returns Claim result with score and rank
-   */
-  async claimScore(playerGuid, playerName, leaderboardSlug) {
+  async claimScore(playerGuid, playerName, leaderboard) {
     const params = new URLSearchParams();
-    if (leaderboardSlug) {
-      params.set("leaderboard", leaderboardSlug);
+    if (leaderboard) {
+      params.set("leaderboard", leaderboard);
     }
     const url = `${this.apiUrl}/api/v1/claim${params.toString() ? "?" + params.toString() : ""}`;
     return this.request(url, {
@@ -157,19 +118,18 @@ var KeeperBoardClient = class {
       })
     });
   }
+  // ============================================
+  // HEALTH CHECK
+  // ============================================
   /**
    * Check if the API is healthy.
    * This endpoint does not require an API key.
-   *
-   * @returns Health status with version and timestamp
    */
   async healthCheck() {
     const url = `${this.apiUrl}/api/v1/health`;
     const response = await fetch(url, {
       method: "GET",
-      headers: {
-        Accept: "application/json"
-      }
+      headers: { Accept: "application/json" }
     });
     const json = await response.json();
     if (!json.success) {
@@ -177,9 +137,9 @@ var KeeperBoardClient = class {
     }
     return json.data;
   }
-  /**
-   * Internal request helper with auth and error handling.
-   */
+  // ============================================
+  // INTERNAL
+  // ============================================
   async request(url, options) {
     const headers = {
       "Content-Type": "application/json",
@@ -188,10 +148,7 @@ var KeeperBoardClient = class {
     };
     const response = await fetch(url, {
       ...options,
-      headers: {
-        ...headers,
-        ...options.headers || {}
-      }
+      headers: { ...headers, ...options.headers || {} }
     });
     const json = await response.json();
     if (!json.success) {

package/dist/index.mjs

@@ -14,21 +14,10 @@ var KeeperBoardClient = class {
     this.apiUrl = config.apiUrl.replace(/\/$/, "");
     this.apiKey = config.apiKey;
   }
-  /**
-   * Submit a score to the leaderboard.
-   * Only updates if the new score is higher than the existing one.
-   *
-   * @param playerGuid - Unique player identifier
-   * @param playerName - Player display name
-   * @param score - Score value
-   * @param metadata - Optional metadata to attach
-   * @param leaderboardSlug - Optional leaderboard slug (uses default if not specified)
-   * @returns Score response with rank and whether it's a new high score
-   */
-  async submitScore(playerGuid, playerName, score, metadata, leaderboardSlug) {
+  async submitScore(playerGuid, playerName, score, leaderboard, metadata) {
     const params = new URLSearchParams();
-    if (leaderboardSlug) {
-      params.set("leaderboard", leaderboardSlug);
+    if (leaderboard) {
+      params.set("leaderboard", leaderboard);
     }
     const url = `${this.apiUrl}/api/v1/scores${params.toString() ? "?" + params.toString() : ""}`;
     const body = {
@@ -37,49 +26,38 @@ var KeeperBoardClient = class {
       score,
       ...metadata && { metadata }
     };
-    const response = await this.request(url, {
+    return this.request(url, {
       method: "POST",
       body: JSON.stringify(body)
     });
-    return response;
   }
-  /**
-   * Get the leaderboard entries with pagination.
-   *
-   * @param limit - Maximum number of entries to return (default: 10, max: 100)
-   * @param offset - Pagination offset (default: 0)
-   * @param leaderboardSlug - Optional leaderboard slug (uses default if not specified)
-   * @returns Leaderboard entries with total count
-   */
-  async getLeaderboard(limit = 10, offset = 0, leaderboardSlug) {
+  async getLeaderboard(name, limit = 10, offset = 0) {
     const params = new URLSearchParams();
     params.set("limit", String(Math.min(limit, 100)));
     params.set("offset", String(offset));
-    if (leaderboardSlug) {
-      params.set("leaderboard", leaderboardSlug);
+    if (name) {
+      params.set("leaderboard", name);
     }
     const url = `${this.apiUrl}/api/v1/leaderboard?${params.toString()}`;
-    return this.request(url, {
-      method: "GET"
-    });
+    return this.request(url, { method: "GET" });
   }
-  /**
-   * Get a specific player's score and rank.
-   *
-   * @param playerGuid - Player's unique identifier
-   * @param leaderboardSlug - Optional leaderboard slug (uses default if not specified)
-   * @returns Player's score and rank, or null if not found
-   */
-  async getPlayer(playerGuid, leaderboardSlug) {
+  async getLeaderboardVersion(name, version, limit = 10, offset = 0) {
+    const params = new URLSearchParams();
+    params.set("leaderboard", name);
+    params.set("version", String(version));
+    params.set("limit", String(Math.min(limit, 100)));
+    params.set("offset", String(offset));
+    const url = `${this.apiUrl}/api/v1/leaderboard?${params.toString()}`;
+    return this.request(url, { method: "GET" });
+  }
+  async getPlayerRank(playerGuid, leaderboard) {
     const params = new URLSearchParams();
-    if (leaderboardSlug) {
-      params.set("leaderboard", leaderboardSlug);
+    if (leaderboard) {
+      params.set("leaderboard", leaderboard);
     }
     const url = `${this.apiUrl}/api/v1/player/${encodeURIComponent(playerGuid)}${params.toString() ? "?" + params.toString() : ""}`;
     try {
-      return await this.request(url, {
-        method: "GET"
-      });
+      return await this.request(url, { method: "GET" });
     } catch (error) {
       if (error instanceof KeeperBoardError && error.code === "NOT_FOUND") {
         return null;
@@ -87,18 +65,10 @@ var KeeperBoardClient = class {
       throw error;
     }
   }
-  /**
-   * Update a player's display name.
-   *
-   * @param playerGuid - Player's unique identifier
-   * @param newName - New display name
-   * @param leaderboardSlug - Optional leaderboard slug (uses default if not specified)
-   * @returns Updated player info
-   */
-  async updatePlayerName(playerGuid, newName, leaderboardSlug) {
+  async updatePlayerName(playerGuid, newName, leaderboard) {
     const params = new URLSearchParams();
-    if (leaderboardSlug) {
-      params.set("leaderboard", leaderboardSlug);
+    if (leaderboard) {
+      params.set("leaderboard", leaderboard);
     }
     const url = `${this.apiUrl}/api/v1/player/${encodeURIComponent(playerGuid)}${params.toString() ? "?" + params.toString() : ""}`;
     return this.request(url, {
@@ -106,19 +76,10 @@ var KeeperBoardClient = class {
       body: JSON.stringify({ player_name: newName })
     });
   }
-  /**
-   * Claim a migrated score by matching player name.
-   * Used when scores were imported (e.g., from CSV) without player GUIDs.
-   *
-   * @param playerGuid - Player GUID to assign to the claimed score
-   * @param playerName - Player name to match against migrated scores
-   * @param leaderboardSlug - Optional leaderboard slug (uses default if not specified)
-   * @returns Claim result with score and rank
-   */
-  async claimScore(playerGuid, playerName, leaderboardSlug) {
+  async claimScore(playerGuid, playerName, leaderboard) {
     const params = new URLSearchParams();
-    if (leaderboardSlug) {
-      params.set("leaderboard", leaderboardSlug);
+    if (leaderboard) {
+      params.set("leaderboard", leaderboard);
     }
     const url = `${this.apiUrl}/api/v1/claim${params.toString() ? "?" + params.toString() : ""}`;
     return this.request(url, {
@@ -129,19 +90,18 @@ var KeeperBoardClient = class {
       })
     });
   }
+  // ============================================
+  // HEALTH CHECK
+  // ============================================
   /**
    * Check if the API is healthy.
    * This endpoint does not require an API key.
-   *
-   * @returns Health status with version and timestamp
    */
   async healthCheck() {
     const url = `${this.apiUrl}/api/v1/health`;
     const response = await fetch(url, {
       method: "GET",
-      headers: {
-        Accept: "application/json"
-      }
+      headers: { Accept: "application/json" }
     });
     const json = await response.json();
     if (!json.success) {
@@ -149,9 +109,9 @@ var KeeperBoardClient = class {
     }
     return json.data;
   }
-  /**
-   * Internal request helper with auth and error handling.
-   */
+  // ============================================
+  // INTERNAL
+  // ============================================
   async request(url, options) {
     const headers = {
       "Content-Type": "application/json",
@@ -160,10 +120,7 @@ var KeeperBoardClient = class {
     };
     const response = await fetch(url, {
       ...options,
-      headers: {
-        ...headers,
-        ...options.headers || {}
-      }
+      headers: { ...headers, ...options.headers || {} }
     });
     const json = await response.json();
     if (!json.success) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keeperboard",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "TypeScript client SDK for KeeperBoard leaderboard-as-a-service",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -19,6 +19,8 @@
     "build": "tsup src/index.ts --format cjs,esm --dts",
     "typecheck": "tsc --noEmit",
     "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -42,8 +44,11 @@
     "url": "https://github.com/clauderoy790/keeperboard/issues"
   },
   "devDependencies": {
+    "@supabase/supabase-js": "^2.95.3",
+    "dotenv": "^17.2.4",
     "tsup": "^8.0.0",
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.18"
   },
   "engines": {
     "node": ">=18"