keeperboard-sdk 1.0.1

package/README.md

@@ -0,0 +1,345 @@
+# 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.
+
+Works with Phaser.js, vanilla JavaScript, and any TypeScript/JavaScript game running in the browser.
+
+## Installation
+
+```bash
+npm install keeperboard-sdk
+```
+
+### Alternative: Copy source directly
+
+If you prefer not to use npm, copy the `src/` folder into your project:
+
+```typescript
+import { KeeperBoardClient, PlayerIdentity } from './keeperboard/index';
+```
+
+## Quick Start
+
+### 1. Get your API key
+
+1. Sign up at your KeeperBoard dashboard
+2. Create a game
+3. Generate an API key for your environment (dev/prod)
+
+### 2. Initialize the client
+
+```typescript
+import { KeeperBoardClient, PlayerIdentity } from 'keeperboard-sdk';
+
+// Create the API client
+const keeperboard = new KeeperBoardClient({
+  apiUrl: 'https://keeperboard.vercel.app',
+  apiKey: 'kb_dev_your_api_key_here',
+});
+
+// Helper for persistent player identity
+const playerIdentity = new PlayerIdentity();
+```
+
+### 3. Submit a score
+
+```typescript
+// Get or create a persistent player GUID
+const playerGuid = playerIdentity.getOrCreatePlayerGuid();
+
+// Submit a score (only updates if higher than existing)
+const result = await keeperboard.submitScore(playerGuid, 'PlayerName', 1500);
+
+console.log(`Rank: #${result.rank}`);
+console.log(`New high score: ${result.is_new_high_score}`);
+```
+
+### 4. Display the leaderboard
+
+```typescript
+const leaderboard = await keeperboard.getLeaderboard(10);
+
+leaderboard.entries.forEach((entry) => {
+  console.log(`#${entry.rank} ${entry.player_name}: ${entry.score}`);
+});
+```
+
+## API Reference
+
+### KeeperBoardClient
+
+#### Constructor
+
+```typescript
+const client = new KeeperBoardClient({
+  apiUrl: string, // Your KeeperBoard API URL
+  apiKey: string, // API key from dashboard (e.g., "kb_dev_...")
+});
+```
+
+#### Methods
+
+##### `submitScore(playerGuid, playerName, score, metadata?, leaderboardSlug?)`
+
+Submit a score. Only updates if the new score is higher than the existing one.
+
+```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
+// }
+```
+
+##### `getLeaderboard(limit?, offset?, leaderboardSlug?)`
+
+Get leaderboard entries with pagination.
+
+```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
+// }
+```
+
+##### `getPlayer(playerGuid, leaderboardSlug?)`
+
+Get a player's score and rank. Returns `null` if not found.
+
+```typescript
+const player = await client.getPlayer('player-uuid-123');
+
+if (player) {
+  console.log(`Score: ${player.score}, Rank: #${player.rank}`);
+}
+```
+
+##### `updatePlayerName(playerGuid, newName, leaderboardSlug?)`
+
+Update a player's display name.
+
+```typescript
+const result = await client.updatePlayerName(
+  'player-uuid-123',
+  'NewPlayerName',
+);
+```
+
+##### `claimScore(playerGuid, playerName, leaderboardSlug?)`
+
+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');
+  }
+}
+```
+
+##### `healthCheck()`
+
+Check if the API is healthy. Does not require an API key.
+
+```typescript
+const health = await client.healthCheck();
+console.log(`API Version: ${health.version}`);
+```
+
+### PlayerIdentity
+
+Helper for managing persistent player identity in localStorage.
+
+```typescript
+const identity = new PlayerIdentity({
+  keyPrefix: 'mygame_', // optional, default: 'keeperboard_'
+});
+
+// Get or create a persistent player GUID
+const guid = identity.getOrCreatePlayerGuid();
+
+// Store/retrieve player name
+identity.setPlayerName('PlayerName');
+const name = identity.getPlayerName();
+
+// Check if identity exists
+if (identity.hasIdentity()) {
+  // returning player
+}
+
+// Clear identity (e.g., for "Sign Out")
+identity.clear();
+```
+
+### Error Handling
+
+All methods throw `KeeperBoardError` on failure:
+
+```typescript
+import { KeeperBoardError } from 'keeperboard-sdk';
+
+try {
+  await client.submitScore(playerGuid, name, score);
+} catch (error) {
+  if (error instanceof KeeperBoardError) {
+    console.error(`Error [${error.code}]: ${error.message}`);
+
+    switch (error.code) {
+      case 'INVALID_API_KEY':
+        // Check your API key
+        break;
+      case 'NOT_FOUND':
+        // Player or leaderboard not found
+        break;
+      case 'INVALID_REQUEST':
+        // Check request parameters
+        break;
+      case 'ALREADY_CLAIMED':
+        // Player already has a score
+        break;
+    }
+  }
+}
+```
+
+## Phaser.js Integration Example
+
+```typescript
+import { KeeperBoardClient, PlayerIdentity } from 'keeperboard-sdk';
+
+const keeperboard = new KeeperBoardClient({
+  apiUrl: 'https://keeperboard.vercel.app',
+  apiKey: 'kb_prod_your_api_key',
+});
+
+const playerIdentity = new PlayerIdentity();
+
+class GameOverScene extends Phaser.Scene {
+  private score: number = 0;
+
+  init(data: { score: number }) {
+    this.score = data.score;
+  }
+
+  async create() {
+    const playerGuid = playerIdentity.getOrCreatePlayerGuid();
+    const playerName = playerIdentity.getPlayerName() ?? 'Anonymous';
+
+    // Submit score
+    const result = await keeperboard.submitScore(
+      playerGuid,
+      playerName,
+      this.score,
+    );
+
+    // Display result
+    this.add
+      .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',
+        })
+        .setOrigin(0.5);
+    }
+
+    // Display leaderboard
+    const leaderboard = await keeperboard.getLeaderboard(10);
+
+    leaderboard.entries.forEach((entry, index) => {
+      const isMe = entry.player_guid === playerGuid;
+      const color = isMe ? '#00ff00' : '#ffffff';
+
+      this.add
+        .text(
+          400,
+          350 + index * 30,
+          `#${entry.rank} ${entry.player_name}: ${entry.score}`,
+          { fontSize: '18px', color },
+        )
+        .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
+
+```bash
+# Install dependencies
+npm install
+
+# Type check
+npm run typecheck
+
+# Build
+npm run build
+
+# Clean
+npm run clean
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,226 @@
+/**
+ * Type definitions for KeeperBoard SDK.
+ * 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;
+}
+interface ScoreSubmission {
+    /** Unique player identifier (UUID or custom string) */
+    player_guid: string;
+    /** Player display name */
+    player_name: string;
+    /** Score value */
+    score: number;
+    /** 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;
+}
+interface ScoreResponse {
+    /** Score ID in the database */
+    id: string;
+    /** Player's unique identifier */
+    player_guid: string;
+    /** Player's display name */
+    player_name: string;
+    /** Current score value */
+    score: number;
+    /** Player's rank on the leaderboard */
+    rank: number;
+    /** Whether this submission resulted in a new high score */
+    is_new_high_score: boolean;
+}
+interface LeaderboardEntry {
+    /** Position on the leaderboard (1-indexed) */
+    rank: number;
+    /** Player's unique identifier */
+    player_guid: string;
+    /** Player's display name */
+    player_name: string;
+    /** Score value */
+    score: number;
+}
+interface LeaderboardResponse {
+    /** Array of leaderboard entries */
+    entries: LeaderboardEntry[];
+    /** Total number of scores on this leaderboard */
+    total_count: number;
+}
+interface PlayerResponse {
+    /** Score ID in the database */
+    id: string;
+    /** Player's unique identifier */
+    player_guid: string;
+    /** Player's display name */
+    player_name: string;
+    /** Player's score */
+    score: number;
+    /** Player's rank on the leaderboard */
+    rank: number;
+}
+interface ClaimResponse {
+    /** Whether the score was successfully claimed */
+    claimed: boolean;
+    /** The claimed score value */
+    score: number;
+    /** Player's rank after claiming */
+    rank: number;
+    /** The player name that was matched */
+    player_name: string;
+}
+interface HealthResponse {
+    /** Service name */
+    service: string;
+    /** API version */
+    version: string;
+    /** 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;
+    constructor(message: string, code: string, statusCode: number);
+}
+
+/**
+ * KeeperBoard API client for TypeScript/JavaScript games.
+ * Works in any browser environment using the fetch API.
+ */
+
+declare class KeeperBoardClient {
+    private readonly apiUrl;
+    private readonly apiKey;
+    constructor(config: KeeperBoardConfig);
+    /**
+     * 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
+     */
+    submitScore(playerGuid: string, playerName: string, score: number, metadata?: Record<string, unknown>, leaderboardSlug?: string): Promise<ScoreResponse>;
+    /**
+     * 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
+     */
+    getLeaderboard(limit?: number, offset?: number, leaderboardSlug?: string): Promise<LeaderboardResponse>;
+    /**
+     * 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
+     */
+    getPlayer(playerGuid: string, leaderboardSlug?: string): Promise<PlayerResponse | null>;
+    /**
+     * 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
+     */
+    updatePlayerName(playerGuid: string, newName: string, leaderboardSlug?: string): Promise<PlayerResponse>;
+    /**
+     * 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
+     */
+    claimScore(playerGuid: string, playerName: string, leaderboardSlug?: string): Promise<ClaimResponse>;
+    /**
+     * Check if the API is healthy.
+     * This endpoint does not require an API key.
+     *
+     * @returns Health status with version and timestamp
+     */
+    healthCheck(): Promise<HealthResponse>;
+    /**
+     * Internal request helper with auth and error handling.
+     */
+    private request;
+}
+
+/**
+ * Helper class for managing player identity in localStorage.
+ * Provides persistent player GUID and name storage across game sessions.
+ */
+interface PlayerIdentityConfig {
+    /** Prefix for localStorage keys (default: "keeperboard_") */
+    keyPrefix?: string;
+}
+declare class PlayerIdentity {
+    private readonly keyPrefix;
+    private readonly guidKey;
+    private readonly nameKey;
+    constructor(config?: PlayerIdentityConfig);
+    /**
+     * Get the stored player GUID, or null if none exists.
+     */
+    getPlayerGuid(): string | null;
+    /**
+     * Set the player GUID in localStorage.
+     */
+    setPlayerGuid(guid: string): void;
+    /**
+     * Get the stored player GUID, creating one if it doesn't exist.
+     * Uses crypto.randomUUID() for generating new GUIDs.
+     */
+    getOrCreatePlayerGuid(): string;
+    /**
+     * Get the stored player name, or null if none exists.
+     */
+    getPlayerName(): string | null;
+    /**
+     * Set the player name in localStorage.
+     */
+    setPlayerName(name: string): void;
+    /**
+     * Clear all stored player identity data.
+     */
+    clear(): void;
+    /**
+     * Check if player identity is stored.
+     */
+    hasIdentity(): boolean;
+    /**
+     * Generate a UUID v4.
+     * Uses crypto.randomUUID() if available, otherwise falls back to a manual implementation.
+     */
+    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 };

package/dist/index.d.ts

@@ -0,0 +1,226 @@
+/**
+ * Type definitions for KeeperBoard SDK.
+ * 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;
+}
+interface ScoreSubmission {
+    /** Unique player identifier (UUID or custom string) */
+    player_guid: string;
+    /** Player display name */
+    player_name: string;
+    /** Score value */
+    score: number;
+    /** 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;
+}
+interface ScoreResponse {
+    /** Score ID in the database */
+    id: string;
+    /** Player's unique identifier */
+    player_guid: string;
+    /** Player's display name */
+    player_name: string;
+    /** Current score value */
+    score: number;
+    /** Player's rank on the leaderboard */
+    rank: number;
+    /** Whether this submission resulted in a new high score */
+    is_new_high_score: boolean;
+}
+interface LeaderboardEntry {
+    /** Position on the leaderboard (1-indexed) */
+    rank: number;
+    /** Player's unique identifier */
+    player_guid: string;
+    /** Player's display name */
+    player_name: string;
+    /** Score value */
+    score: number;
+}
+interface LeaderboardResponse {
+    /** Array of leaderboard entries */
+    entries: LeaderboardEntry[];
+    /** Total number of scores on this leaderboard */
+    total_count: number;
+}
+interface PlayerResponse {
+    /** Score ID in the database */
+    id: string;
+    /** Player's unique identifier */
+    player_guid: string;
+    /** Player's display name */
+    player_name: string;
+    /** Player's score */
+    score: number;
+    /** Player's rank on the leaderboard */
+    rank: number;
+}
+interface ClaimResponse {
+    /** Whether the score was successfully claimed */
+    claimed: boolean;
+    /** The claimed score value */
+    score: number;
+    /** Player's rank after claiming */
+    rank: number;
+    /** The player name that was matched */
+    player_name: string;
+}
+interface HealthResponse {
+    /** Service name */
+    service: string;
+    /** API version */
+    version: string;
+    /** 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;
+    constructor(message: string, code: string, statusCode: number);
+}
+
+/**
+ * KeeperBoard API client for TypeScript/JavaScript games.
+ * Works in any browser environment using the fetch API.
+ */
+
+declare class KeeperBoardClient {
+    private readonly apiUrl;
+    private readonly apiKey;
+    constructor(config: KeeperBoardConfig);
+    /**
+     * 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
+     */
+    submitScore(playerGuid: string, playerName: string, score: number, metadata?: Record<string, unknown>, leaderboardSlug?: string): Promise<ScoreResponse>;
+    /**
+     * 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
+     */
+    getLeaderboard(limit?: number, offset?: number, leaderboardSlug?: string): Promise<LeaderboardResponse>;
+    /**
+     * 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
+     */
+    getPlayer(playerGuid: string, leaderboardSlug?: string): Promise<PlayerResponse | null>;
+    /**
+     * 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
+     */
+    updatePlayerName(playerGuid: string, newName: string, leaderboardSlug?: string): Promise<PlayerResponse>;
+    /**
+     * 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
+     */
+    claimScore(playerGuid: string, playerName: string, leaderboardSlug?: string): Promise<ClaimResponse>;
+    /**
+     * Check if the API is healthy.
+     * This endpoint does not require an API key.
+     *
+     * @returns Health status with version and timestamp
+     */
+    healthCheck(): Promise<HealthResponse>;
+    /**
+     * Internal request helper with auth and error handling.
+     */
+    private request;
+}
+
+/**
+ * Helper class for managing player identity in localStorage.
+ * Provides persistent player GUID and name storage across game sessions.
+ */
+interface PlayerIdentityConfig {
+    /** Prefix for localStorage keys (default: "keeperboard_") */
+    keyPrefix?: string;
+}
+declare class PlayerIdentity {
+    private readonly keyPrefix;
+    private readonly guidKey;
+    private readonly nameKey;
+    constructor(config?: PlayerIdentityConfig);
+    /**
+     * Get the stored player GUID, or null if none exists.
+     */
+    getPlayerGuid(): string | null;
+    /**
+     * Set the player GUID in localStorage.
+     */
+    setPlayerGuid(guid: string): void;
+    /**
+     * Get the stored player GUID, creating one if it doesn't exist.
+     * Uses crypto.randomUUID() for generating new GUIDs.
+     */
+    getOrCreatePlayerGuid(): string;
+    /**
+     * Get the stored player name, or null if none exists.
+     */
+    getPlayerName(): string | null;
+    /**
+     * Set the player name in localStorage.
+     */
+    setPlayerName(name: string): void;
+    /**
+     * Clear all stored player identity data.
+     */
+    clear(): void;
+    /**
+     * Check if player identity is stored.
+     */
+    hasIdentity(): boolean;
+    /**
+     * Generate a UUID v4.
+     * Uses crypto.randomUUID() if available, otherwise falls back to a manual implementation.
+     */
+    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 };

package/dist/index.js

@@ -0,0 +1,296 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  KeeperBoardClient: () => KeeperBoardClient,
+  KeeperBoardError: () => KeeperBoardError,
+  PlayerIdentity: () => PlayerIdentity
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/types.ts
+var KeeperBoardError = class extends Error {
+  constructor(message, code, statusCode) {
+    super(message);
+    this.code = code;
+    this.statusCode = statusCode;
+    this.name = "KeeperBoardError";
+  }
+};
+
+// src/KeeperBoardClient.ts
+var KeeperBoardClient = class {
+  constructor(config) {
+    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) {
+    const params = new URLSearchParams();
+    if (leaderboardSlug) {
+      params.set("leaderboard", leaderboardSlug);
+    }
+    const url = `${this.apiUrl}/api/v1/scores${params.toString() ? "?" + params.toString() : ""}`;
+    const body = {
+      player_guid: playerGuid,
+      player_name: playerName,
+      score,
+      ...metadata && { metadata }
+    };
+    const response = await 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) {
+    const params = new URLSearchParams();
+    params.set("limit", String(Math.min(limit, 100)));
+    params.set("offset", String(offset));
+    if (leaderboardSlug) {
+      params.set("leaderboard", leaderboardSlug);
+    }
+    const url = `${this.apiUrl}/api/v1/leaderboard?${params.toString()}`;
+    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) {
+    const params = new URLSearchParams();
+    if (leaderboardSlug) {
+      params.set("leaderboard", leaderboardSlug);
+    }
+    const url = `${this.apiUrl}/api/v1/player/${encodeURIComponent(playerGuid)}${params.toString() ? "?" + params.toString() : ""}`;
+    try {
+      return await this.request(url, {
+        method: "GET"
+      });
+    } catch (error) {
+      if (error instanceof KeeperBoardError && error.code === "NOT_FOUND") {
+        return null;
+      }
+      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) {
+    const params = new URLSearchParams();
+    if (leaderboardSlug) {
+      params.set("leaderboard", leaderboardSlug);
+    }
+    const url = `${this.apiUrl}/api/v1/player/${encodeURIComponent(playerGuid)}${params.toString() ? "?" + params.toString() : ""}`;
+    return this.request(url, {
+      method: "PUT",
+      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) {
+    const params = new URLSearchParams();
+    if (leaderboardSlug) {
+      params.set("leaderboard", leaderboardSlug);
+    }
+    const url = `${this.apiUrl}/api/v1/claim${params.toString() ? "?" + params.toString() : ""}`;
+    return this.request(url, {
+      method: "POST",
+      body: JSON.stringify({
+        player_guid: playerGuid,
+        player_name: playerName
+      })
+    });
+  }
+  /**
+   * 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"
+      }
+    });
+    const json = await response.json();
+    if (!json.success) {
+      throw new KeeperBoardError(json.error, json.code, response.status);
+    }
+    return json.data;
+  }
+  /**
+   * Internal request helper with auth and error handling.
+   */
+  async request(url, options) {
+    const headers = {
+      "Content-Type": "application/json",
+      Accept: "application/json",
+      "X-API-Key": this.apiKey
+    };
+    const response = await fetch(url, {
+      ...options,
+      headers: {
+        ...headers,
+        ...options.headers || {}
+      }
+    });
+    const json = await response.json();
+    if (!json.success) {
+      throw new KeeperBoardError(json.error, json.code, response.status);
+    }
+    return json.data;
+  }
+};
+
+// src/PlayerIdentity.ts
+var DEFAULT_KEY_PREFIX = "keeperboard_";
+var PlayerIdentity = class {
+  constructor(config = {}) {
+    this.keyPrefix = config.keyPrefix ?? DEFAULT_KEY_PREFIX;
+    this.guidKey = `${this.keyPrefix}player_guid`;
+    this.nameKey = `${this.keyPrefix}player_name`;
+  }
+  /**
+   * Get the stored player GUID, or null if none exists.
+   */
+  getPlayerGuid() {
+    if (typeof window === "undefined" || !window.localStorage) {
+      return null;
+    }
+    return localStorage.getItem(this.guidKey);
+  }
+  /**
+   * Set the player GUID in localStorage.
+   */
+  setPlayerGuid(guid) {
+    if (typeof window === "undefined" || !window.localStorage) {
+      return;
+    }
+    localStorage.setItem(this.guidKey, guid);
+  }
+  /**
+   * Get the stored player GUID, creating one if it doesn't exist.
+   * Uses crypto.randomUUID() for generating new GUIDs.
+   */
+  getOrCreatePlayerGuid() {
+    let guid = this.getPlayerGuid();
+    if (!guid) {
+      guid = this.generateUUID();
+      this.setPlayerGuid(guid);
+    }
+    return guid;
+  }
+  /**
+   * Get the stored player name, or null if none exists.
+   */
+  getPlayerName() {
+    if (typeof window === "undefined" || !window.localStorage) {
+      return null;
+    }
+    return localStorage.getItem(this.nameKey);
+  }
+  /**
+   * Set the player name in localStorage.
+   */
+  setPlayerName(name) {
+    if (typeof window === "undefined" || !window.localStorage) {
+      return;
+    }
+    localStorage.setItem(this.nameKey, name);
+  }
+  /**
+   * Clear all stored player identity data.
+   */
+  clear() {
+    if (typeof window === "undefined" || !window.localStorage) {
+      return;
+    }
+    localStorage.removeItem(this.guidKey);
+    localStorage.removeItem(this.nameKey);
+  }
+  /**
+   * Check if player identity is stored.
+   */
+  hasIdentity() {
+    return this.getPlayerGuid() !== null;
+  }
+  /**
+   * Generate a UUID v4.
+   * Uses crypto.randomUUID() if available, otherwise falls back to a manual implementation.
+   */
+  generateUUID() {
+    if (typeof crypto !== "undefined" && crypto.randomUUID) {
+      return crypto.randomUUID();
+    }
+    return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+      const r = Math.random() * 16 | 0;
+      const v = c === "x" ? r : r & 3 | 8;
+      return v.toString(16);
+    });
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  KeeperBoardClient,
+  KeeperBoardError,
+  PlayerIdentity
+});

package/dist/index.mjs

@@ -0,0 +1,267 @@
+// src/types.ts
+var KeeperBoardError = class extends Error {
+  constructor(message, code, statusCode) {
+    super(message);
+    this.code = code;
+    this.statusCode = statusCode;
+    this.name = "KeeperBoardError";
+  }
+};
+
+// src/KeeperBoardClient.ts
+var KeeperBoardClient = class {
+  constructor(config) {
+    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) {
+    const params = new URLSearchParams();
+    if (leaderboardSlug) {
+      params.set("leaderboard", leaderboardSlug);
+    }
+    const url = `${this.apiUrl}/api/v1/scores${params.toString() ? "?" + params.toString() : ""}`;
+    const body = {
+      player_guid: playerGuid,
+      player_name: playerName,
+      score,
+      ...metadata && { metadata }
+    };
+    const response = await 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) {
+    const params = new URLSearchParams();
+    params.set("limit", String(Math.min(limit, 100)));
+    params.set("offset", String(offset));
+    if (leaderboardSlug) {
+      params.set("leaderboard", leaderboardSlug);
+    }
+    const url = `${this.apiUrl}/api/v1/leaderboard?${params.toString()}`;
+    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) {
+    const params = new URLSearchParams();
+    if (leaderboardSlug) {
+      params.set("leaderboard", leaderboardSlug);
+    }
+    const url = `${this.apiUrl}/api/v1/player/${encodeURIComponent(playerGuid)}${params.toString() ? "?" + params.toString() : ""}`;
+    try {
+      return await this.request(url, {
+        method: "GET"
+      });
+    } catch (error) {
+      if (error instanceof KeeperBoardError && error.code === "NOT_FOUND") {
+        return null;
+      }
+      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) {
+    const params = new URLSearchParams();
+    if (leaderboardSlug) {
+      params.set("leaderboard", leaderboardSlug);
+    }
+    const url = `${this.apiUrl}/api/v1/player/${encodeURIComponent(playerGuid)}${params.toString() ? "?" + params.toString() : ""}`;
+    return this.request(url, {
+      method: "PUT",
+      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) {
+    const params = new URLSearchParams();
+    if (leaderboardSlug) {
+      params.set("leaderboard", leaderboardSlug);
+    }
+    const url = `${this.apiUrl}/api/v1/claim${params.toString() ? "?" + params.toString() : ""}`;
+    return this.request(url, {
+      method: "POST",
+      body: JSON.stringify({
+        player_guid: playerGuid,
+        player_name: playerName
+      })
+    });
+  }
+  /**
+   * 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"
+      }
+    });
+    const json = await response.json();
+    if (!json.success) {
+      throw new KeeperBoardError(json.error, json.code, response.status);
+    }
+    return json.data;
+  }
+  /**
+   * Internal request helper with auth and error handling.
+   */
+  async request(url, options) {
+    const headers = {
+      "Content-Type": "application/json",
+      Accept: "application/json",
+      "X-API-Key": this.apiKey
+    };
+    const response = await fetch(url, {
+      ...options,
+      headers: {
+        ...headers,
+        ...options.headers || {}
+      }
+    });
+    const json = await response.json();
+    if (!json.success) {
+      throw new KeeperBoardError(json.error, json.code, response.status);
+    }
+    return json.data;
+  }
+};
+
+// src/PlayerIdentity.ts
+var DEFAULT_KEY_PREFIX = "keeperboard_";
+var PlayerIdentity = class {
+  constructor(config = {}) {
+    this.keyPrefix = config.keyPrefix ?? DEFAULT_KEY_PREFIX;
+    this.guidKey = `${this.keyPrefix}player_guid`;
+    this.nameKey = `${this.keyPrefix}player_name`;
+  }
+  /**
+   * Get the stored player GUID, or null if none exists.
+   */
+  getPlayerGuid() {
+    if (typeof window === "undefined" || !window.localStorage) {
+      return null;
+    }
+    return localStorage.getItem(this.guidKey);
+  }
+  /**
+   * Set the player GUID in localStorage.
+   */
+  setPlayerGuid(guid) {
+    if (typeof window === "undefined" || !window.localStorage) {
+      return;
+    }
+    localStorage.setItem(this.guidKey, guid);
+  }
+  /**
+   * Get the stored player GUID, creating one if it doesn't exist.
+   * Uses crypto.randomUUID() for generating new GUIDs.
+   */
+  getOrCreatePlayerGuid() {
+    let guid = this.getPlayerGuid();
+    if (!guid) {
+      guid = this.generateUUID();
+      this.setPlayerGuid(guid);
+    }
+    return guid;
+  }
+  /**
+   * Get the stored player name, or null if none exists.
+   */
+  getPlayerName() {
+    if (typeof window === "undefined" || !window.localStorage) {
+      return null;
+    }
+    return localStorage.getItem(this.nameKey);
+  }
+  /**
+   * Set the player name in localStorage.
+   */
+  setPlayerName(name) {
+    if (typeof window === "undefined" || !window.localStorage) {
+      return;
+    }
+    localStorage.setItem(this.nameKey, name);
+  }
+  /**
+   * Clear all stored player identity data.
+   */
+  clear() {
+    if (typeof window === "undefined" || !window.localStorage) {
+      return;
+    }
+    localStorage.removeItem(this.guidKey);
+    localStorage.removeItem(this.nameKey);
+  }
+  /**
+   * Check if player identity is stored.
+   */
+  hasIdentity() {
+    return this.getPlayerGuid() !== null;
+  }
+  /**
+   * Generate a UUID v4.
+   * Uses crypto.randomUUID() if available, otherwise falls back to a manual implementation.
+   */
+  generateUUID() {
+    if (typeof crypto !== "undefined" && crypto.randomUUID) {
+      return crypto.randomUUID();
+    }
+    return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+      const r = Math.random() * 16 | 0;
+      const v = c === "x" ? r : r & 3 | 8;
+      return v.toString(16);
+    });
+  }
+};
+export {
+  KeeperBoardClient,
+  KeeperBoardError,
+  PlayerIdentity
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "keeperboard-sdk",
+  "version": "1.0.1",
+  "description": "TypeScript client SDK for KeeperBoard leaderboard-as-a-service",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "leaderboard",
+    "phaser",
+    "game",
+    "scores",
+    "typescript",
+    "sdk",
+    "keeperboard"
+  ],
+  "author": "Claude Roy",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:clauderoy790/keeperboard.git",
+    "directory": "sdk"
+  },
+  "homepage": "https://github.com/clauderoy790/keeperboard#readme",
+  "bugs": {
+    "url": "https://github.com/clauderoy790/keeperboard/issues"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}