keeperboard 2.0.0 → 2.0.2

package/README.md

@@ -52,7 +52,6 @@ Most browser games should use `KeeperBoardSession`. Use `KeeperBoardClient` for
 const session = new KeeperBoardSession({
   apiKey: 'kb_dev_xxx',           // Required
   leaderboard: 'main',            // Required - session is bound to one board
-  defaultPlayerName: 'ANON',      // Optional (default: 'ANON')
   identity: { keyPrefix: 'app_' }, // Optional localStorage prefix
   cache: { ttlMs: 30000 },        // Optional TTL cache for getSnapshot()
   retry: { maxAgeMs: 86400000 },  // Optional retry queue for failed submissions
@@ -61,10 +60,13 @@ const session = new KeeperBoardSession({
 
 ### Identity (auto-managed)
 
+Player names are auto-generated on first access (e.g., `BOLDFALCON`, `SWIFTPANDA`). Players can override with `setPlayerName()`.
+
 ```typescript
 session.getPlayerGuid();     // Get or create persistent GUID
-session.getPlayerName();     // Get stored name or default
+session.getPlayerName();     // Get stored name (auto-generated if first time)
 session.setPlayerName(name); // Store name locally (doesn't update server)
+session.hasExplicitPlayerName(); // true if player chose their name
 
 // Validate a name (pure function)
 const validated = session.validateName('  Ace Pilot! ');
@@ -271,6 +273,16 @@ class GameOverScene extends Phaser.Scene {
 
 ## Utilities
 
+### generatePlayerName
+
+Generate random AdjectiveNoun player names:
+
+```typescript
+import { generatePlayerName } from 'keeperboard';
+
+const name = generatePlayerName(); // 'BOLDFALCON', 'SWIFTPANDA', etc.
+```
+
 ### PlayerIdentity
 
 Standalone helper for localStorage identity management:

package/dist/index.d.mts

@@ -102,8 +102,6 @@ interface SessionConfig {
     identity?: {
         keyPrefix?: string;
     };
-    /** Default player name when none has been set (default: "ANON") */
-    defaultPlayerName?: string;
     /** TTL cache configuration for getSnapshot() */
     cache?: {
         ttlMs: number;
@@ -303,17 +301,19 @@ declare class KeeperBoardSession {
     private readonly client;
     private readonly identity;
     private readonly leaderboard;
-    private readonly defaultPlayerName;
     private readonly cache;
     private readonly retryQueue;
+    private cachedLimit;
     private isSubmitting;
     constructor(config: SessionConfig);
     /** Get or create a persistent player GUID. */
     getPlayerGuid(): string;
-    /** Get the stored player name, falling back to defaultPlayerName. */
+    /** Get the stored player name, auto-generating one if none exists. */
     getPlayerName(): string;
     /** Store a player name locally. Does NOT update the server — call updatePlayerName() for that. */
     setPlayerName(name: string): void;
+    /** Check if the player has explicitly set a name (vs auto-generated). */
+    hasExplicitPlayerName(): boolean;
     /** Validate a name using configurable rules. Returns sanitized string or null. */
     validateName(input: string, options?: NameValidationOptions): string | null;
     /**
@@ -328,7 +328,8 @@ declare class KeeperBoardSession {
      * 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.
+     * Uses cache if enabled and fresh. If a larger limit is requested than
+     * what's cached, the cache is invalidated and fresh data is fetched.
      */
     getSnapshot(options?: {
         limit?: number;
@@ -367,6 +368,7 @@ declare class PlayerIdentity {
     private readonly keyPrefix;
     private readonly guidKey;
     private readonly nameKey;
+    private readonly nameAutoKey;
     constructor(config?: PlayerIdentityConfig);
     /**
      * Get the stored player GUID, or null if none exists.
@@ -389,6 +391,15 @@ declare class PlayerIdentity {
      * Set the player name in localStorage.
      */
     setPlayerName(name: string): void;
+    /**
+     * Get the stored player name, creating an auto-generated one if it doesn't exist.
+     * Uses AdjectiveNounNumber pattern (e.g., ArcaneBlob99).
+     */
+    getOrCreatePlayerName(): string;
+    /**
+     * Check if the current player name was auto-generated (vs explicitly set by user).
+     */
+    isAutoGeneratedName(): boolean;
     /**
      * Clear all stored player identity data.
      */
@@ -425,13 +436,35 @@ declare class PlayerIdentity {
  */
 declare function validateName(input: string, options?: NameValidationOptions): string | null;
 
+/**
+ * Auto-generated player name system.
+ * Generates random AdjectiveNounNumber names (e.g., ArcaneBlob99).
+ * Names are PascalCase words plus a numeric suffix, and fit within 4-12 characters.
+ */
+/**
+ * Generate a random player name in the format AdjectiveNoun1-99.
+ * Returns a PascalCase string with length 4-12 characters (fits validateName rules).
+ * ~990,000 unique combinations possible.
+ *
+ * @example
+ * generatePlayerName() // 'ArcaneBlob99'
+ * generatePlayerName() // 'CosmicViper42'
+ */
+declare function generatePlayerName(): string;
+
 /**
  * Generic TTL cache with in-flight deduplication and background refresh.
+ *
+ * Features:
+ * - TTL-based expiration
+ * - In-flight request deduplication
+ * - Background refresh scheduling (handles concurrent refresh requests)
  */
 declare class Cache<T> {
     private data;
     private fetchedAt;
     private inflight;
+    private pendingRefresh;
     private readonly ttlMs;
     constructor(ttlMs: number);
     /**
@@ -441,9 +474,11 @@ declare class Cache<T> {
     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.
+     * Returns immediately. If a fetch is already in flight, schedules
+     * the refresh to run after the current one completes.
      */
     refreshInBackground(fetchFn: () => Promise<T>): void;
+    private startBackgroundFetch;
     /** Invalidate the cache, forcing the next getOrFetch to re-fetch. */
     invalidate(): void;
     /** Get the cached value without fetching. Returns undefined if empty or stale. */
@@ -478,4 +513,4 @@ declare class RetryQueue {
     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 };
+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, generatePlayerName, validateName };

package/dist/index.d.ts

@@ -102,8 +102,6 @@ interface SessionConfig {
     identity?: {
         keyPrefix?: string;
     };
-    /** Default player name when none has been set (default: "ANON") */
-    defaultPlayerName?: string;
     /** TTL cache configuration for getSnapshot() */
     cache?: {
         ttlMs: number;
@@ -303,17 +301,19 @@ declare class KeeperBoardSession {
     private readonly client;
     private readonly identity;
     private readonly leaderboard;
-    private readonly defaultPlayerName;
     private readonly cache;
     private readonly retryQueue;
+    private cachedLimit;
     private isSubmitting;
     constructor(config: SessionConfig);
     /** Get or create a persistent player GUID. */
     getPlayerGuid(): string;
-    /** Get the stored player name, falling back to defaultPlayerName. */
+    /** Get the stored player name, auto-generating one if none exists. */
     getPlayerName(): string;
     /** Store a player name locally. Does NOT update the server — call updatePlayerName() for that. */
     setPlayerName(name: string): void;
+    /** Check if the player has explicitly set a name (vs auto-generated). */
+    hasExplicitPlayerName(): boolean;
     /** Validate a name using configurable rules. Returns sanitized string or null. */
     validateName(input: string, options?: NameValidationOptions): string | null;
     /**
@@ -328,7 +328,8 @@ declare class KeeperBoardSession {
      * 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.
+     * Uses cache if enabled and fresh. If a larger limit is requested than
+     * what's cached, the cache is invalidated and fresh data is fetched.
      */
     getSnapshot(options?: {
         limit?: number;
@@ -367,6 +368,7 @@ declare class PlayerIdentity {
     private readonly keyPrefix;
     private readonly guidKey;
     private readonly nameKey;
+    private readonly nameAutoKey;
     constructor(config?: PlayerIdentityConfig);
     /**
      * Get the stored player GUID, or null if none exists.
@@ -389,6 +391,15 @@ declare class PlayerIdentity {
      * Set the player name in localStorage.
      */
     setPlayerName(name: string): void;
+    /**
+     * Get the stored player name, creating an auto-generated one if it doesn't exist.
+     * Uses AdjectiveNounNumber pattern (e.g., ArcaneBlob99).
+     */
+    getOrCreatePlayerName(): string;
+    /**
+     * Check if the current player name was auto-generated (vs explicitly set by user).
+     */
+    isAutoGeneratedName(): boolean;
     /**
      * Clear all stored player identity data.
      */
@@ -425,13 +436,35 @@ declare class PlayerIdentity {
  */
 declare function validateName(input: string, options?: NameValidationOptions): string | null;
 
+/**
+ * Auto-generated player name system.
+ * Generates random AdjectiveNounNumber names (e.g., ArcaneBlob99).
+ * Names are PascalCase words plus a numeric suffix, and fit within 4-12 characters.
+ */
+/**
+ * Generate a random player name in the format AdjectiveNoun1-99.
+ * Returns a PascalCase string with length 4-12 characters (fits validateName rules).
+ * ~990,000 unique combinations possible.
+ *
+ * @example
+ * generatePlayerName() // 'ArcaneBlob99'
+ * generatePlayerName() // 'CosmicViper42'
+ */
+declare function generatePlayerName(): string;
+
 /**
  * Generic TTL cache with in-flight deduplication and background refresh.
+ *
+ * Features:
+ * - TTL-based expiration
+ * - In-flight request deduplication
+ * - Background refresh scheduling (handles concurrent refresh requests)
  */
 declare class Cache<T> {
     private data;
     private fetchedAt;
     private inflight;
+    private pendingRefresh;
     private readonly ttlMs;
     constructor(ttlMs: number);
     /**
@@ -441,9 +474,11 @@ declare class Cache<T> {
     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.
+     * Returns immediately. If a fetch is already in flight, schedules
+     * the refresh to run after the current one completes.
      */
     refreshInBackground(fetchFn: () => Promise<T>): void;
+    private startBackgroundFetch;
     /** Invalidate the cache, forcing the next getOrFetch to re-fetch. */
     invalidate(): void;
     /** Get the cached value without fetching. Returns undefined if empty or stale. */
@@ -478,4 +513,4 @@ declare class RetryQueue {
     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 };
+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, generatePlayerName, validateName };

package/dist/index.js

@@ -26,6 +26,7 @@ __export(index_exports, {
   KeeperBoardSession: () => KeeperBoardSession,
   PlayerIdentity: () => PlayerIdentity,
   RetryQueue: () => RetryQueue,
+  generatePlayerName: () => generatePlayerName,
   validateName: () => validateName
 });
 module.exports = __toCommonJS(index_exports);
@@ -261,6 +262,220 @@ var _KeeperBoardClient = class _KeeperBoardClient {
 _KeeperBoardClient.DEFAULT_API_URL = "https://keeperboard.vercel.app";
 var KeeperBoardClient = _KeeperBoardClient;
 
+// src/nameGenerator.ts
+var MAX_BASE_LENGTH = 10;
+var ADJECTIVES = [
+  "Arcane",
+  "Astro",
+  "Blazing",
+  "Bouncy",
+  "Brassy",
+  "Brisk",
+  "Bubbly",
+  "Chaotic",
+  "Cheeky",
+  "Chill",
+  "Chunky",
+  "Cloaked",
+  "Cosmic",
+  "Crimson",
+  "Crispy",
+  "Dashing",
+  "Dizzy",
+  "Dynamic",
+  "Electric",
+  "Epic",
+  "Feisty",
+  "Fiery",
+  "Flashy",
+  "Frosty",
+  "Funky",
+  "Furious",
+  "Galactic",
+  "Glitchy",
+  "Golden",
+  "Goofy",
+  "Gritty",
+  "Groovy",
+  "Hyper",
+  "Icy",
+  "Inky",
+  "Jazzy",
+  "Jolly",
+  "Jumpy",
+  "Laser",
+  "Legendary",
+  "Loud",
+  "Lucky",
+  "Lunar",
+  "Madcap",
+  "Magic",
+  "Majestic",
+  "Meteor",
+  "Mighty",
+  "Minty",
+  "Mystic",
+  "Neon",
+  "Nimble",
+  "Nova",
+  "Nuclear",
+  "Omega",
+  "Orbital",
+  "Peppy",
+  "Phantom",
+  "Pixel",
+  "Plasma",
+  "Polished",
+  "Primal",
+  "Quantum",
+  "Quick",
+  "Radiant",
+  "Rampaging",
+  "Razor",
+  "Rebel",
+  "Retro",
+  "Rogue",
+  "Rowdy",
+  "Savage",
+  "Shadow",
+  "Shiny",
+  "Silly",
+  "Sketchy",
+  "Skybound",
+  "Slick",
+  "Snappy",
+  "Solar",
+  "Sonic",
+  "Sparky",
+  "Speedy",
+  "Spiky",
+  "Starry",
+  "Stealthy",
+  "Stormy",
+  "Supreme",
+  "Swift",
+  "Thunder",
+  "Turbo",
+  "Twilight",
+  "Ultra",
+  "Vibrant",
+  "Warped",
+  "Wicked",
+  "Wild",
+  "Wizard",
+  "Zappy",
+  "Zesty"
+];
+var NOUNS = [
+  "Aardvark",
+  "Asteroid",
+  "Badger",
+  "Bandit",
+  "Banshee",
+  "Beacon",
+  "Beetle",
+  "Blaster",
+  "Blob",
+  "Boomer",
+  "Bot",
+  "Brawler",
+  "Buccaneer",
+  "Buffalo",
+  "Cannon",
+  "Captain",
+  "Caribou",
+  "Charger",
+  "Cheetah",
+  "Chimera",
+  "Cobra",
+  "Comet",
+  "Cosmonaut",
+  "Cougar",
+  "Coyote",
+  "Cyborg",
+  "Dagger",
+  "Defender",
+  "Dino",
+  "Dragon",
+  "Drifter",
+  "Drone",
+  "Duck",
+  "Eagle",
+  "Eel",
+  "Falcon",
+  "Ferret",
+  "Fireball",
+  "Fox",
+  "Fury",
+  "Gazelle",
+  "Ghost",
+  "Gizmo",
+  "Gladiator",
+  "Goblin",
+  "Griffin",
+  "Hammer",
+  "Hawk",
+  "Hero",
+  "Hydra",
+  "Iguana",
+  "Jaguar",
+  "Jester",
+  "Jetpack",
+  "Jinx",
+  "Kangaroo",
+  "Katana",
+  "Kraken",
+  "Lancer",
+  "Laser",
+  "Legend",
+  "Lemur",
+  "Leopard",
+  "Lion",
+  "Luchador",
+  "Lynx",
+  "Maverick",
+  "Meteor",
+  "Monkey",
+  "Monsoon",
+  "Moose",
+  "Ninja",
+  "Nova",
+  "Octopus",
+  "Oracle",
+  "Otter",
+  "Panther",
+  "Phoenix",
+  "Pirate",
+  "Pixel",
+  "Puma",
+  "Quasar",
+  "Racer",
+  "Raptor",
+  "Raven",
+  "Reactor",
+  "Rocket",
+  "Ronin",
+  "Saber",
+  "Scorpion",
+  "Shark",
+  "Spartan",
+  "Sphinx",
+  "Sprinter",
+  "Stallion",
+  "Tiger",
+  "Titan",
+  "Viking",
+  "Viper",
+  "Wizard"
+];
+function generatePlayerName() {
+  const adjective = ADJECTIVES[Math.floor(Math.random() * ADJECTIVES.length)];
+  const noun = NOUNS[Math.floor(Math.random() * NOUNS.length)];
+  const number = Math.floor(Math.random() * 99) + 1;
+  const base = (adjective + noun).slice(0, MAX_BASE_LENGTH);
+  return `${base}${number}`;
+}
+
 // src/PlayerIdentity.ts
 var DEFAULT_KEY_PREFIX = "keeperboard_";
 var PlayerIdentity = class {
@@ -268,6 +483,7 @@ var PlayerIdentity = class {
     this.keyPrefix = config.keyPrefix ?? DEFAULT_KEY_PREFIX;
     this.guidKey = `${this.keyPrefix}player_guid`;
     this.nameKey = `${this.keyPrefix}player_name`;
+    this.nameAutoKey = `${this.keyPrefix}player_name_auto`;
   }
   /**
    * Get the stored player GUID, or null if none exists.
@@ -316,6 +532,31 @@ var PlayerIdentity = class {
       return;
     }
     localStorage.setItem(this.nameKey, name);
+    localStorage.removeItem(this.nameAutoKey);
+  }
+  /**
+   * Get the stored player name, creating an auto-generated one if it doesn't exist.
+   * Uses AdjectiveNounNumber pattern (e.g., ArcaneBlob99).
+   */
+  getOrCreatePlayerName() {
+    let name = this.getPlayerName();
+    if (!name) {
+      name = generatePlayerName();
+      if (typeof window !== "undefined" && window.localStorage) {
+        localStorage.setItem(this.nameKey, name);
+        localStorage.setItem(this.nameAutoKey, "true");
+      }
+    }
+    return name;
+  }
+  /**
+   * Check if the current player name was auto-generated (vs explicitly set by user).
+   */
+  isAutoGeneratedName() {
+    if (typeof window === "undefined" || !window.localStorage) {
+      return false;
+    }
+    return localStorage.getItem(this.nameAutoKey) === "true";
   }
   /**
    * Clear all stored player identity data.
@@ -326,6 +567,7 @@ var PlayerIdentity = class {
     }
     localStorage.removeItem(this.guidKey);
     localStorage.removeItem(this.nameKey);
+    localStorage.removeItem(this.nameAutoKey);
   }
   /**
    * Check if player identity is stored.
@@ -354,6 +596,7 @@ var Cache = class {
   constructor(ttlMs) {
     this.fetchedAt = 0;
     this.inflight = null;
+    this.pendingRefresh = null;
     this.ttlMs = ttlMs;
   }
   /**
@@ -380,17 +623,30 @@ var Cache = class {
   }
   /**
    * Trigger a background refresh without awaiting the result.
-   * Returns immediately. If a fetch is already in flight, does nothing.
+   * Returns immediately. If a fetch is already in flight, schedules
+   * the refresh to run after the current one completes.
    */
   refreshInBackground(fetchFn) {
-    if (this.inflight) return;
+    if (this.inflight) {
+      this.pendingRefresh = fetchFn;
+      return;
+    }
+    this.startBackgroundFetch(fetchFn);
+  }
+  startBackgroundFetch(fetchFn) {
     this.inflight = fetchFn().then((result) => {
       this.data = result;
       this.fetchedAt = Date.now();
       this.inflight = null;
+      if (this.pendingRefresh) {
+        const pending = this.pendingRefresh;
+        this.pendingRefresh = null;
+        this.startBackgroundFetch(pending);
+      }
       return result;
     }).catch((err) => {
       this.inflight = null;
+      this.pendingRefresh = null;
       throw err;
     });
     this.inflight.catch(() => {
@@ -473,7 +729,8 @@ function validateName(input, options) {
   if (opts.uppercase) {
     name = name.toUpperCase();
   }
-  name = name.replace(opts.allowedPattern, "");
+  const pattern = options?.allowedPattern ?? (opts.uppercase ? /[^A-Z0-9_]/g : /[^A-Za-z0-9_]/g);
+  name = name.replace(pattern, "");
   name = name.substring(0, opts.maxLength);
   if (name.length < opts.minLength) {
     return null;
@@ -484,6 +741,8 @@ function validateName(input, options) {
 // src/KeeperBoardSession.ts
 var KeeperBoardSession = class {
   constructor(config) {
+    this.cachedLimit = 0;
+    // Track the limit used for cached data
     this.isSubmitting = false;
     this.client = new KeeperBoardClient({
       apiKey: config.apiKey,
@@ -492,7 +751,6 @@ var KeeperBoardSession = class {
     });
     this.identity = new PlayerIdentity(config.identity);
     this.leaderboard = config.leaderboard;
-    this.defaultPlayerName = config.defaultPlayerName ?? "ANON";
     this.cache = config.cache ? new Cache(config.cache.ttlMs) : null;
     this.retryQueue = config.retry ? new RetryQueue(
       `keeperboard_retry_${config.leaderboard}`,
@@ -506,14 +764,18 @@ var KeeperBoardSession = class {
   getPlayerGuid() {
     return this.identity.getOrCreatePlayerGuid();
   }
-  /** Get the stored player name, falling back to defaultPlayerName. */
+  /** Get the stored player name, auto-generating one if none exists. */
   getPlayerName() {
-    return this.identity.getPlayerName() ?? this.defaultPlayerName;
+    return this.identity.getOrCreatePlayerName();
   }
   /** Store a player name locally. Does NOT update the server — call updatePlayerName() for that. */
   setPlayerName(name) {
     this.identity.setPlayerName(name);
   }
+  /** Check if the player has explicitly set a name (vs auto-generated). */
+  hasExplicitPlayerName() {
+    return this.identity.getPlayerName() !== null && !this.identity.isAutoGeneratedName();
+  }
   /** Validate a name using configurable rules. Returns sanitized string or null. */
   validateName(input, options) {
     return validateName(input, options);
@@ -543,6 +805,7 @@ var KeeperBoardSession = class {
       this.retryQueue?.clear();
       if (this.cache) {
         this.cache.invalidate();
+        this.cachedLimit = 0;
         this.cache.refreshInBackground(() => this.fetchSnapshot());
       }
       return {
@@ -564,12 +827,18 @@ var KeeperBoardSession = class {
    * 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.
+   * Uses cache if enabled and fresh. If a larger limit is requested than
+   * what's cached, the cache is invalidated and fresh data is fetched.
    */
   async getSnapshot(options) {
     const limit = options?.limit ?? 10;
     if (this.cache) {
-      return this.cache.getOrFetch(() => this.fetchSnapshot(limit));
+      if (limit > this.cachedLimit) {
+        this.cache.invalidate();
+      }
+      const result = await this.cache.getOrFetch(() => this.fetchSnapshot(limit));
+      this.cachedLimit = limit;
+      return result;
     }
     return this.fetchSnapshot(limit);
   }
@@ -584,7 +853,10 @@ var KeeperBoardSession = class {
         newName
       });
       this.identity.setPlayerName(newName);
-      this.cache?.invalidate();
+      if (this.cache) {
+        this.cache.invalidate();
+        this.cachedLimit = 0;
+      }
       return true;
     } catch {
       return false;
@@ -653,5 +925,6 @@ var KeeperBoardSession = class {
   KeeperBoardSession,
   PlayerIdentity,
   RetryQueue,
+  generatePlayerName,
   validateName
 });

package/dist/index.mjs

@@ -229,6 +229,220 @@ var _KeeperBoardClient = class _KeeperBoardClient {
 _KeeperBoardClient.DEFAULT_API_URL = "https://keeperboard.vercel.app";
 var KeeperBoardClient = _KeeperBoardClient;
 
+// src/nameGenerator.ts
+var MAX_BASE_LENGTH = 10;
+var ADJECTIVES = [
+  "Arcane",
+  "Astro",
+  "Blazing",
+  "Bouncy",
+  "Brassy",
+  "Brisk",
+  "Bubbly",
+  "Chaotic",
+  "Cheeky",
+  "Chill",
+  "Chunky",
+  "Cloaked",
+  "Cosmic",
+  "Crimson",
+  "Crispy",
+  "Dashing",
+  "Dizzy",
+  "Dynamic",
+  "Electric",
+  "Epic",
+  "Feisty",
+  "Fiery",
+  "Flashy",
+  "Frosty",
+  "Funky",
+  "Furious",
+  "Galactic",
+  "Glitchy",
+  "Golden",
+  "Goofy",
+  "Gritty",
+  "Groovy",
+  "Hyper",
+  "Icy",
+  "Inky",
+  "Jazzy",
+  "Jolly",
+  "Jumpy",
+  "Laser",
+  "Legendary",
+  "Loud",
+  "Lucky",
+  "Lunar",
+  "Madcap",
+  "Magic",
+  "Majestic",
+  "Meteor",
+  "Mighty",
+  "Minty",
+  "Mystic",
+  "Neon",
+  "Nimble",
+  "Nova",
+  "Nuclear",
+  "Omega",
+  "Orbital",
+  "Peppy",
+  "Phantom",
+  "Pixel",
+  "Plasma",
+  "Polished",
+  "Primal",
+  "Quantum",
+  "Quick",
+  "Radiant",
+  "Rampaging",
+  "Razor",
+  "Rebel",
+  "Retro",
+  "Rogue",
+  "Rowdy",
+  "Savage",
+  "Shadow",
+  "Shiny",
+  "Silly",
+  "Sketchy",
+  "Skybound",
+  "Slick",
+  "Snappy",
+  "Solar",
+  "Sonic",
+  "Sparky",
+  "Speedy",
+  "Spiky",
+  "Starry",
+  "Stealthy",
+  "Stormy",
+  "Supreme",
+  "Swift",
+  "Thunder",
+  "Turbo",
+  "Twilight",
+  "Ultra",
+  "Vibrant",
+  "Warped",
+  "Wicked",
+  "Wild",
+  "Wizard",
+  "Zappy",
+  "Zesty"
+];
+var NOUNS = [
+  "Aardvark",
+  "Asteroid",
+  "Badger",
+  "Bandit",
+  "Banshee",
+  "Beacon",
+  "Beetle",
+  "Blaster",
+  "Blob",
+  "Boomer",
+  "Bot",
+  "Brawler",
+  "Buccaneer",
+  "Buffalo",
+  "Cannon",
+  "Captain",
+  "Caribou",
+  "Charger",
+  "Cheetah",
+  "Chimera",
+  "Cobra",
+  "Comet",
+  "Cosmonaut",
+  "Cougar",
+  "Coyote",
+  "Cyborg",
+  "Dagger",
+  "Defender",
+  "Dino",
+  "Dragon",
+  "Drifter",
+  "Drone",
+  "Duck",
+  "Eagle",
+  "Eel",
+  "Falcon",
+  "Ferret",
+  "Fireball",
+  "Fox",
+  "Fury",
+  "Gazelle",
+  "Ghost",
+  "Gizmo",
+  "Gladiator",
+  "Goblin",
+  "Griffin",
+  "Hammer",
+  "Hawk",
+  "Hero",
+  "Hydra",
+  "Iguana",
+  "Jaguar",
+  "Jester",
+  "Jetpack",
+  "Jinx",
+  "Kangaroo",
+  "Katana",
+  "Kraken",
+  "Lancer",
+  "Laser",
+  "Legend",
+  "Lemur",
+  "Leopard",
+  "Lion",
+  "Luchador",
+  "Lynx",
+  "Maverick",
+  "Meteor",
+  "Monkey",
+  "Monsoon",
+  "Moose",
+  "Ninja",
+  "Nova",
+  "Octopus",
+  "Oracle",
+  "Otter",
+  "Panther",
+  "Phoenix",
+  "Pirate",
+  "Pixel",
+  "Puma",
+  "Quasar",
+  "Racer",
+  "Raptor",
+  "Raven",
+  "Reactor",
+  "Rocket",
+  "Ronin",
+  "Saber",
+  "Scorpion",
+  "Shark",
+  "Spartan",
+  "Sphinx",
+  "Sprinter",
+  "Stallion",
+  "Tiger",
+  "Titan",
+  "Viking",
+  "Viper",
+  "Wizard"
+];
+function generatePlayerName() {
+  const adjective = ADJECTIVES[Math.floor(Math.random() * ADJECTIVES.length)];
+  const noun = NOUNS[Math.floor(Math.random() * NOUNS.length)];
+  const number = Math.floor(Math.random() * 99) + 1;
+  const base = (adjective + noun).slice(0, MAX_BASE_LENGTH);
+  return `${base}${number}`;
+}
+
 // src/PlayerIdentity.ts
 var DEFAULT_KEY_PREFIX = "keeperboard_";
 var PlayerIdentity = class {
@@ -236,6 +450,7 @@ var PlayerIdentity = class {
     this.keyPrefix = config.keyPrefix ?? DEFAULT_KEY_PREFIX;
     this.guidKey = `${this.keyPrefix}player_guid`;
     this.nameKey = `${this.keyPrefix}player_name`;
+    this.nameAutoKey = `${this.keyPrefix}player_name_auto`;
   }
   /**
    * Get the stored player GUID, or null if none exists.
@@ -284,6 +499,31 @@ var PlayerIdentity = class {
       return;
     }
     localStorage.setItem(this.nameKey, name);
+    localStorage.removeItem(this.nameAutoKey);
+  }
+  /**
+   * Get the stored player name, creating an auto-generated one if it doesn't exist.
+   * Uses AdjectiveNounNumber pattern (e.g., ArcaneBlob99).
+   */
+  getOrCreatePlayerName() {
+    let name = this.getPlayerName();
+    if (!name) {
+      name = generatePlayerName();
+      if (typeof window !== "undefined" && window.localStorage) {
+        localStorage.setItem(this.nameKey, name);
+        localStorage.setItem(this.nameAutoKey, "true");
+      }
+    }
+    return name;
+  }
+  /**
+   * Check if the current player name was auto-generated (vs explicitly set by user).
+   */
+  isAutoGeneratedName() {
+    if (typeof window === "undefined" || !window.localStorage) {
+      return false;
+    }
+    return localStorage.getItem(this.nameAutoKey) === "true";
   }
   /**
    * Clear all stored player identity data.
@@ -294,6 +534,7 @@ var PlayerIdentity = class {
     }
     localStorage.removeItem(this.guidKey);
     localStorage.removeItem(this.nameKey);
+    localStorage.removeItem(this.nameAutoKey);
   }
   /**
    * Check if player identity is stored.
@@ -322,6 +563,7 @@ var Cache = class {
   constructor(ttlMs) {
     this.fetchedAt = 0;
     this.inflight = null;
+    this.pendingRefresh = null;
     this.ttlMs = ttlMs;
   }
   /**
@@ -348,17 +590,30 @@ var Cache = class {
   }
   /**
    * Trigger a background refresh without awaiting the result.
-   * Returns immediately. If a fetch is already in flight, does nothing.
+   * Returns immediately. If a fetch is already in flight, schedules
+   * the refresh to run after the current one completes.
    */
   refreshInBackground(fetchFn) {
-    if (this.inflight) return;
+    if (this.inflight) {
+      this.pendingRefresh = fetchFn;
+      return;
+    }
+    this.startBackgroundFetch(fetchFn);
+  }
+  startBackgroundFetch(fetchFn) {
     this.inflight = fetchFn().then((result) => {
       this.data = result;
       this.fetchedAt = Date.now();
       this.inflight = null;
+      if (this.pendingRefresh) {
+        const pending = this.pendingRefresh;
+        this.pendingRefresh = null;
+        this.startBackgroundFetch(pending);
+      }
       return result;
     }).catch((err) => {
       this.inflight = null;
+      this.pendingRefresh = null;
       throw err;
     });
     this.inflight.catch(() => {
@@ -441,7 +696,8 @@ function validateName(input, options) {
   if (opts.uppercase) {
     name = name.toUpperCase();
   }
-  name = name.replace(opts.allowedPattern, "");
+  const pattern = options?.allowedPattern ?? (opts.uppercase ? /[^A-Z0-9_]/g : /[^A-Za-z0-9_]/g);
+  name = name.replace(pattern, "");
   name = name.substring(0, opts.maxLength);
   if (name.length < opts.minLength) {
     return null;
@@ -452,6 +708,8 @@ function validateName(input, options) {
 // src/KeeperBoardSession.ts
 var KeeperBoardSession = class {
   constructor(config) {
+    this.cachedLimit = 0;
+    // Track the limit used for cached data
     this.isSubmitting = false;
     this.client = new KeeperBoardClient({
       apiKey: config.apiKey,
@@ -460,7 +718,6 @@ var KeeperBoardSession = class {
     });
     this.identity = new PlayerIdentity(config.identity);
     this.leaderboard = config.leaderboard;
-    this.defaultPlayerName = config.defaultPlayerName ?? "ANON";
     this.cache = config.cache ? new Cache(config.cache.ttlMs) : null;
     this.retryQueue = config.retry ? new RetryQueue(
       `keeperboard_retry_${config.leaderboard}`,
@@ -474,14 +731,18 @@ var KeeperBoardSession = class {
   getPlayerGuid() {
     return this.identity.getOrCreatePlayerGuid();
   }
-  /** Get the stored player name, falling back to defaultPlayerName. */
+  /** Get the stored player name, auto-generating one if none exists. */
   getPlayerName() {
-    return this.identity.getPlayerName() ?? this.defaultPlayerName;
+    return this.identity.getOrCreatePlayerName();
   }
   /** Store a player name locally. Does NOT update the server — call updatePlayerName() for that. */
   setPlayerName(name) {
     this.identity.setPlayerName(name);
   }
+  /** Check if the player has explicitly set a name (vs auto-generated). */
+  hasExplicitPlayerName() {
+    return this.identity.getPlayerName() !== null && !this.identity.isAutoGeneratedName();
+  }
   /** Validate a name using configurable rules. Returns sanitized string or null. */
   validateName(input, options) {
     return validateName(input, options);
@@ -511,6 +772,7 @@ var KeeperBoardSession = class {
       this.retryQueue?.clear();
       if (this.cache) {
         this.cache.invalidate();
+        this.cachedLimit = 0;
         this.cache.refreshInBackground(() => this.fetchSnapshot());
       }
       return {
@@ -532,12 +794,18 @@ var KeeperBoardSession = class {
    * 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.
+   * Uses cache if enabled and fresh. If a larger limit is requested than
+   * what's cached, the cache is invalidated and fresh data is fetched.
    */
   async getSnapshot(options) {
     const limit = options?.limit ?? 10;
     if (this.cache) {
-      return this.cache.getOrFetch(() => this.fetchSnapshot(limit));
+      if (limit > this.cachedLimit) {
+        this.cache.invalidate();
+      }
+      const result = await this.cache.getOrFetch(() => this.fetchSnapshot(limit));
+      this.cachedLimit = limit;
+      return result;
     }
     return this.fetchSnapshot(limit);
   }
@@ -552,7 +820,10 @@ var KeeperBoardSession = class {
         newName
       });
       this.identity.setPlayerName(newName);
-      this.cache?.invalidate();
+      if (this.cache) {
+        this.cache.invalidate();
+        this.cachedLimit = 0;
+      }
       return true;
     } catch {
       return false;
@@ -620,5 +891,6 @@ export {
   KeeperBoardSession,
   PlayerIdentity,
   RetryQueue,
+  generatePlayerName,
   validateName
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keeperboard",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "TypeScript client SDK for KeeperBoard leaderboard-as-a-service",
   "main": "dist/index.js",
   "module": "dist/index.mjs",