@playcademy/sdk 0.0.1-beta.27 → 0.0.1-beta.29

package/dist/core/client.d.ts

@@ -92,6 +92,26 @@ export declare class PlaycademyClient {
             apply?: boolean;
         }) => Promise<import("../types").GameTokenResponse>;
         exit: () => Promise<void>;
+        onInit: (handler: (context: import("../types").GameContextPayload) => void) => void;
+        onTokenRefresh: (handler: (data: {
+            token: string;
+            exp: number;
+        }) => void) => void;
+        onPause: (handler: () => void) => void;
+        onResume: (handler: () => void) => void;
+        onForceExit: (handler: () => void) => void;
+        onOverlay: (handler: (isVisible: boolean) => void) => void;
+        ready: () => void;
+        sendTelemetry: (data: {
+            fps: number;
+            mem: number;
+        }) => void;
+        removeListener: (eventType: import("..").MessageEvents, handler: ((context: import("../types").GameContextPayload) => void) | ((data: {
+            token: string;
+            exp: number;
+        }) => void) | (() => void) | ((isVisible: boolean) => void)) => void;
+        removeAllListeners: () => void;
+        getListenerCounts: () => Record<string, number>;
     };
     /** Game management methods (fetch, list, saveState, loadState, sessions) */
     games: {
@@ -101,6 +121,17 @@ export declare class PlaycademyClient {
         loadState: () => Promise<import("@playcademy/data/types").GameStateData>;
         startSession: (gameId?: string) => Promise<import("../types").StartSessionResponse>;
         endSession: (sessionId: string, gameId?: string) => Promise<void>;
+        token: {
+            create: (gameId: string, options?: {
+                apply?: boolean;
+            }) => Promise<import("../types").GameTokenResponse>;
+        };
+        leaderboard: {
+            get: (gameId: string, options?: {
+                limit?: number;
+                offset?: number;
+            }) => Promise<import("@playcademy/data/types").LeaderboardEntry[]>;
+        };
     };
     /** User methods (me, inventory management) */
     users: {
@@ -113,6 +144,7 @@ export declare class PlaycademyClient {
             image: string | null;
             role: "admin" | "player" | "developer";
             developerStatus: "none" | "pending" | "approved";
+            characterCreated: boolean;
             createdAt: Date;
             updatedAt: Date;
         }>;
@@ -123,12 +155,21 @@ export declare class PlaycademyClient {
             quantity: (identifier: string) => Promise<number>;
             has: (identifier: string, minQuantity?: number) => Promise<boolean>;
         };
+        scores: {
+            get: (userIdOrOptions?: string | {
+                limit?: number;
+                gameId?: string;
+            }, options?: {
+                limit?: number;
+                gameId?: string;
+            }) => Promise<import("./namespaces/users").UserScore[]>;
+        };
     };
     /** Developer tools (auth, games, keys management) */
     dev: {
         auth: {
             applyForDeveloper: () => Promise<void>;
-            getDeveloperStatus: () => Promise<import("@playcademy/data/types").DeveloperStatusValue>;
+            getStatus: () => Promise<import("@playcademy/data/types").DeveloperStatusValue>;
         };
         games: {
             upsert: (slug: string, metadata: import("@playcademy/data/types").UpsertGameMetadataInput, file: File | Blob) => Promise<import("@playcademy/data/types").Game>;
@@ -136,21 +177,21 @@ export declare class PlaycademyClient {
             delete: (gameId: string) => Promise<void>;
         };
         keys: {
-            createKey: (label?: string) => Promise<{
+            create: (label?: string) => Promise<{
                 id: string;
                 createdAt: Date;
                 userId: string;
                 label: string | null;
                 keyHash: string;
             }>;
-            listKeys: () => Promise<{
+            list: () => Promise<{
                 id: string;
                 createdAt: Date;
                 userId: string;
                 label: string | null;
                 keyHash: string;
             }[]>;
-            revokeKey: (keyId: string) => Promise<void>;
+            revoke: (keyId: string) => Promise<void>;
         };
         items: {
             create: (gameId: string, slug: string, itemData: Omit<import("@playcademy/data/types").InsertItemInput, "slug" | "gameId">) => Promise<import("@playcademy/data/types").Item>;
@@ -171,7 +212,13 @@ export declare class PlaycademyClient {
     };
     /** Map methods (elements) */
     maps: {
+        get: (identifier: string) => Promise<import("@playcademy/data/types").MapData>;
         elements: (mapId: string) => Promise<import("@playcademy/data/types").MapElementWithGame[]>;
+        objects: {
+            list: (mapId: string) => Promise<import("@playcademy/data/types").MapObjectWithItem[]>;
+            create: (mapId: string, objectData: import("@playcademy/data/types").CreateMapObjectData) => Promise<import("@playcademy/data/types").MapObjectWithItem>;
+            delete: (mapId: string, objectId: string) => Promise<void>;
+        };
     };
     /** Admin methods (games, items, currencies, shop listings) */
     admin: {
@@ -183,45 +230,49 @@ export declare class PlaycademyClient {
             create: (props: import("@playcademy/data/types").InsertItemInput) => Promise<{
                 id: string;
                 createdAt: Date;
-                displayName: string;
-                description: string | null;
                 slug: string;
+                displayName: string;
                 metadata: unknown;
                 gameId: string | null;
-                type: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
+                description: string | null;
+                type: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "accessory" | "other";
+                isPlaceable: boolean;
                 imageUrl: string | null;
             }>;
             get: (itemId: string) => Promise<{
                 id: string;
                 createdAt: Date;
-                displayName: string;
-                description: string | null;
                 slug: string;
+                displayName: string;
                 metadata: unknown;
                 gameId: string | null;
-                type: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
+                description: string | null;
+                type: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "accessory" | "other";
+                isPlaceable: boolean;
                 imageUrl: string | null;
             }>;
             list: () => Promise<{
                 id: string;
                 createdAt: Date;
-                displayName: string;
-                description: string | null;
                 slug: string;
+                displayName: string;
                 metadata: unknown;
                 gameId: string | null;
-                type: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
+                description: string | null;
+                type: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "accessory" | "other";
+                isPlaceable: boolean;
                 imageUrl: string | null;
             }[]>;
             update: (itemId: string, props: import("@playcademy/data/types").UpdateItemInput) => Promise<{
                 id: string;
                 createdAt: Date;
-                displayName: string;
-                description: string | null;
                 slug: string;
+                displayName: string;
                 metadata: unknown;
                 gameId: string | null;
-                type: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
+                description: string | null;
+                type: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "accessory" | "other";
+                isPlaceable: boolean;
                 imageUrl: string | null;
             }>;
             delete: (itemId: string) => Promise<void>;
@@ -346,6 +397,43 @@ export declare class PlaycademyClient {
         add: (amount: number) => Promise<number>;
         spend: (amount: number) => Promise<number>;
     };
+    /** Platform-wide leaderboard methods (fetch, getUserRank) */
+    leaderboard: {
+        fetch: (options?: import("@playcademy/data/types").LeaderboardOptions) => Promise<import("@playcademy/data/types").GameLeaderboardEntry[]>;
+        getUserRank: (gameId: string, userId: string) => Promise<import("@playcademy/data/types").UserRankResponse>;
+    };
+    /** Platform-wide scores methods (submit, getUserScores) */
+    scores: {
+        submit: (gameId: string, score: number, metadata?: Record<string, unknown>) => Promise<import("./namespaces/scores").ScoreSubmission>;
+        getByUser: (gameId: string, userId: string, options?: {
+            limit?: number;
+        }) => Promise<import("@playcademy/data/types").UserScore[]>;
+    };
+    /** Character methods (get, create, update, components) */
+    character: {
+        get: (userId?: string) => Promise<import("@playcademy/data/types").PlayerCharacter | null>;
+        create: (characterData: import("./namespaces/character").CreateCharacterData) => Promise<import("@playcademy/data/types").PlayerCharacter>;
+        update: (updates: import("./namespaces/character").UpdateCharacterData) => Promise<import("@playcademy/data/types").PlayerCharacter>;
+        components: {
+            list: (options?: import("./namespaces/character").CharacterComponentsOptions & {
+                skipCache?: boolean;
+            }) => Promise<import("@playcademy/data/types").CharacterComponentWithSpriteUrl[]>;
+            clearCache: () => void;
+            getCacheKeys: () => string[];
+        };
+    };
+    /** Sprites methods (templates) */
+    sprites: {
+        templates: {
+            get: (slug: string) => Promise<import("@playcademy/data/types").SpriteTemplateData>;
+        };
+    };
+    /** Realtime methods (token) */
+    realtime: {
+        token: {
+            get: () => Promise<import("./namespaces/realtime").RealtimeTokenResponse>;
+        };
+    };
     /** Auto-initializes a PlaycademyClient with context from the environment */
     static init: typeof init;
     /** Authenticates a user with email and password */

package/dist/core/namespaces/admin.d.ts

@@ -62,12 +62,13 @@ export declare function createAdminNamespace(client: PlaycademyClient): {
         create: (props: InsertItemInput) => Promise<{
             id: string;
             createdAt: Date;
-            displayName: string;
-            description: string | null;
             slug: string;
+            displayName: string;
             metadata: unknown;
             gameId: string | null;
-            type: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
+            description: string | null;
+            type: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "accessory" | "other";
+            isPlaceable: boolean;
             imageUrl: string | null;
         }>;
         /**
@@ -85,12 +86,13 @@ export declare function createAdminNamespace(client: PlaycademyClient): {
         get: (itemId: string) => Promise<{
             id: string;
             createdAt: Date;
-            displayName: string;
-            description: string | null;
             slug: string;
+            displayName: string;
             metadata: unknown;
             gameId: string | null;
-            type: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
+            description: string | null;
+            type: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "accessory" | "other";
+            isPlaceable: boolean;
             imageUrl: string | null;
         }>;
         /**
@@ -107,12 +109,13 @@ export declare function createAdminNamespace(client: PlaycademyClient): {
         list: () => Promise<{
             id: string;
             createdAt: Date;
-            displayName: string;
-            description: string | null;
             slug: string;
+            displayName: string;
             metadata: unknown;
             gameId: string | null;
-            type: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
+            description: string | null;
+            type: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "accessory" | "other";
+            isPlaceable: boolean;
             imageUrl: string | null;
         }[]>;
         /**
@@ -132,12 +135,13 @@ export declare function createAdminNamespace(client: PlaycademyClient): {
         update: (itemId: string, props: UpdateItemInput) => Promise<{
             id: string;
             createdAt: Date;
-            displayName: string;
-            description: string | null;
             slug: string;
+            displayName: string;
             metadata: unknown;
             gameId: string | null;
-            type: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "other";
+            description: string | null;
+            type: "currency" | "badge" | "trophy" | "collectible" | "consumable" | "unlock" | "upgrade" | "accessory" | "other";
+            isPlaceable: boolean;
             imageUrl: string | null;
         }>;
         /**

package/dist/core/namespaces/character.d.ts

@@ -0,0 +1,146 @@
+import type { CharacterComponentWithSpriteUrl, PlayerCharacter } from '@playcademy/data/types';
+import type { PlaycademyClient } from '../../types';
+export interface CharacterComponentsOptions {
+    /**
+     * Optional level filter for components
+     * When provided, only components available at this level or below are returned
+     */
+    level?: number;
+    /**
+     * Whether to bypass the cache and force a fresh API request
+     * Default: false (use cache when available)
+     */
+    skipCache?: boolean;
+}
+export interface CreateCharacterData {
+    bodyComponentId: string;
+    eyesComponentId: string;
+    hairstyleComponentId: string;
+    outfitComponentId: string;
+    accessoryComponentId?: string | null;
+}
+export interface UpdateCharacterData {
+    bodyComponentId?: string;
+    eyesComponentId?: string;
+    hairstyleComponentId?: string;
+    outfitComponentId?: string;
+    accessoryComponentId?: string | null;
+}
+/**
+ * Creates the character namespace for the PlaycademyClient.
+ * Provides methods for managing player character configuration and components.
+ *
+ * @param client - The PlaycademyClient instance
+ * @returns Character namespace with get, create, update, and components methods
+ */
+export declare function createCharacterNamespace(client: PlaycademyClient): {
+    /**
+     * Gets a player character configuration.
+     *
+     * @param userId - Optional user ID. If omitted, gets the current user's character
+     * @returns Promise resolving to player character data or null if no character exists
+     *
+     * @example
+     * ```typescript
+     * // Get current user's character
+     * const myCharacter = await client.character.get()
+     *
+     * // Get a specific user's character
+     * const otherCharacter = await client.character.get('user-123')
+     *
+     * if (myCharacter) {
+     *   console.log('My character body:', myCharacter.bodyComponentId)
+     * }
+     * ```
+     */
+    get: (userId?: string) => Promise<PlayerCharacter | null>;
+    /**
+     * Creates a new player character.
+     *
+     * @param characterData - The character configuration data
+     * @returns Promise resolving to the created player character
+     *
+     * @example
+     * ```typescript
+     * const character = await client.character.create({
+     *   bodyComponentId: 'body-1',
+     *   eyesComponentId: 'eyes-2',
+     *   hairstyleComponentId: 'hair-3',
+     *   outfitComponentId: 'outfit-4',
+     *   accessoryComponentId: 'accessory-5'
+     * })
+     * console.log('Character created:', character.id)
+     * ```
+     */
+    create: (characterData: CreateCharacterData) => Promise<PlayerCharacter>;
+    /**
+     * Updates an existing player character.
+     *
+     * @param updates - Partial character data to update
+     * @returns Promise resolving to the updated player character
+     *
+     * @example
+     * ```typescript
+     * const updatedCharacter = await client.character.update({
+     *   hairstyleComponentId: 'new-hair-style',
+     *   outfitComponentId: 'new-outfit'
+     * })
+     * console.log('Character updated:', updatedCharacter.id)
+     * ```
+     */
+    update: (updates: UpdateCharacterData) => Promise<PlayerCharacter>;
+    /**
+     * Character components sub-namespace
+     */
+    components: {
+        /**
+         * Lists available character components with optional level filtering.
+         * Results are cached in-memory by level to reduce API calls.
+         *
+         * @param options - Optional filtering options
+         * @param options.level - Filter components by required level
+         * @param options.skipCache - Bypass the cache and force fresh data (default: false)
+         * @returns Promise resolving to array of character components with sprite URLs
+         *
+         * @example
+         * ```typescript
+         * // Get all components (cached if available)
+         * const allComponents = await client.character.components.list()
+         *
+         * // Get components for level 5+ (cached if available)
+         * const levelComponents = await client.character.components.list({ level: 5 })
+         *
+         * // Force fresh data from API
+         * const freshComponents = await client.character.components.list({ skipCache: true })
+         * ```
+         */
+        list: (options?: CharacterComponentsOptions & {
+            skipCache?: boolean;
+        }) => Promise<CharacterComponentWithSpriteUrl[]>;
+        /**
+         * Clears the component cache.
+         * Useful when you know the component data has changed and want to force fresh data.
+         *
+         * @example
+         * ```typescript
+         * // Clear all cached component data
+         * client.character.components.clearCache()
+         * ```
+         */
+        clearCache: () => void;
+        /**
+         * Returns a list of all the component cache keys currently stored.
+         * Primarily useful for debugging and cache inspection.
+         *
+         * @returns Array of cache keys (e.g., ['all', '1', '5'])
+         *
+         * @example
+         * ```typescript
+         * // List all cache keys
+         * const cacheKeys = client.character.components.getCacheKeys()
+         * console.log('Cached levels:', cacheKeys)
+         * ```
+         */
+        getCacheKeys: () => string[];
+    };
+};

package/dist/core/namespaces/dev.d.ts

@@ -31,13 +31,13 @@ export declare function createDevNamespace(client: PlaycademyClient): {
          *
          * @example
          * ```typescript
-         * const status = await client.dev.auth.getDeveloperStatus()
+         * const status = await client.dev.auth.getStatus()
          * if (status === 'approved') {
          *   console.log('Developer access granted')
          * }
          * ```
          */
-        getDeveloperStatus: () => Promise<DeveloperStatusValue>;
+        getStatus: () => Promise<DeveloperStatusValue>;
     };
     /**
      * Game management methods for developers.
@@ -104,11 +104,11 @@ export declare function createDevNamespace(client: PlaycademyClient): {
          *
          * @example
          * ```typescript
-         * const key = await client.dev.keys.createKey('Production Key')
+         * const key = await client.dev.keys.create('Production Key')
          * console.log('API Key:', key.apiKey)
          * ```
          */
-        createKey: (label?: string) => Promise<{
+        create: (label?: string) => Promise<{
             id: string;
             createdAt: Date;
             userId: string;
@@ -122,11 +122,11 @@ export declare function createDevNamespace(client: PlaycademyClient): {
          *
          * @example
          * ```typescript
-         * const keys = await client.dev.keys.listKeys()
+         * const keys = await client.dev.keys.list()
          * keys.forEach(key => console.log(`${key.label}: ${key.id}`))
          * ```
          */
-        listKeys: () => Promise<{
+        list: () => Promise<{
             id: string;
             createdAt: Date;
             userId: string;
@@ -141,11 +141,11 @@ export declare function createDevNamespace(client: PlaycademyClient): {
          *
          * @example
          * ```typescript
-         * await client.dev.keys.revokeKey('key-456')
+         * await client.dev.keys.revoke('key-456')
          * console.log('API key revoked')
          * ```
          */
-        revokeKey: (keyId: string) => Promise<void>;
+        revoke: (keyId: string) => Promise<void>;
     };
     /**
      * Item management methods for developers.

package/dist/core/namespaces/games.d.ts

@@ -1,5 +1,5 @@
-import type { Game, GameStateData, GameWithManifest } from '@playcademy/data/types';
-import type { PlaycademyClient, StartSessionResponse } from '../../types';
+import type { Game, GameStateData, GameWithManifest, LeaderboardEntry } from '@playcademy/data/types';
+import type { GameTokenResponse, PlaycademyClient, StartSessionResponse } from '../../types';
 /**
  * Creates the games namespace for the PlaycademyClient.
  * Provides methods for managing games, game state, and game sessions.
@@ -93,4 +93,57 @@ export declare function createGamesNamespace(client: PlaycademyClient): {
      * ```
      */
     endSession: (sessionId: string, gameId?: string) => Promise<void>;
+    /**
+     * Token management sub-namespace
+     */
+    token: {
+        /**
+         * Creates a game token for the specified game.
+         * This method replaces the old runtime.getGameToken() method.
+         *
+         * @param gameId - The ID of the game to create a token for
+         * @param options - Optional configuration
+         * @param options.apply - Whether to automatically apply the token to this client
+         * @returns Promise resolving to game token response
+         *
+         * @example
+         * ```typescript
+         * // Create token without applying it
+         * const tokenResponse = await client.games.token.create('game-123')
+         *
+         * // Create token and apply it to current client
+         * const tokenResponse = await client.games.token.create('game-123', { apply: true })
+         * ```
+         */
+        create: (gameId: string, options?: {
+            apply?: boolean;
+        }) => Promise<GameTokenResponse>;
+    };
+    /**
+     * Leaderboard sub-namespace
+     */
+    leaderboard: {
+        /**
+         * Gets the leaderboard for a specific game.
+         *
+         * @param gameId - The ID of the game to get leaderboard for
+         * @param options - Optional query parameters
+         * @param options.limit - Maximum number of entries to return
+         * @param options.offset - Number of entries to skip
+         * @returns Promise resolving to array of leaderboard entries
+         *
+         * @example
+         * ```typescript
+         * // Get top 10 scores
+         * const leaderboard = await client.games.leaderboard.get('game-123', { limit: 10 })
+         *
+         * // Get next 10 scores
+         * const moreScores = await client.games.leaderboard.get('game-123', { limit: 10, offset: 10 })
+         * ```
+         */
+        get: (gameId: string, options?: {
+            limit?: number;
+            offset?: number;
+        }) => Promise<LeaderboardEntry[]>;
+    };
 };

package/dist/core/namespaces/index.d.ts

@@ -9,3 +9,8 @@ export { createShopNamespace } from './shop';
 export { createTelemetryNamespace } from './telemetry';
 export { createLevelsNamespace } from './levels';
 export { createCreditsNamespace } from './credits';
+export { createLeaderboardNamespace } from './leaderboard';
+export { createScoresNamespace } from './scores';
+export { createCharacterNamespace } from './character';
+export { createSpritesNamespace } from './sprites';
+export { createRealtimeNamespace } from './realtime';

package/dist/core/namespaces/leaderboard.d.ts

@@ -0,0 +1,48 @@
+import type { GameLeaderboardEntry, LeaderboardOptions, UserRankResponse } from '@playcademy/data/types';
+import type { PlaycademyClient } from '../../types';
+/**
+ * Creates the leaderboard namespace for the PlaycademyClient.
+ * Provides methods for accessing game-specific leaderboards.
+ *
+ * @param client - The PlaycademyClient instance
+ * @returns Leaderboard namespace with fetch methods
+ */
+export declare function createLeaderboardNamespace(client: PlaycademyClient): {
+    /**
+     * Fetches the leaderboard for a specific game.
+     * Note: gameId is required as cross-game score comparisons are not meaningful.
+     *
+     * @param options - Query options for the leaderboard (gameId is required)
+     * @returns Promise resolving to array of leaderboard entries
+     *
+     * @example
+     * ```typescript
+     * // Get top 10 players for a specific game
+     * const gameTop10 = await client.leaderboard.fetch({
+     *   gameId: 'game-123',
+     *   limit: 10
+     * })
+     *
+     * // Get weekly leaderboard for a specific game
+     * const weeklyGameLeaderboard = await client.leaderboard.fetch({
+     *   timeframe: 'weekly',
+     *   gameId: 'game-123'
+     * })
+     * ```
+     */
+    fetch: (options?: LeaderboardOptions) => Promise<GameLeaderboardEntry[]>;
+    /**
+     * Gets the rank of a specific user within a game's leaderboard.
+     *
+     * @param gameId - The game ID to get the user's rank for
+     * @param userId - The user ID to get the rank for
+     * @returns Promise resolving to user rank information
+     *
+     * @example
+     * ```typescript
+     * const userRank = await client.leaderboard.getUserRank('game-123', 'user-456')
+     * console.log(`User is rank ${userRank.rank} with score ${userRank.score}`)
+     * ```
+     */
+    getUserRank: (gameId: string, userId: string) => Promise<UserRankResponse>;
+};