@playcademy/sdk 0.0.5 → 0.0.7

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

@@ -1,90 +0,0 @@
-import type { LevelConfig, UserLevel } from '@playcademy/data/types';
-import type { PlaycademyClient } from '../../types';
-import type { CooldownCacheConfig } from '../cache/types';
-/**
- * Creates the levels namespace for the PlaycademyClient.
- * Provides methods for retrieving user levels and progress.
- *
- * @param client - The PlaycademyClient instance
- * @returns Levels namespace with level query methods
- */
-export declare function createLevelsNamespace(client: PlaycademyClient): {
-    /**
-     * Retrieves the current user's level information.
-     *
-     * @returns Promise resolving to user level data
-     *
-     * @example
-     * ```typescript
-     * const userLevel = await client.levels.get()
-     * console.log('Current level:', userLevel.currentLevel)
-     * console.log('Current XP:', userLevel.currentXp)
-     * console.log('Total XP earned:', userLevel.totalXP)
-     * ```
-     */
-    get: () => Promise<UserLevel>;
-    /**
-     * Retrieves the current user's level progress information.
-     * Uses a 5 second cooldown by default to prevent rapid API calls.
-     *
-     * @param options - Optional cache configuration
-     * @param options.cooldown - Custom cooldown in milliseconds (0 to disable)
-     * @param options.force - Force refresh, bypassing cooldown
-     * @returns Promise resolving to level progress data
-     *
-     * @example
-     * ```typescript
-     * // Use default 5 second cooldown
-     * const progress = await client.levels.progress()
-     *
-     * // Custom 10 second cooldown for background sync
-     * const bgProgress = await client.levels.progress({ cooldown: 10_000 })
-     *
-     * // Force refresh on level up
-     * const freshProgress = await client.levels.progress({ force: true })
-     *
-     * // Disable cooldown for real-time display
-     * const realtimeProgress = await client.levels.progress({ cooldown: 0 })
-     * ```
-     */
-    progress: (options?: CooldownCacheConfig) => Promise<{
-        level: number;
-        currentXp: number;
-        xpToNextLevel: number;
-        totalXP: number;
-    }>;
-    /**
-     * Configuration methods for level system.
-     */
-    config: {
-        /**
-         * Retrieves all level configurations (full XP curve).
-         *
-         * @returns Promise resolving to array of level configurations
-         *
-         * @example
-         * ```typescript
-         * const configs = await client.levels.config.list()
-         * configs.forEach(config => {
-         *   console.log(`Level ${config.level}: ${config.xpRequired} XP, ${config.creditsReward} credits`)
-         * })
-         * ```
-         */
-        list: () => Promise<LevelConfig[]>;
-        /**
-         * Retrieves configuration for a specific level.
-         *
-         * @param level - The level number to get configuration for
-         * @returns Promise resolving to level configuration or null if not found
-         *
-         * @example
-         * ```typescript
-         * const config = await client.levels.config.get(10)
-         * if (config) {
-         *   console.log(`Level 10 requires ${config.xpRequired} XP`)
-         * }
-         * ```
-         */
-        get: (level: number) => Promise<LevelConfig | null>;
-    };
-};

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

@@ -1,93 +0,0 @@
-import type { CreateMapObjectData, MapData, MapElementWithGame, MapObjectWithItem } from '@playcademy/data/types';
-import type { PlaycademyClient } from '../../types';
-/**
- * Creates the maps namespace for the PlaycademyClient.
- * Provides methods for retrieving map data and elements.
- *
- * @param client - The PlaycademyClient instance
- * @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.
-     *
-     * @param mapId - The ID of the map to get elements for
-     * @returns Promise resolving to array of map elements with game data
-     *
-     * @example
-     * ```typescript
-     * const elements = await client.maps.elements('map-123')
-     * elements.forEach(element => {
-     *   console.log(`Element: ${element.elementSlug} - Game: ${element.game?.displayName || 'None'}`)
-     * })
-     * ```
-     */
-    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.client.d.ts

@@ -1,129 +0,0 @@
-import type { RealtimeChannel } from '@playcademy/realtime/server/types';
-/**
- * Client-side implementation of a realtime communication channel.
- * Manages a WebSocket connection to a specific game-scoped realtime channel.
- *
- * **Key Features**:
- * - Automatic connection management with reconnection on token refresh
- * - Type-safe message handling with JSON serialization/deserialization
- * - Proper cleanup and resource management
- * - Integration with the Playcademy messaging system for token updates
- *
- * **Connection Lifecycle**:
- * 1. `connect()` - Establishes WebSocket connection with authentication
- * 2. Message exchange via `send()` and `onMessage()` callbacks
- * 3. Automatic reconnection on token refresh events
- * 4. `close()` - Clean shutdown with proper resource cleanup
- *
- * @example
- * ```typescript
- * const client = new RealtimeChannelClient(
- *   'game-123',
- *   'chat',
- *   () => getToken(),
- *   'ws://localhost:3000'
- * )
- *
- * await client.connect()
- *
- * client.onMessage((data) => {
- *   console.log('Received:', data)
- * })
- *
- * client.send({ type: 'message', text: 'Hello!' })
- *
- * // Clean up when done
- * client.close()
- * ```
- */
-export declare class RealtimeChannelClient implements RealtimeChannel {
-    private gameId;
-    private _channelName;
-    private getToken;
-    private baseUrl;
-    private ws?;
-    private listeners;
-    private isClosing;
-    private tokenRefreshUnsubscribe?;
-    constructor(gameId: string, _channelName: string, getToken: () => Promise<string>, baseUrl: string);
-    /**
-     * Establishes the WebSocket connection to the realtime server.
-     *
-     * **Connection Process**:
-     * 1. Obtains fresh authentication token
-     * 2. Constructs WebSocket URL with token and channel parameters
-     * 3. Creates WebSocket connection
-     * 4. Sets up event handlers for messages, errors, and disconnections
-     * 5. Registers for token refresh events
-     *
-     * **URL Format**: `ws://host/path?token=<jwt>&c=<channel>`
-     *
-     * @throws Error if token retrieval fails or WebSocket connection fails
-     */
-    connect(): Promise<RealtimeChannel>;
-    /**
-     * Sets up WebSocket event handlers for message processing and connection management.
-     *
-     * **Event Handling**:
-     * - `message`: Parses JSON and notifies all registered listeners
-     * - `close`: Handles both expected and unexpected disconnections
-     * - `error`: Logs WebSocket errors for debugging
-     */
-    private setupEventHandlers;
-    /**
-     * Sets up listener for token refresh events from the messaging system.
-     * When a token refresh occurs, the WebSocket connection is closed and reopened
-     * with the new token to maintain authentication.
-     */
-    private setupTokenRefreshListener;
-    /**
-     * Reconnects the WebSocket with a new authentication token.
-     *
-     * **Reconnection Process**:
-     * 1. Close existing connection with TOKEN_REFRESH code
-     * 2. Wait for close event to complete
-     * 3. Re-establish connection with new token
-     *
-     * @param token - The new authentication token (currently unused, relies on getToken())
-     */
-    private reconnectWithNewToken;
-    /**
-     * Sends a message to all members of this channel.
-     *
-     * **Message Format**: JSON-serialized payload
-     * **Delivery**: Best-effort, no acknowledgment or retry logic
-     *
-     * @param data - Any JSON-serializable data to send
-     */
-    send(data: unknown): void;
-    /**
-     * Registers a callback to be invoked when messages are received on this channel.
-     *
-     * **Message Processing**:
-     * - Messages are automatically JSON-parsed before delivery
-     * - Listener errors are caught and logged (won't affect other listeners)
-     * - Multiple listeners can be registered for the same channel
-     *
-     * @param callback - Function to call when messages are received
-     * @returns Unsubscribe function to remove this listener
-     */
-    onMessage(callback: (data: unknown) => void): () => void;
-    /**
-     * Closes the WebSocket connection and cleans up all resources.
-     *
-     * **Cleanup Process**:
-     * 1. Mark as intentionally closing (prevents reconnection attempts)
-     * 2. Remove token refresh listener
-     * 3. Close WebSocket with normal closure code
-     * 4. Clear all message listeners
-     */
-    close(): void;
-    /**
-     * Gets the name of this channel.
-     */
-    get channelName(): string;
-    /**
-     * Checks if the underlying WebSocket connection is currently open.
-     */
-    get isConnected(): boolean;
-}

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

@@ -1,90 +0,0 @@
-import type { RealtimeChannel } from '@playcademy/realtime/server/types';
-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 and channel API
- */
-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>;
-    };
-    /**
-     * Opens a realtime channel for game-scoped communication.
-     *
-     * **Channel Naming**:
-     * - Channels are automatically scoped to the current game
-     * - Channel names should be descriptive (e.g. "chat", "lobby", "map_forest")
-     * - The "default" channel is used if no name is specified
-     *
-     * **Connection Management**:
-     * - Each channel opens its own WebSocket connection
-     * - Connections automatically handle token refresh
-     * - Remember to call `channel.close()` when done to prevent resource leaks
-     *
-     * **Error Handling**:
-     * - Throws if no `gameId` is configured on the client
-     * - Throws if token retrieval fails
-     * - Throws if WebSocket connection fails
-     *
-     * @param channel - Channel name (defaults to "default")
-     * @param url - Optional WebSocket **base** URL (e.g. `ws://localhost:3000`).
-     *   If omitted, the client's `baseUrl` is used and automatically converted to
-     *   a WebSocket URL (`http` → `ws`, `https` → `wss`).
-     * @returns Promise resolving to a `RealtimeChannel` instance
-     *
-     * @example
-     * ```typescript
-     * // Open the default channel
-     * const channel = await client.realtime.open()
-     *
-     * // Listen for messages
-     * const unsubscribe = channel.onMessage((data) => {
-     *   console.log('Received:', data)
-     * })
-     *
-     * // Send a message
-     * channel.send({ type: 'chat', message: 'Hello world!' })
-     *
-     * // Clean up when done
-     * unsubscribe()
-     * channel.close()
-     *
-     * // Open a named channel
-     * const chatChannel = await client.realtime.open('chat')
-     *
-     * // Open a channel against a custom realtime endpoint
-     * const localChannel = await client.realtime.open('dev', 'ws://localhost:3000')
-     * ```
-     */
-    open(channel?: string, url?: string): Promise<RealtimeChannel>;
-};

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

@@ -1,222 +0,0 @@
-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 comprehensive game lifecycle management methods
- */
-export declare function createRuntimeNamespace(client: PlaycademyClient): {
-    /**
-     * Retrieves a game token for the specified game.
-     * Optionally applies the token to the current client instance.
-     *
-     * @param gameId - The ID of the game to get 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
-     * // Get token without applying it
-     * const tokenResponse = await client.runtime.getGameToken('game-123')
-     *
-     * // Get token and apply it to current client
-     * const tokenResponse = await client.runtime.getGameToken('game-123', { apply: true })
-     * ```
-     */
-    getGameToken: (gameId: string, options?: {
-        apply?: boolean;
-    }) => Promise<GameTokenResponse>;
-    /**
-     * Gracefully exits the game runtime.
-     * Automatically ends any active game session and emits an exit event.
-     *
-     * @returns Promise that resolves when exit is complete
-     *
-     * @example
-     * ```typescript
-     * // Clean up and exit the game
-     * await client.runtime.exit()
-     * ```
-     */
-    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

@@ -1,55 +0,0 @@
-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[]>;
-};