keeperboard 1.0.3 → 2.0.0

package/dist/index.d.mts

@@ -1,91 +1,202 @@
 /**
  * Type definitions for KeeperBoard SDK.
- * Matches the API response shapes from the KeeperBoard public API.
+ *
+ * Public types use camelCase. Internal types (prefixed with Api*) match the
+ * snake_case shapes returned by the KeeperBoard REST API and are used only
+ * for deserialization inside the client.
  */
 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;
+    /** Default leaderboard name — used when no leaderboard is specified in method calls */
+    defaultLeaderboard?: string;
+    /** @internal Base URL override for testing. Do not use in production. */
+    apiUrl?: string;
 }
+interface SubmitScoreOptions {
+    playerGuid: string;
+    playerName: string;
+    score: number;
+    /** Leaderboard name. Falls back to `defaultLeaderboard` from config. */
+    leaderboard?: string;
+    metadata?: Record<string, unknown>;
+}
+interface GetLeaderboardOptions {
+    /** Leaderboard name. Falls back to `defaultLeaderboard` from config. */
+    leaderboard?: string;
+    /** Max entries to return (1–100, default 10). */
+    limit?: number;
+    /** Offset for pagination (default 0). */
+    offset?: number;
+    /** Fetch a specific version of a time-based leaderboard. */
+    version?: number;
+}
+interface GetPlayerRankOptions {
+    playerGuid: string;
+    /** Leaderboard name. Falls back to `defaultLeaderboard` from config. */
+    leaderboard?: string;
+}
+interface UpdatePlayerNameOptions {
+    playerGuid: string;
+    newName: string;
+    /** Leaderboard name. Falls back to `defaultLeaderboard` from config. */
+    leaderboard?: string;
+}
+interface ClaimScoreOptions {
+    playerGuid: string;
+    playerName: string;
+    /** Leaderboard name. Falls back to `defaultLeaderboard` from config. */
+    leaderboard?: string;
+}
+interface ScoreResult {
+    id: string;
+    playerGuid: string;
+    playerName: string;
+    score: number;
+    rank: number;
+    isNewHighScore: boolean;
+}
+interface LeaderboardEntry {
+    rank: number;
+    playerGuid: string;
+    playerName: string;
+    score: number;
+}
+/** Reset schedule options for leaderboards */
+type ResetSchedule = 'none' | 'daily' | 'weekly' | 'monthly';
+interface LeaderboardResult {
+    entries: LeaderboardEntry[];
+    totalCount: number;
+    resetSchedule: ResetSchedule;
+    /** Current version number — only present when resetSchedule is not 'none'. */
+    version?: number;
+    /** Oldest available version number — only present when resetSchedule is not 'none'. */
+    oldestVersion?: number;
+    /** ISO timestamp of when the next reset occurs — only present when resetSchedule is not 'none'. */
+    nextReset?: string;
+}
+interface PlayerResult {
+    id: string;
+    playerGuid: string;
+    playerName: string;
+    score: number;
+    rank: number;
+}
+interface ClaimResult {
+    claimed: boolean;
+    score: number;
+    rank: number;
+    playerName: string;
+}
+interface HealthResult {
+    service: string;
+    version: string;
+    timestamp: string;
+}
+interface SessionConfig {
+    /** API key from the KeeperBoard dashboard */
+    apiKey: string;
+    /** Leaderboard name (required — the session is bound to one board) */
+    leaderboard: string;
+    /** PlayerIdentity config for localStorage key prefix */
+    identity?: {
+        keyPrefix?: string;
+    };
+    /** Default player name when none has been set (default: "ANON") */
+    defaultPlayerName?: string;
+    /** TTL cache configuration for getSnapshot() */
+    cache?: {
+        ttlMs: number;
+    };
+    /** Retry queue configuration for failed score submissions */
+    retry?: {
+        maxAgeMs?: number;
+    };
+    /** @internal Base URL override for testing. */
+    apiUrl?: string;
+}
+type SessionScoreResult = {
+    success: true;
+    rank: number;
+    isNewHighScore: boolean;
+} | {
+    success: false;
+    error: string;
+};
+interface SnapshotEntry {
+    rank: number;
+    playerGuid: string;
+    playerName: string;
+    score: number;
+    isCurrentPlayer: boolean;
+}
+interface SnapshotResult {
+    entries: SnapshotEntry[];
+    totalCount: number;
+    /** Player's own rank info — included only when the player is outside the top N. */
+    playerRank: PlayerResult | null;
+}
+interface NameValidationOptions {
+    /** Minimum length after sanitization (default 2). */
+    minLength?: number;
+    /** Maximum length — input is truncated to this (default 12). */
+    maxLength?: number;
+    /** Convert to uppercase (default true). */
+    uppercase?: boolean;
+    /** Regex of allowed characters applied after case conversion (default /[^A-Z0-9_]/g removes non-matching). */
+    allowedPattern?: RegExp;
+}
+/** @internal */
 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>;
 }
-/** Reset schedule options for leaderboards */
-type ResetSchedule = 'none' | 'daily' | 'weekly' | 'monthly';
-interface ScoreResponse {
-    /** Score ID in the database */
+/** @internal */
+interface ApiScoreResponse {
     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) */
+/** @internal */
+interface ApiLeaderboardEntry {
     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 in this version/period */
+/** @internal */
+interface ApiLeaderboardResponse {
+    entries: ApiLeaderboardEntry[];
     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 */
+/** @internal */
+interface ApiPlayerResponse {
     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 */
+/** @internal */
+interface ApiClaimResponse {
     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 */
+/** @internal */
+interface ApiHealthResponse {
     service: string;
-    /** API version */
     version: string;
-    /** Server timestamp */
     timestamp: string;
 }
 declare class KeeperBoardError extends Error {
@@ -93,114 +204,155 @@ declare class KeeperBoardError extends Error {
     readonly statusCode: number;
     constructor(message: string, code: string, statusCode: number);
 }
+/** @deprecated Use `ApiScoreResponse` (internal) or `ScoreResult` (public). */
+type ScoreResponse = ApiScoreResponse;
+/** @deprecated Use `ApiLeaderboardResponse` (internal) or `LeaderboardResult` (public). */
+type LeaderboardResponse = ApiLeaderboardResponse;
+/** @deprecated Use `ApiPlayerResponse` (internal) or `PlayerResult` (public). */
+type PlayerResponse = ApiPlayerResponse;
+/** @deprecated Use `ApiClaimResponse` (internal) or `ClaimResult` (public). */
+type ClaimResponse = ApiClaimResponse;
+/** @deprecated Use `ApiHealthResponse` (internal) or `HealthResult` (public). */
+type HealthResponse = ApiHealthResponse;
 
 /**
  * KeeperBoard API client for TypeScript/JavaScript games.
  * Works in any browser environment using the fetch API.
+ *
+ * All public methods accept options objects and return camelCase results.
+ * A `defaultLeaderboard` can be set in the config to avoid passing it every call.
  */
 
 declare class KeeperBoardClient {
+    private static readonly DEFAULT_API_URL;
     private readonly apiUrl;
     private readonly apiKey;
+    private readonly defaultLeaderboard?;
     constructor(config: KeeperBoardConfig);
     /**
-     * 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).
+     * Submit a score. Only updates if the new score is higher than the existing one.
      *
      * @example
-     * const lb = await client.getLeaderboard();
+     * const result = await client.submitScore({
+     *   playerGuid: 'abc-123',
+     *   playerName: 'ACE',
+     *   score: 1500,
+     * });
+     * console.log(result.rank, result.isNewHighScore);
      */
-    getLeaderboard(): Promise<LeaderboardResponse>;
+    submitScore(options: SubmitScoreOptions): Promise<ScoreResult>;
     /**
-     * Get a specific leaderboard by name (top 10 entries).
+     * Get a leaderboard. Supports pagination and version-based lookups for
+     * time-based boards.
      *
      * @example
-     * const lb = await client.getLeaderboard('Weekly Best');
-     */
-    getLeaderboard(name: string): Promise<LeaderboardResponse>;
-    /**
-     * Get a leaderboard with custom limit.
+     * // Top 10 on default board
+     * const lb = await client.getLeaderboard();
      *
-     * @example
-     * const lb = await client.getLeaderboard('Weekly Best', 25);
+     * // Top 25 on a specific board
+     * const lb = await client.getLeaderboard({ leaderboard: 'Weekly', limit: 25 });
+     *
+     * // Historical version
+     * const lb = await client.getLeaderboard({ leaderboard: 'Weekly', version: 3 });
      */
-    getLeaderboard(name: string, limit: number): Promise<LeaderboardResponse>;
+    getLeaderboard(options?: GetLeaderboardOptions): Promise<LeaderboardResult>;
     /**
-     * Get a leaderboard with pagination.
+     * Get a player's rank and score. Returns `null` if the player has no score.
      *
      * @example
-     * const page2 = await client.getLeaderboard('Weekly Best', 10, 10);
+     * const player = await client.getPlayerRank({ playerGuid: 'abc-123' });
+     * if (player) console.log(`Rank #${player.rank}`);
      */
-    getLeaderboard(name: string, limit: number, offset: number): Promise<LeaderboardResponse>;
+    getPlayerRank(options: GetPlayerRankOptions): Promise<PlayerResult | null>;
     /**
-     * Get a specific version of a time-based leaderboard.
+     * Update a player's display name.
      *
      * @example
-     * // Get last week's leaderboard (version 3)
-     * const lastWeek = await client.getLeaderboardVersion('Weekly Best', 3);
+     * const player = await client.updatePlayerName({
+     *   playerGuid: 'abc-123',
+     *   newName: 'MAVERICK',
+     * });
      */
-    getLeaderboardVersion(name: string, version: number): Promise<LeaderboardResponse>;
+    updatePlayerName(options: UpdatePlayerNameOptions): Promise<PlayerResult>;
     /**
-     * Get a specific version with custom limit.
+     * Claim a migrated score by matching player name.
+     * Used when scores were imported without player GUIDs.
      */
-    getLeaderboardVersion(name: string, version: number, limit: number): Promise<LeaderboardResponse>;
+    claimScore(options: ClaimScoreOptions): Promise<ClaimResult>;
     /**
-     * Get a specific version with pagination.
+     * Check if the API is healthy. Does not require an API key.
      */
-    getLeaderboardVersion(name: string, version: number, limit: number, offset: number): Promise<LeaderboardResponse>;
+    healthCheck(): Promise<HealthResult>;
+    private mapScoreResponse;
+    private mapLeaderboardResponse;
+    private mapPlayerResponse;
+    private mapClaimResponse;
+    private request;
+}
+
+/**
+ * High-level KeeperBoard API for browser games.
+ * Wraps KeeperBoardClient with automatic identity management, caching,
+ * retry queue, and name validation.
+ *
+ * Recommended for most consumers. For server-side or advanced use,
+ * use KeeperBoardClient directly.
+ */
+
+declare class KeeperBoardSession {
+    private readonly client;
+    private readonly identity;
+    private readonly leaderboard;
+    private readonly defaultPlayerName;
+    private readonly cache;
+    private readonly retryQueue;
+    private isSubmitting;
+    constructor(config: SessionConfig);
+    /** Get or create a persistent player GUID. */
+    getPlayerGuid(): string;
+    /** Get the stored player name, falling back to defaultPlayerName. */
+    getPlayerName(): string;
+    /** Store a player name locally. Does NOT update the server — call updatePlayerName() for that. */
+    setPlayerName(name: string): void;
+    /** Validate a name using configurable rules. Returns sanitized string or null. */
+    validateName(input: string, options?: NameValidationOptions): string | null;
     /**
-     * Get a player's rank and score on the default leaderboard.
-     * Returns null if the player has no score.
+     * Submit a score. Identity and leaderboard are auto-injected.
+     * Returns a discriminated union: `{ success: true, rank, isNewHighScore }` or `{ success: false, error }`.
      *
-     * @example
-     * const player = await client.getPlayerRank(playerGuid);
-     * if (player) {
-     *   console.log(`You are ranked #${player.rank}`);
-     * }
-     */
-    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.
+     * If retry is enabled, failed submissions are saved to localStorage for later retry.
+     * Prevents concurrent double-submissions.
      */
-    getPlayerRank(playerGuid: string, leaderboard: string): Promise<PlayerResponse | null>;
+    submitScore(score: number, metadata?: Record<string, unknown>): Promise<SessionScoreResult>;
     /**
-     * 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.
+     * Get a combined snapshot: leaderboard entries (with `isCurrentPlayer` flag)
+     * plus the current player's rank if they're outside the top N.
+     *
+     * Uses cache if enabled and fresh.
      */
-    updatePlayerName(playerGuid: string, newName: string, leaderboard: string): Promise<PlayerResponse>;
+    getSnapshot(options?: {
+        limit?: number;
+    }): Promise<SnapshotResult>;
     /**
-     * Claim a migrated score by matching player name.
-     * Used when scores were imported without player GUIDs.
+     * Update the player's name on the server and locally.
+     * Returns true on success, false on failure.
      */
-    claimScore(playerGuid: string, playerName: string): Promise<ClaimResponse>;
+    updatePlayerName(newName: string): Promise<boolean>;
     /**
-     * Claim a migrated score on a specific leaderboard.
+     * Retry submitting a pending score (from a previous failed submission).
+     * Call this on app startup.
      */
-    claimScore(playerGuid: string, playerName: string, leaderboard: string): Promise<ClaimResponse>;
+    retryPendingScore(): Promise<SessionScoreResult | null>;
+    /** Check if there's a pending score in the retry queue. */
+    hasPendingScore(): boolean;
     /**
-     * Check if the API is healthy.
-     * This endpoint does not require an API key.
+     * Pre-fetch snapshot data in the background for instant display later.
+     * No-op if cache is disabled or already fresh.
      */
-    healthCheck(): Promise<HealthResponse>;
-    private request;
+    prefetch(): void;
+    /** Escape hatch: access the underlying KeeperBoardClient. */
+    getClient(): KeeperBoardClient;
+    private fetchSnapshot;
 }
 
 /**
@@ -252,4 +404,78 @@ declare class PlayerIdentity {
     private generateUUID;
 }
 
-export { type ClaimResponse, type HealthResponse, KeeperBoardClient, type KeeperBoardConfig, KeeperBoardError, type LeaderboardEntry, type LeaderboardResponse, PlayerIdentity, type PlayerIdentityConfig, type PlayerResponse, type ResetSchedule, type ScoreResponse, type ScoreSubmission };
+/**
+ * Pure-function name validation with configurable rules.
+ * Returns the sanitized name or null if invalid after sanitization.
+ */
+
+/**
+ * Validate and sanitize a player name.
+ *
+ * 1. Trims whitespace
+ * 2. Optionally converts to uppercase (default: yes)
+ * 3. Strips characters not matching `allowedPattern`
+ * 4. Truncates to `maxLength`
+ * 5. Returns `null` if result is shorter than `minLength`
+ *
+ * @example
+ * validateName('  Ace Pilot! ')  // 'ACE_PILOT' → wait, no spaces allowed → 'ACEPILOT'
+ * validateName('ab')             // 'AB'
+ * validateName('x')              // null (too short)
+ */
+declare function validateName(input: string, options?: NameValidationOptions): string | null;
+
+/**
+ * Generic TTL cache with in-flight deduplication and background refresh.
+ */
+declare class Cache<T> {
+    private data;
+    private fetchedAt;
+    private inflight;
+    private readonly ttlMs;
+    constructor(ttlMs: number);
+    /**
+     * Get cached value if fresh, otherwise fetch via the provided function.
+     * Deduplicates concurrent calls — only one fetch runs at a time.
+     */
+    getOrFetch(fetchFn: () => Promise<T>): Promise<T>;
+    /**
+     * Trigger a background refresh without awaiting the result.
+     * Returns immediately. If a fetch is already in flight, does nothing.
+     */
+    refreshInBackground(fetchFn: () => Promise<T>): void;
+    /** Invalidate the cache, forcing the next getOrFetch to re-fetch. */
+    invalidate(): void;
+    /** Get the cached value without fetching. Returns undefined if empty or stale. */
+    get(): T | undefined;
+    /** Get the cached value even if stale. Returns undefined only if never fetched. */
+    getStale(): T | undefined;
+    /** Check if the cache has fresh (non-expired) data. */
+    isFresh(): boolean;
+}
+
+/**
+ * localStorage-based retry queue for failed score submissions.
+ * Persists a single pending score and auto-expires after maxAge.
+ */
+declare class RetryQueue {
+    private readonly storageKey;
+    private readonly maxAgeMs;
+    constructor(storageKey: string, maxAgeMs?: number);
+    /** Save a failed score for later retry. */
+    save(score: number, metadata?: Record<string, unknown>): void;
+    /**
+     * Get the pending score, or null if none exists or it has expired.
+     * Automatically clears expired entries.
+     */
+    get(): {
+        score: number;
+        metadata?: Record<string, unknown>;
+    } | null;
+    /** Check if there's a pending score. */
+    hasPending(): boolean;
+    /** Clear the pending score. */
+    clear(): void;
+}
+
+export { Cache, type ClaimResponse, type ClaimResult, type ClaimScoreOptions, type GetLeaderboardOptions, type GetPlayerRankOptions, type HealthResponse, type HealthResult, KeeperBoardClient, type KeeperBoardConfig, KeeperBoardError, KeeperBoardSession, type LeaderboardEntry, type LeaderboardResponse, type LeaderboardResult, type NameValidationOptions, PlayerIdentity, type PlayerIdentityConfig, type PlayerResponse, type PlayerResult, type ResetSchedule, RetryQueue, type ScoreResponse, type ScoreResult, type ScoreSubmission, type SessionConfig, type SessionScoreResult, type SnapshotEntry, type SnapshotResult, type SubmitScoreOptions, type UpdatePlayerNameOptions, validateName };