keeperboard 1.0.2 → 1.0.4

package/README.md

@@ -1,13 +1,13 @@
 # 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.
 
 ## Installation
 
 ```bash
-npm install keeperboard-sdk
+npm install keeperboard
 ```
 
 ### Alternative: Copy source directly
@@ -24,31 +24,30 @@ 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
 
 ```typescript
-import { KeeperBoardClient, PlayerIdentity } from 'keeperboard-sdk';
+import { KeeperBoardClient, PlayerIdentity } from 'keeperboard';
 
 // Create the API client
-const keeperboard = new KeeperBoardClient({
-  apiUrl: 'https://keeperboard.vercel.app',
-  apiKey: 'kb_dev_your_api_key_here',
+const client = new KeeperBoardClient({
+  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 +56,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 +82,155 @@ 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_...")
+  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',
-  'PlayerName',
-  2500,
-  { level: 10, character: 'warrior' }, // optional metadata
-  'high-scores', // optional leaderboard slug
-);
-
-// Returns:
-// {
-//   id: string,
-//   player_guid: string,
-//   player_name: string,
-//   score: number,
-//   rank: number,
-//   is_new_high_score: boolean
-// }
+const result = await client.submitScore('player-uuid', 'PlayerName', 2500);
+// Returns: { id, player_guid, player_name, score, rank, is_new_high_score }
 ```
 
-##### `getLeaderboard(limit?, offset?, leaderboardSlug?)`
+#### `submitScore(playerGuid, playerName, score, leaderboard)`
 
-Get leaderboard entries with pagination.
+Submit to a specific leaderboard by name.
 
 ```typescript
-const result = await client.getLeaderboard(
-  25, // limit (max 100)
-  0, // offset
-  'high-scores', // optional leaderboard slug
-);
-
-// Returns:
-// {
-//   entries: [{ rank, player_guid, player_name, score }],
-//   total_count: number
-// }
+await client.submitScore('player-uuid', 'PlayerName', 2500, 'Weekly Best');
 ```
 
-##### `getPlayer(playerGuid, leaderboardSlug?)`
+#### `submitScore(playerGuid, playerName, score, leaderboard, metadata)`
+
+Submit with optional metadata.
+
+```typescript
+await client.submitScore('player-uuid', 'PlayerName', 2500, 'Weekly Best', {
+  level: 10,
+  character: 'warrior',
+});
+```
+
+---
+
+### Leaderboard
+
+#### `getLeaderboard()`
+
+Get the default leaderboard (top 10 entries).
+
+```typescript
+const lb = await client.getLeaderboard();
+// Returns: { entries, total_count, reset_schedule }
+```
+
+#### `getLeaderboard(name)`
+
+Get a specific leaderboard by name.
+
+```typescript
+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)
+
+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);
+```
+
+#### `getLeaderboardVersion(name, version, limit, offset)`
+
+Get historical version with pagination.
+
+```typescript
+const lb = await client.getLeaderboardVersion('Weekly Best', 3, 25, 0);
+```
+
+---
+
+### Player
+
+#### `getPlayerRank(playerGuid)`
 
-Get a player's score and rank. Returns `null` if not found.
+Get a player's rank and score. Returns `null` if player has no score.
 
 ```typescript
-const player = await client.getPlayer('player-uuid-123');
+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 +239,8 @@ const health = await client.healthCheck();
 console.log(`API Version: ${health.version}`);
 ```
 
+---
+
 ### PlayerIdentity
 
 Helper for managing persistent player identity in localStorage.
@@ -196,12 +266,14 @@ if (identity.hasIdentity()) {
 identity.clear();
 ```
 
+---
+
 ### Error Handling
 
 All methods throw `KeeperBoardError` on failure:
 
 ```typescript
-import { KeeperBoardError } from 'keeperboard-sdk';
+import { KeeperBoardError } from 'keeperboard';
 
 try {
   await client.submitScore(playerGuid, name, score);
@@ -219,25 +291,40 @@ 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';
+import { KeeperBoardClient, PlayerIdentity } from 'keeperboard';
 
-const keeperboard = new KeeperBoardClient({
-  apiUrl: 'https://keeperboard.vercel.app',
+const client = new KeeperBoardClient({
   apiKey: 'kb_prod_your_api_key',
 });
 
-const playerIdentity = new PlayerIdentity();
+const identity = new PlayerIdentity();
 
 class GameOverScene extends Phaser.Scene {
   private score: number = 0;
@@ -247,21 +334,15 @@ 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) {
@@ -273,8 +354,8 @@ class GameOverScene extends Phaser.Scene {
         .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;
@@ -289,40 +370,22 @@ class GameOverScene extends Phaser.Scene {
         )
         .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 +399,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

@@ -3,10 +3,10 @@
  * Matches the API response shapes from the KeeperBoard public API.
  */
 interface KeeperBoardConfig {
-    /** Base URL of the KeeperBoard API (e.g., "https://keeperboard.vercel.app") */
-    apiUrl: string;
     /** API key from the KeeperBoard dashboard (e.g., "kb_dev_abc123...") */
     apiKey: string;
+    /** @internal Base URL override for testing. Do not use in production. */
+    apiUrl?: string;
 }
 interface ScoreSubmission {
     /** Unique player identifier (UUID or custom string) */
@@ -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;
@@ -110,67 +100,107 @@ declare class KeeperBoardError extends Error {
  */
 
 declare class KeeperBoardClient {
+    private static readonly DEFAULT_API_URL;
     private readonly apiUrl;
     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 +253,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

@@ -3,10 +3,10 @@
  * Matches the API response shapes from the KeeperBoard public API.
  */
 interface KeeperBoardConfig {
-    /** Base URL of the KeeperBoard API (e.g., "https://keeperboard.vercel.app") */
-    apiUrl: string;
     /** API key from the KeeperBoard dashboard (e.g., "kb_dev_abc123...") */
     apiKey: string;
+    /** @internal Base URL override for testing. Do not use in production. */
+    apiUrl?: string;
 }
 interface ScoreSubmission {
     /** Unique player identifier (UUID or custom string) */
@@ -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;
@@ -110,67 +100,107 @@ declare class KeeperBoardError extends Error {
  */
 
 declare class KeeperBoardClient {
+    private static readonly DEFAULT_API_URL;
     private readonly apiUrl;
     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 +253,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

@@ -37,26 +37,16 @@ var KeeperBoardError = class extends Error {
 };
 
 // src/KeeperBoardClient.ts
-var KeeperBoardClient = class {
+var _KeeperBoardClient = class _KeeperBoardClient {
   constructor(config) {
-    this.apiUrl = config.apiUrl.replace(/\/$/, "");
+    const url = config.apiUrl ?? _KeeperBoardClient.DEFAULT_API_URL;
+    this.apiUrl = url.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 +55,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 +94,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 +105,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 +119,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 +138,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 +149,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) {
@@ -200,6 +158,8 @@ var KeeperBoardClient = class {
     return json.data;
   }
 };
+_KeeperBoardClient.DEFAULT_API_URL = "https://keeperboard.vercel.app";
+var KeeperBoardClient = _KeeperBoardClient;
 
 // src/PlayerIdentity.ts
 var DEFAULT_KEY_PREFIX = "keeperboard_";

package/dist/index.mjs

@@ -9,26 +9,16 @@ var KeeperBoardError = class extends Error {
 };
 
 // src/KeeperBoardClient.ts
-var KeeperBoardClient = class {
+var _KeeperBoardClient = class _KeeperBoardClient {
   constructor(config) {
-    this.apiUrl = config.apiUrl.replace(/\/$/, "");
+    const url = config.apiUrl ?? _KeeperBoardClient.DEFAULT_API_URL;
+    this.apiUrl = url.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 +27,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 +66,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 +77,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 +91,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 +110,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 +121,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) {
@@ -172,6 +130,8 @@ var KeeperBoardClient = class {
     return json.data;
   }
 };
+_KeeperBoardClient.DEFAULT_API_URL = "https://keeperboard.vercel.app";
+var KeeperBoardClient = _KeeperBoardClient;
 
 // src/PlayerIdentity.ts
 var DEFAULT_KEY_PREFIX = "keeperboard_";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keeperboard",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "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"