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

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

@@ -1,4 +1,4 @@
-import type { MapElementWithGame } from '@playcademy/data/types';
+import type { CreateMapObjectData, MapData, MapElementWithGame, MapObjectWithItem } from '@playcademy/data/types';
 import type { PlaycademyClient } from '../../types';
 /**
  * Creates the maps namespace for the PlaycademyClient.
@@ -8,6 +8,19 @@ import type { PlaycademyClient } from '../../types';
  * @returns Maps namespace with element retrieval methods
  */
 export declare function createMapsNamespace(client: PlaycademyClient): {
+    /**
+     * Gets details for a specific map by its string identifier.
+     *
+     * @param identifier - The string identifier of the map
+     * @returns Promise resolving to map data
+     *
+     * @example
+     * ```typescript
+     * const map = await client.maps.get('world-1-level-1')
+     * console.log('Map name:', map.name)
+     * ```
+     */
+    get: (identifier: string) => Promise<MapData>;
     /**
      * Retrieves all elements for a specific map.
      *
@@ -23,4 +36,58 @@ export declare function createMapsNamespace(client: PlaycademyClient): {
      * ```
      */
     elements: (mapId: string) => Promise<MapElementWithGame[]>;
+    /**
+     * Map objects sub-namespace for managing placed objects on maps
+     */
+    objects: {
+        /**
+         * Lists all placed objects for a specific map.
+         *
+         * @param mapId - The ID of the map to get objects for
+         * @returns Promise resolving to array of map objects
+         *
+         * @example
+         * ```typescript
+         * const objects = await client.maps.objects.list('map-123')
+         * objects.forEach(obj => {
+         *   console.log(`Object at (${obj.worldX}, ${obj.worldY})`)
+         * })
+         * ```
+         */
+        list: (mapId: string) => Promise<MapObjectWithItem[]>;
+        /**
+         * Creates a new placed object on a map.
+         *
+         * @param mapId - The ID of the map to place the object on
+         * @param objectData - The object placement data
+         * @returns Promise resolving to the created map object
+         *
+         * @example
+         * ```typescript
+         * const newObject = await client.maps.objects.create('map-123', {
+         *   worldX: 100,
+         *   worldY: 200,
+         *   width: 32,
+         *   height: 32,
+         *   metadata: { type: 'treasure_chest' }
+         * })
+         * console.log('Object created:', newObject.id)
+         * ```
+         */
+        create: (mapId: string, objectData: CreateMapObjectData) => Promise<MapObjectWithItem>;
+        /**
+         * Deletes a placed object from a map.
+         *
+         * @param mapId - The ID of the map containing the object
+         * @param objectId - The ID of the object to delete
+         * @returns Promise that resolves when object is deleted
+         *
+         * @example
+         * ```typescript
+         * await client.maps.objects.delete('map-123', 'object-456')
+         * console.log('Object deleted')
+         * ```
+         */
+        delete: (mapId: string, objectId: string) => Promise<void>;
+    };
 };

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

@@ -0,0 +1,40 @@
+import type { PlaycademyClient } from '../../types';
+/**
+ * Response type for the realtime token API
+ */
+export interface RealtimeTokenResponse {
+    token: string;
+}
+/**
+ * Creates the realtime namespace for the PlaycademyClient.
+ * Provides methods for realtime connectivity and features.
+ *
+ * @param client - The PlaycademyClient instance
+ * @returns Realtime namespace with token-related methods
+ */
+export declare function createRealtimeNamespace(client: PlaycademyClient): {
+    /**
+     * Token sub-namespace for realtime token management
+     */
+    token: {
+        /**
+         * Gets a realtime JWT token for establishing realtime connections.
+         * This token is typically used for WebSocket connections or MQTT clients.
+         *
+         * @returns Promise resolving to token response
+         *
+         * @example
+         * ```typescript
+         * // Get a realtime token
+         * const response = await client.realtime.token.get()
+         * console.log('Realtime token:', response.token)
+         *
+         * // Use with a realtime client
+         * const realtimeClient = new RealtimeClient({
+         *   token: response.token
+         * })
+         * ```
+         */
+        get: () => Promise<RealtimeTokenResponse>;
+    };
+};

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

@@ -1,10 +1,18 @@
-import type { GameTokenResponse, PlaycademyClient } from '../../types';
+import { MessageEvents } from '../../messaging';
+import type { GameContextPayload, GameTokenResponse, PlaycademyClient } from '../../types';
+/**
+ * Type for runtime event handlers - union of all possible handler signatures
+ */
+type RuntimeEventHandler = ((context: GameContextPayload) => void) | ((data: {
+    token: string;
+    exp: number;
+}) => void) | (() => void) | ((isVisible: boolean) => void);
 /**
  * Creates the runtime namespace for the PlaycademyClient.
  * Provides methods for managing game runtime operations and lifecycle.
  *
  * @param client - The PlaycademyClient instance
- * @returns Runtime namespace with game token and exit methods
+ * @returns Runtime namespace with comprehensive game lifecycle management methods
  */
 export declare function createRuntimeNamespace(client: PlaycademyClient): {
     /**
@@ -41,4 +49,174 @@ export declare function createRuntimeNamespace(client: PlaycademyClient): {
      * ```
      */
     exit: () => Promise<void>;
+    /**
+     * Listens for game initialization events from the parent.
+     * Called when the parent sends initial configuration and auth context.
+     *
+     * @param handler - Function to call when initialization occurs
+     *
+     * @example
+     * ```typescript
+     * client.runtime.onInit((context) => {
+     *   console.log(`Game ${context.gameId} initialized`)
+     *   console.log(`API base URL: ${context.baseUrl}`)
+     * })
+     * ```
+     */
+    onInit: (handler: (context: GameContextPayload) => void) => void;
+    /**
+     * Listens for token refresh events from the parent.
+     * Called when the parent updates the authentication token.
+     *
+     * @param handler - Function to call when token is refreshed
+     *
+     * @example
+     * ```typescript
+     * client.runtime.onTokenRefresh(({ token, exp }) => {
+     *   console.log(`Token refreshed, expires at: ${new Date(exp)}`)
+     *   // Token is automatically applied to the client
+     * })
+     * ```
+     */
+    onTokenRefresh: (handler: (data: {
+        token: string;
+        exp: number;
+    }) => void) => void;
+    /**
+     * Listens for pause events from the parent.
+     * Called when the game should pause execution (e.g., user switches tabs).
+     *
+     * @param handler - Function to call when game should pause
+     *
+     * @example
+     * ```typescript
+     * client.runtime.onPause(() => {
+     *   game.pause()
+     *   audioManager.pauseAll()
+     * })
+     * ```
+     */
+    onPause: (handler: () => void) => void;
+    /**
+     * Listens for resume events from the parent.
+     * Called when the game should resume execution after being paused.
+     *
+     * @param handler - Function to call when game should resume
+     *
+     * @example
+     * ```typescript
+     * client.runtime.onResume(() => {
+     *   game.resume()
+     *   audioManager.resumeAll()
+     * })
+     * ```
+     */
+    onResume: (handler: () => void) => void;
+    /**
+     * Listens for force exit events from the parent.
+     * Called when the game must terminate immediately (emergency exit).
+     *
+     * @param handler - Function to call when game must force exit
+     *
+     * @example
+     * ```typescript
+     * client.runtime.onForceExit(() => {
+     *   game.emergencyCleanup()
+     *   // Game should exit immediately after cleanup
+     * })
+     * ```
+     */
+    onForceExit: (handler: () => void) => void;
+    /**
+     * Listens for overlay visibility events from the parent.
+     * Called when UI overlays are shown/hidden over the game.
+     *
+     * @param handler - Function to call when overlay state changes
+     *
+     * @example
+     * ```typescript
+     * client.runtime.onOverlay((isVisible) => {
+     *   if (isVisible) {
+     *     game.showOverlayMode()
+     *   } else {
+     *     game.hideOverlayMode()
+     *   }
+     * })
+     * ```
+     */
+    onOverlay: (handler: (isVisible: boolean) => void) => void;
+    /**
+     * Signals that the game has finished loading and is ready to receive messages.
+     * Should be called once after game initialization is complete.
+     *
+     * @example
+     * ```typescript
+     * // After game has loaded
+     * await client.runtime.ready()
+     * ```
+     */
+    ready: () => void;
+    /**
+     * Sends performance telemetry data to the parent.
+     * Used for monitoring game performance and analytics.
+     *
+     * @param data - Performance metrics data
+     * @param data.fps - Current frames per second
+     * @param data.mem - Current memory usage in MB
+     *
+     * @example
+     * ```typescript
+     * // Send current performance metrics
+     * client.runtime.sendTelemetry({
+     *   fps: game.getCurrentFPS(),
+     *   mem: performance.memory ? performance.memory.usedJSHeapSize / 1024 / 1024 : 0
+     * })
+     * ```
+     */
+    sendTelemetry: (data: {
+        fps: number;
+        mem: number;
+    }) => void;
+    /**
+     * Removes a specific event listener.
+     * Use this to stop listening for specific events.
+     *
+     * @param eventType - The message event type to stop listening for
+     * @param handler - The exact handler function that was registered
+     *
+     * @example
+     * ```typescript
+     * const pauseHandler = () => game.pause()
+     * client.runtime.onPause(pauseHandler)
+     *
+     * // Later, remove the specific handler
+     * client.runtime.removeListener(MessageEvents.PAUSE, pauseHandler)
+     * ```
+     */
+    removeListener: (eventType: MessageEvents, handler: RuntimeEventHandler) => void;
+    /**
+     * Removes all runtime event listeners.
+     * Use this for cleanup when the game is shutting down.
+     *
+     * @example
+     * ```typescript
+     * // Clean up all runtime listeners before exit
+     * client.runtime.removeAllListeners()
+     * await client.runtime.exit()
+     * ```
+     */
+    removeAllListeners: () => void;
+    /**
+     * Gets the count of active listeners for debugging purposes.
+     *
+     * @returns Object with listener counts by event type
+     *
+     * @example
+     * ```typescript
+     * const counts = client.runtime.getListenerCounts()
+     * console.log(`Active listeners:`, counts)
+     * ```
+     */
+    getListenerCounts: () => Record<string, number>;
 };
+export {};

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

@@ -0,0 +1,55 @@
+import type { UserScore } from '@playcademy/data/types';
+import type { PlaycademyClient } from '../../types';
+export interface ScoreSubmission {
+    id: string;
+    score: number;
+    achievedAt: Date;
+}
+/**
+ * Creates the scores namespace for the PlaycademyClient.
+ * Provides methods for managing scores across the platform.
+ *
+ * @param client - The PlaycademyClient instance
+ * @returns Scores namespace with submit and retrieval methods
+ */
+export declare function createScoresNamespace(client: PlaycademyClient): {
+    /**
+     * Submits a score for a specific game.
+     * Note: This still requires a gameId as scores must be associated with a game.
+     *
+     * @param gameId - The game ID to submit the score for
+     * @param score - The score value to submit
+     * @param metadata - Optional metadata about the score
+     * @returns Promise resolving to the created score record
+     *
+     * @example
+     * ```typescript
+     * const scoreRecord = await client.scores.submit('game-123', 1250, {
+     *   level: 5,
+     *   difficulty: 'hard'
+     * })
+     * console.log('Score submitted:', scoreRecord.id)
+     * ```
+     */
+    submit: (gameId: string, score: number, metadata?: Record<string, unknown>) => Promise<ScoreSubmission>;
+    /**
+     * Gets all scores for a specific user within a specific game.
+     *
+     * @param gameId - The game ID to get scores for
+     * @param userId - The user ID to get scores for
+     * @param options - Optional filtering options
+     * @param options.limit - Maximum number of scores to return
+     * @returns Promise resolving to array of user scores for the game
+     *
+     * @example
+     * ```typescript
+     * const gameScores = await client.scores.getByUser('game-123', 'user-456', {
+     *   limit: 10
+     * })
+     * console.log(`User has ${gameScores.length} scores in this game`)
+     * ```
+     */
+    getByUser: (gameId: string, userId: string, options?: {
+        limit?: number;
+    }) => Promise<UserScore[]>;
+};

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

@@ -0,0 +1,32 @@
+import type { SpriteTemplateData } from '@playcademy/data/types';
+import type { PlaycademyClient } from '../../types';
+/**
+ * Creates the sprites namespace for the PlaycademyClient.
+ * Provides methods for managing sprite templates and related data.
+ *
+ * @param client - The PlaycademyClient instance
+ * @returns Sprites namespace with template methods
+ */
+export declare function createSpritesNamespace(client: PlaycademyClient): {
+    /**
+     * Sprite templates sub-namespace
+     */
+    templates: {
+        /**
+         * Gets a sprite template by its slug.
+         * This fetches the template metadata from the database and then loads
+         * the actual template JSON data from the CDN/S3.
+         *
+         * @param slug - The template slug to fetch
+         * @returns Promise resolving to the sprite template data
+         *
+         * @example
+         * ```typescript
+         * const template = await client.sprites.templates.get('hero-idle')
+         * console.log('Template frames:', template.frames?.length || 0)
+         * console.log('Template animations:', Object.keys(template.animations || {}))
+         * ```
+         */
+        get: (slug: string) => Promise<SpriteTemplateData>;
+    };
+};

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

@@ -1,5 +1,14 @@
 import type { InventoryItemWithItem } from '@playcademy/data/types';
 import type { InventoryMutationResponse, PlaycademyClient } from '../../types';
+export interface UserScore {
+    id: string;
+    score: number;
+    achievedAt: Date;
+    metadata?: Record<string, unknown>;
+    gameId: string;
+    gameTitle: string;
+    gameSlug: string;
+}
 /**
  * Creates the users namespace for the PlaycademyClient.
  * Provides methods for managing user data and inventory operations.
@@ -29,6 +38,7 @@ export declare function createUsersNamespace(client: PlaycademyClient): {
         image: string | null;
         role: "admin" | "player" | "developer";
         developerStatus: "none" | "pending" | "approved";
+        characterCreated: boolean;
         createdAt: Date;
         updatedAt: Date;
     }>;
@@ -128,4 +138,46 @@ export declare function createUsersNamespace(client: PlaycademyClient): {
          */
         has: (identifier: string, minQuantity?: number) => Promise<boolean>;
     };
+    /**
+     * User scores management methods.
+     */
+    scores: {
+        /**
+         * Gets scores for a user across all games.
+         *
+         * @param userIdOrOptions - User ID or options object. If omitted, gets scores for the current user.
+         * @param options - Optional filtering options
+         * @param options.limit - Maximum number of scores to return
+         * @param options.gameId - Filter scores by specific game
+         * @returns Promise resolving to array of user scores
+         *
+         * @example
+         * ```typescript
+         * // Get all scores for current user
+         * const myScores = await client.users.scores.get()
+         *
+         * // Get scores for current user with options
+         * const myGameScores = await client.users.scores.get({
+         *   gameId: 'game-456',
+         *   limit: 20
+         * })
+         *
+         * // Get scores for a specific user
+         * const userScores = await client.users.scores.get('user-123')
+         *
+         * // Get scores for a specific user with options
+         * const userGameScores = await client.users.scores.get('user-123', {
+         *   gameId: 'game-789',
+         *   limit: 10
+         * })
+         * ```
+         */
+        get: (userIdOrOptions?: string | {
+            limit?: number;
+            gameId?: string;
+        }, options?: {
+            limit?: number;
+            gameId?: string;
+        }) => Promise<UserScore[]>;
+    };
 };