keeperboard 2.0.1 → 2.0.3

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;
@@ -141,8 +139,6 @@ interface NameValidationOptions {
     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;
 }
@@ -303,7 +299,6 @@ declare class KeeperBoardSession {
     private readonly client;
     private readonly identity;
     private readonly leaderboard;
-    private readonly defaultPlayerName;
     private readonly cache;
     private readonly retryQueue;
     private cachedLimit;
@@ -311,10 +306,12 @@ declare class KeeperBoardSession {
     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;
     /**
@@ -369,6 +366,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.
@@ -391,6 +389,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.
      */
@@ -415,18 +422,33 @@ declare class PlayerIdentity {
  * 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`
+ * 2. Strips characters not matching `allowedPattern`
+ * 3. Truncates to `maxLength`
+ * 4. Returns `null` if result is shorter than `minLength`
  *
  * @example
- * validateName('  Ace Pilot! ')  // 'ACE_PILOT' → wait, no spaces allowed → 'ACEPILOT'
- * validateName('ab')             // 'AB'
+ * validateName('  Ace Pilot! ')  // 'AcePilot'
+ * validateName('ab')             // 'ab'
  * validateName('x')              // null (too short)
  */
 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.
  *
@@ -488,4 +510,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;
@@ -141,8 +139,6 @@ interface NameValidationOptions {
     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;
 }
@@ -303,7 +299,6 @@ declare class KeeperBoardSession {
     private readonly client;
     private readonly identity;
     private readonly leaderboard;
-    private readonly defaultPlayerName;
     private readonly cache;
     private readonly retryQueue;
     private cachedLimit;
@@ -311,10 +306,12 @@ declare class KeeperBoardSession {
     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;
     /**
@@ -369,6 +366,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.
@@ -391,6 +389,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.
      */
@@ -415,18 +422,33 @@ declare class PlayerIdentity {
  * 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`
+ * 2. Strips characters not matching `allowedPattern`
+ * 3. Truncates to `maxLength`
+ * 4. Returns `null` if result is shorter than `minLength`
  *
  * @example
- * validateName('  Ace Pilot! ')  // 'ACE_PILOT' → wait, no spaces allowed → 'ACEPILOT'
- * validateName('ab')             // 'AB'
+ * validateName('  Ace Pilot! ')  // 'AcePilot'
+ * validateName('ab')             // 'ab'
  * validateName('x')              // null (too short)
  */
 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.
  *
@@ -488,4 +510,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.
@@ -478,16 +720,12 @@ var RetryQueue = class {
 var DEFAULTS = {
   minLength: 2,
   maxLength: 12,
-  uppercase: true,
-  allowedPattern: /[^A-Z0-9_]/g
+  allowedPattern: /[^A-Za-z0-9_]/g
 };
 function validateName(input, options) {
   const opts = { ...DEFAULTS, ...options };
   let name = input.trim();
-  if (opts.uppercase) {
-    name = name.toUpperCase();
-  }
-  const pattern = options?.allowedPattern ?? (opts.uppercase ? /[^A-Z0-9_]/g : /[^A-Za-z0-9_]/g);
+  const pattern = options?.allowedPattern ?? /[^A-Za-z0-9_]/g;
   name = name.replace(pattern, "");
   name = name.substring(0, opts.maxLength);
   if (name.length < opts.minLength) {
@@ -509,7 +747,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}`,
@@ -523,14 +760,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);
@@ -680,5 +921,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.
@@ -446,16 +687,12 @@ var RetryQueue = class {
 var DEFAULTS = {
   minLength: 2,
   maxLength: 12,
-  uppercase: true,
-  allowedPattern: /[^A-Z0-9_]/g
+  allowedPattern: /[^A-Za-z0-9_]/g
 };
 function validateName(input, options) {
   const opts = { ...DEFAULTS, ...options };
   let name = input.trim();
-  if (opts.uppercase) {
-    name = name.toUpperCase();
-  }
-  const pattern = options?.allowedPattern ?? (opts.uppercase ? /[^A-Z0-9_]/g : /[^A-Za-z0-9_]/g);
+  const pattern = options?.allowedPattern ?? /[^A-Za-z0-9_]/g;
   name = name.replace(pattern, "");
   name = name.substring(0, opts.maxLength);
   if (name.length < opts.minLength) {
@@ -477,7 +714,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}`,
@@ -491,14 +727,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);
@@ -647,5 +887,6 @@ export {
   KeeperBoardSession,
   PlayerIdentity,
   RetryQueue,
+  generatePlayerName,
   validateName
 };

package/package.json

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